@omnizap-system/omnizap 2.5.12

package/app/modules/aiModule/AGENT.md

@@ -0,0 +1,547 @@
+# AiModule Agent Guide
+
+Este arquivo e destinado a agentes de IA para gerar respostas no contexto dos comandos deste modulo.
+
+## Fonte de Verdade
+
+- arquivo_base: `app/modules/aiModule/commandConfig.json`
+- schema_version: `2.0.0`
+- module_enabled: `true`
+- generated_at: `2026-03-11T02:35:17.177Z`
+
+## Escopo do Modulo
+
+- module: `aiModule`
+- source_files:
+- catCommand.js
+- total_commands: `3`
+- total_enabled_commands: `3`
+
+## Defaults Schema v2
+
+- inheritance_mode: deep_merge_with_command_overrides
+- compatibility_mode: legacy_and_v2_fields
+- legacy_field_aliases:
+- descricao: description
+- metodos_de_uso: usage
+- permissao_necessaria: permission
+- local_de_uso: contexts
+- informacoes_coletadas: collected_data
+- pre_condicoes: requirements
+- dependencias_externas: dependencies
+- efeitos_colaterais: side_effects
+- observabilidade: observability
+- privacidade: privacy
+- limite_uso_por_plano: plan_limits
+- argumentos: arguments
+- acesso: access
+- defaults.command:
+- enabled: true
+- category: ia
+- version: 1.0.0
+- stability: stable
+- deprecated: false
+- replaced_by: null
+- risk_level: medium
+- defaults.requirements (legacy view):
+- requer_grupo: nao
+- requer_admin: nao
+- requer_admin_principal: nao
+- requer_google_login: sim
+- requer_nsfw: nao
+- requer_midia: nao
+- requer_mensagem_respondida: nao
+
+## Protocolo de Resposta para IA
+
+- Passo 1: identificar comando pelo token apos o prefixo.
+- Passo 2: resolver alias para nome canonico usando campo `aliases`.
+- Passo 3: validar `enabled`, `pre_condicoes`, permissao e local de uso.
+- Passo 4: se houver erro de uso, responder com `mensagens_uso` (quando existir) ou `metodos_de_uso`.
+- Passo 5: seguir `respostas_padrao` como fallback de texto.
+- Passo 6: considerar `informacoes_coletadas`, `privacidade` e `observabilidade` ao elaborar resposta.
+
+## Regras de Seguranca para IA
+
+- A IA orienta, mas nao executa acao administrativa automaticamente.
+- Nao inventar comandos, subcomandos ou permissao fora do JSON.
+- Sempre informar onde pode usar (grupo/privado) e quem pode usar.
+- Em duvida de permissao, responder com orientacao conservadora.
+
+## Catalogo de Comandos
+
+### ia
+
+- id: ai.ia
+- aliases: cat
+- enabled: true
+- categoria: ia
+- descricao: Perguntas para IA com suporte opcional a resposta em audio.
+- permissao_necessaria: usuario comum
+- version: 1.0.0
+- stability: stable
+- deprecated: nao
+- risk_level: low
+- local_de_uso:
+- privado
+- grupo
+- metodos_de_uso:
+- <prefix>ia sua pergunta
+- <prefix>ia --audio sua pergunta
+- mensagens_uso (variantes):
+- default:
+- _<prefix>ia_ [--audio] sua pergunta
+- _<prefix>ia_ (responda ou envie uma imagem com legenda)
+- Opções:
+- --audio | --texto
+- --detail low | high | auto
+- Exemplo:
+- _<prefix>ia_ Explique como funciona a fotossíntese.
+- _<prefix>ia_ --audio Resuma a imagem.
+- subcomandos:
+- (nenhum)
+- argumentos:
+- prompt | tipo: string | opcional | validacao: texto livre; pode usar contexto de mídia | default: null | posicao: 0
+- flags | tipo: array | opcional | validacao: aliases de áudio/texto suportados | default: null | posicao: 1
+- pre_condicoes:
+- requer_grupo: nao
+- requer_admin: nao
+- requer_admin_principal: nao
+- requer_google_login: sim
+- requer_nsfw: nao
+- requer_midia: nao
+- requer_mensagem_respondida: nao
+- rate_limit:
+- max: null
+- janela_ms: null
+- escopo: sem_rate_limit_explicito
+- acesso:
+- somente_premium: nao
+- planos_permitidos: comum, premium
+- limite_uso_por_plano:
+- comum: max=8, janela_ms=300000, escopo=usuario
+- premium: max=40, janela_ms=300000, escopo=usuario
+- informacoes_coletadas:
+- identificador do chat (remoteJid)
+- identificador do remetente (senderJid)
+- texto do comando e argumentos
+- contexto da mensagem (citacao e mencoes, quando existir)
+- prompt textual enviado ao modelo de IA
+- flags de resposta (ex.: audio/voz)
+- midia anexada/citada para analise multimodal (quando houver)
+- identidade do usuario para sessao e contexto de conversa
+- dependencias_externas:
+- OpenAI API
+- efeitos_colaterais:
+- envia resposta textual/áudio de IA
+- respostas_padrao:
+- success: Comando executado com sucesso.
+- usage_error: Formato de uso inválido. Consulte metodos_de_uso.
+- permission_error: Permissão insuficiente para executar este comando.
+- sucesso: Comando executado com sucesso.
+- erro_uso: Formato de uso inválido. Consulte metodos_de_uso.
+- erro_permissao: Permissão insuficiente para executar este comando.
+- mensagens_sistema:
+- premium*only: ⭐ \_Comando Premium*
+
+Este comando é exclusivo para usuários premium.
+Fale com o administrador para liberar o acesso.
+
+- openai*nao_configurada: ⚠️ \_OpenAI não configurada*
+
+Defina a variável _OPENAI_API_KEY_ no `.env` para usar o comando _cat_.
+
+- imagem_muito_grande: ⚠️ A imagem enviada ultrapassa o limite de {{limite_mb}} MB. Envie uma imagem menor.
+- imagem_download_falhou: ⚠️ Não consegui baixar a imagem. Tente reenviar.
+- resposta_vazia: ⚠️ Não consegui gerar uma resposta agora. Tente novamente.
+- audio_muito_longo: ⚠️ A resposta ficou longa demais para áudio. Enviando em texto.
+- audio_falhou: ⚠️ Não consegui gerar o áudio agora. Enviando texto.
+- erro*openai: ❌ \_Erro ao falar com a IA*
+  Tente novamente em alguns instantes.
+- limites_operacionais:
+- (nao informado)
+- opcoes:
+- toggle_on_off_status.type: toggle
+- toggle_on_off_status.allowed_actions: on, off, status
+- toggle_on_off_status.action_argument: acao
+- add_remove_list.type: list_management
+- add_remove_list.allowed_actions: add, remove, list
+- add_remove_list.action_argument: acao
+- approve_reject.type: moderation_decision
+- approve_reject.allowed_actions: approve, reject
+- approve_reject.action_argument: acao
+- approve_reject.requires_targets: true
+- set_status_reset.type: configuration_window
+- set_status_reset.allowed_actions: set, status, reset
+- set_status_reset.action_argument: valor
+- parse.audio_flags: --audio, --voz, --voice, --tts, -a
+- parse.text_flags: --texto, --text, --txt
+- parse.image_detail_aliases.low: low
+- parse.image_detail_aliases.high: high
+- parse.image_detail_aliases.auto: auto
+- parse.image_detail_aliases.baixo: low
+- parse.image_detail_aliases.baixa: low
+- parse.image_detail_aliases.alto: high
+- parse.image_detail_aliases.alta: high
+- parse.image_detail_aliases.automatico: auto
+- parse.image_detail_aliases.automático: auto
+- observabilidade:
+- event_name: command.executed
+- analytics_event: whatsapp_command_cat
+- tags_log: whatsapp, command, aiModule, cat
+- nivel_log: info
+- privacidade:
+- dados_sensiveis:
+- chat_identifier
+- sender_identifier
+- command_content
+- retencao: standard_app_logs
+- base_legal: service_execution_and_legitimate_interest
+- docs:
+- summary: Perguntas para IA com suporte opcional a resposta em audio.
+- usage_examples: <prefix>ia sua pergunta, <prefix>ia --audio sua pergunta
+- usage*variants.default: *<prefix>ia* [--audio] sua pergunta, *<prefix>ia* (responda ou envie uma imagem com legenda), , Opções:, --audio | --texto, --detail low | high | auto, , Exemplo:, *<prefix>ia* Explique como funciona a fotossíntese., *<prefix>ia\_ --audio Resuma a imagem.
+- behavior:
+- type: argument_driven
+- allowed_actions: (nenhum)
+- limits:
+- usage_description: texto sujeito a limites da API
+- rate_limit.max: null
+- rate_limit.janela_ms: null
+- rate_limit.escopo: sem_rate_limit_explicito
+- access.somente_premium: false
+- access.planos_permitidos: comum, premium
+- plan_limits.comum.max: 8
+- plan_limits.comum.janela_ms: 300000
+- plan_limits.comum.escopo: usuario
+- plan_limits.premium.max: 40
+- plan_limits.premium.janela_ms: 300000
+- plan_limits.premium.escopo: usuario
+- discovery:
+- keywords: ia, ia, privado, grupo
+- faq_queries: como usar ia, o que faz ia, comando ia
+- user_phrasings: quero usar ia, me ajuda com ia, perguntas para ia com
+- suggestion_priority: 100
+- handler:
+- file: catCommand.js
+- method: handleCatCommand
+- command_case: ia
+
+### iaimagem
+
+- id: ai.iaimagem
+- aliases: catimage, catimg
+- enabled: true
+- categoria: ia
+- descricao: Gera/edita imagem com IA por prompt.
+- permissao_necessaria: usuario comum
+- version: 1.0.0
+- stability: stable
+- deprecated: nao
+- risk_level: low
+- local_de_uso:
+- privado
+- grupo
+- metodos_de_uso:
+- <prefix>iaimagem seu prompt
+- <prefix>iaimagem --size 1536x1024 seu prompt
+- mensagens_uso (variantes):
+- default:
+- _<prefix>iaimagem_ seu prompt
+- _<prefix>iaimagem_ (responda uma imagem com legenda para editar)
+- Opções:
+- --size 1024x1024 | 1024x1536 | 1536x1024 | auto
+- --quality low | medium | high | auto
+- --format png | jpeg | webp
+- --background transparent | opaque | auto
+- --compression 0-100
+- Exemplo:
+- _<prefix>iaimagem_ --size 1536x1024 Um gato astronauta em aquarela.
+- subcomandos:
+- (nenhum)
+- argumentos:
+- prompt | tipo: string | opcional | validacao: texto livre para gerar/editar imagem | default: null | posicao: 0
+- size | tipo: string | opcional | validacao: auto|1024x1024|1024x1536|1536x1024 | default: null | posicao: 1
+- quality | tipo: string | opcional | validacao: auto|low|medium|high | default: null | posicao: 2
+- format | tipo: string | opcional | validacao: png|jpeg|webp | default: null | posicao: 3
+- pre_condicoes:
+- requer_grupo: nao
+- requer_admin: nao
+- requer_admin_principal: nao
+- requer_google_login: sim
+- requer_nsfw: nao
+- requer_midia: nao
+- requer_mensagem_respondida: nao
+- rate_limit:
+- max: null
+- janela_ms: null
+- escopo: sem_rate_limit_explicito
+- acesso:
+- somente_premium: sim
+- planos_permitidos: premium
+- limite_uso_por_plano:
+- comum: max=8, janela_ms=300000, escopo=usuario
+- premium: max=40, janela_ms=300000, escopo=usuario
+- informacoes_coletadas:
+- identificador do chat (remoteJid)
+- identificador do remetente (senderJid)
+- texto do comando e argumentos
+- contexto da mensagem (citacao e mencoes, quando existir)
+- prompt de geracao/edicao de imagem
+- opcoes de geracao (size, quality, format, background)
+- imagem enviada/citada para edicao (quando houver)
+- dependencias_externas:
+- OpenAI API
+- efeitos_colaterais:
+- envia imagem gerada/editada por IA
+- respostas_padrao:
+- success: Comando executado com sucesso.
+- usage_error: Formato de uso inválido. Consulte metodos_de_uso.
+- permission_error: Permissão insuficiente para executar este comando.
+- sucesso: Comando executado com sucesso.
+- erro_uso: Formato de uso inválido. Consulte metodos_de_uso.
+- erro_permissao: Permissão insuficiente para executar este comando.
+- mensagens_sistema:
+- premium*only: ⭐ \_Comando Premium*
+
+Este comando é exclusivo para usuários premium.
+Fale com o administrador para liberar o acesso.
+
+- openai*nao_configurada: ⚠️ \_OpenAI não configurada*
+
+Defina a variável _OPENAI_API_KEY_ no `.env` para usar o comando _catimg_.
+
+- imagem_muito_grande: ⚠️ A imagem enviada ultrapassa o limite de {{limite_mb}} MB. Envie uma imagem menor.
+- imagem_download_falhou: ⚠️ Não consegui baixar a imagem. Tente reenviar.
+- opcoes_invalidas: ⚠️ Opções inválidas no comando.
+  Detalhes: {{detalhes}}
+
+Use _{{prefix}}catimg_ sem opções para ver o formato correto.
+
+- resposta_vazia: ⚠️ Não consegui gerar a imagem agora. Tente novamente.
+- erro*openai: ❌ \_Erro ao falar com a IA*
+  Tente novamente em alguns instantes.
+- limites_operacionais:
+- (nao informado)
+- opcoes:
+- toggle_on_off_status.type: toggle
+- toggle_on_off_status.allowed_actions: on, off, status
+- toggle_on_off_status.action_argument: acao
+- add_remove_list.type: list_management
+- add_remove_list.allowed_actions: add, remove, list
+- add_remove_list.action_argument: acao
+- approve_reject.type: moderation_decision
+- approve_reject.allowed_actions: approve, reject
+- approve_reject.action_argument: acao
+- approve_reject.requires_targets: true
+- set_status_reset.type: configuration_window
+- set_status_reset.allowed_actions: set, status, reset
+- set_status_reset.action_argument: valor
+- geracao_imagem.size_options: auto, 1024x1024, 1024x1536, 1536x1024
+- geracao_imagem.size_aliases.1024: 1024x1024
+- geracao_imagem.size_aliases.square: 1024x1024
+- geracao_imagem.size_aliases.quadrado: 1024x1024
+- geracao_imagem.size_aliases.portrait: 1024x1536
+- geracao_imagem.size_aliases.retrato: 1024x1536
+- geracao_imagem.size_aliases.landscape: 1536x1024
+- geracao_imagem.size_aliases.paisagem: 1536x1024
+- geracao_imagem.size_aliases.auto: auto
+- geracao_imagem.quality_options: auto, low, medium, high
+- geracao_imagem.quality_aliases.baixa: low
+- geracao_imagem.quality_aliases.baixo: low
+- geracao_imagem.quality_aliases.media: medium
+- geracao_imagem.quality_aliases.média: medium
+- geracao_imagem.quality_aliases.medio: medium
+- geracao_imagem.quality_aliases.médio: medium
+- geracao_imagem.quality_aliases.alta: high
+- geracao_imagem.quality_aliases.alto: high
+- geracao_imagem.quality_aliases.auto: auto
+- geracao_imagem.format_options: png, jpeg, webp
+- geracao_imagem.format_aliases.jpg: jpeg
+- geracao_imagem.format_aliases.jpeg: jpeg
+- geracao_imagem.format_aliases.png: png
+- geracao_imagem.format_aliases.webp: webp
+- geracao_imagem.background_options: auto, transparent, opaque
+- geracao_imagem.background_aliases.auto: auto
+- geracao_imagem.background_aliases.transparent: transparent
+- geracao_imagem.background_aliases.transparente: transparent
+- geracao_imagem.background_aliases.opaque: opaque
+- geracao_imagem.background_aliases.opaco: opaque
+- geracao_imagem.background_aliases.opaca: opaque
+- geracao_imagem.flag_aliases.size: --size, --tamanho
+- geracao_imagem.flag_aliases.quality: --quality, --qualidade
+- geracao_imagem.flag_aliases.format: --format, --formato
+- geracao_imagem.flag_aliases.background: --background, --fundo
+- geracao_imagem.flag_aliases.compression: --compression, --compressao, --compressão
+- geracao_imagem.compression.min: 0
+- geracao_imagem.compression.max: 100
+- observabilidade:
+- event_name: command.executed
+- analytics_event: whatsapp_command_catimg
+- tags_log: whatsapp, command, aiModule, catimg
+- nivel_log: info
+- privacidade:
+- dados_sensiveis:
+- chat_identifier
+- sender_identifier
+- command_content
+- retencao: standard_app_logs
+- base_legal: service_execution_and_legitimate_interest
+- docs:
+- summary: Gera/edita imagem com IA por prompt.
+- usage_examples: <prefix>iaimagem seu prompt, <prefix>iaimagem --size 1536x1024 seu prompt
+- usage*variants.default: *<prefix>iaimagem* seu prompt, *<prefix>iaimagem* (responda uma imagem com legenda para editar), , Opções:, --size 1024x1024 | 1024x1536 | 1536x1024 | auto, --quality low | medium | high | auto, --format png | jpeg | webp, --background transparent | opaque | auto, --compression 0-100, , Exemplo:, *<prefix>iaimagem\_ --size 1536x1024 Um gato astronauta em aquarela.
+- behavior:
+- type: argument_driven
+- allowed_actions: (nenhum)
+- limits:
+- usage_description: imagem de entrada ate OPENAI_MAX_IMAGE_MB (padrao 50 MB)
+- rate_limit.max: null
+- rate_limit.janela_ms: null
+- rate_limit.escopo: sem_rate_limit_explicito
+- access.somente_premium: true
+- access.planos_permitidos: premium
+- plan_limits.comum.max: 8
+- plan_limits.comum.janela_ms: 300000
+- plan_limits.comum.escopo: usuario
+- plan_limits.premium.max: 40
+- plan_limits.premium.janela_ms: 300000
+- plan_limits.premium.escopo: usuario
+- discovery:
+- keywords: iaimagem, catimage, ia, privado, grupo
+- faq_queries: como usar iaimagem, o que faz iaimagem, comando iaimagem
+- user_phrasings: quero usar iaimagem, me ajuda com iaimagem, gera/edita imagem com ia
+- suggestion_priority: 100
+- handler:
+- file: catCommand.js
+- method: handleCatImageCommand
+- command_case: iaimagem
+
+### pergunteia
+
+- id: ai.pergunteia
+- aliases: iaprompt, promptia, catprompt
+- enabled: true
+- categoria: ia
+- descricao: Define ou reseta o prompt personalizado da IA para o usuario.
+- permissao_necessaria: usuario comum
+- version: 1.0.0
+- stability: stable
+- deprecated: nao
+- risk_level: low
+- local_de_uso:
+- privado
+- grupo
+- metodos_de_uso:
+- <prefix>pergunteia novo prompt
+- <prefix>pergunteia reset
+- mensagens_uso (variantes):
+- default:
+- _<prefix>pergunteia_ seu novo prompt
+- Para voltar ao padrão:
+- _<prefix>pergunteia reset_
+- subcomandos:
+- reset
+- argumentos:
+- conteudo | tipo: string | obrigatorio | validacao: texto do prompt ou reset | default: null | posicao: 0
+- pre_condicoes:
+- requer_grupo: nao
+- requer_admin: nao
+- requer_admin_principal: nao
+- requer_google_login: sim
+- requer_nsfw: nao
+- requer_midia: nao
+- requer_mensagem_respondida: nao
+- rate_limit:
+- max: null
+- janela_ms: null
+- escopo: sem_rate_limit_explicito
+- acesso:
+- somente_premium: nao
+- planos_permitidos: comum, premium
+- limite_uso_por_plano:
+- comum: max=8, janela_ms=300000, escopo=usuario
+- premium: max=40, janela_ms=300000, escopo=usuario
+- informacoes_coletadas:
+- identificador do chat (remoteJid)
+- identificador do remetente (senderJid)
+- texto do comando e argumentos
+- contexto da mensagem (citacao e mencoes, quando existir)
+- prompt personalizado informado pelo usuario
+- identidade do usuario para salvar/atualizar preferencia
+- dependencias_externas:
+- store interno de prompt de IA
+- efeitos_colaterais:
+- salva ou reseta prompt personalizado do usuário
+- respostas_padrao:
+- success: Comando executado com sucesso.
+- usage_error: Formato de uso inválido. Consulte metodos_de_uso.
+- permission_error: Permissão insuficiente para executar este comando.
+- sucesso: Comando executado com sucesso.
+- erro_uso: Formato de uso inválido. Consulte metodos_de_uso.
+- erro_permissao: Permissão insuficiente para executar este comando.
+- mensagens_sistema:
+- premium*only: ⭐ \_Comando Premium*
+
+Este comando é exclusivo para usuários premium.
+Fale com o administrador para liberar o acesso.
+
+- prompt_muito_longo: ⚠️ Prompt muito longo. Limite: {{max_chars}} caracteres.
+- prompt_reset_sucesso: ✅ Prompt da IA restaurado para o padrão.
+- prompt_update_sucesso: ✅ Prompt da IA atualizado para você.
+- limites_operacionais:
+- prompt_max_chars: 2000
+- opcoes:
+- toggle_on_off_status.type: toggle
+- toggle_on_off_status.allowed_actions: on, off, status
+- toggle_on_off_status.action_argument: acao
+- add_remove_list.type: list_management
+- add_remove_list.allowed_actions: add, remove, list
+- add_remove_list.action_argument: acao
+- approve_reject.type: moderation_decision
+- approve_reject.allowed_actions: approve, reject
+- approve_reject.action_argument: acao
+- approve_reject.requires_targets: true
+- set_status_reset.type: configuration_window
+- set_status_reset.allowed_actions: set, status, reset
+- set_status_reset.action_argument: valor
+- observabilidade:
+- event_name: command.executed
+- analytics_event: whatsapp_command_catprompt
+- tags_log: whatsapp, command, aiModule, catprompt
+- nivel_log: info
+- privacidade:
+- dados_sensiveis:
+- sender_identifier
+- command_content
+- retencao: standard_app_logs
+- base_legal: service_execution_and_legitimate_interest
+- docs:
+- summary: Define ou reseta o prompt personalizado da IA para o usuario.
+- usage_examples: <prefix>pergunteia novo prompt, <prefix>pergunteia reset
+- usage*variants.default: *<prefix>pergunteia* seu novo prompt, , Para voltar ao padrão:, *<prefix>pergunteia reset\_
+- behavior:
+- type: subcommand
+- allowed_actions: reset
+- limits:
+- usage_description: 1 prompt por usuario (atualizavel)
+- rate_limit.max: null
+- rate_limit.janela_ms: null
+- rate_limit.escopo: sem_rate_limit_explicito
+- access.somente_premium: false
+- access.planos_permitidos: comum, premium
+- plan_limits.comum.max: 8
+- plan_limits.comum.janela_ms: 300000
+- plan_limits.comum.escopo: usuario
+- plan_limits.premium.max: 40
+- plan_limits.premium.janela_ms: 300000
+- plan_limits.premium.escopo: usuario
+- discovery:
+- keywords: pergunteia, iaprompt, promptia, ia, privado, grupo
+- faq_queries: como usar pergunteia, o que faz pergunteia, comando pergunteia
+- user_phrasings: quero usar pergunteia, me ajuda com pergunteia, define ou reseta o
+- suggestion_priority: 100
+- handler:
+- file: catCommand.js
+- method: handleCatPromptCommand
+- command_case: pergunteia

package/app/modules/aiModule/aiAiHelpService.js

@@ -0,0 +1,14 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createModuleAiHelpWrapper } from '../../services/ai/moduleAiHelpWrapperFactory.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export const aiAiHelpWrapper = createModuleAiHelpWrapper({
+  moduleKey: 'ai',
+  moduleLabel: 'comandos de IA',
+  envPrefix: 'AI_AI_HELP',
+  moduleDirPath: __dirname,
+  moduleNameFallback: 'aiModule',
+});

package/app/modules/aiModule/aiConfigRuntime.js

@@ -0,0 +1,135 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { createModuleCommandConfigRuntime } from '../../services/ai/moduleCommandConfigRuntimeService.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const CONFIG_PATH = path.join(__dirname, 'commandConfig.json');
+
+const DEFAULT_TEXTS = {
+  usage_header: 'Use assim:',
+  premium_only: '⭐ *Comando Premium*\n\nEste comando é exclusivo para usuários premium.',
+  openai_not_configured: '⚠️ *OpenAI não configurada*\n\nDefina a variável *OPENAI_API_KEY* no `.env` para usar este comando.',
+  generic_error: '❌ *Erro ao falar com a IA*\nTente novamente em alguns instantes.',
+};
+
+const runtime = createModuleCommandConfigRuntime({
+  configPath: CONFIG_PATH,
+  fallbackConfig: {
+    module: 'aiModule',
+    commands: [],
+    textos: DEFAULT_TEXTS,
+  },
+});
+
+const normalizeText = (value) =>
+  String(value || '')
+    .trim()
+    .toLowerCase();
+
+const renderUsageMethod = (method, commandPrefix) => String(method || '').replaceAll('<prefix>', String(commandPrefix || '/'));
+
+const resolveUsageLines = (entry, variant) => {
+  if (!entry || typeof entry !== 'object') return [];
+
+  const usageMessages = entry?.mensagens_uso && typeof entry.mensagens_uso === 'object' ? entry.mensagens_uso : null;
+
+  if (usageMessages) {
+    const variantKey = typeof variant === 'string' ? variant.trim() : '';
+    const picked = (variantKey && usageMessages[variantKey]) || usageMessages.default || null;
+    if (Array.isArray(picked)) {
+      return picked.filter(Boolean).map((value) => String(value));
+    }
+    if (typeof picked === 'string' && picked.trim()) {
+      return [picked.trim()];
+    }
+  }
+
+  const methods = Array.isArray(entry?.metodos_de_uso) ? entry.metodos_de_uso : [];
+  return methods.filter(Boolean).map((value) => String(value));
+};
+
+export const getAiModuleConfig = () => runtime.getModuleConfig();
+
+export const resolveAiCommandName = (command) => runtime.resolveCommandName(command);
+export const getAiCommandEntry = (command) => runtime.getCommandEntry(command);
+export const listEnabledAiCommands = () => runtime.listEnabledCommands();
+
+export const getAiTextConfig = () => {
+  const config = getAiModuleConfig();
+  const raw = config?.textos && typeof config.textos === 'object' ? config.textos : {};
+  return {
+    ...DEFAULT_TEXTS,
+    ...raw,
+  };
+};
+
+export const getAiUsageText = (command, { commandPrefix = '/', header, variant } = {}) => {
+  const entry = getAiCommandEntry(command);
+  const methods = resolveUsageLines(entry, variant);
+  if (!methods.length) return '';
+
+  const prefixHeader = typeof header === 'string' ? header : getAiTextConfig().usage_header || DEFAULT_TEXTS.usage_header;
+  const lines = methods.map((method) => renderUsageMethod(method, commandPrefix));
+  return [prefixHeader, ...lines].join('\n');
+};
+
+export const isAiCommandPremiumOnly = (command) => {
+  const entry = getAiCommandEntry(command);
+  return Boolean(entry?.acesso?.somente_premium);
+};
+
+export const getAiCommandSystemMessages = (command) => {
+  const entry = getAiCommandEntry(command);
+  const raw = entry?.mensagens_sistema && typeof entry.mensagens_sistema === 'object' ? entry.mensagens_sistema : {};
+  return raw;
+};
+
+export const getAiCommandOperationalLimits = (command) => {
+  const entry = getAiCommandEntry(command);
+  const raw = entry?.limites_operacionais && typeof entry.limites_operacionais === 'object' ? entry.limites_operacionais : {};
+  return raw;
+};
+
+const normalizeMapKeys = (value = {}) => {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
+  const output = {};
+  for (const [key, mapValue] of Object.entries(value)) {
+    const normalizedKey = normalizeText(key);
+    if (!normalizedKey) continue;
+    output[normalizedKey] = String(mapValue ?? '').trim();
+  }
+  return output;
+};
+
+export const getAiCommandOptionConfig = (command) => {
+  const entry = getAiCommandEntry(command);
+  const options = entry?.opcoes && typeof entry.opcoes === 'object' ? entry.opcoes : {};
+
+  const parse = options?.parse && typeof options.parse === 'object' ? options.parse : {};
+  const generation = options?.geracao_imagem && typeof options.geracao_imagem === 'object' ? options.geracao_imagem : {};
+
+  return {
+    parse: {
+      audio_flags: Array.isArray(parse.audio_flags) ? parse.audio_flags.map((item) => String(item || '')).filter(Boolean) : [],
+      text_flags: Array.isArray(parse.text_flags) ? parse.text_flags.map((item) => String(item || '')).filter(Boolean) : [],
+      image_detail_aliases: normalizeMapKeys(parse.image_detail_aliases || {}),
+    },
+    geracao_imagem: {
+      size_options: Array.isArray(generation.size_options) ? generation.size_options.map((item) => normalizeText(item)).filter(Boolean) : [],
+      size_aliases: normalizeMapKeys(generation.size_aliases || {}),
+      quality_options: Array.isArray(generation.quality_options) ? generation.quality_options.map((item) => normalizeText(item)).filter(Boolean) : [],
+      quality_aliases: normalizeMapKeys(generation.quality_aliases || {}),
+      format_options: Array.isArray(generation.format_options) ? generation.format_options.map((item) => normalizeText(item)).filter(Boolean) : [],
+      format_aliases: normalizeMapKeys(generation.format_aliases || {}),
+      background_options: Array.isArray(generation.background_options) ? generation.background_options.map((item) => normalizeText(item)).filter(Boolean) : [],
+      background_aliases: normalizeMapKeys(generation.background_aliases || {}),
+      flag_aliases: generation.flag_aliases && typeof generation.flag_aliases === 'object' ? Object.fromEntries(Object.entries(generation.flag_aliases).map(([key, value]) => [normalizeText(key), Array.isArray(value) ? value.map((item) => normalizeText(item)).filter(Boolean) : []])) : {},
+      compression: {
+        min: Number(generation?.compression?.min ?? 0),
+        max: Number(generation?.compression?.max ?? 100),
+      },
+    },
+  };
+};