Envoy

Embody

crie na velocidade do pensamento.

embody.tools  ·  Documentação  ·  Manifesto  ·  Changelog

_{Embot — ele salta pela sua rede enquanto o Envoy constrói}

O Embody coloca suas ideias na tela tão rápido quanto você consegue descrevê-las. Operadores, conexões, parâmetros, tudo. Quer tentar um rumo diferente? Crie uma nova abordagem em segundos. Compare tentativas lado a lado. Ramifique a partir da que funciona. A ferramenta acompanha você, em vez de o contrário.

Quatro Ferramentas, Uma Ideia

Envoy — velocidade para frente. Um servidor MCP embutido permite que Claude Code, Codex, OpenCode, Gemini, Cursor, Windsurf e GitHub Copilot (via VS Code) conversem diretamente com sua sessão ativa do TouchDesigner. Crie operadores, conecte-os, defina parâmetros, escreva extensões, depure erros — apenas dizendo o que você quer. Sem copiar e colar código. Sem descrever sua rede no chat. Ideia → operadores em segundos.

Embody — velocidade lateral. Marque qualquer operador e o Embody o externaliza para arquivos em disco que espelham a hierarquia da sua rede. Tente uma nova direção, ramifique a partir de uma boa, restaure o estado de ontem — tudo em segundos. Seus arquivos externalizados são a fonte da verdade, então todo projeto já abre em fluxo.

Convoy — velocidade para fora. Nós Embody habilitados para Convoy em uma LAN confiável descobrem, inspecionam e controlam uns aos outros — uma única sessão de IA retransmitindo builds, execuções de teste, salvamentos, capturas de tela e reinicializações para todas as máquinas na sala. Um pequeno aplicativo de fundo por usuário mantém cada nó acessível mesmo com o TouchDesigner fechado. Guia do Convoy

TDXN — o substrato que torna tudo isso possível. Redes do TouchDesigner exportadas como YAML legível por humanos. O formato é o que permite que seu agente de IA entenda o que está na tela, o que permite que você compare uma tentativa com outra, e o que permite que uma rede se reconstrua a partir de texto na próxima abertura do projeto. TDXN é o que torna todo o resto possível.

Início Rápido

Requisitos: TouchDesigner 2025.33230 ou posterior (Windows / macOS). Sem necessidade de configuração Python — o Embody constrói um ambiente Python por projeto (.venv) correspondente ao interpretador do próprio TouchDesigner, e seus próprios pacotes também podem viver nele. Sem estrutura de pastas especial: o Embody funciona em qualquer pasta de projeto, e se você usa git, cada mudança também é um diff limpo de graça.

1. Instalação

Baixe o .tox do Embody em /release e arraste-o para o seu projeto TouchDesigner. O Assistente de Configuração abre e guia você pelas escolhas que importam — quanta autonomia o Embody recebe, o que externalizar, se deve habilitar o assistente de IA (Envoy) e para qual ferramenta, permissões, se deve entrar em um Convoy de LAN confiável, e onde os arquivos de configuração ficam. Nada muda até o clique final, e você pode executá-lo novamente a qualquer momento via o pulso Assistente de Configuração no COMP Embody.

Atualizando o Embody: O Embody se atualiza sozinho — acione Verificar Atualização na página Sobre (ou defina Auto-Atualizar para verificar na inicialização), e uma versão verificada é baixada, com backup e substituída no lugar. Suas configurações e externalizações rastreadas ficam no disco e sobrevivem à atualização intactas. Veja o guia de auto-atualização. Alternativa manual: exclua o COMP Embody antigo e arraste o novo .tox em seu lugar — a nova versão capta seu estado em disco automaticamente, sem nova varredura, sem arquivos reescritos.

Provisionando uma máquina sem ninguém nela (um nó de renderização, um servidor de mídia)? O bootstrap instala o Embody em um .toe offline com as próprias ferramentas do TouchDesigner, em uma linha.

2. Marque e Trabalhe

1. Marque operadores — passe o cursor sobre qualquer COMP ou DAT e pressione lctrl duas vezes para abrir o marcador (escolha uma estratégia para um COMP, um formato de arquivo para um DAT)
2. Trabalhe normalmente — pressione ctrl + shift + u para atualizar todas as externalizações, ou ctrl + alt + u para atualizar apenas o COMP atual. Arquivos externalizados são gravados ao salvar; ao abrir, o .toe permanece autoritativo por padrão (Exportar ao Salvar), enquanto o modo Roundtrip também reconstrói COMPs de estratégia TDXN a partir do disco

Dica: A externalização é opcional — nada é gravado em disco até você marcar. Para capturar o trabalho do seu assistente de IA automaticamente, defina Auto-Externalizar Novos Ops (página de parâmetros do Envoy) e tudo o que ele criar através do Envoy será marcado e externalizado conforme for construído.

Para formatos suportados, configuração de pastas, tratamento de duplicatas, UI do Gerenciador e mais — veja a documentação do Embody.

Servidor MCP Envoy

O Embody inclui o Envoy, um servidor MCP embutido que dá aos assistentes de codificação de IA acesso direto à sua sessão ativa do TouchDesigner.

Configuração

1. Escolha um assistente de IA no Assistente de Configuração — ele abre na primeira instalação, ou execute-o novamente a qualquer momento (o pulso Assistente de Configuração no COMP Embody). Prefere parâmetros? Alternar Habilitar Envoy (Envoyenable) faz o mesmo com suas configurações atuais
2. O servidor inicia em 127.0.0.1:9870 (configurável via Envoyport; se a porta estiver ocupada por outra instância, o Envoy varre para frente automaticamente)
3. Auto-configuração — o Envoy grava um .mcp.json (ponte STDIO, então as ferramentas estão disponíveis mesmo antes do TD estar em execução) na raiz do seu projeto de IA. Por padrão, essa é a raiz do repositório git; a etapa de localização de configuração do assistente — ou o parâmetro Aiprojectroot — pode apontá-la para a pasta .toe ou um caminho personalizado. Projetos sem repositório git ainda recebem configuração gerada na pasta .toe
4. Conecte — abra uma sessão do Claude Code (ou reinicie sua IDE) nessa raiz — ela capta o .mcp.json automaticamente

A configuração gerada executa o transporte STDIO em ponte do Envoy (recomendado — ele pode iniciar e reiniciar o TD para você). Se preferir conectar um cliente manualmente, o transporte HTTP direto funciona sempre que o TD estiver em execução:

{
  "mcpServers": {
    "envoy": {
      "type": "http",
      "url": "http://127.0.0.1:9870/mcp"
    }
  }
}

Ferramentas de Relance

...e mais 56. Veja a referência completa de ferramentas.

Quando o Envoy inicia, ele sempre gera um arquivo AGENTS.md na raiz do seu projeto com padrões de desenvolvimento TD e orientação específica do projeto. Ele também grava uma configuração específica do cliente para o assistente que você selecionar no parâmetro Aiclient (CLAUDE.md + .claude/ para Claude Code, opencode.json + .claude/ para OpenCode, regras do Cursor/Windsurf, instruções do Copilot, GEMINI.md para Gemini; Codex e OpenCode leem AGENTS.md diretamente). Para OpenCode e configurações de modelo local, veja o guia Modelos Locais e Clientes Abertos.

Formato de Rede TDXN

TDXN (TouchDesigner eXternal Network) é o formato de arquivo que torna o resto do Embody possível. Ele exporta uma rede inteira de operadores — operadores, conexões, parâmetros, layout, anotações, conteúdo de DAT — como um único arquivo YAML legível por humanos. Seu agente de IA pode lê-lo. Você pode lê-lo. Qualquer ferramenta de texto pode compará-lo. A rede pode se reconstruir a partir dele.

Este é o substrato. Toda outra capacidade — construção orientada por IA, controle de versão, restauração automática — se constrói sobre ele.

• Projeto inteiro: ctrl + shift + e
• COMP atual: ctrl + alt + e
• Via Envoy: ferramentas MCP export_network / import_network

Veja a especificação completa do TDXN para detalhes do formato, processo de importação e garantias de ida e volta.

Atalhos de Teclado

Estes são os padrões — todo atalho é editável na página de parâmetros Atalhos do COMP Embody (digite uma combinação, ou acione Gravar e pressione as teclas; vazio desativa). Veja Atalhos de Teclado.

my-project/              ← project folder (optionally a git repo)
├── my-project.toe       ← your TouchDesigner project
├── base1/               ← externalized operators
│   ├── base2.tox        ← COMP (TOX strategy)
│   ├── base3.tdxn        ← COMP (TDXN strategy — diffable YAML)
│   └── text1.py         ← DAT
└── ...

op.Embody.Log('Something happened', 'INFO')
op.Embody.Warn('Check this out')
op.Embody.Error('Something broke')

op.unit_tests.RunTests()                              # All tests (non-blocking)
op.unit_tests.RunTests(suite_name='test_path_utils')   # Single suite
op.unit_tests.RunTestsSync()                           # All in one frame (blocks TD)

Histórico de Versões

Cada release é documentado no changelog completo. Destaques:

• 6.2.65 — quatro novas skills (glsl-shaders, operator-gotchas, testing, /collab) e arquivos de referência de skills, com agradecimentos ao TDMCPSkills da Derivative; describe_op_type e run_soak_test; a orientação sempre carregada de um projeto de usuário reduzida em 40%
• 6.2.64 — Esquecer Nós Offline limpa linhas em toda a frota, cada uma pelo seu dono; nós silenciosos se aposentam após uma semana em vez de um mês; trabalhos de atualização não relatam mais falha falsa
• 6.2.63 — o supervisor do Windows permanece armado após uma instalação; linhas de nós carregam a build do TD e a atualização da frota seu runtime id; um nó vivo mas silencioso é lido como travado; uma leitura no meio da varredura é limpa ao reabrir
• 6.2.62 — o registro fantasma de um host re-cunhado fica dormente em seus pares em vez de ser discado para sempre; o pin permanece, o contato o desperta, e o Status nomeia o fantasma em ambos os lados
• 6.2.61 — Convoy nomeia sua dependência Envoy e os avisos do host (certificados rejeitados, identidades re-cunhadas, divisões de realm, binds de VPN), re-pina pares alterados, evita VPNs e redes públicas no auto-bind, e reentra no realm de pares admitidos em vez de fundar um
• 6.2.59 — um clone novo mantém o Envoy que adota; um rollback não reivindica mais a versão que descartou; a verificação de identidade do gate de release parou de falhar builds saudáveis e de passar em tabelas de runtime
• 6.2.57 — exportações TDXN exportam referências de operadores como autoradas e re-baseliam caminhos absolutos dentro do projeto (corrige #132); um clone novo adota a declaração Envoy commitada; smoke de release de instalação nova em um comando, com a etapa macOS no CI
• 6.2.56 — um venv cujo Python para de rodar é reparado no lugar em vez de deletado, em uma thread em segundo plano, mantendo pacotes instalados; habilitar Envoy não congela mais o TD; bump de segurança devalue
• 6.2.55 — novos espécimes Serenity e Beauty com vídeo de capa; clones habilitados de um COMP irmão exportam como seus valores (o mandala .tdxn 9.599 → 2.834 linhas); o visualizador de fonte do embody.tools renderiza no navegador; Embot permitido em TDXN COMPs; nova regra enviada tdxn-economy
• 6.2.52 — parâmetros customizados tuplet (RGB, XYZ, Float/Int multi-componente) com um default não-zero importam com esse valor em vez de 0
• 6.2.51 — sete pegadinhas de regras de agente da issue #94 verificadas ao vivo antes do envio; capas do embody.tools vêm da linha do espécime, nunca de uma lista fixa; novo espécime Prismatic Strata
• 6.2.50 — Export Release Toe: um pulso pergunta, pergunta onde, então envia o projeto como um .toe bloqueado; Embody pode escrever o hook pre_release_toe para você
• 6.2.49 — salvamentos dizem o que um .tdxn não pode conter, cabeçalhos permanecem visíveis no VS Code, e Envoy não pode mais congelar o TouchDesigner deletando seu próprio host (issues #106, #108–#110)
• 6.2.42 — ExportReleaseToe: envie o projeto inteiro como um .toe bloqueado com Embody removido, pré-visualize primeiro
• 6.2.41 — o MCP SDK move para 2.2.0; venvs existentes se atualizam no próximo início
• 6.2.40 — a tag TDXN, a coluna strategy, os arquivos no disco e o driver de diff do git todos dizem TDXN; nove leituras de estratégia que tinham parado silenciosamente de corresponder são corrigidas
• 6.2.13 — defaults de parâmetros customizados vetoriais sobrevivem à ida e volta (issue #96); seis campos de definição, três flags autoradas e formato TDXN 2.1
• 6.2.8 — o rename TDXN completa em docs, skills e embody.tools (/tdn/ → /tdxn/ com redirecionamentos permanentes)
• 6.2.5 — correções de revisão TDXN: exportações de snapshot nunca tocam arquivos rastreados, e detecção de sujeira cobre tudo que uma exportação escreve
• 6.2.0 — três níveis de namespace; a superfície promovida cai de 214 membros para 43 (issue #94 — quebrável para nomes não documentados)
• 6.1.5 — todo cliente de IA recebe a config MCP que realmente lê, de um único registro; proteção de edição viaja dentro de arquivos gerados
• 6.1.2 — o formato se torna TDXN (TouchDesigner eXternal Network); arquivos .tdn existentes funcionam sem mudanças, com um pulso de migração opt-in
• 6.0.201–6.0.280 — o arco de endurecimento do Convoy: habilitação no macOS, um daemon auto-atualizável, atualizações Embody em toda a frota, e um auto-atualizador que não pode mais ser travado por um download preso
• 6.0.171 — Convoy envia de ponta a ponta: nós em uma LAN confiável descobrem, retransmitem trabalho e controlam uns aos outros
• 6.0.162 — port do MCP SDK 2.0 com venvs auto-atualizáveis
• 6.0.145 — auto-atualização enviada: com gate de manifest, verificada, backup + rollback

Contribuidores

Originalmente derivado do External Tox Saver por Tim Franklin. Refatorado inteiramente por Dylan Roscover, com inspiração e orientação de Elburz Sorkhabi, Matthew Ragan e Wieland Hilker.

Quer ajudar? Comece com CONTRIBUTING.md — este repositório funciona de forma diferente de um projeto Python típico (o TouchDesigner escreve muitos dos arquivos), e essa página explica o que é seguro mudar e como rodar os testes.

Créditos

Embody se apoia no trabalho de outras pessoas, e esta seção o nomeia. Ideias circulam entre os projetos TouchDesigner MCP em ambas as direções; onde Embody adotou uma, ela é creditada aqui e no código onde chegou.

• External Tox Saver por Tim Franklin — Embody começou em 2020 como um refactor dele.
• TDMCP por Derivative (seu servidor MCP experimental, um repositório privado no momento da escrita, usado com permissão) — mutações MCP desfazíveis (um passo de undo por lote), o design get_docs (ajuda offline exata por versão primeiro, a API wiki em segundo), crescimento de bloco de sequência em escritas de parâmetros, o prompt de endurecimento de segurança de transporte, e tratar uma regra de revisão de código como uma consulta. Chegou a partir da v6.0.87 (2026-07-04).
• TDMCPSkills por Derivative (privado no momento da escrita, usado com permissão) — a skill pop-networks é adaptada de td-pop-family; glsl-shaders e operator-gotchas foram escritas contra suas skills td-glsl-shaders e família como uma lista de verificação de tópicos, com cada afirmação re-verificada ao vivo no TD 2025.33230 (2026-09-25).
• touchdesigner-mcp por 8beeeaaat — o primeiro servidor TouchDesigner MCP amplamente usado (2025). O vocabulário de ferramentas mais antigo do Envoy (get_td_classes, get_td_class_details, get_td_info, get_module_help, exec_node_method, execute_python) segue os nomes que esse projeto estabeleceu.
• td-mcp-rs por asyade — uma abordagem de daemon Rust para o mesmo problema (2026). Sua dispensa de diálogo do SO, endereçamento de instância por chamada, códigos de erro estáveis com dicas de correção, captura de qualquer família através de um OP Viewer TOP, lint de shader em escritas de DAT e instalação offline em um arquivo de projeto são ideias que Embody adotou e construiu (veja o roadmap).

Se Embody carrega uma ideia sua e esta lista a omite, abra uma issue e ela será adicionada.

Marcas Registradas e Afiliação

Embody é um projeto open-source independente. Não é afiliado, endossado ou patrocinado pela Derivative. TouchDesigner é uma marca registrada da Derivative.

Licença

Licença MIT