Ontology

--- name: ontology-2 slug: ontology-2 displayName: "Ontology" version: "1.0.4" summary: "类型化知识图谱,结构化Agent记忆与可组合技能" description: "类型化知识图谱,结构化Agent记忆与可组合技能。Typed knowledge graph for structured agent memory and composable skills。触发关键词: graph, knowledge, typed, ontology, agent, structured。" license: "MIT" tools: - read --- # 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. ```text Entity: { id, type, properties, relations, created, updated } Relation: { from_id, relation_type, to_id, properties } ``` ## When to Use | Trigger | Action | | --- | --- | | "Remember that..." | Create/update entity | | "What do I know about X?" | Query graph | | "Link X to Y" | Create relation | | "Show all tasks for project Z" | Graph traversal | | "What depends on X?" | Dependency query | | Planning multi-step work | Model as graph transformations | | Skill needs shared state | Read/write ontology objects | ## Core Types ```yaml 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 } # Never store secrets directly Action: { type, target, timestamp, outcome? } Policy: { scope, rule, enforcement } ``` ## Storage Default: `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"} ``` 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 ```bash python3 scripts/ontology.py create --type Person --props '{"name":"Alice","email":"alice@example.com"}' ``` ### Query ```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 ``` ### Link Entities ```bash python3 scripts/ontology.py relate --from proj_001 --rel has_task --to task_001 ``` ### Validate ```bash python3 scripts/ontology.py validate # Check all constraints ``` ## Constraints Define in `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 ``` ## Skill Contract Skills that use ontology should declare: ```yaml 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: ```text 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: ```python action = { "action": "create_entity", "domain": "ontology", "context": {"type": "Task", "project": "proj_001"}, "outcome": "created" } ``` ### Cross-Skill Communication ```python 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 }) ``` ## Quick Start ```bash 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 ``` ## 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. ## 依赖说明 ### 运行环境 - **Agent平台**: 支持SKILL.md的任意AI Agent( Code / Cursor / Codex / CLI等) - **操作系统**: Windows / macOS / Linux ### 依赖说明 | 依赖项 | 类型 | 是否必需 | 获取方式 | |:-------|:-----|:---------|:---------| | LLM API | API | 必需 | 由Agent内置LLM提供 | ### API Key 配置 - 本Skill基于Markdown指令,无需额外API Key(除内容中明确标注的外部API) ### 可用性分类 - **分类**: MD+execute(纯Markdown指令,部分功能需要exec命令行执行能力) - **说明**: 基于Markdown的AI Skill,通过自然语言指令驱动Agent执行任务 ## 核心能力 - Typed knowledge graph for structured agent memory and composable skills - 触发关键词: graph, knowledge, typed, ontology, agent, structured ## 适用场景 | 场景 | 输入 | 输出 | |------|------|------| | 基础使用 | 用户请求 | 处理结果 | **不适用于**：需要人工判断的复杂决策场景 ## 示例 ### 示例1：基础用法 ``` # 请参考上方使用说明进行配置和调用 result = "ready" ```bash 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 ``` # 请参考上方使用说明进行配置和调用 result = "ready" ``` ## 错误处理 | 错误场景 | 原因 | 处理方式 | |---------|------|---------| | 配置错误 | 参数缺失或格式错误 | 检查依赖说明中的配置要求 | | 运行时错误 | 运行环境不满足 | 确认运行环境符合依赖说明 | | 网络错误 | 连接超时或不可达 | 检查网络连接后重试，参考国内替代方案 | ## 常见问题 ### Q1: 如何开始使用Ontology？ A: 请先阅读使用流程章节，确认环境满足依赖说明中的要求。 ### Q2: 遇到错误怎么办？ A: 请参考错误处理章节，按照表格中的处理方式操作。 ### Q3: Ontology有什么限制？ A: 请参考已知限制章节了解具体限制。 ## 已知限制 - 需要LLM支持，无LLM环境无法使用 - 复杂场景可能需要人工辅助判断 - 性能取决于底层模型能力

存档时间线

版本索引永久保留；内容副本只保留最近 2 版，更早版本仅留索引与哈希（存档时间线的证据链不会因此断裂）。

下载存档内容副本