bottlefishandCursor
5eb576777f
- 引入 fiction_source 字段，叙事 SSOT 随阶段迁移 (short-fiction → flow → full-fiction → yarn) - 模板与 README 增加信源说明与四阶段约定 - 火山-维修1 示范指向 Yarn 的骨架形态 - 决策记录归档讨论与 changelog：kb/decisions/2026-02-25-Beat职责重定义与叙事信源迁移.md Co-authored-by: Cursor <cursoragent@cursor.com>
81 lines
4.4 KiB
Markdown
81 lines
4.4 KiB
Markdown
# 模板与 Templater 说明
|
||
|
||
项目使用 Obsidian 插件 Templater。AI 创建 bible/beat 时需与模板体系兼容。与 Agent 身份与原则见 **`AGENTS.md`**；本文档说明**模板位置、占位符、新建/修改流程**以及 **Bible 可读性与结构**。
|
||
|
||
---
|
||
|
||
## 模板位置
|
||
|
||
| 用途 | 路径 |
|
||
|------|------|
|
||
| Templater（Obsidian 内） | `kb/template/` |
|
||
| AI 创建文件时参考 | `template/`（项目根） |
|
||
| 两者内容应同步，**以 `template/` 为源** |
|
||
|
||
| 模板 | 用途 |
|
||
|------|------|
|
||
| `tpl-character.md` | 角色 Bible；底部含「关联提案」Dataview |
|
||
| `tpl-beat.md` | 节拍 Beat；底部含「关联提案」Dataview |
|
||
| `tpl-worldbuilding.md` | 设定 Bible；底部含「关联提案」Dataview |
|
||
| `tpl-proposal.md` | 提案文档，保存到 `proposals/P-xxx_标题.md`（项目根） |
|
||
|
||
---
|
||
|
||
## 占位符约定
|
||
|
||
- **`{{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 使用最新版本。
|
||
|
||
---
|
||
|
||
## Beat 叙事信源迁移（fiction_source）
|
||
|
||
Beat 的叙事 SSOT 不是永远写在 Fiction 区——它随开发阶段迁移。`fiction_source` 字段标记当前信源位置，Fiction 区的详略随之变化。
|
||
|
||
| 阶段 | fiction_source | Fiction 区写什么 | 典型 dev_status |
|
||
|------|---------------|-----------------|----------------|
|
||
| **short-fiction** | `self` | 几段简要叙事，即 SSOT 本体 | fiction |
|
||
| **flow** | `self` 或外部路径 | 流程/步骤/机制描述；若独立成文档则指向它 | prototype |
|
||
| **full-fiction** | `self` | 完整剧本级 fiction，即 SSOT 本体 | fiction |
|
||
| **yarn** | Yarn 文件夹路径 | **叙事骨架**（几句话概括流程），完整内容见 Yarn | playable / function / close |
|
||
|
||
**规则**：
|
||
- `fiction_source: self`（默认）：Fiction 区就是叙事 SSOT，直接在里面写。
|
||
- `fiction_source: 外部路径`：叙事 SSOT 已迁移到外部，Fiction 区只保留骨架摘要 + 指向外部的链接。不要在 Fiction 区维护与外部重复的详细内容。
|
||
- **Beat 始终维护 Yarn 做不到的东西**：summary、reveals、emotional_tone、player_feels、characters、terms、变更日志。这些元数据无论信源在哪个阶段都由 Beat 独家负责。
|
||
- 工程文档（功能需求、设计优化、Yarn command 说明等）跟 Yarn 放一起，不搬进 kb。
|
||
- 信源迁移时在变更日志中记录。
|
||
|
||
---
|
||
|
||
## Bible 可读性与结构（自然语言优先）
|
||
|
||
- **开篇必读**：正文最前用「一句话」+「自然语言介绍」让人和 AI 快速抓意图；假设读者不知道该概念，用 2～5 段连贯文字说明「是什么、在剧情里起什么作用、和谁相关」，用 `[[wikilink]]` 关联角色与设定。
|
||
- **自然语言介绍与 SSOT 同步**：每当 SSOT 发生重大变更（如核心矛盾、身份、生死状态变化）时，必须检查并重写「自然语言介绍」，避免介绍过时。
|
||
- **详情可折叠**：权威设定（定义、流程、时间线、实体关系网）、待确认/冲突、变更日志/来源索引可放在 Obsidian 折叠块（`> [!abstract]- 标题` 等）中，需要时再展开；或保留在 YAML 中供机器用。
|
||
- **模板参考**：新建/大改 bible 时以 `template/tpl-worldbuilding.md`、`template/tpl-character.md` 为参考；新建提案时以 `template/tpl-proposal.md` 为参考。上述模板已同步到 `kb/template/` 供 Templater 使用。
|
||
|
||
---
|
||
|
||
## 变更日志
|
||
|
||
| 日期 | 变更内容 | 决策理由 / 来源 |
|
||
|------|---------|-----------------|
|
||
| 2026-02-25 | 新增「Beat 叙事信源迁移（fiction_source）」一节 | Beat 职责重定义：叙事 SSOT 随阶段迁移，详见 [[kb/decisions/2026-02-25-Beat职责重定义与叙事信源迁移]] |
|