dsh-opencode-go 0.2.0 → 0.2.1

package/README.en.md

@@ -15,6 +15,8 @@
 
 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.
@@ -25,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:
@@ -39,17 +39,19 @@ Under **Settings → OpenCode Go → Advanced settings → Usage display**, choo
 
 ## 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.
+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)
 
-- 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.
+[Narrow-screen light preview](docs/assets/usage-history-mobile.jpg) · [Model rankings and detail](docs/assets/usage-history-models.jpg), both using sample data.
 
-**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.
+- **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.
 
-See [usage analytics notes](docs/usage-analytics.en.md) for the exact accounting rules and limits.
+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
 
@@ -114,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.
 
@@ -158,15 +160,15 @@ dsh plugin --profile web remove dsh-opencode-go
 
 ## Architecture and verification
 
-The source contains 17 implementation modules:
+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, local analytics and transport | `accounts.ts`, `analytics.ts`, `transport.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` |
-| Settings, account/model controls, usage, themes and copy | `client/Section.tsx`, `client/UsagePill.tsx`, `client/AnalyticsDialog.tsx`, `client/presentation.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`.
 
@@ -180,12 +182,12 @@ 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.
+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: accounting, pricing, scan limits, and privacy](docs/usage-analytics.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

@@ -19,10 +19,12 @@ DSH 原生支持接入 OpenCode Go，但原生模式无法满足复杂的生产
 
 ## ✨ 核心特性
 
+- 🆓 **双路由动态模型目录**：Go 与平台免费模型分别从各自网关的 `/models` 发现，保留同名模型；Free 无 Key 时可使用公共访问，两套模型开关与容量设置独立。
+- 🛑 **免费通道限流保护**：遵循上游 `Retry-After`，冷却期间暂停新请求；共享免费额度或 IP 限制不会触发 Go 换号。
 - 🛡️ **多账号无感容灾**：支持最多 20 个账号集中管理与拖拽排序。当主账号额度耗尽或 Key 失效时，**在输出前自动尝试备用账号**，成功后自动扶正，告别“聊到一半额度没了”的打断感。
 - ⚡ **会话级 Prompt 缓存绑定**：严格遵循网关协议注入专有 `x-opencode-session` 路由头，稳定复用网关上下文缓存，显著降低响应首字延迟。
 - 📊 **会话内额度实时透视**：在聊天输入框旁常驻“用量胶囊”，直观展示 5 小时滚动、每周、每月的额度百分比及重置时间倒计时；支持休眠节能与静默刷新。
-- 💰 **本地用量看板**：在本地扫描会话历史，按模型与峰谷时段统计 Token 消耗与估算开销，不上传统计所用的会话内容；模型和价格元数据从 models.dev 联网刷新。
+- 💰 **官方历史用量看板**：按所选 Key 的工作区汇总官方每日 CSV，查看请求、Token、官方用量金额与模型明细，包含其他客户端的调用。
 - 🎛️ **模型与热配置**：无需重启 DSH！随时在线调整模型上下文窗口、最大输出上限、思考预算（Thinking Budget），并支持 HTTP/HTTPS/SOCKS5 代理。
 
 ---
@@ -73,8 +75,6 @@ dsh plugin --profile web add dsh-opencode-go
 
 在聊天输入区旁，常驻有直观的“用量胶囊”。点击即可展开完整的用量卡片：
 
-![订阅用量面板：当前账号、三个额度窗口及重置时间](docs/assets/usage-panel.png)
-
 - **三窗口精准监控**：
   - 🟢 **5 小时滚动配额**：短周期高频使用的健康度。
   - 🟡 **每周配额**：本周累计使用进度。
@@ -87,19 +87,27 @@ dsh plugin --profile web add dsh-opencode-go
   - **常驻**：切换到其他厂商模型时，仍然保持胶囊显示。
   - **关闭**：隐藏胶囊并停止后台用量轮询。
 
-### 3. 用量与开销看板（Analytics）
+### 3. 官方历史用量看板（Analytics）
+
+从对话输入框的用量胶囊展开面板，或侧栏的看板按钮打开：
+
+![新版官方历史用量看板，示例数据](docs/assets/usage-history-desktop.jpg)
+
+[窄屏浅色预览](docs/assets/usage-history-mobile.jpg) · [模型排行与明细预览](docs/assets/usage-history-models.jpg)（均为示例数据）
 
-点击用量面板底部的 **用量统计**，或进入 **设置 → OpenCode Go → 用量统计** 即可唤出看板：
+- **官方 CSV 单一来源**：请求、输入 / 输出 / 缓存 Token、官方用量金额、每日图表与模型明细来自同一份官方每日 CSV；provider + model 区分同名模型。支持今日、7 / 30 / 90 天，日期统一使用 UTC。
+- **独立查看账号**：默认当前调用账号，只查看所选 Key 所属工作区，包含其他客户端；切换查看账号不改变对话账号。看板的三个额度窗口跟随所选账号。匿名 Free 覆盖不作保证。
+- **官方用量金额**：直接汇总 `cost_micro_cents`（1 美元 = 1 亿单位），不等同于 Go 额外扣款。官方日汇总可能延迟。
+- **统一界面**：设置页、用量胶囊、侧栏与看板统一采用暖纸色 / 炭灰色和陶土色强调，跟随宿主明暗。优先使用本地 Anthropic Serif / Sans / Mono 字体，中文标题配衬线回退；宽屏弹窗、窄屏全屏，保留 Token 堆叠或请求日柱图、模型排行与明细。
+- **按需查询**：打开、切账号、切区间或手动刷新时查询，Host 短缓存 30 秒，强制刷新绕过缓存，不后台轮询历史。仅官方模型网关支持历史查询；错误明确显示，不回退本地扫描。
 
-- **本地扫描与缓存**：直接调用 DSH 宿主 `sessionQuery` 扫描本地历史会话，统计本插件产生的 Token 消耗，不会为统计上传会话内容。模型和价格元数据会从 models.dev 联网刷新。会话折叠结果仅在内存中最多复用 5 秒，重启后重新扫描，不写入磁盘缓存。
-- **峰谷电价式开销估算**：使用从 models.dev 获取的模型价格；自动识别 DeepSeek V4.1 Flash / V4 Pro 等模型的官方峰时时段（UTC 周一至周五 01:00–04:00、06:00–10:00）并按双倍费率估算金额。
-- **四款专属主题**：支持在 **寂静黑 / 石墨（默认）/ 海盐青 / 暖砂** 之间切换，自动适配系统的亮色/暗色模式。
+Key 留在 Host；常规报告只向浏览器传递聚合数字与 provider / model / day。用户主动下载的官方 CSV 可包含成员字段。完整口径见[用量统计说明](docs/usage-analytics.md)。
 
 ---
 
 ## 🛠️ 架构设计与工作原理
 
-源码按领域收敛为 17 个实现模块，宿主与浏览器通过 DSH Typert RPC 通讯：
+源码按领域组织，宿主与浏览器通过 DSH Typert RPC 通讯：
 
 ```text
 src/
@@ -110,14 +118,14 @@ src/
 ├── conversion.ts                上下文、单次请求图片预算、回放与流转换
 ├── google.ts + sdk-types.ts      Google SDK 接入与公开类型
 ├── accounts.ts                  串行账号命令、凭据写入与官方配额
-├── analytics.ts                 本地统计、内存会话缓存与计价
+├── analytics.ts                 官方每日 CSV、历史聚合与短缓存
 ├── transport.ts                 HTTP/HTTPS/SOCKS5、超时与脱敏错误
 └── client/
     ├── index.ts + controller.ts  configForms 接入、类型化草稿与账号操作
-    ├── Section.tsx              设置页、账号卡片、模型编辑器与主题选择
+    ├── Section.tsx              宿主设置页、账号卡片与模型编辑器
     ├── UsagePill.tsx            会话额度胶囊
-    ├── AnalyticsDialog.tsx      用量与费用看板
-    └── presentation.ts          多语言、主题与显示格式
+    ├── AnalyticsDialog.tsx      官方历史用量看板
+    └── presentation.ts          多语言、明暗配色与显示格式
 ```
 
 账号操作在内存串行队列中直接更新凭据与设置。模型容量草稿始终保留为对象；图片按单次请求限制数量、编码字节及最多四路并行准备。宿主仅使用 DSH `0.2.1-rc.5` 起提供的设置与图片卸载接口。包的 `.` 与 `./client` 导出路径保持不变。
@@ -137,7 +145,7 @@ OpenCode Go 网关具有会话粘性路由与上下文缓存共享能力。插
 - **显示开关**：自由隐藏不常用的模型，净化聊天选择器。
 - **容量与上下文覆盖**：可手动指定上下文窗口（Context Window）与单次最大输出 Token。
 - **思考预算（Thinking Budget）**：对支持深度思考的模型，可自定义思考强度等级或 Token 预算。
-- *特别规则*：`deepseek-v4.1-flash` 默认自动配置 **64k (65,536 tokens)** 输出预算，并将该上限通知 DSH 宿主，用于计算上下文压缩时机。
+- **默认输出预算**：任意模型声明的输出上限超过 65,536 且调用方与设置均未显式指定时，默认封顶 **65,536 tokens**；较小模型保留 SDK 默认值。该预算同时报告给 DSH，用于上下文压缩。
 
 ### 分组高级设置
 支持在 **设置 → OpenCode Go → 高级设置** 中按需微调：
@@ -177,9 +185,9 @@ OpenCode Go 网关具有会话粘性路由与上下文缓存共享能力。插
 <details>
 <summary><strong>Q: 插件在执行过程中会自动将我的数据上传到第三方吗？</strong></summary>
 
-正常对话会把请求内容发送到你配置的模型网关（默认为 OpenCode Go 官方网关），额度查询也会访问该网关。插件还会从 [models.dev](https://models.dev/api.json) 下载公开的模型能力与价格元数据。
+正常对话会把请求内容发送到你配置的模型网关（默认为 OpenCode Go 官方网关），额度查询也会访问该网关。插件从 Go 与平台网关各自的 `/models` 下载公开的模型能力与价格；默认地址分别为 `https://opencode.ai/inference/go/v1` 与 `https://opencode.ai/inference/v1`。
 
-用量统计在本地读取会话记录，不会把会话正文、账号密钥或逐条统计记录发送给 models.dev，也没有额外的遥测或分析服务。因此，本地统计不等于插件完全不联网。
+历史看板由 Host 使用所选 Key 请求官方 Console 的每日 CSV，仅支持官方模型网关配置，沿用代理设置。浏览器常规报告只收到聚合数字与 provider / model / day，不含 Key、会话正文或成员字段；主动下载的官方 CSV 可包含成员字段。模型发现请求不携带会话正文、账号密钥或逐条统计记录。
 </details>
 
 ---
@@ -211,14 +219,14 @@ npm run check:dist
 npm run verify
 ```
 
-测试按 12 个领域文件覆盖宿主、协议转换、账号、统计、传输和前端。修改源码后先运行 `npm run compile` 更新 `lib/`；`verify` 包含类型检查、产物一致性、全量测试与包加载冒烟。独立安装和 Headless 验证见[开发说明](docs/development.md)。
+测试按领域覆盖宿主、协议转换、账号、统计、传输、免费通道退避、前端。修改源码后先运行 `npm run compile` 更新 `lib/`；`verify` 包含类型检查、产物一致性、全量测试与包加载冒烟。独立安装和 Headless 验证见[开发说明](docs/development.md)。
 
 ---
 
 ## 📚 更多文档与链接
 
 - 📖 [高级使用指南（Headless 部署、代理策略与错误排查）](docs/advanced.md)
-- 📊 [用量看板统计说明（计价口径与扫描策略）](docs/usage-analytics.md)
+- 📊 [用量看板统计说明（官方来源、口径与隐私）](docs/usage-analytics.md)
 - 🛠️ [开发与贡献指南](docs/development.md)
 - 🧪 [验收范围与验证记录](docs/verification.md)
 - 🐛 [提交 Issue 与建议](https://github.com/Duskriver/dsh-opencode-go/issues)

package/THIRD_PARTY_NOTICES.md

@@ -4,8 +4,12 @@ The initial adapter, settings UI, and `src/conversion.ts` were derived from Deep
 
 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.

package/docs/advanced.en.md

@@ -42,24 +42,25 @@ socks5://127.0.0.1:1080
 
 HTTP, HTTPS, SOCKS5, and URLs containing a username and password are supported. Subsequent conversations, catalog updates, and usage queries use the saved proxy. Connections originate from the machine running DSH; on a remote deployment, `127.0.0.1` refers to that server.
 
-### Experimental Responses protocol
+### Dual routes and manual configuration
 
-Open **Settings → OpenCode Go → Advanced settings → DeepSeek V4.1 Flash protocol** to select Responses (experimental). Automatic remains the default and follows the gateway's declared protocol. This setting applies only to `deepseek-v4.1-flash` and to new requests. Existing conversation history can continue with either selection; a failed request does not automatically retry through another protocol.
+`dsh-opencode-go` (DSH OpenCode Go) discovers all chat models from `baseURL/models` and activates when at least one usable API key is configured. `dsh-opencode-free` (DSH OpenCode Free) discovers only chat models with a valid declared tariff whose text input, output, cache and every context tier are all zero, from `freeBaseURL/models`. Missing or invalid prices never qualify as free. Free activates whenever the plugin is enabled.
 
-To configure the experiment manually:
+Free shares the account roster, prefers usable saved keys and follows automatic account retry settings. Without a usable key it sends `Bearer public`. Both routes preserve original model IDs, including overlapping names. Settings provides separate model tabs; Go keeps existing ID keys, while Free uses `dsh-opencode-free/<model ID>` in visibility and capacity settings.
 
-```yaml
-- id: opencode-go
-  config:
-    protocolOverrides:
-      deepseek-v4.1-flash: openai-responses
-```
+Free inference sends direct API requests through the bundled standalone Bun 1.4.4 HTTP worker, with no local OpenCode dependency. The existing Node SDK still handles discovery, message/tool conversion and response parsing; Go retains its transport. Free uses the observed `opencode/latest/2.2.5/cli` user agent and the existing host-session normalization, without placeholder tools or captured account/project/session values. Compatibility does not guarantee upstream free access.
 
-Select Automatic to revert. A null value for this model also clears an inherited override. Gateway routing and performance may change; Responses does not guarantee a particular provider or faster responses.
+Free requests handle rate limits automatically. `FreeUsageLimitError` becomes `FREE_QUOTA`, a generic 429 becomes `FREE_RATE_LIMIT`, an explicit OpenCode client restriction becomes `FREE_CLIENT_RESTRICTED`, and an otherwise unclassified 403 becomes `FREE_ACCESS_DENIED`. Go error codes and account switching retain their behavior. Explicit Go account quota/authentication failures on Free still follow existing account fallback settings; shared Free limits neither rotate accounts nor fall back to paid Go.
 
-### Manual configuration
+Shared Free restrictions and network, timeout or server errors honor `Retry-After` delta-seconds or HTTP-date, including delays of many hours. Without a valid header, exponential backoff starts at 60 seconds and caps at 15 minutes. Cooldowns are isolated by Free gateway and proxy configuration. New calls during cooldown return `FREE_COOLDOWN` without inference traffic; no automatic retry is scheduled. Users can retry after expiry; success resets the fallback counter. State is held in the plugin instance and starts fresh after restart.
 
-Add an `opencode-go` configuration block to a patch file. It can be combined with the default-model configuration above:
+The platform binary installs through npm optional dependencies. Install scripts may be disabled, but optional dependencies must be included. A missing runtime reports `MISSING_BUN_RUNTIME` on Free; reinstall the plugin with optional dependencies enabled. Go remains available. Supported operating systems and CPUs follow Bun's official platform packages.
+
+Each Free HTTP request owns a worker, with at most four concurrent workers and cancellable queueing. Requests use stdin; response headers and raw SSE bytes use stdout. Keys never enter argv or temporary files. Consumer cancellation, timeouts and plugin unload stop requests and reap workers. Encoded IPC requests are limited to 256 MiB. Bun handles HTTP/HTTPS proxies; SOCKS5 uses a per-request loopback byte tunnel with random authentication credentials while Bun still performs target TLS. A proxy failure never falls back to a direct connection.
+
+Protocols, capabilities, reasoning controls and tariffs come directly from each gateway’s `/models` entries. Official gateways prefer declared protocol URLs; custom gateways keep their configured prefix. Separate `go.models.json` and `free.models.json` files under `~/.dsh/cache/dsh-opencode-go/` support ETag revalidation and offline retention. Cache documents identify their source URL and cannot be reused for another gateway.
+
+The following patch configures shared accounts and per-model settings:
 
 ```yaml
 - id: opencode-go
@@ -73,11 +74,14 @@ Add an `opencode-go` configuration block to a patch file. It can be combined wit
         name: Backup
         apiKeyEnv: OPENCODE_GO_BACKUP_KEY
     autoSwitch: true
+    freeBaseURL: https://opencode.ai/inference/v1
     proxyURL: http://127.0.0.1:7890
     refreshMinutes: 60
     modelVisibility:
       deepseek-v4-pro: false
     modelLimits:
+      dsh-opencode-free/beam-free:
+        maxTokens: 8192
       deepseek-v4.1-flash:
         maxTokens: 8192
       qwen3.7-plus:
@@ -90,11 +94,11 @@ Keep the options you need and supply the corresponding keys through DSH credenti
 | Option | Purpose |
 | --- | --- |
 | `baseURL` | OpenCode Go gateway address; defaults to `https://opencode.ai/inference/go/v1`, with official inference endpoints selected by model protocol |
+| `freeBaseURL` | Platform free gateway, default `https://opencode.ai/inference/v1`; editable with URL validation in advanced settings |
 | `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 |
 | `modelVisibility` | Control model picker visibility by model ID |
-| `protocolOverrides` | Experimental `deepseek-v4.1-flash: openai-responses`; unset or null follows the gateway |
 | `modelLimits` | Per-model `contextWindow` and `maxTokens` overrides, plus additional `thinkingBudgets` options; null uses defaults |
 | `maxImages` | Maximum images in one request's history; unset by default, with oldest images offloaded when exceeded |
 | `streamIdleTimeoutMs` | Maximum wait for the next stream event; defaults to 300000 milliseconds |

package/docs/advanced.md

@@ -42,20 +42,23 @@ socks5://127.0.0.1:1080
 
 支持 HTTP、HTTPS、SOCKS5 和带用户名、密码的代理 URL。保存后，后续对话、模型目录更新和用量查询使用新代理。代理运行在 DSH 所在的机器上；远程部署中的 `127.0.0.1` 指服务器自身。
 
-### 实验性协议与手动配置
+### 双路由与手动配置
 
-在 **高级设置 → DeepSeek V4.1 Flash 协议** 中可选择 **Responses（实验性）** 并保存，便于比较同一模型的不同协议。默认 **自动** 跟随模型目录；改回自动即可恢复。选择只影响新请求，不会切换已准备或正在执行的调用，也不会在协议错误后自动改用另一协议。
+`dsh-opencode-go`（DSH OpenCode Go）从 `baseURL` 的 `/models` 动态发现全部聊天模型，需要至少一个可用 API Key 才激活。`dsh-opencode-free`（DSH OpenCode Free）从 `freeBaseURL` 的 `/models` 筛选已声明合法价格、且文本输入、输出、缓存及所有上下文阶梯均为零的聊天模型；缺失或非法价格不会被视为免费。插件开启即激活 Free 路由。
 
-目前仅支持 `deepseek-v4.1-flash` 的 Responses 覆盖，沿用当前账号、代理、会话标识与用量处理。[issue #45](https://github.com/Duskriver/dsh-opencode-go/issues/45) 报告了更低延迟，但它不是网关的稳定性能承诺，也不能据此确认底层服务商；是否更快请以自己的测试为准。无需覆盖时省略以下配置：
+Free 共用账号列表，优先使用已配置的可用 Key，并遵循多账号自动切换设置；没有可用 Key 时使用 `Bearer public`。两个路由分别保留原始模型 ID，同名模型可同时存在。设置页顶部的两个模型 Tab 分别编辑各自列表；Go 沿用原 ID 设置键，Free 使用 `dsh-opencode-free/<模型 ID>`。
 
-```yaml
-- id: opencode-go
-  config:
-    protocolOverrides:
-      deepseek-v4.1-flash: openai-responses
-```
+Free 推理通过插件附带的独立 Bun 1.4.4 HTTP worker 直接发送 API 请求；不依赖本机 OpenCode。模型发现、消息和工具转换、响应解析仍由现有 Node SDK 负责，Go 沿用原传输。Free 使用实测的 `opencode/latest/2.2.5/cli` UA，保留宿主会话 ID 的原有规范化，不注入占位工具或抓包中的账号、项目和会话值。这些兼容行为不保证上游开放免费服务。
+
+Free 请求自动处理限流：`FreeUsageLimitError` 返回 `FREE_QUOTA`，普通 429 返回 `FREE_RATE_LIMIT`，明确的 OpenCode 客户端限制返回 `FREE_CLIENT_RESTRICTED`，其他未明确分类的 403 返回 `FREE_ACCESS_DENIED`。Go 的错误码和账号切换保持原有规则；Free 中明确的 Go 账号额度或凭据错误仍可按既有设置切换账号，共享 Free 限制不会换号或回退到付费 Go。
 
-将该模型的值设为 `null` 会明确选择自动，即使继承的配置启用了 Responses；设置页的「恢复默认」会移除当前层覆盖，恢复继承值。其他模型或协议组合会被拒绝。
+对共享免费限制及网络、超时、服务端错误，优先遵循 `Retry-After` 秒数或 HTTP 日期（不会把数小时的退避缩短成几分钟）；没有有效头时，从 60 秒开始指数退避，最多 15 分钟。冷却按免费网关与代理配置隔离，冷却期间新调用返回 `FREE_COOLDOWN`，不发送推理请求，也不自动定时重试。到期后可由用户重试；成功请求重置本地退避计数。退避计数只保存在当前插件实例内，重启后清空。
+
+Bun 通过 npm 可选依赖安装对应平台的二进制；禁用安装脚本仍可使用，但不能省略可选依赖。若缺少运行时，Free 会报告 `MISSING_BUN_RUNTIME`，可重新安装插件并启用 optional dependencies；Go 不受影响。当前平台包支持的系统和 CPU 以 Bun 的官方发行包为准。
+
+每个 Free HTTP 请求使用一个 worker，默认最多并发 4 个，其余请求可排队或取消。请求通过标准输入传递，响应头和原始 SSE 字节通过标准输出返回；Key 不进入命令行参数或临时文件。消费者停止、超时、取消或卸载插件都会终止相关请求并回收 worker。IPC 请求上限为编码后 256 MiB。HTTP/HTTPS 代理由 Bun 连接；SOCKS5 使用该请求专属、带随机认证凭据的本机字节隧道，目标 TLS 握手仍由 Bun 完成。代理失败不会回退到直连。
+
+协议、能力、思考控制与价格直接来自各自的 `/models` 条目。官方网关优先使用条目声明的协议地址；自定义网关保留配置的前缀。两个模型源分别缓存到 `~/.dsh/cache/dsh-opencode-go/go.models.json` 与 `free.models.json`，支持 ETag 与离线保留；缓存带有网关来源标记，不会用于其他地址。
 
 在 patch 文件中添加 `opencode-go` 配置块，可与上面的默认模型配置一起使用：
 
@@ -71,11 +74,14 @@ socks5://127.0.0.1:1080
         name: 备用账号
         apiKeyEnv: OPENCODE_GO_BACKUP_KEY
     autoSwitch: true
+    freeBaseURL: https://opencode.ai/inference/v1
     proxyURL: http://127.0.0.1:7890
     refreshMinutes: 60
     modelVisibility:
       deepseek-v4-pro: false
     modelLimits:
+      dsh-opencode-free/beam-free:
+        maxTokens: 8192
       deepseek-v4.1-flash:
         maxTokens: 8192
       qwen3.7-plus:
@@ -88,11 +94,11 @@ socks5://127.0.0.1:1080
 | 配置项 | 用途 |
 | --- | --- |
 | `baseURL` | OpenCode Go 网关地址，默认 `https://opencode.ai/inference/go/v1`；官方网关自动按模型协议选择推理端点 |
+| `freeBaseURL` | 平台免费模型网关，默认 `https://opencode.ai/inference/v1`；高级设置可编辑并校验 URL |
 | `usageDisplay` | 额度显示模式：`auto`、`always` 或 `off` |
 | `proxyURL` | 网络代理；空字符串使用默认网络设置 |
 | `refreshMinutes` | 模型目录缓存时长，默认 60 分钟；设置页可随时手动刷新 |
-| `modelVisibility` | 按模型 ID 控制选择器中的显示状态 |
-| `protocolOverrides` | 实验性协议覆盖；目前仅支持 `deepseek-v4.1-flash: openai-responses`，省略或模型值为 `null` 时自动跟随目录 |
+| `modelVisibility` | Go 用原模型 ID；Free 用 `dsh-opencode-free/<模型 ID>`，分别控制显示 |
 | `modelLimits` | 按模型覆盖 `contextWindow`、`maxTokens`，或用 `thinkingBudgets` 添加思考预算选项；空值使用默认设置 |
 | `maxImages` | 单次请求历史中的图片数量上限，默认不设上限；超过时先卸载最旧图片 |
 | `streamIdleTimeoutMs` | 等待下一个流事件的最长时间，默认 300000 毫秒 |
@@ -116,7 +122,6 @@ socks5://127.0.0.1:1080
 
 图片数量超限会在附件读取前检测。每个请求最多并发准备 4 张图片，并在已知编码大小超过单次请求预算时停止；插件不再维护全局图片队列或共享内存池。
 
-
 首次查询目录失败会报告 `DISCOVERY_FAILED`；已有目录时保留之前确认过的模型。网关明确返回空列表才会清空目录。列表中仅部分行格式错误时，仍可使用有效模型，设置页与日志会提示被忽略的行数。高级表单的普通配置项一次提交并检查版本；凭据由独立服务保存，凭据保存失败时保留其草稿，重试只提交未成功的部分。
 
 请求失败时，错误信息仍包含 HTTP 分类、脱敏后的上游摘要，以及适用的上下文容量提示。插件不再输出内部诊断文件或逐调用追踪。

package/docs/development.md

@@ -19,37 +19,41 @@ The development baseline is DSH `0.2.1-rc.5`, Cordis `4.0.5` and Schemastery `3.
 
 ## Test suite
 
-Vitest discovers exactly 12 domain files:
+Vitest tests are organized by domain. Results for the history-dashboard migration are tracked separately in [verification notes](verification.md); the table below is a scope reference, not a passing-run claim.
 
 | Test file | Coverage |
 | --- | --- |
 | `plugin.spec.ts` | Cordis mounting/unloading, native SettingsForms/profile writes, hot configuration, RPC and public exports |
 | `accounts.spec.ts` | Account CRUD, 20-account cap, serial writes, failed-write cleanup, fallback/promotion, stale calls and five-minute cooldown |
-| `catalog.spec.ts` | Discovery, model limits/visibility, online metadata, ETag/disk cache, endpoint isolation and bounded transport |
+| `free.spec.ts` | Dual route lifecycle, public Bearer fallback, saved keys, account retry and credential deadlines |
+| `free-channel.spec.ts`, `free-transport.spec.ts` | Free failure classification, Retry-After/backoff, cancellation, transport isolation and coexistence with Go |
+| `pricing.spec.ts` | Catalog tariff validation and Free-model eligibility; historical amounts come from official CSV |
+| `catalog.spec.ts` | Discovery, model limits/visibility, dual directories, ETag/disk cache, endpoint isolation and bounded transport |
 | `adapter.spec.ts` | Requests, capacity limits, session/attribution headers, immutable request snapshots, cancellation and timeouts |
 | `protocols.spec.ts` | Reasoning levels, protocol overrides, OpenAI/Anthropic/Google serialization and signed Google parts |
 | `conversion.spec.ts` | Independent tool messages, replay signatures, context conversion, durable image offload, per-request budgets and stream contracts |
 | `usage.spec.ts` | Official quota reads, current-account selection, native gateway access and safe error responses |
-| `analytics.spec.ts` | Session folding, totals, context/peak pricing, Go/Go Plus limits, memory cache freshness, scan limits and cancellation |
+| `analytics.spec.ts` | Official daily CSV parsing/aggregation, UTC ranges, provider/model grouping, account isolation, short cache and cancellation |
 | `transport.spec.ts` | Bounded JSON/gzip, classified/redacted HTTP errors, real CONNECT/SOCKS5 proxies and SDK bridge matching |
 | `settings.client.spec.tsx` | Page configuration, typed Save/Reset/refused writes, locale changes, registration and subscription/cancellation lifecycle |
 | `accounts-models.client.spec.tsx` | AccountsCard forms/status/quota, drag/keyboard ordering, model visibility, metadata failures and refresh races |
-| `usage.client.spec.tsx` | Conversation pill, AnalyticsDialog, pricing presentation, polling/visibility, accessibility and themes |
+| `usage.client.spec.tsx` | Conversation pill, dashboard account/range controls, official amount presentation, quota refresh/visibility and accessibility |
 
 All test imports target current modules directly. `vitest.config.ts` has no aliases or compatibility resolver. Its Google SDK loader is the same version-guarded transport patch used by the production build. The UI tests load the published DSH primitives and the installed locale bundle.
 
-`tests/setup.ts` gives each test a temporary `DSH_HOME`, provides synthetic models.dev metadata, allows loopback HTTP fixtures and explicit `.invalid` destinations through the local proxy fixture, and rejects other network requests. `tests/support/` contains five shared helpers: current host/account services, ConfigForm/React fixtures, metadata data, loopback gateways and proxies. Fixtures clean up contexts, sockets, timers and temporary homes.
+`tests/setup.ts` gives each test a temporary `DSH_HOME`, provides complete synthetic `/models` entries, allows loopback HTTP fixtures and explicit `.invalid` destinations through the local proxy fixture, and rejects other network requests. `tests/support/` provides current host/account services, ConfigForm/React fixtures, metadata data, loopback gateways and proxies. Fixtures clean up contexts, sockets, timers and temporary homes.
 
 ## Modules
 
-The source contains 17 implementation modules, plus CSS and its ambient declaration:
+Implementation modules are grouped by domain, with browser CSS and its ambient declaration:
 
 | Domain | Modules |
 | --- | --- |
 | Host composition and settings | `index.ts`, `config.ts` |
 | Inference and model discovery | `adapter.ts`, `catalog.ts`, `conversion.ts`, `google.ts`, `sdk-types.ts` |
 | Account commands and official quota | `accounts.ts` |
-| Local usage analytics and plan pricing | `analytics.ts` |
+| Official daily CSV history and aggregation | `analytics.ts` |
+| Free backoff, error classification and transport | `free-channel.ts`, `free-policy.ts`, `free-transport.ts` |
 | Browser-safe configuration and RPC contracts | `contracts.ts` |
 | HTTP, proxy transport and redacted errors | `transport.ts` |
 | Browser registration and state | `client/index.ts`, `client/controller.ts` |
@@ -59,10 +63,20 @@ The host uses `settings.configure()` and volatile configuration fields; the brow
 
 Account commands and automatic primary-account promotion share one in-memory serial queue. Credential writes settle before the next command starts. Metadata changes use a single revision-guarded write; no WAL, startup recovery or conflict retry loop is maintained. Only credentials owned by the removed generated account are deleted. Request generations prevent late fallback outcomes from replacing a newer user selection. Credential, quota and rate-limit failures can try the next account only before output or positive usage, and rejected gateway keys cool down for five minutes. Changing a key or explicitly selecting an account clears its rejection state.
 
-Analytics folds session events, prices them using the current catalog (including context tiers and peak/off-peak pricing), and includes Go / Go Plus monthly limits. A bounded in-memory session cache reuses results for at most five seconds; restarting the process clears it. Reports retain coverage, truncation, pricing availability and cancellation. Analytics does not write fold files.
+Analytics requests `https://opencode.ai/console/api/v2/usage/export?range=7d|30d|90d` from the Host with the selected account's key. One daily CSV snapshot supplies totals, UTC daily buckets and provider/model detail. Today filters the 7-day snapshot to the current UTC date; absent dates are filled with zero. Input, output, cache read and both 5-minute/1-hour cache-write fields are summed without repricing. Integer `cost_micro_cents` use `1 USD = 100,000,000` units and are presented as the official usage amount, which does not establish extra Go charges.
+
+History queries occur only on open, account/range changes and manual refresh. Official reports and CSVs have a 30-second Host cache isolated by credential, account, network configuration, range and UTC date; forced refresh bypasses it. Queries retain the configured proxy path, cancellation, timeouts and response-size limits. Only official gateway configurations may send keys to Console. Third-party gateways, permission failures, network failures and invalid data produce explicit errors, without a local-history fallback.
+
+The browser receives only aggregate numbers and provider/model/day groups. The user's explicit CSV download may contain official member fields. The independent viewing-account selector defaults to the inference account and scopes all three dashboard quota windows to the selected workspace, including other clients; anonymous Free coverage is not guaranteed. Settings, the dashboard, pill and expanded sidebar share warm paper/charcoal surfaces and terracotta accents, following the Host's light/dark mode. Settings map Host control tokens only within the plugin section. Typography prefers locally installed Anthropic Serif Web, Sans Web and Mono Web families, with system fallbacks and CJK serif headings; no font binaries or external font requests are added.
+
+Backend history tests use synthetic CSVs, synthetic keys and loopback services; real user keys are not used in automated tests. The separately recorded Console check establishes source availability for the checked account; automated migration results are recorded separately in the verification notes.
 
 Image count limits are checked before reads. Each request prepares up to four images concurrently and checks its own encoded-payload budget. The host's `requiredImageOffload` / `projectOffloadedImages` protocol owns durable offload marks. There is no plugin-wide preparation queue or payload pool. HTTP failure classification, credential redaction, context-capacity hints, stream deadlines and cancellation remain active; internal call tracing and diagnostic file capture are removed.
 
 ## Distribution
 
-The `.` and `./client` exports continue to point to the built host entry and browser factory. Rebuild `lib/` with source changes, then run `npm run check:dist`. Builds do not execute during dependency installation. The Google transport bridge remains pinned to the existing SDK versions; the telemetry dependency is fixed at `1.2.0` to retain the original private SDK behavior and shipped license attribution.
+The `.` and `./client` exports continue to point to the built host entry and browser factory. Rebuild `lib/` with source changes, then run `npm run check:dist`. Builds do not execute during dependency installation. The private `opencode-go-pi-ai` alias uses `@earendil-works/pi-ai@1.5.0`, which pins `@earendil-works/pi-telemetry@1.5.0` and `@earendil-works/pi-schema@1.5.0` exactly; `package.json` no longer needs `overrides`.
+
+The Google transport bridge is version-guarded for pi-ai 1.5.0 and `@google/genai@2.21.0`. `src/google.ts` delegates simple streaming to the upstream adapter through the request-scoped fetch binding; pi-ai now selects discrete thinking levels for Gemini 4 natively.
+
+SDK declarations bundle pi-schema in place of TypeBox. `scripts/licenses/pi-1.5.0-LICENSE` supplies the pi packages' upstream MIT license omitted from their npm distributions. pi-schema's format checks and value conversion rules include code adapted from TypeBox 1.3.27 (MIT); the build appends the package's `LICENSES/typebox-LICENSE` to its pi-schema notice in `lib/vendor-licenses.txt`.