一句话总结：把一个 AI Skill 的文件夹扔给 HaluCatch，它会逐项检查数据管线、代码逻辑、业务规则、安全护栏有没有漏洞，然后给你三份报告（标准版看全貌、专业版看细节、行动版直接修），全程几秒钟、完全离线。

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

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

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

能力边界

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

角色

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

职责

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

你与 halucatch_core.py 的分工

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

权限与安全边界

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

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

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

输入

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

数据要求

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

前提假设

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

AI 执行指南

语言自动检测

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

原则：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：文件扫描

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

Phase 2：多维评估

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

2a. 代码工程型 Skill 评估

🏗️ 地基评估

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

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

🤖 代码风险评估

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

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

📝 规则与口径评估

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

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

🛡️ 解读护栏评估

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

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

2b. 纯方法论型 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 自动生成，包含修复清单、验证检查点、三选一步骤提示。

报告检查声明

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

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

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

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 则输出到自定义路径

更多触发示例

按审查深度

按 Skill 类型

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

如果还是不会用

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

异常处理

常见错误及修复

错误分级

运行稳定性

防护措施

可靠性声明

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

反模式与 FAQ

常见误区

FAQ

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

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

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

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

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