dsh-connect-zcode

dsh-connect-zcode

把本机 ZCode 桌面客户端的模型接入 DeepSeek​ Harness（DSH） 的本地插件。

provider zcode-cli 背后是一个常驻的 zcode app-server 会话（stdio JSON-RPC，真流式）。 插件自动发现客户端的安装位置与数据目录，按客户端自己的方式拉起它自带的 agent， 再把该账号能服务的模型清单转述给 DSH —— 烧的是 ZCode 账号的额度，不需要 API Key，也不需要自建网关。 模型可以按需勾选启用哪些（见「选择启用哪些模型」）。

当前版本 0.6.1。

本仓库： · 上游原版：（AGPL-3.0）

v0.6.1 修复：插件页的「zcode 模型」卡片此前在真实宿主上不可用——显示

「插件配置当前不可用」，开关全灰，每次写入都被回滚。根因是 DSH 设置只收录

至少有一个 volatile 字段的插件条目（volatileForm() 无 volatile 字段时整个条目被跳过），

而模型列表字段原本是普通数组，所以该命名空间从未出现在 settings.describe() 里。

0.6.1 把两个字段标记为 volatile 并做了解包。同一版本里开关改为草稿 + 保存，

避免每次勾选都触发一次目录重读而让列表闪灰。详见 CHANGELOG。

它能做什么

• 自动接入桌面客户端：读注册表 Uninstall 项发现安装根，读 ~/.zcode/v2/setting.json

的 dataBaseDir 解析数据根，然后按客户端自己的形态启动内置 agent （ZCode.exe resources/glm/zcode.cjs app-server --stdio --surface desktop，并注入它需要的 ELECTRON_RUN_AS_NODE / ZCODE_* 环境变量）。无需任何环境变量配置。

• 注册套餐账号 provider：桌面版 CLI 接受 provider/updateAccountConfig，插件把内置 release

里声明的 account:* 套餐 provider 连同 {availability, current, entitled} 状态推给它并刷新 registry，套餐模型才进入清单。

• 按路由选对签名凭证：account:* 用凭证里的

account-provider:coding-plan::account::api-key，z.ai Start Plan 才用 zcodejwttoken（用错会卡在 Client signing requires an API Key）。

• 真流式（text/reasoning delta 直接转发）、工具调用、图片输入、多轮会话按 DSH sessionId 复用。
• 逐模型启用/停用：插件页卡片里勾选，保存后 DSH 的模型选择器随即增减。

换机器 / 换账号后如果套餐不可用，上游业务错误（例如

1309 您的GLM Coding Plan套餐已到期）会被 doctor / turn 原样报出来，不会伪装成协议故障。

与上游 0.3.x 的差异（v0.4.x，基于实机逆向重写通道层）

上游假定「DSH 侧注入 Start Plan 账户 + 硬编码模型清单」，实测在 npm 版 CLI

（zcode-app-cli）上这两条都错：

1. CLI 处于 standalone 模式，拒绝宿主注入。provider/updateAccountConfig 直接回

Error: Standalone Account 由本进程管理，不接收 Host 覆盖。账号本来就被 CLI 自己管着，

注入既不可能也没必要 —— 已删除。

2. **同时设 ZCODE_BUILTIN_PROVIDER_CONFIG_FILE 与 ZCODE_PERSONAL_PROVIDER_CONFIG_FILE

会让 CLI 直接起不来**，stderr 固定为 Error: Bundled 与 Active ZCode Built-in Release 均不可用，

而且不服务任何请求。桌面客户端写出的 builtin revision 一旦超过当前 CLI 能解的 schema，

就必然踩中。已彻底不再注入任何 ZCODE_* 环境变量。

3. 模型清单改为读 CLI 上报。session/create 的 settings.model.available 是权威清单；

上游硬编码的 200000 / 64000 / [FALLBACK_MODELS] 与实机差 5 倍（真实

contextWindow=1000000、maxOutputTokens=128000），provider id 也不同。

4. provider id 不再硬编码。上游写死 account:zai-start-plan，但 standalone 下该 provider

不进入 registry；实机是 account:zai-individual-coding-plan。

通道逻辑（回合锁、自愈、事件流、图片物化）沿用上游的逆向结论并补了对应改造，版权归上游作者。

DSH Agent ──► provider "zcode-cli" ──► ZcodeAppServerAdapter
                                            │  spawn zcode.cjs app-server --stdio（常驻）
                                            ├─ session/create    拿 settings.model.available（模型清单）
                                            ├─ session/subscribe  desktop-continuous 事件流
                                            ├─ session/setModel   仅在目标模型与当前不同时切换
                                            ├─ session/send      发回合（真流式）
                                            └─ interaction/requestProviderRuntimeHeaders  回 OAuth 鉴权
                                                  └──► zcode.z.ai/api/v1/zcode-plan/anthropic

安装

前置条件：本机已安装并登录 ZCode 桌面客户端（有可用额度的账号）。没有客户端时插件不会注册 provider。

方式一：直接从 GitHub 安装（当前推荐）

dsh plugin --profile desktop add shudaozhang/dsh-connect-zcode

--profile 换成你的 profile 名（通常是 desktop 或 web）。等效的 pnpm 写法：

pnpm add github:shudaozhang/dsh-connect-zcode

本仓库暂未发布到 npm，所以不要用 add dsh-connect-zcode（会 404）。

GitHub 安装已实测通过：+ dsh-connect-zcode 0.6.1。

方式二：DSH 插件市场（上架后可用）

DSH → 插件 → 发现 → 搜索 dsh-connect-zcode → 安装 → 重启 DSH。

方式三：本地目录装配（开发用）

见下方「开发」章节里 cordis.patch.yml 的 file:// 写法。

安装后

DSH 设置 → 模型（Models）→ 提供方 zcode → 选模型。 也可以到 插件 → dsh-connect-zcode 页面里勾选要启用哪些模型（见「选择启用哪些模型」）。

用法

1. 装一份 ZCode CLI（npm i -g zcode-app-cli，或桌面客户端自带的 zcode.cjs），并登录有额度的账号。
2. 把本插件装进 DSH profile，重启 DSH。
3. DSH 设置 → 模型（Models）→ 提供方 zcode → 选模型。

可用模型不是插件写死的，而是 CLI 当前账号能服务的那批，随账号套餐与客户端版本变化。 下例取自本机（2026-10-24，客户端 3.16.3 / 17 个模型）：

provider · model · context · max output · image account:bigmodel-individual-coding-plan · GLM-5.3 · 1000000 · 128000 · ✓ account:bigmodel-start-plan · GLM-5.3-Flash · 1000000 · 128000 · ✓ account:bigmodel-start-plan · GLM-5.2 · 1000000 · 128000 · ✓ 个人 provider（new-provider-* 等） · qwen3.8-flash / deepseek-v4.1-flash 等 · 1000000 · 384000 · ✓

想看清本机能出哪些模型、各自的 provider 与能力位，跑 node bin/dsh-connect-zcode.js models。

同一 model id 出现在多个 provider 上时（如上表 GLM-5.3 同时在 account: 与 zai-api 上）， 插件优先 `account:` 开头的路由 —— 那条烧计划额度，zai-api 那条按 API Key 计费。 想指定确切路由，就在 cliModels 里给条目写 id: "zai-api/GLM-5.3"（providerId/modelId 形式）。

• 真流式（text/reasoning delta 直接转发）、工具调用、图片输入（图片以本地文件随消息附上，agent 用 Read 读图）
• 多轮会话按 DSH 的 sessionId 复用 app-server 会话
• 会话标题这类辅助调用在本地生成，不消耗额度
• 前置条件：本机能跑起 ZCode CLI，且它已登录有额度的账号

安全须知（装之前必读）

这个「模型提供方」的真身是一个以你当前用户权限运行、且带全套工具执行能力的 agent。它不在 DSH 的工具权限边界内运行：DSH 的权限模式和浏览器审批界面只处理 DSH Host 自己发起的工具调用，不能确认 ZCode app-server 发起的授权请求；本插件也没有自己的交互式确认窗口。

• 两种策略都会将会话设为 ZCode 的 build 权限模式，确保授权请求经过插件处理；模式设置失败时本轮停止。该策略不构成操作系统沙箱，也不阻止无需额外授权的 agent 操作。
• 默认 authorizationPolicy: deny：插件对 interaction/requestPermission 回复 deny，不会弹确认框；需要授权的工具调用会失败。
• 只有显式设置 authorizationPolicy: allow-all 才会自动批准已知的 interaction/requestPermission 请求。该设置允许 agent 以当前用户权限执行 Bash、文件读写和联网操作，不要在不可信任务中启用。
• 名称包含 approval 或 permission 的未知 app-server 请求始终拒绝，即使启用了全自动模式；如果 ZCode 将来改变权限协议，相关调用会失败关闭。
• agent 的输入是 DSH 拍平后的整段对话（包括网页抓取、工具结果等外部内容）。提示注入仍可能诱导全自动模式执行恶意操作；默认拒绝减少了授权面，但不能消除未经过授权请求的副作用。
• 子进程环境变量按白名单透传（系统基础变量、ZCODE_*、NODE_EXTRA_CA_CERTS），不继承

DSH 宿主的全部 env；确有需要可用配置项 childEnvAllow 追加变量名。

• 鉴权 token（zcodejwttoken）只经本机 stdio JSON-RPC 交给 agent 进程，不发往任何第三方。

通道原理（全部实机逆向验证）

1. spawn zcode app-server --surface terminal --no-color 时**不注入任何 ZCODE_***。

实测三种环境（零变量 / 只 ZCODE_SERVICE_AUTHORITY_MODE / 再加 ZCODE_BASE_URL） 产出的模型清单完全相同；而注入 builtin/personal 文件路径会引入上面说的启动失败。

1. session/create 的返回里 settings.model.available 是模型清单，session.model 是当前模型。

条目形状：{ref:{providerId,modelId}, label, providerLabel, contextWindow, maxOutputTokens, reasoning:{levels:[{value}],defaultLevel}, properties:{inputFormat:{supportsImage}}} —— 没有 inputModalities 字段，图片能力要看 properties.inputFormat.supportsImage。

1. session/subscribe 用 {deliveryKind:'desktop-continuous', afterSeq:0, includeSnapshot:true}。
2. session/setModel 要求对象式 {providerId, modelId, options:{reasoningLevel}}；

reasoningLevel 取自条目上报的档位（本机是 low/high/max，默认 max）。

1. agent 发模型请求前回调 interaction/requestProviderRuntimeHeaders 要鉴权 —— 回共享凭证里的

`zcodejwttoken`（oauth:zai:access_token 已过期，回它上游 401）。agent 自己算签名，能过 WAF。

1. session/event 的事件类型在 params.type 顶层（不是 payload.type），turn.failed 也要处理

（错误码在 payload.error.attribution.providerErrorCode），replayState 里不能有 undefined 字段（lossless JSON 校验会炸）。

1. 服务端请求必须应答，否则 session/create 挂起：session/requestRuntimePreferences 回

{nativeSearchEnhancementsEnabled:false, memoryEnabled:false, askUserQuestionAutoResolutionEnabled:true, modelContextBudgetStrategy:'preflight-v1'} 就够。

HTTP 直连计划端点会被无痕验证拦 —— 只有 agent 二进制自己发的签名请求能过，

所以「反代」的形态是托管 agent 进程而不是自建 HTTP 网关。

回合锁与自愈