dsh-opencode-go 0.1.24 → 0.2.1

package/README.en.md

@@ -1,11 +1,22 @@
-# 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.
 
 DSH already supports OpenCode Go natively. This plugin focuses on usage inside conversations, managing multiple accounts, and dedicated model and settings controls.
 
+- **Independent Go and Free routes**: dynamically discover each gateway’s chat models, keep overlapping IDs, and edit them in separate settings tabs. Free shares saved keys and uses public access when none is usable.
+- **Free rate-limit protection**: honors upstream `Retry-After` and pauses new requests during cooldown. Shared Free quota/IP limits do not rotate Go accounts.
 - **Usage at a glance**: see usage beside the conversation input, then open the panel for five-hour, weekly, and monthly percentages and reset times.
 - **Accounts in one place**: inspect each account's quota and key status, drag to reorder, switch inside a conversation, or enable automatic fallback.
 - **Clearer model and settings controls**: search and filter models, adjust visibility, limits, and thinking budgets; advanced settings are grouped by purpose, with hints and a reset action.
@@ -16,8 +27,6 @@ Supports Chinese and English, following DSH's interface language. The screenshot
 
 Click the usage pill beside the conversation input to open the current account's subscription usage. Bars show the **percentage used**, turn amber near the limit, and red when exhausted. Each quota window shows its reset time.
 
-![Subscription usage: current account, three quota windows, and reset times](docs/assets/usage-panel.png)
-
 While visible, usage refreshes every minute. Periodic queries pause while the page is hidden and resume with a refresh when it becomes visible. Temporary failures show a warning; retained readings are marked as previous data. Click **Retry now** after a failure, or **Refresh accounts** in the Settings account card.
 
 Under **Settings → OpenCode Go → Advanced settings → Usage display**, choose:
@@ -28,6 +37,22 @@ 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 the dashboard from the conversation input's expanded usage pill or the sidebar dashboard button.
+
+![Official workspace history dashboard with sample data](docs/assets/usage-history-desktop.jpg)
+
+[Narrow-screen light preview](docs/assets/usage-history-mobile.jpg) · [Model rankings and detail](docs/assets/usage-history-models.jpg), both using sample data.
+
+- **One official source**: totals, daily charts and model detail use the same official daily CSV, covering requests, input/output/cache tokens and the official usage amount. Models are grouped by provider + model. Ranges are today, 7, 30 and 90 days; all dates use UTC.
+- **Independent viewing account**: defaults to the current inference account and shows only the workspace belonging to the selected key, including calls from other clients. Changing the viewing account does not change the conversation account. All three dashboard quota windows follow the selection. Anonymous Free coverage is not guaranteed.
+- **Official usage amount**: sums `cost_micro_cents` directly (`1 USD = 100,000,000` units); it does not mean an additional Go charge. Official daily aggregates may be delayed.
+- **One visual language**: settings, the usage pill, sidebar and dashboard share warm paper / charcoal surfaces and terracotta accents, following the Host's light/dark mode. Locally installed Anthropic Serif / Sans / Mono fonts are preferred, with system and CJK serif fallbacks. The dashboard becomes full-screen on narrow screens and retains daily token/request bars, model rankings and details.
+- **On-demand queries**: history loads when opening, changing account or range, or refreshing manually. The Host uses a 30-second cache; forced refresh bypasses it. History is not polled in the background. Only official model gateway configurations support it; errors remain explicit without falling back to local scans.
+
+Keys stay on the Host. Normal reports send the browser only aggregate numbers and provider / model / day; an official CSV explicitly downloaded by the user may contain member fields. See [usage analytics notes](docs/usage-analytics.en.md) for accounting and privacy details.
+
 ## Manage multiple accounts
 
 Open **Settings → OpenCode Go → Accounts** to manage accounts:
@@ -39,13 +64,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 +98,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,19 +116,19 @@ 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.
+Any model with an output capacity above **65,536 tokens** defaults to that allowance when neither the caller nor settings specifies one. Smaller models retain their SDK defaults. DSH receives the same allowance for compaction budgeting. 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
 
-Advanced settings are grouped into **Usage and protocol**, **Connection**, **Cache and timeouts**, and **Image handling**. Hover over a question mark for help. **Reset all to defaults** clears the card's custom overrides; save to apply the reset. The current account selection is preserved.
+Advanced settings are grouped into **Usage settings**, **Connection**, **Cache and timeouts**, and **Image handling**. Hover over a question mark for help. **Reset all to defaults** clears the card's custom overrides; save to apply the reset. The current account selection is preserved.
 
 ![Advanced settings: grouped controls, hints, and a shared reset action](docs/assets/advanced-settings.png)
 
 HTTP, HTTPS, and SOCKS5 proxies are supported. After saving, subsequent conversations, catalog updates, and usage queries use the proxy. Connections originate from the machine running DSH; on a remote deployment, `127.0.0.1` refers to that server.
 
-The DeepSeek V4.1 Flash Responses option is experimental, applies only to new requests, and does not promise lower latency. See the [advanced guide](docs/advanced.en.md) for full configuration and usage instructions.
+Set `baseURL` and `freeBaseURL` independently under Connection. Protocol selection follows the gateway model declaration. See the [advanced guide](docs/advanced.en.md) for account, model-key and disk-cache details.
 
 Screenshots illustrate the interface. Actual models, quotas, and timestamps depend on your account and the current online catalog.
 
@@ -117,13 +144,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:
 
@@ -131,9 +158,36 @@ Uninstall:
 dsh plugin --profile web remove dsh-opencode-go
 ```
 
+## Architecture and verification
+
+The source is organized by domain:
+
+| 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, official CSV history and transport | `accounts.ts`, `analytics.ts`, `transport.ts` |
+| Browser registration and typed state | `client/index.ts`, `client/controller.ts` |
+| Host settings, account/model controls, usage 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
+```
+
+Tests cover host services, accounts, catalog, protocols, analytics, transport, Free backoff, 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: official source, accounting, 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,140 +1,233 @@
-# 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 的界面语言。
+---
 
-## 查看订阅用量
+## ✨ 核心特性
 
-点击会话输入区旁的用量胶囊，展开当前账号的订阅用量。进度条显示**已用百分比**，接近上限时变为黄色，耗尽时变为红色；每个额度窗口都显示重置时间。
+- 🆓 **双路由动态模型目录**：Go 与平台免费模型分别从各自网关的 `/models` 发现，保留同名模型；Free 无 Key 时可使用公共访问，两套模型开关与容量设置独立。
+- 🛑 **免费通道限流保护**：遵循上游 `Retry-After`，冷却期间暂停新请求；共享免费额度或 IP 限制不会触发 Go 换号。
+- 🛡️ **多账号无感容灾**：支持最多 20 个账号集中管理与拖拽排序。当主账号额度耗尽或 Key 失效时，**在输出前自动尝试备用账号**，成功后自动扶正，告别“聊到一半额度没了”的打断感。
+- ⚡ **会话级 Prompt 缓存绑定**：严格遵循网关协议注入专有 `x-opencode-session` 路由头，稳定复用网关上下文缓存，显著降低响应首字延迟。
+- 📊 **会话内额度实时透视**：在聊天输入框旁常驻“用量胶囊”，直观展示 5 小时滚动、每周、每月的额度百分比及重置时间倒计时；支持休眠节能与静默刷新。
+- 💰 **官方历史用量看板**：按所选 Key 的工作区汇总官方每日 CSV，查看请求、Token、官方用量金额与模型明细，包含其他客户端的调用。
+- 🎛️ **模型与热配置**：无需重启 DSH！随时在线调整模型上下文窗口、最大输出上限、思考预算（Thinking Budget），并支持 HTTP/HTTPS/SOCKS5 代理。
 
-![订阅用量面板：当前账号、三个额度窗口及重置时间](docs/assets/usage-panel.png)
+---
 
-显示用量时每分钟自动刷新；页面进入后台时暂停周期查询，回到前台后刷新。暂时查询失败时，面板会提示失败，并在可保留上次数据时标明“上次数据”，可点击“立即重试”。也可以在设置页的账号卡片中点击 **刷新额度**。
+## 🚀 快速开始
 
-在 **设置 → OpenCode Go → 高级设置 → 额度显示** 中选择：
+适用于 DSH `0.2.1-rc.5` 及以上版本；开发与验证方式见[开发说明](docs/development.md)。
 
-| 模式 | 行为 |
-| --- | --- |
-| 自动（默认） | 选中 **DSH OpenCode Go** 模型时显示 |
-| 常驻 | 使用其他模型时也显示已配置的 OpenCode Go 账号用量 |
-| 关闭 | 隐藏会话用量胶囊并停止其轮询 |
+### 1. 安装插件
 
-## 管理多个账号
+#### 方式 A：在 DSH 界面中一键安装（推荐）
+1. 打开 DSH，进入 **插件 → 添加插件**。
+2. 输入 `dsh-opencode-go`（或填入仓库地址 `https://github.com/Duskriver/dsh-opencode-go`），点击 **安装**。
+3. 安装完成后点击 **立即启用**。
+
+![在 DSH 中安装插件](docs/assets/install-via-dsh.gif)
+
+#### 方式 B：命令行安装
+```sh
+dsh plugin --profile web add dsh-opencode-go
+```
+*命令行安装后请重启 `dsh web`。Headless 用户请使用 `--profile headless`。*
+
+### 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 凭据服务保存，设置页不会回显已保存的密钥。
+在聊天输入区旁，常驻有直观的“用量胶囊”。点击即可展开完整的用量卡片：
 
-## 安装与快速开始
+- **三窗口精准监控**：
+  - 🟢 **5 小时滚动配额**：短周期高频使用的健康度。
+  - 🟡 **每周配额**：本周累计使用进度。
+  - 🔴 **每月配额**：月度套餐消耗百分比。
+  每个窗口均显示精确的重置倒计时；进度条会随着接近上限变黄，耗尽时变红。
+- **节能与防抖机制**：默认每分钟静默刷新；当页面切入后台或浏览器最小化时**自动暂停轮询**，切换回前台时即时刷新。
+- **账号全名与快速切换**：多账号时直接显示当前账号全名（名字过长以省略号截断），展开面板点击“切换”即可直接提拔目标账号为主账号。
+- **显示模式**（在 **高级设置 → 额度显示** 中配置）：
+  - **自动（默认）**：仅在使用 DSH OpenCode Go 模型时显示。
+  - **常驻**：切换到其他厂商模型时，仍然保持胶囊显示。
+  - **关闭**：隐藏胶囊并停止后台用量轮询。
 
-适用于 DSH `0.1.5-rc.1` 及以上版本。已验证的宿主版本见[兼容矩阵](docs/development.md#installed-package-matrix)。
+### 3. 官方历史用量看板（Analytics）
 
-### 在 DSH 中安装
+从对话输入框的用量胶囊展开面板，或侧栏的看板按钮打开：
 
-1. 打开 **插件 → 添加插件**。
-2. 输入 `dsh-opencode-go`，点击 **安装**。
-3. 安装完成后点击 **立即启用**。
+![新版官方历史用量看板，示例数据](docs/assets/usage-history-desktop.jpg)
 
-![在 DSH 中安装插件](docs/assets/install-via-dsh.gif)
+[窄屏浅色预览](docs/assets/usage-history-mobile.jpg) · [模型排行与明细预览](docs/assets/usage-history-models.jpg)（均为示例数据）
+
+- **官方 CSV 单一来源**：请求、输入 / 输出 / 缓存 Token、官方用量金额、每日图表与模型明细来自同一份官方每日 CSV；provider + model 区分同名模型。支持今日、7 / 30 / 90 天，日期统一使用 UTC。
+- **独立查看账号**：默认当前调用账号，只查看所选 Key 所属工作区，包含其他客户端；切换查看账号不改变对话账号。看板的三个额度窗口跟随所选账号。匿名 Free 覆盖不作保证。
+- **官方用量金额**：直接汇总 `cost_micro_cents`（1 美元 = 1 亿单位），不等同于 Go 额外扣款。官方日汇总可能延迟。
+- **统一界面**：设置页、用量胶囊、侧栏与看板统一采用暖纸色 / 炭灰色和陶土色强调，跟随宿主明暗。优先使用本地 Anthropic Serif / Sans / Mono 字体，中文标题配衬线回退；宽屏弹窗、窄屏全屏，保留 Token 堆叠或请求日柱图、模型排行与明细。
+- **按需查询**：打开、切账号、切区间或手动刷新时查询，Host 短缓存 30 秒，强制刷新绕过缓存，不后台轮询历史。仅官方模型网关支持历史查询；错误明确显示，不回退本地扫描。
+
+Key 留在 Host；常规报告只向浏览器传递聚合数字与 provider / model / day。用户主动下载的官方 CSV 可包含成员字段。完整口径见[用量统计说明](docs/usage-analytics.md)。
 
-也可以在添加插件时输入仓库地址：
+---
+
+## 🛠️ 架构设计与工作原理
+
+源码按领域组织，宿主与浏览器通过 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                 官方每日 CSV、历史聚合与短缓存
+├── 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 预算。
+- **默认输出预算**：任意模型声明的输出上限超过 65,536 且调用方与设置均未显式指定时，默认封顶 **65,536 tokens**；较小模型保留 SDK 默认值。该预算同时报告给 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 预算选项；预算式模型还可添加自定义预算并保存。
+---
 
-`deepseek-v4.1-flash` 每次请求默认使用 **64k（65,536 tokens）** 的输出预算，模型输出上限更小时取较小值，并将该默认值告知 DSH 用于计算压缩时机。该规则只应用于此模型；其他模型沿用 SDK 的默认输出行为。需要更长回答时，可在模型容量覆盖中设置「最大输出」。
+## ❓ 常见问题 (FAQ)
 
-流式回复、思考、工具调用和图片输入取决于模型能力。界面中的输入模态来自在线模型配置；本插件目前仅转换并转发图像附件。
+<details>
+<summary><strong>Q: 为什么聊天输入区没有出现用量胶囊？</strong></summary>
 
-### 分组高级设置
+1. 检查当前会话选中的模型是否为 **DSH OpenCode Go** 分组下的模型。默认“自动”模式仅在选择本插件模型时展示；若希望在使用其他模型时也看到配额，可在 **高级设置 → 额度显示** 中切为“常驻”。
+2. 检查是否已在设置中填入有效 API Key 且插件已处于启用状态。
+</details>
 
-高级设置按 **用量与协议**、**连接**、**缓存与超时**、**图片处理** 分组。悬停问号查看说明，可通过 **全部恢复默认** 清除该卡片的自定义覆盖，再保存修改；当前账号选择保持不变。
+<details>
+<summary><strong>Q: 为什么长会话中偶尔会报 400 错误？</strong></summary>
 
-![高级设置：分组配置、提示入口和统一恢复默认](docs/assets/advanced-settings.png)
+通常是因为单次上下文加输出预算超过了模型允许的 Context Window。建议：
+1. 在会话中执行 `/compact` 指令压缩历史消息。
+2. 或在 **可用模型** 设置中，适度调低该模型的“最大输出”上限。
+明确的上下文超限错误会被插件捕获并交由 DSH 原生恢复机制处理。
+</details>
+
+<details>
+<summary><strong>Q: 升级插件后，旧会话找不到模型怎么办？</strong></summary>
+
+从 `0.1.16` 及更早版本升级时，底层 Provider ID 进行了规范化统一。只需在旧会话或 Agent 配置的模型下拉框中，重新选择一次 **DSH OpenCode Go** 下的模型即可。
+</details>
 
-支持 HTTP、HTTPS 和 SOCKS5 代理，保存后用于后续对话、模型目录更新与用量查询。代理运行在 DSH 所在的机器上；远程部署中的 `127.0.0.1` 指服务器自身。
+<details>
+<summary><strong>Q: 插件在执行过程中会自动将我的数据上传到第三方吗？</strong></summary>
 
-DeepSeek V4.1 Flash 的 Responses 协议选项为实验性，仅影响新请求，不承诺更低延迟。完整配置与使用说明见[高级使用指南](docs/advanced.md)。
+正常对话会把请求内容发送到你配置的模型网关（默认为 OpenCode Go 官方网关），额度查询也会访问该网关。插件从 Go 与平台网关各自的 `/models` 下载公开的模型能力与价格；默认地址分别为 `https://opencode.ai/inference/go/v1` 与 `https://opencode.ai/inference/v1`。
 
-截图用于展示界面，具体模型、额度和时间以当前账号与在线目录为准。
+历史看板由 Host 使用所选 Key 请求官方 Console 的每日 CSV，仅支持官方模型网关配置，沿用代理设置。浏览器常规报告只收到聚合数字与 provider / model / day，不含 Key、会话正文或成员字段；主动下载的官方 CSV 可包含成员字段。模型发现请求不携带会话正文、账号密钥或逐条统计记录。
+</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#账号操作与保存)。
-
-**长会话持续报 400 怎么办？** 检查错误中的输出预算与上下文窗口，可执行 `/compact` 或调低该模型的「最大输出」后重试。明确的上下文超限会交给 DSH 的恢复机制；原因不明的 400 会保留原分类并给出排查建议。失败且未取得 token 用量时，插件不发送全零用量，避免将上下文占用误报为 0%。
+### 卸载插件
+```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
 ```
 
-## 更多文档
+测试按领域覆盖宿主、协议转换、账号、统计、传输、免费通道退避、前端。修改源码后先运行 `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,11 +1,15 @@
 # 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.
 
-The host bundle includes the required portions of `@earendil-works/pi-ai@1.2.0`, `@google/genai@2.21.0` and their bundled dependencies; SDK declarations include pi-ai, pi-telemetry and TypeBox types. Their original licenses are reproduced in `lib/vendor-licenses.txt`, including the Google SDK's Apache-2.0 license and data-uri-to-buffer's MIT license from its published README. The pi packages' license comes from the [upstream v1.2.0 license](https://github.com/earendil-works/pi/blob/v1.2.0/LICENSE), which their npm distributions omit. OpenAI and Anthropic transport SDKs remain separate runtime dependencies.
+The host bundle includes the required portions of `@earendil-works/pi-ai@1.5.0`, `@google/genai@2.21.0` and their bundled dependencies; SDK declarations include pi-ai, pi-telemetry and pi-schema types. Their original licenses are reproduced in `lib/vendor-licenses.txt`, including the Google SDK's Apache-2.0 license and data-uri-to-buffer's MIT license from its published README. The pi packages' license comes from the [upstream v1.5.0 license](https://github.com/earendil-works/pi/blob/v1.5.0/LICENSE), which their npm distributions omit, and is retained in `scripts/licenses/pi-1.5.0-LICENSE`. OpenAI and Anthropic transport SDKs remain separate runtime dependencies.
+
+pi-ai 1.5.0 replaces its TypeBox dependency with `@earendil-works/pi-schema@1.5.0`. pi-schema includes format checks and value conversion rules adapted from TypeBox 1.3.27, copyright (c) 2017-2026 Haydn Paterson, under MIT. Its bundled `LICENSES/typebox-LICENSE` is also reproduced in `lib/vendor-licenses.txt`. pi-ai pins both pi-schema and pi-telemetry to 1.5.0, so this package no longer needs a dependency override.
 
 The bundled Google SDK's HTTP fetch call is modified at build time to use the plugin's request-scoped fetch binding. Its message serialization and stream parser remain upstream implementations.
 
 The GitHub icon in the settings footer comes from Simple Icons, distributed under CC0 1.0 Universal.
+
+Free HTTP transport uses the official `bun@1.4.4` optional dependency and its platform packages. Bun is maintained by Oven and contributors and distributed under its upstream license and third-party notices; the runtime remains a separate npm dependency rather than part of this package's JavaScript bundle. See [Bun's license](https://github.com/oven-sh/bun/blob/bun-v1.4.4/LICENSE.md). The HTTP worker and Node bridge in this project are original code.