人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载本技术指南聚焦 IronClaw 开源 Agent OS 中ironclaw_turn_runnercrate 的 Coder编码子代理方向提示词direction prompt剖析其有界文件级编码任务执行协议的全部条款并结合源码揭示该协议在工具白名单、能力衰减、结果安全返回等层面的落地实现。读完本文你将理解 Coder 子代理与 General / Explorer / Planner 子代理在角色边界上的本质差异掌握其工具面、执行纪律与结果交付规范并能定位到对应源码与测试进行二次开发。一、Coder 方向提示词一份完整的子代理角色契约方向提示词direction prompt是 IronClaw 子代理系统为每种风味flavor准备的静态角色提示。Coder 方向的完整原文定义于 coder.md全文可拆解为四个层次的角色契约1. 角色定位focused coding subagentYou are a focused coding subagent.Coder 子代理是面向编码执行的专职代理其角色关键词是focused专注——它与 Planner 的只出计划不执行、Explorer 的只读探索形成鲜明分工Coder 是唯一被允许写文件、打补丁、执行 Shell 的内置子代理。2. 任务边界有界、文件级、服务于父运行Complete a bounded, file-level coding task for the parent run.这是整个协议的核心约束Coder 只承接父运行parent run委派的一个bounded有界、file-level文件级编码任务不做超出任务范围的系统级变更。任务的载体是SubagentGoalRecord包含task与可选handoff字段由父运行通过进程输入通道以subagent-goal:v1标识写入Coder 运行时的提示材料由 prompt_material.rs 中的material_for_run负责组装。3. 执行纪律先读后改、最小改动、范围克制Read the relevant files first to understand existing conventions, then make the smallest correct change that satisfies the task. Prefer apply_patch for edits to existing files; use write_file only when creating new files. Keep changes scoped to the task and avoid unrelated refactors.Coder 被明确要求遵循四步纪律先读文件再动手先读取相关文件以理解既有约定代码风格、结构习惯禁止在不了解上下文的情况下直接改码最小正确改动做出满足任务的最小正确变更smallest correct change不做多余优化apply_patch 优先修改既有文件时优先使用apply_patch仅当创建新文件时才使用write_file——这一约定与untrusted_text.rs中结构化字符会被清洗的安全模型一脉相承补丁式编辑比整文件覆写更可控、更可审计严格范围限制变更必须局限在任务范围内避免无关重构avoid unrelated refactors。4. 验证与交付跑测试、简洁回报、上报阻塞When useful, run the projects tests or checks via the shell to validate your work. Return a concise result that lists the files you changed and the outcome of any tests or checks you ran, plus any blocker the parent must handle.完成改动后Coder 被鼓励在必要时通过 Shell 运行项目测试或检查来验证工作成果最终交付时必须返回简洁结果包含三要素改动了哪些文件、运行了哪些测试/检查及其结果、以及任何需要父运行处理的阻塞项blocker。二、Coder 的工具面白名单如何由代码强制执行方向提示词只是软约束真正让 Coder 只能干编码活的是 flavors.rs 中静态声明的工具白名单。SubagentFlavorId::Coder对应的CODER_TOOLS精确包含 7 个能力工具 ID能力标识CapabilityId用途ReadFilebuiltin.read_file读取文件内容WriteFilebuiltin.write_file创建/覆写文件ApplyPatchbuiltin.apply_patch对既有文件做补丁式修改Shellbuiltin.shell执行 Shell 命令跑测试/检查ListFilesbuiltin.list_dir列出目录Searchbuiltin.grep正则搜索Globbuiltin.glob通配符查找文件与之对照其余三种内置风味的白名单均不含任何写/执行能力General仅read_file、list_dir、grep只读探索Explorerread_file、list_dir、grep、glob只读 通配探索Plannerread_file、list_dir、grep、glob、http只读 联网调研输出实施计划。flavors.rs中的coder_flavor_surface_matches_allowlist_exactly测试断言 Coder 的有效能力面与白名单逐字节相等builtin.read_file、builtin.write_file、builtin.apply_patch、builtin.shell、builtin.list_dir、builtin.grep、builtin.glob并特别验证builtin.spawn_subagent与builtin.http不在其中——即 Coder 不能再次派生子代理也不能发起网络请求。三、方向提示词如何进入运行时include_str! 编译期注入方向提示词并非在运行时从磁盘读取而是通过include_str!在编译期直接嵌入二进制const GENERAL_DIRECTION: str include_str!(general.md); const EXPLORER_DIRECTION: str include_str!(explorer.md); const CODER_DIRECTION: str include_str!(coder.md); const PLANNER_DIRECTION: str include_str!(planner.md); pub fn direction_prompt(id: DirectionId) - static str { match id { DirectionId::General GENERAL_DIRECTION, DirectionId::Explorer EXPLORER_DIRECTION, DirectionId::Coder CODER_DIRECTION, DirectionId::Planner PLANNER_DIRECTION, } }这段代码位于 directions/mod.rs。由此可以总结出该机制的几个工程特性单一事实来源coder.md是提示词的唯一真源修改它即修改线上行为无需经过外部配置下发零运行时 I/O提示文本以static str形式驻留无文件读取失败路径方向与风味解耦DirectionId方向与SubagentFlavorId风味是两个独立枚举由SubagentFlavor结构体将二者绑定Coder 风味 → Coder 方向完整性有测试守护direction_prompts_are_non_empty与every_flavor_direction_resolves等测试保证每个方向提示非空且每个风味都能解析到方向。四、提示材料组装方向 目标 白名单的三元组在 prompt_material.rs 中material_for_flavor_with_goal将三部分组装为SubagentPromptMaterialOk(SubagentPromptMaterial { direction_markdown: direction_prompt(flavor.direction).to_string(), goal, allowed_capabilities, })即子代理提示材料 静态方向提示本文章的主角 coder.md 父运行下发的目标goal 白名单能力集。其中allowed_capabilities由flavor.tool_allowlist逐项转换为CapabilityId后构成BTreeSet。目标goal的来源有两种路径均由goal_for_run统一处理进程输入优先通过ProcessInputPort.get_process_input读取subagent-goal:v1标识的进程输入反序列化为SubagentGoalRecord { task, handoff }线程历史兜底若进程输入缺失则从SessionThreadService读取线程历史从元数据中解析SubagentThreadMetadata要求kind SubagentThreadKind::Subagent并从用户消息中提取任务文本——此时还需调用strip_persisted_handoff剥离追加在任务末尾的 Parent handoff: 后缀避免把交接文本当作任务本体。五、能力衰减Coder 的有效能力面如何被强制收窄方向提示词告诉模型你该做什么而运行时能力面capability surface决定你实际能调用什么。Coder 的能力衰减由 capability_surface.rs 中的SubagentCapabilitySurfaceResolver强制执行let base self.inner.resolve(run_context).await?; if !is_subagent_planned_run_profile(run_context) { return Ok(base); } let material self.material_source.material_for_run(run_context).await?; Ok(base.narrow_to_capability_ids(material.allowed_capabilities))逻辑分三步先解析外层运行配置profile的基础能力面若非子代理运行则原样返回基础面若确为子代理运行使用SUBAGENT_PLANNED_PROFILE_ID计划驱动 profile则用base.narrow_to_capability_ids将基础面收窄到白名单交集。这意味着即使宿主注册了builtin.spawn_subagent、builtin.http等能力Coder 运行时也无法看见或调用它们。flavors.rs的caller_level测试模块对此做了端到端验证coder_gets_exactly_read_write_shell_surface_without_spawn用真实的生产路径RebornSubagentPromptMaterialSource→SubagentCapabilitySurfaceResolver→CapabilitySurfacePolicyFilter构建 Coder 过滤器断言可见能力与工具定义严格等于白名单spawn_subagent、http均不可见白名单内每个能力调用均可通过并到达宿主builtin.spawn_subagent调用被Denied拒绝不会穿透到宿主端口。subagent_surface_intersects_outer_profile_surface测试则证明当外层 profile 本身也受限时如仅允许read_file、shell、httpCoder 的有效面取外层与白名单的交集本例只剩read_file、shell体现双端衰减、取交集的安全设计。六、结果安全返回父运行视角下的 Coder 交付Coder 的最终交付文本会回流到父运行因此 untrusted_text.rs 对子代理产出的不可信文本做了防御性处理wrap_untrusted_subagent_text将子代理文本包裹在|||...|||分隔符中再进入能力结果存储或父运行记录作为针对提示注入prompt injection的纵深防御defense-in-depthsanitize_tool_result_summary剥离 { } [ ]/ 等结构化字符、折叠空白超过 512 字节按字符边界截断若净化后仍不满足ToolResultSafeSummary校验则降级为占位文案 Subagent result availablesanitize_untrusted_terminal_reason对终止原因做同样净化并封装。从源码注释可见builtin.message能力并不存在于宿主注册表因此不在任何白名单中也不存在子代理主动发消息的能力路径——结果交付是带外out-of-band的由完成观察者读取子代理最终助手消息交还父运行。运行状态追踪则由 spawn_result.rs 中的 wire 稳定载荷承载SpawnedChildRunPayload含flavor、mode、status、final_text、failure_summary、terminal_event等字段以 snake_case 序列化SubagentSpawnStatus枚举覆盖 Spawned / Completed / Failed / Cancelled / RecoveryRequired 五种状态其序列化形状有 round-trip 测试钉死防止 wire 格式漂移。七、与其他方向的协同Coder 在子代理体系中的生态位将四份方向提示词并列对比可以清晰看出 IronClaw 子代理体系的职责分工方向提示文件能力面产出能否改文件Generalgeneral.md只读三件套完成父任务并回报否Explorerexplorer.md只读 glob代码库深度分析报告否Codercoder.md读 写 补丁 Shell有界文件级编码改动是Plannerplanner.md只读 glob http结构化实施计划Goal/Plan/Risks/References否一个典型的协作流可以推断为父运行先用 Planner 出计划用 Explorer 摸清代码结构再委派 Coder 按计划落地最小改动——Coder 是链条中唯一动手的环节因此它的方向提示词才会刻意强调先读文件、最小改动、避免无关重构、回报测试结果与阻塞项这些条款共同把 Coder 塑造成一个可信的、可审计的、可预期的执行者。所有内置风味当前均不允许嵌套派生allow_nesting: false有v1_flavors_disallow_nesting测试守护。八、验证与延伸阅读如果你希望亲自验证 Coder 方向协议及其运行时保障可以在仓库根目录运行cargo test -p ironclaw_turn_runner重点关注的测试锚点包括flavors.rs中的coder_flavor_surface_matches_allowlist_exactly、caller_level::coder_gets_exactly_read_write_shell_surface_without_spawn以及directions/mod.rs中的非空断言测试。进一步阅读建议coder.md — 本文主角Coder 方向提示词原文flavors.rs — 风味定义、工具白名单与全套衰减测试prompt_material.rs — 提示材料方向 目标 白名单组装逻辑capability_surface.rs — 子代理能力面收窄实现untrusted_text.rs — 子代理回传文本的清洗与封装spawn_result.rs — 子代理运行结果的 wire 稳定载荷AGENTS.md — 该 crate 的模块边界与验证命令约定。赞分享人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载相关推荐Docker Buildx 安全构建架构深度解析构建流水线中的机密信息管理实践Docker Buildx 安全构建架构深度解析构建流水线中的机密信息管理实践 在现代云原生架构中Docker 镜像构建已从简单的本地操作演变为复杂的 CICI/CDWand-Enhancer 实操指南不花订阅钱5分钟用上专业版功能和手机遥控Wand Enhancer 实操指南不花订阅钱5分钟用上专业版功能和手机遥控 Wand Enhancer 是一个面向 WandWeMod客户端的开源本地桌面应用前端Auto-Claude任务规划与执行从需求分析到代码实现全流程Auto Claude任务规划与执行从需求分析到代码实现全流程 Auto Claude是一款强大的自主多会话AI编码工具能够帮助开发者实现从需求分析到代码部人工智能AI Agent自主智能体代码智能体桌面应用前端开发工具上一篇如何解决BT下载慢83个公共Tracker完整配置指南下一篇免费BT下载加速终极指南如何用83个公共Tracker提升10倍下载速度创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
