dsh-plugins

dsh-plugins — dsh 外部插件工作区

本工作区汇集为 dsh（DeepSeek Harness）开发的外部插件（out-of-tree bundles）。每个插件是一个独立目录（独立的 npm 包），可单独构建、打包、分发、安装到任意 dsh profile。

• 工作区根 pnpm install 统一为所有插件建立可解析的依赖树（link: 装进 profile 后，Node 按插件真实路径解析其 @deepseek-ai/* 导入，插件必须自带依赖）
• 安装到 profile：pnpm dsh plugin --profile <name> add <插件路径>
• 各插件的完整文档见其目录下的 README.md；本文件只做目录与速览

插件一览

插件	目录	版本	一句话作用
dsh-balance-view	dsh-balance-view/	0.1.0	DeepSeek 账户余额查看器：独立查看页 + GUI 悬浮徽章（双半侧 bundle）
dsh-vision	dsh-vision/	0.1.0	为纯文本模型透明补充视觉能力：后台图片转换 + vision 工具 + 视觉端点设置页（双半侧 bundle）

新增插件时：在 pnpm-workspace.yaml 的 packages 里登记目录，然后在上表追加一行、补一个下面的详解小节。

---

dsh-balance-view — DeepSeek 余额查看器

在 dsh GUI 里随时查看 DeepSeek 账户余额，两个入口共享同一套浅色 UI：

• 独立查看器页面 GET /balance-monitor/ — 自包含静态页（余额 JSON + 状态 + 更新时间，30s 轮询）
• GUI 悬浮徽章 — 左下角蓝色渐变胶囊（带鲸鱼图标），实时显示余额；点击弹出内嵌面板，按住可随意拖动，右上角 ✕ 关闭；60s 轮询
• 密钥不进浏览器 — 余额请求只在 Host 半侧发起（credentials 服务 → 环境变量回退），浏览器只拿结果 JSON

功能细节

• 卡片展示总额（蓝色高亮）+ 下方 11px 小字明细：赠金余额（琥珀色）/ 充值余额（绿色）——数据来自 API 的 granted_balance / topped_up_balance（即当前未过期的赠金与充值）
• 浅色系主题（浅灰背景 + 白卡片），状态文字跟随可用性着色（绿/灰/红）
• 徽章可自由拖动（Pointer Events，带边界约束，拖动不会误触发点击）
• 独立页跟随 src/viewer/style.css 主题变量，GUI 面板回落到组件内嵌浅色变量

架构要点

双半侧 + 单一 UI 源 + 三构建产物：

src/index.ts        → lib/index.mjs       Host 半侧（Node）：路由 + 余额请求
src/client/index.ts → lib/client.js       Client 半侧（浏览器）：shell.overlay 徽章
src/viewer/         → lib/page/viewer.js  独立页（IIFE，react 内联）
                     + index.html/style.css（构建时复制）

查看器 UI 只在 src/viewer/Viewer.tsx 实现一次，独立页与徽章面板共用（无 iframe）。

安装 / 卸载

# 先在工作区根安装依赖 + 构建
pnpm install
pnpm --dir dsh-balance-view build

# 加载到 profile（link: 开发模式，改代码免重装）
pnpm dsh plugin --profile web add ./dsh-balance-view
pnpm dsh web                       # 打开 http://127.0.0.1:3080/balance-monitor/

# 卸载
pnpm dsh plugin --profile web remove dsh-balance-view

配置（默认值）

键	默认值	说明
apiKeyEnv	DEEPSEEK_API_KEY	密钥来源的环境变量名（兼作 credentials 凭据名）
baseUrl	https://api.deepseek.com	余额 API 基址，端点 {baseUrl}/user/balance
timeoutMs	10000	单次请求超时（毫秒）
routePrefix	/balance-view	页面/API 路由前缀（本插件 cordis.patch.yml 默认 /balance-monitor，徽章硬编码同前缀）

分发

pnpm --dir dsh-balance-view pack      # tarball（发给别人 / 内部）
# 或发布 npm：先移除 package.json 的 "private": true，再 pnpm publish

完整文档：dsh-balance-view/README.md

---

dsh-vision — 纯文本 DeepSeek 路由的多模态桥

为纯文本模型透明补齐“看图”能力，双半侧 bundle（Host 中间层/工具 + 浏览器设置页）：

• 保持原路由 — 不注册 (dsh-vision) provider、不改默认模型；用户继续选择原 provider/model
• 自动判断 — 原模型支持图片就原样直传；纯文本模型才在后台调用独立视觉端点并替换图片块（含嵌套 tool-result）
• 完整图片准入 — Web 上传与 read_image 都可使用，会话日志仍保存原始图片，只有发往纯文本模型的请求副本被转换
• 前端设置页 — 设置 → 视觉 配置 OpenAI 兼容端点、模型、上下文大小、输出 token、超时和 API Key；除只写密钥外均保存后回显，并支持使用当前草稿测试连接

安装 / 使用

pnpm install && pnpm --filter dsh-vision build
pnpm dsh plugin --profile web add ./dsh-vision
# 设置 → 视觉：填写端点、模型和预算，单独保存 API Key，然后测试连接
# 会话继续使用原模型；上传图片时插件会自动决定直传还是后台转换

验证

pnpm --filter dsh-vision verify   # 离线验证：转换、透明中间层、端点、配置与密钥路由
node dsh-vision/scripts/smoke.mjs   # 打包产物冒烟（host 加载 + client bundle 包裹）

完整文档：dsh-vision/README.md

---

公共约定

• src/ 源码区 / lib/ 产物区：lib/ 由 pnpm run build（tsdown）生成，已 gitignore，可随时删除重建，但勿手改（包入口直接指向它）
• 依赖与 dsh 主机同版锁定（@deepseek-ai/*、schemastery、cordis 等），保证 link:/tarball 安装后在目标机器可解析
• bundle 声明：package.json 的 dsh.bundle（配置层 patch）、dsh.client（浏览器半侧注入）与 exports 是插件被 dsh 识别/加载的依据
• 类型检查：npx tsc --noEmit -p <插件目录>（tsconfig 已开 allowImportingTsExtensions，ESM 相对导入带扩展名是 tsdown 的要求，非报错）