Ontology

Ontology 是什么

Ontology 为代理提供一个工作区内的结构化记忆层：把人物、项目、任务、事件、文档等实体，以及它们之间的关系保存为可查询图谱。它采用追加式 JSONL 记录操作，并用 YAML 模式约束类型、属性和关系，比零散笔记更适合需要稳定实体标识和关系追踪的任务。

适用场景与不适用场景

适合个人知识库、项目依赖、联系人关系、事件追踪和代理长期记忆。不适合高并发、多用户数据库，也不替代图数据库的事务、索引和权限体系。敏感凭据只能保存引用，不能把密码或令牌写进图谱。

核心能力与工作机制

脚本支持 create、get、query、list、update、delete、relate、related、validate 与 schema-append。读取时重放 JSONL 操作得到当前状态，删除是逻辑删除。校验覆盖必填属性、枚举、禁用字段、关系类型与基数、无环约束以及事件起止时间等；路径检查限制图谱和模式位于工作区。

实际工作流与产物

先阅读 schema.yaml，选择既有实体类型；创建实体后用稳定 ID 建立关系，查询或 related 追踪邻接对象。每次批量修改后运行 validate，发现模式缺口时用追加方式扩展 schema。备份时同时保存 graph.jsonl 与 schema.yaml，因为两者共同决定可解释性。

安装、依赖与权限

需要 Python 和工作区文件读写权限，默认数据位于 memory/ontology/graph.jsonl。无需云账号。尽管脚本阻止把 graph/schema 路径指向工作区外，业务数据仍是明文文件，应依靠文件系统权限与版本控制策略保护。

限制、风险与使用建议

追加日志会随时间增长，需要备份和可能的压缩策略；多个进程并发写入可能冲突。部分模式约束可能只是文档说明，实际校验器未完全实现，不能把 validate 当作数据库级保证。逻辑删除和关系残留也需要定期检查。

上手建议

从少量高价值类型和关系开始，命名保持稳定；先验证查询需求，再扩展模式。每次写入后查询目标实体并运行 validate。不要把所有文本切成实体，只有需要独立引用、关联或生命周期管理的对象才值得进入图谱。

来源、版本与许可

依据 ClawHub 1.0.4 页面、完整 Skill 与 Python 实现整理，版本元数据声明 MIT-0。平台 API 的自动审核为 clean，但页面仍显示 Review；这只是扫描信号，不代表无风险。

常见问题

1. 数据保存在哪里？

默认在工作区 memory/ontology/graph.jsonl，模式位于 schema.yaml。它们是普通本地文件，不会自动上传云端；迁移或备份时必须一起保存，单独复制图数据可能失去类型解释。

2. 为什么使用追加式 JSONL？

每次创建、更新或删除都追加一条操作，读取时重放得到当前状态，便于审计和恢复历史。但日志会持续增长，也没有数据库事务保证，需要控制并发并规划备份或压缩。

3. 删除实体会物理移除记录吗？

不会，删除以新操作表达当前实体失效，旧记录仍在日志中。若数据具有隐私删除要求，单纯逻辑删除可能不够，应评估安全清除整个历史文件及备份。

4. 可以保存 API 密钥吗？

不可以。模式专门禁止 secret、password、token、key、api_key 等字段；凭据实体只能保存 secret_ref，实际秘密应留在系统密钥链或秘密管理器中。

5. validate 能保证所有约束吗？

不能把它等同数据库约束。实现覆盖属性、枚举、关系类型、基数、无环和事件时间等主要规则，但文档中的其他约束可能尚未编码，关键业务仍需额外测试。

6. 能把数据文件放到工作区外吗？

实现包含路径校验，要求 graph 与 schema 的解析路径保持在工作区根目录内。这降低误写系统位置的风险，但不会阻止有权限的其他程序读取工作区文件。

7. 适合多人同时写入吗？

不理想。普通 JSONL 文件缺少成熟数据库的锁、事务和冲突解决；多个代理并发追加可能产生竞争。多人场景应串行写入，或迁移到具备并发控制的数据库。

8. 如何设计第一版本模式？

先从查询问题倒推，只定义少量稳定实体、必需属性和关系基数；用真实样例创建、关联、查询并验证。不要一开始复制整个业务世界，否则模式更新和历史兼容成本会迅速上升。