合并最新主分支并同步资源管理修复
合入智能体协作提示词与游戏验收边界更新 保留资源管理审核修复与合并后门禁整理 # Conflicts: # docs/project-memory/shared-memory/pitfalls.md
This commit is contained in:
@@ -5980,10 +5980,20 @@
|
||||
## 2026-08-03 game-chat 开发态前后端同源与快车道恢复
|
||||
|
||||
- 启动决策：`npm run agc` 与 `npm run agc:game-chat` 统一先经外层 Node 启动器预检 `3080`。在 marker 尚不能证明 worktree 归属时，任何已占用的 3080 都不得复用，并必须在原生窗口创建前失败关闭；Tauri CLI 退出后必须收束已启动的客户端进程树，不允许终端已退出但窗口与 Runner 仍假在线。
|
||||
- 首波决策：普通 GUI / CLI 的正式 16 节点 DAG 与 game-chat 首版 lane 都只把 `design-director / art-director / code-director` 作为首波 ready Agent。正式 DAG 的 `design-foundation` 等待策划与美术 Director，`code-prototype` 等待程序 Director 及数值、美术、音频三条底层产物链；game-chat 则在三个 Director 全部完成后才启动 `code-prototype`，再串行执行静态检查和试玩。首波以外的非 repair 底层 Agent 只能由依赖就绪调度或上层明确返工合同按需激活。
|
||||
- Runtime 决策：game-chat 六任务 lane、平台美术、单轮收束和自动预览只由持久 `project-supervisor-game-chat` root source 启用。hydration 对 `Pending` 的容忍只适用于当前 source-aware lane 的三个零依赖首波任务，不再硬编码单个历史任务。页面进度、阶段记录和 final-reply 白名单统一使用六项任务与 `x/6`。
|
||||
- 首波决策：普通 GUI / CLI 的正式 16 节点 DAG 与 game-chat 首版 lane 都只把 `design-director / art-director / code-director` 作为首波 ready Agent。正式 DAG 的 `design-foundation` 等待策划与美术 Director，`code-prototype` 等待程序 Director 及数值、美术、音频三条底层产物链；game-chat 在策划与美术 Director 完成后启动 `art-asset-plan` 生成透明图集，`code-prototype` 必须同时等待三个 Director 与该图集任务，再串行执行静态检查和试玩。首波以外的非 repair 底层 Agent 只能由依赖就绪调度或上层明确返工合同按需激活。
|
||||
- Runtime 决策：game-chat 七任务 lane、平台美术、单轮收束和自动预览只由持久 `project-supervisor-game-chat` root source 启用。hydration 对 `Pending` 的容忍只适用于当前 source-aware lane 的三个零依赖首波任务。页面进度、阶段记录和 final-reply 白名单统一使用七项任务与 `x/7`。
|
||||
- 显式协作合同：autonomous 的旧 `code-prototype + quality-review` 首批合同退出。显式 project collaboration policy 或持久 batch 恢复若进入首批 `agent.delegate` 路径，只允许且要求三个 Director 各一次；策划与程序 Director 是只读规划且 `expectedArtifacts=[]`，美术 Director 是非只读规范图任务且必须交付 `assets/art-spec.png`。任何非 repair 底层委派与 isolated child 都在首批失败关闭；默认 manifest DAG 仍是唯一自动首轮执行链，不额外复制三个 Director 委派。
|
||||
- 输出决策：保留未提交 `streaming / ready` 的当前 revision 门；已提交的专业 Agent final reply 继续使用既有 durable response-stream 身份，后续项目 revision 变化不再隐藏早期阶段回复。
|
||||
|
||||
## 2026-08-03 game-chat 失败续跑与首版产物保护
|
||||
|
||||
- 事故事实：`game01` 的首个根 run 已交付并验证水晶下落方块原型，但父 run 在上下文压缩后因 token 上限失败；用户随后输入“继续”时，客户端创建了 task 仅为“继续”的新 game-chat root，完成合同重置 seed manifest，五分钟 fallback 再把该短语当主题整文件覆盖 `game/index.html`。这不是模型随机换题，而是 root 目标未继承、每新 run 无条件 reset 和 fallback 无条件 `file.write` 叠加形成的确定性缺陷。
|
||||
- 续跑决策：同一 Supervisor Session、同一持久 source 的最近失败根 run 后，严格继续短语创建 successor root，并继承前序原始任务、baseline revision / artifact 身份；纯继续识别统一由一个精确函数负责，覆盖“继续 / 接着 / continue / go on”等无新约束短语。真正新需求、跨 Session、跨 GUI / CLI / game-chat source、前序正常完成或含具体新约束的输入继续创建独立新任务并重置本轮 manifest。successor 不复用旧网络请求、pending、action、Provider lifecycle 或 sidecar，只继承业务目标和已提交项目事实。
|
||||
- 覆盖决策：game-chat fallback 只允许初始化缺失/占位入口的首次落盘。非占位 `game/index.html` 必须保留，并由当前 `code-prototype` 先读取和实际 patch，取得本人 `mutationRevision` 后才能运行 `game.static_smoke` 与交付；只读 smoke 不得冒充续作。确定性 fallback 只允许已实现真实语义的显式玩法模板：俄罗斯方块模板必须具备 10×20 棋盘、下落、移动、旋转、锁定、消行和触顶失败，收集模板只用于明确收集类目标，未知玩法失败关闭。纯继续目标未恢复时同样失败关闭。完成门新增 baseline 玩法连续性和 action-driven state 检查，generic Canvas 非空、三个按钮存在或静态 smoke 通过都不能单独证明任务没有换题。
|
||||
- 美术决策：`art-spec.png` 回归为规范图和下游派生 reference，不能铺作完整场景，也不能裁剪成玩家/目标。首版必须继续由 `art-asset-plan` 通过 icon-spritesheet 生成透明 `art-spritesheet.png`；桌面 Runtime 同时下载服务端 `iconImageSrcs`，按当前图集 resourceId 写入本地切片清单。game-chat 在任何本地落盘前要求稳定、非空的图集 resourceId，并在正式图集登记前要求切片严格等于四、每片 `sourceResourceId` 精确绑定整图，全部切片累计下载最多 `32 MiB`；四类差异按尺寸加规范 RGBA 像素摘要判定，PNG 编码字节不同不代表视觉内容不同。主图、四张 canonical 切片与切片清单作为一个提交合同，并把主图/切片摘要及 Canvas 身份冻结到 `.agent/runtime/art-spritesheet-contract.json` 私有回执；主图安装、回执或资产登记失败时必须恢复整组旧合同。generation 账本恢复允许对摘要一致的已落盘主图幂等补齐合同，摘要冲突不得覆盖。完成门重新读取切片时继续有界解码，并要求实际素材、公开清单、当前 Canvas 登记与私有回执在内容摘要、规范像素摘要、可见 alpha、四类唯一性和资源身份上全部一致。`code-prototype` 在活动 Canvas 中分别绘制玩家、方块/目标、障碍/场景和反馈四类不同切片。纯代码核心画面、猜测 atlas 等分坐标、单个裁切冒充全部类别、整图展示与路径诱饵失败关闭；编辑器仍允许仅有 `sliceWarning` 的完整透明图集完成，但 game-chat 必须等到真实切片可用。
|
||||
- 图集身份与恢复补充：canonical game-chat 图集是 External 通用资源模型的严格完成子集。主图与四个切片都必须含非空 `assetObjectId`，五个 ID 互不复用；同一对象在顶层、resource 与 asset 中重复出现的 `assetObjectId` 和 `taskId` 都必须逐项完全一致，冲突时不得择一冻结。公开切片清单和私有回执同时冻结 `sourceResourceId / sourceAssetObjectId / sourceTaskId / sourceCanvasProjectId / sourceReferenceResourceIds`，四项切片按 usage 唯一且逐项比较 `name / path / width / height / resourceId / assetObjectId / contentSha256 / pixelSha256`。旧项目仅缺私有回执时不得从可编辑公开清单伪造回执；只有同一 `project-supervisor-game-chat` 父 run 下处于 running 的 `art-asset-plan` scheduled child、固定输出路径且当前合同确实失效时，才允许 `replaceExisting=true` 原位 repair。任何 canonical 文件变化前，Runtime 必须在 `.agent/runtime` 私有事务目录原子持久化九个固定合同路径的旧状态并回读，随后写 `prepared` marker；主图字节先写 staging，再安装 canonical 主图，随后才提交四切片、公开清单、私有回执和 Canvas 登记，登记成功后写 `committed` marker 才可回收快照和 backup。恢复只在取得同一项目写锁后按持久 transaction id 扫描；`prepared` 未 `committed` 必须整组恢复旧合同，`committed` 只做幂等清理，不能凭随机 previous/replacement 文件名干扰正在提交的事务。这样即使进程被强杀且远端暂不可用，也能恢复完整旧合同，不留下“旧主图 + 新切片”或半写 canonical PNG。
|
||||
- 图集事务退役补充：九路径快照在创建和恢复读取时都使用跨平台不跟随符号链接 / reparse point 的文件句柄核算 64 MiB 总预算，marker、journal 与快照均通过有界双次读取和句柄元数据复核拒绝同长度并发改写；实际读取仍受剩余预算限制，稀疏或并发增长文件不能触发无界分配。恢复开始时锚定可信事务目录句柄，每次读取控制文件前后都复核目录身份，拒绝 rename、junction 或替换目录。恢复必须先把全部 journal 条目和九路径快照完成结构、大小与摘要校验并形成内存计划，随后缓存全部 canonical 路径的恢复前状态；每项落盘前再次校验目标与父目录，后续项失败时按逆序回滚本轮已应用项，但回滚前必须 CAS 证明目标仍等于本轮安装结果，外部修改不得被覆盖并进入 reconciliation。末尾路径竞态或快照损坏不得留下静默的新旧混合合同。`committed` 持久化后先删除并同步 `prepared`，再清理 `.previous / .replacement`、同步 canonical 合同并最后删除事务目录；递归删除中断后最多留下只有 `committed` 的可清理事务，不能重新落入 rollback 分支。
|
||||
- Tetris 连续性补充：明确俄罗斯方块任务固定分类为 `tetris-v1`，不再回退 generic 可选遥测。HTML tokenizer 只把 TAB / LF / FF / CR / SPACE 视为标签空白，并按 `type / language / nomodule` 判断 Chromium 中的可执行脚本；静态门移除字符串、注释、`template / noscript / textarea / title / style / xmp / iframe / noembed / plaintext`、带 `src` 脚本的非执行正文、非 JavaScript script、不可达匿名或命名函数、短路表达式、恒真分支的 else、顶层无条件 return / throw 后正文和 `if(false)` / 明显恒假分支诱饵，并要求有标识符边界的可达 `fall -> lock -> clear` 调用链；filter / splice 消行必须由满行判断实际控制且绑定未被局部变量或函数参数遮蔽的正式棋盘。同项目 `game/*.js / game/*.mjs` 外部脚本及本地 module 依赖图只按显式 export/import binding 传递语义，side-effect import 不暴露被导入模块的局部绑定，ASI 换行与 template `${...}` 内真实 import 仍参与依赖解析；文件按去重数量和累计 2 MiB 上限有界读取，对象属性 `import / from` 与控制块后的正则正文不得伪造依赖。浏览器状态固定含 `activePieceId / rotation / row / lockedPieces / lineClearChecks / clearedLines / occupiedCells`，同时允许 `score / nextPieceId` 等不影响固定合同的扩展 telemetry；受控试玩在 Chromium 隔离执行上下文的 Promise 闭包中保留点击前基线，MutationObserver 只冻结 trusted 输入 listener 同步产生的最后状态，CDP 点击返回后再收口该冻结值，因此后注册的同步 click listener 仍会计入，而 RAF / timer 任务不会污染因果证据。页面全局对象不能改写隔离世界证据，capture-phase、stopPropagation 与真实 window bubble 处理器均应正确验收。探针 fingerprint 必须覆盖 install、ready 与 finish 三段真实脚本。锁定、消行与 restart 的既有严格约束保持不变。旧合同或纯继续 successor 以及 game-chat 快车道在读取回执前按有效原任务重新分类、重算 fingerprint 并回读迁移结果，旧 generic 回执只能视为 stale，不能交付完成。
|
||||
- 关联：`apps/ai-game-creator-shell/scripts/start-tauri-dev.mjs`、`start-dev-stack.mjs`、`src-tauri/src/agent/runtime_protocol/autonomous_completion.rs`、`response_stream.rs`、`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`。
|
||||
|
||||
## 2026-08-03 托管 MCP 未鉴权响应提供安全接入引导
|
||||
@@ -5991,10 +6001,23 @@
|
||||
- 决策：`/api/external/v1/mcp` 缺少、格式错误或无法验证 Bearer API Key 时继续返回相同 HTTP `401`，并增加 `WWW-Authenticate: Bearer realm="genarrative-external-editor"` 与机器可读 `details.guide`。引导只说明 Bearer Header 格式、登录后在「开发者 API Key」创建密钥、原始密钥只显示一次、凭据不得进入聊天或仓库、配置后重试 `initialize`，以及公开 manifest、Skill 与 OpenAPI 地址。
|
||||
- 安全边界：三种鉴权失败不得通过 code、message、details 结构差异暴露 Key 是否存在；未鉴权响应不得包含 MCP tools、resources、owner 或内部鉴权诊断。其它 External v1 业务路由继续使用原通用 401，不继承 MCP 专用引导。
|
||||
- 关联：`server-rs/crates/api-server/src/external_api_auth.rs`、`server-rs/crates/api-server/src/modules/external_api.rs`、`docs/openapi/genarrative-external-v1.openapi.json`、`docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md`。
|
||||
|
||||
## 2026-08-03 Agent Runtime Prompt 使用版本化 Bundle
|
||||
|
||||
- 决策：把 `prompt.rs` 中依赖长自然语言精确匹配的链式 `.replace()` 拆成仓库内版本化 Prompt Bundle；`build.rs` 读取、校验并生成静态 Rust 定义编译进 Tauri 二进制，生产源码不再直接引用 `prompts/runtime` 的单个 Markdown。
|
||||
- 边界：Supervisor 的角色选择、并行委派、all-join、视觉返工、claim gate 和 repair 自然语言合同，以及 Supervisor / 六组专业 Agent 的编译期静态节点目录进入 Bundle。Bundle 不是完整可执行 graph，也不是生产 Skill；正式 DAG 依赖边、权限、安全门和完成合同继续由 Rust、`shared-contracts` 与校验后的项目协作策略掌控。
|
||||
- 一致性：manifest 是 section、组合顺序、平台 / Editor 变体、role overlay、Provider 协作 fragment 和静态节点目录的单一来源；role overlay 只接受 `rootSourceKind` 强类型语义 selector，构建期拒绝未知 kind，运行期再把权威 source 常量映射为生成的 kind，禁止在 manifest 中复制易漂移的 durable source 字符串。isolated / all-join、autonomous 首轮、首批协作修复、delivery 收敛、manifest wait、试玩后续委派，以及 Supervisor interaction / background planning / final-reply 身份合同不得在 Provider 或 `prompt.rs` 源码中复制。公共 runtime system header 保持身份中立；Supervisor 共享核心身份与最终回复专属规则拆成两个 section：background planning 的 system composition 必须复用核心身份 section，interaction / final-reply 的 system prompt 按 manifest composition 组合核心身份与最终回复两段，所有 user context 都不重复注入 Supervisor 身份合同正文。每个 section 只能属于 runtime composition、Supervisor composition、chat 字段、platform variant、visual variant、role overlay 或 Provider fragment 中一个语义所有者；唯一例外是同一 identity section 由 Supervisor planning 与 `supervisorChat.identity` 显式复用。这样同时阻断 Supervisor 指令外泄和动态 variant 与静态 composition 的重复注入。构建脚本同时监听 Bundle 每一级目录、manifest 和已登记 section，保证任意嵌套目录新增孤立 Markdown 都会触发增量构建并失败关闭；同时拒绝未知字段、非法 / 重复 / symlink 路径、未知 / 重叠 selector、节点 / alias / 生成标识符冲突，并强制 Supervisor planning composition 复用 chat identity、专业节点 taskId / group / role 与正式 seed DAG 一致。原生工具目录仍从 `agent_runtime_native_executable_tools()` 生成，`mcp.call` 不混入静态原生目录；MCP 工具只从当前请求的动态 catalog 暴露。
|
||||
|
||||
## 2026-08-03 AI 游戏生成泥点不足使用确定性中断说明
|
||||
|
||||
- 决策：钱包返回 `泥点余额不足` 或 `可消费泥点不足：...` 时，API 统一按 HTTP 409 业务冲突处理并只公开固定的“泥点余额不足”；Agent Runtime 转换为稳定原因 `mud-points-insufficient`，禁止进入瞬态 Provider 自动重试。
|
||||
- 恢复边界：泥点不足表示平台已经明确拒绝计费与生成，即使本地保留 accepted External Generation ledger，也必须标为 `failed`，不能因账本存在而进入 `needs-reconciliation`。充值后的新输入“继续”仍走现有失败 successor 合同，从原任务和当前已提交项目事实接着完成，不重放旧生成请求。
|
||||
- 展示与安全：game-chat 顶部状态、持久失败对话和 Supervisor 阶段记录统一显示“泥点余额不足，本轮游戏生成已中断。请充值后发送“继续”，系统会从当前项目进度接着完成。”；公开层不得附带 operationId、URL、项目路径、密钥或上游响应正文。第三方 `insufficient_quota`、普通 409、402 与 429 不得误分类为平台泥点不足。
|
||||
|
||||
## 2026-07-31 External v1 生成统一异步并提供托管 MCP 与完整 Skill 包
|
||||
|
||||
- 异步契约：External v1 的图片生成、图片编辑、图标图集、UI 素材提取、角色动画、视频、音效和背景音乐八类 POST 固定持久化入 `external_generation_job` 并返回 HTTP `202 + operationId/statusUrl/pollAfterMs`；不受站内 `GENARRATIVE_EXTERNAL_GENERATION_MODE=inline` 影响。每次逻辑生成必须携带稳定 `Idempotency-Key`，网络结果未知或调用方轮询超时时复用原键和原 operationId，不得换键重提。
|
||||
- 发布窗口兼容：AI 游戏创作桌面客户端严格按 HTTP 状态分流生成首响应；旧服务 `200` 只作为已经完成且含可下载媒体的同步结果消费，旧图集允许从顶层 `spritesheetImageSrc` 换签下载且无效值不得遮蔽可用 `objectKey`；新服务 `202` 必须取得 `operationId` 后轮询，轮询间隔按 OpenAPI 限制在 `250..=5000ms`，其他 2xx 失败关闭。Runtime 在 POST 前原子持久化精确请求体、请求 SHA-256 与稳定幂等键，`202` 后先原子追加 `operationId` 并回读一致再查询；重启时 `accepted` 账本只恢复 GET，`prepared` 表示提交结果未知并禁止自动 POST。生成 POST 使用独立三十五分钟等待预算且不自动重提；game-chat 仍受父 run 五分钟总截止约束，但截止时若 `canvas.asset_generate` 已进入 executing，客户端与预览照常退出，Runtime 保留 pending action、provider batch、生成账本与 `needs-reconciliation`。响应丢失、旧 `200` 结果损坏、`202` 缺 operationId、轮询超时、状态损坏、透明派生失败或外部完成后的本地提交失败统一投影为不可自动重生的对账边界。非阻断 general warning 继续消费结果并与 `sliceWarning` 分别展示。权威 External v1 OpenAPI 仍只声明新异步 `202`，不把部署过渡兼容公开成正式双协议。
|
||||
- 发布窗口兼容：AI 游戏创作桌面客户端严格按 HTTP 状态分流生成首响应；旧服务 `200` 只作为已经完成且含可下载媒体的同步结果消费，旧图集允许从顶层 `spritesheetImageSrc` 换签下载且无效值不得遮蔽可用 `objectKey`；新服务 `202` 必须取得 `operationId` 后轮询，轮询间隔按 OpenAPI 限制在 `250..=5000ms`，其他 2xx 失败关闭。Runtime 在 POST 前原子持久化精确请求体、请求 SHA-256 与稳定幂等键，`202` 后先原子追加 `operationId` 并回读一致再查询；重启时 `accepted` 账本只恢复 GET，`prepared` 表示提交结果未知并禁止自动 POST。生成 POST 使用独立三十五分钟等待预算且不自动重提；game-chat 的两次串行生成纳入父 run `4200` 秒软预算与从 root `bound_at` 起算的 `4500` 秒绝对硬截止，但截止时若 `canvas.asset_generate` 已进入 executing，客户端与预览照常退出，Runtime 保留 pending action、provider batch、生成账本与 `needs-reconciliation`。响应丢失、旧 `200` 结果损坏、`202` 缺 operationId、轮询超时、状态损坏、透明派生失败或外部完成后的本地提交失败统一投影为不可自动重生的对账边界。非阻断 general warning 继续消费结果并与 `sliceWarning` 分别展示。权威 External v1 OpenAPI 仍只声明新异步 `202`，不把部署过渡兼容公开成正式双协议。
|
||||
- 查询与结果：新增 owner-safe `GET /api/external/v1/generations/{operationId}`。`queued/running` 返回 phase/progress，`completed` 返回 compact 稳定 artifact 引用，`failed` 返回脱敏错误，跨 owner 按不存在处理。compact result 允许 objectKey、resource/asset ID、assetObjectId、尺寸、媒体类型、taskId 和告警；禁止完整 project/canvas、Data URL、Blob URL、临时 signed URL、内部 provider 原文和 lease/fencing 控制字段。
|
||||
- 客户端 durable 查询约束：私有生成账本同时绑定 base URL/API Key 配置指纹，指纹不一致不查询旧 operation。旧 `200` 兼容结果只持久恢复允许字段和安全媒体引用。operation 明确 failed 的账本保留到 pending observation 和 Provider batch 终态落盘后再清理。生成提交只有契约明确的 `400 / 401 / 403` 可判定为入队前拒绝并清理 prepared 账本；其它非成功状态一律保留账本进入对账。账本路径解析、扫描和删除逐级拒绝符号链接，非法控制路径失败关闭。
|
||||
- MCP：新增托管 `/api/external/v1/mcp`，使用现有 External API Key Bearer 鉴权和无协议 session 的 Streamable HTTP JSON direct 模式。MCP tools 从同一 OpenAPI operation 形成并复用 External REST router；生成 tool 显式要求 `idempotencyKey`，另有统一任务查询 tool。MCP resources 提供使用说明、OpenAPI、Skill 入口 `SKILL.md` 和 `references/capability-routing.md`、`references/api-operations.md`、`references/authentication-and-safety.md`、`references/requests-and-outputs.md` 四篇稳定 reference；日后新增 reference 时必须同步新增独立 resource。MCP Agent 直接调用托管 tools，不安装 CLI，也不将脚本、测试或 workflow 暴露为 MCP resources。禁止开放内部 SpacetimeDB MCP、worker procedure、controller 或队列控制面。
|
||||
@@ -6016,3 +6039,70 @@
|
||||
- local 状态：`local-*` 只是 ID 形状，不能直接解释为“素材仍在保存”。新上传 / 新生成素材是否 pending 取资源登记在途状态；严格满足兼容谓词的历史自包含本地角色动作序列是持久化终态，不得误报等待。若当前版本尚不能复制这类序列，以准确原因失败关闭；既非 pending 又不满足历史谓词的 unresolved local 图层也失败关闭，但不得承诺稍后一定自动恢复。layout PATCH pending 不参与资源登记判断，系统剪贴板图片导入不受影响。
|
||||
- schema 与迁移：在现有 `EditorCanvasLayer` 结构体末尾追加 `#[default(None::<String>)] asset_kind_override: Option<String>`，不删除、改名、重排或改类型。legacy 图层类型与资源默认相同则迁移为 `None`，不同则迁移为 override；资源无默认值时只有全部引用图层显式同值才补资源默认，否则保留各自 override；自包含历史序列的显式类型迁入 override，不伪造资源。同步 `migration.rs`、表目录 / 数据契约、生成 bindings、HTTP DTO 与结构化 canonical hash，并运行 `npm run spacetime:generate`、`npm run check:spacetime-schema`。
|
||||
- 并发边界：未登记图层被禁止复制后，不再按临时资源 ID 合并项目资源创建请求，也不再用一次响应批量改写共享临时 ID。每个合法新增图层保留自己的响应快照与回调；layout PATCH 的串行 latest-wins 队列、共享资源的多布局引用和 session 资源快照按 `resourceId` 去重继续保留，它们与资源创建 single-flight 是不同机制。
|
||||
|
||||
## 2026-08-03 Agent Runtime 原生工具合同本地失败关闭
|
||||
|
||||
- MCP 边界：动态 MCP 函数的 `arguments.input` 必须在创建 durable pending 前按当前 catalog 的原始 `inputSchema` 本地校验；native parser 负责把错误归类为可修复的 arguments-schema，统一 enrichment 覆盖 legacy 兼容解析并把错误接回同一 repair 链。实际 MCP 调用前还必须按当前 catalog schema 重验一次，阻断升级前遗留的 schema 外 durable pending。校验器关闭 HTTP 与文件解析能力，外部 `$ref`、无效 schema、required/type/enum/additionalProperties 不匹配全部失败关闭，错误不得回显参数或 schema 私密值。
|
||||
- Native Prompt：Provider 请求只描述实际广告的 `update_agent_plan`、动作函数、`respond_to_user` 和动态 MCP 函数；内部 `mcp.call` wrapper、`thinkingSummary/planUpdate` envelope、空 actions 以及无 function-tools 文本回退不再进入实时 Prompt。required-nullable 字段未使用时显式传 JSON `null`，空对象 input 只允许权威空 schema 工具。
|
||||
- Supervisor 合同：配置 External Editor API Key 时，`art-asset-plan` 的 owner 产物统一为 `assets/manifest.art.json` 与 `assets/art-spritesheet.png`；未配置 Key 时只要求 `assets/manifest.art.json`，不得伪造或要求三个 PNG。版本化 Bundle 的视觉合同和 playbook 不得给出互斥 expectedArtifacts。
|
||||
|
||||
## 2026-08-04 图集事务与 Tetris 完成门使用句柄和 AST 收口
|
||||
|
||||
- 图集事务：九文件旧合同在写 `prepared` 前必须全部持有可信源句柄并整体复读；Unix 事务控制文件统一通过锚定目录句柄的 `openat / unlinkat + O_NOFOLLOW + O_NONBLOCK` 操作，FIFO 等非普通文件必须在读取前失败关闭，恢复前态也必须在同一叶子句柄上稳定双读并复核前后元数据与当前 inode。Windows 祖先 pin 只请求读访问并拒绝 delete sharing，可重复持有；只有事务叶子句柄请求删除访问。事务捕获与恢复 CAS 从 canonical 项目根句柄逐组件打开或创建父目录，staging、no-replace link/move 与 unlink 均相对固定父目录句柄执行；清理事务证据前再次复核整组安装结果。安装后的任何清理错误都按实际 canonical 状态把当前项纳入逆序回滚，不能留下新旧混合合同。
|
||||
- 图集事务 live identity：`prepared` 后继续由同一 trusted transaction directory handle 贯穿 canonical 提交、`committed` 清理和 live rollback，不再按路径重开并接受替换目录；发布 `committed` marker 前后都必须验证 retained handle 的权威 pathname identity，Unix rename 漂移不得降级为成功 warning。清理前把权威叶子以 no-replace rename 原子隔离到 retired 名称，复核 retained inode 后清空，最终删除前再次复核；重启恢复先幂等清理已隔离目录。恢复在任何写入前冻结九项 canonical 全部前态，晚序普通文件变化必须 CAS 失败且不得被旧快照覆盖。没有 durable journal 的 legacy `.previous / .replacement` 只做锚定识别并进入 reconciliation，不自动恢复 canonical 或删除残留。
|
||||
- JavaScript / ESM：Tetris 静态连续性检查以 Oxc parser、semantic 与 AST visitor 为权威。无效语法、ASI、template interpolation、正则 / 注释、表达式体箭头、参数和词法遮蔽、export alias、import 后再 export 的 bridge、re-export 与缺失导出链接不再由字符串扫描猜测；跨模块 alias 保留 origin 根绑定名称，只按解析到 import symbol 的 reference span 改写 importer。同一 export 的多个本地 alias 按大小写敏感的 symbol identity 保序保留，同一 dependency 的多条 import declaration 合并绑定；投影在 importer 内按最终 origin 聚合，因此同一 origin 经不同 dependency 或 bridge 到达时也只生成一次根声明。组合单元为 importer 和所有 origin 根绑定分配无冲突的确定性名称，匿名 default、同源私有根名、importer 局部根名及不同 origin 都不得合并；重命名后必须重新通过 parser 与 semantic，只有最终启发式扫描文本统一小写。object shorthand 展开后保留原键；namespace 只改写绑定到 import symbol 的完整 member span，同文本属性和局部遮蔽均不得连带改写。HTML `type` 存在时优先于 legacy `language`。源码投影仍只是静态语义门，最终完成继续要求绑定当前 revision 的真实 Chromium 固定试玩回执。
|
||||
- JavaScript / ESM 声明与 namespace 补充：顶层 function/class/variable declaration 直接按 Oxc statement span 投影，禁止用首个分号或换行截断箭头函数、多行 initializer 或多 declarator；对象、数组、默认值和 rest 解构中的全部 binding 必须递归进入导出图，同一声明只投影一次。import symbol 不从 importer 自有 root binding 集合按小写文本扣除，大小写不同的合法绑定继续隔离；模块组合按依赖层数迭代到稳定闭包，使被导出函数引用的 imported dependency 继续进入最终 consumer 单元，同时限制最终 span replacement 后的单个组合单元最多 `2 MiB`、整轮投影累计处理最多 `32 MiB`，分支或循环图超限失败关闭。固定字符串 dynamic import 同样由下游实际使用的 export 反向驱动加载，未使用 export、未调用嵌套函数和恒假分支中的 source 不进入模块单元；被选声明中只有由 `await import` 解构、namespace member 或 `.then(...)` 静态解析到的 export 才投影。callback 参数、解构 alias 和 namespace member 的引用必须按 semantic symbol span 改接到投影根，禁止靠同名文本共现绕过局部遮蔽。完成全部 span replacement 后重新校验完整组合 unit，最终启发式扫描必须先按原始大小写完成 AST 解析和掩码，再归一化文本。匿名 default function / arrow 在原始 AST 中也必须以 collision-safe synthetic binding 注册可外调 root span，保证 wrapper 内 imported member 的传递依赖继续传播；synthetic binding 必须避开真实根绑定，冲突改名只更新 `default` target，不得改写用户同名命名导出。renamed re-export 的 namespace 投影同时携带 importer member 名和 origin export 名，分别用于定位 consumer span 与 origin declaration。named import、namespace import 及 namespace 解构 alias 的成员调用必须保留完整静态成员路径，并用调用 span 的恒假分支可达性过滤后再向上游传播 demand；对象 / class 的直接成员、解构 alias、实例 alias 与下游 wrapper 都遵循同一规则。对象的 method shorthand、函数表达式值、箭头函数值以及 class function-valued field 均按精确函数 span 注册成员根，不能因声明写法不同漏载其可达 dynamic dependency，也不能把同一属性内未调用的嵌套函数误当根。
|
||||
- JavaScript / ESM occurrence 与成员根补充：dynamic import demand 必须以 source 和 import occurrence position 共同隔离，同 source 的可达裸 import 不得借用不可达 occurrence 的 export；动态 namespace 保留首段 export 后的完整成员路径，声明 initializer 与后续赋值式 `await import` 都绑定 semantic symbol。named / namespace 成员作为回调参数、对象解构 alias、实例 alias 和下游 wrapper 时仍按实际调用 span 传播 demand。constructor、`new Game().method()` 与实例 alias 分别建立精确成员根，`this.method()` 只匹配同一 class / object owner。顶层声明位置直接保留 Oxc span，不得用源码文本 `find` 反查。
|
||||
- JavaScript / ESM alias 与 receiver 补充：imported member 作为参数时只允许受控的 callback API 建立执行 demand，普通日志或元数据传参不得推断为调用。普通 member alias 同时支持声明 initializer 与后续赋值，`new ns.Game()` 等完整 constructor path 必须传播到实例 alias。局部对象、class、实例、`this` 与 `super` 的方法调用统一按 semantic receiver owner 匹配，禁止再按末级方法名跨 owner 扩散到同名 decoy。
|
||||
- JavaScript / ESM 控制流身份补充：member alias、局部 receiver 与动态 namespace 的赋值必须保存 assignment position 和 enclosing function scope；函数体使用按真实 invocation position 选择当时事件，多次调用跨越赋值边界时合并可能 owner，恒假分支、未调用函数或调用之后的赋值不得覆盖更早使用点。导出的 function 与 class/object member 额外以模块初始化结束作为潜在外部调用点，使声明后生效的顶层赋值进入 demand，同时保留更早本地调用状态。动态依赖传播以原始 owner 模块 AST span 为权威，不因投影重排声明或省略独立赋值语句重算 alias。class method owner 进一步区分 static / instance，class expression 与实例化 alias 使用同一 owner 图。callback API 只接受 semantic 未解析的已知全局调度函数，以及可由 AST 证明的 literal array / dynamic import 调用；被用户定义或遮蔽的同名 `setTimeout / map / then` 不得推断执行参数。
|
||||
- JavaScript / ESM 深层可达性补充：constructor、`.call/.apply` 与受控 inline callback 建立真实 invocation；具名 function expression 不再生成遮蔽外层 binding 的重叠节点，普通 inline function / arrow 未被执行时保持不可达。受控 callback API 名大小写敏感，并以精确参数索引建立执行边：timer、microtask、RAF、Promise 与数组迭代取第一个参数，`addEventListener` 取第二个参数，delay、initial value、event type、options 和额外参数保持普通值。条件/循环赋值合并执行与跳过状态，conditional expression 合并各 owner，未知确定赋值显式 invalidation；已调用函数对外层 alias 的副作用按调用位置传播，`super` owner 固定在 class 定义点。恒假扫描先屏蔽 parser 识别的注释和 literal；恒假分支区间随单次函数可达性 analysis 预计算、排序合并并以借用二分索引查询，不再使用 thread-local 完整源码 key 或命中时 clone ranges。投影 canonical 根名避让两侧全部非 import binding，dynamic shorthand 保留原键，循环模块按相同原始声明去重，同名 dynamic export 不得拉入无引用本地声明。
|
||||
- JavaScript / ESM 构造、继承与 callable 补充：`new` 沿冻结的 class owner 图执行本类显式 constructor、显式 `super()` 或隐式 derived constructor，并支持直接 class expression；instance / static 成员未 override 时继续沿 `extends` 链查找。普通嵌套 function 不继承 class `this`，arrow 保持词法 owner。`let binding; binding = function/arrow`、本地 function alias 和 Function.prototype `.bind()` 结果都建立 callable identity；`.call/.apply/.bind` 只有在 receiver 可解析为 callable 时采用 Function.prototype 语义，业务对象同名方法仍作为普通 receiver method 执行。
|
||||
- JavaScript / ESM callable、callback 与视觉可达性补充：callable conditional expression 合并两端全部身份；声明式与后续赋值式 member `.bind()` 都冻结成员 owner。受控 callback API 穿透 callee / receiver 外层括号，Promise `.then` 取 fulfilled 与 rejected 两个 callback 槽，`.catch/.finally` 仍仅取首槽。视觉资产路径与 `drawImage` 启发式可使用 ASCII 小写副本，但 AST、semantic binding 和函数可达性只解析原始大小写 JavaScript，大小写不同的 `MainLoop/mainloop` 不得合并。Canvas 视觉门复用受 256 文件、累计源码 `2 MiB` 与投影处理 `32 MiB` 限制的 inline / external module 链接与投影结果，逐 unit 关联路径、图片变量和可达绘制；inline `type=module`、本地 `src` module 及真实可达依赖可作证据，未链接文件、恒假动态依赖、未调用函数、跨 unit 拼接与纯 HTML 路径诱饵均失败关闭。
|
||||
- 浏览器因果：状态证据仍只冻结 trusted input listener 及其点击派生微任务内的变化；完整手势身份改由宿主在成功完成 Chromium 元素鼠标输入后调用隔离世界 finish。更早注册的 `window` capture listener 即使调用 `stopImmediatePropagation()` 也不能阻断探针自身的完成身份，页面脚本不能伪造 host finish，RAF / timer 继续不计入动作结果。
|
||||
- 验证边界：Linux 定向回归覆盖目录相对读写与清理、祖先 symlink、CAS 安装后错误、九文件混合快照、Tetris AST 反例和七项真实 Chrome generic 试玩。Windows cfg 代码必须继续在真实 Windows CI / 发布构建验证；本地缺少 MinGW C compiler 时，安装了 Rust target 也不能把交叉 `cargo check` 失败误报为源码失败。
|
||||
- JavaScript / ESM 循环与体积补充：投影声明按 `(origin module, original root binding)` 保存身份，canonical 重命名不能改写原始身份；删除回流声明后仍把 import 引用改接到 importer 已有 canonical，并给固定点保留“模块数 + 1”轮的产出与稳定确认预算，未收敛时失败关闭。inline module 先按浏览器可执行标签提取原文并计入与外部脚本共享的累计 `2 MiB` 源码预算，再做语法和语义校验；无效超限模块不能被 helper 静默过滤，无效小模块也明确失败关闭。
|
||||
- JavaScript / ESM alias 求值顺序补充：receiver alias 保存赋值完成时刻并在该时刻解析 source owner，后续 source 重赋值不得倒灌。调用事件按内层参数 / RHS 先于外层调用 / assignment 生效；`switch case/default` 赋值一律保留跳过与各分支可能状态，普通函数内无条件 `return / throw` 截断之后的 alias 副作用。恒真 / 恒假关键字大小写敏感，可能被局部或参数遮蔽的 `undefined` 不再作为文本恒假值。
|
||||
- JavaScript / ESM callee 与终止顺序补充：identifier callee 和 `new C(args)` 的 constructor / instance owner 在实参前冻结，invocation effect 保留在实参之后；callable assignment 到 RHS 完成后才生效，`start = start()` 继续调用旧值。`return / throw` 表达式中的 assignment / call 先执行，截断点取表达式之后的 AST statement end；函数体使用 Oxc body span，不从默认参数或解构参数中的首个 `{` 猜测。未知 guard clause 后续与 `catch` 体一律按 conditional effect 合并旧状态。
|
||||
- JavaScript callable 分支与参数快照补充：conditional expression 必须在 test 求值完成后，分别于 consequent / alternate 自身起点冻结 callable identity；受控 callback 参数按该参数自身起点解析，前置参数产生的 alias 副作用先于后续 callback identity 生效，callback 的执行边仍保留在注册调用完成位置。
|
||||
- JavaScript / ESM live binding 投影补充：被选 export root 的直接顶层 assignment 及其 RHS 依赖必须与原声明共同投影，覆盖 `export let x; x = impl`、导出对象成员安装和 class prototype 安装；assignment target 以 semantic root symbol 归属，函数体写入、嵌套控制流和无关 root 写入不得因同名文本进入投影。共享 declaration 的写入按原始源码位置合并，继续参与 canonical 重命名、循环去重和既有 `2 MiB / 32 MiB` 门禁；全部依赖声明必须先于延后的初始化写入输出，不能因 projection traversal 产生 TDZ。
|
||||
- JavaScript callee 短路、构造与 Promise 链补充：sequence callee 保留前序求值副作用并只调用末项，logical expression 及 `||= / &&= / ??=` 按已知 callable 真值 / nullish 状态短路，未知状态才保留可运行分支。`new` 支持 assignment / conditional callee，并让未被 class 静态业务成员或函数对象 own override 覆盖的 `.bind()` 结果继续指向原 class construct target。`delete` 对 `.call/.apply/.bind` 的括号包装不改变 own-property identity，删除后恢复 Function.prototype intrinsic。dynamic import Promise 的连续 `.then/.catch/.finally` 任意深度都建立 callback 边，但参数槽固定为 `then=[0,1]`、`catch/finally=[0]`，额外参数不得升级为执行 demand。
|
||||
- JavaScript callback 时序、内建覆盖与 class expression owner 补充：受控异步 callback 的注册位置只建立可达调用边，闭包读取的外层 alias 状态选取注册所在同步作用域收尾点，不能冻结在注册点；函数体写副作用仍不得同步提交到注册调用末尾。数组字面量上的已知迭代 callback 继续按同步执行传播外层 alias 变化。函数对象自有 `.call / .apply / .bind` assignment 按函数对象身份形成成员 callable 状态，普通函数别名共享同一对象覆盖，`.bind()` 结果保持独立对象身份；存在覆盖时禁止回退到 Function.prototype 语义。`new (class { ... })` 赋给局部变量时冻结 class expression 的 instance owner，使后续实例方法调用保持可达。
|
||||
- JavaScript / ESM assignment root 与直接动态 namespace 补充：被选 export 的顶层 live-binding function / arrow assignment、对象成员安装和 class prototype 安装同时成为对应 root / member 的 projected reachability root，class static 与 instance assignment 不得串线；`(await import('./dep.mjs')).run()` 及等价静态 computed member 直接记录 occurrence-scoped `run` export demand，恒假分支、未调用函数与其它既有可达性边界继续生效。
|
||||
|
||||
## 2026-08-04 静态视觉门脚本与 ESM 求值顺序
|
||||
|
||||
- HTML 输入只在非 raw-text 区域屏蔽真正的 `<!-- -->` 注释；`script / style` 等 raw-text 原文保持逐字不变，再交给各自 parser / semantic 处理。禁止在整份 HTML 上按文本删除 `//` 或 `/* */`，否则字符串中的 `https://`、路径和注释形状会被破坏；HTML 注释内的标签、脚本和素材路径仍不得形成视觉证据。
|
||||
- classic script 分析单元把 inline 与无 `defer / async` 的本地 external 正文按 `game/index.html` 标签顺序交错组成 parser-blocking 段，再把 classic external `defer` 按文档顺序放到解析完成后的 deferred 段；不得把 defer-before-inline 误投影为外链先执行。classic external `async` 的下载完成顺序不可静态证明，当前静态门直接失败关闭。带 `src` 标签的 inline body 继续忽略；外部文件仍执行可信普通文件、`game/` 边界、文件数与累计体积门禁，重复标签按浏览器出现次数保留求值位置。
|
||||
- Canvas 尺寸、可见性、元素绑定和 stylesheet 选择器扫描只消费浏览器可渲染标记；`template / textarea / noscript / title / style / xmp / iframe / noembed / plaintext` 内的 Canvas、标签和样式诱饵全部跳过。活动顶层 stylesheet 与可见标记分开提取，既允许真实 CSS 参与隐藏/尺寸判断，也不把 CSS raw-text 中的伪标签当作 DOM。
|
||||
- ESM 组合单元按 dependency 初始化先于 importer 顶层求值排列。import reference 的 span replacement 仍基于原 importer 完成，随后把已闭包的 dependency projection 放在 importer 前并对最终单元重跑 parser、semantic、单元 `2 MiB` 与累计投影 `32 MiB` 门禁；循环模块继续按 `(origin module, original root binding)` canonical identity 去重并要求有界固定点收敛。
|
||||
## 2026-08-04 JavaScript 延迟状态与复合调用边
|
||||
|
||||
- 受控异步 callback 的 alias 读取按完整 enclosing invocation 链延迟到各层函数同步收尾，最外层再延迟到当前 job 末尾；callback 写入仍不在注册点同步提交。conditional / assignment expression callee 分别在 test / RHS 求值后建立调用边，`new` 同时执行普通 function constructor 及 alias。
|
||||
- 函数对象自有 `.call / .apply / .bind` 覆盖允许以普通对象静态 member callable 作为 RHS，并继续按函数对象身份跨普通 alias 共享。`delete` 自有覆盖后恢复 Function.prototype intrinsic；条件删除合并覆盖与 intrinsic，非 callable 自有值仍视为属性存在并禁止 intrinsic 回退。
|
||||
- callable 运算结果只把普通 `=` 与实际执行分支的 `||= / &&= / ??=` 视为可调用值来源，算术、位运算和移位复合赋值不得直接采用 RHS callable。logical callee 对 boolean / numeric / string / null 字面量先执行真实短路；sequence receiver 的末项保持函数对象身份，用于 `.call / .apply / .bind` own override 与 `delete`。Promise callback 只接受固定 dynamic import、未遮蔽原生 `Promise` 构造 / 静态方法及可证明变量、alias 和连续链，业务 thenable、未知返回值和遮蔽 `Promise` 保持普通成员调用。直接 `new (Fn.bind(...))()` 在 intrinsic bind 仍可能时继承普通 function `Fn` 的 construct target，确定 own override 时不回退。
|
||||
|
||||
- ESM 最终绑定与 occurrence 补充：外部 callable root 只认模块初始化完成时同一 live binding / member 的最后一次直接顶层 assignment，旧 RHS 不得加载；直接 awaited namespace member 在赋值、受控 callback、constructor 和深层静态 member path 中仍按 `(source, occurrence)` 传播并替换首段 export。assignment class expression 的 static / instance member demand 分离。
|
||||
- ESM 初始化与阻塞补充：projection declaration 保持原模块源码顺序，dependency origin 保持 importer 声明顺序；循环 canonical 去重同时删除声明和对应初始化写入。side-effect static import 只联结按 dependency-before-importer 排列的直接 `globalThis / window` 顶层 effect，不暴露 dependency local binding；静态可判定永不完成的 top-level await 至少对未遮蔽全局 `await new Promise(() => {})` 失败关闭，嵌套函数同形 decoy 和可完成 await 保持允许。
|
||||
|
||||
## 2026-08-04 ESM 解构写入与模块完成性收口
|
||||
|
||||
- side-effect static import 若读取 dependency-local declaration，组合投影必须把该声明及其 semantic 依赖按原源码位置放在 effect 前；同一声明也被 importer 使用时按 origin declaration identity 去重并统一做 collision-safe canonical 重命名，既不泄露无关 local，也不引入 TDZ 或重复声明。
|
||||
- exported live binding 的顶层 object / array destructuring assignment 纳入 projection；最终一次写入中与目标 root 对应的属性或槽位 callable 才作为 dynamic demand root，更早写入和相邻 decoy 不得回流。
|
||||
- 未遮蔽全局 top-level `await new Promise(executor)` 的 executor 若不调用或传递 resolve / reject、也不显式 throw，则返回值不参与 Promise settle，静态门按不完成失败关闭；resolver 按 semantic symbol 识别，Promise 遮蔽与嵌套函数内 await decoy 继续保留。
|
||||
- dynamic import `.then` callback 的对象解构只建立 occurrence-scoped binding，不再仅因读取 export 属性就形成 callable demand；只有该 binding 的可达引用或调用才向 export 内部传播动态依赖，未使用和恒假引用保持关闭。
|
||||
|
||||
## 2026-08-04 静态视觉证据绑定与只读 namespace
|
||||
|
||||
- classic HTML script 组合在每个 Script Record 之间保留硬语句边界，parser-blocking 与 defer 各自保持浏览器顺序，禁止因 ASI 把相邻标签拼成一个表达式。
|
||||
- Canvas 视觉门使用 Oxc AST 和 semantic symbol 关联可见 DOM Canvas、实际 context、精确 `drawImage` member callee、图片 binding 及绘制位置的 `.src` 状态。fakeDrawImage、离屏或隐藏首选 Canvas、恒假 / 未调用 / 绘制后覆盖均不作证；未知条件保持失败关闭。
|
||||
- dynamic import namespace member 写入保持真实只读失败语义，视觉投影不得把写 target 改造成可变本地；可达写入的 RHS 与后续语句不提供视觉证据，纯 namespace read 继续传播 export demand。
|
||||
- 身份与 telemetry 扫描只消费可渲染文本、可执行 inline JavaScript 和已链接外部 unit，排除 inert/raw-text、HTML 注释、带 `src` body 与非 JavaScript script。资产路径比较保持大小写，Linux 文件身份不得经 ASCII 小写副本合并。
|
||||
- 关联：`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion.rs`、`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`。
|
||||
|
||||
## 2026-08-04 静态视觉状态流与可见证据收口
|
||||
|
||||
- Canvas、2D context 与图片变量统一按 semantic symbol 记录声明和整体赋值事件；重新指向离屏 Canvas、无效 context 或新图片时立即失效旧视觉身份，只有绘制点可证明的当前状态才作证。
|
||||
- 同一 Program、函数体或普通 block 内，无条件 `return / throw` 之后的语句统一进入不可达区间；ESM dependency 的直接顶层 `throw` 作为初始化副作用排在 importer 前并阻断后续 importer 视觉证据，嵌套函数或恒假分支中的 throw 不扩大阻断范围。
|
||||
- telemetry 只扫描可见 DOM 文本和 AST 可达的 JavaScript：hidden DOM、字符串/注释、恒假分支、未调用函数和 inert/raw-text 内容不得补齐状态字段；已链接 classic/module 单元沿同一可达扫描口径判定。玩法 identity 保留独立的现有识别口径，不能反向补齐 telemetry。
|
||||
- CSS `url(...)` 的资产路径保持原始大小写解析，stylesheet 证据必须同时命中实际可见元素；未命中 selector、元素自身或祖先 hidden、以及匹配隐藏规则的节点均不作证。
|
||||
- 关联：`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion.rs`、`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`。
|
||||
|
||||
@@ -81,11 +81,13 @@ cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml real_
|
||||
|
||||
修改 game-chat release flavor 后，至少执行壳配置门禁、AppSurface game-chat 定向测试、前端类型检查、AppData / 诊断日志 / release flavor 相关 Rust 定向测试、`npm run check:encoding` 和 `git diff --check`。打包 smoke 必须确认：安装信息和产物版本为 `0.1.1`；无参数启动直接进入且只能停留在 game-chat 页面；停止或断开 `api-server` 后本地工作台仍能打开；普通 dev / release 与 debug game-chat 仍走原认证入口；独立 AppData 生效。预览 smoke 应先让当前 run 成功验证 revision N，确认 Tauri registry 启动一个 server 且 iframe 自动出现；在 validate 后、start 取得锁前推进项目 revision，必须确认原子 `expectedRevision` 门禁拒绝启动且授权保留等待新证据；再验证 revision N+1，确认 server 进程和 loopback origin 不变、iframe 显示新版本且响应为 `no-store`。same-run steer 还要覆盖旧验证不消费新授权、旧异步 attempt 不清新 generation；Runner registry 单独 running、失败 / 相同 / 更低 revision 均不能触发用户预览或重复刷新，停止后顶部显示“预览未启动”。独立包退出时必须通过 `runner.shutdown_for_client_exit` 先进入 draining 再结束本 boot，保留 durable sidecar 供下次 reconciliation，不把中断任务写成 completed；Windows Runner 必须 `CREATE_SUSPENDED -> AssignProcessToJobObject -> ResumeThread`，分配或恢复失败时 kill + wait，客户端持有 kill-on-close Job 兜底，关闭主窗口后 Runner、MCP、command、ConPTY 及其后代都应消失。普通 dev / release 和 CLI 继续使用 `runner.shutdown_if_idle`。
|
||||
|
||||
game-chat 迭代还必须确认以下行为：Supervisor ready 输出、`art-director / code-prototype / preview-readiness / preview-playtest` 四个专业 Agent 的 durable `final-reply`，以及 Rust 明确生成 `eventId + publicText` 的每条公开 Runtime 输出都作为独立 assistant 消息逐条固化在项目聊天；`art-asset-plan` 不进入进度、阶段记录或 final-reply 投影。消息通过顶层 `messageId` 幂等追加，事件 / 轮询 / hydration 重放不重复。前端禁止从原始 `summary / detail`、tool plan、Provider / Runner 元数据、命令输出或路径自行拼接持久消息；UI 把一个父 Run 统一显示为“本轮生成进度”，最新状态也不得暴露内部“第 N 轮”，完整 GUI / CLI 任务图可显示 `x/14`，首版快车道显示 `x/4`，终态不保留运行中进度卡；可信 `project-supervisor-game-chat` 一轮完成 `preview-playtest` 后直接收束，不请求下一次 Provider tool-plan；所有调度入口（包括 `agent.schedule_ready`、`task.list` 结果驱动的直接 `agent.delegate`）均不得暴露或启动 `publish-strategy` / `publish-package`。game-chat 必须配置可用的 External Editor API，由 `art-director` 通过一次平台 `images/generations` 生成并登记 `assets/art-spec.png`，`code-prototype` 必须把它显著用于用户可见的主要背景、玩家和目标；未配置 API 或缺少任一环节都必须失败关闭。普通 GUI / CLI autonomous 继续正式透明 `assets/art-spritesheet.png` 的完整 DAG。对应定向测试至少包括：
|
||||
game-chat 迭代还必须确认以下行为：Supervisor ready 输出、`design-director / art-director / art-asset-plan / code-director / code-prototype / preview-readiness / preview-playtest` 七个专业 Agent 的 durable `final-reply`，以及 Rust 明确生成 `eventId + publicText` 的每条公开 Runtime 输出都作为独立 assistant 消息逐条固化在项目聊天。消息通过顶层 `messageId` 幂等追加，事件 / 轮询 / hydration 重放不重复。前端禁止从原始 `summary / detail`、tool plan、Provider / Runner 元数据、命令输出或路径自行拼接持久消息；UI 把一个父 Run 统一显示为“本轮生成进度”，最新状态也不得暴露内部“第 N 轮”，完整 GUI / CLI 任务图可显示 `x/14`，首版快车道显示 `x/7`，终态不保留运行中进度卡；可信 `project-supervisor-game-chat` 一轮完成 `preview-playtest` 后直接收束，不请求下一次 Provider tool-plan；所有调度入口均不得暴露或启动 `publish-strategy` / `publish-package`。game-chat 必须配置可用的 External Editor API，按 `art-spec.png -> icon-spritesheet -> art-spritesheet.png + iconImageSrcs 本地切片 -> code-prototype Canvas 使用四类切片` 推进；缺少任一环节都必须失败关闭。
|
||||
|
||||
game-chat 首版快车道采用独立四阶段口径：只显示 `art-director`、`code-prototype`、`preview-readiness`、`preview-playtest` 的 `x/4`，不把完整 DAG 或内部 loop 计入分母。父 Run 与全部 child Run 共用 240 秒软预算和 300 秒累计硬上限；首版最多一次 Provider 规划 / 写入请求，软预算后只能运行确定性的本地 fallback、`game.static_smoke`、`preview.validate`，硬上限内未通过完成门必须失败，证据在上限后到齐也不得写 `single_round_converged`。live10 实测正式透明 `icon-spritesheet` 后处理超过 300 秒，因此 game-chat 改为一次平台 `images/generations` 生成并登记 `assets/art-spec.png`；fallback 只有该图片有效登记且真实存在时才允许生成，并必须把它显著绘制为主要背景、玩家和目标。未配置 External Editor API、图片生成失败、缺少 Canvas / manifest 登记、文件、HTML 引用或用户可见绘制时必须在 300 秒内失败关闭，绝不误报 completed。普通 GUI / CLI 继续正式透明 `assets/art-spritesheet.png` 的完整 DAG。对应定向测试至少包括：
|
||||
game-chat 素材完整快车道采用七任务口径。父 Run 与全部 child Run 共用 4200 秒软预算和 4500 秒累计硬上限；先确定性生成并登记 `art-spec.png`，再由 `art-asset-plan` 通过专用 icon-spritesheet 路由生成透明 `art-spritesheet.png`，下载并持久化响应中的独立切片，最后才允许 code-prototype 写入或局部修复入口。软预算后只允许使用已登记图集、当前 resourceId 对应切片清单的确定性本地 fallback、`game.static_smoke` 和 `preview.validate`；不得退回普通生图、猜测 atlas 网格或纯代码核心画面。完成门要求活动 Canvas 分别绘制 player、blocks-and-targets、obstacles-and-scene、feedback-effects 四类不同切片；整图 `<img>`、CSS background、完整图集直绘、单个猜测裁切和路径诱饵均失败。对应定向测试至少包括：
|
||||
|
||||
game-chat GUI 恢复还要覆盖两类竞态：root Runtime 先终态、manifest 四阶段后终态时，必须等到四任务最终状态后仅持久化一条 `【Supervisor 阶段记录】`；页面初始 hydration 直接读到真实终态时也要补写缺失记录，但不得把 `idle` 当作完成。同时，GUI 启动的 `agent.resume` 自动扫描必须先做只读恢复工作预检：新项目或无 task / retry / handoff / finalization / pending / reconciliation 工作的已终态项目不弹确认，存在任何 durable recovery artifact 则仍必须命中 `agent.resume` policy。
|
||||
失败续跑还必须覆盖同 Session 同 source 继承、跨 Session / 跨 source 不继承、首次与连续 successor 的 effective task / contract / scheduler 一致性，以及中英文纯继续短语使用同一识别函数。非占位入口的新 `code-prototype` 必须先产生本人 mutation 再 smoke；连续只读 smoke 不得收束。占位 fallback 只允许显式支持的真实玩法模板，俄罗斯方块必须验证棋盘、下落、旋转、锁定和消行语义，未知玩法必须失败关闭。
|
||||
|
||||
game-chat GUI 恢复还要覆盖两类竞态：root Runtime 先终态、manifest 七任务 lane 后终态时，必须等到七个首版任务最终状态后仅持久化一条 `【Supervisor 阶段记录】`；页面初始 hydration 直接读到真实终态时也要补写缺失记录，但不得把 `idle` 当作完成。同时，GUI 启动的 `agent.resume` 自动扫描必须先做只读恢复工作预检：新项目或无 task / retry / handoff / finalization / pending / reconciliation 工作的已终态项目不弹确认，存在任何 durable recovery artifact 则仍必须命中 `agent.resume` policy。
|
||||
|
||||
```bash
|
||||
npm run test -- apps/ai-game-creator-shell/tests/agentRuntimeModel.test.ts --run
|
||||
|
||||
@@ -4048,6 +4048,14 @@
|
||||
- 验证：`external_editor_api.rs` 的 openapi 断言只校验 schema 形状，不校验兼容性，通过不等于契约安全；判定 breaking 与否以「删字段、移出 required、收窄类型、改语义、新增必填」为准。
|
||||
- 关联：`docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md`、`docs/openapi/genarrative-external-v1.openapi.json`、`server-rs/crates/api-server/src/external_editor_api.rs`、`server-rs/crates/api-server/src/modules/external_api.rs`。
|
||||
|
||||
## “继续”不能成为新游戏主题或触发首版整文件覆盖（2026-08-03）
|
||||
|
||||
- 现象：原根 run 已经写出并验证目标玩法，但父 Runtime 因预算、上下文或 Provider 失败；用户在同一项目输入“继续”后，页面标题变成“继续”，玩法被默认收集/点击模板替换，美术规范总览图被直接铺进游戏画面。
|
||||
- 原因：终态失败 run 不能 steer，提交层因此创建 task 只有继续短语的新 root；每个新 autonomous 根合同又无条件 reset seed manifest；game-chat fallback 从当前 root task 取主题并直接 `file.write game/index.html`。同时快车道把 `icon-spec` 误当运行素材，要求整图背景和象限裁剪实体。通用 smoke/generic playtest 只验证结构与最小交互，无法发现玩法目标已经漂移。
|
||||
- 处理：严格继续意图必须在同一 Supervisor Session、同一持久 source 内继承最近失败根 run 的原始目标和 baseline，但保持新的 run/Provider/sidecar 身份；纯继续词表只能有一个权威实现，中英文短语都走同一入口，真正新需求仍独立 reset。非占位入口禁止 fallback 整体覆盖，也不能反复运行只读 smoke；当前 `code-prototype` 必须先读取并实际 patch，取得本人 mutation 后才能验证和交付。占位 fallback 只支持具备真实语义的显式模板，俄罗斯方块必须实际实现棋盘、下落、旋转、锁定和消行，未知玩法失败关闭。`art-spec.png` 只作规范参考，核心运行时位图必须来自独立派生的透明 `art-spritesheet.png` 及其 `iconImageSrcs` 本地切片；切片清单绑定当前图集 resourceId，Canvas 分别使用玩家、目标、场景和反馈四类素材。不得猜测图集是 2×2 等分、把规范板塞进画面或以纯代码核心实体绕过派生素材。
|
||||
- 验证：覆盖失败根任务“水晶俄罗斯方块”后输入“继续”、连续 successor、跨 Session、跨 source、正常完成后新输入、带具体新需求、既有非占位入口先 patch 后 smoke、初始化占位的俄罗斯方块真实语义、未知玩法失败关闭、纯继续目标缺失、规范图不在运行 DOM/Canvas、真实动作前后 `sequence` 与 RAF 空转。浏览器验收必须同时比较 baseline 玩法关键文本/控件/状态和当前 revision，不能只看 Canvas 非空与三个固定按钮。
|
||||
- 关联：`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/game_chat_fast_path.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/provider_request_builders.rs`。
|
||||
|
||||
## Tauri beforeDevCommand 失败不等于已启动客户端会自动退出（2026-08-03）
|
||||
|
||||
- 现象：旧 worktree 的 AGC Vite 长期占用 `127.0.0.1:3080`，marker 仍指向旧 API；新 worktree 启动 game-chat 后，配套后端在新端口 ready，随后 `beforeDevCommand` 因代理 target 不匹配返回非零，终端已经回到提示符，但原生客户端和它启动的 Runner 仍存活。客户端 WebView 实际加载旧 Vite，因此当前 master 的界面优化看起来全部缺失。
|
||||
@@ -4068,7 +4076,7 @@
|
||||
|
||||
- 现象：生成提交发生客户端超时、连接中断或响应丢失后，调用方创建新的 `Idempotency-Key` 再提交一次；原任务其实已经入队，最终造成重复生成、重复扣费和重复画布 / 素材库写入。
|
||||
- 原因：把“客户端没有收到结果”误判为“服务端没有受理”，又没有持久保留逻辑请求的幂等键和服务端返回的 `operationId`。托管 MCP 若绕过 External REST router 直接调用 worker 或 SpacetimeDB，也会形成第二套去重与状态语义。
|
||||
- 处理：一次逻辑生成只分配一个稳定幂等键。桌面 Runtime 在 POST 前先把精确请求体、SHA-256 和幂等键原子写入私有生成账本并回读一致；收到 `202 + operationId` 后先把账本升级为 `accepted` 再轮询。重启时 `accepted` 只恢复 GET，`prepared`、响应丢失、`202` 缺 operationId、轮询超时和状态损坏都进入 `needs-reconciliation`，绝不自动 POST。game-chat 五分钟硬截止可以结束本轮、关闭预览和客户端，但 executing 的 `canvas.asset_generate` 必须保留 pending action、provider batch 与生成账本；旧 `200` 图集的 `spritesheetResource` 允许为空，此时只在顶层 `spritesheetImageSrc` 是有效下载引用时优先使用，否则回退可用 `objectKey`。`postprocess-failed-source-preserved` 进入不可自动重生的对账边界；其它 non-blocking warning 继续消费成功结果并单独展示。旧 `200` 兼容不改变权威 External v1 的异步契约。MCP 生成工具必须把 `idempotencyKey` 映射到同一 REST header，并复用同一 External router、owner 和任务账本。
|
||||
- 处理：一次逻辑生成只分配一个稳定幂等键。桌面 Runtime 在 POST 前先把精确请求体、SHA-256 和幂等键原子写入私有生成账本并回读一致；收到 `202 + operationId` 后先把账本升级为 `accepted` 再轮询。重启时 `accepted` 只恢复 GET，`prepared`、响应丢失、`202` 缺 operationId、轮询超时和状态损坏都进入 `needs-reconciliation`，绝不自动 POST。game-chat 的 4500 秒硬截止可以结束本轮、关闭预览和客户端，但 executing 的 `canvas.asset_generate` 必须保留 pending action、provider batch 与生成账本；旧 `200` 图集的 `spritesheetResource` 允许为空，此时只在顶层 `spritesheetImageSrc` 是有效下载引用时优先使用，否则回退可用 `objectKey`。`postprocess-failed-source-preserved` 进入不可自动重生的对账边界；其它 non-blocking warning 继续消费成功结果并单独展示。旧 `200` 兼容不改变权威 External v1 的异步契约。MCP 生成工具必须把 `idempotencyKey` 映射到同一 REST header，并复用同一 External router、owner 和任务账本。
|
||||
- 补充：不能把“accepted 分支里没有生成 POST”误当成 GET-only 恢复。若读取账本前仍重做项目/素材目录准备、输出路径预检或请求正文构造，恢复仍可能创建远端资源或在查询 operation 前失败。恢复必须直接使用 durable snapshot；清理必须最后删除 pending 身份锚点，活动 orphan 不得自动删除。完整恢复 future 还要在默认 Tokio worker 栈下验证，不能靠测试环境调大 `RUST_MIN_STACK` 掩盖栈溢出。
|
||||
- 加固：durable snapshot 必须绑定不含明文凭据的 base URL/API Key 配置指纹，配置漂移时连 GET 也必须阻断。accepted operation 明确 failed 也不能在 observation 持久化前删账本。旧 `200` durable result 只保留允许字段与安全 objectKey/相对路径，签名 URL、query/fragment 和未知字段不落盘。提交只有契约明确的 `400 / 401 / 403` 可证明未入队并清理 prepared 账本；超时、冲突、限流、网关错误及其它意外状态均保留账本进入对账。账本根目录、扫描和删除必须通过受控路径解析逐级拒绝符号链接，不能让项目内链接把清理目标指向项目外。
|
||||
- 验证：覆盖“服务端已入队但提交响应丢失”后原键重试仍返回同一 operation、换 owner 不可见、查询最终只出现一份 completed result 和一次计费 / 写回；MCP 与 REST 对同一 owner、同一请求和同一键必须命中同一 operation。
|
||||
@@ -4106,3 +4114,17 @@
|
||||
- 原因：测试触发了与断言无关的账户读取，较快环境中请求会在用例结束前失败，较慢 CI 中请求延迟到组件和 jsdom 均已销毁后才收束。仅用 revision 丢弃旧请求而不在卸载时推进 revision，最后一个在途请求仍会被误认作当前请求。
|
||||
- 处理：调用方在未认证时不得启动受保护的钱包刷新；可取消的读取要为每轮分配 `AbortController`，新读取先失效并中止旧读取，组件卸载时同时推进 revision、abort 当前请求并清空句柄。所有 `then / catch / finally` 在更新状态前都要检查 signal 与 revision。
|
||||
- 验证：定向测试覆盖卸载后请求 signal 已中止；同时复跑触发钱包刷新回调的画布生成集成测试和完整前端测试，不能以单文件偶然快速收束代替全量验证。
|
||||
|
||||
## 不要用自然语言精确 `.replace()` 维护 Runtime Prompt
|
||||
|
||||
- 现象：Prompt 文案稍作改写、增删空格或调整段落后，替换静默失效，代码中出现难以审阅的链式 `.replace()`。
|
||||
- 原因：把自然语言全文同时当内容和结构锚点，没有稳定 section 身份。
|
||||
- 处理：稳定片段拆为版本化 Bundle section，由 Rust 显式按角色、平台和配置组合；`agent_runtime_native_executable_tools()` 是原生可执行工具的权威源列表，同时供 Prompt 工具目录与 native capability registry 使用，`mcp.call` 只服从当前请求的动态 MCP catalog。最终 Provider 请求构建器同样必须使用显式 section 与条件组合，不能以后置自然语言精确 `.replace()` 注入工具合同、平台规则或角色规则。安全规则保留在代码中。
|
||||
- 验证：manifest 覆盖所有嵌入资源、版本一致、源列表中的原生工具全部进入 Prompt 与 native capability registry、`mcp.call` 不进入静态目录、Supervisor section 顺序和关键角色合同保持不变，并扫描 `prompt.rs` 与最终 Provider 请求构建器不再出现自然语言链式 `.replace()`；对最终 Provider 请求直接断言各角色、平台和配置分支的合同内容。
|
||||
|
||||
## 动态 MCP 函数参数不能只依赖 Provider schema
|
||||
|
||||
- 现象：动态 MCP 函数虽然带 catalog `inputSchema`，Runtime 却只检查 `arguments.input` 是 object；非 strict 或兼容 Provider 可以返回缺 required、类型错误、enum 外值或 schema 外隐藏字段，并把它们原样送到外部工具。
|
||||
- 风险：Provider 工具约束不是本地安全边界；特别是 `writes + readOnlyHint=true` 自动放行的工具，schema 外字段可能改变外部副作用而不进入预期确认路径。
|
||||
- 处理：使用完整 JSON Schema validator 校验原始 catalog schema，不手写 required/type 子集；native parser、fingerprint enrichment 与实际 MCP 调用边界复用同一校验器。enrichment 错误必须映射回 classified `arguments-schema` repair，不能以普通字符串直接终止 run；执行点重验用于阻断升级前已经落盘的 schema 外 pending。关闭网络和文件 `$ref` 解析，schema 无法安全编译时不广告或不执行。`serde` 类型错误会包含实际字符串值，catalog miss 也会包含模型提交的 server/tool，因此这两类错误同样只能返回稳定类别，不能拼接原始错误、参数值或 schema 内容。
|
||||
- 验证：覆盖 required、additionalProperties、type、enum、本地 `$defs/$ref`、HTTP/file 外部引用、无效 schema、错误脱敏，证明 legacy wrapper 在注入 fingerprint 前进入 repair，并证明带旧有效 fingerprint 的历史 pending 在实际调用前仍被 schema 拒绝。
|
||||
|
||||
File diff suppressed because one or more lines are too long
Reference in New Issue
Block a user