Merge remote-tracking branch 'origin/master' into fix/clean-history-cmd

# Conflicts: # docs/project-memory/shared-memory/decision-log.md # docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
2026-09-23 15:32:47 +08:00
parent ce70171b43 016356e509
commit ede6efbe73
62 changed files with 728 additions and 388 deletions
@@ -9,6 +9,13 @@
 - 验证方式：`npx tsc -p apps/ai-game-creator-shell/tsconfig.json --noEmit`、`npm run --workspace apps/ai-game-creator-shell typecheck`（含 `check-config.mjs` 的脚本与门禁一致性）、`npx vitest run apps/ai-game-creator-shell/tests/appSurface.test.ts`、`cargo check --tests`（告警消息集与基线一致）、`npm run check:encoding`、`git diff --check`；保留的 e2e 套件为 `supervisor-swarm`、`-transient-retry`、`-final-reply-transient-retry`、`-tool-plan-handoff-runner-kill`、`goal-runtime`、`response-stream`、`web-search`、`context-compaction`、`scoped-agents`、`project-skill`、`parallel-read`、`steer-runner-kill`、`process-session`。
 - 关联文档：[【ADR】退役AGC项目对话斜杠命令与终端swarm chat入口-2026-09-22](../../adr/【ADR】退役AGC项目对话斜杠命令与终端swarm chat入口-2026-09-22.md)、[【里程碑】退役AGC项目对话斜杠命令与终端swarm chat入口-2026-09-22](../plans/【里程碑】退役AGC项目对话斜杠命令与终端swarm chat入口-2026-09-22.md)、`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`。

+## 2026-09-23 AGC 发布前先守可运行原型门禁
+
+- 背景：客户端已经显示“首个可运行原型尚未完成，运行视图暂不可用”，但发布入口仍会先执行用户项目的 `build`，导致未完成原型也进入构建并在后续失败。
+- 决策：`project.export_package` 的发布专用导出链路先检查可玩入口；没有入口时，只有 `code-prototype` 已完成或存在运行中的预览才允许执行 `build`，否则直接返回“首个可运行原型尚未完成，暂不能发布”。发布不再进入聊天确认卡，改为独立全屏进度弹窗；运行中遮罩覆盖整个工作区并阻止交互，失败留在弹窗内，成功后切换到发布资料面板。
+- 边界：已有可运行入口仍直接打包；原型已完成但缺构建产物时保留原有自动构建；缺失 `exports/README.md` 仍在导出前自动生成。
+- 验证：Rust `publish_export` 4/4、前端发布相关测试 16/16、AGC `tsc`、编码检查和 `git diff --check` 通过。
+
 ## 2026-09-22 Direct 埋点与业务持久化锁隔离

 - Direct 采集身份和最新成果编号改由独立纯内存状态保存，初始化时从最终执行账本冻结项目与原 run 身份；成果采集、预览采集上下文和终态成果读取不再争用业务落盘锁。
@@ -1,5 +1,9 @@
 # 踩坑与排障记录

+## 策划 Agent 提示词中的相对路径不要当作内部实现删去
+
+`project/...` 是 Agent 读写策划工作区的目标路径，`resources/...` 是查找内置分册、模板和例子的资源定位；即使阶段上下文也注入了同一产物路径，提示词里的路径仍是 Agent 需要的契约。清理宿主实现细节时不要误删这些相对路径，具体用法见[策划 Agent 路径说明](../../technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md#6-阶段与提示词注入)。
+
 ## AGC 素材直传的 OSS 权限必须同步到 Native shell 契约检查

 - **现象**：Native shell CI 在 `check:native-shells:contract` 的 HTTP scope 检查失败，尚未准备 Rust 缓存；后续导出步骤正常退出但实际跳过，导致 master 缓存产物缺组、自动镜像刷新等待。
@@ -1155,6 +1155,19 @@ game-project/
 - 首页发送以及项目组打开 / 新建都通过绑定当前 `client` 的 Tauri 非阻塞原生目录选择器选择项目路径；用户取消目录选择时不覆盖已有输入或草稿。
 - 最近项目列表只来自本机 WebView storage，可逐行移除；该操作不触碰项目目录，也不触发窗口切换。项目组页自动只读检查最近项目路径，已初始化项目优先显示 `.agent/manifest.json` 里的项目名并保留路径副信息；如果 `.agent/run.latest.json` 可读，则把 status / stopReason 转成面向用户的状态。缺失、非目录、manifest 损坏或检查失败的条目禁用打开；目录仍存在时可从行尾菜单显示，检查中临时禁用打开 / 显示。页面不恢复清空或手动刷新按钮，本地搜索也不改项目列表。
 - 项目组页“打开”直接进入已初始化且 `.agent/manifest.json` 可读的 AI 游戏项目；发现根目录或一层子目录中的唯一 Godot 工程时允许导入并进入项目。路径不存在、不是文件夹、普通未初始化目录或 Godot 歧义时留在当前页提示，且不写 `.agent`。“新建项目”和聊天 `project.create` 新建入口会先检查目标目录，目标目录已经存在且非空时必须弹出确认提醒；用户继续后才调用 `init_local_game_project`，默认项目名取目标文件夹名，再写入最近项目并切到项目开发页；用户取消或初始化失败时不切换视图、也不写入最近项目。
+- 聊天输入 `/commands` 会只读列出 Tauri runtime 暴露的受限命令白名单，读取失败或非 Tauri 环境下回退到共享契约默认列表；该命令不执行白名单命令，也不要求先初始化项目。
+- 聊天输入 `/smoke` 会生成待确认的 `command.run_limited` 内置命令，当前只映射到白名单 `game.static_smoke`，不开放任意命令解析。
+- 聊天输入 `/run` 会生成待确认的 `game.run_local` 内置命令，确认后复用白名单 `game.static_smoke` 运行当前 `game/index.html`，通过后启动只读本地 HTTP 预览并切换到客户端内运行视图；该命令不开放任意 shell。
+- 聊天输入 `/export` 会生成待确认的 `project.export_package` 内置命令，确认后只把 `game/**`、`assets/**` 和 `exports/README.md` 打包到 `exports/playtest-package-*.zip`；缺少 `exports/README.md` 时先按项目 manifest 生成最小试玩说明，已有文件原样保留。发布前若 `code-prototype` 未完成且没有运行中的预览，直接阻止发布，不触发用户项目构建；可运行原型完成后才允许按 `build` 脚本补齐产物。发布进度使用独立模态弹窗展示，遮罩覆盖整个工作区并阻止交互，不再使用聊天确认卡；导出前重新校验可玩入口，拒绝符号链接和越界路径，不把 `.agent/`、`memory/`、日志、trace、运行时配置或密钥文件写入 ZIP。
+- 聊天输入 `/exports` 会只读执行 `project.export_list`，列出当前项目 `exports/playtest-package-*.zip` 历史试玩包，并提供显示目录或继续 `/export` 的草稿；该命令不删除文件、不分享文件、不新增面板。
+- 聊天输入 `/preview` 会生成待确认的 `preview.start` 内置命令，确认后启动只读本地 HTTP 预览并切换到客户端内运行视图；`/open-preview` 在本地项目已初始化后生成待确认的 `preview.open`，只激活当前授权项目对应的 `127.0.0.1` 运行容器；`/preview-status` 只查询当前授权项目的本地 HTTP 预览并写入 `preview.status` 命令日志；`/preview-stop` 只停止当前项目预览，不展示或停止其它项目遗留的全局预览。
+- 聊天输入 `/memory [short|long|blackboard]` 读取短期、长期或黑板记忆；`/remember [short|long|blackboard] 内容` 生成待确认的 `memory.write` 并追加短期、长期或黑板记忆，未写 scope 时默认追加长期记忆；主窗口“记到黑板”“覆盖黑板”“清空黑板”只填入 `/remember blackboard `、`/memory-set blackboard ` 或 `/forget-memory blackboard` 草稿，仍由用户补内容并走聊天确认；`/memory-set [short|long|blackboard] 内容` 生成待确认的 `memory.write` 并覆盖保存对应记忆；`/forget-memory [short|long|blackboard]` 生成待确认的 `memory.delete`。
+- 聊天输入 `/canvas 画板项目ID` 会生成待确认的 `canvas.project_open`，只打开本机 Genarrative 编辑器里的指定画板项目，不开放任意 URL；确认后聊天先反馈正在打开，再回写真实打开 URL。画板项目 ID 为空或包含控制字符时在聊天侧直接拒绝。
+- 聊天输入 `/sync-canvas-project 画板项目ID` 会生成待确认的 `canvas.project_sync`，通过 External Editor API 把该画板项目资源下载到 `assets/canvas-sync/` 并登记为画板来源资产；画板项目 ID 为空或包含控制字符时在聊天侧直接拒绝。
+- 聊天输入 `/generate-art 提示词` 会生成待确认的 `canvas.asset_generate`，通过 External Editor API 生成首版美术素材并写入 `assets/canvas-generated/`；提示词为空时在聊天侧直接拒绝。
+- 主窗口“打开画板”“同步画板”“生成美术”和“导入画板包”按钮只填入对应聊天命令草稿并聚焦输入框，不绕过聊天侧确认流；其中“打开画板”只生成 `/canvas ` 草稿，不要求本地项目已初始化；“导入画板包”通过 Tauri 原生文件选择器选择本地 ZIP 后填入 `/import-canvas-export /绝对路径 `，仍需用户补画板项目 ID 并确认后才导入。
+- 聊天输入 `/import-canvas-asset 本地路径 画板项目ID 资源ID|object:资产对象ID [kind] [mediaType]` 会生成待确认的 `canvas.asset_import`，只把项目目录内已有文件登记为画板来源资产；主窗口画板音频快捷入口只预填 `assets/audio/sfx.wav`，由用户补齐画板项目和资源 ID 后再走同一确认流。画板只有 `assetObjectId` 时使用 `object:` 前缀，不伪造 resourceId。画板项目 ID 为空或包含控制字符时在聊天侧直接拒绝。
+- 聊天输入 `/import-canvas-export /绝对/画板素材.zip 画板项目ID` 会生成待确认的 `canvas.export_import`，把画板导出的素材 ZIP 解包到 `assets/canvas-imports/` 并登记为画板来源资产。画板项目 ID 为空或包含控制字符时在聊天侧直接拒绝。
 - 开发窗口里的 `confirm` 权限命令使用原生确认门，取消时只写命令日志，不执行本地写入、删除、预览或画板打开操作。
 - 原生文件上传会写入 `assets/uploads/`，并追加登记到 `.agent/manifest.json`。
 - 开发模式可把项目内已有文件登记为资产；`asset.register` 支持 `uploaded`、`generated`、`canvas` 三种来源，并可记录画板 project/resource/object 元数据。
@@ -276,6 +276,13 @@ concept → top_design → architecture → systems → tdd → consultant

 `systems: []` 是已确定的行为，不是迁移时需要补齐的缺口。`project/analysis.md`、`project/决策台账.md`、`project/dialog.md` 保持原型中的共享过程文件口径，不升级为新的审批必需项。速览卡保留原型结构提示，但 Runtime 与 UI 不解析其章节或内容字段。

+提示词中的路径是策划 Agent 使用的相对路径约定：
+
+- `project/...` 以策划工作区为根，Agent 将其传给 `read_file`、`write_file`、`patch_file` 等文件工具来读取和维护正式产物及过程文件。宿主将它映射到项目的 `design_artifacts/project/...`；阶段审批按登记的相对路径检查必需产物。提示词写明 `project/速览卡.md`、`project/analysis.md` 等目标位置，是在告诉 Agent 文件应写在哪里，并非泄露宿主绝对路径。
+- `resources/skills/...`、`resources/templates/...`、`resources/exemplars/...` 和 `resources/modules/system-types/...` 指向随应用发布的固定策划资源包，用于定位分册、模板、例子及系统类型资料，不是策划工作区的写入目标。资源目录在 `resources/catalog.json` 中登记相对路径与资源 ID；Agent 可用 `list_resources` 查 ID，再用 `read_resource` 按 ID 读取。分册中省略 `resources/` 前缀的 `templates/...` 等写法仍指同一资源包内的位置。
+
+这些路径直接服务于 Agent 的文件操作和资源查阅，属于提示词应保留的契约；即使阶段上下文也注入了某条产物路径，分册和模板中的路径仍提供目标文件与交叉引用的具体定位。去除客户端与宿主实现细节时，不应把这类相对路径当作意外暴露的内部实现；宿主安装目录、项目绝对路径及会话控制文件位置才不属于 Agent 的操作输入。
+
 过程文档记录关键依据、决定和待办，不要求实时完整，也不应重复正式设计文档；阶段提交前补齐影响验收的关键记录。顶层设计的分册、模板和示例保留核心定位及按需说明的易混淆方向与排除理由，不强制使用固定的“不是 X，而是 Y”句式。

 进入下一阶段必须由用户批准触发。Runtime 推进后向 Agent 追加明确的用户行为语义，例如“用户已批准上一阶段，现在进入顶层设计阶段”，避免 Agent 误认为 Runtime 自行推进。