feat(vision): add configurable image analysis model and workspace file editing
- Add VISION_MODEL and VISION_PROVIDER env options with openrouter default and provider auto-detection from the model id - Add /veriavision, /configiavision and /about commands - Support natural-language editing of files inside workspace/ and a /baixar command to download them - Replace config-based timezone with system-local time detection - Add module version/author/license metadata - Document development conventions in new RULES.md and update README.md/DEPLOY.md with the new commands and env vars
This commit is contained in:
@@ -0,0 +1,289 @@
|
||||
# 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*
|
||||
Reference in New Issue
Block a user