2026Technology-Competition/docs/superpowers/specs/2026-08-09-phase3-word-parser-design.md

Phase 3「Word 解析优先」设计（Parser Agent - Word 解析 + 聚合）

状态： 已批准（brainstorming + 范围澄清吸收） 日期： 2026-08-09 里程碑： implementation-plan 阶段 3（Word 解析优先切片）

1. 背景与目标

implementation-plan.md 阶段 3 定义 Parser Agent 的 Word/PPT 解析与现系统探索。经范围澄清（用户确认），本次迭代只做 Word 解析优先 切片：实现为后续 Writer（阶段 7）、RAG 规则检索（阶段 4）、QA（阶段 8）服务的 Word 模板解析 / Word 规则文档 Markdown 化 / 全量输入聚合 基础设施。

现状：

• data_models.py 已定义 ParsedTemplate / ChapterMarker / RuleDocument / StructuredSource / UnifiedDocument 等数据类，可直接复用
• parsers/ 已有完整 Excel 解析链（ExcelParser → ExcelParseResult），且 python-docx>=1.0 已在 pyproject.toml
• samples/ 已有 3 个 Word 样本：概要設計書テンプレート.docx（模板）、概要設計做成説明書.docx（做成说明书）、記入規則.docx（记入规则），以及 5 个 Excel 样本
• 全量测试基线 132 passed / 100.00% 覆盖（fail_under=99 红线）

目标： 新增 WordTemplateParser（章构成/占位符/样式名提取）、RuleDocParser（docx → Markdown + 规则分类）、SourceParser 门面（按扩展名路由全量输入 → StructuredSource），并配套单元测试与真实样本集成测试，保持红线不回归。

2. 范围与不做的事

范围（implementation-plan 3.1 / 3.2 / 3.6 / 3.7）：

• 3.1 WordTemplateParser：章构成（Heading 层级）提取、占位符（{{section:xxx}}）检测、样式名提取
• 3.2 RuleDocParser（Word）：规则文档 Markdown 化、规则分类（按来源映射）
• 3.6 SourceAggregator：全量输入（Excel 要件定义 + Word 模板 + Word 规则）统一组装 StructuredSource
• 3.7 Parser Agent 集成测试：真实样本（3 Word + 5 Excel）全链路

不做（YAGNI / 后续里程碑）：

• ❌ 3.3 PPTXParser（无 .pptx 样本、python-pptx 未安装）→ 后续补样本后实施
• ❌ 3.4 现有系统代码探索（CodeParser 未实现、无 .java 样本）→ 后续实施
• ❌ 3.5 现有系统设计书探索（无现系统 Word/Excel 设计书样本）→ 后续实施
• ❌ FileReader 统一读取层（UnifiedDocument）（方案 B 否决；现有 Excel 链直接 openpyxl，本轮不重构）
• ❌ 完整样式定义提取（字号/颜色等）（YAGNI：阶段 3 无样式消费方，阶段 7/8 再按需深挖）
• ❌ LLM 参与的规则分类（按来源映射，零网络依赖、离线可测）
• ❌ data_models.py 数据模型改动（现有类型完全够用）

3. 设计

3.1 架构

在 src/genesis/parsers/ 下新增 3 个模块，与现有 excel_parser.py 同构（扁平模块、dataclass 结果、纯函数拆分）：

parsers/
├── excel_parser.py          # 现有，不动
├── word_template_parser.py  # 新：WordTemplateParser
├── rule_doc_parser.py       # 新：RuleDocParser
└── source_aggregator.py     # 新：SourceParser 门面

3.2 WordTemplateParser

输入： docx 路径（str | Path） 输出： ParsedTemplate{file_name, sections, placeholders, styles}（复用 data_models 类型）

占位符统一正则（§3.2 与 §3.6 共用同一契约）： {{([a-z][a-z0-9_]*)(?::([a-z][a-z0-9_]*))?}}——匹配两种形态：带章节名 {{section:introduction}}（组1=section，组2=章节名）与封面型 {{doc_title}}（仅组1=键名）。不匹配该正则的 {{...}} 视为普通正文。

提取逻辑（python-docx）：

产物	提取方式	说明
sections	遍历文档段落，识别 Heading 样式的段落 → ChapterMarker(type="heading", name=段落文本, level=大纲级别)；遍历书签（bookmarkStart）→ type="bookmark"；遍历占位符 → type="placeholder"	ChapterMarker.type 取值 `"heading"
placeholders	用统一正则识别上述两种占位符 → {占位符名: 出现位置或上下文}	占位符名去重（section:introduction / doc_title 等）
styles	收集文档命名样式 + 各段落实际使用的样式名 → 去重集合	样式名级（不提取字号/颜色/字体明细）

3.3 RuleDocParser

输入： docx 路径 + category（调用方按来源映射传入："write" | "design" | "ref"） 输出： RuleDocument{file_name, category, markdown_content, source_path, file_type="word", hash}

Markdown 化规则：

docx 元素	Markdown 输出
Heading 1/2/3	# / ## / ### 标题行
普通段落	文本行
表格	GFM 表格（表头 + 分隔行 + 数据行）
列表项	- 项（检测双通道：样式名含 List Bullet/List Number 或 文本以 ・/-/• 前缀开头——真实样本列表项为 Normal 样式 + ・ 前缀，样式名通道不足以命中）
空段	空行

• hash = 文件内容 sha256 hex（供阶段 4 规则版本管理，即 rag-layer §5 文档级增量更新比对键）
• file_type 固定 "word"

来源映射（分类策略，零 LLM）：

输入文件	category	依据
記入規則.docx	write	写入规则（Type A）
概要設計做成説明書.docx	write	做成说明书 = 各章作成指引，规范明确归类 Type A 写入规则（api-design §2.2 write_instruction、rag-layer §1.1）

类别语义（对齐 design §5.3 / rag-layer §1.1）：

• write — 写入规则（记入规则、图表规则、字体/格式规范）→ Writer Agent 每章生成时检索（Type A）
• design — 设计规则（架构约束、安全要求、设计方针）→ Impact Agent 关联推理时参考（Type B）
• ref — 参考设计文档（过往概要设计书、设计决策记录），可选增强（Type C）

本轮样本三类 docx 全部为 write；design/ref 类别暂由其它输入类型（后续 Excel 图表规则/现系统设计书）填充。

明确的策略： rule_paths 仅接受 .docx 规则文档；类别由门面按来源映射（記入規則* → write，write_instruction（做成说明书）→ write，其余文件名 → write 兜底）。Excel 图表规则（図表規則.xlsx）本轮不纳入 rule_docs（Excel 规则解析留给后续迭代）。

3.4 SourceParser 门面（3.6 SourceAggregator）

输入：

• requirement_paths: list[str | Path] — 要件定义 Excel 列表（api-design requirements）
• template_path: str | Path | None — 概要设计模板 docx（api-design template）
• write_instruction_paths: list[str | Path] — 做成说明书列表（api-design write_instruction，均为 .docx）
• rule_paths: list[str | Path] — 记入规则等规则文档列表（api-design rules，仅 docx）

类别映射（显式角色，零 LLM）： write_instruction_paths 中的文档固定 category="write"（对齐 api-design §2.2「write_instruction RAG 归类 Type A 写入规则」）；rule_paths 中文件名含 記入規則 → write，其它 → write 兜底。不做基于内容/名字的隐式猜测——角色由调用方按 api-design file_type 语义显式传入。

路由：

扩展名/角色	解析器	产物
.xlsx（requirement_paths）	现有 ExcelParser	tables + comments
模板 docx（template_path）	WordTemplateParser	template: ParsedTemplate
做成说明书 docx（write_instruction_paths）	RuleDocParser（category=write）	rule_docs: list[RuleDocument]
规则 docx（rule_paths）	RuleDocParser（category=write）	rule_docs: list[RuleDocument]

输出： StructuredSource{tables, template, rule_docs, image_analyses=[], existing_system=None, comments}（image_analyses/existing_system 本轮恒为空/None，类型字段保留）。

3.5 数据流

samples/*.xlsx ────────────────► ExcelParser ───────► tables / comments
samples/テンプレート.docx ─────► WordTemplateParser ─► template: ParsedTemplate  ─┐
samples/記入規則.docx ─────────► RuleDocParser ─────► rule_docs(write) ───────────┼─► StructuredSource
samples/概要設計做成説明書.docx ─► RuleDocParser ─────► rule_docs(write) ───────────┘

3.6 错误处理

场景	行为
文件不存在	抛出 FileNotFoundError（消息含路径，便于定位）
模板无 Heading / 空文档	WordTemplateParser 返回空 sections/placeholders；RuleDocParser 返回空 markdown_content。均不崩溃（与 ExcelParser 的 skipped 哲学一致）
非法占位符格式（不匹配统一正则的 {{...}}）	不识别为占位符，正文文本原样保留
未知扩展名（如 .txt/.md）	SourceParser 路由阶段报错：ValueError("不支持的文件类型: ...")
docx 损坏	透出 python-docx 异常（PackageNotFoundError），测试不吞

3.7 与现有代码的关系

• 不改 excel_parser.py、data_models.py、pyproject.toml、任何现有测试
• 只新增 src 3 个生产模块 + 4 个测试文件（含 docx_helpers.py）+ 扩展 test_real_samples.py
• 提交消息前缀：feat:（生产实现）/ test:（门禁测试）/ docs:（本文档与 AI 日志）

4. 文件定位与测试先例

• 单元测试沿用 tests/test_real_samples.py:7 的定位方式：Path(__file__).resolve().parents[1] / "samples"，样本缺失 pytest.skip
• 新建 tests/docx_helpers.py 测试基建（与现有 tests/excel_helpers.py 对称）：new_document() 内存构造 / save_document(tmp_path, doc) 落盘，供 3 个 Word 测试文件复用；覆盖 Heading/表格/列表（・ 前缀 + List Bullet 样式双通道）/占位符/书签/空文档等模板
• 新模块覆盖路径（P1-3，fail_under=99 达成路径）：WordTemplateParser 空文档护栏、非模板 docx（无 Heading）、占位符边界（非法格式原样保留）；RuleDocParser 列表双通道命中/未命中、空文档、hash 稳定性；SourceParser 未知扩展名报错、template_path=None、write_instruction/rule 双通道合并、Excel+Word 全量组装
• 全量回归命令：python -m pytest -q（保持 ≥ 132 passed / 100.00% 覆盖 / fail_under=99 红线不破）

5. 验收标准

1. python -m pytest tests/test_word_template_parser.py tests/test_rule_doc_parser.py tests/test_source_aggregator.py tests/test_real_samples.py -v 全绿
2. 全量回归 python -m pytest -q ≥ 132 passed（新增用例后 ≥ 现有基线 + 新增数）/ 100.00% 覆盖 / fail_under=99 达标
3. 真实样本：模板 docx 解析出 7 个 H1 章（はじめに…バッチ一覧）+ 占位符（section:* 与 doc_title）+ 1 个书签；记入规则 docx 产出 category="write" 的 markdown（Heading→#、・ 列表→- ）
4. 门面全量组装：StructuredSource.tables 非空、template 非 None、rule_docs 全部 category="write" 且 ≥2 条（记入规则 + 做成说明书）
5. 手工破坏验证（可选）：删除模板占位符段落 → 占位符断言变红；恢复正常

6. 影响面

• 新增生产文件 3 个：src/genesis/parsers/word_template_parser.py、rule_doc_parser.py、source_aggregator.py
• 新增测试文件 4 个：tests/docx_helpers.py（基建）、tests/test_word_template_parser.py、tests/test_rule_doc_parser.py、tests/test_source_aggregator.py
• 修改文件：tests/test_real_samples.py（追加 3 个 Word 样本用例）、_AI_USAGE_LOG.md（追加日志行）
• 提交纪律：分任务提交（feat/test/docs/chore 各自独立 commit）

7. 不做的事（YAGNI 最终确认）

• ❌ PPTXParser（3.3）— 无样本、无依赖，后续里程碑
• ❌ 现有系统代码/设计书探索（3.4/3.5）— CodeParser 未实现
• ❌ FileReader 统一读取层 — 现有 Excel 链不重构
• ❌ 完整样式定义 / LLM 规则分类 / 模型改动