dsh-newapi-provider 0.0.0-stage → 0.8.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zenVibeCoding
+
+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/PUBLISHING.md

@@ -0,0 +1,135 @@
+# 发布清单（维护者用）
+
+本文件是 `dsh-newapi-provider` 的发布材料。**npm 发布、仓库转公开、插件市场投稿都需要人工确认后单独执行**，自动化流程不代替这三步。
+
+## 当前状态（2026-10-23）
+
+| 项目 | 状态 |
+| --- | --- |
+| npm | **已发布 0.8.3** — https://www.npmjs.com/package/dsh-newapi-provider （`latest`，2026-10-23 17:48 东八区） |
+| 包内容校验 | 下载 tarball 与仓库逐文件字节一致，19 个文件，shasum 一致，无凭据泄漏 |
+| Git tag | `v0.8.3` 已推送 |
+| 仓库 | https://github.com/zenVibeCoding/dsh-newapi-provider （公开，已加 `dsh-plugin` topic） |
+| 市场投稿 | **未提交**，条目文件已备好：[docs/market-entry.yml](docs/market-entry.yml)，卡片图 [assets/icon-180.png](assets/icon-180.png) |
+| 可投稿时间 | 仓库创建 2026-10-23 07:01 UTC，满 24 小时 = **2026-10-24 15:01（东八区）之后** |
+| 许可证 | MIT，作者 `zenVibeCoding` |
+| 验证环境 | DSH 0.2.1-rc.2 / Node.js 22.19+，`engines.dsh: >=0.2.1-rc.1 <0.3.0-0` |
+| 离线测试 | `npm test`，103 项全过 |
+| 真实生图 | **未验证**（网关返回 503 无可用渠道） |
+| 真实视频 | **未验证**（无视频渠道），工具为实验性 |
+
+## 发布前必须完成
+
+1. **在网关侧配好至少一个可用的生图渠道**，跑通一次真实生图并确认附件落盘。
+2. 如能取得视频渠道，跑通一次「提交 → 轮询 → 下载 → 附件」。
+3. 在连接的 DSH 窗口检查设置页三个标签、渠道编辑弹窗、模型编辑弹窗的实际观感。
+4. 更新 README「当前验证范围与限制」，把已验证项写实，未验证项保持明示。
+5. 确认版本号与 `client.js` 里 `data-newapi-provider-version` 一致。
+
+## 打包检查
+
+```sh
+npm test
+node --check index.js
+node --check client.js
+npm pack --dry-run --ignore-scripts
+```
+
+预期：19 个文件，只含 `index.js`、`client.js`、`lib/*.js`、`cordis.patch.yml`、`locale/*.json`、`icon.svg`、`README*.md`、`PUBLISHING.md`、`LICENSE`、`package.json`。
+
+**不得包含**：`test/`、`node_modules`、`docs/`、个人网关地址或令牌、`.credentials*`、调研笔记（`~/dsh-newapi-plugin`）、会话截图。发布前自查：
+
+```sh
+npm pack --dry-run --ignore-scripts 2>&1 | grep -Ei 'credential|secret|sk-|/Users/'
+```
+
+## 第一步：npm 发布
+
+当前 `npm whoami` 报 `ENEEDAUTH`，需要先登录：
+
+```sh
+npm login                     # 浏览器 OAuth；或 npm login --auth-type=legacy
+npm whoami
+
+cd ~/dsh-newapi-provider
+git status --short             # 应为干净
+npm view dsh-newapi-provider version   # 期望 404
+
+npm publish --access public   # 开了 2FA 会提示 --otp <code>
+```
+
+发布后立刻验证（不要只看 npm 网页缓存）：
+
+```sh
+npm view dsh-newapi-provider version     # 期望 0.8.1
+npm view dsh-newapi-provider dist.tarball
+```
+
+装一次真实回归（用临时 profile 或先卸载本地 link 安装）：
+
+```sh
+dsh plugin add dsh-newapi-provider    # 走 npm 而非本地目录
+```
+
+- 包名已被占用时不要硬发，先定后缀（如 `dsh-newapi-provider-community`）并同步 README、`cordis.patch.yml`、locale 标题。
+- 之后发新版只改版本号 → 提交 → `npm publish`，不要复用已发布的版本号。
+
+## 第二步：插件市场投稿
+
+已核对 `awesome-dsh-plugin` 的 [contributing.md](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin/blob/main/contributing.md)，规则如下：
+
+- **一个文件就是全部投稿**：PR 新增 `data/plugins/<owner>__<repo>.yml`，不要手改 README（README 由脚本生成）。
+- 只有 `description.en` 必填，中文描述可选（缺了维护者会补）。
+- 仓库 `package.json` 必须声明 `dsh.bundle`（本仓库有 `{"bundle":{"patch":"./cordis.patch.yml"}}`）。
+- 仓库需含真实可用代码；**创建满 1 天**（CI 自动查）。
+- 仓库需加 `dsh-plugin` topic（已完成）。
+- 描述必须属实，不带营销词；分类要贴合实际功能。
+
+**时间门槛**：仓库创建于 2026-10-23 07:01 UTC，需满 24 小时，即 **2026-10-24 15:01（东八区）之后**再提 PR。
+
+条目已经写好并校验通过：**[docs/market-entry.yml](docs/market-entry.yml)**（用 js-yaml 解析验证过，分类合法、描述以句号结尾）。目标路径是 `data/plugins/zenVibeCoding__dsh-newapi-provider.yml`，直接复制即可：
+
+```yaml
+url: https://github.com/zenVibeCoding/dsh-newapi-provider
+name: zenVibeCoding/dsh-newapi-provider
+category: model
+description:
+  en: 'New API gateway provider: several gateways with one active at a time, per-gateway model lists with context and modality details, quota, and image and video generation tools.'
+  zh: 'New API 网关提供商：多网关同一时间激活一个，每个网关独立的模型清单与上下文/多模态标注、额度查询，以及生图与视频生成工具。'
+icon: https://raw.githubusercontent.com/zenVibeCoding/dsh-newapi-provider/master/assets/icon-180.png
+```
+
+> 描述里有 `: ` 必须加引号，否则 YAML 解析失败（上面英文描述就是这种情况）。
+> 卡片图是 `assets/icon-180.png`（180×180 PNG），市场要求 GitHub 托管的位图；仓库里的 `icon.svg` 是 DSH 插件页用的，不适用于市场卡片。
+
+提交步骤：
+
+```sh
+gh repo fork awesome-dsh-plugin/awesome-dsh-plugin --clone
+cd awesome-dsh-plugin
+mkdir -p data/plugins
+cp ~/dsh-newapi-provider/docs/market-entry.yml data/plugins/zenVibeCoding__dsh-newapi-provider.yml
+git checkout -b add-dsh-newapi-provider
+git add data/plugins/zenVibeCoding__dsh-newapi-provider.yml
+git commit -m "Add dsh-newapi-provider"
+git push -u origin add-dsh-newapi-provider
+gh pr create --fill
+```
+
+分类备选：`model`（模型接入，最贴合）。若维护者认为更偏 UI，会直接改，不会打回。
+
+## 其他收录入口
+
+除了主列表，还有几个市场会自动抓取带 `dsh-plugin` topic 的仓库（如 `dsh-market`、`bradeGithub/DSH-Plugins-Marketplace` 等），加了 topic 后通常会被自动收录，无需逐个投稿。以各仓库说明为准。
+
+## 版本与兼容
+
+- 语义化版本：破坏性配置变更升 minor 前，先写迁移说明（参考 README 的 v0.7.0 改名章节）。
+- 路由 id 一旦发布就不要随意更改：改动会让已有会话失去模型选择。
+- 数据结构变更（`channels`、`enabledModels`、`models`）必须保持向后兼容，或在 README 写清迁移步骤。
+
+## 已知未完成项（可写进「限制」）
+
+- 旧令牌在轮换后仍保留在凭据库，需要「无进行中视频任务引用」的清理规则。
+- 重启后视频任务不会重新唤醒发起它的对话。
+- 部分历史样式未被使用，可在发布前清理。

package/README.md

@@ -1,3 +1,145 @@
-# Temporary Holding Version
+# New API Provider
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+English · [中文](README.zh.md)
+
+A New API gateway workbench for DeepSeek Harness: several gateways with one active at a time, per-gateway model lists and parameter overrides, quota, and image and experimental video generation.
+
+[![npm](https://img.shields.io/npm/v/dsh-newapi-provider.svg)](https://www.npmjs.com/package/dsh-newapi-provider)
+[![license](https://img.shields.io/npm/l/dsh-newapi-provider.svg)](LICENSE)
+
+![Settings → New API Provider: gateways and connections](docs/screenshots/channels.png)
+
+## Preview
+
+| Model capabilities | Fetch models |
+| --- | --- |
+| ![Per-gateway model list with vendor marks, context/output limits, modalities and test results](docs/screenshots/models.png) | ![Fetch models dialog grouped by kind, with new / added / removed-upstream states](docs/screenshots/discover.png) |
+| **Model editor** | **Sidebar quota** |
+| ![Model editor: display name, upstream mapping, context window, output cap and input modalities](docs/screenshots/editor.png) | ![Active gateway's quota at the sidebar foot](docs/screenshots/sidebar.png) |
+
+The screenshots render this plugin's real components and stylesheet with sample data; gateway names, URLs and amounts are examples. The UI follows the DSH theme, so colours adapt to your skin and dark mode.
+
+## Install
+
+Requires **DSH 0.2.1-rc.1 or newer** (verified on 0.2.1-rc.2) and Node.js 22.19+.
+
+Install `dsh-newapi-provider` with DSH's plugin manager, then refresh the page and open **Settings → New API Provider**. No separate web server is needed.
+
+1. **Add gateway** — name, New API site URL, calling token.
+2. **Fetch models** — read what the gateway lists, select the ones you want.
+3. **Activate the gateway** — this plugin's model route now serves those models.
+
+The token is stored in the DSH credential service, never in the gateway configuration, and is never sent back to the browser.
+
+## Features
+
+- Several gateways, exactly one active; each keeps its own URL, credential reference, model list and model overrides.
+- Channel-scoped model management: fetch what a gateway lists, choose which models appear in DSH, test one model, remove with undo, add models the gateway does not list.
+- Capability data from models.dev (context window, output cap, modalities, reasoning), correctable per model, with an optional per-model upstream name mapping.
+- Token quota in the settings summary and at the sidebar foot, plus the account balance when the token is allowed to query it.
+- Image generation saved as durable DSH attachments with a generation history; experimental video through the unified `/v1/videos` interface with background polling and restart recovery.
+
+## Gateways and quota
+
+1. **Test connection** reads the model list only and does not make paid model calls; it also shows the gateway version and model counts.
+2. **Activate** switches every subsequent call made through this plugin, or tick "activate after saving".
+3. Switching never rewrites other adapters or your default provider.
+4. Submitted video tasks keep their originating gateway and are never polled on a newly activated one.
+
+Quota details:
+
+- Quota comes from `GET /api/usage/token/` (note the trailing slash).
+- Amounts are converted with `/api/status` (`quota_per_unit`, `quota_display_type`, `usd_exchange_rate`), never the top-up price.
+- A token that allows user-quota queries also reports the account balance.
+- An unlimited token shows used quota instead of a meaningless negative remainder.
+- Both numbers are the site's own; a present catalog or balance does not prove an upstream channel can serve a model.
+
+The sidebar shows the active gateway's name and amount, with a health dot; click it to refresh. It collapses to a status dot when the sidebar is a rail.
+
+## Per-gateway model lists
+
+Each gateway keeps an independent list, even when two gateways point at the same site with the same token:
+
+- **Model capabilities tab** has a gateway picker; the active gateway is marked and its list edits apply to that gateway only.
+- **Fetch models** reads the gateway catalog with a search box plus status (new / added / removed upstream) and kind filters, grouped by kind; filtering only changes what is listed, never the current selection. The list scrolls on its own and the action bar stays in view.
+- **Remove** only removes the model from this gateway; custom parameters can be kept and the removal can be undone briefly.
+- **Add manually** is for models the gateway can serve but does not list.
+- Gateways created in current versions start with an empty list; channels saved before the feature existed stay in automatic mode (all gateway models) until their first edit, which materialises the list from what the gateway currently lists.
+
+## Testing models
+
+- **Chat models**: one minimal streaming request. The result remembers success, total latency, first packet time and a redacted error. A stream that only sends `[DONE]` counts as a failure, because it carries no protocol response.
+- **Image/video models**: a real generation, so each test asks for confirmation first. Image tests show a preview when the URL is safe to embed; a signed URL is recorded as generated without exposing it.
+- **Batch test** covers the chat models currently filtered, three at a time. Stopping prevents queued requests; requests already sent still finish and may be billed.
+- Tests are billed requests: chat tests send a tiny completion, image/video tests generate.
+
+## Model names and mapping
+
+- **Local model id**: the stable id used by sessions and the model list; never changed by the editor.
+- **Display name** (`name`): label only.
+- **Upstream model name** (`upstreamModel`): the `model` actually sent. Empty means the local id. Mapping is one hop and applies to chat, image generation, image edits, video and model tests.
+- The editor previews the mapping, resolves automatic protocol/capabilities/pricing from the mapping target, and lets input modalities and reasoning follow the catalog or be pinned. Reset clears every override including the mapping.
+
+Capability data is a hint, not proof: a relay may list a model and still fail to serve it.
+
+## Models and modalities
+
+models.dev data is cached. Exact matches win; when nothing matches, defaults apply. Base-model matches, defaults and manual overrides are all marked in the UI. Never treat a guessed capability as something the gateway has proven.
+
+The DSH chat interface currently accepts text and image input only. PDF, audio and video tags are catalog metadata and cannot be sent to a DSH chat. Image and video models serve the generation tools and do not appear as chat models.
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `newapi_balance` | Quota of the active gateway's token (and account, when allowed). Free. |
+| `newapi_models` | Models of a gateway (`channelId` optional, defaults to active) with kind, limits, modalities, pricing, mapping. Free. |
+| `newapi_channels` | `list`, `test`, `save`, `activate`, `delete`, `model_override`, `models_discover`, `models_set`, `model_test`. Writes need a revision. |
+| `newapi_image_generate` | Text-to-image, or image editing when `inputImages` is given. Saves attachments. |
+| `newapi_video_generate` | Submits a video task and returns its id. Billed per task. |
+| `newapi_video_status` | Lists or checks video tasks and returns the saved file. |
+
+Settings-page actions and these tools share one service, so nothing can drift between the UI and the agent.
+
+**Image and video generation cost money.** A submission whose outcome is unknown is never resent automatically; check the gateway's task log first. Stopping a local watch does not cancel or refund the upstream task.
+
+## Paid results
+
+- A video submission that loses the connection or returns an unreadable body after HTTP 200 is reported as **submission unknown, possibly billed**, and is never resent automatically.
+- A video that finished upstream but failed to download stays **generated, retrying download**. Only GET requests are retried, against refreshed URLs; when the recovery deadline passes it becomes **generated, download unsuccessful**. Do not regenerate.
+- Concurrent status checks of one task share a single flow, and unloading the plugin aborts in-flight requests so a stale instance cannot overwrite the new cache.
+- Failed paid requests are never retried automatically.
+
+## Verification status
+
+- Real chat, model discovery, quota, per-gateway lists and gateway editing have been exercised against a local New API instance (v1.0.0-rc.45).
+- A real image request was rejected with HTTP 503 (no available upstream channel). Successful paid image generation is therefore **not yet verified**; the attachment pipeline is covered by offline tests.
+- Video is **experimental**: no real video channel was available. Submission, polling, download recovery, restart recovery and duplicate-submission prevention are covered offline only.
+- Only one New API deployment has been tested. Other versions and relays may differ in endpoint details.
+
+## Migrating from the former name (v0.7.0)
+
+The plugin was called `dsh-newapi-studio`. The rename covers the package, the loader row and provider route (`newapi-provider`), the HTTP prefix (`/newapi-provider/api/`) and the data directory (`plugin-data/dsh-newapi-provider`).
+
+To migrate an existing installation, back up the profile patch and plugin data, then keep each channel's id, credential reference, model list and overrides while moving the data directory to the new name. Current releases do not read the old directory automatically. Keep existing credential references even if they contain `STUDIO`: they still hold the working tokens; new references use the `NEWAPI_PROVIDER_` prefix.
+
+Sessions pinned to the old `newapi-studio` route must pick models again under the new route. Other adapters are unaffected. Tool names (`newapi_channels`, `newapi_models`, …) did not change.
+
+## Development
+
+```sh
+npm test
+node --check index.js
+node --check client.js
+npm pack --dry-run --ignore-scripts
+```
+
+To work on a checkout instead of the published package, install the project directory with DSH's plugin manager.
+
+DSH runtime imports are optional peerDependencies supplied by the host, so no DSH package is installed or copied here. Tests use local fake gateways and never read personal credentials. This repository replaces, rather than depends on, `dsh-gateway-provider`; two adapters cannot own the same provider route.
+
+Release steps are in [PUBLISHING.md](PUBLISHING.md).
+
+MIT License. Uses public DSH exports and pi-ai protocol implementations; no third-party plugin source is vendored.
+
+Vendor marks in the model list come from [LobeHub Icons](https://github.com/lobehub/lobe-icons) (`@lobehub/icons-static-svg` 1.97.0, MIT License), inlined as SVG so the page makes no remote image requests. Brand marks belong to their respective owners and only identify a model's vendor.

package/README.zh.md

@@ -0,0 +1,150 @@
+# New API Provider
+
+[English](README.md) · 中文
+
+DeepSeek Harness 的 New API 渠道与模型工作台：多网关同一时间激活一个，每个网关独立的模型清单与参数覆盖，额度查询，以及生图与实验性视频生成。
+
+[![npm](https://img.shields.io/npm/v/dsh-newapi-provider.svg)](https://www.npmjs.com/package/dsh-newapi-provider)
+[![license](https://img.shields.io/npm/l/dsh-newapi-provider.svg)](LICENSE)
+
+![设置 → New API 提供商：渠道与连接](docs/screenshots/channels.png)
+
+## 效果预览
+
+| 模型能力 | 获取模型列表 |
+| --- | --- |
+| ![按渠道独立的模型清单：厂商图标、上下文/输出上限、输入能力与测试结果](docs/screenshots/models.png) | ![获取模型列表：按类型分组，区分新增 / 已添加 / 网关已下架](docs/screenshots/discover.png) |
+| **模型参数编辑** | **侧栏额度** |
+| ![模型编辑器：显示名称、上游映射、上下文窗口、最大输出与输入能力](docs/screenshots/editor.png) | ![侧栏底部显示当前激活渠道的额度](docs/screenshots/sidebar.png) |
+
+截图使用插件真实的组件与样式渲染，数据为示例（渠道名、地址、金额均为虚构）。界面跟随 DSH 主题，配色会随你的皮肤和深色模式变化。
+
+## 安装
+
+需要 **DSH 0.2.1-rc.1 或以上**（已在 0.2.1-rc.2 验证），Node.js 22.19 或以上。
+
+用 DSH 的插件管理工具安装 `dsh-newapi-provider`，安装后刷新页面，打开「设置 → New API 提供商」。不需要单独启动网页服务器。
+
+1. **添加渠道** —— 填名称、New API 站点地址和调用令牌。
+2. **获取模型列表** —— 读取网关目录，勾选要用的模型。
+3. **激活渠道** —— 本插件的模型路由开始提供这些模型。
+
+令牌存在 DSH 凭据服务里，不写进渠道配置，也不会回传到浏览器。
+
+## 能做什么
+
+- 保存多个网关，一次只激活一个；每个渠道独立保存地址、凭据引用、模型清单和模型参数覆盖。
+- 按渠道管理模型：读取网关目录、挑选哪些模型出现在 DSH、单个测试、删除后撤销、手动添加网关未列出的模型。
+- 能力数据来自 models.dev（上下文窗口、输出上限、多模态、推理），可按模型校正，并支持为单个模型设置上游映射名。
+- 设置页汇总和侧栏底部都能看到令牌额度；令牌允许查询用户额度时同时显示账户余额。
+- 生图结果保存为 DSH 附件并进入生成记录；视频使用统一 `/v1/videos` 接口、后台轮询与重启恢复，属实验性能力。
+
+## 渠道与额度
+
+1. **测试连接**只读取模型目录，不产生生成费用；同时显示网关版本与模型数量。
+2. **激活**切换本插件后续所有调用，或勾选「保存后激活」。
+3. 切换不会修改官方适配器或其他插件。
+4. 已提交的视频任务保持原始渠道，不会转向新激活的网关轮询。
+
+额度说明：
+
+- 主接口为 `GET /api/usage/token/`，注意末尾斜杠。
+- 金额换算使用 `/api/status` 的 `quota_per_unit`、`quota_display_type`、`usd_exchange_rate`，不使用充值单价。
+- 在 New API 为令牌开启「允许查询用户额度」后，可同时返回账户余额。
+- 无限额度令牌显示累计已用，不展示无意义的负余额。
+- 这些数字来自站点；模型目录存在、余额可查，都不保证站点已配置可调用的上游。
+
+侧栏显示当前激活渠道的名称与金额，带健康状态点，点击即刷新；侧栏收成 56px 窄栏时只保留状态点。
+
+## 模型清单（按渠道独立）
+
+每个渠道独立维护自己的模型清单，即使两个渠道指向同一个站点、使用同一个令牌也互不影响：
+
+- 「模型能力」页顶部有渠道切换器。激活的渠道带标记，编辑只作用于当前选中的渠道。
+- 「获取模型列表」只读取网关目录，可按模型 ID／厂商搜索，按状态（新增／已添加／网关已下架）和类型（对话／生图／视频／其他）筛选，并按类型分组显示。筛选只影响显示，已勾选的模型不会丢失；列表自身滚动，底部操作栏始终可见。
+- 新增渠道的清单默认为空；旧渠道兼容原有自动模式，第一次添加或删除时按网关当前目录物化清单。
+- 删除只影响当前渠道，不删除上游模型；可以保留自定义参数，并短暂提供撤销。刷新不会把删除的模型自动加回来。
+- 「手动添加」适合网关未列出但可调用的自定义模型。已从网关下架的模型会单独标注，不自动删除。
+
+## 模型测试
+
+- 对话模型测试发送一条很短的真实请求，**会产生调用费用**，显示总耗时、首包时间、最近结果和脱敏错误。只有 `[DONE]` 而没有协议响应的流不算成功。
+- 生图／视频测试每次需要二次确认，实际产生一个生成任务。签名图片链接无法安全展示时仍记录为已生成，但不会暴露链接；界面会提示不要因为看不到预览而重复生成。
+- 批量测试只针对当前筛选下的对话模型，最多 3 个并发。停止会阻止后续排队请求；已发出的请求仍会完成并可能计费。
+- 测试器支持 OpenAI Chat、Responses 和 Anthropic Messages；Gemini 专用协议会明确提示暂不支持，不会悄悄换协议。
+
+## 模型名称映射
+
+在模型编辑器的「名称与映射」中，三个名称各司其职：
+
+- **本地模型 ID**：会话和已启用清单使用的稳定 ID，不在此处修改。
+- **显示名称**（`name`）：只改变 DSH 中的显示。
+- **上游映射模型名**（`upstreamModel`）：真实请求中的 `model`，留空使用本地 ID。映射只进行一次，不会递归追踪其他模型的映射。
+
+例如本地模型 ID 为 `my-chat`、显示名称为「主力模型」、映射为网关支持的模型 ID，选择器和会话仍使用 `my-chat`，网关收到映射后的名称。对话、生图、编辑图片、视频及模型测试都使用同一映射。
+
+编辑器显示请求映射预览。自动协议、能力、额度参数和定价优先从映射目标补全，手动覆盖仍然优先；输入能力可选自动或自定义，推理支持也可恢复为跟随目录。恢复默认会清除该模型的全部覆盖，包括上游映射。
+
+跨厂商或跨模型系列映射需要检查协议、容量和能力是否合适。模型编辑器修改参数时绑定打开时的渠道；出现配置冲突提示应刷新再编辑，避免覆盖另一个窗口的修改。
+
+## 模型与多模态
+
+models.dev 数据有缓存。精确匹配优先，无法匹配时使用默认值；基础模型匹配、默认值与手动覆盖均在界面标出。切勿把猜测的能力当作网关实测结果。
+
+DSH 当前对话接口只支持文本和图片输入。PDF、音频、视频标签表示目录元数据，不能据此直接向 DSH 对话发送这些内容。生图、视频模型供生成工具使用，不作为聊天模型出现。
+
+## 工具
+
+| 工具 | 用途 |
+| --- | --- |
+| `newapi_balance` | 查询当前激活渠道的令牌额度（允许时也含账户余额）。免费。 |
+| `newapi_models` | 列出某个渠道的模型（`channelId` 可选，默认激活渠道），含类型、上限、多模态、定价与映射。免费。 |
+| `newapi_channels` | `list`、`test`、`save`、`activate`、`delete`、`model_override`、`models_discover`、`models_set`、`model_test`；写入需要 `revision`。 |
+| `newapi_image_generate` | 文生图；传 `inputImages` 时调用图片编辑接口，结果存为附件。 |
+| `newapi_video_generate` | 提交视频任务并返回任务 ID，按任务计费。 |
+| `newapi_video_status` | 列出或查询视频任务，返回已保存的文件。 |
+
+设置页操作与这些工具共用同一套服务，界面与 agent 不会产生分叉。
+
+**生图和视频可能扣费。** 提交结果不确定时不会自动重新提交；请先到网关任务日志核对。停止本地观察任务不代表取消网关端生成或退款。
+
+## 付费结果保护
+
+- 视频提交在收到响应头后断流、超时或响应不可解析，显示「提交结果未知，可能已计费」；不会自动重发提交。
+- 视频上游已生成、仅下载失败时显示「已生成，等待下载重试」。仅重试 GET 状态/下载，并重新获取可能过期的下载链接；下载恢复期限届满则显示「已生成，下载未成功」。不要因此重新生成。
+- 同一任务的并发查询合并为一个请求流程，卸载时中止在途网络请求，防止旧实例覆盖新实例缓存。
+- 失败的付费请求不会自动重试。
+
+## 验证范围与限制
+
+- 对话、模型目录、额度、按渠道独立清单与渠道编辑：已在本地 New API（v1.0.0-rc.45）上验证过。
+- 生图真实调用曾返回 503「无可用渠道」，**真实生成成功尚未验证**；附件保存链路由离线测试覆盖。
+- 视频属**实验性**能力：没有真实上游渠道，只做离线提交、后台轮询、下载恢复、重启恢复与不重复提交测试。
+- 只测过一种 New API 部署；其他版本与中转站的接口细节可能不同。
+
+## 从旧开发名称迁移（v0.7.0）
+
+旧名称为 `dsh-newapi-studio`。此版本统一改为 `dsh-newapi-provider`：配置行与模型路由为 `newapi-provider`，HTTP 接口为 `/newapi-provider/api/`，数据目录为 `plugin-data/dsh-newapi-provider`。
+
+已有安装迁移时需先备份配置和数据，再保留各渠道的 ID、凭据引用、模型清单及覆盖参数，将旧数据目录迁移至新名称。当前版本不自动从旧目录读取。既有凭据引用即使含有 `STUDIO` 也应保留，新建引用使用 `NEWAPI_PROVIDER_` 前缀，无需复制令牌。
+
+使用旧 `newapi-studio` 路由的会话需要重新选择新路由下的模型；其他适配器不受影响。工具名 `newapi_channels`、`newapi_models` 等保持不变。
+
+## 开发
+
+```sh
+npm test
+node --check index.js
+node --check client.js
+npm pack --dry-run --ignore-scripts
+```
+
+要针对源码目录开发，用 DSH 插件管理工具安装该项目目录，而不是 npm 包。
+
+无需安装或复制 DSH 官方包；运行时引用通过 optional peerDependencies 声明，由 DSH 宿主提供。测试不依赖真实网关、不读取用户密钥。本插件替代而非依赖 `dsh-gateway-provider`，两个适配器不能占用同一路由。
+
+发布步骤见 [PUBLISHING.md](PUBLISHING.md)。
+
+MIT License。使用 DSH 的公开导出与 pi-ai 协议实现，不包含第三方插件的源码副本。
+
+模型列表中的厂商图标来自 [LobeHub Icons](https://github.com/lobehub/lobe-icons)（`@lobehub/icons-static-svg` 1.97.0，MIT License），以内嵌 SVG 形式打包，不发起外部图片请求。各品牌标识归其所有者，仅用于标明模型所属厂商。