前言¶

DeepSeek Harness（DSH）把工具链、会话、审批和团队协作收在一套 harness 里跑。ZCode 桌面端自带 agent loop、子代理和记忆，但不少场景里你只想用 ZCode 绑定的智谱 BigModel Coding Plan 额度，会话和工具仍走 DSH。

直接抄 API Key 去调网关并不省事：Coding Plan 是一等 API Key（id.secret），可存于明文配置或加密凭据库；历史上 Start Plan 用的是 JWT 且上游风控不允许直连，该插件曾尝试的托管代发通道已在 2026-10-17 下线。下面介绍社区插件 dsh-connect-zcode（维护者 Shuffle-1992）：从 ZCode 本地配置读取凭据，在 DSH 注册标准 LLM provider，由 DSH 自己发模型请求。

这是什么¶

dsh-connect-zcode 是 DSH 原生 provider 插件，分类属于模型推理。它把 ZCode（Z.ai / 智谱 BigModel）的 Coding Plan（付费套餐） 接进 DSH，provider id 为 zcode，线协议为 anthropic-messages，端点来自 ~/.zcode/v2/config.json 中的 baseURL。

凭据策略是零落盘、零缓存、每次调用现读。插件未发布到 npm，当前仓库版本为 0.6.0（MIT）。DSH 兼容性在 package.json 中声明为 engines.dsh: ">=0.2.0-rc.2 <0.3.0-0"。

需要「agent 自主执行任务 + 免费 Start Plan 额度」时，README 指向姊妹项目 zcode-dispatch（派发台），与本插件的 provider 模式互补，不在本文安装范围内。

核心功能¶

Coding Plan 直连通道¶

插件从 ZCode 配置里解析 builtin:bigmodel-coding-plan（可通过 planKey 覆盖），把模型列表和上下文窗口声明给 DSH。默认上下文窗口 200000；设置面板可把单模型预算写到 1M（contextBudgets），与 ZCode 客户端在 config 里声明的上限对齐。

设置面板能力¶

客户端注入 DSH 设置 UI，支持：

• 模型显隐（enabledModelIds）：空数组表示全部显示，非空则只显示列出的 model id。
• 上下文预算（contextBudgets）：按模型写入官方 Max 档（如 1000000）。
• 能力开关（modelOverrides）：对无官方元数据的模型可配置 reasoning / image；官方数据锁定的模型忽略此项。

并发推理上界由 maxConcurrent 控制（默认 2，范围 1..2）。

额度与开关（辅助）¶

插件维护冻结开关文件（默认 ~/.dsh/dispatch.switch.json）和额度台账（默认 ~/.dsh/dispatch-runs.jsonl，追加写）。缺省或损坏的开关文件视为开启。这些路径可用环境变量 ZCODE_CONNECT_SWITCH_PATH、ZCODE_CONNECT_LEDGER_PATH 覆盖。

安装与启用¶

前置条件¶

1. ZCode 已登录 Coding Plan
   在 ZCode 执行 /login bigmodel-coding-plan（OAuth 或手工粘贴 Key）。
   检查 ~/.zcode/v2/config.json → provider["builtin:bigmodel-coding-plan"]：enabled: true，options.apiKey 非 ey 开头的 JWT，options.baseURL 非空。

2. DSH 桌面端（Electron）正常运行
   插件从宿主 app.asar 内嵌 node_modules 解析 pi-ai / dsh-llm-pi-ai / dsh-llm。解析失败时设置 ZCODE_CONNECT_MODULES_ROOT 或 ZCODE_CONNECT_DSH_RESOURCES 后重启 DSH。

从 GitHub 安装（推荐）¶

Web 版 profile 将 --profile desktop 换成 --profile web。固定版本可加 git 标签，例如 #v0.4.0。

dsh plugin --profile desktop add github:Shuffle-1992/dsh-connect-zcode

安装完成后重启 DSH，模型选择器应出现 zcode 分组。

兼容性与离线自检¶

升级 DSH 前后可在插件目录执行：

node scripts/compat-check.mjs

末行 COMPAT PASS 且 exit 0 表示落在声明的 DSH / Node 区间内。仓库还提供：

node test/selfcheck.mjs

应输出 SELFCHECK PASS 且 exit 0。

配置要点¶

插件 config（cordis.patch.yml 或 profile 覆盖）常用键：

环境变量还可覆盖模块根目录与 DSH resources 路径，见 README「配置」一节。

凭据读不到时的常见原因¶

Coding Plan Key 可能出现在两处：

• ~/.zcode/v2/config.json → provider["builtin:bigmodel-coding-plan"].options.apiKey（明文）
• ~/.zcode/v2/credentials.json → 加密条目 enc:v1

OAuth 重新登录后，ZCode 可能只更新 credentials.json 而不回写 config.json，只读前者的工具会出现 401。此时确认 ZCode 侧登录状态，或按需指定 credentialPath / 让插件逻辑覆盖你实际使用的路径（以仓库故障排查文档为准）。

典型用法¶

1. 完成 ZCode Coding Plan 登录与 DSH 插件安装。
2. 在 DSH 模型选择器中选择 zcode 分组下的模型发起会话；请求由 DSH harness 发出，消耗 Coding Plan 额度。
3. 在插件设置面板勾选要显示的模型、200K 或 1M 上下文档，以及需要的推理/图片能力声明。
4. 长上下文边界探测（会消耗额度）可用仓库脚本 node scripts/probe-context-limit.mjs；零推理复核可用 node scripts/probe-context-declared.mjs（仅 GET /v1/models）。

认证方面，项目实测 Coding Plan 通道 x-api-key 单头即可，anthropic-version 非必需。

适用场景与注意¶

适合谁：已在 ZCode 购买或启用 Coding Plan，希望在 DSH 里统一用同一套工具、审批和团队流程，而不切换回 ZCode 自带 agent 的开发者。

权限与安全：插件以当前 DSH 进程权限运行，会从本机 ZCode 配置读取 API Key（不落盘到插件目录，但进程内仍会使用）。安装前建议阅读 GitHub 仓库 源码与 MIT 许可证，确认符合你的合规要求。

生态说明：DSH 社区插件目录（如 SkillHub 条目）由社区维护，与 DeepSeek / 幻方无官方从属关系；安装命令以仓库 README 为准，勿凭插件名自行拼接 CLI。

版本与历史：Start Plan / 活动赠送额度的托管代发通道因接入不完整已于 2026-10-17 从代码中移除；当前仓库只保留 Coding Plan 的 provider 通道。用户线索里若仍写「两种套餐」，以 README 当前描述为准。

结尾¶

dsh-connect-zcode 解决的是「额度在 ZCode、执行在 DSH」的接线问题：一条 dsh plugin ... add github:Shuffle-1992/dsh-connect-zcode，配合 ZCode 本地 Coding Plan 登录，即可在 DSH 模型列表中使用 zcode provider。

• 目录页：https://www.skillhub.cn/plugins/Shuffle-1992/dsh-connect-zcode
• 源码与文档：https://github.com/Shuffle-1992/dsh-connect-zcode