lightclawbot 1.2.0-beta.0 → 1.2.0-beta.2

package/dist/index.js

@@ -2,19 +2,18 @@
  * LightClaw — 主入口文件
  *
  * 使用 OpenClaw SDK 标准的 defineChannelPluginEntry 工厂函数替代手动创建 plugin 对象，
- * 遵循 Discord/Slack 等官方 channel 插件的标准 index.ts 模式。
  *
  * 该文件定义了 LightClawBot channel plugin 的入口配置，包括插件ID、名称、描述、
  * 核心插件实现、运行时设置和工具注册等功能。
  */
 // 导入 OpenClaw SDK 的核心功能
-import { defineChannelPluginEntry } from "openclaw/plugin-sdk/core";
+import { defineChannelPluginEntry } from 'openclaw/plugin-sdk/core';
 // 导入本地模块
-import { lightclawPlugin } from "./src/channel.js"; // 核心插件实现
-import { setLightclawRuntime } from "./src/runtime.js"; // 运行时配置设置函数
-import { registerLightclawTools } from "./src/tools.js"; // 工具注册函数
+import { lightclawPlugin } from './src/channel.js'; // 核心插件实现
+import { setLightclawRuntime } from './src/runtime.js'; // 运行时配置设置函数
+import { registerLightclawTools } from './src/tools.js'; // 工具注册函数
 // 导出运行时设置函数，供外部使用
-export { setLightclawRuntime } from "./src/runtime.js";
+export { setLightclawRuntime } from './src/runtime.js';
 /**
  * 创建并配置 LightClawBot channel plugin 入口
  *
@@ -25,11 +24,11 @@ export { setLightclawRuntime } from "./src/runtime.js";
  */
 const entry = defineChannelPluginEntry({
     // 插件唯一标识符，用于在系统中识别该插件
-    id: "lightclawbot",
+    id: 'lightclawbot',
     // 插件显示名称，在UI中展示给用户
-    name: "LightClawBot",
+    name: 'LightClawBot',
     // 插件功能描述，说明插件的主要用途
-    description: "Channel plugin for LightClawBot",
+    description: 'Channel plugin for LightClawBot',
     // 核心插件实现，包含消息处理、事件响应等核心逻辑
     plugin: lightclawPlugin,
     // 运行时设置函数，用于配置插件运行时的环境和参数

package/dist/src/channel.js

@@ -1,313 +1,182 @@
 /**
- * LightClaw — ChannelPlugin 主定义文件
+ * LightClaw — ChannelPlugin 主定义
  *
- * 使用 OpenClaw SDK 标准的 createChatChannelPlugin 构建器创建聊天频道插件，
+ * 使用 SDK 标准的 createChatChannelPlugin 构建器，
+ * 参照官方 Discord/Slack channel 实现。
  *
- * 主要结构组成：
- *   base:     基础配置 - 来自 shared.ts 的 createLightclawPluginBase + 扩展字段
- *   messaging: 消息目标解析 - 处理消息发送目标的标准化和验证
- *   status:   状态管理 - 插件运行状态监控和状态面板构建
- *   gateway:  Gateway 生命周期 - WebSocket 连接管理和账户生命周期
- *   outbound: 出站消息适配器 - 消息发送和媒体文件处理
- *
- * 该插件实现了与 AI 助手服务的 WebSocket 通信、消息收发、状态管理等核心功能。
+ * 结构：
+ *   base:     来自 shared.ts 的 createLightclawPluginBase + 扩展字段
+ *   security: DM 安全策略
+ *   outbound: 出站消息适配器
  */
 import { createChatChannelPlugin } from 'openclaw/plugin-sdk/core';
-// 导入工具函数和常量
 import { chunkText, defaultAccountId } from './utils/index.js';
 import { CHANNEL_KEY, DEFAULT_ACCOUNT_ID, TEXT_CHUNK_LIMIT } from './config.js';
-// 导入功能模块
-import { sendText, sendMedia } from './outbound.js'; // 出站消息发送
-import { startGateway } from './gateway.js'; // WebSocket Gateway 启动
-import { createLightclawPluginBase } from './shared.js'; // 基础插件配置
-import { lightclawSetupAdapter } from './setup-core.js'; // Setup 适配器
-import { normalizeTarget, looksLikeId } from './messaging.js'; // 消息目标处理
-/**
- * LightClaw 主插件实例
- *
- * 使用 createChatChannelPlugin 工厂函数创建类型安全的 ChannelPlugin 实例，
- * 泛型参数 ResolvedAssistantAccount 指定了账户数据的类型结构。
- *
- * @type {ChannelPlugin<ResolvedAssistantAccount>}
- */
+import { sendText, sendMedia } from './outbound.js';
+import { startGateway } from './gateway.js';
+import { createLightclawPluginBase } from './shared.js';
+import { lightclawSetupAdapter } from './setup-core.js';
+import { normalizeTarget, looksLikeId } from './messaging.js';
+// ============================================================
+// ChannelPlugin 定义（使用 createChatChannelPlugin）
+// ============================================================
 export const lightclawPlugin = createChatChannelPlugin({
-    // ==================== 基础配置 ====================
     base: {
         // ---- 来自 shared.ts 的基础定义 ----
-        // 使用扩展运算符合并基础配置和 setup 适配器
         ...createLightclawPluginBase({
-            setup: lightclawSetupAdapter, // Setup 阶段使用的适配器
+            setup: lightclawSetupAdapter,
         }),
-        // ---- 消息目标解析配置 ----
+        // ---- 消息目标解析 ----
         messaging: {
-            /**
-             * 目标标准化函数
-             * 对原始目标字符串进行标准化处理：去除空格、统一格式、转换编码等
-             *
-             * @param {string} target - 原始目标字符串
-             * @returns {string} 标准化后的目标字符串
-             */
+            // 对原始目标字符串进行标准化处理，如去除空格、统一格式、转换编码等，返回标准化后的字符串
             normalizeTarget: (target) => {
                 return normalizeTarget(target);
             },
-            /** 目标解析器配置 */
             targetResolver: {
-                /**
-                 * ID 格式检测函数
-                 * 判断一个原始字符串是否看起来像一个有效的 ID 格式
-                 * 用于在完整解析前快速分流处理逻辑，提高性能
-                 *
-                 * @param {string} id - 待检测的字符串
-                 * @param {string} [normalized] - 可选的标准化的字符串
-                 * @returns {boolean} 是否看起来像 ID 格式
-                 */
+                // 判断一个原始字符串是否看起来像一个 ID，用于在解析前快速分流处理逻辑
                 looksLikeId: (id, normalized) => {
                     return looksLikeId(id, normalized);
                 },
-                /**
-                 * 目标格式提示文本
-                 * 显示在 CLI 帮助信息中，指导用户正确的目标格式
-                 */
+                /** 目标格式提示文本，显示在 CLI 帮助信息中 */
                 hint: `user:<userId> or channel:<groupId>`,
             },
         },
-        // ---- 状态面板配置 ----
+        // ---- 状态面板 ----
         status: {
-            /** 默认运行时状态配置 */
             defaultRuntime: {
-                accountId: DEFAULT_ACCOUNT_ID, // 默认账户ID
-                running: false, // 运行状态：未运行
-                connected: false, // 连接状态：未连接
-                lastConnectedAt: null, // 最后连接时间：null
-                lastError: null, // 最后错误信息：null
+                accountId: DEFAULT_ACCOUNT_ID,
+                running: false,
+                connected: false,
+                lastConnectedAt: null,
+                lastError: null,
             },
-            /**
-             * 构建频道摘要信息
-             * 根据快照数据生成频道级别的状态摘要
-             *
-             * @param {Object} param0 - 参数对象
-             * @param {Object} param0.snapshot - 状态快照数据
-             * @returns {Object} 频道摘要信息
-             */
             buildChannelSummary: ({ snapshot }) => ({
-                configured: snapshot.configured ?? false, // 是否已配置
-                running: snapshot.running ?? false, // 是否正在运行
-                connected: snapshot.connected ?? false, // 是否已连接
-                lastConnectedAt: snapshot.lastConnectedAt ?? null, // 最后连接时间
-                lastError: snapshot.lastError ?? null, // 最后错误信息
+                configured: snapshot.configured ?? false,
+                running: snapshot.running ?? false,
+                connected: snapshot.connected ?? false,
+                lastConnectedAt: snapshot.lastConnectedAt ?? null,
+                lastError: snapshot.lastError ?? null,
             }),
-            /**
-             * 构建账户快照信息
-             * 根据账户、运行时和配置数据生成账户级别的状态快照
-             *
-             * @param {Object} param0 - 参数对象
-             * @param {ResolvedAssistantAccount} param0.account - 账户信息
-             * @param {Object} param0.runtime - 运行时状态
-             * @param {OpenClawConfig} param0.cfg - 配置信息
-             * @returns {Object} 账户快照信息
-             */
             buildAccountSnapshot: ({ account, runtime, cfg }) => ({
-                accountId: account?.accountId ?? defaultAccountId(cfg), // 账户ID，优先使用账户的ID
-                name: account?.name, // 账户名称
-                enabled: account?.enabled ?? false, // 是否启用
-                configured: Boolean(account?.apiKey), // 是否已配置（有API密钥）
-                running: runtime?.running ?? false, // 是否正在运行
-                connected: runtime?.connected ?? false, // 是否已连接
-                lastConnectedAt: runtime?.lastConnectedAt ?? null, // 最后连接时间
-                lastError: runtime?.lastError ?? null, // 最后错误信息
+                accountId: account?.accountId ?? defaultAccountId(cfg),
+                name: account?.name,
+                enabled: account?.enabled ?? false,
+                configured: Boolean(account?.apiKey),
+                running: runtime?.running ?? false,
+                connected: runtime?.connected ?? false,
+                lastConnectedAt: runtime?.lastConnectedAt ?? null,
+                lastError: runtime?.lastError ?? null,
             }),
         },
-        // ---- Gateway 生命周期管理（核心功能） ----
+        // ---- Gateway 生命周期（核心！） ----
         gateway: {
             /**
-             * 启动账户
-             * 建立 WebSocket 长连接到 AI 助手服务器
-             * OpenClaw 框架会在加载配置后为每个启用的账户调用此方法
-             *
-             * @async
-             * @param {Object} ctx - 上下文对象
-             * @param {ResolvedAssistantAccount} ctx.account - 账户信息
-             * @param {AbortSignal} ctx.abortSignal - 中止信号，用于取消操作
-             * @param {Object} ctx.log - 日志记录器
-             * @param {OpenClawConfig} ctx.cfg - 配置信息
-             * @param {Function} ctx.setStatus - 状态设置函数
-             * @param {Function} ctx.getStatus - 状态获取函数
+             * 启动账户：建立 WS 长连接到 AI 助手 Server
+             * OpenClaw 会在加载配置后为每个 enabled 的账户调用此方法
              */
             startAccount: async (ctx) => {
-                const { account, abortSignal, log, cfg, accountId } = ctx;
-                // 记录启动日志
-                log?.info(`[${CHANNEL_KEY}:${accountId}] Starting gateway...`);
+                const { account, abortSignal, log, cfg } = ctx;
+                log?.info(`[${CHANNEL_KEY}:${account.accountId}] Starting gateway...`);
                 // 启动并维持一个 Socket.IO Gateway 实例
                 await startGateway({
-                    account, // 账户信息
-                    abortSignal, // 中止信号
-                    cfg, // 配置信息
-                    log, // 日志记录器
-                    /**
-                     * WebSocket 连接就绪回调
-                     * 当 WebSocket 连接成功建立时调用
-                     */
+                    account,
+                    abortSignal,
+                    cfg,
+                    log,
+                    /** WS 连接就绪回调 */
                     onReady: () => {
-                        log?.info(`[${CHANNEL_KEY}:${accountId}] Gateway ready: WS connected`);
+                        log?.info(`[${CHANNEL_KEY}:${account.accountId}] Gateway ready: WS connected`);
                         const now = Date.now();
-                        // 更新运行时状态
                         ctx.setStatus({
-                            ...ctx.getStatus(), // 保留现有状态
-                            running: true, // 设置为运行中
-                            connected: true, // 设置为已连接
-                            lastConnectedAt: now, // 记录最后连接时间
+                            ...ctx.getStatus(),
+                            running: true,
+                            connected: true,
+                            lastConnectedAt: now,
                             // 连接建立时即设置 lastEventAt，作为 health-monitor stale-socket 检测的初始基准
-                            lastEventAt: now, // 最后事件时间
+                            lastEventAt: now,
                         });
                     },
-                    /**
-                     * WebSocket 连接断开回调
-                     * 当 WebSocket 连接断开时调用
-                     */
+                    /** WS 连接断开回调 */
                     onDisconnect: () => {
-                        log?.info(`[${CHANNEL_KEY}:${accountId}] Gateway ready: WS disconnect`);
-                        // 更新连接状态为断开
+                        log?.info(`[${CHANNEL_KEY}:${account.accountId}] Gateway ready: WS disconnect`);
                         ctx.setStatus({
-                            ...ctx.getStatus(), // 保留现有状态
-                            connected: false, // 设置为未连接
+                            ...ctx.getStatus(),
+                            connected: false,
                         });
                     },
-                    /**
-                     * 错误回调
-                     * 当发生错误时调用，记录错误信息但不中断重连逻辑
-                     * 重连逻辑由 gateway 内部处理
-                     *
-                     * @param {Error} error - 错误对象
-                     */
+                    /** 错误回调：记录错误信息，不中断重连逻辑（由 gateway 内部处理） */
                     onError: (error) => {
-                        log?.error(`[${CHANNEL_KEY}:${accountId}] Gateway error: ${error.message}`);
-                        // 记录错误信息
+                        log?.error(`[${CHANNEL_KEY}:${account.accountId}] Gateway error: ${error.message}`);
                         ctx.setStatus({
-                            ...ctx.getStatus(), // 保留现有状态
-                            lastError: error.message, // 记录错误消息
+                            ...ctx.getStatus(),
+                            lastError: error.message,
                         });
                     },
                     /**
-                     * 入站事件回调
-                     * 每次收到消息时调用，用于：
-                     * - 刷新 lastEventAt 和 lastInboundAt 时间戳
-                     * - 通知框架 health-monitor 该连接仍处于活跃状态
-                     * - 防止因长时间无活动而被判定为僵死连接
+                     * 入站事件回调：每次收到消息时调用。
+                     * 刷新 lastEventAt 和 lastInboundAt，
+                     * 通知框架 health-monitor 该连接仍处于活跃状态。
                      */
                     onEvent: () => {
-                        log?.info(`[${CHANNEL_KEY}:${accountId}] Gateway Ready: WS message enter`);
-                        // 更新事件时间戳
+                        log?.info(`[${CHANNEL_KEY}:${account.accountId}] Gateway Ready: WS message enter`);
                         ctx.setStatus({
-                            ...ctx.getStatus(), // 保留现有状态
-                            lastEventAt: Date.now(), // 最后事件时间
-                            lastInboundAt: Date.now(), // 最后入站消息时间
+                            ...ctx.getStatus(),
+                            lastEventAt: Date.now(),
+                            lastInboundAt: Date.now(),
                         });
                     },
                 });
             },
-            /**
-             * 登出账户
-             * 清除账户的凭证信息（如 API 密钥）
-             *
-             * @async
-             * @param {Object} param0 - 参数对象
-             * @param {string} param0.accountId - 账户ID
-             * @param {OpenClawConfig} param0.cfg - 配置信息
-             * @returns {Promise<{ok: boolean, cleared: boolean}>} 操作结果
-             */
+            /** 登出账户：清除凭证 */
             logoutAccount: async ({ accountId, cfg }) => {
-                // 创建配置副本以避免修改原始配置
                 const nextCfg = { ...cfg };
-                // 获取当前 channel 的配置节
                 const section = nextCfg.channels?.[CHANNEL_KEY];
-                let cleared = false; // 清理标志
+                let cleared = false;
                 if (section) {
-                    // 处理默认账户的 API 密钥
                     if (accountId === DEFAULT_ACCOUNT_ID && section.apiKeys) {
-                        delete section.apiKeys; // 删除默认账户的 API 密钥
-                        cleared = true; // 标记为已清理
+                        delete section.apiKeys;
+                        cleared = true;
                     }
-                    // 处理特定账户的 API 密钥
                     const accounts = section.accounts;
                     if (accounts?.[accountId]?.apiKeys) {
-                        delete accounts[accountId].apiKeys; // 删除指定账户的 API 密钥
-                        cleared = true; // 标记为已清理
+                        delete accounts[accountId].apiKeys;
+                        cleared = true;
                     }
                 }
-                // 返回操作结果
                 return { ok: true, cleared };
             },
         },
     },
-    // ==================== 出站消息适配器 ====================
+    // ---- 出站消息适配器 ----
     outbound: {
-        // 基础出站配置
         base: {
-            deliveryMode: 'direct', // 交付模式：直接交付
-            chunker: chunkText, // 文本分块处理器
-            chunkerMode: 'markdown', // 分块模式：Markdown
-            textChunkLimit: TEXT_CHUNK_LIMIT, // 文本分块限制大小
-            /**
-             * 目标解析函数
-             * 解析消息发送的目标地址
-             *
-             * @param {Object} param0 - 参数对象
-             * @param {string} param0.to - 显式指定的目标
-             * @param {string[]} param0.allowFrom - 允许的来源列表
-             * @param {string} param0.mode - 模式（'direct' 或 'implicit'）
-             * @returns {Object} 解析结果
-             */
+            deliveryMode: 'direct',
+            chunker: chunkText,
+            chunkerMode: 'markdown',
+            textChunkLimit: TEXT_CHUNK_LIMIT,
             resolveTarget: ({ to, allowFrom, mode }) => {
-                // 优先使用显式指定的目标地址
+                // 优先使用显式 to；implicit 模式下回退到 allowFrom 第一个非通配符条目
                 const effectiveTo = to?.trim();
                 if (effectiveTo) {
                     return { ok: true, to: effectiveTo };
                 }
-                // implicit 模式下回退到 allowFrom 第一个非通配符条目
                 if (mode === 'implicit' && allowFrom && allowFrom.length > 0) {
                     const candidate = allowFrom.find((entry) => entry && entry !== '*');
                     if (candidate) {
                         return { ok: true, to: candidate };
                     }
                 }
-                // 没有找到有效目标，返回错误
                 return {
                     ok: false,
                     error: new Error(`No delivery target for ${CHANNEL_KEY}. Specify a target with --to or configure allowFrom.`),
                 };
             },
         },
-        // 附加结果处理
         attachedResults: {
-            channel: CHANNEL_KEY, // 频道标识
-            /**
-             * 发送文本消息
-             *
-             * @async
-             * @param {Object} param0 - 参数对象
-             * @param {string} param0.to - 目标地址
-             * @param {string} param0.text - 文本内容
-             * @param {string} param0.accountId - 账户ID
-             * @param {string} param0.replyToId - 回复消息ID
-             * @param {OpenClawConfig} param0.cfg - 配置信息
-             * @returns {Promise<any>} 发送结果
-             */
+            channel: CHANNEL_KEY,
             sendText: async ({ to, text, accountId, replyToId, cfg }) => {
                 return sendText({ to, text, accountId, replyToId, cfg });
             },
-            /**
-             * 发送媒体消息
-             *
-             * @async
-             * @param {Object} param0 - 参数对象
-             * @param {string} param0.to - 目标地址
-             * @param {string} param0.text - 文本内容
-             * @param {string} param0.mediaUrl - 媒体文件URL
-             * @param {string} param0.accountId - 账户ID
-             * @param {string} param0.replyToId - 回复消息ID
-             * @param {OpenClawConfig} param0.cfg - 配置信息
-             * @returns {Promise<any>} 发送结果
-             */
             sendMedia: async ({ to, text, mediaUrl, accountId, replyToId, cfg }) => {
                 return sendMedia({ to, text, mediaUrl, accountId, replyToId, cfg });
             },

package/dist/src/config.js

@@ -145,6 +145,29 @@ export const API_PATH_DOWNLOAD = '/drive/preview';
 export const EVENT_MESSAGE_PRIVATE = 'message:private';
 export const EVENT_HISTORY_REQUEST = 'message:history:request';
 export const EVENT_HISTORY_RESPONSE = 'message:history:response';
+export const EVENT_SESSIONS_REQUEST = 'sessions:request';
+export const EVENT_SESSIONS_RESPONSE = 'sessions:response';
+// ============================================================
+// 文件下载信令（kind 字段值）
+// ============================================================
+// 业务数据统一放入消息的 extra.transferData 字段，不污染顶层协议。
+/**
+ * 文件下载信令统一 kind。
+ *
+ * 所有下载相关消息（请求 / 就绪 / URL / 错误）都使用同一 kind，
+ * 通过 `extra.transferData.status` 区分四种状态：
+ 
+ */
+export const KIND_FILE_DOWNLOAD = 'file:download';
+/** 下载信令 status 枚举（对应旧协议的四个 kind） */
+export const FILE_DOWNLOAD_STATUS = {
+    REQ: 'download_req',
+    READY: 'download_ready',
+    URL: 'download_url',
+    ERROR: 'download_error',
+};
+/** localfile:// URI 前缀（AI 生成文件 / upload-tool 标识，前端据此发起下载信令） */
+export const LOCALFILE_SCHEME = 'localfile://';
 // ============================================================
 // 超时 & 限制配置
 // ============================================================

package/dist/src/file-storage.js

@@ -56,13 +56,13 @@ export async function uploadFileToCos(localPath, config = {}, customFileName) {
         });
         if (!response.ok) {
             const text = await response.text().catch(() => "");
-            throw new Error(`Upload failed (HTTP ${response.status}): ${text}`);
+            throw new Error(`Upload failed (HTTP ${response.ok} : ${response.status}): ${text}`);
         }
         const result = (await response.json());
         if (result.code === 0 && result.data?.uploaded) {
             return { url: `${COS_BASE_URL}${API_PATH_DOWNLOAD}?filePath=${filePath}`, filePath, isUploaded: true };
         }
-        throw new Error(`Upload failed (HTTP ${response.status}): ${result.data}`);
+        throw new Error(`Upload failed other (HTTP ${response.status}): ${result.data}`);
     }
     finally {
         clearTimeout(timeoutId);

package/dist/src/gateway.js

@@ -95,25 +95,26 @@ async function resolveBotClientId(apiKey, log) {
  */
 export async function startGateway(ctx) {
     const { account, abortSignal, onReady, onDisconnect, onEvent, log } = ctx;
+    const prefix = `[${CHANNEL_KEY}:${account.accountId}]`;
     // 判断是否存在有效的apikey
     if (!account.apiKey) {
-        log?.error(`[${CHANNEL_KEY}:${account.accountId}] apiKey is not exist`);
-        throw new Error(`[${CHANNEL_KEY}] Missing apiKey in config`);
+        log?.error(`${prefix} apiKey is not exist`);
+        throw new Error(`${prefix} Missing apiKey in config`);
     }
     // 判断 accountId 在缓存中是否存在，避免同一账号同时持有多个 WebSocket 连接
     // 防重入：如果同一 accountId 已有活跃 gateway，先销毁旧实例再创建新实例
     const existingCleanup = activeGateways.get(account.accountId);
     if (existingCleanup) {
-        log?.warn(`[${CHANNEL_KEY}:${account.accountId}] Destroying existing gateway for account ${account.accountId} before creating new one`);
+        log?.warn(`${prefix} Destroying existing gateway for account ${account.accountId} before creating new one`);
         existingCleanup();
     }
     // 通过 HTTP 接口获取 Bot 的 clientId（botClientId）
     // 新配置格式：accountId 即为 uin，apiKey 与 uin 一一对应，直接构建映射表
-    log?.info(`[${CHANNEL_KEY}: ${account.accountId}] Resolving botClientId for account ${account.accountId}...`);
+    log?.info(`${prefix} Resolving botClientId for account ${account.accountId}...`);
     const { botClientId, ticket } = await resolveBotClientId(account.apiKey, log);
     // 构建 uin→apiKey 映射表（新格式下每个 account 只有一条记录）
     const apiKeyMap = new Map([[account.accountId, account.apiKey]]);
-    log?.info(`[${CHANNEL_KEY}] Bot clientId: ${botClientId}, uin=${account.accountId} → apiKey=***${account.apiKey.slice(-4)}`);
+    log?.info(`${prefix} Bot clientId: ${botClientId}, uin=${account.accountId} → apiKey=***${account.apiKey.slice(-4)}`);
     // 将映射表写入全局 config 模块，供 inbound 处理时按 uin 查找对应 apiKey
     setApiKeyMap(apiKeyMap, account.apiKey);
     /** Gateway 是否已被 abort（用于终止消息处理循环） */
@@ -130,7 +131,6 @@ export async function startGateway(ctx) {
      * 底层 emit：将 PrivateMessageData 通过 ReliableEmitter 发送给客户端。
      * - 统一对 content 字段执行 formatCosUrls（将内部 COS 路径转换为公网 URL）
      * - 所有消息都走可靠发送队列，入队即视为"发送成功"，实际 ACK 由 ReliableEmitter 保证
-     * - 需求约束：所有出站消息必须携带 agentId。调用方未显式指定时，回退到包装 emitter 绑定的 agentId。
      */
     const emit = (data) => {
         // 完整发送日志由 ReliableEmitter 打印（含 idempotencyKey）
@@ -147,8 +147,7 @@ export async function startGateway(ctx) {
      * @param targetId     - 接收方用户 ID
      * @param text         - 回复文本内容
      * @param replyToMsgId - 可选，回复对应的原始消息 ID（用于前端展示引用关系）
-     * @param agentId      - 可选，指定此条出站消息归属的 Agent ID；
-     *                       缺省时由上层包装 emitter 注入，所有出站消息都将携带 agentId。
+     * @param agentId      - 可选，目标 Agent ID
      */
     const sendReply = (targetId, text, replyToMsgId, agentId) => {
         log?.info(`[${CHANNEL_KEY}] sendReply: ${text} to ${targetId} (replyTo: ${replyToMsgId || 'none'})`);
@@ -170,7 +169,7 @@ export async function startGateway(ctx) {
      * @param text         - 消息文本（可为空字符串）
      * @param files        - 文件附件列表（{name, mimeType, bytes} 格式）
      * @param replyToMsgId - 可选，回复对应的原始消息 ID
-     * @param agentId      - 可选，指定此条出站消息归属的 Agent ID。
+     * @param agentId      - 可选，目标 Agent ID
      */
     const sendFiles = (targetId, text, files, replyToMsgId, agentId) => {
         return emit({
@@ -202,7 +201,7 @@ export async function startGateway(ctx) {
             catch (err) {
                 log?.error(`[${CHANNEL_KEY}] Message handler error: ${err}`);
                 try {
-                    emitter.sendReply(msg.senderId, "消息处理异常，请稍后重试。", msg.messageId, msg.agentId);
+                    emitter.sendReply(msg.senderId, "消息处理异常，请稍后重试。", msg.messageId);
                     emitter.emit({
                         msgId: generateMsgId(),
                         from: emitter.botClientId,
@@ -256,7 +255,7 @@ export async function startGateway(ctx) {
     // 使用原生 WebSocket 封装层建立连接
     const socket = new NativeSocketClient(WS_URL, {
         // 认证：ticket 作为 URL query 参数，替代 Authorization header
-        path: `${SOCKET_PATH}${ticketQuery}`,
+        path: `${SOCKET_PATH}${ticketQuery}&enableMultiLogin=false`,
         // 注入日志对象，便于 NativeSocketClient 内部打印连接/重连/错误等诊断信息
         log,
         logPrefix: `[${CHANNEL_KEY}:${account.accountId}:NativeSocket]`,

package/dist/src/inbound.js

@@ -7,7 +7,7 @@
  *   - 并发由 session 写锁 + followup queue 保证；
  *   - /stop 及自然语言 abort 由 tryFastAbortFromMessage 统一处理并递归 kill subagent。
  */
-import { emitSignal } from './types.js';
+import { emitSignal } from './utils/common.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';
@@ -77,24 +77,7 @@ export function createInboundHandler(account, emitter, log) {
         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,
-        };
+        const signalCtx = { emitter, targetId, replyMsgId, originalMsgId: msg.messageId, agentId: resolvedAgentId };
         emitSignal(signalCtx, 'typing_start');
         // 3. 处理文件附件（files[] → 本地存储 + 公网 URL）
         const localMediaPaths = [];
@@ -241,14 +224,13 @@ export function createInboundHandler(account, emitter, log) {
         });
         // 7. 构建流式 dispatcher
         const { dispatcher, replyOptions: streamReplyOptions, hasEmittedContent, } = createStreamReplyConfig({
-            emitter: boundEmitter,
+            emitter,
             targetId,
             replyMsgId,
             originalMsgId: msg.messageId,
             log,
             effectiveApiKey,
             typingAlreadyStarted: true,
-            agentId: effectiveAgentId,
         }, { ...prefixOptions, onModelSelected }, signalCtx);
         // 8. 分发给 AI 引擎（真流式）。abort 由 openclaw fast-abort 处理，sink 层
         //    把英文回执汉化；此处仅兜底自身抛错。
@@ -268,7 +250,7 @@ export function createInboundHandler(account, emitter, log) {
             log?.error(`[${CHANNEL_KEY}] Dispatch error: ${errMsg}`);
             // 已推过可见内容时不再追加错误文案，避免打断阅读。
             if (!hasEmittedContent()) {
-                emitter.sendReply(targetId, '抱歉，处理您的消息时出现了问题，请稍后重试', msg.messageId, effectiveAgentId);
+                emitter.sendReply(targetId, '抱歉，处理您的消息时出现了问题，请稍后重试', msg.messageId);
             }
         }
     };

package/dist/src/outbound.js

@@ -10,7 +10,7 @@
  *      - 连接断开但 entry 存在（重连中）→ 缓冲消息，重连后自动 flush
  *   2. WS 不可用时 fallback 到 REST API（需配置 apiBaseUrl）
  */
-import { CHANNEL_KEY, DEFAULT_ACCOUNT_ID, DEFAULT_AGENT_ID, EVENT_MESSAGE_PRIVATE } from './config.js';
+import { CHANNEL_KEY, DEFAULT_ACCOUNT_ID, EVENT_MESSAGE_PRIVATE } from './config.js';
 import { getLightclawRuntime } from './runtime.js';
 import { getSocket, bufferMessage, hasEntry, getBotClientId, getReliableEmitter } from './socket/index.js';
 import { resolveAccount } from './utils/index.js';
@@ -99,8 +99,6 @@ function sendViaSocket(accountId, target, text, replyToId) {
         timestamp: Date.now(),
         // undefined 表示非回复消息，避免发送多余字段
         replyToMsgId: replyToId ?? undefined,
-        // 所有出站消息必须携带 agentId，outbound 主动发送场景使用默认 Agent
-        agentId: DEFAULT_AGENT_ID,
     };
     if (entry) {
         // 策略 1：Socket 已连接，优先走可靠发送（emitWithAck + 自动重试）

package/dist/src/runtime.js

@@ -1,29 +1,40 @@
 /**
- * LightClaw — 插件运行时存储模块
+ * LightClaw — 插件运行时（PluginRuntime）全局存储模块
+ * ---------------------------------------------------------------
+ * 作用：
+ *   该文件负责保存并暴露插件在运行期间唯一的 `PluginRuntime` 实例，
+ *   使项目内各个模块（如 inbound / socket handlers / channel 逻辑等）
+ *   都能通过统一入口获取到平台运行时对象，而无需层层传递。
  *
- * 使用 OpenClaw SDK 标准的 createPluginRuntimeStore 工具函数替代传统的手动单例管理模式，
- *
- * 该模块的主要功能：
- * - 提供类型安全的运行时存储管理
- * - 避免手动单例模式带来的潜在问题
- * - 提供统一的错误处理和初始化状态管理
- * - 支持插件运行时的动态设置和获取
+ * 使用方式：
+ *   - 在插件启动阶段（通常在入口 `index.ts` 的 `onInit` 回调中）
+ *     调用 `setLightclawRuntime(api.runtime)` 完成注入；
+ *   - 在业务模块中通过 `getLightclawRuntime()` 获取实例，
+ *     进而访问 `runtime.config` / `runtime.channel` 等能力。
  */
-// 导入运行时存储创建工具函数
+// createPluginRuntimeStore：SDK 提供的通用工厂函数，
 import { createPluginRuntimeStore } from 'openclaw/plugin-sdk/runtime-store';
 /**
- * 创建 LightClaw 插件运行时存储
+ * 创建 LightClaw 专属的运行时存储实例。
+ *
+ * - 泛型 `PluginRuntime`：约束该 store 管理的对象形状；
+ * - 入参字符串：当调用方在未完成 `setRuntime` 之前就尝试 `getRuntime`，
+ *   SDK 将抛出包含此错误信息的异常，便于快速定位初始化顺序问题。
+ *
+ * 通过解构重命名，将 SDK 通用的 `setRuntime / getRuntime`
+ * 改名为带插件前缀的 `setLightclawRuntime / getLightclawRuntime`，
+ * 避免与其它插件（或多插件共存场景）产生命名冲突，提高可读性。
+ */
+const { setRuntime: setLightclawRuntime, getRuntime: getLightclawRuntime } = createPluginRuntimeStore('LightClaw runtime not initialized');
+/**
+ * 对外导出的运行时访问 API：
  *
- * 使用 createPluginRuntimeStore 工厂函数创建运行时存储对象，
- * 该函数返回一个包含 setRuntime 和 getRuntime 方法的对象。
+ * @function getLightclawRuntime
+ *   获取当前已注入的 PluginRuntime 实例。
+ *   若未初始化则抛出错误（见上方错误信息）。
  *
- * @template PluginRuntime - 运行时对象的类型参数
- * @param {string} 'LightClaw runtime not initialized' - 运行时未初始化时的错误消息
- * @returns {Object} 包含 setRuntime 和 getRuntime 方法的对象
- * @property {Function} setRuntime - 设置运行时实例的函数
- * @property {Function} getRuntime - 获取运行时实例的函数（如果未设置会抛出错误）
+ * @function setLightclawRuntime
+ *   在插件初始化阶段调用，将平台传入的 runtime 注入到全局存储中。
+ *   通常只应由插件入口调用一次，后续模块只读取不写入。
  */
-const { setRuntime: setLightclawRuntime, getRuntime: getLightclawRuntime } = createPluginRuntimeStore('LightClaw runtime not initialized' // 运行时未初始化时的自定义错误消息
-);
-// 导出运行时管理函数，供其他模块使用
 export { getLightclawRuntime, setLightclawRuntime };

package/dist/src/socket/handlers.js

@@ -12,10 +12,14 @@
  * 所有出站 socket.emit 通过 ReliableEmitter 实现 ACK 确认 + 自动重试，
  * 保证消息在网络抖动时不丢失。
  */
-import { CHANNEL_KEY, EVENT_MESSAGE_PRIVATE, EVENT_HISTORY_REQUEST, EVENT_HISTORY_RESPONSE, DEFAULT_HISTORY_LIMIT, DEFAULT_AGENT_ID, } from '../config.js';
+import { CHANNEL_KEY, EVENT_MESSAGE_PRIVATE, EVENT_HISTORY_REQUEST, EVENT_HISTORY_RESPONSE, DEFAULT_HISTORY_LIMIT, DEFAULT_AGENT_ID, EVENT_SESSIONS_REQUEST, EVENT_SESSIONS_RESPONSE, KIND_FILE_DOWNLOAD, FILE_DOWNLOAD_STATUS, resolveEffectiveApiKey } from '../config.js';
 import { isDuplicate, debounceHistoryRequest, generateMsgId } from '../dedup.js';
 import { getLightclawRuntime } from '../runtime.js';
-import { readSessionHistoryWithCron } from '../history/index.js';
+import { readSessionHistoryWithCron, listSessions } from '../history/index.js';
+import { uploadFileToCos } from '../file-storage.js';
+import { guessMimeByExt } from '../media.js';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
 /**
  * 绑定所有 Socket.IO 事件监听器到指定 socket 实例。
  *
@@ -39,7 +43,21 @@ export function bindSocketHandlers(socket, deps) {
         // ① 回环防御：过滤 bot 自身发出的消息，防止自问自答死循环
         if (data.from === botClientId)
             return;
-        // ② 跳过控制消息（如 typing 状态、stream 信号等），只处理 kind=text 的真实用户消息
+        // ② 分发文件下载信令（kind=file:download, status=download_req）：独立链路，不入 AI 处理队列
+        if (data.kind === KIND_FILE_DOWNLOAD) {
+            const reqTransferData = data.extra?.transferData;
+            if (reqTransferData?.status === FILE_DOWNLOAD_STATUS.REQ) {
+                // 去重：同一 transferId 的重复请求直接跳过
+                if (isDuplicate(data.msgId))
+                    return;
+                onEvent?.();
+                void handleFileDownloadReq(data, botClientId, reliableEmitter, log);
+            }
+            // 其他 status（ready/url/error）是本端自己发出的下行消息，理论上不会从前端回流；
+            // 即便误触发，此处直接 return 不做处理，避免进入 AI 处理队列
+            return;
+        }
+        // ③ 跳过其他控制消息（如 typing 状态、stream 信号等），只处理 kind=text 的真实用户消息
         if (data.kind && data.kind !== 'text')
             return;
         // ③ 内容校验：消息既无文字内容也无附件文件时，直接丢弃
@@ -145,9 +163,139 @@ export function bindSocketHandlers(socket, deps) {
                     sessionKey: '',
                     messages: [],
                     error: err instanceof Error ? err.message : String(err),
-                    agentId: data.agentId,
+                    agentId: data.agentId || DEFAULT_AGENT_ID,
                 }, errorMsgId);
             }
         });
     });
+    socket.on(EVENT_SESSIONS_REQUEST, (data) => {
+        // 通知框架收到入站事件（更新 lastEventAt，防止 stale-socket 误判）
+        onEvent?.();
+        try {
+            const sessions = listSessions();
+            const sessionsMsgId = generateMsgId();
+            reliableEmitter.emitWithAck(EVENT_SESSIONS_RESPONSE, {
+                requestId: data.requestId,
+                sessions,
+                msgId: sessionsMsgId,
+            }, sessionsMsgId);
+        }
+        catch (err) {
+            log?.error(`[${CHANNEL_KEY}] Sessions list error: ${err}`);
+            const sessionsErrMsgId = generateMsgId();
+            reliableEmitter.emitWithAck(EVENT_SESSIONS_RESPONSE, {
+                requestId: data.requestId,
+                sessions: [],
+                error: err instanceof Error ? err.message : String(err),
+                msgId: sessionsErrMsgId,
+            }, sessionsErrMsgId);
+        }
+    });
+}
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 文件下载处理器（kind=file:download, status=download_req）
+//
+// 流程：
+//   1. 从 data.extra.transferData 解析 transferId / localPath
+//   2. 基础校验：必须是绝对路径，文件必须存在
+//   3. 先回告 download_ready 帧（transferId + 文件元数据），前端据此更新下载按钮状态
+//   4. 通过 uploadFileToCos 将本机文件上传到 ai-server，拿到下载 URL
+//   5. 回告 download_url 帧（transferId + url），前端触发浏览器原生下载
+//   6. 任一阶段失败 → 回告 download_error 帧（transferId + error message）
+//
+// 备注：不走目录白名单校验，因为 localPath 来自 AI 工具返回的 localfile:// 链接，
+// AI 只会返回自己刚写盘的文件；上传到 ai-server 后会经过一轮内容审核兜底。
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+async function handleFileDownloadReq(data, botClientId, reliableEmitter, log) {
+    const transferData = data.extra?.transferData;
+    const transferId = transferData?.transferId;
+    const localPath = transferData?.localPath;
+    log?.info(`[${CHANNEL_KEY}] file:download(req) received: transferId=${transferId}, localPath=${localPath}, from=${data.from}`);
+    const sendError = (error) => {
+        const msgId = generateMsgId();
+        reliableEmitter.emitWithAck(EVENT_MESSAGE_PRIVATE, {
+            msgId,
+            from: botClientId,
+            to: data.from,
+            content: '',
+            timestamp: Date.now(),
+            kind: KIND_FILE_DOWNLOAD,
+            extra: { transferData: { transferId, status: FILE_DOWNLOAD_STATUS.ERROR, error } },
+        }, msgId);
+        log?.error(`[${CHANNEL_KEY}] file:download(error) sent: transferId=${transferId}, error=${error}`);
+    };
+    if (!transferId || !localPath) {
+        sendError('Missing transferId or localPath in extra.transferData');
+        return;
+    }
+    // 基础校验：必须是绝对路径
+    if (!path.isAbsolute(localPath)) {
+        sendError(`localPath must be an absolute path: ${localPath}`);
+        return;
+    }
+    const resolvedPath = path.resolve(localPath);
+    if (!fs.existsSync(resolvedPath)) {
+        sendError(`File not found: ${resolvedPath}`);
+        return;
+    }
+    const stat = fs.statSync(resolvedPath);
+    if (!stat.isFile()) {
+        sendError(`Not a regular file: ${resolvedPath}`);
+        return;
+    }
+    const fileName = path.basename(resolvedPath);
+    const mimeType = guessMimeByExt(path.extname(fileName).toLowerCase()) || 'application/octet-stream';
+    // 回告 download_ready（文件确认存在 + 元数据）
+    const readyMsgId = generateMsgId();
+    reliableEmitter.emitWithAck(EVENT_MESSAGE_PRIVATE, {
+        msgId: readyMsgId,
+        from: botClientId,
+        to: data.from,
+        content: '',
+        timestamp: Date.now(),
+        kind: KIND_FILE_DOWNLOAD,
+        extra: {
+            transferData: {
+                transferId,
+                status: FILE_DOWNLOAD_STATUS.READY,
+                name: fileName,
+                size: stat.size,
+                contentType: mimeType,
+            },
+        },
+    }, readyMsgId);
+    log?.info(`[${CHANNEL_KEY}] file:download(ready) sent: transferId=${transferId}, name=${fileName}, size=${stat.size}`);
+    // 上传本机文件到 ai-server（含审核），成功后把 URL 回告前端
+    try {
+        // 通过 senderId 解析真实 apiKey，用于 /drive/save 鉴权
+        const apiKey = resolveEffectiveApiKey({ senderId: data.from });
+        const uploadResult = await uploadFileToCos(resolvedPath, { apiKey });
+        if (!uploadResult.isUploaded || !uploadResult.url) {
+            sendError('Upload to ai-server failed');
+            return;
+        }
+        const urlMsgId = generateMsgId();
+        reliableEmitter.emitWithAck(EVENT_MESSAGE_PRIVATE, {
+            msgId: urlMsgId,
+            from: botClientId,
+            to: data.from,
+            content: '',
+            timestamp: Date.now(),
+            kind: KIND_FILE_DOWNLOAD,
+            extra: {
+                transferData: {
+                    transferId,
+                    status: FILE_DOWNLOAD_STATUS.URL,
+                    url: uploadResult.url,
+                    name: fileName,
+                    size: stat.size,
+                    contentType: mimeType,
+                },
+            },
+        }, urlMsgId);
+        log?.info(`[${CHANNEL_KEY}] file:download(url) sent: transferId=${transferId}, url=${uploadResult.url}`);
+    }
+    catch (err) {
+        sendError(err instanceof Error ? err.message : String(err));
+    }
 }

package/dist/src/streaming/stream-reply-sink.js

@@ -16,7 +16,7 @@ import { CHANNEL_KEY } from "../config.js";
 import { uploadFileToCos } from "../file-storage.js";
 import { mediaUrlsToFiles } from "../media.js";
 import { createDeltaTrackerState, toStreamDeltaText } from "./delta-tracker.js";
-import { emitSignal } from "../types.js";
+import { emitSignal } from "../utils/common.js";
 /** 派生/管理 subagent 的工具名；前端可据此特化渲染 tool_start。 */
 const SUBAGENT_TOOL_NAMES = new Set([
     "sessions_spawn",
@@ -30,7 +30,7 @@ function localizeAbortReplyText(text) {
     return OPENCLAW_ABORT_REPLY_RE.test(text.trim()) ? LOCALIZED_ABORT_REPLY : text;
 }
 export function createStreamReplyConfig(opts, prefixOptions, signalCtx) {
-    const { emitter, targetId, originalMsgId, log, effectiveApiKey, typingAlreadyStarted, agentId } = opts;
+    const { emitter, targetId, originalMsgId, log, effectiveApiKey, typingAlreadyStarted } = opts;
     // ── 增量追踪 & 已推送文本 ──
     let partialReplyState = createDeltaTrackerState();
     let streamedText = "";
@@ -110,11 +110,11 @@ export function createStreamReplyConfig(opts, prefixOptions, signalCtx) {
             enrichedText = enrichedText ? `${enrichedText}\n\n${urlSection}` : urlSection;
         }
         if (files.length > 0) {
-            emitter.sendFiles(targetId, enrichedText, files, originalMsgId, agentId);
+            emitter.sendFiles(targetId, enrichedText, files, originalMsgId);
             emittedUserVisible = true;
         }
         else if (enrichedText.trim()) {
-            emitter.sendReply(targetId, enrichedText, originalMsgId, agentId);
+            emitter.sendReply(targetId, enrichedText, originalMsgId);
             emittedUserVisible = true;
         }
     };
@@ -256,7 +256,7 @@ export function createStreamReplyConfig(opts, prefixOptions, signalCtx) {
                     : "LLM only produced thinking, no visible text";
                 log?.warn(`[${CHANNEL_KEY}] [stream] NO_REPLY: counts=${JSON.stringify(counts)} ` +
                     `toolStart=${toolStartCount} assistantMsg=${assistantMessageCount}. Cause: ${cause}`);
-                emitter.sendReply(targetId, "NO_REPLY", originalMsgId, agentId);
+                emitter.sendReply(targetId, "NO_REPLY", originalMsgId);
             }
             else {
                 log?.info(`[${CHANNEL_KEY}] [stream] markComplete: counts=${JSON.stringify(counts)} ` +

package/dist/src/types.js

@@ -8,24 +8,4 @@
  *
  * @format
  */
-/**
- * 统一的信号发送出口，收敛 typing / stream / tool 控制帧的构造逻辑。
- *
- * - typing_start 不带 replyToMsgId（协议要求）；其余帧都携带。
- * - extra 用于透传 kind 相关字段（如 tool_start 的 toolName/toolPhase、tool_end 的 toolIsError）。
- */
-export function emitSignal(ctx, kind, content = "", extra) {
-    const { emitter, targetId, replyMsgId, originalMsgId, agentId } = ctx;
-    return emitter.emit({
-        msgId: replyMsgId,
-        from: emitter.botClientId,
-        to: targetId,
-        content,
-        timestamp: Date.now(),
-        kind,
-        ...(kind !== "typing_start" ? { replyToMsgId: originalMsgId } : {}),
-        // 所有出站信号帧统一携带 agentId，优先使用 signalCtx.agentId，否则回退 emitter 绑定值
-        ...(agentId || emitter.agentId ? { agentId: agentId ?? emitter.agentId } : {}),
-        ...extra,
-    });
-}
+export {};

package/dist/src/upload-tool.js

@@ -1,16 +1,20 @@
 /**
- * LightClaw — 文件上传工具
+ * LightClaw — 文件注册工具
  *
- * 注册为 OpenClaw Agent Tool，允许 AI 将本地文件上传到云端存储，
- * 获得公网可访问的 URL，方便用户直接下载。
+ * 注册为 OpenClaw Agent Tool。AI 生成本机文件后调用此工具，
+ * 返回 `localfile://<绝对路径>` 格式的 Markdown 下载链接。AI 将链接
+ * 原样写入回复，前端识别 `localfile://` 前缀后通过 WS file:download 信令
+ * （status=download_req）让 lightclaw 按需上传到 ai-server 再推回浏览器下载。
  *
  * 工具名: lightclaw_upload_file
+ *
+ * 备注：名字保留 "upload" 以兼容现有 skill 表述，实际不再主动上传 COS，
+ * 只在本机做存在性校验并生成标准格式的 Markdown 链接。
  */
-import * as fs from "node:fs";
+import * as fsp from "node:fs/promises";
 import * as path from "node:path";
-import { uploadFileToCos } from "./file-storage.js";
 import { formatFileSize } from "./media.js";
-import { resolveEffectiveApiKey } from "./config.js";
+import { LOCALFILE_SCHEME } from "./config.js";
 // ============================================================
 // 工具参数 schema（JSON Schema 格式）
 // ============================================================
@@ -23,13 +27,13 @@ export const uploadToolSchema = {
             items: { type: "string" },
             minItems: 1,
             maxItems: 5,
-            description: "需要上传的本地文件绝对路径数组，文件必须已写入磁盘，最多 5 个文件",
+            description: "需要注册的本地文件绝对路径数组，文件必须已写入磁盘，最多 5 个文件",
         },
     },
     required: ["paths"],
 };
 // ============================================================
-// 工具注册（飞书工厂函数模式）
+// 工具注册（工厂函数模式）
 // ============================================================
 export function registerUploadTool(api) {
     // 通过闭包捕获 api.logger，tool ctx 中没有 log
@@ -37,22 +41,16 @@ export function registerUploadTool(api) {
     api.registerTool((ctx) => {
         // 硬隔离：非 lightclawbot 通道时直接返回 null，框架不会暴露此工具
         if (ctx.messageChannel !== "lightclawbot") {
-            // log.warn(`[lightclaw_upload_file] channel=${ctx.messageChannel}, skip..."`);
             return null;
         }
-        const defaultAccountId = ctx.agentAccountId;
-        const sessionKey = ctx.sessionKey;
-        // log.warn(`[lightclaw_upload_file] channel=${ctx.messageChannel}, contiue..."`);
         return {
             name: UPLOAD_TOOL_NAME,
-            description: "将本地文件上传到云端临时存储并返回下载链接。" +
+            description: "将 AI 生成的本机文件注册为可下载的引用，返回 `localfile://<绝对路径>` 格式的 Markdown 下载链接。" +
                 "当需要把生成的文件（图片、文档、代码包等）交付给用户时，必须使用此工具。" +
-                "文件必须先写入磁盘，然后传入绝对路径。单次最多 5 个文件，超出请分批调用。",
+                "文件必须先写入磁盘，然后传入绝对路径。单次最多 5 个文件，超出请分批调用。" +
+                "重要：工具返回的 Markdown 链接已是最终格式，请原样使用，不要改写为 https:// 或本机路径字符串。",
             parameters: uploadToolSchema,
             async execute(_toolCallId, params) {
-                // 每次 execute 时动态解析 apiKey（多 key 模式下通过 sessionKey 直接获取）
-                const apiKey = resolveEffectiveApiKey({ sessionKey });
-                // log.warn(`[lightclaw_upload_file] resolved apiKey="${apiKey?.slice(0, 8)}..."`);
                 const { paths } = params;
                 // 参数校验
                 if (!Array.isArray(paths) || paths.length === 0) {
@@ -65,78 +63,55 @@ export function registerUploadTool(api) {
                         content: [{ type: "text", text: "Error: maximum 5 files per upload." }],
                     };
                 }
-                // 验证所有文件存在
-                const validationErrors = [];
-                for (const p of paths) {
+                // 并发校验所有路径并顺便拿到 stat
+                //   - 路径合法性（绝对路径、非空字符串）：同步判定
+                //   - 文件存在 + 必须是 regular file：靠 fsp.stat 抛错 / isFile() 判定
+                const results = await Promise.all(paths.map(async (p) => {
                     if (typeof p !== "string" || !p.trim()) {
-                        validationErrors.push(`Invalid path: empty or non-string`);
-                        continue;
+                        return { path: p, error: `Invalid path: empty or non-string` };
                     }
-                    if (!fs.existsSync(p)) {
-                        validationErrors.push(`File not found: ${p}`);
-                        continue;
+                    if (!p.startsWith("/") && !/^[A-Za-z]:\\/.test(p)) {
+                        return { path: p, error: `Path must be absolute: ${p}` };
                     }
-                    const stat = fs.statSync(p);
-                    if (!stat.isFile()) {
-                        validationErrors.push(`Not a regular file: ${p}`);
+                    try {
+                        const stat = await fsp.stat(p);
+                        if (!stat.isFile()) {
+                            return { path: p, error: `Not a regular file: ${p}` };
+                        }
+                        return { path: p, stat };
                     }
-                }
+                    catch (err) {
+                        const code = err?.code;
+                        if (code === 'ENOENT') {
+                            return { path: p, error: `File not found: ${p}` };
+                        }
+                        return { path: p, error: `Stat failed: ${p} (${err.message})` };
+                    }
+                }));
+                const validationErrors = results
+                    .filter((r) => 'error' in r)
+                    .map((r) => r.error);
                 if (validationErrors.length > 0) {
                     return {
                         content: [{ type: "text", text: `Validation errors:\n${validationErrors.join("\n")}` }],
                     };
                 }
-                // 并发上传（最多 3 个并发）
-                const results = [];
-                const concurrency = 3;
-                for (let i = 0; i < paths.length; i += concurrency) {
-                    const batch = paths.slice(i, i + concurrency);
-                    const batchResults = await Promise.allSettled(batch.map(async (filePath) => {
-                        const stat = fs.statSync(filePath);
-                        const uploadResult = await uploadFileToCos(filePath, { apiKey });
-                        return {
-                            path: filePath,
-                            success: true,
-                            url: uploadResult.url,
-                            filePath: uploadResult.filePath,
-                            size: formatFileSize(stat.size),
-                        };
-                    }));
-                    for (let j = 0; j < batchResults.length; j++) {
-                        const r = batchResults[j];
-                        if (r.status === "fulfilled") {
-                            results.push(r.value);
-                        }
-                        else {
-                            results.push({
-                                path: batch[j],
-                                success: false,
-                                error: r.reason instanceof Error ? r.reason.message : String(r.reason),
-                            });
-                        }
-                    }
-                }
-                // 构建结果文本（使用 Markdown 链接格式，引导模型原样输出给用户）
-                const lines = [];
-                const successResults = [];
-                for (const r of results) {
-                    const name = path.basename(r.path);
-                    if (r.success && r.url) {
-                        lines.push(`✅ [${name}](${r.url}) (${r.size})`);
-                        successResults.push({ name, url: r.url, size: r.size });
-                    }
-                    else {
-                        lines.push(`❌ ${name}: ${r.error}`);
-                    }
-                }
-                const summary = results.length === 1
-                    ? successResults.length === 1
-                        ? `File uploaded successfully.\n\n[${successResults[0].name}](${successResults[0].url})`
-                        : `File upload failed: ${results[0].error}`
-                    : `Uploaded ${successResults.length}/${results.length} files.\n${lines.join("\n")}`;
+                // 基于本机路径生成 localfile:// 链接（不上传 COS），复用上一步已拿到的 stat
+                const successResults = results.map(({ path: filePath, stat }) => ({
+                    name: path.basename(filePath),
+                    path: filePath,
+                    url: `${LOCALFILE_SCHEME}${filePath}`,
+                    size: formatFileSize(stat.size),
+                }));
+                log?.info?.(`[${UPLOAD_TOOL_NAME}] registered ${successResults.length} file(s)`);
+                // 构建结果文本（Markdown 链接，引导模型原样输出给用户）
+                const lines = successResults.map((r) => `✅ [${r.name}](${r.url}) (${r.size})`);
+                const summary = successResults.length === 1
+                    ? `File registered successfully.\n\n[${successResults[0].name}](${successResults[0].url})`
+                    : `Registered ${successResults.length} files.\n${lines.join("\n")}`;
                 return {
                     content: [{ type: "text", text: summary }],
-                    details: { uploads: results },
+                    details: { uploads: successResults },
                 };
             },
         };

package/dist/src/utils/common.js

@@ -46,3 +46,23 @@ export function buildAuthHeaders(apiKey) {
         'x-product': X_PRODUCT,
     };
 }
+/**
+ * 统一的信号发送出口，收敛 typing / stream / tool 控制帧的构造逻辑。
+ *
+ * - typing_start 不带 replyToMsgId（协议要求）；其余帧都携带。
+ * - extra 用于透传 kind 相关字段（如 tool_start 的 toolName/toolPhase、tool_end 的 toolIsError）。
+ */
+export function emitSignal(ctx, kind, content = '', extra) {
+    const { emitter, targetId, replyMsgId, originalMsgId, agentId } = ctx;
+    return emitter.emit({
+        msgId: replyMsgId,
+        from: emitter.botClientId,
+        to: targetId,
+        content,
+        timestamp: Date.now(),
+        kind,
+        ...(kind !== 'typing_start' ? { replyToMsgId: originalMsgId } : {}),
+        ...extra,
+        agentId,
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lightclawbot",
-  "version": "1.2.0-beta.0",
+  "version": "1.2.0-beta.2",
   "description": "LightClawBot channel plugin with message support, cron jobs, and proactive messaging",
   "type": "module",
   "files": [