most-box 0.1.0 → 0.1.1

package/server/src/index.js

@@ -33,6 +33,7 @@ import {
   PeerNotFoundError,
   IntegrityError,
   PermissionError,
+  ConflictError,
   EngineNotInitializedError,
 } from './utils/errors.js'
 import {
@@ -51,6 +52,8 @@ import {
   DOWNLOAD_POLL_INTERVAL_MIN,
   DOWNLOAD_POLL_INTERVAL_MAX,
   DRIVE_UPDATE_INTERVAL,
+  HOLDING_REJOIN_BATCH_SIZE,
+  HOLDING_REJOIN_BATCH_DELAY,
   PROGRESS_THROTTLE,
   DEFAULT_READ_LIMIT,
   CHANNEL_NAME_MIN_LENGTH,
@@ -61,16 +64,22 @@ import {
   MAX_MESSAGE_LENGTH,
 } from './config.js'
 
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms))
+
 export class MostBoxEngine extends EventEmitter {
   #store = null
   #swarm = null
   #drives = new Map()
   #publishedFiles = []
+  #holdings = []
   #trashFiles = []
   #initialized = false
   #options = null
   #activeDownloads = new Map()
   #drivePromises = new Map()
+  #fileDiscoveries = new Map()
+  #seedStates = new Map()
+  #holdingResumeTask = null
 
   #channels = []
   #channelCores = new Map()
@@ -99,6 +108,7 @@ export class MostBoxEngine extends EventEmitter {
       downloadPath:
         options.downloadPath || path.join(options.dataPath, 'downloads'),
       maxFileSize: options.maxFileSize || MAX_FILE_SIZE,
+      downloadTimeout: options.downloadTimeout || DOWNLOAD_TIMEOUT,
     }
   }
 
@@ -230,6 +240,17 @@ export class MostBoxEngine extends EventEmitter {
       `[MostBox] Loaded ${this.#publishedFiles.length} published files`
     )
 
+    this.#holdings = this.#loadHoldingsMetadata()
+    console.log(`[MostBox] Loaded ${this.#holdings.length} node holdings`)
+
+    for (const holding of this.#holdings) {
+      this.#setSeedState(holding.cid, {
+        status: 'queued',
+        topic: holding.topic,
+        driveName: holding.driveName,
+      })
+    }
+
     this.#trashFiles = this.#loadTrashMetadata()
     console.log(`[MostBox] Loaded ${this.#trashFiles.length} trash files`)
 
@@ -274,6 +295,7 @@ export class MostBoxEngine extends EventEmitter {
     this.#initialized = true
     console.log(`[MostBox] Engine initialized successfully`)
     this.emit('ready')
+    this.#resumeHoldingsInBackground()
 
     return this
   }
@@ -295,6 +317,9 @@ export class MostBoxEngine extends EventEmitter {
 
     await Promise.allSettled([...this.#drives.values()].map(d => d.close()))
     this.#drives.clear()
+    this.#fileDiscoveries.clear()
+    this.#seedStates.clear()
+    this.#holdingResumeTask = null
 
     for (const core of this.#channelCores.values()) {
       try {
@@ -359,9 +384,11 @@ export class MostBoxEngine extends EventEmitter {
    * Hyperdrive 中存储 key 为 '/' + cid，metadata 中存储 displayName（用户看到的路径）
    * @param {string|Buffer} content - 文件路径（字符串）或内容（Buffer）
    * @param {string} [fileName] - 文件名（Buffer 输入时必填）
+   * @param {object} [options] - 发布选项
+   * @param {string|null} [options.localPath] - 持有记录中的本地路径
    * @returns {Promise<{ cid: string, link: string, fileName: string }>}
    */
-  async publishFile(content, fileName) {
+  async publishFile(content, fileName, options = {}) {
     this.#ensureInitialized()
 
     let cleanPath = null
@@ -409,6 +436,9 @@ export class MostBoxEngine extends EventEmitter {
 
     const { cid: rootCid } = await calculateCid(content)
     const cidString = rootCid.toString()
+    const { driveName: name } = this.#getCidInfo(cidString)
+    const holdingLocalPath =
+      options.localPath === undefined ? cleanPath : options.localPath
 
     // 检查相同内容是否已存在
     const existingIndex = this.#publishedFiles.findIndex(
@@ -416,17 +446,28 @@ export class MostBoxEngine extends EventEmitter {
     )
     if (existingIndex !== -1) {
       const existing = this.#publishedFiles[existingIndex]
+      await this.#joinCidTopicInternal(cidString, {
+        server: true,
+        client: false,
+      })
+      this.#upsertHolding({
+        cid: cidString,
+        fileName: existing.fileName,
+        size: fileSize,
+        localPath: holdingLocalPath,
+        driveName: name,
+        source: 'published',
+        temporary: false,
+      })
       return {
         cid: cidString,
-        link: `most://${cidString}`,
+        link: `most://${cidString}?filename=${encodeURIComponent(existing.fileName)}`,
         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) {
@@ -434,12 +475,15 @@ export class MostBoxEngine extends EventEmitter {
         server: true,
         client: false,
       })
-      const discovery = this.#swarm.join(drive.discoveryKey, {
+      this.#swarm.join(drive.discoveryKey, {
         server: true,
         client: false,
       })
-      await discovery.flushed()
     }
+    await this.#joinCidTopicInternal(cidString, {
+      server: true,
+      client: false,
+    })
 
     this.emit('publish:progress', { stage: 'uploading', file: safeFileName })
 
@@ -490,6 +534,15 @@ export class MostBoxEngine extends EventEmitter {
       starred: false,
     })
     this.#savePublishedMetadata()
+    this.#upsertHolding({
+      cid: cidString,
+      fileName: safeFileName,
+      size: fileSize,
+      localPath: holdingLocalPath,
+      driveName: name,
+      source: 'published',
+      temporary: false,
+    })
 
     const result = {
       cid: cidString,
@@ -505,13 +558,18 @@ export class MostBoxEngine extends EventEmitter {
    * 从 P2P 网络下载文件
    * @param {string} link - most:// 链接
    * @param {string} [taskId] - 用于取消的任务 ID
+   * @param {object} [options] - 下载选项
+   * @param {number} [options.timeout] - 等待 P2P 内容的超时时间（毫秒）
+   * @param {number} [options.streamReadTimeout] - 下载流无进度超时时间（毫秒）
    * @returns {Promise<{ taskId: string, fileName: string, savedPath: string, alreadyExists?: boolean }>}
    */
-  async downloadFile(link, taskId = null) {
+  async downloadFile(link, taskId = null, options = {}) {
     this.#ensureInitialized()
 
     taskId =
       taskId || `dl_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`
+    const downloadTimeout = options.timeout || this.#options.downloadTimeout
+    const streamReadTimeout = options.streamReadTimeout ?? STREAM_READ_TIMEOUT
 
     console.log(
       `[MostBox] Starting download for link: ${link} (taskId: ${taskId})`
@@ -527,10 +585,32 @@ export class MostBoxEngine extends EventEmitter {
       }
       const cidString = parsed.cid
       console.log(`[MostBox] Parsed CID: ${cidString}`)
+      const parsedCid = CID.parse(cidString)
+      const { driveName: name } = this.#getCidInfo(cidString)
 
       const existingFile = this.#publishedFiles.find(f => f.cid === cidString)
       if (existingFile) {
         console.log(`[MostBox] File already exists: ${existingFile.fileName}`)
+        const existingHolding = this.#holdings.find(
+          item => item.cid === cidString
+        )
+        const existingSize = Number(existingFile.size)
+        await this.#joinCidTopicInternal(cidString, {
+          server: true,
+          client: false,
+        })
+        this.#upsertHolding({
+          cid: cidString,
+          fileName: existingFile.fileName,
+          size:
+            existingHolding?.size ??
+            (Number.isFinite(existingSize) ? existingSize : 0),
+          localPath:
+            existingHolding?.localPath || existingFile.localPath || null,
+          driveName: existingFile.driveName || name,
+          source: existingHolding?.source || 'published',
+          temporary: existingHolding?.temporary === true,
+        })
         return {
           taskId,
           fileName: existingFile.fileName,
@@ -540,12 +620,8 @@ export class MostBoxEngine extends EventEmitter {
 
       const linkFileName = parsed.fileName
 
-      const parsedCid = CID.parse(cidString)
-      const hashHex = b4a.toString(parsedCid.multihash.digest, 'hex')
-
       if (taskState.aborted) throw new Error('Download cancelled')
 
-      const name = `drive-${hashHex}`
       let drive = this.#drives.get(name)
 
       if (!drive) {
@@ -558,33 +634,40 @@ export class MostBoxEngine extends EventEmitter {
         this.emit('download:status', { taskId, status: 'connecting' })
 
         console.log(`[MostBox] Joining swarm for drive discovery...`)
-        await this.#swarm
-          .join(drive.discoveryKey, { server: true, client: true })
-          .flushed()
-        console.log(`[MostBox] Swarm join flushed`)
+        this.#swarm.join(drive.discoveryKey, {
+          server: true,
+          client: true,
+        })
+        console.log(`[MostBox] Swarm join requested`)
       } else {
         console.log(`[MostBox] Using existing drive: ${name}`)
       }
+      await this.#joinCidTopicInternal(cidString, {
+        server: true,
+        client: true,
+      })
 
       if (taskState.aborted) throw new Error('Download cancelled')
 
       this.emit('download:status', { taskId, status: 'finding-peers' })
 
       console.log(
-        `[MostBox] Waiting for drive content (timeout: ${DOWNLOAD_TIMEOUT / 1000}s)...`
+        `[MostBox] Waiting for drive entry /${cidString} (timeout: ${downloadTimeout / 1000}s)...`
       )
-      const entries = await this.#waitForDriveContent(
+      const driveKey = '/' + cidString
+      const entry = await this.#waitForDriveEntry(
         drive,
-        DOWNLOAD_TIMEOUT,
+        driveKey,
+        downloadTimeout,
         taskId,
         taskState
       )
 
-      if (entries.length === 0) {
-        console.log(`[MostBox] No entries found after timeout`)
+      if (!entry) {
+        console.log(`[MostBox] Expected drive entry ${driveKey} not found`)
 
         const peerCount = this.#swarm.connections.size
-        let errorMessage = 'No files found in drive. '
+        let errorMessage = `Expected file ${driveKey} was not found. `
 
         if (peerCount === 0) {
           errorMessage +=
@@ -606,10 +689,10 @@ export class MostBoxEngine extends EventEmitter {
       if (taskState.aborted) throw new Error('Download cancelled')
 
       console.log(
-        `[MostBox] Found ${entries.length} entries, starting download...`
+        `[MostBox] Found expected entry ${driveKey}, starting download...`
       )
 
-      const targetDir = this.#options.dataPath
+      const targetDir = this.#options.downloadPath
 
       const writableCheck = await checkDirectoryWritable(targetDir)
       if (!writableCheck.writable) {
@@ -617,6 +700,7 @@ export class MostBoxEngine extends EventEmitter {
       }
 
       // 下载文件
+      const entries = [entry]
       for (const entry of entries) {
         const cleanKey = entry.key.replace(/^[\/\\]/, '')
         const sanitizedFileName = linkFileName
@@ -634,6 +718,10 @@ export class MostBoxEngine extends EventEmitter {
         }
 
         const savePath = path.join(targetDir, sanitizedFileName)
+        fs.mkdirSync(path.dirname(savePath), { recursive: true })
+        if (fs.existsSync(savePath)) {
+          throw new ConflictError(`已有同名文件: ${sanitizedFileName}`)
+        }
 
         this.emit('download:status', {
           taskId,
@@ -652,14 +740,54 @@ export class MostBoxEngine extends EventEmitter {
         let lastProgressUpdate = 0
 
         await new Promise((resolve, reject) => {
+          let settled = false
+          let readTimer = null
+
+          const clearReadTimer = () => {
+            if (readTimer) {
+              clearTimeout(readTimer)
+              readTimer = null
+            }
+          }
+
+          const fail = err => {
+            if (settled) return
+            settled = true
+            clearReadTimer()
+            rs.destroy(err)
+            ws.destroy()
+            fs.unlink(savePath, () => {})
+            reject(err)
+          }
+
+          const complete = () => {
+            if (settled) return
+            settled = true
+            clearReadTimer()
+            resolve()
+          }
+
+          const resetReadTimer = () => {
+            clearReadTimer()
+            if (streamReadTimeout > 0) {
+              readTimer = setTimeout(() => {
+                fail(
+                  new Error(
+                    `Download stalled: no data received for ${streamReadTimeout / 1000}s`
+                  )
+                )
+              }, streamReadTimeout)
+            }
+          }
+
+          resetReadTimer()
+
           rs.on('data', chunk => {
             if (taskState.aborted) {
-              rs.destroy()
-              ws.destroy()
-              fs.unlink(savePath, () => {})
-              reject(new Error('Download cancelled'))
+              fail(new Error('Download cancelled'))
               return
             }
+            resetReadTimer()
             loadedBytes += chunk.length
             const now = Date.now()
             if (
@@ -678,9 +806,19 @@ export class MostBoxEngine extends EventEmitter {
           })
 
           rs.pipe(ws)
-          ws.on('finish', resolve)
-          ws.on('error', reject)
-          rs.on('error', reject)
+          ws.on('finish', complete)
+          ws.on('error', fail)
+          rs.on('error', fail)
+          rs.on('close', () => {
+            if (taskState.aborted) {
+              fail(new Error('Download cancelled'))
+            }
+          })
+          ws.on('close', () => {
+            if (taskState.aborted) {
+              fail(new Error('Download cancelled'))
+            }
+          })
         })
 
         if (taskState.aborted) throw new Error('Download cancelled')
@@ -738,6 +876,16 @@ export class MostBoxEngine extends EventEmitter {
           })
         }
         this.#savePublishedMetadata()
+        const savedSize = totalBytes || fs.statSync(savePath).size
+        this.#upsertHolding({
+          cid: cidString,
+          fileName: sanitizedFileName,
+          size: savedSize,
+          localPath: savePath,
+          driveName: name,
+          source: 'downloaded',
+          temporary: true,
+        })
 
         this.emit('download:success', result)
         return result
@@ -747,6 +895,86 @@ export class MostBoxEngine extends EventEmitter {
     }
   }
 
+  /**
+   * 检测 most:// 链接当前是否能找到可下载内容，但不读取文件内容。
+   * @param {string} link - most:// 链接
+   * @param {object} [options] - 检测选项
+   * @param {number} [options.timeout] - 等待 P2P 内容的超时时间（毫秒）
+   * @returns {Promise<{ available: boolean, cid: string, fileName: string, size: number|null, alreadyExists?: boolean }>}
+   */
+  async checkDownloadAvailability(link, options = {}) {
+    this.#ensureInitialized()
+
+    const timeout = options.timeout || DRIVE_ENTRY_TIMEOUT
+    const parsed = parseMostLink(link)
+    if (parsed.error) {
+      throw new ValidationError(parsed.error)
+    }
+
+    const cidString = parsed.cid
+    const { driveName: name } = this.#getCidInfo(cidString)
+    const existingFile = this.#publishedFiles.find(f => f.cid === cidString)
+    if (existingFile) {
+      return {
+        available: true,
+        cid: cidString,
+        fileName: existingFile.fileName,
+        size: Number(existingFile.size) || null,
+        alreadyExists: true,
+      }
+    }
+
+    const writableCheck = await checkDirectoryWritable(
+      this.#options.downloadPath
+    )
+    if (!writableCheck.writable) {
+      throw new PermissionError(writableCheck.error)
+    }
+
+    let drive = this.#drives.get(name)
+
+    if (!drive) {
+      drive = await this.#getOrCreateDrive(name, {
+        server: true,
+        client: true,
+      })
+
+      this.#swarm.join(drive.discoveryKey, {
+        server: true,
+        client: true,
+      })
+    }
+
+    await this.#joinCidTopicInternal(cidString, {
+      server: true,
+      client: true,
+    })
+
+    const driveKey = '/' + cidString
+    const entry = await this.#waitForDriveEntry(drive, driveKey, timeout)
+
+    if (!entry) {
+      throw new PeerNotFoundError(
+        '当前没有发现可下载的在线种子，请稍后重试或确认发布者在线'
+      )
+    }
+
+    let size = null
+    try {
+      const stat = await drive.entry(entry.key)
+      if (stat?.value?.blob) {
+        size = stat.value.blob.byteLength || 0
+      }
+    } catch {}
+
+    return {
+      available: true,
+      cid: cidString,
+      fileName: parsed.fileName,
+      size,
+    }
+  }
+
   /**
    * 列出所有已发布文件
    * @param {object} [options] - 筛选选项
@@ -764,7 +992,7 @@ export class MostBoxEngine extends EventEmitter {
     return files.map(f => ({
       fileName: f.fileName,
       cid: f.cid,
-      link: `most://${f.cid}`,
+      link: `most://${f.cid}?filename=${encodeURIComponent(f.fileName)}`,
       publishedAt: f.publishedAt,
       starred: f.starred || false,
     }))
@@ -799,17 +1027,28 @@ export class MostBoxEngine extends EventEmitter {
     const index = this.#publishedFiles.findIndex(f => f.cid === cid)
     if (index !== -1) {
       const fileRecord = this.#publishedFiles[index]
+      const holding = this.#holdings.find(item => item.cid === fileRecord.cid)
 
       this.#trashFiles.push({
         fileName: fileRecord.fileName,
         cid: fileRecord.cid,
-        driveName: fileRecord.driveName,
+        driveName:
+          fileRecord.driveName || this.#getCidInfo(fileRecord.cid).driveName,
+        size: holding?.size ?? fileRecord.size ?? 0,
+        localPath: holding?.localPath || fileRecord.localPath || null,
+        source: holding?.source || 'published',
         publishedAt: fileRecord.publishedAt,
         starred: fileRecord.starred || false,
         deletedAt: new Date().toISOString(),
       })
       this.#saveTrashMetadata()
 
+      await this.#leaveCidTopic(fileRecord.cid)
+      await this.#closeDriveForSeed(
+        fileRecord.driveName || this.#getCidInfo(fileRecord.cid).driveName
+      )
+      this.#removeHolding(fileRecord.cid)
+
       this.#publishedFiles.splice(index, 1)
       this.#savePublishedMetadata()
     }
@@ -825,7 +1064,7 @@ export class MostBoxEngine extends EventEmitter {
     return this.#trashFiles.map(f => ({
       fileName: f.fileName,
       cid: f.cid,
-      link: `most://${f.cid}`,
+      link: `most://${f.cid}?filename=${encodeURIComponent(f.fileName)}`,
       publishedAt: f.publishedAt,
       starred: f.starred || false,
       deletedAt: f.deletedAt,
@@ -835,9 +1074,9 @@ export class MostBoxEngine extends EventEmitter {
   /**
    * 从回收站恢复文件
    * @param {string} cid - 要恢复文件的 CID
-   * @returns {Array} 更新后的已发布文件列表
+   * @returns {Promise<Array>} 更新后的已发布文件列表
    */
-  restoreTrashFile(cid) {
+  async restoreTrashFile(cid) {
     this.#ensureInitialized()
     const index = this.#trashFiles.findIndex(f => f.cid === cid)
     if (index === -1) {
@@ -862,6 +1101,20 @@ export class MostBoxEngine extends EventEmitter {
     this.#trashFiles.splice(index, 1)
     this.#saveTrashMetadata()
 
+    await this.#joinCidTopicInternal(fileRecord.cid, {
+      server: true,
+      client: false,
+    })
+    this.#upsertHolding({
+      cid: fileRecord.cid,
+      fileName: fileRecord.fileName,
+      size: Number(fileRecord.size) || 0,
+      localPath: fileRecord.localPath || null,
+      driveName,
+      source: fileRecord.source || 'published',
+      temporary: fileRecord.source === 'downloaded',
+    })
+
     return this.listPublishedFiles()
   }
 
@@ -875,21 +1128,19 @@ export class MostBoxEngine extends EventEmitter {
     const index = this.#trashFiles.findIndex(f => f.cid === cid)
     if (index !== -1) {
       const fileRecord = this.#trashFiles[index]
-      const driveName = fileRecord.driveName
-
-      const drive = this.#drives.get(driveName)
-      if (drive) {
-        try {
-          await drive.del('/' + fileRecord.cid)
-        } catch {
-          // 文件可能不存在于驱动器中
-        }
+      const driveName =
+        fileRecord.driveName || this.#getCidInfo(fileRecord.cid).driveName
 
-        await this.#swarm.leave(drive.discoveryKey)
-        await drive.close()
-        this.#drives.delete(driveName)
+      try {
+        const drive = await this.#getOrCreateDrive(driveName)
+        await drive.del('/' + fileRecord.cid)
+      } catch {
+        // 文件可能不存在于驱动器中
       }
+      await this.#closeDriveForSeed(driveName)
 
+      await this.#leaveCidTopic(fileRecord.cid)
+      this.#removeHolding(fileRecord.cid)
       this.#trashFiles.splice(index, 1)
       this.#saveTrashMetadata()
     }
@@ -904,20 +1155,18 @@ export class MostBoxEngine extends EventEmitter {
     this.#ensureInitialized()
 
     for (const fileRecord of this.#trashFiles) {
-      const driveName = fileRecord.driveName
-
-      const drive = this.#drives.get(driveName)
-      if (drive) {
-        try {
-          await drive.del('/' + fileRecord.cid)
-        } catch {
-          // 文件可能不存在
-        }
+      const driveName =
+        fileRecord.driveName || this.#getCidInfo(fileRecord.cid).driveName
 
-        await this.#swarm.leave(drive.discoveryKey)
-        await drive.close()
-        this.#drives.delete(driveName)
+      try {
+        const drive = await this.#getOrCreateDrive(driveName)
+        await drive.del('/' + fileRecord.cid)
+      } catch {
+        // 文件可能不存在
       }
+      await this.#closeDriveForSeed(driveName)
+      await this.#leaveCidTopic(fileRecord.cid)
+      this.#removeHolding(fileRecord.cid)
     }
 
     this.#trashFiles = []
@@ -1007,7 +1256,7 @@ export class MostBoxEngine extends EventEmitter {
     return {
       cid,
       fileName: safeFileName,
-      link: `most://${cid}`,
+      link: `most://${cid}?filename=${encodeURIComponent(safeFileName)}`,
     }
   }
 
@@ -1034,7 +1283,7 @@ export class MostBoxEngine extends EventEmitter {
         updatedFiles.push({
           cid: file.cid,
           fileName: file.fileName,
-          link: `most://${file.cid}`,
+          link: `most://${file.cid}?filename=${encodeURIComponent(file.fileName)}`,
         })
       }
     }
@@ -1054,15 +1303,143 @@ export class MostBoxEngine extends EventEmitter {
     const task = this.#activeDownloads.get(taskId)
     if (task) {
       task.aborted = true
-      if (task.readStream) task.readStream.destroy()
+      const err = new Error('Download cancelled')
+      if (task.readStream) task.readStream.destroy(err)
       if (task.writeStream) task.writeStream.destroy()
     }
   }
 
+  hasDownloadNameConflict(fileName) {
+    this.#ensureInitialized()
+    const sanitizedFileName = sanitizeFilename(fileName)
+    const savePath = path.join(this.#options.downloadPath, sanitizedFileName)
+    return fs.existsSync(savePath)
+  }
+
+  setMaxFileSize(maxFileSize) {
+    const parsed = Number(maxFileSize)
+    if (!Number.isFinite(parsed) || parsed < 0) {
+      throw new ValidationError('maxFileSize must be a non-negative number')
+    }
+    this.#options.maxFileSize = Math.floor(parsed)
+  }
+
   getPublishedFiles() {
     return this.#publishedFiles
   }
 
+  /**
+   * 列出当前节点持有的可做种文件副本
+   * @returns {Array}
+   */
+  listHoldings() {
+    this.#ensureInitialized()
+    return this.#holdings.map(holding => {
+      const seedState = this.#seedStates.get(holding.cid)
+      const status =
+        seedState?.status ||
+        (this.#fileDiscoveries.has(holding.cid) ? 'active' : 'queued')
+      return {
+        ...holding,
+        joined: status === 'active' && this.#fileDiscoveries.has(holding.cid),
+        seedStatus: status,
+        seedError: seedState?.error,
+        seedStatusUpdatedAt: seedState?.updatedAt,
+        link: `most://${holding.cid}?filename=${encodeURIComponent(holding.fileName || holding.cid)}`,
+      }
+    })
+  }
+
+  /**
+   * 手动记录节点已持有的文件副本
+   * @param {object} record - 持有记录
+   */
+  async addHolding(record) {
+    this.#ensureInitialized()
+    const holding = this.#normalizeHolding(record)
+    await this.#joinCidTopicInternal(holding.cid, {
+      server: true,
+      client: false,
+    })
+    return this.#upsertHolding(holding)
+  }
+
+  /**
+   * 按 CID digest topic 拉取完整文件副本
+   * @param {object} input - 拉取参数
+   * @param {string} [input.link] - most:// 链接
+   * @param {string} [input.cid] - 文件 CID
+   * @param {string} [input.fileName] - 保存文件名
+   * @param {string} [input.taskId] - 下载任务 ID
+   * @param {number} [input.timeout] - 等待 P2P 内容的超时时间
+   */
+  async pullByCid(input = {}) {
+    this.#ensureInitialized()
+
+    if (input.link) {
+      const parsed = parseMostLink(input.link)
+      if (parsed.error) {
+        throw new ValidationError(parsed.error)
+      }
+      const result = await this.downloadFile(input.link, input.taskId || null, {
+        timeout: input.timeout,
+      })
+      return {
+        ...result,
+        cid: parsed.cid,
+      }
+    }
+
+    const cid = input.cid
+    if (!cid) {
+      throw new ValidationError('cid is required')
+    }
+
+    this.#getCidInfo(cid)
+    const fileName = sanitizeFilename(input.fileName || `${cid}.bin`)
+    const link = `most://${cid}?filename=${encodeURIComponent(fileName)}`
+    const result = await this.downloadFile(link, input.taskId || null, {
+      timeout: input.timeout,
+    })
+
+    return {
+      ...result,
+      cid,
+    }
+  }
+
+  /**
+   * 按 CID digest 加入文件 topic
+   * @param {string} cid - 文件 CID
+   * @param {object} [options] - Hyperswarm join 选项
+   */
+  async joinCidTopic(cid, options = {}) {
+    this.#ensureInitialized()
+    return this.#joinCidTopicInternal(cid, options)
+  }
+
+  /**
+   * 用内存复制流连接两个本地引擎，供本地集成测试和诊断使用。
+   */
+  replicateWith(peerEngine) {
+    this.#ensureInitialized()
+    peerEngine.#ensureInitialized()
+
+    const left = this.#store.replicate(true, { live: true })
+    const right = peerEngine.#store.replicate(false, { live: true })
+
+    left.on('error', () => {})
+    right.on('error', () => {})
+    left.pipe(right).pipe(left)
+
+    return {
+      close: () => {
+        left.destroy()
+        right.destroy()
+      },
+    }
+  }
+
   /**
    * 读取已发布文件的内容（用于预览）
    * Hyperdrive 中用 CID 作为 key 存储
@@ -1243,12 +1620,10 @@ export class MostBoxEngine extends EventEmitter {
       server: true,
       client: true,
     })
-    await appDiscovery.flushed()
     const chatDiscovery = this.#chatSwarm.join(chatDiscoveryKey, {
       server: true,
       client: true,
     })
-    await chatDiscovery.flushed()
 
     this.#setupChannelAppendListener(core, name)
 
@@ -1304,12 +1679,10 @@ export class MostBoxEngine extends EventEmitter {
       server: true,
       client: true,
     })
-    await appDiscovery.flushed()
     const chatDiscovery = this.#chatSwarm.join(chatDiscoveryKey, {
       server: true,
       client: true,
     })
-    await chatDiscovery.flushed()
 
     this.#setupChannelAppendListener(core, name)
 
@@ -1351,29 +1724,25 @@ export class MostBoxEngine extends EventEmitter {
 
     const appDiscovery = this.#channelDiscoveries.get(name)
     if (appDiscovery && this.#swarm) {
-      try {
-        await this.#swarm.leave(b4a.from(channel.discoveryKey, 'hex'))
-      } catch (err) {
+      this.#channelDiscoveries.delete(name)
+      this.#swarm.leave(b4a.from(channel.discoveryKey, 'hex')).catch(err => {
         console.warn(
           `[MostBox] Failed to leave app swarm for ${name}:`,
           err.message
         )
-      }
-      this.#channelDiscoveries.delete(name)
+      })
     }
 
     const chatDiscovery = this.#channelChatDiscoveries.get(name)
     if (chatDiscovery && this.#chatSwarm) {
-      try {
-        const chatDiscoveryKey = this.#generateChannelChatDiscoveryKey(name)
-        await this.#chatSwarm.leave(chatDiscoveryKey)
-      } catch (err) {
+      this.#channelChatDiscoveries.delete(name)
+      const chatDiscoveryKey = this.#generateChannelChatDiscoveryKey(name)
+      this.#chatSwarm.leave(chatDiscoveryKey).catch(err => {
         console.warn(
           `[MostBox] Failed to leave chat swarm for ${name}:`,
           err.message
         )
-      }
-      this.#channelChatDiscoveries.delete(name)
+      })
     }
 
     const core = this.#channelCores.get(name)
@@ -1553,6 +1922,255 @@ export class MostBoxEngine extends EventEmitter {
     }
   }
 
+  #getCidInfo(cid) {
+    try {
+      const parsedCid = CID.parse(cid)
+      const topic = b4a.from(parsedCid.multihash.digest)
+      if (topic.length !== 32) {
+        throw new ValidationError('CID digest must be 32 bytes')
+      }
+      const topicHex = b4a.toString(topic, 'hex')
+      return {
+        topic,
+        topicHex,
+        driveName: `drive-${topicHex}`,
+      }
+    } catch (err) {
+      if (err instanceof ValidationError) {
+        throw err
+      }
+      throw new ValidationError('Invalid CID format')
+    }
+  }
+
+  #setSeedState(cid, patch = {}) {
+    const previous = this.#seedStates.get(cid) || {}
+    const next = {
+      ...previous,
+      cid,
+      ...patch,
+      updatedAt: new Date().toISOString(),
+    }
+    this.#seedStates.set(cid, next)
+    this.emit('seed:state', next)
+    return next
+  }
+
+  #clearSeedState(cid) {
+    if (this.#seedStates.delete(cid)) {
+      this.emit('seed:state:removed', { cid })
+    }
+  }
+
+  #resumeHoldingsInBackground() {
+    if (this.#holdingResumeTask || this.#holdings.length === 0) {
+      return
+    }
+
+    const holdings = [...this.#holdings]
+    this.#holdingResumeTask = (async () => {
+      for (
+        let index = 0;
+        index < holdings.length && this.#initialized;
+        index += HOLDING_REJOIN_BATCH_SIZE
+      ) {
+        const batch = holdings.slice(index, index + HOLDING_REJOIN_BATCH_SIZE)
+        await Promise.allSettled(
+          batch.map(async holding => {
+            if (!this.#holdings.some(current => current.cid === holding.cid)) {
+              return
+            }
+            await this.#joinCidTopicInternal(holding.cid, {
+              server: true,
+              client: false,
+            })
+            console.log(`[MostBox] Rejoined CID topic: ${holding.cid}`)
+          })
+        )
+
+        if (
+          index + HOLDING_REJOIN_BATCH_SIZE < holdings.length &&
+          this.#initialized
+        ) {
+          await sleep(HOLDING_REJOIN_BATCH_DELAY)
+        }
+      }
+    })()
+      .catch(err => {
+        console.warn('[MostBox] Failed to resume holdings:', err.message)
+      })
+      .finally(() => {
+        this.#holdingResumeTask = null
+      })
+  }
+
+  #normalizeHolding(record = {}) {
+    const cid = record.cid
+    if (!cid) {
+      throw new ValidationError('cid is required')
+    }
+
+    const { topicHex, driveName } = this.#getCidInfo(cid)
+    if (record.topic && record.topic !== topicHex) {
+      throw new ValidationError('topic must match CID digest')
+    }
+
+    const size = Number(record.size)
+    if (!Number.isFinite(size) || size < 0) {
+      throw new ValidationError('size must be a non-negative number')
+    }
+
+    return {
+      cid,
+      fileName: record.fileName || cid,
+      size,
+      localPath: record.localPath || null,
+      topic: topicHex,
+      driveName: record.driveName || driveName,
+      source: record.source || 'manual',
+      temporary: record.temporary === true,
+    }
+  }
+
+  #upsertHolding(record) {
+    const holding = this.#normalizeHolding(record)
+    const now = new Date().toISOString()
+    const index = this.#holdings.findIndex(f => f.cid === holding.cid)
+    const next =
+      index === -1
+        ? { ...holding, createdAt: now, updatedAt: now }
+        : { ...this.#holdings[index], ...holding, updatedAt: now }
+
+    if (index === -1) {
+      this.#holdings.push(next)
+    } else {
+      this.#holdings[index] = next
+    }
+
+    this.#saveHoldingsMetadata()
+    this.emit('holding:updated', next)
+    const seedState = this.#seedStates.get(next.cid)
+    return {
+      ...next,
+      joined: this.#fileDiscoveries.has(next.cid),
+      seedStatus:
+        seedState?.status ||
+        (this.#fileDiscoveries.has(next.cid) ? 'active' : 'queued'),
+      seedError: seedState?.error,
+      seedStatusUpdatedAt: seedState?.updatedAt,
+    }
+  }
+
+  #removeHolding(cid) {
+    const before = this.#holdings.length
+    this.#holdings = this.#holdings.filter(holding => holding.cid !== cid)
+    if (this.#holdings.length !== before) {
+      this.#saveHoldingsMetadata()
+      this.emit('holding:removed', { cid })
+    }
+    this.#clearSeedState(cid)
+  }
+
+  async #joinCidTopicInternal(cid, options = {}) {
+    const { topic, topicHex, driveName } = this.#getCidInfo(cid)
+    this.#setSeedState(cid, {
+      status: 'joining',
+      topic: topicHex,
+      driveName,
+      error: undefined,
+    })
+
+    try {
+      await this.#getOrCreateDrive(driveName)
+
+      const existing = this.#fileDiscoveries.get(cid)
+      if (existing) {
+        this.#setSeedState(cid, {
+          status: 'active',
+          topic: topicHex,
+          driveName,
+          error: undefined,
+        })
+        return {
+          cid,
+          topic: topicHex,
+          driveName,
+          joined: true,
+        }
+      }
+
+      const discovery = this.#swarm.join(topic, {
+        server: options.server !== false,
+        client: options.client === true,
+      })
+
+      this.#fileDiscoveries.set(cid, {
+        discovery,
+        topic: topicHex,
+        driveName,
+      })
+      this.#setSeedState(cid, {
+        status: 'active',
+        topic: topicHex,
+        driveName,
+        error: undefined,
+      })
+      this.emit('file:topic:joined', { cid, topic: topicHex, driveName })
+
+      return {
+        cid,
+        topic: topicHex,
+        driveName,
+        joined: true,
+      }
+    } catch (err) {
+      this.#setSeedState(cid, {
+        status: 'error',
+        topic: topicHex,
+        driveName,
+        error: err.message,
+      })
+      throw err
+    }
+  }
+
+  async #leaveCidTopic(cid) {
+    const existing = this.#fileDiscoveries.get(cid)
+    if (!existing || !this.#swarm) {
+      this.#setSeedState(cid, { status: 'paused' })
+      return
+    }
+
+    this.#fileDiscoveries.delete(cid)
+    this.#swarm.leave(b4a.from(existing.topic, 'hex')).catch(err => {
+      console.warn(`[MostBox] Failed to leave CID topic ${cid}:`, err.message)
+    })
+    this.#setSeedState(cid, {
+      status: 'paused',
+      topic: existing.topic,
+      driveName: existing.driveName,
+    })
+  }
+
+  async #closeDriveForSeed(driveName) {
+    const drive = this.#drives.get(driveName)
+    if (!drive) {
+      return null
+    }
+
+    if (this.#swarm) {
+      this.#swarm.leave(drive.discoveryKey).catch(err => {
+        console.warn(
+          `[MostBox] Failed to leave drive discovery ${driveName}:`,
+          err.message
+        )
+      })
+    }
+    await drive.close()
+    this.#drives.delete(driveName)
+    return drive
+  }
+
   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)
@@ -1597,6 +2215,10 @@ export class MostBoxEngine extends EventEmitter {
     return path.join(this.#options.dataPath, 'published-files.json')
   }
 
+  #getHoldingsMetadataPath() {
+    return path.join(this.#options.dataPath, 'node-holdings.json')
+  }
+
   #getTrashMetadataPath() {
     return path.join(this.#options.dataPath, 'trash-files.json')
   }
@@ -1636,6 +2258,32 @@ export class MostBoxEngine extends EventEmitter {
     }
   }
 
+  #loadHoldingsMetadata() {
+    try {
+      const metadataPath = this.#getHoldingsMetadataPath()
+      if (fs.existsSync(metadataPath)) {
+        const data = fs.readFileSync(metadataPath, 'utf-8')
+        const parsed = JSON.parse(data)
+        return parsed.map(record => this.#normalizeHolding(record))
+      }
+    } catch (err) {
+      console.warn(
+        'Failed to load node holdings metadata, using empty list:',
+        err.message
+      )
+    }
+    return []
+  }
+
+  #saveHoldingsMetadata() {
+    try {
+      const metadataPath = this.#getHoldingsMetadataPath()
+      this.#atomicWrite(metadataPath, JSON.stringify(this.#holdings, null, 2))
+    } catch (err) {
+      console.error('Failed to save node holdings metadata:', err.message)
+    }
+  }
+
   #loadTrashMetadata() {
     try {
       const metadataPath = this.#getTrashMetadataPath()
@@ -1796,14 +2444,21 @@ export class MostBoxEngine extends EventEmitter {
   }
 
   /**
-   * 等待驱动器内容从对等节点或本地可用
+   * 等待指定 Hyperdrive key 从对等节点或本地可用。
    * @param {Hyperdrive} drive - 要检查的驱动器
+   * @param {string} key - 期望的 Hyperdrive key，固定为 /<cid>
    * @param {number} timeout - 最大等待时间（毫秒）
    * @param {string} [taskId] - 用于取消的任务 ID
    * @param {object} [taskState] - 任务状态对象
-   * @returns {Promise<Array>} - 条目列表
+   * @returns {Promise<object|null>} - Hyperdrive entry
    */
-  async #waitForDriveContent(drive, timeout, taskId = null, taskState = null) {
+  async #waitForDriveEntry(
+    drive,
+    key,
+    timeout,
+    taskId = null,
+    taskState = null
+  ) {
     const startTime = Date.now()
     let pollInterval = DOWNLOAD_POLL_INTERVAL_MIN
     let lastPeerCount = 0
@@ -1811,15 +2466,12 @@ export class MostBoxEngine extends EventEmitter {
     let bootstrapNodesChecked = false
     let lastUpdateTime = 0
 
-    const localEntries = []
     try {
-      for await (const entry of drive.list()) {
-        localEntries.push(entry)
-      }
-      if (localEntries.length > 0) {
-        console.log(`[MostBox] Found ${localEntries.length} entries locally`)
-        this.emit('download:status', { taskId, status: 'syncing' })
-        return localEntries
+      const localEntry = await drive.entry(key)
+      if (localEntry) {
+        console.log(`[MostBox] Found expected entry ${key} locally`)
+        if (taskId) this.emit('download:status', { taskId, status: 'syncing' })
+        return localEntry
       }
     } catch {}
 
@@ -1853,32 +2505,32 @@ export class MostBoxEngine extends EventEmitter {
 
       await tryUpdateDrive()
 
-      const entries = []
       try {
-        for await (const entry of drive.list()) {
-          entries.push(entry)
+        const entry = await drive.entry(key)
+        if (entry) {
+          console.log(`[MostBox] Found ${key} after ${elapsed}s`)
+          if (taskId) {
+            this.emit('download:status', { taskId, status: 'syncing' })
+          }
+          return entry
         }
       } catch {}
 
-      if (entries.length > 0) {
-        console.log(
-          `[MostBox] Found ${entries.length} entries after ${elapsed}s`
-        )
-        this.emit('download:status', { taskId, status: 'syncing' })
-        return entries
-      }
-
       if (hasPeers) {
         const newStatus = 'syncing'
         if (lastStatus !== newStatus) {
-          this.emit('download:status', { taskId, status: newStatus })
+          if (taskId) {
+            this.emit('download:status', { taskId, status: newStatus })
+          }
           lastStatus = newStatus
         }
         pollInterval = Math.min(pollInterval + 200, DOWNLOAD_POLL_INTERVAL_MAX)
       } else {
         const newStatus = 'finding-peers'
         if (lastStatus !== newStatus) {
-          this.emit('download:status', { taskId, status: newStatus })
+          if (taskId) {
+            this.emit('download:status', { taskId, status: newStatus })
+          }
           lastStatus = newStatus
         }
         pollInterval = DOWNLOAD_POLL_INTERVAL_MIN
@@ -1912,36 +2564,34 @@ export class MostBoxEngine extends EventEmitter {
 
     await tryUpdateDrive()
 
-    const entries = []
     try {
-      for await (const entry of drive.list()) {
-        entries.push(entry)
+      const entry = await drive.entry(key)
+      if (entry) {
+        console.log(`[MostBox] Found ${key} on final attempt`)
+        return entry
       }
     } catch (err) {
       console.log(`[MostBox] Final attempt failed: ${err.message}`)
     }
 
-    console.log(`[MostBox] Final entry count: ${entries.length}`)
-
-    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`)
+    const peerCount = this.#swarm.connections.size
+    console.log(`[MostBox] Diagnostic information:`)
+    console.log(`[MostBox] - Expected key: ${key}`)
+    console.log(`[MostBox] - Peer count: ${peerCount}`)
+    console.log(`[MostBox] - Bootstrap nodes: ${SWARM_BOOTSTRAP.length}`)
+    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`
-        )
-      }
+    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
+    return null
   }
 }