@faapi/agent 5.4.0 → 6.1.0

package/dist/index.d.ts

@@ -36,52 +36,73 @@ declare function createOpenAIProvider(config: LlmConfig): LLMProvider;
  * 详见 [provider.md](./provider.md)。
  */
 /**
- * 对话消息
+ * 对话消息（OpenAI chat completions 规范形）
  *
  * 四种 role 与 OpenAI chat completions 一致：
  * - `system` —— 系统提示词（agent 的 systemPrompt）
  * - `user` —— 用户输入
- * - `assistant` —— LLM 回复（可能含 toolCalls）
- * - `tool` —— tool 执行结果（需带 toolCallId 标识对应哪个 tool_call）
+ * - `assistant` —— LLM 回复（可能含 tool_calls）
+ * - `tool` —— tool 执行结果（需带 tool_call_id 标识对应哪个 tool_call）
+ *
+ * 字段拼写与 OpenAI 线格式一致（`tool_calls` / `tool_call_id`），OpenAI provider
+ * 对 messages 恒等透传，观测/存储/展示消费方按 OpenAI 形状处理即可。
  */
 interface LLMMessage {
     role: 'system' | 'user' | 'assistant' | 'tool';
     /** 消息内容（assistant 角色 + tool_calls 时可能为空字符串） */
     content: string;
     /** role='tool' 时:对应的 tool_call ID（用于 LLM 关联 tool 结果） */
-    toolCallId?: string;
+    tool_call_id?: string;
     /** role='assistant' 时:LLM 请求的 tool 调用（reactLoop 据此执行 tool） */
-    toolCalls?: LLMToolCall[];
+    tool_calls?: LLMToolCall[];
+    /**
+     * role='assistant' 时:thinking 模型的推理内容（DeepSeek 线格式字段名）
+     *
+     * provider 响应解析产物（非流式含完整内容），供业务方展示/审计；
+     * **不回传 LLM API**——OpenAI provider 发送请求时剥离（DeepSeek 多轮回传
+     * 推理内容直接 400，OpenAI 等拒绝未知字段），reactLoop 组装历史时同样剥离。
+     * 兼容解析：线格式 `reasoning_content` 优先，缺失时读 `reasoning`（OpenRouter 形状）。
+     */
+    reasoning_content?: string;
 }
 /**
- * LLM 请求的 tool 调用
+ * assistant 消息内的 tool 调用（OpenAI chat completions 规范形）
  *
- * 由 LLM 在 assistant 消息中返回。`arguments` 已 JSON.parse，
- * reactLoop 直接传给 tool 函数。
+ * 由 LLM 在 assistant 消息中返回。`function.arguments` 是线格式的 JSON **字符串**
+ * （不预解析）——消息历史可原样透传与持久化；[reactLoop](./reactLoop.md) 在执行前
+ * JSON.parse，tool 执行函数 / 鉴权钩子 / trace 事件拿到的都是已 parse 的对象。
  */
 interface LLMToolCall {
     /** tool call ID（provider 分配，用于匹配 tool 结果） */
     id: string;
-    /** tool 名（匹配 LLMToolDefinition.name） */
-    name: string;
-    /** tool 参数（已 JSON.parse 的对象） */
-    arguments: Record<string, unknown>;
+    /** 固定 `'function'`（OpenAI 线格式） */
+    type: 'function';
+    function: {
+        /** tool 名（匹配 LLMToolDefinition.function.name） */
+        name: string;
+        /** tool 参数（JSON 字符串，线格式原样） */
+        arguments: string;
+    };
 }
 /**
- * Tool 定义
+ * Tool 定义（OpenAI chat completions 规范形）
  *
  * 由 [reactLoop](./reactLoop.md) 从 [toolRegistry](../../faapi/src/injection/toolRegistry.md)
  * + [agentRegistry.resolveSubAgents](../../faapi/src/injection/agentRegistry.md) 组装：
- * - 常规 tool：`input` 来自 AST 提取的 zod schema（JSON Schema 形式）
- * - agent-as-tool：`input` 为自由 schema（agent 参数开放）
+ * - 常规 tool：`function.parameters` 来自 AST 提取的 zod schema（JSON Schema 形式）
+ * - agent-as-tool：`function.parameters` 为自由 schema（agent 参数开放）
  */
 interface LLMToolDefinition {
-    /** tool 名（如 `weather.getWeather` 或 `agent.researcher`） */
-    name: string;
-    /** tool 描述（对 LLM 可见，引导 LLM 选择调用） */
-    description?: string;
-    /** JSON Schema 对象（描述 tool 参数结构） */
-    input: Record<string, unknown>;
+    /** 固定 `'function'`（OpenAI 线格式） */
+    type: 'function';
+    function: {
+        /** tool 名（如 `weather.getWeather` 或 `agent.researcher`） */
+        name: string;
+        /** tool 描述（对 LLM 可见，引导 LLM 选择调用） */
+        description?: string;
+        /** JSON Schema 对象（描述 tool 参数结构） */
+        parameters?: Record<string, unknown>;
+    };
 }
 /**
  * complete / stream 的入参
@@ -138,10 +159,10 @@ type LLMStopReason = 'stop' | 'tool_calls' | 'length' | 'content_filter' | 'othe
 /**
  * complete 的返回
  *
- * `message.toolCalls` 不为空时 stopReason 应为 `'tool_calls'`。
+ * `message.tool_calls` 不为空时 stopReason 应为 `'tool_calls'`。
  */
 interface LLMResponse {
-    /** assistant 消息（含 content + 可选 toolCalls） */
+    /** assistant 消息（OpenAI 规范形，含 content + 可选 tool_calls） */
     message: LLMMessage;
     /** 停止原因（reactLoop 据此判断是否进入下一轮） */
     stopReason: LLMStopReason;
@@ -149,23 +170,29 @@ interface LLMResponse {
     usage?: LLMUsage;
 }
 /**
- * Token 用量
+ * Token 用量（OpenAI chat completions 规范形）
  */
 interface LLMUsage {
-    promptTokens: number;
-    completionTokens: number;
-    totalTokens: number;
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
 }
 /**
  * stream 的单个 chunk
  *
+ * provider 内部流抽象（非 OpenAI 分片 delta 线格式）：
  * - 内容流：`deltaContent` 为增量 token
- * - tool 调用：累积完成后在最终 chunk 一并 emit `toolCalls`
+ * - 推理内容流（thinking 模型）：`deltaReasoning` 为推理增量（与 `deltaContent` 同为
+ *   增量语义，消费方按到达顺序各自拼接）
+ * - tool 调用：累积完成后在最终 chunk 一并 emit `toolCalls`（OpenAI 规范形，
+ *   `function.arguments` 为 JSON 字符串）
  * - 结束：最终 chunk 含 `finishReason` + 可选 `usage`
  */
 interface LLMStreamChunk {
     /** 增量内容（streaming token） */
     deltaContent?: string;
+    /** 推理内容增量（thinking 模型，如 DeepSeek `reasoning_content` / OpenRouter `reasoning`） */
+    deltaReasoning?: string;
     /** 累积完成的 tool 调用（在最终 chunk 出现） */
     toolCalls?: LLMToolCall[];
     /** 结束原因（只在最终 chunk 出现） */
@@ -388,7 +415,7 @@ interface ReactLoopConfig {
      * 提供时以其为基础（历史应含 system）：历史无 `system` 消息且配置了
      * `systemPrompt` 时自动在最前插入（agent 人格不因续跑丢失）；`input` 非空时
      * 追加为新的 `user` 消息（多轮对话），为空时纯续跑。历史经 `Agent` 层结构校验
-     * （assistant.toolCalls 与 tool 结果按 toolCallId 配对完整）。
+     * （assistant.tool_calls 与 tool 结果按 tool_call_id 配对完整）。
      * 续跑源见 [reactLoop.md](./reactLoop.md) 中断恢复章节。
      */
     messages?: LLMMessage[];
@@ -406,6 +433,12 @@ interface ReactLoopConfig {
 interface ReactLoopResult {
     /** 最终 assistant 消息内容 */
     content: string;
+    /**
+     * 最终 assistant 的推理内容（thinking 模型，多轮时中间轮的推理不保留；
+     * 无推理内容时不存在）。历史 messages 中的 assistant 消息已剥离推理内容，
+     * 仅此字段与 trace 的 `llm_call.response.reasoning_content` 可读。
+     */
+    reasoning?: string;
     /** 完整对话历史（system + user + assistant + tool 消息） */
     messages: LLMMessage[];
     /** 使用的轮数（含最终轮） */
@@ -425,6 +458,7 @@ interface ReactLoopResult {
  *
  * 每个 chunk 至多含一个字段：
  * - `deltaContent` — LLM 增量 token（多次 yield）
+ * - `deltaReasoning` — LLM 推理内容增量（thinking 模型，含中间 tool 轮）
  * - `toolCall` — tool 开始执行
  * - `toolResult` — tool 执行完成
  * - `traceEvent` — trace 事件（`enableTracing=true` 时增量推送,与上述字段互斥）
@@ -433,6 +467,8 @@ interface ReactLoopResult {
 interface ReactLoopStreamChunk {
     /** LLM 增量 token */
     deltaContent?: string;
+    /** LLM 推理内容增量（thinking 模型，见 reactLoop.md thinking 章节） */
+    deltaReasoning?: string;
     /** tool 开始执行（LLM 请求调用 tool） */
     toolCall?: {
         name: string;
@@ -445,12 +481,14 @@ interface ReactLoopStreamChunk {
     };
     /**
      * trace 事件（`enableTracing=true` 时增量推送）。
-     * 与 deltaContent / toolCall / toolResult / done 互斥,一个 chunk 至多一个字段。
+     * 与 deltaContent / deltaReasoning / toolCall / toolResult / done 互斥,一个 chunk 至多一个字段。
      */
     traceEvent?: AgentTraceEvent;
     /** 循环结束 */
     done?: {
         content: string;
+        /** 最终轮的完整推理内容（thinking 模型；无推理内容时不存在） */
+        reasoning?: string;
         turns: number;
         stopReason: LLMStopReason;
         usage?: LLMUsage;
@@ -475,7 +513,7 @@ declare class ReactLoopError extends Error {
  *
  * @param input 用户输入（续跑场景可为空，历史经 `config.messages` 提供）
  * @param config 循环配置
- * @returns 最终结果（content + messages + turns + stopReason + usage）
+ * @returns 最终结果（content + reasoning + messages + turns + stopReason + usage）
  * @throws {ReactLoopError} 超出 maxTurns（`error.messages` 携带完整历史，可续跑）
  * @throws {AgentAbortError} 中断（`error.messages` 携带断点历史，可续跑）
  * @throws {Error} provider.complete 抛错时立即传播
@@ -484,7 +522,7 @@ declare function reactLoop(input: string | undefined, config: ReactLoopConfig):
 /**
  * 执行 ReAct 循环（流式）
  *
- * 使用 `provider.stream()` 异步迭代 chunks，yield `deltaContent` + `toolCall` + `toolResult` + `done`。
+ * 使用 `provider.stream()` 异步迭代 chunks，yield `deltaContent` + `deltaReasoning` + `toolCall` + `toolResult` + `done`。
  *
  * @param input 用户输入（续跑场景可为空，历史经 `config.messages` 提供）
  * @param config 循环配置
@@ -949,17 +987,17 @@ declare class Agent {
      */
     private resolveModelKey;
     /**
-     * 组装 LLM 可见 tool 列表
+     * 组装 LLM 可见 tool 列表（OpenAI chat completions 规范形）
      *
-     * 合并两个来源（按 `name` 去重，先入者保留）：
+     * 合并两个来源（按 `function.name` 去重，先入者保留）：
      * 1. **resolveAgentTools** —— agent 显式声明的 `tools` 引用
      * 2. **sub-agent** —— `resolveSubAgents` 每个包装为 `agent.<name>`
      *
-     * 每个常规 tool 的 `input`：
+     * 每个常规 tool 的 `function.parameters`：
      * - `resolveToolSchema` 提供 → 用其 `jsonSchema`
      * - 未提供 / tool 无 `inputTypeName` → 自由 schema `{ type: 'object' }`
      *
-     * sub-agent 的 `input` 始终为 `{ type: 'object' }`（agent 参数开放）。
+     * sub-agent 的 `function.parameters` 始终为 `{ type: 'object' }`（agent 参数开放）。
      */
     private buildToolDefinitions;
     /**