dsh-opencode-go 0.1.20 → 0.1.22

package/README.en.md

@@ -1,211 +1,217 @@
 # dsh-opencode-go
 
-[中文](README.md)
+[简体中文](README.md)
 
-Use OpenCode Go subscription models in [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness), with streaming replies, tool calls, and image input.
+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.
 
-The plugin automatically adds the session headers required by OpenCode Go, reads the gateway model catalog, and displays subscription usage. There is no need to configure model protocols, modalities, context windows, or maximum output tokens manually.
+Requires DSH `0.1.5-rc.1` or later.
 
-## Features
+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.
 
-- **Session headers**: Every request includes the Harness User-Agent and `x-opencode-session`. A session keeps a stable ID to support gateway routing and prompt-cache optimization; actual cache hits depend on the upstream service.
-- **Streaming and history**: Supports streaming output, tool calls, and history replay through pi-ai.
-- **Image input**: Supports models that advertise image capability in the catalog.
-- **Model capacity overrides**: Override the context window and maximum output per model, with blank values inheriting the online catalog.
-- **Per-model switches**: Control which models appear in conversations, with changes applied immediately. Ordinary models default to on and deprecated models default to off; any model can be enabled individually.
-- **Prompt and caching**: The plugin does not add hidden system prompts; the session ID is used for gateway routing.
+## Install
 
-## Installation and usage
+### From DSH
 
-Supports DSH `0.1.5-rc.1` and later, including alpha, rc, and stable releases. Compatibility will be maintained as new host versions are released.
-
-Verified versions: `0.1.5-rc.1`, `0.1.5-rc.2`, `0.1.6-alpha.1`, `0.1.6-alpha.2`, `0.1.7-alpha.1`, `0.1.7-alpha.2`, `0.1.7-rc.1`, `0.1.7-rc.2`, and `0.2.0-rc.2`.
-
-### Install from DSH (recommended)
-
-1. Open the **Plugins** page in DSH and click **Add plugin** in the top-right corner.
+1. Open **Plugins → Add plugin**.
 2. Enter `dsh-opencode-go` and click **Install**.
-3. If prompted after installation, click **Enable now**.
-
-![Add, install, and enable dsh-opencode-go from DSH (Chinese UI)](docs/assets/install-via-dsh.gif)
+3. Click **Enable now** after installation.
 
-Then open **Settings → OpenCode Go**, enter and save your API key, and select an OpenCode Go model in a conversation.
+![Install the plugin in DSH](docs/assets/install-via-dsh.gif)
 
-The plugin can also be installed by entering this Git repository URL:
+You can also enter the Git repository URL when adding the plugin:
 
 ```text
 https://github.com/Duskriver/dsh-opencode-go
 ```
 
-The current default branch includes the compiled plugin. Installation needs neither a local build nor a plugin-specific `allowBuilds` entry. URLs pinned to older commits retain those commits' installation behavior; update them to the current branch.
-
-If your DSH version does not have an **Add plugin** entry, use the command-line method below.
-
-### Command-line installation (alternative)
+### From the command line
 
 ```sh
 dsh plugin --profile web add dsh-opencode-go
 ```
 
-Start or restart `dsh web`, then:
+Start or restart `dsh web` after installation. Web and Headless use separate profiles; install and update each profile individually.
 
-1. Open **Settings → OpenCode Go**.
-2. Enter and save your OpenCode Go API key.
-3. Select an OpenCode Go model from the conversation model picker.
+## Get started
 
-### Headless
+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.
 
-Install the plugin into the Headless profile:
+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.
 
-```sh
-dsh plugin --profile headless add dsh-opencode-go
-```
+**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.
 
-Save the following as `headless.patch.yml` to select a default model:
+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.
 
-```yaml
-- id: agent-default-model
-  config:
-    provider: dsh-opencode-go
-    model: deepseek-v4.1-flash
-```
+The plugin follows DSH's interface language and supports English and Chinese.
 
-Read the API key in Bash or Zsh, then run a task:
+### View subscription usage
 
-```sh
-read -s OPENCODE_API_KEY
-export OPENCODE_API_KEY
-dsh --profile headless --patch ./headless.patch.yml "Hello"
-```
+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.
 
-The model ID must be available in the current gateway catalog. Web and Headless use separate profiles, so install the plugin in each profile you use.
+Under **Advanced settings → Usage display**, choose:
 
-To build from source and install a local package:
+- **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.
 
-```sh
-npm ci
-npm run compile
-npm pack
-dsh plugin --profile web add ./dsh-opencode-go-0.1.20.tgz
-```
+![Subscription usage](image.png)
 
-Source development builds the plugin explicitly with `npm run compile`; `--legacy-peer-deps` is not required. Multi-version DSH compatibility tests use independent environments and are not installed during ordinary installation or builds. For Headless, replace `web` with `headless`.
+### Manage multiple accounts
 
-### Development and verification
+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.
 
-```sh
-npm run compile       # Regenerate lib/ and commit it with source changes
-npm test              # Core tests, rebuilding the plugin first
-npm run check:dist    # Verify shipped artifacts match the source
-npm run test:compat   # One tarball tested in 9 independent DSH environments
-npm run test:install  # npm / pnpm Git installs without plugin build approval
-npm run verify        # All of the above
-```
+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.
 
-Compatibility and installation checks download dependencies, use system temporary directories, and clean up afterward. To check one host, run `npm run test:compat -- v017-rc2`. See the [development guide](docs/development.md) for maintaining host versions.
+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.
 
-## Updating the plugin
+## Advanced usage
 
-Update the plugin in the Web profile to the latest npm version:
+### Headless mode
+
+Install the plugin:
 
 ```sh
-dsh plugin --profile web update dsh-opencode-go --latest
+dsh plugin --profile headless add dsh-opencode-go
 ```
 
-Restart `dsh web` and refresh the browser afterwards. For Headless, replace `web` with `headless`; if both profiles have the plugin installed, update each one separately.
+Save this as `headless.patch.yml`:
 
-After updating the desktop plugin, fully quit and reopen DeepSeek Harness to load the updated plugin code.
+```yaml
+- id: agent-default-model
+  config:
+    provider: dsh-opencode-go
+    model: deepseek-v4.1-flash
+```
 
-## Subscription usage display
+Enter your key in Bash or Zsh, then run a task:
 
-Under **Settings → OpenCode Go → Advanced settings → Usage display**, choose a mode and save: **Auto (default)** shows the pill only for this plugin's DSH OpenCode Go models; **Always** keeps it visible with other models, including the built-in `opencode-go` provider; **Off** hides it and stops polling. Disabling OpenCode Go hides the pill in every mode. Click the pill to open the usage panel.
+```sh
+read -s OPENCODE_API_KEY
+export OPENCODE_API_KEY
+dsh --profile headless --patch ./headless.patch.yml "Hello"
+```
 
-Usage refreshes every minute. Temporary network or service errors retain the last reading for the same account, with a failure notice, timestamp, and reason; the usage panel offers an immediate retry. Initial and authentication failures do not show old usage. Catalog, metadata, and usage JSON requests retry a transient connection reset once within the original timeout budget; this cannot guarantee recovery while the network is failing.
+Replace `model` with an available model ID from Settings. See [examples/headless.patch.yml](examples/headless.patch.yml).
 
-![OpenCode Go usage display](image.png)
+### Network proxy
 
-## Interface language
+Open **Settings → OpenCode Go → Advanced settings → Proxy address**, enter a URL, and save. Examples:
 
-The plugin follows Harness and supplies Chinese and English copy without storing a separate language preference. With no explicit choice, the Web client matches the browser's preferred languages (usually inherited from the system); native shells with a system-language bridge supply their operating-system languages. English is used when no supported language matches.
+```text
+http://127.0.0.1:7890
+socks5://127.0.0.1:1080
+```
 
-A language explicitly selected in Harness takes precedence and updates the plugin immediately without discarding form drafts. Model names and IDs stay unchanged; usage dates and capacity numbers follow the active interface language. Automatic language detection runs at startup: reload the Web page after changing browser languages, or restart desktop Harness after changing system languages.
+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.
 
-## Model switches
+### Experimental Responses protocol
 
-In **Settings → OpenCode Go**, the switch beside each model controls whether it appears in conversation model pickers. Switch changes are saved immediately; capacity and API key edits still require **Save**. Ordinary models default to on and deprecated models default to off. You can enable a deprecated model individually or disable an ordinary model. Newly discovered models follow the same defaults unless configured individually.
+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.
 
-For manual configuration, add `modelVisibility` under the plugin's `config`, replacing the example placeholders with actual model IDs:
+To configure the experiment manually:
 
 ```yaml
-modelVisibility:
-  your-model-id: false
-  your-deprecated-model-id: true
+- id: opencode-go
+  config:
+    protocolOverrides:
+      deepseek-v4.1-flash: openai-responses
 ```
 
-Only the listed IDs receive explicit overrides. Switches affect model pickers only: existing conversations can still call hidden models served by the gateway, and Settings retains the complete model list.
-
-The older `showDeprecatedModels` and `visibleModelIds` fields no longer control visibility. Use the individual switches or `modelVisibility`; retaining old fields does not prevent the plugin from loading.
-
-## Image count cap
+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.
 
-Under **Settings → OpenCode Go → Advanced settings**, set `maxImages` to a positive integer and save; no restart is needed. It is unset by default, with no image-count cap. Clearing or resetting removes the user override and inherits the base configuration; if the base has no cap either, the count is unlimited.
+### Manual configuration
 
-The count covers the full history sent in one request, including tool-result images. Repeated occurrences of the same attachment count separately. With a cap of `30`, 30 images pass through; 31 images cause the oldest occurrence to be offloaded before the request continues. Offloading replaces image content with a text placeholder and keeps the original attachment, but the model cannot see the offloaded image content in that request.
+Add an `opencode-go` configuration block to a patch file. It can be combined with the default-model configuration above:
 
-DSH 0.1.5 offloads only for the current request. DSH 0.1.6 and later record offloaded occurrences and retry through the host's image-offload mechanism; raising or clearing the cap does not automatically restore images already offloaded from history. Existing payload, pixel, and per-image byte budgets still apply independently and may require more images to be offloaded. This optional compatibility setting does not change upstream service limits.
-
-## FAQ
-
-### Coexistence with the host's OpenCode Go and upgrade migration
-
-Version 0.1.17 and later use the independent `dsh-opencode-go` provider, shown as **DSH OpenCode Go** in the model picker. The host pi-ai's `opencode-go` provider can run alongside it. Configure the API key in this plugin's settings, then choose a model under **DSH OpenCode Go**. Versions 0.1.16 and earlier use `opencode-go`; their headless configuration should also use that older identity.
-
-Sessions, Agent presets and headless defaults previously saved with `provider: opencode-go` need to select **DSH OpenCode Go** again, or change the provider to `dsh-opencode-go`. API keys, model settings and metadata caches are retained. Existing session content remains available; when switching providers, DSH removes the previous adapter's private replay metadata according to its ownership rules.
+```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
+```
 
-### An expected model is missing
+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.
 
-Check that the model's switch is on in **Settings → OpenCode Go**. Deprecated models default to off; turning on an individual model makes it available in conversation pickers without another global option.
+| 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 |
 
-Confirm that the plugin is enabled and an API key is configured, then refresh the model list in Settings. Settings reads and refreshes request the gateway's `/models` endpoint and synchronize the OpenCode Go configuration from [models.dev](https://models.dev/api.json). Conversation pickers respect the catalog cache lifetime, so model switch changes do not force another gateway request. Protocol support, context length, output limit, and image capability come from the online configuration, so new models do not require a release of this plugin or pi-ai.
+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.
 
-Models that are present in the gateway and have an entry using Anthropic Messages, OpenAI Chat Completions, or OpenAI Responses are discovered on the next Settings refresh or after the catalog cache expires. A Settings refresh bypasses the cache and notifies open conversation pickers to use the same updated catalog; a direct request for a previously unseen model also triggers an immediate resynchronization. The Settings page shows the complete discovery result.
+Image count overflow is detected before attachment reads. Preparation shares four execution slots and at most 32 queued tasks within the plugin module, and stops scheduling images when known encoded bytes exceed the payload cap. Active image attempts share a 128 MiB budget for prepared raw data plus base64 payloads; this is not a process memory limit. Queue or shared-budget overflow returns `IMAGE_RESOURCE_BUSY`; retry after another request completes. Count and byte limits may require successive host offload retries.
 
-A gateway model ID with no usable protocol or capability configuration is marked “Configuration missing” in Settings, with its switch off and disabled, and is kept out of the conversation picker, so one unconfigured model cannot block the rest of the list. Direct requests report the reason. Refresh after the upstream configuration is corrected. A model ID alone is not enough to reliably infer its transport; new protocols or protocol-specific exceptions may still require adapter changes.
+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.
 
-If online configuration cannot be loaded, models without usable cached or built-in configuration are marked “Configuration unavailable”, with the configuration source error shown on the page. Check access to `https://models.dev/api.json` from the machine running DSH and review the error details, then refresh. When retrying a retained model list, its previous failure stays visible until a successful refresh clears it; configured models remain usable.
+### Export error diagnostics
 
-A reasoning-capable model without adjustable reasoning levels (for example, `union-alpha`) remains selectable and usable; it simply has no reasoning-strength control.
+To investigate a failed request, set a diagnostics directory before starting DSH:
 
-MiMo V2.6 Flash's gateway catalog does not yet list its controls. Based on direct OpenCode Go probes, the plugin offers **Off / Low / Medium / High**: Default omits `reasoning_effort` and preserves gateway-default reasoning; Off sends `none`, and the other levels send their matching values. This rule applies only to the verified model and protocol, not other MiMo models. Low / Medium / High were accepted and returned reasoning content, but are not guaranteed to produce increasing amounts of reasoning.
+```sh
+export DSH_OPENCODE_GO_DEBUG_DIR=/tmp/dsh-opencode-go-debug
+dsh web
+```
 
-Online effort declarations determine selectable strengths. Toggle or budget declarations produce controls only for established native switch or budget protocols; they do not imply `off` or `high` effort parameters on a generic OpenAI-compatible route. An explicit empty control list does not gain an Off choice just because the model can reason.
+Windows PowerShell:
 
-A model that does offer adjustable levels also declares a default effort (`high` when the model offers it, otherwise the highest level it offers) whenever its transport would answer an unset effort with an explicit disable (`deepseek`, `zai`, `qwen`, `qwen-chat-template`). DSH uses that default when no level has been chosen, so leaving the control unset still sends a reasoning level instead of turning thinking off. Transports that leave the choice to the provider declare no default and are unchanged, and an explicitly chosen level always wins.
+```powershell
+$env:DSH_OPENCODE_GO_DEBUG_DIR = "$env:TEMP\dsh-opencode-go-debug"
+dsh web
+```
 
-If the online configuration is temporarily unavailable, the plugin prefers previously fetched configuration, including disk data from before a restart, and falls back to pi-ai's built-in metadata. If a gateway catalog refresh fails, ongoing requests and Settings retain the last successful list from the current process. A failure from either source shows a warning, its cause, and the last successful checks of the model listing and model configuration separately. An initial gateway failure never invents a model list from cached metadata.
+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.
 
-Model configuration is saved to `$DSH_HOME/cache/dsh-opencode-go/models.dev.api.json`, or `~/.dsh/cache/dsh-opencode-go/models.dev.api.json` when `DSH_HOME` is unset. This contains only public metadata, its ETag, and the last successful check time; it excludes API keys and gateway listings. After a restart, ordinary reads verify the gateway listing and use disk configuration while revalidating metadata in the background. The completed refresh updates conversation pickers. Corrupt caches fall back to the network, and write failures do not discard online results. Settings refreshes always wait for online verification, retaining old configuration with a diagnostic on failure; a disk hit is not reported as an online success. To clear the disk cache, exit DSH and delete this file.
+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.
 
-`refreshMinutes` controls the cache lifetime after a successful refresh. Failed refreshes become eligible for retry on the next read after 5, 10, 20, 40, then at most 60 seconds; there is no background polling when nothing reads the catalog. Explicit Settings refreshes and previously unknown model requests bypass this delay. Cancelling model resolution or generation immediately ends that caller's catalog wait while other callers can continue sharing the same refresh.
+## Update and uninstall
 
-Verified model configurations can serve generation immediately for five minutes after their cache lifetime expires, while triggering one shared background refresh. This window is measured from each source's last successful check; failed retries do not extend it. Beyond that window, requests wait for the next due refresh, retaining the existing fallback behavior if it fails. Initial loads without a disk cache, unknown models, and manual refreshes wait for online results. Listing requests have a 10-second deadline; the larger model metadata download has its own 30-second deadline and negotiates gzip to reduce transfer size on slow connections. If an HTTP/2 host compatibility issue delivers raw gzip bytes, the plugin asynchronously decompresses them within the same deadline, limiting both the delivered bytes and decoded result to 16 MiB. Model listing and usage requests continue to use uncompressed transfer.
+Update to the latest npm release:
 
-Continuation, retries, and restored sessions reuse the Host's durable session ID. Forks and subagent sessions use their own IDs, separate from the parent. Standalone requests without a session ID receive a fresh random identifier each time.
+```sh
+dsh plugin --profile web update dsh-opencode-go --latest
+```
 
-## Uninstall
+Restart `dsh web` and reload the page afterward. For desktop DSH, quit and reopen the application. Headless users should replace `web` with `headless`.
 
-Remove the plugin from the relevant profile and restart the application:
+Uninstall:
 
 ```sh
 dsh plugin --profile web remove dsh-opencode-go
-# or
-dsh plugin --profile headless remove dsh-opencode-go
 ```
 
-## Feedback
-
-Please open an issue for bugs or feature requests.
+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`.
 
-## License
+## More
 
-[MIT](LICENSE)
+- [Development and testing](docs/development.md)
+- [Verification notes](docs/verification.md)
+- [Issues and suggestions](https://github.com/Duskriver/dsh-opencode-go/issues)
+- [MIT license](LICENSE)