dsh-cliproxyapi-pro 1.6.0 → 1.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/CHANGELOG.md +88 -58
  2. package/README.en.md +52 -68
  3. package/README.md +53 -67
  4. package/lib/client.js +2732 -618
  5. package/lib/index.js +146 -173
  6. package/lib/quota.js +1646 -0
  7. package/lib/updater.js +84 -20
  8. package/locale/en.json +2 -2
  9. package/locale/zh.json +2 -2
  10. package/package.json +9 -4
package/README.md CHANGED
@@ -13,7 +13,7 @@
13
13
  - **多账号**：每个账号独立的地址、密钥、模型勾选和参数，互不影响，可随时停用。
14
14
  - **开箱即用**：首次连接时按该服务自己的模型目录，为每个模型家族勾选最新的一个（最多 12 个），模型选择器不会被上百个模型淹没。
15
15
  - **原生协议**：Claude 走 Anthropic Messages，GPT / Codex / Grok 走 OpenAI Responses，其余走 OpenAI Chat，减少 CPA 的协议转换。
16
- - **可视化管理**：设置面板里勾选模型、编辑单个模型的参数；也可以让 DSH 的 Agent 通过 `cliproxyapi` 工具帮你配置。
16
+ - **可视化管理**：设置面板里勾选模型、编辑单个模型的参数。插件不注册 Agent 工具，不占用模型上下文。
17
17
  - **插件更新**：自动检查稳定 / Beta / 开发通道，可选择全球 / 中国大陆下载源；装有 [DSH 插件市场（dshmarket）](https://github.com/dsh-market/dsh-market) 时可一键或自动安装新版本，否则下载校验离线包，在关闭 DSH 后手动升级。
18
18
  - **安全**：API Key 只保存在 DSH 凭证服务里，不写入任何配置文件。
19
19
  - **零依赖**：不依赖任何 npm 包，无需构建，安装几秒完成。
@@ -27,7 +27,7 @@
27
27
  - [截图](#截图)
28
28
  - [功能详解](#功能详解)
29
29
  - [插件自身更新](#插件自身更新)
30
- - [Agent 工具与斜杠命令](#agent-工具与斜杠命令)
30
+ - [斜杠命令与 HTTP 接口](#斜杠命令与-http-接口)
31
31
  - [存储与配置](#存储与配置)
32
32
  - [升级与卸载](#升级与卸载)
33
33
  - [常见问题](#常见问题)
@@ -49,7 +49,7 @@
49
49
  dsh-cliproxyapi-pro
50
50
  ```
51
51
 
52
- 需要固定版本时可以写成 `dsh-cliproxyapi-pro@1.6.0`。
52
+ 需要固定版本时可以写成 `dsh-cliproxyapi-pro@1.7.0`。
53
53
  4. 点击 **安装**，完成后点击 **立即启用**。
54
54
 
55
55
  > 在中国大陆下载慢，可以点输入框旁的 **安装源**，切换到 **中国大陆镜像源**。
@@ -78,7 +78,7 @@ dsh plugin --profile <profile 名称> add dsh-cliproxyapi-pro
78
78
 
79
79
  | 来源 | 填写内容 |
80
80
  |---|---|
81
- | 某个发布版本 | `git+https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro.git#v1.6.0` |
81
+ | 某个发布版本 | `git+https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro.git#v1.7.0` |
82
82
  | 最新开发版 | `git+https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro.git#main` |
83
83
  | 离线安装包 | 下载 [`dsh-cliproxyapi-pro.tgz`](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/releases/latest/download/dsh-cliproxyapi-pro.tgz)（始终是最新版），填写它的本地绝对路径 |
84
84
  | 本地源码（开发用） | 克隆后的仓库目录绝对路径；以链接方式安装，改代码后重载插件即生效 |
@@ -88,31 +88,39 @@ dsh plugin --profile <profile 名称> add dsh-cliproxyapi-pro
88
88
  ## 快速上手
89
89
 
90
90
  1. **打开设置面板**：**设置** → 左侧导航的 **CLIProxyAPI** 页（账号、模型与协议都在这里）。插件自身的更新在左侧栏 **插件** → **CLIProxyAPI**，或 **设置** → **内置插件** → **CLIProxyAPI** 标签页，这两处只有更新功能。
91
- 2. **填写连接信息**：在「连接与认证配置」里填 **CLIProxyAPI 服务地址**（如 `http://127.0.0.1:8317`，不用加 `/v1`）和 **API Key**（本地免密的 CPA 可留空），点 **保存设置并应用**。
92
- 3. **选择模型**：连接成功后，「模型显示筛选」会列出 CPA 上的全部模型，并已为每个家族勾好最新的一个。按需增减后点 **保存模型勾选**。
91
+ 2. **添加账号**：点 **+ 添加账号**，填账号名称、**服务地址**（如 `http://127.0.0.1:8317`，不用加 `/v1`）和 **API Key**（本地免密的 CPA 可留空），点 **连接**。连接成功即创建并启用账号；失败时会显示原因，可修正后重试，或选「仍然添加（不启用）」。
92
+ 3. **选择模型**：在账号的 **模型** 标签里，CPA 上的全部模型已列出，并已为每个家族勾好最新的一个。按需增减后点底部的 **保存并应用**。
93
93
  4. **开始使用**：回到对话框，打开模型选择器，就能在以账号名称命名的分组里看到这些模型。
94
94
 
95
95
  CPA 就在本机默认端口 `8317` 且没有设置密钥时，什么都不用填，插件会自动发现它。
96
96
 
97
97
  ## 截图
98
98
 
99
- **1. 账号栏与账号状态。** 顶部账号栏列出所有账号：绿点表示已连接，灰点加「未启用」标记表示已停用。图中刚用「+ 添加账号」新增了第二个账号「CLI Proxy API 2」：它默认停用，拥有独立的路由 `cli-proxy-2`；由于还没填写服务地址，探测提示本地没有找到 CPA 服务。
99
+ 图 1–5 是离线组件渲染：用本插件的真实界面代码加示例数据（`example.com` 地址、虚构账号）在浏览器中渲染，配色按 DSH 深色主题近似，实际颜色跟随你的 DSH 主题。图 6 是 1.6.0 在 DSH 桌面版中的实际截图。
100
100
 
101
- ![账号栏：一个已连接账号和一个刚添加、未启用的账号](https://raw.githubusercontent.com/TinyBOOOOM/dsh-cliproxyapi-pro/main/assets/screenshots/accounts.png)
101
+ **1. 账号与连接。** 设置左侧导航的 **CLIProxyAPI** 页：顶部账号栏三个标签共用；账号标题下是连接状态、地址和模型数，右侧「启用」开关立即生效，「⋯」菜单里是「立即探测刷新」和「删除此账号」。「连接」标签里每项一行，地址旁可「测试连接」（用正在编辑的值，不保存），次要说明在 ⓘ 里。
102
102
 
103
- **2. 模型显示筛选。** 从 CPA 服务发现的全部 168 个模型，支持全部发现 / 已勾选 / 未勾选切换、家族标签（GPT、CLAUDE、GEMINI、GROK……）、搜索与批量操作。只有勾选的模型会同步到 DSH 模型选择器；每个模型显示将使用的协议（图中为 OpenAI Responses）、图片输入、推理档位与上下文长度，「编辑参数」可打开单模型参数覆盖。
103
+ ![账号栏、账号标题与连接标签（离线渲染）](https://raw.githubusercontent.com/TinyBOOOOM/dsh-cliproxyapi-pro/main/assets/screenshots/connection.png)
104
104
 
105
- ![模型筛选：家族标签、已勾选模型、协议与能力标记](https://raw.githubusercontent.com/TinyBOOOOM/dsh-cliproxyapi-pro/main/assets/screenshots/model-filter.png)
105
+ **2. 模型与统一保存。** 「模型」标签列出该 CPA 上的全部模型：全部 / 已勾选 / 未勾选、家族筛选、搜索、批量操作与「恢复推荐精选」；勾选的模型显示将使用的协议，可「编辑参数」。连接和模型的改动统一记录，底部出现「有未保存的更改 · 放弃更改 / 保存并应用」。
106
106
 
107
- **3. 连接与认证配置。** 每个账号独立的设置：「启用此账号」开关、服务地址、保存在该账号独立引用名（`CLI_PROXY_API_KEY_2`）下的 API Key、接口协议、账号名称、可折叠的高级设置，以及「保存设置并应用」与「删除此账号」。
107
+ ![模型标签与底部保存栏（离线渲染）](https://raw.githubusercontent.com/TinyBOOOOM/dsh-cliproxyapi-pro/main/assets/screenshots/model-filter.png)
108
108
 
109
- ![未启用账号的连接设置，使用独立的密钥引用名](https://raw.githubusercontent.com/TinyBOOOOM/dsh-cliproxyapi-pro/main/assets/screenshots/connection.png)
109
+ **3. 额度。** 「额度」标签：管理密钥、额度数据与刷新、凭证分布条，按渠道分组的凭证（套餐、前缀、状态、5 小时 / 每日 / 每周等额度条与重置时间；Devin 显示每日 / 每周额度，所有 Devin 模型共用；没有额度接口的渠道只显示状态与近期请求），以及可展开的「模型 → 渠道」表。标签上显示该账号可用凭证中最低的剩余额度。
110
110
 
111
- **4. 插件更新卡片。** 使用真实组件与虚构的更新状态离线渲染（拍摄于更新卡片仍位于账号页顶部、默认收起的版本）：一行显示当前版本与更新状态，展开后是通道、下载区域和自动更新开关。现在它单独位于插件页，并默认展开。不是正在运行的 GUI 截图，也不代表实际发布版本。
111
+ ![额度标签：分布条与按渠道分组的凭证额度（离线渲染）](https://raw.githubusercontent.com/TinyBOOOOM/dsh-cliproxyapi-pro/main/assets/screenshots/quota.png)
112
112
 
113
- ![插件更新卡片默认收起：一行显示当前版本与新版本提示](https://raw.githubusercontent.com/TinyBOOOOM/dsh-cliproxyapi-pro/main/assets/screenshots/updates.png)
113
+ **4. 对话框里的额度。** 模型选择器左侧的徽标显示当前模型可用凭证中最充足的剩余额度；点击后列出服务该模型的每个凭证及其额度窗口。只对本插件同步、且所属账号已填写管理密钥的模型显示。
114
114
 
115
- ![展开后的插件更新设置：通道、下载区域与自动开关](https://raw.githubusercontent.com/TinyBOOOOM/dsh-cliproxyapi-pro/main/assets/screenshots/updates-expanded.png)
115
+ ![模型选择器旁的额度徽标与弹出列表（离线渲染）](https://raw.githubusercontent.com/TinyBOOOOM/dsh-cliproxyapi-pro/main/assets/screenshots/quota-badge.png)
116
+
117
+ **5. 添加账号。** 填名称、地址和 API Key 后点「连接」：先测试，成功才创建并启用账号；失败时显示原因，可选「仍然添加（不启用）」。
118
+
119
+ ![添加账号表单（离线渲染）](https://raw.githubusercontent.com/TinyBOOOOM/dsh-cliproxyapi-pro/main/assets/screenshots/add-account.png)
120
+
121
+ **6. 内置插件里的插件更新页**（1.6.0 实际截图）。**设置** → **内置插件** → **CLIProxyAPI** 标签页只有插件更新：检查更新与离线下载、检测到 DSH 插件市场后的「立即更新」、更新通道、下载区域，以及自动检查 / 自动下载 / 自动安装开关。图中已是稳定通道最新版本，所以「立即更新」不可用。
122
+
123
+ ![内置插件中的 CLIProxyAPI 更新页：版本状态、插件市场更新、通道、区域与自动开关](https://raw.githubusercontent.com/TinyBOOOOM/dsh-cliproxyapi-pro/main/assets/screenshots/updates.png)
116
124
 
117
125
  ## 功能详解
118
126
 
@@ -137,7 +145,10 @@ CPA 就在本机默认端口 `8317` 且没有设置密钥时，什么都不用
137
145
 
138
146
  - 每个账号写入自己的一组路由：第一个账号为 `cli-proxy` / `cli-proxy-responses` / `cli-proxy-messages`，之后依次为 `cli-proxy-2*`、`cli-proxy-3*`……；密钥引用名依次为 `CLI_PROXY_API_KEY`、`CLI_PROXY_API_KEY_2`……。模型选择器按账号名称分组。
139
147
  - **停用**账号：保留全部配置，但移除它的路由，模型从选择器中消失；其他账号不受影响。
140
- - **新增**账号默认停用。可先填好地址和密钥，点「立即探测刷新」预览模型并勾选，再打开「启用此账号」保存。
148
+ - **新增**账号：「+ 添加账号」先用填写的地址和密钥测试连接，成功才创建并启用；也可以选择「仍然添加（不启用）」。
149
+ - 每个账号的页面分 **连接 / 模型 / 额度** 三个标签，顶部账号栏对三个标签共用。账号标题旁的「启用」开关立即生效；「⋯」菜单里是「立即探测刷新」和「删除此账号」。
150
+ - 连接和模型的改动统一记录，底部出现「有未保存的更改 · 放弃更改 / 保存并应用」；切换账号前会提醒未保存的更改。「测试连接」用正在编辑的地址和密钥探测，不保存任何内容。
151
+ - 次要说明收进标签旁的 ⓘ 提示（悬停、键盘聚焦或点击打开）。
141
152
  - 填写了服务地址的账号**只连接该地址**，连不上就报错，不会悄悄改连本地 `:8317`，避免两个账号指向同一个服务。
142
153
  - 不同账号的路由 ID 不能重叠，冲突的修改会被拒绝。
143
154
  - **删除**账号会移除它的路由，但保留凭证服务里的密钥。
@@ -158,6 +169,18 @@ CPA 对每个模型同时提供 OpenAI Chat、OpenAI Responses、Anthropic Messa
158
169
  - 可以改为「统一使用」某一种协议，或在单个模型的「编辑参数」里指定。
159
170
  - 你在路由上手动加的其他字段（如 `retryPolicy`）会被保留。
160
171
 
172
+ ### 渠道额度（「额度」标签页与对话框额度徽标）
173
+
174
+ 每个账号的 **额度** 标签（与 **连接**、**模型** 并列）显示该账号的渠道额度；标签上显示该账号可用凭证中最低的剩余额度。
175
+
176
+ - **填写管理密钥**：在「额度」标签里为每个账号填写 CPA 的管理密钥（CPA 配置里的 `remote-management.secret-key`；远程 CPA 还需开启 `remote-management.allow-remote`）。密钥保存在 DSH 凭证服务中，引用名第一个账号为 `CLI_PROXY_MANAGEMENT_KEY`，其他账号为 `CLI_PROXY_MANAGEMENT_KEY_<账号 ID>`（如 `CLI_PROXY_MANAGEMENT_KEY_ACCOUNT_2`）；不会写入 `state.json`、设置或日志，也不会返回给页面。
177
+ - **由宿主读取**：宿主用管理接口读取该 CPA 的全部凭证（`/v0/management/auth-files`）、每个凭证服务的模型列表，并经 `/v0/management/api-call` 查询上游额度：Codex、Claude、Antigravity、Gemini CLI、Kimi（含 Kimi 国际版 kimi.ai）、xAI、Devin、Meta。CPA 插件提供的渠道（凭证标记了 `supports_quota`）改走 CPA 自己的 `/v0/management/quota/fetch`。Devin 的每日 / 每周额度是整个账号共用的，所有 `devin/…` 模型显示同一组额度。Meta 的额度接口需要凭证文件里的 `dca_token`，宿主每次查询时经管理接口读取，只用于这一次请求，不保存、不记录。API Key 类渠道（OpenAI 兼容、Gemini / Claude / Codex API Key）和 Vertex 没有额度接口（CPA 自带面板同样不显示），只显示账号状态与近期请求数；xAI 付费账号也没有额度计数（CPA 面板为此会真实发一次对话请求探测，本插件不这样做，以免后台刷新产生费用）。
178
+ - **额度页**：采用 DSH 原生设置页的行式布局：管理密钥、额度数据与刷新、凭证分布条（充足 / 偏低 / 耗尽 / 停用异常），按渠道分组的凭证列表（套餐、前缀、状态、5 小时 / 每周 / 每月 / 每日额度条与重置时间，问题与剩余最少的排在前面）、渠道筛选（凭证较多时可搜索），以及可展开的「模型 → 渠道」表，列出模型选择器中每个模型实际匹配到的凭证。
179
+ - **对话框徽标**：模型选择器左侧的小徽标（信号格 + 百分比）显示当前所选模型可用凭证中最充足的剩余额度，点击可查看每个凭证的额度。只对本插件同步、且所属账号已填写管理密钥的模型显示；没有管理密钥时不显示徽标。在新建对话页（输入栏尚未接管会话时），徽标显示在输入框上方工作区一行的右侧。
180
+ - **精确匹配**：只在所选模型所属的账号（按路由 `cli-proxy*`、`cli-proxy-2*`…）里找凭证；带前缀的模型（如 `devin/claude-opus-5-5`）只匹配该前缀的凭证；不带前缀的同名模型（如 `claude-opus-5-5`）优先匹配不带前缀的凭证，Claude 渠道与 Devin 渠道不会混用。Antigravity 等按模型分组的额度窗口只取与当前模型相符的那一组。
181
+ - **排查**：`/cpa-status` 会附带额度摘要：每个账号的管理密钥状态、额度状态、凭证数，以及模型选择器中每个模型匹配到的凭证和剩余额度（不输出密钥）。
182
+ - **刷新**：结果在宿主端缓存 5 分钟；有页面在看时才在后台刷新过期账号，也可手动「刷新额度」。管理密钥被拒（401/403）后暂停该账号的自动刷新，直到更新密钥或手动刷新，避免触发 CPA 的错误密钥封禁。
183
+
161
184
  ## 插件自身更新
162
185
 
163
186
  **插件更新** 位于左侧栏 **插件** → **CLIProxyAPI** 的插件页，以及 **设置** → **内置插件** → **CLIProxyAPI** 标签页；这两处只有更新功能，账号与模型设置在 **设置** 左侧导航的 **CLIProxyAPI** 页。更新卡片在插件页默认展开，摘要行显示当前版本和更新状态，可随时收起；后台检查仍按保存的开关运行，展开状态不会被轮询重置。它只管理 `dsh-cliproxyapi-pro` 自身，不会更新 CPA 服务或 DSH 宿主，也不改变 CPA 请求的路由、账号或模型勾选。更新设置修改后立即保存；卡片独立轮询状态，不会重载未保存的账号表单。
@@ -192,7 +215,7 @@ CPA 对每个模型同时提供 OpenAI Chat、OpenAI Responses、Anthropic Messa
192
215
  没有插件市场或需要离线升级时使用：
193
216
 
194
217
  1. 点击 **检查更新**；有更高版本时，点 **下载更新** 并确认版本号，或等待已启用的自动检查 / 自动下载。
195
- 2. 下载先通过 npm 元数据中的 **SHA-512** 完整性校验，再验证 gzip / tar、预期文件与目录、包名和版本；拒绝路径穿越、链接等特殊条目、依赖和安装生命周期脚本。只保存离线包，不解压到安装目录，也不执行包内代码。
218
+ 2. 下载先通过 npm 元数据中的 **SHA-512** 完整性校验，再验证 gzip / tar、包名和版本，并要求包内每个文件都在该包自己的 `package.json` `files` 中声明（`package.json`、README、LICENSE 等 npm 总会打包的文件除外）；拒绝路径穿越、隐藏文件、`node_modules`、链接等特殊条目、依赖和安装生命周期脚本。下载被拒绝时，具体原因会写入 DSH 日志。只保存离线包，不解压到安装目录，也不执行包内代码。
196
219
  3. 校验成功后，卡片显示安装包的绝对路径与适用的升级命令。包保存在 `<Profile 目录>/.dsh-cliproxyapi/updates/dsh-cliproxyapi-pro-<version>.tgz`。
197
220
  4. **先保存工作并完全关闭 DSH**，再在终端执行卡片提供的命令。示意如下，以卡片里的实际 profile 名称和绝对路径为准：
198
221
 
@@ -204,47 +227,9 @@ CPA 对每个模型同时提供 OpenAI Chat、OpenAI Responses、Anthropic Messa
204
227
 
205
228
  **本地链接安装（`link:`）** 可以检查并下载包，但不会提供升级命令，也不会覆盖链接的源码目录。若要保留源码开发方式，请在合适时机手动更新 Git 源码，再重启 DSH；通过离线包重新安装会将插件的安装来源从链接切换到离线包。
206
229
 
207
- ## Agent 工具与斜杠命令
208
-
209
- ### `cliproxyapi` 工具
210
-
211
- DSH 的 Agent 可以用这个工具查看和配置插件，你只需用自然语言提要求。
212
-
213
- | `action` | 作用 |
214
- |---|---|
215
- | `status` | 查看所有账号（或 `account` 指定的账号）的状态与模型 |
216
- | `refresh` | 立即探测并同步；不带 `account` 时刷新全部账号 |
217
- | `configure` | 修改一个账号（默认第一个），保存后立即刷新 |
218
- | `add_account` | 新增账号；给了 `baseURL` 时默认启用，否则停用 |
219
- | `remove_account` | 删除 `account` 指定的账号及其路由 |
220
-
221
- 参数（除 `action` 外都可选）：
222
-
223
- | 参数 | 说明 |
224
- |---|---|
225
- | `account` | 账号 id（如 `default`、`account-2`），也可用路由 ID 或账号名称 |
226
- | `enabled` | 启用 / 停用该账号 |
227
- | `baseURL` | CPA 地址，如 `http://127.0.0.1:8317`；空字符串表示自动发现 |
228
- | `apiKey` | Bearer 密钥，保存到该账号的 `apiKeyEnv` 引用名下 |
229
- | `apiKeyEnv` | 密钥引用名（`[A-Za-z_][A-Za-z0-9_]*`） |
230
- | `provider` | `llm-pi-ai` 路由 ID，每个账号唯一 |
231
- | `displayName` | 账号名称，也是模型选择器中的分组名 |
232
- | `protocolMode` | `auto`（按家族走原生协议，默认）或 `fixed` |
233
- | `protocol` | `fixed` 时使用的协议：`openai-completions` / `openai-responses` / `anthropic-messages` |
234
- | `selectedModels` | 显示在选择器中的模型 id 列表；`[]` 表示全部 |
235
- | `includePrefix` / `excludePrefix` | 逗号分隔的模型 id 关键词 |
236
- | `modelOverrides` | `{ [modelId]: { contextWindow?, maxTokens?, image?, reasoningLevels?, protocol? } }`，整体替换 |
237
-
238
- 示例：
239
-
240
- ```json
241
- { "action": "configure", "baseURL": "http://127.0.0.1:8317", "apiKey": "sk-...", "selectedModels": ["gpt-6.1-sol", "claude-opus-5-5"] }
242
- { "action": "add_account", "displayName": "Backup CPA", "baseURL": "https://other-cpa:8317", "apiKey": "sk-...", "selectedModels": ["gpt-6-astra"] }
243
- { "action": "configure", "account": "account-2", "enabled": false }
244
- { "action": "remove_account", "account": "account-2" }
245
- ```
230
+ ## 斜杠命令与 HTTP 接口
246
231
 
247
- 输出包含 `accounts[]`（每个账号的 `id`、`displayName`、`provider`、`enabled`、`state`、`endpoint`、`modelCount`、`totalDiscovered`、`error`）和文字摘要 `summary`。`state` 取值：`idle`、`probing`、`connected`、`disabled`、`error`。
232
+ 本插件不注册任何 Agent 工具，不占用模型上下文。账号与模型在 **设置** → **CLIProxyAPI** 页管理，也可以用下面的斜杠命令查看和刷新。
248
233
 
249
234
  ### 斜杠命令
250
235
 
@@ -262,10 +247,14 @@ DSH 的 Agent 可以用这个工具查看和配置插件，你只需用自然语
262
247
  | POST | `/api/dsh-cliproxyapi/save` | `{ accountId?, …账号字段, apiKey?, clearApiKey?, refreshIntervalSeconds?, probeTimeoutMs? }` | 保存账号（缺省为第一个）；只有全局字段时只保存全局设置 |
263
248
  | POST | `/api/dsh-cliproxyapi/accounts/add` | 账号字段（可选） | 新增账号，默认停用；返回 `createdId` |
264
249
  | POST | `/api/dsh-cliproxyapi/accounts/remove` | `{ accountId }` | 删除账号及其路由 |
250
+ | POST | `/api/dsh-cliproxyapi/accounts/test` | `{ accountId?, baseURL?, apiKey? }` | 用未保存的地址和密钥测试连接，不保存、不写路由；`apiKey` 留空时用该账号已保存的密钥；不返回密钥 |
265
251
  | GET | `/api/dsh-cliproxyapi/updates/status` | — | 只读更新状态，不主动联网检查 |
266
252
  | POST | `/api/dsh-cliproxyapi/updates/check` | `{}` | 主动检查所选通道与区域；手动检查不触发自动下载 |
267
253
  | POST | `/api/dsh-cliproxyapi/updates/save` | `{ autoCheck?, autoDownload?, autoInstall?, channel?, region? }` | 只保存这五项更新设置，与账号配置独立 |
268
254
  | POST | `/api/dsh-cliproxyapi/updates/download` | `{ version }` | 下载最近一次检查确认的新版本，完成校验后保存离线包；不安装 |
255
+ | GET | `/api/dsh-cliproxyapi/quota/status` | — | `{ ok, quota }`：缓存的额度快照；过期账号在后台刷新 |
256
+ | POST | `/api/dsh-cliproxyapi/quota/refresh` | `{ accountId? }` | 开始刷新一个或全部账号的额度并立即返回（快照中 `refreshing` 为真） |
257
+ | POST | `/api/dsh-cliproxyapi/quota/save` | `{ accountId, managementKey?, clear? }` | 保存或清除该账号的管理密钥，并开始刷新额度；响应不含密钥 |
269
258
 
270
259
  更新接口的操作响应采用 `{ ok, update }`，状态包含 `currentVersion`、`latestVersion`、`available`、`channel`、`region`、`effectiveRegion`、`autoCheck`、`autoDownload`、`autoInstall`、`checking`、`downloading`、`lastCheckedAt`、`error` / `errorCode`、`blockedReason`、`downloadedVersion`、`downloadPath` 与 `upgradeCommand`。未检查或未下载的相关字段为 `null`。`channel` 为 `stable` / `beta` / `dev`，`region` 为 `auto` / `global` / `cn`；`effectiveRegion` 为本次成功检查使用的 `global` / `cn`（此前为 `null`）。
271
260
 
@@ -291,7 +280,7 @@ DSH 的 Agent 可以用这个工具查看和配置插件，你只需用自然语
291
280
  }
292
281
  ```
293
282
 
294
- 文件每次读取都会重新加载，手动修改后点「立即探测刷新」即可生效。旧版（1.3.x 及以前）的单账号文件会自动迁移为 id 为 `default` 的账号，路由、密钥和勾选保持不变，原文件备份为 `state.v1.json`。
283
+ 文件每次读取都会重新加载，手动修改后在账号「⋯」菜单里点「立即探测刷新」即可生效。旧版（1.3.x 及以前）的单账号文件会自动迁移为 id 为 `default` 的账号，路由、密钥和勾选保持不变，原文件备份为 `state.v1.json`。
295
284
 
296
285
  - **更新设置**：独立保存在 `<Profile 目录>/.dsh-cliproxyapi/update-settings.json`，不扩展或改写账号的 `state.json` v2，也不接触凭证。首次没有此文件时采用下列默认值：
297
286
 
@@ -309,7 +298,7 @@ DSH 的 Agent 可以用这个工具查看和配置插件，你只需用自然语
309
298
  设置通过面板保存后立即应用。手动编辑此文件后需重载插件或重启 DSH 才会重新读取；文件损坏、结构 / 字段无效或无法读取时采用关闭自动联网检查的安全默认值。版本检查结果、候选版本、下载完成提示与命令只在内存中，插件重载后重新检查；下载包仍位于独立的 `updates` 子目录，由用户按需清理。
310
299
  - **密钥**：通过 DSH 的 `credentials` 服务按引用名存取；凭证服务里没有时，回退读取同名环境变量。
311
300
  - **环境变量**：`CLIPROXYAPI_BASE_URL` 只用于服务地址留空的账号的自动发现。
312
- - **插件行配置**：`cordis.patch.yml` 中本插件行的 `config` 会在启动时叠加到状态文件上：包含 `accounts` 时替换账号列表，否则其中的字段作用于第一个账号。一般保持 `{}`，用面板或工具配置即可。
301
+ - **插件行配置**：`cordis.patch.yml` 中本插件行的 `config` 会在启动时叠加到状态文件上：包含 `accounts` 时替换账号列表，否则其中的字段作用于第一个账号。一般保持 `{}`，用设置面板配置即可。
313
302
 
314
303
  ## 升级与卸载
315
304
 
@@ -319,7 +308,7 @@ DSH 的 Agent 可以用这个工具查看和配置插件，你只需用自然语
319
308
  ## 常见问题
320
309
 
321
310
  **模型选择器里看不到模型？**
322
- 确认账号已打开「启用此账号」，并且至少勾选了一个模型（或勾选为空，表示全部）。可以运行 `/cpa-status` 查看每个账号的状态。
311
+ 确认账号标题旁的「启用」已打开，并且至少勾选了一个模型（或勾选为空，表示全部）。可以运行 `/cpa-status` 查看每个账号的状态。
323
312
 
324
313
  **提示「none of the selected models matched」？**
325
314
  已勾选的模型在这台服务器上都不存在（常见于换了服务器）。面板里仍会列出该服务器的模型，重新勾选，或点「恢复推荐精选」后保存。
@@ -350,13 +339,10 @@ DSH 使用的 pnpm 可能设置了新版本发布后的等待期（`minimumRelea
350
339
  > 给 DeepSeek Harness 中的 AI Agent：用户要求安装或配置本插件时按以下步骤执行。本包没有 npm 依赖，也没有构建脚本。
351
340
 
352
341
  1. **安装**：调用 `plugin_manager`：`{"action": "install_bundle", "target": "dsh-cliproxyapi-pro", "enabled": true}`。查看结果中的 `application` 与 `warnings`；`restart-required` 表示需要重启 DSH 后新代码才会运行。
353
- 2. **配置**：使用 `cliproxyapi` 工具。
354
- - CPA 在本机 `http://127.0.0.1:8317` 且无鉴权：无需配置，调用 `{"action": "refresh"}`。
355
- - 远程地址或有密钥：`{"action": "configure", "baseURL": "...", "apiKey": "..."}`（作用于第一个账号）；额外的账号用 `{"action": "add_account", ...}`；指定账号时传 `"account": "<id>"`。
356
- - 用 `selectedModels`（取自 `status` 输出中的精确 id）精简模型选择器。
357
- 3. **验证**：`{"action": "status"}` 中每个启用的账号 `state` 为 `connected` 且 `modelCount > 0`。告诉用户模型已出现在 DSH 模型选择器中（按账号名称分组），可在 **设置** 左侧导航的 **CLIProxyAPI** 页管理账号。
342
+ 2. **配置**：本插件不提供 Agent 工具，账号由用户在界面里配置。CPA 在本机 `http://127.0.0.1:8317` 且无鉴权时无需配置，插件启动后会自动发现；否则请用户打开 **设置** 左侧导航的 **CLIProxyAPI** 页，点 **+ 添加账号** 并填写服务地址和 API Key，再在 **模型** 标签勾选需要的模型。
343
+ 3. **验证**：请用户运行 `/cpa-status`，每个启用的账号应为 `connected` 且模型数大于 0。告诉用户模型已出现在 DSH 模型选择器中（按账号名称分组）。
358
344
 
359
- 不要把 API Key 回显给用户，也不要写入任何文件。
345
+ 不要向用户索要 API Key，也不要把它写入任何文件；密钥只在设置页填写。
360
346
 
361
347
  ## 开发
362
348
 
@@ -384,7 +370,7 @@ npm run pack:check # 查看打包文件列表
384
370
 
385
371
  发版只需推送 `v<版本号>` 标签：GitHub Actions 会运行测试、创建 GitHub Release 并附上安装包，再通过 npm 受信任发布（不使用任何 token）上传到 npm，并附带来源证明。稳定版本发布到 npm `latest`；Beta / 开发预发布分别进入 `beta` / `dev`，对应 GitHub Release 标记为预发布，不覆盖稳定通道。更新器只核对 registry 提供的 SHA-512 完整性与包结构，不验证发行者签名或 npm provenance。
386
372
 
387
- 修改代码前请阅读 [AGENTS.md](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/blob/main/AGENTS.md)；变更记录见 [CHANGELOG.md](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/blob/main/CHANGELOG.md)。欢迎提交 Issue 和 Pull Request，修改说明文档时请同时更新中英文两份。
373
+ 修改代码前请阅读 [AGENTS.md](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/blob/main/AGENTS.md)；变更记录见 [CHANGELOG.md](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/blob/main/CHANGELOG.md)（英文版：[CHANGELOG.en.md](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/blob/main/CHANGELOG.en.md)）。欢迎提交 Issue 和 Pull Request，修改说明文档时请同时更新中英文两份。
388
374
 
389
375
  ## 许可证
390
376