Skip to main content
Adapter 是 Huoban 的异形活字转接件：它描述导入格式或外部能力如何进入 Huoban 的 capability、mapping、副作用和依赖边界。Adapter 的存在不代表来源可信或操作获准。 设计背景见 Adapter 模型，环境依赖见 Requirement。

​
字段

locator 按 source type 封闭：mcpTool 只能使用 url + tool；文件型 source 与 local 只能使用 path；harness 不携带 locator，具体目标必须由 Run binding 和 Requirement 明示。 标准副作用列表见 Skill 副作用枚举。

​
合法示例

对应 source example：examples/adapters/grill-me-skill-md.yaml。

​
MCP source 与 MCP Requirement

source.type: mcpTool 要求 Adapter 声明 source.url 与 source.tool。这只描述来源。若希望当前 Preflight 检查 MCP endpoint 和 tool 是否可发现，还必须显式声明 type: mcpTool 的 Requirement，包括 freshness、target.serverUrl 和 target.name。 当前 source example examples/adapters/stage-reporting-mcp.yaml 同时使用这两层结构。

​
当前 CLI 行为

  • validate 检查 source 条件、capability、mapping、Requirement 和副作用形状。
  • explain 输出 source、capabilities、Requirement、副作用和 trustRef。
  • 当前 huoban import 只生成 Profile，不会从外部文件自动生成 Adapter。
  • Adapter 被 Run stage/handler 绑定，或由已绑定 Skill 的 adapterRef 到达时，Preflight 检查 capability、Requirement、trustRef 与 Trust 的 policyRefs。
  • Preflight 不根据 source 自动访问文件或网络；只有显式 Requirement 会触发对应检查。
  • 任何带 source.path 的 source 必须有路径完全相同且包含 read 的 required localPath Requirement；MCP tool source 必须有 URL 与 tool name 完全相同的 required mcpTool Requirement。
当前仓库不调用 Adapter 所描述的外部能力。

​
验证边界

  • mapping 值只验证为字符串；当前 source 没有 mapping DSL evaluator。
  • checkpoint 是开放提示，不是 Checkpoint 实例。
  • 普通 validation 不解析 trustRef。
  • 当前 Preflight 还要求可达 Adapter 的 Trust subjectRef 精确指向该 Adapter，并确认关联 Policy 引用存在；它不评估 trust level、signature 或 Policy rule。
  • source locator 与 required Requirement 不一致时，当前 Preflight 产生 SourceRequirementMissing，不能作为权威就绪结果。

​
相邻概念边界

​
常见错误

  • 为 Adapter 增加不存在的 spec.fallback。
  • source.type: mcpTool 漏写 url 或 tool。
  • 只写 MCP source，却声称 Preflight 会自动 discovery；应增加 MCP Requirement。
  • 把 mapping 写成对象或可执行模板，而不是 string-to-string 映射。
  • 认为 trustRef 可解析就代表来源 trusted 或 Policy 已允许。
  • 声称当前 import 命令会生成 Adapter。