Skill 能力目录

Skill 是平台上"可交易能力"的最小单位。平台定义契约，企业实现契约，匹配引擎按契约找供给，编排引擎按契约推导依赖。

---

为什么以 Skill 为中心

如果平台以 Agent 为中心，每个 Agent 都会定义自己的输入输出，结果就是：

• 无法比较两个 Agent 是否做同一件事
• 无法自动推导多个 Agent 的先后顺序
• 无法自动验证输出是否合格

Skill 把"能力"从"实现"中剥离出来：

Skill（平台定义）          AgentProfile（企业声明）
  输入 Schema      ◀── 实现 ──  skillIds: ["ce-certification-review-v1"]
  输出 Schema                a2aEndpoint
  验证规则                   sla
  运行要求                   pricing

同一个 Skill 可以有多个 Agent 实现，匹配引擎负责选最合适的那个。

---

Skill 结构

interface SkillDefinition {
  skill_id: string;            // 全局唯一，如 "ce-certification-review-v1"
  name: string;                // 可读名称
  domain: string;              // compliance / tax / trade / legal / platform
  subdomain: string;           // ce_certification / vat / hs_code ...
  version: string;             // 语义化版本

  input_schema: JSONSchema;    // 输入契约
  output_schema: JSONSchema;   // 输出契约

  verification: {
    rules: VerificationRule[]; // 可自动执行的校验规则
    test_dataset?: {
      url: string;
      min_accuracy: number;
    };
  };

  reasoning: {
    required: boolean;         // 是否必须附带推理链
    format: 'structured_trail';
  };

  runtime: {
    protocol: string;          // a2a / websocket
    timeout_seconds: number;
  };

  interaction_mode?: 'structured' | 'dialogue' | 'hybrid';
  dependencies?: string[];     // 依赖的其他 skill_id
}

---

当前 Skill 清单（19 个）

定义位于 skills/*.json，启动时由 SkillCatalogService 导入 MongoDB 的 skills 集合。

领域	子领域	Skill 文件
platform	demand_translation	demand-translation.json
platform	result_synthesis	result-synthesis.json
platform	agent_self_registration	agent-self-registration.json
compliance	ce_certification	ce-certification.json
compliance	customs_doc	customs-doc.json
compliance	fda_label	fda-label.json
compliance	returns_compliance	returns-compliance.json
compliance	supplier_verification	supplier-verification.json
compliance	gdpr	gdpr.json
tax	vat	vat.json
tax	transfer_pricing	transfer-pricing.json
trade	hs_code	hs-code.json
trade	freight_quoting	freight-quoting.json
trade	cargo_tracking	cargo-tracking.json
legal	contract_review	contract-review.json
legal	supplier_agreement	supplier-agreement.json
legal	ip_infringement	ip-infringement.json
finance	multi_currency_accounting	multi-currency-accounting.json
procurement	rfq_generation	rfq-generation.json

platform 域的 Skill 由平台内部 Agent 实现，不计费，不参与外部匹配。

---

Skill 如何被使用

1. 匹配

agent-matching 按 skillId + subDomain 查询 AgentProfile.skillIds：

Skill: ce-certification-review-v1
  ├─ Agent A: skillIds 精确包含 → 能力分 +45
  ├─ Agent B: 只有 subDomain 相同 → 能力分 +35
  └─ Agent C: 都不匹配 → 不进入候选

2. 编排

工作流构建时，上游节点的 output_schema 与下游节点的 input_schema 决定依赖关系：

ce-certification（输出：certificateId, directives）
        │
        ▼
customs-doc（输入：certificateId）

如果两个节点之间没有 Schema 兼容关系，平台不会自动连线。

3. 执行

调用外部 Agent 时，平台传入的 input 必须符合 input_schema；返回结果必须符合 output_schema，否则节点失败。

4. 验证

verification.rules 定义可自动执行的检查，例如：

{
  "rules": [
    { "field": "directives", "op": "not_empty" },
    { "field": "riskLevel", "op": "in", "value": ["low", "medium", "high"] },
    { "field": "reasoning", "op": "required" }
  ]
}

验证结果写入 verification_results 集合。

---

新增一个 Skill

以新增"日本 PSE 认证"为例：

1. 定义 Skill JSON（skills/pse-certification.json）

{
  "skill_id": "pse-certification-review-v1",
  "name": "PSE 认证审查",
  "domain": "compliance",
  "subdomain": "pse_certification",
  "version": "1.0.0",
  "input_schema": {
    "type": "object",
    "required": ["product", "category"],
    "properties": {
      "product": { "type": "string" },
      "category": { "type": "string" }
    }
  },
  "output_schema": {
    "type": "object",
    "required": ["applicable", "requirements", "reasoning"],
    "properties": {
      "applicable": { "type": "boolean" },
      "requirements": { "type": "array", "items": { "type": "string" } },
      "reasoning": { "type": "string" }
    }
  },
  "verification": { "rules": [] },
  "reasoning": { "required": true, "format": "structured_trail" },
  "runtime": { "protocol": "a2a", "timeout_seconds": 300 }
}

2. 重启服务，SkillCatalogService 自动导入。

3. Agent 注册时声明：

{
  "agentId": "tokyo-cert-body",
  "skillIds": ["pse-certification-review-v1"],
  "a2aEndpoint": "https://agent.example.com/message:send"
}

4. 匹配与编排自动生效——不需要改代码。

---

设计边界

边界	说明
Skill 由平台定义	企业不能自由创造 Skill，否则契约失去可比性
一个 Agent 可声明多个 Skill	但每个 Skill 独立评分
Skill 有版本	破坏性变更应升版本，旧版本保留过渡期
输入输出必须是 JSON	文件通过 URL 或对象引用传递
验证规则是白名单比较器	不支持任意脚本执行
依赖关系显式或可推导	不依赖 LLM 猜测执行顺序

---

下一步

• 谁能实现 Skill → Agent Profile
• 如何被选中 → Agent Matching
• 能力目录的代码实现 → agent 模块