ontology

本體論

一個類型化詞彙表 + 約束系統，用於將知識表示為可驗證的圖形。

核心概念

一切都是實體，具有類型、屬性以及與其他實體的關係。每次變更在提交前都會根據類型約束進行驗證。

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

使用時機

觸發詞	動作
「記住…」	建立/更新實體
「我知道關於 X 的什麼？」	查詢圖譜
「連結 X 到 Y」	建立關係
「顯示專案 Z 的所有任務」	圖形遍歷
「什麼依賴於 X？」	依賴查詢
規劃多步驟工作	建模為圖形轉換
技能需要共享狀態	讀寫本體物件

核心類型

# 代理與人員
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。

工作流程

建立實體

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.md 的 frontmatter 或標頭中
ontology:
  reads: [Task, Project, Person]
  writes: [Task, Action]
  preconditions:
    - "Task.assignee must exist"
  postconditions:
    - "Created Task has status=open"

規劃為圖形轉換

將多步驟計劃建模為一系列圖形操作：

Plan: "安排團隊會議並建立後續任務"

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] }

每個步驟在執行前都會經過驗證。若違反約束則進行回滾。

整合模式

與因果推論整合

將本體變更記錄為因果動作：

# 建立/更新實體時，同時記錄到因果動作日誌
action = {
    "action": "create_entity",
    "domain": "ontology", 
    "context": {"type": "Task", "project": "proj_001"},
    "outcome": "created"
}

跨技能通訊

# Email 技能建立承諾
commitment = ontology.create("Commitment", {
    "source_message": msg_id,
    "description": "Send report by Friday",
    "due": "2026-01-31"
})

# Task 技能接手
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

# 建立 schema（建議但非必要）
cat > memory/ontology/schema.yaml << 'EOF'
types:
  Task:
    required: [title, status]
  Project:
    required: [name]
  Person:
    required: [name]
EOF

# 開始使用
python3 scripts/ontology.py create --type Person --props '{"name":"Alice"}'
python3 scripts/ontology.py list --type Person

參考資料

• references/schema.md — 完整類型定義與約束模式
• references/queries.md — 查詢語言與遍歷範例