fix(L2-A): generate_report.py docx ImportError → graceful skip

[Wool-xing]

范围

长期挂账 L2 baseline 三子项第 1 项: generate_report.py L23 from docx import Document 无 try/except, python-docx 未装时 ImportError → DAG node n7 fail → L2 通过率 <80% → CI fail。1 文件 +28/-4。

L2 baseline 三子项 (本 PR 仅 A)

子项	失败	本 PR
L2-A	generate_report.py ImportError 'docx'	修
L2-B	knowledge_base/server.py ImportError 'psycopg'	留下个 PR
L2-C	env-manager rollout n2 router 未跳过	留下个 PR

改动

def generate_test_report(data: Dict, output_path: str) -> str:
    try:
        from docx import Document
        from docx.shared import Pt, RGBColor
        from docx.enum.text import WD_ALIGN_PARAGRAPH
    except ImportError:
        logger.warning("python-docx 未安装, Word 报告跳过生成 (graceful skip)...")
        sentinel = Path(output_path).with_suffix(".skipped.txt")
        sentinel.write_text(
            "Word report generation skipped: python-docx not installed.\n"
            f"data summary: project={...} verdict={...} pass_rate={...}\n"
            "Install python-docx>=1.1.0 to enable full Word report.\n",
            ...
        )
        return str(sentinel)
    # 原逻辑
    doc = Document()
    ...

• DAG runner 视 exit 0 = 节点 success, 不再 fail
• 不静默装 docx (避免依赖膨胀)
• sentinel 文件含 data 摘要 + 装包提示, 用户看到不是"silently 跳过"

本地测试

sys.modules['docx'] = None  # mock import 失败
result = generate_test_report({'project_name':'test',...}, '/tmp/report.docx')
# WARNING log 打出
# returned: /tmp/report.skipped.txt
# 文件 utf-8 内容含 data 摘要

协作宪章 §1.3 六道闸自检 (f1-f6)

• a 静态: ✓ Ruff Passed + pre-commit
• b 副作用: ✓ generate_report 被 DAG node n7 调, 现 exit 0 不 fail (其他引用全文档级)
• c 跨层契约: ✓ 不动 SECURITY / charter / runtime
• d 实测: ✓ mock sys.modules['docx']=None 单测通过
• e 回归: ✓ docx 已装时走原逻辑不破
• f 诚实自检:
  • f1: 1 文件 +28/-4 (git diff stat) — H
  • f2: ✓
  • f3: ✓ docstring 明示 "依赖 python-docx (可选)", 不夸大
  • f4: ✓
  • f5: 见下
  • f6: 见下

置信度自检 (f5)

声明	证据	f5
docx ImportError 是 L2 fail root cause	gh run view 25815979436 log 含 ModuleNotFoundError: No module named 'docx' (L23 generate_test_report)	H
try/except 修法实现	git diff 可查	H
sentinel 文件 + warning 落地	本地测试输出	H
Ruff + pre-commit 通过	工具输出	H
CI L2 通过率 +1 节点	推断 (本 fix 只让 n7 不 fail, 其他节点状态不变)	M
整体 L2 通过率 ≥80% 达标	L2-B/L2-C 仍 fail, 本 PR 单独不够	L (需 L2-B/C 一起)

对外承诺仅基于 H, M/L 标注。

假阳性过滤 (f6)

唯一 finding = "generate_report.py docx ImportError":

#	问	答
1	真问题 / 误报?	真。gh run log 实证 stack trace 明指 L23
2	反例可证伪?	"把 python-docx 加 requirements" → 反驳: 强增依赖膨胀, graceful 更 Surgical, 用户主动装更明确意图。不证伪
3	修后实质变好?	是。CI L2 节点 n7 不再 fail; 用户缺包看到 warning + sentinel 比 stack trace 友好

假阳性候选数: 0

关联

• 长期挂账 L2 baseline 三子项第 1 项
• L2-B (psycopg) / L2-C (env-manager 跳过) 单独 PR 排队
• W4-5 (用户手动 install.sh 验证) 我跑不动 Windows, 留用户