Arquitetura

Esta página é para quem quer perceber o Ploy por dentro ou contribuir. Os caminhos são relativos à raiz do código, que ainda não está publicado. Onde um caminho começa por plugin/ ou ploy/, é dentro de packages/core/src/.

Visão geral#

window / terminal
      |
local service (OpenCode: chats, tools, permissions)
      |   model.request hook: new address + token
      v
Ploy gateway (127.0.0.1) -> router -> pipeline of the chosen profile
                                              |
                                              v
                                    Ollama (qwen3-ploy)

Todos os modelos Ploy partilham o mesmo motor: o Qwen3 8B no Ollama. O que muda é o que acontece à volta dele.

Os modelos são servidos por um gateway#

packages/core/src/plugin/ploy-models.ts arranca, dentro do serviço, um pequeno servidor (Bun.serve) em 127.0.0.1, numa porta livre, que fala o protocolo de chat da OpenAI. O resto do Ploy trata os cinco modelos como modelos normais.

• Hook de pedidos. O hook model.request aponta os modelos Ploy para o gateway e junta um token aleatório (x-ploy-token) e o tipo de pedido (x-ploy-kind). Sem o token, o gateway responde 403.
• Um pipeline por volta. Só o primeiro pedido de uma volta corre o pipeline. Os pedidos que continuam a resposta depois de uma ferramenta reutilizam a mesma rota e o mesmo briefing. Títulos e resumos vão direto ao modelo base, sem raciocínio.
• Famílias e datas. O seletor só lista modelos recentes, um por família. Por isso cada modelo Ploy tem a sua própria family e uma data de lançamento recente. Os modelos Ollama em bruto são marcados como obsoletos (e por isso escondidos). Os dois modelos do Nesko, ploy-worker e ploy-builder, também.
• Stop. Com Bun.serve, quando o cliente sai o gateway cancela o pipeline e o pedido ao Ollama.
• Estado nos metadados. Cada conversa guarda ploy.route (a rota escolhida), ploy.activity (o passo em curso), ploy.memory e ploy.nesko.

Automático: o encaminhador#

packages/core/src/ploy/router.ts é determinístico e instantâneo: provas ponderadas por palavras-chave em português e em inglês. Um seguimento curto fica no perfil que respondeu antes. Uma dúvida entre a web e o raciocínio é resolvida com uma pergunta ao modelo (até 12 tokens). Nada vai para o Veta se a web estiver desligada ou se o pedido disser para não pesquisar. A escolha é a primeira linha do raciocínio visível.

Veta: Planeador, Leitor, Verificador#

ploy/research.ts e ploy/search.ts. Cada agente é uma pergunta nova ao mesmo modelo, com contexto próprio e sem ferramentas.

1. O Planeador escreve até três consultas, que são limpas antes de saírem.
2. A pesquisa usa o DuckDuckGo e a Wikipédia. Leem-se até quatro páginas na primeira ronda, no máximo duas por site.
3. Um Leitor por página extrai factos. A página é dados, não instruções.
4. O Verificador cruza as fontes em consenso, conflitos, fontes únicas e lacunas. Uma segunda ronda só corre se as fontes não chegarem, dentro de um orçamento de cinco minutos.
5. O modelo de resposta recebe um dossiê com fontes numeradas, cita [n] e diz o que é incerto.

Antes de o dossiê chegar ao modelo, a conversa é marcada com ploy_tainted (ver Segurança).

Kant: o painel#

ploy/deliberate.ts. O raciocínio do Qwen3 liga-se ou desliga-se; pedir mais esforço não o faz pensar mais fundo. A profundidade vem da estrutura. O Analista (raciocínio ligado) escreve uma resposta completa. O Crítico, num contexto novo e sem ver o raciocínio do analista, procura erros e responde em JSON. O modelo de resposta só revê se o crítico encontrou algo que não seja menor. Um pedido que precisa de ficheiros ou comandos salta o painel.

Nesko: o motor#

O método está no código, não no prompt: packages/core/src/nesko/ (documentos, plano, execução, achados, auditoria, relatório, estado, motor), o controlador em plugin/nesko.ts e a leitura da mensagem em ploy/nesko.ts. O motor fala com o exterior por portas (say, save, worker, text, gate, proof). O estado da execução vive em ploy.nesko e a app desenha-o no cartão por cima do compositor (packages/app/src/session/composer/project-run-dock.tsx). Os trabalhadores usam dois modelos escondidos: ploy-worker pensa (documentos e plano) e ploy-builder não pensa (passos da construção). Ver Nesko.

Cadeia de língua#

1. Cada agente que escreve para a pessoa leva a regra do português de Portugal (ploy/language.ts).
2. Num pedido em português, a regra vai também no fim do pedido, onde um modelo pequeno lhe dá mais peso.
3. As respostas passam por um filtro em streaming (ploy/european.ts) que troca palavras do Brasil por equivalentes exatos de Portugal (por exemplo, os termos brasileiros para ficheiro, utilizador e equipa) e corrige a construção progressiva com gerúndio. Nunca toca em código, nomes de ficheiros, endereços ou palavras com maiúscula a meio da frase.
4. Na app, o dicionário em português do Brasil é reescrito ao carregar (packages/app/src/runtime/i18n/european-portuguese.ts).

Outras peças#

O que é do OpenCode e o que é do Ploy#

O Ploy é um fork do OpenCode (MIT), no ramo ploy, com o remoto upstream guardado como referência. Vêm do OpenCode as sessões, as ferramentas de base, o serviço de permissões, o sistema de plugins, os fornecedores de modelos, a janela e o terminal. A licença e o aviso de copyright mantêm-se (ver Licenças).

O código novo do Ploy está sobretudo em ficheiros novos. As alterações a ficheiros herdados ficam em poucos sítios, marcados com comentários que começam por Ploy:, para poderem ser reaplicadas quando o OpenCode avança. Entre eles: permission.ts, tool/plugin/shell.ts, tool/plugin/write.ts, session/runner/step.ts e plugin/optimize.ts. A troca do nome visível e do tema toca em muitos ficheiros de texto e de aspeto.