@ynhcj/xiaoyi-channel 1.1.26 → 1.1.28

package/dist/src/cspl/upload_file.js

@@ -0,0 +1,211 @@
+/*
+ * 版权所有 (c) 华为技术有限公司 2026-2026
+ */
+import fs from 'fs';
+import path from 'path';
+import https from 'https';
+import { URL } from 'url';
+import { getConfig } from './config.js';
+import { DEFAULT_HTTP_PORT, DEFAULT_HTTPS_PORT, MAX_TIMES, CONNECT_TIMEOUT, READ_TIMEOUT, EXPIRE_TIME, OSMS_PREPARE_URL, OSMS_COMPLETE_URL, TEMPORARY_MATERIAL_PACKAGE, FILE_OWNER_UID, FILE_OWNER_TEAM_ID } from './constants.js';
+function buildOsmsHeaders(config, traceId) {
+    return {
+        'content-type': 'application/json',
+        'x-request-from': 'openclaw',
+        'x-uid': config.uid,
+        'x-api-key': config.apiKey,
+        'x-hag-trace-id': traceId,
+        'x-skill-id': ''
+    };
+}
+function httpRequest(url, method, headers, body, timeout) {
+    return new Promise((resolve, reject) => {
+        const urlObj = new URL(url);
+        const options = {
+            hostname: urlObj.hostname,
+            port: urlObj.port || DEFAULT_HTTP_PORT,
+            path: urlObj.pathname + urlObj.search,
+            method: method,
+            headers: headers,
+            timeout: timeout,
+            rejectUnauthorized: false
+        };
+        const req = https.request(options, (res) => {
+            let data = '';
+            res.on('data', (chunk) => {
+                data += chunk;
+            });
+            res.on('end', () => {
+                if (res.statusCode && res.statusCode >= 400) {
+                    reject(new Error(`HTTP error! status: ${res.statusCode}, body: ${data}`));
+                }
+                else {
+                    resolve(data);
+                }
+            });
+        });
+        req.on('error', (error) => {
+            reject(error);
+        });
+        req.on('timeout', () => {
+            req.destroy();
+            reject(new Error('Request timeout'));
+        });
+        if (body) {
+            req.write(body);
+        }
+        req.end();
+    });
+}
+async function invokingOsmsPrepare(filePath, config, fileSha256, fileSize, sessionId) {
+    const headers = buildOsmsHeaders(config, sessionId);
+    const fileName = path.basename(filePath);
+    const body = JSON.stringify({
+        useEdge: false,
+        objectType: TEMPORARY_MATERIAL_PACKAGE,
+        fileName: fileName,
+        fileSha256: fileSha256,
+        fileSize: fileSize,
+        fileOwnerInfo: {
+            uid: FILE_OWNER_UID,
+            teamId: FILE_OWNER_TEAM_ID
+        }
+    });
+    const prepareUrl = `${config.serviceUrl}${OSMS_PREPARE_URL}`;
+    for (let times = 0; times < MAX_TIMES; times++) {
+        try {
+            const responseData = await httpRequest(prepareUrl, 'POST', headers, body, CONNECT_TIMEOUT);
+            const resp = JSON.parse(responseData);
+            if (!resp.objectId || !resp.draftId || !resp.uploadInfos) {
+                throw new Error('The hag osms prepare interface returns an exception');
+            }
+            if (!resp.uploadInfos || resp.uploadInfos.length === 0) {
+                throw new Error('The hag osms prepare interface uploadInfos returns is empty');
+            }
+            const uploadInfo = resp.uploadInfos[0];
+            if (!uploadInfo.url || !uploadInfo.headers) {
+                throw new Error('The hag osms prepare interface url and headers for uploadInfos map returns is empty');
+            }
+            return resp;
+        }
+        catch (e) {
+            if (times === MAX_TIMES - 1) {
+                throw e;
+            }
+        }
+    }
+    throw new Error('Failed to invoke OSMS prepare interface after max retries');
+}
+function readFileAsBytes(filePath) {
+    try {
+        return fs.readFileSync(filePath);
+    }
+    catch (error) {
+        const err = error;
+        throw new Error(`Failed to read file: ${filePath}. Error: ${err.message}`);
+    }
+}
+async function uploadFileToObs(uploadInfo, fileBytes) {
+    let retryDelay = 1;
+    let retryTime = 1;
+    while (true) {
+        try {
+            const urlObj = new URL(uploadInfo.url);
+            const options = {
+                hostname: urlObj.hostname,
+                port: urlObj.port || DEFAULT_HTTPS_PORT,
+                path: urlObj.pathname + urlObj.search,
+                method: 'PUT',
+                headers: {
+                    ...uploadInfo.headers,
+                    'content-length': fileBytes.length.toString(),
+                },
+                timeout: READ_TIMEOUT,
+                rejectUnauthorized: false
+            };
+            await new Promise((resolve, reject) => {
+                const req = https.request(options, (res) => {
+                    let data = '';
+                    res.on('data', (chunk) => {
+                        data += chunk;
+                    });
+                    res.on('end', () => {
+                        if (res.statusCode && res.statusCode >= 400) {
+                            reject(new Error(`Upload failed with status: ${res.statusCode}, body: ${data}`));
+                        }
+                        else {
+                            resolve();
+                        }
+                    });
+                });
+                req.on('error', (error) => {
+                    reject(error);
+                });
+                req.on('timeout', () => {
+                    req.destroy();
+                    reject(new Error('Upload timeout'));
+                });
+                req.write(fileBytes);
+                req.end();
+            });
+            return true;
+        }
+        catch (e) {
+            retryTime++;
+            if (retryTime > MAX_TIMES) {
+                throw new Error(`Upload file to obs failed: ${e.message}`);
+            }
+            await new Promise(resolve => setTimeout(resolve, retryDelay * Math.pow(2, retryTime)));
+        }
+    }
+}
+async function invokingOsmsComplete(objectId, draftId, config, sessionId) {
+    const headers = buildOsmsHeaders(config, sessionId);
+    const body = JSON.stringify({
+        objectId: objectId,
+        draftId: draftId,
+        expireTime: EXPIRE_TIME
+    });
+    const completeUrl = `${config.serviceUrl}${OSMS_COMPLETE_URL}`;
+    for (let times = 0; times < MAX_TIMES; times++) {
+        try {
+            const responseData = await httpRequest(completeUrl, 'POST', headers, body, CONNECT_TIMEOUT);
+            const resp = JSON.parse(responseData);
+            return resp;
+        }
+        catch (e) {
+            if (times === MAX_TIMES - 1) {
+                throw e;
+            }
+        }
+    }
+    throw new Error('Failed to invoke OSMS complete interface after max retries');
+}
+export async function uploadFileToObsMain(filePath, api, fileHash, sessionId) {
+    const config = getConfig(api);
+    const serviceUrl = config.api.url;
+    const obsConfig = {
+        uid: config.uid,
+        apiKey: config.apiKey,
+        serviceUrl: serviceUrl
+    };
+    const fileSize = fs.statSync(filePath).size;
+    const prepareResponse = await invokingOsmsPrepare(filePath, obsConfig, fileHash, fileSize, sessionId);
+    let fileBytes;
+    try {
+        fileBytes = readFileAsBytes(filePath);
+    }
+    catch (error) {
+        const err = error;
+        throw new Error(`Failed to read file for upload: ${filePath}. Error: ${err.message}`);
+    }
+    const uploadInfo = {
+        url: prepareResponse.uploadInfos[0].url,
+        headers: prepareResponse.uploadInfos[0].headers
+    };
+    await uploadFileToObs(uploadInfo, fileBytes);
+    const completeResponse = await invokingOsmsComplete(prepareResponse.objectId, prepareResponse.draftId, obsConfig, sessionId);
+    if (!completeResponse.fileDetailInfo || !completeResponse.fileDetailInfo.url) {
+        throw new Error('Failed to get download URL from complete response');
+    }
+    return completeResponse.fileDetailInfo.url;
+}

package/dist/src/cspl/utils.d.ts

@@ -1,10 +1,25 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 export declare function filterText(text: string): string;
 export declare function validateAndTruncateText(text: string, maxLength: number): {
     text: string;
     truncated: boolean;
 };
 export declare function extractResultText(event: any, toolName: string): string;
-export declare function processText(resultText: string): string;
+export declare function processText(resultText: string, api: OpenClawPluginApi): string;
 export declare function parseSecurityResult(response: any): {
-    status: "ACCEPT" | "REJECT";
+    status: 'ACCEPT' | 'REJECT';
 };
+export declare function extractInputParams(event: any, toolName: string): string;
+export declare function extractFilePathsFromCommand(command: string): string[];
+export declare function calculateContentHash(content: string): string;
+export declare function getFileSizeInKB(filePath: string): number;
+export declare function adjustContentLength(data: any, api: OpenClawPluginApi, fields: string[]): any;
+export declare function handleExecToolInput(event: any, api: OpenClawPluginApi, sessionId: string): Promise<{
+    status: 'ACCEPT' | 'REJECT';
+} | null>;
+export declare function handleMessageToolInput(event: any, api: OpenClawPluginApi, sessionId: string): Promise<{
+    status: 'ACCEPT' | 'REJECT';
+} | null>;
+export declare function handleOtherToolInput(event: any, api: OpenClawPluginApi, sessionId: string): Promise<{
+    status: 'ACCEPT' | 'REJECT';
+} | null>;

package/dist/src/cspl/utils.js

@@ -1,10 +1,21 @@
-// CSPL Hook 工具函数
-import { MAX_TEXT_LENGTH, regex, SECURITY_NOTICE } from "./constants.js";
+/*
+ * 版权所有 (c) 华为技术有限公司 2026-2026
+ */
+import { MAX_TEXT_LENGTH, regex, SECURITY_NOTICE, MAX_FILE_COUNT, MAX_COMMAND_LENGTH, CODE_FILE_EXTENSIONS, TOOL_INPUT_DEFAULT, FILE_EXTENSION_REGEX, TOOL_INPUT_ACTION } from './constants.js';
+import crypto from 'crypto';
+import fs from 'fs';
+import path from 'path';
+import { Buffer } from 'buffer';
+import { callApi } from './call_api.js';
+import { uploadFileToObsMain } from './upload_file.js';
+import { logger } from '../utils/logger.js';
+// 文本过滤函数：仅保留中文、英文、数字、标点符号
 export function filterText(text) {
     if (!text)
         return "";
-    return text.replace(new RegExp(regex.source, "g"), "");
+    return text.replace(new RegExp(regex.source, 'g'), '');
 }
+// 文本验证和截断函数
 export function validateAndTruncateText(text, maxLength) {
     if (text.length > maxLength) {
         const halfMaxLength = Math.floor(maxLength / 2);
@@ -16,7 +27,8 @@ export function validateAndTruncateText(text, maxLength) {
 }
 export function extractResultText(event, toolName) {
     const resultTexts = [];
-    if (toolName === "web_fetch") {
+    // web_fetch工具特殊处理：从details.text提取
+    if (toolName === 'web_fetch') {
         if (event.result?.details?.text) {
             let text = event.result.details.text;
             text = text.replace(SECURITY_NOTICE, '');
@@ -24,6 +36,7 @@ export function extractResultText(event, toolName) {
         }
         return resultTexts.length > 0 ? resultTexts.join("; ") : "";
     }
+    // 白名单工具：从content[].text提取
     if (event.result?.content && Array.isArray(event.result.content)) {
         for (const item of event.result.content) {
             if (item?.text) {
@@ -33,27 +46,270 @@ export function extractResultText(event, toolName) {
     }
     return resultTexts.length > 0 ? resultTexts.join("; ") : "";
 }
-export function processText(resultText) {
+export function processText(resultText, api) {
     const questionText = filterText(resultText);
-    const { text: finalText } = validateAndTruncateText(questionText, MAX_TEXT_LENGTH);
+    // 检查是否超过4096字符限制，进行截断
+    const { text: finalText, truncated } = validateAndTruncateText(questionText, MAX_TEXT_LENGTH);
+    if (truncated) {
+        logger.warn(`[SENTINEL HOOK] filterText exceeds ${MAX_TEXT_LENGTH}. Original length: ${questionText.length}`);
+    }
     return finalText;
 }
 export function parseSecurityResult(response) {
     if (response === null || response === undefined) {
-        throw new Error("Response is null or undefined");
+        throw new Error('Response is null or undefined');
     }
-    if (!response.data || typeof response.data !== "object") {
-        throw new Error("Response.data is missing or not an object");
+    if (response.data === null || response.data === undefined || typeof response.data !== 'object') {
+        throw new Error('Response.data is null, undefined or not an object');
     }
-    const securityResult = response.data.securityResult;
-    if (typeof securityResult !== "string") {
-        throw new Error("Response.data.securityResult is missing or not a string");
+    if (!('securityResult' in response.data) || typeof response.data.securityResult !== 'string') {
+        throw new Error('Response.data.securityResult is missing or not a string');
     }
+    const securityResult = response.data.securityResult;
     if (securityResult !== securityResult.trim()) {
-        throw new Error("Response.data.securityResult contains leading or trailing spaces");
+        throw new Error('Response.data.securityResult contains leading or trailing spaces');
     }
-    if (securityResult !== "ACCEPT" && securityResult !== "REJECT") {
-        throw new Error(`Response.data.securityResult must be "ACCEPT" or "REJECT". Actual: "${securityResult}"`);
+    if (securityResult !== 'ACCEPT' && securityResult !== 'REJECT') {
+        throw new Error(`Response.data.securityResult must be "ACCEPT" or "REJECT". Actual value: "${securityResult}"`);
     }
     return { status: securityResult };
 }
+// 从event对象中提取工具输入参数
+export function extractInputParams(event, toolName) {
+    if (toolName === 'exec') {
+        return event.params?.command || '';
+    }
+    else if (toolName === 'message') {
+        return event.params?.message || '';
+    }
+    return '';
+}
+// 从shell命令中提取文件路径
+export function extractFilePathsFromCommand(command) {
+    if (!command) {
+        return [];
+    }
+    // 命令字符串超过1K则截断
+    let processedCommand = command;
+    if (command.length > MAX_COMMAND_LENGTH) {
+        processedCommand = command.substring(0, MAX_COMMAND_LENGTH);
+    }
+    // 使用空格分割命令字符串
+    const parts = processedCommand.split(' ');
+    const results = [];
+    let currentBaseDir = ''; // 当前基础目录
+    let expectBaseDir = false; // flag：下一个元素是cd后的基础目录
+    // 遍历分割后的命令部分
+    for (const part of parts) {
+        // 忽略空字符串
+        if (!part) {
+            continue;
+        }
+        // 处理cd命令后的基础目录
+        if (expectBaseDir) {
+            currentBaseDir = part;
+            expectBaseDir = false;
+            continue;
+        }
+        // 识别cd命令
+        if (part === 'cd') {
+            expectBaseDir = true;
+            continue;
+        }
+        // 处理代码文件
+        const absolutePath = processCodeFile(part, currentBaseDir);
+        if (absolutePath && !results.includes(absolutePath)) {
+            results.push(absolutePath);
+            if (results.length >= MAX_FILE_COUNT) {
+                break;
+            }
+        }
+    }
+    return results;
+}
+// 检查是否为代码文件
+function isCodeFile(filePath) {
+    const lastDotIndex = filePath.lastIndexOf('.');
+    if (lastDotIndex === -1) {
+        return { isCodeFile: false, cleanPath: null };
+    }
+    let orign_extension = filePath.substring(lastDotIndex + 1).toLowerCase();
+    orign_extension = orign_extension.replace(FILE_EXTENSION_REGEX, ' ');
+    const extension = orign_extension.split(' ')[0];
+    if (!CODE_FILE_EXTENSIONS.includes(extension)) {
+        return { isCodeFile: false, cleanPath: null };
+    }
+    const cleanPath = `${filePath.substring(0, lastDotIndex + 1)}${extension}`;
+    return { isCodeFile: true, cleanPath: cleanPath };
+}
+// 构建绝对路径
+function buildAbsolutePath(filePath, baseDir) {
+    if (path.isAbsolute(filePath)) {
+        return filePath;
+    }
+    if (baseDir) {
+        return `${baseDir}/${filePath}`;
+    }
+    return filePath;
+}
+// 处理代码文件，返回绝对路径
+function processCodeFile(part, currentBaseDir) {
+    const { isCodeFile: isCodeFileResult, cleanPath } = isCodeFile(part);
+    if (!isCodeFileResult) {
+        return null;
+    }
+    return buildAbsolutePath(cleanPath, currentBaseDir);
+}
+// 计算字符串的SHA256哈希值
+export function calculateContentHash(content) {
+    if (!content) {
+        return '';
+    }
+    return crypto.createHash('sha256').update(content, 'utf8').digest('hex');
+}
+// 获取文件大小（KB）
+export function getFileSizeInKB(filePath) {
+    try {
+        const stats = fs.statSync(filePath);
+        return Math.ceil(stats.size / 1024);
+    }
+    catch (error) {
+        return 0;
+    }
+}
+// 动态计算content字段长度，确保body总长度<=4096
+export function adjustContentLength(data, api, fields) {
+    const adjusted = { ...data };
+    let bodyStr = JSON.stringify(adjusted);
+    if (bodyStr.length <= MAX_TEXT_LENGTH) {
+        return adjusted;
+    }
+    // 需要截断指定字段
+    let lastFieldName = '';
+    for (const fieldName of fields) {
+        lastFieldName = fieldName;
+        bodyStr = JSON.stringify(adjusted);
+        const overSize = bodyStr.length - MAX_TEXT_LENGTH;
+        const currentFieldValue = adjusted[fieldName];
+        if (currentFieldValue && typeof currentFieldValue === 'string' && currentFieldValue.length > overSize) {
+            // 从字段头部开始截断
+            adjusted[fieldName] = currentFieldValue.substring(0, currentFieldValue.length - overSize);
+            logger.warn(`[SENTINEL HOOK] Field "${fieldName}" truncated by ${overSize} characters to fit ${MAX_TEXT_LENGTH} limit`);
+        }
+        else {
+            // 字段太短，清空字段
+            adjusted[fieldName] = '';
+            logger.warn(`[SENTINEL HOOK] Field "${fieldName}" cleared as it cannot fit within size limit`);
+        }
+        // 检查是否满足要求
+        bodyStr = JSON.stringify(adjusted);
+        if (bodyStr.length <= MAX_TEXT_LENGTH) {
+            break;
+        }
+    }
+    bodyStr = JSON.stringify(adjusted);
+    if (bodyStr.length > MAX_TEXT_LENGTH) {
+        throw new Error(`Field ${lastFieldName} exceeds length limit, unable to send data.`);
+    }
+    return adjusted;
+}
+// 发送TOOL_INPUT请求并处理响应，返回扫描结果
+async function sendToolInputRequest(postText, api, sessionId) {
+    const response = await callApi(postText, api, sessionId, TOOL_INPUT_ACTION);
+    const result = parseSecurityResult(response);
+    logger.log(`[SENTINEL HOOK] TOOL_INPUT response: status=${result.status}`);
+    return result;
+}
+// 处理exec工具的TOOL_INPUT数据采集，返回最终扫描结果
+export async function handleExecToolInput(event, api, sessionId) {
+    const command = extractInputParams(event, 'exec');
+    if (!command) {
+        logger.log('[SENTINEL HOOK] No command found for exec tool');
+        return null;
+    }
+    // 解析命令提取文件路径
+    const filePaths = extractFilePathsFromCommand(command);
+    if (filePaths.length > 0) {
+        // 场景1：执行代码文件
+        logger.log(`[SENTINEL HOOK] Found ${filePaths.length} file(s) in command`);
+        const nonExistingFiles = [];
+        let lastResult = null;
+        for (const filePath of filePaths) {
+            if (!fs.existsSync(filePath)) {
+                nonExistingFiles.push(filePath);
+                continue;
+            }
+            const fileContent = fs.readFileSync(filePath, 'utf8');
+            const fileHash = calculateContentHash(fileContent);
+            const fileSize = getFileSizeInKB(filePath);
+            const obsUrl = await uploadFileToObsMain(filePath, api, fileHash, sessionId);
+            const toolInputData = { ...TOOL_INPUT_DEFAULT, tool: 'exec', hash: fileHash, url: obsUrl, size: fileSize,
+                source: command, content: fileContent };
+            const adjustedData = adjustContentLength(toolInputData, api, ['content', 'source']);
+            const postText = JSON.stringify(adjustedData);
+            logger.log(`[SENTINEL HOOK] Sending TOOL_INPUT for file: ${path.basename(filePath)}, body length: ${postText.length}`);
+            try {
+                lastResult = await sendToolInputRequest(postText, api, sessionId);
+                if (lastResult.status === 'REJECT') {
+                    return lastResult;
+                }
+            }
+            catch (e) {
+                logger.error(`[SENTINEL HOOK] Sending TOOL_INPUT Failed: ${e}`);
+            }
+        }
+        // 输出不存在的文件列表
+        if (nonExistingFiles.length > 0) {
+            const fileNames = nonExistingFiles.map(f => path.basename(f)).join(', ');
+            logger.log(`[SENTINEL HOOK] Non-existing files: ${fileNames}`);
+        }
+        return lastResult;
+    }
+    else {
+        // 场景2：直接执行代码（heredoc场景）
+        logger.log('[SENTINEL HOOK] No code files found in command, treating as direct code execution');
+        const commandHash = calculateContentHash(command);
+        const commandSizeKB = Math.ceil(Buffer.byteLength(command, 'utf8') / 1024);
+        const toolInputData = { ...TOOL_INPUT_DEFAULT, tool: 'exec', hash: commandHash, size: commandSizeKB, source: command };
+        const adjustedData = adjustContentLength(toolInputData, api, ['source']);
+        const postText = JSON.stringify(adjustedData);
+        logger.log(`[SENTINEL HOOK] Sending TOOL_INPUT for direct code execution, body length: ${postText.length}`);
+        return await sendToolInputRequest(postText, api, sessionId);
+    }
+}
+// 处理message工具的TOOL_INPUT数据采集，返回扫描结果
+export async function handleMessageToolInput(event, api, sessionId) {
+    const message = extractInputParams(event, 'message');
+    if (!message) {
+        logger.log('[SENTINEL HOOK] No message found for message tool');
+        return null;
+    }
+    logger.log(`[SENTINEL HOOK] Processing message tool input, message length: ${message.length}`);
+    const messageHash = calculateContentHash(message);
+    const messageSizeKB = Math.ceil(Buffer.byteLength(message, 'utf8') / 1024);
+    const toolInputData = { ...TOOL_INPUT_DEFAULT, tool: 'message', hash: messageHash, size: messageSizeKB, content: message };
+    const adjustedData = adjustContentLength(toolInputData, api, ['content']);
+    const postText = JSON.stringify(adjustedData);
+    logger.log(`[SENTINEL HOOK] Sending TOOL_INPUT for message, body length: ${postText.length}`);
+    return await sendToolInputRequest(postText, api, sessionId);
+}
+// 处理其他工具（非 exec 和非 message）的 TOOL_INPUT 数据采集，返回扫描结果
+export async function handleOtherToolInput(event, api, sessionId) {
+    const params = event.params;
+    if (!params) {
+        logger.log('[SENTINEL HOOK] No params found for tool');
+        return null;
+    }
+    logger.log(`[SENTINEL HOOK] Processing other tool input, toolName: ${event.toolName}`);
+    // 将 params 序列化为 JSON 字符串
+    const paramsJson = JSON.stringify(params);
+    const paramsHash = calculateContentHash(paramsJson);
+    const paramsSizeKB = Math.ceil(Buffer.byteLength(paramsJson, 'utf8') / 1024);
+    // 创建 toolInputData，将 params 放到 source 字段
+    const toolInputData = { ...TOOL_INPUT_DEFAULT, tool: event.toolName, hash: paramsHash, size: paramsSizeKB, content: paramsJson };
+    // 对 source 字段进行长度截断处理
+    const adjustedData = adjustContentLength(toolInputData, api, ['content']);
+    const postText = JSON.stringify(adjustedData);
+    logger.log(`[SENTINEL HOOK] Sending TOOL_INPUT for ${event.toolName}, body length: ${postText.length}`);
+    return await sendToolInputRequest(postText, api, sessionId);
+}

package/dist/src/file-upload.d.ts

@@ -17,6 +17,11 @@ export declare class XYFileUploadService {
      * Uses completeAndQuery endpoint to get the file URL directly.
      */
     uploadFileAndGetUrl(filePath: string, objectType?: string): Promise<string>;
+    /**
+     * Upload a file and return a preview-able URL (needPreview=true).
+     * Same as uploadFileAndGetUrl but adds needPreview flag to get a directly viewable URL.
+     */
+    uploadFileAndGetPreviewUrl(filePath: string, objectType?: string): Promise<string>;
     /**
      * Upload multiple files and return their file IDs.
      */

package/dist/src/file-upload.js

@@ -235,6 +235,108 @@ export class XYFileUploadService {
             }
         }
     }
+    /**
+     * Upload a file and return a preview-able URL (needPreview=true).
+     * Same as uploadFileAndGetUrl but adds needPreview flag to get a directly viewable URL.
+     */
+    async uploadFileAndGetPreviewUrl(filePath, objectType = "TEMPORARY_MATERIAL_DOC") {
+        let localFilePath = filePath;
+        let isTempFile = false;
+        try {
+            // Handle remote URLs by downloading first
+            if (isRemoteUrl(filePath)) {
+                localFilePath = await downloadToTempFile(filePath);
+                isTempFile = true;
+            }
+            // Read file
+            const fileBuffer = await fs.readFile(localFilePath);
+            const fileName = path.basename(localFilePath);
+            const fileSha256 = calculateSHA256(fileBuffer);
+            const fileSize = fileBuffer.length;
+            // Phase 1: Prepare
+            logger.log(`[XY File Upload] Phase 1 (preview): Prepare upload for ${fileName}`);
+            const prepareResp = await fetch(`${this.baseUrl}/osms/v1/file/manager/prepare`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "x-uid": this.uid,
+                    "x-api-key": this.apiKey,
+                    "x-request-from": "openclaw",
+                },
+                body: JSON.stringify({
+                    objectType,
+                    fileName,
+                    fileSha256,
+                    fileSize,
+                    fileOwnerInfo: {
+                        uid: this.uid,
+                        teamId: this.uid,
+                    },
+                    useEdge: false,
+                }),
+            });
+            if (!prepareResp.ok) {
+                throw new Error(`Prepare failed: HTTP ${prepareResp.status}`);
+            }
+            const prepareData = await prepareResp.json();
+            if (prepareData.code !== "0") {
+                throw new Error(`Prepare failed: ${prepareData.desc}`);
+            }
+            const { objectId, draftId, uploadInfos } = prepareData;
+            logger.log(`[XY File Upload] Prepare (preview) complete: objectId=${objectId}, draftId=${draftId}`);
+            // Phase 2: Upload
+            logger.log(`[XY File Upload] Phase 2 (preview): Upload file data`);
+            const uploadInfo = uploadInfos[0];
+            const uploadResp = await fetch(uploadInfo.url, {
+                method: uploadInfo.method,
+                headers: uploadInfo.headers,
+                body: fileBuffer,
+            });
+            if (!uploadResp.ok) {
+                throw new Error(`Upload failed: HTTP ${uploadResp.status}`);
+            }
+            logger.log(`[XY File Upload] Upload (preview) complete`);
+            // Phase 3: CompleteAndQuery with needPreview=true
+            logger.log(`[XY File Upload] Phase 3 (preview): CompleteAndQuery with needPreview=true`);
+            const completeResp = await fetch(`${this.baseUrl}/osms/v1/file/manager/completeAndQuery`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "x-uid": this.uid,
+                    "x-api-key": this.apiKey,
+                    "x-request-from": "openclaw",
+                },
+                body: JSON.stringify({
+                    objectId,
+                    draftId,
+                    needPreview: true,
+                    expireTime: 259200,
+                }),
+            });
+            if (!completeResp.ok) {
+                throw new Error(`CompleteAndQuery (preview) failed: HTTP ${completeResp.status}`);
+            }
+            const completeData = await completeResp.json();
+            const fileUrl = completeData?.fileDetailInfo?.url || "";
+            if (!fileUrl) {
+                throw new Error("No file URL returned from completeAndQuery (preview)");
+            }
+            logger.log(`[XY File Upload] File upload with preview URL successful`);
+            return fileUrl;
+        }
+        catch (error) {
+            logger.error(`[XY File Upload] File upload with preview URL failed for ${filePath}:`, error);
+            throw error;
+        }
+        finally {
+            if (isTempFile) {
+                try {
+                    await fs.unlink(localFilePath);
+                }
+                catch { }
+            }
+        }
+    }
     /**
      * Upload multiple files and return their file IDs.
      */