提取清单汇总
用途
给定一个工程资料文件夹（内含多个计价软件导出的 .xls/.xlsx 单位工程文件），把每个文件里的「分部分项工程量清单计价表」明细行提取出来，汇总为一个新工作簿并去重合并。计价软件常按扩大单位（100m2 / 10m3 / 10樘…）输出，本技能默认把计量单位统一折算为自然单位、工程量按系数同步换算（源单位/源工程量另列备查），使不同单位工程之间的同名清单项可直接合并与比对。源文件只读，绝不修改。
触发方式
用户给出一个文件夹路径并说「提取清单汇总」（或类似表述）时，直接开始处理，不需要逐项确认。仅当用户提出与默认口径不同的要求（如不去重、不折算单位）时才调整参数。
执行流程
1. 环境准备
- 使用当前环境的托管隔离 Python；依赖：
xlrd（读 .xls）、openpyxl（读 .xlsx / 写结果）。缺失时用该环境的 pip 安装，不要全局安装 - 本技能自带
scripts/extract_bill.py，用os.path.dirname(__file__)定位，与安装路径无关
2. 运行脚本
"<当前环境的 Python>" "<本技能目录>/scripts/extract_bill.py" "<目标文件夹>"
参数：
| 参数 | 说明 |
|---|---|
| （默认） | 输出到目标文件夹根目录，命名 <文件夹名>-分部分项清单汇总.xlsx；总表去重合并；计量单位折算为自然单位 |
--keep-expanded-unit |
关闭折算，保留源表原样的扩大单位（100m2 等），同时不生成溯源列 |
--decimals <n> |
折算后工程量保留小数位，默认 4 |
--no-merge |
不去重，全部保留明细行（带专业/单位工程列） |
--out <路径> |
指定输出文件路径 |
--sheet-keyword <关键字> |
定位分部分项表的关键字，默认「分部分项」 |
3. 运行口径（已固化在脚本内）
折算、去重、精度、明细行判定等业务逻辑均固化在 extract_bill.py 中，直接运行即可，不需要也不要在对话中重写这些逻辑。需要了解的运行行为：
- 脚本自动跳过
~$临时文件和自身产物（-分部分项清单汇总.xlsx结尾的文件） - 无分部分项表的文件（如「单项工程招标控制价汇总表」类纯汇总页）自动跳过，属正常行为，防止上下级文件重复计量，不要用
--sheet-keyword硬塞进来 - 折算过的明细行会追加「源计量单位 / 源工程量」溯源列，这是事后核账的依据
- 脚本运行结束会打印：扫描文件数、明细行数、折算统计、工程量合计校验结果——照抄进汇报即可
4. 结果汇报
向用户报告：扫描的文件数与跳过原因、明细行数 → 合并后行数、跨单位工程重复组数、计量单位折算统计、工程量合计校验结果、输出文件路径（用 present_files 交付）。
付费契约（PAYSKILL，支付宝 AI 按量付费 / A2M）
本技能为付费技能，调用遵循支付宝 AI 按量付费契约，由平台调度层执行 probe → pay → complete → ack 流程，付费闸口位于 scripts/payment_gate.py：
- probe（探测）：闸口先检查本地权益缓存
.pay_cache/state.json（24h 幂等窗口），已持有有效付费凭证则直接放行 - 402 Payment-Needed（账单下发）：未付费时，闸口请求计费端点（环境变量
PAY_ENDPOINT），端点返回 HTTP 402 与Payment-Needed头（含订单号、商户、金额、RSA2 签名、支付宝支付链接/二维码），闸口原样输出，平台据此唤起支付宝完成付费（pay） - complete（扣费确认）：用户在支付宝完成扣费，平台下发
Payment-Proof付费凭证 - ack（验签放行）：闸口携带 Payment-Proof 重试计费端点，服务端验签确认到账后签发 Entitlement 权益令牌，闸口验签、记录履约回执（ack）并放行主流程
- 订单持久化与幂等：权益与已消费凭证持久化在
.pay_cache/state.json；同一 Payment-Proof 在 24h 幂等窗口内仅生效一次，避免重复扣费
运行行为：extract_bill.py 入口自动执行 ensure_paid()；未付费调用以退出码 402 终止并输出账单，已付费正常执行。环境变量 PAY_ENDPOINT 未配置时闸口不启用，技能以未计费模式运行。
边界与注意
- 源文件一律只读；汇总文件默认生成在目标文件夹根目录下，重名时直接覆盖，必要时先告知用户
- 若某文件结构特殊导致提取 0 行，先人工查看其表头结构，再决定是否调整
--sheet-keyword - 输出仅为工程量清单汇总，不含金额与定额分析；结果请以人工复核为准
免责声明
本技能为辅助工具，输出结果供工程造价汇总参考，使用前请自行核对。作者不对因使用本工具产生的直接或间接损失承担责任。
