dsh-opencode-go 0.1.23 → 0.2.0

package/README.en.md

@@ -1,6 +1,15 @@
-# dsh-opencode-go
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/logo-dark.png">
+    <img src="docs/assets/logo-light.png" alt="DSH-OCGO" width="480">
+  </picture>
+</p>
 
-[简体中文](README.md)
+<h1 align="center">dsh-opencode-go</h1>
+
+<p align="center">
+  <a href="README.md">简体中文</a>
+</p>
 
 **OpenCode Go subscription usage and multiple-account management** for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness), with convenient access to quotas, reset times, and account switching.
 
@@ -28,6 +37,20 @@ Under **Settings → OpenCode Go → Advanced settings → Usage display**, choo
 | Always | Also show configured OpenCode Go account usage while using other models |
 | Off | Hide the conversation pill and stop its polling |
 
+## Usage analytics
+
+Open **Usage analytics** at the bottom of the conversation usage panel, or under **Settings → OpenCode Go → Usage analytics**. Both open the same dashboard. It covers **this plugin's route**, including closed sessions, totals input, output, and cache tokens per model, and estimates cost with the Go plan's models.dev prices.
+
+- Ranges: today, 7 days, 30 days, and 90 days. Opening scans local sessions without uploading their contents; closing the dialog stops the request. Model and pricing metadata may refresh from [models.dev](https://models.dev/api.json), without sending it conversation content, account keys or per-request analytics. Normal inference sends request content to your configured model gateway, which also serves quota queries; there is no additional telemetry or analytics service.
+- Cost uses the request start time. DeepSeek V4.1 Flash and V4 Pro are charged at twice the off-peak rate during the official peak window (01:00–04:00 and 06:00–10:00 UTC, Monday through Friday).
+- Each model row shows only the display name and usage figures. Official quota percentages remain authoritative; the estimate is not an invoice.
+- A scan stops at 500 sessions, 500,000 events, or 12 seconds by default and says so, including why. **Scan more history** raises the session cap to 2,000; the choice is remembered locally. Session folds are reused in memory for at most five seconds and scanned again after a restart; no fold cache is written to disk.
+- DSH's native OpenCode Go route is excluded; pre-0.1.16 legacy route records are admitted by request time. A Host without `sessionQuery` shows an unavailable state.
+
+**Themes**: switch between **Silent Black, Graphite (default), Sea Salt, and Warm Sand** under **Settings → OpenCode Go → Usage analytics**; the four previews show each palette directly. Themes follow DSH's light/dark mode and are stored locally. The pill popover and the dashboard no longer carry their own switch. The pill no longer carries the `Go ·` prefix; with multiple accounts it shows the active account's full name, truncated with an ellipsis when long, with the complete name kept in the button title and the expanded panel.
+
+See [usage analytics notes](docs/usage-analytics.en.md) for the exact accounting rules and limits.
+
 ## Manage multiple accounts
 
 Open **Settings → OpenCode Go → Accounts** to manage accounts:
@@ -39,13 +62,15 @@ Open **Settings → OpenCode Go → Accounts** to manage accounts:
 - Drag a row's handle to reorder accounts. The first row becomes current, and the order determines automatic fallback priority.
 - Click **Switch** in the conversation usage panel to move the selected account first for subsequent requests in this profile. The other accounts keep their relative order.
 
-With **Automatic fallback** enabled, an exhausted quota or unusable key causes the plugin to try other accounts in order before output begins. A fallback account that starts producing output moves first and becomes current, and the usage panel shows a switch notice. Requests that have already produced output, recorded token usage, or been canceled are not automatically resent through another account.
+With **Automatic fallback** enabled, HTTP 401/403/429 or exhausted quota causes the plugin to try other accounts in order before output begins. A fallback account that starts producing output moves first and becomes current, and the usage panel shows a switch notice. Requests that have already produced output, recorded token usage, or been canceled are not automatically resent through another account.
+
+Gateway-rejected keys cool down in memory for five minutes. Account commands write credentials and settings through one serial host queue.
 
 Keys are saved through DSH's credential service. Settings never displays an already saved key.
 
 ## Install and get started
 
-Requires DSH `0.1.5-rc.1` or later. See the [compatibility matrix](docs/development.md#installed-package-matrix) for verified host versions.
+Requires DSH `0.2.1-rc.5` or later. See [development](docs/development.md) for the current validation workflow.
 
 ### Install from DSH
 
@@ -71,7 +96,7 @@ Start or restart `dsh web` after command-line installation. Web and Headless use
 
 ### Get started
 
-1. Open **Settings → OpenCode Go**, enter your OpenCode Go subscription API key and save, or add an account in **Accounts**.
+1. Open **Settings → OpenCode Go → Accounts**, click **Add account**, enter a name and your OpenCode Go subscription API key, and confirm.
 2. Select a model under **DSH OpenCode Go** in the conversation model picker.
 3. Start chatting and check usage beside the input. With multiple accounts, open the panel to switch.
 
@@ -89,6 +114,8 @@ Search **Available models** by name or ID, or filter by **New in 7 days**, **Cus
 - Select a model to inspect its catalog context window, maximum output, and input modalities. Save limit overrides to apply them; empty values use defaults.
 - Reasoning models offer the applicable switch, effort, or token budget options. Budget-based models also accept custom budgets that become available after saving.
 
+Requests to `deepseek-v4.1-flash` default to a **64k (65,536-token)** output allowance, bounded by the model's output capacity. The same default is reported to DSH for compaction budgeting. This rule applies only to that model; other models retain their SDK output defaults. Set a model's **Max output** override when a longer answer is needed.
+
 Streaming, reasoning, tool calls, and image input depend on model capabilities. Input modalities shown in Settings come from online model metadata; this plugin currently converts and forwards only image attachments.
 
 ### Grouped advanced settings
@@ -115,11 +142,13 @@ Restart `dsh web` and reload the page afterward. For desktop DSH, quit and reope
 
 **Why is usage hidden?** Auto mode shows it only for **DSH OpenCode Go** models. Check that the plugin is enabled, a key is configured, and the display mode is appropriate. Choose Always to show usage with other providers.
 
-**What if usage queries or account additions fail?** Retry in the usage panel or refresh usage in the account card. An added account whose key was not saved can be repaired with a key or removed. See [account operations and saving](docs/advanced.en.md#account-operations-and-saving) for recovery behavior.
+**What if usage queries or account additions fail?** Retry in the usage panel or refresh usage in the account card. Account actions run in a serial host queue; unsuccessful operations can be retried. See [account operations and saving](docs/advanced.en.md#account-operations-and-saving).
+
+**What if a long conversation keeps returning 400?** Check the output allowance and context window in the error, then run `/compact` or lower that model's **Max output** before retrying. Explicit context overflow is passed to DSH's recovery mechanism; an unexplained 400 keeps its classification and includes troubleshooting guidance. Failed attempts without measured tokens omit zero usage so they do not report an empty context.
 
 **Why does an old conversation need its model selected again?** When upgrading from `0.1.16` or earlier, select **DSH OpenCode Go** again in existing conversations or Agent presets. Manual configurations use `provider: dsh-opencode-go`.
 
-**Which hosts are verified?** Installed compatibility covers ten host versions from `0.1.5-rc.1` through `0.2.1-alpha.1`. Later versions need verification. Developer messages, dynamic tool additions/removals, and deferred tool loading are explicitly rejected; see [development and compatibility](docs/development.md).
+**Which host is targeted?** The development baseline is DSH `0.2.1-rc.5`. Developer messages, dynamic tool additions/removals, and deferred tool loading are explicitly rejected; see [development and testing](docs/development.md).
 
 Uninstall:
 
@@ -127,9 +156,36 @@ Uninstall:
 dsh plugin --profile web remove dsh-opencode-go
 ```
 
+## Architecture and verification
+
+The source contains 17 implementation modules:
+
+| Domain | Modules |
+| --- | --- |
+| Plugin composition, settings and contracts | `index.ts`, `config.ts`, `contracts.ts` |
+| Requests, model catalog and protocol conversion | `adapter.ts`, `catalog.ts`, `conversion.ts`, `google.ts`, `sdk-types.ts` |
+| Accounts, official quota, local analytics and transport | `accounts.ts`, `analytics.ts`, `transport.ts` |
+| Browser registration and typed state | `client/index.ts`, `client/controller.ts` |
+| Settings, account/model controls, usage, themes and copy | `client/Section.tsx`, `client/UsagePill.tsx`, `client/AnalyticsDialog.tsx`, `client/presentation.ts` |
+
+The browser uses DSH's `configForms`; capacities remain typed objects while editing. Images use per-request count and encoded-byte budgets, with at most four preparations per request. The package keeps its `.` and `./client` exports. Development dependencies pin DSH `0.2.1-rc.5` and Cordis `4.0.5`; runtime Cordis requires `~4.0.5`.
+
+Use Node.js `^22.19.0 || >=24.0.0`:
+
+```sh
+npm ci
+npm test
+npm run typecheck
+npm run check:dist
+npm run verify
+```
+
+Twelve test files cover host services, accounts, catalog, protocols, analytics, transport and browser interactions. After changing source, run `npm run compile` to rebuild `lib/`. `verify` runs type checks, artifact comparison, the full test suite and the package-loading smoke. See [development](docs/development.md) for separate installed-consumer and Headless checks.
+
 ## More documentation
 
 - [Advanced guide: Headless, proxies, manual configuration, and error diagnostics](docs/advanced.en.md)
+- [Usage analytics: accounting, pricing, scan limits, and privacy](docs/usage-analytics.en.md)
 - [Development and testing](docs/development.md)
 - [Verification notes](docs/verification.md)
 - [Issues and suggestions](https://github.com/Duskriver/dsh-opencode-go/issues)

package/README.md

@@ -1,136 +1,225 @@
-# dsh-opencode-go
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/logo-dark.png">
+    <img src="docs/assets/logo-light.png" alt="DSH-OCGO" width="480">
+  </picture>
+</p>
 
-[English](README.en.md)
+<h1 align="center">dsh-opencode-go</h1>
 
-为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 提供 **OpenCode Go 订阅用量查看与多账号管理**，让额度、重置时间和账号切换更方便。
+<p align="center">
+  <a href="README.en.md">English</a> · <a href="#常见问题-faq">常见问题</a> · <a href="docs/advanced.md">高级指南</a> · <a href="docs/development.md">开发与测试</a>
+</p>
 
-DSH 已支持原生接入 OpenCode Go。本插件重点提供会话内用量查看、多账号管理，以及独立的模型与设置界面。
+为 [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) 量身打造的 **OpenCode Go 专属接入与多账号管理插件**。
 
-- **用量随手可查**：在会话输入区查看用量，展开查看 5 小时、每周、每月已用百分比与重置时间。
-- **多个账号集中管理**：查看各账号额度和 Key 状态，拖动排序，在会话中手动切换，也可开启自动使用备用账号。
-- **模型与设置更直观**：搜索和筛选模型，调整显示、容量与思考预算；高级设置按用途分组，提供提示与恢复默认操作。
+DSH 原生支持接入 OpenCode Go，但原生模式无法满足复杂的生产与日常开发需求（如多账号无感容灾、会话级 Prompt 缓存绑定、会话内实时额度透视等）。本插件基于 Cordis 微内核架构，在提供完整模型协议转换的同时，带来了流畅的客户端 UI 与企业级容灾体验。
 
-支持中文和英文，跟随 DSH 的界面语言。
+---
 
-## 查看订阅用量
+## ✨ 核心特性
 
-点击会话输入区旁的用量胶囊，展开当前账号的订阅用量。进度条显示**已用百分比**，接近上限时变为黄色，耗尽时变为红色；每个额度窗口都显示重置时间。
+- 🛡️ **多账号无感容灾**：支持最多 20 个账号集中管理与拖拽排序。当主账号额度耗尽或 Key 失效时，**在输出前自动尝试备用账号**，成功后自动扶正，告别“聊到一半额度没了”的打断感。
+- ⚡ **会话级 Prompt 缓存绑定**：严格遵循网关协议注入专有 `x-opencode-session` 路由头，稳定复用网关上下文缓存，显著降低响应首字延迟。
+- 📊 **会话内额度实时透视**：在聊天输入框旁常驻“用量胶囊”，直观展示 5 小时滚动、每周、每月的额度百分比及重置时间倒计时；支持休眠节能与静默刷新。
+- 💰 **本地用量看板**：在本地扫描会话历史，按模型与峰谷时段统计 Token 消耗与估算开销，不上传统计所用的会话内容；模型和价格元数据从 models.dev 联网刷新。
+- 🎛️ **模型与热配置**：无需重启 DSH！随时在线调整模型上下文窗口、最大输出上限、思考预算（Thinking Budget），并支持 HTTP/HTTPS/SOCKS5 代理。
 
-![订阅用量面板：当前账号、三个额度窗口及重置时间](docs/assets/usage-panel.png)
+---
+
+## 🚀 快速开始
+
+适用于 DSH `0.2.1-rc.5` 及以上版本；开发与验证方式见[开发说明](docs/development.md)。
+
+### 1. 安装插件
+
+#### 方式 A：在 DSH 界面中一键安装（推荐）
+1. 打开 DSH，进入 **插件 → 添加插件**。
+2. 输入 `dsh-opencode-go`（或填入仓库地址 `https://github.com/Duskriver/dsh-opencode-go`），点击 **安装**。
+3. 安装完成后点击 **立即启用**。
 
-显示用量时每分钟自动刷新；页面进入后台时暂停周期查询，回到前台后刷新。暂时查询失败时，面板会提示失败，并在可保留上次数据时标明“上次数据”，可点击“立即重试”。也可以在设置页的账号卡片中点击 **刷新额度**。
+![在 DSH 中安装插件](docs/assets/install-via-dsh.gif)
 
-在 **设置 → OpenCode Go → 高级设置 → 额度显示** 中选择：
+#### 方式 B：命令行安装
+```sh
+dsh plugin --profile web add dsh-opencode-go
+```
+*命令行安装后请重启 `dsh web`。Headless 用户请使用 `--profile headless`。*
 
-| 模式 | 行为 |
-| --- | --- |
-| 自动（默认） | 选中 **DSH OpenCode Go** 模型时显示 |
-| 常驻 | 使用其他模型时也显示已配置的 OpenCode Go 账号用量 |
-| 关闭 | 隐藏会话用量胶囊并停止其轮询 |
+### 2. 配置与使用
+1. 打开 **设置 → OpenCode Go → 账号**，点击添加，填写账号名称与 OpenCode Go API Key 后确认。
+2. 在任意会话的模型选择器中，选择 **DSH OpenCode Go** 目录下的模型。
+3. 开始对话，输入区右下角即可看到实时的用量胶囊。
 
-## 管理多个账号
+---
 
-在 **设置 → OpenCode Go → 账号** 中集中管理账号：
+## 💡 深度功能与运行机制
+
+### 1. 多账号管理与无感容灾（Auto-failover）
+
+在 **设置 → OpenCode Go → 账号** 中集中管理你的所有账号：
 
 ![账号管理：账号排序、额度详情、Key 操作和自动使用备用账号](docs/assets/accounts.png)
 
-- 添加账号、重命名、替换 Key 或删除账号；最多支持 20 个账号。
-- 每行查看 Key 状态、5 小时已用百分比和重置倒计时，展开查看完整用量与账号操作。
-- 拖动行首手柄调整顺序，第一行成为当前账号；顺序也决定自动尝试备用账号的次序。
-- 在会话用量面板中点击 **切换**，将所选账号移至首位，供本 profile 后续请求使用；其他账号的相对顺序保持不变。
+- **拖拽排序即优先级**：列表第一项为当前主账号；鼠标拖拽左侧手柄调整顺序，这个顺序也是自动尝试备用账号的优先次序。
+- **出词前无感切换**：开启“自动使用备用账号”后，若当前账号在发出请求后遇到了 **401/403 鉴权失败、429 限流或 Quota 额度耗尽**：
+  - 插件会在**开始向你输出文字前**，静默挑出下一个备用账号重新发送请求。
+  - 成功出词的备用账号会自动移至首位成为新主账号，并在会话面板给出切换提示。
+  - *防御机制*：若模型已经开始吐字或已产生计费，插件不会切换，避免拼接乱码或重复扣费。
+- **防雪崩冷却黑名单**：被网关拒绝的 Key 会进入 5 分钟的内存冷却名单，避免短时间内反复向已失效的账号发起无意义的重试。
+- **凭据安全隔离**：Key 直接存储至 DSH 底层凭据系统，前端界面永远不会回显明文密钥。
 
-开启 **自动使用备用账号** 后，当前账号额度耗尽或 Key 不可用时，插件会在开始输出前按顺序尝试其他账号。开始正常输出的备用账号会移至首位并成为当前账号，用量面板会显示切换提示。请求已经输出、产生 token 用量或被取消后，不会自动切换账号重发。
+### 2. 会话内订阅额度透视（UsagePill）
 
-Key 通过 DSH 凭据服务保存，设置页不会回显已保存的密钥。
+在聊天输入区旁，常驻有直观的“用量胶囊”。点击即可展开完整的用量卡片：
 
-## 安装与快速开始
+![订阅用量面板：当前账号、三个额度窗口及重置时间](docs/assets/usage-panel.png)
 
-适用于 DSH `0.1.5-rc.1` 及以上版本。已验证的宿主版本见[兼容矩阵](docs/development.md#installed-package-matrix)。
+- **三窗口精准监控**：
+  - 🟢 **5 小时滚动配额**：短周期高频使用的健康度。
+  - 🟡 **每周配额**：本周累计使用进度。
+  - 🔴 **每月配额**：月度套餐消耗百分比。
+  每个窗口均显示精确的重置倒计时；进度条会随着接近上限变黄，耗尽时变红。
+- **节能与防抖机制**：默认每分钟静默刷新；当页面切入后台或浏览器最小化时**自动暂停轮询**，切换回前台时即时刷新。
+- **账号全名与快速切换**：多账号时直接显示当前账号全名（名字过长以省略号截断），展开面板点击“切换”即可直接提拔目标账号为主账号。
+- **显示模式**（在 **高级设置 → 额度显示** 中配置）：
+  - **自动（默认）**：仅在使用 DSH OpenCode Go 模型时显示。
+  - **常驻**：切换到其他厂商模型时，仍然保持胶囊显示。
+  - **关闭**：隐藏胶囊并停止后台用量轮询。
 
-### 在 DSH 中安装
+### 3. 用量与开销看板（Analytics）
 
-1. 打开 **插件 → 添加插件**。
-2. 输入 `dsh-opencode-go`，点击 **安装**。
-3. 安装完成后点击 **立即启用**。
+点击用量面板底部的 **用量统计**，或进入 **设置 → OpenCode Go → 用量统计** 即可唤出看板：
 
-![在 DSH 中安装插件](docs/assets/install-via-dsh.gif)
+- **本地扫描与缓存**：直接调用 DSH 宿主 `sessionQuery` 扫描本地历史会话，统计本插件产生的 Token 消耗，不会为统计上传会话内容。模型和价格元数据会从 models.dev 联网刷新。会话折叠结果仅在内存中最多复用 5 秒，重启后重新扫描，不写入磁盘缓存。
+- **峰谷电价式开销估算**：使用从 models.dev 获取的模型价格；自动识别 DeepSeek V4.1 Flash / V4 Pro 等模型的官方峰时时段（UTC 周一至周五 01:00–04:00、06:00–10:00）并按双倍费率估算金额。
+- **四款专属主题**：支持在 **寂静黑 / 石墨（默认）/ 海盐青 / 暖砂** 之间切换，自动适配系统的亮色/暗色模式。
 
-也可以在添加插件时输入仓库地址：
+---
+
+## 🛠️ 架构设计与工作原理
+
+源码按领域收敛为 17 个实现模块，宿主与浏览器通过 DSH Typert RPC 通讯：
 
 ```text
-https://github.com/Duskriver/dsh-opencode-go
+src/
+├── index.ts + config.ts          插件挂载、configure 设置与热更新
+├── contracts.ts                 浏览器可用的配置、模型与 RPC 契约
+├── adapter.ts                   请求执行、会话头、容灾与冷却
+├── catalog.ts                   模型目录与公共元数据缓存
+├── conversion.ts                上下文、单次请求图片预算、回放与流转换
+├── google.ts + sdk-types.ts      Google SDK 接入与公开类型
+├── accounts.ts                  串行账号命令、凭据写入与官方配额
+├── analytics.ts                 本地统计、内存会话缓存与计价
+├── transport.ts                 HTTP/HTTPS/SOCKS5、超时与脱敏错误
+└── client/
+    ├── index.ts + controller.ts  configForms 接入、类型化草稿与账号操作
+    ├── Section.tsx              设置页、账号卡片、模型编辑器与主题选择
+    ├── UsagePill.tsx            会话额度胶囊
+    ├── AnalyticsDialog.tsx      用量与费用看板
+    └── presentation.ts          多语言、主题与显示格式
 ```
 
-命令行安装：
+账号操作在内存串行队列中直接更新凭据与设置。模型容量草稿始终保留为对象；图片按单次请求限制数量、编码字节及最多四路并行准备。宿主仅使用 DSH `0.2.1-rc.5` 起提供的设置与图片卸载接口。包的 `.` 与 `./client` 导出路径保持不变。
 
-```sh
-dsh plugin --profile web add dsh-opencode-go
-```
+### 为什么必须要携带 `x-opencode-session`？
+OpenCode Go 网关具有会话粘性路由与上下文缓存共享能力。插件会自动将你的 DSH 对话 ID 经过单向哈希（保留可读字符并在需要时转为安全散列），以稳定的形式放入 `x-opencode-session` 请求头中。这样不仅能让多轮对话始终落在同一推理节点上，还能最大化命中网关的 Prompt Cache，显著节省思考与生成时间。
 
-命令行安装后启动或重启 `dsh web`。Web 和 Headless 使用各自的 profile，分别安装和更新。
+---
 
-### 开始使用
+## ⚙️ 模型自定义与高级配置
 
-1. 打开 **设置 → OpenCode Go**，填入 OpenCode Go 订阅的 API Key 并保存，或在 **账号** 中添加账号。
-2. 在会话模型选择器中选择 **DSH OpenCode Go** 下的模型。
-3. 开始对话，在输入区旁查看用量；有多个账号时可展开面板切换。
+### 模型参数覆盖
+进入 **设置 → OpenCode Go → 可用模型**：
 
-插件使用独立的模型提供方 **DSH OpenCode Go**。选择 DSH 原生提供的模型不会自动使用本插件的账号切换功能；“常驻”模式仍可展示本插件已配置账号的用量。
+![模型设置：搜索、分类筛选、显示开关和参数编辑](docs/assets/model-settings.png)
 
-## 模型与设置
+- **显示开关**：自由隐藏不常用的模型，净化聊天选择器。
+- **容量与上下文覆盖**：可手动指定上下文窗口（Context Window）与单次最大输出 Token。
+- **思考预算（Thinking Budget）**：对支持深度思考的模型，可自定义思考强度等级或 Token 预算。
+- *特别规则*：`deepseek-v4.1-flash` 默认自动配置 **64k (65,536 tokens)** 输出预算，并将该上限通知 DSH 宿主，用于计算上下文压缩时机。
 
-### 选择模型与调整参数
+### 分组高级设置
+支持在 **设置 → OpenCode Go → 高级设置** 中按需微调：
 
-在 **可用模型** 中按名称或 ID 搜索，也可以筛选 **近 7 天发布**、**已自定义** 或 **过时模型**。点击 **刷新** 核对最新模型目录。
+![高级设置：分组配置、提示入口和统一恢复默认](docs/assets/advanced-settings.png)
 
-![模型设置：搜索、分类筛选、显示开关和参数编辑](docs/assets/model-settings.png)
+- **网络代理**：支持填入 HTTP、HTTPS 或 SOCKS5 代理地址（如 `socks5://127.0.0.1:1080`），保存后即时应用于对话、用量查询与模型刷新。
+- **超时控制**：分别支持配置请求准备超时（`requestPreparationTimeoutMs`）、整轮请求超时（`requestTimeoutMs`）以及流空闲看门狗阈值（`streamIdleTimeoutMs`）。
+- **一键恢复默认**：点击每张卡片的“全部恢复默认”可一键清空自定义覆盖，不影响已保存的账号 Key。
 
-- 模型开关控制它是否出现在会话选择器中，修改立即生效。
-- 选中模型可查看目录提供的上下文窗口、最大输出和输入模态，容量覆盖保存后生效，留空使用默认值。
-- 支持思考的模型提供相应开关、强度或 token 预算选项；预算式模型还可添加自定义预算并保存。
+---
 
-流式回复、思考、工具调用和图片输入取决于模型能力。界面中的输入模态来自在线模型配置；本插件目前仅转换并转发图像附件。
+## ❓ 常见问题 (FAQ)
 
-### 分组高级设置
+<details>
+<summary><strong>Q: 为什么聊天输入区没有出现用量胶囊？</strong></summary>
 
-高级设置按 **用量与协议**、**连接**、**缓存与超时**、**图片处理** 分组。悬停问号查看说明，可通过 **全部恢复默认** 清除该卡片的自定义覆盖，再保存修改；当前账号选择保持不变。
+1. 检查当前会话选中的模型是否为 **DSH OpenCode Go** 分组下的模型。默认“自动”模式仅在选择本插件模型时展示；若希望在使用其他模型时也看到配额，可在 **高级设置 → 额度显示** 中切为“常驻”。
+2. 检查是否已在设置中填入有效 API Key 且插件已处于启用状态。
+</details>
 
-![高级设置：分组配置、提示入口和统一恢复默认](docs/assets/advanced-settings.png)
+<details>
+<summary><strong>Q: 为什么长会话中偶尔会报 400 错误？</strong></summary>
+
+通常是因为单次上下文加输出预算超过了模型允许的 Context Window。建议：
+1. 在会话中执行 `/compact` 指令压缩历史消息。
+2. 或在 **可用模型** 设置中，适度调低该模型的“最大输出”上限。
+明确的上下文超限错误会被插件捕获并交由 DSH 原生恢复机制处理。
+</details>
+
+<details>
+<summary><strong>Q: 升级插件后，旧会话找不到模型怎么办？</strong></summary>
 
-支持 HTTP、HTTPS 和 SOCKS5 代理，保存后用于后续对话、模型目录更新与用量查询。代理运行在 DSH 所在的机器上；远程部署中的 `127.0.0.1` 指服务器自身。
+从 `0.1.16` 及更早版本升级时，底层 Provider ID 进行了规范化统一。只需在旧会话或 Agent 配置的模型下拉框中，重新选择一次 **DSH OpenCode Go** 下的模型即可。
+</details>
 
-DeepSeek V4.1 Flash 的 Responses 协议选项为实验性，仅影响新请求，不承诺更低延迟。完整配置与使用说明见[高级使用指南](docs/advanced.md)。
+<details>
+<summary><strong>Q: 插件在执行过程中会自动将我的数据上传到第三方吗？</strong></summary>
 
-截图用于展示界面，具体模型、额度和时间以当前账号与在线目录为准。
+正常对话会把请求内容发送到你配置的模型网关（默认为 OpenCode Go 官方网关），额度查询也会访问该网关。插件还会从 [models.dev](https://models.dev/api.json) 下载公开的模型能力与价格元数据。
 
-## 更新与常见问题
+用量统计在本地读取会话记录，不会把会话正文、账号密钥或逐条统计记录发送给 models.dev，也没有额外的遥测或分析服务。因此，本地统计不等于插件完全不联网。
+</details>
 
-更新到 npm 最新发布版本：
+---
 
+## 📦 更新与卸载
+
+### 更新插件
 ```sh
 dsh plugin --profile web update dsh-opencode-go --latest
 ```
+更新后重启 `dsh web` 并刷新浏览器页面（桌面客户端请完全退出后重新打开）。
 
-更新后重启 `dsh web` 并刷新页面；桌面版完全退出后重新打开。Headless 用户将 `web` 换成 `headless`。仓库默认分支可能包含尚未发布到 npm 的修改。
-
-**为什么没有显示用量？** 默认“自动”模式仅在选择 **DSH OpenCode Go** 模型时显示。请检查插件是否启用、Key 是否配置，以及额度显示模式；使用其他提供方时可选择“常驻”。
-
-**查询失败或添加账号中断怎么办？** 用量查询可在面板中重试，或在账号卡片中刷新额度。未成功保存 Key 的新增账号可补填 Key 或删除；账号操作的恢复机制见[高级使用指南](docs/advanced.md#账号操作与保存)。
+### 卸载插件
+```sh
+dsh plugin --profile web remove dsh-opencode-go
+```
 
-**升级后旧会话找不到模型？** 从 `0.1.16` 及更早版本升级时，在旧会话或 Agent 预设中重新选择 **DSH OpenCode Go**；手动配置使用 `provider: dsh-opencode-go`。
+---
 
-**兼容性范围是什么？** 安装兼容性覆盖十个宿主版本，从 `0.1.5-rc.1` 到 `0.2.1-alpha.1`，后续版本仍需验证。目前明确拒绝 developer 消息、动态工具增删和延迟工具加载，详见[开发与兼容性说明](docs/development.md)。
+## 🧪 开发与验证
 
-卸载：
+使用 Node.js `^22.19.0 || >=24.0.0`，开发依赖锁定 DSH `0.2.1-rc.5`、Cordis `4.0.5`；宿主 Cordis 要求 `~4.0.5`。
 
 ```sh
-dsh plugin --profile web remove dsh-opencode-go
+npm ci
+npm test
+npm run typecheck
+npm run check:dist
+npm run verify
 ```
 
-## 更多文档
+测试按 12 个领域文件覆盖宿主、协议转换、账号、统计、传输和前端。修改源码后先运行 `npm run compile` 更新 `lib/`；`verify` 包含类型检查、产物一致性、全量测试与包加载冒烟。独立安装和 Headless 验证见[开发说明](docs/development.md)。
+
+---
+
+## 📚 更多文档与链接
 
-- [高级使用指南：Headless、代理、手动配置与错误诊断](docs/advanced.md)
-- [开发与测试](docs/development.md)
-- [验证记录](docs/verification.md)
-- [问题与建议](https://github.com/Duskriver/dsh-opencode-go/issues)
-- [MIT 许可证](LICENSE)
+- 📖 [高级使用指南（Headless 部署、代理策略与错误排查）](docs/advanced.md)
+- 📊 [用量看板统计说明（计价口径与扫描策略）](docs/usage-analytics.md)
+- 🛠️ [开发与贡献指南](docs/development.md)
+- 🧪 [验收范围与验证记录](docs/verification.md)
+- 🐛 [提交 Issue 与建议](https://github.com/Duskriver/dsh-opencode-go/issues)
+- 📄 [MIT 开源许可证](LICENSE)

package/THIRD_PARTY_NOTICES.md

@@ -1,6 +1,6 @@
 # Third-party notices
 
-The initial adapter, settings UI, and `src/conversion/{context,stream,replay}.ts` were derived from DeepSeek Harness, copyright (c) 2026 DeepSeek, under the MIT license included in LICENSE. The original DeepSeek copyright notice is retained for these derived portions. The conversion modules are maintained in this package because the published DSH pi-ai package does not export its conversion helpers.
+The initial adapter, settings UI, and `src/conversion.ts` were derived from DeepSeek Harness, copyright (c) 2026 DeepSeek, under the MIT license included in LICENSE. The original DeepSeek copyright notice is retained for these derived portions. The conversion code is maintained in this package because the published DSH pi-ai package does not export its conversion helpers.
 
 Original additions and subsequent modifications made in this project are copyright (c) 2026 dsh-opencode-go contributors and are also licensed under MIT. LICENSE records both the upstream attribution and this project's contributor attribution.
 

package/docs/advanced.en.md

@@ -89,7 +89,7 @@ Keep the options you need and supply the corresponding keys through DSH credenti
 
 | Option | Purpose |
 | --- | --- |
-| `baseURL` | Shared OpenCode Go gateway prefix for model discovery, inference and usage; defaults to `https://opencode.ai/inference/go/v1` |
+| `baseURL` | OpenCode Go gateway address; defaults to `https://opencode.ai/inference/go/v1`, with official inference endpoints selected by model protocol |
 | `usageDisplay` | Usage display mode: `auto`, `always`, or `off` |
 | `proxyURL` | Network proxy; an empty string uses the default network settings |
 | `refreshMinutes` | Model catalog cache lifetime; defaults to 60 minutes, with manual refresh available in Settings |
@@ -101,37 +101,30 @@ Keep the options you need and supply the corresponding keys through DSH credenti
 | `requestPreparationTimeoutMs` | Deadline for discovery and each attempt's credential/image preparation; defaults to 60000 milliseconds |
 | `requestTimeoutMs` | Whole dispatch deadline, including discovery, account fallback and streaming; defaults to 1800000 milliseconds. Prepared calls start this timer at dispatch |
 
-Request paths are appended to `baseURL`: `GET /models` lists models, `POST /models/{model}:streamGenerateContent` sends Gemini requests, and `GET /usage` reads usage. A working listing does not verify every inference route. Reading the legacy official base `https://opencode.ai/zen/go/v1` migrates it to the new address for model discovery, every inference protocol and usage requests. Settings writes also store the new address, so operation does not depend on the legacy gateway remaining available. Custom gateways retain their configured addresses.
+The default official gateway lists models at `GET https://opencode.ai/inference/go/v1/models` and reads usage at `GET https://opencode.ai/inference/go/v1/usage`. Inference follows each model's declared protocol and the [official endpoint documentation](https://opencode.ai/v2/docs/console/go/#endpoints). The following paths share the prefix `https://opencode.ai/inference/go`:
 
-Image offloading keeps the original attachment and replaces the old image in the request with a text placeholder. Raising the limit does not automatically restore previously offloaded images.
-
-Image count overflow is detected before attachment reads. Preparation shares four execution slots and at most 32 queued tasks within the plugin module, and stops scheduling images when known encoded bytes exceed the payload cap. Active image attempts share a 128 MiB budget for prepared raw data plus base64 payloads; this is not a process memory limit. Queue or shared-budget overflow returns `IMAGE_RESOURCE_BUSY`; retry after another request completes. Count and byte limits may require successive host offload retries.
-
-A cold catalog outage reports `DISCOVERY_FAILED`; a warm catalog retains previously verified models. Only an explicit empty gateway listing clears membership. A partially malformed listing keeps its valid models and reports the ignored row count in settings and logs. Ordinary advanced form settings commit in one revision-checked batch. Credentials use a separate service; failed credential drafts remain, and retry submits only uncommitted parts.
+| Model protocol | Inference path |
+| --- | --- |
+| OpenAI Chat Completions, such as GLM-5.3-Flash | `/openai/v1/chat/completions` |
+| OpenAI Responses, such as Grok 4.7 and GPT 6 Luna | `/openai/v1/responses` |
+| Anthropic Messages, such as Claude Haiku 5.5 | `/anthropic/v1/messages` |
+| Google, such as Gemini 4 Argon Contributor | `/google/v1beta/models/{model}:streamGenerateContent` |
 
-### Export error diagnostics
+The legacy official base `https://opencode.ai/zen/go/v1` migrates automatically, and settings writes store the new address. There is no need to change the gateway for each model. Custom gateways keep the configured `baseURL` prefix and let each protocol SDK append its resource path; official protocol segments are not added automatically. A working listing does not verify every inference route.
 
-To investigate a failed request, set a diagnostics directory before starting DSH:
+Usage failures retain the HTTP status and show a redacted summary when the upstream provides a readable reason. HTTP 403 includes a reminder to check the API key and Go subscription permissions. “Key saved” only confirms local credential storage; check the subscription for the account or workspace that owns the key, along with the gateway and proxy settings.
 
-```sh
-export DSH_OPENCODE_GO_DEBUG_DIR=/tmp/dsh-opencode-go-debug
-dsh web
-```
+Image offloading keeps the original attachment and replaces the old image in the request with a text placeholder. Raising the limit does not automatically restore previously offloaded images.
 
-Windows PowerShell:
+Image count overflow is detected before attachment reads. Each request prepares at most four images concurrently and stops when known encoded bytes exceed its payload budget. There is no plugin-wide image queue or shared payload pool.
 
-```powershell
-$env:DSH_OPENCODE_GO_DEBUG_DIR = "$env:TEMP\dsh-opencode-go-debug"
-dsh web
-```
 
-Reproduce the failure to get a JSON file path in the error message. The record contains the model, request parameter summaries, HTTP status, upstream log and route IDs, and the error response, for use in an [issue report](https://github.com/Duskriver/dsh-opencode-go/issues). Review the returned error content before sharing. Clear the environment variable and restart DSH to disable diagnostics.
-
-DSH debug logs contain a call ID and each attempt's stage timings, HTTP status, upstream request ID, time to first output and error code, including stream failures after HTTP 200. Image attempts also report aggregate queue waiting and peak resource occupancy. Error files carry the same call ID and attempt number for correlation. These summaries exclude prompts, keys, proxy addresses and raw session IDs.
+A cold catalog outage reports `DISCOVERY_FAILED`; a warm catalog retains previously verified models. Only an explicit empty gateway listing clears membership. A partially malformed listing keeps its valid models and reports the ignored row count in settings and logs. Ordinary advanced form settings commit in one revision-checked batch. Credentials use a separate service; failed credential drafts remain, and retry submits only uncommitted parts.
 
+Request failures retain HTTP classification, redacted upstream summaries and applicable context-capacity hints. The plugin no longer writes internal diagnostic files or per-call traces.
 
 ## Account operations and saving
 
-If adding or removing an account is interrupted by closing the page or losing the connection, the host resumes recovery at startup or after settings and credential updates. An addition whose key was never stored stays visible so you can replace its key or remove it. Recovery preserves a current-account choice made in the meantime.
+Account operations run in a host-owned memory queue, with credential writes completed before settings updates. Closing the page does not cancel a storage write already in progress. There is no transaction journal or startup recovery loop; retry an unsuccessful operation from the accounts card.
 
 Reset all to defaults in advanced settings removes overrides at the current layer and restores inherited values; save to apply the reset. It does not remove accounts or keys, or clear model limit overrides.

package/docs/advanced.md

@@ -87,7 +87,7 @@ socks5://127.0.0.1:1080
 
 | 配置项 | 用途 |
 | --- | --- |
-| `baseURL` | 模型列表、对话发送和额度查询共用的 OpenCode Go 网关前缀，默认 `https://opencode.ai/inference/go/v1` |
+| `baseURL` | OpenCode Go 网关地址，默认 `https://opencode.ai/inference/go/v1`；官方网关自动按模型协议选择推理端点 |
 | `usageDisplay` | 额度显示模式：`auto`、`always` 或 `off` |
 | `proxyURL` | 网络代理；空字符串使用默认网络设置 |
 | `refreshMinutes` | 模型目录缓存时长，默认 60 分钟；设置页可随时手动刷新 |
@@ -99,37 +99,30 @@ socks5://127.0.0.1:1080
 | `requestPreparationTimeoutMs` | 目录查询及每次尝试的凭据、图片准备时限，默认 60000 毫秒 |
 | `requestTimeoutMs` | 一次发送的完整时限，包含目录查询、账号切换和流式输出，默认 1800000 毫秒；预先准备的调用从发送时计时 |
 
-`baseURL` 后会按用途拼接路径：模型列表使用 `GET /models`，Gemini 发送使用 `POST /models/{model}:streamGenerateContent`，额度查询使用 `GET /usage`。列表可访问不代表所有推理接口都可用。读取旧官方地址 `https://opencode.ai/zen/go/v1` 时，插件会统一迁移为新地址，模型列表、所有协议的发送和额度查询都使用新网关；保存设置时也会写入新地址。因此运行不依赖旧网关继续服务。自定义网关仍按配置发送。
+默认官方网关使用 `GET https://opencode.ai/inference/go/v1/models` 读取模型列表，使用 `GET https://opencode.ai/inference/go/v1/usage` 查询额度。推理端点按模型目录声明的协议选择，与[官方文档](https://opencode.ai/v2/docs/console/go/#endpoints)一致，以下路径均以 `https://opencode.ai/inference/go` 为前缀：
 
-图片卸载会保留原始附件，并将请求中的旧图片替换为文字占位；调高上限不会自动恢复已卸载的历史图片。
-
-图片数量超限会在读取附件前返回卸载请求；图片准备在同一插件模块内共享四个执行名额和最多 32 个等待名额，精确字节超限时停止安排剩余图片。正在发送的图片请求共享 128 MiB 的已准备原始数据与 base64 预算；这不是进程总内存上限。排队或共享预算超限会返回 `IMAGE_RESOURCE_BUSY`，可在其他请求结束后重试。数量与字节限制可能需要宿主分次卸载后重试。
-
-首次查询目录失败会报告 `DISCOVERY_FAILED`；已有目录时保留之前确认过的模型。网关明确返回空列表才会清空目录。列表中仅部分行格式错误时，仍可使用有效模型，设置页与日志会提示被忽略的行数。高级表单的普通配置项一次提交并检查版本；凭据由独立服务保存，凭据保存失败时保留其草稿，重试只提交未成功的部分。
+| 模型协议 | 推理路径 |
+| --- | --- |
+| OpenAI Chat Completions（如 GLM-5.3-Flash） | `/openai/v1/chat/completions` |
+| OpenAI Responses（如 Grok 4.7、GPT 6 Luna） | `/openai/v1/responses` |
+| Anthropic Messages（如 Claude Haiku 5.5） | `/anthropic/v1/messages` |
+| Google（如 Gemini 4 Argon Contributor） | `/google/v1beta/models/{model}:streamGenerateContent` |
 
-### 导出错误诊断
+读取旧官方地址 `https://opencode.ai/zen/go/v1` 时，插件会自动迁移，保存设置时也会写入新地址。无需为每个模型手动修改网关。自定义网关继续使用填写的 `baseURL` 作为请求前缀，由各协议 SDK 拼接资源路径；不会自动添加官方网关的协议分段。列表可访问不代表所有推理接口都可用。
 
-需要排查请求失败时，在启动 DSH 前设置诊断目录：
+额度查询失败时，面板会保留 HTTP 状态码，并在上游提供可读原因时显示脱敏后的摘要。HTTP 403 会提示检查 API Key 和 Go 订阅权限；账号显示“已配置 key”仅代表本地保存了凭据。可同时核对 Key 所属账号或 workspace 的订阅状态，以及网关与代理配置。
 
-```sh
-export DSH_OPENCODE_GO_DEBUG_DIR=/tmp/dsh-opencode-go-debug
-dsh web
-```
+图片卸载会保留原始附件，并将请求中的旧图片替换为文字占位；调高上限不会自动恢复已卸载的历史图片。
 
-Windows PowerShell：
+图片数量超限会在附件读取前检测。每个请求最多并发准备 4 张图片，并在已知编码大小超过单次请求预算时停止；插件不再维护全局图片队列或共享内存池。
 
-```powershell
-$env:DSH_OPENCODE_GO_DEBUG_DIR = "$env:TEMP\dsh-opencode-go-debug"
-dsh web
-```
 
-复现后，错误信息会给出 JSON 文件路径。记录包含模型、请求参数摘要、HTTP 状态、上游日志与路由编号及错误响应，便于提交 [问题反馈](https://github.com/Duskriver/dsh-opencode-go/issues)。分享前检查服务返回的错误内容；清空环境变量并重启 DSH 即可关闭诊断。
-
-DSH debug 日志另有每次发送的调用编号，以及各次尝试的阶段耗时、HTTP 状态、上游请求编号、首次输出等待时间与错误码，包含 HTTP 200 后的流中断；图片请求还记录排队累计等待与资源占用峰值。错误文件带有相同调用编号与尝试序号，便于关联排查。这些摘要不记录提示词、Key、代理地址或原始会话编号。
+首次查询目录失败会报告 `DISCOVERY_FAILED`；已有目录时保留之前确认过的模型。网关明确返回空列表才会清空目录。列表中仅部分行格式错误时，仍可使用有效模型，设置页与日志会提示被忽略的行数。高级表单的普通配置项一次提交并检查版本；凭据由独立服务保存，凭据保存失败时保留其草稿，重试只提交未成功的部分。
 
+请求失败时，错误信息仍包含 HTTP 分类、脱敏后的上游摘要，以及适用的上下文容量提示。插件不再输出内部诊断文件或逐调用追踪。
 
 ## 账号操作与保存
 
-新增或删除账号中途关闭页面、断开连接时，宿主会在后续启动或设置、凭据更新时继续恢复。未能写入 Key 的新增账号会保留在列表，可补填 Key 或删除；恢复不会覆盖期间手动选择的当前账号。
+账号操作按宿主内存队列顺序执行，凭据写入完成后再更新设置。页面中断不会取消已经开始的存储写入；进程重启后没有事务日志或自动恢复循环，未成功的操作可从账号卡片重新执行。
 
 高级设置的“全部恢复默认”会清除当前层的自定义覆盖，恢复继承值；需要保存后才生效。它不删除账号或 Key，也不清除模型容量覆盖。