前言¶

智能体开发中，免费 API 配额是绕不过的约束。Google Gemini 免费层按模型限制 20 次/天、UTC 午夜重置，官方只返回 429 错误而不给剩余额度，容易在不知不觉中撞墙。很多用户会在 DSH Web 界面里频繁切换模型，却很难直观感知当前最紧的那一个还剩多少次数。现有做法要么依赖手动查 API，要么完全靠猜。

dsh-gemini-kitten-widget 给 DSH Web 界面右下角挂了一只 Q 版 Gemini 猫娘，实时显示免费层今日已用 / 剩余次数，并按额度变色预警。她只在需要时说话，不会刷屏。

插件定位¶

• 名称：dsh-gemini-kitten-widget
• 维护者：Void-LifeStream
• 分类：客户端
• 标签：DeepSeek、DSH、Gemini、配额监控、Widget
• 许可证：MIT
• 版本：0.1.3
• 目录页：https://www.skillhub.cn/plugins/Void-LifeStream/dsh-gemini-kitten-widget
• 仓库：https://github.com/Void-LifeStream/dsh-gemini-kitten-widget

核心功能¶

配额口径¶

• 限额：20 次 / 模型 / 天
• 重置：UTC 午夜（北京时间次日 08:00）
• 统计范围：只统计 DSH 内发起的调用
• 配额按模型分别计算；挂件主显示“最紧的那个模型”（用掉最多的），悬停可看各模型明细

可视化与预警¶

• 显示已用 / 剩余次数、重置倒计时
• 用掉 80% 变橙色、95% 变红色
• 配额用尽或临近用尽时，她会主动说话（每个配额日每条只喊一次）

交互¶

• 拖动挂件，松手后自动吸附到最近的屏幕边缘（吸附区为视口 12%，贴边 4px）
• 单击猫娘：换一句台词（台词随额度状态变化）
• 单击徽章：切换查看哪个型号
• 拖到屏幕左半边：立绘镜像翻转（脸朝右）
• 右键：回到默认位置（鲸鱼挂件上方）
• 悬停：显示全部型号的明细 / 重置时间 / 数据来源

安装与启用¶

方式一：从仓库安装（推荐）¶

在 DSH 会话里对 agent 说：

plugin_manager install_bundle  target = git+https://github.com/Void-LifeStream/dsh-gemini-kitten-widget

方式二：先 clone 再用本地 link¶

git clone https://github.com/Void-LifeStream/dsh-gemini-kitten-widget

然后在 DSH 会话里对 agent 说：

plugin_manager install_bundle  target = link:<clone 下来的绝对路径>

重启¶

安装后必须重启 DSH（桌面端与 web 形态均建议重启一次）。桌面端注入表在宿主启动时一次性收集，运行期加载无法进入表；web 形态走 tapIndex，同样建议重启一次。

配额数据来源¶

数据来自两道口子，按权威度排序：

1. DSH 会话日志（权威）

路径：~/.dsh/sessions/**/session.v4.jsonl.zstd

每条 assistant/message 对应一次模型响应 = 一次 API 调用。日志是多帧拼接的 zstd，插件逐帧解压、按 mtime/size 增量缓存，稳态约 0ms。

2. 鲸鱼娘账本（兜底）

路径：~/.dsh/.dshw-usage.json 的 events

该账本是按 turn 聚合的，一个 turn 里 agent 可能问模型几十次，它只写一条。所以账本条数 ≠ 调用次数，只在日志读不到时作为兜底数据源。

自定义台词¶

内置台词写死在 assets/kitten.js 的 LINES；私货另存于 ~/.dsh/widget-lines.json 的 kitten 段。host 半随 /dsh-kitten/state 一起下发，客户端追加（不覆盖内置），改完刷新页面即生效，无需重启。

示例配置：

{
  "kitten": {
    "ok":     ["今天也要好好写代码喵。"],
    "warn":   ["换个型号使唤本喵吧，兄弟们还有力气喵。"],
    "danger": ["换一位吧，本喵这个型号今天真没劲了喵。"]
  }
}

占位符：{used} 已用次数 · {remaining} 剩余 · {limit} 每日上限 · {model} 当前型号短名。

注意事项¶

• 本插件只统计 DSH 内发起的调用，其他渠道（如 Gemini CLI / AI Studio / 其他脚本）消耗的配额看不到，挂件数字天然 ≤ 真实剩余。
• 配额是按模型分别算的，gemini-3.8-flash 用完不影响 gemini-3.7-flash。
• 本插件不依赖任何 API key，只读本机数据（会话日志 + 可选的余额账本），不联网、不写配置、不碰凭据。
• 位置同时存服务端（~/.dsh/gemini-kitten-widget/pos.json）和浏览器 localStorage，重启 DSH 不会丢失位置。

适用场景¶

• 需要频繁切换 Gemini 免费层模型，希望直观监控配额的 DSH 用户
• 希望在 Web 界面获得非侵入式、低刷屏率配额提醒的开发者
• 需要跨配额日自动重置、按模型分别统计的环境

技术形态¶

dsh-gemini-kitten-widget/
├─ package.json          dsh.bundle.patch → cordis.patch.yml
├─ cordis.patch.yml      挂载声明（insert 一条）
├─ lib/index.js          host 半：注入行 + 三只读路由 + 位置读写 + 配额统计
├─ assets/kitten.js      client 半：渲染 + 拖拽吸附/翻转 + 位置同步 + 台词 + SVG 兜底
├─ assets/kitten-art.png 形象立绘（本地生成，透明 PNG）
└─ tools/                自测与出图脚本

两条注入通道：

1. webserver/index-inject 推内联 <script> 行 —— 桌面端唯一通道
2. webServer.tapIndex 往 index.html 注入 <script defer> —— web 形态通道

路由：

• GET /dsh-kitten/widget.js：客户端脚本（URL 带 mtime 指纹）
• GET /dsh-kitten/art.png：形象立绘（ETag 走 mtime）
• GET /dsh-kitten/state：配额 JSON
• GET/POST/DELETE /dsh-kitten/pos：挂件位置（跨重启持久化）

安全姿态：前三条只读、不含凭据；/pos 是唯一写接口，加了 body 上限 1 KiB、只接受锚点格式、原子替换等限制。

开发与自测¶

• 改 assets/kitten.js 或 kitten-art.png → 刷新页面即生效
• 改 lib/index.js → 需要重启 DSH
• 改配额口径：DSHK_QUOTA_PER_MODEL=20、DSHK_QUOTA_TZ=UTC
• 发布前运行 node tools/sync-check.cjs（默认）检查本地与远端文件列表差异；加 --deep 查看内容差异

自测脚本（使用 DSH 运行时 node）：

$node = "$env:USERPROFILE\.dsh\dsh-runtimes\dsh-primary-runtime\dependencies\node\bin\node.exe"
& $node tools\selftest.mjs   # host 半离线自测：注入行 / 路由 / 配额算法
& $node tools\logtest.mjs    # 日志计数器：增量解帧 / 半截帧 / 截断重写（13 项）
& $node tools\uitest.mjs     # 浏览器回归：立绘 / 回退 / 拖拽吸附 / 台词 / 三档变色（19 项）
& $node tools\shot.mjs <输出目录>   # 出预览图

结语¶

dsh-gemini-kitten-widget 把免费层配额监控嵌入 DSH Web 界面，用猫娘的方式把“还剩几次”“哪型号最紧”“什么时候重置”这些信息拉到眼前。她只在需要时说话，不会刷屏，也不会偷窥你的凭据。如果你在 DSH 里频繁调用 Gemini 免费层，这只挂件可以帮你少撞几次 429。

• 插件目录：https://www.skillhub.cn/plugins/Void-LifeStream/dsh-gemini-kitten-widget
• GitHub：https://github.com/Void-LifeStream/dsh-gemini-kitten-widget