@aalis/plugin-agent 0.13.5 → 0.14.0

package/dist/index.js

@@ -1,12 +1,48 @@
 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 { agent as agentService, } from '@aalis/api-agent';
+import { commands as commandsService } from '@aalis/api-commands';
+import { gateway as gatewayService } from '@aalis/api-gateway';
+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 { storage as storageService } from '@aalis/api-storage';
+import { asToolExecutionResult, tools as toolsService, } from '@aalis/api-tools';
+import { config as configCap, contributions, definePlugin, events, hooks, lifecycle, logger as loggerCap, optional, pluginsService, provide, services, } from '@aalis/core';
 import { CONTROL_KINDS, getMessageName, getSenderLabel, WellKnownKinds } 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 { 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 +62,7 @@ function getModelMaxOutput(llm) {
     return llm.maxOutputTokens ?? DEFAULT_MAX_OUTPUT_TOKENS;
 }
 class DefaultAgent {
-    ctx;
+    caps;
     logger;
     systemPrompt;
     memoryTokenBudget;
@@ -45,8 +81,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 三个阈值必输出
@@ -56,9 +99,10 @@ class DefaultAgent {
     tokenLogState = new Map();
     /** 已注册的预处理器（name → { priority, 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 +126,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 +173,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;
@@ -145,8 +189,15 @@ class DefaultAgent {
             this.logger.info(`拆卸：已中止 ${n} 个在飞回合`);
     }
     /**
-     * 注册消息预处理器
-     *
+     * 关停收尾：中止在飞回合并等待其 AbortError（或正常完成）收尾落定。
+     * 超时由 core 对 onDrain 回调的 disposeTimeoutMs 护栏负责，不另加配置键。
+     */
+    async abortInflightAndSettle() {
+        this.abortAll();
+        if (this.inflightTurns.size === 0)
+            return;
+        await Promise.allSettled([...this.inflightTurns]);
+    }
     /**
      * 注册输入预处理器（如图片识别、文件读取、用户画像等）。
      * 多个预处理器按注册顺序串行执行（Koa-style 洋葱模型）。
@@ -156,22 +207,24 @@ class DefaultAgent {
      */
     registerPreprocessor(name, handler) {
         // 同名替换
-        const existing = this.preprocessors.get(name);
-        if (existing)
-            existing.dispose();
-        const dispose = this.ctx.middleware('agent:input:before', async (data, next) => {
+        this.preprocessors.get(name)?.dispose();
+        const dispose = this.caps.hooks.middleware('agent:input:before', async (data, next) => {
             await handler(data.message, next);
         });
-        const cleanup = () => {
-            dispose();
-            this.preprocessors.delete(name);
-            this.logger.info(`预处理器已注销: ${name}`);
+        // 退订按条目引用比对：同名重注册后，旧退订闭包只摘自己的中间件，不动新登记的账目
+        const entry = {
+            dispose: () => {
+                dispose();
+                if (this.preprocessors.get(name) !== entry)
+                    return;
+                this.preprocessors.delete(name);
+                this.logger.info(`预处理器已注销: ${name}`);
+            },
         };
-        this.preprocessors.set(name, { dispose: cleanup });
+        this.preprocessors.set(name, entry);
         this.logger.info(`预处理器已注册: ${name}`);
-        return cleanup;
+        return entry.dispose;
     }
-    /**
     /**
      * 获取当前所有已注册预处理器的元信息（按注册顺序返回）
      */
@@ -185,7 +238,7 @@ class DefaultAgent {
      * （平台属于独立子系统，由 api-platform 的 helper 负责）。
      */
     getPluginGroups() {
-        const pm = this.ctx.getService('plugins');
+        const pm = this.caps.plugins.current;
         if (!pm)
             return [];
         // 子系统归属：Agent 域的服务（不含 platform——平台是独立子系统）
@@ -227,7 +280,7 @@ class DefaultAgent {
             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,
@@ -236,14 +289,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,
@@ -261,7 +314,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);
         }
@@ -384,14 +437,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) {
@@ -402,7 +464,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() → 此处永远不执行 → 消息被拦截
@@ -435,7 +497,7 @@ class DefaultAgent {
             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;
@@ -462,9 +524,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 保持**会话/物理**语义（定时任务归属、平台档继承、记忆平台域、
@@ -494,11 +554,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 使用量统计
@@ -541,7 +601,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 = [];
@@ -601,9 +661,9 @@ 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.caps.hooks.run('agent:tool:before', toolBeforeData);
                         // 通知平台：工具开始执行
-                        await this.ctx.emit('tool:execute', {
+                        await this.caps.events.emit('tool:execute', {
                             sessionId: incoming.sessionId,
                             platform: incoming.platform,
                             toolName: toolBeforeData.name,
@@ -612,9 +672,7 @@ class DefaultAgent {
                         });
                         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) ??
+                        const executed = asToolExecutionResult(await (this.caps.tools.current?.execute(toolBeforeData.name, toolBeforeData.args, toolCtx) ??
                             Promise.resolve({ content: JSON.stringify({ error: 'tools 服务不可用' }) })));
                         let result = executed.content;
                         // 工具交给主模型看的图：只随本回合的 tool 消息走（出口由 prepareLLMMessages 编码），
@@ -622,7 +680,7 @@ class DefaultAgent {
                         const resultImages = executed.images;
                         // Hook: agent:tool:after — 插件可以处理工具执行结果
                         const toolAfterData = { name: toolBeforeData.name, result, toolCallContext: toolCtx };
-                        await this.ctx.runHook('agent:tool:after', toolAfterData);
+                        await this.caps.hooks.run('agent:tool:after', toolAfterData);
                         result = toolAfterData.result;
                         // 工具结果截断：按上下文窗口比例限制单条工具结果长度
                         if (result.length > toolResultMaxChars) {
@@ -632,7 +690,7 @@ class DefaultAgent {
                         const toolEndTime = Date.now();
                         this.logger.debug(`工具完成: ${toolBeforeData.name} (${toolEndTime - toolT0}ms) 结果=${result}`);
                         // 通知平台：工具执行完成
-                        await this.ctx.emit('tool:execute', {
+                        await this.caps.events.emit('tool:execute', {
                             sessionId: incoming.sessionId,
                             platform: incoming.platform,
                             toolName: toolBeforeData.name,
@@ -692,11 +750,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 使用量统计
@@ -714,7 +772,7 @@ class DefaultAgent {
                     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);
@@ -736,7 +794,7 @@ 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）。
@@ -770,7 +828,7 @@ class DefaultAgent {
                     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 置空，避免原始未校验内容被外发。
@@ -790,7 +848,7 @@ class DefaultAgent {
                     replyContent = '';
                 }
                 // 发出流结束标记
-                await this.ctx.emit('outbound:stream', {
+                await this.caps.events.emit('outbound:stream', {
                     sessionId: incoming.sessionId,
                     platform: incoming.platform,
                     done: true,
@@ -839,7 +897,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,
@@ -865,7 +923,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,
@@ -874,7 +932,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',
@@ -887,7 +945,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,
@@ -901,7 +959,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',
@@ -912,7 +970,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,
@@ -928,7 +986,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);
@@ -1012,7 +1070,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 原串命中，改形态会打散。
@@ -1042,7 +1100,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 } });
@@ -1059,7 +1117,7 @@ class DefaultAgent {
      * 构建系统提示词
      */
     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}`
@@ -1093,7 +1151,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;
@@ -1164,7 +1222,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,
@@ -1219,7 +1277,7 @@ class DefaultAgent {
         const rel = t.match(/^data\/((?:images|videos|audios|files)\/.+)$/);
         if (!rel)
             return t;
-        const storage = this.ctx.getService('storage');
+        const storage = this.caps.storage.current;
         if (!storage)
             return null;
         try {
@@ -1473,11 +1531,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);
@@ -1488,7 +1552,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',
@@ -1577,7 +1641,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 {
@@ -1596,35 +1660,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',
@@ -1669,21 +1725,26 @@ 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(), '中止在飞回合（兜底）');
     const agent = agentImpl;
-    // 全局默认 LLM：通过 ServicePreference 锁定 ctx.getService<'llm'>() 的首选 entry。
+    // 全局默认 LLM：通过 ServicePreference 锁定 llm 服务的首选 entry。
     // 偏好持久化由 core 配置层负责（servicePreferences 字段）；这里只是开机时按 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);
@@ -1735,13 +1796,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);
@@ -1750,20 +1811,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;
@@ -1781,7 +1842,7 @@ export function apply(ctx, config) {
             .filter(Boolean)
             .join('\n');
     });
-    useCommandService(ctx)
+    caps.commands
         .command('session.set', '设定当前对话的模型 / 人设 / thinking / 显示名（会话级覆盖，持久化，重启不丢）', {
         risk: 'sensitive',
         examples: [
@@ -1798,7 +1859,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() : '';
@@ -1820,7 +1881,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} 个可用。`;
             }
@@ -1828,7 +1889,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)) {
@@ -1854,7 +1915,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'],
@@ -1863,7 +1924,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;
@@ -1895,8 +1956,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 层
@@ -1910,7 +1970,7 @@ export function apply(ctx, config) {
             const maxTokens = getModelMaxOutput(llm);
             const tokenBudget = Math.max(1024, contextLength - maxTokens - 512);
             // 获取历史消息并构建基础消息列表
-            const memory = ctx.getService('memory');
+            const memory = caps.memory.current;
             const messages = [];
             // 系统提示
             const systemPrompt = agent.buildSystemPrompt();
@@ -1922,11 +1982,10 @@ export function apply(ctx, config) {
             }
             // 与真实回合同序：先组装 agent:prompt 贡献（摘要/向量记忆/档案等物化为 system 块），
             // 再跑 agent:llm:before（工具搜索层过滤等拦截职责），使快照贴近实际送入 LLM 的形态
-            const sm = ctx.getService('session-manager');
+            const sm = caps.sessionManager.current;
             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,
@@ -1935,13 +1994,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