定额提取器 · 自我进化版

把安装工程计价定额的源文件（Word 或 PDF）转化为结构化 JSON 定额数据库，供智能组价引擎查询。本技能会越用越聪明：踩过的坑、新格式、修法都会被记下来，同类型问题沉淀到专属小记忆文件，下次自动规避；攒够经验还能主动提议把规则写进技能本身（但要你点头才改）。

本技能只含「提取流程 + 工具脚本 + 进化机制」，不携带任何已提取的定额数据（JSON/MD/Excel 数据文件需自行准备源文件后生成）。

核心架构（务必先理解）

定额源文件
   │
   ├─① 前置文件判断（route.py，只读）──── 判【文件格式】+ 判【定额类型】+ 选提取脚本 + 指记忆文件
   │     · 文件格式：word / pdf-text / pdf-scan / unknown
   │     · 定额类型：consumption(消耗量) / pricing(计价) / unknown
   │       —— 同一本 PDF，消耗量(仅人/材/机消耗量) 与 计价(综合单价/人材机费) schema 完全不同，
   │          必须用不同解析器，绝不可混用（这是「基础数据错」的头号来源）
   │
   ├─② 格式×类型相关提取（只有这一步因格式/类型不同而不同）
   │     Word + 计价          ──→ quota_parser_v3.py
   │     PDF文本 + 消耗量     ──→ quota_parser_pdf_consumption.py（无框对齐表，按坐标聚类）
   │     PDF文本 + 计价       ──→ （缺，待补；可先转 Word 走 v3）
   │     PDF扫描 + *          ──→ 先 OCR → 对应文本型解析器
   │     产出：统一的 JSON 数据库（consumption / pricing 两种 schema，后处理自适应）
   │
   ├─③ 格式/类型无关统一后处理（postprocess.py，永远一致）
   │     validate(自适应) → generate_verify_md(自适应) → coverage_check(未识别内容探测，必跑)
   │       → generate_excel_v2(自适应) → (附录)
   │     产出：校验报告 + MD验证表 + 覆盖率报告 + Excel核对表 + 附录表
   │
   └─④ 可读数据库 + 人工复查 MD 验证表 + 覆盖率报告（交付物）

关键原则：除「提取代码」因文件格式不同而异，提取之后的所有处理代码完全一致，统一走 postprocess.py，避免同一逻辑多份实现导致的不一致。

消耗量定额 JSON 字段语义须知（避坑）

子目名称 name 视版面而定：江苏2026消耗量定额有两种子目名称呈现方式——
- 模式A（无「项目」标签，如机械/电气/工业管道册）：子目码行只列编码（如 编号 4-1 4-2 4-3），不印独立子目名称，名称即「节名」section_title，子目 name 字段留空（正确）。
- 模式B/C（有「项目」标签，如消防/热力/智能化/自控/通信/刷油防腐册）：编号 与 项目 之间常印独立子目名称行（如"数字化仪""钢结构炉架""膨胀式温度计"），解析器已捕获为子目 name 字段。
- 两种模式下 section_title 始终是节名；name 仅在有独立名称行时填充，勿把"name 为空"一律当漏抓。
spec 是描述性文本（保留原文，不转数值）：规格值可能是数值（0.3/≤250/δ0.05）、带前缀符号（≤ < ＞ δ φ ±）、或纯描述性文字（A0、A1 纸型、轻锈/中锈 锈蚀等级、电接点双金属 仪表类型、X-Y记录仪 设备名）。解析器按 x 坐标对齐子目列提取，完整保留原文（如 ≤250 不会丢成 250）。单位从 容量(kVA)/公称直径(mm以内)/锅炉蒸发量(t/h) 等规格表头/同行标签提取为 spec_unit。
真实无规格 ≠ 漏抓：同一节内按「类型」描述的子目（如互感器安装节中电压互感器按"三相/单相"）本就无数字规格，spec 留空属正常。判断标准：该节无任何规格行 → 真实无规格；有规格行但部分子目未对齐到 → 才是 bug。
覆盖率口径：coverage_check 的「子目覆盖率」只算子目编码是否抓全；spec缺失 含"真实无规格"，需结合上述口径解读，勿与"漏提子目"混淆。

⚠️ 自我进化闭环（每次必跑）

┌─ ① 加载经验（开工第一步，必做）
│     Read pattern_library.md（跨类型规律）
│          + experience_log.md（原始流水账）
│          + evolution/by-type/<route判出的类型>.md（同类型小记忆，自动加载）
│     → 历史经验与同类坑当场生效
│
├─ ② 执行提取 + 统一后处理（见下）
│
├─ ③ 记录经验（结束前必做）
│     Append 一条到 evolution/experience_log.md（只追加，不改历史）
│     → 写：遇到的新格式/新坑/修复 + 触发场景
│
└─ ④ 自我增强 + 复盘进化（按需触发，需用户确认才改文件）
      A. 同类型沉淀：把本次同类问题追加到 evolution/by-type/<类型>.md（小记忆，自动加载）
      B. 复盘进化：攒够经验后，把零散记录蒸馏成 pattern_library 新条目（P-xx）
         或修改 SKILL.md/脚本常量/正则 —— 列清单交用户确认后才写入

进化层文件： | 文件 | 角色 | 写入权限 | |------|------|----------| | evolution/experience_log.md | 原始流水账（只追加不改） | 每次任务结束自动追加（安全） | | evolution/by-type/<type>.md | 同类型小记忆（word / pdf-text / pdf-scan） | 同类问题自动追加（安全，仅增数据） | | evolution/pattern_library.md | 跨类型可复用规律精粹（P-01…） | 仅「复盘进化」经用户确认后更新 |

红线：经验流水账与同类型小记忆的「自动追加」是安全的（只增加数据）。但 pattern_library.md、SKILL.md 规则、脚本常量的改写，一律必须用户明确确认——本技能永不偷偷改自己。

第 0 步：加载经验（闭环①，必做）

开工前先读：

evolution/pattern_library.md —— 跨类型可复用规律（P-01…），解析时逐条对照。
evolution/experience_log.md —— 近期原始记录，留意「未决 / 待复盘」条目。
evolution/by-type/<类型>.md —— 由第 1 步 route.py 判出的文件类型对应的小记忆（类型 Word→word.md、PDF文本→pdf-text.md、PDF扫描→pdf-scan.md）。

若文件为空或缺失，按基线规律（已内置于 pattern_library P-01…P-12 与各 by-type 文件）执行，并在第 ③ 步补建。

第 1 步：前置文件判断（route.py，只读）

先跑判断程序，再决定怎么提——这是统一架构的入口，不要跳过。

python route.py <输入文件或目录>

它做四件事（只读、不写文件）：

判文件格式：word / pdf-text（含可提取文字层）/ pdf-scan（需 OCR）/ unknown。
判定额类型：扫描文本层是否含「综合单价」(计价) 或「消耗量」(消耗量)，给出 consumption / pricing / unknown；这是选对解析器的关键。
按 (文件格式, 定额类型) 矩阵给出推荐提取脚本（见第 ② 步），避免把消耗量 PDF 误送计价解析器。
指出本次应加载的同类型记忆文件 evolution/by-type/<格式>.md 与 evolution/by-type/<定额类型>.md。

PDF 文本层探测优先用 pypdf，其次 PyPDF2；两者皆缺时退化为「扩展名分类 + 人工确认」。定额类型探测缺 python-docx 时 .doc 退化为 unknown 并提示人工确认。目录输入会汇总各子文件格式/类型计数。

第 2 步：解析入库（格式×类型相关，只有这一步不同）

选哪条路线由第 ① 步 route.py 的 (文件格式, 定额类型) 决定，不要凭经验硬选。 消耗量 PDF 与计价 PDF 的 schema 完全不同，选错解析器 = 基础数据整批错。

消耗量定额 PDF（江苏 2026 等） — scripts/quota_parser_pdf_consumption.py：

python quota_parser_pdf_consumption.py <pdf路径> [输出json]

按坐标聚类解析无框对齐表（消耗量定额仅有人工/材料/机械的"消耗量"，无综合单价）。要点：子目编码行 1-x 多子目共享一张明细表、消耗量按 x 对齐到子目列（缺列补0）；段归属用单位判定（工日→人工、台班→机械、其余→材料）；跨页续表合并去重；章名跨页继承（章节分隔页无表也能传到表页）。解析时对照 by-type/pdf-text.md 与 by-type/consumption.md。

Word 版（计价定额） — scripts/quota_parser_v3.py：

python quota_parser_v3.py <输入目录或文件>

自动完成 .doc→.docx 转换、按章节解析、主表+续表合并，输出 JSON + Markdown。解析时对照 pattern_library.md 的 P-08~P-11 与 by-type/word.md。

PDF 计价版 / 扫描件：当前无现成解析器（待补）。文本型可先转 Word 走 v3；扫描件先 OCR 再走对应文本型解析器。

无论哪条路线，产出的 JSON 数据库有 consumption / pricing 两种 schema，第 3 步统一后处理对两者都自适应消费。

第 3 步：统一后处理（postprocess.py，格式无关，永远一致）

提取得到 JSON 后，一律走统一后处理入口，不再按来源格式分流：

python postprocess.py <json_path> [--appendix]

依次执行（全部只看 JSON + 源 PDF，与来源格式/类型无关，validate/excel/verify 内部按 quota_type 自适应）：

validate_data.py —— JSON 完整性校验（权威门禁；消耗量查空子目/qty/编码，计价查费用一致性；有「存在问题」时退出码为 1）。
generate_verify_md.py —— 生成逐条 MD 验证表 <stem>_verify.md，供人工复查。
coverage_check.py —— 未识别内容探测器（必跑）：重扫源 PDF，把子目码/明细码/表头与 JSON 做差集，输出 覆盖率 + 漏提子目清单 + 空子目 + qty异常 + 规格缺失。覆盖率 < 100% 即代表基础数据不完整，必须回到第 ② 步修解析器或人工补漏，绝不可带着缺口交付。
generate_excel_v2.py —— Excel 核对表（消耗量：子目总览 + 每章人/材/机明细；计价：原 V2 表）。
generate_appendix_excel.py —— 附录表（仅 --appendix 且附录源可用时；缺省跳过）。

第 4 步：产出规范（交付物）

每次运行必须产出三类可复查物：

智能体可读的数据库（JSON）
- 经 validate_data.py 通过才标记为「已校验」，schema 固定（consumption：章节→节→子目→人/材/机明细；pricing：章节→节→子目→四类明细），智能体读取不会出错。
- 命名建议 book{NN}_db.json，另附 book{NN}_verify.md 供 AI 阅读。
人工复查 MD 验证表（generate_verify_md.py 产出）
- 消耗量逐条表格：编码 | 规格 | 单位 | 人工(条) | 材料(条) | 机械(条) | 来源页 | 校验。
- 计价逐条表格：编码 | 名称/规格 | 单位 | 综合单价 | 人工费 | 材料费 | 机械费 | 校验。
- 使用者据此一目了然地复查，发现漏提/错提。
覆盖率 / 未识别内容报告（coverage_check.py 产出 book{NN}_coverage.md/.json）
- 这是「未能成功识别的内容」的唯一显式出口：子目覆盖率、漏提子目(附页码)、空子目、qty异常、规格缺失、有表头但0解析的页。
- 交付前必看：覆盖率必须 100%（或经人工确认的所有缺口均已记录），否则基础数据不完整。

第 5 步：记录经验（闭环③，必做）

任务结束前，往 evolution/experience_log.md 追加一条（格式见该文件头部）：

## [YYYY-MM-DD] 来源/版本/册名 — 一句话结论
- 遇到的情况：新格式 / 解析异常 / 修复动作
- 根因：……
- 处理/修复：……（含正则、分档取法、回退逻辑）
- 是否沉淀：已进 by-type/<type>.md（条目#）/ 已进 pattern_library（P-xx）/ 待复盘 / 悬而未决
- 触发词或场景：……

这一步是「自我进化」的燃料。即使顺利也建议记录「本册特征 / 特殊格式 / 哪些规律被验证」。

第 6 步：自我增强模块（闭环④，按需触发，需确认）

A. 同类型问题自动沉淀（核心防再犯机制） 把第 ⑤ 步记录的问题，按文件类型追加到 evolution/by-type/<type>.md（小记忆）。下一次 route.py 判出同类型时，第 0 步会自动加载这份记忆，同类错误直接规避。记忆文件只追加、不删历史。

B. 复盘进化（规则升级） 当 experience_log.md / by-type/*.md 积累了多条「待复盘 / 悬而未决」，或你主动说「定额经验复盘 / 技能进化」时：

汇总近期记录，挑可复用的共性问题。
把零散记录蒸馏成 pattern_library.md 的新条目（P-xx，带编号/场景/规律/陷阱/来源）。
若需改 SKILL.md 规则 / 脚本常量 / 正则，整理成修改清单，逐条说明影响。
呈现给用户，用户明确确认后才写入。
技能规则/脚本有实质改动时，version 按语义化版本自增（文案 PATCH / 新增兼容 MINOR / 破坏结构 MAJOR）。

复盘产出是「建议 + 确认」，不是「自动改写」。技能越用越聪明，但每一次自我修改都经你把关。

工具脚本速查

| 脚本 | 作用 | 阶段 | |------|------|------| | route.py | 前置判断：判文件格式 + 判定额类型 → 按矩阵选提取脚本 → 指记忆文件（只读） | ① 前置 | | quota_parser_v3.py | Word 计价定额 → JSON + Markdown（入库主力） | ② 提取(Word/计价) | | quota_parser_pdf_consumption.py | 消耗量定额 PDF → JSON（按坐标聚类，无框对齐表） | ② 提取(PDF/消耗量) | | quota_parser_v2.py | 旧版计价 PDF 分条思路参考（当前未接入主路线） | ② 参考 | | parse_quota_word_v6.py | Word 源 vs JSON 100% 对比验证 | ② 提取后校验(Word) | | postprocess.py | 统一后处理编排：校验+MD表+coverage+Excel+附录（schema 自适应） | ③ 后处理 | | generate_verify_md.py | JSON → 逐条 MD 验证表（人工复查，自适应） | ③ 后处理 | | coverage_check.py | 未识别内容探测器：重扫 PDF 算覆盖率+漏提/空子目/异常（必跑） | ③ 后处理 | | generate_excel_v2.py | JSON → Excel 核对表（消耗量/计价自适应） | ③ 后处理 | | generate_excel.py | Excel 核对表（旧版参考） | ③ 参考 | | generate_appendix_excel.py | 附录表 → Excel（独立 sheet，可选） | ③ 后处理 | | validate_data.py | JSON 完整性校验（消耗量/计价自适应，权威门禁） | ③ 后处理 |

依赖：python-docx（Word 解析）、openpyxl（Excel 生成）、win32com（Windows 上 .doc 转换）、pypdf/PyPDF2（PDF 文本探测，可选）。首次运行缺包会提示安装。

注意事项（已沉淀为 P-01…P-18，详见 pattern_library.md 与各 by-type 文件；其中 P-13…P-18 为消耗量定额专属规律）

分档以定额实际数据为准（P-01），不联网硬编码分档表。
辅助函数必须顶层定义（P-02），匹配逻辑在 if/elif 链内。
编码跳号发 WARN 不报 ERROR（P-03），与原文空位一致。
材料明细表会覆盖主费用表（P-04），用 has_fee_rows 过滤。
附录表必须与子目表分割（P-05），否则误当子目。
同设备不同子类型 spec 格式可能完全不同（P-06），需兼容多格式并回退。
定额库独立性（P-07）：省级与企业定额严格独立存储互不引用。
通用主表表头自适应（P-08）、括号/全角处理（P-09）、四类明细并列（P-10）、续表合并去重（P-11）、校验三对齐（P-12）。

绝不做什么（安全红线）

绝不无确认自改技能文件：pattern_library.md、SKILL.md 规则、脚本常量的任何修改，都必须用户明确确认后才执行。
绝不重复实现后处理逻辑：提取之后一律走 postprocess.py，不为某格式/类型另写一份校验/出表逻辑（脚本内部按 quota_type 自适应即可）。
绝不靠联网硬编码分档：分档值一律从定额原文读取。
绝不跨库互引：省级/企业/不同版本定额各自独立存储。
绝不把附录表当子目：附录必须隔离解析。
绝不把消耗量 PDF 误送计价解析器（反之亦然）：第 ① 步 route.py 必须按 (文件格式, 定额类型) 选解析器；选错 = 基础数据整批错。
绝不在覆盖率 < 100% 时交付：coverage_check.py 是未识别内容的唯一显式出口，缺口必须修复或经人工确认并记录，否则基础数据不完整。
绝不丢弃无法识别的 spec/明细：识别失败返回原始串/记 WARN，交由经验层与 coverage 报告后续处理。