conflict-detector
一个自包含的技能，用于查找一组文档中的矛盾。每个文档被加载（通过路径/内联文本/内联 JSON），提取其事实，然后跨文档规则引擎按规范化键将声明配对并标记不匹配。
强制工作流程
依赖引导（首次使用时）
在首次运行前，检查该技能的运行时依赖：
- 核心：纯标准库——无需安装。
- 可选：
PyYAML（仅在配置/输入为.yaml时需要；JSON 输入仅使用标准库即可工作）。
如果缺少 PyYAML 且输入为 YAML，则告知用户并询问是否要 pip install pyyaml；仅在用户确认后安装。未经明确同意，绝不安装到全局环境中。
- 加载 YAML 配置（以
config/examples/two_docs.yaml为参考）。 - 验证每个
documents[].value/documents[].path是否可达。 - 运行
python -m src.cli run --config <path> [--format json,csv,md]。 - 报告每个级别的冲突数量，并指向用户查看
./conflicts/conflicts_<run_id>.*。
何时使用
- 需要检查两个或多个文档、数据集或提取的事实表之间是否存在矛盾。
- 用户要求“检测冲突”、“发现矛盾”、“交叉核对声明”或询问“这些文档是否一致”。
- 单个声明（一个数字、一个状态、一个命名事实）出现在多个来源中，需要跨来源进行比较。
- 从文档中提取的事实表在使用前需要审核其内部一致性。
使用示例
# 验证配置（快速，不写入报告）
python -m src.cli validate --config config/examples/two_docs.yaml
# 列出配置中解析出的文档来源
python -m src.cli list-docs --config config/examples/two_docs.yaml
# 运行检测；选择输出格式（默认：json）
python -m src.cli run --config config/examples/two_docs.yaml --format json,csv,md
报告会写入 ./conflicts/conflicts_<run_id>.{json,csv,md}；JSON 是机器可读的合同格式。
故障处理
- 配置无效（
validate退出码非零）——修复报告中指出的字段并重新验证；不要手动绕过模式违反。 - 文档来源不可达——运行中止并指明出错的
documents[]条目；检查路径或内联值，然后重试。 - 未发现冲突——有效且可报告的结果（空报告），不是错误；明确说明，而不是重新运行。
- 意外的退出码——逐字报告消息；不要手动比较文档。
检测级别
| 级别 | 类型 | 严重性 | 示例 |
|---|---|---|---|
entity | numeric_mismatch, boolean | 高 | speed = 10 对比 speed = 20 |
clause | categorical | 中 | status = "active" 对比 status = "archived" |
argument | categorical（文本） | 低 | 存在分歧的自由文本行 |
限制
- 提取基于键值对；自由文本段落仅在
argument级别（行级比较）参与。 - 单位规范化通过表驱动（
unit_map）；自定义单位规则必须通过配置提供。