如何让Claude Code/Codex按需查询本体层:EvoOntology的MCP语义工具接入完全指南

原创2026-10-22 20:48:181,760 阅读

如何让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(主动访问)"原则。

EvoOntology本体层对比:无本体层的盲目数据探索与自进化本体层下的语义理解

上图直观展示了对比效果:左侧 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 和会话清单对外暴露本体 知识的"查询窗口"

EvoOntology本体层Schema Layer界面:对象类型、字段与受控关系规则

对普通用户来说,日常打交道的基本只有 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 会自动看到三样东西:

  1. 📄 资源 evo-semantic://session-manifest——会话清单,说明当前本体版本、对象规模(多少术语、多少映射、多少生效约束)以及工具用法;
  2. 🔍 工具 browse_semantics——发现与分析需求相关的语义概念;
  3. 🎯 工具 resolve_semantics——把选中的概念解析为落地的字段映射 + 关联关系/约束/证据。

工具清单与参数定义统一维护在 evoontology/runtime/tools.py,服务端实现见 evoontology/runtime/mcp_server.py。

EvoOntology本体层Tool Layer界面:browse_semantics、resolve_semantics工具与会话清单

四、两个核心语义工具详解

完整的交互协议写在 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)。

EvoOntology框架图:Data Agent本体交互、构建器接地构建、诊断归因与候选版本门控发布

版本发布前会自动经过 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 的最终结论必须建立在真实查询之上。

✅ 三条实用建议

  1. 会话开始先读 manifest,用它判断当前本体规模是否值得深入查询;
  2. resolve_semantics 是主力工具——直接传你打算使用的概念;browse_semantics 只用于"我不知道有什么可用"的场景;
  3. 定期触发 /evo-evolve:本体层是"可训练的 Agent 状态",越用越准的前提是持续用真实轨迹校准。

总结

EvoOntology 给 Claude Code / Codex 装上了一个"可生长的大数据大脑":通过 MCP 的 evo-semantic 服务零配置接入,session-manifest + browse_semantics + resolve_semantics 三个接口实现按需语义查询,配合轨迹驱动的进化闭环让本体层随业务持续更新。对新手的价值一句话概括——让 AI 助手查数前先"看懂业务",而且这份"懂"会自己变聪明。

登录后查看全文
EvoOntology