most-box 0.0.1 → 0.0.2

package/src/index.js

@@ -1,6 +1,11 @@
 /**
- * MostBoxEngine - Core P2P Engine
- * Platform-agnostic engine for P2P file sharing using Hyperswarm/Hyperdrive
+ * MostBoxEngine - 核心 P2P 引擎
+ * 基于 Hyperswarm/Hyperdrive 的跨平台 P2P 文件共享引擎
+ *
+ * 架构设计：
+ * - Hyperdrive: 只负责存储文件内容，key 使用 CID（解耦存储与目录结构）
+ * - published-files.json: 维护文件元数据和显示路径（用户看到的文件夹结构）
+ * - 移动/重命名只需更新 JSON，零成本，不修改 Hyperdrive
  */
 
 import EventEmitter from 'eventemitter3'
@@ -15,7 +20,7 @@ import path from 'node:path'
 import { calculateCid, parseMostLink } from './core/cid.js'
 import { sanitizeFilename, validateAndSanitizePath, validateFileSize, checkDirectoryWritable, formatFileSize } from './utils/security.js'
 import { ValidationError, PathSecurityError, FileSizeError, PeerNotFoundError, IntegrityError, PermissionError, EngineNotInitializedError } from './utils/errors.js'
-import { GLOBAL_SHARED_SEED_STRING, MAX_FILE_SIZE, CONNECTION_TIMEOUT, DOWNLOAD_TIMEOUT, SWARM_BOOTSTRAP } from './config.js'
+import { GLOBAL_SHARED_SEED_STRING, MAX_FILE_SIZE, CONNECTION_TIMEOUT, DOWNLOAD_TIMEOUT, SWARM_BOOTSTRAP, MAX_PEERS, SWARM_KEEP_ALIVE_INTERVAL, SWARM_RANDOM_PUNCH_INTERVAL, DRIVE_ENTRY_TIMEOUT, DRIVE_SYNC_TIMEOUT, STREAM_READ_TIMEOUT, DOWNLOAD_POLL_INTERVAL, PROGRESS_THROTTLE, DEFAULT_READ_LIMIT } from './config.js'
 
 export class MostBoxEngine extends EventEmitter {
   #store = null
@@ -25,22 +30,23 @@ export class MostBoxEngine extends EventEmitter {
   #trashFiles = []
   #initialized = false
   #options = null
-  #activeDownloads = new Map() // taskId -> { aborted, readStream, writeStream }
+  #activeDownloads = new Map()
+  #drivePromises = new Map()
 
   /**
-   * Create a new MostBoxEngine instance
-   * @param {object} options - Configuration options
-   * @param {string} options.dataPath - Path to store P2P data (required)
-   * @param {string} [options.downloadPath] - Default download path (optional, defaults to dataPath/downloads)
-   * @param {number} [options.maxFileSize] - Maximum file size in bytes (default: 100GB)
+   * 创建新的 MostBoxEngine 实例
+   * @param {object} options - 配置选项
+   * @param {string} options.dataPath - 存储 P2P 数据的路径（必填）
+   * @param {string} [options.downloadPath] - 默认下载路径（可选，默认为 dataPath/downloads）
+   * @param {number} [options.maxFileSize] - 最大文件大小（字节）（默认：100GB）
    */
   constructor(options) {
     super()
-    
+
     if (!options || !options.dataPath) {
       throw new Error('dataPath is required')
     }
-    
+
     this.#options = {
       dataPath: options.dataPath,
       downloadPath: options.downloadPath || path.join(options.dataPath, 'downloads'),
@@ -49,7 +55,7 @@ export class MostBoxEngine extends EventEmitter {
   }
 
   /**
-   * Initialize the engine - must be called before other methods
+   * 初始化引擎 — 必须在调用其他方法之前调用
    */
   async start() {
     if (this.#initialized) {
@@ -57,19 +63,17 @@ export class MostBoxEngine extends EventEmitter {
     }
 
     const { dataPath } = this.#options
-    
+
     console.log(`[MostBox] Initializing engine...`)
     console.log(`[MostBox] Storage path: ${dataPath}`)
-    
-    // Create storage directory if not exists
+
     if (!fs.existsSync(dataPath)) {
       fs.mkdirSync(dataPath, { recursive: true })
     }
 
-    // Initialize Corestore with global shared seed
     const GLOBAL_SHARED_SEED = b4a.alloc(32).fill(GLOBAL_SHARED_SEED_STRING)
     this.#store = new Corestore(dataPath, { primaryKey: GLOBAL_SHARED_SEED, unsafe: true })
-    
+
     try {
       await this.#store.ready()
       console.log(`[MostBox] Corestore ready`)
@@ -90,27 +94,17 @@ export class MostBoxEngine extends EventEmitter {
       }
     }
 
-    // Initialize Hyperswarm with NAT traversal enabled
     console.log(`[MostBox] Initializing Hyperswarm...`)
     this.#swarm = new Hyperswarm({
-      // Connection settings for better stability
-      maxPeers: 64,
-      // DHT bootstrap nodes (same as Keet.io/HyperDHT)
+      maxPeers: MAX_PEERS,
       bootstrap: SWARM_BOOTSTRAP,
-      // Enable NAT traversal (hole punching)
-      // firewall function: allow all connections (default behavior)
       firewall: () => false,
-      // Connection keep-alive timeout (5 seconds)
-      connectionKeepAlive: 5000,
-      // Random punch interval for NAT traversal (20 seconds)
-      randomPunchInterval: 20000,
-      // Increase timeouts for unstable networks
+      connectionKeepAlive: SWARM_KEEP_ALIVE_INTERVAL,
+      randomPunchInterval: SWARM_RANDOM_PUNCH_INTERVAL,
       handshakeTimeout: CONNECTION_TIMEOUT
     })
 
-    // Handle swarm-level errors
     this.#swarm.on('error', (err) => {
-      // Silently handle SSL/network errors - they're non-critical for DHT discovery
       if (err.code === 'SSL_ERROR' || err.message?.includes('handshake') || err.message?.includes('ECONNRESET')) {
         console.warn('[MostBox] Network warning (non-critical):', err.message)
         return
@@ -119,10 +113,8 @@ export class MostBoxEngine extends EventEmitter {
       this.emit('error', err)
     })
 
-    // Replicate store on new connections
     this.#swarm.on('connection', (conn, info) => {
       console.log(`[MostBox] New peer connection established`)
-      // Handle connection errors gracefully
       conn.on('error', (err) => {
         if (err.code === 'SSL_ERROR' || err.message?.includes('handshake')) {
           console.warn('[MostBox] Connection warning:', err.message)
@@ -135,42 +127,42 @@ export class MostBoxEngine extends EventEmitter {
       this.emit('connection', conn)
     })
 
-    // Load published files metadata
     this.#publishedFiles = this.#loadPublishedMetadata()
     console.log(`[MostBox] Loaded ${this.#publishedFiles.length} published files`)
-    
-    // Load trash files metadata
+
     this.#trashFiles = this.#loadTrashMetadata()
     console.log(`[MostBox] Loaded ${this.#trashFiles.length} trash files`)
-    
+
     this.#initialized = true
     console.log(`[MostBox] Engine initialized successfully`)
     this.emit('ready')
-    
+
     return this
   }
 
   /**
-   * Stop the engine and cleanup resources
+   * 停止引擎并清理资源
    */
   async stop() {
     if (!this.#initialized) {
       return
     }
 
-    // Close all drives
-    for (const drive of this.#drives.values()) {
-      await drive.close()
+    for (const task of this.#activeDownloads.values()) {
+      task.aborted = true
+      if (task.readStream) task.readStream.destroy()
+      if (task.writeStream) task.writeStream.destroy()
     }
+    this.#activeDownloads.clear()
+
+    await Promise.allSettled([...this.#drives.values()].map(d => d.close()))
     this.#drives.clear()
 
-    // Destroy swarm
     if (this.#swarm) {
       await this.#swarm.destroy()
       this.#swarm = null
     }
 
-    // Close store
     if (this.#store) {
       await this.#store.close()
       this.#store = null
@@ -181,8 +173,8 @@ export class MostBoxEngine extends EventEmitter {
   }
 
   /**
-   * Get the node's public key
-   * @returns {string} Node ID as hex string
+   * 获取节点的公钥
+   * @returns {string} 节点 ID（十六进制字符串）
    */
   getNodeId() {
     this.#ensureInitialized()
@@ -190,7 +182,7 @@ export class MostBoxEngine extends EventEmitter {
   }
 
   /**
-   * Get current network status
+   * 获取当前网络状态
    * @returns {{ peers: number, status: string }}
    */
   getNetworkStatus() {
@@ -203,9 +195,10 @@ export class MostBoxEngine extends EventEmitter {
   }
 
   /**
-   * Publish content to the P2P network
-   * @param {string|Buffer} content - File path (string) or content (Buffer)
-   * @param {string} [fileName] - Name for the file (required for Buffer input)
+   * 将内容发布到 P2P 网络
+   * Hyperdrive 中存储 key 为 '/' + cid，metadata 中存储 displayName（用户看到的路径）
+   * @param {string|Buffer} content - 文件路径（字符串）或内容（Buffer）
+   * @param {string} [fileName] - 文件名（Buffer 输入时必填）
    * @returns {Promise<{ cid: string, link: string, fileName: string }>}
    */
   async publishFile(content, fileName) {
@@ -246,47 +239,61 @@ export class MostBoxEngine extends EventEmitter {
     this.emit('publish:progress', { stage: 'calculating-cid', file: safeFileName })
 
     const { cid: rootCid } = await calculateCid(content)
-    const hashHex = b4a.toString(rootCid.multihash.digest, 'hex')
     const cidString = rootCid.toString()
 
+    // 检查相同内容是否已存在
+    const existingIndex = this.#publishedFiles.findIndex(f => f.cid === cidString)
+    if (existingIndex !== -1) {
+      const existing = this.#publishedFiles[existingIndex]
+      return {
+        cid: cidString,
+        link: `most://${cidString}`,
+        fileName: existing.fileName,
+        alreadyExists: true
+      }
+    }
+
+    // 获取或创建该 CID 对应的 drive
+    const hashHex = b4a.toString(rootCid.multihash.digest, 'hex')
     const name = `drive-${hashHex}`
     let drive = this.#drives.get(name)
-    
+
     if (!drive) {
-      drive = new Hyperdrive(this.#store.namespace(name))
-      await drive.ready()
-      this.#drives.set(name, drive)
-      
+      drive = await this.#getOrCreateDrive(name, { server: true, client: false })
       const discovery = this.#swarm.join(drive.discoveryKey, { server: true, client: false })
       await discovery.flushed()
     }
 
     this.emit('publish:progress', { stage: 'uploading', file: safeFileName })
 
-    const ws = drive.createWriteStream(safeFileName)
+    // Hyperdrive 中用 CID 作为 key 存储（解耦目录结构）
+    const driveKey = '/' + cidString
+
+    const ws = drive.createWriteStream(driveKey)
 
     if (Buffer.isBuffer(content)) {
-      // Stream buffer in chunks to avoid exceeding Hyperdrive block size limit
-      const CHUNK_SIZE = 64 * 1024 // 64KB chunks
+      const CHUNK_SIZE = 64 * 1024
       let offset = 0
-
       const waitForDrain = () => new Promise(resolve => ws.once('drain', resolve))
 
-      while (offset < content.length) {
-        const chunk = content.slice(offset, offset + CHUNK_SIZE)
-        const canContinue = ws.write(chunk)
-        offset += chunk.length
-
-        if (!canContinue && offset < content.length) {
-          await waitForDrain()
+      try {
+        while (offset < content.length) {
+          const chunk = content.slice(offset, offset + CHUNK_SIZE)
+          const canContinue = ws.write(chunk)
+          offset += chunk.length
+          if (!canContinue && offset < content.length) {
+            await waitForDrain()
+          }
         }
+        ws.end()
+        await new Promise((resolve, reject) => {
+          ws.on('finish', resolve)
+          ws.on('error', reject)
+        })
+      } catch (err) {
+        ws.destroy()
+        throw err
       }
-
-      ws.end()
-      await new Promise((resolve, reject) => {
-        ws.on('finish', resolve)
-        ws.on('error', reject)
-      })
     } else {
       const rs = fs.createReadStream(cleanPath)
       await new Promise((resolve, reject) => {
@@ -297,24 +304,14 @@ export class MostBoxEngine extends EventEmitter {
       })
     }
 
-    const existingIndex = this.#publishedFiles.findIndex(f => f.cid === cidString)
-    if (existingIndex !== -1) {
-      const existing = this.#publishedFiles[existingIndex]
-      // Same content already exists - return "already exists" regardless of filename
-      return {
-        cid: cidString,
-        link: `most://${cidString}`,
-        fileName: existing.fileName,
-        alreadyExists: true
-      }
-    } else {
-      this.#publishedFiles.push({
-        fileName: safeFileName,
-        cid: cidString,
-        publishedAt: new Date().toISOString(),
-        starred: false
-      })
-    }
+    // 存储 displayName（用户看到的文件夹路径），不存储 drivePath
+    this.#publishedFiles.push({
+      fileName: safeFileName,
+      cid: cidString,
+      driveName: name,
+      publishedAt: new Date().toISOString(),
+      starred: false
+    })
     this.#savePublishedMetadata()
 
     const result = {
@@ -328,25 +325,22 @@ export class MostBoxEngine extends EventEmitter {
   }
 
   /**
-   * Download a file from the P2P network
-   * @param {string} link - most:// link
-   * @param {string} [taskId] - Task ID for cancellation
+   * 从 P2P 网络下载文件
+   * @param {string} link - most:// 链接
+   * @param {string} [taskId] - 用于取消的任务 ID
    * @returns {Promise<{ taskId: string, fileName: string, savedPath: string, alreadyExists?: boolean }>}
    */
   async downloadFile(link, taskId = null) {
     this.#ensureInitialized()
 
-    // Generate taskId if not provided
     taskId = taskId || `dl_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`
 
     console.log(`[MostBox] Starting download for link: ${link} (taskId: ${taskId})`)
 
-    // Register in active downloads
     const taskState = { aborted: false, readStream: null, writeStream: null }
     this.#activeDownloads.set(taskId, taskState)
 
     try {
-      // Parse link
       const parsed = parseMostLink(link)
       if (parsed.error) {
         throw new ValidationError(parsed.error)
@@ -354,7 +348,6 @@ export class MostBoxEngine extends EventEmitter {
       const cidString = parsed.cid
       console.log(`[MostBox] Parsed CID: ${cidString}`)
 
-      // Check if file already exists in published files
       const existingFile = this.#publishedFiles.find(f => f.cid === cidString)
       if (existingFile) {
         console.log(`[MostBox] File already exists: ${existingFile.fileName}`)
@@ -365,50 +358,40 @@ export class MostBoxEngine extends EventEmitter {
         }
       }
 
-      // Parse CID
       const parsedCid = CID.parse(cidString)
-      const hashBytes = parsedCid.multihash.digest
-      const hashHex = b4a.toString(hashBytes, 'hex')
+      const hashHex = b4a.toString(parsedCid.multihash.digest, 'hex')
 
-      // Check cancellation
       if (taskState.aborted) throw new Error('Download cancelled')
 
-      // Get/Create drive
       const name = `drive-${hashHex}`
       let drive = this.#drives.get(name)
-      
+
       if (!drive) {
         console.log(`[MostBox] Creating new drive: ${name}`)
-        drive = new Hyperdrive(this.#store.namespace(name))
-        await drive.ready()
-        this.#drives.set(name, drive)
-        
+        drive = await this.#getOrCreateDrive(name, { server: true, client: true })
+
         this.emit('download:status', { taskId, status: 'connecting' })
-        
+
         console.log(`[MostBox] Joining swarm for drive discovery...`)
-        // Join as both server and client to allow self-downloads
         await this.#swarm.join(drive.discoveryKey, { server: true, client: true }).flushed()
         console.log(`[MostBox] Swarm join flushed`)
       } else {
         console.log(`[MostBox] Using existing drive: ${name}`)
       }
 
-      // Check cancellation
       if (taskState.aborted) throw new Error('Download cancelled')
 
       this.emit('download:status', { taskId, status: 'finding-peers' })
 
-      // Wait for peers and data to sync
-      console.log(`[MostBox] Waiting for drive content (timeout: ${DOWNLOAD_TIMEOUT/1000}s)...`)
+      console.log(`[MostBox] Waiting for drive content (timeout: ${DOWNLOAD_TIMEOUT / 1000}s)...`)
       const entries = await this.#waitForDriveContent(drive, DOWNLOAD_TIMEOUT, taskId, taskState)
 
       if (entries.length === 0) {
         console.log(`[MostBox] No entries found after timeout`)
-        
-        // 提供更详细的错误信息
+
         const peerCount = this.#swarm.connections.size
         let errorMessage = 'No files found in drive. '
-        
+
         if (peerCount === 0) {
           errorMessage += 'Could not connect to any peers. This may be due to:\n'
           errorMessage += '1. Network firewall blocking P2P connections\n'
@@ -421,29 +404,27 @@ export class MostBoxEngine extends EventEmitter {
           errorMessage += '2. File may have been removed by publisher\n'
           errorMessage += '3. File link may be invalid or corrupted'
         }
-        
+
         throw new PeerNotFoundError(errorMessage)
       }
 
-      // Check cancellation
       if (taskState.aborted) throw new Error('Download cancelled')
 
       console.log(`[MostBox] Found ${entries.length} entries, starting download...`)
 
-      // Save to storage directory (not Downloads folder)
       const targetDir = this.#options.dataPath
 
-      // Check storage directory
       const writableCheck = await checkDirectoryWritable(targetDir)
       if (!writableCheck.writable) {
         throw new PermissionError(writableCheck.error)
       }
 
-      // Download files
+      // 下载文件
       for (const entry of entries) {
-        const sanitizedFileName = sanitizeFilename(entry.key.replace(/^[\/\\]/, ''))
-        
-        // Get file size
+        const cleanKey = entry.key.replace(/^[\/\\]/, '')
+        // 用原始文件名作为 displayName
+        const sanitizedFileName = sanitizeFilename(cleanKey)
+
         let totalBytes = 0
         try {
           const stat = await drive.entry(entry.key)
@@ -451,56 +432,53 @@ export class MostBoxEngine extends EventEmitter {
             totalBytes = stat.value.blob.byteLength || 0
           }
         } catch {
-          // Ignore
+          // 忽略
         }
 
         const savePath = path.join(targetDir, sanitizedFileName)
-        
-        this.emit('download:status', { 
+
+        this.emit('download:status', {
           taskId,
-          status: 'downloading', 
-          file: sanitizedFileName, 
-          size: totalBytes ? formatFileSize(totalBytes) : null 
+          status: 'downloading',
+          file: sanitizedFileName,
+          size: totalBytes ? formatFileSize(totalBytes) : null
         })
 
-        // Download with progress
         const rs = drive.createReadStream(entry.key)
         const ws = fs.createWriteStream(savePath)
-        
+
         taskState.readStream = rs
         taskState.writeStream = ws
 
         let loadedBytes = 0
         let lastProgressUpdate = 0
-        
+
         await new Promise((resolve, reject) => {
           rs.on('data', (chunk) => {
-            // Check cancellation
             if (taskState.aborted) {
               rs.destroy()
               ws.destroy()
+              fs.unlink(savePath, () => { })
               reject(new Error('Download cancelled'))
               return
             }
             loadedBytes += chunk.length
             const now = Date.now()
-            if (totalBytes > 0 && now - lastProgressUpdate > 500) {
+            if (totalBytes > 0 && now - lastProgressUpdate > PROGRESS_THROTTLE) {
               lastProgressUpdate = now
               const percent = Math.round((loadedBytes / totalBytes) * 100)
               this.emit('download:progress', { taskId, loaded: loadedBytes, total: totalBytes, percent })
             }
           })
-          
+
           rs.pipe(ws)
           ws.on('finish', resolve)
           ws.on('error', reject)
           rs.on('error', reject)
         })
 
-        // Check cancellation before verification
         if (taskState.aborted) throw new Error('Download cancelled')
 
-        // Verify integrity
         this.emit('download:status', { taskId, status: 'verifying' })
 
         const { cid: downloadedCid } = await calculateCid(savePath)
@@ -512,13 +490,24 @@ export class MostBoxEngine extends EventEmitter {
           throw new IntegrityError(`File content CID mismatch. File may be corrupted or tampered.`)
         }
 
+        // Write file content to Hyperdrive so it can be served for preview
+        const driveKey = '/' + cidString
+        const readStream = fs.createReadStream(savePath)
+        const writeStream = drive.createWriteStream(driveKey)
+        await new Promise((resolve, reject) => {
+          readStream.pipe(writeStream)
+          writeStream.on('finish', resolve)
+          writeStream.on('error', reject)
+          readStream.on('error', reject)
+        })
+
         const result = {
           taskId,
           fileName: sanitizedFileName,
           savedPath: savePath
         }
 
-        // 将下载的文件添加到已发布文件列表
+        // 将下载的文件添加到已发布文件列表（displayName 用原始文件名）
         const existingIndex = this.#publishedFiles.findIndex(f => f.cid === cidString)
         if (existingIndex !== -1) {
           const existing = this.#publishedFiles[existingIndex]
@@ -530,6 +519,7 @@ export class MostBoxEngine extends EventEmitter {
           this.#publishedFiles.push({
             fileName: sanitizedFileName,
             cid: cidString,
+            driveName: name,
             publishedAt: new Date().toISOString(),
             starred: false
           })
@@ -545,19 +535,19 @@ export class MostBoxEngine extends EventEmitter {
   }
 
   /**
-   * List all published files
-   * @param {object} [options] - Filter options
-   * @param {boolean} [options.starred] - Filter by starred status
+   * 列出所有已发布文件
+   * @param {object} [options] - 筛选选项
+   * @param {boolean} [options.starred] - 按收藏状态筛选
    * @returns {Array<{ fileName: string, cid: string, link: string, publishedAt: string, starred: boolean }>}
    */
   listPublishedFiles(options = {}) {
     this.#ensureInitialized()
     let files = this.#publishedFiles
-    
+
     if (options.starred === true) {
       files = files.filter(f => f.starred === true)
     }
-    
+
     return files.map(f => ({
       fileName: f.fileName,
       cid: f.cid,
@@ -566,11 +556,11 @@ export class MostBoxEngine extends EventEmitter {
       starred: f.starred || false
     }))
   }
-  
+
   /**
-   * Toggle starred status of a file
-   * @param {string} cid - CID of the file
-   * @returns {object} Updated file info
+   * 切换文件的收藏状态
+   * @param {string} cid - 文件的 CID
+   * @returns {object} 更新后的文件信息
    */
   toggleStarred(cid) {
     this.#ensureInitialized()
@@ -587,36 +577,35 @@ export class MostBoxEngine extends EventEmitter {
   }
 
   /**
-   * Delete a published file - moves to trash instead of permanent deletion
-   * @param {string} cid - CID of the file to delete
-   * @returns {Promise<Array>} Updated list of published files
+   * 删除已发布文件 — 移至回收站而非永久删除
+   * @param {string} cid - 要删除文件的 CID
+   * @returns {Promise<Array>} 更新后的已发布文件列表
    */
   async deletePublishedFile(cid) {
     this.#ensureInitialized()
     const index = this.#publishedFiles.findIndex(f => f.cid === cid)
     if (index !== -1) {
       const fileRecord = this.#publishedFiles[index]
-      
-      // Move to trash instead of permanent deletion
+
       this.#trashFiles.push({
         fileName: fileRecord.fileName,
         cid: fileRecord.cid,
+        driveName: fileRecord.driveName,
         publishedAt: fileRecord.publishedAt,
         starred: fileRecord.starred || false,
         deletedAt: new Date().toISOString()
       })
       this.#saveTrashMetadata()
-      
-      // Remove from published files
+
       this.#publishedFiles.splice(index, 1)
       this.#savePublishedMetadata()
     }
     return this.listPublishedFiles()
   }
-  
+
   /**
-   * List all files in trash
-   * @returns {Array} Trash files
+   * 列出回收站中的所有文件
+   * @returns {Array} 回收站文件
    */
   listTrashFiles() {
     this.#ensureInitialized()
@@ -629,11 +618,11 @@ export class MostBoxEngine extends EventEmitter {
       deletedAt: f.deletedAt
     }))
   }
-  
+
   /**
-   * Restore a file from trash
-   * @param {string} cid - CID of the file to restore
-   * @returns {Array} Updated list of published files
+   * 从回收站恢复文件
+   * @param {string} cid - 要恢复文件的 CID
+   * @returns {Array} 更新后的已发布文件列表
    */
   restoreTrashFile(cid) {
     this.#ensureInitialized()
@@ -641,120 +630,105 @@ export class MostBoxEngine extends EventEmitter {
     if (index === -1) {
       throw new Error('File not found in trash')
     }
-    
+
     const fileRecord = this.#trashFiles[index]
-    
-    // Restore to published files
+
+    const parsedCid = CID.parse(fileRecord.cid)
+    const hashHex = b4a.toString(parsedCid.multihash.digest, 'hex')
+    const driveName = `drive-${hashHex}`
+
     this.#publishedFiles.push({
       fileName: fileRecord.fileName,
       cid: fileRecord.cid,
+      driveName,
       publishedAt: fileRecord.publishedAt,
       starred: fileRecord.starred || false
     })
     this.#savePublishedMetadata()
-    
-    // Remove from trash
+
     this.#trashFiles.splice(index, 1)
     this.#saveTrashMetadata()
-    
+
     return this.listPublishedFiles()
   }
-  
+
   /**
-   * Permanently delete a file from trash
-   * @param {string} cid - CID of the file to permanently delete
-   * @returns {Promise<Array>} Updated trash list
+   * 永久删除回收站中的文件
+   * @param {string} cid - 要永久删除文件的 CID
+   * @returns {Promise<Array>} 更新后的回收站列表
    */
   async permanentDeleteTrashFile(cid) {
     this.#ensureInitialized()
     const index = this.#trashFiles.findIndex(f => f.cid === cid)
     if (index !== -1) {
       const fileRecord = this.#trashFiles[index]
-      
-      // Reconstruct drive name from CID
-      const parsedCid = CID.parse(cid)
-      const hashHex = b4a.toString(parsedCid.multihash.digest, 'hex')
-      const driveName = `drive-${hashHex}`
-      
-      // Delete file from Hyperdrive and cleanup drive
+      const driveName = fileRecord.driveName
+
       const drive = this.#drives.get(driveName)
       if (drive) {
         try {
-          await drive.del(fileRecord.fileName)
+          await drive.del('/' + fileRecord.cid)
         } catch (err) {
-          // File may not exist in drive, continue with cleanup
+          // 文件可能不存在于驱动器中
         }
-        
-        // Leave swarm for this drive
+
         await this.#swarm.leave(drive.discoveryKey)
-        
-        // Close and remove drive
         await drive.close()
         this.#drives.delete(driveName)
       }
-      
-      // Remove from trash
+
       this.#trashFiles.splice(index, 1)
       this.#saveTrashMetadata()
     }
     return this.listTrashFiles()
   }
-  
+
   /**
-   * Empty the trash - permanently delete all trash files
-   * @returns {Promise<Array>} Empty trash list
+   * 清空回收站 — 永久删除所有回收站文件
+   * @returns {Promise<Array>} 清空后的回收站列表
    */
   async emptyTrash() {
     this.#ensureInitialized()
-    
+
     for (const fileRecord of this.#trashFiles) {
-      // Reconstruct drive name from CID
-      const parsedCid = CID.parse(fileRecord.cid)
-      const hashHex = b4a.toString(parsedCid.multihash.digest, 'hex')
-      const driveName = `drive-${hashHex}`
-      
-      // Delete file from Hyperdrive and cleanup drive
+      const driveName = fileRecord.driveName
+
       const drive = this.#drives.get(driveName)
       if (drive) {
         try {
-          await drive.del(fileRecord.fileName)
+          await drive.del('/' + fileRecord.cid)
         } catch (err) {
-          // File may not exist in drive, continue with cleanup
+          // 文件可能不存在
         }
-        
-        // Leave swarm for this drive
-        this.#swarm.leave(drive.discoveryKey)
-        
-        // Close and remove drive
+
+        await this.#swarm.leave(drive.discoveryKey)
         await drive.close()
         this.#drives.delete(driveName)
       }
     }
-    
-    // Clear trash
+
     this.#trashFiles = []
     this.#saveTrashMetadata()
-    
+
     return []
   }
-  
+
   /**
-   * Get storage statistics
+   * 获取存储统计信息
    * @returns {Promise<{ total: number, used: number, free: number, fileCount: number, trashCount: number }>}
    */
   async getStorageStats() {
     this.#ensureInitialized()
-    
+
     let totalSize = 0
     let freeSize = 0
     const { dataPath } = this.#options
-    
+
     try {
       const stats = fs.statfsSync(dataPath)
       totalSize = stats.bsize * stats.blocks
       freeSize = stats.bsize * stats.bfree
     } catch (err) {
-      // Fallback if statfs is not available
       try {
         const stats = fs.statSync(dataPath)
         totalSize = 0
@@ -764,8 +738,7 @@ export class MostBoxEngine extends EventEmitter {
         freeSize = 0
       }
     }
-    
-    // Calculate used space by files
+
     let usedSize = 0
     const calculateDirSize = (dirPath) => {
       try {
@@ -781,17 +754,17 @@ export class MostBoxEngine extends EventEmitter {
               const stat = fs.statSync(fullPath)
               usedSize += stat.size
             } catch {
-              // Skip files we can't access
+              // 跳过无法访问的文件
             }
           }
         }
       } catch {
-        // Skip directories we can't access
+        // 跳过无法访问的目录
       }
     }
-    
+
     calculateDirSize(dataPath)
-    
+
     return {
       total: totalSize,
       used: usedSize,
@@ -802,10 +775,11 @@ export class MostBoxEngine extends EventEmitter {
   }
 
   /**
-   * Move/rename a published file (changes path without re-uploading)
-   * @param {string} cid - CID of the file to move
-   * @param {string} newFileName - New file path
-   * @returns {object} Updated file info
+   * 移动/重命名已发布文件
+   * 只更新 metadata 中的 displayName，不修改 Hyperdrive
+   * @param {string} cid - 要移动文件的 CID
+   * @param {string} newFileName - 新文件路径
+   * @returns {object} 更新后的文件信息
    */
   moveFile(cid, newFileName) {
     this.#ensureInitialized()
@@ -825,20 +799,22 @@ export class MostBoxEngine extends EventEmitter {
   }
 
   /**
-   * Rename a folder (renames all files within the folder)
-   * @param {string} oldPath - Current folder path
-   * @param {string} newPath - New folder path
-   * @returns {object} Updated files info
+   * 重命名文件夹（重命名文件夹内的所有文件 displayName）
+   * 只更新 metadata，不修改 Hyperdrive
+   * @param {string} oldPath - 当前文件夹路径
+   * @param {string} newPath - 新文件夹路径
+   * @returns {object} 更新后的文件信息
    */
   renameFolder(oldPath, newPath) {
     this.#ensureInitialized()
     const prefix = oldPath + '/'
     const updatedFiles = []
-    
+
     for (const file of this.#publishedFiles) {
       if (file.fileName.startsWith(prefix)) {
-        const newFileName = newPath + file.fileName.substring(prefix.length)
-        file.fileName = sanitizeFilename(newFileName)
+        const remainder = file.fileName.substring(prefix.length)
+        const newFileName = sanitizeFilename(remainder ? newPath + '/' + remainder : newPath)
+        file.fileName = newFileName
         file.publishedAt = new Date().toISOString()
         updatedFiles.push({
           cid: file.cid,
@@ -847,19 +823,19 @@ export class MostBoxEngine extends EventEmitter {
         })
       }
     }
-    
+
     if (updatedFiles.length > 0) {
       this.#savePublishedMetadata()
     }
-    
+
     return { files: updatedFiles }
   }
 
   /**
-   * Cancel an active download
-   * @param {string} taskId - The task ID of the download to cancel
+   * 取消正在进行的下载
+   * @param {string} taskId - 要取消下载的任务 ID
    */
-   cancelDownload(taskId) {
+  cancelDownload(taskId) {
     const task = this.#activeDownloads.get(taskId)
     if (task) {
       task.aborted = true
@@ -872,7 +848,130 @@ export class MostBoxEngine extends EventEmitter {
     return this.#publishedFiles
   }
 
-  // --- Private methods ---
+  /**
+   * 读取已发布文件的内容（用于预览）
+   * Hyperdrive 中用 CID 作为 key 存储
+   * @param {string} cid - 文件的 CID
+   * @param {number} [offset=0] - 读取起始位置
+   * @param {number} [limit=10000] - 最大读取字节数
+   */
+  async readFileContent(cid, offset = 0, limit = DEFAULT_READ_LIMIT) {
+    this.#ensureInitialized()
+
+    const fileRecord = this.#publishedFiles.find(f => f.cid === cid)
+    if (!fileRecord) {
+      throw new Error('File not found')
+    }
+
+    const drive = await this.#getDriveForFile(fileRecord)
+
+    // Hyperdrive 中 key 为 '/' + cid
+    const driveKey = '/' + cid
+    const entry = await drive.entry(driveKey, { wait: true, timeout: DRIVE_ENTRY_TIMEOUT })
+    if (!entry || !entry.value) {
+      throw new Error('File content not available')
+    }
+
+    const chunks = []
+    const stream = drive.createReadStream(driveKey, { start: offset, end: offset + limit - 1 })
+
+    const timeoutPromise = new Promise((_, reject) => {
+      setTimeout(() => reject(new Error('Stream read timeout')), STREAM_READ_TIMEOUT)
+    })
+
+    const readPromise = (async () => {
+      for await (const chunk of stream) {
+        chunks.push(chunk)
+      }
+    })()
+
+    await Promise.race([readPromise, timeoutPromise])
+
+    const content = Buffer.concat(chunks).toString('utf8')
+    const hasMore = chunks.length > 0 && chunks[chunks.length - 1].length === limit
+
+    return { content, hasMore }
+  }
+
+  /**
+   * 读取已发布文件的原始内容（用于预览/下载）
+   * Hyperdrive 中用 CID 作为 key 存储
+   * @param {string} cid - 文件的 CID
+   * @param {object} [options] - 选项
+   * @param {number} [options.offset=0] - 读取起始位置
+   * @param {number} [options.limit] - 最大读取字节数，不指定则读取到末尾
+   * @param {number} [options.timeout=10000] - 流读取超时（毫秒）
+   * @returns {Promise<{buffer: Buffer, fileName: string, totalSize: number}>}
+   */
+  async readFileRaw(cid, options = {}) {
+    this.#ensureInitialized()
+
+    const fileRecord = this.#publishedFiles.find(f => f.cid === cid)
+    if (!fileRecord) {
+      throw new Error('File not found')
+    }
+
+    const drive = await this.#getDriveForFile(fileRecord)
+
+    const driveKey = '/' + cid
+    const entry = await drive.entry(driveKey, { wait: true, timeout: DRIVE_ENTRY_TIMEOUT })
+    if (!entry || !entry.value || !entry.value.blob) {
+      throw new Error('File content not available')
+    }
+
+    const totalSize = entry.value.blob.byteLength || 0
+
+    const { offset = 0, limit, timeout = STREAM_READ_TIMEOUT } = options
+    const effectiveLimit = (limit === undefined || limit === null)
+      ? totalSize - offset
+      : Math.min(limit, totalSize - offset)
+
+    if (effectiveLimit <= 0) {
+      return { buffer: Buffer.alloc(0), fileName: fileRecord.fileName, totalSize }
+    }
+
+    const chunks = []
+    const stream = drive.createReadStream(driveKey, {
+      start: offset,
+      end: offset + effectiveLimit - 1
+    })
+
+    const timeoutPromise = new Promise((_, reject) => {
+      setTimeout(() => reject(new Error('Stream read timeout')), timeout)
+    })
+
+    const readPromise = (async () => {
+      try {
+        for await (const chunk of stream) {
+          chunks.push(chunk)
+        }
+      } catch (err) {
+        if (err.message !== 'Stream read timeout') {
+          throw err
+        }
+      }
+    })()
+
+    await Promise.race([readPromise, timeoutPromise])
+    await readPromise.catch(() => { })
+
+    const buffer = Buffer.concat(chunks)
+    return { buffer, fileName: fileRecord.fileName, totalSize }
+  }
+
+  /**
+   * 获取文件对应的 drive，如果不存在则创建并同步
+   */
+  async #getDriveForFile(fileRecord) {
+    let drive = this.#drives.get(fileRecord.driveName)
+    if (!drive) {
+      drive = await this.#getOrCreateDrive(fileRecord.driveName, { server: true, client: true })
+    }
+    await this.#syncDrive(drive)
+    return drive
+  }
+
+  // --- 私有方法 ---
 
   #ensureInitialized() {
     if (!this.#initialized) {
@@ -880,21 +979,61 @@ export class MostBoxEngine extends EventEmitter {
     }
   }
 
+  async #getOrCreateDrive(name, options = { server: true, client: false }) {
+    if (this.#drives.has(name)) return this.#drives.get(name)
+    if (this.#drivePromises.has(name)) return this.#drivePromises.get(name)
+
+    const promise = (async () => {
+      const drive = new Hyperdrive(this.#store.namespace(name))
+      await drive.ready()
+      this.#drives.set(name, drive)
+      return drive
+    })()
+
+    this.#drivePromises.set(name, promise)
+
+    try {
+      const drive = await promise
+      return drive
+    } finally {
+      this.#drivePromises.delete(name)
+    }
+  }
+
+  async #syncDrive(drive, timeout = DRIVE_SYNC_TIMEOUT) {
+    const done = drive.findingPeers()
+    this.#swarm.join(drive.discoveryKey, { server: true, client: true }).flushed().then(done, done)
+    try {
+      const updated = await Promise.race([
+        drive.update(),
+        new Promise((_, reject) => setTimeout(() => reject(new Error('Sync timeout')), timeout))
+      ])
+      return updated
+    } catch {
+      return false
+    }
+  }
+
   #getMetadataPath() {
     return path.join(this.#options.dataPath, 'published-files.json')
   }
-  
+
   #getTrashMetadataPath() {
     return path.join(this.#options.dataPath, 'trash-files.json')
   }
 
+  #atomicWrite(filePath, data) {
+    const tmpPath = filePath + '.tmp'
+    fs.writeFileSync(tmpPath, data, 'utf-8')
+    fs.renameSync(tmpPath, filePath)
+  }
+
   #loadPublishedMetadata() {
     try {
       const metadataPath = this.#getMetadataPath()
       if (fs.existsSync(metadataPath)) {
         const data = fs.readFileSync(metadataPath, 'utf-8')
         const parsed = JSON.parse(data)
-        // Ensure starred field exists for older data
         return parsed.map(f => ({ ...f, starred: f.starred || false }))
       }
     } catch (err) {
@@ -906,12 +1045,12 @@ export class MostBoxEngine extends EventEmitter {
   #savePublishedMetadata() {
     try {
       const metadataPath = this.#getMetadataPath()
-      fs.writeFileSync(metadataPath, JSON.stringify(this.#publishedFiles, null, 2), 'utf-8')
+      this.#atomicWrite(metadataPath, JSON.stringify(this.#publishedFiles, null, 2))
     } catch (err) {
       console.error('Failed to save published metadata:', err.message)
     }
   }
-  
+
   #loadTrashMetadata() {
     try {
       const metadataPath = this.#getTrashMetadataPath()
@@ -924,32 +1063,31 @@ export class MostBoxEngine extends EventEmitter {
     }
     return []
   }
-  
+
   #saveTrashMetadata() {
     try {
       const metadataPath = this.#getTrashMetadataPath()
-      fs.writeFileSync(metadataPath, JSON.stringify(this.#trashFiles, null, 2), 'utf-8')
+      this.#atomicWrite(metadataPath, JSON.stringify(this.#trashFiles, null, 2))
     } catch (err) {
       console.error('Failed to save trash metadata:', err.message)
     }
   }
 
   /**
-   * Wait for drive content to be available from peers or local
-   * @param {Hyperdrive} drive - The drive to check
-   * @param {number} timeout - Maximum wait time in ms
-   * @param {string} [taskId] - Task ID for cancellation
-   * @param {object} [taskState] - Task state object
-   * @returns {Promise<Array>} - List of entries
+   * 等待驱动器内容从对等节点或本地可用
+   * @param {Hyperdrive} drive - 要检查的驱动器
+   * @param {number} timeout - 最大等待时间（毫秒）
+   * @param {string} [taskId] - 用于取消的任务 ID
+   * @param {object} [taskState] - 任务状态对象
+   * @returns {Promise<Array>} - 条目列表
    */
   async #waitForDriveContent(drive, timeout, taskId = null, taskState = null) {
     const startTime = Date.now()
-    const checkInterval = 1000 // Check every second
+    const checkInterval = DOWNLOAD_POLL_INTERVAL
     let lastPeerCount = 0
     let lastStatus = ''
     let bootstrapNodesChecked = false
 
-    // First, check if content is already available locally (for self-published files)
     const localEntries = []
     try {
       for await (const entry of drive.list()) {
@@ -961,36 +1099,32 @@ export class MostBoxEngine extends EventEmitter {
         return localEntries
       }
     } catch (err) {
-      // Continue to peer discovery
+      // 继续进行节点发现
     }
 
     while (Date.now() - startTime < timeout) {
-      // Check cancellation
       if (taskState && taskState.aborted) {
         throw new Error('Download cancelled')
       }
 
       const currentTime = Date.now()
       const elapsed = Math.round((currentTime - startTime) / 1000)
-      
-      // Check if we have peers
+
       const currentPeerCount = this.#swarm.connections.size
       const hasPeers = currentPeerCount > 0
 
-      // Log peer count changes
       if (currentPeerCount !== lastPeerCount) {
         console.log(`[MostBox] Peer count changed: ${lastPeerCount} -> ${currentPeerCount} (elapsed: ${elapsed}s)`)
         lastPeerCount = currentPeerCount
       }
 
-      // Try to list entries (works for both local and synced data)
       const entries = []
       try {
         for await (const entry of drive.list()) {
           entries.push(entry)
         }
       } catch (err) {
-        // Drive might not be ready yet
+        // 驱动器可能尚未就绪
       }
 
       if (entries.length > 0) {
@@ -999,7 +1133,6 @@ export class MostBoxEngine extends EventEmitter {
         return entries
       }
 
-      // Update status based on peer connection
       if (hasPeers) {
         const newStatus = 'syncing'
         if (lastStatus !== newStatus) {
@@ -1012,12 +1145,10 @@ export class MostBoxEngine extends EventEmitter {
           this.emit('download:status', { taskId, status: newStatus })
           lastStatus = newStatus
         }
-        
-        // Log progress every 30 seconds
+
         if (elapsed % 30 === 0 && elapsed > 0) {
-          console.log(`[MostBox] Still waiting for peers... (${elapsed}s elapsed, timeout: ${timeout/1000}s)`)
-          
-          // Check if bootstrap nodes are reachable (only once)
+          console.log(`[MostBox] Still waiting for peers... (${elapsed}s elapsed, timeout: ${timeout / 1000}s)`)
+
           if (!bootstrapNodesChecked && elapsed >= 60) {
             bootstrapNodesChecked = true
             console.log(`[MostBox] No peers found after 60s. This may indicate:`)
@@ -1029,13 +1160,11 @@ export class MostBoxEngine extends EventEmitter {
         }
       }
 
-      // Wait before next check
       await new Promise(resolve => setTimeout(resolve, checkInterval))
     }
 
-    console.log(`[MostBox] Timeout reached after ${timeout/1000}s, making final attempt...`)
+    console.log(`[MostBox] Timeout reached after ${timeout / 1000}s, making final attempt...`)
 
-    // Final attempt - return whatever we have (might be empty)
     const entries = []
     try {
       for await (const entry of drive.list()) {
@@ -1044,30 +1173,29 @@ export class MostBoxEngine extends EventEmitter {
     } catch (err) {
       console.log(`[MostBox] Final attempt failed: ${err.message}`)
     }
-    
+
     console.log(`[MostBox] Final entry count: ${entries.length}`)
-    
-    // Provide detailed error information
+
     if (entries.length === 0) {
       const peerCount = this.#swarm.connections.size
       console.log(`[MostBox] Diagnostic information:`)
       console.log(`[MostBox] - Peer count: ${peerCount}`)
       console.log(`[MostBox] - Bootstrap nodes: ${SWARM_BOOTSTRAP.length}`)
-      console.log(`[MostBox] - Timeout: ${timeout/1000}s`)
-      
+      console.log(`[MostBox] - Timeout: ${timeout / 1000}s`)
+
       if (peerCount === 0) {
         console.log(`[MostBox] Suggestion: Check network connectivity and firewall settings`)
       } else {
         console.log(`[MostBox] Suggestion: Publisher may be offline or file may have been removed`)
       }
     }
-    
+
     return entries
   }
 }
 
-// Re-export utilities
+// 重新导出工具函数
 export * from './config.js'
 export * from './core/cid.js'
 export * from './utils/errors.js'
-export * from './utils/security.js'
+export * from './utils/security.js'