panatgithub_AnkiHeadingSync/docs/anki-plugin-ddd-idea.md

# Obsidian Anki 新插件设计备忘（DDD 讨论稿）

> 归档说明（2026-04-21）：本文包含已移除的 legacy sync / syncRegistry 架构讨论。
> 仓库当前有效实现以 `ManualSyncService` manual-sync 主链为准。

## 文档目的

这不是一个立即开工的实现文档，而是一份面向未来的设计备忘。

目标是把当前已经讨论清楚的方向、边界、约束、DDD 拆分方式、领域模型、同步策略、风险点与后续演进路径完整记录下来，避免之后重新开始时又回到模糊状态。

本文档面向的插件目标是：

- 重新做一个新的 Obsidian -> Anki 插件
- 吸收 `AnkiHelperForCoding` 与 `obsidian-to-anki-plugin-forCoding` 的优点
- 保留“好用的做卡与同步能力”
- 去掉过重、过泛化、过难维护的部分
- 明确以 Obsidian 为唯一真源
- 明确只做单向同步：`Obsidian -> Anki`

库一：/Users/panxiaorong/Documents/ObsidianPluginCode/AnkiHelperForCoding
库二：/Users/panxiaorong/Documents/ObsidianPluginCode/obsidian-to-anki-plugin-forCoding

## 背景与总体判断

现有两个仓库各有优点，但都不适合作为新插件的直接基础。

### 1. `AnkiHelperForCoding` 的优点

- 工作流聚焦
- 功能边界相对清楚
- 对标题式做卡思路明确
- 有轻量的批处理和增量处理思路
- 贴近 Obsidian 内的实际使用方式

### 2. `obsidian-to-anki-plugin-forCoding` 的优点

- 真正具备较完整的 AnkiConnect 同步链路
- 能创建牌组、添加卡片、更新卡片、处理媒体
- 有较成熟的 Markdown/媒体/公式/链接转 Anki 可显示内容的能力
- 有全库扫描、同步状态、hash、批量处理等工程经验

### 3. 为什么不能简单合并

`obsidian-to-anki-plugin-forCoding` 的问题不是“代码不好”，而是产品定位已经变成“通用同步平台”，而不是“聚焦标题式做卡的新插件”。

它变重主要来自以下六层：

1. 输入语法越来越多
2. 配置系统越来越像框架
3. 同步系统承担了太多职责
4. 格式转换链较长
5. 全库扫描和过滤系统复杂化
6. TypeScript 之外还有 Python 旁路与更重的工程负担

新插件的方向不是复制它，而是：

- 保留核心能力
- 重写核心结构
- 主动缩掉产品边界

## 当前已确定的产品方向

下面是当前讨论中已经较明确的决定。

### 1. 输入语法只做“标题段落式”

只支持标题段落式卡片，不做旧插件里的通用语法平台。

规则初步确定为：

- 问答题默认使用四级标题 `H4`
- 填空题默认使用五级标题 `H5`
- 两者都允许用户修改级别
- 一个标题对应一个卡片块
- 卡片内容范围是：
  - 从该标题下一行开始
  - 到下一个“同级或更高标题”之前结束

这意味着第一版明确不做：

- 自定义正则语法
- Inline Note
- Begin/End Note 块语法
- 任意用户定义的卡片语法体系

### 2. 配置系统不做大平台

配置系统要保留必要能力，但不再做成旧插件那种开放式框架。

当前已保留的配置方向：

- 问答题标题级别
- 填空题标题级别
- `TARGET DECK`
- `qa note type`
- `cloze note type`
- 默认 deck
- 扫描范围（包含/排除文件夹）
- 是否添加 Obsidian 文件回链
- 是否为 Cloze 启用高亮转空

明确不做：

- folder -> deck 映射表
- folder -> tag 映射表
- 通用 syntax setting 集合
- 大量用户可编程语法选项
- 复杂 glob 平台

### 3. 同步系统保留核心能力

同步系统虽然重，但其中很多能力是值得保留的。

建议保留的能力：

- 创建 deck
- 新增 note
- 更新已有 note
- 媒体上传
- 批量扫描
- 同步状态持久化
- 增量同步
- orphan 检测

暂不直接做：

- Anki -> Obsidian 反向回写
- 双向同步
- 高复杂度冲突解决
- 第一版直接自动删除 orphan 对应的 Anki 卡片

### 4. 格式保真是关键目标

新插件的一个核心目标是：

> 在 Obsidian 里看到的内容，进入 Anki 后也尽量保持可用、可读、可复习。

因此需要保留并重构以下能力：

- Markdown -> HTML
- 数学公式
- 代码块与行内代码尽量不被破坏
- 高亮
- Wikilink
- 图片 embed
- 音频 embed
- Obsidian 回链

### 5. 需要做全局扫描，但边界要收紧

当前讨论结果是：

- 需要全局扫描
- 但只支持用户指定包含文件夹和排除文件夹
- 不做复杂 glob 规则平台

推荐规则：

- `includeFolders` 为空时：扫描整个 vault
- `includeFolders` 非空时：只扫描指定文件夹
- `excludeFolders` 始终生效
- 仅扫描 Markdown 文件

### 6. 工程上不保留 Python 旁路

新插件只保留 TypeScript / Obsidian 插件实现。

明确不做：

- Python CLI
- Python 安装与依赖管理
- 双实现栈同步维护

## 核心产品原则

这是新插件最关键的一条原则：

`Obsidian 是唯一真源，Anki 是同步目标。`

这条原则一旦确定，后续很多设计就会变得稳定：

- Obsidian 中的内容决定 Anki 中的内容
- Anki 中手改正文不会回写
- 下次同步时，Anki 中相关字段会被 Obsidian 内容覆盖
- 不需要做双向冲突合并
- 不需要把 Anki HTML 反解析成 Markdown
- 不需要做“Anki 改动写回标题块”的定位逻辑

## 为什么不做双向同步

虽然理论上可以做 Anki -> Obsidian 回写，但这不适合第一版，也可能永远不值得做。

原因包括：

- 无法轻易决定谁是最终真源
- Anki 中修改的可能是字段、标签、牌组、模型，而不只是正文
- Obsidian 的标题段落结构并不是数据库记录
- 回写时必须重新定位标题块
- 标题改名、移动、层级变化都会让回写不稳定
- HTML/媒体/链接从 Anki 回写为 Markdown 时存在信息损失

因此当前明确决定：

- 只做 `Obsidian -> Anki`
- 不做双向同步
- 不做 Anki 正文回写

## DDD 总体视角

这个插件如果用 DDD 来看，核心不是 UI，也不是 AnkiConnect API，而是：

> 把 Obsidian 中的标题段落块建模为“可同步卡片”，并稳定地同步到 Anki。

因此真正的核心领域不是：

- 设置页
- 命令面板
- HTTP 请求

而是：

- 卡片识别
- 卡片身份稳定性
- 卡片渲染
- 同步计划
- 同步状态演进

## 统一语言（Ubiquitous Language）

下面这些术语建议在整个项目里统一使用，避免后续沟通与实现混乱。

### Source Note

Obsidian 中的一个 Markdown 文件。

### Heading Block

一个标题以及它所管辖的正文范围。

### Card Draft

从标题块中解析出来、但还没有完成渲染和同步决策的卡片草稿。

### Card

领域中的标准化卡片对象，是同步的基本单位。

### Card Type

卡片类型，目前只包括：

- `basic`
- `cloze`

### Deck Target

卡片最终应进入的 Anki 牌组。

### Note Model

Anki 中的 note type / model，例如：

- `Basic`
- `Cloze`

### Rendered Fields

已经转换成可发送给 Anki 的字段内容。

### Sync Record

本地保存的同步记录，用于维护 `cardKey -> noteId` 映射及同步状态。

### Sync Scope

本次扫描或同步覆盖的文件范围。

### Orphan Card

本地同步记录里曾存在，但本次扫描中已经找不到来源卡片的记录。

### Source Hash

源卡片内容计算得到的 hash，用于判断是否变化。

## Bounded Context 拆分

建议把系统拆成四个主要上下文。

## 1. Card Authoring Context

负责从 Obsidian 内容里识别卡片。

### 职责

- 判断哪些标题会被视为卡片
- 判断这是问答题还是填空题
- 提取标题文本
- 提取正文块范围
- 解析文件级 `TARGET DECK`
- 产出 `CardDraft`

### 不负责

- AnkiConnect 通信
- noteId 管理
- orphan 检测
- HTTP
- UI

### 这里的核心问题

- 标题块切分是否准确
- 标题级别策略是否稳定
- 内容范围是否与用户认知一致

## 2. Rendering Context

负责把卡片内容转成 Anki 可接收的字段内容。

### 职责

- Markdown -> HTML
- 数学公式处理
- 图片与音频处理
- Wikilink 处理
- Obsidian 回链处理
- 高亮与 Cloze 转换
- 生成最终字段值

### 不负责

- 扫描哪些文件
- 判断新增/更新/删除
- 生成 noteId

### 这里的核心问题

- 内容是否保真
- 代码块、公式、高亮等边界是否被破坏
- 媒体是否可上传并正确显示

## 3. Sync Context

负责决定“该如何把卡片同步到 Anki”。

### 职责

- 读取历史同步记录
- 判断新增与更新
- 检测 orphan
- 生成同步计划
- 执行同步动作
- 更新本地同步记录

### 不负责

- 标题块如何识别
- markdown 如何渲染
- 设置 UI

### 这里的核心问题

- 同一张卡如何稳定识别
- 什么情况下是更新
- 什么情况下视为 orphan
- 删除是否自动进行

## 4. Integration Context

负责和外部系统打交道。

### 对 Obsidian

- Vault 文件访问
- MetadataCache
- 当前活动文件
- 命令注册
- 设置页

### 对 Anki

- AnkiConnect 调用
- 创建 deck
- 新增 note
- 更新 note
- 删除 note
- 上传媒体

### 角色定位

这是防腐层，不应该污染领域模型。

## Core Domain / Supporting / Generic

为了防止后续又掉回“大而杂”，建议从战略设计上明确区分：

### Core Domain

- 标题块识别
- 卡片身份生成
- 同步计划生成

### Supporting Subdomains

- Markdown/媒体/链接渲染
- 扫描范围过滤
- orphan 检测
- 同步状态存储

### Generic Subdomains

- 设置页
- 命令注册
- Notice 提示
- JSON 持久化
- HTTP 请求

## 聚合设计建议

不建议在这个项目里设计过多聚合。两个主要聚合已经足够。

## 聚合一：SourceFile Aggregate

聚合根：`SourceFile`

### 包含内容

- 文件路径
- 文件内容
- metadata 快照
- 文件级 deck 信息
- 解析出的标题块
- 解析出的卡片草稿

### 职责

- 在单文件内完成标题块识别
- 保证一个文件中的卡片识别逻辑一致
- 处理文件级 deck 覆盖

### 不应该负责

- Anki noteId
- 全局同步状态
- orphan 判断

## 聚合二：SyncRegistry Aggregate

聚合根：`SyncRegistry`

### 包含内容

- `cardKey -> SyncRecord` 映射
- 历史 noteId
- source hash
- 上次同步时间
- orphan 标记

### 职责

- 管理卡片同步状态生命周期
- 帮助判断新增、更新、orphan
- 与数据持久化边界配合

### 不应该负责

- markdown 渲染
- 标题块切分

## 实体与值对象建议

这里要严格区分 Entity 与 Value Object。

## Entity

### SourceFile

身份由 `filePath` 决定。

### Card

身份由 `cardKey` 决定。

### SyncRecord

身份由 `cardKey` 决定，也可内部持有 `noteId`。

## Value Object

建议作为值对象的内容：

- `CardKey`
- `DeckName`
- `NoteModelName`
- `HeadingLevel`
- `HeadingText`
- `HeadingBlockRange`
- `CardType`
- `RenderedFields`
- `SourceLocation`
- `ContentHash`
- `SyncScope`

## Card 领域对象建议

建议把领域中的 `Card` 明确定义为“标准化同步对象”，而不是随便几段文本。

推荐形状如下：

```ts
type Card = {
  key: CardKey;
  source: SourceLocation;
  type: CardType;
  heading: string;
  bodyMarkdown: string;
  deck: DeckName;
  noteModel: NoteModelName;
  tags: string[];
  fields: Record<string, string>;
  contentHash: ContentHash;
};
```

### 字段意义

- `key`
  - 这张卡在领域中的稳定身份
- `source`
  - 它来自哪个文件、哪个标题位置
- `type`
  - `basic` 或 `cloze`
- `heading`
  - 标题文本
- `bodyMarkdown`
  - 原始正文
- `deck`
  - 最终牌组
- `noteModel`
  - 最终 note type
- `fields`
  - 已经渲染好的 Anki 字段
- `contentHash`
  - 用于判断内容是否变化

### 一个重要原则

`bodyMarkdown` 与 `fields` 不应混为一谈。

前者是原始领域内容，后者是渲染后的派生内容。二者都应有清晰位置。

## Card Draft 建议

为了让解析与渲染解耦，建议先有 `CardDraft`。

```ts
type CardDraft = {
  source: SourceLocation;
  heading: string;
  headingLevel: number;
  type: "basic" | "cloze";
  bodyMarkdown: string;
  deckHint?: string;
};
```

然后由渲染层把 `CardDraft` 转成正式 `Card`。

这样做的好处是：

- 标题识别逻辑和渲染逻辑解耦
- deck 解析、字段映射可以单独演进
- 未来更容易测试

## Card Type 语义建议

当前只保留两类卡。

### Basic

语义建议：

- 标题 -> Front
- 正文 -> Back

### Cloze

语义建议：

- 正文 -> Cloze 主字段
- 标题不进入主 cloze 字段
- 标题可选进入额外字段，比如 `Extra` 或上下文字段

原因：

- 如果标题也拼进 Cloze 主字段，会干扰 Cloze 语义
- 标题更适合做上下文或辅助定位信息

## Note Model 与 Deck 的区别

必须明确区分：

### Note Model

决定 Anki 里字段结构，例如：

- `Basic`
- `Basic (and reversed card)`
- `Cloze`

### Deck

决定卡片进入哪个牌组，例如：

- `English`
- `English::Words`
- `History::Chapter1`

它们是两个完全不同的维度。

因此配置上建议分别建模，而不是混淆。

## Card Identity（cardKey）策略

这是整个系统最敏感的问题之一。

### 目标

`cardKey` 需要尽量满足：

- 同一文件内唯一
- 同一轮扫描内唯一
- 在小幅编辑下尽量稳定
- 不依赖 Anki noteId

### 第一版推荐策略

第一版可以先用较保守的组合：

```ts
cardKey = hash(
  filePath +
  headingLevel +
  headingText +
  blockStartLine +
  cardType
)
```

### 优点

- 实现简单
- 同文件内冲突概率低
- 足够支撑第一版

### 缺点

- 标题改名会影响 key
- 前面插入内容导致行号变化会影响 key
- 文件移动会影响 key

### 未来可升级方向

未来如果需要更稳定，可以考虑：

- 持久化块级 anchor
- 在标题块内植入不可见标识
- 使用内部 source id 映射

### DDD 视角下的建议

不要把 key 生成逻辑散落在代码中，而应抽成一个领域策略：

- `CardIdentityPolicy`

它属于业务规则，不只是技术细节。

## Deck 解析策略

当前建议的 deck 决策顺序：

1. 文件中显式配置的 `TARGET DECK`
2. 插件默认 deck

第一版不做：

- folder -> deck 映射
- 基于路径的 deck 自动推导
- 标题级单独 deck 覆盖

### `TARGET DECK` 的定位

作为保留下来的最小 syntax setting：

- 只保留 `Target Deck Line`
- 不保留 Begin/End Note 等其它语法开关

## 标题级别策略

当前建议默认值：

- `qaHeadingLevel = 4`
- `clozeHeadingLevel = 5`

### 需要保证的业务规则

- 两个级别都允许用户修改
- 两个级别不应相同
- 如果相同，应在配置层校验并阻止

## 扫描范围模型

虽然保留全局扫描，但需要主动收缩边界。

### 推荐配置

```ts
type ScanScopeConfig = {
  includeFolders: string[];
  excludeFolders: string[];
};
```

### 推荐行为

- `includeFolders` 为空：扫描全部 Markdown 文件
- `includeFolders` 非空：只扫描这些文件夹下的 Markdown 文件
- `excludeFolders` 永远对候选集做排除

### 第一版不做

- 任意 glob
- 单文件模式表达式
- ignore 语法 DSL
- 复杂优先级覆盖规则

## Sync Record 建议

本地同步状态建议保存为独立模型。

```ts
type SyncRecord = {
  cardKey: string;
  noteId: number;
  filePath: string;
  sourceHash: string;
  lastSyncedAt: number;
  orphan: boolean;
};
```

### 字段说明

- `cardKey`
  - 领域卡片身份
- `noteId`
  - Anki 中对应 note 的 id
- `filePath`
  - 便于追踪来源与调试
- `sourceHash`
  - 判断是否发生变化
- `lastSyncedAt`
  - 便于调试和排错
- `orphan`
  - 表示当前扫描未再找到对应来源

## 为什么建议先不做自动删除

虽然同步系统中“删除失效卡片”看起来合理，但第一版不建议直接做自动删除。

### 原因

- 标题改名会被误判为删除旧卡、创建新卡
- 文件移动可能导致 key 变化
- 扫描范围变窄时可能导致误判 orphan
- 用户切换设置后，候选卡集合可能临时变化
- 删除是破坏性动作，风险高

### 第一版建议

- 支持新增
- 支持更新
- 支持 orphan 检测
- 支持手动清理 orphan 的未来扩展点
- 默认不自动删 Anki 卡

## 建议的领域服务

以下领域服务是比较关键的。

## 1. CardExtractionService

### 输入

- `SourceFile`
- `HeadingPolicy`

### 输出

- `CardDraft[]`

### 负责

- 找到有效标题
- 切分正文块
- 判断 `basic` / `cloze`

## 2. DeckResolutionService

### 输入

- 文件级 `TARGET DECK`
- 插件默认 deck
- 卡片配置

### 输出

- `DeckName`

### 负责

- 决定卡片最终牌组

## 3. CardIdentityService

### 输入

- `SourceLocation`
- 标题信息
- 卡片类型

### 输出

- `CardKey`

### 负责

- 生成稳定 identity

## 4. CardRenderingService

### 输入

- `CardDraft`

### 输出

- `Card`

### 负责

- 生成最终字段
- 处理 Markdown/媒体/链接/公式

## 5. SyncPlanningService

### 输入

- 当前扫描得到的 `Card[]`
- 历史 `SyncRecord[]`

### 输出

- `SyncPlan`

### 负责

- 判断 add
- 判断 update
- 判断 orphan

这个服务是整个同步系统的关键，必须单独存在，不应散落在命令或 UI 层中。

## Sync Plan 建议

推荐把同步规划显式建模出来。

```ts
type SyncPlan = {
  toCreateDecks: string[];
  toAdd: Card[];
  toUpdate: Array<{ card: Card; noteId: number }>;
  toMarkOrphan: SyncRecord[];
};
```

### 第一版动作集合建议

第一版先只做：

- `createDeck`
- `add`
- `update`
- `markOrphan`

不做：

- `delete`

## Application Service / Use Case 建议

DDD 中应用服务负责“编排用例”，不承担核心业务规则。

## 1. ScanAndPlanSyncUseCase

### 流程

1. 读取扫描范围
2. 收集候选文件
3. 从文件解析 `CardDraft`
4. 渲染为 `Card`
5. 读取历史 `SyncRecord`
6. 生成 `SyncPlan`

## 2. ExecuteSyncPlanUseCase

### 流程

1. 创建缺失 deck
2. 上传媒体
3. 新增 cards
4. 更新 cards
5. 更新同步状态
6. 标记 orphan

## 3. SyncCurrentFileUseCase

### 流程

只对当前文件执行完整扫描与同步流程。

## 4. SyncVaultUseCase

### 流程

对扫描范围内的文件执行完整扫描与同步流程。

## 5. PreviewSyncUseCase（未来可选）

### 流程

只生成同步计划，不真正执行。

### 价值

- 调试
- 风险确认
- 后续做 UI 预览

## Repository 建议

Repository 主要是持久化边界，不是业务逻辑本身。

## 1. SyncRegistryRepository

### 负责

- 读取同步记录
- 保存同步记录
- upsert 卡片同步状态
- 标记 orphan

### 可能的存储位置

- 插件 `data.json`

## 2. PluginConfigRepository

### 负责

- 读取插件配置
- 输出面向领域的配置对象

### 注意

不要让领域层直接消费 Obsidian 原始 Setting UI 数据结构。

## 3. ScanScopeRepository（可选）

如果未来扫描配置较复杂，可以单独抽象。

## Anti-Corruption Layer（防腐层）建议

这个项目非常需要防腐层，否则外部 API 会把领域污染掉。

## 对 Obsidian 的防腐层

不要让领域层直接依赖：

- `App`
- `TFile`
- `CachedMetadata`

建议由基础设施层封装为：

- `ObsidianVaultGateway`
- `ObsidianMetadataGateway`
- `ObsidianWorkspaceGateway`

然后向应用层提供干净 DTO。

## 对 AnkiConnect 的防腐层

不要让领域层直接拼 action JSON。

建议封装为：

- `AnkiGateway`

对外提供的方法应是业务语义，而不是裸 `invoke("addNote")`：

- `ensureDeckExists`
- `addNote`
- `updateNote`
- `deleteNotes`
- `storeMedia`

## 领域不变量建议

这些不变量建议尽早确立。

### 卡片识别相关

- 一个标题块最多生成一张卡
- 一张卡必须属于且只属于一种 `CardType`
- 同一次扫描内 `cardKey` 不可重复

### 配置相关

- 问答题级别和填空题级别不能相同
- 每张卡必须解析出 deck
- 每张卡必须解析出 note model

### Basic / Cloze 相关

- `basic` 必须有 front/back 字段映射
- `cloze` 必须映射到支持 cloze 的 note model

### 同步相关

- 一个 `cardKey` 只能对应一个活动同步记录
- 一个 `noteId` 不应对应多个不同 `cardKey`
- orphan 默认不能自动删除

## 建议的目录结构

如果未来真的开工，建议从一开始就按边界建目录，而不是继续堆在 `main.ts` 和工具函数里。

```text
src/
  domain/
    card/
      entities/
      value-objects/
      services/
      policies/
    sync/
      entities/
      value-objects/
      services/
    shared/
      value-objects/
  application/
    use-cases/
    dto/
  infrastructure/
    obsidian/
    anki/
    persistence/
  presentation/
    commands/
    settings/
    notices/
```

可以进一步细化为：

```text
src/domain/card/entities/Card.ts
src/domain/card/entities/SourceFile.ts
src/domain/card/value-objects/CardKey.ts
src/domain/card/value-objects/DeckName.ts
src/domain/card/value-objects/SourceLocation.ts
src/domain/card/services/CardExtractionService.ts
src/domain/card/services/CardRenderingService.ts
src/domain/card/policies/CardIdentityPolicy.ts

src/domain/sync/entities/SyncRecord.ts
src/domain/sync/entities/SyncRegistry.ts
src/domain/sync/services/SyncPlanningService.ts

src/application/use-cases/SyncCurrentFileUseCase.ts
src/application/use-cases/SyncVaultUseCase.ts
src/application/use-cases/ScanAndPlanSyncUseCase.ts
src/application/use-cases/ExecuteSyncPlanUseCase.ts

src/infrastructure/obsidian/ObsidianVaultGateway.ts
src/infrastructure/obsidian/ObsidianMetadataGateway.ts
src/infrastructure/anki/AnkiConnectGateway.ts
src/infrastructure/persistence/DataJsonSyncRegistryRepository.ts

src/presentation/commands/registerCommands.ts
src/presentation/settings/PluginSettingTab.ts
src/presentation/notices/NoticeService.ts
```

## 需要保留和重写的部分

这是从两个旧仓库中提炼出的结论。

## 可以借鉴的方向

### 来自 `AnkiHelperForCoding`

- 聚焦标题级工作流
- 批处理与增量处理思路
- 与 Obsidian 工作流贴近的命令设计

### 来自 `obsidian-to-anki-plugin-forCoding`

- AnkiConnect 通信层思路
- Markdown/链接/媒体/公式转 Anki 的处理经验
- 媒体上传与 deck 创建
- 同步状态管理经验

## 必须重写的部分

- 领域模型
- 卡片解析流程
- 同步计划生成方式
- 配置模型
- 扫描范围模型
- 旧仓库里与通用语法平台强耦合的部分

## 第一版建议做什么

虽然当前阶段不是立即开发，但为了将来回头时不迷失，仍建议记录“第一版的可交付边界”。

### 第一版建议包含

- 标题段落式卡片解析
- `H4` 问答题、`H5` 填空题默认配置
- 标题级别可配置
- `Basic` / `Cloze` 两类卡片
- `qaNoteType` / `clozeNoteType` 可配置
- 默认 deck
- 文件级 `TARGET DECK`
- 全局扫描
- include/exclude 文件夹
- 增量同步
- deck 创建
- note 新增
- note 更新
- 媒体上传
- markdown/html 转换
- Obsidian 回链
- orphan 检测（不自动删）

## 第一版明确不做什么

- 自定义正则系统
- inline note
- begin/end note 语法体系
- folder -> deck 映射
- folder -> tag 映射
- 双向同步
- Anki -> Obsidian 回写
- Python CLI
- 自动删除 orphan 对应 Anki 卡片
- 复杂 glob 系统

## 风险点与尚未完全拍板的问题

虽然方向已经清楚，但仍有一些点需要在未来真正开工前再确认。

## 1. `cardKey` 稳定性

当前推荐方案足以起步，但并不完美。

需要后续根据实际使用情况决定：

- 是否接受标题改名导致新卡
- 是否接受文件移动导致重建
- 是否需要更稳定的内部 source id

## 2. Cloze 标题是否写入字段

当前倾向是：

- Cloze 主字段只放正文
- 标题作为上下文信息另放

但这一点未来仍可在使用体验上再验证。

## 3. orphan 的后续处理策略

当前明确是：

- 先检测
- 先标记
- 不自动删

未来是否要加“手动清理 orphan”，可以再评估。

## 4. 媒体处理边界

第一版建议保留图片和音频支持，但需要注意：

- 不同格式是否都支持
- 文件定位是否稳定
- 上传后是否做重复检测

## 5. 渲染保真度边界

需要明确接受一个现实：

- 不可能一开始就 100% 复刻 Obsidian 显示效果

更现实的目标是：

- 保证常用内容结构可读、可复习
- 保证不轻易破坏数学、代码和媒体

## 未来扩展方向

以下方向可以保留想法，但不应现在就进第一版边界。

### 1. 预览同步计划

在真正同步前，让用户看到：

- 将新增几张
- 将更新几张
- 哪些是 orphan

### 2. 当前标题同步

相较于当前文件同步，进一步细化到只同步当前标题块。

### 3. 手动 orphan 清理

用户明确确认后，删除失效 Anki 卡片。

### 4. 更稳定的 card identity

引入块级 anchor 或内部 source id。

### 5. 更多上下文字段

例如：

- 文件名
- 标题路径
- Obsidian 链接
- 上级标题

## 结论

当前讨论已经形成一个较稳定的产品方向：

- 这是一个新的、聚焦“标题段落式做卡”的 Obsidian -> Anki 插件
- 它借鉴旧项目经验，但不继承旧项目的通用框架定位
- 它明确以 Obsidian 为唯一真源
- 它只做单向同步
- 它保留强同步能力、保留较高内容保真度、保留全局扫描
- 它主动砍掉通用语法平台、folder 映射、Python 旁路、双向同步与自动删除等高复杂度设计

从 DDD 视角看，真正应被认真设计的核心只有三件事：

1. 如何把标题块稳定识别为领域卡片
2. 如何生成尽量稳定的卡片身份
3. 如何在不失控的前提下生成和执行同步计划

只要这三点做对，未来无论是否真的开工，这个插件的方向都不会再轻易漂移。

## 建议的下一步（未来恢复此 idea 时）

当未来决定真正开始做这个插件时，建议按下面顺序继续：

1. 先把 `Card`、`CardDraft`、`SyncRecord` 的精确定义拍板
2. 再拍板 `cardKey` 策略
3. 再定义 `Basic` / `Cloze` 的字段映射策略
4. 再实现 `CardExtractionService`
5. 再实现 `CardRenderingService`
6. 再实现 `SyncPlanningService`
7. 最后接 Obsidian UI 与 AnkiConnect 集成

在真正动手写代码之前，都不要跳过前面三个建模步骤。