🌌 OntoAgent

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

Kognitiver Wissensgraph für das gesamte Repository und Architektur-Governance-Engine für KI-Codierungsagenten.


📖 Warum OntoAgent?

Moderne Coding-Agenten stoßen bei großen Codebasen typischerweise auf drei strukturelle Probleme:

1. Blinde Männer und der Elefant: Sie sehen nur die aktuelle Datei, nicht die modulübergreifenden Aufrufer, API-Verträge und Testabhängigkeiten.

2. Halluzinationen bei langen Kontexten: Das gesamte Repository wird „gewaltsam in den Prompt geworfen“ – hohe Token-Kosten, niedriges Signal-Rausch-Verhältnis, und das Modell übersieht leicht kritische Einschränkungen.

3. Zerstörerische Änderungen sind schwer nachzuverfolgen: Wenn man eine Kernklasse ändert, kann man nicht schnell wissen, welche Upstream-Module, Tests und Schnittstellen zusammen explodieren.

Traditionelle Ansätze:

• Naive Raw Text: Vollständig in den Kontext gestopft – riesige Token-Menge und keine strukturierte Lokalisierung.

• Vector-Chunk RAG: Nach Textähnlichkeit in Blöcke aufgeteilt – kann Token komprimieren, verliert aber AST-Ebene-Abhängigkeiten, Vererbungsbeziehungen und Vertragssemantik.

Die Wahl von OntoAgent:

Mit AST-Statikanalyse + eingebetteter Graphdatenbank einen kognitiven Graphen für das gesamte Repository aufbauen, damit der KI-Agent vor Codeänderungen Aufrufnetzwerk, Verträge, Tests und Explosionsradius sieht.

Related MCP server: code-intel

🏛️ Architektur-Ablauf

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

Mit einem Klick reproduzierbar:

python benchmark/run_benchmark.py

Basierend auf deterministischen Code-Fixtures, Vergleich von drei Kontextaufbaustrategien:

Fazit:

• OntoAgent reduziert den Token-Verbrauch um etwa 89,7% im Vergleich zu Naive Raw Text.

• OntoAgent führt im Vergleich zu Vector-Chunk RAG bei der Rückrufquote kritischer Abhängigkeiten, Test-/Vertragsrückruf und Explosionsradius-Lokalisierung.

• Vollständiger Bericht siehe benchmark/reports/benchmark_report.md.

🚀 Schnellstart

1. Installation

pip install -e .[test]

2. Gesamtes Repository scannen

onto-agent scan --path .

3. Visualisierungsworkbench starten

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

4. MCP konfigurieren

Kopieren Sie integrations/cursor_mcp.json nach .cursor/mcp.json oder führen Sie es in Claude Desktop zusammen:

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

5. DSH-Plugin nativ installieren

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

🧠 Agent-Fähigkeiten

get_blast_radius(file_path)

Vor dem Ändern einer beliebigen Datei/eines Symbols zurückgeben:

• Direkte Aufrufer

• Indirekt betroffene Module

• Downstream-Abhängigkeiten

• Zugehörige API-Verträge

• Tests, die ausgeführt werden müssen

check_architecture_compliance(strict=True)

Prüft:

• Zirkuläre Imports

• Schichtübergreifende Verstöße bei Aufrufen

• Kernklassen ohne Testabdeckung

get_smart_context(query_or_symbol)

Erzeugt hochwertigen Kontext mit hohem Signal-Rausch-Verhältnis vor Refactoring/Generierung:

• Definition, Zeilennummern, Docstring

• Klassen-/Funktionsliste

• imports / callers

• API-Verträge, zugehörige Tests, zugehörige Dokumentation

🔌 Ökosystem

🗂️ Projektstruktur

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

📚 Dokumentation

• MCP & SDK API

• System Architecture

• Ontology Schema

• Agent Behavior Protocol

• Dashboard Spec

• Contributing Guide

📄 Lizenz

Dieses Projekt ist unter Apache-2.0 Open Source.