slug: ontology name: "ontology" version: 1.0.6 displayName: "类型化知识图谱引擎" summary: '"基于类型约束的知识图谱系统，为智能代理提供结构化记忆与可组合技能。类型化知识图谱引擎，将知识表示为可验证的实体-关系图谱。每个实体拥有类型、属性和关系， 所有变更在提交前根据类型约束进行验证"' summary_zh: '"基于类型约束的知识图谱系统，为智能代理提供结构化记忆与可组合技能。类型化知识图谱引擎，将知识表示为可验证的实体-关系图谱。每个实体拥有类型、属性和关系， 所有变更在提交前根据类型约束进行验证"' license: "MIT" description: | 类型化知识图谱引擎，将知识表示为可验证的实体-关系图谱。每个实体拥有类型、属性和关系， 所有变更在提交前根据类型约束进行验证。核心能力涵盖类型化实体创建与验证、关系图谱与基数约束、。Use when 需要AI模型调用、智能对话、Agent编排、LLM应用时使用。不适用于需要100%确定性的关键决策。 功能涵盖: ontology。 Schema约束系统、无环验证、追加式变更日志、图谱遍历查询、跨技能契约声明、计划即图谱变换. 支持 Person、Organization、Project、Task、Goal、Event、Document、Credential 等12种核心实体类型， 可通过Schema自定义扩展。数据以追加式 JSONL 格式存储，支持迁移至 SQLite数据库. ...' tools:

• read
• exec
• write homepage: '""' tags:
• 知识
• task
• person
• title
• status
• schema category: '"Automation"' homepage: "" pricing_tier: "L2-标准级"

类型化知识图谱引擎

输入规范

专业版增强能力

能力矩阵

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

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

参数：--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"
  Credential:
    required: [service, secret_ref]
    forbidden_properties: [password, secret, token]

支持的约束类型：必填属性（required）、枚举值（enum）、禁止属性（forbidden_properties）、自定义验证（validate）、关系基数（cardinality）、无环约束（acyclic）.

4. 无环验证（DAG检查）

对标记为 acyclic: true 的关系类型执行有向无环图检查，防止循环依赖：

• 创建 blocks 关系时检查是否形成环
• 创建 depends_on 关系时检查依赖链是否循环
• 检测到环时拒绝操作并返回完整环路路径

5. 追加式变更日志

所有图谱变更以追加方式记录在 memory/ontology/graph.jsonl，保留完整操作历史：

{"op":"create","entity":{"id":"p_001","type":"Person","properties":{"name":"Alice"}}}
{"op":"create","entity":{"id":"proj_001","type":"Project","properties":{"name":"Website Redesign","status":"active"}}}
{"op":"relate","from":"proj_001","rel":"has_owner","to":"p_001"}
{"op":"update","entity_id":"proj_001","changes":{"status":"in_progress"}}

变更类型：create（创建实体）、relate（创建关系）、update（更新属性）、delete（标记删除）。追加式写入保证历史可追溯，支持回放重建任意时间点的图谱状态.

6. 图谱遍历查询

支持多维度查询和图谱遍历操作：

7. 跨技能契约声明

使用本图谱的技能通过契约声明其读写范围，确保技能间数据隔离与安全协作：

ontology:
  reads: [Task, Project, Person]
  writes: [Task, Action]
  preconditions:
    - "Task.assignee must exist as Person"
  postconditions:
    - "Created Task has status=open"

前置条件在技能执行前验证，后置条件在执行后验证，违反条件时中止操作并回滚.

• 异常时参考错误处理章节进行恢复
• 关键参数: 跨技能契约声明 选项

8. 计划即图谱变换

将多步计划建模为图谱操作序列，每步在执行前验证，违反约束时回滚：

计划："安排团队会议并创建后续任务"
# ...
领先步: CREATE Event { title: "团队周会", attendees: [p_001, p_002] }
第二步: RELATE Event -> has_project -> proj_001
第三步: CREATE Task { title: "准备议程", assignee: p_001 }
第四步: RELATE Task -> for_event -> event_001
第五步: CREATE Task { title: "发送会议纪要", assignee: p_001, blockers: [task_001] }

每步验证通过后提交，任一步骤失败则回滚已执行的步骤，保证图谱一致性.

使用方法

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

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

第二步：创建核心实体

根据项目需求创建 Person、Project、Task 等基础实体。使用 create --type Person --props '{"name":"Alice","email":"alice@example.com"}' 命令逐个创建，系统自动分配ID并验证属性约束.

第三步：建立实体关系

使用 relate 命令在实体之间建立关系。创建 has_owner、has_task、blocks 等关系时，系统自动验证基数约束和无环约束。违反约束的操作被拒绝并返回详细错误信息.

第四步：查询与遍历图谱

使用 query、get、related、path 等命令查询图谱信息。复杂查询可通过 --depth 参数控制遍历深度，或通过 --where 条件过滤结果.

第五步：验证与维护

定期执行 python3 （请参考skill目录中的脚本文件） validate 检查所有约束。审查变更日志确认操作历史。大规模图谱（1000+实体）可迁移至 SQLite数据库 提升查询性能.

错误应对体系

用法示例

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

场景：为"网站重设计"项目创建负责人、任务列表和任务间依赖.

# 创建人员
python3 （请参考skill目录中的脚本文件） create --type Person --props '{"name":"Alice","email":"alice@example.com"}'
# 返回: {"id":"p_001","type":"Person","properties":{"name":"Alice","email":"alice@example.com"}}
# ...
# 创建项目
python3 （请参考skill目录中的脚本文件） create --type Project --props '{"name":"Website Redesign","status":"active","goals":["提升转化率","改善移动端体验"]}'
# 返回: {"id":"proj_001","type":"Project","properties":{"name":"Website Redesign","status":"active"}}
# ...
# 建立项目-负责人关系
python3 （请参考skill目录中的脚本文件） relate --from proj_001 --rel has_owner --to p_001
# 返回: {"from":"proj_001","rel":"has_owner","to":"p_001","validated":true}
# ...
# 创建任务
python3 （请参考skill目录中的脚本文件） create --type Task --props '{"title":"设计首页原型","status":"open","priority":8}'
# 返回: {"id":"task_001","type":"Task","properties":{"title":"设计首页原型","status":"open","priority":8}}
# ...
python3 （请参考skill目录中的脚本文件） create --type Task --props '{"title":"前端开发实现","status":"open","priority":7}'
# 返回: {"id":"task_002","type":"Task","properties":{"title":"前端开发实现","status":"open","priority":7}}
# ...
# 建立任务依赖（task_002 依赖 task_001）
python3 （请参考skill目录中的脚本文件） relate --from task_002 --rel depends_on --to task_001
# 返回: {"from":"task_002","rel":"depends_on","to":"task_001","acyclic_check":true,"validated":true}
# ...
# 建立项目-任务关系
python3 （请参考skill目录中的脚本文件） relate --from proj_001 --rel has_task --to task_001
python3 （请参考skill目录中的脚本文件） relate --from proj_001 --rel has_task --to task_002
# ...
# 查询项目所有任务
python3 （请参考skill目录中的脚本文件） related --id proj_001 --rel has_task
# 返回: [task_001, task_002]
# ...
# 查询任务依赖链
python3 （请参考skill目录中的脚本文件） related --id task_002 --rel depends_on --depth 3
# 返回: [task_001]

示例二：多步计划建模与约束回滚

场景：安排团队会议并创建后续任务，中途因约束违反触发回滚.

# Schema定义（memory/ontology/schema.yaml）
# Task:
#   required: [title, status]
#   status_enum: [open, in_progress, blocked, done]
# Event:
#   required: [title, start]
#   validate: "end >= start if end exists"
# ...
# 领先步：创建会议事件
python3 （请参考skill目录中的脚本文件） create --type Event --props '{"title":"团队周会","start":"2026-07-20T10:00:00","end":"2026-07-20T11:00:00","attendees":["p_001","p_002"]}'
# 返回: {"id":"event_001","validated":true}
# ...
# 第二步：创建准备议程任务
python3 （请参考skill目录中的脚本文件） create --type Task --props '{"title":"准备会议议程","status":"open","assignee":"p_001"}'
# 返回: {"id":"task_003","validated":true}
# ...
# 第三步：尝试创建状态非法的任务（触发约束违反）
python3 （请参考skill目录中的脚本文件） create --type Task --props '{"title":"发送会议纪要","status":"pending"}'
# 返回错误: {"error":"ENUM_VIOLATION","property":"status","value":"pending","allowed":["open","in_progress","blocked","done"]}
# 操作被拒绝，task_003 之前创建的实体不受影响
# ...
# 修正后重新创建
python3 （请参考skill目录中的脚本文件） create --type Task --props '{"title":"发送会议纪要","status":"open","assignee":"p_001"}'
# 返回: {"id":"task_004","validated":true}
# ...
# 建立任务依赖（发送纪要依赖准备议程）
python3 （请参考skill目录中的脚本文件） relate --from task_004 --rel depends_on --to task_003
# 返回: {"acyclic_check":true,"validated":true}
# ...
# 尝试创建循环依赖（task_003 依赖 task_004，形成环）
python3 （请参考skill目录中的脚本文件） relate --from task_003 --rel depends_on --to task_004
# 返回错误: {"error":"CYCLE_DETECTED","path":["task_003","task_004","task_003"]}
# 操作被拒绝，无环约束生效

高频问答

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

默认存储在 memory/ontology/graph.jsonl，采用追加式JSONL格式，每行一个操作记录。追加式写入保证历史可追溯，支持回放重建任意时间点状态。对于大规模图谱（1000+实体），可迁移至 SQLite数据库 提升查询性能，迁移脚本保留JSONL作为备份.

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

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

Q3: 无环约束是如何检测循环依赖的？

对标记为 acyclic: true 的关系类型（如 blocks、depends_on），每次创建关系时执行深度优先搜索（DFS）检查从目标实体回到源实体是否存在路径。如果存在路径则形成环，操作被拒绝并返回完整环路路径（如 ["task_003","task_004","task_003"]），帮助用户定位和修复循环依赖.

Q4: 跨技能契约声明的作用是什么？如何配置？

跨技能契约声明确保使用本图谱的不同技能不会越权读写。在技能的SKILL.md中声明 ontology.reads（可读类型）、ontology.writes（可写类型）、preconditions（前置条件）、postconditions（后置条件）。技能执行前验证前置条件（如"Task.assignee必须存在为Person"），执行后验证后置条件（如"创建的Task状态为open"），违反条件时中止并回滚.

Q5: Credential类型为什么禁止直接存储密码和令牌？

Credential类型在Schema中设置了 forbidden_properties: [password, secret, token]，强制通过 secret_ref 间接引用外部密钥管理服务（如HashiCorp Vault、AWS Secrets Manager）。这确保敏感凭证不会以明文形式存储在图谱文件中，降低泄露风险。图谱仅记录凭证的引用标识，实际凭证值由专门的密钥管理工具保护.

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

graph.jsonl 采用追加式写入，每行是独立的JSON记录。如果部分行损坏，执行 validate --repair 命令尝试修复损坏的JSON行。无法修复的行会被备份到 graph.jsonl.bak 后从主文件移除。如果使用Git版本控制，可通过 git checkout 恢复到最近的有效版本。建议将 memory/ontology/ 目录纳入Git管理，定期提交变更.

环境要求

运行环境

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

依赖项

API Key 配置

• 核心功能无需任何 API Key
• Credential类型的 secret_ref 引用的外部密钥管理服务需对应服务的访问凭证

可用性分类

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

限制条件

1. 并发写入不支持：追加式JSONL文件不支持多进程并发写入，多Agent同时操作同一图谱文件可能导致数据损坏，建议单写者模式或引入文件锁机制.
2. 全文搜索能力有限：当前查询基于属性精确匹配和关系遍历，不支持模糊搜索和全文检索，大规模文本内容检索需配合外部搜索引擎.
3. Schema变更不自动迁移：修改Schema定义后（如新增必填属性），已有实体不会自动补全新属性，需手动执行迁移脚本或逐个更新.
4. 无内置版本控制：图谱变更历史通过追加日志保留，但缺乏内置的版本快照和差异对比功能，需配合Git等外部版本控制工具使用.
5. 关系属性支持有限：当前关系类型主要支持实体间关联，关系本身的属性（如关系的有效时间、权重）需通过额外的属性表管理.

安全规范

差异化分析

效能分析

差异分析