本体（Ontology）

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

核心概念

所有事物均为一个实体（entity），具有类型（type）、属性（properties）以及与其他实体的关系（relations）。每次变更（mutation）在提交前均需通过类型约束校验。

Entity: { id, type, properties, relations, created, updated }
Relation: { from_id, relation_type, to_id, properties }

适用场景

核心类型

# 代理与人员
Person: { name, email?, phone?, notes? }
Organization: { name, type?, members[] }

# 工作
Project: { name, status, goals[], owner? }
Task: { title, status, due?, priority?, assignee?, blockers[] }
Goal: { description, target_date?, metrics[] }

# 时间与地点
Event: { title, start, end?, location?, attendees[], recurrence? }
Location: { name, address?, coordinates? }

# 信息
Document: { title, path?, url?, summary? }
Message: { content, sender, recipients[], thread? }
Thread: { subject, participants[], messages[] }
Note: { content, tags[], refs[] }

# 资源
Account: { service, username, credential_ref? }
Device: { name, type, identifiers[] }
Credential: { service, secret_ref }  # 禁止直接存储密钥

# 元信息
Action: { type, target, timestamp, outcome? }
Policy: { scope, rule, enforcement }

存储

默认路径：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。

仅追加规则（Append-Only Rule）

在处理已有本体数据或模式时，应追加/合并（append/merge）变更，而非覆盖文件。此举可保留历史记录，并避免覆盖先前定义。

工作流

创建实体

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 中定义：

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]  # 强制间接引用

relations:
  has_owner:
    from_types: [Project, Task]
    to_types: [Person]
    cardinality: many_to_one
  
  blocks:
    from_types: [Task]
    to_types: [Task]
    acyclic: true  # 禁止循环依赖

技能契约（Skill Contract）

使用本体的技能应在声明中明确：

# 在 SKILL.md 前置元数据（frontmatter）或标题中
ontology:
  reads: [Task, Project, Person]
  writes: [Task, Action]
  preconditions:
    - "Task.assignee 必须存在"
  postconditions:
    - "新创建的 Task 的 status 字段值为 open"

将规划建模为图变换

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

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

1. CREATE Event { title: "Team Sync", attendees: [p_001, p_002] }
2. RELATE Event -> has_project -> proj_001
3. CREATE Task { title: "Prepare agenda", assignee: p_001 }
4. RELATE Task -> for_event -> event_001
5. CREATE Task { title: "Send summary", assignee: p_001, blockers: [task_001] }

每一步操作执行前均进行校验；若违反约束，则回滚。

集成模式

与因果推理（Causal Inference）集成

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

# 创建或更新实体时，同步记录至因果动作日志
action = {
    "action": "create_entity",
    "domain": "ontology", 
    "context": {"type": "Task", "project": "proj_001"},
    "outcome": "created"
}

跨技能通信

# 邮件技能创建承诺（Commitment）
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 接口用于 create/query/relate/validate 操作；该范围属于本规范覆盖范畴。该技能将读写 workspace 文件，并在首次使用时自动创建 memory/ontology 目录。校验涵盖属性必填项、枚举值、禁用属性检查；关系类型与基数（cardinality）校验；对标注 acyclic: true 的关系执行无环性（acyclicity）检查；以及 Event 类型中 end >= start 的时间逻辑校验。其余更高层级的约束若未在代码中实现，则仍仅为文档说明性质。