halucatch-捕幻-x

原始内容

---
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`——包含完整的使用指南、常见问题和故障排除。

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，它会逐项检查数据管线、代码逻辑、业务规则、安全护栏有没有漏洞，然后给你三份报告（标准版看全貌、专业版看细节、行动版直接修），全程几秒钟、完全离线。

快速开始 · 能力边界 · 输出解读

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 肯定知道用户用什么语言，不需要用户手动配置。

基本用法

# 为中文用户审查
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）自动生成，你不再需要独立撰写报告正文。你只负责：

读取脚本生成的报告文件
对话中展示标准版
在已生成的报告基础上做补充语义分析（关联 info 级别条目）

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

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

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

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

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

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

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

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

报告检查声明

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

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

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

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

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

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

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

报告审查前检查

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

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

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

选项（标题「外部 Skill 确认」）：

「是，跳过 skills/」→ 设 skills_is_external: true，重跑审查
「否，正常扫描」→ 设 skills_is_external: false，重跑审查
「不确定，保留标记」→ 保持现状，报告自动标注 [⚠️ 疑似外部 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，帮我再跑一遍对比一下」	重新审查，对比上次报告，标注修复状态

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

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

异常处理

常见错误及修复

错误现象	原因	修复方法
`❌ 找不到 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——包含完整的使用指南、常见问题和故障排除。