IronClaw 能力架构（Reborn Capability Architecture）实践指南：类型化契约、受中介调用路径与运行时通道设计

本指南以 IronClaw 仓库内的能力架构规则文档（.claude/rules/tools.md）为骨架，结合 ironclaw_capabilities 等核心 crate 的源码与契约测试，系统讲解"能力（Capability）"在 Reborn 宿主路径中的执行方式：产品调用方为何不能直接触碰运行时通道、稳定所有权如何划分、以及如何安全地新增一个能力。读完你将掌握 IronClaw 的能力授权膜（authorization membrane）、dispatch 调用链与运行时适配器的设计约束，能够正确地为项目贡献或审查新能力。

能力是经过受中介路径执行的类型化契约

IronClaw 的能力架构有一条不可动摇的核心原则：能力（Capability）是类型化契约（typed contract），并且只能通过受中介的 Reborn host 路径执行。产品调用方（product caller）不直接调用运行时通道（runtime lanes）、存储后端、provider 客户端或密钥存储来完成某个动作——它们必须先经过宿主的中介层。

这一设计在源码中的体现非常直接：ironclaw_capabilities crate 的模块文档将其定位为"kernel's authorization membrane"（内核授权膜），并声明每一项特权效果（privileged effect）都必须跨过 CapabilityHost（见 crates/kernel/ironclaw_capabilities/src/host/mod.rs）。换句话说，不存在绕过宿主直接"做事情"的旁路。

调用链的抽象层次如下：

• 产品层（ironclaw_assistant、ironclaw_composition、ironclaw_webui）调用能力门面（facade），不触及运行时内部；
• 能力层（ironclaw_capabilities）执行 invoke / resume / spawn 工作流；
• 授权与审批（ironclaw_authorization、ironclaw_approvals、ironclaw_runtime_policy）给出决策与租约（leases）；
• 宿主运行时（ironclaw_host_runtime）持有义务（obligations）、宿主中介服务，以及封闭的通道执行器（closed lane executor）——它把已经授权的请求路由给具体的运行时适配器；
• 具体的执行通道由 WASM / MCP / 脚本（scripts）/ 第一方（first-party）适配器承担；
• ironclaw_extension_registry 只负责声明式清单与安装记录，绝不执行任何东西。

稳定所有权划分：谁拥有什么

架构规则文档给出了清晰的所有权划分，这是理解代码归属的关键：

组件	职责边界
ironclaw_host_api	中性的请求、权威（authority）、资源与结果类型，是契约类型的唯一所有者
ironclaw_capabilities	面向调用方的 invoke / resume / spawn 工作流
authorization / approvals / runtime-policy	决策（decision）与租约（lease）
ironclaw_host_runtime	义务、宿主中介服务、封闭的通道执行器，其 dispatch 组合只负责把已授权请求路由到运行时适配器
WASM / MCP / scripts / first-party 适配器	具体的执行通道
ironclaw_extension_registry	仅声明式清单与安装记录

这一划分在代码层面得到验证：CapabilityDispatcher trait 的注释明确写着"只分发一个已经授权的 JSON 能力请求，且不得执行面向调用方的授权或审批解析"（见 crates/contracts/ironclaw_host_api/src/dispatch.rs），其 dispatch_json 方法接收的参数是 Authorized 见证类型而非裸请求——授权决策发生在调用它的宿主内部。

ironclaw_capabilities 本身也不依赖任何具体运行时实现：契约测试 crates/kernel/ironclaw_capabilities/tests/capability_boundary_contract.rs 直接解析其 Cargo.toml，断言生产依赖中不得出现 ironclaw_host_runtime、ironclaw_mcp、ironclaw_sandbox、ironclaw_wasm、ironclaw_secrets、ironclaw_network 等具体 crate——它只能通过中性端口（neutral ports）与外部协作。

执行链规则：顺序、边界与证据

架构规则文档定义了能力执行必须遵守的规则，这里结合源码逐条展开：

1. 动作按既定顺序穿过各层：授权（authorization）→ 审批（approvals）→ 资源记账（resource accounting）→ 义务（obligations）→ 分发（dispatch）→ 运行时执行（runtime execution）。
2. 运行时适配器只接收已授权的类型化请求，绝不重复或绕过策略。RuntimeAdapter trait 的契约注释同样强调："实现不得执行面向调用方的授权或审批解析；它们只能通过给定的 governor 预留/对账资源，并且只能暴露被脱敏（redacted）的 DispatchError 类别"（见 crates/kernel/ironclaw_host_runtime/src/services/runtime_adapters.rs）。
3. 产品工作流与 UI 处理器调用产品/能力门面，不得伸入运行时通道内部。
4. 扩展清单只声明能力表面（surfaces），注册表不执行它们。
5. 凭据与 HTTP 始终由宿主中介。运行时适配器在发起执行前需要通过 InvocationServicesResolver 解析服务（如网络、密钥注入），而不是由通道自行持有客户端句柄。
6. 模型/用户可纠正的失败返回模型可见的 Failed 或 Denied 结果；宿主机错误（host errors）只用于让运行无法继续的故障。
7. 结果是有界且被脱敏的。外部效果必须有权威证据（authoritative evidence）外加读回验证（read-back verification）；仅凭声明（claim-only）的结果必须按 .claude/rules/tool-evidence.md 的定义显式标记为 unverified（未验证）。

关于第 7 点的"证据"概念，配套文档 .claude/rules/tool-evidence.md 进一步解释：一个成功的能力结果本质上是对某个效果（effect）的声明。产生副作用的能力必须返回由权威边界产生的证据，而不是乐观的本地消息。例如 provider 写入要返回 provider 签发的 ID 或修订号、文件系统写入要返回已提交的版本/大小、OAuth 完成要做一次最小化的已认证读取、外发投递要返回 coordinator 的 Delivered 结果（该结果只在持久化终态写入提交后才发出）。UI 的成功展示也必须跟随后端证据，不允许在持久化或 provider 状态未知时显示本地乐观对勾。

验证调用路径：代码知识图谱与符号搜索

架构规则文档要求在任何编辑动作之前先验证当前调用路径。仓库提供了两个手段：

bash scripts/codebase-graph.sh status
rg -n "CapabilityHost|RuntimeAdapter|dispatch|invoke|resume|Obligation" \
  crates

• scripts/codebase-graph.sh 是仓库自带的代码知识图谱脚本（见 scripts/codebase-graph.sh），status 子命令用于检查图谱的新鲜度；
• 在图谱不可用时，直接以符号搜索代替：搜索能力所有者、追踪入站与出站调用。CapabilityHost、RuntimeAdapter、dispatch、invoke、resume、Obligation 是调用链上的核心符号，前两个分别定义在 crates/kernel/ironclaw_capabilities/src/host/mod.rs 与 crates/kernel/ironclaw_host_runtime/src/services/runtime_adapters.rs。

运行时通道选择：内置、WASM、MCP 还是新通道？

规则文档给出了明确的选型建议：

• 内置能力（Built-in）：适合与宿主强耦合的产品行为；
• WASM：沙箱化扩展代码的默认通道；
• MCP：适合外部服务器集成；
• 新增通道：必须实现既有的宿主契约，不得另起一套平行的执行管线。

这一"封闭通道集合"在 RuntimeLaneExecutor 中得到了具象化实现。它持有四个固定槽位——first_party、wasm、mcp、process——并以 RuntimeLane 枚举做匹配分发（见 crates/kernel/ironclaw_host_runtime/src/services/runtime_adapters.rs）。未配置的通道会返回 DispatchError::MissingRuntimeBackend，而不是静默降级。这意味着通道集合在编译期就是封闭的：要么实现既有的四种通道之一，要么在宿主运行时中显式扩展该封闭集合。

添加一个能力：七步工作流

架构规则文档给出了新增能力的完整步骤，这是全文最具操作性的部分，必须完整保留：

1. 决定行为归属：是宿主耦合的内置能力（host-coupled built-in）、WASM 扩展、MCP 集成，还是其他既有运行时通道。
2. 定义类型化契约：以最低稳定所有者（lowest stable owner）定义类型化的请求/结果、作用域（scope）、权威（authority）、资源（resource）与脱敏（redaction）契约。
3. 注册声明式描述/表面：注册一个声明式的 descriptor / surface，绝不能让"发现"（discovery）过程去执行它。
4. 通过 CapabilityHost 路由调用：包括策略要求的审批/恢复（approval/resume）流程。
5. 实现效果：把效果实现放在宿主运行时服务之后，或实现一个 RuntimeAdapter。
6. 返回有界且脱敏的输出：附带权威的效果证据与读回验证；如果只是声明性结果，则显式标记为 unverified。
7. 补充调用方路径测试：覆盖允许（allow）、拒绝（deny）、审批/恢复（approval/resume）、非法输入（invalid input）、运行时不可用（unavailable runtime）、取消（cancellation）与脱敏（redaction）这些场景。

同时文档还划了两条红线：

• 当请求形状已知时，不得使用裸 JSON/字符串分发约定——即必须使用类型化契约；
• 不得把环境的数据库、文件系统、HTTP 客户端或密钥句柄传入产品处理器或扩展代码——这正与"凭据与 HTTP 保持宿主中介"的规则呼应。

源码视角：CapabilityHost 的六个工作流

CapabilityHost 的实现采用了"按工作流分文件"的组织方式，每个工作流都是宿主上的一个固有方法，对外保持单一入口。各子模块的职责如下（见 crates/kernel/ironclaw_capabilities/src/host/mod.rs）：

模块	负责的工作流	绝不包含
invoke	工作流 1：invoke_json，即时的内联调用	授权决策本身
authorize	共享折叠：信任、运行时策略、持久化审批与 Authorized 封印	任何工作流形状的逻辑
approval_resume	工作流 2：resume_json	分发尾部（属于 resume_support）
auth_resume	工作流 3、4：auth_resume_json 与 decline_auth_json	分发尾部
spawn_resume	工作流 5：resume_spawn_json	内联分发
spawn	工作流 6：spawn_json 及其私有 authorize_spawn 折叠	内联分发
resume_support	三个 resume 工作流汇聚的 preflight / authorize / dispatch 尾部	工作流前奏
obligation_seams	围绕分发调用的 prepare / complete / abort	义务的实现
error_mapping	把外部错误与裁决翻译成本 crate 的词汇表	任何策略决策

三条纪律约束了该结构的真实性：工作流模块只拥有自己的前奏、绝不含分发尾部；authorize 负责决策而工作流只做裁决映射；该文件只存放状态与词汇而非行为。

CapabilityHost 还实现了 CapabilityAuthorizer——它是唯一能铸造 AuthorizationGrant、为 Authorized 见证类型盖章的 crate（见 crates/kernel/ironclaw_capabilities/src/host/mod.rs）。这从类型系统层面保证了"只有运行 authorize 折叠的代码才能封印一次授权"，是授权封印棘轮（authorized seal ratchet）的落点。

构建 CapabilityHost 时，除必填的 registry、dispatcher、authorizer、trust_policy、runtime_policy、policy_facts 外，还有一组可选的 builder 方法（见同文件第 302-383 行）：

• with_invocation_state：挂接进程调用状态存储，resume_json 必需，invoke_json / spawn_json 强烈建议（否则失败路径不持久化调用记录）；
• with_approval_requests：挂接审批请求存储，审批必需的调用路径与 resume_json 必需，缺失时以 ApprovalStoreMissing 失败而不是阻塞等待人工审查；
• with_capability_leases：挂接能力租约存储，用于消费已批准的租约，resume_json 必需；
• with_process_manager：用于派生长期运行的调用，spawn_json 必需，缺失时报 ProcessManagerMissing；
• with_obligation_handler：挂接义务处理器，无处理器时非空义务会 fail-closed（失败关闭）。

直接访问例外：什么情况下可以绕过中介

规则文档明确：在以下三种情形中允许直接访问领域（domain）——

1. 拥有该领域的实现内部；
2. 纯产品读取，且通过类型化的查询/门面契约进行；
3. 组合启动/对账（composition startup/reconciliation）。

但必须强调的是：用户触发的变更（user-triggered mutation）跳过能力授权或宿主中介，绝不构成例外。任何绕过正常路径的调用，其代码注释与 PR 描述都必须说明：所绕过的能力授权、审批、资源、审计或运行时义务分别由哪个契约负责，以及为什么不会丢失。

审查是否存在平行管线（parallel pipeline）时，文档给出了以下命令：

rg -n "\.dispatch\(|\.invoke\(|\.resume\(" crates/product/ironclaw_assistant \
  crates/app/ironclaw_composition crates/product/ironclaw_webui
rg -n "RuntimeAdapter|CapabilityHost" crates

第一条用于在产品工作流与 UI 中排查直接调用分发/调用/恢复方法的旁路，第二条用于盘点适配器与宿主在代码库中的使用面。配合 crates/kernel/ironclaw_capabilities/tests 下覆盖 allow/deny、auth required、审批恢复、调用状态、持久化审批等场景的契约测试（如 capability_host_auth_resume_contract.rs、capability_host_invocation_state_contract.rs、capability_host_github_comment_approval_contract.rs），即可系统验证调用链行为是否符合架构规则。

小结

IronClaw 的能力架构可以浓缩为一句话：调用方提出类型化请求，宿主完成授权折叠并封印 Authorized 见证，封闭的通道执行器把已授权请求路由到不持有策略决策权的运行时适配器，最终效果必须附带权威证据并接受读回验证。新增能力时遵循"选通道 → 定契约 → 注册声明 → 走 CapabilityHost → 实现效果 → 返回有界证据 → 补全测试"的七步法，并守住"不建平行管线、不传环境句柄、不绕过授权"三条红线，即可保证能力始终处于受中介、可审计、可恢复的执行路径之中。