IronClaw 的 Loop 家族：可替换的 Agent 用户态与“端口即膜”的信任架构

IronClaw 的 Loop 家族可替换的 Agent 用户态与“端口即膜”的信任架构【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址: https://gitcode.com/gh_mirrors/iro/ironclawcrates/loop/是 IronClaw 中承载 Agent 行为的核心层级它让“一个回合接下来做什么”这套逻辑可以在不触碰任何特权代码的前提下被整体替换同时通过ironclaw_loop_contracts端口把每一次特权效果交给内核中介。阅读本文你将掌握这一家族的四个 crate 的分工、信任模型shipped loop 不因随产品发布而被信任、单一声明的Loop*Port装饰器链以及由架构测试强制执行的依赖边界规则。Loop 家族是什么可整体替换的 Agent 行为层在 IronClaw 的分层设计中crates/loop/是loop-hosting tier循环托管层它既包含可以被整体替换、而无需触碰任何特权部分的 Agent 行为也包含把行为连接到内核的适配器。家族共 4 个 crate依赖方向为“向下”contracts → kernel从不依赖products/或app/。核心信任故事the loop trust story一个随产品发布的 loop不会仅仅因为它随产品发布就被信任。这个家族中的任何代码都无法构造 capability grant能力授予、approval审批、lease租约或 secret机密。每一个特权效果都必须跨越ironclaw_loop_contracts的端口进入内核由内核中介处理并且只把密封、脱敏后的结果交还给 looploop 声称的退出exit在真正提交任何持久化变更之前还要对照宿主铸造host-minted的证据进行校验。也就是说loop 的退出声明是“主张”而非“事实”。这一信任故事在源码层面被机械地落实ironclaw_agent_loop的依赖集被限定为 contracts 层三个 crateironclaw_common、ironclaw_host_api、ironclaw_loop_contracts其余什么都不可依赖——所以“shipped loop 不受信任”不是评审约定而是编译器强制的事实见 ironclaw_agent_loop/README.md。四个 crate 的分工一览Crate职责一句话何时该看它ironclaw_agent_loop密封的策略与执行器框架loop 家族、规划器、规范执行器、可恢复状态你要改变一个回合决定接下来做什么ironclaw_loop_host基于内核服务的每一个Loop*Port的基座实现含模型网关与工具披露你要把内核/领域服务适配成 loop 端口ironclaw_turn_runnerAgent 回合执行器、驱动注册表与 loop-host 工厂——内核工作声明与 loop 用户态之间的可信适配器你要改变一次已声明运行如何获得驱动、端口或退出处置ironclaw_hooks信任分级trust-tiered的钩子中间件为每次Loop*Port调用附加策略与审计你要改变钩子信任类、决策汇sink或钩子引擎ironclaw_agent_loop密封的策略与执行器框架这是整个系统中“设计上可以被整体替换、而不触碰任何特权部分”的构件。其公开表面包括CanonicalAgentLoopExecutorexecutor.rs——规范执行器内部有序生命周期阶段DefaultExecutorPipeline保持 crate 内部私有AgentLoopPlannerplanner.rs与default_planner.rs——公开的规划器服务策略 trait 刻意不公开family.rs 与families/——LoopFamily、LoopFamilyId、不可变单例式注册表LoopFamilyRegistry及内置家族工厂。从源码可以看到内置家族身份常量LoopFamilyId::DEFAULTdefault、SUBAGENTsubagent、UNBOUND_DEFAULTunbound_default、UNBOUND_STRUCTUREDunbound_structured。LoopFamilyId的校验规则非常明确非空、最长 128 字节、仅允许小写 ASCII 字母、数字、_、-、:注册表拒绝重复家族 IDLoopFamilyRegistryError::DuplicateFamilyId。家族还携带ComponentIdentityid 基于 blake3 的ComponentDigest用于对回放安全相关的组件做内容寻址标识。ironclaw_agent_loop的依赖集仅限 contracts 层3 个依赖因此不依赖任何 substrate、domain、kernel、lane、extension、product 或 app crate它从不“看到”驱动只消费自己的执行器契约由ironclaw_turn_runner的PlannedDriver把它适配到AgentLoopDriver契约上。ironclaw_loop_host内核服务的端口基座实现这是唯一被许可在同一个模块里同时持有Loop*Port类型与内核句柄的 crate也是家族中唯一获得特许PROPOSAL §6.7.2 例外的供应商客户端所在之处——模型网关适配器model_gateway.rs、thread_resolving_model_gateway.rs及 model_routes.rs 中的ModelRoute、ModelSlot、ModelRouteResolver策略词汇。WS3 剥落sheds后它还拥有能力端口及能力表面过滤capability_port.rs、capability_surface_filter.rs渐进式工具披露progressive tool disclosure目录/选择器、可延迟的LoopCapabilityPort装饰器、REBORN_TOOL_DISCLOSURE开关tool_disclosure*.rs输入队列、取消端口、压缩compaction、检查点存储、预算会计budget_accountant.rs、子代理生成端口驱动-宿主端口适配器driver_host_port_adapters.rsHostManagedLoopCheckpointPort、HostManagedLoopProgressPort、NoExtraLoopInputPort提示上下文构建器identity_context.rs、skill_context.rs与skill_activation/WS8 中解散的ironclaw_first_party_extension_portscrate 以模块形式存续loop 层的系统提示词内容资产prompts/default_system.md、tool_disclosure_protocol.md、self_knowledge.md、benchmarking_mode.md、scheduled_trigger_mode.md等经system_prompt_assets.rs导出组合根composition root只负责装配与开机时向磁盘SYSTEM.md的播种绝不嵌入提示词文本。该 crate 唯一的供应商客户端依赖是ironclaw_llmdefault-features false仅服务于模型网关适配器属于章程特许而非漂移。ironclaw_turn_runner可信的控制面适配器ironclaw_turn_runner是内核工作声明与 loop 用户态之间的可信适配器。它把ProcessKind::AgentTurn执行器注册进内核的进程主管依赖反转内核定义端口本 crate 注册进去为每个已声明运行只交付作用域内的端口并把 loop 声称的退出交给回合内核的退出应用器loop_exit_applier.rs校验——它自己从不决定持久化。关键公开表面包括RebornTurnRunExecutorturn_run_executor.rs——注册给进程主管的执行器turn_scheduler.rs 是通用主管之上的 agent-turn投影#6696而非独立调度器DriverRegistry与两个生产驱动PlannedDriver适配ironclaw_agent_loop与 text_loop_driver.rs最小的受支持行为二者之间的回退必须是显式的 profile/readiness 决策绝不静默loop_driver_host.rs 与runtime.rs——loop-host 工厂按章程在此组合每个已声明运行的端口集与能力端口装饰器链的顺序subagent/await_edge/——await-edge 机制store 是对ironclaw_processes::ProcessDependencyPort的纯投影被tests/integration/subagent_await_edge.rs::runner_await_edge_is_a_projection_over_process_dependencies钉死在集成层而resolver 作为真正的 loop 层职责留在这里所有者恢复、untrusted-text 栅栏后的子转录物物化、批门放行与父回合的 exactly-once 恢复、BlockedDependentRunGate恢复策略——见 PROPOSAL §12.13 D-Strace_capture.rs——WS6 追踪捕获拆分的 runner 半边。值得注意的实现细节来自 turn_scheduler.rs回合运行的最大连续心跳失败数为TURN_RUN_MAX_CONSECUTIVE_HEARTBEAT_FAILURES 8但heartbeat_failure_budget_within_lease会按配置的心跳间隔把预算收敛到租约 TTL 内能容纳的值——在默认 15 秒间隔下该预算为 3MAX_HEARTBEAT_INTERVAL_WITHIN_LEASE保证第一次失败仍落在进程租约 TTL 内从而让“放弃”始终是 worker 自己的决策而非恢复扫描发现的租约过期。ironclaw_hooks最外层的信任分级钩子中间件ironclaw_hooks是家族声明的Loop*Port装饰器链的最外层每次端口调用在到达 runner 的组合与loop_host的内核向基座之前先经过策略检查与审计。它拥有HookDispatcherdispatch/与按信任等级区分的安装器install_builtin_*/install_trusted_*/install_installed_*——钩子实现进入系统的唯一公开路径错误等级的实现在类型层面不可铸造四个由来源固定、钩子自身不可声明的信任类builtin内建/ trusted可信/ installed已安装/ self-authored自著密封的决策汇 traitPrivileged*/Restricted*门gate与变异器mutator汇、ObserverSink观察者汇覆盖全部 loop 端口的HookedLoop*Port装饰器middleware/声明式谓词语言与求值器predicate/以及libsql_backend/postgres_backend两个持久化后端完整但当前未接线组合根硬编码内存后端见 ADR 0004基于ironclaw_wasm_limiter的沙箱化 WASM 钩子引擎wasm/。其安全语义非常关键门与变异器决策失败即关闭fail closed观察者与效果决策失败即隔离fail isolated并附脱敏审计违反自身协议的钩子在该运行剩余时间内被禁止行动slot 中毒且分发器按宿主构建全新铸造因此中毒不会泄漏到下一轮运行见tests/integration/hooks.rs::poisoned_hook_slot_does_not_leak_into_the_next_run。ironclaw_hooks永不依赖ironclaw_turns——这正是设计要点回合准入内核不依赖钩子钩子也不再命名内核。什么永远不属于这个家族crates/loop/AGENTS.md明确列出的禁区任何权威决策——信任、授权、审批、资源预留、调度。这些是内核家族的行为crates/kernel/ironclaw_{trust,authorization,approvals,resources,capabilities}。调度策略与生命周期权威——claim、lease、heartbeat、recovery 属于内核的进程日志crates/kernel/ironclaw_processes。自 #6696 起runner 的turn_scheduler.rs只是通用ProcessSupervisor之上的 agent-turn 投影内核仅通过注册的ProcessKind::AgentTurn执行器端口触达本家族。产品工作流——绑定、幂等性、命令语法、投递语义都是crates/product/ironclaw_assistant的产品读取已声明运行的投影结果绝不深入本家族取行为。任何供应商协议——crates/extensions/packages/*与获准的供应商表面拥有供应商命名权。家族中唯一的供应商客户端是ironclaw_loop_host的模型网关适配器章程特许PROPOSAL §6.7.2且没有其他模块可以触达供应商客户端——ironclaw_turn_runner刻意不再命名ironclaw_llm架构测试reborn_runner_llm_wiring_is_isolated守护这一点。裸句柄——原始 secret、文件系统句柄、网络客户端或进程句柄。端口只交付作用域化、被中介的访问。可恢复状态中的原始内容——状态只持有引用、游标、计数器、版本与安全摘要绝不存放原始提示词、原始模型输出、工具参数、secret、宿主路径或供应商诊断见ironclaw_agent_loop/src/state/与ironclaw_loop_contracts的RedactedCheckpointPayload。规则以及谁来强制执行家族规则不是口头约定而是由crates/app/ironclaw_architecture_tests的架构测试逐一钉死的Layer matrix层矩阵四个 crate 都声明layer loopsloop/可向下依赖contracts → kernel永不依赖products或app。执行cargo test -p ironclaw_architecture_tests --test reborn_dependency_boundaries reborn_workspace_crates_declare_layers_and_follow_layer_matrix。BoundaryRulesironclaw_agent_loop是 contracts-only特殊矩阵规则ironclaw_hooks禁止运行时适配器与分发器具体类型。执行cargo test -p ironclaw_architecture_tests --test reborn_dependency_boundaries reborn_crate_dependency_boundaries_hold。密封策略是家族风格house style新 loop 行为是ironclaw_agent_loop中密封家族与规划器组合背后的新策略绝不是在规范执行器里加分支strategies/目录即证据。单一声明的Loop*Port装饰器链ironclaw_loop_host实现每个端口的内核向基座ironclaw_turn_runner把基座组合成每个已声明运行的具体宿主顺序是 runner 的ironclaw_hooks在最外层包装组合后的宿主。工作区内没有其他 crate 实现Loop*Port——新端口实现必须以同一变更加入这条声明链绝不作为并行的、未声明的装饰器。端口定义只存在于ironclaw_loop_contracts每个端口只有一个导入路径。执行reborn_loop_port_location_scan.rs。WS3 剥落物留在 shed 里模型网关、模型路由词汇、驱动-宿主端口适配器、工具披露都在ironclaw_loop_host绝不允许回到 runner。执行reborn_runner_sheds.rs。提示词内容归 loop 层loop 层提示词住在ironclaw_loop_host/prompts/永不进入组合根。执行reborn_composition_boundaries composition_root_embeds_no_prompt_content。解散端口的 crate 边界以模块相等性存续loop_host的skill_activation/模块只能触达旧ironclaw_first_party_extension_portscrate 能触达的东西。执行reborn_dependency_boundaries dissolved_ports_module_keeps_its_crate_boundary。同层边被清点而非免费执行reborn_same_layer_edge_inventory.rs。第五个 crate 必须“挣得”必须给出它在 claim-to-execution 路径中的自有角色、自己的信任封印或多实现端口见docs/internal/reborn/target-architecture/families/loop.md仅凭便利不构成理由。跨越家族边界唯一的出入口向上到ironclaw_compositionapp唯一把本家族组装进部署的 crate它调用 runner/loop-host 工厂并注册执行器。本家族永不反向依赖它。向下到contracts/ironclaw_loop_contracts要改端口的形状就去这里。定义住在 contracts实现住在本家族。ironclaw_loop_contracts/src/lib.rs 的文档注释写得很清楚它是“词汇与端口”——trait 与 DTO不执行任何事、不持久化任何事、不决定任何事回合内核ironclaw_turns实现内核侧并校验这些契约方向从不反转。向下到kernel/ironclaw_turns回合准入、退出校验、ironclaw_processesclaim/lease/journal 边、ironclaw_host_runtime与ironclaw_capabilities端口适配器包装的中介服务。横向到product/永不。产品消费这里运行的投影结果反向边assistant → loop_host6 文件 / 4 seam是产品侧被测量的债务PROPOSAL §6.10.1不是loop → products的许可证。一处端口契约、多条实现路径模型与提示词边界的落地把上述设计落到一次真实调用上ironclaw_agent_loop的规划器/执行器只依赖loop_contracts的LoopModelPort、LoopPromptPort、LoopCapabilityPort等接口ironclaw_loop_host提供这些接口的内核向实现模型网关、提示词组装、能力表面ironclaw_turn_runner按 claim 组合装饰链ironclaw_hooks在链最外层包裹策略与审计。于是“换一个行为”等于换ironclaw_agent_loop里的策略“换一个供应商”等于换loop_host里的网关适配器而整个过程中没有任何一环需要触碰特权句柄——这正是crates/loop/AGENTS.md开篇那句话的全部含义端口是膜从不成为权威。进一步阅读设计记录 docs/internal/reborn/target-architecture/families/loop.md含 PROPOSAL §6.7.1–6.7.4、§8、§12.13 D-S 的指引四个 crate 各自的 README.md 与工作规则 AGENTS.md架构测试位于 crates/app/ironclaw_architecture_tests/tests/reborn_dependency_boundaries.rs、reborn_loop_port_location_scan.rs、reborn_runner_sheds.rs、reborn_same_layer_edge_inventory.rs、reborn_composition_boundaries.rs。【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址: https://gitcode.com/gh_mirrors/iro/ironclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考