npm - @mars-sea/dsh-commandcode-provider - Versions diffs - 0.6.1 → 0.6.2 - Mend

@mars-sea/dsh-commandcode-provider 0.6.1 → 0.6.2

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 (9) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -4,6 +4,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [0.6.2] - 2026-08-21
+### Added
+- **Stored API keys can now be cleared, not just replaced.** A "Clear stored key" action on the default key and on every account stages a removal (with a visible "will be cleared on save" badge and an undo); saving unsets the credential through the Host's `credentials.unset`, so the account reports unconfigured again and falls back to its other key sources. Previously a bad key could only be overwritten, never removed.
+### Changed
+- **Free models now lead the model picker.** Models whose deals mark them free (currently Ox Alpha and Laguna S 2.1) sort ahead of every paid tier — they cost no credits and work on any account, so they make the best defaults. The rest of the order is unchanged: Go → GOAT → Pro → Provider/Max, alphabetical within each tier.
+### Fixed
+- **An invalid or expired API key no longer hides behind "Some endpoint data unavailable".** When every account endpoint rejects with 401 (wrong/expired key), the usage card now shows a prominent "API key invalid or expired" banner with an actionable hint instead of the generic partial-data note; a total 5xx or network outage gets their own distinct banners too. The `/commandcode` command surfaces the same cause up front. Partial failures keep the existing degraded view.
+- **Retry and credential failure messages are now bilingual (English + 中文).** The harness UI renders these messages verbatim inside its retry/turn-error chrome, so the "all accounts exhausted" rate-limit error, the all-401 credential error, and the single-account 401 error now carry both readings in one string — no more parsing an English-only wall of text to learn when your window resets.
 ## [0.6.1] - 2026-08-22
 ### Added

package/README.md CHANGED Viewed

@@ -10,145 +10,67 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![npm](https://img.shields.io/badge/npm-@mars--sea%2Fdsh--commandcode--provider-blue.svg)](https://www.npmjs.com/package/@mars-sea/dsh-commandcode-provider)
-Unofficial [DeepSeek Harness](https://deepseek-harness.github.io/deepseek-harness/) LLM provider plugin for **Command Code**, ported from [pi-commandcode-provider](https://github.com/patlux/pi-commandcode-provider) (MIT). It registers a `commandcode` provider whose requests are translated to Command Code's Provider API (`POST /alpha/generate`, reverse-engineered by the pi plugin, `command-code@1.28.4`).
+Unofficial [DeepSeek Harness](https://deepseek-harness.github.io/deepseek-harness/) LLM provider plugin for **Command Code**, ported from [pi-commandcode-provider](https://github.com/patlux/pi-commandcode-provider) (MIT).
 > This is a community integration. You need your own Command Code account and API key or subscription, and Command Code's terms apply. This project is not affiliated with Command Code, Inc.
 ## What you get
-- **Plugin bundle** installable into any dsh profile with `dsh plugin add`, plus a **`commandcode` provider route** with a live catalog (`GET {apiBase}/provider/v1/models`, cached at `~/.commandcode/models-cache.json`).
-- **Dedicated "Command Code" settings page** (Settings → **Command Code**) with an **API-key field**, connection knobs (API base, working directory, request/stream timeouts), a **live "Account usage" card** (stats, credits, window-limit bars, subscription plan badge) and a **Hide out-of-plan models** toggle. The key is stored through the dsh credentials service; connection fields land in the `llm-commandcode` section and apply to the very next request, no restart.
-- **Multi-account rotation**: when one account's usage window (e.g. the Go plan's 5-hour limit) is exhausted, requests **seamlessly switch to the next account** — passive switching on 429/401, invisible to the model (the request body is account-independent and `threadId` is random per request); when every account is exhausted the error names **the earliest window reset**. The settings page's **Account rotation** card adds/labels/removes accounts, and `/commandcode` plus the usage card report per-account state. See [Account rotation](#account-rotation).
-- **API key resolution order**: `config.apiKey` → credential ref `apiKeyEnv` (default `COMMANDCODE_API_KEY`) → launch environment → the official CLI auth file (`~/.commandcode/auth.json`, from `command-code login`).
-- **Model-picker annotations**: every model shows the **minimum plan** that includes it (`KNOWN_PLANS`), an **active deal** or `FREE` badge (`KNOWN_DEALS`, expiry-aware so lapsed discounts hide themselves), the **current peak/off-peak state** (`Peak`/`Half`) for time-of-day-priced models, an **`Image`** marker for Vision models, and the **context window** (`1M` / `256K` / `262K`) — e.g. *"Go · 50% off · Image · 1M"*, *"Go · Half · 1M"*. The list is **sorted by plan tier** (Go → GOAT → Pro → Provider/Max), so the models your plan can use lead the picker.
-- **Plan-aware picker filtering**: the picker **hides models above your subscription tier** outright (resolved live from your account's billing state). It fails open — an unreachable billing endpoint, an unknown plan, or a positive on-demand credit balance (which the official CLI treats as unlocking every model) all keep the full catalog visible — and the server stays the final gate. Set **Hide out-of-plan models** off on the settings page (or `filterModelsByPlan: false` in the `llm-commandcode` settings section) to always list every model.
-- **Reasoning-effort support** for models the official catalog marks as such (`KNOWN_EFFORTS`, matching `command-code@1.28.4`); reasoning models without effort levels still think automatically, exactly like the official CLI.
-- **Image input for Vision-capable models** (sent in the official wire format via the dsh attachment service); text-only models refuse images loudly (`UNSUPPORTED_CONTENT`) rather than dropping them.
+- **Plugin bundle** — install into any dsh profile with `dsh plugin add`; registers a `commandcode` provider route with a live model catalog.
+- **Dedicated settings page** — API key, connection options, a live account-usage card, and a "Hide out-of-plan models" toggle.
+- **Multi-account rotation** — when one account hits its usage limit, requests switch to the next account automatically. See [Account rotation](#account-rotation).
+- **Flexible API key setup** — via the settings page, an environment variable, or the official CLI login file.
+- **Model-picker annotations** — minimum plan, active deal or `FREE` badge, peak/off-peak state, image support, and context window; free models listed first.
+- **Plan-aware picker** — models above your subscription tier are hidden by default (toggleable).
+- **Reasoning-effort support** — models with selectable reasoning effort levels expose them in the picker.
+- **Image input** — Vision-capable models accept images.
-<img src="assets/screenshots/model-picker.png" alt="Model picker with plan, deal, image and context annotations" width="250">
-## Getting an API key
-Command Code API keys never expire. The easiest path is the official CLI (Node.js 22+):
-```sh
-npm i -g command-code@latest
-cmd login        # macOS/Linux; native Windows: cmdc login
-```
-`cmd login` opens a browser to authenticate; the key is written to `~/.commandcode/auth.json` — picked up automatically as a last-resort fallback. Alternatively create a key in the browser ([Command Code Studio](https://commandcode.ai/studio/auth/cli)) and paste it into **Settings → Command Code**, or `export COMMANDCODE_API_KEY="user_..."`.
+See [Screenshots](#screenshots) below for what the UI looks like.
 ## Install
-### From npm (recommended)
-The bare name `dsh-commandcode-provider` is taken by an unrelated package, so this plugin is published as **`@mars-sea/dsh-commandcode-provider`**:
 ```sh
-dsh plugin --profile web add @mars-sea/dsh-commandcode-provider
+dsh plugin --profile web add @mars-sea/dsh-commandcode-provider@latest
 ```
-### From GitHub
-```sh
-# Pin a release tag (recommended — readable and immutable)
-dsh plugin --profile web add github:Mars-Sea/dsh-commandcode-provider#v0.2.2
-# Or pin any exact commit by its SHA
-dsh plugin --profile web add github:Mars-Sea/dsh-commandcode-provider#<full-commit-sha>
-```
-The `#<ref>` suffix pins one exact revision (pnpm git-dependency syntax). Without it the install tracks the default branch, so a later push can silently change what you get.
-A git install fetches **sources**, so the package's `prepare` script builds `lib/` after install. pnpm ≥10 blocks that script by default — run the `add`, then copy the **exact package key pnpm prints** into `~/.dsh/profiles/web/pnpm-workspace.yaml`:
-```yaml
-allowBuilds:
-  '@mars-sea/dsh-commandcode-provider@github:Mars-Sea/dsh-commandcode-provider#<full-commit-sha>': true
-```
-and re-run the `add`.
-### From a local checkout
+## Updating
 ```sh
-npm install
-npm run build                          # git/tarball installs do this via `prepare` automatically
-dsh plugin --profile web add /path/to/dsh-commandcode-provider
+dsh plugin --profile web add @mars-sea/dsh-commandcode-provider@latest
 ```
-After changing `src/`, re-run `npm run build` and restart the app.
-### What the install does
-`dsh plugin add` links the package into the profile (pnpm records it under the **true package name** `@mars-sea/dsh-commandcode-provider`), appends that name to `dsh.profile.bundles`, and activates the `cordis.patch.yml` layer:
-```yaml
-- insert:
-    - id: llm-commandcode
-      name: "@mars-sea/dsh-commandcode-provider"
-      config:
-        apiKeyEnv: COMMANDCODE_API_KEY
-```
-The patch `name` must be the **full package specifier, quoted** — the loader imports it as a module from the profile's `node_modules`, where pnpm only links the scoped name. A bare name fails with `ERR_MODULE_NOT_FOUND` and crashes the app on boot; an unquoted `@mars-sea/...` fails YAML parsing (see [Troubleshooting](#troubleshooting)).
-Verify the composed layer, then (re)start the web app:
-```sh
-dsh --profile web --dump-config          # shows a "# == @mars-sea/dsh-commandcode-provider" layer
-dsh web                                  # or restart your running instance
-```
+Then restart the web app.
-## Updating
+## Getting an API key
-The patch layer is read from the **installed package** at every boot, so updating the package brings the fixed row automatically — no need to hand-edit `cordis.patch.yml` unless you copied it into your own profile layer.
+The easiest path is the official CLI (Node.js 22+):
 ```sh
-# npm: always the latest published release
-dsh plugin --profile web update @mars-sea/dsh-commandcode-provider
-# GitHub (pinned): point at the new tag — no uninstall needed, pnpm swaps it in place
-dsh plugin --profile web add github:Mars-Sea/dsh-commandcode-provider#v0.2.2
-# local checkout: pull, rebuild, restart
-git -C /path/to/dsh-commandcode-provider pull
-npm run build --prefix /path/to/dsh-commandcode-provider
-dsh web
+npm i -g command-code@latest
+cmd login        # macOS/Linux; native Windows: cmdc login
 ```
-Then restart the web app. Verify with `dsh --profile web --dump-config` — the layer should show `name: '@mars-sea/dsh-commandcode-provider'`.
-> **`update` says "Already up to date" but the version did not move (pnpm ≥ 11)?** pnpm 11's `minimumReleaseAge` supply-chain policy can refuse a freshly published version. Pin the exact version instead: `dsh plugin --profile web add @mars-sea/dsh-commandcode-provider@0.2.2` (or `pnpm config set minimumReleaseAge 0 --location project` inside the profile directory).
-> **Upgrading from ≤0.1.6** (or a broken hand-edited profile): if you *copied* the old patch row into your profile's own `cordis.patch.yml`, that copy still wins over the bundle layer — fix it to `name: "@mars-sea/dsh-commandcode-provider"` or remove it (see [Troubleshooting](#troubleshooting)).
-> **To uninstall instead**: `dsh plugin --profile web remove @mars-sea/dsh-commandcode-provider` (the **scoped** name — pnpm records the dependency under its real name). Your API key in the dsh credential store and `~/.commandcode/auth.json` are left untouched.
+Alternatively, create a key in the browser ([Command Code Studio](https://commandcode.ai/studio/auth/cli)) and paste it into **Settings → Command Code**, or `export COMMANDCODE_API_KEY="user_..."`.
 ## Verify it works
-After restart: **Settings → Command Code** shows the dedicated page — enter your API key and click **Save** (the badge flips to 已配置/Configured once the Host holds it). **Settings → Models** shows a **Command Code** card; the model picker lists the live catalog under **commandcode**. Send a message with a model your plan includes — `deepseek/deepseek-v4-flash` works on entry-level plans, and open-weight models (DeepSeek/Qwen/Kimi/MiniMax) generally do, while frontier models (Claude/GPT/Gemini/Grok) may require Pro/Max plans or on-demand usage.
+After restart, enter your API key in **Settings → Command Code** and save; **Settings → Models** shows a **Command Code** card, and the model picker lists the live catalog under **commandcode**. Send a message with a model your plan includes.
 ## Usage dashboard
-The plugin registers a `/commandcode` slash command (requires the dsh `commands` service, present in the standard web profile) showing your account state from the official account endpoints:
+The plugin registers a `/commandcode` slash command showing per-account usage:
 ```text
 /commandcode        (or /commandcode status)
 ```
-![Usage dashboard](assets/screenshots/usage-dashboard.png)
-Each endpoint degrades independently — a temporary failure of one leaves the rest visible and notes the failure inline.
 ## Account rotation
 With several Command Code subscriptions, the plugin **switches to the next account automatically** when one hits its usage limit:
-- **Passive switching, zero extra cost**: rotation happens only when a request is actually rejected pre-stream — a 429 (window exhausted) marks the account exhausted, a 401 marks its key disabled, and the adapter immediately re-sends the same request with the next account's key (the request body is account-independent and `threadId` is random per request, so the switch is invisible to the model).
-- **Precise revival**: once every account is marked, the plugin probes each key's real five-hour window via `/alpha/billing/credits` — accounts whose window already reset come back immediately; if all are still exhausted the request fails with a `RATE_LIMIT` error naming **the earliest reset time** (all-401 throws `INVALID_CREDENTIAL`).
-- **Configuration surface**: the **Account rotation** card at Settings → **Command Code** — **Add account**, then give each a label and API key (every key is stored through the credentials service under its own reference `COMMANDCODE_API_KEY_2`, …, write-only like the default key). The top-level key always serves first as the `default` account.
-- **Manual switching**: the **Active account** dropdown on the same card pins the preferred account (persisted as the `activeAccount` setting) — effective on the next request after saving. If the pinned account is exhausted, requests still rotate to another usable account, and once its window resets the pinned account serves again.
-- **Per-account reporting**: the settings page's **Account usage** card renders one section per account with **Active / Cooling down / Invalid key** badges; `/commandcode` prints one dashboard section per account.
+- **Setup** — use the **Account rotation** card at Settings → **Command Code** to add accounts with a label and API key; the top-level key always serves first as the `default` account.
+- **Manual switching** — the **Active account** dropdown pins a preferred account; if it is exhausted, requests fall back to other accounts and return once its window resets.
+- **Status** — the **Account usage** card and `/commandcode` report per-account state.
 The equivalent YAML (`$DSH_HOME/settings.yaml` or composition config):
@@ -163,53 +85,33 @@ llm-commandcode:
       apiKeyEnv: COMMANDCODE_API_KEY_3
 ```
-Each account may also carry a literal `apiKey` in composition config (winning over its `apiKeyEnv`); key literals are never stored in the settings document.
 ## Configure
-**Settings → Command Code** is the primary surface: an **API-key** field (stored in `$DSH_HOME/.credentials.yaml` via the credentials service; write-only, reports whether a key is set), plus **API base URL**, **working directory**, and **request/stream timeout** fields, all written to the `llm-commandcode` section. The catalog is browsable without a key. The **working directory** is optional — leave it blank and the placeholder shows the process cwd it resolves to.
+**Settings → Command Code** covers the API key, API base URL, working directory, and request/stream timeouts; once a key is saved, a live **Account usage** card appears at the top of the page.
-Once a key is configured, the page header shows a live **Account usage** card — the same account, spend, credit, and window-limit facts as `/commandcode`, plus your subscription plan badge and billing period end — fetched Host-side (the key never leaves it) and rendered natively:
-<img src="assets/screenshots/settings-page.png" alt="Command Code settings page with the account usage card" width="640">
-The same knobs live in `$DSH_HOME/settings.yaml` (per-request overrides, no restart):
+The same options live in `$DSH_HOME/settings.yaml` (changes apply immediately, no restart):
 ```yaml
 llm-commandcode:
-  apiKeyEnv: COMMANDCODE_API_KEY   # credential reference resolved per request
+  apiKeyEnv: COMMANDCODE_API_KEY   # credential reference
   apiBase: https://api.commandcode.ai
-  workingDir: /path/to/project     # reported to the API (project slug, config block)
+  workingDir: /path/to/project     # optional
   modelsCachePath: ~/.commandcode/models-cache.json
-  requestTimeoutMs: 60000          # max wait for the first response byte (default 60s)
-  streamIdleTimeoutMs: 300000      # stream stall before treated as dead (default 300s — generous, so long-thinking models are not cut off)
+  requestTimeoutMs: 60000          # default 60s
+  streamIdleTimeoutMs: 300000      # default 300s
 ```
-The composition-entry config (`cordis.patch.yml`) accepts the same keys; a literal `apiKey` there takes precedence over the credential reference.
-## Troubleshooting
-- **`Command Code API request to .../alpha/generate failed` with retries** — a **transport-layer failure**: `fetch()` never got an HTTP response (a 401/403/429 would say "API error"). Since 0.1.8 the message names the real root cause (`ECONNREFUSED`, `ENOTFOUND`, `CERT_HAS_EXPIRED`, `socket hang up`, …). Common causes: **a required proxy** (Node's `fetch`/undici ignores `HTTP_PROXY`/`HTTPS_PROXY` — configure a dispatcher or whitelist `api.commandcode.ai`), **connection reset/throttled** (firewall, GFW-style interference, unstable Wi-Fi), **TLS interception** (corporate MITM), or a transient blip retry recovers from.
-- **A long generation stops mid-stream** — since 0.1.8 the adapter aborts after `requestTimeoutMs` (60s) with no first byte, and treats a stream stalling past `streamIdleTimeoutMs` (300s by default) as dead. Both surface as `TIMEOUT` with the stall duration; tune the knobs for slow-but-stable networks.
-- **"Reconnects" when a reasoning model thinks for a long time** — the stream idle watchdog used to default to 120s, which is shorter than a frontier reasoning model's silent thinking phase (xhigh/max effort can stay quiet for minutes, and the official CLI sets no idle cap at all). Since 0.2.3 the default is **300s**; if you still hit spurious timeouts on very long thinking, raise `streamIdleTimeoutMs` in the `llm-commandcode` section or on the settings page.
-- **Boot crash: `ERR_MODULE_NOT_FOUND: Cannot find package 'dsh-commandcode-provider'`** — the patch row's `name` is the bare name, but pnpm only links the scoped name. Fix the row to `name: "@mars-sea/dsh-commandcode-provider"` — note the **quotes** (an unquoted `@`-prefixed scalar fails YAML parsing) — then restart.
-- **`MODEL_NOT_IN_PLAN` (403)** — the model isn't in your plan. Pick an open-weight model or upgrade; the error names the model and links the docs.
-- **`MISSING_CREDENTIAL`** — no key anywhere. Store one via the settings page, `export COMMANDCODE_API_KEY`, set `config.apiKey`, or run `command-code login`. The route and catalog stay browsable without a key.
-- **Models card shows "not configured" but requests work** — the key came from `~/.commandcode/auth.json` (the `cmd login` fallback), not the credential store. Paste it into the card once; both coexist fine.
-- **A reasoning model returns no visible text on short requests** — it consumes output tokens on reasoning first; a small `maxTokens` can be exhausted before visible text. Normal.
-- **`allowBuilds` errors on `dsh plugin add` from git** — copy the exact package key pnpm printed into `pnpm-workspace.yaml` and re-run (see [Install](#from-github)).
 ## Notes & limitations
-- **Image input is model-gated**: only models the official registry lists with Vision accept images (see `KNOWN_IMAGE_MODELS` in `src/adapter.ts`). Text-only models throw `UNSUPPORTED_CONTENT`; Command Code's own CLI's client-side *VISION* fallback is **not** reproduced here — switch to a Vision model instead. Image input also requires the dsh **attachment service**.
-- **Switching to a text-only model in an image-bearing session is rejected by dsh itself** — a harness-level guard (`dsh-host-apiproxy`'s `selectModel`) refuses `model-unavailable` and cannot be relaxed from the plugin side. This bundle makes the message friendlier via its client half: it rewrites the rejection to *"当前会话已包含图片，而模型 \<model\> 不支持图片输入；请选择支持图片的模型，或先移除会话中的图片。"* (the error code and details pass through unchanged). Select a model the picker marks *`Image`*, remove the images first, or use an image-routing bundle (e.g. `@deepseek-ai/dsh-llm-image-routing`).
-- **No `stop` sequences** (the wire format has none): requests carrying one throw `UNSUPPORTED_OPTION`.
-- Reasoning blocks are **not replayed** into later turns (matches the official CLI); only tool calls with a paired tool result are replayed.
-- The catalog endpoint is public; `/alpha/generate` requires your key.
+- **Image input is model-gated** — only Vision models accept images; text-only models refuse them.
+- Switching to a text-only model in an image-bearing session is rejected by dsh — pick a model marked *`Image`* or remove the images first.
+- **No `stop` sequences** — requests carrying one fail.
+- Reasoning blocks are not replayed into later turns; only tool calls with a paired tool result are replayed.
+- The model catalog is browsable without a key; chat requests need one.
 ## Permissions & privacy
-This plugin operates entirely within your dsh profile and your Command Code account. **Local files**: reads `~/.commandcode/auth.json` only as a last-resort key fallback; reads/writes `~/.commandcode/models-cache.json`; reads your key from `$DSH_HOME/.credentials.yaml` via the standard credential seam (never logged). **Network**: `GET {apiBase}/provider/v1/models` (public catalog) and `POST {apiBase}/alpha/generate` (your requests, authenticated), the body including your configured `workingDir`. **No telemetry** — the only outbound host is the Command Code API (`api.commandcode.ai` by default, configurable via `apiBase`).
+The plugin only communicates between your local dsh profile and your Command Code account: locally it touches only the credential store and the models cache (plus `~/.commandcode/auth.json` as a last-resort fallback); on the network it calls only the Command Code API. No telemetry.
 ## Disabling / uninstalling
@@ -220,7 +122,7 @@ This plugin operates entirely within your dsh profile and your Command Code acco
   dsh plugin --profile web remove @mars-sea/dsh-commandcode-provider
   ```
-  This removes the bundle dependency and its layer; your API key in the dsh credential store and `~/.commandcode/auth.json` are left untouched.
+  Your API key in the dsh credential store and `~/.commandcode/auth.json` are left untouched.
 ## Development
@@ -230,6 +132,14 @@ npm run typecheck   # tsc --noEmit
 npm run build       # tsdown -> lib/
 ```
+To try a local build in a profile:
+```sh
+dsh plugin --profile web add /path/to/dsh-commandcode-provider
+```
+After changing `src/`, re-run `npm run build` and restart the app.
 ## Community & feedback
 - <img src="https://cdn.simpleicons.org/github/111827" width="16" alt="GitHub" /> [GitHub Repository](https://github.com/Mars-Sea/dsh-commandcode-provider)
@@ -240,3 +150,17 @@ npm run build       # tsdown -> lib/
 ## License
 MIT — see [LICENSE](./LICENSE). Portions ported from [pi-commandcode-provider](https://github.com/patlux/pi-commandcode-provider) (MIT).
+## Screenshots
+**Model picker** — plan tier, deal/FREE, peak/off-peak, Image and context annotations:
+<img src="assets/screenshots/model-picker.png" alt="Model picker with plan, deal, image and context annotations" width="420">
+**Usage dashboard** — `/commandcode` per-account report:
+![Usage dashboard](assets/screenshots/usage-dashboard.png)
+**Settings page** — API key, connection knobs, account rotation and the live account-usage card:
+<img src="assets/screenshots/settings-page.png" alt="Command Code settings page with the account usage card" width="640">

package/README.zh-CN.md CHANGED Viewed

@@ -10,145 +10,65 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![npm](https://img.shields.io/badge/npm-@mars--sea%2Fdsh--commandcode--provider-blue.svg)](https://www.npmjs.com/package/@mars-sea/dsh-commandcode-provider)
-非官方 [DeepSeek Harness](https://deepseek-harness.github.io/deepseek-harness/) 的 LLM provider 插件，用于 **Command Code**，移植自 [pi-commandcode-provider](https://github.com/patlux/pi-commandcode-provider)（MIT 协议）。它注册了一个 `commandcode` provider，将请求转换为 Command Code 的 Provider API（`POST /alpha/generate`，由 pi 插件逆向工程，对应 `command-code@1.28.4`）。
+非官方 [DeepSeek Harness](https://deepseek-harness.github.io/deepseek-harness/) 的 LLM provider 插件，用于 **Command Code**，移植自 [pi-commandcode-provider](https://github.com/patlux/pi-commandcode-provider)（MIT 协议）。
 > 这是一个社区集成。你需要自己的 Command Code 账号、API key 或订阅，并遵守 Command Code 的服务条款。本项目与 Command Code, Inc. 无关。
 ## 功能一览
-- **插件包**：可通过 `dsh plugin add` 安装到任意 dsh 配置，并提供 **`commandcode` provider 路由**，带实时模型目录（`GET {apiBase}/provider/v1/models`，缓存于 `~/.commandcode/models-cache.json`）。
-- **专属"Command Code"设置页**（设置 → **Command Code**），带 **API key 输入框**、连接参数（API 地址、工作目录、请求/流超时）、**实时「账户用量」卡片**（统计、额度、窗口进度条、订阅套餐徽章）以及**「隐藏套餐外模型」开关**。密钥通过 dsh 凭据服务存储；连接参数写入 `llm-commandcode` 设置段，对下一次请求即刻生效，无需重启。
-- **多账户轮换**：一个账户的用量窗口（如 Go 套餐的 5 小时限额）打满后，请求**无缝切换到下一个账户**——429/401 触发被动切换，请求体与账户无关（`threadId` 每次随机），模型完全无感；全部耗尽时报错并提示**最早的重置时间**。设置页的「多账户轮换」卡片可添加/命名/移除账户，`/commandcode` 与用量卡片按账户分别展示状态。详见[多账户轮换](#多账户轮换)。
-- **API key 解析顺序**：`config.apiKey` → 凭据引用 `apiKeyEnv`（默认 `COMMANDCODE_API_KEY`）→ 启动环境变量 → 官方 CLI 认证文件（`~/.commandcode/auth.json`，由 `command-code login` 写入）。
-- **模型选择器标注**：每个模型显示包含它的**最低套餐**（`KNOWN_PLANS`）、**活动折扣**或 `FREE` 徽章（`KNOWN_DEALS`，到期自动隐藏已失效折扣）、峰谷定价模型的**当前时段状态**（`Peak`/`Half`，按当前 UTC 小时动态判断）、Vision 模型的 **`Image`** 标记，以及**上下文长度**（`1M` / `256K` / `262K`）——例如 *"Go · 50% off · Image · 1M"*、*"Go · Half · 1M"*。列表**按套餐排序**（Go → GOAT → Pro → Provider/Max），你当前套餐能用的模型总是排在最前。
-- **按套餐过滤选择器**：选择器会**直接隐藏超出你订阅套餐的模型**（根据账户账单状态实时判断）。全程失败开放——账单接口不可用、套餐未知，或账户持有按需余额（官方 CLI 视为解锁全部模型）时都显示完整目录——服务端仍是最终闸门。在设置页关闭「隐藏套餐外模型」开关（或在 `llm-commandcode` 设置段中设 `filterModelsByPlan: false`）可始终列出全部模型。
-- **推理强度（reasoning-effort）支持**：针对官方目录标为推理模型的模型（`KNOWN_EFFORTS`，与 `command-code@1.28.4` 一致）；没有可选档位但仍支持思考的模型会自动思考，与官方 CLI 行为完全一致。
-- **支持视觉模型的图片输入**（通过 dsh 附件服务、以官方 wire 格式发送）；纯文本模型会明确拒绝图片（`UNSUPPORTED_CONTENT`）而非静默丢弃。
-<img src="assets/screenshots/model-picker.png" alt="带套餐、折扣、图片与上下文标注的模型选择器" width="250">
-## 获取 API key
-Command Code 的 API key 永不过期。最简单的途径是官方 CLI（Node.js 22+）：
-```sh
-npm i -g command-code@latest
-cmd login        # macOS/Linux；Windows 原生版：cmdc login
-```
-`cmd login` 会打开浏览器认证；成功后 key 写入 `~/.commandcode/auth.json`——本插件会自动读取（最后兜底）。也可以直接在浏览器创建 key（[Command Code Studio](https://commandcode.ai/studio/auth/cli)）并粘贴到 **设置 → Command Code**，或 `export COMMANDCODE_API_KEY="user_..."`。
+- **插件包**：一条 `dsh plugin add` 命令安装到任意 dsh 配置，注册 `commandcode` provider 路由，带实时模型目录。
+- **专属设置页**：API key 输入、连接参数、实时「账户用量」卡片和「隐藏套餐外模型」开关。
+- **多账户轮换**：一个账户用量打满后，请求自动切换到下一个账户。详见[多账户轮换](#多账户轮换)。
+- **key 配置灵活**：设置页填写、环境变量或官方 CLI 登录文件均可。
+- **模型选择器标注**：每个模型标注最低套餐、折扣/FREE 徽章、峰谷时段、图片支持与上下文长度，免费模型置顶。
+- **按套餐过滤**：默认隐藏超出订阅套餐的模型，可一键关闭。
+- **推理强度支持**：支持推理强度的模型可在选择器中选择档位。
+- **图片输入**：Vision 模型支持发送图片。
 ## 安装
-### 从 npm 安装（推荐）
-npm 上裸名 `dsh-commandcode-provider` 已被无关包占用，因此本插件以 **`@mars-sea/dsh-commandcode-provider`** 发布：
 ```sh
-dsh plugin --profile web add @mars-sea/dsh-commandcode-provider
-```
-### 从 GitHub 安装
-```sh
-# 推荐：锁定发布 tag（可读、不可变）
-dsh plugin --profile web add github:Mars-Sea/dsh-commandcode-provider#v0.2.2
-# 或按完整 commit SHA 锁定任意提交
-dsh plugin --profile web add github:Mars-Sea/dsh-commandcode-provider#<完整-commit-sha>
-```
-`#<ref>` 后缀把源码锁定到**某一个精确版本**（pnpm 的 git 依赖语法）。不加 `#` 则跟随默认分支，后续 push 会悄悄改变你装到的内容。
-git 安装会拉取**源码**，因此包的 `prepare` 脚本会在安装后构建 `lib/`。pnpm ≥10 默认阻止该脚本——先运行 `add`，再把 pnpm 打印的**确切包 key** 复制到 `~/.dsh/profiles/web/pnpm-workspace.yaml`：
-```yaml
-allowBuilds:
-  '@mars-sea/dsh-commandcode-provider@github:Mars-Sea/dsh-commandcode-provider#<完整-commit-sha>': true
+dsh plugin --profile web add @mars-sea/dsh-commandcode-provider@latest
 ```
-然后重新运行 `add`。
-### 从本地检出安装
+## 更新
 ```sh
-npm install
-npm run build                          # git/压缩包安装通过 `prepare` 自动执行
-dsh plugin --profile web add /path/to/dsh-commandcode-provider
-```
-修改 `src/` 后需重新运行 `npm run build` 并重启应用。
-### 安装做了什么
-`dsh plugin add` 会把包链接到配置目录（pnpm 按**真实包名** `@mars-sea/dsh-commandcode-provider` 记录），追加到 `dsh.profile.bundles`，并激活 `cordis.patch.yml` 层：
-```yaml
-- insert:
-    - id: llm-commandcode
-      name: "@mars-sea/dsh-commandcode-provider"
-      config:
-        apiKeyEnv: COMMANDCODE_API_KEY
+dsh plugin --profile web add @mars-sea/dsh-commandcode-provider@latest
 ```
-patch 里的 `name` 必须是**带引号的完整包名**——loader 会把它当作模块从 profile 的 `node_modules` 导入，而 pnpm 只会链接带 scope 的名字。写成裸名会报 `ERR_MODULE_NOT_FOUND` 并在启动时崩溃；不引号的 `@mars-sea/...` 会导致 YAML 解析失败（见[故障排查](#故障排查)）。
-验证合成后的层，然后（重新）启动 Web 应用：
-```sh
-dsh --profile web --dump-config          # 会显示 "# == @mars-sea/dsh-commandcode-provider" 层
-dsh web                                  # 或重启你正在运行的实例
-```
+然后重启 Web 应用。
-## 更新
+## 获取 API key
-patch 层在每次启动时都从**已安装的包**读取，更新包本身就会带入修复后的行——**不需要**手工改 `cordis.patch.yml`（除非你把它的内容复制到了自己 profile 的层里）。
+最简单的途径是官方 CLI（Node.js 22+）：
 ```sh
-# npm：总是升到最新发布版本
-dsh plugin --profile web update @mars-sea/dsh-commandcode-provider
-# GitHub（按 tag）：指向新 tag——无需先卸载，pnpm 会就地替换
-dsh plugin --profile web add github:Mars-Sea/dsh-commandcode-provider#v0.2.2
-# 本地检出：拉取、重新构建、重启
-git -C /path/to/dsh-commandcode-provider pull
-npm run build --prefix /path/to/dsh-commandcode-provider
-dsh web
+npm i -g command-code@latest
+cmd login        # macOS/Linux；Windows 原生版：cmdc login
 ```
-然后重启 Web 应用。用 `dsh --profile web --dump-config` 验证——层里应显示 `name: '@mars-sea/dsh-commandcode-provider'`。
-> **`update` 提示 "Already up to date" 但版本没变（pnpm ≥ 11）？** pnpm 11 的 `minimumReleaseAge` 供应链策略可能拒绝刚发布的新版本。请改用显式版本：`dsh plugin --profile web add @mars-sea/dsh-commandcode-provider@0.2.2`（或在 profile 目录里 `pnpm config set minimumReleaseAge 0 --location project`）。
-> **从 ≤0.1.6 升级**（或手改坏的 profile）：如果你之前**手工复制**过旧的 patch 行到你 profile 自己的 `cordis.patch.yml`，那份拷贝会覆盖 bundle 层——请改成 `name: "@mars-sea/dsh-commandcode-provider"` 或删掉它（见[故障排查](#故障排查)）。
-> **想卸载而不是升级**：`dsh plugin --profile web remove @mars-sea/dsh-commandcode-provider`（用 **scoped** 名——pnpm 按真实包名记录依赖）。你在 dsh 凭据库和 `~/.commandcode/auth.json` 里的 API key 不受影响。
+也可以在 [Command Code Studio](https://commandcode.ai/studio/auth/cli) 创建 key 后粘贴到 **设置 → Command Code**，或 `export COMMANDCODE_API_KEY="user_..."`。
 ## 验证是否生效
-重启后：**设置 → Command Code** 显示专属页面——填入 API key 并点击**保存**（徽章变为"已配置"即表示 Host 已存储）。**设置 → Models** 会显示 **Command Code** 卡片；模型选择器会在 **commandcode** 下列出实时目录。发送消息并选择你套餐中包含的模型——`deepseek/deepseek-v4-flash` 适用于入门级套餐，开放权重模型（DeepSeek/Qwen/Kimi/MiniMax）通常都可用，而前沿模型（Claude/GPT/Gemini/Grok）可能需要 Pro/Max 套餐或按需计费。
+重启后，在 **设置 → Command Code** 填入 API key 并保存；**设置 → Models** 出现 **Command Code** 卡片，模型选择器在 **commandcode** 下列出实时目录。选择套餐内包含的模型发送消息即可。
 ## 用量面板
-插件注册了一个 `/commandcode` 斜杠命令（需要 dsh 的 `commands` 服务，标准 web profile 自带），从官方账户端点显示你的账户状态：
+插件注册了 `/commandcode` 斜杠命令，显示各账户的用量状态：
 ```text
 /commandcode        （或 /commandcode status）
 ```
-![用量面板](assets/screenshots/usage-dashboard.png)
-每个端点独立降级——某个端点临时失败不会影响其他数据，并会在末尾内联提示失败。
 ## 多账户轮换
 有多个 Command Code 订阅时，插件可以在一个账户达到用量限额后**自动切换到下一个账户**：
-- **被动切换，零额外开销**：只有请求真正被 pre-stream 拒绝时才轮换——429（窗口打满）标记该账户耗尽、401 标记其密钥失效，adapter 随即用下一个账户的 key 重发同一请求（请求体与账户无关、`threadId` 每次随机，模型完全无感）。
-- **精确复活**：当所有账户都被标记时，插件会用每个 key 查询 `/alpha/billing/credits` 的真实 5 小时窗口——已重置的账户立即复活；仍全部耗尽则抛出 `RATE_LIMIT` 错误并注明**最早的重置时间**（全部为 401 则抛 `INVALID_CREDENTIAL`）。
-- **配置入口**：**设置 → Command Code** 的「多账户轮换」卡片——**添加账户**后为每个账户填备注名和 API key（每个 key 通过凭据服务存于独立引用 `COMMANDCODE_API_KEY_2`…，与默认 key 一样只写不回显）。顶层的 key 始终是第一顺位的 `default` 账户。
-- **手动切换**：同一张卡片上的「当前使用账户」下拉框可以**手动指定优先账户**（持久化为 `activeAccount` 设置项），保存后下次请求即生效；所选账户耗尽时仍自动回落到其他可用账户，窗口重置后自动回到所选账户。
-- **按账户展示**：设置页的「账户用量」卡片按账户分区显示，带「当前使用 / 限额冷却中 / 密钥无效」徽章；`/commandcode` 命令同样按账户输出。
+- **配置**：在 **设置 → Command Code** 的「多账户轮换」卡片添加账户并填写备注名与 API key；顶层 key 始终是第一顺位的 `default` 账户。
+- **手动切换**：卡片上的「当前使用账户」下拉框可指定优先账户；所选账户耗尽时自动回落到其他账户，窗口重置后自动恢复。
+- **状态展示**：「账户用量」卡片与 `/commandcode` 均按账户分别显示状态。
 等价的 YAML（`$DSH_HOME/settings.yaml` 或组合配置）：
@@ -163,53 +83,33 @@ llm-commandcode:
       apiKeyEnv: COMMANDCODE_API_KEY_3
 ```
-组合配置里每个账户也可写字面量 `apiKey`（优先于其 `apiKeyEnv`）；设置文档中永不存储密钥字面量。
 ## 配置
-**设置 → Command Code** 是主要配置入口：**API key** 输入框（通过凭据服务存储在 `$DSH_HOME/.credentials.yaml`，只写不回显，并显示是否已配置），以及 **API 地址**、**工作目录**、**请求/流超时**字段，全部写入 `llm-commandcode` 设置段。没有 key 也可以浏览模型目录。**工作目录可选**——留空即可，占位符会显示它实际使用的进程 cwd。
+**设置 → Command Code** 可配置 API key、API 地址、工作目录与请求/流超时；配置好 key 后，页面顶部会显示实时「账户用量」卡片。
-配置好 key 后，页面顶部会显示实时**「账户用量」卡片**——与 `/commandcode` 相同的账户、花费、额度与窗口限制信息，外加订阅套餐徽章和账期截止——数据在宿主端获取（key 不会离开宿主），并以原生 UI 渲染：
-<img src="assets/screenshots/settings-page.png" alt="Command Code 设置页面（含账户用量卡片）" width="640">
-同一组选项也位于 `$DSH_HOME/settings.yaml`（按请求覆盖，无需重启）：
+同一组选项也位于 `$DSH_HOME/settings.yaml`（修改即刻生效，无需重启）：
 ```yaml
 llm-commandcode:
-  apiKeyEnv: COMMANDCODE_API_KEY   # 每次请求解析的凭据引用
+  apiKeyEnv: COMMANDCODE_API_KEY   # 凭据引用
   apiBase: https://api.commandcode.ai
-  workingDir: /path/to/project     # 上报给 API（项目 slug、配置块）
+  workingDir: /path/to/project     # 可选
   modelsCachePath: ~/.commandcode/models-cache.json
-  requestTimeoutMs: 60000          # 等待首个响应字节的最长时间（默认 60s）
-  streamIdleTimeoutMs: 300000      # 流停顿超过该时长即视为死连接（默认 300s——刻意放宽，避免切断长思考模型）
+  requestTimeoutMs: 60000          # 默认 60s
+  streamIdleTimeoutMs: 300000      # 默认 300s
 ```
-组合入口配置（`cordis.patch.yml`）接受相同的键；那里的字面量 `apiKey` 优先于凭据引用。
-## 故障排查
-- **`Command Code API request to .../alpha/generate failed`，且不停重试** ——这是**传输层失败**：`fetch()` 根本没拿到 HTTP 响应（401/403/429 会显示 "API error"）。0.1.8 起错误消息会点名**真实根因**（`ECONNREFUSED`、`ENOTFOUND`、`CERT_HAS_EXPIRED`、`socket hang up` 等）。常见原因：**需要代理**（Node 的 `fetch`/undici 不读取 `HTTP_PROXY`/`HTTPS_PROXY`——配置 dispatcher 或把 `api.commandcode.ai` 加入白名单）、**连接被中途重置/限速**（防火墙、GFW 类干扰、Wi-Fi 不稳）、**TLS 被中间人替换**（企业 MITM），或只是重试能恢复的瞬时抖动。
-- **长回答生成到一半中断** ——0.1.8 起，adapter 会在 `requestTimeoutMs`（60s）内拿不到首字节时中止，并在流停顿超过 `streamIdleTimeoutMs`（默认 300s）时判为死连接。两者都以 `TIMEOUT` 呈现并附带停顿时长；网络慢但稳定可调大这两个值。
-- **推理模型思考较久时"反复重连"** ——流空闲看门狗原默认 120s，比前沿推理模型（xhigh/max effort）的静默思考期还短——它们可以数分钟不吐 token，而官方 CLI 根本不设空闲上限。0.2.3 起默认改为 **300s**；若极长思考仍触发误判，在 `llm-commandcode` 配置段或设置页调大 `streamIdleTimeoutMs`。
-- **启动崩溃：`ERR_MODULE_NOT_FOUND: Cannot find package 'dsh-commandcode-provider'`** ——patch 行的 `name` 是裸名，但 pnpm 只链接带 scope 的名字。改成 `name: "@mars-sea/dsh-commandcode-provider"`——注意**必须加引号**（不引号的 `@` 开头标量会导致 YAML 解析失败）——然后重启。
-- **`MODEL_NOT_IN_PLAN` (403)** ——所选模型不在你的套餐内。选一个开放权重模型或升级套餐；错误会指明模型并附官方文档链接。
-- **`MISSING_CREDENTIAL`** ——任何地方都没有 key。在设置页存一个、`export COMMANDCODE_API_KEY`、设置 `config.apiKey`，或运行 `command-code login`。没有 key 时路由与目录仍可浏览。
-- **Models 卡片显示"未配置"但请求可用** ——key 来自 `~/.commandcode/auth.json`（`cmd login` 兜底），而非凭据存储。把它粘贴到卡片一次即可；两者可共存。
-- **推理模型在短请求下不返回可见文本** ——它先消耗输出 token 做推理；`maxTokens` 较小时可能在可见文本前就用完。属正常现象。
-- **git 安装时 `dsh plugin add` 报 `allowBuilds` 错误** ——把 pnpm 打印的确切包 key 复制到 `pnpm-workspace.yaml` 并重新运行（见[从 GitHub 安装](#从-github-安装)）。
 ## 注意事项与限制
-- **图片输入按模型能力限制**：只有官方注册表标记为 Vision 的模型接受图片（见 `src/adapter.ts` 的 `KNOWN_IMAGE_MODELS`）。纯文本模型会抛 `UNSUPPORTED_CONTENT`；官方 CLI 对纯文本模型的客户端 *VISION* 副调用在此**不复现**——请改用支持 Vision 的模型。图片输入还需要 dsh 的**附件服务**。
-- **在含图片的会话里切换到纯文本模型会被 dsh 自身拒绝**——这是 harness 层的守卫（`dsh-host-apiproxy` 的 `selectModel`），无法从插件侧放宽。本 bundle 通过客户端插件让提示更友好：把拒绝改写为「当前会话已包含图片，而模型 `<model>` 不支持图片输入；请选择支持图片的模型，或先移除会话中的图片。」（错误码与 details 原样透传）。选择带 *`Image`* 标记的模型、先移除图片，或安装图片路由 bundle（如 `@deepseek-ai/dsh-llm-image-routing`）。
-- **不支持 `stop` 序列**（线上格式没有该字段）：携带它的请求会抛 `UNSUPPORTED_OPTION`。
-- 推理块**不会**重放到后续轮次（与官方 CLI 一致）；只有带配对工具结果的工具调用会被重放。
-- 模型目录端点是公开的；`/alpha/generate` 需要你的 key。
+- **图片输入按模型能力限制**：仅 Vision 模型接受图片，纯文本模型会直接拒绝。
+- 含图片的会话切换到纯文本模型会被 dsh 拒绝——请改选带 *`Image`* 标记的模型，或先移除图片。
+- **不支持 `stop` 序列**：携带它的请求会报错。
+- 推理块不会重放到后续轮次；只有带配对工具结果的工具调用会被重放。
+- 模型目录无需 key 即可浏览；对话请求需要 key。
 ## 权限与隐私
-本插件完全在你的 dsh profile 和你的 Command Code 账号内运行。**本地文件**：仅在最后兜底时读取 `~/.commandcode/auth.json`；读写 `~/.commandcode/models-cache.json`；通过标准凭据 seam 从 `$DSH_HOME/.credentials.yaml` 读取 key（永不记录日志）。**网络**：`GET {apiBase}/provider/v1/models`（公开目录）与 `POST {apiBase}/alpha/generate`（你的请求，已认证），请求体包含你配置的 `workingDir`。**无遥测**——唯一的对外主机是 Command Code API（默认 `api.commandcode.ai`，可通过 `apiBase` 配置）。
+本插件只在本地与你的 Command Code 账号之间通信：本地仅读写凭据存储与模型缓存文件（兜底读取 `~/.commandcode/auth.json`）；网络仅访问 Command Code API。无遥测。
 ## 关闭 / 卸载
@@ -220,7 +120,7 @@ llm-commandcode:
   dsh plugin --profile web remove @mars-sea/dsh-commandcode-provider
   ```
-  这会移除 bundle 依赖及其配置层；你在 dsh 凭据库和 `~/.commandcode/auth.json` 中的 API key 不会被改动。
+  你在 dsh 凭据库和 `~/.commandcode/auth.json` 中的 API key 不会被改动。
 ## 开发
@@ -230,6 +130,14 @@ npm run typecheck   # tsc --noEmit
 npm run build       # tsdown -> lib/
 ```
+在 profile 里试用本地构建：
+```sh
+dsh plugin --profile web add /path/to/dsh-commandcode-provider
+```
+修改 `src/` 后需重新运行 `npm run build` 并重启应用。
 ## 社区与反馈
 - <img src="https://cdn.simpleicons.org/github/111827" width="16" alt="GitHub" /> [GitHub 仓库](https://github.com/Mars-Sea/dsh-commandcode-provider)
@@ -240,3 +148,17 @@ npm run build       # tsdown -> lib/
 ## 许可证
 MIT —— 见 [LICENSE](./LICENSE)。部分内容移植自 [pi-commandcode-provider](https://github.com/patlux/pi-commandcode-provider)（MIT）。
+## 界面截图
+**模型选择器** —— 套餐档位、折扣/FREE、峰谷时段、Image 与上下文标注：
+<img src="assets/screenshots/model-picker.png" alt="带套餐、折扣、图片与上下文标注的模型选择器" width="420">
+**用量面板** —— `/commandcode` 的分账户报告：
+![用量面板](assets/screenshots/usage-dashboard.png)
+**设置页** —— API 密钥、连接参数、多账户轮换与实时账户用量卡片：
+<img src="assets/screenshots/settings-page.png" alt="Command Code 设置页面（含账户用量卡片）" width="640">