autotrain/CHANGELOG.md

2026-06-11 #feat scope:android-h5-automation scope:web-ui - H5 批处理后自动输出二维码顺序核查表

• Why: 跑完后人工核查失败项需要按列表顺序定位，而非按名单排序
• 详见: scripts/invoice_tool.py:441, scripts/invoice_tool.py:1220, scripts/web_ui.py:144, scripts/web_ui.py:632

2026-06-11 #fix scope:web-ui scope:android-h5-automation - 代理人验证码输入 + 二维码唯一文件名

• Why: 新扫码开票后会进入代办人身份核验页，且手机相册容易保留旧二维码
• 详见: scripts/web_ui.py:170, scripts/invoice_tool.py:40, scripts/invoice_tool.py:1416

2026-06-11 #fix scope:web-ui scope:android-h5-automation - 重进开票页改走扫码路径

• Why: 新批次二维码应走 12306 内部扫码链路,不能直接 intent 打开链接
• 详见: scripts/invoice_tool.py:1219, scripts/web_ui.py:795

2026-06-11 #feat scope:android-h5-automation - H5 到底后自动回顶查缺补漏

• Why: 列表跑完后仍需二次确认未成功项,并明确通知用户本轮已收尾
• 详见: scripts/invoice_tool.py:393, scripts/invoice_tool.py:1646

2026-06-11 #refactor scope:web-ui - 二维码批次入口靠近扫码区

• Why: 每组二维码切换是批次操作,入口应贴近截图粘贴区域减少误点
• 详见: scripts/web_ui.py:545

2026-06-11 #fix scope:web-ui - 用 watchdog 保活本地服务

• Why: Codex 启动的后台进程会被会话回收,需要独立父进程自动拉起
• 详见: scripts/restart_web_ui.sh:1, scripts/web_ui_watchdog.sh:1

2026-06-11 #chore scope:web-ui scope:docs - 增加稳定重启入口

• Why: 手动重启易让服务随终端退出,导致浏览器显示拒绝连接
• 详见: scripts/restart_web_ui.sh:1, docs/usage.md:91, INDEX.md:59

2026-06-11 #refactor scope:web-ui - 重排本地 UI 布局层级

• Why: 批量开票操作项过于拥挤,需按名单/参数/二维码分区降低误操作
• 详见: scripts/web_ui.py:386

2026-06-11 #fix scope:web-ui - 保存后当前路径即时跟随输入值

• Why: 用户需要看到“当前保存到”随保存动作立刻更新,而不是被轮询刷新打回
• 详见: scripts/web_ui.py:546, scripts/web_ui.py:715

2026-06-11 #fix scope:web-ui - 保存结果独立显示避免被刷新覆盖

• Why: 保存设置后的路径提示会被状态刷新覆盖,需要稳定可见的生效反馈
• 详见: scripts/web_ui.py:497, scripts/web_ui.py:705

2026-06-11 #fix scope:web-ui - 保存设置后显示生效路径

• Why: 用户点击保存目录后缺少明确反馈,容易误判设置没有生效
• 详见: scripts/web_ui.py:403, scripts/web_ui.py:704

2026-06-11 #fix scope:android-h5-automation - 下载后自动退出发票预览页

• Why: 下载确认后会停在预览页,需要稳定回到成功页/列表继续下一人
• 详见: scripts/invoice_tool.py:1004, scripts/invoice_tool.py:1892

2026-06-11 #fix scope:android-h5-automation - 下载发票文件名带真实姓名

• Why: 仅用脱敏名无法区分和归档,本地 PDF 需要直接体现发票归属人
• 详见: scripts/invoice_tool.py:1919

2026-06-11 #fix scope:android-h5-automation - 处理发票下载完成确认弹窗

• Why: PDF 已保存后卡在下载进度 100% 弹窗,导致无法自动回到列表
• 详见: scripts/invoice_tool.py:1004, scripts/invoice_tool.py:1886

2026-06-11 #fix scope:web-ui - 保存目录输入不再被自动刷新覆盖

• Why: UI 状态轮询会重置正在编辑的目录,导致用户无法自定义保存位置
• 详见: scripts/web_ui.py:481, scripts/web_ui.py:696

2026-06-11 #feat scope:android-h5-automation scope:web-ui - 成功页支持下载发票到本地

• Why: 后续需要保留邮箱流程,同时默认把发票文件直接沉淀到电脑目录
• 详见: scripts/invoice_tool.py:959, scripts/web_ui.py:212

2026-06-11 #fix #perf scope:android-h5-automation scope:web-ui - 修复核验同名歧义、优化续跑锚点、优化图库选码

• Why: UI 跑流程经常报错，需先验证 CLI、再固化续跑断点、再优化重试顺序
• 详见: scripts/invoice_tool.py:402, scripts/invoice_tool.py:1485, scripts/web_ui.py:899

铁路系统发票 · CHANGELOG

每次动了什么记一条。详细记录写在各自模块目录下，根目录 CHANGELOG 是强标签化的检索索引。

如本项目下有子项目（子目录里也有 AGENTS/INDEX/CHANGELOG 三件套）：本 CHANGELOG 只记录跨多个子项目的同时操作；单一子项目操作记在该子项目自己的 CHANGELOG 里。详见 ../docs/trio-protocol.md。

格式规范（严格）

## YYYY-MM-DD #<type> scope:<name> [#<extra-tag>...] - <一句话主题>

- Why: <一句话动机，不复述 what>
- 详见: <path 或 commit hash>

硬约束：

• 日期必须 ISO 格式 YYYY-MM-DD
• 类型标签必须以 # 开头，从下面字典选一个为主标签
• 作用域必须 scope:<name> 形式，name 用 kebab-case；多模块改动用多个 scope:
• Why 一行不超过 80 字符
• 不贴 diff、不复述 what，那些进 commit 或模块自己的文档

类型标签字典

标签	含义
#feat	新功能
#fix	bug 修复
#refactor	重构（无行为变化）
#perf	性能优化
#docs	文档变更
#test	测试相关
#chore	构建/依赖/工具链/初始化
#archive	归档/弃用
#breaking	破坏性变更（叠加）
#deprecated	标记弃用（叠加）
#wip	进行中（叠加）

检索示例

grep -E "^## .* #feat .* scope:invoice" CHANGELOG.md
grep "#breaking" CHANGELOG.md
grep "^## 2026-06" CHANGELOG.md

---

2026-06-09 #feat scope:android-automation #scope:vision-fallback - 视觉驱动批量开票路径打通

• Why: 用户改路线,手动扫码进列表 → 视觉抓行 → anchor 去重 → 按页批次开票
• 详见: scripts/invoice_tool.py 新增 android-vision-page-run 命令(并行存在,不动老路径);scripts/vision_fallback.py 新增 list-rows 子命令 + 0-1000 归一化反推
• docs/debug-trace-2026-06-09.md 全程实测时间线

2026-06-09 #chore scope:vision-fallback - 换用硅基流动 Qwen3-VL-8B-Instruct

• Why: 豆包 Doubao-Seed-2.0-mini OCR 准但 grounding 失败(返坐标完全猜的);Qwen3-VL 系列做过 grounding 训练,实测 bbox 误差 <25px
• 详见: config.local.json provider 改 siliconflow,model Qwen/Qwen3-VL-8B-Instruct;费用估算 21-25 次/全程 ≈ ¥0.05-0.1

2026-06-09 #fix scope:android-automation - 兜底 back 退过头 + 2 字脱敏名正则失配

• Why: no_match 名 tap 后核验弹窗解析失败,旧 back+back 兜底把列表页一起退到 12306 首页
• 详见: invoice_tool.py 核验弹窗正则 {1,3}→{0,3} 兼容澳*/吴* 类两字名;safe_back_until_list 加首页检测 + 单次 back 后 1.5s 等待,外层 abort 闸门避免误操作

2026-06-09 #feat scope:replay - 录制工具 record_step.py

• Why: 视觉模型坐标精度够但子流程边界(2 字名 / 已开过 / 已退 H5)边界 case 多,人工示范+录制比盲调更快
• 详见: scripts/record_step.py — python3 scripts/record_step.py "label" 当前 session 累加;--new 开新 session

2026-06-09 #feat scope:vision-fallback - 接入火山豆包视觉模型作为 adb dump 兜底

• Why: adb 节点解析对 H5 内嵌 UI / 弹窗状态不稳,加视觉 LLM 二次确认
• 详见: scripts/vision_fallback.py (detect-page / ask / ping),config.local.json vision 段;模型 doubao-seed-1-6-flash-250615

2026-06-09 #feat scope:web-ui - 开始运行流程改成"先回顶 + 截屏建队列 + 才操作"

• Why: 原流程开始即翻页,用户没看到本页识别结果就直接 swipe,体验跟"卡死"无异
• 详见: scripts/web_ui.py start_runner 前置同步两步骤;新 UI 复选框"开始前回顶"默认勾选

2026-06-09 #feat scope:android-automation - 翻页到底 fingerprint 检测 + 回顶命令

• Why: swipe 后页面没变化以前会无限滑;新加 android-page-top 让人能从底部回到列表顶端开干
• 详见: scripts/invoice_tool.py android_page_top / android_page_step _last_done_fp 状态比对

2026-06-09 #fix scope:android-automation - 运行时异常软失败,不整体崩 runner

• Why: 单个人开票流程出错以前会让整批停掉,无人值守语义不成立
• 详见: scripts/invoice_tool.py mark_clicked_as_runtime_error / android_page_run try-except

2026-06-09 #feat scope:android-automation - 本页 retry 一次 + 身份证首末位增强匹配

• Why: 用户要求整页跑完后失败者再走一遍才翻页;同名歧义用脱敏身份证首末位解掉
• 详见: scripts/invoice_tool.py build_visible_page_queue / match_roster / RETRYABLE_FAILURES

2026-06-09 #fix scope:web-ui - 启动命令默认带 --auto-next 避免整页 skip 时空转

• Why: 当前页全 skip_progress / no_match 时不上滑下一页,20 步连续 page_done 无进展
• 详见: scripts/web_ui.py start_runner

2026-06-08 #feat scope:web-ui - 增加本地批处理进度页面

• Why: 50 人名单批处理需要可视化上传入口、实时状态和逐人结果表
• 详见: scripts/web_ui.py / scripts/invoice_tool.py / docs/usage.md

2026-06-08 #feat scope:android-automation - 增加扫码列表页队列和翻页处理

• Why: 列表页开具按钮不是固定坐标，需要按当前页姓名和 bounds 生成队列逐个处理
• 详见: scripts/invoice_tool.py / docs/usage.md

2026-06-08 #feat scope:android-automation - 增加 12306 单步开票状态机

• Why: 截图逐页校准成本高，需要用 XML 状态识别减少人工判断和 token 消耗
• 详见: scripts/invoice_tool.py / docs/usage.md

2026-06-08 #feat scope:android-automation - 增加 Android 端身份证后 8 位自动填入

• Why: 12306 App 扫码后需按脱敏姓名匹配名单并填写身份证后 8 位，人工逐个填写太慢
• 详见: scripts/invoice_tool.py / templates/android_flow.example.json / docs/usage.md

2026-06-08 #fix scope:batch-invoice - 识别 PNG 扫码开票单为 App 扫码流程

• Why: 真实铁路扫码开票单截图要求 12306App 扫码，不能误判为网页自动开票
• 详见: scripts/invoice_tool.py / work/invoice_tasks.csv / docs/usage.md

2026-06-08 #feat scope:batch-invoice - 落地铁路发票批量处理本地工具

• Why: 普通代购票缺统一批量开票入口，需要用官方页面配合本地台账和收票归集降本
• 详见: scripts/invoice_tool.py / docs/usage.md / INDEX.md

2026-06-10 #feat scope:h5-automation scope:web-ui - H5扫码开票单视觉驱动批量 + 优雅退出 + UI模式切换

• Why: H5单页挂N个乘客,back重置scroll;手机被占用(微信来电)时常发生,需优雅退出而非崩溃
• 详见: scripts/invoice_tool.py android-h5-page-run + _h5_scroll_down;scripts/web_ui.py mode=h5/h5+模式选择器;三处优雅退出(PREECHECK_FAILED/PAGE_AWAY/sub-flow无法回列表)

2026-06-10 #feat scope:web-ui scope:qr-decode - 粘贴二维码截图自动解码 + ADB 在手机打开

• Why: 用户拿到开票二维码截图后不用再手动扫,贴到 UI 自动解码→在手机打开对应页面
• 详见: scripts/invoice_tool.py decode_qr_image(OpenCV QRCodeDetector);scripts/web_ui.py /api/decode-qr /api/open-on-phone

2026-06-08 #chore scope:init - 项目初始化

• Why: 新专项需要独立工作区和三件套入口，便于后续发票资料处理与核对
• 详见: AGENTS.md / INDEX.md / 本文件