diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index fba7df647..27ce8feab 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -1,5 +1,13 @@ # 决策记录 +## 2026-08-13 立项策划执行计划入档:五步顺序、`WP1`/`WP2` 完成状态与后置清单写进技术方案 + +- 背景:D6→D9→D11 三轮拓扑改写与 `WP1` 拆分都各自记了决策,但「现在做到哪一步、下一步是什么」一直只存在于会话里,没有任何仓库内载体。直接后果是技术方案出现过时陈述——文首状态行与第 1.1 节第 5 条在 `WP1`/`WP2` 已合入本分支后,仍写着「WP1 落地前问询上限仍是 1 轮」「正在另一个 worktree 并行实现」,读文档的人会以为该工作尚未开始。本条把执行计划本身作为需要维护的对象入档。 +- 决策:技术方案新增第 23.5 节(`WP1`/`WP2` 的问题、定稿语义、门禁与完成状态)与第 23.6 节(五步执行计划表 + M1 开工前必须处置的两类事项 + 明确后置清单),并修正上述两处过时陈述。此后每完成一步,须同步更新第 23.6 节的状态列;**设计结论变更与进度状态变更是两件必须分别维护的事,不得只更新前者。** +- `WP1` 的独立立包依据:它改的是 master 已发布的 PR #165 静态委派澄清中转机制,服务对象不止策划链路,因此不并入 M0/M1 门禁,单列第 23.5 节。语义权威定义仍在本文件同日「静态委派返工深度与澄清轮次拆分」相关条目,第 23.5 节只承载问题陈述、门禁与完成状态,不重复展开语义。 +- 明确后置、不阻塞任何一步的四项已记入第 23.6 节:run status 观测暴露派生计数;画布替换授权是否收紧为「只有真实质量返工可替换正式图片」(PR #165 之后就存在的既有行为,与本方案诉求无关);跨 run 全局预算缺口(7 跳是单链界、不是项目生命周期累计界,只要不断开新 run 就能不断获得新配额,本阶段只记录不实现);「做游戏」路径改造(删 `design-director`、收窄 `design-foundation`、调整 16 任务 DAG)。 +- 未纳入:此前一度使用过的 `WP0`/`WP3`/`WP4`/`WP5` 编号从未落进仓库,为避免出现两套不一致的工作包编号,本次只保留 `WP1`/`WP2` 两个真实存在的包名,其余内容按性质分别归入第 23.6 节的「M1 开工前必须处置」与「明确后置」两类,不再引入新编号。 + ## 2026-08-13 `project-planning` 的 agentCatalog 登记机制定稿:与 `supervisor` 平级、不进 `groups`,「做游戏链路一行不动」得以成立 - 背景:D11(见下方同日「立项策划 D9 二次作废…」条)继承了 D9「`project-planning` 需登记 agentCatalog」的结论,但登记方式一直是待裁决项——`build.rs` 的 `validate_seed_task_catalog`(`apps/ai-game-creator-shell/src-tauri/build.rs:23-46`)要求编译出的 `(taskId, groupId, role)` 集合与 `shared_contracts::game_creation_app::new_game_creation_app_seed_tasks()` 完全相等,不等即 `panic!`,直接把 `project-planning` 塞进任何一个专业组会破坏这条一致性校验、污染 16 任务种子 DAG。本条只做只读取证与机制定稿,**不落地任何代码**,工作目录 `C:/wtp`(分支 `feat/plan-agent-catalog-registration`),只改文档。 diff --git a/docs/technical/【技术方案】立项策划Agent(Fast GDD)-2026-08-10.md b/docs/technical/【技术方案】立项策划Agent(Fast GDD)-2026-08-10.md index e54782999..24f31b887 100644 --- a/docs/technical/【技术方案】立项策划Agent(Fast GDD)-2026-08-10.md +++ b/docs/technical/【技术方案】立项策划Agent(Fast GDD)-2026-08-10.md @@ -1,7 +1,7 @@ # 立项策划 Agent(Fast GDD)技术方案 - 日期:2026-08-10 -- 状态:2026-08-12 **M0 代码工作包全部完成**(`M0A-2`、`M0B-1`、`M0B-2` 已合入 M0 集成分支并通过各自门禁,见第 23.4 节);同日 **D6 作废、拓扑改变**,`M0A-1` 交付的文档基线随之失效,需以工作包 `M0A-3` 修订,**修订完成前 M0 不计完整完成**(见第 1.1 节)。2026-08-13 **D9 二次作废、D10 作废,由 D11 取代**:立项策划节点改为 Project Supervisor 通过 `agent.delegate` 发起的静态委派子 Agent,问询复用 PR #165 中转链路(见第 1.1 节「D11 新拓扑」);D11 依赖 WP1(静态委派澄清轮次与返工深度拆分)为强制前置,WP1 落地前问询上限仍是 1 轮。M1~M3 功能尚未实现,全仓库零代码 +- 状态:2026-08-12 **M0 代码工作包全部完成**(`M0A-2`、`M0B-1`、`M0B-2` 已合入 M0 集成分支并通过各自门禁,见第 23.4 节);同日 **D6 作废、拓扑改变**,`M0A-1` 交付的文档基线随之失效,需以工作包 `M0A-3` 修订,**修订完成前 M0 不计完整完成**(见第 1.1 节)。2026-08-13 **D9 二次作废、D10 作废,由 D11 取代**:立项策划节点改为 Project Supervisor 通过 `agent.delegate` 发起的静态委派子 Agent,问询复用 PR #165 中转链路(见第 1.1 节「D11 新拓扑」);D11 依赖 WP1(静态委派澄清轮次与返工深度拆分)为强制前置,**该前置已于 2026-08-13 落地并合入**(`WP1` 生产代码 + `WP2` 回归,完成状态与门禁见第 23.5 节),澄清轮次上限现为 3(game-chat source 仍为 1)。后续执行计划见第 23.6 节。M1~M3 的策划功能本身仍未实现,`fast_gdd` / `.agent/planning` / `project-planning` 相关代码全仓库零命中 - 适用范围:AI 游戏创作独立 App、Project Supervisor、Agent Runtime、本地项目策划 sidecar 与后续完整构建准入 - 当前实现边界:本文件是后续详细设计与实现的仓库内阶段基线;M0 工作包只冻结 Fast GDD 合同并修复现有 owner 验证、game-chat retry 与前端投影边界,不代表立项策划入口、审批 UI、Runtime 持久化或构建绑定已经可用 @@ -88,6 +88,8 @@ M0 三个代码工作包无一行按 D6 编写,**不需要为新设计回退 2026-08-13 更新:命名裁决已冻结——策划子 Agent `agentId=project-planning`,Supervisor 侧承载「做方案」入口的新可信 source 为 `project-supervisor-plan`。批二不再被命名阻塞。但 D11 把策划节点从「ready-task 工作流节点」改成「静态委派子 Agent」,批二这些小节的具体写法(尤其第 3 节注册表、第 4 节拓扑图)必须按 D11 新拓扑而非 D9 旧拓扑重写,且新增了「D11 新拓扑」第 6 条列出的 `build.rs` agentCatalog 一致性前置——`project-planning` 如何登记进编译期 seed task catalog 而不触发 `validate_seed_task_catalog`(`apps/ai-game-creator-shell/src-tauri/build.rs:23-46`)panic,此前尚未裁决,批二涉及注册表落笔前必须先冻结这一点。本轮文档修订范围不含批二,此处只记录状态变化。 +2026-08-13 批一执行状态:批一所列五项已全部落笔并合入(文首状态行、第 1.1 节、第 2 节决定表、第 19 节第 2 条、第 24 节第 8 条、第 23.1 节、第 22 节证据表、第 23.4 节)。其中第 19 节第 2 条与第 24 节第 8 条在 D11 之后又按新拓扑二次改写,现行表述以 D11 为准。批一至此收口,`M0A-3` 的剩余工作只有批二。 + 2026-08-13 二次更新:`build.rs` agentCatalog 一致性问题已定稿(见第 3.1 节)——`project-planning` 登记为与 `supervisor` 平级、不进 `groups` 数组的独立条目,`specialist_nodes` 只读 `groups[].roles[]`,`build.rs`/种子 DAG/`new_game_creation_app_seed_tasks()` 均不需要改动。批二不再被这一具体问题阻塞。但第 3.1 节调研同时发现一个新的、更靠后的执行层缺口:`prompt.rs` 的 `game_creator_agent_role_definition`(`apps/ai-game-creator-shell/src-tauri/src/agent/prompt.rs:661-679`)目前不认识 `project-planning`,仅做 catalog 登记不足以让静态委派可执行,需 M1 补一个平行于 supervisor 特判的分支(清单见第 3.1 节)。批二仍不在本轮范围内,此处只记录状态变化,不落笔批二内容。 #### Goal Contract:四方案作废,替换为三条已验证约束 @@ -121,7 +123,7 @@ D9/D10 描述的「manifest ready-task 调度器在 Supervisor 下游启动策 2. **约束二(答案物理落 Supervisor 会话)成立,有完整机械证据链。** `ensure_static_delegate_user_input_wait_at`(`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/provider_recovery.rs:327-408`)→ `build_game_creator_agent_runtime_pending_tool_action`(`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/provider_action_batch.rs:219-251`,`agent_id`/`session_id`/`run_id` 直接抄 Supervisor 自身的 `runtime` 参数)→ `build_new_user_input_record`(`user_input.rs:396-411`,`agent_id`/`session_id` 从 pending 原样继承)→ `append_user_input_question_message` / `append_user_input_answer_message`(`user_input.rs:494-532`)→ `conversation_file_path_for_resolved_session`(`apps/ai-game-creator-shell/src-tauri/src/project/conversation.rs:48-59`)。问答消息物理写进 Supervisor 自己的会话 `.jsonl` 文件,是后端持久化事实,不是前端把多个 Agent 的会话拼接显示。 3. **多轮不失忆,但转述保真不由 Runtime 校验。** 委派的 `target_session_id` 每轮都解析为 `resolve_agent_conversation_session_id_at(root, target_agent_id, None, true)`(`apps/ai-game-creator-shell/src-tauri/src/project/conversation.rs:860-875`),传 `None` 时走 `catalog.active_session_id`(`conversation.rs:849-850`)——即每一轮委派都落在同一条持久 active session 上;而 prompt history 按 `(agent_id, session_id)` 组装(`apps/ai-game-creator-shell/src-tauri/src/context_compaction.rs:453-490` 的 `prepare_game_creator_agent_runtime_prompt_history`),`run_id` 只用于 `observation_start` 的覆盖计数过滤。因此 continuation 子 Agent 是「新 run、同 session」,能看到自己前几轮的完整对话。**但残留风险如实记录**:用户的答案本身不在子 Agent 的 session 里(物理落在 Supervisor 那边),子 Agent 只能依赖 Supervisor 把已确认答案重新组织进新的委派 task 文本;Runtime 只校验 `questionsSha256`/`answersSha256` 的哈希绑定,**不校验转述内容与已确认答案的语义一致性**,转述保真完全依赖 Supervisor 侧 LLM 的行为质量。委派 task 有硬上限 `AGENT_RUNTIME_TASK_MAX_CHARS = 4_000`(`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver.rs:147`),超限直接 `Err`,不会静默截断丢失内容。 4. **产物路径与 `.agent/planning/**` 不冲突,且有结构性保证而非文档层自律。** `normalize_static_delegate_expected_artifact`(`apps/ai-game-creator-shell/src-tauri/src/delegation.rs:1981-1998`)拒绝首段为 `.agent` 的相对路径,因此 `.agent/planning/**` 在委派发起阶段就无法进入 `expectedArtifacts`,不需要额外的文档层面约束。`game/fast_gdd.md` 不在 `.agent` 下,可以正常登记。定稿:`expectedArtifacts=["game/fast_gdd.md"]`,质性标准写进 `acceptanceCriteria`,`verification_required=false`——策划节点没有 verify/smoke 类工具,无法产生可供 Runtime 复核的验证凭证。 -5. **前置依赖:D11 的“最多 3 轮问询”依赖 WP1 先落地,是强制前置,不是并行工作包。** WP1(澄清轮次 `clarification_round` 与返工深度 `repair_depth` 拆分,详见下方及 decision-log 2026-08-13 条)正在另一个 worktree 并行实现。在 WP1 落地前,`repair_of_delegation_id.is_some()` 即拒绝(`apps/ai-game-creator-shell/src-tauri/src/delegation.rs:1119-1121`),澄清 continuation 与质量返工共用同一条「深度最多为 1」判据,D11 描述的多轮问询实际上限只有 1 轮,且这 1 轮一旦用掉,同一条委派链就再也做不了任何质量返工。本文档把 WP1 列为 D11 生效的强制前置条件,不得默认「等 WP1 完成再补上限」这种弱化表述。 +5. **前置依赖:D11 的“最多 3 轮问询”依赖 WP1 先落地,是强制前置,不是并行工作包。该前置已于 2026-08-13 落地,本条改为记录其成立依据与已完成状态。** WP1(澄清轮次 `clarification_round` 与返工深度 `repair_depth` 拆分,语义见下方,权威定义见 decision-log 2026-08-13 条)与其回归工作包 `WP2` 已合入本分支,完成状态与门禁见第 23.5 节。作为对照记录改造前的事实:改造前 `repair_of_delegation_id.is_some()` 即拒绝(`apps/ai-game-creator-shell/src-tauri/src/delegation.rs:1119-1121`),澄清 continuation 与质量返工共用同一条「深度最多为 1」判据,D11 描述的多轮问询实际上限只有 1 轮,且这 1 轮一旦用掉,同一条委派链就再也做不了任何质量返工;该结论由 `clarification_continuation_chain_supports_multiple_rounds` 走真实 `agent.delegate` 生产路径实证(改造后该用例的断言方向已按预期行为变更反转,见第 23.5 节)。本条不因 WP1 完成而降格:D11 的 3 轮问询能力**只在 WP1 语义生效的前提下成立**,任何回退 WP1 的改动都同时回退 D11 的问询上限。 6. **登记机制已定稿(原「未决前置」,2026-08-13 处置完成):`project-planning` 的编译期 agentCatalog 登记方式,不会撞上 `build.rs` 一致性校验。** `project-planning` 目前不在编译期 agentCatalog 里;`build.rs` 的 `validate_seed_task_catalog`(`apps/ai-game-creator-shell/src-tauri/build.rs:23-46`)要求编译出的 `(taskId, groupId, role)` 集合与 `shared_contracts::game_creation_app::new_game_creation_app_seed_tasks()` 逐项相等,不等直接 `panic!`;但该集合只来自 `manifest.agent_catalog.groups[].roles[]`(`build_support/runtime_prompt_bundle.rs:387-398`),不遍历 `agentCatalog` 其它顶层键。结论:`project-planning` 登记为与 `supervisor` 平级、不进 `groups` 数组的独立条目(先例即 `supervisor` 自己——它是 catalog 成员但不是种子 DAG 任务,`runtime_adapter.rs:4-38`),`new_game_creation_app_seed_tasks()` 不需要新增条目,该 catalog 本身也不需要拆分。完整机制、descriptor 元数据取值与编译链路改动清单见第 3.1 节。**但登记只解决 catalog 成员资格,不解决可执行性**——第 3.1 节调研同时发现一个新的、真正阻塞可执行的缺口:`prompt.rs` 的 `game_creator_agent_role_definition`(`prompt.rs:661-679`)硬编码「非 supervisor 即 group 角色」二分,不认识 `project-planning`,需 M1 补一个平行分支;这才是仍然待处置(M1 范围)的前置,不是本条描述的 catalog 登记方式本身。 WP1 定稿的澄清轮次/返工深度语义(供 D11 依赖,权威定义见 decision-log 2026-08-13 条,不在本节重复展开):`repair_depth` 上限维持 1 不放松,`clarification_round` 上限按 source 区分——`source == AGENT_RUNTIME_SUPERVISOR_GAME_CHAT_SOURCE`(`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver.rs:109`)时取 1,其它 source(含 D11 的 `project-planning` 委派链)取 3;两个维度都是运行时沿 `repair_of_delegation_id` 链上推断的派生值,不新增 `StaticDelegateDeliveryRecord` 持久字段。 @@ -1718,6 +1720,60 @@ M0 收口时的三项已知残留,均已定性且不阻塞后续阶段: M0 完成不表示任何策划功能已上线。M1 的功能实现仍未开始,第 19 节第 2 条等 plan source 不变量目前只是设计意图。 +### 23.5 `WP1` / `WP2`:静态委派澄清轮次与返工深度拆分(2026-08-13 完成) + +这是 D11 的强制前置(见第 1.1 节「D11 新拓扑」第 5 条)。它**不属于 M1~M3**,改的是 master 已发布的 PR #165 静态委派澄清中转机制,服务对象也不止策划链路;因此单独立包,不并入 M0/M1 的门禁。 + +**问题**:`repair_of_delegation_id` 一个字段同时承载「质量返工」与「澄清 continuation」两种语义,`validate_static_delegate_repair_request_at` 用同一道「深度最多为 1」的门对两者无差别拒绝。后果不只是「第 3 轮不可达」——一次澄清会耗尽整条委派链唯一一次质量返工额度。 + +**定稿语义**(权威定义见 decision-log 2026-08-13 条):`repair_depth` 与 `clarification_round` 拆成两个互相独立的维度,且**都是运行时沿链推断的派生值,不新增持久字段**。 + +- 分类判据(唯一权威):`parent.structured_result.contract_status == NeedsUserInput` ⟺ 该跳是澄清 continuation;否则是质量返工。 +- 传播:根节点 `(0, 0)`;澄清跳 `round += 1` 且 **`depth` 不变**;返工跳 `depth += 1` 且 **`round` 重置为 0**。 +- 上限:`repair_depth` 维持 1 不放松;`clarification_round` 按 source 区分,game-chat source 取 1、其它 source(含 `project-planning` 委派链)取 3。 +- 单链总跳数上界 `1 + 2 × 3 = 7` 跳、8 条 delivery 记录。**注意是 7 不是 6**——连接两层的返工跳本身也算一跳。 + +**为什么不加持久字段**:给 `StaticDelegateDeliveryRecord` 新增 `repair_depth` 并用 `#[serde(default)]` 兜底,会让磁盘上已有的返工记录读出 `0`,深度门失效,「返工的返工」漏洞原样复活——方向是 fail-open,不可接受。链上推断对历史记录是**精确**而非仅保守:PR #165 之前不存在 `NeedsUserInput`,旧记录天然被正确分类为「非澄清」。 + +**落地**:`static_delegate_lineage_counters`(`apps/ai-game-creator-shell/src-tauri/src/delegation.rs`)沿 `repair_of_delegation_id` 上溯到根后正向重放,带环检测与跳数上限,异常一律 fail closed;判据抽成与 `validate_static_delegate_clarification_continuation_at` 共用的小函数,避免两处口径漂移。`validate_static_delegate_repair_request_at` 的函数签名未变;同级返工门(同一 delivery 最多一个非 suppressed 子请求)未动;`STATIC_DELEGATE_DELIVERY_SCHEMA_VERSION` 与 `new_static_delegate_delivery_with_contract` 签名均未动。 + +**门禁与完成定义**: + +- 返工门错误文案必须原样保留(现有回归断言了该字符串),澄清上限用一条明显不同的新文案,且用例显式断言两个维度的文案互不串扰。 +- 必须继续绿的回归防线:「返工的返工必须被拒」、`project_supervisor_static_delegate_repair_is_single_bounded_wave`、单跳澄清基准。 +- `clarification_continuation_chain_supports_multiple_rounds` 的断言方向反转属**有意的行为变更**,测试内注释须写明;反转的同时新增对 `(depth, round)` 取值的正向断言,不得只删旧检查。 +- 新增用例须走真实 `observe_agent_runtime_agent_delegate` 生产路径,不得只调校验函数。其中**交替链用例是必需项**:`根 → 返工(depth=1)→ 澄清(depth 仍为 1、round=1)→ 再返工(必须被拒)`;它是唯一能同时证伪「返工跳漏加 1」与「澄清跳误清零」两种失误的用例,而改造前的测试要么纯返工链要么纯澄清链,从未覆盖交替。 +- 另需覆盖:第 4 轮边界、返工重置澄清轮次、澄清不占同级返工门配额、历史记录分类、跨 run 隔离、source 区分上限。 + +**完成状态**:上述门禁全部通过,`WP1` 生产代码与 `WP2` 回归已合入本分支。已知遗留:`project_supervisor_concurrent_repair_dispatch_creates_exactly_one_delivery` 是 Barrier 同步的并发用例,在本机 Windows 上间歇失败;经与改造前基线对照(同一用例各跑 6 次,改造前后同为 1 次失败)确认为既有抖动,不是本工作包引入,不作为回归处理。 + +### 23.6 后续执行计划(2026-08-13 起) + +本节记录 D11 之后的执行顺序与各步状态,避免「设计结论持续更新、但做到哪了无人维护」。 + +| 步骤 | 内容 | 状态 | +| --- | --- | --- | +| 一 | `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 重写 | **待开工**,不再有前置阻塞 | +| 五 | M1 本体:策划闭环功能实现 | 未开始;合入门见下 | + +第四步的范围纪律:批二是把这些小节从 D9/D10 旧拓扑改写到 D11 新拓扑,**不是**实现功能。第 9.1 节的 golden vector 必须由代码重新生成,不得手写。 + +第五步开工前必须先处置的事项,按性质分两类: + +*一、身份可执行性缺口*(第 3.1 节「登记前必须先处理的代码改动」,仅 catalog 登记不足以让静态委派跑起来)——其中角色身份合成缺口为 blocking,另有若干 needs_change 项与一条既有测试的期望集合需同步更新。清单以第 3.1 节为准,本节不重复。 + +*二、既有待裁决项*(第 23.1 节)——checkpoint handoff 私有持久化;plan source 与 Goal Contract 协议的关系。二者是 M1 的合入门,不是 M0 或本节前三步的完成门。 + +以下为已识别但**明确后置**、不阻塞上述任何一步的工作项: + +- `agent.delegate` 澄清 continuation 相关的观测增强(把派生的 `repair_depth` / `clarification_round` 暴露进 run status 观测,便于 Supervisor 感知预算与排障)。 +- 画布替换授权是否收紧为「只有真实质量返工可替换正式图片,澄清续跑不可」。这是 PR #165 之后就存在的既有行为,与本方案诉求无关,单列待评估。 +- 跨 run 全局预算缺口:第 23.5 节的 7 跳上界是**单条链**(同一 `parent_run_id`)粒度的界,不是某专业 Agent 在项目生命周期内的累计界;只要不断开新 run 就能不断获得新配额。本阶段只记录不实现。 +- 「做游戏」路径改造(删 `design-director`、收窄 `design-foundation`、调整 16 任务 DAG),等 GDD 真正被完整构建消费时另开工作包;见第 1.1 节「`M0A-3` 明确不做」。 + ## 24. 最终不变量摘要 - 策划与构建是两个不同 profile/source 的 run,由用户动作连接,不由 Agent 自行升级。