前言¶

写智能体时常见的问题是状态散落在各处：对话里提过的人名、项目名写进了提示词，任务之间的依赖靠上下文回忆，换一个技能就重新来一遍。结果要么重复造数据，要么互相覆盖。ontology 这个技能的思路是把知识显式建模成一张带类型的图：所有写入都先过类型约束，再用脚本读写，多个技能共享同一份存储。

这是什么¶

ontology 是 oswalpalash 发布在 ClawHub 上的一个 ai-agent 分类技能，坐标 @clawhub_oswalpalash/ontology，当前版本 1.0.4，许可证 MIT-0，标签 requires_api_key=false，也就是不依赖外部 API Key。它的定位是「类型化词汇表 + 约束系统」，把知识表示成可校验的图。官方提供 SkillHub 页面（https://www.skillhub.cn/skills/clawhub_oswalpalash/ontology）与上游仓库（https://clawhub.ai/oswalpalash/ontology）。

SkillHub 页面抓取到的评分 100000，下载 408655，安装 29080；ClawHub 上游页另有 Bookmark 660 的记录。两个来源统计口径不同，具体数值以各自页面为准。

核心功能¶

核心概念：实体、关系、约束¶

官方把数据模型压成两个结构：实体和关系。实体有 id、type、properties、relations、created、updated；关系有 from_id、relation_type、to_id、properties。关键约定是：每次变更在提交之前都会按类型约束校验一次。

内置类型¶

官方 SKILL.md 给出了 12 组内置类型，覆盖常见的记忆对象：

• 人与组织：Person、Organization
• 工作项：Project、Task、Goal
• 时间与地点：Event、Location
• 信息载体：Document、Message、Thread、Note
• 资源：Account、Device、Credential
• 元信息：Action、Policy

Task 带有 blockers[]，Project 有 status，Credential 只保存 secret_ref 而不直接存密钥——这是官方明确写出的取向。

存储¶

默认存储在工作区的 memory/ontology/graph.jsonl，一行一个操作。schema 放在 memory/ontology/schema.yaml。

{"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 规则¶

处理已有 ontology 数据或 schema 时，官方要求做追加和合并，不要整文件覆盖。这样能保留历史，也不会踩掉之前的定义。

工作流¶

官方给出四类操作，对应四个 CLI 子命令：建实体、查实体、建关系、校验约束。

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

把规划建模成图变换¶

多步计划可以写成一串图操作，每一步执行前先校验，违反约束则回滚。官方示例是「安排一次团队会议并创建后续任务」：先建 Event，把它关联到 Project，再建两个 Task，第二个任务的 blockers 指向第一个。

技能之间的共享契约¶

使用 ontology 的技能应当声明自己读哪些类型、写哪些类型、前置条件和后置条件。官方示例写在 SKILL.md 的 frontmatter 或头部：

ontology:
  reads: [Task, Project, Person]
  writes: [Task, Action]
  preconditions:
    - "Task.assignee must exist"
  postconditions:
    - "Created Task has status=open"

这样跨技能调用时，读写边界是显式可见的，而不是靠约定。

安装与启用¶

在 ClawHub / OpenClaw 环境里，官方给出的安装命令是：

openclaw skills install @oswalpalash/ontology

页面同时提供 CLI（npx skills）与 Prompt 两种使用方式。安装后首次使用时，技能会在工作区创建 memory/ontology 目录。以下路径与命令均相对技能自身的 scripts/ontology.py，需在技能目录内执行；未在官方资料中出现的 Cursor、Codex CLI、Claude Code 差异说明不在此列出。

典型用法¶

先初始化存储与 schema，再开始读写。

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

跨技能协作的官方示例：邮件技能先写一个 Commitment，任务技能再把它读出来转成 Task。

# 邮件技能创建承诺
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
    })

适用场景与注意¶

适合这几类情况：需要在会话之间记住人物、项目、任务、事件、文档；需要把对象关联起来并查询依赖；需要在写入前挡住不合规的数据；多个技能需要共享状态。触发方式按官方说明：用户说「记住」「我知道关于什么」「把 X 链接到 Y」「显示依赖」，或涉及实体增删改查与跨技能数据访问。

约束是这套方案的主要价值，也是主要限制。官方在 Instruction Scope 里写明：校验包含属性检查、枚举检查、禁用属性检查、关系类型与基数校验、acyclic: true 关系的环检测、Event 的 end >= start 检查；除此之外的更高层约束可能仍然只是文档层面的约定，除非在代码里实现过。也就是说，schema.yaml 里写的东西不等于运行时一定拦住，关键规则需要自己确认对应实现。

另外两点：凭据只存引用，不要直接把密钥写进属性；图谱规模上去之后 .jsonl 需要迁移到 SQLite。

结尾¶

ontology 解决的是一个具体问题：让智能体的记忆有类型、有约束、可共享。它不追求通用数据库能力，只提供建实体、查实体、建关系、校验四类操作加一套 schema 约定，代价是要自己维护 schema 与迁移。如果现有方案靠提示词和文件堆状态已经出现覆盖或查不清的情况，可以从 openclaw skills install @oswalpalash/ontology 开始试。官方地址：https://api.skillhub.cn/user_87f6522b/ontology