lightclawbot 1.1.2 → 1.2.0-beta.0

package/dist/src/inbound.js

@@ -1,340 +1,274 @@
 /**
  * LightClaw — 入站消息处理
  *
- * 接收用户消息 → 文件处理 → 路由 → AI 分发 → 回复
- */
-import { getAssistantRuntime } from "./runtime.js";
-import { CHANNEL_KEY, REPLY_TIMEOUT, MEDIA_MAX_BYTES, resolveEffectiveApiKey, setSessionApiKey } from "./config.js";
-import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline";
-import { generateMsgId } from "./dedup.js";
-import { parseDataUrl, formatFileSize, mediaUrlsToFiles } from "./media.js";
-import { uploadFileToCos, downloadFileFromCos, getFileDownloadUrl } from "./file-storage.js";
-/**
- * 创建入站消息处理器
+ * 接收用户消息 → 文件处理 → 路由 → AI 分发 → 回复。
+ *
+ * 并发/abort 完全委托给 openclaw：
+ *   - 并发由 session 写锁 + followup queue 保证；
+ *   - /stop 及自然语言 abort 由 tryFastAbortFromMessage 统一处理并递归 kill subagent。
  */
+import { emitSignal } from './types.js';
+import { CHANNEL_KEY, MEDIA_MAX_BYTES, resolveEffectiveApiKey, setSessionApiKey, DEFAULT_AGENT_ID } from './config.js';
+import { getLightclawRuntime } from './runtime.js';
+import { createChannelReplyPipeline } from 'openclaw/plugin-sdk/channel-reply-pipeline';
+import { generateMsgId } from './dedup.js';
+import { parseDataUrl, formatFileSize } from './media.js';
+import { uploadFileToCos, downloadFileFromCos, getFileDownloadUrl } from './file-storage.js';
+import { createStreamReplyConfig } from './streaming/index.js';
 export function createInboundHandler(account, emitter, log) {
     return async (msg) => {
-        const pluginRuntime = getAssistantRuntime();
+        // mas: {"senderId":"100013456706","text":"今天天气怎么样","messageId":"91647ae9-c123-48e4-9d80-26f2e9a91ac9","files":[],"timestamp":1776077511044}
+        const pluginRuntime = getLightclawRuntime();
+        // 每次处理消息时重新加载配置，确保使用最新的运行时配置（支持热更新）
         const currentCfg = pluginRuntime.config.loadConfig();
-        // 根据 senderId(=uin) 获取对应的 apiKey（多 key 模式下按 uin 选 key，单 key 模式下 fallback 到主 key）
+        // 根据 senderId（= uin）选择对应的 apiKey：
+        // - 多 key 模式：按 uin→apiKey 映射表查找，实现不同用户使用不同 key
+        // - 单 key 模式：映射表为空，fallback 到账户主 key
         const effectiveApiKey = resolveEffectiveApiKey({ senderId: msg.senderId });
         log?.info(`[${CHANNEL_KEY}] Effective API key for uin ${msg.senderId}: ${effectiveApiKey.slice(0, 8)}...`);
-        // 1. 确定地址和会话 Key
-        // 使用标准 user: 前缀，与 normalizeTarget 输出格式一致
+        // ---- 步骤 1：确定地址和会话 Key ----
+        // 使用标准 user: 前缀，与 normalizeTarget 输出格式保持一致，
+        // 确保框架路由系统能正确识别 peer kind 为 "direct"
         const fromAddress = `user:${msg.senderId}`;
-        // 2. 路由解析
-        const route = pluginRuntime.channel.routing.resolveAgentRoute({
+        // ---- 步骤 2：路由解析 ----
+        // 根据 channel + accountId + peer 三元组确定：
+        // - agentId    : 处理此消息的 Agent ID
+        // - sessionKey : per-channel-peer 会话键（用于隔离不同用户的会话历史）
+        // - accountId  : 实际使用的账户 ID（可能被路由规则覆盖）
+        // agentId 合法性校验：防止前端传入任意 agentId 访问其他 Agent 的数据
+        const validAgentIds = currentCfg.agents?.list?.map((a) => a.id) ?? [DEFAULT_AGENT_ID];
+        const resolvedAgentId = msg.agentId && validAgentIds.includes(msg.agentId) ? msg.agentId : DEFAULT_AGENT_ID; // undefined 时框架自动路由到默认 Agent
+        const baseRoute = pluginRuntime.channel.routing.resolveAgentRoute({
             cfg: currentCfg,
             channel: CHANNEL_KEY,
             accountId: account.accountId,
-            peer: { kind: "direct", id: msg.senderId },
+            peer: { kind: 'direct', id: msg.senderId },
         });
-        // 3. 权限检查
+        // route: {"agentId":"main","channel":"lightclawbot","accountId":"default","sessionKey":"agent:main:lightclawbot:direct:100013456706","mainSessionKey":"agent:main:main","lastRoutePolicy":"session","matchedBy":"default"}
+        // 若前端指定了合法的 agentId，则用 buildAgentSessionKey 覆盖 sessionKey 和 agentId，
+        // 实现 Agent 间隔离（sessionKey 含 agentId，不同 Agent 的会话历史完全独立）
+        const route = resolvedAgentId
+            ? {
+                ...baseRoute,
+                agentId: resolvedAgentId,
+                sessionKey: pluginRuntime.channel.routing.buildAgentSessionKey({
+                    agentId: resolvedAgentId,
+                    channel: CHANNEL_KEY,
+                    accountId: baseRoute.accountId,
+                    peer: { kind: 'direct', id: msg.senderId },
+                    dmScope: 'per-channel-peer',
+                }),
+                mainSessionKey: `agent:${resolvedAgentId}:main`,
+            }
+            : baseRoute;
+        log?.info(`[CHANNEL_KEY]: route= ${JSON.stringify(route)}`);
+        // ---- 步骤 3：权限检查 ----
+        // 根据 allowFrom 白名单和 dmPolicy 策略决定是否允许此用户发送命令
         const commandAuthorized = checkAuth(account.allowFrom, account.dmPolicy, msg.senderId);
-        // 3.5 记录 sessionKey → apiKey 映射（tool 执行时通过 ctx.sessionKey 直接获取对应 apiKey）
-        // 注意：只写入 per-channel-peer 的 sessionKey，不写入 mainSessionKey。
-        // mainSessionKey（= "agent:main:main"）是全局共享的，所有用户消息都会覆盖它，
-        // 导致最后一个用户的 apiKey 覆盖前一个用户，产生并发安全问题。
+        // ---- 步骤 3.5：记录 sessionKey → apiKey 映射 ----
+        // 目的：tool 执行时通过 ctx.sessionKey 直接查找对应的 apiKey，
+        // 避免在 tool 层再次解析 uin。
+        // 重要：只写入 per-channel-peer 的 sessionKey，不写入 mainSessionKey。
+        // mainSessionKey（= "agent:main:main"）是全局共享的，
+        // 若写入则最后一个用户的 apiKey 会覆盖前一个用户，产生并发安全问题。
         if (route?.sessionKey) {
             setSessionApiKey(route.sessionKey, effectiveApiKey);
         }
-        // 4. 处理文件附件（files[] → 本地存储）
+        const targetId = msg.senderId;
+        // 2. 提前发 typing_start（作为"已读回执"，减少 COS 下载/LLM TTFT 期间的无反馈感）
+        const replyMsgId = generateMsgId();
+        // 将 route.agentId 作为整条消息处理链路的绑定默认值，所有出站消息均携带此 agentId
+        const effectiveAgentId = route.agentId ?? resolvedAgentId ?? DEFAULT_AGENT_ID;
+        // 基于上层 gateway 的 emitter，构造一个绑定当前 agentId 的包装 emitter
+        // 所有调用 emit / sendReply / sendFiles 未显式传 agentId 时，消息体都会自动注入 effectiveAgentId
+        const boundEmitter = {
+            botClientId: emitter.botClientId,
+            agentId: effectiveAgentId,
+            emit: (data) => emitter.emit({ ...data, agentId: data.agentId ?? effectiveAgentId }),
+            sendReply: (tid, text, replyTo, agentId) => emitter.sendReply(tid, text, replyTo, agentId ?? effectiveAgentId),
+            sendFiles: (tid, text, files, replyTo, agentId) => emitter.sendFiles(tid, text, files, replyTo, agentId ?? effectiveAgentId),
+        };
+        const signalCtx = {
+            emitter: boundEmitter,
+            targetId,
+            replyMsgId,
+            originalMsgId: msg.messageId,
+            agentId: effectiveAgentId,
+        };
+        emitSignal(signalCtx, 'typing_start');
+        // 3. 处理文件附件（files[] → 本地存储 + 公网 URL）
         const localMediaPaths = [];
+        /** 本地文件 MIME 类型列表，与 localMediaPaths 一一对应 */
         const localMediaTypes = [];
-        // 每个文件对应的公网可访问 URL，用于 session 历史持久化
         const publicMediaUrls = [];
+        /** 传递给 AI 上下文的附件列表（name + mimeType + 公网 URL） */
         const ctxAttachments = [];
-        let attachmentDescription = "";
+        /** 附加到用户消息末尾的文件描述文本（告知 AI 用户发送了哪些文件） */
+        let attachmentDescription = '';
         for (const file of msg.files) {
             try {
                 let buffer;
                 let mimeType;
-                // 记录文件的公网 URL，优先用于 session 存储
                 let cosPublicUrl;
                 const parsed = file.bytes ? parseDataUrl(file.bytes) : null;
                 if (parsed) {
-                    // data URL 格式：直接解析
                     buffer = parsed.buffer;
                     mimeType = parsed.mimeType;
                 }
                 else if (file.uri) {
-                    // 远程 URI（下载地址），下载获取内容
                     log?.info(`[${CHANNEL_KEY}] File has URI, downloading from cloud: ${file.uri}`);
                     const downloaded = await downloadFileFromCos(file.uri, { apiKey: effectiveApiKey });
                     buffer = downloaded.buffer;
                     mimeType = file.mimeType;
-                    // 保留原始公网 URL，用于 session 历史中持久化引用
-                    cosPublicUrl = file.uri.startsWith("http")
-                        ? file.uri
-                        : getFileDownloadUrl(file.uri);
+                    cosPublicUrl = file.uri.startsWith('http') ? file.uri : getFileDownloadUrl(file.uri);
                 }
                 else {
+                    // 来源 3：既无 bytes 也无 uri，无法处理，跳过此文件
                     log?.warn(`[${CHANNEL_KEY}] File has no bytes or uri: ${file.name}, skipping`);
                     continue;
                 }
-                const saved = await pluginRuntime.channel.media.saveMediaBuffer(buffer, mimeType, "inbound", MEDIA_MAX_BYTES, file.name);
+                // 将文件内容保存到本地媒体存储（框架统一管理，支持大小限制和格式校验）
+                const saved = await pluginRuntime.channel.media.saveMediaBuffer(buffer, mimeType, 'inbound', MEDIA_MAX_BYTES, file.name);
                 localMediaPaths.push(saved.path);
                 localMediaTypes.push(mimeType);
-                // 如果文件来自云端，使用公网 URL；否则尝试上传获取公网 URL
                 if (cosPublicUrl) {
                     publicMediaUrls.push(cosPublicUrl);
                 }
                 else {
-                    // data URL 来源的文件：上传到云端以获取公网 URL
+                    // data URL 来源：上传到 COS 获取公网 URL，失败则 fallback 到本地路径
                     try {
                         const uploadResult = await uploadFileToCos(saved.path, { apiKey: effectiveApiKey });
                         publicMediaUrls.push(uploadResult.url || `file://${saved.path}`);
-                        log?.info(`[${CHANNEL_KEY}] Uploaded inbound file to cloud: ${saved.path} → ${uploadResult.url}`);
+                        log?.info(`[${CHANNEL_KEY}] Uploaded inbound file: ${saved.path} → ${uploadResult.url}`);
                     }
                     catch (uploadErr) {
-                        log?.warn(`[${CHANNEL_KEY}] Failed to upload inbound file, falling back to local path: ${uploadErr}`);
+                        log?.warn(`[${CHANNEL_KEY}] Upload failed, falling back to local path: ${uploadErr}`);
                         publicMediaUrls.push(`file://${saved.path}`);
                     }
                 }
-                // Attachments 中使用公网 URL，确保 session 历史中的地址可被前端访问
                 const attachmentUrl = publicMediaUrls[publicMediaUrls.length - 1];
-                ctxAttachments.push({
-                    name: file.name,
-                    mimeType,
-                    url: attachmentUrl,
-                });
+                ctxAttachments.push({ name: file.name, mimeType, url: attachmentUrl });
                 attachmentDescription += `\n用户发送了文件: ${file.name} (${formatFileSize(saved.size)})`;
-                log?.info(`[${CHANNEL_KEY}] File saved: ${saved.path} (${mimeType}, ${formatFileSize(saved.size)}), publicUrl: ${attachmentUrl}`);
+                log?.info(`[${CHANNEL_KEY}] File saved: ${saved.path} (${mimeType}, ${formatFileSize(saved.size)})`);
             }
             catch (err) {
+                // 单个文件处理失败不影响整条消息的处理，记录错误后继续
                 log?.error(`[${CHANNEL_KEY}] File processing failed for ${file.name}: ${err}`);
             }
         }
-        // 5. 构建消息体
+        // 4. 构建 AI 上下文
         const userText = msg.text + attachmentDescription;
-        const agentBody = account.systemPrompt
-            ? `${account.systemPrompt}\n\n${userText}`
-            : userText;
-        // 6. 构建入站上下文
-        // MediaPaths 保持本地路径（AI 模型 vision 需要从本地读取文件内容）
-        // MediaUrls 使用公网 URL（session 历史持久化，前端可直接访问）
+        const agentBody = account.systemPrompt ? `${account.systemPrompt}\n\n${userText}` : userText;
+        // MediaPaths 保留本地路径（vision 模型需读本地文件）；MediaUrls 用公网 URL（session 持久化）
         const mediaFields = {};
         if (localMediaPaths.length > 0) {
-            mediaFields.MediaPaths = localMediaPaths;
-            mediaFields.MediaPath = localMediaPaths[0];
-            mediaFields.MediaTypes = localMediaTypes;
-            mediaFields.MediaType = localMediaTypes[0];
-            mediaFields.MediaUrls = publicMediaUrls;
-            mediaFields.MediaUrl = publicMediaUrls[0];
+            mediaFields.MediaPaths = localMediaPaths; // 所有本地路径（数组）
+            mediaFields.MediaPath = localMediaPaths[0]; // 第一个本地路径（兼容单文件场景）
+            mediaFields.MediaTypes = localMediaTypes; // 所有 MIME 类型（数组）
+            mediaFields.MediaType = localMediaTypes[0]; // 第一个 MIME 类型
+            mediaFields.MediaUrls = publicMediaUrls; // 所有公网 URL（数组）
+            mediaFields.MediaUrl = publicMediaUrls[0]; // 第一个公网 URL
         }
+        // finalizeInboundContext 负责将原始字段规范化为框架标准的 InboundContext 格式
         const ctxPayload = pluginRuntime.channel.reply.finalizeInboundContext({
-            Body: userText,
-            BodyForAgent: agentBody,
-            RawBody: msg.text,
-            CommandBody: msg.text,
-            From: fromAddress,
-            To: `${CHANNEL_KEY}:${account.accountId}`,
+            Body: userText, // 传给 AI 的用户消息（含文件描述）
+            BodyForAgent: agentBody, // 传给 Agent 的完整 body（含 systemPrompt）
+            RawBody: msg.text, // 用户原始文本（不含文件描述）
+            CommandBody: msg.text, // 命令解析用的原始文本
+            From: fromAddress, // 发送方地址（user:<uin>）
+            To: `${CHANNEL_KEY}:${account.accountId}`, // 接收方地址（通道:账户）
             Channel: CHANNEL_KEY,
-            ChatType: "direct",
-            SessionKey: route?.sessionKey ?? fromAddress,
-            AccountId: route?.accountId ?? account.accountId,
-            SenderId: msg.senderId,
-            SenderName: msg.senderId,
+            ChatType: 'direct', // 私聊
+            SessionKey: route?.sessionKey ?? fromAddress, // 会话键（优先用路由解析结果）
+            AccountId: route?.accountId ?? account.accountId, // 账户 ID（路由可能覆盖）
+            SenderId: msg.senderId, // 发送方 uin
+            SenderName: msg.senderId, // 发送方显示名（暂用 uin 代替）
             Provider: CHANNEL_KEY,
             Surface: CHANNEL_KEY,
-            MessageSid: msg.messageId,
+            MessageSid: msg.messageId, // 原始消息 ID（用于回复引用）
             Timestamp: msg.timestamp,
             OriginatingChannel: CHANNEL_KEY,
             OriginatingTo: fromAddress,
-            CommandAuthorized: commandAuthorized,
+            CommandAuthorized: commandAuthorized, // 是否有权限执行命令
+            // 有权限时，将发送方加入 OwnerAllowFrom，使其可以访问 owner 级别的命令
             OwnerAllowFrom: commandAuthorized ? [msg.senderId, fromAddress] : undefined,
             AgentId: route?.agentId,
             Attachments: ctxAttachments.length > 0 ? ctxAttachments : undefined,
             ...mediaFields,
         });
         log?.info(`[${CHANNEL_KEY}] Inbound context: ${JSON.stringify(ctxPayload)}`);
-        const targetId = msg.senderId;
-        log?.info(`[${CHANNEL_KEY}] Processing: from=${msg.senderId} text="${(msg.text || "(仅文件)").slice(0, 60)}" files=${msg.files.length}`);
-        // 6.5 更新 session 的 last route，使 cron 定时任务能找到 lightclawbot 的投递目标
+        log?.info(`[${CHANNEL_KEY}] Processing: from=${msg.senderId} text="${(msg.text || '(仅文件)').slice(0, 60)}" files=${msg.files.length}`);
+        // ---- 步骤 6.5：更新 session 的 last route ----
+        // 目的：使 cron 定时任务能找到 lightclawbot 的投递目标（deliveryContext），
+        // 从而在没有用户消息触发的情况下也能主动推送消息。
         const storePath = pluginRuntime.channel.session.resolveStorePath(route.agentId);
         const deliveryCtx = {
             channel: CHANNEL_KEY,
             to: fromAddress,
             accountId: route.accountId ?? account.accountId,
         };
-        // 写入 per-channel-peer session
+        // 写入 per-channel-peer session（精确匹配当前用户的会话）
         if (route?.sessionKey) {
-            pluginRuntime.channel.session.updateLastRoute({
+            pluginRuntime.channel.session
+                .updateLastRoute({
                 storePath,
                 sessionKey: route.sessionKey,
                 deliveryContext: deliveryCtx,
-            }).catch((err) => {
-                log?.error(`[${CHANNEL_KEY}] Failed to update last route (session): ${err}`);
-            });
+            })
+                .catch((err) => log?.error(`[${CHANNEL_KEY}] updateLastRoute(session) failed: ${err}`));
         }
-        // 写入 main session（兜底）
+        // 写入 main session（兜底，确保全局 cron 也能找到投递目标）
+        // 仅当 mainSessionKey 与 sessionKey 不同时才写入，避免重复写入
         if (route?.mainSessionKey && route.mainSessionKey !== route.sessionKey) {
-            pluginRuntime.channel.session.updateLastRoute({
+            pluginRuntime.channel.session
+                .updateLastRoute({
                 storePath,
                 sessionKey: route.mainSessionKey,
                 deliveryContext: deliveryCtx,
-            }).catch((err) => {
-                log?.error(`[${CHANNEL_KEY}] Failed to update last route (main): ${err}`);
-            });
+            })
+                .catch((err) => log?.error(`[${CHANNEL_KEY}] updateLastRoute(main) failed: ${err}`));
         }
-        // 7. 创建 replyPrefixOptions（使用 createChannelReplyPipeline 替代已移除的 createReplyPrefixOptions）
+        // ---- 步骤 7：创建 replyPrefixOptions ----
+        // createChannelReplyPipeline 返回：
+        // - onModelSelected  : 模型选择回调（用于 replyOptions）
+        // - typingCallbacks  : 打字状态回调（此处不使用，用 _tc 忽略）
+        // - ...prefixOptions : 传给 dispatcherOptions 的前缀配置（含 prefix、suffix 等）
         const { onModelSelected, typingCallbacks: _tc, ...prefixOptions } = createChannelReplyPipeline({
             cfg: currentCfg,
             agentId: route.agentId,
             channel: CHANNEL_KEY,
             accountId: account.accountId,
         });
-        // 8. 分发给 AI 引擎
-        let hasResponse = false;
-        let idleSent = false;
-        let timeoutId = null;
-        let timeoutFired = false;
-        // 超时仅记录日志，不中断 dispatch（AI 可能仍在处理中）
-        timeoutId = setTimeout(() => {
-            if (!hasResponse) {
-                timeoutFired = true;
-                log?.warn(`[${CHANNEL_KEY}] AI reply not received within ${REPLY_TIMEOUT}ms, still waiting...`);
-            }
-        }, REPLY_TIMEOUT);
-        // 同一条消息的流式回复（typing_start / stream_chunk / typing_stop）共用同一个 msgId
-        const replyMsgId = generateMsgId();
-        const dispatchPromise = pluginRuntime.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
-            ctx: ctxPayload,
-            cfg: currentCfg,
-            dispatcherOptions: {
-                ...prefixOptions,
-                deliver: async (payload, info) => {
-                    hasResponse = true;
-                    log?.info(`[${CHANNEL_KEY}] Deliver: ${JSON.stringify(payload)}。info: ${JSON.stringify(info)}`);
-                    if (timeoutId) {
-                        clearTimeout(timeoutId);
-                        timeoutId = null;
-                    }
-                    const replyText = payload.text ?? payload.body ?? "";
-                    const mediaList = payload.mediaUrls?.length
-                        ? payload.mediaUrls
-                        : payload.mediaUrl ? [payload.mediaUrl] : [];
-                    // 流式中间块
-                    if (info.kind === "block") {
-                        if (replyText.trim()) {
-                            emitter.emit({
-                                msgId: replyMsgId,
-                                from: emitter.botClientId,
-                                to: targetId,
-                                content: replyText,
-                                timestamp: Date.now(),
-                                replyToMsgId: msg.messageId,
-                                kind: "stream_chunk",
-                            });
-                        }
-                        return;
-                    }
-                    if (!replyText && !mediaList.length)
-                        return;
-                    // 发送媒体文件 — 同时上传到云端获取公网 URL
-                    if (mediaList.length > 0) {
-                        const files = await mediaUrlsToFiles(mediaList, log);
-                        // 尝试将文件上传获取公网链接
-                        const publicUrls = [];
-                        const storageConfig = {
-                            apiKey: effectiveApiKey,
-                        };
-                        for (const mediaUrl of mediaList) {
-                            try {
-                                // 本地文件路径（file:// 或绝对路径）
-                                const localPath = mediaUrl.startsWith("file://")
-                                    ? mediaUrl.slice(7)
-                                    : mediaUrl;
-                                if (localPath.startsWith("/") || localPath.match(/^[A-Za-z]:\\/)) {
-                                    const { existsSync } = await import("node:fs");
-                                    if (existsSync(localPath)) {
-                                        const result = await uploadFileToCos(localPath, storageConfig);
-                                        publicUrls.push(result.url || '');
-                                        log?.info(`[${CHANNEL_KEY}] Uploaded to cloud: ${localPath} → ${result.url}`);
-                                    }
-                                }
-                            }
-                            catch (uploadErr) {
-                                log?.warn(`[${CHANNEL_KEY}] Cloud upload failed for ${mediaUrl}: ${uploadErr}`);
-                            }
-                        }
-                        // 将公网 URL 追加到回复文本中（Markdown 链接格式）
-                        let enrichedText = replyText;
-                        if (publicUrls.length > 0) {
-                            const urlSection = publicUrls
-                                .map((url, i) => {
-                                // 从 URL 中提取文件名
-                                const match = url.match(/filePath=([^&]+)/);
-                                const filePath = match ? decodeURIComponent(match[1]) : "";
-                                const fileName = filePath.split("/").pop() || `file${publicUrls.length > 1 ? ` (${i + 1})` : ""}`;
-                                return `📎 [${fileName}](${url})`;
-                            })
-                                .join("\n");
-                            enrichedText = enrichedText
-                                ? `${enrichedText}\n\n${urlSection}`
-                                : urlSection;
-                        }
-                        if (files.length > 0) {
-                            emitter.sendFiles(targetId, enrichedText, files, msg.messageId);
-                            return;
-                        }
-                        // 文件无法直接发送，但有公网 URL，用文本方式发送链接
-                        if (enrichedText.trim()) {
-                            emitter.sendReply(targetId, enrichedText, msg.messageId);
-                            return;
-                        }
-                    }
-                    // 发送文本回复
-                    if (replyText.trim()) {
-                        emitter.sendReply(targetId, replyText, msg.messageId);
-                    }
-                },
-                onReplyStart: () => {
-                    emitter.emit({
-                        msgId: replyMsgId,
-                        from: emitter.botClientId,
-                        to: targetId,
-                        content: "",
-                        timestamp: Date.now(),
-                        kind: "typing_start",
-                    });
-                },
-                onIdle: () => {
-                    if (idleSent)
-                        return;
-                    idleSent = true;
-                    emitter.emit({
-                        msgId: replyMsgId,
-                        from: emitter.botClientId,
-                        to: targetId,
-                        content: "",
-                        timestamp: Date.now(),
-                        replyToMsgId: msg.messageId,
-                        kind: "typing_stop",
-                    });
-                },
-                onError: (err, info) => {
-                    log?.error(`[${CHANNEL_KEY}] ${info.kind} reply failed: ${String(err)}`);
-                },
-            },
-            replyOptions: { onModelSelected, disableBlockStreaming: false },
-        });
+        // 7. 构建流式 dispatcher
+        const { dispatcher, replyOptions: streamReplyOptions, hasEmittedContent, } = createStreamReplyConfig({
+            emitter: boundEmitter,
+            targetId,
+            replyMsgId,
+            originalMsgId: msg.messageId,
+            log,
+            effectiveApiKey,
+            typingAlreadyStarted: true,
+            agentId: effectiveAgentId,
+        }, { ...prefixOptions, onModelSelected }, signalCtx);
+        // 8. 分发给 AI 引擎（真流式）。abort 由 openclaw fast-abort 处理，sink 层
+        //    把英文回执汉化；此处仅兜底自身抛错。
         try {
-            await dispatchPromise;
+            await pluginRuntime.channel.reply.withReplyDispatcher({
+                dispatcher,
+                run: () => pluginRuntime.channel.reply.dispatchReplyFromConfig({
+                    ctx: ctxPayload,
+                    cfg: currentCfg,
+                    dispatcher,
+                    replyOptions: streamReplyOptions,
+                }),
+            });
         }
         catch (err) {
             const errMsg = err instanceof Error ? err.message : String(err);
             log?.error(`[${CHANNEL_KEY}] Dispatch error: ${errMsg}`);
-            // 只发送通用提示，不暴露内部错误细节给用户
-            emitter.sendReply(targetId, '抱歉，处理您的消息时出现了问题，请稍后重试', msg.messageId);
-        }
-        finally {
-            if (timeoutId) {
-                clearTimeout(timeoutId);
-                timeoutId = null;
-            }
-            if (timeoutFired) {
-                log?.info(`[${CHANNEL_KEY}] Note: dispatch completed after timeout warning (${hasResponse ? 'with' : 'without'} response)`);
+            // 已推过可见内容时不再追加错误文案，避免打断阅读。
+            if (!hasEmittedContent()) {
+                emitter.sendReply(targetId, '抱歉，处理您的消息时出现了问题，请稍后重试', msg.messageId, effectiveAgentId);
             }
         }
     };
@@ -342,13 +276,28 @@ export function createInboundHandler(account, emitter, log) {
 // ============================================================
 // 权限检查
 // ============================================================
+/**
+ * 检查发送方是否有权限向 Bot 发送消息（命令授权检查）。
+ *
+ * 策略优先级（从高到低）：
+ * 1. `dmPolicy === "disabled"` → 拒绝所有消息（Bot 已关闭私聊）
+ * 2. `dmPolicy === "open"`     → 允许所有消息（Bot 对所有人开放）
+ * 3. `allowFrom` 为空          → 拒绝（未配置白名单视为不允许任何人）
+ * 4. `allowFrom` 含 `"*"`     → 允许所有人（通配符白名单）
+ * 5. `allowFrom` 含发送方 ID  → 允许（精确匹配，大小写不敏感）
+ * 6. 以上均不满足              → 拒绝
+ *
+ * @param allowFrom - 允许发送消息的用户 ID 白名单（支持 "*" 通配符）
+ * @param dmPolicy  - 私聊策略（"disabled" | "open" | "allowlist"）
+ * @param senderId  - 发送方用户 ID（uin）
+ * @returns `true` = 有权限，`false` = 无权限
+ */
 function checkAuth(allowFrom, dmPolicy, senderId) {
-    if (dmPolicy === "disabled")
+    if (dmPolicy === 'disabled')
         return false;
-    if (dmPolicy === "open")
+    if (dmPolicy === 'open')
         return true;
     if (!allowFrom || allowFrom.length === 0)
         return false;
-    return allowFrom.includes("*") || allowFrom.some((id) => id.toLowerCase() === senderId.toLowerCase());
+    return allowFrom.includes('*') || allowFrom.some((id) => id.toLowerCase() === senderId.toLowerCase());
 }
-//# sourceMappingURL=inbound.js.map

package/dist/src/media.js

@@ -84,4 +84,3 @@ export async function mediaUrlsToFiles(urls, log) {
     }
     return files;
 }
-//# sourceMappingURL=media.js.map

package/dist/src/messaging.js

@@ -0,0 +1,65 @@
+import { CHANNEL_KEY } from './config.js';
+/**
+ * 将任意格式的消息目标地址规范化为内部标准格式（`user:xxx` 或 `channel:xxx`）。
+ *
+ * 支持的输入格式：
+ * - `lightclawbot:dm:123`   → `user:123`     （带通道前缀的私聊）
+ * - `lightclawbot:group:456` → `channel:456`  （带通道前缀的群聊）
+ * - `dm:123`                → `user:123`     （私聊简写）
+ * - `group:456`             → `channel:456`  （群聊简写）
+ * - `user:123`              → `user:123`     （已是标准格式，原样返回）
+ * - `channel:456`           → `channel:456`  （已是标准格式，原样返回）
+ * - `123`                   → `user:123`     （纯数字 ID，默认视为私聊）
+ *
+ * @param target - 原始目标地址字符串
+ * @returns 规范化后的目标地址，若输入为空则返回 `undefined`
+ */
+export function normalizeTarget(target) {
+    // 剥离通道名前缀（如 "lightclawbot:"），使后续逻辑只处理纯地址部分
+    const cleaned = target.replace(new RegExp(`^${CHANNEL_KEY}:`, 'i'), '');
+    // 输入为空或仅含通道前缀时，无法确定目标，返回 undefined
+    if (!cleaned)
+        return undefined;
+    // dm:xxx → user:xxx（私聊）
+    if (cleaned.startsWith('dm:')) {
+        return `user:${cleaned.slice(3)}`;
+    }
+    // group:xxx → channel:xxx（群聊）
+    if (cleaned.startsWith('group:')) {
+        return `channel:${cleaned.slice(6)}`;
+    }
+    // 已经是标准格式 user:xxx / channel:xxx，无需转换，原样返回
+    if (/^(user|channel):/i.test(cleaned)) {
+        return cleaned;
+    }
+    // 其余情况视为纯 ID（如纯数字），默认当作私聊目标
+    return `user:${cleaned}`;
+}
+/**
+ * 判断给定字符串是否看起来像一个合法的消息目标 ID。
+ *
+ * 优先使用已规范化的 `normalized` 值进行判断；若未提供，则直接使用原始 `id`。
+ *
+ * 以下格式均被认为是合法 ID：
+ * - `user:xxx` / `channel:xxx`  — 内部标准前缀格式
+ * - `dm:123` / `group:123`      — LightClaw 自有格式（纯数字部分）
+ * - `123`                       — 纯数字 ID
+ *
+ * @param id         - 原始目标地址字符串
+ * @param normalized - 可选，已经过 `normalizeTarget` 处理的规范化地址，优先使用
+ * @returns 若字符串符合合法 ID 格式则返回 `true`，否则返回 `false`
+ */
+export function looksLikeId(id, normalized) {
+    // 优先使用规范化值，去除首尾空白
+    const value = (normalized ?? id).trim();
+    // 空字符串不是合法 ID
+    if (!value)
+        return false;
+    // 匹配内部标准前缀格式：user:xxx 或 channel:xxx
+    if (/^(user|channel):/i.test(value))
+        return true;
+    // 剥离通道前缀后，判断是否符合 LightClaw 自有格式
+    const cleaned = value.replace(new RegExp(`^${CHANNEL_KEY}:`, 'i'), '');
+    // dm:<数字> 或 group:<数字> 格式，或纯数字 ID
+    return /^(dm|group):\d+/.test(cleaned) || /^\d+$/.test(cleaned);
+}