介绍
# Ontology
一种用于将知识表示为可验证图谱的类型化词汇表 + 约束系统。
## 核心概念
一切都是**实体**，拥有**类型**、**属性**以及与其他实体的**关系**。每次变更在提交前都会根据类型约束进行验证。
``` Entity: { id, type, properties, relations, created, updated } Relation: { from_id, relation_type, to_id, properties } ```
## 适用场景
| 触发条件 | 操作 | |---------|--------| | “记住……” | 创建/更新实体 | | “关于 X 我知道些什么？” | 查询图谱 | | “将 X 链接到 Y” | 创建关系 | | “显示项目 Z 的所有任务” | 图谱遍历 | | “什么依赖于 X？” | 依赖查询 | | 规划多步骤工作 | 建模为图谱变换 | | 技能需要共享状态 | 读/写本体对象 |
## 核心类型
```yaml # Agents & People Person: { name, email?, phone?, notes? } Organization: { name, type?, members[] }
# Work Project: { name, status, goals[], owner? } Task: { title, status, due?, priority?, assignee?, blockers[] } Goal: { description, target_date?, metrics[] }
# Time & Place Event: { title, start, end?, location?, attendees[], recurrence? } Location: { name, address?, coordinates? }
# Information Document: { title, path?, url?, summary? } Message: { content, sender, recipients[], thread? } Thread: { subject, participants[], messages[] } Note: { content, tags[], refs[] }
# Resources Account: { service, username, credential_ref? } Device: { name, type, identifiers[] } Credential: { service, secret_ref } # Never store secrets directly
# Meta Action: { type, target, timestamp, outcome? } Policy: { scope, rule, enforcement } ```
## 存储
默认：`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":"proj_001","rel":"has_owner","to":"p_001"} ```
通过脚本或直接文件操作进行查询。对于复杂的图谱，请迁移到 SQLite。
### 仅追加规则
处理现有的本体数据或架构时，请**追加/合并 (append/merge)** 更改，而不是覆盖文件。这可以保留历史记录并避免覆盖之前的定义。
## 工作流
### 创建实体
```bash python3 scripts/ontology.py create --type Person --props '{"name":"Alice","email":"[email protected]"}' ```
### 查询
```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 proj_001 --rel has_task ```
### 链接实体
```bash python3 scripts/ontology.py relate --from proj_001 --rel has_task --to task_001 ```
### 验证
```bash python3 scripts/ontology.py validate # Check all constraints ```
## 约束
在 `memory/ontology/schema.yaml` 中定义：
```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] # Force indirection
relations: has_owner: from_types: [Project, Task] to_types: [Person] cardinality: many_to_one blocks: from_types: [Task] to_types: [Task] acyclic: true # No circular dependencies ```
## 技能契约
使用本体的技能应声明：
```yaml # In SKILL.md frontmatter or header ontology: reads: [Task, Project, Person] writes: [Task, Action] preconditions: - "Task.assignee must exist" postconditions: - "Created Task has status=open" ```
## 规划即图谱变换
将多步骤计划建模为一系列图谱操作：
``` Plan: "Schedule team meeting and create follow-up tasks"
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] } ```
每个步骤在执行前都会经过验证。如果违反约束，则回滚。
## 集成模式
### 与因果推断集成
将本体变更记录为因果动作：
```python # When creating/updating entities, also log to causal action log action = { "action": "create_entity", "domain": "ontology", "context": {"type": "Task", "project": "proj_001"}, "outcome": "created" } ```
### 跨技能通信
```python # Email skill creates commitment commitment = ontology.create("Commitment", { "source_message": msg_id, "description": "Send report by Friday", "due": "2026-01-31" })
# Task skill picks it up tasks = ontology.query("Commitment", {"status": "pending"}) for c in tasks: ontology.create("Task", { "title": c.description, "due": c.due, "source": c.id }) ```
## 快速开始
```bash # Initialize ontology storage mkdir -p memory/ontology touch memory/ontology/graph.jsonl
# Create schema (optional but recommended) python3 scripts/ontology.py schema-append --data '{ "types": { "Task": { "required": ["title", "status"] }, "Project": { "required": ["name"] }, "Person": { "required": ["name"] } } }'
# Start using 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` 检查；其他高级约束可能仍仅作为文档说明，除非在代码中实现。