dsh-plugin-workbuddy-gateway

在 DSH 的设置页管理 WorkBuddy 账号、本地网关和模型路由。网关将 WorkBuddy 国际版或国内版的订阅接口转换为 OpenAI 兼容接口，供 DSH 使用。

中文 | English

当前版本：0.2.5。 安装建议固定到 Git 标签 v0.2.5；回退方法见下文。此仓库提供源码安装，不要求安装插件市场。

功能

• 在「设置 → WorkBuddy」启动、停止、重启网关，查看端口、进程和日志。
• 从桌面端导入账号，或通过浏览器 OAuth 授权登录。
• 显示账号积分余额、最近确认的签到领取状态，支持刷新积分和国内版签到。
• 桌面账号导入时，国内版尝试签到，随后读取积分；国际版只读取积分。
• 启用、停用或移除账号；网关在同一区域内选择可用账号。
• 将网关模型写入 DSH 的 llm-pi-ai 提供方配置。

本插件不是 WorkBuddy / 腾讯官方集成，依赖订阅端内部接口和 DSH 内部扩展接口。接口变化可能导致功能失效，使用也可能触发服务条款限制或账号风控。

环境要求

Windows 自动尝试 python、python3；macOS / Linux 自动尝试 python3、python。也可以在设置页指定 pythonPath。

安装

以下示例使用已存在的 web profile。默认目录是 ~/.dsh/profiles/web；设置了 DSH_HOME 时使用 $DSH_HOME/profiles/web，自定义 profile 则替换 web。修改前建议备份该目录中的 package.json、锁文件及 patch 文件。

方式一：直接安装固定版本

dsh plugin --profile web add "github:Acoder416/dsh-plugin-workbuddy-gateway#v0.2.5"

这个命令安装包依赖，还需要启用插件：编辑 profile 的 package.json，在现有 dsh.profile.bundles 数组末尾添加 dsh-plugin-workbuddy-gateway。保留原有字段和其他 bundle，下面仅展示相关部分：

{
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@deepseek-ai/dsh-web-app",
        "dsh-plugin-workbuddy-gateway"
      ]
    }
  }
}

停止并重新启动 DSH，再刷新浏览器。bundle 在 DSH 启动时加载，仅点击网关的「重启」不足以加载新的宿主插件代码。

方式二：手动克隆并连接本地目录

适合希望保留源码、手动更新或调试的用户。将源码放在长期保留的目录，后续不要删除或移动它。

git clone --branch v0.2.5 https://github.com/Acoder416/dsh-plugin-workbuddy-gateway.git
cd dsh-plugin-workbuddy-gateway
npm run preflight

Windows PowerShell：

$dshPluginDir = (Get-Location).Path
$dshProfileDir = if ($env:DSH_HOME) {
  Join-Path $env:DSH_HOME 'profiles/web'
} else {
  Join-Path $env:USERPROFILE '.dsh/profiles/web'
}
pnpm --dir $dshProfileDir add "link:$dshPluginDir"

macOS / Linux：

dsh_plugin_dir="$PWD"
dsh_profile_dir="${DSH_HOME:-$HOME/.dsh}/profiles/web"
pnpm --dir "$dsh_profile_dir" add "link:$dsh_plugin_dir"

然后按方式一编辑 dsh.profile.bundles，重启 DSH 并刷新页面。插件以 JavaScript 和 Python 源文件交付，无需编译。

可选：使用 profile patch 挂载

安装依赖后，也可以在 profile 的 cordis.patch.yml 中添加：

- insert:
    - id: workbuddy-gateway
      name: dsh-plugin-workbuddy-gateway

bundle 和显式 patch 只能选一种。 使用 patch 时不要把本插件加入 dsh.profile.bundles，否则会出现 duplicate loader entry id: workbuddy-gateway。首次配置后重启 DSH。

第一次使用

1. 打开「设置 → WorkBuddy」，确认网关已启动。默认监听 127.0.0.1:18088。
2. 选择国际版或国内版区域；两个区域的账号和模型分别管理。
3. 点击「扫描桌面端账号」并导入，或选择「浏览器授权登录」并完成授权。
4. 检查账号是否启用、是否有积分。导入后的同步需要上游接口可用；失败时可手动刷新积分或重试签到。
5. 点击「写入模型路由」（开启自动维护时会自动尝试写入），刷新页面后在 DSH 模型选择器中选择模型。

网关启动和重启时会在监听前应用所选区域，区域确认成功后才显示「运行中」；确认失败会停止网关并显示错误。区域状态保存在账号目录的 active_realm.json 中；未指定区域时读取该记录。

积分与签到

「刷新积分」查询余额；上游下发的精确值保留到小数点后两位，已失效的资源包不计入可用余额。「签到」调用国内版每日领取接口。上游返回 code: 10001（包括 HTTP 错误响应）时，表示当天已经领取，插件也会保存该结果。

刷新积分需要实时请求上游，每个账号一次，连接不稳定时会先重试再返回结果。因此「刷新全部积分」在账号较多或网络较差时（例如经由代理访问国际版）可能要等待较久，也可能失败；只关心一个账号时，用账号卡片上的「刷新积分」。

账号卡片显示的是最近保存的领取状态和确认时间；国内版会按本地日期判断，昨天或更早的记录在今天自动显示为「未签到」，不会跨天沿用。页面读取本地状态不会额外请求上游；需要立即确认时点击签到。国际版不提供此签到功能。

「领取积分」会调用内置网关的成长任务流程，与每日签到是不同操作。它依赖上游活动接口，耗时和可用性可能变化；失败时查看操作提示，不保证获得积分。

桌面端凭证目录

扫描只识别目录中的 workbuddy-desktop-ai.info（国际版）和 workbuddy-desktop.info（国内版）。

新版桌面端可能将昵称和登录令牌保存为 $wbEncrypted 加密对象。插件会用文件名代替不可读的昵称；登录令牌加密时显示提示并禁用导入。请选择对应区域，点击插件内的「浏览器授权登录」添加账号。插件不解密或修改桌面端文件，也不会读取带时间戳的备份或 .logged-out 文件。未找到凭证时会显示提示；明文凭证仍可直接导入。

macOS / Linux 的默认目录尚未通过真实桌面端安装验证。如果扫描不到，先确认桌面端已登录及文件实际位置，再指定目录。macOS / Linux 示例：

export WORKBUDDY_DESKTOP_AUTH_DIR="/absolute/path/to/auth"
dsh --profile web

Windows PowerShell 示例：

$env:WORKBUDDY_DESKTOP_AUTH_DIR = 'D:\path\to\auth'
dsh --profile web

此变量必须由启动 DSH 的进程传给网关；修改后需重启 DSH。也可以直接使用浏览器授权。

多账号行为

区域切换同时更新账号列表与模型清单；开启自动维护模型路由时，也更新 DSH 的模型选项。页面分别显示已选区域、网关当前区域和模型清单所属区域。关闭自动维护时，需要手动点击「写入模型路由」。网关未确认切换成功时不会保存新区域。

没有会话绑定时，网关轮询同一区域的可用账号；同一会话优先复用已绑定账号。429 或上游业务码 6004 会记录该账号、该模型的限流恢复时间，并尝试同区其他可用账号；该账号的其他模型不受这条记录影响。到期只表示可以再次尝试，不保证上游一定接受请求；账号有积分也不代表该模型未触发频率限制。

恢复时间优先读取上游消息中带 UTC 偏移的日期时间，其次使用 Retry-After；两者都不可用时，默认等待 300 秒。可在启动 DSH 前设置环境变量 WB_RATE_LIMIT_FALLBACK_SECONDS 为正数秒数，修改后重启 DSH。独立运行网关时也可使用 --rate-limit-fallback-seconds。限流记录保存在账号文件中，重启、重新导入或切换启用状态不会清除尚未到期的记录。账号卡片显示受限模型和预计恢复时间；账号可用数量不代表每个模型都可用。

同区所有候选账号都被该模型的限流记录阻止时，后续请求直接返回 429，错误信息包含最早的 resetAt（Unix 秒），到期前不再请求上游。多个账号均返回 429 不能据此判断为共享 IP 限流；各账号的恢复时间分别保存。

上游业务码 11140 结合官方客户端同样报错时，应解释为账号被上游风控或限制，不能归因于提示词。网关会标记该账号暂时不可用、尝试同区其他账号，并返回上游的 Trace ID 和原始说明；DSH 不再将它显示成 API 密钥无效。该限制需要联系 WorkBuddy 官方处理，修改提示词、重试或切换本地模型无法解除。其他 401、403 保留鉴权冷却并尝试同区其他账号；502、503、504、SSL 断连和连接超时会尝试其他账号，但不使账号进入冷却。一次请求中每个候选账号最多尝试一次；全部失败时仍返回错误。流式响应开始后不会重放请求，账号不会跨区域使用。

可用账号数排除停用、冷却、缺少令牌及已过期且无法刷新的账号；历史错误本身不会阻止冷却结束后的重试。可刷新凭证只表示允许尝试刷新，不保证刷新或模型请求成功。积分余额、模型限流和账号可用状态分别显示。

WorkBuddy 桌面端不必常驻。网关独立保存导入后的凭证；退出桌面端不保证这些凭证立即失效。

数据与安全

未设置 DSH_HOME 时默认使用 ~/.dsh。账号文件包含敏感令牌，不要上传到 GitHub、共享网盘或反馈截图中。保持本地监听和接口鉴权；停用或移除账号可以阻止当前网关继续选择它，但不能代替在服务端撤销授权。

升级与回退

升级前停止 DSH，并备份 profile 配置和 $DSH_HOME/workbuddy/。备份包含凭证，应保存在仅自己可访问的位置。

直接安装方式：

# 升级到本版
dsh plugin --profile web add "github:Acoder416/dsh-plugin-workbuddy-gateway#v0.2.5"

# 回退到已有旧版标签
dsh plugin --profile web add "github:Acoder416/dsh-plugin-workbuddy-gateway#v0.2.4"

本地 link: 方式，在插件源码目录执行：

git status --short
git fetch origin --tags
git switch --detach v0.2.5
# 回退时改为：git switch --detach v0.2.4

如果存在本地修改，先自行保存，避免覆盖。切换版本后重启 DSH 并刷新页面。link: 安装的版本由本地目录决定，重新安装其他目录中的副本不会更新正在使用的插件。

回退代码不会撤销积分领取、还原账号操作或自动恢复模型路由。需要恢复配置时使用自己的备份。版本变化见 CHANGELOG.md。

排障

卸载

1. 在设置页移除模型路由并停止网关，然后停止 DSH。
2. 从 dsh.profile.bundles 移除插件名，或删除显式 patch 中的 workbuddy-gateway 条目。
3. 执行 dsh plugin --profile web remove dsh-plugin-workbuddy-gateway。
4. 重启 DSH。若不再保留账号，可自行删除 $DSH_HOME/workbuddy/，并清理凭据库里的 WORKBUDDY_API_KEY。

开发与验证

npm test
npm run test:python
npm run preflight
node scripts/check-package.mjs

test:python 使用 python 命令；只有 python3 的环境可执行 python3 -m unittest discover -s tests -p 'test_*.py'。回归测试使用模拟接口，不消耗真实账号额度，也不能替代 macOS 实机验证。贡献约定见 CONTRIBUTING.md。

来源与许可证

插件使用 MIT 许可证。内置网关来自 ardeyouxipianyi/workbuddy2api-intl，亦为 MIT；本版包含凭证目录、导入积分同步和签到结果处理方面的本地修改，详见 THIRD_PARTY_NOTICES.md。