🌌 OntoAgent

The All-Knowing Code Brain & Architecture Contract Guard for AI Coding Agents

Движок когнитивной графовой модели всего репозитория и управления архитектурой для ИИ-агентов программирования.

📖 Why OntoAgent?

Современные Coding Agent при работе с большими кодовыми базами обычно сталкиваются с тремя структурными проблемами:

1. Слепцы и слон: видят только текущий файл, но не видят межмодульных вызывающих, API-контрактов и тестовых зависимостей.

2. Галлюцинации длинного контекста: «насильно впихивают» весь репозиторий в Prompt — высокие затраты на Token, низкое соотношение сигнал/шум, модель легко игнорирует ключевые ограничения.

3. Разрушительные изменения трудно отследить: при изменении одного ключевого класса невозможно быстро узнать, какие вышестоящие модули, тесты и интерфейсы «взорвутся» вместе с ним.

Традиционные подходы:

• Naive Raw Text: полностью впихивается в контекст — огромное количество Token и отсутствие структурной локализации.

• Vector-Chunk RAG: разбивается по текстовому сходству, сжимает Token, но теряет AST-уровневые зависимости, отношения наследования и семантику контрактов.

Выбор OntoAgent:

С помощью статического AST-анализа + встроенной графовой базы данных строит когнитивный граф всего репозитория, позволяя AI Agent перед изменением кода увидеть сеть вызовов, контракты, тесты, радиус поражения.

Related MCP server: code-intel

🏛️ Architecture Flow

graph TD
    subgraph Base["底座层"]
        Kuzu["Kùzu Embedded Graph DB"]
        AST["AST Parsers: Python / TypeScript / Markdown / JSON"]
    end

    subgraph Core["核心引擎"]
        Blast["Blast Radius Analyzer"]
        Context["Smart Context Extractor"]
        Compliance["Architecture Compliance Guard"]
        Scanner["Codebase Scanner & Entity Ingestion"]
    end

    subgraph Ecosystem["交互生态"]
        MCP["MCP Server"]
        DSH["DSH / Cordis Plugin"]
        CLI["onto-agent CLI"]
        Dashboard["React 2D Canvas + Dagre Dashboard"]
    end

    AST --> Scanner
    Scanner --> Kuzu
    Kuzu --> Blast
    Kuzu --> Context
    Kuzu --> Compliance
    Blast --> MCP
    Context --> DSH
    Compliance --> CLI
    Scanner --> Dashboard

📊 Benchmark

Воспроизведение одной командой:

python benchmark/run_benchmark.py

На основе детерминированных кодовых фикстур сравниваются три стратегии построения контекста:

Выводы:

• OntoAgent снижает потребление Token примерно на 89,7% по сравнению с Naive Raw Text.

• OntoAgent полностью превосходит Vector-Chunk RAG по полноте ключевых зависимостей, полноте тестов/контрактов и локализации радиуса поражения.

• Полный отчёт см. в benchmark/reports/benchmark_report.md.

🚀 Quickstart

1. Установка

pip install -e .[test]

2. Сканирование всего репозитория

onto-agent scan --path .

3. Запуск визуальной рабочей панели

python dashboard/api_server.py
# 打开 http://127.0.0.1:8000

4. Настройка MCP

Скопируйте integrations/cursor_mcp.json в .cursor/mcp.json или объедините в Claude Desktop:

{
  "mcpServers": {
    "onto-agent": {
      "command": "python",
      "args": ["-m", "onto_agent.mcp"]
    }
  }
}

5. Установка нативного плагина DSH

dsh plugin --profile web add ./integrations/dsh/onto-agent-plugin

🧠 Agent Abilities

get_blast_radius(file_path)

Перед изменением любого файла/символа возвращает:

• Непосредственных вызывающих

• Косвенно затрагиваемые модули

• Нисходящие зависимости

• Связанные API-контракты

• Тесты, которые необходимо запустить

check_architecture_compliance(strict=True)

Проверяет:

• Циклические import

• Нарушающие вызовы между уровнями

• Ключевые классы, не покрытые тестами

get_smart_context(query_or_symbol)

Генерирует контекст с высоким соотношением сигнал/шум перед рефакторингом/генерацией:

• Определение, номер строки, Docstring

• Список классов/функций

• imports / callers

• API-контракты, связанные тесты, связанная документация

🔌 Ecosystem

🗂️ Project Layout

src/onto_agent/
├── engine/          # Scanner, ArchitectureGuard, Context, Steering, Reflection
├── storage/         # Kùzu graph storage adapter
├── mcp/             # MCP Server
├── client/          # Python SDK
└── cli.py           # Unified CLI

dashboard/           # FastAPI + React workbench
benchmark/           # Reproducible Codex-for-Open benchmark
integrations/        # Cursor / Claude / Windsurf / DSH
docs/                # Design docs & tickets
tests/               # 48+ unit / integration tests

📚 Documentation

• MCP & SDK API

• System Architecture

• Ontology Schema

• Agent Behavior Protocol

• Dashboard Spec

• Contributing Guide

📄 License

Этот проект распространяется под лицензией Apache-2.0.