TaylorSwitiger/dsh-plan-bridge

dsh-plan-bridge

一个 DeepSeek Harness（dsh）插件，通过一个本地回环进程，将现有的厂商订阅套餐——ChatGPT
Codex（Plus/Pro）、Claude Code（Pro/Max）、ZCode（BigModel GLM Coding Plan）、Qwen（阿里云
百炼 Token Plan）——桥接进 dsh 模型分组。设置页状态卡片、一键接入、无需改动 dsh 核心、零运行时 npm 依赖。
中文文档如下。

dsh 的多套餐桥接插件。一个本地进程监听 127.0.0.1:8417，按路径前缀分流，同时承载多家订阅套餐；
每家套餐在 dsh 里是独立的模型分组，是否接入由你在设置页决定。

dsh (llm-pi-ai 多 provider 路由)
├─ codex-plan  → http://127.0.0.1:8417/codex/v1
├─ claude-plan → http://127.0.0.1:8417/claude
├─ zcode-plan  → http://127.0.0.1:8417/zcode/v1
└─ qwen-plan   → http://127.0.0.1:8417/qwen/v1
│
├─ codex  OAuth：读 ~/.codex/auth.json，续期写回，转发 ChatGPT codex 后端
├─ claude OAuth：读 ~/.claude/.credentials.json，续期写回，转发 api.anthropic.com
├─ zcode  API-key：转发 open.bigmodel.cn coding 端点
└─ qwen   API-key：转发百炼 token-plan 端点

套餐分两类。OAuth 型（codex、claude）复用厂商 CLI 自己的凭据文件，token 快过期时自动续期并写回原文件，CLI 和桥接共享同一份登录态。API-key 型（zcode、qwen）的 key 存在 dsh 凭据库里，桥接只转发请求和 Authorization 头：key 不进入桥接进程，也不落在插件自己的任何文件里。

桥接不代做登录。OAuth 套餐要求先跑过厂商 CLI 的 login；API-key 套餐要求 dsh 凭据库里已有 key。检测不到凭据的套餐在卡片上显示「不可用」并附凭据指引。

安装

dsh plugin --profile  add -w @taylorswitiger/dsh-plan-bridge
或直接从 GitHub / 本地目录
dsh plugin --profile  add -w https://github.com/TaylorSwitiger/dsh-plan-bridge
dsh plugin --profile  add -w file:/path/to/dsh-plan-bridge

装完重启 host。桥接默认监听 127.0.0.1:8417，可用插件配置 host / port 覆盖。上游需要代理时，给 host 进程设 NODE_USE_ENV_PROXY=1 和 HTTPS_PROXY（桥接走 Node 自带的 env-proxy 出网）。

设置页卡片

设置 → 套餐接入，每套餐一行，接入与否由该行按钮决定，没有自动接入。

| 状态 | 含义 | 按钮 |
|---|---|---|
| 服务中 | 已接入且本机凭据可用 | 停用、重新检测 |
| 另一实例服务中 | 同上，但 8417 被另一个 host 实例持有 | 停用、重新检测 |
| 未接入 | 凭据在，provider 段还没写 | 一键接入、重新检测 |
| 需先登录厂商 CLI | OAuth 凭据文件缺失，附 login 命令指引 | 重新检测 |
| 不可用 | 本机没有该套餐的凭据，附添加指引 | 重新检测 |
| 错误 | 桥接监听失败 | 重新检测 |

OAuth 型行内显示账号掩码（如 use@example.com）、subscriptionType、token 过期时间；API-key 型显示「API key 凭据已配置」。遇到 429 时该行显示额度重置时间，上游错误体里带重置时间戳的（codex、claude）会给出具体时刻，其余只透出错误文本。

停用会从 settings.yaml 移除该套餐的 provider 段，模型目录立即失去该分组，凭据保留不动；再点一键接入随时恢复。该套餐若正被 agent-default-model 指向，停用会被拒绝，先切默认。

一键接入做了什么

provision（卡片按钮或 RPC）幂等地做三件事：

1. 校验本机凭据。缺失时返回结构化错误（cli-login-required 或 credential-missing），卡片显示对应指引。
2. 通过 dsh 的 settings 服务写 llm-pi-ai.providers. 段。已有且一致则跳过；不一致返回字段 diff，需要你在卡片上确认后才覆盖。baseURL 按适配器接受的路径拼写归一比较，等价的写法不算差异。
3. OAuth 型经 credentials 服务补一个占位凭据（桥接不校验值）；API-key 型不写任何凭据。

接入不改变 agent-default-model。

RPC 端点

渠道 /dsh-plan-bridge（loopback）：

plans.list        {}                    卡片首屏
plan.status       {planId}              单套餐详情
provision.begin   {planId, overwrite?}  接入
provision.disable {planId}              停用

HTTP 直测（method 须与 URL 末段一致）：

curl -s http://127.0.0.1:3080/dsh-plan-bridge/plans.list \
-H 'content-type: application/json' \
-d '{"type":"client-request","rpcId":"1","method":"plans.list","payload":{}}'

桥接健康检查：GET http://127.0.0.1:8417/health，单套餐 GET //health。

内置套餐

| planId | providerKey | 类型 | 凭据 | 模型 |
|---|---|---|---|---|
| codex | codex-plan | OAuth | ~/.codex/auth.json | gpt-5.6-sol |
| claude | claude-plan | OAuth | ~/.claude/.credentials.json | claude-opus-5 / sonnet-5 / haiku-4-5 |
| zcode | zcode-plan | API-key | ZAI_CODING_PLAN_API_KEY | glm-5.3 / 5.3-flash / 5.2 / 5-turbo / 5.1 / 4.7 |
| qwen | qwen-plan | API-key | QWEN_TOKEN_PLAN_CN_API_KEY | qwen3.7 / 3.6 系及 deepseek、kimi、glm、minimax 共 15 个 |

已知问题：

- claude 标 beta：转发链路完整可用，但 Apple / App Store 渠道订阅的账号会被 Anthropic 组织策略拒绝（403 oauth_not_allowed_for_organization），网页直付账号不受影响。卡片对该错误有专门的解释文案。
- qwen 标 beta：端点与模型目录取自 pi-ai 的 qwen-token-plan-cn catalog，上游转发未经真实 key 验证；添加 key 后即可使用。
- zcode、qwen 走的是套餐专用网关（open.bigmodel.cn/api/coding、token-plan..maas.aliyuncs.com），用量计入套餐额度，不扣按量余额。

新增一个适配器

框架只管端口、路径分流、生命周期和状态聚合，厂商细节全在适配器里。加一家套餐 = 一个适配器文件 + 注册表一行，路由、卡片行、provision、状态端点自动生效。

OAuth 型适配器导出如下结构的对象（参考实现见 codex.js）：

export const fooAdapter = {
id: 'foo',                    // 路径前缀 /foo/v1 的来源；planId
providerKey: 'foo-plan',      // provision 写入 settings.yaml 的 providers 键名
displayName: 'Foo 套餐',
protocol: 'openai-responses', // llm-pi-ai 的 api 名
apiKeyEnv: 'FOO_PLAN_BRIDGE_KEY',
authKind: 'oauth',            // 'oauth' | 'api-key'
basePath: '/foo/v1',
settingsPath: '/foo',         // 写进 baseURL 的路径，取决于 SDK 是否自己追加 /v1
acceptedBasePaths: ['/foo', '/foo/v1'],
cli: { name: 'Foo CLI', loginCommand: 'foo login', installHint: 'npm i -g foo',
credentialHint: 'dsh 设置 → 凭据 → 添加 FOO_KEY' },
models: [/ { id, name, contextWindow, maxTokens, reasoningEfforts?, input? } /],
profileExtras: {},            // 并入 provider 段的额外字段，如 compat
beta: false,

detectAuth() {                // 探测本机可用性，可异步；api-key 型查 dsh 凭据服务
return { ok, accountMasked?, expiresAt?, reason? }
// reason 'cli-login-required' → 卡片「需先登录厂商 CLI」
// reason 'credential-missing'  → 卡片「不可用」
},
async forward({ subpath, request, response, log }) {},
parseUpstreamError(status, text, headers) {},  // → { type, resetsAt?, detail? } | null
status() { return { accountMasked?, accessTokenExpiresAt?, lastUpstreamError, note? } },
}

API-key 型不必手写，lib/adapters/apikey-plan.js 的工厂一份 spec 换一个完整适配器（凭据探测、Authorization 透传、上游错误缓存都内置）：

export const fooAdapter = apiKeyPlanAdapter({
id: 'foo', providerKey: 'foo-plan', displayName: 'Foo 套餐',
apiKeyEnv: 'FOO_KEY', upstreamBase: 'https://vendor.example/v4',
cli: { name: 'Foo', credentialHint: 'dsh 设置 → 凭据 → 添加 FOO_KEY' },
models: [/ … /],
})

注册（lib/adapters/index.js）：

export const adapters = [codexAdapter, claudeAdapter, zcodeAdapter, qwenAdapter, fooAdapter]

然后 pnpm run check，重新装到 profile，重启 host。
上游端点和模型元数据优先从 pi-ai 的内置 catalog 抄（zai-coding-cn、qwen-token-plan-cn 等），与 dsh 原生路由同源，contextWindow、maxTokens、input 模态都有现成数据。

兼容性

- 不修改 dsh 本体的任何文件，只用公开插件 API：Connection RPC、settings / credentials 服务、settings 插槽。
- 凭据写入全部走 credentials 服务，保持 ~/.dsh/.credentials.yaml 的 version 1 + refs 格式。
- agent-default-model 只能由用户改动，插件的任何端点都不碰它。

设计说明

改代码前值得知道的几件事：

1. 客户端一侧是手写的 module-table bundle（window.__ModuleLoader__.load），react 通过工厂函数的 require('react') 拿宿主共享的实例。因此不需要打包器，pnpm run check 只做解析和打包契约校验；代价是不能用 JSX 和打包期优化。
2. 所有 RPC 端点统一返回 {ok, value} / {ok, error} 结构。曾有端点漏包 value，客户端解包得到 undefined，渲染时导致整个设置分区渲染失败。加端点时保持返回结构一致，客户端的 unwrap 也要对「ok 但缺 value」抛出带错误码的异常。
3. settings 写入再读回会补上空默认值（model 的 input: []、compat: {chatTemplateKwargs:{}}），幂等比较前必须先归一（util.js 的 normalizeForDiff），否则自己刚写的配置会被误报成冲突。
4. 凭据事实与端口持有是两个维度。缺 key、缺登录是机器级事实，闲置实例（8417 被别的 host 持有）也要如实报「不可用」/「需登录」，状态计算先按凭据归类，再看端口。
5. Claude 订阅调用所需请求头与普通 API key 调用不同：OAuth Bearer 之外还需 anthropic-beta: claude-code-20250219,oauth-2025-04-20（与调用方自带值合并）、Claude Code 身份的系统提示首块、anthropic-version: 2023-06-01。token 在 platform.claude.com/v1/oauth2/token 续期，refresh grant 会轮换 refresh_token，写回时保留响应省略的字段。oauth 拒绝码在 error.details.error_code，不在 message 里。
6. codex 的 token 过期时间单位是 epoch 秒，claude 的是毫秒，状态聚合层统一归一成秒。
7. 调试：host 进程设 DSH_PLAN_BRIDGE_DEBUG=，适配器把每个请求和上游错误首段追加写入该文件。

License

MIT