oh-my-pi 的 task 工作代理被委派子任务的角色定义、系统提示与运行约束解析【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi导读task是 oh-my-piOMP编码代理内置的通用型工作代理worker agent专门负责接收主代理委派的、可独立完成的多步子任务。它拥有完整工具权限被要求聚焦单一任务、精简输出并严格遵循委派方指定的流程与验收标准。本篇文章以 task.md 为骨架深入剖析该代理的角色定位、系统提示system prompt的逐条语义、运行时约束以及它与scout、reviewer、sonic等专职代理的协作关系帮助读者理解 oh-my-pi 子代理系统的设计哲学与落地实现。一、task 代理的角色定位被委派的执行者打开 task.md 的第一行全文的第一句话就是它的全部定位Worker agent: delegated tasks.这意味着task不是主动决策的总代理main agent而是一个被动接受委派、专注执行的工作代理。在 oh-my-pi 的任务委派体系task工具中主代理通过tasks[]批量或单条地把工作交给子代理task就是这套体系中最通用的默认执行者。这个定位从源码中得到印证在 spawn-policy.ts 中定义了常量DEFAULT_SPAWN_AGENT task注释写明Default agent used when a session has unrestricted spawning——当会话允许无限制派生子代理、而调用方又省略了agent字段时系统默认派生的就是task代理。在 agents.ts 中task代理的内置定义也被明确描述为name: task description: General-purpose subagent with full capabilities for delegated multi-step tasks spawns: * model: task thinkingLevel: AUTO_THINKING其中spawns: *表示该代理可以再派生任意类型的子代理递归委派model: task表示它默认使用task模型角色对应的模型thinkingLevel: AUTO_THINKING表示思考强度采用自动档。因此可以概括为task是万能的、多步任务的、可继续下钻的执行者而scout只读探索、reviewer代码审查、security-reviewer安全审查则是单一职责的专职者。二、工具权限FULL access按需必用task.md 第二部分明确了子代理的工具边界Tools: FULL access (edit, write, bash, grep, read, etc.); MUST use as needed to complete task.即task代理拥有完整工具集——编辑edit、写入write、执行命令bash、正则搜索grep、读取文件read等并且被强制要求按需使用这些工具去完成任务。这与scout只读和reviewerread/grep/glob/bash/lsp/web_search/ast_grep且 bash 只读形成鲜明对比代理工具面典型用途taskFULL accessedit/write/bash/grep/read 等需要动手改代码、建文件、跑命令的多步任务scout只读工具只做调研不产生任何文件变更reviewerread/grep/glob/bash/lsp/web_search/ast_grepbash 只读基于 diff 做代码审查禁止编辑security-reviewer安全审查专用安全漏洞与风险分析这种全能力 vs 受限能力的设计是 oh-my-pi 委派系统正确性correctness与效率efficiency的基石只有需要真正动手的任务才应该落到task头上纯调研任务应交给更快的scout。这一点在 tools/task.md 中也被明确写进了主代理的提示词Read-only research MUST run onscout(faster model)。三、强制专注hyperfocus绝不偏离task.md 的第三行写了一条铁律MUST hyperfocus assigned task; NEVER deviate.子代理从空上下文blank slate启动没有历史对话因此它的全部注意力都必须集中在当前这条委派任务上。这与 tools/task.md 中Subagents start blank — no conversation history的描述完全一致每次派生子代理都是一次干净的、无历史包袱的执行。绝不偏离NEVER deviate还有一层工程含义在 executor.ts 中runSubprocess为每个子代理建立独立会话并在其系统提示中注入委派任务与共享上下文偏离主题不仅浪费 token更可能越过任务边界去修改不该碰的文件。因此hyperfocus既是提示词要求也是运行时隔离独立会话、独立工作目录上下文的必然结果。四、directives 详解被委派代理的行为守则task.md 的核心是directives块它定义了子代理执行任务时的完整行为规范。逐条拆解如下1. 只完成被委派的工作返回最小有效结果MUST finish assigned work only; return minimum useful result; do not repeat filesystem writes.scope 最小化只做委派的工作不主动顺手修复无关问题、不做额外增强输出最小化返回最小有用结果即只给出结论、关键信息与必要产出不输出冗长的工具调用流水账不重复写盘同一个文件操作不做第二次。这背后是成本意识——子代理每多一轮工具调用都会消耗 token 与时间。2. 需要时再动手SHOULD edit files, run commands, create files when task requires.它明确了动手的触发条件是任务需要when task requires。也就是说编辑文件、执行命令、创建文件都是被允许甚至被期望的但前提是委派的任务要求这么做。这与绝不偏离互为表里动手范围 任务所需范围。3. 极简输出你是给未来的自己写笔记MUST concise; NEVER filler, repetition, tool transcripts. User cannot see you; result: notes for yourself.这条是 oh-my-pi 子代理提示词中最有特色的设计禁止废话与重复NEVER filler, repetition禁止粘贴工具调用原文tool transcripts——子代理的执行过程不会展示给用户用户只关心最终结果结果定位为给自己的笔记result: notes for yourself子代理的产出最终会被主代理或后续流程消费因此它应当是浓缩的、信息密度高的摘要而不是对话记录。从工程实现看executor.ts 中的SOFT_REQUEST_BUDGETscout/sonic 为 100default 为 200会在子代理请求次数越过软预算时注入wrap up提示强制其收敛输出——这从运行时层面保证了极简输出不只是提示词建议而是有硬性兜底的。4. 窄查询优先grep/glob 定位按需读范围SHOULD prefer narrow lookups (grep/glob), then read needed ranges only; ignore beyond current scope.这是对工具使用策略的明确指导优先窄查询先用grep/glob精确定位而不是打开整个文件目录树只读需要的区间定位后只读取必要的行区间read needed ranges only无视当前范围之外的一切ignore beyond current scope。在 oh-my-pi 的实现中grep与glob是内置的快速检索工具而read工具本身也支持offset/limit按区间读取这一策略直接服务于第三条的成本最小化——子代理的上下文窗口是有限的过早塞入大文件全文会挤占真正需要的上下文空间。5. 除非必要避免整文件读取AVOID full-file reads unless necessary.与上一条呼应整文件读取是昂贵操作仅在必要时才允许。这是 oh-my-pi 对子代理 token 消耗的精细管理也解释了为什么read工具默认会返回结构化摘要readSummarize默认开启见 task-agent-discovery.md——只有read-summarize: false的代理如scout才会拿到逐字文件内容。6. 优先编辑现有文件而非新建SHOULD prefer editing existing files over creating new files.在可改与可建之间优先选择改。这减少了对仓库的增删扰动也让变更更容易被 review 与回滚。7. 除非被明确要求绝不创建文档文件NEVER create documentation files (*.md) unless explicitly requested.这是对上一条的强化.md文档文件AGENTS.md、README 等默认不允许由子代理主动创建。结合 init.md 可以看到只有在任务明确要求如生成 AGENTS.md时创建文档才是合法行为——该代理在提示词中写道 After analysis: MUST write AGENTS.md to project root即文档产出必须是委派目标的一部分。8. 必须服从委派MUST follow assignment and instructions.子代理没有讨价还价的余地任务与指令是硬约束。这保证委派链上的每一步都可预期、可追踪。9. 委派时选最具体的代理类型taskdelegation: select most specificagenttype per spawn; general-purpose worker only if no listed specialist fits.这条规则是给使用task工具的主代理看的每次派生都应选择最具体的代理类型scout、reviewer、security-reviewer…只有当没有合适的专职代理时才使用通用型task。在 tools/task.md 中也有同样表述Pick each items most specific available agent。其工程动机在 task-agent-discovery.md 中可见内置代理bundled agents中scout、reviewer、security-reviewer各有专职而task与sonic共用同一个task.md正文模板只是通过注入不同的 frontmatter 区分——task是通用多步执行者sonic是低推理、只做机械更新或数据收集的廉价执行者model: smol、thinkingLevel: Medium。选对代理类型本质上是选对推理成本 × 能力边界的最优组合。五、从提示词到运行时task 代理在代码中如何被装配理解 task.md 之后值得看一下它如何被嵌入 oh-my-pi 的执行链这样读者能清楚提示词与行为之间的对应关系。5.1 构建期嵌入build-time embedding在 agents.ts 中内置代理包括task通过 Bun 的 text import 在构建期嵌入task.md与sonic.md共用同一个taskMd模板只是task注入了spawns: *、model: task、thinkingLevel: AUTO_THINKING而sonic注入的是model: smol、thinkingLevel: Effort.Mediumfrontmatter 由 frontmatter.md 这个 Handlebars 模板渲染把name、description、spawns、model、thinkingLevel等字段拼装成 YAML 头部再与正文即 task.md 的内容合并loadBundledAgents()首次调用时解析并缓存全部内置代理agents.ts后续查找走缓存。5.2 发现与覆盖规则代理定义不仅来自内置还来自文件系统用户代理~/.omp/agent/agents/*.md项目代理.omp/agents/*.md按项目.omp 用户.omp 扩展包 Claude marketplace 插件 内置代理的优先级同名去重first-wins详见 task-agent-discovery.md。这意味着用户完全可以在.omp/agents/下自定义一个名为task的代理来覆盖内置行为或自定义其他名字的专用代理然后在tasks[]中通过agent字段显式指名如{ agent: reviewer, task: ... }。5.3 模型与结构输出的优先级对于一次task委派模型选择遵循 task-agent-discovery.md 中的三级优先级task.agentModelOverrides[agentName]会话设置层面的按代理覆盖代理 frontmatter 中的model列表如task的task角色别名经modelRoles解析父代理的当前模型及其默认回退。而结构化输出output schema的优先级为任务项的显式outputSchema 代理 frontmatter 的output 父会话的outputSchemaschemaMode默认permissive允许重试耗尽后带警告接受strict则把无效结果直接判为失败见 types.ts 与 executor.ts 中finalizeSubprocessOutput的完整校验逻辑。5.4 委派接口与批次形式task代理由task工具驱动。根据设置task.batch、隔离模式等模型看到的参数形状有两种types.ts单条形式{ name?, agent?, task, outputSchema?, schemaMode?, tools?, isolated? }批次形式{ context, tasks: TaskItem[] }其中context是共享背景tasks是子任务数组支持并行派生多个子代理。每次派生对应一个任务项字段含义如下字段说明name稳定的 CamelCase 标识≤32 字符用于 IRC/作业寻址省略时自动生成agent代理类型如task、scout、reviewer省略时取 spawn policy 默认值无限制时为tasktask自包含的完整指令禁止一句话或缺少验收标准outputSchema本次调用专属的 JSON Schema覆盖代理与会话级 schemaschemaModepermissive默认/stricttools暴露给子代理的 eval 定义工具名effort粗粒度思考强度lo/med/hi在task.enableEffort开启时可用isolated在独立 worktree 中运行成功后自动应用到父工作区其中task字段还有严格的格式契约tools/task.md# Target ← 精确的文件与符号明确的非目标 # Change ← 分步的增/删/改API 与模式 # Acceptance ← 可观察的验收结果禁止项目级命令5.5 运行期隔离与兜底子代理运行时executor.ts 的createSubagentSettings还有几项关键隔离策略tools.approvalMode强制为yolo——子代理无头运行、没有 UI 可确认因此以父代理的授权为边界保证无人值守执行不被审批弹窗卡住advisor.enabled默认false未显式配置顾问时不附加顾问会话输出有硬上限PI_TASK_MAX_OUTPUT_BYTES默认 500,000 字节与PI_TASK_MAX_OUTPUT_LINES默认 5000 行见 types.ts递归深度受task.maxRecursionDepth默认 2约束达到上限的子代理会被移除task工具、清空 spawn policy防止无限下钻见 task-agent-discovery.md。六、与其他内置代理的分工协作oh-my-pi 内置的四个代理形成了一个分工明确的委派生态task.md的 directives 第 9 条正是这套生态的路由规则代理定位工具典型委派场景task通用多步执行者FULL access改代码、跑命令、建文件的多步任务sonic低推理机械执行者与 task 共用模板纯机械更新、数据收集scout只读探索者只读工具定位受影响文件、快速调研read-summarize: falsereviewer代码审查者read/grep/glob/bash/lsp/web_search/ast_grepbash 只读对 diff 做正确性审查产出结构化 findingssecurity-reviewer安全审查者安全专用漏洞与风险审查一个典型的工作流是主代理先派scout快速探索仓库确认哪些文件受影响再派一个或多个task代理并行实现改动每个任务必须跳过 formatter/lint/全量测试避免互相阻塞最后派reviewer或security-reviewer基于 diff 审查产出给出结构化结论与 P0–P3 分级 findings见 reviewer.md 的优先级表格。这套探索 → 实现 → 审查的流水线正是 task.md 中选最具体的代理类型这一指令在真实工程中的落地形态。七、结语task代理的 task.md 全文虽短却浓缩了 oh-my-pi 子代理系统的全部核心设计全工具权限负责能动手hyperfocus负责不乱动最小输出负责低成本最具体代理选择负责高效分工。理解这份提示词就等于理解了 oh-my-pi 委派体系的调度哲学——它不是一个全知全能的巨型代理而是一群高度聚焦、成本可控、可并行、可审查的小代理在协作。对于希望在 oh-my-pi 中编写自定义子代理在~/.omp/agent/agents/或.omp/agents/放置带 frontmatter 的 markdown的开发者task.md 是一份绝佳的模板范本沿用它角色一句话 工具边界 行为守则的写法你的自定义代理就能无缝接入这套委派体系。【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考