> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpertai.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 本体工作室

> 在可视化工作区中设计、连接、校验、版本化并发布业务本体。

本体工作室是业务本体定义的编写界面。你可以在这里建模业务领域、把模型连接到现有资源、添加本体自有数据、检查语义路径，并将不可变版本发布到 UOSE 本体运行时。

工作室会把可编辑草稿与已发布运行时状态分开。修改先保存为带修订号的草稿；在新版本完成校验和发布前，本体空间和下游插件会继续读取上一个已发布快照。

## 创建本体

进入 **数据与本体 → 本体工作室**，选择 **创建本体**。

| 字段    | 含义                                   |
| ----- | ------------------------------------ |
| 名称    | 面向用户展示的本体名称                          |
| 资源 ID | 快照和集成使用的稳定运行时标识；可使用字母、数字、`.`、`_`、`-` |
| 描述    | 说明领域用途和所有权                           |
| 起始模板  | `空白本体` 或可继续编辑的 `供应链` 示例              |

工作室列表会展示资源 ID、当前已发布版本、草稿状态、实体数、关系数、实例数和最后更新时间，并支持按标识文本搜索定义。

<Warning>
  资源 ID 和已发布语义版本都是集成契约。插件或外部自动化开始按 ID 与版本解析本体后，不要随意重命名或复用。
</Warning>

## 设计工作区

**设计**工作区用于编写 Schema 和 Action。

### 实体类型与属性

实体类型包含稳定 `code`、可读名称、描述、可选图标与颜色、可选默认状态，以及一组类型化属性。支持以下属性值类型：

* `string`
* `number`
* `integer`
* `boolean`
* `datetime`
* `json`

每个属性可以设为必填或可重复。绑定、关系、Action、Agent 工具和插件都使用稳定编码；可读名称可以本地化或优化，而不改变这些契约。

### 关系类型

关系类型连接源实体类型和目标实体类型，可以选择四种基数：

* 一对一；
* 一对多；
* 多对一；
* 多对多。

关系也可以拥有自己的类型化属性。你可以从资源树创建关系，也可以在图画布中从一个实体连接点拖向另一个实体。发布前会校验关系端点约束。

### Action 定义

Action 定义描述语义操作，但不在本体中嵌入执行实现。它可以定义：

* 一个或多个目标实体类型编码；
* 风险等级：`LOW`、`MEDIUM`、`HIGH`、`CRITICAL`；
* 是否需要审批；
* 发现模式：仅人工触发、可建议、可自动规划、可自动执行；
* 意图标签和前置条件；
* 输入与输出 Schema；
* 读取、分析、状态变更或外部调用等预期影响；
* 幂等和预期影响要求。

<Info>
  本体中的 Action 是语义与治理契约。执行仍需要 Tool Contract 或插件适配器。定义 Action 不会授予助手审批或执行权限。
</Info>

### 画布工具

画布支持选择、拖动定位、缩放、适应视图、自动布局、创建关系和导出 PNG。切换到 RDF 视图，可以查看根据当前草稿生成的 Turtle 预览。

工作室会维护本地撤销/重做历史并自动保存草稿。保存请求携带预期草稿修订号，因此并发修改会产生冲突，而不会静默覆盖服务器上的新版本。发生冲突时，应重新加载服务器草稿，或先下载本地草稿再处理。

## 导入 RDF / OWL

使用 **导入 RDF** 可以把 RDF/XML 本体载入当前草稿。导入流程会：

1. 解析不超过 5 MB 的文件；
2. 预览新增、更新和移除的实体类型与关系类型；
3. 报告不支持或采用默认映射的语义；
4. 说明哪些 Action、绑定、实例和实例关系会被清空；
5. 仅在明确确认后替换当前草稿。

当工作室契约可以表达时，导入器会映射 OWL class、datatype property、object property、标识符和基数。对于无法安全表示的绑定、属性元数据、未解析端点和值类型转换，系统会给出说明，而不是猜测。

## 数据与绑定工作区

**数据与绑定**工作区把 Schema 连接到数据。以下三类内容与 Schema 共用同一个修订、校验和发布生命周期。

### 数据源绑定

数据源绑定把一个实体类型映射到已有 UOSE 资源，需要配置：

* 源资源 ID 和资源类型；
* 可选的源表或对象；
* 主键字段和可选显示字段；
* 本体属性到源字段的映射。

绑定状态可以是 `draft`、`valid` 或 `invalid`。发布前应执行绑定校验，处理缺失主键、源字段或不兼容映射。

### 手工实例

手工实例是由本体定义拥有的记录。选择实体类型后，提供稳定外部键、可选显示名称、生命周期状态，以及已知属性的值。系统会根据 Schema 校验属性名和必填值。

### 实例关系

实例关系连接具体的源实例与目标实例。所选关系类型会约束两端的实体类型，避免草稿连接不符合 Schema 的对象。

## 探索工作区

**探索**工作区用于在发布前后检查语义结构：

* 搜索实体类型和关系类型；
* 筛选图层和标签；
* 查看入向与出向关系；
* 查找两个类型之间的语义路径；
* 对比草稿 Schema 图与已发布 Schema 图；
* 在已有版本时检查已发布详情；
* 把当前定义、草稿修订、工作区和所选 Schema 元素交给本体助手。

本体助手可以提供上下文相关的设计建议；当已配置模板包含本体编写工具时，也可以执行有边界的草稿修改。工作室会刷新已成功写入的远端变更，但不会覆盖本地未保存修改。

## 校验、预览与发布

使用**版本**工作区管理发布。

### 校验

校验结果会给出错误或警告，并标记所属对象类型和路径。检查内容包括：

* 重复或非法稳定编码；
* 属性定义和实例必填属性；
* 关系源端点与目标端点完整性；
* Action 目标、契约和引用类型；
* 数据绑定和实例关系；
* 可发布的 Schema 与数据数量。

发布前必须处理错误，同时应把警告作为发布就绪度信号，例如仍未映射的可选字段。

### 预览 Manifest

**预览 Manifest** 会把草稿编译为完整 `MetaManifest` 和业务本体发布请求。发布前可以据此检查 Action 契约、生成 Schema 与集成输出。

### 发布

填写语义版本和可选发布说明。系统会再次校验，然后创建：

* 不可变的本体定义版本；
* 编译后的 Manifest 和发布请求；
* 业务本体快照；
* graph version 和 ontology ID；
* 配置启用时的 RDF 物化和运行时实例投影。

发布成功后，选择 **在本体空间中打开** 检查生成的资源。

## 版本与生命周期管理

已发布版本不可变。在版本历史中可以：

* 检查版本元数据、snapshot ID 与 graph version；
* 对比已发布版本与当前草稿；
* 下载编译后的 Manifest 和 RDF 产物；
* 把历史版本恢复为新的可编辑草稿。

从未发布的本体可以删除。已发布本体只能归档：它会从工作室活动列表移除，但不可变版本与已发布运行时快照仍会保留。

## 推荐编写顺序

<Steps>
  <Step title="定义稳定领域类型">
    先创建实体类型与属性。稳定编码应能够贯穿插件、绑定和 API 的整个领域契约生命周期。
  </Step>

  <Step title="用明确关系连接类型">
    定义端点和基数，再使用图谱与路径查找检查缺失或含糊语义。
  </Step>

  <Step title="添加受治理 Action">
    定义目标、风险、审批要求、发现模式、输入、前置条件和预期影响。适配器凭据与执行逻辑应留在本体之外。
  </Step>

  <Step title="绑定或添加代表性数据">
    映射外部资源，在适合时添加本体自有实例，并使用受 Schema 约束的关系连接具体实例。
  </Step>

  <Step title="校验并预览">
    处理错误、检查警告，并在分配语义版本前核对编译后的 Manifest。
  </Step>

  <Step title="发布并验收">
    发布版本，然后进入[本体空间](./ontology-workspace)检查快照健康、图谱内容、搜索和历史。
  </Step>
</Steps>