diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index 27ce8feab..ec990eea3 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -1,5 +1,14 @@ # 决策记录 +## 2026-08-13 立项策划 plan 根 run 不允许 steer + +- 裁决:plan 根 run(`source=project-supervisor-plan`)**不接受 steer 替换协议**。原「plan run 是否允许 steer」待裁决项就此关闭。 +- 理由不是「交互未验证」,而是确定性的能力损失:D11 把策划的问询轮次预算挂在委派链上——`clarification_round` 沿 `repair_of_delegation_id` 上溯推断,且每一跳强制 `parent_run_id` 等于当前根 run。steer 会终止旧根、另起 replacement root run,换根后 `parent_run_id` 改变,旧链的 continuation 被跨 run 隔离判据直接拒绝,**该策划链路剩余问询轮次全部作废,用户已回答的内容也无法续接**。 +- 实现约束(关键,不得靠副作用实现):`goal_contract_root_steer_replacement_run_id`(`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/steering.rs:763`)现在的资格判据是 `agent_runtime_supervisor_source_is_trusted(&task.source)`,而该 matcher **同时**是 Goal Contract 创建权限与根控制面工具授权的判据。因此**不得**用「不把 `project-supervisor-plan` 加进该 matcher」来实现本裁决——那会连带否掉 Goal Contract,正好撞上仍未裁决的「plan source 与 Goal Contract 协议的关系」。本裁决必须是一条**独立于可信 source 判定的显式否决**:steer 入口识别出 plan 根 run 即拒绝并返回 typed 错误,无论该 source 是否在可信 matcher 内。回归须覆盖「在 matcher 内」与「不在 matcher 内」两种情形下 steer 均被拒。 +- 产品侧替代路径:本轮问询内回答/自由填写纠偏;GDD 审批卡 `revise` / `reject`;再不行放弃本轮、重开一条 plan lineage(同一时刻只允许一条非终态 lineage,第二条返回 `PLAN_ACTIVE_RUN_EXISTS`)。 +- 连带消解:原条目里「父 Supervisor 被 steer 时下游委派子 Agent 如何收束」随之不存在。game-chat 路径的同类问题不受影响,仍按 2026-08-11 条既有结论处理。 +- M1 入口前置决策至此剩两项:checkpoint handoff 私有持久化;plan source 与 Goal Contract 协议的关系(后者带硬门——裁决冻结前,依赖 plan source 可信身份的 M1 代码不得合入;2026-08-13 已合入的 `project-planning` 身份登记不触碰该门,它登记的是子 Agent 的 `agentId`,未引入 `project-supervisor-plan` 这个 source)。 + ## 2026-08-13 立项策划执行计划入档:五步顺序、`WP1`/`WP2` 完成状态与后置清单写进技术方案 - 背景:D6→D9→D11 三轮拓扑改写与 `WP1` 拆分都各自记了决策,但「现在做到哪一步、下一步是什么」一直只存在于会话里,没有任何仓库内载体。直接后果是技术方案出现过时陈述——文首状态行与第 1.1 节第 5 条在 `WP1`/`WP2` 已合入本分支后,仍写着「WP1 落地前问询上限仍是 1 轮」「正在另一个 worktree 并行实现」,读文档的人会以为该工作尚未开始。本条把执行计划本身作为需要维护的对象入档。 diff --git a/docs/technical/【技术方案】立项策划Agent(Fast GDD)-2026-08-10.md b/docs/technical/【技术方案】立项策划Agent(Fast GDD)-2026-08-10.md index 0df9da4f3..dae182ad9 100644 --- a/docs/technical/【技术方案】立项策划Agent(Fast GDD)-2026-08-10.md +++ b/docs/technical/【技术方案】立项策划Agent(Fast GDD)-2026-08-10.md @@ -1742,7 +1742,15 @@ D9 之后,root 是未变的 Project Supervisor,它在 `standard` 下天然 - **checkpoint handoff 私有持久化**——原有待裁决项,不受拓扑变更影响,继续保留。 - **plan source 与 Goal Contract 协议的关系**——2026-08-12 新增待裁决项,继续保留,**未被上方「2026-08-12 替换结论」解决**。上方三条约束只处置了「策划 run 是否需要豁免 root」这一支(四方案的共同前提),给出的是候选设计方向;但 decision-log 2026-08-12 条「M0 全部完成,并据动态目标验收图收敛 M2/M3 设计」逐字记录的裁决状态仍是「保留待裁决」「裁决冻结前,依赖 plan source 可信身份的 M1 代码不得合入」,且该记录未被任何后续 decision-log 条目覆盖或撤销。本文档此前在本小节未把它列入「仍然保留」,与第 23.4 节、第 23.6 节的表述相冲突(2026-08-13 对抗性复核补记并订正为一致口径)——按最保守口径,本项在正式裁决(decision-log 新条目)冻结前一律按待裁决处理。 - ~~**策划节点 `agentId` / source 命名**~~——**2026-08-13 已裁决冻结**:策划子 Agent `agentId=project-planning`;Supervisor 侧承载「做方案」入口的新可信 source 取全新常量名 `project-supervisor-plan`(不沿用历史 `project-supervisor-plan-chat` 字面,避免语义改变后接错旧代码路径)。第 1.1 节批二不再被本项阻塞,改由下方新增的 `build.rs` 一致性待裁决项阻塞。 -- **plan run 是否允许 steer**——`steering.rs` 的 steer 门按可信 source 判定,steer 替换协议会终止旧根并另起 replacement root run,与第 5.1 节的 session CAS、`roundsUsed` 与 `activeQuestion` 存在未验证交互,第 14 节恢复矩阵没有这条路径。**D11 新拓扑下问题形态变化但未消解**:策划节点不再是 ready-task 工作流节点,而是 Supervisor 的委派子 Agent,与 game-chat 动态美术委派子 Agent 面临同一类「父 Supervisor 被 steer 时下游委派子 Agent 如何收束」问题(参见 2026-08-11 game-chat 动态美术 child 通用 retry 失败关闭的裁决,decision-log 同日条),但委派子 Agent 的收束机制(静态委派 delivery/claim 生命周期)与 ready-task 工作流节点的收束机制并不相同,不能直接照搬旧结论,需重新验证。 +- ~~**plan run 是否允许 steer**~~——**2026-08-13 已裁决:不允许。** plan 根 run 不接受 steer 替换协议。 + + *裁决理由*:steer 替换会终止旧根、另起 replacement root run,而 D11 把策划的轮次预算挂在了委派链上——`clarification_round` 沿 `repair_of_delegation_id` 上溯推断,且每一跳都强制 `parent_run_id` 等于当前根 run(见第 4.1 节与第 23.5 节)。换根之后 `parent_run_id` 变了,旧链的 continuation 会被跨 run 隔离判据直接拒绝,**这条策划链路剩余的问询轮次全部作废**,用户已经回答过的内容也无法续接。这不是"交互未验证",是确定性的能力损失。 + + *实现要求(重要,不能靠副作用实现)*:`goal_contract_root_steer_replacement_run_id`(`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/steering.rs:763`)现在的资格判据是 `agent_runtime_supervisor_source_is_trusted(&task.source)`——**与 Goal Contract 创建权限、根控制面工具授权是同一个 matcher**。因此**不得**用「不把 `project-supervisor-plan` 加进该 matcher」来实现本裁决:那会连带否掉 Goal Contract,正好撞上本节尚未裁决的「plan source 与 Goal Contract 协议的关系」。本裁决必须实现为一条**独立于可信 source 判定的显式否决**:steer 入口识别出 plan 根 run 后直接拒绝并返回 typed 错误,无论该 source 是否在可信 matcher 内。回归用例须同时覆盖「plan source 在 matcher 内」与「不在 matcher 内」两种情形下 steer 均被拒。 + + *产品侧替代路径*:用户中途要改方向,走既有的两条——本轮问询里回答/自由填写来纠偏;或在 GDD 审批卡上 `revise` / `reject`。都不行时放弃本轮、重开一条 plan lineage(第 4.1 节的 `PLAN_ACTIVE_RUN_EXISTS` 约束保证同一时刻只有一条非终态 lineage)。 + + *连带收益*:本裁决同时消解了原条目里「父 Supervisor 被 steer 时下游委派子 Agent 如何收束」这个问题——plan 根 run 不可被 steer,该场景不存在。game-chat 路径的同类问题不受影响,仍按 decision-log 2026-08-11 条的既有结论处理。 - ~~**`project-planning` 的编译期 agentCatalog 登记方式与 `build.rs` 一致性校验**~~——**2026-08-13 机制已定稿**(见第 3.1 节):`project-planning` 在 `agentCatalog` 下登记为与 `supervisor` 平级、不进 `groups` 数组的独立条目,`specialist_nodes` 只读 `manifest.agent_catalog.groups[].roles[]`(`build_support/runtime_prompt_bundle.rs:387-398`),因此 `build.rs` 的 `validate_seed_task_catalog`(`apps/ai-game-creator-shell/src-tauri/build.rs:23-46`)、16 任务种子 DAG、`new_game_creation_app_seed_tasks()` 均不需要改动。批二不再被 catalog 一致性问题阻塞;但登记机制定稿过程中查实了一个新的、真正的**待裁决/待处置项**(不是同一个问题的延续,是第 3.1 节调研发现的独立缺口):`prompt.rs` 的 `game_creator_agent_role_definition`(`apps/ai-game-creator-shell/src-tauri/src/agent/prompt.rs:661-679`)是把 `agent_id` 合成出角色身份的唯一函数,目前硬编码「非 `project-supervisor` 即 group 角色」的二分,`project-planning` 落入 else 分支会返回 `None`,其两个调用方(`provider_request_builders.rs:536-539`、`prompt.rs:416-417`)都会把 `None` 转成 `Err` 中断执行,报「未知 Agent 模板:project-planning」。也就是说**仅做 catalog 登记不足以让 D11 的静态委派可执行**,还需要在 `game_creator_agent_role_definition` 里补一个平行于 supervisor 特判的 `project-planning` 分支——这是 M1 落地范围,第 3.1 节已列出完整改动清单(含另外两处 needs_change:`task_ops.rs` 的 group/role 兜底误分类、`delegation.rs` 的 `agent.spawn_isolated` 放行面),本文档不再假装这只是「登记方式未裁决」,而是明确记录为「机制已定稿、代码待 M1 落地」。 ### 23.2 M0-3:统一 owner 产物验证与可玩验收边界(PR 工作包 `M0A-2`) @@ -1825,7 +1833,7 @@ M0 完成不表示任何策划功能已上线。M1 的功能实现仍未开始 *一、身份可执行性缺口*(第 3.1 节「登记前必须先处理的代码改动」,仅 catalog 登记不足以让静态委派跑起来)——其中角色身份合成缺口为 blocking,另有若干 needs_change 项与一条既有测试的期望集合需同步更新。清单以第 3.1 节为准,本节不重复。 -*二、既有待裁决项*(第 23.1 节)——checkpoint handoff 私有持久化;plan source 与 Goal Contract 协议的关系。二者是 M1 的合入门,不是 M0 或本节前三步的完成门。 +*二、既有待裁决项*(第 23.1 节)——checkpoint handoff 私有持久化;plan source 与 Goal Contract 协议的关系。二者是 M1 的合入门,不是 M0 或本节前三步的完成门。其中后者带硬门:**裁决冻结前,依赖 plan source 可信身份的 M1 代码不得合入**(2026-08-13 已合入的 `project-planning` 身份登记不触碰该门——它登记的是子 Agent 的 `agentId`,未引入 `project-supervisor-plan` 这个 source)。原第三项「plan run 是否允许 steer」已于 2026-08-13 裁决为**不允许**,不再是待裁决项。 以下为已识别但**明确后置**、不阻塞上述任何一步的工作项: