How 是 pstack 技能集中的一个代码库理解技能,主要回答“X 是如何工作的”这类问题,也适用于修改代码前的通读,以及位置、归属、分层等问题(如“这段代码应该放在哪里”“哪个…”。)
用途 探索代码库并给出架构性解释,程度定位为资深工程师初次接触某个子系统时所需的理解:足够建立可用的心智模型,又不会详细到像逐行注释的源码。
主要能力与执行机制
- 所有派生的子代理都是 Task 子代理,subagent_type 为 generalPurpose,readonly 为 true。
- 探索者使用 pstack 设置文件中的 how explorer 行(Cursor 中为 ~/.cursor/rules/pstack-models.mdc,其他框架中为 ~/.agents/pstack-models.md),默认 grok-4.7-xhigh-fast;解释者使用 how explainer 行,默认 claude-opus-5-5-xhigh。如果设置了 model,就使用该行的值;如果文件或该行缺失,则使用默认值。当值为 auto 或 inherit-parent 时,将 model 留空。若子代理工具拒绝某个 slug,使用默认值并说明;若默认值也被拒绝,则使用其错误信息或框架模型列表中同一家族最接近的有效 slug。每个子代理的推理级别和快速或标准速度按 poteto-mode 技能的 Subagents 一节选择。
使用方式(分步流程)
- 评估复杂度:若范围不明确,先说明解释再探索,用户可纠正。简单问题(单个模块、小型工具、诸如“函数 X 如何工作”的窄问题)不派探索者,直接派一个解释者一次性探索并解释,提示词基于 references/explainer-prompt.md 且不含 explorer-findings 部分,然后进入第 4 步。复杂问题(跨多文件或服务的子系统、横切特性、完整架构概览)进入第 2 步。拿不准时走简单路径。
- 探索(仅复杂问题):把问题拆成 2 至 4 个角度,每个角度是子系统的不同切片;在一条消息中派出全部探索者,每个使用 references/explorer-prompt.md 并填入其角度。
- 综合(仅复杂问题):所有探索者返回后,派一个解释者,使用 references/explainer-prompt.md 并填入全部探索者的发现。
- 呈现:呈现解释者的输出,可为清晰或结合对话上下文做轻微编辑,但不要大幅重写。
其他框架适配 该技能中的派生使用 Cursor 的 Task 工具。其他框架使用各自的子代理工具:Claude Code 用 Agent(subagent_type: general-purpose),OpenCode 用 task(subagent_type: general),Codex 用 spawn_agent。保留提示词和模型,去掉工具不支持的参数。若框架没有子代理工具(如无扩展的 Pi),则依次自行扮演每个角色。
输出格式 解释采用 references/explainer-prompt.md 定义的章节,不适用的章节省略:Overview、Key Concepts、How It Works、Where Things Live、Gotchas。
适用场景 理解子系统工作原理、修改代码前通读、回答代码位置与归属、分层问题、完整架构概览。
限制 需要所依赖的 pstack 技能文件与子代理工具支持;工具拒绝模型 slug 时按上述回退规则处理;设置的模型文件与具体框架路径相关。