@aalis/plugin-agent 0.13.6 → 0.15.0

package/dist/index.js

@@ -1,12 +1,50 @@
 import { Buffer } from 'node:buffer';
-import { useCommandService } from '@aalis/api-commands';
-import { listLLMModels, resolveLLMModel } from '@aalis/api-llm';
-import { getPlatformSelfIdentity } from '@aalis/api-platform';
-import { asToolExecutionResult } from '@aalis/api-tools';
-import { CONTROL_KINDS, getMessageName, getSenderLabel, WellKnownKinds } from '@aalis/schema-message';
+import { agent as agentService, } from '@aalis/api-agent';
+import { commands as commandsService } from '@aalis/api-commands';
+import { contributions } from '@aalis/api-contributions';
+import { gateway as gatewayService } from '@aalis/api-gateway';
+import { hooks } from '@aalis/api-hooks';
+import { listLLMModels, llm as llmService, resolveLLMModel } from '@aalis/api-llm';
+import { media as mediaService } from '@aalis/api-media';
+import { memory as memoryService } from '@aalis/api-memory';
+import { messageArchive as messageArchiveService } from '@aalis/api-message-archive';
+import { persona as personaService } from '@aalis/api-persona';
+import { getPlatformSelfIdentity, platform as platformService } from '@aalis/api-platform';
+import { sessionManager as sessionManagerService } from '@aalis/api-session-manager';
+import { createStorageGateway, storage as storageService } from '@aalis/api-storage';
+import { tools as toolsService, } from '@aalis/api-tools';
+import { config as configCap, definePlugin, events, lifecycle, logger as loggerCap, optional, pluginsService, provide, services, } from '@aalis/core';
+import { CONTROL_KINDS, getMessageName, getSenderLabel, WellKnownKinds, WellKnownMetadataKeys, } from '@aalis/schema-message';
 import { normalizeAssistantContent, stripLeakedSpecialTokens, truncateChars } from '@aalis/util-text-normalize';
-import { buildFocusGuidance, describeLLMFailure, estimateMsgTokens, estimateTextTokens, estimateTokens, formatTimeLabel, INPUT_CONVENTIONS, isSameMessage, } from './helpers.js';
+import { buildFocusGuidance, describeLLMFailure, estimateMsgTokens, estimateTextTokens, estimateTokens, formatTimeLabel, formatToolArgsForLog, INPUT_CONVENTIONS, isSameMessage, toPersonaOptions, } from './helpers.js';
 import { assemblePromptContributions, VOLATILE_INJECTOR } from './prompt-assembly.js';
+// ===== 能力声明 =====
+//
+// 对话编排要碰的东西全在这里：没写进 uses 的，插件碰不到。全部 optional——少一样能力
+// 只是少一段能力（没有 memory 就没有历史、没有 tools 就把「工具不可用」回给模型、没有
+// gateway 就直接走事件总线），不该让整个 agent 停活。
+const uses = {
+    logger: loggerCap,
+    config: configCap,
+    events,
+    hooks,
+    contributions,
+    lifecycle,
+    provide,
+    services,
+    commands: optional(commandsService),
+    tools: optional(toolsService),
+    llm: optional(llmService),
+    memory: optional(memoryService),
+    persona: optional(personaService),
+    messageArchive: optional(messageArchiveService),
+    sessionManager: optional(sessionManagerService),
+    platform: optional(platformService),
+    media: optional(mediaService),
+    storage: optional(storageService),
+    gateway: optional(gatewayService),
+    plugins: optional(pluginsService),
+};
 /**
  * 默认 Agent 实现 —— 对话编排器
  *
@@ -26,7 +64,7 @@ function getModelMaxOutput(llm) {
     return llm.maxOutputTokens ?? DEFAULT_MAX_OUTPUT_TOKENS;
 }
 class DefaultAgent {
-    ctx;
+    caps;
     logger;
     systemPrompt;
     memoryTokenBudget;
@@ -45,8 +83,15 @@ class DefaultAgent {
      * 独立管理，互不打断；同来源新消息会中止旧的生成。
      */
     activeControllers = new Map();
+    /**
+     * 在飞回合 Promise。关停时 abort 之后等它们以 AbortError（或正常完成）收尾，
+     * 而不是等 LLM 跑完——收尾里的钩子 / 出站事件还要用 memory。
+     */
+    inflightTurns = new Set();
     /** 同一 lane 的入站消息归档串行化，避免连续消息读取历史时漏掉前一条输入。 */
     archiveQueues = new Map();
+    /** 每次激活只在实际写入缺少归档时告警一次，不因插件加载顺序误报。 */
+    archiveUnavailableWarned = false;
     /**
      * 节流日志状态：记录每个 session 上次 token:usage 日志的"轮次"与 ratio 桶。
      * - 跨过 0.5/0.7/0.85 三个阈值必输出
@@ -54,11 +99,12 @@ class DefaultAgent {
      * 与 token:usage 事件共用同一份 breakdown 数据，零额外计算。
      */
     tokenLogState = new Map();
-    /** 已注册的预处理器（name → { priority, dispose }） */
+    /** 已注册的预处理器（name → { dispose }） */
     preprocessors = new Map();
-    constructor(ctx, config) {
-        this.ctx = ctx;
-        this.logger = ctx.logger.child('agent');
+    constructor(caps) {
+        this.caps = caps;
+        this.logger = caps.logger.child('agent');
+        const config = caps.config;
         this.systemPrompt = config.systemPrompt || '';
         this.memoryTokenBudget = config.memoryTokenBudget ?? 4096;
         this.historyLimit = config.historyLimit ?? 50;
@@ -82,25 +128,25 @@ class DefaultAgent {
     async resolveLLM(platform, sessionId) {
         let ref;
         // session-manager 一步到位：会话 > 父 sessionDefaults > platform profile
-        const sm = this.ctx.getService('session-manager');
+        const sm = this.caps.sessionManager.current;
         if (sm && sessionId) {
             const resolved = sm.resolveConfig(sessionId, platform);
             if (resolved.llm?.provider && resolved.llm?.model)
                 ref = resolved.llm;
         }
         // 解析为具体 LLMModel entry（要求至少 chat 能力；ref 为空时走 ServicePreference / 优先级）
-        return resolveLLMModel(this.ctx, ref, ['chat']);
+        return resolveLLMModel(this.caps.llm, ref, ['chat']);
     }
     /** 解析失败时说清**为什么**（取数在此，措辞在 helpers 的 describeLLMFailure，纯函数便于单测）。 */
     explainLLMFailure(platform, sessionId) {
-        const available = listLLMModels(this.ctx, { caps: ['chat'] }).map(e => e.contextId);
-        const sm = this.ctx.getService('session-manager');
+        const available = listLLMModels(this.caps.llm, { caps: ['chat'] }).map(e => e.contextId);
+        const sm = this.caps.sessionManager.current;
         const wanted = sm && sessionId ? sm.resolveConfig(sessionId, platform).llm : undefined;
         return describeLLMFailure(available, wanted, this.erroredLLMPlugins());
     }
     /** 激活失败且声明提供 llm 的插件——「一个模型都没有」时，病因通常就在它们身上（多为缺 apiKey）。 */
     erroredLLMPlugins() {
-        const pm = this.ctx.getService('plugins');
+        const pm = this.caps.plugins.current;
         if (!pm)
             return [];
         // 这串会拼进**发到聊天**的文案里，原因文本来自插件自抛的 error，长度不可控：
@@ -129,10 +175,10 @@ class DefaultAgent {
     /**
      * 中止全部在飞回合（拆卸路径用）。
      *
-     * activeControllers 是实例私有的，bounce 后新实例看不见旧实例的在飞回合；而拆卸链不等任何
-     * 回合——旧回合会在已 dispose 的 ctx 上跑完并投递（人设/模型都是 bounce 前的），用户在它
-     * 结束前再发一条，两个实例就并发答同一会话。abort 走的是已有的 AbortError 收尾
-     * （outbound:stream done + turn:after outcome='aborted'），与 WebUI「停止生成」同语义。
+     * activeControllers 是实例私有的，bounce 后新实例看不见旧实例的在飞回合。
+     * abort 走已有的 AbortError 收尾（outbound:stream done + turn:after outcome='aborted'），
+     * 与 WebUI「停止生成」同语义。关停在 onDrain 里先调本方法再等回合 Promise；
+     * onDispose 再调一次作兜底（已中止的 controller 不在表里，是空操作）。
      */
     abortAll() {
         let n = 0;
@@ -144,6 +190,20 @@ class DefaultAgent {
         if (n > 0)
             this.logger.info(`拆卸：已中止 ${n} 个在飞回合`);
     }
+    /**
+     * 关停收尾：中止在飞回合并等待其 AbortError（或正常完成）收尾落定。
+     * 超时由 core 对 onDrain 回调的 disposeTimeoutMs 护栏负责，不另加配置键。
+     */
+    async abortInflightAndSettle() {
+        this.abortAll();
+        if (this.inflightTurns.size === 0)
+            return;
+        await Promise.allSettled([...this.inflightTurns]);
+    }
+    /** 会话删除时丢弃其节流日志状态（订阅见 run() 的 session:deleted）。 */
+    dropTokenLogState(sessionId) {
+        this.tokenLogState.delete(sessionId);
+    }
     /**
      * 注册输入预处理器（如图片识别、文件读取、用户画像等）。
      * 多个预处理器按注册顺序串行执行（Koa-style 洋葱模型）。
@@ -154,7 +214,7 @@ class DefaultAgent {
     registerPreprocessor(name, handler) {
         // 同名替换
         this.preprocessors.get(name)?.dispose();
-        const dispose = this.ctx.middleware('agent:input:before', async (data, next) => {
+        const dispose = this.caps.hooks.middleware('agent:input:before', async (data, next) => {
             await handler(data.message, next);
         });
         // 退订按条目引用比对：同名重注册后，旧退订闭包只摘自己的中间件，不动新登记的账目
@@ -184,7 +244,7 @@ class DefaultAgent {
      * （平台属于独立子系统，由 api-platform 的 helper 负责）。
      */
     getPluginGroups() {
-        const pm = this.ctx.getService('plugins');
+        const pm = this.caps.plugins.current;
         if (!pm)
             return [];
         // 子系统归属：Agent 域的服务（不含 platform——平台是独立子系统）
@@ -203,7 +263,7 @@ class DefaultAgent {
      * 同时构建本轮调用的 segments 时间线（按 chunk 到达顺序记录 text / reasoning_text，
      * 相邻同类合并）——用于上层将多轮调用 + 工具执行交错拼接成统一时间线。
      */
-    async consumeStream(llm, request, sessionId, platform, signal) {
+    async consumeStream(llm, request, sessionId, platform) {
         let content = '';
         let reasoningContent = '';
         let toolCalls;
@@ -220,13 +280,13 @@ class DefaultAgent {
         };
         for await (const chunk of llm.chatStream(request)) {
             // 检查中止信号
-            if (signal?.aborted) {
+            if (request.signal?.aborted) {
                 throw new DOMException('Generation aborted', 'AbortError');
             }
             if (chunk.contentDelta) {
                 content += chunk.contentDelta;
                 appendDelta('text', chunk.contentDelta);
-                await this.ctx.emit('outbound:stream', {
+                await this.caps.events.emit('outbound:stream', {
                     sessionId,
                     platform,
                     contentDelta: chunk.contentDelta,
@@ -235,14 +295,14 @@ class DefaultAgent {
             if (chunk.reasoningDelta) {
                 reasoningContent += chunk.reasoningDelta;
                 appendDelta('reasoning_text', chunk.reasoningDelta);
-                await this.ctx.emit('outbound:stream', {
+                await this.caps.events.emit('outbound:stream', {
                     sessionId,
                     platform,
                     reasoningDelta: chunk.reasoningDelta,
                 });
             }
             if (chunk.toolCallProgress) {
-                await this.ctx.emit('outbound:stream', {
+                await this.caps.events.emit('outbound:stream', {
                     sessionId,
                     platform,
                     toolCallProgress: chunk.toolCallProgress,
@@ -260,7 +320,7 @@ class DefaultAgent {
             // 兜底剥离 LLM 端漏出的特殊 token 残渣（DSML 等），同时修复 GFM 表格
             const { sanitized, hadLeak } = stripLeakedSpecialTokens(content);
             if (hadLeak) {
-                this.ctx.logger.warn(`agent: 检测到 LLM 内容残留 DSML 标记，已剥离（session=${sessionId} platform=${platform} 原长=${content.length} 净化后=${sanitized.length}）`);
+                this.caps.logger.warn(`agent: 检测到 LLM 内容残留 DSML 标记，已剥离（session=${sessionId} platform=${platform} 原长=${content.length} 净化后=${sanitized.length}）`);
             }
             finalContent = normalizeAssistantContent(content);
         }
@@ -383,14 +443,23 @@ class DefaultAgent {
             prev.abort();
         const controller = new AbortController();
         this.activeControllers.set(lane, controller);
+        const turn = (async () => {
+            try {
+                await this._handleMessageInner(incoming, controller.signal, lane);
+            }
+            finally {
+                // 仅清理自己创建的 controller（避免清掉后续新请求的）
+                if (this.activeControllers.get(lane) === controller) {
+                    this.activeControllers.delete(lane);
+                }
+            }
+        })();
+        this.inflightTurns.add(turn);
         try {
-            await this._handleMessageInner(incoming, controller.signal, lane);
+            await turn;
         }
         finally {
-            // 仅清理自己创建的 controller（避免清掉后续新请求的）
-            if (this.activeControllers.get(lane) === controller) {
-                this.activeControllers.delete(lane);
-            }
+            this.inflightTurns.delete(turn);
         }
     }
     async _handleMessageInner(incoming, signal, lane) {
@@ -401,7 +470,7 @@ class DefaultAgent {
             metadata: {},
         };
         let handled = false;
-        await this.ctx.runHook('agent:input:before', msgHookData, async () => {
+        await this.caps.hooks.run('agent:input:before', msgHookData, async () => {
             handled = true;
             // ===== defaultAction: 全部消息处理逻辑在此 =====
             // 中间件不调用 next() → 此处永远不执行 → 消息被拦截
@@ -425,16 +494,13 @@ class DefaultAgent {
             // 默认 provider 全局窗口与会话实际 model 不一致的偏差（Bug F 结构性修复）。
             const maxTokens = getModelMaxOutput(llm);
             const contextLength = llm.contextLength;
-            // 预留 token 预算 = 上下文长度 × trimThresholdRatio - 最大输出 token - 安全余量
-            // trimThresholdRatio < 1 可提前触发裁剪，默认 1.0 = 用满扣除输出预留后的可用窗口
-            const tokenBudget = Math.max(1024, Math.floor(contextLength * this.trimThresholdRatio) - maxTokens - 512);
-            // Bug B 防回溯：本回合中通过工具循环写入到 memory 的 (assistant+toolCalls + tool 结果) 消息时间戳。
-            // 用户中途点「停止生成」时，这些条目要从历史中删除——否则下一条消息发出后，agent 会再次
-            // 看到上一轮被中断的工具调用 + 半截 assistant 文本，导致「假回退」。
+            const tokenBudget = this.computeTokenBudget(contextLength, maxTokens);
+            // 本回合经工具循环写入 memory 的 (assistant+toolCalls + tool 结果) 消息时间戳。
+            // 只用于中止日志里的条数：中止时这些已完成的工具调用记录保留不回滚（见下方 catch 分支）。
             const turnPersistedTimestamps = [];
             try {
                 // 统一解析 session 配置（一次解析，多处复用）
-                const sessionMgr = this.ctx.getService('session-manager');
+                const sessionMgr = this.caps.sessionManager.current;
                 const resolved = sessionMgr && incoming.sessionId
                     ? sessionMgr.resolveConfig(incoming.sessionId, incoming.platform)
                     : undefined;
@@ -444,13 +510,7 @@ class DefaultAgent {
                     ? sessionMaxIter
                     : this.maxToolIterations;
                 // 构建 persona 会话选项（从 resolved config 中提取，传给 persona 服务）
-                const personaOpts = resolved
-                    ? {
-                        persona: resolved.persona,
-                        disableOutputFormat: resolved.disableOutputFormat,
-                        clientSideJsonRendering: resolved.clientSideJsonRendering,
-                    }
-                    : undefined;
+                const personaOpts = toPersonaOptions(resolved);
                 // 会话级 thinking 覆盖（/session.set -t on|off）：未设置则不带 think 字段，
                 // 由各 provider 按自己的全局配置决定（ollama thinking / deepseek thinkingMode）。
                 const thinkOverride = resolved?.think;
@@ -461,9 +521,7 @@ class DefaultAgent {
                     enabledGroups = resolved.enabledToolGroups;
                 }
                 this.logger.debug(`工具分组: platform=${incoming.platform}, enabledGroups=${enabledGroups ? JSON.stringify(enabledGroups) : '(无)'}`);
-                const tools = this.ctx
-                    .getService('tools')
-                    ?.getDefinitions(enabledGroups ? { groups: enabledGroups } : undefined) ?? [];
+                const tools = this.caps.tools.current?.getDefinitions(enabledGroups ? { groups: enabledGroups } : undefined) ?? [];
                 const toolCtx = {
                     sessionId: incoming.sessionId,
                     // platform/userId 保持**会话/物理**语义（定时任务归属、平台档继承、记忆平台域、
@@ -493,11 +551,11 @@ class DefaultAgent {
                     triggerType: incoming.triggerType,
                 };
                 // 组装先于链：贡献块（档案/技能/记忆/即时提示）先物化，拦截者审完整成品
-                await assemblePromptContributions(this.ctx, llmBeforeData, {
+                await assemblePromptContributions(this.caps, llmBeforeData, {
                     buildTimeoutMs: this.promptBuildTimeoutMs,
                     signal,
                 });
-                await this.ctx.runHook('agent:llm:before', llmBeforeData, undefined, { warnOnStall: true });
+                await this.caps.hooks.run('agent:llm:before', llmBeforeData, undefined, { warnOnStall: true });
                 // 裁剪消息以确保不超过上下文窗口
                 llmBeforeData.messages = this.trimMessages(llmBeforeData.messages, tokenBudget);
                 // 推送 token 使用量统计
@@ -509,7 +567,7 @@ class DefaultAgent {
                 // 本轮初始时间与累加用量，用于最终 assistant 消息的 modelInfo 元数据。
                 const turnStartTs = t0;
                 // 注：缓存命中量（usage.cachedPromptTokens）不进这里——本对象只喂
-                // assistant 消息的 modelInfo，而其字段是逐个挑的（见下方 :896 附近），
+                // assistant 消息的 modelInfo，而其字段是逐个挑的（见下方 turnModelInfo），
                 // 加进来也不会流到下游。命中率的观测出口是 LLM 响应日志那一行。
                 const turnUsageAcc = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
                 const accUsage = (u) => {
@@ -531,7 +589,7 @@ class DefaultAgent {
                     maxTokens,
                     signal,
                     ...(thinkOverride !== undefined ? { think: thinkOverride } : {}),
-                }, incoming.sessionId, incoming.platform, signal);
+                }, incoming.sessionId, incoming.platform);
                 accUsage(firstResult.usage);
                 // 维护本轮（一次完整对话回合）的统一时间线 segments：
                 // 多次 LLM 调用 + 工具执行的输出按到达顺序拼接，保留模型原本的"思考/回答/工具/思考/回答"交错。
@@ -540,7 +598,7 @@ class DefaultAgent {
                 this.debugLogResponse(response, Date.now() - t0);
                 // Hook: agent:llm:after — 插件可以处理 LLM 返回结果
                 const llmAfterData = { response, messages: llmBeforeData.messages };
-                await this.ctx.runHook('agent:llm:after', llmAfterData);
+                await this.caps.hooks.run('agent:llm:after', llmAfterData);
                 response = llmAfterData.response;
                 // 收集所有思考内容
                 const allReasoning = [];
@@ -600,54 +658,89 @@ class DefaultAgent {
                         }
                         // Hook: agent:tool:before — 插件可以拦截或修改工具调用
                         const toolBeforeData = { name: toolCall.function.name, args, toolCallContext: toolCtx };
-                        await this.ctx.runHook('agent:tool:before', toolBeforeData);
-                        // 通知平台：工具开始执行
-                        await this.ctx.emit('tool:execute', {
-                            sessionId: incoming.sessionId,
-                            platform: incoming.platform,
-                            toolName: toolBeforeData.name,
-                            args: toolBeforeData.args,
-                            phase: 'start',
-                        });
-                        this.logger.debug(`工具执行: ${toolBeforeData.name} 参数=${JSON.stringify(toolBeforeData.args)}`);
-                        const toolT0 = Date.now();
-                        const executed = asToolExecutionResult(await (this.ctx
-                            .getService('tools')
-                            ?.execute(toolBeforeData.name, toolBeforeData.args, toolCtx) ??
-                            Promise.resolve({ content: JSON.stringify({ error: 'tools 服务不可用' }) })));
-                        let result = executed.content;
-                        // 工具交给主模型看的图：只随本回合的 tool 消息走（出口由 prepareLLMMessages 编码），
-                        // 不进钩子/事件/时间线（那些面都是文本），也不落库（见 saveToolCallGroup）。
-                        const resultImages = executed.images;
-                        // Hook: agent:tool:after — 插件可以处理工具执行结果
-                        const toolAfterData = { name: toolBeforeData.name, result, toolCallContext: toolCtx };
-                        await this.ctx.runHook('agent:tool:after', toolAfterData);
-                        result = toolAfterData.result;
-                        // 工具结果截断：按上下文窗口比例限制单条工具结果长度
-                        if (result.length > toolResultMaxChars) {
-                            this.logger.info(`工具结果过长 (${result.length} 字符)，截断至 ${toolResultMaxChars} 字符: ${toolBeforeData.name}`);
-                            result = truncateChars(result, toolResultMaxChars, `\n... [工具输出已截断，原始长度 ${result.length} 字符]`);
+                        // 单个工具的链路异常（钩子 / 守卫 / 结果处理抛错）只算该工具失败，转成它自己的错误结果：
+                        // 整批照常落定、整组落库，兄弟工具已发生的副作用不会因连坐而从历史里消失。
+                        // executeDone 区分失败发生在执行前还是执行后——后者须明说「已执行」，免得模型重做有副作用的操作。
+                        let executeDone = false;
+                        let toolT0;
+                        try {
+                            await this.caps.hooks.run('agent:tool:before', toolBeforeData);
+                            // 通知平台：工具开始执行
+                            await this.caps.events.emit('tool:execute', {
+                                sessionId: incoming.sessionId,
+                                platform: incoming.platform,
+                                toolName: toolBeforeData.name,
+                                args: toolBeforeData.args,
+                                phase: 'start',
+                            });
+                            // 紧随 start 赋值：catch 据此判断 start 已发出、要补发配对的 end
+                            toolT0 = Date.now();
+                            this.logger.debug(`工具执行: ${toolBeforeData.name} 参数=${formatToolArgsForLog(toolBeforeData.args)}`);
+                            const executed = await (this.caps.tools.current?.execute(toolBeforeData.name, toolBeforeData.args, toolCtx) ?? Promise.resolve({ content: JSON.stringify({ error: 'tools 服务不可用' }) }));
+                            executeDone = true;
+                            let result = executed.content;
+                            // 工具交给主模型看的图：只随本回合的 tool 消息走（出口由 prepareLLMMessages 编码），
+                            // 不进钩子/事件/时间线（那些面都是文本），也不落库（见 saveToolCallGroup）。
+                            const resultImages = executed.images;
+                            // Hook: agent:tool:after — 插件可以处理工具执行结果
+                            const toolAfterData = { name: toolBeforeData.name, result, toolCallContext: toolCtx };
+                            await this.caps.hooks.run('agent:tool:after', toolAfterData);
+                            result = toolAfterData.result;
+                            // 工具结果截断：按上下文窗口比例限制单条工具结果长度
+                            if (result.length > toolResultMaxChars) {
+                                this.logger.info(`工具结果过长 (${result.length} 字符)，截断至 ${toolResultMaxChars} 字符: ${toolBeforeData.name}`);
+                                result = truncateChars(result, toolResultMaxChars, `\n... [工具输出已截断，原始长度 ${result.length} 字符]`);
+                            }
+                            const toolEndTime = Date.now();
+                            this.logger.debug(`工具完成: ${toolBeforeData.name} (${toolEndTime - toolT0}ms) 结果=${result}`);
+                            // 通知平台：工具执行完成
+                            await this.caps.events.emit('tool:execute', {
+                                sessionId: incoming.sessionId,
+                                platform: incoming.platform,
+                                toolName: toolBeforeData.name,
+                                args: toolBeforeData.args,
+                                phase: 'end',
+                                result,
+                            });
+                            return {
+                                toolCall,
+                                result,
+                                resultImages,
+                                toolName: toolBeforeData.name,
+                                toolArgs: toolBeforeData.args,
+                                startTime: toolT0,
+                                endTime: toolEndTime,
+                            };
+                        }
+                        catch (err) {
+                            // 执行后的失败不回退到原始结果（fail-closed）：after 钩子可能是脱敏钩子，失败时原始输出不能漏给模型
+                            const reason = err instanceof Error ? err.message : String(err);
+                            this.logger.warn(`工具${executeDone ? '已执行，但结果处理' : '调用'}失败: ${toolBeforeData.name} (${reason})`);
+                            const failedAt = Date.now();
+                            const result = JSON.stringify({
+                                error: executeDone ? `工具已执行，但结果处理失败：${reason}` : `工具调用失败：${reason}`,
+                            });
+                            // start 已发出就补发配对的 end（emit 恒 resolve）：否则 WebUI 流式缓冲里这一段一直显示执行中
+                            if (toolT0 !== undefined) {
+                                await this.caps.events.emit('tool:execute', {
+                                    sessionId: incoming.sessionId,
+                                    platform: incoming.platform,
+                                    toolName: toolBeforeData.name,
+                                    args: toolBeforeData.args,
+                                    phase: 'end',
+                                    result,
+                                });
+                            }
+                            return {
+                                toolCall,
+                                result,
+                                resultImages: undefined,
+                                toolName: toolBeforeData.name,
+                                toolArgs: toolBeforeData.args,
+                                startTime: toolT0 ?? failedAt,
+                                endTime: failedAt,
+                            };
                         }
-                        const toolEndTime = Date.now();
-                        this.logger.debug(`工具完成: ${toolBeforeData.name} (${toolEndTime - toolT0}ms) 结果=${result}`);
-                        // 通知平台：工具执行完成
-                        await this.ctx.emit('tool:execute', {
-                            sessionId: incoming.sessionId,
-                            platform: incoming.platform,
-                            toolName: toolBeforeData.name,
-                            args: toolBeforeData.args,
-                            phase: 'end',
-                            result,
-                        });
-                        return {
-                            toolCall,
-                            result,
-                            resultImages,
-                            toolName: toolBeforeData.name,
-                            toolArgs: toolBeforeData.args,
-                            startTime: toolT0,
-                            endTime: toolEndTime,
-                        };
                     }));
                     // 工具交出的图只服务紧接着的这一次请求：上一轮工具结果里的图在这里剥掉，否则多轮
                     // 工具迭代会让图片在上下文里累积（每张数百 token，且不受文本裁剪约束）。
@@ -691,11 +784,11 @@ class DefaultAgent {
                         triggerType: incoming.triggerType,
                     };
                     // 已物化的贡献按全局键跳过；本轮工具调用新注册的贡献（如新激活技能）增量落位
-                    await assemblePromptContributions(this.ctx, nextLlmData, {
+                    await assemblePromptContributions(this.caps, nextLlmData, {
                         buildTimeoutMs: this.promptBuildTimeoutMs,
                         signal,
                     });
-                    await this.ctx.runHook('agent:llm:before', nextLlmData, undefined, { warnOnStall: true });
+                    await this.caps.hooks.run('agent:llm:before', nextLlmData, undefined, { warnOnStall: true });
                     // 裁剪消息以确保不超过上下文窗口
                     nextLlmData.messages = this.trimMessages(nextLlmData.messages, tokenBudget);
                     // 推送 token 使用量统计
@@ -707,13 +800,13 @@ class DefaultAgent {
                         maxTokens,
                         signal,
                         ...(thinkOverride !== undefined ? { think: thinkOverride } : {}),
-                    }, incoming.sessionId, incoming.platform, signal);
+                    }, incoming.sessionId, incoming.platform);
                     turnSegments.push(...nextResult.segments);
                     response = nextResult;
                     accUsage(response.usage);
                     this.debugLogResponse(response, Date.now() - tN, iterations);
                     const nextLlmAfterData = { response, messages: nextLlmData.messages };
-                    await this.ctx.runHook('agent:llm:after', nextLlmAfterData);
+                    await this.caps.hooks.run('agent:llm:after', nextLlmAfterData);
                     response = nextLlmAfterData.response;
                     if (response.reasoningContent) {
                         allReasoning.push(response.reasoningContent);
@@ -727,6 +820,8 @@ class DefaultAgent {
                 // 保留原始 LLM 输出，用于存入 memory（避免纯文本历史污染 few-shot 示例）
                 let rawLlmContent = response.content ?? '';
                 let replyContent = rawLlmContent;
+                // Hook: agent:reply:before — 插件可以修改最终回复
+                // JSON 解析/修复统一由 persona 的 agent:reply:before 钩子处理
                 const responseData = {
                     content: replyContent,
                     sessionId: incoming.sessionId,
@@ -735,16 +830,18 @@ class DefaultAgent {
                     triggerType: incoming.triggerType,
                     attempt: 0,
                 };
-                await this.ctx.runHook('agent:reply:before', responseData);
+                await this.caps.hooks.run('agent:reply:before', responseData);
                 // 重试循环：当 hook（如 persona 的 outputFormat 解析）报告 retryRequested 时，
                 // 把失败的 assistant 输出 + 系统反馈追加到消息列表，重新请求 LLM；最多按 maxRetries 次。
                 // maxRetries 由 hook 端写入（plugin-persona 从 outputFormat.retries 读取，默认 1）。
+                // 上游吐空流同样会被判不合格：此时没有可回放的失败输出，只追加系统反馈再请求一次。
                 const maxRetries = Math.max(0, responseData.maxRetries ?? 0);
                 let attempt = 0;
-                while (responseData.retryRequested && attempt < maxRetries && rawLlmContent.length > 0) {
+                while (responseData.retryRequested && attempt < maxRetries) {
                     attempt++;
                     this.logger.debug(`agent:reply:before 请求重试 (attempt=${attempt}/${maxRetries}, session=${incoming.sessionId}): ${responseData.retryFeedback ?? '(无反馈)'}`);
-                    llmBeforeData.messages.push({ role: 'assistant', content: rawLlmContent });
+                    if (rawLlmContent.length > 0)
+                        llmBeforeData.messages.push({ role: 'assistant', content: rawLlmContent });
                     llmBeforeData.messages.push({
                         role: 'system',
                         content: responseData.retryFeedback ?? '上一次回复未能通过格式校验，请严格按照系统提示中规定的格式重新输出。',
@@ -756,7 +853,7 @@ class DefaultAgent {
                         maxTokens,
                         signal,
                         ...(thinkOverride !== undefined ? { think: thinkOverride } : {}),
-                    }, incoming.sessionId, incoming.platform, signal);
+                    }, incoming.sessionId, incoming.platform);
                     turnSegments.push(...retryResult.segments);
                     response = retryResult;
                     accUsage(response.usage);
@@ -766,10 +863,11 @@ class DefaultAgent {
                     // 用新输出再次跑 hook；hook 端根据 attempt 决定继续重试或走兜底（静默丢弃）
                     responseData.content = rawLlmContent;
                     responseData.archiveContent = undefined;
+                    responseData.visibleContent = undefined;
                     responseData.retryRequested = false;
                     responseData.retryFeedback = undefined;
                     responseData.attempt = attempt;
-                    await this.ctx.runHook('agent:reply:before', responseData);
+                    await this.caps.hooks.run('agent:reply:before', responseData);
                 }
                 // 双保险：循环结束后若 hook 仍标记 retryRequested（理论上 persona 已在用尽时自动走兜底），
                 // 强制把 content 置空，避免原始未校验内容被外发。
@@ -780,6 +878,7 @@ class DefaultAgent {
                 }
                 replyContent = responseData.content;
                 const archiveContent = responseData.archiveContent ?? rawLlmContent;
+                const visibleContent = responseData.visibleContent ?? replyContent;
                 // 重复检测：如果回复与最近一条 assistant 消息完全相同，视为模型"卡壳"，静默跳过。
                 // 比的是 archiveContent（与落库同源口径）——启用 outputFormat 时历史里存的是整串 JSON，
                 // 拿解码后的纯文本去比永远不成立。
@@ -788,8 +887,12 @@ class DefaultAgent {
                     this.logger.warn(`检测到重复回复，跳过发送 (session=${incoming.sessionId})`);
                     replyContent = '';
                 }
+                // 提交点：此后的流结束标记、落库与外发成组执行。流结束后到这里之间（llm:after / 工具循环退出 /
+                // reply:before / 重试）被 latest-wins、手动停止或拆卸掐掉的回合，走下方 AbortError 收尾，不落库、不外发。
+                if (signal.aborted)
+                    throw new DOMException('Generation aborted', 'AbortError');
                 // 发出流结束标记
-                await this.ctx.emit('outbound:stream', {
+                await this.caps.events.emit('outbound:stream', {
                     sessionId: incoming.sessionId,
                     platform: incoming.platform,
                     done: true,
@@ -815,6 +918,10 @@ class DefaultAgent {
                         ...(assistantMetadata ?? {}),
                         modelInfo: turnModelInfo,
                     };
+                    // 落库的是信封（如 outputFormat 的整串 JSON）时，另带解码后的可见正文，供检索、摘要等按语义读历史的一方用
+                    if (visibleContent !== archiveContent) {
+                        finalAssistantMetadata[WellKnownMetadataKeys.VisibleContent] = visibleContent;
+                    }
                     // 保存最终 assistant 回复：优先存 persona 修复/规范化后的 JSON，保持格式完整，
                     // 避免坏 JSON 或解码后纯文本污染历史 few-shot 示例导致模型不再遵守 outputFormat
                     await this.saveToMemory(incoming.sessionId, {
@@ -838,7 +945,7 @@ class DefaultAgent {
                 }
                 // Hook: agent:turn:after — 插件可以在完整消息周期结束后做后处理
                 const turnOutcome = replyContent.trim().length === 0 ? 'silent' : 'replied';
-                await this.ctx.runHook('agent:turn:after', {
+                await this.caps.hooks.run('agent:turn:after', {
                     message: incoming,
                     reply: replyContent,
                     outcome: turnOutcome,
@@ -851,9 +958,9 @@ class DefaultAgent {
                 //
                 // 历史教训：早期版本会用 turnPersistedTimestamps 把"本轮已持久化的中间消息"全部删掉，
                 // 注释里写的是防"半截 assistant 内容 / 假回退"。但实际审计 saveToolCallGroup（见下方）发现：
-                //   1. saveToolCallGroup 只在并行工具全部执行完毕后整组写入（assistant tool_call + 所有
-                //      tool result 一次性 push），catch 路径根本进不来；turnPersistedTimestamps 里只
-                //      可能是"已完成、副作用已发生"的工具调用对。
+                //   1. saveToolCallGroup 只在并行工具全部落定后整组写入（assistant tool_call + 所有
+                //      tool result 一次性 push；单个工具的异常已在闭包内转成它自己的错误结果），不存在
+                //      写了一半的组；turnPersistedTimestamps 里只可能是"已落定、副作用已发生"的工具调用对。
                 //   2. 删除这些 = 让 agent 忘记自己刚刚做过的有副作用的事（戳一戳/发送消息/调度任务/…），
                 //      下一轮 LLM 看不到自己的行为，会重复调用，外部观察就是"agent 一直以为戳不了"。
                 //   3. 真正的 orphan 风险（assistant tool_calls 缺 tool result）由 sanitizeToolCallHistory
@@ -864,7 +971,7 @@ class DefaultAgent {
                         (turnPersistedTimestamps.length > 0
                             ? `（保留本轮已完成的 ${turnPersistedTimestamps.length} 条工具调用记录，便于下一轮 agent 感知）`
                             : ''));
-                    await this.ctx.emit('outbound:stream', {
+                    await this.caps.events.emit('outbound:stream', {
                         sessionId: incoming.sessionId,
                         platform: incoming.platform,
                         done: true,
@@ -873,7 +980,7 @@ class DefaultAgent {
                     // session-manager 把会话状态从 active 收口为 completed（否则永远停在"进行中"），
                     // checkpoint 关闭当前回合（否则中止后回合不关闭、长期泄漏）。
                     // 文档与 agent-api 早已声明 outcome 含 aborted，此处兑现契约。
-                    await this.ctx.runHook('agent:turn:after', {
+                    await this.caps.hooks.run('agent:turn:after', {
                         message: incoming,
                         reply: '',
                         outcome: 'aborted',
@@ -886,7 +993,7 @@ class DefaultAgent {
                 this.logger.error(`处理消息失败: ${message}`);
                 // 异常同样要结束流：不发 done，CLI 的流式块不收尾、WebUI 的工具进度与上限标记不复位，
                 // 下一轮 delta 还会抹掉这条 [错误] 与用户的新输入。顺序与正常收尾一致——先 done 再发消息。
-                await this.ctx.emit('outbound:stream', {
+                await this.caps.events.emit('outbound:stream', {
                     sessionId: incoming.sessionId,
                     platform: incoming.platform,
                     done: true,
@@ -900,7 +1007,7 @@ class DefaultAgent {
                 // 异常也是回合终态：同样发 turn:after(outcome=error) 让 checkpoint 关闭回合、
                 // session-manager 收口状态。dispatchOutbound 已发系统错误消息，状态可被 outbound:message
                 // 与本钩子双路径幂等收口。
-                await this.ctx.runHook('agent:turn:after', {
+                await this.caps.hooks.run('agent:turn:after', {
                     message: incoming,
                     reply: '',
                     outcome: 'error',
@@ -911,7 +1018,7 @@ class DefaultAgent {
         });
         // 消息被拦截（如流控缓冲），通知前端结束 loading
         if (!handled) {
-            await this.ctx.emit('outbound:stream', {
+            await this.caps.events.emit('outbound:stream', {
                 sessionId: incoming.sessionId,
                 platform: incoming.platform,
                 done: true,
@@ -927,7 +1034,7 @@ class DefaultAgent {
         const systemPrompt = this.buildSystemPrompt(personaOpts);
         messages.push({ role: 'system', content: systemPrompt, metadata: { injector: 'persona' } });
         // 2. 历史消息
-        const memory = this.ctx.getService('memory');
+        const memory = this.caps.memory.current;
         if (memory) {
             try {
                 const history = this.sanitizeToolCallHistory(await memory.getHistory(incoming.sessionId, this.historyLimit), incoming.sessionId);
@@ -1011,7 +1118,7 @@ class DefaultAgent {
         // 多模态：把 attachments 中的 image 项传递给 LLM（视觉模型多模态字段）
         const imageAtts = incoming.attachments?.filter(a => a.kind === 'image') ?? [];
         if (imageAtts.length > 0) {
-            if (this.ctx.getService('media') !== undefined) {
+            if (this.caps.media.current !== undefined) {
                 // media 在场：原样透传。出口形态由 media 的 agent:llm:before 中间件规范化
                 //（describe 剥离 / passthrough 物化），此处不做任何转换——它的描述缓存键与
                 // 动图提示都按 attachment.data 原串命中，改形态会打散。
@@ -1041,7 +1148,7 @@ class DefaultAgent {
         // 秒级时间戳一变，人设 + 记忆 + 历史近 7 万 token 的前缀全部作废——实测每个
         // 新回合命中率恒为 0，只有同回合内的工具迭代（prompt 不重建）才命中。
         // 放到这里语义也更顺：它们本就是「此刻的事实」，紧挨当前消息说更自然。
-        const persona = this.ctx.getService('persona');
+        const persona = this.caps.persona.current;
         const volatileCtx = persona?.getVolatilePrompt?.(personaOpts);
         if (volatileCtx) {
             messages.push({ role: 'system', content: volatileCtx, metadata: { injector: VOLATILE_INJECTOR } });
@@ -1054,11 +1161,19 @@ class DefaultAgent {
         messages.push(userMessage);
         return messages;
     }
+    /**
+     * 裁剪预算 = 上下文长度 × trimThresholdRatio − 最大输出 token − 512 安全余量（下限 1024）。
+     * trimThresholdRatio < 1 可提前触发裁剪，默认 1.0 = 用满扣除输出预留后的可用窗口。
+     * 真实回合与 token:request 快照共用，两处的预算口径因此一致。
+     */
+    computeTokenBudget(contextLength, maxTokens) {
+        return Math.max(1024, Math.floor(contextLength * this.trimThresholdRatio) - maxTokens - 512);
+    }
     /**
      * 构建系统提示词
      */
     buildSystemPrompt(personaOpts) {
-        const persona = this.ctx.getService('persona');
+        const persona = this.caps.persona.current;
         const base = persona
             ? this.systemPrompt
                 ? `${persona.getSystemPrompt(personaOpts)}\n\n${this.systemPrompt}`
@@ -1092,7 +1207,7 @@ class DefaultAgent {
         for (const msg of messages) {
             const t = estimateMsgTokens(msg);
             if (msg.role === 'system') {
-                // 贡献点物化块的 injector 是全局键 `${ctx.id}/${局部标签}`（ctx.id 含 '/'），
+                // 贡献点物化块的 injector 是全局键 `${贡献方实例 id}/${局部标签}`（实例 id 含 '/'），
                 // 归桶按局部标签（末段）匹配——桶规则与统计明细键保持迁移前的稳定值；
                 // 非贡献来源（persona / system-other 等）无 '/'，末段即原值，不受影响。
                 const rawSource = msg.metadata?.injector;
@@ -1119,14 +1234,12 @@ class DefaultAgent {
                     subtaskTokens += t;
                 }
                 else if (source === 'persona' || !source) {
-                    // persona 消息可能被 skills/subtask/toolPriority 追加了内容
+                    // persona 消息可能被 subtask 追加内容
                     if (contributions) {
                         let contributionTokens = 0;
                         for (const [key, charCount] of Object.entries(contributions)) {
                             const ct = estimateTextTokens('x'.repeat(charCount));
-                            if (key === 'skills')
-                                skillsTokens += ct;
-                            else if (key === 'subtask')
+                            if (key === 'subtask')
                                 subtaskTokens += ct;
                             else
                                 systemOtherTokens += ct;
@@ -1163,7 +1276,7 @@ class DefaultAgent {
             systemOtherTokens;
         const totalUsed = systemTokens + historyTokens + toolResultTokens + toolDefsTokens;
         const usageRatio = contextLength > 0 ? totalUsed / contextLength : 0;
-        this.ctx
+        this.caps.events
             .emit('token:usage', {
             sessionId,
             platform,
@@ -1218,9 +1331,9 @@ class DefaultAgent {
         const rel = t.match(/^data\/((?:images|videos|audios|files)\/.+)$/);
         if (!rel)
             return t;
-        const storage = this.ctx.getService('storage');
-        if (!storage)
-            return null;
+        // 经网关按 URI 路由：storage 按根逐条提供，胜者只是其中一个根（多根时通常是 workspace），
+        // 读不了 data:/。缺 data 根（含 storage 整体缺席）时网关抛错，落到下面的 catch
+        const storage = createStorageGateway(this.caps.storage);
         try {
             const raw = (await storage.readFile(`data:/${rel[1]}`));
             // mime 优先取附件自带的 mimeType；缺省按 basename 扩展名推断（适配器落盘只产
@@ -1472,11 +1585,17 @@ class DefaultAgent {
         }
         return result;
     }
-    /**
-     * 保存消息到记忆服务
-     */
+    getArchiveForWrite() {
+        const archive = this.caps.messageArchive.current;
+        if (!archive && !this.archiveUnavailableWarned) {
+            this.archiveUnavailableWarned = true;
+            this.logger.warn('message-archive 服务不可用，缺席期间的新消息不会写入记忆，对话继续。请加载 @aalis/plugin-message-archive 及其 memory 依赖。');
+        }
+        return archive;
+    }
+    /** 保存消息到记忆服务 */
     async saveToMemory(sessionId, message) {
-        const archive = this.ctx.getService('message-archive');
+        const archive = this.getArchiveForWrite();
         if (archive) {
             try {
                 await archive.saveMessage(sessionId, message);
@@ -1487,7 +1606,7 @@ class DefaultAgent {
         }
     }
     buildAssistantMetadata(incoming) {
-        const identity = getPlatformSelfIdentity(this.ctx, incoming.platform, incoming.sessionId);
+        const identity = getPlatformSelfIdentity(this.caps.platform, incoming.platform, incoming.sessionId);
         const metadata = {
             platform: incoming.platform,
             senderType: 'assistant',
@@ -1576,7 +1695,7 @@ class DefaultAgent {
         // 跳过非真实用户输入：闲聊主动触发是系统提示，不应作为 user 消息写入历史
         if (incoming.source === 'idle-trigger')
             return undefined;
-        const archive = this.ctx.getService('message-archive');
+        const archive = this.getArchiveForWrite();
         if (!archive)
             return undefined;
         try {
@@ -1595,35 +1714,27 @@ class DefaultAgent {
      * 此时该 fallback 永远不命中——出站消息总是经过 outbound:dispatch 钩子链
      * （审计 / 脱敏 / 限速 / authority 等中间件）。
      *
-     * 由于 plugin-agent-default 未在 inject.required 中声明 'gateway'，
-     * 即使 gateway 未加载本插件仍会激活，因此保留该 fallback 以便：
+     * gateway 只是本插件的 optional 依赖，它不在场时 agent 照常激活，因此保留该 fallback 以便：
      *   - 集成测试不必启动 gateway
      *   - 嵌入式 / 单 agent 部署场景
      * 生产部署务必确保 plugin-gateway 已加载，否则中间件链会被跳过。
      */
     async dispatchOutbound(message) {
-        const gateway = this.ctx.getService('gateway');
+        const gateway = this.caps.gateway.current;
         if (gateway) {
             await gateway.dispatchOutbound(message);
             return;
         }
-        this.logger.warn('Gateway 服务不可用，回退至 ctx.emit(outbound:message)（中间件链被跳过）');
-        await this.ctx.emit('outbound:message', message);
+        this.logger.warn('Gateway 服务不可用，回退至 outbound:message 事件（中间件链被跳过）');
+        await this.caps.events.emit('outbound:message', message);
     }
 }
 // ----- 插件导出 -----
-export const name = '@aalis/plugin-agent';
-export const displayName = '默认 Agent';
-export const subsystem = 'agent';
-export const provides = ['agent'];
-export const inject = {
-    optional: ['llm', 'memory', 'persona', 'message-archive', 'platform', 'media', 'storage'],
-};
-export const configSchema = {
+const configSchema = {
     defaultLLM: {
         type: 'llm-ref',
         label: '默认对话模型',
-        description: '全局默认 LLM。apply() 时调用 ctx.preferService("llm", `provider/model`) 锁定 ServiceContainer 偏好。会话 / 平台 profile 未覆盖时生效。',
+        description: '全局默认 LLM。apply() 时经 services.prefer 锁定 llm 服务的偏好提供者。会话 / 平台 profile 未覆盖时生效。',
     },
     systemPrompt: {
         type: 'textarea',
@@ -1635,7 +1746,7 @@ export const configSchema = {
         type: 'number',
         label: '长期记忆预留 Token',
         default: 4096,
-        description: '为长期记忆注入的 system 消息预留的 token 额度，截断时不会删除这些消息',
+        description: '为注入的 system 消息预留的 token 额度：超出时先按比例缩减，极端情况下（最后阶段）仍会删除',
     },
     historyLimit: {
         type: 'number',
@@ -1668,21 +1779,28 @@ export const configSchema = {
         description: '裁剪预算 = 上下文长度 × 该比例 − 最大输出 token − 512 安全余量（下限 1024）。本次调用估算输入 token 超过该预算才会对消息列表做内存裁剪（不影响 DB）。默认 1.0 表示用满扣除输出预留后的可用窗口；调低可提前裁剪。压缩触发请在“@aalis/plugin-memory-summary”中配置。',
     },
 };
-export function apply(ctx, config) {
-    const agentImpl = new DefaultAgent(ctx, config);
-    ctx.provide('agent', agentImpl);
-    // 拆卸即中止在飞回合：bounce / disable / unload / 停机都经此，理由见 abortAll。
-    ctx.onDispose(() => agentImpl.abortAll());
+function run(caps) {
+    const agentImpl = new DefaultAgent(caps);
+    caps.provide(agentService, agentImpl);
+    // 收尾段中止在飞回合并等 AbortError 落定。
+    // 第一方栈由 core 关停编排（optional 环成员先全部 drain）与 agent:turn:after 收口；
+    // session-manager 的 onDrain 兜的是未装 agent 或钩子未挂上的路径。
+    // 超时沿用 core 对 onDrain 的 disposeTimeoutMs，不另加配置键。
+    caps.lifecycle.onDrain(() => agentImpl.abortInflightAndSettle(), '中止在飞回合');
+    // 清理段再 abort 一次：drain 超时或未走到收尾时的兜底，表空则空操作。
+    caps.lifecycle.onDispose(() => agentImpl.abortAll(), '中止在飞回合（兜底）');
+    // 会话删除：丢弃该会话的 token 日志节流状态（与 todo-list / file-reader 走同一条会话清理路径）
+    caps.events.on('session:deleted', sessionId => agentImpl.dropTokenLogState(sessionId));
     const agent = agentImpl;
-    // 全局默认 LLM：通过 ServicePreference 锁定 ctx.getService<'llm'>() 的首选 entry。
-    // 偏好持久化由 core 配置层负责（servicePreferences 字段）；这里只是开机时按 agent
+    // 全局默认 LLM：通过 ServicePreference 锁定 llm 服务的首选 entry。
+    // 偏好的持久化在宿主配置文档（servicePreferences 字段，WebUI 切换时写入）；这里只是开机时按 agent
     // 自己的 cfg.defaultLLM 覆写一次，便于纯文件配置流（无 webui 干预）也能生效。
-    const defaultLLM = config.defaultLLM;
+    const defaultLLM = caps.config.defaultLLM;
     if (defaultLLM?.provider && defaultLLM?.model) {
-        ctx.preferService('llm', `${defaultLLM.provider}/${defaultLLM.model}`);
+        caps.services.prefer(llmService, `${defaultLLM.provider}/${defaultLLM.model}`);
     }
     function resolutionLines(sessionId, platform, label, pick) {
-        const smSvc = ctx.getService('session-manager');
+        const smSvc = caps.sessionManager.current;
         if (!smSvc)
             return [`${label}: (session-manager 不可用)`];
         const session = smSvc.getSession(sessionId);
@@ -1734,13 +1852,13 @@ export function apply(ctx, config) {
         }
         return lines.join('\n');
     }
-    useCommandService(ctx)
+    caps.commands
         .command('model [keyword:string]', '列出/搜索可用对话模型（分页，-p 翻页；如 /model grok）')
         .option('page', '-p <n:number>', { description: '页码（默认 1）' })
         .action(async (argv, keyword) => {
         const seen = new Set();
         const ids = [];
-        for (const e of listLLMModels(ctx, { caps: ['chat'] })) {
+        for (const e of listLLMModels(caps.llm, { caps: ['chat'] })) {
             if (seen.has(e.contextId))
                 continue;
             seen.add(e.contextId);
@@ -1749,20 +1867,20 @@ export function apply(ctx, config) {
         const page = typeof argv.options.page === 'number' ? argv.options.page : 1;
         return renderPaged(ids, String(keyword ?? ''), page, '可用模型', '/model');
     });
-    useCommandService(ctx)
+    caps.commands
         .command('persona [keyword:string]', '列出/搜索可用人设（分页，-p 翻页）')
         .option('page', '-p <n:number>', { description: '页码（默认 1）' })
         .action(async (argv, keyword) => {
-        const persona = ctx.getService('persona');
+        const persona = caps.persona.current;
         const names = persona?.listModels ? await persona.listModels() : [];
         const page = typeof argv.options.page === 'number' ? argv.options.page : 1;
         return renderPaged(names, String(keyword ?? ''), page, '可用人设', '/persona');
     });
     // ---- 会话级「模型 + 人设 + thinking + 名称」配置（onebot 等平台对话直接改当前对话生效） ----
-    useCommandService(ctx)
+    caps.commands
         .command('session', '查看当前对话生效的模型 / 人设 / thinking / 名称及来源与解析链', { risk: 'sensitive' })
         .action(async (argv) => {
-        const smSvc = ctx.getService('session-manager');
+        const smSvc = caps.sessionManager.current;
         if (!smSvc)
             return 'session-manager 服务不可用';
         const sid = argv.session.sessionId;
@@ -1780,7 +1898,7 @@ export function apply(ctx, config) {
             .filter(Boolean)
             .join('\n');
     });
-    useCommandService(ctx)
+    caps.commands
         .command('session.set', '设定当前对话的模型 / 人设 / thinking / 显示名（会话级覆盖，持久化，重启不丢）', {
         risk: 'sensitive',
         examples: [
@@ -1797,7 +1915,7 @@ export function apply(ctx, config) {
     })
         .option('name', '-n <label:string>', { description: '会话显示名（可选）' })
         .action(async (argv) => {
-        const smSvc = ctx.getService('session-manager');
+        const smSvc = caps.sessionManager.current;
         if (!smSvc)
             return 'session-manager 服务不可用';
         const modelRef = typeof argv.options.model === 'string' ? argv.options.model.trim() : '';
@@ -1819,7 +1937,7 @@ export function apply(ctx, config) {
             if (lastSlash <= 0 || lastSlash === modelRef.length - 1) {
                 return '模型格式错误。请用 `provider/model`，例如 `@aalis/plugin-llm-openai:main/gpt-4o`';
             }
-            const chatModels = listLLMModels(ctx, { caps: ['chat'] });
+            const chatModels = listLLMModels(caps.llm, { caps: ['chat'] });
             if (!chatModels.some(e => e.contextId === modelRef)) {
                 return `未知模型 "${modelRef}"。用 /model <关键词> 搜索（如 /model grok），共 ${chatModels.length} 个可用。`;
             }
@@ -1827,7 +1945,7 @@ export function apply(ctx, config) {
         }
         // 人设：listModels 可选，缺失则不校验（persona 插件缺席时不误拒）
         if (personaName) {
-            const persona = ctx.getService('persona');
+            const persona = caps.persona.current;
             if (persona?.listModels) {
                 const names = await persona.listModels();
                 if (!names.includes(personaName)) {
@@ -1853,7 +1971,7 @@ export function apply(ctx, config) {
         lines.push('后续消息持续生效（已持久化，重启不丢）。/session.reset 可复位。');
         return lines.join('\n');
     });
-    useCommandService(ctx)
+    caps.commands
         .command('session.reset', '复位当前对话的会话级覆盖（默认清模型+人设+thinking；-m/-p/-t 单独清对应项）', {
         risk: 'sensitive',
         examples: ['/session.reset', '/session.reset -m', '/session.reset -p', '/session.reset -t'],
@@ -1862,7 +1980,7 @@ export function apply(ctx, config) {
         .option('persona', '-p', { description: '仅复位人设覆盖' })
         .option('think', '-t', { description: '仅复位 thinking 覆盖' })
         .action(async (argv) => {
-        const smSvc = ctx.getService('session-manager');
+        const smSvc = caps.sessionManager.current;
         if (!smSvc)
             return 'session-manager 服务不可用';
         const mFlag = argv.options.model === true;
@@ -1894,8 +2012,7 @@ export function apply(ctx, config) {
         return `已复位 → 模型: ${eff.llm ? `${eff.llm.provider}/${eff.llm.model}` : '(默认)'}，人设: ${eff.persona ?? '(默认)'}，thinking: ${thinkStr}`;
     });
     // 监听 token:request 事件 — 客户端刷新/重连时主动请求 token 用量
-    ctx.on('token:request', async (...args) => {
-        const data = args[0];
+    caps.events.on('token:request', async (data) => {
         if (!data?.sessionId)
             return;
         // 唯一发射方是 WebUI；平台缺省按 'webui' 兜底，否则模型/会话配置解析会绕过平台 profile 层
@@ -1907,12 +2024,15 @@ export function apply(ctx, config) {
             const llm = resolved.instance;
             const contextLength = llm.contextLength;
             const maxTokens = getModelMaxOutput(llm);
-            const tokenBudget = Math.max(1024, contextLength - maxTokens - 512);
+            const tokenBudget = agent.computeTokenBudget(contextLength, maxTokens);
+            // 与真实回合同一份会话解析：人设覆盖、结构化输出开关、额外提示都影响系统提示长度
+            const sm = caps.sessionManager.current;
+            const sessionResolved = sm ? sm.resolveConfig(data.sessionId, platform) : undefined;
             // 获取历史消息并构建基础消息列表
-            const memory = ctx.getService('memory');
+            const memory = caps.memory.current;
             const messages = [];
             // 系统提示
-            const systemPrompt = agent.buildSystemPrompt();
+            const systemPrompt = agent.buildSystemPrompt(toPersonaOptions(sessionResolved));
             messages.push({ role: 'system', content: systemPrompt, metadata: { injector: 'persona' } });
             // 历史消息
             if (memory) {
@@ -1921,11 +2041,8 @@ export function apply(ctx, config) {
             }
             // 与真实回合同序：先组装 agent:prompt 贡献（摘要/向量记忆/档案等物化为 system 块），
             // 再跑 agent:llm:before（工具搜索层过滤等拦截职责），使快照贴近实际送入 LLM 的形态
-            const sm = ctx.getService('session-manager');
-            const sessionResolved = sm ? sm.resolveConfig(data.sessionId, platform) : undefined;
             const enabledGroups = sessionResolved?.enabledToolGroups?.length ? sessionResolved.enabledToolGroups : undefined;
-            const tools = ctx.getService('tools')?.getDefinitions(enabledGroups ? { groups: enabledGroups } : undefined) ??
-                [];
+            const tools = caps.tools.current?.getDefinitions(enabledGroups ? { groups: enabledGroups } : undefined) ?? [];
             const llmBeforeData = {
                 messages,
                 tools,
@@ -1934,13 +2051,22 @@ export function apply(ctx, config) {
                 platform,
                 dryRun: true, // 纯统计路径:昂贵注入者(向量检索/档案加载)据此跳过副作用
             };
-            await assemblePromptContributions(ctx, llmBeforeData, { buildTimeoutMs: agent.promptBuildTimeoutMs });
-            await ctx.runHook('agent:llm:before', llmBeforeData, undefined, { warnOnStall: true });
+            await assemblePromptContributions(caps, llmBeforeData, { buildTimeoutMs: agent.promptBuildTimeoutMs });
+            await caps.hooks.run('agent:llm:before', llmBeforeData, undefined, { warnOnStall: true });
             agent.emitTokenUsage(data.sessionId, platform, llmBeforeData.messages, llmBeforeData.tools, contextLength, maxTokens, tokenBudget);
         }
         catch (err) {
-            ctx.logger.debug('token:request 处理失败:', err);
+            caps.logger.debug('token:request 处理失败:', err);
         }
     });
 }
+export default definePlugin({
+    name: '@aalis/plugin-agent',
+    displayName: '默认 Agent',
+    subsystem: 'agent',
+    configSchema,
+    provides: [agentService],
+    uses,
+    apply: run,
+});
 //# sourceMappingURL=index.js.map