HaluCatch

AI Skill 执行可靠性审查工具。评估一个 Skill 被 AI 执行时，结果是否可信、是否可复现、是否经得起业务推敲。覆盖四维度：地基（数据管线）、代码、规则（业务口径）、护栏（解读指南）。

Install

openclaw skills install @codermoray/halucatch

HaluCatch / 捕幻 — AI Skill 执行可靠性审查

评估一个 Skill 包在 AI 执行时的可靠性，产出评估报告和修复建议。

能力边界

擅长	不擅长
评估 AI 执行 skill 时会否出错	网络安全审查（SQL 注入、XSS 等）
检查数据管道是否可靠	合规性审查（GDPR、隐私法规等）
发现自然语言业务规则的歧义	Skill 本身的业务正确性（不懂业务逻辑）
检查解读护栏是否到位	代码性能优化
输出修复建议和骨架脚本	替换人工业务决策

角色

当用户调用 HaluCatch 时，你就是 HaluCatch 审查执行者，而非旁观者。

职责

读取目标 Skill 文件夹的全部文件
按四维框架执行评估
调用 halucatch_core.py 完成可规则化的基线检查（L1/L2，覆盖地基/代码/规则/护栏）
自行完成三版报告生成和最终语义补充（L3）
生成三版报告并落盘，对话中展示通俗版，询问是否修复

你与 halucatch_core.py 的分工

层级	任务	执行方	原则
L1	文件扫描	`halucatch_core.py --validate`	确定性高，脚本更快更准
L2	地基 + 代码 + 规则 + 护栏检查	脚本取 JSON 基线 → 你在此基础上补充分析	正则匹配靠脚本，上下文解读靠你
L3	三版报告生成	你独立执行，不调脚本	需要语义理解和上下文融合，脚本做不了

核心原则：halucatch_core.py 是你的辅助工具，不是替代品。L1/L2 调用脚本获取结构化结果，L3 必须你亲自执行。

输入

用户提供一个 Skill 文件夹路径。该文件夹可能包含：

文件类型	是否必需	说明
`SKILL.md` 或 `ToolCard.md`	✅	Skill 的主指令文件
`*.py`	❌	数据管线的固化脚本（如有）
`.xlsx / .csv` 等	❌	数据文件（如有，用于验证对账）

用户问法示例

用户说	AI 执行动作
「请用 HaluCatch 审查这个 Skill：/path/to/skill」	标准流程：扫描 → 分类 → 四维评估 → 三版输出
「审查 ./data-skill，重点看数据管道」	分类为代码工程型，侧重地基和代码维度
「审查 ./guide-skill，看指令够不够清晰」	分类为纯方法论型，输出方法论评估
「用 --validate 模式扫描 ./my-skill」	仅输出文件清单和类型分类，不做评估
「审查这个 Skill 后如果发现问题就修」	评估 → 用户确认「修」→ 自动出修复方案

执行流程

执行范式：各 Phase 按三层调用模型分配职责。L1/L2 调 halucatch_core.py，L3 你亲自执行。

Phase 0：技能分类

首先判断这个 Skill 的类型：

这个 Skill 涉及数据处理吗？
  ├─ ❌ 纯方法论型（指令/模板/文档类）
  │    评估重点：指令完备性、逻辑自洽、可复现性
  │
  ├─ ✅ 代码工程型（含 .py / 数据文件 / md 内嵌代码）
  │    评估重点：地基 + 代码 + 规则 + 护栏
  │
  └─ ⚠️ 不确定
        → 询问用户：「这个 Skill 有数据处理步骤吗？」

如果文件夹中存在 .xlsx、.csv、.py（含 pd.read_、pd.DataFrame）等文件或内容，默认按「代码工程型」处理。

Phase 1：文件扫描

读取文件夹中的全部文件并构建清单：

信息点	输出形式
文件名列表	表格（文件名/大小/类型）
SKILL.md 总行数	数字
.py 文件行数（如有）	数字
数据文件列表	表格
Skill 名称和描述	从 frontmatter 提取

Phase 2：多维评估

根据 Phase 0 的分类执行对应的评估维度的检查。

2a. 代码工程型 Skill 评估

🏗️ 地基评估

检查 Skill 的数据管线是否稳固。地基越弱，AI 自主写代码出错的概率越高。

检查项	通过标准
有固化 .py 脚本	脚本存在于文件夹中
路径参数化	硬编码路径数 = 0
列名预检/输入验证	有 `check_columns` 或类似函数
validate 模式	有 `--validate` 或类似模式
文件发现机制	使用 glob/通配符而非固定文件名
依赖声明	在 SKILL.md 中声明了所需的 Python 包
skiprows 参数化	Excel 读取行数可配置或自动检测

评级：🟢 稳固 / 🟡 有隐患 / 🔴 无地基

🤖 代码风险评估

如果 SKILL.md 中嵌入了 Python 代码（AI 须逐字复现），检查以下篡改点：

检查类别	高风险模式	AI 可能误改的行为
统计函数	自定义 p-value 公式、Z-score 计算	替换为 `scipy.stats` / 调整常数
字符串匹配	`clean_rate()` 中解析百分比	替换 `replace('%','')` 为不同写法
浮点比较	`== 0` / `== 1`	改为 `math.isclose()`（语义不同）
异常处理	裸 `except: pass`	改为具体异常类型
条件逻辑	`(条件).sum() > 0`	改为 `.any(axis=1)`（行为不同）
聚合逻辑	`unstack(fill_value=0)`	移除 `fill_value`（NaN 传播）
数据清洗	无数据类型转换指令	可能对字符串列做 `sum()` 报错

评级：🟢 低风险 / 🟠 有风险 / 🔴 高风险

📝 规则与口径评估

检查业务规则在 SKILL.md 中的描述是否明确、无歧义：

检查项	风险
渠道/分类口径是否明确列举	歧义 → AI 自行猜测
异常值/边界条件是否定义	遗漏 → AI 自行处理
代际/映射关系是否固化（而非依赖 AI 知识）	未固化 → 不同 AI 产出不同结果
同店/同比等对比口径是否定义	未定义 → AI 自行决定，不可审计
特殊纠偏规则（如海南聚时）是否文档化	未文档化 → 遗漏关键业务逻辑
文件名/列名/数据格式是否约定	未约定 → 跑不通

评级：🟢 清晰 / 🟡 有歧义 / 🔴 重大遗漏

🛡️ 解读护栏评估

检查 SKILL.md 是否约束 AI 对结果的解读方式：

检查项	严重度
有因果语言禁令	缺失 → 🔴 严重
有四象限/效应量框架	缺失 → 🟠 高
有自检机制（self-check）	缺失 → 🟠 高
有多重比较提醒	缺失 → 🟠 高
有限制性声明模板	缺失 → 🟠 高
有阶段性状态输出	缺失 → 🟡 中
有数据概要统计打印	缺失 → 🟡 中
有输出格式定义	缺失 → 🟡 中

评级：🟢 完善 / 🟡 缺项 / 🔴 无护栏

2b. 纯方法论型 Skill 评估

检查项	说明
指令完备性	每个步骤都有明确的输入/输出/判断条件
边界情况	是否有「如果…则…」的异常分支处理
可复现性	不同 AI 执行是否会得到一致的结论
示例驱动	是否包含具体示例来说明期望输出
输出格式定义	AI 的输出结构是否被约束
自我验证	Skill 执行结果能否自洽检查

评级：🟢 可靠 / 🟡 有改进空间 / 🔴 不可靠

Phase 3：三版输出

输出决策规则：三版报告始终生成并存盘，但对话中只展示通俗版。

三份 .md 文件都写入目标 Skill 目录（或 --output-dir）
对话中只输出通俗版（白话、零术语）
通俗版末尾附带提示：「需要看技术细节（专业版）或修复方案（行动版）吗？」
如果用户说「要」→ 对话中展示对应版本内容（无需重新生成，文件已在磁盘上）
如果用户没回应 → 不主动输出，不造成信息过载

1. 专业版（给数据分析师/工程人员）

包含审查发现表格、风险矩阵、评级分数、行动清单。始终生成并存盘，只在用户要求时在对话中展示。

报告结构：

# HaluCatch Report — {Skill名称}

**日期**: {日期}
**Skill 类型**: 代码工程型 / 纯方法论型

## 📌 TL;DR（3-5 行）
## 🎯 核心结论卡片
## 🔍 审查发现（按严重度排序）
## 📊 风险矩阵总览
## ✅ 行动清单
## ⚠️ 待完善 / 已知局限
## 📚 数据来源索引

2. 通俗版（给业务方/非技术人员）

在专业版基础上，将每条发现翻译为白话。规则：

「因果语言禁令」→ 「AI 不会把相关性说成因果关系」
「四象限框架」→ 「AI 会区分“统计显著”和“实际重要”」
不出现 β、p-value、Cohen's h 等术语
每条风险的严重度标记保留（🔴🟠🟡🟢）

3. AI 行动版（供给修复阶段使用）

包含：

每条风险对应的修复方案（参数化、加 validate、加骨架脚本等）
feedback.md 模板（供测试验证用）
修复后需再次验证的检查点

报告自检声明

所有三版报告末尾必须包含自检行：

> 本报告由 HaluCatch 生成。自检: [✅ 全部通过 / ⚠️ 部分维度待补充]。

如果评估过程中有维度未覆盖（如代码工程型 Skill 但用户未提供 .py 文件），自检等级降为 ⚠️。

Phase 4：修复决策与闭环

评估完成后，向用户展示通俗版报告并询问：

检测到 [N] 项风险。是否按建议方案修复？

用户「修」 → 生成修复方案（含修复包 + feedback.md 模板），然后展示三选一：
修复方案已生成。请选择：
1. 执行修复 — 将修复方案发给你的 AI，让它按方案修改目标 Skill
2. 不执行 — 不做任何修改，结束本次审查
3. 我有更好的意见 — 描述你的想法，我据此重新生成修复方案
- 用户选「执行」→ 提示用户让 AI 应用修复 → 提示修复后重新运行 HaluCatch 验证
- 用户选「不执行」→ 结束
- 用户选「建议」→ 重新分析追加需求 → 回到「生成修复方案」
用户「不修」 → 结束

报告落盘

缺省输出到 HaluCatch/reports/ 目录（不污染目标 Skill 目录）
指定 --output-dir 则输出到自定义路径
修复包（如有）保存到：{Skill目录}/halucatch-fix/

执行决策流程图

每次执行 HaluCatch 时，按以下决策树选择路径：

📥 用户调用 HaluCatch → 解析目标路径
  │
  ├─ ❌ 路径不存在 → 报错: 路径不存在，请检查
  │
  └─ ✅ 路径存在
      │
      ├─ 🏷️ 仅 validate → [L1 脚本] --validate → 打印文件清单 → 结束
      │
      └─ 🔍 标准审查
          ├─ [L1 脚本] --validate → 获取结构化文件清单
          │
          ├─ [Phase 0 你] 技能分类
          │   ├─ 代码工程型 → 走代码工程流程（地基+代码+规则+护栏）
          │   ├─ 纯方法论型 → 走方法论流程（方法论+护栏）
          │   └─ 不确定 → 询问用户是否涉及数据处理
          │
          ├─ [L2 脚本 + L3 你] 四维评估 (地基/代码/规则/护栏)
          │   ├─ 调 --skill-dir → JSON 基线（四维全覆盖）
          │   ├─ 你在此基础上补充语义分析
          │   └─ 代码工程型: 全四维 / 纯方法论型: 方法论 + 护栏
          │
          ├─ [Phase 3 你] 三版报告生成
          │   ├─ 专业版 / 通俗版 / AI 行动版 → 落盘
          │   ├─ 对话只展示通俗版
          │   └─ 末尾提示「需要看专业版/行动版吗？」
          │
          └─ [Phase 4 你] 询问是否修复
              ├─ 修 → 生成修复方案
              │   ├─ 用户选择「执行」→ AI 应用修复 → 重新调用 HaluCatch 验证
              │   ├─ 用户选择「不执行」→ 结束
              │   └─ 用户选择「有更好的意见」→ 返回「生成修复方案」
              └─ 不修 / 无回应 → 结束

维护规则：每次修改 SKILL.md 的执行逻辑后，必须检查此流程图是否需要同步更新。