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 para | Não adequado para |
|---|---|
| Avaliar se um skill pode falhar quando executado por IA | Revisão de segurança cibernética (SQL injection, XSS, etc.) |
| Verificar se o pipeline de dados é confiável | Revisão de conformidade (GDPR, regulamentações de privacidade, etc.) |
| Identificar ambiguidades em regras de negócio em linguagem natural | A 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 implementadas | Otimização de desempenho de código |
| Fornecer recomendações de reparo e scripts de esqueleto | Substituir 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.pypara 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ível | Tarefa | Executor | Princípio |
|---|---|---|---|
| L1 | Varredura de arquivos | halucatch_core.py --validate | Alta determinismo, script é mais rápido e preciso |
| L2 | Verificação de fundação + código + regras + barreiras | Script obtém linha de base JSON → você complementa a análise | Correspondência regex pelo script, interpretação contextual por você |
| L3 | Geração de três versões de relatório | halucatch_core.py gera e salva, você lê e exibe ao usuário | reporter.py tem alto determinismo, formato consistente, zero alucinação — você só faz a complementação semântica |
Princípio central:
halucatch_core.pycobre 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ção | Necessidade | Descrição |
|---|---|---|
| Ler diretório alvo do Skill | Leitura | Ler recursivamente todos os arquivos |
| Escrever arquivos de relatório | Escrita | Apenas no diretório reports/, não modifica o Skill alvo |
| Executar script Python | Bash | Apenas 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 arquivo | Obrigatório | Descriçã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
.pyno 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 diz | Açã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ário | Parâmetro | Exemplo |
|---|---|---|
| Chinês (Simplificado/Tradicional) | --lang zh-CN | python3 halucatch_core.py --skill-dir <caminho> --lang zh-CN |
| Inglês | --lang en | python3 halucatch_core.py --skill-dir <caminho> --lang en |
| Incerto | Nã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.pycompleta 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ção | Formato de saída |
|---|---|
| Lista de nomes de arquivos | Tabela (nome/tamanho/tipo) |
| Número total de linhas do SKILL.md | Número |
| Número de linhas do(s) arquivo(s) .py (se houver) | Número |
| Lista de arquivos de dados | Tabela |
| Nome e descrição do Skill | Extraí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ção | Critério de aprovação |
|---|---|
| Script .py consolidado presente | O script existe na pasta |
| Caminhos parametrizados | Número de caminhos codificados = 0 |
| Pré-verificação de nomes de colunas/validação de entrada | Existe função check_columns ou similar |
| Modo validate | Existe modo --validate ou similar |
| Mecanismo de descoberta de arquivos | Usa glob/wildcards em vez de nomes de arquivo fixos |
| Declaração de dependências | Pacotes Python necessários declarados no SKILL.md |
| skiprows parametrizado | Nú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ção | Padrão de alto risco | Comportamento de possível alteração incorreta pela IA |
|---|---|---|
| Funções estatísticas | Fórmula de p-value personalizada, cálculo de Z-score | Substituir por scipy.stats / ajustar constantes |
| Correspondência de strings | Analisar porcentagem em clean_rate() | Substituir replace('%','') por uma sintaxe diferente |
| Comparação de ponto flutuante | == 0 / == 1 | Mudar para math.isclose() (semântica diferente) |
| Tratamento de exceções | except: pass genérico | Mudar para tipo de exceção específico |
| Lógica condicional | (condição).sum() > 0 | Mudar para .any(axis=1) (comportamento diferente) |
| Lógica de agregação | unstack(fill_value=0) | Remover fill_value (propagação de NaN) |
| Limpeza de dados | Sem instruções de conversão de tipo de dados | Pode 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ção | Risco |
|---|---|
| Definições de canal/classificação claramente listadas | Ambiguidade → IA adivinha por conta própria |
| Valores atípicos/condições de contorno definidos | Omissã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) documentadas | Não documentado → lógica de negócio crítica perdida |
| Convenções de nomes de arquivos/nomes de colunas/formatos de dados | Nã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ção | Gravidade |
|---|---|
| Proibição de linguagem causal | Ausente → 🔴 Grave |
| Framework de quatro quadrantes/tamanho do efeito | Ausente → 🟠 Alta |
| Mecanismo de auto-verificação (self-check) | Ausente → 🟠 Alta |
| Aviso de comparação múltipla | Ausente → 🟠 Alta |
| Modelo de declaração de limitação | Ausente → 🟠 Alta |
| Saída de status por etapas | Ausente → 🟡 Média |
| Impressão de resumo estatístico de dados | Ausente → 🟡 Média |
| Definição de formato de saída | Ausente → 🟡 Média |
Classificação: 🟢 Completo / 🟡 Com itens ausentes / 🔴 Sem barreiras
2b. Avaliação de Skill Tipo Puramente Metodológico
| Item de verificação | Descrição |
|---|---|
| Completude das instruções | Cada etapa tem entrada/saída/condição de decisão claras |
| Casos de borda | Existe tratamento de ramificação anômala "se... então..." |
| Reprodutibilidade | IAs diferentes chegarão à mesma conclusão? |
| Orientação por exemplos | Inclui exemplos concretos para ilustrar a saída esperada? |
| Definição de formato de saída | A estrutura de saída da IA é restrita? |
| Auto-verificação | O 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.pyou 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:
- Ler os arquivos de relatório gerados pelo script
- Exibir a versão padrão no diálogo
- 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.
- Execute
halucatch_core.py --skill-dir <caminho>→ O script completa automaticamente a varredura L1 + avaliação L2 + geração de relatório L3 - Três arquivos
.mdsão gravados no diretórioHaluCatch/reports/(ou no caminho especificado por--output-dir) - Apenas a versão padrão é exibida no diálogo (linguagem simples, sem jargões)
- 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)?"
- 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)
- 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 original | A IA precisa avaliar |
|---|---|
| 🔴 Bloqueante | Quão grave é esse risco no contexto real do negócio? Realmente levaria à falha de execução? Qual a prioridade de reparo? |
| 🟠 Alto risco | O contexto realmente constitui um risco? Há possibilidade de falso positivo do script? O plano de reparo precisa ser detalhado? |
| 🟡 Aviso | A 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:
- Executar reparo — Envie o plano de reparo para sua IA, que modificará o Skill alvo de acordo com o plano
- Não executar — Não fazer nenhuma alteração, encerrar esta revisão
- 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-dirpara 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 diz | Açã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 diz | Açã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)
| Plataforma | Escrita correta | ❌ Escrita incorreta |
|---|---|---|
| Claude Code / Geral | /caminho/para/skill | C:\caminho\para\skill |
| Kimi / WeChat Mini Program | skills/nome-do-projeto/ | ~/skills/nome-do-projeto/ |
| Cursor / VS Code | Arraste a pasta para a caixa de diálogo | Digitar 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 erro | Causa | Método de correção |
|---|---|---|
❌ SKILL.md não encontrado | Diretório alvo não existe ou não tem arquivo .md | Confirmar 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 encontrado | O 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 ignorado | O 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ência | Manter apenas os arquivos principais (SKILL.md + script .py), colocar arquivos de dados e dependências em .halucatch-ignore |
⏱️ Revisão excedeu o tempo limite | Muitos arquivos ou tempo de execução do script muito longo | Informar a IA: "Revise apenas o SKILL.md e os arquivos .py principais" |
Classificação de erros
| Nível | Comportamento |
|---|---|
| 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ário | Estraté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 rede | Halucatch não inicia requisições de rede, 100% offline |
| Problemas de codificação | Tentar UTF-8 primeiro → depois tentar locale do sistema → se falhar, ignorar e registrar |
| Diretório ilegível | Relatar 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ívoco | Entendimento 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.