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 层的分派逻辑。

架构

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），不依赖文件系统
`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 + 路径工具)