From a3938a1536d78f66d469c259ad168b12f2ba5145 Mon Sep 17 00:00:00 2001 From: bottlefish <781230111@qq.com> Date: Tue, 24 Feb 2026 16:18:11 +0800 Subject: [PATCH] =?UTF-8?q?chore(agent):=20=E6=96=B0=E5=A2=9E=20diff-impac?= =?UTF-8?q?t-check=20=E5=91=BD=E4=BB=A4=E4=B8=8E=E6=8A=80=E8=83=BD?= 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/skills/diff-impact-check/SKILL.md | 139 ++++++++++++++++++++++ 2 files changed, 171 insertions(+) create mode 100644 .cursor/COMMAND-diff-impact-check.md create 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 new file mode 100644 index 0000000..47426f7 --- /dev/null +++ b/.cursor/COMMAND-diff-impact-check.md @@ -0,0 +1,32 @@ +# 命令：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/skills/diff-impact-check/SKILL.md b/.cursor/skills/diff-impact-check/SKILL.md new file mode 100644 index 0000000..40837ab --- /dev/null +++ b/.cursor/skills/diff-impact-check/SKILL.md @@ -0,0 +1,139 @@ +--- +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 并传入用户选择的「指定路径」或「全量」即可。