dsh-any-deepseek 0.0.15 → 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

@@ -0,0 +1,217 @@
+# dsh-any-deepseek
+
+**Use DeepSeek credit from several providers inside DeepSeek Harness — with one extra row in the
+model list, not N.**
+
+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.
+
+![Channel list](docs/screenshot-channels.png)
+
+[中文](README.md) · English (this page)
+
+---
+
+## Before you install: is this for you?
+
+**Yes**, if any of these is true:
+
+- 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.
+
+**No**, if:
+
+- 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**.
+
+> **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.
+
+## First run: three steps
+
+### 1. Add a channel
+
+Click **添加渠道** (Add channel). Two fields are required:
+
+![Add channel](docs/screenshot-add-channel.png)
+
+| 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. |
+
+**渠道 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".
+
+Bundled presets: DeepSeek Official, OpenCode Go, Ollama Cloud, Open Design, CommandCode.
+For another provider, see [Adding a provider](#adding-a-provider).
+
+### 2. Make sure it is selected
+
+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.
+
+To switch later: click the dot at the left of a row.
+
+### 3. Start using it
+
+In the model picker, choose **DeepSeek V4.1 Flash** (the provider is `any-deepseek`).
+Every request then goes to whichever channel you selected.
+
+## Three things you will actually do
+
+### Switch channels
+
+Click the dot at the left of a row.
+
+> ⚠️ **Switching invalidates the prompt cache for the running conversation**, so switch at a topic
+> boundary, or just start a new session.
+
+### See how much credit is left
+
+Click **查询余额** (Check balance). It does not run when the panel opens — each check calls every
+provider's server.
+
+Different providers can report different things, and the panel keeps them apart:
+
+| 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" |
+
+> **"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**.
+
+### See what this month cost
+
+Switch to the **用量** (Usage) tab.
+
+![Usage](docs/screenshot-usage.png)
+
+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**.
+
+## Is my key safe
+
+**It is stored in your local configuration file, in plaintext.**
+
+The path is `channels.<channel-id>.apiKey` inside the profile. The plugin never sends it to any
+third party, but:
+
+> ⚠️ `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.
+
+If you need to share config for troubleshooting, delete the `apiKey` lines first.
+
+## Troubleshooting
+
+**The model list has no DeepSeek V4.1 Flash.**
+→ You have not restarted since installing. Restart DSH.
+
+**Settings has no "Any DeepSeek".**
+→ Same; or check you installed into the `web` profile: `dsh plugin --profile web list`.
+
+**`MISSING_CREDENTIAL`.**
+→ That channel has no key yet. Its status dot is hollow; click 「填写密钥」 to add one.
+
+**`NO_CHANNEL_SELECTED`.**
+→ No channel is selected. The panel shows a hint at the bottom; click any row's dot.
+
+**「查询余额」 shows 「读取失败」.**
+→ That provider did not answer properly just now; retry. If it never works, your network may not
+reach it.
+
+**401 / 403 / out of credit.**
+→ The key is wrong or expired, or that account really is out of money.
+
+**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
+
+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 provider — the two parts would disagree.
+- Switching mid-conversation invalidates the prompt cache, costing more than the failure saved.
+- Failure is information. Hide it and you never learn a provider is degrading.
+
+## Adding a provider
+
+Five are bundled; adding another usually touches one file. See
+**[CONTRIBUTING.md](CONTRIBUTING.md)**.
+
+## Configuration reference (advanced)
+
+Everything lives under the `dsh-any-deepseek` namespace:
+
+```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
+```
+
+**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.
+
+**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.
+
+**Images**: sending and receiving images is supported.
+
+**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.
+
+## Boundaries
+
+- 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. 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,172 +1,199 @@
 # dsh-any-deepseek
 
-One **DeepSeek V4.1 Flash** provider for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).
-
-Instead of configuring every third-party DeepSeek relay as its own provider, install one
-provider with **exactly one model**, paste a key per channel in the settings panel, and pick
-which channel is live. Token usage is booked **per real upstream**, so you can see what each
-relay actually cost you in tokens.
-
-```text
-composer → any-deepseek / deepseek-v4.1-flash
-                │
-                ├─ channel selected in the panel (manual switch, v1)
-                ├─ key resolved from ctx.credentials per request
-                └─ forwarded as openai-completions to the channel's endpoint
-```
+**在 DeepSeek Harness 里，用多家渠道的 DeepSeek 额度，而模型列表里只多出一行。**
+
+你在好几处买过 DeepSeek 的额度：官方、某家中转、某个云厂商、朋友推荐的便宜渠道。
+这个插件把它们收进**一个** provider，你粘几个 key、点一下就能换 —— 同时按真实渠道分开记账，
+你知道这个月每一家各花了多少 token。
+
+![渠道列表](docs/screenshot-channels.png)
+
+[English](README.en.md) · 中文（本页）
+
+---
+
+## 装之前先看一眼：它适合你吗
 
-## Why
+**适合**，如果你符合下面任意一条：
 
-- **One row in the model picker.** Your relay list stops being N provider groups.
-- **Only a key is user input.** Endpoint, upstream model id, context window, output cap and
-  compatibility flags ship in the plugin's own preset table.
-- **Per-channel accounting.** Input / cache-read / cache-write / output are recorded per
-  request and grouped by the channel that actually served it.
-- **Keys never enter configuration.** They live in the harness credential store; the config
-  only carries the reference name, exactly like the official Models page.
+- 你有**不止一个** DeepSeek 渠道，并且想在 Harness 里随意切换而不用改配置。
+- 你想要**按渠道分开的用量统计**，而不是所有请求混成一个总数。
+- 你用中转站，而它们的模型名各不相同（`deepseek-v4.1-flash` / `deepseek/deepseek-v4.1-flash` /
+  `deepseek-flash`），懒得每次自己对应。
 
-## Install
+**不适合**，如果：
+
+- 你只有一个渠道，且它就是官方 —— Harness 自带的 `deepseek-official` 已经够用，不必装。
+- 你想要**自动故障转移**（一家挂了自动换下一家）。本插件 v1 不做，见 [为什么不做自动切换](#为什么不做自动切换)。
+- 你想要**多模型切换**。这个插件是「一个模型、多个来源」，不是模型路由器。
+
+## 安装
+
+需要已经装好 DeepSeek Harness。在终端执行：
 
 ```bash
 dsh plugin --profile web add dsh-any-deepseek
 ```
 
-Then restart DSH and open **Settings → Any DeepSeek**.
+然后**重启 DSH**，打开 设置 → **Any DeepSeek**。
 
-> **Restart is required for a first install** — the profile's layer list changed, and the
-> composing graph is built at boot. Editing an already-installed plugin's client half reloads
-> in the browser without a restart; 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 (which installs as a symlink).
+> **为什么必须重启**：插件被加进了 profile 的加载列表，而这份列表只在 DSH 启动时读取。
+> 之后改这个插件的界面部分只需刷新浏览器，但**第一次装**一定要重启。
 
-## Configuration
+## 第一次用：三步
 
-Everything lives under the `dsh-any-deepseek` settings namespace — that is the **profile entry
-id** from `cordis.patch.yml`, and it is what the panel binds to:
+### 第 1 步：加一个渠道
 
-```yaml
-dsh-any-deepseek:
-  current: opencode-go          # the live channel (manual)
-  channels:
-    opencode-go:
-      apiKey: sk-…              # the key itself
-    commandcode:
-      apiKey: sk-…              # the key itself
-  usage:
-    enabled: true
-```
+点 **添加渠道**，填两个必填项就能用：
 
-`channels.<id>` may be either:
+![添加渠道](docs/screenshot-add-channel.png)
 
-- **preset-backed** — `preset: opencode-go` plus optional overrides; or
-- **fully declared** — `baseURL` + `model` are required; `api` defaults to
-  `openai-completions`, and `contextWindow` / `maxTokens` fall back to documented defaults
-  (the panel shows a warning next to the row when a default was applied rather than declared).
+| 填什么 | 说明 |
+|---|---|
+| **规格** | 选你用的那家。它决定地址、模型名、协议，所以这三样你不用管。 |
+| **密钥** | 那家给你的 key，直接粘。不需要先起名字。 |
 
-### Where the key lives
+**渠道 id** 会自动填好（可以改，只是配置里的键名）。**显示名**留空的话用规格的默认名 ——
+同一家开两个号时，填上「主号」「备号」之类会好认。
 
-`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.
+内置规格：DeepSeek Official、OpenCode Go、Ollama Cloud、Open Design、CommandCode
+（这些名字与下拉框里显示的完全一致）。
+要接别家，见 [接一个新渠道](#接一个新渠道)。
 
-⚠️ **That means the key is in your profile configuration.** `dsh --dump-config` prints patch
-layers verbatim and does not redact, so a diagnostic dump, a `git diff` of the profile, or a
-pasted config includes it. Do not share the profile document. Environment-variable injection
-(`-e SOME_KEY=…`) is not consulted — nothing resolves a name.
+### 第 2 步：确认它选中了
 
-`apiKeyEnv` is still **read** for configurations written before this change: when its value
-matches the credential-reference grammar (`^[A-Za-z_][A-Za-z0-9_]*$`) it is resolved as a name;
-when it does not, it cannot be a name, so it is adopted as the key itself. `apiKey` always wins
-when both are present, so re-keying through the panel is enough to migrate an entry.
+第一个加进去的渠道会**自动成为当前渠道**，行首有圆点、左侧有色条、右侧有「当前」标记。
 
-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 the row shows an unconfigured dot.
+以后想换：点那一行左边的圆点即可。
 
-### Channels vs. protocols
+### 第 3 步：开始用
 
-`openai-completions` is the default and the recommended protocol: it is what almost every
-relay speaks, 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`).
+在模型的对话界面里选模型，选 **DeepSeek V4.1 Flash**（provider 名是 `any-deepseek`）。
+之后所有请求都会发到你选中的那个渠道。
 
-Set `api` on one channel only when that relay speaks something else (`openai-responses`,
-`anthropic-messages`). The picker never changes per channel behind your back.
+## 日常会用到的三件事
 
-### Switching channels
+### 换一个渠道
 
-v1 is deliberately manual. A channel that fails reports its error; it does not silently fail
-over to another one. Switching invalidates the prompt cache for the running conversation, so
-switch at a natural boundary (or start a new session).
+点行首的圆点。
 
-The current channel is marked on its row (left colour bar, stronger border, tinted background)
-rather than by a small badge — a single-choice list has to be readable at a glance.
+> ⚠️ **换渠道会让当前对话的 prompt 缓存失效**，所以尽量在话题切换时换，或者干脆新开一个会话。
 
-### Thinking level
+### 看还剩多少钱
 
-Each channel declares its selectable thinking levels, and the level picked in the harness is
-passed through to the relay:
+点 **查询余额**。它不会在打开面板时自动跑 —— 因为每次都要请求每一家的服务器。
 
-```
-harness reasoningEffort → pi-ai ThinkingLevel → model.thinkingLevelMap → wire value
-```
+不同家能给出的东西不一样，面板会如实区分：
 
-There is no mapping layer in this plugin: the `thinkingLevelMap` the transport applies **is**
-the mapping, and a second one here would drift from it. A level declared `null` is unsupported
-and is not offered in the picker.
+| 你看到的 | 意思 |
+|---|---|
+| `642.44 CNY`、`55.48 USD` | 这家能报金额 |
+| `rolling 100% · weekly 81% · monthly 75%` | 这家只给**订阅用量百分比**，不给钱 |
+| **余额未尽**（实测可用：…） | 这家**没有余额接口**，但我发了一次最小请求，**它答了** ⇒ 账户没停 |
+| 不支持查询 / 读取失败 / 未配置密钥 | 三种不同的「没拿到」 |
 
-### Display names
+> **「余额未尽」不等于「还剩多少」。** 一次成功的请求只证明三件事：地址通、key 对、账户没因为欠费被拒
+> （欠费的账户会回 402，不会回 200）。所以这里只写「未尽」，**不会编一个金额给你**。
 
-`label` is a free-form display name, and it is what tells two accounts on the same relay apart.
-Rename a channel from the panel; the channel **id** never changes, because the id is the
-channel's identity (its key and its `current` target hang off it).
+### 看这个月花了多少
 
-### Image input
+切到 **用量** 分页。
 
-Not supported yet, and declared as such. A harness `ImageBlock` carries only an
-`attachmentId`; turning that into request bytes requires the durable attachment service, which
-this adapter does not consult. Declaring image support anyway would make the harness stop
-substituting its placeholder text and drop the image silently — worse than declaring text-only.
+![用量统计](docs/screenshot-usage.png)
 
-## Usage accounting
+可以按渠道看，也可以按天看。「输入」只算没命中缓存的部分，缓存读/写单独列出 ——
+三者相加才是计费输入。速度一栏的 `—` 表示没测到，**不是 0**。
 
-The ledger is append-only JSONL, split by month, under the harness home:
+## 我的 key 安全吗
 
-```text
-~/.dsh/any-deepseek/usage-YYYY-MM.jsonl
-```
+**它存在你本机的配置文件里，明文。**
 
-One line per request:
+位置是 profile 的 `channels.<渠道id>.apiKey`。它不会被这个插件发到任何第三方，
+但是：
 
-```json
-{"at":"2026-10-19T10:12:03+08:00","channel":"opencode-go","model":"deepseek-v4.1-flash","ok":true,"ms":4210,"firstTokenMs":810,"usage":{"input":812,"output":96,"cacheRead":40960,"cacheWrite":0,"reasoning":0,"total":41868}}
-```
+> ⚠️ `dsh --dump-config` 会把配置原样打印出来、**不做脱敏**。所以：
+> **别把 profile 配置文件发给别人**，也别把它的 `git diff` 贴到公开的地方。
 
-`usage` is `null` when a relay does not report token counts — the panel shows `—`, never `0`,
-because a zero would read as "this request was free".
+如果你需要分享配置做排查，先把 `apiKey` 那几行删掉。
 
-**Counting convention.** `TokenUsage` counts are *disjoint*: `input` is uncached input only,
-cache reads and writes are reported separately, and the three together are the billable input.
-The stats table states this next to the numbers.
+## 出问题了
 
-## Development
+**模型列表里没有 DeepSeek V4.1 Flash。**
+→ 装完还没重启。重启 DSH。
 
-```bash
-pnpm install
-pnpm run typecheck     # host types come from pinned devDependencies
-pnpm run test          # pure layers only; no harness needed
-pnpm run build         # lib/index.js + lib/client.js
+**设置里找不到「Any DeepSeek」。**
+→ 同上；或确认装的是 `web` 这个 profile：`dsh plugin --profile web list`。
+
+**报 `MISSING_CREDENTIAL`。**
+→ 这个渠道还没填 key。面板里那一行的状态点是空心的，点「填写密钥」补上。
+
+**报 `NO_CHANNEL_SELECTED`。**
+→ 一个渠道都没选中。面板底部会有提示，点任意一行的圆点即可。
+
+**「查询余额」显示「读取失败」。**
+→ 这家服务器这会儿没答好，稍后再试。如果一直这样，可能是网络到不了它。
+
+**报 401 / 403 / 余额不足。**
+→ key 不对或过期，或者那家账户真的没钱了。
+
+**换渠道以后回答变慢/变差。**
+→ 不同家的模型行为不完全一样。用「测试」按钮逐家试，用「用量」分页看各家的速度。
+
+## 为什么不做自动切换
+
+一个渠道失败就**报它自己的错**，不会静默换到另一家。三个理由：
+
+- 静默切换会让「这次答案是谁给的」变得不可知，而用量表会照实记另一家 —— 两处对不上。
+- 半路换渠道会让 prompt 缓存失效，成本比你省下的那次失败更高。
+- 失败是信息。藏起来，你就不知道某家正在坏掉。
+
+## 接一个新渠道
+
+内置了 5 家，接别家通常只需要改一个文件。见 **[CONTRIBUTING.md](CONTRIBUTING.md)**。
+
+## 配置参考（进阶）
+
+设置都在 `dsh-any-deepseek` 这个命名空间下：
+
+```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
 ```
 
-The pure layers (`presets`, `channels`, `route`, `usage-ledger`) do not import the harness and
-are covered by the unit tests. The adapter and panel talk to the host through public seams
-only.
+**协议**：默认 `openai-completions`（几乎所有中转都说它）。只有当某家真的说别的协议时，
+在**那一个**渠道上设 `api: openai-responses` 或 `api: anthropic-messages`。
+
+**思考强度**：每个渠道声明自己支持哪些档位，你在界面上选哪档就传到哪档。
+声明成不支持的档位不会出现在选择器里。
+
+**图片**：支持收发图片。
+
+**兼容旧配置**：早期版本把 key 存在 `apiKeyEnv` 里。这个字段仍会被读：
+值像环境变量名就当名字解析，不像就直接当 key 用。`apiKey` 存在时永远优先 ——
+所以在面板里重填一次 key 就迁移完了。
+
+## 边界
 
-## Boundaries
+- 不修改 Harness 本体，也不替代自带的 `deepseek-official` 路由。
+- 只暴露一个模型 id（`deepseek-v4.1-flash`）；各家的上游模型名由规格映射。
+- **不做费用估算** —— 没有价目表，只有 token 数。
+- **不做自动故障转移**（v1）。
+- **不做多模型聚合**。
 
-- Does not modify the harness, and does not replace `deepseek-official` or `llm-pi-ai` routes.
-- Exposes exactly one model id. Upstream model ids differ per relay and are mapped in presets.
-- No cost estimation (no price table), no automatic failover (v1), no multi-model aggregation.
+## 许可
 
-## License
+MIT。这是个实用小工具，欢迎 fork、提 issue、发 PR —— 见 [CONTRIBUTING.md](CONTRIBUTING.md)。
 
-MIT
+<https://github.com/tellmewhattodo/dsh-any-deepseek>