Remove Absolute and External Path Restrictions of Design Agent. Fix mac runtime failure (#528)

Co-authored-by: kdletters <61648117+kdletters@users.noreply.github.com> Reviewed-on: #528 Co-authored-by: lhk <ink29535@proton.me> Co-committed-by: lhk <ink29535@proton.me>
2026-09-29 17:15:28 +08:00
parent 80bf54c39d
commit 06f7f145b8
9 changed files with 333 additions and 79 deletions
@@ -1,5 +1,24 @@
 # 决策记录

+## 2026-09-29 Codex 私有运行目录先解析系统临时路径上的符号链接
+
+- 决策：新建的 Codex 临时目录确认是普通目录后，先解析为真实路径并去掉 Windows `\\?\` 前缀，再创建 `codex-home`、`workspace` 和隔离用户目录。macOS 的 `/var`、`/tmp` 这类系统符号链接不再阻断 Game Agent 启动。
+- Windows 路径转换必须先将 `\\?\UNC\server\share\...` 恢复为 `\\server\share\...`；不能只删除 `\\?\`，否则网络共享路径会变成相对路径。盘符路径继续去掉 `\\?\` 前缀。
+- 范围：`validate_game_creator_private_path_ancestors` 不放宽。AppData、客户端配置，以及临时目录内部新出现的符号链接，仍然拒绝。
+- 关联：`apps/ai-game-creator-shell/src-tauri/src/agent/codex_app_server/mod.rs`。
+
+## 2026-09-29 策划文件工具说明去掉路径硬限制
+
+- 决策：常驻提示词仍要求策划文件放在工作区内并使用相对路径。`read_file`、`write_file`、`list_dir`、`search_text`、`patch_file`、`delete_path` 的工具说明不再写「工作目录内」或「path 使用相对路径」。说明不宣布可以访问绝对路径或工作区外路径。
+- `delete_path` 保留工作区根目录及其上级目录保护，按真实路径在删除前判定；允许经过祖先链接，删除链接本身只移除链接，递归删除不跟随目录内的链接。阶段产物、共享过程文件和速览卡链接的相对路径约定不变。
+- 关联文档：[策划 Agent 生产迁移与工作区浏览](../../technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md)。
+
+## 2026-09-29 策划文件工具接受绝对路径和工作区外路径
+
+- 决策：Design Agent 的 `list_dir`、`read_file`、`write_file`、`patch_file`、`delete_path`、`search_text` 可以读写绝对路径，以及离开 `design_artifacts` 的路径。相对路径仍以策划工作区为基准，`..` 可以离开工作区。工作区内写入继续走现有私有文件写入；工作区外写入按普通文件创建父目录并写入。
+- 范围：用户工作区浏览和附件导入仍只使用 `design_artifacts`。阶段必需产物仍按工作区相对路径检查。删除允许经过祖先链接；删除链接本身只移除链接，递归删除不跟随目录内的链接。工作区根目录及其上级目录按真实路径保护。提示词本轮未改。
+- 关联文档：[策划 Agent 生产迁移与工作区浏览](../../technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md)。
+
 ## 2026-09-29 dev 渠道改名迁移放进安装器钩子，且只注入 dev

 - 背景：dev 渠道展示名从 `陶泥儿` 改成 `陶泥儿开发版`（`identifier` 不变）后，更新路径不会重建快捷方式，旧桌面图标继续指向旧安装目录里的旧 exe，旧 exe 的更新器又把新版本装进新目录，于是用户看到「更新后自动启动新版、桌面快捷方式打开的还是旧的」。
@@ -1,5 +1,12 @@
 # 踩坑与排障记录

+## 2026-09-29 Codex 隔离用户目录被系统临时目录的符号链接拦下
+
+- **现象**：Game Agent 回合还没改项目文件就失败。卡片是 `direct-codex-failure:v2 stage=code-generation code=runtime-failure`，摘要为「创建 Codex app-server 隔离用户目录失败：Codex 隔离用户目录 路径不能包含符号链接：<absolute-path>」。诊断文件同样把路径脱敏，看不出是哪一级目录。
+- **原因**：临时目录保留 `TMPDIR` 或 `/tmp` 的原始路径。macOS 上 `/var` 指向 `/private/var`，未设置 `TMPDIR` 时 `/tmp` 指向 `/private/tmp`。隔离用户目录会检查全部现存祖先，把这些系统符号链接当成私有目录里的链接拒绝。Linux 和 Windows 只在临时路径上确实有符号链接时同样失败。
+- **处理**：临时目录确认是普通目录后先解析成真实路径，再创建 `codex-home`、`workspace` 和 `home`。祖先检查不放宽；临时目录内部的符号链接仍然拒绝。
+- **关联**：`apps/ai-game-creator-shell/src-tauri/src/agent/codex_app_server/mod.rs` 的 `canonical_codex_private_runtime_dir`。
+
 ## 2026-09-29 dev 渠道改名后，更新路径不会重建快捷方式（旧图标一直指向旧安装）

 - **现象**：改名前的 dev 客户端（展示名 `陶泥儿`，0.1.126）点更新后自动启动的是新版（`陶泥儿开发版`，0.1.160），但桌面/开始菜单里的 `陶泥儿.lnk` 打开的还是旧版。`%LOCALAPPDATA%` 下同时留着 `陶泥儿` 与 `陶泥儿开发版` 两个安装目录，`HKCU\Software\Microsoft\Windows\CurrentVersion\Uninstall` 下同时留着 `陶泥儿`（0.1.109）与 `陶泥儿开发版`（0.1.160）两个卸载项，而新版一份快捷方式都没有。
@@ -104,7 +111,7 @@

 ## 策划 Agent 提示词中的相对路径不要当作内部实现删去

-`project/...` 是 Agent 读写策划工作区的目标路径，`resources/...` 是查找内置分册、模板和例子的资源定位；即使阶段上下文也注入了同一产物路径，提示词里的路径仍是 Agent 需要的契约。清理宿主实现细节时不要误删这些相对路径，具体用法见[策划 Agent 路径说明](../../technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md#6-阶段与提示词注入)。
+`project/...` 是提示词里读写策划工作区的目标路径，`resources/...` 是查找内置分册、模板和例子的资源定位；即使阶段上下文也注入了同一产物路径，提示词里的路径仍是 Agent 需要的契约。清理宿主实现细节时不要误删这些相对路径。Runtime 文件工具另外接受绝对路径和离开 `design_artifacts` 的路径。具体用法见[策划 Agent 路径说明](../../technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md#6-阶段与提示词注入)。

 ## AGC 素材直传的 OSS 权限必须同步到 Native shell 契约检查