dsh-kenari-plugin 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ryan-yuan-dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,281 @@
+# dsh-kenari-plugin
+
+English | [中文](README.md)
+
+Connects [Kenari](https://kenari.id) to the DeepSeek Harness (dsh):
+
+- Kenari models work as dsh session models, and the default route follows the plan attached to your key
+- Web search and fetch go to Kenari first, falling back to the dsh providers on failure
+- 21 REST capabilities registered as agent tools: catalog, account, search, OCR, images, audio, video, embeddings, rerank, moderation, billing, token counting
+- New session titles carry a local-time prefix, with a template you can change or turn off
+- Settings → Kenari holds everything in one page: credential status, runtime parameters, model catalog
+
+Every capability registers through dsh's bundle patch layer and its public seams (`ctx.web`, `ctx.settings`, `ctx.tools`). Nothing in dsh is modified.
+
+## Requirements
+
+You need dsh `0.1.5-rc.1` (installed globally, `dsh` on PATH), Node.js >= 22, and pnpm (`dsh plugin` forwards to it). dsh subpackages must match the main version, so pin the version when installing one; npm's `latest` is not necessarily the right one:
+
+```sh
+dsh plugin --profile web add @deepseek-ai/dsh-web-fetch-http@0.1.5-rc.1
+```
+
+## Install
+
+```sh
+dsh plugin --profile web add dsh-kenari-plugin
+dsh --profile web --dump-config | grep -A3 dsh-kenari-plugin   # confirm the patch layer applied
+dsh --profile web
+```
+
+To work on the plugin source, install from a clone instead: `pnpm install && pnpm build`, then `dsh plugin --profile web add "$PWD"`. The profile links to that directory, so after installing you only rerun `pnpm build` for source changes.
+
+## Set up your key
+
+In the Kenari dashboard, go to API keys → Create key and copy the `kn-...` value (shown once). Then either:
+
+- Open **Settings → Models → Kenari** and paste it into the password field
+- Or write a `.env` file, which the credential layer can write:
+
+```sh
+# ~/.dsh/.env
+KENARI_API_KEY=kn-...
+```
+
+Do not put it in `cordis.patch.yml`. The settings document stores the reference name only, and the value never reaches logs, the UI, or config.
+
+## Session models
+
+Installing the plugin adds a Kenari route to Settings → Models.
+
+### Default route
+
+The default models come from the plan attached to your key. On load, the plugin reads `GET /v1/account/quota` for the plan name, takes that plan's `free_cache_models` (models whose cache reads do not count against the plan), and writes them into the route. It writes once, then the layer is yours.
+
+When the plan cannot be read (no key, a share-page key that gets 403, an account without a plan), this fallback preset stands. It happens to be the free-cache list of the Kreator and Studio plans:
+
+| Model id | Display name | Context | Max output | Notes |
+| --- | --- | --- | --- | --- |
+| `deepseek-v4-flash` | DeepSeek v4 Flash | 1M | 64K | reasoning low/high/max |
+| `glm-5-3-flash` | GLM 5.3 Flash | 1M | 64K | vision, reasoning low/high/max |
+| `gpt-5-6-luna` | GPT 5.6 Luna | 872k | 64K | vision + PDF, 6 reasoning levels |
+| `mimo-v2-5` | MiMo v2.5 | 1.05M | 64K | vision + audio + video |
+
+None of the four is free, so **a new account with no balance hits 402 on its first session**. Add a `:free` model or top up first. `:free` models stay out of the route by default; filter by "free" in the picker to add them.
+
+Display names and output caps are derived by the plugin, since the catalog publishes neither. A name is reconstructed from the id, and the output cap is a quarter of the context window, clamped to [1K, 64K]; models without a published window get no cap field. The name is presentation only.
+
+Once you edit the list yourself, your config replaces the preset as a whole (pi-ai's semantics) and the plugin stops touching it.
+
+### Picking models by capability and plan
+
+Under **Settings → Models → Kenari → Edit → Model catalog**, "Add model" and "Get available models" are the same entry point, and either opens this picker. It uses dsh's own dialog components, with extra filter dimensions:
+
+- Each row shows the model id and capability tags (`image` `audio` `video` `pdf` `embedding`). Paid models also carry an "in plan" tag meaning a subscription plan covers them; free models are recognisable by the `:free` suffix
+- Filters are `in plan`, `free`, and the capability tags. "In plan" and "free" are mutually exclusive, and `embedding` is exclusive on its own (it has no chat endpoint, so mixing it with anything returns an empty list). The rest combine
+- "Add selected" **appends** to the current entries, and rows already in the route cannot be selected
+
+The write is immediate with no save step, and the list inside that card refreshes only after you collapse and reopen Edit. The Host computes the data and serves it at `GET /api/kenari.models`, the same facts as `kenari_list_models`, and no key is needed.
+
+### Three protocol lines and the compat preset
+
+Kenari serves three lines with different base URL shapes. A wrong shape answers 405, not 404:
+
+| pi-ai `api` | Base URL |
+| --- | --- |
+| `openai-completions` | `https://kenari.id/v1` |
+| `openai-responses` | `https://kenari.id/v1` |
+| `anthropic-messages` | `https://kenari.id` (no `/v1`) |
+
+Copy these four compat settings when you build your own route. They live in `cordis.patch.yml`:
+
+- `maxTokensField: max_tokens`. Kenari reads `max_tokens` only; sending `max_completion_tokens` returns 200 and silently ignores it
+- `supportsDeveloperRole: false`, so system prompts keep the `system` role
+- `supportsUsageInStreaming: true`, since the last streaming frame carries the `usage` that `cached_tokens` accounting relies on
+- `reasoningEfforts` keys must come from `off|minimal|low|medium|high|xhigh|max`. Kenari's `none` maps to `off`. A wrong key stops dsh from starting, so run `--dump-config` after editing
+
+## Web search and fetch
+
+Both `searchProvider` and `fetchProvider` are pinned to `kenari-fallback`: Kenari first, then `deepseek-official` and the anonymous local `http` on failure (401/402/403 and network errors included). The log records direction, reason, and elapsed time.
+
+The `available()` contract forbids network calls, so a Kenari outage only surfaces when a call fails and the user pays one extra round trip. To drop this layer, set `fallbackEnabled` to `false` (restart required).
+
+## Automatic recovery on model failure
+
+A failed session model call on a Kenari route recovers on its own:
+
+1. Retry 5 times at a fixed 5 second interval. dsh's own `dsh-llm-retry` does this and leaves an `llm/retry` record
+2. When retries run out, switch to a model with at least as large a window, preferring the smallest adequate one in the same provider before crossing providers
+3. If that also fails, fall back to dsh's default provider and model
+
+Only when all three fail does the turn error out. Retry and switching happen inside the same step, so the task is never interrupted and the plugin sends no "continue" message. A switched model does not inherit `reasoningEffort` (levels are per model); the switch injects a notice you can disable with `modelSwitchNoticeEnabled`, and picking a model yourself with `/model` clears the automatic switch.
+
+`CONTEXT_WINDOW_EXCEEDED` is deliberately not retryable. Retrying the same context on the same model can only fail again, so it goes straight to the model switch, which is often where recovery works.
+
+Two limits:
+
+- **Retry timing on the `llm-pi-ai` route comes from `providers.kenari.retryPolicy` in `cordis.patch.yml`, not from the plugin config.** dsh freezes a route's retry policy when the adapter registers, and the plugin cannot change it. The defaults match the plugin config, so change both together.
+- **A `TRANSPORT` failure may have completed and been billed on the server**, so retrying can bill twice. Narrow `modelRetryableCodes` if that matters. This is separate from the no-retry-on-timeout rule for generation endpoints.
+
+Field defaults are in "Configuration reference".
+
+## Session title prefix
+
+New session titles carry a prefix like `20260911174258-`. The timestamp is the time of the session's first human message, in local time. The plugin writes it into the `session/title` event, so Web, TUI, and headless render the same string.
+
+The timestamp does not come from `session.header.createdAt` (that records session creation, which dsh may have done hours earlier when it reused a blank session). It is the fallback for a session with no human message at all.
+
+The prefix is part of the title text, not a separate display layer, so the setting controls whether one is written at generation time: with it off, new titles have no prefix, and a title written while it was off contains no prefix in its text. Existing sessions are never rewritten, by the switch or the template.
+
+Every source gets the same treatment: LLM titles, the deterministic fallback, and manual renames. When a fork inherits its parent's title, the prefix becomes the child's own start time, ignoring the inherited history.
+
+Three things to keep in mind:
+
+- `sessionTitleMaxBytes` must match `maxTitleBytes` on the `session-title` row in `cordis.patch.yml`. The plugin writes title events directly and dsh will not truncate them
+- The template has no escaping, so substrings like `yyyy` and `MM` are always replaced, and stripping an old prefix replays the template against the session's start time. A template changed between parent and fork, or a parent no longer in the store, can leave a double prefix
+- A prefix already stored in the sidebar is a cached value; restart dsh and open that session and it corrects itself
+
+Field defaults are in "Configuration reference".
+
+## Billing and budget
+
+Each tool call returns a cost line: `cost_micro_idr` when the response carries it, otherwise an estimate from the catalog's `pricing_lines` multiplied by quantity for images, video, and speech. Non-token units round up to whole units (a 21-character TTS call counts as one 1k-character unit).
+
+`kenari_billing` reports per-session totals, a breakdown by tool and model, `cached_tokens` hit rate, remaining budget, and wallet balance; below `lowBalanceAlertRp` the cost line gains a warning. `budgetCapRp` defaults to 0, meaning no cap, and spending tools are refused once it is reached. The pre-check only sees recorded spending, so it stops new billed calls rather than guaranteeing a total. 402, 401, 405, and 403 all carry actionable guidance.
+
+## Settings page
+
+Settings → **Kenari** (namespace `kenari`). The groups follow the order you use them:
+
+| Group | Contents |
+| --- | --- |
+| Key | Status and names only (configured or missing, source, writability, a read-only reference name). No input field |
+| Models | Models the current route can use: id, display name, context. Only the first 3 show by default |
+| Session titles | Switch, prefix format, byte ceiling |
+| Advanced (collapsed) | API base URL, timeouts, retry counts, cache lifetimes, low-balance threshold |
+| Restart required (collapsed) | Switches fixed at load time (whether to register search/fetch/tools, budget cap, the built-in adapter). Read-only; edit the matching settings section and restart |
+| Balance and usage | Numbers that move with usage. No stored snapshot, just a question you can ask as-is |
+
+Copy exists in Chinese and English and follows dsh's language setting; `pnpm build` asserts the two key sets match.
+
+## Tools
+
+| Category | Tools |
+| --- | --- |
+| Catalog and docs | `kenari_list_models` (free grouping, pricing, context, sunset and beta warnings; no key needed), `kenari_search_docs` (also no key) |
+| Account | `kenari_balance`, `kenari_usage`, `kenari_quota` (share-page keys get 403) |
+| Search | `kenari_x_search` |
+| Documents | `kenari_ocr` (`reuse_id` reuses free) |
+| Media | `kenari_image_generate`, `kenari_image_edit`, `kenari_speech`, `kenari_transcribe`, `kenari_music`, `kenari_video_generate`, `kenari_video_extend`, `kenari_video_status`, `kenari_video_content` |
+| Data | `kenari_embed`, `kenari_rerank`, `kenari_moderate` |
+| Context and billing | `kenari_count_tokens`, `kenari_billing` |
+
+Images, audio, and video land on disk through `ctx.attachments` as image or file blocks rather than going into JSON.
+
+The public catalog has no music or moderation model, so `kenari_music` and `kenari_moderate` only return 400. `kenari_speech` works with `mimo-v2-5-tts`, while `kokoro-tts` and `gemini-3-1-flash-tts` return an upstream 400.
+
+## Optional: the plugin's own LlmAdapter
+
+The `llm-pi-ai` preset already runs Kenari as a session model. Setting `nativeAdapterEnabled` to `true` (restart required) adds pricing in the model picker, token accounting and `cached_tokens` hit rate in `kenari_billing`, and reasoning levels exposed exactly as the catalog reports them, `none` included.
+
+Its route is named `kenari-direct` by default, distinct from the preset's `kenari`, so both coexist and turning the switch off reverts. Compared with the preset it does not replay thinking blocks, inject `file-parser` (file blocks project to explanatory text, so use `kenari_ocr` to read documents), or map `web_search_options`; image input works.
+
+```yaml
+- id: kenari
+  config:
+    nativeAdapterEnabled: true
+    nativeProviderId: kenari-direct
+```
+
+## Troubleshooting
+
+| Symptom | Cause and fix |
+| --- | --- |
+| 401 `invalid api key` | The key is dead; dsh was not restarted after a `.env` edit; the credential reference name is wrong |
+| 402 `insufficient_balance` | A paid model with a zero balance. Switch to a `:free` model or top up |
+| 405 | Wrong base URL shape, see "Three protocol lines" |
+| Startup fails with `invalid config ... reasoningEfforts` | That model's `reasoningEfforts` key is outside `off..max`. Revert it or drop the model from the preset |
+| 403 on balance, usage, or quota | The key came from a share page, and those tools read the key owner's account data |
+| The Kenari card in settings is blank | The client bundle was not built, or the service name is wrong. Run `pnpm build` and restart |
+| The nav row still shows a gear | The image did not load. Check that the package contains `assets/kenari-favicon-128.png` and that `GET /api/kenari.favicon` responds |
+| The model list is empty | The preset did not apply. Check `llm-pi-ai` in `dsh --profile web --dump-config` |
+
+## Optional: MCP without the plugin
+
+Kenari ships a Streamable HTTP MCP server with 8 tools, named with the `mcp__kenari__` prefix:
+
+```json
+{ "mcpServers": { "kenari": { "url": "https://kenari.id/mcp", "headers": { "Authorization": "Bearer kn-..." } } } }
+```
+
+The trade is prefixed tool names, no cost visibility or balance warnings, and one more runtime dependency. MCP is for a quick trial.
+
+## Uninstall
+
+```sh
+dsh plugin --profile web remove dsh-kenari-plugin
+```
+
+Everything the plugin registers hangs off a Cordis fiber and is reclaimed on unload; no dsh package or config was changed.
+
+## Configuration reference
+
+Most fields can be edited under Settings → Kenari. The ones marked (restart) belong in the matching settings section followed by a restart.
+
+| Field | Default | Notes |
+| --- | --- | --- |
+| `apiKeyEnv` | `KENARI_API_KEY` | Credential reference holding the key |
+| `baseURL` | `https://kenari.id` | Kenari REST base URL used by the plugin |
+| `timeoutMs` | `30000` | Per-request REST timeout |
+| `generationTimeoutMs` | `180000` | Per-attempt timeout for generation calls (image/audio/music/OCR) |
+| `maxRetries` | `2` | REST retries for transient failures |
+| `searchEnabled` | `true` | Register the search provider (restart) |
+| `fetchEnabled` | `true` | Register the fetch provider (restart) |
+| `fallbackEnabled` | `true` | Fall back to the dsh defaults when Kenari fails (restart) |
+| `toolsEnabled` | `true` | Register the 21 tools (restart) |
+| `docsCacheTtlMs` | `3600000` | Cache lifetime for `/llms-full.txt` |
+| `catalogCacheTtlMs` | `3600000` | Cache lifetime for `/v1/models` |
+| `modelAliases` | `{}` | Model aliases as `{ alias: 'exact-model-id' }` |
+| `lowBalanceAlertRp` | `5000` | Warn below this many Rupiah, 0 disables |
+| `balanceCacheTtlMs` | `300000` | Cache lifetime for the wallet balance |
+| `budgetCapRp` | `0` | Per-session spend ceiling, 0 means no cap |
+| `nativeAdapterEnabled` | `false` | Register the plugin's own LlmAdapter (restart) |
+| `nativeProviderId` | `kenari-direct` | Route id for that adapter |
+| `modelRecoveryEnabled` | `true` | Master switch for automatic recovery |
+| `modelRecoveryProviders` | `['kenari','kenari-direct']` | Routes covered by recovery |
+| `modelRetryMaxRetries` | `5` | Extra retries (`kenari-direct`) |
+| `modelRetryDelayMs` | `5000` | Fixed wait before each retry |
+| `modelRetryableCodes` | `EMPTY_RESPONSE` `RATE_LIMIT` `SERVER` `TIMEOUT` `TRANSPORT` | Retryable failure codes, must not be empty |
+| `modelSwitchEnabled` | `true` | Whether to switch models |
+| `modelSwitchDelayMs` | `5000` | Wait before a switch or fallback |
+| `modelSwitchSkipCodes` | `AUTH` `INVALID_CREDENTIAL` `MISSING_CREDENTIAL` `QUOTA` | Codes that skip straight to the provider fallback |
+| `modelSwitchNoticeEnabled` | `true` | Inject a notice on switch |
+| `sessionTitlePrefixEnabled` | `true` | Session title prefix switch |
+| `sessionTitlePrefix` | `yyyyMMddHHmmss-` | Prefix template |
+| `sessionTitleMaxBytes` | `96` | Byte ceiling for prefix plus body |
+
+## Development
+
+```sh
+pnpm build                      # tsc to lib/, plus the client bundle self-check
+node test/real-harness.mjs      # real dsh harness (needs a real key)
+node test/llm-adapter.mjs       # local fake gateway, no network and no spend
+# offline suites: session-title / catalog-view / default-route / favicon, one .mjs each
+node test/billed-media.mjs      # spends real money: TTS + STT, about Rp 500
+KENARI_ALLOW_VIDEO=1 node test/billed-video.mjs   # spends real money: 4s video, about Rp 1,400
+```
+
+`scripts/check-client.mjs` runs as part of `pnpm build`. It checks the client bundle's registration format, export surface, dependency declarations, and namespace, and renders the settings card for real (the bundle is hand-written with no bundler, so these checks are its compile step). Design and measurement notes live under `docs/`, written for people changing this plugin.
+
+## How this was built
+
+The plugin was written in **ZCode**, with session models from opencode's DeepSeek V4.1 Flash and Kenari's `deepseek-v4-flash`. Building it meant reading dsh's source repeatedly and editing across files, so both were picked for holding a long context.
+
+If you want a similar setup, these are the two I actually use:
+
+- **[Kenari](https://kenari.id/code/KNR-KKRNAJ)**: one key reaches models from several vendors, more than 70 in the catalog, from DeepSeek, GLM and GPT through speech, image, video, OCR, embeddings and rerank. It speaks OpenAI-compatible, Anthropic-compatible and Responses, so an existing client needs only a new base URL. Billing comes both per use and as a monthly plan, in Rupiah, with a low top-up minimum (QRIS from Rp 1,000). The catalog and docs endpoints are public, so you can see what you get before paying.
+- **[opencode Go](https://opencode.ai/go?ref=343F5JW4RA)**: $10 a month with quota per 5 hour window instead of per-token billing, and you can top up credit when the quota runs short. It works with any agent, which is why it runs the dsh session model here.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/README.md

@@ -0,0 +1,283 @@
+# dsh-kenari-plugin
+
+[English](README.en.md) | 中文
+
+把 [Kenari](https://kenari.id) 接进 DeepSeek Harness（dsh）：
+
+- Kenari 的模型可以当 dsh 会话模型，默认路由按 key 的套餐自动决定
+- 搜索与抓取优先走 Kenari，失败回退 dsh 自带的 provider
+- 21 个 REST 能力注册成 agent 工具：目录、账户、搜索、OCR、图像、音频、视频、嵌入、重排、审核、计费、token 计数
+- 新会话标题带本机时间前缀，模板可改、可关
+- Settings → Kenari 一页管完：凭据状态、运行参数、模型目录
+
+所有能力通过 dsh 的 bundle patch 层与公开 seam（`ctx.web`、`ctx.settings`、`ctx.tools`）注册，没有改动 dsh 的任何代码或配置。
+
+## 前提
+
+需要 dsh `0.1.5-rc.1`（全局安装，`dsh` 在 PATH）、Node.js >= 22，以及 pnpm（`dsh plugin` 底层转发给它）。dsh 子包必须与主版本对齐，装的时候显式带版本号，npm 的 `latest` 未必对得上：
+
+```sh
+dsh plugin --profile web add @deepseek-ai/dsh-web-fetch-http@0.1.5-rc.1
+```
+
+## 安装
+
+```sh
+dsh plugin --profile web add dsh-kenari-plugin
+dsh --profile web --dump-config | grep -A3 dsh-kenari-plugin   # 确认 patch 层生效
+dsh --profile web
+```
+
+改插件源码时换成 clone 安装：`pnpm install && pnpm build`，再 `dsh plugin --profile web add "$PWD"`。profile 里是 pnpm link，之后改源码只需重新 `pnpm build`。
+
+## 配置密钥
+
+在 Kenari 面板的 API keys → Create key 生成 `kn-...`（只显示一次），然后二选一：
+
+- 打开 **Settings → 模型 → Kenari 卡片**，在密码框里填入
+- 写 `.env`（凭据层可写）：
+
+```sh
+# ~/.dsh/.env
+KENARI_API_KEY=kn-...
+```
+
+不要写进 `cordis.patch.yml`。设置文档只存引用名，值不进日志、界面与配置。
+
+## 会话模型
+
+装上后 Settings → Models 里会多出 Kenari 路由。
+
+### 默认路由
+
+默认模型由 key 的套餐决定。插件加载时读 `GET /v1/account/quota` 拿套餐名，取该套餐的 `free_cache_models`（缓存读取不占套餐额度）写进路由。只写一次，之后这层归你。
+
+读不到套餐时（没配 key、分享页 key 被 403、账户没有套餐）用内置兜底清单，它正好是 Kreator 与 Studio 两档的免缓存清单：
+
+| 模型 id | 显示名称 | 上下文 | 最大输出 | 备注 |
+| --- | --- | --- | --- | --- |
+| `deepseek-v4-flash` | DeepSeek v4 Flash | 1M | 64K | reasoning low/high/max |
+| `glm-5-3-flash` | GLM 5.3 Flash | 1M | 64K | 视觉，reasoning low/high/max |
+| `gpt-5-6-luna` | GPT 5.6 Luna | 872k | 64K | 视觉 + PDF，6 档 reasoning |
+| `mimo-v2-5` | MiMo v2.5 | 1.05M | 64K | 视觉 + 音频 + 视频 |
+
+四个都不是免费模型，**没有余额的新账户第一次会话会拿到 402**，先加一个 `:free` 模型或充值。`:free` 模型默认不进路由，用挑选器里的「免费」筛一下再加。
+
+显示名称与最大输出由插件推导（目录里都没有）：名称还原自 id，最大输出取窗口的 1/4 并夹在 [1K, 64K]，不公布窗口的模型不写这个字段。名称只用于展示。
+
+你手动改过列表之后，用户配置整份覆盖预设（pi-ai 的语义），插件不再改。
+
+### 按能力和套餐挑模型
+
+**Settings → 模型 → Kenari → 编辑 → 模型目录**里，「添加模型」和「获取可用模型」是同一个入口，都开这台挑选器。它用 dsh 自己的对话框组件，只多了筛选维度：
+
+- 每行显示模型 id 与能力标签（`image` `audio` `video` `pdf` `embedding`），付费模型另带「套餐内」标签，表示被某个订阅套餐覆盖。免费模型看 id 的 `:free` 后缀
+- 过滤片有 `套餐内` `免费` 与各能力标签。「套餐内」与「免费」互斥，`embedding` 独占（它没有 chat 端点，混选只会得到空列表），其余可多选
+- 「添加所选」**追加**到现有条目之后，已在路由里的行不能再勾
+
+写入是即时的，没有保存步骤；同一张卡里的列表要收起再展开才会刷新。数据由 Host 侧算好（`GET /api/kenari.models`），与 `kenari_list_models` 同源，没有 key 也能看。
+
+### 三条协议线与兼容预设
+
+Kenari 有三条线，base URL 形状不同，写错返回 405 而不是 404：
+
+| pi-ai 的 `api` | base URL |
+| --- | --- |
+| `openai-completions` | `https://kenari.id/v1` |
+| `openai-responses` | `https://kenari.id/v1` |
+| `anthropic-messages` | `https://kenari.id`（不带 `/v1`） |
+
+自建路由时照抄这四条兼容设置（已写在 `cordis.patch.yml`）：
+
+- `maxTokensField: max_tokens`。Kenari 只读 `max_tokens`，发 `max_completion_tokens` 会返回 200 但静默忽略
+- `supportsDeveloperRole: false`，系统提示词继续用 `system` 角色
+- `supportsUsageInStreaming: true`，流式最后一帧带 `usage`，`cached_tokens` 计量靠它
+- `reasoningEfforts` 的键只能用 `off|minimal|low|medium|high|xhigh|max`，Kenari 的 `none` 映射成 `off`。键写错会让 dsh 启动失败，改完先 `--dump-config`
+
+## web 搜索与抓取
+
+`searchProvider` 与 `fetchProvider` 都钉到 `kenari-fallback`：先打 Kenari，失败（含 401/402/403 与网络错误）回退 `deepseek-official` 和本地匿名 `http`，日志给出方向、原因与耗时。
+
+`available()` 的契约禁止发网络请求，所以 Kenari 不可用只能等调用失败才发现，用户会多等一次。不想要这层替换，把 `fallbackEnabled` 设为 `false`（需重启）。
+
+## 模型调用失败自动恢复
+
+Kenari 路由上的会话模型调用失败后自动恢复：
+
+1. 按固定 5 秒间隔重试 5 次，由 dsh 自带的 `dsh-llm-retry` 执行，会话里留 `llm/retry` 记录
+2. 用尽后换一个窗口不小于当前模型的模型，先在同一个 provider 内挑最小的够用者，没有候选再跨 provider
+3. 仍失败则回退 dsh 的默认 provider 与模型
+
+三步都失败这一轮才报错。重试与换模型都在同一个 step 内，任务不中断，插件不会再发「继续」消息。换模型不继承 `reasoningEffort`（档位按模型定义），换完注入一条说明，可用 `modelSwitchNoticeEnabled` 关掉；手动 `/model` 会清除自动切换。
+
+`CONTEXT_WINDOW_EXCEEDED` 刻意不在可重试集里：同模型同上下文重试必然再失败，直接进换模型阶段，而这一步往往正是恢复生效的地方。
+
+两处限制：
+
+- **`llm-pi-ai` 路由的重试参数取自 `cordis.patch.yml` 的 `providers.kenari.retryPolicy`，不是插件配置。** dsh 在适配器注册时就冻结了路由的重试策略，插件改不了。默认值与插件配置一致，改一个记得改另一个。
+- **`TRANSPORT` 类失败在服务端可能已经完成并计费**，重试会重复扣费。介意就把 `modelRetryableCodes` 调小。这与生成类端点的「超时不重试」是两回事。
+
+字段与默认值见「配置项」。
+
+## 会话标题前缀
+
+新会话标题默认带 `20260911174258-` 形式的前缀，时间取本会话第一条人类消息的时间（本机时区）。前缀由插件写进 `session/title` 事件，Web、TUI、headless 看到同一个字符串。
+
+时间不用 `session.header.createdAt`（它记的是会话记录创建时间，dsh 复用空白会话时可能比真正开口早几个小时），完全没有人类消息时才退回它。
+
+前缀是标题文本的一部分，不是独立的显示层。所以开关控制的是生成时写不写：关掉后新标题不带前缀，关闭期间落盘的标题文本本身就不含前缀；已有会话不会被回溯修改，改开关或模板都不会。
+
+LLM 标题、确定性 fallback、手动 rename 一视同仁。fork 继承父标题时，前缀换成子会话自己的开始时间（父会话历史不计）。
+
+三点注意：
+
+- `sessionTitleMaxBytes` 必须与 `cordis.patch.yml` 里 `session-title` 行的 `maxTitleBytes` 一致。插件直接写标题事件，dsh 不会替它截断
+- 模板没有转义，`yyyy`、`MM` 这类子串一律替换；剥旧前缀按「当前模板 + 对应会话的开始时间」重放。模板在父会话与 fork 之间被改过、或父会话已不在 store 里，会留下双前缀
+- 侧边栏里已存的旧前缀是缓存值，重启 dsh 并打开那个会话，它会自动校正
+
+字段与默认值见「配置项」。
+
+## 计费与预算
+
+工具每次带一行费用回显：响应里有 `cost_micro_idr` 就写实际扣费，没有的（图像、视频、语音）按目录 `pricing_lines` 单价乘数量写预估。非 token 单位按整单位上取（21 字符的 TTS 计 1 个「1k 字符」单位）。
+
+`kenari_billing` 给会话累计、分工具与分模型、`cached_tokens` 命中率、预算余量、钱包余额；余额低于 `lowBalanceAlertRp` 时费用回显附一条告警。`budgetCapRp` 默认 0（不封顶），到顶后花费型工具会被拒绝。预检只看已记录的花费，所以它是「不再新增花钱调用」，不是「保证总额不超」。402、401、405、403 都带了可执行建议。
+
+## 设置页
+
+Settings → **Kenari**（命名空间 `kenari`）。分组顺序就是使用顺序：
+
+| 分组 | 内容 |
+| --- | --- |
+| 密钥 | 只显示状态与名字（已配置/缺失、来源、可修改性、只读引用名），没有输入框 |
+| 模型 | 当前路由可用的模型：ID、显示名称、上下文。默认只列前 3 个 |
+| 会话标题 | 开关、前缀格式、长度上限 |
+| 高级设置（默认折叠） | API 地址、超时、重试次数、缓存时长、余额提醒阈值 |
+| 重启后生效（默认折叠） | 加载时定型的开关（是否注册搜索/抓取/工具、预算封顶、自带适配器）。只读，改它们要编辑对应设置节并重启 dsh |
+| 余额与用量 | 数字随用量变化，页面不存快照，只给一句可以直接照着问的话 |
+
+文案有中英两套，跟随 dsh 的语言设置切换；`pnpm build` 会断言两边键集一致。
+
+## 工具一览
+
+| 类别 | 工具 |
+| --- | --- |
+| 目录与文档 | `kenari_list_models`（免费分组、价格、上下文、下线与 beta 告警；不需要 key）、`kenari_search_docs`（同样不需要 key） |
+| 账户 | `kenari_balance`、`kenari_usage`、`kenari_quota`（分享页 key 会 403） |
+| 搜索 | `kenari_x_search` |
+| 文档 | `kenari_ocr`（`reuse_id` 复用免费） |
+| 媒体 | `kenari_image_generate`、`kenari_image_edit`、`kenari_speech`、`kenari_transcribe`、`kenari_music`、`kenari_video_generate`、`kenari_video_extend`、`kenari_video_status`、`kenari_video_content` |
+| 数据 | `kenari_embed`、`kenari_rerank`、`kenari_moderate` |
+| 上下文与计费 | `kenari_count_tokens`、`kenari_billing` |
+
+图像、音频、视频经 `ctx.attachments` 落盘成 image/file block，不塞进 JSON。
+
+公开目录里没有 music 与 moderation 模型，所以 `kenari_music` 和 `kenari_moderate` 只会返回 400；`kenari_speech` 用 `mimo-v2-5-tts` 可用，`kokoro-tts` 与 `gemini-3-1-flash-tts` 是上游 400。
+
+## 可选：插件自带的 LlmAdapter
+
+`llm-pi-ai` 预设已经能把 Kenari 当会话模型用。把 `nativeAdapterEnabled` 设为 `true`（需重启）还能得到：模型选择器里直接看到价格、token 计量与 `cached_tokens` 命中率进 `kenari_billing`、推理档位按目录原样暴露（含 `none`）。
+
+它注册的路由默认叫 `kenari-direct`，与预设的 `kenari` 不同名，两条可以并存，关掉开关即回退。相比预设，它不回放思考块、不注入 `file-parser`（文件块投影成说明文本，读文档请用 `kenari_ocr`）、不映射 `web_search_options`；图像输入是支持的。
+
+```yaml
+- id: kenari
+  config:
+    nativeAdapterEnabled: true
+    nativeProviderId: kenari-direct
+```
+
+## 故障排查
+
+| 症状 | 原因与处置 |
+| --- | --- |
+| 401 `invalid api key` | key 失效；`.env` 改完没重启 dsh；凭据引用名写错 |
+| 402 `insufficient_balance` | 用了付费模型但余额为 0。切 `:free` 模型或充值 |
+| 405 | base URL 形状错，见「三条协议线」 |
+| 启动报 `invalid config ... reasoningEfforts` | 该模型的 `reasoningEfforts` 键不在 `off..max` 里，改回或从预设删掉该模型 |
+| 403（balance / usage / quota） | key 来自分享页，这三个工具读 key 所有者的账户数据，所以被拒 |
+| 设置页 Kenari 卡片空白 | 客户端 bundle 没构建或服务名写错。跑 `pnpm build` 再重启 |
+| 导航里 Kenari 那行还是齿轮图标 | 图片没加载成功。确认包内含 `assets/kenari-favicon-128.png`，且 `GET /api/kenari.favicon` 能通 |
+| 模型列表是空的 | 预设未生效，`dsh --profile web --dump-config` 看 `llm-pi-ai` 段是否存在 |
+
+## 可选：只用 MCP，不装插件
+
+Kenari 自带 Streamable HTTP MCP server（8 个工具，名字带 `mcp__kenari__` 前缀），配置如下：
+
+```json
+{ "mcpServers": { "kenari": { "url": "https://kenari.id/mcp", "headers": { "Authorization": "Bearer kn-..." } } } }
+```
+
+代价是工具名带前缀、没有计费可视与余额预警、多一个运行时依赖。MCP 只适合先试一下。
+
+## 卸载
+
+```sh
+dsh plugin --profile web remove dsh-kenari-plugin
+```
+
+注册的一切都挂在 Cordis fiber 上，卸载即回收；dsh 的包与配置没有被改过。
+
+## 配置项
+
+多数可以在 Settings → Kenari 里改，标（重启）的要改对应设置节并重启。
+
+| 字段 | 默认 | 说明 |
+| --- | --- | --- |
+| `apiKeyEnv` | `KENARI_API_KEY` | 存放 key 的凭据引用名 |
+| `baseURL` | `https://kenari.id` | 插件调用 REST API 的地址 |
+| `timeoutMs` | `30000` | 单次 REST 请求超时 |
+| `generationTimeoutMs` | `180000` | 生成类调用（图像/音频/音乐/OCR）的单次超时 |
+| `maxRetries` | `2` | 瞬时失败的 REST 重试次数 |
+| `searchEnabled` | `true` | 注册搜索 provider（重启） |
+| `fetchEnabled` | `true` | 注册抓取 provider（重启） |
+| `fallbackEnabled` | `true` | Kenari 失败时回退 dsh 默认（重启） |
+| `toolsEnabled` | `true` | 注册 21 个工具（重启） |
+| `docsCacheTtlMs` | `3600000` | `/llms-full.txt` 缓存时长 |
+| `catalogCacheTtlMs` | `3600000` | `/v1/models` 缓存时长 |
+| `modelAliases` | `{}` | 模型别名，`{ 别名: '精确模型 id' }` |
+| `lowBalanceAlertRp` | `5000` | 低于这个卢比数就告警，0 关闭 |
+| `balanceCacheTtlMs` | `300000` | 余额缓存时长 |
+| `budgetCapRp` | `0` | 单会话花费上限，0 不封顶 |
+| `nativeAdapterEnabled` | `false` | 注册自带 LlmAdapter（重启） |
+| `nativeProviderId` | `kenari-direct` | 自带适配器的路由 id |
+| `modelRecoveryEnabled` | `true` | 失败自动恢复总开关 |
+| `modelRecoveryProviders` | `['kenari','kenari-direct']` | 参与恢复的路由 |
+| `modelRetryMaxRetries` | `5` | 额外重试次数（`kenari-direct`） |
+| `modelRetryDelayMs` | `5000` | 每次重试前的固定等待 |
+| `modelRetryableCodes` | `EMPTY_RESPONSE` `RATE_LIMIT` `SERVER` `TIMEOUT` `TRANSPORT` | 可重试的失败码，不能为空 |
+| `modelSwitchEnabled` | `true` | 是否换模型 |
+| `modelSwitchDelayMs` | `5000` | 换模型或回退前的等待 |
+| `modelSwitchSkipCodes` | `AUTH` `INVALID_CREDENTIAL` `MISSING_CREDENTIAL` `QUOTA` | 跳过同 provider 换模型，直接回退 |
+| `modelSwitchNoticeEnabled` | `true` | 换模型时注入通知 |
+| `sessionTitlePrefixEnabled` | `true` | 标题前缀开关 |
+| `sessionTitlePrefix` | `yyyyMMddHHmmss-` | 前缀模板 |
+| `sessionTitleMaxBytes` | `96` | 前缀加正文的字节上限 |
+
+## 开发
+
+```sh
+pnpm build                      # tsc → lib/，并跑客户端 bundle 自检
+node test/real-harness.mjs      # 真实 dsh harness（需要真 key）
+node test/llm-adapter.mjs       # 本地假网关，不联网不花钱
+# 离线套件：session-title / catalog-view / default-route / favicon，各一个 .mjs
+node test/billed-media.mjs      # 会真花钱：TTS + STT，约 Rp 500
+KENARI_ALLOW_VIDEO=1 node test/billed-video.mjs   # 会真花钱：4s 视频，约 Rp 1.400
+```
+
+`scripts/check-client.mjs` 随 `pnpm build` 运行，校验客户端 bundle 的注册格式、导出面、依赖声明与命名空间，并真实渲染一次卡片组件（手写的 bundle 没有打包器，这些就是它的编译期检查）。设计与实测记录在 `docs/` 下，面向要改这个插件的人。
+
+## 开发环境与致谢
+
+这个插件在 **ZCode** 里写的，会话模型主要用 opencode 的 DeepSeek V4.1 Flash 和 Kenari 的 `deepseek-v4-flash`。写它要反复读 dsh 的源码并跨文件改，选这两个是因为都扛得住长上下文。
+
+如果你也想搭一套类似的组合，可以参考我实际在用的这两个：
+
+- **[Kenari](https://kenari.id/code/KNR-KKRNAJ)**：一个 key 打通多个厂商的模型，目录七十多个，从 DeepSeek、GLM、GPT 到语音、图像、视频、OCR、嵌入和重排；OpenAI 兼容、Anthropic 兼容与 Responses 三条协议线，现成客户端改个 base URL 就能接。按量付费与包月套餐都有，账单是印尼盾，充值门槛低（QRIS 最低 Rp 1.000）。目录与文档是公开端点，没有 key 也能先看清有什么。
+- **[opencode Go](https://opencode.ai/go?ref=343F5JW4RA)**：$10 一个月，按 5 小时窗口给额度，不用逐 token 算钱，不够还能单独充值。它能配任何 agent，所以我拿它跑 dsh 的会话模型。
+
+两个都支持支付宝扫码支付。
+
+## License
+
+MIT，见 [LICENSE](LICENSE)。