知识本体

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

知识本体（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中声明的使用场景,均已在上述能力点中提供对应的操作支持.

参数说明

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）

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

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

Step 3：建立关系

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

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

Step 4：查询与遍历

# 按类型+条件查询
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

已知限制

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

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

# 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：多步规划建模（图变换序列）

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

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

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

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

用法示例

示例 1：项目依赖管理

输入：

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

执行：

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

输出：

执行顺序：
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：影响分析

输入：

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

执行：

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

输出：

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

示例 3：凭证安全存储

输入：

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

执行：

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

输出：

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

环境要求

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. 无内置全文检索：仅支持结构化属性查询与图遍历，文本内容检索需外接搜索引擎.

结果格式

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

安全基本准则

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

性能数据

优势对比

即刻上手

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. 逐步调试: 缩小问题范围,隔离故障模块

支持文档

错误恢复流程

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