完成素材无限画布最终审计与恢复安全收口
同步资源管理最新稳定的 manifest relay、Runner 重挂与 MCP 域名修复 统一网站与 Tauri 的共享画布 history、缩放恢复和宿主边界 移除生成账本中的临时上传凭证与 Provider 敏感字段 补齐事务快照发布前故障恢复和同幂等身份重放 更新最终 PRD、技术方案、decision-log 与 pitfalls 补齐前端、Tauri Rust、竞态、锁、恢复和原生壳门禁
This commit is contained in:
@@ -474,14 +474,14 @@ type ProjectAgentMudPointAttribution = {
|
||||
4. 根目录全量 Vitest、前后端 typecheck / lint / build、Rust workspace test / check、SpacetimeDB schema、原生壳、内容 / 编码、生产运维与部署门禁全部通过后，阶段七才允许提交。
|
||||
5. 本地 `.env`、`.env.local`、密钥、缓存、日志和构建产物不进入阶段七提交；提交前再次执行编码检查和 `git diff --check`。
|
||||
|
||||
### 7.6 素材创作无限画布阶段一验收
|
||||
### 7.6 素材创作无限画布阶段一至五最终验收
|
||||
|
||||
实现状态（2026-08-05，阶段四）：资源总览新增/图片精修入口、中央素材画布、取消恢复、正式 manifest/revision 实时合并、依赖图重建、dependency/type 双布局协调和三阶段自动定位已经接通。command/event 任意顺序按项目、commit、event 与 revision 去重；低 revision、旧 graph/layout 和失效 focus generation 均不能倒灌。真实 AI 生成仍按合同保持 mock 非目标。
|
||||
实现状态（2026-08-05，阶段五）：资源总览新增/图片精修入口、中央素材画布、取消恢复、正式 manifest/revision 实时合并、依赖图重建、dependency/type 双布局协调和三阶段自动定位已经接通。command/event 任意顺序按项目、commit、event 与 revision 去重；低 revision、旧 graph/layout 和失效 focus generation 均不能倒灌。Tauri 图片新增与精修已经通过共享 generation port 接入真实 External Editor 异步生成、稳定引用下载、阶段三正式事务和重启恢复；成功不依赖刷新、重开项目、随机等待或手工修复。
|
||||
|
||||
1. 网站与 Tauri 实际 import 同一份 `@genarrative/image-canvas-core` 和 `@genarrative/image-canvas-react`，客户端没有复制的主站画布目录；宿主差异只位于 adapter。
|
||||
1. 网站与 Tauri 实际 import 同一份 `@genarrative/image-canvas-core` 和 `@genarrative/image-canvas-react`，客户端没有复制的主站画布目录；viewport、selection、变换、renderer 与 history 算法位于共享层，宿主只保留事件接线与 adapter 副作用。
|
||||
2. “新增资源”和“精修资源”分别进入 create/refine 素材画布；精修保留原资产、创建新资产，并用规范 `referenceResourceIds` 登记直接血缘。
|
||||
3. 草稿 schema、revision、容量、项目身份、OS 锁、CAS、恢复副本和媒体引用符合权威专题；损坏、未知 schema、身份错配和超限均失败关闭。
|
||||
4. 正式提交携带 `expectedProjectId + expectedRevision + expectedDraftRevision + commitId + idempotencyKey`，按文件、manifest/revision、回读、ledger/draft、事件顺序完成；两窗口并发、重复提交和各崩溃阶段均有确定结果。
|
||||
4. 正式提交携带 `expectedProjectId + expectedRevision + expectedDraftRevision + commitId + idempotencyKey`，按事务快照/journal/ledger、文件、manifest/revision、回读、ledger/draft、事件顺序完成；首个快照、全部快照、journal 写入、文件、manifest、revision、验证和 ledger 各崩溃阶段均有确定结果，未发布快照残留只在证明正式文件、manifest 与 revision 均未变化时清理。
|
||||
5. 保存成功后不刷新、不重开项目即可进入 manifest 投影、依赖图、dependency/type 布局和允许时的选中定位；切项目、切中央状态、改选择或改搜索后的迟到结果不得抢焦点。
|
||||
6. 搜索/筛选隐藏新资源时保留条件，明确提示“新资源已保存，当前筛选条件下不可见”，只通过显式动作清除条件并定位。
|
||||
7. 新增、精修、生成、保存、取消、失败和恢复必须覆盖权威专题 §13 的完整验收矩阵；只完成画布 UI 或只完成本地写文件都不能算正式闭环。
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -94,6 +94,12 @@ npm run test -- apps/ai-game-creator-shell/tests/agentRuntimeModel.test.ts --run
|
||||
cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml autonomous_completion_contract -- --nocapture --test-threads=1
|
||||
```
|
||||
|
||||
修改 manifest invalidation relay、GUI owner attach 或其测试夹具后，所有会读写进程全局事件 sink 的测试统一使用 `manifest_invalidation_sink_isolation_` 前缀，并至少以 2 个 test thread 重复运行该 filter。测试 fixture 的 accept 和 payload 读取都必须使用总 deadline，不能只在 accept 成功后给 `TcpStream` 设置 read timeout；全局 sink 只能在共享 test-only 串行锁内由 RAII guard 配置和清理。
|
||||
|
||||
```bash
|
||||
cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml manifest_invalidation_sink_isolation_ -- --nocapture --test-threads=2
|
||||
```
|
||||
|
||||
source allowlist、game-chat 单轮完成门和 Canvas spritesheet 引用门禁均须命中实际测试；若完整 Rust suite 受 Windows `os error 32` 既有文件锁竞态影响，应单独复跑新增 filter 并如实记录，不能把锁竞态失败改报为本次改动通过。
|
||||
|
||||
Windows release 的非交互后台命令统一使用 `CREATE_NO_WINDOW`，包括 `command.exec / project.verify`、STDIO MCP、Repository Context Git、`git.inspect / project.git_commit` 和 `taskkill` 清理命令；需要进程组终止时再叠加 `CREATE_NEW_PROCESS_GROUP`，不要使用 `DETACHED_PROCESS`。smoke 时应在实际任务运行期间观察无额外控制台窗口，并在关闭客户端后核对整棵后台进程树为零，再重启确认 reconciliation 可继续。
|
||||
|
||||
@@ -4205,6 +4205,28 @@
|
||||
- 处理：文件头白名单同时覆盖 32/64 位与 fat Mach-O 的正序和反字节序合法魔数，并由桌面配置门禁同时反查 staging 脚本和根级产物检查，不能改成只按扩展名或构建退出码判断。
|
||||
- 验证：在 macOS 上构建真实 desktop-shell release，运行 `npm run desktop-shell:stage-release-binary`，再由 `npm run check:native-shells` 校验 staged 产物。
|
||||
|
||||
## 托管 MCP 新增公开域名时不能只更新网关路由（2026-08-05）
|
||||
|
||||
- 现象：`https://dev.genarrative.world/api/external/v1/mcp` 的 manifest、OpenAPI 和 Bearer 鉴权都正常，但鉴权后的 `initialize` 返回 `403 FORBIDDEN`；通过 SSH 隧道访问同一 api-server 的 loopback 地址却可以正常列出 tools/resources。
|
||||
- 原因：`rmcp` Streamable HTTP transport 自带 DNS rebinding 防护。公网网关已经接入 dev 域名，但 `external_mcp::service()` 的 `allowed_hosts` / `allowed_origins` 仍只登记正式域名和 localhost，因此请求在 MCP 协议处理前被 transport 拒绝。
|
||||
- 处理：新增公开 MCP 环境时，同批登记对应 Host 与 HTTPS Origin；不要通过客户端伪造 `Host`、关闭防护或改走内部 SpacetimeDB MCP 规避。allowlist 变更属于 api-server 发布内容，必须随正常 API release 部署到目标环境。
|
||||
- 验证：自动测试使用真实公开 Host/Origin 执行 `initialize`；部署后再从公网域名完成带 Key 的 `initialize`、`tools/list`、`resources/list`、Skill resource 读取和至少一个只读业务 tool 调用。loopback 成功只能证明 MCP 实现和 Key 可用，不能替代公网 Host 验收。
|
||||
- 关联：`server-rs/crates/api-server/src/external_mcp.rs`、`docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md`。
|
||||
|
||||
## GUI owner 锁不能替代逐 boot 的事件接收端登记（2026-08-05）
|
||||
|
||||
- 现象：GUI 首次启动后 manifest 事件转发正常，但 Runner 被替换为新 boot 后只剩 owner 锁和 endpoint 可用，后台更新不再到达 GUI；或者 attach 响应只确认 owner，客户端却误记当前 boot 已完整登记，后续 ensure 不再重试。
|
||||
- 原因：把 OS owner 生命周期约束与进程内事件 sink attachment 混成同一状态，或在 `ensure_external_agent_runner` 之外执行一次性 attach；测试若用 actionId 等无关字段代替真实 sink port/token，也无法证明新 boot 重放的是可用接收端。
|
||||
- 处理：GUI 按规范化 AppData 私有登记真实 sink port/token，`ensure_external_agent_runner` 的 endpoint 复用和新 Runner 就绪两条成功路径都按 `bootId` 重放。同 boot 成功后幂等，新 boot 必须重挂；RPC、`attached` 或 `eventSinkAttached` 任一失败或缺失都不得记录成功 boot，并允许同 boot 后续重试。不同 AppData 不共享登记，未登记 CLI 不触发 attach；sink token 不进入日志、错误或公共状态。
|
||||
- 验证：分别覆盖真实 port/token 跨 boot 原样重放、同 boot 幂等、新 boot 重挂、普通 attach 失败、`eventSinkAttached` 缺失与 false 后同 boot 重试、AppData 隔离和未登记 CLI 零副作用。
|
||||
|
||||
## manifest relay 测试不能并行覆盖同一个全局 sink（2026-08-05）
|
||||
|
||||
- 现象：crate 根 relay 测试在配置全局 sink 后阻塞等待 `TcpListener::accept()`，同时 Runner GUI owner attach 测试通过另一条路径覆盖并清空 sink；事件可能被发往另一端口，原 listener 随后永久等待。断言或 `expect` 提前失败时，成功路径末尾的手动 clear 也不会执行。
|
||||
- 原因：两个跨模块测试读写同一进程全局状态，却没有共用隔离边界；只给 accept 后取得的 stream 设置 read timeout 无法约束 accept 本身，payload 读取也缺少总 deadline。
|
||||
- 处理：全部全局 sink 测试共用一把 test-only 串行锁，并由 RAII guard 在 `Drop` 中无条件清空；测试统一使用 `manifest_invalidation_sink_isolation_` 前缀。relay fixture 对 accept 和 payload 分别使用非阻塞轮询与总 deadline，不使用固定 sleep；生产 loopback、token、连接 / 写入超时和 payload 大小校验保持不变。
|
||||
- 验证：用 `--test-threads=2` 重复运行统一 filter，覆盖正常 relay、无事件 accept 超时、不完整 payload 超时、panic 展开清理，以及 GUI owner attach 配置与 guard 清理。
|
||||
|
||||
## 远端图片 completed 不能冒充本地资源创建成功（2026-08-05）
|
||||
|
||||
- 现象：External operation 已返回 completed，但稳定引用缺失、下载失败、正式资产事务中断或 manifest 已提交而 UI 事件丢失时，界面仍可能提前显示“资源创建成功”，重复回调还可能再次下载、写文件或登记资源。
|
||||
@@ -4213,3 +4235,24 @@
|
||||
- 精修补充：`sourceImageSrc` 是可下载的稳定媒体引用，`sourceResourceId` 是资源身份，二者不能因为都可表现为字符串就填同一个 objectKey。本地 `local-asset:*` 只保留在本地 manifest 血缘；没有真实 External resourceId 时省略 `sourceResourceId`。
|
||||
- 验证：覆盖确认前零调用、同 key 连点、accepted 重启 GET-only、重复 completed、取消后迟到、下载后本地事务恢复、事件丢失、切项目/改选择、旧轮询隔离、实时布局与选择、精修血缘及敏感字段零泄漏。
|
||||
- 关联：`apps/ai-game-creator-shell/src-tauri/src/project/asset_canvas/generation.rs`、`apps/ai-game-creator-shell/src/features/asset-canvas/AssetCanvasSurface.tsx`、`docs/technical/【技术方案】客户端素材创作无限画布阶段一合同-2026-08-05.md`。
|
||||
|
||||
## 可恢复生成账本不能持久化 direct-upload ticket（2026-08-05）
|
||||
|
||||
- 现象：为支持参考图上传中断恢复，把完整 upload ticket 放进 generation ledger；账本随之包含 Provider host、formFields、policy、signature 或临时 Authorization，项目目录泄露即可复用临时凭证。
|
||||
- 原因：把“恢复所需的稳定远端身份”和“仅供一次上传的临时授权材料”当成同一种持久状态。原子 sidecar 只能保证写入完整，不能让敏感字段变安全。
|
||||
- 处理：ticket 结构不实现 Serialize/Deserialize，host/formFields 只在本次内存调用中使用。账本在上传前只保存稳定 bucket/objectKey；重启先用这组身份调用 object confirm，确认成功后只保留 objectKey/assetObjectId 并清掉上传中间态。账本测试必须直接序列化完整 ledger，扫描 Provider URL、Authorization、policy、signature、API Key 和 ticket 字段名。
|
||||
- 验证：运行 `cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml private_generation_ledger_never_serializes_upload_credentials_or_provider_url`，并继续检查公开草稿、manifest、事件和普通错误不含 prompt、operationId、Key、绝对路径或媒体正文。
|
||||
|
||||
## prepared journal 之前同样存在正式事务崩溃窗口（2026-08-05）
|
||||
|
||||
- 现象：事务依次安装 before/after 快照后才写 journal；若进程在首个快照、全部快照或 journal 已写但 ledger 未写时退出，重启扫描看到 transaction 目录却无法进入原先只覆盖 prepared 之后的恢复状态机，可能留下孤儿目录或阻塞项目后续提交。
|
||||
- 原因：把 `prepared` 当成事务的第一个可观察持久阶段，忽略了构造 prepared 证据本身也由多次原子文件安装组成。
|
||||
- 处理：把首个快照、全部快照和 journal 后/ledger 前加入故障矩阵。无 ledger 时只允许清理受控快照与本模块临时文件；若 journal 已存在，还必须证明正式目标不存在、manifest 和 project revision 精确等于 before。未知文件、正式文件存在或权威状态漂移全部失败关闭，不能递归猜测清理。清理后同步 transaction 父目录，并允许同 commit/idempotency 身份安全重放。
|
||||
- 验证：故障矩阵逐阶段恢复；额外用同一幂等身份在快照残留清理后提交两次，必须得到一次 committed、一次 already-committed，manifest 仍只有一个 canvas asset。
|
||||
|
||||
## 宿主事件接线不能顺手复制共享 history 栈（2026-08-05）
|
||||
|
||||
- 现象：Tauri Surface 已复用共享 viewport/transform/renderer 数学，却另外维护 undo/redo refs、快照克隆和恢复逻辑；网站共享 hook 后续增加内容安全或字段恢复时，两端会静默分叉。
|
||||
- 原因：把 Pointer 事件接线、宿主生命周期胶水和可复用 history 算法放在同一组件中，误以为没有复制整个画布目录就已经满足共享源码边界。
|
||||
- 处理：两宿主直接消费共享 `useCanvasHistory`；共享 snapshot 统一覆盖 viewport、selection、图层位置和 width/height，宿主只声明本地媒体是否允许安全移除/重做。Tauri 仍可保留 Pointer capture/epoch/host callback 接线，但选择、平移、缩放、变换、renderer 和 history 状态机不得在宿主重写。
|
||||
- 验证：主站 history 定向测试覆盖 resize undo/redo；Tauri 新建、导入、编辑、撤销重做和 durable commit 用例必须在同一共享 hook 下通过。
|
||||
|
||||
@@ -273,7 +273,8 @@ Agent Runtime 负责：
|
||||
- 2026-07-10 补充：后台任务工具箱已加入 `agent.run_status`。Agent 可在 loop 中读取自己、目标 Agent 或一组 Agent 的 Runtime 状态摘要，判断同伴是否正在运行、最近任务和最近工具动作；Runtime 复用 `agent.run_status` 项目权限策略，策略要求确认或拒绝时不读取状态，observation 不返回 `.agent/runtime/*` 文件绝对路径。
|
||||
- 2026-07-10 补充：后台任务工具箱已加入 `agent.delegate`。Agent 可在 loop 中把明确任务投递到另一个 Agent 的独立后台队列，复用目标 Agent 原有锁和 pending drain 语义；同一目标 Agent 串行，不同目标 Agent 可并行。该工具受 `agent.delegate` 策略保护，策略要求确认或拒绝时不会写目标对话、不会启动目标后台任务，也不会写 `agent.runtime.agent.delegate` 审计记录。
|
||||
- 2026-07-10 补充：`agent.delegate` 已形成可恢复的父子任务闭环。`delegationId` 由 durable pending action 的 `actionId` 派生，子任务记录会保存 `parentAgentId / parentRunId / delegationId`，终态记录额外保存经过统一凭据清洗和安全截断的 `terminalDetail`；同一委派的提交和回执分别受 delegation 级 OS 文件锁保护，同一目标 Agent 的 runId 分配与 pending 追加还受任务账本 OS 锁保护。子任务进入 `completed / failed / cancelled / budget-exhausted` 任一终态时，Runtime 按 `delegationId` 幂等生成且至多生成一次 `agent.delegate.result` 回执，失败、排队或活跃取消、预算耗尽都必须回传，不能只覆盖成功。回执会向父 Agent 既有队列追加固定 runId、`source=agent-delegate-receipt` 的续跑任务，把完整的已清洗 `terminalDetail` 交回父 run，不再只保留 80 字符 UI 摘要；回执 prompt 明确禁止重复同一委派，排队期间不提前写入父会话，真正开始执行时才幂等落盘，用户消息或回执消息落盘失败时不会进入 LLM。回执任务保留父 run 关联，并在真正开始或恢复前再次检查父 run 状态，关联缺失或父 run 不存在时失败关闭；该续跑仍受父 Agent 原有 FIFO、per-Agent OS 锁、权限确认、取消、恢复和 `needs-reconciliation` 屏障约束，不直接重入父 run、不插队、不新增独立 worker；父 run 已取消或普通失败时只保留 suppressed receipt 审计，不自动复活，父 Session 归档与切换会被未结束委派阻止，极端归档竞态下回执回落到父 Agent 当前可写 Session。恢复先恢复 pending action / reconciliation 屏障，再扫描“子任务终态已落盘但回执未提交”的窗口并补齐缺失回执；`needs-reconciliation` 本身不回执，只有人工核对后最终取消才回传 `cancelled`。
|
||||
- 历史记录（已由 V1.1 独立 Runner 替代）：Runtime 最初通过 `resume_game_creator_agent_runtime_tasks` 把本地 JSONL 队列重接到当前 App 进程。当前恢复入口仍保留权限、任务顺序和 `agent.runtime.background_task.recovered` 审计语义，但实际由独立 Runner 接管原 run / session；已发出的上游 LLM 请求仍不能从网络中间点续传。2026-07-27 起，Runner 归 Tauri GUI 生命周期所有，同一 AppData 只允许一个 GUI owner。GUI 启动子进程会显式声明 `--gui-owner-required` 并在就绪后 attach owner；Runner 若在启动检查前已发现 owner 释放则直接失败，不得退化成 CLI-owned Runner。Runner 使用独立 watchdog 线程每 100ms 监控 owner OS 锁，不依赖服务端主循环继续推进；owner 丢失后先触发 1.5 秒共享 deadline 的 draining、Provider 中断和 process session 回收，若主循环或排空链路卡死则在 1.75 秒后由 Runner 自身进程安全硬退出并清理匹配 bootId 的 endpoint。因此正常最终退出、panic、SIGKILL 和 setup 中途失败都不会再因 busy 或主循环卡死而残留后台进程。endpoint 缺失 / 读取失败必须结合 Runner 实例锁判断；GUI 客户端强制兜底在 Linux 使用 pidfd、Windows 使用稳定进程 handle。macOS 没有等价稳定句柄，客户端不得在 start identity 检查后按裸 PID 强杀，而由跨平台 Runner 自身 watchdog 提供硬退出兜底。旧 endpoint 缺 start identity 时，只有认证 ping 精确匹配 PID + bootId 才允许迁移 busy 旧 Runner。未完成任务保持 durable 状态并在下一次启动走 reconciliation / recovery，不能伪造 completed 或重放副作用。关闭单个 WebView / 子窗口和普通 CLI 退出不触发该行为，版本切换与人工命令仍可使用只关闭空闲实例的 `runner.shutdown_if_idle`。
|
||||
- 历史记录（已由 V1.1 独立 Runner 替代）：Runtime 最初通过 `resume_game_creator_agent_runtime_tasks` 把本地 JSONL 队列重接到当前 App 进程。当前恢复入口仍保留权限、任务顺序和 `agent.runtime.background_task.recovered` 审计语义，但实际由独立 Runner 接管原 run / session；已发出的上游 LLM 请求仍不能从网络中间点续传。2026-07-27 起，Runner 归 Tauri GUI 生命周期所有，同一 AppData 只允许一个 GUI owner。GUI 启动子进程会显式声明 `--gui-owner-required` 并在就绪后 attach owner；Runner 若在启动检查前已发现 owner 释放则直接失败，不得退化成 CLI-owned Runner。Runner 使用独立 watchdog 线程每 100ms 监控 owner OS 锁，不依赖服务端主循环继续推进；owner 丢失后先触发 1.5 秒共享 deadline 的 draining、Provider 中断和 process session 回收，若主循环或排空链路卡死则在 1.75 秒后由 Runner 自身进程安全硬退出并清理匹配 bootId 的 endpoint。GUI 客户端还必须把完整 `runner.attach_gui_owner` 参数作为绑定规范化 AppData 的进程内登记保存；`ensure_external_agent_runner` 无论复用既有 endpoint 还是启动新 Runner，都要在把 endpoint 交给 Runtime 写请求前按新 `bootId` 补登记。同一登记 generation 在同一 boot 上幂等，补登记失败不得记录成功 boot 且本次 `ensure` 失败关闭；未建立 GUI 登记的普通 CLI 不执行该重放。OS owner 锁与 watchdog 已成立只代表进程受 GUI 生命周期约束，不能替代事件 sink 等进程内附加能力的逐 boot 恢复。因此正常最终退出、panic、SIGKILL 和 setup 中途失败都不会再因 busy 或主循环卡死而残留后台进程。endpoint 缺失 / 读取失败必须结合 Runner 实例锁判断；GUI 客户端强制兜底在 Linux 使用 pidfd、Windows 使用稳定进程 handle。macOS 没有等价稳定句柄，客户端不得在 start identity 检查后按裸 PID 强杀，而由跨平台 Runner 自身 watchdog 提供硬退出兜底。旧 endpoint 缺 start identity 时，只有认证 ping 精确匹配 PID + bootId 才允许迁移 busy 旧 Runner。未完成任务保持 durable 状态并在下一次启动走 reconciliation / recovery，不能伪造 completed 或重放副作用。关闭单个 WebView / 子窗口和普通 CLI 退出不触发该行为，版本切换与人工命令仍可使用只关闭空闲实例的 `runner.shutdown_if_idle`。
|
||||
- 2026-08-05 GUI owner attachment 确认补充：登记参数必须保存 GUI manifest 事件接收端的真实 `event_sink_port` 与 `event_sink_token`，不得借用 actionId 等无关字段作为测试替身。每次 attach RPC 只有同时返回 `attached=true` 与 `eventSinkAttached=true` 才能把当前 `bootId` 标记为已登记；`eventSinkAttached` 缺失、为 false 或普通 RPC 失败都保持当前 boot 待重试。sink token 只留在私有进程内登记和 RPC 参数中，不进入日志、错误文本或公共状态。
|
||||
- 2026-07-10 补充，2026-07-16 由 V1.28 澄清：后台 planning 与预算内 final reply 使用专用最小上下文，只预置 Agent 身份、sessionId、runId、执行模式和工具策略；Agent 私有记忆、项目记忆、黑板、对话、资产、项目索引与文件正文只能经对应工具通过权限 gate 后作为 observation 进入下一轮。只有开发窗口的专业 Agent 前台直调可使用对应角色上下文；正式用户前台现已统一进入 `project-supervisor`。长黑板、记忆和对话按尾部截断，确保最新结论与最新定向消息优先保留。
|
||||
- 2026-07-10 补充，2026-07-16 由 V1.28 澄清：同一 Agent 的开发前台直调、流式调试和后台任务统一使用 `.agent/runtime/locks/<agentId>.lock` OS 文件锁。开发前台不再在整个 LLM 请求期间占用项目级写锁；同 Agent 后台任务在开发前台运行时只入队，前台成功或失败后把当前 Agent 锁直接移交给 drain，不重新抢锁，也不允许 drain 启动异常把已经完成的调试结果改判为失败。正式用户 GUI 不通过该入口直聊专业 Agent；不同 Agent 继续并行，真实项目写工具只在副作用执行期间短暂申请项目写锁。
|
||||
- 2026-07-10 补充，2026-08-01 更新：默认 `agent.resume=confirm` 时，客户端自动恢复命令先做只读 recovery preflight。全新项目和已完全终态且没有 task / retry / handoff / finalization / pending action / reconciliation 等 durable recovery work 的项目直接返回空结果，不显示虚假的 `agent.resume` 确认条。确实存在可恢复工作时，自动命令只做 auto gate 并返回待确认错误；主工作区和独立开发 Agent 聊天窗口显示 `agent.resume` 确认条，确认对象绑定发起时的项目路径，切换项目会取消旧确认，异步返回后也不得把旧项目 Runtime 合并到新项目 UI。开发者确认后调用独立 `confirm_resume_game_creator_agent_runtime_tasks`，该命令仍执行 deny-only 权限检查后才接回 durable queue。临时调用失败不锁死项目路径，允许后续刷新重试；明确 deny 或取消都不恢复任务。
|
||||
@@ -953,6 +954,8 @@ game-project/
|
||||
|
||||
- 阶段五只接图片生成与图片精修，通过阶段二共享 `ImageCanvasGenerationPort` 调用客户端 Tauri adapter，并复用 `canvas.asset_generate` 的 External Editor 会话准备、异步提交/查询、稳定引用解析和受控下载能力；不复制网站 `useImageCanvasGenerationWorkflow`，不新增角色动画、视频、音频、图集或平行生成系统。
|
||||
- 生成面板和确认摘要只操作本地状态；用户点击独立“确认生成”后才通过 `canvas.asset_generate` confirm 权限边界。本地生成意图建立时即分配稳定 `intentId/generationId/idempotencyKey`，取消确认则直接丢弃且零 External 调用；一旦提交，重复点击、重启和未知结果保持原身份，不能自动确认或换键重扣。
|
||||
- External endpoint、精确请求、prompt、配置指纹、idempotency key、operationId 和稳定产物引用只进入 `.agent/workbench/asset-canvas/generations/` 私有账本。API Key、Authorization、Provider URL、签名 URL和绝对路径不进入项目事实；草稿/manifest/event/日志只投影安全阶段与本地身份，External taskId 不写 manifest `source.taskId`。
|
||||
- External 相对 endpoint、精确请求、prompt、配置指纹、idempotency key、operationId 和稳定产物引用只进入 `.agent/workbench/asset-canvas/generations/` 私有账本。本地参考图 direct-upload ticket 的 host/formFields/policy/signature/临时 Authorization 只存在内存；恢复账本只允许保存稳定 bucket/objectKey。API Key、Authorization、Provider URL、签名 URL和绝对路径不进入项目事实；草稿/manifest/event/日志只投影安全阶段与本地身份，External taskId 不写 manifest `source.taskId`。
|
||||
- 固定状态顺序为 `generation-accepted -> generation-running -> remote-completed -> media-downloaded -> asset-durable-committed -> manifest-projected -> layout-ready -> selected`。远端 completed 后必须先验证稳定引用，再经 `/assets/read-url` 下载并写入阶段三 staging；随后用账本中的固定本地 commit 身份进入既有 journal/ledger 事务。正式提交失败只恢复本地事务，不重新生成或下载。
|
||||
- 应用重启时 `accepted/running` 只恢复 GET，`prepared` 只以私有账本原请求字节和原键恢复同一 POST。用户停止等待只失效当前 focus generation；不可取消的远端操作继续 reconcile，迟到 completed 可以更新原项目但不能抢焦点。配置缺失、结果引用不稳定、下载/提交失败和未知结果都不得显示资源创建成功。
|
||||
- 最终审计后 Tauri 撤销/重做直接使用与网站相同的共享 `useCanvasHistory`，共享 history 同时恢复 viewport、选择、图层位置和缩放边界；Tauri 自身只保留 Pointer 事件接线，平移、缩放、选择、图层变换和 renderer 算法继续来自共享 core/react。
|
||||
- 正式事务把首个快照、全部快照和 journal 写入后但 ledger 写入前纳入故障矩阵。恢复发现无 ledger 的 transaction 时，只有目录内容全部属于受控快照/临时文件、正式目标文件不存在、manifest 与 project revision 仍精确等于 before，才清理目录并返回 rolled-back；任何未知文件或权威状态变化都失败关闭。同一 commit/idempotency 身份在清理后可重放，最终仍只登记一份资产。
|
||||
|
||||
@@ -864,7 +864,7 @@ cancelling
|
||||
| A10 | 幂等冲突 | 同 key 或 commitId、不同指纹 | 失败关闭，原 ledger/文件/manifest 不变 |
|
||||
| A11 | 两窗口并发 | 相同 expectedRevision 同时提交 | 最多一笔 committed，另一笔 typed conflict，不覆盖成功方 |
|
||||
| A12 | draft 并发 | 相同 expectedDraftRevision 更新 | 最多一笔 updated，另一笔返回最新完整 draft |
|
||||
| A13 | 崩溃：prepared 后 | 尚未装图片 | 恢复安全回滚 staging/transaction 或继续，不生成幽灵 asset |
|
||||
| A13 | 崩溃：首个/全部事务快照、journal 或 prepared 后 | 尚未装图片 | 无 ledger 的未发布 transaction 只在正式文件不存在且 manifest/revision 仍为 before 时清理；prepared 安全回滚或继续，不生成幽灵 asset |
|
||||
| A14 | 崩溃：图片后 | manifest 前 | 仅在摘要/before 全匹配时删除新文件，否则 reconciliation-required |
|
||||
| A15 | 崩溃：manifest 后 | revision 前 | before/after 匹配时前向补 revision，否则 reconciliation-required |
|
||||
| A16 | 崩溃：revision 后 | ledger/event 前 | 回读验证后补 ledger/draft，并重发相同 eventId |
|
||||
@@ -881,7 +881,7 @@ cancelling
|
||||
| A27 | 取消 | clean、dirty、generating、staging、committing | 分别符合第 12 节；committing 不伪装成可取消 |
|
||||
| A28 | 恢复草稿 | 主文件损坏但恢复副本可信/不可信 | 可信副本恢复到 clean history 基线；不可信进入对账，不猜测 |
|
||||
|
||||
下一阶段只有在矩阵对应的纯模型、共享 React、Web adapter、Tauri adapter、Rust 持久化与 AppSurface 测试全部通过后，才可宣称图片素材创作正式闭环完成。
|
||||
阶段一至五最终审计只有在矩阵对应的纯模型、共享 React、Web adapter、Tauri adapter、Rust 持久化与 AppSurface 测试全部通过后，才可宣称图片素材创作正式闭环完成。
|
||||
|
||||
## 14. 2026-08-05 阶段五真实图片生成补丁
|
||||
|
||||
@@ -902,7 +902,7 @@ cancelling
|
||||
.agent/workbench/asset-canvas/generations/<generationId>.json
|
||||
```
|
||||
|
||||
账本由每个 `projectId + generationId` 的进程内 single-flight、安全相对路径和原子 sidecar 写入保护，包含精确 External endpoint / 请求 JSON / SHA-256、prompt 私有正文、配置指纹、External idempotency key、operationId、稳定 `objectKey/resourceId/assetObjectId`、本地 staging 与 commit 恢复身份。阶段三正式资产事务继续由既有持久锁保护。API Key、Authorization、Provider URL、签名 URL 和绝对路径不得写入账本；API Key 只参与不可逆配置指纹。
|
||||
账本由每个 `projectId + generationId` 的进程内 single-flight、安全相对路径和原子 sidecar 写入保护，包含精确 External 相对 endpoint / 请求 JSON / SHA-256、prompt 私有正文、配置指纹、External idempotency key、operationId、稳定 `objectKey/resourceId/assetObjectId`、本地 staging 与 commit 恢复身份。本地参考图上传恢复只允许暂存稳定 bucket/objectKey；direct-upload ticket 的 host、formFields、policy、signature 和临时 Authorization 只存在内存，任何阶段都不得序列化。阶段三正式资产事务继续由既有持久锁保护。API Key、Authorization、Provider URL、签名 URL 和绝对路径不得写入账本；API Key 只参与不可逆配置指纹。
|
||||
|
||||
草稿、manifest、Tauri 事件、Agent DB、Runtime observation、trace、普通错误和日志只允许出现 `intentId/generationId`、安全阶段、引用资源 ID、本地 asset/commit/event 身份和稳定错误码。草稿 generation record 不再保存 prompt、External idempotency key 或 operationId；阶段五读取旧空记录兼容，但下一次成功写入必须移除这些私有字段。
|
||||
|
||||
|
||||
@@ -77,6 +77,8 @@ provider 原图已保存但透明背景处理最终失败时，worker 保留原
|
||||
|
||||
`/api/external/v1/mcp` 是 Genarrative 托管的远程端点，Agent 只需配置 URL 和现有 API Key，不安装本地 MCP server。首版兼容 MCP `2025-11-25` initialize 生命周期，使用 JSON-RPC 2.0 和 Streamable HTTP，支持 `initialize`、`notifications/initialized`、`ping`、`tools/list`、`tools/call`、`resources/list`、`resources/read`。服务端使用无协议 session 的 JSON direct 模式，不依赖 sticky session，也不把 `Mcp-Session-Id` 作为业务身份。
|
||||
|
||||
MCP transport 的 DNS rebinding 防护必须同时允许正式入口 `www.genarrative.world` / `genarrative.world`、开发入口 `dev.genarrative.world` 和本机开发入口；对应 HTTPS Origin 也必须与公开环境同步登记。新增公开环境域名时，必须在发布前使用该域名的真实 `Host` 和 `Origin` 执行 `initialize` 回归，不能只用 `localhost` 单测证明端点可用。
|
||||
|
||||
MCP tools 从同一份 OpenAPI operation 自动形成 snake_case 名称，并在进程内复用 External REST router，因此鉴权、scope、owner、入参、幂等、计费和结果查询契约只有一份。生成 tools 把 `idempotencyKey` 显式放进参数，因为 MCP transport 的 Authorization 头不能代替逐次业务幂等键。工具结果使用 `structuredContent`；业务失败使用 `isError=true` 的结构化安全错误，协议不可路由时才返回 JSON-RPC error。
|
||||
|
||||
MCP 暴露下列稳定文本资源：
|
||||
|
||||
Reference in New Issue
Block a user