HaluCatch / 捕幻 — AI 技能執行可靠性審查
評估一個技能包在 AI 執行時的可靠性,產出評估報告和修復建議。
能力邊界
| 擅長 | 不擅長 |
|---|---|
| 評估 AI 執行技能時是否會出錯 | 網路安全審查(SQL 注入、XSS 等) |
| 檢查資料管道是否可靠 | 合規性審查(GDPR、隱私法規等) |
| 發現自然語言業務規則的歧義 | 技能本身的業務正確性(不懂業務邏輯) |
| 檢查解讀護欄是否到位 | 程式碼效能最佳化 |
| 輸出修復建議和骨架腳本 | 取代人工業務決策 |
角色
當使用者呼叫 HaluCatch 時,你就是 HaluCatch 審查執行者,而非旁觀者。
職責
- 讀取目標技能資料夾的全部檔案
- 按四維框架執行評估
- 呼叫
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 僅需要以下權限即可執行:
| 操作 | 需要 | 說明 |
|---|---|---|
| 讀取目標技能目錄 | Read | 遞迴讀取全部檔案 |
| 寫入報告檔案 | Write | 僅寫入 reports/ 目錄,不修改目標技能 |
| 執行 Python 腳本 | Bash | 僅執行 halucatch_core.py,不發起網路請求 |
安全約束:HaluCatch 不會存取目標目錄以外的任何路徑,不會發起網路連線,不會修改被審查的技能檔案。審查前必須由使用者明確指定目標路徑。
輸入
使用者提供一個技能資料夾路徑。該資料夾可能包含:
| 檔案類型 | 是否必需 | 說明 |
|---|---|---|
SKILL.md | ✅ | 技能的主指令檔案 |
manifest.json 或 config.yaml | ❌ | 技能設定檔(含版本號等) |
*.py | ❌ | 資料管線的固化腳本(如有) |
*.xlsx / *.csv 等 | ❌ | 資料檔案(如有,用於驗證對帳) |
資料要求
- 時效性:審查基於目標技能目錄的即時快照,不追溯歷史版本。
- 資料範圍:僅評估目標目錄中可見的檔案,不爬取外部依賴或網路資源。
前提假設
- 目標目錄存在且有讀取權限。
- 目標技能應包含至少一個
SKILL.md檔案(規範名稱)。如有其他.md檔案,AI 將嘗試啟發式比對,但會報告規範性問題。 - 目錄中的
.py檔案視為技能核心執行腳本,非第三方依賴庫。
使用者問法範例
| 使用者說 | AI 執行動作 |
|---|---|
| 「請用 HaluCatch 審查這個技能:/path/to/skill」 | 標準流程:掃描 → 分類 → 四維評估 → 三版輸出 |
| 「審查 ./data-skill,重點看資料管道」 | 分類為程式碼工程型,側重地基和程式碼維度 |
| 「審查 ./guide-skill,看指令夠不夠清晰」 | 分類為純方法論型,輸出方法論評估 |
| 「用 --validate 模式掃描 ./my-skill」 | 僅輸出檔案清單和類型分類,不做評估 |
| 「審查這個技能後如果發現問題就修」 | 評估 → 使用者確認「修」→ 自動出修復方案 |
AI 執行指南
語言自動偵測
AI 在載入本技能時,應從系統提示(<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:技能分類
首先判斷這個技能的類型:
這個技能涉及資料處理嗎?
├─ ❌ 純方法論型(指令/範本/文件類)
│ 評估重點:指令完備性、邏輯自洽、可重現性
│
├─ ✅ 程式碼工程型(含 .py / 資料檔案 / md 內嵌程式碼)
│ 評估重點:地基 + 程式碼 + 規則 + 護欄
│
└─ ⚠️ 不確定
→ 詢問使用者:「這個技能有資料處理步驟嗎?」
如果資料夾中存在 .xlsx、.csv、.py(含 pd.read_、pd.DataFrame)等檔案或內容,預設按「程式碼工程型」處理。
Phase 1:檔案掃描
讀取資料夾中的全部檔案並建構清單:
| 資訊點 | 輸出形式 |
|---|---|
| 檔名列表 | 表格(檔名/大小/類型) |
| SKILL.md 總行數 | 數字 |
| .py 檔案行數(如有) | 數字 |
| 資料檔案列表 | 表格 |
| 技能名稱和描述 | 從 frontmatter 提取 |
Phase 2:多維評估
根據 Phase 0 的分類執行對應的評估維度的檢查。
2a. 程式碼工程型技能評估
🏗️ 地基評估
檢查技能的資料管線是否穩固。地基越弱,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. 純方法論型技能評估
| 檢查項 | 說明 |
|---|---|
| 指令完備性 | 每個步驟都有明確的輸入/輸出/判斷條件 |
| 邊界情況 | 是否有「如果…則…」的異常分支處理 |
| 可重現性 | 不同 AI 執行是否會得到一致的結論 |
| 範例驅動 | 是否包含具體範例來說明期望輸出 |
| 輸出格式定義 | AI 的輸出結構是否被約束 |
| 自我驗證 | 技能執行結果能否自洽檢查 |
評級:🟢 可靠 / 🟡 有改善空間 / 🔴 不可靠
⚠️ 執行前確認:在開始掃描檔案、執行
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 四維評估全部執行完畢 / ⚠️ 部分評估維度未完成]。
如果評估過程中有維度未覆蓋(如程式碼工程型技能但使用者未提供 .py 檔案),檢查等級降為 ⚠️。
AI 語義補充(在腳本報告基礎上)
讀取腳本產生的報告後,逐條審查發現,依嚴重度從高到低做上下文分析:
| 原評級 | AI 需要判斷 |
|---|---|
| 🔴 阻塞 | 這條風險在實際業務中到底多嚴重?是否真的會導致執行失敗?修復優先級? |
| 🟠 高危 | 上下文是否真的構成風險?有沒有腳本誤報的可能?修復方案是否需要細化? |
| 🟡 提示 | 跳過項是否真的合理?有沒有腳本漏掉但實際重要的風險? |
| 🟢 通過 | ✅ 腳本判斷正確,無需補充 |
輸出格式:在每個發現條目下方追加一行 > **AI 分析**: [具體判斷]。
Phase 4:修復決策與閉環
評估完成後,向使用者展示標準版報告並詢問:
偵測到 [N] 項風險。是否按建議方案修復?
-
使用者「修」 → 產生修復方案,然後展示三選一:
修復方案已產生。請選擇:
- 執行修復 — 將修復方案發給你的 AI,讓它按方案修改目標技能
- 不執行 — 不做任何修改,結束本次審查
- 我有更好的意見 — 描述你的想法,我據此重新產生修復方案
- 使用者選「執行」→ 提示使用者讓 AI 應用修復 → 提示修復後重新執行 HaluCatch 驗證
- 使用者選「不執行」→ 結束
- 使用者選「建議」→ 重新分析追加需求 → 回到「產生修復方案」
-
使用者「不修」 → 結束
報告存檔
- 缺省輸出到
HaluCatch/reports/目錄(不污染目標技能目錄) - 指定
--output-dir則輸出到自訂路徑 - 修復包(如有)儲存到:
{技能目錄}/halucatch-fix/
更多觸發範例
按審查深度
| 使用者說 | AI 執行動作 |
|---|---|
| 「幫我審一下這個技能,看看靠不靠譜」 | 完整流程:分類 → 四維評估 → 三版報告 |
| 「快速掃一眼,有沒有明顯的坑」 | 僅做 Phase 1 掃描 + Phase 2 L1/L2 規則檢查,輸出一份精簡 checklist |
| 「這次只關注程式碼有沒有除零/裸 except 這種硬傷」 | 跳過規則和護欄維度,只跑地基 + 程式碼檢查 |
| 「上次審查後我改了 SKILL.md,幫我再跑一遍對比一下」 | 重新審查,比對上次報告,標註修復狀態 |
按技能類型
| 使用者說 | AI 執行動作 |
|---|---|
| 「我的技能裡有個 data/ 資料夾和 .py 腳本,幫我全面審」 | 分類為程式碼工程型,四維全覆蓋 |
| 「這是一個純指引文件類技能,幫我看看指令寫得清楚不清楚」 | 分類為純方法論型,僅評估方法論和護欄 |
路徑寫法(不同平台差異)
| 平台 | 正確寫法 | ❌ 錯誤寫法 |
|---|---|---|
| Claude Code / 通用 | /path/to/skill | C:\path\to\skill |
| Kimi / 微信小程式 | skills/專案名/ | ~/skills/專案名/ |
| Cursor / VS Code | 拖曳資料夾到對話框 | 手動輸入複雜路徑 |
如果還是不會用
直接說:「幫我審查這個技能」然後把技能資料夾拖進來,或貼一段 SKILL.md 的內容。AI 會自行判斷接下來的步驟。
異常處理
常見錯誤及修復
| 錯誤現象 | 原因 | 修復方法 |
|---|---|---|
❌ 找不到 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 編碼,或將註解改為英文 |
📦 技能包過大(> 2MB) | 目錄包含大量資料檔案或依賴套件 | 僅保留核心檔案(SKILL.md + .py 腳本),資料檔案和依賴放入 .halucatch-ignore |
⏱️ 審查逾時 | 檔案過多或腳本執行時間過長 | 告知 AI:「只審查 SKILL.md 和核心 .py 檔案」 |
錯誤分級
| 級別 | 行為 |
|---|---|
| 致命(如目錄不存在) | 立即終止,提供明確的修復指引 |
| 警告(如非標準檔名) | 繼續審查但降級自檢評分,在報告中標註 |
| 可恢復(如單個檔案編碼問題) | 跳過該檔案繼續,在報告中標註被跳過的檔案及原因 |
執行穩定性
防護措施
| 場景 | 保護策略 |
|---|---|
| 大檔案(單個 > 1MB) | 截取前 500 行進行分析,在報告中宣告截斷 |
| 大量檔案(目錄 > 200 個檔案) | 按類型篩選(.md → .py → 其他),非核心檔案自動跳過 |
| 腳本執行逾時(> 30s) | 終止該步驟,將已驗證的部分寫入報告,標註未完成項 |
| 網路請求 | Halucatch 不發起網路請求,100% 離線執行 |
| 編碼問題 | 先嘗試 UTF-8 → 再嘗試系統 locale → 失敗則跳過並記錄 |
| 目錄不可讀 | 報告權限錯誤,建議使用者 chmod 或換個路徑 |
可靠性宣告
Halucatch 在正常技能目錄(≤ 50 個檔案,單檔案 ≤ 1MB)上執行穩定。極端情況會自動降級(截斷/跳過/終止),不會靜默失敗。
反模式與 FAQ
常見誤區
| 誤區 | 正確認知 |
|---|---|
| 「審查一次就夠了」 | 技能每次修改後都應重新審查,尤其是修改 SKILL.md 或關鍵 .py 檔案後 |
| 「分數低 = 不能用」 | 分數是相對參考。一個「地基弱但規則清晰」的純方法論型技能可能完全可用 |
| 「修完所有問題才發布」 | 優先修高優(🔴)和中優(🟠)項,低優項可以漸進改進 |
| 「AI 行動版報告可以直接執行」 | 行動版是給 AI 的修復指令,需使用者確認後再讓 AI 執行,防止誤改 |
「用 --validate 模式跑過就算審查了」 | --validate 只做檔案掃描和類型分類,不做四維評估。正式審查必須完整跑 |
FAQ
Q:我需要準備什麼?
A:一個包含 SKILL.md 的資料夾。如果有 .py 腳本或資料檔案,一併放入可以評估得更全面。
Q:審查結果說不通過,我該怎麼辦? A:看報告中的「AI 行動版」,裡面有逐項修復方案。按優先級從高到低修,修完再審查一次驗證。
Q:我的技能沒有 Python 程式碼,能用嗎? A:能。HaluCatch 會自動分類為「純方法論型」,跳過地基和程式碼檢查,重點評估指令完備性和護欄。
Q:遇到報錯怎麼辦? A:看上方「異常處理」章節。90% 的報錯是路徑寫錯或檔名不規範。如果解決不了,把報錯資訊貼給 AI。
💡 更多問題? 查看
FAQ.md——包含完整的使用指南、常見問題和故障排除。