端到端重构创作台为 5 步 task-first Agent 创作流程

[xingbofeng]

端到端重构创作台为 5 步 task-first Agent 创作流程

1. 背景

KidMemory 桌面端的「创作台」是未来 Agent 产品形态的核心入口，但当前 Issue #2 原始提案已经落后于仓库现状：

• 仓库当前 canonical creation flow 已明确为：Compose -> Plan -> Generate -> Review -> Publish
• 仓库当前 canonical API 已明确为：/creation/tasks
• 协议和 Sidecar 当前实现方向已明确为单一 taskId 的 task-first 模型
• 旧提案中的 /creation/jobs、planId -> jobId 双身份流、以及“优先复用 books/jobs 运行时”的表述，已经不再符合当前代码库方向

因此，本 Issue 的目标不再是引入一套新的 jobs/plan 双资源模型，而是：

1. 保留原始 Issue 的产品目标：把创作台重构为 5 步 Agent 创作工作台
2. 按当前仓库事实统一为 task-first 方案
3. 补齐桌面端工作台 UI、阶段状态、预览/导出/分享体验和端到端验证
4. 清理仍残留在文档、测试、客户端或 UI 心智中的旧 jobs/dual-id 叙事

2. 最终决策

本 Issue 采用以下最终方案：

• 保留 5 步主流程，但统一到 canonical vocabulary：
  • Compose
  • Plan
  • Generate
  • Review
  • Publish
• 保留当前 KidMemory 暖色、本地优先、桌面工作台式布局方向：左侧导航、中间主工作区、右侧控制台
• 统一使用 task-first 架构：创作主路径只存在一个 taskId
• 不再引入或恢复 /creation/jobs、planId、jobId 主流程模型
• Plan 是 task 生命周期中的一个阶段，不是先创建 plan 再转成另一个 job 的独立主资源
• 当前 UI 中的中文文案可以继续保留“准备创作 / 计划确认 / 结果预览 / 导出分享”等表达，但它们必须映射到 canonical 5-stage 模型，而不能再驱动另一套独立状态体系

3. 用户故事

US1

作为用户，我希望进入创作台时只看到当前阶段真正需要完成的事情，以便我清楚知道下一步是整理需求、确认计划、等待生成、检查结果还是发布作品。

US2

作为用户，我希望创作台更像一个连续的 Agent 工作台，而不是同时堆满配置、日志、预览和导出区域的表单页。

US3

作为用户，我希望填写创作目标和选择素材后，系统先生成并展示一份可以确认的创作计划，再开始真正生成。

US4

作为用户，我希望绘本、成长纪念册和回忆视频都走真实后端 task 流程，而不是前端静态模拟。

US5

作为用户，我希望在生成中看到真实阶段、真实步骤和真实失败原因，以便理解当前卡在哪里。

US6

作为用户，我希望生成完成后能进入明确的 Review 阶段查看 PDF 或 MP4，再决定导出或分享。

US7

作为用户，我希望在创建 Web 分享链接前得到一次明确确认，以便知道作品会被上传用于分享。

US8

作为维护者，我希望创作主链路只保留一个 canonical API 和一个 canonical identity，避免旧 jobs 模型回流造成再次迁移。

4. 目标

本 Issue 要完成：

• 将当前 GenerateExportPage 收敛为一个 5 步 task-first Agent 创作工作台
• 桌面端、Sidecar、protocol、相关文档和测试统一使用 /creation/tasks
• 主流程统一使用单一 taskId
• POST /creation/tasks 负责创建任务并完成 plan 阶段
• POST /creation/tasks/{taskId}/generate 负责触发生成阶段
• GET /creation/tasks/{taskId}、events、preview、export、share 构成同一 task 生命周期的读取/动作接口
• 创作类型支持：
  • storybook
  • memory_book
  • memoir_video
• storybook / memory_book 的 Review 结果为可预览书稿，并支持导出 PDF
• memoir_video 的 Review 结果为可播放/可打开的视频制品，并支持导出 MP4
• Publish 阶段支持 Web 分享链接创建，且分享前必须用户确认
• 回忆视频流程在缺少 FFmpeg 时走现有自动处理路径，不额外弹出用户确认
• UI 保持一个连续工作台，而不是做成 11 个彼此割裂的独立页面
• 清理或更新所有仍在传播 /creation/jobs、planId、jobId 主流程心智的代码、文档、测试和客户端引用

5. 不做什么

本 Issue 不处理：

• 不恢复 /creation/jobs 兼容主路径
• 不恢复 planId -> jobId 双身份主流程
• 不为了“兼容历史提案”重新引入 books/jobs 运行时依赖
• 不新增 cloud-api 侧 Agent runtime
• 不新增独立作品库页面
• 不新增独立 Skill 市场
• 不新增独立 Hyperframes 编辑器
• 不新增 SSE / WebSocket；本轮仍可使用轮询
• 不做任务取消能力
• 不做假进度百分比
• 不在普通用户页面暴露 taskId 等技术词；仅日志/调试可见

6. 产品方案

6.1 主流程

创作台按以下 5 个主阶段组织：

1. Compose
2. Plan
3. Generate
4. Review
5. Publish

中文 UI 文案可以继续使用更自然的表达，例如：

• Compose -> 准备创作
• Plan -> 计划确认
• Generate -> 生成中
• Review -> 结果预览
• Publish -> 导出分享

但设计、状态映射、实现和验收都必须以 canonical 5-stage 模型为准。

6.2 页面布局

整体布局保持当前方向：

• Sidebar：KidMemory 现有左侧导航
• MainStage：连续创作工作流主内容
• RightPanel：当前阶段相关的设置摘要、状态摘要或动作区

6.3 信息架构原则

• Compose 阶段聚焦：目标、创作类型、素材状态、开始规划
• Plan 阶段聚焦：计划摘要、Skill、步骤、前置条件、确认生成
• Generate 阶段聚焦：真实步骤、当前状态、活动日志、失败原因
• Review 阶段聚焦：预览结果、检查质量、决定是否导出/分享
• Publish 阶段聚焦：导出结果、分享确认、分享结果

原则上不在 Compose 阶段展示大面积空预览或导出结果区，不让页面重新退化成 settings-first 工具页。

6.4 状态表达

允许存在比 5 个主阶段更细的 UI 子状态，但这些子状态必须是 同一个工作台内部的阶段细化，而不是新的顶层流程模型。

允许的典型细化示例：

• Compose：素材不足 / 可开始规划
• Plan：规划中 / 计划已生成 / 规划失败
• Generate：创建生成任务中 / 环境准备中 / 生成中 / 生成失败
• Review：PDF 预览 / MP4 预览 / 预览失败
• Publish：导出中 / 分享确认 / 分享中 / 分享完成 / 分享失败

不要求机械地维持“11 个固定状态名”作为产品主模型；核心要求是：这些状态都能在 5-stage workbench 中被清晰表达。

7. 技术方案

7.1 Canonical API

本 Issue 只认以下 task-first API：

• POST /creation/tasks
• POST /creation/tasks/{taskId}/generate
• GET /creation/tasks/{taskId}
• GET /creation/tasks/{taskId}/events
• GET /creation/tasks/{taskId}/preview
• POST /creation/tasks/{taskId}/export
• POST /creation/tasks/{taskId}/share

7.2 Identity model

创作主流程只存在一个 identity：

• taskId

明确禁止：

• 在创作主流程重新引入 planId
• 在创作主流程重新引入 jobId
• 增加 plan -> job 兼容适配层，除非后续单独出现“仍在运行的既有客户端必须兼容”的明确需求

7.3 Task lifecycle

• POST /creation/tasks：创建 task，并完成 Plan 阶段
• 任务成功返回 status: ready，失败返回 status: failed
• POST /creation/tasks/{taskId}/generate：在同一 taskId 上继续 Generate 阶段
• Review / Publish 继续复用同一 task 的详情、制品和事件流

7.4 Runtime boundary

• Sidecar 继续作为本地受信边界，负责 task 编排、任务状态、预览、导出、分享、本地依赖修复
• @kidmemory/agent-runtime 继续作为受控运行时能力，不重新把业务编排拉回旧 books/jobs 模式
• 不引入与 task-first 边界冲突的 legacy runtime 恢复动作

8. 设计要求

• 视觉风格与当前 KidMemory 桌面端一致
• 保持暖色、本地优先、亲子感、非 SaaS 紫色风
• 5 个主阶段关系清晰
• 中间态要告诉用户：当前在做什么、为什么要等待、失败后怎么办
• Review 必须成为预览和确认的主阶段，而不是生成后顺手弹出的附属区域
• Publish 必须作为最终阶段承载导出与分享，分享前必须明确确认
• 1280px、1440px、1728px 宽度下不出现布局溢出
• 低高度窗口可滚动，不出现 Flutter overflow

9. 验收标准

架构 / 协议

• Issue 端到端重构创作台为 5 步 task-first Agent 创作流程 #2 正文中的 API、类型、生命周期表述全部统一为 /creation/tasks
• 创作主流程只定义一个 identity：taskId
• Plan 被定义为 task 生命周期中的阶段，而不是独立主资源
• 不再要求恢复 /creation/jobs 或 planId/jobId 兼容主路径
• 文档、协议、客户端、测试中的创作主路径不再传播旧 jobs/dual-id 模型

Sidecar / Runtime

• 创作主流程对齐现有 task routes：create / generate / get / events / preview / export / share
• 不重新引入与 task-first 冲突的 legacy books/jobs runtime 依赖
• 视频流程缺少 FFmpeg 时仍走现有自动处理路径
• Review / Publish 所需制品与事件能在同一 task 生命周期内读取

Desktop / UX

• GenerateExportPage 被实现为连续的 5-stage workbench
• Compose / Plan / Generate / Review / Publish 在 UI 上都有清晰表达
• Compose 阶段不再展示大面积空预览或导出结果区
• Plan 阶段能展示后端返回的计划摘要、Skill、步骤和前置条件
• Generate 阶段能展示真实步骤、真实日志和真实失败原因
• Review 阶段能分别承载 PDF 或 MP4 的结果检查
• Publish 阶段能承载导出与分享确认/结果
• UI 子状态都被纳入同一个工作台，不拆成独立页面心智

验证

• 相关桌面端 widget / golden / screenshot 覆盖主要阶段与关键中间态
• 响应式宽度和低高度滚动得到验证
• 最终汇报中区分：真实外部调用、mock、静态检查、手工检查、未验证项
• Browser 优先用于本地前端 / UI 验证；仅在 Browser 不可用或不可靠时使用其他自动化路径

10. 备注

如果后续发现某个仍在使用的旧客户端必须兼容旧接口，必须单独新增 issue，明确：

• 为什么必须兼容
• 兼容层的 owner
• 兼容层的删除条件
• 为什么它不会重新把 creation 主流程拉回双模型

在没有这类明确需求之前，本 Issue 以 一个 canonical API、一个 canonical identity、一个 canonical creation runtime boundary 为完成标准。

[xingbofeng]

已按当前仓库事实把 Issue #2 收敛为最终方案，核心结论如下：

1. 保留 5 步 Agent 创作主线，但统一到 Compose -> Plan -> Generate -> Review -> Publish
2. 创作主路径统一为 /creation/tasks
3. 主流程只保留一个 identity：taskId
4. 不恢复 /creation/jobs、planId -> jobId、也不恢复与 task-first 冲突的 legacy books/jobs 运行时叙事
5. 设计上保留当前暖色、本地优先、左中右 workbench 结构，但要求把页面从 settings-first 收敛成连续的 stage-first 工作台

这版 issue 可以作为后续实现和验收的唯一依据。