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