/manage-kg-schema

name: manage-kg-schema
description: |
  知识图谱本体模型（Schema）管理。通过 CLI 原生命令完成：整体 Schema 的导出（YAML）、导入（YAML）、发布到图引擎并查询发布结果。实体类型/关系类型/属性的增删改通过编辑 Schema YAML 后整体导入实现，不提供细粒度的单类型 CRUD 接口。
  触发场景：知识图谱 Schema / 本体模型 / 实体类型 / 关系类型 / Schema 导入导出 / Schema 发布。

知识图谱本体模型管理（manage-kg-schema）

1. Scenario Description

数据架构师通过阿里云 CLI 管理知识图谱的本体模型（Schema）。当前 KG Schema OpenAPI **仅提供整体 Schema 级别的操作**（导出 / 导入 / 发布），**不提供**实体类型、关系类型的细粒度单独 CRUD 接口。因此新增 / 修改 / 删除实体类型、关系类型、属性，均通过「导出 YAML → 本地编辑 → 整体导入 → 发布」的流程完成。

**业务流程：**

导出当前 Schema（基线）→ 本地编辑 YAML（增删改类型/属性）→ 整体导入 Schema → 发布 Schema → 查询发布结果

**资源拓扑：**

知识图谱空间（Workspace）
├── 实体类型（EntityType）
│   ├── 属性定义（Properties）
│   └── 继承关系（ParentTypeId）
├── 关系类型（RelationType）
│   ├── 起始/目标实体类型
│   ├── 基数（Cardinality）
│   └── 关系属性
├── Schema 版本
│   ├── 草稿态（Draft）
│   └── 已发布版本（Published）
└── 发布任务（PublishTask）
    ├── 四项校验（连接/完整性/兼容性/偏离）
    └── 数据调整策略（BackfillDefault）

**前置条件：**

• 知识图谱空间（Workspace）已存在，当前用户有空间管理权限
• OpTenantId（租户 ID）已知

> **CLI 原生支持**：KG OpenAPI 已正式发布（CLI `--help` 实测显示 Online version: **v6.1.1**，以 `aliyun dataphin-public export-kg-schema --help` 实际输出为准），并注册到 `aliyun-cli-dataphin-public` 插件（**>= 0.7.1**）。本 Skill 全部使用 CLI 原生命令 `export-kg-schema` / `import-kg-schema` / `publish-kg-schema` / `get-kg-schema-publish-result`。独立部署低于该版本（< v6.1.1）的旧环境未发布 KG OpenAPI，可退回 Python Tea SDK 泛化调用（辅助脚本 `scripts/export-schema.py` / `scripts/import-schema.py`）。 > > **重要（能力边界）**：当前 KG Schema OpenAPI **仅支持整体 Schema 操作**——导出、导入、发布及查询发布结果。**不存在** `CreateKgEntityType` / `UpdateKgEntityType` / `DeleteKgEntityType` / `CreateKgRelationType` 等细粒度单类型 CRUD 接口。所有类型/属性的增删改，请编辑导出的 YAML 后整体重新导入。

> **🚨 建模前先确认图引擎**：导出/导入/发布这 4 个接口本身引擎无关，**但 YAML 里的 `dataType` 与业务识别规则随引擎变化**（Lindorm 图引擎自 V6.2.3 支持）： > > | 建模项 | Neo4j | Lindorm 图引擎 | > |---|---|---| > | 日期/时间 `DATE` `TIMESTAMP` `DURATION` | ✅ | ❌ 不支持 → 用 `STRING` 存 ISO 8601 字串 | > | 多值 | `LIST` ✅ / `SET` ❌ | `LIST` ❌ / **`SET` ✅**（V6.2.3 新增） | > | 嵌套 `EMBEDDED` / `MAP<K,V>` | ✅ | ❌ 不支持 → 用 `STRING` 存 JSON 文本 | > | `UNKNOWN`（AI 抽取待确认） | ✅ | ❌ 不支持 | > | `GEOPOINT` | ✅ Point | ✅（底层落 String） | > | 业务识别规则 | 含编辑距离、时间类规则 | ❌ 无编辑距离、无时间类规则（其余精确/忽略大小写/包含/等于/数值/语义相似度均支持） | > > 完整类型映射表与替代写法见 [图引擎能力矩阵](../graph-engine-capabilities.md)。**向 Lindorm 空间导入含不支持类型的 YAML 会在导入/发布阶段失败或被静默降级，请在编辑阶段就按引擎裁剪。**

2. Installation

**Pre-check: Aliyun CLI >= 3.4.8 required** > 运行 `aliyun version` 确认版本 >= 3.4.8。未安装或版本过低，请从 https://aliyuncli.alicdn.com 安装/升级（各操作系统一键脚本见 ./references/cli-installation-guide.md）。

**Pre-check: Aliyun CLI plugin update required** > [MUST] 运行 `aliyun configure set --auto-plugin-install true` 开启插件自动安装。 > [MUST] 运行 `aliyun plugin update` 确保已装插件保持最新（KG 命令要求插件 **>= 0.7.1**）。

# 安装 aliyun CLI（>= 3.4.8）：https://github.com/aliyun/aliyun-cli
# 各操作系统一键安装脚本见 ./references/cli-installation-guide.md

# 开启插件自动安装并更新已装插件
aliyun configure set --auto-plugin-install true
aliyun plugin update

# 安装 dataphin-public 插件（>= 0.7.1，KG 命令自 0.7.x 起注册）
aliyun plugin install --names aliyun-cli-dataphin-public

# 安装 Python 依赖（YAML 预校验脚本需要 pyyaml；SDK 兜底脚本另需 tea-openapi）
pip3 install pyyaml

# 验证：KG Schema 命令已注册
aliyun dataphin-public export-kg-schema --help

详见 [CLI 安装指南](./references/cli-installation-guide.md)。

3. Environment Variables

> 凭证与环境变量由父 skill `alibabacloud-dataphin-skills` 统一声明并预检（父 §3 + §4 Authentication + §8 Step 0，先于路由到本 skill 执行）；本 skill 不重复声明。

4. Authentication

Pre-check: Credentials Required

# 检查凭证配置
aliyun configure list

# 检查 CLI 版本
aliyun version
# 要求 >= 3.4.8

# 检查 KG 命令已注册（插件 >= 0.7.1）
aliyun dataphin-public export-kg-schema --help

**凭证不可打印**：任何时候不得将 AccessKey ID/Secret 输出到终端或日志。

5. RAM Policy

本 Skill 涉及的最小 RAM 权限：

{
  "Effect": "Allow",
  "Action": [
    "dataphin:ExportKgSchema",
    "dataphin:ImportKgSchema",
    "dataphin:PublishKgSchema",
    "dataphin:GetKgSchemaPublishResult"
  ],
  "Resource": "*"
}

Permission Failure Handling

若遇到权限错误（HTTP 403 或 ErrorCode 含 `Forbidden`/`NoPermission`/`Dataphin.KG.NoPermission`），请： 1. 确认 RAM 用户已附加上述策略 2. 确认策略中 Resource 范围覆盖目标租户 3. 确认当前用户具有知识图谱空间的管理权限 4. 联系租户管理员授权

详见 [RAM 策略参考](../../ram-policies.md)。

6. Parameter Confirmation

> **IMPORTANT: Parameter Confirmation** > 执行前必须确认以下业务参数：

| 参数 | CLI 标志 | 含义 | 获取方式 | 必填 | |------|---------|------|---------|------| | **图引擎** | （不是 CLI 参数） | 空间绑定的引擎：`Neo4j` / `Lindorm` | **向用户确认**（决定 YAML 里可用的 `dataType`） | **是（编辑 YAML 前置）** | | OpTenantId | `--op-tenant-id` | 租户 ID | profile 或询问用户 | 是 | | WorkspaceId | `--workspace-id` | 知识图谱空间 ID | **必须向用户索取**（见下方说明） | 是 | | Schema YAML 内容 | `--import-command` 的 `Content` | 编辑后的完整本体模型 | 导出基线后本地编辑 | 导入操作 | | MergeStrategy | `--import-command` 的 `MergeStrategy` | 导入合并策略 `Replace`/`Merge` | 用户指定 | 导入操作 | | Description | `--publish-command` 的 `Description` | 发布备注 | 用户指定 | 发布操作 |

> **WorkspaceId 无自助发现途径**：KG OpenAPI **不提供列出 KG 空间的接口**（全部 18 个 KG 命令中无任何 list-workspace 类命令），WorkspaceId 必须向用户索取（32 位小写 hex 字符串，可在控制台知识图谱空间列表页查到）。不要尝试猜命令或翻 help 探索。

详细 API 入参/出参见 [KG Schema API 参数参考](./references/kg-schema-api-params.md)。

7. Observability

本子 Skill 的 session-id **继承自父 Skill `alibabacloud-dataphin-skills`**，不重新生成。

所有 CLI 命令携带：

--user-agent AlibabaCloud-Agent-Skills/manage-kg-schema/{SESSION_ID}

其中 `{SESSION_ID}` 为父 Skill 生成的 32 字符小写十六进制字符串。

8. Core Workflow

> **能力边界（务必先读）**：KG Schema OpenAPI **仅支持整体 Schema 操作**——`export-kg-schema`（导出）、`import-kg-schema`（导入）、`publish-kg-schema`（发布）、`get-kg-schema-publish-result`（查询发布结果）。**不存在** `CreateKgEntityType` / `UpdateKgEntityType` / `DeleteKgEntityType` / `CreateKgRelationType` 等细粒度单类型 CRUD 接口。新增 / 修改 / 删除实体类型、关系类型、属性，统一通过「**导出 YAML → 本地编辑 → 整体导入 → 发布**」完成。

步骤 1：导出当前 Schema（基线）

# 导出 YAML 并直接提取 Schema 内容存为基线文件
aliyun dataphin-public export-kg-schema \
  --op-tenant-id "{OpTenantId}" \
  --workspace-id "{WorkspaceId}" \
  --output-format yaml \
  --profile {profile} --endpoint {endpoint} \
  --user-agent "AlibabaCloud-Agent-Skills/manage-kg-schema/{SESSION_ID}" \
  --cli-query 'SchemaInf