@goodandready/dsh-opencode-provider

中文文档
0.5.46发布于 2026/11/17MITTypeScriptES Module近 30 天下载 9380

OpenCode / 为 DeepSeek Harness (dsh) 提供的 OpenCode Go LLM 插件 .

中文使用文档
文档目录13 节
  1. 面向 DeepSeek Harness 的 OpenCode Console 与 OpenCode Go 提供商插件
  2. 架构示意
  3. 功能全貌
  4. 安装指南
  5. 配置示例
  6. 密钥解析顺序
  7. 模型到账户路由规则
  8. 常用指令
  9. 引擎矩阵
  10. 0.5.22–0.5.36 新增
  11. 安全规范
  12. 限制
  13. 许可证

📦 @goodandready/dsh-opencode-provider

面向 DeepSeek Harness 的 OpenCode Console 与 OpenCode Go 提供商插件

GoodAndReady 插件展厅 npm 版本 许可证

⭐ 如果您喜欢这个插件,请在 GitHub 上为它点亮 Star — 这能让我知道插件对您有用,并鼓励我继续开发和维护它。

🐛 如果您发现 Bug 或希望增加功能,请使用任意语言在 GitHub 上提交 Issue — 我会评估您的建议,并在后续版本中实现有价值的改进。

面向 DeepSeek Harness(dsh)的 OpenCode / OpenCode Go 提供商插件。

插件注册两个原生 LLM 路由:

路由产品 / 方案基础接口特性说明
opencode-directOpenCode Console / Zenhttps://opencode.ai/inference按量计费(pay-as-you-go)
opencode-go-directOpenCode Go / Go Plushttps://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。
  • 多账户智能无缝轮换:
    • 在生成流开始前,遇到 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: ''            # 固定指定活跃账户名称

密钥解析顺序

  1. DSH 配置中的 config.apiKey。
  2. DSH 凭据服务中由 apiKeyEnv 指定的凭据。
  3. ~/.local/share/opencode/auth.json 中的 openCodeAuthEntry 项(默认 opencode-go)。
  4. 进程环境变量或 $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。

版本与发布记录

@goodandready/dsh-opencode-provider 共发布 43 个版本,首次发布于 2026/10/20;过去 12 个月发布了 43 个版本。

版本发布日期距今
0.5.46latest2026/11/17今天
0.5.452026/11/16今天
0.5.442026/11/115 天前
0.5.432026/11/106 天前
0.5.422026/11/097 天前
0.5.362026/11/0611 天前

关于 @goodandready/dsh-opencode-provider 的常见问题

@goodandready/dsh-opencode-provider 是什么?

OpenCode / 为 DeepSeek Harness (dsh) 提供的 OpenCode Go LLM 插件 .

如何安装 @goodandready/dsh-opencode-provider?

在项目目录运行 npm install @goodandready/dsh-opencode-provider,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:react(^18.2.0)、@deepseek-ai/cordis(>=4.0.5 <5)、@deepseek-ai/dsh-llm(>=0.2.1-rc.2 <0.2.3-0 || >=0.2.2-0 <0.2.3-0)、@deepseek-ai/schemastery(>=3.18.5 <4)、@deepseek-ai/dsh-commands(>=0.2.1-rc.2 <0.2.3-0 || >=0.2.2-0 <0.2.3-0)、@deepseek-ai/dsh-settings(>=0.2.1-rc.2 <0.2.3-0 || >=0.2.2-0 <0.2.3-0)、@deepseek-ai/dsh-attachment(>=0.2.1-rc.2 <0.2.3-0 || >=0.2.2-0 <0.2.3-0)、@deepseek-ai/dsh-credentials(>=0.2.1-rc.2 <0.2.3-0 || >=0.2.2-0 <0.2.3-0)、@deepseek-ai/dsh-client-locale(>=0.2.1-rc.2 <0.2.3-0 || >=0.2.2-0 <0.2.3-0)、@deepseek-ai/dsh-host-webserver(>=0.2.1-rc.2 <0.2.3-0 || >=0.2.2-0 <0.2.3-0)、@deepseek-ai/dsh-client-ui-slots(>=0.2.1-rc.2 <0.2.3-0)、@deepseek-ai/dsh-client-ui-renderer(>=0.2.1-rc.2 <0.2.3-0 || >=0.2.2-0 <0.2.3-0)、@deepseek-ai/dsh-client-ui-settings(>=0.2.1-rc.2 <0.2.3-0 || >=0.2.2-0 <0.2.3-0)、@deepseek-ai/dsh-launch-environment(>=0.2.1-rc.2 <0.2.3-0 || >=0.2.2-0 <0.2.3-0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@goodandready/dsh-opencode-provider 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@goodandready/dsh-opencode-provider 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@goodandready/dsh-opencode-provider 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=22。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@goodandready/dsh-opencode-provider 可以商用吗?

@goodandready/dsh-opencode-provider 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@goodandready/dsh-opencode-provider 的下载量有多少?

根据 npm 官方下载统计,@goodandready/dsh-opencode-provider 在 2026/10/17 – 2026/11/15 这 30 天内被下载 9,380 次,日均约 313 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@goodandready/dsh-opencode-provider 还在维护吗?

最新版本 0.5.46 发布于 2026/11/17(今天);至今共发布 43 个版本,其中过去 12 个月发布了 43 个;首次发布于 2026/10/20。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。