文档：作废 D6，立项策划改为 Supervisor 下游工作流节点
产品侧确定「做方案」入口独立成链后复核代码，D6 的前提逐条不成立： autonomous-game-build 对 user.input_request 的禁令按 run profile 生效、 父子皆不可提问；硬闯会把 runtime.status 写成 failed，而根活跃判定不认 failed，导致整条 16 节点工作流永久瘫痪；子 Run 又不能切换父 Run 的 profile；作为下游的策划节点带 parent，也不能自己提问。 新增 D9 / D10 取代 D6：策划是独立 agentId 的下游工作流节点，父子同为 standard；问询走 Runtime 直投——策划节点提交结构化决策字段，Runtime 创建 owner 为 Supervisor 的 pending。这不是新造机制，现役 AgentRuntimeUserInputRecord 本就两路投影（会话消息 + observation）， 直投只是让两路分别落到 Supervisor 与策划节点，从而满足「用户侧只有一个 对话对象」与「对话内容必须物理存在于 Supervisor 会话」两条产品约束。 新增第 1.1 节承载变更说明与 M0 修订计划（工作包 M0A-3），按是否被 agentId/source 命名裁决阻塞分两批。三个代码工作包零回退——无一行按 D6 编写；但 M0A-2 的 owner 验证四重绑死且要求 parent，standard 路径必须 另建物理独立实现，不可扩展。 Goal Contract 四方案随之作废，替换为三条实测约束，其中「验收 evidence 锚 game/fast_gdd.md、不得指向 .agent/planning」是为了避开 reject_agent_runtime_private_control_path 不区分读写的陷阱。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
@@ -1,5 +1,17 @@
|
||||
# 决策记录
|
||||
|
||||
## 2026-08-12 立项策划 D6 作废：策划改为 Supervisor 下游工作流节点，问询走 Runtime 直投
|
||||
|
||||
- 背景：产品侧确定「做方案」入口独立成链——不动做游戏路径，最终产物只有策划方案，且保持 Supervisor 顶层、工作流节点与子 Agent 在下游的结构。据此复核代码后，D6「策划是 Project Supervisor 通道的第三 persona、复用同一 `agentId`、不注册新 agentCatalog 身份」的前提逐条不成立。
|
||||
- 事实基线（均已逐处打开源码核对）：`user.input_request` 在 `autonomous-game-build` 下被广告层（`tool_policy_snapshot.rs:198-215`）与执行层（`main_loop.rs:2604-2616`）两道拦截，**判据只看 run profile、不看 agent 身份，父 Supervisor 自己也被禁**；硬闯的后果是 `pending_execution.rs:1157` 把 `runtime.status` 写成 `failed`，而 `task_start.rs:685-693` 的根活跃判定不认 `failed`，**整条 16 节点工作流永久瘫痪、须人工核对**；`run_configuration.rs:264-266` 明文「子 Run 不能切换父 Run 的 Run Profile」，故不能只给策划节点换 profile；`user_input.rs:367-394` 拒绝任何带 `parent_agent_id / parent_run_id / delegation_id` 的 run 直接提问。
|
||||
- 决策（D9，取代 D6）：立项策划是独立 `agentId` 的下游工作流节点，由 manifest ready-task 调度器在 Supervisor 下游启动，需登记 agentCatalog；Project Supervisor 以新可信 source 承载「做方案」入口并保持唯一顶层 root；父子 run profile 必须同为 `standard`。「复用 standard」这一结论方向从 D6 继承，但成立理由完全不同。
|
||||
- 决策（D10，问询机制）：策划节点不得直接调用 `user.input_request`，改走 **Runtime 直投**——策划节点提交结构化决策字段，Runtime 创建 **owner 为 Project Supervisor** 的 pending，用户在 Supervisor 对话里回答，Supervisor 的 Provider 全程不参与提问。这不是新造机制：`AgentRuntimeUserInputRecord` 已经是唯一事实源并两路投影（`user_input.rs:494-530` 投影成会话消息写进 pending owner 的会话文件，`:595-623` 投影成结构化 observation，`:803-807` 有「observation 重算冲突」校验防漂移），直投只是让两路分别落到 Supervisor 与策划节点。
|
||||
- 依据的产品约束：一、用户侧只有一个对话对象；二、所有呈现给用户的对话内容必须**物理存在于** Supervisor 的会话文件中，不得由前端把多个 Agent 的会话拼成单一视图。第二条不是靠约定满足，而是靠「会话文件按 `agentId` 分目录（`conversation.rs:42`）、消息归属完全由 pending owner 决定」这个物理事实。
|
||||
- 决策卡冻结范围收窄：冻结三个固定选项及顺序（要确定性映射到 decision state 与 answer source）与 question ID 规则（`decisionId` 由它推导）；**问题正文措辞不冻结**，作者是策划节点。保真由「Runtime 不经过任何 Provider 搬运」保证，与模板无关。
|
||||
- Goal Contract 处置：原四方案 A/B/C/D 随之作废（共同前提是策划 run 自己就是那个 root）。但入口门 `validate_root_goal_contract_control_plan_at` 无 profile 判断，standard root Supervisor 仍受约束，故替换为三条实测约束：Supervisor 第一轮必须且只能提交 `agent.goal_contract`；验收 `requiredEvidence` 锚定 `game/fast_gdd.md` 配 `tool:file.read`，**不得指向 `.agent/planning/**`**（`reject_agent_runtime_private_control_path` 不区分读写，加进去会把 `file.read` 一并挡死、出口门永久 blocked，planning 的写保护须用只挡写的独立判据）；Supervisor 取证必须在 GDD 落盘之后。
|
||||
- M0 影响判定：三个代码工作包（`M0A-2` / `M0B-1` / `M0B-2`）**全部不受影响、零回退**——无一行按 D6 编写，全仓库检索 `fast_gdd` / `.agent/planning` / `project-supervisor-plan-chat` / `is_exact_supervisor_plan_run_at` 均零命中。只有 `M0A-1` 交付的文档基线失效，以工作包 `M0A-3` 修订，修订完成前不得声称「M0 全部完成」。**注意 `M0A-2` 虽不受影响，其实现也不可复用**：`autonomous_owner_artifact_validation_available_for_run_at`（`autonomous_completion.rs:416-441`）四重绑死 owner 白名单、profile、source 且要求 `parent_agent_id` 为 Project Supervisor，standard 路径必须另建物理独立实现。
|
||||
- 保留待裁决：策划节点 `agentId` / source 命名（是 `M0A-3` 批二的共同阻塞点，身份常量不定则第 3、8、9、12、13 节无法落笔，第 9.1 节 golden vector 的 SHA-256 必然重算）；Supervisor 侧新可信 source 是沿用旧字符串还是取新名；checkpoint handoff 私有持久化（原有项，不受影响）；plan run 是否允许 steer，以及 Supervisor 被 steer 时下游策划节点如何收束。
|
||||
|
||||
## 2026-08-12 M0 全部完成，并据动态目标验收图收敛 M2 / M3 设计（M1 裁决保留）
|
||||
|
||||
- 背景：M0-1～M0-4 及 `M0A-1` / `M0A-2` / `M0B-1` / `M0B-2` 四个工作包全部通过门禁并合入 M0 集成分支 `feat/five_min_design`（已推送）。M0 按整体切片交付，不逐工作包直接进 master，因此「未进 master」不作为 M0 未完成的依据。
|
||||
|
||||
@@ -1,5 +1,15 @@
|
||||
# 踩坑与排障记录
|
||||
|
||||
## 2026-08-12 在 autonomous-game-build 下试图向用户提问，会让整条工作流永久瘫痪
|
||||
|
||||
- 现象：给自主构建链路加「问用户一句」的需求时，最自然的两个想法——让 DAG 节点自己问、或让父 Supervisor 代问——**都不成立**，而且第二个的失败方式是灾难性的。
|
||||
- 拦截一（节点自己问）：`apps/ai-game-creator-shell/src-tauri/src/user_input.rs:367-394` 的 `validate_user_input_action_owner` 三路 OR 拒绝任何带 `parent_agent_id / parent_run_id / delegation_id` 的 run。autonomous 的 ready-task 调度器在 `apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/task_start.rs:905-907` **显式**给每个 DAG 子节点写 parent，因此必然命中。
|
||||
- 拦截二（父代问）：`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/tool_policy_snapshot.rs:198-215` 只要 `run_profile == autonomous-game-build` 就把 `user.input_request` 从 `auto_tools` / `confirm_tools` 移除并推进 `denied_tools`；`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/main_loop.rs:2604-2616` 在执行层再拒一次。**两处判据都只看 profile、不看 `agent_id`，所以 root Supervisor 自己也在禁令内**——「父能问、子不能问」这个中转赖以成立的不对称，在 autonomous 下根本不存在。
|
||||
- 真正的坑（后果放大）：硬闯不是「这次失败」，而是**整条流水线停摆**。执行层拒绝会走 `mark_game_creator_agent_runtime_needs_reconciliation_at`，`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/pending_execution.rs:1157` 把 `runtime.status` 直接写成 `failed`；此后每次调度 ready task 必经的 `autonomous_game_build_root_task_is_active`（`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/task_start.rs:685-693`）只认 `pending | running | waiting-for-confirmation | waiting-for-user-input`，`failed` 不在其中，于是报「父 Run 已不再活跃」，**剩余节点一个都起不来，须人工核对才能恢复**。同一类故障本仓库已踩过一次，见下方「自主模式不能保留任何 RequiresConfirmation 漏口」条。
|
||||
- 也别想着换 profile 绕开：`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/run_configuration.rs:264-266` 明文「子 Run 不能切换父 Run 的 Run Profile」，且 profile 是 run 绑定时 CAS 锁死的终身属性。
|
||||
- 处理：需要与用户往返的链路必须整体跑在 `standard` profile 下。`standard` 的 ready-task 调度器（`task_start.rs:566-580`，走 `..._with_source_at` 而非 `..._with_link_at`）不写 parent，节点是自己的 root run，上述拦截一并不适用。这是 2026-08-12 立项策划 D9 改用「Supervisor + standard 下游工作流节点」的直接原因，见 decision-log 同日条。
|
||||
- 附带结论：`autonomous_owner_artifact_validation_available_for_run_at`（`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion.rs:416-441`）同样四重绑死 owner 白名单、profile、source，且**要求 `parent_agent_id` 为 Project Supervisor**——standard 节点无 parent，第 436 行即不通过。想给 standard 路径加 owner 产物验证的人不要试图扩展它，必须另建。
|
||||
|
||||
## 2026-08-12 往 trusted supervisor source 里加新 source，等于同时授予 Goal Contract 参与者身份
|
||||
|
||||
- 现象：`agent_runtime_supervisor_source_is_trusted`（`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver.rs:113`）读起来像一个「谁能启动 Project Supervisor」的入口白名单，实际早已是多条互不相干的授权判据的共同开关。2026-08-11 合入动态目标验收图后，它的非测试消费者从 2 个文件涨到 10 个文件 18 处调用：run 启动（`commands.rs:698`）、steer（`commands.rs:876`、`steering.rs:763`）、Goal Contract 创建权限（`goal_contract.rs:496`）、根控制面工具是否被剥离（`provider_request_builders.rs:134` 的 `root_control_authority`）、验收图完成门（`acceptance_graph.rs:595`）、run configuration、lifecycle_control、task_start、project_gates、autonomous_completion。
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# 立项策划 Agent（Fast GDD）技术方案
|
||||
|
||||
- 日期：2026-08-10
|
||||
- 状态：2026-08-12 起 **M0 全部完成**（M0-1～M0-4 / `M0A-1`、`M0A-2`、`M0B-1`、`M0B-2` 均已合入 M0 集成分支并通过各自门禁，见第 23.4 节）；M1～M3 功能尚未实现，且 M1 有两项入口前置决策待裁决（见第 23.1 节）
|
||||
- 状态：2026-08-12 **M0 代码工作包全部完成**（`M0A-2`、`M0B-1`、`M0B-2` 已合入 M0 集成分支并通过各自门禁，见第 23.4 节）；同日 **D6 作废、拓扑改变**，`M0A-1` 交付的文档基线随之失效，需以工作包 `M0A-3` 修订，**修订完成前 M0 不计完整完成**（见第 1.1 节）。M1～M3 功能尚未实现，全仓库零代码
|
||||
- 适用范围：AI 游戏创作独立 App、Project Supervisor、Agent Runtime、本地项目策划 sidecar 与后续完整构建准入
|
||||
- 当前实现边界：本文件是后续详细设计与实现的仓库内阶段基线；M0 工作包只冻结 Fast GDD 合同并修复现有 owner 验证、game-chat retry 与前端投影边界，不代表立项策划入口、审批 UI、Runtime 持久化或构建绑定已经可用
|
||||
|
||||
@@ -9,7 +9,7 @@
|
||||
|
||||
当前普通完整构建会从简短需求直接进入 `autonomous-game-build`，用户在消耗完整构建成本前没有正式确认玩法方向、MVP 范围和原型验证项的环节。现有完整构建中的 `design-director` 是只读协调任务，`design-foundation` 又会自行补齐玩法定位；用户意图与后续实现之间缺少可版本化、可审批、可恢复的策划基线。
|
||||
|
||||
本方案新增“立项策划”阶段：用户给出一句需求后，由同一 Project Supervisor 顶层通道切换到独立 persona，在最多 3 轮决策卡内形成 Fast GDD；Runtime 校验并提交不可变版本，用户通过审批卡批准、修改或退回。只有不可变 GDD 与对应 approve receipt 同时有效时，后续完整构建才能取得 `approvedGddRef`。
|
||||
本方案新增“立项策划”阶段：用户给出一句需求后，由 Project Supervisor 顶层 run 调度一个独立 `agentId` 的下游策划工作流节点（2026-08-12 起，取代原“同一通道切换 persona”的表述，见第 1.1 节与 D9），在最多 3 轮决策卡内形成 Fast GDD；Runtime 校验并提交不可变版本，用户通过审批卡批准、修改或退回。只有不可变 GDD 与对应 approve receipt 同时有效时，后续完整构建才能取得 `approvedGddRef`。
|
||||
|
||||
目标：
|
||||
|
||||
@@ -29,7 +29,83 @@
|
||||
- 不修改 SpacetimeDB、HTTP API、OpenAPI 或 `shared-contracts` 中的正式作品数据合同。
|
||||
- M1 不实现 300 秒硬停；以 3 轮硬上限和 240 秒 Agent 活跃时间软提示收束。
|
||||
|
||||
## 2. 已锁定决定 D1～D8
|
||||
### 1.1 2026-08-12 设计变更与 M0 修订计划（工作包 `M0A-3`）
|
||||
|
||||
**D6 已作废，策划 Agent 不再是 Project Supervisor 的第三 persona。** 本节是当前唯一权威的变更说明与修订计划。在 `M0A-3` 收口前，第 2～6、12、14、18.1、19、22～24 节中凡与本节冲突的表述，**一律以本节为准**。
|
||||
|
||||
#### 变更触发
|
||||
|
||||
产品侧先确定「做方案」入口独立成链：不动做游戏路径，最终产物只有策划方案，且保持 Supervisor 顶层、工作流节点与子 Agent 在下游的结构。据此复核代码后，D6 的三项前提逐条不成立：
|
||||
|
||||
1. **策划不能跑在 `autonomous-game-build` 下。** `user.input_request` 被两层拦死且判据只看 run profile、不看 agent 身份——广告层 `apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/tool_policy_snapshot.rs:198-215` 按 profile 剔除并推进 `denied`；执行层 `apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/main_loop.rs:2604-2616` 直接判 `NeedsReconciliation`。**父 Supervisor 自己也在禁令内。**
|
||||
2. **硬闯的后果是整条工作流永久瘫痪，不是单次失败。** `apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/pending_execution.rs:1157` 把 `runtime.status` 写成 `failed`，而 `apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/task_start.rs:685-693` 的根活跃判定只认 `pending | running | waiting-for-confirmation | waiting-for-user-input`，此后任何 ready task 都起不来，须人工核对。
|
||||
3. **不能只给策划节点单独换 profile。** `apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/run_configuration.rs:264-266` 明文「子 Run 不能切换父 Run 的 Run Profile」，且 profile 是 run 绑定时 CAS 锁死的终身属性。
|
||||
4. **策划节点作为下游有 parent，不能自己向用户提问。** `apps/ai-game-creator-shell/src-tauri/src/user_input.rs:367-394` 的 `validate_user_input_action_owner` 三路 OR 拒绝任何带 `parent_agent_id / parent_run_id / delegation_id` 的 run。
|
||||
|
||||
#### 新拓扑（替代 D6）
|
||||
|
||||
- **Supervisor 仍是唯一顶层 root run**，以新的可信 source 承载「做方案」入口，run profile 固定 `standard`。
|
||||
- **策划 Agent 是独立 `agentId` 的下游工作流节点**，由 manifest ready-task 调度器在 Supervisor 下游启动，profile 随父固定为 `standard`。本版工作流只有这一个节点，但框架按将来可加节点搭建。
|
||||
- **问询改为「Runtime 直投」**：策划节点提交结构化决策字段，Runtime 据此创建 **owner 是 Supervisor** 的 `user.input_request` pending（`agentId` 为 Project Supervisor、Supervisor 的 session 与 run），用户在 Supervisor 对话里回答。Supervisor 的 Provider 完全不参与提问，是纯函数搬运。
|
||||
- **一份记录两路投影**（复用现役机制，非新造）：`AgentRuntimeUserInputRecord` 是唯一事实源；`apps/ai-game-creator-shell/src-tauri/src/user_input.rs:494-530` 把它投影成会话消息写进 pending owner 的会话文件，`:595-623` 投影成结构化 observation。直投只是让会话投影落到 Supervisor、observation 投影落到策划节点。会话文件按 `agentId` 分目录（`apps/ai-game-creator-shell/src-tauri/src/project/conversation.rs:42`），因此消息归属完全由 pending owner 决定；`:803-807` 的「observation 重算冲突」校验保证两路不漂移。
|
||||
|
||||
该拓扑要满足的两条产品约束：**一、用户侧只有一个对话对象；二、所有出现过的对话内容必须物理存在于 Supervisor 的会话里**——用户后续引用或隐式依赖时，那些内容必须真在上下文中，不能靠前端把多个 Agent 的对话拼在一起显示。直投满足第二条不是靠约定，是靠「消息写在哪个会话文件里」这个物理事实。
|
||||
|
||||
#### 修订范围：只有文档，代码零回退
|
||||
|
||||
| 工作包 | 判定 | 依据 |
|
||||
| --- | --- | --- |
|
||||
| `M0A-1` 文档基线 | **需修订**，即本工作包 `M0A-3` | 是 D6 的唯一载体 |
|
||||
| `M0A-2` owner 产物验证 | **不受影响，但不可复用** | 见下 |
|
||||
| `M0B-1` game-chat 美术边界 | **不受影响** | 只处理 game-chat 单主谱系 |
|
||||
| `M0B-2` game-chat 前端投影 | **不受影响** | 只认 game-chat root → 单主 `code-prototype` 谱系 |
|
||||
|
||||
M0 三个代码工作包无一行按 D6 编写，**不需要为新设计回退或修改任何已合入代码**。全仓库检索 `fast_gdd`、`.agent/planning`、`project-supervisor-plan-chat`、`is_exact_supervisor_plan_run_at` 均零命中，M1 尚未落地任何代码，因此改文档没有迁移成本。
|
||||
|
||||
**但 `M0A-2` 的实现不可被 standard 路径复用。** `autonomous_owner_artifact_validation_available_for_run_at`（`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion.rs:416-441`）四重绑死：owner agent 白名单、`profile == autonomous-game-build`、`source == agent-ready-task-scheduler`、**且要求 `parent_agent_id` 为 Project Supervisor**。standard ready-task 节点无 parent，第 436 行即不通过。standard 路径的 owner 产物验证必须另建一套物理独立实现——这是**新增**，不是扩展，不要把「不受影响」误读为「可以直接改现有函数」。
|
||||
|
||||
#### 分两批执行
|
||||
|
||||
**批一（不依赖命名裁决，可立即修订）**
|
||||
|
||||
- 第 1.1 节（本节）、文首状态行、第 2 节 D6 作废与新决定入表
|
||||
- 第 19 节第 2 条、第 24 节第 8 条：按 Supervisor 根 run 与策划工作流节点两套判据拆写
|
||||
- 第 23.1 节：删除 Goal Contract 四方案 A/B/C/D，替换为已验证的三条约束（见下）
|
||||
- 第 22 节证据表：`trusted matcher 消费者`行结论句改写；新增 standard 路径 owner 验证、Runtime 直投两行
|
||||
- 第 23.4 节：M0 完成状态改为「代码完成、文档待修订」
|
||||
|
||||
**批二（被「策划节点 `agentId` / source 命名」裁决阻塞）**
|
||||
|
||||
- 第 3 节注册表全部身份常量、第 4 节拓扑图、第 4.1 / 4.2 节（整节作废后重写）、第 4.3 节工具清单
|
||||
- 第 5.1 / 5.2 节 checkpoint 触发点、第 6 节 Prompt 权威稿
|
||||
- 第 8.3～8.6 节身份字段取值、第 9.1 节 golden vector 重算（现值 `d85c85dae3…` 必然失效）
|
||||
- 第 12 节 submit dispatch 段、第 13.1 / 13.3 节 `agentId` 常量、第 14 节 activeQuestion 相关五行恢复语义
|
||||
- 第 18.1 节前端入口
|
||||
|
||||
命名未定前批二一个字都无法落笔，因此该裁决是 `M0A-3` 的首要前置。
|
||||
|
||||
#### Goal Contract：四方案作废，替换为三条已验证约束
|
||||
|
||||
原第 23.1 节的 A/B/C/D 四方案共同前提是「策划 run 自己就是那个需要豁免的 root」，新拓扑下 root 是未变的 Supervisor，四选一问题消解。但**入口门仍然适用**：`validate_root_goal_contract_control_plan_at`（`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/autonomous_policy.rs:171-236`）无 run profile 判断，standard root Supervisor 同样受约束。故替换为：
|
||||
|
||||
1. **Supervisor 第一轮必须且只能提交 `agent.goal_contract`**，不得夹带其它 action、`plan_update`、legacy plan 或 response。做方案场景下可满足——交付物「一份获批的方案」开工即确定，不存在自主构建里「目标未澄清就要冻结」的矛盾。
|
||||
2. **验收节点的 `requiredEvidence` 锚定 `game/fast_gdd.md` 配 `tool:file.read`，不得指向 `.agent/planning/**`。** `reject_agent_runtime_private_control_path`（`apps/ai-game-creator-shell/src-tauri/src/project/filesystem.rs:253-266`）目前只挡 `.agent/runtime`、`.agent/checkpoints`、`.agent/workbench` 三类，planning 不在内；但该函数**不区分读写**，若为落实第 19 节第 3 条的写保护而把 planning 加入此列，`file.read` 会被一并挡死、出口门永久 blocked。planning 的写保护必须用只挡写的独立判据实现。
|
||||
3. **Supervisor 取证必须在 GDD 落盘之后。** 验收节点 passed 要求非 mutation evidence 的 before / after / 当前 revision 三者相同；`.agent/planning/**` 与 `game/fast_gdd.md` 尚未实现，其写入是否推进 project revision属于待定设计而非待查事实，故无论如何定，都以「落盘后取证」为准。
|
||||
|
||||
#### `M0A-3` 门禁与完成定义
|
||||
|
||||
- 批一全部合入，且本文不再存在自相矛盾的表述（同一事实在两处给出不同结论即视为未完成）。
|
||||
- 命名裁决冻结并写入决策记录后，批二全部合入。
|
||||
- decision log 与 pitfalls 同步补记：D6 作废理由、autonomous 下父子皆不可提问且硬闯会瘫痪整条工作流、`M0A-2` owner 验证不可复用。
|
||||
- **仅文档工作包，不含任何代码改动**；合入只表示设计基线恢复自洽，不表示任何功能可用。
|
||||
|
||||
#### `M0A-3` 明确不做
|
||||
|
||||
- 不回退、不修改任何已合入的 M0 代码。
|
||||
- 不删 `design-director`、不动 `design-foundation`、不改 16 任务 DAG——这些论证已成立（`design-director` 不在 owner 产物清单、产物无人读），但属于「做游戏」路径改造，等 GDD 真正被完整构建消费时另开工作包。
|
||||
- 不实现 M1～M3 任何功能。
|
||||
|
||||
## 2. 已锁定决定 D1～D10
|
||||
|
||||
| 编号 | 冻结结论 |
|
||||
| --- | --- |
|
||||
@@ -38,9 +114,11 @@
|
||||
| D3 | 阶段、source、composition、工具、schema、审批命令和 UI 名称按第 3 节注册表冻结。 |
|
||||
| D4 | M1 使用 `.agent/planning/` sidecar，不改 `shared-contracts`；是否把 `approvedGddRef` 提升进 manifest 留给 M2，不能在 M1 临时决定。 |
|
||||
| D5 | game-chat 只在 M3 可选只读消费有效批准 GDD；没有批准 GDD 时继续走现役快车道。 |
|
||||
| D6 | “立项策划 Agent”是 Project Supervisor 通道的第三 persona，以持久 source 区分，复用 `standard` profile，不注册新的 agentCatalog 身份。 |
|
||||
| ~~D6~~ | **2026-08-12 作废**，由 D9 取代。原文：“立项策划 Agent”是 Project Supervisor 通道的第三 persona，以持久 source 区分，复用 `standard` profile，不注册新的 agentCatalog 身份。作废理由见第 1.1 节；其中“复用 `standard` profile”这一结论方向被 D9 继承，但成立理由完全不同。 |
|
||||
| D7 | 本期不实现知识图谱；`basis`、知识 provider trait、composition 槽位可以预留，但 v1 数据必须为 `null`，空字段不渲染。 |
|
||||
| D8 | GDD 不含引擎字段；平台事实固定由 Runtime 注入，Agent 不得向用户提问或修改。 |
|
||||
| D9 | **取代 D6。** 立项策划是独立 `agentId` 的下游工作流节点，由 manifest ready-task 调度器在 Supervisor 下游启动，需登记 agentCatalog；Project Supervisor 以新的可信 source 承载「做方案」入口并保持唯一顶层 root；父子 run profile 必须同为 `standard`——不是为了复用顶层通道，而是因为 `autonomous-game-build` 对 `user.input_request` 的禁令按 profile 生效、父子皆不可提问，且子 Run 不能切换父 Run 的 profile。 |
|
||||
| D10 | 策划节点自身有 parent、不得直接调用 `user.input_request`。问询走「Runtime 直投」：策划节点提交结构化决策字段，Runtime 创建 **owner 为 Project Supervisor** 的 pending，会话消息落 Supervisor 会话、结构化 observation 落策划节点，二者是同一 `AgentRuntimeUserInputRecord` 的两路投影。Supervisor 的 Provider 不参与提问。 |
|
||||
|
||||
## 3. 合同名称注册表
|
||||
|
||||
@@ -1338,7 +1416,7 @@ receipt 永远压过 stale pending：一旦该版本存在有效 receipt，pendi
|
||||
## 19. 安全不变量与构建验证边界
|
||||
|
||||
1. 不放松 `autonomous-game-build` 对 `user.input_request` 的现行禁等待防线；多轮策划只发生在 top-level standard plan run。
|
||||
2. plan source 的 action 工具广告与执行双门都只有四项，MCP 为空，且跳过 Supervisor collaboration 强制委派。
|
||||
2. **（2026-08-12 按 D9 拆写，取代原「plan source 四项工具、跳过 collaboration 强制委派」）** 做方案链路的工具边界分两层：**Supervisor 根 run** 以新可信 source 承载入口，工具面按现役 `standard` deny-list 模型，但其 Provider 不参与向用户提问（问询由 Runtime 直投创建 owner 为 Supervisor 的 pending）；**策划工作流节点**有 parent，其 action 工具广告与执行双门都必须是 exact allowlist，MCP 为空，且**不含 `user.input_request`**（它有 parent，`validate_user_input_action_owner` 会拒），改以提交结构化决策字段的专用工具替代。原表述中的「跳过 Supervisor collaboration 强制委派」被直接反转——策划节点恰恰是被 Supervisor 调度的下游，具体清单待第 1.1 节批二随命名裁决落笔。
|
||||
3. `.agent/planning/**` 与 `game/fast_gdd.md` 唯一写者是 Runtime；任何 Agent 通用写工具都不能触达。
|
||||
4. GDD、receipt 追加不可变；index、session、Markdown 和 UI 只作有限投影，不能反写权威事实。
|
||||
5. approve receipt 是构建信任根；Agent 文本、“已批准”状态缓存、Markdown 徽标或 UI 内存都无批准权。
|
||||
@@ -1443,6 +1521,8 @@ M0 文档 PR 本身最低验证：Markdown 结构与三张 Mermaid 图可解析
|
||||
| planning hydrate command | `apps/ai-game-creator-shell/src-tauri/src/commands.rs:856-875`、`apps/ai-game-creator-shell/src-tauri/src/main.rs:2178-2180`、`apps/ai-game-creator-shell/src/App.tsx:1550,1650,2957,3364,3702` | 新增单一 hydrate command/注册与前端生命周期调用；不把 runtime polling 当 GDD authority |
|
||||
| agent.db | `apps/ai-game-creator-shell/src-tauri/src/project/agent_db.rs:955-1034,1551-1605,1995-2088` | 普通 append 不满足 decision 幂等；新增专用保留入口 |
|
||||
| 16 任务 DAG | `server-rs/crates/shared-contracts/src/game_creation_app.rs:263-425` | 2026-08-12 复核 seed 仍是 16 个，M0/M1 不改拓扑；但固定 DAG 已不是完成语义的唯一来源，见下一行 |
|
||||
| standard 路径 owner 产物验证 | `apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion.rs:416-441` | 2026-08-12 复核：`autonomous_owner_artifact_validation_available_for_run_at` 四重绑死——owner agent 白名单、`profile == autonomous-game-build`、`source == agent-ready-task-scheduler`、**且要求 `parent_agent_id` 为 Project Supervisor**。standard ready-task 节点无 parent，第 436 行即不通过。做方案链路的 owner 产物验证必须**另建物理独立实现**，不能扩展该函数 |
|
||||
| 问询与直投 | `apps/ai-game-creator-shell/src-tauri/src/user_input.rs:367-394,494-530,595-623,803-807`、`apps/ai-game-creator-shell/src/App.tsx` 的 `handleProjectSupervisorUserInput`、`apps/ai-game-creator-shell/src/project/conversation.rs:42` | 2026-08-12 复核：`validate_user_input_action_owner` 拒绝任何带 parent 的 run；会话文件按 `agentId` 分目录，消息归属完全由 pending owner 决定；一份 record 已经两路投影（会话消息 + observation）且有「observation 重算冲突」校验。直投只需让两路投影分别落到 Supervisor 与策划节点，**前端可直接复用现有 Supervisor 问答通道** |
|
||||
| Goal Contract / Acceptance Graph | `apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/goal_contract.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/acceptance_graph.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/tool_policy_snapshot.rs`（`agent_runtime_acceptance_evidence_tools`）、`apps/ai-game-creator-shell/src-tauri/prompts/runtime/supervisor/game-chat-routing.md` | 2026-08-11 合入。可信根 Supervisor 必须先冻结 Goal Contract 才能路由，验收图未确认则完成门 blocked；合同按 `.agent/runtime/goal-contracts/{rootAgent}/{rootRun}.json` 分 root run 存放并绑定 binding fingerprint 与 source SHA-256。M1 见第 23.1 节待裁决项，M2 见第 16.1/16.2 节，M3 见第 17 节 |
|
||||
| design-director 现状 | `apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion.rs:70-85`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/task_start.rs:1480-1506` | mutation owner 清单不含 design-director，因此当前落入只读协调 Prompt；M2 才确定性化 |
|
||||
| scheduler delivery | `apps/ai-game-creator-shell/src-tauri/src/agent/runtime_tools/delivery.rs:171-185` | 下游不能依赖普通 durable delivery，必须读权威文件/ref |
|
||||
@@ -1465,6 +1545,8 @@ M0 文档 PR 本身最低验证：Markdown 结构与三张 Mermaid 图可解析
|
||||
|
||||
M0A-1 是 M1 详细设计与技术 spike 的输入，不是功能交付。M1 可以与 M0-3 并行准备；但 checkpoint handoff 私有持久化决策未冻结前，对应 checkpoint 代码不得合入，M0-3 的 dated 决策、Prompt、source/tool policy 与测试未全部合入前，依赖 Fast GDD source/tool policy 的 M1 代码也不得合入主线。M0-3 采用 Runtime 内部 owner 验证，不为未来 plan source 暴露 command、smoke 或替代验证工具。M0-4 不阻塞 M1/M2，仅阻塞 M3-4 和“M0 全部完成”；不得因为并行关系把工作包标签误报为阶段完成。
|
||||
|
||||
> **⚠️ 以下四方案分析已于 2026-08-12 随 D6 作废，保留仅作推导记录，不再是待裁决项。** 四方案的共同前提是「策划 run 自己就是那个需要豁免的 root `project-supervisor` run」；D9 之后 root 是未变的 Supervisor，策划是独立 `agentId` 的下游节点，四选一问题消解（方案 D 的方向被 D9 实质采纳）。**现行结论见本小节末尾「2026-08-12 替换结论」与第 1.1 节。** 其中方案 C 不可行的论证（验收图强制 required 节点 + evidence 必须命中 18 项工具集）仍然有效，是理解第 1.1 节第 2 条约束的背景。
|
||||
|
||||
2026-08-12 新增第二项 M1 合入前置决策：**plan source 与 Goal Contract 协议的关系**。
|
||||
|
||||
冲突的根源不是某处判据写错，而是两套工具模型不兼容。现行是 **deny-list 模型**：`agent_runtime_tool_policy_snapshot_at` 的 `allowed_tools` 直接等于全量 `agent_runtime_executable_tools()`，`agent.goal_contract` 天然在内，`standard` profile 在 `agent_runtime_tool_policy_snapshot_for_run_at` 里更是提前返回、不做任何裁剪；`provider_request_builders.rs` 只对 `!root_control_authority && goal_contract_participant` 的后代做剔除。因此现役可信 root Supervisor（gui / cli / game-chat）**默认就持有**这个工具，两道门对它们是「照着做」。而 M1 是第一个 **allow-list 模型**的 source（第 4.3 节 exact allowlist），Goal Contract 协议隐含的「root Supervisor 一定持有 `agent.goal_contract`」前提对它不成立。
|
||||
@@ -1487,7 +1569,21 @@ M0A-1 是 M1 详细设计与技术 spike 的输入，不是功能交付。M1 可
|
||||
|
||||
因此真正的分岔不是 allow-list 与 deny-list，而是**策划 run 是否应当是一个 root `project-supervisor` run**：三处判据的唯一共同项是 `agent_id == GAME_CREATOR_PROJECT_SUPERVISOR_AGENT_ID`，方案 D 一次性解耦全部三处且不需要在他人协议里挖豁免，方案 B 需要四处豁免并随消费者增加持续维护。
|
||||
|
||||
裁决冻结前，依赖 plan source 可信身份的 M1 代码不得合入主线；该决策与 checkpoint handoff 私有持久化决策并列，均属 M1 入口前置。此外需一并确认：plan run 是否允许 steer——`steering.rs` 的 steer 门同样只按可信 source 判定，而 steer 替换协议会终止旧根并另起 replacement root run，与第 5.1 节的 session CAS、`roundsUsed` 与 `activeQuestion` 语义存在未验证的交互，第 14 节恢复矩阵目前没有这条路径。
|
||||
（以上为作废的四方案推导记录。）
|
||||
|
||||
#### 2026-08-12 替换结论
|
||||
|
||||
D9 之后，root 是未变的 Project Supervisor，它在 `standard` 下天然持有 `agent.goal_contract`（deny-list 模型，且 `root_control_authority` 为真时不被剥夺），四方案作废。**但入口门仍然适用**——`validate_root_goal_contract_control_plan_at` 无 run profile 判断，standard root Supervisor 同样受约束。因此三条已实测约束取而代之，完整表述见第 1.1 节「Goal Contract：四方案作废，替换为三条已验证约束」：
|
||||
|
||||
1. Supervisor 第一轮必须且只能提交 `agent.goal_contract`；做方案场景可满足。
|
||||
2. 验收 `requiredEvidence` 锚定 `game/fast_gdd.md` 配 `tool:file.read`；`.agent/planning/**` 的写保护必须用只挡写的独立判据，不得加入 `reject_agent_runtime_private_control_path`。
|
||||
3. Supervisor 取证必须在 GDD 落盘之后。
|
||||
|
||||
**仍然保留的 M1 入口前置决策**：
|
||||
|
||||
- **checkpoint handoff 私有持久化**——原有待裁决项，不受拓扑变更影响，继续保留。
|
||||
- **策划节点 `agentId` / source 命名**——新增，是第 1.1 节批二的共同阻塞点；同时需决定 Supervisor 侧新可信 source 是沿用 `project-supervisor-plan-chat` 字符串（历史示例字面不变但语义改变，易接错代码路径）还是取全新常量名（示例需全部重生成）。
|
||||
- **plan run 是否允许 steer**——`steering.rs` 的 steer 门按可信 source 判定，steer 替换协议会终止旧根并另起 replacement root run，与第 5.1 节的 session CAS、`roundsUsed` 与 `activeQuestion` 存在未验证交互，第 14 节恢复矩阵没有这条路径。新拓扑下还要额外确认：Supervisor 被 steer 时其下游策划节点如何收束。
|
||||
|
||||
### 23.2 M0-3：统一 owner 产物验证与可玩验收边界（PR 工作包 `M0A-2`）
|
||||
|
||||
@@ -1503,7 +1599,9 @@ M0A-1 是 M1 详细设计与技术 spike 的输入，不是功能交付。M1 可
|
||||
|
||||
### 23.4 M0 完成状态（2026-08-12）
|
||||
|
||||
**M0 全部完成。** M0-1～M0-4 四个正式任务、对应的 `M0A-1` / `M0A-2` / `M0B-1` / `M0B-2` 四个工作包及各自门禁均已通过，全部落在 M0 集成分支 `feat/five_min_design` 并已推送。
|
||||
> **2026-08-12 修正：M0 代码部分完成，文档部分待修订。** D6 作废后 `M0A-1` 交付的设计基线失效，须以工作包 `M0A-3` 修订（见第 1.1 节）。`M0A-3` 收口前不得再声称「M0 全部完成」。三个代码工作包的完成状态不受影响，无需回退。
|
||||
|
||||
**M0 代码工作包全部完成。** M0-1～M0-4 四个正式任务、对应的 `M0A-1` / `M0A-2` / `M0B-1` / `M0B-2` 四个工作包及各自门禁均已通过，全部落在 M0 集成分支 `feat/five_min_design` 并已推送。
|
||||
|
||||
此处「合入」指合入 M0 集成分支，不是合入 `master`：M0 按整体切片交付，不逐工作包直接进 master，因此不得把「未进 master」当作 M0 未完成。M0 期间该分支已两次合入上游 master（含 `03a441027` 无限画布、`1363b9374` 动态目标验收图、`51e35468a` 自主构建测试锁竞态修复），`origin/master` 已是分支祖先。
|
||||
|
||||
@@ -1524,7 +1622,8 @@ M0 完成不表示任何策划功能已上线。M1 的功能实现仍未开始
|
||||
- 不可变事实只增不改；其它内容都能从事实或 session checkpoint 有界恢复。
|
||||
- approvalRequestId 属于不可变 GDD，approval receipt 的 responseId 属于一次审批决定，两者都不可在重试中漂移；user-input answer/checkpoint 的同名 responseId 属于独立回答幂等域，不能跨域复用或恢复。
|
||||
- decisionFingerprint 解决意图幂等，receiptFingerprint 保护完整信任根。
|
||||
- plan source 无 command/smoke/preview/委派/MCP；内部 Markdown 投影不推进代码 revision。
|
||||
- **（2026-08-12 按 D9 拆写）** 策划工作流节点无 command/smoke/preview/再委派/MCP，其工具面是 exact allowlist 且不含 `user.input_request`；Supervisor 根 run 保持现役 `standard` 工具面并负责调度下游，但其 Provider 不参与向用户提问。内部 Markdown 投影不推进代码 revision。
|
||||
- 用户侧只有一个对话对象；所有呈现给用户的对话内容必须物理存在于 Supervisor 的会话文件中，不得由前端把多个 Agent 的会话拼接成单一视图。
|
||||
- 前端只通过 `hydrate_game_creator_plan_gdd_state` 读取策划权威状态；文件、Markdown 和 runtime polling 不能在页面侧合成批准事实。
|
||||
- 完整构建只认后端在项目锁内重算并冻结的 approvedGddRef；直接开建必须显式声明，不能由缺字段降级。根 Run 被 steer 替换时，replacement root run 必须重新冻结同一 ref，不换稿、不降级、不留空窗。
|
||||
- 已批准 GDD 只能作为上下文进入 Supervisor 的目标理解，不能被 Runtime 直接物化成 Goal Contract；GDD 身份也不是 Acceptance Graph 的合法证据取值。
|
||||
|
||||
Reference in New Issue
Block a user