返回板块

M04 doc style check落盘硬闸决策评估报告

2026-09-19行政法规 · 范式
源文件：C:/Users/xub/.workbuddy/spec/3.行政法规/范式/M04_doc_style_check落盘硬闸决策评估报告.md

文件编号：MASTER-RULE-ANNEX-D-001
版本：V1.0.0 ｜ 发布日期：2026-08-29 ｜ 状态：决策评估（待决策点确认后转接入方案）
评估对象：~/.workbuddy/_tools/doc_style_check.py（《MASTER RULE · 技术标准成文规范》自动判定器，V1.0.1 起提供）
决策问题：是否将 doc_style_check.py 设为「文档写入磁盘前的强制校验闸门」？

1 现状与问题

现有工具链闸门覆盖：

闸门 覆盖层 校验内容
check_deliverables.py 交付物层 命名合规、四件套齐全、内容非空白、版本一致
naming_audit.py 文件系统层 时间戳/连接符/版本号命名合规
expert_spec_gate.py / skill_upgrade.py::check_spec_gate 规范前置 无技术规范拒绝升级
assert_fourpiece.py 四件套断言 治理四件套齐全
doc_style_check.py（评估对象） 成文语义层 STD-A/B/C/D/E/F/G/H AUTO 条款（正文成文体例）

缺口：前四道闸门均不校验「文档正文怎么写」——成文体例（模态词、模糊词、图表编号、术语一致、交叉引用命中）此前无自动闸门，仅靠人工逐项勾选自检清单。doc_style_check.py 补上此层，但当前仅作为「按需调用」工具，未成为落盘前置强制步骤。

2 评估维度

2.1 利（收益）

# 收益 说明
L1 成文缺陷前置拦截 P1 类缺陷（模糊词、无主体责任人、图表重号、引用错位）在落盘前即检出，避免带病发布后返工
L2 消除人工逐项勾选的遗漏 自检清单 75 项中 AUTO 类（约 70%）机器判定，人工仅需复核 [MANUAL] 项（约 30%）
L3 基线保护可验证 STD-Z-005 基线 MD5 校验可纳入闸门，杜绝基线被篡改
L4 全域一致性 所有技术标准统一过同一成文闸门，防止「每份标准一套写法」漂移
L5 实测成熟度 对 W1 双模样本实测：md P1=P2=0；docx P1=0、P2=1（目次人工核对）——已具备拦截能力

2.2 弊（成本与风险）

# 风险 说明
D1 误判风险 判定器为正则/结构解析，存在语义盲区（引述豁免已缓解，但仍有边界）
D2 假阳性阻断正常发布 若一刀切硬闸，误判导致正常文档无法落盘，影响交付时效
D3 依赖 python-docx docx 判定依赖受管 venv 的 python-docx；环境缺失时需降级策略
D4 判定覆盖不全 当前实现覆盖 STD-A/B/C/D/E/F/G/H AUTO 约 40 项；STD-C-010 示例覆盖率、STD-Z 裁决等尚未纳入
D5 历史兼容 历史存量文档可能大量未过成文检查，若全量强制会阻塞历史归档/重排

2.3 误判风险评估（实测）

误判类型 缓解机制 残余风险
引述/反例误报 STD-D-011 引述豁免（60 字窗口） 低
代码块正则误报 代码块剥离（code_free） 低
md/docx 解析差异 结构化双模解析（load_md/load_docx） 低
载体例外 STD-A-009 范式源 md / README 豁免 低
范式/清单自检 STD-Z-006/007 适用边界豁免 低
图表说明句误判题注 排除 = 说明句 与 ； 结尾 低
阈值语义 C3 判定依赖基准表（BASE_THRESHOLDS 硬编码） 中（需人工复核边界）

结论：误判风险经「代码块剥离 + 引述豁免 + 结构化解析 + 载体/边界豁免」四重机制显著降低，实测 W1 双模样本无 P1 误判。残余风险集中于 C3 阈值语义边界（母规则基准表硬编码）与 STD-C-010 示例覆盖（尚未接入）。

3 回退方案

层级 回退动作 触发条件
R1 文档级 人工复核 --json 输出，确认误判后忽略该条 判定结果与人工判断不一致
R2 批量级 环境变量 DOC_STYLE_CHECK_BYPASS=1 临时放行（强制跳过） 紧急发布 / 环境异常
R3 规则级 新增豁免标记（如 <!-- stylecheck:skip STD-C-010 -->） 特定条款对特定文档不适用
R4 版本级 回滚 doc_style_check.py 至上一版本 判定器自身缺陷导致全量误报

4 推荐结论：分级灰度接入（先旗标后阻断）

不建议一刀切「全量强制阻断」；建议采取「分级灰度」接入：

文档类别 策略 说明
发布态技术标准 docx（四件套） 强制阻断 P1 不通过 → 拒绝落盘；P2 记录整改项限期闭环
工作态范式源 md / README 旗标提示 检出 P1 → 输出警告但不阻断落盘（人工确认后放行）
历史存量文档 不追溯 仅对新建/升版文档生效，存量按批次人工复核

理由：
1. 发布态 docx 是正式交付物，成文缺陷直接影响下游引用与权威性，值得硬闸拦截；
2. 工作态 md 是迭代载体，高频改动若强阻断会拖慢迭代节奏，旗标即可；
3. 历史存量强制回溯成本高、收益低，且可能误伤归档基线。

5 接入流程（若确认启用）

5.1 接入点（三处）

  1. 生成脚本内置：各 gen_*.py 在 save_doc/save_wb 前调用判定器：
    python from doc_style_check import check, load_doc doc, err = load_doc(out_path) res = check(doc, out_path) p1 = [r for r in res if r['level'] == 'P1' and not r['ok']] if p1: raise StyleGateError(f'成文检查 P1 阻断 {len(p1)} 项')
  2. CI 关卡：check_deliverables.py 增加 --style 开关，扫描后对发布态 docx 追加成文检查：
    bash python check_deliverables.py "F:/400.WorkBuddy_origin" --style # 追加成文检查
  3. 发布前门禁：发布 SOP（S06/S09）增加一步「成文闸门」，输出判定报告并归档。

5.2 失败处理策略

场景 处理
P1 命中 阻断发布，退回编制；定位到具体条款（STD-X-NNN）整改后重跑
P2 命中 放行但登记整改项（5 个工作日闭环），输出整改清单
判定器环境异常（python-docx 缺失） 降级为「跳过 + 警告」，不阻断（与 naming_audit hook 降级放行一致）
判定器自身缺陷（全量误报） 环境变量 BYPASS + 回滚版本（R2/R4）

6 待决策点（需拍板）

# 决策点 选项 我的建议
D1 发布态 docx 是否强制阻断？ A. 强制（P1 拒落盘）｜B. 旗标（警告不阻断）｜C. 不接入 A（强制）
D2 工作态 md 是否旗标？ A. 旗标提示｜B. 强制阻断｜C. 不接入 A（旗标）
D3 是否在 check_deliverables.py 增加 --style 开关？ A. 增加｜B. 不加（独立调用） A（增加）
D4 历史存量文档是否追溯？ A. 不追溯｜B. 批次复核 A（不追溯）
D5 STD-C-010 示例覆盖率与 STD-Z 裁决是否纳入闸门？ A. 纳入（需先扩展判定器）｜B. 后续版本再纳入 A（纳入，配合本轮任务 1/2 扩展）

7 验收标准

检查项 判定
评估报告含利/弊/误判风险/回退方案 ✅
推荐结论明确（分级灰度：发布态强制 + 工作态旗标） ✅
接入流程（生成脚本内置 / CI 开关 / 发布门禁） ✅
失败处理策略（P1 阻断 / P2 登记 / 环境降级 / 版本回退） ✅
待决策点 D1–D5 明确列出 ✅（待用户拍板）

8 修订记录

版本 修订日期 修订人 修订内容
V1.0.0 2026-08-29 全域文件治理工作组 & 技术标准委员会 首版发布：doc_style_check.py 落盘硬闸可行性评估（利/弊/误判/回退/推荐结论/接入流程/待决策点）

9 审批记录

角色 姓名 签字 日期
编制 全域文件治理工作组 & 技术标准委员会 2026-08-29
审核 （待定） 须于发布前完成
批准 （待定） 须于发布前完成
利衡辨 · 全域资料站 ｜ 全域七链元路由 · 一进一出
宪法 ＞ 基本法 ＞ 行政法规 ＞ 地方法规 ＞ 地方规章