TelevyBackup

TelevyBackup 是 macOS desktop backup app + Rust backend。README.md 标记为 work in progress，但已经有 Rust workspace、macOS app build/run scripts、packaging 和 release workflow，说明它不是单 crate 实验。当前发布链路还把一次产品 PR 的 VERSION、merge SHA、tag、制品和 recovery 绑定成单一可审计的 release identity（docs/specs/product-version-release-chain/SPEC.md）。

• Tags: Rust workspace, Rust application, macOS app, Native macOS visual evidence, PR label release, Release failure notification, Quality gates
• Why / evidence: 这些 tags 来自 checked-out repo 和 catalog record。主要证据包括 README.md、Cargo.toml、crates/core/、crates/daemon/、crates/cli/、macos/、packaging/、scripts/macos/build-app.sh。Topic token 的大小写以对应技术/工作流的官方写法为准；slug 只作为稳定 ID，不直接充当项目标题。

• Cargo.toml 定义 workspace，members 包括 crates/core、crates/daemon、crates/cli，并排除 crates/mtproto-helper。
• macos/ 保存 macOS GUI app source/配置。
• scripts/macos/build-app.sh 与 scripts/macos/run-app.sh 是本地 app 构建运行入口。
• packaging/ 保存打包材料，.github/workflows/* 负责 CI/release。
• .github/release-contract.json 是产品版本与 identity contract；.github/scripts/release_chain.py、release_reservation.py、release_preparation.py 和 release_completion.py 分别承载版本解析、append-only refs、VERSION preparation 与完成 gate。
• .github/workflows/release-preparation.yml、release-completion.yml 与 release.yml 将 preparation、merge gate 和 mainline build/publish 分开；.github/workflows/notify-release-failure.yml 负责失败上下文。

开发需要 Rust stable 和 Xcode Command Line Tools。CLI/daemon 用 cargo build，macOS app 用 ./scripts/macos/build-app.sh，dev variant 可用 TELEVYBACKUP_APP_VARIANT=dev，prod-like 运行可启用 Keychain。发布前由 Release intent label gate、release-preparation 和 release-completion 逐层验证；主线发布只消费已绑定 identity，并由 .github/scripts/test-release-chain.sh、test-release-reservation.sh、test-release-preparation.sh、test-release-completion.sh 与 test-release-workflows.sh 覆盖合同。

架构分成 core domain、daemon、CLI 和 macOS GUI。Keychain 行为按 app variant 区分，这是 macOS app 记忆：dev 默认禁用 Keychain，prod-like 运行启用。未来备份引擎、daemon API 和 GUI 状态要保持 workspace 边界清楚。

证据锚点：README.md。

发布 identity 以最高合格 final vX.Y.Z tag 为唯一数字基线；prod 使用 final version，beta、rc、dev 使用同一 base 的精确 prerelease grammar，且 prerelease 不推进 final baseline（.github/release-contract.json、docs/specs/product-version-release-chain/SPEC.md）。

reservation 先于 VERSION preparation 创建，并通过 append-only 的 release-reservation、release-decision、release-bound 和 release-consumed refs 记录 claim、仲裁、merge binding 与 publication consumption；现有 ref 不更新、不删除、不 force-push（docs/adr/0010-release-identity-reservation.md、.github/scripts/release_reservation.py）。

发布失败只允许对相同 merge SHA/version/channel 做 same-SHA recovery；缺少 identity 的历史 merge 不能冒充 recovery，只能在单一边界上走显式、非空、只改 VERSION 的 version-only-release-pr，由新 PR merge SHA 产生新 identity（docs/specs/product-version-release-chain/SPEC.md、.github/scripts/release_preparation.py、.github/scripts/release_completion.py）。

窗口证据存在迁移状态：macos/TelevyBackupApp/UISnapshot.swift 仍使用 PDF/bitmap caching 预览和可见窗口枚举，不能作为当前严格的 WindowServer 证据；较新的 scripts/macos/capture-main-window.sh 与 capture-settings-window.sh 已开始绑定 PID、窗口语义和 screencapture -x -l，但仍需补齐 bundle identity、Accessibility 唯一性和歧义时 fail-closed。遗留路径只作为 Native macOS visual evidence 的负向样本，后续项目任务再迁移，不在本仓库修改下游脚本。

.github/workflows/ci-main.yml、ci-pr.yml、label-gate.yml、release-preparation.yml、release-completion.yml、release.yml、notify-release-failure.yml 和 review-policy.yml 表明 release intent、identity reservation、completion gate 与 failure notification 已接入；.github/quality-gates.json 将 release intent 和 completion 纳入 required checks。macOS app 还需要本地 Xcode 工具链验证，不能只看 Linux CI。release-intent.json 只是 run-bound 的 snapshot artifact；权威事实仍是 immutable refs、commit trailers、产品 tag 和已验证的 merge identity（docs/specs/product-version-release-chain/SPEC.md）。

• 把 core/daemon/cli 拆成 workspace crates，避免 GUI 直接承载业务逻辑。
• 用 app variant 管理 Keychain 行为，降低 dev 环境复杂度。
• macOS 打包脚本作为项目入口，写进 snapshot。
• 将窗口截图迁移拆成独立合同：先固定 target-window identity、fixture isolation 和 changed-surface matrix，再处理项目自身的 capture 实现；历史位图不作为正向证据。
• 先从 final tag 分配版本，再以 reservation/decision/bound/consumed append-only refs 固化 claim 与消费状态，避免把 VERSION 当计数器（.github/release-contract.json、docs/adr/0010-release-identity-reservation.md）。
• 把 prod、beta、rc、dev 的 channel grammar 与 final baseline 分离；same-SHA recovery 只复用原 SHA/version/channel，不计算 successor（.github/scripts/release_chain.py、docs/specs/product-version-release-chain/SPEC.md）。
• 将 normal preparation、version-only-release-pr 和 same-SHA recovery 作为不同 mode；version-only 补救产生新的 merge identity，不能伪装成旧 merge 的 recovery（.github/scripts/release_preparation.py、.github/scripts/release_completion.py）。
• 把 release intent snapshot 当作可丢失的 run context，恢复时回到 refs、trailers 与 product tag，避免 artifact 或 label snapshot 成为版本权威（.github/workflows/release.yml、docs/specs/product-version-release-chain/SPEC.md）。

• WIP 状态下功能边界仍可能变化。
• Keychain、sandbox、签名/公证可能成为 release blocker。
• CI 与本地 macOS 构建能力不完全等价。
• reservation refs 与 product tags 依赖受保护的 release automation 权限；远端权限、provenance 或 identity 不完整时必须保持 fail closed，不能退回到 VERSION、merge order 或 snapshot 计算版本（.github/release-contract.json、docs/adr/0010-release-identity-reservation.md）。

• README.md
• Cargo.toml
• crates/core/
• crates/daemon/
• crates/cli/
• macos/
• packaging/
• scripts/macos/build-app.sh
• scripts/macos/run-app.sh
• .github/workflows/ci-main.yml
• .github/workflows/label-gate.yml
• .github/workflows/release-preparation.yml
• .github/workflows/release-completion.yml
• .github/workflows/release.yml
• .github/workflows/notify-release-failure.yml
• .github/release-contract.json
• .github/quality-gates.json
• .github/scripts/release_chain.py
• .github/scripts/release_reservation.py
• .github/scripts/release_preparation.py
• .github/scripts/release_completion.py
• .github/scripts/test-release-chain.sh
• .github/scripts/test-release-reservation.sh
• .github/scripts/test-release-preparation.sh
• .github/scripts/test-release-completion.sh
• .github/scripts/test-release-workflows.sh
• docs/adr/0010-release-identity-reservation.md
• docs/specs/product-version-release-chain/SPEC.md