docs: 项目说明与 Templater 使用文档
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Cursor
@@ -0,0 +1,67 @@
|
|||||||
|
# Capture 项目现状 · 一页纸（供 Agent 协作）
|
||||||
|
|
||||||
|
**更新**：2025-02-24
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 项目是什么
|
||||||
|
|
||||||
|
- **叙事/世界观知识库**：为某叙事项目（含角色、设定、节拍/剧情单元）维护单一信息源（SSOT），支持 Obsidian 浏览与 Dataview 查询。
|
||||||
|
- **Agent 角色**：知识库维护智能体——负责**信息汇总、格式整理、关系推断、冲突检测、变更记录**；**不负责**创意决策、判断设定对错、解决冲突。
|
||||||
|
- **规则文件**：`AGENTS.md`（必读，含目录结构、Templater、命名、Inbox 处理、一致性检查）。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 目录结构（简要）
|
||||||
|
|
||||||
|
| 路径 | 用途 |
|
||||||
|
|------|------|
|
||||||
|
| `kb/bible/角色/` | 角色条目，中文文件名，如 `佩佩.md`、`火山.md` |
|
||||||
|
| `kb/bible/设定/` | 世界观/设定条目，如 `主脑.md`、`原型.md`、`梦.md` |
|
||||||
|
| `kb/beats/` | 节拍（最小叙事单元），命名：`场景-事件` 或 `角色-情境` |
|
||||||
|
| `kb/decisions/` | 决策记录 |
|
||||||
|
| `kb/template/` | Obsidian Templater 模板（与 `template/` 同步） |
|
||||||
|
| `template/` | 模板源文件，**AI 新建文件时读这里**，占位符 `{{name}}`、`{{title}}`、`{{term_name}}` |
|
||||||
|
| `inbox/` | 输入：eureka、会议记录、点子；处理后可归档到 `inbox/archived/` |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 核心约定（其他 Agent 须知）
|
||||||
|
|
||||||
|
1. **单一信息源**：每个角色/设定/节拍在 `kb/` 下仅有一个权威文件。
|
||||||
|
2. **遇冲突不卡住**：在 bible 的「冲突」小节记录两版+来源，不自行解决。
|
||||||
|
3. **变更必留档**：改 kb 文件必须写 changelog（日期、说明、原因、来源）。
|
||||||
|
4. **Bible 命名**：中文主名，如 `佩佩.md`、`世界观-年表.md`；`aliases` 放所有名称变体。
|
||||||
|
5. **Beat 命名**：内容向，如 `诊室门口-年审公布`、`梦-海边`；不含 Day/order 等编排信息。
|
||||||
|
6. **模板同步**：改 `template/*.md` 后需同步到 `kb/template/`。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 当前数据规模（约）
|
||||||
|
|
||||||
|
- **角色 bible**：约 16 个（佩佩、火山、英理、石头、奇琳、姐姐、戈塔什、主脑相关等）。
|
||||||
|
- **设定 bible**：约 24 个（主脑、原型、梦、回收、幸福市、伊甸计划、年表等）。
|
||||||
|
- **Beats**：约 32 个（维修线、梦线、诊室/地铁/酒吧等场景）。
|
||||||
|
- **模板**：`tpl-character`、`tpl-worldbuilding`、`tpl-beat`、`tpl-day`、`tpl-eureka`、`tpl-outline`、`tpl-decision`。
|
||||||
|
- **辅助**：`kb/inbox-info-map.md` 为 inbox 文档与实体的交叉索引。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Inbox / Git 状态（简要）
|
||||||
|
|
||||||
|
- **已修改**：`AGENTS.md`，部分 inbox 文件（如 2月脑暴、姐姐和梦境等），以及 `template/` 下多个 tpl-*.md。
|
||||||
|
- **未跟踪**：`TEMPLATER.md`，若干新 inbox（如 回收-陈子钦、宇航员、落地全剧情、签约全剧情等），以及 `kb/` 目录。
|
||||||
|
- 处理 inbox 时按 `AGENTS.md`「处理 Inbox / Eureka」流程：读全文 → 更新/新建 bible → 冲突记入「冲突」→ Beat 与叙事时间线双向同步 → 输出处理摘要。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 与其他 Agent 协作要点
|
||||||
|
|
||||||
|
- **做创意/剧情决策**：请交给人类或负责创意的 agent；本库只记录与整理。
|
||||||
|
- **新建 bible/beat**：从 `template/tpl-*.md` 复制，替换 `{{xxx}}` 为实际值，写入 `kb/bible/角色|设定/` 或 `kb/beats/`；不要写 Templater 标签。
|
||||||
|
- **一致性检查**：按 `AGENTS.md`「一致性检查」执行双向对账、reveals 反补、弧线与设定校验，并汇报 `[#TBD]` / `[#Retcon]` / `[#LogicHole]`。
|
||||||
|
- **叙事时间线状态**：✅ 已落地 | 🔹 无Beat | 🆕 仅Beat | ⚠️ 有出入 | 🚧 草稿；废弃 beat 只改 `status: deprecated` 并写 changelog。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*详细规则与流程见 `AGENTS.md`；Templater 用法见 `TEMPLATER.md`。*
|
||||||
@@ -0,0 +1,63 @@
|
|||||||
|
# Templater 使用指南
|
||||||
|
|
||||||
|
[Templater](https://silentvoid13.github.io/Templater/) 是 Obsidian 的模板插件，支持在模板中插入变量、执行 JavaScript，实现自动化创建笔记。
|
||||||
|
|
||||||
|
## 1. 初次配置
|
||||||
|
|
||||||
|
已在 `kb/.obsidian/plugins/templater-obsidian/data.json` 中预设模板文件夹为 `template`。
|
||||||
|
|
||||||
|
1. 打开 Obsidian（以 `kb/` 为 vault）→ **设置** → **Templater**
|
||||||
|
2. 确认 **模板文件夹位置** 为 `template`（即 `kb/template/`，相对 vault 根目录）
|
||||||
|
3. 若显示为空，请手动填入 `template` 并保存
|
||||||
|
4. （可选）勾选「在新标签页中打开新创建的笔记」
|
||||||
|
|
||||||
|
## 2. 基本用法
|
||||||
|
|
||||||
|
### 从模板创建新笔记
|
||||||
|
|
||||||
|
- **方式 A**：命令面板（`Ctrl/Cmd + P`）→ 输入 `Templater: Create new note from template` → 选择模板 → 选择存放位置
|
||||||
|
- **方式 B**：为常用模板设置快捷键（设置 → 热键 → 搜索 Templater）
|
||||||
|
|
||||||
|
### 在现有文件中插入模板
|
||||||
|
|
||||||
|
- 命令面板 → `Templater: Insert template`
|
||||||
|
- 或在编辑器中输入 `<%` 触发内联 Templater 命令
|
||||||
|
|
||||||
|
## 3. 常用语法速查
|
||||||
|
|
||||||
|
| 语法 | 含义 |
|
||||||
|
|------|------|
|
||||||
|
| `<% tp.file.title %>` | 当前文件名（无扩展名） |
|
||||||
|
| `<% tp.file.creation_date("YYYY-MM-DD") %>` | 创建日期 |
|
||||||
|
| `<% tp.date.now("YYYY-MM-DD") %>` | 今天日期 |
|
||||||
|
| `<% tp.file.cursor() %>` | 插入后光标跳转到此处 |
|
||||||
|
| `<% await tp.system.prompt("输入角色名", "佩佩") %>` | 弹窗让用户输入 |
|
||||||
|
| `<%* // 代码块，不输出内容 %>` | 执行 JavaScript，无输出 |
|
||||||
|
|
||||||
|
### 与项目模板的对应关系
|
||||||
|
|
||||||
|
项目模板用 `{{name}}`、`{{title}}` 等占位符，Templater 可用以下替换：
|
||||||
|
|
||||||
|
| 占位符 | Templater 写法 |
|
||||||
|
|--------|----------------|
|
||||||
|
| `{{name}}` | `<% await tp.system.prompt("角色名称", "") %>` 或 `tp.file.title` |
|
||||||
|
| `{{title}}` | `<% await tp.system.prompt("Beat 标题", "") %>` 或 `tp.file.title` |
|
||||||
|
| `{{term_name}}` | `<% await tp.system.prompt("设定名称", "") %>` 或 `tp.file.title` |
|
||||||
|
|
||||||
|
## 4. 模板文件位置
|
||||||
|
|
||||||
|
- **Obsidian 内使用**：`kb/template/`（vault 内，Templater 可访问）
|
||||||
|
- **项目根目录**：`template/`（与 `kb/` 同级，AI 创建文件时参考）
|
||||||
|
|
||||||
|
两份内容应保持一致，修改时请同步更新。
|
||||||
|
|
||||||
|
## 5. 推荐工作流
|
||||||
|
|
||||||
|
- **新建角色**：`Templater: Create new note from template` → 选 `tpl-character.md` → 保存到 `kb/bible/角色/xxx.md`
|
||||||
|
- **新建 Beat**：同上 → 选 `tpl-beat.md` → 保存到 `kb/beats/场景-事件.md`
|
||||||
|
- **新建 Eureka**：选 `tpl-eureka.md` → 保存到 `inbox/xxx.md`
|
||||||
|
|
||||||
|
## 6. 官方文档
|
||||||
|
|
||||||
|
- [Templater 官方文档](https://silentvoid13.github.io/Templater/)
|
||||||
|
- [内置变量与函数](https://silentvoid13.github.io/Templater/Internal%20Variables/Internal%20Variables/)
|
||||||
Reference in New Issue
Block a user