/manage-kg-knowledge

name: manage-kg-knowledge
description: |
  知识图谱知识数据管理与查询。通过 CLI 原生命令完成：实体与关系的增删改查、批量写入、Cypher 图查询、邻居节点遍历。
  触发场景：知识图谱数据 / 创建实体 / 创建关系 / 批量导入 / Cypher 查询 / 邻居遍历 / 知识数据管理。

知识图谱知识数据管理（manage-kg-knowledge）

1. Scenario Description

数据工程师通过阿里云 CLI 管理知识图谱中的实体和关系数据，包括单条 CRUD、批量写入、Cypher 图查询和邻居节点遍历。

**业务流程：**

确认 Schema 就绪 → 创建实体 → 批量导入实体 → 创建关系 → 查询数据 → Cypher 图查询 → 邻居遍历

**资源拓扑：**

知识图谱空间（Workspace）
├── 实体（Entity）
│   ├── 所属实体类型（EntityType）
│   └── 属性键值对（PropertyList）
├── 关系（Relation）
│   ├── 所属关系类型（RelationType）
│   ├── 起始实体 → 目标实体
│   └── 关系属性键值对
└── 图查询引擎
    ├── Cypher 查询（只读，**仅 Neo4j 引擎**）
    └── 邻居节点遍历（引擎无关）

**前置条件：**

• 知识图谱空间已存在且 Schema 已发布到图引擎（`manage-kg-schema` Skill 产出）
• OpTenantId（租户 ID）和 WorkspaceId（空间 ID）已知
• 实体类型和关系类型已在 Schema 中定义
• 写入前已取得目标类型的**主键与必填属性清单**（`export-kg-schema` 中 `isPrimaryKey: true` / `isRequired: true` 的属性）

> **实体/关系 CRUD 引擎无关**：本 Skill 的 12 个知识数据接口在 Neo4j 与 Lindorm 图引擎上用法一致，不需按引擎分叉。**但两处依然受引擎影响**：① 步骤 5 的 Cypher 查询**仅 Neo4j 可用**（Lindorm 报 `DPN.Commons.InternalError`，详见 [图引擎能力矩阵](../graph-engine-capabilities.md) 与 `query-kg` Skill）；② 属性值的可用类型由 Schema 建模时的引擎约束决定（如 Lindorm 无 `DATE`，时间值已存为 ISO 字串）。

> **Schema 面与数据面状态隔离（实测）**：空间 Schema 面处于异常态（如 `RollbackFailed` 发布失败且回滚失败、导入/发布报 `DPN.Planning.KgWorkspaceStatusNotEditable`）**不影响数据面读写**——`create-kg-entity` / `create-kg-relation` / `exec-kg-cypher` / `get-kg-neighbor` / `delete-*` 等基于**已发布版本**的类型定义全部正常。看到 Schema 面报「空间不可编辑」时，不要误判整个空间不可用而放弃数据操作；数据操作仅依赖已发布版本的类型定义。

> **CLI 原生支持**：KG OpenAPI 已正式发布（CLI `--help` 实测显示 Online version: **v6.1.1**，以实际输出为准），并注册到 `aliyun-cli-dataphin-public` 插件（**>= 0.7.1**）。本 Skill 全部使用 CLI 原生命令（kebab-case，如 `create-kg-entity`）。独立部署低于该版本的旧环境未发布 KG OpenAPI，可退回 Python Tea SDK 泛化调用（见 [Python SDK 模板](./references/python-sdk-template.md)）。

2. Installation

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

# 安装 dataphin-public 插件（KG 命令要求插件 >= 0.7.1）
aliyun plugin install --names aliyun-cli-dataphin-public

# 已安装旧版本时升级
aliyun plugin update

# 验证 KG 命令已注册
aliyun dataphin-public --help | grep -i kg-entity

详见 [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 plugin list | grep dataphin-public

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

5. RAM Policy

本 Skill 涉及的最小 RAM 权限：

{
  "Effect": "Allow",
  "Action": [
    "dataphin:CreateKgEntity",
    "dataphin:UpdateKgEntity",
    "dataphin:DeleteKgEntity",
    "dataphin:GetKgEntity",
    "dataphin:ListKgEntity",
    "dataphin:BatchCreateKgEntity",
    "dataphin:CreateKgRelation",
    "dataphin:UpdateKgRelation",
    "dataphin:DeleteKgRelation",
    "dataphin:GetKgRelation",
    "dataphin:ListKgRelation",
    "dataphin:BatchCreateKgRelation",
    "dataphin:ExecKgCypher",
    "dataphin:GetKgNeighbor"
  ],
  "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** > 执行前必须确认以下业务参数：

| 参数 | 含义 | 获取方式 | 必填 | |------|------|---------|------| | OpTenantId | 租户 ID | profile 或询问用户 | 是 | | WorkspaceId | 知识图谱空间 ID | **必须向用户索取**（见下方说明） | 是 | | EntityType | 实体类型编码 | `export-kg-schema`（manage-kg-schema）| 实体操作 | | RelationType | 关系类型编码 | `export-kg-schema`（manage-kg-schema）| 关系操作 | | PropertyList | 属性键值对列表 | 用户指定，Code 必须匹配 Schema 定义 | 写操作 |

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

> Endpoint 传值**不带 `https://` 前缀**（如 `dataphin-openapi.<env>.aliyun.com`），带前缀会报 DNS 解析错误。

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

7. Observability

版本 `{version}`（Shell 变量 `SKILL_VERSION`）来自套件 `references/manifest.json` 的 `version` 字段，与 session-id 一同继承[父技能 §7](../../../SKILL.md#7-observability)。直接加载本子技能时先完成父层初始化；所有 CLI / SDK 调用使用父技能名称与同一版本，跨 Shell 调用须重新注入这些值。

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

所有 CLI 命令携带：

--user-agent "AlibabaCloud-Agent-Skills/alibabacloud-dataphin-skills/{SESSION_ID} skill-version/{version}"

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

8. Core Workflow

步骤 1：创建实体

HITL 确认（写操作）

执行前确认：

• 实体类型编码（必须在 Schema 中已定义）
• 属性键值对（Code 必须匹配 Schema 属性定义）
• 影响范围：在图引擎中新增一条实体记录

> **🚨 先取必填属性清单，再拼 PropertyList（实测高频报错）**：缺一个必填属性就报 400 `DPN.Planning.KgEntityParamInvalid: Knowledge graph entity parameter is invalid: 必填属性 [xxx] 不能为空`（trace f3781307 连碰 5 次，每次差一个字段）。正确做法：**写入前先 `export-kg-schema` 拿该实体类型的属性清单**，按 `isPrimaryKey: true` 与 `isRequired: true` 逐项补齐后一次提交，不要“报错一个补一个”地试。`useSysPk: true` 的类型不需传主键（系统生成 `_sys_id`），但其他必填属性仍要传全。

**确认后执行：**

aliyun dataphin-public create-kg-entity \
  --op-tenant-id {OpTenantId} \
  --workspace-id "{WorkspaceId}" \
  --create-command '{
    "EntityType": "COMPANY",
    "PropertyList": [
      {"Code": "name", "Value": "阿里巴巴集团"},
      {"Code": "industry", "Value": "互联网"},
      {"Code": "founded_year", "Value": "1999"}
    ]
  }' \
  --profile {profile} --endpoint {endpoint} \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-dataphin-skills/{SESSION_ID} skill-version/{version}"

> **注意**：KG 写操作的请求体标志不是通用的 `--body`，而是对应的命令对象标志（`--create-command` / `--update-command` / `--exec-command`），否则报缺参错误。

**响应处理：**

• 提取 `CreateResult.EntityId`（实测为 UUID 字符串），后续创建关系时引用

步骤 2：批量创建实体

aliyun dataphin-public batch-create-kg-entity \
  --op-tenant-id {OpTenantId} \
  --workspace-id