dsh-opencode-compat

Readme

# dsh-opencode-compat

[English](README.en.md)

DeepSeek Harness 的独立 Cordis / DSH bundle 插件，为 OpenCode Zen 请求提供会话格式、客户端版本头和 Muse reasoning 回传兼容处理。无需修改 `node_modules`，不提供模型、密钥或额度。

> 社区兼容方案，非 DeepSeek / OpenCode 官方插件。客户端身份头会被改为配置的 OpenCode 版本；上游可能改变校验或拒绝第三方使用。插件不保证免费额度、地区可用性或服务条款允许的接入范围。

## 安装

要求 Node.js 22+、DSH（开发验证基线：CLI 0.1.5-rc.1，pi-ai 0.85.1）。

```powershell
dsh plugin --profile web add github:dooooling/dsh-opencode-compat#v0.1.1
dsh web
```

安装前先 Ctrl+C 停止正在运行的 DSH。包直接包含可执行 ESM，无 prepare/build 脚本，不需要允许安装构建脚本。生产使用可将 tag 替换为经过审阅的完整 commit SHA。

已有提供方配置继续生效。Muse 必须选择 `openai-responses` 协议；插件不会将 Chat Completions 请求自动翻译成 Responses。可以为 Muse 单独添加路由，保留其他模型原来的协议：

```yaml
# ~/.dsh/settings.yaml：合并到已有 providers，不要覆盖整个文件
llm-pi-ai:
  providers:
    opencode-muse:
      apiKeyEnv: OPENCODE_API_KEY
      api: openai-responses
      baseURL: https://opencode.ai/zen/v1
      models:
        - id: muse-spark-1.3-contributor-free
```

凭据仍由 DSH 管理。插件不读取凭据文件、不记录请求正文或密钥、不修改模型列表和默认模型。

## 配置

默认启用身份头、reasoning 和免费层兼容处理。需要自定义时，在 `~/.dsh/profiles/web/cordis.patch.yml` 添加以下覆盖（已有内容应合并）：

```yaml
- id: opencode-compat
  config:
    enabled: true
    clientVersion: 1.18.31
    rewriteClientHeaders: true
    stripMuseReasoning: true
    completeFreeTierFingerprint: true
```

| 选项 | 默认值 | 含义 |
|---|---|---|
| enabled | true | 启用插件 |
| clientVersion | 1.18.31 | User-Agent 中的版本，校验 >= 1.17.0；不是本机版本检测 |
| rewriteClientHeaders | true | 转换会话 ID，设置 `User-Agent: opencode/<version>` |
| stripMuseReasoning | true | 从 Muse Responses 请求删除加密 reasoning include 和历史 reasoning 条目 |

会话来源依次为 `x-opencode-session`、`session_id`、`x-session-id`、`x-client-request-id`、正文 `prompt_cache_key`。缺少全部来源时不生成随机 ID，也不改客户端身份。DSH/pi-ai 的会话请求头提供了正常来源。外部自定义调用若将 request ID 用作每次请求的新 ID，不应依赖该来源维持会话。

原生 `ses_` 格式保持不变；其他 ID 用带命名空间的 SHA-256 确定性映射为 `ses_` + 26 位小写十六进制。不同会话不会共用一个固定 ID，同一会话重启后保持一致。

## 作用范围与限制

- 仅处理 HTTPS `opencode.ai` 默认端口的 POST 请求，路径限定为 `/zen/v1/` 或 `/zen/go/v1/` 下的 `responses`、`chat/completions`、`messages`。
- 全进程 `globalThis.fetch` 包装：同一 DSH 进程内所有匹配请求都会受到影响，无法按 Cordis 服务隔离。每进程只能加载一个实例。
- 不影响模型列表查询、其他域名、GET、其他端口；不修改鉴权。Node `dispatcher` 等扩展选项、取消信号和响应流保留。
- 仅 JSON Muse Responses 请求执行 reasoning 过滤：整个 `type: reasoning` 条目（包括摘要）被移除；普通消息、工具调用、工具结果保留。磁盘历史不删除，服务端仍可能返回 encrypted reasoning。
- 卸载后恢复 fetch；若其他插件后装了 fetch 包装，不覆盖它，旧包装变成透明转发。配置热重载会释放旧实例。
- 捕获了旧 fetch 引用、使用独立 HTTP 客户端或显式自定义 fetch 的适配器可能绕过插件。单次生成成功不代表多轮工具任务都正常。
- 不关闭 TLS 验证、不自动切换代理、不重试付费请求、不解决额度或地区限制。

### 从手工补丁迁移

插件独立工作，不需要旧补丁。旧会话头补丁和 reasoning 过滤通常是幂等的，但应在备份后恢复对应依赖原文件，并重启验证。插件不会自动还原用户的文件，以免覆盖其他修改。包管理器升级可能恢复依赖文件；插件本身仍由 profile bundle 加载。

## 卸载

```powershell
dsh plugin --profile web remove dsh-opencode-compat
```

重启 DSH。此操作不撤销曾经手工改过的其他依赖文件。

## 验证与开发

```powershell
npm ci
npm run check
npm test
npm pack --dry-run
```

测试覆盖精确域名/路径范围、Request 与 init、取消信号、dispatcher、流原样返回、会话隔离、工具历史保留、异常 JSON、卸载和真实 Cordis 生命周期。CI 在 Windows/Linux、Node 22/24 上执行离线测试，不调用模型服务。

错误应按原始响应排查：`MissingSessionID` 检查会话来源；`FreeTierError` 检查上游策略与版本兼容；429 是额度/限流；Muse 500 检查是否错用 Chat Completions；`encrypted_content` 检查过滤是否实际经过此 fetch。DSH 某些版本将多种 AUTH 错误概括为“API 密钥无效”，请查看原始日志。

## 参考与状态

- [DSH bundle 规范](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/develop/basic/publish.md)
- [9router 同类错误 #4101](https://github.com/decolua/9router/issues/4101)、[修复提案 #4105](https://github.com/decolua/9router/pull/4105)
- [oc2api 修复提案 #2](https://github.com/zhuweiyou/oc2api/pull/2)
- [Muse 协议路由问题](https://github.com/FishBottle7/opencode2dsh/issues/7)

2026-09-17 的社区报告是兼容规则的依据，不是上游协议保证。本项目独立实现上述思路，MIT 许可。

## v0.1.1 免费层兼容

参考 [9router #4132](https://github.com/decolua/9router/pull/4132)，默认启用 `completeFreeTierFingerprint: true`：仅对 /zen/v1/responses 与 /zen/v1/chat/completions 的匿名或 Bearer public 请求，且模型名以 -free 结尾或为 big-pickle，补齐缺少的 bash、glob、grep、read 工具声明，并启用上游流式响应。已有同名工具及其参数完整保留。Go、付费密钥和 messages 接口不应用这项新修复。

调用方原本请求 JSON 时，插件收集 SSE 并恢复 JSON；流式调用直接返回原始响应流。非流式请求因此需要等待上游完成，并在内存中保存结果。HTTP 错误保持原样，流中错误和不完整响应会显式报错。

**补充的是兼容占位声明，不是可执行工具。** 声明明确要求模型不要调用；插件不将 bash 映射到 PowerShell，也不执行命令。如果模型仍调用占位工具，DSH 可能报告工具不存在；完整工具执行兼容尚未验证。需要关闭时，在插件 config 中设置 `completeFreeTierFingerprint: false`。

更新：停止 DSH，执行上面的 v0.1.1 安装命令并重启。v0.1.0 标签不变。