Instagram 多手机工作台 2.4.0 / fleet-v1 数据协议

交付基线
2.4.0 是唯一源码基线。完整解压到新目录，Windows 先运行根目录“首次配置电脑.cmd”，再运行“启动控制台.cmd”。Mac 首次准备由负责人完成，日常运行“启动控制台.command”。没有旧版本兼容加载、旧 USB 路径或旧配置迁移流程。
release.json 是版本来源；构建时会把版本注入 Windows快速开始.txt 和 fleet-static/help.html 的下载链接。未来的小改动用新的版本号，通过网页 ZIP 更新。

项目布局
core/：纯页面解析、精确账户识别、导航决策、重试策略、设置范围、路径和值类型；不读文件、不联网、不运行子进程。
device/：WDA、USB 转发、设备探测、组件和镜像、进程生命周期、Windows Apple 连接支持、下载、SQLite、隧道。
app/：HTTP 服务、电脑准备、设备生命周期、单项任务、批次调度、执行开关、更新和启动。
tools/：构建与验收 CLI。app 不能导入 tools，复用环境检查位于 device/environment.py。
tests/：离线回归和架构门禁。fixture 中的设备响应不是实体手机验收。
fleet-static/：网页控制台、电脑准备和教程。
依赖方向为 app → device → core，包内禁止循环。开发仓库根目录有 AGENTS.md、STANDARD.md 和 docs/（不随安装包分发）；详细职责见 docs/architecture.md。

运行与数据
电脑端服务是 app.server，生产运行环境位于项目根 work/usb-control/venv，日常启动由 app.launcher 装配。
项目根 work/fleet 保存 SQLite、任务事件、截图和页面 XML等运行数据；每部手机独立使用 UDID、WDA 端口和任务进程。work/service 保存电脑设置、启动、环境检查和连接日志。它们不进入源码 ZIP。
一个设备的任务按队列串行，多设备可以并行。断线、账号不符、组件过期或环境失败只处理对应设备，不把已处理条数视作关注成功。
重启后保留记录和设置，重新核验设备就绪与账户。持久化“ready”记录不能代替当前手机检查。

电脑和手机准备
Windows 首次配置准备 Python 3.13 x64、锁定依赖、开发者镜像、Apple 驱动和连接服务。电脑通过不代表手机通过。
手机须用 USB 连接、解锁、信任电脑，完成开发者模式和组件信任。准备流程检查组件授权、有效期、WDA 启动、画面和当前账户。
iOS 17.0–17.3 在 Windows 上直接拒绝并提示升级到 17.4+。此行为不改。
开发者镜像从固定自家 tools 下载目录获取，并核对大小和 SHA256。取不到就报错，不退回其它镜像。device.image_mount 在自己的子进程内适配锁定的设备库，只使用已经验证的本地镜像；iOS 27 的官方 RSD 重试仍保留。没有已发布固定镜像的系统会明确失败，不自动下载第三方镜像。
手机组件目录按 UDID 和有效期匹配。当前正式签名组件授权两台测试机，使用 Team 7ZD954FC3D 的新 Bundle ID；有效期受签名证书较早的 2027-10-15 15:18:15 UTC（北京时间23:18:15）限制。Mac+iPhone SE 的新签名仅验证已有单独证据；Windows和另一台手机的新签名实机仍待验收。发布目录不会自动迁移现有工作台的旧 Bundle ID 绑定；免费签名路径仍未验收。

任务和结果
“仅验证（dry_run）”检查精确目标身份和流程，不点击关注；它也不等于已经关注。真实关注必须由所有者授权。
固定导航和页面判定在 core；模型是辅助。任务取消和页面异常均保留失败原因；截图和事件记录不代表动作成功。录屏调试功能已按所有者要求移除，不需要安装 FFmpeg/FFprobe。
结果保留事件、截图、XML 与失败原因。不确定结果需人工核实，不能因为点击返回或处理数增加就自动当成功重试。

网页更新
上传当前项目构建的 ZIP，先核对逐文件清单、大小、SHA256、Python 语法和版本一致性。执行停止、设备空闲、电脑准备结束后才能安装。
安装先验证候选导入，备份原源码和 SQLite，替换文件后重启；work 中的数据保留。新进程核对版本后记录 installed，执行保持停止。
USB/DDI 的必需更新文件位于 device/usb_control.py、device/usb_forward.py、device/image_mount.py；更新还包含当前 app/core/device/tools/tests、静态资源和配置，不接受旧的顶层 USB 文件路径。

开发与验证
开发解释器锁定 Python 3.13：仓库根 .venv。Mac 运行环境可能是其它版本，不能混用作交付验收。
开发依赖在仓库根 requirements-dev.txt；前端离线回归使用 Node.js 24，已纳入同一 unittest 命令。Node.js 仅用于开发测试，不是产品安装依赖。Windows 运行依赖在应用目录 requirements-windows-lock.txt。

唯一单元测试命令：
cd /Users/apple/Documents/workspace/instagram-usb-control/outputs/instagram-control
../../.venv/bin/python -B -m unittest discover -s tests -t . -p 'test_*.py'

完整门禁（同一应用目录）：
../../.venv/bin/python -B -m tools.check_all
Windows 开发环境运行 check-all.cmd。它依次执行 ruff、pyright、import-linter 和全部 unittest（包含架构测试）。CI 必须执行同一入口。

源码包构建和核验（同一应用目录）：
../../.venv/bin/python -B -m tools.build_release --output-dir ../../dist
../../.venv/bin/python -B -m tools.build_release --verify ../../dist/Instagram_USB_Fleet_2.4.0.zip

隔离更新验收（同一应用目录，仅临时源码、数据库和本机端口）：
../../.venv/bin/python -B -m tools.check_release_lifecycle --package ../../dist/Instagram_USB_Fleet_2.4.0.zip
--installed-package 可指定初装包，配合仅验收用的新版本候选检查未来小版本更新；不用于兼容历史版本。
此工具不扫描 USB、不操作手机，不代表 Windows 或真机通过。

验收证据边界
自动测试、Mac 真机、Windows 接实体 iPhone 必须分别记录。Windows 接实体 iPhone 从未验收过。WP1–WP5 工程化阶段没有真机操作和线上发布；后续 WP6 发布与签名证据见开发仓库中的独立交付记录。
本次 Mac 证据限于离线单元/依赖回归、隔离 HTTP 更新/重启和启动入口 --help；不能冒充真实手机或 Windows 安装。
Windows 原生安装 CI 脚本已修正模块路径并同步本地副本；配置存在不等于本次 CI 通过。
线上部署和支持文件上传属于 WP6，已获所有者批准后单独执行。发布后必须在浏览器打开教程、下载安装包并核对 SHA256；命令行和源站可访问不能替代浏览器验收。
当前任务与证据见仓库 docs/acceptance.md、docs/known-issues.md、docs/tasks.md、docs/engineering-report-2.4.0.md。
