dsh-cliproxyapi-pro 1.9.0 → 1.9.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 (81) hide show
  1. package/CHANGELOG.md +15 -0
  2. package/README.en.md +23 -407
  3. package/README.md +23 -407
  4. package/lib/client.js +46 -20
  5. package/lib/host/accounts.js +176 -0
  6. package/lib/host/apply/agent-tool.js +406 -0
  7. package/lib/host/apply/commands.js +122 -0
  8. package/lib/host/apply/controller.js +105 -0
  9. package/lib/host/apply/http-routes.js +273 -0
  10. package/lib/host/apply/image-jobs.js +171 -0
  11. package/lib/host/apply/index.js +41 -0
  12. package/lib/host/apply/interpret.js +72 -0
  13. package/lib/host/apply/lifecycle.js +34 -0
  14. package/lib/host/apply/media-failures.js +68 -0
  15. package/lib/host/apply/media-service.js +202 -0
  16. package/lib/host/apply/quota-service.js +42 -0
  17. package/lib/host/apply/references.js +43 -0
  18. package/lib/host/apply/session-status.js +104 -0
  19. package/lib/host/apply/state.js +78 -0
  20. package/lib/host/apply/updates.js +55 -0
  21. package/lib/host/apply/video-command.js +152 -0
  22. package/lib/host/apply/video-edit.js +253 -0
  23. package/lib/host/apply/video-jobs.js +206 -0
  24. package/lib/host/apply-utils.js +39 -0
  25. package/lib/host/config.js +205 -0
  26. package/lib/host/controller.js +435 -0
  27. package/lib/host/discovery.js +295 -0
  28. package/lib/host/http-gate.js +144 -0
  29. package/lib/host/models.js +102 -0
  30. package/lib/host/mount-guard.js +56 -0
  31. package/lib/host/routes.js +165 -0
  32. package/lib/host/runtime.js +445 -0
  33. package/lib/host/state-store.js +39 -0
  34. package/lib/host/status-text.js +93 -0
  35. package/lib/index.js +17 -4417
  36. package/lib/media/agent-tool.js +255 -0
  37. package/lib/media/choice.js +83 -0
  38. package/lib/media/classify.js +65 -0
  39. package/lib/media/codec/fit.js +76 -0
  40. package/lib/media/codec/jpeg.js +158 -0
  41. package/lib/media/codec/png.js +102 -0
  42. package/lib/media/commands/parsing.js +269 -0
  43. package/lib/media/constants.js +46 -0
  44. package/lib/media/diagnose.js +134 -0
  45. package/lib/media/images.js +165 -0
  46. package/lib/media/index.js +29 -0
  47. package/lib/media/interpret.js +126 -0
  48. package/lib/media/job-store.js +99 -0
  49. package/lib/media/mp4.js +44 -0
  50. package/lib/media/output-files.js +59 -0
  51. package/lib/media/session-store.js +293 -0
  52. package/lib/media/settings.js +255 -0
  53. package/lib/media/util.js +45 -0
  54. package/lib/media/video.js +326 -0
  55. package/lib/quota/auth-state.js +33 -0
  56. package/lib/quota/constants.js +86 -0
  57. package/lib/quota/controller.js +467 -0
  58. package/lib/quota/helpers.js +325 -0
  59. package/lib/quota/index.js +19 -0
  60. package/lib/quota/management.js +216 -0
  61. package/lib/quota/matching.js +143 -0
  62. package/lib/quota/parsers.js +352 -0
  63. package/lib/quota/probes/billing.js +80 -0
  64. package/lib/quota/probes/google.js +120 -0
  65. package/lib/quota/probes/oauth.js +27 -0
  66. package/lib/quota/probes/plugin.js +18 -0
  67. package/lib/updater/constants.js +23 -0
  68. package/lib/updater/errors.js +8 -0
  69. package/lib/updater/index.js +11 -0
  70. package/lib/updater/registry.js +83 -0
  71. package/lib/updater/settings.js +45 -0
  72. package/lib/updater/store.js +23 -0
  73. package/lib/updater/updater.js +148 -0
  74. package/lib/updater/verify.js +110 -0
  75. package/lib/updater/version.js +31 -0
  76. package/locale/en.json +1 -1
  77. package/locale/zh.json +1 -1
  78. package/package.json +6 -9
  79. package/lib/media.js +0 -2542
  80. package/lib/quota.js +0 -1748
  81. package/lib/updater.js +0 -443
package/CHANGELOG.md CHANGED
@@ -4,6 +4,21 @@
4
4
 
5
5
  本插件的所有重要变更。版本号遵循[语义化版本](https://semver.org/lang/zh-CN/)。
6
6
 
7
+ ## 1.9.1 — 2026-10-27
8
+
9
+ ### 修复
10
+ - **额度查询失败后不再持续自动重试。** 自动刷新缓存从 5 分钟延长到 30 分钟(1.9.0 的管理密钥被拒绝后最多 3 次后台重试也随之按 30 分钟间隔进行,计数规则不变);其他账号级查询失败(网络错误、超时、HTTP 错误、无效响应)暂停该账号,单个凭证额度探测失败只暂停该凭证,其他正常凭证继续更新。仅对该账号手动刷新或保存管理密钥才重试,失败会再次暂停;刷新全部不会恢复暂停项。界面提示暂停原因与恢复方式。暂停保存在宿主内存中,刷新网页不解除,重载插件或重启宿主会重置。
11
+ - **额度状态接口失败后降低页面轮询频率。** 即使旧状态仍为「刷新中」,也按 60 / 120 / 240 / 300 秒退避,不再每 4 秒持续查询;成功读取状态或手动操作成功后恢复正常轮询。
12
+
13
+ ### 变更
14
+ - **代码按职责拆分,功能不变。** Host 入口 `lib/index.js` 只保留导出,实现拆到 `lib/host/`(含 `lib/host/apply/`);生成、额度、更新引擎分别移到 `lib/media/`、`lib/quota/`、`lib/updater/`。网页界面仍是单个文件 `lib/client.js`,改为由 `src/client/` 的源码通过零依赖脚本 `scripts/build-client.mjs` 生成并提交到仓库,安装时不构建、不引入依赖。测试按模块分到 `tests/<模块>/`。
15
+ - 打包文件改为 `lib/**/*.js`,安装包会包含新的模块文件。1.5.0–1.6.0 内置的离线更新仍使用旧的固定文件清单,会拒绝这个版本的离线包;这些版本的用户请通过插件市场或 npm 升级一次(插件页和 `dsh plugin add` 不受影响)。1.7.0 及以后按包内 `files` 校验,不受影响。
16
+
17
+ ### 文档
18
+ - README 精简为概览、安装与快速上手,详细说明移到 `docs/zh/` 与 `docs/en/`;`AGENTS.md` 精简为入口,开发细节移到 `docs/dev/`。
19
+ - 更正存储说明:`media-settings.json` 的每个字段都有作用(此前写着部分字段为预留)。
20
+ - 更新插件简介(npm 的 `description` 与 DSH 插件列表里显示的 `locale/*.json` `meta.description`),补上按原生协议同步、各凭证额度和可选的生图 / 生视频。
21
+
7
22
  ## 1.9.0 — 2026-10-25
8
23
 
9
24
  ### 新增
package/README.en.md CHANGED
@@ -10,31 +10,18 @@
10
10
 
11
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
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. By default the plugin registers no agent tool, so it takes no model context (the optional generation tool `generate_media` is switched on in the Generation tab).
17
- - **Plugin updates**: automatically check Stable / Beta / Dev channels and choose global / Mainland China sources. With the [DSH plugin market (dshmarket)](https://github.com/dsh-market/dsh-market) installed, new versions install in one click or automatically; otherwise download a verified offline package and upgrade with DSH closed.
18
- - **Secure**: API keys live only in the DSH credentials service, never in configuration files.
19
- - **Zero dependencies**: no npm dependencies and no build step; installs in seconds.
13
+ - **Multiple accounts**: each account has its own URL, key, model selection and parameters, and can be switched off at any time. [Details](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/blob/main/docs/en/accounts-and-models.md)
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. [Details](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/blob/main/docs/en/accounts-and-models.md)
15
+ - **Native protocols**: Claude over Anthropic Messages, GPT / Codex / Grok over OpenAI Responses, everything else over OpenAI Chat — fewer protocol translations inside CPA. [Details](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/blob/main/docs/en/accounts-and-models.md)
16
+ - **Visual management**: check models and edit per-model parameters in the settings panel. By default the plugin registers no agent tool, so it takes no model context (the optional generation tool `generate_media` is switched on in the Generation tab). [Details](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/blob/main/docs/en/accounts-and-models.md)
17
+ - **Channel quota**: see each channel's remaining quota per credential, with a badge for the current model in the composer; failed queries pause automatic refresh. [Details](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/blob/main/docs/en/quota.md)
18
+ - **Images and videos**: generate and edit images, and generate, edit and extend videos through CPA; the optional agent generation tool is off by default. [Details](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/blob/main/docs/en/media.md)
19
+ - **Plugin updates**: automatically check Stable / Beta / Dev channels and choose global / Mainland China sources. With the [DSH plugin market (dshmarket)](https://github.com/dsh-market/dsh-market) installed, new versions install in one click or automatically; otherwise download a verified offline package and upgrade with DSH closed. [Details](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/blob/main/docs/en/updates.md)
20
+ - **Secure**: API keys live only in the DSH credentials service, never in configuration files. [Details](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/blob/main/docs/en/storage-and-config.md)
21
+ - **Zero dependencies**: no npm dependencies and nothing built at install time; installs in seconds. [Details](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/blob/main/docs/en/development.md)
20
22
 
21
23
  Works with DSH `0.2.0-rc.1` and later (desktop and web).
22
24
 
23
- ## Contents
24
-
25
- - [Installation](#installation)
26
- - [Getting started](#getting-started)
27
- - [Screenshots](#screenshots)
28
- - [Features in detail](#features-in-detail)
29
- - [Updating this plugin](#updating-this-plugin)
30
- - [Slash commands and HTTP routes](#slash-commands-and-http-routes)
31
- - [Storage and configuration](#storage-and-configuration)
32
- - [Upgrading and uninstalling](#upgrading-and-uninstalling)
33
- - [FAQ](#faq)
34
- - [AI installation guide](#ai-installation-guide)
35
- - [Development](#development)
36
- - [License](#license)
37
-
38
25
  ## Installation
39
26
 
40
27
  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.
@@ -49,7 +36,7 @@ The plugin is published on npm as [`dsh-cliproxyapi-pro`](https://www.npmjs.com/
49
36
  dsh-cliproxyapi-pro
50
37
  ```
51
38
 
52
- To pin a version, write `dsh-cliproxyapi-pro@1.9.0`.
39
+ To pin a version, write `dsh-cliproxyapi-pro@1.9.1`.
53
40
  4. Click **Install**. When it finishes, the dialog offers to enable the plugin right away — accept it.
54
41
 
55
42
  > If downloads are slow in mainland China, open **Registry** next to the input and choose **the mainland China mirror**.
@@ -78,7 +65,7 @@ In **Add plugin**, or as the `plugin_manager` `target`, you can also enter:
78
65
 
79
66
  | Source | What to enter |
80
67
  |---|---|
81
- | A released version | `git+https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro.git#v1.9.0` |
68
+ | A released version | `git+https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro.git#v1.9.1` |
82
69
  | Latest development version | `git+https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro.git#main` |
83
70
  | 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 |
84
71
  | Local source (development) | Absolute path of a cloned repository; installed as a link, so code changes go live when the plugin reloads |
@@ -130,389 +117,18 @@ The panel follows the DSH display language; the screenshots show the Chinese UI.
130
117
 
131
118
  ![The CLIProxyAPI update page under Built-in plugins: version status, plugin-market update, channel, region and automatic switches](https://raw.githubusercontent.com/TinyBOOOOM/dsh-cliproxyapi-pro/main/assets/screenshots/updates.png)
132
119
 
133
- ## Features in detail
134
-
135
- ### Discovery and synchronization
136
-
137
- - The base URL can be local or remote; suffixes such as `/v1`, `/v1/chat/completions` and `/v1/messages` are stripped.
138
- - 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`.
139
- - 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 and its `type` marks image models.
140
- - Image and video models are never written to chat routes; see [Image and video models](#image-and-video-models-the-generation-tab).
141
- - All accounts refresh on a shared interval (300 s by default); an unchanged catalog writes no settings.
142
-
143
- ### Model selection
144
-
145
- - 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.
146
- - Include / exclude keyword rules filter further.
147
- - 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.
148
-
149
- ### Per-model overrides
150
-
151
- **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.
152
-
153
- ### Multiple accounts
154
-
155
- - 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.
156
- - **Disabling** an account keeps its settings but removes its routes, so its models leave the picker; other accounts are unaffected.
157
- - **New** accounts: **+ Add Account** first tests the entered URL and key and creates an enabled account only when that works; **Add Anyway (Disabled)** is also offered.
158
- - Each account page has **Connection / Models / Generation / Quota** tabs under one shared account bar. The **Enabled** switch next to the account title applies at once; the **⋯** menu holds **Probe & Refresh** and **Delete Account**.
159
- - Connection and model changes are tracked together; a bar at the bottom shows **Unsaved changes · Discard / Save & Apply**, and switching accounts asks before dropping unsaved changes. **Test Connection** probes the address and key being edited without saving anything.
160
- - Secondary explanations live in ⓘ tips next to the labels (open on hover, keyboard focus or click).
161
- - 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.
162
- - Provider route IDs of different accounts must not overlap; conflicting changes are rejected.
163
- - **Deleting** an account removes its routes but keeps its key in the credentials service.
164
-
165
- ### Protocol routing
166
-
167
- 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:
168
-
169
- | Model family (from `owned_by` and the model id) | Protocol | Route (for `cli-proxy`) |
170
- |---|---|---|
171
- | Claude (including `devin/claude-*`, Antigravity Claude) | Anthropic Messages `/v1/messages` | `cli-proxy-messages` |
172
- | OpenAI / Codex / GPT, xAI Grok | OpenAI Responses `/v1/responses` | `cli-proxy-responses` |
173
- | Gemini, DeepSeek, Kimi, GLM, SWE, gpt-oss, … | OpenAI Chat `/v1/chat/completions` | `cli-proxy` |
174
-
175
- - DSH custom routes cannot speak Gemini's native `generateContent`, so Gemini uses OpenAI Chat.
176
- - 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.
177
- - Claude 4.6+ / 5.x / Fable use adaptive thinking (`effort`); older Claude models use a token budget.
178
- - Switch to one protocol for every model, or set a protocol per model under **Edit Parameters**.
179
- - Other fields you add to a managed route by hand (such as `retryPolicy`) are kept.
180
-
181
- ### Channel quota (the "Quota" tab and the composer badge)
182
-
183
- Each account's **Quota** tab (next to **Connection**, **Models** and **Generation**) shows that account's channel quota; the tab label shows the lowest remaining quota among its usable credentials.
184
-
185
- - **Management key**: on an account's Quota tab, enter its CPA management key (`remote-management.secret-key` in the CPA config; a remote CPA also needs `remote-management.allow-remote`). It is stored in the DSH credentials service under `CLI_PROXY_MANAGEMENT_KEY` for the first account and `CLI_PROXY_MANAGEMENT_KEY_<ACCOUNT_ID>` for the others (for example `CLI_PROXY_MANAGEMENT_KEY_ACCOUNT_2`); it is never written to `state.json`, settings or logs, and never sent back to the page.
186
- - **Read by the Host**: the Host reads every credential on that CPA (`/v0/management/auth-files`), the models each credential serves, and the upstream quota through `/v0/management/api-call`: Codex, Claude, Antigravity, Gemini CLI, Kimi (including Kimi International, kimi.ai), xAI, Devin and Meta. Channels provided by CPA plugins (credentials marked `supports_quota`) use CPA's own `/v0/management/quota/fetch` instead. Devin's daily / weekly quota belongs to the whole account, so every `devin/…` model shows the same windows. Meta's quota endpoint needs the `dca_token` from the credential file; the Host reads it through the management API for each query, uses it for that one request only, and never stores or logs it. API-key channels (OpenAI-compatible, Gemini / Claude / Codex API keys) and Vertex have no quota endpoint (CPA's own panel shows none either) and show their status and recent request counts only; paid xAI accounts expose no quota counters either (CPA's panel probes them with a real chat request; this plugin does not, so background refreshes never cost money).
187
- - **Quota tab**: laid out as flat rows like the native DSH settings pages: management key, quota data and refresh, a distribution bar (healthy / low / exhausted / off or failing), credentials grouped by channel (plan, prefix, status, 5-hour / weekly / monthly / daily meters with reset times; problems and the least remaining first), channel filter (search when there are many credentials), and an expandable "Model → Channel" table showing which credentials each picker model is matched to.
188
- - **Composer badge**: a small badge left of the model selector (signal bars + percentage) shows the best remaining quota among the usable credentials serving the selected model; click it for every credential's windows. It appears only for models this plugin synchronizes whose account has a management key; without a key there is no badge. On the New Session page (before the composer takes over the session) the badge sits at the right end of the workspace row above the input box.
189
- - **Exact matching**: credentials are looked up only in the account the selected route belongs to (`cli-proxy*`, `cli-proxy-2*`, …); a prefixed model (such as `devin/claude-opus-5-5`) matches only credentials with that prefix; a bare id (such as `claude-opus-5-5`) prefers un-prefixed credentials, so the Claude and Devin channels never mix. Per-model-group windows (for example Antigravity) count only the group that fits the current model.
190
- - **Troubleshooting**: `/cpa-status` includes a quota summary: each account's key state, quota state, credential count, and which credentials each picker model maps to with its remaining quota (never the key).
191
- - **Refreshing**: results are cached on the Host for 5 minutes; stale accounts refresh in the background only while a page is asking, or on **Refresh Quota**. When the management key is rejected (401/403), background checks continue at the 5-minute interval and stop for that account after 3 rejections in a row, so CPA's bad-key protection (a 30-minute ban after 5 bad keys from one address) is not triggered. The count is stored in `.dsh-cliproxyapi/quota-state.json` (never the key) and continues after a DSH restart; saving a new management key (also on the DSH credentials page), clearing the key or a successful check resets it. Once stopped, a manual refresh tries only once and stops again on another rejection. The Quota tab and the badge show how many times the key was rejected, or that checks have stopped.
192
-
193
- ### Image and video models (the "Generation" tab)
194
-
195
- CPA serves image and video generators (such as Grok Imagine) through `/v1/images/*` and `/v1/videos/*`. They cannot chat, so the plugin recognizes them and keeps them out of the chat model picker.
196
-
197
- - **Master switch**: **Enable image and video generation** at the top of the Generation tab applies to every account. While off, the composer shows no generation buttons, `/cpa-image`, `/cpa-video`, `/cpa-video-edit`, `/cpa-video-extend` and `/cpa-video-status` are not registered, the agent generation tool is not registered either, and the Generation tab shows only this switch; videos already submitted still finish, and past results in the chat stay viewable (without the edit / extend buttons). New installations start with it off; a profile that already has `media-settings.json` or has used generation keeps it on after the upgrade. Either way, media models never enter the chat model picker. Everything below needs it switched on.
198
- - **Recognition**, in order: a kind you set on the Generation tab; the catalog's `type` (`openai-image` is an image model) or output modalities (image-only output is an image model, video output a video model); the model families CPA routes to its image / video handlers, matched by prefix: ids starting with `grok-imagine-image` or `gpt-image-` are image models, ids starting with `grok-imagine-video` and `sora-2*` are video models. Everything else is a chat model (for example `gemini-3.1-flash-image`: CPA serves it only through chat, and DSH cannot show images returned in a chat reply). A media model that only the plain `/v1/models` listing carries is included too. A catalog may list variants CPA's generation endpoints do not accept yet (for example `grok-imagine-video-1.5-lite`); they cannot chat either, so they count as media models, and generating with one shows CPA's error.
199
- - **Not in the model picker**: media models are written to no chat route and take no part in the first-run recommendation; an older selection that names them does not synchronize them (the selection itself is kept). The Models tab lists chat models only.
200
- - **The Generation tab** (next to Connection / Models / Quota) lists "Image models" and "Video models"; changes are saved at once. A switch decides whether each model is offered for generation (models that appear later start switched on), and a kind menu changes it to image / video / chat; a kind you set can be reset to the detected one. A model detection missed can be marked under "Mark another model as a media model". Changing a kind re-synchronizes that account's routes immediately. `sora-2*` is labelled "→ grok-imagine-video": CPA rewrites it to the Grok video model.
201
- - **Read-only diagnostic**: **Run diagnostic** sends GET requests only: it reads both model catalogs with the account's key and lists media-looking entries with descriptive fields such as `type` and modalities, then probes `GET /v1/videos/{id}` and `GET /openai/v1/videos/{id}/content` **without the key** (a route that exists answers 401 at once; a missing one gets CPA's 404). It generates nothing and spends no quota; if CPA does not require a key, the probe looks up one nonexistent job id, which is still read-only. The result can be copied and never contains the key.
202
- - **Save location**: the bottom of the Generation tab sets where generated files go (default `generated`); a relative path is resolved against the session's working directory, an absolute path also works. Shared by all accounts.
203
- - **Agent generation**: the **Let the agent generate images / videos** switch (off by default), how agent videos / images are confirmed, and the per-session limit of agent video seconds; see "Letting the agent generate" below.
204
- - **Video defaults**: when the account has video models, the Generation tab sets the default length (1–15 s, default 6 s) and resolution (480p / 720p, default 720p) of `/cpa-video`; shared by all accounts, saved at once.
205
-
206
- #### Generating images (`/cpa-image`)
207
-
208
- Type in the composer:
209
-
210
- ```text
211
- /cpa-image a ginger cat on a neon street on a rainy night
212
- /cpa-image -m quality --aspect 16:9 -n 2 a ginger cat on a neon street on a rainy night
213
- ```
214
-
215
- - **Options** (before the prompt): `-m <model>` picks a model for this run — a full `accountId/modelId`, a model id, or a fragment that matches exactly one model (such as `quality`); several matches are an error that lists them, never a guess. `--aspect <ratio>` is one of `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`, `9:20`, `20:9`. `-n <1-4>` sets the number of images. They can also be written as separate words at the start or end of the prompt (split by spaces or commas): `16:9`, `portrait` / `竖屏` (9:16), `landscape` / `横屏` (16:9), `square` / `方形` (1:1), `2 images` / `2张`, e.g. `/cpa-image 2张 portrait a ginger cat`; an explicit option such as `-n` wins. Everything after `--` is prompt text.
216
- - **Editing**: attach 1–4 images in the composer and run the command; it then uses CPA's `/v1/images/edits` with the images as references (about 1.4 MB in total). Only image attachments are accepted. Attached images travel base64-encoded inside the request, and upstreams cap the request size (about 2 MiB; xAI answers "Failed to read request body: length limit exceeded"), so an oversized image is shrunk first: the plugin re-encodes a PNG as JPEG itself (transparent parts on white, long edge at most 1280), and asks DSH's attachment service for a smaller version of other formats; if it still does not fit, the command fails right away.
217
- - **Saving**: files are written to the save location under the session's working directory, named like `20261022-133000-grok-imagine-image-a-ginger-cat-on-a-neon-s.png` (the first 24 characters of the prompt); an existing file is never replaced, a number is appended instead. The working directory must be a local folder.
218
- - **After you submit**: the command checks the options, model, save folder and references, then returns at once, so the composer clears right away; the generation continues in the background. Meanwhile the workspace session list shows the session as running, and as completed if it finishes while you are in another session. DSH itself counts only agent turns as running, so during a generation the plugin sends DSH's own session status event (`api-session/status`) and repeats it every 5 seconds. During a generation the composer shows a Stop button that cannot stop it (the upstream cannot cancel either); just keep sending messages, the agent answers as usual. Reloading the plugin or closing DSH interrupts a running generation.
219
- - **Result**: the `/cpa-image` row in the conversation reads like an exchange: on the right, a bubble with your prompt (ratio, count and reference images noted below it); on the left, the reply: model and account, the status, placeholders in the requested ratio with a timer while generating, then the images (one image at its own ratio, several as square thumbnails); click one to enlarge it. Below are the time taken and the save folder (relative to the working directory, or the folder's name); **Details** expands the full folder path and the file names (click to open them with the system) and, when the upstream rewrote the prompt, the revised prompt; a failure shows its reason in red. Earlier runs show their images too, as long as the files exist and their records were not pushed out (the last 48 runs and 48 files per session are kept). The images are only shown on the page; they are never sent to the chat model.
220
- - **Image actions**: right-click an image for a menu listing the applications on this computer that open it (the default application first and marked "(default)", like the Open menu of the document preview), then **Show in File Explorer** (**Show in Finder** on macOS, **Show in Files** on Linux), then **Copy image** and **Copy file path**. Under an enlarged image, buttons offer **Open with default app**, the file-manager item and both copy actions. Opening and showing the location go through DSH's own session interface (the same as the document preview; DSH re-verifies the path), and are hidden when DSH cannot open local paths; Copy image always puts a PNG on the clipboard (other formats are converted first).
221
- - **Request details**: one `POST /v1/images/generations` (or `/edits`) to the CPA of the model's account, with only that account's address and key and no retry on another account; it asks for `b64_json`. When CPA returns a link instead, the plugin downloads it: only `data:` or HTTPS links, at most 32 MiB per image, and the download carries no key. It waits at most 3 minutes. Failures show a short CPA error summary (truncated, links removed). Generating images spends that account's upstream quota.
222
-
223
- #### Generating videos (`/cpa-video`)
224
-
225
- ```text
226
- /cpa-video waves rolling onto a beach at sunset
227
- /cpa-video -s 8 -r 480p --aspect 9:16 a cat surfing
228
- ```
229
-
230
- - **Options** (before the prompt): `-m <model>` picks a model for this run (same rules as `/cpa-image`); `-s <1-15>` sets the length in seconds; `-r <480p|720p>` the resolution; `--aspect <ratio>` is one of `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`; without it xAI decides (usually 16:9, or the first frame's ratio). These can also be written as separate words at the start or end of the prompt: `10s` / `10 seconds` / `10秒`, `480p` / `720p`, `16:9`, `portrait`, `landscape`, `square`, e.g. `/cpa-video 10s 480p this character dances`; a word counts only when a space, comma or the end follows it, so "3秒后爆炸" stays prompt text, and words in the middle of a sentence are never read as options. An explicit option such as `-s` wins. Without any, the Generation tab's video defaults apply. Everything after `--` is prompt text.
231
- - **How attached images are used** (images only; oversized ones are shrunk as described under Editing; CPA's video generation route was measured to read only about 1 MiB of request body, so all attached images share about 750 KB and are shrunk beyond that):
232
- - 1 image: the **first frame** by default (image to video); with `--ref` (or the word `reference`) a **reference**; with `--last` (or `last-frame`) the **last frame**, where the video ends.
233
- - 2 images: **references** by default; with `--first-last` (or `first-last`) the first is the first frame and the second the last frame, and the model fills in between.
234
- - 3 or more: **references**, up to 14 on `grok-imagine-video-1.5` and 7 on other video models. References bring in people, clothing or objects without locking the first frame; the prompt can name them in order as `<IMAGE_0>`, `<IMAGE_1>`, ….
235
- - Pinned first / last frames need `grok-imagine-video-1.5`. The fields follow xAI's docs: `image`, `last_frame`, `reference_images`.
236
- - **Cannot be cancelled**: once submitted, a video cannot be withdrawn (neither CPA nor xAI has a cancel route) and is billed as usual; the composer's Stop button does not stop it.
237
- - **Request details**: one `POST /v1/videos/generations` to the CPA of the model's account (xAI's native format: `model`, `prompt`, `duration`, `resolution`, and optional `aspect_ratio` and `image.url`; `sora-2*` is rewritten to `grok-imagine-video` as CPA does), then `GET /v1/videos/{request id}`: every 5 s during the first minute, every 10 s up to 3 minutes, then every 15 s. The finished video is downloaded through CPA's `GET /openai/v1/videos/{request id}/content` (CPA fetches the file with the credential's own proxy; the plugin never contacts the upstream host), streamed into the save location, at most 200 MiB, MP4 / MOV / WebM only, never replacing a file.
238
- - **Background and resuming**: once submitted, the job is stored in `media-jobs.json`. Reloading the plugin or restarting DSH only pauses the waiting; the next start keeps polling and saves the video. CPA remembers which credential made a video for 3 hours only, so a job still unfinished after 3 hours is marked expired and no longer polled. A run cut off by a reload before CPA returned a request id is marked interrupted (it may have been submitted; there is no way to tell). Meanwhile the session shows as running too.
239
- - **Result**: the `/cpa-video` row reads like an exchange as well (**Copy original input** at the end of the tag line copies the command exactly as typed; a line under the model name in the reply states the mode actually used, e.g. "Mode: references ×3 — brings in the people, clothing and objects shown, without fixing the first frame" or "Mode: first frame — the attached image is the video's first frame", and for edits / extensions where the source came from: an uploaded local file, a public link or a video from this session): on the right the prompt with length, resolution, ratio and first-frame tags; on the left queued / generating progress (a percentage when CPA reports one) / saving with a timer, then the playable video (seeking works); buttons below and the right-click menu open it with another application, show it in File Explorer, or copy its path.
240
- - `/cpa-video-status` lists this session's last 20 video jobs with their state and request id.
241
-
242
- #### Editing and extending videos (`/cpa-video-edit`, `/cpa-video-extend`)
243
-
244
- ```text
245
- /cpa-video-edit make the dress red, keep everything else
246
- /cpa-video-extend 4s she turns and walks out of frame
247
- /cpa-video-extend --from cmd-xxxx-3 -s 6 the camera slowly pulls back
248
- /cpa-video-edit --video "D:\clips\street.mp4" make it a rainy night
249
- /cpa-video-extend --url https://example.com/clip.mp4 -s 4 the camera pulls back
250
- ```
251
-
252
- - When a video is done, **Edit video…** and **Extend video…** buttons appear below it; write one sentence and submit, and the result appears in a new row below. You can also type the command.
253
- - **Source video** (one of): **attach an MP4 file** in the composer; `--video <path>` (relative to the session's working directory; quote a path with spaces); `--url <public link>` (http/https, downloaded by xAI itself, no size limit); `--from <command id>` (a video the plugin made in this session); without any, the session's newest generated video. A video path also works without `--video`, written at the start or end of the prompt (quoted or with `@` if you like, ending in `.mp4` / `.mov` / `.m4v`), e.g. `/cpa-video-edit D:\clips\a.mp4 make it a snowy night`. Edits and extensions keep the source's resolution and ratio (an edit also its length), so words like `480p`, `16:9`, `portrait` (and `4s` for an edit) at the start or end of the prompt are taken out, not sent to xAI, and shown as ignored in the chat row. `-m <model>` picks whose video model account to use (default: the session's video model; for a video the plugin made, the account that made it).
254
- - **How it works**: xAI's edit (`/v1/videos/edits`) and extension (`/v1/videos/extensions`) take any MP4, as a public link or as base64 data. CPA has no route to xAI's file upload, so a local video travels base64-encoded inside the request (the edit route was measured to read a 20 MiB body, so local videos may be up to 14 MiB; compress or trim larger ones, or use `--url`). For about an hour, a video the plugin made goes by the short-lived link that came with xAI's own result (kept in memory only, never written to a file or log and never sent to the page); after that, or after a reload, the saved file is sent instead, so the buttons stay available while the file exists. Before sending, the plugin reads the length recorded in the MP4 and refuses a source outside the limits below without a request.
255
- - **Limits** (xAI's docs): both use `grok-imagine-video`; an edit needs a source of at most 8.7 s and keeps its length, ratio and resolution (720p at most); an extension needs a 2–15 s source, `-s` sets the added 2–10 s (default 6, or write `4s`), and returns the source plus the new part.
256
- - **When a server lacks a route**: some CPA servers' upstreams have no extension route (one answered HTTP 405 in testing). That run then reads "the upstream does not offer video extension (HTTP 405)", later extensions on the same account are refused without a request and the **Extend video…** button is hidden until the plugin reloads. After a 405, CPA pauses that credential for the model for about a minute.
257
- - Edits and extensions likewise cannot be cancelled once submitted and are billed as usual; background waiting, resuming after a reload and the row's buttons work as for `/cpa-video`.
258
-
259
- #### Reading plain-language parameters with the chat model
260
-
261
- Each time `/cpa-image`, `/cpa-video`, `/cpa-video-edit` or `/cpa-video-extend` runs, the plugin hands the prompt (after the options) to **the chat model the session is using** and asks it for parameters that were not written as options, such as "make it a ten-second portrait video in HD", "use the second image as the ending", "three landscape ones" or "add five more seconds".
262
-
263
- - **What it reads**: images — ratio and count; videos — length, resolution, ratio and how attached images are used (first frame / references / first & last frame / last frame); extensions — the added seconds; edits have no parameters to read, only the prompt is tidied.
264
- - **Priority**: options written in the command (`-s`, `-r`, `--aspect`, `-n`, `--ref`, …) and words recognized at the start or end always win; the chat model only fills in what is missing, and every value it returns is checked against the allowed range (invalid ones are dropped).
265
- - **The prompt only loses words**: the chat model returns the prompt without the words that stated parameters; the plugin accepts it only if it is the original with some characters deleted (no rewriting, translating or expanding, and not most of it removed), otherwise the original is sent.
266
- - **Model and cost**: the model of the session's latest request (else the agent's setting or the default model), a few hundred tokens and 2–5 extra seconds each time (30 s at most); only the prompt text and the number of attached images are sent, never the images. It runs in the background, so the composer still clears at once and the row shows "Reading parameters".
267
- - **Visible result**: the reply says "Parameters <model> read from the prompt: 10s · 9:16 · first-last", and notes when words were taken out of the prompt; if the chat model is unavailable or its answer cannot be read, it says "Reading parameters failed" and the request is sent with the command's options and the prompt as written.
268
-
269
- #### Letting the agent generate (`generate_media` tool, off by default)
270
-
271
- With **Let the agent generate images / videos** switched on in the Generation tab, the chat agent can call the `generate_media` tool to generate images and videos, or to edit and extend videos. While off (the default) the tool is not registered and takes no model context; when on, it is registered only while the **Enable image and video generation** master switch is on and at least one generation model is enabled. Its definition is compact and lists no models.
272
-
273
- - **What it does**: parameters `kind` (image / video) and `prompt`, optionally `mode` (generate / edit / extend), `model`, `images` (local image paths: for images, to edit or combine; for videos, 1 is the first frame and 2 or more are references), `frames` (first frame / references / first & last frame / last frame), `video` (the source of an edit / extension: a local MP4 path or a public link; without it, this session's newest generated video), `aspect`, `seconds`, `resolution`, `count`. Optional fields may be omitted or set to `null` (including on Responses strict-schema routes); video `count` should be `null`, as each call generates one video. An omitted, `null` or empty `model` uses this session's pick in the composer button (a sub-agent uses the pick of the session it belongs to). It works like the matching slash command, except that the prompt is **sent as written**: words like "10s" or "portrait" in it are not read as options and the chat model is not asked to interpret parameters. The tool description also tells the agent to use the user's own wording and level of detail, never expanding it into a longer scene description or adding camera, lighting, style, character or environment details the user did not ask for.
274
- - **Result**: files go to the save location; the tool returns their paths, the model and the actual parameters. For images, when the current chat model can see images, the generated images (downscaled by DSH) are handed to it as well. The chat renders one **independent generation row** from the recorded tool lifecycle, outside the thinking process, using the slash command's exchange layout (progress, images / a playable video, open / show in folder / copy, and **Edit video… / Extend video…** under a video). There is no need to expand thinking, no extra user command is fabricated, and tool cards or legacy mirrored command cards with a matching generation row do not repeat the result.
275
- - **Confirmation**: videos **ask you each time** by default; images are generated directly by default and can be set to ask too. Confirmation appears independently at the owning root session's composer through DSH's native question interface, naming the account, model, length, resolution / ratio, the start of the prompt, attached images, "cannot be cancelled once submitted" and the seconds used in this session. The choices are bilingual: **Allow / 允许** and **Decline / 拒绝**. This is consent to generation costs, independent of DSH's execution-approval permissions; "full access" does not bypass it. Only an explicit Allow choice submits the request, and declining tells the agent not to retry. No answer within 10 minutes, stopping the wait, disabling the tool or reloading / unloading the plugin refuses consent; a native-question error never grants it either. Only when DSH lacks the native question service does a compatibility confirmation area appear beside the owning root session's composer; generation rows themselves contain no confirmation buttons.
276
- - **Seconds limit**: videos the agent submits are counted in seconds per session (a sub-agent counts against the session it belongs to), 60 s per session by default; choose 30 s to 1 hour or no limit. Videos over the limit are refused only when generating directly; when asking, they are only counted. An edit counts the source's length, an extension the added seconds. Seconds come back when CPA refuses a video at once (no job was created), not when the upstream generation fails. Changing the limit, or switching from asking to direct generation, starts the count again. Your own `/cpa-video` and other commands are neither counted nor confirmed.
277
- - **Per session**: while the tool is on, **Agent generation settings** at the bottom of either model menu opens a secondary menu: video / image confirmation and the video limit can follow the global setting or be set for this session, with "Agent videos in this session: X of N s".
278
- - **Waiting**: the tool waits up to 10 minutes. On timeout, or when you stop the turn, the video keeps generating in the background (and is billed); it is saved to the save location and shown in the call's row, and the agent is told it is still running.
279
-
280
- #### The generation-model button next to the composer
281
-
282
- When an image or video model is available, two generation-model buttons appear in the composer left of the model selector, showing the model used for images (picture icon) and for videos (camera icon).
283
-
284
- - The image button opens only image models and the video button only video models; each menu lists every enabled model of that kind by account, and one click switches it. **Agent generation settings** at the bottom of either menu opens a secondary menu with this session's agent confirmations and video seconds limit. **The pick is saved per session** and also becomes your "last pick": a session without a pick of its own (including a new session) uses the last pick.
285
- - `/cpa-image` / `/cpa-video` choose their model in this order: the `-m` model → this session's pick → the last pick → the only available model; with several models and no pick, the command fails and asks you to pick one.
286
- - Both buttons read their data on load, on a session switch and each time a menu opens; they do not poll in the background. When no generation model is available yet while an enabled account has not read its catalog (for example right after DSH starts), or an account's last read missed the plain model listing (which carries some image models), the plugin syncs once during that read; if the catalog is still incomplete, it retries after 3 and 10 seconds, then every 30 seconds until it is complete.
287
- - When `/cpa-image` finds no image model while an enabled account has not read its catalog yet, it syncs once before deciding; if there is still none, the error lists each account's state and model counts.
288
-
289
- ## Updating this plugin
290
-
291
- **Plugin Updates** live on the plugin page (sidebar **Plugins** → **CLIProxyAPI**) and on **Settings** → **Built-in plugins** → the **CLIProxyAPI** tab; those places contain only update features, while accounts and models are on the **CLIProxyAPI** page in the Settings dialog's left navigation. On the plugin page the update card starts expanded, with a summary row showing the current version and update status, and can be collapsed at any time. Background checks still follow the saved switches, and polling never resets the expanded state. It manages only `dsh-cliproxyapi-pro`. It does not update the CPA server or DSH, or change CPA routes, accounts or model selections. Update settings save immediately; the card polls independently without reloading unsaved account forms.
292
-
293
- > **Installation is handed to the plugin market.** This plugin itself never runs a package manager, uninstalls, overwrites source code, or restarts DSH. With the [DSH plugin market (dshmarket)](https://github.com/dsh-market/dsh-market) installed, the card installs new versions in one click or automatically through the market's public Update API v1. Without the market it can only download and verify an offline package for a manual upgrade with DSH closed.
294
-
295
- ### Channels, regions and automatic controls
296
-
297
- | Setting | Default | Behavior |
298
- |---|---|---|
299
- | Update channel | Stable (`stable`) | Stable / Beta / Dev read the npm `latest` / `beta` / `dev` dist-tags respectively. An unpublished Beta / Dev channel reports an error rather than silently falling back to Stable. |
300
- | Download region | Auto (`auto`) | Auto races global npmjs and Mainland China npmmirror, selecting the first source with **valid version metadata**. Global (`global`) uses only `https://registry.npmjs.org`; Mainland China (`cn`) uses `https://registry.npmmirror.com` and its official `cdn.npmmirror.com` package host. The offline package uses the selected source, with at most 3 HTTPS redirects validated against the host allowlist and exact package/version path; it never falls back across regions. |
301
- | Automatically check for updates | On | Check about 3 seconds after plugin startup or rescheduling update settings, then every 6 hours. **Check for Updates** remains available when disabled. |
302
- | Automatically download updates | Off | Download and verify an offline package only when an **automatic check** finds a newer version. Downloading itself never installs or restarts. Enabling this while automatic checks are off does not trigger background downloads. |
303
- | Automatically install updates | Off | Requires automatic checks and dshmarket (cannot be enabled while the market is not detected). When an **automatic check** finds a newer version, an open DSH page asks the plugin market to install it; each version is tried at most once every 6 hours and never again once installed. Market rules such as its release-age wait still apply, and automatic mode never forces an install. A DSH restart or page refresh may be needed for it to take effect. |
304
-
305
- - Strict SemVer comparison offers downloads only when the selected channel is newer than the running version; there is no automatic downgrade. Automatic region selection never falls back across channels.
306
- - The region affects only this plugin's update metadata and package downloads, **not CPA connections, model requests, or other plugins' installation sources**.
307
- - Check again after switching channel or region. Opening the card, polling, or reloading status only reads in-memory state and does not itself contact an update source; background checks follow the controls above.
308
- - Errors are localized, including unpublished channels, network failures, package integrity failures and storage failures, without exposing backend stack traces.
309
-
310
- ### One-click and automatic updates through the plugin market
311
-
312
- 1. The card only reads the market's local `GET /dsh-market/api/v1/capabilities` when it opens and never contacts a registry for it; once detected it shows **Update Now**.
313
- 2. After a check finds a newer version, click **Update Now** and confirm the version. The card submits `POST /dsh-market/api/v1/updates { "packageName": "dsh-cliproxyapi-pro" }` to the market, then polls that operation's progress and result. Version resolution, download, installation, version verification and recovery are all done by the market.
314
- 3. When it finishes, the card shows the version actually installed and, following the market's result, asks you to **Restart DSH** (a button appears only when the market says it owns restarts; quit and reopen the desktop app completely) or **Refresh Page**. If the market, using its own channel, installed an older version than this card found, the card says so.
315
- 4. During the market's release-age wait (`RELEASE_TOO_FRESH`) or before its mirror catches up (`VERSION_UNCHANGED`) you can choose **Install Anyway**; other failures show only a localized reason, never backend text.
316
- 5. Linked local installations (`link:`) are not installed through the market, so their source link is never replaced.
317
-
318
- ### Download, verification and offline upgrade
319
-
320
- Use this without the plugin market or for offline upgrades:
321
-
322
- 1. Click **Check for Updates**. If a newer version is available, click **Download Update** and confirm its version, or wait for enabled automatic checks and downloads.
323
- 2. The download must match the npm metadata's **SHA-512** integrity, then pass gzip / tar, package name and version checks, and every file in it must be declared by that package's own `package.json` `files` (except files npm always packs, such as `package.json`, README and LICENSE). Path traversal, hidden files, `node_modules`, links and other special entries, dependencies and installation lifecycle scripts are rejected. When a download is rejected, the concrete reason is written to the DSH log. The package is saved without extracting into the installation directory or executing its code.
324
- 3. After verification, the card displays the absolute package path and an upgrade command when applicable. Packages are stored at `<profile dir>/.dsh-cliproxyapi/updates/dsh-cliproxyapi-pro-<version>.tgz`.
325
- 4. **Save your work and fully close DSH first**, then run the card's command in a terminal. This example is illustrative; use the actual profile name and absolute path from your card:
326
-
327
- ```bash
328
- dsh plugin --profile 'desktop' add '/absolute/path/dsh-cliproxyapi-pro-<version>.tgz'
329
- ```
330
-
331
- 5. Start DSH again to load the new version. Check results and downloaded-package notices do not persist across plugin reloads; the offline files remain on disk. Remove old downloads yourself when no longer needed; the plugin does not automatically clean them up.
332
-
333
- **Linked local installations (`link:`)** can check and download packages, but do not receive an upgrade command and their source directories are never overwritten. To keep the development setup, manually update the Git source at an appropriate time, then restart DSH. Reinstalling from an offline package changes the plugin's installation source from the link to the package.
334
-
335
- ## Slash commands and HTTP routes
336
-
337
- Apart from the generation tool `generate_media` (off by default, see above), this plugin registers no agent tool and adds nothing to model context. Accounts and models are managed on the **CLIProxyAPI** page in Settings; the slash commands below show and refresh their state.
338
-
339
- ### Slash commands
340
-
341
- - `/cpa-status` — show every account's status (including how many image / video models were recognized).
342
- - `/cpa-refresh` — refresh every account now, including a catalog probe of disabled ones.
343
- - `/cpa-image [-m model] [--aspect ratio] [-n 1-4] prompt` — generate images; with attached images, edit them. See [Generating images](#generating-images-cpa-image).
344
- - `/cpa-video [-m model] [--aspect ratio] [-s 1-15] [-r 480p|720p] prompt` — generate a video; attach one image as the first frame. A submitted video cannot be cancelled. See [Generating videos](#generating-videos-cpa-video).
345
- - `/cpa-video-status` — list this session's video jobs.
346
- - `/cpa-video-edit [--video path | --url link | --from command-id] [-m model] change` / `/cpa-video-extend [same] [-s 2-10] what happens next` — edit / extend any MP4 (an attached video file works too). See [Editing and extending videos](#editing-and-extending-videos-cpa-video-edit-cpa-video-extend).
347
-
348
- `/cpa-image` and `/cpa-video*` exist only while **Enable image and video generation** is on in the Generation tab.
349
-
350
- ### HTTP API
351
-
352
- Used by the settings panel. Requires the DSH Web session's authentication; POST accepts only same-origin requests from loopback or trusted hosts.
353
-
354
- | Method | Path | Body | Meaning |
355
- |---|---|---|---|
356
- | GET | `/api/dsh-cliproxyapi/status` | — | `{ ok, global, accounts[] }` |
357
- | POST | `/api/dsh-cliproxyapi/refresh` | `{ accountId? }` | Refresh one or all accounts |
358
- | 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 |
359
- | POST | `/api/dsh-cliproxyapi/accounts/add` | Optional account fields | Create a disabled account; returns `createdId` |
360
- | POST | `/api/dsh-cliproxyapi/accounts/remove` | `{ accountId }` | Delete an account and its routes |
361
- | POST | `/api/dsh-cliproxyapi/accounts/test` | `{ accountId?, baseURL?, apiKey? }` | Test unsaved connection values without saving or writing routes; a blank `apiKey` uses the account's stored key; never returns the key |
362
- | GET | `/api/dsh-cliproxyapi/updates/status` | — | Read update state without contacting a registry |
363
- | POST | `/api/dsh-cliproxyapi/updates/check` | `{}` | Check the selected channel and region now; a manual check does not trigger automatic downloading |
364
- | POST | `/api/dsh-cliproxyapi/updates/save` | `{ autoCheck?, autoDownload?, autoInstall?, channel?, region? }` | Save only these five update preferences, independently of accounts |
365
- | POST | `/api/dsh-cliproxyapi/updates/download` | `{ version }` | Download the newer version confirmed by the latest check, verify it, and save an offline package without installing |
366
- | GET | `/api/dsh-cliproxyapi/quota/status` | — | `{ ok, quota }`: the cached quota snapshot; stale accounts refresh in the background |
367
- | POST | `/api/dsh-cliproxyapi/quota/refresh` | `{ accountId? }` | Start refreshing the quota of one or every account and return at once (`refreshing` is set in the snapshot) |
368
- | POST | `/api/dsh-cliproxyapi/quota/save` | `{ accountId, managementKey?, clear? }` | Store or clear the account's management key and start refreshing its quota; the response never contains the key |
369
- | GET | `/api/dsh-cliproxyapi/media/status` | — | `{ ok, media }`: generation settings and each account's recognized image / video models; no network access |
370
- | POST | `/api/dsh-cliproxyapi/media/save` | `{ enabled? }`, global fields (such as `agentTool`, `outputDir`), or `{ account: { accountId, disabledModels?, kindOverrides? } }` | `enabled` switches generation on / off (registering or removing the generation commands and the agent tool at once); save an account's switched-off media models (replaces the list) or kind overrides (merged per model; `null` restores detection); a kind change re-synchronizes that account and adds `status` to the response. Invalid values return 400 with a code such as `invalid-enabled`, `invalid-account` or `invalid-kind` |
371
- | POST | `/api/dsh-cliproxyapi/media/diagnose` | `{ accountId }` | Read-only diagnostic (see above); returns `{ ok, diagnostic }` without the key |
372
- | GET | `/api/dsh-cliproxyapi/media/session?sessionId=` | — | `{ ok, session }`: the image / video models to choose from, the current pick and where it comes from (`session` / `last` / `only`), and this session's recent files (names and ids only, no paths); `pendingConfirmations` lists only compatibility requests owned by this exact session when the native question service is absent, as `{ commandId, kind, en, zh, expiresAt }`; native questions never appear in that list; no network access |
373
- | POST | `/api/dsh-cliproxyapi/media/session/save` | `{ sessionId?, kind: "image" \| "video", ref }` | Pick a session's model (`ref` is `accountId/modelId`; `null` clears the session's pick) and remember it as the last pick; a model that is not offered returns 400 `invalid-model`. Alternatively `{ sessionId, videoConfirm?, imageConfirm?, videoBudget? }` (`ask` / `auto` / `inherit`; the limit is `{ mode: "limited", seconds }` / `{ mode: "unlimited" }` / `inherit`) sets this session's agent-generation rules |
374
- | POST | `/api/dsh-cliproxyapi/media/confirm` | `{ sessionId, commandId, allow }` | Answer only a compatibility `generate_media` confirmation beside the composer when the native question service is absent (reads `media/session` every 2 s); not used for native questions and independent of execution-approval permissions. Only the confirmation's exact owning root session can answer; an answered or expired request returns 400 `confirm-expired` |
375
- | GET | `/api/dsh-cliproxyapi/media/file?sessionId=&id=` | — | Serves a generated file the plugin recorded for that session; anything else, or another session, gets 404. Videos are streamed with single `Range` support (206) so players can seek |
376
- | GET | `/api/dsh-cliproxyapi/media/command?sessionId=&commandId=` | — | `{ ok, run, files }`: one command run's record in that session (status `running` / `done` / `error`, model, prompt, ratio, count, number of references, start and end times, a display name for the save folder, error code and summary) and the files it produced (id, name and full path, plus the save folder `folderPath` and the Host's file manager kind `desktop`: `explorer` / `finder` / `filemanager`), so its row in the conversation can show and open them; video records also carry length, resolution, request id, the `mode` (`text` / `first-frame` / `reference` / `first-last` / `last-frame` / `edit` / `extend`) and the source command id, plus `actions: { edit, extend, expiresAt }` (never the link) while it can still be edited or extended; and while running the `phase` (`submitting` / `queued` / `running` / `downloading`) and CPA's `progress`; a run recorded as running that no background job owns (after a reload or crash) is reported as `interrupted` |
377
-
378
- Update operation responses use `{ ok, update }`. State includes `currentVersion`, `latestVersion`, `available`, `channel`, `region`, `effectiveRegion`, `autoCheck`, `autoDownload`, `autoInstall`, `checking`, `downloading`, `lastCheckedAt`, `error` / `errorCode`, `blockedReason`, `downloadedVersion`, `downloadPath` and `upgradeCommand`. Fields without a check or download result are `null`. `channel` is `stable` / `beta` / `dev`; `region` is `auto` / `global` / `cn`; `effectiveRegion` is the `global` / `cn` source used by the last successful check (`null` before one).
379
-
380
- Failures use a top-level `errorCode` or `update.errorCode`; HTTP status or `ok` alone does not establish success. Common codes include `network-error`, `invalid-metadata`, `channel-unavailable`, `integrity-error`, `invalid-package`, `storage-error`, `busy`, `stale-version`, `service-unavailable`, `forbidden-origin` and `disposed`. Update POSTs still rely on the host's session authentication and trusted-host policy: when a request carries `Origin`, it must belong to the same authority as this listener (host and port compared under the Origin's own scheme, matching the host's own rule), otherwise the response is `forbidden-origin`. The desktop carrier may proxy API calls without an `Origin`; such a request is allowed once the host session authenticates it, while unauthenticated callers are still rejected before reaching the route. Plain unauthenticated `curl` cannot call these endpoints.
381
-
382
- ## Storage and configuration
383
-
384
- - **State file**: `<profile dir>/.dsh-cliproxyapi/state.json` holds accounts, selections and overrides (no keys).
385
-
386
- ```json
387
- {
388
- "version": 2,
389
- "refreshIntervalSeconds": 300,
390
- "probeTimeoutMs": 5000,
391
- "accounts": [
392
- {
393
- "id": "default", "enabled": true, "provider": "cli-proxy", "displayName": "CLI Proxy API",
394
- "baseURL": "https://cpa.example.com", "apiKeyEnv": "CLI_PROXY_API_KEY",
395
- "protocol": "openai-completions", "protocolMode": "auto",
396
- "includePrefix": "", "excludePrefix": "", "selectedModels": ["gpt-6.1-sol"], "modelOverrides": {}
397
- }
398
- ]
399
- }
400
- ```
401
-
402
- The file is re-read on every access; after a manual edit, click **Probe & Refresh** in the account's **⋯** menu. 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`.
403
-
404
- - **Update settings**: stored separately at `<profile dir>/.dsh-cliproxyapi/update-settings.json`. They neither extend nor rewrite the account `state.json` v2 file, nor access credentials. When this file does not yet exist, defaults are:
405
-
406
- ```json
407
- {
408
- "version": 1,
409
- "autoCheck": true,
410
- "autoDownload": false,
411
- "autoInstall": false,
412
- "channel": "stable",
413
- "region": "auto"
414
- }
415
- ```
416
-
417
- Panel saves take effect immediately. After editing this file manually, reload the plugin or restart DSH to re-read it. Corrupt, structurally invalid, invalid-field or unreadable files use safe defaults with automatic network checks disabled. Check results, the candidate version, download notices and commands are in-memory only and reset on plugin reload; downloaded packages remain in the separate `updates` subdirectory for you to clean up when needed.
418
- - **Generation settings**: stored separately at `<profile dir>/.dsh-cliproxyapi/media-settings.json`; `state.json` is not changed. Without this file the defaults apply (`enabled: false`, generation off; but on when `media-sessions.json` or `media-jobs.json` exists); a file without the `enabled` field (written before the master switch existed) reads as on. A damaged file also falls back to the defaults with a log warning, and the next save first keeps the damaged file as `media-settings.corrupt-<time>.json`. The fields: `enabled` (master switch), `agentTool` (agent generation tool), `outputDir` (save location), `defaultVideoSeconds` / `defaultVideoResolution` (video defaults), `imageConfirm` / `videoConfirm` / `videoBudget` (agent confirmation and seconds limit), `lastSelection` (the last picked models), and each account's `disabledModels` (switched-off media models) and `kindOverrides` (kinds you set):
419
-
420
- ```json
421
- {
422
- "version": 1,
423
- "enabled": true,
424
- "agentTool": false,
425
- "outputDir": "generated",
426
- "defaultVideoSeconds": 6,
427
- "defaultVideoResolution": "720p",
428
- "imageConfirm": "auto",
429
- "videoConfirm": "ask",
430
- "videoBudget": { "mode": "limited", "seconds": 60 },
431
- "lastSelection": {},
432
- "accounts": {
433
- "default": { "disabledModels": [], "kindOverrides": { "my-painter": "image" } }
434
- }
435
- }
436
- ```
437
-
438
- - **Per-session generation records**: `<profile dir>/.dsh-cliproxyapi/media-sessions.json` keeps each session's picked generation models, records of its last 48 runs (status, model, prompt, options, start and end times, a display name for the save folder, error summary), and the paths of its last 48 generated files with the command id that produced them (for the command rows in the conversation), for the 500 most recently updated sessions. Deleting it only clears those picks and records, never generated files. A damaged file is treated as empty and kept as `media-sessions.corrupt-<time>.json` before the next write.
439
- - **Video jobs**: `<profile dir>/.dsh-cliproxyapi/media-jobs.json` keeps submitted video jobs (CPA request id, account, model, session and command id, working directory and save location, prompt, length, submission time, state) so a reload or restart can keep waiting; at most 200, finished ones kept 7 days. No keys and no video URLs. A damaged file is treated as empty and kept as `media-jobs.corrupt-<time>.json` before the next write.
440
- - **Management key failures**: `<profile dir>/.dsh-cliproxyapi/quota-state.json` records, per account, how many times in a row the CPA management API rejected the key (401/403), the last error code and time, so automatic checks stop after 3; it never holds the key. Deleting it only resets the counts.
441
- - **Keys**: stored and resolved by ref through the DSH `credentials` service, falling back to an environment variable of the same name.
442
- - **Environment**: `CLIPROXYAPI_BASE_URL` is used only for auto-discovery of accounts without a base URL.
443
- - **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 Settings panel.
444
-
445
- ## Upgrading and uninstalling
446
-
447
- - **Upgrade**: with dshmarket installed, click **Update Now** on the plugin update card (or enable automatic installation), then restart DSH or refresh the page as prompted. Without the market, download a verified offline package through the card, save your work and close DSH, run the displayed `dsh plugin --profile 'name' add 'absolute-package-path'` command, then restart. There is no need to uninstall first. Alternatively, with DSH closed, run `dsh plugin --profile <profile name> add dsh-cliproxyapi-pro@latest` to upgrade from npm. Accounts, selections and parameters remain in the profile directory, and keys in the credentials service; the updater never rewrites them. To preserve a linked source installation, update its source yourself rather than reinstalling from an offline package.
448
- - **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.
449
-
450
- ## FAQ
451
-
452
- **No models in the model picker?**
453
- Check that the **Enabled** switch next to the account title is on and at least one model checked (or an empty selection, meaning all). Run `/cpa-status` to see every account's state.
454
-
455
- **"none of the selected models matched"?**
456
- 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.
457
-
458
- **Connection failed / "no usable CPA service found"?**
459
- 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.
460
-
461
- **A just-published version won't install?**
462
- 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.
463
-
464
- **How do I install updates automatically?**
465
- Install and enable the [DSH plugin market (dshmarket)](https://github.com/dsh-market/dsh-market), then turn on **Automatically Check for Updates** and **Automatically Install Updates** on the plugin update card. The market performs the installation (package manager, version verification and recovery); this plugin itself never runs a package manager, overwrites files or restarts DSH. Without the market it can only prepare an offline package for an upgrade with DSH closed.
466
-
467
- **"Check for Updates" fails immediately (especially on the desktop app)?**
468
- Versions 1.5.1 and earlier required an `Origin` header on update POSTs, but the DSH desktop app strips that header when it forwards page requests, so checks, update-setting saves and downloads were all refused. Since 1.6.0 the plugin follows the host's own rule: without `Origin` the host session authentication decides; with `Origin` it must still be same-origin. Upgrade older versions through the plugin market, the plugin manager or the offline path.
469
-
470
- **No release available on Beta / Dev?**
471
- A channel is usable only after the maintainer publishes its npm dist-tag. Stable is never presented as an unpublished Beta / Dev build. A channel version no newer than the running version does not offer a downgrade download either.
472
-
473
- **The update card says "update service unavailable" or "network error"?**
474
- The collapsed row names the actual cause. **Update service unavailable** means the page runs newer client code than the running host plugin: after installing or upgrading, **restart DSH** (refreshing the page or reloading the plugin is not enough). **Network error** means requests to npmjs or the Mainland China mirror failed; switch the download region and check proxies/firewalls. **Channel unpublished** means that channel has no matching release yet. Expand the card for the matching explanation.
475
-
476
- **Downloaded the update and restarted, but the version did not change?**
477
- Downloading and verification do not install anything. Exit DSH, run the card's upgrade command, then start it again. Linked installations do not receive that command; update their source manually to keep the link. If a plugin reload clears the download notice, the offline file remains in the profile's `updates` directory.
478
-
479
- ## AI installation guide
480
-
481
- > **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.
482
-
483
- 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.
484
- 2. **Configure**: the user configures accounts in the UI (this plugin has no agent tool for account management). A local CPA on `http://127.0.0.1:8317` without auth needs nothing — it is discovered automatically once the plugin runs. Otherwise ask the user to open the **CLIProxyAPI** page in the Settings dialog's left navigation, click **+ Add Account**, enter the server URL and API key, then check the wanted models on the **Models** tab.
485
- 3. **Verify**: ask the user to run `/cpa-status`; each enabled account should be `connected` with more than 0 models. Tell the user the models are in the DSH model picker under the account's name.
486
-
487
- Never ask the user for an API key or write it into files; keys are entered only on the Settings page.
488
-
489
- ## Development
490
-
491
- ```text
492
- lib/index.js Host plugin (discovery, sync, multi-account controller, tool, commands, HTTP API)
493
- lib/client.js Web UI (ModuleLoader: account page in Settings, update card on the plugin pages, no build)
494
- lib/updater.js Update settings, SemVer/channels, region race, SHA-512/package checks, offline storage
495
- locale/*.json Title and description shown by the plugin manager
496
- cordis.patch.yml Bundle patch inserting the dsh-cliproxyapi-pro row
497
- tests/ node:test unit and integration tests
498
- .github/workflows/ CI (tests) and release (GitHub Release + npm trusted publishing)
499
- assets/screenshots/ README screenshots (listed in screenshots.json for plugin storefronts)
500
- AGENTS.md Conventions, architecture and invariants for coding agents
501
- ```
502
-
503
- ```bash
504
- git clone https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro.git
505
- cd dsh-cliproxyapi-pro
506
- npm test # run the tests
507
- npm run check # syntax check + tests
508
- npm run pack:check # list the files a packed bundle contains
509
- ```
510
-
511
- `npm run check` syntax-checks all three `lib/*.js` modules and runs every test. Offline update tests are `tests/updater.test.mjs` (settings, SemVer, regions, download integrity and package structure), `tests/update-routes.test.mjs` (HTTP authentication and same-origin policy), and `tests/client.test.mjs` (the update card and request lifecycle). They never access the real network or profile. `npm run pack:check` should include `lib/updater.js`, but not tests or screenshots; no runtime dependencies need installing.
512
-
513
- 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. Stable releases publish to npm `latest`; Beta / Dev prereleases publish to `beta` / `dev` and are marked as GitHub prereleases, without replacing the stable channel. The updater checks registry-provided SHA-512 integrity and package structure only; it does not verify publisher signatures or npm provenance.
514
-
515
- Read [AGENTS.md](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/blob/main/AGENTS.md) before changing code; see [CHANGELOG.en.md](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/blob/main/CHANGELOG.en.md) for history (Chinese: [CHANGELOG.md](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/blob/main/CHANGELOG.md)). Issues and pull requests are welcome — when you change the documentation, update both the Chinese and the English README.
120
+ ## Documentation
121
+
122
+ - [Accounts and models](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/blob/main/docs/en/accounts-and-models.md)
123
+ - [Channel quota](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/blob/main/docs/en/quota.md)
124
+ - [Images and videos](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/blob/main/docs/en/media.md)
125
+ - [Updating this plugin](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/blob/main/docs/en/updates.md)
126
+ - [Slash commands and HTTP routes](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/blob/main/docs/en/reference.md)
127
+ - [Storage and configuration](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/blob/main/docs/en/storage-and-config.md)
128
+ - [Upgrading and uninstalling](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/blob/main/docs/en/upgrade-and-uninstall.md)
129
+ - [FAQ](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/blob/main/docs/en/faq.md)
130
+ - [AI installation guide](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/blob/main/docs/en/ai-install-guide.md)
131
+ - [Development](https://github.com/TinyBOOOOM/dsh-cliproxyapi-pro/blob/main/docs/en/development.md)
516
132
 
517
133
  ## License
518
134