butler-git：把「我改完了」變成可驗證的事實

在 DSH 插件開發與智能體工作流中，區分「意圖」與「完成」是核心難點。butler-git 插件通過 Git 原生機制，將「我要改什麼（節點）」與「我改完了什麼（Commit）」解耦，並通過門禁強制要求兩者的一致性。

插件定位¶

核心價值：節點是意圖，commit 是證據。只有當預期改動（\(\Delta\)）與檢測程序（\(P\)）全部通過，纔會產生 commit。

基本信息：
* 名稱：hercules-debug/butler-git
* 維護者：Hercules-debug
* 類別：工作流
* 許可：MIT

核心功能¶

1. 節點與證據的分離¶

插件維護一個「意圖樹」。節點先被聲明，作爲意圖存在；只有當達成條件滿足時，纔會生成 commit 作爲證據。兩者不是相等關係，而是達成關係。

2. 零依賴門禁¶

門禁機制不依賴外部環境，只使用 node 和 git。
* Delta (\(\Delta\))：預期變化，精確集合，包含方向（M/A/D/R）。
* Program (\(P\))：檢測程序，執行一條命令，退出碼 0 算通過。
* 提交規則：commit 命令會將工作區固定爲樹，比對 \(\Delta\)，執行 \(P\)。全部通過才寫入歷史。

3. 權限與凍結¶

憑證系統：憑證用於向創建者提權（向下包含所有後代）。憑證明文只在創建時出現一次，之後庫中只有其 hash。
凍結機制：已達成（有 commit）的節點不可變，任何憑證都無法修改，歷史不可重寫。

4. 可視化與審計¶

DAG 圖：生成 Mermaid 佈局的 DAG 圖，展示意圖父子關係和 Git 父子關係。
證據鏈：commit trailer 記錄證據（如 bg-verified-tree），防止僞造。即使圖丟失，也能通過 bg recheck 掃描歷史發現僞造。

使用方式¶

插件提供了 CLI 命令來管理這些意圖和門禁。

定義與提交¶

在一個 git 倉庫中，使用 node bin/bg.mjs 作爲入口：

# 1. 定義意圖（節點）
# --expect: 描述
# --base: 基準提交
# --verify: 驗證命令
# --delta: 預期改動（M:修改, A:新增, D:刪除）
node bin/bg.mjs plan \
  --id n7 \
  --expect "讓導出支持非 ASCII" \
  --base <commit-hash> \
  --verify "pytest -q" \
  --delta "M:src/csv.py" \
  --delta "A:src/enc.py"

# 2. 查看狀態（不跑 P，只對比改動）
node bin/bg.mjs status n7

# 3. 提交（觸發門禁：Delta + P）
node bin/bg.mjs commit n7

人工面與診斷¶

# 查看意圖樹（包含燈、狀態、弱 P 標記）
node bin/bg.mjs tree

# 生成 HTML 可視化（需要聯網，從 CDN 獲取 Mermaid）
node bin/bg.mjs html

# 啓動實時查看器
node bin/bg.mjs serve

# 對當前 commit 複查歷史節點（診斷工具）
node bin/bg.mjs recheck

適用場景與注意¶

適用場景：需要嚴格驗證智能體工作產出的場景。適合對「預期外的改動」極其敏感的項目。
注意：
- bg html 命令依賴網絡加載 Mermaid 庫。斷網時頁面會報錯，但圖中的信息會以純文字列出，不影響門禁邏輯。
- 插件本身運行依賴 DeepSeek Harness 環境（peerDependencies 指向 @deepseek-ai/cordis 和 @deepseek-ai/dsh-tools）。
- 任何提交如果帶有 bg-node trailer，會被視爲走門禁；沒有該 trailer 的提交會被視爲繞過，並在 tree 視圖中標記。

結語¶

butler-git 通過 Git 的不可變性和 trailer 機制，將代碼變更的驗證固化爲事實。它不承諾「整體可用」，而是將驗證粒度下沉到每一個意圖節點，讓「我改完了」真正變成可回放、可審計的證據。