Merge remote-tracking branch 'origin/master' into fix/multi-select

# Conflicts: # docs/project-memory/shared-memory/decision-log.md
2026-07-31 16:18:47 +08:00
parent 59759360b7 48f9c8e690
commit 1297ac192e
677 changed files with 413609 additions and 5097 deletions
@@ -9,6 +9,7 @@
 3. [server-rs 与 SpacetimeDB 数据契约](./【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md)
 4. [平台入口与玩法链路](./【玩法创作】平台入口与玩法链路-2026-05-15.md)
 5. [本地开发验证与生产运维](./【开发运维】本地开发验证与生产运维-2026-05-15.md)
+6. [AI 游戏创作项目开发工作台 PRD](./prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md)

 团队长期约定、决策、流程和排障摘要统一从 [项目记忆入口](./project-memory/README.md) 读取。代码、当前融合文档与项目记忆冲突时，以代码和最新融合文档为准。

@@ -1761,7 +1761,8 @@
        "type": "object",
        "required": [
          "viewport",
-          "layers"
+          "layers",
+          "expectedRevision"
        ],
        "properties": {
          "viewport": {
@@ -1778,7 +1779,7 @@
          "expectedRevision": {
            "type": "integer",
            "minimum": 0,
-            "description": "可选的画布 revision CAS；不匹配时返回 409。"
+            "description": "必填的画布 revision CAS；不匹配时返回 409。"
          }
        },
        "additionalProperties": false
@@ -2561,6 +2562,21 @@
            ],
            "description": "纯色抠像背景色。可传画布支持的纯色背景 hex（如 #CFEFFF）指定；传 \"auto\"、null 或省略则由服务端自动决策。"
          },
+          "style": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "examples": [
+              "none",
+              "pixelArt"
+            ],
+            "description": "可选生成后处理风格，当前识别 none 与 pixelArt。省略、null、空字符串或 none 按无风格处理；pixelArt 仅支持普通图片（kind 省略）和 character。未知字符串或不支持该风格的 kind 按 none 继续生成并返回 unsupported-image-style 告警；非字符串值返回 400。"
+          },
          "size": {
            "type": "string",
            "description": "兼容旧 size 入参；未传 aspectRatio/imageSize 时生效。",
@@ -2585,7 +2601,7 @@
              "ui-design",
              "publication-material"
            ],
-            "default": "spec"
+            "description": "省略时生成普通图片；其它值选择对应的专用生成流程。"
          },
          "model": {
            "type": "string",
@@ -2950,6 +2966,7 @@
          },
          "iconDescriptions": {
            "type": "array",
+            "description": "图标生成需求文本数组，供 prompt 组装使用；数组长度不控制自动切片数量。画布前端把完整用户提示词作为唯一数组元素提交；其它调用方可继续提交 1 到 100 条非空文本。",
            "minItems": 1,
            "maxItems": 100,
            "items": {
@@ -2963,6 +2980,21 @@
            ],
            "description": "纯色抠像背景色。可传画布支持的纯色背景 hex（如 #CFEFFF）指定；传 \"auto\"、null 或省略则由服务端自动决策。"
          },
+          "style": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "examples": [
+              "none",
+              "pixelArt"
+            ],
+            "description": "可选生成后处理风格，当前识别 none 与 pixelArt。省略、null、空字符串或 none 按无风格处理；pixelArt 启用图标图集像素规整。未知字符串按 none 继续生成并返回 unsupported-image-style 告警；非字符串值返回 400。"
+          },
          "model": {
            "type": "string",
            "default": "gemini-3.1-flash-image-preview"
@@ -3158,7 +3190,7 @@
        "properties": {
          "code": {
            "type": "string",
-            "description": "自动拆分未完成的稳定原因码。"
+            "description": "自动拆分未完成的稳定原因码，包括原始连通域超限、局部候选拥挤、输出切片超限、处理超时、未识别到素材或切片持久化失败。"
          },
          "reason": {
            "type": "string",
@@ -3176,8 +3208,13 @@
        "properties": {
          "code": {
            "type": "string",
-            "const": "postprocess-failed-source-preserved",
-            "description": "透明背景处理最终失败并保留 provider 原图时的稳定原因码。"
+            "enum": [
+              "postprocess-failed-source-preserved",
+              "dimension-restore-fallback",
+              "unsupported-image-style",
+              "multiple-generation-warnings"
+            ],
+            "description": "生成成功但后处理发生非阻断降级时的稳定原因码。"
          },
          "reason": {
            "type": "string",
@@ -3212,7 +3249,7 @@
          },
          "iconImageSrcs": {
            "type": "array",
-            "description": "按图集 alpha 连通域拆分并持久化的独立素材列表。",
+            "description": "识别图集中全部有效 alpha 连通域并持久化的独立素材列表，按视觉阅读顺序命名为“素材 N”；数量由图集内容决定，不由 iconDescriptions 数量决定。自动生成与手动拆分图集使用相同识别规则。",
            "items": {
              "$ref": "#/components/schemas/EditorIconSpritesheetIconResult"
            }
@@ -3226,7 +3263,7 @@
                "type": "null"
              }
            ],
-            "description": "图集已成功持久化，但自动拆分未完成时返回；此时 iconImageSrcs 为空，调用方仍应使用整张图集。与通用 warning 互斥。"
+            "description": "可信透明图集已成功持久化，但全连通域自动拆分未完成时返回；此时 iconImageSrcs 为空，调用方仍应使用整张图集。原始连通域、输出数量或 CPU 预算超限不会产生切片 PUT、资源或画布切片。透明处理、Alpha/尺寸恢复、provider 原图修复性回读或透明图完整解码失败时走 provider 原图 source-only，sliceWarning 为 null。"
          },
          "prompt": {
            "type": "string"
@@ -3290,14 +3327,8 @@
                "type": "null"
              }
            ],
-            "description": "透明背景处理最终失败、provider 原图作为主结果时返回的非阻断告警。与 sliceWarning 互斥。"
+            "description": "生成成功但风格归一化、尺寸恢复、透明背景处理、Alpha 回贴、provider 原图修复性回读、透明图完整解码或像素规整发生非阻断降级时返回。source-only 降级只返回 provider 原图且不会进入拆分；其它通用告警可以与 sliceWarning 并存。"
          }
-        },
-        "not": {
-          "required": [
-            "warning",
-            "sliceWarning"
-          ]
        }
      },
      "EditorCharacterAnimationGenerationRequest": {
@@ -0,0 +1,392 @@
+# AI 游戏创作项目开发工作台 PRD
+
+更新时间：`2026-07-28`
+
+## 1. 产品定位
+
+项目开发工作台是 AI 游戏创作独立客户端中承接“做游戏”后的唯一项目级工作区，不是单独的新页面，也不新建第二套项目、资产、Agent 或预览系统。
+
+工作台固定由四个区域组成：
+
+1. 左侧平台导航。
+2. 中央主视窗。
+3. 右侧 Project Supervisor 对话与确认区。
+4. 底部专业 Agent 状态栏。
+
+中央主视窗在“资源管理”和“运行测试”之间切换。正式预览始终在客户端当前窗口内展开，只允许载入当前项目启动的 `127.0.0.1:<port>` 本地 HTTP 预览，不调用系统外部浏览器。
+
+## 2. 创作工具平台接入声明
+
+- 工作台模式：对话式 Project Supervisor 项目工作台，属于 Agent 原生创作例外。
+- 例外原因：该工作台负责跨策划、美术、程序、数值、音频和发布专业组的持续协作，结构化表单不能覆盖多轮项目开发与确认恢复。
+- 复用边界：图片、音频、上传、素材库、画板和外部生成继续复用现有平台能力，不在工作台内新建平行资产系统。
+- 创作链路：做游戏入口 -> 本地项目工作台 -> 资源/运行迭代 -> 导出或后续发布链路。
+- 业务真相：项目 manifest、Agent Runtime、持久对话、本地预览状态和后端计费投影；前端只保存短生命周期展示态。
+- 当前切片不新增玩法 `playId`、公开作品 read model、发布路由或 SpacetimeDB schema。
+
+## 3. 已确认产品决策
+
+### 3.1 预览与窗口
+
+- 游戏预览直接在当前客户端窗口内展开。
+- 客户端仅交付横屏，默认与最小窗口均为 `1280×800`。
+- 右侧 Supervisor 和底部 Agent 状态栏常驻；窗口不得缩小到破坏该结构。
+- 浏览器窄屏样式只作为开发兼容，不属于本版本产品合同。
+
+### 3.2 版本与资源替换
+
+- 可运行版本不可变。
+- 替换版本引用资源时创建下一迭代版本，不原地修改既有版本。
+- 新版本必须记录 `parentVersionId`、替换前后资源身份和创建原因。
+- 当前运行中的版本不消费尚未生成的新版本变更。
+
+### 3.3 资源布局
+
+- “按依赖”和“按类型”分别保存画布位置。
+- 切换布局模式后恢复该模式最后一次用户手动拖动结果。
+- 新资源首次进入某个布局时才执行默认不重叠排版；已有坐标不得被自动排序覆盖。
+- 依赖布局使用资源生成/引用关系；类型布局按资源大类、子类型、尺寸规格排序。
+- 不同资源分区不可互相拖入。
+
+### 3.4 数值微调
+
+- 数值修改立即写入当前项目的编辑态配置。
+- 当前已拉起的体验预览和测试切片不热更新；必须重新拉起后才能消费新值。
+- 自然语言新增数值项只能映射到预定义参数注册表，不允许生成或修改代码。
+
+### 3.5 专业 Agent
+
+现有六个专业组为：
+
+| group | 普通用户名称 | 当前职责 |
+| --- | --- | --- |
+| `design` | 策划组 | 玩法规格、界面原型、规则与验收口径 |
+| `art` | 美术组 | 角色、场景、UI、动画和美术素材 |
+| `code` | 程序组 | 可运行原型、模块实现和工程验证 |
+| `balance` | 数值组 | 速度、生命、得分和难度参数 |
+| `audio` | 音频组 | 背景音乐、音效和音频资源 |
+| `publishing` | 发布组 | 质量评审、试玩、打包和发布准备 |
+
+- 底栏默认突出策划、美术、程序三组。
+- 允许在同一底栏展开数值、音频、发布组，不删除既有专业组。
+- 状态、当前任务和完成进度来自真实 manifest/Runtime。
+- 泥点消耗必须来自后端计费归因投影；无数据时显示“未统计”，不得用前端估算。
+
+### 3.6 审批与扩展能力
+
+- 默认档位为严格审批。
+- P0 只有严格审批是有效运行合同。
+- 高风险审批依赖未确定的 Rank 算法，作为低优先级待解决事项。
+- 无需审批只有在 Runtime、计费、副作用、sandbox 和 reconciliation 均支持对应策略后才能开放。
+- 未开放选项使用“视觉不可用但可点击说明原因”，不使用无法触发说明的原生 `disabled`。
+- 普通用户暂不开放 Agent.md 编辑和自定义 Skill 安装；后续必须先定义来源审核、版本、权限、沙箱和回滚合同。
+
+## 4. 工作台状态机
+
+### 4.1 主视窗
+
+```text
+resources
+  -> run（存在 runnableVersion 且 loopback preview 可启动）
+
+run.playing
+  -> run.paused（用户暂停或切片结束）
+  -> resources（先暂停当前预览表现，再切换视图）
+
+run.paused
+  -> run.playing（继续当前切片）
+  -> run.relaunching（数值或版本编辑态发生变化）
+  -> resources
+```
+
+运行入口不可用时仍允许点击，显示“当前无可运行版本”，但不切换状态。
+
+### 4.2 测试切片
+
+```text
+idle -> starting -> playing -> paused -> completed
+                     |          |
+                     +-> failed +-> playing
+
+completed -> starting(nextSlice)
+```
+
+- 单个切片完成后自动进入 `paused`。
+- 上一项/下一项会停止当前切片并启动目标切片。
+- 数值编辑态变化后，当前切片标记 `stale`；重新拉起前不消费新值。
+
+### 4.3 资源聚焦
+
+```text
+idle -> focused(document|art|audio|version) -> idle
+```
+
+- 文档：在中央画布展开并独立滚动。
+- 美术/音频：进入对应媒体聚焦状态，工具能力复用现有编辑器。
+- 版本：高亮版本引用资源；替换动作只创建下一迭代版本。
+
+### 4.4 历史成果与当前状态
+
+- “当前工作状态”只展示当前 Supervisor run 下的专业 Runtime。
+- “项目已有成果”按项目持久保存，不随 Supervisor run 切换而清空。
+- Agent 文本成果只认可带合法 `agent-finalization-<32 lower hex>` messageId 的 assistant 消息。
+- 新 run 失败、待确认或未完成时继续展示最近一次成功成果；新的成功 finalization 才替换同 Agent 的旧成果。
+- 文本回执不得冒充图片、音频、项目文件或 manifest asset。
+
+## 5. 数据合同
+
+以下合同先冻结字段语义；P0 只实现标注为 P0 的部分。
+
+### 5.1 工作台视图状态（P0）
+
+```ts
+type ProjectWorkbenchViewState = {
+  schemaVersion: 'game-creator-workbench-view.v1';
+  projectId: string;
+  mode: 'resources' | 'run';
+  approvalMode: 'strict' | 'risk' | 'none';
+  expandedAgentGroups: Array<'balance' | 'audio' | 'publishing'>;
+};
+```
+
+P0 中 `approvalMode` 只能有效写入 `strict`；其它值只能作为不可用选项展示。
+
+### 5.2 资源画布布局（P1）
+
+实现状态（2026-07-28）：本节布局合同已在独立客户端落地，dependency / type 双模式通过项目内 CAS sidecar 独立持久化；关系线、资源替换、缩放 / 平移等其余 P1 能力仍按本文非目标保持未实现。
+
+```ts
+type ProjectResourceCanvasLayout = {
+  schemaVersion: 'game-creator-resource-layout.v1';
+  projectId: string;
+  mode: 'dependency' | 'type';
+  revision: number;
+  positions: Array<{
+    resourceId: string;
+    section: 'document' | 'version' | 'art' | 'audio';
+    x: number;
+    y: number;
+    manuallyPlaced: boolean;
+  }>;
+  updatedAt: number;
+};
+```
+
+两个 mode 是两份独立坐标集合；独立客户端的本地项目持久层以 `projectId + mode` 做 CAS 更新。
+
+#### 5.2.1 字段语义
+
+- `x / y` 是相对所属 `section` 内容原点的 CSS 像素坐标，落盘前四舍五入为非负整数；坐标不使用 viewport、页面或资源详情浮层坐标系。
+- `updatedAt` 是持久层生成的 Unix 毫秒时间戳，前端不得自行覆盖。
+- `revision` 从 `0` 开始；布局文件不存在时读取接口合成 `revision=0 / positions=[]`，首次成功写入返回 `revision=1`，后续每次成功 CAS 写入递增 `1`。JSON / Tauri / TypeScript 全链路合法范围固定为 `0..=9_007_199_254_740_991`（`Number.MAX_SAFE_INTEGER`），读取、返回或提交负数、小数、非有限值与超限整数都必须失败关闭。
+- 新资源第一次进入某个 mode 时由默认布局写入 `manuallyPlaced=false`；用户完成一次有效拖动后写为 `true`。
+- 同一份布局中 `resourceId` 必须唯一。持久层允许暂时存在当前资源投影中没有的旧 ID，因为 Agent 文本成果等资源可能晚于 manifest 恢复；前端协调后必须在下一次成功写入中清除已确认失效的坐标。
+- 单份布局最多保存 `4096` 个位置，序列化文件不得超过 `2 MiB`；`resourceId` 最多 `512` 个 Unicode 字符，`x / y` 取值范围固定为 `0..=1_000_000`。
+
+#### 5.2.2 本地存储与业务边界
+
+独立客户端把两份布局保存为项目内 UI sidecar：
+
+```text
+.agent/workbench/resource-layouts/
+├─ dependency.json
+└─ type.json
+```
+
+- 文件名必须与 payload 的 `mode` 一致；payload 的 `projectId` 必须与当前 `.agent/manifest.json` 一致。
+- 布局只属于工作台 UI 状态，不写入 manifest，不增加游戏项目 mutation revision，不使 Runtime verification 失效，不触发权限确认，也不作为 Agent 产物、资产或 Git 提交依据。
+- 写入复用项目安全路径解析、普通文件 / 链接校验和原子 JSON sidecar 安装能力；使用资源布局专用系统文件锁串行化 read-check-write，不用前端进程内互斥替代跨窗口锁，也不长期占用 Agent Runtime 的项目 mutation 锁。`.layout.lock` 是持久锁入口，Unix 互斥跟随 `flock` 文件描述符，Windows 互斥跟随不共享的文件句柄；进程退出由操作系统释放，应用不得按 mtime、PID 文本或其它 stale 启发式删除锁文件。
+- 主文件损坏、schema 不支持、身份不匹配、文件超限或安全文件检查失败时必须失败关闭，不得把默认空布局覆盖到原文件。若原子安装留下可验证的恢复副本，读取时可按既有 sidecar 恢复规则恢复后再返回。
+- 本切片不把布局同步到 `api-server`、SpacetimeDB、云端账号或其它设备。
+
+#### 5.2.3 Tauri 命令合同
+
+```ts
+type ReadProjectResourceCanvasLayoutInput = {
+  projectPath: string;
+  mode: 'dependency' | 'type';
+};
+
+type UpdateProjectResourceCanvasLayoutInput = {
+  projectPath: string;
+  expectedProjectId: string;
+  mode: 'dependency' | 'type';
+  expectedRevision: number;
+  positions: ProjectResourceCanvasLayout['positions'];
+};
+
+type UpdateProjectResourceCanvasLayoutResult =
+  | {
+      status: 'updated';
+      layout: ProjectResourceCanvasLayout;
+    }
+  | {
+      status: 'conflict';
+      layout: ProjectResourceCanvasLayout;
+    };
+```
+
+- 读取命令固定为 `read_local_project_resource_canvas_layout`，返回当前 mode 的完整布局；文件不存在时返回合成的 revision `0` 布局，不为只读操作创建目录或文件。
+- 更新命令固定为 `update_local_project_resource_canvas_layout`。调用方只提交当前已读取布局的 `expectedProjectId` 身份栅栏，不提交 `projectId / revision / updatedAt` 的权威新值；Tauri 必须先只读确认项目存在、manifest 有效且 projectId 与栅栏一致，随后获取系统锁并在锁内复核 `projectId`、重新读取当前布局，再生成新的 revision 与时间戳。路径被其它窗口重建为新项目时，旧窗口必须在任何布局副作用前失败。不存在目录、普通非项目目录或损坏 manifest 均不得先创建 `.agent/workbench`、锁文件或布局文件。
+- `expectedRevision` 与锁内 revision 相同才允许原子写入并返回 `updated`；不同时不得写文件，返回 `conflict` 和锁内最新完整布局。前端不得通过解析错误字符串识别 CAS 冲突。
+- Rust 内部 revision 使用 `u64`，但 JSON / Tauri 合同统一限制为 `0..=9_007_199_254_740_991`，每次成功必须严格递增；持久值或 `expectedRevision` 超限时必须拒绝，当前值达到上限时失败关闭并保持原文件字节不变，不得把超出 JavaScript 安全整数范围的值返回前端或用于 CAS。
+- 项目无效、布局损坏、字段校验失败和文件系统错误继续作为安全、可理解的 Tauri command error 返回；错误不得包含配置、凭据或项目外绝对路径。
+
+#### 5.2.4 前端布局与协调合同
+
+- 资源卡改用 Pointer Events 驱动二维拖动；超过统一移动阈值后才进入拖动态，普通点击仍打开唯一资源详情浮层，`pointercancel` 恢复拖动前位置。
+- 资源只能在原 `section` 内拖动。不同 section 之间既不能通过指针拖入，也不能通过持久 payload 改变当前资源的前端分类事实。
+- dependency 默认布局按 `dependencyDepth` 形成横向层级，同层资源纵向寻找第一个不重叠位置；type 默认布局固定按“资源子类型 -> 媒体类型 -> 名称 -> 资源 ID”稳定排序，在分区内从左到右、从上到下寻找第一个空位。布局模型的 `subtype` 必填：manifest 资产使用 `asset.kind`，任务产物、导入附件与 Agent 文本成果分别使用稳定的 `task-artifact`、`attachment`、`agent-result`，不得以缺失值或显示文案兜底；资源协调签名必须包含 subtype。卡片尺寸、间距和拖动阈值必须由单一前端布局模型常量维护。
+- 资源集合变化时保留全部仍存在的坐标，只为新 ID 计算默认位置，并删除已确认失效的旧 ID；无论 `manuallyPlaced` 为何，已经写入的现存坐标都不得因重新排序、模式切换或新增资源被自动改写。
+- 搜索或筛选只隐藏卡片，不删除、压缩或重排其坐标；清空搜索后恢复原位置。
+- 窗口尺寸变化只改变可视范围和分区滚动边界，不回写、裁切或缩放持久坐标。当前客户端继续以 `1280×800` 横屏合同验收。
+- 打开项目、切换 mode 或当前 mode 首次出现新资源时执行“读取 -> 协调 -> 必要时 CAS 写入”；项目或 mode 已切换后返回的旧异步结果必须丢弃。
+- 同一 `projectPath + projectId + mode` 的首次读取与资源集合协调必须分开：资源集合变化不得取消已经发出的读取或保存。同一 scope 内全部手动拖动和资源自动协调写入使用同一 FIFO，任一时刻最多一个 CAS 在途，后一笔必须使用前一笔成功返回的 revision，不能用“最后请求获胜”跳过中间 CAS。切换项目或 mode 后，旧 scope 的在途请求不能阻塞新 scope 队列；前端放弃旧请求槽位并丢弃其迟到响应，后端继续依靠 `expectedProjectId + expectedRevision + 系统锁` 仲裁已发出的请求。
+- 某笔 CAS 在途期间，同一 scope 内对相同 `resourceId + section` 重复产生但尚未发送的拖动意图必须折叠为最后坐标；已经在途的请求不得取消，不同资源的顺序不得跨越。队列增长必须受当前资源与分区数量约束，不能随连续 pointer 事件无界累积。
+- 用户拖动结束后先乐观更新，再立即提交一次 CAS。成功后以返回布局更新 revision；普通写入失败时恢复最近可信持久布局并提示“布局保存失败，已恢复上次布局”。
+- CAS 冲突时直接载入返回的最新布局并提示“布局已在其他窗口更新，请重新拖动”，丢弃所有基于冲突前快照排队的手动拖动，不得自动重放本地旧坐标或静默覆盖另一窗口结果。即使当前在途请求是允许自动重试的资源协调，只要本次冲突实际清除了任何排队手动拖动，也必须按当前 scope 保留重新拖动提示；后续资源协调成功、失败或通用提示定时器都不得静默清除，只有新的手动布局成功保存或切换 scope 才能解除。资源自动协调可以基于冲突返回的新 revision 有界重试，单次资源签名最多追加 `2` 次，持续跨窗口写入时不得无限自旋。
+- 缺少 Tauri bridge 的浏览器开发态可以保留当前会话内布局用于界面测试，但不得宣称已经持久保存。
+
+### 5.3 资源类型与替换兼容性（P1）
+
+```ts
+type ProjectResourceDescriptor = {
+  resourceId: string;
+  category: 'document' | 'version' | 'art' | 'audio';
+  subtype: string;
+  width?: number;
+  height?: number;
+  durationMs?: number;
+  format: string;
+};
+
+type ProjectVersionResourceReplacement = {
+  sourceVersionId: string;
+  sourceResourceId: string;
+  replacementResourceId: string;
+  compatibility: {
+    categoryEqual: boolean;
+    subtypeEqual: boolean;
+    sizeSpecEqual: boolean;
+  };
+};
+```
+
+三项兼容性必须同时为 true 才能创建下一版本。
+
+### 5.4 游戏迭代版本（P1）
+
+```ts
+type GameIterationVersion = {
+  versionId: string;
+  parentVersionId: string | null;
+  projectRevision: number;
+  resourceBindings: Array<{ slotId: string; resourceId: string }>;
+  parameterSnapshotId: string;
+  createdReason: 'initial' | 'resource-replacement' | 'agent-revision';
+  createdAt: number;
+};
+```
+
+版本写入后不可修改。
+
+### 5.5 测试切片与数值参数（P2）
+
+```ts
+type GameTestSlice = {
+  sliceId: string;
+  versionId: string;
+  title: string;
+  order: number;
+  startCondition: string;
+  endCondition: string;
+  status: 'idle' | 'starting' | 'playing' | 'paused' | 'completed' | 'failed';
+};
+
+type GameTunableParameterDefinition = {
+  parameterId: string;
+  label: string;
+  valueType: 'integer' | 'number' | 'boolean' | 'enum';
+  min?: number;
+  max?: number;
+  step?: number;
+  enumValues?: string[];
+  writePath: string;
+  codeMutationAllowed: false;
+};
+```
+
+参数写入立即增加编辑态 revision；当前 preview/slice 保持旧 revision，并显示“需要重新拉起”。
+
+### 5.6 Agent 泥点归因（P2）
+
+```ts
+type ProjectAgentMudPointAttribution = {
+  projectId: string;
+  agentGroup: 'design' | 'art' | 'code' | 'balance' | 'audio' | 'publishing';
+  chargedMudPoints: number;
+  refundedMudPoints: number;
+  netMudPoints: number;
+  asOf: number;
+};
+```
+
+该投影只能由后端账本聚合产生。
+
+## 6. 分阶段范围
+
+### P0：当前实施切片
+
+- 复用现有四区工作台壳。
+- 资源/运行切换与客户端内 loopback 预览。
+- 只读资源画布、文档展开、美术/音频聚焦入口。
+- Supervisor 正式会话、上传、Runtime 确认与安全错误。
+- 当前 run 专业状态与项目历史成果分离。
+- 默认三专业组，并可展开另外三组。
+- 严格审批有效；风险/无需审批可点击查看未开放原因。
+- 橙色低保真视觉与 `1280×800` 横屏边界。
+
+### P1
+
+- 先实施依赖/类型两套坐标持久化、首次默认不重叠布局、跨重启恢复与 CAS 冲突处理。
+- 资源关系线在布局持久化验收通过后单独实施，不与本切片捆绑伪造完成。
+- 版本资源高亮、兼容性判断和不可变下一迭代版本。
+- 美术/音频编辑状态接线。
+
+### P2
+
+- 测试切片正式协议与恢复。
+- 参数注册表、立即写编辑态和预览重新拉起。
+- 泥点归因 read model。
+- Agent.md/Skill 安全合同。
+- 高风险审批 Rank 与无需审批运行合同。
+
+## 7. 验收
+
+### 7.1 P0 验收
+
+1. `1280×800` 下页面无横向或纵向溢出，输入框与 Agent Dock 始终可见。
+2. 运行入口不可用时点击给出原因；可用时只在客户端内打开 loopback 预览。
+3. 当前 Supervisor run 变化后，旧成功 Agent 文本成果仍可查看；普通失败 assistant 不进入资源区。
+4. 底栏默认显示策划、美术、程序，可展开数值、音频、发布；状态与任务来自真实 Runtime/manifest。
+5. 风险审批和无需审批不能改变运行策略，点击后明确提示尚未开放；严格审批继续使用现有 Runtime 门禁。
+6. 不显示伪造泥点、伪造资源完成度、伪造图片或外部浏览器成功提示。
+
+### 7.2 P1 资源画布布局持久化验收
+
+1. 同一项目在 dependency 与 type mode 分别拖动资源后，关闭并重启客户端，两种 mode 都恢复各自最后一次成功保存的位置。
+2. 新资源进入任一 mode 时获得不重叠默认位置，现存资源坐标保持逐项不变；删除资源后，下一次成功写入不再包含已确认失效的 ID。
+3. 资源不能跨 document、version、art、audio 分区；点击、搜索、筛选和资源详情浮层行为不因二维拖动回归。
+4. 两个窗口基于同一 revision 写入时最多一个成功；失败方收到 `conflict` 与最新完整布局，界面不静默覆盖成功方结果。
+5. 布局文件缺失的旧项目可以无迁移打开；损坏、未知 schema、身份冲突、超限和链接文件失败关闭，且原文件不被空布局覆盖。
+6. 布局读写不改变 manifest、游戏项目 mutation revision、Runtime verification、Agent 权限与预览状态。
+7. `1280×800` 最小横屏下全部资源可通过分区滚动访问，不出现页面级横向或纵向溢出，右侧对话和底部 Agent 状态栏保持可见。
+
+## 8. 非目标
+
+- 资源画布布局持久化切片不实现资源关系线、资源替换、不可变迭代版本、画板编辑状态、测试切片、数值参数或泥点归因。
+- 本切片不保存资源详情浮层位置、画布缩放 / 平移、搜索条件、筛选条件或当前 mode；这些状态如需持久化必须另行扩展合同，不能塞入 `game-creator-resource-layout.v1`。
+- 不修改 SpacetimeDB schema。
+- 不开放普通用户 Agent.md/Skill。
+- 不自动确认 Agent 动作，不自动触发可能扣费的生成。
+- 不把当前项目工作台推广为其它玩法的默认创作模式。
@@ -0,0 +1,48 @@
+# Agent Swarm 纯聊天验证入口计划
+
+更新时间：`2026-07-14`
+
+## 目标
+
+提供一版不依赖正常客户端 GUI 的终端聊天入口，让开发者选择一个父 Agent，通过真实 Agent Runtime 验证静态委派、动态隔离子 Agent、并行执行、确认动作、回执汇总和多轮持久化。
+
+## 范围
+
+- 新增 `--swarm-chat [--init] <本地项目绝对路径> [parentAgentId]`，省略时默认进入 `project-supervisor`。
+- 新增总控短命令 `npm run agc:chat -- --config-dir <项目外 AppData 绝对路径> [--init] <project>`；保留 `agc:swarm` 显式父 Agent 调试入口。
+- 普通输入进入父 Agent background Runtime；不使用一次性 `--agent-chat`。
+- 复用 External Runner、active Session、现有 conversation、Agent 私有记忆、项目黑板、`agent.delegate`、`agent.spawn_isolated`、terminal receipt 和 all-join。
+- 展示全部 Agent 的状态、事件、父子身份和委派关系，并支持在终端批准或拒绝待确认动作。
+- 提供 `/help`、`/agents`、`/status`、`/history`、`/quit`。
+
+## 非目标
+
+- 不新增 Tauri 窗口、浏览器页面或本地 HTTP / SSE bridge。
+- 不新增 Provider 调用路径、Agent 数据库或 conversation 格式。
+- 不伪造 token streaming；首版展示 Runtime 状态 / 事件流和最终回复。
+- 不在终端退出时取消 Runner、run 或 Runner-owned process session。
+
+## 实现步骤
+
+1. 扩展 CLI command、参数解析和项目外 `--config-dir` 门禁。
+2. 新增独立终端 REPL 模块，复用项目初始化、Runtime resume、任务投递和 conversation 读取。
+3. 轮询全 Agent Runtime，按身份去重输出状态和事件；待确认时走现有 confirm / reject。
+4. 用“全 Runtime 非活跃 + 全队列为空 + 稳定观察窗口”判断一轮收束，再读取父 Agent 当前 Session 的新增 assistant 消息。
+5. 增加 npm 短命令、确定性测试、真实启动 smoke 和文档同步。
+
+## 验收清单
+
+- CLI parse、绝对路径、项目初始化、`--config-dir`、空输入、EOF 和 slash command。
+- 同一父 Agent 连续两轮使用同一 Session，退出重进后历史可见。
+- 两个静态 Agent 并行委派，多个动态 child 并行并形成唯一 all-join。
+- approve / reject 均能在终端完成，拒绝后父 Agent 能继续修正计划。
+- 父 Agent 暂时 idle、child 仍运行或 receipt 尚未认领时不提前结束。
+- Runner 或终端重启后恢复同一 run / session，不重放副作用。
+- 真实 Provider transcript 与 task / event / Agent DB / receipt / conversation 一致，最终父回复唯一且无密钥泄漏。
+
+## 当前进度
+
+- 已完成终端入口、短命令、Runtime 状态 / 事件输出、approve / reject、active Session 历史、same-run steer、活跃 `/quit`、启动 / 收束恢复扫描和 Runner 失联阻断。
+- 已用真实 `gpt-5.5` 观察到两个静态 Agent 并行、两条 child result、receipt 排队与重启恢复；终端确认、拒绝和活跃退出均生效。同一父 Session 连续 4 轮固定回复及 8 条消息历史恢复通过，最终双安静窗口收束返回 `FOURTH_OK`。
+- 未通过父 Agent 最终汇总：全量 `agent.run_status` 输出截断导致第一轮预算耗尽；第二轮 receipt continuation 未恢复原始只读目标并请求文件写入，已拒绝。
+- 待办：修复定向状态查询或 receipt continuation 目标恢复，复验唯一最终父回复；再补动态 isolated child 并行、唯一 all-join 和 Runner 强杀恢复。
@@ -45,12 +45,264 @@ hermes
 npm install
 ```

+仓库当前不使用 npm workspaces，根目录 `npm install` 是统一安装入口。子包新增运行时依赖时，必须同步写入根 `package.json` 和根 `package-lock.json`；不能只修改子包 `package.json`。
+
 完整联调开发环境：

 ```bash
 npm run dev
 ```

+AI 游戏创作独立客户端常用短命令：
+
+```bash
+npm run agc
+```
+
+需要构建只能打开“游戏运行 + 聊天”页面的独立 release 包时使用：
+
+```bash
+npm run agc:build:game-chat-release
+```
+
+该命令启用 Rust `game-chat-release` feature，并配合编译期前端入口锁定生成独立 NSIS 包。当前专用 release 版本为 `0.1.1`；产物的 `productName` 为 `Genarrative Game Chat`，`identifier` 为 `world.genarrative.ai-game-creator.game-chat`，安装身份和 AppData 不与普通 AI 游戏创作客户端混用。独立包直接渲染本地 `GameChatReleaseApp`，绕过平台 `AuthenticatedClient`，进入本地项目工作台不依赖 `api-server`；普通 `npm run agc`、`npm run agc:dev`、debug game-chat 和 `npm run agc:build` 继续走既有认证入口与配置。
+
+game-chat 的用户可见 preview 必须由 Tauri 客户端 `PreviewRegistry` 持有。External Runner 和 Tauri 的 registry、server 句柄与 running 状态是进程内资源，不得互相推断或把 Runner 验证用 server 直接交给 iframe。当前 accepted Supervisor 父 run 下真实 `preview-playtest` scheduler child 首次给出结构化成功证据、且其 revision 精确等于项目当前 revision 后，客户端才消费一次性授权并启动一个 Tauri preview server，随后自动显示 iframe；`preview.start` 必须携带 `expectedRevision`，Tauri 在取得项目写锁后再次原子比对。same-run steer 授权必须记录授权前 revision / validation cursor 和唯一 generation ID，旧证据、旧 policy await 或旧 start 返回均不能清除新授权。同一 run 的更高 validated revision 只刷新原 iframe，不能重复 `preview.start` 或新增 server，相同 / 更低 revision 不刷新；同 revision 的最新失败证据必须关闭该 revision 的可玩判定。preview HTTP 的 HTML、脚本、样式、资源和错误响应都必须返回 `Cache-Control: no-store`。没有 Tauri 用户预览时，顶部状态必须显示“预览未启动”，不能只写“未启动”。
+
+`generic-v1` 的真实试玩必须从 `ready` 且正整数 level 开始；start 推进到 `playing` 后，必须先持续观察 2 秒并取得至少 8 个实际样本，期间保持 `playing`，以确认玩家获得正常操作机会；随后点击唯一可见、启用且真实可交互的 `data-playtest-id="primary-action"`，由该控件触发真实主要玩法操作，并以 sequence 相对点击前严格推进证明操作已被接受。操作被接受前进入 `won | lost` 代表玩家没有获得正常操作机会，必须失败；操作被接受后的单次 `lost` 是合法结局，但不能成为所有受控尝试的唯一结果。若主要操作后仍为 `playing`，则继续观察 3 秒并取得至少 12 个实际样本；`won` 可提前证明非失败推进。之后 restart 必须推进 sequence、恢复到 `ready | playing`，并持续观察 3 秒、取得至少 12 个实际样本；若首轮结果为 `lost`，重开稳定后必须再执行一次必要的 start、2 秒 / 8 样本操作机会和真实 primary-action，第二次必须进入或保持 `playing`（再观察 3 秒 / 12 样本且不得转为 `lost`）或进入 `won`。两次受控尝试都固定 `lost` 代表无法正常推进的恶性 bug，必须失败。各观察窗口内 sequence 不得回退，restart 窗口只能保持 `ready | playing`。样本数和观察时长必须同时满足，窗口末端必须强制再读取一次有效状态，不能靠前段样本数提前通过。selector、时长、样本门槛、终态边界、非失败推进、窗口末端覆盖、required assertions 和 sequence 规则都属于 scenario fingerprint。旧 fingerprint 回执在读取和 plan liveness 检查时按 stale missing 处理，让同一 run 可重新 `preview.validate`；身份、digest、路径或内容完整性篡改仍失败关闭，最终完成门仍须现场重算当前 fingerprint 并严格拒绝旧证据。
+
+进度展示只把结构化 `preview.validate` 的 `passed=true && playtestPassed=true` 认作试玩通过，不从 `summary` 的 `：ok` 推断结论。`image.inspect status=ok` 只表示工具成功；`passed=null` 或缺少结构化布尔结论时显示中性“截图分析完成”，不得显示绿色通过。
+
+真实 Chrome 回归必须用同一前缀同时覆盖尚未接受 `primary-action` 就瞬时进入 `lost` 的 FAIL、两次受控尝试都固定 `lost` 的 FAIL，以及首轮合法 `lost` 后重开并在第二轮证明非失败推进的 PASS：
+
+```bash
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml real_chrome_generic_playtest_ --features game-chat-release -- --ignored --nocapture --test-threads=1
+```
+
+修改 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`。
+
+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 可继续。
+
+Provider 失败回归必须同时检查等待态和耗尽态：用本地 mock 503 证明 Runtime 从 durable retry record 显示精确 HTTP 状态、真实 `nextAttempt/maxRetries` 和退避秒数；最后一次重试仍失败时，状态卡与持久 conversation 只显示安全中文摘要。测试正文应包含诱饵 Provider URL/query、API Key 和 Windows / Unix 绝对路径，并断言这些正文、内部 fingerprint / chars 与 `[redacted ...]` 占位符均未进入用户可见消息；不能只验证状态卡而漏掉 `SupervisorChatOnlyView` 直接渲染的 conversation。
+
+Windows 安装包还必须覆盖 AppData 与诊断失败路径：新建目录的 owner 必须等于进程 `TokenUser` SID 且 DACL 仅允许当前用户；历史 foreign-owner 目录应先拒绝任何 reparse / junction / symlink，再原子重命名为同级唯一 `.owner-mismatch-backup-*` 并重建安全目录，旧配置不得覆盖。Windows 新建 Runner lock、endpoint temp、project-owner diagnostic temp 与 real-E2E 私有文件的 owner 可能仍是 token 默认 owner `Administrators`；只允许本进程 `create_new` 后仍持有不共享独占句柄、且句柄确认普通 / 非 reparse / 单链接的对象在写入或原子安装前初始化为 `TokenUser`，失败时清理该新文件。既有 durable 文件读取、活锁、access denied、硬链接或非固定 lock 路径不得删除、接管或截断。`startup.log` 与 `agent-runner.log` 达到 256 KiB 时只保留一份 `.previous.log`，并扫描 API Key、Authorization、AppData 和其它绝对路径零泄漏；AppData 不可写时 `startup.log` 应回退系统 TEMP 的 `Genarrative-Game-Chat-Diagnostics`，故意注入 `.setup()` / `.build()` 初始化失败时必须出现带诊断日志位置的 Windows 对话框；`.setup()` 发生在 `app.run` 阶段，错误对话框必须由 setup 失败路径直接触发，不能只处理 `.build()` 返回值。Runner 子进程已退出时父进程应立即报告，不得继续等待完整启动期限。
+
+开发侧需要无 UI 验收某个单 Agent 的完整 Runtime 时使用：
+
+```bash
+npm run ai-game-creator-shell:agent-task -- --config-dir /absolute/app-data --init /absolute/project code-prototype "修复失败测试并完成验证"
+```
+
+省略 `--init` 时项目必须已经由客户端初始化。所有 Runtime 写命令都必须显式传入项目外 `--config-dir` 并投递给独立 Runner；`--runner-status` 和 Agent 状态查询只读取已有配置与 endpoint，不得创建 AppData、修改权限或为了查询启动 Runner。遇到权限确认会返回非零并保留待确认动作，继续操作应回到开发窗口，不能用 CLI 静默绕过。
+
+### 通用 Agent Runtime 内核抽取复验
+
+修改 `server-rs/crates/agent-runtime-core`、AGC capability registry、Agent catalog、Run Profile 或 Completion Policy 后，先运行纯内核与适配器定向门禁：
+
+```bash
+npm run agent-runtime-core:check
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml interaction_ -- --nocapture --test-threads=1
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml native_runtime_capability_registry_is_the_bidirectional_catalog -- --nocapture --test-threads=1
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml game_creator_runtime_ -- --nocapture --test-threads=1
+```
+
+修改 Provider 中立契约、注册表、`platform-llm` adapter 或 AGC interaction Provider 路由时，追加：
+
+```bash
+cargo test --manifest-path server-rs/crates/agent-runtime-core/Cargo.toml --test provider_registry
+cargo test --manifest-path server-rs/Cargo.toml -p platform-llm
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml agent::interaction::tests:: -- --nocapture
+cargo check --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --tests
+```
+
+验收必须同时证明同 protocol 多实例可并存、能力不匹配时 adapter 零调用、三种现役 protocol 仍复用原 HTTP/SSE/parser，以及 AGC stream/non-stream/fallback 均经 registry。Provider Key、base URL、HTTP client 和 raw-log 目录必须保留在 `LlmClient/LlmConfig` 实例，不得下沉 core descriptor/error 或进程全局状态。
+
+修改通用 run 状态机、Store/ToolHost、Agent lane、action 恢复或 delegation/join 时，追加执行内核 conformance 和 AGC 恢复优先级回归：
+
+```bash
+cargo test --manifest-path server-rs/crates/agent-runtime-core/Cargo.toml --test runtime_execution_conformance
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml background_agent_runtime_legacy_waiting_task_blocks_pending_recovery -- --test-threads=1
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml background_agent_runtime_recovers_stale_running_before_pending_task -- --test-threads=1
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml background_agent_runtime_recovers_pending_task_after_cancelled_canonical_run -- --test-threads=1
+```
+
+action conformance 必须在 ToolHost 调用前看到 durable `executing`，并在 observation commit 失败后用全新 engine 重载快照；只在同一进程里重试不能作为 crash recovery 证据。all-join 结果顺序按 child 注册顺序，不按完成先后。
+
+内核必须保持纯 Rust，只允许 `serde / serde_json` 和标准库依赖；用 `cargo tree --manifest-path server-rs/crates/agent-runtime-core/Cargo.toml --depth 1` 核对不得出现 Tauri、`platform-llm`、MCP、HTTP、图片、浏览器、SpacetimeDB 或游戏领域 crate。AGC 的 function name、schema、Agent id、profile、权限和持久协议必须保持兼容；新增内建 capability 只能经统一 registry 建立双向唯一 binding，不能重新增加平行字符串清单。独立 core 测试会生成 crate 内 `Cargo.lock/target` 时，开发者只保留源码和 manifest，交付前清理生成物；正式 AGC lock 仍需提交 path dependency 变更。
+
+### AI 游戏创作 Runtime V1.2 定向复验
+
+`command.exec` 动作必须保留固定程序和逐项 argv，不得把参数拼成 shell 字符串。例如，定向执行当前仓库的受控命令测试时，action 形状为：
+
+```json
+{
+  "program": "cargo",
+  "args": ["test", "project_command_"],
+  "cwd": "apps/ai-game-creator-shell/src-tauri",
+  "timeoutSeconds": 120
+}
+```
+
+该 action 仍需开发窗口精确确认；不能用 CLI 或项目策略把 `command.exec` 默认改为 `auto`。实现或调整 Runtime V1.2 后，从仓库根目录优先运行以下定向命令：
+
+只有 `cargo check/test/clippy/fmt/build`、`npm test`、规范命名的 npm 验证脚本和精确 `node --test` 可以形成验证凭证；`git`、`rg`、`cargo metadata` 与普通 `npm run` 即使成功也只是诊断结果，最后仍需执行验证型命令。
+
+```bash
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml project_command_
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml config_file_overrides_defaults_without_env
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml llm_reasoning_effort_supports_provider_default_and_explicit_levels
+npm run test -- packages/shared/src/contracts/gameCreationApp.test.ts
+npm run ai-game-creator-shell:typecheck
+```
+
+第一条覆盖固定程序 / argv 拒绝规则、输出清洗、超时和源码改写检测；第二条覆盖全局 / per-Agent 配置继承，第三条覆盖 `default / low / medium / high` 到 Provider 请求的映射；后两条覆盖共享 `confirm` 契约、配置结构和发布默认 `high`。模块级定向验证通过后，再按改动范围运行 `npm run ai-game-creator-shell:check`、`npm run check:encoding` 和 `git diff --check`。
+
+### AI 游戏创作 Swarm 显式重试真实复验
+
+正常 `supervisor-swarm` 全部 completed 不能替代真实 retry 证据。修改 Runtime 显式重试、Provider lifecycle、隔离 AppData 或 Swarm 验收器后，先跑代理夹具和静态门禁，再运行独立真实 suite：
+
+```bash
+npm run test -- apps/ai-game-creator-shell/tests/llmTransientFaultProxy.test.ts
+npm run ai-game-creator-shell:typecheck
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml provider_retry_ -- --nocapture --test-threads=1
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml provider_transient_retry_ -- --nocapture --test-threads=1
+npm run ai-game-creator-shell:agent-runtime:supervisor-swarm-transient-retry-real-e2e -- --config-dir <AppData>
+```
+
+V1.39 真实门禁把一次故障注入到 Project Supervisor 的首次 tool-plan，使退避期强杀发生在子 Agent Provider 请求产生之前；恢复后仍须在同一父 Session/run 完成双专业 Agent 真重叠与唯一 repair。suite 使用 `30s` 退避，必须先观察 sidecar 已落盘且 task/state 均为 `running / waiting-for-provider-retry`，再强杀 Runner；新 boot 接管后 sidecar identity、字节、attempt、slot 与 `retryAt` 不变，重启后和到期前代理请求数都只能为 1。代理的 metadata-only 请求日志只允许保存序号与毫秒时间，第二个请求的 `acceptedAtMs` 必须不早于 `retryAtMs`，且不得包含 URL、method、headers 或正文。forwarding gate 放行前 action、receipt、子委派、claim、assistant、pending、project revision 与 upstream forwarding 全为 0；受控 request identity 必须恰好包含 1 个 failed lifecycle、1 条 retry audit 和 1 个 `-transient-1` 后继 identity。其它真实瞬态失败按 incidental failure/retry 分开计数，每条仍须通过既有 lifecycle、retry audit、唯一后继和终局门禁且两类计数相等；不能把它们混入受控注入链，也不能跳过唯一 Supervisor assistant 和零重复/残留/泄漏要求。首批双专业 Agent 使用正式 collaboration policy 固定为同批两个指定 static delegate，不能只靠提示碰运气；该 suite 已在 Provider 退避边界完成唯一一次 Runner 强杀，后续 repair 只验证持久 pending/确认链，不重复制造第二个 kill 边界。
+
+V1.40 final-reply 持久恢复先运行确定性门禁：
+
+```bash
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml provider_retry_waiting_final_reply_restart_commits_once -- --nocapture --test-threads=1
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml provider_retry_waiting_final_reply_compaction_resumes_without_new_tool_plan -- --nocapture --test-threads=1
+```
+
+第一条测试必须停在 final-reply retry sidecar 已提交而 task/state 尚未投影的窗口，恢复扫描补齐 waiting 后在到期前保持零请求；第二条必须让 final-reply 前置自动压缩先失败并进入 `requestKind=final-reply-context-compaction` 等待态，到期后恢复同一压缩请求，再继续原 final-reply。两条链路都不得重新调用 tool-plan；失败和恢复请求只比较 HTTP body 字节、SHA-256 和长度，测试失败不得打印正文。真实 Provider 验收必须另起独立 suite，在 Supervisor 已认领全部专业回执、repair 和宿主验证后注入 final-reply 故障并于退避期强杀 Runner；该 suite 尚未 PASS 前，不能复用 V1.39 首次 tool-plan 的真实证据。Provider 成功返回到 finalization journal `prepared` 之间的崩溃窗口仍须独立补齐和验收，当前门禁不能据此宣称 Provider 调用 exactly-once。
+
+### AI 游戏创作 Runtime V1.41 成功交接与回复流恢复复验
+
+修改 Provider 成功响应、持久重试、finalization、response stream 或 Runner idle 判定后，至少运行：
+
+```bash
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml provider_handoff_ -- --nocapture --test-threads=1
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml response_stream_ -- --nocapture --test-threads=1
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml durable_provider_handoff_prevents_shutdown_even_when_corrupt -- --nocapture --test-threads=1
+```
+
+复验和排障按 durable ownership 的顺序取证：
+
+1. 先按 handoff 中保存的真实 `providerRequestId / requestSlot / attempt` 核对 Provider lifecycle。成功响应必须先原子写入 handoff 并回读完全一致，再为同一真实 requestId 补 `completed`；恢复不得生成替代 requestId。
+2. 在 handoff 已提交、lifecycle 仍只有 `started` 的 checkpoint 停止执行，关闭 mock Provider 后再恢复。final-reply 必须零网络回放并只产生唯一 assistant/completed/committed stream；前置压缩只允许在回放压缩结果后发出后续必要的 final-reply，不能重复 tool-plan 或 compaction。
+3. 同一 run 同时存在 handoff 与 retry 时，完全匹配才允许回放并清理 retry；identity、attempt 或 slot 冲突必须零网络进入 `needs-reconciliation`，保留两份 sidecar 和真实 requestId 证据，不要为了让 Runner 退出而手工择一删除。
+4. finalization 已到 `runtime-completed` 后，故意删除 stream、保留 `streaming` 半句、注入 committed 写失败、在 committed 后 journal 清理前停止，并在期间推进全局 project revision。恢复必须始终使用 journal 固定的 run/request slot/steer cursor/response revision 与正文重建或幂等提交，写入后回读成功才可删除 journal。
+5. 固定身份或正文冲突、stream 写入或回读失败时，断言 journal 保留且恢复扫描继续处理同一 finalization；Runner 对 primary、`.previous` 或损坏 handoff 都应保持 busy，`runner.shutdown_if_idle` 不得返回 idle。终局再核对 retry/handoff/finalization sidecar 全部为零，并扫描公共 task/event/Agent DB/CLI，确保没有响应正文、thinking、凭据、Provider URL 或绝对路径。
+
+V1.41 只覆盖无 tool call 的 `context-compaction / final-reply-context-compaction / final-reply`。Runner 在 Provider 成功后、handoff 原子提交并回读前被硬杀时，仍只能把未闭合 `started` 视为结果未知并失败关闭；该窗口不是 exactly-once。`tool-plan` 及其 function arguments 不进入 handoff，真实外部 Provider 的 final-reply 退避期 Runner 强杀仍需独立 E2E，不能用上述确定性测试或 V1.39 PASS 代替。
+
+### AI 游戏创作 Runtime V1.42 Supervisor final-reply 强杀真实复验
+
+V1.42 不改变生产 Runtime 协议，只补一次性 fault proxy selector 和独立真实 suite。先完成确定性门禁，再显式传入发布 AppData 的绝对路径运行长链路：
+
+```bash
+npm run test -- apps/ai-game-creator-shell/tests/llmTransientFaultProxy.test.ts
+node apps/ai-game-creator-shell/scripts/agent-runtime-real-e2e.mjs --self-test
+npm run ai-game-creator-shell:agent-runtime:supervisor-swarm-final-reply-transient-retry-real-e2e -- --config-dir <发布AppData绝对路径>
+```
+
+1. proxy selector 只允许读取冻结的 `sequence / acceptedAtMs`，不得接触 URL、header、body 或 Key。harness 从持久层识别同一父 Session/run 的唯一 base final-reply，先核对 `2` 初始加 `1` repair delivery 均已 claim、两次 observed claim 完整覆盖 `3` receipts 且 assistant 为 `0`；selector 再在 proxy reset/forward 该请求前，以可信宿主 Node 在 disposable project cwd 同步运行固定的 `node verify-e2e.mjs`。仅 `real-e2e-command=passed` marker 成功且无失败 marker 才允许注入；失败、超时或 marker 无效时不注入，stdout/stderr 不得写入 state、checkpoint、report 或公共日志。父 run 的 `project.verify` audit/receipt/observation 计数仅用于诊断，不是注入门禁。
+2. base final-reply failed lifecycle、retry audit、sidecar 和 task/Runtime `running / waiting-for-provider-retry` 全部成立后，才在 `30s` backoff 内用 pidfd `SIGKILL` 强杀 suite 自有 Runner。新 boot 必须保持 Session/run/request fingerprint/attempt/next slot/sidecar 字节/retryAt；重启后和到期前零新请求，到期后只允许唯一 `-transient-1`，并证明 `acceptedAtMs >= retryAtMs`。
+3. forwarding gate 放行前再次比较 delivery/claim/receipt、assistant、pending、project revision、可信宿主 marker 结果和父 tool-plan 数；后者在恢复前后必须相等，父 `project.verify` 仍只保留诊断计数。终局要求唯一成功 parent final-reply、唯一 Supervisor assistant、唯一 committed response stream，retry/handoff/finalization artifacts、重复和公共正文/Key/绝对路径泄漏均为 `0`。
+4. task/Runtime 到达终态后仍要显式等待 pending、retry、handoff、finalization、confirmation sidecar 全部清零，并设置 `10s` 硬超时。终态采样与 durable 清理之间允许存在短窗口，但超时仍有残留必须判该轮 **FAIL**，不得复用后续轮次的清理结果。
+5. 并行 Agent 执行 `file.write / file.patch / file.delete` 时统一走 Runtime 短等待项目写锁。锁竞争失败只返回脱敏错误，尤其不得让 `file.write` observation 携带绝对锁路径后再进入 pending 持久化；定向 Rust 回归至少覆盖短等待写锁和 `file.write` 错误脱敏两条边界。
+
+旧 `supervisor-swarm-transient-retry` 继续只复验首次 tool-plan，不能替代新 suite。确定性门禁已完成 fault proxy `14/14`、E2E self-test **PASS**、前端 `308/308`，以及 shell typecheck、`platform-llm 41/41`、`platform-agent 17/17`、`shared-contracts 7/7`。真实外部 Provider suite 共执行六轮，前五轮均为 **FAIL** 且不得拼接：第一、二轮沿用既有失败记录；第三轮因终态后过早观察到 `1` 个 finalization journal 失败；第四轮因 quality-review 普通 tool-plan 连续 transport/connectivity 失败并耗尽重试、未进入目标故障而失败；第五轮因并行 `file.write` 与项目写锁竞争，绝对锁路径进入失败 observation 后触发 pending 持久化拒绝和 `needs-reconciliation` 而失败。完成终态 sidecar 等待和写锁/脱敏修正后，第六轮在同一轮内完整 **PASS**。
+
+第六轮使用 `gpt-5.5 / openai_chat`，形成 `2` 条初始加 `1` 条 repair delivery 和 `3` 条专业 Agent assistant，精确命中 Project Supervisor base final-reply，可信宿主 verify marker 门禁通过；受控 Provider `failed=1 / retry=1`、incidental `failure=0 / retry=0`，`30s` backoff，pidfd `claim=2 / signal=2`，Runner `resumed=true / identityStable=true`。父 tool-plan 在故障前后均为 `13`，parent final-reply 与最终 assistant 唯一，response stream `sequence=2 / committed`；pending、retry、handoff、finalization、confirmation sidecar、全部重复计数及 API Key、私有正文、项目路径、正式配置路径和公共报告泄漏扫描命中均为 `0`。V1.41 handoff 落盘前 unknown-result 边界和 tool-plan handoff 未覆盖状态保持不变。
+
+suite 只能读正式 AppData，在其同级目录写入 sentinel 管理的 `0600` 私有副本和 overlay；启动 CLI/Runner 时须把 loopback 合并进大小写两套 no-proxy 环境，防止系统 HTTP 代理绕过本地故障门禁；source-dir guard 必须证明本 suite 前缀未进入源目录，源配置和 endpoint 身份保持不变，报告不得保存 Provider URL、headers、正文、凭据或绝对配置路径。sidecar 先于 task/state 投影是合法提交窗口，验收器应等待完整等待态后再强杀；若后续协作或终局失败，partial report 仍应保留已取得的 retry checkpoint，但失败轮不得与后续成功轮拼接。
+
+### AI 游戏创作自主 Swarm 终端复验
+
+日常人工验收优先使用短入口，不再手工拼 AppData、临时项目和预览命令：
+
+```bash
+npm run agc:test
+npm run agc:test:chat
+```
+
+`agc:test` 委托确定性 lane-defense E2E，使用本地 loopback Provider 完成 Runtime、项目写入和真实浏览器 `37/37` 门禁，不消耗外部 Provider。`agc:test:chat` 按当前平台自动查找发布客户端 AppData 中的 `game-creator.config.json`，把主配置和可选 local overlay 私有复制到 sentinel 管理的单次隔离 AppData，绝不复制正式 `agent-runner.endpoint.json`、Runner lock、备份或其它文件；随后创建一次性项目，进入 `project-supervisor + autonomous-game-build`。用户只输入一条需求并以 EOF 交付，收束后复用正式 localhost preview server 并打开试玩。正常收束后按 `Ctrl+C`，脚本先通过内部 CLI 仅关闭已经空闲的隔离 Runner，再清理隔离 AppData 和一次性项目；Runner 仍有任务或无法确认退出时必须同时保留项目与隔离配置并报告路径，不得触碰或强退正式客户端 Runner。需要主动保留项目时显式追加 `-- --keep-project`，需要覆盖配置来源或项目时使用 `--config-dir` / `--project-dir` 绝对路径。脚本不得读取或打印 API Key，显式项目永不自动删除，非空且未初始化目录必须拒绝。
+
+修改 Supervisor 自主编排、`agent.message`、static delivery/claim/repair、Swarm CLI `turn.report`、Runner 恢复或 autonomous harness 后，先跑确定性收敛门禁，再运行真实终端 suite：
+
+```bash
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml background_agent_runtime_bounds_duplicate_agent_message_livelock -- --nocapture
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml agent_runtime_context_window_ -- --nocapture
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml project_supervisor_ -- --nocapture
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml swarm_cli::tests:: -- --nocapture
+npm run ai-game-creator-shell:agent-runtime:supervisor-swarm-autonomous-chat-real-e2e -- --config-dir <AppData>
+```
+
+业务任务和一次性仓库规则不得出现 Agent ID、数量、并行/同轮、工具、repair 次数、run/action/delegation 或 Runner 配方。PASS 必须由真实发布二进制的 `--swarm-chat` 自主形成至少两个不同专业 Agent 的同批委派和真实 Provider 重叠，在 acceptance criteria 不满足时只形成一个继承原合同的 repair；repair 确认边界执行 Runner 强杀后仍保持父 Session/run、delivery、claim、pending action 和 Provider started 身份。父 run 的 `project.verify` 是允许的宿主验证，其它意外父 pending action继续失败关闭。
+
+终局必须同时得到 `turn.report=settled`、新增 Supervisor assistant 恰好 1、专业 assistant 只在内部 Session、队列/确认/用户输入/reconciliation/sidecar 全 0，以及重复 action/delivery/message/receipt/Provider lifecycle 和正文/凭据/绝对路径泄漏全 0。`agent.message` 完整回归还要证明同语义消息只写一次、后续 no-op 不刷新进展、6 轮后保持未完成计划并诚实 `budget-exhausted`。隔离 AppData 必须位于正式 AppData 同级并自动清理；失败尝试与后续 PASS 不能拼接，`maxRetries=0` 下的真实外部 Provider 失败应单独保留为失败证据。
+
+### AI 游戏创作静态与隔离混合 Swarm 复验
+
+修改 static delivery/claim、isolated group/result/all-join、父 waiting phase、`agent.run_status` 混合认领、Supervisor 混合协作策略、Runner 恢复或 finalization blocker 后，先运行三条确定性回归，再运行独立真实终端 suite：
+
+```bash
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml project_supervisor_mixed_ -- --nocapture --test-threads=1
+npm run agc:mixed-swarm-e2e -- --config-dir <AppData>
+```
+
+业务任务只写正式交付、临时检查和验证等结果范围，不写 Agent ID、数量、并行方式、具体工具或 Runner 操作。真实 suite 必须以单个独立 run 证明两类 Provider 真重叠、两类 durable 记录绑定同一父 Session/run、认领 observation 早于唯一父 finalization、Runner 恢复身份稳定、isolated 实际零 mutation、唯一用户回复、零重复/残留/泄漏并完成 sentinel 清理；不能把 isolated 的 suite 零写入要求解释成生产权限层面的只读沙箱。命令未运行、退出非零或报告字段不完整时不得标记 PASS，也不得把失败轮和后续成功轮拼接。
+
+### AI 游戏创作 Supervisor 协作策略复验
+
+修改 `.agent/collaboration-policy.json`、Supervisor 首波预检、Provider action batch v2、委派后总控 mutation/MCP 门禁、协作 finalization blocker 或对应恢复顺序后，先跑确定性回归，再运行独立真实 suite：
+
+```bash
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml supervisor_collaboration_ -- --nocapture --test-threads=1
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml provider_action_batch_ -- --nocapture --test-threads=1
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml project_supervisor_mixed_ -- --nocapture --test-threads=1
+npm run agc:collaboration-policy-e2e -- --config-dir <AppData>
+```
+
+真实 suite 必须在隔离 AppData 和单个父 Session/run 中写入 mixed 策略，要求两个指定 static Agent 与同一 group 的三个 isolated child。首批 batch 必须先停在 `waiting-confirmation / nextActionIndex=0` 且副作用为 0；此时强杀 Runner，恢复后 batchId、policy/contract fingerprint 和全部 actionId 必须逐项稳定，再继续完成 V1.31 mixed chain。为避免长链路被偶发外部 transport 抖动误判，suite 只在隔离配置副本中启用有限瞬态重试，必须同时证明正式 AppData、源配置和 Runner endpoint 未被改动，并在报告中保留 retry 计数。最终仍要求两类真实 Provider 重叠、唯一 Supervisor assistant、零重复/残留/泄漏和 sentinel 清理；命令未运行或报告门禁不完整时不能把确定性测试或 V1.31 PASS 当成 V1.32 PASS。
+
+### AI 游戏创作 Runtime V1.10 持久进程定向复验
+
+V1.10 的 PTY 只通过四个 Runner-owned 工具开放；不要把 V1.2 `command.exec` 改成长驻入口。最小工具输入保持结构化：
+
+```json
+{"tool":"command.start","input":{"program":"npm","args":["run","dev"],"cwd":".","timeoutSeconds":300}}
+{"tool":"command.poll","input":{"processId":"proc-...","cursor":"v1:proc-...:0","maxChars":8000,"waitMs":1000}}
+{"tool":"command.stdin","input":{"processId":"proc-...","data":"q","appendNewline":true,"eof":false}}
+{"tool":"command.terminate","input":{"processId":"proc-...","cursor":"v1:proc-...:254"}}
+```
+
+定向复验按以下顺序取证：
+
+1. 用 Runner-owned PTY fixture 覆盖 start、增量 poll、stdin、自然退出和 terminate；确认 `processId` 绑定完整 owning project / Agent / task / session / run / start action / Runner boot，而不是 OS PID。
+2. 让发起 App / CLI 在 start 后退出，确认 Runner 仍持有会话；随后分别在 launch、running、stdin 和 graceful / force 终止窗口强杀 Runner，确认恢复只进入 reconciliation，不增加 fixture launch / stdin 次数，也不按 PID 重连。
+3. terminate 必须携带最后一次 poll 的 `nextCursor`，返回同一 cursor 且不消费输出；活会话和 unresolved reconciliation 期间尝试 finalization 与 `runner.shutdown_if_idle`，必须分别被完成门禁和 busy 状态阻断；终止成功必须同时满足 child terminal、同组残留清理、wait / reap 和 PTY drain。
+4. 使用不同静态 Agent、动态 sibling、run 和项目重放同一 `processId`，全部必须失败关闭。扫描 task、event、Agent DB、receipt、action history、activity/output、UI snapshot 和报告，PTY 输出正文命中数必须为 0，stdin 只能出现 `bytesWritten / contentSha256 / stdinOpen / eof`。
+5. Linux 用忽略 SIGHUP 的 npm / Node fixture 验证 Runner 强杀后 owner watchdog 回收同一前台进程组；Windows 验证 kill-on-close Job Object。仍要明确 PTY、固定 argv、隔离环境和两阶段终止不是容器或 OS sandbox，主动 `setsid` / 外部 service 仍不在完整隔离承诺内。
+
+实现用例统一使用可检索的 `process_session_` 前缀。先运行定向 Rust 用例，再跑 Tauri 全量和真实 Provider：
+
+```bash
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml process_session_ -- --nocapture
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml
+npm run ai-game-creator-shell:agent-runtime:real-e2e -- --config-dir <AppData> --suite process-session
+npm run ai-game-creator-shell:agent-runtime:real-e2e -- --config-dir <AppData> --suite process-session-runner-kill
+```
+
+定向命令必须实际匹配到 V1.10 用例，`0 tests` 不算通过。真实 Provider fixture 不得把工具顺序、processId、readiness 文本所在 chunk 或 OS PID 写进任务提示；验收器只按持久 action identity、fixture 计数、私有输出和公共泄漏扫描判定。三项门禁实际通过后才能把日期、Provider、数量和 PASS 结果写入技术方案或 decision log；未运行或被外部配置阻断时只记录 `BLOCKED` / 未验收事实。
+
+`npm run agc` 会启动 Tauri 开发客户端；其 `beforeDevCommand` 通过 `npm run agc:serve` 先完成壳 typecheck，再启动或复用配套 SpacetimeDB、`api-server` 和固定 `127.0.0.1:3080` Vite。开发态只打开游戏创作聊天入口使用 `npm run agc:game-chat -- [--project-path <absolute-path>]`。只需要浏览器预览同一客户端时可用 `npm run agc:serve`；只启动配套后端和数据库时可用 `npm run agc:backend -- --database <name>`。
+
 Linux 多用户共享同一台机器开发时，本地 dev 脚本会为当前 Linux 用户分配一个固定端口段并写入系统级注册表 `/var/tmp/genarrative-dev-port-ranges/registry.json`，自动分配从 `10000-10099` 开始，每段 100 个端口，五个 dev 服务依次使用 `start` 到 `start + 4`，其中 BgFilter worker 固定为 `start + 4`。可用 `GENARRATIVE_DEV_PORT_RANGE` 或 `npm run dev -- --port-range` 手动指定端口段用于特殊场景；注册表会阻止不同用户使用相同或重叠段，并让同一用户后续启动继续复用自己已占用的固定段。该机制只在 Linux 生效，Windows 把第五个服务纳入原有统一端口探测与漂移逻辑。

 本地 `npm run dev`、`npm run dev:spacetime`、`npm run dev:api-server` 和 `npm run dev:bgfilter-worker` 会在 Rust 子进程环境中绕过项目默认 `sccache` wrapper，避免损坏的本机 cache daemon 阻断 `spacetime publish` 或 Rust 服务启动；显式设置的非 sccache 自定义 wrapper 会被保留。生产 / Jenkins 构建仍按流水线自身的 sccache 策略执行。
@@ -238,6 +490,7 @@ npm run check:native-shells
 ```

 该命令会覆盖 H5 HostBridge 关键测试、微信 / Expo / Tauri 三端桥接层文件结构门禁、完整相对路径文档反查、微信 capability 到真实 WebView / 支付 / 分享页面流程和测试清单的映射门禁、H5 HostBridge 事件订阅双能力门控反查、H5 `navigation.canGoBack` 消费 hook 与直达二级页返回锚点测试、移动端和桌面端单端源码清单门禁、Expo 壳 typecheck / test / EAS build config smoke / config smoke / Metro export smoke、Tauri 壳 typecheck / cargo test、桌面壳 release `--no-bundle` 构建烟测，以及可分发壳与 H5 HostBridge 真实调用链的临时替身词扫描，确认 Expo managed config、移动端 EAS 原生包构建 profile、移动端 iOS / Android production bundle、打包 H5 资产、Tauri release 入口、H5 页面内导航保留完整原生宿主上下文和 H5 HostBridge 真实调用链没有漂移；扫描范围包含微信小程序壳生产 `.js`、Tauri `Info.plist`、共享 HostBridge 契约、H5 native transport，并自动覆盖已接入真实宿主能力 facade 的 H5 生产调用链文件，但不扫描 Expo export、Tauri `target/`、Cargo / Metro 缓存或 release 构建产物。移动壳配置检查必须反查 EAS 生产 profile、文本 / 文档 / 图片 / 音频导入边界都来自共享 HostBridge 契约。登录与支付外链跳转必须保持在该调用链扫描内，`src/services/authService.ts` 和 `src/services/payment/paymentRedirect.ts` 是必扫文件；`AuthGate` 的登录成功、退出登录、身份边界刷新和登录状态异常重试都必须通过 `app.reloadWebView` 优先路径，并由 `src/components/auth/AuthGate.test.tsx` 进入该门禁。壳源码和配置继续严格禁止 mock / fake / placeholder / stub / TODO / FIXME / 占位 / 模拟 / 伪造 / 未实现 / 临时；H5 业务调用链允许正常表单 `placeholder` 属性、业务占位图文案和真实兼容 / 故障语义中的“未实现”“临时”表述，但仍禁止 mock / fake / stub / TODO / FIXME / 模拟 / 伪造等替身痕迹。
+根仓 Vitest 加载独立 AI 游戏客户端源码时，不得为了模块解析把 `@tauri-apps/api` 或 `@tauri-apps/plugin-*` 加入根 H5 依赖；根测试只通过 `vitest.config.ts` 的精确别名使用无副作用测试替身，独立客户端的正式 Tauri guest 依赖继续只由 `apps/ai-game-creator-shell/package.json` 与其 lock 管理。隔离 worktree 验收前需分别执行根 `npm ci` 和 `npm ci --prefix apps/ai-game-creator-shell`。
 反馈页上传凭证在原生壳声明 `file.importImage` 时必须优先走宿主图片导入；移动壳声明 `file.captureImage` 时才显示拍摄凭证入口，并把拍摄图片同样转为 `File` 后复用反馈页原有数量、大小、MIME、data URL 预览和提交 payload 校验。
 Expo / Tauri 声明 `navigation.openNativePage` 时，只用于现役同源 H5 路由的受控导航和宿主上下文续接；微信小程序不再声明该能力。旧儿童动作 Demo、模板工作台、生成页、结果页和运行态不得作为 HostBridge 导航验收入口。
 H5 支付链接跳转在原生壳声明 `app.openExternalUrl` 时必须优先走宿主系统浏览器；原生壳未接真实支付 SDK 前不得声明 `payment.request`，也不得把外部 H5 支付跳转伪装成原生支付成功。
@@ -273,6 +526,11 @@ npm run check:server-rs-ddd

 - 仓库 CI 入口是 `.gitea/workflows/project-ci.yml`，向 `master`、`codex/ai-game-creator-app` 推送和所有 PR 创建、更新时必须运行，也允许手工触发。
 - CI 固定拆分为 `Repository checks`、`Frontend tests`、`Backend tests`、`Native shell tests` 四个 required job；对应 PR context 完整名称是 `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)`，首次运行后仍须从 Gitea 最近一周 context 表复核。测试使用独立 job，不能只藏在综合检查 step 中；原生壳验收单独运行以便定位重型构建失败。
+- 四个 job 共同覆盖 `npm run check`，并追加 `npm run check:server-rs-ddd`、`cargo test --locked --workspace --no-fail-fast --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --all-targets --manifest-path server-rs/Cargo.toml` 和 `cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml`。后端 runner 安装 `ffmpeg`，避免视频抽帧测试因工具缺失提前返回。`codex/ai-game-creator-app` 分支必须用独立 lockfile 安装 AI 游戏创作壳依赖，其原生壳入口还必须覆盖 `npm run ai-game-creator-shell:check`、release build smoke，并检查 AI Tauri `Cargo.lock` 不漂移。原生壳 job 还要通过 Google 官方签名 APT 源安装 `google-chrome-stable`，用于 headless preview 的真实 DOM / canvas smoke；同时安装 `ripgrep`，把 `actions/setup-node` 的完整 Node.js 22 发行目录与 root-owned rustup proxy 映射到 `/usr/local`，供只接受受信任系统命令目录的 `command.exec` 沙箱测试使用，不能放宽生产命令目录白名单。Tauri 的 1132 项级别 suite 固定 `--test-threads=1`，避免共享 Agent Runtime 后台锁与异步终态在 libtest 并行调度下互相干扰。
+- checkout 必须使用完整历史。PR 将 base SHA 写入 `SPACETIME_SCHEMA_BASE_REF`，直接推送 `master` 使用 before SHA；事件基线不可解析时直接失败。Gitea 检查的是 PR head 而非预合并 commit，workflow 必须拒绝不包含最新 base commit 的过期 PR，分支保护同时保持“PR 过期禁止合并”。
+- 普通 PR job 不读取业务 secret，不运行真实 API/SpacetimeDB/OSS/支付/生成/live smoke，也不执行会修改外部状态的维护、迁移、发布或备份命令。
+- Gitea 至少升级到 `1.26.4` 后才能注册执行 PR job 的 runner；`ubuntu-latest` 标签只映射到固定 digest 的 Ubuntu 24.04 级 Docker/临时隔离镜像，不使用浮动镜像 tag，不映射 host，不向 job 暴露 Docker socket、业务 secret 或不必要内网。runner 能访问 Gitea、GitHub Actions 与 `actions/node-versions`、nodejs.org、npm、Rust 分发、crates.io 和 Google Chrome 的 `dl.google.com` 官方签名 APT 源；workflow 的官方 action 固定完整 commit，若内网禁用 GitHub，先在当前 Gitea 镜像对应 commit 并改用绝对 URL。受控镜像优先预装 rustup。Gitea 1.26 的任务超时由 runner 全局配置控制；首次运行成功后，`master` 分支保护必须要求上述四个 job 全部成功。
+- `genarrative-station` 当前使用 Gitea `1.26.4` + 基于 Runner `2.0.0-dind-rootless` 的固定 digest 修补镜像：只修复 `systempaths=unconfined` 的空 slice 被 `mergo` 丢失，真实 job 必须保持 `MaskedPaths=[]`、`ReadonlyPaths=[]`；外层仍非 privileged、无 `CAP_SYS_ADMIN`，内部 Docker 只监听 Unix socket，`docker_host: "-"` 阻止 socket 进入 job。job 只在 `gitea-actions` internal network，通过 `/git` reverse gateway 访问 Gitea，通过拒绝私网、保留地址和 metadata 的 80/443 proxy 访问公共依赖；直连公网和 Gitea 数据网必须失败。内层 bwrap 所需 namespace/proc 选项只能用于该 rootless DinD，不能放宽宿主 rootful runner。系统依赖步骤在 root job 中不调用 sudo，非 root 时用 `sudo -E` 保留受控 proxy；Cargo 关闭 HTTP multiplexing 并设置 10 次网络重试，rustup bootstrap/toolchain 安装也按有界次数重试。AI 原生壳 job 把 Node 发行目录与 rustup proxy 安装到 `/usr/local` 的受信任只读路径，并在测试前执行完整 bwrap canary。宿主 compose helper 必须把 `/opt/gitea-stack` 挂到同名绝对路径，避免相对 volume 错误落到 `/stack` 空目录。
 - 四个 job 共同覆盖 `npm run check`，并追加 `npm run bgfilter-worker:smoke-test`、`npm run check:production-health-patrol`、`npm run check:production-api-release`、`npm run check:production-api-deploy`、`npm run check:server-rs-ddd`、`cargo test --locked --workspace --no-fail-fast --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --all-targets --manifest-path server-rs/Cargo.toml` 和 `cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml`。BgFilter 的 `.test.mjs` 使用 Node test runner，必须由 workflow 显式调用；生产巡检 / 发布 / 部署行为检查只运行无密钥临时 fixture，不连接现场环境。`ffmpeg` 由预构建 job 镜像提供，避免视频抽帧测试因工具缺失提前返回。`codex/ai-game-creator-app` 分支的原生壳入口还必须覆盖 `npm run ai-game-creator-shell:check` 和 release build smoke。
 - checkout 必须使用完整历史。PR 将 base SHA 写入 `SPACETIME_SCHEMA_BASE_REF`，直接推送 `master` 使用 before SHA；事件基线不可解析时直接失败。Gitea 检查的是 PR head 而非预合并 commit，workflow 必须拒绝不包含最新 base commit 的过期 PR，分支保护同时保持“PR 过期禁止合并”。
 - 普通 PR job 不读取业务 secret，不运行真实 API/SpacetimeDB/OSS/支付/生成/live smoke，也不执行会修改外部状态的维护、迁移、发布或备份命令。
@@ -348,3 +606,27 @@ npm run check:server-rs-ddd
 3. 是否有长期知识需要写入 docs/project-memory/shared-memory；
 4. 建议的测试命令和提交信息。
 ```
+
+## AI 游戏创作 App 命令沙箱验证
+
+- Linux `command.exec / command.start / project.verify` 必须经过受信任系统 bubblewrap；缺失或 namespace / mount preflight 失败时工具失败关闭，不能回退宿主执行。
+- 修改命令执行、PTY、项目验证或发布配置后，至少运行 `GENARRATIVE_COMMAND_SANDBOX_REAL_TEST=1 cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml command_sandbox -- --nocapture --test-threads=1`、`cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml command_exec` 和 `cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml process_session -- --test-threads=1`。
+- 真实门禁必须同时证明项目内 Cargo / npm / Git 成功，项目外普通文件读写失败，`.git / .agent / .agents / .codex / .hermes` 写入失败，网络默认不可达，shell / PTY 后代在 `setsid + chdir` 后仍继承相同边界；process record、poll / stdin / terminate 和 project.verify 审计必须断言 `bubblewrap / workspace-write / disabled / workspace-v1`。另测 `RUSTUP_HOME=$HOME` 与 `.rustup -> $HOME` 必须在目标执行前失败。Linux deb / rpm 包必须声明 `bubblewrap` 依赖；AppImage 发布说明必须要求宿主预装受支持的 bwrap，缺失时只能返回 sandbox unavailable。
+
+## AI 游戏创作 App Provider 成功交接验证
+
+- 文本回复继续使用 `game-creator-provider-handoff.v1`；tool-plan/function arguments 使用独立 `game-creator-tool-plan-handoff.v1`，禁止为省事放宽文本 handoff。两类 handoff 都必须在 Provider lifecycle `completed` 前原子落盘并回读。
+- tool-plan `repair-0..N` 必须共用持久 retry 与 handoff-first 恢复；测试停止点按 request kind/精确 slot 命中，不能让较早的 tool-plan 抢占 final-reply 断点。恢复测试必须关闭 mock Provider，证明零网络、原 requestId 唯一闭合、audit 幂等和终局零 sidecar。
+- function arguments 只能进入私有 `0600` handoff 和后续 pending/action batch。参数命中密钥、配置痕迹或结构化可执行路径中的绝对路径时失败关闭，不得先脱敏再执行；源码正文与计划叙述不能用日志路径 token 扫描，以免把 HTML `</tag>` 当路径。未闭合/错配 thinking wrapper 要保留无正文的无效事实并走 repair，不能清洗成可执行计划。公共事件、Agent DB、CLI 和报告只保留哈希、计数与安全身份字段；tool-plan protocol 不保存原始 callId/callIds/responseId/providerRequestId，只保存 call ID SHA-256 数组、catalog-bound function names、response ID SHA-256/字符数和 Provider request ID SHA-256，repair 只保存 call ID/function name SHA-256 及协议错误/preview 哈希。protocol/repair 审计必须在 Agent DB append 锁内按完整身份全历史 compare-and-append。
+- steer/cancel/终态/身份漂移删除 tool-plan handoff 前，必须先按账本顺序幂等闭合全部实际 requestId lifecycle；不能只闭合当前 base entry 后删除后继 repair。Runner 恢复必须扫描 hash 路径归属、primary/`.previous` 和安全临时文件，回收合法终态残留；Unix 读写、扫描和删除固定在逐层打开的目录句柄，handoff 根目录和 Agent 目录用跨进程 `flock` 序列化，临时文件再用非阻塞 `flock` 判断写入方是否仍持有。已有 primary 的安装通过 `RENAME_EXCHANGE` 双端复核并在冲突时回滚；删除先以 `RENAME_NOREPLACE` 隔离到可恢复 temp 名、复核 inode，再按原 fd 清空并同步私有内容。Windows 逐层使用相对父句柄打开，并用 `GetFileInformationByHandleEx` 直接枚举已验证目录句柄，拒绝 reparse point/junction 与硬链接，临时文件以禁止共享的独占句柄表示活跃写入。不得再用文件名中的 PID 或进程存活推断临时文件所有权。未知、链接、身份替换或内容冲突项保持 busy 并失败关闭；主动忽略 advisory lock 的同 UID 进程仍属于宿主 OS 信任边界，不能宣称为完整沙箱隔离。
+- 修改 Provider handoff/retry/Runner idle 判断后，至少运行 `tool_plan_`、`tool_plan_handoff_`、`provider_handoff_`、`provider_retry_`、相关强杀恢复用例、Tauri 串行全量 `cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml -- --test-threads=1`、编码检查和 `git diff --check`；涉及跨平台扫描、PID 或临时文件回收时追加 `cargo check --tests --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --target x86_64-pc-windows-gnu`。当前默认并发全量会受 Tauri 共享执行器饱和影响，曾在不同异步投影断言上偶发失败；它只作竞态诊断，失败时必须精确复跑，不能替代串行门禁，也不能把精确复跑结果伪装成默认并发 PASS。真实 Provider suite 单轮 PASS 前，确定性 mock 结果不得写成外部验收完成。
+- `supervisor-swarm-tool-plan-handoff-runner-kill` 已实现并在 Shell/Root 两级注册。真实外部 Provider 复验从仓库根目录运行：
+
+```bash
+npm run ai-game-creator-shell:agent-runtime:supervisor-swarm-tool-plan-handoff-runner-kill-real-e2e -- --config-dir <发布AppData绝对路径>
+```
+
+- suite 必须使用 sentinel-owned sibling AppData；metadata-only zero-fault proxy 不注入 Provider 故障，为转发请求只做协议校验，请求日志仅记录验收所需的序号/时间等元数据，不得持久化或暴露 URL、method、headers、正文或凭据。每轮随机 capability 必须严格绑定 disposable project、目标 Agent、run 和实际 request slot，任一身份漂移、复用或越权命中都失败关闭。
+- checkpoint 只允许在目标 tool-plan handoff 原子落盘并逐字段回读一致后、同一实际 requestId lifecycle `completed` 前 ACK；收到 ACK 后才可用 pidfd `SIGKILL` 强杀 suite 自有 Runner。新 boot 恢复前不得出现由该计划产生的 action、pending、delivery、claim 或其它副作用。
+- 单轮验收必须证明同一 requestId 唯一闭合且没有替代 identity，proxy `networkReplayCount=0`，protocol/repair audit 幂等，handoff plan fingerprint 与恢复后的 durable pending/action batch 对应；终局 retry/tool-plan handoff/provider handoff/finalization/confirmation sidecar、重复 lifecycle/audit/action/message、capability/Runner/AppData 临时资源和正文/API Key/Provider URL/项目及正式配置绝对路径泄漏全部为 `0`。失败轮不得与后续轮拼接。
+- 当前该 suite 的实现、E2E self-test、Tauri/Rust 串行全量 `1054 passed / 4 ignored / 0 failed`、Linux `cargo check --tests` 与 `x86_64-pc-windows-gnu cargo check --tests` 已通过。2026-07-20 的真实外部 Provider 单轮已到达 checkpoint，并证明旧/新 Runner boot 切换、同一请求恢复、`networkReplayCount=0`、恢复前零 action/pending/delivery 与生命周期唯一闭合；但该轮随后因专业 Agent 连续连接失败而以 FAIL 结束，另一独立轮首批工具数不满足 fixture 也以 FAIL 结束，因此仍没有该 suite 的外部 PASS，且不得拼接两轮证据。Provider 成功到 handoff 原子落盘回读前的 unknown-result 仍未关闭，手动 context-compaction 也不在覆盖内；确定性 mock、命令注册成功或其它 suite PASS 都不能替代单轮完整真实验收。
@@ -14,6 +14,7 @@
 | 创作入口、草稿架和玩法链路 | `docs/【玩法创作】平台入口与玩法链路-2026-05-15.md` |
 | 创作流程统一阶段计划 | `docs/planning/【玩法创作】创作流程统一总计划-2026-05-30.md` |
 | 宿主壳、移动 App、桌面 App 与 AI H5 沙箱边界 | `docs/【前端架构】宿主壳能力统一协议-2026-06-17.md`、`docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md` |
+| AI 游戏创作独立 App、Agent Runtime、Runner、浏览器验证与动态隔离子 Agent | `docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`、`docs/technical/【技术方案】AI游戏创作Agent Runtime V1.1-2026-07-12.md` |
 | 本地启动、验证、部署、埋点和运营查询 | `docs/【开发运维】本地开发验证与生产运维-2026-05-15.md` |
 | 微信小程序虚拟支付 | `docs/【技术方案】微信虚拟支付接入-2026-05-26.md` |
 | UI 像素资产与 9-slice 规范 | `UI_CODING_STANDARD.md` |
@@ -0,0 +1,32 @@
+# AI 游戏创作高风险审批 Rank 待解决事项
+
+更新时间：`2026-07-20`
+
+## 背景
+
+项目开发工作台规划“严格审批 / 高风险审批 / 无需审批”三档。严格审批可直接复用现有 Runtime 确认门禁；高风险审批仍缺少可执行 Rank 合同，当前不能由前端自行判断。
+
+## 待确定
+
+- Rank 的事实源和版本号。
+- 成本、历史错误率、资源不可逆性、代码/命令副作用、外部发布等维度的权重。
+- 单动作 Rank 与批次 Rank 的聚合方式。
+- Rank 阈值由谁配置、如何审计和回滚。
+- 模型建议与 Runtime 强制规则冲突时的裁决顺序。
+- 计费发生前、外部调用前、项目写入前分别在哪个阶段执行门禁。
+- Runner 恢复、重复 action、reconciliation 和策略升级时如何保持确定性。
+- 普通用户可见的风险原因和不泄露内部诊断的展示格式。
+
+## 临时产品边界
+
+- P0 只启用严格审批。
+- 高风险审批在界面中保持视觉不可用，但允许点击查看“Rank 规则待定，暂不可用”。
+- 不得把高风险审批静默降级成严格审批或无需审批。
+- Rank 合同、Runtime 实现和确定性回归完成前不得开放。
+
+## 关闭条件
+
+1. PRD 冻结 Rank 输入、阈值、版本和恢复语义。
+2. Runtime 在副作用前执行同一 Rank 决策，前端只展示后端结果。
+3. 覆盖计费、文件写入、命令、外部生成、批次动作、重放和 reconciliation 回归。
+4. 普通用户界面能说明为何需要确认，但不暴露 provider、fingerprint、密钥或绝对路径。
@@ -1,12 +1,12 @@
 # 后台管理多账号与 Tab 访问权限方案

-更新时间：`2026-07-23`
+更新时间：`2026-07-24`

 ## 1. 文档定位

 本文定义陶泥儿后台从单一环境变量管理员扩展为“1 个 owner 引导账号 + 多个 member 持久账号”的编码契约，并为每个一级 Tab 建立前后端一致的访问权限。

-本次只增加后台管理员账号与整页访问权限，不引入页面内按钮级、字段级或只读权限。正式实现必须同时完成前端导航过滤和后端 API 鉴权；前端过滤只改善体验，不能作为安全边界。
+后台权限默认仍以整页 Tab 为粒度；只有会触发权威钱包全量扫描的“手动对账用户历史花费”作为明确例外，使用独立操作权限，不随任何 Tab 自动授予。正式实现必须同时完成前端按钮过滤和后端 API 鉴权；前端过滤只改善体验，不能作为安全边界。

 ## 2. 当前基线与目标

@@ -17,8 +17,8 @@
 1. 现有环境变量账号升级为 `owner`，仍由部署环境提供，不迁移、不复制到 SpacetimeDB。
 2. owner 始终拥有全部 15 个业务 Tab 权限，并独占“账号管理”Tab 和账号管理 API。
 3. owner 可以创建、修改、启停 member；member 保存在 SpacetimeDB 私有表 `admin_account`。
-4. member 按一级 Tab 分配权限；获得一个 Tab 权限即获得该页面内全部读写能力，页面内部二级 Tab、弹窗和操作区继承一级权限。
-5. member JWT 每次请求都重新读取当前账号并校验 `enabled`、`token_version` 和实时权限，权限、密码或启停变更应立即让旧 JWT 失效。
+4. member 按一级 Tab 分配常规权限；获得一个 Tab 权限即获得该页面内常规读写能力。历史花费手动对账必须另行授予 `profile-wallet-consumption-reconcile`，任何 Tab 都不隐式包含。
+5. member JWT 每次请求都重新读取当前账号并校验 `enabled`、`token_version`、实时 Tab 权限和独立操作权限，权限、密码或启停变更应立即让旧 JWT 失效。

 ## 3. 角色与不可变规则

@@ -26,18 +26,18 @@

 - owner 用户名和密码继续读取 `GENARRATIVE_ADMIN_USERNAME`、`GENARRATIVE_ADMIN_PASSWORD`。
 - owner 是环境变量构造的虚拟账号，不写入 `admin_account`，不允许通过后台改名、改密、禁用或删除。
- owner 始终拥有本文列出的全部 15 个可分配权限，不能在前端取消，也不从数据库加载权限。
- “账号管理”是 owner-only 能力。它可以作为新增一级路由 `accounts` / `#accounts` 展示，但 `accounts` 不进入 `ADMIN_TAB_PERMISSIONS`，不能写入 member 的 `permissions_json`。
+- owner 始终拥有本文列出的全部 15 个 Tab 权限和全部独立操作权限，不能在前端取消，也不从数据库加载权限。
+- “账号管理”是 owner-only 能力。它可以作为新增一级路由 `accounts` / `#accounts` 展示，但 `accounts` 不进入 `ADMIN_TAB_PERMISSIONS` 或 `ADMIN_ACTION_PERMISSIONS`，不能写入 member 的权限 JSON。
 - owner 会话返回 `accountRole = "owner"`、`roles = ["admin", "owner"]`；账号管理权限必须根据服务端确认的 `accountRole` 判断，不能只相信前端角色字符串。
 - owner 配置缺失时，后台整体保持未启用状态；不能依赖数据库中的 member 绕过 owner 引导配置启动后台。

 ### 3.2 member

 - member 只来自 `admin_account`，不新增第二套环境变量账号。
- member 会话返回 `accountRole = "member"`、`roles = ["admin", "member"]` 和当前实时 `tabPermissions`。
+- member 会话返回 `accountRole = "member"`、`roles = ["admin", "member"]`、当前实时 `tabPermissions` 和 `actionPermissions`。
 - member 永远不能访问账号管理页面或账号管理 API，也不能给自己或他人分配 `accounts`。
- member 的一个一级 Tab 权限覆盖该页面的查询、创建、修改、启停、退款等全部现有操作，不拆成 `read` / `write`。
- 页面内二级 Tab、筛选视图、抽屉、弹窗和共享详情弹窗继承触发它的一级 Tab 权限，不另设 permission id。
+- member 的一个一级 Tab 权限覆盖该页面的常规查询、创建、修改、启停、退款等操作，不拆成通用 `read` / `write`。
+- 页面内二级 Tab、筛选视图、抽屉、弹窗和共享详情弹窗默认继承触发它的一级 Tab 权限；历史花费手动对账是唯一独立高风险操作例外，无权限时共享用户详情不展示按钮，直接请求仍由后端返回 403。

 ## 4. 权限标识

@@ -61,9 +61,15 @@
 | `editor-showcase` | 精选审核 | `#editor-showcase` |
 | `editor-assets` | 素材查询 | `#editor-assets` |

-权限数组必须去重并按上表顺序规范化后保存。保存时拒绝未知值和 `accounts`；读取旧数据时遇到未知值应忽略并记录告警，绝不能将未知值解释为全权限。空数组合法，表示 member 可以登录但没有业务页面权限。
+Tab 权限数组必须去重并按上表顺序规范化后保存。保存时拒绝未知值和 `accounts`；读取旧数据时遇到未知值应忽略并记录告警，绝不能将未知值解释为全权限。空数组合法，表示 member 可以登录但没有业务页面权限。

-后续新增一级 Tab 时，必须在同一次改动中更新：
+`ADMIN_ACTION_PERMISSIONS` 是独立操作权限闭合集合，当前只有：
+
+| permission id | 操作 | 授权边界 |
+| --- | --- | --- |
+| `profile-wallet-consumption-reconcile` | 手动对账用户历史花费 | owner 默认拥有；member 必须在账号管理中单独勾选，不要求同时持有特定 Tab |
+
+独立操作权限保存在 `action_permissions_json`，响应为 `actionPermissions`；未知值必须拒绝。后续新增一级 Tab 时，必须在同一次改动中更新：

 - shared-contracts 的 `ADMIN_TAB_PERMISSIONS`。
 - admin-web 的路由定义、权限标签和第一可访问项顺序。
@@ -80,13 +86,14 @@
 | `username` | `String` | `unique`；登录名，创建后不可修改；按 `trim + ASCII lowercase` 规范化 |
 | `display_name` | `String` | 展示名，去除首尾空白后 1 至 64 字符 |
 | `password_hash` | `String` | Argon2id PHC 字符串；只在内部登录查询中返回给 api-server，永不进入 HTTP DTO、日志或前端状态 |
-| `permissions_json` | `String` | 规范化后的 Tab permission JSON；只允许第 4 节 15 个值，空数组为 `[]` |
+| `tab_permissions_json` | `String` | 规范化后的 Tab permission JSON；只允许第 4 节 15 个值，空数组为 `[]` |
 | `enabled` | `bool` | 是否允许登录和继续使用现有 JWT |
 | `token_version` | `u64` | 初始为 `1`；权限、密码或启停状态发生有效变化时加 `1` |
 | `created_by` | `String` | 创建者后台 subject；当前只能是 owner subject |
 | `updated_by` | `String` | 最近更新者后台 subject；当前只能是 owner subject |
 | `created_at` | `Timestamp` | 创建时间，使用 `ctx.timestamp` |
 | `updated_at` | `Timestamp` | 最近更新时间，使用 `ctx.timestamp` |
+| `action_permissions_json` | `Option<String>` | 既有表末尾追加；旧行默认 `None` 并按 `[]` 读取，只允许第 4 节独立操作权限 |

 账号规则：

@@ -94,7 +101,7 @@
 - owner 用户名属于保留名称。创建 member 时必须同时与当前规范化后的 owner 用户名比较并拒绝冲突，不能只依赖 `admin_account.username` 唯一索引。
 - 密码明文只存在于登录、创建和改密请求生命周期内；限制为 6 至 128 个字符，并复用 `platform-auth` 的 Argon2id 哈希与校验能力。Argon2id 必须在 blocking 任务中执行，api-server 通过有界信号量限制同时 hash / verify 数量，不得占用 Tokio worker 或无界堆积高成本任务。
 - 不提供物理删除 API。离职或停用通过 `enabled = false` 完成，以保留 `created_by`、`updated_by` 和账号标识。
- `display_name` 单独变化只更新 `updated_by`、`updated_at`，不要求递增 `token_version`；权限、密码、`enabled` 任一有效变化必须在同一事务中递增版本。
+- `display_name` 单独变化只更新 `updated_by`、`updated_at`，不要求递增 `token_version`；Tab 权限、独立操作权限、密码、`enabled` 任一有效变化必须在同一事务中递增版本。
 - `u64` 版本到达上限时更新失败关闭，不能回绕。

 ## 6. SpacetimeDB 与 facade 边界
@@ -158,9 +165,10 @@ owner 优先既保持原账号行为，也防止数据库同名记录遮蔽或
 ```text
 accountRole: "owner" | "member"
 tabPermissions: string[]
+actionPermissions: string[]
 ```

-owner 返回全部 15 个 permission id；member 返回数据库中的实时规范化数组。`GET /admin/api/me` 同样执行逐请求校验并返回实时权限，供刷新页面后恢复导航。
+owner 返回全部 15 个 Tab permission id 和全部独立操作权限；member 返回数据库中的两组实时规范化数组。`GET /admin/api/me` 同样执行逐请求校验并返回实时权限，供刷新页面后恢复导航和操作按钮。

 后台所有面向运营展示的管理员身份统一使用 `displayName`。审计表继续保存稳定 subject，例如 owner subject 或 `admin-account-<uuid>`；api-server 在返回兑换码、邀请码等操作记录时，按 owner 运行态和 `admin_account` 批量解析显示名称，同时兼容历史用户名记录。已无法解析的历史主体统一展示“已停用管理员”，前端不得直接渲染 `operatorUserId`、账号 ID 或登录用户名代替显示名称。对写接口，显示名目录必须在主事务前加载，或在主事务成功后降级为占位文案；不得因二次读取失败把已提交写入伪装成失败。

@@ -168,14 +176,15 @@ owner 返回全部 15 个 permission id；member 返回数据库中的实时规

 在统一 `require_admin_auth` 之后增加可复用的权限守卫，支持：

- `require_admin_permission(permission)`：owner 自动通过；member 必须包含该 permission。
- `require_any_admin_permission([permission...])`：owner 自动通过；member 至少包含一个，用于共享 API。
+- `require_admin_tab_permission(permission)`：owner 自动通过；member 必须包含该 Tab permission。
+- `require_any_admin_tab_permission([permission...])`：owner 自动通过；member 至少包含一个，用于共享读取 API。
+- `require_admin_action_permission(permission)`：owner 自动通过；member 必须包含该独立操作 permission。
 - `require_admin_owner`：只接受服务端确认的 owner。

 返回语义统一如下：

 - `401 Unauthorized`：token 缺失、无效、过期，member 不存在、被停用或 `token_version` 过期。
- `403 Forbidden`：会话有效但缺少目标 Tab 权限，或 member 请求 owner-only API。
+- `403 Forbidden`：会话有效但缺少目标 Tab / 独立操作权限，或 member 请求 owner-only API。
 - 前端收到 `401` 清除本地 token 并回到登录页；收到 `403` 不应伪装成掉线，应刷新 `/me` 权限并跳转到第一可访问项或零权限空态。

 ## 9. API-to-Tab 权限矩阵
@@ -223,6 +232,8 @@ owner 返回全部 15 个 permission id；member 返回数据库中的实时规
 | `POST` | `/admin/api/profile/recharge-refunds/register` | `recharge-orders` |
 | `POST` | `/admin/api/profile/recharge-refunds/manual-review/resolve` | `recharge-orders` |
 | `GET` | `/admin/api/profile/users/detail` | `tables OR tracking OR recharge-orders OR editor-showcase OR editor-assets` |
+| `POST` | `/admin/api/profile/users/reconcile-consumption` | 独立操作权限 `profile-wallet-consumption-reconcile` |
+| `POST` | `/admin/api/profile/users/initialize-consumption-projections` | owner-only 维护窗口操作 |
 | `POST` | `/admin/api/profile/wallet-restriction` | `recharge-orders` |
 | `GET` | `/admin/api/accounts` | owner-only |
 | `POST` | `/admin/api/accounts` | owner-only |
@@ -249,6 +260,7 @@ accounts: Array<{
  username,
  displayName,
  tabPermissions,
+  actionPermissions,
  enabled,
  tokenVersion,
  createdBy,
@@ -270,6 +282,7 @@ accounts: Array<{
  displayName: string,
  password: string,
  tabPermissions: string[],
+  actionPermissions: string[],
  enabled?: boolean
 }
 ```
@@ -285,11 +298,12 @@ accounts: Array<{
  displayName: string,
  password?: string,
  tabPermissions: string[],
+  actionPermissions: string[],
  enabled: boolean
 }
 ```

-`username` 和 `account_id` 不可修改。更新请求完整提交显示名称、Tab 权限和启停状态；密码省略表示不修改，空字符串密码作为非法参数拒绝。api-server 只在提供新密码时生成新 hash。procedure 比较有效变化，在权限、密码或启停任一变化时只递增一次 `token_version`，并在同一事务写入账号字段、`updated_by`、`updated_at`。响应仍不返回密码或 hash。
+`username` 和 `account_id` 不可修改。更新请求完整提交显示名称、Tab 权限、独立操作权限和启停状态；密码省略表示不修改，空字符串密码作为非法参数拒绝。api-server 只在提供新密码时生成新 hash。procedure 比较有效变化，在权限、密码或启停任一变化时只递增一次 `token_version`，并在同一事务写入账号字段、`updated_by`、`updated_at`。响应仍不返回密码或 hash。

 ## 11. admin-web 行为

@@ -313,7 +327,7 @@ accounts: Array<{

 ### 11.3 账号管理页

- 权限编辑器展示 15 个明确的 checkbox，每项使用现有 Tab 中文名称；不能展示或提交 `accounts`。
+- 权限编辑器分为 15 个 Tab checkbox 和独立操作权限区；当前独立区只显示“手动对账用户历史花费”。不能展示或提交 `accounts`。
 - 创建和编辑使用独立弹窗或抽屉，不在列表下方追加表单。
 - 编辑时密码字段默认空，空表示请求中省略 `password`；页面永不展示现有密码或 hash。
 - 停用使用开关并二次确认。保存成功后以 API 返回 account snapshot 更新列表。
@@ -323,17 +337,17 @@ accounts: Array<{

 建议按以下边界落地，避免在前端或 `api-server` 重新发明持久化规则：

- `shared-contracts`：`ADMIN_TAB_PERMISSIONS`、扩展后的 `AdminSessionPayload`、账号管理 request/response DTO。
+- `shared-contracts`：`ADMIN_TAB_PERMISSIONS`、`ADMIN_ACTION_PERMISSIONS`、扩展后的 `AdminSessionPayload`、账号管理 request/response DTO。
 - `spacetime-module`：私有表、输入类型、typed procedures、唯一性与版本递增事务。
 - `spacetime-client`：生成绑定、row mapper、登录查询与账号管理 facade。
 - `api-server`：owner/member 登录编排、Argon2id、逐请求账号解析、权限 middleware、账号管理 handlers。
 - `apps/admin-web`：权限感知路由、hash 回落、零权限空态、owner-only 账号管理页。

-不能将 `permissions_json` 的解析与授权只放在前端；不能让 admin-web 直连 SpacetimeDB；不能用进程内 member 列表替代 `admin_account`。
+不能将 Tab / 独立操作权限 JSON 的解析与授权只放在前端；不能让 admin-web 直连 SpacetimeDB；不能用进程内 member 列表替代 `admin_account`。

 ## 13. 迁移、绑定与发布顺序

-`admin_account` 是新增私有表，没有旧数据回填。原环境变量 owner 不入表，因此迁移不创建 owner 行。
+`admin_account` 已是私有表；本次只在表结构体最后追加带 `None` 默认值的 `action_permissions_json`，旧 member 自动按空独立权限读取。原环境变量 owner 不入表，并始终由 api-server 合成全部权限。

 实现 schema 后必须：

@@ -380,16 +394,17 @@ spacetime publish <database> \
 - member 私表不能被普通 SpacetimeDB identity 查询或调用 procedure；只有 runtime service identity 可读写。
 - 创建重复规范化用户名、owner 保留用户名、未知权限或 `accounts` 权限均失败。
 - GET/POST/PUT 账号 API 任何响应和日志都不包含明文密码或 `password_hash`。
- 权限、密码、启停更新各自会递增 `token_version`；同一次请求修改多项只递增一次；仅改展示名不递增。
+- Tab 权限、独立操作权限、密码、启停更新各自会递增 `token_version`；同一次请求修改多项只递增一次；仅改展示名不递增。
 - member 被停用、改密或改权限后，旧 JWT 下一次请求返回 401；重新登录后获得实时权限。
 - API-to-Tab 矩阵逐路由覆盖 `modules/admin.rs`，每条路由至少测试 owner 成功、具备权限的 member 成功、缺权限 member 返回 403。
 - 两个共享读取接口分别覆盖每个允许 permission 的成功用例，以及无关 permission 的 403 用例。
- owner-only 账号 API 对任意 member 都返回 403，即使其 `permissions_json` 被污染为包含 `accounts`。
+- 历史花费手动对账对仅持有任意 Tab 的 member 返回 403；只持有独立操作权限时允许调用；全量投影初始化始终 owner-only。
+- owner-only 账号 API 对任意 member 都返回 403，即使其 Tab 或独立权限 JSON 被污染为包含 `accounts`。

 ### 14.2 前端

 - owner 看到 15 个业务 Tab 和账号管理；member 只看到被分配的业务 Tab。
- 每个一级 Tab 内的二级 Tab、弹窗和写操作继承一级权限并正常使用，不出现“页面可见但内部 API 403”的错误映射。
+- 常规二级 Tab、弹窗和写操作继承一级权限；历史花费对账按钮只在用户详情返回 `canReconcileConsumption=true` 时显示。
 - 直接输入无权限 hash 自动替换为第一可访问项，不短暂挂载无权限页面。
 - 当前 Tab 权限被 owner 收回后，下一请求触发重新登录；新会话恢复后落到第一可访问项。
 - 零权限 member 登录后显示空态，不回落 Dashboard、不发送 Dashboard 或其它业务请求，并可正常退出。
@@ -207,7 +207,7 @@ controller 配置：

 透明背景处理正常成功时，角色形象、图标 spritesheet 和 UI 素材提取的画布都同时放透明主结果与 provider 原图：透明主结果保持生成器 `generatedLayerId` 主锚点，provider 原图作为第二个图层放在其右侧；图标和 UI 实际拆分出的业务素材从 provider 原图右侧继续排列。

-inline 与 external v1 成功响应继续使用结构化 `warning.code/reason`；图标 / UI 的透明图已经成功、只有自动拆分失败时，继续返回结构化 `sliceWarning.code/reason`，其中 `sliceWarning.reason` 保留原始诊断。queue worker 把两类告警归一为有界的 `result_payload_json.warning`：通用 `warning` 优先并原样保留完整 `reason`；只有不存在通用 `warning` 时，才给 `sliceWarning.reason` 添加“图集已生成，但自动拆分未完成：”前缀。任务摘要将该展示就绪的 `reason` 原样提取到 `warning_message`，单 job 状态和刷新后的任务列表 BFF 再以 `warning: string` 返回；Web 必须直接展示，不再补前缀或按 code 推断类型。历史任务保留写入时的 `reason` 快照，摘要 backfill 不按当前格式重新解释或补写前缀。该字符串语义是 worker / BFF / Web 的内部同版本契约，三者必须协调发布，不承诺滚动混部或旧 Web 缓存下的跨版本字符串兼容。
+inline 与 external v1 成功响应继续使用结构化 `warning.code/reason`；图标 / UI 的透明图已经成功、只有自动拆分失败时，继续返回结构化 `sliceWarning.code/reason`，其中 `sliceWarning.reason` 保留原始诊断。queue worker 把两类告警归一为有界的 `result_payload_json.warning`：只有一条时原样保留完整 `reason`；两条并存时按“通用在前、拆分在后”拼接，`code` 收敛为 `multiple-generation-warnings`（两条 `code` 相同则沿用原 `code`），任何一条都不得被丢弃。`sliceWarning.reason` 无论是否与通用告警并存都由 worker 添加“图集已生成，但自动拆分未完成：”前缀，拼接结果最后统一做长度上界收敛。任务摘要将该展示就绪的 `reason` 原样提取到 `warning_message`，单 job 状态和刷新后的任务列表 BFF 再以 `warning: string` 返回；Web 必须直接展示，不再补前缀或按 code 推断类型。历史任务保留写入时的 `reason` 快照，摘要 backfill 不按当前格式重新解释或补写前缀。该字符串语义是 worker / BFF / Web 的内部同版本契约，三者必须协调发布，不承诺滚动混部或旧 Web 缓存下的跨版本字符串兼容。

 ## 验收

@@ -59,7 +59,7 @@
 - SpacetimeDB schema guard 比较当前工作树与基线提交时，两侧都必须分别读取各自 `Cargo.toml` 的 `lib.path`，再沿 `mod` / `#[path]` 只扫描该快照 crate root 可达的 schema；不得递归扫描整个 `src/`，否则原位保留的旧源码会与现役历史数据壳产生假 accessor 重复。
 - `module-runtime` 仍是账号、钱包、公共设置、追踪和 feature gate 的现役领域 crate；其混合源码中的 `CreationEntry*`、旧公开作品、旧存档 / 浏览历史 / 游玩统计 DTO、command、mapper 和规则必须以编译条件退出，且不再依赖只为旧创作契约存在的 `shared-contracts`。历史 schema 只继续编译 `RuntimeBrowseHistoryThemeMode` 六个变体和完整保序的 `RuntimeProfileWalletLedgerSourceType` 等持久化 ABI，不保留围绕这些类型的旧业务实现。
 - 纯模板 crate 和专属运行态 crate 不属于 workspace members、default members 或任何在运 crate 的依赖图；源码目录保持原样。
- `platform-agent` 及其专属 `langchainrust` 依赖同样退出 workspace 与 `api-server` 依赖图；现役编辑器 Agent 仅需的模型常量收口到 `platform-llm`，不再通过旧拼图 Phase 1 / Creative Agent 执行器 crate 复用。
+- `platform-agent` 及其专属 `langchainrust` 依赖同样退出 workspace 与 `api-server` 依赖图；现役编辑器 Agent 仅需的模型常量收口到 `platform-llm`，不再通过旧拼图 Phase 1 / Creative Agent 执行器 crate 复用。后续抽出的 `platform-agent-harness` 是无旧玩法依赖的通用 JSON function-calling 底座，不得依赖、复用或重新挂回本条退役 crate。
 - `platform-auth` 不再编译 runtime guest token；`platform-wechat` 不再编译旧生成结果订阅服务，只保留现役认证和支付协议。

 ## 验收
@@ -42,7 +42,14 @@ v1 只开放以下能力：
 - `POST /api/external/v1/editor/audios/background-music/generations`：生成编辑器背景音乐素材。
 - `GET /api/external/v1/openapi.json`：导出本版本 OpenAPI 3.1 JSON。

-角色图生成、图标 spritesheet 和 UI 素材提取的 2xx 成功响应可携带可选结构化 `warning { code, reason }`，当前稳定 `code` 为 `postprocess-failed-source-preserved`。provider 原图已保存但透明背景处理最终失败时，接口返回原图，不返回不存在的透明处理图，图标和 UI 也不继续拆分；有 `projectId + canvasCompletion` 时由原图完成画布写回，无画布上下文时只返回原图及实际存在的资源 / 素材快照。调用方应展示 warning，但不得把任务改判为失败。该降级只覆盖透明背景处理的最终失败，phase 上报、原图或透明处理图持久化、画布写回失败仍返回错误。图标 / UI 已成功生成透明图、只有自动拆分失败时继续使用既有 `sliceWarning`；服务端保证通用 `warning` 与 `sliceWarning` 互斥，防御性客户端若收到异常双字段响应仍以通用 `warning` 为准。
+图片生成、图标 spritesheet 和 UI 素材提取的 2xx 成功响应可携带可选结构化 `warning { code, reason }`。外部 OpenAPI 当前公开四个稳定 `code`：
+
+- `postprocess-failed-source-preserved`：生成成功，但透明处理、像素规整等后处理未完成，接口保留仍可使用的原图或进入该步骤前的结果。
+- `dimension-restore-fallback`：provider 回图无法安全收口到目标交付尺寸，接口保留实际回图尺寸。
+- `unsupported-image-style`：请求的图片后处理风格未知或不适用于当前生成类型，接口按无风格继续生成。
+- `multiple-generation-warnings`：同一成功响应合并了不同 `code` 的多条非阻断告警，具体原因按顺序拼接在 `reason`。
+
+provider 原图已保存但透明背景处理最终失败时，接口返回原图，不返回不存在的透明处理图，图标和 UI 也不继续拆分；有 `projectId + canvasCompletion` 时由原图完成画布写回，无画布上下文时只返回原图及实际存在的资源 / 素材快照。调用方应展示 `warning.reason`，但不得把任务改判为失败。该降级只覆盖透明背景处理的最终失败，phase 上报、原图或透明处理图持久化、画布写回失败仍返回错误。图标 / UI 已成功生成透明图、只有自动拆分失败时继续使用既有 `sliceWarning`。通用 `warning` 与 `sliceWarning` 只在「透明背景最终失败」这一条上互斥（该情况不会进入拆分）；风格归一化或像素规整产生的通用 `warning` 可以与 `sliceWarning` 并存，调用方必须同时展示两者，不得只取其一。

 管理 API Key 的登录态接口保留在站内个人中心链路，但不写入外部 OpenAPI JSON：

@@ -92,6 +92,8 @@ BgFilter 对已经落入私有 OSS 的生成原图、动作抽取帧和手动去

 Full Job 通过 `EXIT_MAINTENANCE_MODE_AFTER_COMPLETION` 明确选择完整发布成功后是否退出维护，默认勾选以保持历史行为。Full 对 Stdb Publish 和 API Deploy 两个下游阶段都固定传 `KEEP_MAINTENANCE_MODE=true`，让 maintenance marker 持续覆盖 Stdb → API → Web 整段发布；Web Deploy 成功后才进入独立 `Exit Maintenance` 阶段。该阶段只能通过 `agent none` 和显式 `node(...)` 分配目标机，直接执行 `/opt/genarrative/current/scripts/deploy/maintenance-off.sh`；目标机不得 checkout Git、挂载 Git SSH 凭据或依赖 Jenkins workspace 源码。取消勾选时跳过最终退出阶段，便于内网验收完成后人工恢复公网。`Genarrative-Api-Deploy` 也单独暴露 `KEEP_MAINTENANCE_MODE` 参数，并转换为随发布包脚本的 `--keep-maintenance-mode`；失败路径仍按既有 current 切换边界保留或退出维护，不受成功态选项覆盖。外部生成 queue 的 `warning` 由 API/worker 固化为可直接展示的完整文案，Web 不再补前缀，因此 API/worker 与 Web 必须在同一维护窗口按同一版本协调发布；分开运行 Job 时先保持维护态完成 API/worker，再发布 Web，二者完成后才能恢复公网，不得在公网可用期间只滚动其中一侧。

+维护门禁启用时，Nginx 与 Pingora 只精确放行默认维护页依赖的 `/branding/taonier-maintenance-page.png` 和 `/branding/taonier-product-ip.png`；不得放开整个 `/branding/`、`/assets/` 或后台静态目录。公网验收除主站、后台和 API 继续返回维护响应外，还必须确认这两个品牌图片返回 `200 image/png`，避免维护页 HTML 正常但背景图请求被再次改写成 `503`。
+
 需要验证“更新 API 不停 worker”和“worker 是否持续消费队列”时，优先使用隔离容器 smoke：`npm run container:worker-smoke -- smoke`。该脚本生成 gitignored 的 `deploy/container/worker-smoke/api-server.env`，启动独立 compose project 与独立 SpacetimeDB，发布当前 `spacetime-module` 后写入 `source_module = editor-canvas`、`job_kind = worker_smoke_unsupported` 的测试 job；预期 worker claim 后执行 unsupported 失败分支，再执行 API-only recreate 并确认 worker 容器 ID 不变，最后再次入队验证 API 更新后队列仍可消费。`external_generation_job` 是 private table，脚本通过 worker 日志确认 job_id 被消费，不用 CLI SQL 查询私表。该 smoke 不读取 `.env.local`，也不依赖真实 VectorEngine / OSS 密钥；真实生图链路联调再在本地私有 env 中补齐 provider 配置。worker-smoke 默认把本机 `spacetime` CLI 打成轻量 SpacetimeDB 镜像，避免本机首次 smoke 依赖官方大镜像下载。若容器内 Cargo 拉取 crates.io 依赖不稳定，可用 `npm run container:worker-smoke -- smoke --local-binary` 让容器内 Cargo 复用本机 Cargo 缓存构建当前二进制，再打入 Debian bookworm smoke runtime 临时镜像；可用 `GENARRATIVE_WORKER_SMOKE_LOCAL_BASE_IMAGE` 覆盖运行时基础镜像；若隔离端口或库数据需要重建，追加 `--force`。完成 queue 链路验证时，用队列概览 BFF、单 job 状态接口和 worker 日志确认任务从 queued/running 收敛到预期失败态。

 本地只做账号/UI smoke 且需要短信登录时，`SMS_AUTH_PROVIDER` 应显式设为 `mock`，并把 `SMS_AUTH_MOCK_VERIFY_CODE` 设为固定值（当前常用 `123456`），再重启 `npm run dev` 或 `npm run dev:api-server`。如果 `.env.local` 还保留 `SMS_AUTH_PROVIDER=aliyun`，`POST /api/auth/phone/login` 用 mock 验证码会稳定报“验证码错误”，不是前端表单问题。真实短信联调再切回 `aliyun` 并重启。
@@ -143,7 +145,17 @@ spacetime sql <database> "SELECT * FROM profile_recharge_refund_bill_checkpoint"

 核对规则：部分退款时原订单保持 `paid`；累计退款等于订单金额后才为 `refunded`，但 `paid_at` 继续保留，因此不会恢复首充资格。泥点退款只回收普通永久泥点；每日免费泥点和会员周期泥点不动。永久泥点不足时 `recovery_status=shortfall`、`unrecovered_points>0`、`wallet_frozen=true`，正式钱包消费在欠款清零前 fail-closed；会员订单统一为 `manual_review`，不得自动缩短有效期或扣周期泥点。

-后台充值订单退款必须通过管理员鉴权接口执行，不得从数据库页面直接改表：列表 `GET /admin/api/profile/recharge-orders`、用户详情 `GET /admin/api/profile/users/detail`、预检 `POST /admin/api/profile/recharge-refunds/preview`、执行 `POST /admin/api/profile/recharge-refunds/execute`、应急退款号登记 `POST /admin/api/profile/recharge-refunds/register`、人工冻结/解冻 `POST /admin/api/profile/wallet-restriction`。预检返回微信支付状态、本地累计退款、剩余可退金额、预计追回泥点、钱包总额、可消费余额、活动占用和退款欠账；只有预检允许且二次确认后才提交退款。提交使用稳定 `requestId`，接口超时后重试必须复用同一值。若返回“退款处理中”，先查同一 `out_refund_no`，不要换号再次发起。商户平台应急退款完成后，在后台登记原 `out_refund_no` 触发验签查单；微信已退款但缺少退款号时等待 T+1 账单，不得凭截图或支付订单 `REFUND` 状态直接手写退款事实。
+后台充值订单退款必须通过管理员鉴权接口执行，不得从数据库页面直接改表：列表 `GET /admin/api/profile/recharge-orders`、用户详情 `GET /admin/api/profile/users/detail`、历史花费手动对账 `POST /admin/api/profile/users/reconcile-consumption`、存量消费投影初始化 `POST /admin/api/profile/users/initialize-consumption-projections`、预检 `POST /admin/api/profile/recharge-refunds/preview`、执行 `POST /admin/api/profile/recharge-refunds/execute`、应急退款号登记 `POST /admin/api/profile/recharge-refunds/register`、人工冻结/解冻 `POST /admin/api/profile/wallet-restriction`。用户详情返回的 `historicalConsumedPoints` 来自 `profile_wallet_consumption_total`，表示退款不冲减的历史总消费；已有投影的正常消费只做按主键 O(1) 原子累加，缺行时按该用户钱包流水索引兜底重建一次，不得用只返回最近 50 条的钱包流水列表在 BFF 或前端重算。手动对账是独立操作权限：owner 始终拥有，member 必须在账号管理中单独勾选“手动对账用户历史花费”，任意 Tab 权限都不隐式授予；接口经二次确认后才扫描该用户全部权威流水、校准投影并记录管理员和时间。投影初始化接口只允许 owner，必须在首次上线的停写维护窗口执行并成功后再恢复业务流量；它扫描全部权威钱包流水并初始化或校准全部消费投影。维护遗漏的存量缺行仍由用户详情首次读取按用户索引兜底回填。预检返回微信支付状态、本地累计退款、剩余可退金额、预计追回泥点、钱包总额、可消费余额、活动占用和退款欠账；只有预检允许且二次确认后才提交退款。提交使用稳定 `requestId`，接口超时后重试必须复用同一值。若返回“退款处理中”，先查同一 `out_refund_no`，不要换号再次发起。商户平台应急退款完成后，在后台登记原 `out_refund_no` 触发验签查单；微信已退款但缺少退款号时等待 T+1 账单，不得凭截图或支付订单 `REFUND` 状态直接手写退款事实。
+
+首次发布消费投影时，先停止业务写入并确认 api-server 与新 SpacetimeDB module 已就绪，再使用当前 owner 登录获得的短期 token 执行：
+
+```bash
+curl -fsS -X POST \
+  -H "Authorization: Bearer ${ADMIN_BEARER_TOKEN}" \
+  "https://<API 域名>/admin/api/profile/users/initialize-consumption-projections"
+```
+
+响应中的 `scannedLedgerCount` 是扫描流水数，`projectedUserCount` 是已存在钱包流水并完成投影的用户数；只有请求成功且返回 `ok=true` 后才恢复业务流量。该接口允许幂等重跑，但每次都会全表扫描，只能在维护窗口由 owner 执行，不得加入普通定时任务或页面自动请求。

 正式落账上线前已经被旧 debug handler 返回成功的退款回调不会因部署新版本自动重放。已知 `out_refund_no` 的历史退款应由具备真实商户凭据的受控服务端操作先调用单笔退款查询，验签后写入同一 observation 事务；未知的商户平台退款等待次日交易账单发现。自动账单按分片补扫微信 API 可查询的近 90 天，超出窗口的历史退款需从商户平台导出核对后逐笔受控查单补录，不能直接把商户平台截图或 CSV 行当作退款终态，也不能开放匿名或普通用户补录 / 退款入口。

@@ -213,9 +225,9 @@ npm run check
 仓库级 Gitea Actions 工作流固定为 `.gitea/workflows/project-ci.yml`，在向 `master` 或 `codex/ai-game-creator-app` 推送、创建或更新 PR，以及手工触发时运行。工作流拆成四个必须通过的 job：

 - `Repository checks`：执行 `npm run lint`、主站与后台生产构建、内容数据检查和提交差异空白检查。
- `Frontend tests`：独立执行根 `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` 收集规则。
+- `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`：执行 `npm run check:server-rs-ddd`、`cargo test --locked --workspace --no-fail-fast`、`api-server --all-targets` 编译和 `spacetime-module` 编译；runner 安装 `ffmpeg`，避免视频抽帧测试因工具缺失提前返回。依赖真实服务或密钥的测试必须显式 `ignored`，不能让普通 PR job访问现场环境。
- `Native shell tests`：独立执行 `npm run check:native-shells`，覆盖微信壳、Expo 和 Tauri 的完整验收，并确认 Tauri `Cargo.lock` 没有被构建过程改写，避免把重型原生壳或依赖锁漂移隐藏在基础检查末尾。`codex/ai-game-creator-app` 分支的同名脚本还会执行 `npm run ai-game-creator-shell:check` 和 AI 游戏创作壳 release build smoke。
+- `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`，不能用并行偶发失败后的逐项通过替代整套稳定门禁。

 四个 job 合起来覆盖根 `npm run check`，并补齐根检查没有包含的 BgFilter worker smoke harness、无密钥生产巡检 / 发布 / 部署行为 fixture、server-rs DDD、正式 workspace Rust 测试与现役后端编译门禁。普通 PR CI 不注入业务密钥，不启动真实 API、SpacetimeDB、OSS、支付、图片生成或生产 live smoke；需要现场环境、可变外部状态、Docker 编排或发布凭据的 `check:*` 继续按对应专题和 Jenkins 发布流程执行，不能遍历所有同名前缀脚本冒充 PR 门禁。

@@ -362,7 +374,7 @@ UI 相关修改要重点验证：
 npm run database:backup:oss -- --data-dir /stdb --stop-service spacetimedb.service --restart-service-after genarrative-api.service --restart-service-after genarrative-external-generation-worker@1.service --restart-service-after genarrative-external-generation-controller.service
 ```

-脚本会将数据目录打包成 `tar.gz`，上传到 `oss://<bucket>/<prefix>/<database>/<database>-<UTC时间>.tar.gz`。生产建议做冷备份：传入 `--stop-service spacetimedb.service`，脚本会在打包前停止服务、打包后恢复服务，再上传 OSS；因 `genarrative-api.service`、`genarrative-external-generation-worker@*.service` 和 `genarrative-external-generation-controller.service` 都依赖 `spacetimedb.service`，生产定时冷备份还必须传入对应的 `--restart-service-after`，确保备份后 API、保底 worker 和 controller 随数据库一起恢复。`2026-06-10` release 故障就是现场 unit 漏掉 API 重启参数，`03:20` 冷备份停止 SpacetimeDB 后 API 被依赖关系一并停止，备份脚本只恢复了 SpacetimeDB，API 直到人工重启前都不可用；`2026-06-24` release 又出现同类依赖停机后只恢复 API、未恢复外部生成 worker/controller，导致图片画布生成任务长期停留在队列中。后续现场变更、provision 模板和 Jenkins 归档都必须通过 `npm run check:production-ops` 防止回退。由于 OSS 上传可能受服务器带宽限制，`Genarrative-Stdb-Module-Publish` 默认使用 `DATABASE_BACKUP_MODE=async`：先在 publish 前用 `--defer-upload` 生成本地冷备份和 `.manifest.json`，随后继续执行 publish；发布脚本退出前会用后台 `node -- ... --upload-archive <tar.gz>` 上传同一份发布前备份，不等待上传完成。`Genarrative-Full-Build-And-Deploy` 必须显式暴露并透传同一个 `DATABASE_BACKUP_MODE`，不得静默使用下游 `async`；release 已有验真冷备且明确禁止再上传时，Full 必须选择 `skip`。发布脚本在校验 wasm 后、执行 `spacetime publish` 前会等待显式 `SPACETIME_SERVER_URL` 的 `/v1/ping` 就绪，默认最多等待 `60` 秒；如生产机器冷备份恢复 `spacetimedb.service` 较慢，可临时设置 `GENARRATIVE_STDB_PUBLISH_READY_TIMEOUT_SECONDS` 调整等待时间。需要强一致发布闸门时改用 `DATABASE_BACKUP_MODE=sync`（等价脚本参数 `--backup-mode sync`），备份会在 publish 前同步打包并上传，失败会阻断 publish；确认已有其他备份窗口时才使用 `DATABASE_BACKUP_MODE=skip`（兼容脚本参数 `--skip-backup`）。若业务不能接受停机窗口，应先规划 SpacetimeDB 原生快照或主备策略，不要直接在写入中的数据目录上做热拷贝并当作强一致备份。
+脚本会将数据目录打包成 `tar.gz`，上传到 `oss://<bucket>/<prefix>/<database>/<database>-<UTC时间>.tar.gz`。生产建议做冷备份：传入 `--stop-service spacetimedb.service`，脚本会在打包前停止服务、打包后恢复服务，再上传 OSS；因 `genarrative-api.service`、`genarrative-external-generation-worker@*.service` 和 `genarrative-external-generation-controller.service` 都依赖 `spacetimedb.service`，生产定时冷备份还必须传入对应的 `--restart-service-after`，确保备份后 API、保底 worker 和 controller 随数据库一起恢复。`2026-06-10` release 故障就是现场 unit 漏掉 API 重启参数，`03:20` 冷备份停止 SpacetimeDB 后 API 被依赖关系一并停止，备份脚本只恢复了 SpacetimeDB，API 直到人工重启前都不可用；`2026-06-24` release 又出现同类依赖停机后只恢复 API、未恢复外部生成 worker/controller，导致图片画布生成任务长期停留在队列中。后续现场变更、provision 模板和 Jenkins 归档都必须通过 `npm run check:production-ops` 防止回退。由于 OSS 上传可能受服务器带宽限制，`Genarrative-Stdb-Module-Publish` 默认使用 `DATABASE_BACKUP_MODE=async`：先在 publish 前用 `--defer-upload` 生成本地冷备份和 `.manifest.json`，随后继续执行 publish；发布脚本退出前会用独立 `systemd-run` transient service 执行 `--upload-deferred-dir <backup-dir>`，串行补传该目录内同库的 `deferred/pending` 归档，不依赖 Jenkins 作业进程树存活。任一归档只有在 OSS archive、manifest 和 baseline state 全部上传并验真后，才按 `keep-local` 规则删除；失败归档保留原 manifest，由下次 publish 重试。`Genarrative-Full-Build-And-Deploy` 必须显式暴露并透传同一个 `DATABASE_BACKUP_MODE`，不得静默使用下游 `async`；release 已有验真冷备且明确禁止再上传时，Full 必须选择 `skip`。发布脚本在校验 wasm 后、执行 `spacetime publish` 前会等待显式 `SPACETIME_SERVER_URL` 的 `/v1/ping` 就绪，默认最多等待 `60` 秒；如生产机器冷备份恢复 `spacetimedb.service` 较慢，可临时设置 `GENARRATIVE_STDB_PUBLISH_READY_TIMEOUT_SECONDS` 调整等待时间。需要强一致发布闸门时改用 `DATABASE_BACKUP_MODE=sync`（等价脚本参数 `--backup-mode sync`），备份会在 publish 前同步打包并上传，失败会阻断 publish；确认已有其他备份窗口时才使用 `DATABASE_BACKUP_MODE=skip`（兼容脚本参数 `--skip-backup`）。若业务不能接受停机窗口，应先规划 SpacetimeDB 原生快照或主备策略，不要直接在写入中的数据目录上做热拷贝并当作强一致备份。

 生产环境变量模板在 `deploy/env/api-server.env.example`：

@@ -398,6 +410,8 @@ files full 会递归扫描 data-dir，保留空目录、每个普通文件的相

 history 的安全边界按每个 replica 独立计算。设最新完整且未锁定的 snapshot offset 为 `S`；数字更大但缺少同 offset `.snapshot_bsatn`、仍存在同名 `.lock` 的目录不能参与边界计算。脚本必须保留起始 offset 小于等于 `S` 的最后一个 commitlog segment，以及它之后的全部 segment；只处理更早的 `.stdb.log` / `.stdb.ofs`，snapshot 只处理最新目录之前的旧目录。files history 会递归展开候选目录，逐对象复用或上传，随后依次验真候选对象、history catalog 与 full baseline catalog，再重新扫描边界和 stat fingerprint，最后覆盖发布并验真 `latest.json`；任何一步失败都不推进 state 或删除源文件。脚本在 work-dir 使用 PID lock 拒绝同库并发上传，SSH 超时后必须先检查原进程，不能直接重跑。

+files 本地续跑 state 使用 `<database>-files-state.json.gz` v2：只保存 full/history catalog 的 object key、长度、SHA 与验真时间，不再重复嵌入每份 catalog 的完整 `files` / `symlinks` 清单。旧 v1 `.json` 仍可读取，并且只在一次非 dry-run 备份的 OSS catalog、`latest.json` 与本地新 state 全部成功后原子迁移为 gzip v2，再删除旧 state；gzip 已存在但损坏时必须失败，不能回退到可能过期的旧 JSON。成功运行后，本地只压缩保留 latest full catalog 作为 full 增量复用缓存，已上传并验真的 history catalog、旧 full catalog、失败或 dry-run 遗留 catalog 自动清理；OSS catalog、CAS 对象与 `latest.json` 不删除、不改 schema。`--result-file` 只写 catalog 引用和计数，不再复制完整文件清单。metadata 压缩或清理失败时不得继续删除 `/stdb` history 源文件。
+
 ```bash
 # 从停库目录或已验证冻结副本建立逐文件完整基线；相同 work-dir 重跑只传变化内容。
 node -- scripts/database-backup-to-oss.mjs \
@@ -431,7 +445,7 @@ node -- scripts/database-backup-to-oss.mjs \

 dev 出口过慢时，可以把冻结基线经内网 rsync 到 release 独立 staging，再由 release 上传 dev bucket。staging 必须位于 `/var/lib/genarrative/dev-database-backup-staging/` 一类隔离目录，命令显式传 staging `--data-dir`、独立 `--work-dir`、dev `--bucket`，且不得传 `--stop-service`；禁止指向或修改 release `/stdb`。中转 key 只为本次传输临时授权，结束后从 dev 私钥和 release `authorized_keys` 同时移除。上传完成后把整个 files work-dir/state 回传 dev，history 才能延续同一 baseline catalog。

-完整恢复默认从 OSS 固定 `latest.json` 读取最新 full catalog：先创建 `directories`，再把每个 `files[].objectKey` 下载到 `<restore-root>/<files[].path>` 并逐项核对 `sizeBytes` / `sha256`；history catalog 用于证明已清理历史仍有 OSS 对象，不需要把已被 full baseline 覆盖的旧文件叠回当前恢复目录。本地 state 仍可作为兼容入口，但不再是异机恢复的前置条件。随后用隔离 data-dir 启动同版本 standalone，验证 `/v1/ping`、日志中的 snapshot restore / commitlog replay / module launch、代表性 SQL 和 reducer。dev 已完成这轮 OSS-only 异机恢复与重启演练；当前 live release 仍保持 `archive-full`，需要切换时先为 release 建立并恢复验证独立 full baseline，再通过 Server-Provision 显式选择 `files-history`，无需修改代码或解除额外硬门禁。
+完整恢复默认从 OSS 固定 `latest.json` 读取最新 full catalog：先创建 `directories`，再把每个 `files[].objectKey` 下载到 `<restore-root>/<files[].path>` 并逐项核对 `sizeBytes` / `sha256`；history catalog 用于证明已清理历史仍有 OSS 对象，不需要把已被 full baseline 覆盖的旧文件叠回当前恢复目录。本地 state 仍可作为兼容入口，并同时支持旧 v1 JSON 与 v2 gzip，但不再是异机恢复的前置条件。随后用隔离 data-dir 启动同版本 standalone，验证 `/v1/ping`、日志中的 snapshot restore / commitlog replay / module launch、代表性 SQL 和 reducer。dev 已完成这轮 OSS-only 异机恢复与重启演练；release 已使用独立 `/var/lib/genarrative/database-backups/release-files` full baseline 和 `files-history` profile，现场最终 `ExecStart`、timer 状态与最近备份结果仍须在变更时重新核对。

 ```bash
 node -- scripts/database-backup-to-oss.mjs \
@@ -690,6 +704,27 @@ OpenTelemetry 现阶段默认开启 OTLP traces / metrics / logs，但本地日

 旧结构化创作 / RPG 的 Responses `web_search` 开关已退出 api-server 配置；部署环境不再保留 `GENARRATIVE_RPG_LLM_WEB_SEARCH_ENABLED` 或 `GENARRATIVE_CREATION_AGENT_LLM_WEB_SEARCH_ENABLED`。

+`platform-llm` 请求默认使用 Responses 协议；需要接旧 OpenAI Chat Completions 兼容网关时，调用方必须显式选择 Chat Completions。三种协议（`openai_chat`、`openai_responses`、`anthropic`）都使用原生 function tools，并统一从最终 `LlmRunResponse.tool_calls` 读取工具调用；流式 `on_delta` 只发送文本，不能把工具参数当作文本增量转发。Anthropic 工具请求使用 `input_schema`，`Required` 使用对象形态 `{ "type": "any" }`；Anthropic 当前不支持 `web_search`、图片内容和纯 system 消息。AI 游戏创作独立 App 是客户端，不读取 `.env`；发布 App 启动时会在 Tauri 应用配置目录生成 `game-creator.config.json`，主窗口“配置”面板读写该运行时文件，真实密钥和本机覆盖项写入该文件，仓库内 `apps/ai-game-creator-shell/game-creator.config.json` 只作为默认模板，开发 CLI 无 AppHandle 时才回退读取仓库旁边的 gitignored 覆盖文件。LLM 维度由 `llm.apiKind` 控制，默认 `openai_responses`，可设为 `openai_chat` 接旧 Chat Completions 兼容网关，或 `anthropic` 接 Anthropic Messages。
+
+流式工具片段按协议 slot 聚合，Responses 允许从 `response.completed` / `response.incomplete` 的 `response.output[]` 恢复只在整体终态事件中携带的工具调用与正文。`response.incomplete` 中的工具调用即使参数是完整 JSON 也返回 `Deserialize`，截断正文则保留为可用的降级结果。收尾时空参数默认 `{}`，非空参数必须是完整 JSON；解析失败、流式工具缺少身份或参数截断属于 `Deserialize`。流式已声明工具调用但没有聚合出工具 slot 属于 `StreamUnavailable`，由调用方决定是否回退非流式；文本和工具调用均为空才是 `EmptyResponse`。
+
+验收证据分为三类：`cargo test -p platform-llm` 的确定性用例验证 checked-in SSE fixture 的 parser 行为；`tests/live_stream_tool_calls.rs` 中默认执行的本地解析测试验证 `PLATFORM_LLM_LIVE_API_KIND` 归一与失败关闭；同文件默认忽略的真实端点用例只做归一后的工具调用 smoke，检查最终工具名、id 和完整参数 JSON，文本增量字符数仅用于打印观测。该 smoke 不录制或逐事件比较原始 SSE，fixture 即使来源于真实抓包也不能据此宣称转录无偏差。
+
+真实端点 smoke 必填 `PLATFORM_LLM_LIVE_BASE_URL`、`PLATFORM_LLM_LIVE_API_KEY` 和 `PLATFORM_LLM_LIVE_MODEL`；`PLATFORM_LLM_LIVE_API_KIND` 可选，取值为 `anthropic` / `openai_chat` / `openai_responses`，省略或仅含空白时默认 `openai_responses`，未知非空值直接失败，避免拼写错误静默测到另一种协议。仓库根目录没有 `Cargo.toml`，必须显式指定 workspace manifest：
+
+```bash
+PLATFORM_LLM_LIVE_BASE_URL=https://api.example.com/anthropic \
+PLATFORM_LLM_LIVE_API_KEY='<从密钥管理处取，勿写入仓库>' \
+PLATFORM_LLM_LIVE_MODEL='<模型名>' \
+PLATFORM_LLM_LIVE_API_KIND=anthropic \
+cargo test -p platform-llm --manifest-path server-rs/Cargo.toml --test live_stream_tool_calls -- --ignored --nocapture
+```
+
+PowerShell 下按测试文件头部示例依次设置三个必填变量，并按需设置 `$env:PLATFORM_LLM_LIVE_API_KIND`，再执行同一条 `cargo test`。切换 `PLATFORM_LLM_LIVE_API_KIND` 逐个跑三种协议，才算覆盖完整；`--nocapture` 会打印解析出的工具名、id、参数和文本增量字符数，便于核对。
+
+该用例只从进程环境变量读取凭据，不读 `.env.secrets.local`，也不会写入任何文件。真实 API Key 一律不得提交进仓库，也不要写进 `docs/`、脚本默认值或测试 fixture；临时密钥用完应在上游及时吊销。
+
+创意 Agent `gpt-5` 文本链路已从 APIMart 切到 VectorEngine：`api-server` 读取 `VECTOR_ENGINE_BASE_URL` / `VECTOR_ENGINE_API_KEY` 构造 OpenAI-compatible LLM client，并自动补齐 `/v1` 前缀用于 Responses 协议。排查或切换密钥后，可在本地运行：
 创意 Agent `gpt-5.4-mini` 文本链路已从 APIMart 切到 VectorEngine：`api-server` 读取 `VECTOR_ENGINE_BASE_URL` / `VECTOR_ENGINE_API_KEY` 构造 OpenAI-compatible LLM client，并自动补齐 `/v1` 前缀后请求 `/chat/completions`。通用 `/api/llm/chat/completions` 代理使用 `GENARRATIVE_LLM_PROVIDER=openai-compatible`、`GENARRATIVE_LLM_BASE_URL=https://api.vectorengine.cn/v1`、`GENARRATIVE_LLM_MODEL=gpt-5.4-mini`，未单独配置 `GENARRATIVE_LLM_API_KEY` 时可复用 `VECTOR_ENGINE_API_KEY`。排查或切换密钥后，可在本地运行：

 ```bash
@@ -732,6 +767,8 @@ cargo test -p platform-auth --manifest-path server-rs/Cargo.toml aliyun_send_sms
 - `profile_wallet_ledger`
 - `profile_wallet_config`

+后台“账号配置”通过 `GET/POST /admin/api/profile/wallet-config` 一次读写账号初始泥点数和每日免费泥点数。修改每日免费额度不重算已初始化的当日余额；尚未初始化的当日额度或下一次北京时间跨日重置使用最新配置。
+
 个人任务首版 scope 仅支持 `user`。每日登录任务按北京时间自然日 0 点重置；用户已登录并停留在“我的”页跨日时，前端需要先非阻断调用 refresh session 以写入新业务日 `daily_login`，再请求 `/api/profile/tasks` 刷新任务中心。认证成功后的 `daily_login` 必须通过 `SpacetimeClient::record_daily_login_tracking_event(...)` 调用 SpacetimeDB 专用 `record_daily_login_tracking_event_and_return` procedure，由数据库事务时间生成当日幂等事件并推进任务进度；不要改回普通 `record_tracking_event_after_success`、tracking outbox 或旧 `profile.login.daily` 事件键。后台、RPG、大鱼吃小鱼、Visual Novel、Story、Combat 等特定链路按 tracking 中间件排除规则处理；作品游玩统一使用 `work_play_start`。

 外部 API 失败审计复用 `tracking_event`，不新增表。普通 API / external-generation 调用的失败事件优先写入本机 tracking outbox，再由后台 worker 批量落库；如果 outbox 因权限、磁盘或保护阈值不可写，仍回退同步直写 SpacetimeDB。BgFilter worker 是受限资源例外：provider 失败审计在 spawn 前受进程级 `1024` 硬上限保护，获准任务写入 `GENARRATIVE_TRACKING_OUTBOX_DIR/bgfilter-worker/` 独立目录；任务满载、outbox 缺失、达到保护阈值或写盘失败时直接丢弃并记录指标，不同步直写。`metadata_json` 包含 endpoint、operation、failureStage、statusCode、statusClass、timeout、retryable、errorMessage、errorSource、latencyMs、promptChars、referenceImageCount、imageModel、rawExcerpt、userId、profileId 和 requestId；其中 `userId` 是触发生成的用户，`profileId` 是调用方传入的草稿 / 作品 / 场景作用域，`requestId` 用于回查同一次 HTTP 请求日志，入口拿不到上下文时允许为空。常用查询：
@@ -115,7 +115,7 @@ V3 退款入口在正式落账的同时保留可用于真实联调的安全诊
 4. 已经发生的外部退款没有 hold 时沿用现有结算：回收当前未被其他 hold 占用的永久泥点，余额不足部分继续以 `profile_recharge_order_refund_settlement.unrecovered_points` 作为唯一退款欠账真相，状态为 `shortfall` 并限制消费。后续永久泥点到账后在同一钱包事务内按最早退款单自动继续追回；每日免费和会员周期泥点不参与。不得再建一张平行 debt 表重复累计欠账。
 5. 人工钱包冻结单独使用 `profile_wallet_manual_restriction`，保存当前是否冻结、原因、操作管理员和操作时间。普通消费同时检查人工冻结、退款欠账和活动 hold；解除人工冻结不能解除仍存在的退款欠账。
 6. 后台 API 统一位于管理员鉴权下：充值订单列表与详情、用户详情、退款预检、退款执行、应急 `out_refund_no` 登记、钱包人工冻结/解冻。任何接口都不得返回原始手机号、商户私钥、APIv3 Key、微信签名、回调密文或账单下载 URL。
-7. 通用用户详情通过内部 `user_id` 或陶泥号解析同一认证用户，展示头像、昵称、陶泥号、内部 ID、脱敏手机号、登录/微信绑定状态、钱包总额、可消费余额、活动占用、退款欠账、冻结原因和最近充值订单。后台语义明确的用户 ID 或陶泥号旁统一使用图标按钮打开同一个弹窗，不复制页面级用户查询逻辑。
+7. 通用用户详情通过内部 `user_id` 或陶泥号解析同一认证用户，展示头像、昵称、陶泥号、内部 ID、脱敏手机号、登录/微信绑定状态、钱包总额、可消费余额、活动占用、退款欠账、历史花费、冻结原因和最近充值订单。历史花费读取 `profile_wallet_consumption_total`：首次上线在停写维护窗口由 owner 全量初始化存量投影，已有投影的消费落账按主键 O(1) 原子累加，退款不冲减；维护遗漏或新用户缺行时，在首次消费或详情读取中按用户全部流水兜底回填一次。不得用最近 50 条账单列表近似。手动对账不继承任意 Tab，member 必须单独持有 `profile-wallet-consumption-reconcile` 操作权限；无权限时用户详情不展示对账按钮。后台语义明确的用户 ID 或陶泥号旁统一使用图标按钮打开同一个弹窗，不复制页面级用户查询逻辑。

 真实联调时显式开启该模块的 debug 日志：

@@ -45,7 +45,7 @@ layer 只表达“某个资源怎样放在画布上”。`src / prompt / actualP

 所有用户布局写入必须携带读取快照时获得的 `expectedRevision`。procedure 在事务中校验 canvas 当前 revision；不一致返回 `409`，前端应重载后端最新快照，不能只换上新 revision 就原样重放冲突前的整包布局。

-前端保存队列只对无 HTTP 响应的传输失败以及 `408 / 425 / 429 / 502 / 503 / 504` 做有界退避重试，`400 / 403 / 404 / 413` 等确定性错误不重复提交。若旧请求执行期间已有更新布局排队，旧请求失败后必须继续发送最新布局；`409` 后权威快照暂时加载失败时保留 pending save 并定时重新进入冲突恢复，不能等待用户再次拖动画布才恢复保存。
+前端保存队列只对无 HTTP 响应的传输失败以及 `408 / 425 / 429 / 502 / 503 / 504` 做有界退避重试，`400 / 403 / 404 / 413` 等确定性错误不重复提交。若旧请求执行期间已有更新布局排队，旧请求失败后必须继续发送最新布局；`409` 后冲突布局立即作废，权威快照暂时加载失败时保留冲突恢复状态并定时只重试 GET，不能把旧布局换上新 revision 后重放，也不能等待用户再次拖动画布才恢复。

 本次结构化 V1 先保留旧 `{ viewport, layers }` PATCH 作为兼容输入。legacy canvas 即使携带 `expectedRevision` 也只做 CAS legacy 保存，不允许用户写入绕过 migration operator 直接激活 structured；只有已完成 backfill / activate、且 active 迁移记录的 revision / hash / 数量 / 资源引用校验均通过时，后端才在单个事务内把兼容输入拆成 layer / dialog 行并递增一次 revision。旧无 CAS procedure 不得写 structured canvas。V1 快照从 typed 列重组，`item_json / dialog_json` 只保留最大 512 KiB 的未结构化扩展字段。自包含本地图片序列在 active canvas 中只能继续保存已回填且 `layerId / resourceId / sourceType / item_json` 语义完全一致的原行；允许修改几何、层级、分组、显隐等 typed 布局字段。前端序列化按正常资源真相边界省略 `assetKind / generationInputs` 时，后端只从既有结构化行恢复这两个冻结字段再校验；显式修改仍拒绝。active 路径不再经过 legacy 元数据清洗，拒绝新增缺资源序列或改写既有帧、预览、prompt 和生成扩展。后续将新增、移动、缩放、删除、重排和分组收窄为有界 batch mutation；在此之前 2 MiB 仍是兼容整包入口的上限。

@@ -66,6 +66,7 @@
 - 底边栏中会在上方弹出二级选项的入口不再依赖点击展开。鼠标悬停到入口即可打开二级面板，鼠标离开入口和二级面板后自动收起；当前范围包括 `生成规范` 和 `生成音乐`。
 - 底边栏二级选项面板必须锚定到对应入口按钮本身，不使用屏幕居中或固定底部偏移；移动端窄屏下也应保持跟随入口位置。
 - 生成图片和生成视频文本输入框紧贴参考图下方，取消旧网格预留导致的空白高度。
+- 在生成类面板或独立修改弹窗的文本输入框内滚动时，滚轮只用于输入内容或面板自身，不得冒泡平移或缩放画布；
 - 生成规范类图片固定使用 `16:9·2K · gpt-image-2`。这三个参数在面板底部沿用可编辑参数按钮的胶囊样式展示，但控件保持禁用不可点击，不提供比例、尺寸或模型修改入口。
 - 宣发素材的 `游戏首图`、`详情五图`、`运营海报` 固定使用 `gpt-image-2`。面板底部只显示禁用态 `gpt-image-2` 模型胶囊和生成按钮，不出现 `nanobanana2` 选项；后端收到 `publication-material` 旧请求时也必须强制归一为 `gpt-image-2`。
 - 图片快速编辑保留一个提示词输入框，并展示与常规图片生成一致的比例 / 尺寸和模型选择；提示词 placeholder 为 `你希望素材如何修改？`，提交按钮显示 `修改`，不展示额外参考图控件。打开面板时优先继承原图关联生成器记录的模型、比例和尺寸；没有关联生成器时使用图层模型，并按原图真实分辨率推导比例和尺寸；模型缺失或已不受支持时回落到当前默认图片模型。切换模型后只展示该模型支持的参数，不兼容的当前值回落到该模型默认值，按钮泥点按选定模型和尺寸同步刷新。提交时必须同时传递 `model / aspectRatio / imageSize`；后端按模型选择 provider 协议：`nanobanana2` 使用 `generateContent + inline_data`，`gpt-image-2` 使用 `/v1/images/edits` multipart，不能把 nanobanana 模型 ID 发往 GPT edits 端点。
@@ -96,7 +97,7 @@
 - 生成中的占位图允许通过键盘 `Delete` / `Backspace` 删除；不额外增加画布上的可见删除按钮。用户删除后，后续异步成功或失败回写不得重新创建该生成对象。
 - 待生成占位的空白样式按生成类型区分：视频使用视频图标和视频角标，角色形象使用角色图标和角色角标，角色动作使用角色动作图标和动作角标，音效使用音效图标和音效角标，背景音乐使用音乐图标和背景音乐角标。
 - 待生成占位的图标语义必须与底部入口或触发入口保持一致：生成图片用图片图标，生成规范用规范图标，生成角色形象用角色图标，生成图标素材用图标网格，生成 UI 设计图用应用窗口，宣发素材用宣发图标，快速编辑用闪光图标，不能默认全部回退为图片图标。
- 图片类待生成占位尺寸必须与面板当前比例和尺寸同步：普通图片、角色形象、图标素材、UI 设计图按当前 `aspectRatio + imageSize` 计算像素尺寸；生成规范固定为 `16:9·2K`，占位为 `2048 x 1152`；宣发素材按 workflow 输出尺寸创建占位。
+- 图片类待生成占位尺寸必须与面板当前比例和尺寸同步：普通图片、角色形象、图标素材、UI 设计图按当前 `aspectRatio + imageSize` 的统一业务像素矩阵计算；所有共用规格都不因模型不同改变画布占地，例如 `nanobanana2` 与 `gpt-image-2` 的 `16:9·2K` 占位和普通最终结果都为 `2048 x 1152`。provider 请求尺寸可因接口合法值不同，但不得泄漏为正常完成的画布尺寸；回图更大时只允许缩小和轻微裁切，回图低于目标时保留实际像素并告警，禁止放大伪造所选档位；生成规范固定为 `16:9·2K`，占位为 `2048 x 1152`；宣发素材按 workflow 输出尺寸创建占位。
 - 视频待生成占位必须与面板当前比例和清晰度同步：默认 `16:9 · 480p` 为 `854 x 480`，切换比例、`720p` 或 `1080p` 后按比例和清晰度重算偶数宽度；调整参数时保持占位中心点不变。
 - 面板中用户修改比例、尺寸或清晰度后，已有空白待生成占位立即同步更新 `width / height / originalWidth / originalHeight`，且保持中心点不跳动。
 - 快速编辑点击修改后不创建独立 `Quick Edit Generator` 画布生成占位；当前快速编辑面板显示修改中，生成成功后结果直接覆盖源图，失败时保留当前面板并显示错误。用户选定的比例和尺寸是新的业务目标分辨率，覆盖旧的“始终保持源图精确分辨率”约束；替换时更新图层原始分辨率，并保持图层中心位置不跳动。需要新建占位的是生成图片、生成视频、重绘、去背景和角色动作等会产出新图层的入口。
@@ -122,7 +123,8 @@
 - 生成成功后仍保留生成器快照；画布渲染优先用 `generatedLayerId` 锚定到成品图层，不再重复显示灰色占位框。
 - 一次生成任务产生多个可复用产物时，已实际生成的产物都必须由后端登记为项目资源并随同一次完成快照加入画布，不能由前端临时追加。角色形象、图标 spritesheet 和 UI 素材提取在透明背景处理正常成功时同时回填纯色背景原图与透明后处理结果，UI 素材提取继续一并回填拆分成功的素材；`generatedLayerId` 锚定透明后处理主结果，附属产物从主结果右侧开始错开放置。透明背景处理最终失败、但 provider 原图已经持久化时，任务以 `completed + warning` 收口，只把 provider 原图作为唯一主图放入画布，`generatedLayerId` 指向原图，不创建不存在的透明处理图，图标和 UI 也不继续拆分；角色重绘遵循同一规则。该收口只捕获透明背景处理本身的最终失败；phase 上报、provider 原图持久化、透明处理图持久化和 `canvasCompletion` 写回错误仍正常传播，不能被原图降级吞掉。
 - 多产物任务的可恢复中间产物还必须进入账号素材库，未传 `assetFolderId` 时落默认“项目”文件夹，并在抠图、尺寸恢复、抽帧或拆分前完成登记。图片修改保存模型对齐尺寸的原始输出；角色动作把绿幕预览视频保存为一个素材，逐帧绿幕源图只保留在同一任务 OSS 路径，避免素材库一次新增 32 至 48 张帧图。普通图片、去背景和音频等没有独立上游中间产物的任务不重复复制最终结果。
- 图标和 UI 图集自动拆分只在透明图集成功后执行，属于非阻断附加动作；识别或切片持久化失败时整张透明图集仍完成并回填，前端通过 `sliceWarning` toast 提示用户可手动重试。透明背景最终失败使用通用 `warning.code/reason`，与 `sliceWarning` 互斥；`sliceWarning` 只表示透明图集成功但自动拆分失败，其 `reason` 原始契约保持不变。inline 响应、worker 队列终态和刷新后的任务列表必须使用同一 warning 语义，不能把已完成或降级完成的任务标记为失败。
+- 图标和 UI 图集自动拆分只在透明图集成功后执行，属于非阻断附加动作；识别或切片持久化失败时整张透明图集仍完成并回填，前端通过 `sliceWarning` toast 提示用户可手动重试。透明背景最终失败使用通用 `warning.code/reason`，该情况不会进入拆分，因此与 `sliceWarning` 互斥；风格归一化或像素规整产生的通用 `warning` 则可与 `sliceWarning` 并存，inline 与队列两条链路都必须把两者拼成同一条提示展示，不得只取通用告警。`sliceWarning` 只表示透明图集成功但自动拆分失败，其 `reason` 原始契约保持不变。inline 响应、worker 队列终态和刷新后的任务列表必须使用同一 warning 语义，不能把已完成或降级完成的任务标记为失败。
+- 画布顶部的生成 / 参考图选择 warning toast 保留手动关闭按钮，并在每次 warning 事件进入显示态后 `3` 秒自动消失，避免一次错误提示持续遮挡画布。同样文案在未消失时再次触发也必须重新计时，不能沿用上一次事件的剩余时间。
 - 普通图片、图片修改、规范、角色、图标、UI 设计、宣发素材、视频、音效、背景音乐和角色动作生成面板不展示“资源名称”输入，默认继续使用现有“类型 + 编号”名称；提示词输入保持统一可见边框。状态与请求契约仍兼容可选 `assetLabel`，内部调用或历史状态携带名称时最多 80 个字符并在提交时 trim，最终解析出的同一个名称必须同时写入画布图层、`editor_project_resource`、`editor_asset` 和 `canvasCompletion.title`。中间原图在主名称后追加“（原图）/（原始输出）”，拆分图标仍使用各自素材描述。
 - 图片、视频和音频生成结果都要写入账号级素材库；视频 / 音频结果由后端持久化到 OSS 并回传 `objectKey` / `assetObjectId`，前端保存素材库时一并记录，后续预览和再次加入画布走统一换签链路。
 - 刷新项目后，画布需要同时恢复图层、生成器快照和生成输入框跟随关系。
@@ -1,6 +1,6 @@
 # 画布Agent对话面板

-日期：`2026-07-20`
+日期：`2026-07-23`

 ## 定位与边界

@@ -28,6 +28,7 @@
 - 用户要求“规范图 / 视觉规范图 / 风格规范图 / 素材规范展板”时，规划默认选择 `generate_image`，并在 prompt 中明确要求生成规范展板，包含统一视角、线条粗细、色卡、材质、阴影、圆角、状态层级、尺寸标注等可落地的视觉规范元素。
 - 用户要求“角色规范图”且语义是角色的规范展板、风格展板或设定板时，仍走 `generate_image`，不要误分流到 `generate_character`；只有实际生成角色立绘、角色主形象或角色视觉资产时才走 `generate_character`。用户要求多个图标素材、图集或 spritesheet 时才走 `generate_icon_spritesheet`。
 - 所有生成必须走 `execute_billable_asset_operation_with_cost` 与模型定价配置，禁止绕过定价收口。
+- function-calling 的 JSON Schema 必须与参数默认值和运行时校验保持一致，不能只在 description 中提示会被运行时拒绝的组合。`generate-ui-design` 固定 `gpt-image-2`，因此 `image_size` 只暴露 `1K / 2K`；其它可切换图片模型的工具通过共享条件 schema 在显式选择 `gpt-image-2` 时同样把 `image_size` 限制为 `1K / 2K`，省略模型时仍按默认 nanobanana2 允许 `0.5K`。`generate-video` 省略 `model` 时按默认 `seedance2.0-fast` 约束 `resolution` 为 `480p / 720p`，显式选择其它模型时仍使用其现有分辨率范围。运行时强类型校验继续作为最终防线。
 - 图层操作及其他未注册的画板功能第一期不进入对话工具面，仍走现有面板。

 ## 当前分支落地状态
@@ -59,8 +60,14 @@
 - 对话框与既有任务侧栏（`ImageCanvasTaskSidebarView`）**互斥展开**：展开一个自动收起另一个；各自收起后保留入口按钮。
 - 对话框与左侧素材 / 图层侧栏**不互斥**，允许同时展开，便于在对话中选取和核对画布素材；左侧栏切换不改变 Agent 面板开关状态。
 - 桌面端对话框固定宽约 360–400px；移动端抽屉式全宽覆盖；收起态为胶囊/圆形入口按钮。
+- 底部消息输入框随输入内容从单行高度自动增长，最大高度为
+  128px；输入框及其 Enter 提交、原生自适应和兼容降级统一封装在独立 `EditorAgentDraftTextarea` 组件中。支持 `field-sizing: content` 的浏览器使用原生内容尺寸自适应，不支持该属性的旧 Safari / iOS WebView 使用前端测量降级，并在宽度变化时重新计算换行高度。内容超过最大高度后停止增长并启用内部纵向滚动，内容缩短或清空后同步收缩。内部滚动条使用浅灰窄滑块和透明轨道，上下留白不得溢出输入框圆角边界；输入框在窄屏下允许收缩且不产生横向滚动。
+- Enter 发送必须同时排除 `isComposing` 和旧 Safari / WebKit 候选词确认事件的 `keyCode === 229`，避免输入法选词时误发送。
+- 用户消息必须包含去除首尾空白后的非空文本；附件只能随文本消息发送，前端发送门禁与后端 `module-editor-agent` 领域校验必须同时拒绝纯附件消息。
 - 会话管理入口在对话框头部：当前会话标题 + 历史会话下拉（按更新时间倒序）+ 新建对话按钮，全部包在对话框内。
- 快速切换会话或会话轮询刷新产生并发详情请求时，前端只允许最后发起的请求更新当前会话、消息、错误和加载态；旧响应不得覆盖用户最新选择。
+- 当前会话没有任何已发送消息时，新建对话按钮置灰且不可点击；输入框草稿和未发送附件不算会话内容。当前会话已有消息时可新建，新建成功后只切换到返回的空白会话，输入文字、附件及附件选择状态与切换历史会话时一样原样保留，旧会话继续保留在历史会话下拉中；创建失败同样不修改草稿。
+- 新会话创建请求 pending 时禁用历史会话下拉和发送动作，但输入框与附件仍可编辑；会话列表或历史消息加载期间同样禁用发送。表单提交处理器必须复用相同门禁，不能先清空草稿再由 hook 静默跳过发送。
+- 快速切换会话或会话轮询刷新产生并发详情请求时，每个请求必须获得唯一且单调递增的请求序号；前端只允许最后发起且有权生效的请求更新当前会话、消息、错误和加载态。被正在进行的会话切换压制的旧会话 refresh 不得提前结束新切换的加载态，旧响应也不得覆盖用户最新选择。
 - 普通 JSON 消息请求的回包必须绑定发送时的会话：用户在等待期间切换到其他会话后，只更新原会话的列表摘要，不得把原会话的 `deltaMessages` 、错误或画布刷新副作用应用到当前面板。
 - 收起对话框只是隐藏面板，不卸载当前会话 hook；普通 JSON 消息请求的等待态和外部生成任务状态必须在收起 / 重新打开之间保持一致。

@@ -74,7 +81,9 @@
 - 附件选择弹窗使用 `PlatformToolModalShell` 承接 portal 主题变量和不透明 panel 背景；不能直接把未注入 `platform-theme` 的 `UnifiedModal` portal 到 `document.body`，否则 `--platform-modal-fill` 失效后面板会变透明。
 - 应用后附件以胶囊 chip 挂在输入框上方；发出的消息内附件渲染为纯文本胶囊 chip（名称 + 小图标），**默认无缩略图，鼠标悬浮才浮出缩略图预览**。
 - 附件领域形状：统一为画布资源 / 素材库对象引用（`resourceId` / `assetId` + 可选 `objectKey`），不存在只属于对话的第三种图；单条消息上限 9 张（前后端共同校验）。前端可携带展示用 `imageSrc` / `thumbnailSrc`，后端必须按当前工程和当前账号重新归一、校验归属与 `objectKey`。
- 输入区附件临时状态统一收口到 `useConversationAttachments`，选择弹窗由独立的 `AttachmentPicker` 负责纯展示；选择、引用、粘贴上传完成、移除、发送清空和失败恢复都必须经同一最新状态更新入口。引用历史消息附件时先保留消息中的展示快照，最终发送前再按 `source + referenceId` 从当前画布和素材库选项刷新，避免提前刷新后又被失败恢复的旧快照覆盖。发送失败时，已发送附件必须与等待期间新增的附件去重合并，不得因输入区已非空而丢弃；同一 `source + referenceId` 冲突时保留等待期间的当前草稿快照，失败请求快照只补充缺失 identity。合并后超过 9 张时优先保留等待期间的最新附件，不恢复失败请求的附件，并立即显示上限错误。异步粘贴完成时基于当时的最新附件去重并重新校验 9 张上限，不能用上传开始时捕获的旧列表覆盖期间新增的引用。
+- 附件 `label` 是人类可读的展示元数据，统一限制为最多 24 个 Unicode 码点。归一化时先去掉首尾空白，删除控制字符以及除 `-`、`_`、`.` 之外的 ASCII 标点，把连续空白折叠为一个半角空格，再按 24 码点截断；只含被过滤字符的 label 视为缺失。中文等非 ASCII 标点不属于本轮过滤范围。
+- 前端在创建画布、素材库和粘贴上传附件引用，以及把历史消息附件重新引用到输入区时，先执行上述归一化；原 label 无有效内容时依次归一化并使用调用方提供的 fallback（默认 `referenceId`）和固定文案「图片」。后端不能信任前端结果：校验当前工程 / 当前账号归属和 `objectKey` 后，必须用同一套字符规则、同一 24 码点上限再次归一化并重建权威附件；素材库附件的提交 label 缺失或过滤为空时，才回退到同样归一化后的素材库 label。前后端常量和规则必须保持同步。
+- 输入区附件临时状态统一收口到 `useConversationAttachments`，选择弹窗由独立的 `AttachmentPicker` 负责纯展示；选择、引用、粘贴上传完成、移除、发送清空和失败恢复都必须经同一最新状态更新入口。引用历史消息附件时，原消息继续保留存量展示快照；进入输入区的新引用先归一化 label 并保留其他展示快照字段，最终发送前再按 `source + referenceId` 从当前画布和素材库选项刷新，避免提前刷新后又被失败恢复的旧快照覆盖。发送失败时，已发送附件必须与等待期间新增的附件去重合并，不得因输入区已非空而丢弃；同一 `source + referenceId` 冲突时保留等待期间的当前草稿快照，失败请求快照只补充缺失 identity。合并后超过 9 张时优先保留等待期间的最新附件，不恢复失败请求的附件，并立即显示上限错误。异步粘贴完成时基于当时的最新附件去重并重新校验 9 张上限，不能用上传开始时捕获的旧列表覆盖期间新增的引用。

 ## 工具调用确认展示契约

@@ -83,12 +92,13 @@
 - 确认接口必须先把工具参数转换为既有编辑器 worker payload，再使用 `editor-agent:{conversationId}:{messageId}:{toolName}` 稳定 dedupe key 入队；同一确认的请求重试只能得到同一个 external job。入队成功后把返回的 job id 写回同一条 OSS 工具消息，不新增 Agent 工具执行关联表。
 - 前端根据 `externalJobId` 查询通用 external-generation job 状态；worker 继续通过 `canvasCompletion` 把生成结果写回工程与素材库。浏览器断线、刷新或 api-server 重启不得导致确认接口重新扣费或重新提交 provider。
 - `GET /conversation` 会在同一个 conversation lock 内扫描 `status=not_completed` 且已有 `externalJobId` 的工具消息：只对这些消息按 job id 定向读取主任务；任务完成后复用对应工具的 `format_execute_message` 替换 system text、回填轻量图片 / 视频 / 音频引用并写为 `completed`，任务失败则回填 `error` 并写为 `failed`。任务结果读取或 completed payload 解析 / formatter 回填失败时，必须在同一次 GET 内完成首次尝试及最多 3 次重试，三次重试各间隔 100ms 并重新读取任务结果；仍失败才把该工具消息写为 `failed` 并保存最后错误。该重试不依赖前端再次刷新。排队和执行中都保持 `not_completed`，整轮扫描结果一次性写回 OSS。
- `EditorAgentToolCall.args` 保留为工具返回的原始 JSON，是确认接口重新反序列化并执行工具的唯一参数真相。图片参数继续只保存由真实 data key 计算出的 opaque SHA-256 `imageId`；不得为了前端预览把 `args` 中的图片 ID 改写成 `objectKey`、URL 或展示对象，也不得由前端重组或回传一份新的执行参数。
+- `EditorAgentToolCall.args` 的正式持久化契约是**校验后的规范参数 JSON**，不是 LLM 返回的原始 JSON。api-server 收到工具调用后，必须先按已注册的 ToolArgs 反序列化、补齐字段默认值、删除未进入 ToolArgs 的未知 / 退役字段、执行工具参数校验，再重新序列化并写入 `args`；校验失败的调用不得持久化为待确认消息。所有有明确默认值的工具标量参数在强类型 ToolArgs 中必须使用非 `Option` 字段：调用方省略字段或把顶层字段显式传为 `null` 时，统一在 ToolArgs 反序列化前视为未提供，由 Serde 补齐默认值，并把具体默认值写入规范 `args`；没有默认值的必填字段显式传为 `null` 时同样按缺失处理.(for compatibility) 后续计价、确认展示和 job payload 不得再次使用 `unwrap_or` 补同一默认值。LLM 原始参数只作为本次规范化的瞬时输入，不作为执行或审计真相；确认、取消、任务回填与后续上下文统一读取同一条消息中的规范 `args`。图片参数继续只保存由真实 data key 计算出的 opaque SHA-256 `imageId`；不得为了前端预览把 `args` 中的图片 ID 改写成 `objectKey`、URL 或展示对象，也不得由前端重组或回传一份新的执行参数。
+- api-server 内画布 Agent 工具统一实现 object-safe `EditorAgentTool: ToolDyn`。`validate_args`、计价、确认展示、worker job 构建、`format_execute_message` 和结果媒体投影都使用统一 JSON 边界；每个具体工具实现负责把 JSON 反序列化为自己的强类型 Args / 结果，并把校验与完成消息格式化转发到 `platform-editor-agent` 中既有的 typed `validate_args` / `format_execute_message`，不得在调用方复制工具规则。`editor_agent_tool(toolName, context)` 是唯一按工具名分派的位置，规划、确认和任务回填只调用返回的 dyn tool；新增工具必须补齐同一个 trait 实现和该工厂分支。LLM builder 的 `.tool(...)` 注册列表仍是独立显式清单，不属于本次动态分派。framework runner 必须在 `ToolCallOutput` 中保留工具返回的结构化 output；runner 写入 LLM memory 与 api-server 使用规范参数持久化 system text 时统一调用公开的 `format_tool_call_message`，不得丢弃 `TOOL_CALL_PENDING_MESSAGE` 后自行拼另一套“等待确认”输出。
 - `EditorAgentToolCall.displayArgs` 是必填、只读的用户确认展示投影，与 `args` 分离：
-  - `stringArgs` 保存提示词、比例、清晰度、模型、时长等可展示参数的稳定名称、用户可见标题和值；
-  - `imageArgs` 按“目标图片 / 参考图片”等参数分组，每个 `refs` 项包含与原始参数对应的 `imageId`，以及后端从已校验会话上下文解析出的 `objectKey`、`imageSrc`、可选 `thumbnailSrc` / `label` / `width` / `height`。
+  - `stringArgs` 保存提示词、比例、清晰度、模型、时长等可展示参数的稳定名称、用户可见标题和值；前端渲染模型字段时复用图片编辑器公共展示名映射，`gemini-3.1-flash-image-preview` 显示为 `nanobanana2`、`audio1.0` 显示为 `Vidu`、`chirp-v5` 显示为 `Suno`，视频模型显示现有产品标签，不得改写后端参数真相；
+  - `imageArgs` 按“目标图片 / 参考图片”等参数分组，每个 `refs` 项包含与规范参数对应的 `imageId`，以及后端从已校验会话上下文解析出的 `objectKey`、`imageSrc`、可选 `thumbnailSrc` / `label` / `width` / `height`。
  - `extras.priceMudPoints` 保存创建待确认消息时按后端运行时模型定价快照计算的预计泥点消耗；前端统一展示为“预计消耗 N泥点”，不自行计算价格。
- `displayArgs` 只能由 api-server 按已注册 tool 白名单，基于已经通过 ToolArgs 校验的 `args` 和当前 OSS 会话文档中的附件 / 历史生成结果构建；不能信任 LLM 自报的展示地址、标题或素材元数据。展示投影不参与确认执行，确认接口仍只读取同一条持久化 tool call 的 `args`，避免“看到的素材”和“实际执行的素材”分叉。
+- `displayArgs` 只能由 api-server 按已注册 tool 白名单，基于已经通过 ToolArgs 校验的 `args` 和当前请求开始时从 OSS 会话文档一次性构建的 `EditorToolContext` 生成；该 context 必须按 opaque `ImageId` 同时保存执行所需的 `dataKey` 与展示所需的图片地址、Object Key、缩略图、label、宽高，参数校验、确认展示和 job payload 统一查同一份 context。不能信任 LLM 自报的展示地址、标题或素材元数据。展示投影不参与确认执行，确认接口仍只读取同一条持久化 tool call 的 `args`，避免“看到的素材”和“实际执行的素材”分叉。
 - `extras.priceMudPoints` 同样只属于展示投影，不作为扣费输入；确认后仍由既有生成 BFF 按后端运行时定价执行预扣费，因此该字段表达用户确认时看到的价格快照，而不是前端可提交或覆盖的计费真相。
 - `EditorAgentToolCall.summary` 只是 `args` 的重复字符串且没有稳定语义，当前契约删除该字段，不再作为展示或执行输入。
 - 前端待确认卡只消费必填 `displayArgs`，不解析各 tool 私有的 snake_case / camelCase schema，也不把 `sha256:*` ID 当标题或图片地址。图片统一通过 `ResolvedAssetImage` 使用 `objectKey` 换签后显示，签名 URL 不进入消息文档。模块尚未上线，不保留缺少 `displayArgs` 时读取 raw `args` 的旧消息降级路径。
@@ -96,13 +106,16 @@
 ## LLM 与计费

 - 编排复用 `creative_agent_gpt5_client` 的 LLM 接入配置（同 provider/env，独立用途标识），画布 Agent 规划请求固定使用 VectorEngine `gpt-5.4-mini` Chat Completions；function-calling 注册八类工具。
- 每个用户回合必须由 LLM 返回结构化计划；LLM 未配置、连接已经断开、请求明确失败、达到最终安全上限或返回格式不可解析时，后端写入正文为 `ERROR <错误内容>` 的 system 消息，不使用本地关键词或“收到：...”回显兜底。面向用户的规划错误使用中文语义，不暴露 `completion error` 等 framework 内部前缀或原始配置/定价诊断；原始错误只记录在后端日志。该错误消息与其它 system 消息一样进入后续 LLM memory，使 Agent 能看到上一轮失败上下文。普通 JSON POST 尚未结束只表示 provider request future 仍在等待，不能伪装成已持久化失败。
- 规划 prompt 必须自动带入上一条已完成生成结果的 `latestGeneratedImage` 引用，内容只包含上一轮 generation 的 `toolName` / `resourceId` / `objectKey` / `assetObjectId` 等轻量元数据，不把私有签名 URL 或大图内容塞进 prompt。
+- 每个用户回合必须由 LLM 返回结构化计划；单次 completion 不是有效 JSON 时，runner 先把无效原文作为 assistant message 追加到当前 staged turn，再追加 system 纠正消息，明确要求下一轮只按既定 JSON Response Format 重试；下一次 completion 必须同时看到该无效原文和纠正指令。无效原文只是重试上下文，不进入对外 `PromptOutput` 或用户可见的会话增量；后续规划成功时随 staged turn 一并提交，无工具活动且最终失败时按下文事务规则整体回滚。LLM 未配置、连接已经断开、请求明确失败、达到最终安全上限或多轮重试后仍不可解析时，后端写入正文为 `ERROR <错误内容>` 的 system 消息，不使用本地关键词或“收到：...”回显兜底。面向用户的规划错误使用中文语义，不暴露 `completion error` 等 framework 内部前缀或原始配置/定价诊断；原始错误只记录在后端日志。该错误消息与其它 system 消息一样进入后续 LLM memory，使 Agent 能看到上一轮失败上下文。普通 JSON POST 尚未结束只表示 provider request future 仍在等待，不能伪装成已持久化失败。
 - 工具参数中的图片 ID 是由真实 object key 或图片地址计算的稳定 SHA-256 标识；真实 data key 仅存于 api-server 的工具上下文映射，所有图片工具在执行时查表恢复，不能把 object key 或图片地址作为 LLM 可见的工具 ID。
- 用户使用「这张」「刚才那个」「上一张」「把衣服换成……」等方式指代或编辑上一张结果图时，LLM 默认选择 `edit_image` 并引用 `latestGeneratedImage` 作为源图；除非用户明确要求全新生成，否则不能因为本轮没有重新上传附件而降级为 `generate_image`。
- 规划 prompt 必须显式区分“规范展板”和“实际素材产出”：规范图、视觉规范图、风格规范图、素材规范展板、角色规范图等规范展板请求走 `generate_image`，并补齐统一视角、线条粗细、色卡、材质、阴影、圆角、状态层级、尺寸标注等要求；实际角色立绘才走 `generate_character`，多个图标素材 / 图集才走 `generate_icon_spritesheet`。
- 画布 Agent 规划请求使用 Chat Completions 和 1024 `max_tokens`。发送后 120 秒是前端软提示阈值，不是 provider 失败 deadline：若普通 JSON POST 仍 pending，消息流临时显示“仍在处理中，请耐心等待”并继续等待，提示不写入 OSS 消息历史；连接或请求明确失败则立即按正式错误收口。provider 单 attempt 保留 8 分钟 hard timeout；请求发起阶段的 timeout、连接失败、`408`、`429` 与 `5xx` 读取 `GENARRATIVE_LLM_MAX_RETRIES`，但画布 Agent 最多重试 1 次，专用重试退避最多 60 秒。消息规划生命周期从 handler 入口开始计入 18 分钟总 deadline，进入 `agent.prompt(...)` 时使用扣除会话锁和上下文准备后的剩余预算；该 deadline 覆盖非法 JSON/工具校验失败触发的后续规划轮，并为错误持久化和 HTTP 返回保留约 2 分钟，不再让前端 20 分钟 transport timeout 先触发。已收到成功响应头后的响应体读取或解析失败直接按明确失败收口，错误计数/日志使用该响应所属的真实 attempt。规划重试发生在任何生成工具执行之前，不会重复提交生成任务或扣费；生成图片/编辑图片仍走对应生成工具和模型计费。
+- 规划 prompt 必须显式区分“规范展板”和“实际素材产出”：规范图、视觉规范图、风格规范图、素材规范展板、角色规范图等规范展板请求走 `generate-image`，并补齐统一视角、线条粗细、色卡、材质、阴影、圆角、状态层级、尺寸标注等要求；实际角色立绘才走 `generate-character`，多个图标素材 / 图集才走 `generate-icon-spritesheet`。
+- 用户的当前消息确实在确认或取消一条已存在且仍为 pending 的工具调用时，画布 Agent 只引导使用该卡片的确认 / 取消按钮，本条确认 / 取消意图不产生新 tool call。这条边界必须使用“匹配 pending 调用时如何处理”的正向、条件化描述，不得改写成“不得重新发起相同工具调用”一类全局否定话术：实测中模型会把这类否定句过度泛化为拒绝后续新请求。已 cancelled 的卡片不再处理；用户明确要求修改、重做或发起新任务时必须允许新 tool call，pending 卡片也不阻塞无关的新请求。
+- 画布 Agent 规划请求使用 Chat Completions 和 1024 `max_tokens`。发送后 120 秒是前端软提示阈值，不是 provider 失败 deadline：若普通 JSON POST 仍 pending，消息流临时显示“仍在处理中，请耐心等待”并继续等待，提示不写入 OSS 消息历史；连接或请求明确失败则立即按正式错误收口。provider 单 attempt 保留 8 分钟 hard timeout；请求发起阶段的 timeout、连接失败、`408`、`429` 与 `5xx` 读取 `GENARRATIVE_LLM_MAX_RETRIES`，但画布 Agent 最多重试 1 次，专用重试退避最多 60 秒。消息规划生命周期从 handler 入口开始计入 18 分钟总 deadline，进入 `agent.prompt(...)` 时使用扣除会话锁和上下文准备后的剩余预算；该 deadline 必须作为 runner 内部 deadline future 参与 completion await，并在每个 tool 开始前、返回后检查，不能用外层 `tokio::timeout` 丢弃整个 prompt future，也不能中途 drop 已开始的工具。工具一旦开始就等待其返回，再按 deadline 携带结果收口；当前八类画布工具只做同步参数校验并返回待确认，因此不会延长正式生成链。deadline 命中时仍按 `PromptRunError` 返回已经完成的工具结果、提交对应 staged memory 并追加终态错误。该 deadline 覆盖非法 JSON/工具校验失败触发的后续规划轮，并为错误持久化和 HTTP 返回保留约 2 分钟，不再让前端 20 分钟 transport timeout 先触发。已收到成功响应头后的响应体读取或解析失败直接按明确失败收口，错误计数/日志使用该响应所属的真实 attempt。规划重试发生在任何生成工具执行之前，不会重复提交生成任务或扣费；生成图片/编辑图片仍走对应生成工具和模型计费。
 - function-calling runner 必须把“等待用户确认”作为显式工具语义：当本批所有工具都校验成功并进入待确认状态时，立即以成功结果结束当前规划回合并持久化助手文本与待确认卡，不得继续依赖 LLM 自行停止；未知工具、参数错误、普通连续工具和不可解析响应仍受 `max_turns` 保护。
+- runner 失败必须返回显式的 `PromptRunError { error, partial_outputs }`，不得只返回终态错误而丢弃本轮已产生的文本或工具事实。prompt 执行使用 `AgentMemory::begin_staged` 创建行为等价且写入隔离的 `StagedAgentMemory` 事务，限长、摘要、脱敏等 append 规则必须在本轮 completion 前生效；成功或已发生工具活动时必须显式调用 `commit()`，直接 drop staged transaction 表示回滚，不得统一复制成 `VecMemory` 或仅替换 box 冒充持久化提交。本轮无工具活动失败时回滚 staged 用户消息、助手文本和不可解析响应；已有工具活动时在末尾追加 terminal error closure 后提交。外部 drop / abort 若尚无工具活动则回滚并保持原 committed memory；若工具已完成则提交结果与取消闭环，若工具仍在执行则提交“已启动、结果未知”事实与取消闭环，后续必须先 reconcile 再决定是否重试。
+- `ToolFailure` 必须以结构化工具失败输出暴露给 harness 调用方：调用方能读取 `kind`、`retryable`、`fatal` 和工具返回的原始 `output`；不得把它们压成单一错误字符串。这些字段只提供流程决策与诊断事实，是否重试、如何展示或持久化仍由业务调用方决定。
+- api-server 收到带 `partial_outputs` 的终态失败时，必须先按原顺序把其中已成功工具转成 `status=not_completed` 待确认消息并写入同一会话增量，再追加 `ERROR <错误内容>` 终态 system 消息；不得因后续轮次、其它工具或 `max_turns` 失败而吞掉已经执行并返回的工具结果。
+- 通用 JSON function-calling 协议、工具 schema 注入、memory / hook、`max_turns` 和“全部工具待确认即结束回合”统一由现役 `platform-agent-harness` 承载；无工具时也必须输出同一 JSON 响应格式。画布角色 prompt、规范展板 / 已有图路由、模型与超时 profile、八类工具、计费、OSS 会话和 external job 编排继续留在 `platform-editor-agent` / `api-server`，不得回流已退役的旧 `platform-agent`。
 - **对话回合免费**（聊天、分析回复不扣泥点），仅 Agent 实际触发生成工具时按对应模型定价扣泥点。
 - 工具调用前后端校验泥点余额；不足时该次生成失败并在对话中以明确错误气泡告知，对话本身可继续。

@@ -143,7 +156,7 @@
  - `GET/POST /api/editor/projects/{projectId}/agent-conversations`（列表/新建）；
  - `GET/DELETE /api/editor/agent-conversations/{conversationId}`（详情/软删）；
  - `POST /api/editor/agent-conversations/{conversationId}/messages`（JSON）；
-  - Agent 编排（function-calling 循环、工具内部调既有生成执行链路）放 api-server 编排层，独立文件，不复用 `creative_agent.rs` 内存会话。
+  - 通用 function-calling harness 放 `platform-agent-harness`；画布 Agent profile 与工具放 `platform-editor-agent`；会话、计费、OSS 和工具内部生成执行链路由 api-server 编排层承接，不复用 `creative_agent.rs` 内存会话。
 - `shared-contracts` + `packages/shared`：`editorAgent` 会话、消息、工具确认展示与轻量媒体结果 DTO；消息响应返回 `conversation`、`deltaMessages` 和可选 `errorMessage`。

 ## 实施顺序
@@ -2,9 +2,11 @@

 日期：`2026-06-15`

+更新时间：`2026-07-29`
+
 ## 背景

-图片画布编辑器已有普通图片生成、生成规范、生成角色形象和角色动画入口。本次新增 `生成图标素材`，用于一次输入多条图标素材描述，生成一张纯色背景 spritesheet；后端去背景正常成功后，再尝试自动拆分为可独立编辑的素材。
+图片画布编辑器已有普通图片生成、生成规范、生成角色形象和角色动画入口。本次新增 `生成图标素材`，用于通过一段完整需求生成一张纯色背景 spritesheet；后端去背景正常成功后，再尝试自动拆分为可独立编辑的素材。

 ## 入口与画布表现

@@ -14,6 +16,7 @@
 - 图标素材面板锚定在占位图下方，和现有生成输入框同一层级展示。
 - 透明背景处理正常成功后删除占位态：透明 spritesheet 作为主图（`assetKind: "icon-spritesheet"`，`generatedLayerId` 锚点）放入画布，provider 带背景原图作为第二个同类型图层放在透明主图右侧，按 alpha 连通域成功拆出的 `assetKind: "icon"` 素材从原图右侧继续铺放；透明背景处理最终失败时，后端完成快照只用 provider 原图替换占位态。
 - 选中 `assetKind: "icon-spritesheet"` 图层时，图片浮动工具栏显示 `拆分图集`；手动拆分只追加独立素材，不复制原图集。
+- 用户把现有图层手动标记为“图集”时，必须先持久化一条 `assetKind: "icon-spritesheet"` 的项目资源并把返回的 `resourceId` 写回图层；项目资源只能在媒体来源和 `assetKind` 都相同时复用，不得因同源图片而返回旧类型资源。持久化完成前必须禁用“拆分图集”，持久化失败时回滚到上一个已确认的素材标签和资源引用，并失效该轮未确认的标签撤销记录。
 - 图标规范图写入 `assetKind: "icon-spec"`，用于刷新后保留标签和限制点选来源。

 ## 面板结构
@@ -26,7 +29,7 @@
 2. 第二模块为素材描述文本框。
   - UI 复用角色形象生成面板同款单个文本输入框，让用户直接叙述多个素材。
   - 默认按换行填入：`返回按钮`、`设置按钮`、`下一关按钮`、`提示按钮`、`原图按钮`、`冻结按钮`。
-   - 生成时按换行、逗号、顿号、分号、斜杠或竖线切分，过滤空文本后最多保留 `100` 个素材描述，并按文本顺序作为 prompt 的素材清单。
+   - 生成时只去除整段文本首尾空白，不按换行、逗号、顿号、分号、斜杠、竖线或语义枚举解析素材数量；文本框内容作为一段完整用户需求进入 prompt。

 ## 面板外观

@@ -39,10 +42,11 @@
 - 前端提交到 `POST /api/editor/icon-spritesheets/generations`。
 - 请求字段：
  - `referenceImageSrc`：图标规范的稳定引用（当前账号的 `objectKey`、项目资源 ID 或素材 ID）；本地临时图必须先上传 OSS，禁止 Data URL / Blob URL。
-  - `iconDescriptions`：过滤空文本后的图标描述数组，`1..100`。
+  - `iconDescriptions`：兼容现有接口的图标需求数组，`1..100`；当前画布前端固定把完整文本作为唯一数组元素提交。数组长度只表达请求文本，不作为自动拆分数量。
  - `model`：支持 `gemini-3.1-flash-image-preview`（UI 显示 `nanobanana2`）和 `gpt-image-2`，默认 `nanobanana2`。
  - `aspectRatio`：按 `x:y` 展示，选项跟随模型。
  - `imageSize`：按 `0.5K / 1K / 2K` 展示，选项跟随模型。
+  - `style`：可选生成后处理风格；未勾选像素艺术时传 `"none"`，勾选时传 `"pixelArt"`。
  - `priceMudPoints`：按当前模型和尺寸从编辑器生成计费配置计算；`nanobanana2 1K` 为 `12`，`gpt-image-2 1K` 为 `3`、`gpt-image-2 2K` 为 `5`。前端只提交配置函数计算值，后端用 `editor_generation_config` 校验，不允许素材生成面板自行写死价格。
 - 模型与尺寸选项：
  - `nanobanana2`：比例 `1:1 / 4:3 / 3:2 / 2:3 / 9:16 / 16:9`；大小 `0.5K / 1K / 2K`。后端走 `/v1beta/models/{model}:generateContent`，把图标规范图作为 `inline_data`，并把 `aspectRatio` / `imageSize` 写入 `generationConfig.imageConfig`；`0.5K` 按 VectorEngine 文档传 `"512"`。
@@ -52,18 +56,29 @@
 - Prompt 固定为：

 ```text
-参考图1的图标规范，背景必须是自动决策出的单一纯色抠图背景，且平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便扣除背景；素材自身不要出现与背景色相同或相近的描边、底板、投影或反光；禁止出现文字，保证每个图标素材的所有内容区域是完全连通的。按照以下的素材的顺序从上到下从左到右依次生成并整理成一张spritesheet：
+参考图1的图标规范，背景必须是自动决策出的单一纯色抠图背景，且平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便扣除背景；素材自身不要出现与背景色相同或相近的描边、底板、投影或反光；禁止出现文字。根据以下用户需求生成图标素材并整理成一张 spritesheet；不同图标素材之间必须彼此分离并保留清晰间距，避免描边、底板、投影或装饰元素连接相邻图标：

-<素材描述按中文顿号拼接>
+<完整用户需求>
 ```

+## 像素风格后处理
+
+- 图标素材面板增加紧凑的 `像素艺术` 勾选项。选择保存于现有生成器快照，并可随现有请求和队列 payload 传递；不写入用户可见 `generationInputs`、素材元数据或新建的持久化记录。
+- `style` 省略、为 `null`、空字符串或 `"none"` 时按内部 `None` 处理且不告警；`"pixelArt"` 启用像素规整。未知字符串按 `None` 继续生成，并通过既有通用 `warning` 返回 `unsupported-image-style`；非字符串 JSON 仍返回 `400`。
+- 图标链路以已持久化的带纯色背景 provider 原图实际尺寸为基准；BgFilter 正常成功后，把 Alpha 蒙版回贴到该同尺寸平底原图，再执行像素规整。网格分析源使用平底 provider 原图，RGBA 采样源使用 Alpha 已回贴的透明图；规整结果不再经过独立的最终尺寸处理，直接上传透明 spritesheet，成功后才进入原有连通域自动拆分。
+- 首版固定参数为分析色数 `16`、Alpha 覆盖阈值 `0.375`、像素格尺寸自动检测、固定色板关闭、K-means 最大采样 `262144`。单格颜色按 `Σ(A × RGB) / ΣA` 进行 Alpha 加权；覆盖率 `Σ(A / 255) / N >= 0.375` 且 `ΣA > 0` 时输出硬 Alpha `255`，否则输出严格 `[0,0,0,0]`。分析色数不限制最终输出色数。
+- 像素规整 CPU 工作使用进程级最大并发 `2`；取得并发许可的排队时间与实际处理时间共享最多 `30` 秒预算，同时不得晚于当前请求 deadline，最终以两者中更早者为准。输入图片任一边不得超过 `10000` 像素，总像素不得超过 `8294400`；超限、排队超时或处理超时均保留 Alpha 已回贴的透明图并走非致命降级，随后仍可进入原有自动拆分。
+- 逻辑低分辨率图只存在内存；snapper 在规整内部使用 nearest 恢复到当前 RGBA 输入尺寸，即前述平底 provider 原图的实际尺寸。图标链路不执行角色链路的前置 Lanczos 交付尺寸归一，nearest 也不是规整后的独立交付尺寸恢复。实现应复用 Alpha 回贴阶段读取的平底 provider 原图；必要时最多增加一次读取已有 provider 对象的 OSS GET，不得增加 OSS PUT。
+- 开启或关闭像素风格都保持现有 provider 原图、透明图集和实际成功切片的持久化与画布数量不变。禁止上传逻辑低分辨率图、像素化前后双份图集、预览或诊断图，也不新增 asset kind、项目资源、画布 item、任务类型或数据库字段。
+- 图标图集的 BgFilter `flat` 调用固定使用 `cross_check=on`。BgFilter 最终失败、Alpha 比例漂移超过 `5%`、provider 原图修复性回读失败、Alpha 回贴失败或透明图完整解码失败时，都统一只保留 provider 原图且不拆分，像素规整不运行；像素规整自身失败但透明图仍通过完整解码和尺寸守卫时，才保留该透明图并继续上传和拆分，通过通用 `warning` 非致命提示，不退款。`sliceWarning` 继续只表达可信透明图成功后的自动拆分失败。
+
 ## 去背与保存

- 父流程收到 spritesheet 后先把带解析后纯色背景的源图写入私有 OSS，并在上传完成后释放原图缓冲；随后只持 object key，并仅向同机唯一 loopback `bgfilter-worker` 发起一次内部 HTTP RPC，请求中的源图只以 object key 传递，并附带 BgFilter 参数、排队预算 `maxQueueWaitMs`、调用预算 `callBudgetMs` 和有界审计关联，父流程不签发 BgFilter URL、不直连 provider，也不重试已被 worker 接收的内部 RPC（连接从未建立时按调度方案 §5.1 有界重连）。子 worker 在 `Q` admission 和 `Semaphore(N)` 约束下执行这次逻辑调用；排队只消耗 `maxQueueWaitMs`，取得 provider permit 后才启动 `callBudgetMs`。每次 provider attempt 前重新签发 600 秒 GET URL，multipart 固定传 `image_url`、`screen_color=<screenColor>`、`seg_model=<segModel>`、`background_mode=flat` 和 `cross_check=off`，不包含 `file`，并在调用预算内最多执行两次顺序 attempt。前端用户路径固定提交 `screenColor=auto` 与默认 `segModel=birefnet`，后端仍识别内部保留的 `anime-seg`，但这些内部参数不对用户可见。成功时，子 worker 通过内部 HTTP 二进制 body 把经过校验的图片字节直接返回父流程，不持久化中间结果；BgFilter 最终失败且父业务预算仍有效时，由父流程进入“阿里云通用抠图（按签名 URL 单独下载）→ 本地键色（再按 object key 独立下载一次原图并在产出后释放）”降级链。
- 透明背景处理正常成功时，父流程把带背景原图和去背后的透明 spritesheet 写入 OSS、项目资源和账号素材库，再按 alpha 连通域和素材描述顺序执行附加拆分；若 BgFilter 返回较小图集，只把 alpha 蒙版重采样到 provider 原图尺寸并应用回原始高分辨率 RGB，不放大低分辨率后处理成品。画布完成快照同时写入透明主图与右侧 provider 原图（二者均已登记为 project resource / 账号素材），`generatedLayerId` 仍锚定透明主图；成功拆出的切片从 provider 原图右侧继续排列。调用方未指定素材文件夹时统一落默认“项目”文件夹。每个成功切片单独写入 OSS、项目资源和账号素材库，`sourceResourceId` 指向透明图集资源。BgFilter 与父侧 fallback 最终均失败、但 provider 原图已经持久化时，任务以 `completed + warning` 收口，只把 provider 原图作为唯一主图放入画布，`generatedLayerId` 指向原图，不创建透明图集，也不继续拆分，`iconImageSrcs=[]`。该收口只捕获透明背景处理本身的最终失败；phase 上报、provider 原图持久化、透明处理图持久化和 `canvasCompletion` 写回错误仍正常传播，不能被原图降级吞掉。最终透明结果及切片的 OSS / 资源 / 画布持久化仍全部由父流程负责。
- 自动拆分只在透明图集成功后执行，属于 best-effort 附加动作，不参与图集生成的成功判定。连通域识别或切片持久化失败时，接口仍返回并回填整张透明图集，`iconImageSrcs=[]`，并通过 `sliceWarning.code/reason` 暴露非阻断原因；`sliceWarning` 与透明背景最终失败使用的通用 `warning` 互斥，前者只表示透明图集成功但自动拆分失败，`sliceWarning.reason` 原始契约保持不变。前端在 inline、worker 队列完成和刷新恢复三条路径统一显示对应 warning toast，用户可在图集工具栏手动重试。
- 响应通过 `iconImageSrcs` 返回成功切片素材；自动生成使用用户输入的素材描述命名，UI 设计提取和手动拆分按从上到下、从左到右自动命名为 `素材 N`。
- 手动拆分调用 `POST /api/editor/icon-spritesheets/slices`，只允许读取当前用户项目中的 `icon-spritesheet` 资源，不调用图片生成 provider，不扣除泥点。输入限制为单边最多 `4096` 像素、总像素最多 `2048×2048`，单次最多持久化 `64` 个切片；超限在任何切片写入前拒绝。
+- 父流程收到 spritesheet 后先把带解析后纯色背景的源图写入私有 OSS，并在上传完成后释放原图缓冲；随后只持 object key，并仅向同机唯一 loopback `bgfilter-worker` 发起一次内部 HTTP RPC，请求中的源图只以 object key 传递，并附带 BgFilter 参数、排队预算 `maxQueueWaitMs`、调用预算 `callBudgetMs` 和有界审计关联，父流程不签发 BgFilter URL、不直连 provider，也不重试已被 worker 接收的内部 RPC（连接从未建立时按调度方案 §5.1 有界重连）。子 worker 在 `Q` admission 和 `Semaphore(N)` 约束下执行这次逻辑调用；排队只消耗 `maxQueueWaitMs`，取得 provider permit 后才启动 `callBudgetMs`。每次 provider attempt 前重新签发 600 秒 GET URL，multipart 固定传 `image_url`、`screen_color=<screenColor>`、`seg_model=<segModel>`、`background_mode=flat` 和 `cross_check=on`，不包含 `file`，并在调用预算内最多执行两次顺序 attempt。前端用户路径固定提交 `screenColor=auto` 与默认 `segModel=birefnet`，后端仍识别内部保留的 `anime-seg`，但这些内部参数不对用户可见。成功时，子 worker 通过内部 HTTP 二进制 body 把经过校验的图片字节直接返回父流程，不持久化中间结果；BgFilter 最终失败且父业务预算仍有效时，由父流程进入“阿里云通用抠图（按签名 URL 单独下载）→ 本地键色（再按 object key 独立下载一次原图并在产出后释放）”降级链。
+- 透明背景处理正常成功时，父流程把带背景原图和经完整解码 / 尺寸守卫验证的透明 spritesheet 写入 OSS、项目资源和账号素材库，再识别 alpha 连通域并执行附加拆分。BgFilter 最终失败或后续 Alpha / 尺寸恢复、原图回读、透明图完整解码失败、但 provider 原图已经持久化时，任务以 `completed + warning` 收口，只把 provider 原图作为唯一主图放入画布，不创建透明图集，也不继续拆分，`iconImageSrcs=[]`、`sliceWarning=null`。该收口不捕获 phase 上报、provider 原图持久化或 `canvasCompletion` 写回错误；provider 原图本身解码失败时在首次持久化前失败，不允许用 `512×512` 伪造元数据。
+- 自动拆分只在透明图集成功后执行，属于 best-effort 附加动作，不参与图集生成的成功判定。连通域识别或切片持久化失败时，接口仍返回并回填整张透明图集，`iconImageSrcs=[]`，并通过 `sliceWarning.code/reason` 暴露非阻断原因；`sliceWarning` 与透明背景最终失败使用的通用 `warning` 互斥，因为透明背景失败时不会进入拆分，但可与风格归一化或像素规整产生的通用 `warning` 并存。前者只表示透明图集成功但自动拆分失败，`sliceWarning.reason` 原始契约保持不变。前端在 inline、worker 队列完成和刷新恢复三条路径统一显示对应 warning toast，用户可在图集工具栏手动重试。
+- 响应通过 `iconImageSrcs` 返回成功切片素材。图标自动拆分、手动 `拆分图集` 和 UI 提取复用同一个 bounded CPU helper 和 platform 实现：全部原始连通域（包括随后过滤的噪点）最多 `4096` 个，辅助部件通过 `64px` 空间网格只检查最大 `48px` 邻域候选；有效输出按视觉阅读顺序命名为 `素材 N`。
+- 三条拆分路径共同限制单边最多 `4096` 像素、总像素最多 `2048×2048`、最多 `64` 个输出；输出限制在排序、裁剪和 PNG 编码前检查。整段图片 CPU 工作在 2 路 semaphore、30 秒本地上限与请求 deadline 共同保护的 `spawn_blocking` 中执行，permit 由 blocking 闭包持有。自动拆分超限以稳定 `sliceWarning` 非阻断降级且不产生切片 PUT、资源或画布切片；手动拆分超限在首次持久化前返回 `422`。

 ## 前端铺放规则

@@ -75,10 +90,12 @@

 - 点击 `生成图标素材` 后出现一叠空白图标占位和图标素材面板。
 - `图标规范 -> 从画布中选择` 只能选择图标规范图，点击普通图片或角色规范图不会绑定。
- 默认 6 个素材描述会进入 prompt；用户在单个文本框中继续输入时最多解析 100 个素材描述。
+- 默认提示文本会完整进入 prompt；用户输入不再被解析为素材数量。例如“各种敌人头像：骷髅 哥布林 强盗 龙 蝙蝠等”只是一段完整需求，不代表必须生成或拆出 `6` 个素材。
 - 默认打开图标素材面板时选中 `nanobanana2 / 1:1 / 1K`；模型切换后，角色和图标素材面板之间沿用上次选择的模型。
 - 图标素材生成请求必须带 `model`、`aspectRatio` 和 `imageSize`；`nanobanana2` 请求体必须包含 `generationConfig.imageConfig.aspectRatio/imageSize`，`gpt-image-2` 请求必须包含文档映射后的 `size`。
+- 图标素材面板可选择 `style: "none" | "pixelArt"`；`none` 完整保持原处理路径，`pixelArt` 在 Alpha 回贴后、自动拆分前执行内存像素规整，最终 OSS PUT、项目资源、图集画布项和切片画布项数量不得因此增加。
 - 图标素材生成可以上传普通参考图；提交时图标规范图仍走 `referenceImageSrc`，普通参考图走 `referenceImageSrcs`，二者都必须是稳定引用（`objectKey` / 项目资源 ID / 素材 ID），禁止 Data URL / Blob URL，并写入 `generationInputs.references`。
- 透明背景处理和自动拆分都成功后，画布同时出现透明 spritesheet 主图、其右侧的 provider 原图，以及从原图右侧铺开的按描述命名的独立图标图层；透明图集成功但拆分失败时仍出现透明主图与右侧原图，透明背景处理最终失败时只出现 provider 原图。
+- 透明背景处理和自动拆分都成功后，画布同时出现透明 spritesheet 主图、其右侧的 provider 原图，以及从原图右侧铺开的全部有效连通域图标图层，图标依次命名为 `素材 N`；透明图集成功但拆分失败时仍出现透明主图与右侧原图，透明背景处理最终失败时只出现 provider 原图。
 - 选中透明图集图层时显示 `拆分图集`；点击后源图集显示扫描蒙层与 `拆图中` 状态，工具栏按钮同步切换为旋转图标和 `拆图中` 并禁用重复提交。完成后恢复工具栏，不新增第二张图集，只在 provider 原图右侧追加自动识别的独立素材，并同步写入素材库。
+- 把同源派生图层从其它标签改为“图集”时，在项目资源返回新 `resourceId` 前“拆分图集”保持禁用；持久化成功后拆分请求必须指向 `assetKind: "icon-spritesheet"` 的新资源，失败时标签回滚且不发起拆分请求。
 - 生成图标素材提交体包含按模型和尺寸计算的 `priceMudPoints`；`nanobanana2 1K` 应为 `12`，`gpt-image-2 1K` 应为 `3`，`gpt-image-2 2K` 应为 `5`。若前端传入与后端计费配置不一致的值，后端返回 `priceMudPoints` 校验错误，不继续调用上游生成。
@@ -2,7 +2,7 @@

 日期：`2026-06-15`

-更新时间：`2026-07-21`
+更新时间：`2026-07-28`

 ## 背景

@@ -60,6 +60,18 @@
  - `nanobanana2`：比例 `1:1 / 4:3 / 3:2 / 2:3 / 9:16 / 16:9`；大小 `0.5K / 1K / 2K`。后端走 `/v1beta/models/{model}:generateContent`，把比例写入 `generationConfig.imageConfig.aspectRatio`，把大小写入 `generationConfig.imageConfig.imageSize`；其中 `0.5K` 按文档传 `"512"`。
  - `gpt-image-2`：比例 `1:1 / 4:3 / 3:2 / 2:3 / 9:16 / 16:9`；大小 `1K / 2K`。后端走 `/v1/images/generations` 或 `/v1/images/edits`。K 档按最长边计算，并转换为 provider 可直接生成的合法像素：`1K` 的 `1:1 / 4:3 / 3:2 / 2:3 / 9:16 / 16:9` 分别为 `1024x1024 / 1024x768 / 1024x688 / 688x1024 / 608x1088 / 1088x608`；`2K` 分别为 `2048x2048 / 2048x1536 / 2048x1376 / 1376x2048 / 1152x2048 / 2048x1152`。其中 9:16 的 1K 尺寸按 provider 最小总像素和 16 对齐约束修正。禁止把 2K 竖图回落为 1K 请求，也禁止在回图后放大伪造所选 K 档。
 - 后端如果收到参考图，`nanobanana2` 把参考图作为 `inline_data` 传入原生 `generateContent`；`gpt-image-2` 走带多参考图的图片编辑链路。没有参考图时按所选模型走纯文本生成链路。
+
+## 风格与像素规整
+
+- 角色面板增加紧凑的 `像素艺术` 勾选项，请求使用可选字符串字段 `style`：未勾选传 `"none"`，勾选传 `"pixelArt"`。该选择可以随现有生成器快照和队列 payload 保存，但不写入用户可见 `generationInputs`、素材元数据或新建的持久化记录。
+- `style` 省略、为 `null`、空字符串或 `"none"` 时按内部 `None` 处理且不告警；`"pixelArt"` 在 `kind="character"` 时启用像素规整。未知字符串按 `None` 继续生成，并通过既有通用 `warning` 返回 `unsupported-image-style`；非字符串 JSON 仍返回 `400`。同一图片生成请求 DTO 被其它 `kind` 复用时，只有普通图片和 `character` 支持 `"pixelArt"`，其它 `kind` 收到该值也按不支持风格降级。
+- 角色 provider 回图先按统一业务像素矩阵执行交付尺寸归一：允许无放大恢复时使用 Lanczos 重采样并居中裁切，无法安全恢复时保留 provider 实际尺寸并返回非阻断告警。归一后的带纯色背景图先持久化并作为 BgFilter 输入；BgFilter 正常成功后，把 Alpha 蒙版回贴到这张同尺寸平底原图，再执行像素规整并上传透明主图。网格分析源使用已收口到实际交付尺寸的平底原图，RGBA 采样源使用 Alpha 已回贴的透明图；软 Alpha 只参与单格覆盖率和 Alpha 加权 RGB 计算，输出 Alpha 硬化为 `0 / 255`。
+- 首版参数固定为分析色数 `16`、Alpha 覆盖阈值 `0.375`、像素格尺寸自动检测、固定色板关闭、K-means 最大采样 `262144`。单格覆盖率 `Σ(A / 255) / N >= 0.375` 且 `ΣA > 0` 时输出 `A=255`，颜色按 `Σ(A × RGB) / ΣA` 计算；否则输出 `[0,0,0,0]`。分析色数不限制最终输出色数。
+- 像素规整 CPU 工作使用进程级最大并发 `2`；取得并发许可的排队时间与实际处理时间共享最多 `30` 秒预算，同时不得晚于当前请求 deadline，最终以两者中更早者为准。输入图片任一边不得超过 `10000` 像素，总像素不得超过 `8294400`；超限、排队超时或处理超时均保留 Alpha 已回贴的透明图并走非致命降级。
+- 逻辑低分辨率图只存在内存；snapper 在规整内部使用 nearest 恢复到当前 RGBA 输入尺寸，该输入已经是前述 Lanczos 归一后的交付尺寸，或尺寸归一无法安全执行时保留的 provider 实际尺寸。nearest 不是新的交付尺寸归一，规整完成后也不再执行第二次 Lanczos 或其它尺寸恢复。实现应复用 Alpha 回贴阶段读取的已持久化平底原图；必要时最多增加一次读取已有 provider 对象的 OSS GET，不得增加 OSS PUT。
+- 开启或关闭像素风格都保持现有 provider 原图与透明主图两份产物、项目资源和画布图层数量不变。禁止上传逻辑低分辨率图、像素化前后双份主图、预览或诊断图，也不新增 asset kind、画布 item 或任务类型。
+- 本功能不修改 BgFilter `flat` 调用、`cross_check=on`、fallback、Alpha 回贴或默认关闭 despill 的现状。BgFilter 最终失败时沿用只保留 provider 原图的既有收口且不运行像素规整；像素规整自身失败时保留已成功的透明图并继续原有持久化，通过通用 `warning` 非致命提示，不退款。
+
 - `kind = "character"` 时，后端不直接把前端文本当完整生图提示词，而是把文本作为 `角色设定` 填入固定提示词骨架：

 ```text
@@ -106,6 +118,7 @@
 - `从画布中选择` 后点击已有画布图片可绑定为角色规范，`Esc` 可退出点选状态。
 - 上传常规参考图后缩略图右下角显示序号。
 - 输入角色设定并生成时，请求包含 `kind: "character"`、角色设定 prompt、参考图数组、`model`、`screenColor`、`aspectRatio` 和 `imageSize`。
+- 角色面板可选择 `style: "none" | "pixelArt"`；`none` 的处理路径和产物保持不变，`pixelArt` 在 Alpha 回贴后执行内存像素规整，最终 OSS PUT、项目资源和画布图层数量不得增加。
 - 默认打开角色生成面板时选中 `nanobanana2 / 1:1 / 1K`；切换到 `gpt-image-2` 后再次打开角色或图标素材面板应沿用该模型。
 - 生成成功后在占位图位置创建 `assetKind: "character"` 图层，右上角显示 `角色` 标签，布局保存包含该字段。