Evaluates the reliability of AI Skill execution. Assesses whether a Skill's output is trustworthy, reproducible, and withstands business scrutiny when execut...
SKILL.md

---
name: halucatch
description: |
  Evaluates the reliability of AI Skill execution. Assesses whether a Skill's output is trustworthy, reproducible, and withstands business scrutiny when executed by an AI agent. Covers four dimensions: data pipeline integrity, code risk, business logic ambiguity, and interpretation guardrails. Use when auditing an AI Skill, checking for hallucinations or unreliable outputs, verifying execution reproducibility, or reviewing a Skill's safety before deployment or sharing.
summary: AI Skill 执行可靠性审查工具。评估一个 Skill 被 AI 执行时，结果是否可信、是否可复现、是否经得起业务推敲。覆盖四维度：地基（数据管线）、代码、规则（业务口径）、护栏（解读指南）。
license: MIT
allowed-tools:
  - Read
  - Write
  - Bash
compatibility: Requires Python 3.8+; Bash only for local 'python3 halucatch_core.py', no network/arbitrary commands
author: CoderMoray
version: 1.8.8
metadata:
  hermes:
    tags:
    - skill-audit
    - reliability
    - engineering-assurance
    - Skill审查
    - 工程质量
    - 可靠性
  openclaw:
    requires:
      bins:
      - python3
    emoji: 🔍
    homepage: https://github.com/CoderMoray/HaluCatch
slug: halucatch
displayName: HaluCatch / 捕幻
tags:
  - skill-audit
  - reliability
  - engineering-assurance
  - Skill审查
  - 工程质量
  - 可靠性
---
> **一句话总结**：把一个 AI Skill 的文件夹扔给 HaluCatch，它会逐项检查数据管线、代码逻辑、业务规则、安全护栏有没有漏洞，然后给你三份报告（标准版看全貌、专业版看细节、行动版直接修），全程几秒钟、完全离线。
>
> [快速开始](#1-入口逻辑) · [能力边界](#能力边界) · [输出解读](#5-报告)

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

评估一个 Skill 包在 AI 执行时的可靠性，产出评估报告和修复建议（建议需用户确认后才执行，不自动修改目标 Skill）。

---

## 能力边界

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

**硬件限制：** 单文件上限 10 MB（超大文件会被跳过并提示），不支持批量审查（一次一个目录），不支持二进制文件，不建立网络连接（仅通过本地 Python 脚本运行）。审查耗时取决于目录下文件数量和大小，通常几秒到几十秒。

---

## 角色

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

### 职责

- 调用 `halucatch_core.py` **一次性完成全流程**（L1 扫描 + L2 评估 + L3 报告生成）
- 读取脚本生成的报告文件，对话中展示标准版，询问是否修复
- 在脚本报告基础上做语义补充：按需读取报告中引用的源文件，提供上下文分析（`info` 级别条目）
- **不要自己读取目标目录的文件**——文件扫描由脚本完成，AI 读取只会浪费 token

### 你与 halucatch_core.py 的分工

| 层级 | 任务 | 执行方 | 原则 |
|------|------|--------|------|
| **L1** | 文件扫描 | `halucatch_core.py --validate` | 确定性高，脚本更快更准 |
| **L2** | 地基 + 代码 + 规则 + 护栏检查 | 脚本取 JSON 基线 → **你在此基础上补充分析** | 正则匹配靠脚本，上下文解读靠你 |
| **L3** | 三版报告生成 | `halucatch_core.py` **生成并落盘**，你读取后展示给用户 | `reporter.py` 确定性高、格式一致、零幻觉——你只需做语义补充 |

> **核心原则**：`halucatch_core.py` 涵盖全流程——L1 扫描、L2 评估、L3 报告生成一次性完成。你只需读取脚本生成的报告并展示给用户。不再由 AI 独立编写报告正文。

## 权限与安全边界

**⚠️ 写入警告：HaluCatch 会生成报告文件写入目标目录的 `reports/` 子目录，并可能产出修复指引（需用户确认后才应用）。这不是纯只读工具。**

HaluCatch 仅需要以下权限即可运行：

| 操作 | 需要 | 说明 |
|------|------|------|
| 读取目标 Skill 目录 | Read | 递归读取全部文件 |
| 写入报告文件 | Write | 仅写入目标目录内的 `reports/` 子目录，不修改 Skill 源文件 |
| 执行 Python 脚本 | Bash | 仅执行本地 `halucatch_core.py`，不访问网络、不执行外部命令 |

**安全约束**：HaluCatch 不会访问目标目录以外的任何路径，不会发起网络连接。Bash 权限仅用于运行自带的 Python 审查脚本，不会执行非本项目代码。审查前必须由用户显式指定目标路径。

---

## 输入

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

| 文件类型 | 是否必需 | 说明 |
|---------|---------|------|
| `SKILL.md` | ✅ | Skill 的主指令文件 |
| `manifest.json` 或 `config.yaml` | ❌ | Skill 配置文件（含版本号等） |
| `*.py` | ❌ | 数据管线的固化脚本（如有） |
| `*.xlsx / *.csv` 等 | ❌ | 数据文件（如有，用于验证对账） |

### 数据要求

- **时效性**：审查基于目标 Skill 目录的即时快照，不追溯历史版本。
- **数据范围**：仅评估目标目录中可见的文件，不爬取外部依赖或网络资源。

### 前提假设

- 目标目录存在且有读取权限。
- 目标 Skill 应包含至少一个 `SKILL.md` 文件（规范名称）。如有其他 `.md` 文件，AI 将尝试启发式匹配，但会报告规范性问题。
- 目录中的 `.py` 文件视为 Skill 核心执行脚本，非第三方依赖库。

## AI 执行指南

### 语言自动检测

AI 在加载本 Skill 时，应从系统提示（`<response_language>`）或对话上下文判断用户语言，然后自动添加 `--lang` 参数：

| 用户语言 | 参数 | 示例 |
|-----------|------|------|
| 中文（简体/繁体） | `--lang zh-CN` | `python3 halucatch_core.py --skill-dir <path> --lang zh-CN` |
| 英文 | `--lang en` | `python3 halucatch_core.py --skill-dir <path> --lang en` |
| 不确定 | 不添加（默认 `auto`，自动检测系统 locale） | `python3 halucatch_core.py --skill-dir <path>` |

**原则**：AI 肯定知道用户用什么语言，不需要用户手动配置。

### 基本用法

```bash
# 为中文用户审查
python3 halucatch_core.py --skill-dir /path/to/skill --lang zh-CN

# 为英文用户审查
python3 halucatch_core.py --skill-dir /path/to/skill --lang en

# 自动检测（fallback）
python3 halucatch_core.py --skill-dir /path/to/skill
```

---

## 执行流程

> **执行范式**：各 Phase 按三层调用模型分配职责。`halucatch_core.py` 一次性完成 L1/L2/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 执行结果能否自洽检查 |

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

---

> ⚠️ **执行前确认**：在开始扫描文件、运行 `halucatch_core.py`、或生成报告之前，必须先向用户确认目标路径无误，并告知即将执行的操作（读取目标目录文件、运行本地脚本、生成报告到 reports/ 目录）。未明确确认前不得执行任何读写操作。

### Phase 3：三版输出

**核心变更**：报告由 `halucatch_core.py`（`reporter.py`）自动生成，你**不再需要独立撰写报告正文**。你只负责：
1. 读取脚本生成的报告文件
2. 对话中展示标准版
3. 在已生成的报告基础上做补充语义分析（关联 `info` 级别条目）

**输出决策规则**：三版报告**始终由脚本生成并存盘**，对话中只展示标准版。

1. 运行 `halucatch_core.py --skill-dir <路径>` → 脚本自动完成 L1 扫描 + L2 评估 + L3 报告生成
2. 三份 `.md` 文件写入 `reports/` 目录（或 `--output-dir` 指定路径）
3. 对话中只输出**标准版**（白话、零术语）
4. 标准版末尾附带提示：「需要看技术细节（专业版）或修复方案（行动版）吗？」
5. 如果用户说「要」→ 对话中展示对应版本内容（文件已在磁盘上，直接读取展示）
6. 如果用户没回应 → 不主动输出，不造成信息过载

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

由 `reporter.py` 自动生成，包含 TL;DR 摘要、四维评级矩阵表、逐维度发现清单、检查声明。

#### 2. 标准版（给业务方/非技术人员）

由 `reporter.py` 自动生成，包含白话摘要、21 条语境解释映射、无术语输出。

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

由 `reporter.py` 自动生成，包含修复清单、验证检查点、三选一步骤提示。

#### 报告检查声明

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

```markdown
> 本报告由 HaluCatch 生成。检查进度: [✅ HaluCatch 四维评估全部执行完毕 / ⚠️ 部分评估维度未完成]。
```

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

#### AI 语义补充（在脚本报告基础上）

读取脚本生成的报告后，逐条审查发现，按严重度从高到低做上下文分析：

| 原评级 | AI 需要判断 |
|--------|-----------|
| 🔴 阻塞 | 这条风险在实际业务中到底多严重？是否真的会导致执行失败？修复优先级？ |
| 🟠 高危 | 上下文是否真的构成风险？有没有脚本误报的可能？修复方案是否需要细化？ |
| 🟡 提示 | 跳过项是否真的合理？有没有脚本漏掉但实际重要的风险？ |
| 🟢 通过 | ✅ 脚本判断正确，无需补充 |

输出格式：在每个发现条目下方追加一行 `> **AI 分析**: [具体判断]`。

#### 报告审查前检查

报告生成后、向用户展示或提交前，**必须**先检查标准版报告中是否存在 `⚠️ 疑似外部 Skill` 标记。

**如存在**：不做 `present_files`，向用户确认（优先用交互弹窗；不支持弹窗的平台改用文字列出选项，等用户回复 1/2/3）：

> ⚠️ 发现疑似外部 Skill 目录。`skills/` 是外部安装的 Skill（非本项目代码）吗？→ 确认后我会同步更新 HaluCatch 运行配置，之后自动跳过。

选项（标题「外部 Skill 确认」）：
1. 「是，跳过 skills/」→ 设 `skills_is_external: true`，重跑审查
2. 「否，正常扫描」→ 设 `skills_is_external: false`，重跑审查
3. 「不确定，保留标记」→ 保持现状，报告自动标注 `[⚠️ 疑似外部 Skill]`，继续展示

---

### Phase 4：修复决策与闭环

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

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

- **用户「修」** → 生成修复方案，然后展示三选一：

  > 修复方案已生成。请选择：
  > 1. **执行修复** — 将修复方案发给你的 AI，让它按方案修改目标 Skill
  > 2. **不执行** — 不做任何修改，结束本次审查
  > 3. **我有更好的意见** — 描述你的想法，我据此重新生成修复方案

  - 用户选「执行」→ 提示用户让 AI 应用修复 → 提示修复后重新运行 HaluCatch 验证
  - 用户选「不执行」→ 结束
  - 用户选「建议」→ 重新分析追加需求 → 回到「生成修复方案」

- **用户「不修」** → 结束

---

## 报告落盘

- 缺省输出到 `reports/` 目录（目标 Skill 目录内）
- 指定 `--output-dir` 则输出到自定义路径

---

## 更多触发示例

### 按审查深度

| 用户说 | AI 执行动作 |
|--------|-----------|
| 「帮我审一下这个 Skill，看看靠不靠谱」 | 完整流程：分类 → 四维评估 → 三版报告 |
| 「快速扫一眼，有没有明显的坑」 | 仅做 Phase 1 扫描 + Phase 2 L1/L2 规则检查，输出一份精简 checklist |
| 「这次只关注代码有没有除零/裸 except 这种硬伤」 | 跳过规则和护栏维度，只跑地基 + 代码检查 |
| 「上次审查后我改了 SKILL.md，帮我再跑一遍对比一下」 | 重新审查，对比上次报告，标注修复状态 |

### 按 Skill 类型

| 用户说 | AI 执行动作 |
|--------|-----------|
| 「我的 Skill 里有个 data/ 文件夹和 .py 脚本，帮我全面审」 | 分类为代码工程型，四维全覆盖 |
| 「这是一个纯指引文档类 Skill，帮我看看指令写得清楚不清楚」 | 分类为纯方法论型，仅评估方法论和护栏 |

### 路径写法（不同平台差异）

| 平台 | 正确写法 | ❌ 错误写法 |
|------|---------|-----------|
| Claude Code / 通用 | `/path/to/skill` | `C:\\path\\to\\skill` |
| Kimi / 微信小程序 | `skills/项目名/` | `~/skills/项目名/` |
| Cursor / VS Code | 拖拽文件夹到对话框 | 手动输入复杂路径 |

### 如果还是不会用

> 直接说：「审查 /path/to/skill」，把 Skill 文件夹拖进来即可。AI 会自行判断接下来的步骤。不要直接贴 SKILL.md 内容——用文件夹路径保证完整性。

---

## 异常处理

### 常见错误及修复

| 错误现象 | 原因 | 修复方法 |
|---------|------|---------|
| `❌ 找不到 SKILL.md` | 目标目录不存在或没有 .md 文件 | 确认路径正确 → 检查目录是否有 `SKILL.md` 或其他 `.md` 文件 → 如无，创建一个 |
| `⚠️ 未找到标准 SKILL.md` | 文件名不是 `SKILL.md`（如 `skill.md`、`README.md`） | 将文件重命名为 `SKILL.md`，或告知 AI 用 `--file` 指定文件名 |
| `🔧 文件编码异常，已跳过 XXX.py` | 文件包含非 UTF-8 字符（如 GBK 编码的中文注释） | 用编辑器将文件另存为 UTF-8 编码（编码转换不改变内容，仅调整存储方式） |
| `📦 Skill 包过大（> 2MB）` | 目录包含大量数据文件或依赖包 | 仅保留核心文件（SKILL.md + .py 脚本），数据文件和依赖放入 `.halucatch-ignore` |
| `⏱️ 审查超时` | 文件过多或脚本执行时间过长 | 告知 AI：「只审查 SKILL.md 和核心 .py 文件」 |

### 错误分级

| 级别 | 行为 |
|------|------|
| **致命**（如目录不存在） | 立即终止，提供明确的修复指引 |
| **警告**（如非标准文件名） | 继续审查但降级自检评分，在报告中标注 |
| **可恢复**（如单个文件编码问题） | 跳过该文件继续，在报告中标注被跳过的文件及原因 |

---

## 运行稳定性

### 防护措施

| 场景 | 保护策略 |
|------|---------|
| 大文件（单个 > 1MB） | 截取前 500 行进行分析，在报告中声明截断 |
| 大量文件（目录 > 200 个文件） | 按类型筛选（.md → .py → 其他），非核心文件自动跳过 |
| 脚本执行超时（> 30s） | 终止该步骤，将已验证的部分写入报告，标注未完成项 |
| 网络请求 | Halucatch **不发起网络请求**，100% 离线运行 |
| 编码问题 | 先尝试 UTF-8 → 再尝试系统 locale → 失败则跳过并记录 |
| 目录不可读 | 报告权限错误，建议用户 `chmod` 或换个路径 |

### 可靠性声明

> Halucatch 在正常 Skill 目录（≤ 50 个文件，单文件 ≤ 1MB）上运行稳定。极端情况会自动降级（截断/跳过/终止），不会静默失败。

---

## 反模式与 FAQ

### 常见误区

| 误区 | 正确认知 |
|------|---------|
| 「审查一次就够了」 | Skill 每次修改后都应重新审查，尤其是修改 SKILL.md 或关键 .py 文件后 |
| 「分数低 = 不能用」 | 分数是相对参考。一个「地基弱但规则清晰」的纯方法论型 Skill 可能完全可用 |
| 「修完所有问题才发布」 | 优先修高优（🔴）和中优（🟠）项，低优项可以渐进改进 |
| 「AI 行动版报告可以直接执行」 | 行动版是给 AI 的修复指令，需用户确认后再让 AI 执行，防止误改 |
| 「用 `--validate` 模式跑过就算审查了」 | `--validate` 只做文件扫描和类型分类，不做四维评估。正式审查必须完整跑 |

### FAQ

**Q：我需要准备什么？**
A：一个包含 `SKILL.md` 的文件夹。如果有 `.py` 脚本或数据文件，一并放入可以评估得更全面。

**Q：审查结果说不通过，我该怎么办？**
A：看报告中的「AI 行动版」，里面有逐项修复方案。按优先级从高到低修，修完再审查一次验证。

**Q：我的 Skill 没有 Python 代码，能用吗？**
A：能。HaluCatch 会自动分类为「纯方法论型」，跳过地基和代码检查，重点评估指令完备性和护栏。

**Q：遇到报错怎么办？**
A：看上方「异常处理」章节。90% 的报错是路径写错或文件名不规范。如果解决不了，把报错信息贴给 AI。

> 💡 **更多问题？** 查看 `FAQ.md`——包含完整的使用指南、常见问题和故障排除。
HaluCatch / 捕幻

SKILL.md

related skills
