dsh-widgets-plugin

dsh 小组件集合

一个面向 DeepSeek Harness 的小组件（挂件 / widgets）monorepo。这里主要制作一些 「小组件」：每个组件都是可独立发布、可在任意 DeepSeek Harness 实例中安装的插件， 浏览器端通常以 shell.overlay 浮动挂件（或输入框装饰）的形式呈现，可拖动、可缩放、 可折叠、可配置。当前仓库包含五个小组件：

小组件 · 包 · 说明 余额看板 · @dsh-plugins/balance · 一个包 = ctx.balance 能力缝隙 + 5 个厂商 Provider + 用户绑定设置 + 浮动余额看板；支持单账户 / 多账户视图、趋势涨跌、动态滚动、缩放与角落吸附，供应商配置在「插件」页 → 「小组件」tab 里该行的「配置」弹窗中完成；面板为液态玻璃材质 Token 暴击挂件 · @dsh-plugins/client-ui-token-crit · 浮动的 token 用量计量挂件；实时显示当前会话累计 token 用量，增长时触发网游风格暴击动效，附带可配置面板 会话监控看板 · @dsh-plugins/client-ui-session-monitor · 浮动的会话监控面板；列出正在执行的会话与运行状态，会话完成一轮时主动弹提醒（可自动消失或需确认），点击任意会话一键跳转；面板为液态玻璃材质 卡片容器 · @dsh-plugins/client-ui-card-container · 浮动的卡片容器面板；开启后把其他小组件拖进一个整齐、等间距的卡片网格集中摆放（浮窗自动收起，可拖拽排序 / 移出）；面板为液态玻璃材质 彩虹流光 · @dsh-plugins/client-ui-rainbow-flow · 输入框装饰（非浮窗）：会话运行时输入框四周环绕一圈柔和的彩虹光晕，像呼吸一样明暗脉动（内部透明不遮输入），呼吸节奏随每秒输出 token 数动态变化，工具行带开/关开关

除了上面五个浏览器内小组件，还有两种「桌面端」形态：官方 DeepSeek Harness 桌面端 （Electron，跑的就是同一份 Web 应用与同一套插件，装法见「安装 → 方式四」，适配细节见 AGENTS.md「DSH 桌面端（Electron）」），以及本仓库自带的 Windows 桌面悬浮窗应用 （desktop/dsh-session-desktop/，Tauri 2，非 npm 包）——后者在官方桌面端之外单独提供一块 常驻置顶小窗（详见文末「桌面悬浮窗」）。

预览

动图（GIF）演示实际交互与动效，静态图为多状态拼图；全部预览来自真实运行中的

Harness 实例。挂件均可拖动、缩放、折叠，完整操作见 使用 及各子包 README。

浮动挂件

余额看板 · Token 暴击挂件 · 会话监控看板 · 卡片容器 · · · 单 / 多账户、趋势涨跌、缩放吸附 · 实时用量 + 暴击动效 · 会话列表、完成提醒、点击跳转 · 拖入网格停靠成卡片，可排序 / 移出

输入框装饰

彩虹流光 会话运行时输入框四周的呼吸彩虹光晕（明暗脉动 + 轻微缩放），呼吸节奏随输出 token 速率变化

插件页 →「小组件」tab

小组件管理 「插件」页 → 「小组件」tab 启用 / 关闭小组件；带配置的挂件（如余额看板）点该行的「配置」按钮在独立弹窗中设置；未安装挂件的「安装指引」弹窗也在这里

结构

包 · 角色 @dsh-plugins/balance · 合并后的余额插件（Host 缝隙 + 厂商 + Web 看板，单插件行）：ctx.balance 绑定提供商路由并应答 balance/query / balance/list Remote；5 个厂商 Provider + 设置驱动的用户绑定 + /_dsh/balance/settings Web 路由；浏览器半挂载 Remote 并注册看板挂件与配置面板 @dsh-plugins/client-ui-token-crit · Token 暴击挂件（浏览器端，纯 UI） @dsh-plugins/client-ui-session-monitor · 会话监控看板（双半：Host 半 turn/end 原因跟踪 + 状态路由；浏览器端列出运行中会话、按状态提醒、点击跳转） @dsh-plugins/client-ui-card-container · 卡片容器（浏览器端，纯 UI）：声明 widgets.card 子槽并渲染停靠卡片，用影子条目隐藏已停靠挂件的浮窗，自带 token-crit / session-monitor / balance 的紧凑卡片视图 @dsh-plugins/client-ui-rainbow-flow · 彩虹流光（浏览器端，纯 UI）：会话运行时输入框四周的呼吸彩虹光晕（conversation.input.left），明暗脉动节奏随输出 token 速率变化，工具行带开/关开关 @dsh-plugins/client-ui-widget-manager · 小组件管理（浏览器端）：在「插件」页贡献「小组件」tab，列出小组件并支持「添加 / 关闭」，为带配置的挂件提供行上的「配置」弹窗与「安装指引」弹窗；不再注册设置页 @dsh-plugins/dsh-widgets-plugin · 可安装 bundle：一层挂载以上全部插件 desktop/dsh-session-desktop/ · Windows 桌面悬浮窗应用（Tauri 2，非 npm 包，可选）：无边框/透明/置顶小窗加载会话监控独立挂件页，托盘唤回，点击行直达已打开的 Harness 标签页（未开才回退浏览器）。官方 Electron 桌面端里看板就在主窗口内，不需要该壳

完整的组件管理列表（组件明细、插槽注册、构建产物、依赖关系、维护清单）见

COMPONENTS.md。

开发新小组件并接入「小组件管理」（「插件」页的「小组件」tab，含配置弹窗）的完整指南见

WIDGET-DEVELOPMENT.md。

前置条件

• 宿主 DeepSeek Harness 版本需已把 ./remote（balance/query、balance/list）挂载进 client 的 api-remotes（Harness 仓库内已在 packages/api/remotes 挂载 balanceRemote）。若宿主未挂载，Host 侧服务仍可安装，但余额看板无法查询余额（表现为「未绑定」）。Token 暴击挂件仅依赖标准 useSessions 会话投影；会话监控看板依赖标准 useSessions 加自身的 /_dsh/session-monitor/status 轮询（Host 半，核心 dsh-session 事件，无此 remote 要求）。
• Host 需要 @deepseek-ai/dsh-settings 与 @deepseek-ai/dsh-credentials 能力（web profile 自带）。

构建

pnpm install
pnpm build   # 等价于 node scripts/build.mjs

pnpm 版本由 root package.json 的 packageManager 固定（pnpm@11.7.0，与官方 deepseek-harness 同款做法）；pnpm/action-setup 会按该字段安装对应版本，本机用 corepack 管理时也会读取同一字段。Node 引擎约束见 root engines （^22.19.0 || >=24.0.0）。

pnpm build 用 esbuild 构建各包的 Host 产物（lib/index.js），用 Vite library mode（官方 deepseek-harness 的 Web 工具链）构建浏览器端 bundle （lib/client.js，ModuleLoader CJS + 内联 CSS），并额外用 tsc 从 src 重新生成 @dsh-plugins/balance 的类型面（lib/types/**），末尾校验所有 exports 目标文件存在。包自带构建产物，安装即用，无需在安装端构建。

@dsh-plugins/balance 的 lib/typert.*（生成的 Remote 线协议）由 typert codegen

产出，不在 pnpm build 内重建；仓库内没有生成工具，因此这 4+1 个文件已**提交进

git**（.gitignore 有豁免段），随包发布（files: ["lib"]）。改 Remote 线协议时

需要从上游/typert codegen 重新生成后提交。

发布

所有包都是 @dsh-plugins/* scoped 包，各 package.json 已带 "publishConfig": { "access": "public" }；7 个包必须一起发——bundle 的依赖是精确 版本（0.1.0），只发 bundle 会在安装端 404。

发布前置三步（缺任一步都发不出去）：

1. 让发布账号拥有 `@dsh-plugins` scope。该 scope 下 7 个包都还没发布（npm view 404），

但名字是否已被他人占用无法只读确认——先确认可用：空着就登录同名账号，或在 npm 建同名 org（公开包免费）并把发布账号加进去；若已被占用只能换 scope（那要同步改 7 个包名、 cordis.patch.yml、widget-manager 目录名与全部文档）。scope 不属于发布账号时 publish 会 403（npm 的既定行为）。

1. 凭据。本地：npm login 后执行下面的命令；CI：publish.yml

已接好 pnpm -r publish --no-git-checks --access public，在仓库 Settings → Secrets 配好 NPM_TOKEN（Automation token，需 publish 权限）即可。

1. 打版本 tag。版本号在各 package.json 里（7 个包保持一致）：

git tag v0.1.0 && git push origin v0.1.0   # 推 tag → publish.yml 自动发布

本地发布与打包校验：

pnpm -r publish --no-git-checks --access public   # 与 pnpm run publish:all 效果相同（各包已带 publishConfig.access）
pnpm -r pack --pack-destination <目录>            # 检查产物清单（CI 用 --dry-run）

发布后自检：

npm view @dsh-plugins/dsh-widgets-plugin version
dsh plugin --profile <name> add @dsh-plugins/dsh-widgets-plugin

bundle 的 workspace:* 依赖在打包时会被自动改写成实际版本号（这里是 0.1.0）。

安装

四种方式：本地一键安装（推荐——一条命令，link: 直连本仓库，改代码即生效）、 发布安装（装 npm 上的预构建产物，也是唯一一条命令交给别人的方式）、手动 CLI 七条（与方式一等价，逐条可见）、官方桌面端（Electron）安装（同一份 bundle， profile 固定为 desktop）。手动 patch 见文末「安装（手动）」。

**可安装的是 bundles/dsh-widgets-plugin（包名 @dsh-plugins/dsh-widgets-plugin），

不是仓库根目录。** 仓库根是 private 的 workspace 根（包名 dsh-widgets-plugin），

没有 dsh.bundle：装它会打印 `dsh: warning: dsh-widgets-plugin declares no

dsh.bundle — installed as a plain dependency, not a profile layer`（退出码 0），

profile 里一层都没挂上。

方式一：本地一键安装（推荐）

在仓库根执行（profile 名自取，例如 web / desktop）：

pnpm install:profile web

它按顺序执行 7 条 dsh plugin --profile web add ——先 bundle 目录，再是 6 个 packages/* 插件包（link: 直连，不拷贝；这 6 条各自打印一条 declares no dsh.bundle 警告是预期的，它们本来就是普通依赖），最后回读 profile 清单确认 dependencies 与 dsh.profile.bundles 两层都写上了——两层缺一都不挂载。 参数写成路径而不是 profile 名时会直接报错，并提示可安装的是哪个目录；非法/保留的 profile 名 （含分隔符、.、..、node_modules、Windows 上含 %…% 的写法）也会被拦下。脚本另外做三件 事：校验 CLI 版本 ≥ 0.2.0-rc.2（旧壳的种子模块表加载不了本仓库的浏览器半）、link 模式下检查 lib/ 产物是否缺失或比源码旧（lib/ 是 gitignore 的，缺了先 pnpm build）、目标 profile 不存在时明确告知「将新建」并列出相近的名字（防拼错）。常用选项：

pnpm install:profile desktop --cli "<桌面端安装目录>/resources/runtime/cli/bin/dsh.cmd"
pnpm install:profile web --dry-run     # 只打印命令，不检查 CLI、不落地
pnpm install:profile web --mode npm    # 装 npm 发布版（见方式二）

bundle 层属于启动时组合，装完必须重启宿主：Web 端重启 dsh web；官方桌面端 完全退出（含托盘）再重开。验收：

dsh <name> --dump-config    # 应出现 "# == @dsh-plugins/dsh-widgets-plugin" 层，以及 6 条 name: '@dsh-plugins/*' 行

改代码后先在仓库根 pnpm build 更新 lib/ 产物（浏览器半会被客户端 HMR 热替换， Host 半改动需重启）。

方式二：发布安装（给别人用的唯一方式）

7 个包发布到 npm 后（前置三步见「发布」），目标机器一条命令：

dsh plugin --profile <name> add @dsh-plugins/dsh-widgets-plugin

pnpm 会把 6 个 @dsh-plugins/* 作为普通依赖装进 profile，@deepseek-ai/* peer 由 运行时提供（同一份实例），不需要再逐个 link:；桌面端「插件」页走的是同一条路。 bundle 的 cordis.patch.yml 会插入 balance、ui-token-crit、ui-session-monitor、 ui-card-container、ui-rainbow-flow、ui-widget-manager 六行，一次挂载全部组件。 发布物自带构建产物（lib/），安装端无需构建授权。

方式三：手动 CLI 七条（与方式一等价）

想逐条看清、或装进别的 profile 时，手打这 7 条（把 `` 换成本仓库绝对路径， 正斜杠更稳）：

dsh plugin --profile <name> add <repo>/bundles/dsh-widgets-plugin
dsh plugin --profile <name> add <repo>/packages/dsh-balance
dsh plugin --profile <name> add <repo>/packages/dsh-client-ui-token-crit
dsh plugin --profile <name> add <repo>/packages/dsh-client-ui-session-monitor
dsh plugin --profile <name> add <repo>/packages/dsh-client-ui-card-container
dsh plugin --profile <name> add <repo>/packages/dsh-client-ui-rainbow-flow
dsh plugin --profile <name> add <repo>/packages/dsh-client-ui-widget-manager

别把 `` 本身（仓库根）当包传给 `dsh plugin add`——那正是开头那条 declares no dsh.bundle 警告的来源。首次使用会初始化 profile （@deepseek-ai/dsh-base 作为第一个 bundle）。

不支持 `github:` 直接安装：git 安装拉取的是源码、不跑任何构建，且 bundle 的

workspace:* 依赖在 workspace 之外无法解析（ERR_PNPM_WORKSPACE_PKG_NOT_FOUND）。

也不支持 tarball 离线交付：pnpm -r pack 会把 bundle 的 workspace:* 改写成

精确版本（实测 tgz 里是 "@dsh-plugins/balance": "0.1.0"），安装端 pnpm 仍会去

registry 取这 6 个包——「先装 6 个 tgz 再装 bundle」「7 个 tgz 一次装」「profile 里写

pnpm.overrides → file:*.tgz」实测全部 ERR_PNPM_FETCH_404。给别人用请走方式二

（npm 发布）。

方式四：官方桌面端（Electron）

官方桌面端跑的是同一份 Web 前端与同一套插件模型，所以装法一致，只是 profile 固定为 desktop、应用要先完全退出（bundle 层属于启动时组合，装完重启生效），且 CLI 要用 桌面端自带的那份：

pnpm install:profile desktop --cli "<桌面端安装目录>/resources/runtime/cli/bin/dsh.cmd"

等价的手打形式：用上面那份 dsh.cmd 执行 plugin --profile desktop add /bundles/dsh-widgets-plugin，再加方式三里的 6 条。 link: 安装不会装 bundle 的依赖，所以要**把 6 个 @dsh-plugins/* 包也 link: 进同一个 profile**（否则插件会从仓库路径加载第二份 @deepseek-ai/*）——方式一/三已经替你做了。 隔离 profile 预检与桌面端浮窗顶栏避让见 AGENTS.md「DSH 桌面端（Electron）」。

安装（手动）

在 profile 的 cordis.patch.yml（或自定义 --patch）加入：

- insert:
    - id: balance
      name: '@dsh-plugins/balance'
      config:
        requestTimeoutMs: 10000
        newApiBaseURL: http://localhost:3000   # New API 自托管实例地址
        bindings: []
    - id: ui-token-crit
      name: '@dsh-plugins/client-ui-token-crit'
    - id: ui-session-monitor
      name: '@dsh-plugins/client-ui-session-monitor'
    - id: ui-card-container
      name: '@dsh-plugins/client-ui-card-container'
    - id: ui-rainbow-flow
      name: '@dsh-plugins/client-ui-rainbow-flow'
    - id: ui-widget-manager
      name: '@dsh-plugins/client-ui-widget-manager'