tsdown-mono/packages/xllm/README.md

@dm/xllm

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

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

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

快速开始

import { createXllm } from "@dm/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);
}