krislavten/ai-sdk-provider-dsh

ai-sdk-provider-dsh

AI SDK 提供程序，将 DeepSeek Harness（dsh）运行时作为语言模型驱动。

dsh 是来自 DeepSeek AI 的完整智能体框架（智能体循环、工具、技能、MCP、会话）。此提供程序将 dsh 运行时子进程封装在 AI SDK 的 LanguageModel 接口之后，因此你可以像 ai-sdk-provider-claude-code 驱动 Claude Code 那样，通过 AI SDK 的 generateText / streamText 驱动框架智能体——同时保持 AI SDK 作为唯一的编排界面。

版本兼容性

此提供程序实现了 LanguageModelV3 规范（specificationVersion: 'v3'），这是跨 AI SDK 主要版本共享的接口。单个构建可同时服务于两者：

| AI SDK | @ai-sdk/provider | 状态 |
| ------ | ------------------ | ------ |
| ai@^6 | @ai-sdk/provider@^3 | ✅ 支持 |
| ai@^7 | @ai-sdk/provider@^4 | ✅ 支持（V3 模型在 v7 中是一等公民） |

| 要求 | 值 |
| ----------- | ----- |
| Node.js | >=22.19 |
| 模块格式 | 仅 ESM |
| DeepSeek Harness 系列 | 固定精确版本 0.1.0-rc.6 |

上游状态： dsh 处于开发者预览阶段（0.1.0-rc.x）；DeepSeek 将其发布策略记录为包含破坏性变更。此提供程序将框架 SDK 系列固定为精确版本，因此运行时版本是有意为之的平台侧决策——请显式升级固定版本，切勿通过范围漂移升级。

安装

npm install ai-sdk-provider-dsh

dsh 运行时是捆绑的：该包附带默认运行时组合（runtime/cordis.yml）以及 dsh-jsonrpc-agent 可执行文件（通过 @deepseek-ai/dsh-sdk-jsonrpc-demo），并且所有运行时插件都在 dependencies 中固定为精确版本。提供程序实例开箱即可启动一个可用的运行时——无需单独安装。

凭据来自运行时的环境变量：

export DEEPSEEK_API_KEY=sk-...                                        # 必需
export DEEPSEEK_BASE_URL=https://api.deepseek.com                     # 可选；任何 OpenAI 兼容网关均可

快速开始

streamText（AI SDK v7）

import { streamText } from "ai";
import { createDsh } from "ai-sdk-provider-dsh";

const dsh = createDsh({
runtime: { provider: "deepseek-official", model: "deepseek-v4-flash" },
});

const result = streamText({
model: dsh.languageModel("deepseek-v4-flash"),
instructions: "You are a coding agent.",
prompt: "run the tests",
});

const text = await result.text;
console.log(text);

streamText（AI SDK v6）

import { streamText } from "ai";
import { createDsh } from "ai-sdk-provider-dsh";

const dsh = createDsh({ runtime: { provider: "deepseek-official", model: "deepseek-v4-flash" } });

const result = streamText({
model: dsh.languageModel("deepseek-v4-flash"),
system: "You are a coding agent.", // v6 名称；v7 使用 instructions
prompt: "run the tests",
});

generateText

typescript
import { generateText } from "ai";
import { createDsh } from "ai-sdk-provider-dsh";

const dsh = createDsh({ runtime: { provider: "deepseek-official", model: "deepseek-v4-flash" } });
const { text } = await generateText({
model: dsh.languageModel("deepseek-v4-flash"),
prompt: "say hello",
});

Provider 工厂
typescript
const dsh = createDsh(options);        // 返回 provider
dsh.languageModel("deepseek-v4-flash") // LanguageModel
dsh("deepseek-v4-flash")               // 可调用别名（AI SDK provider 约定）
await dsh.close();                     // 关闭运行时子进程（幂等）

运行时选项

| 选项 | 默认值 | 含义 |
| ------ | ------- | ------- |
| provider | 必填 | 传递给运行时握手的模型提供方路由（deepseek-official，或 pi-ai 目录路由） |
| model | 必填 | 传递给运行时握手的模型 id |
| env | 继承 process.env | 运行时子进程的环境变量：凭据（DEEPSEEK_API_KEY）、DEEPSEEK_BASE_URL、DSH_CWD、DSH_SESSION_ROOT、…… |
| cwd | process.cwd() | 子进程工作目录 |
| configPath | 内置的 runtime/cordis.yml | 不同的 cordis.yml 组合 |
| binPath | 内置的 dsh-jsonrpc-agent | 不同的运行时二进制文件 |
| command / args | node + [bin, config] | 完全自定义的启动向量（需同时设置两者） |
| maxTokens | — | 每个根代理请求的正输出 token 上限 |
| requestTimeoutMs | SDK 默认值 | JSON-RPC 传输的每请求超时 |
| disposeEofGraceMs / disposeGraceMs | SDK 默认值 | 子进程关闭阶梯（EOF → SIGTERM → SIGKILL） |
| sessionId | 新 UUID | 固定会话 id；保留它可在多轮之间延续同一个 harness 会话 |

内置运行时

默认组合（runtime/cordis.yml）暴露：

- bash（前台）、read/write/edit（文件系统）、subagent、todo_write —— 工具在 harness 内部执行
- 带自动上下文压缩的 JSONL 会话持久化
- $DSH_SYSTEM_PROMPT 选择部署人设

对于无法构建 node-pty 的环境（没有 Linux 预构建 —— 例如最小化容器、缺少 libc6-dev 的 WSL），请使用无 pty 组合：
typescript
runtime: {
provider: "deepseek-official",
model: "deepseek-v4-flash",
configPath: require.resolve("ai-sdk-provider-dsh/runtime/cordis.minimal.yml"),
}

工作原理

- 每个 provider 实例会（惰性地）启动一个 dsh 运行时子进程，通过 stdio 进行 JSON-RPC 通信（dsh SDK 协议）。
- doGenerate / doStream 将 AI SDK 的 LanguageModelV3CallOptions 转换为 dsh 提示，然后将运行时的 session.event 流映射回 AI SDK 流片段（text-start/delta/end、reasoning-start/delta/end、tool-input-start/delta/end、tool-call、finish）。
- 工具在 harness 内部执行——provider 只是一个薄透传层（类似 ai-sdk-provider-claude-code）：工具调用以 providerExecuted: true 的形式出现，AI SDK 永远不会重新执行它们。
- 多轮会话：一个 provider 实例维护一个运行时子进程；在固定 sessionId 的情况下，后续轮次会继续同一个 harness 会话（运行时会持久化会话日志）。已端到端验证：第 1 轮存储一个秘密代码，第 2 轮将其取回。
- 中止：被中止的调用会呈现原始中止原因（绝不会是包装后的传输错误）；预先中止的信号会立即抛出；中止监听器在完成时被移除。

Provider 元数据

每个响应都会在 providerMetadata['dsh'] 下暴露 dsh 元数据（AI SDK v7：result.finalStep.providerMetadata，或对 streamText 使用 await stream.finalStep；v6：result.providerMetadata）：

| 字段 | 类型 | 含义 |
| ----- | ---- | ------- |
| sessionId | string | 本次调用所运行的 harness 会话 id |
| turnId | number? | 最后观察到的轮次编号 |
| terminalReason | string? | 当不是 completed 时的最终轮次结束类型（aborted、error、max-tokens、blocked、interrupted） |

错误诊断

来自运行时边界的错误会被归类为 AI SDK 的 APICallError。经过脱敏的 stderr 尾部会追加到消息中，以便 CLI 故障在日志中可见：

dsh runtime subprocess failed: runtime exited | stderr (tail): ...; ...
typescript
import { generateText } from "ai";
import { createDsh, getErrorMetadata, isAPICallError } from "ai-sdk-provider-dsh";

try {
await generateText({ model: dsh.languageModel("deepseek-v4-flash"), prompt: "Hello!" });
} catch (error) {
if (isAPICallError(error)) {
console.error(getErrorMetadata(error)?.stderr);
console.error("retryable:", error.isRetryable);
}
}

分类映射：

| 运行时故障 | AI SDK 错误 | 可重试 |
| --------------- | ------------ | --------- |
| TransportClosedError（子进程死亡 / stdio 关闭） | APICallError | ✅ |
| RequestTimeoutError | APICallError | ✅ |
| SdkProtocolError（协议违规） | APICallError | ❌ |
| JsonRpcResponseError（运行时拒绝了请求） | APICallError | ❌ |
| Node 启动失败（ENOENT bin 等） | APICallError | 仅 EAGAIN/EMFILE |
| 缺失/无效的 API key | LoadAPIKeyError（通过 createAuthenticationError） | — |

限制

- 需要 Node.js >=22.19；仅支持 ESM。
- SDK 协议上不支持轮次中途取消：中止一个轮次会拒绝当前调用；运行时子进程和会话日志会保留以供后续轮次使用。dsh.close() 会拆除子进程（EOF → SIGTERM → SIGKILL）。
- 技能使用 dsh 原生机制（从 .dsh/skills、.agents/skills、$DSH_HOME/skills 发现的 SKILL.md 包）——本 provider 不采用 reskill 的 skills.json/skills.lock 约定。
- 工具执行属于 harness 内部机制：AI SDK 的 tools / toolChoice 不会由 AI SDK 执行；请通过运行时组合（cordis.yml）或 $DSH_ 环境变量配置工具。
- 部分 AI SDK 调用选项会被接受，但不会转发给 harness：temperature、topP、topK、stopSequences、seed —— 采样由 harness 负责。
- dsh 处于开发者预览阶段；DeepSeek 将破坏性变更作为发布策略予以记录。请谨慎固定 provider 版本和 harness 系列（0.1.0-rc.6）。
- 捆绑的默认运行时在 Linux 上需要 node-pty（安装时编译；无预构建）。在无法满足该条件的环境中使用 cordis.minimal.yml（不含 bash）。

开发
sh
pnpm install
pnpm run check    # 类型检查
pnpm run test     # 单元测试（fake runtime）+ e2e（真实 runtime，无密钥回放）
pnpm run lint     # biome
pnpm run build    # tsup → dist/

测试永远不需要真实的 API 密钥：单元测试使用合成事件流驱动 fake runtime（ai-sdk-provider-claude-code 的理念），e2e 测试则针对由 @deepseek-ai/dsh-llm-replay 回放的录制的会话 fixture 启动真实的 dsh runtime。

录制新的 fixture（需要真实密钥）
sh
DEEPSEEK_API_KEY=sk-... node scripts/record-fixture.mjs   # 写入 tests/fixtures/.jsonl

许可证

MIT