File Manager Migration Plan

本文档覆盖：把旧 FileMetadata / FileStorage 栈迁移到 v2 类型系统的具体执行计划。

框架：v2 把旧 FileMetadata 同时承担的两个角色（DB 行 + 通用文件描述符）显式拆分：

• 持久化角色 → FileEntry（src/shared/data/types/file/fileEntry.ts）
• 描述符角色 → FileInfo（src/shared/file/types/info.ts）
• 跨边界引用 → FileHandle（src/shared/file/types/handle.ts）

本文档以字段级退役（字段归 FileEntry / FileInfo / 彻底删除）和消费域切换（消费者按 P/I/A 桶归属分流）两条主线组织。

不在本文档范围：

• 目标设计（schema、API、架构原则）：见 rfc-file-manager.md
• FS 用法现状（main process 直接 fs 调用清单）：见 fs-usage-audit.md
• FileMetadata 消费现状（96 个文件的全量审计）：见 filemetadata-consumer-audit.md
• 架构语义：见 docs/references/file/architecture.md / file-manager-architecture.md

本文档与 RFC 的关系：RFC §10（迁移策略）和 §11（分阶段实施计划）描述数据层迁移（Dexie → SQLite 的一次性数据搬运）与总体阶段划分。本文档深入到字段级 / 消费者级的具体落地动作，是 RFC 的展开。

1. 全局结构

1.1 迁移的两条主线

这两条可以并行推进，字段退役为域切换扫清障碍（减少 shim 期的适配面积）。

1.2 FileMetadata 角色拆分与桶归属

1.2.1 叙事校正：不是"替换"，是"完成那次 refactor"

src/shared/data/types/file/file.ts:1-4 的类型注释写着：

/**
 * --------------------------------------------------------------------------
 * ⚠️ NOTICE: this type need be refactored after FileSystem is designed
 * --------------------------------------------------------------------------
 */

FileMetadata 从诞生就同时承担两种角色——DB 行（Dexie files 表、message_block.file JSON）与通用文件描述符（OCR 输入、TokenService 入参、UI 渲染字段源）。v2 并不是"用 FileEntry 替换 FileMetadata"，而是把两个角色显式拆开：

这决定了字段的归宿不是统一的"搬到 FileEntry"——需要逐字段判断它属于哪个角色（见 §2）。

1.2.2 消费者三桶划分（P / I / A）

审计（filemetadata-consumer-audit.md）按消费模式把 96 个 FileMetadata 消费者分三桶：

关键规则：

• 桶 P 消费者迁移时直接目标 FileEntry（或对只需要 id 的场合用 FileEntryId），按业务域切分 PR
• 桶 I 消费者迁移时直接目标 FileInfo，不经过 FileEntry 中间层——它们从未需要身份，shim 期也不需要适配
• 桶 A 消费者是真正的工作量：要逐个把"接口说谎"拆成两段——持久化动作显式调 createInternalEntry / ensureExternalEntry，处理动作接 FileInfo
• 升格只有一条路：FileInfo → FileEntry 必须走 FileManager 的 sanctioned 生产入口，不提供隐式 converter

1.2.3 Shim 期的 scope 限定

原先打算的"双向 shim（FileEntry ↔ FileMetadata）"被这个拆分压缩了适用范围：

• 桶 I shim：不需要——消费者从 FileMetadata 改吃 FileInfo 只是字段瘦身（丢 id / count / origin_name 这类身份字段），没有跨系统 boundary，直接改签名即可
• 桶 P shim：需要，但只在桶 P 迁移未完成的域里保留，把 v2 FileEntry 投影回旧 FileMetadata 形状给尚未迁移的持久化消费者；反向（旧 FileMetadata 读出当 FileEntry 用）仅在兼容旧 Dexie 数据窗口期需要
• 桶 A shim：不提供——A 桶必须拆签名解决，不能靠 shim 糊弄过去；否则两栖代码永远不会真正清理

See §4 for the shim function specifications.

1.3 调研依赖图

  filemetadata-consumer-audit.md  ──引用──▶  migration-plan.md
  (完整现状快照 96 files + P/I/A 桶标签)     (落地计划)
        │
        └──  每个字段 / 每个域都在 audit 里有具体 file:line
             本文档只重复"结论 + 动作"，不重复原始引用清单

对每个字段 / 域的迁移条目，先到 audit 查清楚现状，再写入本文档。写入时只保留动作相关的少量引用（具体行号），深度引用留在 audit。

2. 字段级退役计划

归宿规则（按 §1.2.1 的角色拆分）：

• 身份 / 持久化相关字段 → FileEntry（可能伴随重命名或格式变化）
• 磁盘描述符相关字段 → FileInfo
• 业务特化 / 死字段 / 本来就不该在文件对象上的字段 → 彻底删除，归到各自合适的地方（upload 调用参数、file_ref 聚合、TokenService 内部 cache 等）

本章每个字段按"属于哪个角色 / 如何退役"展开。

2.1 字段退役总览

下表给出每个旧 FileMetadata 字段的归属决策（按 §1.2.1 的角色拆分）；详细迁移方案分别展开。

图例：📋 = 调研完成且方案清晰；🔍 = 仅列点，待单独深入调研。

2.2 purpose 字段

FileMetadata.purpose?: OpenAI.FilePurpose 在旧模型里挂在"文件"上，但实际上它是一次上传调用的参数，不是文件本身的属性。v2 FileEntry 不保留此字段。

现状调研

生产方（0 个稳定 setter）：

• renderer FileManager.ts / main FileStorage.ts 创建 FileMetadata 时不写入 purpose——数据库中 99% 实例该字段为 undefined
• 唯一 setter：src/renderer/aiCore/prepareParams/fileProcessor.ts:128-132，对 qwen-long / qwen-doc 模型 spread 一个临时副本设 purpose: 'file-extract'，用完即扔，不回写 DB

消费方（2 个）：

• src/main/services/remotefile/OpenAIService.ts:35 — purpose: file.purpose || 'assistants' 传给 client.files.create
• src/renderer/aiCore/prepareParams/fileProcessor.ts:141-143 — 校验远端已上传文件的 purpose 和本地 file.purpose 是否一致（不一致抛错重传）

Schema 化石：

• src/shared/data/types/knowledge.ts:53 把 purpose 塞进 KnowledgeFileItem，但 Knowledge 业务代码 零消费

迁移目标

把 purpose 从"文件属性"改为"upload 调用参数"，符合以下两条原则：

1. FileEntry 只描述文件本身，不绑定某一次 upload 行为
2. 未来 file_upload 表记录"当初用什么 purpose 上传"，而不是文件永久持有一个模糊的 purpose

迁移步骤

执行时机

可作为独立小 PR，在 v2 文件管理重构之前或之后均可：

• 之前（推荐）：提前把 purpose 从 FileMetadata 剥离，v2 FileEntry 天然不需要为此字段做任何决策；qwen-long 的 'file-extract' 行为在 upload 调用点清晰体现
• 之后：作为 Cleanup Batch 的一部分。缺点：Batch A-E consumer migration 期间 FileEntry → FileMetadata 的适配层还要补造一个 purpose: undefined，增加噪声

PR 命名建议：refactor(file): move FilePurpose from FileMetadata to upload call sites

未来 file_upload 表对 purpose 的处理

当 AI SDK 稳定后引入 file_upload 表（见 file-manager-architecture.md §9），purpose 可作为 metadata JSON 字段的一部分记录：

{
  "file_entry_id": "...",
  "provider": "openai",
  "remote_id": "file-abc123",
  "content_version": "xxh128:...",
  "metadata": { "purpose": "file-extract" } // per-upload, not per-file
}

这样"同一文件用不同 purpose 上传到同一 provider"的场景能天然区分（甚至可以放宽 UNIQUE 约束改为 UNIQUE(file_entry_id, provider, purpose)），比旧模型单一字段准确得多。

两个消费方的 silent failure 模式

purpose 字段一旦在 v1 ↔ v2 投影层被丢弃，影响是双重静默的，外部观察不到错误：

1. OpenAIService.ts:35 — purpose: file.purpose || 'assistants'

   • file.purpose 为 undefined 时静默回退到 'assistants'
   • 调用 qwen-long / qwen-doc 的文件被当成 assistant 文件上传，OpenAI API 不会报错
   • 后果：远端解析方式与本地预期不一致，模型回答可能无声地降级

2. fileProcessor.ts:141-143 — remoteFile.purpose !== file.purpose 校验

   • file.purpose === undefined ≠ 任何非空远端 purpose → 永远 mismatch → 抛 "File purpose mismatch" 重传
   • 后果：OpenAI 文件 de-dup 缓存失效，每次对话都重新上传同一个文件，浪费配额 + 增加延迟

两条路径都是 silent failure（前者 fallback、后者重传），生产环境只会以"模型答非所问"或"API quota 异常上涨"间接显现，CI 测试很难触发。结论：在迁移步骤 #1–#6 全部落地之前，任何 v1 ↔ v2 投影层（shim、adapter、序列化器）都必须把 purpose 列入显式透传清单，不能默认依赖 schema 不变。

Phase 2 Batch 0 实施回顾（2026-05）

Batch 0 早期引入过 src/shared/file/legacy/toFileMetadata shim（FileEntry → FileMetadata 投影），按本节"迁移目标"假设 purpose 终态从 FileMetadata 剥离，直接丢弃了 purpose 与 tokens 字段。但当时 fileProcessor / OpenAIService 这些 v1 消费方尚未迁移，于是上面两条 silent failure 模式都被实际触发。

后来 renderer 侧 FileManager 的 v2 IPC cutover 整体回滚（详见 PR #15067 / 1fe5d3d34），toFileMetadata 一并删除。当前路径恢复为 v1 metadata 全链路携带 purpose，silent failure 不再可触发。

教训：

• v2 终极目标"删 purpose"不等于"过渡期可丢 purpose" —— 迁移先后顺序很关键
• 引入任何 FileEntry → FileMetadata 适配代码时，应该先核对 §2.2 现状调研里所有消费方都已迁移完毕；这次漏掉就是因为只看了一处（self-review audit 仅列 fileProcessor，漏了 OpenAIService —— 详见 PR #15067 thread PRRT_kwDOL_2xws6EeQIz）

设计修订（2026-05）：purpose 决定不属于 fileProcessor

延伸自上述 Batch 0 回顾的更深层观察 —— purpose 的赋值动作本身就不该出现在 fileProcessor 这一层：

• fileProcessor 是"AI 调用参数准备"层，它的职责是把 file metadata 组合成 LLM 请求体
• purpose 是 OpenAI Files API 的 provider-specific 概念，与 LLM 请求体本身无关
• qwen-long / qwen-doc → 'file-extract' 这种 model-name → purpose 的映射，本质是 upload service 的内部知识

把这层逻辑放在 fileProcessor 是双重越界：fileProcessor 既不该懂 OpenAI Files API 的 purpose 枚举，也不该懂 provider-specific 的 "model name 启发式映射"。把决策结果再 spread 回 file 对象（file = { ...file, purpose: ... }）则更糟，污染了 file 的语义并把 provider 细节暴露给所有下游消费者。

修订方案：purpose 决策完全收敛到 FileUploadService 内部，外部 caller 不再接触此字段：

// 修订后的 OpenAIService（concept）
async uploadFile(file: FileMetadata, context?: { model?: Model }): Promise<...> {
  const purpose = inferPurpose(context?.model)  // service 内部的 model → purpose 映射
  return this.client.files.create({ file: /* read stream */, purpose })
}

// 修订后的 fileProcessor（concept）
await window.api.fileService.upload(provider, file, { model })  // 不再 spread purpose

如果 caller 确实需要覆盖 service 的默认决策（极少数情况），可以暴露显式 options.purpose 作为 escape hatch —— 但这是逃生舱，不应当作主路径。

对前述"迁移步骤"的影响

§2.2 "迁移步骤" 表中的步骤 #1 / #2 / #4 应改为：

步骤 #3 / #5 / #6 不变。原则一句话概括：fileProcessor 看不到 purpose，service 内部黑盒处理。

2.3 count 字段

决策：

v2 不持久化 count。file_entry 表无 count 列；引用计数由 DataApi 专用端点 GET /files/entries/ref-counts?entryIds=... 按需聚合 file_ref 表得出。没有缓存，没有双写，没有 trigger——每次查询都是一次纯 SQL 聚合，固定 shape，不再使用 opt-in 参数。

定性：引用计数 → file_ref 表。旧 count 是"这个文件被多少个业务对象引用"的 Dexie-level 数字；v2 由 file_ref 表的 COUNT(*) WHERE fileEntryId = ? 取代，完全按需计算。

2.3.1 数据面

Dexie schema（src/renderer/databases/index.ts:45,49,55,62,71,80,92,105,117,128）：

files: 'id, name, origin_name, path, size, ext, type, created_at, count'

v1-v10 每个版本都把 count 列为索引字段（用于 orderBy('count')）。

初始化值：文件创建时写入 count: 1。所有 setter：

2.3.2 Increment（count++）路径

所有 count++ 都走 renderer 的两条路径：

2.3.3 Decrement（count--）路径

2.3.4 关键调用方（decrement 路径）

以下业务在业务对象被删除时清理 file 引用，全部走 force=false（= 走 count decrement）：

2.3.5 物理删除路径（force=true，绕过 count）

src/renderer/services/FileAction.ts:45-94 (handleDelete) 是 FilesPage 删除按钮的后端。流程：

1. FileManager.deleteFile(fileId, true) — 不看 count，直接物理删
2. db.message_blocks.where('file.id').equals(fileId).toArray() — 手动扫关联 blocks
3. 遍历 topics 重建 messages[].blocks[] 去除引用
4. db.message_blocks.bulkDelete(blockIdsToDelete)

这条路径绕开了 count 机制，揭示旧架构没有真正的引用完整性保证——count 只是个启发式数字，真正的引用扫描发生在 UI 删除按钮里。

2.3.6 UI 消费

2.3.7 Migration 侧的残留

src/main/data/migration/v2/migrators/mappings/KnowledgeMappings.ts:103 的 hasCompleteFileMetadata 校验要求 typeof value.count === 'number'。Knowledge 迁移完成后，KnowledgeItemData.file 仍以 FileMetadataSchema 形状存入 SQLite（详见 audit §5 和 RFC §10.6 前言），所以 count 作为 JSON 字段会在 SQLite knowledge_item.data 中化石化保留。

2.3.8 v2 映射

count 不进入 fileEntryTable（src/main/data/db/schemas/file.ts 已确认无此列）。

v2 对应查询：

-- 旧 file.count
SELECT COUNT(*) FROM file_ref WHERE file_entry_id = ?

-- 旧 orderBy('count')
SELECT fe.*, (SELECT COUNT(*) FROM file_ref fr WHERE fr.file_entry_id = fe.id) AS ref_count
FROM file_entry fe
ORDER BY ref_count DESC

2.3.9 迁移步骤

Step A: FileMigrator 填充 file_ref（RFC §10.1-10.3 范围内）

迁移器扫描 Dexie 每个文件的所有引用源并写入 file_ref：

注意：v2 message 迁移把 blocks 从表移入 data.blocks JSON，所以 post-migration 不能再用 Dexie-style where('file.id') 扫——必须在迁移期扫完写入 file_ref，之后只能靠 sourceId='<messageId>' 反查。

未决点（见 §6 Q7）：paintings 可能不参与本轮迁移（RFC §10.4 标注"不在本次范围内"），因此 paintings 对应的 file_ref 缺失直到 PaintingMigrator 单独上线。Phase 1 通过类型层规避了误删风险：'painting' 不在 FileRefSourceType union 内，OrphanRefScanner 根本不会枚举到这个 sourceType；任何在迁移窗口期意外写入的 sourceType='painting' 行也会在 FileRefSchema.parse 当场失败。PaintingMigrator 上线时按"三件套"原子加入：allSourceTypes 追加 paintingSourceType + 新增 createRefSchema variant + 在 FileRefCheckerRegistry 注册 SourceTypeChecker——Record<FileRefSourceType, …> 的编译期穷举确保 checker 缺失会直接 TS 报错。Notes 域同理：NoteMigrator 上线时按同样三件套加入。

Step B: Renderer 消费改造

按依赖顺序：

Step C: Schema 清理

2.3.10 语义变化（需要产品确认）

旧语义：FileManager.deleteFile(id, force=false) 在 count === 1 时立刻物理删除文件。

v2 两种选择：

• 选项 1（立即清理）：当 file_ref 最后一行被删时，trigger FileManager 立即 permanentDelete(fileEntryId)。需要数据库 trigger 或业务层额外一步
• 选项 2（延迟清理，推荐）：OrphanRefScanner 定期扫描 zero-ref 文件做清理。UX 变化：刚解除最后一个引用后，文件不会立刻消失（但也不再占业务列表）

推荐选项 2，理由：

• 删除操作原子性：业务侧只管 file_ref，不需要跨表 trigger
• 抗误删：短时间内重新引用该文件不会 fail（比如 "undo" 删除一条 message 时）
• 与 internal deletedAt 软删的哲学一致（延迟、可逆）；external 虽然没有软删状态，但延迟 orphan 清理仍然提供"重新引用不失败"的好处

2.3.11 UI 变化

FilesPage 当前"按 count 排序"提供的价值是"热门文件置顶"。v2 走 DataApi 专用端点 /files/entries/ref-counts（纯 SQL 聚合，固定 shape）+ 渲染层组合：

// 1. 拉列表（纯 SQL，无副作用）
const { data: entries } = useQuery(fileApi.listEntries, { origin: 'internal' })
const entryIds = entries?.map((e) => e.id) ?? []

// 2. 并行拉 refCount（DataApi 专用端点）与 dangling（File IPC，FS 副作用走 IPC）
const { data: refCounts } = useQuery(fileApi.refCounts, { entryIds })
const { data: presence } = useQuery(
  ['fileManager.batchGetDanglingStates', entryIds],
  () => window.api.fileManager.batchGetDanglingStates(entryIds),
  { enabled: entryIds.length > 0 }
)

// 3. renderer 合并后按 refCount 排序
const sorted = entries
  ?.map((e) => ({ ...e, refCount: refCounts?.[e.id] ?? 0, dangling: presence?.[e.id] }))
  .sort((a, b) => b.refCount - a.refCount)

DataApi 边界收紧为纯 SQL + 固定 shape：aggregation 走专用端点（依然是 DataApi），FS 副作用（DanglingCache + 冷路径 fs.stat）一律走 File IPC。消费者两次 useQuery 并行组合，成本对调用点显式可见。

FileList 的 "$N 引用" 展示：保留此信息对用户有价值（知道哪些文件是被大量复用的），同样走 /files/entries/ref-counts 端点。

建议：FilesPage 默认同时发起列表 + refCount 两个 query，保留现有排序 UX；dangling 由独立 IPC 查询提供失效标记。冷启动首次 list 的 dangling 冷查可能有 N 次 stat（Promise.all 并行通常 <100ms）——调用点把这个成本明示给开发者，避免隐藏的 IO 副作用。

2.3.12 执行时机

此字段迁移强绑定域级迁移，不能独立小 PR 完成（不像 purpose）：

• B1-B6 需要 file_ref 表 + FileManager + fileRefService 都就绪（Phase 2 尾部）
• B7-B8 依赖 Messages 域迁移（Batch E）完成——因为 FileAction.handleDelete 手动扫 message_blocks 的逻辑在 Batch E 中会被重写
• C1-C4 在 Cleanup Batch

因此 count 字段的完整退役贯穿 Phase 2 到 Cleanup Batch，无独立时间点。

2.3.13 风险

2.4 tokens? 字段

结论：这是一个100% 死字段——从未写入、从未读取。直接删除，零功能影响。

2.4.1 现状

生产方：0 个

• src/main/services/FileStorage.ts 所有 setter 都不写 tokens
• src/renderer/services/FileManager.ts 的 addFile / uploadFile / addBase64File 都不写
• src/main/utils/file.ts 不写
• 任何 MistralPreprocessProvider / VideoPopup / KnowledgeFiles.tsx 的字面量构造都没有 tokens: 赋值

消费方：0 个

• src/renderer/services/TokenService.ts 的 estimateImageTokens(file) 用的是 file.size / 100，不读 file.tokens
• estimateTextTokens(text) 直接从文本内容算（tokenx lib），不碰 FileMetadata
• UI 没有任何位置展示 file.tokens
• 业务逻辑没有任何地方读 file.tokens

Dexie schema：src/renderer/databases/index.ts v1-v10 的 files: 'id, name, origin_name, path, size, ext, type, created_at, count' 没有 tokens 索引

Migration 校验：KnowledgeMappings.hasCompleteFileMetadata 不检查 tokens（可选字段，不参与 completeness 判断）

Schema 化石：

• src/shared/data/types/file/file.ts:27 — tokens?: number
• src/renderer/types/file.ts:123 — tokens?: number
• src/shared/data/types/knowledge.ts:52 — tokens: z.number().optional() 在 FileMetadataSchema 里

2.4.2 迁移目标

v2 FileEntry 不保留此字段。token 估算是 TokenService 的职责（消息构造期临时计算），不是文件的属性——这和 purpose 同样的设计原则。

2.4.3 迁移步骤

独立小 PR，纯删除：

完。 无 adapter 改动，无 UI 改动，无业务逻辑改动。

2.4.4 未来是否需要缓存 token 估算

不需要在 FileEntry 上挂字段。如果未来 TokenService 发现 estimateTextTokens 对大文件开销大，可以：

• 内存缓存：Map<contentHash, number> — content hash 作为 key（已经由 ops.contentHash 提供），避免相同内容重复算
• 持久化缓存（如需）：独立小表 token_estimate_cache，和 FileEntry 表解耦

这不是 Phase 1 范围。先删掉现有 schema 上的死字段，有需要再按实际 profiling 数据加缓存。

2.4.5 执行时机

独立 PR，随时可做。建议和 purpose 字段退役一起打包：refactor(file): drop unused FileMetadata.tokens and .purpose fields（2-3 个文件改动，纯删）。

2.4.6 风险

几乎零风险。唯一可能的"惊喜"是外部消费方（非主项目代码）读了这个字段——但本仓的 FileMetadata 不作为公开 API 导出，所以这不是问题。

2.5 type: FileType 字段

定性：type: 'image' | 'video' | 'audio' | 'text' | 'document' | 'other' 从持久化字段变为动态推导。主路径：getFileType(ext) 按扩展名映射；冷路径：isTextFile(path) buffer 探测升级 OTHER → TEXT。

2.5.1 现状

生产方（FileStorage 的核心逻辑）：

src/main/services/FileStorage.ts:237-242 —— 双层推导：

public getFileType = async (filePath: string): Promise<FileType> => {
  const ext = path.extname(filePath)
  const fileType = getFileTypeByExt(ext)
  return fileType === FILE_TYPE.OTHER && (await this._isTextFile(filePath))
    ? FILE_TYPE.TEXT
    : fileType
}

• Ext 派生：src/main/utils/file.ts:106 getFileType(ext) → 查 fileTypeMap（纯函数）。映射表见 file.ts:20-28 的 imageExts / videoExts / audioExts / textExts / documentExts
• Buffer 升级：FileStorage._isTextFile(filePath) 用 chardet + isbinaryfile 探测（FS 副作用，读文件头 sample）。仅在 ext 归 OTHER 时触发，把"未知扩展名但内容是文本"的文件升级为 TEXT

所有 FileMetadata setter 同时写 type（连同 count: 1 等字段一起构造）：

• FileStorage.ts:227, 273, 340, 365, 705, 755, 1552 —— 各上传 / 保存入口
• src/main/utils/file.ts:136-145 —— getAllFiles 目录扫描（getFileType(ext) 派生，无 buffer 升级）
• src/renderer/components/Popups/VideoPopup.tsx:110 —— 字面量硬编码 VIDEO
• src/renderer/pages/knowledge/items/KnowledgeFiles.tsx:113 —— 字面量构造
• src/main/knowledge/preprocess/MistralPreprocessProvider.ts:185 —— 预处理产物构造

Dexie schema：files: 'id, name, origin_name, path, size, ext, type, created_at, count' —— type 是索引字段，支持 .where('type').equals(...) 查询

v2 占位：src/main/file/ops/metadata.ts 已经保留 getFileType(path) / isTextFile(path) / mimeToExt(mime) 三个函数签名，目前 throw new Error('Not implemented')

2.5.2 消费方（32 个文件，按类别）

A. Dexie SQL query（1 个关键点，必须迁移）：

B. UI 分派 by type（大量，按 type 分支）：

C. 类型守卫：

• src/renderer/types/file.ts:140 isImageFileMetadata(file) => file.type === FILE_TYPE.IMAGE

D. Dexie upgrade migrator：

• src/renderer/databases/upgrades.ts:188 —— 历史 Dexie 升级脚本用 file.type === IMAGE

E. Migration 校验：

• KnowledgeMappings.hasCompleteFileMetadata 要求 typeof value.type === 'string'

2.5.3 v2 映射

v2 FileEntry schema 已经没有 type 列（src/main/data/db/schemas/file.ts 确认）。迁移方案：

Ext 派生（默认路径）：

• getFileType(ext) 逻辑从 src/main/utils/file.ts 搬到 src/shared/file/types/ 或类似 shared 位置，renderer 和 main 都可用
• src/main/file/ops/metadata.ts 的 getFileType(path) 实现：从 path 提取 ext → 调 shared 的 getFileType(ext)
• 零 FS IO

Buffer 升级（保留但收窄）：

• src/main/file/ops/metadata.ts 的 isTextFile(path) 实现：复用 chardet + isbinaryfile 逻辑
• 只在 FileManager.getMetadata(handle) 时触发——打开文件 / 预览 / 处理路径上；list 查询不触发
• 旧 FileStorage 在创建时做 buffer 升级；v2 在读取时做。语义微调：文件的 type 不再是"持久化属性"而是"每次 getMetadata 现算的派生"

2.5.4 DataApi 的 type filter（无 includeType opt-in）

FilesPage 的 where('type').equals(...) 必须有 DataApi 对应：

方案：DataApi query 仅支持 type 过滤（纯 SQL WHERE ext IN (...)，作为请求参数；不是 opt-in 输出字段）。不引入 includeType 等派生输出字段——DataApi 边界收紧为纯 SQL + 固定 shape，派生 type 由 renderer 端通过共享的 getFileType(ext) 纯函数现算：

// DataApi handler（概念代码，纯 SQL）
async function listEntries(query) {
  const extFilter = query.type ? extsOf(query.type) : null
  return db
    .select()
    .from(fileEntry)
    .where(extFilter ? inArray(fileEntry.ext, extFilter) : undefined)
}

// Renderer 侧用共享工具计算 type（纯函数，无 IO）
import { getFileType } from '@shared/file/types/fileType'
const type = getFileType(entry.ext)

DataApi schema 改动：

'/files/entries': {
  GET: {
    query: {
      ...
      type?: FileType              // 按 type 过滤（handler 转成 ext 枚举）
      sortBy?: ... | 'type'         // 可选：按 type 排序（字母序，SQL ORDER BY ext 等价近似）
    }
  }
}

优点：

• 遵守新的 DataApi 纯 SQL + 固定 shape 边界——不引入 opt-in 派生输出
• getFileType(ext) 本身是共享纯函数，renderer 端零成本调用
• 不需要物化派生列，不需要 SQLite generated column 特性

代价：

• list 查询拿不到 buffer-upgraded TEXT（OTHER 的自定义文本扩展名仍显示为 OTHER）
• 用户体验微降：某些历史 .log/.ini 类文件若无 ext 派生规则覆盖，列表里是 OTHER。用户实际使用（打开、send to chat）时 File IPC getMetadata 会给出正确 TEXT

2.5.5 迁移步骤

Step A: shared getFileType 提取（独立小 PR）

Step B: DataApi 加 type 支持

Step C: FileManager IPC getMetadata 升级

Step D: 消费者改造（30+ 文件）

按子系统分批：

Step E: Producer 改造（停止写入 type）

Step F: Schema 清理

2.5.6 Buffer 升级的未决点

旧 _isTextFile 在创建时触发 upgrade；v2 改为 getMetadata 在读取时触发。这个语义变更的影响：

建议：

• 确认 textExts 列表足够覆盖常见文本扩展名（目前 .txt/.md/.html/.json/.js/.ts/.css/.py 等）
• 在扩展名表里补充 .log、.ini、.cfg、.yaml、.yml、.toml 等"配置/日志"类常见文本
• 剩余罕见 ext 接受 list 显示 OTHER 的降级，打开时 getMetadata 升级

2.5.7 复杂度与执行时机

建议拆分：

• PR1: Step A shared getFileType + ops.getFileType + ops.isTextFile 实现（独立基础设施）
• PR2: Step B DataApi type / includeType（独立 API 扩展）
• PR3: Step C getMetadata buffer 升级（独立 IPC 扩展）
• PR4-PR9: Step D 消费者迁移（按子系统 D1-D7 分 PR）
• PR10: Step E + F cleanup

2.5.8 风险

2.5.9 执行时机

大部分改动需要 v2 FileManager / DataApi 基础设施就绪。基础 PR（A/B/C）可以在 Phase 2 完成，消费者迁移（D）贯穿 Batch A-E，Schema 清理（F）在 Cleanup Batch。

2.6 path 字段

定性：path 是最深的单一依赖。但调研显示旧架构里 path 事实上已经是派生字段——DB 里的 path 列在每次读取时被覆盖，真实 SoT 是 id + ext + userData 的运行时拼接。v2 只需要把"约定式派生"变成"显式 API 派生"。

2.6.1 现状的意外发现

src/renderer/services/FileManager.ts:80-89 的 getFile(id)：

static async getFile(id: string): Promise<FileMetadata | undefined> {
  const file = await db.files.get(id)
  if (file) {
    const filesPath = cacheService.get('app.path.files') ?? ''
    file.path = filesPath + '/' + file.id + file.ext   // 🔑 读出来就覆盖
  }
  return file
}

Dexie files 表虽然有 path 列（'id, name, origin_name, path, size, ext, type, created_at, count'），但每次读出来 renderer 都覆盖为运行时计算值。也就是：

• 存储的 path 是死数据（旧值不会被消费，除非绕过 getFile 直接 db.files.get）
• 真正的 path 计算永远是：{userData/files}/{id}{ext}（internal）
• FileManager.getFilePath(file) 和 FileManager.getSafePath(file) 在此基础上各自包装

所以迁移不是"引入 path resolution"，而是"把隐式约定变成显式 API"——v2 FileEntry 不存 path 列（src/main/data/db/schemas/file.ts 已确认），消费者显式通过 helper / IPC 拿 path。

2.6.2 两层访问器

getSafePath 的危险文件防护必须在 v2 保留——否则 `` 可能导致用户通过预览触发 shell 脚本。

2.6.3 消费方分类（~20 个文件）

C1. file:// URL 用于 UI 展示（3 个，高频）：

这些都是同步拿 file:// URL 渲染 ``。不能改成 async IPC（大列表下 async 会产生大量 waterfall 延迟）。

C2. 系统级 open / reveal（3 个）：

可以改为 FileManager.open(handle) IPC（已在 src/shared/file/types/ipc.ts 定义）。

C3. FS 内容读取（4 个）：

可以改为 FileManager.read(handle) 或 FileManager.getMetadata(handle)（已定义）。

C4. 系统路径 interop（2 个）：

C4 的 AgentSessionInputbar 是真的需要 FileMetadata.path，因为 agent 的上下文里要让 LLM 看到本地路径。

C5. Path 派生信息（可直接用 ext）：

C6. OCR / 第三方库（main 侧）（5 个）：

第三方 OCR 库只能接受路径参数——这是 FileManager.withTempCopy(handle, fn) 的经典场景（已在 IPC 定义）。

C7. Main 侧 knowledge readers（3 个）：

Main 侧消费者可以直接用 main 的 resolvePhysicalPath(entry)（src/main/services/file/utils/pathResolver.ts），无需 IPC。

2.6.4 v2 映射策略

不引入新 IPC。现有 File IPC 已经覆盖所有需求：

2.6.5 Path resolution 通过 File IPC + 共享格式化 util 统一提供

原则：Renderer 不知道内部存储布局（{id}.{ext} 拼接方式、userData 路径）。所有 path 来源归到 main 的 resolvePhysicalPath(entry)，通过 File IPC 专用方法暴露给 renderer——不走 DataApi，因为 DataApi 边界收紧为纯 SQL + 固定 shape，任何 main-side 计算（resolver 调用）都算越界。

一对 File IPC + 一组共享格式化工具覆盖所有 renderer 需要 path / URL 的场景：

File IPC 接口（src/shared/file/types/ipc.ts K 段）：

interface FileIpcApi {
  // ...
  getPhysicalPath(params: { id: FileEntryId }): Promise<FilePath>
  batchGetPhysicalPaths(params: { ids: FileEntryId[] }): Promise<Record<FileEntryId, FilePath>>
  // 注：不再有 getSafeUrl / batchGetSafeUrls —— 参见下方"为什么 URL 不走 IPC"
}

共享 URL 工具（src/shared/file/urlUtil.ts，纯函数，main + renderer 共用）：

export function isDangerExt(ext: string | null): boolean         // 危险扩展名策略
export function toFileUrl(path: FilePath): FileURLString         // 跨平台 file:// 编码
export function toSafeFileUrl(path: FilePath, ext: string | null): FileURLString
  // = isDangerExt(ext) ? toFileUrl(dirname(path)) : toFileUrl(path)

Handler 实现（只剩 getPhysicalPath）：

// main 侧处理：每个 id 经过统一路径解析
async function batchGetPhysicalPaths(ids: FileEntryId[]) {
  const entries = await fileEntryService.batchGetById(ids)
  return Object.fromEntries(entries.map((e) => [e.id, resolvePhysicalPath(e)] as const))
}

Main 侧基础函数（保留不变）：

// src/main/services/file/utils/pathResolver.ts (existing)
export function resolvePhysicalPath(entry): string { ... }  // 绝对路径（authority 源头）

为什么 URL 不走 IPC：file:// URL 是对已有 path 做纯字符串格式化 + 危险扩展名的策略判断。两者都可以放在共享包里作为纯函数暴露：

1. Authority 仍在 main —— resolvePhysicalPath 定义"id + ext 如何拼接、userData 在哪、是否 hash-bucket"
2. Formatting 是 locality —— toFileUrl / toSafeFileUrl 只接受一个已经由 main 权威产出的 path string，不产生新的 authority。同一份 util 在 main / renderer 都能调，无需来回打桩

这样比跨 IPC 暴露 getSafeUrl 更薄、表面更小，且 main 将来也能直接 toSafeFileUrl(path, ext) 给 webContents.loadURL 用，不需要再复制一份逻辑。

为什么 path 还要走 IPC（不纯函数）：因为 path resolution 依赖 userData 位置 + 未来可能的 hash-bucket 等存储布局决策——那是 authority，必须留在 main。Renderer 拿到 path 后做的 URL 包装才是 formatting，可以下放。

为什么走 File IPC 而不是 DataApi 的 opt-in 字段：

旧设计曾用 DataApi includePath / includeUrl opt-in 字段统一暴露，理由是"和 refCount / dangling 对称，一次 query 拿齐"。但这把主进程计算（resolvePhysicalPath）藏到 DataApi handler 里，违反了 DataApi 严格的纯 SQL 交接边界——DataApi 必须只做 SQL，任何 main-side 副作用（FS stat、resolver 调用、in-memory cache 查询）一律走 File IPC。

新设计把 path 查询搬到 File IPC 的专用批量方法，URL 格式化放到共享纯函数：

• Renderer 两步组合：先 DataApi 拉固定 shape 的 entry 列表，再 File IPC 批量拿 path；需要 URL 就在进程内 toSafeFileUrl 合成
• 每一步 cost 在调用点显式可见（IPC 数量减半 + formatting 无成本）
• DataApi 响应 shape 保持固定，缓存行为可预测

收益（相比 renderer 拼路径 + 旧 DataApi opt-in + 早期 IPC 双方法三套方案）：

Renderer helper 方案、DataApi opt-in 方案、IPC 双方法方案皆已作废。

2.6.6 迁移步骤

Step A: Path resolution 基础设施（独立 PR）

Step B: C1 显示 URL 迁移

所有 C1 消费者组合两个 useQuery：DataApi 拉 entry 列表（固定 shape，带 ext）+ File IPC batchGetPhysicalPaths 批量拿 path。URL 由共享纯函数 toSafeFileUrl(path, ext) 就地合成——零额外 IPC。重复使用场景建议包一个 useEntriesWithUrl(ids) hook。

Step C: C2 open/reveal 迁移

Step D: C3 FS 内容读取迁移

Step E: C4 Agent 上下文

Step F: C5 Path 派生消除

Step G: C6 OCR 第三方库迁移（main 侧）

Step H: C7 Main 侧 knowledge readers

Step I: Legacy accessor 移除

2.6.7 readExternal 语义（已统一到 read）

window.api.file.readExternal(path, asText) 是旧 API。v2 统一到 FileIpcApi.read(handle)，不保留别名：

• 旧 readExternal(path, true) → read({ kind: 'path', path }, { encoding: 'text' })
• 上下文已经是 FileEntry 时：read({ kind: 'entry', entryId }, ...)

所有调用方必须替换（不存在过渡兼容层）。

2.6.8 Agent 的批量 path 查询

C4 的 AgentSessionInputbar.tsx:395 当前是 files.map(f => f.path).join('\n')——多个文件路径一次拿到。

v2 走 File IPC 专用批量方法 batchGetPhysicalPaths（不走 DataApi——main-side resolver 调用是 DataApi 禁区）：

const { data: paths } = useQuery(
  ['fileManager.batchGetPhysicalPaths', selectedFileIds],
  () => window.api.fileManager.batchGetPhysicalPaths(selectedFileIds),
  { enabled: selectedFileIds.length > 0 }
)
const filePaths = selectedFileIds.map((id) => paths?.[id]).filter(Boolean).join('\n')

IPC 批量方法内部 Promise.all 一次 RT 完成——效率等同旧方案，但成本明确落在独立的 useQuery 上，不隐藏在列表 query 的 opt-in flag 里。

2.6.9 关键风险

2.6.10 复杂度与执行时机

建议拆分 8-10 个 PR（Step A-I 各一）：

• Step A（helper）和 Step B-F（renderer 消费者）可 Phase 2 起步
• Step G-H（main 侧）依赖 FileManager 实现就绪
• Step I（legacy 清理）Cleanup Batch

2.6.11 关键决策记录

Q1: readExternal 的 IPC 别名 ✅ 已决定

统一到 read(handle)，不保留 readExternal 别名。FileHandle 自身区分 entry 与 path 两种引用形态，旧 readExternal(path, text) 相当于 read({ kind: 'path', path }, { encoding: 'text' })。

影响：Step D 所有 readExternal 调用必须替换（不能留过渡别名），配套 readText / isTextFile 等旧 IPC 也走 read / getMetadata。

Q2: 哪些消费路径真的需要路径字符串？

对前述 C1–C7 逐个审查，只有2 个 renderer 类别真的需要路径：

结论：只有 C1 和 C4 两个 renderer 场景真的需要路径字符串。其中：

• C1 必须同步（image render 路径频繁，不能 async）
• C4 低频（一次消息构造），async IPC 也可以；但如果 C1 已经要做同步 helper，C4 顺带复用即可

这意味着 renderer 侧的 path helper 是必要但最小的：仅为这两个场景存在，不做其他扩展。

Q3: 历史 message block 里内嵌 FileMetadata 的兼容方式 ✅ 已决定（终态；落地分两步）

终态：历史 message blocks 的 file: FileMetadata 字段在 v2 消息模型里不再内嵌文件对象，而是通过 file_ref 表建立关系（sourceType='chat_message', sourceId=messageId, fileEntryId=..., role='attachment' | 'image'）。

落地拆分：

• ✅ Batch 0 已落地：v2 message block JSON 只存 fileEntryId: string（ImageBlock.fileId / FileBlock.fileId），渲染时通过 id 查 FileEntry；ChatMigrator 已透传 v1 block.file.id → v2 fileId。不需要 shim 反推 path——block JSON 里连 path 都没了。
• ⏳ 延后：file_ref 反向索引行的写入随 chat 域整体迁移到 v2 file_ref 服务时一并上线（同步注册 'chat_message' sourceType；见 §2.10.3 表格里 ChatMigrator 行的延后说明）。延后期间，附件可达性由 inline fileId 维持，仅 file_ref 反查能力暂缺。

这条和 §2.3（count 用 file_ref 取代）+ RFC §8.4 ChatMigrator 延后说明一致。

Q4: Path 暴露到 renderer 的方式 ✅ 已决定（经架构师复核后收紧）

统一通过 File IPC 专用批量方法——renderer 不知道内部存储布局，main 作为 path 的唯一来源。

• getPhysicalPath / batchGetPhysicalPaths → 原始绝对路径（agent / drag-drop / subprocess）
• 共享纯函数 toSafeFileUrl(path, ext)（@shared/file/urlUtil）→ file:// URL + 危险文件 safety wrap（`` / <video src>），就地合成，无独立 IPC

为什么不再走 DataApi opt-in：DataApi 被严格收紧为纯 SQL + 固定 shape 响应，任何 main-side 副作用（resolver 调用、FS stat、in-memory cache 查询）都必须走 File IPC。让 DataApi handler 调 resolvePhysicalPath 会把 main-side 计算藏到"只读 SQL 接口"里，破坏边界——consumer 无法从端点签名判断这次调用有没有隐性 IO。

已作废的设计：

• Renderer-side entryToFileUrl / entryToAbsolutePath helper（暴露存储布局给 renderer）
• DataApi includePath / includeUrl opt-in 字段（把 main-side 计算混入 SQL 接口）

收益：

• DataApi 边界纪律明确：看到 DataApi 端点 = 纯 SQL，看到 File IPC 调用 = 可能有副作用
• Renderer 调用成本可见：每次要 path / url 就写一个独立的 useQuery，藏不住
• Batch 效率等同旧方案（IPC 内部 Promise.all）
• Main 改存储格式（subdir sharding 等）仍然不影响 renderer
• 危险文件 safety 集中在 main
• Null byte 检查自然包含

2.7 name / origin_name 字段

定性：两个字段语义完全不同，需要分别处理。

2.7.1 name（存储名）现状

Producer（FileStorage 统一构造）：所有 FileStorage.ts 的 setter 里 name: uuid + ext 或 path.basename(...) 模式，统一是"id + ext"形态。由 createInternalEntry / ensureExternalEntry 返回给 renderer。

Renderer 中的真实消费者：

注意：很多 file.name 实际是 Electron 扩展的 browser File 对象 .name（非 FileMetadata）：PasteService.ts:72-73, useRichEditor.ts:493, ObsidianExportDialog.tsx:112, VideoPopup.tsx:98-109, NotesService.ts:321（Dirent）等。这些和本次迁移无关。

2.7.2 origin_name（用户可见原名）现状

Producer：

Consumer：

Dexie schema: files: 'id, name, origin_name, path, size, ext, type, created_at, count'——两个都是 indexed column。

Migration 校验: KnowledgeMappings.hasCompleteFileMetadata 要求 typeof value.origin_name === 'string'。

2.7.3 v2 FileEntry 的新字段语义

// src/shared/data/types/file/fileEntry.ts (already set up)
interface FileEntry {
  id: string; // UUID v7
  origin: "internal" | "external";
  name: string; // 用户可见名字，**不含扩展名**（'My Document'）
  ext: string | null; // 扩展名，**不含前导点**（'pdf'），无扩展名时 null
  size: number;
  externalPath: string | null;
  // deletedAt 仅 internal 可非空；external 恒为 null（fe_external_no_delete CHECK）
  deletedAt: number | null;
  createdAt: number;
  updatedAt: number;
}

语义变化：

• name 语义完全改变：从"存储名（id+ext）"变为"用户可见名（不含扩展名）"
• ext 语义微调：从"含前导点的扩展名（.pdf）"变为"不含前导点（pdf）"——见 §2.5 type 字段的 ext 变化
• 派生的完整显示名 = name + (ext ? '.' + ext : '')

2.7.4 派生工具

增加一个集中式工具（shared 或 renderer 均可，逻辑纯函数）：

// src/shared/file/utils/displayName.ts（新）
export function entryDisplayName(entry: FileEntry): string {
  return entry.ext ? `${entry.name}.${entry.ext}` : entry.name;
}

所有旧消费 file.origin_name 的位置改为 entryDisplayName(entry)。

2.7.5 迁移步骤

Step A: entryDisplayName 工具（独立 PR）

Step B: Producer 改造（设值方）

Step C: Consumer 改造 —— 存储名使用点

Step D: Consumer 改造 —— 原名使用点

Step E: Schema / 迁移

2.7.6 ext 的前导点问题（关联 §2.5）

旧 FileMetadata.ext = '.pdf'（含前导点）；v2 FileEntry.ext = 'pdf'（不含）。

所有做字符串比较的消费者要更新：

• file.ext === '.pdf' → entry.ext === 'pdf'
• file.ext.replace('.', '') 之类的 hacky 写法可以删除
• Producer 停止写前导点（path.extname() 返回 .pdf，需要 .slice(1) 或 .replace(/^\./, '')）

这个和 §2.5 type 字段迁移同步进行，可以合并到一个 PR 里。

2.7.7 FileMigrator 的字段拆分逻辑

Dexie origin_name: 'My Doc.pdf' + ext: '.pdf' → v2:

const oldExt = oldFile.ext.startsWith('.') ? oldFile.ext.slice(1) : oldFile.ext
const oldOriginName = oldFile.origin_name
const newName = oldExt && oldOriginName.endsWith('.' + oldExt)
  ? oldOriginName.slice(0, -(oldExt.length + 1))
  : oldOriginName
const newExt = oldExt || null

newFileEntry = {
  ...
  name: newName,  // 'My Doc'
  ext: newExt,    // 'pdf'
}

注意：旧 origin_name 不一定真的包含 ext（可能是 bug 或用户手动改过），做防御性处理。

2.7.8 Rename 行为的语义变化

旧：updateFile({ ...file, origin_name: newName }) 更新含扩展名的原名。用户输入 'My New Doc.pdf' 整个被保存。

v2：rename popup 只编辑 name，ext 不变。用户看到输入框里是 'My New Doc'（无扩展名），保存后 entry.name = 'My New Doc'，ext='pdf' 保留。

UX 注意：

• Rename popup 的输入框 placeholder / tip 应该提示"不含扩展名"
• 对于 internal 文件：保存 name 只是 DB 更新，物理文件路径（{id}.{ext}）不变
• 对于 external 文件：物理 rename 需要重新组合 {newName}.{ext}，rename externalPath

这个逻辑在 §2.6 Step I 的 FileManager rename 实现里体现。

2.7.9 复杂度与执行时机

建议拆分：

• PR1: Step A（工具）
• PR2: Step E4 + E5（FileMigrator 映射 + schema 校验）—— 迁移基础设施
• PR3-PR5: Step B（Producer）分 main 侧 / 预处理 / renderer 字面量三个 PR
• PR6-PR9: Step D consumer 按子系统分 PR（FileAction / TokenService / Remote upload / aiCore & RichEditor 等）
• PR10: Step E1-E3 cleanup schema

2.7.10 风险

2.8 created_at: string 字段

结论：低复杂度。ISO 8601 string → FileEntry.createdAt: number（ms epoch）。所有消费者已经通过 dayjs 读取，dayjs() 同时接受 string 和 number，所以消费侧改动极小，主要是 Producer 改写 setter 和 Migrator 做一次类型转换。

2.8.1 现状

v2 目标 schema：FileEntry.createdAt: number（ms epoch），和其他 v2 表一致（见 src/main/data/db/schemas/file.ts）。

Producer（写 ISO string 的位置，通过 .toISOString() / birthtime.toISOString()）：

Consumer（通过 dayjs 读）：

关键事实：dayjs(x) 同时接受 string (ISO) 和 number (ms epoch)。v2 切换为 number 后，所有 dayjs 消费者代码不变就能工作。

Dexie upgrades（历史修复脚本）：

• src/renderer/databases/upgrades.ts:48-49 — 历史 bug 修复：若 created_at instanceof Date，转成 toISOString()。v2 迁移后 Dexie 不再使用，保留原状即可（不执行）。

Migration 校验：

• KnowledgeMappings.hasCompleteFileMetadata、KnowledgeMigrator.ts:71 — typeof value.created_at === 'string' 要求是字符串（这是输入侧校验，对应旧 Dexie 数据）
• store/knowledge.ts:74 — 已有 pattern：new Date(item.created_at).getTime() 转换到 ms epoch

2.8.2 迁移步骤

Step A: Producer 改造（都是 mechanical 替换）

Step B: Consumer 适配（实际上几乎 no-op）

dayjs(x) 接受 number，所以：

• dayjs(file.created_at).format(...) —— 无需改，自动工作
• dayjs(a.created_at).unix() —— 无需改

唯一可以简化的：.unix() 换 Math.floor(x / 1000) 更直接，但非必需。

Step C: Schema / Migrator

2.8.3 复杂度与风险

风险：

• 极低。dayjs 天然兼容；FileMigrator 的 new Date(iso).getTime() 有成熟 pattern
• 唯一潜在坑：historical bug 数据可能是 Date 对象而非 string（见 upgrade script :48）——FileMigrator 对 created_at 做 typeof 分支兜底，所有不合法值回退到 Date.now()

执行时机：独立小 PR，与 §2.4 tokens 类似，可以打包到"字段清理"合并 PR，甚至和 ext 前导点迁移合并。

2.9 id: UUID v4 → UUID v7 迁移

决策：

保留原 v4 ID；新 entry 自动用 v7。放宽 FileEntryIdSchema 为 z.uuid() 接受两种。跨表引用零翻译。

2.9.1 现状

v2 设计（当前代码）：

• DB schema（src/main/data/db/schemas/file.ts:25）：id: uuidPrimaryKeyOrdered() —— 新 entry 自动生成 UUID v7（_columnHelpers.ts:26）
• Zod 校验（src/shared/data/types/file/fileEntry.ts:64）：FileEntryIdSchema = z.uuidv7() —— 严格要求 v7
• 测试（fileEntry.test.ts:188-199）：明确断言 v4 校验失败

旧 FileMetadata ID 全部是 v4：

DB 层面 id: text()（_columnHelpers.ts:18, 27）——SQLite TEXT 列不约束 UUID 版本，v4/v7 字符串都能存。冲突点是 Zod runtime 校验。

2.9.2 两种迁移策略对比

Option A: 保留原 v4 + 放宽 Schema（推荐）

• FileMigrator 直接把旧 v4 id 写入 file_entry.id
• 跨表引用（message_blocks、paintings、knowledge_items、file_ref）无需翻译——原 id 原封不动
• 放宽 FileEntryIdSchema 从 z.uuidv7() 到 z.uuid()（接受 v4 和 v7 两种）
• 新建 entry 仍由 uuidPrimaryKeyOrdered() 默认生成 v7

Option B: 重生成 v7 + ID 映射

• FileMigrator 对每个旧 entry 生成新 v7 id，维护 oldId → newId 映射
• 所有引用 file 的表（message_blocks.file.id、paintings.files[].id、knowledge_items.data.file.id、file_ref.fileEntryId）都必须改写
• 保证 strict v7 invariant

取舍：

选 Option A 的理由：

1. v7 的核心优势是"新 insert 按时间顺序"，对索引 B-tree 友好；历史数据已经插入完成，v7 优势对它们不适用
2. 跨表 ID 翻译极易出 bug（每个引用源都要改，一个漏掉就是 orphan）
3. z.uuid() 仍然能拦住 garbage 字符串（真正的 schema validation 目的）
4. 符合 pathResolver 类似决策（信任输入 + 最小化改动面）

2.9.3 迁移步骤

Step A: 放宽 Schema（独立小 PR，可在 FileMigrator 之前做）

Step B: FileMigrator 实现

// 概念代码
async function migrateFileEntry(oldFile: DexieFileRow): Promise<FileEntryRow> {
  return {
    id: oldFile.id, // 保留原 v4 id
    origin: isInternalPath(oldFile.path) ? "internal" : "external",
    name: stripExt(oldFile.origin_name, oldFile.ext),
    ext: normalizeExt(oldFile.ext), // '.pdf' → 'pdf'
    size: oldFile.size,
    externalPath:
      oldFile.origin === "external"
        ? canonicalizeAbsolutePath(oldFile.path)
        : null,
    deletedAt: null, // Dexie 没软删除字段；external 也不允许 trashed（fe_external_no_delete）
    createdAt: toMs(oldFile.created_at), // ISO → ms
    updatedAt: toMs(oldFile.created_at), // Dexie 无 updatedAt，用 createdAt
  };
}

External path 去重（强制）：新 schema 的 UNIQUE(externalPath) 禁止同路径两条行。如果 Dexie 里存在多条指向同一 canonical path 的 external FileMetadata（由 case / NFD / 拼写差异合并后），FileMigrator 必须：

1. 按 canonicalizeAbsolutePath(path) 分组
2. 每组保留一条（建议取 createdAt 最早的）作为 surviving row
3. 把组内其他 id 收集到 id-remap 表，在迁移 file_ref（以及其他引用 FileMetadata.id 的业务表）时将旧 id 重路由到 surviving id
4. 被合并掉的 FileMetadata.id 不产生 file_entry 行

这条 invariant 用 schema 层的 UNIQUE index 强制，任何漏网的重复插入都会在 migrator 内抛出并中止迁移——这是期望行为，引导开发者补全 remap 逻辑而不是让脏数据进库。

Step C: 引用表迁移（对应各自 Migrator）

无跨表 ID 翻译——这是 Option A 的主要简化点。

2.9.4 风险

2.9.5 复杂度与执行时机

S。唯一实质改动是 schema 放宽 + test 更新。FileMigrator 的 id 字段处理是"直接拷贝"。

执行时机：Schema 放宽（Step A）可随时独立 PR；FileMigrator 实现（Step B）在 Batch 0 FileMigrator 整合时落地。

2.10 FileMigrator 整体规约与跨 migrator 协议

本节不重复 §2.2–§2.9 的字段映射，而是把 FileMigrator 的整体职责、在引擎中的位置、与业务 migrator 的协作契约、失败处理和观测性串成一份规约。字段级映射的具体规则散在前面各节（§2.7 拆分 / §2.8 created_at / §2.9 id 保留 / §2.3 file_ref 来源），本节只在 §2.10.6 用一张交叉引用表回链。

2.10.1 FileMigrator 在 MigrationEngine 中的位置

• 文件位置：src/main/data/migration/v2/migrators/FileMigrator.ts（新增；对齐其他 migrator 的命名风格）
• id（migrator 唯一标识）：'file'
• 执行顺序（BaseMigrator.order）：建议 order = 2.7——在 AgentsMigrator (2.5) 之后、KnowledgeMigrator (3) 之前。这保证：
  • 所有引用 FileEntry 的业务 migrator（Knowledge 3 / Chat 4 / 未来 Painting）都在 FileMigrator 之后跑
  • 与 BootConfig / Preferences / Assistant 等不引用 file 的 migrator 不存在虚假依赖
• 依赖：
  • MigrationContext.db —— SQLite 写入
  • MigrationContext.sources.dexieExport.tableExists('files') / createStreamReader('files') —— 读 v1 Dexie 导出的 files.json
• 输出：
  • 写入 file_entry 行（来自 v1 Dexie files 表，经 external 去重后）
  • 不写 file_ref 行——所有 ref 由对应业务 migrator 在迁移引用源时写入（见 §2.10.3）
  • 在 MigrationContext.sharedData 写入跨 migrator 协议产物（见 §2.10.3）

2.10.2 物理文件命名兼容性验证

前置假设：v1 internal 物理文件统一存于 {userData}/Data/Files/{id}{ext}（参考 FileStorage.ts 各 setter 的 name: uuid + ext 模式，其中 v1 ext 含前导点，所以拼接后形如 uuid-abc.pdf）。v2 resolvePhysicalPath 解析为 {userData}/Data/Files/{id}.{ext}（v2 ext 不含前导点，拼接后同样是 uuid-abc.pdf）。

结论：v1 / v2 在物理文件名层面字节相同，不需要重命名物理文件。FileMigrator 只在 schema 层做 ext 归一化（'.pdf' → 'pdf'），磁盘原样保留——与 §5.1 "不移动物理文件" 硬约束一致。

防御性抽样验证（FileMigrator 启动时一次性执行）：

// 概念代码 — 抽样 20 条 internal 行验证物理存在
const sample = candidateEntries.filter((e) => e.origin === 'internal').slice(0, 20)
let missing = 0
for (const entry of sample) {
  if (!(await pathExists(resolvePhysicalPath(entry)))) missing++
}
if (sample.length > 0 && missing / sample.length > 0.5) {
  throw new MigrationFatalError(
    `Physical file naming assumption violated: ${missing}/${sample.length} sampled internal files not found at {id}.{ext}; aborting before mass orphan`
  )
}

抽样失败率 > 50% 表明命名约定假设已破——例如 v1 用了 {id}_${origin_name} 之类的非标准命名。直接中止迁移并让开发者调查；否则盲目继续会产生大量"DB 有行、磁盘无文件"的孤儿 entry。

抽样通过、个别失败（< 50%）只 recordWarning 不阻塞：这些是历史损坏，v1 时代就存在。

2.10.3 跨 migrator 协议：file_ref 重建

file_ref 行不由 FileMigrator 写入，而由各业务 migrator 在迁移自己的引用源时同步写入。这把"业务对象 → 引用文件"的关系局部性留在业务 migrator 内部，避免 FileMigrator 反向依赖各业务表。

引用源责任分配：

MigrationContext 扩展（跨 migrator 数据传递）：

FileMigrator 完成后在 ctx.sharedData 注入两份只读产物：

// 概念代码 — FileMigrator.run 结束前
ctx.sharedData.set('fileMigrator.idRemap', /* ReadonlyMap<oldId, FileEntryId> */)
ctx.sharedData.set('fileMigrator.knownIds', /* ReadonlySet<FileEntryId> */)

• idRemap 服务 external 去重——canonicalizeAbsolutePath 合并掉的 loser id 在表里映射到 surviving id。internal 文件不在表里（一对一保留）。
• knownIds 是所有成功写入 file_entry 的 id 全集，供业务 migrator 校验 "这个 fileId 是否真的迁过去了"。

业务 migrator 通过这两份产物访问 file 子系统，不直接查 DB（保持迁移期单向数据流；同时避免对 fileEntryService 启动顺序产生隐式依赖）。

业务 migrator 调用约定：

// 概念代码 — ChatMigrator 迁移 message_block 时
const idRemap = ctx.sharedData.get('fileMigrator.idRemap') as ReadonlyMap<string, FileEntryId>
const knownIds = ctx.sharedData.get('fileMigrator.knownIds') as ReadonlySet<FileEntryId>

async function migrateOneMessageBlock(block) {
  if (block.file?.id) {
    const fileEntryId = idRemap.get(block.file.id) ?? (block.file.id as FileEntryId)
    if (!knownIds.has(fileEntryId)) {
      // FileMigrator 没成功迁过这个 id —— 跳过 ref，告警
      this.recordWarning(`message_block ${block.id}: file ${block.file.id} missing in file_entry; ref skipped`)
      return
    }
    await ctx.db
      .insert(fileRef)
      .values({
        fileEntryId,
        sourceType: 'chat_message',
        sourceId: block.id,
        role: block.type === 'IMAGE' ? 'image' : 'attachment'
      })
      .onConflictDoNothing() // 重跑幂等
  }
  // ... 继续写入 message_block ...
}

关键约定：

1. 任何业务 migrator 在写入引用 fileEntryId 之前必须查 idRemap——这是 surviving id 的唯一来源；internal 文件查表 miss 时退回原 id（即 v4），external 文件未经查表写入会引用已合并掉的 loser id
2. fileRefService.create（或等价 db.insert(fileRef)）在迁移期使用 onConflictDoNothing 语义——避免重跑时触发 UNIQUE(fileEntryId, sourceType, sourceId, role) 冲突
3. 单条 ref 写入失败 → recordWarning 跳过；不整批回滚。理由：v1 count 本就是启发式数字，少几行 ref 不破坏迁移完整性；后台 OrphanRefScanner 兜底——漏建的 ref 体现为 file_entry "零引用"，由 cleanup UI 展示给用户
4. fileEntryId 在 knownIds 缺失（FileMigrator 没迁成功）→ recordWarning 跳过整个 ref。比"插入 ref 引用不存在的 entry"安全：后者会破坏 FK 完整性

2.10.4 FileMigrator 失败处理矩阵

回滚原则：FileMigrator 的 file_entry 写入在单个 DB 事务内执行；中断 = 全部回滚 = 下次重跑。避免"半迁移"状态下业务 migrator 看到不一致的 knownIds。

注：业务 migrator 的 file_ref 写入不与 FileMigrator 同事务——业务 migrator 各自有自己的事务边界，靠 §2.10.3 的 idRemap / knownIds 协议保证一致性。

2.10.5 观测性

FileMigrator 完成时发出一条 info-级结构化日志记录（通过 loggerService.withContext('FileMigrator')）：

// 概念代码 — FileMigrator.run 结束发射
{
  event: 'file-migrator-completed',
  v1FilesScanned: number,            // 输入流读到的 file 行总数
  v1FilesSkippedMalformed: number,   // 缺字段 / canonicalize 失败 等
  v1FilesMerged: number,             // external 去重折叠掉的 loser 数
  fileEntriesInserted: number,       // 成功写入 file_entry 的总数（= scanned - skipped - merged）
  sampleVerifyMissing: number,       // §2.10.2 物理抽样未通过的数量（> 50% 已 fatal）
  durationMs: number,
}

业务 migrator 在自身收尾阶段各自补一条 *-file-refs-built 记录：

{
  event: 'chat-migrator-file-refs-built' | 'knowledge-migrator-file-refs-built' | ...,
  refsInserted: number,
  refsSkippedMissingEntry: number,   // knownIds miss
  refsSkippedConflict: number,       // onConflictDoNothing 命中（重跑常见）
}

两类记录合起来构成 file 子系统迁移的端到端快照。

2.10.6 与 §2 字段映射节的交叉引用

2.10.7 复杂度与执行时机

前置条件 / PR 拆分顺序：

1. §2.9.3 Step A —— FileEntryIdSchema 放宽至 z.uuid()（独立 PR，可先行）
2. MigrationContext.sharedData 协议扩展（添加 fileMigrator.idRemap / fileMigrator.knownIds 的 key 与读写工具，建议封装成 getFileMigratorProducts(ctx) helper 避免各 migrator 自己 cast unknown）
3. FileMigrator 本体（含 §2.10.2 抽样验证 + §2.10.3 idRemap 计算 + §2.10.4 失败处理 + §2.10.5 日志记录）
4. KnowledgeMigrator 改造（决议见 §6 Q9 后落地：在现有 data.file.id 处理流程后追加 file_ref 写入；loadFileLookup 去留按 Q9 结论）
5. ChatMigrator 改造（延后，PR #15067 已 defer；与 chat 域 file_ref 服务同 PR 上线，三表面同步——allSourceTypes 增加 'chat_message'、createRefSchema 变体、OrphanRefScanner checker）
6. PaintingMigrator 跟随 painting 域整体迁移（不阻塞 v2 主线）

3. 消费域切换计划

总览：详见 filemetadata-consumer-audit.md §6。本节聚焦具体切换顺序和动作。

3.1 域切换顺序

顺序依据：

• 从小到大，先在低风险域验证适配层设计
• Messages 最后——它的数据模型最深，且量最大
• 字段级退役与域切换交错：某域阻塞的字段先做退役，再做域切换

3.2 每个域的切换模板

每个域的切换 PR 遵循相同步骤，逐个域展开时填入具体内容：

1. 入口枚举：列出该域触发文件操作的所有 UI 入口（哪个 component）
2. 当前数据结构：该域如何持有 FileMetadata（直接内嵌？数组？hashmap？）
3. 当前 API 调用：调 window.api.file.* 的哪几个方法
4. 新 API 映射：每个旧调用对应到 v2 哪个 IPC / DataApi
5. 数据迁移器：如果该域有 Dexie → SQLite 数据搬运，对应的 Migrator 位置
6. UI / 行为变化：是否有用户可感知的行为差异（例如 dangling 文件展示）
7. 测试点：关键集成测试用例
8. 回滚策略：如果发现严重问题，如何短时间回退

3.3 Batch A-E 详细计划（待调研后逐个展开）

（占位——每个 Batch 按 §3.2 模板展开）

3.4 跨模块切换协调

本节覆盖字段退役（§2）和 Batch A-E 域切换（§3.1）之外的跨模块协调点。这些事项不属于任何单个 consumer 的迁移，而是切换期需要全局协调的时序、phasing 和下线计划。

3.4.1 Backup / Restore 与 v2 file 子系统协调

v1 现状：

• src/main/services/BackupManager.ts 通过 fs-extra.copy 复制 userData 目录到打包暂存目录
• 备份产物包含：物理文件树（Data/Files/*）+ Dexie 导出（含 files.json）+ LocalStorage / Redux state 导出
• S3 / WebDAV 远端上传 zip 归档

v2 切换后的结构变化：

• Dexie files 表 Cleanup Batch 删除，SQLite file_entry / file_ref 进场
• 备份产物必须同时容纳：物理文件（位置不变）+ SQLite DB 文件 + 兼容期内仍存在的 Dexie 导出
• 恢复时必须原子化还原物理文件 + SQLite DB，否则会触发：
  • 物理文件还原 + DB 未还原 → 启动期 orphan-file-sweep 误删用户文件（命中 §10.4 安全阈值时只是不删，但 count-fraction 触发会变成日常发生）
  • DB 还原 + 物理文件未还原 → file_entry 行指向不存在物理文件，全部变 dangling

改造点（按依赖顺序）：

关键风险与缓解：

复杂度：L（跨 main 进程多个子系统：BackupManager + DbService + FileManager）。

执行时机：与 Phase 2 同步——FileMigrator 落地后立刻补 BackupManager。不能等 Cleanup Batch，否则 Phase 2 切换期间用户备份会丢失 SQLite 数据。

3.4.2 OrphanRefScanner 启动时机 gate

问题：

• RFC §6.4 规定 OrphanRefScanner 在 Background phase 启动，扫描 file_ref 找 sourceId 不存在的行删掉
• FileManager 的 runStartupSweeps（启动期 file-sweep + orphan-entry-report）同样在 onInit 后 fire-and-forget
• 如果 MigrationEngine 还在跑（FileMigrator 写完 file_entry → 业务 migrator 还没写完 file_ref），scanner 提早启动会看到「file_entry 但无 file_ref」状态——虽然 RFC §7.1 政策是「preserve」不删 entry，但 orphan-ref-cleanup 还是会扫——而且 §3.4.1 B4 的 backup-restore 场景也需要同样的 gate

规约：

复杂度：S（Signal 接线 + 一行 await + flag bookkeeping）。

执行时机：与 FileMigrator 落地同一 PR——否则首次 v2 启动就有概率把刚迁过来但 file_ref 还没建好的 entry 错判为 zero-ref（虽然 §7.1 政策保留 internal、policy matrix 处理掉 external 0-ref，但若 §7.2 deferred 提前实现就会出问题）。

3.4.3 Dexie files 表 phasing

问题：§5.1 「保留 Dexie 备份直到 Cleanup Batch」过于粗——Phase 2 切换期间 renderer 是否继续写 Dexie files 表？这条决定了 §4 shim 的有效边界和数据一致性窗口。

phasing 计划：

改造点：

关键决策：

• 无双写期——Phase 2 启动就 freeze。理由：双写期需要维护 Dexie ↔ SQLite 一致性，工程成本高于 shim 的读取适配
• shim 单向（FileEntry → 旧 FileMetadata 形状）已经在 §4.1 规约；§3.4.3 与 §4.1 一致

复杂度：M（renderer 多处入口要审计 + DexieFilesFrozenError 接线）。

执行时机：Phase 2 启动作为 Batch A 之前的 prerequisite PR。

3.4.4 v1 window.api.file.* preload API 下线顺序

问题：v1 preload 暴露 49 个 file 相关 API（File_Read / File_Write / File_Upload / File_Delete / onFileChange 回调 ...）。§4.3 提到 Cleanup Batch 删 FileMetadata 类型和 FileStorage，但没列 preload API 下线顺序——49 个 channel 逐个下线是 Cleanup Batch 的实际工作量。

分类与下线规则：

改造原则：

• 每个 Batch 完成时 deprecate 自己用到的 v1 API（preload 加 @deprecated JSDoc + 首次调用 console.warn 一次，避免日志洪水）
• Cleanup Batch PR 一次性 delete preload 暴露 + 对应 IPC handler 注册

复杂度：M（49 个 API 逐个 audit；多数是机械下线，少数需要先确认所有调用点都已切换）。

执行时机：各 Batch 完成时 deprecate；Cleanup Batch 一次性删除。

3.4.5 remotefile/* services 过渡期生命周期

v1 现状：

• src/main/services/remotefile/{Gemini,OpenAI,Mistral}Service.ts 实现 BaseFileService 接口（uploadFile / retrieveFile / listFiles / deleteFile）
• chat 流程通过 window.api.fileService.upload(provider, file) 走这些 services
• 上传缓存机制：fileProcessor.ts 在上传前查 cached fileId，命中则跳过

v2 终态：

• FileUploadService + file_upload 表（RFC §9.8 Phase X，依赖 Vercel AI SDK 稳定）
• chat 流程改走 FileUploadService.ensureUploaded(entryId, provider)，cache 由 file_upload 表持久化

过渡期协议：

关键决策：

• Phase 2 切换不等 FileUploadService——remotefile/* services 继续担当 upload 通道，仅需在 displayName / purpose 字段层对接 v2 schema（已在 §2.2 / §2.7 规约）
• 过渡期不引入新 cache 表，fileProcessor.ts 旧 cache 逻辑临时保留在 renderer 内存里——避免 file_upload 表设计在 Vercel AI SDK 稳定前被锁死
• watcher 转发协议（§3.4.4 watcher 类）：业务模块用 createDirectoryWatcher 后，自定义 IPC channel（建议 <module>-event，如 notes-event）把事件转发给 renderer；不复用 file-manager-event 通道——后者由 FileManager 占有，业务事件不应混入

复杂度：S（字段层适配已在 §2.2 / §2.7 规约，本节只追加生命周期约定）。

执行时机：Batch B 完成；Phase X 落地时进入下线倒计时。

3.4.6 §3.4 各项的总览

4. 适配层（Shim）设计

Scope 限定：shim 只服务桶 P——给还没迁移到 FileEntry 的持久化消费者（Dexie / message_block 内嵌 / knowledge_item JSON）临时的"看起来像 FileMetadata"视图。

不提供的 shim：

• 桶 I 无 shim——FileMetadata → FileInfo 是同端字段瘦身，直接改签名
• 桶 A 无 shim——两栖消费者必须拆签名解决（持久化动作走 createInternalEntry / ensureExternalEntry 显式升格，处理动作接 FileInfo），用 shim 糊弄会让 A 桶永远清不掉
• 反向 shim（FileMetadata → FileEntry）——不提供；FileInfo → FileEntry 必须走 FileManager sanctioned 生产入口（brand 强制），伪造的 FileEntry 会被 Zod 拒收

4.1 toFileMetadata(entry: FileEntry, physicalPath: FilePath): FileMetadata —— 桶 P 过渡期专用

// 概念代码。仅在未迁移的桶 P 消费者落地点使用；迁移完成后随消费者一起删除
function toFileMetadata(entry: FileEntry, physicalPath: FilePath): FileMetadata {
  return {
    id: entry.id,
    name: entry.ext ? `${entry.id}.${entry.ext}` : entry.id, // 旧的"存储名"约定
    origin_name: entry.ext ? `${entry.name}.${entry.ext}` : entry.name,
    path: physicalPath, // via FileManager.resolveForSystem / resolvePhysicalPath
    size: entry.size,
    ext: entry.ext ? `.${entry.ext}` : "", // 注意加回前导点（旧约定）
    type: getFileTypeFromExt(entry.ext), // ops.getFileType
    created_at: new Date(entry.createdAt).toISOString(),
    count: 0, // 需要时查 file_ref；旧消费方大多不读
    // tokens / purpose 不填——新系统已剥离
  }
}

注意点：

• ext 的前导点差异（旧带点，新不带）在此处归一
• count 需要时查 file_ref，默认 0（旧消费方大多不读）
• path 需要由 main 侧 resolvePhysicalPath(entry) 预先解析；renderer 侧不应自拼

4.2 反向 shim：不提供

旧代码产出的 FileMetadata 不能通过同步转换变成 FileEntry——FileEntrySchema 的 Zod brand 会挡住伪造。正确路径：

• 若旧 FileMetadata 源自Dexie 持久化数据：在 FileMigrator 阶段一次性搬运到 file_entry（见 §6）
• 若旧 FileMetadata 源自runtime 生产（如 FileStorage.uploadFile 新建）：Phase 2 把对应 producer 直接替换成调用 createInternalEntry IPC
• 若仅需要用文件属性（OCR / TokenService / 渲染等）：这是桶 I 或桶 A 的处理路径——FileMetadata 瘦身成 FileInfo，签名改掉就好

4.3 Shim 的生命周期

• Phase 2 双读双写期：引入 toFileMetadata（仅桶 P 用）
• Batch A-E consumer migration 期：随桶 P 消费者逐个迁移到 FileEntry，shim 调用点递减
• Cleanup Batch：最后删掉 toFileMetadata 与 FileMetadata 类型本身；FileInfo / FileEntry / FileHandle 成为唯一表达

5. 执行约束与里程碑

5.1 硬约束

• 不移动物理文件：所有 internal 文件物理位置保持 {userData}/files/{id}.{ext}，FileMigrator 只建表、不动盘
• 不破坏用户数据：每次迁移保留 Dexie 备份直到 Cleanup Batch
• 可逐域回滚：任何一个域的切换 PR 都能独立回滚，不影响其他域

5.2 里程碑（tentative）

5.3 每个 PR 的最小描述模板

切换 PR 应在描述中包含：

• 对应字段 / 域（引用本文档章节号）
• 改动范围（文件清单）
• 是否破坏旧消费方（如有，明确适配层处理）
• 回滚方法

6. 开放问题与决策追踪

附录 A：术语对照

附录 B：修订记录