local: stash the document

docs/technical/【技术方案】AI游戏创作Agent Runtime交互边界重构实施计划-2026-08-12.md

@@ -0,0 +1,319 @@
+# AI 游戏创作 Agent Runtime 交互边界重构实施计划
+
+更新时间：`2026-08-12`
+状态：评审中
+
+## 0. 目标与范围
+
+统一 Consumer（GUI / CLI / 自动化测试）与 Runtime 之间的公开交互边界，达到：
+
+- **Consumer 只做两件事**：`render(state)` 与 `dispatch(intent)`，中间不保留决策。
+- **交互 Loop 收归后端 Supervisor Shell**：Consumer 不再根据 Runtime 状态自行选择 start / steer / confirm / retry / resume。
+- **GUI、CLI、测试夹具是同一套协议的平等 Consumer**，GUI 没有任何特权通道。
+- **Runner 自驱**：工作发现、恢复、继续执行不依赖 Consumer 在线或主动触发。
+
+本重构**不重新设计 Runtime 内部执行模型**（Part D 保持黑盒），只补充 Shell 需要的边界能力。
+
+### 不在本轮
+
+- Agent 执行状态机（main_loop / task_queue / recovery）内部重构。
+- Runner 进程生命周期策略（开机自启 / 无 GUI 常驻）——自驱只限于"Runner 存活期间"，保留 GUI 启动 + GUI-owner watchdog。
+- LLM / Provider / 提示词体系改动。
+
+---
+
+## 1. 交互 Loop 协议（Interaction Contract）
+
+这是 Consumer 与 Supervisor Shell 之间唯一的公开协议。协议不绑定 transport（Tauri 命令 / Runner 协议 / 进程内函数均可用同一套 DTO）。
+
+### 1.1 出向事件（Shell → Consumer）
+
+| 事件 | 含义 | 现状落点 | 是否新增 |
+|---|---|---|---|
+| `progress` | 运行推进 | `status/phase` + `recentEvents` + `waitingOn/nextStep`，经 `read_game_creator_agent_runtimes` 与 `game-creator-agent-progress` 事件 | 收敛 |
+| `needs_input` | 等待澄清回答 | `userInputRequest` / phase `waiting-for-user-input`（`AgentRuntimeUserInputRequest`） | 收敛 |
+| `approval_required` | 等待开发者批准工具动作 | `pendingToolAction` / phase `waiting-for-confirmation`（`AgentRuntimePendingToolActionSummary`） | 收敛 |
+| `tool_request` | 工具已请求/执行中 | 现散在 `recentToolCalls` + phase `action` | **新增派生** |
+| `artifact` | 产物 / manifest 变化 | `game-creator-manifest-invalidated` + finalization journal | 收敛 |
+| `done` | 本轮终态 | `completed` + `AgentRuntimeFinalizationJournal` + responseStream `committed` | 收敛 |
+| `error` | 失败 / 需人工核对 | `failed` / `needs-reconciliation` + `error` | 收敛 |
+
+协议 DTO（camelCase 序列化，与现有一致）：
+
+```rust
+enum AgentRuntimeOutboundEvent {
+    Progress(AgentRuntimeProgress),
+    NeedsInput { request: AgentRuntimeUserInputRequestView },
+    ApprovalRequired { action: AgentRuntimePendingToolActionSummary },
+    ToolRequest(AgentRuntimeToolRequest),          // 新增：Shell 从 recentToolCalls+phase 投影
+    Artifact(AgentRuntimeArtifactEvent),           // 收敛 manifest-invalidated + finalization
+    Done(AgentRuntimeDoneEvent),
+    Error(AgentRuntimePublicError),
+}
+
+struct AgentRuntimeProgress {
+    project_path: String, agent_id: String, run_id: String,
+    status: String, phase: String,
+    current_task: String, current_action: String,
+    plan_steps: Vec<AgentRuntimePlanStep>, active_plan_step_index: Option<u32>,
+    waiting_on: String, next_step: String,   // Shell 负责填充，Consumer 不再映射 phase→文案
+    updated_at: u64,
+}
+```
+
+> 与现状的关键差异：`progress` 里的 `waiting_on`/`next_step` 由 **Shell 填充**。当前是前端在 `model.ts:612/644` 硬编码 phase→中文文案，收归 Shell 后前端删除该映射。
+
+### 1.2 入向命令（Consumer → Shell）
+
+| 命令 | 吸收的旧命令 | 说明 |
+|---|---|---|
+| `submit_intent` | `start_*` / `steer_*` | 一条消息可能 steer 进现有 run，也可能 start 新 run，由 Shell 判定 |
+| `answer` | `answer_game_creator_agent_runtime_user_input` | 回答澄清 |
+| `approve` | `confirm_*` / `reject_*` | 批准或拒绝，含 policy 确认卡 |
+| `cancel` | `cancel_game_creator_agent_runtime_task` | 取消 |
+| `resume` | `resume_*` / `confirm_resume_*` / `retry_*` / `confirm_retry_*` / `schedule_game_creator_agent_ready_tasks` | 恢复/重试/调度统一入口 |
+
+命令签名：
+
+```rust
+#[tauri::command]
+async fn submit_game_creator_agent_intent(
+    project_path: String, session_id: String, intent: String,
+    run_profile: Option<String>, source: Option<String>,
+) -> Result<AgentRuntimeIntentResult, String>;
+
+#[tauri::command]
+async fn answer_game_creator_agent_interaction(
+    project_path: String, run_id: String, action_id: String,
+    request_id: String, response_id: String, answers: BTreeMap<String, String>,
+) -> Result<AgentRuntimeResult, String>;
+
+#[tauri::command]
+async fn approve_game_creator_agent_interaction(
+    project_path: String, run_id: String, action_id: String,
+    approved: bool, note: String,
+) -> Result<AgentRuntimeResult, String>;
+
+#[tauri::command]
+async fn cancel_game_creator_agent_run(
+    project_path: String, agent_id: String, run_id: String,
+) -> Result<AgentRuntimeResult, String>;
+
+#[tauri::command]
+async fn resume_game_creator_agent_project(
+    project_path: String,
+) -> Result<Vec<AgentRuntimeResult>, String>;
+```
+
+协议外 API（不进交互 Loop，作为管理面保留在 Shell 上）：goal CRUD、`compact`、会话管理、配置读写。
+
+### 1.3 统一 InteractionRequired 语义
+
+Shell 向 Consumer 暴露"必须等待外部回答"的单一概念，替代现在分散的 `pendingToolAction` / `userInputRequest` / policy 确认卡：
+
+```rust
+enum AgentRuntimeInteractionRequired {
+    UserInput { request: AgentRuntimeUserInputRequestView },
+    Approval { action: AgentRuntimePendingToolActionSummary },
+    PolicyApproval { policy: String },   // 新增：吸收 confirm_resume/confirm_retry 的 agent.resume 确认卡
+}
+```
+
+> 现状的 `confirm_resume`（`commands.rs:1148`）与 `confirm_retry`（`commands.rs:1020`）是"要求用户确认策略"的产物，由 GUI 弹确认卡实现。收归 Shell 后，Shell 评估 `enforce_project_auto_permission_policy`（`verification.rs:813`），需要确认时返回 `InteractionRequired::PolicyApproval`，用户确认后经统一的 `approve` 命令继续。
+
+---
+
+## 2. 现状盘点与复用清单
+
+### 2.1 可直接复用的资产（近 1 个月内形成，活跃演进期）
+
+| 资产 | 位置 | 复用方式 |
+|---|---|---|
+| CLI 交互决策状态机 | `swarm_cli/turn_dispatch.rs:245` `decide_interaction_action`、`:48` `handle_swarm_user_turn`（steer/start、Reply/Execute/Resume、goal 门禁） | **整体上提**到后端 Shell（纯 Rust、无 UI 纠缠） |
+| Runner 自驱续跑定时器 | `runtime_driver/provider_recovery.rs` 的 `schedule_waiting_provider_retry_wake_after_lane_release` 等 | 已存在，P4 直接复用 |
+| 确定性 e2e | `scripts/agent-runtime-deterministic-playable-e2e.mjs` + `deterministic-lane-defense-provider.mjs`（`expectedProviderStats`/`expectedChildReport` 断言） | P0 基线扩展（协议级 trace） |
+| 版本协商 fallback | 前端 `model.ts:1186-1226` `isMissing*CommandError` | 迁移期新旧并存的标准模式 |
+| 逐命令幂等 | `accepted_run_id`（`runtime_state.rs:1548`）、runner requestId 缓存（`runner/protocol.rs:353`）、goal CAS | P1 设计直接沿用 |
+| 进程内集成测试 | `src-tauri/tests/`（`command_runtime.rs`、`runtime_actions/`、`collaboration/`、`goal.rs`） | P1-P6 每步回归的护栏 |
+
+### 2.2 需要收敛/改造的点
+
+| 点 | 位置 | 动作 |
+|---|---|---|
+| 前端 phase→文案映射 | `model.ts:612/644/974/1498/1554` | Shell 填充 `waiting_on/next_step` 后删除 |
+| 前端 steer/start 决策 | `model.ts:849` `submitProjectSupervisorRuntimeTask`、`App.tsx:5791` | 迁入 Shell（`submit_intent`） |
+| 前端 confirm/retry/resume 门禁 | `model.ts:1131-1154`、`panels.tsx:381-497` | 由 `InteractionRequired` + `approve/resume` 取代 |
+| 前端跨轮状态修补 | `model.ts:244` `normalizeAgentRuntimeState`、`:385` `mergeAgentRuntimeStateIntoMap` | 依赖 P2 Snapshot 稳定后删除 |
+| CLI 独立状态机 | `swarm_cli/turn_dispatch.rs` | 上提 Shell，CLI 只留终端交互（stdin/stdout/observer） |
+| 重复触发恢复 | `App.tsx:2799/10341`、`useDeveloperAgentPanel.ts:684`（启动时 resume）、`App.tsx:10550`（devMode schedule 按钮） | P4 后删除，由 Runner 自驱 |
+
+---
+
+## 3. 分阶段实施计划
+
+> 主线：**先建安全网 → 建统一入口 → 统一状态读取 → 收回决策 → Runner 自驱 → 迁移全部 Consumer → 删旧面**。
+
+### P0 行为基线（安全网）
+
+**目标**：在改动前建立可判断"公开行为是否变化"的验证能力。
+
+- 复用 `deterministic-lane-defense-provider.mjs`，在现有 `agent-runtime-deterministic-playable-e2e.mjs` 基础上**增加协议级事件 trace**：
+  - 录制一条确定性完整会话的**出向事件序列**（progress/needs_input/approval_required/done/error 的顺序与关键载荷），归一化 timestamp、`run_id`/`steer_id`/`request_id` 随机 ID、`accepted_run_id` 对账值。
+  - 断言当前 master 的 trace 与预期一致（快照 diff）。
+- 建立统一的回归命令，P1-P6 每阶段结束必跑：
+  - 确定性 e2e（功能正确性）
+  - `src-tauri/tests/` 进程内集成测试（单元级护栏）
+  - 协议级 trace（迁移等价性）
+- **不动 Runtime 代码**，只建安全网。
+
+**验收**：上述三条命令在当前 master 全绿，trace 基线文件入库。
+
+### P1+P2 统一入口 + 状态读取（adapter + Snapshot 投影）
+
+**目标**：Consumer 改走新协议调用旧实现；状态读取收敛为稳定的公开 Snapshot。**旧接口全保留**为迁移期兼容路径。
+
+**P1 适配器（`submit_intent` / `approve` / `answer` / `cancel` / `resume` 新命令）**：
+
+> **P1 与 P3 的边界**：P1 只做"命令可用 + `submit_intent` 内部判定 steer/start"。`answer`/`approve`/`resume` 在 P1 **只是入口封装**（内部调旧函数），"收到交互该调哪个命令、能否重试"的判定**仍在前端**；到 P3 才把判定收走，前端只剩 `submit`/`respond` 两种动作。
+
+- 新增 `src-tauri/src/agent/supervisor_shell/`，内含：
+  - `intent.rs`：`submit_intent` 内部路由——读当前 runtime → 判定 steer/start（逻辑取自 `swarm_cli/turn_dispatch.rs` 的 steer 判定与前端 `matchingAgentRuntimeForSteer`）→ 调现有 `steer_game_creator_agent_runtime_task_for_profile_at` 或 `start_game_creator_supervisor_background_task_for_session_at` → 返回 `{ mode, accepted_run_id, runtime }`。
+  - `interaction.rs`：`approve/answer/cancel` 薄封装现有 `confirm/reject/answer/cancel` 内部函数（P1 只封装，判定仍在前端）。
+  - `resume.rs`：`resume_game_creator_agent_project` 吸收 `resume/confirm_resume/retry/confirm_retry/schedule_ready`——Shell 判定是否需 policy 确认、是否需先 cancel 再重试（`needs-reconciliation` 分支，逻辑取自 `App.tsx:6205` `handleProjectSupervisorRetry`）。
+- 新命令与旧命令**同时注册**（`main.rs` invoke_handler）。
+- 前端新增"调新命令 → 后端报 unknown command → 回退旧命令"的版本协商（复用 `isMissing*CommandError` 模式），保证打包版本不一致时旧链路可用。
+- **fallback 边界**：仅"命令不存在（版本不兼容）"确定性回退；写操作的其他错误原样呈现，不做盲目重试（防重复入队）。
+
+**P2 Snapshot 投影（状态读取收敛）**：
+
+> **投影 = 读模型**：把同一份 Runtime durable state（唯一事实来源）按一个稳定、精简、面向消费的 schema 重新导出，作为 Consumer 的权威视图。它**不是新的事实来源**，只是同一份事实的另一种呈现；Consumer 依赖投影，业务真相仍在 durable state。
+
+- 新增 `supervisor_shell/snapshot.rs`：`AgentRuntimeSnapshot` 投影。
+  - 输入：现有 `AgentRuntimeResult.state` + `recent_events`/`recent_tasks`/`response_stream`/`user_input_request`。
+  - 输出：稳定的公开视图（agent/session/run 身份、status/phase、`InteractionRequired`、progress、终态、公开错误）。
+  - **内部字段（recentToolCalls、observations、allowedTools、contextUsage 等）不进 Snapshot**。
+- 关键：**后端先补"稳定读取"**——现状前端 `normalizeAgentRuntimeState` 做跨轮 carry-forward，是因为后端 read 在恢复/竞态时字段不稳定。P2 后端投影保证同一 run 身份下字段自洽，前端才能删掉自己的修补。
+- 新增 `read_game_creator_agent_runtime_snapshot(s)` 命令（或改造现有 read 返回 Snapshot），旧 `read_game_creator_agent_runtime(s)` 保留。
+- 前端 `normalizeAgentRuntimeState` / `mergeAgentRuntimeStateIntoMap` / phase→文案映射**依赖 P2 稳定后删除**（本轮先做投影，下一阶段删前端逻辑）。
+
+**验收**：
+- 新命令与旧命令对同一场景返回的终态一致（用 P0 trace + 确定性 e2e 断言）。
+- 前端在"走新 Snapshot"下渲染与旧路径一致（组件回归）。
+- 现有 `command_runtime.rs` / `collaboration/` 测试全绿（旧逻辑未动）。
+
+### P3 Loop 收归 Supervisor Shell
+
+**目标**：Consumer 只 dispatch 意图，不再持有生命周期判断。
+
+- 完成 `submit_intent` / `approve` / `answer` / `cancel` / `resume` 对全部旧分叉的吸收（P1 已建，本轮做全）：
+  - `approve` 吸收 confirm/reject，并按 interaction kind 分派（`UserInput`/`Approval`/`PolicyApproval`）。
+  - `resume` 吸收 resume/confirm_resume/retry/confirm_retry/schedule_ready。
+- 建立 `AgentRuntimeInteractionRequired`（见 1.3），Shell 统一暴露"需等待外部回答"。
+- Shell 负责填充 `waiting_on`/`next_step`（从 phase 映射，逻辑上提自 `model.ts:612/644`）。
+- 新增派生事件 `tool_request`（Shell 从 `recentToolCalls` + phase 投影）。
+- **前端删除**：
+  - `submitProjectSupervisorRuntimeTask` 的 steer/start 决策（`model.ts:849`）。
+  - `agentRuntimeCanCancel/CanRetry/CanConfirm` 门禁（`model.ts:1131-1154`）。
+  - `App.tsx:5981/6127/6205` 的 confirm/retry/repair 路由逻辑。
+- CLI（`swarm_cli`）改为调用同一 Shell：决策逻辑上提后，CLI 只保留 stdin/stdout 终端交互与 observer 渲染。
+
+**验收**：
+- CLI 走新协议跑通完整 supervisor+子 Agent 流程（`agent-swarm-test-chat.mjs` / 确定性 e2e）。
+- GUI 提交、确认、重试、恢复均通过统一 `submit_intent/approve/resume`，无 `steer_*`/`confirm_*`/`retry_*` 直接调用。
+- P0 协议级 trace 在"新旧实现各放一遍"下事件序列一致。
+
+### P4 Runner 自驱
+
+**目标**：工作发现、恢复、继续执行不依赖 Consumer 触发。**这是重构主线的一部分，不是独立项目。**
+
+- 项目目录簿：`runner/state.rs` 的 `known_roots`（当前进程内）→ 持久化到 AppData（复用 runner 的 `--config-dir`），Runner 重启后仍知道持有过哪些项目。
+- 启动自恢复：`runner/server.rs` 启动完成后，对 known roots 调 `has_recoverable_game_creator_agent_background_tasks_at`（`recovery_scan.rs:425`），有可恢复工作则自动 `resume_game_creator_agent_background_tasks_at`。
+- 空闲自扫描：主 accept loop（`server.rs:275`，已有 25ms `EXTERNAL_AGENT_RUNNER_LOOP_INTERVAL`）内增加"是否有 pending 任务需 wake"的轻量检查，替代 Consumer 调 `schedule_game_creator_agent_ready_tasks` / `wake_pending`。
+- 吸收 `schedule_game_creator_agent_ready_tasks`：manifest ready 任务由 Runner 扫描发现并调度，删除前端 devMode 按钮（`App.tsx:10550`）。
+- **边界（不在本轮）**：Runner 仍由 GUI 启动（`main.rs:2124`），保留 GUI-owner watchdog（`server.rs:169`）与 `game_chat_release` 退出协议（`main.rs:2311`）。"自驱 = 存活期间自调度 + 启动自恢复"，**不含**开机自启/无 GUI 常驻。
+- 对应删除前端恢复触发职责：`App.tsx:2799/10341`、`useDeveloperAgentPanel.ts:684` 的启动时 resume、resume 确认卡回调。
+
+**验收**：
+- Runner 进程内：确认一个 pending 任务后无需任何 Consumer 调用即自动执行；恢复 pending 动作后自动续跑。
+- 确定性 e2e 增加"Runner 独立进程跑完整流程"用例（复用 `agent-runtime-real-e2e/harness/process.mjs` 的二进制编译能力）。
+- `confirm_resume` 恢复确认卡流程改为 `InteractionRequired::PolicyApproval` → `approve`。
+
+### P5 迁移 GUI / CLI / Tests
+
+**目标**：三类 Consumer 全部迁移到统一 Intent、Snapshot、Runtime Output。
+
+- GUI：
+  - 状态渲染改读 `AgentRuntimeSnapshot`；删除 `normalizeAgentRuntimeState` / `mergeAgentRuntimeStateIntoMap` / phase 文案映射。
+  - 交互全走 `submit_intent/approve/answer/cancel/resume`；删除 steer/confirm/retry/resume 直接调用与门禁。
+  - 保留只读消费形态：response stream 展示、对话合并、画布资产编排（这些不进 Loop 协议）。
+- CLI：`cli.rs` 与 `swarm_cli` 改用 Shell 命令；删除各自状态机（决策已上提）。
+- Tests：`src-tauri/tests/` 迁移到新命令；`agent-runtime-real-e2e` 与确定性 e2e 走同一协议。
+- 迁移顺序：先 CLI（最薄）→ 再 Tests → 最后 GUI（唯一消费 response stream / conversation 合并 / goal CAS / 委派修复路由，工作量最大）。
+
+**验收**：GUI、CLI、Tests 调用面收敛到同一组命令，代码差异只剩输入输出形式。
+
+### P6 删除旧公开面
+
+**目标**：Interaction Contract 成为唯一稳定公开边界。
+
+- 删除旧 Tauri 命令：`start_game_creator_agent_runtime_task` / `start_game_creator_supervisor_runtime_task` / `steer_*` / `confirm_*` / `reject_*` / `retry_*` / `confirm_retry_*` / `resume_game_creator_agent_runtime_tasks` / `confirm_resume_*` / `schedule_game_creator_agent_ready_tasks` / `read_game_creator_agent_runtime(s)`（`main.rs:2188-2208`）。
+- 删除对应后端 wrapper 与前端 `app/types.ts` 旧 DTO、旧事件协议、迁移期兼容逻辑。
+- 现有 start / steer / resume / recovery 能力作为 Shell 内部实现保留（改名/内联）。
+
+**验收**：`grep` 无旧命令名残留；全量回归（P0 基线 + 单元 + e2e）全绿。
+
+---
+
+## 4. 迁移策略（新旧并存 + 等价性）
+
+1. **接口即实现，不留空窗**：新命令从注册第一天起就是真实可用——内部套用现有旧函数（adapter 套旧实现是**常态、透明**，前端不知道也不关心）。不存在"接口先立、实现待填"的中间态；分阶段的不是"接口 vs 实现"，而是"谁先切到新接口"。
+2. **新旧并存**：P1 起新命令与旧命令同时注册，Consumer 逐个切换，旧路径逐条下线（strangler fig）。
+3. **版本协商 fallback（仅用于迭代空窗期）**：前端调新命令，**仅当**后端报 unknown command（前端版本 ≠ 后端版本，打包错位）时回退旧命令；其他运行错误**原样呈现，不盲目重试**（防重复入队）。后端新版随应用覆盖到位后，fallback 即死代码，P6 删除。
+4. **等价性保障**：
+   - 确定性 provider + 协议级 trace（P0）作为新旧实现的对照基线。
+   - 进程内集成测试每阶段全跑。
+   - 关键迁移点（steer/start 判定、resume 路由、needs-reconciliation 重试）用"同一输入 → 新旧实现输出一致"的单测锁定。
+
+---
+
+## 5. 里程碑与验收门禁
+
+| 里程碑 | 交付 | 门禁 |
+|---|---|---|
+| M0 | P0 基线 + trace 入库 | 回归三件套全绿 |
+| M1 | P1 新命令 + adapter（新旧并存） | 新/旧命令终态一致；现有测试全绿 |
+| M2 | P2 Snapshot 投影 + 前端读 Snapshot | 前端删 normalize 后渲染回归一致 |
+| M3 | P3 Loop 收归（Intent + InteractionRequired） | CLI 走新协议跑通完整流程；前端无 steer/confirm/retry 直调 |
+| M4 | P4 Runner 自驱 | Runner 独立进程自动跑完；resume 确认走统一 approve |
+| M5 | P5 全部 Consumer 迁移 | GUI/CLI/Tests 调用面收敛到同一协议 |
+| M6 | P6 删旧面 | 无旧命令残留；全量回归绿 |
+
+---
+
+## 6. 风险与未决问题
+
+| 风险/问题 | 影响 | 缓解 |
+|---|---|---|
+| P2 依赖"后端 read 先稳定"，否则前端不敢删 normalize | 阶段顺序敏感 | P2 后端投影先行，前端删逻辑放同一阶段尾 |
+| P4 自驱与 GUI-owner 安全模型冲突 | 若误解为"无 GUI 常驻"会引安全评审 | 计划内明确边界，实现不越界 |
+| steer/start 判定含 UX 语义（mode/source/runProfile、steerId 生成、acceptedRunId 对账） | 收归 Shell 后前端展示可能退化 | Shell 返回 `{ mode, accepted_run_id, steer_decision }` 补足展示信息 |
+| `tool_request` 无现成单一落点 | 需 Shell 派生投影 | 提前排进 P2/P3 投影工作量 |
+| 协议级 trace 的随机 ID 归一化 | 基线易碎 | 复用确定性 provider，归一化规则集中一处 |
+
+## 7. 建议实施顺序（一句话）
+
+P0 建安全网 → P1+P2（adapter + Snapshot，纯增量、旧接口全留、fallback 兜底）→ P3 收 Loop → P5 迁移（先 CLI 后 GUI）→ P6 删旧面；P4（Runner 自驱）作为主线中心件贯穿 M4，不单独立项，但边界（存活期间自调度，不含无 GUI 常驻）在计划内写死。
+
+---
+
+## 8. 相对原方案的调整点
+
+本计划在原方案基础上做了以下调整，均基于 master 现状与既有安全模型：
+
+1. **P0 基线**：原方案的 Golden Replay 改为"确定性 e2e + 协议级事件 trace"——在既有确定性 provider e2e（`deterministic-lane-defense-provider.mjs`）上扩展，录制协议级事件序列并归一化 timestamp 与随机 ID，不重建基线体系。
+
+2. **P4 定位与边界**：原方案将"Supervisor Lifecycle Coordinator"列为独立阶段；现作为主线组成部分（里程碑 M4，不单独立项）。自驱限于"Runner 存活期间自调度 + 启动自恢复"，排除"开机自启 / 无 GUI 常驻"，与既有 GUI-owner 安全模型一致。
+
+3. **术语收敛**：原方案"Interaction Contract / Intent / Snapshot"统一为本计划"交互 Loop 协议"（5 入向命令 + 7 出向事件）与"投影"（读模型），含义不变。
+
+4. **迁移原则显式化**：接口即实现（adapter 套旧逻辑为常态）；fallback 仅在版本空窗期、只认 unknown command。原方案未明确此点。