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

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

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

docs/file_guide.md

@@ -8,10 +8,6 @@
 
 **功能**: 从 JasperReports 模板库目录递归收集 `.jrxml` 文件，复制到项目 `jrxml_source` 目录。
 
-**输入**: 源目录路径（硬编码，可按需修改）
-
-**输出**: `jrxml_source/` 目录
-
 **使用方式**:
 ```bash
 python collect_jrxml.py
@@ -21,21 +17,19 @@ python collect_jrxml.py
 
 ## 2. jrxml_chunker.py — JRXML 语义分块引擎 (v3.0)
 
-**功能**: 将单个 JRXML 文件按语义结构拆分，每个 chunk 包含人类可读描述、原始 XML 和结构化元数据。
+**功能**: 将单个 JRXML 文件按语义结构拆分。被 `batch_chunker.py` 调用，也可单独使用。
 
 **输入**: 单个 `.jrxml` 文件路径（或目录）
 
 **输出**: `JRXMLChunk` 列表，字段包括:
 - `chunk_id`: 文件内序号
-- `chunk_type`: 分块类型 (如 `query`, `band_detail`, `chart` 等)
+- `chunk_type`: 分块类型 (`query`, `band_detail`, `chart` 等)
 - `human_description`: 人类可读描述
 - `raw_xml`: 原始 XML 片段
 - `context`: 所属报表名称
 - `metadata`: 元数据 (report_name, band_name, element_kind 等)
 
-**支持的数据源**: SQL, HQL, XPath, JSON, JSONQL, CSV, Data Adapter, Bean Collection, Empty
-
-**使用方式**:
+**单独使用**:
 ```bash
 python jrxml_chunker.py report.jrxml          # 单文件
 python jrxml_chunker.py ./jrxml_source/       # 目录
@@ -43,39 +37,16 @@ python jrxml_chunker.py ./jrxml_source/       # 目录
 
 ---
 
-## 3. jrxml_banch_chunker.py — JRXML 批量分块 (单类型)
+## 3. md_chunker.py — Markdown 语义分块引擎
 
-**功能**: 批量处理目录下所有 JRXML 文件，生成统计报告和按文件分类的输出。是旧版入口，被 `batch_chunker.py` 取代。
-
-**使用方式**:
-```bash
-python jrxml_banch_chunker.py ./jrxml_source --output ./output
-```
-
----
-
-## 4. md_chunker.py — Markdown 语义分块引擎
-
-**功能**: 将 Markdown 文件按标题层级、代码块、表格等结构化元素智能分块。
-
-**输入**: 单个 `.md` 文件路径（或目录）
-
-**输出**: `MDChunk` 列表，字段包括:
-- `chunk_id`: 文件内序号
-- `chunk_type`: 分块类型 (`section_h1`, `code`, `section_installation` 等)
-- `human_description`: 人类可读描述
-- `raw_content`: 原始 Markdown 内容
-- `context`: 所属文档标题
-- `metadata`: 元数据 (heading, heading_level, language 等)
+**功能**: 将 Markdown 文件按标题层级、代码块、表格等结构化元素智能分块。被 `batch_chunker.py` 调用，也可单独使用。
 
 **分块策略**:
-- 按标题层级 (H1/H2/H3) 划分段落
-- 代码块作为独立 chunk
-- 表格作为独立 chunk
-- H2 标题自动识别特殊类型（安装、配置、API、示例等）
+- 按标题层级 (H1/H2/H3) 划分段落，H2 自动识别特殊类型
+- 代码块、表格作为独立 chunk
 - 过长段落按段落/句子二次拆分
 
-**使用方式**:
+**单独使用**:
 ```bash
 python md_chunker.py doc.md                   # 单文件
 python md_chunker.py ./docs/                  # 目录
@@ -83,58 +54,63 @@ python md_chunker.py ./docs/                  # 目录
 
 ---
 
-## 5. batch_chunker.py — 统一批量分块入口
+## 4. batch_chunker.py — 统一批量分块入口
 
-**功能**: 统一入口，支持 JRXML 和 Markdown 文件混合批量处理，生成合并的 chunks 和统计报告。
-
-**输入**: 包含 `.jrxml` / `.md` 文件的目录
+**功能**: 统一入口，支持 JRXML + Markdown 混合批量处理。**支持增量模式**。
 
 **输出**:
 - `all_chunks.json`: 所有 chunks 合并
-- `processing_stats.json`: 处理统计 (成功/失败/耗时/类型分布)
+- `processing_stats.json`: 处理统计 (文件级 chunk 数量、类型分布)
 
-**使用方式**:
+**全量模式** — 首次建库:
 ```bash
-python batch_chunker.py ./mixed_source
-python batch_chunker.py ./mixed_source --output ./my_output
+python batch_chunker.py ./jrxml_source --output ./jrxml_chunker_output
 ```
 
+**增量模式** (`--incremental`) — 追加新文件:
+```bash
+python batch_chunker.py ./jrxml_source --incremental
+```
+
+增量模式逻辑：
+1. 加载已有 `processing_stats.json`，获取已处理文件列表
+2. 扫描输入目录，自动跳过已处理文件
+3. 只分块新增文件
+4. 合并新旧 `all_chunks.json` 和统计数据后保存
+
 ---
 
-## 6. down_embedding_model.py — 嵌入模型下载
+## 5. down_embedding_model.py — 嵌入模型下载
 
-**功能**: 从 HuggingFace Hub 下载嵌入模型到本地。支持国内镜像加速和断点续传。
+**功能**: 从 HuggingFace Hub 下载嵌入模型到本地。支持国内镜像 (`hf-mirror.com`)、断点续传。
 
-**使用方式**:
 ```bash
 python down_embedding_model.py
 ```
 
 ---
 
-## 7. embed_chunks.py — Chunk 向量化
+## 6. embed_chunks.py — Chunk 向量化
 
-**功能**: 使用嵌入模型将 chunks 转换为向量。支持 GPU/CPU、FP16 半精度，**支持增量模式**。
-
-**输入**: chunks JSON 文件 (默认 `jrxml_chunker_output/all_chunks.json`)
+**功能**: 将 chunks 转换为向量。支持 GPU/CPU、FP16 半精度，**支持增量模式**。
 
 **输出**:
 - `embeddings/embeddings.npy`: 向量矩阵 (float32)
 - `embeddings/chunks.json`: 原始 chunks
-- `embeddings/chunk_id_map.json` / `chunk_type_map.json`: 映射文件
-- `embeddings/embeddings.pkl`: 完整数据 pickle
+- `embeddings/chunk_id_map.json` / `chunk_type_map.json`
+- `embeddings/embeddings.pkl`: 完整 pickle
 
-**全量模式**:
+**全量模式** — 首次向量化:
 ```bash
 python embed_chunks.py
-python embed_chunks.py --batch_size 2
-python embed_chunks.py --model_path "sentence-transformers/all-MiniLM-L6-v2"
+python embed_chunks.py --batch_size 2                         # 调整批大小
+python embed_chunks.py --model_path "all-MiniLM-L6-v2"        # 换模型
+python embed_chunks.py --no_fp16                              # 禁用半精度
 ```
 
-**增量模式** (`--incremental` / `-i`):
+**增量模式** (`--incremental` / `-i`) — 只编码新 chunks:
 ```bash
-# 只向量化新增 chunks，自动合并到已有向量数据
-python embed_chunks.py ./new_chunks/all_chunks.json --incremental
+python embed_chunks.py --incremental
 ```
 
 增量模式逻辑：
@@ -145,67 +121,55 @@ python embed_chunks.py ./new_chunks/all_chunks.json --incremental
 
 ---
 
-## 8. import_to_chroma.py — Chroma 向量入库
+## 7. import_to_chroma.py — Chroma 向量入库
 
 **功能**: 将向量数据导入 Chroma 持久化数据库。**支持增量模式**。
 
-**输入**: `embeddings/embeddings.npy` + `embeddings/chunks.json`
-
-**输出**: `chroma_db/` 持久化数据库
-
-**全量模式** (删除旧集合重建):
+**全量模式** — 首次导入 (删除旧集合重建):
 ```bash
 python import_to_chroma.py
 ```
 
-**增量模式** (`--incremental` / `-i`):
+**增量模式** (`--incremental` / `-i`) — 追加新记录:
 ```bash
-# 追加新记录到已有集合，不删除已有数据
 python import_to_chroma.py --incremental
 ```
 
 增量模式逻辑：
-1. 使用 `get_or_create_collection` (不删除已有数据)
-2. 查询已有 ID，跳过已导入的记录
-3. 只追加新增数据
+1. `get_or_create_collection` (不删除已有数据)
+2. 查询 Chroma 已有 ID
+3. 跳过已导入的记录，只追加新数据
 
 ---
 
-## 9. query_chroma.py — 语义搜索查询
+## 8. query_chroma.py — 语义搜索查询
 
-**功能**: 通过自然语言查询 Chroma 数据库，检索相关的 JRXML/Markdown chunks。
+**功能**: 通过自然语言查询 Chroma 数据库。
 
 **两种模式**:
-- 命令行单次查询: `python query_chroma.py "查询内容"`
-- 交互模式: `python query_chroma.py` (支持连续查询)
+- **单次查询**: `python query_chroma.py "查询内容"`
+- **交互模式**: `python query_chroma.py`（支持连续查询和内联命令）
 
 **交互模式命令**:
 ```
 filter:<类型>     按 chunk_type 过滤 (如 filter:query)
-t:<阈值>          设置相似度阈值 0~1
-k:<数量>          设置返回结果数
+t:<阈值>          相似度阈值 0~1 (如 t:0.5)
+k:<数量>          返回结果数 (如 k:10)
 ```
 
-**使用方式**:
+**使用示例**:
 ```bash
-python query_chroma.py                              # 交互模式
-python query_chroma.py "如何修改报表标题"             # 单次查询
+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
 ```
 
 ---
 
-## 10. config.py — 统一配置管理
+## 9. config.py — 统一配置管理
 
-**功能**: 从 `.env` 文件加载所有配置项，所有脚本通过此模块获取配置。
-
-**配置分组**:
-- 模型配置: `EMBEDDING_MODEL_NAME`, `EMBEDDING_MODEL_PATH`, `HF_ENDPOINT`
-- 硬件配置: `USE_GPU`, `USE_FP16`, `BATCH_SIZE`
-- 目录配置: `JRXML_SOURCE_DIR`, `CHUNKER_OUTPUT_DIR`, `EMBEDDINGS_DIR`, `CHROMA_DB_PATH`
-- 分块配置: `MAX_CHUNK_SIZE`
-- 查询配置: `DEFAULT_N_RESULTS`, `SIMILARITY_THRESHOLD`
+**功能**: 从 `.env` 加载所有配置，所有脚本通过此模块获取配置项。
 
 ```bash
 python config.py   # 打印当前配置
@@ -213,30 +177,89 @@ python config.py   # 打印当前配置
 
 ---
 
-## 数据流全景
+## 10. jrxml_banch_chunker.py — 旧版入口 (已废弃)
+
+**功能**: JRXML 单类型批量分块。已被 `batch_chunker.py` 取代，保留以兼容旧流程。
+
+---
+
+## 使用场景
+
+### 场景 A：首次构建数据库
+
+```bash
+# 1. 准备源文件
+python collect_jrxml.py
+# 将 Markdown 文档放入 jrxml_source/ 或指定目录
+
+# 2. 全量分块
+python batch_chunker.py ./jrxml_source
+
+# 3. 下载模型 + 全量向量化
+python down_embedding_model.py
+python embed_chunks.py
+
+# 4. 全量导入
+python import_to_chroma.py
+
+# 5. 开始查询
+python query_chroma.py
+```
+
+### 场景 B：追加新模板/文档
+
+```bash
+# 将新 .jrxml / .md 文件放入源目录后：
+
+# 1. 增量分块 — 自动跳过已处理文件
+python batch_chunker.py ./jrxml_source --incremental
+
+# 2. 增量向量化 — 只编码新 chunks
+python embed_chunks.py --incremental
+
+# 3. 增量导入 — 追加到已有数据库
+python import_to_chroma.py --incremental
+```
+
+### 场景 C：更换嵌入模型
+
+```bash
+# 1. 编辑 .env 修改 EMBEDDING_MODEL_NAME / EMBEDDING_MODEL_PATH
+# 2. 下载新模型
+python down_embedding_model.py
+
+# 3. 重新向量化 (全量)
+python embed_chunks.py
+
+# 4. 重建数据库
+python import_to_chroma.py
+```
+
+---
+
+## 数据流
 
 ```
 ┌─────────────────────┐
-│ JasperReports 模板库 │  (.jrxml)
-│ Markdown 文档        │  (.md)
+│ JRXML 模板 (.jrxml)  │
+│ Markdown 文档 (.md)  │
 └──────────┬──────────┘
            │ collect_jrxml.py / 手动放置
            ▼
 ┌─────────────────────┐
-│ jrxml_source/       │  源文件目录
-│ docs/               │
+│ jrxml_source/       │
 └──────────┬──────────┘
-           │ batch_chunker.py (调用 jrxml_chunker.py + md_chunker.py)
+           │ batch_chunker.py [--incremental]
            ▼
 ┌──────────────────────┐
-│ jrxml_chunker_output/│  all_chunks.json + processing_stats.json
+│ jrxml_chunker_output/│  all_chunks.json
 └──────────┬───────────┘
-           │ embed_chunks.py (Qwen3-Embedding, 支持增量)
+           │ embed_chunks.py [--incremental]
            ▼
 ┌─────────────────┐
 │ embeddings/     │  embeddings.npy + chunks.json
 └────────┬────────┘
-         │ import_to_chroma.py (ChromaDB, 支持增量)
+         │ import_to_chroma.py [--incremental]
          ▼
 ┌─────────────────┐
 │ chroma_db/      │  Chroma 向量数据库