panatgithub_AnkiHeadingSync/docs/2026-04-17PLAN3.md

模块 2：将 Anki noteId 回写到标题块末尾，使用短标记 <!-- AHS:123 -->

归档说明（2026-04-21）：本文描述的是已移除的 legacy syncRegistry 主链方案。 当前保留的生产同步链路是 ManualSyncService 所在的 manual-sync 体系。

Summary

• 新增卡片同步成功后，把返回的 Anki noteId 写回对应标题块的块尾，格式固定为 <!-- AHS:<noteId> -->。
• 以后该标题块再次同步时，优先按这个 noteId 更新原卡，不再依赖 标题 + 行号 + 路径。
• 标记放在块尾而不是标题下方，用来明确卡片边界。
• 老卡不迁移，只对以后新增的卡生效；老卡继续走当前 cardKey 逻辑。
• 如果块尾 noteId 在 Anki 中不存在，自动重建新卡并替换为新的 noteId。
• 如果同一标题块从 basic 切到 cloze 或反过来，直接报错并要求用户重建。

Key Changes

1. 标记语法与块尾规则

• 唯一支持的标记格式：
  • <!-- AHS:<正整数> -->
• 标记位置固定：
  • 当前标题块最后一个非空内容行之后
  • 下一个同级或更高层级标题之前
• 写回规则固定：
  • 有正文时：写在正文末尾
  • 无正文时：写在标题下一行
  • 标记本身视为块尾终止标记
• 读取规则固定：
  • 只识别当前标题块块尾的最后一个合法 AHS 标记
  • 标记不进入 bodyMarkdown
  • 同一标题块多个合法 AHS 标记时报错
  • 非法 AHS 格式时报错，不静默忽略

2. 提取与渲染

• CardDraft 增加 embeddedNoteId?: number
• SourceLocation 增加块尾定位信息，至少包括：
  • blockEndLine
  • contentEndLine
  • markerLine?: number
• CardExtractionService 负责：
  • 识别块尾 <!-- AHS:... -->
  • 从正文中剔除该标记
  • 将 embeddedNoteId 放入 CardDraft
• CardRenderingService 不处理身份标记，继续只处理标题和正文渲染

3. 同步身份与本地状态

• 同步身份模式固定为三种：
  • embedded-note-id
  • legacy-card-key
  • pending-note-id-write
• SyncRecord 增加：
  • identityMode: "embedded-note-id" | "legacy-card-key" | "pending-note-id-write"
  • legacyCardKey?: string
  • noteId: number
  • filePath
  • sourceHash
  • lastSyncedAt
  • orphan
• SyncRegistry 必须支持：
  • findByNoteId(noteId)
  • get(cardKey) 保留兼容
• 新卡首次成功写回 AHS 标记后，记录保存为 embedded-note-id
• 老卡无标记时，继续保存为 legacy-card-key
• 建卡成功但标记写回失败时，保存为 pending-note-id-write 并保留 legacyCardKey

4. 规划逻辑

• 匹配优先级固定：
  1. 有 embeddedNoteId 时，按 noteId
  2. 无 embeddedNoteId 时，按当前 legacy cardKey
• 对 embeddedNoteId 卡片：
  • registry 有同 noteId 记录：按 sourceHash 判断是否更新
  • registry 无记录：仍视为已有卡，可直接更新
• orphan 判定拆成两套：
  • embedded-note-id 按本轮看到的 noteId
  • legacy-card-key 按本轮看到的 cardKey
• 老卡不自动补写 AHS，只保留当前行为

5. 执行逻辑

• AnkiGateway 增加：
  • getNoteSummaries(noteIds: number[]): Promise<Array<{ noteId: number; modelName: string }>>
• 执行前先校验所有 embeddedNoteId：
  • note 存在且模型一致：updateNote
  • note 不存在：自动重建
  • note 存在但模型不一致：报错并停止该卡同步
• 自动重建流程固定：
  1. addNote
  2. 用新的 noteId 替换块尾旧 AHS 标记
  3. registry 更新为新的 embedded-note-id
• 新卡首次同步流程固定：
  1. 无 AHS 标记，先 addNote
  2. 把返回的 noteId 写到块尾
  3. registry 保存为 embedded-note-id

6. Markdown 写回

• VaultGateway 增加：
  • replaceMarkdownFile(path: string, expectedContent: string, nextContent: string): Promise<void>
• 写回采用 optimistic concurrency：
  • 文件内容仍等于扫描时内容才允许写回
• 块尾写回算法固定：
  • 定位当前标题块结束边界
  • 移除旧 AHS 标记（若存在）
  • 将新标记写到块内最后一个非空内容行之后
  • 不允许落到下一个标题之后
• 若 addNote 成功但写回失败：
  • 不删除新建 note
  • registry 记为 pending-note-id-write
  • 以后只要还能按 legacy key 命中，就继续尝试补写 AHS
• 补写成功后，记录转为 embedded-note-id

Public Interfaces / Types

• CardDraft.embeddedNoteId?: number
• SourceLocation.contentEndLine: number
• SourceLocation.markerLine?: number
• SyncRecord.identityMode
• SyncRecord.legacyCardKey?: string
• VaultGateway.replaceMarkdownFile(...)
• AnkiGateway.getNoteSummaries(...)
• HeadingSyncMarker
  • noteId: number
  • raw: string
  • lineIndex: number

Test Plan

• 块尾 <!-- AHS:123 --> 能被正确识别
• AHS 标记不会进入 bodyMarkdown
• 同一标题块多个 AHS 标记时报错
• 非法 AHS 格式时报错
• 新卡创建后，AHS 被写到块尾
• 空正文标题块时，AHS 写在标题下一行
• 带 AHS 的卡在改标题、改正文、块内移动、文件移动后仍更新原 note
• registry 丢失时，带 AHS 的卡仍能按 noteId 更新
• noteId 在 Anki 不存在时会自动重建，并替换块尾 AHS
• basic/cloze 类型切换时报错
• 老卡无 AHS 时继续走 legacy cardKey
• addNote 成功但写回失败时，生成 pending-note-id-write
• 下次命中后可补写 AHS 并转正
• orphan 检测对 embedded-note-id 和 legacy-card-key 都正确

Assumptions

• 第一版只支持块尾短标记 <!-- AHS:<noteId> -->
• 不兼容旧的 ID: 行、长注释格式、frontmatter、block ID
• 老卡不迁移；只有以后新增的卡获得稳定 noteId 身份
• basic 与 cloze 的跨类型切换第一版不自动处理
• 允许插件改写 Markdown 文件，在标题块末尾插入或替换 AHS 标记