补提交 AGC 后端框架与演进路线文档

docs/README.md 已引用但文件未入库，是文档索引门禁失败的第二处缺失\n补齐后 check:doc-index 可在干净检出上通过

docs/technical/【技术方案】AGC后端框架整理与演进路线-2026-09-18.md

@@ -0,0 +1,315 @@
+# 【技术方案】AGC 后端框架整理与演进路线
+
+更新时间：`2026-09-18`
+
+## 结论
+
+可以整理，而且不需要从零重写。当前 AGC 已经具备一套可复用的后端骨架，但它还不是一个可以直接部署的统一 AGC backend：共享 Runtime 目前是库级内核，本地 Tauri 持有项目执行事实，`server-rs` 持有云端平台业务，三者之间还需要 application adapter 和契约收口。现有骨架包括：
+
+- `server-rs/crates/agent-runtime-core` 是不依赖产品和框架的 Runtime 执行内核。
+- `server-rs/crates/agent-runtime-orchestration` 是任务图、依赖波次和修复影响计算。
+- `server-rs/crates/platform-agent` 是 AGC 壳独立 path dependency 使用的游戏任务图、角色和游戏产物规则适配层；它被 `server-rs` 默认 workspace 排除，不能反向成为通用 Runtime 内核。
+- `apps/ai-game-creator-shell/src-tauri/src/agent`、`project`、`runner` 是本地 AGC 执行宿主。
+- `server-rs/crates/module-*`、`spacetime-module`、`spacetime-client`、`api-server` 和 `platform-*` 已覆盖领域、持久化、HTTP/BFF 和外部服务适配。
+
+现在的主要问题是能力已经分布在多个入口，缺少一个对开发者可见的 AGC backend application facade 和统一的跨边界状态合同。目标应是整理边界和调用方向，逐步收拢入口，不新建第二套 Agent Runtime、第二套会话库或第二个业务真相。
+
+## 目标
+
+AGC backend 对外提供一个稳定的“项目开发运行时”能力面：接收用户意图，绑定项目身份，规划或执行 Agent Run，调用受控工具和平台能力，持久化可恢复状态，发布可观察事件，并把本地项目产物或云端资源结果返回给客户端。客户端本地宿主通过共享契约和平台 adapter 与云端交互，不直接把 `module-*` 当作本地 IO 层。
+
+框架需要同时支持两种执行位置：
+
+1. **本地宿主执行**：Agent 需要直接读写用户项目、启动本地进程、访问本地预览或编辑器时，在 Tauri Rust 宿主中执行。
+2. **云端控制面执行**：认证、账户、模型目录、编辑器资源、异步生成、计费、快照上传和公开 API 在 `server-rs` 中执行。
+
+两者共享领域合同、Runtime 语义和错误分类，但不共享不适合跨进程的本地副作用实现。
+
+## 非目标
+
+- 不把 Tauri 本地文件、进程、浏览器或 Codex app-server 搬进云端。
+- 不把 `api-server` 变成任意代码执行器，也不让前端直接访问 SpacetimeDB。
+- 不引入 LangChain、AutoGen、OpenAI Agents SDK sidecar 或另一套调度器作为 AGC 核心。
+- 不恢复已退役的旧创作入口、旧作品架或旧后端服务。
+- 不在本次整理中改变现有公开 API、SpacetimeDB 表字段、OpenAPI 或本地项目文件格式。
+
+## 逻辑分层
+
+```mermaid
+flowchart TB
+    UI[AGC Web UI / Tauri commands]
+    HOST[AGC Local Host\nTauri Rust]
+    CORE[Shared Agent Runtime\nagent-runtime-core]
+    ORCH[Task Graph\nagent-runtime-orchestration]
+    CONTRACT[Shared contracts\nshared-contracts]
+    DOMAIN[Cloud domain modules\nmodule-*]
+    API[Cloud Control Plane\napi-server Axum]
+    DATA[Data plane\nspacetime-client -> SpacetimeDB]
+    PLATFORM[Platform adapters\nplatform-llm / image / oss / auth / ...]
+    PROJECT[Local Project Plane\nfiles / manifest / JSONL / locks / checkpoints]
+
+    UI --> HOST
+    UI --> API
+    HOST --> CORE
+    HOST --> ORCH
+    HOST --> CONTRACT
+    HOST --> PROJECT
+    API --> CONTRACT
+    API --> DOMAIN
+    API --> DATA
+    API --> PLATFORM
+    PLATFORM --> DATA
+```
+
+这张图是调用方向，不表示所有层都必须变成新的 crate。当前 `api-server` 不依赖或执行本地 `agent-runtime-core`/`agent-runtime-orchestration`；如果未来明确引入云端 Runner，再单独增加云端 Runtime host，不把本地项目 Run 事实迁移到 API handler。现有目录已经能承载大部分边界，先用 facade、trait 和契约测试固化边界，再决定是否需要物理拆 crate。
+
+### 1. Shared Runtime kernel
+
+`agent-runtime-core` 只负责通用运行事实和确定性决策：Run、Action、Observation、Tool execution、Completion、Recovery、Provider contract、Capability registry 和 Runtime event。它不能依赖 Tauri、Axum、SpacetimeDB、具体提示词、权限实现或 AGC 业务表。
+
+`agent-runtime-orchestration` 只负责任务图：Agent catalog 校验、依赖关系、ready task、wave 和下游修复影响。它不持有线程、Provider、工具、数据库或产品持久化。
+
+这两层是 AGC 与其他未来 Agent 宿主共享的内核，不能把 AGC 特有规则反向塞回去。
+
+### 2. Domain and contract layer
+
+领域规则留在现有 `module-*`：
+
+| 领域 | 当前承载位置 | 负责内容 |
+| --- | --- | --- |
+| 主站画布 Agent 会话 | `module-editor-agent` | 画布会话归属、标题、消息元数据、领域校验；不是 DirectProject 本地会话事实源 |
+| Runtime / AI task | `module-runtime`、`module-ai` | Runtime 设置、模型目录、AI task 状态和输入校验 |
+| 编辑器项目和资源 | `module-assets`、`spacetime-module` 相关 storage | 项目、资源、版本绑定、生成任务和事务规则 |
+| 认证和账户 | `module-auth`、`platform-auth` | 身份、会话和认证平台适配 |
+
+跨端 DTO、公开请求/响应和错误码留在 `shared-contracts`。目标边界是领域层不发 HTTP、不读本地文件、不调用 LLM、不直接拿 OSS 客户端；当前部分 `module-*` 仍通过 feature 或 service 依赖平台 crate，这属于后续收口债务，不应继续扩大。
+
+### 3. Local AGC host
+
+`apps/ai-game-creator-shell/src-tauri` 是本地 backend，不只是 UI 的 IPC 薄壳。普通 Tauri command 只负责鉴权、确认和 UI bridge；真正的 LLM、工具循环、队列和恢复由独立的 `--agent-runner` 执行者完成。它负责：
+
+- `agent`：DirectProject、Runtime driver、Runtime protocol、工具桥、Codex app-server/CLI、Provider handoff 和恢复。
+- `project`：项目根边界、manifest、JSONL 会话、checkpoint、资源编辑、文件读写、项目写锁和版本替换。
+- `runner`：跨窗口共享的 Agent Runner、loopback 协议、owner/watchdog、连接和生命周期。
+- `browser`、`preview`、`process_session`：受控预览、浏览器试玩、本地进程会话及证据。
+- `editor_adapter`、`plugin_host`：编辑器桥接和插件能力，不向 Agent 暴露原始 pipe、句柄或未绑定项目身份的执行面。
+- `platform_session`、`http_client`：平台身份/凭据和云端 API 调用。
+
+本地宿主可以复用共享 Runtime crate 和 `platform-agent`，但项目文件、资源权限、完成门、Prompt Bundle、DirectProject/Planning V2 和 Runner IPC 都属于 AGC adapter/host，不能迁回 Runtime core。
+
+`main.rs`、`agent.rs` 和命令注册只应是组合层。新的业务规则应进入对应功能域或 Runtime contract，不能继续堆进入口文件。
+
+### 4. Cloud control plane
+
+`api-server` 是云端 HTTP/SSE/BFF 和跨模块编排层。它不持有本地 `--agent-runner` 的项目 Run 事实；除非未来明确引入云端 Runner，否则云端只持有平台业务、异步 operation 和可公开投影。现有入口包括：
+
+- `/api/ai/tasks`：AI task 生命周期。
+- `/api/editor/*` 与 `/api/external/v1/editor/*`：编辑器项目、资源和生成操作。
+- `/api/agc/project-snapshots/*`：AGC 项目文件与 manifest 快照上传。
+- `/admin/api/agc-models`：AGC 模型目录管理。
+- 编辑器 Agent 会话、外部生成任务、运行设置和诊断/追踪相关接口。
+
+这些路由可以继续按领域模块存在，但需要分成两个语义清晰的 facade：
+
+- **本地 host coordinator**：在 Tauri 宿主内统一 `start_run`、`resume_run`、`cancel_run`、`get_run` 和本地事件投影，事实源仍是项目 `.agent/runtime/**` 与 Runner。
+- **云端 application service**：在 `api-server` 统一 `submit_operation`、`get_operation`、`reconcile_operation`、AI task、外部生成和快照调用，复用现有领域 service、队列和 SpacetimeDB procedure。
+
+两者可以共享 DTO、错误分类和 correlation 字段，但当前不新增统一的云端 `/runs` API，也不把本地 Run 伪装成云端持久化记录。
+
+### 5. Platform adapters
+
+LLM、图片/音频/视频、OSS、认证、语音和编辑器外部服务继续放在 `platform-*`。适配器只返回受约束的 Provider/Job/Asset 结果；重试、幂等、扣费、结果落库和公开错误映射由上层 application/domain contract 决定。
+
+## 数据真相和存储边界
+
+### 本地项目平面
+
+以下事实属于当前授权项目，由本地宿主负责读写和恢复：
+
+- 项目源文件、`manifest`、版本和资源绑定的本地投影。
+- `.agent` 下的会话 JSONL、Runtime journal、action/observation、checkpoint 和诊断摘要。
+- 项目写锁、Runner owner、进程会话、预览注册和浏览器证据。
+
+本地写入必须经过项目身份校验、项目根边界、普通文件/reparse point 检查、写锁和现有权限策略。云端 API 不直接读写用户项目目录。
+
+### 云端业务平面
+
+以下事实属于服务端：
+
+- 登录身份、refresh session、钱包/计费和模型目录。
+- 编辑器项目、资源、版本绑定、生成任务、任务事件和结果引用。
+- 错误报告、追踪事件和公开 read model；快照当前以受控 OSS manifest/对象键、审计和诊断能力为主，不假定已经存在 SpacetimeDB 快照元数据表。
+
+当前 SpacetimeDB 没有通用的 AGC Agent Run/Action/Event/Confirmation/Plan 表；`runtime_snapshot` 不能直接当作 AGC Agent Runtime 持久化。若未来把 Run 迁到云端，必须另立清晰的持久化合同；本路线默认本地 `.agent/runtime/**` 继续是 DirectProject 的事实源。
+
+SpacetimeDB 表、reducer、procedure 和事务 adapter 只留在 `spacetime-module`；服务端访问统一走 `spacetime-client` facade。
+
+### OSS / 大对象平面
+
+会话正文、项目快照文件和媒体大对象继续按现有合同进入 OSS；SpacetimeDB 只保存归属、对象键、版本、状态和必要摘要。OSS key 必须由服务端根据已验证的身份/项目 ID 生成，客户端不能把任意对象键当作归属证明。
+
+## 统一执行合同
+
+本地 Run 和云端异步操作可以有不同实现，但公开状态应映射到同一组语义：
+
+```text
+intent
+  -> accepted
+  -> queued
+  -> running
+  -> waiting (user / confirmation / provider retry / external job)
+  -> succeeded | failed | cancelled | needs-reconciliation
+```
+
+- `accepted` 表示请求已经被持久化并得到稳定身份，不表示 child 已经开始执行。
+- `running` 必须由真正持有执行权的 Runner/worker 写入 started 事实后才能公开。
+- `waiting` 必须有可恢复的原因和下一步信息，不能由前端计时器伪造。
+- 外部结果未知、不能安全重放时进入 `needs-reconciliation`，禁止自动重放或伪造成功。
+- 取消、失败、恢复、重试和最终回复都必须保留同一 Run/operation 身份及可追踪的 event 顺序。
+
+现有 `RunStatus`、`ActionStatus`、`ObservationStatus`、AI task 状态、ExternalGenerationJob 状态和项目生成账本可以继续各自保留；application facade 只提供上述语义映射，不强行把它们合并成一张跨域表。
+
+## 核心调用链
+
+### 本地 DirectProject
+
+```text
+UI
+ -> Tauri command
+ -> DirectProject / Runtime driver
+ -> Runner / Codex app-server
+ -> Runtime tool policy
+ -> project owner + write lock
+ -> local files / manifest / JSONL / checkpoint
+ -> Runtime event projection
+ -> UI
+```
+
+工具执行失败时，属于可修复的构建、验证或试玩错误，可以把脱敏上下文反馈给同一 LLM 回合并有界重试；鉴权、项目身份、权限、传输断开、取消、历史损坏和付费操作不确定等边界必须失败关闭。
+
+### 云端资源/生成操作
+
+```text
+AGC tool or UI
+ -> api-server route
+ -> auth + project ownership + idempotency
+ -> module-* validation
+ -> spacetime-client facade
+ -> durable operation / queue
+ -> platform-* provider
+ -> OSS result
+ -> SpacetimeDB result projection
+ -> API polling/SSE
+```
+
+计费、外部 job、结果安装和重试必须围绕 durable operation 编排，不能把 Provider 返回成功当成业务完成的唯一证据。
+
+### 项目快照
+
+```text
+Local project snapshot
+ -> authenticated /api/agc/project-snapshots/*
+ -> body-size and file contract checks
+ -> object storage
+ -> snapshot metadata / diagnostic projection
+```
+
+快照上传用于备份和诊断，不改变本地项目作为开发态文件真相的职责。
+
+## 边界规则
+
+1. **Runtime 与宿主分离**：核心 Runtime 只做状态决策；Tauri host、Runner 和 server worker 提供执行、持久化、时间和能力实现。
+2. **领域与 IO 分离**：`module-*` 不依赖 Axum、Tauri、Provider 或 OSS；HTTP handler 不复制领域校验。
+3. **文件系统单一入口**：任何 Agent 文件读写都经过项目 scope、写锁和受控工具；不能在 API 或前端加旁路写入。
+4. **外部服务单一入口**：LLM、生成、OSS、认证等外部调用只经 `platform-*`，不能在业务 handler 里散落裸 HTTP。
+5. **数据访问单一入口**：`api-server` 和本地需要的云端调用使用 `spacetime-client` facade，不直接拼 SpacetimeDB 请求。
+6. **前端只消费投影**：前端不推导正式业务状态，不直接访问本地项目数据库或 SpacetimeDB。
+7. **身份与凭据分离**：同一身份的 access token 轮换不使在途 Run 失效；换号、退出或 origin 变化必须使旧 Run 停止后续副作用。
+8. **可恢复优先**：持久动作、异步生成、Runner 续跑、外部结果回填和最终状态写入必须有稳定 ID、版本/CAS 或幂等键。
+
+## 当前缺口
+
+### 缺少 AGC application facade
+
+能力散落在 `agent`、`editor_project.rs`、`external_editor_api.rs`、`ai_tasks.rs`、快照路由和生成队列中。它们各自可用，但调用方难以判断一项用户意图应该走本地 Run、云端 task 还是外部 generation operation。
+
+**整理方向**：先建立逻辑 facade 和 capability catalog，保留现有路由作为 adapter；只有当两个以上入口共享同一业务流程时，才下沉 application service。
+
+### 本地和云端状态语义重复
+
+本地 Runtime、AI task、ExternalGenerationJob 和项目资源 operation 都有自己的 accepted/running/failed/retry 表达。状态不能强行合表，但需要统一事件字段：`subject_id`、`run_or_operation_id`、`stage`、`revision`、`occurred_at`、`retryable`、`public_summary` 和 `correlation_id`。
+
+### 组合层偏重
+
+AGC Tauri 的 `main.rs`、`agent.rs` 和部分命令模块已经包含大量注册与兼容出口。后续工作应按功能域继续拆分，但每次只移动一个边界并保持公开导出、命令名称和测试合同不变。
+
+### 云端大文件模块偏重
+
+`api-server` 的编辑器项目、External Editor API 和生成队列承担了较多请求解析、领域校验、计费、队列和结果投影。后续应把领域输入校验和 operation service 继续下沉到 `module-*`/application 层，handler 只保留鉴权、解析、调用和响应映射。
+
+### 契约目录需要集中
+
+AGC 本地 IPC、Runner 协议、Runtime snapshot、云端 API、SpacetimeDB procedure 和 OSS key 规则目前分布在代码及专题文档中。应建立一个只读的 AGC capability/contract catalog，列出入口、调用方、状态源、权限、幂等键、恢复策略和证据位置；它不是新的运行时注册表。
+
+## 演进路线
+
+### 第一阶段：框架定界
+
+- 将本文件作为 AGC backend 主规范。
+- 维护 capability catalog，给每个现有入口标注 `local-host`、`cloud-control-plane` 或 `shared-runtime`。
+- 为本地 Run、云端 task、外部 generation 和快照上传补齐统一 correlation/idempotency 字段的映射表。
+- 不改 API、schema 和文件格式。
+
+### 第二阶段：统一 application facade
+
+- 在现有 `api-server` modules 之上增加薄的 AGC application service/facade。
+- 先收拢 Run 查询、事件查询、取消、恢复和 operation reconcile；生成业务仍复用现有队列和平台适配器。
+- 本地 Tauri 侧将 DirectProject、Runtime driver 和 Runner 的入口分成 `command adapter -> application coordinator -> runtime host` 三层。
+- 用契约测试锁定调用方向，防止前端或 handler 绕过 domain/client facade。
+
+### 第三阶段：持久化与恢复收口
+
+- 为本地 Runtime journal、云端 AI task、外部 generation job 和项目资源 operation 逐项定义 accepted/running/waiting/terminal 的写入点。
+- 补齐重启、重复提交、迟到回调、同身份 token 轮换、换号和 unknown outcome 的恢复测试。
+- 继续保持本地项目文件与云端业务数据的双平面，不做隐式云同步。
+
+### 第四阶段：能力插件化
+
+- 以 capability contract 接入编辑器 adapter、图像/音频/视频生成、浏览器试玩和 UI workflow。
+- 每个能力声明输入约束、权限、写入范围、计费/异步语义、产物身份和验证证据。
+- Cocos 等编辑器桥接继续通过通用 plugin host，不把编辑器进程控制细节泄漏给 Runtime core。
+
+### 第五阶段：观测和发布门禁
+
+- 统一 Run/operation 的 request ID、correlation ID、client marker、错误分类、诊断事件和公开摘要。
+- 建立 AGC backend smoke：健康检查、鉴权、最小 Run、工具拒绝、快照体积边界、异步生成轮询和恢复。
+- 把真实 Provider、登录态、Windows Runner 和本地预览作为单独运行时证据，不用静态检查替代。
+
+## 验收标准与证据
+
+| 条款 | 验收方式 | 证据 |
+| --- | --- | --- |
+| 共享 Runtime 不依赖产品 IO | `cargo check/test -p agent-runtime-core -p agent-runtime-orchestration` 与依赖检查 | crate 依赖和测试输出 |
+| 本地工具只能在授权项目内执行 | AGC Rust 项目 scope、symlink/reparse、写锁和权限定向测试 | `apps/ai-game-creator-shell/src-tauri` 测试报告 |
+| 云端路由不绕过 domain/client | api-server 定向测试和源码依赖检查 | handler、module、spacetime-client 调用证据 |
+| 重复提交不产生重复副作用 | 本地 Run、AI task、ExternalGenerationJob 和生成 operation 幂等测试 | 稳定 ID/receipt/CAS 断言 |
+| 未知外部结果失败关闭 | provider/queue/reconcile 测试 | `needs-reconciliation` 终态证据 |
+| 认证续期不误杀在途 Run | session 与 Runtime 定向测试 | 同身份凭据轮换、换号失效证据 |
+| 快照上传受控 | `/api/agc/project-snapshots/*` API smoke | 鉴权、体积、项目归属和 OSS key 断言 |
+| 公开状态可追踪 | request/correlation/client marker 与错误摘要测试 | tracking、诊断事件和公开 response |
+| 文档与代码口径一致 | `npm run check:doc-index`、`npm run check:encoding`、`git diff --check` | 命令输出 |
+
+## 决策
+
+1. AGC backend 采用“共享 Runtime 内核 + 本地执行宿主 + 云端控制面 + 领域/平台适配器”的逻辑框架；`platform-agent` 继续承载 AGC 游戏特化规则，不能被当作通用内核。
+2. 先整理本地 host coordinator、云端 application service、contract catalog 和测试边界，再决定是否需要新增物理 crate；当前不新建平行 `agc-runtime`。
+3. 本地项目文件和云端业务数据保持双平面，快照是受控上传能力，不是开发态主数据同步。
+4. `agent-runtime-core` 与 `agent-runtime-orchestration` 保持产品无关；AGC 规则进入 host、application 或 `module-*`。
+5. 公开 API、SpacetimeDB schema、生成绑定和现有本地文件合同在后续实现阶段保持兼容，任何 breaking change 单独走 SDD 和迁移评审。
+
+## 未决问题
+
+- AGC application facade 第一批要覆盖哪些调用方：仅客户端本地 Run，还是同时纳入外部编辑器 API。
+- 云端是否需要持久化 AGC Run 元数据，还是继续以本地 Run 为主、云端只持久化资源和异步 operation。
+- capability catalog 最终作为文档、生成的共享 DTO，还是仅作为测试清单；在未证明需要运行时发现前，不把它做成新的动态插件注册中心。
+- 是否有明确的云端 Runner 需求；在没有多租户后台执行需求前，不把本地 Runner 迁移到服务端。