AirFerry: Instructions file for Codex

AGENTS.md — AI 代理操作手册

本文是给 AI 代理（以及人类开发者）的导航 + 操作索引：怎么构建、怎么定位代码、怎么排错、哪些坑别踩。 本文不重复 docs/*.md 的细节，每条都指向权威来源。跨端不变量的位级规格见 docs/SPEC.md。 遇到文档与代码冲突时，一律以代码为准（见下方「文档与代码偏差清单」）。 当本文与 docs/SPEC.md 互相矛盾时（如默认值、常量、行号），先去读对应权威源代码裁决——两份文档都可能滞后，切勿仅凭其中一份下结论。 每次改动代码后，必须同步更新相关文档：改动若涉及常量、默认值、行号、签名、帧格式、文件路径、构建步骤等任一被文档引用的事实，同一提交内回写 AGENTS.md / docs/*.md 的对应位置，勿留滞后（本次审计即是文档滞后于代码的教训）。

项目一句话

AirFerry：完全离线的光学文件传输。发送端把文件编成二维码视频流在屏幕上连续播放，也可由 Python 包输出 MP4；接收端用摄像头或屏幕捕获扫描恢复文件。各端共享同一套 Rust 核心库（WASM、Android Native .so、Windows DLL、Python/PyO3 扩展），编解码逻辑数学上一致。零运行期网络依赖、单向信道、无握手。

1. 仓库布局

AirFerry/
├── core/                       # Rust 协议核心（三个核心 crate；workspace 另含 apps/python）
│   ├── raptorq-core/           #   RFC 6330 RaptorQ 编解码封装（纯逻辑）
│   ├── qr-protocol/            #   帧格式 / 分块 / 压缩 / CRC / QR 矩阵 / 会话 ID
│   ├── transfer-engine/        #   编排 / 状态机 / 进度 / 断点 / 大文件分段组装 + WASM&JNI&C-ABI 绑定
│   └── zxing-decoder/          #   Windows ZXing-C++ 解码核心（非 Cargo crate）
├── apps/
│   ├── sender/                 # 浏览器扩展（Plasmo + React + TS + WASM）
│   │   ├── src/                #   TS 源码（页面 / WASM 桥 / 压缩 worker / background 图标点击直跳）
│   │   ├── wasm-pkg/           #   当前扩展目标的临时 WASM 快照（generated, git-ignored）
│   │   ├── assets/             #   扩展图标
│   │   └── scripts/            #   构建 / manifest 修正 / lzma-wasm 提取
│   ├── web/                    # 网页端（Vite + React + TS）— 直接复用 sender/src 源码，无代码重复
│   │   ├── src/main.tsx        #   薄入口：mount sender 的 App（options.tsx）
│   │   ├── scripts/            #   prepare-wasm（锁定并复制 sender simd 包 + 拷 zstd）/ lzma 提取
│   │   └── public/             #   wasm-zstd.wasm（worker 运行时 fetch，构建时拷入）
│   ├── scanner/                # Android App（Kotlin + CameraX + ZXing-C++）
│   │   └── app/src/main/
│   │       ├── java/com/airferry/app/   # Kotlin
│   │       ├── cpp/                     # ZXing-C++ JNI 桥（CMake）
│   │       └── jniLibs/arm64-v8a/       # Rust .so（cargo-ndk 产物, git-ignored）
│   ├── python/                 # Python 文件转 MP4（PyO3 + Pillow + 本地 FFmpeg；独立包版本）
│   └── windows/                # Windows App（C# WPF + OpenCvSharp + ZXing-C++）
│       ├── native/                     #   Windows ZXing C ABI 包装器 + CMake
│       ├── AirFerry.Windows/            #   主项目（Views/ViewModels/Models/Scan/Bundle/Native/Services/Themes；WPF-UI Fluent 主题）
│       │   └── runtime/                 #   transfer_engine.dll + airferry_zxing.dll（git-ignored）
│       └── AirFerry.Windows.Tests/      #   协议层单元测试（net8.0，跨平台可跑）
├── docs/                       # 协议 / 架构 / API / 构建说明（中文）
├── scripts/build-all.sh        # 一键构建脚本（含 windows 子命令）
├── scripts/build-windows.ps1   # Windows 端原生 PowerShell 构建脚本（首选）
├── Cargo.toml                  # Rust workspace 根配置
└── dist/                       # 发布产物 + 签名密钥（git-ignored）