docs: 更新文档，区分首次全量与增量更新两种使用场景

- README.md: 拆分为"首次使用"和"增量更新"两个独立章节
- docs/file_guide.md: 新增三种使用场景 (首次建库/追加模板/换模型)
- 补充三个 --incremental 标志的工作逻辑对比表

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

README.md

@@ -2,7 +2,7 @@
 
 基于 RAG 的 JasperReports JRXML 模板 + Markdown 文档智能检索系统，作为构建 JRXML 自定义 Agent 的前置工作。
 
-支持 JRXML 模板和 Markdown 文档的语义分块、向量化、Chroma 持久化存储，以及自然语言查询。
+支持 JRXML 模板和 Markdown 文档的语义分块、向量化、Chroma 持久化存储，以及自然语言查询。**三个核心步骤均支持增量处理**。
 
 ## 项目结构
 
@@ -10,102 +10,126 @@
 rag_jrxml/
 ├── collect_jrxml.py              # JRXML 文件收集
 ├── jrxml_chunker.py              # JRXML 语义分块引擎 (v3.0)
-├── jrxml_banch_chunker.py        # JRXML 批量分块 (单类型)
 ├── md_chunker.py                 # Markdown 语义分块引擎
-├── batch_chunker.py              # 统一批量分块入口 (JRXML + MD)
+├── batch_chunker.py              # 统一批量分块入口 (JRXML + MD, 支持增量)
 ├── down_embedding_model.py       # 嵌入模型下载
 ├── embed_chunks.py               # Chunk 向量化 (支持增量)
 ├── import_to_chroma.py           # Chroma 向量入库 (支持增量)
 ├── query_chroma.py               # 语义搜索查询
 ├── config.py                     # 统一配置管理 (.env)
-├── .env                          # 环境变量配置
-├── .env.example                  # 配置模板
+├── .env / .env.example           # 环境变量配置
 ├── requirements.txt              # Python 依赖
 ├── jrxml_source/                 # JRXML 源文件
 ├── jrxml_chunker_output/         # 分块输出
-│   ├── all_chunks.json
-│   ├── processing_stats.json
-│   └── per_file/
-├── models/                       # 本地嵌入模型
 ├── embeddings/                   # 向量输出
-│   ├── embeddings.npy
-│   ├── chunks.json
-│   └── embeddings.pkl
 ├── chroma_db/                    # Chroma 持久化数据库
-└── docs/
-    └── file_guide.md
+└── docs/file_guide.md            # 详细文件功能说明
 ```
 
-## 快速开始
-
-### 环境要求
+## 环境要求
 
 - Python 3.11+
 - NVIDIA GPU (推荐 8GB+ 显存) 或 CPU
 - CUDA 12.1+ (GPU 模式)
 
-### 安装
+## 安装与配置
 
 ```bash
 pip install -r requirements.txt
-```
-
-### 配置
-
-```bash
-cp .env.example .env   # 编辑 .env 调整模型、路径等参数
+cp .env.example .env              # 编辑 .env 调整模型、路径等参数
 ```
 
 主要配置项：
 
 | 变量 | 说明 | 默认值 |
-|---|---|---|
+| --- | --- | --- |
 | `EMBEDDING_MODEL_NAME` | 嵌入模型 (Hub 名) | `Qwen/Qwen3-Embedding-0.6B` |
 | `EMBEDDING_MODEL_PATH` | 本地模型路径 | `models/Qwen3-Embedding-0.6B` |
 | `MAX_CHUNK_SIZE` | 单个 chunk 最大字符数 | `2000` |
 | `BATCH_SIZE` | 向量化批大小 | `16` |
 | `CHROMA_COLLECTION_NAME` | Chroma 集合名 | `jrxml_chunks` |
 
-### 完整流程
+---
+
+## 首次使用 — 全量建库
+
+从头构建向量数据库，三个步骤顺序执行：
+
+### 步骤 1：收集 & 分块
 
 ```bash
-# 1. 收集 JRXML 文件
+# 收集 JRXML 模板文件
 python collect_jrxml.py
 
-# 2. 统一分块 (JRXML + Markdown)
+# 统一分块 (JRXML + Markdown 混合目录)
 python batch_chunker.py ./jrxml_source --output ./jrxml_chunker_output
-
-# 3. 下载嵌入模型 (首次)
-python down_embedding_model.py
-
-# 4. 向量化
-python embed_chunks.py
-
-# 5. 导入 Chroma
-python import_to_chroma.py
-
-# 6. 查询
-python query_chroma.py
 ```
 
-### 增量更新
+输出 `jrxml_chunker_output/all_chunks.json` 和 `processing_stats.json`。
 
-新增或修改部分文件时，无需重新处理全部数据：
+### 步骤 2：向量化
 
 ```bash
-# 分块新文件
-python batch_chunker.py ./new_files --output ./jrxml_chunker_output/new_batch
+# 下载嵌入模型 (仅首次)
+python down_embedding_model.py
 
-# 增量向量化 (只处理新 chunks)
-python embed_chunks.py ./jrxml_chunker_output/new_batch/all_chunks.json --incremental
+# 全量向量化
+python embed_chunks.py
+```
 
-# 增量导入 (不删除已有数据)
+输出 `embeddings/embeddings.npy`、`chunks.json` 等文件。
+
+### 步骤 3：导入 Chroma
+
+```bash
+# 全量导入 (创建新集合)
+python import_to_chroma.py
+```
+
+输出 `chroma_db/` 持久化向量数据库。
+
+### 步骤 4：查询
+
+```bash
+# 交互模式
+python query_chroma.py
+
+# 单次查询
+python query_chroma.py "如何修改报表标题"
+python query_chroma.py "SQL查询怎么写" --filter_field query
+python query_chroma.py "报表参数" --threshold 0.5 --n_results 10
+```
+
+---
+
+## 增量更新 — 追加新模板
+
+已有数据库后，添加新模板无需重建。将新文件放入源目录后：
+
+```bash
+# 步骤 1：增量分块 (自动跳过已处理文件，合并到已有结果)
+python batch_chunker.py ./jrxml_source --incremental
+
+# 步骤 2：增量向量化 (只对新 chunks 编码，合并到已有向量)
+python embed_chunks.py --incremental
+
+# 步骤 3：增量导入 (追加到已有集合，不删除现有数据)
 python import_to_chroma.py --incremental
 ```
 
+三个 `--incremental` 标志各自的工作逻辑：
+
+| 步骤 | 如何识别已处理 | 无新数据时 |
+| --- | --- | --- |
+| `batch_chunker` | 对比 `processing_stats.json` 中的文件路径 | 输出 "没有新文件需要处理" |
+| `embed_chunks` | 按 `(context, chunk_id)` 去重 | 输出 "没有新 chunks 需要向量化" |
+| `import_to_chroma` | 查询 Chroma 已有 ID | 输出 "没有新数据需要导入" |
+
+---
+
 ## 分块类型
 
-### JRXML 分块
+### JRXML
 
 | 类型 | 说明 |
 |---|---|
@@ -126,7 +150,7 @@ python import_to_chroma.py --incremental
 | `subreport` | 子报表元素 |
 | `component` | 组件元素 (列表等) |
 
-### Markdown 分块
+### Markdown
 
 | 类型 | 说明 |
 |---|---|
@@ -140,22 +164,6 @@ python import_to_chroma.py --incremental
 | `section_changelog` | 更新日志章节 |
 | `code` | 代码块 |
 
-## 查询
-
-```bash
-# 交互模式
-python query_chroma.py
-
-# 单次查询
-python query_chroma.py "如何修改报表标题"
-
-# 按类型过滤
-python query_chroma.py "SQL怎么写" --filter_field query
-
-# 设置阈值和数量
-python query_chroma.py "报表参数" --threshold 0.5 --n_results 10
-```
-
 ## 支持的 JRXML 数据源
 
 SQL/JDBC · HQL/Hibernate · XPath/XML · JSON · JSONQL · CSV · Data Adapter (Excel/XML/HTTP) · Bean Collection · Empty