账户余额徽章ABccgh/dsh-account-balance

dsh-account-balance

一个 DeepSeek Harness 插件，在 Web GUI 中显示你的 DeepSeek 账户余额，
并通过一个经过身份验证的宿主路由提供该数据，因此浏览器永远不会持有 API 密钥。

它在侧边栏底部、Settings 条目旁边渲染一个小徽章：

⟳ ¥12.65            宽侧边栏
⟳                   折叠为 56px 窄栏

点击它可立即刷新；悬停可查看货币、总额、赠送金额和充值金额。
它每 60 秒自行轮询一次。读取失败绝不会让徽章变空——
最后已知的金额会保留，并标记为过期，只有在连续两次失败之后，
它才会停止将该金额呈现为当前值。

各部分如何协同工作

分为两半，而且这种划分并非随意为之。

宿主部分 —— lib/index.js

在连接外壳的路由注册表中注册一个精确的 Fetch 路由，GET /api/balance。
它通过 harness 的 credentials 接缝按请求解析 API 密钥
（来自一个引用名称，而绝不是存储的值），并调用提供商文档中记载的
余额端点。

它不发布任何 Cordis 服务。浏览器之外没有任何东西会读取余额，因此
不存在会与宿主自有名称冲突的名称，也没有需要放置的领域。

该路由处理器有意不自行做任何身份验证。 此注册表中的路由是在
/api 载体应用了 Host/Origin 防护和浏览器 cookie 之后才被分派的，
而这正是注册 API 的契约。在此处重复该检查只会重复防护，而不会加强它。
在构建此插件所针对的部署上实测：一个未经身份验证的 GET /api/balance 在到达此处理器
之前就会得到 401 响应，而带上 cookie 的同一请求会得到 200。

浏览器部分 —— lib/client.js

一个手写的客户端插件包，采用 harness 模块加载器格式。它向侧边栏声明的
sidebar.footer.action 插槽注册一个 Pill，这与内置 Cordis 面板占据的是同一个
可叠加席位。

不需要打包器：harness 通过 /plugins//client.js 以纯字节形式提供客户端包，
唯一的要求是格式、一个等于包名的 id，以及 require() 调用仅限于
平台的种子模块加上其他图行。

从代码中看不出来的三个约束

其中每一个都是针对真实部署实测得出的，而且每一个都属于那种
看起来像风格选择、直到它悄无声息地坏掉的东西。

1. 宿主部分有意不导入任何东西

lib/index.js 中没有出现任何静态 import。这是因为 pnpm 将此包以
node_modules/dsh-account-balance ->  的形式链接到某个 profile 中，而
--preserve-symlinks 处于关闭状态——因此裸说明符会从链接的真实路径解析，
而该路径位于所有 node_modules 之外。结果就是：

ERR_MODULE_NOT_FOUND: Cannot find package '@deepseek-ai/schemastery'

两个后果，均已在原地处理：
- 凭据引用由本包自带的 seam 名称语法副本进行校验，而不是导入 credentialRef。不要通过添加该导入来“修复”此问题——该导入无法解析。
- Config 是手写的
Standard Schema 对象，而不是
schemastery schema。Cordis 从插件的 Config 中只需要一样东西——
runtime.Config["~standard"].validate(config)——因此这既满足了加载器，又让该行保持自包含，并且仍能在加载时以 $. 消息报告错误字段。

2. inject: ['connection'] 是关键所在

connection 是一个硬依赖，与随附的 /api 路由所有者一致。替代方案——使用
ctx.get('connection') 并做缺失检查——已经尝试过，但它是错误的：在根树插件的 apply 运行的那一刻，该服务尚未提供，因此该守卫总是走缺失路径。于是该行会挂载，到达客户端启动图，并悄悄地完全不提供任何路由——一个 404，且没有任何日志记录。

3. 浏览器端通过 HTTP 与宿主通信，而不是通过 ctx.remote

ctx.remote 会是惯用的通道，但在这里无法使用：客户端的远程能力集在构建时由 harness 内部的某个程序集固定，因此插件无法在运行时添加命名空间。在已经过认证的 /api 载体上使用精确的 Fetch 路由是添加端点的受支持方式，本包正是采用这种方式。客户端调用 fetch('/api/balance')，并带上 credentials: 'same-origin'。

安装

本包未发布到 npm。它从路径安装。

1. Put the package somewhere the profile can link to, then register it:
dsh plugin --profile web add /absolute/path/to/dsh-account-balance

2. Mount it with a row in the profile's own patch layer
($DSH_HOME/profiles//cordis.patch.yml):

- insert:
- id: account-balance
name: 'dsh-account-balance'
config:
apiKeyEnv: DEEPSEEK_API_KEY
baseURL: https://api.deepseek.com
refreshSeconds: 60
cacheSeconds: 30
timeoutMs: 8000

能节省时间的注意事项：

- insert: 是必需的。 没有它的行是按 id 对现有行的覆盖；对于不存在的 id，它会记录一条警告并被跳过，因此该插件永远不会出现。
- name 必须是包名，而不是目录。 加载器使用 Node 的 ESM 解析器导入该行，而目录导入会失败并报 ERR_UNSUPPORTED_DIR_IMPORT。
- 添加该行后重启 harness。 宿主端需要重启进程；之后对客户端 bundle 的编辑可以热重载，无需重启。
- API 密钥从 harness 凭据存储或环境中解析。它绝不会被写入组合文件，也绝不会到达浏览器。

配置

| 字段 | 默认值 | 含义 |
|---|---|---|
| apiKeyEnv | DEEPSEEK_API_KEY | 凭据引用名称，在每次请求时通过凭据接缝解析 |
| baseURL | https://api.deepseek.com | 提供商基础地址；路由会追加 /user/balance |
| refreshSeconds | 60 | 徽章使用的轮询周期，由路由报告给浏览器 |
| cacheSeconds | 30 | 一次上游读取在请求和标签页之间被复用的时长 |
| timeoutMs | 8000 | 上游调用的每次请求预算 |

响应结构

{
"ok": true,
"source": "https://api.deepseek.com/user/balance",
"fetchedAt": 1789128938178,
"ttlMs": 30000,
"refreshSeconds": 60,
"isAvailable": true,
"balances": [
{ "currency": "CNY", "total": "10.17", "granted": "0.00", "toppedUp": "10.17" }
]
}

失败时返回相同的信封结构，并带有 ok: false、稳定的 code 以及面向纠正的
message；缺少凭据时返回 401，超时返回 504，其他情况返回 502。响应为
cache-control: no-store。

兼容性

基于 DeepSeek Harness 0.1.5-rc.1 构建并验证。它所依赖的接口包括
连接 Fetch 路由注册表、Cordis Config 契约、模块加载器客户端
打包格式，以及侧边栏的 sidebar.footer.action 插槽。这些属于产品
界面，可能随版本变化；升级后应重新验证挂载，而不是假设
它仍然成立。

许可证

MIT — 见 LICENSE。