本体管理平台使用说明 #

面向：数据产品经理、指标/口径负责人、智能问数与智能体的知识工程师

目录 #

• 一、这个平台解决什么问题
• 二、边界：本体做什么、不做什么
• 三、入口与权限
• 四、元模型：核心对象类型
• 五、四层建模方法论
• 六、建模实操（以销售域为例）
• 七、发布审批流
• 八、本体方法
• 九、知识供给：智能体怎么用
• 十、本体项目：多项目隔离
• 十一、Excel 批量维护
• 十二、画布操作说明
• 十三、常见问题
• 十四、名词解释

一、这个平台解决什么问题 #

智能问数和智能体在真实业务里最容易出错的不是数据查不到，而是猜错业务含义：

• 用户问「上个月各城市的成交额」，模型不知道「成交额」的统计口径，于是用了错误的字段；
• 用户问「VIP 客户的商品」，模型不知道 VIP 客户是客户的子类，也不会规划正确的关联路径；
• 用户说「取消这笔订单」，模型没有任何地方可以查到「取消」这个动作该怎么执行。

本体平台把企业的业务语义沉淀成一张可查询、可推理的知识图谱，让智能体能准确理解业务含义：

业务人员口语 ──术语层──▶ 标准概念
                          │
                 属性（口径/单位/枚举）
                 关系（继承/组成/因果…）
                 公理（计算口径、业务规则）
                 实例（样例数据）
                 方法（可执行操作：算 / 调 / 改）
                          │
                          ▼
                智能问数 / 智能体框架获取知识上下文

二、边界：本体做什么、不做什么 #

这是使用本平台最重要的一节。

所以：

• 想让智能体知道某个概念对应哪些数据 → 写在「落地提示」里，它会出现在智能体的知识上下文中；
• 想让智能体真的算出来 → 挂一个方法，把计算逻辑写进去，由智能体框架负责执行；
• 平台本身不会替你查数。

三、入口与权限 #

对象状态流转：草稿 → 审批中 → 已发布 / 已驳回（回退草稿） → 已下线。

核心规则：智能体只能看到「已发布」状态的对象；草稿和审批中的对象不会出现在任何知识供给中。

四、元模型：核心对象类型 #

统一约定：每个本体对象都带有状态、负责人、创建/更新时间、业务域等公共字段。

除以下 7 类核心对象外，还有「本体项目」用于命名空间隔离（详见 第十章），以及「审批记录」和「操作日志」用于流程管理。

1. 本体类（概念） #

2. 数据属性（类的字段） #

每个类下可定义多个属性，同一类内属性编码不重复。关键字段：数据类型（字符串/整数/小数/日期/布尔/枚举等）、单位、枚举值（含同义词）、别名、是否唯一标识、是否可聚合度量、时间语义、是否可为空、落地提示、描述。

枚举的同义词很实用：给「已支付」加上「付款/成交」作为同义词，智能体听到「成交订单」也能正确匹配。

3. 对象属性（语义关系） #

连接两个类：起点类 -[动词]→ 终点类。

• 关系类型：继承（is_a）/ 组成（part_of）/ 包含（has_a）/ 关联（relates_to）/ 导致（causes）/ 位于（locates_in）/ 归属（belongs_to）/ 产出（produces）
• 基数：1:1 / 1:N / N:1 / N:N
• 反向关系：如「下单」↔「属于」
• 传递性 / 对称性 / 单值性：影响路径推理
• 约束：自然语言描述，会拼进智能体提示
• 落地提示：关联的数据线索

选择「继承」类型保存时，会自动设置父类并重算层级，无需手工维护。

4. 术语词典（问数消歧核心资产） #

术语 + 业务域唯一。每个术语指向一个已有的本体对象（类、属性、关系、公理、实例或方法），保存时会校验目标是否存在。同义词用于收纳业务各种口语叫法。

一句话：术语把「黑话」翻译成标准对象。智能体消歧的命中优先级 = 精确术语 → 同义词 → 类/属性名或别名 → 模糊包含。

5. 公理规则 #

• 类型：计算口径 / 一致性 / 取值范围 / 业务规则 / 命名规范
• 约束主体：关联的类（可空 = 全局规则）
• 表达式：伪公式
• 自然语言描述：决定智能体理解质量，务必写清楚
• 严重级别：强制 / 建议
• 示例：辅助说明

6. 本体实例 #

属于某个类的具体样例，包含名称、所属类和属性标签值。用于给智能体展示真实样本长什么样，提升理解准确率。

7. 本体方法（动词层） #

见 第八节。

五、四层建模方法论 #

建议按顺序做，每层做完就能立刻在管理台的「供给自检」里验证效果。

第 1 层：域 + 概念骨架（30 分钟）

1. 定业务域（如「销售」「供应链」），一个域一套概念，不要跨域复用编码。
2. 先画顶层类（5~15 个），只写编码、名称、业务定义、落地提示。
3. 再补继承关系（子类自动获得父类与层级）。只为继承存在的类标记为抽象类。

第 2 层：属性与关系 4. 每个类挑业务上会被问到的属性，不要照抄全表字段。优先标记「可聚合度量」与「唯一标识」。 5. 枚举属性把取值与别名写全。 6. 关系先建「智能体真的会跨」的那几条，动词用一个字（如：下单/包含/归属），画布上直接显示。

第 3 层：术语与公理（性价比最高） 7. 术语表把业务的所有叫法收进来：GMV、成交额、销售额、流水 → 同一个属性。 8. 公理写口径：用一句人话写清「统计什么、排除什么、按什么算」，强约束标记为「强制」。

第 4 层：方法与技能导出 9. 高频算法（成交额、动销率、库存周转）做成方法，写清入参、前置条件和效果。 10. 有副作用的动作（取消订单、发起退款）用 HTTP 方法并标记「需要确认」。 11. 发布后通过「导出技能」功能，直接把工具清单注册进智能体。

质量标尺：拿 10 个真实业务提问，在管理台「供给自检」里测试，看返回的知识块是否已包含回答该问题所需的全部口径 —— 缺什么就补什么（通常缺的是术语和公理，而不是概念）。

六、建模实操（以销售域为例） #

录入时的三个约定 #

• 先选项目：进入画布/管理台第一件事是顶栏右上角的项目切换器定到目标项目（或「全部项目」做跨项目盘点）。之后新建的一切默认就落在它下面，不用每次选。
• 编码不用想：编码一律可留空。保存时系统按名称自动生成；更新时留空则沿用原编码，不会改号。表单里名称输入框失焦即预填，保存成功也会把最终编码回显出来。
• 业务域用下拉，不用手打：所有表单的业务域都是可输入可下拉的选择框，列出库里已有的域（带类数）；输入不存在的名字会当作新域创建。

建模示例 #

类    客户 / 订单 / 商品 / VIP客户（继承客户）
属性  订单.支付金额（小数, 元, 可聚合度量, 落地提示: amt_pay）
      订单.订单状态（枚举: 1=已支付(同义词:付款/成交) 0=未支付）
关系  客户 -[下单]→ 订单      (关联, 1:N, 约束：一个订单只属于一个客户)
      订单 -[包含]→ 商品      (包含, N:N)
      VIP客户 -[是一种]→ 客户  (继承)
术语  成交额 / GMV / 销售额 → 属性: 支付金额
      顾客 / 客人 → 类: 客户
公理  GMV规则（计算口径, 强制）：成交额只统计已支付订单的支付金额之和
方法  计算成交额（SQL模板）：汇总指定业务日期的已支付订单一支付金额

发布后，智能体问「上个月各城市的成交额是多少」会获取到这样的知识上下文（节选）：

【业务本体】
概念：订单；同义词：成交单；落地：ods.ord_order
  属性：订单.支付金额[小数]，单位：元，可聚合度量；落地：amt_pay
  属性：订单.订单状态[枚举: 已支付/未支付]
概念：VIP客户；是一种：客户
关系：客户 -[下单]→ 订单（1:N），约束：一个订单只属于一个客户
关系：订单 -[包含]→ 商品（N:N）
方法：计算成交额（入参: 业务日期）→ 成交额；类型：SQL模板；前置：已确定统计日期
规则[计算口径]：成交额只统计已支付订单的支付金额之和（强制）
术语：“成交额” = 支付金额

七、发布审批流 #

平台采用「申请 → 审批 → 生效」的简单审批模型：

1. 提交：画布顶栏「提交发布」或管理台各 Tab 的行内「提交发布」。支持批量提交，对象状态置为「审批中」。
2. 查看：管理台「审批中心」，三种范围：待我审 / 我提交的 / 历史；按批次聚合展示，附提交时的对象内容快照。
3. 批复：通过 → 对象变为「已发布」，智能体立即可见；驳回 → 回退「草稿」并记录审批意见。支持整批批复。
4. 管理员直发：跳过审批，用于纠错与初始化灌数据。
5. 下线：下线后智能体立即不可见，走审批或直接操作。

审批中的对象不会出现在任何知识供给中 —— 这是防止半成品口径污染智能体的关键。

八、本体方法 #

方法是本体的「动词层」，让智能体从「能查、能懂」升级到「能算、能做」。

挂载位置（三者至少填一个） #

四种方法类型 #

副作用与确认 #

方法可标记副作用类型：无副作用 / 写数据 / 调用外部系统；另有「需要确认」开关。

有副作用或标记需确认的方法：

• 导出工具时会带「需确认」标记，智能体侧必须先向用户确认再调用；
• 知识上下文中该方法会标注「（调用需人工确认）」。

试跑注意 #

• 试跑仅允许在画布或管理台登录后操作，智能体无法直接触发试跑。
• SQL 试跑只允许只读语句（查询、显示结构等），写操作会被拦截。
• Python 方法只能使用已注册的白名单函数。

九、知识供给：智能体怎么用 #

本体平台通过一组知识供给接口为智能体提供业务语义支持，主要能力包括：

对接方式（两种，任选）：

1. 注册工具让模型自己调：把导出的工具清单直接注册到智能体框架，模型会按需调用知识接口。
2. 前置注入：在业务提问进入模型前，固定调一次知识上下文，把结果拼进系统提示。省一次工具往返，召回稳定。

关于方法执行：导出的工具只有定义、没有平台执行端。智能体需要按参数说明自己完成落地调用；平台侧只保留试跑功能给建模者验证。

十、本体项目：多项目隔离 #

一套本体库里往往要同时服务好几个客户/场景：零售、供应链、财务指标口径各不相同。项目就是本体层的命名空间，用来把这些资产彻底隔开。

10.1 隔离规则 #

• 每个项目内，类编码唯一；项目 A 和项目 B 可以有同名类，不冲突。
• 术语、公理、审批等均按项目隔离。
• 属性、关系、实例、方法不单独归属项目，而是跟随它们所属的类自动继承项目归属，类迁移时自动跟着走。
• 删项目是级联的，类、术语、公理连同从属资产一起删除，不可恢复。

10.2 公共区 #

未指定项目的对象属于公共区：所有项目都能看到、都能引用（比如通用的「时间」「组织」「货币」类）。规则是本项目的对象 + 公共区对象取并集，永远不会串到别的项目里去。

10.3 怎么用 #

画布和管理台顶栏都有项目切换器，选中后下次进页面自动恢复。

下拉里还有一个「全部项目（合并视图）」选项，用于跨项目盘点：此时每个类节点卡片头部会挂一个项目角标，标明它属于哪个项目。

切换项目会重载整页所有 Tab，不需要刷新浏览器。

10.4 类归属怎么改 #

• 新建：默认落在「当前项目」下；如果当前是「全部项目」视图，则落到公共区。
• 迁移：右栏类表单里的「归属项目」下拉可直接改，保存即迁移 —— 该类以及挂在它上面的属性、方法会一并迁过去。
• 约束：跨项目不能建立继承与关系 —— 父类必须同项目或属于公共区，提交时会拦截。方案间的复用请把共享概念提到公共区。

10.5 智能体的项目隔离 #

知识供给接口支持指定项目，取值规则：

智能体忘带项目参数也不会串到别的项目，但建议显式指定，语义更明确。

十一、Excel 批量维护 #

本体大概率由业务人员维护而不是建模师，让他们逐条在界面上点不现实。管理台顶栏右侧提供三个入口：

11.1 工作簿形态 #

一个文件八个页签，页签名固定（缺哪个就跳过哪个，不用删页签）：

表头是中文的（业务人员看得懂），也可以容忍手写近似列名。

11.2 三个对业务人员友好的细节 #

• 编码一律可留空：留空时按中文名自动生成英文编码，并在导入报告里标注「自动」。
• 枚举列有下拉：数据类型、关系类型、严重级别、状态等列在模板里带数据校验下拉，不用背英文。
• 引用可以写中文名：所属类 / 起点类 / 终点类既可以写编码也可以写类的中文名；可以引用同一份表里本次新建的类。

11.3 两段式导入 #

上传后不直接写库，先出校验报告：

1. 汇总表：每个页签的「读取行 / 新增 / 更新 / 错误」，以及最终是「全部导入」还是「忽略错误行后导入」；
2. 错误明细：定位到页签 + 行号 + 字段 + 原因（例如「对象属性 第 12 行 终点类 类「门店」不存在」）；
3. 变更清单：逐行列出将会新增还是更新，以及哪些编码是自动生成的。

确认后才落库。有错也能导 —— 错误行会被跳过，其余正常写入（会二次确认）。

11.4 幂等与项目边界 #

• 按编码覆盖：存在则更新、不存在则新增，同一份表反复导入不会长出重复数据。
• 只动自己项目的东西：导入范围严格限定为「当前项目」，不会因为同名就去改写公共区或其它项目的资产。导出同理，只出本项目的数据。
• 导入后状态：可选择直接标记为已发布，或按草稿录入走审批流。

十二、画布操作说明 #

建模画布采用三栏 + 顶栏布局：

• 左栏：本体对象树（类 / 属性 / 关系 / 术语 / 方法 五类切换），搜索；点术语会定位到它指向的概念。
• 中栏画布：显示类节点卡片（头部类名 + 状态徽标，体内列属性），连线显示关系动词和基数。
  • 拖拽节点 = 移动位置（不改变语义），滚轮直接缩放，空白处拖动平移；拖拽停下约 1 秒自动存布局；
  • 布局模式：
    • 力导向（默认）——自动排列，同域节点聚拢，交叉最少；
    • 分层树 ——按继承层级分层排列，适合看继承体系；
    • 网格 ——整齐的五列排列，适合通用浏览；
• 关系降噪（解决"节点一多就看不清"的问题）：
  • 焦点模式：双击节点进入，只看它附近的关系邻居，其余淡出；
  • 悬停高亮：鼠标掠过节点，只保留与它相关的连线；
  • 合并多重边：同一对节点间的多条关系合并显示，点击可轮换查看；
  • 关系类型过滤：勾选想要的关系类型，不关心的边直接不画；
  • 隐藏孤立节点：把还没连线的类临时移出画布；
  • 缩略图（右上角）：整图导航，点击可快速跳转；工具栏「定位类」回车可把指定的类居中显示。
• 右栏：选中节点 → 类表单；选中连线 → 关系表单；节点内属性行 → 属性表单；方法 → 方法面板。带副作用的方法面板顶部有红字提示「智能体调用需人工确认」。
• 顶栏：项目切换器、「项目」按钮（新建/编辑/删除项目）、业务域筛选、缩放/适应、自动布局、新增（类/关系/属性/方法）、「提交发布」、「导出技能」（可切换格式、复制、下载）。

说明：画布与管理台能力等价，区别只在交互形态 —— 批量录入用管理台/Excel，梳理关系用画布。

十三、常见问题 #

Q：为什么智能体查不到我刚建的概念？ 状态还是草稿或审批中。发布（审批通过或管理员直发）后才进入知识供给。

Q：术语保存报错「指向编码不存在」？ 术语的「指向编码」必须填写已存在的对象编码，确认目标对象已经保存。

Q：能不能删掉一个类？ 有子类、有属性、被关系引用、有方法或公理时不能直接删，需要先清除下游对象。平台不做静默级联删除。

Q：SQL 试跑被拒？ 试跑只允许查询类语句，写操作会被拦截。需要执行写操作请建 HTTP 类型方法并标记副作用，由人工确认后在业务系统里执行。

Q：本体和数据表要一一对应吗？ 不需要。本体只靠「落地提示」文本与物理表牵连；表结构变化不需要改本体结构（最多改提示文本）。

Q：两个项目里都要用同名的类，冲突吗？ 不冲突。编码的唯一性按项目判定，跨项目同名不冲突。只有都放在公共区时才需要避免重名。

Q：跨项目能建继承关系吗？ 不能。父类必须在同一个项目或属于公共区。方案间的复用请把共享概念提到公共区。

Q：把类迁到别的项目后，它的属性和方法还在吗？ 在。属性、方法跟随宿主类自动归属到新项目，不需要手工搬运。

Q：智能体怎么只看到自己项目的本体？ 调知识接口时带上项目编码参数即可限定范围。

Q：Excel 上传报错？ 只支持 .xlsx 或 .xlsm 格式，老版 .xls 请在 Excel/WPS 里另存为 xlsx 再传。

Q：导入后多出没录过的对象？ 模板每个页签第 2 行是示例行（淡黄底），忘记删就会被当成真实数据。删掉该行重新导入即可。

Q：同一份表导了两次，会重复吗？ 不会。按编码判定，已存在就更新，不会重复。

Q：导入报告里有错误行，还能导吗？ 能。错误行会被跳过，其余正常写入，但要二次确认。

十四、名词解释 #