# @dm-pkg/xllm

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

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

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

## 快速开始

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

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

## DeepSeek 思考模式（Thinking）

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

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

```ts
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](./docs/LLM-USAGE.md) 第 5.1 节。