@boyingliu01/xp-gate 0.19.2 → 0.20.0

package/plugins/qoder/skills/delphi-review/INSTALL.md

@@ -1,151 +1,150 @@
-# Installing and Configuring Delphi Review (Qoder)
+# Installing and Configuring Delphi Review
 
-This guide walks you through setting up the Delphi consensus review skill in your Qoder environment.
+This guide walks you through setting up the Delphi consensus review skill in your OpenCode environment.
 
 ## Prerequisites
 
-- **Node.js >= 18** (script uses built-in `fetch`)
-- Exactly **3 callable expert model configurations** with distinct trimmed executable model IDs
-- `@boyingliu01/xp-gate` npm package installed (for the `delphi-external-review.cjs` script)
+- OpenCode installed and configured
+- Exactly **3 callable expert model configurations** are required.
+- The three configurations must use distinct trimmed executable model IDs. They may share one provider and token plan.
 
-> Provider, vendor, gateway, and model nationality are unrestricted. One provider and token plan may serve all three roles.
+> Provider, vendor, gateway, and model nationality are unrestricted. The enforced diversity boundary is three distinct requested model IDs, not provider diversity.
 
-## Quick Setup (4 steps)
+## Quick Setup (3 steps)
 
 ### Step 1: Copy the configuration template
 
 ```bash
-# From your project root:
-cp skills/delphi-review/.delphi-config.json.example skills/delphi-review/.delphi-config.json
+# From your project root (where opencode.json lives):
+cp skills/delphi-review/.delphi-config.json.example .delphi-config.json
 ```
 
-Or if installed globally:
+This file maps abstract expert roles to agent names. You typically don't need to edit this unless you want custom agent names.
 
-```bash
-cp ~/.qoder/skills/delphi-review/.delphi-config.json.example ~/.qoder/skills/delphi-review/.delphi-config.json
+### Step 2: Add agent definitions to opencode.json
+
+Copy the `agent` block from `skills/delphi-review/opencode.json.delphi.example` into your `opencode.json`.
+
+Then replace the provider/model placeholders:
+
+```json
+// Before (template):
+"model": "YOUR_PROVIDER/YOUR_MODEL_A"
+
+// After (your config):
+"model": "bailian-tp/qwen-plus"
+// The other two role model fields must be different trimmed IDs.
 ```
 
-### Step 2: Edit the configuration
+### Step 3: Ensure provider configuration exists
+
+Your `opencode.json` must have the provider definitions. If you're using OpenCode's built-in providers (OpenAI, Anthropic, etc.), you just need API keys set in your environment.
 
-Open `.delphi-config.json` and fill in your API keys and model preferences:
+For custom providers (like Ali Bailian), add a provider entry:
 
 ```json
-{
-  "active_profile": "default",
-  "profiles": {
-    "default": {
-      "providers": {
-        "deepseek": {
-          "base_url": "https://api.deepseek.com/v1",
-          "api_key": "sk-your-key-here"
+"provider": {
+  "my-custom-provider": {
+    "npm": "@ai-sdk/anthropic",
+    "name": "My Custom Provider",
+    "options": {
+      "baseURL": "https://your-api-endpoint.com/v1",
+      "apiKey": "your-api-key"
+    },
+    "models": {
+      "my-model-name": {
+        "name": "My Model Name",
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
         },
-        "zhipu": {
-          "base_url": "https://open.bigmodel.cn/api/paas/v4",
-          "api_key": "your-key-here"
+        "limit": {
+          "context": 128000,
+          "output": 8192
         }
-      },
-      "experts": {
-        "architecture": { "provider": "deepseek", "model": "deepseek-chat" },
-        "technical": { "provider": "zhipu", "model": "glm-5.2" },
-        "feasibility": { "provider": "deepseek", "model": "deepseek-reasoner" }
       }
     }
   }
 }
 ```
 
-### Step 3: Verify Node.js version
-
-```bash
-node --version  # Must be >= 18.0.0
-```
-
-### Step 4: Verify configuration
+## Model Recommendations
 
-Test that the script can read your config and the API is reachable:
+The skill requires exactly three experts for every mode. Choose three models that are callable through your configured provider.
 
-```bash
-node <script-path> --expert architecture --input "Test review: verify connectivity" --round 1 --config skills/delphi-review/.delphi-config.json
-```
+| Expert Role | Recommended | Alternatives |
+|-------------|-------------|-------------|
+| **Architecture (Expert A)** | Claude Sonnet 4 | GPT-4o, Qwen-Plus, Gemini 2.5 Pro |
+| **Technical (Expert B)** | Claude Haiku | Qwen-Coder, DeepSeek-Coder, GPT-4o-mini |
+| **Feasibility (Expert C)** | Claude Opus | GPT-4, Gemini 2.5 Pro, Qwen-Max |
 
-Where `<script-path>` is located (in priority order):
-1. `node_modules/@boyingliu01/xp-gate/scripts/delphi-external-review.cjs`
-2. `$(npm root -g)/@boyingliu01/xp-gate/scripts/delphi-external-review.cjs`
+**Minimum viable setup**:
+- Expert A: architecture model
+- Expert B: technical model
+- Expert C: feasibility model
+- All three requested model IDs must be distinct. A `provider: local` fallback does not count.
 
-## Configuration Reference
+## Configuration File Reference
 
 ### `.delphi-config.json`
 
-| Field | Required | Description |
-|-------|----------|-------------|
-| `active_profile` | ✅ | Name of the active configuration profile |
-| `profiles` | ✅ | Named configuration profiles (for easy switching) |
-| `profiles.<name>.providers` | ✅ | Provider definitions: base_url + api_key |
-| `profiles.<name>.experts` | ✅ | Expert-to-provider/model mapping |
-| `profiles.<name>.experts.<role>.provider` | ✅ | Callable provider name; `"local"` fallback cannot count |
-| `consensus.threshold_percent` | ❌ | Consensus threshold (default: 90) |
-| `consensus.max_review_rounds` | ❌ | Max review rounds (default: 5) |
-
-### Switching profiles
-
-Edit `active_profile` in the config, or use the `--profile <name>` CLI argument to override temporarily.
-
-### Single-provider setup
-
-One provider may expose all three distinct executable models:
-
-```json
-{
-  "active_profile": "starter",
-  "profiles": {
-    "starter": {
-      "providers": {
-        "deepseek": { "base_url": "https://api.deepseek.com/v1", "api_key": "sk-xxx" }
-      },
-      "experts": {
-        "architecture": { "provider": "deepseek", "model": "deepseek-chat" },
-        "technical": { "provider": "deepseek", "model": "deepseek-reasoner" },
-        "feasibility": { "provider": "deepseek", "model": "deepseek-coder" }
-      }
-    }
-  }
-}
-```
-
-> All three model IDs must remain distinct after trimming, and all three calls must succeed.
+| Field | Description | Default |
+|-------|-------------|---------|
+| `num_experts` | Number of experts to use | 3, fixed |
+| `experts.architecture` | Architecture reviewer configuration | Required |
+| `experts.technical` | Technical reviewer configuration | Required |
+| `experts.feasibility` | Feasibility reviewer configuration | Required for 3-expert mode |
+    | `consensus.threshold_percent` | Agreement threshold | 90 |
+| `consensus.max_review_rounds` | Maximum review rounds | 5 |
+| `consensus.cross_provider_required` | Deprecated and ignored; emits `cross_provider_required_ignored` | false or omitted |
+
+### `opencode.json` agent block
+
+| Field | Description |
+|-------|-------------|
+| `model` | Provider/model identifier (e.g., `openai/gpt-4o`) |
+| `mode` | Must be `"subagent"` |
+| `prompt` | Expert role instructions |
+| `tools` | Tool permissions (read: true, write: false recommended) |
 
 ## Usage
 
 Once configured, invoke the skill via:
 
-```
+```bash
 /delphi-review
 ```
 
-The skill will:
-1. Read `.delphi-config.json` to find expert configurations
-2. Call external model APIs via `delphi-external-review.cjs` script
-3. Reject `provider: "local"` fallback as non-executed evidence
-4. Aggregate verdicts and compute consensus
+Or reference it in your workflows. The skill will automatically use the agents defined in your `opencode.json`.
 
 ## Troubleshooting
 
-### "Config file not found"
+### "Agent delphi-reviewer-xxx not found"
+
+The agent definitions in `opencode.json` don't match the names in `.delphi-config.json`. Verify:
+1. Agent names in `.delphi-config.json` match keys in `opencode.json` `agent` block
+2. opencode.js is valid JSON (use `jq . opencode.json` to verify)
+
+### "Model YOUR_PROVIDER/YOUR_MODEL not available"
 
-Copy `.delphi-config.json.example` to `.delphi-config.json` and fill in your API keys.
+You forgot to replace the placeholder. Search for `YOUR_PROVIDER` in your opencode.json and replace with actual values.
 
-### "Script not found"
+### Both experts gave identical feedback
 
-Install the npm package: `npm install -g @boyingliu01/xp-gate`
+Shared providers are allowed. Configure three distinct executable model IDs and verify all three calls succeed.
 
-### "Authentication failed (401)"
+### Review takes too long / costs too much
 
-Check your API key in `.delphi-config.json`. Ensure the key matches the provider.
+Do not reduce the expert count. Use three callable models and keep the threshold and round bounds unchanged.
 
-### "Expert model IDs are not distinct"
+## Advanced: JSON Schema Validation
 
-Configure three distinct callable model IDs. They may use the same provider.
+For IDE autocompletion and validation, reference the schema in your `.delphi-config.json`:
 
-### "Node.js >= 18 required"
+```json
+{
+  "$schema": "https://example.com/delphi-config.schema.json"
+}
+```
 
-Upgrade Node.js. The script uses the built-in `fetch` API.
+The schema file is available at `.delphi-config.schema.json` in this directory.

package/plugins/qoder/skills/delphi-review/SKILL.md

@@ -4,8 +4,8 @@ version: 1.1.0
 description: >
   Performs multi-round anonymous expert consensus review using the Delphi method. Supports
   design review (default), code-walkthrough (--mode code-walkthrough), and requirements
-  (--mode requirements) modes. Uses exactly 3
-  successfully executed experts with distinct model IDs and a >=90% statistical consensus threshold.
+  (lightweight, --mode requirements) modes. Uses exactly three experts with distinct executable
+  model IDs and a >=90% statistical consensus threshold.
   Outputs structured verdict (APPROVED/PASS_WITH_CAVEATS/REQUEST_CHANGES/BLOCKED).
 
   WHAT: Anonymous multi-expert review with iterative consensus building for designs, plans,
@@ -21,12 +21,13 @@ description: >
   "多专家评审", "consensus review", "code walkthrough", "push review", "architecture review",
   "delphi review", "run delphi", "start delphi", "评审这个架构", "review this architecture",
   "评审PR", "review this PR with delphi", "delphi评审", "delphi 评审", "run delphi review",
-  "执行delphi", "启动delphi评审".
+  "执行delphi", "启动delphi评审", "review the requirements", "评审需求", "requirements review",
+  "/requirements-review".
   NEGATIVE TRIGGERS: "how does delphi work", "what is delphi review", "code review checklist",
   "review my code quickly", "can you review this", "peer review", "I need a review",
   "explain the review process", "review guidelines", "how to review a design",
   "code review template", "review format", "PR review", "帮我review一下",
-  "just review this", "quick review", "review steps".
+  "just review this", "quick review", "review steps", "review my requirements document".
 maturity: beta
 auto_continue: true
 triggers:
@@ -52,6 +53,10 @@ triggers:
   - "run delphi review"
   - "执行delphi"
   - "启动delphi评审"
+  - "review the requirements"
+  - "评审需求"
+  - "requirements review"
+  - "/requirements-review"
 triggers_negative_examples:
   - "how does delphi work"       # educational question about the process
   - "what is delphi review"      # asking for explanation, not execution
@@ -73,6 +78,7 @@ triggers_negative_examples:
   - "review format"              # asking about format, not executing
   - "show me how to review"      # educational request about reviewing
   - "review checklist example"   # asking for examples, not running review
+  - "review my requirements document"  # educational discussion about requirements, not executing review
 triggers_negative_test_cases:
   - input: "how does delphi work"
     expect: "NOT triggered"
@@ -130,6 +136,16 @@ triggers_negative_test_cases:
     expect: "NOT triggered"
   - input: "run delphi"
     expect: "triggered"
+  - input: "review the requirements"
+    expect: "triggered"
+  - input: "评审需求"
+    expect: "triggered"
+  - input: "requirements review"
+    expect: "triggered"
+  - input: "/requirements-review"
+    expect: "triggered"
+  - input: "review my requirements document"
+    expect: "NOT triggered"
 workflow_steps:
   - "Step 0: Input Validation → Output: [DelphiReview] or [DelphiReview:BLOCKED]"
   - "Round 1: Anonymous Independent Review → Output: [DelphiReview Round 1] expert JSON verdicts"
@@ -170,10 +186,10 @@ tools_denied:
 ## Scope
 
 **In Scope:**
-- Multi-round anonymous expert consensus review (design + requirements + code-walkthrough modes)
-- Exactly 3 experts with distinct trimmed executable model IDs and statistical consensus (>= 90%)
+- Multi-round anonymous expert consensus review (design + code-walkthrough modes)
+- Exactly three experts with distinct normalized executable model IDs and statistical consensus (>= 90%)
 - Structured verdict: APPROVED / PASS_WITH_CAVEATS / REQUEST_CHANGES
-- Provider, vendor, gateway, country, and model nationality are unrestricted; any expert execution failure blocks approval
+- Model nationality, vendor, provider, and gateway are unrestricted.
 
 **Out of Scope:**
 - Does NOT implement code changes (review only, implementation is separate)
@@ -204,6 +220,10 @@ tools_denied:
 - run delphi review
 - 执行delphi
 - 启动delphi评审
+- review the requirements
+- 评审需求
+- requirements review
+- /requirements-review
 
 **NOT triggered by:**
 - "how does delphi work" (educational)
@@ -223,16 +243,17 @@ tools_denied:
 - "code review template" (asking for template)
 - "review format" (asking about format)
 - "show me how to review" (educational)
+- "review my requirements document" (educational discussion, not execution)
 
 ## Workflow
 
 1. **Step 0: Input Validation** — Check input contains reviewable content (design doc/code/spec/diff). Empty input → `[DelphiReview:BLOCKED]`.
-2. **Round 1: Anonymous Independent Review** — Launch the architecture, technical, and feasibility Custom Agents independently. Record three successful `delphi_expert_result` records and each `requested_model`.
-3. **Execution Verification** — Require all three records and three distinct trimmed requested model IDs. Model provider, vendor, gateway, and nationality are unrestricted.
-4. **Consensus Check** — Aggregate all three results; consensus >=90% AND all APPROVED → complete.
-5. **Rounds 2-5** — Exchange evidence and re-evaluate with all three Custom Agents until approved or five rounds are exhausted.
-6. **Failure Handling** — Missing/failed agents, duplicate model IDs, or no consensus after Round 5 → BLOCK; never reduce the expert count.
-7. **Generate Output** — Consensus report + specification.yaml (design) or `.code-walkthrough-result.json` (walkthrough) + `delphi-reviewed.json`.
+2. **Round 1: Anonymous Independent Review** — Invoke architecture, technical, and feasibility independently without exposing their opinions to one another. Every successful result must use `result_type=delphi_expert_result`.
+3. **Execution Verification** — Verify that all three results succeeded and that their `requested_model` values are three distinct trimmed IDs, confirmed against the platform's execution record rather than expert self-report alone (OpenCode: the provider call log; Qoder: the `model` field of `model.request.started` events under `~/.qoder/logs/sessions/<project>/<sessionId>/segments/*.jsonl` — the `--model` argv in `~/.qoder/logs/runs/*/manifest.json` is the session model and proves nothing about subagents). A local fallback (`provider: local`) is not an executed expert and cannot satisfy this check; a local hosted endpoint configured as an ordinary callable provider can. Each expert record must also carry an explicit `channel` of either `external` or `local`; the value is a whitelist and a missing or unknown value fails the gate (it is never defaulted, since defaulting would let a forged record pass by simply omitting the field). Where the platform pins subagents to the session model (current Qoder Custom Agent dispatch, see the Qoder section below), the check cannot pass on built-in models at all and the external provider path is required.
+4. **Consensus Check** — Aggregate all three successful expert results. Consensus >=90% AND all APPROVED → complete. One expert result is never global approval.
+5. **Rounds 2-5: Exchange and Final Positions** — If needed, expose prior aggregate evidence, re-evaluate, and stop at the first approved consensus or after five rounds.
+6. **Failure Handling** — Any expert failure, missing result, duplicate model ID, or unverifiable execution blocks the review. Do not substitute a local fallback or silently reduce the expert count.
+7. **Generate Output** — Write the consensus report and mode-specific evidence only after aggregation. For code walkthrough, bind the exact-HEAD result after aggregation.
 
 ## Activation (MANDATORY for L1 Trigger Detection)
 
@@ -281,37 +302,11 @@ Each round MUST output a structured round marker:
 |------|------|------|------|
 | `design`（默认） | `/delphi-review` | 需求/设计/架构/PR 评审 | 共识报告 + specification.yaml |
 | `code-walkthrough` | `--mode code-walkthrough` | git push 前代码走查 | `.code-walkthrough-result.json` |
-| `requirements` | `--mode requirements` | Phase 2 R1 需求完整性评审 | `.sprint-state/phase-outputs/requirements-reviewed.json` |
+| `requirements` | `--mode requirements` | Phase 2 THINK 阶段需求评审 | `.sprint-state/phase-outputs/requirements-reviewed.json` |
 
 **Code Walkthrough 模式**的完整规范 → 详见 `references/code-walkthrough.md`
 
-### Requirements 模式（Qoder Custom Agents）
-
-在 Phase 2 需求探索完成、设计审批前，并行运行 Qoder 的 architecture、technical、feasibility 三个 Custom Agent。Round 1 保持匿名；任一 Agent 未成功返回、任一裁决不是 `APPROVED`、三个 trimmed `requested_model` 不互异，或聚合 `consensus_ratio < 0.90` 时，R1 必须 BLOCK，不能减少专家数或使用仲裁结果代替。
-
-APPROVED 后读取 `git rev-parse HEAD` 的精确结果并写入 `.sprint-state/phase-outputs/requirements-reviewed.json`。无法解析 HEAD 时不得写 APPROVED 证据：
-
-```json
-{
-  "mode": "requirements",
-  "verdict": "APPROVED",
-  "timestamp": "2026-08-20T10:30:00Z",
-  "requirements_statement": "<被评审的原始需求陈述>",
-  "context_file_used": "CONTEXT.md | null",
-  "requirements_hash": "<SHA-256 of requirements_statement + context exact UTF-8 content if used + timestamp YYYY-MM-DD>",
-  "head_commit": "<exact git rev-parse HEAD>",
-  "consensus_ratio": 0.90,
-  "expert_verdicts": [
-    { "role": "architecture", "verdict": "APPROVED", "result_type": "delphi_expert_result", "requested_model": "provider/model-a" },
-    { "role": "technical", "verdict": "APPROVED", "result_type": "delphi_expert_result", "requested_model": "provider/model-b" },
-    { "role": "feasibility", "verdict": "APPROVED", "result_type": "delphi_expert_result", "requested_model": "provider/model-c" }
-  ]
-}
-```
-
-Schema-v2 对 context 路径执行项目根目录 containment 与 realpath 检查，并在 Phase 2 transition 时重新计算 hash；生成 hash 为小写 hex，比较时大小写不敏感。
-
-`confidence` 可以由 Custom Agent 提供，但不是 R1 evidence contract 的必需字段。Phase 2 全部步骤完成、进入 Phase 3 前必须执行 `npx xp-gate phase-transition 2 completed`；schema-v2 Sprint 只有通过程序化校验才能继续。
+**Requirements 模式**的完整规范 → 详见 `references/requirements.md`
 
 ---
 
@@ -321,37 +316,122 @@ Schema-v2 对 context 路径执行项目根目录 containment 与 realpath 检
 
 | 配置 | 专家 | 适用场景 |
 |------|------|---------|
-| 3 专家（强制） | A(架构) + B(实现) + C(可行性) | 所有评审模式 |
+| 3 专家（固定） | A(架构) + B(实现) + C(可行性) | 所有评审模式 |
 
 ### 模型选择策略（强制 — 平台适配）
 
 **关键原则**：
-- ✅ 三个专家必须成功执行且使用 **三个 distinct trimmed model IDs**
-- ❌ 禁止 hardcode 模型名称
-- ✅ Provider、vendor、gateway 和模型国籍不受限制
-- ❌ `provider: local` fallback 不能计为成功执行
+- ✅ 必须配置 architecture、technical、feasibility 三个专家角色
+- ✅ 三个角色必须使用三个不同的 trimmed、可执行模型 ID
+- ✅ 模型国籍、厂商、provider 和 gateway 不受限制
+- ✅ 三个角色可以共享一个 provider 和 token 计划
+- ❌ `provider: local` 的特殊 fallback 不能计为一次成功执行
+
+#### Qoder 平台（Custom Agent 模式 — 只能做到同模型三角色）
+
+Qoder 的内置模型**没有本地推理端点**：推理请求由 Qoder 客户端经服务端代理发出，凭证是一次性 job token。所以不能照搬 OpenCode 的 `base_url + api_key` 直连方式；Qoder 侧内置模型的唯一入口是 **Custom Agent** —— 每个专家一个独立 agent 文件，frontmatter 用 `model` 字段声明模型。
+
+**契约结论（先说结论）**：这条路径**不满足**"三个不同可执行模型 ID"契约。2026-09-23 做过一次排除混杂因素的复测：先把 `~/.qoder/agents/delphi-*.md` 三份文件绑成三个不同的 0.1× 内置模型（`qfmodel` / `dfmodel` / `gfmodel`；架构角与会话模型同名，所以真正有判别力的是技术角与可行性角），**再**新开会话——新 CLI 进程，`session.config.loaded` 记录 `model: "qfmodel"`，注册表加载的必然是已修好的绑定——然后只派发三个 subagent，各回一句话、不调工具。结果：三个独立的 `is_subagent: true` turn，`turn.started` / `model.request.started` / `model.response.completed` 三处的 `model` 全为会话模型 `qfmodel`，`dfmodel` / `gfmodel` 出现 0 次；同时三份回复分别命中架构 / 技术 / 可行性视角，说明角色提示词确实生效、agent 也确实被加载。即 `subagent_type` 派发路径采纳 Custom Agent 的提示词，但**丢弃**它的 `model` 绑定。
+
+因此 Qoder 原生模式只能作为**同模型、三角色（persona）的自查**，其共识比例不能当作多模型交叉验证的证据，也不应用作 Gate MW 的三模型凭据。需要契约合规的 Delphi 时，按上面的外部 provider 方式配置 `.delphi-config.json`（Qoder 与 OpenCode 同用，条件是模型确有可调端点）。
 
-#### Qoder 平台（推荐 — Custom Agent 模式）
+| 角色 | Agent 文件 | 绑定的 modelId | 实际执行模型 |
+|------|-----------|---------------|-------------|
+| Architecture (A) | `.qoder/agents/delphi-architecture.md` | `qfmodel` | 会话模型 |
+| Technical (B) | `.qoder/agents/delphi-technical.md` | `gfmodel` | 会话模型 |
+| Feasibility (C) | `.qoder/agents/delphi-feasibility.md` | `dfmodel` | 会话模型 |
 
-Qoder 环境下使用 **Custom Agent** 机制，每个专家是一个独立的 custom agent，配置不同的 Qoder 内置模型：
+**安装位置**（`xp-gate init` 自动部署，已存在的文件不覆盖）：
+- 项目级：`<project>/.qoder/agents/`（`xp-gate init`）
+- 用户级：`~/.qoder/agents/`（`xp-gate init --global`）
 
-| 专家 | Agent 文件 | 模型 | Credits 费率 |
-|------|-----------|------|-------------|
-| Architecture (A) | `.qoder/agents/delphi-architecture.md` | Qwen3.7-Max | 0.5× |
-| Technical (B) | `.qoder/agents/delphi-technical.md` | GLM-5.2 | 0.6× |
-| Feasibility (C) | `.qoder/agents/delphi-feasibility.md` | DeepSeek-V4-Pro | 0.5× |
+**model 字段格式**：仍须写成 `"[DisplayName](modelId)"`。裸名字或已下线 ID 不会报错，会被平台静默忽略。`xp-gate init` 会审计已部署的 `delphi-*.md`，格式非法或 modelId 与本版本模板不一致时点名文件并给出"删除 → 重跑 `init` → 重启会话"提示；因为部署语义是"已存在不覆盖"，从 #417 之前的版本升级必须手工删旧文件再重跑 `init`。注意：修好绑定也只是让角色声明规范，并不改变上表的执行模型结论。
 
-**执行方式**：通过 Agent tool 并行启动 3 个 subagent（type=GeneralPurpose），每个 agent 使用自己配置的模型独立评审，主 orchestrator 收集结果后计算共识。
+**执行方式**：用 Agent tool 并行派发 3 个 subagent，`subagent_type` 分别取 `delphi-architecture`、`delphi-technical`、`delphi-feasibility`。**新建或修改 agent 文件后必须重开会话**——注册表只在会话启动时加载，否则报 `Unknown agent type`。
 
-**优势**：无需外部 API key，直接使用 Qoder Credits，模型由平台统一管理。
+**客观验证（不要采信专家自述）**：`~/.qoder/logs/runs/*/manifest.json` 的 argv `--model` 记录的是**会话/进程启动模型**，对 subagent 没有判别力（历史上所有运行都是同一个 ID）。真正的证据在按会话分段的日志里：
+
+```bash
+grep '"type":"model.request.started"' ~/.qoder/logs/sessions/<project>/<sessionId>/segments/*.jsonl \
+  | grep -oE '"model":"[^"]*"' | sort | uniq -c
+```
+
+同一文件里的 `turn.started`（`is_subagent:true`）与 `model.response.completed` 可交叉核对：前者证明三个角色各自起了独立 turn，后者带 `provider` 字段。两个坑：(1) 被验证的那个 modelId 必须**不等于会话模型**，否则该角色测不出判别力（会话模型通常是 `qfmodel`）；(2) 改完 agent 文件必须**换新会话**再测，注册表只在会话启动时加载，用旧会话的数据下结论会被旧绑定污染。专家自述的 `requested_model` 只是在复述自己 frontmatter 里的声明，不构成证据。
+
+**成本**：走这条路径不消耗外部 API key，只计 Qoder Credits。
 
 #### OpenCode 平台（External API 模式）
 
 OpenCode 环境下通过 `opencode.json` 的 agent 配置 + `.delphi-config.json` 调用外部 API：
 - **MUST 从 `opencode.json` 的 agent 配置中读取模型**
-- 通过 `scripts/delphi-external-review.cjs` 调用各 provider 的 OpenAI 兼容 API
+- 通过 `scripts/delphi-external-review.cjs` 调用各 provider 的兼容 API（注意：该脚本目前在仓库根 `scripts/` 下，尚未随 skill 目录分发）
 - 需要用户自行配置 API key（环境变量注入）
 
+#### DeepSeek Harness 平台（`delphi-review` 工具 — 推荐）
+
+DSH 里**不要**用 `subagent` 工具派发三个专家。原因和 Qoder 同源：DSH 的 subagent
+继承宿主配置的**单一**模型（`SubagentModelSelectionConfig.enabled` 默认 `false`），
+三个"专家"会是同一模型的三个实例 —— 按本 skill 的规则必须 BLOCK。
+
+DSH 的正确入口是插件提供的 **`delphi-review` 工具**（`@boyingliu01/dsh-plugin-xp-gate`）：
+
+```
+delphi-review(
+  subject:   <待评审材料：diff / 设计 / 规格>,
+  addressed: <可选：上一轮之后改了什么，用于后续轮次>,
+  maxRounds: <可选：覆盖默认 5 轮>
+)
+```
+
+该工具**直连外部 OpenAI 兼容网关**，每个席位绑定一个不同模型，因此不依赖宿主配置即可
+满足不变量。它复用**同一份** `.delphi-config.json`，无需额外配置。
+
+**代码强制的不变量**（不是文档约定，违反即报错）：
+
+| 不变量 | 违反时 |
+|---|---|
+| 恰好 3 位专家 | `DelphiConfigError` |
+| 3 个 `requested_model` 去空白后两两不同 | `DelphiConfigError` |
+| 模型不得为未展开的 `${...}` 占位符 | `DelphiConfigError`（在**任何网络调用之前**） |
+| 缺密钥 / 缺 provider / 专家跨网关 | `DelphiSetupError`，报变量名而非回显配置 |
+| 报告缺 `### VERDICT` 段 | 记为 `INVALID_NO_VERDICT`，**不计入共识** |
+| 退出码 0 但内容为空 | 记为 ERROR（推理模型可能把预算全烧在隐藏 token 上） |
+
+**轮次语义与本 skill 一致**：Round 1 匿名且并发；Round 2+ 回传**汇总票型**与"已修改项"，
+个体报告始终匿名。达到阈值即停，否则到 `max_review_rounds` 为止并如实返回 `NO CONSENSUS`。
+
+**推理模型注意**：`g-glm-5.3-flash` 这类模型会先产出隐藏推理 token。
+实测 `max_tokens=4000` 时 `finish_reason=length` 且 **content 为空**；
+席位需独立预算（该席位配置为 32000）。工具把"空内容"记为 ERROR 而非空评审。
+
+> 备选：若希望 DSH **原生** `subagent` 也能选模型，需同时满足
+> (1) `dsh-tool-subagent` 的 `modelSelectionSettings: true`（仅能力开关），
+> (2) 宿主设置 `SubagentModelSelectionConfig.enabled = true` 且 `allowedModels` ≥3 个不同模型。
+> 该路线依赖宿主配置，CI / 一次性会话不可靠，故不作为默认路径。
+#### WorkBuddy 平台（Expert 团队模式）
+
+WorkBuddy 侧以 Team 型专家团（示例：`delphi-review-team`，安装在 `~/.workbuddy/plugins/marketplaces/my-experts/plugins/`，创建方式见 [docs/platform-workbuddy.md](../../docs/platform-workbuddy.md)）承载评审，触发本技能后按此路由执行：
+
+| 角色 | Agent ID | 绑定模型 | 倍率 |
+|------|----------|---------|------|
+| 主理人（衡定一，会话自身） | delphi-review-team-team-lead | 会话模型，固定用 `local-deepseek-v4-flash` | 零 credits |
+| Architecture (A) | delphi-arch-reviewer | `deepseek-v4.1-flash` | x0.11 |
+| Technical (B) | delphi-tech-reviewer | `glm-5.3-flash` | x0.06 |
+| Feasibility (C) | delphi-feasibility-reviewer | `hy3` | x0.00（免费） |
+
+**执行方式**：
+- 主理人开场自检：会话模型不是 `local-deepseek-v4-flash` 时，先提醒用户切换再开始。
+- 已启用专家团 → 按其团队机制 spawn 3 位成员；未启用 → 用 `Agent` 工具同一消息**并行** spawn 3 个 `general-purpose` 子代理，prompt = 对应专家 MD 全文人设（读专家团 `agents/` 目录）+ 匿名评审模板 + 待评审材料，`model` 参数按上表传。
+- Round 1 三个子代理互不见对方输出（匿名铁律不变）。
+
+**执行验证（适配本平台，2026-09-29 校准）**：
+- 参数层路由 ✅ 已实测：`Agent` 工具 `model` 参数传 `deepseek-v4.1-flash` / `glm-5.3-flash` / `hy3` 三个 ID 均被接受，3 个 general-purpose 子代理并行执行成功。
+- 执行层证据 ⚠️ 平台暂缺：WorkBuddy 审计日志（`~/.workbuddy/audit-log/`）只记 command-safety 事件，无 per-request 模型路由记录，无法像 Qoder/OpenCode 那样从日志取证 distinct models。
+- **WorkBuddy 过渡验证标准**：参数级校准（model ID 被平台接受且子代理成功执行）+ 专家 `requested_model` 自述如实记录；报告中必须注明「执行层验证待平台日志支持」。若 `model` 参数被拒绝（报错/回落会话模型），按本技能 Failure Handling 处理，不得静默降级冒充三模型共识。
+- 契约合规兜底：需要严格证据时，走外部 provider 路径（`.delphi-config.json` + 兼容 API，如 whalecloud 网关 3 个模型 ID）。
+
+**成本**：3 专家合计 x0.17/轮；主理人选 local 会话模型则零 credits。
+
 ### 共识阈值
 
 | 阈值 | 说明 |
@@ -422,7 +502,7 @@ Phase 0: 准备 → Round 1: 匿名独立评审 → 共识检查
 
 ## Output Format (MANDATORY for L3)
 
-Every Delphi mode MUST use the full JSON schema below. Each of the three Qoder Custom Agents outputs independently and the orchestrator aggregates only after execution verification. There is no single-reviewer Delphi approval path.
+Every Delphi mode MUST use the full JSON schema below. Architecture, technical, and feasibility each output independently; the orchestrator verifies all three executions before aggregating `consensus_report`. There is no single-reviewer Delphi approval path.
 
 ```json
 {
@@ -445,7 +525,31 @@ Every Delphi mode MUST use the full JSON schema below. Each of the three Qoder C
 
 **For code-walkthrough mode**, output follows `.code-walkthrough-result.json` schema (see `references/code-walkthrough.md`).
 
-**For requirements mode**, output follows the Requirements 模式 schema above and includes exact HEAD plus all three successful Custom Agent results.
+**For requirements mode**, output follows `requirements-reviewed.json` schema (see `references/requirements.md`):
+
+```json
+{
+  "mode": "requirements",
+  "verdict": "APPROVED|GAPS_FOUND",
+  "timestamp": "2026-07-25T10:30:00Z",
+  "consensus_ratio": 1.0,
+  "requirements_hash": "<SHA-256 hex digest>",
+  "head_commit": "<git rev-parse HEAD>",
+  "context_file_used": "CONTEXT.md",
+  "round": 1,
+  "expert_verdicts": [
+    { "role": "architecture", "verdict": "APPROVED", "confidence": 9, "result_type": "delphi_expert_result", "requested_model": "provider/model-a", "resolved_model": "provider/model-a", "channel": "external" },
+    { "role": "technical", "verdict": "APPROVED", "confidence": 8, "result_type": "delphi_expert_result", "requested_model": "provider/model-b", "resolved_model": "provider/model-b", "channel": "external" },
+    { "role": "feasibility", "verdict": "APPROVED", "confidence": 8, "result_type": "delphi_expert_result", "requested_model": "provider/model-c", "resolved_model": "provider/model-c", "channel": "external" }
+  ],
+  "requirements_statement": "<short summary of what was reviewed>",
+  "gaps_found": [],
+  "rounds_used": 1,
+  "escalation_needed": false
+}
+```
+
+Schema-v2 Phase 2 requires `requirements_statement`, `timestamp`, `consensus_ratio`, `expert_verdicts`, `head_commit`, and `requirements_hash`. The hash is SHA-256 of the exact concatenation `requirements_statement + project-relative context file UTF-8 content if used + timestamp YYYY-MM-DD`; context paths must remain inside the project after realpath resolution.
 
 **Anti-patterns mapping:**
 - `Round 1 → "评审完成"` → MUST NOT have `verdict: APPROVED` if `critical_issues` exist
@@ -457,7 +561,7 @@ Every Delphi mode MUST use the full JSON schema below. Each of the three Qoder C
 ## Terminal State Checklist
 
 - [ ] Phase 0 完成（文档验证 + 专家分配）
-- [ ] 已完成所需轮次（最多 5 轮，每轮三个 Custom Agent 均执行）
+- [ ] 已完成所需轮次（最多 5 轮，每轮三位专家均执行）
 - [ ] 问题共识比例 >=90%
 - [ ] 所有 Critical Issues 已解决，Major Concerns 已处理
 - [ ] 最终裁决是 **APPROVED** 或 **APPROVED_WITH_MINOR**
@@ -493,14 +597,16 @@ Every Delphi mode MUST use the full JSON schema below. Each of the three Qoder C
 |---------|---------|
 | Round 1 未 APPROVED 就"评审完成" | 迭代直到 APPROVED，修复后重新评审 |
 | 只处理 Critical，忽略 Major | 零容忍：Critical/Major 全部必须处理 |
-| 单专家自评 | 三个 distinct executable models 全部成功执行 |
+| 单专家自评 | 必须运行 architecture、technical、feasibility 三位专家，并聚合三份成功结果 |
 | 用户说"时间紧急"就跳过 | 评审是投资不是开销 |
 | "专家几乎一致"就通过 | "几乎" = 不一致，继续到 >=90% |
-| 按 provider 或模型国籍限制选择 | 仅强制三个 distinct trimmed model IDs |
-| `provider: local` fallback 计入 | fallback 不算成功执行证据 |
+| 使用任何国籍或厂商的模型 | 模型国籍和厂商均不受限制，仍必须满足三个 distinct executable model IDs |
+| 三个专家同一 provider | 允许共享 provider，只要三个 requested_model IDs distinct 且每个调用成功 |
 
 **Code-walkthrough 专属 Anti-Patterns** → 详见 `references/code-walkthrough.md`
 
+**Requirements 专属 Anti-Patterns** → 详见 `references/requirements.md`
+
 ---
 
 ## Red Flags
@@ -510,7 +616,7 @@ Every Delphi mode MUST use the full JSON schema below. Each of the three Qoder C
 | 要求跳过评审 | "skip review", "不用评审", "跳过评审" | → 提醒评审是投资而非开销 |
 | 时间压力 | "来不及", "时间紧", "emergency" | → 提醒时间紧迫正是需要评审的时刻 |
 | 提前终止 | Round 1 后用户说 "可以了", "够了" | → BLOCK: 评审未达终止条件 |
-| 单专家自评 | 用户仅指定 1 个专家 | → BLOCK：必须执行 architecture、technical、feasibility 三个 Custom Agent |
+| 单专家自评 | 用户仅指定 1 个专家 | → BLOCK：Delphi 必须执行 architecture、technical、feasibility 三位专家 |
 | 无文档输入 | 仅触发词，无设计/代码内容 | → `[DelphiReview:BLOCKED]` |
 
 ---
@@ -532,5 +638,6 @@ Every Delphi mode MUST use the full JSON schema below. Each of the three Qoder C
 | File | Content |
 |------|---------|
 | `@references/code-walkthrough.md` | Code-walkthrough mode specification |
+| `@references/requirements.md` | Requirements mode specification |
 | `@references/orchestrator-dispatch.md` | Orchestrator auto-dispatch rules (#218 subagent multi-round loop) |
 | `@references/round-templates.md` | Round templates (anonymous/exchange/final/fix report formats) |