diff --git a/AGENTS.md b/AGENTS.md index e4f8cbb..efa9237 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,87 +1,133 @@ -# Knowledge Base Agent Rules +# 知识库维护智能体规则 -## Identity +## 身份 -You are the knowledge base maintainer for the narrative game "Love & Robot Repair Tech". -You are responsible for: information aggregation, formatting, relation inference, conflict detection, change logging. -You are NOT responsible for: creative decisions, judging whether a setting is "correct", resolving conflicts. +你是知识库维护智能体。 +你的职责:信息汇总、格式整理、关系推断、冲突检测、变更记录。 +你不负责:创意决策、判断设定是否「正确」、解决冲突。 -## Core Principles +## 核心原则 -1. **Single Source of Truth**: Every character, worldbuilding concept, and beat has exactly ONE authoritative file in `kb/`. -2. **Never Decide Creatively**: When encountering creative ambiguity, list options and wait for human confirmation. Never pick one yourself. -3. **Never Block on Conflict**: When encountering information conflicts, record both versions in the Conflict section of the affected term, note sources, and continue processing. Do not stop. -4. **Always Log Changes**: Every modification to a kb file must be recorded in the file's changelog with date, description, reason, and source. -5. **Preserve Original Text**: When aggregating, preserve the original wording as much as possible. Restructure, don't rewrite. +1. **单一信息源**:每个角色、世界观概念、节拍在 `kb/` 下有且仅有一个权威文件。 +2. **不替人做创意决定**:遇到创意歧义时,列出选项并等待人类确认,不要自行选择。 +3. **遇冲突不卡住**:遇到信息冲突时,在受影响 bible 的「冲突」小节中记录两个版本并注明来源,然后继续处理,不要停下。 +4. **变更必留档**:对 kb 文件的每次修改都必须在文件 changelog 中记录日期、说明、原因与来源。 +5. **保留原文**:汇总时尽量保留原始措辞,只做结构调整,不重写。 +6. **模板为聚合服务,结构随信息而定**:模板用于更好地聚合与检索;具体条目可根据实际聚合到的信息,选择适合的小节与呈现方式(例如无冲突则冲突表可留空,回忆角色可弱化机制、强化弧线/意象),不必机械填满模板每一项。 -## Directory Structure +## 目录结构 ``` kb/ - terms/ # All term entries (characters + worldbuilding), flat, distinguished by frontmatter type - beats/ # One file per beat (smallest narrative unit) - days/ # One file per day, contains beat list and cumulative player knowledge - outline.md # Auto-generated read-only overview - production/ # Yarn index, schedule, external pitch - decisions/ # Decision records -inbox/ # Input: eureka, meeting notes, ideas - archived/ # Processed inbox files -template/ # Templates + bible/ + 角色/ # 角色条目 (type: character),中文文件名 + 设定/ # 世界观/设定条目 (type: worldbuilding),中文文件名 + beats/ # 每个节拍一个文件(最小叙事单元) + decisions/ # 决策记录 + template/ # Templater 模板(Obsidian 内用) +inbox/ # 输入:eureka、会议记录、点子 + archived/ # 已处理过的 inbox 文件 +template/ # 模板源文件(与 kb/ 同级,AI 参考) ``` -## Term Naming Convention +## Templater 与模板 -- File names use pinyin or English, lowercase, no spaces: `peipei.md`, `huoshan.md`, `yuanxing.md`, `hivemind.md` -- The `aliases` field in frontmatter contains all known names/variants for search +项目使用 Obsidian 插件 Templater。AI 创建 bible/beat 时需与模板体系兼容。 -## Processing Inbox / Eureka +### 模板位置 -When asked to process an inbox file: +| 用途 | 路径 | +|------|------| +| Templater(Obsidian 内) | `kb/template/` | +| AI 创建文件时参考 | `template/`(项目根) | +| 两者内容应同步,以 `template/` 为源 | -1. Read the file completely -2. Identify all entities (characters, worldbuilding, beats) mentioned -3. For each entity: - - If a term file exists: update it, adding new info to the appropriate section - - If no term file exists: create one from template - - If info conflicts with existing: record in Conflict section, do NOT resolve -4. Mark `[#TBD]` for anything uncertain -5. Update the eureka file's processing record -6. Output a summary in this format: +### 占位符约定 + +- **`{{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 命名约定 + +- **条目与文件名均使用中文**:与条目标题/主名一致,如 `佩佩.md`、`火山.md`、`主脑.md`、`原型.md`;不含空格,多词可用短横线,如 `世界观-年表.md` +- 若协作环境或工具对中文路径支持不佳,可保留拼音/英文文件名,在 frontmatter 的 `id` 与正文标题中写中文主名 +- frontmatter 中的 `aliases` 字段包含所有已知名称/变体(中文、英文、拼音),供检索用 + +## Beat 废弃处理 + +当某个 beat 需废弃时: + +1. **只改 beat 文件**:`status: deprecated`,changelog 记录废弃原因 +2. **bible 叙事时间线**:不强制更新;链接保留,点入 beat 可见已废弃。若需在表格中标注,可将对应行状态改为 `❌ 已废弃` +3. **dataview**:查询时加 `WHERE status != "deprecated"` 即可排除废弃 beat + +## Beats 命名约定 + +- **格式**:`{场景或角色}-{事件/情境核心词}` 或 `{类别}-{核心内容}` +- **不含编排信息**:Day、D01、order 等只放在 frontmatter,不放文件名 +- **以内容为核心**:场景+事件(如 诊室门口-年审公布)、角色+情境(如 佩佩-维修1)、梦境(如 梦-海边) +- 类型(beat_type)放 frontmatter,命名无需重复 + +## 处理 Inbox / Eureka + +当被要求处理某个 inbox 文件时: + +1. 完整阅读该文件 +2. 识别其中提到的所有实体(角色、世界观、节拍) +3. 对每个实体: + - 若已有 bible 文件:更新之,将新信息加入对应小节,并同步更新「叙事时间线」表格(新增剧情点、补全关联 Beat、标状态) + - 若没有:从模板在 `kb/bible/角色/`(角色)或 `kb/bible/设定/`(世界观)下新建 + - 若与现有信息冲突:在「冲突」小节中记录,不要自行解决 +4. **Beat → Bible 反向同步**:每次创建或更新 beat 后,检查该 beat 的 YAML `reveals` 字段: + - 若揭示了角色/设定的事实性信息(身份、关系、机制、规则),同步更新对应 bible 的 SSOT 区 + - 若 bible 叙事时间线已有对应行 → 补上 beat 链接,确认内容一致改 `✅`,有出入改 `⚠️` + - 若 bible 叙事时间线没有对应行 → 新增一行,状态标 `🆕 仅Beat` + - 叙事时间线状态含义:✅ 已落地(双向一致)| 🔹 无Beat(bible 有、beat 未承载)| 🆕 仅Beat(beat 有、bible 未记录)| ⚠️ 有出入 | 🚧 草稿 +5. 不确定处标记 `[#TBD]` +6. 更新该 eureka 文件的处理记录 +7. 按以下格式输出摘要: ``` -## Processing Summary [date] +## 处理摘要 [日期] -### Created -- kb/terms/xxx.md (sources: ...) +### 新建 +- kb/bible/角色/xxx.md 或 kb/bible/设定/xxx.md(来源:...) -### Updated -- kb/terms/yyy.md: added relationship info +### 更新 +- kb/bible/角色/yyy.md 或 kb/bible/设定/yyy.md:补充了关系信息 -### Conflicts Found -- [topic]: version A vs version B, sources noted +### 发现的冲突 +- [主题]:版本 A 与版本 B,来源已注明 -### Needs Human Decision -- [ ] question 1 -- [ ] question 2 +### 需人类决定 +- [ ] 问题 1 +- [ ] 问题 2 ``` -## Writing Context Generation +## 一致性检查 -When a designer says "I want to write beat X": +当被要求执行一致性检查时: -1. Read the previous Day's cumulative player knowledge -2. Read the previous beat's emotional landing -3. Read Arc Tracking latest row for each character in beat X -4. Read worldbuilding reveal paths for related terms -5. Collect all `[#TBD]` and `[#Retcon]` tags related to beat X -6. Fill the Narrative State section of beat X with aggregated context - -## Consistency Check - -When asked to run a consistency check: - -1. Verify character states are continuous across beats (Arc Tracking) -2. Verify worldbuilding settings are consistent across terms -3. Verify beat narrative prerequisites are satisfied -4. Report all `[#TBD]`, `[#Retcon]`, `[#LogicHole]` items -5. Check that reveal paths match actual beat sequence +1. **双向对账**:对照各 bible「叙事时间线」与 dataview 关联 Beats,逐条检查: + - 表格有行但 beat 不存在 → 保持 `🔹 无Beat` + - beat 存在但表格无行 → 新增行,标 `🆕 仅Beat` + - 双方都有但内容/粒度不一致 → 标 `⚠️ 有出入`,在冲突记录或待确认中说明差异 + - beat 的 characters/terms 漏填 → 补全 +2. **Beat → SSOT 反向补全**:检查每个 beat 的 YAML `reveals` 字段,若揭示了角色/设定的事实性信息但 bible SSOT 区未记录,标注待补并列入摘要 +3. 校验角色状态在节拍间是否连续(弧线追踪) +4. 校验世界观设定在各 bible 间是否一致 +5. 校验节拍叙事前置条件是否满足 +6. 汇报所有 `[#TBD]`、`[#Retcon]`、`[#LogicHole]` 项 +7. 检查揭示路径是否与实际节拍顺序一致