skill

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: 22 Imported by: 0

Documentation

Overview

Package skill 实现 Skill 注册表（30 个内置 skill）+ Agent ↔ Skill 关联管理。 子轮 2.3 引入。任务驱动推荐（子轮 2.4）通过 Service.RecommendAgentsBySkills 调用。

Index

Constants

View Source 
const (
	BenchmarkStatusPending  = "pending"
	BenchmarkStatusVerified = "verified"
	BenchmarkStatusFailed   = "failed"
	BenchmarkStatusNotRun   = "not_run"
)

BenchmarkResultStatus = "pending" | "verified" | "failed"。 与 db.AgentSkillScore.Status 同集合，但增加 "not_run" 用于 UI 区分"从未跑过"。

View Source 
const MaxSkillsPerAgent = 5

MaxSkillsPerAgent 单个 Agent 最多可声明的 skill 数量（PRD：5 个上限）。

View Source 
const VerifiedThreshold = 75

VerifiedThreshold 平均分 >= 该值 → status=verified；否则 status=failed。

75 是 docs/25 §5 给出的默认阈值，可调；改阈值时同步更新 README / 详情页说明。

Variables

This section is empty.

Functions

This section is empty.

Types

type AgentMatch 

type AgentMatch struct {
	AgentID       uuid.UUID
	MatchCount    int32
	VerifiedCount int32
	TotalCalls    int32
}

AgentMatch 任务驱动推荐结果（供 2.4 task 模块直接使用）。

MatchCount 是输入 skill 中命中的数量，用于排序与"匹配度"展示； VerifiedCount 是命中 skill 中已 verified 的子集，用于"可信度"加权（模块 B）； TotalCalls 用作热度 tie-break。

type BenchmarkBatchDetail 

type BenchmarkBatchDetail struct {
	BatchID      string             `json:"batch_id"`
	AgentID      string             `json:"agent_id"`
	SkillID      string             `json:"skill_id"`
	Status       string             `json:"status"`
	AverageScore *int32             `json:"average_score,omitempty"`
	Items        []BenchmarkRunItem `json:"items"`
}

BenchmarkBatchDetail 批次详情。

type BenchmarkBatchSummary 

type BenchmarkBatchSummary struct {
	BatchID      string  `json:"batch_id"`
	SkillID      string  `json:"skill_id"`
	TotalCount   int32   `json:"total_count"`
	SuccessCount int32   `json:"success_count"`
	AverageScore *int32  `json:"average_score,omitempty"`
	StartedAt    string  `json:"started_at"`
	FinishedAt   *string `json:"finished_at,omitempty"`
}

BenchmarkBatchSummary 公开 GET /agents/:id/benchmarks 单批汇总（不带 case 明细）。

type BenchmarkHandler 

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

BenchmarkHandler HTTP 入口。Service 是 nil 时不挂路由（main.go 兜底）。

func NewBenchmarkHandler 

func NewBenchmarkHandler(svc benchmarkService) *BenchmarkHandler

NewBenchmarkHandler 构造。

func (*BenchmarkHandler) GetBatch 

func (h *BenchmarkHandler) GetBatch(c echo.Context) error

GetBatch GET /creator/agents/:id/benchmarks/:batchID。

func (*BenchmarkHandler) GetBatchPublic 

func (h *BenchmarkHandler) GetBatchPublic(c echo.Context) error

GetBatchPublic GET /agents/:id/benchmarks/:batchID

func (*BenchmarkHandler) GetRuntimeStatus 

func (h *BenchmarkHandler) GetRuntimeStatus(c echo.Context) error

GetRuntimeStatus GET /benchmark/status。

func (*BenchmarkHandler) ListBatchSummariesPublic 

func (h *BenchmarkHandler) ListBatchSummariesPublic(c echo.Context) error

ListBatchSummariesPublic GET /agents/:id/benchmarks

func (*BenchmarkHandler) ListBenchmarkResults 

func (h *BenchmarkHandler) ListBenchmarkResults(c echo.Context) error

ListBenchmarkResults GET /agents/:id/benchmark-results — docs/25 §5.3 别名。 行为与 ListAgentScoresBySlug 对齐，但用 id 查；公开可见性已在 service 层强制。

func (*BenchmarkHandler) ListMyScores 

func (h *BenchmarkHandler) ListMyScores(c echo.Context) error

ListMyScores GET /creator/agents/:id/skill-scores。

func (*BenchmarkHandler) ListScoresBySlug 

func (h *BenchmarkHandler) ListScoresBySlug(c echo.Context) error

ListScoresBySlug GET /agents/:slug/skill-scores。

func (*BenchmarkHandler) ListTopAgents 

func (h *BenchmarkHandler) ListTopAgents(c echo.Context) error

ListTopAgents GET /skills/:id/top-agents?limit=3。

func (*BenchmarkHandler) Register 

func (h *BenchmarkHandler) Register(api *echo.Group)

Register 公开端点（无需 JWT）。 

GET /skills/:id/top-agents                      某 skill 下 top-N verified Agent
GET /agents/:slug/skill-scores                  按 slug 列出 agent 的 skill 评分
GET /agents/:id/benchmarks                      Phase 2 缺口 3：公开 batch 概览
GET /agents/:id/benchmarks/:batchID             Phase 2 缺口 3：公开 batch 详情（脱敏）
GET /agents/:id/benchmark-results               docs/25 §5.3 别名 → 转发 skill-scores by id
GET /benchmark/status                           主动测评运行能力状态（不泄露密钥）

func (*BenchmarkHandler) RegisterProtected 

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

RegisterProtected 创作者侧端点（需 JWT）。 

POST /creator/agents/:id/benchmarks                     触发 benchmark
GET  /creator/agents/:id/skill-scores                   汇总评分
GET  /creator/agents/:id/benchmarks/:batchID            单次 batch 详情

func (*BenchmarkHandler) RunBenchmark 

func (h *BenchmarkHandler) RunBenchmark(c echo.Context) error

RunBenchmark POST /creator/agents/:id/benchmarks。

type BenchmarkRunItem 

type BenchmarkRunItem struct {
	ID             string  `json:"id"`
	TestCaseTitle  string  `json:"test_case_title"`
	Status         string  `json:"status"`
	Score          *int32  `json:"score,omitempty"`
	JudgeReasoning *string `json:"judge_reasoning,omitempty"`
	ErrorMessage   *string `json:"error_message,omitempty"`
	StartedAt      string  `json:"started_at"`
	FinishedAt     *string `json:"finished_at,omitempty"`
}

BenchmarkRunItem 详情页单条 case 结果（脱敏过 raw_output）。

type BenchmarkRuntimeStatus 

type BenchmarkRuntimeStatus struct {
	CanRun  bool     `json:"can_run"`
	Reasons []string `json:"reasons"`
	Message string   `json:"message"`
}

BenchmarkRuntimeStatus describes whether the platform can start active benchmark runs. It intentionally exposes only coarse readiness flags.

type BenchmarkService 

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

BenchmarkService 负责 Skill Benchmark 的触发、执行、聚合。

复用 skill.Service 持有的 pool / queries，不再单开连接。

func NewBenchmarkService 

func NewBenchmarkService(parent *Service, runner EndpointRunner, llmClient llm.Client) *BenchmarkService

NewBenchmarkService 构造。runner / llmClient 都可为 nil（service 会返回 503）。

func (*BenchmarkService) GetBatchDetail 

func (b *BenchmarkService) GetBatchDetail(ctx context.Context, agentID, creatorID, batchID uuid.UUID) (*BenchmarkBatchDetail, error)

GetBatchDetail 单次 batch 详情。

func (*BenchmarkService) GetBatchDetailPublic 

func (b *BenchmarkService) GetBatchDetailPublic(ctx context.Context, agentID, batchID uuid.UUID) (*BenchmarkBatchDetail, error)

GetBatchDetailPublic 公开 GET /agents/:id/benchmarks/:batchID： 仅校验 Agent 公开运行，并把 raw_output / judge_reasoning 脱敏（不返回）。

func (*BenchmarkService) ListAgentScores 

func (b *BenchmarkService) ListAgentScores(ctx context.Context, agentID uuid.UUID) ([]SkillScoreItem, error)

ListAgentScores 创作者中心 / 内部用：列出某 agent 全部 skill 评分。

func (*BenchmarkService) ListAgentScoresBySlug 

func (b *BenchmarkService) ListAgentScoresBySlug(ctx context.Context, slug string) ([]SkillScoreItem, error)

ListAgentScoresBySlug 公开详情页用：按 slug 查（限 approved Agent）。

func (*BenchmarkService) ListBatchSummariesPublic 

func (b *BenchmarkService) ListBatchSummariesPublic(ctx context.Context, agentID uuid.UUID, limit int) ([]BenchmarkBatchSummary, error)

ListBatchSummariesPublic 公开 GET /agents/:id/benchmarks： 仅校验 Agent 公开运行（visibility != private + lifecycle = active）；不再校验 owner。 单批返回汇总（success/total/avg），不含 raw_output / judge_reasoning。

func (*BenchmarkService) ListTopAgents 

func (b *BenchmarkService) ListTopAgents(ctx context.Context, skillID string, limit int) ([]TopAgentForSkill, error)

ListTopAgents /skills 列表页：某 skill 下 top-N verified Agent。

func (*BenchmarkService) RunBenchmark 

func (b *BenchmarkService) RunBenchmark(ctx context.Context, agentID, creatorID uuid.UUID, skillID string) (*RunBenchmarkResponse, error)

RunBenchmark 创作者触发某 skill 的 benchmark。

校验：

  1. Agent 归属 creatorID
  2. skill_id 已被 agent 声明（agent_skills）
  3. 该 skill 已 seed 测试用例
  4. EndpointRunner + LLM 已就绪

触发成功后异步启动 worker，立即返回 batch_id。

func (*BenchmarkService) RuntimeStatus 

func (b *BenchmarkService) RuntimeStatus() BenchmarkRuntimeStatus

type CreateSkillProposalRequest 

type CreateSkillProposalRequest struct {
	AgentID         *string `json:"agent_id,omitempty"`
	ProposedSkillID string  `json:"proposed_skill_id" validate:"required,min=3,max=120"`
	Category        string  `json:"category" validate:"required,min=2,max=80"`
	Name            string  `json:"name" validate:"required,min=1,max=120"`
	Description     string  `json:"description" validate:"required,min=4,max=1000"`
	Source          string  `json:"source,omitempty" validate:"omitempty,oneof=manual imported_text imported_json"`
}

CreateSkillProposalRequest 是用户提交缺失 Skill / 导入声明后的提案请求。

type EndpointRunner 

type EndpointRunner interface {
	DryRun(ctx context.Context, agent *db.Agent, input map[string]interface{}) (map[string]interface{}, string)
}

EndpointRunner 抽象 Agent endpoint 调用，由 runtime.Service 实现（通过 DryRun 方法满足）。 返回 (output, errMsg)。errMsg 非空视为失败，output 可能为 nil。

type Handler 

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

Handler Skill HTTP 入口。

func NewHandler 

func NewHandler(svc skillService, pool *pgxpool.Pool) *Handler

NewHandler 构造 Handler。

func (*Handler) CreateProposal 

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

CreateProposal POST /skills/proposals。

func (*Handler) ListAgentSkills added in v0.1.59 

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

ListAgentSkills reads declarations through the owner boundary, independently of whether the Agent is visible in the public marketplace.

func (*Handler) ListAll 

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

ListAll GET /skills?q=&category=&sort=&page=&size=。

func (*Handler) ListProposals 

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

ListProposals GET /creator/skill-proposals?q=&status=&sort=&page=&size=。

func (*Handler) Register 

func (h *Handler) Register(api *echo.Group)

Register 公开端点（无需 JWT）。 

GET /skills    列出全部内置 skill（/publish 表单与发现页用）

func (*Handler) RegisterProtected 

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

RegisterProtected 创作者侧端点（需 JWT）。 

GET /creator/agents/:id/skills      读取所有者已声明的 skill，包括私有 Agent
PATCH /creator/agents/:id/skills    覆盖某 Agent 的 skill 列表（最多 5 个）
POST /skills/proposals              提交缺失 Skill / 导入声明提案
GET /creator/skill-proposals        查看当前用户提案

func (*Handler) SetAgentSkills 

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

SetAgentSkills PATCH /creator/agents/:id/skills。

鉴权：JWT 解出当前 user → 拉 Agent → 比对 creator_id；不匹配返回 403。

type RunBenchmarkRequest 

type RunBenchmarkRequest struct {
	SkillID string `json:"skill_id" validate:"required"`
}

RunBenchmarkRequest 创作者触发某 skill 的 benchmark。

type RunBenchmarkResponse 

type RunBenchmarkResponse struct {
	BatchID string `json:"batch_id"`
	SkillID string `json:"skill_id"`
	Status  string `json:"status"` // "running"
}

RunBenchmarkResponse 触发后立即返回 batch_id；执行异步进行。

type Service 

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

Service Skill 业务逻辑层。

func NewService 

func NewService(pool *pgxpool.Pool) *Service

NewService 构造 Service。

func (*Service) CreateProposal 

func (s *Service) CreateProposal(ctx context.Context, ownerID uuid.UUID, req *CreateSkillProposalRequest) (*SkillProposalItem, error)

CreateProposal 创建或更新当前用户的 Skill Proposal。

func (*Service) ListAll 

func (s *Service) ListAll(ctx context.Context) ([]db.Skill, error)

ListAll 返回平台内置 skill（公开，给 /publish 表单与发现页用）。

func (*Service) ListForAgent 

func (s *Service) ListForAgent(ctx context.Context, agentID uuid.UUID) ([]db.Skill, error)

ListForAgent 返回某 Agent 已声明的 skill 详情。

func (*Service) ListPage added in v0.1.20 

func (s *Service) ListPage(ctx context.Context, query, category, listSort, locale string, page, size int32) (*SkillListResponse, error)

ListPage 返回公开 Skill 目录分页结果。

func (*Service) ListProposals 

func (s *Service) ListProposals(ctx context.Context, ownerID uuid.UUID) ([]SkillProposalItem, error)

ListProposals 返回当前用户最近提交或导入生成的 Skill Proposal。

func (*Service) ListProposalsPage added in v0.1.20 

func (s *Service) ListProposalsPage(ctx context.Context, ownerID uuid.UUID, query, status, sort string, page, size int32) (*SkillProposalListResponse, error)

ListProposalsPage 返回当前用户 Skill Proposal 分页结果。

func (*Service) RecommendAgentsBySkills 

func (s *Service) RecommendAgentsBySkills(ctx context.Context, skillIDs []string, limit int) ([]AgentMatch, error)

RecommendAgentsBySkills 任务驱动推荐：按命中 skill 数量降序返回 Agent 列表。

由子轮 2.4 task 模块调用：传入 LLM 解析出的 skill_id 列表 + top-N， 拿到候选 Agent。limit <= 0 时不截断。

runtime Agent 复用市场 readiness，并且必须有 PostgreSQL 证明的 current-contract ready Session。周期在线性由 Redis Session lease 与 Runtime reaper 收敛；数据库 heartbeat 只用于排序。Agent Token 使用记录不是在线性证据。 Direct/MCP Agent 则需要 healthy 或成功运行证据，避免推荐到当前不可执行的供给。 排序：match_count desc → availability → recent Session/success evidence → verified_count desc → total_calls desc → agent_id（稳定）。 verified_count 来自 agent_skill_scores（模块 B 写入），把 verified 过的命中数当作信任加权。

func (*Service) SetAgentSkills 

func (s *Service) SetAgentSkills(ctx context.Context, agentID uuid.UUID, skillIDs []string) error

SetAgentSkills 用 skillIDs 覆盖某 Agent 的关联（事务内 DELETE + 批量 INSERT）。

校验：

  1. 数量 <= MaxSkillsPerAgent；
  2. 去重后非空串；
  3. 每个 id 必须存在于 skills 表（否则 400 报告第一个非法 id）。

调用方负责鉴权：仅 Agent.creator_id == 当前用户 时才允许调用。

type SetSkillsRequest 

type SetSkillsRequest struct {
	// SkillIDs Agent 声明的 skill_id 列表，最多 5 个；重复 / 空串视为非法。
	SkillIDs []string `json:"skill_ids" validate:"required"`
}

SetSkillsRequest 创作者绑定 skill 列表。

type SetSkillsResponse 

type SetSkillsResponse struct {
	AgentID string      `json:"agent_id"`
	Items   []SkillItem `json:"items"`
}

SetSkillsResponse 绑定后回写最新列表。

type SkillItem 

type SkillItem struct {
	ID           string                      `json:"id"`
	Category     string                      `json:"category"`
	Name         string                      `json:"name"`
	Description  string                      `json:"description"`
	SortOrder    int32                       `json:"sort_order"`
	Translations map[string]SkillTranslation `json:"translations,omitempty"`
}

SkillItem 单个 skill 的对外 DTO。

type SkillListResponse added in v0.1.20 

type SkillListResponse struct {
	Items          []SkillItem `json:"items"`
	Total          int64       `json:"total"`
	Page           int32       `json:"page"`
	Size           int32       `json:"size"`
	Query          string      `json:"query,omitempty"`
	CategoryFilter string      `json:"category_filter,omitempty"`
	Sort           string      `json:"sort"`
}

SkillListResponse 是公开 Skill 目录列表响应。

type SkillProposalItem 

type SkillProposalItem struct {
	ID              string  `json:"id"`
	AgentID         *string `json:"agent_id,omitempty"`
	ProposedSkillID string  `json:"proposed_skill_id"`
	Category        string  `json:"category"`
	Name            string  `json:"name"`
	Description     string  `json:"description"`
	Source          string  `json:"source"`
	Status          string  `json:"status"`
	MatchedSkillID  *string `json:"matched_skill_id,omitempty"`
	CreatedAt       string  `json:"created_at"`
	UpdatedAt       string  `json:"updated_at"`
}

SkillProposalItem 是 Skill Proposal 的对外 DTO。

type SkillProposalListResponse 

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

SkillProposalListResponse 是创作者侧提案列表。

type SkillScoreItem 

type SkillScoreItem struct {
	SkillID      string  `json:"skill_id"`
	SkillName    string  `json:"skill_name,omitempty"`
	Status       string  `json:"status"`
	AverageScore *int32  `json:"average_score,omitempty"`
	PassCount    int32   `json:"pass_count"`
	TotalCount   int32   `json:"total_count"`
	LastBatchID  *string `json:"last_batch_id,omitempty"`
	VerifiedAt   *string `json:"verified_at,omitempty"`
	UpdatedAt    string  `json:"updated_at"`
}

SkillScoreItem 单条 (agent × skill) 评分概览。

type SkillTranslation added in v0.1.56 

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

SkillTranslation is locale-specific public copy for one canonical Skill. The top-level fields remain the catalog's default copy for compatibility.

type TopAgentForSkill 

type TopAgentForSkill struct {
	AgentID           string   `json:"agent_id"`
	Slug              string   `json:"slug"`
	Name              string   `json:"name"`
	Description       string   `json:"description"`
	Tags              []string `json:"tags"`
	PricePerCallCents int32    `json:"price_per_call_cents"`
	TotalCalls        int32    `json:"total_calls"`
	AverageScore      *int32   `json:"average_score,omitempty"`
	VerifiedAt        *string  `json:"verified_at,omitempty"`
}

TopAgentForSkill /skills 列表页 top-N 行。

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.