tsdown-mono/packages/xllm

@dm-pkg/xllm

面向大模型 / Agent 的完整 API 与协议说明见 docs/LLM-USAGE.md。

统一的大模型请求库，支持：

• 流式输出（for await...of）
• OpenAI-Compatible 与 DeepSeek 供应商适配
• DeepSeek 思考模式：thinking、reasoning_effort 与流式 reasoning.delta
• 文本、多模态输入（图片 URL）、工具调用结构统一

快速开始

import { createXllm } from "@dm-pkg/xllm";

const xllm = createXllm({
  provider: "deepseek",
  model: "deepseek-chat",
  apiKey: process.env.DEEPSEEK_API_KEY,
});

for await (const event of xllm.stream({
  messages: [{ role: "user", content: [{ type: "text", text: "你好" }] }],
})) {
  if (event.type === "text.delta") process.stdout.write(event.text);
}

工具调用闭环

chatWithTools 会自动执行工具并把结果回填给模型，直到拿到最终回答或达到轮次上限：

const result = await xllm.chatWithTools(
  {
    messages: [{ role: "user", content: [{ type: "text", text: "上海天气如何？" }] }],
    tools: [{ name: "get_weather", parameters: { type: "object" } }],
    toolChoice: "auto",
    maxRounds: 5,
    toolErrorStrategy: "return_tool_error_message", // "throw" | "return_tool_error_message" | "skip"
  },
  {
    get_weather: async (args) => ({ city: args.city, weather: "cloudy", temp: 24 }),
  },
);

console.log(result.response.text);
console.log(result.rounds, result.toolCallsExecuted);

流式工具闭环

streamWithTools 适合需要边输出边自动执行工具的场景：

for await (const event of xllm.streamWithTools(
  {
    messages: [{ role: "user", content: [{ type: "text", text: "查上海天气并总结一句话" }] }],
    tools: [{ name: "get_weather", parameters: { type: "object" } }],
  },
  {
    get_weather: async () => ({ city: "Shanghai", weather: "cloudy", temp: 24 }),
  },
)) {
  if (event.type === "text.delta") process.stdout.write(event.text);
}

DeepSeek 思考模式（Thinking）

thinking / reasoning_effort 仅适用于 OpenAI Chat Completions 兼容体 里采用这些字段名的网关（如 DeepSeek 文档）。其它厂商字段不同时，请用请求上的 providerExtras 合并任意 JSON 根字段，或扩展适配器。

通过 providerExtras 设置 thinking 与 reasoning_effort，会合并进 Chat Completions 请求体。流式下思考增量为 reasoning.delta，正文为 text.delta。

for await (const event of xllm.stream({
  messages: [{ role: "user", content: [{ type: "text", text: "…" }] }],
  providerExtras: { thinking: { type: "enabled" }, reasoning_effort: "high" },
})) {
  if (event.type === "reasoning.delta") process.stderr.write(event.text);
  if (event.type === "text.delta") process.stdout.write(event.text);
}

详见 docs/LLM-USAGE.md 第 5.1 节。