# @francescoli/dsh-quota 中文文档

规范地址：https://npmcn.com/package/%40francescoli/dsh-quota/

版本：0\.4\.4
npm 元数据更新时间：2026-11-09T09:57:09.204Z
中文译文更新时间：2026-11-15T13:44:02.736Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40francescoli/dsh-quota
原文对照：https://npmcn.com/package/%40francescoli/dsh-quota/?lang=original
项目主页：https://github.com/Francesco502/dsh-quota#readme
源码仓库：https://github.com/Francesco502/dsh-quota

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.9 MB，46 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22\.6\.0
- 运行依赖：0 个
- 首次发布：2026-08-26T09:03:42.292Z
- 最新版本发布：2026-11-09T09:57:08.893Z
- 近 30 天下载量：3407（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

AI DeepSeek Harness的配额和托肯使用监视器(DeepSeek,硅花, OpenRouter, Cursor, Codex, Antigravity, Copilot, Kimi, GLM, Quen, OpenCode)

## 安装

```sh
npm install @francescoli/dsh-quota
```

也可以使用：`pnpm add @francescoli/dsh-quota`、`yarn add @francescoli/dsh-quota`、`bun add @francescoli/dsh-quota`

## README

# @francescoli/dsh-quota: DSH AI 额度与用量监控插件

[![version](https://img.shields.io/badge/version-v0.4.4-blue.svg)](https://npmcn.com/package/%40francescoli/dsh-quota/package.json) [![npm](https://img.shields.io/badge/npm-@francescoli/dsh--quota-CB3837.svg)](https://www.npmjs.com/package/@francescoli/dsh-quota) [![license](https://img.shields.io/badge/license-Apache--2.0-green.svg)](https://npmcn.com/package/%40francescoli/dsh-quota/LICENSE)

> 当前版本：**v0.4.4**

专门为 **DeepSeek Harness (DSH)** 打造的全功能 AI 服务额度、余额与用量监控插件。集中监控并展示 **DeepSeek 官方平台**、**Cursor**、**Codex (ChatGPT)**、**Google Antigravity**、**GitHub Copilot**、**OpenAI Platform**、**Anthropic Claude**、**Kimi**、**智谱 GLM**、**MiniMax**、**阿里通义千问**、**火山方舟**、**OpenCode-Go** 及 **OneAPI / NewAPI** 兼容中转的实时剩余额度、用量、充值余额、消耗速率及重置周期。

* * *

## ✨ 核心特性

1.  **16+ 家服务全聚合**：
    -   **国内大模型**：DeepSeek（充值/赠金实时查询）、硅基流动 SiliconFlow（实时余额与充值金）、Kimi（代金券/余额）、智谱 GLM、MiniMax（海螺）、通义千问（百炼）、火山方舟（豆包）；
    -   **IDE 编程助手**：Cursor（免密读取 SQLite `state.vscdb`）、Google Antigravity（CloudCode 配额）、GitHub Copilot（本地凭据探测）；
    -   **海外官方与聚合**：OpenRouter（全局配额/用量）、Codex (ChatGPT Wham)、OpenAI Platform Billing、Anthropic Claude、OpenCode-Go、OneAPI / NewAPI 中转。
2.  **直观数据看板与 HUD 悬浮环**：
    -   **概览看板**：顶部 4 宫格总览、分类筛选 Tab、多模型分组折叠 (Accordion) 与宋代青绿雅致配色；
    -   **HUD 悬浮环**：与监控面板同一套语义配色（品牌色圆环 + 中性轨道），状态色只用于小圆点与文字强调；字号随球径（46px / 贴边 38px 微缩）自适应，长金额自动缩写，悬停可展开明细与暂停轮播；
    -   **设置与测活**：为所有 Provider 提供一键「测试连接」与毫秒级延迟反馈。
3.  **时序统计与智能预警**：
    -   本地 30 天时序历史采样记录（append-only JSONL，写入不阻塞请求）；
    -   自动计算近 24 小时平均消耗速率 (%/h) 与预估可用剩余时长；
    -   多级阈值告警与侧边栏「额度监控」动态小红点 Badge 联动。
4.  **DSH Agent 深度协同**：
    -   注册 `get_quota_status` Agent Tool，支持在对话中直接让 AI 查额度与获取模型可用状态。
5.  **安全与性能加固**：
    -   插件 API 统一守卫（`X-DSH-Quota` 头 + 回环 Host + 同源 Origin + 写入仅 JSON），阻断跨站改写配置；
    -   用户自填的 `baseUrl` 经安全校验（拒绝非 http(s)、云元数据与链路本地地址，允许本机/内网中转）；
    -   独立 Provider TTL 缓存池 + 整轮/实例双层 single-flight，单服务网络超时不阻塞全局；
    -   配置文件保存在本地 `~/.dsh/quota-config.json`，密钥拆分到 `quota-secrets.json`（均 `0600`）；
    -   历史数据写入 append-only `~/.dsh/quota-history.jsonl`，30 天/单 key 2000 点自动裁剪与每日 compaction。
6.  **原生 UI 与国际化**：
    -   通过宿主官方 slots 注册一级导航「额度监控」（`sidebar.panellist` + `main` 面板），与搜索/插件/自动化任务同级；`ctx.layout.selectPanel` 负责选中，dsh-claude-style 的「编辑侧栏…」可直接勾选显隐；旧宿主自动回退 DOM 入口与覆盖层；
    -   响应式布局（1024/720/480 断点）、深浅色主题令牌、32px 圆心百分比、7 天用量柱、数据来源徽标与窄屏卡片化设置表；
    -   壳层文案支持中英切换（`dsh-quota` locale 命名空间）。

* * *

## 🆕 v0.4.4 更新要点

-   **一级导航「额度监控」**：新增根作用域 `sidebar.panellist` 入口与同名 `main` 主面板，和搜索/插件/自动化任务同级；`ctx.layout.selectPanel('quota')` 负责选中，底部快捷入口与 HUD 的「打开面板」也走同一条路径。旧宿主没有 slots/layout 时仍回退到覆盖层与 DOM 入口。
-   **侧栏显隐联动**：dsh-claude-style 的「更多 → 编辑侧栏…」会自动枚举该入口，可勾选显示/隐藏，并沿用其 `sidebarHidden` 设置。
-   **面板版本号修正**：标题版本标签不再硬编码，改为读取 `PLUGIN_VERSION`，本次界面显示 `v0.4.4`。
-   **HUD 配色回归面板语义色**：圆环改为品牌色（`--q-brand`）+ 中性轨道（`--q-track`），不再整环绿/黄/红；状态色只保留在 5px 告警点与卡片内文字，深浅色分别校准。
-   **HUD 文字自适应**：字号按球径 `clamp()` 缩放（46px / 贴边 38px 微缩），长金额缩写成 `K/M/B` 或省略号；`0%`、`100%`、`123%`、`9.99GB`、中英混排与深色主题下均不溢出。
-   **面板滚动与高度**：新增 `data-dsh-quota-mode="panel|overlay"` 区分渲染模式，主面板使用 `height:100%; overflow-y:auto`，不再依赖 `panelOpen` 状态。

* * *

## 📦 安装方法

### 方式一：通过 DSH 插件市场 (dsh-market) 一键安装（推荐）

1.  打开 DSH Web 界面 (`http://127.0.0.1:3080`)；
2.  进入 **设置 (Settings)** → **插件市场 (Plugin Market)**；
3.  搜索 `dsh-quota` 并点击 **安装 (Install)**；
4.  刷新网页即可在侧边栏看到「额度监控」入口。

### 方式二：通过 DSH CLI (npm Scoped 模式) 安装

```bash
dsh plugin --profile web add @francescoli/dsh-quota
```

### 方式三：通过 GitHub 源码链接安装

```bash
dsh plugin --profile web add github:Francesco502/dsh-quota
```

### 桌面版（Desktop）安装

桌面版使用**独立的 Desktop profile**，且 npm 版 CLI 会拒绝管理它（`profile "desktop" is managed exclusively by the Electron application`）。正确步骤：

1.  安装并**启动一次** DeepSeek Harness Desktop，让它初始化 `$DSH_HOME/profiles/desktop`，然后**完全退出**应用；
2.  用 **Desktop 自带的命令运行时**（不是 Homebrew / npm 安装的 `dsh`）执行：
    
    ```bash
    dsh plugin --profile desktop add @francescoli/dsh-quota@0.4.4
    ```
    
3.  重新打开 Desktop。

> 桌面版与 Web 版共享 `$DSH_HOME` 下的数据文件（配置、历史），但不共享插件安装目录；两端升级需要各自执行一次。

* * *

## 🛠️ 构建与发布验证

```bash
npm ci
npm run typecheck    # tsc --noEmit（host 类型走 types/dsh-shims.d.ts）
npm run build        # esbuild 产出 lib/index.js + lib/client.js（含 source map）
npm test             # 类型检查 + legacy 套件 + node:test 全量用例
npm run validate:release -- --tag v0.4.4
```

* * *

## 📚 详细文档

-   [系统架构与实现原理](https://npmcn.com/package/%40francescoli/dsh-quota/docs/ARCHITECTURE.md)
-   [新 Provider 扩展接入指南](https://npmcn.com/package/%40francescoli/dsh-quota/docs/PROVIDERS.md)
-   [常见问题与解答 (FAQ)](https://npmcn.com/package/%40francescoli/dsh-quota/docs/FAQ.md)
-   [版本管理与发布标准规范](https://npmcn.com/package/%40francescoli/dsh-quota/VERSIONING.md)
-   [版本更新日志](https://npmcn.com/package/%40francescoli/dsh-quota/CHANGELOG.md)

* * *

## 📄 开源协议

[Apache-2.0](https://npmcn.com/package/%40francescoli/dsh-quota/LICENSE)

## 常见问题

### @francescoli/dsh-quota 是什么？

AI DeepSeek Harness的配额和托肯使用监视器\(DeepSeek,硅花, OpenRouter, Cursor, Codex, Antigravity, Copilot, Kimi, GLM, Quen, OpenCode\)

### 如何安装 @francescoli/dsh-quota？

在项目目录运行 npm install @francescoli/dsh-quota，或使用 pnpm add / yarn add / bun add。

### @francescoli/dsh-quota 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/francescoli\_\_dsh-quota 是否存在。

### @francescoli/dsh-quota 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @francescoli/dsh-quota 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.6\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @francescoli/dsh-quota 可以商用吗？

@francescoli/dsh-quota 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @francescoli/dsh-quota 的下载量有多少？

根据 npm 官方下载统计，@francescoli/dsh-quota 在 2026/10/16 – 2026/11/14 这 30 天内被下载 3,407 次，日均约 114 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @francescoli/dsh-quota 还在维护吗？

最新版本 0\.4\.4 发布于 2026/11/09（6 天前）；至今共发布 9 个版本，其中过去 12 个月发布了 9 个；首次发布于 2026/08/26。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。