ds-balance — DeepSeek 余额查询插件（文件式 / 默认激活）

介绍：给 DeepSeek Harness 使用的余额查询插件，目前只支持 DeepSeek，其他 API 后续支持接入。

在 DeepSeek Harness 左下角（输入框工具行左端）显示一个小字余额条 ¥ 110.00 + ↻ 刷新按钮，定时自动刷新；设置页可配置刷新间隔与低余额告警阈值（低于阈值余额变红 ⚠ 并提示充值）；对话里说「查一下余额」也可走 deepseek_balance 模型工具。随 DSH 启动自动加载，无需审批。

---

安装方式 0：把这段话发给 AI，自动安装（推荐）

把下面代码块整段发给 DeepSeek Harness 的助手（或任何能操作文件系统的 AI 编码助手）， 它就会自动完成安装接线；你也可以直接对助手说「按 README 的安装方式 0 帮我装」。

你是 DeepSeek Harness 的代码助手。请帮我安装「DeepSeek 余额查询」插件。
插件介绍：给 DeepSeek Harness 使用的余额查询插件，目前只支持 DeepSeek，其他 API 后续支持接入。

插件目录：<插件目录的绝对路径，即本仓库根目录，例如 C:\code\dsh\plugin\ds-balance>
请按以下步骤自动完成安装：

1. 读取插件目录下的 README.md、package.json、cordis.patch.yml，
   确认包名 @local/ds-balance 以及 dsh.bundle.patch / dsh.client 声明无误。
2. 定位 DSH profile：
   $DSH_HOME 下（Windows 默认 C:\Users\<用户名>\.dsh，macOS/Linux 为 ~/.dsh）的
   profiles/<profile名>/package.json（默认 profile 为 web）。
3. 修改 profile 的 package.json（写 $DSH_HOME 下的文件可能超出文件沙箱，如被拒请向用户申请提权）：
   - dependencies 中增加 "@local/ds-balance": "link:<插件目录绝对路径>"（Windows 请用正斜杠，如 link:C:/code/dsh/plugin/ds-balance）；
   - dsh.profile.bundles 数组末尾追加 "@local/ds-balance"。
4. 建立目录链接，让 bundle 解析器（dsh 安装目录 → profile 目录）能找到插件包：
   - Windows：在 profiles/<profile名>/node_modules/@local/ 下创建目录联接（junction）指向插件目录；
   - macOS/Linux：ln -s <插件目录> profiles/<profile名>/node_modules/@local/ds-balance；
   - 或者直接在 profile 目录运行 pnpm install 也可。
5. 验证解析：执行
   node -e "console.log(require.resolve('@local/ds-balance/package.json', { paths: ['<profile绝对路径>'] }))"
   应输出插件包的 package.json 路径。
6. 检查凭证：$DSH_HOME/.credentials.yaml 中是否有 DEEPSEEK_API_KEY；
   若缺失，提示用户配置（插件不硬编码密钥，缺失时余额条会显示「余额 —」）。
7. 完成并告知用户：重启 DSH（dsh web / 重启服务）后生效；
   重启后访问 http://127.0.0.1:3080/ds-balance 应返回 JSON（含 balance_infos）而非 HTML 首页。

提示：段落里的 <插件目录绝对路径>、<用户名>、<profile名> 是占位符，粘贴前替换成实际值； 不替换也能装——助手一般会自行推断或向你确认。

---

1. 能不能在其他电脑上直接用？

插件包本身可以：本目录零第三方依赖（Host 代码 lib/index.js 无任何 import）， 拷到任何机器即可作为 DSH 的 bundle 插件加载。

但"直接生效"还需要每台目标机器完成 4 步接线（约 2 分钟，最快路径见「安装方式 0」）：

1. 把本目录放到目标机器的任意位置（下文以 C:\code\dsh\plugin\ds-balance 为例）
2. 在 DSH profile 组合里登记它（见 §3）
3. 建一个 node_modules 目录链接（见 §4）
4. 配置 DeepSeek API Key（见 §5）
5. 重启 DSH

一句话：插件是"可移植的零件"，接线是"每台机器的装配"，README 就是装配说明。

---

2. 目录结构

ds-balance/
├── package.json          # 包声明：dsh.bundle.patch + dsh.client（客户端 bundle 入口）
├── cordis.patch.yml      # 组合补丁：insert 一行插件（- id: ds-balance, name: '@local/ds-balance'）
└── lib/
    ├── index.js          # Host：HTTP 端点 GET /ds-balance + 模型工具 deepseek_balance（零 import）
    └── client.js         # 浏览器半部：手写经典脚本 bundle（__ModuleLoader__.load），改完刷新页面即生效

配套开发笔记见同目录 PLUGIN-DEV-MEMO.md。

---

3. 接线 A：登记到 profile 组合

找到目标机器使用的 profile（本机是 web）：$DSH_HOME/profiles/<profile名>/package.json （Windows 默认 $DSH_HOME = C:\Users\<用户>\.dsh）。

a) dependencies 增加一行（指向你放置插件的位置）：

"dependencies": {
  // ...原有依赖...
  "@local/ds-balance": "link:C:/code/dsh/plugin/ds-balance"   // ← 改为实际路径
}

b) dsh.profile.bundles 末尾追加包名：

"dsh": {
  "profile": {
    "bundles": [
      // ...原有 bundles...
      "@local/ds-balance"                                      // ← 追加
    ]
  }
}

profile 组合加载顺序：dsh 安装目录 → profile 目录。bundle 必须能被 Node 从 profile 解析到（下一步建链接），否则启动会报 cannot resolve profile bundle。

---

4. 接线 B：建 node_modules 链接

让 resolveBundleDir 能在 profile 目录解析到插件包。二选一：

方式一（推荐，无需 pnpm）：目录联接 / 符号链接

Windows（管理员或普通用户均可，junction 无需提权）：

New-Item -ItemType Directory -Path "$env:USERPROFILE\.dsh\profiles\web\node_modules\@local" -Force
New-Item -ItemType Junction -Path "$env:USERPROFILE\.dsh\profiles\web\node_modules\@local\ds-balance" `
  -Target "C:\code\dsh\plugin\ds-balance"

macOS / Linux：

mkdir -p "$HOME/.dsh/profiles/web/node_modules/@local"
ln -s "/path/to/ds-balance" "$HOME/.dsh/profiles/web/node_modules/@local/ds-balance"

方式二：pnpm install（profile 目录下执行，会按 link: 依赖建立正式链接）

cd "$HOME/.dsh/profiles/web" && pnpm install

验证解析成功：

node -e "console.log(require.resolve('@local/ds-balance/package.json', { paths: ['$HOME/.dsh/profiles/web'] }))"

---

5. 接线 C：配置 API Key（每台机器私有）

插件每次查询时通过凭证 seam 实时读取，不硬编码。目标机器需要：

# $DSH_HOME/.credentials.yaml
DEEPSEEK_API_KEY: sk-xxxx

缺失时插件不报错，余额条显示红色 余额 —，悬停提示「未配置 DEEPSEEK_API_KEY」。

---

6. 接线 D：重启 & 验证

1. 重启 DSH（dsh web / 重启服务）
2. 验证：
   • 浏览器打开 http://127.0.0.1:3080/ds-balance → 应返回 JSON（含 balance_infos）， 而不是 HTML 首页
   • 对话页左下角出现小字余额 + ↻ 按钮（默认 60s 自动刷新）
   • 设置 → 「DeepSeek 余额」可改刷新间隔（5–86400 秒，存 localStorage）
   • 对话中说「查一下余额」→ deepseek_balance 工具输出明细

---

7. 卸载

1. 从 profile package.json 删除 link: 依赖和 bundles 里的 @local/ds-balance
2. 删除 profiles/<profile>/node_modules/@local/ds-balance 链接
3. 删除插件目录
4. 重启 DSH

---

8. 跨平台注意事项（macOS / Linux 兼容）

• HTTP 客户端（已自动处理）：Host 自动检测平台选择 curl 可执行文件名—— Windows 用 curl.exe，macOS/Linux 用 curl（系统自带，无需安装）。 lib/index.js 顶部 CURL_NAME 常量即平台判断，无需手动改动。
• 目录链接：Windows 用 junction，POSIX 用 ln -s（见 §4）。
• 凭证：$DSH_HOME 随平台不同（macOS 为 ~/.dsh），但 .credentials.yaml 的键名 DEEPSEEK_API_KEY 一致。
• 其余部分：客户端 bundle 是纯浏览器代码、Host 零 import、webServer 路由用 Node 标准 http 对象——三平台行为一致。

---

9. 行为开关（改 lib/client.js 后刷新页面即生效，无需重新构建）

想改	位置
取消隐藏左下角 "Cordis Plugin" 徽标	删除 sidebar.footer.action 那段 cordis-panel 注册（含注释）
改默认刷新间隔	DEFAULT_CONFIG.intervalMs（60000）
改默认告警阈值	DEFAULT_CONFIG.lowBalanceThreshold（10，0 = 关闭告警）
改默认币种/显示格式	BalancePill 的 label 逻辑
关闭默认自动刷新	DEFAULT_CONFIG.autoRefresh: false

刷新间隔、自动刷新开关、低余额告警阈值是同一份配置（ds-balance:config，存 localStorage）， 都在 设置 → DeepSeek 余额 页里改。余额低于阈值时数字变红并显示 ⚠，悬停提示 「余额不足，请及时充值」。

⚠️ 若保留徽标隐藏，cordis-panel 注册必须带 priority: -1（遮蔽者用更低 priority， 不能用同 id 同 priority 去撞内置 dsh-client-ui-cordis，否则会把整个 Cordis 面板加载搞挂）。 详见 PLUGIN-DEV-MEMO.md 坑 1。

---

10. 工作原理速览

浏览器端 lib/client.js                    DSH Host lib/index.js
┌────────────────────────────┐  同源      ┌──────────────────────────────┐
│ 左下角小字余额条 + ↻ 按钮    │  fetch    │ webServer 路由 GET /ds-balance │
│ 设置页（间隔, localStorage） │ ─────────► │   → credentials 读 API Key     │
│ deepseek_balance 工具调用    │           │   → subprocess spawn curl     │
└────────────────────────────┘           │   → https://api.deepseek.com/  │
                                         │       user/balance             │
                                         └──────────────────────────────┘

• 数据通道：webServer HTTP 路由（绕开 typert Remote 生成器）
• 工具注册：ctx.tools.register 手写定义（零 import）
• 凭证：ctx.credentials.resolve('DEEPSEEK_API_KEY') 每次实时解析

---

11. 安全说明

项	说明
密钥去向	只在本机、只发给 DeepSeek 官方接口（Authorization: Bearer 头）
命令行不暴露	密钥写入一次性临时 header 文件（node:fs，0600 权限），curl 用 -H @file 读取，请求结束立即删除（finally 兜底，成功失败都清）
不进浏览器	客户端只 fetch('/ds-balance')，返回体只有余额数据，无密钥
不进仓库/日志	密钥零硬编码；响应/工具输出/日志均不含密钥
遗留说明	.credentials.yaml 本身明文存密钥（DSH 凭证机制设计）；临时 header 文件仅在查询瞬间存在于系统临时目录

---

12. 升级注意事项

DSH 升级（npm 更新 / 覆盖安装）不会让插件失效：

• 插件文件在 C:\code\dsh\plugin\，升级不触碰；
• profile 的 package.json 升级自愈逻辑（normalizeShippedProfile）只重写还等于出厂默认 bundles 列表的 profile； 你的列表已含 @local/ds-balance（用户自定义），升级会原样保留；
• node_modules/@local/ds-balance 目录联接在 profile 目录下，不在安装目录，升级不动。

升级后如遇到问题，按优先级检查：

1. 启动报 cannot resolve profile bundle "@local/ds-balance" → profile 的 node_modules 被重建/清理过， 按 README §4 重新建链接（或 pnpm install）即可；
2. 插件加载了但报错 → 可能是 DSH 新版的破坏性变更（槽位名 / tools.register 规范 / bundle 协议）， 按报错适配插件代码（通常是小改动）；
3. 一切正常但余额不显示 → 走 §6 验证清单（/ds-balance 应返回 JSON 而非 HTML）。