人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载导读本文以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 依赖并消费五个阶段 crateironclaw_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归纳如下模块拥有的工作流绝不包含invoke工作流 1 —invoke_json全新内联调用授权决策本身authorize共享折叠信任、运行时策略、持久审批与Authorized密封任何工作流形态approval_resume工作流 2 —resume_json分发尾部归resume_supportauth_resume工作流 3、4 —auth_resume_json与decline_auth_json分发尾部spawn_resume工作流 5 —resume_spawn_json内联分发spawn工作流 6 —spawn_json及其私有authorize_spawn折叠内联分发resume_support三个恢复工作流汇聚的 preflight/授权/分发尾部工作流前奏obligation_seams围绕分发做出的 prepare/complete/abort 调用义务实现error_mapping把外部错误与裁决重命名进本 crate 词汇任何策略决策三条规则保证宪章不被破坏mod.rs 文档注释工作流模块拥有自己的前奏preamble绝不拥有尾部tail——一旦两个恢复工作流同意某个步骤该步骤就归属resume_supportauthorize决策工作流只映射裁决——某个工作流若长出属于自己的策略分支就是夺取了膜本应集中持有的权威本文件只持有状态与词汇不持有行为——结构体、CapabilityAuthorizer密封、跨工作流的请求/折叠类型与构造器集中于此。所有子模块都是私有的且每个工作流都是CapabilityHost上的固有方法inherent method因此调用方仍然只看到一条路径不允许为子模块添加pub use。每个文件必须保持在 1,500 行 ARCH-SPRAWL 阈值之下——这次拆分正是为了撤销融合大文件此前携带的arch-exempt: large_file豁免重新融合会触发 pre-commit-safety.sh 检查。三、CapabilityHost单一权威路径与依赖注入组装CapabilityHostmod.rs是一个泛型结构体唯一携带的具体类型是分发器D: CapabilityDispatcher以D借用其余全部是 trait object 端口pub struct CapabilityHosta, 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: Optiona dyn ProcessInvocationStatePort, approval_requests: Optiona dyn ApprovalRequestStorePort, capability_leases: Optiona dyn CapabilityLeaseStorePort, process_manager: Optiona dyn ProcessManager, obligation_handler: Optiona 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持久化审批提示审批路径必需缺失时返回ApprovalStoreMissingwith_capability_leases消费已批准的租约resume_json必需with_process_manager派生长时调用spawn_json必需缺失返回ProcessManagerMissingwith_obligation_handler满足 allow 裁决的义务缺失时非空义务 fail-closed。唯一的制造地点是ironclaw_host_runtimeREADME 依赖表明确ironclaw_host_runtimeconstructs and drives the membrane — the single construction site。3.1 密封见证只有本 crate 能铸造impl CapabilityAuthorizer for CapabilityHostmod.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 记录做状态迁移再返回错误上下文校验request.context.validate()失败 →AuthorizationDenied { InternalInvariantViolation }指纹invocation_fingerprint_for_kind(Dispatch, ...)计算调用指纹供审批重放比对能力解析前置registry.get_capability查不到 →UnknownCapability且不创建调用记录保持 host_runtime 删除的前置检查行为描述符富化enrich_invocation_descriptor——仅对builtin.shell生效将调用方显式选择的、manifest 声明了placeholder_env的扩展凭据合并进冻结描述符详见下文 4.1调用记录 startinvocation_state.start(...)信任评估内核计算evaluate_trust调用evaluate_invocation_trust(registry, trust_policy, capability_id)。信任是内核在折叠内计算的而不是调用方盖章传入的字段CLAUDE.md 强调 trust is computed here rather than received as a caller-stamped field运行时策略规划enforce_runtime_policy调用ironclaw_runtime_policy::plan_capability规划器拒绝 → 模型可见的AuthorizationDenied对应runtime_policy_failure凭据预检policy_facts.credential_presence(...)——缺失凭据以AuthorizationRequiresAuth呈现先于审批决策保证人类审批永远不会消耗给一个尚无法执行的动作。Indeterminate瞬时存储故障跳过预检因为分发期的义务检查是兜底执行者且故障不应烧掉用户的一次认证交互。端口只返回事实内核负责映射为裁决持久审批折叠apply_persistent_approval——仅对允许持久审批的权限模式PermissionMode::Allow | AskDeny不可升级见 authorize.rs把候选 grant 逐个注入后重新授权首个翻转为Allow的 grant 被采纳注入上下文避免再次拉起审批闸门。返回采纳 grant 的constraints.expires_at作为密封截止时间的冻结事实信任感知授权authorizer.authorize_dispatch_with_trust(authorize_context, descriptor, estimate, trust_decision)产生三叉裁决Decision::Allow { obligations }→prepare_obligations(Invoke, ...)准备义务随后seal_authorization铸造见证返回AuthorizeFold::AuthorizedDecision::Deny { reason }→ 记录 fail 为AuthorizationDenied返回AuthorizeFold::Deniedreason 是模型可见的策略裁决Decision::RequireApproval { request }→ 校验审批请求与调用匹配approval request 与 invocation 指纹持久化 pending 审批approval_requests.save_pending并把调用记录转移到block_approval持久化失败时回滚discard_pending返回AuthorizeFold::Blocked。审批请求缺失任一 store 均返回ApprovalStoreMissing。4.1 shell 凭据富化显式选择的凭据才生效enrich_invocation_descriptorauthorize.rs只为builtin.shell能力工作从输入中解析出shell_credential_contexts要求每个上下文都是活跃扩展且其包信任达到 privileged 级别再收集其中声明了placeholder_env的运行时凭据需求同 handle 冲突声明会拒绝任何上下文未声明 shell 凭据同样拒绝。仅当运行时策略的后端是UserSandbox时才允许。富化后的描述符追加EffectKind::UseSecret冻结的描述符随后驱动审批、凭据暂存与代理策略——普通命令文本永远不会隐式获得凭据。4.2 密封见证六个冻结事实seal_authorizationauthorize.rs铸造Authorized见证将六个权威冻结事实封入其中actor在膜处密封绝不回退到user_id——无 actor 的上下文系统服务/一次性调用密封为Actor::System自身类别lane从描述符 runtime kind 解析System运行时没有不可信执行 laneNone不在膜处密封origin来自 ingress 盖章的上下文事实只盖了run_id的上下文会为过渡兼容重建LoopRuninvocationactivity_id、capability、input、scope、actor、origin、estimate、correlation_id、process_id、parent_process_idmounts / reservation折叠产生的真实挂载与资源预留绝不合成占位值deadline取最短命的冻结事实witness_deadline取各候选过期时间的最小值无冻结事实时回退到 5 分钟默认 TTLWITNESS_DEFAULT_TTL: chrono::Duration::minutes(5)authorize.rs保证持有的见证不会活得比证明它的事实更久。调用方如invoke_json若在允许后拿不到见证会先abort_obligations清理再返回错误MissingAuthorization或AuthorizationExpired见 invoke.rs。五、六个工作流的入口invoke / resume / auth-resume / decline-auth / spawn-resume / spawnCLAUDE.md 指出invoke、approval_resume、auth_resume、spawn_resume、spawn各拥有一个面向调用方的工作流authorize拥有它们全部汇聚的单一授权折叠resume_support拥有三个恢复工作流共享的尾部。以工作流 1invoke_jsoninvoke.rs为例完整生命周期为组装InvocationInput调用self.authorize(request)按AuthorizeFold三态映射Authorized→ 解包见证Denied→ 返回AuthorizationDenied { reason }Blocked→ 返回AuthorizationRequiresApprovalself.dispatcher.dispatch_json(*authorized)分发分发失败 →abort_obligations清理、富化凭据需求错误enrich_dispatch_error_credential_requirements、invocation 记录迁移complete_dispatch_obligations完成后置义务失败 → 以空 outcome 中止义务并 fail 记录成功 →complete_invocation_after_side_effect完成记录返回CapabilityDispatchResult。三个恢复工作流共享的resume_support尾部处理三种互斥的租约状态ResumedLeaseState见 mod.rsPendingClaimresume_json在授权返回Allow之后才认领一次性Active租约Deny 时租约保持 Active、AlreadyClaimedauth_resume_json复用先前已 Claimed 的租约不重复拉起审批、NoPriorLeaseauth_resume_json中approval_request_id为 None 的情况。审批恢复必须先验证并认领匹配的带指纹租约再分发Guardrails 规则。PendingClaimAfterAuth把冻结的 grant 过期时间随规格携带mod.rs因为密封在认领之前铸造过期时间不能从尚未认领的租约中读回。BlockedResumeKindmod.rs区分两种被阻断的恢复路径审批恢复/派生恢复以BlockedApproval记录为键并比较approval_request_id认证恢复以BlockedAuth记录为键且不比较approval_request_id其block_auth转换把持久化的 id 清为None。六、RuntimeDispatcher密封见证的窄分发器RuntimeDispatcherdispatch.rs是唯一的生产CapabilityDispatcher实现它接收已授权的密封见证把请求路由到预绑定的 lane 适配器并拒绝任何见证与绑定 lane 不匹配的请求DispatchError::MissingRuntimeBackend。核心机制ToolResolver按能力 id 解析预绑定绑定TOOL-1。解析是快照形态的查找——绑定在激活/注册时构建绝不做每次调用的包/runtime-kind 选择未知 id 返回None分发在任何适配器工作前失败TOOL-2ResolvedCapability提供者扩展 id宿主内建解析为合成builtin提供者、runtime kind、以及Arcdyn BoundCapabilityAdapterBoundCapabilityAdapter接收原样的已授权CapabilityDispatchRequest——包、描述符、执行计划、文件系统、端口全部在绑定构建时捕获实现不得执行面向调用方的授权或审批决议且只能上浮脱敏的DispatchError类别ChainToolResolverfirst-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_runtimeGuardrails 明确内置义务实现住在crates/kernel/ironclaw_host_runtime/src/obligations/绝不放在本 crate。阶段CapabilityObligationPhase::{Invoke, Resume, Spawn}obligations.rs请求类型CapabilityObligationRequest副作用前、CapabilityObligationCompletionRequest成功分发后、CapabilityObligationAbortRequest失败清理携带 prepared outcome产出CapabilityObligationOutcome { mounts: OptionMountView, resource_reservation: OptionResourceReservation }失败类别稳定脱敏的CapabilityObligationFailureKind::{Audit, Mount, Network, Output, Resource, Secret}错误CapabilityObligationError::{Unsupported, AuthRequired, Failed}变体刻意避免原始输入/输出默认行为satisfy必须实现prepare默认委托satisfy并返回空 outcomeabort默认空操作complete_dispatch默认检查post_dispatch_obligationsAuditAfter、RedactOutput、EnforceResourceCeiling、EnforceOutputLimit存在未支持的后置义务时返回Unsupportedobligations.rs。工作流调用点authorize折叠内在Allow后prepare_obligations(Invoke, ...)invoke_json分发失败时abort_obligations、成功后complete_dispatch_obligationsspawn路径对应Spawn阶段。八、宿主私有重放负载存储ReplayPayloadStoreReplayPayloadStorereplay_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-closedCasUnsupported→Backend错误每个条目带RecordKind标签replay_payload_record使纯字节后端如DiskFilesystem首次写入即被拒绝路径布局/replay-payloads[/agents/agent][/projects/project][/missions/mission][/threads/thread]/invocation_id.json——租户与用户身份进入调用方的MountView按租户MountAlias重写租户内子范围轴保留在路径中防御纵深StoredReplayPayload包装器随负载持久化 scopeload时执行same_scope_owner检查——错误范围的查找表现为未知Ok(None)绝不泄漏他人负载Write-oncesave对已存在的 invocation_id 返回ReplayPayloadAlreadyExists每次调用都新鲜铸造InvocationId冲突是调用方不变式违例而非更新路径无删除方法直到显式保留契约添加数据库Data safety文档要求硬删除需产品/保留契约。九、Guardrails防平行路径、防泄漏、防依赖倒置CLAUDE.md 的 Guardrails 是维护膜不变式的核心纪律单一权威路径CapabilityHost是 invoke/resume/spawn 唯一的面向调用方权威路径host-runtime 适配器、内建、自定义包与外部运行时都必须从该工作流进入禁止添加平行的授权/审批分发路径。authorize决策工作流模块只映射裁决中立分发端口使用CapabilityDispatcher端口禁止对具体运行时 crate 添加普通依赖BoundaryRule禁止ironclaw_host_runtime、ironclaw_secrets、ironclaw_network及所有 lane crate——膜绝不触及媒介执行方向严格为host_runtime → capabilities信任感知授权生产接线必须使用TrustAwareCapabilityDispatchAuthorizer且裁决来自策略推导的TrustDecision禁止绕过信任上限的纯 grant 授权不吸收进程 API进程生命周期/结果属于ironclaw_processes::ProcessHost失败顺序授权拒绝或未支持/失败义务必须先于运行时分发、进程启动或审批租约认领失败审批恢复在分发前验证并认领匹配的带指纹租约义务实现外置义务实现住在ironclaw_host_runtime重放负载绝不外泄ReplayPayloadStore记录只为宿主侧重分发而存在不得进入模型、事件、错误、快照或日志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.rsinvoke 工作流与分发器集成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.rsspawn 工作流与进程集成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.rsschema 引用与依赖边界。另有架构测试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【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载相关推荐IronClaw 能力调用膜Capability Membraneironclaw_capabilities 的六工作流授权折叠与密封见证设计IronClaw 能力调用膜Capability Membrane ironclaw_capabilities 的六工作流授权折叠与密封见证设计 导读 本人工智能AI 应用交互助手AI AgentIronClaw 的可替换 Loop 用户态端口即膜、永不成为权威的四个 Crates 架构解析IronClaw 的可替换 Loop 用户态端口即膜、永不成为权威的四个 Crates 架构解析 导读 本文围绕 crates/loop/CLAUDE.md人工智能AI 应用交互助手AI AgentIronClaw substrates 家族解析特权机制、永非授权的七层安全底座IronClaw substrates 家族解析特权机制、永非授权的七层安全底座 IronClaw 是一个聚焦隐私、安全与可扩展性的 Agent OS其分层人工智能AI 应用交互助手AI Agent上一篇10倍提速Apache Arrow数据压缩实战LZ4与ZSTD深度评测下一篇CocoaAsyncSocket Swift终极指南如何在Swift项目中轻松使用Objective-C网络库创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考