前言¶
用 DSH（DeepSeek Harness）跑对话时，费用往往分散在站点账单、本机会话和脑子里三条线里：站点后台要另开页面查余额，本机每轮 token 消耗又要自己估。若你主要走 API3D（api3d.cn） 的 OpenAI 兼容接口，希望在 Web 界面里一眼看到账户余额、今日已用和每轮扣费，而不反复切站或手填一堆 endpoint，社区插件 dsh-api3d-pet（维护者 ptb-xiaou）把这件事做成标准 DSH bundle：右下角鲸鱼气泡常驻，站点地址与 billing 字段内置，装好只需填一次 API Key。
这是什么¶
dsh-api3d-pet 是面向 DSH Web 的客户端类桌宠挂件：鲸鱼 + 气泡展示 API3D 站点余额、今日已用、每轮对话消耗，并支持点击序列、模块化排版、音效与吸附等交互。它是 API3D 站点专属版——主气泡余额来自站点 billing/subscription 的 balance 与当日 billing/usage 的 total_usage_usd（金额按人民币口径，不折算）；上游通用的 DeepSeek 官方余额链路、多厂商模板、Codex 本机会话统计等已移除。当前 npm 版本为 0.6.10（MIT 许可证）。
分类上属于 DSH 社区目录中的「客户端」插件；目录页：https://www.skillhub.cn/plugins/ptb-xiaou/dsh-api3d-pet，源码：https://github.com/ptb-xiaou/dsh-api3d-pet。
核心功能¶
记账与主气泡¶
- 常驻自启：随 DSH Web 打开自动出现；余额约 60 秒自动刷新，点击鲸鱼可手动刷新；未配置 key 时主气泡显示
NO_KEY，不请求官方接口。 - 今日已用：默认按站点 usage 接口
scope=user取账号当天合计（标签「今日已用（账号）」）；站点回显scope=key或缺少字段时退回当前 key 当天扣费（「今日已用（本 key）」）。 - 计费倍率（0.6.8 起）：主气泡与记账面板可显示站点返回的
effective_rate_multiplier（实测倍率）；站点未回传时显示—，不臆测为 1。 - 本机模型费用：仅统计本机 DSH 会话内对话，按真实 usage × 内置价目表估算，与站点「今日已用」口径独立。
- 每轮消耗：监听本机会话事件，按模型真实 usage 换算金额，每轮结束可弹出消耗泡泡；开关与内容在「音效与提示 → 全局设置 → 每轮消耗提示」中配置，金额占位符为
{cost}。 - API3D 记账面板：支持余额预警、今日预算、「已观测消费」与余额校正、近 7 天 / 全部用量记录、模型名完整换行显示等（详见仓库 README）。
泡泡与交互¶
泡泡内容可完全自定义：点击序列、模块库、随机语句 / 随机图片、总余额 / 赠金 / 充值余额等内置模块，逐模块字体与配色；拖拽排版（每行最多 6 模块、泡泡最多 6 行）。挂件支持四边吸附、贴左水平镜像、按压 Q 弹、隐藏菜单按钮后右键（桌面）或长按（约 1.5 秒，移动端）唤出菜单。
站点配置（仅需 API Key）¶
界面只保留 API3D 一项：站点 https://api3d.cn、凭据键名 API3D_API_KEY、币种 CNY、接口路径等均已内置。用户在「API3D 记账 → API3D 站点设置」粘贴 API Key 即可；密钥写入 DSH 官方凭据服务，配置文件不含明文。可用「测试连通性」验证 key。余额接口示例：GET https://api3d.cn/dashboard/billing/subscription 读取 balance。
一键升级¶
npm 安装到 web profile 时，可在 DSH「插件 → 已安装 → dsh-api3d-pet」详情页或「关于 / 自检」面板执行升级到新版（link: 源码安装不显示按钮）。升级前会备份 package.json / pnpm-lock.yaml，失败可回滚；记录写在 $DSH_HOME/.dshw-update.log。
安装与启用¶
在已具备 DSH 与 npm 发布版安装能力的环境下，推荐命令如下（来自仓库 README）：
# 推荐：npm 已发布版
dsh plugin --profile web add dsh-api3d-pet
# 或从本目录装（源码方式：改代码即时生效，但目录不能移动/改名）
dsh plugin --profile web add link:<本目录绝对路径>
安装完成后重启 dsh web，浏览器使用 Ctrl+F5 强刷。第一次点开桌宠菜单时会有引导遮罩：粘贴 API Key 并保存即可，无需再配站点地址或其它字段。
说明：dsh plugin 按设计操作 web profile；官方 Electron 桌面客户端使用 desktop profile，需在桌面端会话中按 README「桌面端安装」说明由 DSH 自行安装，勿指望用同一命令改 desktop profile。
典型用法¶
- 按上文命令安装并重启 Web 界面。
- 打开右下角鲸鱼菜单，在引导或「API3D 站点设置」中填入 API3D API Key 并保存。
- 主气泡查看余额与今日已用；需要核对倍率时看主气泡或记账面板中的「计费倍率」行。
- 若希望每轮结束弹出本机估算消耗，在「音效与提示 → 全局设置」展开「每轮消耗提示」，打开冒泡并可选「编辑提示内容」使用
{cost}等模块。 - 自定义点击鲸鱼后的文案：通过菜单进入泡泡自定义，配置首次点击、再次点击队列或并列加权出泡。
适用场景与注意¶
适合：主要使用 API3D 中转、长期在 DSH Web 里开发或对话，希望在同一界面盯余额、日用量和单轮成本的用户。
注意：
- 插件以当前 DSH 进程权限运行，安装前请阅读 GitHub 仓库 源码与 MIT 许可证，自行评估是否纳入你的工作流。
- 社区目录 SkillHub 为独立生态站点，与 DeepSeek / 幻方无官方从属关系；插件星标与版本以仓库与 npm 为准。
- 记账面板「已观测消费」来自余额观测估算，与站点 usage 的「今日已用」口径不同，校正需在对应来源的「余额校正」中处理。
结尾¶
dsh-api3d-pet 把 API3D 的 billing 读数嵌进 DSH Web 桌宠：配置一次 key，右下角持续看到余额与日用量，本机每轮消耗与可编辑泡泡则覆盖提醒与展示细节。进一步了解特性与桌面端说明，见目录页 https://www.skillhub.cn/plugins/ptb-xiaou/dsh-api3d-pet 与 https://github.com/ptb-xiaou/dsh-api3d-pet。
