gds-investigate

调查

概述

根据现有证据重建事件经过，或了解不熟悉的领域的作用。生成一份结构化案例 文件，让其他工程师无需背景信息也能接手。持续在缺陷追查（由症状驱动）和 领域探索（没有症状）之间调整；两种情况下都适用相同的严谨方法。

参数： 工单 ID、日志文件路径、诊断归档、错误消息、代码领域名称、问题描述，或现有案例文件的路径。最后一种情况会恢复之前的调查；其他情况会开启新案例。

输出： {implementation_artifacts}/{workflow.case_file_subdir}/{workflow.case_file_filename}。记录参考输入；只有在结果需要时，才会将原始内容读入父上下文。

如果提供了工单 ID，{slug} 就是该 ID；否则，它是与用户商定的简短描述性名称，并转换为仅含小写字母、数字和连字符的形式。如果解析后的路径中已存在案例文件，请询问是将其重命名为 slug-YYYY-MM-DD.md，还是恢复现有文件（恢复会转到结果 0）。

每个结果完成后，说明已了解的内容，并暂停等待用户再继续。

原则

• 证据分级。
  • 已确认。 直接观察到；引用 path:line、日志时间戳或提交哈希。
  • 已推断。 可从已确认的证据通过逻辑推导得出；展示推导链。
  • 假设。 合理但尚未确认；说明如何证实或证伪。
• 先立足于确凿证据。 以一条已确认的证据为锚点，再向外扩展。切勿先提出理论再寻找支持。当证据稀少时，切换到证据精简模式（结果 1 分支）。
• 质疑前提。 用户的描述是假设，而非事实。应独立核实；如果证据与之矛盾，应明确指出。
• 依据证据，而非叙述。 当证据与当前理论矛盾时，应更新理论，而不是反过来。即使用户深信不疑，也要避免确认偏误。
• 不得删除假设。 更新状态（开放／已确认／已证伪）并添加结论。走错的路也是交付内容的一部分。
• 缺失证据本身就是发现。 记录缺口、它能解决什么问题，以及如何获取。
• 尽早记录。 一旦商定 {slug}，就立即初始化案例文件；它是中断期间的持久状态。
• path:line 引用 使用相对于当前工作目录的格式，不带开头的 /，以便在 IDE 嵌入式终端中点击打开。
• 委派纪律。 如果某一步需要读取 5 个以上文件，或任一文件超过 10K 个 token，应委派给子 Agent，并要求其仅返回结构化 JSON。引用其结果中的 path:line；父级上下文不要重新读取。
• 并行执行相互独立的操作（多项 grep、多项读取、并行清单）——一条消息中发起多个工具调用。
• 沟通。 使用以证据为先的表述（“证据表明”“尚未确认，需通过 X 验证”）。不要含糊其辞，不要讲述故事。

激活时

步骤 1：解析工作流配置块

运行：uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow

如果脚本失败，请停止并报告错误。

步骤 2：执行前置步骤

按顺序运行 {workflow.activation_steps_prepend} 中的每一项。

步骤 3：加载持久事实

将 {workflow.persistent_facts} 中的每一项视为基础上下文。以 file: 开头的条目是 {project-root} 下的路径或 glob 模式（加载其内容）；其他条目则是原样使用的事实。

步骤 4：加载配置

加载 {project-root}/_bmad/gds/config.yaml，并解析 {user_name}、{communication_language}、 {document_output_language}、{implementation_artifacts}、{project_knowledge}。如果无法解析 {implementation_artifacts}，则回退到 ./investigations/，并在初始化前说明回退情况。

步骤 5：问候

使用 {communication_language} 问候 {user_name}。

步骤 6：执行追加步骤

按顺序运行 {workflow.activation_steps_append} 中的每个条目。

激活已完成。如果 activation_steps_prepend 或 activation_steps_append 非空，请在继续之前确认每个条目都已按顺序执行。在所有激活步骤完成之前，不要开始主工作流。

步骤 7：确认并路由

将输入作为引用进行确认（记录路径和 ID；不要读取原始内容）。指向现有案例文件的路径 → 结果 0。否则 → 结果 1。

流程

结果 0：现有案例已加载并呈现

读取案例文件。按顺序呈现：未解决的假设（Status = Open）及其确认/反驳标准；未解决的 待办事项（Status ≠ Done）；缺失证据行；最近的 Conclusion 及其置信度。询问要跟进哪条线索。新 证据会开启一个新的 ## Follow-up: {YYYY-MM-DD} 块（同一天再次进入时追加 #2、#3）。以 上摘要暂停并等待用户；等待指示。

结果 1：范围与据点已确立

确认每种输入形态——仅记录位置、范围、时间窗口；批量读取在结果 2 中进行。

• 问题跟踪器工单。 通过可用的 MCP 工具获取完整详情。
• 诊断归档。 记录路径、文件数量、时间窗口。
• 日志文件或堆栈跟踪。 记录路径和时间窗口；此处仅将用户消息中已存在的堆栈帧纳入 范围。
• 自由文本描述。 逐字记录；视为假设。
• 代码区域名称（无症状）。记录入口点。
• 近期提交区域。 记录提交范围。

如果用户带着假设到来，将其登记为假设 #1。独立寻找据点；用户的假设是据点要验证或反驳的 对象之一。

寻找据点：一条已确认的证据（错误消息、函数名、HTTP 路由、配置参数、测试 用例）。以此为锚点。

在分支之前初始化 {case_file}。 路径为 {implementation_artifacts}/{workflow.case_file_subdir}/{workflow.case_file_filename}，其中 {slug} 已替换（slug 和冲突规则见概述）。从 {workflow.case_file_template} 创建文件，并填写 Hand-off Brief （粗略）、Case Info、Problem Statement、初始 Evidence Inventory。

证据稀薄分支。 当无法获取任何已确认证据时：在 Hand-off Brief 中将该案例标记为证据稀薄；用按优先级排序的数据收集项填充 Investigation Backlog；记录"为取得进展，我需要以下之一：……"；暂停并等待用户提供证据或授权结果 2 进行更广泛的扫描。

否则呈现范围、据点、文件路径、拟议方法。以上摘要暂停并等待用户；等待指示。

结果 2：证据边界已映射

勘察现场：跨以下独立类别并行盘点可用证据：诊断归档； 问题跟踪器；版本控制；测试结果；静态分析；源代码。对于任何超过约 10K token 的类别， 委托给子代理，返回 JSON 清单（路径、大小、时间窗口、引用为 path:line 的关键片段）。

将每一项分类为 Available、Partial 或 Missing——Missing 本身就是一项发现。更新 Evidence Inventory 和 Investigation Backlog。以上摘要暂停并等待用户；等待指示。

结果 3：有条理地推理原因

• 追踪因果关系。 症状驱动：从症状反向追踪到导致症状的条件和由此产生的状态。探索：从输出（返回值、副作用、发送的消息）反向追踪到导致输出的条件。方法相同，起点不同。
• 重建时间线，交叉参照日志、系统事件、版本控制记录和用户观察。
• 提出并检验假设。 陈述假设，识别支持或反驳它的证据，进行搜索并评定状态（已确认 / 已驳回 / 未决）。更新状态。切勿删除。
• 进行反驳检查。 每当某个假设向“已确认”推进时，先主动寻找反驳证据。在 Resolution 中记录尝试。
• 核实用户的前提。 如果证据与之矛盾，请明确说明。
• 将发现的路径添加到待办列表。 专注于当前事项。

更新 Confirmed Findings、Deduced Conclusions、Hypothesized Paths、Backlog、Timeline。突出显示与原始前提相矛盾之处。使用上述摘要向用户说明后暂停；等待指示。

结果 4：已追踪相关源码

先将以下初步扫描作为并行工具调用，在同一条消息中发出：使用 grep 搜索精确错误字符串；使用 glob 扫描受影响目录，查找并行实现；使用 git log 查看近期更改。

然后依次执行：阅读相关代码；沿调用链追踪；留意跨越语言和进程边界的情况（已编译代码→脚本、IPC、主机→设备、配置流）。

按案例类型调整侧重点：

• 探索： I/O 映射（触发条件、输出、依赖项）；高频词扫描；控制流筛选（分支、循环、错误处理、状态机转换）。
• 症状驱动： 深度评估——根因是否可从局部上下文追溯到，还是需要更广泛的领域模型？指出需要升级处理的情况；切勿默默扩大范围。评估问题是否容易修复——差一位、缺少空值检查、参数顺序颠倒 → 在报告中给出一行代码建议或差异草案；非简单问题 → 在根因所在区域停止。

调查止于诊断；实现不在范围内。更新 Source Code Trace（Error origin、Trigger、Condition、Related files；范围更广时补充 area model）。使用上述摘要向用户说明后暂停；等待指示。

结果 5：报告已定稿，交接清晰

更新 {case_file}：

• 将 Hand-off Brief 重写为最终版本（3 句话，15 秒可读完）。
• 给出带置信度的 Final Conclusion：高（根因已确认，可确定性复现）、中（已推断；存在少量不确定性）、低（基于假设；存在明确的数据缺口）。
• 适用时提供 Fix direction（多种机制共同作用时，按机制分类）。
• 仍有不确定性时提供 Diagnostic steps。
• 适用时提供 Reproduction Plan；探索类案例则提供验证计划。
• Status： Active / Concluded / Blocked on evidence。

先呈现结论，再给出具体的后续步骤菜单：简单修复 → gds-quick-dev；调整范围 / 计划 → gds-correct-course；跟踪的故事 → gds-create-story；重新审查 → gds-code-review。推荐最有价值的操作。只有收到明确请求后，才生成缓解措施和变通方案——调查止于诊断。若 {workflow.on_complete} 非空，则执行它。使用上述摘要向用户说明后暂停；等待指示。

后续迭代

继续工作时，在 {case_file} 下以新的 ## Follow-up: {YYYY-MM-DD} 区块追加内容（同日重新进入时使用 #2、#3）。满足以下任一条件时，调查即告完成：

• 根因已确认。
• 根因基于假设，且存在明确的数据缺口。
• 心智模型已足以满足用户声明的目标（探索类案例）。
• 待办列表中只剩需要无法获取的证据才能处理的事项。
• 用户明确结束调查。