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

.env

@@ -39,6 +39,10 @@ MAX_HISTORY_LENGTH=50
 WEB_SEARCH_ENABLED=true
 WEB_SEARCH_MAX_RESULTS=5
 
+# Vision / image analysis model
+VISION_MODEL=meta-llama/llama-4-maverick-17b-128e-instruct
+VISION_PROVIDER=openrouter
+
 # Upload file context max characters sent to AI (0 = no truncation)
 UPLOAD_CONTEXT_MAX_CHARS=0
 

DEPLOY.md

@@ -197,6 +197,8 @@ Nomes recomendados para evitar conflito:
 | `AUTO_ENRICH_EVERY` | não | Enriquece perfil a cada N mensagens |
 | `AUTO_IMPROVE_EVERY` | não | Melhoria automática a cada N mensagens |
 | `UPLOAD_CONTEXT_MAX_CHARS` | não | Limite de caracteres do upload enviado para a IA (`0` = sem limite) |
+| `VISION_MODEL` | não | Modelo de IA para análise de imagens |
+| `VISION_PROVIDER` | não | Provider do modelo de visão (`openrouter`, `stepfun`, `qwencloud`) |
 
 ---
 
@@ -204,6 +206,9 @@ Nomes recomendados para evitar conflito:
 
 - `/veria` — mostra o provider e o modelo de IA atuais
 - `/configia` — configura interativamente o provider e o modelo de IA
+- `/veriavision` — mostra o provider e o modelo de visão atuais
+- `/configiavision` — configura interativamente o modelo de visão
+- `/about` — exibe informações do sistema, versão, autor e licença
 
 ---
 

README.md

@@ -75,6 +75,19 @@ O script cria o ambiente virtual, instala dependências e inicia o agente.
 - `/cancelar` — cancela operação em andamento
 - `/veria` — mostra o provider e o modelo de IA atuais
 - `/configia` — configura interativamente o provider e o modelo de IA com seleção por botões
+- `/about` — exibe informações do sistema, versão, autor e licença
+- `/veriavision` — mostra o provider e o modelo de visão atuais
+- `/configiavision` — configura interativamente o modelo de visão com seleção por botões
+- `/baixar <nome>` — baixa um arquivo do workspace pelo nome
+
+## Editando arquivos do workspace
+
+Você pode pedir para editar arquivos existentes no `workspace/` usando comandos como:
+- `edite o arquivo teste.txt e adicione uma linha 4`
+- `modifique o arquivo hello.py para imprimir hello world`
+- `no arquivo teste.txt troque Linha 2 por Linha 2 editada`
+
+O Agent irá localizar o arquivo, aplicar a alteração solicitada e salvar o resultado.
 - `/incluirnomeuperfil <nome>` — atualiza seu nome no perfil
 - `/incluirnoperfildoagent <texto>` — adiciona características ao perfil do agente
 

RULES.md

@@ -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*

config.json

@@ -11,6 +11,5 @@
     ],
     "start_time": "06:00",
     "end_time": "23:30"
-  },
+  }
-  "timezone": "America/Sao_Paulo"
 }