aws-runtime-bridge 1.4.0 → 1.6.1

package/dist/services/workspace-files.js

@@ -2,8 +2,23 @@
  * 工作区文件服务
  * 负责在工作区范围内安全地浏览、读取与保存文件。
  */
+import { createReadStream, createWriteStream, promises as fs } from 'node:fs';
 import path from 'node:path';
-import { promises as fs } from 'node:fs';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { TextDecoder } from 'node:util';
+import { createGunzip } from 'node:zlib';
+import * as tar from 'tar';
+import unzipper from 'unzipper';
+const { ZipArchive } = await import('archiver');
+const ARCHIVE_LIMITS = {
+    maxEntries: 10_000,
+    maxFileBytes: 512 * 1024 * 1024,
+    maxTotalBytes: 2 * 1024 * 1024 * 1024,
+    maxPathDepth: 64,
+    maxPathLength: 4096,
+};
+const GBK_DECODER = new TextDecoder('gbk');
 function toDisplayPath(targetPath) {
     return String(targetPath || '').replace(/\\/g, '/');
 }
@@ -17,6 +32,22 @@ function resolveWorkspaceRoot(workspacePath) {
     }
     return normalizedWorkspacePath;
 }
+async function resolveWorkspaceRootRealpath(workspacePath) {
+    const workspaceRoot = resolveWorkspaceRoot(workspacePath);
+    const realWorkspaceRoot = await fs.realpath(workspaceRoot);
+    const stat = await fs.stat(realWorkspaceRoot);
+    if (!stat.isDirectory()) {
+        throw new Error(`Workspace path is not a directory: ${workspaceRoot}`);
+    }
+    return realWorkspaceRoot;
+}
+async function resolveWorkspaceRoots(workspacePath) {
+    const requestedRoot = resolveWorkspaceRoot(workspacePath);
+    return {
+        requestedRoot,
+        workspaceRoot: await resolveWorkspaceRootRealpath(workspacePath),
+    };
+}
 /**
  * 判断目标路径是否位于工作区内。
  */
@@ -29,15 +60,44 @@ function ensureInsideWorkspace(workspaceRoot, targetPath) {
     }
     return resolvedTargetPath;
 }
+async function ensureRealPathInsideWorkspace(workspaceRoot, targetPath) {
+    const realTargetPath = await fs.realpath(targetPath);
+    return ensureInsideWorkspace(workspaceRoot, realTargetPath);
+}
+async function ensureWritableParentInsideWorkspace(workspaceRoot, targetPath) {
+    const realParentPath = await fs.realpath(path.dirname(targetPath));
+    ensureInsideWorkspace(workspaceRoot, realParentPath);
+    try {
+        const targetLinkStat = await fs.lstat(targetPath);
+        if (targetLinkStat.isSymbolicLink()) {
+            throw new Error(`Refusing to write through symbolic link: ${targetPath}`);
+        }
+    }
+    catch (error) {
+        const errorCode = typeof error === 'object' && error !== null ? Reflect.get(error, 'code') : undefined;
+        if (errorCode !== 'ENOENT') {
+            throw error;
+        }
+    }
+}
+function resolveRequestedPathInsideWorkspace(requestedRoot, workspaceRoot, requestedPath) {
+    const resolvedRequestedPath = path.resolve(requestedPath);
+    const requestedRelativePath = path.relative(requestedRoot, resolvedRequestedPath);
+    if (requestedRelativePath.startsWith('..') || path.isAbsolute(requestedRelativePath)) {
+        throw new Error(`Target path is outside workspace: ${resolvedRequestedPath}`);
+    }
+    return ensureInsideWorkspace(workspaceRoot, path.join(workspaceRoot, requestedRelativePath));
+}
 /**
  * 解析目录目标路径，空路径时回退到工作区根目录。
  */
-function resolveDirectoryTarget({ workspacePath, targetPath = '' }) {
-    const workspaceRoot = resolveWorkspaceRoot(workspacePath);
+async function resolveDirectoryTarget({ workspacePath, targetPath = '' }) {
+    const { requestedRoot, workspaceRoot } = await resolveWorkspaceRoots(workspacePath);
     const requestedPath = String(targetPath || '').trim();
-    const resolvedTargetPath = requestedPath
-        ? ensureInsideWorkspace(workspaceRoot, requestedPath)
+    const lexicalTargetPath = requestedPath
+        ? resolveRequestedPathInsideWorkspace(requestedRoot, workspaceRoot, requestedPath)
         : workspaceRoot;
+    const resolvedTargetPath = await ensureRealPathInsideWorkspace(workspaceRoot, lexicalTargetPath);
     return { workspaceRoot, resolvedTargetPath };
 }
 /**
@@ -56,49 +116,235 @@ function normalizeEntryName(rawName) {
     }
     return entryName;
 }
+/**
+ * 修正 multipart 文件名在部分代理链路中被 latin1 解读造成的 UTF-8 中文乱码。
+ */
+function decodePossiblyLatin1Utf8FileName(rawName) {
+    const fileName = String(rawName || '');
+    if (!/[\u00c0-\u00ff]/.test(fileName)) {
+        return fileName;
+    }
+    const decodedFileName = Buffer.from(fileName, 'latin1').toString('utf8');
+    if (!decodedFileName || decodedFileName.includes('\uFFFD')) {
+        return fileName;
+    }
+    return decodedFileName;
+}
+/**
+ * 将上传文件名规范化为单级文件名，避免浏览器提交的路径穿透目录。
+ */
+function normalizeUploadedFileName(rawName) {
+    const decodedName = decodePossiblyLatin1Utf8FileName(rawName);
+    return normalizeEntryName(path.basename(decodedName.replace(/\\/g, '/')));
+}
+/**
+ * 将浏览器传入的上传相对路径拆成安全路径片段，保留文件夹层级但拒绝穿透路径。
+ */
+function normalizeUploadedRelativePath(rawPath, fallbackName) {
+    if (!rawPath) {
+        return normalizeUploadedFileName(fallbackName);
+    }
+    const decodedPath = decodePossiblyLatin1Utf8FileName(String(rawPath || fallbackName || '')).replace(/\\/g, '/');
+    const segments = decodedPath.split('/').filter(Boolean).map((segment) => normalizeEntryName(segment));
+    if (segments.length === 0) {
+        return normalizeUploadedFileName(fallbackName);
+    }
+    return path.join(...segments);
+}
+function escapeHtml(rawText) {
+    return rawText
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+function decodeXmlText(rawText) {
+    return rawText
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&apos;/g, "'")
+        .replace(/&amp;/g, '&');
+}
+function docxTextToHtml(documentXml) {
+    const paragraphMatches = documentXml.match(/<w:p[\s\S]*?<\/w:p>/g) || [];
+    const paragraphs = paragraphMatches
+        .map((paragraphXml) => {
+        const textSegments = [...paragraphXml.matchAll(/<w:t(?:\s[^>]*)?>([\s\S]*?)<\/w:t>/g)]
+            .map((match) => decodeXmlText(match[1] || ''));
+        return textSegments.join('');
+    })
+        .map((paragraphText) => paragraphText.trim())
+        .filter(Boolean);
+    if (paragraphs.length === 0) {
+        return '<p class="workspace-document-preview__paragraph workspace-document-preview__paragraph--empty">该文档没有可预览的正文内容。</p>';
+    }
+    return paragraphs
+        .map((paragraphText) => `<p class="workspace-document-preview__paragraph">${escapeHtml(paragraphText)}</p>`)
+        .join('\n');
+}
 /**
  * 解析并校验工作区内条目的目标路径。
  */
-function resolveEntryTarget({ workspacePath, targetPath }) {
-    const workspaceRoot = resolveWorkspaceRoot(workspacePath);
+async function resolveEntryTarget({ workspacePath, targetPath }) {
+    const { requestedRoot, workspaceRoot } = await resolveWorkspaceRoots(workspacePath);
     const normalizedTargetPath = String(targetPath || '').trim();
     if (!normalizedTargetPath) {
         throw new Error('targetPath is required');
     }
-    const resolvedTargetPath = ensureInsideWorkspace(workspaceRoot, normalizedTargetPath);
+    const lexicalTargetPath = resolveRequestedPathInsideWorkspace(requestedRoot, workspaceRoot, normalizedTargetPath);
+    const resolvedTargetPath = await ensureRealPathInsideWorkspace(workspaceRoot, lexicalTargetPath);
     if (resolvedTargetPath === workspaceRoot) {
         throw new Error('Workspace root cannot be modified');
     }
     return { workspaceRoot, resolvedTargetPath };
 }
+async function resolveWritableDirectory(params) {
+    const { requestedRoot, workspaceRoot } = await resolveWorkspaceRoots(params.workspacePath);
+    const requestedPath = String(params.targetPath || '').trim();
+    if (!requestedPath) {
+        return { workspaceRoot, resolvedTargetPath: workspaceRoot };
+    }
+    const lexicalTargetPath = resolveRequestedPathInsideWorkspace(requestedRoot, workspaceRoot, requestedPath);
+    if (await pathExists(lexicalTargetPath)) {
+        return {
+            workspaceRoot,
+            resolvedTargetPath: await ensureRealPathInsideWorkspace(workspaceRoot, lexicalTargetPath),
+        };
+    }
+    const realParentPath = await fs.realpath(path.dirname(lexicalTargetPath));
+    ensureInsideWorkspace(workspaceRoot, realParentPath);
+    return { workspaceRoot, resolvedTargetPath: lexicalTargetPath };
+}
+function archiveKind(filePath) {
+    const lowerName = filePath.toLowerCase();
+    if (lowerName.endsWith('.zip'))
+        return 'zip';
+    if (lowerName.endsWith('.tar.gz') || lowerName.endsWith('.tgz'))
+        return 'tgz';
+    if (lowerName.endsWith('.tar'))
+        return 'tar';
+    if (lowerName.endsWith('.gz'))
+        return 'gz';
+    return null;
+}
+function stripArchiveExtension(fileName) {
+    return fileName.replace(/\.tar\.gz$/i, '').replace(/\.tgz$/i, '').replace(/\.zip$/i, '').replace(/\.tar$/i, '').replace(/\.gz$/i, '');
+}
+function resolveArchiveUploadOutputPath(uploadTargetDirectory, archiveFileName) {
+    const outputDirectoryName = normalizeEntryName(stripArchiveExtension(archiveFileName) || 'extracted');
+    return path.join(uploadTargetDirectory, outputDirectoryName);
+}
+function ensureArchiveEntryInside(targetRoot, entryPath) {
+    const normalizedEntryPath = String(entryPath || '').replace(/\\/g, '/');
+    const pathSegments = normalizedEntryPath.split('/').filter(Boolean);
+    if (!normalizedEntryPath || normalizedEntryPath.startsWith('/') || /^[A-Za-z]:/.test(normalizedEntryPath)) {
+        throw new Error(`Archive entry path is invalid: ${entryPath}`);
+    }
+    if (normalizedEntryPath.length > ARCHIVE_LIMITS.maxPathLength || pathSegments.length > ARCHIVE_LIMITS.maxPathDepth) {
+        throw new Error(`Archive entry path is too deep or too long: ${entryPath}`);
+    }
+    return ensureInsideWorkspace(targetRoot, path.join(targetRoot, normalizedEntryPath));
+}
+function decodeZipEntryPath(entry) {
+    const pathBuffer = entry.props?.pathBuffer;
+    if (!pathBuffer || entry.props?.flags?.isUnicode) {
+        return entry.path;
+    }
+    const decodedPath = GBK_DECODER.decode(pathBuffer);
+    if (!decodedPath || decodedPath.includes('\uFFFD')) {
+        return entry.path;
+    }
+    return decodedPath;
+}
+async function drainZipEntry(entry) {
+    const drainedStream = entry.autodrain?.();
+    if (!drainedStream) {
+        return;
+    }
+    await new Promise((resolve, reject) => {
+        drainedStream.on('close', resolve);
+        drainedStream.on('end', resolve);
+        drainedStream.on('finish', resolve);
+        drainedStream.on('error', reject);
+    });
+}
+function trackArchiveEntry(meter) {
+    meter.entries += 1;
+    if (meter.entries > ARCHIVE_LIMITS.maxEntries) {
+        throw new Error(`Archive contains too many entries. Limit: ${ARCHIVE_LIMITS.maxEntries}`);
+    }
+}
+function trackArchiveBytes(meter, bytes) {
+    meter.totalBytes += bytes;
+    if (bytes > ARCHIVE_LIMITS.maxFileBytes) {
+        throw new Error(`Archive entry exceeds max size. Limit: ${ARCHIVE_LIMITS.maxFileBytes} bytes`);
+    }
+    if (meter.totalBytes > ARCHIVE_LIMITS.maxTotalBytes) {
+        throw new Error(`Archive extraction exceeds total size. Limit: ${ARCHIVE_LIMITS.maxTotalBytes} bytes`);
+    }
+}
+async function pipelineWithArchiveLimits(input, destinationPath, meter) {
+    let fileBytes = 0;
+    input.on('data', (chunk) => {
+        const chunkBytes = Buffer.isBuffer(chunk) ? chunk.length : Buffer.byteLength(chunk);
+        fileBytes += chunkBytes;
+        if (fileBytes > ARCHIVE_LIMITS.maxFileBytes || meter.totalBytes + fileBytes > ARCHIVE_LIMITS.maxTotalBytes) {
+            if (input instanceof Readable) {
+                input.destroy(new Error('Archive extraction size limit exceeded'));
+            }
+        }
+    });
+    await pipeline(input, createWriteStream(destinationPath));
+    trackArchiveBytes(meter, fileBytes);
+}
+async function pathExists(targetPath) {
+    try {
+        await fs.access(targetPath);
+        return true;
+    }
+    catch (error) {
+        const errorCode = typeof error === 'object' && error !== null ? Reflect.get(error, 'code') : undefined;
+        if (errorCode === 'ENOENT') {
+            return false;
+        }
+        throw error;
+    }
+}
 /**
  * 解析文件目标路径，并确保文件位于工作区中。
  */
-function resolveFileTarget({ workspacePath, filePath }) {
-    const workspaceRoot = resolveWorkspaceRoot(workspacePath);
+async function resolveFileTarget({ workspacePath, filePath }) {
+    const { requestedRoot, workspaceRoot } = await resolveWorkspaceRoots(workspacePath);
     const normalizedFilePath = String(filePath || '').trim();
     if (!normalizedFilePath) {
         throw new Error('filePath is required');
     }
     return {
         workspaceRoot,
-        resolvedFilePath: ensureInsideWorkspace(workspaceRoot, normalizedFilePath)
+        resolvedFilePath: resolveRequestedPathInsideWorkspace(requestedRoot, workspaceRoot, normalizedFilePath)
     };
 }
 /**
  * 列出工作区目录内容。
  */
 export async function listWorkspaceDirectory(params) {
-    const { workspaceRoot, resolvedTargetPath } = resolveDirectoryTarget(params);
+    const { workspaceRoot, resolvedTargetPath } = await resolveDirectoryTarget(params);
     const stat = await fs.stat(resolvedTargetPath);
     if (!stat.isDirectory()) {
         throw new Error(`Path is not a directory: ${resolvedTargetPath}`);
     }
     const entries = await fs.readdir(resolvedTargetPath, { withFileTypes: true });
-    const items = entries.map((entry) => ({
-        name: entry.name,
-        path: toDisplayPath(path.join(resolvedTargetPath, entry.name)),
-        isDirectory: entry.isDirectory()
+    const items = await Promise.all(entries.map(async (entry) => {
+        const entryPath = path.join(resolvedTargetPath, entry.name);
+        const entrySize = entry.isFile() ? (await fs.stat(entryPath)).size : undefined;
+        return {
+            name: entry.name,
+            path: toDisplayPath(entryPath),
+            isDirectory: entry.isDirectory(),
+            size: entrySize
+        };
     }));
     return {
         currentPath: toDisplayPath(resolvedTargetPath),
@@ -110,7 +356,8 @@ export async function listWorkspaceDirectory(params) {
  * 读取工作区中的文本文件。
  */
 export async function readWorkspaceFile(params) {
-    const { workspaceRoot, resolvedFilePath } = resolveFileTarget(params);
+    const { workspaceRoot, resolvedFilePath: lexicalFilePath } = await resolveFileTarget(params);
+    const resolvedFilePath = await ensureRealPathInsideWorkspace(workspaceRoot, lexicalFilePath);
     const stat = await fs.stat(resolvedFilePath);
     if (!stat.isFile()) {
         throw new Error(`Path is not a file: ${resolvedFilePath}`);
@@ -122,12 +369,47 @@ export async function readWorkspaceFile(params) {
         content
     };
 }
+/**
+ * 返回工作区内 Word 文档的预览元数据；docx 由前端下载原文件后渲染，旧版 doc 明确提示不支持。
+ */
+export async function previewWorkspaceDocument(params) {
+    const { workspaceRoot, resolvedFilePath: lexicalFilePath } = await resolveFileTarget(params);
+    const resolvedFilePath = await ensureRealPathInsideWorkspace(workspaceRoot, lexicalFilePath);
+    const stat = await fs.stat(resolvedFilePath);
+    if (!stat.isFile()) {
+        throw new Error(`Path is not a file: ${resolvedFilePath}`);
+    }
+    const extension = path.extname(resolvedFilePath).toLowerCase();
+    if (extension === '.doc') {
+        return {
+            workspacePath: toDisplayPath(workspaceRoot),
+            filePath: toDisplayPath(resolvedFilePath),
+            kind: 'unsupported',
+            content: '',
+            message: '暂不支持旧版 .doc 格式预览，请另存为 .docx 后再打开。',
+            size: stat.size,
+            mtimeMs: stat.mtimeMs,
+        };
+    }
+    if (extension !== '.docx') {
+        throw new Error('Document preview only supports .docx files');
+    }
+    return {
+        workspacePath: toDisplayPath(workspaceRoot),
+        filePath: toDisplayPath(resolvedFilePath),
+        kind: 'html',
+        content: '',
+        size: stat.size,
+        mtimeMs: stat.mtimeMs,
+    };
+}
 /**
  * 将文本内容保存到工作区文件中。
  */
 export async function writeWorkspaceFile(params) {
-    const { workspaceRoot, resolvedFilePath } = resolveFileTarget(params);
+    const { workspaceRoot, resolvedFilePath } = await resolveFileTarget(params);
     await fs.mkdir(path.dirname(resolvedFilePath), { recursive: true });
+    await ensureWritableParentInsideWorkspace(workspaceRoot, resolvedFilePath);
     await fs.writeFile(resolvedFilePath, String(params.content ?? ''), 'utf-8');
     return {
         ok: true,
@@ -139,7 +421,7 @@ export async function writeWorkspaceFile(params) {
  * 在指定工作区目录下创建文件或目录。
  */
 export async function createWorkspaceEntry(params) {
-    const { workspaceRoot, resolvedTargetPath } = resolveDirectoryTarget(params);
+    const { workspaceRoot, resolvedTargetPath } = await resolveDirectoryTarget(params);
     const entryName = normalizeEntryName(params.entryName);
     const targetPath = ensureInsideWorkspace(workspaceRoot, path.join(resolvedTargetPath, entryName));
     const parentStat = await fs.stat(resolvedTargetPath);
@@ -161,6 +443,7 @@ export async function createWorkspaceEntry(params) {
     }
     else {
         await fs.mkdir(path.dirname(targetPath), { recursive: true });
+        await ensureWritableParentInsideWorkspace(workspaceRoot, targetPath);
         await fs.writeFile(targetPath, '', 'utf-8');
     }
     return {
@@ -174,7 +457,7 @@ export async function createWorkspaceEntry(params) {
  * 在工作区内重命名文件或目录，保持目标仍位于原父目录中。
  */
 export async function renameWorkspaceEntry(params) {
-    const { workspaceRoot, resolvedTargetPath } = resolveEntryTarget(params);
+    const { workspaceRoot, resolvedTargetPath } = await resolveEntryTarget(params);
     const newName = normalizeEntryName(params.newName);
     const renamedPath = ensureInsideWorkspace(workspaceRoot, path.join(path.dirname(resolvedTargetPath), newName));
     if (renamedPath === resolvedTargetPath) {
@@ -204,11 +487,60 @@ export async function renameWorkspaceEntry(params) {
         targetPath: toDisplayPath(renamedPath)
     };
 }
+/**
+ * 将工作区内文件或目录移动到另一个工作区目录，保持原文件名不变。
+ */
+export async function moveWorkspaceEntry(params) {
+    const { workspaceRoot, resolvedTargetPath } = await resolveEntryTarget(params);
+    const destination = await resolveDirectoryTarget({
+        workspacePath: params.workspacePath,
+        targetPath: params.destinationPath,
+    });
+    const destinationStat = await fs.stat(destination.resolvedTargetPath);
+    if (!destinationStat.isDirectory()) {
+        throw new Error(`Destination is not a directory: ${destination.resolvedTargetPath}`);
+    }
+    const targetStat = await fs.stat(resolvedTargetPath);
+    if (targetStat.isDirectory()) {
+        const relativeDestination = path.relative(resolvedTargetPath, destination.resolvedTargetPath);
+        if (relativeDestination === '' || (!relativeDestination.startsWith('..') && !path.isAbsolute(relativeDestination))) {
+            throw new Error('Cannot move a directory into itself or its descendant');
+        }
+    }
+    const movedPath = ensureInsideWorkspace(workspaceRoot, path.join(destination.resolvedTargetPath, path.basename(resolvedTargetPath)));
+    if (movedPath === resolvedTargetPath) {
+        return {
+            ok: true,
+            workspacePath: toDisplayPath(workspaceRoot),
+            sourcePath: toDisplayPath(resolvedTargetPath),
+            targetPath: toDisplayPath(movedPath),
+            destinationPath: toDisplayPath(destination.resolvedTargetPath),
+        };
+    }
+    try {
+        await fs.access(movedPath);
+        throw new Error(`Path already exists: ${movedPath}`);
+    }
+    catch (error) {
+        const errorCode = typeof error === 'object' && error !== null ? Reflect.get(error, 'code') : undefined;
+        if (errorCode !== 'ENOENT') {
+            throw error;
+        }
+    }
+    await fs.rename(resolvedTargetPath, movedPath);
+    return {
+        ok: true,
+        workspacePath: toDisplayPath(workspaceRoot),
+        sourcePath: toDisplayPath(resolvedTargetPath),
+        targetPath: toDisplayPath(movedPath),
+        destinationPath: toDisplayPath(destination.resolvedTargetPath),
+    };
+}
 /**
  * 删除工作区内的文件或目录，并阻止误删工作区根目录。
  */
 export async function deleteWorkspaceEntry(params) {
-    const { workspaceRoot, resolvedTargetPath } = resolveEntryTarget(params);
+    const { workspaceRoot, resolvedTargetPath } = await resolveEntryTarget(params);
     const targetStat = await fs.stat(resolvedTargetPath);
     if (targetStat.isDirectory()) {
         await fs.rm(resolvedTargetPath, { recursive: true, force: false });
@@ -222,3 +554,221 @@ export async function deleteWorkspaceEntry(params) {
         targetPath: toDisplayPath(resolvedTargetPath)
     };
 }
+/**
+ * 上传文件到工作区指定目录，并可在上传后自动解压常见归档。
+ */
+export async function uploadWorkspaceFiles(params) {
+    if (!Array.isArray(params.files) || params.files.length === 0) {
+        throw new Error('files are required');
+    }
+    const { workspaceRoot, resolvedTargetPath } = await resolveWritableDirectory(params);
+    const targetStat = await fs.stat(resolvedTargetPath);
+    if (!targetStat.isDirectory()) {
+        throw new Error(`Path is not a directory: ${resolvedTargetPath}`);
+    }
+    const files = [];
+    for (const file of params.files) {
+        const fileName = normalizeUploadedFileName(file.originalname);
+        const uploadRelativePath = normalizeUploadedRelativePath(file.relativePath, file.originalname);
+        const destinationPath = ensureInsideWorkspace(workspaceRoot, path.join(resolvedTargetPath, uploadRelativePath));
+        await fs.mkdir(path.dirname(destinationPath), { recursive: true });
+        await ensureWritableParentInsideWorkspace(workspaceRoot, destinationPath);
+        await fs.copyFile(file.path, destinationPath);
+        let extracted;
+        if (params.extractArchives && archiveKind(destinationPath)) {
+            extracted = await extractWorkspaceArchive({
+                workspacePath: workspaceRoot,
+                archivePath: destinationPath,
+                outputPath: resolveArchiveUploadOutputPath(resolvedTargetPath, fileName)
+            });
+        }
+        files.push({
+            fileName,
+            targetPath: toDisplayPath(destinationPath),
+            size: file.size,
+            extracted
+        });
+    }
+    return {
+        ok: true,
+        workspacePath: toDisplayPath(workspaceRoot),
+        targetPath: toDisplayPath(resolvedTargetPath),
+        files
+    };
+}
+/**
+ * 解析工作区下载目标；目录由路由层打包为 zip，文件直接流式下载。
+ */
+export async function resolveWorkspaceDownloadTarget(params) {
+    const { workspaceRoot, resolvedTargetPath } = await resolveEntryTarget(params);
+    const targetStat = await fs.stat(resolvedTargetPath);
+    const baseName = path.basename(resolvedTargetPath);
+    return {
+        workspacePath: toDisplayPath(workspaceRoot),
+        targetPath: toDisplayPath(resolvedTargetPath),
+        resolvedTargetPath,
+        fileName: targetStat.isDirectory() ? `${baseName || 'workspace'}.zip` : baseName,
+        contentType: targetStat.isDirectory() ? 'application/zip' : 'application/octet-stream',
+        isDirectory: targetStat.isDirectory()
+    };
+}
+/**
+ * 将目录内容以 zip 格式写入输出流，避免在磁盘生成临时包。
+ */
+export async function streamWorkspaceDirectoryZip(directoryPath, output) {
+    const archive = new ZipArchive({ zlib: { level: 9 } });
+    const completion = new Promise((resolve, reject) => {
+        output.on('close', resolve);
+        output.on('finish', resolve);
+        archive.on('error', reject);
+        output.on('error', reject);
+    });
+    archive.pipe(output);
+    archive.directory(directoryPath, false);
+    await archive.finalize();
+    await completion;
+}
+async function extractZipArchive(archivePath, outputRoot, meter) {
+    let extractedEntries = 0;
+    let extractionError;
+    const sourceStream = createReadStream(archivePath);
+    const parsedStream = sourceStream.pipe(unzipper.Parse({ forceStream: true }));
+    try {
+        for await (const entry of parsedStream) {
+            if (extractionError) {
+                await drainZipEntry(entry);
+                continue;
+            }
+            const entryPath = decodeZipEntryPath(entry);
+            try {
+                const destinationPath = ensureArchiveEntryInside(outputRoot, entryPath);
+                trackArchiveEntry(meter);
+                if (entry.type === 'Directory') {
+                    await fs.mkdir(destinationPath, { recursive: true });
+                    continue;
+                }
+                if (entry.type !== 'File') {
+                    throw new Error(`Unsupported archive entry type: ${entryPath}`);
+                }
+                await fs.mkdir(path.dirname(destinationPath), { recursive: true });
+                await ensureWritableParentInsideWorkspace(outputRoot, destinationPath);
+                await pipelineWithArchiveLimits(entry, destinationPath, meter);
+                extractedEntries += 1;
+            }
+            catch (error) {
+                extractionError = error;
+                await drainZipEntry(entry);
+            }
+        }
+    }
+    finally {
+        sourceStream.destroy();
+        parsedStream.destroy();
+    }
+    if (extractionError) {
+        throw extractionError;
+    }
+    return extractedEntries;
+}
+async function extractTarArchive(archivePath, outputRoot, gzip, meter) {
+    let extractedEntries = 0;
+    let extractionError;
+    /**
+     * 校验 tar 条目并通过 filter 返回值控制是否解压。
+     * tar 的 filter 回调位于流解析链路中，直接抛错会变成未处理异常；这里先记录错误，待流结束后统一 reject。
+     */
+    const shouldExtractTarEntry = (entryPath, entry) => {
+        if (extractionError) {
+            return false;
+        }
+        try {
+            ensureArchiveEntryInside(outputRoot, entryPath);
+            trackArchiveEntry(meter);
+            const entryType = String(entry.type || '').toLowerCase();
+            if (entryType === 'symboliclink' || entryType === 'link') {
+                throw new Error(`Archive links are not supported: ${entryPath}`);
+            }
+            if (entryType !== 'file' && entryType !== 'oldfile' && entryType !== 'contiguousfile' && entryType !== 'directory') {
+                throw new Error(`Unsupported archive entry type: ${entryPath}`);
+            }
+            if (typeof entry.size === 'number') {
+                trackArchiveBytes(meter, entry.size);
+            }
+            if (entryType !== 'directory') {
+                extractedEntries += 1;
+            }
+            return true;
+        }
+        catch (error) {
+            extractionError = error;
+            return false;
+        }
+    };
+    await tar.x({
+        file: archivePath,
+        cwd: outputRoot,
+        gzip,
+        strict: true,
+        filter: (entryPath, entry) => {
+            return shouldExtractTarEntry(entryPath, entry);
+        }
+    });
+    if (extractionError) {
+        throw extractionError;
+    }
+    return extractedEntries;
+}
+async function extractGzipFile(archivePath, outputRoot, meter) {
+    const outputName = stripArchiveExtension(path.basename(archivePath));
+    const destinationPath = ensureArchiveEntryInside(outputRoot, outputName || 'decompressed');
+    trackArchiveEntry(meter);
+    await fs.mkdir(path.dirname(destinationPath), { recursive: true });
+    await ensureWritableParentInsideWorkspace(outputRoot, destinationPath);
+    await pipelineWithArchiveLimits(createReadStream(archivePath).pipe(createGunzip()), destinationPath, meter);
+    return 1;
+}
+/**
+ * 解压工作区中的归档文件到指定目录，支持 zip、tar、tar.gz/tgz 与单文件 gz。
+ */
+export async function extractWorkspaceArchive(params) {
+    const { requestedRoot, workspaceRoot } = await resolveWorkspaceRoots(params.workspacePath);
+    const { resolvedTargetPath: outputRoot } = await resolveWritableDirectory({
+        workspacePath: params.workspacePath,
+        targetPath: params.outputPath || ''
+    });
+    const lexicalArchivePath = resolveRequestedPathInsideWorkspace(requestedRoot, workspaceRoot, String(params.archivePath || '').trim());
+    const archivePath = await ensureRealPathInsideWorkspace(workspaceRoot, lexicalArchivePath);
+    const archiveStat = await fs.stat(archivePath);
+    if (!archiveStat.isFile()) {
+        throw new Error(`Archive path is not a file: ${archivePath}`);
+    }
+    if (!(await pathExists(outputRoot))) {
+        await fs.mkdir(outputRoot, { recursive: true });
+    }
+    const outputStat = await fs.stat(outputRoot);
+    if (!outputStat.isDirectory()) {
+        throw new Error(`Output path is not a directory: ${outputRoot}`);
+    }
+    const kind = archiveKind(archivePath);
+    if (!kind) {
+        throw new Error('Unsupported archive type. Supported: .zip, .tar, .tar.gz, .tgz, .gz');
+    }
+    let extractedEntries = 0;
+    const meter = { entries: 0, totalBytes: 0 };
+    if (kind === 'zip') {
+        extractedEntries = await extractZipArchive(archivePath, outputRoot, meter);
+    }
+    else if (kind === 'tar' || kind === 'tgz') {
+        extractedEntries = await extractTarArchive(archivePath, outputRoot, kind === 'tgz', meter);
+    }
+    else {
+        extractedEntries = await extractGzipFile(archivePath, outputRoot, meter);
+    }
+    return {
+        ok: true,
+        workspacePath: toDisplayPath(workspaceRoot),
+        archivePath: toDisplayPath(archivePath),
+        targetPath: toDisplayPath(outputRoot),
+        extractedEntries
+    };
+}