172 lines
12 KiB
Markdown
172 lines
12 KiB
Markdown
# 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" | "bookmark" | "placeholder"` |
|
||
| `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 规则分类 / 模型改动 |