合并主线并保留资源kind枚举收口

合并 origin/master 的 AGC 画布参考与项目能力更新

解决 canvas 生成恢复与任务模型冲突并继续使用共享 GameCreationAppAssetKind

保留 run_id、generationKind 与外部协议字符串的独立边界

docs/technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md

@@ -75,11 +75,11 @@
 | 渠道      | 构建目标                 | 清单平台键                                     | 更新包                   | 清单地址                             |
 | --------- | ------------------------ | ---------------------------------------------- | ------------------------ | ------------------------------------ |
 | `dev-win` | `x86_64-pc-windows-msvc` | `windows-x86_64`                               | NSIS `.exe` + `.exe.sig` | `<OSS base>/agc/dev-win/latest.json` |
-| `dev-mac` | `universal-apple-darwin` | `darwin-aarch64` + `darwin-x86_64`（同一对象） | `*.app.tar.gz` + `.sig`  | `<OSS base>/agc/dev-mac/latest.json` |
+| `dev-mac` | `aarch64-apple-darwin` 或 `x86_64-apple-darwin` | 对应 `darwin-aarch64` 或 `darwin-x86_64` | `*.app.tar.gz` + `.sig` | `<OSS base>/agc/dev-mac/latest.json` |
 
 - 对象布局：清单固定写成 `agc/<channel>/latest.json`；安装包与签名写成 `agc/<channel>/<version>/<file>` 与 `<file>.sig`。
-- macOS 使用 universal 包：`dev-mac` 按 universal 目标构建（Intel 与 Apple Silicon 共用一个包），清单把同一个 `.app.tar.gz` 与同一个签名分别写入 `darwin-aarch64` 与 `darwin-x86_64`，升级后仍是 universal 包。这是 Tauri 官方发布工具对 universal 产物的既有写法。
-- 上一条的两个键不能合成单一 `darwin-universal` 键：更新插件按运行时实际架构解析清单键（Apple Silicon 命中 `darwin-aarch64`，Intel 命中 `darwin-x86_64`），不存在自动命中 `darwin-universal` 的情形。将来真要单独发该键，必须在客户端同时设置自定义 target，否则清单里这一项永远不会被读取。
+- macOS 当前采用单架构包：Apple Silicon 使用 `aarch64-apple-darwin`，Intel 使用 `x86_64-apple-darwin`；每次生成的清单只登记本次实际构建的架构，不把单架构原生 Codex 资源挂到另一架构。`universal-apple-darwin` 在版本读取/写入、构建和清单生成之前拒绝。
+- 渠道清单以实际运行架构为键。两种单架构构建不可轮流覆盖同一个 `latest.json` 并宣称双架构均可更新；当前不实现跨构建合并，Intel 发布需先完成其构建验证与多架构清单发布方案。
 - 构建期要求：打开 `bundle.createUpdaterArtifacts` 以生成 `.sig`；构建环境提供签名私钥与密码（私钥内容不得入库）；公钥写入客户端配置。公钥在首个带更新能力的版本发布后不可更换，更换等于放弃自动更新（只能手动重装）。
 - 版本递增按渠道独立进行：发布脚本读取该渠道远端 `latest.json` 的 `version`，与本地版本取较高者递增 patch；两个渠道的版本号互不影响。
 - 版本高水位：发布脚本取「渠道清单版本」与「旧协议迁移指针版本」（迁移窗口内）中的较大值再递增。只看渠道清单会在渠道启用初期把版本链改小 —— 2026-09-17 首次渠道发布即把旧指针的 0.1.57 退回 0.1.48，随后以显式 0.1.60 纠偏；迁移窗口结束（旧指针 404）后自动只剩渠道清单，`dev-mac` 不参与旧指针比较。
@@ -90,6 +90,7 @@
 ## 构建与发布
 
 - 发布入口：`npm run ai-game-creator-shell:release:upload`（构建 + 按渠道上传）；仅构建不发布的 smoke 使用 `--no-bundle` 分支，不读远端版本、不改版本、不生成清单。
+- 发布入口只解析一次目标，优先级为 CLI `--target value` / `--target=value` / `-t value`、`AGC_BUILD_TARGET`、Windows 默认值；重复/空目标与不支持目标失败关闭。版本高水位、构建 feature/渠道端点、bundle 路径、产物后缀、清单平台键及摘要必须消费同一个发布上下文，不能分别回读默认目标。
 - 渠道由构建参数显式指定，并按目标平台校验：Windows 目标只允许 `dev-win`，macOS 目标只允许 `dev-mac`；未显式指定时按目标平台取默认渠道。
 - 定时调度只在本轮到达的提交包含 AGC 相关路径（客户端、共享包、`server-rs/crates`、AGC 插件、桌面壳图标、根依赖清单）时才触发渠道发布；纯文档或流水线自身的提交只跑 Full Build，不推高客户端版本号。判定失败或勾选强制触发时按"需要发布"处理。
 - 更新摘要自动生成：发布脚本用渠道清单里的 `commit` 字段（上一次发布的提交）到本次提交之间、且只覆盖客户端相关路径的提交列表生成 `notes`（每条 `- 提交标题（短 SHA）`，最多 12 条、主题 80 字、整体 900 字，超出折叠或截断），同时写入旧协议清单的 `releaseNotes` 和归档文件 `release-notes.txt`。`AGC_UPDATE_RELEASE_NOTES` 非空时以手动文案为准；无法判定起点（缺少上次 `commit` 或本地没有该提交）时不写摘要。清单缺少 `commit` 时回退用上一次成功构建的 `COMMIT_HASH`（CI 通过 `AGC_UPDATE_PREVIOUS_COMMIT` 传入）作为锚点，因此首次启用摘要或更换渠道后也能立即产出摘要。锚点仍不可得（清单读取失败或没有 CI 锚点）时降级为「最近客户端改动」列表并注明可能与上一版重复 —— 摘要属于附注，任何情况下都不允许因为它让发布失败。
@@ -105,7 +106,7 @@
 | 条款                         | 验收方式                                                                | 证据                                                                                                                                 |
 | ---------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
 | 渠道与端点映射、渠道校验     | `node --test apps/ai-game-creator-shell/scripts/build-release.test.mjs` | 通过（默认渠道、错配失败关闭、未知渠道失败关闭）                                                                                     |
-| universal 包挂两个平台键     | 同上 + 本地发布烟测（伪造 bundle）                                      | 通过（两键同 URL 同签名，不生成迁移清单）                                                                                            |
+| macOS 单架构清单与 universal 拒绝 | 定向发布脚本测试 | 单架构各用对应平台键；拒绝未闭合的 universal 发布 |
 | 缺签名时失败关闭             | 同上                                                                    | 通过                                                                                                                                 |
 | 开发态不检查更新             | `vitest run apps/ai-game-creator-shell/tests/appUpdate.test.ts`         | 通过（开关关闭时不请求清单）                                                                                                         |
 | 旧自研链路整条删除           | 代码检索无残留命令、事件与白名单条目                                    | 通过（`download_agc_update` / 下载事件 / 清单常量均无残留）                                                                          |
@@ -127,7 +128,7 @@
 
 已决策：
 
-- macOS 采用 universal 包，同一产物同时挂 `darwin-aarch64` 与 `darwin-x86_64` 两个清单键（见「契约与迁移」）。
+- macOS 采用单架构包，只登记实际构建架构；Intel 真机构建与跨架构清单合并未验收，不公开宣称双架构分发就绪。
 - 旧客户端迁移桥：保留一个版本周期。渠道清单上线后，发布管线同时把旧的 `agc/latest.json`（sha256 格式）指向 `dev-win` 最新安装包，让已发布客户端自动升级到新协议；下个周期整条删除。
 - 签名密钥：由本仓库维护者生成并保管，私钥保存在仓库外（`%USERPROFILE%\.tauri\genarrative-agc-updater.key`），只有公钥进入客户端配置；Jenkins 用受保护凭据 `AgcUpdaterSigningKey` 与 `AgcUpdaterSigningKeyPassword` 注入为 Tauri 打包器读取的 `TAURI_SIGNING_PRIVATE_KEY` 与 `TAURI_SIGNING_PRIVATE_KEY_PASSWORD`，本机可用 `TAURI_SIGNING_PRIVATE_KEY_PATH` 指向同一私钥。当前密钥不带密码；首次发布前仍可重新生成，首次发布后不可更换。
 - macOS 发布方式：`dev-mac` 产物在本机 mac 上执行发布入口上传，Jenkins 暂不新增 macOS 节点；macOS 代码签名与公证凭据未确认前，相关闭环记为未验证项，不静默通过。

docs/technical/【技术方案】AGC模板库与模板建项-2026-09-17.md

@@ -52,7 +52,7 @@ templates/
 | --- | --- |
 | `fetch_game_template_library` | 读 `templates/index.json`（≤4 MiB），校验后缓存到 `<app_data>/templates/index.json`；网络失败时回退本机缓存并在 `source` 标 `cache` |
 | `download_game_template` | 取清单里对应条目，流式下载 zip（≤512 MiB），校验字节数与 SHA-256，解压到 `<app_data>/templates/installed/<id>/<version>/`，最后写 `installed.json` 作为安装完成的唯一标记 |
-| `create_automatic_local_game_project_from_template` | 需要时先安装模板，然后在 `<app_data>/projects/` 下按既有自动工作区规则建目录：先复制模板文件，再走 `init_local_game_project_at` 补 `.agent` 清单与标准目录 |
+| `create_automatic_local_game_project_from_template` | 需要时先安装模板，然后在 `<app_data>/projects/` 下按既有自动工作区规则建目录：先复制模板文件，再走 `init_local_game_project_at` 补 `.agent` 清单与标准目录。根目录可用 `projectsRoot` 覆盖（必须来自本机目录选择器并通过私有路径门禁），未指定时仍是 `<app_data>/projects/`；见 [`【实施计划】AGC项目创建目录可选-2026-09-17.md`](../project-memory/plans/【实施计划】AGC项目创建目录可选-2026-09-17.md) |
 
 安全与健壮性：
 

docs/technical/【技术方案】AGC通用插件宿主与编辑器适配-2026-09-09.md

@@ -69,6 +69,10 @@ OpenAI 的标准模型是“Plugin 作为可安装包，组合 Skills、可选 M
 
 除 AppData 导入外，宿主还扫描 `plugins/` 工作区：每个含根目录 `plugin.json` 的一级子目录是一个插件包。解析顺序为环境变量 `AGC_PLUGIN_WORKSPACE`、随包资源目录 `<resource_dir>/plugins`、开发构建的仓库 `plugins/`。仓库工作区约定见 [`plugins/README.md`](../../../plugins/README.md)。
 
+Windows 与 macOS 构建都将内置插件的清单、JS 入口与面板复制到应用资源目录；staging 每次重建，避免已删除插件或跨目标原生 payload 残留。macOS 不携带 Windows native payload。Cocos 进程桥接仍仅按既有 Windows 平台实现提供，插件文件可被发现不代表 macOS 已支持编辑器控制；JS 入口的系统 Node 前提不变。
+
+Cocos 插件对用户可见与可启动必须同时满足当前为 Cocos 项目、宿主已注册 `cocos-editor` 原生适配器；没有适配器时从插件/扩展列表隐藏，直接启动或读取面板也在产生子进程前拒绝。正式适配器仅在 Windows 且编译 `cocos-editor-execute` 时注册；Agent 工具使用相同平台与 feature 门禁。前端只按后端列表投影判断是否自动启动，不自行推断平台能力。
+
 ### 内置插件与可用开关
 
 `plugins/` 工作区里的插件是**内置插件**：随客户端分发，用户不能卸载或删除，只能通过可用开关控制是否生效。开关状态持久化在 AppData `extensions/builtin-plugins.json`（`schemaVersion = agc.builtin-plugins.v1`，`enabled` 是 id 到布尔的映射）；文件缺失按插件 manifest 的 `enabled` 处理，坏文件失败关闭。内置插件优先级高于同名导入插件，AppData 里的同名 Plugin 不会覆盖或间接卸载它。

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

@@ -29,6 +29,45 @@ Rust 侧在 `server-rs/crates/shared-contracts` 维护唯一权威 `GameCreation
 当前候选正式成员以 api-server 仍有效的资源 kind 命名为基线，并保留 shell 已实际使用的字体与通用音频语义：`image`、`scene`、`character`、`character-animation`、`icon`、`icon-spritesheet`、`icon-spec`、`ui-design`、`ui-design-doc`、`publication-material`、`spec`、`video`、`audio`、`sound-effect`、`background-music`、`font`、`document`、`code`、`unknown`。`audio` 表示通用上传音频，`sound-effect` 与 `background-music` 表示更具体的生成/资源语义，不因同属 `audio` category 而合并。`asset`、`ui`、`animation`、`game-background`、`art-spritesheet` 等旧值必须逐处审计：进入 GameCreationAppAssetKind 的生产写入改为正式成员；仅作为 workflow、generation、路径或协议标识的值保持原字段，留待后续独立 PR。
 
 实施要求：先完成 shell 内 raw kind / typed kind 扫描清单与生产写入审计，再分小提交实现 Rust enum、生成绑定、内部字段收紧、写入方修正、Unknown 可观测性和旧 alias 删除。每个提交只形成一个可验证的深模块，不把不同领域的字符串类型强行合并；完成后补充 `ts-rs` 生成/校验门禁、serde round-trip、未知值日志和所有 manifest writer 的 canonical/Unknown 边界测试。
+## 游戏画布居中指引
+
+开发 Agent 的系统工程提示与 `agc-web-game-development` Skill 明确约束同一 canvas 的居中只能由一方负责：Phaser `FIT + CENTER_BOTH` 配合尺寸明确的普通块级父容器，不叠加同一父容器的 Grid/Flex 居中、自动外边距或居中 transform；如由 CSS 居中则设置 Phaser `NO_CENTER`，外围页面的 Grid/Flex 不受此限制。布局修改后构建实际 dist，并在桌面、移动和 resize 下核对 canvas 对游戏父容器中心偏差不超过 1 CSS px、无溢出与意外滚动条。出现偏移先检查游戏项目的 CSS/scale，不修改 AGC 预览固定偏移掩盖问题；这些要求通过 Agent 指引执行，不新增运行时门禁或平行校验系统。
+
+## 画布验收返修边界
+
+- 生成浮层的实例、输入、失败状态与请求身份必须按占位草稿身份隔离；切换到另一张占位时不能沿用上一张的工具类型、输入或 operation。切换未提交草稿仍须保留各自输入，回到原占位可继续编辑。
+- 失败任务重试必须保留原请求的完整参考资产 ID 集合。参考资产失效时明确提示并阻止旧请求提交，不得静默过滤后用改变的参考集恢复原 operation，也不得自动创建新的付费请求。
+- 显式整理的待写意图不能因切换栏目而覆盖其他栏目的排队范围。每个受影响范围与撤销步骤保持一致；拖动预览和最终写回使用同一份按下时冻结的起点快照，即使拖动期间布局收到异步更新也不跳位。
+
+## 多选素材批量标签
+
+- 画布与资源面板共用选中集合。选择至少两项同项目已登记素材后，从已有“编辑标签”入口或资源面板的“批量标签”动作打开同一标签编辑器的批量模式；入口遵循既有“常用操作 + 更多”收纳，不新增平行资源管理页。
+- 批量模式只将用户填写的标签追加到整组选中素材。输入按既有中英文逗号、顿号、换行拆分，trim、去空及去重；每份素材原有标签、正式分类、类型、路径、来源、版本关系均保留。批量删除/替换既有标签、批量改素材类型及 AI 自动分类不在本次范围。
+- 操作对象在打开面板时冻结为去重后的素材 ID 列表，不随后续选择变化扩散；项目切换关闭面板并忽略迟到响应。混合选择含虚拟版本、未登记附件或已删除资源时，不允许只对其中一部分静默保存，入口禁用并给出原因。
+- 批量范围为当前入口展示的完整选中集合：资源面板保留跨筛选的选择时，也必须显示实际目标数量；不得仅修改第一项或仅修改当前可见项。每批最多 200 个不同素材，超过上限要求缩小选择。
+- 原生新增局部命令 `add_local_project_resource_tags`，参数 `input: { projectPath, expectedProjectId, expectedProjectRevision, assetIds, tags }`；仅消费当前 manifest 素材 ID。响应 `{ assets, committedProjectRevision }` 返回整组选中素材最新条目。沿用 `asset.register` 权限、项目身份、写锁及 revision CAS；不新建 manifest schema、数据库字段或外部 API。
+- 原生按锁内最新 manifest 为每项合并标签，沿用现有单标签长度与标签总量限制，先校验全部目标及合并后上限，再一次写 manifest；非法 ID、标签、项目身份或版本冲突不写入任何一项。重复标签重试不重复追加；整批无变化时不推进 revision、不追加修改审计。已写 manifest 后的审计或 revision 异常必须明确返回“已写入”状态信息，沿用既有单资源写入错误语义，不能谎称回滚。
+- 保存期间禁用重复提交及关闭；失败保留待追加标签，CAS 冲突需明确报错而非自动覆盖。成功用原生返回条目刷新宿主 manifest 与筛选统计，不循环调用单素材保存、不按旧闭包覆盖最新其他素材。
+- 单素材标签编辑仍保持既有增删标签行为；菜单信息/类型入口、批量移动、文档与引擎资源预览不得回退。验收覆盖不同原始标签与分类、资源面板/画布多选入口、重复标签、超限及混合选择、批次失败零部分写、一次 revision、项目切换迟到回包和单素材回归。
+- 批量模式的标签输入仅显示待追加草稿，不把各素材已有标签并集作为提交值。资源面板入口放入现有动作行，画布入口沿用选中工具栏的收纳。响应条目按去重后请求 ID 的首次出现顺序返回，无变化时返回当前 revision；DTO 使用 camelCase 并拒绝未知字段，批次上限按去重后数量计算。
+
+## 资源画布生成、展示与布局合同
+
+- 生成工具点击后先在当前栏目创建临时占位卡，并以卡片为锚点展示独立生成浮层；占位不登记为正式素材、不进入 Agent 可引用资源集。上传仍沿用文件选择，不创建虚假生成任务。关闭编辑浮层不应丢失正在执行的任务；切换项目不得将旧项目结果或草稿写入新项目。
+- 图片生成支持从现有素材选择器添加真实参考；引用携带稳定资源身份并经既有原生权限、归属与类型校验传至生成链路，不能仅拼接名称。缺少规范图不阻止打开面板；确有规范前置的操作必须在提交前满足要求，不能绕过后端校验。用户可通过现有工具栏先生成规范图。
+- 占位可移动。提交复用正式生成任务、幂等与结果登记链路；成功结果使用占位最新位置，失败保留输入与引用供重试。已受理但响应不确定时先对账，不能无条件再次发起付费生成。关闭、删除占位和后台任务的行为需保持既有任务所有权，不把隐藏展示当作取消任务。
+- 所有资源卡显示正式素材名称（Agent 生成的 assetName 或用户重命名），没有名称时才使用既有文件名兜底；长名称省略但可查看完整名称。文档卡以居中图标呈现，不显示无效正文片段；独立详情保留原文预览、UI JSON 识别、权限及读取预算。
+- “整理画布”显式重排当前栏目全部素材，包括手动坐标；筛选不缩小整理集合，其他栏目不变。重排作为一次可撤销操作保存，失败继续使用现有写队列及冲突处理，不伪报保存成功。
+- 框选多个素材后拖动任一已选卡，按统一位移移动整个选择集并保持相对位置；拖动未选卡保留单选语义。松手统一提交，整次操作可一次撤销；缩放坐标、指针取消、窗口失焦、保存失败和项目切换不得导致选择丢失或布局串写。
+- 本合同不包含拖入对话批量 @、复制聊天引用、历史替换交互、SpacetimeDB schema 或新的远程公开 API。共享表现与交互优先扩展公共组件，正式资源状态仍由宿主/原生链路维护。
+- 参考选择范围为同一项目已登记图片，可跨栏目、多选，无规范前置时最多 5 张，有规范前置时最多 4 张用户参考（总计最多 5 张）；复用资源引用选择组件，不允许文档、音视频、占位或跨项目素材。本地生成命令补最小引用 ID 参数并转换为当前账号绑定下的远端资源 ID，沿用图片生成 API 已有 `referenceImageSrcs`。需要规范图的普通图片请求合并并去重规范引用，总数不超过现有 API 限制；只接受单规范引用的图集操作不显示用户参考选择器，原生提交拒绝额外参考而非静默丢弃。不得降级成纯提示词。
+- 占位由宿主按项目与独立草稿 ID 管理，提交后关联任务 ID；失败重试使用同一占位。切项目清理未提交草稿与界面位置，已提交任务继续沿用账本恢复，重开后不承诺恢复未持久化的占位位置。迟到结果先核对项目和任务归属；只有本会话仍存在的占位才应用最新位置。删除占位只隐藏展示，不取消后台任务或丢弃正式结果。
+- 参考必须是原生可解码的栅格图片，SVG 不进入参考候选；原生在上传任何引用前预校验整组素材的归属、受控路径、文件及解码，失败不静默丢图。需要重新上传当前账号绑定的参考遵循 `asset.upload` 权限。manifest 读侧的引用形状检查不证明远端账号归属，实际生成始终通过当前账号 binding 解析，不凭历史来源 ID 发起请求。
+- 图片类 GUI 生成通过可选 `targetCategory` 在原生登记时写入入口栏目，使用既有 manifest `category` 字段及合法分类词表；不传时保留按 kind 派生的行为，Agent 不传。该值不改变远端生成内容及计费幂等槽，仅决定本地生成结果分类；重试保持原占位栏目。同路径重新生成时，主产物按本次入口栏目更新分类（包含覆盖此前手动分类），图集附属切片保持既有独立分类规则。
+- 生成面板打开后，占位和面板需处于当前画布标题栏与底部工具栏之间；面板复用公共外观，空间不足时面板内部滚动，提交按钮可达。音频/BGM 占位绑定原有 operation/idempotency 身份，进行中不允许换身份重复提交；失败可用原身份重试，成功结果与图片一样接管占位。关闭未提交浮层保留可继续编辑的草稿，删除占位才丢弃该草稿。
+- 整理范围为当前栏目页全部资源；“所有资源”页为当前项目所有可展示资源，总览不新增整理行为。重排结果成为自动坐标，可撤销恢复原坐标与手动标记；历史仅保留当前会话，切项目清空。多选仅作用于当前画布可见选中资源，不携带筛选隐藏或跨栏目残留选择；取消手势恢复拖动前坐标，切项目清空选择。
+- 当前素材名以现有正式命名链路为准：生成时 assetName 参与落盘名称，重命名更新文件名；卡片消费正式资源 label，不从临时输入或历史任务名覆盖后续重命名，不新增平行显示名持久化。若原有命名链路丢失 assetName，则修复原链路，而非只在卡片本地伪造。文档卡不显示任何正文摘要，但详情原文与 JSON 识别读取不变。
+- 验收覆盖空素材项目进入工具、真实引用入参、成功/失败/重试与迟到响应、占位移动后落点、全类型名称、文档详情、当前栏目重排/撤销、不同缩放的多选移动/撤销以及其他栏目不变。自动化、真实客户端和真实 Provider 验证分别报告；未实际运行的路径不得标为通过。
 
 ## 策划 Agent 批量局部修改
 
@@ -193,7 +232,7 @@ npm 游戏的可预览产物固定为对应 package 目录下的 `dist/index.htm
 
 - `agc_tools` 新增 `agc_list_registered_assets` 与 `agc_create_or_derive_resource`。前者按 `kind / assetId / offset / limit` 有界查询客户端权威 manifest，并可显式返回角色动画正式序列帧的稳定 objectKey、assetObjectId 和尺寸；结果不包含完整 manifest、prompt、model、provider route、签名 URL、宿主路径或凭据。后者只接受 `kind / mode / sourceLocalAssetId / prompt / assetName`，`create` 仅允许无源视频、音效和背景音乐，`derive` 必须引用当前项目已登记的 localAssetId，角色动画固定为 derive。
 - `prompt` 上限按 `kind` 分别生效，且工具 schema、MCP 校验、客户端工具桥与提交校验共用同一权威口径（`resource_edit_prompt_max_chars`）：背景音乐 140、音效 1900、视频与角色动画 4000、图片编辑 32000。schema 逐 kind 声明 `maxLength` 并在 `prompt` 描述里写明数字，超限必须在发起任何桥请求与付费提交之前失败并回报真实上限；`sourceLocalAssetId` 不是当前项目已登记资源时，错误文案必须直接给出 `agc_list_registered_assets` 与 `agc_list_project_files` → `agc_import_account_assets.localPaths` 两步后续动作。
-- 项目路径、projectId、当前 revision、源文件路径与媒体类型、operationId、Idempotency-Key、登录态、项目锁、付费提交、轮询恢复、下载校验与 manifest 事务全部由客户端持有。模型不能提交或覆盖这些字段。同一 Direct `clientTurnId + 规范语义参数` 生成稳定 UUID v4 身份；单回合同参重试复用原 operation，不同请求串行且最多四项。跨回合存在完全匹配的 pending 账本时优先恢复原 operation，不能换键重发。
+- 项目路径、projectId、当前 revision、源文件路径与媒体类型、operationId、Idempotency-Key、登录态、项目锁、付费提交、轮询恢复、下载校验与 manifest 事务全部由客户端持有。模型不能提交或覆盖这些字段。同一 Direct `clientTurnId + 规范语义参数` 生成稳定 UUID v4 身份；单回合同参重试复用原 operation，不同请求串行且最多四项（不计费的抠图派生请求不占该额度，见决策记录 2026-09-18）。跨回合存在完全匹配的 pending 账本时优先恢复原 operation，不能换键重发。
 - 资源查询同时投影未完成 operation 的安全状态。媒体工具成功只返回 operation、本地相对路径、资源类型、Canvas/resource/asset/task 身份、正式序列帧以及脱敏后的 `warnings / sliceWarnings`；错误继续使用统一脱敏边界。客户端资源账本持久化 completed 结果的两类告警，committed replay 不能把历史告警伪装成空集合。
 - 角色动画、视频、音效和背景音乐在构造新的远端请求前统一准备当前项目同名画布与素材目录上下文，并在端点支持时携带 `projectId / assetFolderId / canvasCompletion`。角色动画 placeholder 使用源图片真实宽高，避免非方形角色进入画布时失真；正式 resource/asset 与序列帧继续直接复用 External 返回身份，不从首帧伪造重复资源。已有冻结 request body 或已受理 operation 保持不变，不因本次升级重建请求或重复扣费。
 - 抠图通过新增 `agc_remove_background` 语义工具开放：模型只提交当前 manifest 的图片 `sourceLocalAssetId` 与结果名称；客户端解析稳定 `resourceId`，准备同名画布/素材目录并生成稳定 operation/idempotency 身份。普通登录态使用账号鉴权的 `/api/editor/images/background-removals`，ExternalDeveloper 模式使用 External v1 `/api/external/v1/editor/images/background-removals`；客户端接收异步受理后轮询任务状态，下载完成媒体并登记到本地 manifest，未知结果保留同一 operation 供恢复。抠图服务仍由客户端和服务端负责源校验、BgFilter、素材登记与画布事务，Codex 不获得内部 worker、凭据或任意 API 调用权。
@@ -382,6 +421,11 @@ Supervisor 认领该回执后，由父 run 自己为每个原 delivery 逐一创
 - 调度边界：正式 DAG、manifest、Agent task/session/run 身份、队列、锁、委派、all-join、完成门、Provider lifecycle、持久 retry/handoff 与 `needs-reconciliation` 继续由现有 AGC Runtime 掌控。每个被调度节点在 `codex_cli` 模式下直接启动一次非交互 `codex exec` 充当该节点的推理 Agent；Codex 返回当前 Runtime 广告函数的结构化调用，Runtime 仍是唯一 ToolHost，不允许 CLI 自己写项目、执行命令、调用 MCP 或形成第二套 revision / verification 真相。
 - 安装包侧车：Windows x64 release 固定随 Tauri resource 打包 `@openai/codex@0.147.0` 的原生 `codex.exe`；Rust build script 从 AGC 子包锁定依赖 stage 到 resource，并写入版本与 SHA-256 清单。Windows 侧车映射只写入 `tauri.windows.conf.json`，通用 `tauri.conf.json` 不得让 Linux / macOS 构建依赖未生成的 Windows 二进制。运行时只在文件摘要和 `codex-cli` 版本同时匹配清单时优先选内置侧车；缺失、损坏或版本漂移时跳过它，按既有 npm 安装、PATH 顺序回退。安装包同时携带 Apache-2.0 第三方声明；API Key、`auth.json`、Cookie、Token、用户 `CODEX_HOME`、用户配置和项目数据绝不打包。
 - Windows x64 release 安装包只生成 NSIS，不生成 MSI：`tauri.windows.conf.json` 的 `bundle.targets` 固定为 `["nsis"]`，通用配置继续保留其它平台的默认打包目标。安装后的产品名、开始菜单 / 桌面快捷方式和 EXE 产品描述统一由 `tauri.conf.json` 的 `productName: "陶泥儿"` 生成；应用 identifier 与内部可执行文件名保持稳定。内置 Codex 资源安装到顶层 `coding-agent/win-x64/`，运行时从同一路径查找 `bin/codex.exe` 与 `manifest.json`；仓库 staging 仍使用 `resources/codex/win-x64/`，包内子目录、组件名、版本和完整性校验保持原合同。
+- macOS 单架构安装包同样必须携带锁定版本的原生 Codex、`codex-code-mode-host`、`rg`、上游 zsh、`codex-package.json` 和第三方声明，保留上游相对布局；构建时按 Cargo 目标选择 npm 原生依赖，缺文件、版本或目标不匹配立即失败，不借用开发机 PATH 里的 Codex。资源只在 `tauri.macos.conf.json` 映射到 `Contents/Resources/coding-agent/mac-native/`。构建与运行共享平台文件白名单，运行时由当前 `.app/Contents/MacOS` 定位相邻 `Resources`，完整性与版本验证通过后优先使用内置组件；失败沿既有外部安装回退，不能运行未校验的内置文件。单架构资源不能冒充 universal 包。
+- 内置插件的清单、运行入口与面板同时在 Windows/macOS 随包分发，继续由既有 PluginHost 的应用资源目录扫描入口发现；不携带开发依赖、缓存、测试或私有配置。插件文件随包不等于原生适配器跨平台：Cocos 进程桥接仍受现有 Windows 实现和 feature 门禁约束，macOS 原生桥接另行设计与验收，不复制 Windows DLL 冒充支持。系统 Node、用户 Cocos Creator、账号登录、网络和生成工程的 npm 工具链仍是现有外部前提，不在此次 Codex 侧车补齐中隐式变更。
+- macOS 安装包验收必须包括：脱离仓库位置的 `.app` 资源与架构检查、受限 PATH/隔离 HOME 下内置 Codex 启动和 app-server 握手、必需文件缺失/篡改/平台错误的拒绝测试，以及 DMG 完整性检查。真实登录、Provider 对话、GUI 和 Cocos 操作必须独立列出证据，不能用压缩包生成或 `--version` 成功替代。未配置正式签名、公证的本地测试包不得作为公开发行包。
+- macOS 安装包的系统下限取主程序和全部原生组件中的最高要求；锁定 Codex 0.147.0 原生依赖所携带的 zsh 要求 macOS 15.0，因此 `bundle.macOS.minimumSystemVersion` 明确为 `15.0`。更新原生依赖时重新检查 Mach-O 的系统下限，不能只按 AGC 主程序宣称兼容版本。
+- 发布链路的目标解析和单架构清单以《AGC客户端更新检查与下载》为准：CLI 目标优先，版本、构建、端点、bundle 与更新清单共用单一发布上下文。插件能力以《AGC通用插件宿主与编辑器适配》为准：无已注册 Cocos 原生适配器时隐藏且拒绝启动，前端自动启动只消费后端可用性投影。
 - CLI 安全边界：CLI 固定使用 argv 启动，禁止 shell 拼接；工作目录使用本次请求专用的空临时目录，不把游戏项目绝对路径写入 prompt、stdout、stderr 或持久记录。调用固定使用 ephemeral、忽略用户配置和 exec rules、read-only sandbox、never approval，并关闭 Codex shell tool；只继承 CLI 运行和认证所需的最小环境，显式移除宿主 `CODEX_API_KEY`。用户级 Codex 登录态继续由本机 Codex 自己读取，API Key、auth 文件、Cookie、Token、`CODEX_HOME` 私有内容不得复制到项目配置、Runtime sidecar、Agent DB、conversation 或日志；stdout / stderr 无换行时也受硬上限约束，stderr 诊断只记录固定分类、字节数和 SHA-256。
 - 协议边界：Runtime 把既有 `LlmRunRequest` 的消息和当前函数目录编码为有界 prompt，并从同一函数 JSON Schema 生成 Codex structured-output schema。CLI 输出转换为现有 `LlmRunResponse / LlmToolCall` 后，继续经过 native tool / MCP 参数校验、动作上限、权限、pending、receipt、验证与格式修复链；最终回复仍走唯一提交路径，不新增平行响应协议。
 - 取消与恢复：Codex 子进程绑定当前 Provider request lifecycle，取消、暂停、Runner draining 或 GUI owner 丢失时终止并回收当前进程；started 后没有可信终态仍沿现有 Provider reconciliation 处理。`agentMode`、CLI 可执行身份和影响输出的 Codex 参数进入 `providerConfigFingerprint`，模式切换不得消费另一模式遗留的 retry/handoff。

docs/technical/【技术方案】GameAgent对话工具调用卡片-2026-09-14.md

@@ -11,7 +11,38 @@
 
 ## 一句话交付
 
-把 GameAgent 右侧对话面板里的「执行命令 / 写文件 / 调工具」从一行中文进度文本，改成 Codex 桌面客户端那样的**可折叠卡片**（折叠态一行摘要，展开态看命令与文件明细），并且在**刷新页面、重开项目后仍然存在**。
+把 GameAgent 右侧对话面板里的「执行命令 / 写文件 / 调工具」改成可折叠卡片，整轮总耗时只在回合状态/完成小结显示一处，工具组与内部工具分别显示各自耗时；运行中的计时动态增长，不足一分钟保留一位小数，达到分钟后显示整数秒。
+
+## 总耗时与动态工具计时
+
+### 紧凑过程入口与 Markdown
+
+- 思考过程、执行过程和工具组统一为无大块底色的单行折叠入口：左侧小图标/简短预览，最右侧展开箭头；长文本省略，不把箭头挤出窄聊天列。沿用共享过程色和 12px 层级，键盘可展开、有可见焦点。
+- 思考折叠态直接显示浅色的内容预览，而不是只有“思考过程”标题；预览不显示 Markdown 控制符、原始 HTML 或链接地址。展开后复用现有安全 Markdown 渲染链路，支持段落、强调、列表、链接、代码块等，不开启原始 HTML 执行。实时与历史、当前 Agent 与策划 Agent 使用同一呈现。
+- 思考入口使用灯泡图标；展开后入口文字切换为“思考过程”，原内容仅在 Markdown 正文显示一份，不同时保留相同摘要。收起后恢复浅色内容预览；键盘开合与鼠标开合行为一致。
+- 回合结束后最外层“执行了 N 个操作，耗时 XXX”使用正文颜色；收进该折叠层的内部过程保持运行中原有颜色、行高和块间距，不能因额外 Grid gap 与子元素 margin 叠加而拉大间距。
+- 思考与工具组按紧凑连续列表呈现，相邻过程块间距 4px，内部工具行使用紧凑的 2px 上下内边距；运行与完成后的容器使用同一口径。失败工具的名称、图标、状态及耗时使用错误红色，所属组摘要有“有操作失败”提示且标红；同组其它工具仍运行时也不能吞掉失败标识，成功行不得被连带染红。
+- 工具组摘要只统计本组工具条目总数，显示“执行了 N 个操作，耗时 XXX”；运行中另有状态提示，不把操作数称作成功数，失败仍保留明确状态。回合外层执行过程统计所有工具块的操作数，不把思考段落或文本消息当工具操作；缺失耗时不伪造。
+- 所有 AGC 耗时统一用中文时分秒：不足一分钟显示 `5.2秒`，达到分钟后显示整数秒，如 `2分05秒`、`1时02分05秒`。省略前导零单位，带小时则保留两位分钟，带分钟则秒补齐两位整数；先整体舍入再拆分单位，避免出现 60 秒/60 分。工具行、组、整轮、生成任务及策划耗时共用一个纯格式化函数，不改变各自计时来源和动态刷新。
+- Direct 对话发送后、本轮首个可见思考/文字/工具响应到达前，在消息列表内、工具调用块外临时显示“思考中…”。收到首个响应后移除，失败、取消和空闲时同样不显示；直接从现有忙碌状态与本轮投影派生，不新增原生事件、定时器或持久化消息。工具间等待不在本次轻量实现范围内。
+- 独立计时保持不变，组状态/用时在单行中作为次要信息，空间不足可移至展开内容，不能占第二行破坏紧凑入口；整轮总耗时仍只显示一次。工具输入/输出、失败信息与操作明细不因样式变更丢失。
+- 只改展示与对应测试，不改变消息身份、分组顺序、生成或原生执行语义。验证覆盖 Markdown 安全与语义、预览省略、准确计数、展开/键盘操作、窄屏布局及原有计时冻结。
+
+- “总耗时”表示同一轮用户请求从发送到回合终态的墙钟跨度，包含 LLM 推理、工具调用和等待；只在本轮运行状态或完成小结显示，不重复放进各工具组。
+- 工具组顶部“执行了 N 个操作，耗时 XXX”中的耗时范围是本组首个工具开始到最后一个工具完成，包含组内等待但不是工具耗时之和。不同工具组独立计时；本组全部终态后立即固定，即使本轮或后面的工具组仍运行，也不能显示“进行中”或继续增加。组头不展示发送/结束时刻，不沿用用户发送时间计算本组。
+- 回合仍运行但全部工具暂时结束时，只增长本轮总耗时。成功、失败或终止到达后整轮按实际终态时间固定；随后打开折叠块、翻页或其它回合的新事件不得改变已完成的组或回合用时。
+- 单条工具从其实际开始到完成计时。运行中的工具按当前时间持续增长，不能把最近一次快照更新时间当作当前时间；已经结束的工具必须立即固定，即使同组其它工具或 LLM 仍在运行。
+- 对话的组、工具及整轮耗时运行中均每 100 毫秒刷新，统一使用上述中文时分秒格式。以时间戳计算而不是按 tick 累加，避免后台节流后的累计漂移；缺失或倒序边界不伪造 `0.0`。非对话场景只统一文本格式，不改变原有刷新或后端累计时间语义。
+- 各层时间范围与对应耗时使用相同的起止边界。运行标记也按本层状态判定；完成后如果展示起止时间，其精度不得造成范围差与用时矛盾。组内存在缺失或倒序的工具边界时，不能用其他组或整轮的时间补造本组耗时。
+- 原生事件保留各阶段的时间语义：开始与完成不能都优先折叠成开始时间。优先采用上游明确提供的阶段时间或实际调用时长，缺失时使用宿主观察该阶段的时间；重放沿用原事件时间，不能在前端收到或重放时重新取当前时间。
+- 工具开始/完成的权威边界是事件级 `at`，不是条目展示字段 `item.at`。整轮起点优先采用该轮实际用户消息的发送时间（与气泡一致，不取所有条目的最小时间），缺失时采用原生 `turn.started.at`；终点只采用 `turn.completed.at` 或明确的终止/失败收口事件。首次补到更早的真实发送时间可以校正起点，但旧历史或重复事件不能覆盖已经固定的终点。
+- 回合阶段使用宿主观测阶段的毫秒时间，或上游明确的毫秒边界/可靠时长；不把上游已截断的整秒时间冒充十分之一秒精度。回合是否开始以 Thread Manager 的事件顺序为准，不能用时间戳大小拒绝取消后同一秒内的新请求。回合完成的展示时间在当前会话中冻结；重新打开后若历史未保存完整生命周期边界，则隐藏未知用时而非补造。
+- 无效边界包括缺字段、非有限值、时间戳为 0、结束早于开始；这些情况隐藏不能证明的耗时。合法开始时刻的运行中 `0.0秒` / `0.0s` 则正常显示。只有完成快照而没有开始事件的工具不猜测开始时间。
+- 沿用 Thread Manager 的生命周期与条目身份，不引入第二套回合状态源、计时账本、远程 API 或数据库字段。前端仅保存原事件的展示时间边界；旧历史缺少完整边界时不声称知道精确总耗时或工具耗时，不为补齐计时启动模型请求。
+- 必须覆盖：前组已完成而后组运行时各自时间独立、整轮总耗时仅出现一次、无新事件仍增长、工具完成后 LLM 继续、并行工具分别计时、完成/失败/终止冻结、同身份重放不改终态时间、切项目与卸载停止计时、缺失与倒序时间、0.0 / 59.9 / 60.0 秒边界。真实 Provider 验证与模拟事件的客户端验证分开报告。
+- Direct 对话的初始消息占位仅在正式用户消息尚未进入当前显示链路时显示；正式条目或乐观用户条目出现后撤下占位，不在消息列表外额外保留一份。只控制占位是否显示，不按文本合并或删除用户真实重复发送的消息；分页已有更早历史时不把初始占位补到当前页。
+- 同一用户消息从本地发送转为正式条目时必须保留原发送时间，不能因去重丢掉该时间而改用启动应答后的观测时间。回合明确结束时，即使当前 live 集合为空，也应将终态边界关联到已知的本轮用户条目；不得仅按“历史最后一项”猜测或向无关旧回合补时间。
+- 生命周期事件可携带已有用户条目的 `userItemId`，用于把时间边界精确关联到同一条历史消息（不产生新的回合 ID 或持久化字段）。恢复时该关联随 Thread Manager 原事件重放；带旧用户身份的终态不能收口另一条新请求。缺少身份的旧事件不据时间猜测归属。
 
 ## 背景与现状（已核实）
 
@@ -74,21 +105,20 @@ DirectRuntime 写 `<projectRoot>/.agent/conversations/tool-calls.jsonl`；回读
 ```html
 <section class="agent-tool-call-group" data-testid="agent-tool-call-group" data-status="completed">
   <button type="button" class="agent-tool-call-group-head" aria-expanded="false" aria-controls="…"
-          aria-label="已执行 2 个命令、1 个文件变更，用时 42秒">
+          aria-label="执行了 3 个操作，耗时 42.0秒">
     <span class="agent-tool-call-group-icon" aria-hidden="true"></span>
-    <span class="agent-tool-call-group-summary">已执行 2 个命令、1 个文件变更</span>
-    <span class="agent-tool-call-group-time">14:20:05 → 14:21:02</span>
-    <span class="agent-tool-call-group-duration">用时 42秒</span>
+    <span class="agent-process-summary-preview">执行了 3 个操作</span>
+    <span class="agent-process-summary-meta">，耗时 42.0秒</span>
     <svg class="agent-tool-call-group-chevron" aria-hidden="true"></svg>
   </button>
   <div class="agent-tool-call-group-body" hidden>
     <ul class="agent-tool-call-group-rows">
       <li class="agent-tool-call-group-row" data-testid="agent-tool-call-row" data-kind="command" data-duration-ms="12300">
         <button type="button" class="agent-tool-call-row-head" aria-expanded="false" aria-controls="…"
-                aria-label="已运行 npm run build，耗时 12.3s">
+                aria-label="已运行 npm run build，耗时 12.3秒">
           <span class="agent-tool-call-row-icon" aria-hidden="true"></span>
           <span class="agent-tool-call-row-text">已运行 npm run build</span>
-          <span class="agent-tool-call-row-duration">12.3s</span>
+          <span class="agent-tool-call-row-duration">12.3秒</span>
           <svg class="agent-tool-call-row-chevron" aria-hidden="true"></svg>
         </button>
         <div class="agent-tool-call-row-detail" hidden>
@@ -103,10 +133,10 @@ DirectRuntime 写 `<projectRoot>/.agent/conversations/tool-calls.jsonl`；回读
 ```
 
 - 文案规则（按 kind，不允许自由发挥）：
-  - 块头汇总按 kind 计数、顺序固定 `command → file_change → mcp_tool → web_search → context_compaction → other`，标签 `命令`/`文件变更`/`工具调用`/`联网搜索`/`上下文整理`/`其他操作`，形如 `已执行 5 个命令、2 个文件变更`；空集合不渲染块。
+  - 块头按实际工具条目计总数，形如 `执行了 7 个操作，耗时 1分05秒`；空集合不渲染块。操作数不是成功数，失败与运行状态仍单独可见。
   - 行文案：展示工具摘要，不重复添加动词前缀；`context_compaction` 固定为“整理上下文”。状态单独放在行尾（执行中 / 已执行 / 失败），`failed` 使用现有 `--platform-*` 错误色；已结束回合不因残留 `running` 快照显示“执行中”。
-  - 耗时：单条工具 = `startedAt` → `updatedAt`，块头总用时 = 该回合所有工具的 `min(startedAt)` → `max(updatedAt)`。单条格式：`<1s` → `0.4s`、`<60s` → `12.3s`（整秒省略小数）、`≥60s` → `2m 5s`；块头格式：`42秒` / `4分钟` / `5分钟 45秒`。`startedAt` 为 0 或 `updatedAt < startedAt` 时不显示耗时（不显示 `0s` / 负数），耗时为 0 时同样不显示 `0s`。
-  - 时间：块头显示该回合结束时间（`max(updatedAt)` 的本地 `HH:mm:ss`）；同一回合能拿到用户消息时间（`updatedAt > 0`）时显示 `HH:mm:ss → HH:mm:ss`（发送 → 结束），取不到就只显示结束时间，不编造。
+  - 耗时：执行“总耗时与动态工具计时”合同。块头是本组用时，单条是该工具独立耗时，整轮总耗时只在本轮状态/小结显示；不足一分钟显示一位小数，达到分钟后显示整数秒，运行中每 100 毫秒刷新，各自终态固定。
+  - 时间：范围与对应层级用时采用同一边界，不把用户发送起点与局部工具组终点混搭。缺失的历史时间不编造。
   - 回合结束时间与耗时在正文下方右对齐；Direct 对话输入框提示统一为“描述你的想法，或 @ 引用素材”，引用按钮保留输入盒的 12px 内边距，不使用负边距贴边。
   - 当前 Agent 与策划 Agent 共用 `packages/shared` 的 `AgentMessageContent` 表现组件：正文为 14px / `--platform-text-strong`，思考、中间输出和工具调用为 12px / `--platform-text-soft`。实时与历史思考共用同一个折叠入口；工具输入输出继承过程色，失败状态保留错误色。Markdown 标题、表格及代码高亮在过程区同步弱化，最终回复和文档预览仍保留正常排版，不按 Agent 类型复制样式。输入提示与禁用状态保持原有反馈。
   - Windows 命令展示：仅 `command` 卡片识别 `pwsh` / `powershell`（含完整路径、`.exe`、常见启动选项）的 `-Command` / `-c` 外层包装，摘要和展开输入只展示脚本正文，并解开单个 shell 参数的引用拼接。摘要优先读取已脱敏的 `detail.command`，再按首行 120 字符截断，避免历史摘要被可执行文件路径占满。无法识别的启动方式、`-File`、`-EncodedCommand`、普通命令和 MCP 输入原样展示；执行参数、持久化原文、脱敏和输出均不改变。