# Ontology Hub

<div align="center">

**AI Agent 本体管理中心**

一个基于 MCP (Model Context Protocol) 的 AI Native 本体管理系统，让 AI Agent 能够发现、学习和执行 Skill。

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
[![React](https://img.shields.io/badge/react-18+-61dafb.svg)](https://reactjs.org/)
[![MCP](https://img.shields.io/badge/MCP-compatible-green.svg)](https://modelcontextprotocol.io/)

</div>

---

## 什么是 Ontology Hub？

Ontology Hub 是一个 **AI Native** 的本体管理中心，它将 Skill（技能）作为本体（Ontology）进行建模和管理，通过 MCP 协议向 AI Agent 暴露工具，实现：

- **Skill 发现**：Agent 可以搜索和浏览可用的 Skill
- **Skill 执行**：Agent 根据 Skill 的 prompt 指导执行任务
- **Workspace 隔离**：不同项目/领域的 Skill 完全隔离
- **千人千面**：每个 Token 可以有独立的工具权限

## 核心概念

```
┌─────────────────────────────────────────────────────────────┐
│                        AI Agents                            │
│              (Claude, Codex, Cursor, etc.)                  │
└─────────────────────┬───────────────────────────────────────┘
                      │ MCP Protocol (HTTP POST)
                      ▼
┌─────────────────────────────────────────────────────────────┐
│                    Ontology Hub                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │ MCP Server  │  │ Admin Tools │  │   Business Tools    │  │
│  │             │  │ (ontology_*)│  │ (function:/action:) │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │ SchemaStore │  │ ObjectStore │  │    TokenStore       │  │
│  │ (workspace) │  │ (workspace) │  │    (MCP Token)      │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                      │ HTTP API
                      ▼
┌─────────────────────────────────────────────────────────────┐
│                    Web Panel (React)                        │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐           │
│  │  图谱   │ │  结构   │ │  实例   │ │  工具   │           │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘           │
└─────────────────────────────────────────────────────────────┘
```

### 本体（Ontology）

本体是知识的结构化表示，包含：

| 概念 | 说明 | 示例 |
|------|------|------|
| **Object Type** | 定义实体的属性和关系 | Skill, Workspace, SkillExecution |
| **Instance** | 对象类型的具体实例 | 一个具体的 Skill |
| **Function** | 只读查询逻辑，无副作用 | searchSkills, listSkillsByWorkspace |
| **Action** | 数据变更操作 | createSkill, updateSkill, deleteSkill |

### Skill（技能）

Skill 是 AI Agent 的能力定义：

```yaml
Skill:
  skillId: SKI-001           # 唯一标识
  name: 代码审查              # 技能名称
  trigger: 当需要审查代码质量时  # 触发条件
  prompt: 请审查以下代码...    # 提示词模板
  tools: []                  # 依赖的工具
  workspace: default         # 所属工作空间
  status: active             # 状态
```

### Workspace（工作空间）

- 每个 Workspace 是独立的本体空间
- 不同 Workspace 的数据完全隔离
- 可以按项目、领域或团队划分

## 界面预览：本体图谱

力导向图谱页。三种视图模式 × 四种着色方式，所有图分析（邻接表、BFS 跳数、最短路径、连通分量、度数中心性）都在浏览器内基于 `/api/graph` 完成，**不依赖后端改动，也没有引入 Canvas/WebGL 等新依赖**。

| 视图模式 | 作用 |
|------|------|
| **全图** | 展示工作空间内全部实例与关系 |
| **类型聚合** | 同类实例压成超节点（`Model × 22`），边聚合为 `22 条 · belongsToProvider`，直接看本体骨架；点击超节点下钻到该类型 |
| **聚焦** | 只保留选中节点的关系子图（双击节点即进入） |

| 着色方式 | 语义 |
|------|------|
| **类型** | 按 Object Type 着色 |
| **跳数热力** | 以选中节点为热源，按关系跳数分环着色（锚点红 → 1跳橙 → 2跳黄 → 远端蓝） |
| **属性热力** | 自动筛出离散字段（如 `status`）按其取值着色，图例带数量 |
| **度数热力** | 按连接数着色，暴露枢纽资产 |

### 全图 · 按类型着色

![本体图谱全图](docs/screenshots/01-full.png)

### 跳数热力 · 某个 Provider 的影响面

选中 `AIXJ` 后切到跳数热力：顶部 HUD 给出 `1 锚点 · 20 1跳 · 3 2跳 · 0 ≥3跳 · 13 范围外`，无关实例自动淡化，右侧详情抽屉列出全部 20 条反向引用。

![跳数热力](docs/screenshots/02-heatmap.png)

### 类型聚合 · 本体骨架

37 个实例压成 7 个超节点，关系聚合成带计数的边标签。

![类型聚合](docs/screenshots/04-grouped.png)

### 度数热力 + 图谱总览

右侧总览面板给出节点/边/密度、类型分布、关系分布、连接数 TOP（含类型与度数）、连通分量数量。

![度数热力与统计](docs/screenshots/05-stats.png)

### 属性热力

按 `status` 着色，图例直接显示 `active 36 / deprecated 1`，一眼定位异常资产。

![属性热力](docs/screenshots/06-property.png)

### 聚焦 · 只看相关节点

双击任意节点即隔离出它的关系子图，配合「距离」滑杆（1~8 跳）控制关系半径。

![聚焦视图](docs/screenshots/03-focused.png)

### 最短关系链追踪

选中起点 → 点「追踪路径」→ 点终点，用紫色流动线高亮两者之间的最短关系链，详情抽屉给出逐跳步骤与方向语义（含 `(反向)` 标注）。跨孤岛时会如实提示不可达。

![最短关系链](docs/screenshots/07-path.png)

### 选中一个节点后可以做什么

| 操作 | 说明 |
|------|------|
| **只看相关** | 隔离出该节点的关系子图 |
| **居中** | 平移缩放至该节点 |
| **固定位置** | 钉住节点坐标，再次点击解除（Shift+点击为快捷方式） |
| **隐藏** | 从当前视图移除，底部可一键全部恢复 |
| **追踪路径** | 以此为起点，再点击另一节点求最短关系链 |
| **复制查询参数** | 直接复制 `ontology_get_instance` 的 arguments，粘给 Agent 调用 |

关系列表按外键方向拆成**「它引用（出边）」**与**「被谁引用（入边）」**两组，点击任意一条即跳转选中；没有入边的实例会被标注为可能的孤儿数据。

### 其它交互

- **搜索定位**：输入即出建议（Top 6，含名称/类型/ID），回车选中并居中
- **图例筛选**：单击类型隐藏、双击只看该类型
- **显示开关**：边标签、淡化无关、按度数放大节点半径
- **性能护栏**：可见集合裁剪、背景边超 320 条等步长抽稀、标签按缩放档给预算（2/12/40）、大图提前收敛
- **URL 深链**：`?view=focused&color=hop&select=Provider:PRV-aixj&depth=2&stats=1&from=A&to=B`，可把当前视图直接分享给别人
- **快捷键**：`Esc` 取消选择/退出聚焦、`F` 聚焦、`H` 跳数热力、`D` 度数热力、`L` 边标签、`R` 适应视图、`/` 聚焦搜索框

## 快速开始

### 环境要求

- Python 3.10+
- Node.js 18+
- Windows / Linux / macOS

### 安装

```bash
# 克隆项目
git clone https://github.com/your-username/ontology-hub.git
cd ontology-hub

# 安装后端依赖
pip install -r requirements.txt

# 安装前端依赖
cd frontend
npm install
cd ..
```

### 启动服务

```bash
# 启动后端（端口 8100）
python -m uvicorn ontohub.main:app --host 0.0.0.0 --port 8100

# 启动前端（端口 5175）
cd frontend
npm run dev
```

### 访问

- **Web 面板**: http://localhost:5175
- **API 文档**: http://localhost:8100/docs

## MCP 接入

### 1. 生成 MCP Token

在 Web 面板中：
1. 进入 **工具管理** → **MCP Token**
2. 点击 **新建 Token**
3. 选择 Workspace 和角色
4. （可选）自定义工具权限
5. 点击 **生成 Token**
6. 点击 **一键复制** 复制配置

### 2. 配置到 Agent

#### Claude Desktop

编辑配置文件：
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "ontohub-default": {
      "url": "http://localhost:5175/mcp/message",
      "headers": {
        "Authorization": "Bearer mcp_default_admin_xxx",
        "X-Workspace": "default",
        "X-Role": "admin"
      }
    }
  }
}
```

#### Qoder / Cursor

编辑 `~/.qoder/mcp.json` 或 `~/.cursor/mcp.json`：

```json
{
  "mcpServers": {
    "ontohub-default": {
      "url": "http://localhost:5175/mcp/message",
      "headers": {
        "Authorization": "Bearer mcp_default_admin_xxx",
        "X-Workspace": "default",
        "X-Role": "admin"
      }
    }
  }
}
```

### 3. 验证连接

重启 Agent 后，你应该能看到 Ontology Hub 的工具列表。

## 工具说明

### 工具命名规则

| 前缀 | 类型 | 说明 |
|------|------|------|
| `ontology_*` | Admin Tool | 本体管理工具（创建类型、实例等） |
| `function:*` | Function | 只读查询函数 |
| `action:*` | Action | 数据变更操作 |

### Admin Tools（25个）

| 工具 | 说明 |
|------|------|
| `ontology_create_workspace` | 创建工作空间 |
| `ontology_delete_workspace` | 删除工作空间 |
| `ontology_list_workspaces` | 列出所有工作空间 |
| `ontology_switch_workspace` | 切换工作空间 |
| `ontology_get_current_workspace` | 获取当前工作空间 |
| `ontology_create_type` | 创建对象类型 |
| `ontology_update_type` | 更新对象类型 |
| `ontology_delete_type` | 删除对象类型 |
| `ontology_create_instance` | 创建实例 |
| `ontology_update_instance` | 更新实例 |
| `ontology_delete_instance` | 删除实例 |
| `ontology_get_instance` | 获取实例 |
| `ontology_query_instances` | 查询实例 |
| `ontology_traverse` | 关系遍历 |
| `ontology_register_function` | 注册函数 |
| `ontology_unregister_function` | 注销函数 |
| `ontology_list_functions` | 列出函数 |
| `ontology_register_action` | 注册 Action（自动暴露为 action:* 工具） |
| `ontology_unregister_action` | 注销 Action |
| `ontology_get_schema` | 获取本体结构 |
| `ontology_list_types` | 列出类型 |
| `ontology_get_graph` | 获取图数据 |
| `ontology_assign_tools` | 分配工具权限 |
| `ontology_revoke_tools` | 撤销工具权限 |
| `ontology_list_roles` | 列出角色 |

### Functions（5个）

| 函数 | 说明 |
|------|------|
| `function:searchSkills` | 搜索 Skill |
| `function:listSkillsByWorkspace` | 列出工作空间中的 Skill |
| `function:getSkillDetail` | 获取 Skill 详情 |
| `function:getSkillExecutionHistory` | 获取 Skill 执行历史 |
| `function:findSkillByTrigger` | 根据触发条件查找 Skill |

### Actions（5个，默认模板）

| 操作 | 说明 |
|------|------|
| `action:createSkill` | 创建 Skill |
| `action:updateSkill` | 更新 Skill |
| `action:deleteSkill` | 删除 Skill |
| `action:activateSkill` | 激活 Skill |
| `action:recordExecution` | 记录执行结果 |

> **治理约定**：Workspace 的创建/删除属于基础设施管理，由 Admin Tool `ontology_create_workspace` / `ontology_delete_workspace` 承担，不作为业务 Action 暴露。各空间可通过 `ontology_register_action` 按需注册领域运维 Action（如 llm 空间的 `revokeApiKey`、`rotateApiKey` 相关操作）。

## 使用示例

### Agent 对话示例

```
用户：帮我查看一下有哪些可用的 Skill

Agent：我来帮你查看可用的 Skill。

[调用 function:searchSkills]

目前有以下 Skill：
1. 代码审查 - 当需要审查代码质量时使用
2. 文档生成 - 当需要生成技术文档时使用

你想了解哪个 Skill 的详情？
```

### API 调用示例

```bash
# 获取本体结构
curl -X POST http://localhost:5175/mcp/message \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer mcp_default_admin_xxx" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "ontology_get_schema",
      "arguments": {}
    }
  }'

# 创建 Skill
curl -X POST http://localhost:5175/mcp/message \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer mcp_default_admin_xxx" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "action:createSkill",
      "arguments": {
        "name": "代码审查",
        "trigger": "当需要审查代码质量时",
        "prompt": "请审查以下代码...",
        "workspace": "default"
      }
    }
  }'
```

## 部署

### 本地开发

```bash
# 后端
python -m uvicorn ontohub.main:app --host 0.0.0.0 --port 8100 --reload

# 前端
cd frontend && npm run dev
```

### 生产部署（Nginx）

```nginx
server {
    listen 443 ssl;
    server_name onto.example.com;
    
    location / {
        proxy_pass http://localhost:5175;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
    
    location /api/ {
        proxy_pass http://localhost:8100;
    }
    
    location /mcp/ {
        proxy_pass http://localhost:8100;
    }
}
```

### 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `ONTOHUB_DB` | 数据库文件路径 | `.ontohub.db` |
| `ONTOHUB_CONFIG` | 配置文件目录 | `config/` |
| `ONTOHUB_MCP_URL` | MCP 服务地址 | 自动检测 |

## 项目结构

```
ontohub/
├── core/                   # 核心模块
│   ├── store.py           # 实例存储（支持 workspace 隔离）
│   ├── schema_store.py    # Schema 存储（支持 workspace 隔离）
│   ├── token_store.py     # MCP Token 存储
│   └── audit.py           # 审计日志
├── frontend/              # React 前端
│   ├── src/
│   │   ├── components/
│   │   │   ├── GraphPanel.tsx        # 图谱页容器（视图/着色/交互编排）
│   │   │   └── graph/                # 图谱交互层
│   │   │       ├── graphAnalytics.ts # 纯函数图分析（BFS/最短路/分量/中心性）
│   │   │       ├── typePalette.ts    # 类型色与热力色阶
│   │   │       ├── GraphToolbar.tsx  # 视图/着色/距离/搜索工具栏
│   │   │       ├── DistanceHud.tsx   # 距离情报条与图例
│   │   │       ├── NodeInspector.tsx # 节点详情抽屉与操作
│   │   │       ├── GraphStats.tsx    # 图谱总览面板
│   │   │       └── types.ts          # 数据契约
│   │   └── App.tsx        # 主应用
│   └── vite.config.ts     # Vite 配置
├── docs/screenshots/      # 界面截图
├── config/                # 配置文件
│   └── skill_ontology.yaml # Skill 本体定义
├── admin_tools.py         # Admin 工具
├── business_tools.py      # 业务工具
├── mcp_server.py          # MCP 服务器
├── main.py                # FastAPI 入口
└── requirements.txt       # Python 依赖
```

## 技术栈

- **后端**: FastAPI, SQLite, Python 3.10+
- **前端**: React 18, TypeScript, Tailwind CSS, D3.js（d3-force 力导向 + d3-zoom，SVG 渲染）
- **协议**: MCP (Model Context Protocol)
- **数据库**: SQLite（支持 workspace 隔离）

## 贡献

欢迎提交 Issue 和 Pull Request！

## 许可证

[MIT License](LICENSE)

---

<div align="center">

**让 AI Agent 拥有可发现、可学习、可执行的 Skill**

</div>