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

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

【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址: https://gitcode.com/gh_mirrors/iro/ironclaw

crates/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的端口进入内核，由内核中介处理，并且只把密封、脱敏后的结果交还给 loop；loop 声称的退出（exit）在真正提交任何持久化变更之前，还要对照宿主铸造（host-minted）的证据进行校验。也就是说，loop 的退出声明是“主张”而非“事实”。

这一信任故事在源码层面被机械地落实：ironclaw_agent_loop的依赖集被限定为 contracts 层三个 crate（ironclaw_common、ironclaw_host_api、ironclaw_loop_contracts），其余什么都不可依赖——所以“shipped loop 不受信任”不是评审约定，而是编译器强制的事实（见 ironclaw_agent_loop/README.md）。

四个 crate 的分工一览

ironclaw_agent_loop：密封的策略与执行器框架

这是整个系统中“设计上可以被整体替换、而不触碰任何特权部分”的构件。其公开表面包括：

• CanonicalAgentLoopExecutor（executor.rs）——规范执行器，内部有序生命周期阶段（DefaultExecutorPipeline保持 crate 内部私有）；
• AgentLoopPlanner（planner.rs）与default_planner.rs——公开的规划器服务，策略 trait 刻意不公开；
• family.rs 与families/——LoopFamily、LoopFamilyId、不可变单例式注册表LoopFamilyRegistry及内置家族工厂。

从源码可以看到内置家族身份常量：LoopFamilyId::DEFAULT（"default"）、SUBAGENT（"subagent"）、UNBOUND_DEFAULT（"unbound_default"）、UNBOUND_STRUCTURED（"unbound_structured"）。LoopFamilyId的校验规则非常明确：非空、最长 128 字节、仅允许小写 ASCII 字母、数字、_、-、:；注册表拒绝重复家族 ID（LoopFamilyRegistryError::DuplicateFamilyId）。家族还携带ComponentIdentity（id + 基于 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.rs）：HostManagedLoopCheckpointPort、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_llm（default-features = false），仅服务于模型网关适配器，属于章程特许而非漂移。

ironclaw_turn_runner：可信的控制面适配器

ironclaw_turn_runner是内核工作声明与 loop 用户态之间的可信适配器。它把ProcessKind::AgentTurn执行器注册进内核的进程主管（依赖反转：内核定义端口，本 crate 注册进去），为每个已声明运行只交付作用域内的端口，并把 loop 声称的退出交给回合内核的退出应用器（loop_exit_applier.rs）校验——它自己从不决定持久化。

关键公开表面包括：

• RebornTurnRunExecutor（turn_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-S；
• trace_capture.rs——WS6 追踪捕获拆分的 runner 半边。

值得注意的实现细节（来自 turn_scheduler.rs）：回合运行的最大连续心跳失败数为TURN_RUN_MAX_CONSECUTIVE_HEARTBEAT_FAILURES = 8，但heartbeat_failure_budget_within_lease会按配置的心跳间隔把预算收敛到租约 TTL 内能容纳的值——在默认 15 秒间隔下该预算为 3；MAX_HEARTBEAT_INTERVAL_WITHIN_LEASE保证第一次失败仍落在进程租约 TTL 内，从而让“放弃”始终是 worker 自己的决策，而非恢复扫描发现的租约过期。

ironclaw_hooks：最外层的信任分级钩子中间件

ironclaw_hooks是家族声明的Loop*Port装饰器链的最外层：每次端口调用在到达 runner 的组合与loop_host的内核向基座之前，先经过策略检查与审计。它拥有：

• HookDispatcher（dispatch/）与按信任等级区分的安装器（install_builtin_*/install_trusted_*/install_installed_*）——钩子实现进入系统的唯一公开路径，错误等级的实现在类型层面不可铸造；
• 四个由来源固定、钩子自身不可声明的信任类：builtin（内建）/ trusted（可信）/ installed（已安装）/ self-authored（自著）；
• 密封的决策汇 trait：Privileged*/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的架构测试逐一钉死的：

1. Layer matrix（层矩阵）：四个 crate 都声明layer = "loops"；loop/可向下依赖（contracts → kernel），永不依赖products或app。执行：cargo test -p ironclaw_architecture_tests --test reborn_dependency_boundaries reborn_workspace_crates_declare_layers_and_follow_layer_matrix。
2. BoundaryRules：ironclaw_agent_loop是 contracts-only（特殊矩阵规则）；ironclaw_hooks禁止运行时适配器与分发器具体类型。执行：cargo test -p ironclaw_architecture_tests --test reborn_dependency_boundaries reborn_crate_dependency_boundaries_hold。
3. 密封策略是家族风格（house style）：新 loop 行为是ironclaw_agent_loop中密封家族与规划器组合背后的新策略，绝不是在规范执行器里加分支（strategies/目录即证据）。
4. 单一声明的Loop*Port装饰器链：ironclaw_loop_host实现每个端口的内核向基座；ironclaw_turn_runner把基座组合成每个已声明运行的具体宿主（顺序是 runner 的）；ironclaw_hooks在最外层包装组合后的宿主。工作区内没有其他 crate 实现Loop*Port——新端口实现必须以同一变更加入这条声明链，绝不作为并行的、未声明的装饰器。端口定义只存在于ironclaw_loop_contracts，每个端口只有一个导入路径。执行：reborn_loop_port_location_scan.rs。
5. WS3 剥落物留在 shed 里：模型网关、模型路由词汇、驱动-宿主端口适配器、工具披露都在ironclaw_loop_host，绝不允许回到 runner。执行：reborn_runner_sheds.rs。
6. 提示词内容归 loop 层：loop 层提示词住在ironclaw_loop_host/prompts/，永不进入组合根。执行：reborn_composition_boundaries composition_root_embeds_no_prompt_content。
7. 解散端口的 crate 边界以模块相等性存续：loop_host的skill_activation/模块只能触达旧ironclaw_first_party_extension_portscrate 能触达的东西。执行：reborn_dependency_boundaries dissolved_ports_module_keeps_its_crate_boundary。
8. 同层边被清点而非免费：执行：reborn_same_layer_edge_inventory.rs。
9. 第五个 crate 必须“挣得”：必须给出它在 claim-to-execution 路径中的自有角色、自己的信任封印或多实现端口（见docs/internal/reborn/target-architecture/families/loop.md）；仅凭便利不构成理由。

跨越家族边界：唯一的出入口

• 向上到ironclaw_composition（app）：唯一把本家族组装进部署的 crate；它调用 runner/loop-host 工厂并注册执行器。本家族永不反向依赖它。
• 向下到contracts/ironclaw_loop_contracts：要改端口的形状就去这里。定义住在 contracts，实现住在本家族。ironclaw_loop_contracts/src/lib.rs 的文档注释写得很清楚：它是“词汇与端口”——trait 与 DTO，不执行任何事、不持久化任何事、不决定任何事；回合内核ironclaw_turns实现内核侧并校验这些契约，方向从不反转。
• 向下到kernel/：ironclaw_turns（回合准入、退出校验）、ironclaw_processes（claim/lease/journal 边）、ironclaw_host_runtime与ironclaw_capabilities（端口适配器包装的中介服务）。
• 横向到product/：永不。产品消费这里运行的投影结果；反向边（assistant → loop_host，6 文件 / 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