# Phase 19：知识图谱 + 双通道检索

## 背景与目标

### 问题空间

agcore v0.3.0 已交付 Phase 0-18，记忆系统具备 `KnowledgeStore`（页面级内容检索）和 `VectorStore`（向量语义检索），但缺少实体-关系维度的关联检索能力。用户搜索"X 与什么相关"时，现有系统无法返回实体间的拓扑关系。

`docs/note-knowledge-graph-design.md` 已记录完整的知识图谱设计，Phase 19 将其落地为可编译、可测试的模块。

### 目标

- 新增 `memory/graph.rs`，实现 `KnowledgeGraph` trait + `InMemoryGraph` 内存实现
- 扩展 `MemoryRetriever` 为双通道：KnowledgeStore（内容）+ KnowledgeGraph（实体关系）
- 通过 `RetrievalStrategy` 枚举控制通道选择（Hybrid / KnowledgeOnly / GraphOnly）
- 统一 `RetrievalResult.items` 为 `Vec<RetrievalItem>`，enum 变体区分类别
- 标签管理 API 预留（无自动提取流程，Agent 层显式写入）
- Phase 19 仅提供底层 CRUD 接口，实体/关系的写入由 Agent 层（如 LLM 提取）在后续 Phase 中接入。当前无自动填充流程，需 Agent 显式调用 `add_entity`/`add_relation`。

### 与现有模块的定位关系

```
KnowledgeStore:  页面级内容（"什么是 X"）    ← Phase 6 已有
VectorStore:     向量语义（相似度检索）       ← Phase 15 已有
KnowledgeGraph:  实体级关系（"X 与什么相关"） ← Phase 19 新增
MemoryRetriever: 统一检索入口               ← Phase 19 扩展为双通道
```

### 依赖与优先级

- **依赖**：Phase 6（KnowledgeStore）[高]、Phase 15（VectorStore 模式参考）[低]
- **优先级**：P0（v0.3.0 最后一个 Phase）
- **预估规模**：约 600 行核心 + 200 行测试

---

## 需求分析

### 功能需求

| ID | 需求 | 优先级 |
|----|------|--------|
| F1 | `GraphEntity` / `GraphRelation` / `RelationDirection` 类型定义 | P0 |
| F2 | `KnowledgeGraph` trait（10 个 async 方法） | P0 |
| F3 | `InMemoryGraph` 实现（HashMap + Vec + tag_index） | P0 |
| F4 | BFS 图遍历（防环、权重衰减、方向过滤） | P0 |
| F5 | `RetrievalItem` / `RetrievalStrategy` / `RetrievalResult` 扩展 | P0 |
| F6 | `MemoryRetriever` 双通道（`tokio::join!` 并行） | P0 |
| F7 | 标签管理（set_entity_tags / find_tags / entity_count_by_tag） | P1（预留） |

### 非功能需求

| ID | 需求 | 说明 |
|----|------|------|
| NF1 | 零新依赖 | 纯 std + tokio + 已有 crate |
| NF2 | 异步安全 | `InMemoryGraph` 内部 Mutex 保护，trait 方法 async |
| NF3 | 类型安全 | 不新增 `MemoryError` 变体，复用现有 5 个 |
| NF4 | 向后兼容 | `MemoryRetriever::new()` 签名不变，可选链式注入 graph |
| NF5 | Breaking change 受控 | `RetrievalResult.items` 类型变化，需在 CHANGELOG 标注 |

---

## 方案设计

### 3.1 数据模型

#### GraphEntity

```rust
/// 图谱实体 —— 表示一个可被关联检索的节点。
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GraphEntity {
    /// 唯一标识（如 "person:rust-dev-01"）。
    pub id: String,
    /// 实体名称（用于展示和关键词匹配）。
    pub name: String,
    /// 实体类型（"person" | "concept" | "project" | ...）。
    pub entity_type: String,
    /// 一句话描述。
    pub description: String,
    /// 检索标签（全小写，原子词，由 Agent 层显式写入）。
    pub tags: Vec<String>,
    /// 任意附加属性（与 PersistentVectorStore.metadata 保持一致）。
    pub properties: HashMap<String, String>,
}
```

#### GraphRelation

```rust
/// 图谱关系 —— 连接两个实体的有向边。
///
/// 无 `id` 字段，用 `(source_id, target_id, relation_type)` 三元组唯一标识。
/// 提供 `composite_key()` 作为派生 id，满足未来独立 id 需求。
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GraphRelation {
    /// 源实体 ID。
    pub source_id: String,
    /// 目标实体 ID。
    pub target_id: String,
    /// 关系类型（"works_on" | "part_of" | "related_to" | ...）。
    pub relation_type: String,
    /// 关系强度 [0.0, 1.0]，用于 BFS 评分衰减。
    pub weight: f32,
}

impl GraphRelation {
    /// 复合键：`source_id:target_id:relation_type`，用于去重和查找。
    pub fn composite_key(&self) -> String {
        format!("{}:{}:{}", self.source_id, self.target_id, self.relation_type)
    }
}
```

#### RelationDirection

```rust
/// 关系遍历方向。
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum RelationDirection {
    /// 仅出边：source_id → target_id（默认）。
    Outgoing,
    /// 仅入边：target_id → source_id。
    Incoming,
    /// 双向遍历。
    Both,
}

impl Default for RelationDirection {
    fn default() -> Self {
        Self::Outgoing
    }
}
```

#### ScoredEntity

```rust
/// 带评分的实体 + 路径信息。
#[derive(Debug, Clone)]
pub struct ScoredEntity {
    pub entity: GraphEntity,
    /// 基于图距离的评分 [0.0, 1.0]，沿路径权重乘积衰减。
    pub score: f32,
    /// 从查询实体到当前实体的 ID 路径（用于可解释性）。
    pub path: Vec<String>,
}
```

#### TagConstraints

```rust
/// 标签约束配置。
#[derive(Debug, Clone)]
pub struct TagConstraints {
    /// 每个实体最多标签数（默认 8）。
    pub max_tags_per_entity: usize,
}

impl Default for TagConstraints {
    fn default() -> Self {
        Self {
            max_tags_per_entity: 8,
        }
    }
}
```

### 3.2 KnowledgeGraph trait

```rust
/// 知识图谱抽象 —— 实体-关系存储与图遍历检索。
///
/// 所有方法 `async + Send + Sync`，支持跨 `.await` 调用。
/// 复用 `MemoryError`，不新增变体。
#[async_trait]
pub trait KnowledgeGraph: Send + Sync {
    // ── 实体管理 ──

    /// 添加或更新实体（upsert 语义）。
    async fn add_entity(&self, entity: GraphEntity) -> Result<(), MemoryError>;

    /// 按 ID 获取实体，不存在返回 `Ok(None)`。
    async fn get_entity(&self, id: &str) -> Result<Option<GraphEntity>, MemoryError>;

    /// 删除实体及其所有关联关系。
    async fn remove_entity(&self, id: &str) -> Result<(), MemoryError>;

    // ── 关系管理 ──

    /// 添加关系（若复合键已存在则覆盖 weight）。
    async fn add_relation(&self, relation: GraphRelation) -> Result<(), MemoryError>;

    /// 按复合键删除关系。
    async fn remove_relation(
        &self,
        source_id: &str,
        target_id: &str,
        relation_type: &str,
    ) -> Result<(), MemoryError>;

    /// 从指定实体出发，BFS 遍历 depth 层，返回关联实体（带评分）。
    ///
    /// - `direction`：遍历方向（Outgoing / Incoming / Both）
    /// - `relation_types`：可选过滤，仅遍历指定关系类型
    async fn get_related(
        &self,
        entity_id: &str,
        depth: usize,
        direction: RelationDirection,
        relation_types: Option<&[&str]>,
    ) -> Result<Vec<ScoredEntity>, MemoryError>;

    // ── 检索 ──

    /// 按关键词子串匹配实体（不区分大小写），与 KnowledgeStore.search 一致。
    async fn find_by_keywords(&self, keywords: &[String]) -> Result<Vec<GraphEntity>, MemoryError>;

    // ── 标签管理（预留接口，Agent 层显式写入） ──

    /// 按前缀查找已有标签（用于标签复用）。
    async fn find_tags(&self, prefix: &str) -> Result<Vec<String>, MemoryError>;

    /// 设置实体标签（替换式，保留前 max_tags_per_entity 个）。
    /// 返回实际设置的标签数。
    async fn set_entity_tags(
        &self,
        entity_id: &str,
        tags: Vec<String>,
    ) -> Result<usize, MemoryError>;

    /// 按标签统计实体数量。
    async fn entity_count_by_tag(&self, tag: &str) -> Result<usize, MemoryError>;

    /// 获取标签约束配置。
    fn tag_constraints(&self) -> TagConstraints;
}
```

### 3.3 InMemoryGraph 实现

#### 内部结构

```rust
/// 内存知识图谱实现 —— 纯内存，无持久化。
///
/// 生命周期跟随实例；持久化路径参考 InMemoryVectorStore → PersistentVectorStore 演进模式。
pub struct InMemoryGraph {
    /// 内部状态（单一锁结构，避免嵌套锁死锁）
    inner: Mutex<GraphInner>,
    /// 标签约束
    constraints: TagConstraints,
}

struct GraphInner {
    /// id → entity
    entities: HashMap<String, GraphEntity>,
    /// 所有关系（线性扫描，实测 5000 条 ≈ 1-50µs，无需邻接表索引）
    relations: Vec<GraphRelation>,
    /// tag → entity_ids（反向索引，用于 find_tags / entity_count_by_tag）
    tag_index: HashMap<String, HashSet<String>>,
}
```

#### BFS 遍历算法

```rust
async fn get_related(
    &self,
    entity_id: &str,
    depth: usize,
    direction: RelationDirection,
    relation_types: Option<&[&str]>,
) -> Result<Vec<ScoredEntity>, MemoryError> {
    // 1. 验证起点存在
    let inner = self.inner.lock().unwrap();
    if !inner.entities.contains_key(entity_id) {
        return Err(MemoryError::NotFound(entity_id.to_string()));
    }

    // 2. BFS 初始化
    let mut visited: HashSet<String> = HashSet::new();
    let mut result: Vec<ScoredEntity> = Vec::new();
    // 队列：(entity_id, score, path)
    let mut queue: VecDeque<(String, f32, Vec<String>)> = VecDeque::new();

    queue.push_back((entity_id.to_string(), 1.0, vec![entity_id.to_string()]));
    visited.insert(entity_id.to_string());

    // 3. BFS 逐层遍历
    for _ in 0..depth {
        let mut next_queue: VecDeque<(String, f32, Vec<String>)> = VecDeque::new();

        while let Some((current_id, score, path)) = queue.pop_front() {
            // 筛选与 current_id 相关的关系
            for rel in inner.relations.iter() {
                // 方向过滤
                let (match_source, match_target) = match direction {
                    RelationDirection::Outgoing => (&rel.source_id, &rel.target_id),
                    RelationDirection::Incoming => (&rel.target_id, &rel.source_id),
                    RelationDirection::Both => {
                        if rel.source_id == current_id {
                            (&rel.source_id, &rel.target_id)
                        } else if rel.target_id == current_id {
                            (&rel.target_id, &rel.source_id)
                        } else {
                            continue;
                        }
                    }
                };

                if *match_source != current_id {
                    continue;
                }

                // 关系类型过滤
                if let Some(types) = relation_types {
                    if !types.contains(&rel.relation_type.as_str()) {
                        continue;
                    }
                }

                let neighbor_id = match_target.clone();
                if visited.contains(&neighbor_id) {
                    continue;
                }
                visited.insert(neighbor_id.clone());

                // 权重乘积衰减
                let new_score = score * rel.weight;
                let mut new_path = path.clone();
                new_path.push(neighbor_id.clone());

                result.push(ScoredEntity {
                    entity: inner.entities.get(&neighbor_id).cloned()
                        .ok_or_else(|| MemoryError::NotFound(neighbor_id.clone()))?,
                    score: new_score,
                    path: new_path.clone(),
                });

                next_queue.push_back((neighbor_id, new_score, new_path));
            }
        }

        queue = next_queue;
    }

    // 4. 按分数降序排列
    result.sort_by(|a, b| b.score.partial_cmp(&a.score).unwrap_or(std::cmp::Ordering::Equal));
    Ok(result)
}
```

`depth=0` 时仅验证起点实体存在，返回空关联列表（不遍历任何边）。

**BFS 关键设计点**：

| 特性 | 处理方式 |
|------|----------|
| 环路 | `visited: HashSet<String>` 已访问集合防环 |
| 评分衰减 | 沿路径 `score *= rel.weight`，权重乘积 |
| 多路径 | BFS 天然先到先得，同一实体只保留首次到达路径 |
| 关系类型过滤 | `relation_types: Option<&[&str]>`，`None` 表示不过滤 |
| 方向过滤 | `RelationDirection` 枚举，`Both` 时双向检查 |

> 以上性能数据为基于算法复杂度的估算值（O(R) 线性扫描，R=关系数），实际性能需通过基准测试验证。建议在实现后添加 `#[bench]` 或 criterion 基准测试。

### 3.4 检索扩展

#### RetrievalStrategy

```rust
/// 检索策略 —— 控制双通道分流。
#[derive(Debug, Clone, Default)]
pub enum RetrievalStrategy {
    /// 并行 KnowledgeStore + KnowledgeGraph，合并排序（默认）。
    #[default]
    Hybrid,
    /// 仅 KnowledgeStore。
    KnowledgeOnly,
    /// 仅 KnowledgeGraph。
    GraphOnly,
}
```

#### RetrievalItem

```rust
/// 统一检索条目 —— enum 变体区分类别，两通道分数均在 [0,1] 区间。
#[derive(Debug, Clone)]
pub enum RetrievalItem {
    /// 知识页面（来自 KnowledgeStore）。
    KnowledgePage {
        page: KnowledgePage,
        /// TextOverlap 评分 [0.0, 1.0]。
        score: f32,
    },
    /// 图谱实体（来自 KnowledgeGraph）。
    GraphEntity {
        entity: crate::memory::graph::GraphEntity,
        /// 图距离评分 [0.0, 1.0]。
        score: f32,
        /// 从查询实体到当前实体的 ID 路径。
        path: Vec<String>,
    },
}

impl RetrievalItem {
    /// 统一分数（用于合并排序）。
    pub fn score(&self) -> f32 {
        match self {
            Self::KnowledgePage { score, .. } => *score,
            Self::GraphEntity { score, .. } => *score,
        }
    }
}
```

> **注意**：两个通道的分数维度不同（TextOverlap vs 图距离），合并排序仅用于统一返回，不代表跨通道可比性。

#### 向后兼容导出（ScoredItem）

```rust
// ── 向后兼容导出 ──

/// 旧版带评分的知识页面检索结果（已废弃）。
///
/// 请迁移到 `RetrievalItem::KnowledgePage { page, score }`。
#[deprecated(since = "0.3.0", note = "使用 RetrievalItem::KnowledgePage 代替")]
#[derive(Debug, Clone)]
pub struct ScoredItem {
    pub page: KnowledgePage,
    pub score: f32,
}

// 在 memory.rs 模块根的重导出中保留：
// #[allow(deprecated)]
// pub use retriever::ScoredItem;
```

#### RetrievalResult 更新

```rust
/// 检索结果。
#[derive(Debug, Clone)]
pub struct RetrievalResult {
    /// 统一条目列表，按分数降序排列。
    pub items: Vec<RetrievalItem>,
    pub query: String,
    /// 本次检索实际执行的策略（可能因 graph 未注入而退化），而非用户通过 `with_strategy()` 配置的值。
    pub strategy: RetrievalStrategy,
}
```

#### MemoryRetriever 扩展

```rust
pub struct MemoryRetriever {
    knowledge_store: KnowledgeStore,
    /// 可选知识图谱（None 时退化为单通道）。
    knowledge_graph: Option<Arc<dyn KnowledgeGraph>>,
    /// 检索策略（默认 Hybrid）。
    strategy: RetrievalStrategy,
    config: RetrieverConfig,
    stop_words: HashSet<String>,
}

impl MemoryRetriever {
    /// 创建新的 MemoryRetriever（保持向后兼容）。
    pub fn new(knowledge_store: KnowledgeStore, config: RetrieverConfig) -> Self {
        Self {
            knowledge_store,
            knowledge_graph: None,
            strategy: RetrievalStrategy::default(),
            config,
            stop_words: default_stop_words(),
        }
    }

    /// 注入知识图谱，启用双通道检索。
    pub fn with_knowledge_graph(mut self, graph: Arc<dyn KnowledgeGraph>) -> Self {
        self.knowledge_graph = Some(graph);
        self
    }

    /// 设置检索策略。
    pub fn with_strategy(mut self, strategy: RetrievalStrategy) -> Self {
        self.strategy = strategy;
        self
    }

    /// 检索相关记忆（双通道）。
    pub async fn retrieve(&self, query: &str) -> Result<RetrievalResult, MemoryError> {
        if query.is_empty() {
            return Ok(RetrievalResult {
                items: Vec::new(),
                query: query.to_string(),
                strategy: self.strategy.clone(),
            });
        }

        let keywords = extract_keywords(query, &self.stop_words);
        let has_graph = self.knowledge_graph.is_some();

        // 按策略分流
        match (&self.strategy, has_graph) {
            // 仅知识页面
            (RetrievalStrategy::KnowledgeOnly, _) | (_, false) => {
                let items = self.search_knowledge_store(query, &keywords).await?;
                Ok(RetrievalResult {
                    items,
                    query: query.to_string(),
                    strategy: RetrievalStrategy::KnowledgeOnly,
                })
            }
            // 仅图谱
            (RetrievalStrategy::GraphOnly, true) => {
                let graph = self.knowledge_graph.as_ref().unwrap();
                let items = self.search_graph(query, &keywords, graph).await?;
                Ok(RetrievalResult {
                    items,
                    query: query.to_string(),
                    strategy: self.strategy.clone(),
                })
            }
            // 混合：并行执行，合并排序
            (RetrievalStrategy::Hybrid, true) => {
                let graph = self.knowledge_graph.as_ref().unwrap();
                let (kp_items, g_items) = tokio::join!(
                    self.search_knowledge_store(query, &keywords),
                    self.search_graph(query, &keywords, graph),
                );

                let mut items = kp_items?;
                items.extend(g_items?);
                items.sort_by(|a, b| {
                    b.score().partial_cmp(&a.score())
                        .unwrap_or(std::cmp::Ordering::Equal)
                });
                items.truncate(self.config.max_results);

                Ok(RetrievalResult {
                    items,
                    query: query.to_string(),
                    strategy: self.strategy.clone(),
                })
            }
        }
    }
}
```

### 3.5 标签管理

#### 标签索引维护

`tag_index: HashMap<String, HashSet<String>>` 维护 tag → entity_ids 反向映射：

- **`set_entity_tags`**：先清除旧标签的反向引用，再写入新标签。超出 `max_tags_per_entity` 时截断。
- **`find_tags`**：遍历 `tag_index.keys()`，按前缀过滤。
- **`entity_count_by_tag`**：直接返回 `tag_index.get(tag).map_or(0, |s| s.len())`。

#### 实现要点

```rust
async fn set_entity_tags(
    &self,
    entity_id: &str,
    tags: Vec<String>,
) -> Result<usize, MemoryError> {
    let mut inner = self.inner.lock().unwrap();
    let entity = inner.entities.get_mut(entity_id)
        .ok_or_else(|| MemoryError::NotFound(entity_id.to_string()))?;

    // 清除旧标签的反向引用
    for old_tag in &entity.tags {
        if let Some(ids) = inner.tag_index.get_mut(old_tag) {
            ids.remove(entity_id);
            if ids.is_empty() {
                inner.tag_index.remove(old_tag);
            }
        }
    }

    // 截断到 max_tags_per_entity
    let max = self.constraints.max_tags_per_entity;
    let new_tags: Vec<String> = tags.into_iter().take(max).collect();

    // 写入新标签的反向引用
    for tag in &new_tags {
        inner.tag_index.entry(tag.clone())
            .or_default()
            .insert(entity_id.to_string());
    }

    entity.tags = new_tags.clone();
    Ok(new_tags.len())
}
```

#### 标签复用流程（文档说明）

```
LLM 提取候选标签 → 对每个候选:
  graph.find_tags(candidate.lowercase())
    ├─ 命中已有标签 → 复用
    └─ 无匹配 → 注册新标签
```

> **标注**：当前无自动提取流程，需 Agent 层显式调用 `set_entity_tags`。

---

## 实现计划

| Step | 内容 | 文件范围 | 验证标准 | 预估行数 |
|------|------|----------|----------|----------|
| 1 | `graph.rs` 核心类型：GraphEntity / GraphRelation / RelationDirection / ScoredEntity / TagConstraints | `src/memory/graph.rs` | `cargo check` 编译通过 | ~80 |
| 2 | `KnowledgeGraph` trait 定义（10 个 async 方法） | `src/memory/graph.rs` | trait 编译通过，无未实现方法 | ~90 |
| 3 | `InMemoryGraph` 实现 + BFS 遍历 | `src/memory/graph.rs` | 单元测试：添加实体/关系、BFS 遍历、方向过滤、类型过滤 | ~250 |
| 4 | 标签管理实现（set_entity_tags / find_tags / entity_count_by_tag） | `src/memory/graph.rs` | 单元测试：标签增删查、截断、反向索引维护 | ~80 |
| 5 | `retriever.rs` 扩展：RetrievalItem / RetrievalStrategy / MemoryRetriever 改造 | `src/memory/retriever.rs` | `cargo check` + 双通道检索测试 | ~180 |
| 6 | `memory.rs` 模块根更新 + 重导出 | `src/memory.rs` | `cargo check`，pub use 无编译错误 | ~10 |
| 7 | 内联测试 | `src/memory/graph.rs` + `src/memory/retriever.rs` | `cargo test --all-targets` 全绿 | ~150 |

**总预估**：约 840 行（核心 640 + 测试 200）

---

## 风险评估

| 风险 | 影响 | 缓解措施 |
|------|------|----------|
| 标签 API 无消费者 | 低 — 预留接口，不影响核心功能 | 文档标注"Agent 层显式写入"，后续 Phase 接入 |
| 评分不可比 | 中 — TextOverlap vs 图距离维度不同 | `RetrievalItem` enum 变体分离，合并排序仅统一返回，文档注明维度差异 |
| BFS 性能 | 低 — 5000 关系遍历 ≈ 1-50µs | 不引入邻接表索引，等实测超过 1ms 再优化 |
| Breaking change | 中 — `RetrievalResult.items` 类型变化 | CHANGELOG 标注，`ScoredItem` 保留为 `pub` 兼容导出（deprecate） |
| Mutex 竞争 | 低 — InMemoryGraph 单实例场景 | 读多写少， Mutex 性能足够；后续可升级 RwLock |

---

## 验收标准

| 检查项 | 标准 | 验证命令 |
|--------|------|----------|
| 编译 | 0 error | `cargo check --all-targets` |
| 测试 | 全绿，测试数从 ~391 增至 ~410+ | `cargo test --all-targets` |
| Clippy | 0 warning | `cargo clippy --all-targets -- -D warnings` |
| 文档 | 0 warning | `cargo doc --no-deps` |
| BFS 覆盖 | 所有边界条件：空图、单实体、环路、深度 0、方向过滤、类型过滤 | 内联测试 |
| 双通道 | Hybrid / KnowledgeOnly / GraphOnly 三种策略功能正确 | 内联测试 |
| 向后兼容 | `MemoryRetriever::new()` 签名不变，现有调用无需修改 | `cargo check` 无 breaking error |