补充DirectProject canonical内容严格边界计划

- 明确 content-only 输入与最终空内容校验 - 规划删除 userItem 兜底并修正 Direct caller
2026-09-16 15:28:25 +08:00
parent fc0fd846f9
commit f4b496caca
2 changed files with 76 additions and 0 deletions
@@ -0,0 +1,35 @@
+# 【实施计划】DirectProject canonical content 严格边界
+
+| 字段 | 值 |
+| --- | --- |
+| Milestone | `docs/project-memory/plans/【里程碑】DirectProject canonical content严格边界-2026-09-16.md` |
+| Status | in-progress |
+| Owner | Codex |
+
+## 实施顺序
+
+1. 先把主转换函数改为原样传递 `draft.content`，并在 content-only 测试中覆盖空白 part 保留。
+2. 将最终 content 有效性判断抽为纯函数，接入普通提交、队列入队和其它 Direct Codex 入口。
+3. 删除 Direct Codex 的 `userItem` fallback；首页首轮和队列出队直接构造 canonical user item。
+4. 收敛策略确认重试为复用同一 canonical user item；旧 Supervisor/Planning caller 加 TODO，不改变其非 Direct Codex 行为。
+5. 迁移现有测试 fixture，删除旧字段构造，不增加“字段不存在”测试。
+
+## 修改边界
+
+- 允许修改：AGC shell 前端 `resourceReferences`、`App`、聊天队列、Direct Codex 相关测试和当前里程碑文档。
+- 不修改：Rust user item schema、附件 DTO、SpacetimeDB、HTTP API、用户已有 `.env` / `package-lock.json` 修改。
+- 不引入：`text` / `references` 到 canonical Direct Codex item 的任何兼容 fallback。
+
+## 验证命令
+
+- `npm run test -- apps/ai-game-creator-shell/tests/resourceReferences.test.ts apps/ai-game-creator-shell/tests/resourceReferenceInput.test.tsx apps/ai-game-creator-shell/tests/chatPromptPolish.test.tsx apps/ai-game-creator-shell/tests/appSurface/project-conversation.suite.ts`
+- `npm run ai-game-creator-shell:typecheck`
+- `npm run check:encoding`
+- `npm run check:doc-index`
+- `git diff --check`
+
+## 风险与回滚点
+
+- 空白 `input_text` 不再前端删除，需确保最终有效性判断只拒绝全空 content，不改变其它 part。
+- Direct caller 漏传 user item 时应在类型检查或明确错误分支暴露，不能静默重建。
+- 共享工作树含用户未提交修改；提交时只 stage 本计划和本次代码 hunk。
@@ -0,0 +1,41 @@
+# 【里程碑】DirectProject canonical content 严格边界
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 1.0 |
+| Status | proposed |
+| Date | 2026-09-16 |
+| Parent Spec | `docs/【功能说明】AGC聊天素材引用-2026-09-08.md` |
+
+## 目标
+
+让 DirectProject 的用户消息只以 `content[]` 作为 canonical 输入：保留 Lexical 产生的全部 content part（包括纯空白 `input_text`），只在最终 content 上判断是否存在有效输入；所有 Direct Codex caller 必须显式提供完整 `userItem`。
+
+## 范围
+
+- 移除 `chatComposerDraftToDirectCodexUserItem` 对纯空白 `input_text` 的预过滤。
+- Direct Codex 发送前只做最终 content 的有效性判断，不改写 content。
+- 删除 `executeChatAgentReply` 在 `userItem` 缺失时的构造兜底。
+- 修正首页首轮、队列出队和其它 Direct Codex caller，使其直接构造 canonical user item。
+- 将队列与策略确认重试按 canonical user item 传递，避免拆回 `text` / `references`。
+- 仍在使用的旧 Supervisor/Planning caller 保持非 Direct Codex 行为，并添加后续迁移 TODO。
+
+## 不在范围内
+
+- 不保留从 `draft.text` / `draft.references` 重建 Direct Codex content 的兼容分支。
+- 不新增断言 legacy 字段“不存在”的测试；现有测试直接迁移到 content-only 输入。
+- 不修改 Rust user item schema、SpacetimeDB schema、HTTP API 或历史迁移。
+
+## 验收标准
+
+- `chatComposerDraftToDirectCodexUserItem` 输出与输入 `draft.content` 顺序和值完全一致。
+- 只有当最终 content 不含非空文本且不含任何非文本 part 时，发送入口才拒绝本轮。
+- Direct Codex 路径不存在 `userItem ?? ...` 或等价 fallback。
+- 首页首轮、普通聊天、队列出队、策略确认重试均发送同一个 canonical user item 语义。
+- 旧 Supervisor/Planning caller 上有明确 TODO，且不进入 Direct Codex canonical 发送路径。
+
+## 证据
+
+- 前端 canonical content、有效性判断、caller 与队列定向测试。
+- AGC shell 类型检查与定向 Vitest。
+- `npm run check:encoding`、`git diff --check`、必要的文档索引检查。