@@ -1,5 +1,13 @@
# AI 游戏创作智能体 App 实施计划
## 2026-09-08 Web 游戏 npm 与 Phaser 4 产物合同
新建 Web 游戏使用 npm 工程：默认 `game/package.json` 声明 Phaser 4.2.1 和 Vite 构建工具，源码使用 `import Phaser from 'phaser'` ， `package-lock.json` 由 npm 维护。默认脚手架文件位于 `game/` ，包含 `index.html` 、`game.js` 、`style.css` 、`vite.config.js` 和 npm 配置/锁文件；已有根目录 npm 工程沿用原根，可按需求拆分模块并添加任意其它 npm 依赖，不设置包名白名单。客户端不手工分发 Phaser bundle，不用 import map 模拟 package 导入。
Agent 在包含 `package.json` 的目录执行 `npm ci` （依赖变更使用 `npm install` ）和 `npm run build` ；默认可从工作区根执行 `npm --prefix game ci` 与 `npm --prefix game run build` 。DirectProject 保持 workspace-write 目录边界并开放网络，以支持 npm 依赖解析和安装；凭据仍由客户端代理持有，不进入项目或原生命令环境。其它执行模式维持现有权限。新游戏完成后执行 `npm run build` 并用真实浏览器试玩；依赖安装与构建失败必须反馈真实错误，不能回退成未解析裸模块导入的静态页面。
npm 游戏的可预览产物固定为对应 package 目录下的 `dist/index.html` ，静态 smoke 校验构建入口及本地文件引用，实际可玩性由浏览器验证。预览服务与导出读取该构建目录，所有运行素材必须由构建纳入 dist；npm 预览不回退读取源码或项目素材目录，保证试玩与导出一致。源码投影包含 package、锁文件、配置和真实游戏源码，排除 `node_modules/` 、`dist/` 、控制文件与凭据；npm 试玩包将 dist 文件映射到 `game/` 并附带发布说明，不包含源码依赖安装目录。现有单 HTML 项目不自动迁移，Godot 项目保持原合同。旧 JSON Generator 仅接受已初始化的单 HTML 项目，npm 项目或新建请求在调用 LLM 前明确拒绝并引导使用 DirectProject，避免静态草案伪装为 npm 构建产物。本节覆盖下文仅适用于旧单 HTML 产物的 Canvas API、手写动画循环和禁止外部本地脚本要求。
## 2026-09-02 项目名称显示与自动提炼
- `.agent/manifest.json` 的 `name` 仍是本地项目显示名唯一事实源；项目组页行尾更多菜单提供行内重命名，保存必须走 Tauri 受控命令、项目写锁、manifest 写锁与既有 ACL/权限校验。重命名只更新 manifest，不改变项目目录、`projectId` 、项目类型、任务、资源、版本或远端同步状态；保存成功后当前项目上下文、窗口标题和最近项目检查结果必须回读新 manifest 并保持一致。
@@ -58,6 +66,10 @@ Runtime 确认卡与普通聊天确认卡必须共用“信息区 + 固定操作
## 2026-08-19 UI Editor 节点右键菜单
## 2026-09-05 UI Editor 节点树快捷删除
左侧 `UI Tree` 每个可删除节点行在右侧提供桌面端快捷删除按钮，眼睛与删除按钮组成固定宽度的右侧动作列；整棵树保留横向滚动，深层节点的缩进、完整名称和组件数随树内容一起滚动，不使用省略号截断。沿用右键菜单的页面根节点禁删规则。快捷删除与右键删除共用页面级 `requestDelete` 入口：叶子节点直接调用现有删除命令；包含后代节点时先打开模态确认，正文显示节点名称及将同时删除的后代节点数量，按钮为“取消 / 删除”。确认期间使用现有 `ThemedModal` 的模态行为，取消或完成后关闭弹窗。底层 `deleteNode` 命令继续保持无确认，以兼容键盘 `Delete` 及已有状态测试；锁定态下快捷按钮和右键删除均不可执行。
## 2026-08-20 UI Editor 最终预览互斥子节点
最终预览中，选中一个 `Exclusive` 父节点时，它的子节点切换条必须在该父节点自身的预览坐标空间内、紧贴节点上方悬浮；不得固定在预览容器左上角，也不得另行按屏幕坐标换算。点击 tab 必须显式选中对应子节点，不能按通用“切换可见性”语义把当前分支隐藏。`Exclusive` 父节点首次加载且尚未发生可见性操作时，必须默认且仅显示第一个直接子节点；用户手动隐藏全部直接子节点后必须保持全部隐藏，不得再次回退显示第一个子节点；空容器不显示子节点。切换条始终按内容宽度展开并允许溢出节点边界，不设最大宽度或内部滚动区域。从 `Exclusive` 切回 `Stack` 时必须清除全部直接子节点因互斥选择产生的隐藏状态并立即显示所有子节点，后代节点自身的独立隐藏状态保持不变。切换条仅改变现有子节点可见性状态，不能触发参考图重读、视口重新适配或预览树的异步重建。
@@ -234,6 +246,13 @@ Supervisor 认领该回执后，由父 run 自己为每个原 delivery 逐一创
- 旧配置迁移：既有 AppData 若没有 `agentMode` ，只有全局和逐 Agent 路由均为 `openai_responses` 时迁移到 `codex_app_server` ；存在 `openai_chat / anthropic` 时显式保留 `provider` ，避免打开项目自动恢复时把所有节点批量写成 `invalid-config` 。用户确认端点支持 Responses 后，可在设置中显式切换并保留原 model/base URL/API Key。
- 验收：fake JSON-RPC fixture、三态 UI/config、配置指纹、unknown-terminal 零重放、旧两种模式回归和显式 ignored 真实 smoke 全部通过后，才可视为模式切换完成。
### 2026-09-03 AGC 客户端能力以 MCP 暴露
- MCP 暴露是客户端能力层，不替换 `codex_app_server / codex_cli / provider` 或客户端对话。客户端对话入口继续驱动 Codex app-server；
- MCP 会话在客户端握手时绑定当前账号、项目和实例，工具参数不得携带 `projectPath` 、Token、Cookie、objectKey 或内部 URL。仅暴露稳定业务白名单与 `resources/list/read` ，所有文件、资源、画布、预览和 operation 副作用继续复用客户端权限、锁、计费、幂等账本、manifest/revision 与恢复机制。
- 客户端对话继续写入现有 conversation projection；外部 Host 如需旁路保存返回文本，可显式调用 `conversation.record_codex_response` 。客户端将有界、脱敏正文、SHA-256、安全摘要和状态追加到项目级 journal，UI 只展示记录，不从文本推断业务状态或触发副作用。
- MCP 子进程只由当前客户端为绑定项目启动，并在该项目工作目录内运行；客户端回合结束或客户端退出后子进程随 Codex app-server 一并回收。账号和项目权限仍由客户端业务桥接层校验，未知副作用保持 `needs-reconciliation` ，只能通过 operation 查询恢复。稳定验收覆盖客户端对话驱动的 MCP 工具调用、Skill 指导资源、跨项目/账号拒绝以及旧 Provider/Codex 回归。
### 2026-08-10 Supervisor 边做边聊与条件中断
- 根 Project Supervisor 的运行中消息继续进入当前 `taskId / sessionId / runId` ，先持久显示“正在判断、当前任务继续”，再由独立 LLM 生成非终态语义回复并给出 `interruptCurrentProvider` 。过程回复不能调用终态 `respond_to_user` ，不能把制作 Run、Goal 或 task 提前完成。
@@ -870,7 +889,7 @@ game-project/
- 聊天输入 `/status` 会读取 `.agent/manifest.json` 并在聊天里汇总项目目录、任务状态、资产数量、预览状态和最近命令，不向普通用户暴露任务或文件面板。
- 聊天输入 `/files` 会通过 `file.list` 只读列出本地项目内的文件摘要；主窗口最近项目文件可一键读取，也可一键填入 `/read` 或 `/asset-register` 草稿，但资产登记仍必须走聊天确认；`/checkpoints` 复用 `file.list` / `file.read` 只读列出最近 checkpoint id、文件数、大小和可复制的 `/diff` / `/restore` 命令，主窗口最近 checkpoint 列表也可填入对应草稿；普通用户仍不暴露文件读写面板。
- 聊天输入 `/assets` 会读取 `.agent/manifest.json` 并在聊天里列出本地项目资产路径、类型和来源，资产列表消息和主窗口最近项目资产入口都可一键填入对应资产的 `/read` 草稿；聊天输入 `/art` 只使用当前已加载 manifest 盘点美术素材，并提供首版美术生成或读取美术清单草稿，不直接读取文件、不触发平台生成或画板同步；聊天输入 `/audio` 只使用当前已加载 manifest 盘点音频素材，并提供登记音效或读取音频清单草稿，不直接读取文件、不触发资产写入；`/asset-register 路径 [kind] [mediaType]` 可确认后登记项目内已有资产；主窗口音效快捷入口只填入 `/asset-register assets/audio/sfx.wav audio audio/wav` 草稿，不直接写 manifest；普通用户仍不暴露资产面板。
- 聊天输入 `/read 本地相对路径` 会通过 `file.read` 只读返回项目内文本文件内容并在聊天中截断长文本；普通用户仍不暴露文件写入或删除能力。
- 聊天输入 `/read 本地相对路径` 会通过 `file.read` 只读返回项目内文本文件内容并在聊天中截断长文本；聊天回执中的正文必须包装为安全的 `<pre><code>` 代码块，保留源码字面量但不得执行 HTML； 普通用户仍不暴露文件写入或删除能力。
- 主窗口常用生成产物入口只把 `game/index.html` 、`game/game_design.md` 、`game/balance.json` 、`assets/manifest.art.json` 、`assets/manifest.audio.json` 和 `exports/README.md` 的 `/read` 草稿填入聊天输入框；聊天输入 `/artifacts` 只列出这组固定读取命令并提供首个 `/read` 草稿，聊天输入 `/run-artifacts` 只列出最近 run trace 里的产物读取命令并提供首个 `/read` 草稿，聊天输入 `/run-files` 只列出 `.agent/output.jsonl` 、`.agent/activity.jsonl` 和 `.agent/context.bundle.json` 的读取命令并提供首个 `/read` 草稿；读取仍由聊天侧 `file.read` 权限流执行。
- 聊天输入 `/logs` 只列出 `.agent/logs/command.log` 、`.agent/logs/preview.log` 和 `.agent/logs/agent.log` 对应的 `/read ...` 草稿 / 命令，并提供首个 `/read` 草稿；该命令不直接读取日志，不新增普通用户日志面板，实际读取仍由聊天侧 `file.read` 权限流执行。
- 聊天输入 `/tasks` 会读取 `.agent/manifest.json` 并在聊天里列出专业组、角色、任务状态、产物交接和下一步可执行任务；普通用户仍不暴露任务面板。
@@ -1063,7 +1082,7 @@ game-project/
- 内部 owner 验证只接受 GUI / CLI 完整 16 任务 DAG 中 `agent-ready-task-scheduler` 启动的确定性直接 child、当前活跃根和完整 project/source/profile/Agent/run/parent/root/binding 身份。错误 source、delegated run、历史或终态根、非当前活跃根、跨 Agent/run 凭证均失败关闭；再次 mutation 使旧凭证失效，相同身份恢复可按当前事实确定性重验。本阶段不扩到后置 `publish-package` 。`code-prototype` 与 `preview-readiness` 继续执行真实 `game.static_smoke` ， `preview-playtest` 继续独立执行浏览器验收；任何 owner 文件凭证都不能替代可玩证据。
- `design-foundation` 的 2026-07-26 职责隔离继续有效：项目文件仍只允许 `memory/project.md` 、`game/game_design.md` 和配置 Key 时的固定 `assets/ui-prototype.png` ，禁止修改 `game/index.html` 、调用 smoke / preview / process 或恢复整项目。未配置 External Editor API Key 时 `art-director` 保持只读协调；配置 Key 时它是条件 Canvas owner，必须生成并登记 `assets/art-spec.png` ，成功 `canvas.asset_generate` 为本人当前 revision 形成普通验证凭证，不能被只读分类吞掉。配置 Key 时 UI 原型、透明图集、Canvas 登记和视觉门仍按既有合同执行，内部 owner 文件验证不替代图片证据。
- `canvas.asset_generate.replaceExisting` 默认并必须保持 `false` ；只有静态专业 Agent 的 `delegated-*` 唯一 repair run 才能申请 `true` 。Runtime 要求当前 delivery 带 `repairOfDelegationId` ，原 delivery 已被同一父 Agent / 父 run 认领，原始与返工合同的目标 Agent 和精确 `expectedArtifacts` 路径一致；普通 run、未声明路径、错误 Agent、未认领原交付或缺失原图都失败关闭。图片生成仍服从 `art-director` / `design-foundation` / `art-asset-plan` 的固定输出路径、比例、尺寸、kind 和 label，禁止先删除正式图片；请求前记录旧文件 SHA-256，外部生成返回后在项目写锁内复核，旧图在网络请求期间变化即拒绝覆盖。授权替换先写私有临时文件，再以备份 / rename 切换；落盘或 manifest 登记失败时恢复旧图，不把新旧文件并存状态当作成功。
- 在既有 16-task manifest 内固定正式视觉 DAG，不新增平行任务系统： `art-director` 用当前调用模式的图片生成 `kind=spec` 生成 `assets/art-spec.png` 并登记为 `assetKind=icon-spec` ； `design-foundation` 使用该规范图的稳定资源 ID 作为视觉规范参考，用同模式图片生成 `kind=ui-design` 生成 `assets/ui-prototype.png` ； `art-asset-plan` 以同一 resource ID 调用同模式图标 spritesheet 生成，产出透明 `assets/art-spritesheet.png` `/api/editor/*` ， `/api/external/v1/*` ； 业务请求、依赖和验收完全一致。规范图缺失、未登记或缺少稳定资源 ID 时，下游任务不得退回普通生图。图集 warning、透明像素与切片门禁 保持不变。
- 视觉 Agent 只负责指导 Codex 选择合适的图片/编辑/图集工具并提供项目上下文，不再固定图片数量、文件槽位、素材类别或 spritesheet 布局；请求可按玩法需要生成单图、多图或任意切片布局 。普通模式使用内部 `/api/editor/*` ， `/api/external/v1/*` ； 权限、计费、幂等、资源登记和安全校验 保持不变。
- 旧项目已有同路径派生图但缺少上述 provenance 时，一律标记为 legacy，不得只因文件、kind 或通用视觉检查存在就完成。原位替换仍走显式 repair：`design-foundation` 与 `art-asset-plan` 先在同一 Supervisor 批次分别建立 owner 精确原合同并交付 `needs-repair` ，父 run 认领后再在同一批次分别发起各自唯一 repair；两个 repair 合称一个显式视觉返工阶段。`art-director` 不得跨 owner 声明或替换 UI / spritesheet，
- 2026-07-27 新起的“16 任务正式产物 + 两张真实画布图片 + current revision 静态 / 双视口浏览器 / PNG 证据 + 受限 repair 替换”独立外部 Provider 验收，使用 `npm run agc:test:chat -- --timeout-minutes 75` ，约 `59m50s` 后以退出码 `0` 完整 **PASS ** 。同一轮真实生成并登记 `assets/ui-prototype.png` （ `2829418` bytes）与 `assets/art-spritesheet.png` （ `1361906` bytes），固定 `16` 个 manifest task 均为当前父 Run 下唯一 logical run、一次 started、一次 completed、零 failed / cancelled 和一次 manifest projection；七份基础正式产物、两张 PNG、当前 revision 的 `game.static_smoke` 、desktop / mobile `lane-defense-v1` playtest、浏览器报告与截图全部通过。`turn.report=settled` 且唯一 assistant， `0` ；隔离 Runner、一次性项目和隔离 AppData 已自动清理。此前失败轮继续独立保留，不与本轮拼接；未来合同变化仍须新起完整轮次复验。
- 2026-07-27 补充 tool-plan 成功响应交接的内容边界：Provider 的自然语言计划叙述，以及结构化 arguments 中 `body / code / content / css / html / newText / oldText / patch / script / text` 等源码内容字段，只检查真实密钥 token 形状、凭据头标记和不安全控制字符；仅仅提及 `.env` 或 `game-creator.config` 不能阻断已经计费的安全响应。结构化输入中的敏感 JSON key、非内容字段中的配置痕迹或绝对路径、真实 token、容量、thinking、身份、顺序和账本完整性门禁仍失败关闭。成功 handoff 失败进入 reconciliation 时，Runtime 额外只持久化受控 `failureKind` 、脱敏错误 SHA-256 和字符数，不保存 Provider 正文、function arguments、密钥或绝对路径。定向回归覆盖叙述/源码字段放行、`.env.local` 路径和真实 token 拒绝、全部 tool-plan handoff 回归及诊断零正文。
@@ -1275,6 +1294,15 @@ DirectProject 使用 `approvalPolicy=never`，避免每次原生调用再经过
- 该档位不把最终验收条件提前成启动条件，也不把平台画布、preview、static smoke、发布包或其它平台产物检查作为 child 或根 Supervisor 的完成门。缺少平台产物不会把已完成任务重置为 `Pending` ；根 run 只等待任务图进入终态并交回结果。
- 代码可先按约定的项目路径落地并完成自己的工作；后续任务状态变化只负责唤醒同一根 run 继续收束，不因 `art-polish` 、`art-asset-plan` 等非代码任务失败而阻塞代码启动。平台产物和可玩性检查若需要，属于后续独立验收，不是本档位的运行前置条件。
## 2026-09-04 AGC 项目聊天 Markdown 与流式回复渲染
- 项目开发工作台的 `ProjectWorkspaceChatPane` 、`ProjectSupervisorView` 与 `SupervisorChatOnlyView` 继续共享 `ChatMessage` / `visibleMessages` 数据结构；聊天 Markdown 只作为前端表现层能力，不新增消息字段、持久化格式、后端 DTO 或事件协议。
- 三个视图统一复用 `apps/ai-game-creator-shell/src/components/ChatMarkdownMessage` 。assistant 历史消息和流式临时回复使用 `react-markdown + remark-gfm` 渲染；用户消息与命令草稿保持纯文本。调用方仍先执行现有的 `projectSupervisorVisibleConversationText` 安全文案归一化，再交给展示组件。
- 流式回复以事件中的 `accumulatedText` 作为当前完整草稿：每次更新替换上一版临时正文，不在渲染层自行拼接 `deltaText` 。既有 `runId` / sequence 去重、最终 assistant 持久化和历史回放语义保持不变。
- Markdown 禁止原始 HTML；链接和图片只显示普通文本，不产生可点击或可加载的外部资源。后续若开放安全外链，必须另行评估协议白名单、窗口策略和审计边界，并保留实现 TODO。
- Markdown 元素样式使用 Tailwind 内联 class，限定在聊天消息组件内部，不改全局 `.message` 、资源文档预览或启动器全局 Agent 聊天。组件异常按单条消息回退纯文本，不能使整个聊天面板崩溃。
- 流式更新沿用“仅在用户接近底部时跟随”的滚动语义；用户主动查看历史时不得被实时 Markdown 高度变化强制拉回底部。实现验收需覆盖 GFM、未闭合 Markdown 中间态、HTML/链接/图片安全、三视图一致性、流式去重、历史回放和桌面/移动视口。
## 2026-08-29 DirectProject 受控联网搜索闭环
- 本次正式产品范围只包含 `DirectProject` 单 Codex Agent； `Provider` 、`ToolHost` 、`DirectHome` 不新增联网工具桥，也不纳入本次联网路由覆盖。受控联网唯一实现为 `agc_tools.agc_web_search` ：
