task

package
v0.1.59 Latest Latest
Warning

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

 Go to latest Published: Sep 14, 2026 License: Apache-2.0 Imports: 23 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 DetailResponse 

type DetailResponse struct {
	ID                string           `json:"id"`
	Query             string           `json:"query"`
	Visibility        string           `json:"visibility"`
	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"`
	CompletionRunID   *string          `json:"completion_run_id,omitempty"`
	CompletedAt       *string          `json:"completed_at,omitempty"`
	CompletionSummary *string          `json:"completion_summary,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) Choose 

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

Choose POST /tasks/:id/choose

func (*Handler) GetByID 

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

GetByID GET /tasks/:id

func (*Handler) ListMine 

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

ListMine GET /tasks/me?q=&status=&sort=created_desc&page=1&size=20

func (*Handler) ListTaskTemplates 

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

ListTaskTemplates GET /task-templates

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/run         从任务直接启动一次 Agent 运行
GET  /tasks/me              我的任务历史（最多 20 条）
GET  /tasks/:id             单个任务详情（含推荐卡回填）

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"`
	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"`
	CompletionRunID     *string  `json:"completion_run_id,omitempty"`
	CompletedAt         *string  `json:"completed_at,omitempty"`
	CompletionSummary   *string  `json:"completion_summary,omitempty"`
	CreatedAt           string   `json:"created_at"`
}

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

type HistoryListResponse added in v0.1.15 

type HistoryListResponse struct {
	Items        []HistoryItem `json:"items"`
	Total        int32         `json:"total"`
	Page         int32         `json:"page"`
	Size         int32         `json:"size"`
	Query        string        `json:"query,omitempty"`
	Sort         string        `json:"sort"`
	StatusFilter string        `json:"status_filter,omitempty"`
}

type MCPToolRef 

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

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

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"`
	AgentSlugs []string `json:"agent_slugs,omitempty" validate:"omitempty,max=5,dive,min=1,max=120"`
}

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

type RecommendResponse 

type RecommendResponse struct {
	TaskID          uuid.UUID        `json:"task_id"`
	Visibility      string           `json:"visibility"`
	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 RunTaskRequest 

type RunTaskRequest struct {
	AgentID        uuid.UUID              `json:"agent_id" validate:"required"`
	Input          map[string]interface{} `json:"input,omitempty"`
	IdempotencyKey string                 `json:"idempotency_key" validate:"required,min=1,max=255,printascii"`
}

RunTaskRequest 从私有任务详情直接启动一次 Agent 运行。调用方必须为 每次语义运行提供稳定幂等键，不能只用 task_id 推导。

type RunTaskResponse 

type RunTaskResponse struct {
	TaskID string               `json:"task_id"`
	Status string               `json:"status"`
	Run    *runtime.RunResponse `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) 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) 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) ListMine 

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

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

func (*Service) ListMinePage added in v0.1.15 

func (s *Service) ListMinePage(ctx context.Context, userID uuid.UUID, query, status, sort string, page, size int32) (*HistoryListResponse, error)

ListMinePage returns task history with server-side search, filters, sorting, and pagination.

func (*Service) ListTaskTemplates 

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

func (*Service) Recommend 

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

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

func (*Service) RunTask 

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

RunTask 从私有任务详情启动一次运行。任务必须属于调用者，且 Agent 必须先从推荐结果中选定；运行结果由 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"`
	ReasonCode string `json:"reason_code,omitempty"`
	Reason     string `json:"reason"`
}

TaskNextAction 是推荐/详情页给人类和外部 Agent 的结构化下一步。 无匹配供给时返回 connect_agent，并把私有任务意图编码到站内 /publish 链接。

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"`
	Translations          map[string]TaskTemplateTranslation `json:"translations"`
	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 TaskTemplateTranslation added in v0.1.56 

type TaskTemplateTranslation struct {
	Title        string `json:"title"`
	Summary      string `json:"summary"`
	ExampleQuery string `json:"example_query"`
}

TaskTemplateTranslation contains the user-facing fields that vary by locale. The top-level template fields remain the catalog's default copy so existing consumers can continue to read them without selecting a translation.

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.