dsh-cliproxyapi-pro 1.4.0 → 1.4.1

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 (5) hide show
  1. package/CHANGELOG.md +8 -0
  2. package/README.en.md +299 -0
  3. package/README.md +209 -149
  4. package/package.json +2 -2
  5. package/README.zh.md +0 -237
package/CHANGELOG.md CHANGED
@@ -2,6 +2,14 @@
2
2
 
3
3
  All notable changes to this plugin. Versions follow [Semantic Versioning](https://semver.org/).
4
4
 
5
+ ## 1.4.1 — 2026-10-19
6
+
7
+ Documentation and release tooling only; the plugin code is unchanged from 1.4.0.
8
+
9
+ ### Changed
10
+ - `README.md` is now Chinese (the default on GitHub and npm), with the English version in `README.en.md`. Both are rewritten: a quick start, four verified ways to install (DSH **Plugins** page, the DSH agent, `dsh plugin add`, GitHub / offline package), upgrading and uninstalling, and a FAQ. Images and links use absolute URLs so they also render on npmjs.com.
11
+ - Releases publish to npm through npm trusted publishing (GitHub Actions OIDC) with an automatic provenance statement; no npm token is stored anywhere. The release workflow can also be run by hand for an existing tag and skips steps that are already done.
12
+
5
13
  ## 1.4.0 — 2026-10-19
6
14
 
7
15
  First public release.
package/README.en.md ADDED
@@ -0,0 +1,299 @@
1
+ # dsh-cliproxyapi-pro
2
+
3
+ [中文](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/blob/main/README.md) | English
4
+
5
+ [![npm](https://img.shields.io/npm/v/dsh-cliproxyapi-pro?label=npm)](https://www.npmjs.com/package/dsh-cliproxyapi-pro)
6
+ [![CI](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/actions/workflows/ci.yml/badge.svg)](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/actions/workflows/ci.yml)
7
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/blob/main/LICENSE)
8
+
9
+ **Bring the models of [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) (CPA) into the model picker of [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH).**
10
+
11
+ Enter a server URL and an API key, and the plugin reads the CPA model catalog and synchronizes the models you check — with their context window, image input and reasoning levels — into DSH, each over the protocol that suits it best. Connect several CPA accounts at once and enable or disable each one on its own.
12
+
13
+ - **Multiple accounts**: each account has its own URL, key, model selection and parameters, and can be switched off at any time.
14
+ - **Works out of the box**: on the first connection, the newest model of each family in that server's own catalog is checked (at most 12), so the picker isn't flooded with hundreds of models.
15
+ - **Native protocols**: Claude over Anthropic Messages, GPT / Codex / Grok over OpenAI Responses, everything else over OpenAI Chat — fewer protocol translations inside CPA.
16
+ - **Visual management**: check models and edit per-model parameters in the settings panel, or let the DSH agent configure things for you through the `cliproxyapi` tool.
17
+ - **Secure**: API keys live only in the DSH credentials service, never in configuration files.
18
+ - **Zero dependencies**: no npm dependencies and no build step; installs in seconds.
19
+
20
+ Works with DSH `0.2.0-rc.1` and later (desktop and web).
21
+
22
+ ## Contents
23
+
24
+ - [Installation](#installation)
25
+ - [Getting started](#getting-started)
26
+ - [Screenshots](#screenshots)
27
+ - [Features in detail](#features-in-detail)
28
+ - [Agent tool and slash commands](#agent-tool-and-slash-commands)
29
+ - [Storage and configuration](#storage-and-configuration)
30
+ - [Upgrading and uninstalling](#upgrading-and-uninstalling)
31
+ - [FAQ](#faq)
32
+ - [AI installation guide](#ai-installation-guide)
33
+ - [Development](#development)
34
+ - [License](#license)
35
+
36
+ ## Installation
37
+
38
+ The plugin is published on npm as [`dsh-cliproxyapi-pro`](https://www.npmjs.com/package/dsh-cliproxyapi-pro) and is also available from the China mainland mirror (npmmirror). Pick any one of the methods below.
39
+
40
+ ### Option 1: the DSH Plugins page (recommended)
41
+
42
+ 1. Open DSH and click **Plugins** in the left sidebar.
43
+ 2. Click **Add plugin** at the top of the page.
44
+ 3. Enter the package name:
45
+
46
+ ```text
47
+ dsh-cliproxyapi-pro
48
+ ```
49
+
50
+ To pin a version, write `dsh-cliproxyapi-pro@1.4.1`.
51
+ 4. Click **Install**. When it finishes, the dialog offers to enable the plugin right away — accept it.
52
+
53
+ > If downloads are slow in mainland China, open **Registry** next to the input and choose **the mainland China mirror**.
54
+
55
+ ### Option 2: ask the agent in DSH
56
+
57
+ Just say in a DSH conversation:
58
+
59
+ ```text
60
+ Install the DSH plugin dsh-cliproxyapi-pro
61
+ ```
62
+
63
+ The agent installs and enables it with `plugin_manager` (depending on your permission settings, it may ask for your approval). Then ask it to configure the plugin, e.g. "set the CLIProxyAPI URL to http://127.0.0.1:8317 with key sk-…".
64
+
65
+ ### Option 3: command line
66
+
67
+ ```bash
68
+ dsh plugin --profile <profile name> add dsh-cliproxyapi-pro
69
+ ```
70
+
71
+ This downloads the plugin from npm and adds it to the profile's enabled plugins in one step. The DSH desktop profile is usually called `desktop`; if DSH is running, restart it to load the plugin.
72
+
73
+ ### Option 4: from GitHub (without npm)
74
+
75
+ In **Add plugin**, or as the `plugin_manager` `target`, you can also enter:
76
+
77
+ | Source | What to enter |
78
+ |---|---|
79
+ | A released version | `git+https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro.git#v1.4.1` |
80
+ | Latest development version | `git+https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro.git#main` |
81
+ | Offline package | Download [`dsh-cliproxyapi-pro.tgz`](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/releases/latest/download/dsh-cliproxyapi-pro.tgz) (always the latest release) and enter its absolute local path |
82
+ | Local source (development) | Absolute path of a cloned repository; installed as a link, so code changes go live when the plugin reloads |
83
+
84
+ All versions are listed under [Releases](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/releases).
85
+
86
+ ## Getting started
87
+
88
+ 1. **Open the settings panel**: sidebar **Plugins** → **CLIProxyAPI**, or **Settings** → **Built-in plugins** → the **CLIProxyAPI** tab.
89
+ 2. **Enter the connection**: under **Connection & Authentication**, fill in the **CLIProxyAPI Base URL** (e.g. `http://127.0.0.1:8317`, without `/v1`) and the **API Key** (leave it empty for a local CPA without authentication), then click **Save & Apply**.
90
+ 3. **Choose models**: once connected, **Model Picker Filter** lists every model on the server, with the newest model of each family already checked. Adjust the selection and click **Apply Selected Models**.
91
+ 4. **Use them**: open the model picker in a conversation; the models appear in a group named after the account.
92
+
93
+ If CPA runs on this machine on the default port `8317` without a key, there is nothing to fill in: the plugin finds it automatically.
94
+
95
+ ## Screenshots
96
+
97
+ The panel follows the DSH display language; the screenshots show the Chinese UI.
98
+
99
+ **1. Account bar and account status.** The bar at the top lists every account: a green dot means connected, a grey dot plus the **Off** badge means disabled. Here a second account, *CLI Proxy API 2*, was just added with **+ Add Account**: it starts disabled, gets its own provider route `cli-proxy-2`, and — since no base URL is set yet — the probe reports that no local CPA was found.
100
+
101
+ ![Account bar with one connected and one newly added, disabled account](https://raw.githubusercontent.com/TinyBOOOOM/dsh-cliproxyapi-pro/main/assets/screenshots/accounts.png)
102
+
103
+ **2. Model picker filter.** All 168 models discovered from the CPA server, with All / Checked / Unchecked tabs, family chips (GPT, CLAUDE, GEMINI, GROK, …), search and bulk actions. Checked models are the only ones synchronized into the DSH model picker; each shows the protocol it will use (here OpenAI Responses), image input, reasoning levels and context window, and **Edit Parameters** opens its per-model overrides.
104
+
105
+ ![Model filter with family chips, checked models, protocol and capability badges](https://raw.githubusercontent.com/TinyBOOOOM/dsh-cliproxyapi-pro/main/assets/screenshots/model-filter.png)
106
+
107
+ **3. Connection & Authentication.** Per-account settings: the **Enable This Account** switch, base URL, API key stored under the account's own credential ref (`CLI_PROXY_API_KEY_2`), wire protocol, account name, the collapsible advanced section, **Save & Apply** and **Delete Account**.
108
+
109
+ ![Connection settings of a disabled account with its own credential ref](https://raw.githubusercontent.com/TinyBOOOOM/dsh-cliproxyapi-pro/main/assets/screenshots/connection.png)
110
+
111
+ ## Features in detail
112
+
113
+ ### Discovery and synchronization
114
+
115
+ - The base URL can be local or remote; suffixes such as `/v1`, `/v1/chat/completions` and `/v1/messages` are stripped.
116
+ - With an empty URL, the plugin tries, in order: the existing route's URL, the `CLIPROXYAPI_BASE_URL` environment variable, and local `127.0.0.1:8317`.
117
+ - The enriched catalog comes from `/v1/models?client_version=pi` (standard OpenAI `data[]` catalogs work too); `owned_by` from `/v1/models` identifies each model's family.
118
+ - All accounts refresh on a shared interval (300 s by default); an unchanged catalog writes no settings.
119
+
120
+ ### Model selection
121
+
122
+ - Search, family chips, All / Checked / Unchecked tabs and bulk selection. **Only checked models appear in the model picker**; an empty selection shows all of them.
123
+ - Include / exclude keyword rules filter further.
124
+ - An account that has never saved a selection gets the newest model of each family checked on its first successful probe (at most 12), computed from that server's own catalog; **Reset to Recommended** restores that set at any time.
125
+
126
+ ### Per-model overrides
127
+
128
+ **Edit Parameters** on a checked model sets its context window, max output, image input, thinking levels (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`) and request protocol, each resettable to the discovered value.
129
+
130
+ ### Multiple accounts
131
+
132
+ - Each account writes its own set of routes: the first account uses `cli-proxy` / `cli-proxy-responses` / `cli-proxy-messages`, later ones `cli-proxy-2*`, `cli-proxy-3*`, …; credential refs are `CLI_PROXY_API_KEY`, `CLI_PROXY_API_KEY_2`, …. The model picker groups models by account name.
133
+ - **Disabling** an account keeps its settings but removes its routes, so its models leave the picker; other accounts are unaffected.
134
+ - **New** accounts start disabled. Fill in the URL and key, click **Probe & Refresh** to preview and check models, then turn on **Enable This Account** and save.
135
+ - An account with a base URL **only connects to that URL** and reports an error when it is unreachable; it never silently falls back to local `:8317`, so two accounts cannot end up on the same server.
136
+ - Provider route IDs of different accounts must not overlap; conflicting changes are rejected.
137
+ - **Deleting** an account removes its routes but keeps its key in the credentials service.
138
+
139
+ ### Protocol routing
140
+
141
+ CPA serves every model on OpenAI Chat, OpenAI Responses and Anthropic Messages, translating when the entry protocol differs from the upstream one. The default auto mode sends each model over its upstream's own protocol:
142
+
143
+ | Model family (from `owned_by` and the model id) | Protocol | Route (for `cli-proxy`) |
144
+ |---|---|---|
145
+ | Claude (including `devin/claude-*`, Antigravity Claude) | Anthropic Messages `/v1/messages` | `cli-proxy-messages` |
146
+ | OpenAI / Codex / GPT, xAI Grok | OpenAI Responses `/v1/responses` | `cli-proxy-responses` |
147
+ | Gemini, DeepSeek, Kimi, GLM, SWE, gpt-oss, … | OpenAI Chat `/v1/chat/completions` | `cli-proxy` |
148
+
149
+ - DSH custom routes cannot speak Gemini's native `generateContent`, so Gemini uses OpenAI Chat.
150
+ - A DSH route has a single protocol, so models are split across the three routes; a route left without models is removed. When the default model moves to another route, `agent-default-model` follows it.
151
+ - Claude 4.6+ / 5.x / Fable use adaptive thinking (`effort`); older Claude models use a token budget.
152
+ - Switch to one protocol for every model, or set a protocol per model under **Edit Parameters**.
153
+ - Other fields you add to a managed route by hand (such as `retryPolicy`) are kept.
154
+
155
+ ## Agent tool and slash commands
156
+
157
+ ### The `cliproxyapi` tool
158
+
159
+ The DSH agent uses this tool to inspect and configure the plugin; just ask in plain language.
160
+
161
+ | `action` | Effect |
162
+ |---|---|
163
+ | `status` | Show every account (or only `account`) with its state and models |
164
+ | `refresh` | Probe and sync now; without `account`, all accounts |
165
+ | `configure` | Update one account (the first by default), then refresh it |
166
+ | `add_account` | Create an account; enabled when `baseURL` is given, otherwise disabled |
167
+ | `remove_account` | Delete the `account` and its routes |
168
+
169
+ Parameters (all optional except `action`):
170
+
171
+ | Parameter | Meaning |
172
+ |---|---|
173
+ | `account` | Account id (e.g. `default`, `account-2`), or its provider route ID or display name |
174
+ | `enabled` | Enable or disable the account |
175
+ | `baseURL` | CPA URL such as `http://127.0.0.1:8317`; an empty string means auto-discover |
176
+ | `apiKey` | Bearer key, stored under the account's `apiKeyEnv` ref |
177
+ | `apiKeyEnv` | Credential ref name (`[A-Za-z_][A-Za-z0-9_]*`) |
178
+ | `provider` | `llm-pi-ai` provider route ID, unique per account |
179
+ | `displayName` | Account name, also the group title in the model picker |
180
+ | `protocolMode` | `auto` (native protocol per family, default) or `fixed` |
181
+ | `protocol` | Protocol used in `fixed` mode: `openai-completions` / `openai-responses` / `anthropic-messages` |
182
+ | `selectedModels` | Model ids shown in the picker; `[]` shows all |
183
+ | `includePrefix` / `excludePrefix` | Comma-separated model id keywords |
184
+ | `modelOverrides` | `{ [modelId]: { contextWindow?, maxTokens?, image?, reasoningLevels?, protocol? } }`, replacing the whole map |
185
+
186
+ Examples:
187
+
188
+ ```json
189
+ { "action": "configure", "baseURL": "http://127.0.0.1:8317", "apiKey": "sk-...", "selectedModels": ["gpt-6.1-sol", "claude-opus-5-5"] }
190
+ { "action": "add_account", "displayName": "Backup CPA", "baseURL": "https://other-cpa:8317", "apiKey": "sk-...", "selectedModels": ["gpt-6-astra"] }
191
+ { "action": "configure", "account": "account-2", "enabled": false }
192
+ { "action": "remove_account", "account": "account-2" }
193
+ ```
194
+
195
+ The output has `accounts[]` (each with `id`, `displayName`, `provider`, `enabled`, `state`, `endpoint`, `modelCount`, `totalDiscovered`, `error`) and a text `summary`. `state` is one of `idle`, `probing`, `connected`, `disabled`, `error`.
196
+
197
+ ### Slash commands
198
+
199
+ - `/cpa-status` — show every account's status.
200
+ - `/cpa-refresh` — refresh every account now, including a catalog probe of disabled ones.
201
+
202
+ ### HTTP API
203
+
204
+ Used by the settings panel. Requires the DSH Web session's authentication; POST accepts only same-origin requests from loopback or trusted hosts.
205
+
206
+ | Method | Path | Body | Meaning |
207
+ |---|---|---|---|
208
+ | GET | `/api/dsh-cliproxyapi/status` | — | `{ ok, global, accounts[] }` |
209
+ | POST | `/api/dsh-cliproxyapi/refresh` | `{ accountId? }` | Refresh one or all accounts |
210
+ | POST | `/api/dsh-cliproxyapi/save` | `{ accountId?, …account fields, apiKey?, clearApiKey?, refreshIntervalSeconds?, probeTimeoutMs? }` | Save an account (the first by default); a body with only global fields saves just the globals |
211
+ | POST | `/api/dsh-cliproxyapi/accounts/add` | Optional account fields | Create a disabled account; returns `createdId` |
212
+ | POST | `/api/dsh-cliproxyapi/accounts/remove` | `{ accountId }` | Delete an account and its routes |
213
+
214
+ ## Storage and configuration
215
+
216
+ - **State file**: `<profile dir>/.dsh-cliproxyapi/state.json` holds accounts, selections and overrides (no keys).
217
+
218
+ ```json
219
+ {
220
+ "version": 2,
221
+ "refreshIntervalSeconds": 300,
222
+ "probeTimeoutMs": 5000,
223
+ "accounts": [
224
+ {
225
+ "id": "default", "enabled": true, "provider": "cli-proxy", "displayName": "CLI Proxy API",
226
+ "baseURL": "https://cpa.example.com", "apiKeyEnv": "CLI_PROXY_API_KEY",
227
+ "protocol": "openai-completions", "protocolMode": "auto",
228
+ "includePrefix": "", "excludePrefix": "", "selectedModels": ["gpt-6.1-sol"], "modelOverrides": {}
229
+ }
230
+ ]
231
+ }
232
+ ```
233
+
234
+ The file is re-read on every access; after a manual edit, click **Probe & Refresh**. A single-account file from 1.3.x and earlier migrates automatically into account `default` with the same routes, key and selection, and the original is kept as `state.v1.json`.
235
+
236
+ - **Keys**: stored and resolved by ref through the DSH `credentials` service, falling back to an environment variable of the same name.
237
+ - **Environment**: `CLIPROXYAPI_BASE_URL` is used only for auto-discovery of accounts without a base URL.
238
+ - **Plugin row config**: the plugin row's `config` in `cordis.patch.yml` is overlaid on the state file at startup: `accounts` replaces the account list, other fields apply to the first account. Normally keep it `{}` and configure through the panel or the tool.
239
+
240
+ ## Upgrading and uninstalling
241
+
242
+ - **Upgrade**: uninstall and reinstall on the **Plugins** page, or run `dsh plugin --profile <profile name> add dsh-cliproxyapi-pro@latest`. Accounts, selections and parameters live in the profile directory and keys in the credentials service, so reinstalling keeps them.
243
+ - **Uninstall**: uninstall on the **Plugins** page. The synchronized model routes are stored in DSH settings and are not removed with the plugin; to remove those models from the picker too, disable or delete every account before uninstalling.
244
+
245
+ ## FAQ
246
+
247
+ **No models in the model picker?**
248
+ Check that the account has **Enable This Account** on and at least one model checked (or an empty selection, meaning all). Run `/cpa-status` to see every account's state.
249
+
250
+ **"none of the selected models matched"?**
251
+ None of the checked models exists on this server (typical after switching servers). The panel still lists the server's models — check new ones, or click **Reset to Recommended**, then save.
252
+
253
+ **Connection failed / "no usable CPA service found"?**
254
+ Make sure the base URL is reachable from the machine running DSH and the API key is correct. An account with a URL never tries another address; the error lists every address tried and why it failed.
255
+
256
+ **A just-published version won't install?**
257
+ The pnpm used by DSH may enforce a waiting period for new releases (`minimumReleaseAge`); the install screen shows which version it actually installed. Try again later or name the version explicitly.
258
+
259
+ ## AI installation guide
260
+
261
+ > **For the AI agent in DeepSeek Harness**: when the user asks you to install or configure this plugin, follow these steps. The package has no npm dependencies and no build scripts.
262
+
263
+ 1. **Install**: call `plugin_manager` with `{"action": "install_bundle", "target": "dsh-cliproxyapi-pro", "enabled": true}`. Read `application` and `warnings` in the result; `restart-required` means DSH must restart before the new code runs.
264
+ 2. **Configure** with the `cliproxyapi` tool:
265
+ - Local CPA on `http://127.0.0.1:8317` without auth: nothing to configure; call `{"action": "refresh"}`.
266
+ - Remote URL or key: `{"action": "configure", "baseURL": "...", "apiKey": "..."}` (first account), or `{"action": "add_account", ...}` for another account. Pass `"account": "<id>"` to target a specific account.
267
+ - Narrow the picker with `selectedModels` (exact ids from the `status` output).
268
+ 3. **Verify**: `{"action": "status"}` shows `state: "connected"` and `modelCount > 0` for each enabled account. Tell the user the models are in the DSH model picker under the account's name, and that accounts are managed in **Sidebar → Plugins → CLIProxyAPI** or **Settings → Built-in plugins → CLIProxyAPI**.
269
+
270
+ Never echo API keys back to the user or write them into files.
271
+
272
+ ## Development
273
+
274
+ ```text
275
+ lib/index.js Host plugin (discovery, sync, multi-account controller, tool, commands, HTTP API)
276
+ lib/client.js Web settings panel (hand-written ModuleLoader module, no build)
277
+ locale/*.json Title and description shown by the plugin manager
278
+ cordis.patch.yml Bundle patch inserting the dsh-cliproxyapi-pro row
279
+ tests/ node:test unit and integration tests
280
+ .github/workflows/ CI (tests) and release (GitHub Release + npm trusted publishing)
281
+ assets/screenshots/ README screenshots (listed in screenshots.json for plugin storefronts)
282
+ AGENTS.md Conventions, architecture and invariants for coding agents
283
+ ```
284
+
285
+ ```bash
286
+ git clone https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro.git
287
+ cd dsh-cliproxyapi-pro
288
+ npm test # run the tests
289
+ npm run check # syntax check + tests
290
+ npm run pack:check # list the files a packed bundle contains
291
+ ```
292
+
293
+ Releasing is a pushed `v<version>` tag: GitHub Actions runs the tests, creates a GitHub Release with the package attached, and publishes to npm through npm trusted publishing (no token involved) with a provenance statement.
294
+
295
+ Read [AGENTS.md](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/blob/main/AGENTS.md) before changing code; see [CHANGELOG.md](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/blob/main/CHANGELOG.md) for history. Issues and pull requests are welcome — when you change the documentation, update both the Chinese and the English README.
296
+
297
+ ## License
298
+
299
+ [MIT](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/blob/main/LICENSE)
package/README.md CHANGED
@@ -1,132 +1,187 @@
1
- # dsh-cliproxyapi-pro (v1.4.0)
1
+ # dsh-cliproxyapi-pro
2
2
 
3
- English | [中文](README.zh.md)
3
+ 中文 | [English](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/blob/main/README.en.md)
4
4
 
5
+ [![npm](https://img.shields.io/npm/v/dsh-cliproxyapi-pro?label=npm)](https://www.npmjs.com/package/dsh-cliproxyapi-pro)
5
6
  [![CI](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/actions/workflows/ci.yml/badge.svg)](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/actions/workflows/ci.yml)
6
- [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
7
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/blob/main/LICENSE)
7
8
 
8
- A [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) provider for **DeepSeek Harness (DSH `>=0.2.0-rc.1`)**. It discovers CPA servers, synchronizes their model catalogs and capabilities (context window, image input, reasoning levels) into the DSH model picker, and supports **multiple accounts** that can each be enabled or disabled, with a visual model filter and per-model parameter overrides.
9
+ **把 [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)（CPA）里的模型，一键接进 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）的模型选择器。**
9
10
 
10
- - No runtime dependencies and no build step; only Node.js built-ins and DSH (Cordis) context services.
11
- - API keys are stored only in the DSH credentials service, never in configuration files.
11
+ 填好服务地址和 API Key，插件会自动读取 CPA 的模型目录，把你勾选的模型连同上下文长度、图片输入、推理档位一起同步到 DSH；每个模型自动走它最合适的协议。可以同时接入多个 CPA 账号，每个账号单独启用或停用。
12
12
 
13
- ## Contents
13
+ - **多账号**：每个账号独立的地址、密钥、模型勾选和参数，互不影响，可随时停用。
14
+ - **开箱即用**：首次连接时按该服务自己的模型目录，为每个模型家族勾选最新的一个（最多 12 个），模型选择器不会被上百个模型淹没。
15
+ - **原生协议**：Claude 走 Anthropic Messages，GPT / Codex / Grok 走 OpenAI Responses，其余走 OpenAI Chat，减少 CPA 的协议转换。
16
+ - **可视化管理**：设置面板里勾选模型、编辑单个模型的参数；也可以让 DSH 的 Agent 通过 `cliproxyapi` 工具帮你配置。
17
+ - **安全**：API Key 只保存在 DSH 凭证服务里，不写入任何配置文件。
18
+ - **零依赖**：不依赖任何 npm 包，无需构建，安装几秒完成。
14
19
 
15
- - [Features](#features)
16
- - [Screenshots](#screenshots)
17
- - [Installation](#installation)
18
- - [Usage](#usage)
19
- - [Settings panel](#settings-panel)
20
- - [Multiple accounts](#multiple-accounts)
21
- - [Agent tool `cliproxyapi`](#agent-tool-cliproxyapi)
22
- - [Slash commands](#slash-commands)
23
- - [HTTP API](#http-api)
24
- - [Protocol routing](#protocol-routing)
25
- - [Storage and configuration](#storage-and-configuration)
26
- - [AI installation protocol](#ai-installation-protocol)
27
- - [Development](#development)
28
- - [License](#license)
20
+ 适用于 DSH `0.2.0-rc.1` 及以上版本（含桌面版与 Web 版）。
29
21
 
30
- ## Features
22
+ ## 目录
31
23
 
32
- 1. **Auto-discovery.** Enter a remote or local URL (suffixes such as `/v1`, `/v1/chat/completions` and `/v1/messages` are stripped), or leave it empty to try the existing route URL, the `CLIPROXYAPI_BASE_URL` environment variable, and local `127.0.0.1:8317` in turn. The enriched catalog comes from `/v1/models?client_version=pi` (OpenAI `data[]` catalogs work too); `owned_by` from `/v1/models` identifies each model's family.
33
- 2. **Model filter.** Search, family chips, All / Checked / Unchecked tabs and bulk selection. **Only checked models appear in the conversation model picker.** An empty selection means no filter; include / exclude keyword rules apply on top. An account that has never saved a selection starts with the newest model of each family in its own server's catalog (at most 12); **Reset to Recommended** restores that set.
34
- 3. **Per-model overrides.** Context window, max output, image input, thinking levels (`off` … `max`) and request protocol, each resettable to the discovered value.
35
- 4. **Native protocol per model family** (default). See [Protocol routing](#protocol-routing).
36
- 5. **Multiple accounts.** Each account has its own URL, key, routes, protocol, selection and overrides, and can be enabled or disabled on its own. See [Multiple accounts](#multiple-accounts).
37
- 6. **Automatic refresh.** All accounts refresh on a shared interval (300 s by default); an unchanged catalog writes no settings.
24
+ - [安装](#安装)
25
+ - [快速上手](#快速上手)
26
+ - [截图](#截图)
27
+ - [功能详解](#功能详解)
28
+ - [Agent 工具与斜杠命令](#agent-工具与斜杠命令)
29
+ - [存储与配置](#存储与配置)
30
+ - [升级与卸载](#升级与卸载)
31
+ - [常见问题](#常见问题)
32
+ - [给 AI Agent 的安装指南](#给-ai-agent-的安装指南)
33
+ - [开发](#开发)
34
+ - [许可证](#许可证)
38
35
 
39
- ## Screenshots
36
+ ## 安装
40
37
 
41
- The panel lives in the **Settings → Built-in plugins → CLIProxyAPI** tab and follows the DSH display language; the screenshots show the Chinese UI.
38
+ 插件已发布到 npm：[`dsh-cliproxyapi-pro`](https://www.npmjs.com/package/dsh-cliproxyapi-pro)，中国大陆镜像（npmmirror）同步可用。任选一种方式安装即可。
42
39
 
43
- **1. Account bar and account status.** The bar at the top lists every account: a green dot means connected, a grey dot plus the **Off** badge means disabled. Here a second account, *CLI Proxy API 2*, was just added with **+ Add Account**: it starts disabled, gets its own provider route `cli-proxy-2`, and — since no base URL is set yet — the probe reports that no local CPA was found.
40
+ ### 方式一：在 DSH 插件页安装（推荐）
44
41
 
45
- ![Account bar with one connected and one newly added, disabled account](assets/screenshots/accounts.png)
42
+ 1. 打开 DSH，点击左侧栏的 **插件**。
43
+ 2. 点击页面顶部的 **添加插件**。
44
+ 3. 在输入框中填写包名：
46
45
 
47
- **2. Model picker filter.** All 168 models discovered from the CPA server, with All / Checked / Unchecked tabs, family chips (GPT, CLAUDE, GEMINI, GROK, …), search and bulk actions. Checked models are the only ones synchronized into the DSH model picker; each shows the protocol it will use (here OpenAI Responses), image input, reasoning levels and context window, and **Edit Parameters** opens its per-model overrides.
46
+ ```text
47
+ dsh-cliproxyapi-pro
48
+ ```
48
49
 
49
- ![Model filter with family chips, checked models, protocol and capability badges](assets/screenshots/model-filter.png)
50
+ 需要固定版本时可以写成 `dsh-cliproxyapi-pro@1.4.1`。
51
+ 4. 点击 **安装**，完成后点击 **立即启用**。
50
52
 
51
- **3. Connection & Authentication.** Per-account settings: the **Enable This Account** switch, base URL, API key stored under the account's own credential ref (`CLI_PROXY_API_KEY_2`), wire protocol, account name, the collapsible advanced section, **Save & Apply** and **Delete Account**.
53
+ > 在中国大陆下载慢，可以点输入框旁的 **安装源**，切换到 **中国大陆镜像源**。
52
54
 
53
- ![Connection settings of a disabled account with its own credential ref](assets/screenshots/connection.png)
55
+ ### 方式二：让 DSH 里的 Agent 帮你装
54
56
 
55
- ## Installation
57
+ 在 DSH 对话框里直接说：
56
58
 
57
- Ask the agent in a DSH conversation to install it with `plugin_manager`, using one of these targets:
59
+ ```text
60
+ 帮我安装 DSH 插件 dsh-cliproxyapi-pro
61
+ ```
58
62
 
59
- | Source | `target` |
60
- |---|---|
61
- | GitHub, latest `main` | `git+https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro.git#main` |
62
- | GitHub, a release tag | `git+https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro.git#v1.4.0` (see [Releases](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/releases)) |
63
- | GitHub Release `.tgz` | Download [`dsh-cliproxyapi-pro.tgz`](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/releases/latest/download/dsh-cliproxyapi-pro.tgz) (always the latest release) and pass its absolute path |
64
- | Local checkout (development, linked) | Absolute path of the cloned repository |
65
- | npm (once published) | `dsh-cliproxyapi-pro` |
63
+ Agent 会调用 `plugin_manager` 完成安装和启用（视权限设置，可能需要你批准）。装好后可以接着让它配置，例如「把 CLIProxyAPI 地址设为 http://127.0.0.1:8317，密钥是 sk-…」。
66
64
 
67
- ```json
68
- { "action": "install_bundle", "target": "<target from the table>", "enabled": true }
65
+ ### 方式三：命令行
66
+
67
+ ```bash
68
+ dsh plugin --profile <profile 名称> add dsh-cliproxyapi-pro
69
69
  ```
70
70
 
71
- - Installing a directory links it (`source: link:<dir>`); code changes go live when the plugin reloads.
72
- - Reinstalling over an older version is fine; replacing an installed package needs a DSH restart to load the new code.
73
- - If the result's `application` is `restart-required`, restart DSH.
71
+ 这条命令从 npm 下载插件，并把它加入该 profile 已启用的插件列表，一步完成。DSH 桌面版的 profile 通常叫 `desktop`；如果 DSH 正在运行，重启后生效。
74
72
 
75
- After installation, open:
73
+ ### 方式四：从 GitHub 安装（不经过 npm）
76
74
 
77
- - Sidebar → **Plugins** → **CLIProxyAPI**
78
- - **Settings** → **Built-in plugins** → **CLIProxyAPI** tab
75
+ 在插件页的 **添加插件** 中，或作为 `plugin_manager` 的 `target`，也可以填写：
79
76
 
80
- ## Usage
77
+ | 来源 | 填写内容 |
78
+ |---|---|
79
+ | 某个发布版本 | `git+https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro.git#v1.4.1` |
80
+ | 最新开发版 | `git+https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro.git#main` |
81
+ | 离线安装包 | 下载 [`dsh-cliproxyapi-pro.tgz`](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/releases/latest/download/dsh-cliproxyapi-pro.tgz)（始终是最新版），填写它的本地绝对路径 |
82
+ | 本地源码（开发用） | 克隆后的仓库目录绝对路径；以链接方式安装，改代码后重载插件即生效 |
81
83
 
82
- ### Settings panel
84
+ 所有版本见 [Releases](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/releases)。
83
85
 
84
- The **account bar** at the top switches between accounts (the dot shows each account's state; disabled accounts carry an **Off** badge), and **+ Add Account** creates one. Below it, for the selected account:
86
+ ## 快速上手
85
87
 
86
- | Section | Contents |
87
- |---|---|
88
- | Status card | Connection state, active endpoint, models in the picker / discovered; **Probe & Refresh**, **Save & Apply** |
89
- | Model Picker Filter | Check models and edit per-model parameters; click **Apply Selected Models** to save |
90
- | Connection & Authentication | **Enable This Account** switch, base URL, API key (clearable), wire protocol, account name |
91
- | Advanced Routing & Keyword Rules | Include / exclude keywords, provider route ID, credential ref, refresh interval (shared by all accounts); **Delete Account** |
88
+ 1. **打开设置面板**：左侧栏 **插件** → **CLIProxyAPI**，或 **设置** → **内置插件** → **CLIProxyAPI** 标签页。
89
+ 2. **填写连接信息**：在「连接与认证配置」里填 **CLIProxyAPI 服务地址**（如 `http://127.0.0.1:8317`，不用加 `/v1`）和 **API Key**（本地免密的 CPA 可留空），点 **保存设置并应用**。
90
+ 3. **选择模型**：连接成功后，「模型显示筛选」会列出 CPA 上的全部模型，并已为每个家族勾好最新的一个。按需增减后点 **保存模型勾选**。
91
+ 4. **开始使用**：回到对话框，打开模型选择器，就能在以账号名称命名的分组里看到这些模型。
92
+
93
+ CPA 就在本机默认端口 `8317` 且没有设置密钥时，什么都不用填，插件会自动发现它。
94
+
95
+ ## 截图
96
+
97
+ **1. 账号栏与账号状态。** 顶部账号栏列出所有账号：绿点表示已连接，灰点加「未启用」标记表示已停用。图中刚用「+ 添加账号」新增了第二个账号「CLI Proxy API 2」：它默认停用，拥有独立的路由 `cli-proxy-2`；由于还没填写服务地址，探测提示本地没有找到 CPA 服务。
98
+
99
+ ![账号栏：一个已连接账号和一个刚添加、未启用的账号](https://raw.githubusercontent.com/TinyBOOOOM/dsh-cliproxyapi-pro/main/assets/screenshots/accounts.png)
100
+
101
+ **2. 模型显示筛选。** 从 CPA 服务发现的全部 168 个模型，支持全部发现 / 已勾选 / 未勾选切换、家族标签（GPT、CLAUDE、GEMINI、GROK……）、搜索与批量操作。只有勾选的模型会同步到 DSH 模型选择器；每个模型显示将使用的协议（图中为 OpenAI Responses）、图片输入、推理档位与上下文长度，「编辑参数」可打开单模型参数覆盖。
102
+
103
+ ![模型筛选：家族标签、已勾选模型、协议与能力标记](https://raw.githubusercontent.com/TinyBOOOOM/dsh-cliproxyapi-pro/main/assets/screenshots/model-filter.png)
104
+
105
+ **3. 连接与认证配置。** 每个账号独立的设置：「启用此账号」开关、服务地址、保存在该账号独立引用名（`CLI_PROXY_API_KEY_2`）下的 API Key、接口协议、账号名称、可折叠的高级设置，以及「保存设置并应用」与「删除此账号」。
106
+
107
+ ![未启用账号的连接设置，使用独立的密钥引用名](https://raw.githubusercontent.com/TinyBOOOOM/dsh-cliproxyapi-pro/main/assets/screenshots/connection.png)
108
+
109
+ ## 功能详解
110
+
111
+ ### 自动发现与同步
112
+
113
+ - 服务地址可以是本地或远程，`/v1`、`/v1/chat/completions`、`/v1/messages` 等后缀会自动去掉。
114
+ - 地址留空时，依次尝试：已有路由的地址、环境变量 `CLIPROXYAPI_BASE_URL`、本机 `127.0.0.1:8317`。
115
+ - 读取 `/v1/models?client_version=pi` 的富元数据目录（也兼容标准 OpenAI `data[]` 格式），并用 `/v1/models` 的 `owned_by` 判断模型家族。
116
+ - 所有账号按统一间隔自动刷新（默认 300 秒）；模型目录没有变化时不写入任何设置。
117
+
118
+ ### 模型勾选
119
+
120
+ - 搜索、家族标签、全部 / 已勾选 / 未勾选切换、批量勾选。**只有勾选的模型会出现在模型选择器中**；勾选为空表示全部显示。
121
+ - 还可以用「包含 / 排除关键词」规则进一步过滤。
122
+ - 从未保存过勾选的账号，首次探测成功后自动为每个模型家族勾选最新的一个（最多 12 个），按该服务自己的模型目录计算；**恢复推荐精选** 可随时恢复这组勾选。
123
+
124
+ ### 单模型参数覆盖
92
125
 
93
- ### Multiple accounts
126
+ 已勾选模型的 **编辑参数** 可以单独设置：上下文窗口、最大输出、图片输入、思考等级（`off`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`）和请求协议，也可一键恢复自动探测值。
94
127
 
95
- - Each account writes its own set of `llm-pi-ai` routes: the first account uses `cli-proxy` / `cli-proxy-responses` / `cli-proxy-messages`, later ones `cli-proxy-2*`, `cli-proxy-3*`, …; credential refs are `CLI_PROXY_API_KEY`, `CLI_PROXY_API_KEY_2`, …. The model picker groups models by account name.
96
- - **Provider route IDs must not overlap** (for example, another account cannot use `cli-proxy-messages`); saving such a change is rejected.
97
- - **Disabling** an account keeps its settings but removes its routes, so its models leave the picker; other accounts are unaffected.
98
- - **New** accounts start disabled. Fill in the URL and key, click **Probe & Refresh** to preview and check models, then turn on **Enable This Account** and save.
99
- - An account with a base URL **only probes that URL** and reports an error when it is unreachable; it never falls back to local `:8317`, so two accounts cannot silently point at the same server.
100
- - **Deleting** an account removes its routes but keeps its key in the credentials service.
128
+ ### 多账号
101
129
 
102
- ### Agent tool `cliproxyapi`
130
+ - 每个账号写入自己的一组路由：第一个账号为 `cli-proxy` / `cli-proxy-responses` / `cli-proxy-messages`，之后依次为 `cli-proxy-2*`、`cli-proxy-3*`……；密钥引用名依次为 `CLI_PROXY_API_KEY`、`CLI_PROXY_API_KEY_2`……。模型选择器按账号名称分组。
131
+ - **停用**账号：保留全部配置，但移除它的路由，模型从选择器中消失；其他账号不受影响。
132
+ - **新增**账号默认停用。可先填好地址和密钥，点「立即探测刷新」预览模型并勾选，再打开「启用此账号」保存。
133
+ - 填写了服务地址的账号**只连接该地址**，连不上就报错，不会悄悄改连本地 `:8317`，避免两个账号指向同一个服务。
134
+ - 不同账号的路由 ID 不能重叠，冲突的修改会被拒绝。
135
+ - **删除**账号会移除它的路由，但保留凭证服务里的密钥。
103
136
 
104
- | `action` | Effect |
137
+ ### 协议路由
138
+
139
+ CPA 对每个模型同时提供 OpenAI Chat、OpenAI Responses、Anthropic Messages 三种入口，入口协议和上游不一致时需要转换。默认的自动模式让每个模型直接使用上游协议：
140
+
141
+ | 模型家族（依据 `owned_by` 与模型 id） | 协议 | 路由（以 `cli-proxy` 为例） |
142
+ |---|---|---|
143
+ | Claude（含 `devin/claude-*`、Antigravity Claude） | Anthropic Messages `/v1/messages` | `cli-proxy-messages` |
144
+ | OpenAI / Codex / GPT、xAI Grok | OpenAI Responses `/v1/responses` | `cli-proxy-responses` |
145
+ | Gemini、DeepSeek、Kimi、GLM、SWE、gpt-oss 等 | OpenAI Chat `/v1/chat/completions` | `cli-proxy` |
146
+
147
+ - DSH 自定义路由不支持 Gemini 原生 `generateContent`，所以 Gemini 走 OpenAI Chat。
148
+ - DSH 每条路由只能有一种协议，模型按协议分到三条路由；没有模型的路由会自动移除。默认模型因此换了路由时，`agent-default-model` 会自动跟随。
149
+ - Claude 4.6+ / 5.x / Fable 使用自适应思考（`effort`），更早的 Claude 使用 token 预算。
150
+ - 可以改为「统一使用」某一种协议，或在单个模型的「编辑参数」里指定。
151
+ - 你在路由上手动加的其他字段（如 `retryPolicy`）会被保留。
152
+
153
+ ## Agent 工具与斜杠命令
154
+
155
+ ### `cliproxyapi` 工具
156
+
157
+ DSH 的 Agent 可以用这个工具查看和配置插件，你只需用自然语言提要求。
158
+
159
+ | `action` | 作用 |
105
160
  |---|---|
106
- | `status` | Show every account (or only `account`) with its state and models |
107
- | `refresh` | Probe and sync now; without `account`, all accounts |
108
- | `configure` | Update one account (the first by default), then refresh it |
109
- | `add_account` | Create an account; enabled when `baseURL` is given, otherwise disabled |
110
- | `remove_account` | Delete `account` and its routes |
161
+ | `status` | 查看所有账号（或 `account` 指定的账号）的状态与模型 |
162
+ | `refresh` | 立即探测并同步；不带 `account` 时刷新全部账号 |
163
+ | `configure` | 修改一个账号（默认第一个），保存后立即刷新 |
164
+ | `add_account` | 新增账号；给了 `baseURL` 时默认启用，否则停用 |
165
+ | `remove_account` | 删除 `account` 指定的账号及其路由 |
111
166
 
112
- Parameters (all optional except `action`):
167
+ 参数（除 `action` 外都可选）：
113
168
 
114
- | Parameter | Meaning |
169
+ | 参数 | 说明 |
115
170
  |---|---|
116
- | `account` | Account id (e.g. `default`, `account-2`), or its provider route ID or display name |
117
- | `enabled` | Enable or disable the account |
118
- | `baseURL` | CPA URL such as `http://127.0.0.1:8317`; an empty string means auto-discover |
119
- | `apiKey` | Bearer key, stored under the account's `apiKeyEnv` ref |
120
- | `apiKeyEnv` | Credential ref name (`[A-Za-z_][A-Za-z0-9_]*`) |
121
- | `provider` | `llm-pi-ai` provider route ID, unique per account |
122
- | `displayName` | Account name / model picker group title |
123
- | `protocolMode` | `auto` (native protocol per family, default) or `fixed` |
124
- | `protocol` | Protocol used in `fixed` mode: `openai-completions` / `openai-responses` / `anthropic-messages` |
125
- | `selectedModels` | Model ids shown in the picker; `[]` shows all |
126
- | `includePrefix` / `excludePrefix` | Comma-separated model id keywords |
127
- | `modelOverrides` | `{ [modelId]: { contextWindow?, maxTokens?, image?, reasoningLevels?, protocol? } }`, replacing the whole map |
128
-
129
- Examples:
171
+ | `account` | 账号 id（如 `default`、`account-2`），也可用路由 ID 或账号名称 |
172
+ | `enabled` | 启用 / 停用该账号 |
173
+ | `baseURL` | CPA 地址，如 `http://127.0.0.1:8317`；空字符串表示自动发现 |
174
+ | `apiKey` | Bearer 密钥，保存到该账号的 `apiKeyEnv` 引用名下 |
175
+ | `apiKeyEnv` | 密钥引用名（`[A-Za-z_][A-Za-z0-9_]*`） |
176
+ | `provider` | `llm-pi-ai` 路由 ID，每个账号唯一 |
177
+ | `displayName` | 账号名称，也是模型选择器中的分组名 |
178
+ | `protocolMode` | `auto`（按家族走原生协议，默认）或 `fixed` |
179
+ | `protocol` | `fixed` 时使用的协议：`openai-completions` / `openai-responses` / `anthropic-messages` |
180
+ | `selectedModels` | 显示在选择器中的模型 id 列表；`[]` 表示全部 |
181
+ | `includePrefix` / `excludePrefix` | 逗号分隔的模型 id 关键词 |
182
+ | `modelOverrides` | `{ [modelId]: { contextWindow?, maxTokens?, image?, reasoningLevels?, protocol? } }`，整体替换 |
183
+
184
+ 示例：
130
185
 
131
186
  ```json
132
187
  { "action": "configure", "baseURL": "http://127.0.0.1:8317", "apiKey": "sk-...", "selectedModels": ["gpt-6.1-sol", "claude-opus-5-5"] }
@@ -135,44 +190,28 @@ Examples:
135
190
  { "action": "remove_account", "account": "account-2" }
136
191
  ```
137
192
 
138
- The output has `accounts[]` (each with `id`, `displayName`, `provider`, `enabled`, `state`, `endpoint`, `modelCount`, `totalDiscovered`, `error`) and a text `summary`. `state` is one of `idle`, `probing`, `connected`, `disabled`, `error`.
193
+ 输出包含 `accounts[]`（每个账号的 `id`、`displayName`、`provider`、`enabled`、`state`、`endpoint`、`modelCount`、`totalDiscovered`、`error`）和文字摘要 `summary`。`state` 取值：`idle`、`probing`、`connected`、`disabled`、`error`。
139
194
 
140
- ### Slash commands
195
+ ### 斜杠命令
141
196
 
142
- - `/cpa-status` — show every account's status.
143
- - `/cpa-refresh` — refresh every account now, including a catalog probe of disabled ones.
197
+ - `/cpa-status`：显示所有账号的状态。
198
+ - `/cpa-refresh`：立即刷新所有账号（也会探测停用账号的模型列表）。
144
199
 
145
- ### HTTP API
200
+ ### HTTP 接口
146
201
 
147
- Used by the settings panel. Requires the DSH Web session's authentication; POST accepts only same-origin requests from loopback or trusted hosts.
202
+ 供设置面板使用，需要 DSH Web 会话的认证；POST 只接受来自本机或受信任主机的同源请求。
148
203
 
149
- | Method | Path | Body | Meaning |
204
+ | 方法 | 路径 | 请求体 | 说明 |
150
205
  |---|---|---|---|
151
206
  | GET | `/api/dsh-cliproxyapi/status` | — | `{ ok, global, accounts[] }` |
152
- | POST | `/api/dsh-cliproxyapi/refresh` | `{ accountId? }` | Refresh one or all accounts |
153
- | POST | `/api/dsh-cliproxyapi/save` | `{ accountId?, …account fields, apiKey?, clearApiKey?, refreshIntervalSeconds?, probeTimeoutMs? }` | Save an account (the first by default); a body with only global fields saves just the globals |
154
- | POST | `/api/dsh-cliproxyapi/accounts/add` | Optional account fields | Create a disabled account; returns `createdId` |
155
- | POST | `/api/dsh-cliproxyapi/accounts/remove` | `{ accountId }` | Delete an account and its routes |
156
-
157
- ## Protocol routing
207
+ | POST | `/api/dsh-cliproxyapi/refresh` | `{ accountId? }` | 刷新一个或全部账号 |
208
+ | POST | `/api/dsh-cliproxyapi/save` | `{ accountId?, …账号字段, apiKey?, clearApiKey?, refreshIntervalSeconds?, probeTimeoutMs? }` | 保存账号（缺省为第一个）；只有全局字段时只保存全局设置 |
209
+ | POST | `/api/dsh-cliproxyapi/accounts/add` | 账号字段（可选） | 新增账号，默认停用；返回 `createdId` |
210
+ | POST | `/api/dsh-cliproxyapi/accounts/remove` | `{ accountId }` | 删除账号及其路由 |
158
211
 
159
- CLIProxyAPI serves every model on OpenAI Chat, OpenAI Responses and Anthropic Messages, translating when the entry protocol differs from the upstream one. Auto mode (`protocolMode: "auto"`) sends each model over its upstream's own protocol:
160
-
161
- | Model family (from `owned_by` and the model id) | Protocol | Route (for `cli-proxy`) |
162
- |---|---|---|
163
- | Claude (including `devin/claude-*`, Antigravity Claude) | Anthropic Messages `/v1/messages` | `cli-proxy-messages` |
164
- | OpenAI / Codex / GPT, xAI Grok | OpenAI Responses `/v1/responses` | `cli-proxy-responses` |
165
- | Gemini, DeepSeek, Kimi, GLM, SWE, gpt-oss, … | OpenAI Chat `/v1/chat/completions` | `cli-proxy` |
212
+ ## 存储与配置
166
213
 
167
- - DSH custom routes cannot speak Gemini's native `generateContent`, so Gemini uses OpenAI Chat.
168
- - A DSH route has a single protocol, so models are split across the three routes; a route left without models is removed. When the default model moves to another route, `agent-default-model` follows it.
169
- - Claude 4.6+ / 5.x / Fable use adaptive thinking (`effort`); older Claude models use a token budget.
170
- - Switch to one protocol for every model (`fixed`), or set a protocol per model under **Edit Parameters**.
171
- - Other fields you add to a managed route by hand (such as `retryPolicy`) are kept.
172
-
173
- ## Storage and configuration
174
-
175
- - **State file**: `<profile dir>/.dsh-cliproxyapi/state.json`
214
+ - **状态文件**：`<Profile 目录>/.dsh-cliproxyapi/state.json`，保存账号、勾选和参数覆盖（不含密钥）。
176
215
 
177
216
  ```json
178
217
  {
@@ -190,48 +229,69 @@ CLIProxyAPI serves every model on OpenAI Chat, OpenAI Responses and Anthropic Me
190
229
  }
191
230
  ```
192
231
 
193
- The file is re-read on every access; after a manual edit, click **Probe & Refresh**. A v1 single-account file migrates automatically into account `default` (same routes, key and selection), and the original is kept as `state.v1.json`.
232
+ 文件每次读取都会重新加载，手动修改后点「立即探测刷新」即可生效。旧版（1.3.x 及以前）的单账号文件会自动迁移为 id 为 `default` 的账号，路由、密钥和勾选保持不变，原文件备份为 `state.v1.json`。
233
+
234
+ - **密钥**：通过 DSH 的 `credentials` 服务按引用名存取；凭证服务里没有时，回退读取同名环境变量。
235
+ - **环境变量**：`CLIPROXYAPI_BASE_URL` 只用于服务地址留空的账号的自动发现。
236
+ - **插件行配置**：`cordis.patch.yml` 中本插件行的 `config` 会在启动时叠加到状态文件上：包含 `accounts` 时替换账号列表，否则其中的字段作用于第一个账号。一般保持 `{}`，用面板或工具配置即可。
237
+
238
+ ## 升级与卸载
239
+
240
+ - **升级**：在 **插件** 页卸载后重新安装即可；命令行可以运行 `dsh plugin --profile <profile 名称> add dsh-cliproxyapi-pro@latest`。账号、勾选和参数保存在 profile 目录里，密钥保存在凭证服务里，重装不会丢失。
241
+ - **卸载**：在 **插件** 页卸载。已同步的模型路由保存在 DSH 设置里，卸载插件不会自动删除它们；想让这些模型一并从选择器消失，请在卸载前把各账号停用或删除。
194
242
 
195
- - **Keys**: stored and resolved by ref through the DSH `credentials` service, falling back to an environment variable of the same name. A local CPA without authentication needs no key.
196
- - **Environment**: `CLIPROXYAPI_BASE_URL` is used only for auto-discovery of accounts without a base URL.
197
- - **Bundle row config**: the plugin row's `config` in `cordis.patch.yml` is overlaid on the state file at startup: `accounts` replaces the account list, flat fields apply to the first account. Normally keep it `{}` and configure through the panel or the tool.
243
+ ## 常见问题
198
244
 
199
- ## AI installation protocol
245
+ **模型选择器里看不到模型？**
246
+ 确认账号已打开「启用此账号」，并且至少勾选了一个模型（或勾选为空，表示全部）。可以运行 `/cpa-status` 查看每个账号的状态。
200
247
 
201
- > **For the AI agent in DeepSeek Harness**: when the user asks you to install or configure this plugin, follow these steps. The package has no npm dependencies and no build scripts.
248
+ **提示「none of the selected models matched」？**
249
+ 已勾选的模型在这台服务器上都不存在（常见于换了服务器）。面板里仍会列出该服务器的模型，重新勾选，或点「恢复推荐精选」后保存。
202
250
 
203
- 1. **Install**: call `plugin_manager` with `{"action": "install_bundle", "target": "<see Installation>", "enabled": true}`. Read `application` and `warnings` in the result; `restart-required` means DSH must restart before the new code runs.
204
- 2. **Configure** with the `cliproxyapi` tool:
205
- - Local CPA on `http://127.0.0.1:8317` without auth: nothing to configure; call `{"action": "refresh"}`.
206
- - Remote URL or key: `{"action": "configure", "baseURL": "...", "apiKey": "..."}` (first account), or `{"action": "add_account", ...}` for another account. Pass `"account": "<id>"` to target a specific account.
207
- - Narrow the picker with `selectedModels` (exact ids from the `status` output).
208
- 3. **Verify**: `{"action": "status"}` shows `state: "connected"` and `modelCount > 0` for each enabled account. Tell the user the models are in the DSH model picker under the account's name, and that accounts are managed in **Sidebar → Plugins → CLIProxyAPI** or **Settings → Built-in plugins → CLIProxyAPI**.
251
+ **连接失败 / no usable CPA service found？**
252
+ 检查服务地址是否能从运行 DSH 的机器访问、API Key 是否正确。填写了地址的账号不会改连其他地址，报错里会列出尝试过的地址和原因。
209
253
 
210
- Never echo API keys back to the user or write them into files.
254
+ **刚发布的新版本装不上？**
255
+ DSH 使用的 pnpm 可能设置了新版本发布后的等待期（`minimumReleaseAge`），安装界面会说明实际装到的版本。稍后再装，或明确写出版本号。
211
256
 
212
- ## Development
257
+ ## 给 AI Agent 的安装指南
258
+
259
+ > 给 DeepSeek Harness 中的 AI Agent：用户要求安装或配置本插件时按以下步骤执行。本包没有 npm 依赖，也没有构建脚本。
260
+
261
+ 1. **安装**：调用 `plugin_manager`：`{"action": "install_bundle", "target": "dsh-cliproxyapi-pro", "enabled": true}`。查看结果中的 `application` 与 `warnings`；`restart-required` 表示需要重启 DSH 后新代码才会运行。
262
+ 2. **配置**：使用 `cliproxyapi` 工具。
263
+ - CPA 在本机 `http://127.0.0.1:8317` 且无鉴权：无需配置，调用 `{"action": "refresh"}`。
264
+ - 远程地址或有密钥：`{"action": "configure", "baseURL": "...", "apiKey": "..."}`（作用于第一个账号）；额外的账号用 `{"action": "add_account", ...}`；指定账号时传 `"account": "<id>"`。
265
+ - 用 `selectedModels`（取自 `status` 输出中的精确 id）精简模型选择器。
266
+ 3. **验证**：`{"action": "status"}` 中每个启用的账号 `state` 为 `connected` 且 `modelCount > 0`。告诉用户模型已出现在 DSH 模型选择器中（按账号名称分组），可在 **左侧栏 → 插件 → CLIProxyAPI** 或 **设置 → 内置插件 → CLIProxyAPI** 管理账号。
267
+
268
+ 不要把 API Key 回显给用户，也不要写入任何文件。
269
+
270
+ ## 开发
213
271
 
214
272
  ```text
215
- lib/index.js Host plugin (discovery, sync, multi-account controller, tool, commands, HTTP API)
216
- lib/client.js Web settings panel (hand-written ModuleLoader module, no build)
217
- locale/*.json Title and description shown by the plugin manager
218
- cordis.patch.yml Bundle patch inserting the dsh-cliproxyapi-pro row
219
- tests/ node:test unit and integration tests
220
- .github/workflows/ CI (tests) and release (.tgz asset, optional npm publish)
221
- assets/screenshots/ README screenshots (listed in screenshots.json for plugin storefronts)
222
- AGENTS.md Conventions, architecture and invariants for coding agents
273
+ lib/index.js Host 插件（发现、同步、多账号控制器、工具、命令、HTTP 接口）
274
+ lib/client.js Web 设置面板（ModuleLoader 格式，手写，无需构建）
275
+ locale/*.json 插件管理器中显示的标题与描述
276
+ cordis.patch.yml Bundle patch，插入 dsh-cliproxyapi-pro 行
277
+ tests/ node:test 单元与集成测试
278
+ .github/workflows/ CI（测试）与发版（GitHub Release + npm 受信任发布）
279
+ assets/screenshots/ README 截图（同时登记在 screenshots.json 中供插件市场展示）
280
+ AGENTS.md 给编码 Agent 的开发约定、架构与不变量
223
281
  ```
224
282
 
225
283
  ```bash
226
284
  git clone https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro.git
227
285
  cd dsh-cliproxyapi-pro
228
- npm test # run the tests
229
- npm run check # syntax check + tests
230
- npm run pack:check # list the files a packed bundle contains
286
+ npm test # 运行测试
287
+ npm run check # 语法检查 + 测试
288
+ npm run pack:check # 查看打包文件列表
231
289
  ```
232
290
 
233
- Read [AGENTS.md](AGENTS.md) before changing code; see [CHANGELOG.md](CHANGELOG.md) for history. Issues and pull requests are welcome — when you change the documentation, update both the English and the Chinese README.
291
+ 发版只需推送 `v<版本号>` 标签：GitHub Actions 会运行测试、创建 GitHub Release 并附上安装包，再通过 npm 受信任发布（不使用任何 token）上传到 npm，并附带来源证明。
292
+
293
+ 修改代码前请阅读 [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，修改说明文档时请同时更新中英文两份。
234
294
 
235
- ## License
295
+ ## 许可证
236
296
 
237
- [MIT](LICENSE)
297
+ [MIT](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/blob/main/LICENSE)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-cliproxyapi-pro",
3
- "version": "1.4.0",
3
+ "version": "1.4.1",
4
4
  "description": "Auto-discovery CLIProxyAPI provider and management UI for DeepSeek Harness — multiple accounts, dynamic model sync, capability detection, and visual settings.",
5
5
  "keywords": [
6
6
  "dsh",
@@ -41,7 +41,7 @@
41
41
  "cordis.patch.yml",
42
42
  "icon.svg",
43
43
  "README.md",
44
- "README.zh.md",
44
+ "README.en.md",
45
45
  "CHANGELOG.md",
46
46
  "LICENSE"
47
47
  ],
package/README.zh.md DELETED
@@ -1,237 +0,0 @@
1
- # dsh-cliproxyapi-pro (v1.4.0)
2
-
3
- [English](README.md) | 中文
4
-
5
- [![CI](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/actions/workflows/ci.yml/badge.svg)](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/actions/workflows/ci.yml)
6
- [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
7
-
8
- [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) 接入插件，适用于 **DeepSeek Harness（DSH `>=0.2.0-rc.1`）**：自动发现 CPA 服务、同步模型目录与能力（上下文、视觉、推理档位）到 DSH 模型选择器，支持**多个账号**分别启用/停用、可视化勾选模型与单模型参数覆盖。
9
-
10
- - 零运行时依赖，无需构建；仅使用 Node.js 内置模块与 DSH（Cordis）上下文服务。
11
- - 密钥只存放在 DSH 凭证服务中，不会写入配置文件。
12
-
13
- ## 目录
14
-
15
- - [功能](#功能)
16
- - [截图](#截图)
17
- - [安装](#安装)
18
- - [使用](#使用)
19
- - [设置面板](#设置面板)
20
- - [多账号](#多账号)
21
- - [Agent 工具 `cliproxyapi`](#agent-工具-cliproxyapi)
22
- - [斜杠命令](#斜杠命令)
23
- - [HTTP 接口](#http-接口)
24
- - [协议路由](#协议路由)
25
- - [存储与配置](#存储与配置)
26
- - [AI Agent 安装与配置指南](#ai-agent-安装与配置指南)
27
- - [开发](#开发)
28
- - [许可证](#许可证)
29
-
30
- ## 功能
31
-
32
- 1. **自动发现**：可填写远程/本地地址（自动剥离 `/v1`、`/v1/chat/completions`、`/v1/messages` 等后缀），留空则依次尝试已有路由地址、环境变量 `CLIPROXYAPI_BASE_URL` 与本地 `127.0.0.1:8317`。读取 `/v1/models?client_version=pi` 富元数据目录（兼容 OpenAI `data[]` 格式），并用 `/v1/models` 的 `owned_by` 判断模型家族。
33
- 2. **模型勾选筛选**：搜索、家族标签、全部/已勾选/未勾选切换、批量勾选；**只有勾选的模型会出现在对话框模型选择器中**。勾选为空表示不过滤；另可用包含/排除关键词规则。从未保存过勾选的账号，首次探测成功后会按该服务自己的模型目录，为每个模型家族勾选最新的一个（最多 12 个）；「恢复推荐精选」可恢复这组勾选。
34
- 3. **单模型参数覆盖**：上下文窗口、最大输出、图片输入、思考等级（`off`…`max`）、请求协议，可一键恢复自动探测值。
35
- 4. **按模型家族走原生协议**（默认）：见[协议路由](#协议路由)。
36
- 5. **多账号**：每个账号独立的服务地址、密钥、路由、协议、勾选与覆盖，可单独启用/停用。见[多账号](#多账号)。
37
- 6. **自动刷新**：所有账号按统一间隔（默认 300 秒）刷新；数据无变化时不写入任何设置。
38
-
39
- ## 截图
40
-
41
- 面板位于 **设置 → 内置插件 → CLIProxyAPI** 标签页，界面语言跟随 DSH 设置。
42
-
43
- **1. 账号栏与账号状态。** 顶部账号栏列出所有账号：绿点表示已连接，灰点加「未启用」标记表示已停用。图中刚用「+ 添加账号」新增了第二个账号「CLI Proxy API 2」：它默认停用，拥有独立的路由 `cli-proxy-2`；由于还没填写服务地址，探测提示本地没有找到 CPA 服务。
44
-
45
- ![账号栏：一个已连接账号和一个刚添加、未启用的账号](assets/screenshots/accounts.png)
46
-
47
- **2. 模型显示筛选。** 从 CPA 服务发现的全部 168 个模型，支持全部发现 / 已勾选 / 未勾选切换、家族标签（GPT、CLAUDE、GEMINI、GROK……）、搜索与批量操作。只有勾选的模型会同步到 DSH 模型选择器；每个模型显示将使用的协议（图中为 OpenAI Responses）、图片输入、推理档位与上下文长度，「编辑参数」可打开单模型参数覆盖。
48
-
49
- ![模型筛选：家族标签、已勾选模型、协议与能力标记](assets/screenshots/model-filter.png)
50
-
51
- **3. 连接与认证配置。** 每个账号独立的设置：「启用此账号」开关、服务地址、保存在该账号独立引用名（`CLI_PROXY_API_KEY_2`）下的 API Key、接口协议、账号名称、可折叠的高级设置，以及「保存设置并应用」与「删除此账号」。
52
-
53
- ![未启用账号的连接设置，使用独立的密钥引用名](assets/screenshots/connection.png)
54
-
55
- ## 安装
56
-
57
- 在 DSH 对话中让 Agent 调用 `plugin_manager` 安装，`target` 任选其一：
58
-
59
- | 来源 | `target` |
60
- |---|---|
61
- | GitHub 最新 `main` | `git+https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro.git#main` |
62
- | GitHub 某个版本标签 | `git+https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro.git#v1.4.0`（见 [Releases](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/releases)） |
63
- | GitHub Release 的 `.tgz` | 下载 [`dsh-cliproxyapi-pro.tgz`](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/releases/latest/download/dsh-cliproxyapi-pro.tgz)（始终是最新版本），填写它的绝对路径 |
64
- | 本地目录（开发用，链接安装） | 克隆后的仓库目录绝对路径 |
65
- | npm（发布后） | `dsh-cliproxyapi-pro` |
66
-
67
- ```json
68
- { "action": "install_bundle", "target": "<上表中的 target>", "enabled": true }
69
- ```
70
-
71
- - 安装目录时为链接安装（`source: link:<目录>`），修改代码后重载插件即生效。
72
- - 已安装旧版本时可直接重新安装；替换已安装的包后需要重启 DSH 才能加载新代码。
73
- - 安装结果中的 `application` 为 `restart-required` 时需重启 DSH。
74
-
75
- 安装后入口：
76
-
77
- - 左侧栏 → **插件** → **CLIProxyAPI**
78
- - **设置** → **内置插件** → **CLIProxyAPI** 标签页
79
-
80
- ## 使用
81
-
82
- ### 设置面板
83
-
84
- 面板顶部是**账号栏**：点击切换账号（圆点表示状态，未启用的账号带「未启用」标记），「+ 添加账号」新增账号。下方针对当前账号：
85
-
86
- | 区块 | 内容 |
87
- |---|---|
88
- | 状态卡片 | 连接状态、当前节点、选择器中的模型数 / 发现总数；「立即探测刷新」「保存设置并应用」 |
89
- | 模型显示筛选 | 勾选模型、编辑单模型参数；修改后点「保存模型勾选」 |
90
- | 连接与认证 | 「启用此账号」开关、服务地址、API Key（可清除）、接口协议、账号名称 |
91
- | 高级路由与规则过滤 | 包含/排除关键词、路由 ID、密钥引用名、自动刷新间隔（所有账号共用）；「删除此账号」 |
92
-
93
- ### 多账号
94
-
95
- - 每个账号写入自己的一组 `llm-pi-ai` 路由：首个账号为 `cli-proxy` / `cli-proxy-responses` / `cli-proxy-messages`，新增账号依次为 `cli-proxy-2*`、`cli-proxy-3*`……；密钥引用名依次为 `CLI_PROXY_API_KEY`、`CLI_PROXY_API_KEY_2`……。模型选择器中按账号名称分组。
96
- - **路由 ID 不能重叠**（例如另一个账号不能使用 `cli-proxy-messages`），保存时会拒绝。
97
- - **停用**账号：保留全部配置，但删除它的路由，模型从选择器中消失；其他账号不受影响。
98
- - **新增**账号默认停用。填写地址与密钥后可先「立即探测刷新」预览模型并勾选，再打开「启用此账号」保存。
99
- - 填写了服务地址的账号**只探测该地址**，连不上就报错，不会回退到本地 `:8317`，避免多个账号指向同一服务。
100
- - **删除**账号会移除它的路由，但保留凭证服务中的密钥。
101
-
102
- ### Agent 工具 `cliproxyapi`
103
-
104
- | `action` | 作用 |
105
- |---|---|
106
- | `status` | 查看所有账号（或 `account` 指定的账号）状态与模型 |
107
- | `refresh` | 立即探测并同步；不带 `account` 时刷新全部账号 |
108
- | `configure` | 修改一个账号（默认第一个），保存后立即刷新 |
109
- | `add_account` | 新增账号；给了 `baseURL` 时默认启用，否则停用 |
110
- | `remove_account` | 删除 `account` 及其路由 |
111
-
112
- 参数（除 `action` 外均可选）：
113
-
114
- | 参数 | 说明 |
115
- |---|---|
116
- | `account` | 账号 id（如 `default`、`account-2`），也可用路由 ID 或账号名称 |
117
- | `enabled` | 启用 / 停用该账号 |
118
- | `baseURL` | CPA 地址，如 `http://127.0.0.1:8317`；空字符串表示自动发现 |
119
- | `apiKey` | Bearer 密钥，保存到该账号的 `apiKeyEnv` 引用名下 |
120
- | `apiKeyEnv` | 密钥引用名（`[A-Za-z_][A-Za-z0-9_]*`） |
121
- | `provider` | `llm-pi-ai` 路由 ID，每个账号唯一 |
122
- | `displayName` | 账号名称 / 模型选择器分组名 |
123
- | `protocolMode` | `auto`（按家族原生协议，默认）或 `fixed` |
124
- | `protocol` | `fixed` 时使用的协议：`openai-completions` / `openai-responses` / `anthropic-messages` |
125
- | `selectedModels` | 显示在选择器中的模型 id 列表；`[]` 表示全部 |
126
- | `includePrefix` / `excludePrefix` | 逗号分隔的模型 id 关键词 |
127
- | `modelOverrides` | `{ [modelId]: { contextWindow?, maxTokens?, image?, reasoningLevels?, protocol? } }`，整体替换 |
128
-
129
- 示例：
130
-
131
- ```json
132
- { "action": "configure", "baseURL": "http://127.0.0.1:8317", "apiKey": "sk-...", "selectedModels": ["gpt-6.1-sol", "claude-opus-5-5"] }
133
- { "action": "add_account", "displayName": "Backup CPA", "baseURL": "https://other-cpa:8317", "apiKey": "sk-...", "selectedModels": ["gpt-6-astra"] }
134
- { "action": "configure", "account": "account-2", "enabled": false }
135
- { "action": "remove_account", "account": "account-2" }
136
- ```
137
-
138
- 输出包含 `accounts[]`（每个账号的 `id`、`displayName`、`provider`、`enabled`、`state`、`endpoint`、`modelCount`、`totalDiscovered`、`error`）与文字摘要 `summary`。`state` 取值：`idle`、`probing`、`connected`、`disabled`、`error`。
139
-
140
- ### 斜杠命令
141
-
142
- - `/cpa-status`：显示所有账号的状态。
143
- - `/cpa-refresh`：立即刷新所有账号（包括探测停用账号的模型列表）。
144
-
145
- ### HTTP 接口
146
-
147
- 供设置面板使用，需要 DSH Web 会话认证；POST 仅接受本机/受信任主机的同源请求。
148
-
149
- | 方法 | 路径 | 请求体 | 说明 |
150
- |---|---|---|---|
151
- | GET | `/api/dsh-cliproxyapi/status` | — | `{ ok, global, accounts[] }` |
152
- | POST | `/api/dsh-cliproxyapi/refresh` | `{ accountId? }` | 刷新一个或全部账号 |
153
- | POST | `/api/dsh-cliproxyapi/save` | `{ accountId?, …账号字段, apiKey?, clearApiKey?, refreshIntervalSeconds?, probeTimeoutMs? }` | 保存账号（缺省为第一个）；只有全局字段时只保存全局设置 |
154
- | POST | `/api/dsh-cliproxyapi/accounts/add` | 账号字段（可选） | 新增账号，默认停用；返回 `createdId` |
155
- | POST | `/api/dsh-cliproxyapi/accounts/remove` | `{ accountId }` | 删除账号及其路由 |
156
-
157
- ## 协议路由
158
-
159
- CLIProxyAPI 对每个模型同时提供 OpenAI Chat、OpenAI Responses、Anthropic Messages 三种入口，入口协议与上游不一致时会做转换。自动模式（`protocolMode: "auto"`）让每个模型直接使用上游协议：
160
-
161
- | 模型家族（依据 `owned_by` 与模型 id） | 协议 | 路由（以 `cli-proxy` 为例） |
162
- |---|---|---|
163
- | Claude（含 `devin/claude-*`、Antigravity Claude） | Anthropic Messages `/v1/messages` | `cli-proxy-messages` |
164
- | OpenAI / Codex / GPT、xAI Grok | OpenAI Responses `/v1/responses` | `cli-proxy-responses` |
165
- | Gemini、DeepSeek、Kimi、GLM、SWE、gpt-oss 等 | OpenAI Chat `/v1/chat/completions` | `cli-proxy` |
166
-
167
- - DSH 自定义路由不支持 Gemini 原生 `generateContent`，Gemini 走 OpenAI Chat。
168
- - DSH 每条路由只有一种协议，模型按协议拆入三条路由；没有模型的路由会被移除。默认模型因此换路由时，`agent-default-model` 自动跟随。
169
- - Claude 4.6+ / 5.x / Fable 使用自适应思考（`effort`），更早的 Claude 使用 token 预算。
170
- - 可改为「统一使用」某一协议（`fixed`），或在单个模型的「编辑参数」中指定协议。
171
- - 路由上你手动添加的其他字段（如 `retryPolicy`）会被保留。
172
-
173
- ## 存储与配置
174
-
175
- - **状态文件**：`<Profile 目录>/.dsh-cliproxyapi/state.json`
176
-
177
- ```json
178
- {
179
- "version": 2,
180
- "refreshIntervalSeconds": 300,
181
- "probeTimeoutMs": 5000,
182
- "accounts": [
183
- {
184
- "id": "default", "enabled": true, "provider": "cli-proxy", "displayName": "CLI Proxy API",
185
- "baseURL": "https://cpa.example.com", "apiKeyEnv": "CLI_PROXY_API_KEY",
186
- "protocol": "openai-completions", "protocolMode": "auto",
187
- "includePrefix": "", "excludePrefix": "", "selectedModels": ["gpt-6.1-sol"], "modelOverrides": {}
188
- }
189
- ]
190
- }
191
- ```
192
-
193
- 文件每次读取时都会重新加载，手动修改后点「立即探测刷新」即可生效。v1 单账号文件会自动迁移为 id `default` 的账号（路由、密钥、勾选不变），原文件备份为 `state.v1.json`。
194
-
195
- - **密钥**：通过 DSH `credentials` 服务按引用名存取；未存储时回退读取同名环境变量。本地免密的 CPA 可以不填密钥。
196
- - **环境变量**：`CLIPROXYAPI_BASE_URL` 仅用于服务地址留空的账号的自动发现。
197
- - **Bundle 行配置**：`cordis.patch.yml` 中插件行的 `config` 会在启动时叠加到状态文件上：含 `accounts` 时替换账号列表，否则平铺字段作用于第一个账号。通常保持 `{}`，使用面板或工具配置即可。
198
-
199
- ## AI Agent 安装与配置指南
200
-
201
- > 给 DeepSeek Harness 中的 AI Agent：用户要求安装或配置本插件时按以下步骤执行。本包没有 npm 依赖，也没有构建脚本。
202
-
203
- 1. **安装**：调用 `plugin_manager`，`{"action": "install_bundle", "target": "<见安装一节>", "enabled": true}`。查看结果中的 `application` 与 `warnings`；`restart-required` 表示需重启 DSH 后新代码才会运行。
204
- 2. **配置**：使用 `cliproxyapi` 工具。
205
- - 本地 `http://127.0.0.1:8317` 且无鉴权：无需配置，调用 `{"action": "refresh"}`。
206
- - 远程地址或密钥：`{"action": "configure", "baseURL": "...", "apiKey": "..."}`（第一个账号），额外账号用 `{"action": "add_account", ...}`；指定账号时传 `"account": "<id>"`。
207
- - 用 `selectedModels`（取自 `status` 输出的精确 id）精简模型选择器。
208
- 3. **验证**：`{"action": "status"}` 中每个启用的账号 `state` 为 `connected` 且 `modelCount > 0`。告诉用户模型已出现在 DSH 模型选择器中（以账号名称分组），可在 **左侧栏 → 插件 → CLIProxyAPI** 或 **设置 → 内置插件 → CLIProxyAPI** 管理账号。
209
-
210
- 不要把 API Key 回显给用户或写入任何文件。
211
-
212
- ## 开发
213
-
214
- ```text
215
- lib/index.js Host 插件（发现、同步、多账号控制器、工具、命令、HTTP 接口）
216
- lib/client.js Web 设置面板（ModuleLoader 格式，手写，无需构建）
217
- locale/*.json 插件管理器中显示的标题与描述
218
- cordis.patch.yml Bundle patch，插入 dsh-cliproxyapi-pro 行
219
- tests/ node:test 单元与集成测试
220
- .github/workflows/ CI（测试）与发版（Release .tgz，可选 npm 发布）
221
- assets/screenshots/ README 截图（同时登记在 screenshots.json 中供插件市场展示）
222
- AGENTS.md 给编码 Agent 的开发约定、架构与不变量
223
- ```
224
-
225
- ```powershell
226
- git clone https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro.git
227
- cd dsh-cliproxyapi-pro
228
- npm test # 运行测试
229
- npm run check # 语法检查 + 测试
230
- npm run pack:check # 查看打包文件列表
231
- ```
232
-
233
- 修改代码前请阅读 [AGENTS.md](AGENTS.md)；变更记录见 [CHANGELOG.md](CHANGELOG.md)。欢迎提交 Issue 与 Pull Request，修改说明文档时请同时更新中英文两份。
234
-
235
- ## 许可证
236
-
237
- [MIT](LICENSE)