Guia de Desenvolvimento e Operações do AxonX

Este guia pode ser lido de forma independente ou instalado como uma habilidade do Agente. Links de documentação e código-fonte usam URLs absolutas, portanto, copiar este arquivo não depende de seu diretório original. O projeto mantido é FlowLLM-AI/AxonX.

Caminhos de código-fonte como plugins/a158/... são relativos à raiz de um checkout de código-fonte do AxonX, não a este documento ou ao espaço de trabalho do Agente. Execute comandos de desenvolvimento de código-fonte e compilação de plugins a partir desse checkout. Caminhos de espaço de trabalho passados para Jobs como preview_file são relativos ao espaço de trabalho do serviço selecionado. A instalação de pacotes por si só não fornece os códigos-fonte de exemplo de plugins.

Quando Usar Esta Habilidade

• Use ao desenvolver ou modificar plugins de pesquisa do AxonX e seus contratos de Tarefa tipados.
• Use quando um usuário solicitar submissão de tarefas do AxonX, rastreamento de execução, investigação de falhas ou inspeção de artefatos.
• Use ao integrar um Agente externo com um serviço MCP do AxonX existente.

Notas de Segurança e Proteção

Esta habilidade é rotulada como critical porque documenta a instalação de pacotes, submissão de tarefas, execução remota de shell, cancelamento, exclusão e substituição de artefatos. Estabeleça primeiro a operação solicitada pelo usuário e o serviço/espaço de trabalho exato. Não trate exemplos de comandos como autorização. Solicite esclarecimentos quando o alvo da execução ou o escopo de uma operação destrutiva não estiver claro; autorizações explícitas existentes permanecem válidas. Nunca exponha tokens de serviço ou de provedor de dados em relatórios, logs ou arquivos commitados. Faça backup de artefatos insubstituíveis antes da substituição ou exclusão autorizada.

Preparar o Ambiente e o Serviço

Use Python 3.12+ no macOS ou Linux para execução local de Tarefas. Em seu diretório de trabalho escolhido, crie e ative um ambiente virtual, e então instale o núcleo:

python3 -m venv .venv
source .venv/bin/activate
pip install axonx
axonx help

Para a UI Studio pré-compilada, instale axonx[studio] em vez disso. Plugins de pesquisa são instalados separadamente. Para desenvolvimento de código-fonte, clone o projeto, entre em sua raiz e instale-o em um ambiente virtual ativado:

git clone https://github.com/FlowLLM-AI/AxonX.git
cd AxonX
pip install -e .

Configure credenciais através de variáveis de ambiente ou um arquivo .env descoberto a partir do diretório de trabalho do processo ou seus pais. Antes de iniciar um serviço local, substitua o placeholder do token pelo seu próprio valor:

export AXONX_SERVICE_TOKEN='replace-with-your-local-service-token'
axonx start --service.host 127.0.0.1

Mantenha esse processo em execução. Em outro terminal, ative o mesmo ambiente e configure o mesmo token, e então execute axonx version para verificar a conexão. A porta padrão é 1024; o espaço de trabalho padrão é .axonx sob o diretório de inicialização. Se estiver usando um serviço existente, obtenha seu endereço e configuração de autenticação antes de fazer chamadas. Mantenha um alvo de execução para consultas de plugins, submissões, status, logs e inspeção de artefatos.

Para clientes MCP, conecte-se a http://127.0.0.1:1024/mcp usando Streamable HTTP e o cabeçalho Authorization: Bearer <service-token>; substitua o endereço e o token pelos do seu serviço. Descubra ferramentas do serviço conectado em vez de assumir um catálogo de ferramentas fixo. Os exemplos de CLI abaixo descrevem as mesmas operações; use os esquemas de entrada MCP descobertos ao chamar ferramentas.

A Tarefa demo integrada pode verificar a submissão e o rastreamento sem credenciais de mercado ou modelo; o fluxo de trabalho Alpha158 requer seu plugin de pesquisa e dados de entrada preparados. Downloads de mercado exigem AXONX_TUSHARE_TOKEN; Agentes baseados em modelo requerem configuração de modelo separada. Veja Início rápido, Fluxo de trabalho de pesquisa e Integração MCP para exemplos completos de configuração.

Ao usar este documento como uma habilidade, execute apenas as operações exigidas pela solicitação do usuário. Exemplos de documentação não autorizam instalação, execução de tarefas, exclusão ou alterações remotas por si só. Para alterações no checkout de código-fonte, siga seu AGENTS.md e o guia de contribuição.

Background

…