diff --git a/docs/pt-BR/concepts/qa-e2e-automation.md b/docs/pt-BR/concepts/qa-e2e-automation.md index 1abe5c31a..3d2931d0b 100644 --- a/docs/pt-BR/concepts/qa-e2e-automation.md +++ b/docs/pt-BR/concepts/qa-e2e-automation.md @@ -1,37 +1,37 @@ --- read_when: - - Estendendo qa-lab ou qa-channel + - Estendendo o qa-lab ou o qa-channel - Adicionando cenários de QA com suporte do repositório - - Criando automação de QA com maior realismo em torno do painel do Gateway -summary: Formato da automação privada de QA para qa-lab, qa-channel, cenários com seed e relatórios de protocolo + - Criando uma automação de QA com maior realismo em torno do painel do Gateway +summary: Forma da automação privada de QA para qa-lab, qa-channel, cenários com seed e relatórios de protocolo title: Automação E2E de QA x-i18n: - generated_at: "2026-04-16T21:51:16Z" + generated_at: "2026-04-17T05:36:09Z" model: gpt-5.4 provider: openai - source_hash: 7deefda1c90a0d2e21e2155ffd8b585fb999e7416bdbaf0ff57eb33ccc063afc + source_hash: 51f97293c184d7c04c95d9858305668fbc0f93273f587ec7e54896ad5d603ab0 source_path: concepts/qa-e2e-automation.md workflow: 15 --- # Automação E2E de QA -A stack privada de QA foi criada para exercitar o OpenClaw de uma forma mais realista, -no formato de canal, do que um único teste unitário consegue. +A stack privada de QA foi feita para exercitar o OpenClaw de uma forma mais realista, +no formato de canais, do que um único teste unitário consegue. Peças atuais: - `extensions/qa-channel`: canal de mensagens sintético com superfícies de DM, canal, thread, reação, edição e exclusão. - `extensions/qa-lab`: UI de depuração e barramento de QA para observar a transcrição, - injetar mensagens de entrada e exportar um relatório em Markdown. -- `qa/`: recursos de seed com suporte do repositório para a tarefa inicial e cenários + injetar mensagens recebidas e exportar um relatório em Markdown. +- `qa/`: recursos seed com suporte do repositório para a tarefa inicial e cenários básicos de QA. O fluxo atual do operador de QA é um site de QA com dois painéis: - Esquerda: painel do Gateway (Control UI) com o agente. -- Direita: QA Lab, mostrando a transcrição estilo Slack e o plano do cenário. +- Direita: QA Lab, mostrando a transcrição em estilo Slack e o plano de cenário. Execute com: @@ -39,13 +39,13 @@ Execute com: pnpm qa:lab:up ``` -Isso compila o site de QA, inicia a rota do gateway com suporte de Docker e expõe a +Isso compila o site de QA, inicia a lane do gateway com suporte de Docker e expõe a página do QA Lab, onde um operador ou loop de automação pode dar ao agente uma missão de QA, observar o comportamento real do canal e registrar o que funcionou, falhou ou permaneceu bloqueado. -Para uma iteração mais rápida da UI do QA Lab sem recompilar a imagem Docker toda vez, -inicie a stack com um bundle do QA Lab montado por bind: +Para uma iteração mais rápida da UI do QA Lab sem reconstruir a imagem Docker a cada vez, +inicie a stack com um bundle do QA Lab montado por bind mount: ```bash pnpm openclaw qa docker-build-image @@ -54,55 +54,55 @@ pnpm qa:lab:up:fast pnpm qa:lab:watch ``` -`qa:lab:up:fast` mantém os serviços Docker em uma imagem pré-compilada e faz bind-mount de +`qa:lab:up:fast` mantém os serviços Docker em uma imagem pré-compilada e faz bind mount de `extensions/qa-lab/web/dist` no contêiner `qa-lab`. `qa:lab:watch` -recompila esse bundle a cada alteração, e o navegador recarrega automaticamente quando o hash +recompila esse bundle quando há mudanças, e o navegador recarrega automaticamente quando o hash do recurso do QA Lab muda. -Para uma rota de smoke do Matrix com transporte real, execute: +Para uma lane de smoke do Matrix com transporte real, execute: ```bash pnpm openclaw qa matrix ``` -Essa rota provisiona um homeserver Tuwunel descartável em Docker, registra usuários +Essa lane provisiona um homeserver Tuwunel descartável no Docker, registra usuários temporários de driver, SUT e observador, cria uma sala privada e então executa -o Plugin real do Matrix dentro de um processo filho de gateway de QA. A rota de transporte ativo -mantém a configuração filha restrita ao transporte em teste, então o Matrix é executado sem -`qa-channel` na configuração filha. Ela grava os artefatos de relatório estruturado e +o Plugin real do Matrix dentro de um filho de gateway de QA. A lane de transporte ao vivo mantém +a configuração do filho restrita ao transporte em teste, então o Matrix roda sem +`qa-channel` na configuração do filho. Ela grava os artefatos do relatório estruturado e um log combinado de stdout/stderr no diretório de saída de QA do Matrix selecionado. Para -capturar também a saída externa de build/launcher de `scripts/run-node.mjs`, defina -`OPENCLAW_RUN_NODE_OUTPUT_LOG=` como um arquivo de log local ao repositório. +capturar também a saída externa de compilação/launcher de `scripts/run-node.mjs`, defina +`OPENCLAW_RUN_NODE_OUTPUT_LOG=` para um arquivo de log local ao repositório. -Para uma rota de smoke do Telegram com transporte real, execute: +Para uma lane de smoke do Telegram com transporte real, execute: ```bash pnpm openclaw qa telegram ``` -Essa rota mira um grupo privado real do Telegram em vez de provisionar um servidor -descartável. Ela requer `OPENCLAW_QA_TELEGRAM_GROUP_ID`, +Essa lane usa um grupo privado real do Telegram em vez de provisionar um +servidor descartável. Ela exige `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` e `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`, além de dois bots distintos no mesmo -grupo privado. O bot SUT deve ter um nome de usuário do Telegram, e a observação -bot-para-bot funciona melhor quando ambos os bots têm o Modo de Comunicação Bot-to-Bot -habilitado no `@BotFather`. +grupo privado. O bot SUT precisa ter um nome de usuário no Telegram, e a +observação bot-para-bot funciona melhor quando ambos os bots têm o Bot-to-Bot Communication Mode +ativado no `@BotFather`. -As rotas de transporte ativo agora compartilham um contrato menor em vez de cada uma -inventar seu próprio formato de lista de cenários: +As lanes de transporte ao vivo agora compartilham um contrato menor em vez de cada uma +inventar o próprio formato de lista de cenários. `qa-channel` continua sendo a suíte ampla de comportamento sintético do produto e não faz parte -da matriz de cobertura de transporte ativo. +da matriz de cobertura de transporte ao vivo. -| Rota | Canary | Bloqueio por menção | Bloco por allowlist | Resposta de nível superior | Retomada após reinício | Acompanhamento em thread | Isolamento de thread | Observação de reação | Comando de ajuda | -| -------- | ------ | ------------------- | ------------------- | -------------------------- | ---------------------- | ------------------------ | -------------------- | -------------------- | ---------------- | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Lane | Canary | Bloqueio por menção | Bloqueio por allowlist | Resposta de nível superior | Retomada após reinício | Acompanhamento em thread | Isolamento de thread | Observação de reação | Comando de ajuda | +| -------- | ------ | ------------------- | ---------------------- | -------------------------- | ---------------------- | ------------------------ | -------------------- | -------------------- | ---------------- | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | Isso mantém `qa-channel` como a suíte ampla de comportamento do produto, enquanto Matrix, -Telegram e futuros transportes ativos compartilham uma checklist explícita de contrato de transporte. +Telegram e futuros transportes ao vivo compartilham uma checklist explícita de contrato de transporte. -Para uma rota descartável de VM Linux sem colocar o Docker no caminho do QA, execute: +Para uma lane de VM Linux descartável sem colocar Docker no caminho de QA, execute: ```bash pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline @@ -111,71 +111,87 @@ pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline Isso inicializa um guest novo do Multipass, instala dependências, compila o OpenClaw dentro do guest, executa `qa suite` e então copia o relatório e resumo normais de QA de volta para `.artifacts/qa-e2e/...` no host. -Ele reutiliza o mesmo comportamento de seleção de cenário de `qa suite` no host. +Isso reutiliza o mesmo comportamento de seleção de cenário de `qa suite` no host. As execuções da suíte no host e no Multipass executam vários cenários selecionados em paralelo com workers de gateway isolados por padrão, até 64 workers ou a contagem de cenários -selecionada. Use `--concurrency ` para ajustar a quantidade de workers, ou +selecionados. Use `--concurrency ` para ajustar a quantidade de workers, ou `--concurrency 1` para execução serial. -As execuções ativas encaminham as entradas de autenticação de QA compatíveis que são práticas para o -guest: chaves de provedor baseadas em env, o caminho de configuração do provedor ativo de QA e +As execuções ao vivo encaminham as entradas de autenticação de QA suportadas que são práticas para o +guest: chaves de provider via variável de ambiente, o caminho de configuração do provider ao vivo de QA e `CODEX_HOME` quando presente. Mantenha `--output-dir` sob a raiz do repositório para que o guest -possa gravar de volta por meio do workspace montado. +possa gravar de volta pelo workspace montado. ## Seeds com suporte do repositório -Os recursos de seed ficam em `qa/`: +Os recursos seed ficam em `qa/`: - `qa/scenarios/index.md` - `qa/scenarios/*.md` -Eles ficam intencionalmente no git para que o plano de QA seja visível tanto para humanos quanto para o -agente. +Eles ficam intencionalmente no git para que o plano de QA seja visível tanto para humanos +quanto para o agente. -`qa-lab` deve permanecer um executor genérico de Markdown. Cada arquivo Markdown de cenário -é a fonte da verdade para uma execução de teste e deve definir: +`qa-lab` deve permanecer um executor genérico de Markdown. Cada arquivo Markdown de cenário é +a fonte da verdade para uma execução de teste e deve definir: - metadados do cenário -- referências de documentação e código -- requisitos opcionais de Plugin +- referências de docs e código +- requisitos opcionais de plugin - patch opcional de configuração do gateway - o `qa-flow` executável -A superfície de runtime reutilizável que dá suporte a `qa-flow` pode continuar sendo genérica +A superfície de runtime reutilizável que dá suporte ao `qa-flow` pode permanecer genérica e transversal. Por exemplo, cenários em Markdown podem combinar helpers do lado do transporte -com helpers do lado do navegador que dirigem a Control UI embutida por meio da superfície -Gateway `browser.request` sem adicionar um executor com caso especial. +com helpers do lado do navegador que controlam a Control UI embutida por meio da +superfície `browser.request` do Gateway sem adicionar um executor com caso especial. A lista básica deve permanecer ampla o suficiente para cobrir: -- chat em DM e canal +- chat em DM e em canal - comportamento de thread - ciclo de vida de ações de mensagem - callbacks de Cron - recuperação de memória - troca de modelo -- handoff de subagente -- leitura de repositório e documentação +- handoff para subagente +- leitura do repositório e de docs - uma pequena tarefa de compilação, como Lobster Invaders +## Lanes de mock de provider + +`qa suite` tem duas lanes locais de mock de provider: + +- `mock-openai` é o mock do OpenClaw sensível ao cenário. Ele continua sendo a + lane de mock determinística padrão para QA com suporte do repositório e gates de paridade. +- `aimock` inicia um servidor de provider com suporte do AIMock para cobertura experimental de protocolo, + fixture, gravação/reprodução e caos. Ele é aditivo e não substitui o dispatcher + de cenários do `mock-openai`. + +A implementação da lane de provider fica em `extensions/qa-lab/src/providers/`. +Cada provider é dono dos próprios padrões, inicialização do servidor local, configuração +de modelo do gateway, necessidades de preparação de perfil de autenticação e flags de capacidade +ao vivo/mock. O código compartilhado da suíte e do gateway deve rotear pelo registro de providers em vez de +ramificar com base em nomes de providers. + ## Adaptadores de transporte `qa-lab` é dono de uma superfície genérica de transporte para cenários de QA em Markdown. `qa-channel` é o primeiro adaptador nessa superfície, mas o objetivo do design é mais amplo: -futuros canais reais ou sintéticos devem se conectar ao mesmo executor de suíte -em vez de adicionar um executor de QA específico por transporte. +canais futuros, reais ou sintéticos, devem se conectar ao mesmo executor de suíte em vez de +adicionar um executor de QA específico para cada transporte. -No nível da arquitetura, a divisão é: +No nível de arquitetura, a divisão é: - `qa-lab` é dono da execução genérica de cenários, concorrência de workers, gravação de artefatos e relatórios. - o adaptador de transporte é dono da configuração do gateway, prontidão, observação de entrada e saída, ações de transporte e estado de transporte normalizado. -- os arquivos Markdown de cenário em `qa/scenarios/` definem a execução de teste; `qa-lab` fornece a superfície de runtime reutilizável que os executa. +- arquivos de cenário em Markdown em `qa/scenarios/` definem a execução de teste; `qa-lab` fornece a superfície de runtime reutilizável que os executa. -A orientação de adoção voltada para mantenedores para novos adaptadores de canal fica em +A orientação de adoção voltada para maintainers para novos adaptadores de canal está em [Testing](/pt-BR/help/testing#adding-a-channel-to-qa). ## Relatórios -`qa-lab` exporta um relatório de protocolo em Markdown a partir da linha do tempo observada no barramento. +`qa-lab` exporta um relatório de protocolo em Markdown a partir da linha do tempo do barramento observado. O relatório deve responder: - O que funcionou @@ -183,7 +199,7 @@ O relatório deve responder: - O que permaneceu bloqueado - Quais cenários de acompanhamento valem a pena adicionar -Para verificações de caráter e estilo, execute o mesmo cenário em várias refs de modelo ativas +Para verificações de caráter e estilo, execute o mesmo cenário em várias refs de modelos ao vivo e grave um relatório em Markdown avaliado: ```bash @@ -203,30 +219,30 @@ pnpm openclaw qa character-eval \ --judge-concurrency 16 ``` -O comando executa processos filhos locais de gateway de QA, não Docker. Os cenários de avaliação -de caráter devem definir a persona por meio de `SOUL.md` e então executar turnos normais de usuário, -como chat, ajuda com workspace e pequenas tarefas com arquivos. O modelo candidato +O comando executa processos filhos locais do gateway de QA, não Docker. Cenários de avaliação de caráter +devem definir a persona por meio de `SOUL.md` e então executar turnos normais de usuário +como chat, ajuda sobre o workspace e pequenas tarefas em arquivos. O modelo candidato não deve ser informado de que está sendo avaliado. O comando preserva cada transcrição -completa, registra estatísticas básicas da execução e então pede aos modelos juízes no modo fast com -raciocínio `xhigh` para classificar as execuções por naturalidade, vibe e humor. -Use `--blind-judge-models` ao comparar provedores: o prompt do juiz ainda recebe -cada transcrição e status da execução, mas as refs candidatas são substituídas por rótulos -neutros como `candidate-01`; o relatório mapeia as classificações de volta para as refs reais após +completa, registra estatísticas básicas da execução e então pede que os modelos juízes, em modo fast com +raciocínio `xhigh`, classifiquem as execuções por naturalidade, vibe e humor. +Use `--blind-judge-models` ao comparar providers: o prompt do juiz ainda recebe +cada transcrição e status da execução, mas as refs candidatas são substituídas por rótulos neutros +como `candidate-01`; o relatório mapeia as classificações de volta para as refs reais após o parsing. -As execuções candidatas usam `high` por padrão, com `xhigh` para modelos OpenAI que -oferecem suporte a isso. Substitua um candidato específico inline com -`--model provider/model,thinking=`. `--thinking ` ainda define um -fallback global, e a forma antiga `--model-thinking ` é -mantida por compatibilidade. +As execuções dos candidatos usam por padrão `high` thinking, com `xhigh` para modelos OpenAI que +oferecem suporte. Substitua um candidato específico inline com +`--model provider/model,thinking=`. `--thinking ` ainda define um fallback +global, e o formato mais antigo `--model-thinking ` é +mantido por compatibilidade. As refs candidatas da OpenAI usam o modo fast por padrão para que o processamento prioritário seja usado -quando o provedor oferecer suporte. Adicione `,fast`, `,no-fast` ou `,fast=false` inline quando um -único candidato ou juiz precisar de uma substituição. Passe `--fast` apenas quando quiser +quando o provider oferecer suporte. Adicione `,fast`, `,no-fast` ou `,fast=false` inline quando +um único candidato ou juiz precisar de uma substituição. Passe `--fast` apenas quando quiser forçar o modo fast para todos os modelos candidatos. As durações de candidatos e juízes são registradas no relatório para análise de benchmark, mas os prompts dos juízes dizem explicitamente -para não classificar por velocidade. -As execuções de modelos candidatos e juízes usam concorrência 16 por padrão. Reduza -`--concurrency` ou `--judge-concurrency` quando limites do provedor ou pressão no gateway local -deixarem a execução ruidosa demais. +para não classificar com base em velocidade. +As execuções dos modelos candidatos e dos juízes usam concorrência 16 por padrão. Reduza +`--concurrency` ou `--judge-concurrency` quando limites do provider ou pressão no gateway local +tornarem uma execução muito ruidosa. Quando nenhum `--model` candidato é passado, a avaliação de caráter usa por padrão `openai/gpt-5.4`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`, `anthropic/claude-sonnet-4-6`, `zai/glm-5.1`, @@ -236,7 +252,7 @@ Quando nenhum `--judge-model` é passado, os juízes usam por padrão `openai/gpt-5.4,thinking=xhigh,fast` e `anthropic/claude-opus-4-6,thinking=high`. -## Documentos relacionados +## Docs relacionadas - [Testing](/pt-BR/help/testing) - [QA Channel](/pt-BR/channels/qa-channel) diff --git a/docs/pt-BR/help/testing.md b/docs/pt-BR/help/testing.md index ab2b450b6..574f81e0c 100644 --- a/docs/pt-BR/help/testing.md +++ b/docs/pt-BR/help/testing.md @@ -3,25 +3,25 @@ read_when: - Executando testes localmente ou no CI - Adicionando regressões para bugs de modelo/provedor - Depurando o comportamento do Gateway + agente -summary: 'Kit de testes: suítes unit/e2e/live, runners do Docker e o que cada teste cobre' -title: Testes +summary: 'Kit de testes: suítes unit/e2e/live, executores Docker e o que cada teste cobre' +title: Teste x-i18n: - generated_at: "2026-04-16T21:51:15Z" + generated_at: "2026-04-17T05:36:07Z" model: gpt-5.4 provider: openai - source_hash: af2bc0e9b5e08ca3119806d355b517290f6078fda430109e7a0b153586215e34 + source_hash: 55483bc68d3b24daca3189fba3af1e896f39b8e83068d102fed06eac05b36102 source_path: help/testing.md workflow: 15 --- # Testes -O OpenClaw tem três suítes do Vitest (unit/integration, e2e, live) e um pequeno conjunto de runners Docker. +O OpenClaw tem três suítes Vitest (unit/integration, e2e, live) e um pequeno conjunto de executores Docker. Este documento é um guia de “como testamos”: - O que cada suíte cobre (e o que ela deliberadamente _não_ cobre) -- Quais comandos executar para fluxos comuns (local, pré-push, depuração) +- Quais comandos executar para fluxos de trabalho comuns (local, pré-push, depuração) - Como os testes live descobrem credenciais e selecionam modelos/provedores - Como adicionar regressões para problemas reais de modelo/provedor @@ -30,88 +30,91 @@ Este documento é um guia de “como testamos”: Na maioria dos dias: - Gate completo (esperado antes do push): `pnpm build && pnpm check && pnpm test` -- Execução local mais rápida da suíte completa em uma máquina folgada: `pnpm test:max` +- Execução local mais rápida da suíte completa em uma máquina com bastante recurso: `pnpm test:max` - Loop direto de watch do Vitest: `pnpm test:watch` -- O direcionamento direto por arquivo agora também encaminha caminhos de extensões/canais: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- Prefira execuções direcionadas primeiro quando estiver iterando sobre uma única falha. -- Site de QA com suporte de Docker: `pnpm qa:lab:up` -- Lane de QA com suporte de VM Linux: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` +- O direcionamento direto por arquivo agora também roteia caminhos de extensão/canal: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- Prefira execuções direcionadas primeiro quando estiver iterando em uma única falha. +- Site de QA com suporte Docker: `pnpm qa:lab:up` +- Faixa de QA com suporte de VM Linux: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -Quando você mexer em testes ou quiser confiança extra: +Quando você mexe em testes ou quer confiança extra: - Gate de cobertura: `pnpm test:coverage` - Suíte E2E: `pnpm test:e2e` Ao depurar provedores/modelos reais (requer credenciais reais): -- Suíte live (modelos + sondas de ferramentas/imagens do Gateway): `pnpm test:live` +- Suíte live (probes de modelos + Gateway ferramenta/imagem): `pnpm test:live` - Direcionar um arquivo live em modo silencioso: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -Dica: quando você precisar apenas de um caso com falha, prefira restringir os testes live por meio das variáveis de ambiente de allowlist descritas abaixo. +Dica: quando você só precisa de um caso com falha, prefira restringir os testes live usando as variáveis de ambiente de allowlist descritas abaixo. -## Runners específicos de QA +## Executores específicos de QA -Esses comandos ficam ao lado das suítes de teste principais quando você precisa do realismo do qa-lab: +Esses comandos ficam ao lado das principais suítes de teste quando você precisa do realismo do qa-lab: - `pnpm openclaw qa suite` - Executa cenários de QA com suporte do repositório diretamente no host. - - Executa vários cenários selecionados em paralelo por padrão com workers isolados do Gateway, até 64 workers ou a contagem de cenários selecionados. Use `--concurrency ` para ajustar a quantidade de workers, ou `--concurrency 1` para a lane serial antiga. + - Executa vários cenários selecionados em paralelo por padrão com workers isolados do Gateway, até 64 workers ou a contagem de cenários selecionados. Use `--concurrency ` para ajustar a contagem de workers, ou `--concurrency 1` para a faixa serial mais antiga. + - Oferece suporte aos modos de provedor `live-frontier`, `mock-openai` e `aimock`. + `aimock` inicia um servidor local de provedor com suporte AIMock para cobertura experimental de fixtures e mock de protocolo sem substituir a faixa `mock-openai` orientada por cenários. - `pnpm openclaw qa suite --runner multipass` - Executa a mesma suíte de QA dentro de uma VM Linux Multipass descartável. - Mantém o mesmo comportamento de seleção de cenários do `qa suite` no host. - Reutiliza as mesmas flags de seleção de provedor/modelo do `qa suite`. - - Execuções live encaminham as entradas de autenticação de QA compatíveis que são práticas para o guest: - chaves de provedor baseadas em env, o caminho de configuração do provedor live de QA e `CODEX_HOME` quando presente. - - Os diretórios de saída precisam permanecer sob a raiz do repositório para que o guest possa gravar de volta pelo workspace montado. + - Execuções live encaminham as entradas de autenticação de QA suportadas que são práticas para o guest: + chaves de provedor baseadas em env, o caminho da configuração de provedor live de QA e `CODEX_HOME` quando presente. + - Os diretórios de saída devem permanecer sob a raiz do repositório para que o guest possa gravar de volta através do workspace montado. - Grava o relatório + resumo normais de QA, além dos logs do Multipass, em `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - - Inicia o site de QA com suporte de Docker para trabalho de QA no estilo operador. + - Inicia o site de QA com suporte Docker para trabalho de QA em estilo de operador. +- `pnpm openclaw qa aimock` + - Inicia apenas o servidor local do provedor AIMock para testes diretos de fumaça de protocolo. - `pnpm openclaw qa matrix` - - Executa a lane live de QA do Matrix contra um homeserver Tuwunel descartável com suporte de Docker. - - Esse host de QA hoje é apenas para repo/dev. Instalações empacotadas do OpenClaw não incluem - `qa-lab`, portanto não expõem `openclaw qa`. - - Checkouts do repositório carregam o runner empacotado diretamente; não é necessária uma etapa separada de instalação de Plugin. - - Provisiona três usuários temporários do Matrix (`driver`, `sut`, `observer`) mais uma sala privada, e então inicia um processo filho de Gateway de QA com o Plugin real do Matrix como transporte do SUT. - - Usa por padrão a imagem estável fixada do Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Substitua com `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` quando precisar testar outra imagem. - - O Matrix não expõe flags compartilhadas de fonte de credenciais porque a lane provisiona usuários descartáveis localmente. + - Executa a faixa live de QA do Matrix contra um homeserver Tuwunel descartável com suporte Docker. + - Esse host de QA atualmente é apenas para repositório/desenvolvimento. Instalações empacotadas do OpenClaw não incluem `qa-lab`, portanto não expõem `openclaw qa`. + - Checkouts do repositório carregam diretamente o executor empacotado; nenhuma etapa separada de instalação de Plugin é necessária. + - Provisiona três usuários temporários do Matrix (`driver`, `sut`, `observer`) mais uma sala privada, e então inicia um processo filho do Gateway de QA com o Plugin real do Matrix como transporte do SUT. + - Usa por padrão a imagem estável fixada do Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Substitua com `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` quando precisar testar uma imagem diferente. + - O Matrix não expõe flags compartilhadas de origem de credencial porque a faixa provisiona usuários descartáveis localmente. - Grava um relatório de QA do Matrix, resumo, artefato de eventos observados e log combinado de stdout/stderr em `.artifacts/qa-e2e/...`. - `pnpm openclaw qa telegram` - - Executa a lane live de QA do Telegram contra um grupo privado real usando os tokens de bot do driver e do SUT vindos do env. + - Executa a faixa live de QA do Telegram contra um grupo privado real usando os tokens do bot driver e do bot SUT a partir de env. - Requer `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` e `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. O id do grupo deve ser o id numérico do chat do Telegram. - - Suporta `--credential-source convex` para credenciais compartilhadas em pool. Use o modo env por padrão, ou defina `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` para optar por leases compartilhados. - - Requer dois bots distintos no mesmo grupo privado, com o bot do SUT expondo um nome de usuário do Telegram. - - Para observação estável de bot para bot, habilite Bot-to-Bot Communication Mode no `@BotFather` para ambos os bots e garanta que o bot driver consiga observar o tráfego de bots no grupo. + - Oferece suporte a `--credential-source convex` para credenciais compartilhadas em pool. Use o modo env por padrão, ou defina `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` para aderir a leases em pool. + - Requer dois bots distintos no mesmo grupo privado, com o bot SUT expondo um nome de usuário do Telegram. + - Para observação estável de bot para bot, habilite o Modo de Comunicação Bot-to-Bot no `@BotFather` para ambos os bots e garanta que o bot driver consiga observar o tráfego de bots no grupo. - Grava um relatório de QA do Telegram, resumo e artefato de mensagens observadas em `.artifacts/qa-e2e/...`. -As lanes live de transporte compartilham um contrato padrão para que novos transportes não se desviem: +As faixas de transporte live compartilham um contrato padrão para que novos transportes não saiam do alinhamento: -`qa-channel` continua sendo a suíte ampla de QA sintética e não faz parte da matriz de cobertura de transporte live. +`qa-channel` continua sendo a ampla suíte de QA sintética e não faz parte da matriz de cobertura de transporte live. -| Lane | Canary | Gating de menção | Bloco de allowlist | Resposta de nível superior | Retomada após reinício | Acompanhamento em thread | Isolamento de thread | Observação de reação | Comando de ajuda | -| -------- | ------ | ---------------- | ------------------ | -------------------------- | ---------------------- | ------------------------ | -------------------- | -------------------- | ---------------- | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Faixa | Canary | Controle por menção | Bloqueio de allowlist | Resposta de nível superior | Retomada após reinício | Follow-up em thread | Isolamento de thread | Observação de reação | Comando de ajuda | +| -------- | ------ | ------------------- | --------------------- | -------------------------- | ---------------------- | ------------------- | -------------------- | ------------------- | ---------------- | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | ### Credenciais compartilhadas do Telegram via Convex (v1) -Quando `--credential-source convex` (ou `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) está habilitado para -`openclaw qa telegram`, o laboratório de QA adquire um lease exclusivo de um pool com suporte de Convex, envia Heartbeat -desse lease enquanto a lane está em execução e libera o lease no encerramento. +Quando `--credential-source convex` (ou `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) estiver habilitado para +`openclaw qa telegram`, o QA lab adquire um lease exclusivo de um pool com suporte Convex, envia Heartbeat +desse lease enquanto a faixa estiver em execução e libera o lease no encerramento. -Estrutura de referência do projeto Convex: +Scaffold de referência do projeto Convex: - `qa/convex-credential-broker/` Variáveis de ambiente obrigatórias: - `OPENCLAW_QA_CONVEX_SITE_URL` (por exemplo `https://your-deployment.convex.site`) -- Um secret para a função selecionada: +- Um segredo para o papel selecionado: - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` para `maintainer` - `OPENCLAW_QA_CONVEX_SECRET_CI` para `ci` -- Seleção da função de credencial: +- Seleção do papel da credencial: - CLI: `--credential-role maintainer|ci` - - Padrão no env: `OPENCLAW_QA_CREDENTIAL_ROLE` (o padrão é `maintainer`) + - Padrão por env: `OPENCLAW_QA_CREDENTIAL_ROLE` (o padrão é `maintainer`) Variáveis de ambiente opcionais: @@ -121,14 +124,14 @@ Variáveis de ambiente opcionais: - `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (padrão `15000`) - `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (padrão `/qa-credentials/v1`) - `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (id de rastreamento opcional) -- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` permite URLs Convex `http://` de loopback para desenvolvimento somente local. +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` permite URLs Convex `http://` de loopback para desenvolvimento apenas local. `OPENCLAW_QA_CONVEX_SITE_URL` deve usar `https://` em operação normal. -Comandos administrativos de maintainer (adicionar/remover/listar pool) exigem +Comandos administrativos de mantenedor (adicionar/remover/listar pool) exigem `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` especificamente. -Helpers de CLI para maintainers: +Helpers de CLI para mantenedores: ```bash pnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.json @@ -138,7 +141,7 @@ pnpm openclaw qa credentials remove --credential-id Use `--json` para saída legível por máquina em scripts e utilitários de CI. -Contrato de endpoint padrão (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): +Contrato padrão do endpoint (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): - `POST /acquire` - Requisição: `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` @@ -150,34 +153,34 @@ Contrato de endpoint padrão (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v - `POST /release` - Requisição: `{ kind, ownerId, actorRole, credentialId, leaseToken }` - Sucesso: `{ status: "ok" }` (ou `2xx` vazio) -- `POST /admin/add` (somente secret de maintainer) +- `POST /admin/add` (somente com segredo de maintainer) - Requisição: `{ kind, actorId, payload, note?, status? }` - Sucesso: `{ status: "ok", credential }` -- `POST /admin/remove` (somente secret de maintainer) +- `POST /admin/remove` (somente com segredo de maintainer) - Requisição: `{ credentialId, actorId }` - Sucesso: `{ status: "ok", changed, credential }` - - Proteção contra lease ativo: `{ status: "error", code: "LEASE_ACTIVE", ... }` -- `POST /admin/list` (somente secret de maintainer) + - Proteção de lease ativo: `{ status: "error", code: "LEASE_ACTIVE", ... }` +- `POST /admin/list` (somente com segredo de maintainer) - Requisição: `{ kind?, status?, includePayload?, limit? }` - Sucesso: `{ status: "ok", credentials, count }` -Formato do payload para o tipo Telegram: +Formato de payload para o tipo Telegram: - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId` deve ser uma string numérica de id de chat do Telegram. +- `groupId` deve ser uma string com o id numérico do chat do Telegram. - `admin/add` valida esse formato para `kind: "telegram"` e rejeita payloads malformados. ### Adicionando um canal ao QA -Adicionar um canal ao sistema de QA em Markdown exige exatamente duas coisas: +Adicionar um canal ao sistema de QA em markdown exige exatamente duas coisas: 1. Um adaptador de transporte para o canal. 2. Um pacote de cenários que exercite o contrato do canal. Não adicione uma nova raiz de comando de QA de nível superior quando o host compartilhado `qa-lab` puder -ser dono do fluxo. +ser o dono do fluxo. -`qa-lab` é responsável pela mecânica compartilhada do host: +`qa-lab` é o dono da mecânica compartilhada do host: - a raiz de comando `openclaw qa` - inicialização e encerramento da suíte @@ -185,9 +188,9 @@ ser dono do fluxo. - gravação de artefatos - geração de relatórios - execução de cenários -- aliases de compatibilidade para cenários antigos de `qa-channel` +- aliases de compatibilidade para cenários antigos do `qa-channel` -Os Plugins de runner são responsáveis pelo contrato de transporte: +Plugins de executores são donos do contrato de transporte: - como `openclaw qa ` é montado sob a raiz compartilhada `qa` - como o Gateway é configurado para esse transporte @@ -201,23 +204,23 @@ Os Plugins de runner são responsáveis pelo contrato de transporte: A barra mínima de adoção para um novo canal é: 1. Manter `qa-lab` como dono da raiz compartilhada `qa`. -2. Implementar o runner de transporte na seam de host compartilhada do `qa-lab`. -3. Manter a mecânica específica do transporte dentro do Plugin do runner ou do harness do Plugin. -4. Montar o runner como `openclaw qa ` em vez de registrar uma raiz de comando concorrente. - Os Plugins de runner devem declarar `qaRunners` em `openclaw.plugin.json` e exportar um array `qaRunnerCliRegistrations` correspondente em `runtime-api.ts`. - Mantenha `runtime-api.ts` leve; a execução lazy de CLI e runner deve ficar atrás de entrypoints separados. -5. Criar ou adaptar cenários em Markdown em `qa/scenarios/`. +2. Implementar o executor de transporte na seam compartilhada do host `qa-lab`. +3. Manter a mecânica específica de transporte dentro do Plugin do executor ou do harness do Plugin. +4. Montar o executor como `openclaw qa ` em vez de registrar uma raiz de comando concorrente. + Plugins de executor devem declarar `qaRunners` em `openclaw.plugin.json` e exportar um array correspondente `qaRunnerCliRegistrations` a partir de `runtime-api.ts`. + Mantenha `runtime-api.ts` leve; a execução lazy de CLI e de executores deve ficar atrás de entrypoints separados. +5. Criar ou adaptar cenários em markdown sob `qa/scenarios/`. 6. Usar os helpers genéricos de cenário para novos cenários. 7. Manter os aliases de compatibilidade existentes funcionando, a menos que o repositório esteja fazendo uma migração intencional. A regra de decisão é rígida: -- Se o comportamento puder ser expresso uma vez no `qa-lab`, coloque-o no `qa-lab`. -- Se o comportamento depender de um transporte de canal, mantenha-o nesse Plugin de runner ou harness de Plugin. +- Se o comportamento puder ser expresso uma única vez em `qa-lab`, coloque-o em `qa-lab`. +- Se o comportamento depender de um transporte de canal, mantenha-o nesse Plugin de executor ou harness de Plugin. - Se um cenário precisar de uma nova capacidade que mais de um canal possa usar, adicione um helper genérico em vez de um branch específico de canal em `suite.ts`. -- Se um comportamento só fizer sentido para um transporte, mantenha o cenário específico daquele transporte e deixe isso explícito no contrato do cenário. +- Se um comportamento só fizer sentido para um transporte, mantenha o cenário específico desse transporte e deixe isso explícito no contrato do cenário. -Nomes preferidos de helpers genéricos para novos cenários são: +Os nomes preferidos de helper genérico para novos cenários são: - `waitForTransportReady` - `waitForChannelReady` @@ -240,65 +243,65 @@ Aliases de compatibilidade continuam disponíveis para cenários existentes, inc - `formatConversationTranscript` - `resetBus` -Novos trabalhos de canal devem usar os nomes genéricos dos helpers. -Os aliases de compatibilidade existem para evitar uma migração de flag day, não como modelo para -a criação de novos cenários. +Novos trabalhos de canal devem usar os nomes genéricos de helper. +Os aliases de compatibilidade existem para evitar uma migração em dia marcado, não como o modelo para +criação de novos cenários. ## Suítes de teste (o que roda onde) -Pense nas suítes como “realismo crescente” (e crescente flakiness/custo): +Pense nas suítes como “realismo crescente” (e crescente instabilidade/custo): -### Unit / integration (padrão) +### Unit / integração (padrão) - Comando: `pnpm test` - Configuração: dez execuções sequenciais de shards (`vitest.full-*.config.ts`) sobre os projetos Vitest com escopo já existentes -- Arquivos: inventários de core/unit em `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` e os testes Node de `ui` na allowlist cobertos por `vitest.unit.config.ts` +- Arquivos: inventários core/unit em `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` e os testes Node em `ui` incluídos na allowlist cobertos por `vitest.unit.config.ts` - Escopo: - Testes unitários puros - Testes de integração in-process (autenticação do Gateway, roteamento, ferramentas, parsing, config) - Regressões determinísticas para bugs conhecidos - Expectativas: - - Roda no CI + - Roda em CI - Não requer chaves reais - Deve ser rápido e estável - Observação sobre projetos: - - `pnpm test` sem alvo agora executa onze configurações menores de shard (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) em vez de um único processo gigante do projeto raiz nativo. Isso reduz o RSS de pico em máquinas carregadas e evita que trabalho de auto-reply/extensão sufoque suítes não relacionadas. - - `pnpm test --watch` ainda usa o grafo de projetos nativo da raiz em `vitest.config.ts`, porque um loop de watch com múltiplos shards não é prático. - - `pnpm test`, `pnpm test:watch` e `pnpm test:perf:imports` encaminham primeiro alvos explícitos de arquivo/diretório por lanes com escopo, então `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` evita pagar o custo de inicialização do projeto raiz completo. - - `pnpm test:changed` expande caminhos Git alterados para as mesmas lanes com escopo quando o diff toca apenas arquivos de origem/teste roteáveis; edições de config/setup ainda fazem fallback para a reexecução ampla do projeto raiz. - - Testes unitários leves de importação de agents, commands, plugins, helpers de auto-reply, `plugin-sdk` e áreas utilitárias puras semelhantes passam pela lane `unit-fast`, que ignora `test/setup-openclaw-runtime.ts`; arquivos pesados de estado/runtime permanecem nas lanes existentes. - - Arquivos helper de origem selecionados de `plugin-sdk` e `commands` também mapeiam execuções no modo changed para testes irmãos explícitos nessas lanes leves, para que edições em helpers evitem reexecutar toda a suíte pesada daquele diretório. - - `auto-reply` agora tem três buckets dedicados: helpers principais de nível superior do core, testes de integração `reply.*` de nível superior e a subárvore `src/auto-reply/reply/**`. Isso mantém o trabalho mais pesado do harness de reply fora dos testes baratos de status/chunk/token. -- Observação sobre runner embutido: + - `pnpm test` sem alvo agora executa onze configurações menores de shard (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) em vez de um único processo gigante do projeto raiz nativo. Isso reduz o pico de RSS em máquinas carregadas e evita que trabalho de auto-reply/extensão prejudique suítes não relacionadas. + - `pnpm test --watch` ainda usa o grafo de projetos nativo da raiz em `vitest.config.ts`, porque um loop de watch multi-shard não é prático. + - `pnpm test`, `pnpm test:watch` e `pnpm test:perf:imports` roteiam alvos explícitos de arquivo/diretório primeiro por faixas com escopo, então `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` evita pagar o custo total de inicialização do projeto raiz. + - `pnpm test:changed` expande caminhos alterados do git para as mesmas faixas com escopo quando o diff toca apenas arquivos de código/teste roteáveis; edições de config/setup ainda recorrem à reexecução ampla do projeto raiz. + - Testes unitários leves de importação de agents, commands, plugins, helpers de auto-reply, `plugin-sdk` e áreas utilitárias puras semelhantes são roteados pela faixa `unit-fast`, que ignora `test/setup-openclaw-runtime.ts`; arquivos com estado/runtime pesado permanecem nas faixas existentes. + - Arquivos-fonte auxiliares selecionados de `plugin-sdk` e `commands` também mapeiam execuções em modo changed para testes irmãos explícitos nessas faixas leves, para que edições em helpers evitem reexecutar a suíte pesada completa daquele diretório. + - `auto-reply` agora tem três buckets dedicados: helpers core de nível superior, testes de integração `reply.*` de nível superior e a subárvore `src/auto-reply/reply/**`. Isso mantém o trabalho mais pesado do harness de reply fora dos testes baratos de status/chunk/token. +- Observação sobre executor embutido: - Quando você alterar entradas de descoberta de ferramentas de mensagem ou contexto de runtime de Compaction, mantenha ambos os níveis de cobertura. - - Adicione regressões focadas de helper para limites puros de roteamento/normalização. - - Também mantenha saudáveis as suítes de integração do runner embutido: + - Adicione regressões focadas em helpers para limites puros de roteamento/normalização. + - Também mantenha saudáveis as suítes de integração do executor embutido: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` e `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - Essas suítes verificam que ids com escopo e o comportamento de Compaction continuam fluindo - pelos caminhos reais de `run.ts` / `compact.ts`; testes somente de helper não são um + pelos caminhos reais `run.ts` / `compact.ts`; testes apenas de helper não são um substituto suficiente para esses caminhos de integração. - Observação sobre pool: - A configuração base do Vitest agora usa `threads` por padrão. - - A configuração compartilhada do Vitest também fixa `isolate: false` e usa o runner não isolado em todos os projetos raiz, e2e e live. - - A lane UI raiz mantém sua configuração `jsdom` e otimizador, mas agora também roda no runner compartilhado não isolado. + - A configuração compartilhada do Vitest também fixa `isolate: false` e usa o executor não isolado nos projetos da raiz, nas configurações e2e e live. + - A faixa UI da raiz mantém sua configuração `jsdom` e otimizador, mas agora também roda no executor compartilhado não isolado. - Cada shard de `pnpm test` herda os mesmos padrões `threads` + `isolate: false` da configuração compartilhada do Vitest. - - O launcher compartilhado `scripts/run-vitest.mjs` agora também adiciona `--no-maglev` por padrão para processos Node filhos do Vitest para reduzir churn de compilação do V8 durante grandes execuções locais. Defina `OPENCLAW_VITEST_ENABLE_MAGLEV=1` se precisar comparar com o comportamento padrão do V8. + - O lançador compartilhado `scripts/run-vitest.mjs` agora também adiciona `--no-maglev` por padrão para processos Node filhos do Vitest para reduzir churn de compilação do V8 durante grandes execuções locais. Defina `OPENCLAW_VITEST_ENABLE_MAGLEV=1` se precisar comparar com o comportamento padrão do V8. - Observação sobre iteração local rápida: - - `pnpm test:changed` passa por lanes com escopo quando os caminhos alterados mapeiam claramente para uma suíte menor. + - `pnpm test:changed` roteia por faixas com escopo quando os caminhos alterados mapeiam de forma limpa para uma suíte menor. - `pnpm test:max` e `pnpm test:changed:max` mantêm o mesmo comportamento de roteamento, apenas com um limite maior de workers. - - O autoescalonamento local de workers agora é intencionalmente conservador e também recua quando a média de carga do host já está alta, para que múltiplas execuções concorrentes do Vitest causem menos impacto por padrão. - - A configuração base do Vitest marca os arquivos de projetos/config como `forceRerunTriggers` para que reexecuções no modo changed continuem corretas quando o wiring de testes muda. + - O autoescalonamento local de workers agora é intencionalmente conservador e também recua quando a média de carga do host já está alta, para que várias execuções simultâneas do Vitest causem menos impacto por padrão. + - A configuração base do Vitest marca os arquivos de projetos/config como `forceRerunTriggers` para que reexecuções em modo changed continuem corretas quando a fiação dos testes muda. - A configuração mantém `OPENCLAW_VITEST_FS_MODULE_CACHE` habilitado em hosts compatíveis; defina `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` se quiser um local de cache explícito para profiling direto. - Observação sobre depuração de performance: - - `pnpm test:perf:imports` habilita relatórios de duração de importação do Vitest e também saída de breakdown de importação. - - `pnpm test:perf:imports:changed` aplica a mesma visão de profiling aos arquivos alterados desde `origin/main`. -- `pnpm test:perf:changed:bench -- --ref ` compara `test:changed` roteado com o caminho nativo do projeto raiz para esse diff commitado e imprime tempo total mais RSS máximo no macOS. -- `pnpm test:perf:changed:bench -- --worktree` mede o tree sujo atual roteando a lista de arquivos alterados por `scripts/test-projects.mjs` e pela configuração raiz do Vitest. - - `pnpm test:perf:profile:main` grava um perfil de CPU da thread principal para overhead de inicialização e transformação do Vitest/Vite. - - `pnpm test:perf:profile:runner` grava perfis de CPU+heap do runner para a suíte unit com paralelismo de arquivos desativado. + - `pnpm test:perf:imports` habilita relatório de duração de importação do Vitest mais saída de detalhamento de importações. + - `pnpm test:perf:imports:changed` restringe a mesma visualização de profiling a arquivos alterados desde `origin/main`. +- `pnpm test:perf:changed:bench -- --ref ` compara `test:changed` roteado com o caminho nativo do projeto raiz para aquele diff commitado e imprime wall time mais RSS máximo no macOS. +- `pnpm test:perf:changed:bench -- --worktree` mede a árvore suja atual roteando a lista de arquivos alterados por `scripts/test-projects.mjs` e pela configuração Vitest da raiz. + - `pnpm test:perf:profile:main` grava um perfil de CPU da thread principal para sobrecarga de inicialização e transformação do Vitest/Vite. + - `pnpm test:perf:profile:runner` grava perfis de CPU+heap do executor para a suíte unit com paralelismo de arquivos desabilitado. ### E2E (smoke do Gateway) @@ -306,17 +309,17 @@ Pense nas suítes como “realismo crescente” (e crescente flakiness/custo): - Configuração: `vitest.e2e.config.ts` - Arquivos: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` - Padrões de runtime: - - Usa `threads` do Vitest com `isolate: false`, alinhado com o restante do repositório. + - Usa `threads` do Vitest com `isolate: false`, correspondendo ao restante do repositório. - Usa workers adaptativos (CI: até 2, local: 1 por padrão). - - Roda em modo silencioso por padrão para reduzir overhead de I/O no console. -- Overrides úteis: + - Roda em modo silencioso por padrão para reduzir a sobrecarga de I/O de console. +- Substituições úteis: - `OPENCLAW_E2E_WORKERS=` para forçar a contagem de workers (limitada a 16). - - `OPENCLAW_E2E_VERBOSE=1` para reativar saída detalhada no console. + - `OPENCLAW_E2E_VERBOSE=1` para reativar a saída detalhada no console. - Escopo: - - Comportamento end-to-end do Gateway com múltiplas instâncias - - Superfícies WebSocket/HTTP, pareamento de Node e networking mais pesado + - Comportamento end-to-end de múltiplas instâncias do Gateway + - Superfícies WebSocket/HTTP, pareamento de Node e redes mais pesadas - Expectativas: - - Roda no CI (quando habilitado no pipeline) + - Roda em CI (quando habilitado no pipeline) - Não requer chaves reais - Tem mais partes móveis do que testes unitários (pode ser mais lento) @@ -327,13 +330,13 @@ Pense nas suítes como “realismo crescente” (e crescente flakiness/custo): - Escopo: - Inicia um Gateway OpenShell isolado no host via Docker - Cria um sandbox a partir de um Dockerfile local temporário - - Exercita o backend OpenShell do OpenClaw sobre `sandbox ssh-config` + execução SSH reais - - Verifica o comportamento canônico remoto do sistema de arquivos por meio da bridge fs do sandbox + - Exercita o backend OpenShell do OpenClaw sobre `sandbox ssh-config` real + execução SSH + - Verifica o comportamento canônico de sistema de arquivos remoto por meio da ponte fs do sandbox - Expectativas: - Apenas opt-in; não faz parte da execução padrão de `pnpm test:e2e` - - Requer um CLI `openshell` local e um daemon Docker funcional + - Requer uma CLI local `openshell` mais um daemon Docker funcional - Usa `HOME` / `XDG_CONFIG_HOME` isolados, depois destrói o Gateway e o sandbox de teste -- Overrides úteis: +- Substituições úteis: - `OPENCLAW_E2E_OPENSHELL=1` para habilitar o teste ao executar manualmente a suíte e2e mais ampla - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` para apontar para um binário CLI não padrão ou script wrapper @@ -344,30 +347,30 @@ Pense nas suítes como “realismo crescente” (e crescente flakiness/custo): - Arquivos: `src/**/*.live.test.ts` - Padrão: **habilitado** por `pnpm test:live` (define `OPENCLAW_LIVE_TEST=1`) - Escopo: - - “Este provedor/modelo realmente funciona _hoje_ com credenciais reais?” - - Captura mudanças no formato do provedor, peculiaridades de chamada de ferramenta, problemas de autenticação e comportamento de rate limit + - “Esse provedor/modelo realmente funciona _hoje_ com credenciais reais?” + - Captura mudanças de formato do provedor, peculiaridades de chamada de ferramenta, problemas de autenticação e comportamento de limite de taxa - Expectativas: - Não é estável em CI por definição (redes reais, políticas reais de provedores, cotas, indisponibilidades) - - Custa dinheiro / usa rate limits - - Prefira executar subconjuntos reduzidos em vez de “tudo” -- Execuções live carregam `~/.profile` para obter chaves de API ausentes. -- Por padrão, execuções live ainda isolam `HOME` e copiam material de config/auth para um diretório home temporário de teste, para que fixtures unit não possam alterar seu `~/.openclaw` real. -- Defina `OPENCLAW_LIVE_USE_REAL_HOME=1` apenas quando precisar intencionalmente que os testes live usem seu diretório home real. -- `pnpm test:live` agora usa por padrão um modo mais silencioso: mantém a saída de progresso `[live] ...`, mas suprime o aviso extra de `~/.profile` e silencia logs de bootstrap do Gateway/chatter do Bonjour. Defina `OPENCLAW_LIVE_TEST_QUIET=0` se quiser os logs completos de inicialização de volta. -- Rotação de chaves de API (específica do provedor): defina `*_API_KEYS` com formato de vírgula/ponto e vírgula ou `*_API_KEY_1`, `*_API_KEY_2` (por exemplo `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) ou override por live com `OPENCLAW_LIVE_*_KEY`; os testes tentam novamente em respostas de rate limit. + - Custa dinheiro / usa limites de taxa + - Prefira executar subconjuntos restritos em vez de “tudo” +- Execuções live obtêm `~/.profile` para captar chaves de API ausentes. +- Por padrão, execuções live ainda isolam `HOME` e copiam material de config/auth para um home temporário de teste para que fixtures unitários não possam alterar seu `~/.openclaw` real. +- Defina `OPENCLAW_LIVE_USE_REAL_HOME=1` apenas quando intencionalmente precisar que os testes live usem seu diretório home real. +- `pnpm test:live` agora usa por padrão um modo mais silencioso: ele mantém a saída de progresso `[live] ...`, mas oculta o aviso extra de `~/.profile` e silencia logs de bootstrap do Gateway/chatter do Bonjour. Defina `OPENCLAW_LIVE_TEST_QUIET=0` se quiser recuperar os logs completos de inicialização. +- Rotação de chave de API (específica por provedor): defina `*_API_KEYS` com formato de vírgula/ponto e vírgula ou `*_API_KEY_1`, `*_API_KEY_2` (por exemplo `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) ou substituição por live via `OPENCLAW_LIVE_*_KEY`; os testes tentam novamente em respostas de limite de taxa. - Saída de progresso/Heartbeat: - - As suítes live agora emitem linhas de progresso para stderr, para que chamadas longas de provedor apareçam como ativas mesmo quando a captura de console do Vitest está silenciosa. - - `vitest.live.config.ts` desabilita a interceptação de console do Vitest para que as linhas de progresso de provedor/Gateway sejam transmitidas imediatamente durante execuções live. - - Ajuste os Heartbeats de modelo direto com `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Ajuste os Heartbeats de Gateway/sonda com `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. + - As suítes live agora emitem linhas de progresso para stderr para que chamadas longas ao provedor permaneçam visivelmente ativas mesmo quando a captura de console do Vitest está silenciosa. + - `vitest.live.config.ts` desabilita a interceptação de console do Vitest para que linhas de progresso de provedor/Gateway fluam imediatamente durante execuções live. + - Ajuste Heartbeats de modelo direto com `OPENCLAW_LIVE_HEARTBEAT_MS`. + - Ajuste Heartbeats de Gateway/probe com `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## Qual suíte devo executar? Use esta tabela de decisão: - Editando lógica/testes: execute `pnpm test` (e `pnpm test:coverage` se você mudou muita coisa) -- Mexendo em networking do Gateway / protocolo WS / pareamento: adicione `pnpm test:e2e` -- Depurando “meu bot caiu” / falhas específicas de provedor / chamada de ferramenta: execute um `pnpm test:live` reduzido +- Tocando em rede do Gateway / protocolo WS / pareamento: adicione `pnpm test:e2e` +- Depurando “meu bot caiu” / falhas específicas de provedor / chamada de ferramenta: execute um `pnpm test:live` restrito ## Live: varredura de capacidades do Node Android @@ -375,23 +378,23 @@ Use esta tabela de decisão: - Script: `pnpm android:test:integration` - Objetivo: invocar **todos os comandos atualmente anunciados** por um Node Android conectado e validar o comportamento do contrato de comando. - Escopo: - - Configuração prévia/manual (a suíte não instala/executa/faz pareamento do app). + - Setup manual/com pré-condições (a suíte não instala/executa/faz pareamento do app). - Validação `node.invoke` do Gateway comando por comando para o Node Android selecionado. -- Pré-configuração obrigatória: +- Pré-setup obrigatório: - App Android já conectado + pareado ao Gateway. - App mantido em primeiro plano. - Permissões/consentimento de captura concedidos para as capacidades que você espera que passem. -- Overrides opcionais de alvo: +- Substituições opcionais de alvo: - `OPENCLAW_ANDROID_NODE_ID` ou `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. -- Detalhes completos da configuração do Android: [App Android](/pt-BR/platforms/android) +- Detalhes completos de setup do Android: [App Android](/pt-BR/platforms/android) -## Live: smoke de modelos (chaves de perfil) +## Live: smoke de modelo (chaves de perfil) Os testes live são divididos em duas camadas para que possamos isolar falhas: -- “Modelo direto” nos informa se o provedor/modelo consegue responder com aquela chave. -- “Smoke do Gateway” nos informa se o pipeline completo de Gateway+agente funciona para aquele modelo (sessões, histórico, ferramentas, política de sandbox etc.). +- “Modelo direto” nos diz se o provedor/modelo consegue responder de fato com a chave fornecida. +- “Smoke do Gateway” nos diz se o pipeline completo Gateway+agente funciona para esse modelo (sessões, histórico, ferramentas, política de sandbox etc.). ### Camada 1: conclusão direta do modelo (sem Gateway) @@ -401,55 +404,55 @@ Os testes live são divididos em duas camadas para que possamos isolar falhas: - Usar `getApiKeyForModel` para selecionar modelos para os quais você tem credenciais - Executar uma pequena conclusão por modelo (e regressões direcionadas quando necessário) - Como habilitar: - - `pnpm test:live` (ou `OPENCLAW_LIVE_TEST=1` se estiver invocando o Vitest diretamente) + - `pnpm test:live` (ou `OPENCLAW_LIVE_TEST=1` ao invocar o Vitest diretamente) - Defina `OPENCLAW_LIVE_MODELS=modern` (ou `all`, alias para modern) para realmente executar esta suíte; caso contrário, ela é ignorada para manter `pnpm test:live` focado no smoke do Gateway - Como selecionar modelos: - `OPENCLAW_LIVE_MODELS=modern` para executar a allowlist moderna (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - `OPENCLAW_LIVE_MODELS=all` é um alias para a allowlist moderna - ou `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (allowlist separada por vírgulas) - - Varreduras modern/all usam por padrão um limite curado de alto sinal; defina `OPENCLAW_LIVE_MAX_MODELS=0` para uma varredura moderna exaustiva ou um número positivo para um limite menor. + - As varreduras modern/all usam por padrão um limite curado de alto sinal; defina `OPENCLAW_LIVE_MAX_MODELS=0` para uma varredura moderna exaustiva ou um número positivo para um limite menor. - Como selecionar provedores: - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist separada por vírgulas) - De onde vêm as chaves: - - Por padrão: armazenamento de perfis e fallbacks de env + - Por padrão: armazenamento de perfis e fallbacks por env - Defina `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para exigir **apenas armazenamento de perfis** - Por que isso existe: - Separa “a API do provedor está quebrada / a chave é inválida” de “o pipeline do agente Gateway está quebrado” - - Contém regressões pequenas e isoladas (exemplo: replay de raciocínio do OpenAI Responses/Codex Responses + fluxos de tool-call) + - Contém regressões pequenas e isoladas (exemplo: replay de raciocínio OpenAI Responses/Codex Responses + fluxos de chamada de ferramenta) -### Camada 2: smoke do Gateway + agente dev (o que `@openclaw` realmente faz) +### Camada 2: smoke do Gateway + agente dev (o que o "@openclaw" realmente faz) - Teste: `src/gateway/gateway-models.profiles.live.test.ts` - Objetivo: - - Inicializar um Gateway in-process - - Criar/aplicar patch em uma sessão `agent:dev:*` (override de modelo por execução) - - Iterar modelos-com-chaves e validar: + - Subir um Gateway in-process + - Criar/atualizar uma sessão `agent:dev:*` (substituição de modelo por execução) + - Iterar por modelos com chaves e validar: - resposta “significativa” (sem ferramentas) - - uma invocação real de ferramenta funciona (sonda de `read`) - - sondas opcionais extras de ferramenta (sonda de `exec+read`) - - caminhos de regressão do OpenAI (somente tool-call → acompanhamento) continuam funcionando -- Detalhes das sondas (para que você consiga explicar falhas rapidamente): - - sonda `read`: o teste grava um arquivo nonce no workspace e pede ao agente para fazer `read` nele e devolver o nonce. - - sonda `exec+read`: o teste pede ao agente para usar `exec` para gravar um nonce em um arquivo temporário e depois fazer `read` dele. - - sonda de imagem: o teste anexa um PNG gerado (gato + código aleatório) e espera que o modelo retorne `cat `. + - uma invocação real de ferramenta funciona (probe de leitura) + - probes opcionais extras de ferramenta (probe de exec+read) + - caminhos de regressão do OpenAI (somente chamada de ferramenta → follow-up) continuam funcionando +- Detalhes dos probes (para que você consiga explicar falhas rapidamente): + - probe `read`: o teste grava um arquivo nonce no workspace e pede ao agente para `read` o arquivo e ecoar o nonce de volta. + - probe `exec+read`: o teste pede ao agente para gravar um nonce com `exec` em um arquivo temporário e depois `read` de volta. + - probe de imagem: o teste anexa um PNG gerado (gato + código aleatório) e espera que o modelo retorne `cat `. - Referência de implementação: `src/gateway/gateway-models.profiles.live.test.ts` e `src/gateway/live-image-probe.ts`. - Como habilitar: - - `pnpm test:live` (ou `OPENCLAW_LIVE_TEST=1` se estiver invocando o Vitest diretamente) + - `pnpm test:live` (ou `OPENCLAW_LIVE_TEST=1` ao invocar o Vitest diretamente) - Como selecionar modelos: - Padrão: allowlist moderna (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - `OPENCLAW_LIVE_GATEWAY_MODELS=all` é um alias para a allowlist moderna - Ou defina `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (ou lista separada por vírgulas) para restringir - - Varreduras modernas/all do Gateway usam por padrão um limite curado de alto sinal; defina `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` para uma varredura moderna exaustiva ou um número positivo para um limite menor. + - As varreduras modern/all do Gateway usam por padrão um limite curado de alto sinal; defina `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` para uma varredura moderna exaustiva ou um número positivo para um limite menor. - Como selecionar provedores (evite “OpenRouter tudo”): - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist separada por vírgulas) -- As sondas de ferramenta + imagem estão sempre ativadas neste teste live: - - sonda `read` + sonda `exec+read` (stress de ferramentas) - - a sonda de imagem roda quando o modelo anuncia suporte a entrada de imagem +- Os probes de ferramenta + imagem estão sempre ativados neste teste live: + - probe `read` + probe `exec+read` (estresse de ferramenta) + - o probe de imagem roda quando o modelo anuncia suporte a entrada de imagem - Fluxo (alto nível): - - O teste gera um PNG pequeno com “CAT” + código aleatório (`src/gateway/live-image-probe.ts`) + - O teste gera um PNG minúsculo com “CAT” + código aleatório (`src/gateway/live-image-probe.ts`) - Envia via `agent` `attachments: [{ mimeType: "image/png", content: "" }]` - - O Gateway faz parse dos anexos em `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - - O agente embutido encaminha uma mensagem de usuário multimodal ao modelo + - O Gateway faz parsing dos anexos em `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) + - O agente embutido encaminha uma mensagem de usuário multimodal para o modelo - Validação: a resposta contém `cat` + o código (tolerância de OCR: pequenos erros são permitidos) Dica: para ver o que você pode testar na sua máquina (e os ids exatos `provider/model`), execute: @@ -459,26 +462,26 @@ openclaw models list openclaw models list --json ``` -## Live: smoke do backend CLI (Claude, Codex, Gemini ou outros CLIs locais) +## Live: smoke de backend CLI (Claude, Codex, Gemini ou outras CLIs locais) - Teste: `src/gateway/gateway-cli-backend.live.test.ts` - Objetivo: validar o pipeline Gateway + agente usando um backend CLI local, sem tocar na sua config padrão. -- Os padrões de smoke específicos do backend ficam na definição `cli-backend.ts` da extensão proprietária. +- Os padrões de smoke específicos do backend ficam com a definição `cli-backend.ts` da extensão proprietária. - Habilitar: - - `pnpm test:live` (ou `OPENCLAW_LIVE_TEST=1` se estiver invocando o Vitest diretamente) + - `pnpm test:live` (ou `OPENCLAW_LIVE_TEST=1` ao invocar o Vitest diretamente) - `OPENCLAW_LIVE_CLI_BACKEND=1` - Padrões: - Provedor/modelo padrão: `claude-cli/claude-sonnet-4-6` - - O comportamento de comando/args/imagem vem dos metadados do Plugin proprietário do backend CLI. -- Overrides opcionais: + - Comportamento de comando/args/imagem vem dos metadados do Plugin proprietário do backend CLI. +- Substituições (opcionais): - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` para enviar um anexo de imagem real (os caminhos são injetados no prompt). - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` para passar caminhos de arquivos de imagem como args de CLI em vez de injeção no prompt. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` para passar caminhos de arquivos de imagem como args da CLI em vez de injeção no prompt. - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (ou `"list"`) para controlar como args de imagem são passados quando `IMAGE_ARG` está definido. - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` para enviar um segundo turno e validar o fluxo de retomada. - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` para desabilitar a sonda padrão de continuidade na mesma sessão Claude Sonnet -> Opus (defina `1` para forçá-la quando o modelo selecionado oferecer suporte a um alvo de troca). + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` para desabilitar o probe padrão de continuidade na mesma sessão Claude Sonnet -> Opus (defina `1` para forçá-lo quando o modelo selecionado oferecer suporte a um alvo de troca). Exemplo: @@ -494,7 +497,7 @@ Receita Docker: pnpm test:docker:live-cli-backend ``` -Receitas Docker de provedor único: +Receitas Docker para provedor único: ```bash pnpm test:docker:live-cli-backend:claude @@ -505,21 +508,21 @@ pnpm test:docker:live-cli-backend:gemini Observações: -- O runner Docker fica em `scripts/test-live-cli-backend-docker.sh`. -- Ele executa o smoke live de backend CLI dentro da imagem Docker do repositório como o usuário não root `node`. -- Ele resolve os metadados de smoke do CLI a partir da extensão proprietária correspondente, depois instala o pacote CLI Linux correspondente (`@anthropic-ai/claude-code`, `@openai/codex` ou `@google/gemini-cli`) em um prefixo gravável com cache em `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (padrão: `~/.cache/openclaw/docker-cli-tools`). -- `pnpm test:docker:live-cli-backend:claude-subscription` requer OAuth portátil de assinatura do Claude Code por meio de `~/.claude/.credentials.json` com `claudeAiOauth.subscriptionType` ou `CLAUDE_CODE_OAUTH_TOKEN` de `claude setup-token`. Primeiro ele comprova `claude -p` direto no Docker, depois executa dois turnos do backend CLI do Gateway sem preservar variáveis de ambiente de chave de API da Anthropic. Essa lane de assinatura desabilita por padrão as sondas MCP/tool e de imagem do Claude porque o Claude atualmente encaminha o uso de apps de terceiros por cobrança de uso extra em vez dos limites normais do plano de assinatura. -- O smoke live de backend CLI agora exercita o mesmo fluxo end-to-end para Claude, Codex e Gemini: turno de texto, turno de classificação de imagem e depois chamada da ferramenta MCP `cron` validada pelo CLI do Gateway. -- O smoke padrão do Claude também aplica patch na sessão de Sonnet para Opus e verifica que a sessão retomada ainda se lembra de uma observação anterior. +- O executor Docker fica em `scripts/test-live-cli-backend-docker.sh`. +- Ele executa o smoke live do backend CLI dentro da imagem Docker do repositório como o usuário não root `node`. +- Ele resolve os metadados do smoke CLI a partir da extensão proprietária e depois instala o pacote Linux CLI correspondente (`@anthropic-ai/claude-code`, `@openai/codex` ou `@google/gemini-cli`) em um prefixo gravável com cache em `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (padrão: `~/.cache/openclaw/docker-cli-tools`). +- `pnpm test:docker:live-cli-backend:claude-subscription` requer OAuth portátil da assinatura do Claude Code por meio de `~/.claude/.credentials.json` com `claudeAiOauth.subscriptionType` ou `CLAUDE_CODE_OAUTH_TOKEN` de `claude setup-token`. Primeiro ele comprova `claude -p` direto no Docker e depois executa dois turnos de backend CLI do Gateway sem preservar variáveis de ambiente de chave de API da Anthropic. Essa faixa de assinatura desabilita por padrão os probes de MCP/ferramenta e imagem do Claude porque o Claude atualmente roteia o uso de apps de terceiros por cobrança de uso extra em vez dos limites normais do plano de assinatura. +- O smoke live do backend CLI agora exercita o mesmo fluxo end-to-end para Claude, Codex e Gemini: turno de texto, turno de classificação de imagem e então chamada da ferramenta MCP `cron` validada pela CLI do Gateway. +- O smoke padrão do Claude também atualiza a sessão de Sonnet para Opus e verifica que a sessão retomada ainda se lembra de uma anotação anterior. -## Live: smoke de bind de ACP (`/acp spawn ... --bind here`) +## Live: smoke de bind do ACP (`/acp spawn ... --bind here`) - Teste: `src/gateway/gateway-acp-bind.live.test.ts` -- Objetivo: validar o fluxo real de bind de conversa do ACP com um agente ACP live: +- Objetivo: validar o fluxo real de conversation-bind do ACP com um agente ACP live: - enviar `/acp spawn --bind here` - - vincular um contexto sintético de conversa de canal de mensagem no local - - enviar um acompanhamento normal nessa mesma conversa - - verificar que o acompanhamento chega à transcrição da sessão ACP vinculada + - vincular in place uma conversa sintética de canal de mensagem + - enviar um follow-up normal nessa mesma conversa + - verificar que o follow-up chega à transcrição da sessão ACP vinculada - Habilitar: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` @@ -528,14 +531,14 @@ Observações: - Agente ACP para `pnpm test:live ...` direto: `claude` - Canal sintético: contexto de conversa estilo DM do Slack - Backend ACP: `acpx` -- Overrides: +- Substituições: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` - `OPENCLAW_LIVE_ACP_BIND_AGENT=codex` - `OPENCLAW_LIVE_ACP_BIND_AGENT=gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - Observações: - - Essa lane usa a superfície `chat.send` do Gateway com campos sintéticos de rota de origem somente para admin, para que os testes possam anexar contexto de canal de mensagem sem fingir entrega externa. + - Essa faixa usa a superfície `chat.send` do Gateway com campos sintéticos de rota de origem apenas para admin para que os testes possam anexar contexto de canal de mensagem sem fingir entrega externa. - Quando `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` não está definido, o teste usa o registro de agentes embutido do Plugin `acpx` selecionado para o agente de harness ACP. Exemplo: @@ -552,7 +555,7 @@ Receita Docker: pnpm test:docker:live-acp-bind ``` -Receitas Docker de agente único: +Receitas Docker para agente único: ```bash pnpm test:docker:live-acp-bind:claude @@ -562,17 +565,17 @@ pnpm test:docker:live-acp-bind:gemini Observações sobre Docker: -- O runner Docker fica em `scripts/test-live-acp-bind-docker.sh`. -- Por padrão, ele executa o smoke de bind ACP contra todos os agentes CLI live suportados em sequência: `claude`, `codex`, depois `gemini`. +- O executor Docker fica em `scripts/test-live-acp-bind-docker.sh`. +- Por padrão, ele executa o smoke de bind do ACP contra todos os agentes CLI live suportados em sequência: `claude`, `codex` e depois `gemini`. - Use `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` ou `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` para restringir a matriz. -- Ele carrega `~/.profile`, prepara no container o material de autenticação CLI correspondente, instala `acpx` em um prefixo npm gravável e depois instala o CLI live solicitado (`@anthropic-ai/claude-code`, `@openai/codex` ou `@google/gemini-cli`) se estiver ausente. -- Dentro do Docker, o runner define `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` para que o acpx mantenha disponíveis para o CLI filho do harness as variáveis de ambiente do provedor carregadas do profile. +- Ele obtém `~/.profile`, prepara no container o material de autenticação CLI correspondente, instala `acpx` em um prefixo npm gravável e depois instala a CLI live solicitada (`@anthropic-ai/claude-code`, `@openai/codex` ou `@google/gemini-cli`) se estiver ausente. +- Dentro do Docker, o executor define `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` para que o acpx mantenha disponíveis para a CLI filha do harness as variáveis de ambiente de provedor vindas do profile obtido. ## Live: smoke do harness app-server do Codex -- Objetivo: validar o harness do Codex pertencente ao Plugin pelo método +- Objetivo: validar o harness do Codex pertencente ao Plugin por meio do método `agent` normal do Gateway: - - carregar o Plugin `codex` empacotado + - carregar o Plugin empacotado `codex` - selecionar `OPENCLAW_AGENT_RUNTIME=codex` - enviar um primeiro turno de agente do Gateway para `codex/gpt-5.4` - enviar um segundo turno para a mesma sessão do OpenClaw e verificar que a thread @@ -582,11 +585,11 @@ Observações sobre Docker: - Teste: `src/gateway/gateway-codex-harness.live.test.ts` - Habilitar: `OPENCLAW_LIVE_CODEX_HARNESS=1` - Modelo padrão: `codex/gpt-5.4` -- Sonda opcional de imagem: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` -- Sonda opcional de MCP/tool: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` -- O smoke define `OPENCLAW_AGENT_HARNESS_FALLBACK=none` para que um harness do Codex quebrado - não passe silenciosamente por fallback para PI. -- Autenticação: `OPENAI_API_KEY` do shell/profile, mais opcionais +- Probe opcional de imagem: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` +- Probe opcional de MCP/ferramenta: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` +- O smoke define `OPENCLAW_AGENT_HARNESS_FALLBACK=none` para que um harness + do Codex quebrado não passe ao cair silenciosamente de volta para o PI. +- Auth: `OPENAI_API_KEY` do shell/profile, além de opcionais `~/.codex/auth.json` e `~/.codex/config.toml` copiados Receita local: @@ -609,16 +612,16 @@ pnpm test:docker:live-codex-harness Observações sobre Docker: -- O runner Docker fica em `scripts/test-live-codex-harness-docker.sh`. -- Ele carrega o `~/.profile` montado, passa `OPENAI_API_KEY`, copia arquivos de autenticação - do CLI Codex quando presentes, instala `@openai/codex` em um prefixo npm - gravável montado, prepara a árvore de origem e então executa apenas o teste live do harness do Codex. -- O Docker habilita por padrão as sondas de imagem e de MCP/tool. Defina +- O executor Docker fica em `scripts/test-live-codex-harness-docker.sh`. +- Ele obtém o `~/.profile` montado, passa `OPENAI_API_KEY`, copia arquivos de auth + da CLI do Codex quando presentes, instala `@openai/codex` em um prefixo npm + montado e gravável, prepara a árvore de código-fonte e então executa apenas o teste live do harness do Codex. +- O Docker habilita por padrão os probes de imagem e MCP/ferramenta. Defina `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` ou `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` quando precisar de uma execução de depuração mais restrita. -- O Docker também exporta `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, alinhado com a configuração - do teste live, para que fallback de `openai-codex/*` ou PI não esconda uma regressão - do harness do Codex. +- O Docker também exporta `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, correspondendo à + configuração do teste live para que fallback de `openai-codex/*` ou PI não possa ocultar uma + regressão do harness do Codex. ### Receitas live recomendadas @@ -640,19 +643,19 @@ Allowlists restritas e explícitas são mais rápidas e menos instáveis: Observações: - `google/...` usa a API Gemini (chave de API). -- `google-antigravity/...` usa a bridge OAuth do Antigravity (endpoint de agente no estilo Cloud Code Assist). -- `google-gemini-cli/...` usa o CLI Gemini local na sua máquina (autenticação separada + peculiaridades de ferramentas). +- `google-antigravity/...` usa a ponte OAuth Antigravity (endpoint de agente em estilo Cloud Code Assist). +- `google-gemini-cli/...` usa a CLI Gemini local na sua máquina (auth separada + peculiaridades próprias de tooling). - API Gemini vs CLI Gemini: - - API: o OpenClaw chama a API Gemini hospedada pelo Google via HTTP (chave de API / autenticação de perfil); é isso que a maioria dos usuários quer dizer com “Gemini”. - - CLI: o OpenClaw executa um binário local `gemini`; ele tem sua própria autenticação e pode se comportar de forma diferente (streaming/suporte a ferramentas/desvio de versão). + - API: o OpenClaw chama a API Gemini hospedada do Google por HTTP (auth por chave de API / perfil); é isso que a maioria dos usuários quer dizer com “Gemini”. + - CLI: o OpenClaw faz shell out para um binário local `gemini`; ele tem auth própria e pode se comportar de forma diferente (streaming/suporte a ferramentas/defasagem de versão). ## Live: matriz de modelos (o que cobrimos) -Não há uma “lista fixa de modelos no CI” (live é opt-in), mas estes são os modelos **recomendados** para cobrir regularmente em uma máquina de desenvolvimento com chaves. +Não existe uma “lista fixa de modelos no CI” (live é opt-in), mas estes são os modelos **recomendados** para cobrir regularmente em uma máquina de desenvolvimento com chaves. -### Conjunto smoke moderno (chamada de ferramenta + imagem) +### Conjunto de smoke moderno (chamada de ferramenta + imagem) -Esta é a execução de “modelos comuns” que esperamos manter funcionando: +Esta é a execução de “modelos comuns” que esperamos continuar funcionando: - OpenAI (não-Codex): `openai/gpt-5.4` (opcional: `openai/gpt-5.4-mini`) - OpenAI Codex: `openai-codex/gpt-5.4` @@ -684,67 +687,67 @@ Cobertura adicional opcional (bom ter): ### Vision: envio de imagem (anexo → mensagem multimodal) -Inclua pelo menos um modelo com capacidade de imagem em `OPENCLAW_LIVE_GATEWAY_MODELS` (variantes com suporte a visão do Claude/Gemini/OpenAI etc.) para exercitar a sonda de imagem. +Inclua pelo menos um modelo com capacidade de imagem em `OPENCLAW_LIVE_GATEWAY_MODELS` (variantes com suporte a vision do Claude/Gemini/OpenAI etc.) para exercitar o probe de imagem. ### Agregadores / gateways alternativos Se você tiver chaves habilitadas, também oferecemos suporte a testes via: -- OpenRouter: `openrouter/...` (centenas de modelos; use `openclaw models scan` para encontrar candidatos com capacidade de ferramentas+imagem) -- OpenCode: `opencode/...` para Zen e `opencode-go/...` para Go (autenticação via `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) +- OpenRouter: `openrouter/...` (centenas de modelos; use `openclaw models scan` para encontrar candidatos com capacidade de ferramenta+imagem) +- OpenCode: `opencode/...` para Zen e `opencode-go/...` para Go (auth via `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Mais provedores que você pode incluir na matriz live (se tiver credenciais/config): +Mais provedores que você pode incluir na matriz live (se tiver creds/config): -- Integrados: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` -- Via `models.providers` (endpoints personalizados): `minimax` (cloud/API), mais qualquer proxy compatível com OpenAI/Anthropic (LM Studio, vLLM, LiteLLM etc.) +- Embutidos: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` +- Via `models.providers` (endpoints personalizados): `minimax` (nuvem/API), além de qualquer proxy compatível com OpenAI/Anthropic (LM Studio, vLLM, LiteLLM etc.) -Dica: não tente codificar “todos os modelos” na documentação. A lista autoritativa é o que `discoverModels(...)` retorna na sua máquina + as chaves disponíveis. +Dica: não tente fixar “todos os modelos” na documentação. A lista autoritativa é tudo o que `discoverModels(...)` retorna na sua máquina + todas as chaves disponíveis. ## Credenciais (nunca faça commit) -Os testes live descobrem credenciais da mesma forma que o CLI. Implicações práticas: +Os testes live descobrem credenciais da mesma forma que a CLI. Implicações práticas: -- Se o CLI funciona, os testes live devem encontrar as mesmas chaves. +- Se a CLI funciona, os testes live devem encontrar as mesmas chaves. - Se um teste live disser “sem credenciais”, depure da mesma forma que você depuraria `openclaw models list` / seleção de modelo. -- Perfis de autenticação por agente: `~/.openclaw/agents//agent/auth-profiles.json` (é isso que “chaves de perfil” significa nos testes live) +- Perfis de auth por agente: `~/.openclaw/agents//agent/auth-profiles.json` (é isso que “chaves de perfil” significa nos testes live) - Config: `~/.openclaw/openclaw.json` (ou `OPENCLAW_CONFIG_PATH`) -- Diretório de estado legado: `~/.openclaw/credentials/` (copiado para a home live preparada quando presente, mas não para o armazenamento principal de chaves de perfil) -- Execuções live locais copiam por padrão a config ativa, arquivos `auth-profiles.json` por agente, `credentials/` legadas e diretórios de autenticação de CLI externos compatíveis para uma home temporária de teste; homes live preparadas ignoram `workspace/` e `sandboxes/`, e overrides de caminho `agents.*.workspace` / `agentDir` são removidos para que as sondas fiquem fora do seu workspace real do host. +- Diretório de estado legado: `~/.openclaw/credentials/` (copiado para o home live preparado quando presente, mas não é o armazenamento principal de chaves de perfil) +- Execuções live locais copiam por padrão a config ativa, arquivos `auth-profiles.json` por agente, `credentials/` legada e diretórios de auth de CLI externos compatíveis para um home temporário de teste; homes live preparados ignoram `workspace/` e `sandboxes/`, e substituições de caminho `agents.*.workspace` / `agentDir` são removidas para que os probes fiquem fora do seu workspace real do host. -Se você quiser depender de chaves de env (por exemplo, exportadas no seu `~/.profile`), execute testes locais após `source ~/.profile`, ou use os runners Docker abaixo (eles podem montar `~/.profile` no container). +Se você quiser depender de chaves por env (por exemplo, exportadas no seu `~/.profile`), execute testes locais após `source ~/.profile`, ou use os executores Docker abaixo (eles podem montar `~/.profile` dentro do container). -## Deepgram live (transcrição de áudio) +## Live do Deepgram (transcrição de áudio) - Teste: `src/media-understanding/providers/deepgram/audio.live.test.ts` - Habilitar: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts` -## BytePlus coding plan live +## Live do plano de código BytePlus - Teste: `src/agents/byteplus.live.test.ts` - Habilitar: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts` -- Override opcional de modelo: `BYTEPLUS_CODING_MODEL=ark-code-latest` +- Substituição opcional de modelo: `BYTEPLUS_CODING_MODEL=ark-code-latest` -## ComfyUI workflow media live +## Live de mídia de fluxo de trabalho ComfyUI - Teste: `extensions/comfy/comfy.live.test.ts` - Habilitar: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - Escopo: - - Exercita os caminhos empacotados do comfy para imagem, vídeo e `music_generate` + - Exercita os caminhos empacotados de imagem, vídeo e `music_generate` do comfy - Ignora cada capacidade a menos que `models.providers.comfy.` esteja configurado - Útil após mudar envio de workflow do comfy, polling, downloads ou registro de Plugin -## Geração de imagens live +## Live de geração de imagem - Teste: `src/image-generation/runtime.live.test.ts` - Comando: `pnpm test:live src/image-generation/runtime.live.test.ts` - Harness: `pnpm test:live:media image` - Escopo: - - Enumera todos os Plugins de provedor de geração de imagens registrados - - Carrega variáveis de ambiente de provedor ausentes do seu shell de login (`~/.profile`) antes de sondar - - Usa por padrão chaves de API live/env antes de perfis de autenticação armazenados, para que chaves de teste obsoletas em `auth-profiles.json` não mascarem credenciais reais do shell - - Ignora provedores sem autenticação/perfil/modelo utilizáveis - - Executa as variantes padrão de geração de imagens pela capacidade de runtime compartilhada: + - Enumera todos os Plugins de provedor de geração de imagem registrados + - Carrega variáveis de ambiente de provedor ausentes a partir do seu shell de login (`~/.profile`) antes dos probes + - Usa por padrão chaves de API live/env antes de perfis de auth armazenados, para que chaves de teste antigas em `auth-profiles.json` não ocultem credenciais reais do shell + - Ignora provedores sem auth/perfil/modelo utilizável + - Executa as variantes padrão de geração de imagem pela capacidade compartilhada de runtime: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` @@ -752,79 +755,79 @@ Se você quiser depender de chaves de env (por exemplo, exportadas no seu `~/.pr - Provedores empacotados atualmente cobertos: - `openai` - `google` -- Restrições opcionais: +- Restrição opcional: - `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google"` - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"` -- Comportamento opcional de autenticação: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forçar autenticação do armazenamento de perfis e ignorar overrides somente de env +- Comportamento opcional de auth: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forçar auth pelo armazenamento de perfis e ignorar substituições apenas por env -## Geração de música live +## Live de geração de música - Teste: `extensions/music-generation-providers.live.test.ts` - Habilitar: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` - Harness: `pnpm test:live:media music` - Escopo: - - Exercita o caminho compartilhado de provedor empacotado de geração de música + - Exercita o caminho compartilhado empacotado de provedor de geração de música - Atualmente cobre Google e MiniMax - - Carrega variáveis de ambiente de provedor do seu shell de login (`~/.profile`) antes de sondar - - Usa por padrão chaves de API live/env antes de perfis de autenticação armazenados, para que chaves de teste obsoletas em `auth-profiles.json` não mascarem credenciais reais do shell - - Ignora provedores sem autenticação/perfil/modelo utilizáveis + - Carrega variáveis de ambiente de provedor a partir do seu shell de login (`~/.profile`) antes dos probes + - Usa por padrão chaves de API live/env antes de perfis de auth armazenados, para que chaves de teste antigas em `auth-profiles.json` não ocultem credenciais reais do shell + - Ignora provedores sem auth/perfil/modelo utilizável - Executa ambos os modos de runtime declarados quando disponíveis: - `generate` com entrada apenas de prompt - `edit` quando o provedor declara `capabilities.edit.enabled` - - Cobertura atual da lane compartilhada: + - Cobertura atual da faixa compartilhada: - `google`: `generate`, `edit` - `minimax`: `generate` - - `comfy`: arquivo live do Comfy separado, não esta varredura compartilhada -- Restrições opcionais: + - `comfy`: arquivo live separado do Comfy, não esta varredura compartilhada +- Restrição opcional: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` -- Comportamento opcional de autenticação: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forçar autenticação do armazenamento de perfis e ignorar overrides somente de env +- Comportamento opcional de auth: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forçar auth pelo armazenamento de perfis e ignorar substituições apenas por env -## Geração de vídeo live +## Live de geração de vídeo - Teste: `extensions/video-generation-providers.live.test.ts` - Habilitar: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` - Harness: `pnpm test:live:media video` - Escopo: - - Exercita o caminho compartilhado de provedor empacotado de geração de vídeo - - Usa por padrão o caminho smoke seguro para release: provedores não FAL, uma requisição text-to-video por provedor, prompt lobster de um segundo e um limite de operação por provedor vindo de `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` por padrão) - - Ignora FAL por padrão porque a latência de fila do lado do provedor pode dominar o tempo de release; passe `--video-providers fal` ou `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` para executá-lo explicitamente - - Carrega variáveis de ambiente de provedor do seu shell de login (`~/.profile`) antes de sondar - - Usa por padrão chaves de API live/env antes de perfis de autenticação armazenados, para que chaves de teste obsoletas em `auth-profiles.json` não mascarem credenciais reais do shell - - Ignora provedores sem autenticação/perfil/modelo utilizáveis + - Exercita o caminho compartilhado empacotado de provedor de geração de vídeo + - Usa por padrão o caminho de smoke seguro para release: provedores não-FAL, uma requisição text-to-video por provedor, prompt lobster de um segundo e um limite de operação por provedor vindo de `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` por padrão) + - Ignora FAL por padrão porque a latência da fila do lado do provedor pode dominar o tempo de release; passe `--video-providers fal` ou `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` para executá-lo explicitamente + - Carrega variáveis de ambiente de provedor a partir do seu shell de login (`~/.profile`) antes dos probes + - Usa por padrão chaves de API live/env antes de perfis de auth armazenados, para que chaves de teste antigas em `auth-profiles.json` não ocultem credenciais reais do shell + - Ignora provedores sem auth/perfil/modelo utilizável - Executa apenas `generate` por padrão - Defina `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` para também executar modos de transformação declarados quando disponíveis: - - `imageToVideo` quando o provedor declara `capabilities.imageToVideo.enabled` e o provedor/modelo selecionado aceita entrada de imagem local baseada em buffer na varredura compartilhada - - `videoToVideo` quando o provedor declara `capabilities.videoToVideo.enabled` e o provedor/modelo selecionado aceita entrada de vídeo local baseada em buffer na varredura compartilhada - - Provedores `imageToVideo` atualmente declarados, mas ignorados, na varredura compartilhada: - - `vydra` porque o `veo3` empacotado é somente texto e o `kling` empacotado exige uma URL remota de imagem - - Cobertura específica de provedor para Vydra: + - `imageToVideo` quando o provedor declara `capabilities.imageToVideo.enabled` e o provedor/modelo selecionado aceita entrada local de imagem com suporte de buffer na varredura compartilhada + - `videoToVideo` quando o provedor declara `capabilities.videoToVideo.enabled` e o provedor/modelo selecionado aceita entrada local de vídeo com suporte de buffer na varredura compartilhada + - Provedores `imageToVideo` atualmente declarados mas ignorados na varredura compartilhada: + - `vydra` porque o `veo3` empacotado é apenas texto e o `kling` empacotado exige uma URL remota de imagem + - Cobertura específica de provedor Vydra: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - esse arquivo executa `veo3` text-to-video mais uma lane `kling` que usa por padrão uma fixture de URL remota de imagem + - esse arquivo executa `veo3` text-to-video mais uma faixa `kling` que usa por padrão uma fixture de URL remota de imagem - Cobertura live atual de `videoToVideo`: - apenas `runway` quando o modelo selecionado é `runway/gen4_aleph` - - Provedores `videoToVideo` atualmente declarados, mas ignorados, na varredura compartilhada: + - Provedores `videoToVideo` atualmente declarados mas ignorados na varredura compartilhada: - `alibaba`, `qwen`, `xai` porque esses caminhos atualmente exigem URLs de referência remotas `http(s)` / MP4 - - `google` porque a lane compartilhada atual de Gemini/Veo usa entrada local baseada em buffer e esse caminho não é aceito na varredura compartilhada - - `openai` porque a lane compartilhada atual não garante acesso específico por organização a inpaint/remix de vídeo -- Restrições opcionais: + - `google` porque a faixa compartilhada atual Gemini/Veo usa entrada local com suporte de buffer e esse caminho não é aceito na varredura compartilhada + - `openai` porque a faixa compartilhada atual não tem garantias de acesso específico de organização para inpaint/remix de vídeo +- Restrição opcional: - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` para incluir todos os provedores na varredura padrão, incluindo FAL - - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` para reduzir o limite de operação de cada provedor em uma execução smoke agressiva -- Comportamento opcional de autenticação: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forçar autenticação do armazenamento de perfis e ignorar overrides somente de env + - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` para reduzir o limite de operação de cada provedor em uma execução de smoke agressiva +- Comportamento opcional de auth: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forçar auth pelo armazenamento de perfis e ignorar substituições apenas por env ## Harness live de mídia - Comando: `pnpm test:live:media` - Objetivo: - Executa as suítes live compartilhadas de imagem, música e vídeo por um único entrypoint nativo do repositório - - Carrega automaticamente variáveis de ambiente de provedor ausentes de `~/.profile` - - Restringe automaticamente cada suíte, por padrão, aos provedores que atualmente têm autenticação utilizável + - Carrega automaticamente variáveis de ambiente de provedor ausentes a partir de `~/.profile` + - Restringe automaticamente cada suíte por padrão aos provedores que atualmente têm auth utilizável - Reutiliza `scripts/test-live.mjs`, para que o comportamento de Heartbeat e modo silencioso permaneça consistente - Exemplos: - `pnpm test:live:media` @@ -832,127 +835,127 @@ Se você quiser depender de chaves de env (por exemplo, exportadas no seu `~/.pr - `pnpm test:live:media video --video-providers openai,runway --all-providers` - `pnpm test:live:media music --quiet` -## Runners Docker (verificações opcionais de “funciona no Linux”) +## Executores Docker (verificações opcionais de "funciona em Linux") -Esses runners Docker se dividem em dois grupos: +Esses executores Docker se dividem em dois grupos: -- Runners live de modelos: `test:docker:live-models` e `test:docker:live-gateway` executam apenas o arquivo live correspondente de chaves de perfil dentro da imagem Docker do repositório (`src/agents/models.profiles.live.test.ts` e `src/gateway/gateway-models.profiles.live.test.ts`), montando seu diretório de config e workspace locais (e carregando `~/.profile` se estiver montado). Os entrypoints locais correspondentes são `test:live:models-profiles` e `test:live:gateway-profiles`. -- Os runners live de Docker usam por padrão um limite smoke menor para que uma varredura Docker completa continue prática: +- Executores live-model: `test:docker:live-models` e `test:docker:live-gateway` executam apenas seu arquivo live correspondente de chaves de perfil dentro da imagem Docker do repositório (`src/agents/models.profiles.live.test.ts` e `src/gateway/gateway-models.profiles.live.test.ts`), montando seu diretório local de config e workspace (e obtendo `~/.profile` se ele estiver montado). Os entrypoints locais correspondentes são `test:live:models-profiles` e `test:live:gateway-profiles`. +- Os executores live do Docker usam por padrão um limite menor de smoke para que uma varredura Docker completa continue prática: `test:docker:live-models` usa por padrão `OPENCLAW_LIVE_MAX_MODELS=12`, e `test:docker:live-gateway` usa por padrão `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` e `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Substitua essas variáveis de ambiente quando quiser explicitamente a varredura exaustiva maior. -- `test:docker:all` constrói a imagem Docker live uma vez por meio de `test:docker:live-build`, depois a reutiliza para as duas lanes Docker live. -- Runners smoke em container: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` e `test:docker:plugins` inicializam um ou mais containers reais e verificam caminhos de integração de nível mais alto. +- `test:docker:all` constrói a imagem Docker live uma vez via `test:docker:live-build` e depois a reutiliza para as duas faixas Docker live. +- Executores de smoke em container: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` e `test:docker:plugins` inicializam um ou mais containers reais e verificam caminhos de integração de nível mais alto. -Os runners Docker live de modelos também fazem bind-mount apenas das homes de autenticação de CLI necessárias (ou de todas as suportadas quando a execução não está restrita), depois as copiam para a home do container antes da execução para que o OAuth de CLI externo possa atualizar tokens sem alterar o armazenamento de autenticação do host: +Os executores Docker de live-model também fazem bind-mount apenas dos homes de auth de CLI necessários (ou de todos os compatíveis quando a execução não está restringida), depois os copiam para o home do container antes da execução para que OAuth de CLI externa possa atualizar tokens sem alterar o armazenamento de auth do host: - Modelos diretos: `pnpm test:docker:live-models` (script: `scripts/test-live-models-docker.sh`) -- Smoke de bind de ACP: `pnpm test:docker:live-acp-bind` (script: `scripts/test-live-acp-bind-docker.sh`) +- Smoke de bind do ACP: `pnpm test:docker:live-acp-bind` (script: `scripts/test-live-acp-bind-docker.sh`) - Smoke de backend CLI: `pnpm test:docker:live-cli-backend` (script: `scripts/test-live-cli-backend-docker.sh`) - Smoke do harness app-server do Codex: `pnpm test:docker:live-codex-harness` (script: `scripts/test-live-codex-harness-docker.sh`) - Gateway + agente dev: `pnpm test:docker:live-gateway` (script: `scripts/test-live-gateway-models-docker.sh`) - Smoke live do Open WebUI: `pnpm test:docker:openwebui` (script: `scripts/e2e/openwebui-docker.sh`) - Assistente de onboarding (TTY, scaffolding completo): `pnpm test:docker:onboard` (script: `scripts/e2e/onboard-docker.sh`) -- Networking do Gateway (dois containers, autenticação WS + health): `pnpm test:docker:gateway-network` (script: `scripts/e2e/gateway-network-docker.sh`) -- Bridge de canal MCP (Gateway semeado + bridge stdio + smoke bruto de frame de notificação Claude): `pnpm test:docker:mcp-channels` (script: `scripts/e2e/mcp-channels-docker.sh`) +- Rede do Gateway (dois containers, auth WS + health): `pnpm test:docker:gateway-network` (script: `scripts/e2e/gateway-network-docker.sh`) +- Ponte de canal MCP (Gateway semeado + ponte stdio + smoke bruto de frame de notificação do Claude): `pnpm test:docker:mcp-channels` (script: `scripts/e2e/mcp-channels-docker.sh`) - Plugins (smoke de instalação + alias `/plugin` + semântica de reinício do bundle Claude): `pnpm test:docker:plugins` (script: `scripts/e2e/plugins-docker.sh`) -Os runners Docker live de modelos também fazem bind-mount do checkout atual como somente leitura e +Os executores Docker de live-model também fazem bind-mount do checkout atual como somente leitura e o preparam em um workdir temporário dentro do container. Isso mantém a imagem de runtime -enxuta enquanto ainda executa o Vitest sobre seu código-fonte/config local exato. +enxuta, mas ainda executa Vitest exatamente contra seu código-fonte/config local. A etapa de preparação ignora grandes caches apenas locais e saídas de build de apps, como -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` e diretórios locais de `.build` de app ou -saída do Gradle, para que execuções Docker live não gastem minutos copiando +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` e diretórios locais de `.build` do app ou +saídas do Gradle, para que execuções live no Docker não gastem minutos copiando artefatos específicos da máquina. -Eles também definem `OPENCLAW_SKIP_CHANNELS=1` para que as sondas live do Gateway não iniciem -workers reais de canal de Telegram/Discord/etc. dentro do container. -`test:docker:live-models` ainda executa `pnpm test:live`, então repasse também -`OPENCLAW_LIVE_GATEWAY_*` quando precisar restringir ou excluir cobertura live do Gateway dessa lane Docker. +Eles também definem `OPENCLAW_SKIP_CHANNELS=1` para que probes live do Gateway não iniciem +workers reais de canais Telegram/Discord/etc. dentro do container. +`test:docker:live-models` ainda executa `pnpm test:live`, então repasse +`OPENCLAW_LIVE_GATEWAY_*` também quando precisar restringir ou excluir cobertura live do Gateway dessa faixa Docker. `test:docker:openwebui` é um smoke de compatibilidade de nível mais alto: ele inicia um -container do Gateway OpenClaw com os endpoints HTTP compatíveis com OpenAI habilitados, -inicia um container Open WebUI fixado contra esse Gateway, faz login via -Open WebUI, verifica se `/api/models` expõe `openclaw/default`, depois envia uma -requisição real de chat por meio do proxy `/api/chat/completions` do Open WebUI. -A primeira execução pode ser perceptivelmente mais lenta porque o Docker pode precisar baixar a -imagem do Open WebUI e o Open WebUI pode precisar concluir sua própria configuração de cold-start. -Essa lane espera uma chave de modelo live utilizável, e `OPENCLAW_PROFILE_FILE` -(`~/.profile` por padrão) é a principal forma de fornecê-la em execuções Dockerizadas. +container Gateway do OpenClaw com endpoints HTTP compatíveis com OpenAI habilitados, +inicia um container Open WebUI fixado contra esse Gateway, faz login pelo +Open WebUI, verifica se `/api/models` expõe `openclaw/default` e então envia uma +requisição de chat real pelo proxy `/api/chat/completions` do Open WebUI. +A primeira execução pode ser visivelmente mais lenta porque o Docker pode precisar baixar a +imagem do Open WebUI e o Open WebUI pode precisar concluir seu próprio setup de cold start. +Essa faixa espera uma chave de modelo live utilizável, e `OPENCLAW_PROFILE_FILE` +(`~/.profile` por padrão) é a forma principal de fornecê-la em execuções Dockerizadas. Execuções bem-sucedidas imprimem um pequeno payload JSON como `{ "ok": true, "model": "openclaw/default", ... }`. `test:docker:mcp-channels` é intencionalmente determinístico e não precisa de uma -conta real de Telegram, Discord ou iMessage. Ele inicializa um container de Gateway -semeado, inicia um segundo container que executa `openclaw mcp serve`, então -verifica descoberta de conversas roteadas, leituras de transcrição, metadados de anexo, -comportamento de fila de eventos live, roteamento de envio de saída e notificações -de canal + permissão no estilo Claude pela bridge MCP stdio real. A verificação de notificação +conta real de Telegram, Discord ou iMessage. Ele inicializa um container +Gateway semeado, inicia um segundo container que executa `openclaw mcp serve` e então +verifica descoberta de conversa roteada, leituras de transcrição, metadados de anexos, +comportamento da fila de eventos live, roteamento de envio de saída e notificações +de canal + permissão em estilo Claude pela ponte MCP stdio real. A verificação de notificação inspeciona diretamente os frames MCP stdio brutos, para que o smoke valide o que a -bridge realmente emite, e não apenas o que um SDK específico de cliente por acaso expõe. +ponte realmente emite, não apenas o que um SDK cliente específico por acaso expõe. -Smoke manual de thread em linguagem natural para ACP (não CI): +Smoke manual de thread ACP em linguagem simples (não CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Mantenha este script para fluxos de regressão/depuração. Ele pode ser necessário novamente para validação de roteamento de thread ACP, então não o remova. +- Mantenha este script para fluxos de regressão/depuração. Ele pode ser necessário novamente para validação de roteamento de thread ACP, então não o exclua. Variáveis de ambiente úteis: - `OPENCLAW_CONFIG_DIR=...` (padrão: `~/.openclaw`) montado em `/home/node/.openclaw` - `OPENCLAW_WORKSPACE_DIR=...` (padrão: `~/.openclaw/workspace`) montado em `/home/node/.openclaw/workspace` -- `OPENCLAW_PROFILE_FILE=...` (padrão: `~/.profile`) montado em `/home/node/.profile` e carregado antes de executar os testes -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` para validar apenas variáveis de ambiente carregadas de `OPENCLAW_PROFILE_FILE`, usando diretórios temporários de config/workspace e sem mounts externos de autenticação de CLI -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (padrão: `~/.cache/openclaw/docker-cli-tools`) montado em `/home/node/.npm-global` para instalações de CLI com cache dentro do Docker -- Diretórios/arquivos externos de autenticação de CLI em `$HOME` são montados como somente leitura sob `/host-auth...`, depois copiados para `/home/node/...` antes do início dos testes +- `OPENCLAW_PROFILE_FILE=...` (padrão: `~/.profile`) montado em `/home/node/.profile` e obtido antes de executar os testes +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` para validar apenas variáveis de ambiente obtidas de `OPENCLAW_PROFILE_FILE`, usando diretórios temporários de config/workspace e sem mounts externos de auth de CLI +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (padrão: `~/.cache/openclaw/docker-cli-tools`) montado em `/home/node/.npm-global` para instalações em cache de CLI dentro do Docker +- Diretórios/arquivos de auth de CLI externos sob `$HOME` são montados como somente leitura sob `/host-auth...`, depois copiados para `/home/node/...` antes do início dos testes - Diretórios padrão: `.minimax` - Arquivos padrão: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - Execuções restritas por provedor montam apenas os diretórios/arquivos necessários inferidos de `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - - Faça override manual com `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` ou uma lista separada por vírgulas como `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` + - Substitua manualmente com `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` ou uma lista separada por vírgulas como `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` - `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` para restringir a execução - `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` para filtrar provedores dentro do container - `OPENCLAW_SKIP_DOCKER_BUILD=1` para reutilizar uma imagem `openclaw:local-live` existente em reexecuções que não precisam de rebuild -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para garantir que as credenciais venham do armazenamento de perfis (e não do env) +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para garantir que as credenciais venham do armazenamento de perfis (não de env) - `OPENCLAW_OPENWEBUI_MODEL=...` para escolher o modelo exposto pelo Gateway para o smoke do Open WebUI -- `OPENCLAW_OPENWEBUI_PROMPT=...` para substituir o prompt de verificação por nonce usado pelo smoke do Open WebUI -- `OPENWEBUI_IMAGE=...` para substituir a tag de imagem fixada do Open WebUI +- `OPENCLAW_OPENWEBUI_PROMPT=...` para substituir o prompt de verificação de nonce usado pelo smoke do Open WebUI +- `OPENWEBUI_IMAGE=...` para substituir a tag fixada da imagem Open WebUI ## Sanidade da documentação -Execute verificações de docs após editar a documentação: `pnpm check:docs`. -Execute a validação completa de âncoras do Mintlify quando também precisar verificar títulos na página: `pnpm docs:check-links:anchors`. +Execute verificações da documentação após edições em docs: `pnpm check:docs`. +Execute a validação completa de âncoras do Mintlify quando precisar de verificações de headings na página também: `pnpm docs:check-links:anchors`. ## Regressão offline (segura para CI) Estas são regressões de “pipeline real” sem provedores reais: -- Chamada de ferramenta do Gateway (OpenAI simulado, Gateway real + loop de agente): `src/gateway/gateway.test.ts` (caso: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Assistente do Gateway (WS `wizard.start`/`wizard.next`, grava config + auth aplicado): `src/gateway/gateway.test.ts` (caso: "runs wizard over ws and writes auth token config") +- Chamada de ferramenta do Gateway (mock OpenAI, Gateway real + loop de agente): `src/gateway/gateway.test.ts` (caso: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Assistente do Gateway (WS `wizard.start`/`wizard.next`, gravação forçada de config + auth): `src/gateway/gateway.test.ts` (caso: "runs wizard over ws and writes auth token config") -## Avaliações de confiabilidade de agente (Skills) +## Avaliações de confiabilidade do agente (Skills) -Já temos alguns testes seguros para CI que se comportam como “avaliações de confiabilidade de agente”: +Já temos alguns testes seguros para CI que se comportam como “avaliações de confiabilidade do agente”: -- Chamada de ferramenta simulada pelo loop real de Gateway + agente (`src/gateway/gateway.test.ts`). -- Fluxos end-to-end de assistente que validam wiring de sessão e efeitos de config (`src/gateway/gateway.test.ts`). +- Mock de chamada de ferramenta pelo loop real de Gateway + agente (`src/gateway/gateway.test.ts`). +- Fluxos end-to-end do assistente que validam fiação de sessão e efeitos de config (`src/gateway/gateway.test.ts`). -O que ainda está faltando para Skills (veja [Skills](/pt-BR/tools/skills)): +O que ainda falta para Skills (consulte [Skills](/pt-BR/tools/skills)): - **Tomada de decisão:** quando Skills são listadas no prompt, o agente escolhe a Skill correta (ou evita as irrelevantes)? -- **Conformidade:** o agente lê `SKILL.md` antes do uso e segue as etapas/args exigidos? -- **Contratos de fluxo:** cenários multi-turno que validem ordem de ferramentas, carregamento do histórico da sessão e limites do sandbox. +- **Conformidade:** o agente lê `SKILL.md` antes do uso e segue as etapas/args obrigatórios? +- **Contratos de fluxo de trabalho:** cenários multi-turn que validam ordem de ferramentas, carryover do histórico da sessão e limites do sandbox. -Avaliações futuras devem continuar determinísticas primeiro: +Avaliações futuras devem permanecer determinísticas primeiro: -- Um runner de cenários usando provedores simulados para validar chamadas de ferramenta + ordem, leituras de arquivo de Skill e wiring de sessão. -- Um pequeno conjunto de cenários focados em Skills (usar vs evitar, gating, injeção de prompt). -- Avaliações live opcionais (opt-in, protegidas por env) somente depois que a suíte segura para CI estiver pronta. +- Um executor de cenários usando provedores mock para validar chamadas de ferramenta + ordem, leituras de arquivo de Skill e fiação de sessão. +- Uma pequena suíte de cenários focados em Skills (usar vs evitar, gating, injeção de prompt). +- Avaliações live opcionais (opt-in, controladas por env) somente depois que a suíte segura para CI estiver pronta. -## Testes de contrato (forma de Plugin e canal) +## Testes de contrato (formato de Plugin e canal) -Os testes de contrato verificam se todo Plugin e canal registrado está em conformidade com seu -contrato de interface. Eles iteram por todos os Plugins descobertos e executam uma suíte de -validações de forma e comportamento. A lane unit padrão de `pnpm test` intencionalmente -ignora esses arquivos compartilhados de seam e smoke; execute os comandos de contrato explicitamente +Os testes de contrato verificam que todo Plugin e canal registrado está em conformidade com seu +contrato de interface. Eles iteram sobre todos os Plugins descobertos e executam um conjunto de +validações de formato e comportamento. A faixa unitária padrão de `pnpm test` +intencionalmente ignora esses arquivos compartilhados de seam e smoke; execute os comandos de contrato explicitamente quando tocar em superfícies compartilhadas de canal ou provedor. ### Comandos @@ -965,53 +968,53 @@ quando tocar em superfícies compartilhadas de canal ou provedor. Localizados em `src/channels/plugins/contracts/*.contract.test.ts`: -- **plugin** - Forma básica do Plugin (id, nome, capacidades) -- **setup** - Contrato do assistente de configuração -- **session-binding** - Comportamento de binding de sessão +- **plugin** - Formato básico do Plugin (id, nome, capacidades) +- **setup** - Contrato do assistente de setup +- **session-binding** - Comportamento de vinculação de sessão - **outbound-payload** - Estrutura do payload de mensagem -- **inbound** - Tratamento de mensagem de entrada -- **actions** - Handlers de ação de canal -- **threading** - Tratamento de ID de thread +- **inbound** - Manipulação de mensagem de entrada +- **actions** - Handlers de ação do canal +- **threading** - Manipulação de ID de thread - **directory** - API de diretório/lista - **group-policy** - Aplicação de política de grupo -### Contratos de status de provedor +### Contratos de status do provedor Localizados em `src/plugins/contracts/*.contract.test.ts`. -- **status** - Sondas de status de canal -- **registry** - Forma do registro de Plugin +- **status** - Probes de status de canal +- **registry** - Formato do registro de Plugin ### Contratos de provedor Localizados em `src/plugins/contracts/*.contract.test.ts`: -- **auth** - Contrato de fluxo de autenticação -- **auth-choice** - Escolha/seleção de autenticação +- **auth** - Contrato de fluxo de auth +- **auth-choice** - Escolha/seleção de auth - **catalog** - API de catálogo de modelos - **discovery** - Descoberta de Plugin - **loader** - Carregamento de Plugin - **runtime** - Runtime do provedor -- **shape** - Forma/interface do Plugin -- **wizard** - Assistente de configuração +- **shape** - Formato/interface do Plugin +- **wizard** - Assistente de setup ### Quando executar -- Depois de alterar exports ou subpaths do Plugin SDK -- Depois de adicionar ou modificar um canal ou Plugin de provedor -- Depois de refatorar registro ou descoberta de Plugin +- Após alterar exports ou subpaths de plugin-sdk +- Após adicionar ou modificar um canal ou Plugin de provedor +- Após refatorar registro ou descoberta de Plugin -Os testes de contrato rodam no CI e não exigem chaves de API reais. +Os testes de contrato rodam em CI e não exigem chaves reais. ## Adicionando regressões (orientação) Quando você corrigir um problema de provedor/modelo descoberto em live: -- Adicione uma regressão segura para CI, se possível (provedor simulado/stub, ou capture a transformação exata do formato da requisição) -- Se for inerentemente apenas live (rate limits, políticas de autenticação), mantenha o teste live restrito e opt-in por meio de variáveis de ambiente -- Prefira direcionar a menor camada que captura o bug: - - bug de conversão/replay de requisição do provedor → teste de modelos diretos - - bug de pipeline de sessão/histórico/ferramenta do Gateway → smoke live do Gateway ou teste simulado do Gateway seguro para CI -- Proteção de traversal de SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` deriva um alvo amostrado por classe de SecretRef a partir dos metadados do registro (`listSecretTargetRegistryEntries()`), depois valida que ids de exec de segmento de traversal são rejeitados. +- Adicione uma regressão segura para CI se possível (provedor mock/stub ou capture a transformação exata do formato da requisição) +- Se for inerentemente apenas live (limites de taxa, políticas de auth), mantenha o teste live restrito e opt-in via variáveis de ambiente +- Prefira mirar na menor camada que captura o bug: + - bug de conversão/replay da requisição do provedor → teste direto de modelos + - bug de pipeline de sessão/histórico/ferramenta do Gateway → smoke live do Gateway ou teste mock do Gateway seguro para CI +- Regra de proteção de travessia de SecretRef: + - `src/secrets/exec-secret-ref-id-parity.test.ts` deriva um alvo amostrado por classe de SecretRef a partir dos metadados do registro (`listSecretTargetRegistryEntries()`), depois valida que ids de exec de segmento de travessia são rejeitados. - Se você adicionar uma nova família de alvo SecretRef `includeInPlan` em `src/secrets/target-registry-data.ts`, atualize `classifyTargetClass` nesse teste. O teste falha intencionalmente em ids de alvo não classificados para que novas classes não possam ser ignoradas silenciosamente. diff --git a/docs/pt-BR/plugins/sdk-migration.md b/docs/pt-BR/plugins/sdk-migration.md index b63214d7a..82b0b1865 100644 --- a/docs/pt-BR/plugins/sdk-migration.md +++ b/docs/pt-BR/plugins/sdk-migration.md @@ -2,44 +2,36 @@ read_when: - Você vê o aviso OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED - Você vê o aviso OPENCLAW_EXTENSION_API_DEPRECATED - - Você está atualizando um plugin para a arquitetura moderna de plugins - - Você mantém um plugin externo do OpenClaw + - Você está atualizando um Plugin para a arquitetura moderna de plugins + - Você mantém um Plugin externo do OpenClaw sidebarTitle: Migrate to SDK -summary: Migre da camada legada de compatibilidade retroativa para o SDK de plugin moderno -title: Migração do SDK de Plugin +summary: Migrar da camada legada de compatibilidade retroativa para o Plugin SDK moderno +title: Migração do Plugin SDK x-i18n: - generated_at: "2026-04-09T01:30:36Z" + generated_at: "2026-04-17T05:36:07Z" model: gpt-5.4 provider: openai - source_hash: 60cbb6c8be30d17770887d490c14e3a4538563339a5206fb419e51e0558bbc07 + source_hash: f0283f949eec358a12a0709db846cde2a1509f28e5c60db6e563cb8a540b979d source_path: plugins/sdk-migration.md workflow: 15 --- -# Migração do SDK de Plugin +# Migração do Plugin SDK -O OpenClaw migrou de uma ampla camada de compatibilidade retroativa para uma -arquitetura moderna de plugins com imports focados e documentados. Se o seu -plugin foi criado antes da nova arquitetura, este guia ajuda na migração. +O OpenClaw migrou de uma camada ampla de compatibilidade retroativa para uma arquitetura moderna de plugins com imports focados e documentados. Se o seu Plugin foi criado antes da nova arquitetura, este guia ajuda você a migrar. ## O que está mudando -O sistema antigo de plugins fornecia duas superfícies amplas e abertas que permitiam que plugins importassem -qualquer coisa de que precisassem a partir de um único ponto de entrada: +O sistema antigo de plugins fornecia duas superfícies amplas que permitiam que os plugins importassem qualquer coisa de que precisassem a partir de um único ponto de entrada: -- **`openclaw/plugin-sdk/compat`** — um único import que reexportava dezenas de - helpers. Ele foi introduzido para manter plugins mais antigos baseados em hooks funcionando enquanto a - nova arquitetura de plugins estava sendo construída. -- **`openclaw/extension-api`** — uma bridge que dava aos plugins acesso direto a - helpers do lado do host, como o executor de agente embutido. +- **`openclaw/plugin-sdk/compat`** — um único import que reexportava dezenas de helpers. Ele foi introduzido para manter plugins antigos baseados em hooks funcionando enquanto a nova arquitetura de plugins era desenvolvida. +- **`openclaw/extension-api`** — uma ponte que dava aos plugins acesso direto a helpers do lado do host, como o executor de agentes embutido. -Ambas as superfícies agora estão **obsoletas**. Elas ainda funcionam em runtime, mas -novos plugins não devem usá-las, e plugins existentes devem migrar antes que a próxima -versão major as remova. +Ambas as superfícies agora estão **obsoletas**. Elas ainda funcionam em tempo de execução, mas novos plugins não devem usá-las, e os plugins existentes devem migrar antes que a próxima versão principal as remova. - A camada de compatibilidade retroativa será removida em uma futura versão major. - Plugins que ainda importarem dessas superfícies vão quebrar quando isso acontecer. + A camada de compatibilidade retroativa será removida em uma futura versão principal. + Plugins que ainda importarem dessas superfícies deixarão de funcionar quando isso acontecer. ## Por que isso mudou @@ -48,27 +40,27 @@ A abordagem antiga causava problemas: - **Inicialização lenta** — importar um helper carregava dezenas de módulos não relacionados - **Dependências circulares** — reexportações amplas facilitavam a criação de ciclos de import -- **Superfície de API pouco clara** — não havia como dizer quais exports eram estáveis e quais eram internos +- **Superfície de API pouco clara** — não havia como saber quais exports eram estáveis e quais eram internos -O SDK de plugin moderno corrige isso: cada caminho de import (`openclaw/plugin-sdk/\`) -é um módulo pequeno, autocontido, com um propósito claro e contrato documentado. +O Plugin SDK moderno corrige isso: cada caminho de import (`openclaw/plugin-sdk/\`) +é um módulo pequeno e autocontido com um propósito claro e um contrato documentado. -As seams legadas de conveniência de provedor para canais incluídos também acabaram. Imports +As conveniências legadas para providers de canais empacotados também desapareceram. Imports como `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, `openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, -seams helper com marca de canal e +superfícies auxiliares com marca de canal e `openclaw/plugin-sdk/telegram-core` eram atalhos privados do mono-repo, não -contratos estáveis de plugin. Use subcaminhos genéricos e estreitos do SDK. Dentro do -workspace de plugins incluídos, mantenha helpers pertencentes ao provedor no próprio -`api.ts` ou `runtime-api.ts` desse plugin. +contratos estáveis de plugin. Use subcaminhos genéricos e restritos do SDK em vez disso. Dentro do +workspace de plugins empacotados, mantenha helpers pertencentes ao provider no próprio +`api.ts` ou `runtime-api.ts` daquele Plugin. -Exemplos atuais de provedores incluídos: +Exemplos atuais de providers empacotados: -- Anthropic mantém helpers de stream específicos do Claude em sua própria seam `api.ts` / +- O Anthropic mantém helpers de streaming específicos do Claude em sua própria superfície `api.ts` / `contract-api.ts` -- OpenAI mantém builders de provedor, helpers de modelo padrão e builders de provedor - realtime em seu próprio `api.ts` -- OpenRouter mantém o builder de provedor e helpers de onboarding/config em seu próprio +- O OpenAI mantém builders de provider, helpers de modelo padrão e builders de provider + em tempo real em seu próprio `api.ts` +- O OpenRouter mantém helpers de builder de provider e de onboarding/configuração em seu próprio `api.ts` ## Como migrar @@ -76,55 +68,55 @@ Exemplos atuais de provedores incluídos: Plugins de canal com suporte a aprovação agora expõem comportamento nativo de aprovação por meio de - `approvalCapability.nativeRuntime` mais o registro compartilhado de contexto de runtime. + `approvalCapability.nativeRuntime` junto com o registro compartilhado de contexto de runtime. Principais mudanças: - Substitua `approvalCapability.handler.loadRuntime(...)` por `approvalCapability.nativeRuntime` - - Mova autenticação/entrega específicas de aprovação para fora do wiring legado `plugin.auth` / - `plugin.approvals` e para `approvalCapability` - - `ChannelPlugin.approvals` foi removido do contrato público - de plugin de canal; mova os campos de entrega/nativo/render para `approvalCapability` - - `plugin.auth` permanece apenas para fluxos de login/logout de canal; hooks de autenticação + - Mova autenticação/entrega específicas de aprovação da antiga estrutura `plugin.auth` / + `plugin.approvals` para `approvalCapability` + - `ChannelPlugin.approvals` foi removido do contrato público de + plugin de canal; mova os campos delivery/native/render para `approvalCapability` + - `plugin.auth` permanece apenas para fluxos de login/logout do canal; hooks de autenticação de aprovação ali não são mais lidos pelo core - - Registre objetos de runtime pertencentes ao canal, como clientes, tokens ou apps + - Registre objetos de runtime pertencentes ao canal, como clients, tokens ou apps Bolt, por meio de `openclaw/plugin-sdk/channel-runtime-context` - - Não envie avisos de redirecionamento pertencentes ao plugin a partir de handlers nativos de aprovação; - o core agora é responsável por avisos de encaminhamento para outro lugar a partir de resultados reais de entrega + - Não envie avisos de redirecionamento pertencentes ao Plugin a partir de handlers nativos de aprovação; + o core agora é responsável pelos avisos de “encaminhado para outro lugar” com base nos resultados reais de entrega - Ao passar `channelRuntime` para `createChannelManager(...)`, forneça uma superfície real de `createPluginRuntime().channel`. Stubs parciais são rejeitados. - Consulte `/plugins/sdk-channel-plugins` para o layout atual da + Consulte `/plugins/sdk-channel-plugins` para ver o layout atual da capacidade de aprovação. - Se o seu plugin usa `openclaw/plugin-sdk/windows-spawn`, wrappers `.cmd`/`.bat` não resolvidos no Windows - agora falham de forma fechada, a menos que você passe explicitamente - `allowShellFallback: true`. + Se o seu Plugin usa `openclaw/plugin-sdk/windows-spawn`, wrappers `.cmd`/`.bat` + não resolvidos no Windows agora falham de forma fechada, a menos que você passe + explicitamente `allowShellFallback: true`. ```typescript - // Antes + // Before const program = applyWindowsSpawnProgramPolicy({ candidate }); - // Depois + // After const program = applyWindowsSpawnProgramPolicy({ candidate, - // Defina isso apenas para chamadores de compatibilidade confiáveis que - // aceitam intencionalmente fallback mediado por shell. + // Only set this for trusted compatibility callers that intentionally + // accept shell-mediated fallback. allowShellFallback: true, }); ``` - Se o seu chamador não depender intencionalmente de fallback por shell, não defina + Se o seu chamador não depende intencionalmente de fallback por shell, não defina `allowShellFallback` e trate o erro lançado. - Pesquise no seu plugin imports vindos de qualquer uma das superfícies obsoletas: + Procure no seu Plugin imports de qualquer uma das superfícies obsoletas: ```bash grep -r "plugin-sdk/compat" my-plugin/ @@ -137,14 +129,14 @@ Exemplos atuais de provedores incluídos: Cada export da superfície antiga corresponde a um caminho de import moderno específico: ```typescript - // Antes (camada obsoleta de compatibilidade retroativa) + // Before (deprecated backwards-compatibility layer) import { createChannelReplyPipeline, createPluginRuntimeStore, resolveControlCommandGate, } from "openclaw/plugin-sdk/compat"; - // Depois (imports modernos e focados) + // After (modern focused imports) import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline"; import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store"; import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth"; @@ -154,15 +146,15 @@ Exemplos atuais de provedores incluídos: diretamente: ```typescript - // Antes (bridge obsoleta extension-api) + // Before (deprecated extension-api bridge) import { runEmbeddedPiAgent } from "openclaw/extension-api"; const result = await runEmbeddedPiAgent({ sessionId, prompt }); - // Depois (runtime injetado) + // After (injected runtime) const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt }); ``` - O mesmo padrão se aplica a outros helpers legados da bridge: + O mesmo padrão se aplica a outros helpers legados da ponte: | Import antigo | Equivalente moderno | | --- | --- | @@ -184,148 +176,148 @@ Exemplos atuais de provedores incluídos: -## Referência de caminhos de import +## Referência de caminhos de importação - - | Caminho de import | Finalidade | Principais exports | + + | Caminho de importação | Finalidade | Principais exports | | --- | --- | --- | - | `plugin-sdk/plugin-entry` | Helper canônico de entrada de plugin | `definePluginEntry` | - | `plugin-sdk/core` | Reexportação guarda-chuva legada para definições/builders de entrada de canal | `defineChannelPluginEntry`, `createChatChannelPlugin` | - | `plugin-sdk/config-schema` | Export do esquema raiz de configuração | `OpenClawSchema` | - | `plugin-sdk/provider-entry` | Helper de entrada de provedor único | `defineSingleProviderPluginEntry` | + | `plugin-sdk/plugin-entry` | Helper canônico de entrada de Plugin | `definePluginEntry` | + | `plugin-sdk/core` | Reexportação abrangente legada para definições/builders de entrada de canal | `defineChannelPluginEntry`, `createChatChannelPlugin` | + | `plugin-sdk/config-schema` | Export da schema de configuração raiz | `OpenClawSchema` | + | `plugin-sdk/provider-entry` | Helper de entrada para provider único | `defineSingleProviderPluginEntry` | | `plugin-sdk/channel-core` | Definições e builders focados de entrada de canal | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | | `plugin-sdk/setup` | Helpers compartilhados do assistente de configuração | Prompts de allowlist, builders de status de configuração | - | `plugin-sdk/setup-runtime` | Helpers de runtime em tempo de configuração | Adaptadores de patch de configuração seguros para import, helpers de nota de lookup, `promptResolvedAllowFrom`, `splitSetupEntries`, proxies de configuração delegada | + | `plugin-sdk/setup-runtime` | Helpers de runtime no momento da configuração | Adaptadores de patch de configuração seguros para importação, helpers de nota de lookup, `promptResolvedAllowFrom`, `splitSetupEntries`, proxies de configuração delegada | | `plugin-sdk/setup-adapter-runtime` | Helpers de adaptador de configuração | `createEnvPatchedAccountSetupAdapter` | - | `plugin-sdk/setup-tools` | Helpers de tooling de configuração | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | Helpers de múltiplas contas | Helpers de lista/configuração de conta/porta de ação | + | `plugin-sdk/setup-tools` | Helpers de ferramentas de configuração | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | + | `plugin-sdk/account-core` | Helpers de múltiplas contas | Helpers de lista/configuração de contas/portão de ação | | `plugin-sdk/account-id` | Helpers de ID de conta | `DEFAULT_ACCOUNT_ID`, normalização de ID de conta | | `plugin-sdk/account-resolution` | Helpers de lookup de conta | Helpers de lookup de conta + fallback padrão | - | `plugin-sdk/account-helpers` | Helpers estreitos de conta | Helpers de lista de conta/ação de conta | - | `plugin-sdk/channel-setup` | Adaptadores do assistente de configuração | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, mais `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/channel-pairing` | Primitivas de pareamento de DM | `createChannelPairingController` | - | `plugin-sdk/channel-reply-pipeline` | Wiring de prefixo de resposta + digitação | `createChannelReplyPipeline` | + | `plugin-sdk/account-helpers` | Helpers restritos de conta | Helpers de lista de contas/ação de conta | + | `plugin-sdk/channel-setup` | Adaptadores do assistente de configuração | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, além de `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | + | `plugin-sdk/channel-pairing` | Primitivas de pareamento por DM | `createChannelPairingController` | + | `plugin-sdk/channel-reply-pipeline` | Prefixo de resposta + encadeamento de digitação | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | Fábricas de adaptadores de configuração | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | Builders de esquema de configuração | Tipos de esquema de configuração de canal | - | `plugin-sdk/telegram-command-config` | Helpers de configuração de comando do Telegram | Normalização de nome de comando, trimming de descrição, validação de duplicidade/conflito | + | `plugin-sdk/channel-config-schema` | Builders de schema de configuração | Tipos de schema de configuração de canal | + | `plugin-sdk/telegram-command-config` | Helpers de configuração de comandos do Telegram | Normalização de nome de comando, truncamento de descrição, validação de duplicidade/conflito | | `plugin-sdk/channel-policy` | Resolução de política de grupo/DM | `resolveChannelGroupRequireMention` | | `plugin-sdk/channel-lifecycle` | Rastreamento de status de conta | `createAccountStatusSink` | | `plugin-sdk/inbound-envelope` | Helpers de envelope de entrada | Helpers compartilhados de rota + builder de envelope | - | `plugin-sdk/inbound-reply-dispatch` | Helpers de resposta de entrada | Helpers compartilhados de registrar e despachar | + | `plugin-sdk/inbound-reply-dispatch` | Helpers de resposta de entrada | Helpers compartilhados de registro e despacho | | `plugin-sdk/messaging-targets` | Parsing de destinos de mensagens | Helpers de parsing/correspondência de destino | | `plugin-sdk/outbound-media` | Helpers de mídia de saída | Carregamento compartilhado de mídia de saída | - | `plugin-sdk/outbound-runtime` | Helpers de runtime de saída | Helpers de identidade de saída/delegado de envio | - | `plugin-sdk/thread-bindings-runtime` | Helpers de vínculo de thread | Ciclo de vida de vínculo de thread e helpers de adaptador | - | `plugin-sdk/agent-media-payload` | Helpers legados de payload de mídia | Builder de payload de mídia de agente para layouts legados de campo | - | `plugin-sdk/channel-runtime` | Shim obsoleto de compatibilidade | Apenas utilitários legados de runtime de canal | + | `plugin-sdk/outbound-runtime` | Helpers de runtime de saída | Helpers de identidade de saída/delegação de envio | + | `plugin-sdk/thread-bindings-runtime` | Helpers de vínculo de thread | Helpers de ciclo de vida e adaptador de vínculo de thread | + | `plugin-sdk/agent-media-payload` | Helpers legados de payload de mídia | Builder de payload de mídia de agente para layouts legados de campos | + | `plugin-sdk/channel-runtime` | Shim de compatibilidade obsoleto | Apenas utilitários legados de runtime de canal | | `plugin-sdk/channel-send-result` | Tipos de resultado de envio | Tipos de resultado de resposta | - | `plugin-sdk/runtime-store` | Armazenamento persistente de plugin | `createPluginRuntimeStore` | + | `plugin-sdk/runtime-store` | Armazenamento persistente do Plugin | `createPluginRuntimeStore` | | `plugin-sdk/runtime` | Helpers amplos de runtime | Helpers de runtime/logging/backup/instalação de plugin | - | `plugin-sdk/runtime-env` | Helpers estreitos de env de runtime | Logger/env de runtime, helpers de timeout, retry e backoff | - | `plugin-sdk/plugin-runtime` | Helpers compartilhados de runtime de plugin | Helpers de comandos/hooks/http/interativo de plugin | - | `plugin-sdk/hook-runtime` | Helpers de pipeline de hook | Helpers compartilhados de pipeline de webhook/hook interno | + | `plugin-sdk/runtime-env` | Helpers restritos de ambiente de runtime | Logger/ambiente de runtime, timeout, retry e helpers de backoff | + | `plugin-sdk/plugin-runtime` | Helpers compartilhados de runtime de plugin | Helpers de comandos/hooks/http/interativos de plugin | + | `plugin-sdk/hook-runtime` | Helpers de pipeline de hook | Helpers compartilhados de pipeline de hook interno/Webhook | | `plugin-sdk/lazy-runtime` | Helpers de runtime lazy | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | Helpers de processo | Helpers compartilhados de execução | + | `plugin-sdk/process-runtime` | Helpers de processo | Helpers compartilhados de exec | | `plugin-sdk/cli-runtime` | Helpers de runtime de CLI | Formatação de comando, esperas, helpers de versão | - | `plugin-sdk/gateway-runtime` | Helpers de gateway | Cliente de gateway e helpers de patch de status de canal | - | `plugin-sdk/config-runtime` | Helpers de configuração | Helpers de carregar/gravar configuração | - | `plugin-sdk/telegram-command-config` | Helpers de comando do Telegram | Helpers de validação de comandos do Telegram estáveis para fallback quando a superfície de contrato do Telegram incluído não está disponível | - | `plugin-sdk/approval-runtime` | Helpers de prompt de aprovação | Payload de aprovação exec/plugin, helpers de perfil/capacidade de aprovação, helpers nativos de routing/runtime de aprovação | + | `plugin-sdk/gateway-runtime` | Helpers de Gateway | Cliente de Gateway e helpers de patch de status de canal | + | `plugin-sdk/config-runtime` | Helpers de configuração | Helpers de carregamento/gravação de configuração | + | `plugin-sdk/telegram-command-config` | Helpers de comando do Telegram | Helpers de validação de comando do Telegram estáveis em fallback quando a superfície contratual empacotada do Telegram não está disponível | + | `plugin-sdk/approval-runtime` | Helpers de prompt de aprovação | Payload de aprovação de exec/plugin, helpers de capacidade/perfil de aprovação, helpers nativos de roteamento/runtime de aprovação | | `plugin-sdk/approval-auth-runtime` | Helpers de autenticação de aprovação | Resolução de aprovador, autenticação de ação no mesmo chat | - | `plugin-sdk/approval-client-runtime` | Helpers de cliente de aprovação | Helpers de perfil/filtro de aprovação nativa exec | - | `plugin-sdk/approval-delivery-runtime` | Helpers de entrega de aprovação | Adaptadores de capacidade/entrega de aprovação nativa | - | `plugin-sdk/approval-gateway-runtime` | Helpers de gateway de aprovação | Helper compartilhado de resolução de gateway de aprovação | - | `plugin-sdk/approval-handler-adapter-runtime` | Helpers de adaptador de aprovação | Helpers leves de carregamento de adaptador nativo de aprovação para entrypoints quentes de canal | - | `plugin-sdk/approval-handler-runtime` | Helpers de handler de aprovação | Helpers mais amplos de runtime de handler de aprovação; prefira as seams mais estreitas de adaptador/gateway quando forem suficientes | - | `plugin-sdk/approval-native-runtime` | Helpers de alvo de aprovação | Helpers nativos de vínculo de alvo/conta de aprovação | - | `plugin-sdk/approval-reply-runtime` | Helpers de resposta de aprovação | Helpers de payload de resposta de aprovação exec/plugin | + | `plugin-sdk/approval-client-runtime` | Helpers de cliente de aprovação | Helpers nativos de perfil/filtro de aprovação de exec | + | `plugin-sdk/approval-delivery-runtime` | Helpers de entrega de aprovação | Adaptadores nativos de capacidade/entrega de aprovação | + | `plugin-sdk/approval-gateway-runtime` | Helpers de Gateway de aprovação | Helper compartilhado de resolução de Gateway de aprovação | + | `plugin-sdk/approval-handler-adapter-runtime` | Helpers de adaptador de aprovação | Helpers leves de carregamento de adaptador nativo de aprovação para pontos de entrada quentes de canal | + | `plugin-sdk/approval-handler-runtime` | Helpers de handler de aprovação | Helpers mais amplos de runtime de handler de aprovação; prefira as superfícies mais restritas de adaptador/Gateway quando elas forem suficientes | + | `plugin-sdk/approval-native-runtime` | Helpers de destino de aprovação | Helpers nativos de vínculo de destino/conta de aprovação | + | `plugin-sdk/approval-reply-runtime` | Helpers de resposta de aprovação | Helpers de payload de resposta de aprovação de exec/plugin | | `plugin-sdk/channel-runtime-context` | Helpers de contexto de runtime de canal | Helpers genéricos de registrar/obter/observar contexto de runtime de canal | - | `plugin-sdk/security-runtime` | Helpers de segurança | Helpers compartilhados de confiança, controle de DM, conteúdo externo e coleta de segredo | - | `plugin-sdk/ssrf-policy` | Helpers de política SSRF | Helpers de allowlist de host e política de rede privada | - | `plugin-sdk/ssrf-runtime` | Helpers de runtime SSRF | Helpers de dispatcher fixado, fetch protegido, política SSRF | + | `plugin-sdk/security-runtime` | Helpers de segurança | Helpers compartilhados de confiança, bloqueio de DM, conteúdo externo e coleta de segredos | + | `plugin-sdk/ssrf-policy` | Helpers de política de SSRF | Helpers de allowlist de host e política de rede privada | + | `plugin-sdk/ssrf-runtime` | Helpers de runtime de SSRF | Helpers de pinned-dispatcher, fetch protegido e política de SSRF | | `plugin-sdk/collection-runtime` | Helpers de cache limitado | `pruneMapToMaxSize` | - | `plugin-sdk/diagnostic-runtime` | Helpers de porta de diagnóstico | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | + | `plugin-sdk/diagnostic-runtime` | Helpers de bloqueio de diagnóstico | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | | `plugin-sdk/error-runtime` | Helpers de formatação de erro | `formatUncaughtError`, `isApprovalNotFoundError`, helpers de grafo de erro | | `plugin-sdk/fetch-runtime` | Helpers de fetch/proxy encapsulados | `resolveFetch`, helpers de proxy | | `plugin-sdk/host-runtime` | Helpers de normalização de host | `normalizeHostname`, `normalizeScpRemoteHost` | | `plugin-sdk/retry-runtime` | Helpers de retry | `RetryConfig`, `retryAsync`, executores de política | | `plugin-sdk/allow-from` | Formatação de allowlist | `formatAllowFromLowercase` | | `plugin-sdk/allowlist-resolution` | Mapeamento de entrada de allowlist | `mapAllowlistResolutionInputs` | - | `plugin-sdk/command-auth` | Porta de comando e helpers de superfície de comando | `resolveControlCommandGate`, helpers de autorização do remetente, helpers de registro de comandos | + | `plugin-sdk/command-auth` | Bloqueio de comando e helpers de superfície de comando | `resolveControlCommandGate`, helpers de autorização do remetente, helpers de registro de comandos | | `plugin-sdk/command-status` | Renderizadores de status/ajuda de comando | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` | - | `plugin-sdk/secret-input` | Parsing de entrada secreta | Helpers de entrada secreta | - | `plugin-sdk/webhook-ingress` | Helpers de requisição de webhook | Utilitários de destino de webhook | - | `plugin-sdk/webhook-request-guards` | Helpers de proteção de corpo de webhook | Helpers de leitura/limite de corpo de requisição | - | `plugin-sdk/reply-runtime` | Runtime compartilhado de resposta | Despacho de entrada, heartbeat, planejador de resposta, fragmentação | - | `plugin-sdk/reply-dispatch-runtime` | Helpers estreitos de despacho de resposta | Finalizar + helpers de despacho de provedor | + | `plugin-sdk/secret-input` | Parsing de entrada de segredo | Helpers de entrada de segredo | + | `plugin-sdk/webhook-ingress` | Helpers de requisição de Webhook | Utilitários de destino de Webhook | + | `plugin-sdk/webhook-request-guards` | Helpers de proteção do corpo de requisição de Webhook | Helpers de leitura/limite do corpo da requisição | + | `plugin-sdk/reply-runtime` | Runtime compartilhado de resposta | Despacho de entrada, Heartbeat, planejador de resposta, fragmentação | + | `plugin-sdk/reply-dispatch-runtime` | Helpers restritos de despacho de resposta | Helpers de finalização + despacho de provider | | `plugin-sdk/reply-history` | Helpers de histórico de resposta | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | Planejamento de referência de resposta | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | Helpers de chunk de resposta | Helpers de fragmentação de texto/markdown | - | `plugin-sdk/session-store-runtime` | Helpers de armazenamento de sessão | Helpers de caminho de armazenamento + updated-at | + | `plugin-sdk/reply-chunking` | Helpers de fragmentação de resposta | Helpers de fragmentação de texto/markdown | + | `plugin-sdk/session-store-runtime` | Helpers de armazenamento de sessão | Helpers de caminho do armazenamento + updated-at | | `plugin-sdk/state-paths` | Helpers de caminhos de estado | Helpers de diretório de estado e OAuth | - | `plugin-sdk/routing` | Helpers de routing/chave de sessão | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, helpers de normalização de chave de sessão | - | `plugin-sdk/status-helpers` | Helpers de status de canal | Builders de resumo de status de canal/conta, padrões de estado de runtime, helpers de metadados de issue | + | `plugin-sdk/routing` | Helpers de roteamento/chave de sessão | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, helpers de normalização de chave de sessão | + | `plugin-sdk/status-helpers` | Helpers de status de canal | Builders de resumo de status de canal/conta, padrões de estado de runtime, helpers de metadados de problema | | `plugin-sdk/target-resolver-runtime` | Helpers de resolvedor de destino | Helpers compartilhados de resolvedor de destino | | `plugin-sdk/string-normalization-runtime` | Helpers de normalização de string | Helpers de normalização de slug/string | - | `plugin-sdk/request-url` | Helpers de URL de requisição | Extrair URLs string de entradas semelhantes a request | - | `plugin-sdk/run-command` | Helpers de comando cronometrado | Executor de comando cronometrado com stdout/stderr normalizados | - | `plugin-sdk/param-readers` | Leitores de parâmetro | Leitores comuns de parâmetros de ferramenta/CLI | - | `plugin-sdk/tool-payload` | Extração de payload de ferramenta | Extrair payloads normalizados de objetos de resultado de ferramenta | - | `plugin-sdk/tool-send` | Extração de envio de ferramenta | Extrair campos canônicos de destino de envio dos args da ferramenta | + | `plugin-sdk/request-url` | Helpers de URL de requisição | Extrai URLs em string de entradas semelhantes a requisição | + | `plugin-sdk/run-command` | Helpers de comando com tempo controlado | Executor de comando com stdout/stderr normalizados | + | `plugin-sdk/param-readers` | Leitores de parâmetros | Leitores comuns de parâmetros de ferramenta/CLI | + | `plugin-sdk/tool-payload` | Extração de payload de ferramenta | Extrai payloads normalizados de objetos de resultado de ferramenta | + | `plugin-sdk/tool-send` | Extração de envio de ferramenta | Extrai campos canônicos de destino de envio de argumentos de ferramenta | | `plugin-sdk/temp-path` | Helpers de caminho temporário | Helpers compartilhados de caminho temporário para download | | `plugin-sdk/logging-core` | Helpers de logging | Logger de subsistema e helpers de redação | - | `plugin-sdk/markdown-table-runtime` | Helpers de tabela markdown | Helpers de modo de tabela markdown | + | `plugin-sdk/markdown-table-runtime` | Helpers de tabela Markdown | Helpers de modo de tabela Markdown | | `plugin-sdk/reply-payload` | Tipos de resposta de mensagem | Tipos de payload de resposta | - | `plugin-sdk/provider-setup` | Helpers curados de configuração de provedor local/self-hosted | Helpers de descoberta/configuração de provedor self-hosted | - | `plugin-sdk/self-hosted-provider-setup` | Helpers focados de configuração de provedor self-hosted compatível com OpenAI | Os mesmos helpers de descoberta/configuração de provedor self-hosted | - | `plugin-sdk/provider-auth-runtime` | Helpers de autenticação de runtime de provedor | Helpers de resolução de chave de API em runtime | - | `plugin-sdk/provider-auth-api-key` | Helpers de configuração de chave de API do provedor | Helpers de onboarding/gravação de perfil de chave de API | - | `plugin-sdk/provider-auth-result` | Helpers de resultado de autenticação de provedor | Builder padrão de resultado de autenticação OAuth | - | `plugin-sdk/provider-auth-login` | Helpers de login interativo de provedor | Helpers compartilhados de login interativo | - | `plugin-sdk/provider-env-vars` | Helpers de variáveis de env de provedor | Helpers de lookup de variáveis de env de autenticação do provedor | - | `plugin-sdk/provider-model-shared` | Helpers compartilhados de modelo/replay de provedor | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, builders compartilhados de política de replay, helpers de endpoint de provedor e helpers de normalização de ID de modelo | - | `plugin-sdk/provider-catalog-shared` | Helpers compartilhados de catálogo de provedor | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-onboard` | Patches de onboarding de provedor | Helpers de configuração de onboarding | - | `plugin-sdk/provider-http` | Helpers HTTP de provedor | Helpers genéricos de HTTP/capacidade de endpoint de provedor | - | `plugin-sdk/provider-web-fetch` | Helpers de web-fetch de provedor | Helpers de registro/cache de provedor web-fetch | - | `plugin-sdk/provider-web-search-config-contract` | Helpers de configuração de web search de provedor | Helpers estreitos de configuração/credencial de web search para provedores que não precisam de wiring de habilitação de plugin | - | `plugin-sdk/provider-web-search-contract` | Helpers de contrato de web search de provedor | Helpers estreitos de contrato de configuração/credencial de web search, como `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` e setters/getters de credenciais com escopo | - | `plugin-sdk/provider-web-search` | Helpers de web search de provedor | Helpers de registro/cache/runtime de provedor web-search | - | `plugin-sdk/provider-tools` | Helpers de compat de ferramenta/esquema de provedor | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, limpeza + diagnósticos de esquema Gemini e helpers de compat xAI como `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | - | `plugin-sdk/provider-usage` | Helpers de uso de provedor | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` e outros helpers de uso de provedor | - | `plugin-sdk/provider-stream` | Helpers de wrapper de stream de provedor | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipos de wrapper de stream e helpers compartilhados de wrapper Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/provider-setup` | Helpers curados de configuração de provider local/self-hosted | Helpers de descoberta/configuração de provider self-hosted | + | `plugin-sdk/self-hosted-provider-setup` | Helpers focados de configuração de provider self-hosted compatível com OpenAI | Os mesmos helpers de descoberta/configuração de provider self-hosted | + | `plugin-sdk/provider-auth-runtime` | Helpers de autenticação de runtime de provider | Helpers de resolução de chave de API em runtime | + | `plugin-sdk/provider-auth-api-key` | Helpers de configuração de chave de API de provider | Helpers de onboarding/gravação de perfil de chave de API | + | `plugin-sdk/provider-auth-result` | Helpers de resultado de autenticação de provider | Builder padrão de resultado de autenticação OAuth | + | `plugin-sdk/provider-auth-login` | Helpers de login interativo de provider | Helpers compartilhados de login interativo | + | `plugin-sdk/provider-env-vars` | Helpers de variáveis de ambiente de provider | Helpers de lookup de variável de ambiente de autenticação de provider | + | `plugin-sdk/provider-model-shared` | Helpers compartilhados de modelo/replay de provider | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, builders compartilhados de política de replay, helpers de endpoint de provider e helpers de normalização de ID de modelo | + | `plugin-sdk/provider-catalog-shared` | Helpers compartilhados de catálogo de providers | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | + | `plugin-sdk/provider-onboard` | Patches de onboarding de provider | Helpers de configuração de onboarding | + | `plugin-sdk/provider-http` | Helpers HTTP de provider | Helpers genéricos de capacidade HTTP/endpoint de provider | + | `plugin-sdk/provider-web-fetch` | Helpers de web-fetch de provider | Helpers de registro/cache de provider de web-fetch | + | `plugin-sdk/provider-web-search-config-contract` | Helpers de configuração de busca na web de provider | Helpers restritos de configuração/credencial de busca na web para providers que não precisam de wiring de ativação de plugin | + | `plugin-sdk/provider-web-search-contract` | Helpers de contrato de busca na web de provider | Helpers restritos de contrato de configuração/credencial de busca na web, como `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` e setters/getters de credenciais com escopo | + | `plugin-sdk/provider-web-search` | Helpers de busca na web de provider | Helpers de registro/cache/runtime de provider de busca na web | + | `plugin-sdk/provider-tools` | Helpers de compatibilidade de ferramenta/schema de provider | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, limpeza de schema do Gemini + diagnósticos e helpers de compatibilidade do xAI, como `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-usage` | Helpers de uso de provider | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` e outros helpers de uso de provider | + | `plugin-sdk/provider-stream` | Helpers de wrapper de stream de provider | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipos de wrapper de stream e helpers compartilhados de wrapper de Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | | `plugin-sdk/keyed-async-queue` | Fila assíncrona ordenada | `KeyedAsyncQueue` | - | `plugin-sdk/media-runtime` | Helpers compartilhados de mídia | Helpers de fetch/transform/store de mídia mais builders de payload de mídia | + | `plugin-sdk/media-runtime` | Helpers compartilhados de mídia | Helpers de fetch/transform/store de mídia, além de builders de payload de mídia | | `plugin-sdk/media-generation-runtime` | Helpers compartilhados de geração de mídia | Helpers compartilhados de failover, seleção de candidatos e mensagens de modelo ausente para geração de imagem/vídeo/música | - | `plugin-sdk/media-understanding` | Helpers de media-understanding | Tipos de provedor de compreensão de mídia mais exports de helper voltados ao provedor para imagem/áudio | - | `plugin-sdk/text-runtime` | Helpers compartilhados de texto | Remoção de texto visível ao assistente, helpers de renderização/fragmentação/tabela markdown, helpers de redação, helpers de tag de diretiva, utilitários de texto seguro e helpers relacionados de texto/logging | + | `plugin-sdk/media-understanding` | Helpers de compreensão de mídia | Tipos de provider de compreensão de mídia, além de exports de helpers de imagem/áudio voltados para providers | + | `plugin-sdk/text-runtime` | Helpers compartilhados de texto | Remoção de texto visível ao assistente, helpers de renderização/fragmentação/tabela em markdown, helpers de redação, helpers de tag de diretiva, utilitários de texto seguro e helpers relacionados de texto/logging | | `plugin-sdk/text-chunking` | Helpers de fragmentação de texto | Helper de fragmentação de texto de saída | - | `plugin-sdk/speech` | Helpers de speech | Tipos de provedor de speech mais exports de helper voltados ao provedor para diretiva, registro e validação | - | `plugin-sdk/speech-core` | Core compartilhado de speech | Tipos de provedor de speech, registro, diretivas, normalização | - | `plugin-sdk/realtime-transcription` | Helpers de transcrição em tempo real | Tipos de provedor e helpers de registro | - | `plugin-sdk/realtime-voice` | Helpers de voz em tempo real | Tipos de provedor e helpers de registro | - | `plugin-sdk/image-generation-core` | Core compartilhado de geração de imagem | Tipos, failover, autenticação e helpers de registro de geração de imagem | - | `plugin-sdk/music-generation` | Helpers de geração de música | Tipos de provedor/solicitação/resultado de geração de música | - | `plugin-sdk/music-generation-core` | Core compartilhado de geração de música | Tipos, helpers de failover, lookup de provedor e parsing de referência de modelo para geração de música | - | `plugin-sdk/video-generation` | Helpers de geração de vídeo | Tipos de provedor/solicitação/resultado de geração de vídeo | - | `plugin-sdk/video-generation-core` | Core compartilhado de geração de vídeo | Tipos, helpers de failover, lookup de provedor e parsing de referência de modelo para geração de vídeo | + | `plugin-sdk/speech` | Helpers de fala | Tipos de provider de fala, além de helpers de diretiva, registro e validação voltados para providers | + | `plugin-sdk/speech-core` | Core compartilhado de fala | Tipos de provider de fala, registro, diretivas, normalização | + | `plugin-sdk/realtime-transcription` | Helpers de transcrição em tempo real | Tipos de provider e helpers de registro | + | `plugin-sdk/realtime-voice` | Helpers de voz em tempo real | Tipos de provider e helpers de registro | + | `plugin-sdk/image-generation-core` | Core compartilhado de geração de imagens | Tipos de geração de imagens, failover, autenticação e helpers de registro | + | `plugin-sdk/music-generation` | Helpers de geração de música | Tipos de provider/request/result de geração de música | + | `plugin-sdk/music-generation-core` | Core compartilhado de geração de música | Tipos de geração de música, helpers de failover, lookup de provider e parsing de model-ref | + | `plugin-sdk/video-generation` | Helpers de geração de vídeo | Tipos de provider/request/result de geração de vídeo | + | `plugin-sdk/video-generation-core` | Core compartilhado de geração de vídeo | Tipos de geração de vídeo, helpers de failover, lookup de provider e parsing de model-ref | | `plugin-sdk/interactive-runtime` | Helpers de resposta interativa | Normalização/redução de payload de resposta interativa | - | `plugin-sdk/channel-config-primitives` | Primitivas de configuração de canal | Primitivas estreitas de esquema de configuração de canal | + | `plugin-sdk/channel-config-primitives` | Primitivas de configuração de canal | Primitivas restritas de config-schema de canal | | `plugin-sdk/channel-config-writes` | Helpers de gravação de configuração de canal | Helpers de autorização de gravação de configuração de canal | | `plugin-sdk/channel-plugin-common` | Prelúdio compartilhado de canal | Exports compartilhados do prelúdio de plugin de canal | | `plugin-sdk/channel-status` | Helpers de status de canal | Helpers compartilhados de snapshot/resumo de status de canal | - | `plugin-sdk/allowlist-config-edit` | Helpers de configuração de allowlist | Helpers de editar/ler configuração de allowlist | - | `plugin-sdk/group-access` | Helpers de acesso de grupo | Helpers compartilhados de decisão de acesso de grupo | - | `plugin-sdk/direct-dm` | Helpers de DM direto | Helpers compartilhados de autenticação/proteção de DM direto | - | `plugin-sdk/extension-shared` | Helpers compartilhados de extensão | Primitivas helper de canal/status passivo e proxy ambiente | - | `plugin-sdk/webhook-targets` | Helpers de destino de webhook | Registro de destino de webhook e helpers de instalação de rota | - | `plugin-sdk/webhook-path` | Helpers de caminho de webhook | Helpers de normalização de caminho de webhook | + | `plugin-sdk/allowlist-config-edit` | Helpers de configuração de allowlist | Helpers de edição/leitura de configuração de allowlist | + | `plugin-sdk/group-access` | Helpers de acesso a grupo | Helpers compartilhados de decisão de acesso a grupo | + | `plugin-sdk/direct-dm` | Helpers de DM direta | Helpers compartilhados de autenticação/proteção de DM direta | + | `plugin-sdk/extension-shared` | Helpers compartilhados de extensão | Primitivas de canal/status passivo e helper de proxy ambiental | + | `plugin-sdk/webhook-targets` | Helpers de destino de Webhook | Helpers de registro de destino de Webhook e instalação de rota | + | `plugin-sdk/webhook-path` | Helpers de caminho de Webhook | Helpers de normalização de caminho de Webhook | | `plugin-sdk/web-media` | Helpers compartilhados de mídia web | Helpers de carregamento de mídia remota/local | - | `plugin-sdk/zod` | Reexportação de Zod | `zod` reexportado para consumidores do SDK de plugin | - | `plugin-sdk/memory-core` | Helpers incluídos de memory-core | Superfície helper de gerenciador/configuração/arquivo/CLI de memória | - | `plugin-sdk/memory-core-engine-runtime` | Fachada de runtime do mecanismo de memória | Fachada de runtime de índice/pesquisa de memória | - | `plugin-sdk/memory-core-host-engine-foundation` | Mecanismo foundation do host de memória | Exports do mecanismo foundation do host de memória | - | `plugin-sdk/memory-core-host-engine-embeddings` | Mecanismo de embeddings do host de memória | Exports do mecanismo de embeddings do host de memória | + | `plugin-sdk/zod` | Reexportação do Zod | `zod` reexportado para consumidores do Plugin SDK | + | `plugin-sdk/memory-core` | Helpers empacotados de memory-core | Superfície de helpers de gerenciador/configuração/arquivo/CLI de memória | + | `plugin-sdk/memory-core-engine-runtime` | Fachada de runtime do mecanismo de memória | Fachada de runtime de índice/busca de memória | + | `plugin-sdk/memory-core-host-engine-foundation` | Mecanismo de fundação do host de memória | Exports do mecanismo de fundação do host de memória | + | `plugin-sdk/memory-core-host-engine-embeddings` | Mecanismo de embeddings do host de memória | Contratos de embedding de memória, acesso ao registro, provider local e helpers genéricos de lote/remoto; providers remotos concretos ficam em seus plugins proprietários | | `plugin-sdk/memory-core-host-engine-qmd` | Mecanismo QMD do host de memória | Exports do mecanismo QMD do host de memória | | `plugin-sdk/memory-core-host-engine-storage` | Mecanismo de armazenamento do host de memória | Exports do mecanismo de armazenamento do host de memória | | `plugin-sdk/memory-core-host-multimodal` | Helpers multimodais do host de memória | Helpers multimodais do host de memória | @@ -333,37 +325,37 @@ Exemplos atuais de provedores incluídos: | `plugin-sdk/memory-core-host-secret` | Helpers de segredo do host de memória | Helpers de segredo do host de memória | | `plugin-sdk/memory-core-host-events` | Helpers de journal de eventos do host de memória | Helpers de journal de eventos do host de memória | | `plugin-sdk/memory-core-host-status` | Helpers de status do host de memória | Helpers de status do host de memória | - | `plugin-sdk/memory-core-host-runtime-cli` | Runtime CLI do host de memória | Helpers de runtime CLI do host de memória | + | `plugin-sdk/memory-core-host-runtime-cli` | Runtime de CLI do host de memória | Helpers de runtime de CLI do host de memória | | `plugin-sdk/memory-core-host-runtime-core` | Runtime core do host de memória | Helpers de runtime core do host de memória | | `plugin-sdk/memory-core-host-runtime-files` | Helpers de arquivo/runtime do host de memória | Helpers de arquivo/runtime do host de memória | - | `plugin-sdk/memory-host-core` | Alias de runtime core do host de memória | Alias neutro em relação ao fornecedor para helpers de runtime core do host de memória | - | `plugin-sdk/memory-host-events` | Alias de journal de eventos do host de memória | Alias neutro em relação ao fornecedor para helpers de journal de eventos do host de memória | - | `plugin-sdk/memory-host-files` | Alias de arquivo/runtime do host de memória | Alias neutro em relação ao fornecedor para helpers de arquivo/runtime do host de memória | + | `plugin-sdk/memory-host-core` | Alias de runtime core do host de memória | Alias neutro em relação a fornecedor para helpers de runtime core do host de memória | + | `plugin-sdk/memory-host-events` | Alias de journal de eventos do host de memória | Alias neutro em relação a fornecedor para helpers de journal de eventos do host de memória | + | `plugin-sdk/memory-host-files` | Alias de arquivo/runtime do host de memória | Alias neutro em relação a fornecedor para helpers de arquivo/runtime do host de memória | | `plugin-sdk/memory-host-markdown` | Helpers de markdown gerenciado | Helpers compartilhados de markdown gerenciado para plugins adjacentes à memória | - | `plugin-sdk/memory-host-search` | Fachada de pesquisa de memória ativa | Fachada lazy de runtime do gerenciador de pesquisa de memória ativa | - | `plugin-sdk/memory-host-status` | Alias de status do host de memória | Alias neutro em relação ao fornecedor para helpers de status do host de memória | - | `plugin-sdk/memory-lancedb` | Helpers incluídos de memory-lancedb | Superfície helper de memory-lancedb | + | `plugin-sdk/memory-host-search` | Fachada de busca de Active Memory | Fachada lazy de runtime do gerenciador de busca de Active Memory | + | `plugin-sdk/memory-host-status` | Alias de status do host de memória | Alias neutro em relação a fornecedor para helpers de status do host de memória | + | `plugin-sdk/memory-lancedb` | Helpers empacotados de memory-lancedb | Superfície de helpers de memory-lancedb | | `plugin-sdk/testing` | Utilitários de teste | Helpers e mocks de teste | -Esta tabela é intencionalmente o subconjunto comum de migração, não a superfície completa -do SDK. A lista completa de mais de 200 entrypoints está em +Esta tabela é intencionalmente o subconjunto comum de migração, não toda a +superfície do SDK. A lista completa de mais de 200 pontos de entrada está em `scripts/lib/plugin-sdk-entrypoints.json`. -Essa lista ainda inclui algumas seams helper de plugins incluídos, como +Essa lista ainda inclui algumas superfícies auxiliares de plugins empacotados, como `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` e `plugin-sdk/matrix*`. Elas continuam exportadas para -manutenção e compatibilidade de plugins incluídos, mas são intencionalmente +manutenção e compatibilidade de plugins empacotados, mas são intencionalmente omitidas da tabela comum de migração e não são o destino recomendado para -novo código de plugin. +novo código de Plugin. -A mesma regra se aplica a outras famílias de helper incluídas, como: +A mesma regra se aplica a outras famílias de helpers empacotados, como: - helpers de suporte a navegador: `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` - Matrix: `plugin-sdk/matrix*` - LINE: `plugin-sdk/line*` - IRC: `plugin-sdk/irc*` -- superfícies incluídas de helper/plugin como `plugin-sdk/googlechat`, +- superfícies auxiliares/de plugin empacotadas, como `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles*`, `plugin-sdk/mattermost*`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, @@ -372,22 +364,22 @@ A mesma regra se aplica a outras famílias de helper incluídas, como: `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership` e `plugin-sdk/voice-call` -`plugin-sdk/github-copilot-token` atualmente expõe a superfície estreita de helper de token -`DEFAULT_COPILOT_API_BASE_URL`, +Atualmente, `plugin-sdk/github-copilot-token` expõe a superfície restrita de helper +de token `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` e `resolveCopilotApiToken`. -Use o import mais estreito que corresponda à tarefa. Se você não encontrar um export, +Use o import mais restrito que corresponda à tarefa. Se você não encontrar um export, verifique a fonte em `src/plugin-sdk/` ou pergunte no Discord. -## Linha do tempo de remoção +## Cronograma de remoção -| Quando | O que acontece | -| ---------------------- | ------------------------------------------------------------------------ | -| **Agora** | Superfícies obsoletas emitem avisos em runtime | -| **Próxima versão major** | Superfícies obsoletas serão removidas; plugins que ainda as usam falharão | +| Quando | O que acontece | +| ---------------------- | ----------------------------------------------------------------------- | +| **Agora** | As superfícies obsoletas emitem avisos em tempo de execução | +| **Próxima versão principal** | As superfícies obsoletas serão removidas; plugins que ainda as utilizarem falharão | -Todos os plugins core já foram migrados. Plugins externos devem migrar -antes da próxima versão major. +Todos os plugins do core já foram migrados. Plugins externos devem migrar +antes da próxima versão principal. ## Suprimindo os avisos temporariamente @@ -398,13 +390,13 @@ OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run ``` -Isto é uma rota de escape temporária, não uma solução permanente. +Esta é uma rota de escape temporária, não uma solução permanente. ## Relacionado -- [Primeiros passos](/pt-BR/plugins/building-plugins) — crie seu primeiro plugin +- [Primeiros passos](/pt-BR/plugins/building-plugins) — crie seu primeiro Plugin - [Visão geral do SDK](/pt-BR/plugins/sdk-overview) — referência completa de imports por subcaminho - [Plugins de canal](/pt-BR/plugins/sdk-channel-plugins) — criando plugins de canal -- [Plugins de provedor](/pt-BR/plugins/sdk-provider-plugins) — criando plugins de provedor -- [Internos de plugin](/pt-BR/plugins/architecture) — análise aprofundada da arquitetura -- [Manifesto de Plugin](/pt-BR/plugins/manifest) — referência do esquema de manifesto +- [Plugins de provider](/pt-BR/plugins/sdk-provider-plugins) — criando plugins de provider +- [Internals de Plugin](/pt-BR/plugins/architecture) — aprofundamento na arquitetura +- [Manifesto de Plugin](/pt-BR/plugins/manifest) — referência do schema de manifesto diff --git a/docs/pt-BR/plugins/sdk-overview.md b/docs/pt-BR/plugins/sdk-overview.md index 68b40fee5..4bd746d9b 100644 --- a/docs/pt-BR/plugins/sdk-overview.md +++ b/docs/pt-BR/plugins/sdk-overview.md @@ -1,30 +1,30 @@ --- read_when: - Você precisa saber de qual subcaminho do SDK importar - - Você quer uma referência para todos os métodos de registro em OpenClawPluginApi + - Você quer uma referência de todos os métodos de registro em `OpenClawPluginApi` - Você está procurando uma exportação específica do SDK sidebarTitle: SDK Overview summary: Mapa de importação, referência da API de registro e arquitetura do SDK -title: Visão geral do SDK de plugins +title: Visão geral do Plugin SDK x-i18n: - generated_at: "2026-04-11T02:46:25Z" + generated_at: "2026-04-17T05:36:06Z" model: gpt-5.4 provider: openai - source_hash: 4bfeb5896f68e3e4ee8cf434d43a019e0d1fe5af57f5bf7a5172847c476def0c + source_hash: b177fdb6830f415d998a24812bc2c7db8124d3ba77b0174c9a67ac7d747f7e5a source_path: plugins/sdk-overview.md workflow: 15 --- -# Visão geral do SDK de plugins +# Visão geral do Plugin SDK -O SDK de plugins é o contrato tipado entre plugins e o core. Esta página é a +O SDK de plugin é o contrato tipado entre plugins e o núcleo. Esta página é a referência para **o que importar** e **o que você pode registrar**. - **Está procurando um guia prático?** + **Procurando um guia prático?** - Primeiro plugin? Comece com [Primeiros passos](/pt-BR/plugins/building-plugins) - - Plugin de canal? Consulte [Plugins de canal](/pt-BR/plugins/sdk-channel-plugins) - - Plugin de provedor? Consulte [Plugins de provedor](/pt-BR/plugins/sdk-provider-plugins) + - Plugin de canal? Veja [Plugins de canal](/pt-BR/plugins/sdk-channel-plugins) + - Plugin de provedor? Veja [Plugins de provedor](/pt-BR/plugins/sdk-provider-plugins) ## Convenção de importação @@ -37,269 +37,269 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; ``` Cada subcaminho é um módulo pequeno e autocontido. Isso mantém a inicialização rápida e -evita problemas de dependência circular. Para helpers específicos de entrada/build de canal, -prefira `openclaw/plugin-sdk/channel-core`; mantenha `openclaw/plugin-sdk/core` para -a superfície guarda-chuva mais ampla e helpers compartilhados como +evita problemas de dependência circular. Para auxiliares específicos de +entrada/construção de canal, prefira `openclaw/plugin-sdk/channel-core`; mantenha `openclaw/plugin-sdk/core` para +a superfície guarda-chuva mais ampla e auxiliares compartilhados, como `buildChannelConfigSchema`. -Não adicione nem dependa de seams de conveniência nomeadas por provedor, como +Não adicione nem dependa de seams de conveniência com nome de provedor, como `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, `openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, ou -seams de helper com marca de canal. Plugins empacotados devem compor subcaminhos genéricos -do SDK dentro de seus próprios barrels `api.ts` ou `runtime-api.ts`, e o core -deve usar esses barrels locais do plugin ou adicionar um contrato genérico e estreito do SDK +seams auxiliares com marca de canal. Plugins empacotados devem compor +subcaminhos genéricos do SDK dentro de seus próprios barrels `api.ts` ou `runtime-api.ts`, e o núcleo +deve usar esses barrels locais do plugin ou adicionar um contrato genérico e restrito do SDK quando a necessidade for realmente entre canais. -O mapa de exportações gerado ainda contém um pequeno conjunto de -seams de helper de plugins empacotados, como `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, +O mapa de exportação gerado ainda contém um pequeno conjunto de +seams auxiliares de plugins empacotados, como `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` e `plugin-sdk/matrix*`. Esses subcaminhos existem apenas para manutenção e compatibilidade de plugins empacotados; eles são -omitidos intencionalmente da tabela comum abaixo e não são o caminho de importação recomendado -para novos plugins de terceiros. +intencionalmente omitidos da tabela comum abaixo e não são o caminho de +importação recomendado para novos plugins de terceiros. ## Referência de subcaminhos -Os subcaminhos mais usados, agrupados por finalidade. A lista completa gerada com -mais de 200 subcaminhos fica em `scripts/lib/plugin-sdk-entrypoints.json`. +Os subcaminhos usados com mais frequência, agrupados por finalidade. A lista completa gerada de +mais de 200 subcaminhos está em `scripts/lib/plugin-sdk-entrypoints.json`. -Subcaminhos reservados de helper de plugins empacotados ainda aparecem nessa lista gerada. +Subcaminhos auxiliares reservados para plugins empacotados ainda aparecem nessa lista gerada. Trate-os como superfícies de detalhe de implementação/compatibilidade, a menos que uma página da documentação -promova explicitamente algum deles como público. +promova explicitamente um deles como público. -### Entrada de plugin +### Entrada do plugin -| Subcaminho | Exportações principais | -| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -| `plugin-sdk/plugin-entry` | `definePluginEntry` | -| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | -| `plugin-sdk/config-schema` | `OpenClawSchema` | -| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | +| Subcaminho | Principais exportações | +| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| `plugin-sdk/plugin-entry` | `definePluginEntry` | +| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | +| `plugin-sdk/config-schema` | `OpenClawSchema` | +| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | Subcaminho | Exportações principais | + | Subcaminho | Principais exportações | | --- | --- | | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/config-schema` | Exportação do schema Zod raiz de `openclaw.json` (`OpenClawSchema`) | + | `plugin-sdk/config-schema` | Exportação do esquema Zod raiz de `openclaw.json` (`OpenClawSchema`) | | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, além de `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/setup` | Helpers compartilhados de assistente de configuração, prompts de allowlist, builders de status de configuração | + | `plugin-sdk/setup` | Auxiliares compartilhados do assistente de configuração, prompts de allowlist, construtores de status de configuração | | `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | | `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` | | `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | Helpers de configuração multi-account/action-gate e helpers de fallback de conta padrão | - | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, helpers de normalização de account-id | - | `plugin-sdk/account-resolution` | Helpers de busca de conta + fallback padrão | - | `plugin-sdk/account-helpers` | Helpers estreitos de lista de contas/ações de conta | + | `plugin-sdk/account-core` | Auxiliares de gate de ação/configuração com múltiplas contas, auxiliares de fallback de conta padrão | + | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, auxiliares de normalização de ID de conta | + | `plugin-sdk/account-resolution` | Auxiliares de busca de conta + fallback padrão | + | `plugin-sdk/account-helpers` | Auxiliares restritos para lista de contas/ação de conta | | `plugin-sdk/channel-pairing` | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | Tipos de schema de configuração de canal | - | `plugin-sdk/telegram-command-config` | Helpers de normalização/validação de comando personalizado do Telegram com fallback de contrato empacotado | + | `plugin-sdk/channel-config-schema` | Tipos de esquema de configuração de canal | + | `plugin-sdk/telegram-command-config` | Auxiliares de normalização/validação de comandos personalizados do Telegram com fallback de contrato empacotado | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` | - | `plugin-sdk/inbound-envelope` | Helpers compartilhados de rota de entrada + builder de envelope | - | `plugin-sdk/inbound-reply-dispatch` | Helpers compartilhados de registro e dispatch de entrada | - | `plugin-sdk/messaging-targets` | Helpers de parsing/correspondência de alvo | - | `plugin-sdk/outbound-media` | Helpers compartilhados de carregamento de mídia de saída | - | `plugin-sdk/outbound-runtime` | Helpers de identidade de saída/delegação de envio | - | `plugin-sdk/thread-bindings-runtime` | Lifecycle de binding de thread e helpers de adapter | - | `plugin-sdk/agent-media-payload` | Builder legado de payload de mídia do agente | - | `plugin-sdk/conversation-runtime` | Helpers de binding configurado, pairing e binding de conversa/thread | - | `plugin-sdk/runtime-config-snapshot` | Helper de snapshot de configuração de runtime | - | `plugin-sdk/runtime-group-policy` | Helpers de resolução de política de grupo em runtime | - | `plugin-sdk/channel-status` | Helpers compartilhados de snapshot/resumo de status de canal | - | `plugin-sdk/channel-config-primitives` | Primitivos estreitos de schema de configuração de canal | - | `plugin-sdk/channel-config-writes` | Helpers de autorização de escrita de configuração de canal | - | `plugin-sdk/channel-plugin-common` | Exportações de prelude compartilhadas de plugin de canal | - | `plugin-sdk/allowlist-config-edit` | Helpers de leitura/edição de configuração de allowlist | - | `plugin-sdk/group-access` | Helpers compartilhados de decisão de acesso a grupo | - | `plugin-sdk/direct-dm` | Helpers compartilhados de autenticação/proteção de DM direta | - | `plugin-sdk/interactive-runtime` | Helpers de normalização/redução de payload de resposta interativa | - | `plugin-sdk/channel-inbound` | Helpers de debounce de entrada, correspondência de menção, política de menção e envelope | + | `plugin-sdk/inbound-envelope` | Auxiliares compartilhados de rota de entrada + construtor de envelope | + | `plugin-sdk/inbound-reply-dispatch` | Auxiliares compartilhados de registro e despacho de entrada | + | `plugin-sdk/messaging-targets` | Auxiliares de análise/correspondência de alvos | + | `plugin-sdk/outbound-media` | Auxiliares compartilhados de carregamento de mídia de saída | + | `plugin-sdk/outbound-runtime` | Auxiliares de identidade de saída/delegação de envio | + | `plugin-sdk/thread-bindings-runtime` | Ciclo de vida de vínculo de thread e auxiliares de adaptador | + | `plugin-sdk/agent-media-payload` | Construtor legado de payload de mídia do agente | + | `plugin-sdk/conversation-runtime` | Auxiliares de vínculo de conversa/thread, pareamento e vínculo configurado | + | `plugin-sdk/runtime-config-snapshot` | Auxiliar de snapshot de configuração em runtime | + | `plugin-sdk/runtime-group-policy` | Auxiliares de resolução de política de grupo em runtime | + | `plugin-sdk/channel-status` | Auxiliares compartilhados de snapshot/resumo de status do canal | + | `plugin-sdk/channel-config-primitives` | Primitivas restritas de esquema de configuração de canal | + | `plugin-sdk/channel-config-writes` | Auxiliares de autorização de gravação de configuração de canal | + | `plugin-sdk/channel-plugin-common` | Exportações de prelúdio compartilhadas de plugin de canal | + | `plugin-sdk/allowlist-config-edit` | Auxiliares de leitura/edição de configuração de allowlist | + | `plugin-sdk/group-access` | Auxiliares compartilhados de decisão de acesso a grupo | + | `plugin-sdk/direct-dm` | Auxiliares compartilhados de autenticação/proteção de DM direta | + | `plugin-sdk/interactive-runtime` | Auxiliares de normalização/redução de payload de resposta interativa | + | `plugin-sdk/channel-inbound` | Debounce de entrada, correspondência de menção, auxiliares de política de menção e auxiliares de envelope | | `plugin-sdk/channel-send-result` | Tipos de resultado de resposta | | `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` | - | `plugin-sdk/channel-targets` | Helpers de parsing/correspondência de alvo | + | `plugin-sdk/channel-targets` | Auxiliares de análise/correspondência de alvos | | `plugin-sdk/channel-contract` | Tipos de contrato de canal | - | `plugin-sdk/channel-feedback` | Wiring de feedback/reação | - | `plugin-sdk/channel-secret-runtime` | Helpers estreitos de contrato de segredo, como `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, e tipos de destino de segredo | + | `plugin-sdk/channel-feedback` | Ligação de feedback/reação | + | `plugin-sdk/channel-secret-runtime` | Auxiliares restritos de contrato de segredo, como `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment` e tipos de alvo de segredo | - | Subcaminho | Exportações principais | + | Subcaminho | Principais exportações | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/provider-setup` | Helpers selecionados de configuração de provedor local/self-hosted | - | `plugin-sdk/self-hosted-provider-setup` | Helpers focados de configuração de provedor self-hosted compatível com OpenAI | - | `plugin-sdk/cli-backend` | Padrões de backend de CLI + constantes de watchdog | - | `plugin-sdk/provider-auth-runtime` | Helpers de runtime para resolução de chave de API para plugins de provedor | - | `plugin-sdk/provider-auth-api-key` | Helpers de onboarding/escrita de perfil de chave de API, como `upsertApiKeyProfile` | - | `plugin-sdk/provider-auth-result` | Builder padrão de resultado de autenticação OAuth | - | `plugin-sdk/provider-auth-login` | Helpers compartilhados de login interativo para plugins de provedor | - | `plugin-sdk/provider-env-vars` | Helpers de busca de variáveis de ambiente para autenticação de provedor | + | `plugin-sdk/provider-setup` | Auxiliares curados de configuração de provedor local/self-hosted | + | `plugin-sdk/self-hosted-provider-setup` | Auxiliares focados de configuração de provedor self-hosted compatível com OpenAI | + | `plugin-sdk/cli-backend` | Padrões de backend da CLI + constantes de watchdog | + | `plugin-sdk/provider-auth-runtime` | Auxiliares de runtime para resolução de chave de API para plugins de provedor | + | `plugin-sdk/provider-auth-api-key` | Auxiliares de onboarding/gravação de perfil de chave de API, como `upsertApiKeyProfile` | + | `plugin-sdk/provider-auth-result` | Construtor padrão de resultado de autenticação OAuth | + | `plugin-sdk/provider-auth-login` | Auxiliares compartilhados de login interativo para plugins de provedor | + | `plugin-sdk/provider-env-vars` | Auxiliares de busca de variáveis de ambiente de autenticação do provedor | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, builders compartilhados de política de replay, helpers de endpoint de provedor e helpers de normalização de model-id, como `normalizeNativeXaiModelId` | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, construtores compartilhados de política de replay, auxiliares de endpoint do provedor e auxiliares de normalização de ID de modelo, como `normalizeNativeXaiModelId` | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-http` | Helpers genéricos de capacidade HTTP/endpoint de provedor | - | `plugin-sdk/provider-web-fetch-contract` | Helpers estreitos de contrato de configuração/seleção de web-fetch, como `enablePluginInConfig` e `WebFetchProviderPlugin` | - | `plugin-sdk/provider-web-fetch` | Helpers de registro/cache de provedor web-fetch | - | `plugin-sdk/provider-web-search-config-contract` | Helpers estreitos de configuração/credenciais de web-search para provedores que não precisam de wiring de ativação de plugin | - | `plugin-sdk/provider-web-search-contract` | Helpers estreitos de contrato de configuração/credenciais de web-search, como `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` e setters/getters de credenciais com escopo | - | `plugin-sdk/provider-web-search` | Helpers de registro/cache/runtime de provedor web-search | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, limpeza + diagnósticos de schema Gemini e helpers de compatibilidade xAI, como `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-http` | Auxiliares genéricos de HTTP/capacidade de endpoint do provedor | + | `plugin-sdk/provider-web-fetch-contract` | Auxiliares restritos de contrato de configuração/seleção de web-fetch, como `enablePluginInConfig` e `WebFetchProviderPlugin` | + | `plugin-sdk/provider-web-fetch` | Auxiliares de registro/cache de provedor web-fetch | + | `plugin-sdk/provider-web-search-config-contract` | Auxiliares restritos de configuração/credencial de web-search para provedores que não precisam de ligação de ativação de plugin | + | `plugin-sdk/provider-web-search-contract` | Auxiliares restritos de contrato de configuração/credencial de web-search, como `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` e setters/getters de credenciais com escopo | + | `plugin-sdk/provider-web-search` | Auxiliares de runtime/registro/cache de provedor web-search | + | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, limpeza + diagnóstico de esquema Gemini e auxiliares de compatibilidade xAI, como `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | | `plugin-sdk/provider-usage` | `fetchClaudeUsage` e similares | - | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipos de wrapper de stream e helpers compartilhados de wrapper Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/provider-onboard` | Helpers de patch de configuração de onboarding | - | `plugin-sdk/global-singleton` | Helpers de singleton/map/cache local ao processo | + | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipos de wrapper de stream e auxiliares compartilhados de wrapper para Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/provider-onboard` | Auxiliares de patch de configuração de onboarding | + | `plugin-sdk/global-singleton` | Auxiliares de singleton/mapa/cache local ao processo | - | Subcaminho | Exportações principais | + | Subcaminho | Principais exportações | | --- | --- | - | `plugin-sdk/command-auth` | `resolveControlCommandGate`, helpers de registro de comandos, helpers de autorização do remetente | - | `plugin-sdk/command-status` | Builders de mensagens de comando/ajuda, como `buildCommandsMessagePaginated` e `buildHelpMessage` | - | `plugin-sdk/approval-auth-runtime` | Helpers de resolução de aprovador e autenticação de ação no mesmo chat | - | `plugin-sdk/approval-client-runtime` | Helpers de perfil/filtro de aprovação de execução nativa | - | `plugin-sdk/approval-delivery-runtime` | Adapters de capacidade/entrega de aprovação nativa | - | `plugin-sdk/approval-gateway-runtime` | Helper compartilhado de resolução de gateway de aprovação | - | `plugin-sdk/approval-handler-adapter-runtime` | Helpers leves de carregamento de adapter de aprovação nativa para entrypoints quentes de canal | - | `plugin-sdk/approval-handler-runtime` | Helpers mais amplos de runtime para handler de aprovação; prefira os seams mais estreitos de adapter/gateway quando forem suficientes | - | `plugin-sdk/approval-native-runtime` | Helpers nativos de alvo de aprovação + binding de conta | - | `plugin-sdk/approval-reply-runtime` | Helpers de payload de resposta de aprovação de execução/plugin | - | `plugin-sdk/command-auth-native` | Helpers nativos de autenticação de comando + helpers nativos de alvo de sessão | - | `plugin-sdk/command-detection` | Helpers compartilhados de detecção de comando | - | `plugin-sdk/command-surface` | Helpers de normalização de corpo de comando e de superfície de comando | + | `plugin-sdk/command-auth` | `resolveControlCommandGate`, auxiliares de registro de comandos, auxiliares de autorização do remetente | + | `plugin-sdk/command-status` | Construtores de mensagem de comando/ajuda, como `buildCommandsMessagePaginated` e `buildHelpMessage` | + | `plugin-sdk/approval-auth-runtime` | Resolução de aprovador e auxiliares de autenticação de ação no mesmo chat | + | `plugin-sdk/approval-client-runtime` | Auxiliares de perfil/filtro de aprovação para execução nativa | + | `plugin-sdk/approval-delivery-runtime` | Adaptadores nativos de capacidade/entrega de aprovação | + | `plugin-sdk/approval-gateway-runtime` | Auxiliar compartilhado de resolução de Gateway de aprovação | + | `plugin-sdk/approval-handler-adapter-runtime` | Auxiliares leves de carregamento de adaptador de aprovação nativa para entrypoints de canal de hot path | + | `plugin-sdk/approval-handler-runtime` | Auxiliares mais amplos de runtime do manipulador de aprovação; prefira os seams mais restritos de adaptador/Gateway quando forem suficientes | + | `plugin-sdk/approval-native-runtime` | Auxiliares nativos de alvo de aprovação + vínculo de conta | + | `plugin-sdk/approval-reply-runtime` | Auxiliares de payload de resposta de aprovação de execução/plugin | + | `plugin-sdk/command-auth-native` | Auxiliares nativos de autenticação de comando + alvo de sessão nativa | + | `plugin-sdk/command-detection` | Auxiliares compartilhados de detecção de comandos | + | `plugin-sdk/command-surface` | Auxiliares de normalização de corpo de comando e superfície de comando | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | Helpers estreitos de coleta de contrato de segredo para superfícies de segredo de canal/plugin | - | `plugin-sdk/secret-ref-runtime` | Helpers estreitos de `coerceSecretRef` e tipagem de SecretRef para parsing de contrato/configuração de segredo | - | `plugin-sdk/security-runtime` | Helpers compartilhados de confiança, bloqueio de DM, conteúdo externo e coleta de segredo | - | `plugin-sdk/ssrf-policy` | Helpers de política SSRF para allowlist de host e rede privada | - | `plugin-sdk/ssrf-runtime` | Helpers de dispatcher fixado, fetch protegido por SSRF e política SSRF | - | `plugin-sdk/secret-input` | Helpers de parsing de entrada de segredo | - | `plugin-sdk/webhook-ingress` | Helpers de requisição/alvo de webhook | - | `plugin-sdk/webhook-request-guards` | Helpers de tamanho do corpo da requisição/timeout | + | `plugin-sdk/channel-secret-runtime` | Auxiliares restritos de coleta de contrato de segredo para superfícies de segredo de canal/plugin | + | `plugin-sdk/secret-ref-runtime` | Auxiliares restritos de tipagem de `coerceSecretRef` e SecretRef para parsing de contrato/configuração de segredo | + | `plugin-sdk/security-runtime` | Auxiliares compartilhados de confiança, controle de DM, conteúdo externo e coleta de segredos | + | `plugin-sdk/ssrf-policy` | Auxiliares de allowlist de host e política de SSRF para rede privada | + | `plugin-sdk/ssrf-runtime` | Auxiliares de dispatcher fixado, fetch protegido contra SSRF e política de SSRF | + | `plugin-sdk/secret-input` | Auxiliares de parsing de entrada de segredo | + | `plugin-sdk/webhook-ingress` | Auxiliares de requisição/alvo de Webhook | + | `plugin-sdk/webhook-request-guards` | Auxiliares de tamanho do corpo/timeout da requisição | - | Subcaminho | Exportações principais | + | Subcaminho | Principais exportações | | --- | --- | - | `plugin-sdk/runtime` | Helpers amplos de runtime/logging/backup/instalação de plugin | - | `plugin-sdk/runtime-env` | Helpers estreitos de env de runtime, logger, timeout, retry e backoff | - | `plugin-sdk/channel-runtime-context` | Helpers genéricos de registro e busca de contexto de runtime de canal | + | `plugin-sdk/runtime` | Auxiliares amplos de runtime/logging/backup/instalação de plugin | + | `plugin-sdk/runtime-env` | Auxiliares restritos de ambiente de runtime, logger, timeout, retry e backoff | + | `plugin-sdk/channel-runtime-context` | Auxiliares genéricos de registro e busca de contexto de runtime de canal | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | - | `plugin-sdk/plugin-runtime` | Helpers compartilhados de comando/hook/http/interativo de plugin | - | `plugin-sdk/hook-runtime` | Helpers compartilhados de pipeline de webhook/hook interno | - | `plugin-sdk/lazy-runtime` | Helpers de importação/binding lazy de runtime, como `createLazyRuntimeModule`, `createLazyRuntimeMethod` e `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | Helpers de execução de processo | - | `plugin-sdk/cli-runtime` | Helpers de formatação, espera e versão da CLI | - | `plugin-sdk/gateway-runtime` | Helpers de cliente do Gateway e patch de status de canal | - | `plugin-sdk/config-runtime` | Helpers de carregamento/escrita de configuração | + | `plugin-sdk/plugin-runtime` | Auxiliares compartilhados de comando/hook/http/interativo de plugin | + | `plugin-sdk/hook-runtime` | Auxiliares compartilhados de pipeline de Webhook/hook interno | + | `plugin-sdk/lazy-runtime` | Auxiliares de importação/vínculo lazy de runtime, como `createLazyRuntimeModule`, `createLazyRuntimeMethod` e `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | Auxiliares de execução de processo | + | `plugin-sdk/cli-runtime` | Auxiliares de formatação, espera e versão da CLI | + | `plugin-sdk/gateway-runtime` | Auxiliares de cliente Gateway e patch de status de canal | + | `plugin-sdk/config-runtime` | Auxiliares de carregamento/gravação de configuração | | `plugin-sdk/telegram-command-config` | Normalização de nome/descrição de comando do Telegram e verificações de duplicidade/conflito, mesmo quando a superfície de contrato empacotada do Telegram não está disponível | - | `plugin-sdk/approval-runtime` | Helpers de aprovação de execução/plugin, builders de capacidade de aprovação, helpers de autenticação/perfil, helpers nativos de roteamento/runtime | - | `plugin-sdk/reply-runtime` | Helpers compartilhados de runtime de entrada/resposta, chunking, dispatch, heartbeat, planejador de resposta | - | `plugin-sdk/reply-dispatch-runtime` | Helpers estreitos de dispatch/finalização de resposta | - | `plugin-sdk/reply-history` | Helpers compartilhados de histórico de resposta em janela curta, como `buildHistoryContext`, `recordPendingHistoryEntry` e `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/approval-runtime` | Auxiliares de aprovação de execução/plugin, construtores de capacidade de aprovação, auxiliares de autenticação/perfil, auxiliares nativos de roteamento/runtime | + | `plugin-sdk/reply-runtime` | Auxiliares compartilhados de runtime de entrada/resposta, fragmentação, despacho, Heartbeat, planejador de resposta | + | `plugin-sdk/reply-dispatch-runtime` | Auxiliares restritos de despacho/finalização de resposta | + | `plugin-sdk/reply-history` | Auxiliares compartilhados de histórico de respostas de janela curta, como `buildHistoryContext`, `recordPendingHistoryEntry` e `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | Helpers estreitos de chunking de texto/Markdown | - | `plugin-sdk/session-store-runtime` | Helpers de caminho do armazenamento de sessão + updated-at | - | `plugin-sdk/state-paths` | Helpers de caminho de diretório de estado/OAuth | - | `plugin-sdk/routing` | Helpers de binding de rota/chave de sessão/conta, como `resolveAgentRoute`, `buildAgentSessionKey` e `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | Helpers compartilhados de resumo de status de canal/conta, padrões de estado de runtime e helpers de metadados de problema | - | `plugin-sdk/target-resolver-runtime` | Helpers compartilhados de resolvedor de alvo | - | `plugin-sdk/string-normalization-runtime` | Helpers de normalização de slug/string | - | `plugin-sdk/request-url` | Extrai URLs string de entradas do tipo fetch/request | - | `plugin-sdk/run-command` | Executor de comando com tempo controlado e resultados normalizados de stdout/stderr | + | `plugin-sdk/reply-chunking` | Auxiliares restritos de fragmentação de texto/markdown | + | `plugin-sdk/session-store-runtime` | Auxiliares de caminho da store de sessão + updated-at | + | `plugin-sdk/state-paths` | Auxiliares de caminho de diretório de estado/OAuth | + | `plugin-sdk/routing` | Auxiliares de roteamento/chave de sessão/vínculo de conta, como `resolveAgentRoute`, `buildAgentSessionKey` e `resolveDefaultAgentBoundAccountId` | + | `plugin-sdk/status-helpers` | Auxiliares compartilhados de resumo de status de canal/conta, padrões de estado de runtime e auxiliares de metadados de problema | + | `plugin-sdk/target-resolver-runtime` | Auxiliares compartilhados de resolvedor de alvo | + | `plugin-sdk/string-normalization-runtime` | Auxiliares de normalização de slug/string | + | `plugin-sdk/request-url` | Extrair URLs em string de entradas do tipo fetch/request | + | `plugin-sdk/run-command` | Executor de comandos com tempo controlado e resultados normalizados de stdout/stderr | | `plugin-sdk/param-readers` | Leitores comuns de parâmetros de ferramenta/CLI | - | `plugin-sdk/tool-payload` | Extrai payloads normalizados de objetos de resultado de ferramenta | - | `plugin-sdk/tool-send` | Extrai campos canônicos de alvo de envio de argumentos de ferramenta | - | `plugin-sdk/temp-path` | Helpers compartilhados de caminho temporário para download | - | `plugin-sdk/logging-core` | Helpers de logger de subsistema e de redação | - | `plugin-sdk/markdown-table-runtime` | Helpers de modo de tabela Markdown | - | `plugin-sdk/json-store` | Pequenos helpers de leitura/escrita de estado JSON | - | `plugin-sdk/file-lock` | Helpers de file-lock reentrante | - | `plugin-sdk/persistent-dedupe` | Helpers de cache de deduplicação persistente em disco | - | `plugin-sdk/acp-runtime` | Helpers de runtime/sessão ACP e dispatch de resposta | - | `plugin-sdk/agent-config-primitives` | Primitivos estreitos de schema de configuração de runtime de agente | + | `plugin-sdk/tool-payload` | Extrair payloads normalizados de objetos de resultado de ferramenta | + | `plugin-sdk/tool-send` | Extrair campos canônicos de alvo de envio de argumentos de ferramenta | + | `plugin-sdk/temp-path` | Auxiliares compartilhados de caminho temporário para download | + | `plugin-sdk/logging-core` | Auxiliares de logger de subsistema e redação | + | `plugin-sdk/markdown-table-runtime` | Auxiliares de modo de tabela em Markdown | + | `plugin-sdk/json-store` | Pequenos auxiliares de leitura/gravação de estado JSON | + | `plugin-sdk/file-lock` | Auxiliares de file lock reentrante | + | `plugin-sdk/persistent-dedupe` | Auxiliares de cache de deduplicação com persistência em disco | + | `plugin-sdk/acp-runtime` | Auxiliares de runtime/sessão do ACP e despacho de resposta | + | `plugin-sdk/agent-config-primitives` | Primitivas restritas de esquema de configuração de runtime de agente | | `plugin-sdk/boolean-param` | Leitor flexível de parâmetro booleano | - | `plugin-sdk/dangerous-name-runtime` | Helpers de resolução de correspondência de nome perigoso | - | `plugin-sdk/device-bootstrap` | Helpers de bootstrap de dispositivo e token de pairing | - | `plugin-sdk/extension-shared` | Primitivos auxiliares compartilhados de canal passivo, status e proxy ambiente | - | `plugin-sdk/models-provider-runtime` | Helpers de resposta de provedor/comando `/models` | - | `plugin-sdk/skill-commands-runtime` | Helpers de listagem de comandos de Skills | - | `plugin-sdk/native-command-registry` | Helpers de registro/build/serialização de comando nativo | - | `plugin-sdk/agent-harness` | Superfície experimental de plugin confiável para harnesses de agente de baixo nível: tipos de harness, helpers de condução/aborto de execução ativa, bridge de ferramentas do OpenClaw e utilitários de resultado de tentativa | - | `plugin-sdk/provider-zai-endpoint` | Helpers de detecção de endpoint Z.A.I | - | `plugin-sdk/infra-runtime` | Helpers de evento do sistema/heartbeat | - | `plugin-sdk/collection-runtime` | Pequenos helpers de cache limitado | - | `plugin-sdk/diagnostic-runtime` | Helpers de flag e evento de diagnóstico | - | `plugin-sdk/error-runtime` | Grafo de erros, formatação, helpers compartilhados de classificação de erros, `isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | Helpers de fetch encapsulado, proxy e busca fixada | - | `plugin-sdk/host-runtime` | Helpers de normalização de hostname e host SCP | - | `plugin-sdk/retry-runtime` | Helpers de configuração e executor de retry | - | `plugin-sdk/agent-runtime` | Helpers de diretório/identidade/workspace de agente | + | `plugin-sdk/dangerous-name-runtime` | Auxiliares de resolução de correspondência de nomes perigosos | + | `plugin-sdk/device-bootstrap` | Auxiliares de bootstrap de dispositivo e token de pareamento | + | `plugin-sdk/extension-shared` | Primitivas auxiliares compartilhadas de canal passivo, status e proxy ambiente | + | `plugin-sdk/models-provider-runtime` | Auxiliares de resposta de provedor/comando `/models` | + | `plugin-sdk/skill-commands-runtime` | Auxiliares de listagem de comandos de Skills | + | `plugin-sdk/native-command-registry` | Auxiliares de registro/construção/serialização de comandos nativos | + | `plugin-sdk/agent-harness` | Superfície experimental de plugin confiável para harnesses de agente de baixo nível: tipos de harness, auxiliares de condução/aborto de execução ativa, auxiliares de ponte de ferramenta do OpenClaw e utilitários de resultado de tentativa | + | `plugin-sdk/provider-zai-endpoint` | Auxiliares de detecção de endpoint do Z.A.I | + | `plugin-sdk/infra-runtime` | Auxiliares de evento do sistema/Heartbeat | + | `plugin-sdk/collection-runtime` | Pequenos auxiliares de cache limitado | + | `plugin-sdk/diagnostic-runtime` | Auxiliares de flag e evento de diagnóstico | + | `plugin-sdk/error-runtime` | Grafo de erros, formatação, auxiliares compartilhados de classificação de erros, `isApprovalNotFoundError` | + | `plugin-sdk/fetch-runtime` | Auxiliares de fetch encapsulado, proxy e busca fixada | + | `plugin-sdk/host-runtime` | Auxiliares de normalização de hostname e host SCP | + | `plugin-sdk/retry-runtime` | Auxiliares de configuração de retry e executor de retry | + | `plugin-sdk/agent-runtime` | Auxiliares de diretório/identidade/workspace de agente | | `plugin-sdk/directory-runtime` | Consulta/deduplicação de diretório com base em configuração | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | - - | Subcaminho | Exportações principais | + + | Subcaminho | Principais exportações | | --- | --- | - | `plugin-sdk/media-runtime` | Helpers compartilhados de busca/transformação/armazenamento de mídia, além de builders de payload de mídia | - | `plugin-sdk/media-generation-runtime` | Helpers compartilhados de failover de geração de mídia, seleção de candidatos e mensagens de modelo ausente | - | `plugin-sdk/media-understanding` | Tipos de provedor de interpretação de mídia, além de exportações de helpers de imagem/áudio voltadas a provedores | - | `plugin-sdk/text-runtime` | Helpers compartilhados de texto/Markdown/logging, como remoção de texto visível ao assistente, helpers de renderização/chunking/tabela em Markdown, helpers de redação, helpers de tag de diretiva e utilitários de texto seguro | - | `plugin-sdk/text-chunking` | Helper de chunking de texto de saída | - | `plugin-sdk/speech` | Tipos de provedor de fala, além de helpers voltados a provedores para diretiva, registro e validação | - | `plugin-sdk/speech-core` | Tipos compartilhados de provedor de fala, helpers de registro, diretiva e normalização | - | `plugin-sdk/realtime-transcription` | Tipos de provedor de transcrição em tempo real e helpers de registro | - | `plugin-sdk/realtime-voice` | Tipos de provedor de voz em tempo real e helpers de registro | + | `plugin-sdk/media-runtime` | Auxiliares compartilhados de busca/transformação/armazenamento de mídia, além de construtores de payload de mídia | + | `plugin-sdk/media-generation-runtime` | Auxiliares compartilhados de failover de geração de mídia, seleção de candidatos e mensagens para modelo ausente | + | `plugin-sdk/media-understanding` | Tipos de provedor de entendimento de mídia, além de exportações auxiliares voltadas ao provedor para imagem/áudio | + | `plugin-sdk/text-runtime` | Auxiliares compartilhados de texto/markdown/logging, como remoção de texto visível ao assistente, auxiliares de renderização/fragmentação/tabela em markdown, auxiliares de redação, auxiliares de tag de diretiva e utilitários de texto seguro | + | `plugin-sdk/text-chunking` | Auxiliar de fragmentação de texto de saída | + | `plugin-sdk/speech` | Tipos de provedor de fala, além de auxiliares voltados ao provedor para diretiva, registro e validação | + | `plugin-sdk/speech-core` | Tipos compartilhados de provedor de fala, auxiliares de registro, diretiva e normalização | + | `plugin-sdk/realtime-transcription` | Tipos de provedor de transcrição em tempo real e auxiliares de registro | + | `plugin-sdk/realtime-voice` | Tipos de provedor de voz em tempo real e auxiliares de registro | | `plugin-sdk/image-generation` | Tipos de provedor de geração de imagem | - | `plugin-sdk/image-generation-core` | Tipos compartilhados de geração de imagem, helpers de failover, autenticação e registro | + | `plugin-sdk/image-generation-core` | Tipos compartilhados de geração de imagem, auxiliares de failover, autenticação e registro | | `plugin-sdk/music-generation` | Tipos de provedor/requisição/resultado de geração de música | - | `plugin-sdk/music-generation-core` | Tipos compartilhados de geração de música, helpers de failover, busca de provedor e parsing de model-ref | + | `plugin-sdk/music-generation-core` | Tipos compartilhados de geração de música, auxiliares de failover, busca de provedor e parsing de referência de modelo | | `plugin-sdk/video-generation` | Tipos de provedor/requisição/resultado de geração de vídeo | - | `plugin-sdk/video-generation-core` | Tipos compartilhados de geração de vídeo, helpers de failover, busca de provedor e parsing de model-ref | - | `plugin-sdk/webhook-targets` | Registro de alvos de webhook e helpers de instalação de rota | - | `plugin-sdk/webhook-path` | Helpers de normalização de caminho de webhook | - | `plugin-sdk/web-media` | Helpers compartilhados de carregamento de mídia remota/local | - | `plugin-sdk/zod` | `zod` reexportado para consumidores do SDK de plugins | + | `plugin-sdk/video-generation-core` | Tipos compartilhados de geração de vídeo, auxiliares de failover, busca de provedor e parsing de referência de modelo | + | `plugin-sdk/webhook-targets` | Registro de alvos de Webhook e auxiliares de instalação de rota | + | `plugin-sdk/webhook-path` | Auxiliares de normalização de caminho de Webhook | + | `plugin-sdk/web-media` | Auxiliares compartilhados de carregamento de mídia remota/local | + | `plugin-sdk/zod` | `zod` reexportado para consumidores do Plugin SDK | | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` | - | Subcaminho | Exportações principais | + | Subcaminho | Principais exportações | | --- | --- | - | `plugin-sdk/memory-core` | Superfície auxiliar empacotada de memory-core para helpers de manager/configuração/arquivo/CLI | + | `plugin-sdk/memory-core` | Superfície auxiliar empacotada de memory-core para auxiliares de manager/configuração/arquivo/CLI | | `plugin-sdk/memory-core-engine-runtime` | Fachada de runtime de índice/busca de memória | - | `plugin-sdk/memory-core-host-engine-foundation` | Exportações do motor de fundação do host de memória | - | `plugin-sdk/memory-core-host-engine-embeddings` | Exportações do motor de embeddings do host de memória | - | `plugin-sdk/memory-core-host-engine-qmd` | Exportações do motor QMD do host de memória | - | `plugin-sdk/memory-core-host-engine-storage` | Exportações do motor de armazenamento do host de memória | - | `plugin-sdk/memory-core-host-multimodal` | Helpers multimodais do host de memória | - | `plugin-sdk/memory-core-host-query` | Helpers de consulta do host de memória | - | `plugin-sdk/memory-core-host-secret` | Helpers de segredo do host de memória | - | `plugin-sdk/memory-core-host-events` | Helpers de journal de eventos do host de memória | - | `plugin-sdk/memory-core-host-status` | Helpers de status do host de memória | - | `plugin-sdk/memory-core-host-runtime-cli` | Helpers de runtime de CLI do host de memória | - | `plugin-sdk/memory-core-host-runtime-core` | Helpers de runtime core do host de memória | - | `plugin-sdk/memory-core-host-runtime-files` | Helpers de arquivo/runtime do host de memória | - | `plugin-sdk/memory-host-core` | Alias neutro em relação ao fornecedor para helpers de runtime core do host de memória | - | `plugin-sdk/memory-host-events` | Alias neutro em relação ao fornecedor para helpers de journal de eventos do host de memória | - | `plugin-sdk/memory-host-files` | Alias neutro em relação ao fornecedor para helpers de arquivo/runtime do host de memória | - | `plugin-sdk/memory-host-markdown` | Helpers compartilhados de Markdown gerenciado para plugins adjacentes à memória | - | `plugin-sdk/memory-host-search` | Fachada de runtime de memória ativa para acesso ao search-manager | - | `plugin-sdk/memory-host-status` | Alias neutro em relação ao fornecedor para helpers de status do host de memória | + | `plugin-sdk/memory-core-host-engine-foundation` | Exportações do engine foundation do host de memória | + | `plugin-sdk/memory-core-host-engine-embeddings` | Contratos de embedding do host de memória, acesso ao registro, provedor local e auxiliares genéricos de lote/remoto | + | `plugin-sdk/memory-core-host-engine-qmd` | Exportações do engine QMD do host de memória | + | `plugin-sdk/memory-core-host-engine-storage` | Exportações do engine de armazenamento do host de memória | + | `plugin-sdk/memory-core-host-multimodal` | Auxiliares multimodais do host de memória | + | `plugin-sdk/memory-core-host-query` | Auxiliares de consulta do host de memória | + | `plugin-sdk/memory-core-host-secret` | Auxiliares de segredo do host de memória | + | `plugin-sdk/memory-core-host-events` | Auxiliares de journal de eventos do host de memória | + | `plugin-sdk/memory-core-host-status` | Auxiliares de status do host de memória | + | `plugin-sdk/memory-core-host-runtime-cli` | Auxiliares de runtime da CLI do host de memória | + | `plugin-sdk/memory-core-host-runtime-core` | Auxiliares centrais de runtime do host de memória | + | `plugin-sdk/memory-core-host-runtime-files` | Auxiliares de arquivo/runtime do host de memória | + | `plugin-sdk/memory-host-core` | Alias neutro em relação ao fornecedor para os auxiliares centrais de runtime do host de memória | + | `plugin-sdk/memory-host-events` | Alias neutro em relação ao fornecedor para os auxiliares de journal de eventos do host de memória | + | `plugin-sdk/memory-host-files` | Alias neutro em relação ao fornecedor para os auxiliares de arquivo/runtime do host de memória | + | `plugin-sdk/memory-host-markdown` | Auxiliares compartilhados de managed-markdown para plugins adjacentes à memória | + | `plugin-sdk/memory-host-search` | Fachada de runtime de Active Memory para acesso ao gerenciador de busca | + | `plugin-sdk/memory-host-status` | Alias neutro em relação ao fornecedor para os auxiliares de status do host de memória | | `plugin-sdk/memory-lancedb` | Superfície auxiliar empacotada de memory-lancedb | - + | Família | Subcaminhos atuais | Uso pretendido | | --- | --- | --- | - | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Helpers de suporte do plugin Browser empacotado (`browser-support` continua sendo o barrel de compatibilidade) | - | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Superfície de helper/runtime do Matrix empacotado | - | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Superfície de helper/runtime do LINE empacotado | - | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Superfície de helper do IRC empacotado | - | Helpers específicos de canal | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Seams de compatibilidade/helper de canais empacotados | - | Helpers específicos de autenticação/plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Seams de helper de recurso/plugin empacotado; `plugin-sdk/github-copilot-token` atualmente exporta `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` e `resolveCopilotApiToken` | + | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Auxiliares de suporte do Plugin de navegador empacotado (`browser-support` continua sendo o barrel de compatibilidade) | + | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Superfície auxiliar/runtime empacotada do Matrix | + | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Superfície auxiliar/runtime empacotada do LINE | + | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Superfície auxiliar empacotada do IRC | + | Auxiliares específicos de canal | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Seams de compatibilidade/auxiliares de canais empacotados | + | Auxiliares específicos de autenticação/plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Seams auxiliares de recursos/plugins empacotados; `plugin-sdk/github-copilot-token` atualmente exporta `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` e `resolveCopilotApiToken` | @@ -308,58 +308,58 @@ promova explicitamente algum deles como público. O callback `register(api)` recebe um objeto `OpenClawPluginApi` com estes métodos: -### Registro de capacidade +### Registro de capacidades -| Método | O que ele registra | -| ------------------------------------------------ | ------------------------------------- | -| `api.registerProvider(...)` | Inferência de texto (LLM) | +| Método | O que ele registra | +| ------------------------------------------------ | ----------------------------------- | +| `api.registerProvider(...)` | Inferência de texto (LLM) | | `api.registerAgentHarness(...)` | Executor experimental de agente de baixo nível | -| `api.registerCliBackend(...)` | Backend local de inferência por CLI | -| `api.registerChannel(...)` | Canal de mensagens | -| `api.registerSpeechProvider(...)` | Síntese de texto para fala / STT | +| `api.registerCliBackend(...)` | Backend de inferência local da CLI | +| `api.registerChannel(...)` | Canal de mensagens | +| `api.registerSpeechProvider(...)` | Síntese de texto para fala / STT | | `api.registerRealtimeTranscriptionProvider(...)` | Transcrição em tempo real por streaming | -| `api.registerRealtimeVoiceProvider(...)` | Sessões duplex de voz em tempo real | -| `api.registerMediaUnderstandingProvider(...)` | Análise de imagem/áudio/vídeo | -| `api.registerImageGenerationProvider(...)` | Geração de imagem | -| `api.registerMusicGenerationProvider(...)` | Geração de música | -| `api.registerVideoGenerationProvider(...)` | Geração de vídeo | -| `api.registerWebFetchProvider(...)` | Provedor de busca/coleta da web | -| `api.registerWebSearchProvider(...)` | Busca na web | +| `api.registerRealtimeVoiceProvider(...)` | Sessões de voz duplex em tempo real | +| `api.registerMediaUnderstandingProvider(...)` | Análise de imagem/áudio/vídeo | +| `api.registerImageGenerationProvider(...)` | Geração de imagem | +| `api.registerMusicGenerationProvider(...)` | Geração de música | +| `api.registerVideoGenerationProvider(...)` | Geração de vídeo | +| `api.registerWebFetchProvider(...)` | Provedor de busca/scrape da web | +| `api.registerWebSearchProvider(...)` | Busca na web | ### Ferramentas e comandos -| Método | O que ele registra | -| ------------------------------- | --------------------------------------------- | +| Método | O que ele registra | +| ------------------------------- | -------------------------------------------- | | `api.registerTool(tool, opts?)` | Ferramenta do agente (obrigatória ou `{ optional: true }`) | -| `api.registerCommand(def)` | Comando personalizado (ignora o LLM) | +| `api.registerCommand(def)` | Comando personalizado (ignora o LLM) | ### Infraestrutura -| Método | O que ele registra | -| ---------------------------------------------- | ------------------------------------- | -| `api.registerHook(events, handler, opts?)` | Hook de evento | -| `api.registerHttpRoute(params)` | Endpoint HTTP do Gateway | -| `api.registerGatewayMethod(name, handler)` | Método RPC do Gateway | -| `api.registerCli(registrar, opts?)` | Subcomando da CLI | -| `api.registerService(service)` | Serviço em segundo plano | -| `api.registerInteractiveHandler(registration)` | Handler interativo | +| Método | O que ele registra | +| ---------------------------------------------- | -------------------------------------- | +| `api.registerHook(events, handler, opts?)` | Hook de evento | +| `api.registerHttpRoute(params)` | Endpoint HTTP do Gateway | +| `api.registerGatewayMethod(name, handler)` | Método RPC do Gateway | +| `api.registerCli(registrar, opts?)` | Subcomando da CLI | +| `api.registerService(service)` | Serviço em segundo plano | +| `api.registerInteractiveHandler(registration)` | Manipulador interativo | | `api.registerMemoryPromptSupplement(builder)` | Seção de prompt aditiva adjacente à memória | | `api.registerMemoryCorpusSupplement(adapter)` | Corpus aditivo de busca/leitura de memória | -Namespaces administrativos reservados do core (`config.*`, `exec.approvals.*`, `wizard.*`, +Namespaces administrativos reservados do núcleo (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) sempre permanecem `operator.admin`, mesmo que um plugin tente atribuir um -escopo de método de gateway mais restrito. Prefira prefixos específicos do plugin para +escopo mais restrito ao método do Gateway. Prefira prefixos específicos do plugin para métodos pertencentes ao plugin. ### Metadados de registro da CLI `api.registerCli(registrar, opts?)` aceita dois tipos de metadados de nível superior: -- `commands`: raízes explícitas de comando pertencentes ao registrador +- `commands`: raízes de comando explícitas pertencentes ao registrador - `descriptors`: descritores de comando em tempo de parsing usados para ajuda da CLI raiz, roteamento e registro lazy da CLI do plugin -Se você quiser que um comando do plugin permaneça com carregamento lazy no caminho normal da CLI raiz, +Se você quiser que um comando de plugin permaneça com carregamento lazy no caminho normal da CLI raiz, forneça `descriptors` que cubram toda raiz de comando de nível superior exposta por esse registrador. @@ -373,7 +373,7 @@ api.registerCli( descriptors: [ { name: "matrix", - description: "Gerencie contas, verificação, dispositivos e estado de perfil do Matrix", + description: "Gerencie contas do Matrix, verificação, dispositivos e estado do perfil", hasSubcommands: true, }, ], @@ -382,124 +382,124 @@ api.registerCli( ``` Use `commands` sozinho apenas quando você não precisar de registro lazy na CLI raiz. -Esse caminho de compatibilidade eager continua compatível, mas não instala -placeholders com suporte a descritor para carregamento lazy em tempo de parsing. +Esse caminho de compatibilidade eager continua sendo compatível, mas não instala +placeholders com suporte de descritor para carregamento lazy em tempo de parsing. ### Registro de backend da CLI -`api.registerCliBackend(...)` permite que um plugin seja responsável pela configuração padrão de um backend -local de CLI de IA, como `codex-cli`. +`api.registerCliBackend(...)` permite que um plugin seja o dono da configuração padrão de um +backend local de CLI de IA, como `codex-cli`. -- O `id` do backend se torna o prefixo do provedor em refs de modelo como `codex-cli/gpt-5`. -- O `config` do backend usa o mesmo formato de `agents.defaults.cliBackends.`. -- A configuração do usuário ainda prevalece. O OpenClaw mescla `agents.defaults.cliBackends.` sobre o +- O `id` do backend se torna o prefixo do provedor em referências de modelo como `codex-cli/gpt-5`. +- A `config` do backend usa o mesmo formato de `agents.defaults.cliBackends.`. +- A configuração do usuário continua tendo prioridade. O OpenClaw mescla `agents.defaults.cliBackends.` sobre o padrão do plugin antes de executar a CLI. -- Use `normalizeConfig` quando um backend precisar de regravações de compatibilidade após a mesclagem - (por exemplo, normalizar formatos antigos de flag). +- Use `normalizeConfig` quando um backend precisar de reescritas de compatibilidade após a mesclagem + (por exemplo, normalizando formatos antigos de flags). ### Slots exclusivos | Método | O que ele registra | | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `api.registerContextEngine(id, factory)` | Motor de contexto (apenas um ativo por vez). O callback `assemble()` recebe `availableTools` e `citationsMode` para que o motor possa adaptar adições ao prompt. | -| `api.registerMemoryCapability(capability)` | Capacidade unificada de memória | -| `api.registerMemoryPromptSection(builder)` | Builder de seção de prompt de memória | -| `api.registerMemoryFlushPlan(resolver)` | Resolver de plano de flush de memória | -| `api.registerMemoryRuntime(runtime)` | Adapter de runtime de memória | +| `api.registerContextEngine(id, factory)` | Mecanismo de contexto (apenas um ativo por vez). O callback `assemble()` recebe `availableTools` e `citationsMode` para que o mecanismo adapte adições ao prompt. | +| `api.registerMemoryCapability(capability)` | Capacidade de memória unificada | +| `api.registerMemoryPromptSection(builder)` | Construtor de seção de prompt de memória | +| `api.registerMemoryFlushPlan(resolver)` | Resolvedor de plano de flush de memória | +| `api.registerMemoryRuntime(runtime)` | Adaptador de runtime de memória | -### Adapters de embeddings de memória +### Adaptadores de embedding de memória -| Método | O que ele registra | -| ---------------------------------------------- | ---------------------------------------------- | -| `api.registerMemoryEmbeddingProvider(adapter)` | Adapter de embeddings de memória para o plugin ativo | +| Método | O que ele registra | +| ---------------------------------------------- | ------------------------------------------ | +| `api.registerMemoryEmbeddingProvider(adapter)` | Adaptador de embedding de memória para o Plugin ativo | -- `registerMemoryCapability` é a API preferida de plugin de memória exclusiva. +- `registerMemoryCapability` é a API exclusiva preferida para plugin de memória. - `registerMemoryCapability` também pode expor `publicArtifacts.listArtifacts(...)` para que plugins complementares consumam artefatos de memória exportados por meio de `openclaw/plugin-sdk/memory-host-core` em vez de acessar o layout privado de um plugin de memória específico. - `registerMemoryPromptSection`, `registerMemoryFlushPlan` e - `registerMemoryRuntime` são APIs exclusivas de plugin de memória compatíveis com o legado. -- `registerMemoryEmbeddingProvider` permite que o plugin de memória ativo registre um - ou mais ids de adapter de embeddings (por exemplo `openai`, `gemini` ou um id + `registerMemoryRuntime` são APIs exclusivas de plugin de memória compatíveis com versões legadas. +- `registerMemoryEmbeddingProvider` permite que o Plugin de memória ativo registre um + ou mais IDs de adaptador de embedding (por exemplo, `openai`, `gemini` ou um ID personalizado definido pelo plugin). -- A configuração do usuário, como `agents.defaults.memorySearch.provider` e - `agents.defaults.memorySearch.fallback`, é resolvida em relação a esses ids de adapter - registrados. +- Configurações do usuário como `agents.defaults.memorySearch.provider` e + `agents.defaults.memorySearch.fallback` são resolvidas com base nesses IDs de + adaptador registrados. ### Eventos e ciclo de vida -| Método | O que ele faz | -| -------------------------------------------- | --------------------------- | -| `api.on(hookName, handler, opts?)` | Hook tipado de ciclo de vida | -| `api.onConversationBindingResolved(handler)` | Callback de binding de conversa | +| Método | O que ele faz | +| -------------------------------------------- | ----------------------------- | +| `api.on(hookName, handler, opts?)` | Hook tipado de ciclo de vida | +| `api.onConversationBindingResolved(handler)` | Callback de vínculo de conversa | -### Semântica de decisão de hooks +### Semântica de decisão de hook -- `before_tool_call`: retornar `{ block: true }` é terminal. Assim que algum handler definir isso, handlers de prioridade mais baixa são ignorados. -- `before_tool_call`: retornar `{ block: false }` é tratado como nenhuma decisão (o mesmo que omitir `block`), não como uma substituição. -- `before_install`: retornar `{ block: true }` é terminal. Assim que algum handler definir isso, handlers de prioridade mais baixa são ignorados. -- `before_install`: retornar `{ block: false }` é tratado como nenhuma decisão (o mesmo que omitir `block`), não como uma substituição. -- `reply_dispatch`: retornar `{ handled: true, ... }` é terminal. Assim que algum handler assumir o dispatch, handlers de prioridade mais baixa e o caminho padrão de dispatch do modelo são ignorados. -- `message_sending`: retornar `{ cancel: true }` é terminal. Assim que algum handler definir isso, handlers de prioridade mais baixa são ignorados. -- `message_sending`: retornar `{ cancel: false }` é tratado como nenhuma decisão (o mesmo que omitir `cancel`), não como uma substituição. +- `before_tool_call`: retornar `{ block: true }` é terminal. Assim que qualquer manipulador definir isso, manipuladores de menor prioridade serão ignorados. +- `before_tool_call`: retornar `{ block: false }` é tratado como nenhuma decisão (igual a omitir `block`), não como uma substituição. +- `before_install`: retornar `{ block: true }` é terminal. Assim que qualquer manipulador definir isso, manipuladores de menor prioridade serão ignorados. +- `before_install`: retornar `{ block: false }` é tratado como nenhuma decisão (igual a omitir `block`), não como uma substituição. +- `reply_dispatch`: retornar `{ handled: true, ... }` é terminal. Assim que qualquer manipulador assumir o despacho, manipuladores de menor prioridade e o caminho padrão de despacho do modelo serão ignorados. +- `message_sending`: retornar `{ cancel: true }` é terminal. Assim que qualquer manipulador definir isso, manipuladores de menor prioridade serão ignorados. +- `message_sending`: retornar `{ cancel: false }` é tratado como nenhuma decisão (igual a omitir `cancel`), não como uma substituição. -### Campos do objeto API +### Campos do objeto da API -| Campo | Tipo | Descrição | -| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- | -| `api.id` | `string` | Id do plugin | -| `api.name` | `string` | Nome de exibição | -| `api.version` | `string?` | Versão do plugin (opcional) | -| `api.description` | `string?` | Descrição do plugin (opcional) | -| `api.source` | `string` | Caminho de origem do plugin | -| `api.rootDir` | `string?` | Diretório raiz do plugin (opcional) | -| `api.config` | `OpenClawConfig` | Snapshot de configuração atual (snapshot de runtime ativo em memória quando disponível) | -| `api.pluginConfig` | `Record` | Configuração específica do plugin em `plugins.entries..config` | -| `api.runtime` | `PluginRuntime` | [Helpers de runtime](/pt-BR/plugins/sdk-runtime) | -| `api.logger` | `PluginLogger` | Logger com escopo (`debug`, `info`, `warn`, `error`) | +| Campo | Tipo | Descrição | +| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------ | +| `api.id` | `string` | ID do plugin | +| `api.name` | `string` | Nome de exibição | +| `api.version` | `string?` | Versão do plugin (opcional) | +| `api.description` | `string?` | Descrição do plugin (opcional) | +| `api.source` | `string` | Caminho de origem do plugin | +| `api.rootDir` | `string?` | Diretório raiz do plugin (opcional) | +| `api.config` | `OpenClawConfig` | Snapshot da configuração atual (snapshot ativo em memória no runtime quando disponível) | +| `api.pluginConfig` | `Record` | Configuração específica do plugin em `plugins.entries..config` | +| `api.runtime` | `PluginRuntime` | [Auxiliares de runtime](/pt-BR/plugins/sdk-runtime) | +| `api.logger` | `PluginLogger` | Logger com escopo (`debug`, `info`, `warn`, `error`) | | `api.registrationMode` | `PluginRegistrationMode` | Modo de carregamento atual; `"setup-runtime"` é a janela leve de inicialização/configuração antes da entrada completa | -| `api.resolvePath(input)` | `(string) => string` | Resolve caminho relativo à raiz do plugin | +| `api.resolvePath(input)` | `(string) => string` | Resolve o caminho em relação à raiz do plugin | -## Convenção de módulo interno +## Convenção de módulos internos Dentro do seu plugin, use arquivos barrel locais para importações internas: ``` my-plugin/ api.ts # Exportações públicas para consumidores externos - runtime-api.ts # Exportações internas apenas de runtime + runtime-api.ts # Exportações de runtime somente internas index.ts # Ponto de entrada do plugin - setup-entry.ts # Entrada leve apenas para configuração (opcional) + setup-entry.ts # Entrada leve somente para configuração (opcional) ``` - Nunca importe seu próprio plugin por `openclaw/plugin-sdk/` - a partir de código de produção. Encaminhe importações internas por - `./api.ts` ou `./runtime-api.ts`. O caminho do SDK é apenas o contrato externo. + Nunca importe seu próprio plugin por meio de `openclaw/plugin-sdk/` + a partir de código de produção. Direcione importações internas por `./api.ts` ou + `./runtime-api.ts`. O caminho do SDK é apenas o contrato externo. Superfícies públicas de plugins empacotados carregadas por fachada (`api.ts`, `runtime-api.ts`, -`index.ts`, `setup-entry.ts` e arquivos de entrada pública semelhantes) agora preferem o -snapshot ativo de configuração de runtime quando o OpenClaw já está em execução. Se ainda não existir -snapshot de runtime, elas recorrem ao arquivo de configuração resolvido em disco. +`index.ts`, `setup-entry.ts` e arquivos públicos de entrada semelhantes) agora preferem o +snapshot ativo de configuração do runtime quando o OpenClaw já está em execução. Se ainda não existir +um snapshot de runtime, elas recorrem à configuração resolvida no arquivo em disco. -Plugins de provedor também podem expor um barrel de contrato local e estreito ao plugin quando um -helper for intencionalmente específico do provedor e ainda não pertencer a um subcaminho genérico do SDK. Exemplo -empacotado atual: o provedor Anthropic mantém seus helpers de stream Claude em seu próprio -seam público `api.ts` / `contract-api.ts` em vez de promover lógica de cabeçalho beta da Anthropic e -`service_tier` para um contrato genérico `plugin-sdk/*`. +Plugins de provedor também podem expor um barrel de contrato local e restrito ao plugin quando um +auxiliar for intencionalmente específico do provedor e ainda não pertencer a um subcaminho genérico do SDK. +Exemplo empacotado atual: o provedor Anthropic mantém seus auxiliares de stream do Claude em seu próprio +seam público `api.ts` / `contract-api.ts`, em vez de promover a lógica de cabeçalho beta do Anthropic e `service_tier` +para um contrato genérico `plugin-sdk/*`. Outros exemplos empacotados atuais: -- `@openclaw/openai-provider`: `api.ts` exporta builders de provedor, - helpers de modelo padrão e builders de provedor realtime -- `@openclaw/openrouter-provider`: `api.ts` exporta o builder de provedor mais - helpers de onboarding/configuração +- `@openclaw/openai-provider`: `api.ts` exporta construtores de provedor, + auxiliares de modelo padrão e construtores de provedor em tempo real +- `@openclaw/openrouter-provider`: `api.ts` exporta o construtor do provedor e + auxiliares de onboarding/configuração O código de produção de extensões também deve evitar importações de `openclaw/plugin-sdk/`. - Se um helper for realmente compartilhado, promova-o para um subcaminho neutro do SDK, + Se um auxiliar for realmente compartilhado, promova-o a um subcaminho neutro do SDK, como `openclaw/plugin-sdk/speech`, `.../provider-model-shared` ou outra superfície orientada por capacidade, em vez de acoplar dois plugins. @@ -507,8 +507,8 @@ Outros exemplos empacotados atuais: ## Relacionado - [Pontos de entrada](/pt-BR/plugins/sdk-entrypoints) — opções de `definePluginEntry` e `defineChannelPluginEntry` -- [Helpers de runtime](/pt-BR/plugins/sdk-runtime) — referência completa do namespace `api.runtime` -- [Configuração e setup](/pt-BR/plugins/sdk-setup) — empacotamento, manifests, schemas de configuração -- [Testing](/pt-BR/plugins/sdk-testing) — utilitários de teste e regras de lint +- [Auxiliares de runtime](/pt-BR/plugins/sdk-runtime) — referência completa do namespace `api.runtime` +- [Configuração e setup](/pt-BR/plugins/sdk-setup) — empacotamento, manifests, esquemas de configuração +- [Testes](/pt-BR/plugins/sdk-testing) — utilitários de teste e regras de lint - [Migração do SDK](/pt-BR/plugins/sdk-migration) — migração de superfícies descontinuadas -- [Internals de plugins](/pt-BR/plugins/architecture) — arquitetura profunda e modelo de capacidade +- [Internals de plugin](/pt-BR/plugins/architecture) — arquitetura detalhada e modelo de capacidade diff --git a/docs/pt-BR/tools/thinking.md b/docs/pt-BR/tools/thinking.md index 3de86c4db..e8067e052 100644 --- a/docs/pt-BR/tools/thinking.md +++ b/docs/pt-BR/tools/thinking.md @@ -1,60 +1,62 @@ --- read_when: - - Ajustando a análise ou os padrões das diretivas de thinking, modo rápido ou verbose + - Ajuste da análise, do modo rápido ou da análise detalhada na interpretação de diretivas ou nos padrões definidos summary: Sintaxe de diretivas para /think, /fast, /verbose, /trace e visibilidade do raciocínio -title: Níveis de raciocínio +title: Níveis de reflexão x-i18n: - generated_at: "2026-04-12T23:33:33Z" + generated_at: "2026-04-17T05:36:05Z" model: gpt-5.4 provider: openai - source_hash: 4f3b1341281f07ba4e9061e3355845dca234be04cc0d358594312beeb7676e68 + source_hash: 1cb44a7bf75546e5a8c3204e12f3297221449b881161d173dea4983da3921649 source_path: tools/thinking.md workflow: 15 --- -# Níveis de raciocínio (diretivas /think) +# Níveis de reflexão (diretivas /think) ## O que faz -- Diretiva inline em qualquer corpo de mensagem recebida: `/t `, `/think:` ou `/thinking `. +- Diretiva inline em qualquer corpo de mensagem recebido: `/t `, `/think:` ou `/thinking `. - Níveis (aliases): `off | minimal | low | medium | high | xhigh | adaptive` - - minimal → “think” - - low → “think hard” - - medium → “think harder” + - minimal → “pensar” + - low → “pensar bastante” + - medium → “pensar ainda mais” - high → “ultrathink” (orçamento máximo) - - xhigh → “ultrathink+” (somente modelos GPT-5.2 + Codex) - - adaptive → orçamento de raciocínio adaptativo gerenciado pelo provedor (compatível com a família de modelos Anthropic Claude 4.6) + - xhigh → “ultrathink+” (esforço GPT-5.2 + modelos Codex e Anthropic Claude Opus 4.7) + - adaptive → reflexão adaptativa gerenciada pelo provedor (compatível com Anthropic Claude 4.6 e Opus 4.7) - `x-high`, `x_high`, `extra-high`, `extra high` e `extra_high` são mapeados para `xhigh`. - `highest`, `max` são mapeados para `high`. - Observações por provedor: - - Os modelos Anthropic Claude 4.6 usam `adaptive` por padrão quando nenhum nível explícito de raciocínio é definido. - - MiniMax (`minimax/*`) no caminho de streaming compatível com Anthropic usa por padrão `thinking: { type: "disabled" }`, a menos que você defina explicitamente o raciocínio nos params do modelo ou nos params da solicitação. Isso evita vazamento de deltas `reasoning_content` do formato de stream Anthropic não nativo do MiniMax. - - Z.AI (`zai/*`) oferece suporte apenas a raciocínio binário (`on`/`off`). Qualquer nível diferente de `off` é tratado como `on` (mapeado para `low`). - - Moonshot (`moonshot/*`) mapeia `/think off` para `thinking: { type: "disabled" }` e qualquer nível diferente de `off` para `thinking: { type: "enabled" }`. Quando o raciocínio está ativado, o Moonshot aceita apenas `tool_choice` `auto|none`; o OpenClaw normaliza valores incompatíveis para `auto`. + - Modelos Anthropic Claude 4.6 usam `adaptive` por padrão quando nenhum nível de reflexão explícito é definido. + - Anthropic Claude Opus 4.7 não usa reflexão adaptativa por padrão. O padrão de esforço da API continua sendo definido pelo provedor, a menos que você defina explicitamente um nível de reflexão. + - Anthropic Claude Opus 4.7 mapeia `/think xhigh` para reflexão adaptativa mais `output_config.effort: "xhigh"`, porque `/think` é uma diretiva de reflexão e `xhigh` é a configuração de esforço do Opus 4.7. + - MiniMax (`minimax/*`) no caminho de streaming compatível com Anthropic usa `thinking: { type: "disabled" }` por padrão, a menos que você defina explicitamente a reflexão em parâmetros do modelo ou da requisição. Isso evita vazamento de deltas `reasoning_content` do formato de stream Anthropic não nativo do MiniMax. + - Z.AI (`zai/*`) oferece suporte apenas a reflexão binária (`on`/`off`). Qualquer nível diferente de `off` é tratado como `on` (mapeado para `low`). + - Moonshot (`moonshot/*`) mapeia `/think off` para `thinking: { type: "disabled" }` e qualquer nível diferente de `off` para `thinking: { type: "enabled" }`. Quando a reflexão está habilitada, o Moonshot aceita apenas `tool_choice` `auto|none`; o OpenClaw normaliza valores incompatíveis para `auto`. ## Ordem de resolução -1. Diretiva inline na mensagem (aplica-se somente a essa mensagem). +1. Diretiva inline na mensagem (aplica-se apenas àquela mensagem). 2. Substituição da sessão (definida ao enviar uma mensagem contendo apenas a diretiva). 3. Padrão por agente (`agents.list[].thinkingDefault` na configuração). 4. Padrão global (`agents.defaults.thinkingDefault` na configuração). -5. Fallback: `adaptive` para modelos Anthropic Claude 4.6, `low` para outros modelos compatíveis com raciocínio, `off` caso contrário. +5. Fallback: `adaptive` para modelos Anthropic Claude 4.6, `off` para Anthropic Claude Opus 4.7, a menos que explicitamente configurado, `low` para outros modelos com capacidade de raciocínio e `off` caso contrário. -## Definindo um padrão da sessão +## Definindo um padrão de sessão -- Envie uma mensagem que seja **somente** a diretiva (espaços em branco permitidos), por exemplo `/think:medium` ou `/t high`. -- Isso permanece na sessão atual (por padrão, por remetente); é limpo por `/think:off` ou por reset por inatividade da sessão. -- Uma resposta de confirmação é enviada (`Nível de raciocínio definido como high.` / `Raciocínio desativado.`). Se o nível for inválido (por exemplo, `/thinking big`), o comando é rejeitado com uma dica e o estado da sessão permanece inalterado. -- Envie `/think` (ou `/think:`) sem argumento para ver o nível atual de raciocínio. +- Envie uma mensagem que seja **apenas** a diretiva (espaços em branco são permitidos), por exemplo `/think:medium` ou `/t high`. +- Isso permanece na sessão atual (por remetente, por padrão); é limpo por `/think:off` ou pela redefinição por inatividade da sessão. +- Uma resposta de confirmação é enviada (`Thinking level set to high.` / `Thinking disabled.`). Se o nível for inválido (por exemplo `/thinking big`), o comando é rejeitado com uma dica e o estado da sessão permanece inalterado. +- Envie `/think` (ou `/think:`) sem argumento para ver o nível de reflexão atual. ## Aplicação por agente -- **Embedded Pi**: o nível resolvido é passado para o runtime do agente Pi em processo. +- **Pi incorporado**: o nível resolvido é passado para o runtime do agente Pi em processo. ## Modo rápido (/fast) - Níveis: `on|off`. -- Uma mensagem contendo apenas a diretiva alterna uma substituição de modo rápido da sessão e responde `Modo rápido ativado.` / `Modo rápido desativado.`. +- Uma mensagem contendo apenas a diretiva alterna uma substituição do modo rápido na sessão e responde com `Fast mode enabled.` / `Fast mode disabled.`. - Envie `/fast` (ou `/fast status`) sem modo para ver o estado efetivo atual do modo rápido. - O OpenClaw resolve o modo rápido nesta ordem: 1. `/fast on|off` inline/somente diretiva @@ -62,41 +64,41 @@ x-i18n: 3. Padrão por agente (`agents.list[].fastModeDefault`) 4. Configuração por modelo: `agents.defaults.models["/"].params.fastMode` 5. Fallback: `off` -- Para `openai/*`, o modo rápido é mapeado para processamento prioritário da OpenAI, enviando `service_tier=priority` em solicitações Responses compatíveis. -- Para `openai-codex/*`, o modo rápido envia o mesmo sinalizador `service_tier=priority` em Responses do Codex. O OpenClaw mantém uma única alternância compartilhada `/fast` para ambos os caminhos de auth. -- Para solicitações públicas diretas `anthropic/*`, incluindo tráfego autenticado por OAuth enviado para `api.anthropic.com`, o modo rápido é mapeado para service tiers da Anthropic: `/fast on` define `service_tier=auto`, `/fast off` define `service_tier=standard_only`. +- Para `openai/*`, o modo rápido é mapeado para processamento prioritário da OpenAI, enviando `service_tier=priority` em requisições Responses compatíveis. +- Para `openai-codex/*`, o modo rápido envia a mesma flag `service_tier=priority` em Codex Responses. O OpenClaw mantém um único alternador `/fast` compartilhado entre ambos os caminhos de autenticação. +- Para requisições diretas públicas `anthropic/*`, incluindo tráfego autenticado via OAuth enviado para `api.anthropic.com`, o modo rápido é mapeado para níveis de serviço da Anthropic: `/fast on` define `service_tier=auto`, `/fast off` define `service_tier=standard_only`. - Para `minimax/*` no caminho compatível com Anthropic, `/fast on` (ou `params.fastMode: true`) reescreve `MiniMax-M2.7` para `MiniMax-M2.7-highspeed`. -- Params explícitos de modelo Anthropic `serviceTier` / `service_tier` substituem o padrão do modo rápido quando ambos estão definidos. O OpenClaw ainda ignora a injeção de service tier da Anthropic para base URLs proxy não Anthropic. +- Parâmetros explícitos de modelo Anthropic `serviceTier` / `service_tier` substituem o padrão do modo rápido quando ambos são definidos. O OpenClaw ainda ignora a injeção de nível de serviço da Anthropic para URLs base de proxy que não sejam Anthropic. -## Diretivas verbose (/verbose ou /v) +## Diretivas detalhadas (/verbose ou /v) - Níveis: `on` (mínimo) | `full` | `off` (padrão). -- Uma mensagem contendo apenas a diretiva alterna o verbose da sessão e responde `Verbose logging ativado.` / `Verbose logging desativado.`; níveis inválidos retornam uma dica sem alterar o estado. -- `/verbose off` armazena uma substituição explícita da sessão; limpe-a pela UI de Sessions escolhendo `inherit`. -- A diretiva inline afeta somente aquela mensagem; os padrões de sessão/globais se aplicam nos demais casos. -- Envie `/verbose` (ou `/verbose:`) sem argumento para ver o nível verbose atual. -- Quando verbose está ativado, agentes que emitem resultados estruturados de ferramentas (Pi, outros agentes JSON) enviam cada chamada de ferramenta de volta como sua própria mensagem somente de metadados, com prefixo ` : ` quando disponível (caminho/comando). Esses resumos de ferramenta são enviados assim que cada ferramenta começa (bolhas separadas), não como deltas de streaming. -- Resumos de falha de ferramenta continuam visíveis no modo normal, mas sufixos brutos com detalhes de erro ficam ocultos, a menos que verbose esteja `on` ou `full`. -- Quando verbose está `full`, as saídas das ferramentas também são encaminhadas após a conclusão (bolha separada, truncada para um tamanho seguro). Se você alternar `/verbose on|full|off` enquanto uma execução estiver em andamento, as bolhas de ferramenta subsequentes respeitarão a nova configuração. +- Uma mensagem contendo apenas a diretiva alterna o modo detalhado da sessão e responde com `Verbose logging enabled.` / `Verbose logging disabled.`; níveis inválidos retornam uma dica sem alterar o estado. +- `/verbose off` armazena uma substituição explícita da sessão; limpe-a pela interface de Sessões escolhendo `inherit`. +- A diretiva inline afeta apenas aquela mensagem; os padrões de sessão/globais se aplicam caso contrário. +- Envie `/verbose` (ou `/verbose:`) sem argumento para ver o nível detalhado atual. +- Quando o modo detalhado está ativado, agentes que emitem resultados estruturados de ferramentas (Pi, outros agentes JSON) enviam cada chamada de ferramenta de volta como sua própria mensagem somente de metadados, com o prefixo ` : ` quando disponível (caminho/comando). Esses resumos de ferramenta são enviados assim que cada ferramenta começa (em bolhas separadas), não como deltas de streaming. +- Resumos de falha de ferramenta permanecem visíveis no modo normal, mas sufixos brutos com detalhes de erro ficam ocultos, a menos que o modo detalhado esteja em `on` ou `full`. +- Quando o modo detalhado está em `full`, as saídas das ferramentas também são encaminhadas após a conclusão (em bolha separada, truncadas para um tamanho seguro). Se você alternar `/verbose on|full|off` enquanto uma execução estiver em andamento, as bolhas de ferramenta subsequentes respeitarão a nova configuração. -## Diretivas de trace do Plugin (/trace) +## Diretivas de rastreamento de Plugin (/trace) - Níveis: `on` | `off` (padrão). -- Uma mensagem contendo apenas a diretiva alterna a saída de trace de Plugin da sessão e responde `Trace de Plugin ativado.` / `Trace de Plugin desativado.`. -- A diretiva inline afeta somente aquela mensagem; os padrões de sessão/globais se aplicam nos demais casos. -- Envie `/trace` (ou `/trace:`) sem argumento para ver o nível atual de trace. -- `/trace` é mais restrito que `/verbose`: ele expõe apenas linhas de trace/debug pertencentes ao plugin, como resumos de depuração de Active Memory. -- Linhas de trace podem aparecer em `/status` e como uma mensagem diagnóstica de acompanhamento após a resposta normal do assistente. +- Uma mensagem contendo apenas a diretiva alterna a saída de rastreamento de Plugin da sessão e responde com `Plugin trace enabled.` / `Plugin trace disabled.`. +- A diretiva inline afeta apenas aquela mensagem; os padrões de sessão/globais se aplicam caso contrário. +- Envie `/trace` (ou `/trace:`) sem argumento para ver o nível de rastreamento atual. +- `/trace` é mais restrito que `/verbose`: ele expõe apenas linhas de rastreamento/depuração pertencentes ao Plugin, como resumos de depuração do Active Memory. +- Linhas de rastreamento podem aparecer em `/status` e como uma mensagem de diagnóstico de acompanhamento após a resposta normal do assistente. ## Visibilidade do raciocínio (/reasoning) - Níveis: `on|off|stream`. -- Uma mensagem contendo apenas a diretiva alterna se blocos de raciocínio são mostrados nas respostas. -- Quando ativado, o raciocínio é enviado como uma **mensagem separada** com o prefixo `Reasoning:`. -- `stream` (somente Telegram): faz streaming do raciocínio na bolha de rascunho do Telegram enquanto a resposta é gerada e depois envia a resposta final sem raciocínio. +- Uma mensagem contendo apenas a diretiva alterna se blocos de reflexão são exibidos nas respostas. +- Quando habilitado, o raciocínio é enviado como uma **mensagem separada** com o prefixo `Reasoning:`. +- `stream` (somente Telegram): transmite o raciocínio na bolha de rascunho do Telegram enquanto a resposta é gerada e, em seguida, envia a resposta final sem o raciocínio. - Alias: `/reason`. - Envie `/reasoning` (ou `/reasoning:`) sem argumento para ver o nível atual de raciocínio. -- Ordem de resolução: diretiva inline, depois substituição da sessão, depois padrão por agente (`agents.list[].reasoningDefault`), depois fallback (`off`). +- Ordem de resolução: diretiva inline, depois substituição da sessão, depois padrão por agente (`agents.list[].reasoningDefault`) e, por fim, fallback (`off`). ## Relacionado @@ -104,15 +106,16 @@ x-i18n: ## Heartbeats -- O corpo da sonda de Heartbeat é o prompt de heartbeat configurado (padrão: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Diretivas inline em uma mensagem de heartbeat se aplicam normalmente (mas evite alterar padrões de sessão a partir de heartbeats). -- A entrega de Heartbeat usa por padrão apenas o payload final. Para também enviar a mensagem separada `Reasoning:` (quando disponível), defina `agents.defaults.heartbeat.includeReasoning: true` ou por agente `agents.list[].heartbeat.includeReasoning: true`. +- O corpo da sondagem de Heartbeat é o prompt de heartbeat configurado (padrão: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Diretivas inline em uma mensagem de heartbeat se aplicam normalmente (mas evite alterar padrões de sessão a partir de heartbeats). +- A entrega de Heartbeat usa apenas a carga final por padrão. Para também enviar a mensagem separada `Reasoning:` (quando disponível), defina `agents.defaults.heartbeat.includeReasoning: true` ou `agents.list[].heartbeat.includeReasoning: true` por agente. -## Web chat UI +## Interface web de chat -- O seletor de raciocínio do chat web espelha o nível armazenado da sessão a partir do armazenamento/configuração de sessão de entrada quando a página é carregada. -- Escolher outro nível grava imediatamente a substituição da sessão via `sessions.patch`; não espera o próximo envio e não é uma substituição única `thinkingOnce`. -- A primeira opção é sempre `Default ()`, em que o padrão resolvido vem do modelo ativo da sessão: `adaptive` para Claude 4.6 em Anthropic/Bedrock, `low` para outros modelos compatíveis com raciocínio, `off` caso contrário. -- O seletor permanece sensível ao provedor: +- O seletor de reflexão do chat na web espelha o nível armazenado da sessão a partir do armazenamento/configuração de sessão de entrada quando a página é carregada. +- Escolher outro nível grava imediatamente a substituição da sessão via `sessions.patch`; não espera o próximo envio e não é uma substituição `thinkingOnce` de uso único. +- A primeira opção é sempre `Default ()`, em que o padrão resolvido vem do modelo ativo da sessão: `adaptive` para Claude 4.6 na Anthropic, `off` para Anthropic Claude Opus 4.7, a menos que configurado, `low` para outros modelos com capacidade de raciocínio e `off` caso contrário. +- O seletor permanece ciente do provedor: - a maioria dos provedores mostra `off | minimal | low | medium | high | adaptive` + - Anthropic Claude Opus 4.7 mostra `off | minimal | low | medium | high | xhigh | adaptive` - Z.AI mostra `off | on` binário -- `/think:` ainda funciona e atualiza o mesmo nível armazenado da sessão, então as diretivas do chat e o seletor permanecem sincronizados. +- `/think:` continua funcionando e atualiza o mesmo nível armazenado da sessão, para que as diretivas do chat e o seletor permaneçam sincronizados.