桌面设置补全 VCPr0j3k7/dsh-desktop-settings

dsh-desktop-settings

License: MIT
Node.js

为 DeepSeek Harness (DSH) 桌面版补充官方设置中缺失的几节：README 翻译（DeepL）配置与连通性自测、GitHub 加速代理（自建反向代理）配置与连通性自测、插件市场缓存清理，以及 DeepSeek 开放平台的充值入口。

本插件以独立 bundle 形式装入 DSH profile，不修改任何官方代码。

目录

- 问题背景
- 环境要求
- 安装
- 卸载
- 工作原理
- 功能与设置项
- 配置文件
- HTTP 路由
- 刻意不实现的能力
- 启用条件
- 测试
- 已知限制
- 许可

问题背景

官方设置页已覆盖 account / general / models / plugins / subagent / web-search / agent-loop / shell 等节，但以下几项没有对应入口：

| 缺失项 | 影响 |
| README 翻译 | 插件市场中大量仓库只有英文 README，中文用户不易判断用途 |
| GitHub 加速代理 | 直连 GitHub 常因 TLS 握手与首字节延迟而缓慢或失败，缺少统一的出口配置 |
| 缓存清理 | 市场列表缓存、下载残留与翻译缓存没有清理入口 |
| 充值入口 | 余额不足时需要自行查找充值页 |

本插件只补齐这四项。以下三节刻意不提供：「应用名称」「DSH 数据目录（DSH_HOME）」「从其他 DSH 目录沿用配置」—— 它们的前提是外壳会划出一个完全隔离的数据目录，而官方桌面版不隔离 ~/.dsh，只存在一个家目录，因此这三节没有存在的前提。

环境要求

| 项 | 要求 |
| Node.js | ^22.19.0 \|\| >=24 |
| DeepSeek Harness | 官方桌面版（宿主半边依赖其 process.argv 布局与 profile 结构） |

宿主半边只依赖 ctx.webServer；客户端半边依赖官方客户端模块加载器与 @deepseek-ai/dsh-client-ui-slots 提供的槽位。

安装

用官方桌面版随包的 pnpm 装进目标 profile：

用官方桌面版随包的 pnpm 装进 profile
pnpm add "file:"
或者直接从 GitHub 装
pnpm add "github:VCPr0j3k7/dsh-desktop-settings"

示例（路径按实际安装位置替换）：

PNPM="D:/DeepSeek Harness/resources/runtime/pnpm/bin/pnpm.cjs"
NODE="D:/DeepSeek Harness/resources/runtime/primary-runtime/dependencies/node/bin/node.exe"
PROFILE="C:/Users//.dsh/profiles/desktop"

cd "$PROFILE"
"$NODE" "$PNPM" add "file:C:/path/to/dsh-desktop-settings"

装完还必须把包名加进 profile package.json 的 dsh.profile.bundles 数组，否则插件不会加载 —— 这是本项目的关键坑：

{
"dsh": {
"profile": {
"bundles": [
// …已有条目…
"dsh-desktop-settings"
]
}
}
}

pnpm add 只会把包写进 dependencies 并安装到 node_modules。声明了
dsh.bundle.patch 的插件必须在 dsh.profile.bundles 中登记才会被挂载；仅安装而不登记时，插件加载过程没有任何报错，界面上也看不出差异，只是它的设置分区与侧边栏入口都不会出现。
官方 CLI 的 dsh plugin add 会自动完成这一步，手动执行 pnpm 时需自行补齐。

安装完成后必须重启 DeepSeek Harness。宿主只在启动时装配插件树，运行中的实例不会热更新。

验证是否生效：

1. 重启后，设置页应出现「桌面设置补充」分区，侧边栏应出现「API 充值」入口；
2. 打开开发者工具，控制台应出现：

[dsh-desktop-settings] client factory 已执行 [dsh-desktop-settings] 宿主基址 = （相对路径）

第一行说明客户端半边已被加载，第二行说明它已连上宿主。只有第一行而没有第二行，表示客户端未能连上宿主。

卸载

cd "$PROFILE"
"$NODE" "$PNPM" remove dsh-desktop-settings

随后把 dsh.profile.bundles 中的 dsh-desktop-settings 条目一并删除，并重启 DeepSeek Harness。

若要临时停用而不卸载，只需从 dsh.profile.bundles 中移除该条目后重启。

工作原理

本插件由「两个半边」组成：

dsh-desktop-settings/
├── package.json 声明 dsh.bundle.patch 与 dsh.client.platform ├── cordis.patch.yml 宿主侧挂载声明 ├── index.js 宿主半边：Cordis 插件，在 /dsh-desktop-settings/api 下注册路由 ├── client.js 客户端半边：window.__ModuleLoader__.load({ id, factory }) └── host/ 适配层与服务实现 ├── env.mjs 把 process.argv 解析成路径与宿主上下文 ├── router.mjs HTTP 门面（前缀派发、{ok,data|error}、事件队列） ├── config.mjs 共享配置（/dsh-extras.json） ├── system.mjs 打开浏览器 / 选择目录 / 打开文件夹 ├── logger.mjs 输出捕获与日志环形缓冲 ├── electron-shim.mjs app.getPath('userData') 的替身 ├── yaml-libs.mjs 借用官方所使用的两个 YAML 库（多候选路径） └── services/ 翻译、GitHub 代理与设置辅助能力

宿主半边

1. 在 ctx.webServer 上注册一条 kind: 'prefix' 路由，前缀为 /dsh-desktop-settings/api，前缀内部的派发由 host/router.mjs 完成。注册点只有一处，卸载时由框架统一清理。
2. 所有响应统一为 { ok: true, data } 或 { ok: false, error }，业务失败也返回 HTTP 200；状态码只用于表达「路由不存在」这类传输层事实。
3. 进度事件进入环形队列（上限 400 条），客户端以 GET /events?since= 轮询增量。
不采用 SSE，是因为外壳对自定义 scheme 的转发是否会缓冲响应体无法确认，轮询没有这个未知数。

客户端半边

1. 页面由官方外壳提供，其来源（origin）有三种可能：宿主自身的 HTTP 地址、外壳的自定义 scheme（dsh-app://app/）、不透明来源（location.origin === "null"）。因此传输层在第一次请求时按顺序尝试候选基址（相对路径 → http://dsh.internal），并以 /info 的返回内容判定哪条真正可用。
2. 判定条件是 data.plugin 等于本插件 id，而不是「返回 200」—— SPA 的兜底路由会把未知路径也回成 200 加一段 HTML。
3. 选定基址后记录，后续请求直接复用；全部候选都不可用时回落到相对路径，并只在控制台留下一行提示，不反复重试。

功能与设置项

README 翻译（DeepL）

- 开关默认开启。翻译只对「基本不含中文」的文本调用：CJK 字符少于 30 个且占比低于 8% 时才发送请求，因此真正的中文 README 不会消耗配额。
- 关键词提取完全在本地完成，不受翻译开关影响，离线可用。
- 翻译结果按仓库缓存在磁盘上，重复打开不会重复计费。
- 连通性自测：POST /settings/test-translation 会翻译一句固定文本，返回检测到的源语言、目标语言与译文。若返回 456 表示配额用尽，403 表示密钥无效或 Free / Pro 端点选错。
- DeepL Free 版密钥以 :fx 结尾，必须使用 api-free.deepl.com 主机；认证头是 Authorization: DeepL-Auth-Key ，不是 Bearer。

GitHub 加速代理

- 默认关闭且地址留空。代理地址属于搭建者本人，插件不预置任何值，也不会把使用者的请求静默导到某台机器上。关闭时行为与没有该功能时完全一致。
- 开启条件是开关打开且地址非空；只开开关不填地址时静默回落到官方地址，而不是报错。
- 地址会被归一化：容忍未写协议、结尾多一个斜杠、反向代理挂在子路径下三种情况；协议只认 http / https，其它一律判为无效并回落直连。
- 路径前缀与上游域名一一对应，令牌、Accept 头与请求方法均原样透传：

| 上游域名 | 代理路径前缀 |
| api.github.com | /api |
| raw.githubusercontent.com | /raw |
| codeload.github.com | /codeload |
| github.com | /gh |
| objects.githubusercontent.com | /objects |
| release-assets.githubusercontent.com | /release-assets |

- 302 由本插件手动跟随（上限 6 跳），拿到 Location 后把其中的 GitHub 域名重新改写为代理地址再请求。若交给 fetch 自动跟随，它会直接连接重定向目标域名，等于绕开代理。
- 连通性自测：POST /settings/test-github-proxy 打两个探针 —— 代理根路径与一条真实的 raw 请求（electron/electron 的 README）。两者都必须通过：根路径正常只说明反向代理在运行，不代表它能连上 GitHub。
- 可选令牌 githubToken 默认留空。留空时按匿名请求发送（每小时 60 次）；填入个人访问令牌后走认证额度（每小时 5000 次）。令牌仅用于访问 GitHub API，不写入日志，也不随插件分发。

清理缓存

POST /market/clear 删除以下内容：

| 目标 | 说明 |
| /plugin-data/market-cache.json | 插件市场列表缓存 |
| /plugin-data/market-downloads | 下载残留目录 |
| /plugin-data/translate-cache/ | 翻译缓存 |

单个目标删除失败时会被跳过，不会让整个操作失败。

API 充值

- GET /recharge/status 返回充值页地址、用量页地址、API Key 的来源与当前数据目录。
- API Key 来源只做存在性探测，不读取也不回传密钥本体：优先看环境变量 DEEPSEEK_API_KEY，其次检查 /.credentials.yaml 中是否存在该键。
- POST /recharge/open 用系统默认浏览器打开 https://platform.deepseek.com/top_up。
打开地址前会校验协议，只放行 http / https。
- 侧边栏的「API 充值」图标点击后直接打开浏览器，同时主面板切到充值页。

配置文件

所有设置统一写入 /dsh-extras.json，与插件市场（dsh-plugin-market）共用同一份文件：写入方是本插件，读取方还包括需要翻译与下载的市场模块。采用文件而不是插件间 HTTP 调用，是因为文件不存在「另一个插件没装 / 还没启动」的时序问题。

| 字段 | 默认值 | 说明 |
| appName | "DeepSeek Harness" | 显示名 |
| githubProxy.enabled | false | 是否启用 GitHub 加速代理 |
| githubProxy.baseUrl | "" | 代理地址，形如 http://1.2.3.4:8080 |
| githubToken | "" | 可选的 GitHub API 令牌 |
| translate.enabled | true | 是否启用 README 翻译 |
| translate.endpoint | https://api-free.deepl.com/v2/translate | DeepL 端点 |
| translate.apiKey | "" | DeepL API Key |
| translate.targetLang | "ZH" | 目标语言代码（DeepL 使用大写） |
| translate.characterCount | 0 | 本地累计的已翻译字符数 |
| translate.maxCharacters | 4000 | 单个 README 最多翻译的字符数 |

配置读取不做缓存：文件只有几百字节，每次重读的成本可以忽略，换来的是「改完立刻生效」。
未知字段会原样保留，缺失字段回落到默认值。

首次运行时，若 /dsh-extras.json 尚不存在，会尝试从 %APPDATA%/DSH-Desktop/config.json（或 DSH Desktop、dsh-desktop）迁移一次 translate 与 githubProxy，使此前填写过的密钥与代理地址可以继续使用。

HTTP 路由

宿主半边在 /dsh-desktop-settings/api 前缀下提供以下路由。

| 方法 | 路径 | 说明 |
| GET | /info | 版本、数据目录、运行时目录、宿主状态与本插件 id |
| GET | /config | 读取完整配置（不含内部路径字段） |
| POST | /config | 深合并写入配置，返回写后的完整配置 |
| POST | /open-external | 用系统默认程序打开网址（仅 http / https） |
| POST | /pick-directory | 选择目录：优先官方 directoryPicker，退回 PowerShell 文件夹对话框 |
| GET | /restart-pending | profile 关键文件是否晚于宿主就绪时刻被修改 |
| POST | /restart-host | 刻意拒绝，见下文 |
| GET | /events | 增量拉取事件队列，参数 since |
| POST | /settings/test-translation | DeepL 连通性自测 |
| POST | /settings/test-github-proxy | GitHub 加速代理连通性自测 |
| POST | /market/clear | 清理市场缓存、下载残留与翻译缓存 |
| GET | /recharge/status | 充值页信息与 API Key 来源 |
| POST | /recharge/open | 打开充值页 |
| GET | /settings/inspect-homes | 刻意报「不适用」，见下文 |
| POST | /settings/import-from | 刻意报「不适用」，见下文 |

请求体上限为 8MB；未知路由返回 404 与 JSON 响应体。

刻意不实现的能力

以下三条路由存在，但会明确回报失败，而不是静默忽略或返回空结果。

跨 DSH_HOME 的配置探测与导入

GET /settings/inspect-homes 与 POST /settings/import-from 对应「从另一个 DSH 数据目录沿用配置」这一能力。它的前提是外壳划出完全隔离的数据目录，而官方桌面版不隔离 ~/.dsh，只存在一个家目录，因此该能力不适用。两条路由会返回可读的原因说明，而不是 404 —— 这样在有人手工构造请求时能直接得到解释。

host/services/settings-ops.mjs 中保留了该能力的完整实现，供需要隔离语义的环境使用。

重启宿主

POST /restart-host 会返回插件无法重启宿主进程，请手动退出并重新打开 DeepSeek Harness。

在某些外壳中 DSH 是其 spawn 出来的子进程，因此可以重启；但插件本身就是宿主加载的一部分，无法让宿主重启自己，而尝试杀死进程会一并丢失用户的会话。因此这里如实拒绝，由界面把「请手动重启」显示给用户。

启用条件

| 半边 | 启用条件 |
| 宿主半边 | 包名出现在 profile package.json 的 dsh.profile.bundles 数组中；宿主在启动时装配插件树 |
| 客户端半边 | dsh.client.platform === 'web'，且运行环境提供官方客户端模块加载器与 @deepseek-ai/dsh-client-ui-slots 槽位 |

客户端半边向以下槽位注册内容：

| 槽位 | 内容 |
| settings.section | 「桌面设置补充」分区（order: 30） |
| sidebar.panellist | 「API 充值」侧边栏入口（order: 44），点击即打开充值页 |
| main | 充值页主面板 |

官方桌面版的插件库开关在保存时会重写 dsh.profile.bundles（内部调用
sanitizeProfile(...) 清理非官方 bundle）。若插件突然失效，应首先检查该条目是否仍然存在。

测试

npm test
等价于
node test/check.mjs

test/check.mjs 为离线自检，只使用 Node 内置模块，不依赖 DSH 运行时，覆盖：

- 宿主半边可被 import，且导出 name / inject / apply；
- package.json 中 dsh.bundle.patch 指向的文件真实存在；
- dsh.client.platform === 'web'，且 exports['./client'] 指向的文件真实存在；
- 路由对齐：从 client.js 中提取全部被调用的路由路径，逐条确认在 index.js 的路由表中都有实现；
- host/config.mjs 的默认值包含 githubToken 字段。

端到端验证需要在真机上进行：安装并重启桌面版后，设置页应出现「桌面设置补充」分区，侧边栏应出现「API 充值」入口，两个「测试连通性」按钮应能返回结果。

已知限制

- 安装后必须手动登记 dsh.profile.bundles。 手动执行 pnpm 安装时不会自动登记，漏掉这一步的表现为插件完全静默 —— 无报错、无日志、界面上没有任何变化。
- 客户端半边能否连上宿主只能在真窗口里确认。 页面来源存在三种可能，因此传输层采用按顺序探测的方式；选错时会在控制台留下「宿主基址 = …」一行。
- 本仓库不包含反向代理的服务端配置。 代码注释中引用的 deploy/ghproxy.conf 是搭建反向代理时的 nginx 配置示例，未随本包分发。路径前缀与 location 必须与上表一致，对不上不会报错，只会安静地返回 404。
- 自建反向代理多为明文 HTTP。 启用 githubToken 时 Authorization 头会经它明文发出，开启前请确认链路可信；建议不要在启用代理的同时配置令牌。
- 插件无法重启宿主。 安装或修改配置后需要手动退出并重新打开 DeepSeek Harness。
- 翻译配额由本地计数近似统计。 translate.characterCount 只累加本插件发出的字符数，与 DeepL 账户的实际用量可能不一致，仅用于在设置页显示大致规模。
- 官方若变更 profile 结构或 process.argv 布局，宿主半边的路径解析会失效。 相关解析集中在 host/env.mjs，失效时表现为无法定位 profile 或随包 pnpm。

许可

MIT