IronClaw Coder 子代理方向规范：有界编码任务的执行协议与源码实现解析

• 人工智能
• AI 应用
• 交互助手
• AI Agent

本技术指南聚焦 IronClaw 开源 Agent OS 中ironclaw_turn_runnercrate 的 Coder（编码）子代理方向提示词（direction prompt），剖析其"有界文件级编码任务"执行协议的全部条款，并结合源码揭示该协议在工具白名单、能力衰减、结果安全返回等层面的落地实现。读完本文，你将理解 Coder 子代理与 General / Explorer / Planner 子代理在角色边界上的本质差异，掌握其工具面、执行纪律与结果交付规范，并能定位到对应源码与测试进行二次开发。

一、Coder 方向提示词：一份完整的子代理角色契约

方向提示词（direction prompt）是 IronClaw 子代理系统为每种"风味"（flavor）准备的静态角色提示。Coder 方向的完整原文定义于 coder.md，全文可拆解为四个层次的角色契约：

1. 角色定位：focused coding subagent

You 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 被明确要求遵循四步纪律：

1. 先读文件再动手：先读取相关文件以理解既有约定（代码风格、结构习惯），禁止在不了解上下文的情况下直接改码；
2. 最小正确改动：做出满足任务的最小正确变更（smallest correct change），不做多余优化；
3. apply_patch 优先：修改既有文件时优先使用apply_patch，仅当创建新文件时才使用write_file——这一约定与untrusted_text.rs中"结构化字符会被清洗"的安全模型一脉相承，补丁式编辑比整文件覆写更可控、更可审计；
4. 严格范围限制：变更必须局限在任务范围内，避免无关重构（avoid unrelated refactors）。

4. 验证与交付：跑测试、简洁回报、上报阻塞

When useful, run the project's 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 个能力：

与之对照，其余三种内置风味的白名单均不含任何写/执行能力：

• General：仅read_file、list_dir、grep（只读探索）；
• Explorer：read_file、list_dir、grep、glob（只读 + 通配探索）；
• Planner：read_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将三部分组装为SubagentPromptMaterial：

Ok(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统一处理：

1. 进程输入优先：通过ProcessInputPort.get_process_input读取subagent-goal:v1标识的进程输入，反序列化为SubagentGoalRecord { task, handoff }；
2. 线程历史兜底：若进程输入缺失，则从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、http），Coder 的有效面取外层与白名单的交集（本例只剩read_file、shell），体现"双端衰减、取交集"的安全设计。

六、结果安全返回：父运行视角下的 Coder 交付

Coder 的最终交付文本会回流到父运行，因此 untrusted_text.rs 对子代理产出的不可信文本做了防御性处理：

• wrap_untrusted_subagent_text：将子代理文本包裹在|||...|||分隔符中再进入能力结果存储或父运行记录，作为针对提示注入（prompt injection）的纵深防御（defense-in-depth）；
• sanitize_tool_result_summary：剥离< > { } [ ]/ ` 等结构化字符、折叠空白，超过 512 字节按字符边界截断，若净化后仍不满足ToolResultSafeSummary校验则降级为占位文案 "Subagent result available"；
• sanitize_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 子代理体系的职责分工：

一个典型的协作流可以推断为：父运行先用 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