本体

一个类型化词汇表+约束系统，用于将知识表示为可验证的图。

核心概念

一切都是具有类型、属性以及与其他实体关系的实体。每次变更在提交前都会根据类型约束进行验证。

实体: { id, 类型, 属性, 关系, 创建时间, 更新时间 }
关系: { 来源id, 关系类型, 目标id, 属性 }

使用场景

触发条件	操作
记住...	创建/更新实体
关于X我知道什么？

查询图 | | 将X链接到Y | 创建关系 | | 显示项目Z的所有任务 | 图遍历 | | 什么依赖于X？ | 依赖查询 | | 规划多步骤工作 | 建模为图变换 | | 技能需要共享状态 | 读取/写入本体对象 |

核心类型

yaml

代理与人员

Person: { 姓名, 邮箱?, 电话?, 备注? }
Organization: { 名称, 类型?, 成员[] }

工作

Project: { 名称, 状态, 目标[], 负责人? } Task: { 标题, 状态, 截止日期?, 优先级?, 执行人?, 阻塞项[] } Goal: { 描述, 目标日期?, 指标[] }

时间与地点

Event: { 标题, 开始时间, 结束时间?, 地点?, 参与者[], 重复规则? } Location: { 名称, 地址?, 坐标? }

信息

Document: { 标题, 路径?, URL?, 摘要? } Message: { 内容, 发送者, 接收者[], 线程? } Thread: { 主题, 参与者[], 消息[] } Note: { 内容, 标签[], 引用[] }

资源

Account: { 服务, 用户名, 凭证引用? } Device: { 名称, 类型, 标识符[] } Credential: { 服务, 密钥引用 } # 切勿直接存储密钥

元数据

Action: { 类型, 目标, 时间戳, 结果? } Policy: { 范围, 规则, 执行方式 }

存储

默认路径: memory/ontology/graph.jsonl

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:proj001,rel:hasowner,to:p_001}

通过脚本或直接文件操作进行查询。对于复杂图，可迁移至SQLite。

仅追加规则

处理现有本体数据或模式时，应追加/合并变更而非覆盖文件。这可以保留历史记录并避免覆盖先前的定义。

工作流程

创建实体

bash
python3 scripts/ontology.py create --type Person --props {name:Alice,email:alice@example.com}

查询

bash
python3 scripts/ontology.py query --type Task --where {status:open}
python3 scripts/ontology.py get --id task_001
python3 scripts/ontology.py related --id proj001 --rel hastask

链接实体

bash
python3 scripts/ontology.py relate --from proj001 --rel hastask --to task_001

验证

bash
python3 scripts/ontology.py validate # 检查所有约束

约束

定义在 memory/ontology/schema.yaml:

yaml
types:
Task:
required: [title, status]
statusenum: [open, inprogress, blocked, done]

Event:
required: [title, start]
validate: end >= start if end exists

Credential:
required: [service, secret_ref]
forbidden_properties: [password, secret, token] # 强制间接引用

relations:
has_owner:
from_types: [Project, Task]
to_types: [Person]
cardinality: manytoone

blocks:
from_types: [Task]
to_types: [Task]
acyclic: true # 无循环依赖

技能契约

使用本体的技能应声明：

yaml

在 SKILL.md 前言或头部

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

作为图变换的规划

将多步骤计划建模为一系列图操作：

计划: 安排团队会议并创建后续任务

1. 1. CREATE Event { title: 团队同步, 参与者: [p001, p002] }
2. RELATE Event -> hasproject -> proj001
3. CREATE Task { title: 准备议程, 执行人: p001 }
4. RELATE Task -> forevent -> event001
5. CREATE Task { title: 发送总结, 执行人: p001, 阻塞项: [task_001] }

每一步在执行前都经过验证。违反约束时回滚。

集成模式

与因果推断集成

将本体变更记录为因果动作：

python

创建/更新实体时，同时记录到因果动作日志

action = {
action: create_entity,
domain: ontology,
context: {type: Task, project: proj_001},
outcome: created
}

跨技能通信

python

邮件技能创建承诺

commitment = ontology.create(Commitment, {
sourcemessage: msgid,
description: 周五前发送报告,
due: 2026-01-31
})

任务技能获取承诺

tasks = ontology.query(Commitment, {status: pending}) for c in tasks: ontology.create(Task, { title: c.description, due: c.due, source: c.id })

快速开始

bash

初始化本体存储

mkdir -p memory/ontology
touch memory/ontology/graph.jsonl

创建模式（可选但推荐）

python3 scripts/ontology.py schema-append --data { types: { Task: { required: [title, status] }, Project: { required: [name] }, Person: { required: [name] } } }

开始使用

python3 scripts/ontology.py create --type Person --props {name:Alice} python3 scripts/ontology.py list --type Person

参考资料

• - references/schema.md — 完整类型定义和约束模式
• references/queries.md — 查询语言和遍历示例

指令范围

运行时指令操作本地文件（memory/ontology/graph.jsonl 和 memory/ontology/schema.yaml），并提供创建/查询/关联/验证的CLI使用方式；这属于本技能范围。该技能读取/写入工作区文件，并在使用时创建 memory/ontology 目录。验证包括属性/枚举/禁止项检查、关系类型/基数验证、标记为 acyclic: true 的关系的无环性检查，以及事件 end >= start 检查；其他更高级别的约束可能仍仅为文档说明，除非已在代码中实现。