task

package
v0.1.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 5, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

Documentation

Overview

Package task 实现子轮 2.4 的"任务驱动 A 形态"： 

用户自然语言描述任务 → LLM/规则解析 skill → 推荐 Top 3 Agent → 用户选择。

与 internal/skill 协作：本模块只消费 SkillRecommender 接口，不直接读 skill 表。

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AgentMatch 

type AgentMatch struct {
	AgentID    uuid.UUID
	MatchCount int32
}

AgentMatch skill 模块返回给推荐器的最小信息。

本模块独立定义同名结构是为避免 internal/task 与 internal/skill 的潜在循环依赖， 调用方（main.go）需把 internal/skill 的实现适配到 SkillRecommender 接口。

type AgentSummary 

type AgentSummary struct {
	ID                string   `json:"id"`
	Slug              string   `json:"slug"`
	Name              string   `json:"name"`
	Description       string   `json:"description"`
	PricePerCallCents int32    `json:"price_per_call_cents"`
	TotalCalls        int32    `json:"total_calls"`
	AvgRating         *float32 `json:"avg_rating,omitempty"`
	CreatorName       string   `json:"creator_name"`
	Tags              []string `json:"tags"`
}

AgentSummary 推荐返回的 Agent 简要信息（不含 endpoint / 鉴权头）。

type ChooseRequest 

type ChooseRequest struct {
	AgentID uuid.UUID `json:"agent_id" validate:"required"`
}

ChooseRequest 用户选定推荐里某个 Agent 的请求体。

type ClaimRequest 

type ClaimRequest struct {
	AgentID uuid.UUID `json:"agent_id" validate:"required"`
}

ClaimRequest 创作者用自己的 Agent 接入任务广场任务。

type CompleteRequest 

type CompleteRequest struct {
	AgentID            uuid.UUID              `json:"agent_id" validate:"required"`
	RunID              uuid.UUID              `json:"run_id" validate:"required"`
	ResultSummary      string                 `json:"result_summary" validate:"required,min=1,max=2000"`
	ResultArtifact     map[string]interface{} `json:"result_artifact,omitempty"`
	DeliveryVisibility string                 `json:"delivery_visibility,omitempty" validate:"omitempty,oneof=private shared public_example"`
}

CompleteRequest 把一次成功 run 写回任务。

type DeliveryArtifact 

type DeliveryArtifact map[string]interface{}

DeliveryArtifact 是任务详情公开给任务相关方的结构化产物。

type DetailResponse 

type DetailResponse struct {
	ID                  string           `json:"id"`
	Query               string           `json:"query"`
	Visibility          string           `json:"visibility"`
	PublicSummary       *string          `json:"public_summary,omitempty"`
	PublishedAt         *string          `json:"published_at,omitempty"`
	ParsedSkills        []string         `json:"parsed_skills"`
	ParsedSkillRefs     []SkillRef       `json:"parsed_skill_refs"`
	MCPTools            []string         `json:"mcp_tools"`
	MCPToolRefs         []MCPToolRef     `json:"mcp_tool_refs"`
	Status              string           `json:"status"`
	ChosenAgentID       *string          `json:"chosen_agent_id,omitempty"`
	ChosenAt            *string          `json:"chosen_at,omitempty"`
	ClaimedAgentID      *string          `json:"claimed_agent_id,omitempty"`
	ClaimedByUserID     *string          `json:"claimed_by_user_id,omitempty"`
	ClaimedAt           *string          `json:"claimed_at,omitempty"`
	CompletionRunID     *string          `json:"completion_run_id,omitempty"`
	CompletedAt         *string          `json:"completed_at,omitempty"`
	CompletionSummary   *string          `json:"completion_summary,omitempty"`
	DeliveryStatus      string           `json:"delivery_status"`
	DeliveryVisibility  string           `json:"delivery_visibility"`
	DeliveryArtifact    DeliveryArtifact `json:"delivery_artifact,omitempty"`
	AcceptedAt          *string          `json:"accepted_at,omitempty"`
	RevisionRequestedAt *string          `json:"revision_requested_at,omitempty"`
	RevisionNote        *string          `json:"revision_note,omitempty"`
	CreatedAt           string           `json:"created_at"`
	Recommendations     []Recommendation `json:"recommendations"`
	NextAction          *TaskNextAction  `json:"next_action,omitempty"`
}

DetailResponse GET /tasks/:id 详情响应。

用于冷链接（直接打开 /tasks/<id> URL，sessionStorage 无缓存）时 让前端依然能渲染 3 张推荐卡。recommendations 按 recommended_agent_ids 顺序回填； 若某 agent 已下架则跳过该位置。

type Handler 

type Handler struct {
	// contains filtered or unexported fields
}

Handler 任务驱动 A 形态 HTTP 入口。

func NewHandler 

func NewHandler(svc *Service) *Handler

NewHandler 构造 Handler。

func (*Handler) Accept 

func (h *Handler) Accept(c echo.Context) error

Accept POST /tasks/:id/accept

func (*Handler) Choose 

func (h *Handler) Choose(c echo.Context) error

Choose POST /tasks/:id/choose

func (*Handler) Claim 

func (h *Handler) Claim(c echo.Context) error

Claim POST /tasks/:id/claim

func (*Handler) Complete 

func (h *Handler) Complete(c echo.Context) error

Complete POST /tasks/:id/complete

func (*Handler) GetByID 

func (h *Handler) GetByID(c echo.Context) error

GetByID GET /tasks/:id

func (*Handler) ListBoard 

func (h *Handler) ListBoard(c echo.Context) error

ListBoard GET /tasks/board?limit=20

func (*Handler) ListMine 

func (h *Handler) ListMine(c echo.Context) error

ListMine GET /tasks/me?limit=20

func (*Handler) ListTaskTemplates 

func (h *Handler) ListTaskTemplates(c echo.Context) error

ListTaskTemplates GET /task-templates

func (*Handler) Publish 

func (h *Handler) Publish(c echo.Context) error

Publish POST /tasks/:id/publish

func (*Handler) Recommend 

func (h *Handler) Recommend(c echo.Context) error

Recommend POST /tasks/recommend

func (*Handler) RegisterProtected 

func (h *Handler) RegisterProtected(api *echo.Group, jwtMiddleware echo.MiddlewareFunc)

RegisterProtected 注册需要 JWT 的端点。 

POST /tasks/recommend       自然语言 → 推荐 Top3 Agent
POST /tasks/:id/choose      用户选定推荐里某个 Agent
POST /tasks/:id/publish     显式把私有推荐草稿发布到任务广场
POST /tasks/:id/claim       创作者用自己的 Agent 接入任务广场任务
POST /tasks/:id/run         从任务直接启动一次 Agent 运行
POST /tasks/:id/complete    把成功 run 写回任务结果
POST /tasks/:id/accept      任务发布者验收结果
POST /tasks/:id/revision    任务发布者要求修订
GET  /tasks/board           任务广场公开列表
GET  /tasks/me              我的任务历史（最多 20 条）
GET  /tasks/:id             单个任务详情（含推荐卡回填）

func (*Handler) RequestRevision 

func (h *Handler) RequestRevision(c echo.Context) error

RequestRevision POST /tasks/:id/revision

func (*Handler) Run 

func (h *Handler) Run(c echo.Context) error

Run POST /tasks/:id/run

type HistoryItem 

type HistoryItem struct {
	ID                  string   `json:"id"`
	Query               string   `json:"query"`
	Visibility          string   `json:"visibility"`
	PublicSummary       *string  `json:"public_summary,omitempty"`
	PublishedAt         *string  `json:"published_at,omitempty"`
	ParsedSkills        []string `json:"parsed_skills"`
	MCPTools            []string `json:"mcp_tools"`
	RecommendedAgentIDs []string `json:"recommended_agent_ids"`
	Status              string   `json:"status"`
	ChosenAgentID       *string  `json:"chosen_agent_id,omitempty"`
	ChosenAt            *string  `json:"chosen_at,omitempty"`
	ClaimedAgentID      *string  `json:"claimed_agent_id,omitempty"`
	ClaimedByUserID     *string  `json:"claimed_by_user_id,omitempty"`
	ClaimedAt           *string  `json:"claimed_at,omitempty"`
	CompletionRunID     *string  `json:"completion_run_id,omitempty"`
	CompletedAt         *string  `json:"completed_at,omitempty"`
	CompletionSummary   *string  `json:"completion_summary,omitempty"`
	DeliveryStatus      string   `json:"delivery_status"`
	DeliveryVisibility  string   `json:"delivery_visibility"`
	AcceptedAt          *string  `json:"accepted_at,omitempty"`
	RevisionRequestedAt *string  `json:"revision_requested_at,omitempty"`
	RevisionNote        *string  `json:"revision_note,omitempty"`
	CreatedAt           string   `json:"created_at"`
}

HistoryItem "我的任务"列表项（GET /tasks/me）。

type MCPToolRef 

type MCPToolRef struct {
	Name        string `json:"name"`
	Description string `json:"description"`
}

MCPToolRef 是任务发布流对 OpenLinker MCP 工具的稳定引用。

type PublicTaskItem 

type PublicTaskItem struct {
	ID                    string       `json:"id"`
	Query                 string       `json:"query"` // public-safe summary, not the private original query
	PublicSummary         string       `json:"public_summary"`
	PublishedAt           *string      `json:"published_at,omitempty"`
	ParsedSkills          []string     `json:"parsed_skills"`
	ParsedSkillRefs       []SkillRef   `json:"parsed_skill_refs"`
	MCPTools              []string     `json:"mcp_tools"`
	MCPToolRefs           []MCPToolRef `json:"mcp_tool_refs"`
	RecommendedAgentCount int          `json:"recommended_agent_count"`
	Status                string       `json:"status"` // open / matched / in_progress / completed / needs_agent
	ClaimedAgentID        *string      `json:"claimed_agent_id,omitempty"`
	ClaimedAt             *string      `json:"claimed_at,omitempty"`
	CompletedAt           *string      `json:"completed_at,omitempty"`
	DeliveryStatus        string       `json:"delivery_status"`
	CreatedAt             string       `json:"created_at"`
}

PublicTaskItem 任务广场公开列表项。

不包含 user_id / email / display_name；创作者只看到需求、Skill 和匹配状态。

type PublishRequest 

type PublishRequest struct {
	PublicSummary string `json:"public_summary,omitempty" validate:"omitempty,min=4,max=240"`
}

PublishRequest 把私有推荐草稿显式发布到任务广场。

type RecommendRequest 

type RecommendRequest struct {
	Query      string   `json:"query" validate:"required,min=4,max=500"`
	TemplateID string   `json:"template_id,omitempty" validate:"omitempty,min=2,max=80"`
	SkillIDs   []string `json:"skill_ids,omitempty" validate:"omitempty,max=5,dive,min=1,max=80"`
	MCPTools   []string `json:"mcp_tools,omitempty" validate:"omitempty,max=5,dive,min=1,max=80"`
}

RecommendRequest 推荐请求体。Query 长度由 schema CHECK 与 validator 双重保障。

type RecommendResponse 

type RecommendResponse struct {
	TaskID          uuid.UUID        `json:"task_id"`
	Visibility      string           `json:"visibility"`
	PublicSummary   *string          `json:"public_summary,omitempty"`
	ParsedSkills    []string         `json:"parsed_skills"`
	ParsedSkillRefs []SkillRef       `json:"parsed_skill_refs"`
	MCPTools        []string         `json:"mcp_tools"`
	MCPToolRefs     []MCPToolRef     `json:"mcp_tool_refs"`
	Recommendations []Recommendation `json:"recommendations"`
	NextAction      *TaskNextAction  `json:"next_action,omitempty"`
}

RecommendResponse 推荐响应。

TaskID 用于后续 POST /tasks/:id/choose；空数组表示无匹配，前端可提示用户改写描述。

type Recommendation 

type Recommendation struct {
	Agent         AgentSummary `json:"agent"`
	MatchScore    float32      `json:"match_score"` // [0,1]
	Why           string       `json:"why"`         // 中文解释，如 "匹配 SQL 查询 + 数据分析"
	MatchedSkills []SkillRef   `json:"matched_skills"`
}

Recommendation 单条推荐：Agent + 匹配分 + 解释。

type RevisionRequest 

type RevisionRequest struct {
	Note string `json:"note" validate:"required,min=1,max=2000"`
}

RevisionRequest 请求接单方修订交付结果。

type RunTaskRequest 

type RunTaskRequest struct {
	AgentID uuid.UUID              `json:"agent_id" validate:"required"`
	Input   map[string]interface{} `json:"input,omitempty"`
}

RunTaskRequest 从任务详情直接启动一次 Agent 运行。

type RunTaskResponse 

type RunTaskResponse struct {
	TaskID string      `json:"task_id"`
	Status string      `json:"status"`
	Run    interface{} `json:"run"`
}

RunTaskResponse 返回任务级启动结果。run 字段保持 runtime.RunResponse 的 JSON 形状。

type RuntimeStarter 

type RuntimeStarter interface {
	StartRun(ctx context.Context, userID uuid.UUID, req *runtime.RunRequest, source string) (*runtime.RunResponse, error)
}

RuntimeStarter 是任务直接运行 Agent 时需要的最小 runtime 能力。

type Service 

type Service struct {
	// contains filtered or unexported fields
}

Service 任务驱动 A 形态业务逻辑。

allSkills 在 NewService 时预热，并按 TTL 刷新，避免运营更新长期滞后。

func NewService 

func NewService(pool *pgxpool.Pool, llmClient llm.Client, skillSvc SkillRecommender) *Service

NewService 构造 Service，并立即预热 skill catalog。

任何启动期失败（skillSvc.ListAll 出错）记 warn 但仍返回 Service —— 后续 Recommend 调用会重新尝试加载，避免启动顺序耦合。

func (*Service) AcceptDelivery 

func (s *Service) AcceptDelivery(ctx context.Context, taskID, userID uuid.UUID) (*WorkResponse, error)

AcceptDelivery marks a submitted task result as accepted. Only the task poster can accept a delivery.

func (*Service) Choose 

func (s *Service) Choose(ctx context.Context, taskID, userID, agentID uuid.UUID) error

Choose 用户在推荐里选定一个 Agent。校验：

  • task_id 必须属于该 user（否则 404，不暴露存在性）
  • agent_id 必须出现在 recommended_agent_ids 里（否则 400）

func (*Service) Claim 

func (s *Service) Claim(ctx context.Context, taskID, userID, agentID uuid.UUID) (*WorkResponse, error)

Claim 让创作者用自己的 Agent 接入公开任务。它只登记任务工作关系； 实际运行仍走 /runs，成功后再调用 Complete 写回结果。

func (*Service) Complete 

func (s *Service) Complete(ctx context.Context, taskID, userID uuid.UUID, req *CompleteRequest) (*WorkResponse, error)

Complete 把一次成功 run 绑定回任务。任务发布者选择推荐 Agent 后可完成； 任务广场接单方也可在自己的 Agent 跑完后完成。

func (*Service) GetByID 

func (s *Service) GetByID(ctx context.Context, taskID, userID uuid.UUID) (*DetailResponse, error)

GetByID 取单个任务 + 回填推荐卡。用于冷链接（sessionStorage 缓存丢失）。

权限：task 必须属于该 user，否则 404。 recommendations 按 recommended_agent_ids 顺序回填，跳过已下架/找不到的 agent。 parsed_skills 用于生成 Why 文案，保持与 Recommend 一致。

func (*Service) ListBoard 

func (s *Service) ListBoard(ctx context.Context, limit int32) ([]PublicTaskItem, error)

ListBoard 返回任务广场最近公开任务。列表不暴露发布者身份。

func (*Service) ListMine 

func (s *Service) ListMine(ctx context.Context, userID uuid.UUID, limit int32) ([]HistoryItem, error)

ListMine 用户最近 limit 条任务历史（默认上限 20）。

func (*Service) ListTaskTemplates 

func (s *Service) ListTaskTemplates(ctx context.Context) ([]TaskTemplateResponse, error)

func (*Service) Publish 

func (s *Service) Publish(ctx context.Context, taskID, userID uuid.UUID, req *PublishRequest) (*DetailResponse, error)

Publish 把私有推荐草稿显式发布到任务广场。公开列表只展示 public_summary。

func (*Service) Recommend 

func (s *Service) Recommend(ctx context.Context, userID uuid.UUID, req *RecommendRequest) (*RecommendResponse, error)

Recommend 主流程：解析 → 推荐 → 回填 → 持久化。

func (*Service) RequestRevision 

func (s *Service) RequestRevision(ctx context.Context, taskID, userID uuid.UUID, req *RevisionRequest) (*WorkResponse, error)

RequestRevision asks the worker to resubmit a completed task delivery.

func (*Service) RunTask 

func (s *Service) RunTask(ctx context.Context, taskID, userID uuid.UUID, req *RunTaskRequest) (*RunTaskResponse, error)

RunTask 从任务详情启动一次运行。它要求任务已经被发布者选择 Agent， 或已经由创作者接入；结果终态仍由 Complete 写回，便于 async run 统一处理。

func (*Service) SetRunStarter 

func (s *Service) SetRunStarter(runner RuntimeStarter)

SetRunStarter 注入 runtime.Service，使任务详情可以直接启动一次 Agent run。

type SkillRecommender 

type SkillRecommender interface {
	ListAll(ctx context.Context) ([]db.Skill, error)
	RecommendAgentsBySkills(ctx context.Context, skillIDs []string, limit int) ([]AgentMatch, error)
}

SkillRecommender skill 模块对外暴露给本模块的能力。由 internal/skill.Service 实现。 

ListAll                     — 启动时取全部 skill catalog（用于 LLM prompt + 规则匹配）
RecommendAgentsBySkills     — 给定 skill_id 列表，返回命中数量最多的 Agent

type SkillRef 

type SkillRef struct {
	ID          string `json:"id"`
	Category    string `json:"category"`
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
}

SkillRef 是任务发布流对 Skill catalog 的稳定引用。

type TaskNextAction 

type TaskNextAction struct {
	Type   string `json:"type"`
	Label  string `json:"label"`
	Hint   string `json:"hint"`
	Href   string `json:"href"`
	Reason string `json:"reason"`
}

TaskNextAction 是推荐/详情页给人类和外部 Agent 的结构化下一步。

type TaskTemplateResponse 

type TaskTemplateResponse struct {
	ID                    string       `json:"id"`
	Slug                  string       `json:"slug"`
	Title                 string       `json:"title"`
	Category              string       `json:"category"`
	Summary               string       `json:"summary"`
	RequiredSkillIDs      []string     `json:"required_skill_ids"`
	RequiredSkillRefs     []SkillRef   `json:"required_skill_refs"`
	RequiredMCPTools      []string     `json:"required_mcp_tools"`
	RequiredMCPToolRefs   []MCPToolRef `json:"required_mcp_tool_refs"`
	ExampleQuery          string       `json:"example_query"`
	ExpectedArtifactTypes []string     `json:"expected_artifact_types"`
	DefaultVisibility     string       `json:"default_visibility"`
}

TaskTemplateResponse is the public catalog item that lowers the first-run burden without exposing or publishing a user's private task input.

type WorkResponse 

type WorkResponse struct {
	TaskID              string  `json:"task_id"`
	Status              string  `json:"status"`
	Query               string  `json:"query"`
	AgentID             string  `json:"agent_id"`
	ClaimedAt           *string `json:"claimed_at,omitempty"`
	CompletionRunID     *string `json:"completion_run_id,omitempty"`
	CompletedAt         *string `json:"completed_at,omitempty"`
	CompletionSummary   *string `json:"completion_summary,omitempty"`
	DeliveryStatus      string  `json:"delivery_status"`
	DeliveryVisibility  string  `json:"delivery_visibility"`
	AcceptedAt          *string `json:"accepted_at,omitempty"`
	RevisionRequestedAt *string `json:"revision_requested_at,omitempty"`
	RevisionNote        *string `json:"revision_note,omitempty"`
}

WorkResponse 是 claim/complete 共享返回体。

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.