@zhin.js/core 1.0.26 → 1.0.28

package/lib/ai/compaction.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Session Compaction — 会话压缩
+ *
+ * 借鉴 OpenClaw 的 compaction 设计，当对话历史超过上下文窗口限制时，
+ * 通过 LLM 生成摘要来压缩早期消息，保留最近的消息完整性。
+ *
+ * 核心理念：
+ *   1. Token 估算：用 chars/4 粗略估算 token 数
+ *   2. 分块（Chunk）：按 token 预算将消息分成多块
+ *   3. 渐进式摘要：对每块分别生成摘要，再合并
+ *   4. 安全裕度：估算偏低时留 20% buffer
+ *   5. 降级策略：摘要失败时使用更粗糙的摘要
+ */
+import type { AIProvider, ChatMessage } from './types.js';
+/** 默认上下文窗口大小（tokens） */
+export declare const DEFAULT_CONTEXT_TOKENS = 128000;
+/** 上下文窗口最低阈值 */
+export declare const CONTEXT_WINDOW_HARD_MIN_TOKENS = 16000;
+/** 上下文窗口警告阈值 */
+export declare const CONTEXT_WINDOW_WARN_BELOW_TOKENS = 32000;
+/** 基础分块比例 — 每块最多占上下文的 40% */
+export declare const BASE_CHUNK_RATIO = 0.4;
+/** 最小分块比例 */
+export declare const MIN_CHUNK_RATIO = 0.15;
+/** 安全裕度系数 — 20% buffer 补偿 estimateTokens 的低估 */
+export declare const SAFETY_MARGIN = 1.2;
+/**
+ * 估算单条消息的 token 数
+ * 使用 chars/4 粗略估算（对中文偏高，对英文偏低，但足够用于分块）
+ */
+export declare function estimateTokens(message: ChatMessage): number;
+/**
+ * 估算消息列表的总 token 数
+ */
+export declare function estimateMessagesTokens(messages: ChatMessage[]): number;
+/**
+ * 按 token 份额拆分消息
+ */
+export declare function splitMessagesByTokenShare(messages: ChatMessage[], parts?: number): ChatMessage[][];
+/**
+ * 按最大 token 数拆分消息
+ */
+export declare function chunkMessagesByMaxTokens(messages: ChatMessage[], maxTokens: number): ChatMessage[][];
+/**
+ * 计算自适应分块比例
+ * 消息越大，分块比例越小，避免超出模型限制
+ */
+export declare function computeAdaptiveChunkRatio(messages: ChatMessage[], contextWindow: number): number;
+export type ContextWindowSource = 'config' | 'model' | 'default';
+export interface ContextWindowInfo {
+    tokens: number;
+    source: ContextWindowSource;
+}
+export interface ContextWindowGuardResult extends ContextWindowInfo {
+    shouldWarn: boolean;
+    shouldBlock: boolean;
+}
+/**
+ * 解析上下文窗口大小
+ */
+export declare function resolveContextWindowTokens(configTokens?: number, modelContextWindow?: number): ContextWindowInfo;
+/**
+ * 评估上下文窗口安全性
+ */
+export declare function evaluateContextWindowGuard(info: ContextWindowInfo): ContextWindowGuardResult;
+/**
+ * 带降级的摘要生成
+ *
+ * 完整摘要失败时，尝试排除超大消息再摘要
+ */
+export declare function summarizeWithFallback(params: {
+    provider: AIProvider;
+    messages: ChatMessage[];
+    maxChunkTokens: number;
+    contextWindow: number;
+    previousSummary?: string;
+    customInstructions?: string;
+}): Promise<string>;
+/**
+ * 分阶段摘要 — 先将消息拆为多段分别摘要，再合并
+ */
+export declare function summarizeInStages(params: {
+    provider: AIProvider;
+    messages: ChatMessage[];
+    maxChunkTokens: number;
+    contextWindow: number;
+    previousSummary?: string;
+    customInstructions?: string;
+    parts?: number;
+}): Promise<string>;
+export interface PruneResult {
+    /** 保留的消息 */
+    messages: ChatMessage[];
+    /** 被丢弃的消息 */
+    droppedMessages: ChatMessage[];
+    /** 丢弃的块数 */
+    droppedChunks: number;
+    /** 丢弃的消息数 */
+    droppedCount: number;
+    /** 丢弃的 token 数 */
+    droppedTokens: number;
+    /** 保留的 token 数 */
+    keptTokens: number;
+    /** 预算 token 数 */
+    budgetTokens: number;
+}
+/**
+ * 剪裁历史消息，使其不超过上下文预算
+ *
+ * 策略：从最旧的消息开始丢弃，直到 token 总量在预算内
+ */
+export declare function pruneHistoryForContext(params: {
+    messages: ChatMessage[];
+    maxContextTokens: number;
+    maxHistoryShare?: number;
+    parts?: number;
+}): PruneResult;
+/**
+ * 对给定消息列表执行一次就地压缩，返回压缩后的摘要和保留消息
+ */
+export declare function compactSession(params: {
+    provider: AIProvider;
+    messages: ChatMessage[];
+    contextWindow?: number;
+    keepRecentCount?: number;
+}): Promise<{
+    summary: string;
+    keptMessages: ChatMessage[];
+    compactedCount: number;
+    savedTokens: number;
+}>;
+//# sourceMappingURL=compaction.d.ts.map

package/lib/ai/compaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compaction.d.ts","sourceRoot":"","sources":["../../src/ai/compaction.ts"],"names":[],"mappings":"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"}

package/lib/ai/compaction.js

@@ -0,0 +1,370 @@
+/**
+ * Session Compaction — 会话压缩
+ *
+ * 借鉴 OpenClaw 的 compaction 设计，当对话历史超过上下文窗口限制时，
+ * 通过 LLM 生成摘要来压缩早期消息，保留最近的消息完整性。
+ *
+ * 核心理念：
+ *   1. Token 估算：用 chars/4 粗略估算 token 数
+ *   2. 分块（Chunk）：按 token 预算将消息分成多块
+ *   3. 渐进式摘要：对每块分别生成摘要，再合并
+ *   4. 安全裕度：估算偏低时留 20% buffer
+ *   5. 降级策略：摘要失败时使用更粗糙的摘要
+ */
+import { Logger } from '@zhin.js/logger';
+const logger = new Logger(null, 'Compaction');
+// ============================================================================
+// 常量
+// ============================================================================
+/** 默认上下文窗口大小（tokens） */
+export const DEFAULT_CONTEXT_TOKENS = 128_000;
+/** 上下文窗口最低阈值 */
+export const CONTEXT_WINDOW_HARD_MIN_TOKENS = 16_000;
+/** 上下文窗口警告阈值 */
+export const CONTEXT_WINDOW_WARN_BELOW_TOKENS = 32_000;
+/** 基础分块比例 — 每块最多占上下文的 40% */
+export const BASE_CHUNK_RATIO = 0.4;
+/** 最小分块比例 */
+export const MIN_CHUNK_RATIO = 0.15;
+/** 安全裕度系数 — 20% buffer 补偿 estimateTokens 的低估 */
+export const SAFETY_MARGIN = 1.2;
+/** 默认摘要回退文本 */
+const DEFAULT_SUMMARY_FALLBACK = '无历史记录。';
+/** 摘要合并指令 */
+const MERGE_SUMMARIES_INSTRUCTIONS = '将下面这些部分摘要合并为一份连贯的完整摘要。保留关键决定、TODO、未解决的问题和所有约束。';
+// ============================================================================
+// Token 估算
+// ============================================================================
+/**
+ * 估算单条消息的 token 数
+ * 使用 chars/4 粗略估算（对中文偏高，对英文偏低，但足够用于分块）
+ */
+export function estimateTokens(message) {
+    const content = typeof message.content === 'string'
+        ? message.content
+        : JSON.stringify(message.content);
+    // 消息角色和格式开销约 4 tokens
+    return Math.ceil(content.length / 4) + 4;
+}
+/**
+ * 估算消息列表的总 token 数
+ */
+export function estimateMessagesTokens(messages) {
+    return messages.reduce((sum, m) => sum + estimateTokens(m), 0);
+}
+// ============================================================================
+// 分块
+// ============================================================================
+/**
+ * 按 token 份额拆分消息
+ */
+export function splitMessagesByTokenShare(messages, parts = 2) {
+    if (messages.length === 0)
+        return [];
+    const normalizedParts = Math.min(Math.max(1, Math.floor(parts)), messages.length);
+    if (normalizedParts <= 1)
+        return [messages];
+    const totalTokens = estimateMessagesTokens(messages);
+    const targetTokens = totalTokens / normalizedParts;
+    const chunks = [];
+    let current = [];
+    let currentTokens = 0;
+    for (const message of messages) {
+        const msgTokens = estimateTokens(message);
+        if (chunks.length < normalizedParts - 1 &&
+            current.length > 0 &&
+            currentTokens + msgTokens > targetTokens) {
+            chunks.push(current);
+            current = [];
+            currentTokens = 0;
+        }
+        current.push(message);
+        currentTokens += msgTokens;
+    }
+    if (current.length > 0)
+        chunks.push(current);
+    return chunks;
+}
+/**
+ * 按最大 token 数拆分消息
+ */
+export function chunkMessagesByMaxTokens(messages, maxTokens) {
+    if (messages.length === 0)
+        return [];
+    const effectiveMax = Math.max(1, Math.floor(maxTokens / SAFETY_MARGIN));
+    const chunks = [];
+    let currentChunk = [];
+    let currentTokens = 0;
+    for (const message of messages) {
+        const msgTokens = estimateTokens(message);
+        if (currentChunk.length > 0 && currentTokens + msgTokens > effectiveMax) {
+            chunks.push(currentChunk);
+            currentChunk = [];
+            currentTokens = 0;
+        }
+        currentChunk.push(message);
+        currentTokens += msgTokens;
+        // 超大单条消息也要拆
+        if (msgTokens > effectiveMax) {
+            chunks.push(currentChunk);
+            currentChunk = [];
+            currentTokens = 0;
+        }
+    }
+    if (currentChunk.length > 0)
+        chunks.push(currentChunk);
+    return chunks;
+}
+/**
+ * 计算自适应分块比例
+ * 消息越大，分块比例越小，避免超出模型限制
+ */
+export function computeAdaptiveChunkRatio(messages, contextWindow) {
+    if (messages.length === 0)
+        return BASE_CHUNK_RATIO;
+    const totalTokens = estimateMessagesTokens(messages);
+    const avgTokens = totalTokens / messages.length;
+    const safeAvgTokens = avgTokens * SAFETY_MARGIN;
+    const avgRatio = safeAvgTokens / contextWindow;
+    if (avgRatio > 0.1) {
+        const reduction = Math.min(avgRatio * 2, BASE_CHUNK_RATIO - MIN_CHUNK_RATIO);
+        return Math.max(MIN_CHUNK_RATIO, BASE_CHUNK_RATIO - reduction);
+    }
+    return BASE_CHUNK_RATIO;
+}
+/**
+ * 解析上下文窗口大小
+ */
+export function resolveContextWindowTokens(configTokens, modelContextWindow) {
+    if (configTokens && configTokens > 0) {
+        return { tokens: Math.floor(configTokens), source: 'config' };
+    }
+    if (modelContextWindow && modelContextWindow > 0) {
+        return { tokens: Math.floor(modelContextWindow), source: 'model' };
+    }
+    return { tokens: DEFAULT_CONTEXT_TOKENS, source: 'default' };
+}
+/**
+ * 评估上下文窗口安全性
+ */
+export function evaluateContextWindowGuard(info) {
+    const tokens = Math.max(0, Math.floor(info.tokens));
+    return {
+        ...info,
+        tokens,
+        shouldWarn: tokens > 0 && tokens < CONTEXT_WINDOW_WARN_BELOW_TOKENS,
+        shouldBlock: tokens > 0 && tokens < CONTEXT_WINDOW_HARD_MIN_TOKENS,
+    };
+}
+// ============================================================================
+// 摘要生成
+// ============================================================================
+/**
+ * 通过 LLM 对消息进行摘要
+ */
+async function generateSummary(provider, messages, maxChunkTokens, previousSummary, customInstructions) {
+    const conversation = messages.map(m => {
+        const role = m.role === 'user' ? '用户' : m.role === 'assistant' ? '助手' : '系统';
+        const content = typeof m.content === 'string' ? m.content : JSON.stringify(m.content);
+        return `[${role}] ${content}`;
+    }).join('\n');
+    let systemPrompt = `你是一个对话摘要助手。请将以下对话压缩为简洁的摘要，保留：
+- 关键决定和结论
+- 未完成的 TODO 和待解决的问题
+- 重要的用户偏好和约束
+- 讨论的核心主题
+
+摘要应该简洁但信息量大，便于后续对话能快速了解上下文。`;
+    if (customInstructions) {
+        systemPrompt += `\n\n额外要求：${customInstructions}`;
+    }
+    let userContent = '';
+    if (previousSummary) {
+        userContent += `之前的摘要：\n${previousSummary}\n\n`;
+    }
+    userContent += `新的对话内容：\n${conversation}\n\n请生成更新后的完整摘要。`;
+    try {
+        const response = await provider.chat({
+            model: provider.models[0],
+            messages: [
+                { role: 'system', content: systemPrompt },
+                { role: 'user', content: userContent },
+            ],
+        });
+        const result = response.choices?.[0]?.message?.content;
+        return typeof result === 'string' ? result : DEFAULT_SUMMARY_FALLBACK;
+    }
+    catch (e) {
+        logger.warn(`摘要生成失败: ${e.message}`);
+        return DEFAULT_SUMMARY_FALLBACK;
+    }
+}
+/**
+ * 对消息分块摘要，支持降级
+ */
+async function summarizeChunks(params) {
+    if (params.messages.length === 0) {
+        return params.previousSummary ?? DEFAULT_SUMMARY_FALLBACK;
+    }
+    const chunks = chunkMessagesByMaxTokens(params.messages, params.maxChunkTokens);
+    let summary = params.previousSummary;
+    for (const chunk of chunks) {
+        summary = await generateSummary(params.provider, chunk, params.maxChunkTokens, summary, params.customInstructions);
+    }
+    return summary ?? DEFAULT_SUMMARY_FALLBACK;
+}
+/**
+ * 带降级的摘要生成
+ *
+ * 完整摘要失败时，尝试排除超大消息再摘要
+ */
+export async function summarizeWithFallback(params) {
+    if (params.messages.length === 0) {
+        return params.previousSummary ?? DEFAULT_SUMMARY_FALLBACK;
+    }
+    // 尝试完整摘要
+    try {
+        return await summarizeChunks(params);
+    }
+    catch (fullError) {
+        logger.warn(`完整摘要失败，尝试部分摘要: ${fullError.message}`);
+    }
+    // 降级：排除超大消息
+    const smallMessages = [];
+    const oversizedNotes = [];
+    for (const msg of params.messages) {
+        const tokens = estimateTokens(msg) * SAFETY_MARGIN;
+        if (tokens > params.contextWindow * 0.5) {
+            oversizedNotes.push(`[大型 ${msg.role} 消息 (~${Math.round(tokens / 1000)}K tokens) 已从摘要中省略]`);
+        }
+        else {
+            smallMessages.push(msg);
+        }
+    }
+    if (smallMessages.length > 0) {
+        try {
+            const partial = await summarizeChunks({ ...params, messages: smallMessages });
+            const notes = oversizedNotes.length > 0 ? `\n\n${oversizedNotes.join('\n')}` : '';
+            return partial + notes;
+        }
+        catch (partialError) {
+            logger.warn(`部分摘要也失败: ${partialError.message}`);
+        }
+    }
+    // 最终降级
+    return `上下文包含 ${params.messages.length} 条消息（${oversizedNotes.length} 条超大）。由于大小限制，摘要不可用。`;
+}
+/**
+ * 分阶段摘要 — 先将消息拆为多段分别摘要，再合并
+ */
+export async function summarizeInStages(params) {
+    const { messages } = params;
+    if (messages.length === 0) {
+        return params.previousSummary ?? DEFAULT_SUMMARY_FALLBACK;
+    }
+    const parts = Math.min(Math.max(1, params.parts ?? 2), messages.length);
+    const totalTokens = estimateMessagesTokens(messages);
+    // 消息太少，或 token 没超限，直接走单次摘要
+    if (parts <= 1 || messages.length < 4 || totalTokens <= params.maxChunkTokens) {
+        return summarizeWithFallback(params);
+    }
+    const splits = splitMessagesByTokenShare(messages, parts).filter(c => c.length > 0);
+    if (splits.length <= 1)
+        return summarizeWithFallback(params);
+    // 每段分别摘要
+    const partialSummaries = [];
+    for (const chunk of splits) {
+        partialSummaries.push(await summarizeWithFallback({
+            ...params,
+            messages: chunk,
+            previousSummary: undefined,
+        }));
+    }
+    if (partialSummaries.length === 1)
+        return partialSummaries[0];
+    // 合并多段摘要
+    const summaryMessages = partialSummaries.map(s => ({
+        role: 'user',
+        content: s,
+    }));
+    const mergeInstructions = params.customInstructions
+        ? `${MERGE_SUMMARIES_INSTRUCTIONS}\n\n额外要求：${params.customInstructions}`
+        : MERGE_SUMMARIES_INSTRUCTIONS;
+    return summarizeWithFallback({
+        ...params,
+        messages: summaryMessages,
+        customInstructions: mergeInstructions,
+    });
+}
+/**
+ * 剪裁历史消息，使其不超过上下文预算
+ *
+ * 策略：从最旧的消息开始丢弃，直到 token 总量在预算内
+ */
+export function pruneHistoryForContext(params) {
+    const maxHistoryShare = params.maxHistoryShare ?? 0.5;
+    const budgetTokens = Math.max(1, Math.floor(params.maxContextTokens * maxHistoryShare));
+    let keptMessages = params.messages;
+    const allDropped = [];
+    let droppedChunks = 0;
+    let droppedCount = 0;
+    let droppedTokens = 0;
+    const parts = Math.min(Math.max(1, params.parts ?? 2), keptMessages.length);
+    while (keptMessages.length > 0 && estimateMessagesTokens(keptMessages) > budgetTokens) {
+        const chunks = splitMessagesByTokenShare(keptMessages, parts);
+        if (chunks.length <= 1)
+            break;
+        const [dropped, ...rest] = chunks;
+        keptMessages = rest.flat();
+        droppedChunks += 1;
+        droppedCount += dropped.length;
+        droppedTokens += estimateMessagesTokens(dropped);
+        allDropped.push(...dropped);
+    }
+    return {
+        messages: keptMessages,
+        droppedMessages: allDropped,
+        droppedChunks,
+        droppedCount,
+        droppedTokens,
+        keptTokens: estimateMessagesTokens(keptMessages),
+        budgetTokens,
+    };
+}
+// ============================================================================
+// /compact 命令 — 主动压缩当前会话
+// ============================================================================
+/**
+ * 对给定消息列表执行一次就地压缩，返回压缩后的摘要和保留消息
+ */
+export async function compactSession(params) {
+    const contextWindow = params.contextWindow ?? DEFAULT_CONTEXT_TOKENS;
+    const keepRecentCount = params.keepRecentCount ?? 6;
+    const messages = params.messages;
+    if (messages.length <= keepRecentCount) {
+        return {
+            summary: '',
+            keptMessages: messages,
+            compactedCount: 0,
+            savedTokens: 0,
+        };
+    }
+    // 保留最近 N 条，其余摘要
+    const toCompact = messages.slice(0, messages.length - keepRecentCount);
+    const toKeep = messages.slice(messages.length - keepRecentCount);
+    const beforeTokens = estimateMessagesTokens(toCompact);
+    const maxChunkTokens = Math.floor(contextWindow * computeAdaptiveChunkRatio(toCompact, contextWindow));
+    const summary = await summarizeInStages({
+        provider: params.provider,
+        messages: toCompact,
+        maxChunkTokens,
+        contextWindow,
+    });
+    return {
+        summary,
+        keptMessages: toKeep,
+        compactedCount: toCompact.length,
+        savedTokens: beforeTokens - estimateTokens({ role: 'system', content: summary }),
+    };
+}
+//# sourceMappingURL=compaction.js.map

package/lib/ai/compaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compaction.js","sourceRoot":"","sources":["../../src/ai/compaction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAGzC,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;AAE9C,+EAA+E;AAC/E,KAAK;AACL,+EAA+E;AAE/E,wBAAwB;AACxB,MAAM,CAAC,MAAM,sBAAsB,GAAG,OAAO,CAAC;AAE9C,gBAAgB;AAChB,MAAM,CAAC,MAAM,8BAA8B,GAAG,MAAM,CAAC;AAErD,gBAAgB;AAChB,MAAM,CAAC,MAAM,gCAAgC,GAAG,MAAM,CAAC;AAEvD,6BAA6B;AAC7B,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAEpC,aAAa;AACb,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CAAC;AAEpC,gDAAgD;AAChD,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,CAAC;AAEjC,eAAe;AACf,MAAM,wBAAwB,GAAG,QAAQ,CAAC;AAE1C,aAAa;AACb,MAAM,4BAA4B,GAChC,gDAAgD,CAAC;AAEnD,+EAA+E;AAC/E,WAAW;AACX,+EAA+E;AAE/E;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,OAAoB;IACjD,MAAM,OAAO,GAAG,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ;QACjD,CAAC,CAAC,OAAO,CAAC,OAAO;QACjB,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACpC,sBAAsB;IACtB,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;AAC3C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB,CAAC,QAAuB;IAC5D,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,cAAc,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACjE,CAAC;AAED,+EAA+E;AAC/E,KAAK;AACL,+EAA+E;AAE/E;;GAEG;AACH,MAAM,UAAU,yBAAyB,CACvC,QAAuB,EACvB,KAAK,GAAG,CAAC;IAET,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACrC,MAAM,eAAe,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAClF,IAAI,eAAe,IAAI,CAAC;QAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IAE5C,MAAM,WAAW,GAAG,sBAAsB,CAAC,QAAQ,CAAC,CAAC;IACrD,MAAM,YAAY,GAAG,WAAW,GAAG,eAAe,CAAC;IACnD,MAAM,MAAM,GAAoB,EAAE,CAAC;IACnC,IAAI,OAAO,GAAkB,EAAE,CAAC;IAChC,IAAI,aAAa,GAAG,CAAC,CAAC;IAEtB,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,SAAS,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;QAC1C,IACE,MAAM,CAAC,MAAM,GAAG,eAAe,GAAG,CAAC;YACnC,OAAO,CAAC,MAAM,GAAG,CAAC;YAClB,aAAa,GAAG,SAAS,GAAG,YAAY,EACxC,CAAC;YACD,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACrB,OAAO,GAAG,EAAE,CAAC;YACb,aAAa,GAAG,CAAC,CAAC;QACpB,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACtB,aAAa,IAAI,SAAS,CAAC;IAC7B,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC7C,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,wBAAwB,CACtC,QAAuB,EACvB,SAAiB;IAEjB,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAErC,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,aAAa,CAAC,CAAC,CAAC;IACxE,MAAM,MAAM,GAAoB,EAAE,CAAC;IACnC,IAAI,YAAY,GAAkB,EAAE,CAAC;IACrC,IAAI,aAAa,GAAG,CAAC,CAAC;IAEtB,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,SAAS,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;QAC1C,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,IAAI,aAAa,GAAG,SAAS,GAAG,YAAY,EAAE,CAAC;YACxE,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YAC1B,YAAY,GAAG,EAAE,CAAC;YAClB,aAAa,GAAG,CAAC,CAAC;QACpB,CAAC;QACD,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC3B,aAAa,IAAI,SAAS,CAAC;QAE3B,YAAY;QACZ,IAAI,SAAS,GAAG,YAAY,EAAE,CAAC;YAC7B,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YAC1B,YAAY,GAAG,EAAE,CAAC;YAClB,aAAa,GAAG,CAAC,CAAC;QACpB,CAAC;IACH,CAAC;IAED,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IACvD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CACvC,QAAuB,EACvB,aAAqB;IAErB,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,gBAAgB,CAAC;IAEnD,MAAM,WAAW,GAAG,sBAAsB,CAAC,QAAQ,CAAC,CAAC;IACrD,MAAM,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC,MAAM,CAAC;IAChD,MAAM,aAAa,GAAG,SAAS,GAAG,aAAa,CAAC;IAChD,MAAM,QAAQ,GAAG,aAAa,GAAG,aAAa,CAAC;IAE/C,IAAI,QAAQ,GAAG,GAAG,EAAE,CAAC;QACnB,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,GAAG,CAAC,EAAE,gBAAgB,GAAG,eAAe,CAAC,CAAC;QAC7E,OAAO,IAAI,CAAC,GAAG,CAAC,eAAe,EAAE,gBAAgB,GAAG,SAAS,CAAC,CAAC;IACjE,CAAC;IAED,OAAO,gBAAgB,CAAC;AAC1B,CAAC;AAkBD;;GAEG;AACH,MAAM,UAAU,0BAA0B,CACxC,YAAqB,EACrB,kBAA2B;IAE3B,IAAI,YAAY,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;QACrC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;IAChE,CAAC;IACD,IAAI,kBAAkB,IAAI,kBAAkB,GAAG,CAAC,EAAE,CAAC;QACjD,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,kBAAkB,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;IACrE,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,sBAAsB,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;AAC/D,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,0BAA0B,CACxC,IAAuB;IAEvB,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IACpD,OAAO;QACL,GAAG,IAAI;QACP,MAAM;QACN,UAAU,EAAE,MAAM,GAAG,CAAC,IAAI,MAAM,GAAG,gCAAgC;QACnE,WAAW,EAAE,MAAM,GAAG,CAAC,IAAI,MAAM,GAAG,8BAA8B;KACnE,CAAC;AACJ,CAAC;AAED,+EAA+E;AAC/E,OAAO;AACP,+EAA+E;AAE/E;;GAEG;AACH,KAAK,UAAU,eAAe,CAC5B,QAAoB,EACpB,QAAuB,EACvB,cAAsB,EACtB,eAAwB,EACxB,kBAA2B;IAE3B,MAAM,YAAY,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE;QACpC,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;QAC7E,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;QACtF,OAAO,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;IAChC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEd,IAAI,YAAY,GAAG;;;;;;4BAMO,CAAC;IAE3B,IAAI,kBAAkB,EAAE,CAAC;QACvB,YAAY,IAAI,YAAY,kBAAkB,EAAE,CAAC;IACnD,CAAC;IAED,IAAI,WAAW,GAAG,EAAE,CAAC;IACrB,IAAI,eAAe,EAAE,CAAC;QACpB,WAAW,IAAI,WAAW,eAAe,MAAM,CAAC;IAClD,CAAC;IACD,WAAW,IAAI,YAAY,YAAY,kBAAkB,CAAC;IAE1D,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC;YACnC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;YACzB,QAAQ,EAAE;gBACR,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,YAAY,EAAE;gBACzC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE;aACvC;SACF,CAAC,CAAC;QACH,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC;QACvD,OAAO,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,wBAAwB,CAAC;IACxE,CAAC;IAAC,OAAO,CAAM,EAAE,CAAC;QAChB,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;QACpC,OAAO,wBAAwB,CAAC;IAClC,CAAC;AACH,CAAC;AAED;;GAEG;AACH,KAAK,UAAU,eAAe,CAAC,MAM9B;IACC,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACjC,OAAO,MAAM,CAAC,eAAe,IAAI,wBAAwB,CAAC;IAC5D,CAAC;IAED,MAAM,MAAM,GAAG,wBAAwB,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,cAAc,CAAC,CAAC;IAChF,IAAI,OAAO,GAAG,MAAM,CAAC,eAAe,CAAC;IAErC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,OAAO,GAAG,MAAM,eAAe,CAC7B,MAAM,CAAC,QAAQ,EACf,KAAK,EACL,MAAM,CAAC,cAAc,EACrB,OAAO,EACP,MAAM,CAAC,kBAAkB,CAC1B,CAAC;IACJ,CAAC;IAED,OAAO,OAAO,IAAI,wBAAwB,CAAC;AAC7C,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,MAO3C;IACC,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACjC,OAAO,MAAM,CAAC,eAAe,IAAI,wBAAwB,CAAC;IAC5D,CAAC;IAED,SAAS;IACT,IAAI,CAAC;QACH,OAAO,MAAM,eAAe,CAAC,MAAM,CAAC,CAAC;IACvC,CAAC;IAAC,OAAO,SAAc,EAAE,CAAC;QACxB,MAAM,CAAC,IAAI,CAAC,kBAAkB,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC;IACrD,CAAC;IAED,YAAY;IACZ,MAAM,aAAa,GAAkB,EAAE,CAAC;IACxC,MAAM,cAAc,GAAa,EAAE,CAAC;IAEpC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QAClC,MAAM,MAAM,GAAG,cAAc,CAAC,GAAG,CAAC,GAAG,aAAa,CAAC;QACnD,IAAI,MAAM,GAAG,MAAM,CAAC,aAAa,GAAG,GAAG,EAAE,CAAC;YACxC,cAAc,CAAC,IAAI,CACjB,OAAO,GAAG,CAAC,IAAI,SAAS,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,oBAAoB,CACtE,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;IAED,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7B,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,eAAe,CAAC,EAAE,GAAG,MAAM,EAAE,QAAQ,EAAE,aAAa,EAAE,CAAC,CAAC;YAC9E,MAAM,KAAK,GAAG,cAAc,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAClF,OAAO,OAAO,GAAG,KAAK,CAAC;QACzB,CAAC;QAAC,OAAO,YAAiB,EAAE,CAAC;YAC3B,MAAM,CAAC,IAAI,CAAC,YAAY,YAAY,CAAC,OAAO,EAAE,CAAC,CAAC;QAClD,CAAC;IACH,CAAC;IAED,OAAO;IACP,OAAO,SAAS,MAAM,CAAC,QAAQ,CAAC,MAAM,QAAQ,cAAc,CAAC,MAAM,qBAAqB,CAAC;AAC3F,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,MAQvC;IACC,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,CAAC;IAC5B,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,MAAM,CAAC,eAAe,IAAI,wBAAwB,CAAC;IAC5D,CAAC;IAED,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,IAAI,CAAC,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACxE,MAAM,WAAW,GAAG,sBAAsB,CAAC,QAAQ,CAAC,CAAC;IAErD,2BAA2B;IAC3B,IAAI,KAAK,IAAI,CAAC,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,WAAW,IAAI,MAAM,CAAC,cAAc,EAAE,CAAC;QAC9E,OAAO,qBAAqB,CAAC,MAAM,CAAC,CAAC;IACvC,CAAC;IAED,MAAM,MAAM,GAAG,yBAAyB,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACpF,IAAI,MAAM,CAAC,MAAM,IAAI,CAAC;QAAE,OAAO,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAE7D,SAAS;IACT,MAAM,gBAAgB,GAAa,EAAE,CAAC;IACtC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,gBAAgB,CAAC,IAAI,CACnB,MAAM,qBAAqB,CAAC;YAC1B,GAAG,MAAM;YACT,QAAQ,EAAE,KAAK;YACf,eAAe,EAAE,SAAS;SAC3B,CAAC,CACH,CAAC;IACJ,CAAC;IAED,IAAI,gBAAgB,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAE9D,SAAS;IACT,MAAM,eAAe,GAAkB,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAChE,IAAI,EAAE,MAAe;QACrB,OAAO,EAAE,CAAC;KACX,CAAC,CAAC,CAAC;IAEJ,MAAM,iBAAiB,GAAG,MAAM,CAAC,kBAAkB;QACjD,CAAC,CAAC,GAAG,4BAA4B,YAAY,MAAM,CAAC,kBAAkB,EAAE;QACxE,CAAC,CAAC,4BAA4B,CAAC;IAEjC,OAAO,qBAAqB,CAAC;QAC3B,GAAG,MAAM;QACT,QAAQ,EAAE,eAAe;QACzB,kBAAkB,EAAE,iBAAiB;KACtC,CAAC,CAAC;AACL,CAAC;AAuBD;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAKtC;IACC,MAAM,eAAe,GAAG,MAAM,CAAC,eAAe,IAAI,GAAG,CAAC;IACtD,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,gBAAgB,GAAG,eAAe,CAAC,CAAC,CAAC;IACxF,IAAI,YAAY,GAAG,MAAM,CAAC,QAAQ,CAAC;IACnC,MAAM,UAAU,GAAkB,EAAE,CAAC;IACrC,IAAI,aAAa,GAAG,CAAC,CAAC;IACtB,IAAI,YAAY,GAAG,CAAC,CAAC;IACrB,IAAI,aAAa,GAAG,CAAC,CAAC;IAEtB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,IAAI,CAAC,CAAC,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC;IAE5E,OAAO,YAAY,CAAC,MAAM,GAAG,CAAC,IAAI,sBAAsB,CAAC,YAAY,CAAC,GAAG,YAAY,EAAE,CAAC;QACtF,MAAM,MAAM,GAAG,yBAAyB,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;QAC9D,IAAI,MAAM,CAAC,MAAM,IAAI,CAAC;YAAE,MAAM;QAE9B,MAAM,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,GAAG,MAAM,CAAC;QAClC,YAAY,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAC3B,aAAa,IAAI,CAAC,CAAC;QACnB,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC;QAC/B,aAAa,IAAI,sBAAsB,CAAC,OAAO,CAAC,CAAC;QACjD,UAAU,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC;IAC9B,CAAC;IAED,OAAO;QACL,QAAQ,EAAE,YAAY;QACtB,eAAe,EAAE,UAAU;QAC3B,aAAa;QACb,YAAY;QACZ,aAAa;QACb,UAAU,EAAE,sBAAsB,CAAC,YAAY,CAAC;QAChD,YAAY;KACb,CAAC;AACJ,CAAC;AAED,+EAA+E;AAC/E,yBAAyB;AACzB,+EAA+E;AAE/E;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,MAKpC;IAMC,MAAM,aAAa,GAAG,MAAM,CAAC,aAAa,IAAI,sBAAsB,CAAC;IACrE,MAAM,eAAe,GAAG,MAAM,CAAC,eAAe,IAAI,CAAC,CAAC;IACpD,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;IAEjC,IAAI,QAAQ,CAAC,MAAM,IAAI,eAAe,EAAE,CAAC;QACvC,OAAO;YACL,OAAO,EAAE,EAAE;YACX,YAAY,EAAE,QAAQ;YACtB,cAAc,EAAE,CAAC;YACjB,WAAW,EAAE,CAAC;SACf,CAAC;IACJ,CAAC;IAED,gBAAgB;IAChB,MAAM,SAAS,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,MAAM,GAAG,eAAe,CAAC,CAAC;IACvE,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,GAAG,eAAe,CAAC,CAAC;IACjE,MAAM,YAAY,GAAG,sBAAsB,CAAC,SAAS,CAAC,CAAC;IAEvD,MAAM,cAAc,GAAG,IAAI,CAAC,KAAK,CAAC,aAAa,GAAG,yBAAyB,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC,CAAC;IACvG,MAAM,OAAO,GAAG,MAAM,iBAAiB,CAAC;QACtC,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,QAAQ,EAAE,SAAS;QACnB,cAAc;QACd,aAAa;KACd,CAAC,CAAC;IAEH,OAAO;QACL,OAAO;QACP,YAAY,EAAE,MAAM;QACpB,cAAc,EAAE,SAAS,CAAC,MAAM;QAChC,WAAW,EAAE,YAAY,GAAG,cAAc,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;KACjF,CAAC;AACJ,CAAC"}

package/lib/ai/hooks.d.ts

@@ -0,0 +1,143 @@
+/**
+ * AI Hooks — AI 生命周期事件钩子系统
+ *
+ * 借鉴 OpenClaw 的 Hooks 设计，提供可扩展的事件驱动钩子：
+ *
+ *   - message:received   — 收到消息时触发
+ *   - message:sent       — 发送消息时触发
+ *   - session:compact    — 会话压缩时触发
+ *   - session:new        — 新建会话时触发
+ *   - agent:bootstrap    — Agent 初始化时触发
+ *   - agent:tool-call    — 工具调用时触发
+ *
+ * 钩子按注册顺序执行，错误不会中断其他钩子。
+ */
+/** 事件类型 */
+export type AIHookEventType = 'message' | 'session' | 'agent' | 'tool';
+/** Hook 事件基础接口 */
+export interface AIHookEvent {
+    /** 事件类型 */
+    type: AIHookEventType;
+    /** 具体动作 */
+    action: string;
+    /** 会话标识 */
+    sessionId?: string;
+    /** 附加上下文 */
+    context: Record<string, unknown>;
+    /** 事件时间戳 */
+    timestamp: Date;
+    /** 钩子可以推送消息到这个数组 */
+    messages: string[];
+}
+/** 消息接收事件 */
+export interface MessageReceivedEvent extends AIHookEvent {
+    type: 'message';
+    action: 'received';
+    context: {
+        from: string;
+        content: string;
+        platform: string;
+        channelId?: string;
+        messageId?: string;
+    };
+}
+/** 消息发送事件 */
+export interface MessageSentEvent extends AIHookEvent {
+    type: 'message';
+    action: 'sent';
+    context: {
+        to: string;
+        content: string;
+        success: boolean;
+        error?: string;
+        platform: string;
+    };
+}
+/** 会话压缩事件 */
+export interface SessionCompactEvent extends AIHookEvent {
+    type: 'session';
+    action: 'compact';
+    context: {
+        compactedCount: number;
+        savedTokens: number;
+        summary: string;
+    };
+}
+/** 会话新建事件 */
+export interface SessionNewEvent extends AIHookEvent {
+    type: 'session';
+    action: 'new';
+    context: {
+        previousSessionId?: string;
+    };
+}
+/** Agent 初始化事件 */
+export interface AgentBootstrapEvent extends AIHookEvent {
+    type: 'agent';
+    action: 'bootstrap';
+    context: {
+        workspaceDir: string;
+        toolCount: number;
+        skillCount: number;
+        bootstrapFiles: string[];
+    };
+}
+/** 工具调用事件 */
+export interface ToolCallEvent extends AIHookEvent {
+    type: 'tool';
+    action: 'call';
+    context: {
+        toolName: string;
+        args: Record<string, unknown>;
+        result?: string;
+        durationMs?: number;
+        success: boolean;
+        error?: string;
+    };
+}
+/** Hook 处理函数 */
+export type AIHookHandler = (event: AIHookEvent) => Promise<void> | void;
+/**
+ * 注册 Hook 处理函数
+ *
+ * @param eventKey - 事件类型（如 'message'）或具体动作（如 'message:received'）
+ * @param handler - 处理函数
+ *
+ * @example
+ * ```ts
+ * // 监听所有消息事件
+ * registerAIHook('message', async (event) => {
+ *   console.log('消息事件:', event.action);
+ * });
+ *
+ * // 只监听消息接收
+ * registerAIHook('message:received', async (event) => {
+ *   console.log('收到消息:', event.context.content);
+ * });
+ * ```
+ */
+export declare function registerAIHook(eventKey: string, handler: AIHookHandler): () => void;
+/**
+ * 注销 Hook 处理函数
+ */
+export declare function unregisterAIHook(eventKey: string, handler: AIHookHandler): void;
+/**
+ * 清除所有 Hook（测试用）
+ */
+export declare function clearAIHooks(): void;
+/**
+ * 获取已注册的事件 key 列表（调试用）
+ */
+export declare function getRegisteredAIHookKeys(): string[];
+/**
+ * 触发 Hook 事件
+ *
+ * 同时调用通用类型（如 'message'）和具体动作（如 'message:received'）的处理函数。
+ * 处理函数按注册顺序执行，错误被捕获并记录，不影响其他处理函数。
+ */
+export declare function triggerAIHook(event: AIHookEvent): Promise<void>;
+/**
+ * 创建 Hook 事件（辅助函数）
+ */
+export declare function createAIHookEvent(type: AIHookEventType, action: string, sessionId?: string, context?: Record<string, unknown>): AIHookEvent;
+//# sourceMappingURL=hooks.d.ts.map

package/lib/ai/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/ai/hooks.ts"],"names":[],"mappings":"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"}