dsh-agent-router

dsh-agent-router

专业的事情，交给专业的 agent。

DeepSeek Harness（DSH）多模型路由插件：为任意 DSH 主 agent 挂载专业 agent 目录——Agent 预设与 subagent 默认模型、专业 Agent 配置与自动路由、ChatGPT 订阅登录 + 主模型调用三大主要功能，按任务自动路由到带独立模型的视觉、图片生成、翻译、语音、子代理等专业 agent，扩展主 agent 的能力边界。

项目目标

专业的事情交给专业的 agent：以三大主要功能为主轴，扩展任意 DSH 主 agent 的能力边界——Agent 预设默认模型（按 DSH 预设粒度配置主 Agent 与 subagent 的默认模型）、专业 Agent 配置（自定义任意类型 agent 并配置对应的文本模型/多模态模型，按能力标签自动路由）、ChatGPT 订阅接入（订阅登录，并支持主模型调用与订阅生图）——图片识别与生成、语音识别与转写、视频脚本与字幕、翻译、复杂子任务委派等任意专业能力，一套工具完成多模型协同。

特性

• 🎯 Agent 预设默认模型：按 DSH 预设粒度配置主 Agent 与 subagent 的默认模型——新会话/切换预设即时跟随显示（打开即显示，无需先发消息）；会话内手动选择永远优先（用户主权）；subagent 未配置跟随主 Agent 当前模型（含会话内手动切换，不固化为预设配置值）；未配置的预设完全遵循 DSH 现行规则（零行为变化）
• 🧭 专业 Agent 配置（核心）：五种执行通路（chat 远端模型 / agent 完整子代理 / cli 无头 CLI 子代理 / image 图片生成 / speech 语音转写）+ 自定义能力标签自动路由；每个 agent 独立服务商与模型，未配置自动复用主 agent 模型
• 🔑 ChatGPT 订阅登录 + 主模型调用：ChatGPT 订阅经官方 Codex OAuth 通路一键授权登录；v0.4.1 起订阅模型可直接作为主模型——经宿主官方 openai-codex 路由，模型选择器直接可选 gpt-5.6 系列订阅模型组，OAuth token 由插件自动注入刷新（订阅卡可随时切回「插件内置」通路）；订阅生图——draw 类 agent 绑定订阅账号即可出图（gpt-image 系模型透传）
• 🖼 多模态任务路由：图片识别（OCR、截图、图表）、图片生成、语音转写；files 参数按能力分发——图片内联注入、文本内联、任意文件交给 agent / cli 类型子代理读取
• 💬 对话框图片能力：启用视觉类专业 agent（能力标签含 image）后，输入框出现「添加图片」按钮——附件图片进入原生草稿栏随消息原生发送，会话日志保留原件（界面原生显示）；插件在 system 层注入路由提示，主 agent 按需调用 route_agent（includeImages 把最近消息的图片转发给视觉 agent，自动附带主会话最近上下文，截图真正成为对话上下文的一部分）；生成图片经插件同源画布直达显示（v0.4.1 起：/router-assets/ 内容寻址同源路由，不再依赖宿主附件通道；route_agent 工具卡默认折叠、输入区 🖼 按钮汇总会话产物；纯插件机制：带图轮始终由主模型应答，纯文本主模型全程不接触图片字节）
• 🤖 无头 CLI 子代理（Codex / Claude / Gemini）：把 codex / claude / gemini 等外部 agent 工具作为子代理接入——无头模式（codex exec --json / claude -p / gemini -p）在工作区内自动执行多步任务，图片与文件按工作区路径注入；CLI 使用自身登录态（各自终端登录一次），插件零 OAuth 对接
• 💳 多模态账号与账号池：任意服务商 API Key 配置式添加（官方/中转/本地部署同一条路径，无预设无登录）；账号池按健康/用量/轮询策略自动选号与失败切换（官方 API 不提供 OAuth——v0.3.2 起已移除不可用的「OAuth 官方登录」入口）
• 📊 实时用量统计（分级视图）：统计信息卡内四张二级卡——预设统计（按预设 × 主/subagent 口径）、专业 Agent 统计（含「主模型」归组对账）、账号级统计（按真实账号聚合，请求口径计数覆盖全部路由形态）、全局统计；每卡总用量 / 每日 / 实时三段 + 最近调用记录；用量按天持久化（缺省落盘 $DSH_HOME、保留 90 天，重启不清零；router.stats.persist=false 可关闭）、CSV 导出（agent / account / preset 三级）
• 🔌 零配置接入：宿主平面注册 route_agent 工具与路由提示段，内置与自定义的任意 agent 预设自动获得路由能力

安装

方式一（推荐）：dsh plugin 标准管理

前置要求：DSH ≥ 0.2.0-rc.2（声明面支持范围下限；实测主基线 0.2.1-rc.2，见下「宿主兼容性」支持基线集表；dsh plugin 命令自 0.1.1-rc.2 起提供）+ pnpm（宿主插件管理以 pnpm 拉起安装）。

在线安装（插件未发布 npm registry，走 GitHub git 源）：

dsh 形态 · 命令 npm 全局安装了 dsh · dsh plugin --profile web add github:peterwangze/dsh-agent-router npx 拉起 dsh · npx @deepseek-ai/dsh plugin --profile web add github:peterwangze/dsh-agent-router

离线安装（发行包为 npm pack 形态——解压出 package/ 目录）：

1. 下载发行包：dsh-agent-router-0.7.1.tar.gz
2. 解压并进入包目录：

# Windows（PowerShell）
tar -xzf dsh-agent-router-0.7.1.tar.gz
cd package
dsh plugin --profile web add file:./

# macOS / Linux
tar -xzf dsh-agent-router-0.7.1.tar.gz
cd package
npx @deepseek-ai/dsh plugin --profile web add file:./

离线 spec 必须用 file: 且带 ./ 前缀——相对路径由宿主锚定到当前目录，不带 ./ 的裸相对名会被当作 registry 包名。不要用 link:：link: 只创建符号链接、不安装依赖，插件自身依赖缺失无法加载；file: 由 pnpm 完整安装依赖。

更新 / 卸载（git 与 file: 安装均可重新解析）：

操作 · npm 全局安装了 dsh · npx 拉起 dsh 更新 · dsh plugin --profile web update dsh-agent-router · npx @deepseek-ai/dsh plugin --profile web update dsh-agent-router 卸载 · dsh plugin --profile web remove dsh-agent-router · npx @deepseek-ai/dsh plugin --profile web remove dsh-agent-router

完成后重启 DSH 即可。

方式二：安装脚本（无需 pnpm 的替代通道）

无需 pnpm 的替代安装通道；标准管理命令见方式一。

在线安装（一条命令）

平台 · 命令 Windows（PowerShell） · powershell -ExecutionPolicy Bypass -Command "iex (((irm https://raw.githubusercontent.com/peterwangze/dsh-agent-router/main/install.ps1) -join [Environment]::NewLine).TrimStart([char]0xFEFF))" macOS / Linux · curl -fsSL https://raw.githubusercontent.com/peterwangze/dsh-agent-router/main/install.sh \ · sh

安装脚本自动完成：克隆源码 → 链接到 ~/.dsh/profiles/node_modules/ → 在 profiles/web/cordis.patch.yml 写入宿主行（幂等，可重复执行）。完成后重启 DSH 即可。

固定版本：把命令中的 main 换成版本号，如 v0.7.1。

离线安装

1. 下载发行包：dsh-agent-router-0.7.1.tar.gz
2. 解压并进入包目录（npm pack 形态，目录名为 package）：

# Windows
tar -xzf dsh-agent-router-0.7.1.tar.gz
cd package
powershell -ExecutionPolicy Bypass -File .\install.ps1 -LocalPath .

# macOS / Linux
tar -xzf dsh-agent-router-0.7.1.tar.gz
cd package
./install.sh --local .

从旧方式迁移（junction / 脚本安装用户）

此前用安装脚本安装的用户（junction 链接 + 手写 patch 行）迁移到标准管理，三步：

1. 编辑 ~/.dsh/profiles/web/cordis.patch.yml，删除手写的 router / tool-router 两行（保留文件中的其它行）：

- id: router
         name: dsh-agent-router
       - id: tool-router
         name: dsh-agent-router/tool

1. 删除 junction 链接（只删链接、不动源码）：

• Windows（PowerShell）：(Get-Item ~.dsh\profiles\node_modules\dsh-agent-router -Force).Delete()
• macOS / Linux：rm ~/.dsh/profiles/node_modules/dsh-agent-router

1. 按方式一重新 add，完成后重启 DSH。

必须先清后装：手写 patch 行与 bundle 层会重复注册同一对服务（router / tool-router），不清除直接 add 会导致双重注册。

让 AI 帮你装（对话安装）

把下面这段提示词发给 DSH 主 agent 或 ChatGPT / Claude / Gemini 等任意主流 agent，它会自动检测平台并完成安装：

请帮我在 DeepSeek Harness 上安装「dsh-agent-router」多模型路由插件：

1. 确认前置条件：DeepSeek Harness ≥ 0.2.0-rc.2（声明面支持范围下限；实测主基线 `0.2.1-rc.2`）、本机已安装 pnpm。
2. 在终端执行标准管理命令（npx 形态最通用，Windows / macOS / Linux 一致）：
   npx @deepseek-ai/dsh plugin --profile web add github:peterwangze/dsh-agent-router
3. 等待命令执行完成，确认输出无报错（pnpm 会自动安装插件依赖）。
4. 提醒用户重启 DeepSeek Harness。
5. 重启后打开「设置 → Agent 路由」，用预设模板添加专业 Agent（如视觉识别）。

宿主兼容性（实测基线）

支持基线集（ARCH-005 基线档案的人类可读投影；机器权威 = 快照测试，见下）：

基线 · 状态 · dsh CLI · 全系 dsh-* · cordis · schemastery · 实测时点 0.2.1 · primary（当前） · 0.2.1-rc.2 · 0.2.1-rc.2 · 4.0.5 · 3.18.5 · 2026-10-20，npm 全局树实读 0.2.0 · frozen（历史） · 0.2.0-rc.2 · 0.2.0-rc.2 · 4.0.5 · 3.18.5 · 2026-10-17，npm 全局树实读 0.1.5 · frozen（历史） · 0.1.5-rc.1 · 0.1.5-rc.2 · 4.0.2 · 3.18.2 · 2026-09-12 实读

• 声明面（v0.7.0 起）：`peerDependencies` 13 项 + `engines.dsh` 单字段契约，`dependencies` 零宿主包。 13 项 = 8 项特性面（peerDependenciesMeta optional: true：缺失时对应能力降级，不阻断装载）+ 3 项运行时包（dsh-llm / dsh-tools / dsh-typert-protocol，插件直接 import，故为必填 peer）+ 2 项平台包（cordis / schemastery）。11 项 @deepseek-ai/dsh* 的范围收敛同一口径 ^0.2.0-rc.2（声明面锚定口径——锚定 0.2.0 frozen 档案项、以覆盖判据容纳主基线 0.2.1-rc.2），engines.dsh 与之逐字相同（宿主装载门以 engines.dsh 优先判定、忽略 peer 判定，两套范围分叉会被测试判红）。
• ⛔ 宿主包永不得写入 `dependencies`（P0 纪律，2026-10-25 桌面端启动故障的血证）。 桌面端 profile 用 nodeLinker: hoisted 装插件时，pnpm 会把 dependencies 里的 @deepseek-ai/* 提升到 profile 根 `node_modules`；宿主 dsh-app-boot 的装载门（prepareProfileEntries → preflight → manifestOf，走未经运行时替换层拦截的最近副本解析）随即把核心行 tools 解析到那份旧代副本 → evaluatePluginCompatibility 判为「与运行宿主不兼容」→ 该行被 disabled（宿主 stderr：dsh: disabling profile plugin row "tools": …）→ tools 服务永不发布 → required 的 agent-loop 永久 pending → `startup failed: 1 required plugin did not activate`，桌面端完全无法启动；且「禁用第三方插件」不会恢复（被提升的副本来自依赖树，不是 bundle 选择）。宿主包因此只能是 peer：由宿主的安装侧提供，插件的解析经宿主运行时替换层路由回宿主自身副本。两处机器守卫看护此事：tests/host-version-snapshot.mjs（dependencies 零 @deepseek-ai/* + 注册表投影值级锁定）与 tests/host-contract.mjs S3/S10（声明面纯净性 + lib/ 宿主包 import 单点）。
• @deepseek-ai/dsh* 的声明范围同时是宿主装载门的门控钥匙：dsh-app-boot 对插件 manifest 的 engines.dsh（存在时单独判定；否则逐项判定 @deepseek-ai/dsh* peerDeps）做 semver.satisfies(runtimeVersion, range, {includePrerelease:true})，不满足且无豁免（dsh plugin allow-version）即整层拒载——宿主启动 stderr 打印 skipping profile bundle "dsh-agent-router" 与兼容性警告（crash/data-loss 风险提示）。8 项特性面 peer 带 optional: true：该标记仅影响安装器行为（pnpm 装入 profile 时不对缺失 peer 告警），不解除宿主装载门（engines.dsh 存在时装载门甚至不看 peer）。
• 两种版本漂移形态（用户可观察的行为差异）：① minor 跳位拒载——宿主 minor 升级（如 0.3.0）不在 ^0.2.0-rc.2 范围内 → 插件整层不加载，宿主启动 stderr 的 skip 警告是唯一用户侧线索（单范围基线跳跃策略的已知代价，处置 = 升级插件）；② patch/rc 内跳位可运行——落在声明范围内但未经实测的宿主版本（如 0.2.0 final、0.2.1-alpha.x）照常装载运行，属「未实测宿主版本」：若个别宿主面不兼容，面级降级不整页崩溃，健康面板可见各宿主面实时状态。
• 兼容性判定的权威防护 = tests/host-version-snapshot.mjs 版本快照测试 + tests/host-contract.mjs 宿主面契约静态看护（声明面 / 契约形状 / 消费点，见「维护与开发」）+ 本矩阵：声明面不再覆盖主基线（版本范围漂移 / 回退历史基线 / 注入清单引用已消亡包）时全量测试网即红。
• 宿主升级后请同步刷新基线：更新 package.json 版本范围、本矩阵数值与快照测试中的基线常量（测试文件头注释含刷新步骤）。

使用指南

安装并重启后，在 DSH 的「设置 → Agent 路由」打开配置页。

1. 总览

• 顶部总开关：启用多模型路由（关闭后 route_agent 拒绝调用、统计暂停）
• 宿主面健康面板与徽章（v0.5.0 新增，位于总开关下方）：显示宿主版本、各宿主面健康状态（ok / degraded / missing）与最近宿主诊断事件——宿主升级导致某面不适配时直接可见「哪一面不可用、为什么」，不再是「某功能莫名失灵」而无从排查
• 四个分级分类卡片（v0.4.5 起全部默认折叠），点击标题展开/收起：
• 预设 Agent（第一张，默认折叠）：按 DSH 预设粒度配置默认模型；预设卡内含生效诊断面板（生效/未生效可观测）
• 专业 Agent（核心区，默认折叠）：维护自定义专业 agent
• 多模态账号（默认折叠）：API Key 账号、ChatGPT 订阅登录、子代理（无头 CLI）与账号池
• 统计信息（默认折叠）：分级用量明细——内含四张二级卡（预设 / 专业 Agent / 账号级 / 全局）
• 分类头实时显示摘要（预设数量、agent 数量、账号数量、调用统计），无需展开即可掌握概况

2. 预设 Agent 默认模型

「预设 Agent」卡片按 DSH 预设（governance / novel-writing 等宿主预设）为粒度配置默认模型：让不同预设的新会话默认落在不同模型上（例如 governance 用强推理模型、写作预设用便宜长文模型），无需每次新建会话手动切换。

• 添加：展开卡片 →「+ 添加预设配置」→ 统一模板内联表单——下拉选择宿主预设（自动列出宿主预设与信任级别；已配置的预设不再出现；损坏的预设标记不可选）→ 主 Agent 默认模型（服务商 + 模型）→ subagent 默认模型（服务商 + 模型，留空 = 继承主 Agent 模型）→ 添加
• 条目管理：每个预设一行摘要（预设 · 主模型 · subagent 模型/继承），点击展开编辑、删除；宿主侧已删除的预设其残留配置会提示「预设已不存在」，可删除清理
• 语义（事件驱动，打开即显示）：
• 打开即显示：新开（或空白切换）某预设的会话时，对话框模型选择器立即显示该预设配置的默认模型——无需先发消息；空白会话切换预设时实时跟随新预设的配置，切到无配置的预设则回落 DSH 全局默认
• 首条消息后锚定：发出第一条消息后，会话模型由请求日志锚定（宿主原生行为）——后续配置修改不再影响该会话
• 手动选择即当前会话生效：会话内手动切换模型 = 宿主原生会话内选择，插件不监听、不干预、不打架
• 主 Agent 默认模型：仅对空白会话生效——未发过消息（未开启过对话轮）；已运行会话（重启恢复的已产出对话）始终优先，不受配置影响；未设置 = 完全遵循 DSH 现行规则（零行为变化）
• subagent 默认模型：该预设派生的 subagent 的默认模型；未设置时 subagent 跟随主 Agent 当前实际模型（含会话内手动切换后的模型，不固化为预设配置时的值）；显式指定模型的子代理（如插件专业 agent 委派、workflow 指定模型）不受影响
• 实现机制：模型跟随两个预设事件（agent 创建 / 空白切换），不介入会话过程（无请求流拦截，会话进行中零插件开销）；主会话显示播种借用宿主会话模型选择通路，其附带的全局默认写入立即自动写回恢复（瞬态毫秒级，通常不可感知）——恢复失败时自动重试一次，仍失败则在日志高声告警并提示手动改回原全局默认；多个播种事件并发到达时（宿主不等待事件监听器完成）按内部串行化队列依次执行，并发交错不会污染全局默认的写回恢复
• 已知行为披露：重启后重新打开从未发过消息的空白预设会话，同样会触发显示播种（宿主在恢复会话时也发出 agent 创建事件）——与「打开即显示」语义一致；已发过消息的会话不受影响（日志锚定）。全局默认模型（「设置 → 模型」）在播种成功且恢复正常的情况下保持不变；保存后热生效，无需重启。宿主发出预设事件后不等待播种完成（fire-and-forget）——播种按内部串行化队列依次处理（极小窗口内并发创建的多个会话各自正确播种、全局默认仍恢复正确），但会话创建后到播种完成前的毫秒级窗口内，首个请求可能短暂路由到全局默认模型，显示与实际路由随后自动一致（人手操作通常不可感知）

3. 专业 Agent 配置

每个 agent 卡片默认折叠为一行摘要（名称 / 类型 / 生效模型 / 简要用量），点击展开配置：

• 名称、类型：类型只是执行方式（chat 调远端模型 / agent 委派 DSH 子代理 / cli 无头 CLI 子代理 / image 图片生成 / speech 语音转写），不限制能力；能力标签才是自定义的调度契约（路由与 files 图片分发都按它判定）
• 服务商 / 模型：留空自动复用主 agent 模型；「发现模型」按钮可拉取服务商模型列表一键选用（cli 类型下模型字段作为 CLI 的 -m / --model 参数）
• cli 类型：执行方式切到 cli 后，从「子代理」下拉选择账号区已添加的 CLI 条目作为执行路径（未选择 = 旧形态内嵌命令，提示迁移）。卡片保留登录状态指示、模型覆盖字段（-m / --model，空 = CLI 默认模型）与底部「登录」按钮；命令、参数、登录、拉取模型与统计统一在「多模态账号 → 子代理」维护
• 能力说明：主 agent 据此判断何时调用该 agent
• 高级设置：推理强度、温度、最大输出、轮数、System prompt、工具白名单（agent 类型）；cli 类型高级设置仅保留能力标签与 System prompt（注入任务头部作角色设定）
• 操作：启用开关、保存、测试（cli 类型 = 登录状态检查）、删除；底部显示该 agent 的实时用量与 tokens 分布
• 列表末尾「+」用预设模板快速添加：视觉识别 / 图片生成 / 翻译 / 语音识别 / 视频生成 / 通用子 Agent（模板只是能力起点；Codex/Claude/Gemini 等 CLI 工具不是 agent 类别，而是任意 agent 在 cli 执行方式下可选的子代理路径）
• 对话框图片：启用带 image 能力标签的视觉类专业 agent（chat / agent / cli 类型）后，对话输入框出现「添加图片」按钮——选中图片进入原生附件栏随消息原生发送；图片保留在会话日志中原生显示，插件在 system 层注入路由提示，主 agent 按需调用 route_agent 交给视觉 agent 分析（includeImages 转发最近消息的图片，自动附带主会话最近上下文——截图是对话上下文的一部分，视觉 agent 结合上下文作答）。生成图片以缩略图显示在 route_agent 工具卡片里（点击查看原图），纯文本主模型全程不接触图片字节

4. 多模态账号配置

• API Key 账号：统一配置式添加——服务商 ID（openai / my-gateway / one-api 等）+ 接口类型（openai-completions / openai-responses / anthropic-messages）+ Base URL + API Key（本地部署可留空）+ 模型列表，填好即保存到共享模型列表；官方服务商、第三方中转与本地部署同一条路径
• ChatGPT 订阅登录（一级，正式通道）：ChatGPT 订阅经官方 Codex OAuth 通路一键授权登录（浏览器授权 → 凭据落盘 → 专业 agent 的「OAuth 账号」字段指向它即可调用）；需自行知悉并承担平台服务条款与账号风控风险
• 子代理（无头 CLI）：Codex / Claude Code / Gemini CLI 等 CLI 工具作为账号类条目统一管理——「＋」一键添加（预填命令与参数）或自定义；每卡配置命令/参数/超时/并发、登录状态与一键登录（弹出终端窗口完成 codex login 等并自动刷新）、拉取模型（CLI 无列表命令时回退常见模型清单）与用量统计；专业 Agent 的「执行方式 = cli」时从「子代理」下拉直接引用这些条目。Codex 沙箱参数按平台自适应：macOS/Linux 用 --sandbox workspace-write（产物如图片必须能写入工作区，read-only 会导致任务无法落盘），Windows 用 --sandbox danger-full-access——codex 的 Windows 沙箱实现无法启动 WindowsApps 目录下的 shell（报 CreateProcessAsUserW failed: 5/1920），每条命令都会在执行前失败并触发子代理反复重试、成倍浪费 token，关闭 OS 级沙箱后仍保留审批策略；参数留空即用该默认，自定义参数未显式指定 --sandbox 时也会按平台自动补齐；每次执行宿主都会注入重试纪律（同一失败最多重试 2 次即报告错误结束），避免子代理无限重试卡死任务
• 自定义提供方（＋ 自定义）：未集成的服务商、第三方中转与本地部署（Ollama / One-API / LM Studio 等）——填服务商 ID 与 Base URL 即复用模型添加基座注册到共享模型列表，模型列表留空时保存会自动从端点拉取并写入（拉取失败会提示手工填写模型 id），注册后也可用「发现模型」拉取端点模型；API Key 可留空（免鉴权本地服务）
• 高级扩展（默认折叠）：账号池收进折叠卡片（v0.3.2 起不再提供「OAuth 官方登录 / 粘贴 token」的添加与管理表单——官方 API 不提供 OAuth，该入口已移除）——
• 账号池：多个已授权账号组成池，按健康优先 / 用量最低 / 轮询自动选号，单账号失败自动切换；agent 的「OAuth 账号」字段可指向池；池内账号行提供「删除账号」入口（删除条目与本机凭据，并从所有池移除引用——与「移除」仅移出本池区分）
• 未入池的 OAuth 账号：历史配置中未加入任何账号池的 OAuth 账号（含旧版自定义 / 粘贴 token / 未知预设值账号）在折叠区以极简列表呈现，仅提供删除入口（清理凭据与条目）

5. 统计信息

• 四张二级卡（每卡统一三段：总用量 / 每日用量 / 实时 tokens 分布 + 最近调用记录）：
• 预设统计：按 DSH 预设聚合，主 Agent / subagent 两口径分开计数
• 专业 Agent 统计：每个专业 agent 一卡，外加「主模型」分组卡（主 agent 含 subagent 经插件通路的用量归组对账）
• 账号级统计：按真实账号聚合（同一账号的多通路用量归并一卡——含包装路由与宿主官方路由），模型细分表与 tokens 分布展开查看
• 全局统计：全局调用数 / 失败数 / 入出 tokens 汇总
• 计数口径：账号级调用数 = 请求口径（每次 LLM 请求恰记一条，覆盖全部路由形态）；token / 耗时 / 失败数 = 调用明细口径——插件自有流才有 token，直连 provider 端点无 token 上报时显示 0
• CSV 导出三级（agent / account / preset），一键清空统计，每 2 秒自动刷新

维护与开发

宿主升级 SOP（五步——检测 / diff 定性 / 影响分级 / 适配批 / 发布与复验，含基线登记 checklist 与重装后真机复验清单）：见 docs/host-upgrade-sop.md（ARCH-005 R5 固化，每步含机器入口与失败可观测面）。

门控命令（单入口，本地与 CI 同一命令）

node tests/run-all.mjs          # 全量测试网：枚举 tests/*.mjs 的独立套件顺序执行并聚合退出码
npm test                        # 等价（package.json scripts.test）
node tests/host-contract.mjs    # 只跑宿主面契约静态看护（npm run test:contract）

• 任一套件失败 → 退出码非零（run-all 打印失败套件清单与输出尾部）；单套件超时 10 分钟（RUN_ALL_TIMEOUT_MS 可覆盖，挂死套件不得吞掉门控）。
• 顺序执行（非并行）：部分套件占用固定端口 / 临时 DSH_HOME / 进程级单例，并行会互扰。
• 套件计数口径：tests/ 下 attachments.mjs / audit-001-concurrency.mjs / client-render.mjs / install-entry.mjs 只 export runX(check)、无顶层执行、无 process.exit，属 runner 模块——其断言由 smoke.mjs import 后调用承载，不计入独立套件（当作套件子进程执行 = 零断言幻影 PASS：计数虚高 + 静默覆盖丢失）。run-all 启动行区分「N 独立套件 + M runner 模块」，并在跑套件前机器断言 `smoke.mjs` 仍 import 并调用这些 `runX`：调用点消失/改名、模块被误登记、或登记项含 process.exit → 门控红（排除不得等于丢覆盖）。双向守卫（FIX-037 ②）：反向断言「未排除的每个套件 MUST 含独立入口/退出闸（process.exit / process.exitCode / invokedDirectly，判据取剥注释后的代码文本）」——新增 runner 形态模块漏登记即红，幻影 PASS 不可复发。
• skip 可见性（FIX-037 ①）：通过套件默认只打一行摘要，故 run-all 捕获套件输出中的 skip 行（ skip … / -- …）并回显——PASS (Nms, K skip) + #SKIP | ，汇总行附 #SKIP n (套件×条数)；smoke.mjs 汇总行同时给出自身 skipped 计数。门控（CI）日志因此可判定「哪些断言被跳过」，与「打印可见 skip、禁静默降级」的口径一致（此前 skip 行被 stdio: pipe 吞掉）。
• 产品代码变更 MUST 跑全量网并零回退（P4）：改 lib/**、package.json 声明面、cordis.patch.yml、tests/** 后必须全绿再提交。

静态看护体系（tests/host-contract.mjs）

宿主面契约静态看护（ARCH-004 设计 §5.1 D3(a) 完整落地），五类守卫：

• 契约快照四类面：llm 适配器契约（动态枚举宿主基类原型 + twin / oauth-llm 适配器实现奇偶）、宿主协议对象导出面、remote.* 面方法形状、ctx 服务面、转发事件白名单——宿主新增/删除面即红（RISK-003 预警）；
• 宿主源码形状锚点：高风险非导出面以「形状签名 + 注释锚行号」冻结（P10-④：桩形态锚定宿主源码，禁按心智模型伪造宿主面）；
• 声明面比对：dsh.client.inject / peerDependencies 与 lib/host-abi/inject-manifest.js 代码侧常量交叉一致；cordis.patch.yml 两宿主行 id 存在性（宿主对不存在条目仅 stderr 警告——静默面守卫）；宿主侧包表半边：inject 三 client 包 vs 宿主 @deepseek-ai 实际包表（插件自身 node_modules 不含这些包，故只能在宿主靶子上核验；宿主不可达时与 S7 同语义记 skip）；
• 消费点黑名单：高危面名禁止域模块外裸 ctx.get（低危面分级白名单放行）；域管事件名禁止域外裸 ctx.on（scoped 钩子 agent/pre-step、agent/created、agent/request 直订合法）；
• 字段级 wire schema 白名单：消费字段 ⊆ 宿主 schema 字段（锚宿主 dsh-api-remotes 源码声明），字段增删/改名不再静默；
• 转发事件白名单：客户端 $on 订阅事件名 ⊆ 宿主转发白名单（死订阅类缺陷的机器防线）。

本套件不依赖宿主 checkout 存在（基线与锚点为静态常量，锚行号写在注释里）；宿主源码可达时（DSH_HOST_SOURCE / DSH_HOST_PACKAGES 显式优先，本地 _npx 缓存探测兜底）自动追加增强靶子组直读源码核验，不可达只记 skip 不失败。靶子选择确定：多 _npx 缓存共存时按目录名降序取首命中（readdirSync 顺序非契约），启动行打印实际读取路径、来源与未选候选——RISK-003 预警可复现。版本一致性判据（FIX-037 ③）：确定性 ≠ 指向运行宿主，故选定靶子与全部候选的关键包版本（dsh + S7 直读四包 dsh-api-remotes/dsh-api-session-controller/dsh-client-ui-model-selection/dsh-llm + S3 判据两包 dsh-client-ui-settings/dsh-client-locale）逐条打印并与 tests/host-version-snapshot.mjs 的 HOST_BASELINE 比对——不一致即显式告警 + 记 skip（门控可见），S3/S7 结论的适用范围由此可判定（不引入宿主硬依赖红——BR-03 不变）；该判据的基线副本由「基线副本」断言与权威文件机器锁定（刷新漏改任一即红，FIX-037 R0 P2-1）。宿主升级后按文件头注释刷新基线（共四处，含本套件的副本），并与 tests/host-version-snapshot.mjs 的版本基线同步执行。

CI 第①步（RISK-001 主轨道）

.github/workflows/ci.yml 单 job：checkout → setup pnpm → setup-node（LTS 锁定）→ pnpm install --frozen-lockfile → node tests/run-all.mjs。

• 能覆盖：全部可在 Node 内静态/桩驱动执行的套件（契约快照、声明面比对、消费点守卫、事件白名单、域行为判别）——与本地同一条门控命令（启动行区分独立套件与 runner 模块）。
• 在 ubuntu-latest 上会 skip 的断言（打印可见 skip、不失败）：① host-contract.mjs 的 S3 宿主侧包表半边与 S7 增强靶子组（CI 无宿主 checkout）——其余 71 条静态断言照跑（宿主不可达侧；宿主可达侧 82 条——FIX-037 R1 计数更新），宿主靶子不可达记 -- skipped（靶子可达时另打印关键包版本一致性判据，≠ HOST_BASELINE → 告警 + skip）；② smoke.mjs 的 install.ps1 解析（探测 powershell/pwsh，两者皆无则打印 skip 原因；Ubuntu 运行器预期自带 PowerShell 7，该平台事实以 CI 首跑日志确认）；③ install-entry.mjs 的在线/离线命令臂按可用宿主择一（ubuntu 走 sh+curl 与 pwsh 臂）。FIX-038 平台适用性判据（非适用平台记可见 skip，禁静默通过）：install-entry.mjs 的 3 条 -File 离线臂（offline install (-File) succeeds/idempotent、bare-source install (-File) …、real node_modules dir left untouched (-File)——install.ps1 自述 Windows 专属入口，离线臂依赖 junction / robocopy / 反斜杠子路径）仅在 win32 执行（FIX-040 P2-2 起 `smoke.mjs` 的 `cli invocation cmd shim` 已平台中立化：resolveCliInvocation 增可选平台判据注入参（默认实机、行为零变化），断言显式传 'win32' 驱动 ⇒ 全平台恒跑，并新增注入 'linux' 的反向旁路臂）；POSIX 对偶覆盖按臂分列（仅陈述实际成立范围）——§6（-File 离线安装）与 §6c（裸源码依赖链接）在 sh 可用时由 install.sh 臂承担（断言未删除），§6d（自带真实 `node_modules` 不得改动）无 POSIX 对照臂（install.sh 的「源码自带依赖目录：…（跳过依赖链接）」分支与 LINKED=0 拷贝回退护栏同载该数据保护语义却零判别测试 = 已知覆盖缺口，台账候选；锚形 = 符号名 / 代码串 + 文件——FIX-040 起不再写死行号）。这些 skip 行不再只在套件内可见：run-all 汇总回显 #SKIP | 与 #SKIP n (套件×条数)（FIX-037 ①）——CI 日志可直接判定被跳过的断言；单宿主探针失败同样打印 skip … (probe failed: …)，该臂不静默消失。预期内的 skip（非缺陷，FIX-037 P2-3/R1 口径 + FIX-038 扩表 + FIX-040 收口，按环境分列）：ubuntu 正常态 = `#SKIP 6 (host-contract.mjs×2, smoke.mjs×4)`（预期值——修复后首跑前尚未实测，以首跑日志逐行复核）——host-contract 在 CI 必然无宿主（无 DSH_HOST_SOURCE/DSH_HOST_PACKAGES，Linux 无 LOCALAPPDATA）⇒ S3 半边 + S7 组 2 条，smoke 4 条 = install.ps1 parses (powershell) 探针臂 1 条（5.1 仅 Windows 存在，同一断言由 pwsh 臂完整执行，≠ 断言被跳过）+ FIX-038 遗留 -File 离线臂 3 条；属 Windows 侧、不计入 ubuntu 的 skip 来源：POSIX online checks（触发条件 = sh/curl 均不可探；ubuntu 运行器自带 sh+curl ⇒ 该臂照跑不跳）、win32 侧 0o600 可见 skip（ubuntu 照常执行）、.cmd shim（FIX-040 P2-2 起全平台恒跑）；Windows 本地正常态 = `#SKIP 2 (smoke.mjs×2)`（本地实测；FIX-040 起由 `#SKIP 1` 升为 2 = install-entry 的 `POSIX online checks` 1 条 + smoke 的 `0o600` 可见 skip 1 条，后者此前为 `if (!win32)` 静默消失，属 FIX-037 ① 同族收口）。判据取相对基线增量：出现新增 skip 来源或断言数下降才需研判（绝对值随平台组合变化，不作为告警依据）。
• 必须 Windows 本地跑（CI 不覆盖）：Windows PowerShell 5.1 解析/执行臂（install.ps1 + install-entry 的 5.1 online/offline 命令）、目录 link 语义的 win32 半边（win32 junction——install.ps1 的 -File 离线安装臂按此判据平台门控：非 win32 记可见 skip，不再以失败/崩溃形态出现；按臂分列，FIX-040 如实化：其 POSIX 半边（symlink）实为 CI 已覆盖——sh 可用时 install-entry 的 sh --local 臂在 ubuntu 首跑日志中已执行，run 34696694673 的失败点在其后 §6c 的 lstatSync 裸抛；CI 真正不覆盖的是 win32 junction 半边与 §6d 对偶臂）、宿主运行时装配与 fiber inject 面就绪时序、GUI 渲染与设置页交互、OAuth 真实端点登录流、CLI 子代理真机执行。这些仍由真机手工验收 + 设置页诊断面板（router/hostFaceDiagnostics：宿主版本 + 面健康 + 诊断环形）兜底。对称面：smoke 的 POSIX 文件权限断言（0o600）仅在非 win32 平台执行（FIX-040 起 win32 侧为可见 skip，非静默消失）。
• 宿主依赖在 CI 的解析：lib/ 的宿主包 import 全部收敛到 `lib/host-abi/host-imports.js` 一个出口（S10 静态守卫；其余 lib/** 零 @deepseek-ai/* 裸 import），这些包声明为 peerDependencies，运行时由宿主的运行时替换层路由到宿主自身副本——插件侧不再持有宿主包副本（v0.7.0 前它们在 dependencies，正是桌面端启动故障的根因，见「宿主兼容性（实测基线）」节的 P0 纪律）。本仓 node_modules 由 devDependencies（同 5 包）供给，故冻结锁文件安装即可跑通全量网。

隔离 worktree 验证规矩（EV-178 事故教训）

用 git worktree 做隔离验证时，清理前必须先删 junction 再 `git worktree remove`——git worktree remove --force 会穿越指向主仓库 node_modules 的 junction，删到 pnpm store 内容（EV-178 实证：cordis / dsh-llm / schemastery 等 5+ 包内容被误删，靠 pnpm install --frozen-lockfile + 全量网复验自愈）。规矩：

# 1) 先删 worktree 内的 node_modules junction（只删链接，不动主仓库内容）
(Get-Item <worktree>\node_modules -Force).Delete()
# 2) 再移除 worktree
git worktree remove <worktree>

常见问题

• 视觉 agent 用什么模型？ 需要支持图片输入的模型（如 gpt-4o 等 OpenAI 兼容多模态模型；实测 opencode-go/qwen3.7-plus 亦可）。模型不支持图片输入时插件会在调用前给出明确报错。
• 能用 Codex / Claude Code / Gemini CLI 做子代理吗？ 能——在「多模态账号 → 子代理」添加 CLI 条目（一键预填或自定义），完成登录与模型拉取；然后把任意专业 agent 的执行方式切到 cli，从「子代理」下拉选择该条目。无头模式在工作区内执行，CLI 自己管登录（codex login 等一次即可），不经过插件的 OAuth 账号体系。
• CLI 子代理任务一直转圈/卡住？ CLI 子代理是完整 LLM agent：遇到可重试的错误（网络 502、上游超时）会自行反复重试而不是立即失败，而插件只在总超时（默认 15 分钟/条目，工具级 20 分钟）后强杀，因此表现为长时间卡住。宿主已注入重试纪律（同一失败重试 ≤2 次即报告错误结束），失败时返回结果会带上子代理 stderr 关键行（工作区 .router-files/cli-run-*-err.log 也有完整日志）。常见根因：① 上游网络不可达——图片生成走子代理自身的上游服务（如 Codex 走 ChatGPT 图片接口），需保证本机可达（开启代理等）；② 沙箱配置不当——Codex 在 Windows 上用 workspace-write / read-only 时，OS 沙箱无法启动 shell（每条命令报 CreateProcessAsUserW failed: 5/1920），子代理会反复重试浪费 token；保持参数留空（平台自适应默认）或显式使用 --sandbox danger-full-access（Windows）/ workspace-write（macOS/Linux），read-only 还会让产物无法落盘。注意：自定义参数里的旧版 --full-auto 会让 --sandbox danger-full-access 失效（实测仍走 Windows 沙箱并报 5/1920），请一并移除；③ 并发与超时——同一子代理受「并发上限」约束，连点多次会各自排队或报「正忙」。
• ChatGPT / Claude 能 OAuth 登录吗？ ChatGPT 订阅账号：设置 → Agent 路由 → 多模态账号 →「ChatGPT 订阅登录」一键登录（v0.3.1 起为正式通道，无需开启任何开关；v0.3.0 时期的实验开关已废弃）。曾在 v0.3.0 开启实验后又手动关闭开关的用户请注意：升级后通道恢复可用（旧的「关闭」偏好不迁移），暂不使用时可在该账号卡「登出并删除凭据」或删除账号。官方 API 不提供 OAuth（Claude 官方 API 亦无）：官方服务请用官方 API Key；v0.3.2 起已移除不可用的「OAuth 官方登录 / 粘贴 token」管理入口，历史 OAuth 账号仅保留在账号池与「未入池的 OAuth 账号」列表中（可在池行或列表行删除清理凭据），不再提供登录与维护表单。v0.4.1 起：订阅账号可直接生图（draw 类 agent 绑定订阅账号即可出图，gpt-image 系模型透传），订阅主模型默认经宿主官方 openai-codex 路由（token 自动注入；可在订阅卡切回「插件内置」通路——既有会话切回后需在模型选择器手动重选模型组）。
• 主 agent 怎么知道该调谁？ 安装后所有 agent 预设自动获得 route_agent 工具与路由提示段，按能力标签路由：带图片的任务路由给声明 image 能力的 agent，语音转写路由给 audio 能力 agent。
• 纯文本主模型怎么发送对话框图片？ 主模型不支持图片输入时，harness 默认拒绝带图片的消息（且图片块进入历史会让纯文本模型的每次请求报 UNSUPPORTED_CONTENT）。启用带 image 能力的视觉类专业 agent 后，多模态接管生效（v0.3.3 起为图片条件化自动接管）：输入框贴图即自动把会话模型切到「\ + 多模态」包装路由（无需手动开启接管开关；无图/纯文本轮永不自动切换、用户手动选择的模型始终尊重）；发送后保持该路由——包装路由对带图消息放行准入，插件把模型输入中的图片块改写为路由提示（会话日志保留原件、界面原生显示，带图轮始终由主模型应答），后续纯文本轮经包装路由零开销委托原生模型，主 agent 据此调用 route_agent（includeImages 转发图片并自动附带主会话最近对话上下文，视觉 agent 结合上下文与截图作答——截图真正参与上下文理解，而非孤立 OCR）。生成图片经插件同源画布直达显示（v0.4.1 起：内容寻址同源路由直接出图，route_agent 工具卡默认折叠——过程收起、结果直出，输入区 🖼 按钮可查看会话产物集合；不再经宿主附件通道，历史「图片加载失败」类显示层问题随之根治）。行为说明：移除未发送的图片不会自动切回原模型（插件无法安全区分「发送后清空」与「移除」，切回请在模型列表手动选择）；主模型本身支持图片时，原生粘贴 / 拖拽发送仍照常可用。
• 统计会丢吗？ 不会丢——v0.3.0 起用量统计默认写入磁盘（位置：DSH 数据目录 $DSH_HOME；按天 JSONL；默认保留 90 天），DSH 重启后统计仍在；不希望落盘可在设置中关闭 router.stats.persist（回纯内存行为，此前已落盘的数据不受影响，重新开启后自动恢复）。降级可行域判据：目标版本的统计行版本 ≥ 数据行版本才可读——v0.4.5 起写入的统计行为行版本 v2（v0.4.4 及更早版本为 v1），旧版本读不了 v2 行；降级后首次统计加载会触发旧版坏行修复、不可逆清除这些 v2 行，故降级前请先备份统计目录（DSH_HOME/dsh-agent-router/stats/）。
• 升级 / 重复安装？ 已用方式一（dsh plugin 标准管理）安装的用户直接 dsh plugin --profile web update dsh-agent-router（或 npx 形态）；方式二脚本安装的用户重跑安装命令即可（脚本幂等；在线模式自动 git pull 更新源码）。

License