From a174c417df31db990650ec9a5373b2a0e3aeb53b Mon Sep 17 00:00:00 2001 From: bottlefish <781230111@qq.com> Date: Tue, 24 Feb 2026 16:57:55 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E7=A7=BB=E9=99=A4=20diff-impact-check?= =?UTF-8?q?=20=E5=B9=B6=E7=B2=BE=E7=AE=80=20AGENTS=EF=BC=8C=E5=BC=95?= =?UTF-8?q?=E7=94=A8=20kb/template=20README?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Cursor --- .cursor/COMMAND-diff-impact-check.md | 32 ----- .cursor/FLOW-FEISHU-INBOX.md | 67 ----------- .cursor/skills/diff-impact-check/SKILL.md | 139 ---------------------- AGENTS.md | 113 ++---------------- 4 files changed, 13 insertions(+), 338 deletions(-) delete mode 100644 .cursor/COMMAND-diff-impact-check.md delete mode 100644 .cursor/FLOW-FEISHU-INBOX.md delete mode 100644 .cursor/skills/diff-impact-check/SKILL.md diff --git a/.cursor/COMMAND-diff-impact-check.md b/.cursor/COMMAND-diff-impact-check.md deleted file mode 100644 index 47426f7..0000000 --- a/.cursor/COMMAND-diff-impact-check.md +++ /dev/null @@ -1,32 +0,0 @@ -# 命令：Bible/Beat Diff 影响检查 - -在对话或 Composer 中可用下面任一说法触发 **diff 影响检查**（执行 `.cursor/skills/diff-impact-check/SKILL.md`）： - ---- - -## 触发句式 - -- **「检查当前 bible 和 beat 的 diff 影响」** / **「跑一下 diff 影响检查」** -- **「检查这些文件的修改会影响什么：kb/bible/设定/海.md, kb/beats/梦-海边.md」**（指定文件） -- **「全量检查 bible 和 beat 的 diff，给一份影响报告」** - ---- - -## 含义 - -| 说法 | 行为 | -|------|------| -| 不指定文件 / 「全量」 | 对 `kb/bible/`、`kb/beats/` 下所有**有变更**的文件做 diff，沿 wikilink/backlink 查关联，输出《Diff 影响报告》 | -| 指定若干路径 | 仅对这些路径做 diff，再查关联并报告 | - ---- - -## 报告内容概要 - -1. **变更摘要**：哪些文件改了、改了什么性质的内容 -2. **关联范围**：每个变更文件链接了哪些 bible/beat、被哪些引用 -3. **潜在冲突**：与 SSOT 或其他 beat 的事实性矛盾（如「有人见过海」vs「从来没人见过海」） -4. **相关标记**：涉及的 `[#TBD]`、`[#LogicHole]` 等 -5. **建议后续动作**：冲突如何记录或统一口径 - -详见 skill 内《Diff 影响报告》模板。 diff --git a/.cursor/FLOW-FEISHU-INBOX.md b/.cursor/FLOW-FEISHU-INBOX.md deleted file mode 100644 index 8e41b3e..0000000 --- a/.cursor/FLOW-FEISHU-INBOX.md +++ /dev/null @@ -1,67 +0,0 @@ -# 飞书会议记录 → Inbox → Inbox 分析 流程 - -本文描述如何跑通：**飞书会议记录通过飞书/机器人进入 inbox，再走 inbox 分析**。 - ---- - -## 流程总览 - -``` -飞书（会议纪要/文档） → 进入 inbox/ → 执行 inbox 分析（阶段一：分析报告 → 阶段二：执行并归档） -``` - -- **Inbox 分析**：按 `.cursor/skills/inbox-process/SKILL.md` 执行（识别实体、更新/新建 bible 与 beat、归档）。 -- **飞书 → inbox**：有两种方式，见下。 - ---- - -## 方式一：在 Cursor 里用飞书 MCP 拉取到 inbox（推荐先跑通） - -无需在飞书里配置机器人，在 Cursor 对话中完成「拉取 + 分析」。 - -### 步骤 - -1. **把飞书文档拉到 inbox** - - 对 AI 说：**「把飞书文档拉到 inbox」** 或 **「从飞书拉会议记录到 inbox」**，并给出： - - 飞书文档链接（如 `https://xxx.feishu.cn/docx/XXXX` 或 `https://xxx.feishu.cn/wiki/YYYY`），或 - - 文档标题/关键词（由 AI 用 MCP 搜索后选一个）。 - - AI 会使用 **user-lark-mcp** 的 `docx_v1_document_rawContent`（或先 `wiki_v2_space_getNode` 再取正文）拉取正文，写入 `inbox/{文件名}.md`，并在文首注明来源（飞书 docx/wiki）。 - -2. **对刚进 inbox 的文件跑 inbox 分析** - - 对 AI 说：**「对 inbox 的 {文件名} 跑 inbox 分析」** 或 **「处理 inbox / 处理 eureka」**（若只有一个待处理文件）。 - - AI 按 `inbox-process` skill：先做**阶段一（只读分析 + 输出报告）**，等你确认后做**阶段二（更新/新建 bible 与 beat、归档、摘要）**。 - -### 依赖 - -- Cursor 已启用 **user-lark-mcp**，且已配置好飞书应用与 token（用户身份拉 doc 需 useUAT）。 -- 文档链接中的 token：wiki 链接用 `wiki/` 后的节点 token；docx 链接用 `docx/` 后的 `document_id` 调 `docx_v1_document_rawContent`。 - ---- - -## 方式二：飞书机器人自动推到 inbox（后续扩展） - -希望「会议结束或有人分享会议纪要到群」时，自动在仓库里生成 inbox 文件时，可做： - -1. **飞书端** - - 创建自定义应用，开通所需权限（如：云文档读、群消息接收、会议相关事件等）。 - - 机器人订阅事件，例如： - - 群消息中有人发送会议纪要文档链接；或 - - 日历/会议结束后生成纪要 doc，通过 webhook 通知。 -2. **本地/服务器端** - - 提供一个 HTTP 端点（或 GitHub App / 仓库 webhook），接收飞书发来的「文档 link 或 document_id」。 - - 该端点调用飞书 API 拉取文档正文，在仓库中创建 `inbox/{标题或日期}.md`（或先写临时文件再由 Cursor 移动）。 -3. **分析** - - 你打开 Cursor 后对 AI 说「处理 inbox」或指定「对 inbox 的 xxx 跑 inbox 分析」即可。 - -当前 MCP 没有「会议事件」专用接口，机器人方案需要你在飞书开放平台配置事件与 webhook，并与仓库写入方式对接。 - ---- - -## 小结 - -| 阶段 | 做法 | -|----------------|------| -| 飞书 → inbox | **方式一**：在 Cursor 说「把飞书文档/会议记录拉到 inbox」并给链接或关键词，由 AI 用 Lark MCP 拉取并写入 `inbox/`。 | -| Inbox 分析 | 说「对 inbox 的 {文件名} 跑 inbox 分析」或「处理 inbox」，按 `inbox-process` 做分析 → 确认 → 执行并归档。 | - -先按方式一在 Cursor 里跑通一次「拉一条会议记录 → 跑 inbox 分析」，再如需自动化可扩展方式二。 diff --git a/.cursor/skills/diff-impact-check/SKILL.md b/.cursor/skills/diff-impact-check/SKILL.md deleted file mode 100644 index 40837ab..0000000 --- a/.cursor/skills/diff-impact-check/SKILL.md +++ /dev/null @@ -1,139 +0,0 @@ ---- -name: diff-impact-check -description: 检查 bible/beat 的 diff 会产生哪些影响。当用户要「检查修改影响、diff 影响、指定文件/全量 bible beat 的 diff、修改后冲突」时使用。可指定若干文件的 diff，或检查所有 bible 与 beat 的未提交/已暂存变更；沿 wikilink 与 backlink 查关联内容并发现事实性冲突（如一处写「有人见过海」、bible 写「从来没人见过海」或另一 beat 冲突），输出影响报告。 ---- - -# Bible/Beat Diff 影响检查 - -对当前工作区中 **bible** 与 **beat** 的修改（diff）做影响分析：找出因本次修改可能产生的**事实性冲突**与**关联影响**，并生成报告。例如：某 beat 写「有人见过海」，而某 bible 的 SSOT 写「从来没人见过海」；或另一 beat 的 Fiction/reveals 与本次修改矛盾——此类冲突需被检出并列入报告。 - ---- - -## 何时使用 - -- 用户要求：检查**当前修改**对 bible/beat 的影响、diff 影响、冲突检查 -- 用户指定：只检查**某些文件**的 diff，或**所有** bible 与 beat 的 diff -- 提交前希望：确认本次改动不会与既有 SSOT、其他 beat 产生未记录的事实冲突 - ---- - -## 输入约定 - -| 用户说法 | 含义 | -|----------|------| -| 指定文件 | 只对这些路径做 diff 并做影响分析（路径可为 `kb/bible/…`、`kb/beats/…`） | -| 全量 / 所有 bible 和 beat | 对 `kb/bible/` 与 `kb/beats/` 下所有**有变更**的文件做 diff 并做影响分析 | -| 未明确指定 | 视为「全量」：检查 `kb/bible/`、`kb/beats/` 下所有未提交与已暂存的变更 | - ---- - -## 执行流程 - -### 1. 获取 Diff 范围 - -- **指定文件**：只对这些路径执行 `git diff` 与 `git diff --cached`（PowerShell 下路径用英文/相对路径，避免中文参数编码问题；见 powershell-windows-chinese skill）。 -- **全量**：对 `kb/bible/`、`kb/beats/` 执行： - - `git diff -- kb/bible/ kb/beats/` - - `git diff --cached -- kb/bible/ kb/beats/` -- 合并得到「本次受检的变更文件列表」及每个文件的 **+/- 行内容**（新增/删除的表述）。 - -若没有任何变更，直接输出：「当前在 kb/bible 与 kb/beats 下无 diff，无需做影响检查。」 - -### 2. 解析变更并提取「事实性焦点」 - -对每个有变更的文件： - -- 区分是 **bible**（`kb/bible/角色/`、`kb/bible/设定/`）还是 **beat**（`kb/beats/`）。 -- 从 **新增（+）** 与 **删除（-）** 的段落中，提取可能涉及事实的表述（例如 SSOT 中的定义、Fiction 中的情节、reveals 中的揭示），用简短要点归纳（不必逐字，便于后续对比）。 -- 若变更仅限 frontmatter（如日期、tags）、变更日志表、纯格式，可标注为「非事实性」，但仍列入「变更摘要」，关联检查可简化。 - -### 3. 沿关联查找：Wikilink 与 Backlink - -对每个**有事实性变更**的文件： - -- **从该文件出发的链接**：在当前文件内容（优先用修改后的版本，即工作区文件）中找出所有 `[[xxx]]`（含 `[[xxx|显示名]]` 取 `xxx`）。这些 `xxx` 可能是角色名、设定名或 beat 的 id（如 `梦-海边`）。 -- **将 link 名解析为路径**（仅限 kb 内）： - - 若存在 `kb/bible/角色/xxx.md` 或 `kb/bible/设定/xxx.md` 或 `kb/beats/xxx.md`，则视为「关联 bible/beat」。 - - 同一名字可能只存在于角色或设定或 beat 之一，按实际存在的路径为准。 -- **反向引用（backlink）**：在 `kb/` 下搜索包含 `[[当前条目名]]` 的文件。当前条目名 = 文件名去掉 `.md`（如 `回收`、`梦-海边`）。即：哪些 bible/beat 引用了本文件，它们也可能与本次修改产生冲突。 -- 汇总得到「与本文件相关的 bible 与 beat 文件列表」。 - -### 4. 对比并标记潜在冲突 - -对每个变更点与相关文件做**事实性对比**（不做创意裁决，只标出可能冲突）： - -- **与 bible SSOT 冲突**：若本次新增/修改的表述与某关联 bible 的「权威设定 (SSOT)」或「核心定义」等小节中的表述**相反或明显矛盾**（例如「有人见过海」 vs 「从来没人见过海」），记作一条冲突，注明两处引用与路径。 -- **与其它 beat 冲突**：若本次修改与某关联 beat 的 Fiction、summary 或 reveals 中的事实性描述**相反或明显矛盾**，记作一条冲突，注明两处引用与路径。 -- **与同文件内其它段落冲突**：若本次修改导致同一文件内前后表述矛盾，也可记一条「同文件内冲突」。 -- 若某处已有 `[#TBD]`、`[#LogicHole]`、`[#Retcon]` 等标记且与本次修改相关，在报告中「相关标记」小节提及。 - -### 5. 输出《Diff 影响报告》 - -按下面结构输出（可复制为 markdown 使用）： - -```markdown -## Diff 影响报告 - -**范围**：{指定文件列表 | 全量 kb/bible + kb/beats} -**基准**：工作区 vs HEAD（未提交 + 已暂存） - ---- - -### 1. 变更摘要 - -| 文件 | 类型 | 变更性质简述 | -|------|------|----------------| -| kb/bible/设定/回收.md | 设定 | 1.3 强制流程补充「海」检测一句 | -| kb/beats/梦-海边.md | beat | Fiction 增加「见过海」的描写 | - ---- - -### 2. 关联范围（按变更文件） - -- **kb/bible/设定/回收.md** - - 本文件链接到：[[罐头]]、[[原型]]、[[主脑]]、… - - 引用本文件的：kb/beats/梦-回收.md、kb/bible/角色/火山.md、… - -- **kb/beats/梦-海边.md** - - 本文件链接到：[[梦]]、[[姐姐]]、[[路斯]] - - 引用本文件的：kb/bible/设定/梦.md、kb/bible/角色/姐姐.md、… - ---- - -### 3. 潜在冲突 - -| # | 类型 | 位置 A | 表述 A | 位置 B | 表述 B | -|---|------|--------|--------|--------|--------| -| 1 | bible vs 本次 | 回收.md §1.3 | 从未有人见过海（SSOT） | 梦-海边.md Fiction（新增） | 我和姐姐在海边，见过海 | -| 2 | beat vs 本次 | 梦-佩佩画画.md reveals | 玩家得知从没见过海 | 梦-海边.md 修改后 | 见过海 | - -（无冲突时本表为空，并写「未发现事实性冲突。」） - ---- - -### 4. 相关标记 - -- 梦-海边.md 中有 `[#TBD: 海是否可见]`，与本次「海」相关修改有关，建议确认后统一口径。 - ---- - -### 5. 建议后续动作 - -- 若采纳本次修改：请在相关 bible 的「冲突」小节或 SSOT 中二选一/记录两版并注明来源；或修改冲突 beat，并在 changelog 中说明。 -- 若保留原设定：请回退或调整本次 diff 中与 SSOT 矛盾的表述。 -``` - ---- - -## 约束与注意 - -- **只报告、不裁决**：发现冲突只写入报告，不替用户决定以哪边为准；创意决策由人做。 -- **wikilink 为准**：关联以正文中的 `[[…]]` 及 backlink 为准，不依赖 beat 的 `characters`/`terms` 或 bible 的 `related_*` 等 frontmatter 作为权威来源。 -- **路径与编码**：在 Windows/PowerShell 下执行 git 或 grep 时，尽量用相对路径、英文参数，避免中文路径在命令行中的编码问题；必要时可先 `cd` 到仓库根再执行。 -- **无 diff 即无报告**：若指定范围内没有任何变更，只输出简短说明，不生成空报告。 - ---- - -## 若需做成 Cursor 命令 - -可在 Cursor 的 Custom Instructions 或 `.cursor` 下添加一条命令，描述为：「对当前 bible/beat 的 diff 做影响检查；可指定文件或全量。」执行时调用本 skill 并传入用户选择的「指定路径」或「全量」即可。 diff --git a/AGENTS.md b/AGENTS.md index 7d10964..55eba99 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,113 +17,26 @@ ## 目录结构 -``` -kb/ - bible/ - 角色/ # 角色条目 (type: character)，中文文件名 - 设定/ # 世界观/设定条目 (type: worldbuilding)，中文文件名 - beats/ # 每个节拍一个文件（最小叙事单元） - decisions/ # 决策记录 - template/ # Templater 模板（Obsidian 内用） -inbox/ # 输入：eureka、会议记录、点子 - archived/ # 已处理过的 inbox 文件 -template/ # 模板源文件（与 kb/ 同级，AI 参考） -``` - -## Templater 与模板 - -项目使用 Obsidian 插件 Templater。AI 创建 bible/beat 时需与模板体系兼容。 - -### 模板位置 - -| 用途 | 路径 | +| 路径 | 用途 | |------|------| -| Templater（Obsidian 内） | `kb/template/` | -| AI 创建文件时参考 | `template/`（项目根） | -| 两者内容应同步，以 `template/` 为源 | +| `kb/bible/角色/` | 角色条目 (type: character)，中文文件名 | +| `kb/bible/设定/` | 世界观/设定条目 (type: worldbuilding) | +| `kb/beats/` | 每个节拍一个文件（最小叙事单元） | +| `kb/decisions/` | 决策记录 | +| `kb/template/` | Templater 模板（Obsidian 内用） | +| `inbox/`、`inbox/archived/` | 输入与已处理归档 | +| `template/`（项目根） | 模板源文件，**AI 创建文件时参考** | -### 占位符约定 - -- **`{{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 使用。 - -## 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，命名无需重复 +命名与索引等约定见 **`kb/README.md`**；模板、占位符与新建流程见 **`template/README.md`**。 ## Bible 与 Beat 的信息边界 - **Beat 维护**：游戏内的事件信息——在哪个场景发生了什么、玩家经历了什么、什么信息在哪里被揭示。 - **Bible 维护**：事件之外的信息——角色是谁、设定规则、跨叙事的静态事实。 -**推论**： +**索引与新建 Beat**：在来源索引或叙事时间线中遇到需要新建 beat 时，创建新 beat 并设 `status: backlog`（待写稿）；若已有具体 Fiction 草稿则用 `draft`。 -- 叙事时间线留在 bible 作为聚合视图，但内容完全由 beats 驱动；AI 处理 beat 时自动同步，人不手动维护。 -- Bible 里不应出现人工维护的动态/事件性内容。 +## 流程入口（按 skill / 文档执行） -**索引与新建 Beat**：在来源索引或叙事时间线中遇到需要新建 beat 的情况时，创建新 beat 并设 `status: backlog`（待写稿）；若已有具体 Fiction 草稿则用 `draft`。 - -## Bible 来源索引 - -- **正常流程**：经 inbox 流程处理并被 bible 引用的来源，会先归档到 `inbox/archived/`；来源索引中的链接应使用**已归档路径** `[[inbox/archived/文件名]]`，便于跳转原文且与流程一致。 -- 未走归档流程的少数来源（如人工直接创建的 bible）可暂时用 `inbox/xxx` 或注明「未归档」，待后续归档后更新链接。 - -## 处理 Inbox / Eureka - -当被要求处理某个 inbox 文件时，按 **`.cursor/skills/inbox-process/SKILL.md`** 执行全流程（识别实体、更新/新建 bible、Beat→Bible 反向同步、归档、输出摘要）。流程与摘要格式以该 skill 为准。 - -若需将**飞书会议记录/文档**纳入 inbox 再分析：先用 **`.cursor/skills/feishu-to-inbox/SKILL.md`** 通过飞书 MCP 拉取文档到 `inbox/`，再对生成的文件跑 inbox 流程。端到端说明见 **`.cursor/FLOW-FEISHU-INBOX.md`**。 - -## 一致性检查 - -当被要求执行一致性检查时： - -1. **双向对账**：对照各 bible「叙事时间线」与引用该 bible 的 Beats（通过 backlink 或正文 wikilink 可见），逐条检查： - - 表格有行但 beat 不存在 → 保持 `🔹 无Beat` - - beat 存在但表格无行 → 新增行，标 `🆕 仅Beat` - - 双方都有但内容/粒度不一致 → 标 `⚠️ 有出入`，在冲突记录或待确认中说明差异 -2. **Beat → SSOT 反向补全**：检查每个 beat 的 YAML `reveals` 字段，若揭示了角色/设定的事实性信息但 bible SSOT 区未记录，标注待补并列入摘要 -3. 校验角色状态在节拍间是否连续（弧线追踪） -4. 校验世界观设定在各 bible 间是否一致 -5. 校验节拍叙事前置条件是否满足 -6. 汇报所有 `[#TBD]`、`[#Retcon]`、`[#LogicHole]` 项 -7. 检查揭示路径是否与实际节拍顺序一致 - -## Diff 影响检查 - -当被要求检查**当前修改（diff）**对 bible/beat 的影响时，按 **`.cursor/skills/diff-impact-check/SKILL.md`** 执行：获取指定文件或全量 `kb/bible`、`kb/beats` 的 diff，沿 wikilink 与 backlink 查关联内容，对比事实性表述（如 SSOT 与 beat Fiction/reveals），输出《Diff 影响报告》并标出潜在冲突（例如一处写「有人见过海」、bible 写「从来没人见过海」）。可指定检查某些文件的 diff，或检查所有 bible 与 beat 的未提交/已暂存变更。命令说明见 `.cursor/COMMAND-diff-impact-check.md`。 +- **处理 Inbox / Eureka**：按 **`.cursor/skills/inbox-process/SKILL.md`** 执行全流程（识别实体、更新/新建 bible、Beat→Bible 反向同步、归档、输出摘要）。 +- **飞书文档→inbox 再分析**：先用 **`.cursor/skills/feishu-to-inbox/SKILL.md`** 拉取到 `inbox/`，再对生成的文件跑 inbox 流程。端到端见 **`.cursor/FLOW-FEISHU-INBOX.md`**。