场记单识别 · 结构校对 · Resolve CSV 回填
识别 PDF 或图片场记单，复核场、镜、次及条次状态， 再将确认后的结果写回 DaVinci Resolve CSV。
| 输入 | 处理 | 输出 |
|---|---|---|
| PDF、JPEG、PNG、WebP 场记单 | 本地逐页栅格化、OCR evidence、视觉模型识别、字段校验、版式 Profile 复用 | 保留原格式的 Resolve CSV |
| Resolve CSV、素材目录 | 条号对账、场镜次序检查、slate.txt 元数据读取 |
可预览、可校对、可导出的回填结果 |
| 项目库或项目包 | SQLite v1 校验、原子传输、导入导出与关闭重开回归 | 可迁移的项目与项目库数据 |
当前仓库保留两条有明确职责的架构基线：
| 分支 | 架构角色 | 开发规则 |
|---|---|---|
main |
Electron 主架构 | 维护现有 Electron 产品与兼容行为 |
swift-rewrite |
Swift/SwiftUI 原生架构 | 当前项目开发、验证和新功能的基线 |
当前开发分支默认从 swift-rewrite 创建，并以 swift-rewrite 为合并目标。
| 识别与理解 | 校对与回填 | 项目与安全 |
|---|---|---|
| 支持 macOS Vision OCR、可选 PaddleOCR，以及已配置的 OpenAI/兼容视觉模型。 | 导入 Resolve CSV，校验条号、场镜次序和识别完整性，确认后再导出。 | Project Library 使用 SQLite 保存项目、任务、诊断和场记结构 Profile。 |
| 根据 OCR 表头、坐标和页面版式学习并复用场记结构 Profile。 | 读取素材目录中的 slate.txt，补充 Camera FPS 和 Shoot Day。 |
项目库和项目包执行路径边界、符号链接和版本校验；API Key 使用本地 AES-256-GCM 加密文件。 |
| PDF 先在本地逐页准备，模型请求使用页面图片与 OCR evidence。 | 保留原 CSV 的编码、换行和未匹配字段，仅更新匹配到的字段。 | 所有自动测试使用隔离临时数据，不触碰用户项目库、日志或 Keychain。 |
- macOS 15.0 或更高版本。
- Xcode 26.3（17C529）。
- Swift 6.2.4、macOS 26.2 SDK。
- 当前 Release 目标为 arm64 与 x86_64 的 Universal app。
项目不需要安装 Node.js、npm 或 Electron 依赖。在仓库根目录执行：
./script/build_and_run.sh常用启动选项：
./script/build_and_run.sh --release # 构建并启动 Release
./script/build_and_run.sh --verify # 启动后验证本次构建的进程
./script/build_and_run.sh --logs # 启动并输出 SlateSync 日志
./script/build_and_run.sh --telemetry # 启动并输出结构化遥测日志
./script/build_and_run.sh --background # 后台启动也可以用 Xcode 打开 SlateSync.xcodeproj，选择共享 SlateSync Scheme，然后使用 Run、Test、
Profile 或 Archive。开发脚本和 Xcode 使用相同的工程配置。
手工验证时可以指定独立数据根，避免读写默认的 Application Support 和项目库：
SLATESYNC_TEST_ROOT=/private/tmp/slatesync-manual-test ./script/build_and_run.sh --verify在项目库或工作区的项目设置中，可以导入、导出独立项目包；项目库页面也支持整个 Project Library 的导入、导出、改名和迁移。导入会创建新的项目 ID，原项目不会被覆盖；任务、诊断证据、 场记结构 Profile、设置、时间戳以及任务中保存的图片和 CSV 数据会随项目保留。
v1 项目包使用目录格式而不是 ZIP，结构固定为：
<项目名>.slatesync-project/
├── slatesync-project.json
├── project.json
├── project.sqlite
├── tasks/*.json
└── diagnostics/*.json
项目库导入/导出不包含全局配置、API Key、OCR 环境与路径、日志或项目库索引。传输前会等待正在 进行的保存和项目写入；数据通过临时目录、SQLite online backup 和原子重命名完成。包校验会拒绝 符号链接、非法未来版本、同路径、嵌套路径和已存在目标。
备份优先使用应用的导出功能。手工复制 SQLite 数据库前应退出应用，避免遗漏 WAL 中尚未合并的 修改；升级或回退前请保存独立备份。
导入场记单
↓
PDF 逐页栅格化 → Vision/PaddleOCR → OCR evidence + 页面图片 → 视觉模型 → 字段归一化与版式匹配
↓
载入 Resolve CSV + 可选扫描 slate.txt
↓
条号对账 / 场镜次序检查 / 完整性告警
↓
回填预览 → 人工校对 → 导出 CSV
| 阶段 | SlateSync 会做什么 |
|---|---|
| 识别 | 本地准备 PDF 页面，提取文字、置信度和坐标，再由视觉模型抽取场、镜、次和条次状态。 |
| 学习 | 从 OCR 表头、坐标和版式生成场记结构 Profile，并在相似任务中复用。 |
| 对账 | 载入 Resolve CSV，检查条号缺失、场镜次序异常和识别完整性。 |
| 回填 | 只更新匹配到的素材与允许写入的字段，保留原 CSV 的编码、换行和其他内容。 |
| 方式 | 位置 | 适合场景 |
|---|---|---|
| macOS Vision OCR | 本地 | 基础文字与坐标识别，无需额外 OCR 安装 |
| PaddleOCR | 本地，可选安装 | 需要额外 OCR 引擎或本地处理能力 |
| OpenAI / OpenAI 兼容视觉接口 | 按设置配置 | 复杂版式、中文或手写内容的视觉理解 |
| Resolve 字段 | 数据来源 |
|---|---|
Scene |
场记单中的场次 |
Shot |
场记单中的镜 |
Take |
场记单中的次 |
Comments |
按设置写入过条、保条标记；其他情况为空 |
Camera FPS |
素材目录 slate.txt 的 Sensor FPS |
Shoot Day |
素材目录 slate.txt 的 Shot Date |
字段无法确认时不会被强行写入，必须人工校对。合并导出不会因为单纯的位宽规范化而掩盖没有 匹配到完整素材记录的情况。
SlateSyncApp（SwiftUI 应用入口）
└─ SlateSyncUI
└─ SlateSyncWorkflow
├─ SlateSyncMedia
├─ SlateSyncPersistence
└─ SlateSyncDomain
SlateSyncApp/Resources/PaddleOCR
└─ runner 源码与固定依赖清单
SlateSyncDomain：领域类型、验证、设置、Provider、OCR、识别和错误合同。SlateSyncPersistence：SQLite v1、项目包、Project Library、设置、本地加密凭据和日志。SlateSyncMedia：PDF/图片准备、Vision/Paddle OCR、OCR 进程与资源生命周期。SlateSyncWorkflow：CSV、场景、Provider、识别、版式 Profile 和安装编排。SlateSyncUI：原生窗口、项目库、工作区、CSV、设置、帮助和日志界面。SlateSyncApp/Resources/PaddleOCR：唯一的 Paddle runner 与 requirements 来源。Tests、SlateSyncTests、SlateSyncUITests：SwiftPM 单元/合同测试与 Xcode UI 验收。
业务状态和文件/进程生命周期由 Swift concurrency、actor 和隔离的数据服务管理；应用不会
携带旧 Electron/Node 运行时。历史迁移材料保存在 .codex/refactor/ 和
.codex/swift-migration/，不参与运行或打包。
应用内的“全局设置”用于管理 Provider、Base URL、模型、请求并发/超时、Vision OCR、PaddleOCR
和模型缓存路径。自定义 OpenAI 兼容接口支持多个连接和手动模型 ID；API Key 使用 Apple CryptoKit AES-256-GCM 加密保存到本机 Credentials/provider-keys.enc，
随机主密钥保存在独立 Credentials/master.key（目录 0700、文件 0600）。无需钥匙串授权；
同时取得两文件的人仍可解密。旧密钥不迁移，请重新填写。凭据不写入项目包、项目库或 Git。
机器设置、非敏感配置和日志位于：
~/Library/Application Support/SlateSync/
默认项目库位于：
~/Library/Application Support/Local SlateSync Library/
也可以在应用中选择其他项目库位置。全局设置按机器用户保存，不随项目包导入/导出。
原生默认配置位于 Sources/SlateSyncPersistence/Resources/slatesync.config.json，随应用打包。
开发运行可显式设置 SLATESYNC_CONFIG_PATH；没有指定路径且工作目录不存在配置时，使用原生资源默认值。
打包应用使用包内配置。路径在启动时确定，内容在每次操作时重新校验；首次读取失败会停止相关操作，
后续无效编辑保留最后有效版本。
slate.maxDirectoryDepth 控制原生元数据扫描深度，scenario.matching 控制识别时的结构匹配。
resolve 为新建项目提供初始格式；现有项目与任务的显式设置优先，不被全局配置覆盖。
正常启动会自动将项目库索引、项目设置、任务、诊断、场记 Profile 和 JSON 快照转换为 AES-256-GCM 加密存储。加密密钥保存在本机 macOS 登录钥匙串，无需 Apple 开发者账号。 旧数据逐文件迁移，认证失败或密钥不可用时停止，保留原文件供恢复。
原始媒体与媒体缓存、机器级配置和日志不在此加密范围。应用内导出的 CSV、项目包和项目库 保持通用格式；导入到本地项目库后重新加密。迁移时请关闭其他旧版 SlateSync。
跨 Mac 或备份给其他软件使用时，请通过应用内导出。直接复制内部加密目录仍需要原钥匙串； 丢失密钥无法解密。迁移不会清除已有系统备份或磁盘历史快照中的旧明文数据。
内部 SQLite 在内存中查询并以加密快照原子落盘，避免新增明文数据库日志；这会增加大型 项目库的内存与读写开销。该加密边界保护本地文件内容，不隐藏目录名称，也不替代整盘加密。
PaddleOCR 是可选功能。App 只携带 runner 源码和固定依赖清单，不携带 Python、虚拟环境或模型缓存。
安装需要用户选择的 Python 环境和网络；当前固定版本为 paddlepaddle==3.3.1 与
paddleocr==3.7.0。自动 Gate 不执行联网安装。
真实离线模型推理需要显式提供隔离的 SM06_PADDLE_RUNTIME_FILE：
./script/paddle_offline_check.sh- Project Library 和每个项目使用 SQLite v1；迁移和导入会执行版本、路径和内容校验。
- 项目库边界拒绝越界路径和符号链接，文件写入使用临时文件与原子替换。
- API Key 只由原生应用的数据服务读取，UI 不直接访问凭据或任意文件系统能力。
- PDF 原始字节只用于本地逐页栅格化；模型请求发送页面图片与本地 OCR evidence，不发送原始 PDF。
- OCR 引擎不可用、超时或失败时会按设置降级为页面图片识别；设置为必需时则停止识别并报告错误。
- 自动测试只使用临时数据根，不应指向个人 Project Library、日志或 Keychain。
- 不要将用户项目库、
data/、凭据、模型缓存或本地安装环境提交到 Git。
SwiftPM 基线：
swift build
swift test项目合同和发布链路测试：
./script/tests/phase_gate_tests.zsh
python3 -B script/tests/sm09_release_contract.py
python3 -B script/tests/packaged_ui_contract.py --self-test
./script/tests/release_pipeline_tests.zsh
python3 script/tests/sm09_coverage_tests.py
python3 script/tests/sm09_inventory_tests.py修改 workflow、UI 用例或打包清单后，先运行上述契约和 Gate 自测。CI 会在构建前执行预检；
Debug 合成 Provider 用例必须全部通过，打包 Release 的实际执行名称必须与交付回归清单一致。
失败诊断工件包含完整 .xcresult.zip、测试树、汇总、截图/AX 附件和运行器日志。
日常本机验证优先使用 ./script/ci_preflight.sh：只运行契约和自测，不启动应用、切换窗口或采集前台画面。
完整 SM-09 与原生 UI、打包 Release UI 在 GitHub macOS runner 上执行；预检通过仅代表准备完成，
完整通过以同一提交的远端 native-test 和 UI 覆盖证据为准。本机前台验收仅在用户明确安排时进行。
./script/archive_release.sh /private/tmp/SlateSync-release 1.1.0 2脚本会在仓库外的新目录中生成 Universal SlateSync.xcarchive，并验证最低 macOS 版本、
架构、资源、签名、hardened runtime 和依赖。版本号和 build number 是显式输入，不会改写
已跟踪的工程文件。
- 当前仅支持 macOS 15.0 及以上版本，不提供 Windows 或 Linux 运行时。
- PaddleOCR 需要用户提供 Python 环境和网络安装条件；Python、虚拟环境和模型不包含在 App 中。
- 无法确认的识别字段不会被强行写入，必须人工校对。
- 项目库与项目包当前保持 v1 格式；升级、迁移或回退前应保留独立备份。