知识本体

面向AI Agent的类型化知识图谱系统，提供实体关系建模、约束校验引擎、模式演进管理、图遍历规划四大核心能力. 内置15+实体类型与7类约束规则，支持append-only历史保留与三步迁移法，确保模式变更不破坏旧数据. 将多步计划建模为图操作序列，每步执行前自动校验约束，违反约束自动回滚. 适用于需要结构化查...

功能说明: 本技能涵盖 化工作流场景 等核心能力。

知识本体（Knowledge Ontology）

一切皆实体，一切变更皆受约束。 将 Agent 记忆从扁平文件升级为类型化可验证的知识图谱，支持图遍历查询、模式演进、多步规划建模，让知识结构化、可查询、可信任.

主要能力

类型化实体与关系系统

内置 Person/Organization/Project/Task/Goal/Event/Location/Document/Message/Thread/Note/Account/Device/Credential/Action/Policy 15+ 类型，实体含 id/type/properties/relations/created/updated 标准结构.

处理: 解析类型化实体与关系系统的输入参数,完成核心逻辑,输出结构化数据. 输出: 返回类型化实体与关系系统的响应数据,包含返回码、数据和处理记录.

• 调用时传入input_params参数,支持创建/查询/导出操作

约束校验引擎

支持 required（必填）、enum（枚举）、forbidden_properties（禁止属性，如 Credential 禁止 password）、cardinality（关系基数）、acyclic（无环校验，如 blocks 关系）、validate（自定义表达式）、defaults（默认值）7 类约束规则.

处理: 解析约束校验引擎的输入参数,完成核心逻辑,输出结构化数据. 输出: 返回约束校验引擎的响应数据,包含返回码、数据和处理记录.

• 调用时传入input_params参数,支持创建/查询/导出操作

模式演进管理

append-only 历史保留 + 迁移脚本三步法（追加新 schema → 编写迁移 → 执行+校验），确保模式变更不破坏旧数据.

处理: 解析模式演进管理的输入参数,完成核心逻辑,输出结构化数据. 输出: 返回模式演进管理的响应数据,包含返回码、数据和处理记录.

• 调用时传入input_params参数,支持创建/查询/导出操作

图遍历规划

将多步计划建模为图操作序列（CREATE/RELATE），每步执行前校验约束，违反约束自动回滚；支持依赖分析、影响分析、循环依赖检测.

处理: 解析图遍历规划的输入参数,完成核心逻辑,输出结构化数据. 输出: 返回图遍历规划的响应数据,包含返回码、数据和处理记录.

• 调用时传入input_params参数,支持创建/查询/导出操作

Skill 契约声明

使用本体的 Skill 声明 reads/writes 边界与前后置条件，任一失败自动回滚，明确跨 Skill 通信边界.

处理: 解析Skill 契约声明的输入参数,完成核心逻辑,输出结构化数据. 输出: 返回Skill 契约声明的响应数据,包含返回码、数据和处理记录. 技术参数：使用input_params和output_format参数控制执行行为,支持json/text/csv输出格式. 能力覆盖范围：本技能覆盖以下场景：类型化知识图谱、Agent、记忆结构化可验证、的类型化知识图谱、提供实体关系建模、图遍历规划能力、适用于需要结构化、查询的、多实体关系管理、依赖追踪与影响分、多步计划建模场景、避免扁平文件记忆、难查询、约束缺失数据脏、模式演进破坏旧数、据等问题、适用关键词、知识图谱、实体关系、ontology、graph等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持.

参数说明

参数名	类型	必填	说明
input	string	是	知识本体处理的输入数据或指令
options	object	否	附加配置选项,如模式选择、格式偏好等
callback_url	string	否	异步处理完成后的回调通知URL

bash

mkdir -p memory/ontology
touch memory/ontology/graph.jsonl
python3 （请参考skill目录中的脚本文件） schema-append --data '{
  "types": {
    "Task": { "required": ["title", "status"] },
    "Project": { "required": ["name"] },
    "Person": { "required": ["name"] }
  }
}'

Step 2：创建实体（append-only）

bash

python3 （请参考skill目录中的脚本文件） create --type Person --props '{"name":"Alice"}'
python3 （请参考skill目录中的脚本文件） create --type Project --props '{"name":"网站重构","status":"active"}'

关键原则： 处理已有数据时追加新 op 到文件末尾，绝不覆盖文件.

Step 3：建立关系

bash

python3 （请参考skill目录中的脚本文件） relate --from proj_001 --rel has_owner --to p_001

关系建立前自动校验 from_types/to_types/cardinality 约束.

Step 4：查询与遍历

bash

# 按类型+条件查询
python3 （请参考skill目录中的脚本文件） query --type Task --where '{"status":"open"}'
# ...
# 关联查询
python3 （请参考skill目录中的脚本文件） related --id proj_001 --rel has_task
# ...
# 依赖说明
python3 （请参考skill目录中的脚本文件） traverse --id task_001 --rel depends_on --direction outgoing
# ...
# 影响分析（反向遍历）
python3 （请参考skill目录中的脚本文件） traverse --id task_001 --rel depends_on --direction incoming
# ...
# 循环依赖检测
python3 （请参考skill目录中的脚本文件） cycle-check --rel blocks

已知限制

bash

python3 （请参考skill目录中的脚本文件） validate
# 示例
# ✓ 142 个实体校验通过
# ✗ 3 个实体校验失败：
#   - task_042: 缺少必填属性 'status'
#   - cred_001: 包含禁止属性 'password'

Step 6：模式演进（不破坏旧数据）

bash

# 1. 追加新 schema（不删旧）
python3 （请参考skill目录中的脚本文件） schema-append --data '{"types":{"Task":{"required":["title","status","priority"]}}}'
# ...
# 2. 编写迁移脚本
# migrations/001_add_priority_to_tasks.py
def migrate(graph):
    for entity in graph.query(type="Task"):
        if "priority" not in entity.properties:
            entity.properties["priority"] = 3
    return graph
# ...
# 3. 执行迁移 + 校验
python3 （请参考skill目录中的脚本文件） migrate --script 001_add_priority_to_tasks.py
python3 （请参考skill目录中的脚本文件） validate

Step 7：多步规划建模（图变换序列）

bash

python3 （请参考skill目录中的脚本文件） plan --file plan.yaml --validate-each --rollback-on-fail

每步执行前校验约束，失败自动回滚到上一步.

Step 8：规模扩展（JSONL → SQLite）

bash

# >10000 实体时迁移
python3 （请参考skill目录中的脚本文件） migrate --from jsonl --to sqlite

用法示例

示例 1：项目依赖管理

输入：

text

用户："重构支付模块需要先完成哪些任务？"

执行：

1. 查找支付模块相关 Project
2. 遍历 has_task 关系找到所有 Task
3. 遍历 blocks 关系找到阻塞链
4. 拓扑排序输出执行顺序

输出：

text

执行顺序：
1. 设计支付接口（task_001）— 无阻塞
2. 实现支付网关（task_002）— blocked by task_001
3. 集成测试（task_003）— blocked by task_002
4. 上线部署（task_004）— blocked by task_003

示例 2：影响分析

输入：

text

用户："如果推迟数据库迁移，影响哪些任务？"

执行：

1. 找到数据库迁移 Task
2. 反向遍历 depends_on 关系
3. 找出所有依赖该任务的 Task

输出：

text

影响范围（3 个任务）：
- task_015: API 部署（depends on 迁移）
- task_022: 性能测试（depends on task_015）
- task_031: 上线（depends on task_022）
# ...
建议级联调整截止日期.

示例 3：凭证安全存储

输入：

text

用户："记住我的 Stripe API Key"

执行：

1. 检查 Credential 类型约束 → forbidden_properties: [api_key, secret]
2. 拒绝直接存储
3. 创建间接引用

输出：

python

ontology.create("Credential", {
  "service": "stripe",
  "secret_ref": "vault://secrets/stripe_key"  # 指向外部密钥库
})
# 输出："已记录 Stripe 凭证引用（密钥本身存储在密钥库，未写入图谱）"

环境要求

依赖项	类型	是否必需	获取方式
LLM API	API	必需	由 Agent 内置 LLM 提供
Python 3.8+	运行时	必需	系统安装
PyYAML	Python 包	必需	pip install pyyaml（解析 schema.yaml）
SQLite	数据库	可选	Python 内置（>10000 实体时使用）
Agent 平台	运行环境	必需	支持 SKILL.md 的任意 AI Agent
操作系统	运行环境	必需	Windows / macOS / Linux

API Key 配置： 本 Skill 无需任何 API Key，纯本地文件操作，无网络请求。凭证等敏感信息强制间接引用，不存储在图谱中. 可用性分类： MD+EXEC（Markdown 指令 + exec 命令行执行）。核心实体/关系概念纯 Markdown 可理解；创建/查询/校验等操作需 Python 脚本执行.

已知限制(补充)

1. 默认 JSONL 不适合超大规模：>10000 实体需手动迁移到 SQLite，迁移过程需停服或锁写.
2. append-only 文件会持续增长：不主动 compact 会越来越大，compact 会丢失历史，需用户权衡.
3. 并发写入支持弱：JSONL 存储无事务，多 Skill 并发写入需外部文件锁或队列串行化.
4. 不存储敏感信息原文：Credential 类型强制间接引用（secret_ref），用户需自行管理外部密钥库.
5. 校验引擎覆盖有限：支持 7 类约束规则，但不支持复杂业务逻辑校验（如跨实体的多字段联合校验需在迁移脚本中自行实现）.
6. 无内置全文检索：仅支持结构化属性查询与图遍历，文本内容检索需外接搜索引擎.

结果格式

json

{
  "success": true,
  "data": {
    "result": "知识本体处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "knowledge ontology"
    }
  },
  "execution_log": ["解析输入参数", "执行核心处理", "格式化输出结果"],
  "error": null
}

安全基本准则

风险类型	防范措施
API密钥泄露	使用环境变量注入,不得在源码中明文写入
命令执行风险	命令执行受白名单约束,避免注入用户输入
网络通信安全	通信使用HTTPS并校验证书有效性
敏感数据暴露	返回数据中不含凭证信息

使用前请确认已阅读依赖说明章节，确保运行环境满足安全要求。

性能数据

操作场景	手动耗时	自动化耗时	效率提升
文件解析与提取	5-10分钟/个	<5秒/个	60-120x
批量文件处理(100个)	8-16小时	<5分钟	96-192x
API调用与响应解析	2-3分钟/次	<1秒/次	120-180x
多接口数据聚合	15-30分钟	<10秒	90-180x
命令执行与结果收集	3-5分钟/次	<2秒/次	90-150x
重复任务批量执行	因任务而异	线性缩减	5-50x
错误排查与修复	10-30分钟	<30秒	20-60x

优势对比

对比维度	知识本体	传统手动方式	通用脚本工具
自动化程度	全流程自动	完全手动	部分自动
错误处理	内置错误恢复	依赖人工经验	基本try-catch
可复用性	参数化配置	一次性脚本	模板化
安全合规	内置安全检查	无安全保障	无安全保障
适用场景	类型化知识图谱：约束校验+模式演进+图遍历规划，让Agent记忆结构化可验证。。	通用场景	通用场景

即刻上手

1. 配置API密钥: 在环境变量中设置对应的API Key
2. 初始化连接: 使用提供的凭证建立API连接
3. 调用接口: 传入必要参数执行API调用
4. 准备文件: 确认文件路径正确且格式受支持
5. 执行处理: 调用对应的处理函数
6. 查看结果: 检查输出文件或返回数据
7. 检查环境: 确认运行时和依赖已安装
8. 执行命令: 使用正确的参数格式执行
9. 查看输出: 检查命令输出和退出码

前置条件

• 已安装所需运行环境(参考依赖说明)
• 已获取必要的API密钥或访问凭证(如适用)
• 输入数据已准备就绪

高频问答

Q1: 知识本体支持哪些输入格式？

A1: 类型化知识图谱：约束校验+模式演进+图遍历规划，让Agent记忆结构化可验证。。面向AI Agent的类型化知识图谱系统，提供实体关系建模、约束校验、模式演进、。支持文本指令和结构化参数输入，具体格式参考使用流程章节。

Q2: 需要配置API Key吗？

A2: 是的，部分功能需要配置对应平台的API Key。请在依赖说明章节查看具体要求，并通过环境变量安全配置。

Q3: 命令行执行失败怎么办？

A3: 检查命令参数是否正确，确认运行环境支持exec能力。如遇权限问题，请参照错误处理章节排查。

知识本体通用排查步骤

1. 检查输入参数: 确认所有必填参数已提供且格式正确
2. 查看日志输出: 定位具体错误行和异常类型
3. 验证环境配置: 确认依赖库版本和运行环境满足要求
4. 逐步调试: 缩小问题范围,隔离故障模块

支持文档

错误恢复流程

针对知识本体使用中可能遇到的常见问题,提供以下排查方案:

错误类型	原因分析	解决方案
API认证失败(401)	API密钥错误或过期	检查密钥配置,重新生成token
接口限流(429)	请求频率超出限制	降低调用频率,启用重试退避策略
响应超时(504)	网络延迟或服务端负载过高	增加超时阈值,检查网络连接
文件不存在	路径错误或文件未创建	检查路径拼写,确认文件已生成
文件格式不支持	扩展名不在支持列表中	转换为支持的格式后重试
权限不足	当前用户无读写权限	检查文件权限,以管理员身份运行
命令执行失败	参数错误或环境依赖缺失	检查命令语法,确认依赖已安装
进程超时	命令执行时间过长	增加超时设置,优化命令参数
网络连接失败	DNS解析失败或防火墙拦截	检查网络配置,确认代理设置