如何让Claude Code/Codex按需查询本体层:EvoOntology的MCP语义工具接入完全指南
如何让Claude Code/Codex按需查询本体层:EvoOntology的MCP语义工具接入完全指南
EvoOntology 是面向数据 Agent 的自进化本体层(Self-Evolving Ontology Layer),它通过 MCP(Model Context Protocol)语义工具,让 Claude Code、Codex 等 AI 编程助手在分析数据时按需查询业务概念、字段映射和约束证据,而不是把整份语义文档硬塞进上下文。本文用零代码的方式讲清楚:接入原理、安装步骤、两个核心工具怎么配合工作,以及最佳实践。
一、为什么是"按需查询"而不是"整份注入"?
先理解 EvoOntology 要解决的问题。当 Data Agent 面对表格、CSV、数据库、日志等异构数据源时,最大的困难往往不是"查不到数据",而是语义不确定:labor_expense 到底是人工成本还是制造费用?"毛利率"的定义是否扣除了 FX(汇率)影响?这些业务知识散落在文档和人的脑子里,Agent 只能反复猜测。
传统做法是把语义层(术语表、指标口径、字段映射)整份写进系统提示。但静态语义层有两个硬伤:
- 上下文膨胀:语义层越大,每次对话消耗越多 token,无关内容还干扰推理;
- 维护成本高:数据和业务一变,人工维护的口径就过期了。
EvoOntology 的设计思路是:本体层是一个"可查询的库",而不是一段"注入的文本"。会话开始时 Agent 只拿到一份几行字的会话清单(session manifest),需要哪个概念再去查哪个——这就是"Active access(主动访问)"原则。
上图直观展示了对比效果:左侧 Agent 直接对着异构数据源"盲猜",充满问号;右侧有了 EvoOntology 本体层后,Data Agent 通过本体交互获得有数据依据的理解(Grounded Data Understanding),并持续自我进化。
二、本体层三层结构:Tool Layer 是 Agent 的"查询窗口"
EvoOntology 把本体层分成三个互相关联的层,理解它们有助于明白 MCP 工具能查到什么(架构细节见 docs/architecture.md):
| 层 | 角色 | 类比 |
|---|---|---|
| Content Layer(内容层) | 类型化语义图:术语(Term)、映射(Mapping)、约束(Constraint)、证据(Evidence)四类节点 | 知识本身 |
| Schema Layer(模式层) | 定义四类节点的字段、允许的关系类型与引用规则 | 知识的"数据字典" |
| Tool Layer(工具层) | 通过 browse_semantics、resolve_semantics 和会话清单对外暴露本体 |
知识的"查询窗口" |
对普通用户来说,日常打交道的基本只有 Tool Layer:它是 Data Agent 唯一需要"学习"的接口面,另外两层由构建/进化流程自动维护。
三、MCP 接入快速上手:零配置自动拉起
MCP(Model Context Protocol)是 AI 客户端与外部工具服务的标准协议。EvoOntology 插件把语义服务声明为 MCP server,客户端会自动拉起进程,无需手动启动、无需 clone 仓库、无需 pip install。
3.1 Claude Code:三行命令安装插件
claude plugin marketplace add ruc-datalab/EvoOntology
claude plugin install evoontology@evoontology
claude plugin list
以 plugin list 显示已安装为准。MCP 配置由插件内的 .mcp.json 声明:它通过跨平台启动器 launch-evoontology 自动运行内置的 MCP 服务 mcp_server.py,默认读取当前项目根下的 .evoontology/ 工作区,零配置。安装细节见 plugins/claude-code/README.md。
3.2 Codex:同样三条命令
codex plugin marketplace add ruc-datalab/EvoOntology
codex plugin add evoontology-codex@evoontology
codex plugin list
Codex 侧的 .mcp.json 声明了同样的 evo-semantic 服务,接入方式见 plugins/evoontology-codex/README.md。
3.3 安装后 Agent 能看到什么?
会话开始后,Data Agent 会自动看到三样东西:
- 📄 资源
evo-semantic://session-manifest——会话清单,说明当前本体版本、对象规模(多少术语、多少映射、多少生效约束)以及工具用法; - 🔍 工具
browse_semantics——发现与分析需求相关的语义概念; - 🎯 工具
resolve_semantics——把选中的概念解析为落地的字段映射 + 关联关系/约束/证据。
工具清单与参数定义统一维护在 evoontology/runtime/tools.py,服务端实现见 evoontology/runtime/mcp_server.py。
四、两个核心语义工具详解
完整的交互协议写在 ontology-interaction-protocol.md,核心要点如下。
4.1 browse_semantics:先"发现"
什么时候用:你还不知道本体里存了哪些概念,需要先"逛一圈"。
| 参数 | 说明 |
|---|---|
query(必填) |
分析需求描述,如"影响利润率的成本因素" |
kind |
过滤类型:term / mapping / relation / constraint / all |
limit |
返回条数上限,1~6,默认 6 |
version |
可选,指定本体版本,缺省用当前激活版本 |
返回的是概念目录(名称、定义、类型),帮你确定该用哪些术语去解析。注意它是有界导航辅助:最多返回 6 条,避免一次性倾倒整个词表。
4.2 resolve_semantics:再"落地"
什么时候用:你已经确定了要用的概念,需要知道它对应哪张表、哪个字段、有什么限制。
| 参数 | 说明 |
|---|---|
mentions(必填) |
概念名列表,最多 5 个,如 ["labor cost"] |
context |
上下文,帮助消歧,如"公司盈利能力分析" |
workspace / version |
可选,指向特定工作区/版本 |
返回每个概念的状态与 grounding 映射(表名、列名)、适用约束(如"2018 年之后可用")和支撑证据。拿到映射后,Agent 再用原生的 SQL/Python 工具去查真实数据验证——语义结果是导航,不是最终答案。
4.3 推荐的查询节奏
读取 session-manifest(自动)
↓
不确定概念 → browse_semantics 发现
↓
概念确定 → resolve_semantics 落地映射
↓
原生工具查询数据库验证证据 → 产出结论
这不是死板流程,而是"语义工具在有价值时才调用"的原则。清单里也明确写着:"Resolved mappings are guidance, not final answers"。
五、从查询到进化:本体层如何持续变好
按需查询只是使用闭环的一半。EvoOntology 的另一半是自进化:每次任务的工具调用轨迹会记录到 .evoontology/trajectories/,当新增任务达到阈值(默认 30 个或 7 天)时,Claude Code 的 Session Start hook 会注入提醒,你运行 /evo-evolve 即可触发进化会话——诊断历史错误 → 归因到 Content/Tool/Schema 某一层 → 生成局部补丁 → 评估门控(只有可复现的改进才发布为新版本 ontology_vN+1)。
版本发布前会自动经过 validate_semantics 确定性校验(JSON 合法、引用完整、可加载),你也可以随时用 /evo-visualize 生成离线交互式 HTML 浏览器,只读查看各版本的语义图与版本差异。完整工作流参考 USAGE.md。
六、常见问题与最佳实践
❓ 插件-only 安装需要在项目里跑 Python 代码吗?
不需要。构建、进化、可视化所需的确定性操作(如 validate_semantics、visualize_ontology、accept_evolution)都通过同一个 MCP 服务暴露,客户端自动拉起。
❓ 可以指向别的项目工作区吗?
可以。默认是当前项目的 .evoontology/;如需指向别处,在 .mcp.json 的 args 里追加 --store <workspace-root> 即可。
❓ 语义工具和原生数据工具是什么关系? 互补,不替代。语义工具负责"概念 grounding",SQL、Python 等原生工具负责证据收集;Agent 的最终结论必须建立在真实查询之上。
✅ 三条实用建议
- 会话开始先读 manifest,用它判断当前本体规模是否值得深入查询;
resolve_semantics是主力工具——直接传你打算使用的概念;browse_semantics只用于"我不知道有什么可用"的场景;- 定期触发
/evo-evolve:本体层是"可训练的 Agent 状态",越用越准的前提是持续用真实轨迹校准。
总结
EvoOntology 给 Claude Code / Codex 装上了一个"可生长的大数据大脑":通过 MCP 的 evo-semantic 服务零配置接入,session-manifest + browse_semantics + resolve_semantics 三个接口实现按需语义查询,配合轨迹驱动的进化闭环让本体层随业务持续更新。对新手的价值一句话概括——让 AI 助手查数前先"看懂业务",而且这份"懂"会自己变聪明。



