Adapter 模型

Adapter 是 Huoban 的异形活字转接件：它把外部 skill、MCP tool、规则文件、团队脚本或工具能力，转成 Huoban 可理解、可排版、可审查的对象声明。它不是调用桥，也不是 MCP server。Adapter 的职责是声明外部能力如何进入 Huoban：来源是什么、提供哪些 capability、依赖哪些环境事实、输入输出如何映射、声明哪些 side effects、是否建议 checkpoint，以及信任信息在哪里。本页属于核心概念，解释 Adapter 的设计边界和使用模型；字段级定义、必填项和 schema 约束见 Adapter 规范。

声明外部来源

source 记录外部能力来自 skillMd、mcpTool、claudeSkill、codexSkill、cursorRule、harness 或 local。

映射为 capability

capabilities 声明外部来源可以满足哪些 Huoban 能力需求。

声明副作用

sideEffects.declared 是计划和审批输入，不等于实际执行事实。

连接 Trust / Policy

trustRef 指向信任记录，Policy 再基于 capability、side effect 和 trust level 审查行为边界。

暴露运行依赖

requirements[] 声明本地文件、程序、MCP tool、凭据或 runner capability，供 Preflight 检查。

Adapter 不是调用桥

Adapter 的第一性职责是把外部能力标准化，而不是执行外部能力。

对象	职责	不承担
`Skill`	声明 Huoban 原生或已标准化的能力。	不描述外部来源如何被适配。
`Adapter`	声明外部来源如何映射成 capability、输入输出、副作用和信任边界。	不执行工具，不保存运行事实，不证明来源可信。
`Policy`	基于 capability、side effect、trust level 判断 allow / deny / requireApproval。	不推断外部工具 mapping。
`Run`	在一次执行中把 Flow role / capability 绑定到具体 Skill 或 Adapter。	不重新定义 Adapter 的 source、mapping 和 sideEffects。
`Trust`	记录 Adapter 或其他对象的来源、level、review、signatures、sandbox 和 policyRefs。	不自动授予执行权限。

一句话：Skill 是标准活字，Adapter 是异形活字转接件。

与 Skill 的边界

外部 SKILL.md、MCP tool、Cursor Rule、团队脚本或内部 workflow 默认不应直接变成 trusted Skill。

对象	表达内容
`Skill`	已经标准化的能力、输入输出、上下文提示和 declared side effects。
`Adapter`	外部来源如何被解释为 Huoban capability，以及输入输出、副作用和信任边界如何映射。

Adapter 可以经过 review 后派生或提升为 Skill，但这不是自动过程。导入外部 SKILL.md 时，默认结果应是 Adapter。

与 Tool / MCP 的边界

MCP tool、CLI、API 和内部脚本是外部能力来源；Adapter 是它们进入 Huoban 的标准化声明。 Adapter 不替代 MCP server，也不规定某个工具的调用协议。它只声明：

这个外部来源提供哪些 capability。
Huoban 输入输出如何映射到外部输入输出。
可能产生哪些 declared side effects。
使用前需要满足哪些 Requirement。
是否有 checkpoint hints。
信任记录由哪个 Trust 对象承载。

调用协议、认证细节和请求参数细节不进入标准 Adapter；如需保留，应放在标准对象之外的实现侧材料中。mapping 只保留槽位映射，checkpoint 只保留非标准化提示。 source.type: mcpTool 必须带 url 和 tool，用于标识外部来源；实际可用性应另用 requirements[] 中的 mcpTool 声明并通过 Preflight 发现。source identity 与 readiness 不能合并成一个模糊字段。

与 Profile 的边界

Profile 处理“按什么上下文判断”，Adapter 处理“外部能力如何被使用和审查”。

来源内容	应进入
团队规范、项目结构、领域语言、历史决策。	`Profile`
可复用 skill、工具行为、脚本、workflow 或 capability-like 指令。	`Adapter`
AGENTS.md / CLAUDE.md / Cursor Rules 中的上下文规则。	通常进入 `Profile`。
AGENTS.md / CLAUDE.md / Cursor Rules 中的可复用能力或工具流程。	通过 `Adapter` 表达。

不要把所有 Markdown 都导成 Adapter，也不要把可执行能力塞进 Profile。

与 Policy 的边界

Adapter 声明外部能力可能产生哪些 side effects；Policy 决定这些 side effects 在当前 trust level 下允许、拒绝或需要审批。

# Adapter spec fragment
sideEffects:
  declared:
    - readFile
    - writeFile

# Policy spec fragment
defaults:
  unknownSideEffect: requireApproval
rules:
  - effect: requireApproval
    when:
      sideEffects:
        - writeFile

Adapter 不能绕过 Policy，也不能通过声明自己安全来获得权限。未声明或无法判断的副作用应由 Policy.spec.defaults.unknownSideEffect 保守处理；当前 side effect enum 没有 unknown。

与 Run binding 的边界

Adapter 是可复用外部能力声明；Run.spec.bindings 是一次执行中的绑定结果。

# Run spec fragment
bindings:
  primary-review:
    adapterRef: grill-me-skill-md

边界是：

Flow 声明需要 capability。
Adapter 声明外部来源可以满足哪些 capability。
Run.spec.bindings 在一次具体执行中选择 Skill 或 Adapter。
Run.spec.snapshot.bindingHash 可以记录 binding map。

当前 snapshot 不能声称完整冻结 Adapter spec。Adapter 不保存执行状态，Run 也不复制 Adapter 的 source、mapping 和 sideEffects。

Requirement 与 Lifecycle provider

Adapter 是声明外部依赖最重要的所有者之一：

spec:
  source:
    type: mcpTool
    url: http://127.0.0.1:8787/mcp
    tool: report_stage
  capabilities:
    - huoban.dev/stageReporting
  requirements:
    - id: reporting-tool
      type: mcpTool
      origin: declared
      freshness:
        maxAgeSeconds: 60
      target:
        serverUrl: http://127.0.0.1:8787/mcp
        name: report_stage

Flow 的 Lifecycle Handler 可以要求 huoban.dev/stageReporting，Run 再把 handler role 绑定到这个 Adapter。Preflight 检查 capability、binding、Trust 引用和 MCP tool readiness；实际投递仍受 Policy 与执行权限约束。 Adapter 本身不监听事件，也不调度 handler。它只是 provider 的标准声明。详见 Requirement 与 Lifecycle Handler。

与 Trust 的边界

Adapter 可以通过 trustRef 指向 Trust，但 Adapter 本身不证明可信。

# Adapter spec fragment
trustRef:
  name: local-reviewed-grill-me

Trust 记录来源、level、review、signatures、sandbox 和 policyRefs。外部来源默认应按 unknown level 处理，review 后才可能成为 reviewed 或 trusted。无论 trust level 多高，执行仍受 Policy 约束。

source type

v1alpha1 的 Adapter.spec.source.type 只支持以下值：

source type	语义
`skillMd`	外部或本地 `SKILL.md`。
`mcpTool`	MCP tool。
`claudeSkill`	Claude skill。
`codexSkill`	Codex skill。
`cursorRule`	Cursor Rules。
`harness`	外部 harness 类来源。
`local`	本地脚本、文件或工具来源。

这些是外部来源类型，不是 Huoban 的自我定位。harness 只表示某类外部来源可以被 Adapter 标准化，不能把 Huoban 写成 harness。 locator 由 source type 决定：mcpTool 使用 url + tool，文件型来源与 local 使用 path，harness 不携带 locator。任何 path 或 MCP tool 依赖仍必须由精确匹配的 required Requirement 显式声明。

mapping

Adapter.spec.mapping 只表达输入输出槽位的映射约定。

mapping:
  inputs:
    prompt: user.prompt
    context: profile.effectiveContent
  outputs:
    review: artifact.decisionNotes

当前 mapping.inputs 和 mapping.outputs 是字符串 map，不是完整转换语言。类型转换、模板执行、参数校验和复杂输出解析属于实现层或未来扩展。

checkpoint 与 fallback

Adapter.spec.checkpoint 是开放结构，只能提供实现或导入时的校对提示：

checkpoint:
  recommended: true
  reason: SkillProducesDesignJudgment

示例中的 recommended 和 reason 是当前示例约定，不是 v1alpha1 固定字段。真正的决策边界由 Checkpoint 对象承载。 fallback 不属于 Adapter。替代实现必须在 Run.spec.bindings.<role>.fallback 中显式锁定，这样同一个 Adapter 不会在不同 Run 中隐式改变行为。fallback provider 仍需满足 capability 并通过同一次 Preflight；reference implementation 尚不提供自动切换 runtime。

为什么 Adapter 是顶层对象

Adapter 与其余九个顶层 kind 具有相同的协议地位。实现可以只支持协议对象的一个明确子集；但只要声明支持 Adapter，就必须按 schema 和这里的边界解释外部 SKILL.md、MCP tool、Cursor Rule、团队脚本与内部工具。没有 Adapter，Huoban 要么只能重写所有能力，要么会把外部自然语言资产误认为原生可信 Skill。

行业语言映射

用当前行业语言看，Adapter 位于 tool adapter、MCP wrapping、skill import 和 capability normalization 的交叉点。

行业概念	Huoban 表达
tool adapter	外部工具通过 `Adapter` 声明 source、capability、mapping 和 side effects。
MCP wrapping	MCP tool 是 source type；Adapter 不替代 MCP server。
skill import	`SKILL.md` 默认导入为 Adapter，而不是 trusted Skill。
capability normalization	不同来源先归一成 capability，再进入 Flow 和 Run binding。

Huoban 不要求已有生态全部重写成原生对象。Adapter 让外部能力先进入同一套对象模型，再逐步 review、标准化和复用。

结构示例

apiVersion: huoban.dev/v1alpha1
kind: Adapter
metadata:
  name: grill-me-skill-md
  labels:
    huoban.dev/imported-from: SKILL.md
spec:
  source:
    type: skillMd
    path: examples/fixtures/grill-me/SKILL.md
  capabilities:
    - huoban.dev/designReview
    - huoban.dev/planning
  requirements:
    - id: skill-source
      type: localPath
      origin: declared
      target:
        path: examples/fixtures/grill-me/SKILL.md
        access:
          - read
  mapping:
    inputs:
      prompt: user.prompt
      context: profile.effectiveContent
    outputs:
      review: artifact.decisionNotes
  sideEffects:
    declared:
      - readFile
      - writeFile
  checkpoint:
    recommended: true
    reason: SkillProducesDesignJudgment
  trustRef:
    name: local-reviewed-grill-me
status:
  conditions:
    - type: AdapterImported
      status: "True"
      reason: ImportedFromSkillMd
    - type: ImportNeedsReview
      status: "True"
      reason: CapabilityAndSideEffectsInferred

这个示例来自 examples/adapters/grill-me-skill-md.yaml。它展示的是 SKILL.md 导入后的 Adapter：声明来源、能力、映射、副作用、checkpoint hint 和 trust 引用。

开始使用

核心概念

规范参考

迁移指南

示例

标准与治理

开源项目

Adapter 模型

声明外部来源

映射为 capability

声明副作用

连接 Trust / Policy

暴露运行依赖

Adapter 不是调用桥

与 Skill 的边界

与 Tool / MCP 的边界

与 Profile 的边界

与 Policy 的边界

与 Run binding 的边界

Requirement 与 Lifecycle provider

与 Trust 的边界

source type

mapping

checkpoint 与 fallback

为什么 Adapter 是顶层对象

行业语言映射

结构示例

声明外部来源

映射为 capability

声明副作用

连接 Trust / Policy

暴露运行依赖

​Adapter 不是调用桥

​与 Skill 的边界

​与 Tool / MCP 的边界

​与 Profile 的边界

​与 Policy 的边界

​与 Run binding 的边界

​Requirement 与 Lifecycle provider

​与 Trust 的边界

​source type

​mapping

​checkpoint 与 fallback

​为什么 Adapter 是顶层对象

​行业语言映射

​结构示例

Adapter 不是调用桥

与 Skill 的边界

与 Tool / MCP 的边界

与 Profile 的边界

与 Policy 的边界

与 Run binding 的边界

Requirement 与 Lifecycle provider

与 Trust 的边界

source type

mapping

checkpoint 与 fallback

为什么 Adapter 是顶层对象

行业语言映射

结构示例