企业官网建设流程全解析

• 人工智能
• AI 应用
• 交互助手
• AI Agent

导读

本文以crates/kernel/ironclaw_capabilities为核心，讲解 IronClaw（一个聚焦隐私、安全与可扩展性的 Agent OS）中**能力调用膜（Capability Membrane）**的架构与实现：所有特权效果——无论是 Loop 主循环、扩展宿主还是产品表面——都必须经由CapabilityHost这一唯一入口，穿越"信任上限 → 授权 → 审批 → 义务 → 资源预留"五重折叠，才能触达运行时。读完本文，你将掌握CapabilityHost的六个工作流划分、authorize单一决策折叠、Authorized密封见证（sealed witness）的铸造机制、义务缝（obligation seam）与宿主私有重放负载存储的设计，以及如何通过本地与架构测试验证这套边界。

一、能力膜定位：没有其他门的调用服务

ironclaw_capabilities在 IronClaw Reborn 中扮演"膜（membrane）"的角色：它是每个特权效果必须跨越的、面向调用方的唯一调用服务。该 crate 自述（README.md）明确指出：

The membrane: the single caller-facing invocation service every privileged effect must cross.

它属于kernel/层（[package.metadata.ironclaw] layer = "kernel"，见 Cargo.toml）。在 IronClaw 中，任何需要特权效果（文件写入、网络、密钥使用、进程派生等）的调用方——Loop 主循环、扩展宿主、产品表面——都必须走这里，"There is no other door"（没有其他门）。

职责边界同样清晰：

• 使用它：任何调用方需要调用（invoke）、恢复（resume）或派生（spawn）一个特权能力时；
• 不使用它：需要媒介执行机制（egress、secret staging、lane 适配器，→ironclaw_host_runtime）、进程生命周期或结果（→ironclaw_processes::ProcessHost）、或审批决议（→ironclaw_approvals）时。

该 crate 依赖并消费五个阶段 crate（ironclaw_trust、ironclaw_authorization、ironclaw_approvals、ironclaw_resources、ironclaw_runtime_policy），加上ironclaw_processes与ironclaw_turns，以及ironclaw_host_api、ironclaw_loop_contracts、ironclaw_event_log、ironclaw_filesystem、ironclaw_safety、ironclaw_extension_contracts、ironclaw_extension_registry等（详见 Cargo.toml 依赖清单）。四个正常消费方为ironclaw_host_runtime（唯一构造并驱动膜的场所）、ironclaw_loop_host、ironclaw_extension_host与ironclaw_composition。

二、六个工作流与 src/host 模块宪章

src/host/是一个工作流一个文件的目录模块拆分。CLAUDE.md 要求任何新增代码前先读src/host/mod.rs中的宪章表——它是"某项归属哪个文件"的唯一规则。宪章表（见 mod.rs）归纳如下：

三条规则保证宪章不被破坏（mod.rs 文档注释）：

1. 工作流模块拥有自己的前奏（preamble），绝不拥有尾部（tail）——一旦两个恢复工作流同意某个步骤，该步骤就归属resume_support；
2. authorize决策，工作流只映射裁决——某个工作流若长出属于自己的策略分支，就是夺取了膜本应集中持有的权威；
3. 本文件只持有状态与词汇，不持有行为——结构体、CapabilityAuthorizer密封、跨工作流的请求/折叠类型与构造器集中于此。

所有子模块都是私有的，且每个工作流都是CapabilityHost上的固有方法（inherent method），因此调用方仍然只看到一条路径；不允许为子模块添加pub use。每个文件必须保持在 1,500 行 ARCH-SPRAWL 阈值之下——这次拆分正是为了撤销融合大文件此前携带的arch-exempt: large_file豁免，重新融合会触发 pre-commit-safety.sh 检查。

三、CapabilityHost：单一权威路径与依赖注入组装

CapabilityHost（mod.rs）是一个泛型结构体，唯一携带的具体类型是分发器D: CapabilityDispatcher（以&D借用），其余全部是 trait object 端口：

pub struct CapabilityHost<'a, D> where D: CapabilityDispatcher + ?Sized, { registry: &'a ExtensionRegistry, dispatcher: &'a D, authorizer: &'a dyn TrustAwareCapabilityDispatchAuthorizer, trust_policy: &'a dyn TrustPolicy, runtime_policy: &'a EffectiveRuntimePolicy, policy_facts: &'a dyn HostPolicyFacts, invocation_state: Option<&'a dyn ProcessInvocationStatePort>, approval_requests: Option<&'a dyn ApprovalRequestStorePort>, capability_leases: Option<&'a dyn CapabilityLeaseStorePort>, process_manager: Option<&'a dyn ProcessManager>, obligation_handler: Option<&'a dyn CapabilityObligationHandler>, }

构造采用 builder 风格：new()接受五个必选端口（registry、dispatcher、authorizer、trust_policy、runtime_policy、policy_facts），随后可按需挂接：

• with_invocation_state：记录调用生命周期，resume_json必需，invoke_json/spawn_json强烈建议（否则错误路径不持久化调用记录）；
• with_approval_requests：持久化审批提示，审批路径必需，缺失时返回ApprovalStoreMissing；
• with_capability_leases：消费已批准的租约，resume_json必需；
• with_process_manager：派生长时调用，spawn_json必需，缺失返回ProcessManagerMissing；
• with_obligation_handler：满足 allow 裁决的义务，缺失时非空义务 fail-closed。

唯一的制造地点是ironclaw_host_runtime（README 依赖表明确：ironclaw_host_runtime"constructs and drives the membrane — the single construction site"）。

3.1 密封见证：只有本 crate 能铸造

impl CapabilityAuthorizer for CapabilityHost（mod.rs）是全工作区唯一的CapabilityAuthorizer实现者——也就是唯一能构造AuthorizationGrant(())、进而密封Authorized的代码。这正是"膜"的密封不变式的实现机制：只有运行授权折叠的代码才能铸造见证。该不变式由架构测试reborn_authorized_seal_ratchet.rs::capability_authorizer_is_implemented_only_by_the_kernel强制（含自测，验证绕过或不可读源码会令扫描失败而非通过），对应测试位于 ironclaw_architecture_tests。

四、authorize 折叠：信任 → 运行时策略 → 凭据 → 持久审批 → 授权 → 义务 → 密封

authorize()（authorize.rs）是所有工作流汇聚的单一决策折叠。其执行顺序（每一步失败都先尝试对 invocation 记录做状态迁移再返回错误）：

1. 上下文校验：request.context.validate()失败 →AuthorizationDenied { InternalInvariantViolation }；
2. 指纹：invocation_fingerprint_for_kind(Dispatch, ...)计算调用指纹，供审批重放比对；
3. 能力解析（前置）：registry.get_capability查不到 →UnknownCapability，且不创建调用记录（保持 host_runtime 删除的前置检查行为）；
4. 描述符富化：enrich_invocation_descriptor——仅对builtin.shell生效，将调用方显式选择的、manifest 声明了placeholder_env的扩展凭据合并进冻结描述符（详见下文 4.1）；
5. 调用记录 start：invocation_state.start(...)；
6. 信任评估（内核计算）：evaluate_trust调用evaluate_invocation_trust(registry, trust_policy, capability_id)。信任是内核在折叠内计算的，而不是调用方盖章传入的字段（CLAUDE.md 强调 "trust is computed here rather than received as a caller-stamped field"）；
7. 运行时策略规划：enforce_runtime_policy调用ironclaw_runtime_policy::plan_capability，规划器拒绝 → 模型可见的AuthorizationDenied（对应runtime_policy_failure）；
8. 凭据预检：policy_facts.credential_presence(...)——缺失凭据以AuthorizationRequiresAuth呈现，先于审批决策，保证人类审批永远不会消耗给一个尚无法执行的动作。Indeterminate（瞬时存储故障）跳过预检，因为分发期的义务检查是兜底执行者，且故障不应烧掉用户的一次认证交互。端口只返回事实，内核负责映射为裁决；
9. 持久审批折叠：apply_persistent_approval——仅对允许持久审批的权限模式（PermissionMode::Allow | Ask，Deny不可升级，见 authorize.rs），把候选 grant 逐个注入后重新授权，首个翻转为Allow的 grant 被采纳注入上下文，避免再次拉起审批闸门。返回采纳 grant 的constraints.expires_at作为密封截止时间的冻结事实；
10. 信任感知授权：authorizer.authorize_dispatch_with_trust(&authorize_context, &descriptor, &estimate, &trust_decision)，产生三叉裁决：
    • Decision::Allow { obligations }→prepare_obligations(Invoke, ...)准备义务，随后seal_authorization铸造见证，返回AuthorizeFold::Authorized；
    • Decision::Deny { reason }→ 记录 fail 为AuthorizationDenied，返回AuthorizeFold::Denied（reason 是模型可见的策略裁决）；
    • Decision::RequireApproval { request }→ 校验审批请求与调用匹配（approval request 与 invocation 指纹），持久化 pending 审批（approval_requests.save_pending），并把调用记录转移到block_approval；持久化失败时回滚（discard_pending），返回AuthorizeFold::Blocked。审批请求缺失任一 store 均返回ApprovalStoreMissing。

4.1 shell 凭据富化：显式选择的凭据才生效

enrich_invocation_descriptor（authorize.rs）只为builtin.shell能力工作：从输入中解析出shell_credential_contexts，要求每个上下文都是活跃扩展且其包信任达到 privileged 级别，再收集其中声明了placeholder_env的运行时凭据需求（同 handle 冲突声明会拒绝）；任何上下文未声明 shell 凭据同样拒绝。仅当运行时策略的后端是UserSandbox时才允许。富化后的描述符追加EffectKind::UseSecret，冻结的描述符随后驱动审批、凭据暂存与代理策略——普通命令文本永远不会隐式获得凭据。

4.2 密封见证：六个冻结事实

seal_authorization（authorize.rs）铸造Authorized见证，将六个权威冻结事实封入其中：

• actor：在膜处密封，绝不回退到user_id——无 actor 的上下文（系统服务/一次性调用）密封为Actor::System自身类别；
• lane：从描述符 runtime kind 解析；System运行时没有不可信执行 lane（None），不在膜处密封；
• origin：来自 ingress 盖章的上下文事实；只盖了run_id的上下文会为过渡兼容重建LoopRun；
• invocation：activity_id、capability、input、scope、actor、origin、estimate、correlation_id、process_id、parent_process_id；
• mounts / reservation：折叠产生的真实挂载与资源预留，绝不合成占位值；
• deadline：取最短命的冻结事实（witness_deadline取各候选过期时间的最小值），无冻结事实时回退到 5 分钟默认 TTL（WITNESS_DEFAULT_TTL: chrono::Duration::minutes(5)，authorize.rs），保证持有的见证不会活得比证明它的事实更久。

调用方（如invoke_json）若在允许后拿不到见证，会先abort_obligations清理再返回错误（MissingAuthorization或AuthorizationExpired，见 invoke.rs）。

五、六个工作流的入口：invoke / resume / auth-resume / decline-auth / spawn-resume / spawn

CLAUDE.md 指出invoke、approval_resume、auth_resume、spawn_resume、spawn各拥有一个面向调用方的工作流，authorize拥有它们全部汇聚的单一授权折叠，resume_support拥有三个恢复工作流共享的尾部。

以工作流 1invoke_json（invoke.rs）为例，完整生命周期为：

1. 组装InvocationInput，调用self.authorize(&request)；
2. 按AuthorizeFold三态映射：Authorized→ 解包见证；Denied→ 返回AuthorizationDenied { reason }；Blocked→ 返回AuthorizationRequiresApproval；
3. self.dispatcher.dispatch_json(*authorized)分发；分发失败 →abort_obligations清理、富化凭据需求错误（enrich_dispatch_error_credential_requirements）、invocation 记录迁移；
4. complete_dispatch_obligations完成后置义务；失败 → 以空 outcome 中止义务并 fail 记录；
5. 成功 →complete_invocation_after_side_effect完成记录，返回CapabilityDispatchResult。

三个恢复工作流共享的resume_support尾部处理三种互斥的租约状态（ResumedLeaseState，见 mod.rs）：PendingClaim（resume_json在授权返回Allow之后才认领一次性Active租约，Deny 时租约保持 Active）、AlreadyClaimed（auth_resume_json复用先前已 Claimed 的租约，不重复拉起审批）、NoPriorLease（auth_resume_json中approval_request_id为 None 的情况）。审批恢复必须先验证并认领匹配的带指纹租约再分发（Guardrails 规则）。PendingClaimAfterAuth把冻结的 grant 过期时间随规格携带（mod.rs），因为密封在认领之前铸造，过期时间不能从尚未认领的租约中读回。

BlockedResumeKind（mod.rs）区分两种被阻断的恢复路径：审批恢复/派生恢复以BlockedApproval记录为键并比较approval_request_id；认证恢复以BlockedAuth记录为键且不比较approval_request_id（其block_auth转换把持久化的 id 清为None）。

六、RuntimeDispatcher：密封见证的窄分发器

RuntimeDispatcher（dispatch.rs）是唯一的生产CapabilityDispatcher实现：它接收已授权的密封见证，把请求路由到预绑定的 lane 适配器，并拒绝任何见证与绑定 lane 不匹配的请求（DispatchError::MissingRuntimeBackend）。

核心机制：

• ToolResolver：按能力 id 解析预绑定绑定（TOOL-1）。解析是快照形态的查找——绑定在激活/注册时构建，绝不做每次调用的包/runtime-kind 选择；未知 id 返回None，分发在任何适配器工作前失败（TOOL-2）；
• ResolvedCapability：提供者扩展 id（宿主内建解析为合成builtin提供者）、runtime kind、以及Arc<dyn BoundCapabilityAdapter>；
• BoundCapabilityAdapter：接收原样的已授权CapabilityDispatchRequest——包、描述符、执行计划、文件系统、端口全部在绑定构建时捕获；实现不得执行面向调用方的授权或审批决议，且只能上浮脱敏的DispatchError类别；
• ChainToolResolver：first-Some-wins 的解析器组合（宿主内建 + 活动扩展快照）；
• DispatchReservationGuard：分发期间持有资源预留，validate()在分发前向ResourceGovernor校验；Drop中释放未交付的预留（失败时释放，见 dispatch.rs）；
• 事件发射：dispatch_requested、runtime_selected、dispatch_succeeded/dispatch_failed通过可选EventSink写入RuntimeEvent，并携带parent_invocation_id关联父调用。

见证过期（into_parts(Utc::now())失败）时，RuntimeDispatcher释放预留并返回DispatchError::AuthorizationExpired——fail-closed 语义，绝不带着过期见证分发。

七、义务缝：阶段化的 satisfy / prepare / abort / complete

义务（obligations）是授权裁决携带的、必须在副作用前后满足的约束。ironclaw_capabilities只定义缝（seam），实现位于ironclaw_host_runtime（Guardrails 明确：内置义务实现住在crates/kernel/ironclaw_host_runtime/src/obligations/，绝不放在本 crate）。

• 阶段：CapabilityObligationPhase::{Invoke, Resume, Spawn}（obligations.rs）；
• 请求类型：CapabilityObligationRequest（副作用前）、CapabilityObligationCompletionRequest（成功分发后）、CapabilityObligationAbortRequest（失败清理，携带 prepared outcome）；
• 产出：CapabilityObligationOutcome { mounts: Option<MountView>, resource_reservation: Option<ResourceReservation> }；
• 失败类别：稳定脱敏的CapabilityObligationFailureKind::{Audit, Mount, Network, Output, Resource, Secret}；
• 错误：CapabilityObligationError::{Unsupported, AuthRequired, Failed}，变体刻意避免原始输入/输出；
• 默认行为：satisfy必须实现；prepare默认委托satisfy并返回空 outcome；abort默认空操作；complete_dispatch默认检查post_dispatch_obligations（AuditAfter、RedactOutput、EnforceResourceCeiling、EnforceOutputLimit），存在未支持的后置义务时返回Unsupported（obligations.rs）。

工作流调用点：authorize折叠内在Allow后prepare_obligations(Invoke, ...)；invoke_json分发失败时abort_obligations、成功后complete_dispatch_obligations；spawn路径对应Spawn阶段。

八、宿主私有重放负载存储：ReplayPayloadStore

ReplayPayloadStore（replay_payload.rs）是门控/认证恢复的宿主私有原始重放负载持久化（arch-simplification §5.3）。其核心设计：

• 用途：当一次能力调用在审批或认证门控处被阻断时，未来某个恢复回合需要重新分发所需的原始负载——工具inputJSON、ResourceEstimate、先前审批身份、input ref、correlation id——当前随CapabilityApprovalResume/CapabilityAuthResume通过不可信 Loop 带内传输并暂存于 Loop 的序列化检查点；能力结果折叠后，面向 Loop 的Resolution只携带不透明恢复令牌（等于InvocationId），因此宿主必须自行持久化并在恢复时重建负载；
• 与 GateRecord 相反：GateRecord是模型可见的、只携带SafeSummary的门控渲染内容；ReplayPayload是宿主私有、携带原始工具输入，绝不模型可见——不得进入模型、事件、错误、快照或日志（CLAUDE.md Guardrails 逐条列举）。把负载移到宿主侧还消除了一项真实暴露：原始工具输入不再往返于 Loop 的序列化检查点；
• 为何放在本 crate：原始重放输入不属于进程日志生命周期行，ironclaw_turns宪章明确禁止在回合状态或事件中持久化原始工具输入；而本 crate 拥有该负载服务的调用/恢复/派生工作流且无此禁令。记录嵌入ironclaw_turns拥有的字段类型（CapabilityInputRef、AuthResumeApprovalIdentity）而非重新定义；
• 持久化后端：镜像ironclaw_approvals的GateRecordStore——ScopedFilesystem覆盖任意RootFilesystem，走共享的无锁cas_updatelane（非 CAS 后端 fail-closed：CasUnsupported→Backend错误），每个条目带RecordKind标签（"replay_payload_record"）使纯字节后端（如DiskFilesystem）首次写入即被拒绝；
• 路径布局：/replay-payloads[/agents/<agent>][/projects/<project>][/missions/<mission>][/threads/<thread>]/<invocation_id>.json——租户与用户身份进入调用方的MountView（按租户MountAlias重写），租户内子范围轴保留在路径中；
• 防御纵深：StoredReplayPayload包装器随负载持久化 scope，load时执行same_scope_owner检查——错误范围的查找表现为未知（Ok(None)），绝不泄漏他人负载；
• Write-once：save对已存在的 invocation_id 返回ReplayPayloadAlreadyExists（每次调用都新鲜铸造InvocationId，冲突是调用方不变式违例而非更新路径）；无删除方法，直到显式保留契约添加（数据库"Data safety"文档要求硬删除需产品/保留契约）。

九、Guardrails：防平行路径、防泄漏、防依赖倒置

CLAUDE.md 的 Guardrails 是维护膜不变式的核心纪律：

1. 单一权威路径：CapabilityHost是 invoke/resume/spawn 唯一的面向调用方权威路径；host-runtime 适配器、内建、自定义包与外部运行时都必须从该工作流进入，禁止添加平行的授权/审批分发路径。authorize决策，工作流模块只映射裁决；
2. 中立分发端口：使用CapabilityDispatcher端口，禁止对具体运行时 crate 添加普通依赖（BoundaryRule禁止ironclaw_host_runtime、ironclaw_secrets、ironclaw_network及所有 lane crate——膜绝不触及媒介执行，方向严格为host_runtime → capabilities）；
3. 信任感知授权：生产接线必须使用TrustAwareCapabilityDispatchAuthorizer且裁决来自策略推导的TrustDecision；禁止绕过信任上限的纯 grant 授权；
4. 不吸收进程 API：进程生命周期/结果属于ironclaw_processes::ProcessHost；
5. 失败顺序：授权拒绝或未支持/失败义务必须先于运行时分发、进程启动或审批租约认领失败；审批恢复在分发前验证并认领匹配的带指纹租约；
6. 义务实现外置：义务实现住在ironclaw_host_runtime；
7. 重放负载绝不外泄：ReplayPayloadStore记录只为宿主侧重分发而存在，不得进入模型、事件、错误、快照或日志；
8. Do Not Move In Here：平行分发路径、进程生命周期/结果 API、分发先于授权/义务/审批门控；以及错误、事件、快照、日志或文档中的密钥、原始宿主路径、后端错误细节与未脱敏的用户内容。

十、验证与测试矩阵

CLAUDE.md 的验证命令：

# 快速本地检查 cargo test -p ironclaw_capabilities # 依赖/API 变更后的边界检查 cargo test -p ironclaw_architecture_tests # 生产持久化行为变更时，维护 PostgreSQL 与 libSQL 对等测试

本 crate 自带 15 个契约测试（tests/），覆盖六个工作流与核心不变式：

• capability_host_contract.rs/capability_host_dispatcher_integration.rs：invoke 工作流与分发器集成；
• capability_host_approval_*、capability_host_persistent_approval_contract.rs、capability_host_github_comment_approval_contract.rs：审批门控与持久审批折叠；
• capability_host_auth_*系列：认证恢复与凭据富化；
• capability_host_spawn_contract.rs、capability_host_process_integration.rs：spawn 工作流与进程集成；
• capability_obligation_handler_contract.rs：义务缝契约；
• replay_payload_store_contract.rs：重放负载存储（CAS、write-once、错误范围隔离）；
• runtime_dispatch_contract.rs/runtime_dispatch_event_contract.rs：分发语义与#[traced_test]事件追踪断言；
• memory_profile_schema_refs_exist.rs、capability_boundary_contract.rs：schema 引用与依赖边界。

另有架构测试reborn_authorized_seal_ratchet强制"只有内核实现CapabilityAuthorizer"，与reborn_same_layer_edge_inventory固定七个阶段 crate 的层内依赖。

十一、配套契约文档与进一步阅读

CLAUDE.md "Start Here" 指向四份 Reborn 契约作为变更行为前的 truth source，均位于 docs/internal/reborn/contracts/：

• capability-access.md——授权契约：默认拒绝规则（未匹配 grant →Deny { MissingGrant }）、grant 效果覆盖不足 →Deny { PolicyDenied }、principal 匹配（tenant/user/project/mission/thread/extension）、租约背书授权与CapabilityLeaseStore端口签名；
• capabilities.md——能力描述符与效果语义；
• approvals.md——审批决议如何签发租约、恢复如何认领/消费；
• run-state.md——运行状态与调用记录。

配套工作规则见本 crate 的 README.md（章程、测得的依赖/消费方、门控）与 AGENTS.md（工作规则与 guardrails 的权威版本），以及内核家族总纲 crates/kernel/AGENTS.md。对于需要媒介执行机制（egress、secret staging、lane 适配器）的场景，请转向 ironclaw_host_runtime，其内置义务实现位于其 src/obligations/ 目录。

结语

ironclaw_capabilities用"一个 crate、一条路径、一个折叠"将能力调用的权威集中到内核的单一膜上：六个面向调用方的工作流共享同一个authorize决策折叠，唯一密封的Authorized见证承载六个冻结事实，中立的分发端口与阶段化的义务缝保证策略与执行解耦，宿主私有的重放负载存储则以 write-once、CAS、scope 防御纵深的方式守住原始工具输入的最后一块宿主侧领地。理解这套设计，是理解 IronClaw 安全模型如何落地为可测试、可维护的 Rust 架构的钥匙。

• 人工智能
• AI 应用
• 交互助手
• AI Agent