跳转到内容
pstack 中文学习站
learn-pstack

why

你在看 pstack 0.15.17 时的版本，最新版在这里

Why

Section titled “Why”

调查代码背后的动机与意图。配套的 how skill 回答代码做什么、如何工作。why 回答是什么力量塑造了它的形态。

下面每次 spawn 都对应 pstack-models.mdc 规则中的一行角色及其默认值。将 model 设为该行值；若规则或该行缺失，则用默认值。当值为 auto 或 inherit-parent 时，不设置 model。若 Task 工具拒绝某 slug，改用默认值并说明。若默认值也被拒绝，从其错误信息中选取同系列最接近的有效 slug。

每次启动都是 generalPurpose，readonly 为 false（agent 模式）。不要用 readonly/Ask 模式。 它会去掉 MCP，依赖 MCP 的调查员和合成器的引用抽查都会失效。调查员仍然不该写任何东西。

操作姿态

Section titled “操作姿态”

以谨慎、保守、精确的调查者身份工作。诚实区分已知与推断。完整置信度框架与措辞指南见 references/epistemics.md。合成器必须遵循它。

第 1 步：理解目标与问题

Section titled “第 1 步：理解目标与问题”

目标通常是某段代码、某种模式、某个功能，或一项具名设计决策。问题通常是设计理由、权衡、驱动边缘情况的动机、外部约束、死代码，或一次广泛的历史梳理。

若目标模糊（例如「我们为什么这样做？」却没有明确指代），根据对话上下文（打开的文件、最近编辑、光标位置、刚讨论的内容）做最佳猜测。简要说明你的理解，以便用户纠正，然后继续。

第 2 步：建立代码锚点

Section titled “第 2 步：建立代码锚点”

在 spawn 调查员之前，把种子上下文内联建好：文件路径和行范围、关键符号（函数、类、常量）、最近触及该目标的若干次提交、合并提交主题行里的 PR 编号（(#1234) 这种模式），以及任何关联的工单 ID。用 git blame -L <start>,<end> <file> 查最后改动这些行的提交，用 git log --follow -p -- <file> 看跟踪重命名的完整历史和补丁，用 git log --oneline -20 -- <file> 看最近提交和其中的 PR 编号，用 git log -1 --format=%B <commit> 抽出 PR 编号。然后对任何实质性提交拉取 PR 正文和讨论：gh pr view <number> --json title,body,author,createdAt,mergedAt,labels,closingIssuesReferences,comments,reviews。这份锚点要交给每个调查员和合成器。

第 3 步：Spawn 并行调查员

Section titled “第 3 步：Spawn 并行调查员”

默认采用完整并行调查。 目标是一张完整的覆盖图，不是最小的那张。记录空结果，不要跳过搜索。

发现

Section titled “发现”

spawn 调查员之前，列出 Cursor 环境中可用的 MCP。若有 available-tools 映射则使用；否则检查 Cursor 暴露的 mcps/ 目录中已启用的 MCP 服务器。

将每个可用 MCP 映射到一个证据类别：

  1. 源码控制历史
  2. 工单 / ticket 跟踪
  3. 长文文档
  4. 实时团队聊天
  5. 基础设施可观测性
  6. 错误 / 异常跟踪
  7. 产品分析数仓

源码控制始终可通过 git 与 gh 访问。对其余六类，根据 MCP 名称、服务器说明、工具名与资源描述分类。若某 MCP 可归属多类，选与其主要证据最匹配的一类。模糊情况记入覆盖图。

每个有匹配 MCP 的类别 spawn 一名调查员，全部放在同一条消息里并发跑，每人恰好负责一个工具或 MCP。不要让一个 agent 覆盖多个 MCP。model：why investigators 那一行，默认 grok-4.7-xhigh-fast。

每个调查员的提示词是填好的 references/investigator-prompt.md，再加上：

  • 所选 MCP 的类别 playbook references/sources/<source>.md，按 references/source-playbook.md 里的例子改写
  • 如果目标代码看起来有防御性（空值检查、重试、超时、限流、功能开关、出口守卫、OOM 处理），再加上 references/sources/incident-postmortem.md
  • 代码锚点和用户原来的问题

调查员名册，每个有证据的类别一名

Section titled “调查员名册，每个有证据的类别一名”

下面每一类都能揭示一种别的来源给不了的「为什么」，写在「最擅长」后面。用它来知道该期待什么、某一类空着时怎么称呼这个缺口，以及只在极少、能证明不相关的情况下，说明为什么跳过。

  1. 源码控制（Git 历史、用 gh 查 PR、代码注释、测试）。始终 spawn，这是唯一保证有的来源。最擅长评审当时记下来的实现理由。
  2. 工单 / ticket 跟踪（如 Linear、Jira、GitHub Issues、Plane、Shortcut MCP）。最擅长产品或业务上的推动力。当「为什么」在工程之外时最强。
  3. 长文文档（如 Notion、Confluence、Google Docs、Coda MCP）。最擅长写成文字的设计理由，在变成代码之前就写下来的那种。
  4. 实时团队聊天（如 Slack、Discord、Microsoft Teams、Mattermost MCP）。最擅长没写进文档的实时讨论。源码控制、工单和文档的纸面痕迹很薄时尤其重要。
  5. 基础设施可观测性（如 Datadog、New Relic、Honeycomb、Grafana、Splunk MCP）。最擅长促使写出这段代码的基础设施和运行时现实。目标在对基础设施信号做反应时最强（超时、重试、限流、熔断）。
  6. 错误 / 异常跟踪（如 Sentry、Rollbar、Bugsnag、Airbrake MCP）。最擅长促使写出防御或纠正代码的具体异常和错误轨迹。对 catch 块、空值守卫、类型检查、重试和其他防御最强。
  7. 产品分析数仓（如 Databricks、Snowflake、BigQuery、ClickHouse、dbt、Redshift MCP）。最擅长塑造代码的产品和数据现实。对功能开关后面的代码、实验驱动的发布、数据迁移，以及「这个数字从哪来」最强。

何时跳过某调查员

Section titled “何时跳过某调查员”

只有写明的理由才能跳过，理由写进最终的已查阅来源。两种有效理由：

  • 该类别在本环境没有可用的 MCP。标成缺口，不是选择：「实时团队聊天已跳过。无匹配 MCP，对话记录不可搜索。」
  • 来源可以证明不相关，不是「大概不相关」。门槛很高：「错误 / 异常跟踪已跳过。目标是构建期脚本，没有运行时路径。」

若范围评估表明是单提交琐碎目标且 PR 描述已含完整答案，可在确认全部七个可用类别搜索都会冗余后内联回答。明确说明。应属罕见。

第 4 步：合成

Section titled “第 4 步：合成”

spawn 一名合成器。model：why synthesizer 那一行，默认 claude-opus-5-5-xhigh。它拿到：

  1. 调查员的发现，包括空结果和写明理由后跳过的类别
  2. 代码锚点
  3. 用户原来的问题
  4. references/epistemics.md 里的认识论框架
  5. references/synthesizer-prompt.md 里的合成器提示词模板

第 5 步：呈现

Section titled “第 5 步：呈现”

把合成器的输出呈现给用户。为了更清楚，或为了补上对话里的上下文，可以小改，但不要改写置信度措辞。

输出格式

Section titled “输出格式”

结构见 references/synthesizer-prompt.md：问题、相关代码、已经查到的、可以合理推断的、竞争假设、还不知道的、已查阅来源、置信度摘要。可按需调整，但保持置信度分开，且已查阅来源每个调查员一行，包括没有结果或被跳过的，并写上理由。

已查阅来源之后，如果用户的 why 问题是改这段代码的前奏，把溯源发现转成一套 Preserve / Change / Avoid / Risk 约束，用来规划这次改动。

常见失败模式（避免）

Section titled “常见失败模式（避免）”
  • 近因偏误。假设最近提交即权威。当前形态往往是更早决策的累积。要追溯。

本目录的其他译文

Section titled “本目录的其他译文”