DSH HUB
HomePlugin StorePlugin PacksCommunityRankingsResourcesPublish Guide
Plugin source
Back to catalog

VCPr0j3k7 /

VCPr0j3k7/dsh-desktop-settings

Verified

Settings page for the DeepSeek Harness desktop shell — README translation, GitHub proxy, market cache, and account top-up

★ 0 Stars0 Forks0 IssuesN/A Community rating0 Confirmed installs
View on GitHub
READMESource: main@955b6e74

dsh-desktop-settings

License: MIT Node.js

English | 简体中文

为 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_HOME>/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=<seq> 轮询增量。 不采用 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 <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 删除以下内容：

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

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

API 充值

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

配置文件

所有设置统一写入 <DSH_HOME>/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_HOME>/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

—/ 5

No ratings yet

Verified DSH bundle

Commit 955b6e74c6fe

Community comments

No comments yet. Be the first to write one.

DSH HUB

A community index for DSH plugins. Not an official GitHub or DeepSeek AI product.

CommunityResourcesAPIAbout