@next-open-ai/openclawx 0.8.36 → 0.8.40

package/dist/core/agent/proxy/adapters/opencode-adapter.js

@@ -20,7 +20,9 @@
  *   - opencode/big-pickle          — Big Pickle
  * 本适配器请求不传 model 时由 OpenCode 服务端使用上述配置的默认模型。详见 https://opencode.ai/docs/zen
  */
+import { join, resolve } from "path";
 import { createOpencodeClient } from "@opencode-ai/sdk";
+import { getOpenbotWorkspaceDir } from "../../agent-dir.js";
 import { ensureLocalOpencodeRunning } from "./opencode-local-runner.js";
 /** 单次请求与事件流超时。长任务（如 init 分析大项目、多轮工具调用）可能较久，故设 15 分钟 */
 const REQUEST_TIMEOUT_MS = 15 * 60 * 1000; // 15 min
@@ -85,6 +87,17 @@ function getOpenCodeConfig(config) {
         model: { providerID, modelID: modelID || "default" },
     };
 }
+/** 与 Claude Code 一致：未显式配置时使用智能体工作区路径 ~/.openbot/workspace/<workspace>/ */
+function getOpencodeWorkingDirectory(config) {
+    const custom = config.opencode?.workingDirectory;
+    if (typeof custom === "string" && custom.trim()) {
+        return resolve(custom.trim());
+    }
+    const w = config.workspace;
+    if (typeof w !== "string" || !w.trim())
+        return undefined;
+    return join(getOpenbotWorkspaceDir(), w.trim());
+}
 function buildAuthHeaders(oc) {
     const user = oc.username || DEFAULT_SERVER_USERNAME;
     const pass = oc.password ?? "";
@@ -208,7 +221,7 @@ function parseSlashCommand(message) {
     const args = space >= 0 ? rest.slice(space + 1).trim() : "";
     return command ? { command, args } : null;
 }
-/** 从 session.prompt / session.command 返回的 parts 提取文本 */
+/** 从 session.prompt / session.command 返回的 parts 提取文本（含所有 type，用于兼容旧逻辑） */
 function partsToText(parts) {
     if (!Array.isArray(parts))
         return "";
@@ -217,6 +230,17 @@ function partsToText(parts) {
         .filter(Boolean)
         .join("");
 }
+/** 仅取 type=text 的 part 拼接为助手正文，与流式时只推 text 保持一致，不包含 reasoning/step-start/step-finish */
+function partsToReplyText(parts) {
+    if (!Array.isArray(parts))
+        return "";
+    return parts
+        .filter((p) => p?.type === "text")
+        .map((p) => (typeof p.text === "string" ? p.text : typeof p.content === "string" ? p.content : ""))
+        .filter(Boolean)
+        .join("")
+        .trim();
+}
 /** 日志用：可序列化对象，避免循环引用、过长字符串和不可序列化字段 */
 function safeForLog(obj, maxStrLen = 2000) {
     if (obj === null || obj === undefined)
@@ -348,7 +372,7 @@ async function pollForAssistantMessage(session, sessionId) {
             const parts = item?.info?.parts ?? item?.parts;
             if (!Array.isArray(parts))
                 continue;
-            const text = partsToText(parts);
+            const text = partsToReplyText(parts);
             if (text)
                 return text;
             // 已有 assistant 但 parts 为空，可能仍在生成，继续轮询
@@ -367,7 +391,7 @@ export const opencodeAdapter = {
             throw new Error("OpenCode adapter: missing opencode.port or (remote 模式下缺少 address) in agent config");
         }
         if (config.opencode?.mode === "local" && config.opencode.port != null) {
-            await ensureLocalOpencodeRunning(Number(config.opencode.port), config.opencode.model?.trim() || undefined, config.opencode.workingDirectory?.trim() || undefined);
+            await ensureLocalOpencodeRunning(Number(config.opencode.port), config.opencode.model?.trim() || undefined, getOpencodeWorkingDirectory(config));
         }
         const hasPassword = Boolean(oc.password?.trim());
         const userSignal = options.signal;
@@ -538,15 +562,36 @@ export const opencodeAdapter = {
             let hadAnyChunk = false;
             let lastTextLength = 0;
             let eventCount = 0;
-            // 非 text 部分按 (messageID, partType) 记录上次已下发的完整内容，避免同一 part 多次相同事件导致前端重复显示
-            const lastEmittedNonText = new Map();
+            // reasoning 只缓存在见到 text 或 session.idle 时再整体输出一次，避免「先部分后完整」重复显示
+            const reasoningBuffer = new Map();
+            // 正文累积后去掉 [step-start]/[step-finish] 再推送，避免服务端把这类标签混在 text 里
+            let textAccumulated = "";
+            let lastEmittedCleanLen = 0;
+            const stepMarkerRe = /\n?\[step-(?:start|finish)\]\n?/g;
+            const emitStrippedText = () => {
+                const cleaned = textAccumulated.replace(stepMarkerRe, "");
+                const toEmit = cleaned.slice(lastEmittedCleanLen);
+                if (toEmit) {
+                    hadAnyChunk = true;
+                    callbacks.onChunk(toEmit);
+                    lastEmittedCleanLen = cleaned.length;
+                }
+            };
+            const flushReasoningForMessage = (messageID) => {
+                const raw = reasoningBuffer.get(messageID);
+                if (!raw?.trim())
+                    return;
+                reasoningBuffer.delete(messageID);
+                const formatted = `\n\n---\nreasoning: ${raw.slice(0, 2000)}${raw.length > 2000 ? "…" : ""}\n---\n\n`;
+                hadAnyChunk = true;
+                callbacks.onChunk(formatted);
+            };
             try {
                 for await (const event of eventStream) {
                     if (userSignal?.aborted)
                         break;
                     eventCount++;
                     const ev = event;
-                    // 日志：长任务排查时可见 OpenCode 下发了哪些事件类型与 part 类型，便于确认是否有中间状态未回显
                     if (ev.type !== "message.part.updated" || (ev.properties?.part?.type !== "text")) {
                         const partType = ev.properties?.part?.type ?? "(no part)";
                         console.log(`[OpenCode] event #${eventCount} type=${ev.type} part.type=${partType}`);
@@ -558,41 +603,32 @@ export const opencodeAdapter = {
                     if (ev.type === "message.part.updated" && ev.properties?.part?.sessionID === opencodeSessionId) {
                         const part = ev.properties.part;
                         if (userMessageID != null && part.messageID === userMessageID)
-                            continue; // 跳过用户消息的 part
+                            continue;
                         const partType = part.type ?? "";
                         const delta = ev.properties.delta;
                         const fullText = typeof part?.text === "string" ? part.text : "";
                         if (partType === "text") {
+                            const msgId = part.messageID ?? "";
+                            flushReasoningForMessage(msgId);
                             if (typeof delta === "string" && delta) {
-                                hadAnyChunk = true;
-                                callbacks.onChunk(delta);
-                                lastTextLength += delta.length;
+                                textAccumulated += delta;
+                                emitStrippedText();
                             }
                             else if (fullText.length > lastTextLength) {
-                                hadAnyChunk = true;
-                                callbacks.onChunk(fullText.slice(lastTextLength));
+                                textAccumulated = fullText;
                                 lastTextLength = fullText.length;
+                                emitStrippedText();
                             }
                         }
-                        else {
-                            // 非 text（如 reasoning、tool_call 等）：向前端回显简短状态；相同 part 相同内容只发一次，避免重复
-                            const key = `${part.messageID ?? ""}-${partType}`;
-                            if (fullText && fullText.trim()) {
-                                const formatted = `\n\n---\n${partType}: ${fullText.slice(0, 500)}${fullText.length > 500 ? "…" : ""}\n---\n\n`;
-                                if (lastEmittedNonText.get(key) === formatted)
-                                    continue;
-                                lastEmittedNonText.set(key, formatted);
-                                hadAnyChunk = true;
-                                callbacks.onChunk(formatted);
-                            }
-                            else if (partType) {
-                                // [tool]/[step-start]/[step-finish] 等无正文：每次事件都发（无法区分“同一事件重复”与“多次不同 tool/step”，故不做去重）
-                                hadAnyChunk = true;
-                                callbacks.onChunk(`\n[${partType}]\n`);
-                            }
+                        else if (partType === "reasoning" && fullText.trim()) {
+                            const msgId = part.messageID ?? "";
+                            reasoningBuffer.set(msgId, fullText);
                         }
+                        // step-start、step-finish、tool_call 等不推给前端
                     }
                     if (ev.type === "session.idle" && ev.properties?.sessionID === opencodeSessionId) {
+                        for (const msgId of reasoningBuffer.keys())
+                            flushReasoningForMessage(msgId);
                         console.log(`[OpenCode] session.idle after ${eventCount} events, hadAnyChunk=${hadAnyChunk}`);
                         break;
                     }
@@ -625,7 +661,7 @@ export const opencodeAdapter = {
             throw new Error("OpenCode adapter: missing opencode.port or (remote 模式下缺少 address) in agent config");
         }
         if (config.opencode?.mode === "local" && config.opencode.port != null) {
-            await ensureLocalOpencodeRunning(Number(config.opencode.port), config.opencode.model?.trim() || undefined, config.opencode.workingDirectory?.trim() || undefined);
+            await ensureLocalOpencodeRunning(Number(config.opencode.port), config.opencode.model?.trim() || undefined, getOpencodeWorkingDirectory(config));
         }
         const hasPassword = oc.password != null && String(oc.password).trim() !== "";
         const client = createOpencodeClient({

package/dist/core/agent/proxy/adapters/opencode-local-runner.js

@@ -3,6 +3,7 @@
  * 并通过 OPENCODE_CONFIG_CONTENT 注入默认模型与端口；可选设置工作目录（cwd）。
  */
 import { spawn } from "child_process";
+import { mkdirSync } from "node:fs";
 import { createInterface } from "readline";
 import { resolve } from "path";
 const HEALTH_PATH = "/global/health";
@@ -41,6 +42,14 @@ export async function ensureLocalOpencodeRunning(port, model, workingDirectory)
         ...process.env,
         OPENCODE_CONFIG_CONTENT: JSON.stringify(config),
     };
+    if (cwd) {
+        try {
+            mkdirSync(cwd, { recursive: true });
+        }
+        catch (e) {
+            console.warn("[OpenCode local runner] mkdir cwd failed:", e.message);
+        }
+    }
     const child = spawn("opencode", ["serve", "--port", String(port), "--hostname", "127.0.0.1"], {
         env,
         stdio: ["ignore", "pipe", "pipe"],

package/dist/core/agent/proxy/index.js

@@ -8,9 +8,11 @@ import { localAdapter } from "./adapters/local-adapter.js";
 import { cozeAdapter } from "./adapters/coze-adapter.js";
 import { openclawxAdapter } from "./adapters/openclawx-adapter.js";
 import { opencodeAdapter } from "./adapters/opencode-adapter.js";
+import { claudeCodeAdapter } from "./adapters/claude-code-adapter.js";
 registerAgentProxyAdapter(localAdapter);
 registerAgentProxyAdapter(cozeAdapter);
 registerAgentProxyAdapter(openclawxAdapter);
 registerAgentProxyAdapter(opencodeAdapter);
+registerAgentProxyAdapter(claudeCodeAdapter);
 export { runForChannelStream, runForChannelCollect } from "./run-for-channel.js";
 export { registerAgentProxyAdapter, getAgentProxyAdapter, listAgentProxyAdapterTypes } from "./registry.js";

package/dist/core/agent/token-usage-log-extension.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 内置 extension：在 turn_start / turn_end 和 compaction 相关事件时打印 context 用量与 compaction 信息，
+ * 便于分析 token 占用。仅打 log，不改变行为。
+ * 若 agent-manager 在 session 创建后调用了 setTokenUsageInitialStats，则每轮会打印 systemPrompt/skills/tools/conversation 的估算占比。
+ */
+import type { ExtensionFactory } from "@mariozechner/pi-coding-agent";
+export interface TokenUsageInitialStats {
+    systemPromptEstTokens: number;
+    skillsBlockEstTokens: number;
+    toolsDefsEstTokens: number;
+}
+/** 由 agent-manager 在 session 创建并算完 systemPrompt/skills/tools 后调用，供本 extension 在 turn 时打印占比 */
+export declare function setTokenUsageInitialStats(compositeKey: string, stats: TokenUsageInitialStats): void;
+export declare function createTokenUsageLogExtensionFactory(compositeKey: string): ExtensionFactory;

package/dist/core/agent/token-usage-log-extension.js

@@ -0,0 +1,61 @@
+const LOG_PREFIX = "[token-usage]";
+const initialStatsByKey = new Map();
+/** 由 agent-manager 在 session 创建并算完 systemPrompt/skills/tools 后调用，供本 extension 在 turn 时打印占比 */
+export function setTokenUsageInitialStats(compositeKey, stats) {
+    initialStatsByKey.set(compositeKey, stats);
+}
+function logContextBreakdown(phase, totalTokens, compositeKey) {
+    const stats = initialStatsByKey.get(compositeKey);
+    if (!stats || totalTokens <= 0)
+        return;
+    const { systemPromptEstTokens, skillsBlockEstTokens, toolsDefsEstTokens } = stats;
+    const conversationEst = Math.max(0, totalTokens - systemPromptEstTokens - toolsDefsEstTokens);
+    console.log(`${LOG_PREFIX} ${phase} breakdown | total=${totalTokens} systemPrompt≈${systemPromptEstTokens} (含skills≈${skillsBlockEstTokens}) tools≈${toolsDefsEstTokens} conversation≈${conversationEst}`);
+}
+export function createTokenUsageLogExtensionFactory(compositeKey) {
+    return (pi) => {
+        const on = pi.on.bind(pi);
+        on("turn_start", (_event, ctx) => {
+            const c = ctx;
+            try {
+                const usage = c?.getContextUsage?.();
+                if (usage && typeof usage.tokens === "number") {
+                    console.log(`${LOG_PREFIX} turn_start contextUsage.tokens=${usage.tokens} (估算，用于判断是否触发 compaction)`);
+                    logContextBreakdown("turn_start", usage.tokens, compositeKey);
+                }
+            }
+            catch {
+                // ignore
+            }
+        });
+        on("turn_end", (_event, ctx) => {
+            const c = ctx;
+            try {
+                const usage = c?.getContextUsage?.();
+                if (usage && typeof usage.tokens === "number") {
+                    console.log(`${LOG_PREFIX} turn_end contextUsage.tokens=${usage.tokens} (本轮结束后)`);
+                    logContextBreakdown("turn_end", usage.tokens, compositeKey);
+                }
+            }
+            catch {
+                // ignore
+            }
+        });
+        on("session_compact", (event) => {
+            const e = event;
+            const entry = e?.compactionEntry;
+            const tokensBefore = entry?.tokensBefore;
+            const summaryLen = typeof entry?.summary === "string" ? entry.summary.length : 0;
+            console.log(`${LOG_PREFIX} session_compact 已触发 tokensBefore=${tokensBefore ?? "?"} summaryChars=${summaryLen}`);
+        });
+        on("auto_compaction_start", (event) => {
+            const e = event;
+            console.log(`${LOG_PREFIX} auto_compaction_start 已触发 reason=${String(e?.reason ?? "?")}`);
+        });
+        on("auto_compaction_end", (event) => {
+            const e = event;
+            const { result, aborted, willRetry, errorMessage } = e ?? {};
+            console.log(`${LOG_PREFIX} auto_compaction_end 已结束 aborted=${aborted} willRetry=${willRetry} result=${result != null ? "ok" : "null"}${errorMessage ? ` error=${errorMessage}` : ""}`);
+        });
+    };
+}

package/dist/core/config/desktop-config.d.ts

@@ -56,8 +56,8 @@ export interface ChannelsConfig {
 export type DesktopMcpServerConfig = import("../mcp/index.js").McpServerConfig;
 /** MCP 标准 JSON 格式（key 为服务器名称），存储与 UI 可读写 */
 export type DesktopMcpServersStandardFormat = import("../mcp/index.js").McpServersStandardFormat;
-/** Agent 执行器类型：local=本机 pi-coding-agent，coze/openclawx/opencode=远程代理 */
-export type AgentRunnerType = "local" | "coze" | "openclawx" | "opencode";
+/** Agent 执行器类型：local=本机 pi-coding-agent，coze/openclawx/opencode=远程代理，claude_code=本机 Claude Code CLI */
+export type AgentRunnerType = "local" | "coze" | "openclawx" | "opencode" | "claude_code";
 /** Coze 站点：国内站 api.coze.cn / 国际站 api.coze.com，凭证不通用 */
 export type CozeRegion = "cn" | "com";
 /** 某站点的 Bot 凭证（国内/国际各自独立） */
@@ -90,6 +90,11 @@ export interface AgentOpenClawXConfig {
 }
 /** OpenCode 启动模式：local=由本应用按需启动本机服务；remote=连接已运行的远端服务 */
 export type OpenCodeServerMode = "local" | "remote";
+/** Claude Code CLI 代理配置（当 runnerType 为 claude_code 时使用） */
+export interface AgentClaudeCodeConfig {
+    /** 工作目录：Claude Code CLI 执行时的 cwd；留空则使用该智能体工作区路径 */
+    workingDirectory?: string;
+}
 /** OpenCode 代理配置：仅对接 [OpenCode 官方 Server API](https://opencode.ai/docs/server)（Session/Message + HTTP Basic） */
 export interface AgentOpenCodeConfig {
     /** 启动模式：local=本应用控制启动并可选设置默认模型；remote=连接已有服务 */
@@ -143,6 +148,8 @@ export interface DesktopAgentConfig {
     workspace?: string;
     /** MCP 服务器配置（数组或标准对象格式），创建 Session 时传入并归一化 */
     mcpServers?: DesktopMcpServerConfig[] | DesktopMcpServersStandardFormat;
+    /** MCP 单次返回最大 token；超过则从尾部裁剪；不配置则不限制 */
+    mcpMaxResultTokens?: number;
     /** 自定义系统提示词，会与技能等一起组成最终 systemPrompt */
     systemPrompt?: string;
     /** 执行器类型，缺省 local */
@@ -153,8 +160,21 @@ export interface DesktopAgentConfig {
     openclawx?: AgentOpenClawXConfig;
     /** OpenCode 代理配置 */
     opencode?: AgentOpenCodeConfig;
+    /** Claude Code CLI 代理配置 */
+    claudeCode?: AgentClaudeCodeConfig;
     /** 是否使用经验（长记忆）；默认 true */
     useLongMemory?: boolean;
+    /** 在线搜索：解析后的运行时配置，仅当 runnerType 为 local 时用于注册 web_search 工具 */
+    webSearch?: {
+        enabled: boolean;
+        provider: "brave" | "duck-duck-scrape";
+        apiKey?: string;
+        timeoutSeconds: number;
+        cacheTtlMinutes: number;
+        maxResults: number;
+        /** 单次搜索返回最大 token；超过则从尾部裁剪；不配置则不限制 */
+        maxResultTokens?: number;
+    };
 }
 /**
  * 从 config.json 读取缺省智能体 id（defaultAgentId）。

package/dist/core/config/desktop-config.js

@@ -220,6 +220,7 @@ export async function loadDesktopAgentConfig(agentId) {
     }
     let workspaceName = resolvedAgentId;
     let mcpServers;
+    let mcpMaxResultTokens;
     let systemPrompt;
     let useLongMemory = true;
     if (existsSync(agentsPath)) {
@@ -233,6 +234,9 @@ export async function loadDesktopAgentConfig(agentId) {
                     workspaceName = agent.workspace;
                 else if (agent.id)
                     workspaceName = agent.id;
+                if (agent.mcpMaxResultTokens != null && typeof agent.mcpMaxResultTokens === "number" && agent.mcpMaxResultTokens > 0) {
+                    mcpMaxResultTokens = agent.mcpMaxResultTokens;
+                }
                 if (agent.mcpServers != null) {
                     if (Array.isArray(agent.mcpServers) || (typeof agent.mcpServers === "object" && !Array.isArray(agent.mcpServers))) {
                         mcpServers = agent.mcpServers;
@@ -276,6 +280,19 @@ export async function loadDesktopAgentConfig(agentId) {
     let coze;
     let openclawx;
     let opencode;
+    let claudeCode;
+    const tw = config.tools?.webSearch;
+    const timeoutSeconds = typeof tw?.timeoutSeconds === "number" && tw.timeoutSeconds > 0 ? tw.timeoutSeconds : 15;
+    const cacheTtlMinutes = typeof tw?.cacheTtlMinutes === "number" && tw.cacheTtlMinutes >= 0 ? tw.cacheTtlMinutes : 5;
+    const maxResultsRaw = typeof tw?.maxResults === "number" ? tw.maxResults : 5;
+    const maxResults = Math.min(10, Math.max(1, maxResultsRaw));
+    let webSearch = {
+        enabled: false,
+        provider: "duck-duck-scrape",
+        timeoutSeconds,
+        cacheTtlMinutes,
+        maxResults,
+    };
     if (existsSync(agentsPath)) {
         try {
             const rawAgents = await readFile(agentsPath, "utf-8");
@@ -285,9 +302,16 @@ export async function loadDesktopAgentConfig(agentId) {
             if (agentRow) {
                 if (agentRow.runnerType === "coze" ||
                     agentRow.runnerType === "openclawx" ||
-                    agentRow.runnerType === "opencode") {
+                    agentRow.runnerType === "opencode" ||
+                    agentRow.runnerType === "claude_code") {
                     runnerType = agentRow.runnerType;
                 }
+                if (agentRow.runnerType === "claude_code") {
+                    const wd = agentRow.claudeCode?.workingDirectory;
+                    claudeCode = {
+                        workingDirectory: typeof wd === "string" && wd.trim() ? wd.trim() : undefined,
+                    };
+                }
                 if (agentRow.coze) {
                     const row = agentRow.coze;
                     const region = row.region === "cn" || row.region === "com" ? row.region : "com";
@@ -353,6 +377,35 @@ export async function loadDesktopAgentConfig(agentId) {
                         }
                     }
                 }
+                if (agentRow.webSearch?.enabled === true) {
+                    let preferredProvider = agentRow.webSearch?.provider === "brave" || agentRow.webSearch?.provider === "duck-duck-scrape"
+                        ? agentRow.webSearch.provider
+                        : tw?.defaultProvider === "brave" || tw?.defaultProvider === "duck-duck-scrape"
+                            ? tw.defaultProvider
+                            : "duck-duck-scrape";
+                    let braveKey;
+                    if (preferredProvider === "brave") {
+                        braveKey =
+                            (typeof tw?.providers?.brave?.apiKey === "string" && tw.providers.brave.apiKey.trim()
+                                ? tw.providers.brave.apiKey.trim()
+                                : undefined) ??
+                                (process.env.BRAVE_API_KEY && process.env.BRAVE_API_KEY.trim() ? process.env.BRAVE_API_KEY.trim() : undefined);
+                        if (!braveKey)
+                            preferredProvider = "duck-duck-scrape";
+                    }
+                    const maxResultTokens = agentRow.webSearch?.maxResultTokens != null && typeof agentRow.webSearch?.maxResultTokens === "number" && agentRow.webSearch.maxResultTokens > 0
+                        ? agentRow.webSearch.maxResultTokens
+                        : undefined;
+                    webSearch = {
+                        enabled: true,
+                        provider: preferredProvider,
+                        apiKey: preferredProvider === "brave" ? braveKey : undefined,
+                        timeoutSeconds,
+                        cacheTtlMinutes,
+                        maxResults,
+                        maxResultTokens,
+                    };
+                }
             }
         }
         catch {
@@ -365,12 +418,15 @@ export async function loadDesktopAgentConfig(agentId) {
         apiKey: apiKey ?? undefined,
         workspace: workspaceName,
         mcpServers,
+        mcpMaxResultTokens,
         systemPrompt,
         runnerType,
         coze,
         openclawx,
         opencode,
+        claudeCode,
         useLongMemory,
+        webSearch,
     };
 }
 function ensureDesktopDir() {

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

@@ -0,0 +1 @@
+export { loadExtensionFactories, clearExtensionFactoriesCache } from "./load.js";

package/dist/core/extensions/index.js

@@ -0,0 +1 @@
+export { loadExtensionFactories, clearExtensionFactoriesCache } from "./load.js";

package/dist/core/extensions/load.d.ts

@@ -0,0 +1,11 @@
+import type { ExtensionFactory } from "@mariozechner/pi-coding-agent";
+/**
+ * 扫描 ~/.openbot/plugins，加载所有已安装的扩展包，返回 ExtensionFactory 数组。
+ * 进程内缓存结果；若需重载可调用 clearExtensionFactoriesCache()。
+ */
+export declare function loadExtensionFactories(): ExtensionFactory[];
+/**
+ * 清除扩展 factory 缓存，下次 loadExtensionFactories() 时会重新扫描并加载。
+ * 用于安装/卸载扩展后希望不重启即生效的场景（若调用方在适当时机调用）。
+ */
+export declare function clearExtensionFactoriesCache(): void;

package/dist/core/extensions/load.js

@@ -0,0 +1,101 @@
+/**
+ * 从 ~/.openbot/plugins 目录加载通过 openbot extension install 安装的 npm 包，
+ * 将每个包的默认导出规范为 ExtensionFactory 并返回，供 AgentManager 注入到 DefaultResourceLoader.extensionFactories。
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { getOpenbotPluginsDir } from "../agent/agent-dir.js";
+let cachedFactories = null;
+/**
+ * 从插件目录的 package.json 读取 dependencies（及 optionalDependencies）的包名列表。
+ * 仅返回在 node_modules 中实际存在的包名。
+ */
+function getInstalledPluginNames(pluginsDir) {
+    const pkgPath = join(pluginsDir, "package.json");
+    if (!existsSync(pkgPath))
+        return [];
+    let pkg;
+    try {
+        pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    }
+    catch {
+        return [];
+    }
+    const deps = {
+        ...pkg.dependencies,
+        ...pkg.optionalDependencies,
+    };
+    const names = Object.keys(deps || {});
+    return names.filter((name) => {
+        const dir = join(pluginsDir, "node_modules", name);
+        return existsSync(dir);
+    });
+}
+/**
+ * 将包默认导出规范为 ExtensionFactory：(pi) => void。
+ * 插件可导出 (pi) => void 或 () => (pi) => void（工厂），此处统一为 (pi) => void。
+ */
+function toExtensionFactory(fn) {
+    if (typeof fn !== "function")
+        return null;
+    if (fn.length === 1)
+        return fn; // (pi) => void
+    if (fn.length === 0) {
+        const result = fn();
+        if (typeof result === "function")
+            return result; // () => (pi) => void
+    }
+    return null;
+}
+/**
+ * 加载单个插件包，返回 ExtensionFactory 或 null（失败时打日志并返回 null）。
+ * 使用 require(pkgName) 从 plugins 目录的 node_modules 解析，以便插件自身依赖正确解析。
+ */
+function loadOnePlugin(pluginsDir, pkgName) {
+    const require = createRequire(join(pluginsDir, "package.json"));
+    let mod;
+    try {
+        mod = require(pkgName);
+    }
+    catch (err) {
+        console.warn(`[extensions] Failed to load plugin "${pkgName}":`, err);
+        return null;
+    }
+    const def = mod && typeof mod === "object" && "default" in mod ? mod.default : mod;
+    const factory = toExtensionFactory(def);
+    if (!factory) {
+        console.warn(`[extensions] Plugin "${pkgName}" default export is not a function; skipped.`);
+        return null;
+    }
+    return factory;
+}
+/**
+ * 扫描 ~/.openbot/plugins，加载所有已安装的扩展包，返回 ExtensionFactory 数组。
+ * 进程内缓存结果；若需重载可调用 clearExtensionFactoriesCache()。
+ */
+export function loadExtensionFactories() {
+    if (cachedFactories !== null)
+        return cachedFactories;
+    const pluginsDir = getOpenbotPluginsDir();
+    if (!existsSync(pluginsDir)) {
+        cachedFactories = [];
+        return cachedFactories;
+    }
+    const names = getInstalledPluginNames(pluginsDir);
+    const factories = [];
+    for (const name of names) {
+        const factory = loadOnePlugin(pluginsDir, name);
+        if (factory)
+            factories.push(factory);
+    }
+    cachedFactories = factories;
+    return factories;
+}
+/**
+ * 清除扩展 factory 缓存，下次 loadExtensionFactories() 时会重新扫描并加载。
+ * 用于安装/卸载扩展后希望不重启即生效的场景（若调用方在适当时机调用）。
+ */
+export function clearExtensionFactoriesCache() {
+    cachedFactories = null;
+}

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 数组。