@next-open-ai/openclawx 0.8.36 → 0.8.48

package/dist/core/local-llm-server/server.js

@@ -0,0 +1,235 @@
+/**
+ * OpenAI 兼容 HTTP 服务（严格对齐 [OpenAI Chat Completions / Embeddings API](https://platform.openai.com/docs/api-reference)）。
+ * 实现：GET /v1/models；POST /v1/chat/completions（流式/非流式，tool_calls）；POST /v1/embeddings。
+ * - 错误统一为 { error: { message, type } }，流式错误以 SSE 事件发送后结束。
+ * - 流式 delta 仅含规范字段：role、content（必为 string）、tool_calls（规范结构），避免客户端解析到未知类型。
+ */
+import { createServer } from "node:http";
+import { randomUUID } from "node:crypto";
+import { chatCompletionStream, chatCompletion, getEmbedding, isReady, } from "./llm-context.js";
+const LLM_MODEL_ID = process.env.LOCAL_LLM_MODEL_ID ?? "local-llm";
+const EMB_MODEL_ID = process.env.LOCAL_EMB_MODEL_ID ?? "local-embedding";
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        let data = "";
+        req.on("data", (chunk) => (data += chunk));
+        req.on("end", () => {
+            try {
+                resolve(data ? JSON.parse(data) : {});
+            }
+            catch {
+                reject(new Error("Invalid JSON body"));
+            }
+        });
+        req.on("error", reject);
+    });
+}
+function sendJson(res, status, body) {
+    const json = JSON.stringify(body);
+    res.writeHead(status, { "Content-Type": "application/json" });
+    res.end(json);
+}
+/** OpenAI 规范错误体：{ error: { message, type } } */
+function sendError(res, status, message, type = status >= 500 ? "server_error" : "invalid_request_error") {
+    sendJson(res, status, { error: { message: String(message), type } });
+}
+/** 构造 OpenAI 格式的 chat completion 响应对象 */
+function buildCompletionResponse(content, tool_calls, finish_reason, model) {
+    const message = { role: "assistant", content: tool_calls ? null : content };
+    if (tool_calls?.length)
+        message.tool_calls = tool_calls;
+    return {
+        id: `chatcmpl-${randomUUID()}`,
+        object: "chat.completion",
+        created: Math.floor(Date.now() / 1000),
+        model,
+        choices: [{ index: 0, message, finish_reason, logprobs: null }],
+        usage: { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 },
+    };
+}
+/** 构造 SSE delta chunk，仅含 OpenAI 流式规范字段，不包含 logprobs 避免下游解析异常 */
+function buildStreamChunk(id, model, delta, finish_reason) {
+    const choice = { index: 0, delta, finish_reason };
+    const chunk = {
+        id,
+        object: "chat.completion.chunk",
+        created: Math.floor(Date.now() / 1000),
+        model,
+        choices: [choice],
+    };
+    return `data: ${JSON.stringify(chunk)}\n\n`;
+}
+async function handleChatCompletions(req, res) {
+    let body;
+    try {
+        body = await readBody(req);
+    }
+    catch {
+        return sendError(res, 400, "Invalid JSON body");
+    }
+    if (!isReady())
+        return sendError(res, 503, "模型尚未加载完成，请稍后重试", "server_error");
+    if (!Array.isArray(body.messages)) {
+        return sendError(res, 400, "Missing or invalid 'messages' (must be an array)", "invalid_request_error");
+    }
+    if (body.messages.length === 0) {
+        return sendError(res, 400, "'messages' must contain at least one message", "invalid_request_error");
+    }
+    const messages = body.messages;
+    const tools = Array.isArray(body.tools) ? body.tools : [];
+    const stream = body.stream === true;
+    const model = typeof body.model === "string" && body.model.trim() ? body.model.trim() : LLM_MODEL_ID;
+    const abortCtrl = new AbortController();
+    req.on("close", () => abortCtrl.abort());
+    if (stream) {
+        res.writeHead(200, {
+            "Content-Type": "text/event-stream",
+            "Cache-Control": "no-cache",
+            Connection: "keep-alive",
+        });
+        const id = `chatcmpl-${randomUUID()}`;
+        // 首包：role + content 占位，与 DeepSeek 等一致，避免仅 role 时下游对 delta 的严格校验
+        res.write(buildStreamChunk(id, model, { role: "assistant", content: "" }, null));
+        let pendingToolCalls;
+        let finishReason = "stop";
+        try {
+            await chatCompletionStream(messages, tools, (chunk) => {
+                if (abortCtrl.signal.aborted)
+                    return;
+                if (chunk.content != null && chunk.content !== "") {
+                    const text = typeof chunk.content === "string" ? chunk.content : String(chunk.content);
+                    res.write(buildStreamChunk(id, model, { content: text }, null));
+                }
+                if (chunk.tool_calls?.length) {
+                    pendingToolCalls = chunk.tool_calls;
+                }
+                if (chunk.finish_reason) {
+                    finishReason = chunk.finish_reason;
+                }
+            }, abortCtrl.signal);
+        }
+        catch (e) {
+            if (!abortCtrl.signal.aborted) {
+                const errMsg = e instanceof Error ? e.message : String(e);
+                const stack = e instanceof Error ? e.stack : undefined;
+                console.error("[local-llm] stream error:", errMsg);
+                if (stack)
+                    console.error("[local-llm] stream stack:", stack);
+                res.write(`data: ${JSON.stringify({ error: { message: errMsg, type: "server_error" } })}\n\n`);
+            }
+            res.end();
+            return;
+        }
+        // 若有 tool_calls，按 OpenAI 流式规范发一条 delta（含 index/id/type/function），与 DeepSeek 等一致
+        if (pendingToolCalls?.length) {
+            const deltaToolCalls = pendingToolCalls.map((tc, i) => ({
+                index: i,
+                id: typeof tc.id === "string" ? tc.id : `call_${i}`,
+                type: "function",
+                function: {
+                    name: typeof tc.function?.name === "string" ? tc.function.name : "",
+                    arguments: typeof tc.function?.arguments === "string" ? tc.function.arguments : "",
+                },
+            }));
+            res.write(buildStreamChunk(id, model, { tool_calls: deltaToolCalls }, null));
+            finishReason = "tool_calls";
+        }
+        res.write(buildStreamChunk(id, model, {}, finishReason));
+        res.write("data: [DONE]\n\n");
+        res.end();
+    }
+    else {
+        try {
+            const result = await chatCompletion(messages, tools, abortCtrl.signal);
+            sendJson(res, 200, buildCompletionResponse(result.content, result.tool_calls, result.finish_reason, model));
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            sendError(res, 500, msg, "server_error");
+        }
+    }
+}
+async function handleEmbeddings(req, res) {
+    let body;
+    try {
+        body = await readBody(req);
+    }
+    catch {
+        return sendError(res, 400, "Invalid JSON body", "invalid_request_error");
+    }
+    if (!isReady())
+        return sendError(res, 503, "模型尚未加载完成，请稍后重试", "server_error");
+    const input = body.input;
+    if (input === undefined || input === null) {
+        return sendError(res, 400, "Missing 'input' (string or array of strings)", "invalid_request_error");
+    }
+    const inputs = Array.isArray(input) ? input : [input];
+    if (inputs.length === 0 || inputs.some((x) => typeof x !== "string")) {
+        return sendError(res, 400, "'input' must be a non-empty string or array of strings", "invalid_request_error");
+    }
+    try {
+        const data = await Promise.all(inputs.map(async (text, i) => ({
+            object: "embedding",
+            index: i,
+            embedding: await getEmbedding(text),
+        })));
+        sendJson(res, 200, {
+            object: "list",
+            data,
+            model: body.model ?? EMB_MODEL_ID,
+            usage: { prompt_tokens: 0, total_tokens: 0 },
+        });
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        sendError(res, 500, msg, "server_error");
+    }
+}
+function handleModels(_req, res) {
+    sendJson(res, 200, {
+        object: "list",
+        data: [
+            { id: LLM_MODEL_ID, object: "model", created: 0, owned_by: "local" },
+            { id: EMB_MODEL_ID, object: "model", created: 0, owned_by: "local" },
+        ],
+    });
+}
+export function createOpenAICompatServer(port) {
+    return new Promise((resolve, reject) => {
+        const server = createServer(async (req, res) => {
+            const url = req.url ?? "";
+            const method = req.method ?? "";
+            // CORS
+            res.setHeader("Access-Control-Allow-Origin", "*");
+            res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization");
+            if (method === "OPTIONS") {
+                res.writeHead(204);
+                res.end();
+                return;
+            }
+            try {
+                if (method === "GET" && url === "/v1/models") {
+                    handleModels(req, res);
+                }
+                else if (method === "POST" && url === "/v1/chat/completions") {
+                    await handleChatCompletions(req, res);
+                }
+                else if (method === "POST" && url === "/v1/embeddings") {
+                    await handleEmbeddings(req, res);
+                }
+                else {
+                    sendError(res, 404, `Not found: ${method} ${url}`, "invalid_request_error");
+                }
+            }
+            catch (e) {
+                if (!res.headersSent)
+                    sendError(res, 500, String(e));
+            }
+        });
+        server.listen(port, "127.0.0.1", () => {
+            console.log(`[local-llm] OpenAI 兼容服务已启动: http://127.0.0.1:${port}/v1`);
+            resolve();
+        });
+        server.on("error", reject);
+    });
+}

package/dist/core/mcp/adapter.d.ts

@@ -9,9 +9,11 @@ import type { McpClient } from "./client.js";
  * @param tool MCP tools/list 返回的项
  * @param client 已连接的 McpClient，用于 callTool
  * @param serverId 可选前缀，用于避免多 MCP 时工具名冲突
+ * @param maxResultTokens 可选，单次返回最大 token；超过则从尾部裁剪并打日志；不配置则不限制
  */
-export declare function mcpToolToToolDefinition(tool: McpTool, client: McpClient, serverId?: string): ToolDefinition;
+export declare function mcpToolToToolDefinition(tool: McpTool, client: McpClient, serverId?: string, maxResultTokens?: number): ToolDefinition;
 /**
  * 将某 MCP 客户端的全部工具转为 ToolDefinition 数组。
+ * @param maxResultTokens 可选，单次返回最大 token；不配置则不限制
  */
-export declare function mcpToolsToToolDefinitions(tools: McpTool[], client: McpClient, serverId?: string): ToolDefinition[];
+export declare function mcpToolsToToolDefinitions(tools: McpTool[], client: McpClient, serverId?: string, maxResultTokens?: number): ToolDefinition[];

package/dist/core/mcp/adapter.js

@@ -2,6 +2,7 @@
  * MCP Tool 转为 pi-coding-agent ToolDefinition 的适配层。
  */
 import { Type } from "@sinclair/typebox";
+import { truncateTextToMaxTokens } from "../tools/truncate-result.js";
 /** 通用参数：MCP 工具接受任意 JSON 对象作为 arguments */
 const McpToolParamsSchema = Type.Record(Type.String(), Type.Any());
 /**
@@ -9,8 +10,9 @@ const McpToolParamsSchema = Type.Record(Type.String(), Type.Any());
  * @param tool MCP tools/list 返回的项
  * @param client 已连接的 McpClient，用于 callTool
  * @param serverId 可选前缀，用于避免多 MCP 时工具名冲突
+ * @param maxResultTokens 可选，单次返回最大 token；超过则从尾部裁剪并打日志；不配置则不限制
  */
-export function mcpToolToToolDefinition(tool, client, serverId) {
+export function mcpToolToToolDefinition(tool, client, serverId, maxResultTokens) {
     const name = serverId ? `${serverId}_${tool.name}` : tool.name;
     const description = (tool.description ?? "").trim() || `MCP tool: ${tool.name}`;
     return {
@@ -22,10 +24,13 @@ export function mcpToolToToolDefinition(tool, client, serverId) {
             const args = params && typeof params === "object" ? params : {};
             try {
                 const result = await client.callTool(tool.name, args);
-                const text = result.content
+                let text = result.content
                     ?.filter((c) => c.type === "text")
                     .map((c) => c.text)
                     .join("\n") ?? (result.isError ? "MCP 调用返回错误" : "");
+                if (typeof maxResultTokens === "number" && maxResultTokens > 0) {
+                    text = truncateTextToMaxTokens(text, maxResultTokens, `MCP ${name}`);
+                }
                 return {
                     content: [{ type: "text", text }],
                     details: result.isError ? { isError: true } : undefined,
@@ -43,7 +48,8 @@ export function mcpToolToToolDefinition(tool, client, serverId) {
 }
 /**
  * 将某 MCP 客户端的全部工具转为 ToolDefinition 数组。
+ * @param maxResultTokens 可选，单次返回最大 token；不配置则不限制
  */
-export function mcpToolsToToolDefinitions(tools, client, serverId) {
-    return tools.map((t) => mcpToolToToolDefinition(t, client, serverId));
+export function mcpToolsToToolDefinitions(tools, client, serverId, maxResultTokens) {
+    return tools.map((t) => mcpToolToToolDefinition(t, client, serverId, maxResultTokens));
 }

package/dist/core/mcp/index.d.ts

@@ -17,4 +17,6 @@ export { mcpToolToToolDefinition, mcpToolsToToolDefinitions } from "./adapter.js
 export declare function createMcpToolsForSession(options: {
     mcpServers?: McpServerConfig[] | McpServersStandardFormat;
     sessionId?: string;
+    /** 单次 MCP 工具返回最大 token；不配置则不限制 */
+    mcpMaxResultTokens?: number;
 }): Promise<ToolDefinition[]>;

package/dist/core/mcp/index.js

@@ -19,5 +19,6 @@ export async function createMcpToolsForSession(options) {
         return [];
     return getMcpToolDefinitions(configs, {
         sessionId: options.sessionId,
+        maxResultTokens: options.mcpMaxResultTokens,
     });
 }

package/dist/core/mcp/operator.d.ts

@@ -18,6 +18,8 @@ export interface GetMcpToolDefinitionsOptions {
     initRetryDelayMs?: number;
     /** 会话 ID，用于经全局 sendSessionMessage 推送 MCP 进度系统消息 */
     sessionId?: string;
+    /** 单次 MCP 工具返回最大 token；超过则从尾部裁剪并打日志；不配置则不限制 */
+    maxResultTokens?: number;
 }
 /**
  * 为给定 MCP 服务器配置列表获取或创建客户端，并返回其工具对应的 ToolDefinition 数组。

package/dist/core/mcp/operator.js

@@ -113,7 +113,7 @@ export async function getMcpToolDefinitions(serverConfigs, options = {}) {
             try {
                 const tools = await client.listTools();
                 const serverId = `mcp${i}`;
-                const definitions = mcpToolsToToolDefinitions(tools, client, serverId);
+                const definitions = mcpToolsToToolDefinitions(tools, client, serverId, options.maxResultTokens);
                 allTools.push(...definitions);
                 toolsListed = true;
                 break;

package/dist/core/memory/local-embedding.d.ts

@@ -1,10 +1,11 @@
 /**
- * 本地 embedding：仅 node-llama-cpp (GGUF)。不可用时返回 null，由上层决定是否使用在线 RAG。
+ * 本地 embedding：优先走本地 LLM 子进程服务（/v1/embeddings），
+ * 不可用时回退到 node-llama-cpp 直接加载（GGUF）。
  */
 import type { IEmbeddingProvider } from "./embedding-types.js";
 export declare function getLocalEmbeddingUnavailableReason(): string | null;
 /**
- * 获取本地 embedding 提供方（懒加载，失败后不再重试）。
- * 仅使用 node-llama-cpp (GGUF)。不可用时返回 null。
+ * 获取本地 embedding 提供方（懒加载）。
+ * 优先使用本地 LLM 子进程服务；不可用时回退到 node-llama-cpp 直接加载。
  */
 export declare function getLocalEmbeddingProvider(): Promise<IEmbeddingProvider | null>;

package/dist/core/memory/local-embedding.js

@@ -5,19 +5,59 @@ let envLogged = false;
 export function getLocalEmbeddingUnavailableReason() {
     return getLocalEmbeddingLlamaUnavailableReason();
 }
+/** 通过本地 LLM 子进程服务的 /v1/embeddings 接口获取向量 */
+function createLocalServerEmbeddingProvider(baseUrl) {
+    return {
+        name: "local-llm-server",
+        async embed(text) {
+            try {
+                const res = await fetch(`${baseUrl}/embeddings`, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json", Authorization: "Bearer local" },
+                    body: JSON.stringify({ input: text }),
+                    signal: AbortSignal.timeout(30_000),
+                });
+                if (!res.ok)
+                    return null;
+                const data = await res.json();
+                const vec = data?.data?.[0]?.embedding;
+                return Array.isArray(vec) && vec.length > 0 ? vec : null;
+            }
+            catch {
+                return null;
+            }
+        },
+    };
+}
 /**
- * 获取本地 embedding 提供方（懒加载，失败后不再重试）。
- * 仅使用 node-llama-cpp (GGUF)。不可用时返回 null。
+ * 获取本地 embedding 提供方（懒加载）。
+ * 优先使用本地 LLM 子进程服务；不可用时回退到 node-llama-cpp 直接加载。
  */
 export async function getLocalEmbeddingProvider() {
     if (cached)
         return cached;
+    // 优先：本地 LLM 子进程服务
+    const localBaseUrl = process.env.LOCAL_LLM_BASE_URL;
+    if (localBaseUrl) {
+        const serverProvider = createLocalServerEmbeddingProvider(localBaseUrl);
+        // 快速探测服务是否可用
+        const testVec = await serverProvider.embed("test");
+        if (testVec !== null) {
+            cached = serverProvider;
+            if (!envLogged) {
+                envLogged = true;
+                console.log("[RAG embedding] 使用本地 LLM 子进程服务");
+            }
+            return cached;
+        }
+    }
+    // 回退：node-llama-cpp 直接加载
     const provider = await getLocalEmbeddingLlamaProvider(getRagLocalModelPathSync());
     if (provider) {
         cached = provider;
         if (!envLogged) {
             envLogged = true;
-            console.warn("[RAG embedding] 本地模型使用 node-llama-cpp (GGUF)");
+            console.log("[RAG embedding] 使用 node-llama-cpp (GGUF) 直接加载");
         }
         return cached;
     }

package/dist/core/tools/index.d.ts

@@ -6,3 +6,4 @@ export { createSwitchAgentTool } from "./switch-agent-tool.js";
 export { createListAgentsTool } from "./list-agents-tool.js";
 export { createCreateAgentTool } from "./create-agent-tool.js";
 export { createGetBookmarkTagsTool, createSaveBookmarkTool, createAddBookmarkTagTool, } from "./bookmark-tool.js";
+export { createWebSearchTool } from "./web-search/index.js";

package/dist/core/tools/index.js

@@ -6,3 +6,4 @@ export { createSwitchAgentTool } from "./switch-agent-tool.js";
 export { createListAgentsTool } from "./list-agents-tool.js";
 export { createCreateAgentTool } from "./create-agent-tool.js";
 export { createGetBookmarkTagsTool, createSaveBookmarkTool, createAddBookmarkTagTool, } from "./bookmark-tool.js";
+export { createWebSearchTool } from "./web-search/index.js";

package/dist/core/tools/truncate-result.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 工具返回结果按 token 估算截断：超过 maxTokens 时从尾部裁剪并打日志。
+ * 用于 MCP、web_search 等单次返回可能过大的场景。
+ */
+/** 粗略按字符估算 token（中英混合约 1/3） */
+export declare function estTokensFromChars(chars: number): number;
+/**
+ * 若 text 估算 token 超过 maxTokens，则保留前 maxTokens 对应字符并打日志，否则返回原 text。
+ * @param text 原始文本
+ * @param maxTokens 最大保留 token 数（仅当 > 0 时生效）
+ * @param toolLabel 工具标识，用于日志
+ * @returns 截断后的文本（可能为原 text）
+ */
+export declare function truncateTextToMaxTokens(text: string, maxTokens: number, toolLabel: string): string;

package/dist/core/tools/truncate-result.js

@@ -0,0 +1,27 @@
+/**
+ * 工具返回结果按 token 估算截断：超过 maxTokens 时从尾部裁剪并打日志。
+ * 用于 MCP、web_search 等单次返回可能过大的场景。
+ */
+const LOG_PREFIX = "[tool-result]";
+/** 粗略按字符估算 token（中英混合约 1/3） */
+export function estTokensFromChars(chars) {
+    return Math.ceil(chars / 3);
+}
+/**
+ * 若 text 估算 token 超过 maxTokens，则保留前 maxTokens 对应字符并打日志，否则返回原 text。
+ * @param text 原始文本
+ * @param maxTokens 最大保留 token 数（仅当 > 0 时生效）
+ * @param toolLabel 工具标识，用于日志
+ * @returns 截断后的文本（可能为原 text）
+ */
+export function truncateTextToMaxTokens(text, maxTokens, toolLabel) {
+    if (!text || maxTokens <= 0)
+        return text;
+    const est = estTokensFromChars(text.length);
+    if (est <= maxTokens)
+        return text;
+    const keepChars = Math.max(1, maxTokens * 3);
+    const truncated = text.slice(0, keepChars);
+    console.log(`${LOG_PREFIX} ${toolLabel} 返回超限 estTokens=${est} maxTokens=${maxTokens} 已从尾部裁剪，保留约 ${maxTokens} token`);
+    return truncated;
+}

package/dist/core/tools/web-search/create-web-search-tool.d.ts

@@ -0,0 +1,17 @@
+import type { ToolDefinition } from "@mariozechner/pi-coding-agent";
+export interface WebSearchToolOptions {
+    enabled: boolean;
+    provider: "brave" | "duck-duck-scrape";
+    apiKey?: string;
+    timeoutSeconds?: number;
+    cacheTtlMinutes?: number;
+    maxResults?: number;
+    /** 单次搜索返回内容最大 token；超过则从尾部裁剪并打日志；不配置则不限制 */
+    maxResultTokens?: number;
+}
+/**
+ * 创建 web_search 工具。
+ * - enabled 为 false 时返回 null，调用方不应将工具加入 customTools。
+ * - enabled 为 true 但当前 provider 不可用（如 Brave 无 Key）时仍返回工具，执行时空转，返回固定提示。
+ */
+export declare function createWebSearchTool(options: WebSearchToolOptions): ToolDefinition | null;

package/dist/core/tools/web-search/create-web-search-tool.js

@@ -0,0 +1,87 @@
+import { Type } from "@sinclair/typebox";
+import { getWebSearchProvider } from "./providers/index.js";
+import { truncateTextToMaxTokens } from "../truncate-result.js";
+const WebSearchSchema = Type.Object({
+    query: Type.String({
+        description: "搜索关键词或问题，例如：当前天气、最新新闻、某概念解释等",
+    }),
+    count: Type.Optional(Type.Number({
+        description: "返回结果条数，1-10，默认 5",
+        minimum: 1,
+        maximum: 10,
+    })),
+    country: Type.Optional(Type.String({
+        description: "可选，地区代码（如 us、cn），部分 Provider 支持",
+    })),
+    freshness: Type.Optional(Type.String({
+        description: "可选，时间范围（如 pd、pw、pm），部分 Provider 支持",
+    })),
+});
+const WEB_SEARCH_NOOP_MESSAGE = "当前在线搜索不可用：所选 Provider 未配置或不可用（如选择了 Brave 但未配置 API Key）。请在设置中配置 Brave API Key，或将智能体在线搜索 Provider 改为 DuckDuckGo。";
+/**
+ * 创建 web_search 工具。
+ * - enabled 为 false 时返回 null，调用方不应将工具加入 customTools。
+ * - enabled 为 true 但当前 provider 不可用（如 Brave 无 Key）时仍返回工具，执行时空转，返回固定提示。
+ */
+export function createWebSearchTool(options) {
+    if (!options || options.enabled !== true)
+        return null;
+    const provider = getWebSearchProvider(options.provider);
+    const apiKey = options.provider === "brave" ? options.apiKey : undefined;
+    const available = provider.isAvailable({ apiKey });
+    const timeoutSeconds = options.timeoutSeconds ?? 15;
+    const cacheTtlMinutes = options.cacheTtlMinutes ?? 5;
+    const maxResults = options.maxResults ?? 5;
+    return {
+        name: "web_search",
+        label: "Web Search",
+        description: "联网搜索：根据查询词从互联网获取最新结果（标题、链接、摘要）。无 API Key 时使用 DuckDuckGo；配置 Brave API Key 后可选用 Brave。在回答需要实时信息、新闻、天气、概念解释等问题前可调用本工具。",
+        parameters: WebSearchSchema,
+        execute: async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
+            if (!available) {
+                return {
+                    content: [{ type: "text", text: WEB_SEARCH_NOOP_MESSAGE }],
+                    details: undefined,
+                };
+            }
+            const query = (params.query ?? "").trim();
+            if (!query) {
+                return {
+                    content: [{ type: "text", text: "请提供搜索关键词（query）。" }],
+                    details: undefined,
+                };
+            }
+            const count = Math.min(10, Math.max(1, params.count ?? maxResults));
+            try {
+                const result = await provider.search({
+                    query,
+                    count,
+                    apiKey,
+                    timeoutSeconds,
+                    cacheTtlMinutes,
+                    country: params.country,
+                    freshness: params.freshness,
+                });
+                const lines = result.results.map((r, i) => `${i + 1}. ${r.title}\n   ${r.url}${r.description ? `\n   ${r.description}` : ""}`);
+                let text = (result.cached ? "[缓存] " : "") +
+                    `搜索「${result.query}」共 ${result.count} 条（${result.provider}${result.tookMs != null ? `, ${result.tookMs}ms` : ""}）：\n\n` +
+                    (lines.length ? lines.join("\n\n") : "未找到结果。");
+                const maxResultTokens = options.maxResultTokens;
+                if (typeof maxResultTokens === "number" && maxResultTokens > 0) {
+                    text = truncateTextToMaxTokens(text, maxResultTokens, "web_search");
+                }
+                return {
+                    content: [{ type: "text", text }],
+                    details: { query: result.query, count: result.count, provider: result.provider },
+                };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return {
+                    content: [{ type: "text", text: `在线搜索失败: ${msg}` }],
+                    details: undefined,
+                };
+            }
+        },
+    };
+}

package/dist/core/tools/web-search/index.d.ts

@@ -0,0 +1,4 @@
+export { createWebSearchTool } from "./create-web-search-tool.js";
+export type { WebSearchToolOptions } from "./create-web-search-tool.js";
+export type { WebSearchProviderId, WebSearchResultItem, WebSearchProviderResult, IWebSearchProvider, WebSearchSearchParams, } from "./types.js";
+export { getWebSearchProvider } from "./providers/index.js";

package/dist/core/tools/web-search/index.js

@@ -0,0 +1,2 @@
+export { createWebSearchTool } from "./create-web-search-tool.js";
+export { getWebSearchProvider } from "./providers/index.js";

package/dist/core/tools/web-search/providers/brave.d.ts

@@ -0,0 +1,2 @@
+import type { IWebSearchProvider } from "../types.js";
+export declare const braveProvider: IWebSearchProvider;