# Code Walkthrough Mode Reference

> Extracted from `SKILL.md`. This file contains ALL content specific to the `code-walkthrough` mode of Delphi Review.

---

## Overview

代码走查模式，用于 git push 前对代码变更进行多专家 Delphi 评审。

**触发命令**: `/code-walkthrough` (等价于 `/delphi-review --mode code-walkthrough`)

---

## Five Core Properties

1. **匿名性** — Expert A/B 互不知道对方意见
2. **迭代共识** — 多轮直到 APPROVED
3. **零容忍** — Critical Issues 必须修复
4. **零降级** — 环境/资源问题必须阻断，通知用户解决
5. **强制覆盖** — 超过阈值必须 BLOCK，不能跳过

---

## 触发条件

- **自动触发**：`git push` 前（通过 pre-push hook 验证结果文件）
- **手动触发**：`/code-walkthrough` 命令（等价于 `/delphi-review --mode code-walkthrough`）

**⚠️ 重要调用方式说明**：

- ✅ **正确**: 在 Agent session 中执行 `/code-walkthrough`
- ❌ **错误**: Shell 脚本调用 `opencode code-walkthrough` (OpenCode CLI 不支持 skill 子命令)
- ❌ **错误**: CLI 子命令 `opencode run --skill code-walkthrough --diff` (不支持)

**设计决策**: code-walkthrough 是 **强制但手动触发** 的质量门禁：
- **强制**: push 必须有有效的 `.code-walkthrough-result.json` 文件
- **手动**: Skill 执行由用户在 Agent session 内触发
- **理由**: 避免 OpenCode CLI 架构限制，保持正常工作模式

**⚠️ 门禁零容忍声明**:

code-walkthrough 是强制性质控门禁，以下行为严格禁止：
- ❌ 使用 `git push --no-verify` 绕过 pre-push hook 验证
- ❌ 伪造 `.code-walkthrough-result.json` 文件
- ❌ 因为"时间紧急"或"变更很小"而跳过评审
- ❌ 修改门禁阈值让告警消失

**门禁工具检测出的问题 = 必须修复，不允许绕过。**

详见: [质量门禁行为准则](../../githooks/QUALITY-GATES-CODE-OF-CONDUCT.md)

---

## 流程概览

```
git push
    │
    ▼
pre-push hook
    │
    ├─→ 获取 git diff main...HEAD
    │
    ├─→ 提取变更摘要
    │
    ├─→ 运行 Principles Checker (Clean Code + SOLID)
    │
    ├─→ 触发 Delphi 评审 (code-walkthrough mode)
    │         │
    │         ├─→ Expert A (架构 + 设计) 匿名评审 (含 principles_findings)
    │         │
    │         ├─→ Expert B (实现 + 代码质量) 匿名评审 (含 principles_findings)
    │         │
    │         ├─→ 共识检查
    │         │      │
    │         │      ├─→ 2/2 APPROVED → 允许推送
    │         │      │
    │         │      ├─→ 分歧 → Expert C 仲裁
    │         │      │
    │         │      └─→ REQUEST_CHANGES → 阻塞推送
    │         │
    │         └─→ 写入 .code-walkthrough-result.json
    │
    └─→ 允许/阻塞推送
```

---

## 专家角色

| 专家 | 视角 | 配置 |
|------|------|------|
| Expert A | 架构 + 设计评审 | `.delphi-config.json` → `experts.architecture` |
| Expert B | 实现 + 代码质量 | `.delphi-config.json` → `experts.technical` |
| Expert C (仲裁) | 冲突裁决 | `.delphi-config.json` → `experts.feasibility` |

> ⚠️ **注意**: 至少配置 **两个不同 provider** 的模型。详见 [INSTALL.md](./INSTALL.md)。

---

## 评审维度

**必检项**：

| 维度 | 检查内容 |
|------|---------|
| **正确性** | 逻辑是否正确，边界条件是否处理 |
| **安全性** | 是否有注入、泄露、越权风险 |
| **可维护性** | 命名、结构、注释是否清晰 |
| **测试覆盖** | 是否有足够的测试 |

**选检项**（根据变更类型）：

| 变更类型 | 额外检查 |
|---------|---------|
| API 变更 | 接口兼容性、文档更新 |
| 数据库变更 | 迁移脚本、回滚方案 |
| 性能敏感 | 性能测试、基准对比 |

---

## Principles Module Integration

作为代码走查的一部分，自动运行 principles checker 分析：

```yaml
principles_module:
  enabled: true
  trigger: pre-push
  rules:
    - clean-code.all      # 9 rules
    - solid.all           # 5 rules
  integration_point: expert_prompt
  output_format: principles_findings section
```

**Principles 检查流程**：

```
git push
    │
    ▼
pre-push hook
    │
    ├─→ Step 1: Principles Checker
    │         │
    │         ├─→ 检测变更文件语言
    │         ├─→ 选择对应 Adapter
    │         ├─→ 运行 14 个规则
    │         │      │
    │         │      ├─→ Clean Code (9 rules)
    │         │      │   - long-function (>50 lines)
    │         │      │   - large-file (>500 lines)
    │         │      │   - magic-numbers (非语义数字)
    │         │      │   - god-class (>15 methods)
    │         │      │   - deep-nesting (>4 levels)
    │         │      │   - too-many-params (>7)
    │         │      │   - missing-error-handling (IO 无 try-catch)
    │         │      │   - unused-imports (未使用的导入)
    │         │      │   - code-duplication (>15% 相似度)
    │         │      │
    │         │      ├─→ SOLID (5 rules)
    │         │      │   - srp (单一职责)
    │         │      │   - ocp (开闭原则)
    │         │      │   - lsp (里氏替换)
    │         │      │   - isp (接口隔离)
    │         │      │   - dip (依赖倒置)
    │         │      │
    │         │      └─→ 输出 violations
    │         │
    │         └─→ Step 2: Delphi Code Walkthrough
    │                  │
    │                  ├─→ Expert A 评审 (含 principles_findings)
    │                  ├─→ Expert B 评审 (含 principles_findings)
    │                  └─→ 共识检查
    │
    └─→ 允许/阻塞推送
```

**Principles Findings 输出格式**（在 Expert 评审报告中添加）：

```markdown
## Principles Findings

### Clean Code Violations

| Rule | Severity | File | Line | Description |
|------|----------|------|------|-------------|
| clean-code.long-function | warning | src/api.ts | 45 | Function "processData" exceeds 50 lines |
| clean-code.deep-nesting | warning | src/utils.ts | 12 | Nesting depth 5 > threshold 4 |

### SOLID Violations

| Rule | Severity | File | Line | Description |
|------|----------|------|------|-------------|
| solid.srp | warning | src/user.ts | 1 | Class has 18 methods (>15 threshold) |
| solid.dip | warning | src/service.ts | 23 | Direct instantiation of UserRepository |

### Summary
- Total violations: [N]
- Errors: [N]
- Warnings: [N]
- Infos: [N]
```

**Principles 检查与 Delphi 评审的关系**：

| Principles 结果 | Delphi 评审行为 |
|-----------------|-----------------|
| 无 violations | Expert 正常评审，无额外关注点 |
| 有 info 级别 | Expert 评审时参考，不阻塞 |
| 有 warning 级别 | Expert 必须在评审中提及并给出意见 |
| 有 error 级别 | **自动阻塞推送**，无需 Delphi 评审 |

**阈值配置**：项目级配置文件 `.principlesrc` 可覆盖默认阈值：

```json
{
  "rules": {
    "clean-code": {
      "long-function": { "threshold": 50 },
      "god-class": { "threshold": 15 },
      "deep-nesting": { "threshold": 4 }
    },
    "solid": {
      "srp": { "methodThreshold": 15 },
      "isp": { "methodThreshold": 10 }
    }
  }
}
```

---

## 共识标准

| 条件 | 结果 |
|------|------|
| 2/2 APPROVED + 无 Critical Issues | ✅ 允许推送 |
| 2/2 APPROVED + 有 Minor Issues | ✅ 允许推送（记录问题） |
| 1/2 APPROVED | ⚠️ 需要 Expert C 仲裁 |
| 0/2 APPROVED | ❌ 阻塞推送 |
| 有 Critical Issues | ❌ 阻塞推送 |
| 有 Major Issues 且未处理 | ❌ 阻塞推送 |

---

## 成本控制 (零降级原则)

| 指标 | 阈值 | 处理 |
|------|------|------|
| 单次走查成本 | ~$0.03 | 正常执行 |
| 最大评审文件数 | 20 个文件 | 超过 → **BLOCK** |
| 最大 diff 行数 | 500 行 | 超过 → **BLOCK** |

**超过阈值处理 (零降级)**：

```
IF 超过阈值:
  → BLOCK 推送
  → 通知用户：变更过大，无法有效评审
  → 用户选项：
     A. 拆分变更（推荐）
     B. 用户明确授权跳过走查（需书面确认风险）

  ❌ 禁止自动跳过走查
  ❌ 禁止自动分批并批准
```

**设计原则**：
- 大变更跳过评审 = 质量风险泄露到生产环境
- 用户有权决定是否接受风险，AI 不能自动跳过

---

## Agent 可用性检查 (MANDATORY)

**启动前检查**：

```
BEFORE code walkthrough:
  ├─ 检查 Expert A 模型可用性
  ├─ 检查 Expert B 模型可用性
  ├─ 检查 Expert C 模型可用性（仲裁时需要）
  └─ 检查 OpenCode CLI 可用性

IF 任何检查失败:
  → BLOCK 推送
  → 通知用户具体缺失项
  → 提供修复指引
  → ❌ 禁止跳过走查直接推送
```

**模型不可用处理**：

| 情况 | 处理 |
|------|------|
| Expert A API 错误 | BLOCK + 提示用户检查 API key |
| Expert B API 错误 | BLOCK + 提示用户检查 API key |
| OpenCode CLI 缺失 | BLOCK + 提示用户安装 OpenCode |

---

## Expert 评审输出格式

```markdown
## Code Walkthrough - Expert [A/B]

### 变更摘要
[变更的主要内容]

### 发现问题

| ID | 严重程度 | 问题描述 | 代码位置 | 修复建议 |
|----|----------|----------|---------|---------|
| ... | ... | ... | ... | ... |

### 裁决
[APPROVED / REQUEST_CHANGES]

### 置信度
[X/10]
```

---

## 共识报告格式

```markdown
## Code Walkthrough 共识报告

### 变更信息
- 分支: [branch name]
- 提交数: [N]
- 文件数: [N]
- 新增行数: +[N]
- 删除行数: -[N]

### 专家意见汇总
- Expert A: [APPROVED / REQUEST_CHANGES]
- Expert B: [APPROVED / REQUEST_CHANGES]

### 共识结果
[CONSENSUS / DISAGREEMENT]

### 最终裁决
[APPROVED / REQUEST_CHANGES / NEED_ARBITRATION]

### 问题清单（如有）
[需要修复的问题]
```

---

## 结果输出文件 (MANDATORY)

完成评审后，Skill 必须写入结果文件以供 Hook 验证：

**输出文件位置**：`.code-walkthrough-result.json`

**输出文件格式**：

```json
{
  "commit": "abc123def456",
  "branch": "feature/xp-rewrite",
  "timestamp": "2026-04-14T10:30:00Z",
  "expires": "2026-04-14T11:30:00Z",
  "verdict": "APPROVED",
  "confidence": 9,
  "experts": [
    { "id": "Expert A", "verdict": "APPROVED", "confidence": 9 },
    { "id": "Expert B", "verdict": "APPROVED", "confidence": 8 }
  ],
  "issues": [],
  "consensus_ratio": 1.0,
  "files_reviewed": 5,
  "lines_added": 120,
  "lines_deleted": 45
}
```

**字段说明**：

| 字段 | 类型 | 说明 |
|------|------|------|
| `commit` | string | 当前 HEAD commit hash (git rev-parse HEAD) |
| `branch` | string | 当前分支名 |
| `timestamp` | string | 评审完成时间 (ISO 8601 UTC) |
| `expires` | string | 过期时间 (timestamp + 1小时) |
| `verdict` | string | 最终裁决: APPROVED / REQUEST_CHANGES |
| `confidence` | number | 整体置信度 (1-10) |
| `experts` | array | 专家评审结果 |
| `issues` | array | 未解决的问题（如有） |
| `consensus_ratio` | number | 问题共识比例 (≥0.90 为共识) |

**有效期机制**：

- **有效期**: 1小时
- **过期后**: Hook 将提示重新执行 `/code-walkthrough`
- **commit 必须匹配**: 文件中的 commit 必须等于当前 HEAD

**Hook 验证逻辑**：

Hook 验证以下条件（全部满足才允许 push）：

1. 文件存在
2. JSON 格式有效
3. commit hash 匹配当前 HEAD
4. verdict = APPROVED
5. timestamp 未过期 (< 1小时)

---

## 与现有系统集成

| 集成点 | 说明 |
|--------|------|
| `pre-push` hook | 验证 `.code-walkthrough-result.json` 文件（不调用 Skill） |
| `gstack-ship` | 推送后进入发布流程 |
| `verification-loop` | 走查通过后运行验证 |

---

## Anti-Patterns

**只在 `--mode code-walkthrough` 时适用：**

| 错误 | 正确 |
|------|------|
| Expert 不可用时跳过走查 | BLOCK + 提示用户修复环境 |
| 超过阈值自动跳过走查 | BLOCK + 提示用户拆分变更 |
| 超过阈值自动分批评审 | BLOCK + 用户决定是否拆分或授权跳过 |
| OpenCode CLI 缺失时允许推送 | BLOCK + 提示用户安装 OpenCode |
| 模型 API 错误时降级单模型 | BLOCK + 提示用户检查 API 配置 |
| 未写入 `.code-walkthrough-result.json` 就声明完成 | MUST 写入结果文件后才能完成 |
| 结果文件 commit hash 不匹配 | MUST 重新执行走查 |

---

## Terminal State Checklist (code-walkthrough mode)

**Pre-requisites (MANDATORY - BLOCK if missing):**
- [ ] OpenCode CLI 已安装且可用
- [ ] Expert A 模型 API 可用
- [ ] Expert B 模型 API 可用
- [ ] 变更大小在阈值内（文件 ≤20，行数 ≤500）
- [ ] Expert A 完成匿名评审
- [ ] Expert B 完成匿名评审
- [ ] 共识检查完成

**CRITICAL - 共识验证 (code-walkthrough):**
- [ ] 至少 2/2 或 2/3 专家 APPROVED
- [ ] 无 Critical Issues 未解决
- [ ] 无 Major Issues 未处理（或有处理计划）

**Final Requirements (code-walkthrough):**
- [ ] 共识报告已生成
- [ ] 问题已记录（如有）
- [ ] `.code-walkthrough-result.json` 已写入项目根目录
- [ ] 结果文件 commit hash 匹配当前 HEAD
- [ ] 结果文件未过期 (< 1小时)

**IF 任何 Pre-requisite 缺失:**
- **CANNOT 允许推送**
- **MUST BLOCK 并通知用户**
- **用户必须修复环境问题后重试**

**IF 有 Critical Issues:**
- **CANNOT 允许推送**
- **MUST 修复后重新走查**

**IF 超过大小阈值:**
- **CANNOT 允许推送**
- **MUST BLOCK 并提示拆分变更**
- **用户可明确授权跳过（需确认风险）**

**⭐ APPROVED 后必做 (code-walkthrough mode)：写入结果文件**

IF mode == `code-walkthrough` AND 最终裁决是 APPROVED，评审完成后必须：

1. 写入 `.code-walkthrough-result.json` 到项目根目录
2. 验证 JSON 格式有效
3. 验证 commit hash 匹配当前 HEAD
4. 验证 expires 字段 = timestamp + 1小时