2026Technology-Competition/docs/milestone2.5-mixed-parser-review.md

里程碑 2.5（MIXED 完整段落解析）评审与交付报告

• 日期：2026-08-09
• 状态：通过（最终里程碑评审 Ready for delivery: YES）
• 关联文档：docs/superpowers/specs/2026-08-09-mixed-paragraph-parsing-design.md、docs/superpowers/plans/2026-08-09-mixed-paragraph-parsing.md、docs/milestone2-excel-parser-review.md（遗留记录#1 的闭环）
• 范围：里程碑 2 验收遗留项「MIXED 折叠进纯表路径」的完整落地（design §3.5.2「段落分割→各段落最优解析」）

一、交付内容

新实现 5 个任务、6 个新测试用例（当前全量 58 passed），7 个提交（base 81c6b6c）：

任务	提交	说明
Task 9 段落分割器	34ef28b	paragraph_splitter.py：split_paragraphs(matrix) -> list[(start,end)]（含端点、0-based，全空行为界，空矩阵→[]）
Task 10 data_models 扩展	539945b	追加 MixedParagraph（kind=table/free_text、matrix、table、text、source_range）、MixedSheet；ExcelParseResult.mixed（默认[]）；仅追加不改既有类字段
Task 11 MIXED 装配	1e3f702（+docs bc79945）	excel_parser.py MIXED 分支：forward_fill→split→每段 classify→TABLE：段内 header_row=find_header_row(seg) + seg_fmt_map（物理→段内坐标）；其余→FREE_TEXT（extract_text_blocks+build_free_text_table，防二次递归）；表/自由文本段双写 result.tables + result.mixed
Task 12 混合型样本+端到端	7592516	samples/要件定義_混合型.xlsx（表段+连续碎片段）；test_real_samples.py 新增 test_mixed_sample_segments_detected（段落==2、kinds、F101、rows==3、碎片含 改修ポイント/対象期間）
Task 13 遗留清理	d93cc77	① extraction_method 枚举同源（ExtractionMethod .value）；② header_row 越界防御；③ forward_fill 非法/越界范围跳过完整实现；④ Provenance.row 语义注释；⑤ 补测试 6 个

二、验收结论

验收项	结论
段落分割（空行边界）	✅ 纯函数 5 用例 + 样本实测 [(0,3),(5,6)]
段落容器与 API 兼容	✅ 追加式扩展，既有类/字段/消费方零破坏（58 passed）
MIXED 各段最优解析	✅ 表段 → extract_table（表头/格式化）；碎片段 → 文本块+占位表（llm_from_free_text）
formatting_map 段内坐标	✅ seg_fmt_map[(pr-s, pc)] 物理→段内平移，与 extract_table 索引语义闭环（test_parse_mixed_sheet_formatting_in_mid_segment 锁旧错误）
防二次递归	✅ 段内二次 MIXED 落入 FREE_TEXT 分支
混合型端到端	✅ 样本真实驱动，断言 4 项全绿、无 skip
回归安全	✅ TABLE/FREE_TEXT 路径行为不变；58 passed（14 基线 + 27 里程碑2 + 17 新 M2.5）
每任务 pytest 全绿	✅ 各任务评审均 Approved（T9-T13）
覆盖率 >80%	⚠️ 未安装 pytest-cov（同里程碑2，可选增强，非阻塞）

三、评审发现与闭环

最终里程碑评审（base 81c6b6c..d93cc77）独立复验：58/58 passed、样本直接内省 [(0,3),(5,6)]、坐标转移零偏移（F101 段内 (1,0)）；无 Critical / Important，仅以下 Minor（已记录，不影响交付）：

事项	处置
progress.md Task11 重复/编码行	本次去重
MixedParagraph.matrix docstring 写「原始矩阵」但存 forward-filled 段	标签进 backlog（措辞调整）
excel_parser 两处重复的 fmt_map 遍历	backlog（后续抽取公共辅助）
test_excel_parser.py 中部 import（风格）	backlog
_AI_USAGE_LOG.md Task13 范式步骤「整体迭代」用词	本次改为「反馈迭代」并补时间
尾随空行（Windows 风格）	既有 backlog（非功能）

四、下一步建议（不在本里程碑范围）

• 将碎片段中「・」/「■」结构化到 LLM 提取（依赖 InferenceEngine，后续里程碑）
• 覆盖率工具（pytest-cov）与默读增强
• 既有 MIXED 的 source_range 供 Impact/Writer 的追溯消费

五、提交与日志

• 提交：34ef28b 0f137b9 539945b 1e3f702 bc79945 7592516 d93cc77
• _AI_USAGE_LOG.md 每任务各追加 1 行（范式步骤：Agent 实现/测试验证/反馈迭代），模型 deepseek-v4-flash-free
• （本次报告本身随附日志行 + 提交）