PsAgentAI/RULES.md

PsAgentAI - Regras de Desenvolvimento

Regras oficiais para IAs e desenvolvedores codarem o sistema PsAgentAI de forma correta, padronizada e segura.

---

1. Visão Geral do Projeto

• Nome: PsAgentAI
• Tipo: Bot Telegram de agente de IA conversacional
• Linguagem: Python 3.9+
• Framework: python-telegram-bot (v20+)
• Arquivo principal: psagentai_agent.py
• Propósito: Companheiro pessoal conversacional com memória, perfis, workspace de arquivos, análise de imagens, pesquisa web e automações.

Regra básica

Toda alteração deve preservar o comportamento existente a menos que o usuário solicite explicitamente uma mudança. Alterações estruturais devem ser validadas com python3 -m py_compile psagentai_agent.py.

---

2. Padrões de Código

2.1 Estilo

• Siga o estilo já estabelecido no psagentai_agent.py.
• Use aspas duplas para strings curtas e mensagens; aspas simples apenas quando houver aspas duplas dentro.
• Indentação: 4 espaços.
• Nomes de funções/arquivos: snake_case.
• Constantes globais em UPPER_CASE.
• Comentários em português do Brasil quando necessário; evite comentários óbvios.
• Mantenha logs print("[LABEL] ...") apenas onde já existirem; não adicione novos logs sem necessidade.

2.2 Estrutura do arquivo principal

Mantenha a ordem lógica:

1. Imports
2. Variáveis globais e constantes
3. Funções utilitárias
4. Funções de profile/context/workspace
5. Handlers de comandos
6. Handlers de mensagens/voz/foto/documento
7. process_text_message
8. Funções de criação/edição de arquivos
9. Registro de handlers e main()

Novos handlers devem ser adicionados próximos a funcionalidades similares já existentes.

2.3 Imports

• Agrupe imports padrão, de terceiros e locais.
• Não adicione dependências sem verificar se já existem no requirements.txt.
• Se precisar de uma nova dependência, atualize requirements.txt e comunique.

---

3. Convenções de Comandos e Handlers

3.1 Nomenclatura

• Funções de comando: <nome>_command (ex: help_command, manualdeuso_command).
• Handler registration: CommandHandler("nome", nome_command).
• Nomes de comando em minúsculas, sem espaços, em português quando for comando voltado ao usuário final.

3.2 Registro de handlers

• Sempre adicione o CommandHandler na seção apropriada de setup_handlers().
• Mantenha a ordem existente: primeiro comandos, depois callbacks, depois mensagens de mídia, depois MessageHandler(filters.TEXT & ~filters.COMMAND, message_handler).
• Nunca registre handlers duplicados para o mesmo comando.

3.3 Comportamento de comandos

• Todos os handlers de comando devem chamar await auto_detect_chat_id(update) no início, exceto onde já houver tratamento explícito.
• Respostas devem usar await update.message.reply_text(...) ou await context.bot.send_message(...) quando necessário.
• Use ParseMode.HTML apenas quando realmente precisar de formatação.

---

4. Gerenciamento de Perfis

4.1 Arquivos

• user_profile.json — perfil do usuário.
• agent_profile.json — perfil do agente.
• Nunca crie novos arquivos de perfil sem necessidade.

4.2 Atualização de perfis

• Use as funções existentes: load_user_profile(), save_user_profile(), load_agent_profile(), save_agent_profile().
• Atualizações parciais devem mesclar com o conteúdo existente, não sobrescrever campos inteiros sem leitura prévia.
• Triggers de atualização natural devem usar handle_profile_update_if_triggered() sempre que possível.

4.3 Onboarding

• Mantenha o fluxo de onboarding existente.
• Novas perguntas de onboarding devem ser adicionadas ao dicionário ONBOARDING_QUESTIONS ou à lógica existente, não criando fluxos paralelos.

---

5. Contexto de Conversa

5.1 Diretório

• Contextos são salvos em contexts/YYYY-MM-DD.json.
• Use load_context() e add_to_context() para manipular contexto.
• Nunca acesse diretamente o arquivo de contexto sem usar as funções auxiliares.

5.2 Limites

• Respeite os limites de tokens configurados no .env.
• Funções de limpeza de contexto devem usar remove_old_messages() ou equivalente, não reescrever o arquivo manualmente.

---

6. Workspace e Arquivos

6.1 Diretórios

• workspace/ — armazena uploads, imagens e arquivos criados/editados.
• workspace/projects/ — projetos criados pelo usuário.
• Nunca crie pastas adicionais dentro de workspace/ sem necessidade explícita.

6.2 Funções obrigatórias

Use sempre as funções auxiliares existentes:

• ensure_workspace_dirs() — cria diretórios necessários.
• save_workspace_file(filename, content) — salva arquivo no workspace.
• build_workspace_tree() — gera árvore visual do workspace.
• _find_workspace_file(target) — localiza arquivo por nome parcial.
• _looks_like_create_request() / _handle_create_request() — cria arquivos via IA.
• _looks_like_edit_request() / _handle_edit_request() — edita arquivos via IA.

6.3 Metadados

• Atualize uploads_metadata.json quando necessário.
• Metadados devem conter: original_name, filepath, chat_id, summary, full_text, type.

---

7. Integração com IA

7.1 Providers suportados

• openrouter
• stepfun
• qwencloud
• llamacpp (local)

7.2 Uso

• Sempre use AIProvider.chat(model, messages, ...) para chamadas de IA.
• Não chame APIs diretamente; use a camada de abstração existente.
• Modelos padrão vêm do .env: DEFAULT_MODEL, VISION_MODEL, etc.
• Novos modelos devem ser adicionados às listas em psagentai_agent.py quando houver suporte explícito.

7.3 Prompts

• System prompt é gerado por build_system_prompt().
• Não altere o system prompt sem necessidade; se alterar, preserve as seções de data/hora, perfil do usuário e perfil do agente.
• Para tarefas específicas (edição de arquivo, criação, análise), crie prompts separados e claros.

---

8. Pesquisa na Internet

8.1 Funções

• _web_search() — executa busca no DuckDuckGo HTML.
• _looks_like_search_request() — detecta intenção de busca.
• Triggers estão em _WEB_SEARCH_TRIGGERS.

8.2 Regras

• Não ative pesquisa web automaticamente para todo tipo de pergunta.
• Respeite a diretriz IMPORTANTE SOBRE INFORMAÇÕES ATUALIZADAS no system prompt.
• Limite de resultados vem do .env (WEB_SEARCH_MAX_RESULTS).

---

9. Análise de Imagens e Visão

• Funções: encode_image_to_base64(), analyze_image(), save_image_to_workspace().
• Comandos: /veriavision, /configiavision.
• Configuração via .env: VISION_MODEL, VISION_PROVIDER.
• Imagens enviadas como documento preservam o nome original.

---

10. Agendamento e Rotina

10.1 Arquivos

• config.json — armazena agendamentos.
• Não adicione campos obsoletos (ex: timezone foi removido; use horário do servidor).

10.2 Regras

• O Agent SEMPRE usa o horário do servidor (datetime.now().astimezone()).
• /fusohorario é apenas informativo, não permite alteração.
• get_timezone() sempre retorna o timezone do servidor; set_timezone() retorna False.

---

11. Segurança

• Nunca commite .env, chaves de API, tokens ou dados sensíveis.
• Use variáveis de ambiente para segredos.
• Preserve emails e telefones em perfis e contextos sem expô-los em logs.
• Valide caminhos de arquivo para evitar path traversal.

---

12. Testes e Validação

12.1 Obrigatório

• Após alterações em psagentai_agent.py: python3 -m py_compile psagentai_agent.py.
• Teste cenários básicos com scripts Python inline quando possível.
• Não quebre funcionalidades existentes (ex: criação/edição de arquivos, perfis, comandos).

12.2 Testes manuais recomendados

• /start, /ajuda, /manualdeuso, /about
• Criação de arquivo: "crie um arquivo teste.txt com conteúdo X"
• Edição de arquivo: "edite o arquivo teste.txt e adicione Y"
• Envio de foto e análise
• Envio de voz e transcrição
• Pesquisa web: "pesquise sobre X"
• Configuração de IA: /veria, /configia

---

13. Documentação

13.1 Arquivos obrigatórios

• README.md — documentação principal, comandos, funcionalidades.
• DEPLOY.md — guia de deploy em servidor.
• RULES.md — este arquivo, regras de desenvolvimento.
• LICENSE — licença proprietária.

13.2 Atualização

• Sempre atualize README.md quando adicionar comandos ou funcionalidades.
• Atualize DEPLOY.md se houver mudanças em variáveis de ambiente ou estrutura.
• Este arquivo (RULES.md) deve ser atualizado quando novas regras forem definidas.

---

14. Git e Workflow

14.1 Commits

• Mensagens curtas e descritivas em português ou inglês técnico.
• Commits devem refletir uma mudança lógica por vez.
• Não faça commits automáticos sem revisão.

14.2 Branches

• Trabalhe na branch principal ou crie branches para features específicas.
• Não faça force push sem autorização.

---

15. Idioma e Comunicação

• Interface do bot: português do Brasil.
• Respostas do Agent: português do Brasil.
• Logs e código: inglês técnico para nomes de variáveis/funções; português para mensagens ao usuário.
• Documentação: português do Brasil.

---

16. Regras Específicas do PsAgentAI

16.1 Nunca faça

• Remover funcionalidades existentes sem solicitação explícita.
• Alterar o .env sem aviso.
• Modificar estrutura de pastas (workspace/, contexts/) sem necessidade.
• Introduzir dependências pesadas sem justificativa.
• Usar input() ou interações bloqueantes no código do bot.

16.2 Sempre faça

• Preserve compatibilidade com versões anteriores de perfis e contextos.
• Trate erros de forma graceful (try/except com logs).
• Use logger para erros graves; use print() apenas para debug existente.
• Valide entradas do usuário antes de processar.
• Forneça feedback ao usuário em caso de erro ("Erro ao processar. Tente novamente.").

16.3 Integração de novas funcionalidades

1. Entenda o fluxo existente antes de adicionar código.
2. Crie funções pequenas e específicas.
3. Integre no ponto correto do process_text_message ou handlers.
4. Registre handlers na ordem correta.
5. Atualize a documentação.
6. Valide com py_compile e testes manuais.

---

17. Versionamento

• Versão atual: 1.0.0
• Incremente a versão em __version__ quando houver mudanças relevantes.
• Atualize o CHANGELOG se existir; senão, documente no commit.

---

18. Contato e Suporte

• Sistema desenvolvido por: Syspanel.com.br
• Autor: Marco A. S. Costa
• Email: contato@syspanel.com.br
• Licença: Proprietária para syspanel.com.br

---

Última atualização: Outubro 2026