LLMCase-V4
定位 ：面向人的机制级实现说明------用于快速理解、学习、复用 本工程各核心机制。
区别于：设计文档（为什么这样设计/决策链）、
全流程架构与实现.md（流水线各阶段原理与坑）、使用与维护指南（怎么用）。章节体系 ：本工程本质是领域特化 RAG 系统 （策划文档 → 检索增强 → 测试要点/用例生成 → 评估），
章节按 RAG pipeline 阶段编号组织（00-11），每章内以「递进小节」展开（基础→变体→本工程特化）。
每小节固定四段：① 机制一句话；② 数据流图；③ 代码入口（
path:line锚定）；④ 复用清单。⚠️ 骨架版（session#70 立项）：小节标题与内容后续对话逐步充实调整。
开发任务排序：任务 1=实现新功能，任务 2=本文档（培训教材）。
维护纪律：涉及下述机制的 change 收尾时，须同步更新本文档对应小节。
00 工程总览与最小链路
- 00-1 一句话与总架构：策划文档（docx）→ 结构化测试要点与用例 + 全程质量评估；四服务拓扑（convert2md:8000 / generator:8001 / evaluator:8002 / dashboard:8080）与共享层（
model_core/modules/common）。 - 00-2 数据流水线阶段目录总图（
data/workspace/01_raw → 02_markdown → 03_entity → 04_point → 05_case → 06_eval，后缀 SRC/ENT/PNT/CAS/EVAL）。 - 00-3 一次端到端数据旅行叙事（拿一份真实 docx 走完全链）。
- 00-4 环境与运行（.env / start_all_services / 已知坑速查）。
01 数据导入：docx 到 markdown
- 01-1 简单文本导入（纯文字 docx → md 的基本链路）
- 01-2 结构化内容（标题层级、列表、加粗等格式映射）
- 01-3 图文数据（图片抽取 +
<!--IMG_REF-->占位符协议） - 01-4 表格数据（docx 表格 → md 表格 → ExcelTableThinking）
- 01-5 归档契约与版本（单文件 + 行区间、
.superseded_归档、批次 artifacts.source）
02 文本切块：从文档到提取单元
- 02-1 章节树构建（标题层级=功能层级假设，section 切分）
- 02-2 辅助段落分流（aux-section：overview 反哺 / boilerplate 跳过）
- 02-3 正文前约定区切分（preamble：三级识别 + 指导/提取双路，
template_chapters.split_preamble） - 02-4 跨表/跨节块（ExcelTableThinking 块、跨节依赖 Pass 2）
03 实体提取：文本到功能实体图（本工程特化）
- 03-1 两遍提取（骨架 Pass→细化 Pass→依赖解析）
- 03-2 prompt 组装与 flag 体系（模板章节 guard 白名单、img 上下文注入、aux 背景）
- 03-3 实体合并与孤儿挂接、原子性判定
- 03-4 共享词表体系（template_chapters / aux_sections 单一真相源）
04 向量嵌入
- 04-1 嵌入模型选型（bge-m3：多语/长文本/延迟基线）
- 04-2 嵌入什么（实体/要点/用例的向量化对象与粒度）
05 向量存储
- 05-1 FAISS 索引结构与持久化
- 05-2 few-shot 样例池（genre/universal 双池、入库治理）
06 检索前处理
- 06-1 查询构造（从实体/要点生成检索 query）
- 06-2 三级路由（tier1 项目内 → tier2 品类 → tier3 零样本）
- 06-3 提问式生成的子树圈定（scope）
07 索引优化（拟，后续调整）
08 检索后处理
- 08-1 宽召回 + rerank（recall floor、bge reranker）
- 08-2 检索质量阈值与忠实性（faithfulness，防编造）
09 响应生成：测试要点与用例
- 09-1 测试要点生成（TP：结构、prompt、few-shot 注入）
- 09-2 测试用例生成（CAS：步骤/断言、四象限）
- 09-3 提问式生成双路（单点生成 ask 流）
10 系统评估
- 10-1 geval judge（LLM 评估）
- 10-2 critic 四维（单条质量）
- 10-3 watchdog 双轨交叉验证（确定性 vs LLM 分歧）
- 10-4 A/B 实验方法学（本工程反复使用的判据体系）
11 高级机制（拟，后续调整）
- 11-1 few-shot 价值结论（产量放大器而非质量提升器）
- 11-2 批次血缘与产物回溯（sessions/backfill）
- 11-3 可观测性（结构化日志 TAG 协议 / log_doctor / Langfuse / flag 收敛）
附录 A：复用依赖地图（拟）
编写进度
| 章节 | 状态 | 完成时间 |
|---|---|---|
| 00 总览与最小链路 | 待写 | |
| 01 数据导入 | 待写 | |
| 02 文本切块 | 待写 | |
| 03 实体提取 | 待写 | |
| 04 向量嵌入 | 待写 | |
| 05 向量存储 | 待写 | |
| 06 检索前处理 | 待写 | |
| 07 索引优化（拟） | 待定 | |
| 08 检索后处理 | 待写 | |
| 09 响应生成 | 待写 | |
| 10 系统评估 | 待写 | |
| 11 高级机制（拟） | 待定 |