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 机制，将代码变更的验证固化为事实。它不承诺「整体可用」，而是将验证粒度下沉到每一个意图节点，让「我改完了」真正变成可回放、可审计的证据。