结构化知识图谱

技能文档

---
name: ontology
title: 结构化知识图谱
category: 开发工具
description: 基于类型化知识图谱管理结构化记忆与实体关系，支持实体创建、查询、关联、约束校验与跨技能共享。当用户需要「记住某个信息」「查询已知内容」「关联两个对象」「查看依赖关系」「创建实体或关系」时触发。触发词：知识图谱、结构化记忆、实体管理、关系查询。
---

# 结构化知识图谱

一套带类型约束的词汇表与校验系统，将知识表达为可验证的图结构。

## 核心概念

一切皆为**实体**，拥有**类型**、**属性**和**关系**。每次变更在写入前都会经过类型约束校验。

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

## 技能工作流

### 步骤1：判断操作类型

| 触发场景 | 执行操作 |
|----------|----------|
| "记住……" | 创建/更新实体 |
| "关于 X 我知道什么？" | 查询图谱 |
| "把 X 和 Y 关联" | 创建关系 |
| "列出项目 Z 的所有任务" | 图遍历 |
| "X 被什么阻塞？" | 依赖查询 |
| 规划多步骤工作 | 建模为图变换 |
| 技能间需要共享状态 | 读写图谱对象 |

### 步骤2：执行实体操作

#### 创建实体

```bash
python3 scripts/ontology.py create --type Person --props '{"name":"Alice","email":"alice@example.com"}'
```

#### 查询

```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
```

#### 关联实体

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

#### 校验

```bash
python3 scripts/ontology.py validate  # 检查所有约束
```

## 核心类型

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

# 元信息
Action: { type, target, timestamp, outcome? }
Policy: { scope, rule, enforcement }
```

## 存储

默认路径：`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"}
```

可通过脚本或直接文件操作查询。图谱规模较大时建议迁移至 SQLite。

## 约束定义

在 `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]

relations:
  has_owner:
    from_types: [Project, Task]
    to_types: [Person]
    cardinality: many_to_one
  
  blocks:
    from_types: [Task]
    to_types: [Task]
    acyclic: true
```

## 技能协作约定

使用本图谱的技能应声明读写权限：

```yaml
ontology:
  reads: [Task, Project, Person]
  writes: [Task, Action]
  preconditions:
    - "Task.assignee 必须已存在"
  postconditions:
    - "新建 Task 的 status 为 open"
```

## 规划建模为图变换

将多步骤计划表达为一系列图操作：

```
计划："安排团队会议并创建后续任务"

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

每一步在执行前进行约束校验，违反约束时自动回滚。

## 快速开始

```bash
# 初始化存储
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` — 查询语言与遍历示例

使用说明

# 结构化知识图谱

用类型化知识图谱管理实体、关系与约束，实现跨技能的结构化记忆共享。

## 使用

```bash
# 创建实体
python3 scripts/ontology.py create --type Person --props '{"name":"张三"}'

# 查询实体
python3 scripts/ontology.py query --type Task --where '{"status":"open"}'

# 建立关系
python3 scripts/ontology.py relate --from proj_001 --rel has_task --to task_001

# 查看关联
python3 scripts/ontology.py related --id proj_001 --rel has_task

# 校验约束
python3 scripts/ontology.py validate
```

## 工作原理

所有数据以实体（Entity）和关系（Relation）的形式存储在 `memory/ontology/graph.jsonl` 中。每个实体拥有类型、属性和关系；每次写入前自动校验类型约束（必填字段、枚举值、禁止属性等）。支持通过脚本进行创建、查询、关联、遍历和校验操作。

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。