Skip to main content
阀门业务工作台是 Xpert 插件使用本体的参考模式。插件不会只把本体当作一段附加到提示词的文本，而是携带版本化领域模型，通过 data-xpert 生命周期发布，从 ready 快照读取准确对象，再把本体 Action 定义映射到插件自有、受治理的执行适配器。 最终形成一个包含 Object 360、语义证据、Action 发现、预检、人工审批、Demo 执行和审计的工程业务界面。

​
责任划分

日常 Workbench 和 Assistant 操作对本体数据只读。唯一的本体写入路径是显式初始化或版本升级。草案和执行审计记录保存在插件命名空间，不会反写为本体事实。

​
携带版本化本体包

插件在代码中携带稳定资源 ID 为 valve-engineering-ontology 的本体包。1.0.0 版本包含中性的产品演示内容： 本体包不包含客户生产记录或外部数据绑定，因此初始化具有确定性，适合安全演示，同时继续使用生产集成会使用的同一套已发布本体契约。

​
为什么本体包只保存在服务端

iframe 不会提交资源 ID、语义版本、定义内容、tenant、organization 或 data-xpert 地址。这些值来自插件代码、配置和宿主运行时，避免浏览器调用方改变本体范围，或通过 Workbench bridge 导入任意定义。

​
通过定义生命周期初始化

连接 data-xpert 本身不会写入本体。Workbench 用户必须点击初始化本体并确认。
1

检查固定资源和版本

插件检查 valve-engineering-ontology 是否存在，以及代码自有语义版本是否已经发布。
2

创建或替换草稿

定义不存在时创建定义；如果存在未发布草稿，必须由用户再次明确确认代码自有本体包将覆盖该草稿。
3

在 data-xpert 中校验

完整草稿通过本体定义 API 提交，并使用与本体工作室相同的实体、关系、Action、实例和实例关系规则校验。
4

发布语义版本

data-xpert 创建不可变版本和已发布快照，并更新运行时投影。
5

刷新 ready 资源

插件重新加载资源，只展示处于活动、ready 状态并包含精确根实体类型编码 valve 的对象。
初始化具有幂等性：准确语义版本已经发布时返回 already_current，不会创建重复版本。升级时应修改代码自有模型、递增语义版本、重新部署，再由 Workbench 提示更新本体。不要改写已发布语义版本。

​
从已发布邻域构建 Object 360

初始化后，Workbench 服务端使用当前用户的短期 Actor Token 调用 data-xpert Agent Tools，并重新校验组织、活动资源、ready 状态、可选资源白名单、可选定义筛选和精确 valve 根类型。 对选中的阀门，插件会组合当前实体及其一跳邻域，展示：
  • 稳定身份和类型化属性；
  • 部件、材料、执行机构与适用标准；
  • 关系方向和关联对象详情；
  • 证据与来源摘要；
  • 结构化约束和告警；
  • 当前类型可用的 Action 定义；
  • 页面使用的 snapshot ID 和 graph version。
Assistant 获得同一个有界 Workbench 上下文。它的 Skill 要求区分本体事实、证据缺口和 Agent 判断，避免把建议描述成源系统事实。

​
把本体 Action 变成受治理操作

本体定义 Action 的业务含义：稳定编码、目标类型、风险、审批要求、输入契约、前置条件、发现模式和预期影响。插件再把稳定 actionTypeCode 映射到执行适配器。 阀门示例包含： 在客户 Demo 配置下，插件可以展示当前本体尚未包含的 Action，但必须清晰标记为 Demo 补充。如果要求所有可见 Action 都来自 data-xpert，应关闭 fallback。

​
创建草案前先预检

Assistant 或 Workbench 创建 ontology_action 草案前，会先运行只读的 valve_preflight_action，检查：
  • Action 是否适用于当前实体类型；
  • Demo 适配器是否启用；
  • 必填输入和数值范围；
  • 草案使用的 graph version 是否过期；
  • 是否存在同类待审核或已批准任务；
  • 本体约束和 simulation_only 告警。
规范化输入与预检摘要会随草案保存，使审批人能够检查实际通过校验的准确契约。

​
让审批与执行保持人工控制

Assistant 中间件提供严格工具，用于发现 ready 资源、检查 Schema、搜索对象、读取 Object 360、发现 Action、执行预检、列出草案、创建草案和读取审计。唯一写操作是幂等创建 pending_review 草案。 它故意不提供 approve、reject 或 execute 工具。
只有已批准草案可以执行。成功路径记录：
失败时记录 execution_failed，不会伪造成功回执。CRITICAL 阀门隔离路径明确标记为 simulation_only，不会声称向 DCS 或 SIS 发送了控制命令。

​
安全与范围模式

阀门插件展示了以下可复用规则：
  • Actor Token 和 tenant 身份只保留在 view bridge 的服务端；
  • 从当前宿主请求获得身份，而不是接受浏览器配置；
  • 每次 data-xpert 调用都要求活动 organization 范围；
  • 插件自有本体完成初始化后再配置资源白名单；
  • 校验稳定实体类型编码，不根据显示名称或属性组合猜测类型；
  • 预检时固定 snapshot 与 graph version；
  • 把语义 Action 定义与执行凭据、适配器代码分开；
  • 把本体初始化、托管 Assistant 准备和日常 Workbench 操作分成独立生命周期；
  • 让有后果的状态变更保持可见、可认证、幂等和可审计。

​
可复用插件蓝图

把这种模式用于其他领域时：
  1. 定义稳定的实体、关系、属性和 Action 编码；
  2. 决定插件携带中性本体包、绑定客户资源，或同时使用两者；
  3. 通过 data-xpert 发布，而不是维护私有图格式；
  4. 初始化和语义版本升级都要求显式确认；
  5. 从 ready 快照发现对象，并校验准确根实体类型；
  6. 根据实体邻域、证据、约束和 Action 构建紧凑领域 DTO；
  7. 把 Action 编码映射到插件自有适配器，不把凭据放进本体；
  8. 创建草案前执行预检与 graph version 校验；
  9. 风险要求时，把审批和执行保留在已认证用户界面；
  10. 将草案、执行回执和追加式审计与本体事实分开持久化。
这样既能让本体保持为可复用语义契约，又能由每个插件提供适合自身领域的界面、集成适配器和治理流程。