DebugBrief 记录您在调试时所做的所有操作，并将其转化为基于证据的Markdown报告，适用于拉取请求、交接或事件记录。DebugBrief 捕获您写的笔记和运行的命令，然后根据实际发生的情况构建报告：您尝试了什么、失败了什么、通过了什么，以及在此期间哪些文件发生了变化。它不使用人工智能，也不推断根本原因或报告您没有获得的测试结果。安装：pipx install debugbrief 或 uv tool install debugbrief 普通的 pip install debugbrief 也可以。DebugBrief 需要 Python 3.9 或更新版本。在可用时使用原生 Git 来捕获仓库元数据和更改的文件。您调试的项目不需要是 Python 项目；只有 DebugBrief 在 Python 上运行。快速入门 debugbrief start "修复 add() 返回错误结果" debugbrief note "add() 进行了减法而不是加法；测试期望值为 5." debugbrief run -- python -m pytest -q test_calc.py # 失败 # 进行修复 debugbrief redo # 同样的测试，现在通过 debugbrief end # 写入 PR 报告 -- 之后的所有内容将按照您输入的内容完全运行，同时其输出实时流向您的终端。DebugBrief 标志（--timeout，--shell，--no-redact，--verify）应放在 -- 之前。redo 会重新运行最后一个捕获的命令，end 默认进入 PR 报告模式。提示：一个单行别名可以在日常使用中消除捕获前缀。alias db="debugbrief run --" db pytest -q 您得到的报告仅基于记录的证据。以下是一次实际运行的简短摘录：## 汇总 失败的检查 `python -m pytest -q test_calc.py` 在 2 次尝试后于 2 秒内通过，变更涉及 calc.py。## 变更 A 检查在 12:02:09 失败，`python -m pytest -q test_calc.py` 在 12:02:10 通过（窗口 1 秒）。在失败与通过检查之间，这些文件发生了变化（相关性，而非因果关系）：- `calc.py` 完整示例：PR，交接，事件。工作原理：run 在伪终端下执行一个命令，因此其输出实时流动，然后记录实际的退出代码、有限的输出预览、持续时间以及每个命令的 git 快照。通过或失败仅来自退出代码。仅当被识别的测试、构建、Lint 或类型检查运行程序实际返回 0 时，命令才被视为验证通过。它兼容任何语言。被识别的运行程序（pytest、jest、vitest、go test、cargo test、dotnet test、make check 以及更多）会被自动分类。任何其他命令仍然会被捕获，您可以用 --verify 标记它为检查。end 从这些事件中生成报告：红到绿窗口、再现和验证命令、时间线、观察到的错误和失败的尝试。空部分被省略。在写入磁盘之前，机密信息会被屏蔽。屏蔽是最佳努力；通过 --no-redact 可以针对单个命令选择退出。完整命令参考和完整的识别运行者列表：docs/COMMANDS.md。安全模型和屏蔽细节：SECURITY.md。直接将报告发布到拉取请求（可选 GitHub CLI）：debugbrief end --stdout | gh pr comment --body-file - 命令：您最常使用的五个命令：命令 作用 start "<title>" 开始一个会话 note <text> 记录观察 run -- <command> 运行并捕获命令 redo 重新运行最后一个捕获的命令 end [--mode pr|handoff|incident] 最终化并写入报告（默认 pr）其余命令：命令 作用 init 设置项目并显示工作流状态 show 显示活动会话预览 [--mode ...] 打印报告而不结束会话 cancel [--yes] 放弃活动会话，不报告 doctor [--fix] 健康检查项目和状态 recover 修复崩溃后的会话指针 last 显示最近的报告路径 open 打开最近的报告 list 列出记录的会话 show <id> 显示已记录的会话 每个命令的完整标志和行为请参见 docs/COMMANDS.md。依赖：DebugBrief 使用 Python 标准库和原生 git。在 Python 3.11 及以上版本中不需要其他任何依赖。在 Python 3.9 和 3.10 中，它使用小型的 tomli 包来读取可选的 .debugbrief.toml。DebugBrief 本身不进行网络请求、不使用人工智能，也不收集遥测数据。支持的平台：Linux 和 macOS 在 CI 中进行了 Python 3.9 至 3.14 的测试。其他类似 Unix 的系统可能有效，但当前尚未测试。原生 Windows 和 PowerShell 不受支持。限制：通过 debugbrief run 进行明确捕获。输出实时流动，同时为报告存储有限的预览，因此没有完整的记录。全屏 TUI（如 vim 会话、htop）不会被有效捕获。请直接运行这些，并用 note 记录结果。屏蔽是保守和最佳努力；并非所有秘密都会被捕获。Git 部分需要原生 git；在仓库之外将被省略。开发：pip install -e ".[dev]" pytest 详见 CONTRIBUTING.md 获取完整设置和贡献指南。许可证：MIT。见 LICENSE.