# Agent Memory V9.2.0 — 版本规划

> 基于 V9.1.0（安全加固·性能优化·冷库修复）的后续版本规划
>
> 基线: V9.1.0（675 测试全通过，21项安全/性能/架构修复完成）

---

## 总览

```
V9.1.0 ──→ V9.2.0 ──→ V9.3.0 ──→ V10.0
安全加固     智能检索     数据入口     云原生平台
冷库修复     语义分段     微信导入     S3+PGVector
性能优化     RAG Chunk   MBTI分析     多语言SDK
            文档精读     长文本优化   商业化
```

---

# Phase 7: V9.2.0 — 智能检索与文档精读

> 目标: 实现语义感知的文本分段和 RAG 式 chunk 检索，赋予系统"精读"能力
> 周期: 3 周
> 优先级: 🔴 P0

## 7.1 功能需求分析

### 7.1.1 核心痛点（来自 V9.1.0 审查）

| 痛点 | 影响 | 优先级 |
|------|------|--------|
| 长文本只能整条存储，无法按章节/段落检索 | 论文/书籍场景不可用 | P0 |
| 机械分段（5000字符切分）丢失语义边界 | 段落被截断，上下文断裂 | P0 |
| 检索时只能看到80字摘要，无法回溯原文 | 细节丢失，无法精确定位 | P0 |
| 冷库向量被删除，恢复后无法语义检索 | 冷数据恢复不完整 | P1 |
| 两套冷存储实现不统一 | 维护成本高，行为不一致 | P1 |

### 7.1.2 功能需求清单

| 编号 | 需求 | 优先级 | 预期效果 |
|------|------|--------|---------|
| F-01 | 语义感知文本分段器 | P0 | 按章节/段落/主题自然边界切分 |
| F-02 | Chunk-level 向量检索 | P0 | 每段独立编码+向量化，精准定位 |
| F-03 | 文档级元数据管理 | P0 | 文档/章节/页码/位置索引 |
| F-04 | 精准回溯原文 | P0 | 检索结果可定位到原文章节 |
| F-05 | 统一冷存储实现 | P1 | 废弃 store.py 冷库，统一用 memory_tier |
| F-06 | 冷库向量保留/重建 | P1 | 迁移时不删向量，或恢复时自动重建 |
| F-07 | 冷库 FTS 索引 | P1 | 冷库也创建 FTS5 虚拟表 |
| F-08 | memory_id 解析器 | P2 | 从 memory_id 反向提取6D维度 |

## 7.2 技术架构规划

### 7.2.1 语义分段器架构

```
原始长文本（论文/书籍/文档）
    │
    ▼
┌──────────────────────────────────────────────────────┐
│  DocumentParser — 文档结构解析                         │
│  ├─ PDF: PyPDF2 提取目录 + 页码                       │
│  ├─ Markdown: 标题层级解析 (H1/H2/H3)                 │
│  ├─ Word: python-docx 段落/标题提取                   │
│  └─ Plain Text: 空行/缩进/编号模式识别                │
└──────────────┬───────────────────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────────────────┐
│  SemanticChunker — 语义分段器                          │
│  ├─ 策略1: 结构边界（标题/章节/段落）优先              │
│  ├─ 策略2: 语义连贯性（相邻段embedding相似度>0.7合并） │
│  ├─ 策略3: 长度约束（500-1500字/chunk，重叠50字）     │
│  └─ 策略4: 主题一致性（同主题段落优先合并）            │
└──────────────┬───────────────────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────────────────┐
│  ChunkIndexer — 分段索引器                             │
│  ├─ 每段独立 memory_id（含文档ID+章节号）             │
│  │  "DOC_{hash}_ch3.2_p45_{uuid}"                     │
│  ├─ 每段独立 768 维向量                               │
│  ├─ 段落间 sequential 关联                            │
│  ├─ 文档级元数据表 document_meta                      │
│  └─ 分段元数据表 chunk_meta                           │
└──────────────┬───────────────────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────────────────┐
│  ChunkRetriever — 分段检索器                           │
│  ├─ 查询 → 向量匹配 → 命中特定 chunk                  │
│  ├─ 沿 sequential 关联展开上下文（前后各1-2段）        │
│  ├─ 返回: 章节标题 + 原文段落 + 页码 + 位置           │
│  └─ 支持跨 chunk 的上下文窗口滑动                     │
└──────────────────────────────────────────────────────┘
```

### 7.2.2 新增数据库表

```sql
-- 文档级元数据
CREATE TABLE document_meta (
    doc_id      TEXT PRIMARY KEY,
    title       TEXT NOT NULL,
    author      TEXT DEFAULT '',
    source_path TEXT NOT NULL,
    source_type TEXT DEFAULT 'text',     -- pdf/md/docx/txt/url
    total_chunks INTEGER DEFAULT 0,
    total_chars  INTEGER DEFAULT 0,
    created_at   INTEGER NOT NULL,
    updated_at   INTEGER NOT NULL
);

-- 分段级元数据
CREATE TABLE chunk_meta (
    chunk_id    TEXT PRIMARY KEY,         -- DOC_{hash}_ch3.2_p45_{uuid}
    doc_id      TEXT NOT NULL,
    chapter     TEXT DEFAULT '',          -- 章节标题
    section     TEXT DEFAULT '',          -- 小节标题
    page_num    INTEGER DEFAULT 0,
    position    INTEGER DEFAULT 0,        -- 段落在文档中的序号
    prev_chunk  TEXT DEFAULT '',          -- 前一段 chunk_id
    next_chunk  TEXT DEFAULT '',          -- 后一段 chunk_id
    char_offset INTEGER DEFAULT 0,       -- 在原文中的字符偏移
    char_length INTEGER DEFAULT 0,       -- 段落字符长度
    FOREIGN KEY (doc_id) REFERENCES document_meta(doc_id)
);
```

### 7.2.3 统一冷存储架构

```
当前（V9.1.0）:
  store.py → memory_cold.db (物理删除，丢关联数据)
  memory_tier.py → memory_archive.db (软删除，JSON序列化)

目标（V9.2.0）:
  统一使用 memory_tier.py 的归档机制:
  ├─ memory_archive.db 为唯一冷库
  ├─ 保留完整关联数据（topics/tools/knowledge/links）
  ├─ 冷库创建 FTS5 索引
  ├─ 迁移时保留向量（标记为 archived）
  ├─ 恢复时自动重建向量（如已删除）
  └─ query()/recall() 自动 fallback 到冷库
```

## 7.3 开发进度安排

| 周次 | 里程碑 | 交付物 | 验收标准 |
|------|--------|--------|---------|
| **W1** | 语义分段器 + 文档元数据 | DocumentParser + SemanticChunker + chunk_meta 表 | 论文分段准确率>90% |
| **W2** | Chunk检索 + 精准回溯 | ChunkIndexer + ChunkRetriever + 回溯API | 检索可定位到章节+页码 |
| **W3** | 统一冷存储 + 集成测试 | 冷库统一 + 端到端测试 + 文档更新 | 675+测试全通过 |

### W1 详细任务

| 天 | 任务 | 产出 |
|----|------|------|
| D1-2 | DocumentParser 实现（PDF/MD/DOCX/TXT） | document_parser.py |
| D3-4 | SemanticChunker 实现（4种策略） | semantic_chunker.py |
| D5 | document_meta + chunk_meta 表 + 迁移 | schema.sql 更新 |

### W2 详细任务

| 天 | 任务 | 产出 |
|----|------|------|
| D1-2 | ChunkIndexer（分段编码+向量化+关联） | chunk_indexer.py |
| D3-4 | ChunkRetriever（分段检索+上下文展开+回溯） | chunk_retriever.py |
| D5 | API 端点 + CLI 命令 | api_v3.py + cli.py 更新 |

### W3 详细任务

| 天 | 任务 | 产出 |
|----|------|------|
| D1-2 | 统一冷存储（废弃 store.py 冷库） | store.py + memory_tier.py 重构 |
| D3 | 冷库 FTS + 向量保留/重建 | 冷库检索增强 |
| D4 | 集成测试 + 回归测试 | test_chunk.py + test_cold_unified.py |
| D5 | 文档更新 + 版本发布 | CHANGELOG + README + API.md |

## 7.4 资源分配方案

| 角色 | 人数 | 职责 |
|------|------|------|
| 核心开发 | 1 | 语义分段器 + Chunk检索器 |
| 存储开发 | 1 | 冷存储统一 + FTS/向量重建 |
| 测试 | 1 | 集成测试 + 回归测试 + 性能基准 |
| 文档 | 0.5 | API文档 + 用户指南更新 |

## 7.5 质量保障策略

| 维度 | 标准 | 方法 |
|------|------|------|
| 功能完整性 | 所有 F-01~F-08 需求实现 | 需求追踪矩阵 |
| 测试覆盖率 | ≥80% | pytest-cov |
| 分段准确率 | ≥90% | 人工标注 100 段对比 |
| 检索召回率 | ≥85% | 标准测试集 P@10 |
| 回归测试 | 675+ 测试全通过 | CI 自动化 |
| 性能基准 | 分段速度 ≥1000字/秒 | benchmark |

## 7.6 风险管理计划

| 风险 | 概率 | 影响 | 缓解措施 |
|------|------|------|---------|
| 语义分段准确率不足 | 中 | 高 | 降级为结构边界分段，保留语义分段为可选 |
| 冷库统一导致数据迁移风险 | 低 | 高 | 提供迁移脚本 + 回滚机制 |
| chunk 向量存储空间激增 | 中 | 中 | 限制最大 chunk 数 + 压缩向量 |
| FTS5 冷库索引创建耗时 | 低 | 低 | 异步创建 + 进度通知 |

---

# Phase 8: V9.3.0 — 数据入口与深度分析

> 目标: 打通外部数据源（微信聊天记录等），实现深度人格分析
> 周期: 3 周
> 优先级: 🟡 P1

## 8.1 功能需求清单

| 编号 | 需求 | 优先级 | 预期效果 |
|------|------|--------|---------|
| F-09 | 微信聊天记录解析器 | P0 | 支持 .db/.txt/.csv 格式导入 |
| F-10 | 说话人识别与区分 | P0 | 自动区分对话双方 |
| F-11 | 双方高频词对比统计 | P1 | 可视化词频差异 |
| F-12 | MBTI/Big5 人格推断 | P1 | 基于对话内容推断人格类型 |
| F-13 | 话题语义聚类 | P1 | LDA/BERTopic 深度话题分析 |
| F-14 | 词云可视化 | P2 | 高频词词云生成 |
| F-15 | 长文本智能分段增强 | P1 | 论文/书籍专用解析器 |
| F-16 | 大文件流式处理 | P2 | 超大文件不全量读入内存 |

## 8.2 技术架构

### 8.2.1 微信聊天记录解析器

```
微信导出文件
    │
    ├─ .db (SQLite) ──→ WeChatDBParser
    │  ├─ 读取 MSG_0.db 等聊天数据库
    │  ├─ 解析联系人 + 消息记录
    │  └─ 按时间排序重建对话流
    │
    ├─ .txt (文本导出) ──→ WeChatTextParser
    │  ├─ 正则匹配: "昵称(时间): 内容"
    │  ├─ 说话人识别: 基于昵称/ID
    │  └─ 时间线重建
    │
    └─ .csv (表格导出) ──→ WeChatCSVParser
       ├─ 列映射: 时间/发送者/内容/类型
       └─ 类型过滤: 文本/图片/语音/视频
               │
               ▼
┌──────────────────────────────────────────────────────┐
│  ChatAnalyzer — 对话分析器                             │
│  ├─ 双方高频词统计 + 对比                              │
│  ├─ 话题语义聚类 (TF-IDF + BERTopic)                  │
│  ├─ MBTI 推断 (规则引擎 + LLM 辅助)                   │
│  ├─ 情感曲线分析 (Plutchik 8维 + 时间线)              │
│  ├─ 关系动态分析 (亲密度/影响力/话题主导)              │
│  └─ 行为模式推断 (活跃时段/回复速度/话题偏好)          │
└──────────────┬───────────────────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────────────────┐
│  注入现有系统                                          │
│  ├─ 解析结果 → remember() 批量写入                    │
│  ├─ 人格画像 → digital_twin.build_unified_profile()   │
│  ├─ 话题分布 → topic 统计 + 可视化                    │
│  └─ MBTI 结果 → persona_profile 表                    │
└──────────────────────────────────────────────────────┘
```

### 8.2.2 MBTI 推断引擎

```
对话内容
    │
    ▼
┌──────────────────────────────────────────────────────┐
│  MBTI 推断 (4个维度)                                   │
│                                                       │
│  E/I (外向/内向):                                     │
│  ├─ 主动发起对话频率                                   │
│  ├─ 表情/语气词使用频率                                │
│  └─ 话题广度 vs 深度                                  │
│                                                       │
│  S/N (感觉/直觉):                                     │
│  ├─ 具体细节描述 vs 抽象概念讨论                       │
│  ├─ 数据引用频率 vs 类比/隐喻使用                      │
│  └─ 过去经验 vs 未来设想                              │
│                                                       │
│  T/F (思考/情感):                                     │
│  ├─ 逻辑论证 vs 情感表达                              │
│  ├─ 决策依据: 事实 vs 价值观                          │
│  └─ 批评/赞美比例                                     │
│                                                       │
│  J/P (判断/感知):                                     │
│  ├─ 计划性表达 vs 随性表达                            │
│  ├─ 截止日期提及频率                                   │
│  └─ 话题切换频率                                      │
│                                                       │
│  → 输出: MBTI类型 + 置信度 + 各维度得分               │
│  → 降级: 无LLM时使用规则引擎(准确率~60%)              │
│  → 增强: 有LLM时使用语义理解(准确率~80%)              │
└──────────────────────────────────────────────────────┘
```

## 8.3 开发进度安排

| 周次 | 里程碑 | 交付物 |
|------|--------|--------|
| **W1** | 微信解析器 + 说话人识别 | chat_parser.py + speaker_identifier.py |
| **W2** | 对话分析器 + MBTI推断 | chat_analyzer.py + mbti_engine.py |
| **W3** | 批量导入 + 可视化 + 测试 | chat_importer.py + test_chat.py |

---

# Phase 9: V10.0 — 云原生平台

> 目标: 云原生存储 + 多语言SDK + 商业化准备
> 周期: 6 周
> 优先级: 🟢 P2

## 9.1 功能需求清单

| 编号 | 需求 | 优先级 |
|------|------|--------|
| F-17 | S3/OSS 对象存储 | P0 |
| F-18 | PGVector 向量数据库 | P0 |
| F-19 | 媒体文件托管（缩略图+压缩+CDN） | P1 |
| F-20 | Go SDK | P2 |
| F-21 | Rust SDK (嵌入式) | P3 |
| F-22 | LangChain/LlamaIndex 集成 | P1 |
| F-23 | Docker + K8s Helm Chart | P1 |
| F-24 | Grafana Dashboard 模板 | P2 |

## 9.2 技术架构

```
┌─────────────────────────────────────────────────────┐
│  API Layer (FastAPI + gRPC)                          │
│  ├─ 水平自动扩展 (K8s HPA)                           │
│  └─ JWT + RBAC + 多租户                              │
├─────────────────────────────────────────────────────┤
│  Worker Layer (异步任务队列)                          │
│  ├─ Embedder Worker (向量编码)                       │
│  ├─ Indexer Worker (FTS/索引更新)                    │
│  └─ Archiver Worker (冷迁移/备份)                    │
├─────────────────────────────────────────────────────┤
│  Storage Layer                                       │
│  ├─ S3/OSS (媒体文件 + 冷记忆归档)                   │
│  ├─ PGVector (向量数据库，替代 sqlite-vec)            │
│  ├─ PostgreSQL (结构化数据，替代 SQLite)              │
│  └─ Redis (缓存 + 会话)                              │
└─────────────────────────────────────────────────────┘
```

---

# 版本里程碑总表

| 版本 | 主题 | 周期 | 核心交付 | 测试目标 | 状态 |
|------|------|------|---------|---------|------|
| **V9.1.0** | 安全加固·冷库修复 | ✅ 已完成 | 21项修复 + 675测试 | 675 passed | ✅ |
| **V9.2.0** | 智能检索·文档精读 | 3周 | 语义分段 + Chunk RAG + 冷库统一 | 750+ tests | 📋 规划中 |
| **V9.3.0** | 数据入口·深度分析 | 3周 | 微信解析 + MBTI + 对话分析 | 800+ tests | 📋 规划中 |
| **V10.0** | 云原生平台 | 6周 | S3 + PGVector + SDK + K8s | 900+ tests | 📋 规划中 |

---

*本文档基于 V9.1.0 代码审查 + 675 项测试的实证分析推导生成。*
*V9.2.0 为下一迭代版本，聚焦智能检索与文档精读能力。*
