HaluCatch

SKILL.md

---
slug: halucatch
displayName: "HaluCatch / 捕幻"
name: halucatch
description: |
  AI Skill 执行可靠性审查工具。评估一个 Skill 被 AI 执行时，结果是否可信、是否可复现、是否经得起业务推敲。
  覆盖四维度：地基（数据管线）、代码、规则（业务口径）、护栏（解读指南）。
author: Engineering Assurance Team
version: "1.6.9"
tags:
  - "工程质量"
  - "engineering-assurance"
  - "Skill审查"
  - "skill-audit"
  - "可靠性"
  - "reliability"
category: "engineering"
---

# 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：三版输出

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

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

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

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

报告结构：

```markdown
# HaluCatch Report — {Skill名称}

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

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

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

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

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

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

包含：

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

#### 报告自检声明

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

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

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

---

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

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

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

- **用户「修」** → 生成修复方案（含修复包 + feedback.md 模板），然后展示三选一：

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

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

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

---

## 报告落盘

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