CherryHQ-cherry-studio/v2-refactor-temp/docs/file-manager/handler-mapping.md

FileManager Handler Mapping

⚠️ OUTDATED / SUPERSEDED（2026-04-21）

本文档的"新 IPC"列捕获的是早期设计（createEntry({origin}) 未拆分），已被后续评审推翻。关键调整：

• createEntry({origin:'internal',...}) → createInternalEntry(...)
• createEntry({origin:'external',...}) → ensureExternalEntry(...)（纯 upsert by path，无 restore 分支）
• External entry 不进入 trash 生命周期；permanentDelete 对 external 只动 DB 行

实现准绳：docs/references/file/file-manager-architecture.md、rfc-file-manager.md、file-arch-problems-response.md。

本文档保留用于 v1→v2 handler 迁移阶段的对照参考；不要据此固化新 IPC 命名。

---

v1 IPC → v2 IPC 的映射关系，以及 FileManager handler 层的分派逻辑。

相关文档：

• ipc-redesign.md — v2 IPC 接口签名与 v1 兼容性审查
• filestorage-redesign.md — v1 FileStorage ~78 个方法到 v2 架构归属

架构

FileManager 统管所有 IPC handler 注册，handler 内部按 target 类型分派：

Renderer
  → FileManager.registerIpcHandlers() (统一入口)
    ├── target: FileEntryId → FileManager 方法 (entry 协调: resolve → DB + FS)
    │     ├── ops.ts
    │     ├── FileTreeService (DB)
    │     └── FileRefService (DB)
    └── target: FilePath    → ops.ts (直接 FS/路径操作)

FileManager 的 public 方法只认 FileEntryId，纯 path 操作在 handler 层直接委托 ops.ts，不污染 public API。

Main process 其他 service 可根据实际需求直接调 ops.ts 或 FileManager，不经过 IPC。

方法分类

一、纯 Entry 操作 → FileManager

这些方法的参数永远是 FileEntryId，必须经过 FileManager 协调 DB + FS。

v2 IPC 方法	替代的 v1 IPC	备注
createEntry(params)	File_Upload, File_SaveBase64Image, File_SavePastedImage, File_Download, File_Mkdir	按 content 类型分派不同 ops 函数
batchCreateEntries(params)	File_BatchUploadMarkdown	事务包裹
trash({ id })	File_Delete, File_DeleteDir
restore({ id })	(v1 无)	需 ensureAncestors
permanentDelete({ id })	File_DeleteExternalFile, File_DeleteExternalDir	FS 删除 + DB 级联
batchTrash/Restore/PermanentDelete	(v1 无)	事务包裹
move(params)	File_Move, File_MoveDir, File_Rename, File_RenameDir	FS move + DB update
batchMove(params)	(v1 无)	事务包裹
copy(params)	File_Copy	树内复制创建新条目；导出到外部不创建

二、纯 Path 操作 → ops.ts

这些方法的参数永远是 FilePath，直接委托 ops.ts，不涉及 entry 系统。

v2 IPC 方法	替代的 v1 IPC	备注
select(options)	File_Select, File_SelectFolder	Electron dialog
save(options)	File_Save, File_SaveImage	Electron dialog + ops.write
listDirectory(dirPath, options?)	File_ListDirectory
validateNotesPath(dirPath)	File_ValidateNotesDirectory
canWrite(dirPath)	App_HasWritePermission	ops.canWrite
resolvePath(filePath)	App_ResolvePath	ops.resolvePath (path.resolve + untildify)
isPathInside(child, parent)	App_IsPathInside	ops.isPathInside
isNotEmptyDir(dirPath)	App_IsNotEmptyDir	ops.isNotEmptyDir

三、双态方法 → handler 按 target 类型分派

这些方法接受 FileEntryId | FilePath，handler 判断 target 类型后分派：

v2 IPC 方法	替代的 v1 IPC	FileEntryId →	FilePath →
read(target, options?)	File_Read, File_ReadExternal, Fs_Read, Fs_ReadText, File_Base64Image, File_BinaryImage, File_Base64File	FileManager.read	ops.read
getMetadata(target)	File_Get, File_GetPdfInfo, File_IsTextFile, File_IsDirectory	FileManager.getMetadata	ops.stat + getFileType
write(target, data)	File_Write, File_WriteWithId	FileManager.write	ops.write
open(target)	File_OpenPath, File_OpenWithRelativePath, Open_Path	FileManager.open	ops.open
showInFolder(target)	File_ShowInFolder	FileManager.showInFolder	ops.showInFolder

已移除的 v1 IPC

v1 IPC	原因
File_Open	renderer 自行组合 select + read
File_Clear	危险操作
File_CreateTempFile	→ createEntry({ parentId: 'mount_temp', ... })
File_CheckFileName	sanitize → shared 纯函数，冲突 → service 内部
File_GetDirectoryStructure	→ DataApi GET /files/entries/:id/children
File_StartWatcher/Stop/Pause/Resume	FileManager 内部管理，不暴露 IPC

不属于 File Module 的 IPC

v1 IPC	v2 归属	说明
getPathForFile	preload utils	同步方法，不经过 IPC
Open_Website	App 层	shell.openExternal(url)
Pdf_ExtractText	保持独立	纯内容处理（传 buffer），不依赖文件系统
App_Copy	数据迁移模块	userData 递归复制，专用场景
FileService_*	Provider 模块	AI Provider 远程文件 API
Gemini_*File	Provider 模块	Gemini 专用
Export_Word	Export 模块
Zip_Compress/Decompress	Backup 模块
Webview_PrintToPDF/SaveAsHTML	Webview 模块
Skill_ReadFile/ListFiles	Skill 模块

---

汇总

	v1	v2
文件相关 IPC 总数	52	22
其中纯 Entry 操作	—	9 → FileManager
其中纯 Path 操作	—	8 → ops.ts
其中双态（handler 分派）	—	5 → FileManager or ops.ts
已移除	—	10
归属其他模块	—	10
新增（v1 无）	—	7 (trash/restore/batch + 路径工具)