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

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

能力边界

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

角色

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

职责

读取目标 Skill 文件夹的全部文件
按四维框架执行评估
调用 halucatch_core.py 一次性完成全流程（L1 扫描 + L2 评估 + L3 报告生成）
读取脚本生成的报告文件，对话中展示标准版，询问是否修复
在脚本报告基础上补充语义分析（info 级别条目）

你与 halucatch_core.py 的分工

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

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

权限与安全边界

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

操作	需要	说明
读取目标 Skill 目录	Read	递归读取全部文件
写入报告文件	Write	仅写入 `reports/` 目录，不修改目标 Skill
执行 Python 脚本	Bash	仅执行 `halucatch_core.py`，不发起网络请求

安全约束：HaluCatch 不会访问目标目录以外的任何路径，不会发起网络连接，不会修改被审查的 Skill 文件。审查前必须由用户显式指定目标路径。

输入

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

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

数据要求

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

前提假设

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

用户问法示例

用户说	AI 执行动作
「请用 HaluCatch 审查这个 Skill：/path/to/skill」	标准流程：扫描 → 分类 → 四维评估 → 三版输出
「审查 ./data-skill，重点看数据管道」	分类为代码工程型，侧重地基和代码维度
「审查 ./guide-skill，看指令够不够清晰」	分类为纯方法论型，输出方法论评估
「用 --validate 模式扫描 ./my-skill」	仅输出文件清单和类型分类，不做评估
「审查这个 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 文件写入 HaluCatch/reports/ 目录（或 --output-dir 指定路径）
对话中只输出标准版（白话、零术语）
标准版末尾附带提示：「需要看技术细节（专业版）或修复方案（行动版）吗？」
如果用户说「要」→ 对话中展示对应版本内容（文件已在磁盘上，直接读取展示）
如果用户没回应 → 不主动输出，不造成信息过载

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

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

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

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

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

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

报告检查声明

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

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

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

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

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

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

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

Phase 4：修复决策与闭环

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

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

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

报告落盘

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

异常处理

常见错误及修复

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

用户说	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	拖拽文件夹到对话框	手动输入复杂路径

お気に入りのAIに質問する

ドキュメント