# 知信图谱 — AI 辅助提取指南

## 概述

本指南定义 Claude Code 如何从对话/文档中提取结构化知识，以及提取后如何与用户确认、写入知信图谱。

**原则**：AI 辅助提取，人类决策确认。

---

## 触发词

| 用户说 | Claude 行为 |
|--------|------------|
| "把这些整理到知信图谱" | 分析当前对话，提取实体/关系/事实，展示预览 |
| "这段文档录入知信图谱" | 分析给出的文档内容 |
| "把 X 记到知信图谱" | 提取 X 相关的内容 |
| "查知信图谱 X" | 搜索 KG，返回结果 |
| "X 在知信图谱里怎么验证的" | 展示 X 的验证链 |

---

## 提取流程

### Step 1: 分析

Claude 分析对话/文档，识别：

**实体候选**（有明确名称和类型的人/项目/概念/工具等）：
- 去重：已在 KG 中的实体，直接复用 ID
- 新实体：生成 name + type + description

**关系候选**（实体间有意义的连接）：
- 仅连接已确认的实体（新提取的或 KG 中已有的）
- 标注关系类型

**事实候选**（附着于实体的知识原子）：
- 一句话一条事实
- 标注事实类型和来源
- 全部默认 `unverified`

### Step 2: 预览

以结构化格式展示给用户：

```
📦 实体 (N个):
  1. 张三 (person) — 后端开发
  2. 项目A (project) — [已在 KG 中，复用]
  3. FastAPI (tool) — Python Web 框架

🔗 关系 (M条):
  1. 张三 works_on 项目A
  2. 项目A depends_on FastAPI

📝 事实 (K条):
  1. [项目A] 使用 Python 3.12 和 FastAPI — knowledge, 源:张三, unverified
  2. [项目A] 截止日期 2026-06-01 — constraint, 源:张三, unverified
  3. [张三] 有5年后端经验 — knowledge, 源:张三, unverified
```

### Step 3: 确认

等待用户回应：
- "确认" / "OK" / "写入" → 全部写入
- "去掉第N条" → 移除指定条目后写入
- "第N条改成..." → 修改后写入
- "先只记实体" → 仅写入实体

### Step 4: 写入

Claude 调用 kg.py 命令批量写入，完成后输出摘要：

```
✅ 已写入知信图谱：
  - 新增实体 2 个，复用 1 个
  - 新增关系 2 条
  - 新增事实 3 条（全部 unverified，建议后续验证）
  - 未验证: 3 | 自查: 0 | 复核: 0
```

---

## 提取质量标准

### 好的事实陈述

✅ 一句话、可验证、有明确主体：
- "项目A 使用 Python 3.12"
- "张三 负责后端开发"
- "Q3计划 预算为50万"

### 避免的写法

❌ 模糊、无法验证、过于冗长：
- "项目A好像用了Python" （模糊）
- "整个系统的架构设计考虑了可扩展性和高可用性..." （过于冗长，应拆分为多条）
- "大家都觉得这个方案好" （无法验证，缺乏具体主体）

---

## JSON 格式定义

### add-entity
```json
{
  "name": "实体名称",
  "type": "person|project|concept|tool|event|document|org",
  "description": "描述（可选）",
  "tags": ["标签1", "标签2"]
}
```

### add-fact
```json
{
  "entity_name": "所属实体名称",
  "content": "事实陈述，一句话",
  "fact_type": "knowledge|opinion|decision|status|constraint",
  "source_name": "信息来源（可选，需已在 sources 表中）",
  "verification": "unverified|self_checked",
  "fresh_until": "2026-12-31（可选，ISO日期）"
}
```

### add-relation
```json
{
  "from": "实体A名称",
  "to": "实体B名称",
  "relation_type": "works_on|knows|depends_on|contains|created_by|related_to|before|after",
  "source_ref": "关系依据（可选）"
}
```

### add-source
```json
{
  "name": "信息源名称",
  "type": "person|document|observation|external|team_member",
  "credibility_score": 0.7,
  "reliability_notes": "评定依据"
}
```

---

## 常见场景提取示例

### 场景 1：会议讨论

对话：
> 张三："我们决定用 PostgreSQL 替代 MySQL，因为查询性能更好"
> 李四："同意，迁移计划从下周开始"

提取：
```json
// 实体: PostgreSQL(tool), MySQL(tool), 迁移计划(project)
// 事实: [项目] 使用 PostgreSQL 替代 MySQL — decision, 源:张三
// 事实: [迁移计划] 从下周开始 — status, 源:张三
// 标注: [decision事实] 李四 confirm
```

### 场景 2：文档分析

文档内容：
> 系统架构采用微服务模式，包含用户服务、订单服务、支付服务三个核心服务。
> 服务间通过 gRPC 通信，使用 etcd 做服务发现。

提取：
```json
// 实体: 微服务架构(concept), 用户服务(project), 订单服务(project), 支付服务(project), gRPC(tool), etcd(tool)
// 关系: 各服务 depends_on gRPC, 各服务 depends_on etcd
// 事实: [微服务架构] 包含3个核心服务 — knowledge
// 事实: [服务间通信] 使用 gRPC — knowledge
// 事实: [服务发现] 使用 etcd — knowledge
```