📦 @goodandready/dsh-opencode-provider
|
⭐ 如果您喜欢这个插件,请在 GitHub 上为它点亮 Star — 这能让我知道插件对您有用,并鼓励我继续开发和维护它。
🐛 如果您发现 Bug 或希望增加功能,请使用任意语言在 GitHub 上提交 Issue — 我会评估您的建议,并在后续版本中实现有价值的改进。 |
面向 DeepSeek Harness(dsh)的 OpenCode / OpenCode Go 提供商插件。
插件注册两个原生 LLM 路由:
| 路由 | 产品 / 方案 | 基础接口 | 特性说明 |
|---|---|---|---|
opencode-direct | OpenCode Console / Zen | https://opencode.ai/inference | 按量计费(pay-as-you-go) |
opencode-go-direct | OpenCode Go / Go Plus | https://opencode.ai/inference/go | 订阅专属,含 5小时/每周/每月配额估算 |
密钥在每次调用时动态解析:在设置中或环境文件中更换凭据无需重启服务器即可立即生效。
-direct 后缀用于避免与内置 llm-pi-ai 已声明的 opencode / opencode-go 冲突。
重复 id 会触发 DUPLICATE_DIRECTORY,导致核心丢弃内置目录、其他提供商消失并禁用添加按钮。
旧会话继续使用内置路由;要使用本插件的账户、配额、回退和遥测,请选择
OpenCode (plugin) 或 OpenCode Go (plugin)。
架构示意
graph LR
subgraph DSH["DeepSeek Harness 核心"]
Agent["DSH 智能体 / 聊天"]
Creds["凭据服务 / auth.json"]
end
subgraph Plugin["dsh-opencode-provider"]
Router{"路由选择器"}
Pool["多账户连接池<br/>(智能轮换与冷却)"]
Heatmap["遥测与请求热力图<br/>(5小时 / 周 / 月)"]
subgraph Transports["4 种底层传输协议 (Wire Transports)"]
T1["OpenAI Chat"]
T2["Anthropic Messages<br/>(Thinking Signatures)"]
T3["OpenAI Responses"]
T4["Google GenAI<br/>(thoughtSignature 重放)"]
end
end
subgraph OpenCode["OpenCode 网关"]
Console["opencode-direct (Console / Zen)"]
Go["opencode-go-direct (Go / Go Plus)"]
end
Agent --> Router
Creds -.-> Pool
Router -->|opencode-direct| Pool
Router -->|opencode-go-direct| Pool
Pool --> Heatmap
Pool --> Transports
T1 & T2 & T3 & T4 --> Console & Go
功能全貌
- 4 种原生传输协议,按模型自动优选:
- OpenAI Chat Completions(DeepSeek、GLM、Kimi、MiMo、LongCat、Hy3、Step 等)。
- Anthropic Messages(Claude、MiniMax、Qwen)。
- OpenAI Responses(GPT、Grok、Muse)。
- Google Generative AI(Gemini)。
- 完整数据类型流式支持:文本、思考推理(reasoning)、流式工具调用(tool calls)、用量统计与 finish reasons。
- 多模态图像传输:通过持久化附件服务,按协议原生转换与传输;文件转为 DSH 确定性 handle 文本(由 harness 提供只读路径),不传 inline 字节。
- 工具结果中的图像在 Anthropic、OpenAI Responses 和 Google 中内联;OpenAI Chat 因消息格式限制保留文本占位符。
- 账户引导:Import all from auth.json 将所有 OpenCode 密钥导入独立 credential ref 并添加账户;Check all accounts 刷新每个账户的配额与健康状态。
- 协议特定元数据重放:
- Anthropic 思考签名(
thinking signatures)。 - Google 历史函数调用中的
thoughtSignature。
- Anthropic 思考签名(
- 多账户智能无缝轮换:
- 在生成流开始前,遇到 401/403/429 或配额用尽响应(400/402/403/429)自动重试下一个账户。
- 最多 20 个账户,支持拖拽调整优先级。无效密钥冷却 5 分钟,超额冷却 10 分钟(或遵循
Retry-After),速率限制冷却 60 秒。上次成功服务的账户会提升到首位并在重启后保留。 - 正在流式传输中的请求不会被打断,下一个请求会自动使用下一个可用密钥。
- 侧边栏配额卡片:Auto / Always / Off 模式;
Auto在存在 Go 用量时显示,Off停止后台轮询。 - 多账户额度与健康监控:每行独立展示 5 小时、每周与每月使用情况,活跃账户驱动侧边栏与配额面板。
- 每账户预计可用时长:按各窗口的平均消耗速度估算耗尽时间,并标记在重置前最先耗尽的窗口;API 仅提供当前百分比与重置时间,因此为近似值。
- 模型 ➔ 账户路由规则:支持 Glob 通配符(如
*free*、deepseek-*)将模型优先绑定至特定账户,其他账户保留为备用。 - 按模型覆盖:可在设置中为每个模型修改上下文窗口和输出上限;
0表示该模型省略输出上限。 - 配额回退:在设置中选择免费模型;Go 返回配额错误时,同一请求通过 Console/Zen 重试一次。若回退也失败,返回原始配额错误。
- 会话粘性账户:同一会话优先使用上次成功的账户,并通过本地
sticky.json跨重启保留(仅哈希后的 session id 和密钥指纹);显式模型规则、固定账户和配额回退优先。 - 路由追踪:配额面板显示最近的账户/模型决策(
rule、sticky、rotation、quota-fallback),不记录提示词或密钥。 - 按账户请求统计:请求日志记录
ok、latencyMs、ttftMs和error;热力图表格显示每个账户的请求数、错误数及平均延迟/TTFT。 - 本地时间请求热力图:星期×小时交互式热力图,排除系统心跳与重复记录,可按模型或账户过滤,仅保存
{at, provider, model, purpose, account, reason, ok, latencyMs, ttftMs, error}元数据,不保存任何提示词与回复。 - 稳定的
x-opencode-session标头:根据 DSH 会话 ID 派生,确保重试与连续对话复用相同的网关路由键。 - 实时模型目录:自动从
/v1/models同步,并以models.dev生成文件作为回退。 - 代理:一个实时
proxyUrl设置即可让推理、模型目录和额度检查走 HTTP、HTTPS 或 SOCKS5;地址变化前复用 dispatcher。proxyUsername与凭据服务中的密码可为 HTTP 和 SOCKS5 启用 Basic 认证,密码不会返回浏览器。 - 路由开关:可独立启用或禁用 Console/Zen 与 Go/Go Plus 路由;禁用的路由会从选择器移除并拒绝请求,至少保留一个路由。
- Go 订阅额度估算:每月美元额度以及 5 小时、每周和每月的估算请求次数。
/opencode斜杠指令:快速查询状态、配额、账户、模型及执行联通性测试。- TUI 设置:
/settings → OpenCode支持密钥、端点、allowlist、活动账户、回退模型、粘性路由和超时。 - Web UI 一键更新:设置页集成版本比对与一键热更新按钮。
- MCP 工具上限防护:在大规模 MCP 工具集达到 128 工具限制时,优先保留 DSH 核心系统工具。
安装指南
从源码构建与打包:
npm install
npm run build
npm pack
通过**打包文件 (.tgz)**安装:
dsh plugin --profile web add /absolute/path/to/goodandready-dsh-opencode-provider-<version>.tgz
# DSH 桌面端:
dsh plugin --profile desktop add /absolute/path/to/goodandready-dsh-opencode-provider-<version>.tgz
# 或从 npm 安装已发布版本:
dsh plugin --profile web add @goodandready/dsh-opencode-provider@<version>
安装完成后重启 dsh 或 DSH 桌面端,在模型选择器中选择 OpenCode (plugin) 或 OpenCode Go (plugin) 即可。
配置示例
- id: llm-opencode
name: "@goodandready/dsh-opencode-provider"
config:
apiKeyEnv: OPENCODE_API_KEY # 环境变量或 DSH 凭据名
# apiKey: oc_sk_... # 仅本地调试,严禁提交代码库
openCodeAuthEntry: opencode-go
requestTimeoutMs: 300000
streamIdleTimeoutMs: 300000
visibleModels: []
modelTransports: {}
accounts:
- label: Go #2
apiKeyEnv: OPENCODE_API_KEY_2
activeAccount: '' # 固定指定活跃账户名称
密钥解析顺序
- DSH 配置中的
config.apiKey。 - DSH 凭据服务中由
apiKeyEnv指定的凭据。 ~/.local/share/opencode/auth.json中的openCodeAuthEntry项(默认opencode-go)。- 进程环境变量或
$DSH_HOME/.env。
模型到账户路由规则
modelAccountRules:
- pattern: "*free*"
account: "free"
- pattern: "your-provider-*"
account: "go"
常用指令
/opencode status # 查看账户健康状态、配额与路由规则
/opencode usage # 查看当前配额窗口
/opencode accounts # 账户列表与 5h/周/月消耗
/opencode models # 模型列表与 Go 方案限制
/opencode rules # 模型到账户规则
/opencode test [model] # 发送最小化测试请求
在 设置 → OpenCode → /opencode 命令语言 中选择 中文 即可切换输出语言,默认英语。
引擎矩阵
npm run test:engine -- <candidate.tgz> 使用 engines.dsh 与 dsh.compatibility.dshReleases 校验不可变的已构建包,并检查只打包生产文件。该命令只读:不安装 DSH、不启动运行时、不解压归档、不修改其他插件,也不需要清理。兼容性执行在批准的 MiniPC 测试环境上使用已发布候选包完成,绝不使用 worktree 路径,也不强制结束进程或递归删除。
0.5.22–0.5.36 新增
- 代理认证:
proxyUsername与凭据服务中的密码支持 HTTP/HTTPS/SOCKS5,密码不会返回浏览器。 - 路由开关:Console/Zen 与 Go/Go Plus 可独立启停;禁用路由会从选择器移除并拒绝请求。
- 按模型覆盖:上下文、输出上限、传输;
0表示不发送输出上限。 - 分析与热力图:请求、令牌、TTFT、延迟、模型/日期/会话及星期×小时网格;只读取本地数值元数据。
- 配额模式 Auto/Always/Off、粘性路由、
autoSwitch、账户切换提示与更新卡片。 - Admin token 用于 LAN/Web profile;通过代理且未配置 token 的请求将被拦截 (401 fail-closed)。
安全规范
- 同源检查用于防御 CSRF,并非身份认证。在配置文件(
adminToken)或OPENCODE_ADMIN_TOKEN中设置管理员令牌后,所有/dsh-opencode/*路由都要求x-opencode-token或Authorization: Bearer;设置界面会要求输入一次并保存在当前浏览器。未设置令牌时 Loopback 客户端可用,LAN 客户端返回 401。 npm audit仍报告zod < 4.6.6(GHSA-mrhx-c7xc-m3w5):@deepseek-ai/dsh-*0.2.2-rc.1 固定使用 zod 4.4.3。目前没有使用 4.6.6 的 DSH 0.2.2 版本;本插件不打包 zod,也不使用强制 override。待上游 DSH 更新后重新审计。- 密钥冷却状态通过 SHA-256 哈希指纹持久化,本地日志不保存提示词与明文密钥。
限制
- 文件附件以 DSH 的文本句柄转发,而不是内联字节。工具结果中的图片在 Anthropic、OpenAI Responses 与 Google 上内联;OpenAI Chat 使用文本占位符。
- 配额接口 (
/zen/go/v1/usage) 是非官方接口,可能变更;聊天不依赖它。 - 费用只由 DSH 原生指示器显示,插件不额外添加 composer 费用标签。
- 自动更新需要运行时暴露 DSH CLI 入口;没有入口时卡片只显示当前/最新版本并指向插件管理器。
- 订阅请求数是 OpenCode 公布的估算值,不是强制配额;最终以网关为准。
- “按模型用量”聚合本地 projection 缓存,并把整个会话归到最后使用的模型;切换过模型的会话是近似值。不会读取提示词或标题。
opencode-direct(Console) 路由没有按模型限额;主要目标是 Go。
许可证
MIT © GooDAnDReaDY。详见 LICENSE 与 NOTICE。