修复 AGC 生成准备依赖全量素材库的问题 (#592)

修复已有项目和素材目录绑定时，AGC 生成准备仍读取完整账户素材库、导致无关素材读取失败阻断生成的问题。

- 新增站内与 External v1 的单目录 GET，按主键读取并校验账号归属；复用目录 DTO，不读取素材列表或创建默认目录。
- 已有 binding 和 partial 恢复改为确认目标目录；首次建绑直接沿用稳定幂等创建，不再读取全库。
- 目录缺失、越权、超时、响应身份不符或会话切换时停止，保留恢复证据，不自动重建、不换键重发生成；已有生成账本继续沿用冻结快照恢复。
- 既有素材库与目录创建、修改、删除 API 合同保持不变，持久化表结构不变。同步 OpenAPI、生成绑定及技术文档。

验证：
- AGC Rust：目录绑定 7 项、生成 94 项、资源编辑 60 项、抠图 5 项通过（目录绑定用例包含在生成组中）。
- api-server：External Editor 30 项、受保护路由矩阵 3 项通过。
- 真实隔离 SpacetimeDB：目录读取成功、空目录、缺失、越权、删除后缺失、只读不变，以及既有幂等/并发/孤儿检查通过。
- smoke 脚本测试 4 项通过；module 编译、生成绑定、87 张表 schema guard、DDD、编码、文档索引、定向 Rust 格式与 diff 检查通过。
- 已比较 OpenAPI：除新增单目录 GET 外，原有定义逐项保持一致。

验证限制：未完成独立 API `/healthz` 联调，本地隔离数据库与授权配置未就绪；启动尝试已停止并清理。未运行全量测试或真实付费生成。

发布顺序：先发布后端模块与 API，再发布新客户端；不提供全库回退。#574 的素材分页、筛选及按素材 ID 读取不在本 PR 范围内。

Closes #550

Reviewed-on: #592
Co-authored-by: Linghong <ink29535@proton.me>
Co-committed-by: Linghong <ink29535@proton.me>

docs/openapi/genarrative-external-v1.openapi.json

@@ -786,6 +786,46 @@
       }
     },
     "/api/external/v1/editor/assets/folders/{folderId}": {
+      "get": {
+        "tags": ["Editor Assets"],
+        "operationId": "getEditorAssetFolder",
+        "summary": "按 ID 读取当前账号素材文件夹",
+        "description": "要求 editor:asset scope。仅按 folderId 读取目录并校验当前账号归属，不读取素材列表或创建默认目录；空目录也可读取。目录不存在返回 404，无权访问返回 403。",
+        "security": [
+          {
+            "ExternalApiKey": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/FolderId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "素材文件夹",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ExternalEditorAssetFolderResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      },
       "patch": {
         "tags": ["Editor Assets"],
         "operationId": "updateEditorAssetFolder",

docs/project-memory/shared-memory/development-workflow.md

@@ -53,6 +53,8 @@
 
 ## 验证路由
 
+AGC 生成准备只通过单目录 GET 确认当前账号绑定，不能重新依赖完整素材库，也不能把目录查询失败当成首次无绑定而创建目录。目录删除时保留证据并停止；`prepared / accepted / legacy-completed` 生成账本继续用冻结快照恢复。该查询同时覆盖站内会话与 External v1，后端新增接口先发布，旧 API 保持兼容；详见 AGC 实施计划和后端数据契约。
+
 Windows 下的移动壳 smoke 通过 Node 启动从当前 workspace 包解析出的 Expo/EAS CLI，不直接 `spawnSync('npm.cmd')`；保留原配置与导出断言。具体入口和警告清理边界见本地开发运维文档。
 
 AGC 的纯桌面/生产接入按模块排除测试编译，共享实现与受测入口保持可测试；拆分后同时检查普通目标和测试目标，并保留原有行为断言。命令注册与退出接线的源码检查跟随真实模块位置更新，不能因移动文件而漏检；不通过全局允许死代码或虚假调用消除告警。具体边界见开发运维文档“编译告警的保留边界与待优化项”。

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

@@ -946,6 +946,10 @@ Agent Runtime 负责：
 - 2026-07-10 补充：后台任务工具箱已加入 `preview.start`。Agent 可在 loop 中自行请求启动当前项目的本地 HTTP 预览；Runtime 会复用 `preview.start` 策略、项目写锁、共享 `PreviewRegistry`、manifest 预览状态、`.agent/logs/preview.log` 和 run trace 追加逻辑，并把 `agent.runtime.preview.start` 写入 `.agent/agent.db`。该 observation 只向 LLM 返回 localhost URL 与端口，不返回用户项目绝对路径。
 - External Editor 的远端项目和资源属于服务 principal，不属于本地项目的跨账号身份。`.agent/manifest.json` 中 `source.canvasProjectId / resourceId / assetObjectId` 只记录生成来源，不得作为当前登录账号的 active editable binding。客户端在 `.agent/runtime/external-editor-bindings/` 私有保存账号级投影：项目键至少包含服务 origin、principal 和本地 `projectId`，资源键再包含远端项目、本地 asset ID、源文件 SHA-256、媒体类型与 canonical asset kind；值保存该 principal 下的远端 project/folder/resource/object 身份。Token 轮换继续复用同一 principal binding，账号、服务、源字节或 canonical kind 变化必须重新建立；同名本地项目和项目改名不得参与权威匹配。
 - binding 的 lookup key 与稳定 payload 内容指纹分开校验；远端 project/folder/resource/object ID、object key 或尺寸被单独改写时必须失败关闭。同一本地项目和 principal 的首次项目 binding 建立必须串行化覆盖“复读 binding → 必要的远端创建 → 原子安装 binding”，不得因并发任务创建孤儿画布。External v1 项目、素材目录和项目资源创建请求携带由 binding key 派生的稳定 `Idempotency-Key`；服务端在 owner 与接口命名空间内生成稳定 ID，并允许同键同正文安全重试，使远端响应后、本地 sidecar 落盘前崩溃也不会重复创建。
+- 素材生成准备的目录确认采用单目录读取：站内 `GET /api/editor/assets/folders/{folderId}` 与开发者 `GET /api/external/v1/editor/assets/folders/{folderId}` 返回现有 `{folder: ...}` 数据结构，后端按目录主键读取并校验 owner，不读取账户素材、不创建默认目录、不执行媒体修复。External 入口要求 `editor:asset` scope；缺失目录返回 404，越权返回 403，未认证返回 401。原素材库快照及目录创建、修改、删除接口的合同不变；不修改持久化表结构。先部署新增后端接口，再发布依赖该接口的客户端；新客户端不回退完整素材库。
+- 已有当前账号项目 binding 或恢复 partial 的目录身份时，在新的生成准备中按该 ID 确认目录并核对响应 ID；合法空目录也可继续。首次没有可复用目录身份时直接沿用稳定幂等创建和冻结正文，不先列举素材库，不按同名认领目录。partial 继续只承载中间恢复进度，成功写入完整 binding 后删除；既有生成账本的 `prepared / accepted / legacy-completed` 恢复仍使用冻结快照，不重新查询或创建目录。
+- 单目录查询超时、断网、服务异常、鉴权失效、越权或会话切换时停止准备并保留现有 binding / 恢复证据，不解释为目录缺失、不自动 POST 新目录。明确 404 时提示绑定目录不存在并停止，不用原键复活目录、不换键重建或重发生成；自动重新绑定与素材分页、关键词筛选、按素材 ID 导入不属于该行为。验证覆盖全库不可用而单目录正常、空目录、首次建绑、缺失与越权、查询失败及切号，并保留并发单次创建、创建响应丢失、冻结正文及生成账本恢复回归。
+- 单目录合同的定向验证使用 AGC Rust `external_canvas_context`、`canvas_generation_tests`、`project::resource_editor::tests`、`background_removal_tests` 与 `direct_tools_mcp::tests`，工具链 HTTP 夹具按单目录 GET 返回 `data.folder`；后端使用 `external_editor`、`external_mcp` 和 `protected_route_matrix_keeps_auth_methods_and_head_behavior`，覆盖 OpenAPI 自动增加单目录 MCP 工具后的目录数量及名称唯一性。`npm run check:editor-idempotency-procedures` 在独立 SpacetimeDB 中验证真实目录读取、归属、删除与只读行为，host 单测不能代替该运行时证据。
 - 当前 binding wire schema 为 v2，payload fingerprint 必填。已落盘的 v1 project/resource JSON 只能经独立严格 wire 结构读取，在 lookup key、principal、本地 source、远端字段、对象键、时间和尺寸等不变量全部通过后重算指纹并原子回写 v2。不得用 `serde(default)` 把未知或篡改文档混入迁移。
 - 已完成的本地正式资源以本地文件和 manifest asset 身份为权威。切换账号后，当前账号没有资源 binding 时，必须从本地字节上传、confirm 并登记到当前账号的远端项目后再编辑或派生；任何请求都不得把旧账号的 `canvasProjectId / resourceId / objectKey` 与新账号 Token 组合。新绑定不得覆盖历史来源，也不得迁移或删除旧账号远端对象。已经 `prepared / accepted / running` 的生成或编辑 operation 仍冻结原 principal、原正文和原 operation；切换账号只能停止恢复并保留对账证据，不能改绑、重放或重复扣费。
 - 远端提交返回 `operationId` 后先持久化 accepted 身份，再在每次 poll、download 和本地 commit 前复验冻结会话；同步本地 commit 持有冻结会话租约，使切号只能发生在完整安装前或安装后。Tauri 手工生成同样使用稳定的 durable operation slot，不得使用进程内临时幂等键。历史资源编辑账本从 manifest 远端 resource ID 迁移到本地 asset ID 时，只允许在本地 asset、路径和内容摘要仍一致时兼容旧指纹，新请求不得恢复信任 manifest 远端 ID。

docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md

@@ -617,6 +617,7 @@ Responses 的终态载荷既是工具调用的恢复源，也是正文的恢复
 - Rust 结构体：`EditorAssetFolder`
 - 源码：`server-rs/crates/spacetime-module/src/editor_project_storage.rs`
 - 说明：图片画布账号级素材文件夹表，归属于用户账号而不是 project；首次读取素材库时自动创建系统默认“项目素材”文件夹。文件夹支持重命名、折叠和删除，系统默认文件夹不能删除。
+- 单目录读取：`GET /api/editor/assets/folders/{folderId}` 与 `GET /api/external/v1/editor/assets/folders/{folderId}` 经同一 `spacetime-client` facade / 只读 procedure 按目录主键和 owner 校验，返回现有目录 DTO；不读取素材、不创建默认目录或修复媒体。External 要求 `editor:asset` scope；未认证 401、越权 403、缺失 404。既有全库、目录创建/修改/删除 API 合同和持久表结构保持不变；先部署后端再发布依赖新接口的 AGC 客户端，不提供全库回退。
 - 索引：`by_editor_asset_folder_owner_user_id`。
 
 ### `editor_asset`