Show HN：DebugBrief —— 将调试过程转化为报告，无需AI

DebugBrief 是一个创新的命令行工具，旨在帮助开发者将调试过程系统化地记录并转化为清晰、可复现的报告。它完全本地运行，不依赖任何人工智能服务，也不收集遥测数据，确保开发者的工作流隐私得到保护。

核心功能

DebugBrief 通过 debugbrief run 命令捕获用户执行的命令及其输出。它记录每个命令的退出码、输出预览、执行耗时以及执行前的 git 快照。所有记录仅基于实际发生的事件——用户尝试了什么、失败了什么、通过了哪些测试、哪些文件发生了变更。工具不会推测根因或报告用户未获得的结果。

工具支持在报告中生成三种模式：PR 模式（默认）、交接模式和事故模式。报告结构包括摘要、红绿转换窗口（从失败到通过的时间线）、验证命令、时间线以及观察到的错误。空部分会自动省略。

安装与快速开始

DebugBrief 需要 Python 3.9 或更高版本。可以通过 pipx 或 uv 工具安装：

pipx install debugbrief
# 或
uv tool install debugbrief

使用十分简单。启动会话并记录命令：

debugbrief start "修复 add() 返回错误结果"
debugbrief note "add() 执行减法而非加法；测试预期为 5。"
debugbrief run -- python -m pytest -q test_calc.py # 执行测试
# 进行修复
debugbrief redo # 重新运行上次的命令
debugbrief end # 生成 PR 报告

redo 命令会重新运行上次捕获的命令，而 end 默认生成 PR 报告。用户还可将命令输出通过管道提交到 GitHub PR：debugbrief end --stdout | gh pr comment --body-file -。

兼容性与限制

DebugBrief 支持 Linux 和 macOS（CI 测试覆盖 Python 3.9 至 3.14），其他 Unix-like 系统可能可用但未测试。不支持原生 Windows 和 PowerShell。工具能够自动识别常见的测试运行器（如 pytest、jest、go test、cargo test 等），但其他命令也可通过 --verify 标记为检查点。

工具的捕获模式是显式的——仅记录通过 debugbrief run 执行的命令。全屏 TUI 应用（如 vim、htop）不会有效捕获。隐私方面，工具在写入磁盘前会尽力进行秘密信息脱敏，但无法保证完全覆盖所有情况。

依赖与许可

DebugBrief 使用 Python 标准库和原生 git。在 Python 3.11+ 上无需额外依赖，Python 3.9/3.10 需要 tomli 包以读取可选的 .debugbrief.toml 配置文件。工具本身不发起网络请求，不调用 AI，不收集遥测。项目采用 MIT 许可证。

总体而言，DebugBrief 是一个轻量级、诚实且可靠的调试记录工具，特别适合需要透明、可验证开发流程的团队和个人。