chore(agent): 新增 diff-impact-check 命令与技能
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Cursor
@@ -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 影响报告》模板。
|
||||
@@ -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 并传入用户选择的「指定路径」或「全量」即可。
|
||||
Reference in New Issue
Block a user