# Jarvis RAG 升级计划索引

本目录用于存放 Jarvis RAG 系统的分阶段升级规划文档。

## 文档说明

| 文件 | 说明 |
|------|------|
| `README.md` | 总览、阶段关系、实施顺序 |
| `phase-r-0-current-state.md` | 当前现状、问题、目标架构、VCPToolBox 借鉴 |
| `phase-r-1-token-chunking.md` | Token 感知分块优化 |
| `phase-r-2-multi-index.md` | 多索引架构 |
| `phase-r-3-dynamic-weight.md` | 动态权重增强 |
| `phase-r-4-advanced.md` | 高级特性（可选） |
| `checklist.md` | 执行清单 |

## 推荐阅读顺序

1. 先读 `phase-r-0-current-state.md`
2. 再按顺序阅读 phase r-1 ~ r-4
3. 实施时严格按阶段推进，R.4 为可选
4. 参考 `checklist.md` 进行任务追踪

---

## 总体升级原则

1. **Token 精确控制** - 使用 tiktoken 精确计数
2. **多索引分层** - 按知识类型/重要性分离
3. **动态适配** - 根据查询特性动态调整检索策略
4. **测试优先** - 所有升级都要配套测试
5. **可独立推进** - Phase R 可与 Agent Phase 1-5 并行

---

## 阶段总览图

```
R.0 ──────────────────────────────────────────────────────────────┐
│ 现状与目标                                                           │
│ - 当前架构分析                                                        │
│ - 短板识别                                                           │
│ - VCPToolBox TagMemo V6 借鉴                                         │
└────────────────────────────────────────────────────────────────────┘
         │
         ▼
R.1 ──────────────────────────────────────────────────────────────┐
│ Token 感知分块优化                                                    │
│ - tiktoken 集成                                                     │
│ - 智能断句                                                          │
│ - 重叠分块 (10% overlap)                                            │
│                                                                      │
│ 核心文件: services/chunker.py                                    │
│ 工作量: 3 天                                                        │
└────────────────────────────────────────────────────────────────────┘
         │
         ▼
R.2 ──────────────────────────────────────────────────────────────┐
│ 多索引架构                                                           │
│ - Collection 分离策略                                               │
│ - 懒加载 + LRU TTL                                                 │
│ - 重要性感知检索                                                    │
│                                                                      │
│ 核心文件: services/multi_index.py                                │
│ 依赖: R.1                                                          │
│ 工作量: 4 天                                                       │
└────────────────────────────────────────────────────────────────────┘
         │
         ▼
R.3 ──────────────────────────────────────────────────────────────┐
│ 动态权重增强                                                        │
│ - QueryAnalyzer                                                    │
│ - DynamicReranker                                                 │
│ - CoreTagAwareSearch                                              │
│                                                                      │
│ 核心文件: services/query_analyzer.py,                             │
│          services/dynamic_reranker.py,                           │
│          services/core_tag_search.py                              │
│ 依赖: R.1                                                          │
│ 工作量: 4.5 天                                                    │
└────────────────────────────────────────────────────────────────────┘
         │
         ▼
R.4 ──────────────────────────────────────────────────────────────┐
│ 高级特性 (可选)                                                    │
│ - 语义去重                                                         │
│ - 语义分桶                                                         │
│ - EPA 分析设计                                                      │
│                                                                      │
│ 状态: 可选                                                         │
│ 工作量: 4.5 天                                                   │
└────────────────────────────────────────────────────────────────────┘
```

---

## VCPToolBox TagMemo V6 核心借鉴

| 借鉴点 | 实现位置 | 难度 |
|--------|---------|------|
| Token 感知分块（85%+10% 重叠） | R.1 | 🟢 低 |
| 多索引架构 | R.2 | 🟡 中 |
| 懒加载 + LRU | R.2 | 🟡 中 |
| TagBoost 动态权重 | R.3 | 🟡 中 |
| 核心标签系统（1.33x 加权） | R.3 | 🟡 中 |
| LIF 脉冲扩散 | R.4 | 🔴 高 |

---

## 实施顺序

```
R.0 → R.1 → R.2 → R.3 → (R.4 可选)
  │       │       │       │
  │       │       │       └── 语义去重/分桶/PCA
  │       │       └── 多索引 + 懒加载
  │       └── Token感知分块
  └── 现状与目标
```

**注意：** R.1 是基础，R.2 和 R.3 都依赖 R.1；R.4 可选。

---

## 文件变更追踪

| Phase | 新增文件 | 修改文件 |
|-------|---------|---------|
| R.1 | `services/chunker.py`, `tests/test_chunker.py` | `services/document_service.py` |
| R.2 | `services/multi_index.py`, `tests/test_multi_index.py` | `services/knowledge_service.py`, `models/document.py` |
| R.3 | `services/query_analyzer.py`, `services/dynamic_reranker.py`, `services/core_tag_search.py`, `tests/test_dynamic_reranker.py` | `services/knowledge_service.py`, `models/document.py` |
| R.4 | `services/deduplicator.py`, `services/semantic_bucket.py` (可选) | - |

---

## 与 Agent Phase 1-5 的关系

| Agent Phase | RAG 协作内容 |
|-------------|-------------|
| Phase 1 | Task Schema 追踪 RAG 任务 |
| Phase 2 | RAG 任务可分解给 Librarian Agent |
| Phase 3 | 支持多索引动态选择 |
| Phase 4 | RAG 检索过程可视化 |
| Phase 5 | EPA 分析、语义分桶 |
| **Phase R** | **独立 RAG 升级路径，可与 Phase 1-5 并行推进** |

---

## 注意事项

| 注意事项 | 说明 |
|---------|------|
| R.1 是基础 | R.2 和 R.3 都依赖 R.1 的分块优化 |
| Token 精确计数 | 使用 tiktoken，多版本验证 |
| 索引分离 | 提供统一检索接口，隐藏内部逻辑 |
| 动态权重 | 提供配置项，允许用户调整 |
| EPA 高复杂度 | Phase R.4 可选，暂不实现 |