Community寫作與編輯github.com

CoderMoray/HaluCatch

AI 技能可靠性審查工具。評估技能被 AI 執行時的可重現性、可信度與業務適配性。

HaluCatch 是什麼?

HaluCatch 是一個專為 AI 技能(Skill)開發者與使用者設計的可靠性審查工具,其名稱「HaluCatch」源自「Hallucination(幻覺)」與「Catch(捕獲)」。該工具能對目標技能目錄進行靜態分析,透過獨創的四維評估框架(地基、程式碼風險、規則清晰度、解讀護欄)全面檢查技能在 AI 執行時可能出現的幻覺與錯誤。HaluCatch 支援 CLI 命令列操作,內建 Python 核心腳本 `halucatch_core.py`,可一鍵完成文件掃描(L1)、多維評估(L2)與三版報告生成(L3),並自動根據使用者語言(中文/英文)調整輸出。它適用於任何包含 `SKILL.md` 的目錄,無論是純方法論型(無程式碼)或程式碼工程型(含 `.py` 腳本),皆能提供有針對性的評估與修復建議。作為開發者工具鏈的一部分,HaluCatch 特別適合在 CI/CD 流程中整合,確保每次技能迭代後都能獲得即時的可靠性回饋。

相容平台✓Claude Code~Codex CLI✓Cursor
npx skills add CoderMoray/HaluCatch

Installed? Explore more 寫作與編輯 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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-CNpython3 halucatch_core.py --skill-dir <path> --lang zh-CN
英文--lang enpython3 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)自動產生,你不再需要獨立撰寫報告正文。你只負責:

  1. 讀取腳本產生的報告檔案
  2. 對話中展示標準版
  3. 在已產生的報告基礎上做補充語義分析(關聯 info 級別條目)

輸出決策規則:三版報告始終由腳本產生並存檔,對話中只展示標準版。

  1. 執行 halucatch_core.py --skill-dir <路徑> → 腳本自動完成 L1 掃描 + L2 評估 + L3 報告產生
  2. 三份 .md 檔案寫入 HaluCatch/reports/ 目錄(或 --output-dir 指定路徑)
  3. 對話中只輸出標準版(白話、零術語)
  4. 標準版末尾附帶提示:「需要看技術細節(專業版)或修復方案(行動版)嗎?」
  5. 如果使用者說「要」→ 對話中展示對應版本內容(檔案已在磁碟上,直接讀取展示)
  6. 如果使用者沒回應 → 不主動輸出,不造成資訊過載

1. 專業版(給資料分析師/工程人員)

由 reporter.py 自動產生,包含 TL;DR 摘要、四維評級矩陣表、逐維度發現清單、檢查宣告。

2. 標準版(給業務方/非技術人員)

由 reporter.py 自動產生,包含白話摘要、21 條語境解釋對應、無術語輸出。

3. AI 行動版(供給修復階段使用)

由 reporter.py 自動產生,包含修復清單、驗證檢查點、三選一步驟提示。

報告檢查宣告

所有三版報告末尾必須包含檢查行:

> 本報告由 HaluCatch 產生。檢查進度: [✅ HaluCatch 四維評估全部執行完畢 / ⚠️ 部分評估維度未完成]。

如果評估過程中有維度未覆蓋(如程式碼工程型技能但使用者未提供 .py 檔案),檢查等級降為 ⚠️。

AI 語義補充(在腳本報告基礎上)

讀取腳本產生的報告後,逐條審查發現,依嚴重度從高到低做上下文分析:

原評級AI 需要判斷
🔴 阻塞這條風險在實際業務中到底多嚴重?是否真的會導致執行失敗?修復優先級?
🟠 高危上下文是否真的構成風險?有沒有腳本誤報的可能?修復方案是否需要細化?
🟡 提示跳過項是否真的合理?有沒有腳本漏掉但實際重要的風險?
🟢 通過✅ 腳本判斷正確,無需補充

輸出格式:在每個發現條目下方追加一行 > **AI 分析**: [具體判斷]。


Phase 4:修復決策與閉環

評估完成後,向使用者展示標準版報告並詢問:

偵測到 [N] 項風險。是否按建議方案修復?

  • 使用者「修」 → 產生修復方案,然後展示三選一:

    修復方案已產生。請選擇:

    1. 執行修復 — 將修復方案發給你的 AI,讓它按方案修改目標技能
    2. 不執行 — 不做任何修改,結束本次審查
    3. 我有更好的意見 — 描述你的想法,我據此重新產生修復方案
    • 使用者選「執行」→ 提示使用者讓 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/skillC:\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——包含完整的使用指南、常見問題和故障排除。

相關技能