pstack 的 how 技能实战：用并行子代理在 Cursor 中系统化回答“X 是如何工作的”

pstack 的 how 技能实战：用并行子代理在 Cursor 中系统化回答“X 是如何工作的”

【免费下载链接】pluginsCursor plugin specification and official plugins项目地址: https://gitcode.com/GitHub_Trending/plugins125/plugins

how是 pstack 插件中专门用于回答代码库“how does X work?”类问题的技能：它按复杂度区分简单与复杂问题，为复杂问题并行派发只读 explorer 子代理做切片探索，再由 explainer 子代理统一合成为一份资深工程师级的架构解释。读完本文，你将掌握how的完整工作流、两套子代理提示词模板的结构与使用方式、其输出格式规范，以及它如何与why、teach、poteto-mode的 investigation playbook 协作，并学会通过setup-pstack自定义参与探索与讲解的模型。

一、how技能定位：回答“怎么工作的”，而非“为什么这么设计”

how是一个 Cursor Skill，定义于 pstack/skills/how/SKILL.md。它的前导元数据（frontmatter）明确划定了触发场景：

• 用于回答"how does X work"类问题；
• 用于改动代码之前的代码走读（code walkthroughs）；
• 用于归属/职责/分层类问题：如"这段逻辑应该放在哪""哪个包拥有这段逻辑""这是不是正确的层"；
• 它能解释子系统架构、运行时流程，并帮助新人建立心智模型（onboarding mental models）。

与之形成互补的是why技能（pstack/skills/why/SKILL.md）：how回答代码"做了什么、怎么运转"，why回答"是什么力量把它塑造成现在这个样子"（设计动机、回归、事后复盘、数据支撑的阈值等）。二者在 pstack 的teach技能中被串联使用：teach先跑how获取工作机制，再跑why获取设计缘由，然后融合成一份面向人的通俗讲解。

值得注意的是，how的 frontmatter 中带有disable-model-invocation: true。这意味着它通常不由用户直接以/how之外的方式单独触发，而是在poteto-mode这类路由技能的执行流中被按需调用，或由用户显式输入/how触发。

二、整体流程：四步走（Step 1 – Step 4）

how的执行流程分为四个步骤，核心是"先评估复杂度、再决定是否并行探索"：

步骤	名称	作用
Step 1	Assess Complexity（评估复杂度）	判断问题属于简单还是复杂，决定走哪条执行路径
Step 2a	Explore（复杂问题专用）	将问题分解为 2–4 个探索角度，并行派发 explorer 子代理
Step 2b	Direct Explain（简单问题专用）	直接派发单个 Task 子代理，边探索边讲解
Step 3	Synthesize（复杂问题专用）	派发一个 synthesizer 子代理，把多路探索发现合成为统一解释
Step 4	Present（呈现）	把 explainer 的输出交给用户，仅做轻度编辑

其中 Step 2a、Step 2b 与 Step 3 是二选一的两条路径：简单问题走 2b → 4，复杂问题走 2a → 3 → 4。

三、Step 1：先评估复杂度，拿不准就走简单路径

SKILL.md 要求在执行任何子代理派发前先对问题范围做复杂度评估：

• Simple（简单）：问题只涉及单个模块、一个小工具、或一个窄范围问题（如"函数 X 是怎么工作的"）。此时不派发 explorer，由一个 explainer 子代理在一次通过中完成探索与讲解，直接进入 Step 2b。
• Complex（复杂）：问题横跨多个文件或多个服务（子系统级）、是跨切面特性、或要求完整的架构总览。此时先并行派发 explorer，再把结果交给 explainer，进入 Step 2a。

SKILL.md 给出了一个明确的决策原则：When in doubt, take the simple path（拿不准时，走简单路径）。这避免了为窄问题过度消耗子代理与上下文窗口，与 pstack 一贯的"最小化读者负载、守护上下文窗口"原则一致。

另外，如果问题范围本身有歧义，how要求：先陈述你对问题的理解，然后开始探索，让用户随时可以纠正方向，而不是停下来反复追问。

四、Step 2a：复杂问题的并行探索（Explorer）

对于复杂问题，how将原问题分解为 2 到 4 个探索角度，每个角度都是该子系统的不同切片，并在同一条消息中一次性派发所有 explorer，让它们真正并行运行。每个 explorer 的子代理配置为：

• subagent_type:generalPurpose
• model: 你配置的 how-explorer 模型（默认grok-4.6-fast-xhigh）
• readonly:true（只读模式）

每个 explorer 拿到的基础提示词来自 pstack/skills/how/references/explorer-prompt.md，其中会填充各自的探索角度（EXPLORATION_ANGLE）与原问题（QUESTION）。该模板要求 explorer 扮演"事实收集者"角色——"另一个代理将根据你的发现撰写面向人的解释，所以请优先追求彻底与准确，而不是文采"。它规定了严格的探索纪律：

1. 找到入口点（Find the entry point）：什么触发该行为？用户动作、API 调用、还是定时任务？找到起点。
2. 追踪流程（Trace the flow）：从入口沿调用链阅读每个函数，弄清数据如何流转与变换。
3. 映射关键抽象（Map the key abstractions）：哪些类型、接口、服务、类是核心？读它们的定义，理解其代表什么、为何存在。
4. 找到边界（Find the boundaries）：该子系统如何与其他部分交互？输入输出是什么？
5. 寻找非显然之处（Look for the non-obvious）：任何令人意外的东西、历史遗留痕迹、新人容易误解之处。

模板还明确要求 explorer不要凭空猜测（"Don't guess from names. Read the code."），并诚实汇报无法追踪的部分——"我无法确定 X 如何与 Y 连接"远好于编造。探索发现的输出被规范化为六个小节：Components Found（组件清单）、Flow（执行流程）、Files Read（已读文件）、Boundaries（边界）、Non-Obvious Things（非显然之处）、Open Questions（未解问题），且要求尽可能给出精确的文件路径、函数名、类型名与行号。

五、Step 2b：简单问题的直接讲解（Direct Explain）

如果问题属于简单类别，how只派发一个Task 子代理，让它在一次通过中完成"探索 + 讲解"两件事，不再单独派发 explorer：

• subagent_type:generalPurpose
• model: 你配置的 how-explainer 模型（默认claude-fable-5-1-thinking-max）
• readonly:true

它的提示词同样基于 explainer-prompt.md 构建，但去掉其中的 explorer-findings（探索发现）部分，因为没有并行探索环节。构建完成后直接进入 Step 4 呈现。

六、Step 3：复杂问题的合成（Synthesize）

当所有 explorer 返回后，how派发一个Task 子代理，将多路发现合成为一份统一解释：

• subagent_type:generalPurpose
• model: 你配置的 how-explainer 模型（默认claude-fable-5-1-thinking-max）
• readonly:true

synthesizer 的提示词同样来自 explainer-prompt.md，但填入每个 explorer 的全部发现（EXPLORER_FINDINGS_ALL）。模板明确要求 synthesizer：

• 调和（Reconcile）：各 explorer 分别调查同一子系统的不同角度，发现会重叠、偶尔会矛盾。必须合并重叠描述、通过自己查代码解决矛盾、把分散的切片拼成统一图景。
• 面向对象：写给"不熟悉该领域的高级工程师"，让其读完就建立起扎实的心智模型，足以自信地开始动手。
• 保持只读：synthesizer 拥有代码库只读访问权限，可用 Read/Grep/Glob 核查细节或填补空白；"explorers 已经做了重活，你不应该从头再探索一遍"。
• 诚实面对缺口：如果 explorer 标记了开放问题或空白，要承认它们，而不是隐藏。

七、Step 4：呈现（Present）

synthesizer（或简单路径下的 explainer）返回后，how将输出直接呈现给用户。SKILL.md 明确限制：可以做轻度编辑以提升清晰度或结合对话上下文，但不得实质性重写（Do not substantially rewrite it）——这是为了保住探索与合成环节产出的客观事实与证据完整性。

八、输出格式规范：Explainer 的五段式骨架

how的输出格式由 explainer-prompt.md 定义，按问题适配，不适用的段落可去掉：

段落	内容要求
Overview（概述）	1–2 段。这是什么、做什么、为什么存在。读者只看这一段就能决定是否继续读下去。
Key Concepts（关键概念）	理解后续内容所需的重点类型、服务或抽象，简明定义即可，不必穷尽。
How It Works（工作原理）	解释的核心，也是最长的一节。按流程推进：什么触发它、逐步发生了什么、数据流向哪里、决策点在哪。用散文而非伪代码；引用具体文件和函数供读者定位，但不要大段贴代码。多组件交互或数据分阶段变换时，用 mermaid 画图（时序图、流程图、组件图）或用 ASCII 图表达更简单的关系；图是为了澄清而非装饰，散文讲清楚流程时就不必画图。
Where Things Live（代码在哪里）	简短的目录/文件地图，只列开始动手时需要的那几个。
Gotchas（易错点）	非显然的、令人意外的、历史背景、陷阱。没有值得说的就跳过。

模板还规定了沟通风格要求：用具体语言而非"关于抽象的抽象"（例如写"UserService调用了AuthClient.refresh()"，而不是"服务把任务委托给了客户端"）；复杂的地方要解释为什么复杂，而不要只描述复杂度；简单的地方不要注水；有合适的类比就用，没有就不要硬造。

九、配套子代理提示词模板：如何按需填充

两个 references 文件都是带占位符的模板，how技能在运行时负责填充：

• pstack/skills/how/references/explorer-prompt.md：填充{QUESTION}与{EXPLORATION_ANGLE}，派发给并行 explorer。模板开头会提醒每个 explorer："其他探索者正在并行调查同一子系统的不同切片，不要试图覆盖一切，聚焦分配给你的角度并深入。"
• pstack/skills/how/references/explainer-prompt.md：填充{QUESTION}与{EXPLORER_FINDINGS_ALL}（复杂路径）或仅{QUESTION}（简单路径），派发给 explainer/synthesizer。

这两个模板本身就是可复用的资产：即便脱离how技能，你也可以在自定义子代理编排中直接借鉴"先并行收集事实、再统一合成解释"的提示词分层设计。

十、模型配置：通过 setup-pstack 覆盖默认模型

how技能中涉及两类模型角色，均有默认值：

• how explorer：默认grok-4.6-fast-xhigh（并行探索用，追求速度与广度）
• how explainer：默认claude-fable-5-1-thinking-max（讲解合成用，追求判断与表达）

这些默认值可以通过 pstack 的 setup-pstack 技能 覆盖。setup-pstack会检测你当前会话可用的模型 slug，然后向~/.cursor/rules/pstack-models.mdc写入一条alwaysApply: true的规则，逐角色指定模型。其中与how相关的两行规则形如：

how explorer: grok-4.6-fast-xhigh how explainer: claude-fable-5-1-thinking-max

删除某一行即回退到技能内置默认值；值也可设为inherit-parent或auto，表示该角色沿用父级对话模型。pstack 的模型配置思路是"每个技能读取该规则文件、缺省时回退到合理默认值"，因此你只需覆盖想改的角色。

十一、在 pstack 生态中的位置：与 investigation、why、teach 的协作

how不是孤立存在的技能，它与 pstack 的多个技能形成分工协作网络：

• investigation playbook：在 poteto-mode 的 investigation playbook 中，只读型调查问题（"how does x work, why was y built this way, are we sure"）被要求路由到how技能；若是动机类问题还要同时路由到why技能。产出格式即how的五段式（Overview / Key Concepts / How It Works / Where Things Live / Gotchas），或对决策类问题给出带权衡表的建议，最后还要过一遍unslop技能清理文风。由此可见，how是 pstack 面对只读探索型任务时的默认执行引擎。
• why 技能：why 是how的"动机侧"伴侣，回答"为什么代码长成这个样子"，两者在 README 的技能表中被并排列出，供用户按需选用。
• teach 技能：teach 明确"站在how和why之上"——它会并行运行这两个技能，把结果织成一份通俗、按学习者节奏推进的讲解（配图采用逐图叠加的构建式画法），但保留why的置信度措辞不变。
• README 使用示例：pstack 的 README 给出了一条典型的how直接调用示例：/how do we cancel runs? do we have an n+1 when we look up every run to cancel?——可见它擅长承载"先讲机制、再顺带排查性能隐患（如 N+1 查询）"这类复合问题。

十二、最佳实践与注意事项小结

综合 SKILL.md 与配套模板，使用how时值得记住的实践要点包括：

1. 拿不准复杂度就走简单路径，避免为窄问题付出并行探索的代价。
2. 范围模糊时先亮出你的理解再探索，把纠偏权交给用户，而不是阻塞等待。
3. explorer 只收集事实，讲解交给 explainer；两者职责分离，保证并行探索的覆盖面与最终解释的质量。
4. explorer 必须只读且诚实：readonly: true杜绝副作用；无法追踪的连接要明确写出，不编造。
5. synthesizer 负责调和矛盾：发现冲突时以查代码为准，而不是简单采信某一路。
6. 输出遵循五段式骨架，并视问题裁剪；涉及多组件流转时用 mermaid 图澄清，而非装饰。
7. 呈现阶段克制编辑：保证探索与合成成果的客观性不被重写破坏。
8. 模型可配：通过setup-pstack的how explorer/how explainer两行规则，把探索与讲解分别映射到适合的模型。

how的价值在于把"读懂一段代码"从随机的个人能力，变成一条可复现、可并行、可审计的工程流程：复杂度评估控制成本，并行 explorer 摊薄探索时间，专职 explainer 保证讲解深度，固定输出骨架让结果对后续的poteto-mode、teach等流程可直接消费。对任何想要在 Cursor 中获得"深度优先"代码理解能力的团队，它都是一个可以直接落地的范式。

【免费下载链接】pluginsCursor plugin specification and official plugins项目地址: https://gitcode.com/GitHub_Trending/plugins125/plugins