🌌 OntoAgent

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

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

📖 Why OntoAgent?

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

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

传统方案：

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

📄 License

本项目基于 Apache-2.0 开源。

onto-agent

PLUG IN

README