workbuddy-to-dsh使用教程

你有没有过这种体验：电脑里装着一个桌面端，里面明明躺着一堆能用的模型------DeepSeek、GLM、Kimi、MiniMax，你问什么它都答。可一旦你想让 Agent 工具、脚本、编辑器插件去调这些模型，就发现根本调不到：没有 API key，没有公开入口，凭据锁在客户端里。你只能一边开着桌面端，一边手动复制粘贴。

更别扭的是：你明明已经为这些模型付了费，却只能坐在客户端窗口前面用------它像一个货架上摆满了东西、却不对你开门的仓库。

这篇文章讲一个开源项目 workbuddy-to-dsh 做的事：把本机 WorkBuddy 桌面端已登录的模型能力，经一个只监听 127.0.0.1 的本地桥，暴露成 OpenAI 兼容接口------任何支持自定义 Base URL 的客户端（比如 DeepSeek Harness，下称 dsh）都能直接调。

这篇只讲两件事：它能给你什么，以及怎么用起来。 至于它内部是怎么把凭据取出来的，那是另一个故事了------想了解实现可以直接看仓库的 README.md 和 docs/ARCHITECTURE.md，那里写得很细。

它长什么样

一句话：一个本地桥 + 一个网页控制台 + 一个 dsh 原生插件，都是纯 Node 脚本，零 npm 依赖。

flowchart LR A["你的客户端"] --> B["本地桥 127.0.0.1 8790"] C["网页控制台 127.0.0.1 8792"] --> B D["DeepSeek Harness 插件"] --> B B --> E["上游网关"]

桥：127.0.0.1:8790，讲 OpenAI 协议，流式与非流式都支持。
控制台 ：127.0.0.1:8792，一屏看状态、用量、请求、模型、诊断、签到。
插件：装进 dsh 后，模型选择器里直接多出 provider WorkBuddy，设置页多出 9 个标签页。

两者都只绑回环地址，不对外暴露，也不内置任何密钥。

先看成品：一屏能干什么

双击一次 启动.cmd，浏览器会自动打开控制台。这就是你看到的东西：

七个亮点，先列个总览：

亮点	一句话价值
用量统计与趋势图	这钱花在哪了，一屏看清
请求明细	某个模型调不通时，不用翻原始日志
模型目录与体检	先知道自己手上有哪些牌、哪些真能用
环境诊断	8 项检查按优先级排，红色项不解决模型就不会出现
每日自动签到	别忘了领积分，默认帮你签
对话测试	不用切回客户端就能验证链路
dsh 原生插件	模型直接出现在 dsh 选择器里，不写配置文件

下面挑几个最常用的展开说。

亮点一：用量统计与趋势图，看清钱花在哪

这是整个控制台里我花心思最多、也最常用的部分。

控制台：

dsh插件：

1 / 7 / 30 天三档：调用次数、token 数、平均耗时、消耗积分、失败数，一眼看全。
趋势图可切换口径：指标能在「次数 / tokens / 积分」之间切，粒度能在「按天 / 最近 24 小时」之间切。想确认某个时段是不是在偷偷跑量，切到小时粒度最直观。
积分排行 ：按模型排，直接回答「这段时间积分花在哪了」。你会很清楚地看到哪些模型是性价比之王------比如 space-bunny 的倍率是 x0.03，而 kimi-k3-1 是 x1.62，差五十多倍。
实测成本：账本窗口内「扣分合计 ÷ token 合计 × 1000」，是拿真实数据算出来的，不是拿目录倍率估的。数据不够时它会显示「---」并说明原因，不会编一个数字糊弄你。
导出 CSV：想自己在 Excel 里做透视表的话，一键导出。

关于隐私可以放心：账本 bridge/usage.jsonl 只记元数据 ------时间、模型、流式与否、耗时、token、扣分、状态码、错误码。从不记对话内容，也不记请求体。

还有个细节值得一提：失败也会记账 。成功和失败写在同一个账本里，靠 ok 字段区分。因为失败既没有 token 也没有扣分，如果只统计成功，那「某个模型调不通」在界面上就完全不可见了。

亮点二：请求明细，调不通的时候不用翻日志

控制台：
dsh插件：

逐条请求明细：时间、模型、是否流式、耗时、token、扣分、结果。失败的行标红并带上游错误码，点失败标签可以直接一键复制错误详情。

支持的操作用起来很顺手：

模型筛选：下拉来自完整模型目录，不是只列当前这一页出现过的模型（这个坑我踩过，早期版本越筛越少）；
仅看失败：排查的时候直接过滤；
40 / 100 / 200 条叠加查看；
暂停自动刷新：想盯着某一条看的时候很有用；
导出当前筛选的 CSV：筛完再导出，拿去贴 issue 正好。

常见错误码速查：11102 模型不存在、11128 请求结构不被认可、11101 需要流式。看到这三个数字，基本就知道问题出在哪一层了。

亮点三：模型目录与体检，先知道自己有哪些牌

控制台：
dsh插件：

「可用模型」面板展示的是从上游实时拉回来的真实可用模型，不是写死的清单。每一行带上下文长度、输出上限、消耗倍率和实测成本。

几个我觉得很实用的点：

体检：能逐个测「这个模型到底调不调得通」，范围可选（勾选的 / 已注册的 / 全部）。测完可以一键取消勾选不可用的------省得你一个个试。
促销徽章 ：上游在做限时免费的模型会挂一个红色标签，倍率位直接显示「免费」而不是 0。注意促销是动态的，今天免费不代表明天免费。
多模态标记：支持图片输入的模型会带一个文字标记「图片」，表头上方还有一行统计------「共 N 个模型，其中 M 个支持图片输入」。
模型详情：点行末的 ⓘ 展开，里面是中文描述、厂商标识、标签、精确的上下文与输出上限，还有一个「用这个模型对话 →」直接跳到对话测试。
一键同步到 dsh：勾好之后一步写进 dsh 设置。

顺带一提，模型数量比你想的多：国内账号实测 31 个，国际账号 26 个。所有图表都是自己画的零依赖内联 SVG------项目没有引入任何图表库，整个控制台前端就是一个单文件 HTML。

亮点四：环境诊断，8 项检查按优先级排

控制台里最容易忽略、但排查时最省时间的一块。

8 项检查：WorkBuddy 客户端、登录文件、AtRest 密钥、凭据解密、桥服务、dsh 模型路由、凭据引用、profile bundles。

它有两个设计我很喜欢：

按优先级排序 ------fail > warn > ok。红色项不解决，模型就不会出现，所以最该看的排在最上面，不用你自己判断先修哪个。
每项都带修法。不是只告诉你「这里红了」，而是直接写「点『启动桥服务』」或者「在 profile 目录执行 pnpm add <包名>@<与 DSH 一致的版本>」。

命令行也能跑同一套诊断：

cmd 复制代码

node tools\doctor.mjs

因为控制台本身不含探测逻辑，所有判断都来自同一份 lib/，所以页面结论和命令行输出必然一致，不会出现两边各说各话的情况。

亮点五：每日自动签到，别忘了领积分

签到是确定性动作，忘了就是白丢积分，所以项目默认帮你做：

桥在跑就会签 ：每次有模型请求经过时顺带补签，不阻塞这次调用（fire-and-forget，绝不拖慢你的请求）；
控制台开着也会签：启动时和每小时各检查一次，而且会先问「今天签了没」再决定要不要打上游，不做无用请求；
重复签到不算失败 ：上游对「已签到」返回的是非零业务码，项目把它当作幂等成功处理，不会误报成错误；
开关在界面上：不想自动签随时关掉。

顺带说一句：国际版账号没有签到活动 ，界面上会显示未启用，这不是故障。

亮点六：对话测试，不用切回客户端就能验证

装好之后想确认「整条链路真的通了」，不用切回桌面端，控制台里就能测：

多轮对话，带上下文；
按轮次分段，每条回答下面贴着本轮耗时、tokens、扣分；
流式输出可随时停止；
回答可复制，旁边还附带桥日志（可按关键字过滤、只看错误、只看本次启动）。

注意它消耗的是你自己账号的额度，跟正常使用一样------只是量很小。

亮点七：dsh 原生插件，两个前端一个后端

如果只用「接入 dsh」这一个场景，装插件是最省事的：模型直接出现在 dsh 的模型选择器里 ，不写 settings.yaml ，也不依赖 llm-pi-ai。

设置页里会多出 9 个标签页：概览 / 账号 / 用量 / 请求 / 签到 / 诊断 / 模型 / 对话测试 / 日志------功能和控制台网页完全等价 。因为它们是「两个前端、一个后端」：读同一个桥、写同一份 .state.json，你在任意一边改，另一边跟着变。

插件还带了 5 个工具和一组斜杠命令：

text 复制代码

/workbuddy status    桥与控制台总览
/workbuddy models    列出当前可用模型
/workbuddy usage     最近 7 天用量
/workbuddy checkin   签到状态
/workbuddy start | stop | restart

上手教程

不想动手？ 如果你只是想快速体验、不想自己敲命令，也可以让 AI 帮你自动部署：把仓库地址 https://github.com/Ianzhyh/workbuddy-to-dsh 丢给支持执行命令的 AI 助手（比如 DeepSeek Harness 里的 Agent 工具），让它按下面的步骤一步步跑完即可------本质上就是「双击启动 + 装插件」那几步，AI 照着做就行。

前置条件

条件	说明
Node.js	18 或更高。无 npm 依赖，不需要 `npm install`
WorkBuddy 桌面端	已安装且已登录，进程可用
DeepSeek Harness	可选。只有要接入 dsh 时才需要
操作系统	Windows 已验证；macOS / Linux 已实现但未实测

第一步：双击启动

Windows 上双击根目录的 启动.cmd，就这一步。它会自动定位 Node.js、启动服务、并在浏览器里打开控制台，桥会被自动拉起。

三个「不需要」：

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

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

macOS / Linux 用 scripts/start.sh。

第二步：确认一切就绪

打开 http://127.0.0.1:8792，先看两处：

顶部提示条 ：它只显示需要你处理的事，优先级是「桥不可用 > 令牌临期 > 新失败 > 未签到」。什么都不显示就是一切正常。
状态卡：确认账号对不对、令牌还剩多少天、桥在不在跑（有 PID 和运行时长）、模型数是多少、积分余额是多少。

如果哪里不对，直接点「环境诊断」，红色项就是你要修的。

第三步：接入 DeepSeek Harness（推荐装插件）

三种安装方式，装的是同一个插件，挑一个：

sh 复制代码

# 方式一：一条命令直装
dsh plugin --profile desktop add github:Ianzhyh/workbuddy-to-dsh

# 方式二：release 附件（tgz 安装包，无构建、无需 allowBuilds 授权）
dsh plugin --profile desktop add ./dsh-plugin-workbuddy-1.1.0.tgz

# 方式三：从源码
git clone https://github.com/Ianzhyh/workbuddy-to-dsh.git
dsh plugin --profile desktop add workbuddy-to-dsh/dsh-plugin

装完重启一次 dsh（插件模块会被缓存，客户端引导行只在启动时组装一次）。之后打开「设置 → WorkBuddy」，模型就能在 dsh 的模型选择器里看到了。

如果你之前手写过 llm-pi-ai.providers.workbuddy 路由，插件首次加载会自动清理掉（会先备份），否则两条同名路由会撞名。

第四步：不装插件也行（手写 YAML）

如果暂时不想装插件，模型靠两处手写 YAML 注册：

yaml 复制代码

llm-pi-ai:
  providers:
    workbuddy:
      displayName: WorkBuddy
      apiKeyEnv: WORKBUDDY_BRIDGE_KEY     # 引用，不写明文
      api: openai-completions             # 手工声明路由必须点名协议
      baseURL: http://127.0.0.1:8790/v1
      models:
        - id: deepseek-v4.1-flash

两个要注意的点：

pi-ai 的 OpenAI 兼容实现要求请求必须带 API key 头 （即使本地桥并不校验），所以这个占位凭据不能省，值只要与桥的 WORKBUDDY_LOCAL_TOKEN 一致即可（默认 wb-local-bridge）；
settings.yaml 是热重载的，保存后模型立刻出现在选择器里。

小提示：DSH Desktop 0.2.0 会把 settings.yaml 导入 profile 的 patch 层并归档为 .imported，所以它「不见了」是正常的，不是被删了。

第五步：接入其它 OpenAI 客户端

任何支持自定义 Base URL 的客户端都能用，填两个值：

项	值
Base URL	`http://127.0.0.1:8790/v1`
API Key	`wb-local-bridge`（与你的 `WORKBUDDY_LOCAL_TOKEN` 一致即可）

注意这个 token 只是本地回环令牌 ，用来防止同机其它程序误用这个端口，不是上游凭据。

日常：不想开控制台也可以

用的是同一套配置：

cmd 复制代码

bridge\start-bridge.cmd       :: 只起桥
node tools\doctor.mjs         :: 命令行自检，输出缺失项与修法
node tools\verify-atrest.mjs  :: 凭据解密自检

常用配置项压成三行就够，写在根目录的 .env 里：

变量	默认值	说明
`WORKBUDDY_PORT`	`8790`	桥监听端口
`DASHBOARD_PORT`	`8792`	控制台端口
`WORKBUDDY_AUTH_FILE`	自动定位	登录文件；多账号时务必显式指定

两个能直接跑的示例

示例一：curl 直连桥。 最朴素的验证方式：

bash 复制代码

curl http://127.0.0.1:8790/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer wb-local-bridge" \
  -d '{
    "model": "deepseek-v4.1-flash",
    "messages": [
      {"role": "system", "content": "你是一个简洁的助手。"},
      {"role": "user", "content": "用一句话解释什么是 OpenAI 兼容接口。"}
    ],
    "stream": false
  }'

先看目录再选模型：curl http://127.0.0.1:8790/v1/models（加 ?refresh=1 强制重取上游）。健康状态和配额分别是 curl http://127.0.0.1:8790/health 与 curl http://127.0.0.1:8790/v1/quota。

示例二：用 OpenAI SDK 调用。 因为桥是 OpenAI 兼容的，任何支持自定义 Base URL 的 SDK 都能直接用：

python 复制代码

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:8790/v1",
    api_key="wb-local-bridge",   # 本地占位令牌，与 WORKBUDDY_LOCAL_TOKEN 一致即可
)

resp = client.chat.completions.create(
    model="glm-5.3",
    messages=[
        {"role": "system", "content": "你是一个简洁的助手。"},
        {"role": "user", "content": "写一个 Python 快速排序，只给代码。"},
    ],
    stream=False,
)
print(resp.choices[0].message.content)

Node.js 也一样，把 baseURL 指向同一个地址即可。SDK 侧不需要做任何特殊适配------角色名转换、首条消息补 system、非流转流式这些差异，桥都替你处理了。

常见问题

现象	怎么办
模型没出现在 dsh 里	桥没启动 / 路由没生效 / profile bundle 缺失。先跑一次环境诊断
提示「桥凭据异常」或 401	WorkBuddy 登录态失效了，打开桌面端重新登录一次
端口 8790 / 8792 被占	在 `.env` 里改 `WORKBUDDY_PORT` / `DASHBOARD_PORT`
登录目录里有多个账号	显式指定 `WORKBUDDY_AUTH_FILE`，否则可能选错账号
某个模型调不通	看「最近请求」面板，失败行标红并带上游错误码，比翻日志快
想看更细的排查	仓库里 `docs/TROUBLESHOOTING.md` 是按「症状 → 原因」整理的

使用须知

非官方路径。 它依赖 WorkBuddy 桌面端未公开的登录凭据存储格式，上游随时可能改动协议或封禁这种方式，可用性无任何保证，也不承诺兼容性。

仅供本机、仅供自用。 它只驱动你自己机器上已登录的那个账号，用的是该账号自身的配额；请勿做多账号中转、代他人调用或任何形式的对外提供，团队与商用场景请申请官方 API。

不要绑 0.0.0.0。 那等于把订阅额度暴露给整个局域网------项目全程只绑 127.0.0.1，请勿修改。

凭据不落盘。 项目不内置、不缓存、不记录任何令牌明文；登录文件始终只读。除发往上游的模型请求外，无任何遥测。

额度归属登录账号。 控制台的「对话测试」也会消耗少量额度。使用前请自行确认是否符合 WorkBuddy 的服务条款。

写在最后

回到开头那个仓库的比喻：这个项目做的事，其实就是把仓库的门打开，并且在门口挂一块牌子，写清楚里面有什么、你拿了多少、还剩下多少。

对使用者来说，它带来的东西很实在：模型能接进你惯用的工具了，用量和积分看得见了，出问题的时候有地方查了。至于它是怎么把凭据从加密信封里取出来的------那部分我确实花了不少功夫，但那是给想改代码的人看的，放在仓库的 README.md、docs/ARCHITECTURE.md 和 docs/SECURITY.md 里更合适。

仓库地址 ：github.com/Ianzhyh/wor...
许可：MIT
免责声明：本项目与腾讯、WorkBuddy、CodeBuddy、DeepSeek 均无关联，未获其背书或支持。

如果这个工具对你有用，欢迎去仓库点个 star，或者在 issue 里聊聊你遇到的坑------尤其是 macOS / Linux 上的真机验证，那部分代码已实现但还没实测。