Arquitetura do Pantheon¶
🇺🇸 English version available: Read in English
Público-alvo: Desenvolvedores estendendo o Pantheon e qualquer pessoa que queira entender como as peças se encaixam. O guia de instalação está em Instalação; os comportamentos do usuário no OpenCode 2.x estão documentados em OpenCode 2.x.
Fluxo de Agentes¶
O Pantheon substitui o loop tradicional de agente único por uma arquitetura com um condutor (orquestrador) e especialistas.
flowchart TD
User(["👤 Demanda do Usuário"]) --> Zeus["⚡ Zeus (Orquestrador)"]
Zeus -->|"Planejamento"| Athena["🏛️ Athena (Plano)"]
Zeus -->|"Descoberta & Varredura"| Apollo["🔍 Apollo (Batedor)"]
Zeus -->|"Hotfix Rápido (Linha Expressa)"| Talos["🛡️ Talos (Hotfix)"]
Zeus -->|"Gerenciamento de Memória"| Mnemosyne["🧠 Mnemosyne (Memória)"]
Zeus -->|"Git / PRs no GitHub"| Iris["🌈 Iris (GitHub)"]
Athena -.->|"Plano Estruturado Aprovado"| Zeus
Zeus -->|"Implementação"| Specialists
subgraph Specialists["🛠️ Especialistas de Implementação"]
Hermes["✉️ Hermes (Backend)"]
Aphrodite["🎨 Aphrodite (Frontend)"]
Demeter["🌾 Demeter (Banco de Dados)"]
Prometheus["🔥 Prometheus (Infraestrutura)"]
Hephaestus["🔨 Hephaestus (Pipelines de IA)"]
Nyx["🌙 Nyx (Observabilidade)"]
Gaia["🌍 Gaia (Sensoriamento Remoto)"]
end
Specialists -->|"Mudanças Materiais e Sensíveis"| Themis["⚖️ Themis (Revisão & Auditoria)"]
Themis -->|"Veredito PASS"| Zeus
Zeus -->|"Entrega & Telemetria"| User
O @zeus orquestra, mas nunca implementa diretamente. Ele encaminha trabalhos delimitados para um especialista e aciona planejamento, descoberta, trabalho paralelo e auditoria conforme o escopo e o risco demandam. O comando /pantheon-deepwork é o fluxo de trabalho com checkpoints para demandas pesadas em múltiplas fases. Os arquivos canônicos dos agentes residem em src/agents/*.md; a Matriz de Agentes indexa cada um deles.
Os portões de qualidade são qualitativos, não limiares cegos de linhas/arquivos: trabalho autocontido permanece inline; uma tarefa delimitada vai para um especialista; frentes independentes podem utilizar despachos raiz separados. A @themis audita mudanças materiais e sensíveis — autenticação, segurança, esquemas/banco de dados e qualquer coisa que altere comportamentos de forma ampla. Veja Permissões, Portões & Delegação.
Mecânica de Delegação¶
O Pantheon delega através do motor nativo de sessões filhas do host. A ferramenta chamável é subagent no runtime raiz reportado; a documentação do host/API chama esse mesmo mecanismo de task(). A disponibilidade de ferramentas, opções de execução em segundo plano e observabilidade de conclusão são propriedades do runtime ativo, não do Pantheon. A antiga ferramenta pantheon_delegate e seu motor legado foram removidos na versão 2.0.
Todo despacho raiz carrega um briefing de handoff conciso: objetivo/resultado esperado, escopo delimitado, critérios de aceite, apenas as entradas relevantes, restrições e portões de segurança, formato do entregável e verificação. Nunca copie conversas inteiras ou histórico não relacionado.
Os contratos de retorno são específicos por papel:
| Chamador | Formato de Retorno |
|---|---|
| Agente de Implementação | ## subtask_summary com arquivos modificados, resumo, testes e eventuais impedimentos |
Investigação (apollo) |
Achados estruturados: tópicos, caminhos com números de linha, snippets ≤ 3 linhas |
Planejador (athena) |
O plano completo em Markdown/JSON, nunca apenas um resumo ou ponteiro |
| Especialista de Conselho | ## specialist_response |
Trabalhos delegados recebem no máximo uma nova tentativa após falha transiente inicial. Quando nenhuma ferramenta de status/conclusão é exposta, prefira despacho síncrono ou aguarde a notificação do host; não presuma polling, cancelamento ou recuperação baseada em quadro.
No OpenCode 2.x, o plugin impõe adicionalmente uma matriz chamador/alvo para requisições subagent gerenciadas pelo Pantheon quando o host expõe ctx.permission.hook. Ele valida os identificadores de sessão, mensagem e chamada de ferramenta de um registro de curta duração de tool.execute.before, exigindo que a sessão do host não tenha parentID. Origens ausentes, expiradas ou incompatíveis falham fechadas (fail-closed). Se o hook não estiver disponível, as permissões do host mantêm o controle. A matriz está documentada em Permissões, Portões & Delegação.
O que o Plugin Registra¶
Existe uma geração única: a linha de plugins V1 foi removida no 2.0, e a superfície abaixo é a única ativa.
O plugin é registrado sob a chave plural plugins como o diretório <installed>/src/plugin. O arquivo src/plugin/index.ts reexporta o ponto de entrada real em src/plugin.ts; o registro de hooks de ferramentas em src/plugin.ts é alimentado pelas definições em src/pantheon/tools.ts.
Quatro Ferramentas Incondicionais:¶
hashline_edit— Edição precisa baseada em linhas de hash (src/pantheon/tools.ts).pantheon_cost— Telemetria de tokens consumidos, custos estimados e velocidade de cache (src/pantheon/tools.ts).pantheon_model— Roteamento dinâmico de modelos por especialista (src/pantheon/tools.ts).pantheon_local_decision— Seletor consultivo local; rejeita execução a menos que o contexto do host identifique o chamador como Zeus (src/pantheon/tools.ts).
Até Duas Ferramentas Dependentes do Host:¶
vision_describe— Adicionada apenas quandoctx.model.listé uma função (src/plugin.ts; definição emsrc/pantheon/native-vision.ts).pantheon_bounded_read— Adicionada apenas quando o hooktool.execute.beforeé registrado e o host expõe as APIs de permissão e sessão (src/plugin.ts; definição emsrc/pantheon/bounded-read.ts). Apenas para sessões raiz do Zeus.
As ferramentas de metas automáticas são omitidas onde o PluginContext do host não as suporta (reportado como goal-tools).
O plugin também conecta cinco inscrições de eventos (session.created, session.idle, session.deleted, session.error, session.compacted), hooks de sessão (prompt, context, compaction), um hook execute.before que aplica modo somente-leitura (o mesmo manipulador impede o orquestrador de ler diretamente códigos-fonte, testes e scripts com read/glob/grep), e uma cadeia execute.after (task-result-guard → context-sandbox → read-enhancer → formatador + auditoria de delegação).
sequenceDiagram
autonumber
participant Host as OpenCode 2.x Host
participant Plugin as Pantheon Plugin
participant Guard as Execute Guards
participant Agent as Especialista
Host->>Plugin: tool.execute.before
Plugin->>Guard: Guardião Read-Only (impede Zeus de ler fontes/testes diretamente)
Guard-->>Host: Allow / Deny
Host->>Agent: Executa ferramenta ou subagente
Agent-->>Host: Retorna saída bruta da ferramenta
Host->>Plugin: tool.execute.after
Plugin->>Guard: task-result-guard → context-sandbox → read-enhancer
Guard-->>Host: Resultado limpo, delimitado e enriquecido
Modelo do Instalador e Configuração¶
As fontes canônicas em src/ são lidas pelo instalador e gravadas na configuração de destino. Não há etapa de geração em runtime.
- O instalador grava
opencode.json, nuncaopencode.jsonc. O host pode mesclar um arquivo.jsoncirmão; veja Compatibilidade. - Ele remove referências legadas ao Pantheon tanto na chave singular
pluginquanto na chave pluralpluginsantes de escrever o registro atual, garantindo que dois plugins do Pantheon nunca coexistam. Chaves no formato legado V1 são normalizadas para o formato 2.x antes da gravação. - Entradas de plugins e MCPs de terceiros são estritamente preservadas e nunca convertidas.
- Um inventário versionado de propriedade por arquivo registra o que o instalador possui, permitindo que o comando
reconcileidentifique arquivos não modificados.
O pacote expõe o plugin como a exportação importável pantheon-opencode/plugin; o subcaminho pantheon-opencode/local-decision-router é a fonte TypeScript do roteador de decisões. Não há exportação de ponte e não há segundo contrato: o plugin opera de forma independente com degradação graciosa.
Lojas de Memória e Contexto¶
O Pantheon possui três lojas independentes, documentadas em Memória:
pantheon-memory— Banco SQLite persistente com busca léxica por palavras-chave FTS5/BM25.pantheon-persistence— Checkpoints de sessão e metas manuais de sessão..pantheon/memory-bank/— Arquivos do projeto revisados por humanos, lidos sob demanda.
Elas não são sincronizadas automaticamente. A disponibilidade das ferramentas MCP depende das permissões do agente ativo; namespaces são filtros organizacionais, não fronteiras de controle de acesso.
Servidores MCP (Pontos de Entrada)¶
Cinco servidores locais stdio em Python, declarados em scripts/install-mcp.mjs e registrados no OpenCode:
| Servidor | Ponto de Entrada | Ferramentas | Recursos |
|---|---|---|---|
pantheon-resources |
scripts/mcp_resources.py |
— | 4 estáticos + 6 templates |
pantheon-code-mode |
scripts/code_mode.py |
2 | 1 estático + 1 template |
pantheon-memory |
scripts/memory_mcp.py |
9 | — |
pantheon-persistence |
scripts/mcp_persistence.py |
6 | — |
pantheon-vision |
src/mcp/pantheon_vision.py |
3 | — |
A configuração detalhada e allowlists estão em Servidores MCP.
Princípios de Design¶
- Uma única casa para cada fato: A matriz de suporte, a mecânica do instalador, o processo de release e as evidências de benchmark vivem cada um em exatamente uma página.
- Configuração mais um runtime enxuto: O comportamento dos agentes vive em Markdown (
src/agents/*.md,src/instructions/*.instructions.md,src/skills/*/SKILL.md); o plugin instalado fornece a orquestração, ferramentas e guardiões. - Fail-closed em identidade e permissões; fail-open em apresentação: Uma origem de permissão malformada nega a delegação. Um payload de compactação malformado mantém o array de mensagens inalterado.