WorkBuddy 本地 API 桥

🌏 English summary: README.en.md

把本机 WorkBuddy 的模型能力（DeepSeek / GLM / Kimi / MiniMax 等）， 经一个本地桥变成本机的 OpenAI 兼容、Anthropic 兼容与 OpenAI Responses 三套接口 —— Claude Code、Codex、opencode、Cursor、Trae、 Cherry Studio、NextChat、LobeChat、Open WebUI 等任何支持自定义 Base URL 的客户端都能直连。

凭据有两种来源：已登录的 WorkBuddy 桌面端，或者 dsh 插件里的「插件登录」—— 没装过桌面端也能用，只需在浏览器完成一次授权（凭据由插件加密保管：Windows 用 DPAPI，其他平台用文件密钥）。

另附一个网页控制台（状态 / 启停 / 诊断 / 模型注册 / 用量 / 体检 / 对话测试）， 中 / 英双语（右上角切换，选择记在本机）， 以及一个可选的 DeepSeek Harness（dsh）原生插件（见下方说明）。

一句话：WorkBuddy 的模型额度 → 本地 API → 你惯用的任意 AI 客户端。

关键词（便于检索，按关心的问题分组）：

在 DeepSeek Harness（dsh） 里用上 WorkBuddy 的模型，本仓库提供的是 原生 dsh 插件 + 本地 API 桥 + 可视化控制台的完整组合 —— 装完模型直接出现在 dsh 的模型选择器里，日常需要的接入、管理、监控、运维能力也全在同一个插件内。

• 没装桌面端也能用：插件内设备码登录，不下载、不安装 WorkBuddy 客户端。
• 装了桌面端更省事：已登录的账号自动复用，第 2 步都可以跳过。
• 不填任何东西：不需要 API Key、Base URL、令牌、端口或环境变量；桥由插件自动拉起，控制台在第一次打开数据页时按需拉起。
• 国内 / 国际版自动预选：登录区域跟随现有账号或桌面端域名，不用每次手动切。
• 模型选择器即时刷新：登录、切号、重启桥后自动广播目录更新，不需要重启 dsh。
• 聊天页闭环：未登录时空会话里直接「连接 WorkBuddy」；已有对话遇到凭据失效时，顶部胶囊位会变成登录入口。对话页顶部常驻「积分 N」（悬停看套餐余量 / 今日已用 / 最近一次，点一下刷新）；每轮回复末尾显示本轮积分（优先按本轮 tokens 与本地账本核对）。 7 天内有积分到期时，胶囊会变黄（≤1 天变红），悬停可看到期明细；概览积分卡也会出现可关闭的到期提醒。
• 限流看得见：账号页显示当前账号的额度上限/账号风控（带恢复时刻）；模型页给被限流/繁忙/排队的模型加标记；请求页可「仅看需要处理」，失败悬停直接给下一步建议。
• 模型名自带倍率：选择器/聊天顶部直接显示 DeepSeek-V4.1-Flash · ×0.11，免费模型标「免费」，不用再翻模型详情。
• 凭据不裸奔：DPAPI / 文件密钥 + AES-GCM 加密保存；同一账号的桌面/插件双凭据自动合并，401/403 自动接管。

×0.11 是积分消耗倍率，不是人民币单价；免费模型直接标「免费」。 积分胶囊、登录入口、每轮成本都在 dsh 对话页；完整用量曲线、请求明细和 CSV 仍在设置页的「用量 / 请求」里。

能力清单：

在 dsh 里直接装：设置 → 插件 → 添加插件，填

github:Ianzhyh/workbuddy-to-dsh

安装源保持默认即可（GitHub 地址由 pnpm 直接拉取，国内镜像只影响 npm 依赖）。 也可以走命令行（安装路线、验收清单与故障排查见 docs/INSTALL.md）：

dsh plugin --profile desktop add github:Ianzhyh/workbuddy-to-dsh

npm 包名 workbuddy-to-dsh 已按可发布形态准备好；发布后「添加插件」里直接填 workbuddy-to-dsh 即可（npm 名 dsh-plugin-workbuddy 已被他人占用，不要填它）。

装完重启一次 dsh，模型选择器里直接多出 WorkBuddy。

插件登录需要 v1.8.0 或更高版本。从 dsh 市场安装时请确认上架版本； 旧版（≤1.7.0）仍要求 WorkBuddy 桌面端登录态。

⚠️ 请先读这一段（免责与边界）

这是一个自托管的开源工具：欢迎自用、欢迎分享源码，但它是非官方路径，风险自担。

• 非官方路径。 它依赖 WorkBuddy 未公开的上游协议与登录凭据格式（插件登录 不需要桌面端，但同样走非官方设备码接口）。上游随时可能改动协议或收紧风控 （已经发生过——见故障排查里的真实案例），可用性 无任何保证，且不承诺任何兼容性。把它当作「随时可能需要更新甚至失效的 互操作性实现」，而不是稳定服务。
• 只驱动你自己的账号。 它只读取你自己机器上已登录的桌面账号，或你在插件里 明确授权的那一个插件账号，消耗该账号自身的配额。请勿用它做多账号池化、 代他人调用、或任何形式的转售 / 托管服务 —— 那既违背本项目的设计初衷，也最容易 触发上游风控（殃及所有用户）。
• 请确认你符合 WorkBuddy 的服务条款。 使用前请自行阅读并确认；若条款不允许， 请不要使用本项目。
• 无担保。 按 MIT 许可"按现状"提供。作者不对账号风控、额度异常或任何损失负责。 若你需要长期稳定、可商用的模型接入，请申请官方 API。
• 自担风险的分享是欢迎的：转发仓库链接、写教程、提 PR 都可以；但请不要 打包转售、绑定付费，或以本项目名义收集任何人的凭据。

兼容性分档见 docs/COMPATIBILITY.md；上游失效/项目停更时 怎么退回官方客户端、数据在哪，见 docs/SUNSET.md。安全报告方式见 .github/SECURITY.md。

• 方向与 claude-code-router 相反： CCR 把别家的 API 注入 Claude Code；本项目把 Claude Code 等发给 WorkBuddy 的 模型额度导出成标准 API——两者互补而非竞争。
• 与 WorkBuddy2API 集群（社区 20+ 同目标项目）的差异：本项目刻意保持 单账号 · 不落明文凭据 · 零运行时依赖 · 自包含（桌面凭据现取现解； 插件登录凭据以 DPAPI / 文件密钥 + AES-GCM 加密保存）；默认不提供多账号池化与 任务自动化——如果你的需求是后者，社区里已有更对口的工具。限流自动切号是显式 opt-in 的本机自有账号切换（默认关闭，见插件配置），不导出凭据、不做公网中转， 也不代表支持池化或转售。
• 上游协议是未公开接口：所有同类项目都在同一片雷区里，失效与修复是常态。 本项目的对策是把排查写清楚（症状、证据、处置）， 而不是承诺稳定。

• 详细的风险与边界见 注意事项 与 docs/SECURITY.md。

本仓库还提供一个 DeepSeek Harness 原生插件（dsh-plugin/）： 装进 dsh 后，模型选择器里直接多出 provider WorkBuddy，设置里多一页 9 个标签页的数据面板； 插件自带桥与控制台，拷一个文件夹就能用。它是可选的 —— 不用 dsh 的话， 前面说的本地 API 照常可用，只是没有那个原生集成。

只在本机回环地址上工作，不对外暴露，不内置任何密钥。

# ── 第 1 步：跑起来（所有用法都需要，与 dsh 无关）──────────────────────
git clone https://github.com/Ianzhyh/workbuddy-to-dsh.git
cd workbuddy-to-dsh
# Windows：双击 启动.cmd —— 桥和控制台都会自动起来，不需要 npm install
# macOS / Linux：bash scripts/start.sh

# 或者只要桥、不开控制台：
bridge\start-bridge.cmd        # Windows
bash bridge/start-bridge.sh    # macOS / Linux

跑起来后，去控制台「客户端接入」页签拿 Base URL 与令牌填进你的客户端 （见 接入你的客户端）。到这里就已经能用了。

# ── 第 2 步（可选）：再装进 DeepSeek Harness ──────────────────────────
# 只有用 dsh 的人需要。三种方式装的是同一个插件，任选一种。

# 方式一：一条命令直装（v1.1.0 起，仓库根已声明 dsh.bundle）
dsh plugin --profile desktop add github:Ianzhyh/workbuddy-to-dsh

# 方式二：release 附件（tgz 安装包，无构建、无需 allowBuilds 授权）
#   从 GitHub Releases 下载 dsh-plugin-workbuddy-<版本>.tgz 后：
dsh plugin --profile desktop add ./dsh-plugin-workbuddy-1.23.0.tgz

# 方式三：从源码（插件在 dsh-plugin/ 子目录，接第 1 步的 git clone）
dsh plugin --profile desktop add workbuddy-to-dsh/dsh-plugin
# 装完重启一次 dsh；之后：设置 → WorkBuddy

三种方式装的是同一个插件。方式一/二由 npm 装仓库根包（Loader 行 name = workbuddy-to-dsh，对应根目录的 cordis.patch.yml）；方式三按子目录安装 （name = dsh-plugin-workbuddy，对应 dsh-plugin/cordis.patch.yml）。 两份 patch 除 name 外完全一致，改动时需同步。

插件是自带一切的独立包（npm run vendor 生成的 vendor/ 里含桥与控制台）， 可以直接把 dsh-plugin/ 文件夹拷给别人，对方不需要本仓库。 安装路线、验收清单与九条故障排查见 docs/INSTALL.md。

WorkBuddy 的上游后端本身就讲 OpenAI 协议，官方只是没有开放公开入口，鉴权依赖桌面端 的登录会话。所以就协议层面而言，只需要一个薄薄的转发层。

真正的工程难点在于从 WorkBuddy 5.6.0 起，官方开启了 AtRest 加密：登录文件里的 accessToken / refreshToken 从明文 JWT 变成了 AES-256-GCM 信封，而解密密钥不落盘、 只存在于客户端进程内。这让所有在进程外读取该文件的既有工具全部失效。

本项目的做法是请客户端自己完成解密：以 ELECTRON_RUN_AS_NODE=1 运行 WorkBuddy.exe，调用它自己的原生绑定 loggerGet()，由客户端交出它本来就在用的 那把密钥。没有任何密钥被写进代码或磁盘，登录文件也始终只读。

没装桌面端时走另一条路：插件的「插件登录」用设备码在浏览器完成授权，桥直接使用 插件自己保管的凭据（Windows 用 DPAPI、其他平台用文件密钥保护密钥，AES-GCM 信封；不依赖桌面端进程）。

这里刻意不做「破解」：不逆向密钥派生、不硬编码密钥、不改写登录文件。 密钥始终由客户端进程提供，本项目只是把它的结果用起来 —— 这也是它能长期跟上 客户端版本变化的原因。实现细节见 lib/atrest.mjs。

复用桌面端登录态目前只支持 Windows：解密的密钥不在本包里，每次由 WorkBuddy 客户端 自己的 Electron 原生绑定现取，这条路只在 Windows 上验过。插件包虽然声明了 os: ["win32"]， 但那个字段只对 npm 生效（npm install 会报 EBADPLATFORM）；dsh 的插件安装走它自带的 pnpm，pnpm 不检查 os（实测 11.7.0）—— 所以非 Windows 上装是装得上的， 只是大概率卡在「读不出登录凭据」。

插件登录不依赖这个二进制。Windows 用 DPAPI 加密落盘；macOS / Linux 默认用 文件密钥 + AES-GCM 落盘（桥重启、更新插件都不需要重登）。容器部署请把 WORKBUDDY_CREDENTIAL_DIR 挂到持久卷，并建议设置 WORKBUDDY_CREDENTIAL_KEY （密钥不落盘）。这条路径尚未实机验证，要试请按实验对待。

桥只驱动本机已登录的账号，不绕过任何鉴权，也不提供任何绕过方式。

Windows：双击根目录的 启动.cmd。macOS / Linux：bash scripts/start.sh。就这一步。

它会自动定位 Node.js、启动服务、并在浏览器里打开控制台——桥也会被自动拉起， 不需要任何手工操作。打开后即可看到桥已就绪和完整的模型列表。

首次使用：桥起来之后，去「客户端接入」页签拿到 Base URL 与令牌，填进你的客户端即可 —— 见下方接入你的客户端。 若用 DeepSeek Harness，另外在「可用模型」里勾选所需模型并点「保存到 dsh 设置」， 再重启一次 dsh，模型就会出现在它的选择器里。

三个"不需要"：

• 不需要 npm install —— 本项目零依赖
• 不需要改配置 —— 所有项都有合理默认值，.env 是可选的
• 不需要手工启动桥 —— 控制台会自动启动它（并复用已在运行的实例）

窗口保持打开即可。关掉窗口会停止控制台；桥在后台继续驻留，下次启动直接复用。

不想开控制台也可以（用的是同一套配置）：

# 只起桥：
bridge\start-bridge.cmd        # Windows
bash bridge/start-bridge.sh    # macOS / Linux

# 命令行自检 / 备份：
node tools/doctor.mjs
node tools/backup.mjs          # --restore <目录> --yes 恢复

不想照着文档一步步来？把下面这段话整段粘给任意 AI Agent（WorkBuddy 对话、 Claude Code、opencode…），它会替你完成判定 → 安装 → 验证，出错时自己查排错文档：

请帮我在本机安装并验证 workbuddy-to-dsh（WorkBuddy 本地 API 桥）。步骤：

1. 环境判定：确认 Node.js 18+（node -v）。凭据二选一：WorkBuddy 桌面端已安装并
   登录过（Windows 下检查 %LOCALAPPDATA%\CodeBuddyExtension\Data\Public\auth\ 里
   是否有 .info 登录文件）；或者没装桌面端，稍后在 dsh 插件里用「插件登录」。
2. 获取代码：git clone https://github.com/Ianzhyh/workbuddy-to-dsh 并进入目录。
   本项目零依赖，不需要 npm install。
3. 启动：Windows 双击根目录的 启动.cmd（或 node dashboard/server.mjs）——它会自动
   启动桥并打开控制台（http://127.0.0.1:8792）。
4. 验证：运行 node tools/doctor.mjs 自检全部通过；再请求模型目录（令牌见下）：
   curl -H "Authorization: Bearer <本地令牌>" http://127.0.0.1:8790/v1/models
   确认返回模型列表。
5. 若我是 DeepSeek Harness 用户：改用 dsh plugin add github:Ianzhyh/workbuddy-to-dsh
   直装插件，然后在 dsh 设置页的 WorkBuddy 分区完成模型注册并重启 dsh；
   没有桌面端就在「账号」页点「开始登录」，完成浏览器授权。
6. 遇到问题先读 docs/TROUBLESHOOTING.md，按里面的处置试过再带报错来问我。
全程只允许 127.0.0.1 本机回环，不要尝试改绑 0.0.0.0 或暴露到局域网。

桥同时讲三套协议，填哪个地址取决于客户端讲哪套：

Codex 为什么不能只改 Base URL？ 它说的是 Responses 协议，而桥的 /v1 那套 是 chat/completions；两者的事件流与请求体都不同，所以桥里做了一层真正的协议转换 （CC Switch 靠一个本地路由进程做的事，这里内置了，不用再装中间人）。 注意网上仍在流传 wire_api = "chat"，上游已经把它移除，照抄会直接报错 —— "responses" 是现在唯一还能用的值。

不想手抄配置？控制台面板最上面有「一键接入」：它检测本机装了哪些客户端 （Codex / Claude Code / opencode），把 Base URL 与令牌直接写进它们的配置文件 —— 只动它自己的键（cc-switch 写过的节一字不动）、写入前整份备份、支持一键撤销、 写完拿配置里的令牌真打一次桥验证。不想开控制台也可以用命令行：

npm run connect status          :: 三个客户端各自的状态与将要改动什么
npm run connect apply codex     :: 写入（codex / claude / opencode）
npm run connect apply codex --models glm-5.3,kimi-k3-1   :: 一次接多个模型
npm run connect verify codex    :: 静态读回 + 端到端验证
npm run connect undo codex      :: 撤销

多模型：勾选几个就接几个，其中一个作为主模型（客户端打开时用的那个）。 改完勾选要点一次「重新写入」才会进客户端（勾选只改面板状态，不碰你的配置文件）； 写完之后那行显示的个数会跟着真正写进去的那批走，两边不一致时不会互相遮掩。 三个客户端的机制不同，写进去的形状也不同 —— 但都是客户端自己认的写法：

Codex 的目录是合并的：model_catalog_json 已经指向别人的目录时（cc-switch 就是 常见的一种），原条目一条不动，只补桥这边缺的；撤销连那份文件一起还原。 本机找不到可用的目录模板时不生成，界面会直说"只能接一个模型"，不硬编造。

opencode 的配置文件名：官方同时认 opencode.json 与 opencode.jsonc （JSON with Comments）。我们挑你已有的那个改 —— 你那份叫 .jsonc 就改 .jsonc， 不会在旁边多造一个 .json（按文档优先级那会盖住你自己的文件，把你写在里面的 设置顶掉）。两个都在时用 .json。 注意：JSON 这条路写入会重排成 2 空格缩进，.jsonc 里的注释会一并丢掉 （写入前整份备份、可撤销，界面也会提示"该文件会被重新排版"）。

不改我的配置（Codex 的 profile 通道）：如果你不想让接入动到 ~/.codex/config.toml， 可以用 profile 这条零写入的路 —— 它只写 $CODEX_HOME/workbuddy.config.toml， 你原来的配置一个字节都不动：

npm run connect profile codex            :: 只写 profile 文件，基础配置不动
codex -p workbuddy                       :: 用这个 profile 启动 Codex
npm run connect undo codex-profile       :: 不想要了就删掉（基础配置始终没被碰过）

面板里等价的操作：Codex 那一行 →「详情」→ 不改我的配置（可选） →「写入 profile 文件」。

依据是 Codex 自己的 -p/--profile（codex --help：Layer $CODEX_HOME/<name>.config.toml on top of the base user config）。因为基础配置没被碰过，这条路不需要备份/撤销/ 权限收紧那一整套安全网 —— 它是"便捷性与安全性同时更好"的那一档。

⚠️ 桌面应用不接受命令行开关（-p / -c 都是 CLI 的参数），所以这条通道只对命令行生效。 用桌面应用的话仍然走上面那条"写基础配置"的路。界面与命令行都会把这条限制写出来。

随时切回客户端自己的模型：面板里每个客户端的「详情」里有一个模式区块， 在「走桥」与「客户端自己的模型」之间来回切（命令行： npm run connect native codex / npm run connect bridge codex）。

切回原始模型会按记录把配置逐键还原成接入之前的样子（连注释与空行都在）， model_catalog_json 一并还原 —— 客户端打开时用的就是它自己原来那个模型， 模型选择器里也是它自己的清单。我们那份模型目录文件留在磁盘上但不被引用， 随时能一键切回来。切回原始模型不需要桥在跑（它只动配置文件）， 所以"桥挂了、我又不想用桥了"这种时候照样能用。

它与「撤销接入」的分工：撤销是拆掉（记录归档、我们建的目录文件删掉， 再想用桥得重新接入一遍），切模式是换挡（记录与目录都留着）。 一个客户端能同时被接入多次、来回切多少次，"撤销"还原的始终是最初那一份配置。

这块面板的纪律（都是"界面不说假话"的具体做法，踩过坑才有的）：

• 读不到状态就说读不到：接口 404 / 超时 / 返回形状不对时给出原因 + 「重试」， 绝不挂着一句「正在读取接入状态…」永远转圈（实测踩过：控制台进程还在跑改动前的 旧代码，/api/connect 回 404，面板从头到尾一个字都没渲染出来）；
• 「已接入」不是一个文件的存在性：配置被手改过、桥换过端口/令牌，标签会变成 「已接入，需重新写入」；反过来，你自己照片段抄进去的配置会被认成 「已接入（非本控制台写入）」。已接入的行可以随时点**「验证接入」**—— 静态读回 + 拿配置里的令牌真打一次桥，失败结论直接落在标签上 （「已接入，验证未通过」）；
• 「桥没起」与「桥在跑但不认这把令牌」分开说：前者去点「启动桥服务」， 后者去点「重启桥」。混成一句时用户会按错的按钮，然后卡住
• 写进去几个就显示几个：面板上的「N 个模型」不许自己念自己那份勾选状态。 写入成功后以服务端回报的实际集合为准（实测踩过：请求里漏发了勾选的那批模型， 服务端于是把旧的又写了一遍，界面却一直显示用户勾的 5 个 —— 面板永远停在 「需重新写入」，而用户没有任何办法看出差异，重启客户端多少次都一样）
• "还没写入的勾选"要留住：勾好但没点写入时刷新页面，不该回到配置文件里那批。 选择存在浏览器本地（只存模型 id，不存任何凭据），刷新后恢复，并且真的发给服务端 —— 只在界面上显示没用，预览与写入都得按它算 （见 TROUBLESHOOTING）；
• 布局按"一年看几次"排序：主路径只有三行客户端（状态 · 名称 · 路径 · 操作）， 说明、三个接入值、各家配置片段、兼容性清单都收进折叠区 —— 自己抄配置那条路照样完整，只是不再天天占着屏幕。

标了「本机未实测」的客户端：写入逻辑有往返单测，但本机没装它， 所以「它是否认这份配置」没法替你保证 —— 其余客户端仍走复制片段。

指定接入模型：一键接入默认为每个客户端写入桥对应的默认模型（Codex / Claude Code 用 glm-5.3，opencode 用精选集首个）。控制台面板里每个客户端都带一个「接入模型」下拉，写入前 可直接改；命令行用 --model：

node tools\connect.mjs apply codex --model glm-5.3

所选模型会写进各客户端配置（Codex config.toml 的 model、opencode 的 model、Claude Code 的 env.ANTHROPIC_MODEL），桥收到后精确命中目录即原样使用 —— 选什么就跑什么。写入前会校验该 id 在当前目录里，避免写错导致桥静默回退到别的模型。

本地令牌从哪来？ 首次启动时随机生成，控制台的「客户端接入」面板里直接显示并 可一键复制（页面上的值就是准的，不用去翻文件）。需要手动读时它在 <WORKBUDDY_DATA_DIR>/bridge-token（默认 %USERPROFILE%\.workbuddy-bridge\bridge-token）； 也可在 .env 里用 WORKBUDDY_LOCAL_TOKEN= 显式指定。

控制台的「客户端接入」页签里有每个客户端的完整配置片段，点一下即可复制。

兼容性分三档，如实标注、不夸大：

「协议兼容」= 这些客户端只用 /v1/models 与 /v1/chat/completions 两个端点， 桥侧已验证；但没有真的装一遍跑通，所以不写成「支持」。

Claude Code 的模型名会被映射。 它发的是 claude-sonnet-4-…，上游没有这些 id， 桥会映射到真实模型（默认 glm-5.3）。想指定就用 WORKBUDDY_ANTHROPIC_MODEL=<上游真实模型 id>； 走「一键接入」时会把你选的模型直接写进 settings.json 的 env.ANTHROPIC_MODEL，无需再设环境变量。 你显式指定的模型名不会被悄悄换成别的模型：上游目录里没有这个名字就直接报 404 （WORKBUDDY_SKIP_MODEL_PREFLIGHT=1 可放行给上游裁决）。

Claude Code 的上下文窗口怎么开。 它对不认识的模型 id 一律按 200K 假设窗口 （它不读 /v1/models），所以「一键接入」会额外写一行 env.CLAUDE_CODE_MAX_CONTEXT_TOKENS=<该模型的上限>（v2.1.193+ 认这个变量）； dsh 面板里按模型设的上下文窗口也会落到这一行。多模型接入时取所选模型的最小上限 （/model 切到小窗口模型后不会虚报）；目录冷启动、上限未知时不写这一行 —— 写任何数字都是猜。老版本 Claude Code 认不了这个变量， 可以给模型名加 [1m] 后缀（桥会剥掉后缀再匹配）。

已知限制：知识库 / RAG 用不了。 上游只提供对话模型，没有任何 embedding 模型， POST /v1/embeddings 会明确返回 501。需要 RAG 的客户端请另配一个 embedding 提供方——桥不做「假的向量」，那会让知识库看起来建成了、实际全是噪声。

本仓库同时提供 DeepSeek Harness 原生插件（dsh-plugin/）。 插件和「桥 + 网页控制台」是一套东西的两个前端，不是二选一 —— 用不用 dsh 都能用这个项目，只是装了插件多一层原生集成：

插件当引擎，控制台的全部功能搬进 dsh 设置页 —— 两个前端、一个后端。

设置页右上角有 EN / 中 语言开关，9 个标签页的界面文案全部双语 （与控制台同一套词条思路；上游数据保持原样不翻）：

插件在 dsh 里注册原生模型路由、把桥和控制台都管起来（已在跑就复用，没跑就拉起）； 设置 → WorkBuddy 里有 9 个标签页：概览 / 账号 / 用量 / 请求 / 签到 / 诊断 / 模型 / 对话测试 / 日志， 与控制台网页共享同一个桥、同一份 .state.json（账号切换等写操作由插件透传给控制台执行， 保证只有它写），在任意一边改，另一边同步变化。按模型编辑输入/输出 Token 是插件面板 额外提供的能力，控制台网页只读展示；原控制台照常可用。

资源占用：桥常驻约 130MB。控制台另占约 80MB，但默认不随 dsh 启动： 第一次打开面板的数据页或执行 workbuddy console 时按需拉起，闲置 10 分钟自动 退出（页面打开期间会被轮询保活）。想常驻：consoleAutoStart: true；想让按需 拉起的实例不自动回收：consoleIdleExitMs: 0。

概览最上方的「网页搜索」独立卡片会按「配置 + 桥存活 + 令牌匹配」显示是否真的 可用（不再藏在「操作」里；旧宿主没上报状态时也会显示重启提示与手动入口）。插件启动、 桥就绪后默认自动接入（issue #7）：用户显式配过 baseURL / key / searchProvider 就完全不碰；桥换了端口或本地令牌轮换会自动自愈；点「恢复接入前配置」会还原并关闭自动 接入，之后不再自动重连。自动接入时卡片会注明；自动失败会显示原因并保留「一键接入」 按钮，也可以用 WORKBUDDY_AUTO_WEB_SEARCH=0 永久关闭。接入后插件会把桥令牌写进独立 凭据引用、用 dsh 自己的 web 服务真搜一次做自检，并保留最近一次的时间/来源数。

即使 dsh 内置搜索仍指向 DeepSeek（或 key 失效），agent 还可以用 workbuddy_web_search 工具直接走桥的 WorkBuddy 原生搜索，不依赖 dsh 的搜索配置。 视频同理：dsh 里可以直接让 agent 调用 workbuddy_generate_video 提交（文生视频 / 首尾帧 / 参考图），再用 workbuddy_video_status 查询；提交是计费动作，工具文案会明确 提醒不要重复提交。详见 dsh-plugin/README.md。

dsh plugin --profile desktop add <本仓库路径>/dsh-plugin

装完重启一次 dsh（插件模块与客户端引导行只在启动时组装）。 两种方式可以共存：控制台照旧能开，桥是同一个进程；但不要同时保留旧的手写 llm-pi-ai.providers.workbuddy 路由——插件首次加载会自动把它清掉（先备份）。

诊断怎么认「打包安装」：Electron 形态的 DSH 把 @deepseek-ai/dsh-base / dsh-web-app 这类随安装提供的 bundle 打进 resources\app.asar，普通 node 的 existsSync 穿不透归档 —— 旧版因此把它们报成「缺失」，还建议你去 profile 里 pnpm add（那会与自带的那份形成双实例与代次冲突）。现在会读 asar 的索引头 确认（零依赖、只读几十字节；在 dsh 宿主进程里会临时关掉 Electron 的 asar fs 补丁，所以面板与命令行看到的是同一份事实），detail 里注明「N 个随安装提供」； 布局实在认不出来时只说「无法确认」，不报红。详见 docs/TROUBLESHOOTING.md。

模型 → 详情顶部就是这张表单：

• 输入 / 输出并排：输入 = dsh 上下文预算，输出 = 发给上游的 max_tokens； 两行都是「滑块粗选 + 数值框精确」，支持 128K / 1M / 131072，留空 = 自动。
• 改完自动保存：滑块松开、输入框失焦或回车即落盘；temperature / 思考强度 仍点「保存修改」一起提交。
• 下一轮请求生效：保存后下一次请求会按新预算解析（同一会话也生效）； 用量弹层的分母可能还停留在上一轮，发一条消息即可刷新；切换模型后按 该模型自己的预算解析。面板状态显示「当前配置」。
• 不会被官方默认误判：模型自己的「默认输入 300K + 输出上限 384K」是合法 组合；输入/输出共享窗口只做非阻断提示，模型上限/下限仍硬校验。
• 精确回填：131072 不会显示成 128K 后再存成 128000；输出上限同时 显示精确 tokens。
• 覆盖值会标「自定义」，可用「已自定义（N）」筛选；偏好写入 <DSH_HOME>/workbuddy-model-prefs.json，旧的插件目录文件在启动时自动迁移。

细节、配置项与验证记录见 dsh-plugin/README.md。

打开 http://127.0.0.1:8792 后：

每个面板的表头都显示「数据更新于 HH:MM:SS」，页面上出现的结论都能对得上时间。 所有图表都是自己画的零依赖内联 SVG（没有引入任何图表库）。

控制台的所有接口见 dashboard/README.md。

桥同时讲两套协议，因为客户端说的是两套：

OpenAI 系客户端（opencode / Cursor / Trae / Cherry Studio …）
   │  POST /v1/chat/completions
   │
Claude Code
   │  POST /v1/messages            ← Anthropic Messages 协议
   ▼
bridge/workbuddy-bridge.mjs
   │  1. 注入鉴权头（桌面凭据现取现解；插件凭据解密后仅驻内存）
   │  2. 保证流式（上游不接受非流式请求）
   │  3. 请求体归一化（developer → system、tool_choice 对象 → 字符串）
   │  4. Anthropic ↔ OpenAI 双向翻译（仅 /v1/messages 这条路径）
   ▼
copilot.tencent.com/v2/chat/completions   ← 上游只说 OpenAI 协议，且只支持流式

OpenAI 那条路径基本不做协议翻译——上游本来就说 OpenAI 协议，桥只做上面 1–3 三件适配。Anthropic 那条必须翻译：Claude Code 的请求结构、响应结构、流式事件 格式都与 OpenAI 不同，光把 Base URL 指过来会直接 404。

两条路径最终汇到上游同一个端点，所以用量、积分、账本、控制台是统一的。

网页搜索另走 WorkBuddy 的原生 POST /agenttool/v1/search：桥暴露 POST /v1/web_search，并在 /v1/messages 识别 web_search_20250305。dsh 的 Web search provider 把接口地址指到桥后，搜索走 WorkBuddy 账号、不消耗 DeepSeek 钱包。插件启动后默认自动接入（用户显式配置过搜索后端则不动；可 恢复接入前配置 或 WORKBUDDY_AUTO_WEB_SEARCH=0 关闭），桥令牌写进独立凭据引用、不覆盖 DEEPSEEK_API_KEY，写完还会用 dsh 自己的 web 服务真搜一次做自检；自动失败的兜底是 workbuddy_web_search 工具（直接打桥，不依赖 dsh 搜索配置）。配置与验证提示词见 dsh-plugin/README.md。

上游比 OpenAI 规范更严的地方（developer 角色、tool_choice 只认字符串、首条必须 是 system）都在同一次归一化里处理；缺的能力（embedding）明确返回 501 而不是伪造。 详见 docs/ARCHITECTURE.md。

视频生成另走 WorkBuddy 的 Miora 产品网关：桥暴露 POST /v1/videos、 GET /v1/videos/{id} 与 GET /v1/videos/{id}/content，支持文生视频、首尾帧、 参考图三种模式。图片同源：POST /v1/images、POST /v1/images/edits、 GET /v1/images/{id}、GET /v1/images/{id}/content，支持文生图 / 图生图。 两类通常是异步任务（202 + 轮询查询，可加 ?wait=N 让桥代等）；上游有时同步跑完， 此时返回 200 + sync: true，产物/失败原因就在提交响应里（图片实测常见），不要再按 id 查询。提交成功即按账号积分计费；临时 key 只驻内存，401 才换 key 重试一次， 429/5xx 不自动重提以免重复扣费。 媒体接口只接受本地管理令牌（普通 client key 仅聊天）；配置、参数、计费边界与实测 结论见 docs/VIDEO-GENERATION.md 与 docs/IMAGE-GENERATION.md。

所有配置项都有合理默认值；完整清单（含中文说明）见 .env.example。 机器可读的接口描述见 docs/openapi.yaml（OpenAPI 3.1）。

统一配置真源是 config.mjs，优先级： 进程环境变量 > .env > 内置默认值。

copy .env.example .env

常用项：

| WORKBUDDY_AUTH_FILE | 自动定位 | 登录文件；多账号时务必显式指定 | | WORKBUDDY_CONTEXT_WINDOW | 官方默认（多为 300000） | dsh 的上下文容量按模型解析。推荐在插件「模型 → 详情 → 上下文窗口（Token）」里按模型单独调（输入/输出改完自动保存；保存后下一轮请求按新预算解析，用量分母可能显示上一轮，发一条消息刷新；切换模型用该模型自己的预算）；本变量作为面板「自动」时的桥端默认值，也供不使用面板的其它 OpenAI 客户端使用，可钉到 600000 / 1000000（不超过模型上限） | | WORKBUDDY_ANTHROPIC_MODEL | glm-5.3 | Claude Code 的模型名映射到哪个真实模型（也可直接填上游真实 id） | | WORKBUDDY_ANTHROPIC_FAST_MODEL | glm-5.3-flash | Claude Code 后台任务（标题生成、文件摘要）用的小快模型 |

完整列表见 .env.example 与 docs/CONFIGURATION.md。

改端口后需同步：控制台会按新配置启动桥，无需手工对齐。

适合 API key 网关模式（CODEBUDDY_API_KEY 由外部注入）。桌面凭据模式需要 本机的 WorkBuddy.exe 取 AtRest 密钥，容器里没有——那种用法保持「本机 + 启动.cmd」：

docker build -t workbuddy-bridge .
docker run -d -p 8790:8790 -p 8792:8792 \
  -e CODEBUDDY_API_KEY=<key> \
  -e WORKBUDDY_LOCAL_TOKEN=<一串随机值> \
  -v workbuddy-data:/data \
  workbuddy-bridge

容器里没有桌面端可供读取，必须显式给 WORKBUDDY_LOCAL_TOKEN；不给时 healthcheck 会如实判 unhealthy（不再用空 Bearer 假装健康）。/data 卷保存 账本与令牌，重建容器不丢。

非 root 用户运行，带 /health 健康检查。

启动.cmd                   一键启动（Windows，双击即可）
config.mjs                 统一配置（唯一真源）
.env.example               配置样例
bridge/
  workbuddy-bridge.mjs     桥本体（AtRest 解密 + 请求体归一化 + Anthropic 兼容层）
  launch.mjs               按统一配置独立启动桥
  start-bridge.cmd         Windows 独立启动入口
  start-bridge.sh          macOS / Linux 独立启动入口
dsh-plugin/                DeepSeek Harness 原生插件（宿主端 + dsh 设置页）
  lib/index.js            插件入口：桥/控制台生命周期、原生模型路由、工具、命令
  lib/adapter.mjs         dsh 词汇 ↔ OpenAI 词汇（SSE → StreamChunk）
  lib/console.mjs         控制台进程管理（识别 / 复用 / 拉起）
  lib/consoleApi.mjs      控制台 API 白名单透传（设置页与控制台同步的关键）
  lib/client.js           客户端半边：dsh 设置里的 9 标签页（控制台全部功能）
  README.md               插件文档（安装、配置、验证记录）
dashboard/
  server.mjs               控制台后端（仅绑 127.0.0.1）
  public/index.html        控制台前端（单文件）
lib/
  atrest.mjs               AtRest 密钥获取与信封解密
  config-schema.mjs        数值 / 枚举配置的取值校验（诊断页「配置取值」）
  diagnostics.mjs          环境诊断（页面与 CLI 共用；含客户端安装布局体检）
  dsh.mjs                  dsh 配置读取与模型注册写入
tools/
  doctor.mjs               命令行自检（doctor --json 可选）
  backup.mjs               运行期数据备份 / 恢复（含 SHA-256 清单）
  verify-atrest.mjs        凭据解密自检
  dev/                     开发期探查脚本，日常无需使用
scripts/
  start.sh                 一键启动（macOS / Linux；仅源码自建，凭据解密未实测）
docs/                      架构、配置、排错、安全、接入链路审计、界面规范

务必了解的风险与边界（定位与合规声明见文档最前面的 ⚠️ 请先读这一段）：

1. 非官方路径。 上游随时可能修改协议或封禁该方式，可用性无保证。团队或商用场景应申请官方 API 访问权限。
2. 不要绑 0.0.0.0。 那等于把订阅额度暴露给整个局域网。项目全程只绑 127.0.0.1，请勿修改。
3. 登录文件只读。 桥不会写回登录文件——这是有意为之，写入明文会破坏客户端的加密凭据存储。令牌刷新结果只留在桥的内存里。
4. 不落明文凭据。 项目不内置、不记录任何令牌明文；桌面源每次请求现取现解，插件源用 DPAPI / 文件密钥 + AES-GCM 加密保存（密钥不可用时仅内存）。诊断只读取长度、账号与有效期。
5. 令牌有效期约 45 天。 桌面端会自行续期；桥每次请求都重新读取并解密登录文件，因此只要客户端在正常使用就无需额外维护。插件登录的令牌会由桥在后台刷新并加密回写。
6. 额度归属登录账号。 桥只转发登录账号的请求，消耗的是该账号自身的配额；控制台的「对话测试」也会消耗少量额度。
7. 合规。 使用前请确认符合 WorkBuddy 的服务条款。详见 docs/SECURITY.md。
8. 计费口径请自行核对。 桥不引入任何新的计费——经桥的调用与在客户端里直接使用消耗的是同一份账号额度；但两种路径是否按同一口径计入取决于上游策略。建议连续几天对比控制台「用量统计」的积分合计与客户端内的用量页：量级与趋势应一致，出现系统性偏差就停止使用并排查（桥只在本地记账，不上报任何数据）。

• 使用求助 / 报错提问：Discussions · Q&A —— 先搜一下已有讨论；提问时附上脱敏诊断包（node tools\doctor.mjs --bundle）。
• 功能建议：Discussions · Ideas
• 接入案例 / 工作流分享：Discussions · Show and tell
• 维护者公告：Discussions · Announcements
• 确定是 bug：开 issue；产品使用问题请优先走上面的 Q&A，issue 区留给可复现的缺陷。

不要在公开讨论或 issue 里贴令牌、Authorization 头、登录文件、账号 UID 或完整对话内容。安全问题请按 SECURITY.md 私下报告。

这一版的很多修正来自使用者的真实反馈 —— 他们不只报现象，还把根因定位到具体代码行。

GitHub 的 Contributors 列表只统计已合并的 PR，所以这里用文字署名；被采纳但未合并的思路同样算数。

「可用模型」上方若出现黄色提示条，说明有模型已注册进 dsh 但已不在上游目录里 ——它们会留在 dsh 的模型列表里但调用必然失败，点提示条里的「清理并保存」一步清掉（自动备份）， 「全选 / 加选免费」也会自动跳过体检结论为「不可用」的模型。

先跑诊断，缺失项与修法会直接列出来：

node tools\doctor.mjs
node tools\doctor.mjs --bundle   :: 可分享的诊断包（版本/路径/PID/端口/vendor 指纹/最近失败，脱敏）
node tools\backup.mjs --out D:\wb-backup   :: 备份运行期数据（换机 / 重装前）
node tools\backup.mjs --restore D:\wb-backup --yes   :: 恢复（先停桥与控制台）

完整排查表见 docs/TROUBLESHOOTING.md。

MIT。本项目派生自若干公开项目，完整的来源与改动说明见 NOTICE.md。

与腾讯、WorkBuddy、CodeBuddy、DeepSeek 均无关联，未获其背书或支持。