概述

什么是 deepseek-kit？

deepseek-kit 是一个专为 DeepSeek API 深度适配的 TypeScript Agent 框架。与通用框架不同，deepseek-kit 从底层开始针对 DeepSeek 的思考模式、上下文缓存和结构化输出等核心特性进行专业优化，确保每一个 DeepSeek 特有的能力都能被正确、高效地使用。

为什么选择 deepseek-kit？

LangChain.js 和 AI SDK 都是优秀的通用框架，但 DeepSeek API 拥有独特的思考模式和缓存机制，通用框架在这些场景下存在难以回避的适配缺陷。deepseek-kit 从根源上解决了这些问题。

思考模式下的工具调用 — 精准适配

DeepSeek 思考模式会在最终回答前输出一段思维链（reasoning_content）。当模型在思考过程中发起工具调用时，后续所有请求必须完整回传 reasoning_content，否则 API 将返回 400 错误。

通用框架的消息管理机制无法区分"有工具调用"和"无工具调用"两种场景对 reasoning_content 的不同处理要求，导致多轮工具调用频繁失败。

deepseek-kit 的解决方案：

• 自动追踪思维链：在 Agent 循环中自动保留并回传 reasoning_content，确保思考链路不中断
• 区分处理策略：无工具调用时省略 reasoning_content 以减少 token 消耗，有工具调用时完整回传以保证正确性
• 默认启用思考模式：createModel 默认开启思考模式并设置 reasoningEffort: 'high'，无需额外配置即可获得最佳推理质量

更高的缓存命中率 — 降低成本

DeepSeek API 默认开启上下文硬盘缓存，当后续请求与之前请求的前缀完全匹配时，重复部分只需从缓存拉取，大幅降低延迟和费用。

然而，缓存命中依赖于请求前缀的严格一致性。通用框架常在请求中注入时间戳、请求 ID 等动态元数据，或以非确定性顺序排列消息，这些行为会破坏前缀一致性，导致缓存命中率骤降。

deepseek-kit 的解决方案：

• 零冗余请求体：仅发送 API 所需的字段，不注入任何额外元数据，最大化前缀匹配概率
• 确定性消息构建：消息按固定顺序组装，确保相同输入始终产生相同的请求前缀
• 缓存命中率可观测：Usage 类型完整暴露 prompt_cache_hit_tokens 和 prompt_cache_miss_tokens，让你实时掌握缓存效率

更好的结构化输出 — 思考模式兼容

结构化输出是 Agent 应用的高频需求，但在 DeepSeek 思考模式下，通用框架的结构化输出方案往往与 reasoning_content 的管理产生冲突，导致输出格式不可靠。

deepseek-kit 的解决方案：

• Zod Schema 驱动：基于 Zod 定义输出结构，获得完整的 TypeScript 类型推导
• 智能重试与错误反馈：输出不符合 Schema 时，自动将格式化后的校验错误反馈给模型进行修正，最多重试 3 次
• 思考模式兼容：结构化输出流程完整保留 reasoning_content，不会因格式化步骤丢失思维链上下文

核心特性

• 🧠 思考模式适配 — 自动管理 reasoning_content，工具调用链路零配置可用
• 💾 缓存命中率优化 — 零冗余请求体 + 确定性消息构建，最大化 DeepSeek 缓存收益
• 📋 结构化输出 — Zod Schema 驱动，智能重试，思考模式完全兼容
• 🤖 Agent 系统 — 创建具有工具调用能力的智能代理
• 💬 流式输出 — 支持文本、思维链、工具调用的流式事件
• 🔧 工具调用 — 内置工具定义、参数校验、超时与重试
• ✍️ FIM 补全 — 支持 Fill-in-the-Middle 代码补全
• 🪝 Hook 机制 — 在生成步骤前后插入自定义逻辑
• 🔄 自动重试 — 指数退避 + 抖动的智能重试策略
• 🌲 Tree-shakable — 纯 ESM，sideEffects: false
• 🔒 类型安全 — 完整的 TypeScript 类型定义

环境要求

• Node.js >= 18.0.0
• DeepSeek API 密钥

快速体验

在线试用 — 无需本地安装：

或本地脚手架创建项目：

npx create-deepseek-kit my-agent

快速示例

import { createAgent, createModel, tool } from 'deepseek-kit'
import { z } from 'zod'

const model = createModel({ model: 'deepseek-v4-flash' })

const weatherTool = tool({
  name: 'get_weather',
  description: '获取指定城市的天气信息',
  schema: z.object({
    city: z.string().describe('城市名称'),
  }),
  execute: async ({ city }) => `${city}：晴，25°C`,
})

const agent = createAgent({
  model,
  tools: [weatherTool],
})

const result = await agent.generate({
  prompt: '重庆今天天气怎么样？',
})

console.log(result.text)

社区

如果您对 deepseek-kit 有任何问题，欢迎在 GitHub Issues 上提问。

MIT

MIT