ontology-agent-demo MCP Server
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
本体 × 智能体协作 Demo
演示本体(Ontology)如何与智能体(Agent)配合:用户用自然语言提问,智能体负责理解与编排(把问题翻译成对推理 API 的调用),本体负责给出确定性、可解释的推理结论,智能体再把结论组织成回答。全程可视化展示「事实 → 规则 → 结论」的推导链。
一句话定位:把本体推理能力打包成一个开箱即用的工具——一条命令起服务,MCP 接入智能体,配套 9 篇《本体上手指南》边学边跑。

第一次用:点右上角「当前领域」→ 第 02 问「能问它什么」→ T2-15,一次看完从任务拆解到执行者、约束与复核候选的完整编排。
两条路径别混淆:示例题是
guide.json里的契约预置题(固定参数、可复现、页内只读试跑);自然语言是智能体经 MCP 调用推理 API 的路径(本仓库不带对话输入框)。两者最终调用同一套领域能力。
演示场景
# | 问法 | 智能体做什么 | 本体推理做什么 |
1 | 「登录模块开发谁能做?」 | 识别任务实体 | R1 能力匹配(属性链) |
2 | 「新功能上线怎么安排?」 | 拆解任务链 | R3 依赖传递 + 逐环节匹配 |
3 | 「把合规报表开发分配给初级研发」 | 执行分配 | R4 合规冲突检测 |
4 | 「为什么选研发 Agent?」 | 追问上一步 | 返回推导链(事实→规则→结论) |
5 | 「检查一下有没有冲突」 | 触发检查 | 一致性检查 |
6 | 「介绍一下这个本体」 | 读取本体概览 | 结构导出 |
Related MCP server: oak-mcp
功能特性一览
能力 | 说明 | 快速入口 |
OWL 2 RL 推理引擎 | 加载 OWL 本体并物化推理;SPARQL / 类层次 / 个体 / 属性查询 |
|
业务规则 R1 / R2 / R2a / R2b / R5 / R6 | 能力匹配、任务委派、认证有效期、担责判定、人工介入、双人复核与复核候选;R4 合规冲突由适配器在分配时校验。规则层可审查、可改口径,输出可解释推导链 |
|
REST API | 72 个端点:能力查询 / 能力变更 / 解释 / 一致性 / SPARQL / CQ 集管理与依据定位 / OWL 上传 |
|
MCP Server | 同进程双端点: |
|
当前领域单页 | 六问导航:定位 / 能问什么 / 能做什么 / 凭什么可信 / 怎么接入 / 现在跑的是哪一份;示例题按「看一次编排 / 预测一次变化 / 其余示例」分组 | 页头「当前领域」 |
CQ 集页 | 题库总览(承诺 / 已定位 / 可答 / 缺口 + 两档覆盖率)、逐题增删改(题干 / 题型 / 状态 / SPARQL 断言)、变更审计、运行评估、导入导出(JSON / cq-test / JUnit) | 页头「CQ 集」 |
图谱工作台 | React 工作台:三档视图图谱、OWL 源码查看、导入导出、图谱右侧编辑框(草图预览)+ 在线编辑(写盘) |
|
CLI 双通道 | HTTP 优先、失败回退内嵌引擎( |
|
Docker 一键起 | 多阶段构建,compose 起 API + MCP |
|
学习指南 | 9 篇《本体上手指南》随仓库分发,章节↔代码对照 |
快速开始
要求:Python 3.10+(推荐 3.10–3.12,实测 3.14 亦可)、Git。
方式一:一键脚本(推荐,macOS / Linux)
cd <项目根目录>
bash scripts/start.sh # 建 venv → 装依赖 → 起服务 → 自动打开浏览器方式二:Docker
cd <项目根目录>
docker compose up # 同时起 API(:8000) 和 MCP(:9000)Dockerfile 为多阶段构建:Node 阶段自动编译前端,Python 阶段仅装运行时依赖;默认国内镜像源(npm: npmmirror / pip: 清华 TUNA)加速,均可覆盖:
docker build --build-arg NPM_REGISTRY=https://registry.npmjs.org --build-arg PIP_INDEX_URL=https://pypi.org/simple -t <镜像名> .
方式三:手动
cd <项目根目录>
# 1. 创建虚拟环境并安装依赖(首次)
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
# 2. 安装示例领域(首次必做;domains/ 是运行态目录,不随仓库分发)
.venv/bin/python scripts/ontologyctl.py domain install --from ./examples/agent_task
# 可选:安装异构示例,之后用 POST /api/domains/{name}/activate 热切换
.venv/bin/python scripts/ontologyctl.py domain install --from ./examples/onto_playground
# 3. 构建本体(可选,装好的领域包里已带 agent_task_ontology.owl)
.venv/bin/python scripts/build_ontology.py
# 4. 启动推理 API + Demo 页面
.venv/bin/uvicorn api.main:app --host 127.0.0.1 --port 8000打开浏览器访问 http://127.0.0.1:8000/#guide 即可(scripts/start.sh 会自动打开这一页;直接访问裸地址会落在图谱页,顶部有首次使用指路条)。
运行测试与一键演示
.venv/bin/python -m pytest tests/ -v # 自动化测试套件(全绿即可;项数以末行 passed 为准)
make demo # 按顺序跑一遍核心接口(需服务已启动)
make命令清单:make setup/make run/make mcp/make test/make demo/make build-ontology/make docs。
命令行工具(CLI)
scripts/query.py 提供与 API 对应的命令行查询,自动双通道:先试 HTTP(服务已启动时),连接失败则回退内嵌引擎(不依赖服务):
.venv/bin/python scripts/query.py capability_match --task t_login_dev --local
.venv/bin/python scripts/query.py classes --local
.venv/bin/python scripts/query.py query-sparql --sparql "SELECT ?i ?t WHERE { ?i <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> ?t }" --local完整命令清单见脚本帮助:.venv/bin/python scripts/query.py -h,用法教程见指南篇 5。
运维 CLI(ontologyctl)与备份
scripts/ontologyctl.py 聚合 REST API + git + MCP 探测,统一管理本体服务(003 批次 REQ-04/07):
.venv/bin/python scripts/ontologyctl.py status # 服务 + 本体状态 + MCP 进程/端口(含两端一致性)
.venv/bin/python scripts/ontologyctl.py reload # API reload + MCP kill -HUP
.venv/bin/python scripts/ontologyctl.py diff # 未提交变更预览(服务 changelog + git status)
.venv/bin/python scripts/ontologyctl.py commit -m "新增合规任务" # 本体变更入 git 并打 tag
.venv/bin/python scripts/ontologyctl.py rollback # 回滚最近本体 tag(可指定 tag)并 reload
.venv/bin/python scripts/ontologyctl.py log # git log + 服务 changelog + tags环境变量:DOUBAO_API_BASE(API 地址,默认 http://127.0.0.1:8000)、ONTOLOGY_GIT_ROOT(git 仓库根,默认项目根)。
文件级快照备份(不依赖 git):
bash scripts/backup.sh # 核心 .owl + extensions/ → backups/<时间戳>/(已被 .gitignore 忽略)前端应用(三个页面)
frontend/app/ 是基于 Microsoft Ontology-Playground(MIT)代码实现的功能完整前端:
图谱工作台:Cytoscape.js 交互图谱,三档视图——只看原始的 / 显示推理全貌(默认)/ 只看新推出的;推理新增边以虚线+独立色标注
当前领域单页:与图谱工作台平级的正式页面,按六问回答「这个包能替我做什么」——定位 / 覆盖范围 / 明确不做什么 / 能力用途(来自
guide.json)+ 运行态实测 + 对账;示例题可直接试跑(只读)或给出写盘请求预览,全部数据来自GET /api/domains/current/guide;导入自定义本体后本页整体切成「导入的本体」的只读说明CQ 集页:与上两页平级,回答「这份本体答得上什么」——题库总览(承诺 / 已定位 / 可答 / 缺口 + 两档覆盖率)、逐题增删改(题干 / 题型 / 状态 / SPARQL 断言)、变更审计、运行评估、导入导出(JSON / cq-test / JUnit);REST 与 MCP
/mcp/cq共用同一份数据,字段规格见 09 CQ 集管理页内两个标签:「题目」是上面的题库;「训练」是训练现场(首屏:状态 / 缺口 / 待决卡片 + 点选项或自由文本反馈)与下方只读时间线(训练事件 + 审计 + 回归历史 + 迭代档案四源聚合),「迭代」是时间线里的筛选按钮,显示迭代档案的业务话 / 变更摘要 / 闸门快照,TTL 全文折叠为附件
OWL 源码:RDF/XML 源码语法高亮只读查看,可下载原始文件;编辑请用「在线编辑本体定义」
导入 / 导出:拖拽上传
.owl/.rdf解析展示,导入即切换为「导入的本体」只读领域(说明 / 能力 / 示例题 / 页头一起换);导出当前模型(RDF/XML)或物化后本体(Turtle / RDF/XML)图谱右侧编辑框(草图预览):点图谱上的类 / 关系 / 个体,右侧同一块 panel 直接改;结构边按父类 / 所属类型字段重算;顶部常驻「仅预览 · 不写入系统、不进查询与推理结果」;画布工具栏可新建类 / 关系,或「添加事实」(先定短名与类型,属性值只写进导出文件)。要写入本体定义请用「在线编辑本体定义」
在线编辑本体定义:任意 OWL 本体的在线编辑——左侧分类导航(类层次 / 对象属性 / 数据属性 / 实例,带计数)+ 单一工作区(搜索、全部展开 / 折叠、新增吸底、删除收进「⋯」菜单),编辑模型由后端 rdflib 全量提取(不受前端 parser 子集限制,默认本体也可编辑);撤销 / 重做 / 脏标记 / 实时校验;保存由后端序列化 OWL 并重建引擎自动重推理,图谱视图与右侧概览联动刷新;支持生成新本体文件(写入
data/uploads/并切换为「导入的本体」只读领域)或覆盖当前本体文件(默认本体覆盖后领域推理保留,弹结构化确认框逐条说明影响),保存后可直接下载 OWL 文件物化展示:调用推理引擎物化 diff(原始断言 ∪ 推理新增),右侧「图谱概览」在未选中元素时显示「文件里声明的 / 推理后的全部 / 推出来的」三项统计
在线编辑边界:编辑模型 = 类 / 属性 / 个体子集(复杂公理如 restriction、属性链不进入表单);但保存不再重建整份文件——后端以当前文件为底图,只覆盖表单建模到的部分,未建模的公理、属性注释与字面量 datatype 原样保留,不改直接保存是无损的。写盘前自动备份到
backups/<时间戳>/(保留最近 10 份),重建失败从备份恢复原文件(「生成新本体文件」写到data/uploads/并切换为「导入的本体」只读领域)。校验规则刻意宽松(开放世界假设):id 仅要求非空且无 IRI 危险字符,中文短名 / 下划线短名合法;对象断言可指向未声明实体。
# 开发(先启动后端 :8000)
cd frontend/app
npm install
npm run dev # http://localhost:5173(/api 自动代理到 :8000)
# 生产构建(构建后由 FastAPI 托管,GET / 优先返回新前端)
npm run build # 产物 frontend/app/dist说明:导入自定义本体后点击「同步到推理引擎」即切换为框架内置的「导入的本体」只读领域——页头固定显示「导入的本体」,说明 / 示例题 / 计数一起换成这份本体;图谱 / 物化 / SPARQL / 查依据等通用只读能力可用,领域专属推理(R1 / R2 / R2a / R2b / R5 / R6)仅默认本体可用(接口返回明确提示)。V1 只读,不提供在导入本体上的新建 / 修改 / 删除;重启服务回到默认领域。
安全边界:
/api/upload是单机演示功能,接收任意.owl写入data/uploads/,无鉴权、无输入隔离——请勿把服务直接暴露到公网;如需公网部署,请自行加鉴权与上传校验。
架构
三层依赖:领域插件 SDK → 宿主(引擎与框架)→ 运行态领域包。领域包只依赖 SDK,不依赖宿主实现。
浏览器前端 / 工作台 智能体(豆包等,经 MCP 接入)
│ │
│ REST /api/* │ MCP 工具调用(30 个)
▼ ▼
推理 API(api/main.py · FastAPI) MCP Server(mcp/mcp_server.py · :9000)
└────────────── 共享同一运行态 ──────────────┘
│
DomainManager(domains/manager.py)
当前领域的唯一真相源 · 热切换的落点
L1 本体内容重载 /api/ontology/reload
L2 同包代码重载 /api/domains/reload
L3 跨包切换 /api/domains/{name}/activate
│ 构造成功才整体替换(失败保持旧领域服务)
▼
宿主 reasoner/:通用引擎 + G1–G4 闸门 + proof(不含领域词汇)
│ 只依赖下面的 SDK
▼
领域插件 SDK packages/ontology-plugin-sdk
protocol / semantic / derivation / abox / context / cq / fakes
▲ 领域包唯一依赖
▼
运行态领域包 domains/<name>/(← examples/<name> 安装)
agent_task(默认)· _minimal(零复制样板)
本体 .owl + adapter.py + config.json + shapes/*.ttl + mcp.py推理器说明:HermiT(owlready2 内置)需要 Java Runtime。本 Demo 为保证 零依赖随处可跑,推理层改用纯 Python 的 OWL 2 RL(owlrl)+ 业务规则引擎;本体仍为标准 OWL 2 文件,可在 Protege(配 Java)中直接打开并跑 HermiT 校验。
推理 API
领域模式专属端点统一挂在
/api/domains/current/前缀下:同一 URL 在热切换后指向另一个领域实现。不带该前缀的端点(通用查询 / 本体管理 / 状态探针 / 领域管理)对任意.owl可用;用旧路径调用会直接 404,不提供兼容跳转。
方法 | 路径 | 功能 |
GET |
| Demo 页面(图谱展示) |
GET |
| 健康检查 |
GET |
| 本体结构(图谱渲染数据) |
GET |
| 领域声明的图谱分组 |
GET |
| 使用视角说明( |
POST |
|
|
POST |
|
|
GET |
| 领域自声明的实体字段形状( |
POST |
|
|
POST |
| 最近一次查询的推导链(模板填槽,非公理反查;查询响应本身已带 |
POST |
| 一致性 / 合规冲突检查 |
运维 / CRUD 接口(v0.2.0 起,003 批次 REQ-04/05/06/07):
方法 | 路径 | 功能 |
POST |
| 热重载本体(新引擎构造+推理全部成功才原子替换,失败返回 400 旧状态可用) |
GET |
| 本体状态(baseline_file_hash / dirty / pending_changes / changelog / last_commit / counts;v1.5.0 起含 |
DELETE |
| 删除个体 |
POST |
| 撤销任务分配 |
POST |
| 批量导入任务个体(事务:任一校验失败整体拒绝) |
领域管理接口(v0.6.0 起,多领域与热切换):
方法 | 路径 | 功能 |
GET |
| 已安装领域 + 当前领域(name / display_name / imported / description / onto_path / capabilities / triples / mode) |
POST |
| L2 同包重载:重读领域代码 |
POST |
| L3 跨包切换:切到另一个已安装领域;失败一律 400 且旧领域继续服务 |
在线编辑接口(在线编辑本体定义;保存后自动重建引擎并重推理):
方法 | 路径 | 功能 |
GET |
| 当前本体 → 结构化编辑模型 JSON(classes/objectProps/dataProps/individuals) |
POST |
| 保存编辑模型 |
GET |
| 下载已保存的 OWL 文件(basename 白名单 + |
通用查询接口(v1.1.0 起,与本体定义无关,任意 .owl 加载后均可使用):
方法 | 路径 | 功能 |
POST |
| 执行 SPARQL |
POST |
| 指定类(含子类)的个体列表 |
POST |
| 全部类层次(name/label/parent) |
POST |
| 个体推理后的全部类型 |
POST |
| 主体-属性取值列表 |
POST |
| 重新执行推理,返回三元组/个体统计与 |
POST |
| CQ 题干 → 本体里承载它的条目(锚点 / 覆盖形态 / 证据 / 计数;只读,不调模型) |
POST |
| 加载指定 OWL 到当前引擎(自定义本体 → 「导入的本体」只读领域) |
GET |
| 物化后的本体(raw ∪ 推理新增) |
GET |
| 当前本体的 OWL/RDF 源码 |
GET |
| 导出当前模型或物化后本体(Turtle / RDF/XML) |
短名解析与个体口径(#120 / #121):
/api/types、/api/property、/api/individuals的短名按「完整 IRI → 主命名空间 → 全图唯一后缀」三级解析,IRI 带语义子目录(/dept/x、/capability/x)也能查对;三级都不中或短名有歧义时返回 400 并给出候选完整 IRI,不再把「名称拼错」伪装成空集。个体口径只有一份:显式owl:NamedIndividual∪ 以业务类为rdf:type的具名主语,/api/infer、加载/重载回执与说明页报同一个数;/api/infer的breakdown把推理新增拆成自反 / 元层 / 业务,业务为 0 时会明确说明推不出新结论。
CQ 依据定位(#124):
/api/domains/current/cq/locate用「本体术语字典 + 最长匹配 + 固定 SPARQL 模板」把一条 CQ 题干映射到承载条目,不生成查询、不调模型、不落库;coverage只会是no_anchors/gap/scattered/has_candidates,hint只报事实,不判「可答 / 不可答」。导入自定义本体后同样可用,不需要领域适配器。
SPARQL 支持边界(兼容度声明)
把边界写在明处:拿标准语法来测试前,先看这张表再判定是 Bug 还是边界。/api/query 与 MCP query_sparql 由 rdflib 实现,支持 SELECT 与 ASK(CONSTRUCT / DESCRIBE 仍不支持)——下表每一条都经实际查询验证(验证环境:默认 agent_task 本体 + rdflib 7.x,随版本演进维护):
能力 | 支持 | 实测说明 |
SELECT 基本语法(WHERE / FILTER / OPTIONAL / UNION / ORDER BY / LIMIT / OFFSET / DISTINCT / MINUS / FILTER NOT EXISTS) | ✅ | 实测通过(覆盖大部分 SPARQL 1.1 语法) |
属性路径( | ✅ | 实测通过 |
聚合与表达式(COUNT / SUM / AVG / GROUP BY、BIND、VALUES、STR / CONTAINS 等内置函数) | ✅ | 实测通过 |
子查询 | ✅ | 实测通过 |
UPDATE(INSERT / DELETE) | ❌ | 解析即拒绝。为什么不开放裸写入:本服务的写路径必须「先校验、后留痕」——更新请走 |
SERVICE(联邦查询) | ❌ | 不在支持面:运行时会尝试外呼远端端点(连不上报网络错误),但缺隔离与超时控制,不作为产品能力承诺 |
ASK( | ✅ | 返回 `{askAnswer: true |
CONSTRUCT / DESCRIBE | ❌ | 未开放:这两种形态返回图而非行/布尔,当前报错拒绝(错误文案暂为底层异常信息,改进中) |
声明兼容度是行业成品的通行底线(Apache Jena 提供
strictSPARQL严格模式开关,把「离标准多远」做成第一等信息)。demo 当前以文档声明为主,查询级的严格模式开关列为后续工作。
示例:
curl -s -X POST http://127.0.0.1:8000/api/domains/current/capabilities/query \
-H "Content-Type: application/json" \
-d '{"kind":"capability_match","params":{"task":"t_login_dev"}}'
curl -s -X POST http://127.0.0.1:8000/api/query \
-H "Content-Type: application/json" \
-d '{"sparql":"SELECT ?i WHERE { ?i a <http://ontology.localhost/agent-task#Agent> }"}'
curl -s -X POST http://127.0.0.1:8000/api/individuals \
-H "Content-Type: application/json" \
-d '{"class_name":"Task"}'架构:SDK(领域契约)→ 宿主(引擎与框架)→ 运行态领域包
三层职责清晰划分,领域包只依赖 SDK,不依赖宿主实现:
领域插件 SDK packages/ontology-plugin-sdk/
领域包唯一依赖;protocol(契约)/ semantic / derivation / abox / context / cq / fakes
▲
宿主 reasoner/
通用引擎 engine.py · 流水线闸门 pipeline_gate.py(G1–G4)· proof.py
{protocol,semantic,derivation,abox,plugin}.py 仅为兼容层,re-export SDK,勿新增逻辑
▲
运行态 domains/<name>/(由 examples/<name> 安装,.gitignore 忽略)
本体 .owl + adapter.py + config.json + derivation.json + shapes/*.ttl + mcp.py领域包契约(最小必需):
__init__.py暴露NAME/DESCRIPTION/ONTO_FILE/create_adapter_ctx(ctx),建议加PLUGIN_API = "1";本体*.owl由ONTO_FILE指向 (或取包内唯一的.owl)。adapter.py/config.json/derivation.json/shapes/*.ttl/mcp.py均可按需省略。运行时装载:
domains/manager.py的DomainManager持有"当前领域"这一个唯一真相源。 换领域不是给全局变量重新赋值,而是先构造新实例、成功后整体替换(DomainHandle不可变)—— 构造期任何异常都不会动到旧领域。热切换三级:L1 本体内容重载(
/api/ontology/reload)· L2 同包代码重载(/api/domains/reload)· L3 跨包切换(/api/domains/{name}/activate)。改了领域 Python 代码必须用 L2,L1 不会重读包代码。预置领域 / 导入的本体 / 旧版通用模式:判据是"对外服务的引擎是否就是当前领域绑定的那个"(
in_domain_mode())。 导入自定义本体后激活框架内置的imported领域(展示名「导入的本体」),说明由domains/imported.build_guide()按运行态生成并走同一份 guide 契约校验;领域专属推理不可用时接口会明确提示。generic仅作兼容保留(引擎被绕过 manager 替换时才会出现),HTTP 入口不再进入该模式。领域自带的东西由领域自己声明:能力处理器
QUERY_HANDLERS(只读)/APPLY_HANDLERS(变更)、 实体字段形状ENTITY_SCHEMA、图谱分组graph_group_members都交给领域包声明,框架不再写死进契约。 声明一个框架没预见的只读能力(例如diagnose)只要给出QUERY_HANDLERS落点即可被接纳, 需要改图的则挂APPLY_HANDLERS;同一能力名不得同时出现在两张表里(加载期拒绝)。异构领域因此 不必顺着任务编排的形状长。领域包可脱离本仓库运行:唯一依赖
ontology-plugin-sdk与rdflib,配合 SDK 的FakeEngine即可单测,无需启动宿主:
from ontology_plugin_sdk import FakeEngine, PluginContext
engine = FakeEngine(ns="http://ontology.localhost/agent-task#")
ctx = PluginContext.for_module(domain_module, engine)
adapter = domain_module.create_adapter_ctx(ctx)当前默认领域 domains/agent_task/:领域数据按关注点分两个独立 JSON——
config.json(类角色映射)、derivation.json(推导链文案模板 + 展开规则),
查询服务在 adapter.py(R2/R4 规则),MCP 领域工具注册在 mcp.py(10 个领域工具随领域包走)。
中文名标签统一来自本体 rdfs:label(引擎 label() 读取,支持 URIRef 与短名),
不再在配置中重复维护——owl 是中文名的唯一事实源。
属性名采用"语义名即本体短名"约定:属性与本体同名时无需配置(SemanticConfig.resolve() 兜底),
换本体(属性名不同)时在 config.json 覆盖即可。
语义配置与推导链展开均为引擎配套的通用机制(ontology_plugin_sdk/semantic.py 配置容器+JSON 加载、
ontology_plugin_sdk/derivation.py 声明式推导链解释器,均不含领域词汇),领域包只提供数据。
领域数据可编辑:改领域包里的 config.json 即改领域语义与推导链叙事,无需动 Python。
换领域 = 提供一个领域包(暴露 NAME / DESCRIPTION / create_adapter_ctx,依赖 ontology_plugin_sdk),
核心引擎、API、MCP、CLI 无需改动。
# 换同构本体语义:基于默认配置整体覆盖(返回新配置,原配置不可变)
from domains.agent_task import AgentTaskAdapter, DEFAULT_CONFIG
adapter = AgentTaskAdapter(get_engine(), DEFAULT_CONFIG.update(
agent_class="Worker", task_class="Job", complex_task_class="Pipeline",
has_capability="owns_skill", requires_capability="needs_skill"))推理规则
规则 | 内容 | 实现层 |
R1 能力匹配 |
| owlrl / OWL 2 RL |
R2 复合任务委派 | Agent 可执行复合任务的全部子任务 ⇒ 可执行复合任务 | 业务规则 |
R3 依赖传递 |
| owlrl / OWL 2 RL |
R4 合规冲突 | 任务要求合规认证、Agent 未认证 ⇒ 冲突报告 | 业务规则 |
目录结构
<项目根目录>/
├── packages/ontology-plugin-sdk/ # 领域插件 SDK:领域包唯一依赖,自身不依赖宿主
│ └── src/ontology_plugin_sdk/
│ ├── protocol.py # 适配器契约 AdapterProtocol / AdapterBase / 契约三态判据
│ ├── semantic.py # 语义配置容器 + JSON 加载器
│ ├── derivation.py # 声明式推导链解释器
│ ├── abox.py # ABox 事务仓库(删除/撤回/批量导入/增量落盘)
│ ├── context.py # PluginContext(引擎 + 包目录 + 配置 + 原语 + ABox 工厂)
│ ├── engine.py # EngineProtocol + local / resolve_ns
│ ├── cq/ # CQ 建模工位:出题 / 质检 / TBox 草稿(领域中立)
│ └── fakes.py # FakeEngine:领域包脱离宿主做单测
├── reasoner/ # 宿主:引擎与框架能力
│ ├── engine.py # 通用引擎(加载/推理/SPARQL/通用查询,与本体无关)
│ ├── pipeline_gate.py # G1–G4 闸门(G4 形状按当前领域包解析)
│ ├── proof.py # 结构化机读证明(build_proof)
│ └── {protocol,semantic,derivation,abox,plugin}.py # 兼容层:re-export SDK,勿新增逻辑
├── domains/ # 运行态 root(gitignore,需 domain install)
│ ├── registry.py # load_domain / 契约校验 / PLUGIN_API 版本比对
│ ├── manager.py # DomainManager:当前领域唯一真相源 + L1/L2/L3 切换
│ └── installer.py # install / uninstall 与内容哈希
├── examples/ # 随仓库分发的示例领域包(模板,不自动生效)
│ ├── agent_task/ # 完整业务领域(多能力 / R2 R4 / ABox 写入 / MCP 工具)
│ ├── _minimal/ # 零复制验收物(1 类 3 个体,0 业务方法)
│ └── onto_playground/ # 异构领域(元模型 4 公理 / 3 只读能力 / SHACL)
├── api/
│ ├── main.py # FastAPI(领域端点走适配器 + 通用端点走引擎)
│ └── schemas.py # 请求模型
├── mcp/mcp_server.py # MCP Server 通用出口(--domain 动态加载领域工具)
│ ├── policy.py # 受控语义策略(类/谓词白名单门禁),随领域包配置
│ └── tool_guard.py # 调用护栏(预算熔断/循环拦截/缓存复用/审计留痕)
├── frontend/app/ # React 工作台源码(Vite 构建产物由 API 托管)
├── scripts/
│ ├── build_ontology.py # 一键重建本体(含结构自检)
│ ├── ontologyctl.py # domain install / list / use / uninstall
│ ├── start.sh # 一键启动(venv → 依赖 → 服务 → 浏览器)
│ └── demo.sh # 一键演示(curl 串演核心接口)
├── docs/
│ └── guide/ # 《本体上手指南》9 篇(MkDocs 构建在线站点)
├── assets/demo.png # README 演示截图
├── tests/ # 推理 / API / 插件 / 热切换 / SDK 自动化测试(pytest)
├── .github/workflows/ # CI(pytest × 3.10-3.12)+ 文档站自动构建
├── Makefile / docker-compose.yml / Dockerfile / pyproject.toml
└── README.mdMCP 接入(智能体直接调用)
本体推理已封装为标准 MCP Server(mcp/mcp_server.py,内嵌引擎、复用当前领域),
同一进程内暴露两个 streamable-http 端点(/mcp 仍是 /mcp/ontology 的旧路径别名):
/mcp/ontology——本体推理:领域业务工具 10 个随领域包走(
domains/<name>/mcp.py注册):capability_match/orchestrate/assign/classify/consistency/explain/ontology/status/entities/validate_shapes引擎通用工具 16 个任意
.owl可用:query_sparql/individuals/classes/types_of/property_values/infer/explain_proof/predefined_queries/run_predefined_query/active_facts/guard_status/pipeline_gate/run_rules/list_rules/merge_check/mcp_status(MCP 自省:当前领域 / 来源 / 工具数 / 可切换领域)
/mcp/cq——CQ 集全生命周期 + 训练过程(框架级,不依赖领域包,导入裸 OWL 也可用):cq_set_read/cq_set_write/cq_case_upsert/cq_case_remove/cq_locate/cq_validate/cq_author/cq_to_schema/cq_regression/cq_audit/cq_action_complete/cq_coverage/cq_decision/cq_agenda/cq_resume/cq_timeline/cq_training_write/cq_iteration_write
CQ 工具与本体端点共享同一个 get_engine() 工厂和同一份 cq_store:回归跑的是当前
内存引擎图,不会吃到过期图;身份沿用 workspaces 的 ontology_id(导入态与 REST 同一个
工作区 uuid)。所有 CQ 错误统一返回 {ok: false, error: {code, message}}。
调用护栏在同目录 policy.py(语义白名单门禁)与 tool_guard.py(预算熔断 / 循环拦截 /
缓存复用 / 审计留痕),均随领域包配置,未启用时逐字节向后兼容。
换领域时领域工具随之更换:有 mcp.py 的领域注册自有工具;未提供 mcp.py 的领域只注册
引擎通用工具,其自有能力仍可通过 REST 调用;/mcp/cq 始终可用。--domain imported
直接绑定当前导入的本体,不需要任何领域包。
cd <项目根目录>
.venv/bin/python mcp/mcp_server.py # 默认领域;streamable-http
.venv/bin/python mcp/mcp_server.py --domain agent_task --port 9000 # 换领域
.venv/bin/python mcp/mcp_server.py --domain imported --port 9000 # 当前导入的本体
.venv/bin/python mcp/mcp_server.py --watch # 文件监听热重载(推荐)
.venv/bin/python mcp/mcp_server.py --transport stdio # stdio(本地 Client)接入豆包:侧边栏「技能 / 连接器」→ 添加 → 新建自定义连接器 → 传输类型 HTTP →
URL 填 http://127.0.0.1:9000/mcp/ontology(本体推理)或 http://127.0.0.1:9000/mcp/cq
(CQ 集管理);旧地址 http://127.0.0.1:9000/mcp 仍可连接本体推理。
与《本体上手指南》配套
仓库内 docs/guide/ 是面向零本体基础读者的 9 篇入门系列,每篇都有可复现的命令,
并在 指南首页 提供章节 ↔ 仓库代码对照表(讲哪段,去哪个文件看)。
学习路径:
概念认知 推理与图谱 服务搭建 应用与扩展
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ 00 为什么需要本体 │ → │ 03 推理原理 │ → │ 05 推理服务 │ → │ 07 协作实战 │
│ 01 本体入门 │ │ 04 与知识图谱 │ │ 06 MCP接入 │ │ 08 扩展新领域 │
│ 02 解剖示例本体 │ └─────────────┘ └─────────────┘ └─────────────┘
└─────────────┘本地看:直接打开
docs/guide/README.md操作手册:
docs/manual/(快速开始 / 推理查询 / 前端与 MCP / 运维 / 场景演练 / 二次开发 / FAQ + 速查表),与指南同一站点导航在线站点:由仓库 CI 工作流自动构建部署
开发与贡献
测试:
make test(pytest,覆盖推理规则、插件契约、热切换与 SDK 边界;全绿即可,项数以末行 passed 为准);CI 在 push / PR 时对 Python 3.10–3.12 全量跑。文档:指南用 MkDocs 构建,推送
main后由 CI 自动构建并部署文档站;本地make docs预览需 Python 3.10–3.12(当前机器 3.14 暂无 watchdog 轮子,故本地构建在 CI 上验证)。可安装包:
pip install -e .(pyproject.toml,依赖与 requirements.txt 一致)。领域插件 SDK 是 同仓库的 workspace 包,requirements.txt已含-e ./packages/ontology-plugin-sdk,会一起装上。欢迎提 Issue / PR;新增领域见指南篇 8。
备注
智能体由外部 AI 智能体(如豆包)经 MCP 连接器承担:对话 / 理解由智能体负责,本体推理由本服务负责(确定性、可解释)。
通过 API / MCP 执行「分配」会修改引擎内存中的分配记录并实时反映到图谱(assigned_to 边)。
许可证:MIT。
AI生成
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Discover, search, invoke, and rate A2A (Agent-to-Agent) protocol agents.
Discover, compare, route, and execute machine-accessible capabilities for AI agents.
Finds, connects and runs tools for agents; when a tool is missing, it assembles one from operations.
Knowledge graph for AI agents. Query concepts, walk edges, get advisories.
Related MCP Servers
- AlicenseBqualityFmaintenanceExposes OpenClaw tools (web search, page fetching, browser automation, PDF analysis, messaging, inter-agent communication, Canvas) as MCP tools for ACP agents.7-
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to interact with ontologies through the Ontology Access Kit, providing ontology querying and management capabilities.5MIT
- AlicenseNot gradedqualityDmaintenanceExposes Iceberg-backed ontology objects, links, and actions as typed MCP tools for LLM agents, enabling governed data access and operations without raw SQL.MIT
- FlicenseNot gradedqualityDmaintenanceEnables local, deterministic semantic operations on OWL/RDF ontologies, including Description Logic reasoning, SPARQL querying, TBox/ABox mutation, and interactive graph visualization via an MCP interface.2-