eibednejo/dsh-llm-commandcode

dsh-llm-commandcode

一个 DeepSeek Harness（dsh）LLM
适配器，通过 Command Code 路由模型调用，
因此 Command Code Go 套餐 可以为 harness 提供 DeepSeek —— 以及 Claude、GPT、Kimi、GLM、
Qwen、MiniMax —— 包括图像输入。

pi ──────────► pi-commandcode-provider ──┐
dsh ─────────► dsh-llm-commandcode ──────┼──► api.commandcode.ai ──► model
cmd ─────────► (native) ─────────────────┘

为什么需要它

Command Code 的套餐层级决定了账户可以访问哪些 API 接口：

| 套餐 | POST /provider/v1/chat/completions | POST /alpha/generate | GET /provider/v1/models |
|---|---|---|---|
| Go | 403 upgrade_required | 允许 | 允许 |
| Provider 及以上 | 允许 | 允许 | 允许 |

/alpha/generate 是 cmd CLI 自身驱动的端点，也是 Go 套餐可以访问的端点。此适配器使用它：
harness 获得一个普通的 LlmAdapter 路由，而底层请求就是 CLI 自身的传输方式。
pi 扩展 pi-commandcode-provider 通过传输路由器做同样的事情；此插件是 dsh 的等价实现，
针对 harness 适配器接缝编写，而非兼容性垫片。

如果你的账户是 Provider 套餐或更高，你不需要此插件 ——
dsh-llm-pi-ai 可以通过普通配置访问文档化的 Provider API。

安装

从此目录的检出中：

dsh plugin --profile web add link:/absolute/path/to/dsh-llm-commandcode

然后向该 profile 的 cordis.patch.yml
（$DSH_HOME/profiles//cordis.patch.yml）添加两行：

Aim the harness at the new route.
- id: agent-default-model
config:
provider: commandcode
model: deepseek/deepseek-v4.1-flash
reasoningEffort: high

Mount the adapter.
- insert:
- id: llm-commandcode
name: 'dsh-llm-commandcode'
config:
baseURL: https://api.commandcode.ai
apiKeyEnv: COMMAND_CODE_API_KEY
modelCatalog: auto
defaultReasoningEffort: high

重启 dsh web。模型选择器随后会在内置的 DeepSeek 分组旁显示一个 Command Code 分组。

凭据

密钥按请求解析，首个匹配项生效：

1. harness 凭据服务（~/.dsh/.credentials.yaml，由 Web UI 中的 Models 页面写入）
2. 由 apiKeyEnv 命名的环境变量
3. ~/.commandcode/auth.json —— cmd login 写入的内容 —— 然后是 pi 和 OMP 的
auth 文件

配置中不存储任何密钥，且没有任何密钥的请求会以 MISSING_CREDENTIAL 失败，
而不是在插件加载时失败，因此 harness 的其余部分保持正常工作。

配置

| 字段 | 默认值 | 含义 |
|---|---|---|
| apiKeyEnv | COMMAND_CODE_API_KEY | 按请求解析的凭据引用 |
| baseURL | https://api.commandcode.ai | API 根地址；会追加 /alpha/generate |
| workingDir | 进程工作目录 | 作为请求上下文报告给端点 |
| cliVersion | 已安装的 command-code 版本，否则为 1.53.0 | 作为 x-command-code-version 发送，端点以此作为门控依据 |
| maxTokens | 64000 | 默认输出上限；目录模型自身的上限和显式请求值优先 |
| defaultContextWindow | 1000000 | 目录未指定大小的模型的容量 |
| defaultReasoningEffort | high | 会话未选择任何值时使用的推理强度 |
| streamIdleTimeoutMs | 300000 | 两个流事件之间的最大静默时间 |
| models | 五个 DeepSeek 模型 | 静态建议目录，在发现功能关闭或不可达时使用 |
| modelCatalog | auto | auto 从端点刷新（缓存一小时）；static 从不请求 |
| zeroDataRetention | false | 发送 x-cmd-zdr: 1，向网关请求零保留 |
| requestImagePixelBudget | 640000 | 每个请求图像的路径默认像素预算；目录模型自身的预算优先 |
| requestImageMaxBytes | 1048576 | 每个请求图像的路径默认编码字节目标；目录模型自身的目标优先 |
| maxRequestImageBytes | 20971520 | 单个请求中累积 base64 图像负载的上限 |
| maxImagesPerRequest | 600 | 单个请求中可表示的最大图像数 |
| imageOffloadByteQuantum | 10485760 | 超过负载上限后每次移除的原始字节步长 |
| imageOffloadCountQuantum | 20 | 超过数量上限后每次移除的图像数步长 |
| retryPolicy | 正常，五次重试 | 提供商拥有的重试策略 |

按模型覆盖配置放在目录条目本身上：

- id: llm-commandcode
name: 'dsh-llm-commandcode'
config:
models:
- id: deepseek/deepseek-v4.1-flash
inputModalities: [text, image]
imagePixelBudget: 1048576 # a larger per-image budget than the route default
imageMaxBytes: 2097152

图像输入

图像以内联 base64 数据 URL 部分的形式传输。每张图像前面都有一行简短的身份标识，模型可以引用它；当 harness 能将附件映射到某个路径时，该行还会携带一个只读路径，这样模型的文件工具就能打开规范化后的副本。

模型是否接受图像取决于 src/models.js 中的 MODEL_INPUT_MODALITIES，它镜像了 cmd CLI 自身的目录。表中未描述的模型会被视为仅文本——此时 harness 会为每张图像替换为确定性文本，而不是发送一个端点可能在会话后续每一轮都拒绝的图像。这就是为什么未编入目录的模型在附加图像时仍能工作，而不是失败。

来自工具结果的图像无法搭载在其仅文本的 role: 'tool' 消息中，因此它们会在紧随其后的独立用户轮次中发送——这与 Command Code 自身 CLI 发送的形式相同。

支持与不支持的内容

可正常工作，并已针对实时端点验证：

- 流式文本和推理（reasoning_content 等价物）
- 工具调用，包括多轮调用/结果往返
- 在目录声明支持图像能力的模型上进行图像输入
- 缓存感知的 token 计量以互不重叠的计数形式报告
- 推理强度菜单（off、low、high、max）
- 按请求重新解析凭据和端点

有意设定的限制，明确声明而非隐藏：

- 不发送停止序列。 生成路由没有经过验证的字段来承载它们，而凭空发明一个字段可能会导致请求被拒绝。
- 图像以内联方式发送，而非上传。 单个请求受 maxRequestImageBytes 限制；超出该限制的历史记录会将其最旧的图像出现位置替换为确定性的占位文本，而不是直接失败。
- 模型目录仅供参考。 发现过程会读取受计划门控的 GET /provider/v1/models 列表，并回退到静态目录；按照接缝的要求，任何模型 id 仍然可以直接请求。

注意事项

/alpha/generate 是 Command Code 的内部 CLI 端点，而非其文档化的 Provider API，并且上述计划门控是一项可能变化的商业决策。此适配器与 pi 扩展使用的是同一个变通方案；请将其视为变通方案。如果你需要受支持的契约，Provider 计划加上针对 /provider/v1 的 dsh-llm-pi-ai 才是预期路径。

与 Command Code 或 DeepSeek 无关联，亦未获得其认可。

跟进 dsh

dsh 是一个 0.x 预发布版本，其自身的 README 承诺会有破坏性变更，因此适配器必须在每个版本上重新证明其正确性，而不能想当然。check:upgrade 通过一条命令完成这件事：

npm run check:upgrade                      # 升级到 next 标签，验证，失败时回滚
npm run check:upgrade -- --dry-run         # 打印计划，不做任何更改
npm run check:upgrade -- --to 0.1.6-rc.1   # 指定版本或标签
npm run check:upgrade -- --skip-live       # 仅离线检查

它运行四个步骤：

1. 基线 — 首先针对已安装的版本验证插件。一台已经出问题的机器，其故障不能被归咎于升级，而且只有回滚目标原本可用，才值得回退到它。
2. 使用 npm install -g 安装目标版本。
3. 验证 — 先运行离线测试套件，然后通过 dsh 配置文件执行一次真实的 agent 回合（当没有可用的配置文件或凭据时，会跳过并给出原因）。
4. 当目标版本失败时自动回滚，并同时验证恢复后的版本。

退出码，正是它们让该脚本可用于自动化：

| 代码 | 含义 |
|---|---|
| 0 | 目标版本已安装并验证通过 |
| 1 | 安装失败；未做任何更改 |
| 2 | 目标版本验证失败；已恢复并验证上一版本 |
| 3 | 目标版本验证失败，且回滚无法验证 |

回滚以 2 而非 0 退出是有意为之：机器已恢复健康，但升级并未发生，调用方必须能够区分这两种情况。

除非明确指示，它也会拒绝向后移动。dsh 的 dist-tags 并非
单调递增——latest 当前解析到的构建版本比 next 更旧——因此默认目标是 next，而直接运行 npm install -g @deepseek-ai/dsh 会静默地将你降级。--allow-downgrade 可以覆盖这一拒绝行为。

测试

npm test                  # 38 项离线检查，无需网络
npm run test:live         # 驱动真实端点，需要 Command Code 密钥
node tests/live-adapter.mjs deepseek/deepseek-v4-pro

离线测试套件覆盖请求序列化、图像路径、流式转换、配置解析，以及升级检查所依赖的版本排序。实时脚本通过此插件自身的序列化和转换路径驱动真实端点，不依赖任何测试框架运行时，并打印每一轮的块、用量和结束原因。

pretest 钩子会运行 scripts/link-dsh-deps.mjs，该脚本会从你的 dsh 安装中链接此插件所导入的 @deepseek-ai/* 包。正是这一点使得测试套件可以从一个裸克隆中运行；通过 dsh plugin add 安装到 profile 中的插件则完全不需要这些，因为 profile 的加载器会提供解析。