# @dm/xllm

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

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

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

## 快速开始

```ts
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` 会自动执行工具并把结果回填给模型，直到拿到最终回答或达到轮次上限：

```ts
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` 适合需要边输出边自动执行工具的场景：

```ts
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);
}
```