panatgithub_AnkiHeadingSync/docs/implementation-decisions.md

模块 3 实现决策

本文锁定模块 3 的具体实现决策，范围以 docs/2026-04-18PLAN4.md 为准。

1. 主链路替换策略

• 模块 3 采用新的索引/状态/规划/执行主链路。
• 现有模块 1/2 代码保留在仓库中，但插件命令入口改接模块 3 use case。
• 不为旧 legacy cardKey / embeddedNoteId 做兼容适配。

2. marker 与身份

• 统一 marker 格式：<!-- AHS:card=<cardId> note=<noteId> -->
• 允许仅写 cardId：<!-- AHS:card=<cardId> -->
• cardId 采用 ahs_ 前缀加随机唯一片段生成
• 缺失 marker 的块在用户执行命令时生成 cardId，平时不自动回写

3. 文件级跳过实现

• 为满足“先过滤路径，再读文件内容”，新增文件元数据扫描接口
• 文件状态除计划要求的 fileHash 外，额外保存内部 fileStamp
• fileStamp 采用 mtime:size，只用于决定是否需要重新读取文件
• fileHash 在真正读取文件内容后计算并持久化

4. pending write-back 恢复策略

• 计划要求 pending write-back 可恢复，但 marker 缺失时无法仅靠 marker 重新定位
• 因此增加一个严格受限的内部恢复规则：仅允许在“同一文件 + 相同 rawBlockHash”时复用既有 cardId/noteId
• 这不是通用无 marker 身份推断，只用于本地已知 pending 或已存在状态的恢复

5. 渲染策略

• 扫描阶段只建立 IndexedFile/IndexedCard
• 仅 toCreate / toUpdate 进入 renderer
• renderConfigHash 独立计算，不与 rawBlockHash 混用
• 现有 markdown 渲染逻辑保留并抽到新的模块 3 渲染服务里复用

6. Anki 批处理策略

• 新增 BatchScheduler
• notesInfo / addNotes / updateNoteFields / changeDeck / storeMedia 按批执行
• 默认使用保守常量：
  • notesInfo batch size 100
  • addNotes / updateNoteFields batch size 50
  • storeMedia batch size 10，并发 3
• 不为当前模块额外开放用户设置项，先保持范围收敛

7. 本地状态结构

• 新状态统一存入 pluginState
• 结构包含：
  • files
  • cards
  • pendingWriteBack
• 当前实现不做旧 syncRegistry 自动迁移；旧数据保留但模块 3 不读取

8. rebuild index

• rebuild index 不调用 Anki 字段更新
• 它会：
  • 全量重建文件状态与卡片状态
  • 为缺失 cardId 的块补齐 marker
  • 尝试用本地状态恢复已知 noteId

9. 命令与提示

• 命令名称按计划使用中文：
  • 同步当前文件到 Anki
  • 同步全库到 Anki
  • 重建卡片索引
• Notice 展示：扫描文件数、扫描卡片数、新增、更新、orphan、media、跳过未变化卡数
• 若有 markdown 回写冲突，明确列出失败文件

10. 范围控制

• 不实现旧插件迁移
• 不实现双向同步
• 不实现实时监听自动同步
• 不为 tags 引入额外语法；当前阶段 tagsHint 为空数组，但批处理执行层保留接口位置