项目快照整目录上传 .agent，保留项目身份与 Agent 历史

- 新增 should_skip_project_snapshot_sync_path：快照同步放行 .agent 组件，并放行其中 .db / .db-wal / .db-shm 的 Agent 状态数据库 - 组件与后缀排除表提取为常量；should_skip_project_snapshot_path 行为不变，项目索引、checkpoint、Agent 上下文与 git 检查继续排除整个 .agent - project_snapshot 扫描入口切到新口径，.agent 的 manifest、agent.db、会话、日志、checkpoint、workbench 与 project.lock 全部参与同步 - 新增整目录扫描用例与策略用例，覆盖 .agent 内凭据、.env、版本库与构建目录仍被排除 - 主规范更新上传内容边界与后台归档范围：工程 ZIP 可用于还原项目身份与 AGC 对话历史 - 里程碑、实施计划与共享记忆决策记录同步 .agent 全量口径、真实上传与后台 ZIP 的运行时验证证据，以及 v1/v2 键布局边界
2026-09-22 16:38:39 +08:00
parent fdc14404b2
commit bba4f0eb24
8 changed files with 232 additions and 75 deletions
@@ -1824,7 +1824,8 @@ Direct 回合的所有权属于进程内项目身份锁，不属于当前页面
 - 失败关闭：单个文件失败不推进该文件的索引项，失败文件与剩余文件在下一次周期或下次关闭时重试。鉴权失败（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）各有上限，超限文件进入跳过或延后清单而不是静默丢弃。
+- 上传内容边界：`.agent` 是项目身份与 Agent 状态的权威位置，**整目录参与同步**（`manifest.json`、`agent.db` 及其 WAL/SHM、conversations、logs、checkpoint、workbench、`project.lock`、`.manifest.json.lock`）。因此快照同步使用独立口径 `should_skip_project_snapshot_sync_path`：它与 `should_skip_project_snapshot_path` 共用同一份组件与后缀规则，只额外放行 `.agent` 组件本身，以及 `.agent` 内的 Agent 状态数据库后缀（`.db`/`.db-wal`/`.db-shm`）。其余排除项在 `.agent` 内同样生效——版本控制目录、`node_modules`/`target`/`dist`/`build`/`coverage`/`.cache`、凭据目录、`.pem`/`.key`/`.sql` 等敏感后缀与 `.env*` 都不参与同步；符号链接与重解析点在扫描阶段跳过（不能被当作普通文件传输）。单文件（64 MiB）与单次同步总量（512 MiB）各有上限，超限文件进入跳过或延后清单而不是静默丢弃。
+- 该口径只对快照同步生效：项目索引、checkpoint、Agent 上下文与 git 检查继续排除整个 `.agent`。收录 `.agent` 意味着会话记录、运行日志与诊断快照随项目离机并写入该用户自己的私有前缀，这是本轮产品决定（远端工程包要能还原项目身份与 AGC 历史），不是遗漏。

 ### 契约与兼容

@@ -1848,7 +1849,7 @@ Direct 回合的所有权属于进程内项目身份锁，不属于当前页面
 - `GET /admin/api/project-snapshots/{userId}/{projectId}/download` 只读取该用户/项目的固定清单与其引用对象，返回 `application/zip` 附件。ZIP 中路径直接使用原始相对路径，不包含 userId、摘要目录或 OSS 前缀；名称使用经过安全处理的项目名和 revision。下载固定本次读到的清单，远端并发回收导致对象缺失则整体失败，不能静默遗漏。
 - `partial` 快照下载返回 409；`unverified` 历史快照可导出已同步文件，列表明确显示“完整性未知”，动作称“下载已存文件”。`ready` 才显示“下载完整工程”。ZIP 构建核验每一文件的长度与 fnv1a64 摘要，拒绝穿越、绝对路径、重复/大小写冲突路径、非法项目身份；缺失或损坏整体失败，不返回成功的残缺 ZIP。
 - ZIP 使用服务端临时文件并限制并发，不将 2 GiB 工程整体驻留内存；成功、失败、客户端取消均清理临时文件。单文件、总量、文件数沿用上传上限，超限明确拒绝。零字节工程文件可以上传和导出。OSS 凭据与签名不下发浏览器，列表失败保留错误而非伪造空列表。
- 工程归档范围与上传策略一致：源码、素材及引擎配置按原路径保存，依赖/构建缓存、凭据、`.agent` 会话与运行日志排除；此 ZIP 不声明能恢复 AGC 对话历史。后台读取需要目标前缀的 ListObjects 与 GetObject 权限，不新增数据库表，不改 External API。
+- 工程归档范围与上传策略一致：源码、素材、引擎配置与 `.agent`（含会话、运行日志、checkpoint、`agent.db`）都按原相对路径保存，依赖/构建缓存与凭据排除；因此该 ZIP 可以还原项目身份与 AGC 对话历史（归档只保证字节还原，不承诺跨机器可用性）。后台读取需要目标前缀的 ListObjects 与 GetObject 权限，不新增数据库表，不改 External API。
 - 验收覆盖真实单窗口生命周期登记、首次/增量/零字节上传、后台列表分页和权限、ZIP 解压目录及摘要、部分/历史清单、缺失对象、路径拒绝、下载取消清理，并分别报告定向测试和真实环境证据。

 ### 未决问题