前言¶
在 DeepSeek Harness（DSH）里接第三方模型，常见做法是单独配置 provider、填 API Key 或走一套 OAuth。若你已经在 opencode 里通过 CANNWork（cannbot-toolkit 扩展）登录过 CANNBOT 网关，网关侧实际需要 Virtual Key（VK）与 JWT 同时出现在请求里，缺一就会 401。再为 DSH 重复登录或手抄凭据，既容易过期不同步，也增加密钥散落面。
下面介绍维护者 gentle-knight 的插件 dsh-cannbot-connect：把 CANNBOT 网关模型注册进 DSH，从本机 CANNWork 已写入的文件读取 VK 与 JWT，在每次 LLM 请求里自动带上，不另起 OAuth、不需要在插件里填 key。仓库声明 MIT 许可，当前版本 0.2.1；GitHub 镜像见文末链接，安装命令以 README 为准（clone 源为 gitcode.com）。
这是什么¶
dsh-cannbot-connect 是一个 first-class LlmAdapter 插件：用 fetch 与 SSE 直接对接 CANNBOT 的 OpenAI 兼容网关（默认 https://cannbot.hicann.cn/gateway/compatible-mode/v1），零运行时依赖。它不做凭据签发，只消费 CANNWork 维护的本机文件；DSH 侧每次请求现读磁盘，CANNWork 刷新令牌后下一个 DSH 请求即可生效，无需重启 DSH。
网关实测行为（README 归纳）：
| 请求携带 | 网关响应 |
|---|---|
| 只带 VK | 401，提示需要 Access Token |
| 只带 JWT | 401，提示需要 Virtual Key |
| VK + JWT | 200，正常返回 |
核心功能¶
凭据来源与查找顺序¶
插件按顺序自适应 opencode 的数据目录与配置目录（兼容不同版本 CANNWork/opencode 的落盘位置）：
- 数据目录：
$XDG_DATA_HOME/opencode（默认~/.local/share/opencode） - 配置目录：
$XDG_CONFIG_HOME/opencode（默认~/.config/opencode）
| 凭据 | 文件 | 字段 | 维护方 |
|---|---|---|---|
| JWT | session.json |
accessToken |
CANNWork，约 24h 有效并自动刷新 |
| VK | auth.json |
cannbot.key |
CANNWork |
JWT 先查数据目录的 session.json，再查配置目录。VK 在两处 auth.json 中按 cannbot.key 查找；旧版 opencode 可能把 vk- 前缀的值放在 cannbot-cli.refresh，插件仅接受 vk- 开头作为兜底，避免误把刷新令牌当 VK 发出。
DSH 侧行为¶
- 接入点：
ctx.llm.registerAdapter(['cannbot'], adapter)。 - 模型目录：用 JWT 请求个人模型列表；内置兜底模型先挂载，catalog 拉取成功后替换；对
builtinModels与personalModels按「personal 优先」去重，避免 DSH 因重复 id 报INVALID_CATALOG。 - 对话能力：支持文本与推理档位（
minimal/low/medium/high/max/xhigh；网关不接受reasoning_effort=off）；assistant 历史中的reasoning_content与tool_calls/tool_call_id多轮往返已按 README 说明实现。 - 输入限制：对外只声明文本输入；图片/文件块会被明确拒绝。
- 错误映射：失败归类到 DSH 错误体系（如
AUTH、RATE_LIMIT、SERVER等），并按Retry-After回填providerRetryAfterMs。
安全相关（仓库已说明）¶
baseURL/modelsURL默认必须https（回环地址允许http）；请求带redirect: 'error'，不跟随重定向。- 错误正文对 JWT/VK 做脱敏；凭据经校验后再写入 HTTP 头；插件只读凭据文件、不写盘。仓库不含密钥，VK/JWT 均来自运行时本机文件。
前置条件¶
- 已安装 CANNWork 并成功登录。未登录时插件仍会注册但不可用；可先确认某处
session.json存在accessToken。 - DSH 内核：
>=0.2.1-rc.2且<0.3.0（engines.dsh与peerDependencies中@deepseek-ai/dsh-llm区间需同时满足）。 - Node.js：
^22.19.0 || >=24.0.0。 - 网络可访问
cannbot.hicann.cn。
安装与启用¶
插件无运行时依赖，README 给出的安装步骤如下。clone 完成后用本地路径加入 profile：
git clone https://gitcode.com/gentle-knight/dsh-cannbot-connect.git
dsh plugin --profile desktop add file:$(pwd)/dsh-cannbot-connect
然后重启 DSH，模型选择器中应出现 CANNBOT 分组。
若 CLI 对 desktop profile 报 EPERM（部分发行版不允许独立 CLI 写 App 管理的 ~/.dsh/profiles/desktop），可改用 Web/TUI profile，或按 README §7 在 profile 的 package.json 与 cordis.patch.yml 中手动挂载；仓库自带 cordis.patch.yml，bundle 安装时会通过 dsh.bundle.patch 生效。可选配置示例：
- id: llm-cannbot
name: dsh-cannbot-connect
config:
baseURL: https://cannbot.hicann.cn/gateway/compatible-mode/v1
streamIdleTimeoutMs: 300000
验证与典型用法¶
开发期验证需安装 dev 依赖后运行 e2e（使用真实本机凭据与网关）：
npm install
node e2e.mjs
成功时 README 示例会打印 jwt: present、vk : present、可用模型数量，以及文本回合、工具调用与工具结果回放等 ok 行，并以 PASS: CANNBOT is reachable through the DSH LLM seam. 结束。常见失败：jwt: MISSING 表示未登录 CANNWork；catalog 未加载可能为 JWT 过期，需重开 CANNWork 后再试。
离线安全回归（无需 CANNBOT 登录）：
npm test
适用场景与注意¶
适合：已在 opencode 使用 CANNWork、希望在 DSH 同一账号可见模型 roster 下直接选 CANNBOT 分组，且接受网关仅文本输入与固定推理档位集合的用户。
务必知晓：
- 插件以当前 DSH 进程权限运行，会读取 opencode 凭据文件并向配置的
baseURL/modelsURL发送 JWT 与 VK；安装前应阅读源码与 MIT 许可证，确认可接受凭据复用范围。 - 强依赖 CANNWork 续期 JWT；DSH 侧不缓存凭据文件内容，但令牌过期后请求会失败，需依赖 CANNWork 恢复登录态。
- 换账号后重新请求即可反映新模型列表，无需重启；升级 DSH 内核后若兼容性判定变化，请对照
engines.dsh区间并重跑node e2e.mjs。 - DSH 插件目录为社区站点 SkillHub 插件页 与 awesome-dsh-plugins 等生态索引，与 DeepSeek / 幻方无官方从属关系；本文事实来自仓库 README 与
package.json。
链接¶
- 目录页：https://www.skillhub.cn/plugins/gentle-knight/dsh-cannbot-connect
- GitHub：https://github.com/gentle-knight/dsh-cannbot-connect
- 安装用仓库（README clone 地址）：https://gitcode.com/gentle-knight/dsh-cannbot-connect.git
经过上面的步骤，DSH 可在不重复配置 OAuth 或 API Key 的前提下，与 CANNWork 共用同一套 CANNBOT 网关凭据，在 harness 内直接选用网关模型。
