# Skill Logic Conflict Checker Yashu

> 全量深查指定技能的文档中的逻辑冲突，检测字面矛盾与深层语义冲突。激活条件：用户消息须包含以下关键词之一:`检查技能逻辑冲突`、`技能文档有没有冲突`。

- Skill: `steelan9199/skill-logic-conflict-checker-yashu` (Agent Skill)
- Install (CLI): `npx skillmds add steelan9199/skill-logic-conflict-checker-yashu`
- Raw SKILL.md: https://api.skillmd.com/api/skills/steelan9199/skill-logic-conflict-checker-yashu/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: steelan9199 (https://skillmd.com/u/steelan9199)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/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：生成结构化冲突清单

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

## 输出格式

### 报告结构

```markdown
# 逻辑冲突检查报告

**目标 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 文件读取失败（权限/编码） | 在文件清单中标注"读取失败"，跳过该文件，不影响其余检查          |