cd ontology-agent-demo
bash scripts/start.sh        # 建 venv → 装依赖 → 起服务 → 自动打开浏览器

cd ontology-agent-demo
docker compose up            # 同时起 API(:8000) 和 MCP(:9000)

cd ontology-agent-demo

# 1. 创建虚拟环境并安装依赖（首次）
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

# 2. 构建本体（可选，仓库已内置 domains/agent_task/agent_task_ontology.owl）
.venv/bin/python scripts/build_ontology.py

# 3. 启动推理 API + Demo 页面
.venv/bin/uvicorn api.main:app --host 127.0.0.1 --port 8000

.venv/bin/python -m pytest tests/ -v      # 38 项测试
make demo                                  # 按顺序跑一遍核心接口（需服务已启动）

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

bash scripts/backup.sh        # 核心 .owl + extensions/ → backups/<时间戳>/（已被 .gitignore 忽略）

# 开发（先启动后端 :8000）
cd frontend/app
npm install
npm run dev                 # http://localhost:5173（/api 自动代理到 :8000）

# 生产构建（构建后由 FastAPI 托管，GET / 优先返回新前端）
npm run build               # 产物 frontend/app/dist

浏览器前端（图谱展示）              智能体（豆包等，经 MCP 接入）
        │                                │
        │ ① /api/ontology 图谱数据       │ ① MCP 工具调用（能力匹配/编排/分配…）
        ▼                                ▼
推理 API（api/main.py · FastAPI）◄─────── MCP Server（mcp/mcp_server.py · :9000）
   /api/ontology /api/reason /api/classify /api/explain /api/consistency
        │ ② 触发推理（领域适配器）
        ▼
通用引擎（reasoner/engine.py）
  L1 OWL 2 RL（owlrl）：R1 属性链、R3 传递闭包
  L2 领域适配器（domains/agent_task）：R2 复合任务委派、R4 合规冲突
  L3 查询服务 + 推导链
        │ ③ 加载并推理
        ▼
本体模型（domains/agent_task/agent_task_ontology.owl · OWL 2）
  类层次 / 属性约束 / 推理公理 / 演示个体

curl -s -X POST http://127.0.0.1:8000/api/reason \
  -H "Content-Type: application/json" \
  -d '{"type":"capability_match","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://demo.example.org/agent-task-ontology#Agent> }"}'

curl -s -X POST http://127.0.0.1:8000/api/individuals \
  -H "Content-Type: application/json" \
  -d '{"class_name":"Task"}'

from reasoner.engine import get_engine
from domains import list_domains, load_domain

list_domains()                      # 枚举可用领域：[{"name","description","module"}, ...]
adapter = load_domain("agent_task", get_engine())   # 按名加载适配器
adapter.capability_match(adapter.NS["t_login_dev"]) # 领域查询
get_engine().individuals("Task")    # 通用查询（任意本体可用）

# 换同构本体语义：基于默认配置整体覆盖（返回新配置，原配置不可变）
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"))

ontology-agent-demo/
├── reasoner/
│   ├── engine.py                      # 通用引擎（加载/推理/SPARQL/通用查询，与本体无关）
│   ├── semantic.py                    # 通用语义配置（不可变键值容器 + JSON 加载器，零领域词汇）
│   └── derivation.py                  # 通用推导链解释器（声明式步骤规则展开，零领域词汇）
├── domains/                           # 领域适配器（独立目录，运行时动态加载）
│   ├── __init__.py                    # list_domains / load_domain 注册表
│   └── agent_task/                    # 「智能体任务编排」领域（自包含）
│       ├── agent_task_ontology.owl    # 本体定义（Protege 可打开，核心定义）
│       ├── extensions/                # 增量扩展目录（REQ-06：classify/assign 持久化块，按文件名排序加载）
│       ├── __init__.py                # 纯导出（NAME/DESCRIPTION/ONTO_FILE/EXTENSIONS_DIR/适配器符号）
│       ├── adapter.py                 # 领域适配器（R2/R4 规则 + 5 个查询方法 + 图谱导出 + 增量持久化）
│       ├── config.json                # 领域语义配置（类角色映射/结构数据；中文名见 owl rdfs:label，属性名默认同本体短名）
│       ├── derivation.json            # 领域推导链配置（文案模板 templates + 展开规则 derivations）
│       └── mcp.py                     # 领域 MCP 工具注册（8 个领域工具，register_tools）
├── api/
│   ├── main.py                        # FastAPI（领域端点走适配器 + 通用端点走引擎）
│   └── schemas.py                     # 请求模型
├── mcp/mcp_server.py                  # MCP Server 通用出口（--domain 动态加载领域工具 + 6 个通用工具）
├── frontend/index.html                # 图谱可视化展示页
├── scripts/
│   ├── build_ontology.py              # 一键重建本体（含结构自检）
│   ├── start.sh                       # 一键启动（venv → 依赖 → 服务 → 浏览器）
│   └── demo.sh                        # 一键演示（curl 串演核心接口）
├── docs/
│   └── guide/                         # 《本体上手指南》9 篇（MkDocs 构建在线站点）
├── assets/demo.png                    # README 演示截图
├── tests/                             # 推理 + API + 增量持久化自动化测试（pytest）
├── .github/workflows/                 # CI（pytest × 3.10-3.12）+ GitHub Pages
├── Makefile / docker-compose.yml / Dockerfile / pyproject.toml
└── README.md

cd ontology-agent-demo
.venv/bin/python mcp/mcp_server.py --domain agent_task --port 9000   # 默认 agent_task；streamable-http
.venv/bin/python mcp/mcp_server.py --transport stdio                 # stdio（本地 Client）

概念认知            推理与图谱            服务搭建            应用与扩展
┌─────────────┐   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐
│ 00 为什么需要本体 │ → │ 03 推理原理    │ → │ 05 推理服务   │ → │ 07 协作实战   │
│ 01 本体入门     │   │ 04 与知识图谱  │   │ 06 MCP接入   │   │ 08 扩展新领域 │
│ 02 解剖示例本体 │   └─────────────┘   └─────────────┘   └─────────────┘
└─────────────┘