Merge remote-tracking branch 'origin/master' into fix/agc-recent-project-status-retry
# Conflicts: # docs/project-memory/shared-memory/decision-log.md
This commit is contained in:
@@ -837,6 +837,7 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
|
||||
- 并发边界：steer 入队、Runner `runtime.steer` 通知都不得直接触发 Provider interrupt。Codex app-server 的判定使用独立节点，不能等待主节点 turn 锁；判定为 true 后也只能中断 `appliedSteerCursor < steer.sequence` 的旧 Provider 请求，已经消费该 steer 后启动的新请求不可被误杀。已经开始的工具和外部动作不强杀，完成 observation 后再消费 steer。
|
||||
- 验证：真实 mock LLM 回归必须覆盖状态询问回复且 `interruptCurrentProvider=false`；持久重放只保留一条语义回复；steer 入队后旧 Provider 继续运行，判定为 true 后才中断；新规划 Provider 的 cursor 已包含该 steer 时即使旧判定为 true 也不能中断。前端同秒多条消息保持“用户补充 → 判断提示/语义回复”的关联顺序。
|
||||
- 关联：`apps/ai-game-creator-shell/src-tauri/src/agent/interaction.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/steering.rs`、`apps/ai-game-creator-shell/src-tauri/src/runner/dispatch.rs`、`apps/ai-game-creator-shell/src/features/agent-runtime/model.ts`。
|
||||
- 2026-09-23 更新：`agent/interaction.rs` 与 `steer-decision` LLM 判定链已整体删除，本条中「判定 LLM / `interruptCurrentProvider` / 只中断旧 cursor」的实现细节仅作历史记录；现役语义是 steer durable 入队后由 `runtime.steer` 唤醒，并在下一安全边界应用。
|
||||
|
||||
## Jenkins 异步备份不能用 nohup 脱离作业
|
||||
|
||||
@@ -4443,9 +4444,9 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
|
||||
|
||||
- 现象：`npm run agc:test:chat` 在进入聊天前报“Agent Runner 版本与当前客户端不一致，但旧 Runner 仍有任务，暂不能重启”；正式客户端仍能看到自己的待确认或委派任务，重复执行测试也持续失败。
|
||||
- 原因：Runner 复用身份同时绑定协议版本和当前可执行文件 SHA-256。`cargo run` 重新编译后的 debug 二进制与正在运行的 release Runner 指纹不同，而旧入口只隔离测试项目、仍把正式 AppData 直接传给 CLI，于是测试会向正式 endpoint 发升级探测。正式 Runner 有 pending action、Provider sidecar、进程会话或非终态队列时拒绝退出是正确的安全门禁，不能通过强退或放宽 idle 判定让测试通过。
|
||||
- 处理：正式 AppData 只作只读配置来源。每次人工测试在系统临时根创建 `0700` sentinel 隔离目录，只把主配置和可选 local overlay 私有复制为 `0600` 普通文件；不得复制 endpoint、lock、`.previous` 或其它状态。LLM 检查与 Swarm CLI 全部使用隔离目录。退出时通过内部 CLI 请求 `runner.shutdown_if_idle`，确认隔离 endpoint 消失后才删除配置；仍有任务或无法确认退出时同时保留测试项目和隔离配置并报告路径。正式 Runner 的 PID、bootId、端口和 executable fingerprint 必须保持不变。
|
||||
- 处理：正式 AppData 只作只读配置来源。每次人工测试在系统临时根创建 `0700` sentinel 隔离目录，只把主配置和可选 local overlay 私有复制为 `0600` 普通文件；不得复制 endpoint、lock、`.previous` 或其它状态。LLM 检查与端到端测试入口全部使用隔离目录。退出时通过内部 CLI 请求 `runner.shutdown_if_idle`，确认隔离 endpoint 消失后才删除配置；仍有任务或无法确认退出时同时保留测试项目和隔离配置并报告路径。正式 Runner 的 PID、bootId、端口和 executable fingerprint 必须保持不变。
|
||||
- 验证：单元测试覆盖私有 inode、权限、local overlay、禁止复制 endpoint/lock/备份、符号链接拒绝、sentinel 清理和 endpoint 存在时拒绝删除；真实 smoke 使用隔离 AppData 启动并收束空闲 Runner，前后比较正式 endpoint 身份且确认正式 PID 存活，再检查本轮 `/tmp` 项目和隔离配置均已清理。
|
||||
- 关联：`apps/ai-game-creator-shell/scripts/agent-swarm-test-chat.mjs`、`apps/ai-game-creator-shell/tests/agentSwarmTestEntry.test.ts`、`apps/ai-game-creator-shell/src-tauri/src/runner/client.rs`、`apps/ai-game-creator-shell/src-tauri/src/cli.rs`。
|
||||
- 关联：`apps/ai-game-creator-shell/src-tauri/src/runner/client.rs`、`apps/ai-game-creator-shell/src-tauri/src/cli.rs`。
|
||||
|
||||
## Swarm 队列 busy 不能直接当成 canonical run 可 steer
|
||||
|
||||
@@ -4453,7 +4454,7 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
|
||||
- 原因：旧 `runtime_is_busy` 同时包含当前 state 和队列汇总，调用方看到 `task_queue.pending > 0` 后仍从 canonical state 反推 steer、失败扫描和 turn report 的 runId；取消 tombstone 还会让恢复扫描在处理 A 后无条件跳过 B。底层拒绝 terminal steer 和保留 A 的真实失败历史都是正确行为，不能通过放宽门禁或删除历史记录修复。
|
||||
- 处理：保留 queue busy 用于 Runner 存活判断，另由 Runtime 协议层提供唯一 steerable 判定。start mutation 返回实际 `acceptedRunId`，CLI 以它建立不可变 turn baseline；失败、reconciliation、用户交互、收束和报告只观察该 run。canonical 已推进到后续 run 时从 task journal 读取目标 run 的最终记录。旧 cancelled canonical 若仍有 pending 且无 running，恢复扫描跳过旧 run 的 pending action 恢复，直接启动队首 pending。若输入与已落盘 pending task 及最后一条 user 消息相同，则只观察原 run。Goal 路径也必须核对同一 Agent、Session、runId、Run Profile 和 steerable 状态。连续 run 的回复必须按确定性 finalization message ID 过滤；历史 specialist 失败必须以 `(agentId, runId)` 为键读取完整 journal，不能让滞后的非失败 state 删除 journal 已记录的失败；报告计数也不能退回 `recent_tasks` 的 12 条窗口。
|
||||
- 验证：构造 cancelled run A、保留 A cancel tombstone、pending run B 和单份已落盘用户消息，证明恢复后 B 进入 running 并完成且 conversation 不重复。另覆盖观察 B 时忽略 A 及 A 子任务失败、观察 A 时仍正常失败、B 完成后 canonical 已推进到 C 仍可从 journal 收束 B、`turn.report.parentRunId` 始终为 baseline，以及 expected Goal runId 不一致时不选中目标。
|
||||
- 关联：`apps/ai-game-creator-shell/src-tauri/src/swarm_cli/turn_dispatch.rs`、`apps/ai-game-creator-shell/src-tauri/src/swarm_cli/terminal_classification.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/steering.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/recovery_scan.rs`。
|
||||
- 关联：`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/steering.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/recovery_scan.rs`。
|
||||
|
||||
## 2026-07-25 autonomous-game-build 不能只检查 game/index.html 就宣称正式项目完成
|
||||
|
||||
@@ -4468,9 +4469,9 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
|
||||
|
||||
## 终端真实测试不能混用配置参数、stdin EOF 和持续预览
|
||||
|
||||
- 现象：开发者第一次运行 `agc:test:chat` 时必须先打开 GUI 才能配置 Provider；无 TTY 的脚本可能在 stdin 立即 EOF 后零任务成功退出，或者任务已经完成却继续等待 preview 的 `Ctrl+C`，导致自动化看似卡死。若为图省事增加 `--api-key`，密钥还会进入 shell history 和进程列表。
|
||||
- 现象：开发者第一次运行真实 E2E 聊天测试时必须先打开 GUI 才能配置 Provider；无 TTY 的脚本可能在 stdin 立即 EOF 后零任务成功退出，或者任务已经完成却继续等待 preview 的 `Ctrl+C`，导致自动化看似卡死。若为图省事增加 `--api-key`，密钥还会进入 shell history 和进程列表。
|
||||
- 原因：把首次配置、手工多轮聊天、单轮真实测试和持续试玩当成同一个交互生命周期；同时让 GUI 与 CLI 使用不同配置入口，或把 EOF 既解释为“提交当前需求”又解释为“没有输入”，会让退出语义随调用环境漂移。
|
||||
- 处理：GUI 与 `npm run agc:config` 共用系统 AppData `game-creator.config.json`，终端隐藏输入 API Key 并禁止 `--api-key`；更新时保留 `agentLlm`、`editorApi`、`mcpServers` 等其它配置，POSIX 权限维持目录 `0700` / 文件 `0600` 并原子替换。显式 `--config-dir` 必须以 `world.genarrative.ai-game-creator` 为独立叶目录，不能让向导对 `/tmp`、AppData 根或共享目录整体 chmod / 重建 DACL。隐藏输入调用 `stdin.resume()` 后必须记住原 pause 状态，在成功、取消、异常和 `SIGINT / SIGTERM / SIGHUP` 路径恢复 raw mode 并 `pause()`，信号恢复后重发；只移除 `data` listener 会让 `--configure-only`、配置检查失败或 Ctrl+C 保持活动 stdin。缺配置时仅 TTY 人工会话可询问进入向导，非 TTY 立即失败并提示配置命令。
|
||||
- 处理：GUI 与 `npm run agc:config` 共用系统 AppData `game-creator.config.json`，终端隐藏输入 API Key 并禁止 `--api-key`；更新时保留 `agentLlm`、`editorApi`、`mcpServers` 等其它配置，POSIX 权限维持目录 `0700` / 文件 `0600` 并原子替换。显式 `--config-dir` 必须以 `world.genarrative.ai-game-creator` 为独立叶目录，不能让向导对 `/tmp`、AppData 根或共享目录整体 chmod / 重建 DACL。隐藏输入调用 `stdin.resume()` 后必须记住原 pause 状态，在成功、取消、异常和 `SIGINT / SIGTERM / SIGHUP` 路径恢复 raw mode 并 `pause()`，信号恢复后重发；只移除 `data` listener 会让 配置检查失败或 Ctrl+C 保持活动 stdin。缺配置时仅 TTY 人工会话可询问进入向导，非 TTY 立即失败并提示配置命令。
|
||||
- Windows 密钥复制：`mode: 0o600` 和 POSIX `chmod` 在 Windows 上不能代替 DACL。隔离 AppData 目录必须先设置仅当前用户、禁止继承的 DACL；目标配置文件先以空文件创建并收紧 DACL，之后才允许把 API Key 字节写入。先 `copyFile` 再依赖 Rust 只读检查或事后收紧会留下密钥暴露窗口，也可能因继承 ACL 不满足 Runtime 合同而在首次 `--llm-status` 失败。
|
||||
- Windows PowerShell 参数：不要把 DACL 目标路径和目录标记直接追加在 `powershell.exe -Command <script>` 后；Windows Node `spawn` 会让 PowerShell 5.1 把这些值拼入命令文本，带空格的临时路径会被拆分并使 `GetFullPath($args[0])` 失败。当前实现只通过子进程私有环境变量传入路径和布尔值，并由真实 Windows `npm run agc:typecheck` 覆盖 DACL 回归。
|
||||
- 测试超时补充：配置向导的读路径和写路径都会加固私有目录与配置文件，`readGameCreatorWizardConfigState` 与 `writeGameCreatorConfigAtomically` 只要没拿到 `secureWindowsPath` 桩，Windows 上每次调用就各自拉起真实 `powershell.exe`（本机实测约 `0.6s` / 次）。只给写路径传桩、漏掉读路径时，单条用例会累计 `9` 次加固、耗时约 `5.5s`，稳定撞上 vitest 默认 `5000ms` 上限并报 `Test timed out in 5000ms`（不是断言失败）。凡只校验配置分层优先级、不校验 ACL 的用例，读写路径必须带上同一份 `skippedWindowsAclOptions` 桩，把用例耗时从秒级压回 `24ms` 量级；确实要覆盖私有 ACL 的用例才保留真实加固，并自行留足超时预算。隔离 Swarm 运行配置的入口 `prepareSwarmTestRuntimeConfig` 按同一范式暴露了可选第三参 `{ secureWindowsPath }`，默认 `null` 时仍走真实实现，生产调用点保持单参调用；一次调用在双配置文件场景最多加固 3 次，不传桩时同样会稳定吃掉秒级预算。
|
||||
@@ -4528,7 +4529,7 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
|
||||
|
||||
## tool-plan handoff 不能把计划叙述和源码字段当成配置载荷扫描
|
||||
|
||||
- 现象：Provider 已返回 HTTP 200 并计费，tool-plan lifecycle 却只有 `started`，handoff 账本停在上一 loop，Runtime 进入 `needs-reconciliation`；重启 Runner 或 `/resume` 后仍原样被屏障阻断。
|
||||
- 现象：Provider 已返回 HTTP 200 并计费，tool-plan lifecycle 却只有 `started`，handoff 账本停在上一 loop，Runtime 进入 `needs-reconciliation`；重启 Runner 或运行显式恢复（`--agent-resume`）后仍原样被屏障阻断。
|
||||
- 原因：在解析 function arguments 之前，对整段 `response.text` 和序列化 arguments 统一执行 `.env`、`game-creator.config` 等字面标记扫描。安全叙述如“无需读取 `.env`”，或 `oldText / newText / content / patch` 中的普通源码字面量，会在真实路径和内容字段尚未区分时被误判。原始响应未成功交接时不会留下正文，因此现场只能结合 loop 边界和最小复现定位，不能把高概率分支冒充已恢复的原响应证据。
|
||||
- 处理：计划叙述与规范源码内容字段只检查真实密钥 token 形状、凭据头标记和不安全控制字符；结构化敏感 JSON key、非内容字段的配置痕迹和绝对路径、真实 token、容量、thinking、身份、顺序及账本完整性继续失败关闭。成功 handoff 失败时只在 Runtime event/state 和 Agent DB 保存受控 `failureKind`、脱敏错误 SHA-256、字符数与 requestId，禁止保存正文、arguments、密钥和绝对路径。
|
||||
- 验证：必须同时覆盖 narrative 和 `oldText / newText / content / html / patch` 提及 `.env` / `game-creator.config` 可 round-trip，`path=.env.local` 与 `sk-...` 真实 token 仍拒绝，全部 handoff 回归通过；诊断审计必须断言不存在 `error / response / arguments` 原文。修复后的外部 Provider 重试仍需新起独立轮次，不能与故障轮或确定性回归拼接为 PASS。
|
||||
@@ -4536,10 +4537,10 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
|
||||
|
||||
## 自然语言“继续修复”不能在无活动 Runtime 时落入空 resume
|
||||
|
||||
- 现象：旧 run 已取消且 `/resume` 明确报告无可恢复任务，用户随后输入“继续”“继续之前干的事情”或“那就继续修复”，interaction 仍返回 `resume`，宿主反复扫描后不新建任务。
|
||||
- 原因：interaction 模型能看到会话历史，却不知道宿主已经排除了 active、pending 和可 steer Runtime；宿主又把自然语言 `resume` 与显式 `/resume` 当成相同控制动作机械执行。
|
||||
- 处理：活动 Runtime、排队任务和 Goal 仍在 interaction 前优先 steer/恢复；只有这些门禁全部为空后，自然语言 interaction 返回的 `resume` 才规范化为 `execute` 并创建新 run。显式 `/resume` 继续保持纯恢复控制，不因无任务而隐式执行。
|
||||
- 验证：保留自然语言必须进入统一 interaction loop 与显式 `/resume` 命令测试，并新增无活动 Runtime 时 `Resume -> Execute`、普通 reply 不变的回归。
|
||||
- 现象：旧 run 已取消且显式恢复入口明确报告无可恢复任务，用户随后输入“继续”“继续之前干的事情”或“那就继续修复”，interaction 仍返回 `resume`，宿主反复扫描后不新建任务。
|
||||
- 原因：interaction 模型能看到会话历史，却不知道宿主已经排除了 active、pending 和可 steer Runtime；宿主又把自然语言 `resume` 与显式恢复入口当成相同控制动作机械执行。
|
||||
- 处理：活动 Runtime、排队任务和 Goal 仍在 interaction 前优先 steer/恢复；只有这些门禁全部为空后，自然语言 interaction 返回的 `resume` 才规范化为 `execute` 并创建新 run。显式恢复入口（`--agent-resume`）继续保持纯恢复控制，不因无任务而隐式执行。
|
||||
- 验证：保留自然语言必须进入统一 interaction loop 与显式恢复入口测试，并新增无活动 Runtime 时 `Resume -> Execute`、普通 reply 不变的回归。
|
||||
|
||||
## tool-plan 中项目内绝对路径应在成功交接时规范化
|
||||
|
||||
@@ -5285,7 +5286,7 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
|
||||
- 同进程恢复补充：命中“同一 stable turn 仍在运行”后除禁止写 assistant 终态外，还必须删除当前 App 实例的恢复 claim。这样原调用随后成功时显式刷新能读取其终态，随后失败时也能按相同 `clientTurnId` 再次续跑；不要靠重载 WebView 清理进程内 claim，也不要用无界定时轮询制造并发调用。
|
||||
- 严格图集崩溃补充：规范图和背景图的两文件 rollback 不覆盖严格图集事务已经整体修改的 `.agent/manifest.json`、私有回执、公开清单、主图集、四切片和切片清单。必须在严格调用前持久化 pending 及九项旧合同身份；重启恢复先对账底层严格事务，完整新合同直接收口完成，完整旧合同才补偿前两阶段，混合或漂移状态失败关闭。不要在严格提交成功后局部恢复前两张图。
|
||||
- 部分旧包补充：rollback 的规范图/背景图必须保存旧字节与旧 manifest entry，不能把这两项缺失隐式当成空内容；显式 `regenerate` 因此只在这两项可信可回滚时开放。历史主图集、私有回执、公开清单或 canonical 切片可以缺失，但八个严格路径与受管顶层 asset identity 必须逐项冻结其真实 `Present/Some` 或 `Missing/None` 状态，补偿也必须恢复相同存在性。不要因为旧美术包缺切片而阻断重生成，也不要把本轮新建的严格文件误记成旧文件。
|
||||
- 对话扫描与 claim 补充：历史中出现 `User A / User B / Assistant B` 时，B 已回答不代表 A 已回答，扫描必须继续寻找 A。成功 Direct 回复在 Rust 返回前已经落盘，前端冗余 append 失败不能据此重跑；普通错误回复的显式落盘失败时，恢复 claim 要保持到 React fallback writer 的同一 messageId append 明确收敛。writer 成功或明确失败后才释放；失败路径要停止该消息的自动迟到重试，再由显式 `/history` 复用原 stable turn。终态后及时删除 claim，避免 Set 无界增长。
|
||||
- 对话扫描与 claim 补充：历史中出现 `User A / User B / Assistant B` 时，B 已回答不代表 A 已回答，扫描必须继续寻找 A。成功 Direct 回复在 Rust 返回前已经落盘，前端冗余 append 失败不能据此重跑；普通错误回复的显式落盘失败时，恢复 claim 要保持到 React fallback writer 的同一 messageId append 明确收敛。writer 成功或明确失败后才释放；失败路径要停止该消息的自动迟到重试，再由显式重新加载对话复用原 stable turn。终态后及时删除 claim，避免 Set 无界增长。
|
||||
|
||||
## GDD 历史审批回执误触发当前恢复提示（2026-08-27）
|
||||
|
||||
@@ -5845,7 +5846,7 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
|
||||
|
||||
- **现象**：`chat_with_game_creator_direct_codex` 的 Tauri 入参曾并列带一个 `prompt: String`（前端把 canonical content 渲染成 `@显示名` 文本），Rust 侧从不读取——`cargo check` 直接报 `src/agent/direct_runtime/user_input.rs` 的 `unused variable: prompt`；前端每次提交仍要算一遍，界面测试也钉着这份投影文本。
|
||||
- **成因**：DirectProject 回合真正的输入只来自 canonical `userItem`。`direct_codex_user_item_to_codex_turn_input`（`agent/direct_codex_user_item/wire.rs`）在 DirectProject 分支重建 `turn/start.input`，`LlmRunRequest` 里那份 `user_prompt` 会被覆盖；客户端投影走的是另一套口径（素材被删或改名时退化成裸 resourceId），一旦有人把它接回 Codex，就把 `@显示名` 标签污染了模型输入。
|
||||
- **现行口径**：IPC 只传 `projectPath`、`clientTurnId`、`userItem` 与可选 `creationType`；Rust 只从 `userItem` 派生回合输入（空判定与三维契约探测用的派生 prompt 仍在 Rust 内部生成）。前端那份 `@显示名` 投影只服务本地的 `/history` 识别与队列 chip 文案，不出 IPC；界面断言只能读 `userItem.content`。
|
||||
- **现行口径**：IPC 只传 `projectPath`、`clientTurnId`、`userItem` 与可选 `creationType`；Rust 只从 `userItem` 派生回合输入（空判定与三维契约探测用的派生 prompt 仍在 Rust 内部生成）。前端那份 `@显示名` 投影只服务本地的历史条目识别与队列 chip 文案，不出 IPC；界面断言只能读 `userItem.content`。
|
||||
- **关联**：`apps/ai-game-creator-shell/src-tauri/src/agent/direct_runtime/user_input.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/direct_codex_user_item/wire.rs`、`apps/ai-game-creator-shell/src/view/project-development/chat/controller/useDirectProjectChatController.ts`、`apps/ai-game-creator-shell/tests/appSurface/chat-composer.suite.ts`。
|
||||
|
||||
## 2026-09-21 DirectProject 结构化消息不能逐个拒绝空白文本片段
|
||||
|
||||
Reference in New Issue
Block a user