@boyingliu01/xp-gate 0.18.5 → 0.19.0

package/plugins/dsh/skills/delphi-review/references/code-walkthrough.md

@@ -0,0 +1,470 @@
+# 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/C 在 Round 1 互不知道对方意见
+2. **迭代共识** — 多轮直到 APPROVED
+3. **零容忍** — Critical Issues 必须修复
+4. **零降级** — 环境/资源问题必须阻断，通知用户解决
+5. **强制覆盖** — 变更必须完整评审；大型变更由用户选择完整评审或在评审前拆分
+
+---
+
+## 触发条件
+
+- **自动触发**：`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)
+    │         │
+    │         ├─→ Expert C (可行性) 匿名评审 (含 principles_findings)
+    │         │
+    │         ├─→ 共识检查
+    │         │      │
+    │         │      ├─→ 三份成功结果、三个 distinct requested_model、≥90% → 允许推送
+    │         │      │
+    │         │      ├─→ 分歧 → 继续下一轮（最多 5 轮）
+    │         │      │
+    │         │      └─→ 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` |
+
+> 必须成功执行三个专家角色，并验证三个 distinct trimmed requested_model。Provider、vendor、gateway 和模型国籍均不受限制。`provider: local` fallback 不能计数，local hosted endpoint 可作为普通 callable provider。
+
+---
+
+## 评审维度
+
+**必检项**：
+
+| 维度 | 检查内容 |
+|------|---------|
+| **正确性** | 逻辑是否正确，边界条件是否处理 |
+| **安全性** | 是否有注入、泄露、越权风险 |
+| **可维护性** | 命名、结构、注释是否清晰 |
+| **测试覆盖** | 是否有足够的测试 |
+
+**选检项**（根据变更类型）：
+
+| 变更类型 | 额外检查 |
+|---------|---------|
+| 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 / architecture 评审 (含 principles_findings)
+    │                  ├─→ Expert B / technical 评审 (含 principles_findings)
+    │                  ├─→ Expert C / feasibility 评审 (含 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 }
+    }
+  }
+}
+```
+
+---
+
+## 共识标准
+
+| 条件 | 结果 |
+|------|------|
+| 三份成功结果、三个 distinct requested_model、≥90% 且无 Critical Issues | ✅ 允许推送 |
+| 三份成功结果、≥90% 且有 Minor Issues | ✅ 允许推送（记录问题） |
+| 任一专家失败、缺失或模型重复 | ❌ 阻塞推送 |
+| 共识不足或有 Critical Issues | ❌ 阻塞推送 |
+| 有 Critical Issues | ❌ 阻塞推送 |
+| 有 Major Issues 且未处理 | ❌ 阻塞推送 |
+
+---
+
+## 成本控制 (零降级原则)
+
+| 指标 | 阈值 | 处理 |
+|------|------|------|
+| 单次走查成本 | ~$0.03 | 正常执行 |
+| 变更规模 | 无硬性文件数或行数上限 | 大型变更必须完整评审或由用户选择拆分 |
+
+大型变更没有自动跳过或绕过路径。用户可以选择完整评审，或在评审前主动拆分变更；每个变更仍须通过完整的走查和证据验证。
+
+---
+
+## Agent 可用性检查 (MANDATORY)
+
+**启动前检查**：
+
+```
+BEFORE code walkthrough:
+  ├─ 检查 Expert A 模型可用性
+  ├─ 检查 Expert B 模型可用性
+  ├─ 检查 Expert C 模型可用性
+  └─ 检查 OpenCode CLI 可用性
+
+IF 任何检查失败:
+  → BLOCK 推送
+  → 通知用户具体缺失项
+  → 提供修复指引
+  → ❌ 禁止跳过走查直接推送
+```
+
+**模型不可用处理**：
+
+| 情况 | 处理 |
+|------|------|
+| 任一专家 API 错误 | BLOCK + 提示用户检查 provider/API key |
+| OpenCode CLI 缺失 | BLOCK + 提示用户安装 OpenCode |
+
+---
+
+## Expert 评审输出格式
+
+```markdown
+## Code Walkthrough - Expert [A/B/C]
+
+### 变更摘要
+[变更的主要内容]
+
+### 发现问题
+
+| 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]
+- Expert C: [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", "role": "architecture", "verdict": "APPROVED", "confidence": 9, "result_type": "delphi_expert_result", "requested_model": "provider/model-a", "resolved_model": "provider/model-a" },
+    { "id": "Expert B", "role": "technical", "verdict": "APPROVED", "confidence": 8, "result_type": "delphi_expert_result", "requested_model": "provider/model-b", "resolved_model": null },
+    { "id": "Expert C", "role": "feasibility", "verdict": "APPROVED", "confidence": 8, "result_type": "delphi_expert_result", "requested_model": "provider/model-c", "resolved_model": "provider/model-c" }
+  ],
+  "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 未过期
+6. expires 必须是 timestamp 之后恰好 1 小时
+
+---
+
+## 与现有系统集成
+
+| 集成点 | 说明 |
+|--------|------|
+| `pre-push` hook | 验证 `.code-walkthrough-result.json` 文件（不调用 Skill） |
+| `gstack-ship` | 推送后进入发布流程 |
+| `verification-loop` | 走查通过后运行验证 |
+
+---
+
+## Anti-Patterns
+
+**只在 `--mode code-walkthrough` 时适用：**
+
+| 错误 | 正确 |
+|------|------|
+| Expert 不可用时跳过走查 | 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 已安装且可用
+- [ ] 三个专家模型 API 均可用
+- [ ] 变更已由用户选择完整评审或拆分为可审阅的变更
+- [ ] Expert A 完成匿名评审
+- [ ] Expert B 完成匿名评审
+- [ ] Expert C 完成匿名评审
+- [ ] 共识检查完成
+
+**CRITICAL - 共识验证 (code-walkthrough):**
+- [ ] 三个成功结果均为 `result_type=delphi_expert_result`
+- [ ] 三个 `requested_model` trimmed 后 distinct
+- [ ] 聚合共识 >=90%，并在 exact HEAD 上写入结果
+- [ ] 无 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 修复后重新走查**
+
+**⭐ 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小时

package/plugins/dsh/skills/delphi-review/references/orchestrator-dispatch.md

@@ -0,0 +1,64 @@
+# Orchestrator Dispatch Rules（#218 自动多轮调度）
+
+## 背景
+
+Delphi review 在 sprint-flow 中通过 subagent 调用时，Round 1→Round 2→Round 3 的调度**必须在 subagent 内部自动完成**，不能每轮暂停等待 orchestrator 或用户干预。只有在以下情况才需要 orchestrator 暂停：
+
+## 自动调度规则
+
+| 场景 | 自动处理 | 需暂停 |
+|------|---------|--------|
+| Round 1 完成，需 Round 2 | ✅ subagent 自动继续 | ❌ |
+| Round 2 完成，需 Round 3 | ✅ subagent 自动继续 | ❌ |
+| Round 3+ 完成，仍需更多轮 | ✅ subagent 自动继续，直到 max_rounds | ❌ |
+| 最终 APPROVED (>=90%) | ✅ subagent 输出结果后退出 | ❌ |
+| 最终 REQUEST_CHANGES（可自动修复） | ✅ subagent 尝试修复措辞、AC 缺失等常见问题后自动重评审 | ❌ |
+| 最终 REQUEST_CHANGES（无法自动修复） | ✅ subagent 输出详细失败报告 | **✅ orchestrator 暂停等用户** |
+| 超过 max_rounds (5) 仍无共识 | ✅ subagent 输出"未达成共识报告" | **✅ orchestrator 暂停等用户决策** |
+
+## Subagent 内部 Round 循环
+
+当 delphi-review 以 subagent 启动时（非交互式），应执行以下自动循环：
+
+```python
+round = 1
+while round <= max_review_rounds:
+    results = execute_round(round)
+    consensus = check_consensus(results)
+
+    if consensus.verdict == "APPROVED" and consensus.ratio >= 0.9:
+        emit_verdict("APPROVED", consensus)
+        break
+
+    if round == max_review_rounds:
+        emit_verdict("NO_CONSENSUS", consensus)
+        break
+
+    round += 1
+
+if verdict == "REQUEST_CHANGES":
+    auto_fix_result = attempt_auto_fix(issues)
+    if auto_fix_result.success:
+        round = 2
+        continue
+    else:
+        emit_verdict("REQUEST_CHANGES", auto_fix_result.failed_issues)
+```
+
+## 终止结果输出
+
+当 subagent 因终态退出时，必须输出清晰的裁决：
+
+- **APPROVED**: 共识报告 + specification.yaml
+- **REQUEST_CHANGES（可自动修复）**: 自动修复后再次评审
+- **REQUEST_CHANGES（不可自动修复）**: 失败报告 + 建议修复方向
+- **NO_CONSENSUS**: 分歧详情报告
+
+## 与 orchestrator 的交互约定
+
+| 状态 | Subagent 输出 | Orchestrator 动作 |
+|------|--------------|------------------|
+| APPROVED | `{verdict:"APPROVED", consensus_ratio: N, ...}` | 自动进入下一 Phase |
+| REQUEST_CHANGES (auto-fixed) | `{verdict:"APPROVED", auto_fixed: ["..."]}` | 自动进入下一 Phase |
+| REQUEST_CHANGES (unfixable) | `{verdict:"REQUEST_CHANGES", failed_issues: [...]}` | ⚠️ 暂停等用户修复后，通过 task_id 重新 dispatch |
+| NO_CONSENSUS | `{verdict:"NO_CONSENSUS", disagreements: [...]}` | ⚠️ 暂停等用户决策（可继续/中止/强制通过） |