Skip to main content
Glama
ontology-agent-demo MCP Server

ontology-agent-demo MCP Server

by jasony62

本体 × 智能体协作 Demo

演示本体(Ontology)如何与智能体(Agent)配合:用户用自然语言提问,智能体负责理解与编排(把问题翻译成对推理 API 的调用),本体负责给出确定性、可解释的推理结论,智能体再把结论组织成回答。全程可视化展示「事实 → 规则 → 结论」的推导链。

一句话定位:把本体推理能力打包成一个开箱即用的工具——一条命令起服务,MCP 接入智能体,配套 9 篇《本体上手指南》边学边跑。

Demo 页面

第一次用:点右上角「当前领域」→ 第 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 / 类层次 / 个体 / 属性查询

scripts/query.py classes --local

业务规则 R1 / R2 / R2a / R2b / R5 / R6

能力匹配、任务委派、认证有效期、担责判定、人工介入、双人复核与复核候选;R4 合规冲突由适配器在分配时校验。规则层可审查、可改口径,输出可解释推导链

make demo

REST API

72 个端点:能力查询 / 能力变更 / 解释 / 一致性 / SPARQL / CQ 集管理与依据定位 / OWL 上传

http://127.0.0.1:8000/api-docs(在线文档,含请求与响应说明)

MCP Server

同进程双端点:/mcp/ontology(领域业务 10 + 引擎通用 16)与 /mcp/cq(CQ 18),合计 44,智能体(豆包等)一行配置接入

make mcp

当前领域单页

六问导航:定位 / 能问什么 / 能做什么 / 凭什么可信 / 怎么接入 / 现在跑的是哪一份;示例题按「看一次编排 / 预测一次变化 / 其余示例」分组

页头「当前领域」

CQ 集页

题库总览(承诺 / 已定位 / 可答 / 缺口 + 两档覆盖率)、逐题增删改(题干 / 题型 / 状态 / SPARQL 断言)、变更审计、运行评估、导入导出(JSON / cq-test / JUnit)

页头「CQ 集」

图谱工作台

React 工作台:三档视图图谱、OWL 源码查看、导入导出、图谱右侧编辑框(草图预览)+ 在线编辑(写盘)

npm run dev

CLI 双通道

HTTP 优先、失败回退内嵌引擎(--local 零依赖)

python scripts/query.py -h

Docker 一键起

多阶段构建,compose 起 API + MCP

docker compose up

学习指南

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

/api/health

健康检查

GET

/api/domains/current/ontology

本体结构(图谱渲染数据)

GET

/api/domains/current/ontology/graph-groups

领域声明的图谱分组 {groups: [{name, class, label, members}]};前端据此上色与出图例,未声明时为空数组

GET

/api/domains/current/guide

使用视角说明(guide.json 声明 + 运行态实测 + 对账);当前领域页唯一数据源,含 display_name / imported、examples[].safe 与 runtime.mcp

POST

/api/domains/current/capabilities/query

{type, task, agent, params};纯读,不改图、不落盘、可安全重试。内置 capability_match / orchestrate,领域可通过 QUERY_HANDLERS 追加只读能力(参数放 params)

POST

/api/domains/current/capabilities/apply

{type, task, agent, persist, params};会改图,persist=true 落 extensions/,不保证幂等。内置 assign,领域可通过 APPLY_HANDLERS 追加变更能力

GET

/api/domains/current/entities/schema

领域自声明的实体字段形状(ENTITY_SCHEMA),先看它再 POST /api/domains/current/entities

POST

/api/domains/current/entities

{payload, persist?};字段形状由领域的 ENTITY_SCHEMA 声明

POST

/api/domains/current/explain

最近一次查询的推导链(模板填槽,非公理反查;查询响应本身已带 derivation)

POST

/api/domains/current/consistency

一致性 / 合规冲突检查

运维 / CRUD 接口(v0.2.0 起,003 批次 REQ-04/05/06/07):

方法

路径

功能

POST

/api/ontology/reload

热重载本体(新引擎构造+推理全部成功才原子替换,失败返回 400 旧状态可用)

GET

/api/ontology/status

本体状态(baseline_file_hash / dirty / pending_changes / changelog / last_commit / counts;v1.5.0 起含 mode:default=默认本体 / imported=导入的本体 / generic=旧版通用模式)

DELETE

/api/domains/current/ontology/individual/{name}

删除个体 ?persist&cascade(被引用时保护,cascade 连带清理反向引用)

POST

/api/domains/current/ontology/revoke

撤销任务分配 {task, agent, persist}

POST

/api/domains/current/ontology/import

批量导入任务个体(事务:任一校验失败整体拒绝){individuals, persist}

领域管理接口(v0.6.0 起,多领域与热切换):

方法

路径

功能

GET

/api/domains

已安装领域 + 当前领域(name / display_name / imported / description / onto_path / capabilities / triples / mode)

POST

/api/domains/reload

L2 同包重载:重读领域代码 adapter.py / config.json 并重建引擎;失败返回 400 且旧领域可用

POST

/api/domains/{name}/activate

L3 跨包切换:切到另一个已安装领域;失败一律 400 且旧领域继续服务

在线编辑接口(在线编辑本体定义;保存后自动重建引擎并重推理):

方法

路径

功能

GET

/api/ontology/edit-model

当前本体 → 结构化编辑模型 JSON(classes/objectProps/dataProps/individuals)

POST

/api/ontology/save

保存编辑模型 {model, filename, mode: "new"|"overwrite"};new 写入 data/uploads/ 并切换为「导入的本体」只读领域,overwrite 覆盖当前本体(默认本体重建领域推理);返回 {status, path, filename, mode, stats, materialized}

GET

/api/ontology/download?name=

下载已保存的 OWL 文件(basename 白名单 + data/uploads/ 限定,防路径穿越)

通用查询接口(v1.1.0 起,与本体定义无关,任意 .owl 加载后均可使用):

方法

路径

功能

POST

/api/query

执行 SPARQL {sparql}:SELECT 返回结果行,ASK 返回 askAnswer;IRI 自动转短名

POST

/api/individuals

指定类(含子类)的个体列表 {class_name}

POST

/api/classes

全部类层次(name/label/parent)

POST

/api/types

个体推理后的全部类型 {individual}

POST

/api/property

主体-属性取值列表 {subject, property}

POST

/api/infer

重新执行推理,返回三元组/个体统计与 breakdown(自反 / 元层 / 业务)

POST

/api/domains/current/cq/locate

CQ 题干 → 本体里承载它的条目(锚点 / 覆盖形态 / 证据 / 计数;只读,不调模型)

POST

/api/ontology/load

加载指定 OWL 到当前引擎(自定义本体 → 「导入的本体」只读领域)

GET

/api/ontology/materialized

物化后的本体(raw ∪ 推理新增)

GET

/api/ontology/source

当前本体的 OWL/RDF 源码

GET

/api/ontology/export

导出当前模型或物化后本体(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 语法)

属性路径(+ / * / / / ^ 等,如依赖闭包 depends_on+)

✅

实测通过

聚合与表达式(COUNT / SUM / AVG / GROUP BY、BIND、VALUES、STR / CONTAINS 等内置函数)

✅

实测通过

子查询

✅

实测通过

UPDATE(INSERT / DELETE)

❌

解析即拒绝。为什么不开放裸写入:本服务的写路径必须「先校验、后留痕」——更新请走 /api/domains/current/entities、/api/domains/current/ontology/import、MCP assign / classify 等任务接口(带事务与变更记录),而不是让数据「改完就走」

SERVICE(联邦查询)

❌

不在支持面:运行时会尝试外呼远端端点(连不上报网络错误),但缺隔离与超时控制,不作为产品能力承诺

ASK(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 能力匹配

has_capability ◦ required_by ⊑ can_execute(属性链)

owlrl / OWL 2 RL

R2 复合任务委派

Agent 可执行复合任务的全部子任务 ⇒ 可执行复合任务

业务规则

R3 依赖传递

depends_on 传递闭包

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.md

MCP 接入(智能体直接调用)

本体推理已封装为标准 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…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to interact with ontologies through the Ontology Access Kit, providing ontology querying and management capabilities.
      5
      MIT