diff --git a/docs/technical/【技术方案】立项策划Agent(Fast GDD)-2026-08-10.md b/docs/technical/【技术方案】立项策划Agent(Fast GDD)-2026-08-10.md index 59394dc5c..0df9da4f3 100644 --- a/docs/technical/【技术方案】立项策划Agent(Fast GDD)-2026-08-10.md +++ b/docs/technical/【技术方案】立项策划Agent(Fast GDD)-2026-08-10.md @@ -150,15 +150,16 @@ WP1 定稿的澄清轮次/返工深度语义(供 D11 依赖,权威定义见 | --- | --- | | UI 阶段名 | `立项策划` | | 英文称呼 | `plan phase` | -| 工作流节点名 | `立项策划 Agent`(2026-08-12:不再是 persona,见 D9) | +| 策划 Agent 称呼 | `立项策划 Agent`(2026-08-12 起不再是 persona;2026-08-13 起也不再是「工作流节点」,改为 Supervisor 的静态委派子 Agent,见 D11) | | **策划节点 agentId** | `project-planning`(登记 agentCatalog;`project-` 前缀标明项目级、不属任何专业组,故不与 design 组的 `design-director` / `design-foundation` 混淆;登记机制定稿见第 3.1 节,本轮只冻结机制、代码留给 M1) | -| **策划节点 durable source** | `agent-ready-task-scheduler`(复用现役 standard ready-task 调度器,不新增 source) | +| **策划子 Agent durable source** | `agent-delegate`(**2026-08-13 按 D11 取代原值 `agent-ready-task-scheduler`**。字面量见 `apps/ai-game-creator-shell/src-tauri/src/agent/runtime_tools/delegation.rs:1063`;不新增 source,复用现役静态委派族。该 source 同时是 `validate_user_input_action_owner` 拒绝直接提问的判据之一,见第 19 节第 2 条) | | **Supervisor 入口 durable source** | `project-supervisor-plan`(与 `-gui` / `-cli` / `-game-chat` 同族;2026-08-12 取代原预留值 `project-supervisor-plan-chat`,**旧字符串作废不得沿用**,避免字面未变而语义已改导致接错代码路径) | | Rust source 常量 | `AGENT_RUNTIME_SUPERVISOR_PLAN_SOURCE` | -| run profile | `standard`(Supervisor 根 run 与策划节点必须同为此值,见 D9) | -| Prompt composition | 策划节点 `projectPlanning`;Supervisor 入口沿用现役 supervisor composition(其 Provider 不参与提问,无需专用 persona 稿) | +| run profile | `standard`(Supervisor 根 run 与策划子 Agent 必须同为此值。**2026-08-13 按 D11 更正成立理由**:不是 ready-task 调度的约定,而是委派通用的父子继承——`bind_game_creator_agent_runtime_run_profile_at` 强制子 Run 等于父 Run 已绑定的 profile,「子 Run 不能切换父 Run 的 Run Profile」) | +| Prompt composition | **不新增**。策划子 Agent 复用现役 `runtime` composition(委派/孤立子 Agent 通用模板),Supervisor 入口沿用现役 supervisor composition。**2026-08-13 按 D11 取代原冻结值 `projectPlanning`**:`manifest.json` 的 `compositions` 只有 `runtime`/`supervisor`/`supervisorChat` 三个固定字段,校验不遍历 `agentCatalog`,新增子 Agent 不需要也不能配第四套(依据见第 3.1 节) | | Prompt source kind | `ProjectPlanning` | -| 原生 action tool | `plan.submit_gdd`、`plan.request_decision`(后者为 2026-08-12 新增:策划节点提交结构化决策字段,替代它不可能拥有的 `user.input_request`,见 D10) | +| 原生 action tool | `plan.submit_gdd`。**2026-08-13 按 D11 删除 `plan.request_decision`**:该工具是 D10「Runtime 直投」的配套,其存在的唯一理由是「standard ready-task 节点无 parent、Runtime 拦不住直接提问,只能另造工具绕开」;D11 下策划 Agent 是委派子 Agent、天然带 parent,问询改走 `AGC_NEEDS_USER_INPUT_V1` 终态信封 + Supervisor 中转,该工具连同 D10 一并作废,从未实现,全仓库零命中 | +| 问询载体 | `AGC_NEEDS_USER_INPUT_V1` 终态信封(复用 PR #165 已实现的静态委派澄清中转,非本方案新增合同),单次信封 1~3 题 | | pending kind | `gdd-approval` | | 审批 Tauri command | `decide_game_creator_plan_gdd` | | 审批动作 | `approve \| revise \| reject` | @@ -277,12 +278,13 @@ flowchart TD BUILD["完整构建 Supervisor
source=project-supervisor-gui 或 project-supervisor-cli
profile=autonomous-game-build"] CHAT["game-chat Supervisor
source=project-supervisor-game-chat
profile=autonomous-game-build"] end - U <-->|"唯一对话对象;问答落 Supervisor 会话"| SPLAN - SPLAN -->|"ready-task 调度(standard,无 parent 链接以外的特权)"| PLANNODE["立项策划节点
agentId=project-planning
source=agent-ready-task-scheduler
profile=standard
composition=projectPlanning"] - PLANNODE -->|"plan.request_decision 提交结构化决策字段"| RELAY{{"Runtime 直投
创建 owner=Supervisor 的 pending"}} - RELAY -->|"会话消息投影"| SPLAN - RELAY -->|"observation 投影"| PLANNODE - PLANNODE --> GDD["不可变 GDD + approve receipt"] + U <-->|"唯一对话对象;问答物理落 Supervisor 会话文件"| SPLAN + SPLAN -->|"agent.delegate 静态委派(profile 由父 run 继承)"| PLANAGENT["立项策划子 Agent
agentId=project-planning
source=agent-delegate
profile=standard
composition=runtime(复用)"] + PLANAGENT -->|"以 AGC_NEEDS_USER_INPUT_V1 终态信封退出"| DELIV{{"needs-user-input delivery"}} + DELIV -->|"Supervisor 认领回执"| SPLAN + SPLAN -->|"在自己的 runtime/session 上建 pending,向用户提问"| U + SPLAN -->|"answersSha256 绑回 delivery,再发 continuation 委派
(最多 3 轮,受 clarification_round 上限约束,见第 23.5 节)"| PLANAGENT + PLANAGENT --> GDD["不可变 GDD + approve receipt"] GDD -->|"用户动作:开始完整制作"| BUILD U -.->|"直接开建"| BUILD BUILD --> DAG["现行 16 任务 DAG"] @@ -293,56 +295,83 @@ flowchart TD ### 4.1 source、profile 与 run 身份 -策划 run 必须同时满足: +> **2026-08-13 按 D11 整节重写。** 原文按 D6 persona 模型写成「策划 run 就是 `agentId=project-supervisor` + `source=project-supervisor-plan-chat` 的那一个顶层 run」,D11 下做方案链路是**两个 run**:未变的 Supervisor 顶层 root run,加一个由它静态委派出的策划子 run。凡本节与旧表述冲突处一律以本节为准;已作废的字面量 `project-supervisor-plan-chat` 与 `is_exact_supervisor_plan_run_at` 不得再使用。 + +**第一层:Supervisor 根 run(做方案入口)**必须同时满足: - `agentId=project-supervisor`; -- 顶层 run,`parentAgentId`、`parentRunId` 和 delegation identity 均为空; -- `source=project-supervisor-plan-chat`; +- 顶层 run,`parentAgentId`、`parentRunId` 和 delegation identity 均为空,`rootAgentId=agentId`、`rootRunId=runId`; +- `source=project-supervisor-plan`; - `runProfile=standard`; - source、profile、session、run 与 profile binding fingerprint 已写入现有 durable run configuration,并在恢复、steer、工具执行和审批命令中逐项相等。 -任一字段缺失、漂移或与当前 active plan run 不同都失败关闭。普通 `standard` Supervisor 不能借 persona 名称进入策划工具面,plan source 也不能切换到 `autonomous-game-build`。每个项目同一时刻最多一个非终态 plan run;首次开始策划时,Runtime 在项目锁内生成唯一 `gddId` 并 create-only 创建 session revision 1。第二窗口并发启动返回 typed `PLAN_ACTIVE_RUN_EXISTS`,不得创建第二条 lineage。 +**第二层:策划子 run**必须同时满足: -M1 不能把新 source 直接塞进一个被 autonomous 语义复用的总 matcher。source predicate 必须拆成三种语义:top-level Supervisor trusted matcher 接受 gui/cli/game-chat/plan;autonomous-build trusted matcher仍只接受现役 gui/cli/game-chat;plan binding matcher只接受 top-level `project-supervisor + standard + project-supervisor-plan-chat`。现有 run configuration、completion gate 和恢复调用点逐个改用正确 predicate,确保 `plan + autonomous-game-build` 永远非法。前端已有 `runProfile + source` 提交链只能作为请求;后端必须重新验证,不能信任页面选择。 +- `agentId=project-planning`; +- `parentAgentId=project-supervisor`、`parentRunId` 等于上述根 run 的 `runId`、`delegationId` 非空——这三项由 `agent.delegate` 派发时写入 task link,是 `validate_user_input_action_owner` 拒绝它直接向用户提问的结构性判据; +- `source=agent-delegate`; +- `runProfile=standard`,且**该值不是独立配置的**,而是由父 run 的 profile binding 强制继承(子 Run 不能切换父 Run 的 Run Profile);因此「父子同为 standard」不需要额外的一致性校验去保证,只需要保证父 run 本身是 standard; +- `targetRunId` 由 Runtime 从 `delegationId` 确定性派生,`targetSessionId` 解析为 `project-planning` 的持久 active session——**同一策划链路的多轮 continuation 共享同一条 session**,这是多轮之间不失忆的机制依据(详见第 1.1 节「D11 新拓扑」第 3 条)。 + +任一字段缺失、漂移或与当前 active plan lineage 不同都失败关闭。普通 `standard` Supervisor 不能借 source 名称进入策划工具面,plan source 也不能切换到 `autonomous-game-build`。每个项目同一时刻最多一个非终态 plan lineage;首次开始策划时,Runtime 在项目锁内生成唯一 `gddId` 并 create-only 创建 session revision 1。第二窗口并发启动返回 typed `PLAN_ACTIVE_RUN_EXISTS`,不得创建第二条 lineage。 + +**「同一条策划链路」的判定不能只看子 run 的 `agentId`。** 委派子 run 的身份权威是 `(parentAgentId, parentRunId, delegationId)` 三元组加上 delivery 记录本身;多轮 continuation 每轮都是新的 `delegationId` 与新的 `targetRunId`,靠 `repair_of_delegation_id` 串成链。判定「这是不是当前策划链路的一环」必须沿该链上溯到根 delegation 并核对根 delegation 的 `parentRunId` 等于当前 plan 根 run,不得用「`agentId=project-planning` 即认为属于本链路」这种弱判据——否则跨 run 的旧策划残留会被误纳入当前轮。 + +M1 不能把新 source 直接塞进一个被 autonomous 语义复用的总 matcher。source predicate 必须拆成三种语义:top-level Supervisor trusted matcher 接受 gui/cli/game-chat/plan;autonomous-build trusted matcher仍只接受现役 gui/cli/game-chat;plan binding matcher只接受 top-level `project-supervisor + standard + project-supervisor-plan`。现有 run configuration、completion gate 和恢复调用点逐个改用正确 predicate,确保 `plan + autonomous-game-build` 永远非法。前端已有 `runProfile + source` 提交链只能作为请求;后端必须重新验证,不能信任页面选择。 2026-08-12 复核:上述三分法在 2026-08-11 动态目标验收图合入后**已不足**。原文把 plan 归入「top-level Supervisor trusted matcher」,而该 matcher(`agent_runtime_supervisor_source_is_trusted`)如今同时是 Goal Contract 创建权限、根控制面工具授权与验收图完成门的判据,plan 一进入即被当作 Goal Contract 参与者。至少需要第四种语义「Goal Contract 参与者」,且它与 top-level trusted 的关系必须显式冻结,不能靠默认相等。此外 Goal Contract 的入口门只按 `agentId=project-supervisor` + root binding 判定,与 source predicate 无关,因此拆 matcher 本身解决不了它。完整处置见第 23.1 节待裁决项;该裁决可能反过来影响本节已冻结的 `agentId=project-supervisor`(方案 D)。 -所有 plan 例外必须共用单一 `is_exact_supervisor_plan_run_at(root, agentId, runId)`:只有 durable run-profile binding 已通过 project/fingerprint 校验,且 `agentId=project-supervisor`、`source=project-supervisor-plan-chat`、`profile=standard`、parent/delegation 均为空、`rootAgentId=agentId`、`rootRunId=runId`,并与 task/runtime 以及存在时的 planning pending、尚存 batch 的 source/profile/binding fingerprint 逐项相等时才返回 true。缺失必需 binding、损坏或漂移不得获得 plan 例外,不能只比较内存中的 `runtime.source`。 +**(2026-08-13 按 D11 改写)** 所有针对 **Supervisor 根 run** 的 plan 例外必须共用单一判据函数(原名 `is_exact_supervisor_plan_run_at` 连同其 `project-supervisor-plan-chat` 取值一并作废,M1 落地时取新名):只有 durable run-profile binding 已通过 project/fingerprint 校验,且 `agentId=project-supervisor`、`source=project-supervisor-plan`、`profile=standard`、parent/delegation 均为空、`rootAgentId=agentId`、`rootRunId=runId`,并与 task/runtime 以及存在时的 planning pending、尚存 batch 的 source/profile/binding fingerprint 逐项相等时才返回 true。缺失必需 binding、损坏或漂移不得获得 plan 例外,不能只比较内存中的 `runtime.source`。 -普通 standard retry 当前会改写为通用 background source。M1 必须在 generic standard fallback 前增加 exact plan root 分支,但不扩大现役 retry 的破坏面:只有 Provider 故障的旧 plan task 已由现有生命周期收束为终态、没有 provider/action/planning pending ledger,且原 task 与已验证 root binding 逐项相等、无 parent/delegation 时,retry 才以同一 gddId/session 创建新 run,继续使用 `project-supervisor-plan-chat + standard`,并在项目锁内写 session revision+1 successor;不得由 retry helper 主动终结 running/waiting run,不得新建 gddId,也不得降级为 `agent-background-task`。任一身份校验失败直接拒绝 retry。已经进入 `gdd-approval` 等待的 run 禁止走 generic retry,只能恢复并续跑 receipt 所绑定的精确原 run。 +**策划子 run 不共用上述判据**,它的合法性由第二层身份条件加委派 delivery 链决定(见本节前述)。不得把子 run 也塞进同一个函数——那会要求该函数同时接受「parent 为空」和「parent 非空」两种互斥形态,判据随即失去意义。 + +普通 standard retry 当前会改写为通用 background source。M1 必须在 generic standard fallback 前增加 exact plan root 分支,但不扩大现役 retry 的破坏面:只有 Provider 故障的旧 plan 根 task 已由现有生命周期收束为终态、没有 provider/action/planning pending ledger,且原 task 与已验证 root binding 逐项相等、无 parent/delegation 时,retry 才以同一 gddId/session 创建新 run,继续使用 `project-supervisor-plan + standard`,并在项目锁内写 session revision+1 successor;不得由 retry helper 主动终结 running/waiting run,不得新建 gddId,也不得降级为 `agent-background-task`。任一身份校验失败直接拒绝 retry。已经进入 `gdd-approval` 等待的 run 禁止走 generic retry,只能恢复并续跑 receipt 所绑定的精确原 run。 + +**策划子 run 的失败恢复不走上述根 run retry 路径。** 它是静态委派子 Agent,其失败按现役委派回执语义收束:子 run 终态形成 delivery,由 Supervisor 认领后决定是发质量返工还是终止本轮策划。这里必须注意 `WP1` 定稿的预算语义(见第 23.5 节)——**澄清与质量返工是两个独立维度**,`repair_depth` 上限仍是 1,因此一条策划链路最多只有一次质量返工机会;把它耗在可以靠 continuation 解决的问题上,后续真出现交付质量问题时就没有额度了。M1 的 Supervisor Prompt 须显式区分这两种情形。 ### 4.2 Prompt 分流 -`supervisorPlanChat` 是独立 composition,不是 autonomous role overlay: +> **2026-08-13 按 D11 整节重写。** 原文的前提是「策划是 Supervisor 的第三套 persona,因此需要一套独立 composition `supervisorPlanChat`」。D11 下策划是独立 `agentId` 的委派子 Agent,两侧各自沿用现役 composition,**不新增第四套**;`supervisorPlanChat` / `SupervisorPlanChat` 两个字面量随 D6 一并作废,不得再出现在实现或文档中。 -1. Provider 请求的 system composition 按 durable root source 选择。 -2. tool-plan 请求和 final-reply 请求都必须选择 `supervisorPlanChat`,不能只有首轮生效、收尾又回到通用 `supervisorChat`。 -3. `SupervisorPlanChat` 是 Prompt Bundle 的编译期 source kind;不进入 agentCatalog,也不改变 seed manifest 的 Agent 列表。 -4. 现有 role overlay 仍只服务 autonomous 路径。plan standard run 不伪装成 game-chat overlay,也不注入知识图谱 overlay。 +1. **Supervisor 根 run** 沿用现役 supervisor composition。做方案入口不需要专用 persona 稿:它的 Provider 不生成策划内容,只做委派、认领回执、代为提问与审批收束;这些能力现役 supervisor composition 已经具备。差异化只体现在 Prompt 的任务描述与工具面上,不体现在 composition 选择上。 +2. **策划子 Agent** 复用现役 `runtime` composition(委派/孤立子 Agent 通用模板)。其角色专属内容由 agentCatalog 条目的 brief 承载,而不是由 composition 承载——这与所有专业 Agent 的组织方式一致,见第 3.1 节。 +3. 因此本方案**不新增 Prompt Bundle 的编译期 source kind**。原 `SourceKind::SupervisorPlanChat` 不再需要。 +4. 现有 role overlay 仍只服务 autonomous 路径。策划链路的两个 run 都不伪装成 game-chat overlay,也不注入知识图谱 overlay。 +5. 策划子 Agent 的每一轮 continuation 都是**新 run、同 session**,其 Provider 请求的历史来自该 session 的既有对话,不需要也不应该由 Prompt 层去拼接「前几轮问答」。需要显式传递的只有用户的**答案**——它物理落在 Supervisor 会话文件而非子 Agent 会话文件,只能由 Supervisor 写进新一轮委派的 task 文本;该转述的保真依赖 Supervisor 侧 Provider,Runtime 只校验 `questionsSha256` / `answersSha256` 的哈希绑定,不校验转述语义(残留风险,见第 1.1 节「D11 新拓扑」第 3 条)。 -### 4.3 四个 action tool 与两项协议控制函数 +### 4.3 两层工具面与两项协议控制函数 -plan source 对 Provider 可见且执行可通过的 action tool 恰好是: +> **2026-08-13 按 D11 整节重写。** 原文假设做方案链路只有一层「plan source」,因此把工具清单、`agent.delegate` 禁令和 collaboration 冻结全写成同一层的属性。D11 下是两层,且**两层的结论在若干条上正好相反**——尤其 `agent.delegate`:策划子 Agent 禁止,Supervisor 根 run 恰恰必须使用。凡与本节冲突的旧表述一律作废。 + +**第一层:Supervisor 根 run(`source=project-supervisor-plan`)** + +工具面按现役 `standard` deny-list 模型,不改为 allow-list。它需要且必须持有:`agent.delegate`(发起与续跑策划委派,这是做方案链路的主动作)、`user.input_request`(代策划子 Agent 向用户提问)、以及现役 standard Supervisor 既有的读取与审批相关能力。 + +关键约束不是「不许持有」,而是「持有但不得这样用」:**其 Provider 不得自行发起策划性提问**。`user.input_request` 的合法用法只有一种——认领策划子 Agent 的 `AGC_NEEDS_USER_INPUT_V1` 终态信封后代为创建 pending,且问题正文必须与信封逐字一致(由 `static_delegate_clarification_pending_matches_delivery_at` 做结构相等 + `questionsSha256` 双重校验,Supervisor 改不了子 Agent 的问题原文)。这一条靠机制保证,不靠 Prompt 劝阻。 + +**第二层:策划子 Agent(`agentId=project-planning`,`source=agent-delegate`)** + +action 工具广告与执行双门都必须是 exact allowlist,MCP catalog 为空,`webSearchEnabled` 固定为 false。允许项恰好是: - `file.read` - `file.list` -- `user.input_request` - `plan.submit_gdd` -> **2026-08-13 按 D11 更正,避免与第 19 节第 2 条矛盾**:以上四工具清单是 D6/D9 时代「单一 plan source 自己直接持有 `user.input_request`」旧模型下的表述,本节其余段落仍待第 1.1 节批二随 `build.rs` 一致性裁决整体重写,但这一条必须先更正,不能放任两节结论互相冲突:**D11 现行拓扑下 `user.input_request` 不在策划子 Agent(`agentId=project-planning`)的工具面里**,也不依赖 exact allowlist 主动排除——委派子 Agent 天然带 `parent_agent_id`/`parent_run_id`,该调用被执行层 `validate_user_input_action_owner`(`user_input.rs:367-394`)直接兜底拒绝(广告层仍可见,模型会调但必失败,见第 19 节第 2 条)。Supervisor 根 run(新可信 source `project-supervisor-plan`)继续持有 `user.input_request`,但其 Provider 不用它直接向用户提问,而是在认领策划子 Agent 的 `AGC_NEEDS_USER_INPUT_V1` 终态信封后代为创建 pending。四工具清单中 `file.read`/`file.list`/`plan.submit_gdd` 三项,以及本节 exact allowlist、MCP 为空、collaboration 六类入口冻结等结构性约束方向不受此更正影响,具体归属哪一层(Supervisor 根 run 还是策划子 Agent)随第 1.1 节批二重写。 - -`update_agent_plan` 与 `respond_to_user` 是 Runtime 协议控制函数,不计入“四个 action tool”,但仍受现有结构、轮次和终态门禁约束。plan source 的 MCP catalog 必须为空,Provider request 的 `webSearchEnabled` 固定为 false;广告层不得暴露其它 native action、内建搜索或 MCP,也不得只靠 Prompt 劝阻。执行 policy 必须按同一 durable source 再做 exact allowlist,伪造 tool call 一律拒绝。 +`update_agent_plan` 与 `respond_to_user` 是 Runtime 协议控制函数,不计入上述清单,但仍受现有结构、轮次和终态门禁约束。 明确禁止:通用写入、patch/delete、command、process、preview、canvas、asset generation、确认型副作用、`agent.delegate`、`agent.route_manifest`、isolated child、任务图调度和所有 MCP 工具。 -项目级 collaboration policy 对所有 Supervisor 的现有预检不能应用到 exact plan run。六类入口冻结如下,非 plan Supervisor 行为保持不变: +`user.input_request` **不在允许清单内**,但要如实记录它的排除性质:这不是 exact allowlist 独力保证的——委派子 Agent 天然带 `parent_agent_id`/`parent_run_id`,该调用被执行层 `validate_user_input_action_owner`(`apps/ai-game-creator-shell/src-tauri/src/user_input.rs:367-394`)兜底拒绝;**广告层仍会把它列进函数目录**,模型看得见、会去调,只是调用必失败并转成一次失败的 tool observation。allowlist 的作用是让它在广告层就消失、避免模型浪费轮次,兜底则由 Runtime 提供。两者都要有,不可互相替代(见第 19 节第 2 条)。 -1. Provider request/context 不读取或渲染 collaboration policy,`collaborationPolicy` 固定为 not-applicable;MCP catalog 在构建请求前即为空,只渲染四 action tool 与两项 control function,不拼接 delegate、MCP、command 或 canvas 示例。 -2. tool-plan 不读取 collaboration policy/state、不做 preflight,`force_supervisor_initial_collaboration=false`;不进入 collaboration liveness/repair,不重新广告全量能力或注入 delegate repair。plan 输出非法协作 action 时由 exact allowlist 直接拒绝。 -3. action batch preparation 的 collaboration policy/state/contract 固定为空,跳过 collaboration/MCP orchestrator 逻辑;plan batch 若持久化了非空 `collaborationContract`,视为身份污染并进入 reconciliation。 -4. provider batch validate/write/recovery 对 exact plan 同样不解析、绑定或从 batch 恢复 collaboration snapshot;只有先验证 exact identity 且 `collaborationContract=null` 才能读取 plan batch。 -5. collaboration completion blocker 在读取项目 policy 前对已验证 exact plan 返回 not-applicable;身份验证错误不能吞掉为例外。plan 改由专用 GDD completion blocker检查提问/审批等待、receipt、observation、session 与 recovery 状态。 -6. prompt context、batch ledger 或 final-reply 任一调用点都不得另写宽松 source 字符串判断;全部调用第 4.1 节统一谓词,防止某一恢复入口重新强制 `agent.delegate`。 +**collaboration policy 的处置(原「六类入口冻结」按 D11 修订)** + +原文的核心主张是「plan run 跳过 Supervisor 的 collaboration 强制委派」。该主张在 D11 下**方向反转**:策划子 Agent 恰恰是被 Supervisor 委派的下游,强制委派不再是需要绕开的东西,而是链路本身。修订如下: + +1. **Supervisor 根 run**:不再要求跳过 collaboration 预检,但项目级 collaboration policy 不得把做方案链路当成 16 任务 DAG 的协作场景来编排——它只应产生一条指向 `project-planning` 的委派,不得注入专业组 delegate 示例、MCP 或 canvas 能力。具体是「按 source 收窄现役 policy」还是「为 plan source 单列一份最小 policy」,属 M1 详细设计。 +2. **策划子 Agent**:collaboration policy 完全不适用,`collaborationPolicy` 固定为 not-applicable;Provider request/context 不读取或渲染它,MCP catalog 在构建请求前即为空。 +3. 策划子 Agent 的 action batch 若持久化了非空 `collaborationContract`,视为身份污染并进入 reconciliation;batch validate/write/recovery 只有先验证身份且 `collaborationContract=null` 才能读取。 +4. 完成门:策划链路改由专用 GDD completion blocker 检查提问/审批等待、receipt、observation、session 与 recovery 状态;现役 collaboration completion blocker 对策划子 Agent 返回 not-applicable,身份验证错误不能被吞成例外。 +5. prompt context、batch ledger 或 final-reply 任一调用点都不得另写宽松 source 字符串判断,全部调用第 4.1 节的统一谓词(根 run 与子 run 各一套,不可混用)。 ### 4.4 平台事实 @@ -367,10 +396,15 @@ Runtime 注入并强校验以下精确结构: - 建议顺序:核心行为与本局目标 → 重玩动力 → 制作边界与 MVP。 - 满足任一条件即出稿:用户明确说“直接出稿”;已经完成第 3 轮;剩余问题不影响首个可玩闭环;Runtime 注入 240 秒 Agent 活跃时间软提示。 - `accumulatedAgentMillis` 只累计 Provider 活跃区间,不包含等待用户、等待审批、进程休眠或应用关闭时间。 -- 提问 Provider turn 只产生一条 strict `user.input_request`。Runtime 先把完整问题、请求/action/Provider identity 和问题哈希 checkpoint 到 session.activeQuestion,之后才允许决策卡对用户可见。 -- 用户回答先只进入现役 user-input sidecar 的 `answer-prepared`;Runtime 随后在同一 run 发起专用 `plan-decision-checkpoint` Provider turn,让 Agent 基于原问题和完整回答形成设计解释。checkpoint 成功响应 durable 后,Runtime 才以 session CAS 写入决定、原型验证项和 applied-answer identity。 -- 新 session primary 是“该轮 Agent 已解释用户回答”的线性化点。越过该点后才允许把 sidecar 标成 `answered`、发布原 `user.input_request` terminal observation 并结束该 action;页面重载、Runner 重启或同 run continuation 不能把一条回答计为两轮。 -- 下一题或 `plan.submit_gdd` 必须由新 session primary 上的第二个普通 tool-plan Provider 请求产生。不得让同一个 Provider response 一边绑定旧 session 解释回答,一边在尚未提交的新 session 上执行下一 action。 +> **2026-08-13 按 D11 重写以下四条。** 原文描述的是 D10「Runtime 直投」状态机:策划节点持续存活于同一 run,用 `plan.request_decision` 提交决策字段,Runtime 直投出 pending,回答后再在**同一 run** 内发起专用 `plan-decision-checkpoint` Provider turn,并以新 session primary 作为线性化点。D11 下这套整个不成立——策划子 Agent 不能调 `user.input_request`,且它是**以终态信封退出**来提问的,该 run 随即结束,不存在「同一 run 内的第二个 turn」。D11 用已发布并有回归覆盖的 PR #165 中转链路替换了这台自造状态机。 + +- **提问**:策划子 Agent 以 `AGC_NEEDS_USER_INPUT_V1` 终态信封退出本轮 run,信封含 1~3 题的结构化问题。Runtime 据此形成 `contract_status=NeedsUserInput` 的 delivery,问题原文与 `questionsSha256` 一并落在 delivery 里——**delivery 就是「已问出、未回答」这一状态的权威载体**,不再需要 session.activeQuestion 承担该职责。 +- **提问对用户可见**:Supervisor 认领该 delivery 后,在自己的 runtime/session 上创建 `waiting-for-user-input` pending。问题正文必须与信封逐字一致,由 `static_delegate_clarification_pending_matches_delivery_at` 做结构相等加 `questionsSha256` 双重校验;Supervisor 改不了子 Agent 的问题原文。 +- **回答与线性化点**:用户在 Supervisor 会话内作答,`requestId` 与 `answersSha256` 原子绑回原 delivery。**该绑定就是本轮的线性化点**,取代原「新 session primary」——它由已发布代码保证「首次写入或逐字相同则幂等,绑到不同请求或不同答案则拒绝」,页面重载、Runner 重启或重放都不会把一条回答计成两轮。 +- **解释与下一步**:Supervisor 随后发起 continuation 委派,Runtime 从 `(parent_run_id, 原 delegationId, questionsSha256, answersSha256)` 确定性派生新的 delegation 身份——**同一组问答只能派生同一个 continuation,重放天然幂等**。新一轮子 Agent 是**新 run、同 session**,它在自己的第一个普通 tool-plan turn 里既完成对上一轮回答的设计解释,也决定下一题或 `plan.submit_gdd`。因此不再需要独立的 `plan-decision-checkpoint` 请求 kind:原本要靠它保证的「解释与下一动作不能挤在同一个 Provider response 里」,在 D11 下由「上一轮 run 已终态、下一轮是全新 run」这一结构性事实免费保证。 +- **轮次计数与上限**:本轮是第几轮由委派链上的 `clarification_round` 派生值决定(沿 `repair_of_delegation_id` 上溯推断,见第 23.5 节),上限 3;不再由 session 自行累加 `roundsUsed`。session 仍是 decisions 数组与 GDD 草稿内容的权威,但**不再是轮次状态机的权威**。 + +> **随之而来的合同影响(M1 落地前必须收口,本轮只登记不展开)**:第 3 节注册表中的 `plan-decision-checkpoint.v1`、plan Provider request kinds 里的 `plan-decision-checkpoint`、以及为承载 checkpoint 而引入的 lifecycle `v3` / batch `v4` 增量字段,其存在理由均随本节重写而消失;第 8.6 节 `plan-session.v1` 的 `activeQuestion` 与 `roundsUsed` 字段、第 14 节与 activeQuestion 相关的恢复语义同理。这些是本次重写的**必然推论**,不是新的设计选择,但涉及多份 strict schema 与 golden vector,须作为一个独立小工作包统一改,避免边改边漏。 - 用户明确输入优先于 Agent 默认;默认建议必须标为 `default_pending`,手感、节奏、镜头、可读性或重玩差异等需要验证的结论标为 `prototype_pending`。 - session revision 1 由 Runtime 先写入固定 `initial-request` 决定:topic=`初始需求`、state=`confirmed`、answerSource=`user_freeform`、round=0、answerSummary 精确等于规范化后的 1~400 scalar 初始用户需求。Provider 不能改写或省略这条来源记录;超过上限的初始输入先要求用户收束,不能截断。 @@ -415,6 +449,14 @@ exact plan source 的 `user.input_request` 仍是四个 action tool 之一,不 三个 option 的标签与顺序必须逐字等于上表;plan question ID 在现役 snake_case 规则上进一步限制为最多 32 个 ASCII 字符,并且不能映射成 `initial-request`。Runtime 确定性令 `decisionId = questionId.replace('_', '-')`,因此该 ID 必然满足第 8.3 节 GDD decision ID 合同,Provider 不能另选身份。Provider batch 仍须满足 `user.input_request` sole-action 规则;exact plan 的普通 tool-plan 只要产生 action,即使仅一项也必须强制 durable 写 v4 batch,不能走现役“少于两项则 NotNeeded”的优化。`user.input_request` 与 `plan.submit_gdd` 因此都有唯一 v4 member;decision-checkpoint/final-reply 无 action 才不创建 batch。非 plan source 的 input wire、数量和校验保持现状,任何额外 plan metadata 都因 unknown field 失败。 +> **2026-08-13 D11 作废横幅:本节以下段落至第 5.2 节末,连同第 8.6 节 `activeQuestion`/`roundsUsed`、第 9.1 节 golden vector、第 12 节、第 13 节、第 14 节中依赖 `plan-decision-checkpoint` 的部分,整体待改。** +> +> 这些内容描述的是 D10「Runtime 直投」状态机——策划节点持续存活、`user.input_request` 由它自己产生、Runtime 在同一 run 内截获并写 `activeQuestion` session checkpoint、回答后再发 `plan-decision-checkpoint` Provider 请求。D11 下这条链路的每一环都换了承载物:问题落在 delivery 而非 `activeQuestion`,线性化点是 delivery 的答案绑定而非新 session primary,「解释 + 下一步」由 continuation 子 Agent 的第一个普通 turn 完成而非专用请求 kind(依据见第 5.1 节重写后的四条)。 +> +> **未在本轮直接改写的原因,是它们与 golden vector 强耦合**:第 8.3~8.6 节的 golden JSON 示例、第 9.1 节的 typed 指纹(现值 `d85c85dae3…`)与第 12/13 节的 wire 版本(lifecycle `v3` / batch `v4` 的增量字段专为 checkpoint 而设)必须**一次性一起改**,且指纹必须由代码重新生成、不得手写。逐段修补会产生「schema 已改、vector 未换」的中间态,比暂时保留旧文更危险。 +> +> 处置:作为一个独立小工作包统一收口,前置是 M1 的 strict schema 实现(届时才有能生成指纹的代码)。在该工作包完成前,本横幅以下内容**只作为 D10 时代的历史记录**,不得作为实现依据;凡与第 4.1 / 4.2 / 4.3 / 5.1 节冲突处,一律以那四节为准。 + Runtime 在普通 user-input dispatch 前截获 exact plan:先用 v4 batch 中的 durable provider/session/action binding 校验问题,再创建稳定 request sidecar;随后在项目锁内写 session successor,把完整规范化 question、`questionsSha256`、request/action/provider 身份和 round 放进 `activeQuestion`。只有该 session primary durable 后才能发布等待态和决策卡。batch 已有而 activeQuestion session checkpoint 未落时分两种:① current session 仍精确等于 binding,只允许 user-input sidecar 不存在,或已经是与 v4 batch/request identity 逐项相等的 pending 记录;恢复重放同一 action,缺 sidecar 时确定性创建同一 request,已有 exact pending 时直接复用并安装 activeQuestion。② current session 已是 binding 的合法 successor,且 activeQuestion、standalone pending、决策卡和 answer-prepared 均未形成,则旧问题尚未被业务消费;sidecar 只允许 absent/exact pending,Runtime 按第 12 节 stale 顺序先补 lifecycle completed、持锁把旧 batch 标为 superseded 并回读,再删除 exact pending sidecar并确认其 durable absent,最后清理旧 batch,之后才可按 successor 新 base 请求新问题。任一断点只重放同一清理步骤,不得展示或重发旧问题。sidecar 为 answer-prepared/answered/cancelled、内容/hash 冲突、存在 standalone pending/card,或 session 漂移不能证明为合法 successor 时进入 reconciliation;不得生成新的 question/request/decision ID 或把旧问题绑定到新 session。 回答提交沿用现役 `requestId + responseId + answers` transport。规范化答案精确等于三个固定 label 之一时按上表识别为 option;其它值一律是自由填写,不能由 UI 另传一个未持久化的“答案类型”布尔值。plan 回答额外限制为 1~400 scalar,不得截断。exact plan 先把 sidecar写到可恢复的 `answer-prepared`,不能先发布 terminal observation,也不能直接把用户原文或预设 option description 当作 Agent 解释写入 session。 @@ -838,6 +880,8 @@ entries 必须从 1 连续递增,文件名与 version 精确一致,且逐项 ### 8.6 `plan-session.v1` +> **2026-08-13:本节含依赖 `plan-decision-checkpoint` / `activeQuestion` 的 D10 时代内容,与 golden vector 强耦合,整体待改。处置与理由见第 5.2 节「D11 作废横幅」;凡与第 4.1 / 4.2 / 4.3 / 5.1 节冲突处以那四节为准。** + ```jsonc { "schemaVersion": "plan-session.v1", @@ -933,6 +977,8 @@ exact plan 的 base Provider request ID 不复用现役换行拼接算法,也 ### 9.1 GDD golden vector +> **2026-08-13:本节含依赖 `plan-decision-checkpoint` / `activeQuestion` 的 D10 时代内容,与 golden vector 强耦合,整体待改。处置与理由见第 5.2 节「D11 作废横幅」;凡与第 4.1 / 4.2 / 4.3 / 5.1 节冲突处以那四节为准。** + 以下一行是完整 `FingerprintEnvelope` canonical value;外层存储字段 `fingerprint` 不在 value 中。数组顺序、中文、`null`、空数组、Runtime 注入的 session binding、initial request 和 prototype pass criterion 均为受保护字节。精确 UTF-8 bytes 无 BOM、无结尾换行,共 3707 bytes: ```json @@ -997,6 +1043,8 @@ flowchart LR ## 12. GDD 提交合同 +> **2026-08-13:本节含依赖 `plan-decision-checkpoint` / `activeQuestion` 的 D10 时代内容,与 golden vector 强耦合,整体待改。处置与理由见第 5.2 节「D11 作废横幅」;凡与第 4.1 / 4.2 / 4.3 / 5.1 节冲突处以那四节为准。** + `plan.submit_gdd` 由 Agent 调用,但只有 Runtime 写文件。它必须是一次 Provider 响应中的唯一 action tool;同一响应可以更新 `update_agent_plan`,但不得把 submit 与 `file.read`、`file.list`、`user.input_request` 或第二次 submit 混入同一 action batch。Runtime 在 batch 建立 durable actionId 之前拒绝混批,避免审批等待落在 generic multi-action cursor 中间。 产生 submit 的 Provider request 必须先冻结 durable source-session binding,不能只放在内存: @@ -1096,6 +1144,8 @@ type PlanSubmitGddResult = { ## 13. 审批 pending、提交点与幂等 +> **2026-08-13:本节含依赖 `plan-decision-checkpoint` / `activeQuestion` 的 D10 时代内容,与 golden vector 强耦合,整体待改。处置与理由见第 5.2 节「D11 作废横幅」;凡与第 4.1 / 4.2 / 4.3 / 5.1 节冲突处以那四节为准。** + ### 13.1 `gdd-approval` pending M1 新增独立 `.agent/planning/pending.json`,不升级、不迁移、不重写现役全局 `game-creator-pending-action.v5`,也不能把普通 `user.input_request` 或 confirmation pending 改名冒充审批。独立文件使用 `plan-gdd-approval-pending.v1` strict schema: @@ -1251,6 +1301,8 @@ type PlanGddDecisionResult = { ## 14. 恢复与兼容矩阵 +> **2026-08-13:本节含依赖 `plan-decision-checkpoint` / `activeQuestion` 的 D10 时代内容,与 golden vector 强耦合,整体待改。处置与理由见第 5.2 节「D11 作废横幅」;凡与第 4.1 / 4.2 / 4.3 / 5.1 节冲突处以那四节为准。** + 恢复顺序固定为:路径/普通文件/大小/schema → project/source/profile/run identity → GDD 连续性与 typed fingerprint → receipt 引用、decisionFingerprint 与 receiptFingerprint → 状态推导 → index/Markdown → pending → audit/observation/session。权威事实冲突时停止 mutation;只有缺失或落后的投影允许自动修复。 | 磁盘或运行状态 | 冻结行为 | @@ -1394,7 +1446,7 @@ game-chat 不强制先策划、不改变单主结构。项目存在有效 approv ### 18.1 入口 -- 新项目目标态默认提交 `standard + project-supervisor-plan-chat`;创建界面保留明确的“直接开建”。 +- 新项目目标态默认提交 `standard + project-supervisor-plan`(2026-08-13 按 D11 更正,旧值 `project-supervisor-plan-chat` 作废);创建界面保留明确的“直接开建”。前端只提交 Supervisor 根 run 的身份,**不提交也不感知策划子 Agent**——后者由 Supervisor 在服务端通过 `agent.delegate` 派生,页面侧不得直接创建或引用它。 - 已有项目可从项目开发页进入“立项策划”或继续现行构建;一个项目同时最多显示一个 active plan run。 - 策划阶段聊天输入属于当前 run:有活跃决策卡/审批卡时,输入回到该卡片对应 action;无 active run 时才可创建新的 plan continuation。 - approved 后显示“开始完整制作”;“批准并开建”只是先审批、后开建的快捷交互,不合并后端命令或 durable 记录。 @@ -1578,7 +1630,7 @@ Canvas 是条件外部能力,不是 M0-3 四个固定 owner 的通用前置: | projection recovery | index/Markdown/audit/observation/session/独立 pending 每个断点恢复;现役 global pending v5 零迁移;恰一逻辑 audit/observation;无永久 stale 卡 | | agent.db | 专用幂等 helper;same key conflict;日志达到普通容量、尾部截断与压缩后仍能补齐并保留决定记录 | | source/security | durable exact identity;四 action tool 广告与执行;MCP 空且 webSearchEnabled=false;control functions 单列;tool-plan/batch/ledger/context/repair/completion 全部跳过 collaboration;plan retry 保留 source/profile;所有副作用工具拒绝 | -| Prompt | tool-plan、decision-checkpoint 和 final-reply 都用 supervisorPlanChat;3 轮/单题/固定选项;回答后设计解释与 prototype item;平台事实;恢复摘要;direct-out 条件 | +| Prompt | **2026-08-13 按 D11 改写**:不新增 composition,Supervisor 根 run 沿用现役 supervisor composition、策划子 Agent 复用 `runtime` composition(见第 4.2 节);`decision-checkpoint` 请求 kind 随 D10 作废(见第 5.1 节)。仍冻结:3 轮/单题/固定选项;回答后设计解释与 prototype item;平台事实;恢复摘要;direct-out 条件 | | frontend | 默认入口与直接开建;stable approvalRequestId/responseId;busy;stale card;hydrate strict input/view;无目录空态;receipt 隐藏 stale pending;corrupt authority typed error;project open/reload/resume/submit/decision 刷新;recovery pending;批准并开建两命令顺序 | | M2 integration | explicit approved/direct mode;锁内重验 receipt;ref 贯穿 task/run/completion/context;无 ref 非回归;恢复不换稿 | | M3 integration | 有批准 GDD 的只读注入;无 GDD 零差异;不改变 game-chat 单主 lineage | @@ -1757,9 +1809,16 @@ M0 完成不表示任何策划功能已上线。M1 的功能实现仍未开始 | 一 | `M0A-3` 批一:D9 二次作废 / D10 作废 / D11 入表、第 1.1 节新拓扑段、第 19 节第 2 条与第 24 节第 8 条改写、decision-log 补记 | **已完成**(见第 1.1 节批一执行状态) | | 二 | `WP1` + `WP2`:澄清轮次与返工深度拆分及其回归 | **已完成**(见第 23.5 节) | | 三 | `project-planning` 的 agentCatalog 登记机制定稿 | **已完成**(机制冻结见第 3.1 节;代码落地属 M1) | -| 四 | `M0A-3` 批二:第 3 节注册表其余行、第 4 节拓扑图与 4.1 / 4.2 / 4.3、第 5.1 / 5.2、第 6 节 Prompt、第 8.3~8.6、第 9.1 golden vector 重算、第 12、13.1 / 13.3、第 14、18.1 节按 D11 重写 | **待开工**,不再有前置阻塞 | +| 四 | `M0A-3` 批二:拓扑与工具面部分 | **已完成**(2026-08-13),拆解见下 | +| 四之余 | schema 与 golden vector 收口 | **待开工,前置是 M1 的 strict schema 实现** | | 五 | M1 本体:策划闭环功能实现 | 未开始;合入门见下 | +批二在 2026-08-13 拆成两半,因为其中一半在 M1 代码存在之前**做不完**: + +*已完成*——第 3 节注册表按 D11 更正(策划子 Agent 的 durable source 由 `agent-ready-task-scheduler` 改为 `agent-delegate`;删除随 D10 作废的 `plan.request_decision`;Prompt composition 由冻结值 `projectPlanning` 改为「不新增、复用现役」,消解了与第 3.1 节的自相矛盾;run profile 的成立理由改为委派父子继承);第 4 节拓扑图重画;第 4.1 节按「Supervisor 根 run + 策划子 run 两层」整节重写;第 4.2 节整节重写(`supervisorPlanChat` / `SupervisorPlanChat` 一并作废);第 4.3 节按两层工具面整节重写,并修正了原文「明确禁止 `agent.delegate`」与 D11「Supervisor 在做方案链路的主动作恰恰是委派」之间的方向性冲突;第 5.1 节对话循环四条按 D11 重写;第 18.1 节前端入口 source 更正;第 22 节 Prompt 行更正。 + +*未完成*——第 5.2 节后半,以及第 8.3~8.6、9.1、12、13、14 节中依赖 `plan-decision-checkpoint` / `activeQuestion` 的内容。这些与 golden vector 强耦合:改 schema 就必须同步重算第 9.1 节的 typed 指纹,而**指纹必须由代码生成、不得手写**,M1 的 strict schema 尚未实现。此时逐段修补只会产生「schema 已改、vector 未换」的中间态,比暂时保留旧文更危险。已在第 5.2 节加作废横幅、并在上述五节各加一条指向它的短横幅,明确这些内容只作为 D10 时代的历史记录、不得作为实现依据,冲突时以第 4.1 / 4.2 / 4.3 / 5.1 节为准。 + 第四步的范围纪律:批二是把这些小节从 D9/D10 旧拓扑改写到 D11 新拓扑,**不是**实现功能。第 9.1 节的 golden vector 必须由代码重新生成,不得手写。 第五步开工前必须先处置的事项,按性质分两类: