dsh-any-deepseek 0.0.16 → 0.0.17

package/CONTRIBUTING.md

@@ -0,0 +1,133 @@
+# 参与改进 dsh-any-deepseek
+
+这是个实用小工具，改动从「一个字段的文案」到「接一家新渠道」都欢迎。
+
+**先读 [README.md](README.md)** —— 那里讲的是怎么用；这一份讲怎么改。
+
+---
+
+## 最有价值的三种贡献
+
+### 1. 接一个新渠道
+
+内置 5 家，接别家通常只改 [`src/presets.ts`](src/presets.ts) 一个文件。
+
+```ts
+'your-relay': {
+  displayName: 'Your Relay',
+  api: 'openai-completions',
+  baseURL: 'https://your-relay.example/v1',
+  // 🔴 用**这家自己的**拼写。各家模型名不同：
+  //    deepseek-v4.1-flash / deepseek/deepseek-v4.1-flash / deepseek-flash
+  //    抄错不会在本地报错 —— 会在第一次真请求时被上游拒。
+  model: 'deepseek-v4.1-flash',
+  ...V41_FLASH_CAPS,
+  // 可选：这家有没有余额接口、是哪种形状（见 src/balance.ts 的四种 shape）
+  // balance: { shape: 'openai-billing' },
+},
+```
+
+加完这一条，面板的规格下拉里就有它了 —— 不需要改别处。
+
+**两条硬规矩**（都是付过代价的）：
+
+1. **注释里不要写「我探过了」，除非真的探过。**
+   这个仓里曾经有一条 `Probed live: the billing pair answers` 的注释，而那个路由**从没被调用过**，
+   第一次真调用就 404。**假证据比没有注释更坏** —— 它让下一个读者不再去查。
+
+2. **`model` 填上游的拼写，不是我们的 id。**
+   我们对外只暴露 `deepseek-v4.1-flash` 一个 id，各家的拼写由预设吸收。
+   **这正是这个插件存在的理由** —— 所以别在预设里图省事写我们的 id。
+
+### 2. 修一处文案
+
+面板上的每一句都应该是一个**能在页面上验证的事实**。读到含糊、过时、或替宿主猜原因的，直接改。
+
+判断标准（本项目一直在用）：
+
+- ❌ 「已安全保存」—— 读者无法验证。
+- ✅ 「存在 `channels.<id>.apiKey`，会出现在 `--dump-config` 输出里」—— 可验证。
+- ❌ 「只读部署，或设置服务未启用」—— 替宿主猜了两个**没查过**的原因。
+- ✅ 「宿主拒绝了这个修改」+ 宿主自己的错误信息 —— 只说知道的事。
+
+### 3. 报一个「装了但没反应」
+
+**静默失效是本项目最贵的一类缺陷** —— 装了不生效、写了没保存、功能存在但不可达，
+全都零报错。复现步骤比任何猜测都值钱。
+
+这类问题通常有这几个藏身处，如果你能指出是哪一处，修起来会快很多：
+
+| 现象 | 可能的位置 |
+|---|---|
+| 面板整块不出现，控制台零错误 | `SETTINGS_NS` 与 `cordis.patch.yml` 的条目 id 不一致 |
+| 面板在，但每次请求都失败、表格显示「还没有渠道」 | `inject` 里少了 `webServer`，路由被静默跳过 |
+| 设置写不进去，但看不出原因 | schema 少了 `.volatile()`，或写入被 `.catch` 吞了 |
+| provider 装了但模型选择器里没有 | 注册元数据（`inputModalities` / `reasoning`）没声明 |
+
+## 加一种余额形状（少见）
+
+如果某家有余额接口但形状是新的，改 [`src/balance.ts`](src/balance.ts)：
+
+1. 给 `BalanceProbe.shape` 加一个值；
+2. 写一个 `parseXxx()`；
+3. 在 `balanceUrls()` 里给它路径；
+4. 在 `readBalance()` 里分发。
+
+`balanceUrls()` 是**唯一**知道路径的地方 —— 这样预设就不可能和传输层意见相左。
+
+还有一条底线：**缺数字就报缺，绝不填 0。**
+「读不到」和「是空的」导致相反的行动，而只有一个是真的。
+
+## 开发
+
+```bash
+pnpm install
+pnpm run typecheck     # 两个 tsconfig：node 半 + client 半
+pnpm run test          # 纯函数层，不需要装上 harness
+pnpm run build         # lib/index.js + lib/client.js
+```
+
+纯函数层（`presets` / `channels` / `route` / `usage-ledger` / `balance`）不 import harness，
+所以单测跑得很快。适配器与面板只通过宿主的公开接缝和它说话。
+
+## 判据必须承重
+
+**每条新判据都要附一次「把它弄红」的实验结果。**
+
+把修复回滚，那条用例必须红；否则它只是装饰。这个仓的 CHANGELOG 里每个结论都带着它的负控制读数
+（例如「去掉 `percent` 取反 ⇒ 精确红 3 条」）。
+
+三种特别容易写成**假判据**的形态，本项目都踩过：
+
+1. **判据与被判对象同源**。例：`bump` 改的是 CHANGELOG 首个标题，而 `version` 只读首个标题 ⇒
+   永远读绿。要抓这类缺陷，判据必须碰**别的不变式**（现在是「集合包含」：原有每个标题都在，且恰好多一个）。
+2. **假传输层掩盖走错协议**。测试里传输层是假的，走错协议照样「通」。
+   分发决策要用**结构判据**钉住（断言 `api: apiImplementations()` 存在、旧形态不回来）。
+3. **自写抽取器出错时不喊**。手写的 YAML 正则抽空了，用例照样绿。
+   ⇒ 抽取要**如实落盘原文**再看，不要在抽取器里顺手「清洗」。
+
+## 截图怎么更新
+
+README 里的三张图来自 `scripts/screenshot-harness.tsx`，它渲染**真实面板组件**
+（假数据、真 CSS/JSX/文案）—— 面板本身在 token 保护的 Web UI 后面，干净 profile 打开是空白页，
+所以直拍拿不到。
+
+```bash
+msm("any-deepseek-develop", ["shot"])        # 打包成单文件页面
+```
+
+生成的页面在 `_tmp/shot/screenshot-harness.html`，用浏览器打开后截图即可。
+加 `?variant=add` 可以拍「添加渠道」表单那一种状态。
+
+> ⚠️ 打包时有两个坑，都会让页面**空白且零报错**：产物里残留 `import`（内联模块无法解析）、
+> 或外部 `<script src>` 在 `file://` 下被 CORS 拒。`shot` 已自带「不许有残留 import」的判据。
+
+## 发布
+
+维护者用的开发通道是 CCC 的 MSM `any-deepseek-develop`（safe-mode 下没有 bash）。
+`stage check` 是「能不能装」的唯一判据 —— **`npm publish` 的退出码 0 不代表可安装**，
+新版本要一两分钟后才在 registry 上出现。
+
+## 许可
+
+MIT

package/README.en.md

@@ -1,277 +1,217 @@
 # dsh-any-deepseek
 
-Collapse several DeepSeek relays into **one** provider with **one** model: paste a key per channel
-in the settings panel, click to switch.
+**Use DeepSeek credit from several providers inside DeepSeek Harness — with one extra row in the
+model list, not N.**
 
-A small open-source tool (MIT). Fork it, add a relay, improve it — see
-[Contributing](#contributing).
+You bought DeepSeek credit in several places: the official API, a relay, a cloud vendor, a cheap
+one a friend recommended. This plugin collects them into **one** provider: paste a few keys, click
+to switch — and usage is booked per real upstream, so you can see what each one cost this month.
 
-[中文](README.md) · English (this page)
+![Channel list](docs/screenshot-channels.png)
 
-![Channels tab](docs/screenshot-channels.png)
+[中文](README.md) · English (this page)
 
 ---
 
-## What problem this solves
+## Before you install: is this for you?
 
-You have DeepSeek credit in several places: the official API, a relay, a cloud vendor, a
-colleague's cheap recommendation. In DeepSeek Harness, that would normally become **N entries in
-the model picker**, and every switch means editing configuration, changing the model id, changing
-the key — plus you have to remember yourself which relay spent how many tokens this month.
+**Yes**, if any of these is true:
 
-After installing this plugin:
+- You have **more than one** DeepSeek endpoint and want to switch between them without editing
+  configuration.
+- You want **per-channel usage accounting** instead of one blended total.
+- You use relays whose model ids differ (`deepseek-v4.1-flash` / `deepseek/deepseek-v4.1-flash` /
+  `deepseek-flash`) and don't want to keep track yourself.
 
-- The model picker has **one row**: `any-deepseek / deepseek-v4.1-flash`.
-- Any number of **channels** hang off it; each is an endpoint + a key + a display name.
-- Click a channel's dot and requests go there. **No automatic switching** (see
-  [Why no failover](#why-no-failover)).
-- Usage is booked **per real upstream**.
+**No**, if:
 
-```
-                ┌── channel A (official)   ← currently selected
-composer ──────►│
-  │             ├── channel B (a relay)
-  ▼             └── channel C (another)
-any-deepseek
-  / deepseek-v4.1-flash
-   (the only model exposed)
-```
+- You have a single endpoint and it is the official one — the built-in `deepseek-official` already
+  covers you; this plugin is unnecessary.
+- You want **automatic failover** (one endpoint dies, requests move to the next). v1 does not do
+  that — see [Why no failover](#why-no-failover).
+- You want to **switch between models**. This is "one model, many sources", not a model router.
 
 ## Install
 
+Requires DeepSeek Harness to be installed already. In a terminal:
+
 ```bash
 dsh plugin --profile web add dsh-any-deepseek
 ```
 
 Then **restart DSH** and open Settings → **Any DeepSeek**.
 
-> **A first install requires a restart**: the profile's layer list changed, and the composition
-> graph is built at boot. Editing an already-installed plugin's client half reloads in the
-> browser; its node half does not.
->
-> `dsh plugin` forwards its arguments to pnpm, so `add <spec>` accepts a registry name, a tarball
-> path, or a local directory (installed as a symlink).
+> **Why the restart**: the plugin is added to the profile's load list, which is read only at
+> startup. Afterwards, changing this plugin's UI half needs only a browser refresh — but the
+> **first install** needs the restart.
 
-## Usage
+## First run: three steps
 
-### Add a channel
+### 1. Add a channel
 
-Click **添加渠道**. Only two things are required:
+Click **添加渠道** (Add channel). Two fields are required:
 
-| Field | Required | Meaning |
-|---|---|---|
-| **规格** (preset) | ✅ | Determines endpoint, upstream model id, and protocol — so you don't type them. |
-| **渠道 id** (channel id) | ✅ | The configuration key, `[a-z0-9][a-z0-9_-]*`. The same preset can be added twice; the second becomes `-2`. |
-| **显示名** (display name) | — | Display only. Tells two accounts on the same relay apart. **Renaming never touches the id.** |
-| **密钥** (key) | ✅ | The key itself. There is no name to invent. |
+![Add channel](docs/screenshot-add-channel.png)
 
-Bundled presets: **DeepSeek Official**, **OpenCode Go**, **Ollama Cloud**, **Open Design**,
-**CommandCode**. For another relay, see [Adding a channel](#adding-a-channel).
+| Field | What it means |
+|---|---|
+| **规格** (preset) | Pick your provider. It determines the endpoint, model id, and protocol — so you don't type them. |
+| **密钥** (key) | The key that provider gave you. Paste it. There is no name to invent. |
 
-### Switch channels
+**渠道 id** (channel id) is filled in for you — it is just the configuration key, and you can
+change it. **显示名** (display name) defaults to the preset name; when you run two accounts on the
+same provider, set something like "main" / "backup".
 
-Click the dot at the left of a row. The current channel is marked three ways — a colour bar down
-the left edge, a stronger border, and a tinted fill — plus `aria-current`.
+Bundled presets: DeepSeek Official, OpenCode Go, Ollama Cloud, Open Design, CommandCode.
+For another provider, see [Adding a provider](#adding-a-provider).
 
-**Switching invalidates the prompt cache for the running conversation**, so switch at a natural
-boundary or start a new session.
+### 2. Make sure it is selected
 
-### Remaining balance
+The first channel you add **becomes the current channel automatically** — its row gets a radio
+dot, a colour bar down the left edge, and a 「当前」 badge.
 
-Click **查询余额** (on demand; nothing is scanned when the panel opens). Four outcomes are kept
-strictly apart, because each calls for a different action:
+To switch later: click the dot at the left of a row.
 
-| Shown | Meaning |
-|---|---|
-| `642.44 CNY` / `55.48 USD` | An amount was read |
-| `rolling 100% · weekly 81% · monthly 75%` | This relay reports **usage windows**, not money |
-| **余额未尽** (no balance API; verified live: …) | No balance API, but a live request **succeeded** ⇒ the account is not blocked for lack of credit. **Not an amount** (see below) |
-| 不支持查询 / 读取失败 / 未配置密钥 | Three different kinds of "nothing" |
+### 3. Start using it
 
-> ⚠️ **"Not exhausted" is not "how much is left".** It is the result of one minimal real request
-> (a token or two) succeeding, which proves exactly three things: the endpoint is serving, the key
-> works, and the account is not blocked for lack of credit (an exhausted account answers
-> 402/quota, not 200). So the panel says only 「未尽」 and **never fabricates an amount** —
-> printing `0.00` would read as "you are out of credit", the opposite of the truth.
+In the model picker, choose **DeepSeek V4.1 Flash** (the provider is `any-deepseek`).
+Every request then goes to whichever channel you selected.
 
-> ⚠️ **A missing number is never rendered as `0`.** "We could not read it" and "it is empty" lead
-> to opposite actions.
+## Three things you will actually do
 
-### Usage
+### Switch channels
 
-![Usage tab](docs/screenshot-usage.png)
+Click the dot at the left of a row.
 
-One row per channel, groupable by channel or by day.
+> ⚠️ **Switching invalidates the prompt cache for the running conversation**, so switch at a topic
+> boundary, or just start a new session.
 
-**Counting convention** (the panel prints it too): harness token counts are **disjoint** —
-**input** is uncached input only, cache reads and writes are separate columns, and the three
-together are the **billable input**. Treating "input" as the total makes it look under-reported.
+### See how much credit is left
 
-**Speed** counts generation time only (total minus time-to-first-token). Blending queueing +
-first-token wait + generation into one number makes "slow to start" and "slow throughout" read
-identically, and those two call for opposite fixes. `—` means unmeasured, **not zero**.
+Click **查询余额** (Check balance). It does not run when the panel opens — each check calls every
+provider's server.
 
-## Configuration
+Different providers can report different things, and the panel keeps them apart:
 
-Everything lives under one settings namespace — the **profile entry id** from
-`cordis.patch.yml`, which is what the panel binds to:
+| What you see | Meaning |
+|---|---|
+| `642.44 CNY`, `55.48 USD` | This provider reports an amount |
+| `rolling 100% · weekly 81% · monthly 75%` | This provider reports **subscription usage percentages**, not money |
+| **余额未尽** (verified live: …) | This provider has **no balance API**, but a minimal live request **succeeded** ⇒ the account is not blocked |
+| 不支持查询 / 读取失败 / 未配置密钥 | Three different kinds of "nothing" |
 
-```yaml
-dsh-any-deepseek:
-  current: opencode-go          # the live channel
-  channels:
-    opencode-go:
-      apiKey: sk-…              # the key itself
-    open-design:
-      preset: open-design
-      label: Open Design (main)  # optional display name
-  usage:
-    enabled: true
-```
+> **"Not exhausted" is not "how much is left".** One successful request proves exactly three
+> things: the endpoint is reachable, the key is valid, and the account is not blocked for lack of
+> credit (an exhausted account answers 402, not 200). So the panel says only 「未尽」 and **never
+> invents an amount**.
 
-`channels.<id>` may be either:
+### See what this month cost
 
-- **preset-backed** — `preset: opencode-go`, plus optional overrides; or
-- **fully declared** — `baseURL` + `model` required, `api` defaults to `openai-completions`,
-  and `contextWindow` / `maxTokens` fall back to documented defaults (the panel shows ⚠ on the
-  row when a default was applied rather than declared).
+Switch to the **用量** (Usage) tab.
 
-### Where the key lives (please read this part)
+![Usage](docs/screenshot-usage.png)
 
-`apiKey` holds the key **itself**, on the channel. The panel never asks you to invent a name for
-it — you paste the key and it is written here.
+Group by channel or by day. "Input" counts only cache misses; cache reads and writes are separate
+columns, and the three together are the billable input. In the speed column, `—` means
+**unmeasured — not zero**.
 
-⚠️ **That means the key is in your profile configuration.** `dsh --dump-config` prints patch
-layers verbatim and does **not** redact, so a diagnostic dump or a `git diff` of the profile
-includes it. **Do not share the profile document.** Environment-variable injection
-(`-e SOME_KEY=…`) is not consulted — nothing resolves a name.
+## Is my key safe
 
-> An earlier version hid the key behind a "credential reference name" and told you to set it "in
-> the credential centre" — a UI that does not exist. The current design is one field, one store,
-> one write.
+**It is stored in your local configuration file, in plaintext.**
 
-`apiKeyEnv` is still **read**, for configurations written before this change: when its value
-matches the reference-name grammar (`^[A-Za-z_][A-Za-z0-9_]*$`) it is resolved as a name; when it
-does not, it cannot be one, so it is adopted as the key itself. `apiKey` always wins when both are
-present, so re-entering the key once in the panel migrates an entry.
+The path is `channels.<channel-id>.apiKey` inside the profile. The plugin never sends it to any
+third party, but:
 
-A channel with no key **still appears** in the panel — that is how you find and fix it. Requests
-through it fail with `MISSING_CREDENTIAL`, and its row shows a hollow dot.
+> ⚠️ `dsh --dump-config` prints the configuration verbatim and does **not** redact it. So:
+> **do not share your profile configuration**, and do not paste its `git diff` anywhere public.
 
-### Protocols
+If you need to share config for troubleshooting, delete the `apiKey` lines first.
 
-`openai-completions` is the default and the recommendation: almost every relay speaks it, it
-exposes the largest compatibility surface (~20 switches), and its usage normalization already
-reconciles the three cache-token spellings relays use
-(`prompt_tokens_details.cached_tokens`, `prompt_cache_hit_tokens`, top-level `cached_tokens`).
+## Troubleshooting
 
-Set `api` on one channel only when that relay speaks something else (`openai-responses`,
-`anthropic-messages`). The panel never changes protocol behind your back.
+**The model list has no DeepSeek V4.1 Flash.**
+→ You have not restarted since installing. Restart DSH.
 
-### Thinking level
+**Settings has no "Any DeepSeek".**
+→ Same; or check you installed into the `web` profile: `dsh plugin --profile web list`.
 
-Each channel declares its selectable thinking levels, and the level picked in the harness is
-passed through to the relay:
+**`MISSING_CREDENTIAL`.**
+→ That channel has no key yet. Its status dot is hollow; click 「填写密钥」 to add one.
 
-```
-harness reasoningEffort → pi-ai ThinkingLevel → model.thinkingLevelMap → wire value
-```
+**`NO_CHANNEL_SELECTED`.**
+→ No channel is selected. The panel shows a hint at the bottom; click any row's dot.
 
-**There is no second mapping layer in this plugin**: the `thinkingLevelMap` the transport applies
-**is** the mapping, and a second one would drift from it. A level declared `null` is unsupported
-and is not offered in the picker.
+**「查询余额」 shows 「读取失败」.**
+→ That provider did not answer properly just now; retry. If it never works, your network may not
+reach it.
 
-### Image input
+**401 / 403 / out of credit.**
+→ The key is wrong or expired, or that account really is out of money.
 
-Supported. A channel can send and receive images, which requires declaring `input` with `image` —
-during **model registration** (`inputModalities`), not in the request path. This was a real
-defect: capability is a property of the provider, not of a channel or a single request.
+**Answers got slower or worse after switching.**
+→ Providers do not behave identically. Use the 测试 (Test) button per channel, and the 用量 tab to
+compare speeds.
 
 ## Why no failover
 
-v1 is deliberately manual. A failing channel reports its own error; it does not silently fall over
-to another:
+A failing channel reports its own error; it never silently moves to another. Three reasons:
 
 - Silent failover makes "who answered this?" unknowable, while the usage table honestly records
-  the other relay — two parts of the UI would disagree.
+  the other provider — the two parts would disagree.
 - Switching mid-conversation invalidates the prompt cache, costing more than the failure saved.
-- Failure is information. Hiding it means you never learn a relay is degrading.
-
-## Adding a channel
-
-This is a **small practical plugin**, and adding a relay is the most valuable contribution —
-usually it touches one file.
-
-### Add a preset (the common case)
-
-Edit [`src/presets.ts`](src/presets.ts) and add an entry to `CHANNEL_PRESETS`:
-
-```ts
-'your-relay': {
-  displayName: 'Your Relay',
-  api: 'openai-completions',
-  baseURL: 'https://your-relay.example/v1',
-  // 🔴 Use THIS relay's spelling. Model ids differ per relay:
-  //    deepseek-v4.1-flash / deepseek/deepseek-v4.1-flash / deepseek-flash …
-  //    A wrong spelling does not error here — the upstream rejects it on the first request.
-  model: 'deepseek-v4.1-flash',
-  ...V41_FLASH_CAPS,
-  // Optional: does this relay expose a balance surface, and which shape?
-  // balance: { shape: 'openai-billing' },
-},
-```
+- Failure is information. Hide it and you never learn a provider is degrading.
 
-That is enough — the preset picker gains the entry automatically.
+## Adding a provider
 
-⚠️ **Two rules** (both from real costs):
+Five are bundled; adding another usually touches one file. See
+**[CONTRIBUTING.md](CONTRIBUTING.md)**.
 
-1. **Do not write "probed live" in a comment unless you actually probed it.** This repo once
-   carried a `Probed live: the billing pair answers` comment for a route that had never been
-   called; the first real call returned 404. **A false claim is worse than no comment**, because
-   it stops the next reader from checking.
-2. **`model` is the upstream spelling, not our id.** We expose exactly one id,
-   `deepseek-v4.1-flash`; per-relay spellings are absorbed by presets — that is the whole point
-   of this plugin.
+## Configuration reference (advanced)
 
-### Add a balance shape (rarer)
+Everything lives under the `dsh-any-deepseek` namespace:
 
-If a relay has a balance API with a new shape, edit [`src/balance.ts`](src/balance.ts): add a
-`shape`, add a `parseXxx()`, give it a path in `balanceUrls()`, and dispatch it in `readBalance()`.
-`balanceUrls()` is the **only** place that knows the paths, so a preset cannot disagree with the
-transport.
-
-### Gates (run before committing)
-
-```bash
-pnpm run typecheck     # two tsconfigs: node half + client half
-pnpm run test          # pure layers only; no harness needed
-pnpm run build         # lib/index.js + lib/client.js
+```yaml
+dsh-any-deepseek:
+  current: opencode-go          # the current channel
+  channels:
+    opencode-go:
+      apiKey: sk-…              # the key itself
+    open-design:
+      preset: open-design       # use a bundled preset
+      label: Open Design (main) # optional display name
+    my-relay:
+      baseURL: https://relay.example/v1   # or declare it fully
+      model: deepseek-v4.1-flash
+      apiKey: sk-…
+  usage:
+    enabled: true
 ```
 
-Changes must come with a test **that can go red**. The rule in this repo is that **a judgement must
-carry weight** — revert the fix and the test must fail; otherwise it is decoration. Every
-significant claim in the code carries its negative-control result.
+**Protocol**: defaults to `openai-completions` (almost every relay speaks it). Set `api:
+openai-responses` or `api: anthropic-messages` on **that one channel** only when it really speaks
+something else.
 
-## Known boundaries
+**Thinking level**: each channel declares which levels it supports, and the level you pick in the
+UI is the one sent upstream. Unsupported levels are not offered in the picker.
 
-- Does not modify the harness, and does not replace `deepseek-official` / `llm-pi-ai` routes.
-- Exposes exactly one model id. Upstream ids differ per relay and are mapped in presets.
-- **No cost estimation** (there is no price table).
-- **No automatic failover** (v1, see above).
-- **No multi-model aggregation** — this is "one model, many sources", not a model router.
+**Images**: sending and receiving images is supported.
 
-## Contributing
+**Legacy config**: early versions stored the key in `apiKeyEnv`. That field is still read — a value
+that looks like an environment-variable name is resolved as one, otherwise it is used as the key
+itself. `apiKey` always wins, so re-entering the key once in the panel migrates the entry.
 
-Fork, file an issue, send a PR. Especially welcome:
+## Boundaries
 
-- **Add a relay** — one file, see above.
-- **Fix a sentence** — every line in the panel is supposed to be a verifiable fact. If one is
-  vague or stale, change it.
-- **Report "installed but nothing happens"** — silent failure is the most expensive class of bug
-  in this project, and a reproduction is worth more than any guess.
-
-Source: <https://github.com/tellmewhattodo/dsh-any-deepseek>
+- Does not modify Harness itself, and does not replace the built-in `deepseek-official` route.
+- Exposes exactly one model id (`deepseek-v4.1-flash`); per-provider upstream ids are mapped by
+  presets.
+- **No cost estimation** — there is no price table, only token counts.
+- **No automatic failover** (v1).
+- **No multi-model aggregation**.
 
 ## License
 
-MIT
+MIT. This is a small practical tool — forks, issues and PRs are welcome. See
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+<https://github.com/tellmewhattodo/dsh-any-deepseek>

package/README.md

@@ -1,248 +1,199 @@
 # dsh-any-deepseek
 
-把多家 DeepSeek 中转站收成**一个** provider、**一个**模型，在设置面板里粘 key、点一下切换。
+**在 DeepSeek Harness 里，用多家渠道的 DeepSeek 额度，而模型列表里只多出一行。**
 
-一个开源小工具（MIT）。欢迎改、欢迎加渠道 —— 见 [参与改进](#参与改进)。
+你在好几处买过 DeepSeek 的额度：官方、某家中转、某个云厂商、朋友推荐的便宜渠道。
+这个插件把它们收进**一个** provider，你粘几个 key、点一下就能换 —— 同时按真实渠道分开记账，
+你知道这个月每一家各花了多少 token。
 
-[English](README.en.md) · 中文（本页）
+![渠道列表](docs/screenshot-channels.png)
 
-![渠道分页](docs/screenshot-channels.png)
+[English](README.en.md) · 中文（本页）
 
 ---
 
-## 它解决的是什么问题
+## 装之前先看一眼：它适合你吗
 
-你在好几个地方买了 DeepSeek 的额度：官方、某家中转、某个云厂商、某个同事推荐的便宜渠道。
-在 DeepSeek Harness 里，它们本来会变成**模型选择器里的 N 个条目**，而每次换渠道都要改配置、
-换模型名、换 key，还得自己记住这个月哪个渠道花了多少 token。
+**适合**，如果你符合下面任意一条：
 
-装了这个插件之后：
+- 你有**不止一个** DeepSeek 渠道，并且想在 Harness 里随意切换而不用改配置。
+- 你想要**按渠道分开的用量统计**，而不是所有请求混成一个总数。
+- 你用中转站，而它们的模型名各不相同（`deepseek-v4.1-flash` / `deepseek/deepseek-v4.1-flash` /
+  `deepseek-flash`），懒得每次自己对应。
 
-- 模型选择器里只有**一行**：`any-deepseek / deepseek-v4.1-flash`。
-- 下面挂**任意多个渠道**，每个渠道 = 一个端点 + 一个 key + 一个显示名。
-- 点哪个渠道的圆点，请求就发到哪个。**不会自动切换**（见 [为什么不做自动切换](#为什么不做自动切换)）。
-- 用量按**真实上游**分别记账。
+**不适合**，如果：
 
-```
-                ┌── 渠道 A（官方）      ← 当前选中这个
-composer ──────►│
-  │             ├── 渠道 B（某中转）
-  ▼             └── 渠道 C（另一家）
-any-deepseek
-  / deepseek-v4.1-flash
-   （唯一对外模型）
-```
+- 你只有一个渠道，且它就是官方 —— Harness 自带的 `deepseek-official` 已经够用，不必装。
+- 你想要**自动故障转移**（一家挂了自动换下一家）。本插件 v1 不做，见 [为什么不做自动切换](#为什么不做自动切换)。
+- 你想要**多模型切换**。这个插件是「一个模型、多个来源」，不是模型路由器。
 
 ## 安装
 
+需要已经装好 DeepSeek Harness。在终端执行：
+
 ```bash
 dsh plugin --profile web add dsh-any-deepseek
 ```
 
 然后**重启 DSH**，打开 设置 → **Any DeepSeek**。
 
-> **首次安装必须重启**：profile 的分层列表变了，而装配图是启动时构建的。
-> 改已装插件的 client 半只需刷新浏览器；改它的 node 半则要重启。
->
-> `dsh plugin` 会把参数转给 pnpm，所以 `add` 后面可以是 registry 名、tarball 路径或本地目录。
-
-## 用法
-
-### 加一个渠道
-
-点 **添加渠道**，只有两样东西是必填的：
-
-| 字段 | 必填 | 说明 |
-|---|---|---|
-| **规格** | ✅ | 决定端点地址、上游模型名、协议。选它这三样就不用填了。 |
-| **渠道 id** | ✅ | 配置里的键名，`[a-z0-9][a-z0-9_-]*`。同规格可加多次，第二个自动变成 `-2`。 |
-| **显示名** | — | 只影响界面显示。同一家开两个号时靠它区分。**改名不动 id。** |
-| **密钥** | ✅ | 服务商给你的那串 key 本体，不需要先起名字。 |
-
-内置规格：**DeepSeek 官方**、**OpenCode Go**、**Ollama Cloud**、**Open Design**、**CommandCode**。
-想接别的中转，见 [加一个新渠道](#加一个新渠道要改什么)。
-
-### 切换渠道
+> **为什么必须重启**：插件被加进了 profile 的加载列表，而这份列表只在 DSH 启动时读取。
+> 之后改这个插件的界面部分只需刷新浏览器，但**第一次装**一定要重启。
 
-点行左边的圆点。当前渠道有三重标识：左侧色条、更强边框、底色，另加 `aria-current`。
+## 第一次用：三步
 
-**切换会让当前对话的 prompt 缓存失效**，所以尽量在自然的断点切，或新开一个会话。
+### 第 1 步：加一个渠道
 
-### 看余额
+点 **添加渠道**，填两个必填项就能用：
 
-点 **查询余额**（按需触发，不在打开面板时自动扫）。四种结果被严格区分，因为它们的下一步动作不同：
+![添加渠道](docs/screenshot-add-channel.png)
 
-| 显示 | 含义 |
+| 填什么 | 说明 |
 |---|---|
-| `642.44 CNY` / `55.48 USD` | 读到了金额 |
-| `rolling 100% · weekly 81% · monthly 75%` | 这家只给**订阅窗口**，不给钱 |
-| **余额未尽**（无余额接口，实测可用：…） | 这家没有余额接口，但**实测能用** ⇒ 账户没欠费。**不代表余额数字**（见下） |
-| 不支持查询 / 读取失败 / 未配置密钥 | 三种不同的"没有" |
+| **规格** | 选你用的那家。它决定地址、模型名、协议，所以这三样你不用管。 |
+| **密钥** | 那家给你的 key，直接粘。不需要先起名字。 |
 
-> ⚠️ **余额未尽 ≠ 余额还有多少。** 它是一次最小真实请求（消耗一两个 token）成功的结果，
-> 只证明三件事：端点在线、key 可用、账户**没有**因为欠费被拒（欠费会答 402/quota，不答 200）。
-> 所以面板只写「未尽」，**绝不编一个金额**——写 `0.00` 会被读成"你没钱了"，与事实正相反。
+**渠道 id** 会自动填好（可以改，只是配置里的键名）。**显示名**留空的话用规格的默认名 ——
+同一家开两个号时，填上「主号」「备号」之类会好认。
 
-> ⚠️ **绝不用 0 代替"读不到"。** 缺数字就报缺。"读不到"与"是空的"导致相反的行动。
+内置规格：DeepSeek Official、OpenCode Go、Ollama Cloud、Open Design、CommandCode
+（这些名字与下拉框里显示的完全一致）。
+要接别家，见 [接一个新渠道](#接一个新渠道)。
 
-### 看用量
+### 第 2 步：确认它选中了
 
-![用量分页](docs/screenshot-usage.png)
+第一个加进去的渠道会**自动成为当前渠道**，行首有圆点、左侧有色条、右侧有「当前」标记。
 
-每个渠道一行，可以按渠道或按天分组。
+以后想换：点那一行左边的圆点即可。
 
-**口径**（面板里也印着）：harness 的 token 计数是**不相交**的 —— **输入**只算未命中缓存的输入，
-**缓存读** / **缓存写**单独成列，三者相加才是**计费输入**。把「输入」直接当总量会得出
-"输入被少报了"的错误结论。
+### 第 3 步：开始用
 
-**速度**只算生成阶段（总时长减去首字等待）。把排队 + 首字 + 生成混成一个数，会让
-"想得久但吐得快"和"全程都慢"读数相同，而这两者的处理方式完全相反。
-`—` 表示没测到，**不是 0**。
+在模型的对话界面里选模型，选 **DeepSeek V4.1 Flash**（provider 名是 `any-deepseek`）。
+之后所有请求都会发到你选中的那个渠道。
 
-## 配置
+## 日常会用到的三件事
 
-设置都在这一个命名空间下 —— 它是 `cordis.patch.yml` 里的 **profile 条目 id**，面板绑定的就是它：
-
-```yaml
-dsh-any-deepseek:
-  current: opencode-go          # 当前渠道
-  channels:
-    opencode-go:
-      apiKey: sk-…              # key 本体
-    open-design:
-      preset: open-design
-      label: Open Design（主号）  # 可选，显示名
-  usage:
-    enabled: true
-```
+### 换一个渠道
 
-`channels.<id>` 有两种写法：
+点行首的圆点。
 
-- **预设背书** — `preset: opencode-go`，可选覆盖若干字段；
-- **完全手写** — `baseURL` + `model` 必填，`api` 默认 `openai-completions`，
-  `contextWindow` / `maxTokens` 有文档值兜底（走兜底时面板会在该行显示 ⚠）。
+> ⚠️ **换渠道会让当前对话的 prompt 缓存失效**，所以尽量在话题切换时换，或者干脆新开一个会话。
 
-### key 存在哪（请读完这段）
+### 看还剩多少钱
 
-`apiKey` 存的是 **key 本人**，就在渠道条目上。面板不会让你给它起名字 —— 你粘 key，它就写在这儿。
+点 **查询余额**。它不会在打开面板时自动跑 —— 因为每次都要请求每一家的服务器。
 
-⚠️ **这意味着 key 在你的 profile 配置文件里。** `dsh --dump-config` 逐字打印 patch 层且
-**不脱敏**，所以一次诊断输出、一次 `git diff` 都会带上它。**别把 profile 文件发给别人。**
-环境变量注入（`-e SOME_KEY=…`）不会被查询 —— 没有任何地方去解析一个名字。
+不同家能给出的东西不一样，面板会如实区分：
 
-> 早期版本把 key 藏在"凭据引用名"后面，并提示你"到凭据中心设置" —— 而这个界面本身并不存在。
-> 现在的做法是：一个字段、一个存储、一次写入。
+| 你看到的 | 意思 |
+|---|---|
+| `642.44 CNY`、`55.48 USD` | 这家能报金额 |
+| `rolling 100% · weekly 81% · monthly 75%` | 这家只给**订阅用量百分比**，不给钱 |
+| **余额未尽**（实测可用：…） | 这家**没有余额接口**，但我发了一次最小请求，**它答了** ⇒ 账户没停 |
+| 不支持查询 / 读取失败 / 未配置密钥 | 三种不同的「没拿到」 |
 
-`apiKeyEnv` 仍会**读**，为了兼容旧配置：值符合引用名语法（`^[A-Za-z_][A-Za-z0-9_]*$`）时当名字解析；
-不符合时不可能是名字，于是当 key 本体用。`apiKey` 存在时永远优先，所以在面板里重填一次 key
-就把旧条目迁移完了。
+> **「余额未尽」不等于「还剩多少」。** 一次成功的请求只证明三件事：地址通、key 对、账户没因为欠费被拒
+> （欠费的账户会回 402，不会回 200）。所以这里只写「未尽」，**不会编一个金额给你**。
 
-没配 key 的渠道**照样出现在面板里** —— 那是你发现并修复它的方式。通过它发请求会失败
-（`MISSING_CREDENTIAL`），该行的状态点是空心的。
+### 看这个月花了多少
 
-### 协议
+切到 **用量** 分页。
 
-`openai-completions` 是默认也是推荐：几乎所有中转都说它，兼容位最多（约 20 个），
-且 usage 的三种缓存字段拼写（`prompt_tokens_details.cached_tokens` /
-`prompt_cache_hit_tokens` / 顶层 `cached_tokens`）已由传输层归一。
+![用量统计](docs/screenshot-usage.png)
 
-只有当某家真的说别的协议时才在**那一个渠道**上设 `api`（`openai-responses` / `anthropic-messages`）。
-面板永远不会背着你在渠道间改协议。
+可以按渠道看，也可以按天看。「输入」只算没命中缓存的部分，缓存读/写单独列出 ——
+三者相加才是计费输入。速度一栏的 `—` 表示没测到，**不是 0**。
 
-### 思考强度
+## 我的 key 安全吗
 
-每个渠道声明自己支持哪些档位，harness 里选的档位会一路传到上游：
+**它存在你本机的配置文件里，明文。**
 
-```
-harness reasoningEffort → pi-ai ThinkingLevel → model.thinkingLevelMap → wire value
-```
+位置是 profile 的 `channels.<渠道id>.apiKey`。它不会被这个插件发到任何第三方，
+但是：
 
-**本插件里没有第二层映射**：传输层用的 `thinkingLevelMap` **就是**映射层，再写一个必然与它漂移。
-声明成 `null` 的档位表示不支持，不会出现在选择器里。
+> ⚠️ `dsh --dump-config` 会把配置原样打印出来、**不做脱敏**。所以：
+> **别把 profile 配置文件发给别人**，也别把它的 `git diff` 贴到公开的地方。
 
-### 图片输入
+如果你需要分享配置做排查，先把 `apiKey` 那几行删掉。
 
-支持。两个渠道都可以收发图片，前提是宿主把 `input` 声明为含 `image` —— 该声明在**注册模型时**给出
-（`inputModalities`），不是写在请求处理里。这是个踩过的坑：能力是 provider 的属性，
-不是某条渠道或某次请求的属性。
+## 出问题了
 
-## 为什么不做自动切换
+**模型列表里没有 DeepSeek V4.1 Flash。**
+→ 装完还没重启。重启 DSH。
 
-v1 刻意只做手动。一个渠道失败就**报它自己的错**，不会静默转到另一个：
+**设置里找不到「Any DeepSeek」。**
+→ 同上；或确认装的是 `web` 这个 profile：`dsh plugin --profile web list`。
 
-- 静默切换会让"这次答案是谁给的"变得不可知，而用量表会照实记另一个渠道 —— 两处口径不一致。
-- 半途换渠道会让 prompt 缓存失效，成本比你省下的那次失败更高。
-- 失败是信息。把它藏起来，你就不知道某个渠道正在坏掉。
+**报 `MISSING_CREDENTIAL`。**
+→ 这个渠道还没填 key。面板里那一行的状态点是空心的，点「填写密钥」补上。
 
-## 加一个新渠道要改什么
+**报 `NO_CHANNEL_SELECTED`。**
+→ 一个渠道都没选中。面板底部会有提示，点任意一行的圆点即可。
 
-这是一个**实用小插件**，加渠道是最有价值的贡献 —— 大多数情况下只需要动一个文件。
+**「查询余额」显示「读取失败」。**
+→ 这家服务器这会儿没答好，稍后再试。如果一直这样，可能是网络到不了它。
 
-### 只加一个预设（最常见）
+**报 401 / 403 / 余额不足。**
+→ key 不对或过期，或者那家账户真的没钱了。
 
-改 [`src/presets.ts`](src/presets.ts)，往 `CHANNEL_PRESETS` 里加一条：
+**换渠道以后回答变慢/变差。**
+→ 不同家的模型行为不完全一样。用「测试」按钮逐家试，用「用量」分页看各家的速度。
 
-```ts
-'your-relay': {
-  displayName: 'Your Relay',
-  api: 'openai-completions',
-  baseURL: 'https://your-relay.example/v1',
-  // 🔴 用**这家自己的**拼写。各家中转的模型名不同：
-  //    deepseek-v4.1-flash / deepseek/deepseek-v4.1-flash / deepseek-flash …
-  //    抄错不会报错，只会在第一次请求时被上游拒。
-  model: 'deepseek-v4.1-flash',
-  ...V41_FLASH_CAPS,
-  // 可选：这家有没有余额接口、是什么形状（见 src/balance.ts 的四种 shape）
-  // balance: { shape: 'openai-billing' },
-},
-```
+## 为什么不做自动切换
 
-就够了 —— 面板的规格下拉会自动多出这一项。
+一个渠道失败就**报它自己的错**，不会静默换到另一家。三个理由：
 
-⚠️ **两条规矩**（都有实际代价）：
+- 静默切换会让「这次答案是谁给的」变得不可知，而用量表会照实记另一家 —— 两处对不上。
+- 半路换渠道会让 prompt 缓存失效，成本比你省下的那次失败更高。
+- 失败是信息。藏起来，你就不知道某家正在坏掉。
 
-1. **注释里不要写"我探过了"，除非真的探过。** 这个仓里曾经有一条
-   `Probed live: the billing pair answers` 的注释，而它从没被调用过，第一次真调用就 404。
-   **假证据比没有注释更坏**，因为它让下一个读者不再去查。
-2. **`model` 用上游的拼写，不是我们的 id。** 我们对外只暴露 `deepseek-v4.1-flash` 一个 id，
-   上游拼写由预设吸收 —— 这正是这个插件存在的理由。
+## 接一个新渠道
 
-### 加一种余额形状（少见）
+内置了 5 家，接别家通常只需要改一个文件。见 **[CONTRIBUTING.md](CONTRIBUTING.md)**。
 
-如果这家有余额接口但形状是新的一种，改 [`src/balance.ts`](src/balance.ts)：
-加一个 `shape`、加一个 `parseXxx()`、在 `balanceUrls()` 里给路径、在 `readBalance()` 里分发。
-`balanceUrls()` 是**唯一**知道路径的地方，所以预设无法与传输层意见相左。
+## 配置参考（进阶）
 
-### 门禁（提交前必跑）
+设置都在 `dsh-any-deepseek` 这个命名空间下：
 
-```bash
-pnpm run typecheck     # 两个 tsconfig：node 半 + client 半
-pnpm run test          # 纯函数层，不需要 harness
-pnpm run build         # lib/index.js + lib/client.js
+```yaml
+dsh-any-deepseek:
+  current: opencode-go          # 当前渠道
+  channels:
+    opencode-go:
+      apiKey: sk-…              # key 本体
+    open-design:
+      preset: open-design       # 用内置规格
+      label: Open Design（主号）  # 可选，显示名
+    my-relay:
+      baseURL: https://relay.example/v1   # 或者完全手写
+      model: deepseek-v4.1-flash
+      apiKey: sk-…
+  usage:
+    enabled: true
 ```
 
-改动要带**能变红的用例**。这个仓的规矩是：**判据必须承重** —— 把修复回滚，那条用例必须红；
-否则它只是装饰。仓里每条重要结论都附了它的负控制结果。
+**协议**：默认 `openai-completions`（几乎所有中转都说它）。只有当某家真的说别的协议时，
+在**那一个**渠道上设 `api: openai-responses` 或 `api: anthropic-messages`。
 
-## 已知边界
+**思考强度**：每个渠道声明自己支持哪些档位，你在界面上选哪档就传到哪档。
+声明成不支持的档位不会出现在选择器里。
 
-- 不修改 harness，也不替代 `deepseek-official` / `llm-pi-ai` 路由。
-- 只暴露一个模型 id。上游模型 id 各家不同，由预设映射。
-- **不做费用估算**（没有价目表）。
-- **不做自动故障转移**（v1，见上）。
-- **不做多模型聚合** —— 这个插件就是"一个模型、多个来源"，不是模型路由器。
+**图片**：支持收发图片。
 
-## 参与改进
+**兼容旧配置**：早期版本把 key 存在 `apiKeyEnv` 里。这个字段仍会被读：
+值像环境变量名就当名字解析，不像就直接当 key 用。`apiKey` 存在时永远优先 ——
+所以在面板里重填一次 key 就迁移完了。
 
-欢迎 fork、提 issue、发 PR。特别是：
+## 边界
 
-- **加一家渠道** —— 见上，改一个文件。
-- **修一处文案** —— 面板上的每一句都应该是一个可验证的事实；读到含糊或过时的，直接改。
-- **报一个"装了但没反应"** —— 这类静默失效是本项目最花时间的一类缺陷，
-  复现步骤比任何猜测都值钱。
-
-源码：<https://github.com/tellmewhattodo/dsh-any-deepseek>
+- 不修改 Harness 本体，也不替代自带的 `deepseek-official` 路由。
+- 只暴露一个模型 id（`deepseek-v4.1-flash`）；各家的上游模型名由规格映射。
+- **不做费用估算** —— 没有价目表，只有 token 数。
+- **不做自动故障转移**（v1）。
+- **不做多模型聚合**。
 
 ## 许可
 
-MIT
+MIT。这是个实用小工具，欢迎 fork、提 issue、发 PR —— 见 [CONTRIBUTING.md](CONTRIBUTING.md)。
+
+<https://github.com/tellmewhattodo/dsh-any-deepseek>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-any-deepseek",
-  "version": "0.0.16",
+  "version": "0.0.17",
   "description": "One DeepSeek V4.1 Flash provider for DeepSeek Harness: paste a key per channel, switch channels manually, token usage booked per real upstream.",
   "license": "MIT",
   "repository": {
@@ -30,6 +30,7 @@
     "cordis.patch.yml",
     "README.md",
     "README.en.md",
+    "CONTRIBUTING.md",
     "docs/*.png",
     "LICENSE"
   ],