补齐 AGC 项目快照的回收、配额、可见性与一致性校验

- 服务端在清单写入成功后回收上一版清单不再引用的对象，单次最多 2000 个，上一版不可读时整轮跳过
- 服务端新增单项目 2 GiB 上限（413）、同一项目 5 秒最小清单间隔与用户小时配额（429 + Retry-After）
- 客户端新增单项目上限预判，并把单次同步预算改名为 MAX_SYNC_BYTES，避免与项目上限混淆
- 客户端在读取摘要后与上传前各复核一次文件元数据，同步期间被改写的文件不上传、不推进索引、也不被误判成删除
- 客户端新增 file-changed 与 throttled 两类可重试失败，429 计入可重试而不是终态失败
- 新增工作区「项目快照」面板：显示上传状态、上次同步时间、同步序号、已纳管文件数与最近一次同步计数，支持刷新与立即同步
- 新增面板前端测试，并把两条快照命令从 check-config 的 native-only 白名单移入前端 invoke 名单
- 部署模板补充 AGC 项目快照 OSS 变量，api-server 启动时打印启用状态与凭据来源
- 同步主规范、里程碑、开发运维文档

docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md

@@ -1529,8 +1529,8 @@ Direct 回合的所有权属于进程内项目身份锁，不属于当前页面
 
 ### 目标与非目标
 
-- 目标：AGC 在项目工作区打开期间按固定周期把用户项目增量上传到 OSS `agc-dev`，并在项目关闭（工作区窗口关闭、切回启动器、应用退出）时立即补一次同步；重复内容不重复上传。
-- 非目标：不做云端下载/恢复、不做跨设备合并、不做远端多余对象清理、不新增 UI 面板、不修改 `/api/external/v1` 与 OpenAPI、不新增 SpacetimeDB 表。
+- 目标：AGC 在项目工作区打开期间按固定周期把用户项目增量上传到 OSS `agc-dev`，并在项目关闭时立即补一次同步；重复内容不重复上传，远端占用跟随当前清单收敛，用户可在项目里查看同步状态并手动触发。
+- 非目标：不做云端下载/恢复、不做跨设备合并、不保留多版本历史、不修改 `/api/external/v1` 与 OpenAPI、不新增 SpacetimeDB 表。
 - 非目标：不把 OSS AccessKey 放进客户端；客户端不直连 OSS。
 
 ### 参与入口、状态与跨模块边界
@@ -1538,7 +1538,8 @@ Direct 回合的所有权属于进程内项目身份锁，不属于当前页面
 - 触发入口有两个：工作区窗口 `main` 存活期间的周期定时器、工作区窗口关闭事件（`CloseRequested`）。两者共用同一个进程内同步器，同一项目的同步串行执行，周期触发在已有同步进行时直接让位，不排队堆积。
 - 应用退出（`RunEvent::Exit`）不重复发起同步：该时刻窗口已销毁，按窗口重新枚举项目只会得到空集；退出路径只负责在有界预算（15 秒）内等待在途同步收尾，让关窗触发的那一次同步能写完索引再退出。
 - 客户端扫描、差异对比、索引持久化与上传编排都在 Tauri Rust 进程（`src-tauri/src/project_snapshot/`）；WebView 只读状态，不参与差异计算。
-- 本地索引是增量对比的唯一依据：`<AppData>/project-snapshots/<projectId>/index.json` 保存上次成功同步的相对路径、`sha256`、字节数和修改时间。项目根使用现有 manifest 的稳定 `project_id` 作为远端身份，路径不再作为身份。
+- 本地索引是增量对比的唯一依据：`<AppData>/project-snapshots/<projectId>/index.json` 保存上次成功同步的相对路径、校验和、字节数和修改时间。项目根使用现有 manifest 的稳定 `project_id` 作为远端身份，路径不再作为身份。
+- 界面入口：工作区聊天头部的「项目快照」按钮打开独立面板（`ProjectSnapshotDialog`），显示上传状态、上次同步时间、同步序号、已纳管文件数、本地索引是否写入，以及最近一次同步的上传/远端已有/删除/延后计数与失败明细；面板提供「刷新」与「立即同步」。面板不写功能说明文案，只用标签与数值。
 - 远端写入经 `api-server`，客户端只持平台登录态 Access Token。两条登录态路由：`POST /api/agc/project-snapshots/files`（单文件，正文为原始字节，元数据走查询串）与 `POST /api/agc/project-snapshots/manifest`（本次同步后的完整清单）。
 - 对象键与清单由服务端决定：文件键为 `agc/project-snapshots/v1/{userId}/{projectId}/files/{sizeBytes}-{checksumDigest}/{relPath}`，清单键为 `agc/project-snapshots/v1/{userId}/{projectId}/manifest.json`。键里带字节数与摘要，因此"对象已存在且长度一致"可以作为内容一致的判据；路径按原始大小写保留，不走 `put_object` 的低位规范化。`agc` 前缀继续是服务端专用私有前缀，通用对象键解析与客户端直传票据都不覆盖它。
 - 目标 bucket 使用独立配置 `GENARRATIVE_AGC_PROJECT_SNAPSHOT_OSS_BUCKET` / `_ENDPOINT` / `_ACCESS_KEY_ID` / `_ACCESS_KEY_SECRET`，默认 `agc-dev` + `oss-rg-china-mainland.aliyuncs.com`，未配置时回退 `ALIYUN_OSS_*`；与"资源 bucket 与备份 bucket 分离"的既有口径一致。
@@ -1546,27 +1547,33 @@ Direct 回合的所有权属于进程内项目身份锁，不属于当前页面
 ### 正常、失败、重试与幂等行为
 
 - 差异对比口径：先按 `相对路径 + 字节数 + 修改时间` 判定是否候选变更，命中旧记录则复用已存 `sha256`，只有 `(size, mtime)` 变化才重算摘要。产出新增、修改、删除三类集合，只上传新增与修改的文件。
-- 每次成功同步的最后一步上传该项目的 `manifest.json`（当前全量文件清单：相对路径、摘要、字节数、同步序号）。删除文件只在清单中消失，本期不删除远端对象；远端清理留给后续里程碑。
+- 每次成功同步的最后一步上传该项目的 `manifest.json`（当前全量文件清单：相对路径、摘要、字节数、同步序号）。清单描述的是项目当前全量内容，因此清单体积就是该项目在 OSS 上的常驻占用。
+- 远端回收：清单写入成功后，服务端读取上一版清单，按 `(路径, 字节数, 摘要)` 反推出不再被当前清单引用的对象键并删除。只处理上一版清单登记过的键，不做 LIST，因此不可能误删其它项目或其它功能的对象；单次最多回收 2000 个对象，剩余部分留到下一次清单写入继续；上一版清单读不到或解析失败时整轮跳过回收（fail-closed）。单个删除失败只记日志，不影响本次同步语义。
+- 因此本功能是"当前状态镜像 + 清单"，不保留历史版本：同一路径的内容变化会覆盖式替换远端对象，回滚能力不在本轮范围内。
 - 幂等：同一摘要与字节数的对象重复提交由服务端 HEAD 校验后跳过；探测失败按"未存在"处理并照常 PUT，宁可多传一次也不漏传。索引只在清单写入成功后推进，失败时保留旧索引以便下次重算。
-- 失败关闭：单个文件失败不推进整次同步的完成位，失败文件与剩余文件在下一次周期或下次关闭时重试。鉴权失败（401/403）、权限、额度与身份类失败不做自动重试，只记录分类结果并等待用户重新登录后的下一次触发。
+- 与项目写锁解耦：同步不持有项目写锁，也不阻塞 Agent 写入。读取摘要后与上传前各按 `(字节数, 修改时间)` 复核一次，任一处不一致就判定该文件"同步期间发生变化"：本轮不上传、不写入索引；若该路径上一轮已同步过则沿用旧记录，避免被误判成删除而触发远端回收。这类文件在下一个周期或下次关窗时重算重试。
+- 失败关闭：单个文件失败不推进该文件的索引项，失败文件与剩余文件在下一次周期或下次关闭时重试。鉴权失败（401/403）与格式类拒绝（400/413）是确定性失败，停止本轮剩余请求并等待用户处理后重试；服务端配额或频率拒绝（429）与传输类失败按可重试处理。
+- 配额与限流：单文件 64 MiB、单次同步上传预算 512 MiB（超出部分延后到下一次）、单项目常驻上限 2 GiB（客户端在扫描后先判，超限直接给出明确失败；服务端按清单累计体积复核并返回 413）；服务端按用户做进程内小时配额（文件 3000 次、清单 120 次）并对同一项目强制 5 秒最小清单间隔，超限返回 429 且带 `Retry-After`。进程内配额只用于抑制异常客户端与失控重试，跨节点配额由"单项目上限 + 清单引用回收"保证。
 - 生命周期：同步有界超时（单文件与整次同步分别设上限），项目关闭与应用退出路径不因同步失败而阻塞或延迟退出超过超时上限。
 - 上传内容边界：复用项目索引与 checkpoint 同一份 `should_skip_project_snapshot_path` 口径——整个 `.agent`（含 runtime、logs、checkpoint、manifest、project.lock）、版本控制目录、`node_modules`/`target`/`dist`/`build`/`coverage`/`.cache`、凭据目录与 `.pem`/`.key` 等敏感后缀都不参与同步；符号链接与重解析点同样跳过。单文件（64 MiB）与单次同步总量（512 MiB）各有上限，超限文件进入跳过或延后清单而不是静默丢弃。
 
 ### 契约与兼容
 
 - 新增登录态内部路由 `POST /api/agc/project-snapshots/files`，请求 DTO 放在 `shared-contracts`；不属于 `/api/external/v1`，因此不更新 External OpenAPI，与 `/api/error-reports` 同类。
-- 服务端校验 `projectId` 形态（拒绝路径分隔符、`..`、控制字符与超长值）、相对路径规范（正斜杠、拒绝绝对路径与穿越）、摘要形态（64 位十六进制）和字节数上限，任何越界返回 4xx 而不是写入 OSS。
+- 服务端校验 `projectId` 形态（拒绝路径分隔符、`..`、控制字符与超长值）、相对路径规范（正斜杠、拒绝绝对路径与穿越）、摘要形态（`fnv1a64:` + 16 位十六进制）和字节数上限，任何越界返回 4xx 而不是写入 OSS。
 - 不改变客户端与 Runner 的本机协议、平台会话语义、项目写锁与 manifest 结构；新增索引文件位于 AppData，不进入用户项目目录。
 
 ### 验收标准与证据来源
 
 - 定向 Rust 测试：首次同步全量、仅改一个文件时只产生一个修改项、删除文件只体现在清单、`(size,mtime)` 未变时复用旧摘要、排除规则与上限跳过、同步失败不推进索引、同一项目并发触发串行化。
-- 服务端测试：越界 `projectId`/相对路径/摘要被拒；相同摘要重复提交走跳过分支；鉴权缺失返回 401；OSS 未配置返回明确的 5xx 而不是写入空对象。
+- 服务端测试：越界 `projectId`/相对路径/摘要被拒；相同摘要重复提交走跳过分支；超过单项目上限返回 413；超过用户小时配额返回 429；鉴权缺失返回 401；OSS 未配置返回明确的 5xx 而不是写入空对象。
+- 前端测试：面板打开即读取索引状态并显示同步序号与文件数；手动同步后显示上传计数并刷新状态；同步失败显示错误而不是伪造成功。
 - 运行时 smoke：AGC 开发态打开项目、观察索引写入与同步日志、关闭工作区窗口后确认关闭触发的那次同步执行；报告为"客户端 diff 已验证 / 服务端已配置环境联调"两层，不合并成一句"已通"。
 - 边界：新增日志与错误文案不含 Access Token、AccessKey、绝对路径与项目内容。
 
 ### 未决问题
 
-- 远端删除对象清理、配额与保留策略未定；本期只写清单，OSS 侧对象只增不减。
-- 目标 bucket 的私有前缀权限与生命周期规则（例如转低频/过期删除）需要在部署环境确认后单独收口。
-- 大项目（素材数量多、单文件大）的首轮全量上传耗时与带宽占用未实测；必要时后续里程碑引入并发上限与断点续传。
+- 历史版本：本轮只保留"当前状态镜像 + 清单"，旧内容对象在清单写入成功后即被回收，没有回滚能力；要保留历史版本需要先定"保留几个 revision + 由谁回收"的策略。
+- 用户级配额：跨节点的用户总量配额与计费口径未定；当前用单项目 2 GiB 上限 + 清单引用回收保证常驻占用有界，用户级总量只能靠项目数间接约束。
+- 目标 bucket 的生命周期规则（例如转低频/过期删除）需要在部署环境确认后单独收口；功能本身已不再依赖它来控制增长。
+- 大项目（素材数量多、单文件大）的首轮全量上传耗时与带宽占用未实测；单次预算 512 MiB 会把超出部分留到下一次同步，但并发上限与断点续传仍未引入。