# 模板与 Templater 说明

项目使用 Obsidian 插件 Templater。AI 创建 bible/beat 时需与模板体系兼容。与 Agent 身份与原则见 **`AGENTS.md`**；本文档说明**模板位置、占位符、新建/修改流程**以及 **Bible 可读性与结构**。

---

## 模板位置

| 用途 | 路径 |
|------|------|
| Templater（Obsidian 内） | `kb/template/` |
| AI 创建文件时参考 | `template/`（项目根） |
| 两者内容应同步，**以 `template/` 为源** |

---

## 占位符约定

- **`{{name}}`**：角色名，AI 填充时用上下文角色名。
- **`{{title}}`**：Beat/Eureka 标题，AI 填充时用场景-事件。
- **`{{term_name}}`**：世界观设定名。

Templater 语法对应：`<% await tp.system.prompt("提示", "默认值") %>` 或 `tp.file.title`（以文件名为值）。**AI 创建文件时**：直接替换占位符为实际值，不写入 Templater 标签。

---

## 新建文件流程

- **人类**：命令面板 → `Templater: Create new note from template` → 选模板 → 保存到对应目录。
- **AI**：读取 `template/tpl-*.md`，复制内容，替换 `{{xxx}}` 为实际值，写入 `kb/bible/角色/`、`kb/bible/设定/`、`kb/beats/` 等。

---

## 修改模板时

修改 `template/` 下任意 `tpl-*.md` 后，需**同步到 `kb/template/`**，保证 Obsidian 内 Templater 使用最新版本。

---

## Bible 可读性与结构（自然语言优先）

- **开篇必读**：正文最前用「一句话」+「自然语言介绍」让人和 AI 快速抓意图；假设读者不知道该概念，用 2～5 段连贯文字说明「是什么、在剧情里起什么作用、和谁相关」，用 `[[wikilink]]` 关联角色与设定。
- **详情可折叠**：权威设定（定义、流程、时间线、实体关系网）、待确认/冲突、变更日志/来源索引可放在 Obsidian 折叠块（`> [!abstract]- 标题` 等）中，需要时再展开；或保留在 YAML 中供机器用。
- **模板参考**：新建/大改 bible 时以 `template/tpl-worldbuilding.md`、`template/tpl-character.md` 为参考；两者已同步到 `kb/template/` 供 Templater 使用。