本体论

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

核心概念

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

实体：{ id, type, properties, relations, created, updated }
关系：{ from_id, relation_type, to_id, properties }

使用场景

核心类型

# 代理与人
人员: { 姓名, 邮箱?, 电话?, 备注? }
组织: { 名称, 类型?, 成员[] }

# 工作
项目: { 名称, 状态, 目标[], 负责人? }
任务: { 标题, 状态, 截止日期?, 优先级?, 分配人?, 阻碍项[] }
目标: { 描述, 目标日期?, 指标[] }

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

# 信息
文档: { 标题, 路径?, 网址?, 摘要? }
消息: { 内容, 发送者, 接收者[], 所属线程? }
线程: { 主题, 参与者[], 消息[] }
笔记: { 内容, 标签[], 引用[] }

# 资源
账户: { 服务, 用户名, 凭证引用? }
设备: { 名称, 类型, 标识符[] }
凭证: { 服务, 密钥引用 }  # 切勿直接存储密钥

# 元数据
操作: { 类型, 目标, 时间戳, 结果? }
策略: { 范围, 规则, 执行方式 }

存储

默认：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"}

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

仅追加规则

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

工作流

创建实体

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

查询

python3 scripts/ontology.py query --type Task --where '{"status":"open"}'
python3 scripts/ontology.py get --id task_001
python3 scripts/ontology.py related --id proj_001 --rel has_task

链接实体

python3 scripts/ontology.py relate --from proj_001 --rel has_task --to task_001

验证

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

约束条件

定义于memory/ontology/schema.yaml：

类型:
  Task:
    必需字段: [标题, 状态]
    状态枚举: [开放, 进行中, 阻塞, 已完成]
  
  Event:
    必需字段: [标题, 开始时间]
    验证: "如果存在结束时间，则结束时间 >= 开始时间"

  Credential:
    必需字段: [服务, 密钥引用]
    禁止属性: [密码, 密钥, 令牌]  # 强制间接引用

关系:
  has_owner:
    起始类型: [项目, 任务]
    目标类型: [人员]
    基数: 多对一
  
  blocks:
    起始类型: [任务]
    目标类型: [任务]
    无环: true  # 禁止循环依赖

技能契约

使用本体的技能应声明：

# 在 SKILL.md 的 frontmatter 或页眉中
本体:
  读取: [任务, 项目, 人员]
  写入: [任务, 行动]
  前置条件:
    - "任务.负责人 必须存在"
  后置条件:
    - "创建的任务状态为 开放"

作为图变换的规划

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

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

1. 创建 事件 { 标题: "团队同步", 参与者: [p_001, p_002] }
2. 关联 事件 -> has_project -> proj_001
3. 创建 任务 { 标题: "准备议程", 负责人: p_001 }
4. 关联 任务 -> for_event -> event_001
5. 创建 任务 { 标题: "发送总结", 负责人: p_001, 阻塞者: [task_001] }

每个步骤在执行前都会进行验证。若违反约束条件则回滚。

集成模式

与因果推理集成

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

# 创建/更新实体时，也记录到因果行动日志
action = {
    "action": "create_entity",
    "domain": "ontology", 
    "context": {"type": "Task", "project": "proj_001"},
    "outcome": "created"
}

跨技能通信

# 邮件技能创建承诺
commitment = ontology.create("Commitment", {
    "source_message": msg_id,
    "description": "Send report by Friday",
    "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
    })

快速开始

# 初始化本体存储
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的检查；其他更高级别的约束可能仍仅作为文档存在，除非在代码中实现。