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*