diff --git a/_AI_USAGE_LOG.md b/_AI_USAGE_LOG.md index 7d19e93..c951923 100644 --- a/_AI_USAGE_LOG.md +++ b/_AI_USAGE_LOG.md @@ -68,3 +68,4 @@ | 2026-08-10 | Agent 实现 | Phase3 Task4 实现:SourceParser 门面全量输入聚合。新建 src/genesis/parsers/source_aggregator.py(角色显式传参无隐式猜测;requirements 校验 .xlsx/.xls 后缀聚合 tables/comments;template 校验 .docx 用 WordTemplateParser 解析;write_instruction+rule 校验 .docx 按 category='write' 归入 rule_docs;不存在抛 FileNotFoundError、未知扩展名抛 ValueError('不支持的文件类型: ...');image_analyses=[]/existing_system=None 固定)与 tests/test_source_aggregator.py 按 brief 6 用例 + 补 4 用例(模板未知扩展名、规则路径文件缺失、requirements/规则无扩展名兜底 '无扩展名' 文案,覆盖 51/62 行缺失与 or 表达式分支)达 100%;TDD 验证 RED(ModuleNotFoundError: No module named 'genesis.parsers.source_aggregator')→ GREEN(聚焦 10 passed);pytest 全量 156 passed 覆盖 100.00%(929 stmts/236 br),fail_under=99 达标 | src/genesis/parsers/source_aggregator.py, tests/test_source_aggregator.py, _AI_USAGE_LOG.md | deepseek-v4-flash-free | | 2026-08-10 | 测试验证 | Phase3 Task5 实现:真实样本 Word 解析集成测试。tests/test_real_samples.py 追加 4 用例(保留现有 4 个 Excel 用例与 _x 辅助):模板→7 H1(はじめに…バッチ一覧)+section:introduction/doc_title 占位符+template_start 书签;记入規則→category=write/file_type=word/# 1. 機能一覧の書き方/- 機能ID は F001 から連番で付与する。(・前缀双通道检测);做成説明書→category=write/# 2. 機能一覧;全量组装→tables 非空+template 非空+rule_docs==2 且全 write;聚焦测试 8 passed 无 skip;pytest 全量 160 passed 覆盖 100.00%(929 stmts/236 br),fail_under=99 达标 | tests/test_real_samples.py, _AI_USAGE_LOG.md | deepseek-v4-flash-free | | 2026-08-10 | 测试验证 | Phase3 Word 解析最终评审收尾:3 文件补尾随换行、test_real_samples import 排序、SourceParser docstring 契约优先级注释 | src/genesis/parsers/source_aggregator.py, tests/test_source_aggregator.py, tests/test_real_samples.py, _AI_USAGE_LOG.md | deepseek-v4-flash-free | +| 2026-08-10 | 测试验证 | Phase3 Word 解析里程碑评审报告:docs/milestone3-word-parser-review.md(5 任务 task review 全 Approved + 最终 whole-branch review With fixes 闭环;160 passed / 100.00% 分支覆盖 929 stmts/236 br;Pre-Flight 裁决 3 项 + 覆盖补齐 4 项记录;deferred 遗留 6 项移交后续) | docs/milestone3-word-parser-review.md, _AI_USAGE_LOG.md | deepseek-v4-flash-free | diff --git a/docs/milestone3-word-parser-review.md b/docs/milestone3-word-parser-review.md new file mode 100644 index 0000000..5be6985 --- /dev/null +++ b/docs/milestone3-word-parser-review.md @@ -0,0 +1,77 @@ +# 里程碑 3.5(Word 解析优先)评审与交付报告 + +- 日期:2026-08-10 +- 状态:**通过**(5 任务逐项 task review 全部 Approved + 最终 whole-branch review With fixes 已闭环) +- 关联文档:`docs/superpowers/plans/2026-08-09-phase3-word-parser.md`、`docs/superpowers/specs/2026-08-09-phase3-word-parser-design.md`、`docs/api-design.md`(§2.2)、`docs/rag-layer-design.md`(§1.1) + +## 一、交付内容 + +新实现 3 个解析模块 + 1 个共享 helper + 测试基建 + 真实样本集成测试,共 28 个新增测试用例(当前全量 **160 passed / 100.00% 分支覆盖**),7 个提交: + +| 任务 | 提交 | 说明 | +|------|------|------| +| 计划修订(Pre-Flight 裁决) | `7bc9175` | Task 1 前缀 `chore:`→`test:`;`_heading_level` 重复定义→提取共享 `_word_common.py`;兜底分支测试补齐 | +| Task 1 docx 测试基建 | `e8771aa` | `tests/docx_helpers.py`:`new_document`/`save_document`/`make_rule_doc`(与 `tests/excel_helpers.py` 对称) | +| Task 2 WordTemplateParser | `00fcbf1` | `_word_common.py`(`heading_level` 共享 helper)+ `word_template_parser.py`(章构成/占位符/书签/样式名提取) | +| Task 3 RuleDocParser | `9ab11da` | `rule_doc_parser.py`:Markdown 化 + 列表双通道检测 + GFM 表格 + sha256 hash | +| Task 4 SourceParser 门面 | `7f29cc9` | `source_aggregator.py`:显式角色参数路由全量输入 → `StructuredSource` | +| Task 5 真实样本集成测试 | `16921ec` | `test_real_samples.py` 追加 4 个 Word 样本端到端用例 | +| 最终评审收尾 | `31167c9` | 3 文件补尾随换行 + import 排序 + SourceParser 契约优先级注释 | + +## 二、验收结论 + +| 验收项 | 结论 | +|--------|------| +| WordTemplateParser 章构成(H1 大纲级别) | ✅ 模板样本 7 个 H1(1.はじめに…7.バッチ一覧)全命中 | +| 占位符提取(封面型 `{{doc_title}}` / section 型 `{{section:xxx}}`) | ✅ 统一正则,样本 `section:introduction`/`doc_title` 命中 | +| 书签提取(bookmarkStart) | ✅ 样本 `template_start` 命中(含无 name 兜底分支覆盖) | +| 样式名级提取 `{defined, used}` | ✅ 空文档不崩溃,样式名去重排序 | +| RuleDocParser Markdown 化 | ✅ Heading→#、列表→`- `、表格→GFM(含 `\|` 转义)、空段→空行 | +| 列表双通道检测(List 样式 OR ・/-/• 前缀) | ✅ 真实样本「・前缀 Normal 样式」命中(spec §3.3) | +| hash = 文件内容 sha256 hex | ✅ 64 位 hex,稳定 | +| SourceParser 显式角色参数(对齐 api-design file_type) | ✅ requirements/template/write_instruction/rules 四角色 | +| 规则分类按来源映射 category=write(零 LLM) | ✅ 做成说明书与记入规则均 write(api-design §2.2 Type A) | +| 错误处理 FileNotFoundError / ValueError 未知扩展名 | ✅ 两契约各有测试 | +| 全量组装 StructuredSource(tables/template/rule_docs/image_analyses/existing_system/comments) | ✅ 真实样本 4 输入端到端通过 | +| 覆盖率红线 | ✅ **160 passed / 100.00%**(929 stmts / 236 br,branch=true),fail_under=99 达标 | +| 既有代码零改动 | ✅ `excel_parser.py`/`data_models.py`/`pyproject.toml`/既有测试全程未触碰 | + +## 三、Pre-Flight 裁决与执行偏差(均已获用户批准) + +1. **Task 1 提交前缀**:Global Constraints 规定 `feat:/test:/docs:`,Task 1 原计划 `chore:` → 用户裁决改用 `test:`。 +2. **`_heading_level` 重复定义**:Task 2/3 各写一份相同函数(review rubric 视 verbatim duplication 为缺陷)→ 用户裁决提取共享 helper `_word_common.py`,Task 2 新建、Task 3 复用。 +3. **覆盖率补齐**(branch=true 刚性要求): + - Task 2:bookmark 用例内追加无 name 元素,命中 `if name:` 假分支(8 用例不变); + - Task 3:`test_parse_empty_document` 补 `doc.add_paragraph("")`,命中空段→空行分支(6 用例不变); + - Task 4:brief 6 用例外补 4 个用例(模板未知扩展名、规则路径缺失、两处无扩展名兜底),各对应一个不可达分支(全量 156 替代计划 152;Task 5 基线随之调整,最终 160)。 +4. 上述补齐均经 task reviewer 裁定为「合法最小覆盖」非 scope creep。 + +## 四、最终评审发现与修复(闭环) + +最终 whole-branch review(`7bc9175..16921ec`)结论 **With fixes**,无 Critical/Important;Minor 收尾已一次 commit 闭环: + +1. **缺尾随换行 ×3**(合并前置硬性项):`source_aggregator.py`/`test_source_aggregator.py`/`test_real_samples.py` 末字节补 `\n`。 +2. **import 排序**:`test_real_samples.py` 新增导入改为字母序(rule_doc → source_aggregator → word_template_parser)。 +3. **契约优先级注释**:`SourceParser.parse` docstring 注明「扩展名校验先于存在性校验」。 + +## 五、移交下个里程碑的遗留记录(deferred) + +1. **`ParsedTemplate.sections` 跨类型顺序无保证**:bookmark marker 一律追加在 heading/placeholder 之后,与 DOM 实际位置无关。当前 `src/` 无任何消费者读取 `sections`(grep 验证),无实际影响;建议 Writer 里程碑落地时改为单遍 DOM 顺序合并或在 `ChapterMarker` 补位置字段(spec 显式规定)。 +2. **无法打开异常无显式测试**:WordTemplateParser 依赖「不捕获即透出」的隐式保证;建议补一例 `tmp_path/"missing.docx"` 断言抛异常,防未来误加 try/except。 +3. **RuleDocParser 双读文件**:`Document(str(path))` 与 `read_bytes()` hash 各读一次;可合并为 `data = read_bytes()` → `Document(io.BytesIO(data))`,微优化非必须。 +4. **函数体内 import**:`rule_doc_parser.py` 循环内 `from docx.text.paragraph import Paragraph` / `from docx.table import Table`,纯风格可提至模块顶部。 +5. **扩展名/存在性校验优先级重叠**:不存在的文件若扩展名未知 → `ValueError` 而非 `FileNotFoundError`(计划既定顺序,docstring 已注明)。 +6. 后续迭代(非本里程碑范围):PPTXParser(补样本 + python-pptx)、ExistingSystemExplorer(补 Java 样本 + CodeParser)、Excel 图表规则解析(図表規則.xlsx → design/write)。 + +## 六、测试证据 + +- 全量:`python -m pytest` → **160 passed in ~5.9s**,覆盖率 **100.00%**(929 stmts / 236 br),fail_under=99 达标 +- 真实样本端到端:模板 7 H1 + 占位符 + 1 书签 / 記入規則 write + markdown / 做成説明書 write / 4 输入全量组装(tables 非空 + template 非空 + rule_docs==2 全 write),0 skip +- 每任务独立 commit,逐项 task review 均 Approved(含 spec 合规 + 代码质量双裁决) + +## 七、合规自查 + +- `excel_parser.py`/`data_models.py`/`pyproject.toml`/既有测试全程未改动 +- 交流统一中文、标识符英文、commit 前缀 `feat:/test:/docs:/chore:` 规范 +- 每次修改均追加 `_AI_USAGE_LOG.md`(范式步骤:架构设计/Agent 实现/测试验证) +- 零真实网络(无 LLM 调用);未上传任何客户/公司数据;API Key 未在源码中出现