用途:回答“X 是如何工作的”问题,输出面向资深工程师接手子系统级别的架构解释,足以建立可用的心智模型,而不会写成逐行注释源码。也用于改动前的代码走读,以及放置、归属、分层问题(如“这个应该放在哪里”“哪个……”)。
主要能力与用法:每次 spawn 都是只读的通用子代理。探索者使用 pstack 模型配置中的 how explorer 行(默认 sonnet),解释者使用 how explainer 行(默认 opus)。用 pstack-harness 技能解析每次 spawn 的模型、effort 与代理类型;其“Spawn a role”部分也涵盖缺少配置、inherit-parent 与被拒绝的值。
流程:先评估复杂度。范围含糊时说明自己的理解再探索,用户可纠正。简单情况(单模块、小工具、窄问题,如“函数 X 如何工作”)不派探索者,只 spawn 一个解释者,依据 references/explainer-prompt.md 并填入 Direct exploration 指令,一次完成探索与解释,省略 Explorer Findings 与 Synthesis,进入第 4 步。复杂情况(跨多文件或服务的子系统、横切特性、完整架构概览)进入第 2 步。拿不准时走简单路径。若仓库有 GitNexus 索引(存在 .gitnexus/)且 PATH 上有 gitnexus,先刷新:自己运行一次 gitnexus analyze --index-only,再 spawn 任何东西(该命令增量执行,已最新时为空操作;绝不要从并行分支运行)。随后播种探索:gitnexus query "<concept>" 查执行流,gitnexus context <symbol> 查调用者/被调用者,gitnexus trace <from> <to> 查两个符号间的路径。图结果用于决定读哪里,代码本身仍是事实来源——索引反映上次分析的提交,看不到未提交改动。无索引或 CLI 时正常探索。无索引但 PATH 上有 gitnexus 时,回答完复杂问题后可向用户建议一次 gitnexus analyze,用于值得再次探索的仓库。
复杂情况:把问题拆成 2 到 4 个角度,每个是子系统的不同切片。单条消息中 spawn 所有探索者,各自填入 references/explorer-prompt.md 与其角度。全部返回后,spawn 一个解释者,带上 references/explainer-prompt.md、每个探索者的发现与 Synthesis 指令,省略 Direct exploration。然后呈现解释者输出,可为清晰或结合对话上下文做轻度编辑,不要大幅重写。
输出格式:使用 references/explainer-prompt.md 定义的章节,不适用则省略:Overview、Key Concepts、How It Works、Where Things Live、Gotchas。
限制:所有 spawn 均为只读;未提供官方收费或价格信息;具体模型默认值(sonnet、opus)来自资料,其余平台细节暂未提供。