6.7 KiB
6.7 KiB
模板与 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 标签。
summary 写作规范
第一层渐进式读取依赖 frontmatter 的 summary 做相关性过滤，故需统一格式与字数，避免偏流程、偏流水账的描述。
- 字数：不超过 60 字（按字符计，含标点）。
- 结构模板：[身份/定位] + [核心矛盾或功能] + [与主线的关键钩子]
不必机械拆成三句，但需同时覆盖「是谁/是什么」「核心矛盾或功能」「和主线/关键剧情的关系」。 - 避免：只写「发生了 A → 然后 B → 然后 C」的流程梗概；应提炼矛盾、功能、钩子，方便第一层判断是否与当前任务相关。
| 类型 | 侧重 |
|---|---|
| 角色 | 身份/气质 + 核心矛盾或欲望 + 与主线或关键角色的钩子 |
| 设定 | 是什么/功能 + 在剧情中的关键作用或矛盾 + 与主线/核心事件的钩子 |
| 节拍 | 谁/场景 + 核心矛盾或情绪转折 + 对主线或角色弧的关键影响（非流水步骤） |
示例（符合规范）
- 角色·奇琳：「用眼泪给客人调制美酒，眼泪从未为自己而流；东京打工妹气质、努力坚强，过度渴望他人爱与认可。」（身份+矛盾+钩子，约 50 字）
- 设定·罐头：「机体维持生存的综合凝胶，每日必需品；迷梦/特别罐头由记忆制造、激发原型人性，与销赛、戈塔什、暴动线核心相关。」（功能+作用+主线钩子）
反例（偏流程，不宜作 summary）
- 节拍：「火山表达模块崩溃，堆积很多没说出口的话。效率审查司拦住导致紧张。帮助校准情绪处理器，让他自信起来。」 → 可改为强调矛盾与落点，例如：「火山因审查司拦截积压未说之话、表达崩溃；维修中校准情绪处理器，落点振作与自信。」（≤60 字，含谁、矛盾、对角色/主线的影响）
新建或更新 Bible/Beat 时，summary 须满足上述规范；与正文「一句话」一致，但可更压缩以适配 60 字上限。
新建文件流程
- 人类：命令面板 →
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 | 新增「summary 写作规范」：模板「身份/定位+核心矛盾或功能+与主线钩子」、≤60 字、类型侧重与正反例 | 统一第一层渐进式读取的 summary 质量，避免偏流程描述；见项目 CHANGELOG |
| 2026-02-25 | 新增「Beat 叙事信源迁移（fiction_source）」一节 | Beat 职责重定义：叙事 SSOT 随阶段迁移，详见 kb/decisions/2026-02-25-Beat职责重定义与叙事信源迁移 |