Merge branch 'master' into codex/game-agent-runtime-interaction-design
This commit is contained in:
@@ -109,7 +109,7 @@
|
||||
- 主站账号、钱包、服务端项目、云端素材库和生成面板仍留在网站宿主；客户端本地项目、manifest、Runtime、审批、草稿、生成与正式提交仍留在 Tauri 宿主。共享视觉组件不得读取这些业务事实。
|
||||
- 客户端 UI 对齐采用“同视觉、同组件、保留四区布局”，不复制主站整页布局。资源总览、运行视图和 Supervisor 对话继续是 Game Agent 工作台独有语义。
|
||||
- 客户端正式产品仍只按 `1280×800` 横屏合同交付；更窄浏览器样式只负责不崩溃和开发兼容，不改成移动端创作工作台。
|
||||
- 普通用户界面不默认展示内部错误码、开发者 API 配置或本机绝对路径；确需诊断的信息进入受控详情或开发模式，不与主要动作并列。
|
||||
- 普通用户界面不默认展示内部错误码或本机绝对路径；External Editor 配置只进入独立“运行时配置”对话框，不与素材画布主要动作并列，确需诊断的信息进入受控详情或开发模式。
|
||||
- 素材画布的“素材名称”是用户可编辑的正式输出名称；“资源用途”是 manifest subtype，不向普通用户开放自由文本。新增资源默认“普通游戏美术”，可从普通游戏美术、统一视觉规范、游戏界面原型、核心美术图集四项中选择；精修资源继承源用途且不可改。导出格式继续限定 PNG/JPEG/WebP。工具动作与保存设置分层展示，“保存到项目”在 `1280×800` 和窄容器中都必须完整可见。
|
||||
|
||||
### 3.8 现有 Godot 项目
|
||||
@@ -530,7 +530,7 @@ type ProjectAgentMudPointAttribution = {
|
||||
|
||||
### 7.6 素材创作无限画布阶段一至五最终验收
|
||||
|
||||
实现状态（2026-08-11）：当前产品切片禁用“新增资源”，只从现有资源进入非破坏性编辑。图片进入中央 refine 画布，其他现役类型进入统一派生编辑壳；取消恢复、正式 manifest/revision 实时合并、依赖图重建、dependency/type 双布局协调和三阶段自动定位已经接通。command/event 任意顺序按项目、commit、event 与 revision 去重；低 revision、旧 graph/layout 和失效 focus generation 均不能倒灌。Tauri 远端媒体编辑固定使用 AppData 私有 `editorApi.baseUrl/apiKey` 访问 `/api/external/v1/*`，不把 Key 传入 WebView、项目事实、账本、日志或普通错误；画布 UI 不提供 Base URL/API Key 输入。重启恢复只继续原 operation，不以新请求、新幂等键或新 operationId 替代结果未知的旧任务。
|
||||
实现状态（2026-08-12）：当前产品切片禁用“新增资源”，只从现有资源进入非破坏性编辑。图片进入中央 refine 画布，其他现役类型进入统一派生编辑壳；取消恢复、正式 manifest/revision 实时合并、依赖图重建、dependency/type 双布局协调和三阶段自动定位已经接通。command/event 任意顺序按项目、commit、event 与 revision 去重；低 revision、旧 graph/layout 和失效 focus generation 均不能倒灌。Tauri 远端媒体编辑固定使用 AppData 私有 `editorApi.baseUrl/apiKey` 访问 `/api/external/v1/*`，普通 Launcher、开发工作台和独立 game-chat 的“运行时配置”都可编辑这两个字段；不把 Key 传入 WebView、项目事实、账本、日志或普通错误，素材画布工作区自身不提供凭据输入。重启恢复只继续原 operation，不以新请求、新幂等键或新 operationId 替代结果未知的旧任务。
|
||||
|
||||
1. 网站与 Tauri 实际 import 同一份 `@genarrative/image-canvas-core` 和 `@genarrative/image-canvas-react`，客户端没有复制的主站画布目录；viewport、selection、变换、renderer 与 history 算法位于共享层，宿主只保留事件接线与 adapter 副作用。
|
||||
2. “新增资源”在当前产品切片中保持禁用；“编辑资源”只接受现有资源。图片 refine 保留原资产与原文件、创建新资产，并用规范 `referenceResourceIds` 登记直接血缘；其他类型同样只追加派生文件/asset 或子版本，不覆盖、删除或重排源记录。
|
||||
|
||||
@@ -1,5 +1,21 @@
|
||||
# 决策记录
|
||||
|
||||
## 2026-08-12 Repository checks 采用 CI 与本地共用的单一门禁入口
|
||||
|
||||
- 背景：master run 1037 的 Backend/Frontend 已通过，但 `Repository checks` 因 3 个 `simple-import-sort/imports` 错误失败。原 pre-commit 只运行 Prettier，Prettier 不处理 ESLint import 排序；推送前又未运行完整仓库 lint，因此本地与 CI 的覆盖范围长期存在漂移。
|
||||
- 决策：`npm run check:repository-ci` 成为 Repository checks 唯一仓库入口，统一执行 lint、生产构建、内容检查和基线到候选提交的空白差异检查；Gitea workflow 与 master pre-push 只调用该入口。pre-push 必须验证待推 master SHA 是当前 `HEAD` 且已跟踪工作树干净，无法确认候选内容时失败关闭；feature 分支不运行该重门禁。
|
||||
- 提交门禁：lint-staged 对 staged JS/TS 先运行按 ESLint 配置过滤 ignored 文件的 autofix wrapper，再运行 Prettier。回归测试覆盖 import 排序、部分暂存恢复、ignored 文件、feature push 跳过、master push 参数绑定，以及 workflow/hook 共用入口。
|
||||
- 权威边界：本地 hook 可被 `--no-verify` 绕过，不能从制度上保证 master 永远不红。服务端根治要求禁止日常直接 push master，统一走 PR，并要求当前 head 的 Repository/Frontend/Backend/Native 四项检查全部成功后合并；紧急白名单只能最小化保留。
|
||||
|
||||
## 2026-08-12 Agent 失败原因使用稳定分类贯穿 Runtime 与正式展示面
|
||||
|
||||
- 背景：Codex app-server 的 failed turn 已携带 `turn.error.codexErrorInfo`，但适配器曾丢弃该字段并写固定失败句；Runtime、事件 `publicText`、最近任务、game-chat 阶段记录和多个 Agent 卡片又各自用固定文案覆盖已有安全原因。自主构建 final-reply 已形成确定性完成文案时还对任意错误 fallback 成成功，导致鉴权、额度、上下文、策略、sandbox、配置或网络失败可能被伪装为完成。
|
||||
- 决策：app-server 只消费协议稳定错误分类和 HTTP 状态，不公开 `message / additionalDetails`；Runtime 持久私有诊断继续脱敏，正式 conversation、失败事件 `publicText`、阶段记录、最近任务和所有 Agent 卡片统一从封闭分类派生可行动中文摘要。失败事件只允许后端 `publicText` 进入正式活动详情，缺失时使用固定安全 summary，私有 `detail` 不得展示；旧 Supervisor 与专业 Agent 失败 conversation 也必须经过同一安全映射。`needs-reconciliation` 是停止自动推进并等待人工处置的终态，显示为“待核对”，不得归为普通运行中或普通完成；未知错误保留固定安全兜底。自主构建确定性 final-reply fallback 只允许稳定 `empty-response / deserialize` 回复形状错误，任何鉴权、额度、上下文、策略、sandbox、配置、网络或上游错误都保持失败。
|
||||
- 安全边界：不得把 Provider 正文、URL/query、API Key、Token、Cookie、本地绝对路径、fingerprint、字符数或 `[redacted ...]` 占位符放入正式 UI、conversation、事件 `publicText` 或阶段记录。前端只消费后端稳定分类或已通过严格门禁的公共摘要，不从自由文本猜测敏感上游错误。
|
||||
- 未完成恢复项：isolated join 唤醒、isolated child result 发布、manifest terminal projection 和 terminal-unknown reconciliation 在持久化自身失败时仍需要独立 durable marker 与重启扫描协议；这些跨崩溃窗口必须单独设计和验证，不能用 best-effort 事件或日志冒充已恢复。
|
||||
- 验证方式：覆盖 Codex 分类与敏感诱饵、失败事件公共摘要、最近任务与各正式卡片、game-chat 阶段记录、待核对状态、final-reply fallback 白名单及 malformed 响应完整重试；运行 Rust 定向测试、前端模型/AppSurface 定向测试、Shell typecheck、编码和 diff 门禁。
|
||||
- 关联文档：`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`。
|
||||
|
||||
|
||||
## 2026-08-10 资源管理评审阻塞项按第二轮正式合同修复
|
||||
|
||||
@@ -58,6 +74,7 @@
|
||||
|
||||
- 产品边界：主站网页画布继续使用登录态 `/api/editor/*`、`/api/assets/*` 与 `/api/runtime/external-generation/jobs/*`；AI 游戏创作 Tauri 客户端没有网页画布宿主，图片、图片引用、视频、音效和背景音乐等远端媒体编辑固定使用 `/api/external/v1/*`。两条入口继续复用相同请求 DTO、owner 归属、统一生成队列和正式资产结果，不新建平行生成服务。
|
||||
- 凭据边界：客户端沿用发布 AppData 私有运行时配置中的 `editorApi.baseUrl/apiKey`，不实现登录后自动签发 Developer API Key，不把站内 Access Token 传给 Tauri 生成命令，也不把 API Key 打包进仓库、传入 WebView、写入项目、账本、日志或普通错误。Key 缺失投影安全配置错误，`401/403` 投影 External 凭据无效或权限不足，不再描述为站内登录失效。
|
||||
- 配置入口：普通 Launcher、开发工作台和独立 game-chat 复用同一“运行时配置”对话框，均可编辑 AppData 私有 `editorApi.baseUrl/apiKey`；字段可见性不依赖开发模式或 Agent 模式。素材画布工作区自身不承接凭据输入，密钥输入保持 password 类型并禁用浏览器自动填充。
|
||||
- 路由边界：图片编辑、视频、音效和 BGM 分别使用 `/api/external/v1/editor/images/edits`、`/api/external/v1/editor/videos/generations`、`/api/external/v1/editor/audios/sound-effects/generations` 与 `/api/external/v1/editor/audios/background-music/generations`；上传、确认、轮询和换签固定使用 External v1 对应端点。SVG、UTF-8 文档、代码、Agent 回执与项目版本仍是本地派生，不制造无意义的远端请求。
|
||||
- 可靠性边界：External POST 固定携带原稳定 `Idempotency-Key` 并只接受 `202 + operationId`；`prepared` 只重放原正文和原键，`accepted/running` 只查询 `/api/external/v1/generations/{operationId}`。账本使用 `service-origin-v1` 绑定规范化 External base URL 的服务指纹，不绑定或保存明文 Key；升级前 Key-bound 素材画布生成账本无法用当前 Key 验证时，必须由用户显式确认面板中展示的当前 origin 才能恢复冻结请求；全类型资源编辑的旧指纹无法验证时保留原 operation 对账。升级前已保存的站内 endpoint 只保留为待对账状态，禁止拿 External Key 自动重放。本地参考媒体继续严格执行 ticket → OSS form → confirm，结果只消费稳定 `objectKey/resource/asset`，旧资源保留且派生资源追加。
|
||||
- 关联：`apps/ai-game-creator-shell/src/features/asset-canvas/tauriImageCanvasHostAdapter.ts`、`apps/ai-game-creator-shell/src/view/project-development/resourceEditModel.ts`、`apps/ai-game-creator-shell/src/view/project-development/index.tsx`、`apps/ai-game-creator-shell/src-tauri/src/project/asset_canvas/generation.rs`、`apps/ai-game-creator-shell/src-tauri/src/project/resource_editor.rs`。
|
||||
@@ -7091,7 +7108,7 @@
|
||||
- 决策：生成请求勾选 `style="pixelArt"` 与已有图片手动 `POST /api/editor/images/pixel-art-snaps` 共用同一输出语义：snapper 直接编码并持久化唯一的逻辑分辨率 PNG，不再 nearest 恢复到源图、RGBA 输入、业务交付或 generation dialog 占位尺寸。成功输出宽高固定为 `(columns.len() - 1) × (rows.len() - 1)`，允许与输入、交付和占位尺寸不同；响应、project resource、账号素材和结果 layer 一律记录最终 PNG 的实际宽高。
|
||||
- 保留边界：普通图片和角色在规整前执行的 Lanczos 交付尺寸归一继续保留；角色 / 图标的平底网格分析源与透明 RGBA 采样源仍必须同尺寸，Alpha 覆盖、Alpha 加权 RGB、二值 Alpha、P30 步长估算、确定性采样、输入上限、deadline、strict 无网格拒绝和失败降级尺寸守卫全部不变。这些约束保护输入坐标系、资源安全或失败路径，不构成成功输出与输入同尺寸的承诺。
|
||||
- 持久化边界：数量增量保持不变。普通图片只保存一张最终逻辑主图；角色保留一张 provider 原图与一张最终透明逻辑主图；图标保留一张 provider 原图、一张最终透明逻辑图集和原有成功切片；手动完美像素只保存一张最终逻辑 PNG。不得另外保存输入尺寸恢复版、像素化前后双份主图、预览、诊断或报告，不修改 asset kind、队列类型、数据库 schema、路由或请求 / 响应字段形状。
|
||||
- 跨版本重放：手动入口算法指纹升为 `perfect-pixel-v2`。同一稳定 operation 已有结果时，candidate object key 相同才继续既有 exact replay；key 不同或既有稳定资源缺 key 时，必须在 preflight 与 OSS PUT 前返回 `409 + operationResultAlreadyExists=true`，由客户端 GET 权威项目收口，不得冒充本次请求已经设置 `resultPersistenceStarted`。preflight 到最终提交之间仍无数据库 reservation，滚动发布必须排空旧算法实例，不能把该护栏解释为消除了并发 TOCTOU。
|
||||
- 跨版本重放：手动入口算法指纹升为 `perfect-pixel-v2`。完成请求基础校验、owner-scoped 项目读取与占位验证后，只要同一稳定 `resourceId` 已存在，即在来源解析、OSS GET、像素规整、candidate object key、preflight 与 OSS PUT 前返回 `409 + operationResultAlreadyExists=true` 及已鉴权的稳定 `resultResourceId`，由客户端 GET 权威项目收口；前端按稳定资源 ID 定位后继续复核 task、项目、对象与 dialog/layer 关联，损坏 task 必须明确失败关闭为冲突，不得漏检后持续等待。不再按 candidate object key 继续 exact replay。该分支不带 `resultPersistenceStarted`，因为本请求尚未开始持久化。preflight 到最终提交之间仍无数据库 reservation，滚动发布必须排空旧算法实例，不能把该护栏解释为消除了并发 TOCTOU。
|
||||
- 历史边界：本条覆盖 2026-07-28 首发决策中“逻辑结果 nearest 恢复交付尺寸 / 逻辑图不持久化”和 2026-07-30 手动入口中“右侧新增同尺寸 PNG / 不保存逻辑低分辨率图”的旧口径；旧条目作为历史记录保留，不回写改造。
|
||||
- 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md`、`docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md`、`docs/【编辑器】图片画布结构化持久化与迁移回滚方案-2026-07-19.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
|
||||
|
||||
@@ -7124,6 +7141,12 @@
|
||||
- 传输边界：dev 公网入口不接受 Tauri WebView 的跨域 OPTIONS 预检，因此 release 使用 `tauri-plugin-http` 原生 transport。插件的 npm 依赖只归属 AGC 子包及其 lockfile，根 H5 package 与根 lockfile 不得引入任何 Tauri guest 依赖。插件 capability 与前端 URL 解析双重限制为 `https://dev.genarrative.world/api/*`，不为 WebView CSP 增加远程 `connect-src`，也不开放任意 HTTP(S) 目标。
|
||||
- 会话边界：插件默认 Cookie Store 持久化 refresh Cookie；访问 Token 继续保存在现有客户端存储并通过 Authorization header 发送，不把 Token、Cookie 或登录正文写入日志、配置文件或仓库。
|
||||
|
||||
## 2026-08-12 子 Agent 澄清回执由 Supervisor 中转（Issue #163）
|
||||
|
||||
- 决策：`project-supervisor` 继续是唯一正式用户对话 Agent。child 不开放 `user.input_request`；缺少关键用户事实时，child 终态返回 `AGC_NEEDS_USER_INPUT_V1` 结构化问题，形成 `needs-user-input` delivery。
|
||||
- 中转：Supervisor 认领回执后，在自己的父 run 按原 delivery 逐一创建 durable 用户输入 pending action；重启、重复回执和重复唤醒只复用身份与问题完全一致的 action。回答沿用现有 same-run 回灌，并把 requestId 与 answersSha256 原子绑定回原 delivery；随后最多创建一次绑定原 `delegationId` 的 continuation child。
|
||||
- 约束：原 delivery 持久保存 `questionsSha256 / clarificationRequestId / clarificationAnswersSha256`；`agent.delegate` continuation 提交原 delegation、问题 SHA 与答案 SHA，Runtime 自动派生稳定 identity，即使旧 pending 已清理也必须失败关闭校验。多个 child 的问题不能展平为同一请求，问题 envelope、数量、长度、归属和指纹校验失败关闭。不得把 child pending action直接暴露给用户，也不得把澄清回执误判成普通 repair。
|
||||
|
||||
## 2026-08-10 AGC monorepo 构建强制复用单一 React runtime
|
||||
|
||||
- 根因：AGC 子目录存在独立 `node_modules` 时，AGC 源码会解析子目录 React，而仓库共享组件解析根目录 React；登录页不依赖共享 Hooks，进入首页后才触发 `Cannot read properties of null (reading 'useCallback')` 并白屏。
|
||||
@@ -7138,6 +7161,12 @@
|
||||
- HTTP 传输边界：根 H5 包不得依赖 Tauri guest 插件；AGC 独立包保留 `@tauri-apps/plugin-http`。Rust 插件显式关闭默认特性，只启用 `charset`、`cookies`、`http2` 和 `rustls-tls`，避免 `reqwest/system-proxy` 通过 Cargo feature union 把画布、Provider、Runtime 与本地回环夹具统一接入 OS 自动系统代理；如未来产品要求正式客户端继承系统代理，必须按各客户端明确设计并单独完成跨平台验证。
|
||||
- 运行决策：Godot 项目提交给 Project Supervisor 时使用 `standard` Run Profile，避免触发 Web 专用 `game/index.html`、HTTP preview 与自主 Web 完成门。Godot 编辑器启动和内嵌运行预览不在本切片范围。
|
||||
|
||||
## 2026-08-12 AGC Agent 设置分层界面
|
||||
|
||||
- `RuntimeConfigDialog` 保持现有配置字段、持久化格式、Runner 读取和 MCP 测试语义，只重构界面信息架构。
|
||||
- 设置页固定为“常用设置 / Agent 模型 / 连接与工具 / 高级参数”四类；默认只展示运行方式与默认模型，逐 Agent 覆盖按角色折叠，MCP、External Editor 连接和低频运行参数不进入首屏。
|
||||
- 设置壳复用 AGC 平台 tokens、按钮层级和响应式断点；桌面使用双栏 modal，窄屏改为横向分类导航和单列表单，底部保存动作常驻。
|
||||
|
||||
## 2026-08-11 Game Agent 通用 Goal Contract 与动态验收图
|
||||
|
||||
- 决策：固定规则只负责安全、事实完整性和完成协议。根 Project Supervisor 必须先用 `agent.goal_contract` 把自己对当前用户最终意图的理解冻结为结构化 outcome、硬约束、偏好、禁止假设、开放问题和 acceptance nodes；同一根 Run 不允许改写。该合同摘要进入共享黑板，权威 JSON 绑定可信 root Run Profile、source task SHA-256 与 fingerprint。
|
||||
|
||||
@@ -611,13 +611,15 @@ npm run check:server-rs-ddd
|
||||
- 页面交互 smoke
|
||||
- 移动端视口检查
|
||||
|
||||
### 提交前 TypeScript 自动格式化
|
||||
### 提交与 master 推送前自动门禁
|
||||
|
||||
仓库级 Git `pre-commit` hook 通过 `lint-staged`，只对当前已暂存的 `*.ts`、`*.tsx` 文件运行 Prettier 自动格式化，并把格式化结果更新到本次提交的暂存区；未暂存的其他文件不进入格式化范围。格式化或暂存恢复失败时提交会中止，应先处理失败原因并重新检查 staged diff，不能等 CI 再暴露格式问题。
|
||||
仓库级 Git `pre-commit` hook 通过 `lint-staged`，只对当前已暂存的 `*.js`、`*.mjs`、`*.cjs`、`*.ts`、`*.tsx` 文件依次运行 ESLint autofix 和 Prettier，并把修复结果更新到本次提交的暂存区；ESLint wrapper 会按仓库配置过滤 ignored 文件，避免 ignored warning 与 `--max-warnings 0` 组合造成误阻塞。未暂存的其他文件不进入处理范围，修复或暂存恢复失败时提交会中止，应先处理失败原因并重新检查 staged diff，不能等 CI 再暴露 import 排序或格式问题。
|
||||
|
||||
部分暂存同一 TS / TSX 文件时，`lint-staged` 会临时隐藏该文件未暂存的改动，以暂存快照执行格式化，随后恢复未暂存内容。因此提交前后都应分别检查 `git diff --cached` 和 `git diff`，确认格式化后的暂存内容属于本次提交，未暂存工作没有被误带入；若恢复产生冲突，先人工整理暂存边界再重新提交。
|
||||
部分暂存同一 JS / TS 文件时，`lint-staged` 会临时隐藏该文件未暂存的改动，以暂存快照执行修复和格式化，随后恢复未暂存内容。因此提交前后都应分别检查 `git diff --cached` 和 `git diff`，确认修复后的暂存内容属于本次提交，未暂存工作没有被误带入；若恢复产生冲突，先人工整理暂存边界再重新提交。
|
||||
|
||||
`git commit --no-verify` 会绕过该 hook，只允许在已明确原因的紧急场景使用。绕过时仍须对本次暂存的 TS / TSX 文件手动执行等价的 Prettier 格式化、重新暂存并核对 staged diff；`--no-verify` 不代表可以跳过格式化或其他提交门禁。
|
||||
`Repository checks` 的唯一仓库入口是 `npm run check:repository-ci`，依次运行 `npm run lint`、生产构建、内容检查和基线到候选提交的空白差异检查。Gitea `Repository checks` job 和本地 master `pre-push` 必须共同调用该入口，禁止各自复制或删减子命令；本地 hook 还会确认待推 master SHA 等于当前 `HEAD` 且已跟踪工作树干净，无法确认时失败关闭。普通 feature 分支 push 不运行这条重门禁，进入 master 前仍以 PR required checks 为权威。
|
||||
|
||||
`git commit --no-verify` 和 `git push --no-verify` 都会绕过本地 hook，只允许在已明确原因的紧急场景使用；绕过不代表可以跳过等价门禁。真正阻止红提交进入 master 依赖 Gitea 分支保护：禁止日常直接 push，统一经 PR，并要求 `Repository checks`、`Frontend tests`、`Backend tests`、`Native shell tests` 四个当前 head context 全部成功后合并。本地 hook 只负责提前反馈，不能替代服务端分支保护。
|
||||
|
||||
前端原则：
|
||||
|
||||
|
||||
@@ -4734,6 +4734,15 @@
|
||||
- 队列与事务：独立恢复面板必须展示后端权威队列的所有 operation，读取失败不能伪装为空。`remote-failed` 不再重放，只能显式标为 `archived` 并保留账本；`reconciliation-required` 不能归档。派生 asset 使用 `prepared -> media-installed -> manifest-written -> revision-written -> committed` journal，只对可证明状态前向恢复；尚未证明目标写入时严格核对 before/after，已证明目标 asset/media 与 target revision 后允许 manifest/revision 被后续合法提交继续推进，并补齐同一 ledger。committed 后只有 staging 与正式媒体摘要一致、manifest 按 ID 或路径唯一精确匹配 journal asset 时才尽力清理；删除 I/O 失败保持 durable committed，身份或媒体漂移保留 staging 并进入对账。version journal 同样冻结 project revision before/after 身份；manifest 已有子版本但 journal 缺失，或旧 journal 面对已推进 revision 无法补证时都失败关闭。
|
||||
- 验证：覆盖跨进程唯一 refine 草稿发现和多候选失败关闭、文本 Provider 成功到 staging 崩溃后零重复调用、任务视频/版本旧账本恢复、所有目录条目上限、Key 轮换与旧 Key 无法验证时的显式确认、Accepted 后 401/403 再换 Key 只 GET 原 operation、远端明确失败只归档且零新网络/扣费、三条乱序恢复队列、项目切换迟到结果、asset transaction 各崩溃阶段、revision 后项目继续合法修改仍补齐 ledger、committed 后 staging 清理成功/删除 I/O 失败/媒体或 manifest 漂移保留、源摘要漂移拒绝、committed 视频二次派生，以及 manifest 子版本缺 journal、旧 version journal 无法证明 revision 推进与 version journal exactly-once。
|
||||
|
||||
## 子 Agent 澄清不能直接穿透用户输入权限（2026-08-12）
|
||||
|
||||
- 现象：child 需要产品取舍时若直接调用 `user.input_request` 会被 owner gate 拒绝；若把它误走 `needs-repair`，Supervisor 会错误返工而永远不向用户提问。
|
||||
- 正确路径：child 返回短小的 `AGC_NEEDS_USER_INPUT_V1` envelope；Runtime 生成 `needs-user-input` delivery，父 Supervisor 认领后创建自己的 durable `user.input_request`。回答仍绑定原父 run，续建 child 由稳定 delegation identity 幂等控制。
|
||||
- 验证：重复 wake / Runner 重启不得创建第二个用户输入 action；问题数量、字段长度、问题 SHA 和答案 SHA 不匹配时必须 fail-closed。child 直接请求用户输入仍应保持拒绝。
|
||||
- 恢复加固：正常 completed child 的最终回复也必须进入 envelope 解析；回答后 pending 会被下一轮动作替换，因此 continuation 不能读取 current pending 作为证据，必须读取原 delivery 上的 durable request/answer 绑定。多个 child 各用一条用户请求逐一收束，禁止把不同 delivery 的问题和答案指纹拍平混用。
|
||||
- 协议演进：`agent.delegate` 的澄清 continuation 字段虽然在 strict schema 中是 required nullable，但 Runtime 解析器仍必须接受完全未携带这三个字段的既有调用；只允许三者全缺失、全 `null` 或全为合法字符串，部分出现、部分字符串和非法 SHA 均失败关闭。新增 schema 字段时要同步原生函数目录断言与旧调用回归，避免协议修复轮次打乱 Supervisor 协作计划。
|
||||
- 门禁优先级：已经存在真实 `preview.validate` 失败 observation 或 durable `failed_playtest_revision` 时，具体试玩修复与新 revision 重新验证门禁必须先于通用“首次 mutation”门禁；否则 Runtime 会把明确的试玩修复错误收窄成普通 pre-mutation repair，导致 Supervisor 无法选择正确的协作动作。
|
||||
|
||||
## 无限画布延迟草稿与零位移不能制造新状态（2026-08-11）
|
||||
|
||||
- 现象：r5 的 `loadDraft` 比 r6 更晚回包时会把草稿回退；pointerdown 后没有任何移动，pointerup 仍增加一条空 undo 并触发 CAS 保存；Tauri 自行维护 Shift toggle 后，Shift 单击唯一选中图层会意外清空选择。同一 `canvas.failed` 视图还可能把草稿保存或提交故障显示成生成重试。
|
||||
|
||||
@@ -66,8 +66,8 @@
|
||||
- 前端提交前先创建关闭 composer 的右侧生成占位，再解析或上传源图以取得稳定引用，随后把版本化 `perfectPixelOperation` 请求快照写入**本机账本**（占位本身只带 `perfectPixelOperationId` 标记）并 flush 当前项目布局，最后才发送 POST。`canvasCompletion.dialogId` 同时作为 operation identity、稳定 task identity 的输入和本地源图上传 ID；同一 operation 的上传路径与后续 POST 请求都不得随机漂移。`sourceImageSrc` 优先由当前图层已有的 `objectKey / resourceId / sourceAssetId` 解析；尚未登记的浏览器本地图片只执行 `ticket → OSS PUT → confirm → objectKey`，不为这条持久化输入换取 signed URL。一个 `AbortSignal` 必须贯穿源文件 fetch / 图片解析边界、ticket、PUT、confirm，完整上传 helper 的可选换签也必须透传同一 signal。正式请求不得包含 `data:` / `blob:`、signed URL 或普通外链。后端在读取源图前必须把该字段解析为当前 owner 已登记的私有 OSS object key，并核对 project / resource / asset 归属。
|
||||
- 源准备与 operation journal 使用两段绝对预算：`ticket → PUT → confirm` 连同源解析共用 90 秒；confirm 成功后形成稳定 `perfectPixelOperation` 并**同步写入本机账本**（`perfectPixelOperationStore`，owner + project 双键的 localStorage），布局里只留 `perfectPixelOperationId` 标记。原先的 strict layout save 通道（60 秒绝对预算、revision ACK 前 POST 为零）已整体删除：账本不再寄生在用户布局上，本机写入不过网络也不受服务端校验影响，同样能保证请求可被追溯。被解除的是**客户端侧**「拿不到 revision ack 就拒发」这一层阻断；端到端依赖仍在——布局 PATCH 被校验拒绝、占位因此从未落库时，POST 仍会被服务端以 409 拒收。POST 前仍然 `await` 一次 best-effort 布局保存——服务端要求占位**此前已经持久化**，否则 `validate_editor_pixel_art_snap_placeholder_exists` 直接 409；但 best-effort 不再提供成功 ACK，因此客户端**无法证明**该前置已满足，只能提高满足它的概率（占位可能已由此前的自动保存落库，PATCH 也可能成功而 ACK 丢失）。该 flush 没有整体上限，所以 75 秒对账窗口必须在 flush 返回、authority 复核通过之后才锚定，且首次提交与人工重试同此口径；锚定只覆盖 `submittedAt / reconcileUntil`，按同一 `operationId` 覆盖账本，request 与 dialog / operation / task identity 逐字节不变。此阶段失败持久化为 `failed + perfectPixelOperation`，保留同一 `sourceImageSrc / dialogId / taskId / request`；重试请求必须与账本中的 POST JSON byte-for-byte 一致且不得重新上传。**明确接受的行为，不是缺口**：占位恢复可删除之后，用户删掉未收口占位再从源图发起会得到第二个 identity，旧的服务端操作若迟到落库就会多出一份素材，两个 `taskId` 无法幂等合并。按上文的优先级判据，这属于「已生成资源丢失关联」而非主链路故障，代价是用户自行删掉多余素材，**不得**通过让本机账本参与防重来「闭合」——那是被明令禁止的「禁止一张图处理两遍」。confirm 成功后浏览器在 operation 首次 PATCH 落库前立即崩溃仍可能留下 object-only 记录；完全消除该窗口需要服务端 durable upload journal，不属于当前前端修复。
|
||||
- 该已有图片入口使用 strict 语义：只接受静态 PNG / JPEG / WebP，GIF、APNG、动画 WebP、图片序列及其它非静态媒体必须在处理前拒绝。strict 与生成风格复用完全相同的 legacy profile、峰值估算、单轴步长补全、walker、采样和编码；仅当横纵两轴都未检测到步长、legacy 即将使用 `min(width,height)/64` 统一网格兜底时拒绝。任一轴已检测到步长时，两条路径行为和输出必须一致。源图读取、解码、尺寸校验、排队、像素规整或 PNG 编码任一步失败 / 超时 / 不适用时，请求失败，不保留原图副本冒充成功，不执行最终 OSS PUT，也不创建 project resource、账号素材或结果图层。成功时只对唯一的逻辑分辨率 PNG 执行一次 OSS PUT，并至多各创建一个 `editor_project_resource` 和一个 `editor_asset`，再按 `canvasCompletion` 写回一个派生图层；resource、asset、响应与图层使用该 PNG 的实际宽高，不要求与源图或占位尺寸相等，也不得另存输入尺寸恢复版、诊断图或前后对比图。
|
||||
- strict 的本次结果事实零写入边界截至首个最终 PNG PUT：所有可预判的引用、归属、类型、静态编码、元数据、网格适用性和 CPU 处理错误必须在此前失败；前置 owner-scoped 项目 / 素材读取仍可能按既有语义懒建默认 canvas / folder，这些基础记录不属于本次完美像素结果。后端先纯计算精确 object key 和候选 project resource，再调用只读 SpacetimeDB preflight 校验自定义素材目录归属、复用权威 completion planner，并执行 legacy / structured 的 2 MiB 总量与 512 KiB 单项门禁；默认目录尚未创建时允许通过，preflight 不写库。preflight 与 PUT / HEAD / 原子 persist 共用 60 秒绝对 deadline；preflight 失败或超时不得 PUT，也不得带 `resultPersistenceStarted`。最终 PNG 的 OSS PUT / HEAD 位于数据库事务外；验证上传结果后，asset object、project resource、账号素材与可选 canvas completion 由单个受 runtime service identity 保护的 SpacetimeDB procedure 在一次事务中原子提交，并重新校验目录、布局、幂等身份与 revision。preflight 不加锁或 reservation，所以通过后若目录或画布并发漂移，最终事务仍可能在 PUT 后拒绝并留下 OSS 孤儿对象；这是本次最小修复明确保留的 TOCTOU 边界。operation 以 `owner + project + canvasCompletion.dialogId` 为作用域，task / object / resource / asset ID 稳定派生，object key 携带规范请求与输入 / 输出摘要形成的 fingerprint；同内容重放只返回原结果，输入漂移或部分既有事实失败关闭。HTTP timeout/drop 不能撤销已发往远端的 procedure，客户端仍须按稳定 `taskId / objectKey / resourceId` 对账，不能把未收到回包等同于未提交。
|
||||
- 手动入口的算法指纹随逻辑分辨率输出升级为 `perfect-pixel-v2`。若 owner-scoped 项目快照中同一稳定 resource 已存在，candidate object key 相同才继续 exact replay；key 不同或既有 resource 缺 key 时，后端必须在 preflight / OSS PUT 前返回 `operationResultAlreadyExists=true`，前端 initial 与 retry 两条 catch 都按稳定 task GET 项目对账。该标记表示旧权威结果已存在，不得与“本次 PUT 已开始”的 `resultPersistenceStarted` 混用；发布时仍须排空旧算法实例以规避 preflight 到提交之间的跨版本 TOCTOU。
|
||||
- strict 的本次结果事实零写入边界截至首个最终 PNG PUT：所有可预判的引用、归属、类型、静态编码、元数据、网格适用性和 CPU 处理错误必须在此前失败；前置 owner-scoped 项目 / 素材读取仍可能按既有语义懒建默认 canvas / folder，这些基础记录不属于本次完美像素结果。后端先纯计算精确 object key 和候选 project resource，再调用只读 SpacetimeDB preflight 校验自定义素材目录归属、复用权威 completion planner，并执行 legacy / structured 的 2 MiB 总量与 512 KiB 单项门禁；默认目录尚未创建时允许通过，preflight 不写库。preflight 与 PUT / HEAD / 原子 persist 共用 60 秒绝对 deadline；preflight 失败或超时不得 PUT，也不得带 `resultPersistenceStarted`。最终 PNG 的 OSS PUT / HEAD 位于数据库事务外；验证上传结果后，asset object、project resource、账号素材与可选 canvas completion 由单个受 runtime service identity 保护的 SpacetimeDB procedure 在一次事务中原子提交，并重新校验目录、布局、幂等身份与 revision。preflight 不加锁或 reservation，所以通过后若目录或画布并发漂移，最终事务仍可能在 PUT 后拒绝并留下 OSS 孤儿对象；这是本次最小修复明确保留的 TOCTOU 边界。operation 以 `owner + project + canvasCompletion.dialogId` 为作用域，task / object / resource / asset ID 稳定派生，object key 携带规范请求与输入 / 输出摘要形成的 fingerprint；一旦 owner-scoped 项目快照已发现同 operation 的稳定 resource，本次 POST 不再执行 candidate-key exact replay，而是直接返回 `operationResultAlreadyExists=true` 并交由 GET 对账；输入漂移或部分既有事实失败关闭。HTTP timeout/drop 不能撤销已发往远端的 procedure，客户端仍须按稳定 `taskId / objectKey / resourceId` 对账，不能把未收到回包等同于未提交。
|
||||
- 手动入口的算法指纹随逻辑分辨率输出升级为 `perfect-pixel-v2`。在完成请求基础校验、owner-scoped 项目读取与占位验证后，只要同一稳定 `resourceId` 已存在，后端必须在来源解析、OSS GET、像素规整、candidate object key、preflight 与 OSS PUT 前返回 `409 + operationResultAlreadyExists=true`，并携带已鉴权的稳定 `resultResourceId`；不再按 candidate object key 继续 exact replay。前端 initial 与 retry 两条 catch 都按稳定资源与 task GET 项目对账，由权威快照明确 `applied`、`dialog-missing` 或 `conflict`；即使稳定记录的 `taskId` 损坏，也必须据 `resultResourceId` 找到该记录并失败关闭为冲突，不得持续等待。该标记表示旧权威结果已存在，不得与“本次 PUT 已开始”的 `resultPersistenceStarted` 混用；发布时仍须排空旧算法实例以规避独立新操作在 preflight 到提交之间的跨版本 TOCTOU。
|
||||
- `POST /api/editor/images/pixel-art-snaps` 是有副作用的 unsafe POST。客户端不得为它配置 `EDITOR_REQUEST_RETRY_OPTIONS`，请求字节可能已发出后不因 transport 异常或 `408 / 425 / 429 / 502 / 503 / 504` 自动重放；Bearer 中间件在 handler 前以 `401` 拒绝、刷新 token 后的既有认证恢复不属于业务副作用重放，保持通用行为。POST 回包中的 `project / resource / asset` 不是结果 verdict；首次成功回包、未知异常、人工 exact replay 和刷新恢复都只读取项目 GET。`perfectPixelOperation.submittedAt / reconcileUntil` 在 pre-POST flush 返回、authority 复核通过之后、POST 发出之前建立统一 75 秒绝对窗口（该 flush 没有整体上限，锚在它之前会让窗口在请求发出前就烧光），POST 回包不能续期；读取必须立即执行一次，随后退避间隔不超过 5 秒，窗口已过期时仍执行一次即时 GET。每次项目读取使用 `requestJson.deadlineAt` 覆盖缺 token 补票、业务 fetch、401 refresh、重试退避与响应体读取；窗口内单次最多 10 秒且不得越过 `reconcileUntil`，过期后的唯一即时读取最多额外 10 秒。固定判据为：匹配 task 的唯一 resource 加已收口 dialog / 关联图层才是画布成功；dialog 不存在但存在匹配 task resource 才是 asset-only 成功；dialog 仍 generating、dialog 不存在且无匹配 resource、项目始终不可读或窗口耗尽均保持 unknown。素材库刷新只在项目终态后 fire-and-forget，同步抛错、异步拒绝或永久挂起都不得阻塞 verdict、项目快照应用和执行锁释放。
|
||||
- unknown 状态持久化为原 generation dialog 上的 `pending-confirmation + perfectPixelOperation`（账本在本机，布局只留 `perfectPixelOperationId`）。**用户可以随时删除该占位**，任何状态都不例外、也不弹确认：删除不撤销任何在途请求，结果照常落库并进素材库，服务端发现 dialog 已不在会返回 `DialogMissing`；封锁用户删除自己画布上的元素不是可接受的代价。删除后**结果不再自动回填画布**（服务端发现 dialog 已不在会返回 `DialogMissing`），这是用户主动放弃的结果，不得判定为缺陷；但对账本身不会因此停止——当前标签页已经在飞的 Promise 会继续读到终态，本机账本也会以孤儿身份在下次加载被读一次，结果确已落库时仍会提示用户去素材库取。未删除时用户可继续 GET 对账或显式按原 identity 重放。人工重试在 pre-POST flush **之后**才刷新观察窗口（同上一节的锚定口径），POST JSON 必须与持久请求 byte-for-byte 一致，不得按当前画布、目录、类型或标题重建，也不得创建第二个 dialog / task / object / resource / asset。hydrate 后只做 GET，不自动 POST、上传或重建请求。处理成功但事务内权威 dialog 已删除时，后端保留 object / resource / asset 并返回 asset-only 事实，canvas / revision 不变；前端只有在项目 GET 看见匹配 task resource 后才能提示“已保存到素材库”。现有布局 CAS 没有 deletion tombstone，completion 与其它已持久化布局编辑冲突时继续按权威 revision 守卫收口；尚未防抖落库的本地编辑合并不在本批范围。
|
||||
- 删除 generation dialog 的按钮、快捷键和右键菜单必须在写画布历史、清选择或执行低层移除前经过同一请求保护入口。未收口完美像素 operation 与其它占位同样可被立即删除，写正常的 `delete-generation-result` 历史并清理 identity；删除确认只对**计费**生成成立（现成弹窗讲的是「已消耗的泥点不会返还」，而完美像素 `generation_cost_mud_points = 0`），判据收敛为具名的 `requiresGenerationDeleteConfirmation`。低层 `removeCanvasGenerationDialogById` 必须无条件删除——低层对上层抗命正是「占位未删却写出伪历史」的根因。
|
||||
|
||||
@@ -1,5 +1,13 @@
|
||||
# AI 游戏创作智能体 App 实施计划
|
||||
|
||||
## 2026-08-12 Issue #163：子 Agent 澄清回执中转
|
||||
|
||||
正式用户对话 Agent 仍固定为 `project-supervisor`；委派专业 Agent 和隔离 child 不得直接调用 `user.input_request`。当 child 缺少会实质改变结果的用户事实时，child 以短小的 `AGC_NEEDS_USER_INPUT_V1` + 结构化 JSON 终态回执交付问题，Runtime 将其作为 `needs-user-input` delivery，而不是 `needs-repair`。
|
||||
|
||||
Supervisor 认领该回执后，由父 run 自己为每个原 delivery 逐一创建 durable `user.input_request` pending action，并将原 `delegationId`、问题数量和 `questionsSha256` 放入父任务上下文；不同 child 的问题不得展平到同一请求。Runner 重启、重复 delivery 或重复 wake 只复用当前 delivery 的同一 pending action，不把 child 的 pending action 暴露给用户。用户回答仍走现有 Supervisor same-run continuation；回答 observation 绑定 `requestId`、`responseId`、问题 / 答案指纹，并把 `requestId / answersSha256` 原子写回原 delivery。答案收齐后，Supervisor 最多创建一次绑定原 `delegationId` 的 continuation child；`agent.delegate` 必须提交 `continuationOfDelegationId / questionsSha256 / answersSha256`，Runtime 自动派生稳定 continuation identity，不依赖已清理的 pending action，也不得按单个答案重复创建 child。
|
||||
|
||||
问题 envelope、问题数量、字段长度和 SHA 校验均 fail-closed；问题正文只在受保护的 Runtime sidecar / 父 run 上下文中流转，不写入公共审计。若合并后的问题超过用户输入上限，Runtime 停止自动提问并进入 reconciliation，等待人工核对。
|
||||
|
||||
## 目标
|
||||
|
||||
在 Genarrative 内建设独立桌面 App：普通用户通过项目开发工作台中的陶泥儿对话、资源画布、运行状态和确认操作，让平台生成保存在本地的可运行 Web 游戏原型，并通过本地 HTTP server 预览；主窗口提供运行时配置入口，用于保存发布版 AppData / Tauri 配置目录里的 LLM 配置及受控开发者 External Editor 配置。普通客户素材画布使用平台登录态调用内部编辑器 API，不展示或要求填写画板 Base URL / API Key。任务明细、原始文件、命令日志和专业 Agent 调试控制仍放到开发构建的独立开发窗口。v1 的生成闭环仍以 Web 小游戏为主，同时允许用户打开已有 Godot 项目：所选含 `project.godot` 的目录直接成为项目根，Agent 使用标准运行档在该目录内继续修改，只新增并保留 `.agent/` 作为运行元数据，不创建 `game/`、`assets/`、`memory/`、`exports/` 平行目录；本期不扩展 Unity、Godot 内嵌预览、云同步或插件市场。
|
||||
@@ -40,7 +48,7 @@
|
||||
- Supervisor 持久决策与单主条件美术：game-chat 的关键词、用户是否报告“美术未接入”、占位状态和当前资产探测只形成 `advisoryOnly=true` 的补充上下文，不得直接重置 Graph、预完成美术节点、选择复用/生成分支或继承历史试玩类型。当前根 Run 没有持久化 Supervisor 决策时，scheduler 不启动任何 child；Supervisor Provider 只通过 auto-safe 的 `agent.route_manifest` 提交 `game-chat-workflow-decision.v2`：`intentSummary` 是 Supervisor 自行理解并持久化的用户意图，`strategy=audit-existing-first` 只是固定安全执行策略，两者不得混用。此动作不能审计、生成、委派或替代后续判断，也不能把整体视觉重做解释成整套美术的强制重生成；成功后 Runtime 只启动唯一 `code-prototype` 主 Agent。升级恢复时严格校验 v1 sidecar 的旧 fingerprint，并从完成合同绑定的有效任务恢复 `intentSummary`；旧 `code-director` coverage/route 只作为迁移输入，不作为当前完成证据，必须由同一根 Run 的 `code-prototype` 重新 `asset.list` 后原位替换为单主合同。确定性 `code-prototype` Run 仅兼容已知 canonical task 文本版本，其余 task/binding/root 身份继续失败关闭；升级前已运行的 fixed-graph 美术 child 不再具备任何 mutation 或生图权限。主 Agent 必须以当前正式资产、Canvas 登记、私有图集合同、四张语义切片和 art manifest 判断真实缺口；完整覆盖时直接接入，不得生成或扣费。只有可证实缺失 `art-spec` 或核心 spritesheet 时，主 Agent 才可对相应 `art-director` 或 `art-asset-plan` 建立一条 durable 委派；每次最多一个活跃美术 child，child 仅可写 `assets/**`，不得修改 `game/**` 或接入/验收游戏。若两个槽位都缺失，必须先完成 `art-director`，由同一主 Run 认领其 `EvidenceReady` delivery 后，才能委派依赖规范图的 `art-asset-plan`；失败或未就绪 delivery 不得消耗不可重试的图集委派槽位。主 Agent 认领必要回执后继续同一 Run 完成素材接入、原玩法语义校验、`game.static_smoke` 与桌面/移动 `preview.validate`。绝对硬截止对嵌套美术 child 继续核验 `root -> code-prototype -> agent-delegate` 完整身份并保留未知外部生成的 reconciliation 证据。Runtime 只负责校验根/父子身份、当前 revision、路径、Canvas 登记、缺口/路由 fingerprint、写入范围及完成证据；纯“继续”仍走既有正式 continuation 合同，普通美术措辞不得借用更老项目的具体试玩场景。不得以增加 loop 预算、伪造 revision、机械改写 manifest 或重放历史图片 action 代替 Supervisor 决策和程序侧审计。
|
||||
- ready-task 对账取消续跑：未知工具结果仍停在 `needs-reconciliation` 且禁止自动重放；人工核对后显式取消原 child，保留 cancel tombstone，旧 child 和旧父 Run 按真实终态收口。若随后创建同 Session、同 Supervisor source、同有效任务语义的 continuation，新完成合同只对同时具有历史 `failed / needs-reconciliation`、最终 `cancelled` 和 durable tombstone 的 ready-task，把当前 manifest 对应 failed 节点恢复为 pending，并由 scheduler 创建全新 child Run。manifest 的读取、failed 筛选、每任务一次的 child journal 索引、证据重验和写回必须位于同一项目写锁域；较新的无 child 根 Run 只有在 durable journal 精确表明为旧 failed Graph 在进入调度前即失败时才能跨过，scheduler 自身失败必须阻断借用更老 tombstone。普通失败、无 tombstone、不同 source/Session/任务语义或证据冲突均保持失败关闭；不得复活旧 pending action、补造 observation 或把取消任务标成 completed。
|
||||
- 完成门静态分析预算：Canvas 视觉门必须先做只会提前拒绝的词法预检。经典或模块脚本同时不含大小写精确的 `import` 与 `export` 字节序列时，不运行模块依赖语义分析；纯 `export ... from` / `export * from` 仍须进入正式模块图分析。当前脚本不含目标文件名或任一已绑定 DOM 图片元素 ID 时，先低成本解码 `\\xNN`、`\\uNNNN`、`\\u{...}`、简单转义和续行；解码后仍无候选才不运行完整 Canvas alias / 函数可达性分析，解码不确定则保守进入 Oxc。存在任一候选时仍执行原 parser、semantic binding、解码后的 computed 属性/StringLiteral 路径、可达 `drawImage`、可见 Canvas、路径大小写和动态 namespace 写入门禁；HTML 中存在某个绑定元素不得使所有无关 JavaScript 单元进入重分析，禁止把词法命中当作通过条件。
|
||||
- Provider 故障展示：Provider retry 的“是否可重试”继续使用 `upstream-5xx` 等稳定类别判断，但 durable retry record 保留安全的精确 `upstream-<HTTP status>` 身份。等待态必须从真实 record 显示 HTTP 状态、`nextAttempt/maxRetries` 与当前持久退避剩余秒数，例如“Provider 上游返回 HTTP 503，准备自动重试 1/3；预计 8 秒后重试”；不得以动画或前端自增计时伪造 attempt。重试耗尽的 Runtime 私有错误只保存 `kind/httpStatus/fingerprint/chars/retryAttempt/maxRetries/retryState`，前端和持久 conversation 仅在字段顺序、范围、状态一致且无尾随正文时派生“上游服务返回 HTTP 503；自动重试已耗尽（3/3）”；其它错误使用固定安全摘要。Provider 响应正文、URL/query、凭据、本地绝对路径、fingerprint、字符数和 `[redacted ...]` 占位符均不得进入用户可见消息。
|
||||
- Provider 故障展示：Provider retry 的“是否可重试”继续使用 `upstream-5xx` 等稳定类别判断，但 durable retry record 保留安全的精确 `upstream-<HTTP status>` 身份。等待态必须从真实 record 显示 HTTP 状态、`nextAttempt/maxRetries` 与当前持久退避剩余秒数，例如“Provider 上游返回 HTTP 503，准备自动重试 1/3；预计 8 秒后重试”；不得以动画或前端自增计时伪造 attempt。重试耗尽的 Runtime 私有错误只保存 `kind/httpStatus/fingerprint/chars/retryAttempt/maxRetries/retryState`，前端和持久 conversation 仅在字段顺序、范围、状态一致且无尾随正文时派生“上游服务返回 HTTP 503；自动重试已耗尽（3/3）”。`codex_app_server` 收到 failed turn 时必须读取协议 `turn.error.codexErrorInfo`，按上下文超限、会话预算、用量、鉴权、请求、策略、sandbox、会话恢复和连接 / HTTP 状态生成封闭稳定分类；不得丢弃该字段后统一写“turn 执行失败”，也不得把 `message / additionalDetails` 原文公开。自主构建已有本地确定性完成文案时，也只允许 `empty-response / deserialize` 这类回复形状错误使用 fallback；鉴权、额度、上下文、策略、sandbox、配置、网络和上游错误必须保持失败，禁止用完成文案掩盖。正式面、阶段记录、Runtime 活动详情和持久 conversation 从稳定分类派生同一份可行动中文摘要；失败事件活动详情只消费后端 `publicText`，缺失时退回固定安全 summary，禁止公开私有 `detail`。旧 Supervisor 与专业 Agent 失败 conversation 必须在展示时经过相同安全映射。`needs-reconciliation` 是停止自动推进、轮询和活跃计数并等待人工处置的终态，明确显示为待核对，不能显示为普通运行中或已完成；未知分类仍使用固定安全兜底。Provider 响应正文、URL/query、凭据、本地绝对路径、fingerprint、字符数和 `[redacted ...]` 占位符均不得进入用户可见消息。
|
||||
- 跨轮阶段记录：game-chat 父 run 进入真实 completed / failed / cancelled 终态后，客户端等待唯一 `code-prototype` 主 Run 及其所有必要美术委派都已形成真实终态，再把本轮、主 Agent 进度、是否复用/补齐素材、最新试玩 / 静态检查、最近返工决定和已登记成果图片路径整理成一条 `【Supervisor 阶段记录】` 项目 assistant 消息。父 run 先终态而 child 或 manifest 仍在 hydration 时不得以陈旧快照提前归档，要暂存终态 Runtime 并在状态刷新后重试。页面初始 hydration 若直接读到缺少阶段记录的真实终态 run，也必须补写，但 `idle` 不是可归档终态。每个“项目 + 父 run”最多追加一次，进入现有 `conversation.write` 权限与项目 conversation 持久化链路，下一轮及重载后继续保留。阶段记录不是 Supervisor Runtime 正式回复，不写入 Agent Session、不增加 final assistant 数量，也不逐条复制原始事件或内部正文。
|
||||
- 图片成果：当前 manifest 新增或恢复已登记的 PNG / JPEG / WebP 资源时，聊天消息流同步显示 Runtime-owned “Supervisor 成果图片”卡，最多展示最新 4 张并随 manifest 原位更新。图片必须通过现有 `read_local_project_image_preview` 读取，只允许当前授权项目中 `assets/` 下的已登记资源，继续执行 `file.read` auto 权限、真实格式、大小、尺寸、普通文件、祖先目录和项目根边界校验；前端只接受返回路径、媒体类型和 `data:` 前缀与请求完全一致的结果。缩略图点击后使用独立模态查看器，支持按钮与滚轮缩放、指针拖拽、双击 / 按钮复位、Esc / 按钮 / 遮罩关闭，移动端占满视口；不得在聊天卡下方追加展开区。图片卡不写入 conversation，不解析 assistant 文本中的任意 Markdown / 绝对路径，也不开放 `.agent` 验收截图读取。
|
||||
- Run 接管：External Runner 模式下首次提交可能返回“旧 canonical state + 新 `acceptedRunId`”；页面必须以 `acceptedRunId` 作为本轮权威身份，在 state 尚未切换时显示“已投递，正在同步 Agent Runner”，并允许该 run 的 Tauri event 或轮询结果接管。不得把旧 idle state 当作本轮结果、过滤新 run 事件，自动预览授权也必须绑定 `acceptedRunId`。
|
||||
@@ -189,7 +197,7 @@ V1.47 在只读工具边界和 batch v3/v2/v1 恢复终审修复后的最新独
|
||||
|
||||
V1.17 计划快照随 `game-creator-runtime-context-bundle.v3` 持久化，v2 在通过原身份、revision 和 verification gate 校验后从当前 Runtime state 补齐计划字段继续恢复；计划元数据本身不推进项目 revision、不改变 verification gate，也不触发项目权限确认。开发 UI 和 CLI 有界展示 revision、说明与完整 8 步；正式用户的 Supervisor 只展示完成数、当前步骤、等待对象、下一步和协作数量的紧凑摘要。恢复、same-run steer 和真实 Provider 的完整验收矩阵以 Runtime V1.17 章节为准；2026-07-16 已在当前 v5 context 上完成正式 `openai_chat / gpt-5.5` 的同 run steer + Runner 强杀恢复专项，门禁状态为 PASS。
|
||||
|
||||
2026-07-18 起，正式项目工作台的总控与策划 / 美术 / 程序 Agent 状态统一投影当前 Supervisor 父 run 的真实 Runtime；专业 Agent 只有在 `parentRunId` 精确匹配该父 run 时才可进入当前项目状态列表。普通项目页在 Tauri event 之外必须保留只读轮询，兜底独立 Runner 无法可靠投递 App event 的情况；短暂读取失败时保留最后一份可信快照，不得清空或倒退界面状态。正式面只展示真实运行阶段、计划完成数 / 总数、最近更新时间、失败、待确认与待回答等紧凑状态；专业 Agent 的确认或拒绝必须同时绑定真实 `agentId + runId + actionId`。`manifest.tasks` 只能在没有匹配 Runtime 时作为回退，不得覆盖真实 Runtime；正式面不展示内部 `currentAction`、`observation`、工具计划正文、Provider 错误原文、fingerprint 或字符计数，transport / timeout / 鉴权 / 限流等失败只映射为可理解的安全文案，也不得根据 manifest 或动画伪造生产中、进度百分比或完成状态。当前父 run 或专业状态集合变化时 Runtime 状态区回到顶部，总控摘要在内部滚动期间保持可见。
|
||||
2026-07-18 起，正式项目工作台的总控与策划 / 美术 / 程序 Agent 状态统一投影当前 Supervisor 父 run 的真实 Runtime；专业 Agent 只有在 `parentRunId` 精确匹配该父 run 时才可进入当前项目状态列表。普通项目页在 Tauri event 之外必须保留只读轮询，兜底独立 Runner 无法可靠投递 App event 的情况；短暂读取失败时保留最后一份可信快照，不得清空或倒退界面状态。正式面只展示真实运行阶段、计划完成数 / 总数、最近更新时间、失败、待确认与待回答等紧凑状态；专业 Agent 的确认或拒绝必须同时绑定真实 `agentId + runId + actionId`。`manifest.tasks` 只能在没有匹配 Runtime 时作为回退，不得覆盖真实 Runtime；正式面不展示内部 `currentAction`、`observation`、工具计划正文、Provider 错误原文、fingerprint 或字符计数。transport / timeout / 鉴权 / 限流、Codex 稳定错误分类，以及验证、预期产物、权限策略、预算、恢复对账和持久化等常见 Runtime 失败必须映射为可理解、可行动的安全文案；底部子 Agent 状态卡在失败时直接展示同一安全摘要，不能只写“失败”或“子 Agent 任务失败”。不得根据 manifest 或动画伪造生产中、进度百分比或完成状态。当前父 run 或专业状态集合变化时 Runtime 状态区回到顶部，总控摘要在内部滚动期间保持可见。
|
||||
|
||||
2026-07-19 起，当前父 run 下的专业 Agent 进入 `failed` 后，正式工作台必须提供“在当前项目重试”恢复入口，不得要求用户新建项目。重试必须精确核对原 `agentId + runId + parentRunId`，复用原 task、active Session 和父 run 归属，同时生成新的专业 Agent runId；新 run 继承已持久化的上下文和父子绑定，不覆写旧失败 run 的审计事实，也不得把 UI 重试解释为底层 transport 根因已修复。`agent.resume` 默认 `confirm` 不变：自动 retry command 继续执行 auto gate；正式失败卡按钮自身是本次明确确认，使用 deny-only 的 confirmed retry command。按钮必须原卡即时显示“正在提交重试”、受理或安全错误；若 Supervisor 已为同一 delegation 准备合同 repair，则该按钮优先确认既有 repair，避免重复派发。
|
||||
|
||||
@@ -915,6 +923,7 @@ game-project/
|
||||
- 2026-07-28 Project Supervisor 首批协作 repair 累积约定：针对每轮只返回单个 function call 的 Provider，Runtime 从首次触发协作缺口的响应开始，跨文本 JSON、OpenAI Chat tool call 与 OpenAI Responses function call 修复轮次累积合法的 `agent.delegate / agent.spawn_isolated`；同一 `agentId` 以最新响应覆盖旧 action，唯一 `agent.spawn_isolated` 槽位也以最新响应覆盖，禁止把修正版追加成同批第二个 spawn。每轮根据累计结果计算尚缺的静态 Agent，并仅在缺失集合含明确 Agent ID 时收窄下一轮 function schema 的 `agentId` enum；`missingStaticAgents=none` 是空集合哨兵，不是 Agent ID。只有累计首批满足完整协作合同时才成批提交，已满足的 Agent 不得因后续修复重复派发。
|
||||
- 2026-07-28 pending / provider action 安全持久化约定：自然语言任务中的裸短语 `api key` 不是泄密证据，不能据此拒绝 action；否则 `agent.delegate` 的“不要暴露 External Editor API Key”等安全指令会被误判。API Key 赋值只允许完整受控状态或固定无密钥降级说明，禁止用安全状态前缀放行后续任意内容；`none-but-secret`、`not configured; actual value ...` 等必须失败关闭。Markdown 装饰、反引号或环境限定标签不能改变赋值语义，`**API Key**:`、`` `API Key`: ``、`API Key（生产）:` 仍必须进入同一检测。持久化前继续检测结构化 `apiKey / api_key`、`Authorization / Cookie`、`token / Bearer` 标记和已知 secret token 形状，命中真实凭据时仍失败关闭。
|
||||
- 2026-07-28 Windows Provider retry 恢复修正：`provider_retry::list_at` 从绝对路径剥离项目 root 后，按路径组件重组成 `/` 分隔的 portable UTF-8 相对路径，再交给 Runtime JSON sidecar 读取器。不能直接使用 Windows `Path::to_str()` 的反斜杠文本，否则应用重启、Runner recovery scan 和正式 `--agent-resume` 都无法推进已到期的 `waiting-for-provider-retry` run。全部 provider retry 列举、previous 恢复、去重和路径冲突回归必须在真实 Windows 通过。
|
||||
- 2026-08-12 Windows Codex 启动链修正：AGC 不再直接依赖可能命中 WindowsApps shim 的 `codex` 命令，而是逐个执行 `--version` 验证候选，优先发现 npm 安装中的原生 `codex.exe`，并回退到 Codex Desktop 的原生 CLI；app-server 启动参数只关闭当前 CLI 仍支持的 feature flag。可信根 Project Supervisor 尚未冻结 Goal Contract 时，首轮和协议修复轮都只广告 `agent.goal_contract`，禁止计划更新、回复或其它动作抢跑。GUI 显式传入的 `--config-dir` 必须贯穿 Tauri 与 Cargo 的参数分隔并作为应用参数保留，setup 优先复用该目录，避免开发版或发布版误占默认 AppData 的 GUI owner lock。发布验收必须使用 release/安装目录 EXE 启动真实 Runner，并核对 CLI 版本、app-server 生命周期、Goal Contract 持久化、后续项目观察以及最终 completed/idle 状态，不能只以构建成功或 mock 测试代替。
|
||||
- `npm run agc:test:chat` 未显式指定配置且找不到 AppData 配置时，只在 stdin / stdout 都是 TTY 时询问并启动同一 `agc:config --configure-only` 向导，非 TTY 或显式无效 `--config-dir` 直接失败。测试环境只把主配置和存在时的 local overlay 复制到带随机 sentinel 的单次隔离 AppData；副本必须是独立的无符号链接普通文件，POSIX 权限为目录 `0700` / 文件 `0600`，不复制正式 Runner endpoint、lock 或其它 AppData。自动任务默认 50 分钟且可用 `--timeout-minutes` 显式设置；超时或信号会终止独立子进程树，POSIX 先向进程组发送 `SIGTERM`、等待 10 秒后发送 `SIGKILL` 并再等待 5 秒，Windows 使用 `taskkill /T` 并在强制阶段追加 `/F`。超时和信号分别以 `124 / 130 / 143` 失败退出，隔离 Runner 收束另有 20 秒上限；Runner 未空闲或收束失败时保留隔离配置和项目，验收未完成但 Runner 已安全退出时只保留一次性项目证据，不把中断报告为成功，也不误删正式 AppData。
|
||||
- 自动验收现在严格要求 manifest 恰好包含固定 16 个不重复 task ID 且全部为 `completed`，并逐任务核对当前父 Run 下唯一 logical run、一次 started、一次 completed、零 failed / cancelled 和一次 manifest projection；七份基础正式产物存在并满足文件 / JSON / 非占位入口检查，配置画布 API Key 时再增加 `art-spec / ui-prototype / art-spritesheet` 三张图片。PNG 验收不止检查 magic / IHDR / 比例，还会校验 chunk CRC、zlib 解压、scanline 长度、索引色 PLTE 和未知 critical chunk。Runtime 根 Supervisor 的完成合同已升级为 `game-creator-autonomous-completion-contract.v2`，`baselineArtifacts` 必填并纳入指纹，旧 v1 或缺基线合同失败关闭；最终门禁要求最后一次验证工具是 `game.static_smoke`、状态通过且 `verifiedRevision == currentRevision`。`preview.validate` 回执必须绑定同一 Agent、run、current revision、当前 `game/index.html` 摘要、固定试玩场景、持久浏览器报告以及 desktop / mobile 两张截图的路径、摘要和 PNG 身份，任一证据缺失、变化、过期或来自其它 run / revision 都阻止最终回复。旧两图合同的确定性证据不替代新三图 DAG 验收；新合同实现后必须新起独立单轮。
|
||||
- `design-foundation` 已增加专属职责边界：项目文件只允许写 `memory/project.md` 与 `game/game_design.md`；配置 External Editor API Key 且合同要求界面原型时，只额外允许固定 `assets/ui-prototype.png`。它不得创建、修改、删除或补丁 `game/index.html`，不得改动其它程序实现、发布、音频或美术素材，也不得调用 `preview.start`、`preview.validate`、`game.static_smoke`，或借 `command.exec / command.start / command.run_limited` 启动预览服务、浏览器、Playwright 和桌面 / 移动试玩。程序和质量 Agent 的共享 Runtime 工具合同不因此缩减；有 / 无画布配置和其它 Agent 不受影响的聚焦回归为 `3/3` 通过。
|
||||
@@ -1051,6 +1060,15 @@ game-project/
|
||||
|
||||
## 2026-08-11 通用 Goal Contract 与动态 Acceptance Graph
|
||||
|
||||
## 2026-08-13 Windows 本地运行与恢复稳定性
|
||||
|
||||
- Windows 原子文件事务在 rename 安装成功后必须立即释放临时文件句柄；恢复扫描遇到仍被活跃 writer 独占的临时文件时保留该文件并继续扫描已提交账本，不能让单个 `ERROR_SHARING_VIOLATION / ERROR_LOCK_VIOLATION` 阻断整个恢复。新建目录与安装关键 sidecar 后仍按既有平台能力同步文件和目录，不能把 Windows 目录 `sync_all` 失败误判为业务提交失败。
|
||||
- `.agent/project.lock` 的 `create_new` 在 Windows 目标存在或处于 delete-pending 竞争时，可能返回 `ACCESS_DENIED(5)`、sharing violation(32) 或 lock violation(33)，这些结果统一投影为“项目正在被其他写操作占用”并进入既有有界等待；其他权限错误继续失败关闭。Runtime 测试若在终态后立即二次恢复，必须同时等待 `status/phase` 终态和 Agent execution lane 释放，不能只观察 state JSON。
|
||||
- Windows 子进程启动把 `npm.cmd` 解析为当前 Node 与 `npm-cli.js` 的显式 argv，保留 CRLF/ANSI/ConPTY 处理和 Job Object 生命周期；项目验证使用隔离 Cargo target wrapper，避免开发 GUI 或旧 runner 持有测试需要替换的 EXE。Agent DB 打开继续允许同进程读写共享并修复唯一 JSONL 残尾，不能用默认独占句柄破坏并发读取。
|
||||
- Node ESM 脚本必须用 `fileURLToPath()` 把 `import.meta.url` 转为 Windows 本地路径，禁止直接把 URL pathname 交给 `path.resolve()`；真实 agent-run smoke 的浏览器探测覆盖 Windows Chrome/Edge 固定安装位置。开发态 smoke 在旧安装版持有默认 AppData GUI owner 时使用独立 `--config-dir`，不得终止用户现有客户端。
|
||||
|
||||
- 2026-08-12 计划拒绝恢复：结构化 `runtime.plan_update` 被 Runtime 拒绝后，下一轮 Provider 请求按请求级目录收窄到实际项目 mutation 与 `respond_to_user`（已进入协作编排的 Supervisor 保留 `agent.delegate / agent.run_status`），并明确禁止再次规划、读取、搜索或验证；后续已有真实 mutation observation 后解除临时目录，不改变持久 executable policy。
|
||||
|
||||
- Goal Contract 绑定 project、可信根 Run Profile、source task SHA-256 和不可变 fingerprint；同一根 Run 只允许幂等重放完全相同的合同，语义变化必须进入新根 Run。已有合同的根 Supervisor 收到 steer 时，Runtime 必须按旧 rootRunId 串行化转换并在持锁后重验 Session 当前权威 Run，再取消并确认旧 rootRunId 的静态、ready、isolated 整棵树已进入终态或 `needs-reconciliation`；旧树未停稳时拒绝启动 replacement，停稳后才在同一 Session、source 和 Run Profile 创建唯一的新根 Run，不能把新增要求塞进旧合同继续完成。合同摘要作为 `decision` 投影到共享黑板，JSON sidecar 才是权威源；黑板冲突条目和专家事实仍追加保留。
|
||||
- 所有静态 delegate、ready child 和 isolated child 都只读继承根合同与当前 Acceptance Graph；isolated child 还必须实际收到自己的 `acceptanceCriteria / expectedArtifacts / writeScopes`。继承上下文不扩大工具、目录、写入权限或 expectedArtifacts。专业 Agent 只能报告局部结果、证据和剩余风险，不能修改根合同、根验收图或宣布用户总目标完成。
|
||||
- Acceptance Graph 节点由 Supervisor 针对当前任务动态生成，不来自玩法模板。节点记录 required/optional、依赖、状态、证据引用与摘要；只有同一可信根 Supervisor 能调用 `agent.acceptance_update`，且该动作必须独占一轮。failed 与 not-observed 节点形成下一轮定向返工集合，未提交的 passed 节点保持不变。
|
||||
|
||||
@@ -58,7 +58,7 @@ apps/ai-game-creator-shell/src/features/asset-canvas/tauriImageCanvasHostAdapter
|
||||
- `image-canvas-core` 只含纯 TypeScript 的画布模型、几何、选择、图层命令、历史、序列化、防御校验和状态机；不得依赖 React、DOM、Tauri、HTTP、账号、钱包或浏览器存储。
|
||||
- `image-canvas-react` 只含 React 视图、hooks、交互控制器和通用 UI，依赖 core 和注入的 Host Port；不得直接 import Tauri API、站点请求客户端、账户 store 或钱包 store。
|
||||
- 网站 adapter 可以依赖账户、钱包、现有服务端 editor project、云端素材库、OSS/asset object 和生成 API。
|
||||
- Tauri adapter 可以依赖 `invoke/listen`、本地项目上下文、受控媒体命令、manifest、项目 revision、草稿 sidecar 和当前平台登录态；受控开发者模式才可依赖 External Editor API 配置。
|
||||
- Tauri adapter 可以依赖 `invoke/listen`、本地项目上下文、受控媒体命令、manifest、项目 revision、草稿 sidecar 和 AppData 私有 External Editor API 配置；该配置由独立“运行时配置”对话框维护，不进入共享画布或项目事实。
|
||||
- 依赖方向只能是“宿主 adapter -> React/UI -> core”。core/react 不得反向 import 任一宿主。
|
||||
|
||||
### 3.2 禁止复制的验收门
|
||||
@@ -200,7 +200,7 @@ interface ImageCanvasHostPort {
|
||||
- `hostRevision` 是宿主权威提交版本的字符串表示：Tauri 使用十进制项目 mutation revision，网站使用现有服务端 editor project revision。共享 UI 只透传/展示，不比较不同宿主的 revision。
|
||||
- `commitId/idempotencyKey` 由共享流程在第一次正式保存前生成；响应未知时两宿主都复用原完整请求。`expectedHostRevision` 由 adapter 从已加载的权威宿主快照提供，Tauri 必须无损解析为本文的安全整数 `expectedRevision`。
|
||||
- Web adapter 把草稿、导入、生成、导出和提交映射到现有服务端 editor project、云端素材库及账户/钱包链路。
|
||||
- Tauri adapter 把草稿、导入、导出和提交映射到本文第 7 至 11 节的本地合同；普通客户生成通过平台登录态调用现有内部编辑器/资产/任务状态 API，后端按 owner 进入统一生成队列与泥点预扣/退款。客户界面不显示或要求填写 Base URL / API Key。External Editor API 只作为第三方 Agent、CLI 和受控内部验收通道；任一模式的凭据都不能进入项目 sidecar、manifest、事件或错误正文。
|
||||
- Tauri adapter 把草稿、导入、导出和提交映射到本文第 7 至 11 节的本地合同；远端媒体编辑通过 AppData 私有 `editorApi.baseUrl/apiKey` 使用 External v1，后端按 owner 进入统一生成队列与泥点预扣/退款。素材画布工作区不显示或要求填写 Base URL / API Key，普通 Launcher、开发工作台和独立 game-chat 的独立“运行时配置”对话框均可维护这两个字段；凭据不能进入共享画布、项目 sidecar、manifest、事件或错误正文。
|
||||
|
||||
### 3.4 主站 UI 对齐与共享画布 chrome
|
||||
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -236,7 +236,7 @@ npm run check
|
||||
|
||||
仓库级 Gitea Actions 工作流固定为 `.gitea/workflows/project-ci.yml`，在向 `master` 或 `codex/ai-game-creator-app` 推送、创建或更新 PR，以及手工触发时运行。工作流拆成四个必须通过的 job：
|
||||
|
||||
- `Repository checks`：执行 `npm run lint`、主站与后台生产构建、内容数据检查和提交差异空白检查。
|
||||
- `Repository checks`：调用唯一入口 `npm run check:repository-ci`，执行 `npm run lint`、主站与后台生产构建、内容数据检查和提交差异空白检查。本地 master `pre-push` 复用同一入口，禁止在 workflow 与 hook 中维护两份近似命令。
|
||||
- `Frontend tests`：按根 lockfile 与 `apps/ai-game-creator-shell/package-lock.json` 分别执行干净的 `npm ci`，再独立执行根 `npm run test`、`npm run bgfilter-worker:smoke-test`、`npm run check:production-health-patrol`、`npm run check:production-api-release` 和 `npm run check:production-api-deploy`，让 Vitest、Node test smoke harness 及不依赖真实服务的生产巡检 / 发布 / 部署行为 fixture 在 Gitea job 中持续执行；其中 `.test.mjs` 使用 Node test runner，不依赖 Vitest 的 `scripts/**/*.test.ts` 收集规则。
|
||||
- `Backend tests`：先对 `server-rs/Cargo.lock` 执行带 5 次整命令级有界重试的 `cargo fetch --locked`，再执行 `npm run check:server-rs-ddd`、`cargo test --locked --workspace --no-fail-fast`、`api-server --all-targets` 编译和 `spacetime-module` 编译；依赖准备必须位于会触发 Cargo build 的 DDD / 产物边界门禁之前，避免锁新增依赖未命中镜像缓存时绕过既有下载重试。runner 安装 `ffmpeg`，避免视频抽帧测试因工具缺失提前返回。依赖真实服务或密钥的测试必须显式 `ignored`，不能让普通 PR job访问现场环境。
|
||||
- `Native shell tests`：按根 lockfile 与 AI 游戏创作壳独立 lockfile 安装依赖后执行 `npm run check:native-shells`，覆盖微信壳、Expo 和 Tauri 的完整验收，并确认桌面壳与 AI 游戏创作壳的 `Cargo.lock` 都没有被构建过程改写。`codex/ai-game-creator-app` 分支的同名脚本还会执行 `npm run ai-game-creator-shell:check` 和 AI 游戏创作壳 release build smoke；共享 Agent Runtime 后台锁 suite 固定 `--test-threads=1`，不能用并行偶发失败后的逐项通过替代整套稳定门禁。
|
||||
@@ -268,6 +268,8 @@ bash scripts/gitea-ci-job-image.sh load-runner
|
||||
|
||||
workflow 首次成功运行后，在 Gitea `master` 分支保护中把 `Project CI / Repository checks (pull_request)`、`Project CI / Frontend tests (pull_request)`、`Project CI / Backend tests (pull_request)`、`Project CI / Native shell tests (pull_request)` 四个完整 context 都设为合并必需检查，并从最近一周已上报 context 表复核名称后再保存。不能只填裸 job 名，否则无法匹配 Gitea 实际上报的 `<workflow> / <job> (<event>)`。只提交 workflow 文件不会自动创建 runner，也不会自动修改分支保护；如果 Actions 长时间停留在等待状态，先到仓库或组织的 Actions runner 页面确认存在在线、带 `genarrative-ci` 标签的 runner，再检查精确 Image ID 是否已装入内层 Docker。
|
||||
|
||||
master 日常交付必须禁止直接 push，只允许经 PR 在当前 head 的四个 required context 全绿后合并；本地 `pre-commit` 的 staged ESLint/Prettier 和 master `pre-push` 的 Repository checks parity 只用于提前发现问题，可被 `--no-verify` 绕过，不能充当服务端权威门禁。紧急直推白名单如需保留，应按人员和时限最小化，并要求执行同一 `npm run check:repository-ci <base> <head>` 后回读 push CI。
|
||||
|
||||
视觉小说负向扫描与验收门禁：
|
||||
|
||||
```bash
|
||||
|
||||
Reference in New Issue
Block a user