pstack Why 技能的证据源手册面向七类 MCP 的并行取证 Playbook 全解析【免费下载链接】pluginsCursor plugin specification and official plugins项目地址: https://gitcode.com/GitHub_Trending/plugins125/plugins导读本文深入解析 pstack 插件中why技能用于回答这段代码为什么长成这样的**证据源手册Source Playbooks**体系。why技能会为每类可用的证据来源并行派出一个调查者investigator每个调查者阅读一份与自身证据类别对应的专项 Playbook据此在各自的 MCP 中取证。读完本文你将掌握七类证据源源码控制历史、工单追踪、长文档、实时聊天、基础设施可观测性、错误追踪、产品分析数仓各自的取证策略、证据识别标准、常见陷阱与结果回报格式并能把示例 Playbook 适配到同类的其他 MCP 上。一、Source Playbooks 的定位每类证据源一份的取证手册pstack/skills/why/references/source-playbook.md 是整个why技能取证体系的索引中枢。它本身不承载某个具体证据源的细节而是解决两个问题分类将可用的 MCP 证据来源划分为七类每类对应一份独立的自包含 Playbook适配原则Playbook 是针对常见 MCP 编写的具体示例同一类别下的其他 MCP 需要按示例自行适配。正如 SKILL.md 所述why技能回答的是什么力量塑造了这段代码的形态——它不同于how技能代码做什么、怎么工作而是追溯设计动机、权衡取舍、回归原因与数据支撑的阈值来源。调查的答案是证据驱动的动机存在于 commit、PR、工单、文档和对话里而这些证据恰好分散在七类来源中因此需要一个调查者负责一类来源的并行架构。每个调查者的 Prompt 由 investigator-prompt.md 模板拼装而成模板中会追加一份与该调查者证据类别匹配的 source playbook索引见 source-playbook.md如果目标代码呈现防御性特征null 检查、重试、超时、限流、特性开关、出口护栏、OOM 处理还会再追加横切的 incident-postmortem.md。七类证据源与示例 MCP 总览原文档给出的分类表是整套体系的骨架完整继承如下类别Playbook示例 MCP源码控制历史code-archaeology.mdgit、gh工单 / 追踪器linear.mdLinear适配 Jira、GitHub Issues、Plane、Shortcut长文档notion.mdNotion适配 Confluence、Google Docs、Coda实时团队聊天slack.mdSlack适配 Discord、Microsoft Teams、Mattermost基础设施可观测性datadog.mdDatadog适配 New Relic、Honeycomb、Grafana、Splunk错误 / 异常追踪sentry.mdSentry适配 Rollbar、Bugsnag、Airbrake产品分析数仓databricks.mdDatabricks SQL适配 Snowflake、BigQuery、ClickHouse、dbt另有横切角度 incident-postmortem.md当目标代码看起来是防御性写法null 检查、重试、超时、限流、特性开关、出口护栏、OOM 处理时追加。二、源码控制历史code-archaeology.md——最可信、最完整的证据源code-archaeology.md 被称为最可信、最完整的证据源——它直接绑定代码本身所有经过仓库的东西都应该在这里留下痕迹。2.1 这个来源包含什么提交历史消息、日期、作者、diff通过gh获取的 PR 描述、评审评论与讨论线程行内代码注释、TODO、FIXME、弃用说明仓库内的 ADR架构决策记录若维护测试测试名与断言往往编码了促成一次变更的边界用例同一提交内修改的相关文件共同变更信号仓库内的 CHANGELOG 条目、发布说明提交消息与 PR 正文中提到的工单 ID2.2 怎么搜索从种子提交列表展开# 穿越重命名的完整文件历史 git log --follow --oneline -- file # Pickaxe新增或删除了这段精确文本的提交 git log -S exact_string_from_code -- file # 或使用正则模式 git log -G regex -- file # 每一行是谁、何时写的 git blame -L start,end file # 查看某个提交的完整 diff git show hash # 两个时间点之间影响该文件的提交 git log old..new -p -- file对于每个实质性提交拉取 PR 上下文# 从 merge commit 或分支找到 PR 号 git log -1 --format%B hash # 完整 PR 上下文正文、评审评论、关联 issue gh pr view number --json title,body,author,createdAt,mergedAt,labels,closingIssuesReferences,comments,reviews,files # --json 的 reviews 和 comments 字段才是真正的信号所在查找带外文档# ADR 通常放在 docs/adr/ 等目录 rg -l -i architecture.decision --glob *.md # 目标附近的 TODO / FIXME rg -n -C2 (TODO|FIXME|HACK|XXX|NOTE) target_file # 相关测试测试名常常编码了 why rg -l symbol --glob *test*2.3 好证据长什么样解释了所解决问题的 PR 描述修复了导致 X 的分页 bug而非仅仅描述变更就备选方案展开辩论的长评审线程目标行附近解释非显然约束的行内注释名为test_handles_edge_case_when_X、揭示动机边界的测试引用工单或事故 ID 的提交消息总结用户可见动机的 CHANGELOG 条目2.4 常见陷阱Squash-merge 平原仓库若压缩合并 PR分支历史的独立提交会丢失需退回 PR 正文与评论误导性提交消息Small refactor 有时掩盖了有意的行为变更要看 diff 而非消息从众复制的模式作者可能复制了某个模式却不懂其缘由需追溯该模式在代码库中的起源提交Bot 提交与自动合并Dependabot、Renovate、自动 backport 通常不携带动机寻找意图时应跳过把代码当作意图的证据代码本身不是其存在理由的证据证据来自提交消息、PR、注释、测试、文档不要以函数叫 X来引用意图2.5 返回什么每个与问题相关的 commit/PR/评论都要给出精确引用文本、hash/PR 号/file:line、作者与日期、以及它是直接证据还是间接证据。三、工单 / 追踪器linear.md——产品与业务强制力的所在linear.md 认为Linear 承载的是产品/业务上下文我们做这个是因为客户 X 要求或这是 Q3 合规计划的一部分。3.1 来源内容描述功能、bug 及其动机的 issue挂在 issue 下的项目文档常为 PRD 或规格父/子 issue 关系宏观计划 → 具体 ticketissue 评论澄清、范围变更、我们为什么这么做的动机标签如compliance、customer-request、perf它们暗示动机的类型解释范围变更的状态更新附件与关联的 GitHub PR3.2 搜索方法Linear MCP从关联工单开始种子 commit/PR 引用了工单 ID如ENG-1234、[BUG-567]先用get_issue获取读完整 issue 含评论按关键词列出相关 issue用list_issues按功能名、关键符号或业务术语做文本搜索尝试多种措辞走 issue 树落到子 issue 时取父 issue——子 issue 是战术性的父 issue 常携带为什么读项目文档issue 属于某项目时用get_project查看附件文档项目级文档是规格与动机最常被捕获的地方查标签与里程碑标签暗示动机类别customer-request、incident-followup、compliance里程碑把工作与截止日期绑定常能揭示动机3.3 好证据与陷阱好证据包括陈述业务问题的 issue 描述客户 Acme 因 SOC2 审计需要 X、记录决策的评论我们选 B 方案因为 A 方案要动 billing 服务、类似计划的父 issue 标题、附带的 PRD/规格、customer:acme/incident-followup/compliance/perf-regression标签。陷阱需警惕范围漂移ticket 可能被关闭又换范围重开要读完整历史、机械模板强制填写的 Why 部分可能是套话improve user experience 类泛化文本不是真答案、过期 ticket旧 ticket 反映已改变的旧计划核对日期并与代码上线时间交叉验证、重复关闭链沿 duplicate-of 关系追溯回权威 ticket、私有空间内容无法访问时记为 gap 而非猜测。3.4 返回什么每个相关工单返回工单 ID 与标题、从描述或评论逐字引用的问题/动机不可转述合成器需要精确文本用于引用、标签/父 issue/项目、作者与创建/关闭日期、工单链接若有。四、长文档notion.md——代码落地之前为什么的栖息地notion.md 指出Notion 是长形式why常常在成为代码之前存在的地方一个重要功能通常先有一份文档。4.1 来源内容PRD产品需求文档技术规格与 RFC架构决策记录ADR设计评审的会议纪要携带领域上下文的团队页面事故复盘postmortem可能解释防御性代码的 runbook设定优先级的战略文档4.2 搜索方法Notion MCP用notion-search做关键词搜索功能名、目标代码中的关键符号/类名、作者用户名设计文档常在代码落地前完成、错误字符串或用户可见术语、以及知道上线时间时的限时查询用notion-fetch抓取候选页面读全文而非预览动机常埋在文档中段追踪反向链接与子页面设计文档常有备选方案、附录或实现说明的子页查相关数据库notion-query-data-sources与notion-query-meeting-notes可挖出讨论该决策的会议纪要搜索作者专属空间若 PR 作者有个人笔记本其中可能有先于代码的探索性思考4.3 好证据与陷阱好证据带 Problem statement 或 Motivation 段落且与目标代码目的吻合的 PRDAlternatives considered / Rejected approaches 段落把目标代码指认为某次具体事故修复的 postmortem记录我们因为 Y 决定 X且作者/日期与 PR 匹配的会议纪要非平凡填写的 ADR 模板status、context、decision、consequences。陷阱过时文档规格在实现前写成且未更新要与实际 PR 交叉核对、文档与现实漂移规格说做 X代码实际做 Y要标记分歧、模板套话无具体性的 Why 段落、未链接文档最相关的文档可能不被任何地方链接宽泛关键词搜索有用、多份草稿找到最终版或最近更新的那份核对日期、访问受限页面记为 gap。五、实时团队聊天slack.md——从未进入文档的实时商议slack.md 强调Slack 常常是真正决策发生的地方尤其是那些小到不值得写文档的变更它也是最易逝的来源——线程被删、频道被归档、搜索质量随时间退化。5.1 来源内容问题与决策的实时讨论事故频道里做过的救火决策权衡取舍被辩论的设计讨论线程资深工程师回答过、但没进文档的问题解释为什么被重访的合并后讨论DM通常不可搜索据此界定范围5.2 搜索方法先检查可用 Slack MCP 的工具 schema可能需要mcp_auth认证失败就停下并报告 gap作者限定搜索围绕 PR 合并日期搜索 PR 作者的消息大幅缩小范围且常能命中关键信息功能名与关键符号关键词搜索包含拼写错误与口语化表述PR URL 搜索Slack 常在评审/讨论时贴 PR搜索 PR URL 或/pull/number错误字符串搜索代码处理特定错误时搜索该错误字符串事故线程常浮出频道限定搜索#eng-*工程讨论、#proj-*项目频道、#incident-*/#sev-*事故频道、团队专属频道、设计评审频道线程遍历找到相关消息后抓取整个线程——决策常在回复里5.3 好证据与陷阱好证据显式辩论权衡的线程我本来要用 A但 B 更好因为……、描述该代码所预防 bug 的事故频道消息、评审者的提问与作者/负责人的权威回答、对某次会议的引用、PM 或客户对接工程师解释客户诉求的消息。陷阱频道考古限制因保留策略很老的消息可能消失记下保留悬崖、未搜索的 DM许多决策在不可搜索的 DM 中这是已知局限、玩笑被当成决策Lol just do the thing 不是决策即使它先于 commit 出现要找经过思考的讨论、单条消息的语境坍缩没有线程时单条消息常被误读务必抓线程、认证失败MCP 未认证就停止不要编造发现。六、基础设施可观测性datadog.md——生产现实的记录datadog.md 的核心观点Datadog 持有运行期记录——生产环境实际发生了什么而非计划或讨论过什么。它回答这段代码写成时周围的生产现实是什么这往往解释了代码的形态。6.1 来源内容指标Metrics团队埋点的计数器、gauge、histogram。指标存在本身就是证据——有人觉得这个数字值得盯着监控与告警Monitors alerts团队决定值得把人叫醒的条件。一个在rate_limit_hit 10/min触发的 monitor 直接证明团队担心那个阈值看板Dashboards策展视图图表告诉你团队认为某个子系统什么重要APM 链路与 span请求级运行数据适用于为什么这么慢/为什么这里有超时日志Logs高容量事件记录常含促成防御性代码的错误条件事故Incidents带时间线与关联 postmortem 的正式事故记录笔记本Notebooks探索性调查常含假设与分析6.2 搜索方法Datadog MCP先宽后窄识别归属服务search_datadog_services (按名称或团队过滤) search_datadog_service_dependencies (查看上游/下游)先看看板与监控——它们告诉你团队关心什么search_datadog_dashboards (查询功能名、服务名、符号) search_datadog_monitors (同样的查询)当看板或监控覆盖目标时记下其查询与被盯的阈值。阈值常常就是为什么这里被钳制在 N的答案。目标周围的指标search_datadog_metrics (按名称模式如功能或符号) get_datadog_metric_context (元数据描述、单位、标签) get_datadog_metric (时序数据PR 日期附近有尖峰吗)将指标轨迹与目标新增/变更日期相关联是强佐证payment_timeout指标在 2023-11-03 尖峰重试逻辑在 2023-11-06 合并。日志收敛不要倾倒search_datadog_logs (目标附近的原始日志模式设 use_log_patternstrue) analyze_datadog_logs (SQL 风格聚合只在需要计数时)用符号、错误字符串或功能名搜索强烈优先限时查询如变更前后 30 天。日志体量巨大无约束搜索浪费时间且可能超时。APM span 与 traceaggregate_spans (统计这个端点失败频率多高) search_datadog_spans (检查单个 span) get_datadog_trace (某个特定 trace ID)适用于超时、重试、慢路径与跨服务行为。事故search_datadog_incidents (按标题、团队、日期范围) get_datadog_incident (某个具体事故的完整详情)若目标看起来是防御性的搜索它被加入前后的事故。时间线包含为 X 添加了防御检查的事故是近乎直接的证据。6.3 好证据与陷阱好证据查询与阈值匹配代码所强制约束的 monitor代码钳制 100monitor 在请求超 100/min 时告警目标作者创建的、widget 与代码测量/防御内容对应的看板代码合并前立即出现生产尖峰、之后稳定的指标引用目标代码、相同符号或相同错误字符串的事故记录在变更前时间窗内显示防御性代码将预防的特定错误模式的日志。陷阱相关不等于因果PR 前尖峰 后稳定只是提示性的同窗口可能还有其他变更查相邻 PR、过度拟合找到的图Datadog 可视化由人制作反映制作人的框架名为 retry success rate 的图证明团队关心重试成功而非某行代码存在的原因、消失的遥测指标可能被重命名、删除或保留期短找不到相关窗口数据是 gap 而非空结果、大规模噪音用服务、标签、时间激进地收敛用analyze_datadog_logs聚合而非倾倒原始日志、有埋点 ≠ 由它导致指标存在只说明有人觉得值得度量不说明代码因它而加要与 commit/PR 日期交叉引用。七、错误 / 异常追踪sentry.md——哪里出了错的档案sentry.md 认为 Sentry 是出过问题的事的档案。对于防御性、纠错性或错误处理代码它常常握着直接动机促使某人添加检查、catch、重试或兜底的特定异常、栈轨迹与频率。7.1 来源内容Issues按指纹分组的错误含计数、first/last seen 时间戳、受影响 release、评论Eventsissue 内的单个错误实例栈轨迹、标签、用户上下文Releases部署记录及关联 issue回答哪个版本修复了这个Replays用户可见错误的会话录制若启用Profiles性能剖析数据对 why 用处小对 how slow 用处大Issue 评论与分配有时含工程师对根因的笔记Sentry 提供的最有价值的东西是时间相关性issue X 创建于 2024-01-02峰值 500 events/day在 2024-01-15 发布 v2.14.0发出防御检查的版本后消失。7.2 搜索方法Sentry MCP定向不知道项目 slug 与组织时先用find_organizations、find_projects搜索相关 issuesearch_issues自然语言如 errors in PaymentService timeout。好的查询成分目标处理的异常类名、目标函数/类名、目标检查的错误消息字符串、目标文件路径按 release 与时间窗收窄search_issue_events按 release、时间、环境、trace ID、标签过滤、get_issue_tag_values查看 issue 在版本/用户/环境间的分布。对疑似 issue 检查first seen错误何时开始出现、last seen何时停止是否与目标上线日期对齐、affected releases哪些版本受影响、哪个是修复、频率轨迹是否尖峰后被解决拉取完整 event 获取上下文get_sentry_resource传 Sentry URL 或 typeID。栈轨迹是否穿过目标代码标签与 breadcrumbs 是否匹配目标防御的条件检查目标附近的 releasesfind_releases围绕目标 commit 日期将 release 版本与 PR 合并日期交叉引用谨慎使用 Seeranalyze_issue_with_seer产生 AI 根因分析可作假设生成器但要当作推断而非权威——实际 event 与栈轨迹才是主要证据7.3 好证据与陷阱好证据first seen略早于目标 PR、last seen略晚于目标的 issue暗示目标处理了该错误穿过或落在目标函数上的栈轨迹展示正被防御的精确失败模式PR 作者描述修复的 issue 评论引用 Sentry issue URL 或 ID 的目标 PR 描述/提交消息在含目标的 release 之后停止的高事件数 issue。陷阱分组漂移Sentry 按指纹分组重构/重命名会让同一个错误出现在新 issue ID 下issue 骤停可能只是被重新分组检查紧随其后的新 issue、release 相关性有噪音一个 release 含大量 commitissue 停在 v2.14.0 不证明目标修复了它要交叉引用目标的确切 commit、无声修复错误可能因上游变更而停止相关性提示修复但不证明作者身份、resolved ≠ 已修复issue 可被手动标记 resolved 而无任何代码变更、Seer 幻觉Seer 可能生成听上去自信但错误的解释做论断时回到实际 event、栈轨迹与时间戳、采样激进采样下低 event 数可能只是高采样率而非罕见错误不确定就记为 gap。八、产品分析数仓databricks.md——产品与数据现实databricks.md 指出Databricks 是产品分析、数据管道与数仓遥测层与 Datadog 互补——Datadog 是基础设施/运行时视角Databricks 是产品/数据视角用户做了什么、跑了哪些实验、功能使用如何演变、阈值常量从哪来。8.1 来源内容产品分析事件your_warehouse.events.analytics_track_event原始与按事件类型化、去重的 dbt 模型your_analytics_db.schema.table。用户行为功能调用、点击、接受/拒绝、提交、客户端上报错误使用与计费事件your_warehouse.events.usage_event/stg_usage_events、raw_model_event/stg_raw_model_events。用于成本或体量驱动的决策实验 / 特性开关数据曝光与结果表。Schema 因公司而异先SHOW TABLES探测再假设表名系统表system.query.history、system.compute.warehouses、system.billing.*、system.access.audit。回答这个查询贵吗多久有人跑一次仓库负载何时尖峰dbt 血缘your_analytics_db.schema中的模型揭示哪些管道依赖某表/字段上游变更常促成下游消费代码的变更Databricks notebooks工程师在改代码前的探索分析。SQL MCP 无法查询若怀疑动机在 notebook 中记为 gap8.2 搜索方法Databricks SQL MCP主工具execute_sql_read_only若返回statement_id用poll_sql_result轮询而非重跑。查询前先定向——schema 因公司而异先探测再信任表名SHOW TABLES IN your_analytics_db.schema LIKE *keyword*; DESCRIBE TABLE your_analytics_db.schema.stg_event;每条查询都限时。这些表巨大无约束扫描会超时。以_timestamp事件或start_timesystem.query.history过滤窗口包围上线日期通常约前后 30 天。优先类型化 dbt 模型而非原始表your_analytics_db.schema.table去重、类型化、liquid-clusteredyour_warehouse.events.analytics_track_event有重复与无类型的properties_json。模型名模式stg_source_event_name_with_underscores其中source为app、backend、website或cli。模式无法确定确切模型名时用SHOW TABLES确认。仅当尚无 dbt 模型、或需要 dbt 刷新滞后窗口内的事件时才退回原始表。类型化 dbt 模型的列约定掌握可省一次DESCRIBE往返_timestamp、_id、_auth_id、_request_id、event_name每个模型都有properties_name为类型化、下划线命名的事件属性properties_entrypoint、properties_size_bytes……context_team_id、context_client_version、context_country、context_client_os为预提取的客户端上下文。值得投入的调查模式按目标选择表 列组合事件使用轨迹在 PR 合并前后 ±30d 窗口内统计相关stg_*模型的日计数。从零到稳态体量的阶跃函数是该 PR 发布了该功能的强间接证据衰减到零暗示弃用或删除护栏 / 防御检查的起源PR 前 14 天内相关properties_name列的分布median / p99 / max。与目标阈值常量匹配的 p99 暗示该数字取自数据实验 / 特性开关查找SHOW TABLES ... LIKE *experiment*找曝光表再按相关 flag key 在 PR 日期附近拉取各变体的曝光计数迁移、回填或性能重写的查询历史证据system.query.history用statement_text ILIKE %table_or_symbol%加紧凑start_time窗口过滤按total_duration_ms排序或聚合SUM(read_bytes)、COUNT(*)可浮现促成变更的昂贵查询dbt 血缘若目标读/写your_analytics_db.schema模型该模型自身的 git 历史常携带动机——把线索交回 git 调查者而非自己追8.3 好证据与陷阱好证据错误分类事件在防御性代码 PR 后数天内计数跌近零暗示该 PR 解决了该错误类曝光表行以 shipped/concluded 决策命名目标特性开关键且与 PR 上线日期吻合。陷阱有埋点 ≠ 由它导致事件存在只说明有人值得记录它宣称因果前须与 git 调查者的 PR/commit 引用配对、无声的埋点变更事件体量阶跃可能是新事件开始记录而非用户行为变化解读为功能上线信号前检查同期埋点 PR、schema 漂移今天类型化模型上的列在目标编写时可能不存在旧数据可能只在原始properties_json里、dbt 刷新滞后your_analytics_db.schema.*按计划重建通常小时/日级近几小时事件退回your_warehouse.events.*并按_id去重、公司专属表实验、特性开关、计费、使用表各不相同从没确认存在就报告结果是典型失败模式先用SHOW TABLES/DESCRIBE TABLE探测、保留悬崖相关窗口早于表保留期或 dbt 模型创建日期时是 gap 而非空结果要显式说明避免合成器把无结果读成无活动、notebook 不可查询SQL MCP 看不到 Databricks notebooks怀疑动机在其中就返回 gap。九、横切视角incident-postmortem.md——防御性代码的事故溯源incident-postmortem.md 不是独立来源而是横切角度。事故常常促成防御性代码X 中断后我们加了这条检查所以当目标代码呈现防御性特征时null 检查、重试逻辑、超时处理、限流、特性开关、出口护栏、OOM 处理要在每个可用来源中专项搜寻事故历史Notion搜索提到目标文件、功能或错误字符串的 postmortemLinear找带incident、sev-*、postmortem-action-item、reliability标签的 ticketSlack围绕目标代码被添加的日期搜索#sev-*与#incident-*频道Gitfix for incident、add defensive check、revert 后跟 re-apply with... 之类的提交消息是强信号Datadogsearch_datadog_incidents找带时间线的正式事故记录以及作为 postmortem action items 创建的看板与监控Sentryfirst-seen/last-seen 窗口与目标 PR 上线日期对齐的 issue、穿过目标的栈轨迹Databricks对错误条件分类的产品分析事件客户端上报失败、用户可见重试事件等常在事故窗口尖峰目标 PR 上线后该事件计数下降是对目标代码解决了用户可见症状的间接支持即使 Datadog/Sentry 信号嘈杂找到事故链接就抓完整 postmortem——postmortem 通常有直接对应代码变更的 Action Items 段落。当多个来源相互印证一个 Datadog 事故 ID 出现在 Linear ticket 中、该 ticket 出现在 Notion postmortem 中、该 postmortem 出现在指向目标 PR 的 Slack 线程中、且 Databricks 错误事件计数在修复后下降证据尤其强。这段调查值得在代码的防御性特征让事故驱动起源显得可信时投入对不显防御性的代码可跳过。十、与 Why 技能主流程的配合从 Playbook 到并行调查source-playbook 的运用场景在 SKILL.md 中有完整定义其流程是理解目标与问题解析用户问的目标通常是代码块、模式、功能或具名设计决策与问题设计动机、权衡、触发边界用例、外部约束、死代码或宽历史扫描目标模糊时基于对话上下文打开的文件、近期编辑、光标位置做最佳猜测并简要陈述建立代码锚点用git blame -L、git log --follow -p、git log --oneline -20、git log -1 --format%B收集文件路径/行范围、关键符号、初始 commit 列表、PR 号与关联工单 ID作为传给调查者的种子上下文并行派调查者先发现环境中的 MCP可用工具映射或检查 Cursor 暴露的mcps/目录把每个 MCP 映射到七类证据类别之一目标是完整的覆盖图而非最小图在单条消息中同时启动所有匹配的调查者。每个调查者获得基础 Promptinvestigator-prompt.md、按所选 MCP 适配的类别 playbook、目标代码防御性时的横切 playbook、代码锚点、用户的原始问题。配置上使用generalPurpose子代理类型、配置的 why-investigators 模型默认grok-4.6-fast-xhigh、readonly: false——不能用 readonly/Ask 模式那会剥离 MCP 访问跳过调查者的唯一合法理由该类别的 MCP 不可用记为 gap 而非选择或来源被证明无关高标准如目标是构建期脚本无运行时代码路径且跳过理由必须写进最终输出的 Sources Consulted 部分合成派一个合成者子代理拿到所有调查者发现含空结果与带理由的跳过、代码锚点、原始问题、epistemics.md 置信度框架与 synthesizer-prompt.md 模板呈现可直接轻编辑以提升清晰度但不得改写置信度语言调查者的取证纪律来自 investigator-prompt.md引用而非转述措辞关键处必须逐字引用引用要让读者数秒内跳到来源确认先宽后深先撒大网不错过相关上下文再收窄记录搜过什么不只记录找到什么absence 只有在读者知道搜过什么时才有用逐字记录查询抵抗叙事三份证据整齐排好、第四份矛盾时矛盾才是最有趣的发现不要归档了事考虑反事实报告强发现前自问——若当前解读是错的是否仍会预期找到该证据、证据会如何不同绝不编造想把部分发现四舍五入成自信陈述时停下并标记为 partial不混淆机制与动机把limit 50改成limit 100的 commit 只展示变更不展示动机动机要在提交消息、PR 描述、关联工单或评审评论中找不从代码风格推断意图作者选了函数式写法是对代码的观察不是意图证据只有作者陈述过才算意图保留不确定性证据模棱两可就说模棱两可一个解读更合理但不确凿就说清楚不做静默替换问题问功能 X 却只找到功能 Y 的证据时不要把 Y 的证据当作 X 的答案十一、置信度框架如何严谨地报告为什么epistemics.md 是整套取证体系的置信度骨架其核心前提是代码不携带自己的动机。你能读到代码做了什么但读不到它为何存在——那活在 commit、PR、工单、文档与对话里而这些材料都不完整、有偏、有时根本缺失。假装不是这样就会产出听上去自信却误导用户的猜测。最终输出的每一条论断必须落入五个置信层级之一层级决定论断进入哪个输出小节以及如何措辞层级含义措辞输出位置Direct直接作者实际写下为什么的显式文本引用如此修复解决了拥有 1000 项用户无法分页的 bug的 PR 描述、客户 Acme 在安全评审中要求的工单、clamp to 100 because the upstream API rejects larger values的代码注释自信、现在时This exists because X. 附引用What We FoundSupported有支撑多条间接证据收敛无单一来源明说但跨来源模式使其很可能如 PR 标题 improve performance 工单标签 perf 相邻 commit 都动同一热点路径自信但明确为推导证据强烈指向 X[具体片段] 引用多个来源What We FoundInferred推断对上下文的合理解读但无显式支撑如PR 没说为什么但考虑到生产报错时间按事故频道时间线与修复匆忙当天合并可能是 hotfix回避式appears tolikelysuggestsis consistent with显式给出推断链Given A and B, C seems likely because DWhat We Can Reasonably InferSpeculative推测合理假设但证据薄弱、其他解释同样成立如可能是对已修复浏览器 bug 的 workaround但未找到同期证据显式推测One possibility is X, but we have no direct evidenceCompeting HypothesesUnknown未知找过但没找到具体说明搜过什么we searched X, Y, and Z and found no evidence of whyWhat We Dont Know措辞纪律becausethe reason iswas designed tofixesthe team decided 等词暗示 Direct/Supported 置信度推断时不可使用appears tolikelysuggestsplausibly 等词用于推断。避免 obviouslyclearlyof coursejust 以及 I think/I believe用 the evidence suggests。同时要避免合理化今天讲得通的代码可能是为已失效的理由写的、甚至当时就是错的——不要从作者做了正确的事倒推辩护不要把无证据变成无证据的证据没人提安全问题所以当时没人在意。反奉承陷阱用户常带着内嵌假设问 why我们为什么这么做我猜是为了性能。不要直接确认——把它当作候选之一独立检验证据证据支持就用引用确认不支持就说明并呈现证据真正支持的结论。用户的猜测是调查的起点不是要被验证的结论。证据矛盾时两个来源冲突PR 说一套、工单说另一套就把两者都摆出来不要挑更顺耳的。证据缺失时诚实的我们不知道是这个技能最有价值的输出之一——它让用户知道答案不在显而易见的地方、需要去问真人原作者、产品负责人、团队负责人或可以决定不再深究。把一个 gap 填上自信的猜测会积极伤害用户因为他们会照着猜测行动。十二、输出格式与约束从发现到可引用的结论按 SKILL.md 引用的合成器模板why调查的输出结构为The Question问题、The Code in Question被质疑的代码、What We Found找到什么、What We Can Reasonably Infer合理推断、Competing Hypotheses竞争假设、What We Dont Know未知、Sources Consulted引用的来源、Confidence Summary置信度总结。要保持置信度分离完整且Sources Consulted 中每个调查者一行——包括返回空结果的与跳过的并注明原因。若用户的 why 问题是变更代码的前奏则在 Sources Consulted 块之后把谱系发现转换为适合规划变更的Preserve / Change / Avoid / Risk 约束集。需要避开的常见失败模式见 SKILL.md包括近因偏差——假设最近的 commit 是权威的当前形态往往是许多早期决策的累积要追溯回去。结语why技能之所以能回答这段代码为什么长这样靠的不是读代码而是围绕七类证据源并行取证、并用五级置信度框架严谨报告。source-playbook.md 作为索引把每类证据源的取证策略收敛为一份自包含、可适配的手册git/gh是始终可用的最可信来源工单承载产品强制力长文档保存落地前的设计理由聊天记录留存从未成文的商议可观测性暴露生产现实错误追踪存档出过的事分析数仓回答数字从哪来而事故复盘把防御性代码与历史事故串成因果链。当你在自己的环境中面对不同的 MCPJira、Confluence、Discord、New Relic、Rollbar、BigQuery……只需按同类别 Playbook 的结构适配即可复用整套方法论——这也是这套手册设计的最终意图。参考路径速查索引手册pstack/skills/why/references/source-playbook.md技能主文档pstack/skills/why/SKILL.md七类来源 Playbookcode-archaeology.mdgit/gh、linear.md工单、notion.md长文档、slack.md聊天、datadog.md可观测性、sentry.md错误追踪、databricks.md分析数仓横切 Playbookincident-postmortem.md配套模板与框架investigator-prompt.md、synthesizer-prompt.md、epistemics.md【免费下载链接】pluginsCursor plugin specification and official plugins项目地址: https://gitcode.com/GitHub_Trending/plugins125/plugins创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考