🌌 OntoAgent

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

面向 AI 编程智能体的全仓认知知识图谱与架构治理引擎。

---

📖 Why OntoAgent?

现代 Coding Agent 面对大型代码库时，通常会遇到三个结构性问题：

1. 盲人摸象：只看到当前文件，看不到跨模块调用者、API 契约和测试依赖。
2. 长上下文幻觉：把整个仓库“暴力丢进 Prompt”，Token 成本高、信噪比低，模型容易忽略关键约束。
3. 破坏性改动难以溯源：改一个核心类，无法快速知道哪些上游模块、测试和接口会一起爆炸。

传统方案：

• Naive Raw Text：全量塞入上下文，Token 巨大且没有结构化定位。
• Vector-Chunk RAG：按文本相似度切块，能压缩 Token，但会丢失 AST 级依赖、继承关系和契约语义。

OntoAgent 的选择：

用 AST 静态解析 + 嵌入式图数据库 构建全仓认知图谱，让 AI Agent 在修改代码前先看到 调用网、契约、测试、爆炸半径。

---

🏛️ 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

基于确定性代码夹具，对比三种上下文构建策略：

Method	Tokens	Token Reduction	Critical Dep Recall	Test & Contract Recall	Blast Precision	Blast Recall	Blast F1
A. Naive Raw Text	1162	0.0%	100.0%	100.0%	50.0%	100.0%	66.7%
B. Vector-Chunk RAG	282	75.7%	0.0%	66.7%	60.0%	60.0%	60.0%
C. OntoAgent AST Graph	120	89.7%	100.0%	100.0%	100.0%	100.0%	100.0%

结论：

• OntoAgent 相比 Naive Raw Text 降低约 89.7% Token 消耗。
• 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

入口	方式
MCP	onto_get_blast_radius、onto_check_architecture_compliance、onto_get_smart_context 等 10 个工具
DSH	integrations/dsh/onto-agent-plugin，Cordis 原生插件
CLI	onto-agent blast-radius、onto-agent compliance、onto-agent context
REST	/api/blast_radius、/api/architecture/compliance、/api/smart_context
Dashboard	React + Force Graph + Dagre 层次架构图

---

🗂️ 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 开源。