CommunityEscrita e Ediçãogithub.com

CoderMoray/HaluCatch

Ferramenta de revisão de confiabilidade para execução de AI Skills. Avalia a reprodutibilidade, credibilidade e adequação ao negócio de um Skill quando executado por IA.

O que é HaluCatch?

HaluCatch é uma skill especializada em auditar a confiabilidade de outras skills de IA (como as usadas em Claude Code, Cursor ou Codex). Ela analisa o conteúdo de uma skill — seu arquivo `SKILL.md`, scripts Python anexos e arquivos de dados — e produz um relatório detalhado com pontuações em quatro dimensões: fundação (estrutura do pipeline de dados), código (risco de alucinação em snippets embutidos), regras (clareza das regras de negócio) e barreiras (restrições de interpretação para o modelo). O processo é totalmente automatizado por um script Python (`halucatch_core.py`) que realiza a varredura (L1), a avaliação (L2) e a geração de três versões do relatório (técnica, de negócio e de reparo) sem depender da geração criativa do modelo. O papel do agente é ler esses relatórios já gerados, apresentá-los ao usuário e, se solicitado, sugerir correções com base nas descobertas. A skill é offline, não faz requisições de rede e só escreve arquivos em seu próprio diretório de relatórios, garantindo segurança e foco.

Funciona com✓Claude Code~Codex CLI✓Cursor
npx skills add CoderMoray/HaluCatch

Installed? Explore more Escrita e Edição skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

HaluCatch / 捕幻 — Revisão de Confiabilidade de Execução de AI Skill

Avalia a confiabilidade de um pacote Skill quando executado por IA, gerando relatório de avaliação e sugestões de reparo.


Limites de Capacidade

Adequado paraNão adequado para
Avaliar se um skill pode falhar quando executado por IARevisão de segurança cibernética (SQL injection, XSS, etc.)
Verificar se o pipeline de dados é confiávelRevisão de conformidade (GDPR, regulamentações de privacidade, etc.)
Identificar ambiguidades em regras de negócio em linguagem naturalA correção lógica do próprio skill (não entende a lógica de negócio)
Verificar se as barreiras de interpretação estão implementadasOtimização de desempenho de código
Fornecer recomendações de reparo e scripts de esqueletoSubstituir decisões de negócio humanas

Papel

Quando o usuário chama o HaluCatch, você é o executor da revisão HaluCatch, não um observador.

Responsabilidades

  • Ler todos os arquivos da pasta Skill alvo
  • Executar a avaliação de acordo com o framework quadridimensional
  • Chamar halucatch_core.py para completar todo o fluxo de uma só vez (L1 varredura + L2 avaliação + L3 geração de relatório)
  • Ler o arquivo de relatório gerado pelo script, exibir a versão padrão no diálogo e perguntar se deseja corrigir
  • Complementar a análise semântica (itens de nível info) com base no relatório do script

Divisão de trabalho entre você e o halucatch_core.py

NívelTarefaExecutorPrincípio
L1Varredura de arquivoshalucatch_core.py --validateAlta determinismo, script é mais rápido e preciso
L2Verificação de fundação + código + regras + barreirasScript obtém linha de base JSON → você complementa a análiseCorrespondência regex pelo script, interpretação contextual por você
L3Geração de três versões de relatóriohalucatch_core.py gera e salva, você lê e exibe ao usuárioreporter.py tem alto determinismo, formato consistente, zero alucinação — você só faz a complementação semântica

Princípio central: halucatch_core.py cobre todo o fluxo — varredura L1, avaliação L2, geração de relatório L3 de uma só vez. Você só precisa ler o relatório gerado pelo script e exibi-lo ao usuário. Você não precisa mais escrever o corpo do relatório independentemente.

Permissões e Limites de Segurança

O HaluCatch só precisa das seguintes permissões para executar:

OperaçãoNecessidadeDescrição
Ler diretório alvo do SkillLeituraLer recursivamente todos os arquivos
Escrever arquivos de relatórioEscritaApenas no diretório reports/, não modifica o Skill alvo
Executar script PythonBashApenas executa halucatch_core.py, não inicia requisições de rede

Restrições de segurança: HaluCatch não acessa nenhum caminho fora do diretório alvo, não inicia conexões de rede e não modifica os arquivos do Skill revisado. O caminho alvo deve ser explicitamente especificado pelo usuário antes da revisão.


Entrada

O usuário fornece um caminho de pasta do Skill. Essa pasta pode conter:

Tipo de arquivoObrigatórioDescrição
SKILL.md✅Arquivo de instruções principal do Skill
manifest.json ou config.yaml❌Arquivo de configuração do Skill (contém número de versão, etc.)
*.py❌Scripts consolidados do pipeline de dados (se houver)
*.xlsx / *.csv etc.❌Arquivos de dados (se houver, para verificação de conciliação)

Requisitos de Dados

  • Atualidade: A revisão é baseada em um snapshot instantâneo do diretório do Skill alvo, não rastreia versões históricas.
  • Escopo de dados: Avalia apenas os arquivos visíveis no diretório alvo, não rastreia dependências externas ou recursos de rede.

Premissas

  • O diretório alvo existe e tem permissão de leitura.
  • O Skill alvo deve conter pelo menos um arquivo SKILL.md (nome padrão). Se houver outros arquivos .md, a IA tentará uma correspondência heurística, mas relatará problemas de padronização.
  • Arquivos .py no diretório são considerados scripts principais de execução do Skill, não bibliotecas de dependência de terceiros.

Exemplos de Perguntas do Usuário

O usuário dizAção da IA
"Por favor, revise este Skill com o HaluCatch: /caminho/para/skill"Fluxo padrão: varredura → classificação → avaliação quadridimensional → três versões de saída
"Revise ./data-skill, foco no pipeline de dados"Classificado como tipo engenharia de código, ênfase nas dimensões fundação e código
"Revise ./guide-skill, veja se as instruções são claras o suficiente"Classificado como tipo puramente metodológico, saída de avaliação metodológica
"Varra ./my-skill no modo --validate"Apenas saída de lista de arquivos e classificação de tipos, sem avaliação
"Revise este Skill e, se encontrar problemas, corrija"Avaliação → usuário confirma "corrigir" → plano de reparo gerado automaticamente

Guia de Execução da IA

Detecção Automática de Idioma

Ao carregar este Skill, a IA deve detectar o idioma do usuário a partir do prompt do sistema (<response_language>) ou do contexto do diálogo e adicionar automaticamente o parâmetro --lang:

Idioma do usuárioParâmetroExemplo
Chinês (Simplificado/Tradicional)--lang zh-CNpython3 halucatch_core.py --skill-dir <caminho> --lang zh-CN
Inglês--lang enpython3 halucatch_core.py --skill-dir <caminho> --lang en
IncertoNão adicionar (padrão auto, detecta locale do sistema)python3 halucatch_core.py --skill-dir <caminho>

Princípio: A IA certamente sabe qual idioma o usuário está usando; não há necessidade de configuração manual pelo usuário.

Uso Básico

# Revisão para usuário chinês
python3 halucatch_core.py --skill-dir /caminho/para/skill --lang zh-CN

# Revisão para usuário inglês
python3 halucatch_core.py --skill-dir /caminho/para/skill --lang en

# Detecção automática (fallback)
python3 halucatch_core.py --skill-dir /caminho/para/skill

Fluxo de Execução

Paradigma de execução: Cada Fase atribui responsabilidades de acordo com o modelo de três camadas de chamada. halucatch_core.py completa L1/L2/L3 de uma só vez; você lê o arquivo de relatório gerado e o exibe ao usuário.

Fase 0: Classificação do Skill

Primeiro, determine o tipo deste Skill:

Este Skill envolve processamento de dados?
  ├─ ❌ Tipo puramente metodológico (instruções/modelos/documentos)
  │    Ênfase da avaliação: Completude das instruções, consistência lógica, reprodutibilidade
  │
  ├─ ✅ Tipo engenharia de código (contém .py / arquivos de dados / código embutido em md)
  │    Ênfase da avaliação: Fundação + Código + Regras + Barreiras
  │
  └─ ⚠️ Incerto
        → Perguntar ao usuário: "Este Skill tem etapas de processamento de dados?"

Se a pasta contiver arquivos .xlsx, .csv, .py (com pd.read_, pd.DataFrame, etc.) ou conteúdo semelhante, trate como "tipo engenharia de código" por padrão.

Fase 1: Varredura de Arquivos

Ler todos os arquivos da pasta e construir um inventário:

Ponto de informaçãoFormato de saída
Lista de nomes de arquivosTabela (nome/tamanho/tipo)
Número total de linhas do SKILL.mdNúmero
Número de linhas do(s) arquivo(s) .py (se houver)Número
Lista de arquivos de dadosTabela
Nome e descrição do SkillExtraído do frontmatter

Fase 2: Avaliação Multidimensional

Executar a verificação das dimensões de avaliação correspondentes de acordo com a classificação da Fase 0.


2a. Avaliação de Skill Tipo Engenharia de Código

🏗️ Avaliação de Fundação

Verificar se o pipeline de dados do Skill é estável. Quanto mais fraca a fundação, maior a probabilidade de a IA cometer erros ao escrever código de forma autônoma.

Item de verificaçãoCritério de aprovação
Script .py consolidado presenteO script existe na pasta
Caminhos parametrizadosNúmero de caminhos codificados = 0
Pré-verificação de nomes de colunas/validação de entradaExiste função check_columns ou similar
Modo validateExiste modo --validate ou similar
Mecanismo de descoberta de arquivosUsa glob/wildcards em vez de nomes de arquivo fixos
Declaração de dependênciasPacotes Python necessários declarados no SKILL.md
skiprows parametrizadoNúmero de linhas a pular na leitura de Excel configurável ou detectado automaticamente

Classificação: 🟢 Estável / 🟡 Com riscos / 🔴 Sem fundação


🤖 Avaliação de Risco de Código

Se o SKILL.md contiver código Python embutido (que a IA deve reproduzir literalmente), verifique os seguintes pontos de adulteração:

Categoria de verificaçãoPadrão de alto riscoComportamento de possível alteração incorreta pela IA
Funções estatísticasFórmula de p-value personalizada, cálculo de Z-scoreSubstituir por scipy.stats / ajustar constantes
Correspondência de stringsAnalisar porcentagem em clean_rate()Substituir replace('%','') por uma sintaxe diferente
Comparação de ponto flutuante== 0 / == 1Mudar para math.isclose() (semântica diferente)
Tratamento de exceçõesexcept: pass genéricoMudar para tipo de exceção específico
Lógica condicional(condição).sum() > 0Mudar para .any(axis=1) (comportamento diferente)
Lógica de agregaçãounstack(fill_value=0)Remover fill_value (propagação de NaN)
Limpeza de dadosSem instruções de conversão de tipo de dadosPode resultar em erro sum() em coluna de string

Classificação: 🟢 Baixo risco / 🟠 Com risco / 🔴 Alto risco


📝 Avaliação de Regras e Definições

Verificar se a descrição das regras de negócio no SKILL.md é clara e inequívoca:

Item de verificaçãoRisco
Definições de canal/classificação claramente listadasAmbiguidade → IA adivinha por conta própria
Valores atípicos/condições de contorno definidosOmissão → IA trata por conta própria
Relações geracionais/mapeamentos consolidados (em vez de depender do conhecimento da IA)Não consolidado → diferentes IAs produzem resultados diferentes
Definições de comparação (mesma loja, ano a ano, etc.)Não definido → IA decide por conta própria, não auditável
Regras de correção especiais (por exemplo, agregação em Hainan) documentadasNão documentado → lógica de negócio crítica perdida
Convenções de nomes de arquivos/nomes de colunas/formatos de dadosNão acordado → não funciona

Classificação: 🟢 Claro / 🟡 Ambíguo / 🔴 Omissão Grave


🛡️ Avaliação de Barreiras de Interpretação

Verificar se o SKILL.md restringe a forma como a IA interpreta os resultados:

Item de verificaçãoGravidade
Proibição de linguagem causalAusente → 🔴 Grave
Framework de quatro quadrantes/tamanho do efeitoAusente → 🟠 Alta
Mecanismo de auto-verificação (self-check)Ausente → 🟠 Alta
Aviso de comparação múltiplaAusente → 🟠 Alta
Modelo de declaração de limitaçãoAusente → 🟠 Alta
Saída de status por etapasAusente → 🟡 Média
Impressão de resumo estatístico de dadosAusente → 🟡 Média
Definição de formato de saídaAusente → 🟡 Média

Classificação: 🟢 Completo / 🟡 Com itens ausentes / 🔴 Sem barreiras


2b. Avaliação de Skill Tipo Puramente Metodológico

Item de verificaçãoDescrição
Completude das instruçõesCada etapa tem entrada/saída/condição de decisão claras
Casos de bordaExiste tratamento de ramificação anômala "se... então..."
ReprodutibilidadeIAs diferentes chegarão à mesma conclusão?
Orientação por exemplosInclui exemplos concretos para ilustrar a saída esperada?
Definição de formato de saídaA estrutura de saída da IA é restrita?
Auto-verificaçãoO resultado da execução do Skill pode ser verificado de forma consistente?

Classificação: 🟢 Confiável / 🟡 Com espaço para melhoria / 🔴 Não confiável


⚠️ Confirmação antes da execução: Antes de começar a escanear arquivos, executar halucatch_core.py ou gerar relatórios, você deve primeiro confirmar com o usuário que o caminho alvo está correto e informar as operações que serão realizadas (ler arquivos do diretório alvo, executar script local, gerar relatório no diretório reports/). Nenhuma operação de leitura ou escrita deve ser executada antes da confirmação explícita.

Fase 3: Saída de Três Versões

Mudança central: Os relatórios são gerados automaticamente pelo halucatch_core.py (reporter.py). Você não precisa mais escrever o corpo do relatório de forma independente. Você é responsável apenas por:

  1. Ler os arquivos de relatório gerados pelo script
  2. Exibir a versão padrão no diálogo
  3. Complementar a análise semântica (associar itens de nível info) com base no relatório já gerado

Regra de decisão de saída: Os três relatórios são sempre gerados e salvos pelo script; apenas a versão padrão é exibida no diálogo.

  1. Execute halucatch_core.py --skill-dir <caminho> → O script completa automaticamente a varredura L1 + avaliação L2 + geração de relatório L3
  2. Três arquivos .md são gravados no diretório HaluCatch/reports/ (ou no caminho especificado por --output-dir)
  3. Apenas a versão padrão é exibida no diálogo (linguagem simples, sem jargões)
  4. Ao final da versão padrão, anexe o aviso: "Precisa ver os detalhes técnicos (versão profissional) ou o plano de reparo (versão de ação)?"
  5. Se o usuário disser "sim" → Exibir o conteúdo da versão correspondente no diálogo (o arquivo já está no disco; basta ler e exibir)
  6. Se o usuário não responder → Não exibir ativamente, sem sobrecarga de informação

1. Versão Profissional (para analistas de dados/engenheiros)

Gerada automaticamente pelo reporter.py, contém resumo TL;DR, matriz de classificação quadridimensional, lista de descobertas por dimensão e declaração de verificação.

2. Versão Padrão (para áreas de negócio/público não técnico)

Gerada automaticamente pelo reporter.py, contém resumo em linguagem simples, mapeamento de contexto de 21 itens e saída sem jargões.

3. Versão de Ação da IA (para uso na fase de reparo)

Gerada automaticamente pelo reporter.py, contém lista de correções, pontos de verificação de validação e prompt de três opções.

Declaração de Verificação do Relatório

Todas as três versões do relatório devem conter uma linha de verificação no final:

> Este relatório foi gerado pelo HaluCatch. Status da verificação: [✅ Todas as quatro dimensões da avaliação HaluCatch foram concluídas / ⚠️ Algumas dimensões da avaliação não foram concluídas].

Se alguma dimensão não for coberta durante a avaliação (por exemplo, Skill tipo engenharia de código, mas o usuário não forneceu arquivos .py), a classificação de verificação é rebaixada para ⚠️.

Complemento Semântico da IA (com base no relatório do script)

Após ler o relatório gerado pelo script, revise as descobertas item por item, analisando o contexto em ordem decrescente de gravidade:

Classificação originalA IA precisa avaliar
🔴 BloqueanteQuão grave é esse risco no contexto real do negócio? Realmente levaria à falha de execução? Qual a prioridade de reparo?
🟠 Alto riscoO contexto realmente constitui um risco? Há possibilidade de falso positivo do script? O plano de reparo precisa ser detalhado?
🟡 AvisoA omissão é realmente razoável? Existem riscos importantes que o script perdeu?
🟢 Aprovado✅ O julgamento do script está correto, nenhum complemento necessário

Formato de saída: Abaixo de cada item de descoberta, adicione uma linha > **Análise da IA**: [julgamento específico].


Fase 4: Decisão de Reparo e Fechamento

Após a conclusão da avaliação, exiba o relatório da versão padrão ao usuário e pergunte:

Detectados [N] riscos. Deseja corrigir de acordo com o plano sugerido?

  • Usuário "corrigir" → Gerar plano de reparo e, em seguida, exibir três opções:

    Plano de reparo gerado. Por favor, escolha:

    1. Executar reparo — Envie o plano de reparo para sua IA, que modificará o Skill alvo de acordo com o plano
    2. Não executar — Não fazer nenhuma alteração, encerrar esta revisão
    3. Tenho uma sugestão melhor — Descreva sua ideia e gerarei um novo plano de reparo com base nela
    • Usuário escolhe "Executar" → Instrua o usuário a aplicar o reparo pela IA → Instrua a executar novamente o HaluCatch para verificação após o reparo
    • Usuário escolhe "Não executar" → Encerrar
    • Usuário escolhe "Sugestão" → Reanalisar os requisitos adicionais → Voltar para "Gerar plano de reparo"
  • Usuário "não corrigir" → Encerrar


Armazenamento de Relatórios

  • Padrão: Saída para o diretório HaluCatch/reports/ (não polui o diretório do Skill alvo)
  • Especificar --output-dir para saída em caminho personalizado
  • Pacote de reparo (se houver) salvo em: {Diretório do Skill}/halucatch-fix/

Mais Exemplos de Gatilho

Por profundidade de revisão

O usuário dizAção da IA
"Me ajude a revisar este Skill, veja se é confiável"Fluxo completo: classificação → avaliação quadridimensional → três versões de relatório
"Dê uma olhada rápida, veja se tem armadilhas óbvias"Apenas Fase 1 varredura + verificação de regras L1/L2 da Fase 2, saída de uma checklist simplificada
"Desta vez, foque apenas em problemas graves de código, como divisão por zero, except genérico, etc."Pular as dimensões de regras e barreiras, apenas verificação de fundação + código
"Depois da última revisão, modifiquei o SKILL.md; me ajude a executar novamente e comparar"Re-revisar, comparar com o relatório anterior, marcar o status do reparo

Por tipo de Skill

O usuário dizAção da IA
"Meu Skill tem uma pasta data/ e script .py; me ajude a revisar completamente"Classificado como tipo engenharia de código, cobertura total das quatro dimensões
"Este é um Skill puramente de guia/documentação; me ajude a ver se as instruções estão claras"Classificado como tipo puramente metodológico, apenas avaliação metodológica e de barreiras

Sintaxe de caminho (diferenças entre plataformas)

PlataformaEscrita correta❌ Escrita incorreta
Claude Code / Geral/caminho/para/skillC:\caminho\para\skill
Kimi / WeChat Mini Programskills/nome-do-projeto/~/skills/nome-do-projeto/
Cursor / VS CodeArraste a pasta para a caixa de diálogoDigitar caminho complexo manualmente

Se ainda estiver com dificuldades

Diga diretamente: "Me ajude a revisar este Skill" e arraste a pasta do Skill para cá, ou cole um trecho do conteúdo do SKILL.md. A IA determinará automaticamente os próximos passos.


Tratamento de Exceções

Erros comuns e correções

Sintoma de erroCausaMétodo de correção
❌ SKILL.md não encontradoDiretório alvo não existe ou não tem arquivo .mdConfirmar que o caminho está correto → Verificar se o diretório contém SKILL.md ou outros arquivos .md → Se não, criar um
⚠️ SKILL.md padrão não encontradoO nome do arquivo não é SKILL.md (por exemplo, skill.md, README.md)Renomear o arquivo para SKILL.md, ou informar a IA para usar --file para especificar o nome do arquivo
🔧 Erro de codificação de arquivo, XXX.py ignoradoO arquivo contém caracteres não UTF-8 (por exemplo, comentários em chinês codificados em GBK)Usar um editor para salvar o arquivo como UTF-8, ou alterar os comentários para inglês
📦 Pacote Skill muito grande (> 2MB)O diretório contém muitos arquivos de dados ou pacotes de dependênciaManter apenas os arquivos principais (SKILL.md + script .py), colocar arquivos de dados e dependências em .halucatch-ignore
⏱️ Revisão excedeu o tempo limiteMuitos arquivos ou tempo de execução do script muito longoInformar a IA: "Revise apenas o SKILL.md e os arquivos .py principais"

Classificação de erros

NívelComportamento
Fatal (por exemplo, diretório não existe)Interromper imediatamente, fornecer instruções claras de correção
Aviso (por exemplo, nome de arquivo não padrão)Continuar a revisão, mas rebaixar a pontuação de auto-verificação e marcar no relatório
Recuperável (por exemplo, problema de codificação de arquivo único)Pular o arquivo e continuar, marcar o arquivo ignorado e o motivo no relatório

Estabilidade de Execução

Medidas de proteção

CenárioEstratégia de proteção
Arquivo grande (único > 1MB)Analisar apenas as primeiras 500 linhas, declarar truncamento no relatório
Muitos arquivos (diretório > 200 arquivos)Filtrar por tipo (.md → .py → outros), ignorar automaticamente arquivos não essenciais
Tempo limite de execução do script (> 30s)Interromper a etapa, escrever a parte já verificada no relatório, marcar itens incompletos
Requisições de redeHalucatch não inicia requisições de rede, 100% offline
Problemas de codificaçãoTentar UTF-8 primeiro → depois tentar locale do sistema → se falhar, ignorar e registrar
Diretório ilegívelRelatar erro de permissão, sugerir que o usuário execute chmod ou mude de caminho

Declaração de Confiabilidade

Halucatch é estável em diretórios de Skill normais (≤ 50 arquivos, arquivo único ≤ 1MB). Em casos extremos, ele será rebaixado automaticamente (truncamento/ignorar/interromper) sem falhar silenciosamente.


Anti-padrões e FAQ

Equívocos comuns

EquívocoEntendimento correto
"Revisar uma vez é suficiente"Todo Skill modificado deve ser revisado novamente, especialmente após alterações no SKILL.md ou em arquivos .py críticos
"Pontuação baixa = não utilizável"A pontuação é uma referência relativa. Um Skill puramente metodológico com "fundação fraca, mas regras claras" pode ser perfeitamente utilizável
"Corrigir todos os problemas antes de publicar"Priorizar correções de alta prioridade (🔴) e média prioridade (🟠); itens de baixa prioridade podem ser melhorados progressivamente
"A versão de ação da IA pode ser executada diretamente"A versão de ação são instruções de reparo para a IA; o usuário deve confirmar antes de a IA executar, para evitar modificações acidentais
"Usar o modo --validate já conta como revisão"--validate apenas faz varredura de arquivos e classificação de tipos, não faz avaliação quadridimensional. A revisão formal deve ser completa

FAQ

P: O que preciso preparar? R: Uma pasta contendo SKILL.md. Se houver scripts .py ou arquivos de dados, inclua-os para uma avaliação mais completa.

P: O resultado da revisão diz que não passei. O que devo fazer? R: Veja a "Versão de Ação da IA" no relatório, que contém planos de reparo item por item. Corrija por ordem de prioridade (do mais alto para o mais baixo) e, em seguida, execute uma nova revisão para verificar.

P: Meu Skill não tem código Python. Ele pode ser usado? R: Sim. HaluCatch classificará automaticamente como "tipo puramente metodológico", pulando as verificações de fundação e código, com foco na completude das instruções e barreiras.

P: O que fazer se encontrar um erro? R: Consulte a seção "Tratamento de Exceções" acima. 90% dos erros são caminhos escritos incorretamente ou nomes de arquivo não padronizados. Se não conseguir resolver, cole a mensagem de erro para a IA.

💡 Mais perguntas? Consulte o FAQ.md — contém o guia de uso completo, perguntas frequentes e solução de problemas.

Habilidades Relacionadas