dsh-opencode-go 0.1.21 → 0.1.23

package/README.md

@@ -2,246 +2,135 @@
 
 [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 订阅用量查看与多账号管理**，让额度、重置时间和账号切换更方便。
 
-插件会自动添加 OpenCode Go 所需的会话请求头、读取网关模型目录，并显示订阅用量，无需给模型配置协议、模态、上下文长度、最大输出token
+DSH 已支持原生接入 OpenCode Go。本插件重点提供会话内用量查看、多账号管理，以及独立的模型与设置界面。
 
-## 功能说明
+- **用量随手可查**：在会话输入区查看用量，展开查看 5 小时、每周、每月已用百分比与重置时间。
+- **多个账号集中管理**：查看各账号额度和 Key 状态，拖动排序，在会话中手动切换，也可开启自动使用备用账号。
+- **模型与设置更直观**：搜索和筛选模型，调整显示、容量与思考预算；高级设置按用途分组，提供提示与恢复默认操作。
 
-- **会话请求头**：每次请求包含 Harness User-Agent 和 `x-opencode-session`。同一会话保持稳定 ID，支持网关路由和提示词缓存优化；实际命中率取决于上游服务。
-- **流式与历史**：支持流式输出、工具调用及历史回放，协议请求由 pi-ai 执行。
-- **图片输入**：支持目录中声明图片能力的模型。
-- **模型容量覆盖**：可按模型覆盖上下文窗口和最大输出，空值继承在线目录。
-- **逐模型开关**：每个模型独立控制会话中的显示状态，修改立即生效；普通模型默认开启，过时模型默认关闭，也可单独开启。
-- **网络代理**：在设置页配置 HTTP(S) 或 SOCKS5 代理，统一用于对话、模型目录更新与订阅用量查询。
-- **提示与缓存**：插件不增加隐藏系统提示；会话 ID 用于网关路由。
+支持中文和英文，跟随 DSH 的界面语言。
 
-## 安装与使用
+## 查看订阅用量
 
-支持 DSH `0.1.5-rc.1` 及以上版本，包括 alpha、rc 和正式版，并持续跟随宿主版本更新维护兼容性。
+点击会话输入区旁的用量胶囊，展开当前账号的订阅用量。进度条显示**已用百分比**，接近上限时变为黄色，耗尽时变为红色；每个额度窗口都显示重置时间。
 
-已验证版本：`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`、`0.2.0-rc.2` 和 `0.2.1-alpha.1`。
+![订阅用量面板：当前账号、三个额度窗口及重置时间](docs/assets/usage-panel.png)
 
-### 在 DSH 中安装（推荐）
+显示用量时每分钟自动刷新；页面进入后台时暂停周期查询，回到前台后刷新。暂时查询失败时，面板会提示失败，并在可保留上次数据时标明“上次数据”，可点击“立即重试”。也可以在设置页的账号卡片中点击 **刷新额度**。
 
-1. 打开 DSH 的 **插件** 页面，点击右上角 **添加插件**。
-2. 输入 `dsh-opencode-go`，点击 **安装**。
-3. 安装成功后，如果出现 **立即启用**，点击即可。
-
-![在 DSH 插件页添加、安装并启用 dsh-opencode-go](docs/assets/install-via-dsh.gif)
+在 **设置 → OpenCode Go → 高级设置 → 额度显示** 中选择：
 
-然后打开 **设置 → OpenCode Go**，填入 API Key 并保存，或在「账号」中添加账号，即可在会话中选择 OpenCode Go 模型。
+| 模式 | 行为 |
+| --- | --- |
+| 自动（默认） | 选中 **DSH OpenCode Go** 模型时显示 |
+| 常驻 | 使用其他模型时也显示已配置的 OpenCode Go 账号用量 |
+| 关闭 | 隐藏会话用量胶囊并停止其轮询 |
 
-也支持在添加插件时直接输入 Git 仓库地址：
+## 管理多个账号
 
-```text
-https://github.com/Duskriver/dsh-opencode-go
-```
+在 **设置 → OpenCode Go → 账号** 中集中管理账号：
 
-当前主分支附带编译好的插件，安装时无需本地构建，也无需为本插件修改 `allowBuilds`。固定到旧提交的 Git 地址仍沿用旧提交的安装方式，请更新到当前主分支。
+![账号管理：账号排序、额度详情、Key 操作和自动使用备用账号](docs/assets/accounts.png)
 
-若当前 DSH 没有「添加插件」入口，可使用下面的命令行方式。
+- 添加账号、重命名、替换 Key 或删除账号；最多支持 20 个账号。
+- 每行查看 Key 状态、5 小时已用百分比和重置倒计时，展开查看完整用量与账号操作。
+- 拖动行首手柄调整顺序，第一行成为当前账号；顺序也决定自动尝试备用账号的次序。
+- 在会话用量面板中点击 **切换**，将所选账号移至首位，供本 profile 后续请求使用；其他账号的相对顺序保持不变。
 
-### 命令行安装（备选）
-
-```sh
-dsh plugin --profile web add dsh-opencode-go
-```
+开启 **自动使用备用账号** 后，当前账号额度耗尽或 Key 不可用时，插件会在开始输出前按顺序尝试其他账号。开始正常输出的备用账号会移至首位并成为当前账号，用量面板会显示切换提示。请求已经输出、产生 token 用量或被取消后，不会自动切换账号重发。
 
-安装后启动或重启 `dsh web`，然后：
+Key 通过 DSH 凭据服务保存，设置页不会回显已保存的密钥。
 
-1. 打开 **设置 → OpenCode Go**。
-2. 填入 OpenCode Go API Key 并保存。
-3. 在会话的模型选择器中选择 OpenCode Go 模型。
+## 安装与快速开始
 
-### 无头模式
+适用于 DSH `0.1.5-rc.1` 及以上版本。已验证的宿主版本见[兼容矩阵](docs/development.md#installed-package-matrix)。
 
-安装到 Headless profile：
+### 在 DSH 中安装
 
-```sh
-dsh plugin --profile headless add dsh-opencode-go
-```
-
-将以下内容保存为 `headless.patch.yml`，选择默认模型：
-
-```yaml
-- id: agent-default-model
-  config:
-    provider: dsh-opencode-go
-    model: deepseek-v4.1-flash
-```
-
-在 Bash 或 Zsh 中读取 API Key，然后运行任务：
-
-```sh
-read -s OPENCODE_API_KEY
-export OPENCODE_API_KEY
-dsh --profile headless --patch ./headless.patch.yml "你好"
-```
-
-模型 ID 须在当前网关目录中可用。Web 和 Headless 使用各自的 profile，需要分别安装插件。
-
-如需从源码构建并安装本地包：
-
-```sh
-npm ci
-npm run compile
-npm pack
-dsh plugin --profile web add ./dsh-opencode-go-0.1.21.tgz
-```
+1. 打开 **插件 → 添加插件**。
+2. 输入 `dsh-opencode-go`，点击 **安装**。
+3. 安装完成后点击 **立即启用**。
 
-源码开发时显式运行 `npm run compile`；普通用户直接安装预编译产物，无需 `--legacy-peer-deps`。多版本 DSH 兼容性测试使用独立环境，不参与普通安装或构建。Headless 用户将 `web` 换成 `headless`。
+![在 DSH 中安装插件](docs/assets/install-via-dsh.gif)
 
-### 开发与验证
+也可以在添加插件时输入仓库地址：
 
-```sh
-npm run compile       # 更新 lib/，与源码一起提交
-npm test              # 基础功能测试（自动重新构建）
-npm run check:dist    # 检查已提交产物是否与源码一致
-npm run test:compat   # 同一安装包在 9 套独立 DSH 环境中测试
-npm run test:install  # npm / pnpm 无额外构建授权的 Git 安装检查
-npm run verify        # 执行以上全部检查
+```text
+https://github.com/Duskriver/dsh-opencode-go
 ```
 
-兼容性与安装检查会下载依赖，使用系统临时目录并在结束后清理。只检查一个宿主可运行 `npm run test:compat -- v017-rc2`。维护测试版本的方式见[开发与测试说明](docs/development.md)。
-
-## 升级插件
-
-更新 Web profile 中的插件到 npm 最新版本：
+命令行安装：
 
 ```sh
-dsh plugin --profile web update dsh-opencode-go --latest
-```
-
-完成后重启 `dsh web` 并刷新浏览器。Headless 用户将 `web` 换成 `headless`；如果两个 profile 都安装了插件，需要分别升级。
-
-桌面版升级后，请完全退出并重新打开 DeepSeek Harness，以加载更新后的插件代码。
-
-
-
-Headless 或手动配置可在插件的 `config` 中填写：
-
-```yaml
-apiKeyEnv: OPENCODE_API_KEY
-accounts:
-  - id: primary
-    name: 主账号
-    apiKeyEnv: OPENCODE_API_KEY
-  - id: backup
-    name: 备用账号
-    apiKeyEnv: OPENCODE_GO_BACKUP_KEY
-autoSwitch: false
+dsh plugin --profile web add dsh-opencode-go
 ```
 
-分别通过凭据服务或环境变量提供两个引用的 Key。`apiKeyEnv` 指向首选账号；省略 `accounts` 保留旧版单 Key 行为，`accounts: []` 表示已移除全部账号。
+命令行安装后启动或重启 `dsh web`。Web 和 Headless 使用各自的 profile，分别安装和更新。
 
-「账号」卡片默认可收起：折叠时显示账号数量、首选账号、可用数量与统一的刷新时间（当天只显示时刻，悬停给出完整日期时间）。展开后每个账号占一行，行内显示 Key 状态、加粗的 5 小时额度条（12px 通栏，25%/50%/75% 刻度，≥80% 转琥珀、满额转红）与重置倒计时；各列位置固定（手柄 / 名称 / Key 状态 / 额度条 / 百分比 / 重置倒计时 / 详情箭头），账号名过长时省略并悬停显示全名，因此不同长度的账号名不会挪动后面的列；点开行尾箭头可查看周/月额度，以及重命名、替换 Key、删除操作。按住行首手柄上下拖动（或聚焦手柄后按 ↑ / ↓）即可调整顺序，**从上到下依次尝试**：第一行即首选账号，松手后它同时成为新的首选；自动回退开启时按同一顺序尝试其他账号。
+### 开始使用
 
-## 网络代理
+1. 打开 **设置 → OpenCode Go**，填入 OpenCode Go 订阅的 API Key 并保存，或在 **账号** 中添加账号。
+2. 在会话模型选择器中选择 **DSH OpenCode Go** 下的模型。
+3. 开始对话，在输入区旁查看用量；有多个账号时可展开面板切换。
 
-打开 **设置 → OpenCode Go → 高级设置 → 代理地址**，填写代理 URL 后点击 **保存**。例如：
+插件使用独立的模型提供方 **DSH OpenCode Go**。选择 DSH 原生提供的模型不会自动使用本插件的账号切换功能；“常驻”模式仍可展示本插件已配置账号的用量。
 
-```text
-http://127.0.0.1:7890
-socks5://127.0.0.1:1080
-```
+## 模型与设置
 
-也支持 HTTPS 代理，以及 `http://用户名:密码@主机:端口`、`socks5://用户名:密码@主机:端口` 形式的认证代理；用户名和密码中的特殊字符需要 URL 编码。
+### 选择模型与调整参数
 
-保存后，后续对话、模型列表、模型元数据下载和用量查询立即使用新代理，无需重启。清空地址并保存使用默认网络设置；「重置」恢复配置中继承的值。代理连接失败会报告错误，不会自动改为直连。
+在 **可用模型** 中按名称或 ID 搜索，也可以筛选 **近 7 天发布**、**已自定义** 或 **过时模型**。点击 **刷新** 核对最新模型目录。
 
-代理连接由运行 DSH 的机器发起。若 DSH 部署在服务器上，`127.0.0.1` 指服务器自身。无头模式也可以在插件配置中设置 `proxyURL`。
+![模型设置：搜索、分类筛选、显示开关和参数编辑](docs/assets/model-settings.png)
 
-## 订阅用量显示
+- 模型开关控制它是否出现在会话选择器中，修改立即生效。
+- 选中模型可查看目录提供的上下文窗口、最大输出和输入模态，容量覆盖保存后生效，留空使用默认值。
+- 支持思考的模型提供相应开关、强度或 token 预算选项；预算式模型还可添加自定义预算并保存。
 
-在「设置 → OpenCode Go → 高级设置 → 额度显示」中选择并保存：**自动（默认）**仅在选中本插件的 DSH OpenCode Go 模型时显示；**常驻**在使用其他模型（包括宿主自带的 `opencode-go`）时也显示；**关闭**隐藏胶囊并停止轮询。停用 OpenCode Go 后所有模式均隐藏。显示时点击胶囊展开用量面板：首行是当前使用的账号（状态点 + 名称 + 首选标签 + 「切换」），点「切换」后卡片内容变为账号列表（当前账号带勾，↑ / ↓ 或点击选择，Esc 返回额度视图）；这里切换的是"现在用哪个账号的额度"，额度消耗顺序仍由设置页那列顺序决定。三个窗口各占一行（名称、进度条、百分比），重置时间在下方，刷新时间在卡片底部。
+流式回复、思考、工具调用和图片输入取决于模型能力。界面中的输入模态来自在线模型配置；本插件目前仅转换并转发图像附件。
 
-用量每分钟刷新。临时网络或服务错误会保留同一账号的上次数据，并标明刷新失败、更新时间和错误原因；可在用量弹层中立即重试。首次获取失败或鉴权失败时不显示旧额度。模型目录、模型配置和用量的 JSON 请求遇到短暂连接重置时会在原有超时范围内额外重试一次；这不能保证故障中的网络恢复可用。
+### 分组高级设置
 
-![OpenCode Go usage display](image.png)
+高级设置按 **用量与协议**、**连接**、**缓存与超时**、**图片处理** 分组。悬停问号查看说明，可通过 **全部恢复默认** 清除该卡片的自定义覆盖，再保存修改；当前账号选择保持不变。
 
-## 界面语言
+![高级设置：分组配置、提示入口和统一恢复默认](docs/assets/advanced-settings.png)
 
-插件跟随 Harness 的界面语言，提供中文和英文文案，不另存一套语言设置。未手动指定语言时，Web 版按浏览器语言列表匹配中英文（浏览器通常跟随系统）；支持系统语言桥接的桌面版由宿主提供系统语言。没有匹配的语言时使用英文。
+支持 HTTP、HTTPS 和 SOCKS5 代理，保存后用于后续对话、模型目录更新与用量查询。代理运行在 DSH 所在的机器上；远程部署中的 `127.0.0.1` 指服务器自身。
 
-在 Harness 中手动选择的语言优先，切换后插件即时更新，保留未保存的表单内容。模型名称和 ID 保留原名；用量日期和容量数字按当前界面语言格式化。自动语言在启动时识别：Web 版更改浏览器语言后需刷新页面，桌面版更改系统语言后需重启 Harness。
+DeepSeek V4.1 Flash 的 Responses 协议选项为实验性，仅影响新请求，不承诺更低延迟。完整配置与使用说明见[高级使用指南](docs/advanced.md)。
 
-## 模型开关
+截图用于展示界面，具体模型、额度和时间以当前账号与在线目录为准。
 
-在 **设置 → OpenCode Go** 中，每个模型右侧的开关决定它是否出现在会话模型选择器中。开关立即保存，无需再点“保存”；容量和 API Key 的修改仍需保存。普通模型默认开启，过时模型默认关闭。你可以单独开启任意过时模型，也可以关闭普通模型。新出现且未单独配置的模型同样按此规则处理。
+## 更新与常见问题
 
-手动配置时，在插件的 `config` 下添加 `modelVisibility`，使用真实模型 ID 替换示例中的占位符：
+更新到 npm 最新发布版本：
 
-```yaml
-modelVisibility:
-  your-model-id: false
-  your-deprecated-model-id: true
+```sh
+dsh plugin --profile web update dsh-opencode-go --latest
 ```
 
-只有列出的 ID 被显式覆盖。开关只影响模型选择器；已有会话仍可调用网关提供的隐藏模型，设置页也保留完整模型列表。
-
-旧配置中的 `showDeprecatedModels` 和 `visibleModelIds` 不再控制显示状态。请使用逐模型开关或 `modelVisibility`；旧字段可以保留，不会妨碍插件加载。
-
-## 图片数量上限
-
-在「设置 → OpenCode Go → 高级设置」中可以设置 `maxImages`，填写正整数后保存即可生效，无需重启。默认不设置，不限制图片张数；清空或重置会移除用户覆盖，重新继承基础配置（基础配置也未设置时没有张数上限）。
-
-数量按单次请求携带的完整历史统计，包括工具输出里的图片；同一附件出现多次也分别计数。例如设置为 `30` 时，30 张正常发送，31 张会先卸载最旧的 1 张，再继续请求。卸载将图片内容替换为文字占位，原始附件仍保留，但模型在该次请求中看不到被卸载图片的内容。
-
-DSH 0.1.5 的卸载只影响本次请求；DSH 0.1.6 及以上版本通过宿主的图片卸载机制记录卸载状态并重试，调高或清空上限不会自动恢复已卸载的历史图片。现有图片载荷、像素和单图字节预算仍独立生效，可能需要卸载更多图片。`maxImages` 是可选的兼容设置，不会改变上游服务自身的限制。
-
-## 常见问题
-
-### 与宿主的 OpenCode Go 共存及升级迁移
+更新后重启 `dsh web` 并刷新页面；桌面版完全退出后重新打开。Headless 用户将 `web` 换成 `headless`。仓库默认分支可能包含尚未发布到 npm 的修改。
 
-从 0.1.17 起使用独立的 `dsh-opencode-go` provider，模型选择器中显示为 **DSH OpenCode Go**；宿主 pi-ai 的 `opencode-go` 可以同时使用。请在插件设置页配置 API Key，然后选择 **DSH OpenCode Go** 下的模型。0.1.16 及以前版本使用 `opencode-go`，这些版本的 headless 配置也应使用旧标识。
+**为什么没有显示用量？** 默认“自动”模式仅在选择 **DSH OpenCode Go** 模型时显示。请检查插件是否启用、Key 是否配置，以及额度显示模式；使用其他提供方时可选择“常驻”。
 
-升级前保存为 `provider: opencode-go` 的会话、Agent 预设和 headless 默认模型，需要重新选择 **DSH OpenCode Go**，或将 provider 改为 `dsh-opencode-go`。API Key、模型设置和元数据缓存继续沿用。旧会话内容保留；跨 provider 切换时，DSH 会按其规则去除旧适配器的专用回放元数据。
+**查询失败或添加账号中断怎么办？** 用量查询可在面板中重试，或在账号卡片中刷新额度。未成功保存 Key 的新增账号可补填 Key 或删除；账号操作的恢复机制见[高级使用指南](docs/advanced.md#账号操作与保存)。
 
-### 没有出现预期的模型
+**升级后旧会话找不到模型？** 从 `0.1.16` 及更早版本升级时，在旧会话或 Agent 预设中重新选择 **DSH OpenCode Go**；手动配置使用 `provider: dsh-opencode-go`。
 
-先在 **设置 → OpenCode Go** 检查该模型的开关是否开启。过时模型默认关闭，单独打开它的开关后即可出现在会话模型选择器中，无需开启其他全局选项。
+**兼容性范围是什么？** 安装兼容性覆盖十个宿主版本，从 `0.1.5-rc.1` 到 `0.2.1-alpha.1`，后续版本仍需验证。目前明确拒绝 developer 消息、动态工具增删和延迟工具加载，详见[开发与兼容性说明](docs/development.md)。
 
-先确认插件已启用且 API Key 已配置，再刷新设置页中的模型列表。设置页读取或刷新列表时会请求网关 `/models`，并同步 [models.dev 的 OpenCode Go 配置](https://models.dev/api.json)。会话模型选择器遵守目录缓存时长，切换模型开关不会强制重新请求网关。模型的协议、上下文长度、输出上限和图片能力来自在线配置，新模型无需等待本插件或 pi-ai 发布新版本。
-
-网关和在线配置已收录、且使用 Anthropic Messages、OpenAI Chat Completions 或 OpenAI Responses 协议的新模型，在下次设置页刷新或目录缓存到期后即可被发现。设置页刷新会绕过已有缓存，并通知已打开的会话模型选择器使用同一份新目录；直接请求尚未缓存的新模型也会立即重新同步。设置页显示完整模型列表。
-
-网关已公布 ID 但尚无有效协议/能力配置的模型会在设置页标注“配置缺失”，开关保持关闭且不可操作，不进入对话模型选择器，避免一个未配置的模型阻断整个列表；直接调用时会说明原因。配置补齐后，刷新列表即可使用。仅凭模型 ID 无法可靠推断调用方式。上游新增全新协议或协议特例时，仍可能需要适配。
-
-如果在线配置获取失败，没有可用缓存或内置配置的模型会标注“配置暂不可用”，页面会显示配置源错误。请检查运行 DSH 的设备能否访问 `https://models.dev/api.json`，并查看具体错误后刷新重试。已有模型列表在重试期间保留上次的失败提示，成功后自动清除；已配置的模型继续可用。
-
-模型具有推理能力但没有可调节的推理档位时（如 `union-alpha`），仍可正常选择和使用，只是不显示推理强度选项。
-
-MiMo V2.6 Flash 的网关目录尚未列出可调节档位，插件按 OpenCode Go 实测提供 **Off / Low / Medium / High**：默认不发送 `reasoning_effort`，保留网关默认思考；Off 发送 `none`，其余发送对应值。仅对这个已验证的型号和协议补充映射，不扩展到其他 MiMo 型号。Low / Medium / High 已验证可正常请求并返回思考内容，但不保证实际思考量随档位递增。
-
-在线目录中的 effort 列表决定可选强度。仅有 toggle 或 budget 声明时，插件只对已有原生开关或预算协议提供相应控件，不为普通 OpenAI 兼容协议猜测 `off` 或 `high` 参数。明确的空控制列表不会因为模型具有推理能力就自动增加 Off。
-
-提供可调节档位的模型，如果其传输协议在未选择档位时会显式关闭思考（`deepseek`、`zai`、`qwen`、`qwen-chat-template`），还会声明一个默认档位（模型支持 `high` 时用 `high`，否则用它提供的最高档位）。用户未选择档位时 DSH 使用该默认值，因此留空也会带上推理档位，而不是关闭思考。由服务商自行决定的协议不声明默认值，行为不变；显式选择的档位始终优先。
-
-在线配置暂时不可达时，优先复用之前成功获取的配置（包括重启前的磁盘缓存），以 pi-ai 内置配置作为备用。网关目录刷新失败时，已有请求和设置页均保留本次运行中上次成功获取的列表。任一来源刷新失败，设置页都会显示警告、失败原因，以及模型名单和模型配置各自上次成功检查的时间。首次读取网关失败时，不会仅凭元数据缓存生成模型列表。
-
-模型配置自动保存到 `$DSH_HOME/cache/dsh-opencode-go/models.dev.api.json`，未设置 `DSH_HOME` 时位于 `~/.dsh/cache/dsh-opencode-go/models.dev.api.json`。缓存仅包含公共元数据、ETag 和上次成功检查时间，不包含 API Key 或网关模型名单。重启后的普通读取先确认网关名单，再使用磁盘中的配置，同时后台校验元数据；后台完成后同步模型选择器。缓存损坏时重新联网获取，无法写入时仍可使用在线结果。设置页刷新始终等待在线校验，失败会保留旧配置并显示原因，不会把缓存命中标记为在线刷新成功。需要清除磁盘缓存时，可退出 DSH 后删除该文件。
-
-`refreshMinutes` 控制成功刷新后的目录缓存时长。刷新失败后，下一次读取会按 5、10、20、40、60 秒的退避间隔尝试恢复，最长等待间隔为 60 秒；没有读取时不会后台轮询。设置页主动刷新和未知模型的即时发现不受这个间隔限制。取消模型解析或生成时，会立即结束当前调用的目录等待，其他调用仍可继续使用同一次共享刷新。
-
-已验证的模型配置在缓存到期后的 5 分钟内可直接用于生成，同时触发一次共享后台刷新。这个窗口按两种来源各自上次成功检查的时间计算，失败重试不会延长它；超过窗口后，请求等待下一次到期刷新，刷新仍失败时保留已有回退行为。没有磁盘缓存的首次加载、未知模型和手动刷新会等待在线结果。模型名单请求限时 10 秒，体积更大的模型配置下载单独限时 30 秒，并协商 gzip 压缩以减少慢速连接的传输量。若宿主因 HTTP/2 兼容问题返回未解压的 gzip 数据，插件会在同一超时预算内异步解压，原始数据和解压结果均受 16 MiB 限制。模型名单和用量接口继续使用非压缩传输。
-
-同一会话继续、重试以及恢复后的请求沿用宿主保存的会话 ID。分叉和子会话使用各自的 ID，不复用父会话标识；没有会话 ID 的独立请求每次生成随机标识。
-
-## 卸载
-
-从对应 profile 移除插件，再重启应用：
+卸载：
 
 ```sh
 dsh plugin --profile web remove dsh-opencode-go
-# 或
-dsh plugin --profile headless remove dsh-opencode-go
 ```
 
-## 反馈
-
-遇到 bug 或有功能建议请提 issue。
-
-## 许可证
+## 更多文档
 
-[MIT](LICENSE)
+- [高级使用指南：Headless、代理、手动配置与错误诊断](docs/advanced.md)
+- [开发与测试](docs/development.md)
+- [验证记录](docs/verification.md)
+- [问题与建议](https://github.com/Duskriver/dsh-opencode-go/issues)
+- [MIT 许可证](LICENSE)

package/THIRD_PARTY_NOTICES.md

@@ -1,5 +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. Wire protocol implementations remain supplied by `@earendil-works/pi-ai`, installed under the plugin's `opencode-go-pi-ai` npm alias.
+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.
+
+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.

package/docs/advanced.en.md

@@ -0,0 +1,137 @@
+# OpenCode Go advanced guide
+
+[Back to README](../README.en.md) · [简体中文](advanced.md)
+
+## Advanced usage
+
+### Headless mode
+
+Install the plugin:
+
+```sh
+dsh plugin --profile headless add dsh-opencode-go
+```
+
+Save this as `headless.patch.yml`:
+
+```yaml
+- id: agent-default-model
+  config:
+    provider: dsh-opencode-go
+    model: deepseek-v4.1-flash
+```
+
+Enter your key in Bash or Zsh, then run a task:
+
+```sh
+read -s OPENCODE_API_KEY
+export OPENCODE_API_KEY
+dsh --profile headless --patch ./headless.patch.yml "Hello"
+```
+
+Replace `model` with an available model ID from Settings. See [examples/headless.patch.yml](../examples/headless.patch.yml).
+
+### Network proxy
+
+Open **Settings → OpenCode Go → Advanced settings → Proxy address**, enter a URL, and save. Examples:
+
+```text
+http://127.0.0.1:7890
+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
+
+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.
+
+To configure the experiment manually:
+
+```yaml
+- id: opencode-go
+  config:
+    protocolOverrides:
+      deepseek-v4.1-flash: openai-responses
+```
+
+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
+```
+
+Keep the options you need and supply the corresponding keys through DSH credentials or environment variables. The first entry in `accounts` is current; the remaining entries are tried in order. The legacy `apiKeyEnv` reference must match the first entry. Manual and automatic switches move the target account first while preserving the other accounts' relative order. Existing configurations retain their selected account by moving it first.
+
+| Option | Purpose |
+| --- | --- |
+| `baseURL` | Shared OpenCode Go gateway prefix for model discovery, inference and usage; defaults to `https://opencode.ai/inference/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 |
+
+Request paths are appended to `baseURL`: `GET /models` lists models, `POST /models/{model}:streamGenerateContent` sends Gemini requests, and `GET /usage` reads usage. A working listing does not verify every inference route. Reading the legacy official base `https://opencode.ai/zen/go/v1` migrates it to the new address for model discovery, every inference protocol and usage requests. Settings writes also store the new address, so operation does not depend on the legacy gateway remaining available. Custom gateways retain their configured addresses.
+
+Image offloading keeps the original attachment and replaces the old image in the request with a text placeholder. Raising the limit does not automatically restore previously offloaded images.
+
+Image count overflow is detected before attachment reads. Preparation shares four execution slots and at most 32 queued tasks within the plugin module, and stops scheduling images when known encoded bytes exceed the payload cap. Active image attempts share a 128 MiB budget for prepared raw data plus base64 payloads; this is not a process memory limit. Queue or shared-budget overflow returns `IMAGE_RESOURCE_BUSY`; retry after another request completes. Count and byte limits may require successive host offload retries.
+
+A cold catalog outage reports `DISCOVERY_FAILED`; a warm catalog retains previously verified models. Only an explicit empty gateway listing clears membership. A partially malformed listing keeps its valid models and reports the ignored row count in settings and logs. Ordinary advanced form settings commit in one revision-checked batch. Credentials use a separate service; failed credential drafts remain, and retry submits only uncommitted parts.
+
+### Export error diagnostics
+
+To investigate a failed request, set a diagnostics directory before starting DSH:
+
+```sh
+export DSH_OPENCODE_GO_DEBUG_DIR=/tmp/dsh-opencode-go-debug
+dsh web
+```
+
+Windows PowerShell:
+
+```powershell
+$env:DSH_OPENCODE_GO_DEBUG_DIR = "$env:TEMP\dsh-opencode-go-debug"
+dsh web
+```
+
+Reproduce the failure to get a JSON file path in the error message. The record contains the model, request parameter summaries, HTTP status, upstream log and route IDs, and the error response, for use in an [issue report](https://github.com/Duskriver/dsh-opencode-go/issues). Review the returned error content before sharing. Clear the environment variable and restart DSH to disable diagnostics.
+
+DSH debug logs contain a call ID and each attempt's stage timings, HTTP status, upstream request ID, time to first output and error code, including stream failures after HTTP 200. Image attempts also report aggregate queue waiting and peak resource occupancy. Error files carry the same call ID and attempt number for correlation. These summaries exclude prompts, keys, proxy addresses and raw session IDs.
+
+
+## Account operations and saving
+
+If adding or removing an account is interrupted by closing the page or losing the connection, the host resumes recovery at startup or after settings and credential updates. An addition whose key was never stored stays visible so you can replace its key or remove it. Recovery preserves a current-account choice made in the meantime.
+
+Reset all to defaults in advanced settings removes overrides at the current layer and restores inherited values; save to apply the reset. It does not remove accounts or keys, or clear model limit overrides.

package/docs/advanced.md

@@ -0,0 +1,135 @@
+# OpenCode Go 高级使用指南
+
+[返回 README](../README.md) · [English](advanced.en.md)
+
+## 高级用法
+
+### Headless 模式
+
+安装插件：
+
+```sh
+dsh plugin --profile headless add dsh-opencode-go
+```
+
+将以下内容保存为 `headless.patch.yml`：
+
+```yaml
+- id: agent-default-model
+  config:
+    provider: dsh-opencode-go
+    model: deepseek-v4.1-flash
+```
+
+在 Bash 或 Zsh 中输入 Key 后运行任务：
+
+```sh
+read -s OPENCODE_API_KEY
+export OPENCODE_API_KEY
+dsh --profile headless --patch ./headless.patch.yml "你好"
+```
+
+将 `model` 换成设置页中可用的模型 ID。示例文件见 [examples/headless.patch.yml](../examples/headless.patch.yml)。
+
+### 网络代理
+
+在 **设置 → OpenCode Go → 高级设置 → 代理地址** 中填写并保存，例如：
+
+```text
+http://127.0.0.1:7890
+socks5://127.0.0.1:1080
+```
+
+支持 HTTP、HTTPS、SOCKS5 和带用户名、密码的代理 URL。保存后，后续对话、模型目录更新和用量查询使用新代理。代理运行在 DSH 所在的机器上；远程部署中的 `127.0.0.1` 指服务器自身。
+
+### 实验性协议与手动配置
+
+在 **高级设置 → DeepSeek V4.1 Flash 协议** 中可选择 **Responses（实验性）** 并保存，便于比较同一模型的不同协议。默认 **自动** 跟随模型目录；改回自动即可恢复。选择只影响新请求，不会切换已准备或正在执行的调用，也不会在协议错误后自动改用另一协议。
+
+目前仅支持 `deepseek-v4.1-flash` 的 Responses 覆盖，沿用当前账号、代理、会话标识与用量处理。[issue #45](https://github.com/Duskriver/dsh-opencode-go/issues/45) 报告了更低延迟，但它不是网关的稳定性能承诺，也不能据此确认底层服务商；是否更快请以自己的测试为准。无需覆盖时省略以下配置：
+
+```yaml
+- id: opencode-go
+  config:
+    protocolOverrides:
+      deepseek-v4.1-flash: openai-responses
+```
+
+将该模型的值设为 `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
+```
+
+按需保留配置项，并通过 DSH 凭据服务或环境变量提供对应的 Key。`accounts` 的首项为当前账号，其余账号按顺序备用；`apiKeyEnv` 保留为兼容引用，应与首项一致。手动或自动切换都会将目标账号移至首位，保持其他账号的相对顺序。旧配置中当前账号不在首位时，会保留原来的选择并将它前移。
+
+| 配置项 | 用途 |
+| --- | --- |
+| `baseURL` | 模型列表、对话发送和额度查询共用的 OpenCode Go 网关前缀，默认 `https://opencode.ai/inference/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 毫秒；预先准备的调用从发送时计时 |
+
+`baseURL` 后会按用途拼接路径：模型列表使用 `GET /models`，Gemini 发送使用 `POST /models/{model}:streamGenerateContent`，额度查询使用 `GET /usage`。列表可访问不代表所有推理接口都可用。读取旧官方地址 `https://opencode.ai/zen/go/v1` 时，插件会统一迁移为新地址，模型列表、所有协议的发送和额度查询都使用新网关；保存设置时也会写入新地址。因此运行不依赖旧网关继续服务。自定义网关仍按配置发送。
+
+图片卸载会保留原始附件，并将请求中的旧图片替换为文字占位；调高上限不会自动恢复已卸载的历史图片。
+
+图片数量超限会在读取附件前返回卸载请求；图片准备在同一插件模块内共享四个执行名额和最多 32 个等待名额，精确字节超限时停止安排剩余图片。正在发送的图片请求共享 128 MiB 的已准备原始数据与 base64 预算；这不是进程总内存上限。排队或共享预算超限会返回 `IMAGE_RESOURCE_BUSY`，可在其他请求结束后重试。数量与字节限制可能需要宿主分次卸载后重试。
+
+首次查询目录失败会报告 `DISCOVERY_FAILED`；已有目录时保留之前确认过的模型。网关明确返回空列表才会清空目录。列表中仅部分行格式错误时，仍可使用有效模型，设置页与日志会提示被忽略的行数。高级表单的普通配置项一次提交并检查版本；凭据由独立服务保存，凭据保存失败时保留其草稿，重试只提交未成功的部分。
+
+### 导出错误诊断
+
+需要排查请求失败时，在启动 DSH 前设置诊断目录：
+
+```sh
+export DSH_OPENCODE_GO_DEBUG_DIR=/tmp/dsh-opencode-go-debug
+dsh web
+```
+
+Windows PowerShell：
+
+```powershell
+$env:DSH_OPENCODE_GO_DEBUG_DIR = "$env:TEMP\dsh-opencode-go-debug"
+dsh web
+```
+
+复现后，错误信息会给出 JSON 文件路径。记录包含模型、请求参数摘要、HTTP 状态、上游日志与路由编号及错误响应，便于提交 [问题反馈](https://github.com/Duskriver/dsh-opencode-go/issues)。分享前检查服务返回的错误内容；清空环境变量并重启 DSH 即可关闭诊断。
+
+DSH debug 日志另有每次发送的调用编号，以及各次尝试的阶段耗时、HTTP 状态、上游请求编号、首次输出等待时间与错误码，包含 HTTP 200 后的流中断；图片请求还记录排队累计等待与资源占用峰值。错误文件带有相同调用编号与尝试序号，便于关联排查。这些摘要不记录提示词、Key、代理地址或原始会话编号。
+
+
+## 账号操作与保存
+
+新增或删除账号中途关闭页面、断开连接时，宿主会在后续启动或设置、凭据更新时继续恢复。未能写入 Key 的新增账号会保留在列表，可补填 Key 或删除；恢复不会覆盖期间手动选择的当前账号。
+
+高级设置的“全部恢复默认”会清除当前层的自定义覆盖，恢复继承值；需要保存后才生效。它不删除账号或 Key，也不清除模型容量覆盖。