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

pstack 的 how 技能实战用并行子代理在 Cursor 中系统化回答“X 是如何工作的”【免费下载链接】pluginsCursor plugin specification and official plugins项目地址: https://gitcode.com/GitHub_Trending/plugins125/pluginshow是 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.mdhow回答代码做了什么、怎么运转why回答是什么力量把它塑造成现在这个样子设计动机、回归、事后复盘、数据支撑的阈值等。二者在 pstack 的teach技能中被串联使用teach先跑how获取工作机制再跑why获取设计缘由然后融合成一份面向人的通俗讲解。值得注意的是how的 frontmatter 中带有disable-model-invocation: true。这意味着它通常不由用户直接以/how之外的方式单独触发而是在poteto-mode这类路由技能的执行流中被按需调用或由用户显式输入/how触发。二、整体流程四步走Step 1 – Step 4how的执行流程分为四个步骤核心是先评估复杂度、再决定是否并行探索步骤名称作用Step 1Assess Complexity评估复杂度判断问题属于简单还是复杂决定走哪条执行路径Step 2aExplore复杂问题专用将问题分解为 2–4 个探索角度并行派发 explorer 子代理Step 2bDirect Explain简单问题专用直接派发单个 Task 子代理边探索边讲解Step 3Synthesize复杂问题专用派发一个 synthesizer 子代理把多路探索发现合成为统一解释Step 4Present呈现把 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:generalPurposemodel: 你配置的 how-explorer 模型默认grok-4.6-fast-xhighreadonly:true只读模式每个 explorer 拿到的基础提示词来自 pstack/skills/how/references/explorer-prompt.md其中会填充各自的探索角度EXPLORATION_ANGLE与原问题QUESTION。该模板要求 explorer 扮演事实收集者角色——另一个代理将根据你的发现撰写面向人的解释所以请优先追求彻底与准确而不是文采。它规定了严格的探索纪律找到入口点Find the entry point什么触发该行为用户动作、API 调用、还是定时任务找到起点。追踪流程Trace the flow从入口沿调用链阅读每个函数弄清数据如何流转与变换。映射关键抽象Map the key abstractions哪些类型、接口、服务、类是核心读它们的定义理解其代表什么、为何存在。找到边界Find the boundaries该子系统如何与其他部分交互输入输出是什么寻找非显然之处Look for the non-obvious任何令人意外的东西、历史遗留痕迹、新人容易误解之处。模板还明确要求 explorer不要凭空猜测Dont 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 子代理让它在一次通过中完成探索 讲解两件事不再单独派发 explorersubagent_type:generalPurposemodel: 你配置的 how-explainer 模型默认claude-fable-5-1-thinking-maxreadonly:true它的提示词同样基于 explainer-prompt.md 构建但去掉其中的 explorer-findings探索发现部分因为没有并行探索环节。构建完成后直接进入 Step 4 呈现。六、Step 3复杂问题的合成Synthesize当所有 explorer 返回后how派发一个Task 子代理将多路发现合成为一份统一解释subagent_type:generalPurposemodel: 你配置的 how-explainer 模型默认claude-fable-5-1-thinking-maxreadonly:truesynthesizer 的提示词同样来自 explainer-prompt.md但填入每个 explorer 的全部发现EXPLORER_FINDINGS_ALL。模板明确要求 synthesizer调和Reconcile各 explorer 分别调查同一子系统的不同角度发现会重叠、偶尔会矛盾。必须合并重叠描述、通过自己查代码解决矛盾、把分散的切片拼成统一图景。面向对象写给不熟悉该领域的高级工程师让其读完就建立起扎实的心智模型足以自信地开始动手。保持只读synthesizer 拥有代码库只读访问权限可用 Read/Grep/Glob 核查细节或填补空白explorers 已经做了重活你不应该从头再探索一遍。诚实面对缺口如果 explorer 标记了开放问题或空白要承认它们而不是隐藏。七、Step 4呈现Presentsynthesizer或简单路径下的 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 n1 when we look up every run to cancel?——可见它擅长承载先讲机制、再顺带排查性能隐患如 N1 查询这类复合问题。十二、最佳实践与注意事项小结综合 SKILL.md 与配套模板使用how时值得记住的实践要点包括拿不准复杂度就走简单路径避免为窄问题付出并行探索的代价。范围模糊时先亮出你的理解再探索把纠偏权交给用户而不是阻塞等待。explorer 只收集事实讲解交给 explainer两者职责分离保证并行探索的覆盖面与最终解释的质量。explorer 必须只读且诚实readonly: true杜绝副作用无法追踪的连接要明确写出不编造。synthesizer 负责调和矛盾发现冲突时以查代码为准而不是简单采信某一路。输出遵循五段式骨架并视问题裁剪涉及多组件流转时用 mermaid 图澄清而非装饰。呈现阶段克制编辑保证探索与合成成果的客观性不被重写破坏。模型可配通过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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考