dsh-opencode-go-catalog: A Real-Time Maintained OpenCode Go Model Catalog for DeepSeek Harness

前言¶

DeepSeek Harness (DSH) 的内置 opencode-go 路由依赖 @earendil-works/pi-ai 中的静态目录，不会自动更新。当上游依赖未更新时，新模型（如 Step 5 或 Cat Jam）将不会出现在模型选择器中。

dsh-opencode-go-catalog 插件通过维护三个协议分离的兄弟路由来解决这个问题。它从不触碰内置的 opencode-go 路由，而是通过 settings.mutate 接口管理 opencode-go-extras、opencode-go-responses 和 opencode-go-messages 这三个路由。模型列表会从实时名录（roster）和文档接口（docs）中重建，无需人工干预。

核心功能¶

实时维护目录：从 https://models.opencode.ai/api.json（注册表）和 https://opencode.ai/zen/go/v1/models（名录）获取最新状态。
协议分离路由：将模型按协议分为三类，避免因协议不匹配导致的 500 或 401 错误。
- opencode-go-extras：使用 openai-completions 协议。
- opencode-go-responses：使用 openai-responses 协议。
- opencode-go-messages：使用 anthropic-messages 协议。
自动同步与快照：支持命令 /opencode-go-sync 强制同步，并保留一个经过筛选的快照作为离线回退方案。
容错机制：当源数据不可用或模型数量低于安全阈值时，自动切换到快照模式，确保模型选择器不会空置。

安装与启用¶

该插件需通过手动方式安装。

    cp -r dsh-opencode-go-catalog <profile>/node_modules/dsh-opencode-go-catalog

编辑配置目录下的 package.json，在 dsh.profile.bundles 中添加插件名称：

    {
      "dsh": {
        "profile": {
          "bundles": [
            "dsh-opencode-go-catalog"
          ]
        }
      }
    }

重启 DSH。

配置说明¶

在 cordis.patch.yml 中配置插件，以控制同步行为和路由列表。这是一个整体替换（非深度合并），需包含所有字段：

- id: opencode-go-catalog
  name: dsh-opencode-go-catalog
  config:
    enabled: true            # false 时移除兄弟路由
    autoMembership: true     # false 时仅使用快照，不查询名录/文档
    minAutoModels: 8         # 安全阈值：低于此数量使用快照
    minProtocolRows: 10      # 安全阈值：防止文档重设计导致路由为空
    minAutoRatio: 0.6        # 安全阈值：上次采用集的保留比例，0 禁用
    refreshReasoning: true   # false 时仅使用快照推理值，禁用自动模式
    sessionHeaderValue: 'dsh-opencode-go-catalog'  # 添加静态会话头
    intervalMinutes: 240     # 0 表示仅在启动时同步
    startupDelaySeconds: 10
    refreshTimeoutMs: 120000
    catalogPath: ./catalog/models.json
    managedRoutes:
      - opencode-go-extras
      - opencode-go-responses
      - opencode-go-messages

常用命令与脚本¶

通过聊天命令或脚本文件管理目录状态。

聊天命令
* /opencode-go-sync：立即从实时源重写模型列表。

脚本文件
* node bin/sync.mjs：默认模式，报告字段差异、新/死模型 ID，但不写入文件。
* node bin/sync.mjs --auto：预览自动模式下的输出（新增、移除、未解析项）。
* node bin/sync.mjs --adopt：将实时成员写入快照（保留当前回退快照）。
* node bin/sync.mjs --write：从注册表重写快照字段并标记日期。

注意事项¶

手添模型不持久：在设置界面手动添加到三个路由的模型，在下次同步（启动、定时或命令触发）时会被覆盖删除。如需持久化，请使用 --adopt 命令写入快照或使用排除列表。
运行环境：插件以当前 DSH 进程权限运行。安装前请检查源码与许可证（MIT）。
依赖条件：必须确保 DSH 正在运行，且已配置有效的 OPENCODE_GO_API_KEY（内置路由可用即代表配置正确）。

总结¶

dsh-opencode-go-catalog 为 DSH 提供了动态的 OpenCode Go 模型目录管理能力，解决了内置静态目录无法更新的痛点。通过协议分离和快照回退机制，它在不干扰现有路由的前提下，保证了模型列表的实时性和稳定性。插件源码与文档可参考 GitHub。