1实现原理 · 为什么它能做到

纯 prompt 编排、零脚本零资产：how 的 SKILL.md 只规定『如何拆解与委派』，所有读代码的动作都交给宿主 Task 子代理，自带两个 prompt 模板（explorer/explainer）作为唯一参照物。

pstack/skills/how/SKILL.md

Explore the codebase to answer "how does X work?" questions. Produce architectural explanations at the level of a senior engineer onboarding onto a subsystem, enough to build a working mental model, not so much that it reads like annotated source code.

定位是『senior engineer onboarding 级心理模型』，刻意排除逐行注释式流水账——这是输出质量的锚。

复杂度路由：简单问题单遍 explainer 直出；复杂问题先按 2-4 个角度并行派 explorer 切片深挖，再交给 explainer 合成；拿不准默认走简单路径。

pstack/skills/how/SKILL.md

**Simple** (a single module, a small utility, a narrow question such as "how does function X work"): no explorers. One explainer explores and explains in a single pass. Go to Step 2b.

并行度由问题真实复杂度决定；'When in doubt, take the simple path.' 防止小题大做、空转多个子代理。

explorer 全部只读、并行、一次消息齐发：每路一个 generalPurpose 子代理，model 取配置（默认 grok-4.6-fast-xhigh），readonly 恒为 true——探查层被设计成无副作用的事实采集器。

pstack/skills/how/SKILL.md

Decompose the question into 2 to 4 exploration angles, each a distinct slice of the subsystem. Spawn all explorers in a single message

同段下方逐项列出 subagent_type: generalPurpose、model: your configured how-explorer model (default `grok-4.6-fast-xhigh`)、readonly: true——三处 spawn 块（2a/2b/3）全部标注 readonly。

explorer 产出是固定结构的事实契约（Components Found / Flow / Files Read / Boundaries / Non-Obvious Things / Open Questions），并把『读代码不许猜』与『诚实承认断点』写成硬要求。

pstack/skills/how/references/explorer-prompt.md

Start by finding the relevant code. Use Glob to find directories and files, Grep to find key symbols, Read to understand the actual implementation. Don't guess from names. Read the code.

模板尾部另有 'Return your findings in this structure…Reference exact file paths, function names, type names, and line numbers where relevant.' 与 '"I couldn't determine how X connects to Y" is better than making something up.'——输出结构化是为了让 explainer 能交叉核对，不许粉饰。

explainer 负责调停与再验证：多路 explorer 发现重叠或矛盾时，explainer 先自行查码消解再写解释，且被授予只读复查权（Read/Grep/Glob），不需要从零重探。

pstack/skills/how/references/explainer-prompt.md

Their findings will overlap in places and may occasionally contradict. Reconcile them. Merge overlapping descriptions, resolve contradictions by checking the code yourself, and combine the separate slices into a unified picture.

这是把『并行切片→合并』做成两级流水线：explorer 求深，explainer 求整合，矛盾以源码为准。

输出格式与呈现纪律：解释按固定章节（Overview/Key Concepts/How It Works/Where Things Live/Gotchas，可裁剪），复杂流允许 mermaid/ASCII 图但禁装饰性图；前台只做轻度润色，禁止大幅改写。

pstack/skills/how/SKILL.md

Present the explainer's output to the user. Light edits for clarity or context from the conversation are fine. Do not substantially rewrite it.

章节清单在 SKILL.md Output Format 段原文列出；图的使用规则在 explainer-prompt.md：'Use mermaid (```mermaid) for structured flows…A diagram should clarify, not decorate.'

触发面收窄为用户显式调用，且模型角色可配置：frontmatter 声明 disable-model-invocation: true，模型默认值可被 pstack 常驻模型规则覆盖。

pstack/skills/how/SKILL.md

disable-model-invocation: true

『your configured how-explorer model』的配置来源在 pstack 家族其它 skill 明文：setup-pstack/SKILL.md 'Write `~/.cursor/rules/pstack-models.mdc`, an always-applied rule that sets pstack's model per role.'、interrogate/SKILL.md 同引该路径；how 自身只声明默认值与回退语义，不写文件。

2核心能力

01代码走读式解释（how does X work / 子系统架构 / 运行时流）

02放置/归属/分层判断（where should this live / which package owns this / is this the right layer）

03简单问题单遍直答（不派子代理）

04复杂问题 2-4 路并行只读探查后统一合成

05只读纪律贯穿全链（explorer 与 explainer 均 readonly: true）

06反编造查证：explorer 必须实读代码并列出 Files Read，explainer 允许自行复查消解矛盾

07按需图示：mermaid（结构化流）或 ASCII（简单关系），禁止为装饰而图

4管控建议与判定依据

建议配套管控措施

面向 Agent

限定工作目录

面向管理者

保留操作记录

判定依据（文件路径与关键语句摘要）

本地文件: 操作本地工程文件或工作目录工件

审计说明： 。接触面=宿主 Task 下 readonly 子代理对本地代码库的只读访问，以及经由常驻规则注入的本地模型配置（~/.cursor/rules/pstack-models.mdc，仅模型名、非凭证）；无脚本执行、无网络外发、无凭证读取、无本地写入；disable-model-invocation: true 仅用户显式调用（/how）。注意点：readonly 为提示词级约束、子代理读范围以宿主授权为界。

5第二遍独立确认

[ok] 纯 prompt、无脚本资产 — 技能目录仅 SKILL.md + references/explorer-prompt.md + references/explainer-prompt.md 三个 markdown，无 scripts/data/模板之外文件。
[ok] 复杂度路由与默认简单路径 — SKILL.md 原文 'When in doubt, take the simple path.' 存在；Simple→2b、Complex→2a→3 的流程编号自洽。
[ok] 2-4 路并行 explorer + 单一 explainer 合成 — 原文 'Decompose the question into 2 to 4 exploration angles'、'Spawn all explorers in a single message'、'synthesize their findings into one explanation' 逐字在。
[ok] readonly 贯穿 — Step 2a/2b/3 三处均列 '- `readonly`: `true`'；模板无任何写盘/执行指令。
[ok] explorer 输出契约与反编造要求 — explorer-prompt.md 含完整小节标题（Components Found 等六个）、'Don't guess from names. Read the code.'、以及 'is better than making something up' 原文。
[ok] explainer 调停矛盾 + 只读复查 — 原文 'resolve contradictions by checking the code yourself' 与 'You have read-only access to the codebase' 均在。
[ok] 输出格式/呈现纪律 — SKILL.md 列出的五章节与模板 Output Format 一致；'Light edits for clarity…do not substantially rewrite it.' 逐字存在。
[ok] 模型可配置（how-explorer/how-explainer） — how 内仅声明默认值；配置写入/读取路径在 setup-pstack（写 ~/.cursor/rules/pstack-models.mdc）与 interrogate/arena/swarm（读同文件）一致，机制真实存在；角色键 how-explorer/how-explainer 的逐键映射未在 pstack 内单点列出，属『规则文件按角色键注入』的通用机制 [INFERENCE]，已在正文限定表述。

6结论

只读委派把『读代码』的成本与风险隔离在 readonly 子代理里，主会话不被大段源码淹没，输出只有一份整合解释。

并行切片→单一合成者的两级结构对复杂子系统有真实的提速与深度收益，且矛盾以源码复查为准而非投票。

输出契约化：固定章节 + 反编造 + 诚实标注断点，解释可被读者/其他 agent 复核到具体 file/function。

零依赖零写入，跨宿主可整目录搬移；与 pstack 家族（why/teach/poteto-mode）通过 description 与模型规则自然衔接。

适合： 适合改动任何不熟悉代码前先建心理模型的场景：跨服务/跨模块子系统上手、'这段逻辑为什么这样走'、新成员 onboarding、把架构讲给下一个 agent 或人；也适合作为其它工程 skill 的只读探查原语被复用（teach 已这样用）。

不适合： 不适合动机/权衡/历史背景类问题（description 明确交给 why：'Use why for motivation.'）；不适合需要留下文档产物的场景（它只答不写，要落盘应选 teach 或其它写文档的 skill）；不适合极小的一次性疑问（简单路径虽省子代理，仍偏重）；不适合需要跑代码验证行为的场景（纯静态读码，动态行为请用验证类 skill）。

Install Agent-Ready

① Verified Mirror 2026-09-09

Option A · Direct DownloadDownload how.tar.gz

sha256: ee70ff35028506ef…

Option B · Copy Guide for Agent

install.json

agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。

② Upstream GitHub

GitHub Repo ↗

Pinned to commit df3fb154fb.