steelan9199/skill-logic-conflict-checker-yashu

Skill Logic Conflict Checker — 技能逻辑冲突检查器

功能概述

对指定 Skill 进行全量深查：读取 SKILL.md + 全部 references/ 目录下的 .md 文件，检测字面矛盾与深层语义冲突，输出结构化冲突清单。

环境说明

| 变量 | 含义 | | ------------------- | ----------------------------------------------------------- | | $TARGET_SKILL_DIR | 用户指定的被检查 skill 目录（.trae/skills/<skill-name>/） |

全局前置条件

| 前置条件 | 说明 | | ---------- | ---------------------------------------------------- | | 目标 Skill | $TARGET_SKILL_DIR/SKILL.md 必须存在且可读 | | references | $TARGET_SKILL_DIR/references/ 目录如存在则全量读取 |

触发映射

| 用户输入触发词 | AI 执行动作 | | ----------------------------------------- | ------------------------------------------------- | | "检查技能逻辑冲突" / "技能文档有没有冲突" | 确定目标 skill 后启动全量深查，输出结构化冲突清单 | | "检查文档矛盾" / "逻辑冲突检查" | 同上 |

检查范围与深度

文件覆盖范围

1. 必须读取：$TARGET_SKILL_DIR/SKILL.md
2. 必须读取：$TARGET_SKILL_DIR/references/ 目录下所有 .md 文件（递归遍历子目录）
3. scripts/、config/ 等目录下的非 .md 文件不检查，但在冲突溯源时可作为辅助参考

两维检查深度

维度 1：字面矛盾（Literal Contradiction）

同一条规则、参数、数值在两处或多处文档中表述不一致：

| 检查项 | 说明 | 严重级别 | | --------------- | ----------------------------------------------------------------------------- | -------- | | 数值矛盾 | 同一参数/配置的数字取值不同（如一处写 timeout: 30，另一处写 timeout: 60） | 高 | | 命名/标识矛盾 | 同一事物的名称在不同文档中不一致（如脚本名、API 端点路径、环境变量名） | 高 | | 条件/约束矛盾 | 同一前置条件在一处写"必须"，另一处写"可选"或未提及 | 高 | | 流程步骤矛盾 | 同一操作的步骤顺序在不同文档中不同 | 高 | | 状态/结果矛盾 | 同一操作的预期返回值、输出格式、状态码在不同文档中说法不同 | 中 | | 版本/兼容性矛盾 | 要求的版本号范围不一致（如一处写 >=18，另一处写 >=18.20.8） | 中 | | 措辞不一致 | 对同一概念用了不同的术语且未做等价说明（轻微不一致，不构成严重冲突则降级） | 低 |

维度 2：深层语义冲突（Deep Semantic Conflict）

两条不同规则之间间接互斥，或规则与示例、流程逻辑之间存在自相矛盾：

| 检查项 | 说明 | 严重级别 | | ------------------ | -------------------------------------------------------------------------- | -------- | | 规则互斥 | 规则 A 要求 X，规则 B 隐含禁止 X 或要求 not X，两者无法同时满足 | 高 | | 检查表与示例矛盾 | 文档中声明的检查项/要求，与给出的代码示例、命令示例行为不一致 | 高 | | 流程顺序不合理 | 步骤顺序在逻辑上不可行（如步骤 3 依赖步骤 5 的输出，但步骤 3 在前） | 高 | | 前置条件与行为矛盾 | 声明了前置条件 A，但后续流程中未检查 A 即直接执行依赖 A 的操作 | 高 | | 权限/能力范围矛盾 | 一处声明支持某功能/平台/模式，另一处通过限制条件间接排除了该功能 | 中 | | 全局规则被局部覆盖 | 全局规则声称"所有场景适用"，但某个具体功能的描述违反了该全局规则 | 中 | | 默认值与推荐值矛盾 | 文档声明的默认值在实际示例中使用了不同的值，且无明确说明 | 中 | | 引用链断裂 | 文档引用了不存在的文件、锚点、章节，或引用的目标内容与描述的用途不符 | 中 | | 冗余/重复要求 | 多个规则表达的约束完全相同或高度重叠，但分散在多处，可能导致维护不一致 | 低 | | 隐式假设不一致 | 两处文档对同一场景的隐式假设不同（如一处假设用户已登录，另一处未做此假设） | 低 |

执行流程

步骤 1：确定目标 Skill

1. 从用户输入中提取 skill 名称
2. 定位 $TARGET_SKILL_DIR 为 .trae/skills/<skill-name>/
3. 若目录不存在或缺少 SKILL.md，提示用户并终止

步骤 2：全量读取文档

1. 读取 SKILL.md 全文
2. 使用 Glob 发现 references/ 下所有 .md 文件
3. 逐个读取所有 references 文件全文
4. 记录文件清单（文件名、行数），作为报告附录

步骤 3：字面矛盾检测

对每一对文档（包括 SKILL.md 与 references、references 之间），检测：

• 是否出现相同的关键数值但值不同
• 是否出现相同的术语/标识但定义不同
• 是否出现相同的操作/流程但步骤描述不同

方法：从文档中提取关键实体（数值、参数名、端点、步骤序号、约束条件），逐对比较。

步骤 4：深层语义冲突检测

对所有文档进行整体分析：

• 提取所有显式规则/约束/要求，两两比较是否存在互斥
• 将代码示例/命令示例与文字描述对照，检查行为一致性
• 分析流程步骤的前置依赖，检查顺序合理性
• 检查引用目标是否存在且内容匹配
• 检查全局声明是否被局部规则违反

方法：构建"规则清单 → 规则关联图 → 矛盾推理"三步管线。

步骤 5：生成结构化冲突清单

输出完整报告（格式见下方）。

输出格式

报告结构

# 逻辑冲突检查报告

**目标 Skill**：{skill-name}
**检查时间**：{timestamp}
**覆盖文件**：{N} 个（SKILL.md + {M} 个 references）

---

## 一、总览

| 严重级别 | 数量 |
| -------- | ---- |
| 高       | X    |
| 中       | Y    |
| 低       | Z    |
| **合计** | N    |

---

## 二、字面矛盾

### [高] 冲突标题（简短概括）

- **涉及文档**：`文件A.md#L10-L15` vs `文件B.md#L20-L25`
- **冲突描述**：（一句话说明矛盾点）
- **原文 A**：
  > 引用原文关键句
- **原文 B**：
  > 引用原文关键句
- **建议**：（提出统一方案）

---（每项冲突以此格式重复）

## 三、深层语义冲突

### [高] 冲突标题（简短概括）

- **涉及文档**：`文件A.md#L10-L15` vs `文件B.md#L20-L25`
- **冲突类型**：规则互斥 / 检查表与示例矛盾 / 流程顺序不合理 / 前置条件缺失 / ...
- **冲突描述**：（详细说明为何构成冲突）
- **原文 A**：
  > 引用原文关键句
- **原文 B**：
  > 引用原文关键句
- **推理过程**：（说明从 A + B 如何推出矛盾）
- **建议**：（提出修正方案）

---（每项冲突以此格式重复）

---

## 附录：文件清单

| 序号 | 文件路径（相对 `$TARGET_SKILL_DIR`） | 行数 |
| ---- | ------------------------------------ | ---- |
| 1    | SKILL.md                             | XXX  |
| 2    | references/xxx.md                    | XXX  |
| ...  | ...                                  | ...  |

输出位置

直接输出到对话中，不写入文件。

使用示例

用户：检查 skill-tester 的文档有没有逻辑冲突
AI：
  1. 定位 .trae/skills/skill-tester/
  2. 读取 SKILL.md（218 行）
  3. 发现 references/ 下 5 个文件，逐个读取
  4. 执行字面矛盾检测 + 深层语义冲突检测
  5. 输出结构化冲突清单

全局规则

| 规则 | 说明 | | ------------ | -------------------------------------------------------- | | 全量读取 | references/ 下所有 .md 文件必须逐一读取，不得抽样 | | 不修改文档 | 本 skill 仅做检查分析，禁止直接修改被检查的文档 | | 证据先行 | 每一项冲突必须附原文引用，不得凭空断言 | | 逐对比较 | 字面矛盾检测须对所有文档对（pairwise）进行，不得遗漏组合 | | 严重级别准确 | 严格按上述检查项的严重级别分类，不得随意升降级 |

全局错误处理

| 场景 | 处理方式 | | --------------------------------------- | --------------------------------------------------------------- | | $TARGET_SKILL_DIR 不存在 | 提示用户 skill 不存在，列出 .trae/skills/ 下可用 skill 供选择 | | $TARGET_SKILL_DIR/SKILL.md 不存在 | 提示该目录不是有效 skill，终止检查 | | references/ 目录不存在 | 仅检查 SKILL.md，在报告中注明"无 references 目录" | | references 下无 .md 文件 | 仅检查 SKILL.md，在报告中注明"references 目录下无 .md 文件" | | 某 references 文件读取失败（权限/编码） | 在文件清单中标注"读取失败"，跳过该文件，不影响其余检查 |