settlement-workflow-orchestrator

工程结算资料一键整理 Codex Skill 套件。当前发布版本：V2.0。

V2.0 不向后兼容 V1.0 的方案文件。旧项目要复跑时，先使用 orchestrator reinit 重新生成 origin manifest，再重新生成 Stage 2-5 方案。

V2.0 定位

V2.0 把原来的“每阶段确认后改真实文件”改为 manifest 虚拟链：

• Stage 1 init：扫描 1.基础资料收集/，生成 _manifest_origin.json。
• Stage 2-5 plan：只生成版本化方案 HTML、报告和 dry-run manifest，不复制、不移动、不提取 PDF。未标版视为第01版；后续输出写 _第02版、_第03版。
• final-apply --approved：在 Stage 5 方案人工确认后，一次性物化最终归档目录。
• Stage 6 ocr：在 final-apply 成功后，只在 6.关键材料OCR/ 写派生 OCR Markdown、_ocr_manifest.json、index.jsonl、progress.jsonl 和 _engine_responses/，不改原始资料或归档 PDF。
• Stage 7 summarize：在 Stage 6 OCR 后，只在 7.关键材料摘要/ 写 Agent 摘要任务包、worker result、_summary_manifest.json、进度和汇总摘要；摘要字段由 Codex/Claude Code worker 智能阅读 OCR 后编制，不由脚本做规则抽取。
• Stage 8 audit：在 Stage 7 汇总摘要后，只在 8.审核问题清单/ 写 Agent 审核任务包、审核结果、问题清单.md、_audit_manifest.json、_audit_coverage.md 和进度；默认是一个完整项目通盘审核任务，问题判定由 Codex/Claude Code 审核专家按汇总摘要和审计规则库智能完成，不由脚本做规则判题。Stage 8 另有独立 audit-special 专项表工作线，写 漏项及未结算专项检查表*.md，不进入 audit manifest。

唯一真实物化入口是总控：

./orchestrator final-apply --project "<project_root>" --approved

子 Skill 的 apply 已在 V2 禁用，不要直接调用。

目录结构

project_root/
  workflow.config.yaml
  progress.md
  _manifest_origin.json
  _apply_log.json
  1.基础资料收集/
  2.重命名PDF/
  3.费用凭证归类/
  4.五项关键材料/
  5.概算归档/
    概算大类文件夹/
  6.关键材料OCR/
  7.关键材料摘要/
  8.审核问题清单/

1.基础资料收集/ 是唯一原始资料池，V2 全流程不会修改它。最终归档根目录默认是 5.概算归档/概算大类文件夹/。

快速开始

1. 把 references/workflow.config.example.yaml 放到项目根目录，命名为 workflow.config.yaml。
2. 把基础资料放入 1.基础资料收集/。
3. 校验配置：

./orchestrator validate --project "<project_root>"

4. 生成 origin manifest：

./orchestrator init --project "<project_root>"

5. 生成 Stage 2-5 虚拟方案：

./orchestrator plan --project "<project_root>" --all

6. 审阅 5.概算归档/ 下最新版本 _概算大类归档方案*.html，确认后把人工确认行改为：

人工确认: 同意执行 <码>

7. 最终物化：

./orchestrator final-apply --project "<project_root>" --approved

8. 对已物化归档 PDF 做整篇逐页 OCR：

./orchestrator ocr-preflight --project "<project_root>"
./orchestrator ocr-batch --project "<project_root>" --resume

兼容旧单进程入口：

./orchestrator ocr --project "<project_root>" --resume

9. 生成 Stage 7 摘要 worker 任务，并在 worker 完成后汇总：

./orchestrator summarize --project "<project_root>" --resume --agents 4

Stage 7 是 Agent-native：总控和脚本只负责列任务、校验和汇总；每个费用子文件夹的摘要由 Codex/Claude Code worker 按 child_skills/summarize-key-materials/SKILL.md 读取 Stage 6 OCR Markdown 后编制。

10. 生成 Stage 8 完整项目审核任务，并在主复核结果完成后生成问题清单：

./orchestrator audit --project "<project_root>" --resume

Stage 8 是 Agent-native：总控和脚本只负责列任务、校验、覆盖率和最终写表；默认任务读取完整 Stage 7 汇总摘要和审计规则库，覆盖全部审核条目并允许跨费用、跨材料通盘判断。_summary_manifest.json 只作为机器流程资料，用于枚举审核条目、校验 fee_key、排序、覆盖率和路径追踪，不作为业务事实来源。若使用独立 subagent 初审，初审结果写 review_role=initial_subagent；主对话独立复核后写 review_role=main_final，最终三列表格 问题清单.md 只从 main_final 结果生成。

生成 Stage 8 漏项及未结算专项检查表任务，并在独立 subagent 完成后校验：

./orchestrator audit-special --project "<project_root>" --resume

专项表读取同一份 Stage 7 汇总摘要和专项填表规则，覆盖全部真实费用子项和 未发生 概算占位。它是人工辅助检查表，不进入 _audit_manifest.json、问题数或 must-catch 覆盖率。

查看状态：

./orchestrator status --project "<project_root>"

强制重算原始台账：

./orchestrator reinit --project "<project_root>"

Manifest 链

• _manifest_origin.json：原始文件台账，file_id = f_ + sha256 前 12 位。
• 2.重命名PDF/_dry_run_manifest*.json：rename 虚拟操作。
• 3.费用凭证归类/_dry_run_manifest*.json：move_to_category 虚拟操作。
• 4.五项关键材料/_dry_run_manifest*.json：reference、extract_pages 和缺失资料清单。
• 5.概算归档/_dry_run_manifest*.json：archive_to_budget 和整合后的缺失资料清单。
• _apply_log.json：final-apply 的实际源文件、目标路径、状态和失败信息。
• 6.关键材料OCR/_ocr_manifest.json：Stage 6 派生 OCR 交接清单，回溯 origin f_* → final-apply PDF → OCR Markdown。
• 7.关键材料摘要/_summary_manifest.json：Stage 7 Agent 摘要交接清单，回溯 Stage 6 OCR Markdown → 费用子文件夹摘要 → 全项目汇总摘要。
• 8.审核问题清单/_audit_manifest.json：Stage 8 Agent 审核交接清单，回溯 Stage 7 汇总摘要 → 命中规则/证据 → 问题清单条目。

总控、status/progress 和 final-apply 自动选择每个 Stage 的最新版本 manifest；若没有版本化文件则兼容旧 _dry_run_manifest.json。所有方案 HTML 不再内嵌执行 JSON；执行依据只来自独立 manifest。

Stage 4 首页 OCR 默认 ocr_policy=auto、ocr_threshold=100：常规匹配和去重后，疑似委托依据/合同候选少于阈值时自动 OCR；达到阈值时不写新方案和 manifest，但会写同版 OCR首页备份_第NN版/ 预检索引并等待确认。实际 OCR 也会在该目录留存 index.html、index.jsonl、progress.jsonl、单页 PDF、GLM 返回 JSON、OCR Markdown、决策 JSON 或失败文本。密钥只从环境变量或 env_file 读取；Stage 4 未显式配置 env_file 且总控 Skill 根目录存在 .env.local 时，总控会自动传递该文件路径给子 Skill。

Stage 2 扫描版明细账可在 detected.ledger_paths 指定多份 PDF。stage2.mode: "pdf-ledger" 时，总控调用 Stage 2 多 PDF OCR 流程：每份明细账分别在 2.重命名PDF/01_明细账OCR/ 下生成 OCR Markdown、原始返回和 Excel，再把多个 OCR Excel 合并为同一次核对输入；最终 异常报告*.md、重命名方案*.html、_dry_run_manifest*.json 保持在 2.重命名PDF/ 顶层。Stage 2 OCR 密钥只从环境变量或 Skill 根目录 .env.local 注入子进程环境，不出现在命令行。

Stage 5 概算大类归档默认把概算 PDF 送云端 GLM-OCR 解析；未显式配置 stage5.env_file 且总控 Skill 根目录存在 .env.local 时，总控会自动传递该文件路径给子 Skill。stage5.ocr_md_file 只允许离线测试或用户明确要求使用人工/本地 OCR Markdown 时配置，并且必须同时设置 stage5.allow_offline_ocr_md: true；否则总控和子 Skill 都会拒绝执行，避免擅自绕开云端 GLM-OCR。Stage 5 中带系统建议的人工确认项，如果用户没有明确写出修改、删除或改目标意见，空白意见默认采用建议并进入 archive_to_budget operations；虚拟目录树、拟定文件夹结构、manifest 和 final-apply 都以同一套归档结果为准。

Stage 6 OCR 默认使用批次调度：先执行归档目录与 _apply_log.json 前置核对，再生成 _batch_plan.json，每批默认 2 个 worker，允许 1-4；遇到 429 或连接中断时降并发。前置核对会在 6.关键材料OCR/ 写 _archive_apply_log_preflight.json 和 _archive_apply_log_preflight.md，对比 _apply_log.json 成功 PDF 操作与 apply_log.archive_root 下真实可见业务 PDF；如果发现真实目录多出 PDF、apply_log PDF 缺失、PDF 不可读、目标重复或最终 PDF 元数据不一致，Stage 6 会停止，等待用户确认补入 _apply_log.json、忽略或移走材料。每个 worker 只处理一个费用子文件夹并写 _worker_results/，批内全部 worker done 后才统一合并 _ocr_manifest.json，避免并发抢写主 manifest；失败 worker 使用原 worker_id 续跑。兼容旧单进程入口仍支持按费用子文件夹并发，默认 batch size 为 2，最大 4；支持 --resume、--shard N/M、--fee-folder "<概算大类>/<费用子文件夹>"。Stage 6 会复刻 Stage 5 最终归档目录结构，包括没有费用子项的空概算大类目录，并在 _ocr_manifest.json.mirrored_directories 中记录这些结构目录；OCR 任务仍只来自 _apply_log.json 成功操作，不会把真实目录多出的 PDF 静默纳入任务。1.委托依据-* 和 3.成果文件-* 超过 10 页时只 OCR 前 10 页，Markdown 文件名为 原PDF文件名前10页OCR.md；合同、支付凭证、结算文件不限页。_ocr_manifest.json 中 source_page_count 保留原 PDF 总页数，page_count 表示实际 OCR 页数。每个实际 OCR 页必须包含 ## 第 N 页 和 <!-- PAGE: N -->，失败页显式标注，不静默跳过。

Stage 7 摘要默认使用 Agent worker 任务包：先生成 _summary_batch_plan.json 和 _worker_tasks/*.json，每批默认 4 个 worker，允许 1-4。每个 worker 只处理一个费用子文件夹，读取任务包列出的 Stage 6 OCR Markdown 和三份摘要 reference，写自己的 五类关键材料摘要.md，再运行 validator 生成 _worker_results/*.json。脚本不得根据 OCR 文本用正则、关键词、固定行号或固定表格位置直接填业务字段；它只做任务、格式校验、链接重写、进度和汇总。摘要第一行必须使用项目正式名称，不得使用“五类/五项关键材料摘要”；只有合同备注要求页码/条款/位置，其他备注只写简洁审阅问题或留空；审计备注可空，填写时限约 400 字且只写问题。Stage 7 会继承 Stage 6 已镜像但无费用子文件夹的概算大类，写入 未发生 占位摘要和汇总占位，以保持费用序号和概算大类覆盖稳定。所有 状态 列在编制阶段必须留空，已核、待核、自动计算、✔ 等审核态只能留给后续审核 Skill。

Stage 8 审核默认使用一个 full-project Agent 审核任务包：先生成 _audit_task_plan.json 和 _audit_tasks/audit-001.json，审核任务覆盖 Stage 7 真实费用子文件夹，以及 Stage 7 budget_category_placeholders 中的 未发生 概算大类；占位概算大类会作为可挂问题对象进入必检覆盖。业务审核输入只包括 五类关键材料摘要汇总.md 和 Stage 8 规则库，_summary_manifest.json 仅出现在任务的 machine_context 中。审核结果先可由独立 subagent 写 initial_subagent 初稿，再由主对话独立复核并写 main_final；最终 问题清单.md 只接受 main_final。显式 --audit-mode segmented --agents N 才会启用多任务分段，且只适合真正独立上下文的 subagent 审核。

Stage 8 专项表默认使用一个 special-check-001 任务包：先生成 _special_check_task_plan.json 和 _special_check_tasks/special-check-001.json，由独立 subagent 写 漏项及未结算专项检查表*.md 和 _special_check_results/special-check-001.json。脚本只校验表头、行覆盖、顺序、版本化路径和只读输入边界，不把专项表并入 _audit_manifest.json。

风险与回滚

final-apply 先做完整预检：四份 stage manifest 必须存在并通过校验，Stage 5 HTML 必须人工确认，origin 文件不能漂移。任一源文件缺失、大小或 SHA256 改变都会阻断。

物化时先写入 .tmp_apply_<timestamp>/ staging 目录，全部成功后才把最终归档根目录切到 5.概算归档/ 下。失败时会删除 staging，并写入失败状态的 _apply_log.json。V2 当前提供回滚依据，不自动删除已成功切换的最终归档目录。

配置

常规字段：

• source_materials_root：原始资料池。
• stage_dirs：Stage 2-5 的方案和 manifest 输出目录。
• stage5.env_file：可选 GLM OCR env 文件；为空时 Stage 5 可读取 Skill 根目录 .env.local。
• stage5.ocr_md_file / stage5.allow_offline_ocr_md：仅用于离线测试或用户明确要求的人工/本地 OCR Markdown 路线；默认不要配置。
• stage6.output_root：可选覆盖 Stage 6 OCR 输出目录，默认 6.关键材料OCR。
• stage6.env_file：可选 GLM OCR env 文件；为空时 Stage 6 可读取 Skill 根目录 .env.local。
• stage6.batch_size / stage6.shard：兼容旧单进程 OCR 的并发与分片默认值；并发允许 1-4。
• stage6.agents_per_batch：Stage 6 批次调度每批 worker 数，默认 2，允许 1-4。
• stage7.output_root：可选覆盖 Stage 7 摘要输出目录，默认 7.关键材料摘要。
• stage7.agents_per_batch：Stage 7 摘要 worker 任务每批数量，默认 4，允许 1-4。
• stage7.summary_title：可选指定摘要 H1 的项目正式名称；为空时由 worker 按材料提取。
• stage8.output_root：可选覆盖 Stage 8 审核输出目录，默认 8.审核问题清单。
• stage8.audit_mode：Stage 8 审核模式，默认 full-project；只有显式设为 segmented 时才按审核条目分段。
• stage8.agents_per_batch：仅用于 stage8.audit_mode: segmented 的分段任务数量，允许 1-4；默认 full-project 不读取该字段。
• stage8.rules_dir：可选覆盖审计规则库目录；默认使用 child_skills/audit-expert/rules/。
• orchestrator audit-special：Stage 8 辅助专项表命令，使用同一 stage8.output_root 和 stage8.rules_dir。
• archive_root_name：最终归档根目录名。
• archive_root_in_project_root: false：默认最终归档根挂在 5.概算归档/ 下；设为 true 可兼容旧版项目根输出。
• final_apply.mode: copy：V2 强制 copy。
• detected.*：自动识别不明确时手动指定明细账、凭证 PDF 根目录、技术资料、补充资料和概算 PDF；多份扫描版明细账使用 ledger_paths，ledger_path 仍保留单份兼容。

child_skills 只用于高级调试替换 plan 脚本，不再包含 apply 路径。

测试

python3 -m unittest tests/test_manifest_schema.py tests/test_manifest_init.py tests/test_origin_drift_check.py
python3 -m unittest tests/test_orchestrator.py tests/test_drift_detection.py tests/e2e_dry_run_chain_test.py
python3 -m unittest tests/test_stage6_manifest_validator.py
python3 -m unittest tests/test_stage8_audit_manifest_validator.py
python3 -m unittest child_skills/summarize-key-materials/tests/test_summarize_key_materials.py
python3 -m unittest child_skills/audit-expert/tests/test_audit_expert.py
python3 -m unittest child_skills/reorganize-expense-pdfs/tests/test_expense_pdf_reorg.py
python3 -m unittest child_skills/collect-five-key-materials/tests/test_collect_five_key_materials.py
python3 -m unittest child_skills/archive-fee-folders-by-budget/tests/test_archive_fee_folders_by_budget.py
python3 -m unittest child_skills/ocr-key-materials/tests/test_ocr_key_materials.py
node --test child_skills/finance-voucher-rename/tests/step1-logic.test.mjs

部分测试依赖 PyYAML、pypdf 和本仓库子 Skill 的 Node 依赖。