@@ -4,7 +4,7 @@
- 背景：AGC 项目对话曾把大量能力挂在「聊天输入 `/<cmd>` 」上（`/history` 、`/read` 、`/help` 、`/status` 、`/trace` 、`/export` 、`/preview` 、`/remember` 、`/brief` 等），无 GUI 的终端 swarm chat 入口 `--swarm-chat` 又自带一套控制命令（`/help` 、`/agents` 、`/status` 、`/history` 、`/compact` 、`/resume` 、`/goal` 、`/quit` ）。两套入口都没有现役调用方，撤回成本却持续存在：命令字面量散落在前端命令分支、润色绕过、摘要模块、`swarm_cli` 终端输入解析、构建期门禁条目和文档承诺里，任何新对话形态都要额外维护这套死词汇表。
- 决策：斜杠命令语义与终端 swarm chat 入口整体退役，按「从未存在」处理。应用侧删除 Direct 聊天的 `/history` 精确匹配分支与 `reloadHistory` 、`chatPromptPolish` 的 `/` 前缀绕过、`chatCommandMetadata` / `chatCommandHelp` / `memoryCommands` 的命令清单与参数解析、只服务退役 Supervisor 摘要面板的 `project-summary/*Summaries.ts` 与 `agentTrace.ts` 、草稿回填死链（前端 `agentPresentation.ts` + Rust `suggested_canvas_tool_call` ）、无人调用的 Tauri 命令 `get_game_creation_agent_capabilities` / `get_limited_local_commands` ，以及钉住这些字符串的构建期门禁条目与专属测试。终端侧连同入口一并删除：`--swarm-chat` 、`src-tauri/src/swarm_cli.rs` 与整个 `swarm_cli/` 目录（命令解析与帮助输出、turn 派发、观察器、报告、专属测试）、`SwarmChatFlow` 、`SwarmTurnObservation` 、`SwarmTurnOutcome::Quit` 、`SwarmConfirmationResolution::Quit` 、`SWARM_TURN_*_ERROR` 、只服务这些命令的 `agent.compact` / `agent.resume` / `agent.run_status` 权限门禁与 `print_runtime_response_stream_status` 打印器，以及只服务终端交互内核的 `agent/interaction.rs` 整层（`AgentInteractionAction` 、tool registry、`game_creator_agent_uses_interaction_kernel` 、`decide_game_creator_agent_interaction_turn_for_session_at` 、`AgentInteractionProviderStreamSink` ）；该文件只保留自然语言 steer 决策路径 `decide_game_creator_agent_runtime_steer_at` 。真实 E2E 的交互式 CLI 管道、`scripts/agent-swarm-test-chat.mjs` 、`agentSwarmTestEntry.test.ts` 与 `agc:test:chat` / `agc:test:chat:manual` / `agc:chat` / `agc:swarm` 等 npm 脚本同步删除。
- 保留项：命令 id 注册表 `GAME_CREATION_APP_COMMANDS` 与 `GameCreationAppPermission` （项目权限策略词汇表，开发 Agent UI 仍在用 ）、`needsInitializedChatProject` ，以及 `--agent-run` / `--agent-enqueue` / `--agent-steer` / `--agent-resume` / `--agent-context-compact` 等非聊天 CLI 控制命令与 Tauri IPC 注册。
- 保留项：命令 id 注册表 `GAME_CREATION_APP_COMMANDS` 与 `GameCreationAppPermission` （项目权限策略词汇表； `GameCreationAppCommandDescriptor` 类型表达权限判定与审计粒度，数组本体由 Rust 策略路径消费 ）、`needsInitializedChatProject` ，以及 `--agent-run` / `--agent-enqueue` / `--agent-steer` / `--agent-resume` / `--agent-context-compact` 等非聊天 CLI 控制命令与 Tauri IPC 注册。
- 影响范围：`apps/ai-game-creator-shell/src/**` （ `project-summary` 、`project-workspace` ）、`src-tauri/src/**` （ `cli.rs` 、`main.rs` 、`swarm_cli` 整目录删除、`agent/interaction.rs` 收敛、命令注册、canvas 生成、provider / project 测试）、`apps/ai-game-creator-shell/scripts/agent-runtime-real-e2e/**` 、`scripts/check-config.mjs` 、root 与 App 的 `package.json` 脚本、`tests/**` ，以及 AGC 主实施计划文档、Runtime V1.1 文档与 `CONTEXT.md` 术语。
- 验证方式：`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` 。
@@ -2291,7 +2291,7 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
- 2026-07-12 安全边界：`project.verify` 的 script 最多 160 个字符，固定使用系统 script shell，并在解析和执行前拒绝项目级 `.npmrc` 。Runtime context bundle 必须绑定 `projectId / agentId / taskId / sessionId / runId / source / task` ，结尾换行计入 64 KiB 上限；恢复时还要校验 `nextLoopIndex` 、context window、当前窗口已完成轮数、观察指纹、计划和 observation 数量。bundle 写入必须拒绝父目录符号链接，读取必须基于同一文件句柄限制到 64 KiB，并清洗项目路径及常见平台凭据；已观察动作只有在 observation 写入 context checkpoint 后才能删除 ledger，下一轮 planning 和跨重启恢复不得再被旧 ledger 抢占。
- 背景：开发用单 Agent 聊天已经能真实调用各 Agent 的 LLM 路由并持久化对话，但 Agent 仍主要表现为同步问答，用户无法明确投递一个任务让某个 Agent 独立运行，也无法同时启动多个 Agent 的工作。
- 决策：在现有 `.agent/runtime` 和 `.agent/conversations` 基础上新增单 Agent 后台任务入口。Tauri 命令 `start_game_creator_agent_runtime_task ` 立即写入该 Agent 的 runtime state/event/task history，追加用户任务到 `.agent/conversations/agents/<agentId>.jsonl` ，随后在 App 进程内启动 tokio task 执行最小 Agent loop： `thinkingSummary / plan / actions / response` ，Runtime 按白名单和项目权限策略执行工具并记录 `action / observation` 事件，再把已有 observation 放回下一轮 prompt，让 Agent 修正计划、继续行动或用空 actions + response 收束；单 Agent Runtime 每 6 轮形成一个上下文压缩窗口，窗口有新的独立 observation 时压缩上下文并在同一 run 继续，最近 6 轮没有独立进展或相邻窗口重复时以 `failed / budget-exhausted` 和 `loop-budget-exhausted` 终止，不生成总结伪装完成。完成或失败后把 assistant 回复或错误追加回对话，并写入 `.agent/agent.db` 审计记录。工具箱包含只读工具 `memory.read` 、`conversation.read` 、`asset.list` 、`project.index` 、`project.diff` 、`file.list` 、`file.read` 、`agent.run_status` ，以及受策略保护的写/运行工具 `memory.write` 、`file.write` 、`command.run_limited` 、`blackboard.write` 、`agent.message` 和 `agent.delegate` ； `memory.write` 可追加或覆盖本 Agent 私有记忆、项目长期/短期记忆或黑板，`file.write` 只能写项目内相对路径，`command.run_limited` 只接受 `game.static_smoke` 并复用本地静态自检安全边界，`blackboard.write` 追加共享黑板，`agent.message` 写目标 Agent 对话，`agent.delegate` 把任务投递到目标 Agent 的独立后台队列；策略拒绝时不执行工具并把 `blocked` observation 回给 Agent；策略要求确认时不执行工具，而是持久化精确待确认动作并暂停该 Agent 队列，待开发者确认或拒绝后在同一 run 续跑。每个 Agent 的任务历史落在 `.agent/runtime/tasks/<agentId>.jsonl` ，读 runtime 时按 `runId` 去重返回最近任务，任务视角状态使用 `pending / running / completed / failed` ， `nextStep` ， `.agent/runtime/locks/<agentId>.lock` ，允许并行运行；同一 Agent 已有运行任务时，新任务会先进入该 Agent 的 pending 队列，当前 drain 持锁完成后串行继续下一条 pending。该能力仍不是独立 OS 进程或跨重启离线常驻 worker。
- 决策：在现有 `.agent/runtime` 和 `.agent/conversations` 基础上新增单 Agent 后台任务入口。后台任务入口 `start_game_creator_agent_background_task_for_session_at ` 立即写入该 Agent 的 runtime state/event/task history，追加用户任务到 `.agent/conversations/agents/<agentId>.jsonl` ，随后在 App 进程内启动 tokio task 执行最小 Agent loop： `thinkingSummary / plan / actions / response` ，Runtime 按白名单和项目权限策略执行工具并记录 `action / observation` 事件，再把已有 observation 放回下一轮 prompt，让 Agent 修正计划、继续行动或用空 actions + response 收束；单 Agent Runtime 每 6 轮形成一个上下文压缩窗口，窗口有新的独立 observation 时压缩上下文并在同一 run 继续，最近 6 轮没有独立进展或相邻窗口重复时以 `failed / budget-exhausted` 和 `loop-budget-exhausted` 终止，不生成总结伪装完成。完成或失败后把 assistant 回复或错误追加回对话，并写入 `.agent/agent.db` 审计记录。工具箱包含只读工具 `memory.read` 、`conversation.read` 、`asset.list` 、`project.index` 、`project.diff` 、`file.list` 、`file.read` 、`agent.run_status` ，以及受策略保护的写/运行工具 `memory.write` 、`file.write` 、`command.run_limited` 、`blackboard.write` 、`agent.message` 和 `agent.delegate` ； `memory.write` 可追加或覆盖本 Agent 私有记忆、项目长期/短期记忆或黑板，`file.write` 只能写项目内相对路径，`command.run_limited` 只接受 `game.static_smoke` 并复用本地静态自检安全边界，`blackboard.write` 追加共享黑板，`agent.message` 写目标 Agent 对话，`agent.delegate` 把任务投递到目标 Agent 的独立后台队列；策略拒绝时不执行工具并把 `blocked` observation 回给 Agent；策略要求确认时不执行工具，而是持久化精确待确认动作并暂停该 Agent 队列，待开发者确认或拒绝后在同一 run 续跑。每个 Agent 的任务历史落在 `.agent/runtime/tasks/<agentId>.jsonl` ，读 runtime 时按 `runId` 去重返回最近任务，任务视角状态使用 `pending / running / completed / failed` ， `nextStep` ， `.agent/runtime/locks/<agentId>.lock` ，允许并行运行；同一 Agent 已有运行任务时，新任务会先进入该 Agent 的 pending 队列，当前 drain 持锁完成后串行继续下一条 pending。该能力仍不是独立 OS 进程或跨重启离线常驻 worker。
- 2026-07-10 补充：后台 Runtime 每次追加 `.agent/runtime/events/<agentId>.jsonl` 后会通过 Tauri `game-creator-agent-runtime-update` 事件广播当前 `AgentRuntimeResult` ；开发单 Agent 聊天页、项目内 Agent 对话弹窗和主窗口 Agent 状态列表都只把该事件作为实时 UI 通知并复用前端 runtime 归一化合并，事实源仍是 `.agent/runtime/agents` 、`events` 和 `tasks` 文件。
- 2026-07-11 补充：开发单 Agent 聊天页保留整页纵向滚动，聊天消息区固定响应式高度并在内部滚动；Runtime 恢复确认区使用独立布局行，避免与 Runtime 详情或聊天内容重叠。Runtime 面板详情可折叠且折叠时不渲染详情 DOM，但状态标题与任务控制按钮继续保留；等待 LLM 时在消息区持续显示动态状态和进行中提示，连续流式 delta 合并到动画帧更新并跳过重复 Runtime state。OpenAI Chat SSE 会跳过空 `choices` 心跳 / 元数据事件，收集 usage-only 尾包、保留 finish reason 与上游 error message，收到 `[DONE]` 后立即结束；正文与 finish reason 已接收后出现尾包异常时保存已完成正文，不把整轮改写成失败。持久事件订阅失败时显示非致命错误，聊天事件监听不可用或首个文本片段前流式失败时降级普通回复并继续落盘。
- 2026-07-11 补充：为缩小单 Agent 与 Codex CLI 在代码任务上的差距，Runtime 工具箱新增 `project.search` 和 `file.patch` ，并扩展 `file.read` 的按行分页。`project.search` 在项目内执行有界字面量检索，默认忽略大小写，返回相对路径、行号和匹配行，跳过 `.agent` 、敏感配置、依赖和构建目录；权限继承 `file.read` 。`file.read` 接受 `startLine / maxLines` ，返回带行号的最多 240 行、8,000 字符上下文，允许 Agent 继续分页而不是只看到文件开头约 900 字符。`file.patch` 只做 `oldText -> newText` 精确替换，必须声明预期匹配数，匹配数不符时不写入；它继承 `file.write` 权限，复用项目写锁和 Runtime 动作账本，并追加不含代码正文的 `agent.runtime.file.patch` 审计记录。三者组成“搜索定位 -> 分段读取 -> 局部修改 -> 再次读取验证”的最小代码工作闭环，不开放任意 shell。
@@ -6317,7 +6317,7 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
- 2026-07-10 调整：`.agent/policy.json` 支持 `agentPolicies` ，用规范 Agent id 保存单个 Agent 的 `deniedCommands / confirmCommands` 。Runtime 计算有效工具策略时把项目级策略和 Agent 级策略叠加，项目级策略继续对所有 Agent 生效，Agent 级策略只能进一步拒绝或要求确认，不能放宽项目级策略；拒绝优先于确认。主聊天新增 `/agent-policy-deny Agent 命令` 、`/agent-policy-allow Agent 命令` 、`/agent-policy-confirm Agent 命令` 和 `/agent-policy-auto Agent 命令` ，继续通过 `project.policy_write` 确认卡写入策略。
- 2026-07-10 调整：后台 Agent 工具命中确认策略时不再当作 `blocked` observation 继续收尾，而是把当前 Runtime 写成 `status/phase = waiting-for-confirmation` ， `waitingOn` 固定为等待开发者确认工具动作，`recentToolCalls` 、事件流、任务记录和 `taskQueue.waitingForConfirmation` 都保留该事实；同一 Agent 的后台 drain 暂停，不继续消费后续 pending 任务。命中拒绝策略仍使用 `blocked` observation 交回 Agent 修正计划。
- 2026-07-10 调整：Agent Runtime 后台任务支持按 Agent / runId 取消和重试。取消先通过 `.agent/runtime/cancel/<agentId>/<runId>.json` 写入本地取消请求；pending 任务被取消后不会被 drain 消费，running 任务在原 worker 仍持锁时只投影为 `cancelling` ，必须等当前 LLM 或工具调用返回后的检查点真正停下，才由持锁 worker 向任务 JSONL、事件流和 `agent.db` 追加 `cancelled` 审计，不再继续执行工具或保存最终 assistant 回复。`cancelling` 期间禁止重试；重试只能基于已有非 running / pending / waiting-for-confirmation / cancelling 任务创建新的 run，并继续走 `agent.resume` 自动权限和同一 Agent 队列锁。
- 2026-07-10 调整：Agent Runtime 后台任务的 `runId` 是同一 Agent 任务历史的身份，不允许复用覆盖。`start_game_creator_agent_runtime_task ` 、`agent.delegate` 和 retry 进入后台队列前会读取该 Agent 全量 task JSONL 历史；若调用方传入的规范化 runId 已存在，Runtime 自动追加 `-dup-<timestamp>-<attempt>` 生成实际 runId。任务队列、delegate observation 和 `agent.db` 审计都必须使用实际 runId，避免 `latest_game_creator_agent_runtime_tasks` 按 runId 去重时折叠掉不同任务。
- 2026-07-10 调整：Agent Runtime 后台任务的 `runId` 是同一 Agent 任务历史的身份，不允许复用覆盖。`start_game_creator_agent_background_task_for_session_at ` 、`agent.delegate` 和 retry 进入后台队列前会读取该 Agent 全量 task JSONL 历史；若调用方传入的规范化 runId 已存在，Runtime 自动追加 `-dup-<timestamp>-<attempt>` 生成实际 runId。任务队列、delegate observation 和 `agent.db` 审计都必须使用实际 runId，避免 `latest_game_creator_agent_runtime_tasks` 按 runId 去重时折叠掉不同任务。
- 2026-07-10 调整：Agent Runtime 的 `memory.write scope=agent` 只能写当前 Agent 自己的私有记忆。若 action 指定其他 `agentId / targetAgentId` ， `blocked` observation，不写目标 Agent 私有记忆、不写 `agent.runtime.memory.write` 审计；跨 Agent 共享稳定结论必须走 `blackboard.write` ，给单个 Agent 留上下文必须走 `agent.message` 。
- 2026-07-10 调整：Agent Runtime 和本地对话使用 append-only JSONL 作为事实源时，进程内必须按目标文件路径串行追加整行。`.agent/agent.db` 、`.agent/conversations/**/*.jsonl` 、`.agent/runtime/events/*.jsonl` 、`.agent/runtime/tasks/*.jsonl` 、`.agent/activity.jsonl` 和 `.agent/output.jsonl` 统一走共享追加 helper，避免多个后台 Agent 并行完成时 JSON record 与换行交错。
- 2026-07-10 调整：Agent Runtime 待确认工具动作改用 durable `AgentRuntimePendingToolAction` 。Runtime 将精确 `action` 输入、当前 task/run、loop 轮次、action 序号、计划、已有 observations 与后续 loop 所需上下文先做敏感内容和项目绝对路径校验，再通过临时文件替换原子写入 `.agent/runtime/pending-actions/<agentId>/<runId>.json` ；公共 runtime state 的 `pendingToolAction` 只暴露 `actionId / actionFingerprint / tool / inputSummary / reason / requestedAt` 安全摘要，完整输入不进入公共状态。`actionFingerprint` 绑定工具名、完整输入 JSON 与实际执行使用的 task context； `actionId` 还绑定 run、loop、action 序号和 occurrence nonce，使同一 run 内输入相同的两次动作仍是两个不同发生。确认和拒绝都必须匹配 `runId + actionId` ，Runtime 会重算指纹并与私有落盘动作及公共摘要交叉校验，不一致时失败关闭。确认通过后在同一 run 直接执行持久化的原 action，把真实 observation 接回后续 Agent loop，不创建新 run，也不让模型重复生成待确认动作；拒绝不执行工具，写入 `blocked` observation 后在同一 run 继续规划。待确认账本按 `pending-confirmation / approved / executing / observed-approved / observed-rejected` 迁移：重启时 `approved` 可恢复精确动作，已持久化 observation 可直接续 loop， `executing` 表示外部副作用结果未知，Runtime 必须进入 `failed / needs-reconciliation` 并禁止自动重放，开发者核对项目状态后只能先取消原任务。waiting run、完整待确认动作和安全摘要均已落盘，App 重启不会越过该 run 去启动后续任务；等待期间同 Agent 新任务只保持 `pending` ，确认、拒绝或取消结束后再由同一 drain 串行排空。`.agent/runtime/` 是 Runtime 私有控制面，通用 `file.list / file.read / file.write / file.delete` 不得列出、读取、修改或删除；checkpoint/index/diff/restore 继续整体排除该目录。每 Agent 锁包含唯一 token，旧持有者析构时只删除自己的锁；Linux 上其他仍存活进程的锁不会因超过固定时长被抢占。确认、拒绝及工具 observation 分别写入 `agent.runtime.tool_confirmation.approved` 、`agent.runtime.tool_confirmation.rejected` 和 `agent.runtime.tool_observation` 审计；pending 和 confirmation 文件只在 observation/终态可靠落盘后清理，失败清理会显式报错。
@@ -6386,7 +6386,7 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
## 2026-07-10 AI 游戏创作 Agent Runtime 执行边界
- 决策：开发单 Agent 对话默认使用可执行 Runtime，输入区通过 `执行 / 聊天` 分段控件显式区分；`执行` 调用 `start_game_creator_agent_runtime_task ` 并保留工具策略、确认、取消、排队和状态事件，`聊天` 才使用无工具流式回复，不再保留并列的“后台运行”按钮。消息区使用固定响应式网格行和内部滚动，并在 Runtime 非终态期间显示当前等待对象。Runtime 完成前必须先把 assistant 回复写入发起 Session，再写 completed 终态和广播；落盘失败只能进入 failed。前端收到匹配当前项目、Agent、Session 和 runId 的终态后自动重读对话，切换 Session 会清除当前等待投影，旧 run 事件不得覆盖新 Session。
- 决策：开发单 Agent 对话默认使用可执行 Runtime，输入区通过 `执行 / 聊天` 分段控件显式区分；`执行` 走后台任务入口 `start_game_creator_agent_background_task_for_session_at ` 并保留工具策略、确认、取消、排队和状态事件，`聊天` 才使用无工具流式回复，不再保留并列的“后台运行”按钮。消息区使用固定响应式网格行和内部滚动，并在 Runtime 非终态期间显示当前等待对象。Runtime 完成前必须先把 assistant 回复写入发起 Session，再写 completed 终态和广播；落盘失败只能进入 failed。前端收到匹配当前项目、Agent、Session 和 runId 的终态后自动重读对话，切换 Session 会清除当前等待投影，旧 run 事件不得覆盖新 Session。
- 2026-07-12 修正：Runtime 状态为空时也要保留其网格行位，消息区和输入区显式固定到第 5、6 行，禁止空 Runtime 容器通过 `display:none` 让长消息落入 `auto` 行并撑高页面；等待 LLM 期间消息区同步使用 `aria-busy` 暴露忙碌状态。消息区只在用户仍接近底部时自动跟随最新片段，用户向上查看历史后暂停跟随，切换会话、重新读取或主动发送时再恢复。
- 2026-07-12 修正：OpenAI-compatible 流式响应中 `choices` 为空数组或 `null` 的 usage / metadata 包不得再报缺少 `choices[0]` ，必须跳过元数据并继续等待正文。首个 delta 前只有 `StreamUnavailable / EmptyResponse / Deserialize` 协议兼容错误允许由 Rust 单 Agent 流式入口回退一次非流式请求；上游状态、鉴权、额度、超时、连接和请求错误直接保留原错误，前端不得再次发起普通 LLM 请求。已收到正文和完成原因后继续保留完整流式回复，不能被尾部坏包覆盖。
- 2026-07-12 修正：Tauri 聊天事件监听被拒绝后，前端选择的普通回复入口必须固定调用 `client.run` ，即使 Agent 路由保留 `stream=true` 也不得再内部发 SSE。pending action 的 project revision 快照改为绑定 planning 请求发出前的版本；`file.delete` 取得项目写锁后必须再次校验 revision / verification gate，公共 pending 摘要必须与私有 ledger 完整相等，confirm / reject 只在迁移状态可靠落盘后启动 continuation。manifest 和 pending ledger 禁止 truncate/remove 旧文件后再替换，统一使用同目录临时文件的原子替换及可恢复 backup。
