WorkBuddy 桥接 miaoyongxu/hana-workbuddy-connect

WorkBuddy → HanaAgent 桥接

hana-workbuddy-connect · 非官方 · MIT

把 WorkBuddy / WorkBuddy AI 桌面 App 里的模型（GLM-5.3、DeepSeek-V4.1、Kimi-K3、GPT-6、Grok-4.7、Gemini-3.8、Hy3…）
接进 HanaAgent，复用你已经登录的桌面 App 账号，不需要 API Key。

上游与致谢

桌面凭据解密、WorkBuddy 上游协议（请求头 / 消息体 / 令牌续期）、模型目录与倍率促销元数据，全部来自 corrinehu 的 dsh-workbuddy-connect（MIT）。

本项目只做 HanaAgent 侧的适配层：一个环回 OpenAI 兼容端点 + 一个原生 provider 插件。
不复制上游代码，以上游包作为运行时依赖加载（npm dsh-workbuddy-connect），因此它的版权与许可声明始终跟在上游包里，本项目在此另行致谢。
上游是这些实现的唯一来源与真相，桥接不重新实现、也不改写成自己的版本。

第三方许可与商标声明见 THIRD_PARTY_NOTICES.md。

结论先说

dsh-workbuddy-connect 不能原样装到 HanaAgent 上——它是 DSH（cordis）插件，依赖 DSH 的设置服务、 pi-ai provider 注册和客户端 UI，这些在 HanaAgent 里都不存在。

但核心部分可以复用，而且改动量很小：

| 部件 | 归属 | 能否复用 |
| 桌面凭据解密（5.6 信封 + Electron 取密钥） | dsh-workbuddy-connect | ✅ 直接 import |
| 上游协议（强制流式、tool_choice 字符串化、X-IDE- 身份头、令牌续期） | dsh-workbuddy-connect | ✅ 直接 import |
| 模型目录（/v3/config） | dsh-workbuddy-connect | ✅ 直接 import |
| DSH 插件外壳（cordis / 设置卡片 / provider 注册） | dsh-workbuddy-connect | ❌ 不适用，丢弃 |
| 「OpenAI 兼容端点」 | 本桥接自建（约 200 行） | 新增 |
| 「在 HanaAgent 里出现为 provider」 | HanaAgent 本地 provider 插件（JSON） | 原生支持 |

所以本目录做的是桥接，不是移植：一个本地进程把 WorkBuddy 的私有协议翻译成 OpenAI 兼容协议，再以 HanaAgent 自己的「本地 provider 插件」形式注册进去。

HanaAgent (hana-server :43246)
└─ provider plugin workbuddy / workbuddy-ai ← ~/.hanako/provider-plugins/
│ authType: none, baseUrl: http://127.0.0.1:8788/<variant>/v1
▼
bridge.mjs (:8788, 仅监听 127.0.0.1)
│ ← 直接 import dsh-workbuddy-connect 的 lib ├─ 凭据：读桌面 App 的加密 auth 文件，按需续期 └─ 上游：copilot.tencent.com（国内版）/ www.workbuddy.ai（国际版）

没有改 HanaAgent 的 bundle：本地 provider 插件 + 环回 baseUrl 是 HanaAgent 原生支持的形态（它的目录核心专门把环回地址判定为「不需要 Key」），所以 HanaAgent 升级不会把这个接入冲掉。

依赖关系：到底依赖什么

| 层 | 是什么 | 依赖 DSH 吗 |
| HanaAgent 侧 | ~/.hanako/provider-plugins/workbuddy{,-ai}/——HanaAgent 原生的本地 provider 插件，HanaAgent 自己读它 | ❌ 不依赖 |
| 桥接进程 | 独立 Node 进程，把 WorkBuddy 私有协议翻成 OpenAI 兼容 | ❌ 不需要 DSH 运行；DSH 全程不在链路上 |
| 代码复用 | import 了 dsh-workbuddy-connect 这个包的 lib/（凭据解密 / 上游协议 / 模型目录） | ⚠️ 依赖这个 npm 包存在 |

所以准确说法是：

- 不是「必须由 DeepSeek Harness 桥接过去」——DSH 应用不参与，数据也不经过它；
- 也不是「一个包丢进 HanaAgent 就完事」——目前是「原生 provider 插件 + 常驻桥接进程」两件套，而且桥接需要 dsh-workbuddy-connect 这个包。

那个包不需要装 DSH：它在 npm 上（MIT，0.7.4），peer 依赖 0.2.0-rc.2 也都在 npm 上， npm install 就能装齐（实测 151 个包，13 秒）。桥接按这个顺序找它：

1. 环境变量 WORKBUDDY_PLUGIN_DIR——显式设置就是权威：指错了会直接报错并说明，不会偷偷改用别的副本
2. npm 为本包安装的那份依赖——用 Node 自己的解析算法定位（不猜路径），所以 npm install 之后无需任何配置，也不需要机器上装着 DSH
3. ~/.dsh/profiles//node_modules/dsh-workbuddy-connect（复用已有 DSH 安装）

实测：把包装到干净的 %TEMP% 目录（152 个包），跑 --sync-only 两版目录照样拉到（18 + 24 个模型），用的是它自己的依赖副本，全程没碰 DSH profile。

想彻底不依赖那个包，只能把它那部分逻辑（凭据解密 + 上游协议 + 目录）vendor 进本仓库——可行，但等于自己承担 WorkBuddy 私有协议变更的维护。目前刻意选择复用，保证「上游一变，跟着插件升级就行」。
为什么刻意不 vendor：MIT 的署名义务跟着代码走——只要不复制代码，归属就永远不会含糊（上游依旧是实现者，本项目只是调用方）。抄进来再改名，反而既丢了署名、又多了维护责任。

前置条件

1. WorkBuddy 或 WorkBuddy AI 桌面版已安装并登录（桥接读它的登录态，不写它）。
2. Node.js 22+（本机 v24 已验证）。
3. HanaAgent 正在使用（可选：不运行时只写文件，不热注册）。
4. dsh-workbuddy-connect 可被找到，二选一：
- 在本仓库跑 npm install（自带依赖，不需要 DSH）；或
- 复用已有安装：dsh plugin --profile web add dsh-workbuddy-connect，或用 WORKBUDDY_PLUGIN_DIR 指向任意一份包目录。

用法

git clone https://github.com/miaoyongxu/hana-workbuddy-connect.git
cd hana-workbuddy-connect
npm install # 可选：不自带依赖时，桥接会去 DSH profile 里找 dsh-workbuddy-connect

启动（后台，日志写 logs/bridge.log） powershell -ExecutionPolicy Bypass -File start-workbuddy-bridge.ps1

看状态（含两版的登录态） powershell -ExecutionPolicy Bypass -File start-workbuddy-bridge.ps1 -Status

停止 powershell -ExecutionPolicy Bypass -File start-workbuddy-bridge.ps1 -Stop

前台跑（调试用）
node bridge.mjs

平台：桥接本体是纯 Node，跨平台；start-workbuddy-bridge.ps1 / install-workbuddy-bridge-autostart.ps1 是 Windows 的便利脚本，macOS / Linux 上直接
node bridge.mjs --log-file logs/bridge.log &，开机自启用你自己的 supervisor（launchd / systemd）。
凭据发现逻辑（macOS 默认路径、Windows 注册表、WSL 挂载）来自上游插件，本桥接只是调用它。

启动时它会做三件事：拉一次实时模型目录 → 写 ~/.hanako/provider-plugins/<id>/ → 通过 HanaAgent 自己的 PUT /api/config 热注册（和设置界面「添加 provider」走同一条路），所以不需要重启 HanaAgent。之后每 15 分钟复查一次目录（--resync-minutes 可调，0 = 关闭）。

拿不到实时目录的那一版会被跳过（不写文件、不注册），所以列表里只会出现真正能用的分组；等它在桌面 App 里重新登录后，下一次复查会自动补上。

复查不会反复写你的配置：声明没变、而且这个 provider 确实还注册在 HanaAgent 里时，复查只读不写。
（PUT /api/config 是 HanaAgent 自己的设置保存路径，会让它重写 agent 配置文件；每 15 分钟来一次既没必要，也可能和用户正在改设置撞车。）如果用户在界面上把这个 provider 删掉了，复查会发现它不在了并自动重新注册，不用重启应用。

启动失败会明说：端口被占用会提示「端口 8788 已被占用……用 --port 换一个」，并以退出码 1 结束，不会留下一个「进程还在、但没在服务」的僵尸。

然后在 HanaAgent 里选模型：模型选择器会出现 WorkBuddy AI（国内版登录有效时还会有 WorkBuddy）分组。

控制台（独立外置窗口）

控制台由桥接自己提供，不依赖 HanaAgent 渲染任何东西：

powershell -ExecutionPolicy Bypass -File .\start-workbuddy-panel.ps1
npm run panel # 同一件事
npm run panel -- -DryRun # 只看会做什么，不打开窗口
npm run panel -- -NoApp # 用默认浏览器开普通标签

它会先确认桥接在跑（没跑就自动拉起），然后用 Edge / Chrome 的 --app= 打开 http://127.0.0.1:<port>/panel。--app= 没有地址栏和标签栏，看起来就是一个独立小工具；机器上没有 Edge/Chrome 时退回默认浏览器，也可以用 -Browser <路径> 指定。

| 功能 | 说明 |
| 桥接状态 | 运行中/未运行、端口、脚本与数据目录、上游插件位置、PID 与启动时间 |
| 账号与登录态 | 两个变体各自的 uid、域名、登录有效期、最近成功/失败、配额冻结 |
| 剩余积分 | 按需查询：各套餐余额与到期时间 + 7 天内到期提醒。这是一次真实的计费请求，所以不做自动轮询 |
| 刷新模型目录 | 与命令行 --sync-only 同一条链路：拉实时目录 → 写 provider 文件 → 热注册 |
| 账号档案（多账号） | 把桌面 App 当前的登录采集为一份档案，之后手动切换；一个变体可存多份 |
| 模型显隐 | 按账号保存；改完立刻重新同步给 HanaAgent，模型选择器马上生效 |
| 推理档位探测 | 复用上游插件自己的探测逻辑，三种结论：validating（列出支持档位）/ non-validating（该端点不校验）/ unknown（带原因） |
| 启停桥接 | 「启动」由控制台拉起桥接；「停止」走 /admin/shutdown 优雅退出——不猜 PID 去杀进程 |
| 桥接日志 | 读桥接日志文件尾部 |

为什么是外置而不是做成 HanaAgent 里的页面：HanaAgent 的 contributes.page 被它自己的服务端标注为 legacy WebView 表面（原文：new plugins must use contributes.cards instead），实测里它在部分版本不会出现在应用左栏。页面本身通过 HTTP 完全可用，所以把界面改成由桥接直接提供——少一层宿主依赖，app 升级也不会影响控制台。

多账号：只做手动切换

- 档案是桌面 App 登录文件的一份副本，切换时把凭据存储指向它；续期结果写在档案自己的文件里，所以副本保持"采集那一刻的登录"，两边不会互相覆盖。
- 采集会校验版本：拿国内版的登录文件去给国际版建档会被直接拒绝并删掉副本（这是实测踩到的坑：两个变体在平台层的候选路径是同一个文件，真正区分靠 store 里的变体文件名）。
- 没有「配额用尽自动换号」，而且不会做。WorkBuddy 的 6004 就是按账号的配额池，自动换号等于专门绕过它——风险是风控/封号，也超出这个工具该做的事。
手动切换解决的是正常需求（工作号 / 个人号分开用）。
- 控制台不接触任何令牌：页面与 /admin 同源，桥接端口和 bearer 从它启动时写的 endpoint.json 读取。

也可以装进 HanaAgent（可选）

同一份界面也能作为 HanaAgent 原生插件提供：

powershell -ExecutionPolicy Bypass -File .\install-workbuddy-plugin.ps1

安装脚本把插件与桥接运行时复制到 <HanaAgent 数据目录>\plugins\workbuddy-connect\，面板资源取自本仓库的 panel\（与独立控制台是同一份文件，避免两处代码漂移）。
装好后页面在 /api/plugins/workbuddy-connect/workbuddy，能否出现在左栏取决于 HanaAgent 版本；无论左栏有没有，用独立控制台都不受影响。

模型名后面的倍率与促销

模型列表里的名字会带上倍率和促销徽标，和 DSH 里的口径一致：

GLM-5.3-Flash · x0.06 Hy3 · x0.00 · Free now GLM-5.2 · x0.79 · 夜间折扣 Hy4 preview · x0.29 · 夜间免费 Step-5-Preview · x0.00 · 独家限免

- 倍率（x0.06）来自上游目录的 credits 字段，x0.00 即当前免费。
- 徽标（限时免费 / 夜间免费 / 夜间折扣 / 独家限免 / Free now）是上游自己的拼写，直接跟着走，不做翻译；国内版还有一个额外请求去控制台目录把 badge: 标签并回来。
- 两半都调插件自己的 normalizeCredits / modelWithCurrentPromotion，所以和 DSH 不会各说各话；时间窗促销在每次复查时重新判定，过期徽标会自己消失（最多滞后一个复查周期，默认 15 分钟）。
- 这是纯展示：HanaAgent 选模型存的是 {id, provider}（agents/<agent>/config.yaml），请求体里带的是 id，没有任何地方按名字匹配模型。
- 不想要后缀：--plain-names（或 WORKBUDDY_BRIDGE_PLAIN_NAMES=1）。

想看上游原始数据（倍率/徽标/促销窗口）：node dump-catalog.mjs。

命令行参数

| 参数 | 说明 |
| --port <n> | 监听端口，默认 8788（env WORKBUDDY_BRIDGE_PORT） |
| --host <addr> | 监听地址，默认 127.0.0.1（不要改成 0.0.0.0） |
| --token <v> | 要求 Bearer，默认任意值（环回地址本身是边界） |
| --hana-home <dir> | HanaAgent 数据目录，默认 ~/.hanako |
| --log-file <path> | 额外写一份 UTF-8 日志 |
| --plain-names | 只显示原始模型名，不加 · x0.06 · 夜间免费 后缀 |
| --resync-minutes <n> | 目录复查间隔，默认 15，0 = 不复查 |
| --no-apply | 只写文件，不热注册运行中的 HanaAgent |
| --no-sync | 完全不动 HanaAgent 侧 |
| --sync-only | 同步一次就退出（配合 --no-apply 可只写文件） |

验证

1) 桥接自身 curl.exe -sS http://127.0.0.1:8788/healthz curl.exe -sS http://127.0.0.1:8788/workbuddy-ai/v1/models

2) 真实跑一次（不经过 HanaAgent） $body = '{"model":"hy3","stream":false,"messages":[{"role":"user","content":"只回答一个数字：2+2"}]}'
$f = "$env:TEMP\wb.json"; [IO.File]::WriteAllText($f, $body)
curl.exe -sS -X POST http://127.0.0.1:8788/workbuddy-ai/v1/chat/completions
-H "Content-Type: application/json" -d "@$f"

3) 经过 HanaAgent 自己的 provider 测试通道 $tok = (Get-Content "$env:USERPROFILE\.hanako\server-info.json" -Raw | ConvertFrom-Json).token
$t = "$env:TEMP\wb-test.json"; [IO.File]::WriteAllText($t, '{"name":"workbuddy-ai","model_id":"hy3"}')
curl.exe -sS -X POST http://127.0.0.1:43246/api/providers/test
-H "Authorization: Bearer $tok" -H "Content-Type: application/json" --data-binary "@$t"
期望：{"ok":true,"status":200}
注意：这一步只证明 baseUrl 可达（openai-completions 走的是 GET /v1/models），不等于能对话。

4) 用 HanaAgent 自己的 pi-ai 客户端真跑一轮对话（同一段客户端代码，不动会话设置）

node verify-e2e.mjs # 默认 hy3，期望末尾 RESULT: PASS
node verify-e2e.mjs --model glm-5.3 --prompt "用一句话介绍你自己"
node verify-e2e.mjs --variant workbuddy --model deepseek-v4.1-flash # 国内版

5) 功能矩阵：智能体真正会用到的东西（工具调用 / 图片 / 推理档位 / developer 角色 / SSE 工具流）

node verify-features.mjs # 国际版
node verify-features.mjs --variant workbuddy --model glm-5.3 # 国内版

第 5 步别省。「能回一句话」和「能干活」是两件事：HanaAgent 的智能体会调工具、发图片、设推理档位，还要能吃 pi-ai 发来的 developer 角色系统提示。这个矩阵实测结果（两版各 10/10）：

✔ PASS tool call (tool_choice=auto)
✔ PASS tool call (tool_choice as object)
✔ PASS tool_choice=none suppresses tools
✔ PASS tool result turn (role=tool)
✔ PASS image input (data URI)
✔ PASS developer role is accepted (pi-ai system prompt)
✔ PASS max_tokens is honoured
✔ PASS reasoning_effort=high
✔ PASS reasoning_effort=off
✔ PASS streaming with tools (SSE)

上游限流时该项记为 ~ SKIP（含原因），不算失败——那代表「本次没验出来」，不是「不支持」。

第 4 步是链路关键：HanaAgent 调模型用的就是 ~/.hanako/artifacts/server/<版本>/node_modules/@earendil-works/pi-ai 里的 openai-completions 客户端，verify-e2e.mjs 直接驱动它，因此验证的是与界面发消息同一条链路，只是省掉了会话层。实测输出（2026-10-14）：

pi-ai : %USERPROFILE%\.hanako\artifacts\server\1.1.0-beta-...\node_modules\@earendil-works\pi-ai
baseUrl : http://127.0.0.1:8788/workbuddy-ai/v1
model : hy3
prompt : 只回答一个数字：2+2 等于几？

4

stopReason : stop
text : "4"
thinking : 36 chars
usage : {"input":29,"output":27,"reasoning":24,...}
RESULT: PASS

另外 npm test 会跑 20 项自动化测试（归属规则、发布产物完整性、PowerShell 的 BOM、包解析），其中两项是离线端到端：真起桥接进程 + HTTP 断言，不需要网络和凭据。

出错了，是谁的问题？

报错文字直接写在 HanaAgent 的报错里，第一句就标明归属，例如：

WorkBuddy 服务端限流（与本插件无关，也不是你的网络问题）：模型 deepseek-v4.1-flash 的使用频率/额度已用尽。
额度将在 2026-10-14 23:21:18 UTC+8 重置；在此之前重试不会成功，请改用其它模型。
上游原文：{"code":6004,"msg":"usage exceeds frequency limit, ..."}

（HanaAgent 只显示响应体里的 error.message，所以桥接把「谁的锅 + 重试有没有用 + 该怎么办」都写进这一句里，最后附上 WorkBuddy 自己的原文——那是唯一能说明具体限制的东西，报 issue 时也需要它。）

归属只在下游失败时改写，且只写站得住的话：

- 这些文字只出现在上游已经拒绝的那条分支——成功响应、模型列表、流式分片、工具调用一个字节都不改，所以不可能影响 HanaAgent 的正常使用。
- 只有WorkBuddy 真的回了 HTTP 状态时，才会说「与本插件无关」。桥接连不上上游（status 0）时说的是「可能是本机网络/代理问题」——那种情况本来就可能是你的网络。
- 无法归类的 4xx 不站队：「WorkBuddy 拒绝了这次请求……可能是该模型不支持的参数，也可能是桥接构造的请求有问题」——因为这两种原因从这里看长得一模一样，硬赖上游会把真 bug 藏起来。
- 规则由 failure-report.test.mjs（11 项）+ bridge-smoke.test.mjs（真起进程跑 HTTP）钉住，npm test 可复现。

对照表：

| 你看到的 | 是谁的问题 | 怎么办 |
| WorkBuddy 服务端限流…额度已用尽…将在 <时间> 重置 | 上游配额/频率（code 6004） | 换模型，或等到重置点；重试无用 |
| WorkBuddy 服务端短时限流…请求过于频繁 | 上游突发限流（code 14003） | 等约 1 分钟再试 |
| WorkBuddy 登录态已失效…重新登录 | 桌面 App 的登录过期 | 打开 WorkBuddy / WorkBuddy AI 桌面 App 登录一次 |
| WorkBuddy 账号额度不足 | 账号积分/配额用尽 | 到 WorkBuddy 客户端查看 |
| bridge transport error / 连不上 127.0.0.1:8788 | 桥接或它的网络 | 看 logs/bridge.log，重启桥接 |
| 模型列表里没有那一组 | 桥接没跑，或那一版拿不到实时目录 | node bridge.mjs --sync-only 看输出 |

自诊断：GET /healthz

不用翻日志，一次请求就能看清状态（两版各自一段）：powershell curl.exe -sS http://127.0.0.1:8788/healthz jsonc {
"variants": [{
"id": "workbuddy-ai",
"state": "signed-in", // 登录态（只读桌面凭据文件，不发起请求）
"lastError": { // 最近一次上游拒绝（保留，不会被后续成功清掉）
"at": "2026-10-14T03:16:36.661Z",
"model": "deepseek-v4.1-flash",
"kind": "soft_rate", "upstreamStatus": 429, "upstreamCode": "6004",
"resetAt": "2026-10-14 23:21:18 UTC+8",
"message": "WorkBuddy 服务端限流（不是本插件或你的网络问题）：…"
},
"lastSuccessAt": "2026-10-14T03:16:37.738Z", // 有它说明其它调用是通的 → 不是网络/桥接整体故障
"quotaBlocked": [{ "model": "deepseek-v4.1-flash", "resetsAt": "2026-10-14 23:21:18 UTC+8" }]
}]
}

lastSuccessAt 比 lastError 新，就说明只有那一个模型被限，桥接和网络都好——这是最快的一条判据。

桥接不会替你空转

上游说「配额已用尽、几点重置」时，重试是注定失败的。但 HanaAgent 把 429 归为 LLM_RATE_LIMITED （retryable: true，重试预算 4–6 次），实测一个被限模型 3 分钟内会被打 75 次。

所以桥接会把这类拒绝连同重置时间一起记下来，冷却期内直接本地作答（响应带 Retry-After），不再打上游：客户端那几次自动重试零成本，WorkBuddy 那边也不会收到一片无用请求。
冷却上限 30 分钟（短于上游公布的重置时间），到点自动放一次真请求探活，避免限制提前解除时被长时间缓存。

已知限制 / 排错

- 某一版不出现分组：桥接只发布当时能认证的那一版——拿不到实时目录就跳过，不会挂一堆必然报错的模型。
实测过一次：国内版桌面 App 五天没开，凭据里的 access token 过期、refresh token 也被服务端判 12153 invalid，于是国内版一直不注册；打开国内版 WorkBuddy 一次（App 自己会刷新并重写凭据文件）之后，桥接在下一次复查（≤15 分钟）就自动挂上了，也可以立刻 node bridge.mjs --sync-only。
国际版与国内版互相独立，一版出问题不影响另一版。
- 429 / 6004 与 429 / 14003 不是一回事：前者是配额型（报文带重置时间，重试无用，换模型或等），后者是突发型（等约 1 分钟）。两者都是 WorkBuddy 服务端行为，与桥接、网络无关；判别见上一节。
- HanaAgent 里看不到分组：确认 node bridge.mjs --sync-only 输出里有 hot-registered with HanaAgent on :43246。若显示 not hot-registered，说明 hana-server 没在跑，或 ~/.hanako/server-info.json 读不到；此时重启一次 HanaAgent 也会加载（文件已在磁盘上）。
- 不要改 --host：桥接能无 Key 访问你的 WorkBuddy 账号，必须只听 127.0.0.1。
- 插件升级：dsh-workbuddy-connect 每次发版都会换 host-heartbeat-<hash>.js 的哈希名，桥接按结构（lib/ 下的 host-heartbeat-.js + index.js 里的 as 别名表）自动识别，不用改代码。真正换了内部布局时，plugin.mjs 会在启动时报出缺哪个导出。
- HanaAgent 升级：~/.hanako/provider-plugins/ 是用户数据，升级不覆盖；桥接进程也不受影响。
- 桥接进程存活：logs/bridge.log 是权威日志；logs/console.out.log / console.err.log 是进程级崩溃堆栈兜底。脚本已把子进程的 stdout/stderr 重定向到文件，Node 侧也对断开的控制台流做了容错——这两层是必需的：子进程若继续写父进程留下的控制台管道，管道断开时会 EPIPE 直接打死桥接。

与 DSH 插件的功能差异

DSH 插件里这些是 DSH 宿主能力，HanaAgent 侧没有：设置卡片、账号/积分展示、推理档位手动探测、模型显隐（按账号）、上游最大上下文开关、doctor/logout 子命令。桥接只保证：模型列表 + 真实对话（含流式）+ 思考档位（上游声明了才给）。

卸载 powershell powershell -ExecutionPolicy Bypass -File start-workbuddy-bridge.ps1 -Stop Remove-Item "$env:USERPROFILE\.hanako\provider-plugins\workbuddy-ai" -Recurse -Force Remove-Item "$env:USERPROFILE\.hanako\provider-plugins\workbuddy" -Recurse -Force

若已设开机自启：删掉启动文件夹里的 WorkBuddy Bridge.lnk

桥接不写 WorkBuddy 桌面 App 的任何文件；~/.dsh/.workbuddy-auth.json 是 DSH 插件自己的凭据副本，桥接与它共用同一把锁，删除与否都不影响桌面 App 的登录。

文件说明

| 文件 | 作用 |
| bridge.mjs | 入口：HTTP 服务、流式转发、模型目录同步与热注册 |
| plugin.mjs | 定位并加载 dsh-workbuddy-connect 的 lib；按结构识别被混淆的导出名 |
| failure-report.mjs | 失败归属与用户可读文案（独立模块，便于单测） |
| dsh-shim-loader.mjs | ESM resolve 钩子，把 @deepseek-ai/dsh-atomic-write 指到本地垫片 |
| dsh-atomic-write-shim.mjs | 该包的本地实现（原子写 + 文件锁），只用到这两个函数 |
| hana-providers.mjs | 写 HanaAgent 本地 provider 插件 JSON（含模型能力字段映射与倍率/徽标后缀） |
| hana-apply.mjs | 通过 PUT /api/config 把 provider 热注册进运行中的 HanaAgent |
| dump-catalog.mjs | 打印两版实时目录的倍率/徽标/促销窗口（核对显示名怎么来的） |
| verify-e2e.mjs | 用 HanaAgent 自己的 pi-ai 客户端做端到端对话验证（只读，不改会话） |
| panel/ | 控制台界面（panel.html 由桥接生成，panel.css / panel.js 静态资源）。独立控制台与 HanaAgent 插件共用这一份 |
| start-workbuddy-panel.ps1 | 起桥接并用 Edge/Chrome 的 --app= 打开独立控制台（-DryRun 只检查不打开） |
| account-profiles.mjs | 账号档案：采集 / 列表 / 切换 / 删除（含采集时的变体校验） |
| model-visibility.mjs | 按账号保存的模型显隐 |
| admin-api.mjs | 控制台后端：/admin/ 运维接口 |
| verify-features.mjs | 功能矩阵：工具调用 / 图片 / 推理档位 / developer 角色 / SSE 工具流 |
| .test.mjs | npm test 跑的 20 项测试（含两项离线端到端；测试文件不随包发布） |
| start-workbuddy-bridge.ps1 | 启动 / -Status / -Stop（UTF-8 BOM） |
| install-workbuddy-bridge-autostart.ps1 | 可选：开机自启（启动文件夹快捷方式） |
| package.json / LICENSE / THIRD_PARTY_NOTICES.md | 发布用：依赖声明、MIT 许可、第三方声明 |
| .gitignore | 挡住 logs/、bridge.pid、.bak、凭据副本 |

许可与免责

- 本项目自己的代码：MIT（见 LICENSE，版权人 miaoyongxu）。
- 上游 dsh-workbuddy-connect：MIT（作者 corrinehu，<https://github.com/corrinehu/dsh-workbuddy-connect>）。
本项目以运行时依赖方式使用它，没有复制它的代码；署名与许可说明见 THIRD_PARTY_NOTICES.md。
- 非官方：与 WorkBuddy / WorkBuddy AI / CodeBuddy / 腾讯 / DeepSeek / HanaAgent 均无隶属关系，名字里的 hana- 只表示「给 HanaAgent 用的」。
- 不提供、也不收集任何凭据：桥接读取你本机已登录的桌面 App 会话，凭据不出本机（只监听 127.0.0.1，provider 声明为 authType: none，真正的凭据由上游插件自己管理）。
- 不保证长期可用：走的是客户端私有接口与本地登录态，上游改协议 / 改加密 / 加风控都会让它失效；上游插件自己也是同样的口径。
- 使用可能受上游服务条款约束，请自行判断。

维护方式

- 刻意不 vendor 上游代码：MIT 的署名义务跟着代码走，保持依赖关系能让归属永远清楚（上游是实现者，本项目是调用方 + HanaAgent 适配层），同时把协议变更的修复成本压到最低。
- 上游每次发版都会换 host-heartbeat-<hash>.js 的哈希名，本项目按结构识别（lib/ 下的模式 + index.js 里的 as 别名表），通常不需要跟着改。
- 升级上游：改 package.json 里的依赖版本 → npm install → 重启桥接。
- 上游真的改了内部布局时，plugin.mjs 会在启动时报出缺哪个导出，而不是静默出错。

想更「原生」的两条路

如果目标是「像装一个普通插件那样装进 HanaAgent」，还有两步可走：

| 方案 | 做法 | 代价 |
| B. 搬进原生插件 | 把桥接放进 ~/.hanako/plugins/<id>/，用 routes/.js（Hono）在 hana-server 进程内暴露 /v1，provider 的 baseUrl 指向插件路由 | 单包安装、没有独立进程与自启；仍依赖 dsh-workbuddy-connect 包 |
| C. B + vendor | 再把凭据解密 / 上游协议 / 目录那部分代码搬进插件 | 真正零依赖、可独立发布；但要自己跟 WorkBuddy 私有协议变更，且必须保留上游 MIT 声明 |

当前实现是「A. 外部进程 + 原生 provider 插件」：改动最小、上游一变跟着插件升级，代价是多一个常驻进程（有启动脚本和可选自启）。