Desenvolvedor ensina Claude Code e Codex a editar processos de negócio do Bitrix24 via .bpt

Um processo de negócio no Bitrix24 vive mais tempo do que seus autores se lembram. Uma solicitação ainda precisa ser aprovada, um responsável designado, uma notificação enviada. Mas, com os anos, o esquema vira uma árvore em que os blocos se chamam «Condição» e «Notificação», e para mudar uma rota é preciso lembrar as intenções de outras pessoas. As redes neurais há muito analisam repositórios, mas aqui tudo é feito à mão. O autor do projeto decidiu corrigir isso e deu aos agentes de IA ferramentas adequadas.

O que o agente recebe

Um pedido como «corrija o processo de negócio» não dá nada ao modelo: ele não sabe como o Bitrix armazena um modelo. Uma captura de tela do esquema também não ajuda, pois não mostra as propriedades dos blocos, as expressões e as ligações entre ações.

Por isso o repositório contém um único skill: um arquivo com a ordem de trabalho, quatro guias de referência (estrutura do modelo, expressões, tipos de ações, gateway) e scripts em Python. Eles descompactam o arquivo, mostram a árvore, procuram nós e verificam links. Um .bpt exportado é uma serialização PHP sobre zlib, não XML nem JSON. Não é possível substituir diretamente um nome em russo no texto: o comprimento da string é gravado em bytes e o arquivo quebraria. A edição passa pela estrutura: carregar, alterar a propriedade, remontar.

Há dois modos. No modo de arquivo, o agente trabalha com a exportação e a importação para o portal continua sendo uma etapa separada; isso serve também para a nuvem, se o portal permitir exportação e importação. No segundo modo, um módulo pago para a edição on-premise oferece um gateway: pelo cliente bpagent.py o agente lê o processo, encontra o ramo e envia a alteração. MCP não é usado aqui, e o módulo não tem modelo embutido.

Como é o trabalho

Primeiro o validador é executado no modelo original, para que defeitos antigos não sejam depois atribuídos ao agente. Depois vem a busca: por tipo de nó, por substring, por exemplo um domínio antigo, e a leitura da subárvore. Por padrão, o cliente não devolve inteira uma árvore grande se ela tiver mais de 150 nós. Uma boa prática: separar busca e substituição, porque o mesmo domínio pode aparecer no texto de um e-mail, numa condição ou em código executável.

Na prática, o agente encontrou URLs incorretas e problemas com funcionários designados. O autor é franco: não há medições exatas da economia de tempo e ele não criou um processo do zero dessa maneira.

Segurança da gravação

A leitura devolve a árvore e um hash de versão. A gravação exige esse hash no cabeçalho If-Match; caso contrário, o servidor recusa. Antes de salvar, o gateway verifica tipos, permissões e tamanhos, executa o validador e cria um snapshot. A gravação passa pelo padrão CBPWorkflowTemplateLoader::update(), sem SQL direto. A chave de acesso pode ser restrita por permissões de leitura, gravação, criação e execução, bem como a modelos específicos. Alterar o PHP embutido (CodeActivity) exige uma permissão separada, templates:write_code, porque é código executável no servidor do portal.

Limitações

O validador verifica apenas a estrutura. Uma referência existente a uma constante existente pode ser formalmente correta e errada quanto ao sentido. A gravação está bloqueada para NodeWorkflowActivity. A versão 0.3.1 não tem bloqueio atômico contra salvamentos simultâneos no editor visual, então combine quem está editando o processo no momento. Outro ponto: mesmo com o Bitrix instalado no seu próprio servidor, o conteúdo dos modelos vai para um agente externo e fica sujeito aos termos da sua ferramenta de IA. O módulo ainda está em moderação no Marketplace do 1C-Bitrix.

O que fazer

Se você tem dezenas de processos acumulados, comece pelo modo de arquivo em uma cópia da exportação: peça ao agente apenas para encontrar e explicar, sem alterar nada. Depois da aprovação, verifique a alteração no designer e execute-a em uma entidade de teste. O padrão geral é útil além do Bitrix: dê ao agente um formato, ferramentas e a ordem «estudar, alterar, verificar», e não simplesmente um JSON enorme.