Skip to main content
O dev-vpop é o pacote Pi de desenvolvimento mantido pela IplanRio. Ele transforma o Pi Agent neutro em um assistente com doutrina de engenharia própria: como planejar, testar, revisar, depurar e entregar software no contexto municipal. A versão v1 atende times técnicos: pessoas desenvolvedoras, arquitetas e de infraestrutura das secretarias e da própria IplanRio. Não é um pacote de análise de dados nem de uso administrativo. Instalação e pré-requisitos estão no guia do Pi Agent.

​
Casos de Uso Municipais

  • SMS: revisar um pull request de integração de prontuário com achados por severidade antes do merge
  • SME: planejar a migração de um serviço de matrícula em passos atômicos com gates e caminho de reversão
  • IplanRio: diagnosticar falha de conectividade em cluster GKE em modo somente leitura, sem escrita acidental
  • Qualquer secretaria: auditar entrega de fornecedor com régua comparável e evidência em arquivo e linha

​
Skills

O pacote traz 12 skills. O agente carrega uma por vez, sob demanda, para não desperdiçar contexto. Comandos em pt-BR acionam os fluxos mais comuns: /planejar, /revisar, /depurar, /retomar e /encerrar.

​
Agentes

São 5 agentes especializados, cada um com modelo e permissões próprias. Agentes somente leitura não editam arquivos nem publicam nada. Nenhum agente delega para outro agente. A orquestração fica com a sessão principal, o que mantém o rastro de decisão em um lugar só.
Efeito externo pede confirmação explícita: escrita em ambiente compartilhado, publicação, exclusão, push, deploy e mudança de infraestrutura. Diagnóstico é livre.

​
Modelos e Política de Custo

A política é custo primeiro: comece pelo modelo mais barato que resolve e suba de faixa apenas quando conseguir nomear a lacuna que a faixa atual não cobre. O modelo padrão é o GPT-5.6 Luna, com nível de raciocínio baixo. Ele cobre a maior parte do trabalho diário: ler código, responder dúvidas, editar arquivos conhecidos, escrever commit.
O pacote não troca de modelo sozinho. A escalada é sempre explícita: ou a pessoa muda o modelo da sessão, ou quem despacha o trabalho escolhe o agente da faixa adequada. Nenhum relatório deve afirmar que houve seleção automática de custo.
Todos os modelos passam pelo Bifrost com a sua Virtual Key, então os limites diários de cota valem igual aos do OpenCode.

​
Contexto e Sessões

O Pi faz compactação nativa da conversa quando a janela aperta. A configuração recomendada reserva 24.576 tokens para a compactação e preserva 24.000 tokens de histórico recente. Além disso, o pacote faz poda de contexto: resultados antigos de ferramentas acima de 24.000 bytes são truncados no meio, mantendo início e fim. O limite é ajustável por projeto em context-budget.json, dentro do diretório de configuração do projeto, e só é aplicado em projeto confiável.

​
Retenção de sessões

Uma vez por dia, no início de uma sessão, o pacote limpa o histórico local:
  • Sessões com mais de 30 dias são removidas
  • Mesmo vencidas, as 20 sessões mais recentes de cada projeto são preservadas
  • Sessões nomeadas são preservadas até remoção explícita
  • A remoção usa a lixeira do sistema quando disponível
  • Sem lixeira compatível, o arquivo vai para uma quarentena dentro da raiz de sessões
A execução automática nunca apaga permanentemente. Remoção definitiva exige o comando explícito session-gc --purge. Sessões locais podem conter trechos de código e caminhos de arquivo, então a retenção curta reduz superfície de exposição.

​
MCP Sob Demanda

O pacote registra uma única ferramenta mcp que funciona como despachante preguiçoso, com as ações list, search, describe e call. Nenhum servidor sobe no início da sessão: o processo ou a conexão só é aberta quando uma chamada realmente precisa dela. Isso mantém o prompt enxuto. Em vez de dezenas de ferramentas descritas no contexto o tempo todo, o agente descobre o que existe apenas quando a tarefa exige. Todos os servidores vêm desabilitados por padrão em ~/.pi/agent/mcp.json:

​
Habilitar um servidor

Edite ~/.pi/agent/mcp.json e troque enabled para true no servidor desejado:
Os campos headers e env guardam nomes de variáveis de ambiente, nunca o segredo em si. No exemplo acima, o valor do header Authorization é lido de ATLASSIAN_MCP_AUTHORIZATION em tempo de execução. Token escrito direto no arquivo é vazamento de credencial.
Exporte a variável no seu shell antes de abrir o Pi:
Confira o que está ativo com a ação list da ferramenta mcp dentro do agente.

​
Diagnósticos de Código

A ferramenta vpop_diagnostics executa verificações do próprio projeto com escopo file ou project e devolve os erros normalizados em um formato único. Ela usa os comandos que o repositório já tem, como compilador, type checker e linter. Isso não é um LSP completo. Não há go-to-definition, find-references nem rename: a versão v1 entrega apenas a costura de diagnóstico, projetada para receber um backend LSP completo em versão futura sem mudar a interface da ferramenta. Em projeto não confiável a ferramenta não executa comandos do repositório.

​
Diagnóstico da Instalação

O comando é determinístico e não chama modelo algum, então roda sem consumir cota. Ele verifica Node, versão do Pi, diretório do agente, credencial, settings.json, pacote instalado, mcp.json, modelos registrados, sessões, alcance do Bifrost e isolamento em relação a outras ferramentas de IA. O código de saída distingue sucesso, aviso e falha, o que permite usar o relatório como evidência em chamado de suporte.

​
Atualizações

O pacote se atualiza sozinho. A cada início de sessão o agente consulta o catálogo da IplanRio, no máximo uma vez a cada 24 horas, e instala a versão nova quando ela existe.
Reinicie o Pi para ativar a versão baixada. Sem rede, o agente registra o estado offline na barra de status e segue funcionando com a versão instalada. Atualizar o binário do Pi ou aplicar novas configurações recomendadas exige reexecutar o instalador, descrito no guia do Pi Agent.

​
Segurança e LGPD

  • A credencial fica em ~/.pi/agent/dev-vpop.credential.json com permissão 600, e o diretório com 700
  • O instalador valida SHA-256 de si mesmo, das configurações e dos metadados; o atualizador fixa o pacote por SHA de commit e verifica a árvore instalada
  • O Pi é instalado com --ignore-scripts, o que impede execução de script de pós-instalação de dependência
  • Segredos de MCP entram por variável de ambiente, nunca no arquivo de configuração
  • Skill vpop-security orienta tratamento de dado pessoal em log, resposta de API e mensagem de erro
Dado pessoal de cidadão é regido pela LGPD. Não cole CPF, prontuário, endereço nem qualquer base identificável no prompt do agente: use identificador anônimo ou amostra sintética ao pedir ajuda com uma consulta ou pipeline.
Conteúdo lido pelo agente é dado, não instrução. Página web, saída de ferramenta e arquivo de terceiro informam a decisão, mas nunca autorizam uma ação.

​
Troubleshooting

Comandos /vpop:* não aparecem: o pacote não foi carregado. Confirme a entrada do pacote na lista packages de ~/.pi/agent/settings.json e reinicie o Pi. No Pi sessions found no doctor: instalação nova, sem histórico. É aviso, não erro. MCP retorna erro de autenticação: a variável de ambiente do servidor não está exportada na sessão de terminal que abriu o Pi. Exporte e reabra o agente. Servidor MCP não aparece na ação list: ele continua com enabled: false no mcp.json. Erro de cota do Bifrost: o limite diário da Virtual Key acabou. Troque para um modelo da faixa econômica ou peça ampliação em #peça-permissão. vpop_diagnostics não retorna nada: o projeto não é confiável na sessão atual, ou o repositório não expõe comando de verificação reconhecível. Sessões sumiram: a limpeza diária moveu sessões elegíveis para a lixeira ou para .session-gc-quarantine dentro da raiz de sessões. Recupere por uma dessas duas fontes.

Instalar o Pi Agent

Pré-requisitos, comando de instalação, catálogo de pacotes e desinstalação

OpenCode

Agente alternativo em terminal, com a mesma Virtual Key Bifrost