Ontoly Software Graph

Visão Geral

Ontoly constrói um Software Graph determinístico a partir de um repositório TypeScript e o expõe através de consultas CLI, capacidades MCP e habilidades de agente. Use esta habilidade quando um agente de codificação precisar de um entendimento do codebase baseado em evidências antes de pesquisar arquivos diretamente.

Esta habilidade é um guia operacional para o projeto público Ontoly. Ela não contém lógica de compilador; todo o entendimento do software deve vir do grafo gerado pelo Ontoly, modelo semântico, motor de consulta e servidor MCP.

Quando Usar Esta Habilidade

• Use quando o usuário perguntar sobre arquitetura de repositório, propriedade de módulos ou ajuda de integração.
• Use ao rastrear uma requisição, rota, controlador, serviço, provedor, dependência ou cadeia de chamadas.
• Use ao estimar o impacto para remover, renomear ou refatorar um símbolo, módulo, pacote, rota ou serviço.
• Use ao revisar a topologia de dependência, importações circulares, código morto, uso de configuração ou variáveis de ambiente.
• Use quando o usuário explicitamente quiser Ontoly, Software Graph, MCP, validação de grafo, cobertura semântica ou habilidades de agente.

Como Funciona

Passo 1: Verificar se o Ontoly Está Disponível

Verifique se o repositório já possui saídas do Ontoly, como .ontoly/, SoftwareGraph.json, relatórios de validação ou scripts Ontoly documentados. Se o comando ontoly não estiver disponível, pergunte ao usuário se deve instalar ou usar o comando do gerenciador de pacotes documentado do repositório.

Verificações locais recomendadas:

ontoly --help
find . -maxdepth 3 \( -name "SoftwareGraph.json" -o -name ".ontoly" \) -print

Passo 2: Construir ou Atualizar o Grafo

Execute a construção do grafo apenas no repositório sobre o qual o usuário perguntou. Informe ao usuário que a geração do grafo pode criar artefatos Ontoly locais antes de executá-la.

ontoly build .

Se o projeto documentar um comando diferente, prefira o comando documentado em vez de adivinhar.

Passo 3: Verificar Confiança, Diagnósticos e Cobertura

Antes de responder a perguntas arquiteturais, inspecione os diagnósticos do Ontoly, estatísticas do grafo, confiança e cobertura semântica. Trate importações não resolvidas, baixa confiança, detecção de framework ausente ou falhas de validação de grafo como restrições para a resposta.

Use as capacidades CLI ou MCP expostas pela versão Ontoly instalada. Prefira consultas de grafo estruturadas em vez de busca de texto.

Passo 4: Usar Capacidades do Ontoly MCP

Inicie ou conecte-se ao servidor Ontoly MCP quando o host suportar MCP:

ontoly mcp

Use capacidades como resumos de arquitetura, análise de dependência, rastreamento de requisição, análise de impacto, consulta de configuração, relatórios de framework, análise de código morto e validação de grafo quando disponíveis.

Passo 5: Responder com Evidências

Toda resposta deve incluir:

• A capacidade ou consulta Ontoly utilizada.
• A evidência do nó, aresta, rota, pacote ou diagnóstico que suporta a resposta.
• Uma declaração de confiança derivada das evidências do grafo.
• Quaisquer limitações conhecidas causadas por regiões de grafo ou diagnósticos ausentes.

Passo 6: Recuar Graciosamente

Inspecione arquivos do repositório diretamente apenas quando o Ontoly não puder responder, o grafo estiver ausente, os diagnósticos tornarem o grafo não confiável para a pergunta, ou o usuário pedir verificação em nível de código-fonte. Ao recuar, explique qual evidência do grafo foi insuficiente.

Exemplos

Revisão de Arquitetura

Usuário pergunta: "Explique este repositório."

Fluxo de trabalho:

1. Verifique ou construa o grafo Ontoly.
2. Verifique a confiança do grafo, diagnósticos, frameworks detectados, pacotes, módulos, serviços, rotas e os maiores hubs de dependência.
3. Use o resumo de arquitetura do Ontoly ou consulta equivalente.
4. Relate a arquitetura com evidências do grafo e confiança.

Rastreamento de Requisição

Usuário pergunta: "Rastreie o fluxo de login."

Fluxo de trabalho:

1. Procure nos nós do grafo por rotas e controladores de autenticação.
2. Rastreie as relações rota-para-controlador-para-serviço-para-repositório.
3. Inclua arestas não resolvidas ou relações ausentes como limitações.
4. Evite abrir arquivos de código-fonte, a menos que o grafo não consiga identificar o fluxo.

Análise de Impacto

Usuário pergunta: "O que quebra se eu remover UserRepository?"

Fluxo de trabalho:

1. Localize o nó do grafo para UserRepository.
2. Consulte chamadores, consumidores, arestas de injeção de dependência, módulos, rotas e pacotes que o referenciam.
3. Separe dependentes diretos do impacto transitivo.
4. Inclua confiança baseada em relações explícitas do grafo.

Melhores Práticas

• Prefira consultas de grafo Ontoly antes de grep, análise AST ou busca ampla de arquivos.
• Mantenha as evidências do grafo separadas da inferência.
• Trate os diagnósticos como parte da resposta, não como ruído.

…