新增 DirectProject 用户 Response item 契约

新增 Rust canonical user item 与 Codex wire 转换模块增加 ts-rs 绑定目录及生成文件检查边界更新聊天素材引用规范与里程碑实施计划
2026-09-15 14:45:58 +08:00
parent 9aa6f5efea
commit dfd6fadedf
12 changed files with 372 additions and 4 deletions
@@ -0,0 +1,36 @@
+# 【实施计划】DirectProject 用户 Response item 输入
+
+| 字段 | 值 |
+| --- | --- |
+| Milestone | `docs/project-memory/plans/【里程碑】DirectProject用户ResponseItem输入-2026-09-15.md` |
+| Status | ready |
+| Owner | Codex |
+
+## 修改边界
+
+- 允许修改：AGC 壳 Rust agent 输入合同、DirectProject 历史适配、前端聊天引用模型、ts-rs 生成配置、当前聊天素材文档。
+- 明确不修改：assistant 返回协议、工具 activity、附件/图片协议、SpacetimeDB、HTTP API。
+
+## 实现顺序
+
+1. 提取深模块：Rust canonical user item 的定义、校验和 Codex wire 转换。
+2. 生成并接入 ts-rs 类型，排除生成文件 lint/style。
+3. 将前端 Lexical 草稿从 `text + references[]` 改为 inline content parts。
+4. 修改 Tauri command 与 DirectProject turn：校验通过后持久化 canonical item，再发送转换后的 Codex 输入。
+5. 删除本链路对 legacy conversation 行的读取 fallback，保留标准 `response_item`。
+6. 补齐定向测试与文档验证；每个独立切片形成小提交。
+
+## 验证命令
+
+1. `cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml direct_codex`
+2. 相关前端 Vitest 与类型检查。
+3. `npm run check:encoding`
+4. `npm run check:doc-index`
+5. `git diff --check`
+
+## 风险与回滚点
+
+- ts-rs 生成路径或 workspace lint 配置不一致：先固定生成入口，再接入业务。
+- 历史中 canonical item 含 AGC part 时，thread replay 必须经过同一 wire converter；转换失败不得启动 turn。
+- 共享工作树存在用户 `.env` 修改，禁止覆盖或提交。
+- 每个切片保持独立提交，出现协议问题时按提交粒度回滚。
@@ -0,0 +1,51 @@
+# 【里程碑】DirectProject 用户 Response item 输入
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 1.0 |
+| Status | proposed |
+| Date | 2026-09-15 |
+| Parent Spec | `docs/【功能说明】AGC聊天素材引用-2026-09-08.md` |
+
+## 目标
+
+将 DirectProject 的用户消息升级为受限 Response API `message` item：文本与 AGC 引用按编辑顺序内联，Rust 校验后持久化 canonical item，并转换为 Codex 可接受的输入。
+
+## 范围
+
+- Rust 定义 user item 与 content part，并通过 `ts-rs` 生成 TypeScript 绑定。
+- 前端 Lexical 草稿生成 inline `content[]`。
+- `agc_resource_reference` 只使用稳定 `resourceId`。
+- `agc_runtime_region_reference` 保留运行区域语义摘要。
+- Rust 在持久化前完成白名单、manifest 与路径校验。
+- 现有标准 `response_item` 原样兼容；legacy conversation 行不提供 fallback。
+- 保持 assistant 返回、工具 activity、附件/图片协议不变。
+
+## 不在范围内
+
+- assistant item 前端投影或 Tauri 返回值改造。
+- 工具 item、reasoning、file change、MCP item 的 UI 模型化。
+- 附件/图片 content part。
+- SpacetimeDB schema 或 HTTP API 变更。
+
+## 依赖与前置条件
+
+- DirectProject 现有 app-server thread/inject_items/turn/start 链路。
+- 项目 manifest 作为资源身份与路径权威。
+- 现有 `project.jsonl` 的 `response_item` envelope。
+
+## 验收标准
+
+- [ ] 前端生成的 canonical user item 保留 Lexical 中文本与引用的相对顺序。
+- [ ] `agc_resource_reference` 仅包含 `resourceId`，显示信息由 manifest 派生。
+- [ ] runtime-region 字段经过 Rust 有界清洗并验证关联资源。
+- [ ] 未知 part、失效资源或非法路径在持久化前失败关闭。
+- [ ] canonical item 以 `response_item` 写入历史，标准旧 item 原样可读。
+- [ ] Codex wire input 不含 AGC 私有 part，且顺序与 canonical content 一致。
+- [ ] assistant、附件和工具链路行为无变化。
+
+## 证据要求
+
+- 自动化：Rust item 校验/转换/历史测试；前端草稿顺序与类型测试；ts-rs 生成检查。
+- 运行时：DirectProject 本地 app-server smoke（如环境可用）。
+- 边界：未知 part、资源删除、非法路径、重复提交 clientTurnId、legacy 行拒绝。