类型化知识图谱引擎

核心功能: 本技能提供中文交互、基础结构化记忆、化工作流场景等能力。

类型化知识图谱引擎（基础版）

将知识表示为可验证的实体-关系图谱系统。一切皆为实体，拥有类型、属性和与其他实体的关系。每次变更在提交前根据类型约束进行验证，确保图谱一致性。支持追加式变更日志，保留完整历史记录。

核心能力

1. 类型化实体创建与验证

创建带有类型约束的实体，支持核心预定义类型和自定义扩展：

参数：--type（实体类型）、--props（JSON格式属性）

输出：实体ID（如 p_001、task_003）、创建时间戳、验证结果。

2. 关系图谱与基数约束

在实体之间建立类型化关系，支持基数约束验证：

参数：--from（源实体ID）、--rel（关系类型）、--to（目标实体ID）

输出：关系记录、基数验证结果。

3. Schema约束系统

通过 memory/ontology/schema.yaml 定义类型约束，所有变更在提交前强制验证：

types:
  Task:
    required: [title, status]
    status_enum: [open, in_progress, blocked, done]
  Event:
    required: [title, start]
    validate: "end >= start if end exists"

支持的约束类型：必填属性（required）、枚举值（enum）、自定义验证（validate）、关系基数（cardinality）。

输出: 返回Schema约束系统的执行结果,包含操作状态和输出数据。

4. 图谱遍历查询

支持基础查询和关联遍历操作：

输出: 返回图谱遍历查询的执行结果,包含操作状态和输出数据。

使用流程

领先步：初始化图谱目录与Schema

创建 memory/ontology/ 目录和空的 graph.jsonl 文件。编写 schema.yaml 定义项目所需的实体类型和关系约束。执行 python3 scripts/ontology.py validate 验证Schema格式正确。

第二步：创建核心实体并建立关系

根据项目需求创建 Person、Project、Task 等基础实体，使用 relate 命令在实体之间建立关系。创建关系时系统自动验证基数约束，违反约束的操作被拒绝并返回错误信息。

第三步：查询与验证图谱

使用 query、get、related 等命令查询图谱信息。定期执行 validate 命令检查所有约束是否满足。

错误处理

示例

示例：创建项目任务体系并建立关系

场景：为"网站重设计"项目创建负责人和任务列表。

# 创建人员
python3 scripts/ontology.py create --type Person --props '{"name":"Alice","email":"alice@example.com"}'
# 返回: {"id":"p_001","type":"Person","properties":{"name":"Alice","email":"alice@example.com"}}

# 创建项目
py create --type Project --props '{"name":"Website Redesign","status":"active"}'
# 返回: {"id":"proj_001","type":"Project","properties":{"name":"Website Redesign","status":"active"}}

# 建立项目-负责人关系
py relate --from proj_001 --rel has_owner --to p_001
# 返回: {"from":"proj_001","rel":"has_owner","to":"p_001","validated":true}

# 创建任务
py create --type Task --props '{"title":"设计首页原型","status":"open","priority":8}'
# 返回: {"id":"task_001","type":"Task","properties":{"title":"设计首页原型","status":"open","priority":8}}

# 建立项目-任务关系
py relate --from proj_001 --rel has_task --to task_001
# 返回: {"validated":true}

# 查询项目所有任务
py related --id proj_001 --rel has_task
# 返回: [task_001]

FAQ

Q1: 知识图谱的数据存储在哪里？支持什么格式？

默认存储在 memory/ontology/graph.jsonl，采用追加式JSONL格式，每行一个操作记录。追加式写入保证历史可追溯，支持回放重建任意时间点状态。

Q2: 如何自定义新的实体类型和关系类型？

在 memory/ontology/schema.yaml 中的 types 下新增类型定义，指定 required（必填属性）、enum（枚举值）等约束。在 relations 下新增关系定义，指定 from_types、to_types、cardinality（基数）。新增后执行 validate 命令确认Schema格式正确。

Q3: 图谱文件被意外修改后如何恢复？

graph.jsonl 采用追加式写入，每行是独立的JSON记录。如果部分行损坏，可手动检查并修复损坏的JSON行。建议将 memory/ontology/ 目录纳入Git版本控制，定期提交变更，通过 git checkout 恢复到最近的有效版本。

依赖说明

运行环境

• Agent平台：支持 SKILL.md 的任意 AI Agent（Claude Code / Cursor / Codex / Gemini CLI 等）
• 操作系统：Windows / macOS / Linux
• Python环境：Python 3.8+（脚本执行依赖）
• 本地存储：可写的 memory/ontology/ 目录

依赖项

API Key 配置

• 核心功能无需任何 API Key

可用性分类

• 分类：MD+EXEC（Markdown指令驱动，需exec执行Python脚本）
• 说明：通过自然语言指令驱动Agent执行图谱创建、查询和验证操作

已知限制

1. 无无环验证：基础版不支持 depends_on 和 blocks 关系的循环依赖检测，无法自动防止任务依赖形成环。
2. 实体类型有限：基础版仅支持 Person、Project、Task、Document、Note 5种核心类型，不支持 Credential、Event、Location 等高级类型。
3. 无跨技能契约：基础版不支持技能间的读写权限声明和前后置条件验证，多技能协作时需手动协调。
4. 无计划即图谱变换：基础版不支持将多步计划建模为图谱操作序列，无法实现步骤级验证和自动回滚。
5. 查询深度有限：基础版关联查询仅支持单跳遍历，无法进行多跳依赖链和路径查询。

升级提示

当前为基础版，以下高级能力需升级至完整版解锁：

• 无环验证（DAG检查）：对 blocks 和 depends_on 关系执行有向无环图检查，自动防止循环依赖，检测到环时返回完整环路路径。
• 12种核心实体类型：在基础5种类型上增加 Organization、Goal、Event、Location、Message、Account、Credential 共7种高级类型，支持更丰富的知识建模。
• 跨技能契约声明：通过 reads/writes/preconditions/postconditions 声明技能读写范围，前置条件执行前验证，后置条件执行后验证，违反时自动回滚。
• 计划即图谱变换：将多步计划建模为图谱操作序列，每步验证通过后提交，任一步骤失败则回滚已执行步骤。
• 多跳图谱遍历：支持 --depth 参数控制遍历深度（最多3跳），支持路径查询 path --from --to 查找两实体间的关系路径。
• 追加式变更日志修复：提供 validate --repair 命令自动修复损坏的JSONL行，支持从最近有效状态重建图谱。
• 大规模图谱迁移：支持将JSONL图谱迁移至 SQLite数据库，提升1000+实体规模的查询性能。

升级至完整版以获取全部8项核心能力、8个领域专属错误处理场景和2个完整实战案例。

安全注意事项

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

效率量化分析

差异化对比

核心功能

• 自动化执行: 基于指令驱动的自动化流程
• 文件处理: 支持多种文件格式的读取、解析和写入操作
• API集成: 通过标准化接口调用外部服务并处理响应
• 命令执行: 在安全沙箱中执行系统命令并收集结果
• 信息检索: 快速搜索和过滤目标数据