aws-runtime-bridge 1.9.32 → 1.9.40

package/package/acode/dist/runtime.js

@@ -1,13 +1,21 @@
 import { EventEmitter } from "node:events";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { createBuiltInFileTools, } from "./built-in-file-tools.js";
+import { ASK_USER_QUESTION_TOOL_NAME, createAskUserQuestionTool, } from "./ask-user-question-tool.js";
+import { createSkillTool } from "./skill-tool.js";
+import { createTodoWriteTool, createTodoReadTool } from "./todo-tool.js";
+import { createSubAgentTools } from "./sub-agent-tools.js";
 import { cleanupAcodeCmdDist } from "./builtins/commandArtifacts.js";
 import { loadAcodeCommands } from "./commands/commandLoader.js";
 import { ACodeCommandRegistry } from "./commands/commandRegistry.js";
-import { loadAcodeConfig, loadAcodeSkills } from "./config.js";
+import { calculateCompactionThreshold, COMPACTION_LLM_PROMPT_TEMPLATE, conversationSizeKB, estimateConversationTokens, performCompaction, pruneToolOutputs, summarizeConversation, } from "./compaction.js";
+import { loadAcodeConfig, loadAcodeSkillGroup } from "./config.js";
 import { ACodeHookBus, findDeniedHookResult } from "./hooks/hookBus.js";
 import { isMcpPollingToolName } from "./mcpToolNames.js";
 function cloneChatContentPart(part) {
@@ -67,10 +75,26 @@ const DEFAULT_BASH_BUILT_IN_TOOL_TIMEOUT_MS = 10 * 60_000 + 2000;
 const DEFAULT_RUNTIME_SHUTDOWN_TIMEOUT_MS = 10_000;
 const MAX_INLINE_IMAGE_BYTES = 10 * 1024 * 1024;
 const MAX_REQUEST_BODY_BYTES = 800 * 1024;
-const CONTEXT_COMPACTION_RECENT_MESSAGE_COUNT = 12;
-const CONTEXT_COMPACTION_MAX_SUMMARY_CHARS = 6000;
-const CONTEXT_COMPACTION_MAX_PREVIEW_CHARS = 500;
-const CONTEXT_COMPACTION_SUMMARY_PREFIX = "ACode context compaction summary:";
+/**
+ * 上下文压缩调试日志开关：仅当设置环境变量 ACODE_COMPACTION_DEBUG=1 时启用。
+ * 默认关闭，避免生产环境同步写盘阻塞事件循环。
+ */
+const COMPACTION_DEBUG_ENABLED = process.env.ACODE_COMPACTION_DEBUG === "1";
+const COMPACTION_DEBUG_LOG = COMPACTION_DEBUG_ENABLED
+    ? path.join(os.tmpdir(), "acode-compaction-debug.log")
+    : "";
+/**
+ * Runtime 调试日志：受 ACODE_COMPACTION_DEBUG=1 开关控制。
+ * 默认关闭以避免生产环境同步写盘阻塞事件循环、泄漏用户消息内容。
+ * 文件中所有原 `console.log` 调用均改为走此 helper。
+ */
+function runtimeDebugLog(...args) {
+    if (!COMPACTION_DEBUG_ENABLED)
+        return;
+    console.log(...args);
+}
+/** 当 provider 未配置 contextLimit 时使用的默认值 */
+const FALLBACK_CONTEXT_LIMIT = 64_000;
 async function withTimeout(operation, timeoutMs, label, onTimeout) {
     if (timeoutMs <= 0) {
         return await operation;
@@ -393,38 +417,6 @@ function contentPreview(content) {
         .join(" ")
         .trim();
 }
-function truncateText(value, maxChars) {
-    if (value.length <= maxChars) {
-        return value;
-    }
-    return `${value.slice(0, maxChars)}…`;
-}
-function summarizeToolCalls(toolCalls) {
-    if (!toolCalls || toolCalls.length === 0) {
-        return "";
-    }
-    return toolCalls
-        .map((toolCall) => {
-        const args = truncateText(toolCall.function.arguments.replace(/\s+/g, " ").trim(), 160);
-        return `${toolCall.function.name}(${args})`;
-    })
-        .join(", ");
-}
-function summarizeConversationMessage(message, index) {
-    const preview = truncateText(contentPreview(message.content).replace(/\s+/g, " ").trim(), CONTEXT_COMPACTION_MAX_PREVIEW_CHARS);
-    const toolCalls = summarizeToolCalls(message.tool_calls);
-    const parts = [`${index + 1}. ${message.role}`];
-    if (toolCalls) {
-        parts.push(`tool_calls=${toolCalls}`);
-    }
-    if (message.tool_call_id) {
-        parts.push(`tool_call_id=${message.tool_call_id}`);
-    }
-    if (preview) {
-        parts.push(`content=${preview}`);
-    }
-    return parts.join(" | ");
-}
 /**
  * 解析 ACode 工具权限配置。
  * 主流程：运行时配置优先 -> `.acode/config.json` 次之 -> 兼容旧式 allowedTools/deniedTools 字段。
@@ -530,6 +522,10 @@ function coerceArguments(rawArguments) {
     }
 }
 function getBuiltInToolTimeoutMs(tool, args, fallbackTimeoutMs) {
+    // ask_user_question 工具阻塞等待用户回答，不受超时限制
+    if (tool.toolName === ASK_USER_QUESTION_TOOL_NAME) {
+        return 0;
+    }
     if (tool.toolName !== "Bash") {
         return fallbackTimeoutMs;
     }
@@ -594,12 +590,16 @@ function estimateMessageSizeBytes(message) {
     }
     return size;
 }
-function isContextCompactionSummaryMessage(message) {
-    return (message.role === "system" &&
-        typeof message.content === "string" &&
-        message.content.startsWith(CONTEXT_COMPACTION_SUMMARY_PREFIX));
-}
-function truncateConversationIfNeeded(conversation, maxBytes) {
+/**
+ * 按字节大小截断对话，防止 HTTP 请求体过大。
+ * 这是与 token 压缩不同的关注点：即使 token 在上下文窗口内，
+ * HTTP 请求体也可能因 base64 图片等内容超过网关限制。
+ * 使用 compaction 模块的 performCompaction 进行压缩。
+ *
+ * ★ 支持 LLM 摘要器（与 performCompaction 一致）：
+ *   若提供 llmSummarizer，则 summarize 阶段使用 LLM 生成语义化摘要。
+ */
+async function truncateConversationIfNeeded(conversation, maxBytes, contextLimit, maxOutput, llmSummarizer) {
     let totalBytes = 0;
     for (const message of conversation) {
         totalBytes += estimateMessageSizeBytes(message);
@@ -607,52 +607,14 @@ function truncateConversationIfNeeded(conversation, maxBytes) {
     if (totalBytes <= maxBytes) {
         return 0;
     }
-    return compactConversationForRequestLimit(conversation, maxBytes);
-}
-function compactConversationForRequestLimit(conversation, maxBytes) {
-    const baseSystemMessages = conversation.filter((m) => m.role === "system" && !isContextCompactionSummaryMessage(m));
-    const compactableMessages = conversation.filter((m) => m.role !== "system" || isContextCompactionSummaryMessage(m));
-    const keptMessages = [];
-    let keptBytes = baseSystemMessages.reduce((sum, m) => sum + estimateMessageSizeBytes(m), 0);
-    for (let i = compactableMessages.length - 1; i >= 0; i--) {
-        const messageSize = estimateMessageSizeBytes(compactableMessages[i]);
-        if (keptBytes + messageSize > maxBytes && keptMessages.length > 0) {
-            break;
-        }
-        keptBytes += messageSize;
-        keptMessages.unshift(compactableMessages[i]);
-    }
-    return compactConversationWithSummary(conversation, compactableMessages.length - keptMessages.length);
-}
-function compactConversationForContextOverflow(conversation) {
-    const compactableMessages = conversation.filter((m) => m.role !== "system" || isContextCompactionSummaryMessage(m));
-    const removableCount = Math.max(0, compactableMessages.length - CONTEXT_COMPACTION_RECENT_MESSAGE_COUNT);
-    return compactConversationWithSummary(conversation, removableCount);
-}
-function compactConversationWithSummary(conversation, requestedRemovedCount) {
-    const baseSystemMessages = conversation.filter((m) => m.role === "system" && !isContextCompactionSummaryMessage(m));
-    const compactableMessages = conversation.filter((m) => m.role !== "system" || isContextCompactionSummaryMessage(m));
-    const removedCount = Math.max(0, Math.min(requestedRemovedCount, compactableMessages.length));
-    if (removedCount === 0) {
-        return 0;
-    }
-    const removedMessages = compactableMessages.slice(0, removedCount);
-    const keptMessages = compactableMessages.slice(removedCount);
-    const summaryLines = removedMessages.map((message, index) => summarizeConversationMessage(message, index));
-    const summary = truncateText(summaryLines.join("\n"), CONTEXT_COMPACTION_MAX_SUMMARY_CHARS);
-    conversation.length = 0;
-    conversation.push(...baseSystemMessages);
-    conversation.push({
-        role: "system",
-        content: [
-            CONTEXT_COMPACTION_SUMMARY_PREFIX,
-            `${removedCount} earlier compactable conversation messages were summarized to keep the provider request within context limits.`,
-            "Preserve the user's goal, decisions, tool results, file paths, errors, and unresolved tasks from this summary. Recent messages below remain authoritative.",
-            summary,
-        ].join("\n"),
+    const result = await performCompaction(conversation, contextLimit, maxOutput, {
+        llmSummarizer,
     });
-    conversation.push(...keptMessages);
-    return removedCount;
+    if (result.strategy !== "none") {
+        return result.prunedToolMessages + result.summarizedMessages;
+    }
+    // performCompaction 未生效时，强制 summarize
+    return summarizeConversation(conversation, { llmSummarizer, contextLimit });
 }
 function isContextOverflowProviderRequestError(error) {
     const message = getErrorMessage(error).toLowerCase();
@@ -742,10 +704,10 @@ function buildSkillPrompt(skills) {
         return "";
     }
     return [
-        "Available skills:",
-        ...skills.map((skill) => `- ${skill.name}${skill.description ? `: ${skill.description}` : ""}`),
-        "Use these skills as guidance when they match the user task.",
-    ].join("\n");
+        "Skills are available for this session.",
+        "Use the `skill` tool to load specialized skill instructions when a user task matches one of the available skills listed in the tool description.",
+        "Do not attempt to follow skill instructions from memory — always invoke the `skill` tool first to load the full content.",
+    ].join(" ");
 }
 function buildCommandPrompt(commands) {
     if (commands.length === 0) {
@@ -757,6 +719,49 @@ function buildCommandPrompt(commands) {
         "When the user invokes a slash command, ACode expands it before model execution.",
     ].join("\n");
 }
+/**
+ * 格式化 profile 信息为文本，供 rolePrompt 拼接使用。
+ * 主流程：提取关键字段并格式化为可读文本，返回空字符串当 profile 为空。
+ */
+function buildProfilePrompt(profile) {
+    if (!profile || typeof profile !== "object") {
+        return "";
+    }
+    const p = profile;
+    const parts = [];
+    const displayName = p.displayName;
+    const roleName = p.roleName;
+    const instanceName = p.instanceName;
+    const projectName = p.projectName;
+    const workspacePath = p.workspacePath;
+    const runtimeMode = p.runtimeMode;
+    const describe = p.describe;
+    if (typeof displayName === "string" && displayName.trim()) {
+        parts.push(`Display Name: ${displayName.trim()}`);
+    }
+    if (typeof roleName === "string" && roleName.trim()) {
+        parts.push(`Role: ${roleName.trim()}`);
+    }
+    if (typeof instanceName === "string" && instanceName.trim()) {
+        parts.push(`Instance: ${instanceName.trim()}`);
+    }
+    if (typeof projectName === "string" && projectName.trim()) {
+        parts.push(`Project: ${projectName.trim()}`);
+    }
+    if (typeof workspacePath === "string" && workspacePath.trim()) {
+        parts.push(`Workspace: ${workspacePath.trim()}`);
+    }
+    if (typeof runtimeMode === "string" && runtimeMode.trim()) {
+        parts.push(`Runtime Mode: ${runtimeMode.trim()}`);
+    }
+    if (typeof describe === "string" && describe.trim()) {
+        parts.push(`Description: ${describe.trim()}`);
+    }
+    if (parts.length === 0) {
+        return "";
+    }
+    return ["[User Profile]", ...parts].join("\n");
+}
 function toOpenAiTools(tools) {
     return tools.map((tool) => ({
         type: "function",
@@ -854,6 +859,8 @@ export class ACodeRuntime extends EventEmitter {
             commands: [],
             commandRegistry: new ACodeCommandRegistry([]),
             conversation: [],
+            accumulatedInputTokens: 0,
+            accumulatedOutputTokens: 0,
         };
         this.abortController = null;
         this.submitQueue = Promise.resolve();
@@ -862,6 +869,20 @@ export class ACodeRuntime extends EventEmitter {
         this.sessionCompleteEmitted = false;
         this.contextVersion = 0;
         this.stopWaiters = new Set();
+        /** 上下文压缩调试定时器（每 5 秒输出一次） */
+        this.compactionDebugTimer = null;
+        /** 可动态刷新的 SkillTool 引用（含 refresh 方法），运行中变更时调用其 refresh */
+        this.skillTool = null;
+        /** 监听 skills 目录变更的 FSWatcher 列表 */
+        this.skillWatchers = [];
+        /** skill 目录变更后的防抖定时器，避免短时间多次触发重扫 */
+        this.skillRefreshTimer = null;
+        /**
+         * ask_user_question 工具的挂起等待队列。
+         * key: toolCallId；value: resolve/reject 回调 + 创建时的 contextVersion。
+         * submitQuestionAnswer() 调用时 resolve；abort/stop/supersede 时 reject。
+         */
+        this.questionWaiters = new Map();
         this.hookBus = new ACodeHookBus({
             sessionId: config.sessionId,
             onError: (event, error) => {
@@ -883,6 +904,44 @@ export class ACodeRuntime extends EventEmitter {
         };
         this.emit("event", event);
     }
+    /**
+     * 发射压缩子事件（phase 事件）到面板时间线。
+     * 子事件通过 parentId 关联到父压缩事件，在前端以嵌套子元素形式展示。
+     *
+     * @param compactionId 父压缩事件 ID
+     * @param phase 阶段标识（detect/prune/prune_done/summarize/summarize_done）
+     * @param phaseLabel 阶段显示标签（如"阶段1: 裁剪工具输出"）
+     * @param phaseDetail 阶段详情（如"裁剪了 5 条工具输出"）
+     */
+    emitCompactionPhase(compactionId, phase, phaseLabel, phaseDetail) {
+        this.emitAcodeEvent("context_compaction", {
+            action: "phase",
+            compactionId,
+            parentId: compactionId,
+            phase,
+            phaseLabel,
+            phaseDetail,
+        });
+    }
+    /**
+     * performCompaction 的 onPhase 回调处理：将 CompactionPhaseEvent 转换为面板子事件。
+     */
+    handleCompactionPhase(compactionId, event) {
+        switch (event.phase) {
+            case "prune_start":
+                this.emitCompactionPhase(compactionId, "prune", "阶段1: 裁剪工具输出", `正在裁剪 ${event.messageCount ?? 0} 条消息中的工具输出...`);
+                break;
+            case "prune_end":
+                this.emitCompactionPhase(compactionId, "prune_done", "阶段1: 裁剪工具输出", `裁剪了 ${event.prunedCount ?? 0} 条工具输出, 释放 ${event.freedTokens ?? 0} tokens`);
+                break;
+            case "summarize_start":
+                this.emitCompactionPhase(compactionId, "summarize", "阶段2: 摘要化对话", `正在摘要 ${event.messageCount ?? 0} 条早期对话...`);
+                break;
+            case "summarize_end":
+                this.emitCompactionPhase(compactionId, "summarize_done", "阶段2: 摘要化对话", `摘要化了 ${event.summarizedCount ?? 0} 条消息${event.usedLLM ? " (LLM 摘要)" : " (规则摘要)"}`);
+                break;
+        }
+    }
     /**
      * 启动 ACode headless 会话。
      * 主流程：加载 `.acode/config.json` 与 skills 目录 -> 发出 MCP/Skill 状态 ->
@@ -890,20 +949,42 @@ export class ACodeRuntime extends EventEmitter {
      */
     async start() {
         const acodeConfig = await loadAcodeConfig(this.config.configPath);
-        const skills = await loadAcodeSkills(this.config.skillsDir);
+        // Skills 来源（按优先级，后加载的覆盖先加载的同名 skill）：
+        //   1. 全局目录（~/.acode/skills，由 config.skillsDir 指定）
+        //   2. 项目目录（<workingDirectory>/.acode/skills）
+        //   3. 项目目录（<workingDirectory>/.agentswork/skills）
+        // 各目录的 skills 合并后供 SkillTool / prompt 使用；分组信息供前端按目录展示。
+        // 即使目录不存在也会作为空节点返回，前端按目录展示。
+        const { skills, skillGroups, watchedDirs } = await this.loadAllSkills();
         const provider = resolveProviderConfig(this.config, acodeConfig);
         // [DEBUG] ACode Runtime 最终解析的 provider 配置（写入 stdout，bridge 会捕获）
-        console.log(`[ACodeRuntime] ★★★ DEBUG ★★★ resolveProviderConfig 结果: config.model=${this.config.model ?? "(undefined)"}, ` +
+        runtimeDebugLog(`[ACodeRuntime] ★★★ DEBUG ★★★ resolveProviderConfig 结果: config.model=${this.config.model ?? "(undefined)"}, ` +
             `resolvedModel=${provider.model}, baseURL=${provider.baseURL ?? "(none)"}, apiKey=${provider.apiKey ? "[set]" : "(none)"}, ` +
             `configPath=${this.config.configPath ?? "(none)"}`);
         const permissions = resolvePermissionConfig(this.config, acodeConfig);
         const mcpConnections = await this.connectMcpServers(acodeConfig.mcpServers ?? {}, provider.mcpToolTimeoutMs);
+        // 获取用户 profile 信息并拼接在 rolePrompt 下方
+        const profilePrompt = await this.fetchProfilePrompt(mcpConnections);
         const agentId = this.config.agentId || "unknown";
         // 重启时清理旧 spillover 输出
         void cleanupAcodeCmdDist(agentId);
         const builtInTools = createBuiltInFileTools(this.config.workingDirectory, agentId);
+        const askUserQuestionTool = createAskUserQuestionTool(this.buildAskUserQuestionDeps(), () => this.contextVersion);
+        const skillTool = createSkillTool(skills);
+        this.skillTool = skillTool;
+        const todoWriteTool = createTodoWriteTool(agentId);
+        const todoReadTool = createTodoReadTool(agentId);
+        // 注册 sub-agent 工具集（仅当注入了 subAgentManager）
+        const subAgentTools = this.config.subAgentManager
+            ? createSubAgentTools(this.buildSubAgentToolDeps(this.config.subAgentManager))
+            : [];
         const exposedTools = [
             ...builtInTools,
+            askUserQuestionTool,
+            skillTool,
+            todoWriteTool,
+            todoReadTool,
+            ...subAgentTools,
             ...mcpConnections.flatMap((connection) => connection.tools),
         ];
         const commandDirs = this.resolveCommandDirs(acodeConfig);
@@ -922,9 +1003,14 @@ export class ACodeRuntime extends EventEmitter {
             .join("\n\n");
         // 辅助函数：将非空文本构造为 system role 消息，消除重复的 spread+ternary 模式
         const makeSystem = (content) => content?.trim() ? [{ role: 'system', content: content.trim() }] : [];
+        // 将 rolePrompt 与 profilePrompt 合并为第二条 system 消息
+        const roleWithProfile = [this.config.rolePrompt, profilePrompt]
+            .map((item) => item?.trim())
+            .filter((item) => Boolean(item))
+            .join("\n\n");
         const initialConversation = [
             ...makeSystem(this.config.globalPrompt),
-            ...makeSystem(this.config.rolePrompt),
+            ...makeSystem(roleWithProfile),
             ...makeSystem(this.config.memory),
             ...(runtimePrompt ? [{ role: 'system', content: runtimePrompt }] : []),
         ];
@@ -945,6 +1031,8 @@ export class ACodeRuntime extends EventEmitter {
             commands,
             commandRegistry,
             conversation: cloneChatConversation(initialConversation),
+            accumulatedInputTokens: 0,
+            accumulatedOutputTokens: 0,
         };
         await this.hookBus.dispatch("SessionStart", {
             workingDirectory: this.config.workingDirectory,
@@ -972,6 +1060,7 @@ export class ACodeRuntime extends EventEmitter {
                 source: tool.kind === "mcp"
                     ? `${tool.serverName}.${tool.toolName}`
                     : `builtin.${tool.toolName}`,
+                description: tool.description || "",
             })),
         });
         this.emitAcodeEvent("skill_status", {
@@ -980,6 +1069,16 @@ export class ACodeRuntime extends EventEmitter {
             skills: skills.map((skill) => ({
                 name: skill.name,
                 description: skill.description,
+                directory: skill.directory,
+            })),
+            skillGroups: skillGroups.map((group) => ({
+                dir: group.dir,
+                exists: group.exists,
+                skills: group.skills.map((skill) => ({
+                    name: skill.name,
+                    description: skill.description,
+                    directory: skill.directory,
+                })),
             })),
         });
         this.emitAcodeEvent("command_status", {
@@ -994,6 +1093,234 @@ export class ACodeRuntime extends EventEmitter {
         if (this.config.initialPrompt) {
             await this.submit(this.config.initialPrompt);
         }
+        // 启动上下文压缩调试日志（仅当 ACODE_COMPACTION_DEBUG=1 时启用）
+        this.startCompactionDebugLog();
+        // 启动 skills 目录监听，运行中变更会触发重扫并刷新 SkillTool + 重发 skill_status
+        this.startSkillWatchers(watchedDirs);
+    }
+    /**
+     * 加载所有 skills 来源目录并合并。
+     *
+     * 三个来源（按优先级，后加载的覆盖先加载的同名 skill）：
+     *   1. 全局目录（~/.acode/skills，由 config.skillsDir 指定）
+     *   2. 项目目录（<workingDirectory>/.acode/skills）
+     *   3. 项目目录（<workingDirectory>/.agentswork/skills）
+     *
+     * 返回合并后的 skills 列表、按目录分组的 skillGroups，以及需要监听的目录列表
+     * （已去重、规范化）。watchedDirs 用于启动 fs.watch 监听运行时变更。
+     */
+    async loadAllSkills() {
+        const globalSkillsDir = this.config.skillsDir ?? "";
+        const projectAcodeSkillsDir = path.join(this.config.workingDirectory, ".acode", "skills");
+        const projectAgentsworkSkillsDir = path.join(this.config.workingDirectory, ".agentswork", "skills");
+        // 按规范化路径去重，避免全局目录与项目目录路径相同时重复加载
+        const seenDirs = new Set();
+        const skillGroups = [];
+        const watchedDirs = [];
+        for (const dir of [globalSkillsDir, projectAcodeSkillsDir, projectAgentsworkSkillsDir]) {
+            if (!dir)
+                continue;
+            const normalized = path.resolve(dir);
+            if (seenDirs.has(normalized))
+                continue;
+            seenDirs.add(normalized);
+            skillGroups.push(await loadAcodeSkillGroup(dir));
+            // 即使目录不存在也加入监听列表：fs.watch 会失败但被静默忽略，
+            // 这样用户后续创建该目录时（如果父目录存在）能通过其他途径感知。
+            // 实际上 fs.watch 不存在的路径会抛错，所以这里只加入存在的目录。
+            try {
+                await fs.promises.access(normalized);
+                watchedDirs.push(normalized);
+            }
+            catch {
+                // 目录不存在，跳过监听
+            }
+        }
+        // 合并各目录 skills，按 name 去重（项目优先覆盖全局）
+        const skillsByName = new Map();
+        for (const group of skillGroups) {
+            for (const skill of group.skills) {
+                skillsByName.set(skill.name, skill);
+            }
+        }
+        const skills = [...skillsByName.values()];
+        return { skills, skillGroups, watchedDirs };
+    }
+    /**
+     * 启动 fs.watch 监听 skills 目录变更。
+     *
+     * 使用 recursive: true（Windows/macOS 原生支持，Linux 在 Node 19+ 支持）。
+     * Linux 旧版本不支持时会抛 ERR_FEATURE_UNAVAILABLE，fallback 到非 recursive
+     * 监听顶层目录（只能感知 skill 子目录的新增/删除，无法感知 SKILL.md 内容修改）。
+     *
+     * 变更事件经防抖后触发 refreshSkills()，重新扫描目录、刷新 SkillTool、重发 skill_status。
+     */
+    startSkillWatchers(dirs) {
+        for (const dir of dirs) {
+            let watcher = null;
+            try {
+                watcher = fs.watch(dir, { recursive: true }, () => {
+                    this.scheduleSkillRefresh();
+                });
+            }
+            catch {
+                // recursive 在当前平台不支持（如 Linux 旧版本），fallback 到非 recursive
+                try {
+                    watcher = fs.watch(dir, () => {
+                        this.scheduleSkillRefresh();
+                    });
+                }
+                catch {
+                    // 监听失败（如权限问题），跳过该目录
+                    continue;
+                }
+            }
+            if (watcher) {
+                watcher.on("error", () => {
+                    // 静默处理 watcher 错误（如目录被删除），避免未捕获异常
+                });
+                this.skillWatchers.push(watcher);
+            }
+        }
+    }
+    /**
+     * 防抖调度 skill 重扫。短时间内多次变更事件只触发一次重扫。
+     */
+    scheduleSkillRefresh() {
+        if (this.skillRefreshTimer) {
+            clearTimeout(this.skillRefreshTimer);
+        }
+        this.skillRefreshTimer = setTimeout(() => {
+            this.skillRefreshTimer = null;
+            void this.refreshSkills();
+        }, ACodeRuntime.SKILL_REFRESH_DEBOUNCE_MS);
+    }
+    /**
+     * 重新扫描 skills 目录并刷新 SkillTool 与 state。
+     *
+     * 调用时机：fs.watch 监听到目录变更后（经防抖）。
+     * 副作用：
+     *   - 更新 this.skillTool 的内部 Map 与工具描述（让下一轮 turn 的 LLM 感知新 skill）
+     *   - 更新 this.state.skills（影响 fallback 响应等）
+     *   - 重发 skill_status 事件（让 DevTools 面板刷新"能力"标签页）
+     */
+    async refreshSkills() {
+        if (!this.state.started || this.state.terminated)
+            return;
+        try {
+            const { skills, skillGroups } = await this.loadAllSkills();
+            if (this.skillTool) {
+                this.skillTool.refresh(skills);
+            }
+            this.state.skills = skills;
+            this.emitAcodeEvent("skill_status", {
+                skillsDir: this.config.skillsDir,
+                installedCount: skills.length,
+                skills: skills.map((skill) => ({
+                    name: skill.name,
+                    description: skill.description,
+                    directory: skill.directory,
+                })),
+                skillGroups: skillGroups.map((group) => ({
+                    dir: group.dir,
+                    exists: group.exists,
+                    skills: group.skills.map((skill) => ({
+                        name: skill.name,
+                        description: skill.description,
+                        directory: skill.directory,
+                    })),
+                })),
+            });
+            runtimeDebugLog(`[skill-watch] Skills refreshed: ${skills.length} skills ` +
+                `(${skills.map((s) => s.name).join(", ") || "none"})`, { sessionId: this.config.sessionId });
+        }
+        catch (error) {
+            console.error(`[skill-watch] Failed to refresh skills:`, error instanceof Error ? error.message : error);
+        }
+    }
+    /**
+     * 关闭所有 skills 目录监听器与防抖定时器。在 stop() 中调用。
+     */
+    stopSkillWatchers() {
+        if (this.skillRefreshTimer) {
+            clearTimeout(this.skillRefreshTimer);
+            this.skillRefreshTimer = null;
+        }
+        for (const watcher of this.skillWatchers) {
+            try {
+                watcher.close();
+            }
+            catch {
+                // 忽略关闭错误
+            }
+        }
+        this.skillWatchers = [];
+    }
+    /**
+     * 启动上下文压缩调试日志，每 5 秒写入系统临时目录下的 acode-compaction-debug.log。
+     * 仅当环境变量 ACODE_COMPACTION_DEBUG=1 时启用，使用异步写入避免阻塞事件循环。
+     */
+    startCompactionDebugLog() {
+        if (!COMPACTION_DEBUG_ENABLED)
+            return;
+        if (this.compactionDebugTimer)
+            return;
+        const provider = this.state.provider;
+        const contextLimit = (provider.contextLimit && provider.contextLimit > 0)
+            ? provider.contextLimit
+            : FALLBACK_CONTEXT_LIMIT;
+        const maxOutput = (provider.maxOutput && provider.maxOutput > 0)
+            ? provider.maxOutput
+            : 8_192;
+        const inputLimit = (provider.inputLimit && provider.inputLimit > 0)
+            ? provider.inputLimit
+            : undefined;
+        const triggerThreshold = calculateCompactionThreshold(contextLimit, maxOutput, inputLimit);
+        this.compactionDebugTimer = setInterval(() => {
+            try {
+                const actualUsed = this.state.accumulatedInputTokens + this.state.accumulatedOutputTokens;
+                const estimatedUsed = estimateConversationTokens(this.state.conversation);
+                const effectiveUsed = Math.max(actualUsed, estimatedUsed);
+                const sizeKB = conversationSizeKB(this.state.conversation);
+                const isRunning = this.state.started && !this.state.terminated;
+                const lines = [
+                    `[${new Date().toISOString()}]`,
+                    `started=${this.state.started}`,
+                    `terminated=${this.state.terminated}`,
+                    `activeTurn=${this.activeTurn}`,
+                    `conversationSize=${this.state.conversation.length}msgs`,
+                    `sizeKB=${sizeKB}KB`,
+                    `estimation=${estimatedUsed} tokens`,
+                    `actualInput=${this.state.accumulatedInputTokens}`,
+                    `actualOutput=${this.state.accumulatedOutputTokens}`,
+                    `actualUsed=${actualUsed}`,
+                    `contextLimit=${contextLimit}`,
+                    `inputLimit=${inputLimit ?? "n/a"}`,
+                    `maxOutput=${maxOutput}`,
+                    `triggerThreshold=${triggerThreshold}`,
+                    `remainingToTrigger=${Math.max(0, triggerThreshold - actualUsed)}`,
+                    `isRunning=${isRunning}`,
+                    `shouldCompact=${isRunning ? effectiveUsed >= triggerThreshold : false}`,
+                    `---`,
+                ].join(" | ");
+                // 异步写入，避免阻塞事件循环
+                fs.promises.appendFile(COMPACTION_DEBUG_LOG, lines + "\n", "utf-8").catch(() => {
+                    // 忽略日志写入错误
+                });
+            }
+            catch {
+                // 忽略日志写入错误
+            }
+        }, 5000);
+    }
+    /**
+     * 停止上下文压缩调试日志。
+     */
+    stopCompactionDebugLog() {
+        if (this.compactionDebugTimer) {
+            clearInterval(this.compactionDebugTimer);
+            this.compactionDebugTimer = null;
+        }
     }
     /**
      * 处理一轮用户输入。
@@ -1019,17 +1346,19 @@ export class ACodeRuntime extends EventEmitter {
         this.abortController?.abort();
         this.abortController = null;
         this.state.conversation = cloneChatConversation(this.initialConversation);
+        this.state.accumulatedInputTokens = 0;
+        this.state.accumulatedOutputTokens = 0;
     }
     isTurnSuperseded(contextVersion) {
         return contextVersion !== this.contextVersion;
     }
     async executeSubmit(message, contextVersion) {
         const turnStartTime = Date.now();
-        console.log(`[ACodeRuntime] ══════════════════════════════════════════`);
-        console.log(`[ACodeRuntime] ▶️ executeSubmit STARTED`);
-        console.log(`[ACodeRuntime]  Message: ${message.slice(0, 100)}${message.length > 100 ? '...' : ''}`);
-        console.log(`[ACodeRuntime] 🔢 Context version: ${contextVersion}`);
-        console.log(`[ACodeRuntime] ═══════════════════════════════════════════`);
+        runtimeDebugLog(`[ACodeRuntime] ══════════════════════════════════════════`);
+        runtimeDebugLog(`[ACodeRuntime] ▶️ executeSubmit STARTED`);
+        runtimeDebugLog(`[ACodeRuntime]  Message: <redacted, length=${message.length}>`);
+        runtimeDebugLog(`[ACodeRuntime] 🔢 Context version: ${contextVersion}`);
+        runtimeDebugLog(`[ACodeRuntime] ═══════════════════════════════════════════`);
         if (!this.state.started || this.state.terminated) {
             console.error(`[ACodeRuntime] ❌ Runtime not active (started: ${this.state.started}, terminated: ${this.state.terminated})`);
             throw new Error("ACode runtime is not active");
@@ -1039,14 +1368,14 @@ export class ACodeRuntime extends EventEmitter {
         const originalPrompt = message.trim();
         let turnCompleted = false;
         try {
-            console.log(`[ACodeRuntime] 🔍 Dispatching UserPromptSubmit hook...`);
+            runtimeDebugLog(`[ACodeRuntime] 🔍 Dispatching UserPromptSubmit hook...`);
             const promptHookStartTime = Date.now();
             const promptHookResults = await this.hookBus.dispatch("UserPromptSubmit", { prompt: originalPrompt });
             const promptHookDuration = Date.now() - promptHookStartTime;
-            console.log(`[ACodeRuntime] ✅ UserPromptSubmit hook completed in ${promptHookDuration}ms, ` +
+            runtimeDebugLog(`[ACodeRuntime] ✅ UserPromptSubmit hook completed in ${promptHookDuration}ms, ` +
                 `results: ${promptHookResults.length}`);
             if (this.isTurnSuperseded(contextVersion)) {
-                console.log(`[ACodeRuntime] ⚠️ Turn superseded after hook, aborting`);
+                runtimeDebugLog(`[ACodeRuntime] ⚠️ Turn superseded after hook, aborting`);
                 return;
             }
             const promptDeny = findDeniedHookResult(promptHookResults);
@@ -1057,15 +1386,15 @@ export class ACodeRuntime extends EventEmitter {
                 });
                 this.emitAcodeEvent("turn_complete", { failed: true });
                 turnCompleted = true;
-                console.log(`[ACodeRuntime] 📤 Emitted turn_complete (failed=true) due to hook deny`);
+                runtimeDebugLog(`[ACodeRuntime] 📤 Emitted turn_complete (failed=true) due to hook deny`);
                 return;
             }
-            console.log(`[ACodeRuntime] 🔍 Expanding command if any...`);
+            runtimeDebugLog(`[ACodeRuntime] 🔍 Expanding command if any...`);
             const expandedCommand = this.state.commandRegistry.expand(originalPrompt);
             const trimmed = expandedCommand?.prompt.trim() || originalPrompt;
             const commandAllowedTools = expandedCommand?.command.allowedTools;
             if (expandedCommand) {
-                console.log(`[ACodeRuntime] 📋 Slash command detected: ${expandedCommand.command.name}`);
+                runtimeDebugLog(`[ACodeRuntime] 📋 Slash command detected: ${expandedCommand.command.name}`);
                 this.emitAcodeEvent("command_status", {
                     action: "slash_command",
                     command: expandedCommand.command.name,
@@ -1074,76 +1403,85 @@ export class ACodeRuntime extends EventEmitter {
                 });
             }
             if (!this.state.provider.baseURL || !this.state.provider.apiKey) {
-                console.log(`[ACodeRuntime] ⚠️ No provider configured, using fallback response`);
+                runtimeDebugLog(`[ACodeRuntime] ⚠️ No provider configured, using fallback response`);
                 const text = createFallbackResponse(trimmed, this.state);
                 this.emitAcodeEvent("assistant_delta", { text });
                 this.emitAcodeEvent("turn_complete", {
                     usage: { inputTokens: trimmed.length, outputTokens: text.length },
                 });
                 turnCompleted = true;
-                console.log(`[ACodeRuntime] 📤 Emitted turn_complete (fallback mode)`);
+                runtimeDebugLog(`[ACodeRuntime] 📤 Emitted turn_complete (fallback mode)`);
                 return;
             }
-            console.log(`[ACodeRuntime] 📎 Parsing attachment message...`);
+            runtimeDebugLog(`[ACodeRuntime] 📎 Parsing attachment message...`);
             const parsedContent = parseAttachmentMessage(trimmed);
             if (parsedContent.hasImages && !this.state.provider.supportsImageInput) {
                 console.error(`[ACodeRuntime] ❌ Image input not supported by current provider`);
                 throw new Error("ACode provider/model is not configured for image input. Enable provider.default.models[model].modalities.input including 'image' or options.supportsImageInput=true.");
             }
-            console.log(`[ACodeRuntime] 🖼️ Materializing image content if any...`);
+            runtimeDebugLog(`[ACodeRuntime] 🖼️ Materializing image content if any...`);
             const userContent = await materializeImageContent(parsedContent.content);
             if (this.isTurnSuperseded(contextVersion)) {
-                console.log(`[ACodeRuntime] ️ Turn superseded after materializing content, aborting`);
+                runtimeDebugLog(`[ACodeRuntime] ️ Turn superseded after materializing content, aborting`);
                 return;
             }
-            console.log(`[ACodeRuntime] 💬 Adding user message to conversation`);
+            runtimeDebugLog(`[ACodeRuntime] 💬 Adding user message to conversation`);
             this.state.conversation.push({ role: "user", content: userContent });
-            console.log(`[ACodeRuntime]  Conversation size: ${this.state.conversation.length} messages`);
-            console.log(`[ACodeRuntime]  Starting runModelTurn...`);
+            runtimeDebugLog(`[ACodeRuntime]  Conversation size: ${this.state.conversation.length} messages`);
+            runtimeDebugLog(`[ACodeRuntime]  Starting runModelTurn...`);
             const modelTurnStartTime = Date.now();
             const result = await this.runModelTurn(commandAllowedTools, contextVersion);
             const modelTurnDuration = Date.now() - modelTurnStartTime;
-            console.log(`[ACodeRuntime] ✅ runModelTurn completed in ${modelTurnDuration}ms`);
-            console.log(`[ACodeRuntime] 📝 Result: text=${result.text ? result.text.slice(0, 80) + (result.text.length > 80 ? '...' : '') : '(empty)'}, ` +
+            runtimeDebugLog(`[ACodeRuntime] ✅ runModelTurn completed in ${modelTurnDuration}ms`);
+            runtimeDebugLog(`[ACodeRuntime] 📝 Result: text=${result.text ? result.text.slice(0, 80) + (result.text.length > 80 ? '...' : '') : '(empty)'}, ` +
                 `finishReason=${result.finishReason || '(none)'}`);
             if (this.isTurnSuperseded(contextVersion)) {
-                console.log(`[ACodeRuntime] ️ Turn superseded after runModelTurn, aborting`);
+                runtimeDebugLog(`[ACodeRuntime] ️ Turn superseded after runModelTurn, aborting`);
                 return;
             }
             if (result.text && !this.state.provider.stream) {
-                console.log(`[ACodeRuntime] 📤 Emitting assistant_delta (non-streaming mode)`);
+                runtimeDebugLog(`[ACodeRuntime] 📤 Emitting assistant_delta (non-streaming mode)`);
                 this.emitAcodeEvent("assistant_delta", { text: result.text });
             }
-            console.log(`[ACodeRuntime] 📤 Emitting turn_complete...`);
+            runtimeDebugLog(`[ACodeRuntime] 📤 Emitting turn_complete...`);
             this.emitAcodeEvent("turn_complete", {
+                // ★ 使用 result.totalOutputTextLength 替代 result.text.length，
+                //    result.text 只保留最后一次迭代的文本，导致多轮迭代时 outputTokens 被严重低估
                 usage: result.usage ?? {
                     inputTokens: trimmed.length,
-                    outputTokens: result.text.length,
+                    outputTokens: result.totalOutputTextLength ?? result.text.length,
                 },
                 ...(result.responseBody ? { responseBody: result.responseBody } : {}),
                 ...(result.finishReason ? { finishReason: result.finishReason } : {}),
             });
+            // ★ token 用量已在 runModelTurn 中按迭代更新到 state（非累加），
+            //    此处不再累加，避免 actualUsed 跨轮只增不减导致 shouldCompact 永远为 true。
+            //    finalUsage 仍用于 turn_complete 事件的 usage 上报（多轮迭代的总和）。
+            runtimeDebugLog(`[ACodeRuntime] 💰 Current context usage: ` +
+                `input=${this.state.accumulatedInputTokens}, ` +
+                `output=${this.state.accumulatedOutputTokens}` +
+                (result.usage ? '' : ' (estimated, no provider usage)'));
             turnCompleted = true;
             const totalDuration = Date.now() - turnStartTime;
-            console.log(`[ACodeRuntime] ═══════════════════════════════════════════`);
-            console.log(`[ACodeRuntime] ✅ executeSubmit COMPLETED in ${totalDuration}ms`);
-            console.log(`[ACodeRuntime] ══════════════════════════════════════════`);
+            runtimeDebugLog(`[ACodeRuntime] ═══════════════════════════════════════════`);
+            runtimeDebugLog(`[ACodeRuntime] ✅ executeSubmit COMPLETED in ${totalDuration}ms`);
+            runtimeDebugLog(`[ACodeRuntime] ══════════════════════════════════════════`);
         }
         catch (error) {
             const errorDuration = Date.now() - turnStartTime;
             console.error(`[ACodeRuntime] ❌ executeSubmit FAILED after ${errorDuration}ms:`, error instanceof Error ? error.message : String(error));
             console.error(`[ACodeRuntime] 🔍 Error stack:`, error instanceof Error ? error.stack : '(no stack)');
             if (this.isTurnSuperseded(contextVersion)) {
-                console.log(`[ACodeRuntime] ️ Turn superseded in error handler, skipping recovery`);
+                runtimeDebugLog(`[ACodeRuntime] ️ Turn superseded in error handler, skipping recovery`);
                 return;
             }
             if (this.abortRequested) {
-                console.log(`[ACodeRuntime] ⚠️ Abort requested, emitting aborted turn_complete`);
+                runtimeDebugLog(`[ACodeRuntime] ⚠️ Abort requested, emitting aborted turn_complete`);
                 this.emitAcodeEvent("turn_complete", { aborted: true });
                 turnCompleted = true;
                 return;
             }
-            console.log(`[ACodeRuntime]  Emitting error and failed turn_complete...`);
+            runtimeDebugLog(`[ACodeRuntime]  Emitting error and failed turn_complete...`);
             this.emitAcodeEvent("error", {
                 message: error instanceof Error ? error.message : String(error),
             });
@@ -1152,8 +1490,8 @@ export class ACodeRuntime extends EventEmitter {
         }
         finally {
             const finallyDuration = Date.now() - turnStartTime;
-            console.log(`[ACodeRuntime] 🔚 executeSubmit finally block entered after ${finallyDuration}ms`);
-            console.log(`[ACodeRuntime] 🔍 turnCompleted=${turnCompleted}, activeTurn=${this.activeTurn}, ` +
+            runtimeDebugLog(`[ACodeRuntime] 🔚 executeSubmit finally block entered after ${finallyDuration}ms`);
+            runtimeDebugLog(`[ACodeRuntime] 🔍 turnCompleted=${turnCompleted}, activeTurn=${this.activeTurn}, ` +
                 `abortRequested=${this.abortRequested}`);
             this.activeTurn = false;
             this.abortRequested = false;
@@ -1167,7 +1505,7 @@ export class ACodeRuntime extends EventEmitter {
                     message: "ACode turn completed without proper completion event (internal error)",
                 });
                 this.emitAcodeEvent("turn_complete", { failed: true });
-                console.log(`[ACodeRuntime]  Emergency turn_complete (failed=true) emitted`);
+                runtimeDebugLog(`[ACodeRuntime]  Emergency turn_complete (failed=true) emitted`);
             }
         }
     }
@@ -1176,6 +1514,144 @@ export class ACodeRuntime extends EventEmitter {
         this.abortRequested = this.activeTurn;
         this.abortController?.abort();
         this.abortController = null;
+        // ask_user_question 等待用户回答期间被 abort，需 reject 所有 waiter
+        this.rejectAllQuestionWaiters("aborted");
+    }
+    /**
+     * 构造 ask_user_question 工具的依赖注入。
+     * onQuestion: 发出 question_request 事件，让 adapter 转发到前端。
+     * waitForAnswer: 阻塞等待 submitQuestionAnswer() 调用 resolve，或 abort/stop/supersede 时 reject。
+     */
+    buildAskUserQuestionDeps() {
+        return {
+            onQuestion: (toolCallId, questions) => {
+                this.emitAcodeEvent("question_request", {
+                    toolCallId,
+                    questions: questions,
+                });
+            },
+            waitForAnswer: (toolCallId, contextVersion) => {
+                return new Promise((resolve, reject) => {
+                    this.questionWaiters.set(toolCallId, {
+                        resolve,
+                        reject,
+                        contextVersion,
+                    });
+                });
+            },
+        };
+    }
+    /**
+     * 构造 sub-agent 工具集依赖（注入 SubAgentManager 句柄）。
+     *
+     * 5 个工具的依赖：
+     *   - spawnSubAgent: 创建子 agent（不阻塞，不自动 start）
+     *   - listSubAgents: 列出当前 agent 的所有子 agent
+     *   - getSubAgentStatus: 查询某子 agent 实时状态
+     *   - awaitSubAgents: 阻塞等待指定子 agent 数组完成
+     *   - abortSubAgent: 终止某子 agent
+     */
+    buildSubAgentToolDeps(manager) {
+        const parentAgentId = this.config.agentId ?? "unknown";
+        const parentSessionId = this.config.sessionId;
+        const workingDirectory = this.config.workingDirectory;
+        const parentConfig = this.config;
+        return {
+            // 非阻塞 spawn：创建后不等待，立即返回 subId
+            spawnSubAgent: async (opts) => {
+                const subId = await manager.spawn({
+                    parentAgentId,
+                    parentSessionId,
+                    subagentType: opts.subagentType,
+                    description: opts.description,
+                    prompt: opts.prompt,
+                    workingDirectory,
+                    parentConfig,
+                });
+                // 自动 start（非阻塞，立即返回）
+                await manager.start(subId);
+                return { subId };
+            },
+            // 列出当前 agent 的所有子 agent（运行中 + 历史）
+            listSubAgents: async () => {
+                const entries = manager.listByParent(parentAgentId);
+                const running = [];
+                const history = [];
+                for (const entry of entries) {
+                    const info = {
+                        subId: entry.subId,
+                        subagentType: entry.subagentType,
+                        description: entry.description,
+                        status: entry.status,
+                        startedAt: entry.startedAt,
+                        endedAt: entry.endedAt,
+                        durationMs: entry.durationMs,
+                    };
+                    if (entry.status === "pending" || entry.status === "running") {
+                        running.push(info);
+                    }
+                    else {
+                        history.push(info);
+                    }
+                }
+                // history 按 endedAt 倒序
+                history.sort((a, b) => (b.endedAt ?? 0) - (a.endedAt ?? 0));
+                return { running, history };
+            },
+            // 查询某子 agent 实时状态
+            getSubAgentStatus: async (subId) => {
+                const entry = manager.getSubAgent(subId);
+                if (!entry)
+                    return null;
+                return {
+                    subId: entry.subId,
+                    subagentType: entry.subagentType,
+                    description: entry.description,
+                    status: entry.status,
+                    startedAt: entry.startedAt,
+                    endedAt: entry.endedAt,
+                    durationMs: entry.durationMs,
+                    prompt: entry.prompt,
+                    result: entry.result,
+                    errorMessage: entry.errorMessage,
+                    contextSnapshot: entry.contextSnapshot,
+                };
+            },
+            // 阻塞等待指定子 agent 数组完成
+            awaitSubAgents: (subIds, timeoutMs) => manager.awaitCompletion(subIds, timeoutMs),
+            // 终止某子 agent
+            abortSubAgent: (subId) => manager.abort(subId),
+        };
+    }
+    /**
+     * 接收用户对 ask_user_question 的回答（由 AcodeSdkAdapter.sendQuestionAnswer 调用）。
+     * 若当前 turn 已被 supersede（contextVersion 变更），返回 false 让 adapter 知晓。
+     */
+    submitQuestionAnswer(toolCallId, answers) {
+        const waiter = this.questionWaiters.get(toolCallId);
+        if (!waiter) {
+            return false;
+        }
+        this.questionWaiters.delete(toolCallId);
+        // 若 turn 已被 supersede，不 resolve（避免过期答案污染新轮次）
+        if (this.isTurnSuperseded(waiter.contextVersion)) {
+            waiter.reject(new Error("turn superseded before user answered"));
+            return false;
+        }
+        waiter.resolve(answers);
+        return true;
+    }
+    /**
+     * 中止所有 ask_user_question 等待，让工具 execute() 抛错走 appendToolFailureResult。
+     * 在 abort()/stop() 中调用，确保用户点停止或会话终止时 execute 不会永久阻塞。
+     */
+    rejectAllQuestionWaiters(reason) {
+        if (this.questionWaiters.size === 0)
+            return;
+        for (const [, waiter] of this.questionWaiters) {
+            waiter.reject(new Error(`ask_user_question ${reason}`));
+        }
+        this.questionWaiters.clear();
     }
     /** 终止 ACode 会话并发出 session_complete。 */
     async stop() {
@@ -1187,6 +1663,8 @@ export class ACodeRuntime extends EventEmitter {
         this.abortRequested = this.activeTurn;
         this.abortController?.abort();
         this.abortController = null;
+        // ask_user_question 等待用户回答期间被 stop，需 reject 所有 waiter
+        this.rejectAllQuestionWaiters("session terminated");
         await runBestEffort("ACode active turn shutdown", this.submitQueue, (message) => {
             this.emitAcodeEvent("error", { message });
         });
@@ -1199,6 +1677,18 @@ export class ACodeRuntime extends EventEmitter {
             this.sessionCompleteEmitted = true;
             this.emitAcodeEvent("session_complete", { exitCode: 0 });
         }
+        this.stopCompactionDebugLog();
+        this.stopSkillWatchers();
+        if (COMPACTION_DEBUG_ENABLED) {
+            try {
+                fs.promises.appendFile(COMPACTION_DEBUG_LOG, `[${new Date().toISOString()}] runtime stopped | ---\n`, "utf-8").catch(() => {
+                    // 忽略
+                });
+            }
+            catch {
+                // 忽略
+            }
+        }
     }
     resolveCommandDirs(acodeConfig) {
         const configured = [
@@ -1215,29 +1705,31 @@ export class ACodeRuntime extends EventEmitter {
         let finalUsage;
         let finalResponseBody;
         let finalFinishReason;
+        let accumulatedAssistantText = ""; // 累加多轮迭代的 output 文本长度
+        let accumulatedPromptTokens = 0; // 累加多轮迭代的 prompt_tokens
         // 日志：开始 runModelTurn
-        console.log(`[ACodeRuntime] ▶️ runModelTurn started (contextVersion: ${contextVersion})`);
+        runtimeDebugLog(`[ACodeRuntime] ▶️ runModelTurn started (contextVersion: ${contextVersion})`);
         // 移除5次限制，添加安全上限防止真正的无限循环
         const SAFETY_LIMIT = 50; // 安全上限，正常情况下不会达到
         for (let step = 0; step < SAFETY_LIMIT; step += 1) {
             // 详细日志：记录每次迭代
-            console.log(`[ACodeRuntime] 🔄 Iteration ${step + 1} starting...`);
+            runtimeDebugLog(`[ACodeRuntime] 🔄 Iteration ${step + 1} starting...`);
             if (this.isTurnSuperseded(contextVersion)) {
-                console.log(`[ACodeRuntime] ⚠️ Turn superseded at iteration ${step + 1}, aborting`);
-                return { text: "" };
+                runtimeDebugLog(`[ACodeRuntime] ⚠️ Turn superseded at iteration ${step + 1}, aborting`);
+                return { text: "", totalOutputTextLength: accumulatedAssistantText.length };
             }
             const requestStartTime = Date.now();
             const response = await this.requestChatCompletion(commandAllowedTools);
             const requestDuration = Date.now() - requestStartTime;
             // 日志：AI请求完成
-            console.log(`[ACodeRuntime] 🤖 AI request completed in ${requestDuration}ms, ` +
+            runtimeDebugLog(`[ACodeRuntime] 🤖 AI request completed in ${requestDuration}ms, ` +
                 `choices: ${response.choices?.length || 0}`);
             if (this.isTurnSuperseded(contextVersion)) {
-                console.log(`[ACodeRuntime] ⚠️ Turn superseded after AI response at iteration ${step + 1}`);
-                return { text: "" };
+                runtimeDebugLog(`[ACodeRuntime] ⚠️ Turn superseded after AI response at iteration ${step + 1}`);
+                return { text: "", totalOutputTextLength: accumulatedAssistantText.length };
             }
             if (this.state.terminated) {
-                console.log(`[ACodeRuntime]  Runtime terminated at iteration ${step + 1}`);
+                runtimeDebugLog(`[ACodeRuntime]  Runtime terminated at iteration ${step + 1}`);
                 throw new Error("ACode runtime was stopped during the active turn");
             }
             const choice = response.choices?.[0];
@@ -1252,7 +1744,7 @@ export class ACodeRuntime extends EventEmitter {
                 ? message.tool_calls
                 : [];
             // 日志：AI响应详情
-            console.log(`[ACodeRuntime]  AI response: ` +
+            runtimeDebugLog(`[ACodeRuntime]  AI response: ` +
                 `content=${content ? content.slice(0, 100) + (content.length > 100 ? '...' : '') : '(empty)'}, ` +
                 `toolCalls=${toolCalls.length}, ` +
                 `finishReason=${finalFinishReason || '(none)'}`);
@@ -1261,11 +1753,25 @@ export class ACodeRuntime extends EventEmitter {
                 const rtOutputTokens = response.usage.completion_tokens ?? response.usage.output_tokens;
                 if (typeof rtInputTokens === "number" &&
                     typeof rtOutputTokens === "number") {
-                    finalUsage = {
-                        inputTokens: rtInputTokens,
-                        outputTokens: rtOutputTokens,
-                    };
-                    console.log(`[ACodeRuntime] 💰 Token usage: input=${rtInputTokens}, output=${rtOutputTokens}`);
+                    if (finalUsage) {
+                        finalUsage.inputTokens += rtInputTokens;
+                        finalUsage.outputTokens += rtOutputTokens;
+                    }
+                    else {
+                        finalUsage = {
+                            inputTokens: rtInputTokens,
+                            outputTokens: rtOutputTokens,
+                        };
+                    }
+                    accumulatedPromptTokens += rtInputTokens;
+                    // ★ 更新 state 为当前迭代的实际 token 用量（非累加）
+                    //    prompt_tokens 代表本次请求时 provider 看到的完整上下文大小，
+                    //    是当前上下文大小的最准确度量。
+                    //    之前用 += 累加导致 actualUsed 只增不减，shouldCompact 永远为 true。
+                    this.state.accumulatedInputTokens = rtInputTokens;
+                    this.state.accumulatedOutputTokens = rtOutputTokens;
+                    runtimeDebugLog(`[ACodeRuntime] 💰 Token usage: input=${rtInputTokens}, output=${rtOutputTokens} ` +
+                        `(turn accumulated: input=${accumulatedPromptTokens}, output=${finalUsage.outputTokens})`);
                 }
             }
             this.state.conversation.push({
@@ -1275,31 +1781,33 @@ export class ACodeRuntime extends EventEmitter {
             });
             if (content) {
                 finalText = content;
-                console.log(`[ACodeRuntime] ✨ Captured assistant text: ${content.slice(0, 80)}...`);
+                accumulatedAssistantText += content;
+                runtimeDebugLog(`[ACodeRuntime] ✨ Captured assistant text: ${content.slice(0, 80)}...`);
             }
             if (toolCalls.length === 0) {
-                console.log(`[ACodeRuntime] ✅ No tool calls at iteration ${step + 1}, completing turn`);
+                runtimeDebugLog(`[ACodeRuntime] ✅ No tool calls at iteration ${step + 1}, completing turn`);
                 return {
                     text: finalText,
                     usage: finalUsage,
                     responseBody: finalResponseBody,
                     finishReason: finalFinishReason,
+                    totalOutputTextLength: accumulatedAssistantText.length,
                 };
             }
             // 日志：即将执行工具调用
             const toolNames = toolCalls.map(tc => tc.function.name).join(", ");
-            console.log(`[ACodeRuntime] 🔧 Executing ${toolCalls.length} tool(s) at iteration ${step + 1}: ${toolNames}`);
+            runtimeDebugLog(`[ACodeRuntime] 🔧 Executing ${toolCalls.length} tool(s) at iteration ${step + 1}: ${toolNames}`);
             const toolStart = Date.now();
             await this.handleToolCalls(toolCalls, commandAllowedTools, contextVersion);
             const toolDuration = Date.now() - toolStart;
             // 日志：工具执行完成
-            console.log(`[ACodeRuntime] ⚙️ Tool execution completed in ${toolDuration}ms at iteration ${step + 1}`);
+            runtimeDebugLog(`[ACodeRuntime] ⚙️ Tool execution completed in ${toolDuration}ms at iteration ${step + 1}`);
             if (this.isTurnSuperseded(contextVersion)) {
-                console.log(`[ACodeRuntime] ⚠️ Turn superseded after tool execution at iteration ${step + 1}`);
-                return { text: "" };
+                runtimeDebugLog(`[ACodeRuntime] ⚠️ Turn superseded after tool execution at iteration ${step + 1}`);
+                return { text: "", totalOutputTextLength: accumulatedAssistantText.length };
             }
             // 日志：准备下一次迭代
-            console.log(`[ACodeRuntime] 🔄 Preparing iteration ${step + 2}...`);
+            runtimeDebugLog(`[ACodeRuntime] 🔄 Preparing iteration ${step + 2}...`);
         }
         // 达到安全上限（理论上不应该发生）
         console.error(`[ACodeRuntime] 🚨 CRITICAL: Reached safety limit of ${SAFETY_LIMIT} iterations! ` +
@@ -1309,19 +1817,162 @@ export class ACodeRuntime extends EventEmitter {
             usage: finalUsage,
             responseBody: finalResponseBody,
             finishReason: finalFinishReason || "safety_iteration_limit_reached",
+            totalOutputTextLength: accumulatedAssistantText.length,
         };
     }
+    /**
+     * LLM 摘要器：调用当前 provider 生成结构化对话摘要。
+     *
+     * 这是把 OpenCode 的 LLM 摘要能力赋能到 ACode 的核心方法：
+     * - OpenCode 在 compaction.process 中调用独立的 compaction agent
+     * - ACode 复用当前 provider 配置，发起一次非流式 chat completion 请求
+     * - 使用 COMPACTION_LLM_PROMPT_TEMPLATE 作为 prompt 模板
+     *
+     * 设计要点：
+     * 1. 非流式调用（不需要流式，简化处理）
+     * 2. 不带 tools（纯文本生成）
+     * 3. 失败时抛出异常，由 summarizeConversation 降级到规则摘要
+     * 4. 独立的 AbortController，避免主请求取消影响摘要
+     * 5. 复用 provider 的 timeout 配置
+     *
+     * @param input 摘要输入（conversationText + messageCount + contextLimit）
+     * @returns LLM 生成的结构化摘要文本
+     */
+    async summarizeConversationWithLLM(input) {
+        const provider = this.state.provider;
+        const baseURL = provider.baseURL;
+        if (!baseURL) {
+            throw new Error("ACode provider baseURL is not configured for LLM summarization");
+        }
+        const headers = {
+            "Content-Type": "application/json",
+        };
+        if (provider.apiKey) {
+            headers.Authorization = `Bearer ${provider.apiKey}`;
+        }
+        const requestBody = {
+            model: provider.model,
+            stream: false,
+            messages: [
+                {
+                    role: "system",
+                    content: "You are a helpful AI assistant tasked with summarizing conversations. " +
+                        "When asked to summarize, provide a detailed but concise summary of the conversation. " +
+                        "Focus on information that would be helpful for continuing the conversation. " +
+                        "Do not respond to any questions in the conversation, only output the summary.",
+                },
+                {
+                    role: "user",
+                    content: `Below is an earlier conversation (${input.messageCount} messages) that needs to be summarized ` +
+                        `to free context space (current context limit: ${input.contextLimit} tokens).\n\n` +
+                        `--- Conversation Start ---\n${input.conversationText}\n--- Conversation End ---\n\n` +
+                        COMPACTION_LLM_PROMPT_TEMPLATE,
+                },
+            ],
+        };
+        const abortController = new AbortController();
+        this.abortController = abortController;
+        const response = await withTimeout(fetch(normalizeChatCompletionsUrl(baseURL), {
+            method: "POST",
+            headers,
+            body: JSON.stringify(requestBody),
+            signal: abortController.signal,
+        }), provider.requestTimeoutMs, "ACode LLM summarization", () => {
+            abortController.abort();
+        });
+        if (!response.ok) {
+            throw new Error(`ACode LLM summarization request failed: ${response.status} ${await response.text()}`);
+        }
+        const payload = (await response.json());
+        const content = payload.choices?.[0]?.message?.content;
+        if (!content || content.trim().length === 0) {
+            throw new Error("ACode LLM summarization returned empty content");
+        }
+        return content;
+    }
     async requestChatCompletion(commandAllowedTools) {
         const provider = this.state.provider;
         const baseURL = provider.baseURL;
         if (!baseURL) {
             throw new Error("ACode provider baseURL is not configured");
         }
-        const truncatedCount = truncateConversationIfNeeded(this.state.conversation, MAX_REQUEST_BODY_BYTES);
+        // 主动上下文压缩：在发送 AI 请求前检测 token 是否溢出
+        // 使用 provider 配置中的 contextLimit/inputLimit/maxOutput（来自模板配置）。
+        // 不依赖 MODEL_CONTEXT_LIMITS 硬编码查找表，若未配置则使用 FALLBACK_CONTEXT_LIMIT（64K）。
+        const contextLimit = (provider.contextLimit && provider.contextLimit > 0)
+            ? provider.contextLimit
+            : FALLBACK_CONTEXT_LIMIT;
+        const maxOutput = (provider.maxOutput && provider.maxOutput > 0)
+            ? provider.maxOutput
+            : 8_192;
+        // ★ 融合 OpenCode 预算思路：优先用 inputLimit（部分 Provider input+output 总额 ≠ context 上限）
+        //   未配置 inputLimit 时降级到 contextLimit，行为与改进前一致。
+        const inputLimit = (provider.inputLimit && provider.inputLimit > 0)
+            ? provider.inputLimit
+            : undefined;
+        // ★ 阈值 = min(contextLimit × 55%, hardLimit - reserved)
+        //   hardLimit = inputLimit ?? contextLimit
+        //   reserved = min(COMPACTION_BUFFER, maxOutput)  // buffer 不超过输出上限
+        const compactionThreshold = calculateCompactionThreshold(contextLimit, maxOutput, inputLimit);
+        // 使用 effectiveUsed = max(actualUsed, estimatedUsed)
+        // 因为部分 provider 不返回 usage 数据（actualUsed=0），此时降级到文本估算
+        const actualUsed = this.state.accumulatedInputTokens + this.state.accumulatedOutputTokens;
+        const estimatedUsed = estimateConversationTokens(this.state.conversation);
+        const effectiveUsed = Math.max(actualUsed, estimatedUsed);
+        const shouldCompact = effectiveUsed >= compactionThreshold;
+        runtimeDebugLog(`[ACodeRuntime] 🔍 Compaction check: ` +
+            `actualUsed=${actualUsed}, estimation=${estimatedUsed}, ` +
+            `effectiveUsed=${effectiveUsed}, contextLimit=${contextLimit}, ` +
+            `inputLimit=${inputLimit ?? "n/a"}, maxOutput=${maxOutput}, ` +
+            `triggerThreshold=${compactionThreshold}, shouldCompact=${shouldCompact}`);
+        if (shouldCompact) {
+            const sizeBeforeKB = conversationSizeKB(this.state.conversation);
+            const compactionId = `compaction-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+            this.emitAcodeEvent("context_compaction", {
+                action: "start",
+                compactionId,
+                sizeKB: sizeBeforeKB,
+                estimatedTokens: estimatedUsed,
+                actualInputTokens: this.state.accumulatedInputTokens,
+                actualOutputTokens: this.state.accumulatedOutputTokens,
+                messageCount: this.state.conversation.length,
+                model: provider.model,
+                trigger: actualUsed >= compactionThreshold ? "actual_usage" : "estimated_overflow",
+            });
+            // ★ 发射压缩子事件（检测到溢出）
+            this.emitCompactionPhase(compactionId, "detect", "检测到上下文溢出", `有效用量: ${effectiveUsed} tokens, 阈值: ${compactionThreshold}, 触发: ${actualUsed >= compactionThreshold ? "实际用量" : "估算溢出"}`);
+            const result = await performCompaction(this.state.conversation, contextLimit, maxOutput, {
+                llmSummarizer: (input) => this.summarizeConversationWithLLM(input),
+                onPhase: (phaseEvent) => this.handleCompactionPhase(compactionId, phaseEvent),
+            });
+            const sizeAfterKB = conversationSizeKB(this.state.conversation);
+            this.emitAcodeEvent("context_compaction", {
+                action: "end",
+                compactionId,
+                sizeBeforeKB,
+                sizeAfterKB,
+                freedKB: Math.round((sizeBeforeKB - sizeAfterKB) * 10) / 10,
+                strategy: result.strategy,
+                freedTokens: result.freedTokens,
+                prunedToolMessages: result.prunedToolMessages,
+                summarizedMessages: result.summarizedMessages,
+                messageCountBefore: result.messageCountBefore,
+                messageCountAfter: result.messageCountAfter,
+            });
+            // ★ 压缩后重置累积 token 计数，使下一次请求时 actualUsed 反映压缩后的真实上下文大小。
+            //    若不重置，actualUsed 仍为压缩前的旧值，shouldCompact 会持续为 true 导致无效压缩循环。
+            this.state.accumulatedInputTokens = 0;
+            this.state.accumulatedOutputTokens = 0;
+        }
+        const truncatedCount = await truncateConversationIfNeeded(this.state.conversation, MAX_REQUEST_BODY_BYTES, contextLimit, maxOutput, (input) => this.summarizeConversationWithLLM(input));
         if (truncatedCount > 0) {
             this.emitAcodeEvent("warning", {
                 message: `Conversation truncated: removed ${truncatedCount} older messages to fit within ${MAX_REQUEST_BODY_BYTES} byte request size limit`,
             });
+            // ★ HTTP body 兜底压缩后同样重置累积 token 计数，避免下一轮 actualUsed 仍为
+            //   压缩前旧值导致 shouldCompact 误判（与主动压缩路径行为一致，见上方 shouldCompact 块）。
+            this.state.accumulatedInputTokens = 0;
+            this.state.accumulatedOutputTokens = 0;
         }
         const allowedTools = this.state.exposedTools.filter((tool) => isToolAllowed(tool, this.state.permissions, commandAllowedTools));
         const buildBody = () => {
@@ -1343,7 +1994,7 @@ export class ACodeRuntime extends EventEmitter {
         const emitAiRequest = (body) => {
             const requestBody = JSON.stringify(body, null, 2);
             // [DEBUG] ACode Runtime 实际发送的模型名称
-            console.log(`[ACodeRuntime] ★★★ DEBUG ★★★ emitAiRequest: 发送请求 model=${provider.model}, endpoint=${requestUrl}, messageCount=${this.state.conversation.length}`);
+            runtimeDebugLog(`[ACodeRuntime] ★★★ DEBUG ★★★ emitAiRequest: 发送请求 model=${provider.model}, endpoint=${requestUrl}, messageCount=${this.state.conversation.length}`);
             this.emitAcodeEvent("ai_request", {
                 model: provider.model,
                 endpoint: requestUrl,
@@ -1415,11 +2066,57 @@ export class ACodeRuntime extends EventEmitter {
                     !this.abortRequested &&
                     !this.state.terminated &&
                     isContextOverflowProviderRequestError(requestError)) {
-                    const compactedCount = compactConversationForContextOverflow(this.state.conversation);
+                    // 响应式上下文压缩：Provider 返回上下文溢出错误时强制执行
+                    // 这里不通过 performCompaction（它会先检查 isOverflow），
+                    // 而是直接调用 summarizeConversation 进行强制摘要化
+                    const sizeBeforeKB = conversationSizeKB(this.state.conversation);
+                    const msgCountBefore = this.state.conversation.length;
+                    const compactionId = `compaction-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+                    this.emitAcodeEvent("context_compaction", {
+                        action: "start",
+                        compactionId,
+                        sizeKB: sizeBeforeKB,
+                        messageCount: msgCountBefore,
+                        model: provider.model,
+                        trigger: "provider_overflow_error",
+                    });
+                    // ★ 发射压缩子事件（检测到溢出）
+                    this.emitCompactionPhase(compactionId, "detect", "Provider 返回上下文溢出", `消息: ${msgCountBefore}条, 大小: ${sizeBeforeKB}KB`);
+                    // 先尝试 prune 旧工具输出
+                    this.emitCompactionPhase(compactionId, "prune", "阶段1: 裁剪工具输出", "正在裁剪...");
+                    const pruneResult = pruneToolOutputs(this.state.conversation, contextLimit);
+                    this.emitCompactionPhase(compactionId, "prune_done", "阶段1: 裁剪工具输出", `裁剪了 ${pruneResult.prunedCount} 条工具输出, 释放 ${pruneResult.freedTokens} tokens`);
+                    // 再强制 summarize 早期对话（使用 LLM 摘要器提升摘要质量，失败降级到规则摘要）
+                    this.emitCompactionPhase(compactionId, "summarize", "阶段2: 摘要化对话", "正在摘要...");
+                    const summarizedCount = await summarizeConversation(this.state.conversation, {
+                        llmSummarizer: (input) => this.summarizeConversationWithLLM(input),
+                        contextLimit,
+                    });
+                    this.emitCompactionPhase(compactionId, "summarize_done", "阶段2: 摘要化对话", `摘要化了 ${summarizedCount} 条消息`);
+                    const sizeAfterKB = conversationSizeKB(this.state.conversation);
+                    const msgCountAfter = this.state.conversation.length;
                     contextOverflowCompacted = true;
+                    const compactedCount = pruneResult.prunedCount + summarizedCount;
+                    this.emitAcodeEvent("context_compaction", {
+                        action: "end",
+                        compactionId,
+                        sizeBeforeKB,
+                        sizeAfterKB,
+                        freedKB: Math.round((sizeBeforeKB - sizeAfterKB) * 10) / 10,
+                        messageCountBefore: msgCountBefore,
+                        messageCountAfter: msgCountAfter,
+                        strategy: summarizedCount > 0 ? "summarize" : "prune",
+                        freedTokens: pruneResult.freedTokens,
+                        prunedToolMessages: pruneResult.prunedCount,
+                        summarizedMessages: summarizedCount,
+                        trigger: "provider_overflow_error",
+                    });
                     if (compactedCount === 0) {
                         throw requestError;
                     }
+                    // ★ 响应式压缩后同样重置累积 token 计数
+                    this.state.accumulatedInputTokens = 0;
+                    this.state.accumulatedOutputTokens = 0;
                     this.emitAcodeEvent("warning", {
                         message: `ACode provider context limit exceeded; summarized ${compactedCount} older messages and rebuilt the request instead of retrying the same oversized payload`,
                     });
@@ -1457,6 +2154,8 @@ export class ACodeRuntime extends EventEmitter {
         const toolCallAccumulators = new Map();
         let text = "";
         let buffer = "";
+        /** 从 SSE 流最终 chunk 中提取的 usage（OpenAI 格式在最后一个 chunk 的 usage 字段中） */
+        let streamUsage;
         const consumeFrame = (frame) => {
             for (const data of parseSseDataLines(frame)) {
                 if (data === "[DONE]") {
@@ -1466,6 +2165,11 @@ export class ACodeRuntime extends EventEmitter {
                 if (!isRecord(payload)) {
                     continue;
                 }
+                // ★ 提取 SSE chunk 中的 usage（OpenAI 流式 API 在最后一个 chunk 返回完整 usage，此时 choices 为空数组）
+                const chunkUsage = payload.usage;
+                if (chunkUsage) {
+                    streamUsage = chunkUsage;
+                }
                 const choice = payload.choices?.[0];
                 const delta = choice?.delta;
                 const reasoningText = extractReasoningText(delta);
@@ -1510,17 +2214,18 @@ export class ACodeRuntime extends EventEmitter {
                     },
                 },
             ],
+            ...(streamUsage ? { usage: streamUsage } : {}),
         };
     }
     async handleToolCalls(toolCalls, commandAllowedTools, contextVersion = this.contextVersion) {
-        console.log(`[ACodeRuntime]  handleToolCalls started with ${toolCalls.length} tool(s)`);
+        runtimeDebugLog(`[ACodeRuntime]  handleToolCalls started with ${toolCalls.length} tool(s)`);
         for (const toolCall of toolCalls) {
             if (this.isTurnSuperseded(contextVersion)) {
-                console.log(`[ACodeRuntime] ️ Turn superseded, skipping remaining tools`);
+                runtimeDebugLog(`[ACodeRuntime] ️ Turn superseded, skipping remaining tools`);
                 return;
             }
             const toolName = toolCall.function.name;
-            console.log(`[ACodeRuntime] 🔍 Looking up tool: ${toolName}`);
+            runtimeDebugLog(`[ACodeRuntime] 🔍 Looking up tool: ${toolName}`);
             const tool = this.state.exposedTools.find((item) => item.exposedName === toolCall.function.name);
             if (!tool) {
                 console.error(`[ACodeRuntime] ❌ Tool not found: ${toolCall.function.name}, ` +
@@ -1532,11 +2237,11 @@ export class ACodeRuntime extends EventEmitter {
                 });
                 continue;
             }
-            console.log(`[ACodeRuntime]  Found tool: ${tool.toolName} (kind: ${tool.kind}, source: ${tool.kind === 'mcp' ? tool.serverName : 'builtin'})`);
+            runtimeDebugLog(`[ACodeRuntime]  Found tool: ${tool.toolName} (kind: ${tool.kind}, source: ${tool.kind === 'mcp' ? tool.serverName : 'builtin'})`);
             try {
                 if (tool.kind === "builtin") {
                     const toolArguments = coerceArguments(toolCall.function.arguments);
-                    console.log(`[ACodeRuntime]  Built-in tool arguments: ${JSON.stringify(toolArguments).slice(0, 200)}`);
+                    runtimeDebugLog(`[ACodeRuntime]  Built-in tool arguments: ${JSON.stringify(toolArguments).slice(0, 200)}`);
                     assertToolPermission(tool, this.state.permissions, commandAllowedTools);
                     const preResults = await this.hookBus.dispatch("PreToolUse", {
                         source: "builtin",
@@ -1553,7 +2258,7 @@ export class ACodeRuntime extends EventEmitter {
                         throw new Error(denied.message ||
                             `ACode tool denied by hook: ${tool.exposedName}`);
                     }
-                    console.log(`[ACodeRuntime]  Emitting mcp_status call_tool for ${tool.exposedName}`);
+                    runtimeDebugLog(`[ACodeRuntime]  Emitting mcp_status call_tool for ${tool.exposedName}`);
                     this.emitAcodeEvent("mcp_status", {
                         action: "call_tool",
                         server: "builtin",
@@ -1564,7 +2269,7 @@ export class ACodeRuntime extends EventEmitter {
                         argumentsPreview: summarizeToolArguments(toolArguments),
                     });
                     const toolStart = Date.now();
-                    console.log(`[ACodeRuntime] ▶️ Executing built-in tool: ${tool.exposedName}`);
+                    runtimeDebugLog(`[ACodeRuntime] ▶️ Executing built-in tool: ${tool.exposedName}`);
                     const result = await withTimeout(tool.execute(toolArguments, {
                         onOutput: (outputEvent) => {
                             this.emitAcodeEvent("command_output", {
@@ -1582,9 +2287,10 @@ export class ACodeRuntime extends EventEmitter {
                                     : {}),
                             });
                         },
+                        toolCallId: toolCall.id,
                     }), getBuiltInToolTimeoutMs(tool, toolArguments, this.state.provider.mcpToolTimeoutMs), `ACode built-in tool ${tool.toolName}`);
                     const toolDuration = Date.now() - toolStart;
-                    console.log(`[ACodeRuntime] ✅ Built-in tool ${tool.exposedName} completed in ${toolDuration}ms`);
+                    runtimeDebugLog(`[ACodeRuntime] ✅ Built-in tool ${tool.exposedName} completed in ${toolDuration}ms`);
                     if (this.isTurnSuperseded(contextVersion)) {
                         return;
                     }
@@ -1598,7 +2304,7 @@ export class ACodeRuntime extends EventEmitter {
                         return;
                     }
                     const resultText = toToolResultText(result);
-                    console.log(`[ACodeRuntime] 📤 Emitting mcp_status tool_result for ${tool.exposedName}, ` +
+                    runtimeDebugLog(`[ACodeRuntime] 📤 Emitting mcp_status tool_result for ${tool.exposedName}, ` +
                         `result length: ${resultText.length} chars`);
                     this.emitAcodeEvent("mcp_status", {
                         action: "tool_result",
@@ -1611,7 +2317,7 @@ export class ACodeRuntime extends EventEmitter {
                         tool_call_id: toolCall.id,
                         content: resultText,
                     });
-                    await this.appendSyntheticMultimodalUserMessage(resultText, contextVersion);
+                    await this.appendSyntheticMultimodalUserMessage(resultText, toolCall.id, contextVersion);
                     continue;
                 }
                 // MCP工具处理
@@ -1627,7 +2333,7 @@ export class ACodeRuntime extends EventEmitter {
                     continue;
                 }
                 const toolArguments = coerceArguments(toolCall.function.arguments);
-                console.log(`[ACodeRuntime]  MCP tool arguments: ${JSON.stringify(toolArguments).slice(0, 200)}`);
+                runtimeDebugLog(`[ACodeRuntime]  MCP tool arguments: ${JSON.stringify(toolArguments).slice(0, 200)}`);
                 assertToolPermission(tool, this.state.permissions, commandAllowedTools);
                 const preResults = await this.hookBus.dispatch("PreToolUse", {
                     source: "mcp",
@@ -1644,7 +2350,7 @@ export class ACodeRuntime extends EventEmitter {
                     console.error(`[ACodeRuntime] ❌ MCP tool denied by hook: ${tool.exposedName}: ${denied.message}`);
                     throw new Error(denied.message || `ACode tool denied by hook: ${tool.exposedName}`);
                 }
-                console.log(`[ACodeRuntime] 📤 Emitting mcp_status call_tool for MCP ${tool.exposedName}`);
+                runtimeDebugLog(`[ACodeRuntime] 📤 Emitting mcp_status call_tool for MCP ${tool.exposedName}`);
                 this.emitAcodeEvent("mcp_status", {
                     action: "call_tool",
                     server: tool.serverName,
@@ -1659,11 +2365,11 @@ export class ACodeRuntime extends EventEmitter {
                     ? this.state.provider.mcpPollingToolTimeoutMs
                     : this.state.provider.mcpToolTimeoutMs;
                 const toolStart = Date.now();
-                console.log(`[ACodeRuntime] ▶️ Executing MCP tool: ${tool.exposedName} ` +
+                runtimeDebugLog(`[ACodeRuntime] ▶️ Executing MCP tool: ${tool.exposedName} ` +
                     `(timeout: ${toolTimeoutMs}ms, polling: ${isPollingTool})`);
                 const result = await this.callMcpToolWithTimeout(connection, tool, toolArguments, toolTimeoutMs, isPollingTool);
                 const toolDuration = Date.now() - toolStart;
-                console.log(`[ACodeRuntime] ✅ MCP tool ${tool.exposedName} completed in ${toolDuration}ms`);
+                runtimeDebugLog(`[ACodeRuntime] ✅ MCP tool ${tool.exposedName} completed in ${toolDuration}ms`);
                 if (this.isTurnSuperseded(contextVersion)) {
                     return;
                 }
@@ -1678,7 +2384,7 @@ export class ACodeRuntime extends EventEmitter {
                     return;
                 }
                 const resultText = toToolResultText(result);
-                console.log(`[ACodeRuntime] 📤 Emitting mcp_status tool_result for MCP ${tool.exposedName}, ` +
+                runtimeDebugLog(`[ACodeRuntime] 📤 Emitting mcp_status tool_result for MCP ${tool.exposedName}, ` +
                     `result length: ${resultText.length} chars`);
                 this.emitAcodeEvent("mcp_status", {
                     action: "tool_result",
@@ -1691,7 +2397,7 @@ export class ACodeRuntime extends EventEmitter {
                     tool_call_id: toolCall.id,
                     content: resultText,
                 });
-                await this.appendSyntheticMultimodalUserMessage(resultText, contextVersion);
+                await this.appendSyntheticMultimodalUserMessage(resultText, toolCall.id, contextVersion);
             }
             catch (error) {
                 console.error(`[ACodeRuntime] ❌ Tool execution failed: ${toolCall.function.name}`, error instanceof Error ? error.message : String(error));
@@ -1699,13 +2405,13 @@ export class ACodeRuntime extends EventEmitter {
                     return;
                 }
                 if (this.abortRequested || this.state.terminated) {
-                    console.log(`[ACodeRuntime] ⚠️ Rethrowing error due to abort/termination`);
+                    runtimeDebugLog(`[ACodeRuntime] ⚠️ Rethrowing error due to abort/termination`);
                     throw error instanceof Error ? error : new Error(String(error));
                 }
                 this.appendToolFailureResult(toolCall, tool, error);
             }
         }
-        console.log(`[ACodeRuntime]  handleToolCalls completed for all ${toolCalls.length} tool(s)`);
+        runtimeDebugLog(`[ACodeRuntime]  handleToolCalls completed for all ${toolCalls.length} tool(s)`);
     }
     async callMcpToolWithTimeout(connection, tool, toolArguments, timeoutMs, retrySdkTimeout) {
         const sdkTimeout = timeoutMs > 0 ? timeoutMs : MCP_SDK_MAX_SAFE_TIMEOUT_MS;
@@ -1776,7 +2482,7 @@ export class ACodeRuntime extends EventEmitter {
             notifyStop();
         }
     }
-    async appendSyntheticMultimodalUserMessage(toolResultText, contextVersion = this.contextVersion) {
+    async appendSyntheticMultimodalUserMessage(toolResultText, toolCallId, contextVersion = this.contextVersion) {
         const parsedContent = parseAttachmentMessage(toolResultText);
         if (!parsedContent.hasImages) {
             return;
@@ -1792,11 +2498,48 @@ export class ACodeRuntime extends EventEmitter {
             return;
         }
         this.state.conversation.push({ role: "user", content });
+        // 去重：将对应 tool 消息中的图片/附件数据替换为占位符，
+        // 避免 conversation 中同时存在原始 tool 结果和解析后的 user 消息导致重复。
+        const toolMsg = this.state.conversation.find((m) => m.role === "tool" && m.tool_call_id === toolCallId);
+        if (toolMsg && typeof toolMsg.content === "string") {
+            let cleaned;
+            // 尝试 JSON 格式：移除 attachments 数组，保留 text 和 messages
+            try {
+                const parsed = JSON.parse(toolMsg.content);
+                if (typeof parsed === "object" && parsed !== null) {
+                    const clone = { ...parsed };
+                    if ("attachments" in clone) {
+                        delete clone.attachments;
+                        cleaned = JSON.stringify(clone);
+                    }
+                }
+            }
+            catch {
+                // 不是 JSON，尝试 marker 格式
+            }
+            if (cleaned === undefined) {
+                const markerCleaned = toolMsg.content
+                    .replace(/\[(图片|文件)\s*:\s*([^\]\n]*?)\s*\]/gi, "")
+                    .trim();
+                if (markerCleaned !== toolMsg.content) {
+                    cleaned = markerCleaned;
+                }
+            }
+            if (cleaned !== undefined && cleaned.length > 0) {
+                toolMsg.content = cleaned;
+            }
+            else if (cleaned !== undefined) {
+                toolMsg.content = "[Tool result contained images; see user message above]";
+            }
+        }
     }
     appendToolFailureResult(toolCall, tool, error) {
         const resultText = toToolErrorResultText(tool, error);
+        // 工具执行失败是正常运行过程的一部分（Agent 会继续处理失败结果）。
+        // 标记 nonFatal=true 让 adapter 不变更运行态为 "error"，避免面板按钮异常。
         this.emitAcodeEvent("error", {
             message: `ACode tool failed: ${tool.exposedName}: ${getErrorMessage(error)}`,
+            nonFatal: true,
         });
         this.emitAcodeEvent("mcp_status", {
             action: "tool_result",
@@ -1869,6 +2612,63 @@ export class ACodeRuntime extends EventEmitter {
             requestInit,
         });
     }
+    /**
+     * 通过 MCP 连接调用 get_profile 工具获取用户 profile 信息，
+     * 格式化为文本后返回，用于拼接到 rolePrompt 下方。
+     * 主流程：遍历已连接的 MCP -> 找到 get_profile 工具 -> 调用 -> 格式化结果。
+     * 容错：任何步骤失败都返回空字符串，不阻塞启动。
+     */
+    async fetchProfilePrompt(mcpConnections) {
+        for (const connection of mcpConnections) {
+            const profileTool = connection.tools.find((tool) => tool.toolName === "get_profile");
+            if (!profileTool) {
+                continue;
+            }
+            try {
+                const result = await withTimeout(connection.client.callTool({ name: "get_profile", arguments: {} }, undefined, { timeout: DEFAULT_MCP_TOOL_CALL_TIMEOUT_MS }), DEFAULT_MCP_TOOL_CALL_TIMEOUT_MS, "ACode startup get_profile");
+                const profile = this.extractProfileFromToolResult(result);
+                return buildProfilePrompt(profile);
+            }
+            catch (error) {
+                this.emitAcodeEvent("warning", {
+                    message: `ACode failed to fetch profile via ${connection.serverName}/get_profile: ${error instanceof Error ? error.message : String(error)}`,
+                });
+                return "";
+            }
+        }
+        return "";
+    }
+    /**
+     * 从 MCP callTool 返回值中提取 profile 对象。
+     * 主流程：优先取 content[0].text JSON -> 回退到 result 本身为对象。
+     */
+    extractProfileFromToolResult(result) {
+        if (!isRecord(result)) {
+            return null;
+        }
+        const content = result.content;
+        if (Array.isArray(content)) {
+            for (const item of content) {
+                if (!isRecord(item))
+                    continue;
+                if (typeof item.text === "string" && item.text.trim()) {
+                    try {
+                        const parsed = JSON.parse(item.text);
+                        if (isRecord(parsed)) {
+                            return parsed;
+                        }
+                    }
+                    catch {
+                        // text 不是 JSON，继续
+                    }
+                }
+            }
+        }
+        if (isRecord(result)) {
+            return result;
+        }
+        return null;
+    }
     async disconnectMcpServers() {
         const connections = this.state.mcpConnections;
         this.state.mcpConnections = [];
@@ -1878,3 +2678,5 @@ export class ACodeRuntime extends EventEmitter {
         }, this.state.provider.mcpToolTimeoutMs)));
     }
 }
+/** skill 重扫防抖间隔（毫秒） */
+ACodeRuntime.SKILL_REFRESH_DEBOUNCE_MS = 500;