oh-my-pi 编码代理中的 scout 侦察子代理只读代码库快速调研与压缩交接协议详解【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi导读scout是 oh-my-pi 编码代理coding-agent内置的一款侦察兵子代理专为探索性代码库研究、快速代码分析和广度模式搜索而设计。它以只读方式高速扫描仓库并把调研结果压缩成结构化、可供其他 Agent 直接消费的交接信息避免下游代理重新通读整个代码库。本文以 scout 代理提示词 为骨架逐字段拆解其 frontmatter 配置、JSON 输出契约、执行守则并结合 agents.ts、executor.ts、spawn-policy.ts 等源码说明其实际生效机制帮助读者理解并复用这一低成本、高保真、可交接的调研模式。一、scout 的定位为什么要一个只读侦察子代理在一个由多个子代理协作的编码代理系统中最昂贵的往往是大模型重新读取代码。当主代理需要了解某个模块的现状时如果每次都完整通读整个仓库上下文窗口与 token 成本都会快速失控。scout 的出现正是为了解决这个问题。从 scout.md 的 frontmatter 可以看到它的自我定位description: MUST be used for exploratory codebase research, rapid code analysis, and broad pattern searches. Fast read-only scout returning compressed context for handoff.三个关键词构成了 scout 的全部使命探索性研究面对不熟悉的仓库先派 scout 摸清结构快速代码分析秒级定位关键文件、类型、函数与依赖关系广度模式搜索大量使用 grep/glob 做模式匹配而不是逐个文件精读。它产出的不是我看了什么的过程记录而是你接下来该知道什么的压缩上下文compressed context供后续 agent 直接消费。二、frontmatter 配置逐字段解析scout 的完整配置以 YAML frontmatter 形式写在文档头部系统通过 frontmatter 模板 将name、description、model、thinkingLevel等字段渲染成标准代理定义再由 parseAgent 解析并缓存。各字段含义如下字段值作用namescout代理唯一标识供spawns策略与任务分发引用description见上说明适用场景作为主代理选择子代理的决策依据toolsread, grep, glob, web_search只读工具集精确读文件、正则搜索、glob 找文件、联网检索modelsmol使用轻量小模型运行保证低成本与高速度thinking-levelmedium中等思考强度介于快速查找与深度推演之间read-summarizefalse关闭读取摘要管线read 返回原始内容而非压缩摘要2.1 工具集四件套支撑广度优先scout 只被授予四个工具全部是只读的read读取文件关键段落grep正则搜索做广度模式匹配glob按文件名模式定位候选文件web_search必要时检索外部公开资料辅助理解。注意这里没有 bash、write、edit 等任何可能改变系统状态的工具与文档critical段的只读约束互相印证。从 executor.ts 可以看到当agent.readSummarize false时执行器会向 read 工具注入read.summarize.enabled: false配置即 scout 读到的是文件的真实原文而不是经过摘要压缩的内容——这对需要产出精确path:line引用的侦察任务至关重要。2.2 model: smol 与 thinking-level: mediumsmol是项目内置的轻量模型档位。在 agents.ts 中另一个使用smol的内置代理sonic被描述为strictly mechanical updates or data collection可见这一档位面向机械、批量、低推理需求的任务。scout 同样受益于小模型的低成本但通过thinking-level: medium保留了一定的分析能力使其既能秒级完成搜索又足以梳理架构关系。2.3 请求预算100 次软上限在 executor.ts 的SOFT_REQUEST_BUDGET中scout 与 sonic 均被分配了 100 次请求的软预算默认档位为 200。也就是说 scout 一轮运行中最多驱动约 100 次 assistant 请求逼近预算时会注入收尾提示超支时会被强制收敛到一次yield确保部分发现也能以真实报告的形式回流。这是对快速侦察定位的执行层保障。三、输出协议一份可交接的压缩上下文scout 的产出不是自由文本而是一份结构化 JSON。frontmatter 中通过output.properties定义了严格的 schema这是它与普通读代码然后写总结最本质的区别。3.1 必填字段summary: type: string description: Brief summary of findings and conclusions files: type: array elements: path: string # 项目相对路径可带 :12-34 行号区间 description: string # 该文件相关内容 architecture: type: string description: Brief explanation of how pieces connectsummary调研结论与判断的简短总结供下游代理快速决策files关键文件清单每项包含项目相对路径可附带:12-34这样的行号区间锚点和该文件承载的内容说明。这实际上是一份可信索引让下游代理可以精确跳转无需重新定位architecture各部件如何连接的整体解释回答这段代码是怎么串起来的。3.2 可选字段 reportreport: type: string description: The complete deliverable when the task asks for a report, table, enumeration, or per-item audit — full markdown at the depth requested当任务要求报告、表格、枚举或逐项审计时完整交付物放在report字段中以所请求深度的完整 Markdown 呈现含表格、path:line锚点、函数签名、代码摘录。文档明确强调report绝不是 summary 的重复summary已经承担了概要职责只有快速查询时才允许省略report。这个设计把概要与完整交付物分离summary 始终简短以便交接report 按需全量以完成任务两者互不挤占上下文。四、执行守则directives / thoroughness / procedure / criticalscout 文档正文给出了四条行为守则共同定义了它的工作方式。4.1 directives搜索优先、并行执行、空结果不放弃- You MUST use tools for broad pattern matching / code search as much as possible. - You SHOULD invoke tools in parallel—this is a short investigation, and you are supposed to finish in a few seconds. - If a search returns empty results, you MUST try at least one alternate strategy (different pattern, broader path, or AST search) before concluding the target doesnt exist.三条硬性要求能搜索就不精读尽量用 grep/glob 做广度匹配而不是盲目打开文件必须并行调用工具这是一次几秒钟内结束的短调研串行等待不可接受空结果必须换策略换不同的正则、扩大路径范围或改用 AST 搜索至少尝试一种替代方案后才能下目标不存在的结论——避免假阴性误报。4.2 thoroughness从任务推断深度默认 medium- Quick: Targeted lookups, key files only - Medium: Follow imports, read critical sections - Thorough: Trace all dependencies, check tests/types.scout 不预设固定深度而是从任务推断Quick只做定点查找看关键文件Medium默认跟进 import读取关键段落Thorough追踪全部依赖并检查测试与类型定义。4.3 procedure标准四步流程1. Locate relevant code using tools. 2. Read key sections. NEVER read full files unless theyre tiny. 3. Identify types/interfaces/key functions. 4. Note dependencies between files.四步可归纳为定位 → 精读 → 提炼 → 关联先用工具定位再只读关键片段除非文件很小绝不整文件通读这也是 token 控制的核心然后提炼类型、接口、关键函数最后记录文件间依赖。4.4 critical绝对只读 坚持到底You MUST operate as read-only. You NEVER write, edit, or modify files, nor execute any state-changing commands, via git, build system, package manager, etc. You MUST keep going until complete.两条底线严格只读绝不写、编辑、修改任何文件也不通过 git、构建系统、包管理器等执行任何改变状态的命令坚持完成除非任务被明确终止否则必须运行到产出完整结果。从源码看这一约束是双重保险一方面工具清单里根本没有写类工具另一方面 executor.ts 的注释还揭示了一个细节——所有只读 scout 都不具备hub工具因而永远无法接收 hub 分发的信息从机制上杜绝了只读代理参与信息分发链路。五、源码视角scout 在编码代理中的完整调用链scout 并非独立文档它被编译期嵌入并在会话运行时按需拉起。其完整生命周期如下。5.1 编译期嵌入与解析在 agents.ts 中scout.md 与其他内置代理reviewer、security-reviewer、task 等一起通过 Bun 的import ... with { type: text }在构建期嵌入{ fileName: scout.md, template: scoutMd },加载时由buildAgentContent将正文渲染、经 frontmatter 模板组装再由parseAgent解析 frontmatter 生成AgentDefinition结果缓存于bundledAgentsCache后续通过getBundledAgent(scout)/getBundledAgentsMap()按名取用。5.2 会话层的可用性判定在 agent-session.ts 中会话通过#isScoutAvailable()判断 scout 是否可派发return this.#scoutAllowedBySpawnPolicy !disabledAgents?.includes(scout);即 scout 可用需要同时满足会话的 spawn 策略允许scoutAllowedBySpawnPolicy可在配置中通过scoutAllowedBySpawnPolicy项设定且未被task.disabledAgents禁用。该可用性状态还会通过scoutAvailable字段注入系统提示词让主代理知道自己能否派 scout 出去。5.3 spawn 策略的解析spawn-policy.ts 提供了isScoutSpawnable作为独立判定函数先检查disabledAgents是否包含 scout再通过resolveSpawnPolicy解析父代理的spawns声明——允许列表为空列表未启用或不允许 scout 时返回 false允许列表包含 scout 或完全不受限*时返回 true。典型的允许场景见 reviewer.mdreviewer 的 frontmatter 声明spawns: scout即代码评审代理可以派出 scout 先行侦察相关代码再基于侦察结果进行评审——这是侦察 → 评审协作流水线的直接证据。5.4 运行期的预算与 read 行为运行期由 executor.ts 负责约束scout 请求软预算为 100 次见上文 2.3 节同时因其read-summarize: false执行器为其注入read.summarize.enabled: false保证侦察读取的是原文而非压缩摘要。六、与其他内置代理的分工协作在 agents.ts 的EMBEDDED_AGENT_DEFS中scout 与以下代理并列内置代理定位与 scout 的关系scout只读快速侦察输出压缩交接信息本文主角reviewer代码评审spawns: scout评审前先派 scout 侦察security-reviewer安全评审可复用 scout 的只读侦察结果task通用多步任务子代理spawns: *、model: task可自由派发 scout 做前置调研sonic低推理机械更新/数据收集model: smol与 scout 共享轻量模型档位从 spawn-policy.ts 看会话默认的 spawn 代理是taskDEFAULT_SPAWN_AGENT而 scout 通常作为 task/reviewer 的下游侦察员被派发。一个典型的多代理流水线是task 规划 → scout 侦察压缩上下文 → 主代理基于 files/architecture 精确跳转 → 针对性编辑整个过程 scout 只读且不产生中间垃圾信息。七、扩展思路如何自定义一个侦察型子代理理解了 scout 的机制后读者可以在自己的编码代理中复刻这一模式。核心配方即 scout 文档呈现的五要素frontmatter 声明只读工具集tools: read, grep, glob可按需加入 web_search选择轻量模型与中等思考model: smolthinking-level: medium关闭摘要管线保真read-summarize: false确保读到原文定义结构化输出契约用output.properties固定summary/files带path:line锚点/architecture并按需开放report固化执行守则搜索优先、并行调用、空结果换策略、按任务推断 thoroughness、严格只读。若要注册自定义代理可参考 agents.ts 中EMBEDDED_AGENT_DEFS的写法——每个条目由fileName、可选frontmatter经 frontmatter.md 模板渲染与template正文组成。结语scout 是 oh-my-pi 编码代理中以最小成本换取最大信息增量的典型设计轻量模型、只读工具集、关闭摘要的原文读取、结构化 JSON 输出再叠加 100 次请求软预算与强制收尾机制使它能在几秒内完成一次仓库侦察并产出一份可供下游代理直接消费的压缩交接上下文。无论是想理解大型代码库的协作式调研架构还是想在自己的 Agent 系统中复刻侦察-交接-执行流水线scout.md 连同 agents.ts、executor.ts、spawn-policy.ts 都是值得精读的参考实现。【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/11 6:09:04 · 阅读 1.2k oh-my-pi 编码代理中的 scout 侦察子代理：只读代码库快速调研与压缩交接协议详解
oh-my-pi 编码代理中的 scout 侦察子代理只读代码库快速调研与压缩交接协议详解【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi导读scout是 oh-my-pi 编码代理coding-agent内置的一款侦察兵子代理专为探索性代码库研究、快速代码分析和广度模式搜索而设计。它以只读方式高速扫描仓库并把调研结果压缩成结构化、可供其他 Agent 直接消费的交接信息避免下游代理重新通读整个代码库。本文以 scout 代理提示词 为骨架逐字段拆解其 frontmatter 配置、JSON 输出契约、执行守则并结合 agents.ts、executor.ts、spawn-policy.ts 等源码说明其实际生效机制帮助读者理解并复用这一低成本、高保真、可交接的调研模式。一、scout 的定位为什么要一个只读侦察子代理在一个由多个子代理协作的编码代理系统中最昂贵的往往是大模型重新读取代码。当主代理需要了解某个模块的现状时如果每次都完整通读整个仓库上下文窗口与 token 成本都会快速失控。scout 的出现正是为了解决这个问题。从 scout.md 的 frontmatter 可以看到它的自我定位description: MUST be used for exploratory codebase research, rapid code analysis, and broad pattern searches. Fast read-only scout returning compressed context for handoff.三个关键词构成了 scout 的全部使命探索性研究面对不熟悉的仓库先派 scout 摸清结构快速代码分析秒级定位关键文件、类型、函数与依赖关系广度模式搜索大量使用 grep/glob 做模式匹配而不是逐个文件精读。它产出的不是我看了什么的过程记录而是你接下来该知道什么的压缩上下文compressed context供后续 agent 直接消费。二、frontmatter 配置逐字段解析scout 的完整配置以 YAML frontmatter 形式写在文档头部系统通过 frontmatter 模板 将name、description、model、thinkingLevel等字段渲染成标准代理定义再由 parseAgent 解析并缓存。各字段含义如下字段值作用namescout代理唯一标识供spawns策略与任务分发引用description见上说明适用场景作为主代理选择子代理的决策依据toolsread, grep, glob, web_search只读工具集精确读文件、正则搜索、glob 找文件、联网检索modelsmol使用轻量小模型运行保证低成本与高速度thinking-levelmedium中等思考强度介于快速查找与深度推演之间read-summarizefalse关闭读取摘要管线read 返回原始内容而非压缩摘要2.1 工具集四件套支撑广度优先scout 只被授予四个工具全部是只读的read读取文件关键段落grep正则搜索做广度模式匹配glob按文件名模式定位候选文件web_search必要时检索外部公开资料辅助理解。注意这里没有 bash、write、edit 等任何可能改变系统状态的工具与文档critical段的只读约束互相印证。从 executor.ts 可以看到当agent.readSummarize false时执行器会向 read 工具注入read.summarize.enabled: false配置即 scout 读到的是文件的真实原文而不是经过摘要压缩的内容——这对需要产出精确path:line引用的侦察任务至关重要。2.2 model: smol 与 thinking-level: mediumsmol是项目内置的轻量模型档位。在 agents.ts 中另一个使用smol的内置代理sonic被描述为strictly mechanical updates or data collection可见这一档位面向机械、批量、低推理需求的任务。scout 同样受益于小模型的低成本但通过thinking-level: medium保留了一定的分析能力使其既能秒级完成搜索又足以梳理架构关系。2.3 请求预算100 次软上限在 executor.ts 的SOFT_REQUEST_BUDGET中scout 与 sonic 均被分配了 100 次请求的软预算默认档位为 200。也就是说 scout 一轮运行中最多驱动约 100 次 assistant 请求逼近预算时会注入收尾提示超支时会被强制收敛到一次yield确保部分发现也能以真实报告的形式回流。这是对快速侦察定位的执行层保障。三、输出协议一份可交接的压缩上下文scout 的产出不是自由文本而是一份结构化 JSON。frontmatter 中通过output.properties定义了严格的 schema这是它与普通读代码然后写总结最本质的区别。3.1 必填字段summary: type: string description: Brief summary of findings and conclusions files: type: array elements: path: string # 项目相对路径可带 :12-34 行号区间 description: string # 该文件相关内容 architecture: type: string description: Brief explanation of how pieces connectsummary调研结论与判断的简短总结供下游代理快速决策files关键文件清单每项包含项目相对路径可附带:12-34这样的行号区间锚点和该文件承载的内容说明。这实际上是一份可信索引让下游代理可以精确跳转无需重新定位architecture各部件如何连接的整体解释回答这段代码是怎么串起来的。3.2 可选字段 reportreport: type: string description: The complete deliverable when the task asks for a report, table, enumeration, or per-item audit — full markdown at the depth requested当任务要求报告、表格、枚举或逐项审计时完整交付物放在report字段中以所请求深度的完整 Markdown 呈现含表格、path:line锚点、函数签名、代码摘录。文档明确强调report绝不是 summary 的重复summary已经承担了概要职责只有快速查询时才允许省略report。这个设计把概要与完整交付物分离summary 始终简短以便交接report 按需全量以完成任务两者互不挤占上下文。四、执行守则directives / thoroughness / procedure / criticalscout 文档正文给出了四条行为守则共同定义了它的工作方式。4.1 directives搜索优先、并行执行、空结果不放弃- You MUST use tools for broad pattern matching / code search as much as possible. - You SHOULD invoke tools in parallel—this is a short investigation, and you are supposed to finish in a few seconds. - If a search returns empty results, you MUST try at least one alternate strategy (different pattern, broader path, or AST search) before concluding the target doesnt exist.三条硬性要求能搜索就不精读尽量用 grep/glob 做广度匹配而不是盲目打开文件必须并行调用工具这是一次几秒钟内结束的短调研串行等待不可接受空结果必须换策略换不同的正则、扩大路径范围或改用 AST 搜索至少尝试一种替代方案后才能下目标不存在的结论——避免假阴性误报。4.2 thoroughness从任务推断深度默认 medium- Quick: Targeted lookups, key files only - Medium: Follow imports, read critical sections - Thorough: Trace all dependencies, check tests/types.scout 不预设固定深度而是从任务推断Quick只做定点查找看关键文件Medium默认跟进 import读取关键段落Thorough追踪全部依赖并检查测试与类型定义。4.3 procedure标准四步流程1. Locate relevant code using tools. 2. Read key sections. NEVER read full files unless theyre tiny. 3. Identify types/interfaces/key functions. 4. Note dependencies between files.四步可归纳为定位 → 精读 → 提炼 → 关联先用工具定位再只读关键片段除非文件很小绝不整文件通读这也是 token 控制的核心然后提炼类型、接口、关键函数最后记录文件间依赖。4.4 critical绝对只读 坚持到底You MUST operate as read-only. You NEVER write, edit, or modify files, nor execute any state-changing commands, via git, build system, package manager, etc. You MUST keep going until complete.两条底线严格只读绝不写、编辑、修改任何文件也不通过 git、构建系统、包管理器等执行任何改变状态的命令坚持完成除非任务被明确终止否则必须运行到产出完整结果。从源码看这一约束是双重保险一方面工具清单里根本没有写类工具另一方面 executor.ts 的注释还揭示了一个细节——所有只读 scout 都不具备hub工具因而永远无法接收 hub 分发的信息从机制上杜绝了只读代理参与信息分发链路。五、源码视角scout 在编码代理中的完整调用链scout 并非独立文档它被编译期嵌入并在会话运行时按需拉起。其完整生命周期如下。5.1 编译期嵌入与解析在 agents.ts 中scout.md 与其他内置代理reviewer、security-reviewer、task 等一起通过 Bun 的import ... with { type: text }在构建期嵌入{ fileName: scout.md, template: scoutMd },加载时由buildAgentContent将正文渲染、经 frontmatter 模板组装再由parseAgent解析 frontmatter 生成AgentDefinition结果缓存于bundledAgentsCache后续通过getBundledAgent(scout)/getBundledAgentsMap()按名取用。5.2 会话层的可用性判定在 agent-session.ts 中会话通过#isScoutAvailable()判断 scout 是否可派发return this.#scoutAllowedBySpawnPolicy !disabledAgents?.includes(scout);即 scout 可用需要同时满足会话的 spawn 策略允许scoutAllowedBySpawnPolicy可在配置中通过scoutAllowedBySpawnPolicy项设定且未被task.disabledAgents禁用。该可用性状态还会通过scoutAvailable字段注入系统提示词让主代理知道自己能否派 scout 出去。5.3 spawn 策略的解析spawn-policy.ts 提供了isScoutSpawnable作为独立判定函数先检查disabledAgents是否包含 scout再通过resolveSpawnPolicy解析父代理的spawns声明——允许列表为空列表未启用或不允许 scout 时返回 false允许列表包含 scout 或完全不受限*时返回 true。典型的允许场景见 reviewer.mdreviewer 的 frontmatter 声明spawns: scout即代码评审代理可以派出 scout 先行侦察相关代码再基于侦察结果进行评审——这是侦察 → 评审协作流水线的直接证据。5.4 运行期的预算与 read 行为运行期由 executor.ts 负责约束scout 请求软预算为 100 次见上文 2.3 节同时因其read-summarize: false执行器为其注入read.summarize.enabled: false保证侦察读取的是原文而非压缩摘要。六、与其他内置代理的分工协作在 agents.ts 的EMBEDDED_AGENT_DEFS中scout 与以下代理并列内置代理定位与 scout 的关系scout只读快速侦察输出压缩交接信息本文主角reviewer代码评审spawns: scout评审前先派 scout 侦察security-reviewer安全评审可复用 scout 的只读侦察结果task通用多步任务子代理spawns: *、model: task可自由派发 scout 做前置调研sonic低推理机械更新/数据收集model: smol与 scout 共享轻量模型档位从 spawn-policy.ts 看会话默认的 spawn 代理是taskDEFAULT_SPAWN_AGENT而 scout 通常作为 task/reviewer 的下游侦察员被派发。一个典型的多代理流水线是task 规划 → scout 侦察压缩上下文 → 主代理基于 files/architecture 精确跳转 → 针对性编辑整个过程 scout 只读且不产生中间垃圾信息。七、扩展思路如何自定义一个侦察型子代理理解了 scout 的机制后读者可以在自己的编码代理中复刻这一模式。核心配方即 scout 文档呈现的五要素frontmatter 声明只读工具集tools: read, grep, glob可按需加入 web_search选择轻量模型与中等思考model: smolthinking-level: medium关闭摘要管线保真read-summarize: false确保读到原文定义结构化输出契约用output.properties固定summary/files带path:line锚点/architecture并按需开放report固化执行守则搜索优先、并行调用、空结果换策略、按任务推断 thoroughness、严格只读。若要注册自定义代理可参考 agents.ts 中EMBEDDED_AGENT_DEFS的写法——每个条目由fileName、可选frontmatter经 frontmatter.md 模板渲染与template正文组成。结语scout 是 oh-my-pi 编码代理中以最小成本换取最大信息增量的典型设计轻量模型、只读工具集、关闭摘要的原文读取、结构化 JSON 输出再叠加 100 次请求软预算与强制收尾机制使它能在几秒内完成一次仓库侦察并产出一份可供下游代理直接消费的压缩交接上下文。无论是想理解大型代码库的协作式调研架构还是想在自己的 Agent 系统中复刻侦察-交接-执行流水线scout.md 连同 agents.ts、executor.ts、spawn-policy.ts 都是值得精读的参考实现。【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考