SuperBizAgent-java/docs/analysis/plan-chunking-step4-refactor.md

# Plan: 分片策略第 4 步重构

> 分支: `refactor/rag-chunking-strategy`  
> 状态: 规划中  
> 范围: 仅改 `DocumentChunkService.chunkSection()` 一个方法

---

## 背景

经 debug 确认，当前分片流程的 1/2/3 步逻辑正确：

```
第1步 chunkDocument()           → splitByHeadings(content)     ✅ 保持不变
第2步 for each Section          → 循环章节                      ✅ 保持不变
第3步 chunkSection() 入口       → 容量短路判断 + splitByParagraphs  ✅ 保持不变
第4步 chunkSection() 累积循环   → 段落累积 + 字符触发切分       ❌ 需重构
```

**第 4 步的两个核心问题：**

| 问题 | 现象 |
|------|------|
| A. 丢失顺序 | `trim()` + 手工拼接 `\n\n` 导致 `currentStartIndex` 漂移 |
| B. 结构无感知 | 有序列表项被拆散到不同分块（排查步骤 1-4 在一块，第 5 步在另一块） |

---

## 目标

改造 `chunkSection()` 的段落累积循环，使其：

1. **不丢顺序** — 用原始文本索引替代手工拼装的 `currentStartIndex`
2. **感知列表结构** — 有序/无序列表项之间不在中间切断
3. **Token 感知** — 用启发式 token 估算替代纯字符计数（为后续 Spring AI TokenTextSplitter 做准备）
4. **软边界** — 在接近上限时查找语义安全切点，而非硬截断

---

## 不改的部分

| 组件 | 理由 |
|------|------|
| `splitByHeadings()` | 标题分割正确，正则够用 |
| `getOverlapText()` | 句子校准逻辑保留，作为安全网 |
| `DocumentChunk` 数据结构 | 字段完备，无需新增 |
| `DocumentChunkConfig` | 增加 `maxTokens` 字段，保留原字段兼容 |
| `VectorIndexService` | 消费者改动延后到下一阶段 |

---

## 改动方案

### 改动 1: `DocumentChunkConfig` — 增加 token 配置

```java
// 新增字段
private int maxTokens = 500;     // token 上限（中文约500字，英文约2000字符）
private int maxTokensHard = 600; // 硬上限（maxTokens × 1.2）

// 保留原字段作为向后兼容
private int maxSize = 800;       // 保留但标记 @Deprecated
```

### 改动 2: `chunkSection()` — 改造累积循环

**当前逻辑（伪代码）：**

```
for each paragraph:
    if length + paragraph > maxSize → 切分 → 从 overlap 开始新块
    append paragraph + "\n\n"
```

**新逻辑（伪代码）：**

```
for each paragraph:
    currentTokens = estimateTokens(buffer)
    paraTokens = estimateTokens(paragraph)
    
    if currentTokens + paraTokens > maxTokens:
        if isInUnbreakableContext(buffer, paragraph):
            if currentTokens + paraTokens > maxTokensHard:
                → 必须切（硬上限保护）
            else:
                → 不切，继续累积（容忍超出，保护列表完整性）
        else:
            → 切分（段落边界 = 安全切点）
            → 从 overlap 开始新块
    else:
        → 不切，继续累积
    
    append paragraph + "\n\n"
```

### 改动 3: 新增 `estimateTokens()` — 启发式 token 估算

```java
/**
 * 启发式 token 估算（无需外部依赖）
 * 中文: ~1 字符/token
 * 英文/数字: ~4 字符/token
 * 标点/空白: 忽略
 */
private int estimateTokens(String text) {
    int tokens = 0;
    for (char c : text.toCharArray()) {
        if (Character.UnicodeBlock.of(c) == Character.UnicodeBlock.CJK_UNIFIED_IDEOGRAPHS
            || Character.UnicodeBlock.of(c) == Character.UnicodeBlock.CJK_UNIFIED_IDEOGRAPHS_EXTENSION_A) {
            tokens += 1;   // 中文字符 1:1
        } else if (Character.isWhitespace(c)) {
            // 空白字符不计
        } else {
            tokens += 1;   // 非中文凑 4 个算 1 token（简化）
        }
    }
    // 非中文部分 / 4
    return tokens;
}
```

### 改动 4: 新增 `isInUnbreakableContext()` — 结构感知

```java
/**
 * 判断当前段落是否属于不可中断的结构
 * 返回 true = 不能在当前位置切分
 */
private boolean isInUnbreakableContext(String buffer, String nextParagraph) {
    // 有序列表: "1. " "2. " "3. " 格式
    if (nextParagraph.matches("^\\d{1,2}\\.\\s.*")) {
        // 前一个段落也是列表项 → 不切
        String lastLine = getLastNonEmptyLine(buffer);
        if (lastLine.matches("^\\d{1,2}\\.\\s.*|.*\\n\\d{1,2}\\.\\s.*")) {
            return true;
        }
    }
    // 无序列表: "- " 或 "* " 格式
    if (nextParagraph.matches("^[-*]\\s.*")) {
        String lastLine = getLastNonEmptyLine(buffer);
        if (lastLine.matches("^[-*]\\s.*|.*\\n[-*]\\s.*")) {
            return true;
        }
    }
    // 代码块: ``` 内部不切
    if (buffer.contains("```") && countOccurrences(buffer, "```") % 2 == 1) {
        return true;  // 在未闭合的代码块内 → 不切
    }
    return false;
}
```

### 改动 5: 修复 index 漂移

```java
// 当前问题：用手工拼装的 chunkContent.length() 推算 offset
// String chunkContent = currentChunk.toString().trim();  ← trim 丢字符
// currentStartIndex = currentStartIndex + chunkContent.length() - overlap.length();  ← 漂移

// 改为：用段落在原始文档中的实际位置
// 对每个 paragraph 记录其在 section.content 中的 offset，切分时直接使用
```

---

## 改动文件清单

| 文件 | 改动 | 行数变化 |
|------|------|----------|
| `config/DocumentChunkConfig.java` | +2 字段 | +8 |
| `service/DocumentChunkService.java` | 改造 `chunkSection()` + 3 个新方法 | ~+50 / -20 |
| `test/.../DocumentChunkServiceTest.java` | 新增列表结构感知 + token 估算用例 | +40 |

总计改动约 80 行，仅影响一个核心方法。

---

## 验收标准

| # | 用例 | 预期 |
|---|------|------|
| 1 | 有序列表（5 项，每项 50 字符，maxTokens=180） | 5 项不拆散，容忍略超上限 |
| 2 | 有序列表（20 项，超 maxTokensHard） | 在硬上限处切，但不在列表项中间切 |
| 3 | 纯段落（10 段，每段 100 字符，maxTokens=300） | 在段落边界切 |
| 4 | 中文 800 字 vs 英文 3200 字符 | 分块数接近 |
| 5 | H1→空的→H2（标题空壳） | 仍有（不在本次修复范围） |
| 6 | 原有测试：空文档、短文档、标题分割、重叠、chunkIndex | 全部通过 |

---

## 后续阶段

| 阶段 | 内容 | 依赖 |
|------|------|------|
| **Phase 1（本次）** | 改 `chunkSection()` — token + 列表感知 | 无 |
| Phase 2 | 标题空壳问题修复（`splitByHeadings` 合并相邻空 section） | Phase 1 |
| Phase 3 | 可选：切换到 Spring AI `TokenTextSplitter` | Phase 1/2 |
| Phase 4 | 语义相似度辅助切点决策 | Phase 1 |
| Phase 5 | Markdown AST 解析替代正则 | 低优先级 |