AGC 项目定时快照上传（目标 OSS agc-dev） #400

Merged

kdletters merged 6 commits from codex/agc-project-snapshot-upload into master 2026-09-17 18:34:51 +08:00

Conversation 0 Commits 6 Files Changed 25

+3543 -6

kdletters commented 2026-09-17 15:50:13 +08:00

Member

Copy Link

Copy Source

交付内容

• 客户端新增 project_snapshot 模块：项目扫描与排除口径、增量索引、差异对比、上传编排、状态查询。
• 触发：工作区窗口存活期间的周期定时器 + 工作区窗口关闭（CloseRequested）；应用退出只在有界预算内等待在途同步收尾，不重复发起。
• 服务端新增两条登录态路由 POST /api/agc/project-snapshots/files 与 /manifest，由 api-server 用服务端凭据写入私有前缀 agc/project-snapshots/v1/{user}/{project}/；客户端不持有 OSS 凭据、不直连 OSS。
• platform-oss 新增内部对象精确写入与探测、项目快照对象键构造；修复 head_internal_object 读 HEAD 响应长度恒为 0（会导致服务端"已存在即跳过"永不生效）。
• shared-contracts 新增 agc_project_snapshots DTO 与项目 ID、相对路径、摘要校验。
• 真实 OSS 存储层冒烟示例 + 客户端真实链路冒烟用例（#[ignore]，env 驱动）。
• 登记 check-config.mjs 的 native-only 命令白名单，恢复 npm run agc 可启动。

验证证据

• 存储层：cargo run -p platform-oss --example agc_project_snapshot_live_smoke 对真实 agc-dev 完成写入 → 读回（contentLength 32）→ 清单写入 → 探针清理。
• HTTP 层：登录态下 7 项校验（401 无 token、400 路径穿越/长度不一致/非法摘要/空正文/重复路径清单）全部符合预期且不写对象。
• 客户端链路（真实项目 gameagent-033b6cf3…）：第一次 synced uploaded=6 uploadedBytes=36694 remoteSkipped=6，紧接着第二次 no-op uploaded=0。
• GUI 触发：trigger=periodic ... uploaded=6；把周期设为 600 秒排除干扰、改一个文件后关窗得到 trigger=project-close ... revision=2 uploaded=1，索引摘要由 28d837cd84f8ab62 推进到 bff34e2e336d901f（同步在进程退出前完成）。
• 门禁：AGC project_snapshot 14 passed（+1 ignored live）、api-server project_snapshots 3 passed、platform-oss 39 passed、shared-contracts 87 passed、cargo fmt --check（两处）、check:encoding、check:doc-index、git diff --check、check-config.mjs 全部通过。

已知未决（不阻塞本里程碑）

• 远端对象只增不减：没有删除路径，也没有 bucket 生命周期规则；要收口需要先定保留语义（清单引用 GC 还是 OSS 生命周期）。
• 部署环境需确认 GENARRATIVE_AGC_PROJECT_SNAPSHOT_OSS_* 或回退的 ALIYUN_OSS_* 具备目标 bucket 私有前缀的 PutObject 权限；未配置时接口返回 503、客户端失败关闭（不推进索引）。
• 缺少按用户/项目的配额与限流（error_reports 有每小时提交上限的先例，本功能没有）。
• 没有界面入口与状态可见性：read_local_project_snapshot_state 已注册但未接 UI，失败只写本机日志。

不做

• 不做云端下载/恢复、跨设备合并、版本回滚。
• 不改 /api/external/v1 与 External OpenAPI，不新增 SpacetimeDB 表。

## 交付内容 - 客户端新增 `project_snapshot` 模块：项目扫描与排除口径、增量索引、差异对比、上传编排、状态查询。 - 触发：工作区窗口存活期间的周期定时器 + 工作区窗口关闭（`CloseRequested`）；应用退出只在有界预算内等待在途同步收尾，不重复发起。 - 服务端新增两条登录态路由 `POST /api/agc/project-snapshots/files` 与 `/manifest`，由 api-server 用服务端凭据写入私有前缀 `agc/project-snapshots/v1/{user}/{project}/`；客户端不持有 OSS 凭据、不直连 OSS。 - `platform-oss` 新增内部对象精确写入与探测、项目快照对象键构造；修复 `head_internal_object` 读 HEAD 响应长度恒为 0（会导致服务端"已存在即跳过"永不生效）。 - `shared-contracts` 新增 `agc_project_snapshots` DTO 与项目 ID、相对路径、摘要校验。 - 真实 OSS 存储层冒烟示例 + 客户端真实链路冒烟用例（`#[ignore]`，env 驱动）。 - 登记 `check-config.mjs` 的 native-only 命令白名单，恢复 `npm run agc` 可启动。 ## 验证证据 - 存储层：`cargo run -p platform-oss --example agc_project_snapshot_live_smoke` 对真实 `agc-dev` 完成写入 → 读回（contentLength 32）→ 清单写入 → 探针清理。 - HTTP 层：登录态下 7 项校验（401 无 token、400 路径穿越/长度不一致/非法摘要/空正文/重复路径清单）全部符合预期且不写对象。 - 客户端链路（真实项目 gameagent-033b6cf3…）：第一次 `synced uploaded=6 uploadedBytes=36694 remoteSkipped=6`，紧接着第二次 `no-op uploaded=0`。 - GUI 触发：`trigger=periodic ... uploaded=6`；把周期设为 600 秒排除干扰、改一个文件后关窗得到 `trigger=project-close ... revision=2 uploaded=1`，索引摘要由 `28d837cd84f8ab62` 推进到 `bff34e2e336d901f`（同步在进程退出前完成）。 - 门禁：AGC `project_snapshot` 14 passed（+1 ignored live）、api-server `project_snapshots` 3 passed、platform-oss 39 passed、shared-contracts 87 passed、`cargo fmt --check`（两处）、`check:encoding`、`check:doc-index`、`git diff --check`、`check-config.mjs` 全部通过。 ## 已知未决（不阻塞本里程碑） - 远端对象只增不减：没有删除路径，也没有 bucket 生命周期规则；要收口需要先定保留语义（清单引用 GC 还是 OSS 生命周期）。 - 部署环境需确认 `GENARRATIVE_AGC_PROJECT_SNAPSHOT_OSS_*` 或回退的 `ALIYUN_OSS_*` 具备目标 bucket 私有前缀的 `PutObject` 权限；未配置时接口返回 503、客户端失败关闭（不推进索引）。 - 缺少按用户/项目的配额与限流（error_reports 有每小时提交上限的先例，本功能没有）。 - 没有界面入口与状态可见性：`read_local_project_snapshot_state` 已注册但未接 UI，失败只写本机日志。 ## 不做 - 不做云端下载/恢复、跨设备合并、版本回滚。 - 不改 `/api/external/v1` 与 External OpenAPI，不新增 SpacetimeDB 表。

kdletters added 1 commit 2026-09-17 15:50:13 +08:00

为 AGC 新增项目定时快照上传（目标 OSS agc-dev） ... c722fd844b

- 新增客户端 project_snapshot 模块：项目扫描与排除口径、增量索引、差异对比、上传编排与状态查询
- 新增周期定时器与工作区窗口关闭触发；应用退出只做有界等待，不重复发起同步
- 新增 api-server 两条登录态路由：单文件上传与清单覆盖写入，落在服务端私有前缀内
- platform-oss 新增内部对象精确写入与探测、项目快照对象键构造，并修复 HEAD 读取长度恒为 0
- shared-contracts 新增 agc_project_snapshots DTO 与项目 ID、相对路径、摘要校验
- 新增真实 OSS 存储层冒烟示例与客户端真实链路冒烟用例（默认忽略）
- 登记 check-config 的 native-only 命令白名单，恢复 npm run agc 可启动
- 同步主规范、里程碑、实施计划、开发运维文档与 .env.example

kdletters added 1 commit 2026-09-17 16:52:24 +08:00

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

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

kdletters added 1 commit 2026-09-17 17:04:31 +08:00

按产品口径移除项目快照的客户端可见界面 ... 4afdb2f359

- 删除项目快照面板组件与其前端测试，回退工作区头部入口、App 接线、前端类型与面板样式
- 两条快照命令恢复为 native-only 登记，并在注释中说明按产品口径不做客户端界面
- 主规范与里程碑同步：可观测性收敛到 AppData 诊断日志，未决问题补记用户侧不可见

kdletters added 1 commit 2026-09-17 18:15:35 +08:00

Merge branch 'master' into codex/agc-project-snapshot-upload e0cfbb2747

kdletters added 1 commit 2026-09-17 18:27:46 +08:00

Merge remote-tracking branch 'origin/master' into codex/agc-project-snapshot-upload 3854165a56

kdletters added 1 commit 2026-09-17 18:34:42 +08:00

Merge branch 'master' into codex/agc-project-snapshot-upload b349708fbd

kdletters merged commit 1a7abfd059 into master 2026-09-17 18:34:51 +08:00

kdletters deleted branch codex/agc-project-snapshot-upload 2026-09-17 18:34:51 +08:00

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

Clear labels

Compat/Breaking

Breaking change that won't be backward compatible

Kind/Bug

Something is not working

Kind/Documentation

Documentation changes

Kind/Enhancement

Improve existing functionality

Kind/Feature

New functionality

Kind/Security

This is security issue

Kind/Testing

Issue or pull request related to testing

Priority

Critical

1

The priority is critical

Priority

High

2

The priority is high

Priority

Low

4

The priority is low

Priority

Medium

3

The priority is medium

Reviewed

Confirmed

1

Issue has been confirmed

Reviewed

Duplicate

2

This issue or pull request already exists

Reviewed

Invalid

3

Invalid issue

Reviewed

Won't Fix

3

This issue won't be fixed

Status

Abandoned

3

Somebody has started to work on this but abandoned work

Status

Blocked

1

Something is blocking this issue or pull request

Status

Need More Info

2

Feedback is required to reproduce issue or to continue work

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

HuangJiaJia JenkenB k88936 (王德宇) kdletters (段舒康) laura2008 (王乐) lhk229 (孔令弘) Loer (农洛儿) loong suzmii (董羽秦) taobaisu (叶东旭) wuxiangwanzi (王子民) YixuanLiu ziyu

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: GenarrativeAI/Genarrative#400