# Jarvis RAG 升级执行清单

日期：2026-04-03
状态：执行清单
借鉴来源：VCPToolBox TagMemo V6 架构

---

## 使用说明

- 完成前使用 `- [ ]`
- 完成后改成 `- [x]`
- Day R.2 默认依赖 Day R.1 的分块优化完成后再推进
- Day R.3 默认依赖 Day R.1 的分块优化完成后再推进
- Day R.4 为可选特性

---

## Day R.1：Token 感知分块优化（3天）

Day R.1 目标：解决跨块边界信息丢失问题，实现精确的 token 计数和重叠分块。

### Task R.1.1：集成 tiktoken

- [ ] 安装 tiktoken 依赖
  ```bash
  uv add tiktoken
  ```

- [ ] 新增 `backend/app/services/chunker.py`
  实现 `TokenAwareChunker` 类，支持 85% 安全边界

- [ ] 实现 `count_tokens()` 方法

### Task R.1.2：实现智能断句

- [ ] 实现 `find_best_breakpoint()` 函数
  在断点处（标点/空白）智能断开

- [ ] 实现 `_force_split_long_text()` 方法
  处理超长句子强制分割

### Task R.1.3：实现重叠分块

- [ ] 实现 `chunk_with_overlap()` 方法
  10% token 重叠，保证上下文连续性

- [ ] 实现 `_create_overlap()` 方法
  创建重叠部分

### Task R.1.4：集成到 DocumentService

- [ ] 修改 `backend/app/services/document_service.py`
  集成新的 TokenAwareChunker

- [ ] 替换原有的 `_build_chunks()` 方法

### Task R.1.5：补测试

- [ ] 新增 `backend/tests/services/test_chunker.py`

- [ ] 测试 Token 计数准确性

- [ ] 测试智能断句

- [ ] 测试重叠分块

### Day R.1 验收

- [ ] tiktoken 正确集成，token 计数误差 < 1%
- [ ] 超长句子不在词汇中间断开
- [ ] 重叠分块保证上下文连续性
- [ ] 单元测试覆盖率 > 80%
- [ ] 文档上传→分块→检索 集成测试通过

---

## Day R.2：多索引架构（4天）

Day R.2 目标：按知识类型/重要性分层，支持懒加载和 LRU 淘汰。

### Task R.2.1：设计 Collection 分离策略

- [ ] 新增 `backend/app/services/multi_index.py`

- [ ] 定义 `MultiIndexManager` 类

- [ ] 实现 `INDEX_STRATEGIES` 配置
  - default: 通用文档
  - important: 重要文档
  - code: 代码片段
  - meeting: 会议记录

- [ ] 实现 `get_collection()` 方法

### Task R.2.2：实现懒加载 + LRU TTL

- [ ] 实现 `LazyIndexLoader` 类

- [ ] 实现 `get_or_load()` 方法

- [ ] 实现 `sweep()` 方法
  2小时 TTL 淘汰机制

### Task R.2.3：实现重要性感知检索

- [ ] 实现 `retrieve_with_importance()` 方法

- [ ] important 索引加权 1.2x

### Task R.2.4：修改 Document 模型

- [ ] 修改 `backend/app/models/document.py`

- [ ] 增加 `importance` 字段（Float, default=0.5）

### Task R.2.5：集成到 KnowledgeService

- [ ] 修改 `backend/app/services/knowledge_service.py`

- [ ] 集成 MultiIndexManager

- [ ] 集成 LazyIndexLoader

- [ ] 根据 importance 选择索引

### Task R.2.6：补测试

- [ ] 新增 `backend/tests/services/test_multi_index.py`

- [ ] 测试多 Collection 创建

- [ ] 测试懒加载

- [ ] 测试 TTL 淘汰

### Day R.2 验收

- [ ] 多 Collection 创建成功
- [ ] 懒加载索引生效
- [ ] TTL 淘汰机制工作
- [ ] 重要性感知检索加权生效
- [ ] 单元测试覆盖率 > 80%

---

## Day R.3：动态权重增强（4.5天）

Day R.3 目标：根据查询特性动态调整检索策略，支持核心标签加权。

### Task R.3.1：实现查询特性分析

- [ ] 新增 `backend/app/services/query_analyzer.py`

- [ ] 定义 `QueryProfile` 数据类

- [ ] 实现 `QueryAnalyzer` 类

- [ ] 实现查询类型检测
  - 代码相关
  - 表格相关
  - 对话式

- [ ] 实现 `_calc_logic_depth()` 方法

### Task R.3.2：实现动态 Reranker

- [ ] 新增 `backend/app/services/dynamic_reranker.py`

- [ ] 实现 `DynamicReranker` 类

- [ ] 实现 `_get_weights()` 方法
  - 代码查询：关键词权重高
  - 表格查询：标题权重高
  - 对话式：语义权重高

- [ ] 实现 `_calc_beta()` 方法

- [ ] 实现 `rerank()` 方法

### Task R.3.3：实现核心标签系统

- [ ] 新增 `backend/app/services/core_tag_search.py`

- [ ] 实现 `CoreTagAwareSearch` 类

- [ ] 实现 `CORE_BOOST_FACTOR = 1.33`

- [ ] 实现 `search()` 方法

### Task R.3.4：修改 DocumentChunk 模型

- [ ] 修改 `backend/app/models/document.py`

- [ ] 增加 `tags` 字段（JSON, default=list）

- [ ] 增加 `is_core` 字段（Boolean, default=False）

### Task R.3.5：集成到 KnowledgeService

- [ ] 修改 `backend/app/services/knowledge_service.py`

- [ ] 集成 QueryAnalyzer

- [ ] 集成 DynamicReranker

- [ ] 集成 CoreTagAwareSearch

- [ ] 修改 `retrieve()` 方法支持动态权重

### Task R.3.6：补测试

- [ ] 新增 `backend/tests/services/test_dynamic_reranker.py`

- [ ] 测试查询特性分析

- [ ] 测试动态权重调整

- [ ] 测试核心标签加权

### Day R.3 验收

- [ ] 查询特性分析准确（代码/表格/对话式识别）
- [ ] 动态权重根据查询类型调整
- [ ] 核心标签检索加权 1.33x
- [ ] Rerank 集成测试通过

---

## Day R.4：高级特性（可选）（4.5天）

Day R.4 目标：探索更高级的 RAG 增强技术。

### Task R.4.1：语义去重

- [ ] 新增 `backend/app/services/deduplicator.py`

- [ ] 实现 `SemanticDeduplicator` 类

- [ ] 实现 `_cosine_similarity()` 方法

- [ ] 实现 `deduplicate()` 方法

### Task R.4.2：语义分桶（可选）

- [ ] 新增 `backend/app/services/semantic_bucket.py`

- [ ] 实现 `SemanticBucketing` 类

- [ ] 实现 `bucket_by_topic()` 方法

### Task R.4.3：EPA 分析设计（可选探索）

- [ ] 设计 EPA 模块架构

- [ ] 定义 EPA 接口

- [ ] 实现残差金字塔算法（伪代码）

### Day R.4 验收（可选）

- [ ] 语义去重测试通过
- [ ] 语义分桶原型完成（可选）
- [ ] EPA 分析方案设计完成（可选实现）

---

## 总验收清单

### Phase R.1-R.3 必须完成

- [ ] Token 感知分块正常工作
- [ ] 多索引架构正常工作
- [ ] 动态权重增强正常工作
- [ ] 单元测试覆盖率 > 80%
- [ ] 集成测试通过
- [ ] 原有检索功能无回退

### Phase R.4 可选完成

- [ ] 语义去重正常工作
- [ ] 语义分桶正常工作（可选）
- [ ] EPA 设计文档完成（可选）

---

## 总工作量估算

| Phase | 工作量 |
|-------|--------|
| R.1 Token 感知分块 | 3 天 |
| R.2 多索引架构 | 4 天 |
| R.3 动态权重增强 | 4.5 天 |
| R.4 高级特性（可选） | 4.5 天 |
| **R.1-R.3 必须** | **11.5 天** |
| **R.1-R.4 含可选** | **16 天** |

---

## 产出清单

| 产出 | 对应 Phase |
|------|-----------|
| `services/chunker.py` | R.1 |
| `services/multi_index.py` | R.2 |
| `services/query_analyzer.py` | R.3 |
| `services/dynamic_reranker.py` | R.3 |
| `services/core_tag_search.py` | R.3 |
| `services/deduplicator.py` | R.4 |
| `services/semantic_bucket.py` | R.4（可选） |
| `models/document.py` 更新 | R.2, R.3 |
| 单元测试 > 80% | R.1, R.2, R.3 |
| 集成测试通过 | R.1, R.2, R.3 |

---

## 与 Agent Phase 关系

| Agent Phase | RAG 协作内容 |
|-------------|-------------|
| Phase 1 | Task Schema 追踪 RAG 任务 |
| Phase 2 | RAG 任务可分解给 Librarian Agent |
| Phase 3 | 支持多索引动态选择 |
| Phase 4 | RAG 检索过程可视化 |
| Phase 5 | EPA 分析、语义分桶 |

**Phase R 可与 Agent Phase 1-5 并行推进。**