Invoice Processing

票据处理编排

⛔ MCP 工具调用铁律

agent 唯一直调的 MCP 工具是 open_invoice_match_review_ui（呼起 UI，入参仅 {caller_expert_id, data_cache_id}），其契约见 references/tools/open_invoice_match_review_ui.md。其余 MCP 工具（get_project_list / list_pending_tickets / get_org_cos_credential / get_pending_invoice）参数已由脚本内部固定，agent 不直调、不构造参数。

⛔ 全局对话铁律

• ⛔ 绝对禁止把内部思考 / 推理过程作为对话内容展示给用户（思考链、工具调用前的推演、候选方案权衡、约束逐条比对、内部状态机推演等）。用户只应看到结论性、可执行的反馈。
• 需要"解释原因"时，只给业务层结论（如"该申请单已被本批其他票据占用"），⛔ 不得展开内部推导路径。
• 内部调试信息、脚本日志、断言细节 ⛔ 不得回显给用户。
• ⛔ 金额单位铁律：amount 恒为「分」（uint32），不是「元」。凡向用户描述 / 播报金额，必须先做「分→元」换算，且必须整数运算 f"{c//100}.{c%100:02d}"（⛔ 严禁浮点除法，33000/100 可能得到 329.999...）。

🚀 主编排器 run_pipeline.py（agent 主路径）

正常流程 agent 只需做三件事：

1. 写 manifest.json：把用户 PDF 绝对路径（pdf_paths）+ session_id + workspace + progress_log 写入（org_no / org_name 可选，不传时脚本内部自查）。格式见脚本顶部 docstring。
2. 调一次：python skills/invoice-processing/scripts/run_pipeline.py --input-file manifest.json（用 run_in_background=true 后台启动）。
3. 读落盘文件并呼起 UI：读 {workspace}/ui_req.json（完整 UiReq）→ 调 build_invoice_match_ui_params.py 经 set_common_data_cache 缓存拿到 data_cache_id → 以 {caller_expert_id, data_cache_id} 调 open_invoice_match_review_ui（⛔ 不得把完整 UiReq 直接传给工具）。

脚本内部一次性跑完「md5 去重 → 光栅化 → 全本地 OCR → 金额换算 → 项目匹配 → 远程匹配 → m:n 分配 → COS 上传 → 组装 ui_req」。

🔴 禁止运行时探查与手工装包：不得为了"确认格式/兼容性"读取编排器源码、导入 OCR 包探测、执行 pip install。manifest 与启动命令是稳定契约，依赖初始化只由编排器内部单入口完成。

⛔ 核心红线（头等铁律）

1. 光栅化 vs 文本层：PDF 必须光栅化成图片再 OCR。⛔ 严禁用 pypdf / pdfplumber / pdftotext 读 PDF 文本层当字段来源（加密字体 → CID 乱码 → 假字段 → 假结论）。"PDF 里能提到文本" ≠ 可以跳过光栅化。
2. 匹配信号只有 3 个：title（抬头）+ amount（金额，分）+ project_id（项目 ID，可选）。后端只吃这 3 个字段，⛔ 不得把其它字段当匹配条件。
3. 匹配结果二值：只有 match_status = 1（命中）/ 2（未命中），没有置信度概念。⛔ 不得自造 match_confidence / default_selected 等字段，⛔ 不得在对话里报告"置信度 92%"或 high/medium 档位。
4. 不 LLM 代算：金额换算走 amount_conversion.py、抬头归一化走 title_normalizer.py、项目名映射走 project_matcher.py、匹配走 list_pending_tickets。⛔ 严禁 LLM 自己算金额、改写抬头、做子串匹配、实现编辑距离/语义匹配"救回"未命中的票。
5. 不手工装依赖 / 不过早放弃：宣布"本环境做不到"前，必须先运行编排器并读取结构化错误。依赖缺失由脚本单入口补齐，⛔ 不得手工 pip install、拆包补装。
6. 匹配 0 命中 ≠ "捐赠人不存在"：只代表"本次 filter 组合没找到候选"。⛔ 不得据此得出"捐赠人不存在""金额异常""用户走错机构"等结论。

批处理与性能

实时进度协议（日志文件）

• 脚本侧（写）：run_pipeline.py 向 progress_log 追加用户可读的中文进度（如 🔍 OCR识别阶段：已处理 10/100），节点前缀形如「📋 准备 / 🖼️ 光栅化 / 🔍 OCR识别 / 📝 字段抽取 / 📚 项目库 / 🔗 项目匹配 / 🌐 远程匹配 / ☁️ 原件上传 / 🧩 组装」。
• 对话侧（读）：agent 后台启动脚本后用 TaskOutput(task_id, block=false) 取权威状态，running 时 tail -n 1 <progress_log> 原样转述末行（短任务 35s / 长任务 1030s 轮询），completed 时 wc -l + tail -n 3 汇总后停止。⛔ 不解析、不润色、不重算耗时。
• 🔴 远程匹配完成行固定「已处理/总数量」口径（如 已处理 100/100，自动匹配 13 笔，待人工确认 87 笔）。⛔ 不得写成「成功 13 / 待处理 87」——待处理 会让 agent 误判"还有 87 张没匹配完"，实则该阶段已完成，87 笔是待用户在确认页确认的 pending_list。
• 🔴 严禁只发一句「OCR识别中」就长时间静默——必须持续转述节点/分批进度。
• 进度分母一律是本批上传数 N，⛔ 不得用全机构待开票总数 M。

耗时预估口径

1. 启动前用默认系数给一次预估区间（如"预计 4~6 分钟出确认列表"）+ 说明主要耗时来源。
2. 之后靠 tail -n 1 持续转述进度。⛔ 脚本一次跑完、agent 不重算耗时、不给"预计完成时刻"（不存在"先跑一批→实测均值→二次播报"的分批校准）。

并发边界与话术

• ⛔ 不得向用户承诺 OCR / 匹配的并行加速（匹配/提交接口不能并发）。
• 并发与阶段重叠都在脚本内部完成，agent 只需如实转述进度。

轮次预算软着陆

• 轮次到软着陆阈值主动收尾：落 checkpoint + 输出进度 + 告知"回复「继续」我接着处理"，⛔ 不硬跑到被截断。
• ⛔ 不得依赖"轮次用完平台会自动提示继续"（续跑完全靠 checkpoint）。

Token 治理与上传规模

• 候选池 / OCR 全文 / 全量匹配数据一律不进 agent 上下文（脚本落盘，agent 只收计数级摘要）。⛔ 不得逐条罗列每张票据字段，向用户/调度方反馈用计数级摘要。
• 单次消息建议 ≤500 份 PDF；超过照常处理（路径长吃 token，但不阻断）。
• ⛔ 不要求"凑齐 M 张再开始"、不展示门槛式进度（"1/M 张"）；处理中的进度反馈（分母是本批上传数）是合规且必要的。

对话话术硬约束（MUST 执行）

• OCR 精度提示：全本地 OCR 对印章/手写体识别率偏低，呼起 UI 前 MUST 告知用户"本批使用本地识别引擎, 精度可能下降, 请在确认页面重点核对"。

触发场景

• 用户直接对话："我要处理待开票的票据"、"帮我处理这些 PDF"、"批量上传票据"等。
• 被 today-todo-team-lead 调度，prompt 明确"引导用户完成票据处理流程"。

工作流程

核心节奏（铁律）：用户一次性发送本次要处理的全部票据 PDF，agent 收到后立即写 manifest → 调一次 run_pipeline.py → 拿 ui_req → 直接呼起 UI。⛔ 不弹"继续上传/开始匹配"二选一、不要求分批、不提醒可多次发。

Step 1: 提示上传 PDF

请上传您本次要处理的票据 PDF（可一条消息附带多份），发送后我会识别并直接打开匹配页面供您确认。
（单次消息建议不超过 500 份）

⛔ 措辞要点：不说"请上传全部 M 张后开始"、"进度 X/M"、"可分几次发"。M 只是背景信息，不是本轮要凑够的目标数。

Step 1.5: 收到 PDF 立即跑全流程

用户在一条消息里发送了 ≥1 份 PDF → 立即写 manifest → 后台启动 run_pipeline.py → 按实时进度协议转述进度 → 脚本结束后读落盘文件呼起 UI。

Step 2-8: 降级参考（仅脚本报错需调试时查阅）

正常流程不逐条执行各子脚本。脚本报错时，按「特殊情况处理」对应条目应对：

Step 9: 呼起 UI

🔴 data_cache_id 范式：完整 UiReq（含两个 repeated 数组）先经 build_invoice_match_ui_params.py → set_common_data_cache 缓存拿 data_cache_id，再用 {caller_expert_id, data_cache_id} 两个字段呼起 UI。⛔ 不得把完整 UiReq 塞进工具。

1. 读 {workspace}/ui_req.json（含 org_no / matched_items / matched_failed_items / submit），⛔ 不得手抄改写；某侧列表为空时脚本会【省略该字段】，agent 必须保持它不存在，⛔ 不得"好心补" "" 或 []。
2. 调 python skills/invoice-processing/scripts/build_invoice_match_ui_params.py --json-file <workspace>/ui_req.json → 写出 ui_params.json（{caller_expert_id, data_cache_id}）。
3. 以 ui_params.json 内容调 open_invoice_match_review_ui。

submit.next_step 固定文案（脚本写入）：使用提交票据到远程步骤，剔除本地已提交项。

🔴 呼起 UI 成功后，本轮立即结束，全部对话输出只能是「一句极简提示」：

• ✅ 唯一允许：票据信息已识别完成，已为您打开匹配确认页面，请在页面中确认并选择提交。
• ⛔ 不得输出处理摘要/统计表格/数量清单/分支说明/进度播报/文件路径，不得把内部思考回显，不得追问或寒暄，不得输出多行。
• ⛔⛔ 实测事故：调起成功后继续输出内容，会把刚打开的 UI 页面刷没（前端把新文字流当作新一轮渲染，覆盖掉 UI），用户看不到票据确认页。
• ⛔ 不阻塞等待、不编造用户勾选/修改结果。

提交后增量处理 + 命名步骤「提交票据到远程」

用户在 UI 内点提交 → UI 内完成 update_tickets → UI 回传「已提交成功的 pdf 列表」+ submit.next_step 文案交还 Host → Host 重新调度本专家执行命名步骤：

1. 调 title_normalizer.py --input '{"mode":"prune",...}' 剔除已提交项（按 invoice_url）。
2. 按 remaining_count 分流告知：0 → "已提交 X 条，本批票据已全部提交完成"；>0 → "已提交 X 条，剩余 Y 条待处理"（⛔ 不重新呼起 UI，UI 侧已自行刷新）。

🔴 会话边界前置约束：prune 复用存量/剔除已提交项，一律以 session_id 与当前会话完全一致为前提。跨会话（session_id 不一致）→ 视为全新批次，重新走完整流程，⛔ 不得采信他会话的 invoice_url / 旧匹配结果。

未匹配原因文案（agent 向用户解释用）

⚠️ 已提交、md5 重复、申请单被占用这三种情况，票据识别信息完全正确，不能用默认文案让用户改抬头（改多少次都匹配不上，死循环）。

特殊情况处理

参考文件

• references/tools/open_invoice_match_review_ui.md — Step 9：呼起票据匹配 UI（agent 唯一直调的 MCP 工具；入参仅 {caller_expert_id, data_cache_id}）
• scripts/README.md — 各脚本用法（降级调试时查）