dsh-opencode-go 0.1.22 → 0.1.24

package/LICENSE

@@ -1,6 +1,7 @@
 MIT License
 
 Copyright (c) 2026 DeepSeek
+Copyright (c) 2026 dsh-opencode-go contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.en.md

@@ -2,204 +2,128 @@
 
 [简体中文](README.md)
 
-Use OpenCode Go subscription models in [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness), with streaming, reasoning, tool calls, and image input. The plugin synchronizes model listings and limits, and provides multiple accounts, subscription usage, and proxy settings.
+**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.
 
-Requires DSH `0.1.5-rc.1` or later.
+DSH already supports OpenCode Go natively. This plugin focuses on usage inside conversations, managing multiple accounts, and dedicated model and settings controls.
 
-Installed compatibility is checked on ten host versions from `0.1.5-rc.1` through `0.2.1-alpha.1`; see the [compatibility matrix](docs/development.md#installed-package-matrix). Later hosts need verification. Developer messages, dynamic tool additions/removals, and deferred tool loading are explicitly rejected.
+- **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.
 
-## Install
+Supports Chinese and English, following DSH's interface language. The screenshots below show the Chinese interface.
 
-### From DSH
+## View subscription usage
 
-1. Open **Plugins → Add plugin**.
-2. Enter `dsh-opencode-go` and click **Install**.
-3. Click **Enable now** after installation.
-
-![Install the plugin in DSH](docs/assets/install-via-dsh.gif)
-
-You can also enter the Git repository URL when adding the plugin:
-
-```text
-https://github.com/Duskriver/dsh-opencode-go
-```
-
-### From the command line
-
-```sh
-dsh plugin --profile web add dsh-opencode-go
-```
-
-Start or restart `dsh web` after installation. Web and Headless use separate profiles; install and update each profile individually.
-
-## Get started
-
-1. Open **Settings → OpenCode Go**, enter your API key and save, or add an account in **Accounts**.
-2. Select a model under **DSH OpenCode Go** in the conversation model picker.
-3. Start chatting. Choose a reasoning level when offered, or attach images to a model that supports them.
-
-Refresh the model list in Settings to synchronize the catalog. The switch beside each model controls its visibility in the picker and takes effect immediately. Context windows and output limits use catalog values by default; edit and save individual model limits as needed.
-
-**Default** leaves reasoning to the service; **Off** explicitly disables it. Models with a switch show **On / Off**, models with adjustable effort show their supported levels, and budget-based models show token values.
+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.
 
-Budget-based models offer common presets such as 1,024 / 2,048 / 8,192 / 16,384 tokens. Select a model in Settings, expand **Thinking budgets**, enter a value, click **Add**, then save to make that budget available in conversations. Allowed ranges vary by model; the SDK may reduce the actual budget to leave room for the answer.
+![Subscription usage: current account, three quota windows, and reset times](docs/assets/usage-panel.png)
 
-The plugin follows DSH's interface language and supports English and Chinese.
+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.
 
-### View subscription usage
+Under **Settings → OpenCode Go → Advanced settings → Usage display**, choose:
 
-Click the usage pill beside the conversation input to see the current account's five-hour, weekly, and monthly usage and reset times. Usage refreshes every minute and can also be refreshed manually.
+| Mode | Behavior |
+| --- | --- |
+| Auto (default) | Show while a **DSH OpenCode Go** model is selected |
+| Always | Also show configured OpenCode Go account usage while using other models |
+| Off | Hide the conversation pill and stop its polling |
 
-Under **Advanced settings → Usage display**, choose:
+## Manage multiple accounts
 
-- **Auto**: show usage while using this plugin's models; the default.
-- **Always**: also show usage while using other models.
-- **Off**: hide usage and stop polling.
+Open **Settings → OpenCode Go → Accounts** to manage accounts:
 
-![Subscription usage](image.png)
+![Account management: ordering, usage details, key actions, and automatic fallback](docs/assets/accounts.png)
 
-### Manage multiple accounts
+- Add, rename, replace keys, or remove accounts; up to 20 accounts are supported.
+- See key status, five-hour usage, and a reset countdown in each row; expand it for full usage and account actions.
+- 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.
 
-Use **Accounts** to add accounts, rename them, or replace keys. Expand an account row for detailed usage. Drag its handle to reorder accounts; the first account becomes the current one.
+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.
 
-Enable **Auto switch** to try other accounts in list order when the current account runs out of quota or its key is unavailable, before output begins. To choose the account for subsequent requests directly, click **Switch** in the usage pill.
+Keys are saved through DSH's credential service. Settings never displays an already saved key.
 
-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.
+## Install and get started
 
-## Advanced usage
+Requires DSH `0.1.5-rc.1` or later. See the [compatibility matrix](docs/development.md#installed-package-matrix) for verified host versions.
 
-### Headless mode
+### Install from DSH
 
-Install the plugin:
+1. Open **Plugins → Add plugin**.
+2. Enter `dsh-opencode-go` and click **Install**.
+3. Click **Enable now** after installation.
 
-```sh
-dsh plugin --profile headless add dsh-opencode-go
-```
+![Install the plugin in DSH](docs/assets/install-via-dsh.gif)
 
-Save this as `headless.patch.yml`:
+You can also enter the repository URL:
 
-```yaml
-- id: agent-default-model
-  config:
-    provider: dsh-opencode-go
-    model: deepseek-v4.1-flash
+```text
+https://github.com/Duskriver/dsh-opencode-go
 ```
 
-Enter your key in Bash or Zsh, then run a task:
+Command-line installation:
 
 ```sh
-read -s OPENCODE_API_KEY
-export OPENCODE_API_KEY
-dsh --profile headless --patch ./headless.patch.yml "Hello"
+dsh plugin --profile web add dsh-opencode-go
 ```
 
-Replace `model` with an available model ID from Settings. See [examples/headless.patch.yml](examples/headless.patch.yml).
+Start or restart `dsh web` after command-line installation. Web and Headless use separate profiles; install and update each individually.
 
-### Network proxy
+### Get started
 
-Open **Settings → OpenCode Go → Advanced settings → Proxy address**, enter a URL, and save. Examples:
+1. Open **Settings → OpenCode Go**, enter your OpenCode Go subscription API key and save, or add an account in **Accounts**.
+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.
 
-```text
-http://127.0.0.1:7890
-socks5://127.0.0.1:1080
-```
+The plugin registers its own **DSH OpenCode Go** model provider. Selecting a native DSH provider does not automatically use this plugin's account switching. **Always** mode can still show usage for accounts configured in this plugin.
 
-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.
+## Models and settings
 
-### Experimental Responses protocol
+### Select models and adjust parameters
 
-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.
+Search **Available models** by name or ID, or filter by **New in 7 days**, **Customized**, or **Deprecated**. Click **Refresh** to check the latest catalog.
 
-To configure the experiment manually:
+![Model settings: search, filters, visibility switches, and parameter editing](docs/assets/model-settings.png)
 
-```yaml
-- id: opencode-go
-  config:
-    protocolOverrides:
-      deepseek-v4.1-flash: openai-responses
-```
+- Each model's switch controls its visibility in the conversation picker and takes effect immediately.
+- 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.
 
-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.
-
-### Manual configuration
-
-Add an `opencode-go` configuration block to a patch file. It can be combined with the default-model configuration above:
-
-```yaml
-- id: opencode-go
-  config:
-    apiKeyEnv: OPENCODE_API_KEY
-    accounts:
-      - id: primary
-        name: Primary
-        apiKeyEnv: OPENCODE_API_KEY
-      - id: backup
-        name: Backup
-        apiKeyEnv: OPENCODE_GO_BACKUP_KEY
-    autoSwitch: true
-    proxyURL: http://127.0.0.1:7890
-    refreshMinutes: 60
-    modelVisibility:
-      deepseek-v4-pro: false
-    modelLimits:
-      deepseek-v4.1-flash:
-        maxTokens: 8192
-      qwen3.7-plus:
-        thinkingBudgets: [4096, 6000]
-    maxImages: 30
-```
+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.
 
-Keep the options you need and supply the corresponding keys through DSH credentials or environment variables. `apiKeyEnv` selects the current account; the order of `accounts` determines automatic fallback order.
+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.
 
-| Option | Purpose |
-| --- | --- |
-| `baseURL` | OpenCode Go gateway URL; defaults to `https://opencode.ai/zen/go/v1` |
-| `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 |
-| `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 |
+### Grouped advanced settings
 
-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.
+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.
 
-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.
+![Advanced settings: grouped controls, hints, and a shared reset action](docs/assets/advanced-settings.png)
 
-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.
+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.
 
-### Export error diagnostics
+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.
 
-To investigate a failed request, set a diagnostics directory before starting DSH:
+Screenshots illustrate the interface. Actual models, quotas, and timestamps depend on your account and the current online catalog.
 
-```sh
-export DSH_OPENCODE_GO_DEBUG_DIR=/tmp/dsh-opencode-go-debug
-dsh web
-```
+## Updates and common questions
 
-Windows PowerShell:
+Update to the latest npm release:
 
-```powershell
-$env:DSH_OPENCODE_GO_DEBUG_DIR = "$env:TEMP\dsh-opencode-go-debug"
-dsh web
+```sh
+dsh plugin --profile web update dsh-opencode-go --latest
 ```
 
-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.
+Restart `dsh web` and reload the page afterward. For desktop DSH, quit and reopen the application. Headless users should replace `web` with `headless`. The repository's default branch may contain changes not yet released to npm.
 
-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.
+**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.
 
-## Update and uninstall
+**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.
 
-Update to the latest npm release:
+**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.
 
-```sh
-dsh plugin --profile web update dsh-opencode-go --latest
-```
+**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`.
 
-Restart `dsh web` and reload the page afterward. For desktop DSH, quit and reopen the application. Headless users should replace `web` with `headless`.
+**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).
 
 Uninstall:
 
@@ -207,10 +131,9 @@ Uninstall:
 dsh plugin --profile web remove dsh-opencode-go
 ```
 
-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`.
-
-## More
+## More documentation
 
+- [Advanced guide: Headless, proxies, manual configuration, and error diagnostics](docs/advanced.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

@@ -2,202 +2,128 @@
 
 [English](README.en.md)
 
-在 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 中使用 OpenCode Go 订阅模型，支持流式回复、思考模式、工具调用和图片输入。插件自动同步模型列表与容量信息，并提供多账号管理、订阅用量显示和网络代理设置。
+为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 提供 **OpenCode Go 订阅用量查看与多账号管理**，让额度、重置时间和账号切换更方便。
 
-适用于 DSH `0.1.5-rc.1` 及以上版本。
+DSH 已支持原生接入 OpenCode Go。本插件重点提供会话内用量查看、多账号管理，以及独立的模型与设置界面。
 
-安装兼容性已覆盖十个宿主版本，从 `0.1.5-rc.1` 到 `0.2.1-alpha.1`，具体版本见[兼容矩阵](docs/development.md#installed-package-matrix)。后续宿主版本仍需验证；目前会明确拒绝 developer 消息、动态工具增删和延迟工具加载。
+- **用量随手可查**：在会话输入区查看用量，展开查看 5 小时、每周、每月已用百分比与重置时间。
+- **多个账号集中管理**：查看各账号额度和 Key 状态，拖动排序，在会话中手动切换，也可开启自动使用备用账号。
+- **模型与设置更直观**：搜索和筛选模型，调整显示、容量与思考预算；高级设置按用途分组，提供提示与恢复默认操作。
 
-## 安装
+支持中文和英文，跟随 DSH 的界面语言。
 
-### 在 DSH 中安装
-
-1. 打开 **插件 → 添加插件**。
-2. 输入 `dsh-opencode-go`，点击 **安装**。
-3. 安装完成后点击 **立即启用**。
-
-![在 DSH 中安装插件](docs/assets/install-via-dsh.gif)
-
-也可以在添加插件时输入 Git 仓库地址：
-
-```text
-https://github.com/Duskriver/dsh-opencode-go
-```
+## 查看订阅用量
 
-### 命令行安装
+点击会话输入区旁的用量胶囊，展开当前账号的订阅用量。进度条显示**已用百分比**，接近上限时变为黄色，耗尽时变为红色；每个额度窗口都显示重置时间。
 
-```sh
-dsh plugin --profile web add dsh-opencode-go
-```
-
-安装后启动或重启 `dsh web`。Web 和 Headless 使用各自的 profile，分别安装和更新。
-
-## 开始使用
-
-1. 打开 **设置 → OpenCode Go**，填入 API Key 并保存，或在「账号」中添加账号。
-2. 在会话模型选择器中选择 **DSH OpenCode Go** 下的模型。
-3. 开始对话；支持思考的模型可选择其提供的思考档位，支持图片的模型可直接接收图片。
-
-在设置页刷新模型列表即可同步最新目录。每个模型旁的开关控制它是否出现在选择器中，修改后立即生效。模型的上下文窗口和最大输出默认使用目录配置，也可逐个修改并保存。
-
-思考选项中的 **默认** 使用服务商设置；**Off** 明确关闭思考。只有开关的模型显示 **On / Off**，支持强度的模型显示其可用档位，预算式模型显示具体的 token 数值。
+![订阅用量面板：当前账号、三个额度窗口及重置时间](docs/assets/usage-panel.png)
 
-预算式模型提供 1,024 / 2,048 / 8,192 / 16,384 tokens 等常用选项。在设置页选择模型，展开“思考预算”，输入数值、点击“添加”并保存，即可在会话中选择自定义预算。可用范围随模型而定；SDK 会根据剩余输出空间缩小实际预算。
+显示用量时每分钟自动刷新；页面进入后台时暂停周期查询，回到前台后刷新。暂时查询失败时，面板会提示失败，并在可保留上次数据时标明“上次数据”，可点击“立即重试”。也可以在设置页的账号卡片中点击 **刷新额度**。
 
-插件跟随 DSH 的界面语言，支持中文和英文。
+在 **设置 → OpenCode Go → 高级设置 → 额度显示** 中选择：
 
-### 查看订阅用量
-
-点击会话输入区旁的用量胶囊，查看当前账号的 5 小时、周和月用量及重置时间。用量每分钟刷新，也可手动刷新。
+| 模式 | 行为 |
+| --- | --- |
+| 自动（默认） | 选中 **DSH OpenCode Go** 模型时显示 |
+| 常驻 | 使用其他模型时也显示已配置的 OpenCode Go 账号用量 |
+| 关闭 | 隐藏会话用量胶囊并停止其轮询 |
 
-在 **高级设置 → 额度显示** 中选择：
+## 管理多个账号
 
-- **自动**：使用本插件的模型时显示，默认选项。
-- **常驻**：使用其他模型时也显示。
-- **关闭**：隐藏用量显示并停止轮询。
+在 **设置 → OpenCode Go → 账号** 中集中管理账号：
 
-![订阅用量](image.png)
+![账号管理：账号排序、额度详情、Key 操作和自动使用备用账号](docs/assets/accounts.png)
 
-### 管理多个账号
+- 添加账号、重命名、替换 Key 或删除账号；最多支持 20 个账号。
+- 每行查看 Key 状态、5 小时已用百分比和重置倒计时，展开查看完整用量与账号操作。
+- 拖动行首手柄调整顺序，第一行成为当前账号；顺序也决定自动尝试备用账号的次序。
+- 在会话用量面板中点击 **切换**，将所选账号移至首位，供本 profile 后续请求使用；其他账号的相对顺序保持不变。
 
-在「账号」中添加、重命名或更换 Key，展开账号行可查看详细用量。拖动行首手柄调整顺序，第一行成为当前账号。
+开启 **自动使用备用账号** 后，当前账号额度耗尽或 Key 不可用时，插件会在开始输出前按顺序尝试其他账号。开始正常输出的备用账号会移至首位并成为当前账号，用量面板会显示切换提示。请求已经输出、产生 token 用量或被取消后，不会自动切换账号重发。
 
-开启 **自动切换** 后，当前账号额度耗尽或 Key 不可用时，插件会在开始输出前按列表顺序尝试其他账号。也可以在用量胶囊中点击 **切换**，直接选择后续请求使用的账号。
+Key 通过 DSH 凭据服务保存，设置页不会回显已保存的密钥。
 
-新增或删除账号中途关闭页面、断开连接时，宿主会在后续启动或设置、凭据更新时继续恢复。未能写入 Key 的新增账号会保留在列表，可补填 Key 或删除；恢复不会覆盖期间手动选择的当前账号。
+## 安装与快速开始
 
-## 高级用法
+适用于 DSH `0.1.5-rc.1` 及以上版本。已验证的宿主版本见[兼容矩阵](docs/development.md#installed-package-matrix)。
 
-### Headless 模式
+### 在 DSH 中安装
 
-安装插件：
+1. 打开 **插件 → 添加插件**。
+2. 输入 `dsh-opencode-go`，点击 **安装**。
+3. 安装完成后点击 **立即启用**。
 
-```sh
-dsh plugin --profile headless add dsh-opencode-go
-```
+![在 DSH 中安装插件](docs/assets/install-via-dsh.gif)
 
-将以下内容保存为 `headless.patch.yml`：
+也可以在添加插件时输入仓库地址：
 
-```yaml
-- id: agent-default-model
-  config:
-    provider: dsh-opencode-go
-    model: deepseek-v4.1-flash
+```text
+https://github.com/Duskriver/dsh-opencode-go
 ```
 
-在 Bash 或 Zsh 中输入 Key 后运行任务：
+命令行安装：
 
 ```sh
-read -s OPENCODE_API_KEY
-export OPENCODE_API_KEY
-dsh --profile headless --patch ./headless.patch.yml "你好"
+dsh plugin --profile web add dsh-opencode-go
 ```
 
-将 `model` 换成设置页中可用的模型 ID。示例文件见 [examples/headless.patch.yml](examples/headless.patch.yml)。
+命令行安装后启动或重启 `dsh web`。Web 和 Headless 使用各自的 profile，分别安装和更新。
 
-### 网络代理
+### 开始使用
 
-在 **设置 → OpenCode Go → 高级设置 → 代理地址** 中填写并保存，例如：
+1. 打开 **设置 → OpenCode Go**，填入 OpenCode Go 订阅的 API Key 并保存，或在 **账号** 中添加账号。
+2. 在会话模型选择器中选择 **DSH OpenCode Go** 下的模型。
+3. 开始对话，在输入区旁查看用量；有多个账号时可展开面板切换。
 
-```text
-http://127.0.0.1:7890
-socks5://127.0.0.1:1080
-```
+插件使用独立的模型提供方 **DSH OpenCode Go**。选择 DSH 原生提供的模型不会自动使用本插件的账号切换功能；“常驻”模式仍可展示本插件已配置账号的用量。
 
-支持 HTTP、HTTPS、SOCKS5 和带用户名、密码的代理 URL。保存后，后续对话、模型目录更新和用量查询使用新代理。代理运行在 DSH 所在的机器上；远程部署中的 `127.0.0.1` 指服务器自身。
+## 模型与设置
 
-### 手动配置
+### 选择模型与调整参数
 
-在 **高级设置 → DeepSeek V4.1 Flash 协议** 中可选择 **Responses（实验性）** 并保存，便于比较同一模型的不同协议。默认 **自动** 跟随模型目录；改回自动即可恢复。选择只影响新请求，不会切换已准备或正在执行的调用，也不会在协议错误后自动改用另一协议。
+在 **可用模型** 中按名称或 ID 搜索，也可以筛选 **近 7 天发布**、**已自定义** 或 **过时模型**。点击 **刷新** 核对最新模型目录。
 
-目前仅支持 `deepseek-v4.1-flash` 的 Responses 覆盖，沿用当前账号、代理、会话标识与用量处理。[issue #45](https://github.com/Duskriver/dsh-opencode-go/issues/45) 报告了更低延迟，但它不是网关的稳定性能承诺，也不能据此确认底层服务商；是否更快请以自己的测试为准。无需覆盖时省略以下配置：
+![模型设置：搜索、分类筛选、显示开关和参数编辑](docs/assets/model-settings.png)
 
-```yaml
-- id: opencode-go
-  config:
-    protocolOverrides:
-      deepseek-v4.1-flash: openai-responses
-```
+- 模型开关控制它是否出现在会话选择器中，修改立即生效。
+- 选中模型可查看目录提供的上下文窗口、最大输出和输入模态，容量覆盖保存后生效，留空使用默认值。
+- 支持思考的模型提供相应开关、强度或 token 预算选项；预算式模型还可添加自定义预算并保存。
 
-将该模型的值设为 `null` 会明确选择自动，即使继承的配置启用了 Responses；设置页的「恢复默认」会移除当前层覆盖，恢复继承值。其他模型或协议组合会被拒绝。
-
-在 patch 文件中添加 `opencode-go` 配置块，可与上面的默认模型配置一起使用：
-
-```yaml
-- id: opencode-go
-  config:
-    apiKeyEnv: OPENCODE_API_KEY
-    accounts:
-      - id: primary
-        name: 主账号
-        apiKeyEnv: OPENCODE_API_KEY
-      - id: backup
-        name: 备用账号
-        apiKeyEnv: OPENCODE_GO_BACKUP_KEY
-    autoSwitch: true
-    proxyURL: http://127.0.0.1:7890
-    refreshMinutes: 60
-    modelVisibility:
-      deepseek-v4-pro: false
-    modelLimits:
-      deepseek-v4.1-flash:
-        maxTokens: 8192
-      qwen3.7-plus:
-        thinkingBudgets: [4096, 6000]
-    maxImages: 30
-```
+`deepseek-v4.1-flash` 每次请求默认使用 **64k（65,536 tokens）** 的输出预算，模型输出上限更小时取较小值，并将该默认值告知 DSH 用于计算压缩时机。该规则只应用于此模型；其他模型沿用 SDK 的默认输出行为。需要更长回答时，可在模型容量覆盖中设置「最大输出」。
 
-按需保留配置项，并通过 DSH 凭据服务或环境变量提供对应的 Key。`apiKeyEnv` 选择当前账号，`accounts` 的顺序决定自动切换顺序。
+流式回复、思考、工具调用和图片输入取决于模型能力。界面中的输入模态来自在线模型配置；本插件目前仅转换并转发图像附件。
 
-| 配置项 | 用途 |
-| --- | --- |
-| `baseURL` | OpenCode Go 网关地址，默认 `https://opencode.ai/zen/go/v1` |
-| `usageDisplay` | 额度显示模式：`auto`、`always` 或 `off` |
-| `proxyURL` | 网络代理；空字符串使用默认网络设置 |
-| `refreshMinutes` | 模型目录缓存时长，默认 60 分钟；设置页可随时手动刷新 |
-| `modelVisibility` | 按模型 ID 控制选择器中的显示状态 |
-| `protocolOverrides` | 实验性协议覆盖；目前仅支持 `deepseek-v4.1-flash: openai-responses`，省略或模型值为 `null` 时自动跟随目录 |
-| `modelLimits` | 按模型覆盖 `contextWindow`、`maxTokens`，或用 `thinkingBudgets` 添加思考预算选项；空值使用默认设置 |
-| `maxImages` | 单次请求历史中的图片数量上限，默认不设上限；超过时先卸载最旧图片 |
-| `streamIdleTimeoutMs` | 等待下一个流事件的最长时间，默认 300000 毫秒 |
-| `requestPreparationTimeoutMs` | 目录查询及每次尝试的凭据、图片准备时限，默认 60000 毫秒 |
-| `requestTimeoutMs` | 一次发送的完整时限，包含目录查询、账号切换和流式输出，默认 1800000 毫秒；预先准备的调用从发送时计时 |
+### 分组高级设置
 
-图片卸载会保留原始附件，并将请求中的旧图片替换为文字占位；调高上限不会自动恢复已卸载的历史图片。
+高级设置按 **用量与协议**、**连接**、**缓存与超时**、**图片处理** 分组。悬停问号查看说明，可通过 **全部恢复默认** 清除该卡片的自定义覆盖，再保存修改；当前账号选择保持不变。
 
-图片数量超限会在读取附件前返回卸载请求；图片准备在同一插件模块内共享四个执行名额和最多 32 个等待名额，精确字节超限时停止安排剩余图片。正在发送的图片请求共享 128 MiB 的已准备原始数据与 base64 预算；这不是进程总内存上限。排队或共享预算超限会返回 `IMAGE_RESOURCE_BUSY`，可在其他请求结束后重试。数量与字节限制可能需要宿主分次卸载后重试。
+![高级设置：分组配置、提示入口和统一恢复默认](docs/assets/advanced-settings.png)
 
-首次查询目录失败会报告 `DISCOVERY_FAILED`；已有目录时保留之前确认过的模型。网关明确返回空列表才会清空目录。列表中仅部分行格式错误时，仍可使用有效模型，设置页与日志会提示被忽略的行数。高级表单的普通配置项一次提交并检查版本；凭据由独立服务保存，凭据保存失败时保留其草稿，重试只提交未成功的部分。
+支持 HTTP、HTTPS 和 SOCKS5 代理，保存后用于后续对话、模型目录更新与用量查询。代理运行在 DSH 所在的机器上；远程部署中的 `127.0.0.1` 指服务器自身。
 
-### 导出错误诊断
+DeepSeek V4.1 Flash 的 Responses 协议选项为实验性，仅影响新请求，不承诺更低延迟。完整配置与使用说明见[高级使用指南](docs/advanced.md)。
 
-需要排查请求失败时，在启动 DSH 前设置诊断目录：
+截图用于展示界面，具体模型、额度和时间以当前账号与在线目录为准。
 
-```sh
-export DSH_OPENCODE_GO_DEBUG_DIR=/tmp/dsh-opencode-go-debug
-dsh web
-```
+## 更新与常见问题
 
-Windows PowerShell：
+更新到 npm 最新发布版本：
 
-```powershell
-$env:DSH_OPENCODE_GO_DEBUG_DIR = "$env:TEMP\dsh-opencode-go-debug"
-dsh web
+```sh
+dsh plugin --profile web update dsh-opencode-go --latest
 ```
 
-复现后，错误信息会给出 JSON 文件路径。记录包含模型、请求参数摘要、HTTP 状态、上游日志与路由编号及错误响应，便于提交 [问题反馈](https://github.com/Duskriver/dsh-opencode-go/issues)。分享前检查服务返回的错误内容；清空环境变量并重启 DSH 即可关闭诊断。
+更新后重启 `dsh web` 并刷新页面；桌面版完全退出后重新打开。Headless 用户将 `web` 换成 `headless`。仓库默认分支可能包含尚未发布到 npm 的修改。
 
-DSH debug 日志另有每次发送的调用编号，以及各次尝试的阶段耗时、HTTP 状态、上游请求编号、首次输出等待时间与错误码，包含 HTTP 200 后的流中断；图片请求还记录排队累计等待与资源占用峰值。错误文件带有相同调用编号与尝试序号，便于关联排查。这些摘要不记录提示词、Key、代理地址或原始会话编号。
+**为什么没有显示用量？** 默认“自动”模式仅在选择 **DSH OpenCode Go** 模型时显示。请检查插件是否启用、Key 是否配置，以及额度显示模式；使用其他提供方时可选择“常驻”。
 
-## 更新与卸载
+**查询失败或添加账号中断怎么办？** 用量查询可在面板中重试，或在账号卡片中刷新额度。未成功保存 Key 的新增账号可补填 Key 或删除；账号操作的恢复机制见[高级使用指南](docs/advanced.md#账号操作与保存)。
 
-更新到 npm 最新版本：
+**长会话持续报 400 怎么办？** 检查错误中的输出预算与上下文窗口，可执行 `/compact` 或调低该模型的「最大输出」后重试。明确的上下文超限会交给 DSH 的恢复机制；原因不明的 400 会保留原分类并给出排查建议。失败且未取得 token 用量时，插件不发送全零用量，避免将上下文占用误报为 0%。
 
-```sh
-dsh plugin --profile web update dsh-opencode-go --latest
-```
+**升级后旧会话找不到模型？** 从 `0.1.16` 及更早版本升级时，在旧会话或 Agent 预设中重新选择 **DSH OpenCode Go**；手动配置使用 `provider: dsh-opencode-go`。
 
-更新后重启 `dsh web` 并刷新页面；桌面版完全退出后重新打开。Headless 用户将 `web` 换成 `headless`。
+**兼容性范围是什么？** 安装兼容性覆盖十个宿主版本，从 `0.1.5-rc.1` 到 `0.2.1-alpha.1`，后续版本仍需验证。目前明确拒绝 developer 消息、动态工具增删和延迟工具加载，详见[开发与兼容性说明](docs/development.md)。
 
 卸载：
 
@@ -205,10 +131,9 @@ dsh plugin --profile web update dsh-opencode-go --latest
 dsh plugin --profile web remove dsh-opencode-go
 ```
 
-从 `0.1.16` 及更早版本升级时，在旧会话或 Agent 预设中重新选择 **DSH OpenCode Go**；手动配置使用 `provider: dsh-opencode-go`。
-
-## 更多
+## 更多文档
 
+- [高级使用指南：Headless、代理、手动配置与错误诊断](docs/advanced.md)
 - [开发与测试](docs/development.md)
 - [验证记录](docs/verification.md)
 - [问题与建议](https://github.com/Duskriver/dsh-opencode-go/issues)

package/THIRD_PARTY_NOTICES.md

@@ -1,7 +1,11 @@
 # Third-party notices
 
-The adapter, settings UI, and `src/conversion/{context,stream,replay}.ts` derive from DeepSeek Harness, copyright (c) 2026 DeepSeek, under the MIT license included in LICENSE. 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/{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 host bundle includes the required portions of `@earendil-works/pi-ai@1.1.0` and `partial-json`; SDK declarations include pi-ai, pi-telemetry and TypeBox types. Their original MIT licenses are reproduced in `lib/vendor-licenses.txt`. The pi packages' license comes from the [upstream v1.1.0 license](https://github.com/earendil-works/pi/blob/v1.1.0/LICENSE), which their npm distributions omit. OpenAI and Anthropic transport SDKs remain separate runtime dependencies.
+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 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.