人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载IronClaw 的ironclaw_agent_loopcrate 是 Reborn 架构中可整体替换的密封循环框架sealed loop framework负责定义循环家族loop family身份与注册表、规划器planner及其密封策略组合、带有序生命周期阶段的规范执行器canonical executor以及可恢复的执行状态。读完本文你将理解该 crate 的职责边界、contracts-only 依赖约束如何由编译器强制保证掌握规范执行器的每个生命周期阶段、十大密封策略轴decision axis与 typed state slot 的设计原理以及在此框架中添加新行为的规范姿势与验证命令。一、先定位ironclaw_agent_loop 在 IronClaw 中的角色按 CLAUDE.md 的定位本 crate 属于loop层layer loops是loop-hosting 层级中唯一持有决定一个 turn 下一步做什么这一职责的构件。它在整个系统中扮演的角色可概括为一句话它定义了循环框架的状态与策略契约且是系统中唯一设计为可被整体替换而不触碰任何特权构件的产物。从 README.md 可以确认其边界语义什么时候使用它当你需要改变一个 turn 下一步决定做什么时——即新增一个策略、一个循环家族、一个执行器生命周期阶段或一个类型化状态槽位。什么时候不要用它把宿主服务适配到循环端口用ironclaw_loop_host把内核的工作声明桥接到驱动用ironclaw_turn_runner对端口调用的策略/审计包装用ironclaw_hooks。该 crate 的公开表面public surface非常克制只有四块公开构件源码位置说明CanonicalAgentLoopExecutorexecutor.rs规范执行器DefaultExecutorPipeline与各阶段类型保持 crate 内部可见AgentLoopPlannerdefault_plannerplanner.rs公开规划器服务策略 trait 刻意不公开LoopFamily/families/family.rs循环家族、家族 ID、注册表、内置家族工厂state.rs/state/state.rs可恢复状态只存引用、游标、计数器、版本号与安全摘要这种公开表面极小、内部机制密封的设计是整个框架安全性的基石下游 crate 可以持有并解析一个家族但永远无法窥探或篡改其规划器内部策略槽。二、contracts-only 依赖边界把信任故事变成编译器事实CLAUDE.md 的 Boundaries 一节是整个 crate 最重要的一条规则原文明确写道Dependencies are contracts-tier only:ironclaw_common,ironclaw_host_api,ironclaw_loop_contracts.也就是说本 crate 的全部普通依赖只有三个 contracts 层 crate另有async-trait、blake3、serde、tokio、tracing等通用基础库。从 Cargo.toml 可以验证这一点工作区内部依赖恰好是ironclaw_common、ironclaw_host_api、ironclaw_loop_contracts三个任何 substrate、domain、kernel、lane、product 或 app crate 都不允许出现在依赖列表里。这条约束不是靠 review 约定而是由架构测试机械地强制执行的。在 reborn_dependency_boundaries.rs 中有专门的userland ruleif crate_name ironclaw_agent_loop *dependency_layer ! contracts { violations.push(format!( ironclaw_agent_loop userland rule allows only contracts-layer normal \ dependencies, but it depends on {dependency_name} ({dependency_layer}) )); }对应验证命令cargo test -p ironclaw_architecture_tests --test reborn_dependency_boundaries reborn_crate_dependency_boundaries_hold与之配套的另外两条不变式invariants在 README.md 中列出本 crate 不定义任何Loop*Port端口定义只存在于ironclaw_loop_contracts每个端口只有一条导入路径--test reborn_loop_port_location_scan。状态不存任何原始内容绝不保存原始 prompt、原始模型输出、工具参数、密钥、宿主路径或 provider 诊断信息详见本文第五部分。这形成了 IronClaw 的循环信任故事一个已发布的循环之所以可信不是因为它是随产品一起发布的而是因为框架层没有任何能力去构造能力授权、审批、租约或密钥——每一个特权效果都必须穿过ironclaw_loop_contracts的端口进入内核由内核中介并只回传密封的、脱敏后的结果参见 crates/loop/AGENTS.md。三、Loop Family家族身份、内容寻址版本与注册表CLAUDE.md 指出 crate 拥有family.rs、families/、planner.rs、default_planner.rs和strategies/用于密封的内置循环家族/规划策略组合每个策略文件只负责一个决策轴。3.1 LoopFamilyId扁平字符串身份family.rs 定义了内置家族的四个常量 IDDEFAULTdefault——文本工具使用基线家族SUBAGENTsubagent——子代理家族UNBOUND_DEFAULTunbound_default——非绑定默认家族UNBOUND_STRUCTUREDunbound_structured——非绑定结构化输出家族ID 在 profile JSON 中以扁平字符串序列化且经过严格校验family.rs非空、最长 128 字节、只允许小写 ASCII 字母、数字、_、-、:。这些约束都有对应的单元测试覆盖loop_family_id_validates_construction_and_deserialization。3.2 ComponentIdentityBLAKE3 内容寻址家族的可重放性replay safety通过内容寻址来保证ComponentDigest 是 BLAKE3-256 摘要ComponentIdentity由id digest组成用于标识循环家族、hook、技能快照、模型路由等一切实现变更会影响重放安全的构件。families/mod.rs中的default_family_fingerprint函数families/mod.rs把默认家族的全部可调旋钮——上下文策略max_messages128、压缩策略context_limit128000, reserve20000, preserve_tail8000, ...、能力策略、模型策略、批处理bounded_fanout4、门控策略、恢复策略max_attempts_per_class2, model_availability_attempts...、回复准入、停止条件consecutive_repeat3、输入排空、预算策略iteration_limit...——序列化为一个指纹字符串其 BLAKE3-256 哈希即DEFAULT_FAMILY_DIGEST。这保证了家族的ComponentIdentity摘要永远标识它实际运行时的配置而不是某个声称的默认值。3.3 LoopFamilyRegistry不可变单例注册表LoopFamilyRegistry 是不可变注册表提供get、ids、with_families三个操作。with_families会拒绝重复家族 ID返回LoopFamilyRegistryError::DuplicateFamilyId。它的核心设计是注册表是某个反序列化出来的 ID 是否真的已绑定的唯一权威——家族工厂是唯一的构造入口下游可以解析和持有家族但无法检查或组合其规划器槽位。四、Planner 与密封策略组合一个策略文件 一个决策轴CLAUDE.md 的 Adding code 一节给出了最核心的扩展法则Add a new strategy file only for a new independent decision axis.也就是说框架的演进哲学是新行为 新的密封策略而不是在规范执行器里加分支。4.1 公开 trait 与 crate 私有扩展planner.rs 中公开的AgentLoopPlannertrait 是刻意identity-only的——它没有run()或tick()方法循环机制在 executor 中公开调用方只能观察到家族 ID 与内容身份。执行器真正消费策略是通过 crate 私有的AgentLoopPlannerInternal扩展 traitplanner.rs它暴露了十个策略槽的访问器。4.2 十大密封策略轴结合 strategies/mod.rs 与DefaultPlanner的槽位定义可以梳理出框架的十个决策轴及其职责策略轴策略文件职责Contextcontext.rs规划上下文请求prompt bundle、游标、表面版本、最大消息数Capabilitycapability.rs能力过滤CapabilityFilter与能力可见性Modelmodel.rs模型选择主模型/回退索引、结构化结果Compactioncompaction.rsactive_task_compaction.rs上下文压缩决策触发、字节上限、有效性基线Gategate.rs门控处理GateOutcome::Block等Recoveryrecovery.rs错误恢复按错误类别的重试预算、退避、重试变更ReplyAdmissionreply_admission.rs回复准入拒绝空回复与 provider 转写伪影Stopstop.rs停止条件观察已完成 turn 终止决策Draindrain.rs用户输入排空steering / follow-up 两种模式Budgetbudget.rs迭代上限与墙钟时间上限需要注意的策略契约细节strategies/mod.rs 的文档注释大多数策略接收LoopExecutionState并返回一个 outcome 枚举outcome 携带自己槽位的新值执行器负责把槽位交换进下一个完整状态。Gate 与 Recovery 策略是异步的因为它们可能查询宿主/运行时状态授权历史、认证流程状态、路由健康度、熔断器计数纯策略如 Budget保持同步。检查点/可观测性的线格式枚举标注为#[non_exhaustive]后续扩展不需要破坏现有消费者。4.3 DefaultPlanner参考组合default_planner.rs 中的DefaultPlanner是内置策略的参考组合构造是 crate 私有的compose_default公开调用方只能通过families::*与LoopFamilyRegistry拿到密封的AgentLoopPlanner。其 builder 链with_id/with_version/with_context/with_compaction/ ... /with_budget为未来家族工厂预置了能力——内置家族正是用它来定制策略集的例如subagent家族通过with_budget覆盖预算策略。DefaultStrategySlotsdefault_planner.rs的默认值展示了参考组合的出厂配置DefaultContextStrategy、ActiveTaskPreservingCompactionStrategy、DefaultCapabilityStrategy、DefaultModelStrategy、DefaultGateHandlingStrategy、DefaultRecoveryStrategy、DefaultReplyAdmissionStrategy、DefaultStopConditionStrategy、DefaultInputDrainStrategy、DefaultBudgetStrategy。4.4 内置家族工厂families/目录提供内置家族工厂目前有三个模块defaultfamilies/mod.rs文本工具使用基线DefaultPlanner::compose_default()直接产出迭代上限取DEFAULT_ITERATION_BACKSTOP。subagentfamilies/subagent.rs子代理家族迭代上限收紧为256其余策略沿用默认但model_availability_attempts提高到12更耐心地等待模型可用。unboundfamilies/unbound.rs非绑定家族默认 结构化输出两个变体面向非绑定场景。families/mod.rs还提供default_with_iteration_limit与FamilyOverrides供测试与本地 harness 以较小的迭代上限快速触达硬预算路径而不必等待生产环境的 1024 次迭代背停。五、可恢复执行状态typed slots 与只存安全摘要铁律CLAUDE.md 反复强调状态边界State stores refs, cursors, counters, versions, and safe summaries only.状态只存引用、游标、计数器、版本号与安全摘要。Do Not Move In Here 一节更是列出了明确的禁区禁止在状态中存放原始 prompt、原始 assistant 内容、工具输入 JSON、密钥、宿主路径或后端诊断信息。5.1 LoopExecutionState 的结构state.rs 中LoopExecutionState的核心设计是不可变状态穿针引线执行器每个 tick 都把本地let mut state重新绑定为下一个完整状态策略接收LoopExecutionState并返回携带自己槽位新值的 outcome执行器通过交换槽位构建下一个状态。关键字段包括执行器通用字段iteration迭代计数、last_checkpoint、assistant_refs、result_refs、last_gate、input_cursor、surface_version。执行器观察字段对策略只读recent_call_signaturesBoundedRing_, 8有界环、recent_failure_kinds、recent_output_token_counts。预算账本budget_ledger以#[serde(flatten)]展平保证检查点线格式不变。完成提示completion nudge字段completion_nudges_used与completion_nudge_pending均带#[serde(default)]以兼容旧检查点。值得注意的是CHECKPOINT_SCHEMA_ID为reborn:default-loop-v2、版本为2state.rsv1 检查点刻意不做迁移。5.2 策略专属状态槽每个策略的持久化状态都是独立的类型化槽位位于 state/slots.rs。例如CompactionStrategyStateslots.rs承载last_compacted_through_seq、last_deferred延迟压缩水位、force_compact_on_next_iteration、consecutive_ineffective_compactions、compaction_circuit_open单向熔断器连续INEFFECTIVE_COMPACTION_TRIP_LIMIT 3次无效压缩后开启避免压缩-再压缩死循环持续烧掉摘要推理等。CLAUDE.md 的规则是只有当一个策略需要类型化的可恢复状态时才新增状态槽类型禁止用serde_json::Value走捷径——已知形状必须有类型。Stop 与 Gate 各自拥有独立槽位不存在共享的control_state因此家族未来在任一维度上的增长都不会通过共享结构意外混入关切。tests/state_lifecycle.rs中的测试如state_serializes_round_trips、model_error_recovery_budget_and_observation_survive_checkpoint_reload验证了这些状态槽的序列化往返与检查点重载LoopExecutionState::from_checkpoint_payload能力。六、规范执行器canonical tick 的生命周期阶段CLAUDE.md 的 Executor stage ownership 一节给出了执行器的组织原则Keepsrc/executor/canonical.rsas the ordered lifecycle spine; put lifecycle mechanics in the owning executor stage instead of branch logic incanonical.rs.即canonical.rs是有序生命周期脊柱生命周期机制放进各自所属的执行器阶段而不是堆在canonical.rs里加分支逻辑。同时规定CanonicalAgentLoopExecutor保持公开DefaultExecutorPipeline与阶段类型保持 crate 内部不要把兄弟阶段通过另一个阶段的输入传递不要为纯映射 helper 或一行包装新增阶段取消、检查点、pending-input-ack 的顺序要在拥有状态转移的阶段边界显式处理。6.1 执行器入口AgentLoopExecutortraitexecutor.rs只有唯一的公开入口execute_family接收一个已解析的LoopFamily、一个AgentLoopDriverHosttrait 对象、一个初始LoopExecutionState返回LoopExit。CanonicalAgentLoopExecutorexecutor.rs是默认实现直接委托给DefaultExecutorPipeline::execute。错误模型同样是已清洗的AgentLoopExecutorErrorexecutor.rs只包含HostUnavailable、PlannerContract、CheckpointRejected、CheckpointFailed、RecoverySequenceExhausted、Cancelled等信任可靠的失败类型循环级的终止态通常以LoopExit返回而不是抛错。6.2 规范 tick 的十个阶段DefaultExecutorPipelinepipeline.rs由十个阶段组成对应源码目录下的阶段文件。canonical.rs中execute的主循环canonical.rs按序执行cancel_checkCheckpointStage.cancel_if_requested协作式检查取消请求——这是唯一不产生Cancelled错误的取消路径错误变体Cancelled只用于 in-flight 外部调用返回取消结果的情形。budgetBudgetStage检查预算迭代上限、墙钟上限超限则强制退出。这里需要特别说明的是默认迭代上限DEFAULT_ITERATION_BACKSTOP 1024strategies/budget.rs注释明确指出这是一个防失控背停runaway backstop而非运营预算——真实的长 agentic 编码 turn 合法地运行数百次模型调用过小的上限会在工作中途失败并丢弃模型已完成的一切运营级上限本应由资源预算系统ResourceBudgetPolicy.max_model_calls与墙钟上限目前是已定义但未强制执行提供。emit_iteration_started发出LoopProgressEvent::IterationStarted进度事件。input_drain_steering以UserFacingInputDrainMode::Steering模式排空用户输入单次最多MAX_INPUT_DRAIN 32条executor.rs并通过PendingInputAck保证 input ack 在持久化后才推进。promptPromptStage构建 prompt bundle走 Context 策略产出四种结果之一Prepared进入模型阶段、ResumeApproval/ResumeAuth/ResumeExternalTool三种待恢复调用路径、SkipModel仅压缩 turn。checkpoint_before_model在模型调用前批量写入检查点。modelModelStage调用模型产出Response/RetryIteration/Exit。每次模型响应都累积cumulative_model_usage包括工具调用 turn 的 token/成本不能只在 assistant-reply 分支上记录。reply_admission assistant_reply / capabilities模型输出为AssistantReply时先经ReplyAdmissionStage准入Accept/Reject再走AssistantReplyStage为CapabilityCalls时走CapabilityStage每批最多MAX_CAPABILITY_RETRIES 8次重试。post_capability能力批处理后的统一收尾如触发force_compact_initiator CapabilityResultOverflow。stop_observe stop_decide先StopConditionStrategy::observe_completed_turn记账再should_stop_after_observed_turn决策。StopStep::Stop时还有一个关键机制——completion nudge完成提示若SteeringPolicy.allow_driver_specific_nudges开启、completion_nudges_used COMPLETION_NUDGE_LIMIT(2)executor/loop_exit.rs且停止类型为GracefulStop且收尾回复话没说完last_reply_trailed_off或定时触发器运行且收尾回复以问句结尾执行器会不终止而是带完整工具面重入循环一轮注入完成提示指令让模型先把任务做完例如写出必需的文件再作答NoProgressDetected已是失败终止态所以不会 nudgeAborted永不 nudgecanonical.rs。此外ReplyOnly结束的 turn 会额外执行一次input_drain_follow_upUserFacingInputDrainMode::FollowUp若排空到排队中的后续输入则继续循环而不是终止。6.3 阶段所有权规则CLAUDE.md 对阶段组织的规定非常具体实践中应严格遵守生命周期机制放进所属阶段模块canonical.rs只做编排每个阶段的 helper 行为留在阶段模块内部不跨阶段传递兄弟阶段只为真正的生命周期机制新增 executor helper子模块化先于文件变成无关 helper 的大杂烩禁止misc/utils/common这类模块。七、扩展法则什么时候新增什么文件CLAUDE.md 的 Adding code 一节给出了精确的新增代码决策表这是本文档最具实战价值的部分完整继承如下想做什么正确姿势源码位置新增一个独立决策轴新增一个策略文件src/strategies/axis.rs策略需要类型化可恢复状态新增一个状态槽类型禁止serde_json::Value捷径src/state/slots.rs新增内置循环家族新增一个家族文件由密封策略组合而来src/families/family.rs新增执行器能力仅当它属于规范循环机制时新增 executor helpersrc/executor/各阶段文件文件混杂无关 helper先引入子模块禁止misc/utils/common模块—同时CLAUDE.md 的 Do Not Move In Here 划出了明确的禁区以下内容严禁进入本 crate产品专属逻辑、产品适配器、传输行为或 Reborn app 组合AgentLoopDriver/PlannedDriver宿主接线那座桥属于ironclaw_turn_runner——框架永远看不到 driver只看到自己的 executor 契约运行时 lanes、host-runtime 服务、provider 认证、网络/密钥、UI 关切状态中的原始 prompt、原始 assistant 内容、工具输入 JSON、密钥、宿主路径、后端诊断。八、常见错误清单Common MistakesCLAUDE.md 专门列出了三个高频错误值得在代码评审时逐条对照不要把产品专属逻辑追加到执行器上——执行器只属于规范循环机制产品逻辑应留在产品层crates/product/。不要向下游 crate 公开策略 trait——策略 trait 全部保持 crate 私有公开的只是密封的AgentLoopPlanner。不要通过引用让策略修改共享状态——策略必须返回 outcome由执行器把类型化槽位交换进下一个完整状态。这一条在 strategies/mod.rs 的测试strategy_outcomes_compose_through_owned_loop_state_slots中有直接体现Gate/Recovery/Stop 的 outcome 各自携带新槽值随后被交换进next_state。九、验证命令与测试矩阵CLAUDE.md 的 Validation 一节给出了三层验证命令按场景选择# 快速本地检查框架与驱动测试 cargo test -p ironclaw_agent_loop # 依赖/API 变更后的边界检查BoundaryRule 仲裁 cargo test -p ironclaw_architecture_tests # 涉及 driver 或 loop-host 集成时 cargo test -p ironclaw_turn_runner仓库内的测试资产可以进一步细分crate 内单元测试src/executor/tests/覆盖执行器各阶段的边界情形认证恢复auth_resume.rs、预算budget.rs、取消cancellation.rs、能力结果capability_results.rs、压缩compaction.rs、完成退出completion_exit.rs、拒绝恢复denied_resume.rs、失败矩阵failure_matrix.rs、门控gates.rs、模型恢复model_recovery.rs、并行批处理parallel_batch.rs、prompt 阶段prompt_stage.rs、provider 重放provider_replay.rs、回复输入reply_input.rs另有src/strategies/、src/families/、src/state/的策略/状态测试。集成测试tests/目录executor_happy_paths.rs快乐路径、state_lifecycle.rs状态生命周期与检查点往返、strategy_interactions.rs策略交互、deferred_followups.rs延迟后续输入、safety_nets.rs安全网/背停机制。fixture 支持test_support/提供MockAgentLoopDriverHost、ScenarioScript、ScriptedModelResponse、ScriptedCapabilityCall等脚本化驱动宿主配合test-supportfeatureCargo.toml用tokio::sync::Notify确定性驱动取消路径。十、结语如何读懂并维护这套框架理解ironclaw_agent_loop的钥匙是一组环环相扣的设计决策密封性公开表面只有执行器、规划器、家族与状态四个入口策略 trait 与执行器管线全部 crate 私有机械强制contracts-only 依赖与端口位置由ironclaw_architecture_tests的 BoundaryRule 在 CI 中强制执行信任不依赖自觉决策轴正交每个策略文件只回答一个问题新行为通过新增密封策略而非在规范执行器里加分支状态最小化可恢复状态只放引用、游标、计数器、版本号与安全摘要任何原始内容都被挡在状态之外。需要继续深入时推荐按以下路径阅读仓库框架入门README.md → 本 CLAUDE.md → crates/loop/AGENTS.mdloop 家族总规则契约定义crates/contracts/ironclaw_loop_contracts端口与 driver 契约相邻 cratecrates/loop/ironclaw_loop_host/AGENTS.md端口实现与 crates/loop/ironclaw_turn_runner/AGENTS.mddriver 桥接边界仲裁crates/app/ironclaw_architecture_tests/tests/reborn_dependency_boundaries.rs。这套设计的最终检验标准是 README 中的那句话它是系统中唯一被设计为可整体替换而不触碰任何特权构件的产物——而 contracts-only 依赖集合正是这一信任故事得以机械成立而非依赖评审约定的根本原因。赞分享人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载相关推荐IronClaw 密封循环框架 ironclaw_agent_loop执行器生命周期、密封策略组合与可恢复状态架构解析IronClaw 密封循环框架 ironclaw_agent_loop执行器生命周期、密封策略组合与可恢复状态架构解析 导读 ironclaw_agent_l人工智能AI 应用交互助手AI AgentIronClaw 的 Loop 家族可替换的 Agent 用户态与“端口即膜”的信任架构IronClaw 的 Loop 家族可替换的 Agent 用户态与“端口即膜”的信任架构 crates/loop/ 是 IronClaw 中承载 Agent人工智能AI 应用交互助手AI AgentPDF补丁丁上手记批量修好几十份论文的书签与元数据的免费PDF编辑工具箱PDF补丁丁上手记批量修好几十份论文的书签与元数据的免费PDF编辑工具箱 上周帮同事处理 47 份扫描报告文件名全是“扫描_01”书签要么缺失要么指向错人工智能AI 应用交互助手AI Agent上一篇终极指南如何为zsh-syntax-highlighting配置持续集成与实现GitHub Actions自动化测试下一篇MinIO s3zip 扩展实现解析直接在 S3 API 中列出、查看与下载 ZIP 归档内的对象创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考