lightclawbot 1.2.0-beta.1 → 1.2.0-beta.3

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/config.js

@@ -32,7 +32,7 @@ export const WS_URL = `wss://${DOMAIN}`;
 /** HTTP API 基础地址 */
 export const API_BASE_URL = `https://${DOMAIN}`;
 /** 文件存储相关配置 */
-export const COS_BASE_URL = `https://${DOMAIN}`;
+export const SERVER_UPLOAD_BASE_URL = `https://${DOMAIN}`;
 // ============================================================
 // WebSocket 配置
 // ============================================================
@@ -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/download-tool.js

@@ -9,7 +9,7 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { getFileDownloadUrl, downloadFileFromCos, uploadFileToCos, } from "./file-storage.js";
+import { getFileDownloadUrl, downloadFileFromServer, uploadFileToServer, } from "./file-storage.js";
 import { formatFileSize } from "./media.js";
 import { resolveEffectiveApiKey } from "./config.js";
 // ============================================================
@@ -79,7 +79,7 @@ export function registerDownloadTool(api) {
                             };
                         }
                         case "download_to_local": {
-                            const result = await downloadFileFromCos(filePath, { apiKey });
+                            const result = await downloadFileFromServer(filePath, { apiKey });
                             const targetDir = localDir || process.cwd();
                             // 确保目录存在
                             if (!fs.existsSync(targetDir)) {
@@ -107,7 +107,7 @@ export function registerDownloadTool(api) {
                                     content: [{ type: "text", text: `Error: local file not found: ${filePath}` }],
                                 };
                             }
-                            const uploadResult = await uploadFileToCos(filePath, { apiKey });
+                            const uploadResult = await uploadFileToServer(filePath, { apiKey });
                             const fileName = path.basename(filePath);
                             return {
                                 content: [{

package/dist/src/file-storage.js

@@ -10,7 +10,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { guessMimeByExt } from "./media.js";
-import { COS_BASE_URL, API_PATH_UPLOAD, API_PATH_DOWNLOAD, UPLOAD_TIMEOUT, } from "./config.js";
+import { SERVER_UPLOAD_BASE_URL, API_PATH_UPLOAD, API_PATH_DOWNLOAD, UPLOAD_TIMEOUT, } from "./config.js";
 import { buildAuthHeaders } from './utils/index.js';
 // ============================================================
 // 核心方法
@@ -23,7 +23,7 @@ import { buildAuthHeaders } from './utils/index.js';
  * @param customFileName - 自定义文件名（可选，默认使用原文件名）
  * @returns 上传结果，包含公网 URL
  */
-export async function uploadFileToCos(localPath, config = {}, customFileName) {
+export async function uploadFileToServer(localPath, config = {}, customFileName) {
     // 验证文件存在
     if (!fs.existsSync(localPath)) {
         throw new Error(`File not found: ${localPath}`);
@@ -48,7 +48,7 @@ export async function uploadFileToCos(localPath, config = {}, customFileName) {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), UPLOAD_TIMEOUT);
     try {
-        const response = await fetch(`${COS_BASE_URL}${API_PATH_UPLOAD}`, {
+        const response = await fetch(`${SERVER_UPLOAD_BASE_URL}${API_PATH_UPLOAD}`, {
             method: "POST",
             body: formData,
             headers,
@@ -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 };
+            return { url: `${SERVER_UPLOAD_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);
@@ -77,7 +77,7 @@ export async function uploadFileToCos(localPath, config = {}, customFileName) {
  * @param config - 文件存储配置
  * @returns 上传结果，包含公网 URL
  */
-export async function uploadBufferToCos(buffer, fileName, mimeType, config = {}) {
+export async function uploadBufferToServer(buffer, fileName, mimeType, config = {}) {
     const filePath = `${Date.now()}/${fileName}`;
     const { Blob: NodeBlob } = await import("node:buffer");
     const blob = new NodeBlob([new Uint8Array(buffer)], { type: mimeType });
@@ -88,7 +88,7 @@ export async function uploadBufferToCos(buffer, fileName, mimeType, config = {})
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), UPLOAD_TIMEOUT);
     try {
-        const response = await fetch(`${COS_BASE_URL}${API_PATH_UPLOAD}`, {
+        const response = await fetch(`${SERVER_UPLOAD_BASE_URL}${API_PATH_UPLOAD}`, {
             method: "POST",
             body: formData,
             headers,
@@ -100,7 +100,7 @@ export async function uploadBufferToCos(buffer, fileName, mimeType, config = {})
         }
         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 };
+            return { url: `${SERVER_UPLOAD_BASE_URL}${API_PATH_DOWNLOAD}?filePath=${filePath}`, filePath, isUploaded: true };
         }
         throw new Error(`Upload failed (HTTP ${response.status}): ${result.data}`);
     }
@@ -116,7 +116,7 @@ export async function uploadBufferToCos(buffer, fileName, mimeType, config = {})
  * @returns 公网下载 URL
  */
 export function getFileDownloadUrl(filePath) {
-    return `${COS_BASE_URL}${API_PATH_DOWNLOAD}?filePath=${encodeURIComponent(filePath)}`;
+    return `${SERVER_UPLOAD_BASE_URL}${API_PATH_DOWNLOAD}?filePath=${encodeURIComponent(filePath)}`;
 }
 /**
  * 从云端存储下载文件内容
@@ -125,8 +125,8 @@ export function getFileDownloadUrl(filePath) {
  * @param config - 文件存储配置
  * @returns 下载结果，包含 Buffer 和文件信息
  */
-export async function downloadFileFromCos(filePath, config = {}) {
-    const url = filePath.startsWith("http") ? filePath : `${COS_BASE_URL}${API_PATH_DOWNLOAD}?filePath=${encodeURIComponent(filePath)}`;
+export async function downloadFileFromServer(filePath, config = {}) {
+    const url = filePath.startsWith("http") ? filePath : `${SERVER_UPLOAD_BASE_URL}${API_PATH_DOWNLOAD}?filePath=${encodeURIComponent(filePath)}`;
     const headers = buildAuthHeaders(config.apiKey ?? "");
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), UPLOAD_TIMEOUT);
@@ -154,6 +154,6 @@ export async function downloadFileFromCos(filePath, config = {}) {
  * @returns 公网可访问的下载 URL
  */
 export async function uploadAndGetPublicUrl(localPath, config = {}) {
-    const result = await uploadFileToCos(localPath, config);
+    const result = await uploadFileToServer(localPath, config);
     return result.url || '';
 }

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（用于终止消息处理循环） */

package/dist/src/inbound.js

@@ -7,13 +7,13 @@
  *   - 并发由 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 { emitSignal } from './utils/common.js';
+import { CHANNEL_KEY, MEDIA_MAX_BYTES, resolveEffectiveApiKey, setSessionApiKey, DEFAULT_AGENT_ID, LOCALFILE_SCHEME } 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 { uploadFileToServer, downloadFileFromServer, getFileDownloadUrl } from './file-storage.js';
 import { createStreamReplyConfig } from './streaming/index.js';
 export function createInboundHandler(account, emitter, log) {
     return async (msg) => {
@@ -92,7 +92,7 @@ export function createInboundHandler(account, emitter, log) {
             try {
                 let buffer;
                 let mimeType;
-                let cosPublicUrl;
+                let uploadPublicUrl;
                 const parsed = file.bytes ? parseDataUrl(file.bytes) : null;
                 if (parsed) {
                     buffer = parsed.buffer;
@@ -100,10 +100,10 @@ export function createInboundHandler(account, emitter, log) {
                 }
                 else if (file.uri) {
                     log?.info(`[${CHANNEL_KEY}] File has URI, downloading from cloud: ${file.uri}`);
-                    const downloaded = await downloadFileFromCos(file.uri, { apiKey: effectiveApiKey });
+                    const downloaded = await downloadFileFromServer(file.uri, { apiKey: effectiveApiKey });
                     buffer = downloaded.buffer;
                     mimeType = file.mimeType;
-                    cosPublicUrl = file.uri.startsWith('http') ? file.uri : getFileDownloadUrl(file.uri);
+                    uploadPublicUrl = file.uri.startsWith('http') ? file.uri : getFileDownloadUrl(file.uri);
                 }
                 else {
                     // 来源 3：既无 bytes 也无 uri，无法处理，跳过此文件
@@ -114,19 +114,20 @@ export function createInboundHandler(account, emitter, log) {
                 const saved = await pluginRuntime.channel.media.saveMediaBuffer(buffer, mimeType, 'inbound', MEDIA_MAX_BYTES, file.name);
                 localMediaPaths.push(saved.path);
                 localMediaTypes.push(mimeType);
-                if (cosPublicUrl) {
-                    publicMediaUrls.push(cosPublicUrl);
+                const localPath = `${LOCALFILE_SCHEME}${saved.path}`;
+                if (uploadPublicUrl) {
+                    publicMediaUrls.push(localPath);
                 }
                 else {
-                    // data URL 来源：上传到 COS 获取公网 URL，失败则 fallback 到本地路径
+                    // data URL 来源：用户自行上传到服务器
                     try {
-                        const uploadResult = await uploadFileToCos(saved.path, { apiKey: effectiveApiKey });
-                        publicMediaUrls.push(uploadResult.url || `file://${saved.path}`);
+                        const uploadResult = await uploadFileToServer(saved.path, { apiKey: effectiveApiKey });
+                        publicMediaUrls.push(localPath);
                         log?.info(`[${CHANNEL_KEY}] Uploaded inbound file: ${saved.path} → ${uploadResult.url}`);
                     }
                     catch (uploadErr) {
                         log?.warn(`[${CHANNEL_KEY}] Upload failed, falling back to local path: ${uploadErr}`);
-                        publicMediaUrls.push(`file://${saved.path}`);
+                        publicMediaUrls.push(localPath);
                     }
                 }
                 const attachmentUrl = publicMediaUrls[publicMediaUrls.length - 1];

package/dist/src/runtime.js

@@ -1,9 +1,40 @@
 /**
- * LightClaw — 插件运行时存储
+ * LightClaw — 插件运行时（PluginRuntime）全局存储模块
+ * ---------------------------------------------------------------
+ * 作用：
+ *   该文件负责保存并暴露插件在运行期间唯一的 `PluginRuntime` 实例，
+ *   使项目内各个模块（如 inbound / socket handlers / channel 逻辑等）
+ *   都能通过统一入口获取到平台运行时对象，而无需层层传递。
  *
- * 使用 SDK 标准的 createPluginRuntimeStore 替代手动单例管理，
- * 确保与官方 channel 插件（Discord/Slack）的模式一致。
+ * 使用方式：
+ *   - 在插件启动阶段（通常在入口 `index.ts` 的 `onInit` 回调中）
+ *     调用 `setLightclawRuntime(api.runtime)` 完成注入；
+ *   - 在业务模块中通过 `getLightclawRuntime()` 获取实例，
+ *     进而访问 `runtime.config` / `runtime.channel` 等能力。
  */
+// createPluginRuntimeStore：SDK 提供的通用工厂函数，
 import { createPluginRuntimeStore } from 'openclaw/plugin-sdk/runtime-store';
+/**
+ * 创建 LightClaw 专属的运行时存储实例。
+ *
+ * - 泛型 `PluginRuntime`：约束该 store 管理的对象形状；
+ * - 入参字符串：当调用方在未完成 `setRuntime` 之前就尝试 `getRuntime`，
+ *   SDK 将抛出包含此错误信息的异常，便于快速定位初始化顺序问题。
+ *
+ * 通过解构重命名，将 SDK 通用的 `setRuntime / getRuntime`
+ * 改名为带插件前缀的 `setLightclawRuntime / getLightclawRuntime`，
+ * 避免与其它插件（或多插件共存场景）产生命名冲突，提高可读性。
+ */
 const { setRuntime: setLightclawRuntime, getRuntime: getLightclawRuntime } = createPluginRuntimeStore('LightClaw runtime not initialized');
+/**
+ * 对外导出的运行时访问 API：
+ *
+ * @function getLightclawRuntime
+ *   获取当前已注入的 PluginRuntime 实例。
+ *   若未初始化则抛出错误（见上方错误信息）。
+ *
+ * @function setLightclawRuntime
+ *   在插件初始化阶段调用，将平台传入的 runtime 注入到全局存储中。
+ *   通常只应由插件入口调用一次，后续模块只读取不写入。
+ */
 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 } 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 { uploadFileToServer } 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, account, log);
+            }
+            // 其他 status（ready/url/error）是本端自己发出的下行消息，理论上不会从前端回流；
+            // 即便误触发，此处直接 return 不做处理，避免进入 AI 处理队列
+            return;
+        }
+        // ③ 跳过其他控制消息（如 typing 状态、stream 信号等），只处理 kind=text 的真实用户消息
         if (data.kind && data.kind !== 'text')
             return;
         // ③ 内容校验：消息既无文字内容也无附件文件时，直接丢弃
@@ -150,4 +168,134 @@ export function bindSocketHandlers(socket, deps) {
             }
         });
     });
+    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. 通过 uploadFileToServer 将本机文件上传到 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, account, 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 = account.apiKey;
+        const uploadResult = await uploadFileToServer(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

@@ -13,10 +13,10 @@
  *   counts / *Count  计数器，供 markComplete 推断 NO_REPLY 原因
  */
 import { CHANNEL_KEY } from "../config.js";
-import { uploadFileToCos } from "../file-storage.js";
+import { uploadFileToServer } 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",
@@ -87,7 +87,7 @@ export function createStreamReplyConfig(opts, prefixOptions, signalCtx) {
                 if (localPath.startsWith("/") || localPath.match(/^[A-Za-z]:\\/)) {
                     const { existsSync } = await import("node:fs");
                     if (existsSync(localPath)) {
-                        const result = await uploadFileToCos(localPath, storageConfig);
+                        const result = await uploadFileToServer(localPath, storageConfig);
                         publicUrls.push(result.url || "");
                         log?.info(`[${CHANNEL_KEY}] [stream] Uploaded to COS: ${localPath} → ${result.url}`);
                     }

package/dist/src/types.js

@@ -8,23 +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 } : {}),
-        ...extra,
-        agentId,
-    });
-}
+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.1",
+  "version": "1.2.0-beta.3",
   "description": "LightClawBot channel plugin with message support, cron jobs, and proactive messaging",
   "type": "module",
   "files": [