@caoruhua/open-claude-remote 1.0.9 → 1.3.6

package/dist/backend/src/api/file-routes.js

@@ -1,30 +1,17 @@
 import { Router } from 'express';
 import { readFile, stat, readdir } from 'node:fs/promises';
 import { createReadStream } from 'node:fs';
-import { extname, join, relative, resolve, normalize } from 'node:path';
+import { extname, join, relative, basename, resolve, normalize } from 'node:path';
 import { loadUserConfig } from '../config.js';
 import { logger } from '../logger/logger.js';
+import { SUPPORTED_EXTENSIONS, IMAGE_EXTENSIONS, PREVIEWABLE_EXTENSIONS, CONVERTIBLE_TO_PDF, FILE_MIME_TYPES, getFileCategory, } from '../../../shared/index.js';
+import { createConversionTask, getTaskStatus, startConversion, isSofficeAvailable, getLibreOfficeInstallGuide, TEMP_DIR } from '../services/pptx-converter.js';
 /** 文件大小限制：5MB（与 PRD 一致） */
 const MAX_FILE_SIZE = 5 * 1024 * 1024;
-/** 允许的文件扩展名 */
-const ALLOWED_EXTENSIONS = ['.md', '.markdown'];
-/** 允许的图片扩展名 */
-const ALLOWED_IMAGE_EXTENSIONS = ['.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg', '.ico', '.bmp'];
-/** 图片 MIME 类型映射 */
-const IMAGE_MIME_TYPES = {
-    '.png': 'image/png',
-    '.jpg': 'image/jpeg',
-    '.jpeg': 'image/jpeg',
-    '.gif': 'image/gif',
-    '.webp': 'image/webp',
-    '.svg': 'image/svg+xml',
-    '.ico': 'image/x-icon',
-    '.bmp': 'image/bmp',
-};
 /** 最大扫描文件数限制 */
 const MAX_FILES = 1000;
 /** 跳过的目录 */
-const SKIP_DIRS = ['node_modules', 'dist', 'build', '.git'];
+const SKIP_DIRS = ['node_modules', 'dist', 'build', '.git', '.svn', '.hg'];
 /**
  * 检查路径是否在允许的目录白名单范围内
  * @param path - 要检查的路径（绝对路径）
@@ -33,6 +20,10 @@ const SKIP_DIRS = ['node_modules', 'dist', 'build', '.git'];
  */
 function isPathAllowed(path, allowedCwds) {
     const normalizedPath = normalize(path);
+    // 允许访问 PPTX 转换输出目录
+    if (normalizedPath.startsWith(TEMP_DIR + '/') || normalizedPath === TEMP_DIR) {
+        return true;
+    }
     return allowedCwds.some((cwd) => {
         const normalizedCwd = normalize(cwd);
         return normalizedPath.startsWith(normalizedCwd + '/') || normalizedPath === normalizedCwd;
@@ -87,24 +78,39 @@ function getAllowedCwds(instanceManager) {
     return [...new Set([...configWorkspaces, ...instanceCwds])];
 }
 /**
- * 递归扫描目录中的 Markdown 文件
- * @param dir - 要扫描的目录
- * @param baseDir - 基准目录（用于计算相对路径）
- * @param allowedCwds - 允许的目录白名单
- * @param files - 已收集的文件列表（递归用）
- * @returns Markdown 文件列表
+ * 构建目录树节点
  */
-async function scanMarkdownFiles(dir, baseDir, allowedCwds, files = []) {
+function buildDirectoryNode(name, path, relativePath) {
+    return {
+        name,
+        path,
+        relativePath,
+        children: [],
+        fileCount: 0,
+        typeCounts: {
+            markdown: 0,
+            pdf: 0,
+            presentation: 0,
+            image: 0,
+            all: 0,
+        },
+    };
+}
+async function scanFiles(dir, baseDir, allowedCwds, result, category = 'all', searchQuery, currentNode) {
     // 安全检查：路径必须在白名单范围内
     if (!isPathAllowed(dir, allowedCwds)) {
         logger.warn({ dir, allowedCwds }, 'Scan rejected: directory not allowed');
-        return files;
+        return;
+    }
+    // 初始化当前节点
+    if (!currentNode) {
+        currentNode = result.rootNode;
     }
     try {
         const entries = await readdir(dir, { withFileTypes: true });
         for (const entry of entries) {
             // 达到最大文件数限制时停止扫描
-            if (files.length >= MAX_FILES) {
+            if (result.files.length >= MAX_FILES) {
                 logger.warn({ dir, maxFiles: MAX_FILES }, 'Scan stopped: max file limit reached');
                 break;
             }
@@ -114,27 +120,64 @@ async function scanMarkdownFiles(dir, baseDir, allowedCwds, files = []) {
                 if (entry.name.startsWith('.') || SKIP_DIRS.includes(entry.name)) {
                     continue;
                 }
+                // 创建子目录节点
+                const relativePath = relative(baseDir, fullPath);
+                const childNode = buildDirectoryNode(entry.name, fullPath, relativePath.startsWith('.') ? relativePath : `./${relativePath}`);
+                currentNode.children.push(childNode);
                 // 递归扫描子目录
-                await scanMarkdownFiles(fullPath, baseDir, allowedCwds, files);
+                await scanFiles(fullPath, baseDir, allowedCwds, result, category, searchQuery, childNode);
+                // 汇总子目录统计
+                currentNode.fileCount += childNode.fileCount;
+                for (const cat of Object.keys(childNode.typeCounts)) {
+                    currentNode.typeCounts[cat] += childNode.typeCounts[cat];
+                }
             }
             else if (entry.isFile()) {
                 // 检查扩展名
                 const ext = extname(entry.name).toLowerCase();
-                if (!ALLOWED_EXTENSIONS.includes(ext)) {
+                if (!SUPPORTED_EXTENSIONS.includes(ext)) {
                     continue;
                 }
+                // 获取文件分类
+                const fileCategory = getFileCategory(entry.name);
+                // ✅ 先统计 typeCounts（不受 category 影响）
+                currentNode.typeCounts[fileCategory]++;
+                currentNode.typeCounts.all++;
+                // 分类筛选（只影响 files 数组，不影响 typeCounts）
+                if (category !== 'all' && fileCategory !== category) {
+                    continue; // 不加入 files，但 typeCounts 已统计
+                }
                 try {
                     const fileStat = await stat(fullPath);
                     const relativePath = relative(baseDir, fullPath);
-                    files.push({
+                    // 搜索筛选（搜索时需要回退 typeCounts，因为搜索结果不应显示被排除的文件）
+                    if (searchQuery) {
+                        const searchLower = searchQuery.toLowerCase();
+                        if (!entry.name.toLowerCase().includes(searchLower) &&
+                            !relativePath.toLowerCase().includes(searchLower)) {
+                            // 搜索过滤时回退 typeCounts
+                            currentNode.typeCounts[fileCategory]--;
+                            currentNode.typeCounts.all--;
+                            continue;
+                        }
+                    }
+                    const fileItem = {
                         filename: entry.name,
                         absolutePath: fullPath,
                         relativePath: relativePath.startsWith('.') ? relativePath : `./${relativePath}`,
                         size: fileStat.size,
                         modifiedAt: fileStat.mtime.toISOString(),
-                    });
+                        category: fileCategory,
+                        extension: ext,
+                    };
+                    result.files.push(fileItem);
+                    // 更新当前目录统计（fileCount 统计过滤后的文件数）
+                    currentNode.fileCount++;
                 }
                 catch (err) {
+                    // stat 失败时回退 typeCounts
+                    currentNode.typeCounts[fileCategory]--;
+                    currentNode.typeCounts.all--;
                     logger.debug({ path: fullPath, err: String(err) }, 'Failed to stat file during scan');
                 }
             }
@@ -143,15 +186,16 @@ async function scanMarkdownFiles(dir, baseDir, allowedCwds, files = []) {
     catch (err) {
         logger.warn({ dir, err: String(err) }, 'Failed to read directory during scan');
     }
-    return files;
 }
 export function createFileRoutes(authModule, instanceManager) {
     const router = Router();
     /**
-     * GET /api/file/list - 列出当前工作目录下的 Markdown 文件
+     * GET /api/file/list - 列出当前工作目录下的文件
      * Query params:
      *   - instanceId: 可选，指定实例 ID，优先使用该实例的 cwd
      *   - cwd: 可选，指定扫描目录（默认使用第一个实例的 cwd）
+     *   - category: 可选，文件分类筛选（markdown|pdf|presentation|image|all）
+     *   - search: 可选，搜索关键词（匹配文件名和路径）
      */
     router.get('/file/list', authModule.requireAuth, async (req, res) => {
         try {
@@ -164,25 +208,40 @@ export function createFileRoutes(authModule, instanceManager) {
                     files: [],
                     cwd: '',
                     total: 0,
+                    directoryTree: undefined,
+                    typeCounts: undefined,
                 });
                 return;
             }
-            // 确定扫描目录：优先级 instanceId > cwd > 默认第一个允许目录
+            // 确定扫描目录：
+            // - 如果提供了 cwd，使用 cwd（需要验证是否在允许范围内）
+            // - 如果只提供了 instanceId，使用实例的 cwd
+            // - 否则使用默认第一个允许目录
             const instanceId = req.query.instanceId;
             const queryCwd = req.query.cwd;
             let baseDir;
+            // 首先获取实例的 cwd（用于验证 cwd 是否在实例范围内）
+            let instanceCwd;
             if (instanceId) {
-                // 通过 instanceId 获取实例的 cwd
                 const instance = instanceManager.getInstance(instanceId);
                 if (!instance) {
                     logger.warn({ instanceId }, 'File list rejected: instance not found');
                     res.status(404).json({ error: 'Instance not found' });
                     return;
                 }
-                baseDir = instance.cwd;
+                instanceCwd = instance.cwd;
             }
-            else if (queryCwd) {
-                baseDir = normalizePath(queryCwd, allowedCwds[0]) || allowedCwds[0];
+            if (queryCwd) {
+                // 使用 cwd 参数，但需要验证路径是否在允许范围内
+                const resolvedCwd = normalizePath(queryCwd, instanceCwd || allowedCwds[0]);
+                if (!resolvedCwd) {
+                    res.status(400).json({ error: 'Invalid cwd path format' });
+                    return;
+                }
+                baseDir = resolvedCwd;
+            }
+            else if (instanceCwd) {
+                baseDir = instanceCwd;
             }
             else {
                 baseDir = allowedCwds[0];
@@ -195,22 +254,33 @@ export function createFileRoutes(authModule, instanceManager) {
                 });
                 return;
             }
-            logger.info({ baseDir }, 'Scanning for Markdown files');
-            // 递归扫描 Markdown 文件
-            const files = await scanMarkdownFiles(baseDir, baseDir, allowedCwds);
+            // 解析查询参数
+            const category = req.query.category || 'all';
+            const searchQuery = req.query.search;
+            logger.info({ baseDir, category, search: searchQuery }, 'Scanning for files');
+            // 初始化扫描结果
+            const scanResult = {
+                files: [],
+                rootNode: buildDirectoryNode(basename(baseDir), baseDir, './'),
+            };
+            // 递归扫描文件
+            await scanFiles(baseDir, baseDir, allowedCwds, scanResult, category, searchQuery);
             // 按修改时间倒序排序
-            files.sort((a, b) => new Date(b.modifiedAt).getTime() - new Date(a.modifiedAt).getTime());
+            scanResult.files.sort((a, b) => new Date(b.modifiedAt).getTime() - new Date(a.modifiedAt).getTime());
             // 限制返回数量
-            const limitedFiles = files.slice(0, 100);
+            const limitedFiles = scanResult.files.slice(0, 100);
             logger.info({
-                scanned: files.length,
+                scanned: scanResult.files.length,
                 returned: limitedFiles.length,
                 cwd: baseDir,
-            }, 'Markdown file scan completed');
+                category,
+            }, 'File scan completed');
             const response = {
                 files: limitedFiles,
                 cwd: baseDir,
                 total: limitedFiles.length,
+                directoryTree: scanResult.rootNode.children.length > 0 ? scanResult.rootNode : undefined,
+                typeCounts: scanResult.rootNode.typeCounts,
             };
             res.json(response);
         }
@@ -220,15 +290,17 @@ export function createFileRoutes(authModule, instanceManager) {
         }
     });
     /**
-     * GET /api/file/read - 读取 Markdown 文件内容
+     * GET /api/file/content - 读取文件内容（统一接口，支持文本和二进制）
      * Query params:
      *   - instanceId: 可选，指定实例 ID，用于解析相对路径
      *   - path: 文件路径（绝对路径或相对于 cwd 的相对路径）
+     *   - asBase64: 可选，是否以 base64 返回（默认为文本，图片/PDF自动转为base64）
      */
-    router.get('/file/read', authModule.requireAuth, async (req, res) => {
+    router.get('/file/content', authModule.requireAuth, async (req, res) => {
         try {
             const rawPath = req.query.path;
             const instanceId = req.query.instanceId;
+            const asBase64 = req.query.asBase64 === 'true';
             if (!rawPath) {
                 res.status(400).json({ error: 'Missing path parameter' });
                 return;
@@ -237,7 +309,7 @@ export function createFileRoutes(authModule, instanceManager) {
             const allowedCwds = getAllowedCwds(instanceManager);
             // 如果白名单为空，拒绝所有请求
             if (allowedCwds.length === 0) {
-                logger.warn({ path: rawPath }, 'File read rejected: no allowed directories');
+                logger.warn({ path: rawPath }, 'File content request rejected: no allowed directories');
                 res.status(403).json({
                     error: 'No allowed directories configured. Start an instance first.',
                 });
@@ -248,7 +320,7 @@ export function createFileRoutes(authModule, instanceManager) {
             if (instanceId) {
                 const instance = instanceManager.getInstance(instanceId);
                 if (!instance) {
-                    logger.warn({ instanceId }, 'File read rejected: instance not found');
+                    logger.warn({ instanceId }, 'File content request rejected: instance not found');
                     res.status(404).json({ error: 'Instance not found' });
                     return;
                 }
@@ -264,17 +336,17 @@ export function createFileRoutes(authModule, instanceManager) {
             }
             // 安全检查：路径必须在白名单范围内
             if (!isPathAllowed(absolutePath, allowedCwds)) {
-                logger.warn({ path: absolutePath, allowedCwds }, 'File read rejected: path not allowed');
+                logger.warn({ path: absolutePath, allowedCwds }, 'File content request rejected: path not allowed');
                 res.status(403).json({
                     error: 'Access denied. File is outside allowed directories.',
                 });
                 return;
             }
-            // 扩展名检查
+            // 扩展名检查（只允许支持的文件类型）
             const ext = extname(absolutePath).toLowerCase();
-            if (!ALLOWED_EXTENSIONS.includes(ext)) {
+            if (!SUPPORTED_EXTENSIONS.includes(ext) && !PREVIEWABLE_EXTENSIONS.includes(ext)) {
                 res.status(400).json({
-                    error: 'Only Markdown files (.md, .markdown) are allowed',
+                    error: `Unsupported file type. Supported: ${SUPPORTED_EXTENSIONS.join(', ')}`,
                 });
                 return;
             }
@@ -300,28 +372,133 @@ export function createFileRoutes(authModule, instanceManager) {
                 });
                 return;
             }
+            const filename = basename(absolutePath);
+            const mimeType = FILE_MIME_TYPES[ext] || 'application/octet-stream';
+            const isBinary = IMAGE_EXTENSIONS.includes(ext) || ext === '.pdf';
             // 读取文件内容
-            const content = await readFile(absolutePath, 'utf-8');
-            const filename = absolutePath.split('/').pop() || absolutePath;
-            logger.info({ path: absolutePath, size: fileStat.size }, 'File read successfully');
+            let content;
+            let responseIsBase64 = false;
+            if (isBinary || asBase64) {
+                // 二进制文件或强制 base64：读取并转为 base64
+                const buffer = await readFile(absolutePath);
+                content = buffer.toString('base64');
+                responseIsBase64 = true;
+            }
+            else {
+                // 文本文件：直接读取
+                content = await readFile(absolutePath, 'utf-8');
+            }
+            logger.info({ path: absolutePath, size: fileStat.size, mimeType }, 'File content served');
             const response = {
                 content,
                 path: absolutePath,
                 filename,
                 size: fileStat.size,
+                isBase64: responseIsBase64,
+                mimeType,
             };
             res.json(response);
         }
+        catch (err) {
+            logger.error({ err }, 'Failed to read file content');
+            res.status(500).json({ error: 'Internal server error' });
+        }
+    });
+    /**
+     * GET /api/file/read - 读取 Markdown 文件内容（向后兼容）
+     * 保留原有接口行为，仅支持 Markdown 文件
+     */
+    router.get('/file/read', authModule.requireAuth, async (req, res) => {
+        try {
+            const rawPath = req.query.path;
+            const instanceId = req.query.instanceId;
+            if (!rawPath) {
+                res.status(400).json({ error: 'Missing path parameter' });
+                return;
+            }
+            // 获取允许的目录白名单
+            const allowedCwds = getAllowedCwds(instanceManager);
+            if (allowedCwds.length === 0) {
+                logger.warn({ path: rawPath }, 'File read rejected: no allowed directories');
+                res.status(403).json({
+                    error: 'No allowed directories configured. Start an instance first.',
+                });
+                return;
+            }
+            // 确定基准目录
+            let baseDir;
+            if (instanceId) {
+                const instance = instanceManager.getInstance(instanceId);
+                if (!instance) {
+                    logger.warn({ instanceId }, 'File read rejected: instance not found');
+                    res.status(404).json({ error: 'Instance not found' });
+                    return;
+                }
+                baseDir = instance.cwd;
+            }
+            else {
+                baseDir = allowedCwds[0];
+            }
+            const absolutePath = normalizePath(rawPath, baseDir);
+            if (!absolutePath) {
+                res.status(400).json({ error: 'Invalid path format' });
+                return;
+            }
+            // 安全检查
+            if (!isPathAllowed(absolutePath, allowedCwds)) {
+                logger.warn({ path: absolutePath, allowedCwds }, 'File read rejected: path not allowed');
+                res.status(403).json({
+                    error: 'Access denied. File is outside allowed directories.',
+                });
+                return;
+            }
+            // 仅允许 Markdown 文件（向后兼容）
+            const ext = extname(absolutePath).toLowerCase();
+            if (!['.md', '.markdown'].includes(ext)) {
+                res.status(400).json({
+                    error: 'Only Markdown files (.md, .markdown) are allowed',
+                });
+                return;
+            }
+            // 检查文件
+            let fileStat;
+            try {
+                fileStat = await stat(absolutePath);
+            }
+            catch {
+                logger.debug({ path: absolutePath }, 'File not found');
+                res.status(404).json({ error: 'File not found' });
+                return;
+            }
+            if (!fileStat.isFile()) {
+                res.status(400).json({ error: 'Path is not a file' });
+                return;
+            }
+            if (fileStat.size > MAX_FILE_SIZE) {
+                res.status(413).json({
+                    error: `File too large. Maximum size is ${MAX_FILE_SIZE / 1024 / 1024}MB`,
+                });
+                return;
+            }
+            // 读取文件内容
+            const content = await readFile(absolutePath, 'utf-8');
+            const filename = basename(absolutePath);
+            logger.info({ path: absolutePath, size: fileStat.size }, 'Markdown file read successfully');
+            res.json({
+                content,
+                path: absolutePath,
+                filename,
+                size: fileStat.size,
+            });
+        }
         catch (err) {
             logger.error({ err }, 'Failed to read file');
             res.status(500).json({ error: 'Internal server error' });
         }
     });
     /**
-     * GET /api/file/asset - 获取图片等静态资源文件
-     * Query params:
-     *   - instanceId: 可选，指定实例 ID，用于解析相对路径
-     *   - path: 文件路径（绝对路径或相对于 cwd 的相对路径）
+     * GET /api/file/asset - 获取图片等静态资源文件（向后兼容）
+     * 支持流式传输，保留原有行为
      */
     router.get('/file/asset', authModule.requireAuth, async (req, res) => {
         try {
@@ -333,7 +510,6 @@ export function createFileRoutes(authModule, instanceManager) {
             }
             // 获取允许的目录白名单
             const allowedCwds = getAllowedCwds(instanceManager);
-            // 如果白名单为空，拒绝所有请求
             if (allowedCwds.length === 0) {
                 logger.warn({ path: rawPath }, 'Asset request rejected: no allowed directories');
                 res.status(403).json({
@@ -341,7 +517,7 @@ export function createFileRoutes(authModule, instanceManager) {
                 });
                 return;
             }
-            // 确定基准目录：优先级 instanceId > 默认第一个允许目录
+            // 确定基准目录
             let baseDir;
             if (instanceId) {
                 const instance = instanceManager.getInstance(instanceId);
@@ -360,7 +536,7 @@ export function createFileRoutes(authModule, instanceManager) {
                 res.status(400).json({ error: 'Invalid path format' });
                 return;
             }
-            // 安全检查：路径必须在白名单范围内
+            // 安全检查
             if (!isPathAllowed(absolutePath, allowedCwds)) {
                 logger.warn({ path: absolutePath, allowedCwds }, 'Asset request rejected: path not allowed');
                 res.status(403).json({
@@ -370,13 +546,13 @@ export function createFileRoutes(authModule, instanceManager) {
             }
             // 扩展名检查（仅允许图片格式）
             const ext = extname(absolutePath).toLowerCase();
-            if (!ALLOWED_IMAGE_EXTENSIONS.includes(ext)) {
+            if (!IMAGE_EXTENSIONS.includes(ext)) {
                 res.status(400).json({
-                    error: `Only image files (${ALLOWED_IMAGE_EXTENSIONS.join(', ')}) are allowed`,
+                    error: `Only image files (${IMAGE_EXTENSIONS.join(', ')}) are allowed`,
                 });
                 return;
             }
-            // 检查文件是否存在并获取大小
+            // 检查文件
             let fileStat;
             try {
                 fileStat = await stat(absolutePath);
@@ -386,12 +562,10 @@ export function createFileRoutes(authModule, instanceManager) {
                 res.status(404).json({ error: 'File not found' });
                 return;
             }
-            // 检查是否为文件
             if (!fileStat.isFile()) {
                 res.status(400).json({ error: 'Path is not a file' });
                 return;
             }
-            // 文件大小检查
             if (fileStat.size > MAX_FILE_SIZE) {
                 res.status(413).json({
                     error: `File too large. Maximum size is ${MAX_FILE_SIZE / 1024 / 1024}MB`,
@@ -399,7 +573,7 @@ export function createFileRoutes(authModule, instanceManager) {
                 return;
             }
             // 设置 Content-Type
-            const contentType = IMAGE_MIME_TYPES[ext] || 'application/octet-stream';
+            const contentType = FILE_MIME_TYPES[ext] || 'application/octet-stream';
             res.setHeader('Content-Type', contentType);
             res.setHeader('Content-Length', fileStat.size);
             res.setHeader('Cache-Control', 'public, max-age=31536000');
@@ -419,6 +593,228 @@ export function createFileRoutes(authModule, instanceManager) {
             res.status(500).json({ error: 'Internal server error' });
         }
     });
+    /**
+     * GET /api/file/download - 下载文件（支持所有受支持的文件类型）
+     * 设置 Content-Disposition: attachment 触发浏览器原生下载
+     */
+    router.get('/file/download', authModule.requireAuth, async (req, res) => {
+        try {
+            const rawPath = req.query.path;
+            const instanceId = req.query.instanceId;
+            if (!rawPath) {
+                res.status(400).json({ error: 'Missing path parameter' });
+                return;
+            }
+            const allowedCwds = getAllowedCwds(instanceManager);
+            if (allowedCwds.length === 0) {
+                logger.warn({ path: rawPath }, 'Download request rejected: no allowed directories');
+                res.status(403).json({
+                    error: 'No allowed directories configured. Start an instance first.',
+                });
+                return;
+            }
+            let baseDir;
+            if (instanceId) {
+                const instance = instanceManager.getInstance(instanceId);
+                if (!instance) {
+                    logger.warn({ instanceId }, 'Download request rejected: instance not found');
+                    res.status(404).json({ error: 'Instance not found' });
+                    return;
+                }
+                baseDir = instance.cwd;
+            }
+            else {
+                baseDir = allowedCwds[0];
+            }
+            const absolutePath = normalizePath(rawPath, baseDir);
+            if (!absolutePath) {
+                res.status(400).json({ error: 'Invalid path format' });
+                return;
+            }
+            if (!isPathAllowed(absolutePath, allowedCwds)) {
+                logger.warn({ path: absolutePath, allowedCwds }, 'Download request rejected: path not allowed');
+                res.status(403).json({
+                    error: 'Access denied. File is outside allowed directories.',
+                });
+                return;
+            }
+            // 扩展名检查（允许所有受支持的文件类型）
+            const ext = extname(absolutePath).toLowerCase();
+            if (!SUPPORTED_EXTENSIONS.includes(ext)) {
+                res.status(400).json({
+                    error: `Unsupported file type. Supported: ${SUPPORTED_EXTENSIONS.join(', ')}`,
+                });
+                return;
+            }
+            let fileStat;
+            try {
+                fileStat = await stat(absolutePath);
+            }
+            catch {
+                logger.debug({ path: absolutePath }, 'Download file not found');
+                res.status(404).json({ error: 'File not found' });
+                return;
+            }
+            if (!fileStat.isFile()) {
+                res.status(400).json({ error: 'Path is not a file' });
+                return;
+            }
+            if (fileStat.size > MAX_FILE_SIZE) {
+                res.status(413).json({
+                    error: `File too large. Maximum size is ${MAX_FILE_SIZE / 1024 / 1024}MB`,
+                });
+                return;
+            }
+            const filename = basename(absolutePath);
+            const contentType = FILE_MIME_TYPES[ext] || 'application/octet-stream';
+            const isTextFile = contentType.startsWith('text/');
+            // 文本类型显式声明 charset=utf-8，避免浏览器按系统默认编码解析导致中文乱码
+            res.setHeader('Content-Type', isTextFile ? `${contentType}; charset=utf-8` : contentType);
+            // 文本文件添加 UTF-8 BOM (3 bytes)，帮助移动端应用正确检测编码
+            const UTF8_BOM = Buffer.from([0xEF, 0xBB, 0xBF]);
+            res.setHeader('Content-Length', isTextFile ? fileStat.size + UTF8_BOM.length : fileStat.size);
+            // RFC 5987 编码文件名，支持中文等非 ASCII 字符
+            const encodedFilename = encodeURIComponent(filename).replace(/'/g, '%27');
+            // ASCII fallback for filename, UTF-8 encoded for filename*
+            const asciiFilename = filename.replace(/[^\x20-\x7E]/g, '_');
+            res.setHeader('Content-Disposition', `attachment; filename="${asciiFilename}"; filename*=UTF-8''${encodedFilename}`);
+            // 文本文件先写入 BOM，再 pipe 文件流
+            if (isTextFile) {
+                res.write(UTF8_BOM);
+            }
+            const fileStream = createReadStream(absolutePath);
+            fileStream.pipe(res);
+            fileStream.on('error', (err) => {
+                logger.error({ path: absolutePath, err: String(err) }, 'Failed to stream download file');
+                if (!res.headersSent) {
+                    res.status(500).json({ error: 'Failed to read file' });
+                }
+            });
+            logger.info({ path: absolutePath, size: fileStat.size, filename }, 'File download served');
+        }
+        catch (err) {
+            logger.error({ err }, 'Failed to serve download');
+            res.status(500).json({ error: 'Internal server error' });
+        }
+    });
+    /**
+     * POST /api/file/convert - 创建 PPTX 转换任务
+     * Body: { path: string, instanceId?: string }
+     */
+    router.post('/file/convert', authModule.requireAuth, async (req, res) => {
+        try {
+            const rawPath = req.body.path;
+            const instanceId = req.body.instanceId;
+            if (!rawPath) {
+                res.status(400).json({ error: 'Missing path parameter' });
+                return;
+            }
+            // 检查文件扩展名
+            const ext = extname(rawPath).toLowerCase();
+            if (!CONVERTIBLE_TO_PDF.includes(ext)) {
+                res.status(400).json({
+                    error: 'Only PPTX files can be converted',
+                    supported: CONVERTIBLE_TO_PDF,
+                });
+                return;
+            }
+            // 获取允许的目录白名单
+            const allowedCwds = getAllowedCwds(instanceManager);
+            if (allowedCwds.length === 0) {
+                res.status(403).json({ error: 'No allowed directories configured' });
+                return;
+            }
+            // 确定基准目录
+            let baseDir;
+            if (instanceId) {
+                const instance = instanceManager.getInstance(instanceId);
+                if (!instance) {
+                    res.status(404).json({ error: 'Instance not found' });
+                    return;
+                }
+                baseDir = instance.cwd;
+            }
+            else {
+                baseDir = allowedCwds[0];
+            }
+            const absolutePath = normalizePath(rawPath, baseDir);
+            if (!absolutePath) {
+                res.status(400).json({ error: 'Invalid path format' });
+                return;
+            }
+            // 安全检查
+            if (!isPathAllowed(absolutePath, allowedCwds)) {
+                res.status(403).json({ error: 'Access denied' });
+                return;
+            }
+            // 检查文件是否存在
+            try {
+                await stat(absolutePath);
+            }
+            catch {
+                res.status(404).json({ error: 'File not found' });
+                return;
+            }
+            // 创建转换任务
+            const task = await createConversionTask(absolutePath);
+            // 异步启动转换
+            startConversion(task.id);
+            logger.info({ taskId: task.id, path: absolutePath }, 'Created conversion task');
+            res.json({
+                taskId: task.id,
+                status: task.status,
+            });
+        }
+        catch (err) {
+            logger.error({ err }, 'Failed to create conversion task');
+            res.status(500).json({ error: 'Internal server error' });
+        }
+    });
+    /**
+     * GET /api/file/convert/status - 查询转换任务状态
+     * Query: { taskId: string }
+     */
+    router.get('/file/convert/status', authModule.requireAuth, async (req, res) => {
+        try {
+            const taskId = req.query.taskId;
+            if (!taskId) {
+                res.status(400).json({ error: 'Missing taskId parameter' });
+                return;
+            }
+            const task = getTaskStatus(taskId);
+            if (!task) {
+                res.status(404).json({ error: 'Task not found' });
+                return;
+            }
+            const response = {
+                taskId: task.id,
+                status: task.status,
+                pdfPath: task.status === 'completed' ? task.outputPath : undefined,
+                error: task.error,
+            };
+            res.json(response);
+        }
+        catch (err) {
+            logger.error({ err }, 'Failed to get conversion status');
+            res.status(500).json({ error: 'Internal server error' });
+        }
+    });
+    /**
+     * GET /api/file/convert/check - 检查 LibreOffice 是否可用
+     */
+    router.get('/file/convert/check', authModule.requireAuth, async (req, res) => {
+        try {
+            const isAvailable = await isSofficeAvailable();
+            res.json({
+                available: isAvailable,
+                installGuide: !isAvailable ? getLibreOfficeInstallGuide() : undefined,
+            });
+        }
+        catch (err) {
+            logger.error({ err }, 'Failed to check LibreOffice availability');
+            res.status(500).json({ error: 'Internal server error' });
+        }
+    });
     return router;
 }
 //# sourceMappingURL=file-routes.js.map