MÓDULO 1.1

🧠 O que é o openpcbot v3

Um Jarvis que cabe na sua máquina: assistente pessoal multicanal com fila durável em SQLite, cérebro com memória PT-BR e custo medido em toda chamada.

6
Tópicos
50
Minutos
Essencial
Nível
Fundamento
Tipo
Progresso do módulo 1.1 0%
0 de 0
1

📡 Um assistente com três portas de entrada

O openpcbot v3 é um assistente pessoal multicanal. Multicanal quer dizer que a mesma cabeça atende por três portas: o Telegram (o bot @inemav3bot), a linha de comando da sua máquina e uma porta HTTP local. Você escolhe por onde falar, a resposta sai pelo mesmo lugar de onde veio.

🆕 Novo aqui?

  • Canal: um jeito de conversar com o bot. Telegram, terminal e HTTP são canais diferentes do mesmo assistente.
  • CLI: a linha de comando, aquele terminal preto onde você digita comandos. No v3 é npm run cli.
  • HTTP: o jeito que programas conversam entre si na rede. Aqui é um endereço local que aceita uma mensagem e devolve a resposta.
  • systemd: o programa do Linux que liga serviços sozinho e reinicia quando caem. O v3 roda como serviço de usuário chamado openpcbotv3.

◆ Conceito principal

As três portas existem para que o assistente nunca fique inacessível. Se o Telegram estiver fora, o CLI continua. O serviço sobe mesmo sem token do Telegram, servindo só HTTP em 127.0.0.1:3142 e o CLI.

  • •Telegram: responde só ao chat autorizado em ALLOWED_CHAT_ID.
  • •CLI: npm run cli -- "mensagem", sem sair da máquina.
  • •HTTP: POST /mensagem com {"texto":"..."}, mais o painel em /.

✦ Dica prática

A porta HTTP escuta em 127.0.0.1 por padrão, ou seja, só a sua máquina alcança. Expor na rede local exige HTTP_BIND_V3=0.0.0.0 e DASHBOARD_TOKEN_V3, nunca só o primeiro.

2

🧱 As camadas que formam o v3

O v3 não é um arquivo gigante: é um conjunto de camadas, cada uma com uma responsabilidade só. A pasta src/ tem uma subpasta por camada, e nenhum módulo passa de 500 linhas.

🆕 Novo aqui?

  • Bus (barramento): o correio interno do programa. Uma camada publica um aviso, por exemplo mensagem.recebida, e quem se interessa escuta. Assim o canal não precisa conhecer o cérebro.
  • Fila: a lista de trabalhos a fazer, gravada em SQLite. Se o serviço reinicia, a lista continua lá. É isso que "durável" quer dizer.
  • Orquestrador: quem lê a mensagem e decide o que fazer com ela.
  • Cérebro: a memória do bot, o que ele lembra de você entre conversas.
  • Ollama: o programa que roda modelos de IA dentro da sua máquina, sem internet e sem custo por uso.
Telegram CLI HTTP bus correio interno orquestrador decide o que fazer fila (SQLite) cérebro gestor do Ollama gateway de custo: toda chamada de modelo passa aqui

O que olhar: em azul, o que vem de fora e o que mede o gasto. Em verde, o que é decisão e estado do bot. Nenhuma seta pula o gateway quando um modelo é chamado.

◆ Conceito principal

A lista de camadas aparece na pasta src/: bus/, canais/, fila/, orquestrador/, ollama/, custo/, cerebro/, tarefas/, telemetria/, dashboard/, cli/ e db/. Guardar as sete primeiras já explica quase tudo que acontece com uma mensagem.

3

🕰️ De onde veio: o v3 roda ao lado do v2

O v3 é sucessor do openpcbotv2, que continua em produção no bot @inemaclaudebot. O v3 tem bot próprio (@inemav3bot), porta própria (3142) e banco próprio (store/openpcbotv3.db). Estrangulamento, não corte: o novo sobe ao lado, prova que funciona, e só depois o velho sai.

1

O diagnóstico do v2

Um monólito: src/bot.ts com 145 KB, sem fila, sem custo por chamada, sem gestão do Ollama, e a memória semântica classificando por regex só em inglês, o que a deixava quebrada em português.

2

3.0.0, em 2026-09-06: fases 0 a 7 no ar

Esqueleto e bus, fila e gestor do Ollama, custo e telemetria, canal Telegram e orquestrador, cérebro, tarefas e cron, canais extras, dashboard e backup. A fase 8, o corte, ficou de fora de propósito.

3

3.1.0 e 3.1.1: conectores

E-mails e agendas Google versionados em conectores/google/, Telegram com chats observados, e a ingestão que transforma texto bruto em fatos duráveis usando o modelo local, com custo zero.

4

3.2.1 a 3.2.3: a fase 9, "Jarvis obedece"

Interruptores /parar e /retomar, modos de fila por chat, persona em camadas, /context, doctor --deep e ferramentas externas declaradas por agente. São 187 testes passando em npm test.

◆ Conceito principal

Rodar ao lado impõe regras. O token do Telegram do v2 é recusado no boot do v3, porque dois programas pedindo getUpdates ao mesmo bot geram erro 409 e deixam o bot surdo. O banco do v2 só é lido por snapshot. WhatsApp e Slack ficam desligados no v3 enquanto o v2 é dono da sessão e do token.

4

🏠 O que roda local e o que vai para a nuvem

O padrão do v3 é resolver na sua máquina. Só sobe para a nuvem o que o local não dá conta, e cada subida registra o motivo.

🆕 Novo aqui?

  • Tier: a faixa de qualidade e preço escolhida para aquela chamada. O v3 tem três: local, barato e premium.
  • Gateway: o portão único por onde toda chamada de modelo passa, em src/custo/gateway.ts. É ele que escolhe o tier, mede a latência e grava o custo.
  • Token (no sentido de custo): o pedaço de texto que os provedores cobram. Preço em dólares por milhão de tokens fica em config/precos.yaml.
local · Ollama qwen3.8:27b residente · custo 0 barato · OpenRouter claude-haiku-4.5 premium · claude -p sonnet ou opus, por agente sobe de degrau só com motivo registrado

O que olhar: o degrau de baixo é o padrão e é grátis. Cada seta para cima custa dinheiro, por isso o motivo da subida é gravado junto com a chamada.

✓ Fica na sua máquina

  • ✓Conversa comum, pergunta curta, resumo, tradução: tier local.
  • ✓A decisão de rota, feita pelo modelo pequeno llama3.2.
  • ✓Os vetores da memória, gerados por bge-m3.
  • ✓A consolidação noturna da memória, às 4h, custo zero.

✗ Sai da máquina e custa

  • ✗Raciocínio longo em resposta direta cai no tier barato.
  • ✗Ollama sem RAM suficiente também cai no tier barato, com alerta.
  • ✗Rota de agente vai para o tier premium pelo CLI claude.
  • ✗Orçamento em 100 % trava tudo isso: só o Ollama passa.

◆ Conceito principal

O orçamento mensal vem de ORCAMENTO_MENSAL_USD e de config/orcamento.yaml: aviso em 70 %, trava em 100 %. Travado, o assistente não emudece, ele volta a ser inteiramente local.

5

📏 As regras de ouro do projeto

Quatro regras vieram do v2 e do hub de monitoramento e valem para qualquer mudança no código. Elas parecem burocracia até o dia em que a máquina fica sem memória no meio de uma conversa.

✓ O que fazer

  • ✓Passar toda chamada de modelo por src/custo/gateway.ts, inclusive as que geram os vetores de significado da memória, os embeddings.
  • ✓Falar com o Ollama só por HTTP, na porta 11434 do serviço systemd.
  • ✓Manter cada módulo de src/ abaixo de 500 linhas.
  • ✓Registrar toda falha real como uma linha em FALHAS.md, antes da próxima tarefa.

✗ O que não fazer

  • ✗Subir um ollama serve paralelo ao serviço.
  • ✗Gerar mídia paga sem confirmação explícita no momento.
  • ✗Mudar a tag do papel geral sem mudar no v2: viram dois modelões residentes e a máquina fica sem memória.
  • ✗Descarregar um modelo que o v3 não carregou: pode ser do v2.

✦ Dica prática

A linha do FALHAS.md tem quatro campos: data, o que quebrou, a menor correção possível e se era problema de prompt ou de infraestrutura. Depois de umas dez linhas o padrão aparece sozinho.

◆ Conceito principal

O serviço roda com MemoryHigh=1.5G e MemoryMax=2G no cgroup, mais --max-old-space-size=1024 no Node. O pico observado foi de cerca de 1 GB com um agente rodando. Esse teto é o que garante que o v3 não derrube o v2.

6

✅ O que ele já faz e o que ainda não

Na versão 3.2.3 o v3 conversa, delega trabalho a agentes, lembra, agenda, avisa quando quebra e mostra quanto custou. A lista do que falta também está escrita, e isso importa tanto quanto a lista do que existe.

🆕 Novo aqui?

  • Agente: um trabalhador com ferramentas. Diferente da conversa, ele pode abrir arquivo, rodar comando, mexer em repositório, buscar na web. No v3 cada agente é uma pasta em agents/.
  • Skill: uma receita escrita em skills/<id>/SKILL.md que ensina o bot a fazer um tipo de tarefa. Só o resumo dela entra no prompt, para não gastar token à toa.
  • MCP: um padrão para plugar ferramentas externas em um agente. No v3 cada agente pode declarar as suas em mcp_config e ver só aquelas.

⌨️ Copie e rode

Objetivo: descobrir qual versão está no ar e se o serviço responde, sem depender do Telegram.

curl http://127.0.0.1:3142/health

Como verificar: volta um JSON com ok, mais fila, modelos, RAM e orçamento. No Telegram, o mesmo par de perguntas se faz com /versao e /health.

✓ Já faz hoje (3.2.3)

  • ✓Conversa no Telegram, no CLI e por HTTP, com fila durável por trás.
  • ✓Delega a agentes com claude -p e junta especialistas só leitura.
  • ✓Lembra, consolida de madrugada e propõe entradas no vault para você aprovar.
  • ✓Mede custo por chamada, avisa em 70 % do orçamento e trava em 100 %.
  • ✓Faz backup noturno com retenção de 14 cópias em store/backups/.

✗ Ainda não faz

  • ✗Fase 8, o corte: trocar o token de produção e arquivar o v2. Só com ordem explícita.
  • ✗Fase 10, anotada: cliente MCP nativo no caminho Ollama, voz no Telegram, /retry e /undo.
  • ✗WhatsApp de verdade, em daemon separado, e Slack ligado.
  • ✗A memória guarda a frase inteira, não um fato extraído dela.
  • ✗A tabela jobs nunca é limpa: crescem cerca de 1,5 mil linhas por dia.

◆ Conceito principal

Ter a lista do que falta escrita no próprio repositório é o que permite dizer "ainda não" sem parecer defeito. A fase 8 não começa por iniciativa do código: ela espera ordem.

✅ Resumo do Módulo

✓
Três portas de entrada - Telegram, CLI e HTTP para a mesma cabeça
✓
Camadas separadas - bus, fila, orquestrador, cérebro, Ollama, custo
✓
Ao lado do v2 - bot, porta e banco próprios, sem corte seco
✓
Local por padrão - nuvem só com motivo registrado e orçamento vigiado
✓
Quatro regras de ouro - gateway, Ollama por HTTP, 500 linhas, FALHAS.md
✓
O que falta está escrito - fase 8 e fase 10 esperam ordem

Próximo módulo:

1.2 - O caminho de uma mensagem

Voltar para a trilha Próximo módulo: O caminho de uma mensagem