ffyuuu/dsh-llm-longcat

dsh-llm-longcat

用于 DeepSeek Harness LLM 接缝的 LongCat 适配器。

将 LongCat-2.0 添加为模型提供方：1M 上下文、思考模式、工具调用。

特性

- 思考模式 — 识别 LongCat 的 reasoning_content 字段，并将其转换为 harness 的 ReasoningBlock
- 工具调用 — 完整的函数调用支持，arguments 全程保持为原始 JSON 字符串
- 多轮对话 — 在工具调用轮次中回放 reasoning_content，这是思考模式回传所要求的
- 流式传输 — SSE，采用 harness 所依赖的 usage 先于 finish 的顺序
- 凭据接缝 — 密钥按请求从 ctx.credentials 或环境变量中解析；任何配置文件中都不含密钥

支持的模型

| 模型 | 上下文 | 最大输出 | 备注 |
|---|---|---|---|
| LongCat-2.0 | 1,048,576 | 131,072 | 纯文本；思考 + 工具调用 |

事实来自 GET /openai/v1/models/LongCat-2.0，这是唯一一个会报告
supported_parameters 的已记录端点。工具调用在
chat-completions 文档页面上未提及，仅在该端点可见。

安装

dsh plugin --profile default add github:ffyuuu/dsh-llm-longcat
export LONGCAT_API_KEY=...   # create one at https://longcat.chat/platform/api_keys

安装 bundle 会让该包的安装脚本在你的机器上运行，
处于 agent 所运行的沙箱之外。请固定一个提交，这样之后的推送
就无法改变实际执行的内容：

dsh plugin --profile default add github:ffyuuu/dsh-llm-longcat#3dcb3b1b5870ba52baab053453bdbb28826e5f13

然后在模型选择器中选择 LongCat-2.0。密钥也可以通过
Web UI 的 Models 页面存储，而非环境变量。

如果 dsh 本身无法安装

在撰写本文时，安装 harness 可能在触及任何插件之前就失败，
报错为 ETARGET … dsh-typert-protocol@^0.1.0-rc.8 或 npm
堆内存耗尽。这是上游的打包状态，而非本插件的问题：
@deepseek-ai/dsh 发布了 0.1.0-rc.8，而它所依赖的若干包
却停留在 0.1.0-rc.7，并且由于这些清单使用脱字符范围，
^0.1.0-rc.7 仍会向上解析到缺失的 rc.8。npm 随后会在
一个无法满足的依赖图上回溯，直到内存耗尽。

通过 npm overrides 将每个 @deepseek-ai/ 包固定到确切的
0.1.0-rc.7 可以避免这种漂移。无论哪种方式，本插件都无需更改
——它声明 >=0.1.0-rc.7，并且对宿主最终采用的其中任一版本都能正常工作。

配置

- id: llm-longcat
name: dsh-llm-longcat
config:
apiKeyEnv: LONGCAT_API_KEY   # default; resolved per request, never a literal key
baseURL: https://api.longcat.chat/openai/v1  # optional; $LONGCAT_BASE_URL then the public API
thinking: enabled            # optional deployment policy; disabled locks every request to off
reasoningEffort: high        # optional; off | high — LongCat's switch is binary
maxTokens: 131072            # 可选的每请求输出上限
defaultContextWindow: 1048576
streamIdleTimeoutMs: 300000  # 可选；默认五分钟
retryPolicy:                 # 可选；省略时使用有界的常规默认值
mode: normal
maxRetries: 3
models:
- id: LongCat-2.0
contextWindow: 1048576

$DSH_HOME/settings.yaml 中的 llm-longcat: 段可在无需重启的情况下覆盖任何字段：
基础 URL、目录、请求默认值和空闲预算都会在下一个请求时生效，而进行中的流
会保留其启动时的事实。

推理是二元的，这是有意为之

LongCat 通过 thinking: {type: enabled|disabled} 控制思考，并且
不接受 OpenAI 顶层的 reasoning_effort —— 其
supported_parameters 列出了前者而省略了后者。因此
没有低/中/高的梯度可供映射，此适配器只提供
两个级别，而不是宣传那些会坍缩到相同
两个请求体上的控制项：

| 所选强度 | 线上请求体 |
|---|---|
| high（“Thinking”） | {"thinking": {"type": "enabled"}} |
| off | {"thinking": {"type": "disabled"}} |
| （未指定）* | 从配置解析；仍然是显式的 |

off 会序列化一个显式的 disabled，而不是省略该字段 ——
省略它会把决定权交给 LongCat 的服务端默认值，这
并不是选择 Off 应有的含义。请求 low、medium 或 max 会在任何网络 I/O 之前
以 UNSUPPORTED_REASONING_EFFORT 失败。

线上格式说明

- 工具调用增量会把 id 和 name 重复为显式的 null。 LongCat 会在
起始增量上发送它们，然后在每个后续增量上发送 null（而非省略），因此一个朴素的
!== undefined 守卫会把已组装调用的名称清空。已在实时流量上验证；
由回归测试固定。
- 仅支持流式，且 stream_options.include_usage 始终开启。用量可能
附加在结束块上到达，也可能作为仅含用量的尾随块到达；两者
都会推迟到 [DONE]，因此 usage 总是先于 finish。
- 第一个思考模式增量可能是空字符串 —— 它不得开启一个
推理块。
- 推理回传：在携带工具调用的助手轮次上，
reasoning_content 会被序列化回历史记录；在不含工具调用的轮次上
它会被丢弃（反正也会被忽略 —— 节省 token）。
- 助手的 content 始终是字符串，绝不为 null：该消息是持久的
会话历史，而那里的 null 会让后续轮次重放一个
端点可能拒绝的请求体。
- 缓存核算：prompt_tokens_details.cached_tokens 映射到
cacheReadTokens，并从 inputTokens 中减去，以保持
测试框架的不相交计数约定。

错误

非 2xx 响应会抛出带有稳定代码的 LlmError。LongCat 文档中有一个
专用的 402 用于 token 配额耗尽，并将 insufficient_quota 放在
403 上，而大多数 OpenAI 兼容提供商使用 429 —— 两者都被归类
在认证和速率限制桶之前作为 QUOTA，因此耗尽的余额
永远不会被报告为错误的密钥，也不会作为瞬态速率限制重试。

| 条件 | 代码 |
|---|---|
| 402，或任何状态下的配额详情 | QUOTA_EXCEEDED |
| 401 / 403 | AUTH |
| 429 | RATE_LIMIT |
| 400 且带有上下文溢出详情 | CONTEXT_WINDOW_EXCEEDED |
| 其他 400 | INVALID_REQUEST |
| 5xx | SERVER |
| 无 [DONE] / 错误的 JSON | STREAM_CLOSED / MALFORMED_RESPONSE |

一个已完成但未打开任何内容块的流会变成带有
EMPTY_RESPONSE 的 finish 错误，随附的重试策略将其视为可重试。

测试
sh
npm run typecheck   # against the published @deepseek-ai/dsh-llm types
npm test            # 30 unit tests over serialize + translate
npm run build       # emits lib/ and lib/types/
npm run test:e2e    # real API, needs LONGCAT_API_KEY, spends a few hundred tokens

test:e2e 驱动已构建适配器自身的 serialize → SSE → translate 流水线
针对 api.longcat.chat，因此它验证的是插件实际发送的内容，
而不是手写的近似值。正是它捕获了 null-name delta 缺陷。

限制

- 无图像输入。 LongCat-2.0 报告 modality: text->text，因此图像
内容在发送前被拒绝，并指明模型名称。
- 无停止序列。 stop 不在 supported_parameters 中；传入
一个会以 UNSUPPORTED_OPTION 失败，而不是静默地越过它运行。
- 推理是二元的 —— 不存在可映射的低/中/高梯度。

许可证

MIT