核心概念

Project 与笔记

一个 Project 表示一次具有稳定命名空间的发布。它可以把笔记放入多个 Anki 牌组：default_deck 提供默认目标，Note::deck 覆盖该目标。牌组是输出的去处，并非另一层内容编写、媒体或构建容器。

Note 携带其模型和内容。project.add(key, note) 分配必填的稳定源记录键，并原子地收集依赖。重复键、未知字段、模型或媒体冲突会使操作失败，不会留下部分添加的状态。项目命名空间和记录键必须在编辑及源数据重新排序后保持不变。显示名称和文本不是身份键。

模型、字段与模板

NoteType::builder(key) 收集声明；.build() 校验后返回可共享的不可变模型。model.note() 创建持有该模型的笔记。内置 Basic、Cloze 和图片遮挡笔记自带模型。

字段和模板有稳定键与可选的显示名称。编写模板时使用字段键，例如 {{front}}，即使 Anki 显示名称为 正面。模型完成时会校验并编译引用，包括条件区块、过滤器、Cloze 和浏览器模板。赋值也使用键，不会猜测键或回退到显示名称。

文本与 HTML

在 Basic、Cloze 和自定义笔记中，普通字符串始终表示 Text。Text 会转义 HTML；Content::html 用于有意加入标记。{{c1::answer}} 等 Cloze 语法在 Text 中保留，但这不会使嵌入 HTML 自动成为可信标记。Content::sequence 把文本、HTML、图片和声音组合成一个字段。

类型化的图片与声音内容会保留媒体依赖直至导出。添加内容前不要把媒体渲染成字符串，除非也为手写的 HTML、CSS 或脚本显式声明了该资源。

媒体所有权

Media 持有媒体数据的不可变快照，并管理其生命周期；导出文件名由内容确定。只有在预算范围内完成读取与校验后，导入才会成功；之后源文件可以改变或消失。克隆共享存储，可用于多个项目。with_export_name 选择固定且可移植的文件名，不会改变已有克隆或内容节点。

类型化引用自动收集媒体。模型或项目上显式声明的资源，即使静态分析无法识别用途，也会被包含。库不会从任意 HTML 或脚本中自动发现文件内容。

构建与更新

成功构建返回保证包含 APKG 的输出对象。报告只包含观察结果；快照是 JSON 数据，不拥有文件。临时产物只有在至少一个产物所有者仍存在时才保持有效。

更新使用上一次原始分发 APKG 内嵌的完整证据。独立比较将发现项与发布策略分开。高风险发现项默认阻止更新；硬错误不能被放行。Anki 导入设置、本地编辑和卡片调度仍需客户端验证。参见更新和构建保证。