# 核心概念

Canonical page: https://ankiforge.dev/zh-cn/docs/concepts/
Language: zh-CN
Description: 理解 Project、笔记与媒体的所有权、稳定键，以及更新时如何识别原有笔记。

## 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 导入设置、本地编辑和卡片调度仍需客户端验证。参见[更新](https://ankiforge.dev/zh-cn/docs/updates/)和[构建保证](https://ankiforge.dev/zh-cn/docs/build-guarantees/)。