JARVIS/development-doc/plan/rag-update/checklist.md

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 依赖

  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 并行推进。