Ontology：面向 AI Agent 的结构化知识图谱 - Openclaw Skills

下载入口:https://github.com/openclaw/skills/tree/main/skills/oswalpalash/ontology

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

npx clawhub@latest install ontology

2. 手动安装

将技能文件夹复制到以下位置之一

全局模式 ~/.openclaw/skills/ 工作区 <project>/skills/

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

请帮我使用 Clawhub 安装 ontology。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。

什么是 Ontology？

Ontology 是一个强大的框架，用于在 Openclaw Skills 生态系统中将知识表示为可验证的图谱。它超越了简单的基于文本的记忆，将每一条信息视为具有特定类型、属性以及与其他对象存在关系的实体。这种结构允许 AI Agent 维持高保真的上下文，确保项目、任务和人员等数据互连，并根据严格的模式（Schema）约束进行验证。

通过实现此技能，开发人员可以使他们的 Agent 执行复杂的推理，例如依赖关系跟踪和图遍历。该系统使用类型化词汇表来防止数据损坏，并确保仅在满足预定义要求时才提交变更，使其成为构建可靠、多步骤 Agent 工作流的重要组件。

Ontology 应用场景

• 为人员、组织和项目创建并维护长期 Agent 记忆。
• 跟踪复杂的任务依赖关系并识别项目生命周期中的阻碍因素。
• 将相关的文档、消息和线程链接到特定事件或目标。
• 管理多个 Openclaw Skills 之间的共享状态，实现无缝的跨技能通信。
• 将多步执行计划建模为一系列可验证的图变换。

Ontology 工作原理

1. 实体定义：创建实体（如人员、任务或文档），每个实体分配特定的类型和唯一的 ID。
2. 关系映射：建立实体之间的有向关系（例如，任务“拥有者”是人员），以构建语义网络。
3. 模式验证：在 YAML 模式中定义约束，以强制执行所需的属性、枚举和关系规则（如无环性）。
4. 图变更：使用仅追加的 JSONL 存储来创建、更新或关联实体，同时保留历史记录。
5. 查询与遍历：执行图查询以检索相关对象、查找依赖关系或按状态和属性过滤实体。

Ontology 配置指南

要初始化 Ontology 存储并使用 Openclaw Skills 定义您的第一个模式，请运行以下命令：

# 创建存储目录和图文件
mkdir -p memory/ontology
touch memory/ontology/graph.jsonl

# 为任务和人员初始化基本模式
python3 scripts/ontology.py schema-append --data '{
  "types": {
    "Task": { "required": ["title", "status"] },
    "Person": { "required": ["name"] }
  }
}'

# 创建测试实体
python3 scripts/ontology.py create --type Person --props '{"name":"Alice"}'

Ontology 数据架构与分类体系

Ontology 技能使用图的仅追加 JSONL 格式和模式定义的 YAML 格式来组织数据。这确保了数据完整性和清晰的审计追踪。

组件	描述
实体 (Entity)	包含 id、type、properties (JSON 映射) 和 relations。
关系 (Relation)	定义 from_id、relation_type、to_id 以及附加元数据。
模式 (Schema)	位于 memory/ontology/schema.yaml，定义类型、必填字段和枚举。
存储 (Storage)	主要数据持久化在 memory/ontology/graph.jsonl 中，便于解析和迁移。

name: ontology
description: Typed knowledge graph for structured agent memory and composable skills. Use when creating/querying entities (Person, Project, Task, Event, Document), linking related objects, enforcing constraints, planning multi-step actions as graph transformations, or when skills need to share state. Trigger on "remember", "what do I know about", "link X to Y", "show dependencies", entity CRUD, or cross-skill data access.

Ontology

A typed vocabulary + constraint system for representing knowledge as a verifiable graph.

Core Concept

Everything is an entity with a type, properties, and relations to other entities. Every mutation is validated against type constraints before committing.

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

When to Use

Core Types

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

Storage

Default: 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"}

Query via scripts or direct file ops. For complex graphs, migrate to SQLite.

Append-Only Rule

When working with existing ontology data or schema, append/merge changes instead of overwriting files. This preserves history and avoids clobbering prior definitions.

Workflows

Create Entity

python3 scripts/ontology.py create --type Person --props '{"name":"Alice","email":"[email protected]"}'

Query

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

Link Entities

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

Validate

python3 scripts/ontology.py validate  # Check all constraints

Constraints

Define in 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]  # 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

Skill Contract

Skills that use ontology should declare:

# 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"

Planning as Graph Transformation

Model multi-step plans as a sequence of graph operations:

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

Each step is validated before execution. Rollback on constraint violation.

Integration Patterns

With Causal Inference

Log ontology mutations as causal actions:

# When creating/updating entities, also log to causal action log
action = {
    "action": "create_entity",
    "domain": "ontology", 
    "context": {"type": "Task", "project": "proj_001"},
    "outcome": "created"
}

Cross-Skill Communication

# 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
    })

Quick Start

# 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

• references/schema.md — Full type definitions and constraint patterns
• references/queries.md — Query language and traversal examples

Instruction Scope

Runtime instructions operate on local files (memory/ontology/graph.jsonl and memory/ontology/schema.yaml) and provide CLI usage for create/query/relate/validate; this is within scope. The skill reads/writes workspace files and will create the memory/ontology directory when used. Validation includes property/enum/forbidden checks, relation type/cardinality validation, acyclicity for relations marked acyclic: true, and Event end >= start checks; other higher-level constraints may still be documentation-only unless implemented in code.