@boyingliu01/xp-gate 0.19.3 → 0.20.0

package/scripts/delphi-external-review.cjs

@@ -18,9 +18,16 @@ function checkNodeVersion() {
 // ── Argument parsing ───────────────────────────────────────────────────
 const VALID_EXPERTS = ['architecture', 'technical', 'feasibility'];
 const VALID_MODES = ['design', 'code-walkthrough', 'requirements'];
+const DEFAULT_TIMEOUT_MS = 30000;
+
+// Shared by CLI --timeout-ms and provider timeout_ms validation.
+function isValidTimeoutMs(value) {
+  return Number.isInteger(value) && value >= 1000 && value <= 600000;
+}
 
 function parseArgs(argv) {
   const args = {};
+  let timeoutMsRaw;
   for (let i = 0; i < argv.length; i++) {
     switch (argv[i]) {
       case '--expert': args.expert = argv[++i]; break;
@@ -31,6 +38,7 @@ function parseArgs(argv) {
       case '--mode': args.mode = argv[++i]; break;
       case '--profile': args.profile = argv[++i]; break;
       case '--other-experts-file': args.otherExpertsFile = argv[++i]; break;
+      case '--timeout-ms': timeoutMsRaw = argv[++i]; break;
       case '--fallback-local': args.fallbackLocal = true; break;
       default: break;
     }
@@ -60,6 +68,16 @@ function parseArgs(argv) {
     process.exit(1);
   }
 
+  // Validate --timeout-ms: integer within [1000, 600000]
+  if (timeoutMsRaw !== undefined) {
+    const parsed = /^\d+$/.test(timeoutMsRaw) ? Number(timeoutMsRaw) : NaN;
+    if (!isValidTimeoutMs(parsed)) {
+      console.error('[delphi-review] ERROR: --timeout-ms must be an integer between 1000 and 600000.');
+      process.exit(1);
+    }
+    args.timeoutMs = parsed;
+  }
+
   // Defaults
   if (!args.mode) args.mode = 'design';
   if (!VALID_MODES.includes(args.mode)) {
@@ -71,6 +89,28 @@ function parseArgs(argv) {
 }
 
 // ── Config reading ─────────────────────────────────────────────────────
+// Provider fields used to be checked only inside the per-expert loop, so a
+// malformed provider nobody currently points an expert at survived silently and
+// only surfaced at runtime (a bad timeout_ms fell back to the default). The
+// whole profile is checked here instead, at the system boundary, naming the
+// provider so the fix is obvious (#429).
+function validateProviders(providers, profileName) {
+  for (const [name, provider] of Object.entries(providers)) {
+    const providerPath = `profiles.${profileName}.providers.${name}`;
+    const fail = (detail) => {
+      console.error(`[delphi-review] ERROR: ${providerPath} ${detail}`);
+      process.exit(1);
+    };
+
+    if (!isPlainObject(provider)) fail('must be an object.');
+    if (typeof provider.base_url !== 'string' || provider.base_url.trim() === '') fail('must define a non-empty base_url.');
+    if (typeof provider.api_key !== 'string' || provider.api_key.trim() === '') fail('must define a non-empty api_key.');
+    if (provider.timeout_ms !== undefined && !isValidTimeoutMs(provider.timeout_ms)) {
+      fail('timeout_ms must be an integer between 1000 and 600000.');
+    }
+  }
+}
+
 function readConfig(configPath, profileOverride) {
   if (!fs.existsSync(configPath)) {
     console.error(`[delphi-review] ERROR: Config file not found: ${configPath}`);
@@ -97,6 +137,7 @@ function readConfig(configPath, profileOverride) {
 
   // Resolve ${ENV_VAR} references in provider api_key fields
   const providers = profile.providers || {};
+  validateProviders(providers, profileName);
   for (const [name, prov] of Object.entries(providers)) {
     if (prov.api_key && prov.api_key.startsWith('${') && prov.api_key.endsWith('}')) {
       const envName = prov.api_key.slice(2, -1);
@@ -104,7 +145,11 @@ function readConfig(configPath, profileOverride) {
       if (envVal) {
         prov.api_key = envVal;
       } else {
-        console.error(`[delphi-review] WARNING: Environment variable ${envName} not set (provider: ${name}). API calls will fail.`);
+        // A missing variable used to be a WARNING, after which the runner sent the
+        // literal `Bearer ${NAME}` and reported the 401 as "check API key" — the
+        // diagnosis pointed at a wrong key while the real cause was the shell.
+        console.error(`[delphi-review] ERROR: Environment variable ${envName} is not set (profiles.${profileName}.providers.${name}.api_key). Export it or point that provider at a literal key.`);
+        process.exit(1);
       }
     }
   }
@@ -201,6 +246,12 @@ function validateDistinctModels(experts, providers, consensus = {}) {
     if (typeof provider.api_key !== 'string' || provider.api_key.trim() === '') {
       return { valid: false, reason: `Expert ${role} provider must define a non-empty api_key.` };
     }
+    if (provider.timeout_ms !== undefined && !isValidTimeoutMs(provider.timeout_ms)) {
+      return {
+        valid: false,
+        reason: `Expert ${role} provider ${expert.provider} timeout_ms must be an integer between 1000 and 600000.`,
+      };
+    }
   }
 
   if (consensus.cross_provider_required === true) {
@@ -257,7 +308,7 @@ const SYSTEM_PROMPTS = {
 4) 架构演进性 — 是否为未来扩展留有空间
 5) 技术选型合理性 — 技术栈选择是否有充分依据
 
-输出要求：返回结构化 JSON，包含 verdict (APPROVED/REQUEST_CHANGES/REJECTED)、confidence (1-10)、critical_issues、major_concerns、minor_concerns、summary。`,
+输出要求：返回结构化 JSON，包含 verdict (APPROVED/REQUEST_CHANGES/REJECTED)、confidence (1-10，整数，10 为最高)、summary (字符串)。critical_issues、major_concerns、minor_concerns 必须是字符串数组（string[]），每项是一句自包含的完整描述（可加 "CI-01: " 前缀，但整体必须是字符串，不是对象）。不要把问题写成 {id, title, description} 对象。`,
 
   technical: `你是技术实现评审专家（Delphi Method - Technical Expert）。
 
@@ -268,7 +319,7 @@ const SYSTEM_PROMPTS = {
 4) 性能影响 — 是否有性能瓶颈或资源泄漏风险
 5) 可测试性 — 代码是否易于编写单元测试
 
-输出要求：返回结构化 JSON，包含 verdict (APPROVED/REQUEST_CHANGES/REJECTED)、confidence (1-10)、critical_issues、major_concerns、minor_concerns、summary。`,
+输出要求：返回结构化 JSON，包含 verdict (APPROVED/REQUEST_CHANGES/REJECTED)、confidence (1-10，整数，10 为最高)、summary (字符串)。critical_issues、major_concerns、minor_concerns 必须是字符串数组（string[]），每项是一句自包含的完整描述（可加 "MC-01: " 前缀，但整体必须是字符串，不是对象）。不要把问题写成 {id, title, description} 对象。`,
 
   feasibility: `你是可行性分析专家（Delphi Method - Feasibility Expert）。
 
@@ -279,7 +330,7 @@ const SYSTEM_PROMPTS = {
 4) 替代方案 — 是否有更简单或更可靠的替代方案
 5) 回滚策略 — 如果实施失败，是否有退路
 
-输出要求：返回结构化 JSON，包含 verdict (APPROVED/REQUEST_CHANGES/REJECTED)、confidence (1-10)、critical_issues、major_concerns、minor_concerns、summary。`,
+输出要求：返回结构化 JSON，包含 verdict (APPROVED/REQUEST_CHANGES/REJECTED)、confidence (1-10，整数，10 为最高)、summary (字符串)。critical_issues、major_concerns、minor_concerns 必须是字符串数组（string[]），每项是一句自包含的完整描述（可加 "FC-01: " 前缀，但整体必须是字符串，不是对象）。不要把问题写成 {id, title, description} 对象。`,
 };
 
 const MODE_FOCUS_PROMPTS = {
@@ -316,6 +367,60 @@ function resolveInputContent(args) {
   return args.input || '';
 }
 
+// ── Timeout resolution ─────────────────────────────────────────────────
+// CLI --timeout-ms > provider timeout_ms > default (30000, unchanged behavior).
+function resolveTimeoutMs(args, providerConfig) {
+  if (args && isValidTimeoutMs(args.timeoutMs)) return args.timeoutMs;
+  if (providerConfig && isValidTimeoutMs(providerConfig.timeout_ms)) return providerConfig.timeout_ms;
+  return DEFAULT_TIMEOUT_MS;
+}
+
+// ── Prompt budget ──────────────────────────────────────────────────────
+// Measured on the whalecloud gateway during the #457 walkthrough: a 40 KB prompt
+// answered normally, a 50 KB one killed the seat with no usable error, and a
+// dead expert seat blocks the whole review. The ceiling is therefore checked
+// before the request is made, where the message can say what to narrow.
+const DEFAULT_PROMPT_BUDGET_BYTES = 40000;
+
+// A seat-level override (`max_prompt_bytes` on the expert entry) exists because
+// the ceiling is a property of the model behind the seat, not of the runner.
+// Values that cannot be honoured fall back to the default rather than disabling
+// the guard -- `max_prompt_bytes: 0` reads as "no limit" and is not.
+function resolvePromptBudgetBytes(expertConfig) {
+  const configured = expertConfig && expertConfig.max_prompt_bytes;
+  if (typeof configured === 'number' && Number.isFinite(configured) && configured > 0) {
+    return Math.trunc(configured);
+  }
+  if (configured !== undefined) {
+    // Silently falling back is how a raised ceiling looks like a still-broken
+    // guard: the operator edits the config, the run still refuses, and nothing
+    // says the value never took effect.
+    console.error(
+      `[delphi-review] WARNING: max_prompt_bytes=${JSON.stringify(configured)} cannot be honoured ` +
+      `(needs a finite number > 0); using the ${DEFAULT_PROMPT_BUDGET_BYTES} byte default instead.`
+    );
+  }
+  return DEFAULT_PROMPT_BUDGET_BYTES;
+}
+
+// Bytes, never `String.length`: review content is Chinese prose, and a code-unit
+// count understates what the gateway actually receives by up to 3x.
+function checkPromptBudget({ systemPrompt, userPrompt, maxBytes }) {
+  const bytes = Buffer.byteLength(String(systemPrompt ?? ''), 'utf8')
+    + Buffer.byteLength(String(userPrompt ?? ''), 'utf8');
+  return { ok: bytes <= maxBytes, bytes, maxBytes };
+}
+
+function describePromptBudgetFailure({ bytes, maxBytes, expert }) {
+  return (
+    `Prompt for expert "${expert}" is ${bytes} bytes, over the ${maxBytes} byte budget. ` +
+    'The gateway drops oversized requests without a diagnosable error, so this run ' +
+    'refuses to send it. Narrow the review range (fewer commits or files, or exclude ' +
+    'vendored/lockfile content), or raise the seat\'s `max_prompt_bytes` in ' +
+    '.delphi-config.json if this model is known to accept larger requests.'
+  );
+}
+
 // ── API call ───────────────────────────────────────────────────────────
 async function callModelAPI(providerConfig, model, systemPrompt, userPrompt, options = {}) {
   const url = `${providerConfig.base_url.replace(/\/$/, '')}/chat/completions`;
@@ -330,7 +435,9 @@ async function callModelAPI(providerConfig, model, systemPrompt, userPrompt, opt
     response_format: { type: 'json_object' },
   };
 
-  const timeoutMs = options.timeoutMs ?? 30000;
+  // Same constant as the runner default: a second literal here silently
+  // diverges whenever the default is retuned (#429).
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), timeoutMs);
   let responseReceived = false;
@@ -352,6 +459,29 @@ async function callModelAPI(providerConfig, model, systemPrompt, userPrompt, opt
     }
 
     if (response.status === 429) {
+      // A 429 is not always a transient rate limit. WhaleCloud returns 429 with
+      // `type: "budget_exceeded"` in two distinct non-retryable cases, which a
+      // blind retry cannot clear and would otherwise burn two round-trips before
+      // failing:
+      //   - `error.param === "category_quota"`: the account has no ECONOMY/STANDARD
+      //     quota configured for the model ("需要专项额度...尚未配置") — needs an
+      //     admin to add it.
+      //   - `error.param === "cost_quota"`: the account's daily spending cap is
+      //     exhausted ("今日额度已耗尽...限额: 100.00元") — resets the next day.
+      // Surface which kind it is so the caller knows whether to wait or to request
+      // an admin change, rather than treating both as a generic rate limit.
+      let quotaType = '';
+      try {
+        const body = await response.json();
+        if (body && body.error && body.error.type === 'budget_exceeded') {
+          quotaType = body.error.param === 'cost_quota' ? 'daily budget exhausted' : 'quota not configured';
+        }
+      } catch {
+        // body is not JSON; fall through to the generic rate-limit handling
+      }
+      if (quotaType) {
+        return { error: true, retryable: false, message: `WhaleCloud budget_exceeded: ${quotaType} for this model.` };
+      }
       return { error: true, retryable: true, message: 'Rate limit exceeded (429).' };
     }
 
@@ -374,18 +504,33 @@ async function callModelAPI(providerConfig, model, systemPrompt, userPrompt, opt
       return { error: true, message: 'Invalid response from model.' };
     }
 
+    // The gateway must echo which model actually served the request. Writing
+    // `null` here used to be tolerated downstream, which let a run that never
+    // resolved a model count as a successful expert call (#423). Fail at the
+    // source instead, so the evidence never records an unverifiable expert.
+    const resolvedModel = typeof data.model === 'string' ? data.model.trim() : '';
+    if (resolvedModel === '') {
+      return {
+        error: true,
+        message: 'Gateway response did not include a resolved model id; cannot prove which model ran.',
+      };
+    }
+
     return {
       success: true,
       content: content.trim(),
-      resolved_model: typeof data.model === 'string' && data.model.trim() !== '' ? data.model.trim() : null,
+      resolved_model: resolvedModel,
     };
   } catch (err) {
     if (err instanceof Error && err.name === 'AbortError') {
-      return { error: true, retryable: true, message: `Request timed out (${timeoutMs}ms).` };
+      return { error: true, retryable: true, message: `Request timed out (${timeoutMs}ms). Raise --timeout-ms or the provider's timeout_ms.` };
     }
     if (responseReceived) {
       return { error: true, message: 'Invalid response from model.' };
     }
+    // Deliberately do NOT surface the underlying cause here. Provider errors can
+    // carry mutable metadata (tokens, keys, hostnames) that must not leak into the
+    // evidence file; the test suite asserts this redaction. Keep the generic form.
     return { error: true, message: 'Network error.' };
   } finally {
     clearTimeout(timeout);
@@ -432,6 +577,11 @@ function buildReviewOutput(verdict, args, provenance) {
     model_used: `${provenance.provider}/${provenance.requested_model}`,
     requested_model: provenance.requested_model,
     resolved_model: provenance.resolved_model,
+    // Provenance marker required by Gate MW (#423). This script talks to an
+    // external gateway, so every record it emits is `external`. The field is
+    // explicit rather than inferred: the validator rejects a missing value
+    // instead of defaulting it, which is what makes forgery costly.
+    channel: provenance.channel,
     round: args.round,
     mode: args.mode,
   };
@@ -442,10 +592,10 @@ function buildReviewOutput(verdict, args, provenance) {
 }
 
 // ── Retry logic ────────────────────────────────────────────────────────
-async function callWithRetry(providerConfig, model, systemPrompt, userPrompt, maxRetries = 2) {
+async function callWithRetry(providerConfig, model, systemPrompt, userPrompt, maxRetries = 2, timeoutMs = DEFAULT_TIMEOUT_MS) {
   let lastResult;
   for (let attempt = 0; attempt <= maxRetries; attempt++) {
-    const result = await callModelAPI(providerConfig, model, systemPrompt, userPrompt);
+    const result = await callModelAPI(providerConfig, model, systemPrompt, userPrompt, { timeoutMs });
 
     if (result.success) return result;
     if (!result.retryable) return result;
@@ -507,8 +657,32 @@ async function main() {
   const systemPrompt = buildSystemPrompt(args.expert, args.mode);
   const userPrompt = buildUserPrompt(reviewContent, otherExpertsContent, args.round);
 
+  // Refuse before the request, not after the gateway kills it.
+  const budget = checkPromptBudget({
+    systemPrompt,
+    userPrompt,
+    maxBytes: resolvePromptBudgetBytes(expertConfig),
+  });
+  if (!budget.ok) {
+    const message = describePromptBudgetFailure({ ...budget, expert: args.expert });
+    console.error(`[delphi-review] ERROR: ${message}`);
+    // Same stdout contract as an API failure: an orchestrator parsing this stream
+    // must be able to tell "we never asked" from "the model answered wrongly".
+    console.log(JSON.stringify({
+      error: true,
+      error_type: 'prompt_budget_exceeded',
+      expert_role: args.expert,
+      message,
+      bytes: budget.bytes,
+      max_bytes: budget.maxBytes,
+      retryable: false,
+    }));
+    process.exit(1);
+  }
+
   // Call API with retry
-  const result = await callWithRetry(provider, expertConfig.model, systemPrompt, userPrompt);
+  const timeoutMs = resolveTimeoutMs(args, provider);
+  const result = await callWithRetry(provider, expertConfig.model, systemPrompt, userPrompt, 2, timeoutMs);
 
   if (result.error) {
     const errorOutput = {
@@ -533,6 +707,9 @@ async function main() {
     provider: expertConfig.provider,
     requested_model: expertConfig.model,
     resolved_model: result.resolved_model,
+    // This runner only ever reaches an external provider; local/offline
+    // fallbacks are recorded by a different path (#423).
+    channel: 'external',
   });
 
   console.log(JSON.stringify(output, null, 2));
@@ -549,6 +726,12 @@ if (require.main !== module) {
     buildSystemPrompt,
     buildUserPrompt,
     resolveInputContent,
+    resolveTimeoutMs,
+    DEFAULT_TIMEOUT_MS,
+    resolvePromptBudgetBytes,
+    checkPromptBudget,
+    describePromptBudgetFailure,
+    DEFAULT_PROMPT_BUDGET_BYTES,
     checkNodeVersion,
     callModelAPI,
     callWithRetry,

package/scripts/sync-package-content.js

@@ -188,7 +188,7 @@ function syncHooks() {
     fs.copyFileSync(adapterCommonSrc, path.join(PKG_ROOT, 'adapter-common.sh'));
   }
 
-  const HOOK_FILES = ['pre-commit', 'pre-push', 'adapter-common.sh'];
+  const HOOK_FILES = ['pre-commit', 'pre-push', 'post-merge', 'adapter-common.sh'];
   let copied = 0;
 
   for (const name of HOOK_FILES) {
@@ -477,8 +477,11 @@ function main() {
   // tui-plugin removed in v0.13.0 — validation skipped.
 }
 
-if (require.main !== module) {
+if (require.main === module) {
+  main();
+} else {
+  // Requiring this script must not mutate the work tree: a test that only wants
+  // checkDocsDrift/checkAdapterDrift used to trigger a full mirror sync at
+  // require-time, which vitest-worktree-guard rightly reported as pollution.
   module.exports = { checkDocsDrift, checkAdapterDrift };
 }
-
-main();

package/skills/clipboard-vision/__tests__/clipboard-vision-distribution.test.cjs

@@ -19,7 +19,6 @@ describe('clipboard-vision distribution', () => {
     'scripts/build-plugin.mjs',
     'scripts/build-plugin.sh',
     'scripts/test-plugins.mjs',
-    'scripts/test-plugins.sh',
     'src/npm-package/scripts/sync-package-content.js',
     'plugins/opencode/scripts/prepack.cjs',
     'src/npm-package/plugins/opencode/scripts/prepack.cjs',

package/skills/delphi-review/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/DELPHI-REVIEW KNOWLEDGE BASE
 
-**Generated:** 2026-09-24
-**Commit:** 467174d
-**Branch:** main
-**Version:** 0.19.3.0
+**Generated:** 2026-10-07
+**Commit:** ff55f35b
+**Branch:** fix/batch-defects-20261007
+**Version:** 0.20.0.0
 
 ## OVERVIEW
 Delphi Consensus Review — multi-round anonymous expert review (≥90% threshold, exactly 3 experts with distinct executable model IDs). Supports design, requirements, and code-walkthrough modes.

package/skills/delphi-review/SKILL.md

@@ -249,7 +249,7 @@ tools_denied:
 
 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** — 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. 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.
+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.
@@ -327,27 +327,111 @@ Each round MUST output a structured round marker:
 - ✅ 三个角色可以共享一个 provider 和 token 计划
 - ❌ `provider: local` 的特殊 fallback 不能计为一次成功执行
 
-#### Qoder 平台（推荐 — Custom Agent 模式）
+#### Qoder 平台（Custom Agent 模式 — 只能做到同模型三角色）
 
-Qoder 环境下使用 **Custom Agent** 机制，每个专家是一个独立的 custom agent，配置不同的 Qoder 内置模型：
+Qoder 的内置模型**没有本地推理端点**：推理请求由 Qoder 客户端经服务端代理发出，凭证是一次性 job token。所以不能照搬 OpenCode 的 `base_url + api_key` 直连方式；Qoder 侧内置模型的唯一入口是 **Custom Agent** —— 每个专家一个独立 agent 文件，frontmatter 用 `model` 字段声明模型。
 
-| 专家 | 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× |
+**契约结论（先说结论）**：这条路径**不满足**"三个不同可执行模型 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` 绑定。
 
-**执行方式**：通过 Agent tool 并行启动 3 个 subagent（type=GeneralPurpose），每个 agent 使用自己配置的模型独立评审，主 orchestrator 收集结果后计算共识。
+因此 Qoder 原生模式只能作为**同模型、三角色（persona）的自查**，其共识比例不能当作多模型交叉验证的证据，也不应用作 Gate MW 的三模型凭据。需要契约合规的 Delphi 时，按上面的外部 provider 方式配置 `.delphi-config.json`（Qoder 与 OpenCode 同用，条件是模型确有可调端点）。
 
-**优势**：无需外部 API key，直接使用 Qoder Credits，模型由平台统一管理。
+| 角色 | 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` | 会话模型 |
+
+**安装位置**（`xp-gate init` 自动部署，已存在的文件不覆盖）：
+- 项目级：`<project>/.qoder/agents/`（`xp-gate init`）
+- 用户级：`~/.qoder/agents/`（`xp-gate init --global`）
+
+**model 字段格式**：仍须写成 `"[DisplayName](modelId)"`。裸名字或已下线 ID 不会报错，会被平台静默忽略。`xp-gate init` 会审计已部署的 `delphi-*.md`，格式非法或 modelId 与本版本模板不一致时点名文件并给出"删除 → 重跑 `init` → 重启会话"提示；因为部署语义是"已存在不覆盖"，从 #417 之前的版本升级必须手工删旧文件再重跑 `init`。注意：修好绑定也只是让角色声明规范，并不改变上表的执行模型结论。
+
+**执行方式**：用 Agent tool 并行派发 3 个 subagent，`subagent_type` 分别取 `delphi-architecture`、`delphi-technical`、`delphi-feasibility`。**新建或修改 agent 文件后必须重开会话**——注册表只在会话启动时加载，否则报 `Unknown agent type`。
+
+**客观验证（不要采信专家自述）**：`~/.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 的兼容 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。
+
 ### 共识阈值
 
 | 阈值 | 说明 |
@@ -454,9 +538,9 @@ Every Delphi mode MUST use the full JSON schema below. Architecture, technical,
   "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" },
-    { "role": "technical", "verdict": "APPROVED", "confidence": 8, "result_type": "delphi_expert_result", "requested_model": "provider/model-b" },
-    { "role": "feasibility", "verdict": "APPROVED", "confidence": 8, "result_type": "delphi_expert_result", "requested_model": "provider/model-c" }
+    { "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": [],

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

@@ -255,9 +255,15 @@ pre-push hook
 |------|------|------|
 | 单次走查成本 | ~$0.03 | 正常执行 |
 | 变更规模 | 无硬性文件数或行数上限 | 大型变更必须完整评审或由用户选择拆分 |
+| 单席位 prompt 体积 | 默认 40000 字节（`max_prompt_bytes` 可按席位覆盖） | runner 发送前拒绝，报错里给出处置办法 |
 
 大型变更没有自动跳过或绕过路径。用户可以选择完整评审，或在评审前主动拆分变更；每个变更仍须通过完整的走查和证据验证。
 
+**prompt 预算是硬约束，不是建议**：实测 `g-glm-5.3-flash` 在 ~40KB 正常应答（225s）、~50KB 直接崩溃
+（305s，`0xC0000409` + libuv `UV_HANDLE_CLOSING`，表现为 "Network error."）——一个席位崩溃就会让整个共识无法完成。
+构造输入时按重要性排序、给每个席位独立预算、并在报告里显式列出因体积省略的文件；
+截断到「核心 hunk 看不见」比超限更糟：席位会花整轮报告「无法审计」，而这是评审者的真实缺陷而非代码缺陷。
+
 ---
 
 ## Agent 可用性检查 (MANDATORY)
@@ -356,9 +362,9 @@ IF 任何检查失败:
   "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" }
+    { "id": "Expert A", "role": "architecture", "verdict": "APPROVED", "confidence": 9, "result_type": "delphi_expert_result", "requested_model": "provider/model-a", "resolved_model": "provider/model-a", "channel": "external" },
+    { "id": "Expert B", "role": "technical", "verdict": "APPROVED", "confidence": 8, "result_type": "delphi_expert_result", "requested_model": "provider/model-b", "resolved_model": "provider/model-b", "channel": "external" },
+    { "id": "Expert C", "role": "feasibility", "verdict": "APPROVED", "confidence": 8, "result_type": "delphi_expert_result", "requested_model": "provider/model-c", "resolved_model": "provider/model-c", "channel": "external" }
   ],
   "issues": [],
   "consensus_ratio": 1.0,
@@ -399,6 +405,33 @@ Hook 验证以下条件（全部满足才允许 push）：
 5. timestamp 未过期
 6. expires 必须是 timestamp 之后恰好 1 小时
 
+### experts[] 必填字段与 #423 的迁移说明
+
+`validate-code-walkthrough.cjs` 对每个 expert 对象强制要求：
+
+| 字段 | 约束 |
+|------|------|
+| `result_type` | 必须等于 `"delphi_expert_result"` |
+| `role` | 非空，三个席位 role 互异 |
+| `requested_model` | 非空；比较前只做 trim，**区分大小写**（规范原文是 "distinct trimmed requested model IDs"，见 AGENTS.md） |
+| `resolved_model` | 非空；比较前 trim + 转小写，三者互异 |
+| `channel` | 必须严格属于 `["external", "local"]`；`provider: local` 的 fallback 记录不能计为成功执行 |
+
+缺字段或取值不在白名单 → Gate MW **FAIL**（不是 SKIP）。
+
+**升级后旧证据怎么处置**：唯一正确做法是在当前 HEAD 重跑一次评审、由 runner 重新生成证据文件。
+不要手工给老文件补 `channel` —— 那等于伪造执行证据，而 `channel` 存在的目的正是让证据可追溯到一次真实调用。
+证据本来就与 commit 绑定（`commit` 必须等于 HEAD，有效期 1 小时），跨 commit 复用从来不是受支持的路径。
+
+**回滚语义**：validator 与证据生产者（`scripts/delphi-external-review.cjs`）必须成对回滚。
+
+- 旧 validator 读新证据：安全，多余字段被忽略。
+- 新 validator 读旧证据：必然 FAIL（缺 `channel`）。这是设计意图——宁可在发布关口停下，
+  也不放行一份无法证明模型来源的证据；把「三个不同模型真的跑过」降级为可选项，等于让门禁只剩形式。
+- 临时降级开关：**没有**。既没有 `XP_GATE_SKIP_MW` 之类的环境变量，也不允许 `--no-verify`
+  （见 `githooks/QUALITY-GATES-CODE-OF-CONDUCT.md`）。如果评审确实无法完成，处理方式是缩小
+  `--range` 或按席位调整 prompt 预算重跑，而不是放行。
+
 ---
 
 ## 与现有系统集成

package/skills/delphi-review/references/requirements.md

@@ -190,9 +190,9 @@ Round 2: delphi-review --mode requirements（带 Round 1 gaps 上下文）
   "context_file_used": null,
   "round": 1,
    "expert_verdicts": [
-     { "role": "architecture", "verdict": "APPROVED", "confidence": 9, "result_type": "delphi_expert_result", "requested_model": "bailian-tp/qwen-plus" },
-     { "role": "technical", "verdict": "APPROVED", "confidence": 8, "result_type": "delphi_expert_result", "requested_model": "bailian-tp/deepseek-v3" },
-     { "role": "feasibility", "verdict": "APPROVED", "confidence": 8, "result_type": "delphi_expert_result", "requested_model": "bailian-tp/glm-4.5" }
+     { "role": "architecture", "verdict": "APPROVED", "confidence": 9, "result_type": "delphi_expert_result", "requested_model": "bailian-tp/qwen-plus", "resolved_model": "qwen-plus", "channel": "external" },
+     { "role": "technical", "verdict": "APPROVED", "confidence": 8, "result_type": "delphi_expert_result", "requested_model": "bailian-tp/deepseek-v3", "resolved_model": "deepseek-v3", "channel": "external" },
+     { "role": "feasibility", "verdict": "APPROVED", "confidence": 8, "result_type": "delphi_expert_result", "requested_model": "bailian-tp/glm-4.5", "resolved_model": "glm-4.5", "channel": "external" }
    ],
   "requirements_statement": "实现用户注册流程，支持邮箱验证和密码重置",
   "gaps_found": [],
@@ -214,9 +214,9 @@ Round 2: delphi-review --mode requirements（带 Round 1 gaps 上下文）
   "context_file_used": null,
   "round": 1,
   "expert_verdicts": [
-    { "role": "architecture", "verdict": "APPROVED", "confidence": 8, "result_type": "delphi_expert_result", "requested_model": "provider/model-a" },
-    { "role": "technical", "verdict": "GAPS_FOUND", "confidence": 7, "result_type": "delphi_expert_result", "requested_model": "provider/model-b" },
-    { "role": "feasibility", "verdict": "APPROVED", "confidence": 8, "result_type": "delphi_expert_result", "requested_model": "provider/model-c" }
+    { "role": "architecture", "verdict": "APPROVED", "confidence": 8, "result_type": "delphi_expert_result", "requested_model": "provider/model-a", "resolved_model": "provider/model-a", "channel": "external" },
+    { "role": "technical", "verdict": "GAPS_FOUND", "confidence": 7, "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": "实现用户注册流程，支持邮箱验证和密码重置",
   "gaps_found": [