@mcgrapeng/ccg 3.1.0 → 4.1.0

package/ccg.md

@@ -1,50 +1,67 @@
 ---
-description: Code-divergence detector. Run Codex+Gemini in parallel on a diff, then surface where they DISAGREE (high-signal) vs where they agree. Auto-picks risk-aware mode. Logs each review to ledger. See README.md.
+description: Code Change Guardian — multi-model review, AI commit gate, merge conflict resolution, and pre-push analysis.
 ---
 
-# CCG v3 — 代码分歧检测器
+# CCG v4 — Code Change Guardian
 
-**身份**：不是 review 工具，是**分歧检测器**。两个独立模型家族（Codex/Gemini）评审同一份 diff，Claude 综合时把"两边都说没事 / 两边都说有问题"压成低优先级，把"两边判断不一致的点"放到聚光灯下——这才是真正值得人类介入的地方。
-
-**默认行为**：无参数 → 抓 git diff → 风险打分 → 自动选 mode → 并行评审 → 输出 AGREEMENT / DIVERGENCE / BLINDSPOT 三段 → 落 ledger。
+> **4-Stage Guardian**: Two independent AI model families guard every change across Review · Commit · Merge · Push—surfacing where they disagree, auto-filtering low-risk changes, and providing a pre-push quality gate before code leaves your machine.
 
 ## 三柱设计
 
 | 柱 | 解决的问题 | 实现 |
 |---|---|---|
-| Divergence Engine | 单源 review 看不到"自己看不到的盲区" | 同 prompt 双投喂 + Claude 综合时强调分歧 |
+| Divergence Engine | 单源 review 看不到"自己看不到的盲区" | 同 prompt 投喂两个**不同厂商**模型，综合时强调分歧 |
 | Risk-Aware Routing | 用户不应该手选 cost/balanced/quality | `ccg_risk_score` 基于路径/内容/规模规则打分自动选 |
 | Review Ledger | 这次评审的判断下次没法复用 | 每次评审追加 JSONL，按路径可查历史 |
 
+> **模型策略**：各阶段主力是 BAILIAN 平台**两个不同厂商**的顶级模型（厂商限定
+> `qwen / glm / mimo / deepseek / kimi / minimax`）。`codex / gemini / claude`
+> **仅在质量优先（`CCG_MODE=quality`）时启用**——此时 Stage 1 在三者中任选 2 个，
+> 剩下一个作为 synthesizer。风险评分会自动路由：低/中风险走便宜的 Bailian 对，
+> 高风险自动进入 quality 解锁 premium 三件套。
+
 ## 配置 (环境变量)
 
 | 变量 | 默认 | 说明 |
 |---|---|---|
 | `CCG_MODE` | `auto` | `auto` (按 risk score 决) / `cost` / `balanced` / `quality` |
-| `CCG_CODEX_MODEL` | — | 显式 codex 模型（优先于 CCG_MODE） |
-| `CCG_GEMINI_MODEL` | — | 显式 gemini 模型 |
+| `CCG_PROVIDERS` | (按 mode) | Stage 1 provider 列表，最多 2 个。非 quality 默认两个不同厂商 Bailian；quality 默认 `codex gemini`。支持 `bailian:qwen-3.6 bailian:deepseek-v4` 语法 |
+| `CCG_ALLOW_SAME_VENDOR` | `0` | `1` = 允许 Stage 1 两个 slot 同厂商（默认禁止，破坏 divergence） |
+| `BAILIAN_API_KEY` | — | Bailian 主力模型必需 |
+| `CCG_BAILIAN_MODEL` | — | 显式 bailian 模型（优先于 CCG_MODE） |
+| `CCG_CODEX_MODEL` | — | 显式 codex 模型（仅 quality 生效） |
+| `CCG_GEMINI_MODEL` | — | 显式 gemini 模型（仅 quality 生效） |
+| `CCG_SYNTH_PROVIDER` | (按 mode) | 覆盖 synthesizer：quality 默认用三件套中未上场的那个（缺省 claude），非 quality 用 bailian |
+| `CCG_RISK_LLM` | `0` | `1` = 用 LLM 做风险评分（需 BAILIAN_API_KEY）；默认纯规则、确定性、不花钱 |
 | `CCG_CODEX_TIMEOUT` | `240` | Codex 超时秒数 |
 | `CCG_GEMINI_TIMEOUT` | `120` | Gemini 超时秒数 |
 | `CCG_NO_CACHE` | `0` | `1` = 跳过 24h prompt-hash 缓存 |
 | `CCG_CACHE_TTL_HOURS` | `24` | 缓存 TTL |
-| `CCG_MAX_PROMPT_KB` | `100` | 防止把整个 repo 塞进 prompt |
+| `CCG_MAX_PROMPT_KB` | `100` | 防止把整个 repo 塞进 prompt（超过此值各 provider 直接拒绝） |
 | `CCG_KEEP_ARTIFACTS` | `0` | `1` = 保留临时文件 |
 | `CCG_LEDGER_LOG` | `$XDG_DATA_HOME/ccg/ledger.jsonl` | 评审历史落盘位置（fallback `~/.local/share/ccg/`，自动迁移老路径 `~/.ccg/`） |
+| `CCG_NO_REPORT` | `0` | `1` = 跳过 `.ccg/reports/<sha>_<ts>.md` 持久化 |
+| `CCG_REPORT_DIR` | `<repo>/.ccg/reports` | 改写报告目录（默认 git repo 根下的 `.ccg/reports/`） |
+| `CCG_NO_HISTORY` | `0` | `1` = 跳过把过去同路径的评审摘要注入 prompt |
+| `CCG_HISTORY_MAX` | `3` | 注入 prompt 的历史评审条数上限 |
 
 ### Mode → 默认模型映射
 
-| Mode | Codex | Gemini |
+| Mode | Stage 1（主力，两个不同厂商） | Synthesizer |
 |---|---|---|
-| `cost` | gpt-5-nano | gemini-2.5-flash-lite |
-| `balanced` (默认) | gpt-5-mini | gemini-2.5-flash |
-| `quality` | gpt-5 | gemini-2.5-pro |
+| `cost` | `qwen-3.5-haiku` + `deepseek-v4-lite`（Bailian） | bailian |
+| `balanced` (默认) | `qwen-3.6` + `deepseek-v4`（Bailian） | bailian |
+| `quality` | `codex` + `gemini`（三件套任选 2） | 剩下那个（缺省 `claude`） |
 
-> ⚠️ 第三方代理若不支持上述模型名，会 5xx/404。用 `CCG_CODEX_MODEL`/`CCG_GEMINI_MODEL` 显式指定代理实际支持的型号。
+> ⚠️ codex/gemini/claude 仅在 `quality` 模式启用。非 quality 模式即使在
+> `CCG_PROVIDERS` 里写了它们，也会被跳过。
+> ⚠️ 第三方代理若不支持上述模型名，会 5xx/404。用 `CCG_*_MODEL` 显式指定代理实际支持的型号。
 
 ## 前置依赖
 
-- `npm i -g @openai/codex` `npm i -g @google/gemini-cli`
-- `export GEMINI_API_KEY=...` 放在 `~/.zshenv`（非交互 shell 也能读到）
+- **Bailian（主力，非 quality 模式必需）**：`export BAILIAN_API_KEY=...`
+- **premium（仅 quality 模式）**：`npm i -g @openai/codex`、`npm i -g @google/gemini-cli` + `export GEMINI_API_KEY=...`
+- API key 放在 `~/.zshenv`（非交互 shell 也能读到）
 
 ## 执行协议（Claude 严格按以下步骤）
 
@@ -63,9 +80,10 @@ ccg_init
 source ~/.claude/commands/ccg.sh
 ccg_preflight
 ```
-- `CCG_PREFLIGHT_CODEX=missing` → 说明缺哪个 CLI + 安装命令
-- `CCG_PREFLIGHT_GEMINI=no-api-key` → 标注 Gemini 不可用，跳过
-- 两者都不可用 → Claude 独立回答
+- `CCG_PREFLIGHT_BAILIAN=ok` → 主力可用（非 quality 模式用两个不同厂商 Bailian 模型）
+- `CCG_PREFLIGHT_BAILIAN=no-api-key` → 非 quality 模式不可用；提示设 `BAILIAN_API_KEY`
+- `CCG_PREFLIGHT_CODEX` / `CCG_PREFLIGHT_GEMINI` → 仅 **quality 模式**用得到（premium 三件套）
+- 主力与 premium 都不可用 → Claude 独立回答
 
 ### 步骤 2. 确定任务输入（两种模式）
 
@@ -88,6 +106,22 @@ ccg_diff_capture "$CCG_DIR/diff.txt"
 
 **Claude 必须在最终输出中显示对比的是哪个 source，让用户知道评审的范围。**
 
+### 步骤 2.5. 历史评审注入（让 ledger 不再 write-only）
+
+```bash
+CCG_DIR=<字面路径>
+source ~/.claude/commands/ccg.sh
+ccg_ledger_context "$CCG_DIR/diff.txt"
+```
+
+读 `CCG_HISTORY_*`：
+- `CCG_HISTORY_OK=<n>_matches_<max>_max` + `CCG_HISTORY_FILE=<path>` → 文件已写入 `<CCG_DIR>/history.txt`，**步骤 4 写 prompt 时必须把这段内容拼到 diff 前面**
+- `CCG_HISTORY_NONE=0_matches` → ledger 里没匹配（首次评审这些文件）；正常情况，prompt 不带 history 块
+- `CCG_HISTORY_SKIPPED=<no-ledger|no-diff|disabled|no-paths-in-diff>` → 跳过即可，不报错
+- `CCG_HISTORY_FAIL=...` → 临时文件写不进；忽略并继续（这一步是增强信号，不是必需）
+
+> 设计立场：L6 ledger 不再是日记本——每次评审都把"过去对同一文件的判断"作为先验喂给两个评审模型。recurring patterns、未解决的 fix-required 都进入第一现场。环境变量 `CCG_NO_HISTORY=1` 可关闭；`CCG_HISTORY_MAX` 改条数（默认 3）。
+
 ### 步骤 3. 风险打分 + 自动选 mode（仅 B 模式）
 
 ```bash
@@ -102,7 +136,20 @@ ccg_risk_score "$CCG_DIR/diff.txt" | tee "$CCG_DIR/risk.txt"
 
 > 设计立场：路径/内容/规模规则比 LLM 判断更**可解释、零成本、可改**。社区贡献者可以直接 PR 改权重。
 
-### 步骤 4. 写 prompt（结构化输出协议）
+### 步骤 4. 选择两个评审模型 + 写 prompt（结构化输出协议）
+
+**先按 `CCG_MODE` 选定两个 Stage 1 评审模型（必须是不同厂商）：**
+
+- **非 quality（cost / balanced）→ 两个不同厂商的 Bailian 主力模型**：
+
+  ```bash
+  CCG_DIR=<字面路径>
+  source ~/.claude/commands/ccg.sh
+  _ccg_resolve_bailian_pair "${CCG_MODE:-balanced}"   # 输出两行，如：qwen-3.6 / deepseek-v4
+  ```
+  第 1 行 = Reviewer A 的模型，第 2 行 = Reviewer B 的模型（厂商天然不同）。
+
+- **quality → premium 三件套（codex / gemini / claude）任选 2 个**作为 Reviewer A/B，剩下那个留给步骤 7 的 synthesis（缺省 claude）。默认 A=codex、B=gemini。
 
 **核心改动**：要求两端都按下面格式输出（便于 Claude 后续做对齐和分歧检测）。
 
@@ -128,59 +175,81 @@ detail: <2-4 行解释，必须可独立读懂>
 
 不要寒暄，不要在外面加任何文字。如果没有发现问题，FINDINGS 段落留空，但格式仍要保留。
 
+<如果 step 2.5 产出了 history.txt，把它的完整内容贴在这里，标题"=== PRIOR REVIEWS ===" 自带>
+
 待评审的 diff（source: <CCG_DIFF_SOURCE>）：
 
 <贴入 diff 内容>
 ````
 
-用 **Write tool**（不是 echo）写入：
-- `<CCG_DIR>/codex.prompt`
-- `<CCG_DIR>/gemini.prompt`
+用 **Write tool**（不是 echo）写入两份**完全相同**的 prompt（含 history 段——两个 reviewer 看相同的过往）：
+- `<CCG_DIR>/slot1.prompt`
+- `<CCG_DIR>/slot2.prompt`
 
-两份 prompt 内容**完全相同**。让两个独立大脑产生差异——这正是分歧检测的来源。
-
-### 步骤 5. 并行调用 CLI（单消息两个 Bash 调用）
+### 步骤 5. 并行调用两个评审模型（单消息两个 Bash 调用）
 
 helper 内部：检查大小 → 查缓存（命中则 $0）→ 真打 API → 落 cache + usage.log。
+**两个 Bash 调用必须在同一条 assistant message 内发出**，才能真并行。
+
+**非 quality（Bailian × 2，不同厂商）：**
 
-**Codex** (timeout 260000)：
 ```bash
 CCG_DIR=<字面路径>
 source ~/.claude/commands/ccg.sh
-ccg_codex "$CCG_DIR/codex.prompt" "$CCG_DIR/codex.result"
-echo "---ANSWER---"
-cat "$CCG_DIR/codex.result"
+CCG_BAILIAN_MODEL=<Reviewer A 模型> ccg_bailian "$CCG_DIR/slot1.prompt" "$CCG_DIR/slot1.result"
+echo "---ANSWER---"; cat "$CCG_DIR/slot1.result"
 ```
+```bash
+CCG_DIR=<字面路径>
+source ~/.claude/commands/ccg.sh
+CCG_BAILIAN_MODEL=<Reviewer B 模型> ccg_bailian "$CCG_DIR/slot2.prompt" "$CCG_DIR/slot2.result"
+echo "---ANSWER---"; cat "$CCG_DIR/slot2.result"
+```
+
+**quality（premium，默认 codex + gemini；timeout 由 helper 内部控制）：**
 
-**Gemini** (timeout 140000)：
 ```bash
 CCG_DIR=<字面路径>
 source ~/.claude/commands/ccg.sh
-ccg_gemini "$CCG_DIR/gemini.prompt" "$CCG_DIR/gemini.result"
-echo "---ANSWER---"
-cat "$CCG_DIR/gemini.result"
+ccg_codex "$CCG_DIR/slot1.prompt" "$CCG_DIR/slot1.result"
+echo "---ANSWER---"; cat "$CCG_DIR/slot1.result"
+```
+```bash
+CCG_DIR=<字面路径>
+source ~/.claude/commands/ccg.sh
+ccg_gemini "$CCG_DIR/slot2.prompt" "$CCG_DIR/slot2.result"
+echo "---ANSWER---"; cat "$CCG_DIR/slot2.result"
 ```
 
-**两个 Bash 调用必须在同一条 assistant message 内发出**，才能真并行。
+> 让两个不同厂商的独立大脑产生差异——这正是分歧检测的来源。
 
 ### 步骤 6. 实际成本
 
+按各 slot 实际用的 provider 调用（`<provA>`/`<provB>` ∈ codex|gemini|bailian|claude）。
+**bailian 时把同一个 `CCG_BAILIAN_MODEL` 一起传**，成本才准确：
+
 ```bash
 CCG_DIR=<字面路径>
 source ~/.claude/commands/ccg.sh
-ccg_actual "$CCG_DIR/codex.prompt" "$CCG_DIR/codex.result" codex
-ccg_actual "$CCG_DIR/gemini.prompt" "$CCG_DIR/gemini.result" gemini
+# 非 quality 示例（两个不同厂商 Bailian）：
+CCG_BAILIAN_MODEL=<Reviewer A 模型> ccg_actual "$CCG_DIR/slot1.prompt" "$CCG_DIR/slot1.result" bailian
+CCG_BAILIAN_MODEL=<Reviewer B 模型> ccg_actual "$CCG_DIR/slot2.prompt" "$CCG_DIR/slot2.result" bailian
+# quality 示例：
+# ccg_actual "$CCG_DIR/slot1.prompt" "$CCG_DIR/slot1.result" codex
+# ccg_actual "$CCG_DIR/slot2.prompt" "$CCG_DIR/slot2.result" gemini
 ```
 
 ### 步骤 7. 健康判定 + 综合输出（**Pillar 1 关键**）
 
-| Codex | Gemini | 路径 |
+| Reviewer A | Reviewer B | 路径 |
 |---|---|---|
 | OK | OK | 完整三段输出（AGREEMENT / DIVERGENCE / BLINDSPOT）|
-| OK | FAIL | 只能输出 Codex 视角，标注分歧无法验证 |
-| FAIL | OK | 只能输出 Gemini 视角，标注分歧无法验证 |
+| OK | FAIL | 只能输出 A 视角，标注分歧无法验证 |
+| FAIL | OK | 只能输出 B 视角，标注分歧无法验证 |
 | FAIL | FAIL | Claude 独立回答 + 标注顾问不可用 |
 
+> **谁来综合（synthesizer）**：非 quality → 一个 Bailian 模型（最好是与 A/B 不同的第三个厂商，如 glm/kimi）；quality → codex/gemini/claude 三件套里没上场的那个（缺省 claude）。Claude 本体在 Claude Code 内即可直接做这步综合。
+
 **Claude 的综合规则（必须严格遵守）：**
 
 1. **解析两边的 [FINDING] 块**，按 `(file, line, category, title 关键字)` 做对齐。Levenshtein 不重要，类别 + 文件 + 大致位置一致即视为同一发现。
@@ -200,12 +269,12 @@ ccg_actual "$CCG_DIR/gemini.prompt" "$CCG_DIR/gemini.result" gemini
 ### 步骤 8. 综合输出模板（**严格按此格式**）
 
 ```
-## CCG v3 综合结果
+## CCG 综合结果
 
 📍 评审范围：<source 标签，如 worktree | staged | upstream:origin/main>
 🎯 模式：<mode>（risk score: <分数> ｜ 触发: <reasons>）
-🩺 顾问状态：Codex ✓ ｜ Gemini ✓
-💰 本次成本：Codex $0.0023 + Gemini $0.0008 = **$0.0031**
+🩺 评审模型：A=<provider:model> ✓ ｜ B=<provider:model> ✓   （非 quality 为两个不同厂商 Bailian）
+💰 本次成本：A $0.0009 + B $0.0011 = **$0.0020**
 
 ═══ AGREEMENT (N) ═══
 两边都指出，新增信息量低：
@@ -215,10 +284,10 @@ ccg_actual "$CCG_DIR/gemini.prompt" "$CCG_DIR/gemini.result" gemini
 ═══ DIVERGENCE (M) ═══   ★ 这一段是 ccg 的核心价值 ★
 
 ▸ DIV#1 — file:line
-  🔵 Codex: <Codex 的判断>
-  🟢 Gemini: <Gemini 的判断 / 没提到>
+  🔵 Reviewer A (<model>): <A 的判断>
+  🟢 Reviewer B (<model>): <B 的判断 / 没提到>
   ⚖️  Claude 综合: <哪边更可信，为什么>
-  ➡️ 建议: <accept Codex / accept Gemini / NEEDS HUMAN DECISION>
+  ➡️ 建议: <accept A / accept B / NEEDS HUMAN DECISION>
 
 ▸ DIV#2 — ...
 
@@ -231,8 +300,8 @@ ccg_actual "$CCG_DIR/gemini.prompt" "$CCG_DIR/gemini.result" gemini
 <一句话理由>
 
 ═══ 来源原文（折叠展示）═══
-🔵 Codex (gpt-5-mini): <VERDICT 段原样>
-🟢 Gemini (gemini-2.5-flash): <VERDICT 段原样>
+🔵 Reviewer A (<provider:model>): <VERDICT 段原样>
+🟢 Reviewer B (<provider:model>): <VERDICT 段原样>
 ```
 
 **关键纪律：**
@@ -243,7 +312,7 @@ ccg_actual "$CCG_DIR/gemini.prompt" "$CCG_DIR/gemini.result" gemini
 
 ### 步骤 9. 落 ledger
 
-把上面综合输出的核心部分写到 `$CCG_DIR/synthesis.txt`（前 400 字符即可，ledger 自截断），然后：
+把上面综合输出的**完整**核心结论写到 `$CCG_DIR/synthesis.txt`（ledger 自动截断前 400 字符做摘要；持久化报告则使用完整内容），然后：
 
 ```bash
 CCG_DIR=<字面路径>
@@ -251,7 +320,22 @@ source ~/.claude/commands/ccg.sh
 ccg_ledger_record "$CCG_DIR"
 ```
 
-### 步骤 10. 清理
+### 步骤 10. 持久化报告到仓库（让评审结果在 session 结束后还能被找到）
+
+```bash
+CCG_DIR=<字面路径>
+source ~/.claude/commands/ccg.sh
+ccg_persist_report "$CCG_DIR"
+```
+
+- `CCG_REPORT_OK=<path>` → 把这个路径告诉用户："本次评审完整记录已写入 `<path>`"
+- `CCG_REPORT_SKIPPED=not-a-git-repo` → 跳过持久化（不在 git 仓库下），是正常情况，不要报错
+- `CCG_REPORT_SKIPPED=disabled` → 用户显式 `CCG_NO_REPORT=1`，不要报错
+- `CCG_REPORT_FAIL=<reason>` → 提示用户检查 `.ccg/reports/` 目录权限
+
+报告位置（默认）：`<repo_root>/.ccg/reports/<sha-or-WIP>_<UTC-timestamp>.md`。建议用户把 `.ccg/` 加入 `.gitignore`（首次出现时可顺手提醒一句）。
+
+### 步骤 11. 清理
 
 ```bash
 CCG_DIR=<字面路径>
@@ -272,6 +356,157 @@ ccg_ledger_query                                # 最近 5 条评审
 ccg_ledger_query "src/auth.ts"                  # 这个文件历史评审过几次
 ```
 
+## /ccg ship — 一键交付（review → commit → merge）
+
+**语义**：`/ccg ship [target-branch] [commit-message]` = 把当前分支的 staged 改动 review 后提交，再合并到 target。
+
+| 命令 | 含义 |
+|---|---|
+| `/ccg ship` | staged → autocommit → merge 到默认保护分支 |
+| `/ccg ship main` | staged → autocommit → merge 到 main |
+| `/ccg ship main "feat: login"` | 同上，指定 commit message |
+
+**执行协议（Claude 必须严格按以下步骤）：**
+
+### 步骤 S.1 调用 ccg_ship
+
+```bash
+source ~/.claude/commands/ccg.sh
+ccg_ship "<target-branch>" "<commit-message>"
+```
+
+helper 内部自动：
+1. 若有 staged 改动 → 调 `ccg_autocommit`（AI review → 通过才 commit）
+2. 若无 staged 改动 → 跳过 commit，直接进入 merge
+3. 调 `ccg_merge <target>` → AI 辅助合并，冲突自动解决
+
+### 步骤 S.2 解读输出
+
+| 输出 | 含义 |
+|---|---|
+| `CCG_SHIP_COMMITTED=1` | staged 改动已通过 review 并 commit |
+| `CCG_SHIP_COMMITTED=0` | 没有 staged 改动，跳过 commit |
+| `CCG_SHIP_DONE=1` | 全流程完成 |
+| `CCG_SHIP_FAIL=autocommit-blocked` | review 不通过，commit 被阻断，merge 未执行 |
+| `CCG_SHIP_FAIL=merge-blocked` | commit 成功但 merge 失败（冲突需人工处理） |
+
+### 步骤 S.3 输出格式
+
+```
+## 🚀 CCG Ship 结果
+
+**分支**：`<source>` → `<target>`
+
+**Step 1 — Commit**：✅ 已提交 / ⏭️ 无 staged 改动（跳过）/ ❌ review 不通过（已阻断）
+
+**Step 2 — Merge**：✅ 合并完成 / ⚠️ 需人工处理冲突 / ❌ 失败
+
+<如果 merge 有冲突，原样转发 ccg_merge 的冲突报告表格>
+```
+
+### 环境变量
+
+| 变量 | 说明 |
+|---|---|
+| `CCG_GATE_OFFLINE=1` | 跳过 AI review，直接 commit |
+| `CCG_MERGE_DRY_RUN=1` | merge 演练，不实际提交 |
+| `CCG_MERGE_NO_FETCH=1` | 跳过 fetch（离线环境） |
+
+---
+
+## /ccg merge — AI 辅助合并（用户主动触发）
+
+**语义**：`/ccg merge [target-branch]` = **把当前分支合并到 target**。
+
+| 命令 | 含义 |
+|---|---|
+| `/ccg merge` | 站在 `feature` 上，合并到默认保护分支（main → master → develop 顺序） |
+| `/ccg merge develop` | 站在 `feature` 上，合并到 `develop` |
+| `/ccg merge feature` 站在 `main` 上 | ❌ 报 same-branch（请先 checkout feature 再用） |
+
+> **重要**：参数是"合并到哪"，不是"合并什么"。你的当前分支永远是 source。
+
+**执行协议（Claude 必须严格按以下步骤）：**
+
+### 步骤 M.0 安全前置
+
+调用前**强制确认**：
+- 当前分支(source) = `git rev-parse --abbrev-ref HEAD`
+- 工作区是否干净？
+- 目标分支是否存在？（helper 内部会校验，但 Claude 必须在 prompt 里告知用户即将合并的是 `<current> → <target>`）
+
+### 步骤 M.1 调用 ccg_merge
+
+```bash
+source ~/.claude/commands/ccg.sh
+ccg_merge "<target-branch>"          # 不传参数则默认 main/master/develop
+```
+
+helper 内部自动：
+1. 校验工作区干净（脏则 `CCG_MERGE_FAIL=dirty-working-tree` 退出）
+2. **备份 target 分支**（受影响的那一方）到 `ccg-backup/<target>-<timestamp>`
+3. `git checkout <target>` — 切到 target 让 merge commit 落在那
+4. `git merge --no-commit --no-ff <source>` — 把当前分支合并进 target
+5. 无冲突 → 直接 commit + 输出 `CCG_MERGE_RESULT=clean`
+6. 有冲突 → 解析所有冲突块 → 并行调 Codex+Gemini 决策每个冲突
+7. AI 给 `NEEDS_HUMAN_DECISION` 的冲突 → 不 commit，**留在 target 分支上**供人审
+
+### 步骤 M.2 解读 helper 输出
+
+| 输出 | 含义 | 给用户怎么说 |
+|---|---|---|
+| `CCG_MERGE_SOURCE=<x>` + `CCG_MERGE_TARGET=<y>` | 标识本次方向 | 一定要明确告诉用户：source → target |
+| `CCG_MERGE_RESULT=clean` + `CCG_MERGE_COMMITTED=1` | 合并完成、无冲突 | "✅ `<source>` 已合并到 `<target>`，你现在在 `<target>` 分支" |
+| `CCG_MERGE_RESULT=conflicts` + `CCG_MERGE_COMMITTED=1` | 有冲突，AI 解决了，已 commit | 展示冲突报告表格（helper 已输出） |
+| `CCG_MERGE_BLOCKED=needs-human` | 部分冲突 AI 不敢决策，**未 commit** | "你在 `<target>` 分支（未 commit 的 merge 状态）。请审查 `<files>`，确认后 `git commit`，或 `git merge --abort && git checkout <source>` 撤销" |
+| `CCG_MERGE_FAIL=dirty-working-tree` | 工作区脏 | "请先 `git commit` 或 `git stash` 当前改动" |
+| `CCG_MERGE_FAIL=same-branch` | 当前已经在 target 上 | "你已经在 `<target>` 分支上。请先 `git checkout <feature>` 再合并" |
+| `CCG_MERGE_FAIL=target-not-found:<x>` | target 分支不存在 | "目标分支 `<x>` 不存在。本地分支：`git branch`，远程：`git branch -r`" |
+| `CCG_MERGE_FAIL=no-target-branch` | 找不到默认保护分支 | "请显式指定目标分支：`/ccg merge <branch>`" |
+
+### 步骤 M.3 输出可视化合并报告（**严格按此格式**）
+
+helper 已经在 stdout 输出了 Markdown 表格，Claude **必须原样转发**给用户，并在表格前后加摘要：
+
+````
+## 🔀 CCG Merge 报告
+
+**Source**：`<source_branch>`（你的工作分支）
+**Target**：`<target_branch>`（被合并到，已自动切到此分支）
+**Backup**：`ccg-backup/<target>-<ts>`（target 合并前的快照，后悔时可恢复）
+
+<helper 输出的 OURS/THEIRS 表格原样贴在这里>
+
+> 表格中：OURS = target 分支原内容，THEIRS = 你的 feature 改动
+
+═══ 决策摘要 ═══
+- ✅ AI 解决：N 处
+- ⚠️ 需人审：M 处（如有，列出 file:idx）
+
+═══ 你现在在哪 ═══
+- 如果 CCG_MERGE_COMMITTED=1：你已切到 `<target>`，合并已完成，可以 `git push origin <target>`
+- 如果 CCG_MERGE_BLOCKED：你在 `<target>` 但 merge 未 commit，请审查冲突文件
+
+═══ 撤销方法 ═══
+- 撤销已 commit 的合并：`git reset --hard ccg-backup/<target>-<ts>`
+- 撤销未 commit 的合并：`git merge --abort && git checkout <source>`
+````
+
+### 关键纪律
+
+1. **永远不要弄混 source/target**：source 是用户的工作分支（current），target 是要合并到的地方（参数/默认）
+2. **OURS = target**：因为 git checkout target 后，target 的内容就是 ours
+3. **NEEDS_HUMAN_DECISION 不要替用户决策**：明确告诉用户"AI 不敢决，请你看"
+4. **保留双方代码**：AI 默认行为是合并双方逻辑，绝不静默丢弃任何一方
+5. **可视化优先**：表格比一段一段叙述清楚 10 倍
+
+### 环境变量
+
+| 变量 | 默认 | 说明 |
+|---|---|---|
+| `CCG_MERGE_DRY_RUN` | `0` | `1` = 跑全流程但不 commit（预览模式，结束时切回 source） |
+| `CCG_MERGE_NO_AI` | `0` | `1` = 跳过 AI 解决，保留冲突标记给人手工解 |
+
 ## 故障排除
 
 | 症状 | 原因 | 解决 |
@@ -285,10 +520,15 @@ ccg_ledger_query "src/auth.ts"                  # 这个文件历史评审过几
 | `CCG_*_FAIL=Model ... not registered / 503` | 代理不支持当前模型 | 显式 `CCG_CODEX_MODEL=<代理支持的型号>` |
 | `CCG_GEMINI_FAIL=error-leaked-to-stdout` | 代理把错误写到 stdout | 检查 `$CCG_DIR/gemini.err`（需 `CCG_KEEP_ARTIFACTS=1`） |
 | `CCG_*_FAIL=timeout-Ns` | CLI 超时 | 调大 `CCG_*_TIMEOUT` |
+| `CCG_REPORT_FAIL=cannot-create-dir:...` | `.ccg/reports/` 无法创建 | 检查仓库目录写权限或设 `CCG_REPORT_DIR=/path/you/own` |
+| `CCG_REPORT_SKIPPED=not-a-git-repo` | 当前目录不在 git 仓库里 | 这是预期行为，不报错；要持久化就 cd 进仓库或显式给 `CCG_REPORT_DIR` |
+| `CCG_HISTORY_SKIPPED=no-ledger` | 还没攒下评审历史 | 这是预期行为；多跑几次 `/ccg` 后历史就有了 |
+| `CCG_HISTORY_NONE=0_matches` | 这次 diff 触及的文件之前没评审过 | 这是预期行为，prompt 里不带 history 块 |
 
 ## 已知设计取舍
 
 - **Divergence over consensus**：放弃"给一份完整 review 报告"，转向"标记需要人裁决的点"。AGREEMENT 段意识形态上**故意降级**——单源 Claude 也能发现，无新增信号
+- **Ledger 双向化**：v3.x 起 ledger 不再只写——`ccg_ledger_context` 在每次评审前把"过去对同一文件的判断"作为先验注入 prompt。recurring patterns 和未解决的 fix-required 进入第一现场，不再随 session 关闭而蒸发。这是把 L6 从"日记本"升级成"结构化记忆"。
 - **同 prompt 双投喂**：训练数据差异自然产生多样性，比拍脑袋分工（codex=arch、gemini=ux）更可靠
 - **24h 缓存**：调试同段代码反复跑时省 90% 费用；改了代码 prompt hash 自然变了，无需手动失效
 - **prompt 大小硬限**：100KB ≈ 32k token，比 codex/gemini context window 小一个数量级，防止把 repo 塞进去