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 是一個輕量級、誠實且可靠的調試記錄工具，特別適合需要透明、可驗證開發流程的團隊和個人。