Zed 崩溃修复工作流：从复现测试到最小化根因修复的完整方法论

本文以 Zed 仓库内置的崩溃修复提示词（crash fix prompt）为主体，讲解其六步修复工作流：如何确认失败测试、定位被破坏的不变量、实施最小化根因修复、验证回归、通过 Clippy 检查，并按团队模板撰写 PR 描述。读完后，你将掌握一套可直接复用于 Rust 大型代码库的崩溃修复方法，并理解 Zed 崩溃上报基础设施（crash handler、Sentry 抓取脚本）如何为这套流程提供输入。

一、流程定位：investigate → fix → link-issues

Zed 将线上崩溃（crash）的处理拆分为三个由 Agent 提示词驱动的独立阶段，全部位于 .factory/prompts/crash/ 目录下：

阶段	文档	职责
调查	investigate.md	抓取 Sentry 崩溃报告，分析堆栈，产出 ANALYSIS.md 和复现测试
修复	fix.md	在已有分析和复现测试的基础上，实施最小化、正确的修复（本文主体）
关联	link-issues.md	搜索可能相关的 GitHub issues，按置信度分级，供人工复核

fix.md 开篇即明确了自身的前置条件与目标：“You are fixing a crash that has been analyzed and has a reproduction test case. Your goal is to implement a minimal, correct fix that resolves the root cause and makes the reproduction test pass.” —— 修复阶段的输入不是原始崩溃，而是调查阶段的产物。

二、输入前置检查：两项产物缺一不可

fix 阶段开始前必须确认两个输入存在：

1. ANALYSIS.md — 调查阶段（investigate）产出的崩溃分析文档，必须通读；
2. 失败的复现测试 — 能触发同一崩溃的测试用例，修复的第一步就是先运行它确认其按预期失败。

两者任一缺失时，fix.md 的指令是停止并让用户补齐，或先运行调查阶段（/prompt crash/investigate）。这一设计保证了修复永远建立在“已确认的失败”之上，而不是凭空猜测。

ANALYSIS.md 的格式在 investigate.md 中定义为四个固定小节：Crash Summary（Sentry Issue、错误信息、崩溃位置）、Root Cause（含数据流说明）、Reproduction（含精确的测试命令）、Suggested Fix（具体到函数与检查点，多方案时列出权衡）。fix 阶段 Step 2 会直接消费其中的 "Suggested Fix" 小节。

崩溃报告本身的来源由调查阶段决定，仓库内提供了配套脚本 script/sentry-fetch：给定 Sentry issue 短 ID（如 ZED-4VS）或数字 ID，它从环境变量 SENTRY_AUTH_TOKEN 或 ~/.sentryclirc 读取凭据，调用 Sentry API 拉取最新事件，并格式化为含 Tags、Exceptions、Threads 的 Markdown 崩溃报告，其中每个堆栈帧都标注了 (In app) / (Not in app) 标记并高亮可疑行（<-- SUSPECT LINE）——这正是 fix.md 要求“确认 panic 信息与堆栈和 ANALYSIS.md 一致”时对照的原始材料。

三、Step 1：确认失败测试

cargo test -p <crate> <test_name>

运行复现测试后，fix.md 要求阅读失败输出，确认 panic 消息和堆栈与 ANALYSIS.md 描述一致。关键纪律在这里：如果测试不失败、或失败方式与预期不同，必须停下来重新评估（stop and reassess）再继续。这条规则防止在错误的基础上做修复——例如调查阶段的根因判断有误，或复现测试实际触发的是另一条代码路径。

这一检查与调查阶段的产出标准是闭环的：investigate.md 要求复现测试“在同一个函数、以同一种错误类型失败（same panic message pattern）”，且失败堆栈应与原始崩溃报告共享关键应用帧；最外层框架（crash handler、signal handler）在测试环境下会不同，属预期差异。

四、Step 2：理解修复——先回答两个问题

在写任何代码之前，fix.md 要求读完 ANALYSIS.md 的 "Suggested Fix" 与相关源码，并对以下两点形成清晰认识：

1. 被违反的是什么不变量（invariant） — 崩溃代码假设了数据的什么性质？
2. 不变量在哪里被打破 — 是哪个函数产出了坏状态？

这个提问框架把“修一个 panic”重新表述为“修复一个数据流上的状态错误”，直接为 Step 3 的核心准则“修根因、修表象”提供依据。例如：slice 索引不在 char 边界、越界访问、对 None 调用 unwrap——这些都是 investigate.md Step 2 列举的“immediate cause”类型，而修复阶段要回答的是坏数据从哪里来。

五、Step 3：实施最小化修复——五条准则

fix.md 给出的实施准则是这套方法论的核心，逐条展开：

1. Fix the root cause, not the symptom（修根因，不修表象）。 文档给出了反例：如果真正的问题是偏移量计算错误，就不要再加一个 bounds check 去 catch 那个 panic——直接修正计算。
2. Preserve existing behavior（保持既有行为）。 修复只应改变原本会崩溃场景下的行为；所有非崩溃路径的行为必须保持不变。
3. Don't add unnecessary changes（不做顺手改动）。 禁止 drive-by improvements，diff 必须聚焦，这是代码评审可处理性的前提。
4. Add a comment only if the fix is non-obvious（只在非显而易见时加注释）。 判断标准是：读者是否会问“为什么这里要有这个检查？”——若是，则用简短注释解释崩溃场景。
5. Consider long term maintainability（兼顾长期可维护性）。 在聚焦修复的同时，要考虑该修复对代码库长期可靠性与可维护性的影响。

Zed 代码库本身就体现了“注释解释崩溃场景”的风格，例如 crates/crashes/src/crashes.rs 中的 strip_user_string_from_panic：

/// Rust's string-slicing panics embed the user's string content in the message,
/// e.g. "byte index 4 is out of bounds of `a`". Strip that suffix so we
/// don't upload arbitrary user text in crash reports.
fn strip_user_string_from_panic(message: &str) -> String {
    const STRING_PANIC_PREFIXES: &[&str] = &[
        // Older rustc (pre-1.95):
        "byte index ",
        "begin <= end (",
        // Newer rustc (1.95+):
        "start byte index ",
        "end byte index ",
        "begin > end (",
    ];
    // ...
}

该函数处理的是 Rust 字符串切片 panic 消息中内嵌用户字符串的隐私问题——注意它还按 rustc 版本区分了旧格式（byte index / begin <= end (）与新格式（start byte index / end byte index ）前缀，这是“考虑长期可维护性”的实例：对上游行为变化保持兼容而非硬编码单一格式。

六、Step 4：验证修复——复现测试 + 全量 crate 测试

验证分两级：

cargo test -p <crate> <test_name>   # 1. 复现测试必须通过
cargo test -p <crate>              # 2. 受影响 crate 的完整测试套件

第一级确认修复本身生效；第二级是回归防线——运行受影响 crate 的完整测试套件。若任何测试失败，fix.md 要求先判断是否是修复引入的回归，回归必须在继续之前修掉。这一步与“preserve existing behavior”准则呼应：行为保持不是口头承诺，而是由 crate 级测试套件来验证的。

七、Step 5：运行 Clippy

./script/clippy

并处理（address）由本次改动引入的新警告。仓库中的 script/clippy 实现揭示了这条命令的实际强度：

"${CARGO:-cargo}" clippy "$@" --release --all-targets --all-features -- --deny warnings

即 --release --all-targets --all-features 下 --deny warnings——任何警告都会导致构建失败，因此“处理新警告”不是可选项。另外两个细节值得注意：

• 脚本在未指定 -p/--package 时会自动追加 --workspace，意味着直接运行 ./script/clippy 是对整个 workspace 的检查；
• 在本地环境（非 CI）中，若安装了 cargo-shear、typos、buf，还会依次跑依赖检查（cargo shear --locked --deny-warnings）、拼写检查（typos --config typos.toml，对应根目录的 typos.toml）以及 proto 文件的 buf lint / buf format 检查。

这也解释了为何 fix.md 只要求处理新引入的警告：全 workspace 的检查是重操作，聚焦增量才能保持修复 diff 的克制。

八、Step 6：总结与 PR 描述模板

修复完成后需为 PR 描述写一段简要总结，必须覆盖四点：

• What was the bug — 一句话说明根因；
• What the fix does — 一句话说明改动；
• How it was verified — 注明复现测试现在通过；
• Sentry issue link — 若 ANALYSIS.md 中可用则附上。

fix.md 内嵌了 Zed 团队的 PR 描述模板：

<Description of change, what the issue was and the fix.>

Release Notes:

- N/A *or* Added/Fixed/Improved ...

Release Notes 一栏要求显式回答“对外部用户可感知吗”——不可感知时写 N/A，否则以 Added/Fixed/Improved 开头。这与第三阶段 link-issues.md 形成收尾：该阶段会把潜在相关的 GitHub issues 按 High/Medium/Low 置信度分级输出到 LINKED_ISSUES.md，但明确标注“advisory only”，由人类确认后才允许添加 Fixes #... 关闭关键字——修复流程的自动化止于“给出证据”，发布声明保留给人。

九、方法论文档之外的底座：Zed 崩溃基础设施

理解 fix 流程的输入产出，离不开 Zed 的崩溃上报架构，其核心在 crates/crashes/src/crashes.rs：

• 独立的 crash-handler sidecar 进程：spawn_crash_handler 以 --crash-handler <socket> 参数拉起同一个二进制的独立进程（crashes.rs#L644-L651），主进程通过 Unix socket（Windows 下为命名管道）与其通信，信号处理器通过 CrashHandler::attach 挂载；
• panic 到 minidump 的链路：panic hook（panic_hook）先把剥离用户字符串后的 panic 消息与 file:line span 发给 sidecar，再调用 std::process::abort() 主动触发信号路径，让 crash handler 生成 minidump（crashes.rs#L572-L599）；
• 崩溃数据文件：sidecar 在 on_minidump_created 回调中把 minidump 压缩为 zstd，并与 CrashInfo（含 init/panic/minidump_error/abort_message/gpus/tags）一起写入 <session_id>.json，供下一版本启动时上传 Sentry；
• Linux 特有细节：通过 process_vm_readv 跨进程读取 glibc 私有符号 __abort_msg，恢复 free(): invalid pointer 这类 abort 前诊断（crashes.rs#L339-L359），并有针对页面尺寸校验、NUL 截断的单元测试（如 crashes.rs#L818-L855）——这些“先写测试再动代码”的实践，正是 fix.md 工作流在该 crate 上的真实体现。

十、可复用要点总结

fix.md 虽然只有一页，但把崩溃修复中的常见失控点全部设卡：

1. 不确认失败就不动手——防止在错误假设上修复；
2. 先问不变量，再写代码——把症状修复转化为数据流修复；
3. diff 聚焦——根因修复、行为保持、零顺手改动，三者共同保证评审可验证；
4. 两级测试验证——复现测试 + crate 全量测试，回归先修再继续；
5. --deny warnings 门槛——增量警告必须清零；
6. 结构化 PR 输出——根因、改动、验证方式、Sentry 链接四要素齐备，Release Notes 显式声明。

这套“investigate → fix → link-issues”三阶段提示词与仓库内 script/sentry-fetch、script/clippy、crates/crashes 基础设施相互配合，构成了 Zed 处理线上崩溃的完整闭环：Agent 负责把崩溃转化为带复现测试的最小修复，人负责最终的相关性确认与发布声明。