opencode-plusplus

# OpenCode++ OpenCode++ é um plugin Harness focado em Windows para o aplicativo oficial OpenCode Desktop, projetado para tornar todo o processo de código gerado por IA visível e auditável: o que o modelo leu, o que bloqueou, o que pediu para executar e o que a evidência atual realmente verificou. ## Problema resolvido Sessões de codificação com IA podem produzir diffs plausíveis, mas que na verdade leram arquivos errados, editaram além do escopo, executaram comandos irrelevantes ou anunciaram sucesso sem evidência de testes recentes. OpenCode++ adiciona um plano de controle de verificação ao redor do OpenCode Desktop, fazendo o modelo trabalhar com base em contexto do repositório, limites de edição explícitos, evidências rastreáveis e decisões finais. OpenCode++ não é outro aplicativo de chat nem um modelo substituto. É um plugin de desktop em nível de usuário que observa as ferramentas já expostas pelo OpenCode e fornece ferramentas Harness para: - Selecionar arquivos e símbolos relevantes antes de buscas cegas; - Preparar limites de tarefa e verificações necessárias; - Proteger comandos e caminhos protegidos; - Registrar evidências de execução limpas contra a árvore de trabalho atual; - Avaliar portões de política, frescor, regressão, alucinação e convergência; - Explicar se o próximo passo é correção, reempacotamento, revisão humana ou finalização. ## Arquitetura do sistema A fronteira principal é simples: o OpenCode ainda lê arquivos, edita código e executa comandos. OpenCode++ fornece contexto determinístico, limites, verificações de evidência e decisões ao redor dessas atividades. | Camada | O que OpenCode++ faz | O que não afirma | | --- | --- | --- | | Registro e recuperação de contexto | Encontra pacotes, arquivos, símbolos, versões e dependências relevantes; explica arquivos selecionados e rejeitados. | Contexto é orientação, não permissão ou prova. | | Proteção e política | Verifica comandos, caminhos protegidos, contratos, frescor, regressão e ações necessárias. | Não é um sandbox de sistema operacional. | | Evidência | Combina resultados de comandos ou CI com o hash da árvore de trabalho atual e a política de evidência ativa. | Passar em um comando sozinho não prova correção de negócio. | | Registro de intervenções | Registra observações, bloqueios, solicitações, correções, verificações, não resolvidos e status de revisão humana. | Prevenção ou sugestão não é correção verificada. | | Decisão e painel | Retorna a próxima ação permitida e exibe fatos registrados em resultados de desktop e artefatos locais. | Não expõe cadeia de pensamento oculta do modelo nem chama outro modelo. | O caminho normal de desktop usa um modelo OpenCode atual e um plugin em processo. CLI e MCP permanecem como superfícies de desenvolvimento/compatibilidade; não são necessários para instalação ou uso diário. ## Funcionalidades atuais O instalador do Windows adiciona um modo principal opcional do OpenCode chamado **OpenCode++**. Selecione-o no seletor de modo na parte inferior da caixa de prompt e descreva a tarefa de codificação normalmente. Não é necessário memorizar comandos de barra do OpenCode++. Ao selecionar esse modo, seu prompt instrui o modelo OpenCode atual a usar as ferramentas do plugin em processo. O plugin não inicia um segundo modelo nem um processo CLI. Ele roda dentro do OpenCode Desktop e grava artefatos de runtime auditáveis no diretório `.agent-context/` do repositório. O instalador EXE é por usuário, para Windows x64, e não requer privilégios de administrador. Por padrão, o plugin funciona offline: não busca fontes de contexto remotas nem chama um segundo modelo. Fontes remotas configuradas ou transferência de feedback devem ser explicitamente habilitadas. O modelo OpenCode ativo ainda é responsável por ler, editar e executar comandos; OpenCode++ fornece ferramentas e portões determinísticos ao redor dessas atividades. ## Instalação e uso 1. Baixe `opencode-plusplus-setup-win-x64.exe` dos Releases do GitHub. 2. Saia completamente do OpenCode Desktop. 3. Clique duas vezes no EXE e aceite as mensagens de instalação. 4. Reinicie o OpenCode Desktop e abra um repositório. 5. Selecione **OpenCode++** no seletor de modo. 6. Digite uma solicitação normal, por exemplo, "corrija o timeout de login e adicione um teste de regressão". 7. Deixe o modo selecionado chamar `prepare`, `retrieve`, `evaluate` e `next` durante o trabalho. Para tarefas que exigem portões Harness, não volte para Build. 8. Leia o status compacto após `evaluate` ou `next`. Quando precisar de progresso de fase, arquivos selecionados e rejeitados, base de decisão, frescor de evidência, intervenções e resumo final, chame `opencode_plusplus_dashboard`. 9. Verifique `.agent-context/` para rastreamento, descobertas, comandos necessários ou relatório final. O instalador grava apenas os seguintes arquivos de configuração do OpenCode: ```text <config OpenCode>\plugins\opencode-plusplus.js <config OpenCode>\agents\opencode-plusplus.md <config OpenCode>\opencode-plusplus\state.json <config OpenCode>\opencode-plusplus\installation.json ``` Ele remove arquivos de versões antigas que criavam comandos de barra ou modificavam `app.asar`. Não altera mais o pacote do OpenCode Desktop. O diretório de configuração padrão é `%USERPROFILE%\.config\opencode`; `OPENCODE_CONFIG_DIR` tem prioridade. ## Relatórios e limites As evidências de runtime são locais a cada repositório: - `.agent-context/traces/` contém evidências de execução e teste; - `.agent-context/runs/` contém contexto de tarefa e limites de edição; - `.agent-context/loops/` contém decisões e estado de convergência; - `.agent-context/sidecar/latest.md` contém o resumo de verificação mais recente. - `.agent-context/sidecar/visualization.json` contém o snapshot estruturado mais recente do painel Harness. O plugin não é um sandbox de sistema operacional. Ele não pode impedir que outro aplicativo edite arquivos, não pode provar semântica de negócio a partir de códigos de saída e não pode garantir que argumentos de ferramentas opacos sejam classificados corretamente. Passar em um comando é evidência, não prova completa de correção. Resultados bloqueados exigem que o modo selecionado corrija ou solicite revisão humana. ### O que o usuário vê Os resultados de ferramentas de desktop são por padrão compactos: `OpenCode++ ✓ Verified`, `✗ Repair required` ou `⚠ Human review`. O JSON estruturado ainda contém `actionSummary` com itens `observed`, `prevented`, `requested`, `repaired`, `verified` e `unresolved`. Chame `opencode_plusplus_dashboard` para ver a visão completa `Plan -> Prepare -> Retrieve -> Execute -> Collect -> Evaluate -> Decide -> Persist -> Finalize`, com base de decisão, frescor de evidência, contagem de intervenções e arquivos selecionados/rejeitados. O painel expõe fatos registrados do sistema e entradas de decisão. Não expõe cadeia de pensamento oculta do modelo. Isso torna a visão útil para depuração e revisão, sem apresentar raciocínio interno privado como fato auditável. Os resultados de desktop e `.agent-context/sidecar/latest.md` distinguem os seguintes problemas: - **Arquivos de intervenção:** arquivos selecionados para verificação, editados dentro dos limites ou rejeitados com motivo; - **Riscos bloqueados:** comandos inseguros, caminhos protegidos, contexto desatualizado, testes ausentes, violações de política ou regressões não resolvidas; - **Correções sugeridas:** ações solicitadas ou edições relatadas pelo executor, mas ainda sem evidência; - **Correções verificadas:** correção seguida de nova evidência de comando ou CI da árvore de trabalho atual; - **Trabalho humano:** descobertas não resolvidas, progresso repetido sem avanço ou decisões semânticas que o Harness não pode provar. Portanto, `verified fix` é mais restrito que `suggested fix`. Comentários, documentação de contexto, declarações manuais, testes antigos bem-sucedidos, edições de código-fonte, listas de commits ou resumos gerados pelo modelo não podem se tornar verificados apenas por parecerem plausíveis. Contexto externo é orientação não confiável; comentários são conhecimento local, não política. Quando o resultado mostrar `human-review`, leia exatamente qual evidência está faltando em `actionSummary.evidence`; não é um pedido para repetir a tarefa. O uso de cache de contexto e registro é armazenado em `.agent-context/cache/` e `.agent-context/context-registry/usage/`. Feedback local fica em `.agent-context/context-registry/feedback/`, anotações em `.agent-context/knowledge/annotations/` e registros de intervenção em `.agent-context/interventions/`. Esses são artefatos de runtime locais e normalmente devem permanecer não versionados. No Windows, caminhos com espaços e caracteres não ASCII são suportados, mas o plugin ainda depende das permissões do usuário ativo, da capacidade de escrita do repositório e do diretório de plugins que o OpenCode Desktop carrega. Bloqueios de antivírus, pastas somente leitura, fontes de rede indisponíveis, conteúdo de registro inválido e falhas de permissão são relatados como diagnóstico ou status de revisão humana; não se convertem em verificação bem-sucedida. ## Personalizando seu Harness OpenCode++ é intencionalmente um ponto de extensão. Se o OpenCode parecer permissivo demais, restritivo demais ou inadequado ao fluxo de trabalho da sua equipe, bifurque ou estenda o plugin e defina sua própria política Harness, em vez de esconder o problema em prompts. Pontos de personalização úteis incluem: - `src/installer/opencode-plusplus-prompts.ts` para o prompt principal do agente; - `src/integrations/opencode/plugin-runtime/` para regras de comandos e caminhos protegidos; - `src/retrievers/` e `src/core/ranker.ts` para ranqueamento de recuperação; - `src/outputs/evidence.ts` e `src/harness/verification-plane/` para confiança e frescor de evidência; - `src/harness/control-plane/` para parada de loop e arbitragem de decisão; - `src/integrations/opencode/plugin-runtime/harness/` para comportamento específico de ferramentas de desktop. O padrão seguro de personalização é: adicione testes para a política desejada, altere o plugin ou o modo do agente, execute todas as verificações e distribua um novo instalador Windows com checksum. Mantenha o Harness explícito sobre o que pode observar e o que permanece decisão humana. ## Contribuição 1. Bifurque o repositório e crie um branch focado. 2. Leia `AGENTS.md`, os arquivos-fonte relevantes e a documentação bilíngue correspondente. 3. Adicione ou atualize testes determinísticos antes de alterar comportamento. 4. Mantenha artefatos de runtime de desktop, `dist/`, staging do instalador, chaves e arquivos locais `.agent-context/` fora do commit. 5. Execute `npm run check`, `npm run lint`, `npm run format:check`, `npm run docs:bilingual:check` e `npm test`. 6. Para alterações no instalador, execute também no Windows `npm run build:installer:windows`, `npm run test:installer:windows` e `npm run release:verify`. 7. Atualize a documentação do usuário nos dois idiomas e explique os limites de compatibilidade no pull request. ## Superfície de compatibilidade para desenvolvedores O repositório mantém pontos de entrada CLI e MCP para desenvolvimento de código-fonte, CI, diagnóstico e integrações de compatibilidade. Eles não são o caminho normal de instalação de desktop e não são necessários para usuários comuns. ## Licença MIT