merge: integrate preflight readiness and diff-report optimizations into main

Author: toraidl

README.md

@@ -151,6 +151,15 @@ sudo python3 main.py --stock <底包路径> --port <移植包路径> --pack-type
 | `--clean` | 开始前清理工作目录 | `false` |
 | `--debug` | 开启调试日志 | `false` |
 | `--eu-bundle` | EU 本地化资源包 (ZIP) 的路径或 URL | 无 |
+| `--preflight-only` | 仅执行预检并输出报告，然后退出 | `false` |
+| `--skip-preflight` | 跳过预检阶段（不建议） | `false` |
+| `--preflight-strict` | 将风险项也视为失败项（用于严格阻断） | `false` |
+| `--preflight-report` | 预检 JSON 报告输出路径 | `build/preflight-report.json` |
+| `--enable-snapshots` | 在关键阶段保存工作目录快照 | `false` |
+| `--snapshot-dir` | 快照目录（未设置时使用 `<work-dir>/snapshots`） | `null` |
+| `--rollback-to-snapshot` | 从指定快照恢复目标工作目录并退出 | `null` |
+| `--enable-diff-report` | 生成产物差异报告（前后文件/属性/APK变化） | `false` |
+| `--diff-report` | 差异报告 JSON 输出路径 | `build/diff-report.json` |
 
 ---
 

README_EN.md

@@ -153,6 +153,15 @@ sudo python3 main.py --stock <path_to_stock_zip> --port <path_to_port_zip> --pac
 | `--clean` | Clean work directory before starting | `false` |
 | `--debug` | Enable verbose debug logging | `false` |
 | `--eu-bundle` | Path/URL to EU Localization Bundle ZIP | N/A |
+| `--preflight-only` | Run preflight checks only, emit report, then exit | `false` |
+| `--skip-preflight` | Skip the preflight phase (not recommended) | `false` |
+| `--preflight-strict` | Treat risk findings as failures (strict gating) | `false` |
+| `--preflight-report` | Output path for preflight JSON report | `build/preflight-report.json` |
+| `--enable-snapshots` | Capture workspace snapshots at key workflow stages | `false` |
+| `--snapshot-dir` | Snapshot directory (defaults to `<work-dir>/snapshots`) | `null` |
+| `--rollback-to-snapshot` | Restore target workspace from a named snapshot and exit | `null` |
+| `--enable-diff-report` | Generate artifact diff report (files/props/APK changes) | `false` |
+| `--diff-report` | Output path for artifact diff report JSON | `build/diff-report.json` |
 
 ---
 

src/app/cli.py

@@ -41,6 +41,51 @@ def build_parser() -> argparse.ArgumentParser:
         help="Filesystem type for repacking. Default: from config or 'erofs'",
     )
     parser.add_argument("--eu-bundle", help="Path/URL to EU Localization Bundle zip")
+    parser.add_argument(
+        "--preflight-only",
+        action="store_true",
+        help="Run input preflight checks only, then exit",
+    )
+    parser.add_argument(
+        "--skip-preflight",
+        action="store_true",
+        help="Skip preflight checks before porting workflow",
+    )
+    parser.add_argument(
+        "--preflight-strict",
+        action="store_true",
+        help="Treat risk findings as failures in preflight checks",
+    )
+    parser.add_argument(
+        "--preflight-report",
+        default="build/preflight-report.json",
+        help="Path to write preflight JSON report (default: build/preflight-report.json)",
+    )
+    parser.add_argument(
+        "--enable-snapshots",
+        action="store_true",
+        help="Capture workflow snapshots at key stages",
+    )
+    parser.add_argument(
+        "--snapshot-dir",
+        default=None,
+        help="Snapshot directory (default: <work-dir>/snapshots)",
+    )
+    parser.add_argument(
+        "--rollback-to-snapshot",
+        default=None,
+        help="Restore target workspace from the named snapshot and exit",
+    )
+    parser.add_argument(
+        "--enable-diff-report",
+        action="store_true",
+        help="Generate before/after artifact diff report",
+    )
+    parser.add_argument(
+        "--diff-report",
+        default="build/diff-report.json",
+        help="Output path for artifact diff report (default: build/diff-report.json)",
+    )
     parser.add_argument(
         "--phases",
         nargs="+",