7a01ed4db9
- add scripts/annotate_roster_invoices.py: match passenger names to invoice PDFs, write status + relative encoded hyperlinks into roster xlsx - add scripts/add_invoice_passenger_name.py, scripts/calibrate.py - add .opencode/skills/invoice-wrapup skill - improve invoice_tool.py / web_ui.py / vision_fallback.py automation - add device/screen/windows adaptation docs - ignore out/ (delivered invoice PDFs contain sensitive data)
164 lines
6.4 KiB
Markdown
164 lines
6.4 KiB
Markdown
# Windows 迁移清单
|
||
|
||
> 2026-07-09 整理。本项目从 macOS 搬到 Windows 前必读。
|
||
>
|
||
> 核心结论：**代码不能直接跑**，有 4 处硬编码 macOS 路径 + 3 个 bash 脚本依赖 launchd/lsof + Python 依赖需手动装。
|
||
|
||
## 一、必须一起带的文件（项目外依赖）
|
||
|
||
| 依赖 | 说明 | 当前位置 | Windows 处理 |
|
||
|---|---|---|---|
|
||
| **ADB（platform-tools）** | 3 处硬编码路径引用，必须安装 | `/opt/homebrew/share/android-commandlinetools/platform-tools/adb` | 装 Android Platform Tools，改代码路径或加 PATH |
|
||
| **Python 3.12+** | 标准库 + 3 个三方包 | `/opt/homebrew/opt/python@3.12/bin/python3.12`（脚本里写死） | 装 Python 3.12+，脚本里的 `python3` 换成 `python` |
|
||
| **openpyxl** | 读 xlsx 名单（`invoice_tool.py:27`，try/except 守护） | pip 安装 | `pip install openpyxl` |
|
||
| **pypdf** | `add_invoice_passenger_name.py` 硬 import | pip 安装 | `pip install pypdf` |
|
||
| **qrcode** | 生成二维码（`invoice_tool.py:1698`，lazy import） | pip 安装 | `pip install qrcode` |
|
||
| **numpy** | 可选（`invoice_tool.py:167`，try/except） | pip 安装 | `pip install numpy`（不装也能跑） |
|
||
|
||
## 二、必须改的代码（硬编码 macOS 路径）
|
||
|
||
### 2.1 ADB 路径（3 处，最关键）
|
||
|
||
```
|
||
scripts/invoice_tool.py:43 ADB_PATH = "/opt/homebrew/share/android-commandlinetools/platform-tools/adb"
|
||
scripts/invoice_tool.py:1334 ["/opt/homebrew/share/android-commandlinetools/platform-tools/adb", "exec-out", "screencap", "-p"]
|
||
scripts/calibrate.py:23 ADB = "/opt/homebrew/share/android-commandlinetools/platform-tools/adb"
|
||
```
|
||
|
||
**Windows 改法**：装 platform-tools 后，要么改成 `C:\\platform-tools\\adb.exe`，要么改成 `"adb"` 靠 PATH 解析（推荐，跨平台）。
|
||
|
||
注意 `invoice_tool.py:1334` 是**独立硬编码**（不走 ADB_PATH 变量），要单独改。
|
||
|
||
### 2.2 其他脚本用 `"adb"` 字符串（靠 PATH）
|
||
|
||
`vision_fallback.py:38`、`record_step.py:64-69` 用的是 `["adb", ...]`，靠 PATH 解析。Windows 上把 `adb.exe` 加 PATH 即可。
|
||
|
||
### 2.3 Python 解释器路径
|
||
|
||
`restart_web_ui.sh` 和 `install_web_ui_launch_agent.sh` 里用 `python3`，Windows 用 `python`。但这两个脚本是 bash 脚本，Windows 上不能直接跑（见第三节）。
|
||
|
||
## 三、不能直接跑的脚本（macOS 专属）
|
||
|
||
| 脚本 | 问题 | Windows 替代 |
|
||
|---|---|---|
|
||
| `scripts/restart_web_ui.sh` | bash 脚本 + 用 `lsof` + `pgrep` + `launchctl` + `os.fork()` | 见下方「Windows 启动方案」 |
|
||
| `scripts/web_ui_watchdog.sh` | bash 脚本 + `lsof` + `curl` 循环 | 写个 `.bat` 或直接 `python scripts/web_ui.py` 前台跑 |
|
||
| `scripts/install_web_ui_launch_agent.sh` | 生成 macOS LaunchAgent plist | Windows 不需要，用启动菜单/任务计划程序替代 |
|
||
|
||
### Windows 启动方案
|
||
|
||
最简单：开个 cmd 直接前台跑
|
||
```cmd
|
||
cd C:\path\to\autotrain
|
||
python scripts\web_ui.py
|
||
```
|
||
|
||
或者写个 `start_web_ui.bat`：
|
||
```bat
|
||
@echo off
|
||
cd /d %~dp0\..
|
||
python scripts\web_ui.py
|
||
pause
|
||
```
|
||
|
||
## 四、配置文件
|
||
|
||
### config.local.json（已含识别 key，必须带）
|
||
|
||
```json
|
||
{
|
||
"company_title": "...",
|
||
"tax_id": "...",
|
||
"receiver_email": "...",
|
||
"vision": {
|
||
"provider": "siliconflow",
|
||
"base_url": "https://api.siliconflow.cn/v1",
|
||
"api_key": "sk-xxx",
|
||
"model": "Qwen/Qwen3-VL-8B-Instruct"
|
||
},
|
||
"invoice_success_action": "download",
|
||
"invoice_output_dir": "output/01"
|
||
}
|
||
```
|
||
|
||
**这个文件在 .gitignore 里，必须手动打包带过去。** 识别 key 已在里面。
|
||
|
||
### work/ 目录（部分需要带）
|
||
|
||
`work/` 整个在 .gitignore 里。需要带的：
|
||
|
||
| 文件 | 必须带 | 说明 |
|
||
|---|---|---|
|
||
| `passenger_roster.csv` | ✅ | 当前名单（44 人），不带要重新 import-roster |
|
||
| `android_invoice_progress.csv` | ✅ | 开票进度（143 completed），不带会重复开票 |
|
||
| `qr_page_order.csv` | ✅ | 本二维码核查表 |
|
||
| `agent_id_last8.txt` | ✅ | 代理人证件后 8 位 |
|
||
| `last_qr_image.png` / `last_qr_url.txt` | ✅ | 上次扫码的二维码，H5 precheck 用 |
|
||
| `device_profile.json` | ❌（不存在） | Windows 上跑 `/calibrate` 重新生成 |
|
||
| `android_page_queue.csv` | ❌ | 当前页队列，临时态，可不带 |
|
||
| `*.log` / `*.png`（调试截图） | ❌ | 无价值 |
|
||
|
||
### data/ 目录
|
||
|
||
`.gitignore` 忽略了 `data/input/`、`data/mail/`、`data/attachments/`。如果还要跑 import-codes / collect-mail，需要带对应输入文件。如果只跑 H5 开票，不需要。
|
||
|
||
## 五、手机/ADB 环境（Windows 侧准备）
|
||
|
||
1. **装 Android Platform Tools**：https://developer.android.com/tools/releases/platform-tools
|
||
2. **手机开 USB 调试**：设置 -> 开发者选项 -> USB 调试
|
||
3. **验证 ADB 连通**：`adb devices` 能看到设备
|
||
4. **12306 App 装好**，登录，能到扫码开票页
|
||
|
||
## 六、换手机/换屏幕必跑
|
||
|
||
到了 Windows + 新手机后，**第一件事**：
|
||
|
||
1. 打开 `http://127.0.0.1:8765/calibrate`（改完代码启动后）
|
||
2. 点「💾 保存设备配置」生成 `work/device_profile.json`
|
||
3. 逐状态截图校准（重点：「确认」「继续开票」「开具」）
|
||
4. `python scripts/invoice_tool.py android-h5-page-run --dry-run --max-actions 1` 验证
|
||
|
||
详见 `docs/device-adaptation.md`。
|
||
|
||
## 七、打包压缩建议
|
||
|
||
```
|
||
要打包的：
|
||
scripts/ （全量，含 9 个脚本）
|
||
docs/ （全量，含 device-adaptation / screen-adaptation / web-ui-adaptation-log）
|
||
templates/ （全量）
|
||
config.local.json （关键！含识别 key）
|
||
config.example.json
|
||
AGENTS.md / INDEX.md / CHANGELOG.md / CODEMAP.md
|
||
work/passenger_roster.csv
|
||
work/android_invoice_progress.csv
|
||
work/qr_page_order.csv
|
||
work/agent_id_last8.txt
|
||
work/last_qr_image.png
|
||
work/last_qr_url.txt
|
||
|
||
不要打包的：
|
||
archive/ （旧备份，体积大）
|
||
output/ （已交付发票，体积大）
|
||
data/input/ （原始开票码，如不跑 import-codes 不需要）
|
||
data/mail/ data/attachments/
|
||
work/*.log work/*.png（调试产物）
|
||
work/__pycache__/
|
||
.git/
|
||
```
|
||
|
||
## 八、Windows 上首次运行步骤
|
||
|
||
```cmd
|
||
REM 1. 装 Python 3.12+ 和 ADB
|
||
REM 2. pip install openpyxl pypdf qrcode
|
||
REM 3. 改代码里的 ADB 路径（3 处，见第二节）
|
||
REM 4. 启动
|
||
cd C:\path\to\autotrain
|
||
python scripts\web_ui.py
|
||
REM 5. 浏览器打开 http://127.0.0.1:8765
|
||
REM 6. 进 /calibrate 生成 device_profile.json
|
||
REM 7. dry-run 验证
|
||
python scripts\invoice_tool.py android-h5-page-run --dry-run --max-actions 1
|
||
```
|