@aalis/plugin-adapter-onebot 0.4.1

package/dist/forward-expand.js

@@ -0,0 +1,275 @@
+import { resolveLLMModel } from '@aalis/plugin-llm-api';
+import { buildEnvelope, expandForward } from './forward.js';
+import { collectForwardSegments } from './types.js';
+/**
+ * 合并转发摘要默认 system prompt。
+ *
+ * 设计重点：明确要求保留多人互动结构（谁说了什么 / 态度 / 回应关系）,
+ * 避免出现 “Alice 表达了对…” 这种压成一句、丢掉互动的退化摘要。
+ *
+ * 用户可通过配置 `forward.summaryPrompt` 完全覆盖本默认值。
+ */
+export const DEFAULT_FORWARD_SUMMARY_PROMPT = '你是聊天记录摘要助手。给定一段合并转发的原始内容，用简体中文输出一段含多人互动细节的摘要：\n' +
+    '- 按时间顺序串联主线，使用“某人：……”或“某人对某人说……”这种紧凑句式保留发言人轮次与互动关系，但不要逐条复述每句寒暄；\n' +
+    '- 明确点出每位主要参与人的关键发言 / 立场 / 情绪变化，以及他们互相同意、反驳、调侃、追问的点；\n' +
+    '- 原文里出现的请求 / 指令 / 待执行事项 / 希望机器人代发或转告的内容，必须原文输出并保留具体目标对象 / 群聊 / 要表达的观点；\n' +
+    '- 图片识别结果、链接、文件名等视觉 / 附件信息也要写进来；\n' +
+    '- 不要寒暄、不要解释自己、不要使用 markdown 列表或标题；输出单段落纯文本；\n' +
+    '- 控制在目标字数以内，优先保留互动细节与可引用发言，寒暄/重复信息略去。';
+const FORWARD_CACHE_TTL_MS = 60 * 60 * 1000;
+const FORWARD_METADATA_NS = 'onebot:forward';
+/**
+ * 把一个异步函数包成"同时最多 N 路"的并发受限版本。
+ * 用于合并转发内大量图片识别请求时削峰，避免压垮上游 / 触发限流。
+ */
+function createConcurrencyLimited(fn, limit) {
+    let active = 0;
+    const queue = [];
+    const acquire = () => {
+        if (active < limit) {
+            active++;
+            return Promise.resolve();
+        }
+        return new Promise(resolve => {
+            queue.push(() => {
+                active++;
+                resolve();
+            });
+        });
+    };
+    const release = () => {
+        active--;
+        const next = queue.shift();
+        if (next)
+            next();
+    };
+    return async (arg) => {
+        await acquire();
+        try {
+            return await fn(arg);
+        }
+        finally {
+            release();
+        }
+    };
+}
+/**
+ * 合并转发展开器工厂。
+ *
+ * 收到一条带 forward 段的消息时，立即递归拉取原文、做图像识别、生成摘要，
+ * 并把完整原文写入此缓存（也会同步到 MemoryService.saveMetadata 做持久化），
+ * 这样：
+ *   1) LLM 在对话上下文里看到的是"信封 + 摘要"，不被超长原文淹没；
+ *   2) 想看细节时调 onebot_get_forward_msg 工具直接命中缓存/持久化层；
+ *   3) 摘要会随 inbound:message 进入历史归档与向量库，被语义召回。
+ *
+ * 内存缓存 1h TTL；持久化由 memory metadata 兜底（如果实现支持）。
+ */
+export function createForwardExpander(deps) {
+    const { ctx, sendAction, forwardCfg } = deps;
+    const forwardCache = new Map();
+    function getCachedForward(id) {
+        const c = forwardCache.get(id);
+        if (!c)
+            return undefined;
+        if (c.expiresAt < Date.now()) {
+            forwardCache.delete(id);
+            return undefined;
+        }
+        return c.entry;
+    }
+    function setCachedForward(id, entry) {
+        forwardCache.set(id, { entry, expiresAt: Date.now() + FORWARD_CACHE_TTL_MS });
+        const memory = ctx.getService('memory');
+        if (memory?.saveMetadata) {
+            memory
+                .saveMetadata(FORWARD_METADATA_NS, id, entry)
+                .catch((err) => ctx.logger.debug(`forward metadata 持久化失败 id=${id}: ${err}`));
+        }
+    }
+    /** 从持久化层加载（缓存未命中时尝试） */
+    async function loadPersistedForward(id) {
+        const memory = ctx.getService('memory');
+        if (!memory?.getMetadata)
+            return undefined;
+        try {
+            const data = await memory.getMetadata(FORWARD_METADATA_NS, id);
+            if (data && typeof data === 'object' && typeof data.fullText === 'string') {
+                return data;
+            }
+        }
+        catch (err) {
+            ctx.logger.debug(`forward metadata 读取失败 id=${id}: ${err}`);
+        }
+        return undefined;
+    }
+    /**
+     * 拉取一条合并转发的内容，依次尝试多种参数键。
+     * 不同 OneBot 实现接受的字段不同：标准为 id，NapCat/Lagrange 部分版本接受
+     * message_id / res_id / m_resid。
+     */
+    async function fetchForwardOnce(state, id) {
+        const attempts = [{ id }, { message_id: id }, { res_id: id }, { m_resid: id }];
+        let lastErr;
+        for (const params of attempts) {
+            try {
+                return await sendAction(state, 'get_forward_msg', params);
+            }
+            catch (err) {
+                lastErr = err;
+            }
+        }
+        ctx.logger.debug(`get_forward_msg 全部参数尝试失败 id=${id}: ${lastErr}`);
+        return null;
+    }
+    /** 用 LLM 给一段 forward 原文生成摘要；失败/未配置则返回 null。 */
+    async function summarizeForward(text, hint) {
+        if (!forwardCfg.summarize)
+            return null;
+        const entry = resolveLLMModel(ctx, forwardCfg.summaryLLM, ['chat']);
+        if (!entry) {
+            ctx.logger.debug('forward 摘要：无可用 LLM 服务，跳过');
+            return null;
+        }
+        const llm = entry.instance;
+        const inputLimit = forwardCfg.summaryInputLimit;
+        const trimmedInput = inputLimit > 0 && text.length > inputLimit ? `${text.slice(0, inputLimit)}\n…（原文已截断）` : text;
+        // 摘要 prompt：用户可通过 forward.summaryPrompt 覆盖默认值，默认 prompt
+        // 明确要求保留多人互动结构，避免压成一句的退化摘要。
+        const sys = forwardCfg.summaryPrompt && forwardCfg.summaryPrompt.trim().length > 0
+            ? forwardCfg.summaryPrompt
+            : DEFAULT_FORWARD_SUMMARY_PROMPT;
+        const userPrompt = `合并转发包含 ${hint.count} 条消息，主要参与人：${hint.participants.join(', ') || '未知'}。\n目标字数：≤${forwardCfg.summaryMaxChars} 字（可超出 10% 以完整保留互动结构）。\n\n原文：\n${trimmedInput}`;
+        try {
+            const resp = await llm.chat({
+                messages: [
+                    { role: 'system', content: sys },
+                    { role: 'user', content: userPrompt },
+                ],
+                temperature: 0.3,
+                think: false,
+                maxTokens: Math.max(800, Math.ceil(forwardCfg.summaryMaxChars * 1.5)),
+            });
+            const out = (resp.content ?? '').trim();
+            if (!out) {
+                ctx.logger.debug(`forward 摘要返回空内容: model=${forwardCfg.summaryLLM ? `${forwardCfg.summaryLLM.provider}/${forwardCfg.summaryLLM.model}` : 'default'}, chars=${forwardCfg.summaryMaxChars}`);
+                return null;
+            }
+            return out;
+        }
+        catch (err) {
+            ctx.logger.warn(`forward 摘要生成失败: ${err}`);
+            return null;
+        }
+    }
+    /**
+     * 把 event.text 中所有 <forward id="X">[合并转发消息]</forward> 占位符
+     * 替换为"信封文本"（含摘要）；完整原文写入 forwardCache + memory metadata。
+     *
+     * 优先使用消息段里随帧带来的 inline content（部分 NapCat 版本会内嵌），
+     * 这种情况下顶层无需走网络。
+     */
+    async function expandForwardsInText(state, text, rawSegments) {
+        if (!forwardCfg.enabled)
+            return text;
+        if (!text.includes('<forward id='))
+            return text;
+        const inlineMap = new Map();
+        if (rawSegments && Array.isArray(rawSegments)) {
+            for (const f of collectForwardSegments(rawSegments)) {
+                if (f.inlineNodes && f.inlineNodes.length > 0)
+                    inlineMap.set(f.id, f.inlineNodes);
+            }
+        }
+        const idRe = /<forward id="([^"]+)">\[合并转发消息\]<\/forward>/g;
+        const ids = new Set();
+        let m = idRe.exec(text);
+        while (m !== null) {
+            ids.add(m[1]);
+            m = idRe.exec(text);
+        }
+        if (ids.size === 0)
+            return text;
+        const mediaSvc = ctx.getService('media');
+        const rawRecognize = forwardCfg.imageRecognition && mediaSvc?.describeImage ? (src) => mediaSvc.describeImage(src) : undefined;
+        const concurrency = Math.max(1, forwardCfg.imageRecognitionConcurrency);
+        // 用一个简单 semaphore 限制单次展开内的图片/音频/视频识别并发，避免 OOM/触发上游限流
+        const recognizeImage = rawRecognize ? createConcurrencyLimited(rawRecognize, concurrency) : undefined;
+        const recognizeAudio = mediaSvc?.transcribe
+            ? createConcurrencyLimited((src) => mediaSvc.transcribe({ kind: 'audio', data: src }), concurrency)
+            : undefined;
+        const recognizeVideo = mediaSvc?.describeVideo
+            ? createConcurrencyLimited(async (src) => (await mediaSvc.describeVideo(src)) || undefined, concurrency)
+            : undefined;
+        const envelopeMap = new Map();
+        for (const id of ids) {
+            let entry = getCachedForward(id);
+            if (!entry) {
+                const persisted = await loadPersistedForward(id);
+                if (persisted) {
+                    setCachedForward(id, persisted);
+                    entry = persisted;
+                }
+            }
+            if (entry) {
+                envelopeMap.set(id, buildEnvelope({
+                    id,
+                    count: entry.count,
+                    participants: entry.participants,
+                    fullText: entry.fullText,
+                    truncatedDepth: false,
+                    truncatedNodes: false,
+                }, entry.summary));
+                continue;
+            }
+            try {
+                const expanded = await expandForward(id, inlineMap.get(id) ?? null, {
+                    fetchForward: (childId) => fetchForwardOnce(state, childId),
+                    recognizeImage,
+                    recognizeAudio,
+                    recognizeVideo,
+                    maxDepth: forwardCfg.maxDepth,
+                    maxNodesPerLevel: forwardCfg.maxNodesPerLevel,
+                    imageRecognitionEnabled: forwardCfg.imageRecognition,
+                });
+                if (!expanded.fullText.trim()) {
+                    envelopeMap.set(id, `<forward id="${id}">[合并转发消息：协议端无法读取（可能已过期/不在当前会话作用域）]</forward>`);
+                    continue;
+                }
+                const summary = await summarizeForward(expanded.fullText, {
+                    count: expanded.count,
+                    participants: expanded.participants,
+                });
+                const stored = {
+                    fullText: expanded.fullText,
+                    summary,
+                    count: expanded.count,
+                    participants: expanded.participants,
+                    expandedAt: Date.now(),
+                };
+                setCachedForward(id, stored);
+                const truncFlag = expanded.truncatedDepth || expanded.truncatedNodes ? ' [truncated]' : '';
+                // 日志里输出完整摘要（或在无摘要时输出完整原文），便于排查 forward 实际入库内容；
+                // 不再做 80 字 preview 截断，避免「日志看不到全貌」。原文/摘要都已入库到
+                // forwardCache + memory metadata，后续 onebot_get_forward_msg 可直接取回。
+                const fullPreview = (summary ?? expanded.fullText).replace(/\n/g, ' ');
+                ctx.logger.debug(`forward 展开完成 id=${id} count=${expanded.count} participants=[${expanded.participants.join(',')}]` +
+                    ` summary=${summary ? `${summary.length}字` : 'null'}${truncFlag} content="${fullPreview}"`);
+                envelopeMap.set(id, buildEnvelope(expanded, summary));
+            }
+            catch (err) {
+                ctx.logger.warn(`forward 展开失败 id=${id}: ${err}`);
+                envelopeMap.set(id, `<forward id="${id}">[合并转发消息：展开过程出错]</forward>`);
+            }
+        }
+        return text.replace(idRe, (raw, id) => envelopeMap.get(id) ?? raw);
+    }
+    return {
+        getCachedForward,
+        setCachedForward,
+        loadPersistedForward,
+        fetchForwardOnce,
+        expandForwardsInText,
+    };
+}
+//# sourceMappingURL=forward-expand.js.map

package/dist/forward-expand.js.map

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

package/dist/forward.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 合并转发（forward）展开、图片识别与摘要生成。
+ *
+ * 设计目标：让 agent 处理合并转发更接近"人类阅读"的方式：
+ * - 进入对话上下文 / 历史归档的是一份摘要（信封），而非整块原文，
+ *   避免长转发淹没真正对话；
+ * - 内部图片走 media 服务转写为文字描述，保证多模态信息
+ *   不在摘要里丢失；
+ * - 嵌套转发递归展开（带深度上限与已访问 id 集合防环），让摘要能反映
+ *   多层结构；
+ * - 完整原文仍保留在缓存与 memory metadata 中，agent 想看细节时通过
+ *   onebot_get_forward_msg 工具 / 缓存命中拿回。
+ *
+ * 本模块仅做"纯逻辑"，不直接依赖 Context；适配器通过依赖注入提供
+ * fetchForward / recognizeImage / summarize 三个能力函数。
+ */
+/** 单个转发节点的扁平表示 */
+export interface ForwardLine {
+    /** 缩进层级（顶层=0，嵌套+1） */
+    depth: number;
+    index: number;
+    nickname: string;
+    userId?: string;
+    /** 已替换图片为 [图片: 描述] / [图片] 的纯文本 */
+    text: string;
+}
+export interface ExpandedForward {
+    /** forward id */
+    id: string;
+    /** 顶层节点条数（嵌套不计入） */
+    count: number;
+    /** 去重后的参与人列表（昵称(uid) 形式，最多前 8 个） */
+    participants: string[];
+    /** 完整渲染文本（用于缓存 / 工具回看 / 摘要输入） */
+    fullText: string;
+    /** 嵌套转发是否被截断（命中深度上限） */
+    truncatedDepth: boolean;
+    /** 是否有节点被截断（命中 maxNodesPerLevel） */
+    truncatedNodes: boolean;
+}
+export interface ForwardExpandOptions {
+    /** 抓取一个 forward id 的原始数据（成功则返回 OneBot 返回的 data） */
+    fetchForward: (id: string) => Promise<unknown | null>;
+    /** 把图片源转为文字描述（不可用则可返回 undefined） */
+    recognizeImage?: (source: string) => Promise<string | undefined>;
+    /** 把音频源（record 段）转为文字（转写或描述） */
+    recognizeAudio?: (source: string) => Promise<string | undefined>;
+    /** 把视频源转为文字描述（抽帧+音轨综合） */
+    recognizeVideo?: (source: string) => Promise<string | undefined>;
+    /** 嵌套展开深度上限（顶层为 1） */
+    maxDepth: number;
+    /** 单层节点数上限 */
+    maxNodesPerLevel: number;
+    /** 是否启用图片识别 */
+    imageRecognitionEnabled: boolean;
+    /** 是否启用音频识别（默认随 recognizeAudio 是否提供） */
+    audioRecognitionEnabled?: boolean;
+    /** 是否启用视频识别（默认随 recognizeVideo 是否提供） */
+    videoRecognitionEnabled?: boolean;
+}
+/**
+ * 递归展开一个 forward。返回扁平行（含 depth）便于直接拼接文本。
+ *
+ * @param topId 顶层 forward id
+ * @param topNodes 顶层节点数组（如果调用方已抓到了，可直接传入；否则将通过 fetchForward 抓取）
+ */
+export declare function expandForward(topId: string, topNodes: unknown[] | null, opts: ForwardExpandOptions): Promise<ExpandedForward>;
+export interface SummarizeOptions {
+    /** 调用 LLM 生成摘要（输入完整 forward 文本，输出摘要文本）。返回 null 表示不生成。 */
+    summarize?: (text: string, hint: {
+        count: number;
+        participants: string[];
+    }) => Promise<string | null>;
+    /** 摘要不可用 / 失败时的回退渲染：把完整文本截断为信封。 */
+    fallbackFullTextMaxChars: number;
+}
+/** 把展开结果包装成最终注入到 event.text 的"信封文本"。 */
+export declare function buildEnvelope(expanded: ExpandedForward, summary: string | null, truncatedFallbackChars?: number): string;
+//# sourceMappingURL=forward.d.ts.map

package/dist/forward.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forward.d.ts","sourceRoot":"","sources":["../src/forward.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,kBAAkB;AAClB,MAAM,WAAW,WAAW;IAC1B,sBAAsB;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,eAAe;IAC9B,iBAAiB;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,oBAAoB;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,iCAAiC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,wBAAwB;IACxB,cAAc,EAAE,OAAO,CAAC;IACxB,oCAAoC;IACpC,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,mDAAmD;IACnD,YAAY,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IACtD,oCAAoC;IACpC,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACjE,gCAAgC;IAChC,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACjE,0BAA0B;IAC1B,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACjE,sBAAsB;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc;IACd,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe;IACf,uBAAuB,EAAE,OAAO,CAAC;IACjC,wCAAwC;IACxC,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,wCAAwC;IACxC,uBAAuB,CAAC,EAAE,OAAO,CAAC;CACnC;AA2OD;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,OAAO,EAAE,GAAG,IAAI,EAC1B,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,eAAe,CAAC,CA6F1B;AAID,MAAM,WAAW,gBAAgB;IAC/B,yDAAyD;IACzD,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,EAAE,CAAA;KAAE,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACtG,mCAAmC;IACnC,wBAAwB,EAAE,MAAM,CAAC;CAClC;AAED,wCAAwC;AACxC,wBAAgB,aAAa,CAAC,QAAQ,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,EAAE,sBAAsB,SAAM,GAAG,MAAM,CAarH"}