# @boyingliu01/dsh-plugin-xp-gate 中文文档

规范地址：https://npmcn.com/package/%40boyingliu01/dsh-plugin-xp-gate/

版本：0\.35\.18
npm 元数据更新时间：2026-10-31T16:54:15.506Z
中文译文更新时间：2026-10-31T17:06:30.327Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40boyingliu01/dsh-plugin-xp-gate
原文对照：https://npmcn.com/package/%40boyingliu01/dsh-plugin-xp-gate/?lang=original
项目主页：https://github.com/boyingliu01/xp-gate#readme
源码仓库：https://github.com/boyingliu01/xp-gate

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：727 kB，127 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@deepseek-ai/cordis ^4\.0\.1，@deepseek-ai/dsh-llm \>=0\.2\.0-rc\.2 \<0\.3\.0-0，@deepseek-ai/dsh-shell \>=0\.2\.0-rc\.2 \<0\.3\.0-0，@deepseek-ai/dsh-skill \>=0\.2\.0-rc\.2 \<0\.3\.0-0，@deepseek-ai/dsh-tools \>=0\.2\.0-rc\.2 \<0\.3\.0-0，@deepseek-ai/schemastery ^3\.18\.5，@deepseek-ai/dsh-credentials \>=0\.2\.0-rc\.2 \<0\.3\.0-0
- 首次发布：2026-08-27T06:09:45.185Z
- 最新版本发布：2026-10-31T16:54:15.212Z
- 已发布版本数：59（近 12 个月 59 个）

## 中文简介

XP-Gate确定性质量门+ AI工作流技能作为DeepSeek Harness （DSH）原生插件：gate-check / gate-principles / gate-arch tools + 12 SKILL。医学技能

## 安装

```sh
npm install @boyingliu01/dsh-plugin-xp-gate
```

也可以使用：`pnpm add @boyingliu01/dsh-plugin-xp-gate`、`yarn add @boyingliu01/dsh-plugin-xp-gate`、`bun add @boyingliu01/dsh-plugin-xp-gate`

## README

# @boyingliu01/dsh-plugin-xp-gate

XP-Gate 确定性质量门禁 + AI 工作流技能，作为 **DeepSeek Harness (DSH)** 原生插件（bundle）。

> 关联 Issue: #393　设计文档: `docs/plans/2026-08-23-dsh-plugin-design.md` 集成评估: `docs/plans/2026-09-30-dsh-integration-assessment.md`

## Tools

| Tool | Purpose |
| --- | --- |
| `gate-check` | Run XP-Gate quality gates (`xp-gate check`) on a file or directory |
| `gate-principles` | Run the Clean Code/SOLID rules (`xp-gate principles`, Gate 4) |
| `gate-arch` | Run architecture validation (`xp-gate arch`, Gate 6) |
| `delphi-review` | **多模型交叉评审**：用 3 个不同模型独立评审同一份材料并迭代到共识（见下） |

## Install

```bash
dsh plugin --profile <name> add @boyingliu01/dsh-plugin-xp-gate
```

The `gate-*` tools require a global `xp-gate` CLI:

```bash
npm install -g @boyingliu01/xp-gate
```

When `xp-gate` is missing those tools degrade gracefully (tool-missing → SKIP-style message) rather than erroring.

## 跨平台：shell 方言层

DSH 在非 Windows 上使用 POSIX shell、在 Windows 上使用 **PowerShell executor** （`dsh-base` bundle 里 `bash-sandbox` 在 win32 被禁用、`pwsh-sandbox` 启用）。

插件最初硬编码 POSIX 命令串，导致三个工具在 Windows 上**全部解析失败**：

```
[stderr] ParserError:
   1 |  if command -v xp-gate >/dev/null 2>&1; then xp-gate principles 'D:\pr …
     |    ~
     | if语句中的'if'后缺少"(”。
[exit code: 1]
```

现已按平台生成对应方言（`src/dialect.ts`）：

| POSIX | PowerShell |
| --- | --- |
| `command -v X` | `Get-Command X -ErrorAction SilentlyContinue` |
| `printf '%s\n' '...'` | `Write-Output '...'` |
| `'\''`（单引号转义） | `''`（单引号内双写） |

实测（Windows + PowerShell executor）：`gate-check` exit 0、`gate-principles` exit 0（`Rules run: 15`）。

## 多模型交叉评审（`delphi-review`）

### 为什么需要它，而不是用 DSH 的 subagent

Delphi 方法的价值**完全建立在「评审者是不同模型」之上**。DSH 的 `subagent` 工具继承宿主 配置的**单一**模型，因此三个"专家"会是同一个模型的三个实例 —— 按 `delphi-review` skill 自身的规则必须 BLOCK。

所以本工具**直接调用外部 OpenAI 兼容网关**，每个席位绑定一个不同模型。

> 另一条路线是打开 DSH 的 `subagentModelSelection`（Web GUI → **Plugins**），让 subagent 也能选模型。两者并不冲突：那条路线让 DSH 原生 subagent 具备多模型能力，本工具则在 **不依赖宿主配置**的前提下保证不变量成立（包括 CI / 一次性会话）。

### 配置

复用项目既有的 `.delphi-config.json`（skill 与工具**同一份配置**）：

```jsonc
{
  "active_profile": "whalecloud",
  "profiles": {
    "whalecloud": {
      "providers": {
        "whalecloud": {
          "base_url": "https://<gateway>/gpt-proxy",
          "api_key": "${WHALECLOUD_API_KEY}"   // 支持 ${VAR} 与 {env:VAR} 两种写法
        }
      },
      "experts": {                              // 对象形式；key 即角色
        "architecture": { "provider": "whalecloud", "model": "g-glm-5.3-flash" },
        "technical":    { "provider": "whalecloud", "model": "g-qwen3.8-flash" },
        "feasibility":  { "provider": "whalecloud", "model": "g-deepseek-flash" }
      }
    }
  },
  "consensus": { "threshold_percent": 90, "max_review_rounds": 5 }
}
```

密钥**只从环境变量读取**，绝不写入配置文件。 `experts` 同时接受**对象形式**（key 为角色）与**数组形式**（explicit `role` 字段）。

### 强制的不变量（代码强制，非文档约定）

| 不变量 | 违反时 |
| --- | --- |
| 恰好 3 位专家 | `DelphiConfigError` |
| 3 个 `requested_model` 去空白后两两不同 | `DelphiConfigError` |
| 模型不得为未展开的 `${...}` 占位符 | `DelphiConfigError`（在网络调用**之前**） |
| 缺密钥 / 缺 provider / 专家跨网关 | `DelphiSetupError`，报出变量名而非回显配置 |
| 报告缺 `### VERDICT` 段 | 记为 `INVALID_NO_VERDICT`，**不计入共识**（绝不从散文里猜裁决） |
| 退出码 0 但内容为空 | 记为 ERROR（推理模型可能把预算全烧在隐藏 token 上） |
| 共识按**全体席位数**计算 | 一份畸形报告不能靠其余全票"凑"出共识 |

共识阈值为百分比：3 席时 ≥90% 意味着**必须 3/3 通过**。

### 轮次语义

-   **Round 1 匿名且并发**：各席位互不可见。
-   **Round 2+**：回传**汇总票型**（`architecture: APPROVED` …）与"已修改项"， 各席位据此修正或坚持立场。**个体报告始终匿名** —— 只共享计票，这是方法可信的前提。
-   达到阈值即停；否则到 `max_review_rounds`（默认 5）为止，并如实返回 `NO CONSENSUS`。

### 已知行为（实测）

用一段**故意有缺陷**的样例代码喂给三个模型，15 次调用（5 轮 × 3 模型）全部成功且 `resolved_model` 两两不同，三个模型**独立**指出同一个真实缺陷： `{ ok: true }` 是**无条件**返回的常量，"把退出码契约换成了一个常量，而不是真正的结果信号"。 机制**拒绝**给出共识，而不是盖章通过 —— 这正是它该有的行为。

## 配置界面（Plugins 页）

插件声明了 `dsh.client`（`platform: web`），在 Web GUI 里注册一个**行配置页**：

**侧边栏 Plugins → `@boyingliu01/dsh-plugin-xp-gate` → 组件 `tool-xp-gate` → 配置**

该页面可以编辑 Delphi 三席（角色 / 模型）、网关、密钥引用与共识参数；模型可从 **宿主已配置的 provider 目录**下拉选择，也可手填。

### 来源优先级

| 优先级 | 来源 | 说明 |
| --- | --- | --- |
| 1 | 本插件配置里的 `delphi` 段（本页写入） | 一旦保存了席位，评审就用它 |
| 2 | 项目根 `.delphi-config.json` | 席位为空时自动回落，老项目**无需改动** |

页面上如果 `seats` 为空，评审继续走 `.delphi-config.json`，所以**打开页面不会静默改变行为**。

### 宿主强制的不变量（不是表单装饰）

表单只是方便，**宿主是权威**。每次评审前 `seatsFromSettings` 重新校验：

-   恰好 3 席
-   3 个 model 去空白后两两不同
-   模型不得为空或未展开的 `${...}` 占位符
-   配了席位就必须有 `base_url`
-   `api_key` 必须是**凭据引用**（`${VAR}` / `{env:VAR}`）；写入明文 token 会被拒绝， 因为那会把密钥落到 profile 文件里

> 为什么不在表单里就拦死：DSH 的 settings 表单只能编辑 `.volatile()` 字段， 而 volatile 意味着**保存即热生效**。对"每次运行都花钱"的配置来说，前端校验不够， 所以校验放在宿主、在发出任何请求之前。

### 关于 `bash` 守卫

`delphiGuard` 用**只读工具白名单**判定：只有 `read` / `grep` / `glob` / `read_image` / XP-Gate 自己的报告类工具算只读，**其余一律视为可写**（包括 `bash`、`pwsh` 和将来新增的工具）。

早期版本用"已知写工具黑名单"（`write` / `edit` / `str_replace_editor`）， `bash` 一条命令就能改文件，等于这道 HARD-GATE 可绕过。白名单的代价是可能**误拦**新加的 只读工具——那会表现为"拦得太狠"，而不是"悄悄放行"。

## Skills

本包在 publish 时通过 `scripts/prepack.cjs` 捆绑仓库 `skills/`（当前 12 个）。

要让 DSH 直接看到**仓库版** skill（而非 `~/.agents/skills` 里指向 `~/.qoder/skills` 的 junction）， 运行仓库提供的准备脚本：

```powershell
pwsh -File plugins/dsh/setup-dsh.ps1           # 全部（skill 链接 + 编译 + 提示）
pwsh -File plugins/dsh/setup-dsh.ps1 -WhatIf   # 只预览
```

该脚本在 `$DSH_HOME/skills`（DSH 发现根 rank 400）为仓库每个 skill 建 junction，保持单一真源。

> DSH 只读 skill frontmatter 的 6 个字段：`name`、`description`、`whenToUse`、 `metadata`、`disable-model-invocation`、`user-invocable`。 本仓库 skill 里的 `allowed-tools` / `hooks` / `triggers` / `maturity` / `auto_continue` **会被静默忽略**（无害，但不生效）。`references/` 子目录可用 —— DSH 的 `skill` 工具返回 base directory，模型按需用 read 工具加载。

## 备选路线：启用 DSH 原生 subagent 模型选择

上面的 `delphi-review` 工具不依赖宿主配置即可保证不变量。若你希望 DSH **原生** `subagent` 工具也能指定模型（例如让 Agent Teams 的队友跑不同模型），需显式启用 （Web GUI → **Plugins** 页面）：

```
subagent model selection:
  enabled = true
  allowedModels = [
    { provider: 'whalecloud', model: 'g-glm-5.3-flash'  },
    { provider: 'whalecloud', model: 'g-qwen3.8-flash'  },
    { provider: 'whalecloud', model: 'g-deepseek-flash' }
  ]
```

启用后 `subagent` 工具会新增 `provider` / `model` / `reasoning_effort` 参数， 并注册 `list_subagent_models` 工具。

> 注意：`dsh-tool-subagent` 的 `modelSelectionSettings: true` **只是能力开关**； 实际策略来自宿主设置 `SubagentModelSelectionConfig`（`enabled` 默认 `false`， `allowedModels` 默认 `[]`）。两者都要满足才会生效。

## Build

```bash
npm install --ignore-scripts   # --ignore-scripts 绕过 esbuild postinstall（受限环境会 EBUSY）
npm run build                  # tsc -> lib/，并把 client/client.js 复制成 lib/client.js
npm run prepare-skills         # 从仓库 skills/ 复制
npm test                       # vitest
```

或在仓库根目录：

```bash
npm run build:dsh-plugin       # = node scripts/build-plugin.mjs --platform dsh
```

> `client/client.js` 是**手写**的浏览器 bundle，不走 tsc：它以 DSH 的客户端模块格式 (`window.__ModuleLoader__.load`) 编写，引用了浏览器全局，不是 TypeScript 模块。 `npm run build` 的第二步（`scripts/copy-client.cjs`）负责把它放进 `lib/`。

## 注意

-   `lib/` 与 `skills/` 是**构建产物**（已 gitignore），不提交；`client/client.js` 是**源文件**，要提交。
-   `scripts/prepack.cjs` 的 skill 列表为**动态发现**（读取仓库 `skills/`），不硬编码。
-   `plugins/dsh/package.json` 的 peerDeps 仍 pin `0.1.1-rc.2`，但实测运行在 `0.2.0-rc.2` 上 `defineTool` / `TOOL_ABORTED` / `HarnessError` 签名未变，无需改写。
-   **配置项只有在导出 `Config` 之后才会显示。** 0.31.4 及更早的构建没有导出 `Config`，所以 `dsh --profile <name> --dump-config-schema` 里该行落在 `unknownConfig`，Plugins 页也就没有可编辑的字段。安装 0.32.x 后这一项自愈。

## 常见问题

### @boyingliu01/dsh-plugin-xp-gate 是什么？

XP-Gate确定性质量门\+ AI工作流技能作为DeepSeek Harness （DSH）原生插件：gate-check / gate-principles / gate-arch tools \+ 12 SKILL。医学技能

### 如何安装 @boyingliu01/dsh-plugin-xp-gate？

在项目目录运行 npm install @boyingliu01/dsh-plugin-xp-gate，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@deepseek-ai/cordis（^4\.0\.1）、@deepseek-ai/dsh-llm（\>=0\.2\.0-rc\.2 \<0\.3\.0-0）、@deepseek-ai/dsh-shell（\>=0\.2\.0-rc\.2 \<0\.3\.0-0）、@deepseek-ai/dsh-skill（\>=0\.2\.0-rc\.2 \<0\.3\.0-0）、@deepseek-ai/dsh-tools（\>=0\.2\.0-rc\.2 \<0\.3\.0-0）、@deepseek-ai/schemastery（^3\.18\.5）、@deepseek-ai/dsh-credentials（\>=0\.2\.0-rc\.2 \<0\.3\.0-0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @boyingliu01/dsh-plugin-xp-gate 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @boyingliu01/dsh-plugin-xp-gate 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @boyingliu01/dsh-plugin-xp-gate 可以商用吗？

@boyingliu01/dsh-plugin-xp-gate 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @boyingliu01/dsh-plugin-xp-gate 还在维护吗？

最新版本 0\.35\.18 发布于 2026/11/01（2 天前）；至今共发布 59 个版本，其中过去 12 个月发布了 59 个；首次发布于 2026/08/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。