panatgithub_AnkiHeadingSync/docs/compatibility-touchpoints-report.md

兼容性触点报告

分析边界

• 只评估当前 manual-sync 主链，不把旧 syncRegistry 主链当成最终方案。
• 证据来源限定为四类真值：仓库代码、用户提供的旧 Markdown 样本、用户提供的新 Markdown 样本、实时 AnkiConnect 返回。
• 目标问题只有一个：当前主链能否安全接管由 Obsidian to Anki 生成的旧卡，并继续后续同步。

结论先行

当前主链不能直接接管旧卡。核心阻塞点不是 note model，也不是 deck，而是 identity bootstrap。

• 旧样本只提供 legacy noteId marker：<!--ID: 1760624596099-->
• 新主链只识别 AHS marker：<!-- AHS:card=ahs_xxx note=1776515511477 -->
• 当前状态层以 cardId -> noteId 为主键，而不是以 noteId 为主键
• 因此，旧文件在首次进入当前主链时，既拿不到 marker.cardId，也拿不到 pluginState.cards[cardId]，最后只能被当成新卡创建

这意味着“直接接管”会造成重复建卡，而不是认领旧卡。

关键触点一览

触点	当前行为	兼容性影响	结论
src/domain/manual-sync/services/CardMarkerService.ts	isCandidate() 和 parse() 只认 <!-- AHS:card=... note=... -->	旧样本 <!--ID: ...--> 对主链是不可见 marker	不兼容
src/domain/manual-sync/services/CardIndexingService.ts 的 extractMarker()	只会剥离 AHS marker；没识别出的 legacy marker 会被保留在正文里	旧 marker 不会转成 noteId，还会污染 bodyMarkdown 与 rawBlockHash	不兼容
src/domain/manual-sync/services/CardIndexingService.ts 的 resolveIdentity()	解析顺序是 marker.cardId -> pendingWriteBack -> knownCards(filePath, rawBlockHash) -> 生成新 cardId	旧文件首次扫描时三条已有身份路径都不存在，必然生成新 cardId	不兼容
src/domain/manual-sync/services/DiffPlannerService.ts	resolvedNoteId 为空就进入 toCreate	旧卡不会被“接管更新”，而会被“新建重复卡”	不兼容
src/domain/manual-sync/entities/PluginState.ts	cards 以 cardId 为 key，状态里没有 legacy marker 元数据位	当前状态容器无法直接承接“只有 noteId、没有 cardId”的旧卡	不兼容
src/infrastructure/persistence/DataJsonPluginStateRepository.ts	只读取 snapshot.pluginState，不会消费 syncRegistry	即便 data.json 里还有旧 syncRegistry 记录，manual-sync 也不会拿来认领旧卡	不兼容
src/application/services/FileIndexerService.ts	只把 pluginState.cards 和 pendingWriteBack 喂给 indexer	旧卡若没先迁入 pluginState，主链没有任何第二身份来源	不兼容
src/application/services/MarkdownWriteBackService.ts	只会写入新的 AHS marker	如果直接跑在旧文件上，会在 legacy marker 后再插入一个 AHS marker，而不是替换旧 marker	有风险
src/domain/manual-sync/services/DeckExtractionService.ts + DeckNormalizationService.ts	会提取 TARGET DECK，并保留 deck segment 原文，只做分隔符规范化	旧样本里的 [[anki背诵]]::[[《城市居住区规划设计标准》图解2021年]] 能被原样保留	兼容
src/domain/manual-sync/services/ManualCardRenderer.ts	当前渲染会在背面追加 Open in Obsidian backlink	即使完成接管，后续同步也会把旧卡字段逐步归一到新渲染样式	条件兼容
src/application/services/HeadingSyncMarkerService.ts + src/domain/card/services/CardExtractionService.ts	旧链路支持的是 <!-- AHS:123 --> 这种 noteId-only marker	这和本次真实旧样本的 <!--ID: ...--> 不是同一种格式，也不在 current manual-sync 主链里	不能直接复用

代码触点拆解

1. Marker 语义已经换代

当前 manual-sync 的 marker 不是“把 noteId 嵌进去就行”，而是显式要求：

• 一个稳定的 cardId
• 一个可选的 noteId
• 一个确定的 AHS marker 字面量

旧样本只有 noteId，没有 cardId。这不是缺一个字段那么简单，而是整个主链的身份主键已经从 noteId 切成了 cardId。

2. 当前主链不会利用旧 syncRegistry

实时 data.json 里仍然同时存在：

• syncRegistry.records[].identityMode = "embedded-note-id"
• pluginState.files / pluginState.cards

但 DataJsonPluginStateRepository 只加载 pluginState，manual-sync 完全不看 syncRegistry。所以旧状态即便还在 data.json 里，也不会自动帮助旧卡进入新主链。

3. Deck 不是阻塞点

这是这次分析里最重要的反向结论之一。

• 旧样本 Markdown 明确声明了 TARGET DECK: [[anki背诵]]::[[《城市居住区规划设计标准》图解2021年]]
• 旧样本 live card 的 cardsInfo.deckName 也正是这个 wikilink deck 字符串
• 当前 DeckNormalizationService 不会剥掉 [[...]]，只会规范 /、\ 和 ::

因此，旧 deck 的字面值兼容是成立的。真正不兼容的是 identity，不是 deck。

4. Note model 与字段映射也不是阻塞点

实时样本显示：

• 旧样本 live note：modelName = 问答题，字段为 正面 / 背面
• 新样本 live note：modelName = 问答题，字段为 正面 / 背面
• 当前插件设置：basic:问答题 -> titleField=正面, bodyField=背面

所以旧卡与新卡在 Anki 侧的数据模型是兼容的，后续接管不需要做 note type 迁移。

最终触点判断

已兼容

• 旧 deck 字符串可继续沿用
• 旧 note model / 字段映射与当前设置兼容
• 旧 noteId 在 Anki 中真实存在，具备可迁移基础

未兼容

• legacy marker 识别
• 首次 identity 认领
• 旧状态向 pluginState 的引导
• 直接运行时的防重复保障

因此得到的主结论

当前主链不属于“可直接接管”。

它属于“可以接管，但必须先做一次迁移写回”：

• 先把旧 noteId 身份翻译成新 cardId + noteId 身份
• 再把 Markdown marker 和 pluginState 一次性对齐到 current manual-sync 语义