Add generation harness runtime

2026-06-21 22:31:38 +08:00
parent 7ebdfb2582
commit 459ca9edef
18 changed files with 2846 additions and 419 deletions
--- a/docs/planning/harness-stage-0-report.md
+++ b/docs/planning/harness-stage-0-report.md
@@ -0,0 +1,111 @@
+# Harness Engineering 改造阶段 0 报告
+
+**阶段**: 0 - 设计与基线  
+**日期**: 2026-06-21  
+**状态**: 已完成  
+**范围**: 技术设计、阶段拆解、最小任务、验收标准  
+
+---
+
+## 1. 本阶段目标
+
+本阶段不修改业务代码，目标是先建立 harness engineering 改造的执行基线：
+
+- 明确这次改造不是引入外部工作流引擎，也不是重写项目。
+- 确认现有统一生成工作流的能力边界。
+- 设计 Generation Harness Runtime 的目标架构。
+- 把后续工作拆成可执行、可验证、可报告的阶段。
+
+## 2. 已完成工作
+
+- 阅读并对齐现有统一生成 PRD：`docs/product/unified-generation-workflow-prd.md`
+- 阅读现有架构说明：`docs/technical/architecture.md`
+- 阅读现有 job/event 说明：`docs/technical/generation-job-state.md`
+- 阅读 Provider 路由说明：`docs/technical/provider-routing.md`
+- 检查当前生成链路实现：
+  - `backend/app/services/story_service.py`
+  - `backend/app/services/generation_jobs.py`
+  - `backend/app/services/provider_router.py`
+  - `backend/app/tasks/generation_workflow.py`
+- 检查当前关键测试：
+  - `backend/tests/test_generation_jobs.py`
+  - `backend/tests/test_stories.py`
+- 新增技术设计文档：
+  - `docs/technical/harness-engineering-modernization.md`
+
+## 3. 核心结论
+
+DreamWeaver 已经具备 harness engineering 的雏形，不需要从零开始。
+
+当前最有价值的改造路径是：
+
+1. 先抽出 harness 基础类型、trace recorder 和 execution control。
+2. 再拆资产工作流。
+3. 然后引入显式 workflow plan。
+4. 最后补 quality gates、trace analytics 和前端增量展示。
+
+第一阶段应避免大改数据库、API 和前端，先保证内部边界更清楚，并让现有测试继续通过。
+
+## 4. 发现的现状问题
+
+| 问题 | 影响 | 后续阶段 |
+| --- | --- | --- |
+| `story_service` 同时负责业务流程、事件记录、取消检查、资产补全和响应构造 | 文件职责偏重，后续扩展容易继续堆叠 | 阶段 1、2、3 |
+| event type 已经丰富，但缺少标准 step/artifact/failure category | 可观测性有数据，但分析语义还不稳定 | 阶段 1、5 |
+| Provider trace 已落库，但还没有纳入统一 runtime 语义 | 调用层和产品步骤之间缺少统一映射 | 阶段 1、5 |
+| 输出质量主要依赖 adapter 和 schema | 儿童内容质量、结构完整性和安全门还不够显式 | 阶段 4 |
+| 资产工作流 helper 已抽出一部分，但仍在 `story_service` 内 | 重试、后台补全、同步兼容路径仍有重复风险 | 阶段 2 |
+
+## 5. 阶段 1 入口标准
+
+可以进入阶段 1，入口条件已满足：
+
+- 技术设计已存在。
+- 最小任务已经拆解。
+- 阶段 1 不需要产品澄清。
+- 阶段 1 不需要数据库迁移。
+- 阶段 1 有明确验证命令。
+
+阶段 1 第一批任务：
+
+| ID | 任务 |
+| --- | --- |
+| H1-1 | 新增 `app/services/harness/__init__.py` |
+| H1-2 | 新增 `types.py` 枚举和 event type 映射 |
+| H1-3 | 新增 `trace.py` 封装 job event 写入 |
+| H1-4 | 新增 `control.py` 封装取消检查 |
+| H1-5 | 替换 `story_service` 内部 helper 实现 |
+| H1-6 | 补 `tests/test_harness_runtime.py` |
+
+## 6. 验证
+
+本阶段为文档阶段，验证方式是文档审查和路径确认。
+
+已确认：
+
+- 设计文档放在 `docs/technical/`
+- 阶段报告放在 `docs/planning/`
+- 后续阶段有明确测试命令
+- 改造策略与现有统一生成 PRD 不冲突
+
+## 7. 风险
+
+| 风险 | 等级 | 处理 |
+| --- | --- | --- |
+| 过早拆 workflow 导致行为回归 | 高 | 阶段 1 不拆主流程，只抽基础支撑件 |
+| metadata 标准化影响前端 | 中 | 只新增字段，不删除旧字段 |
+| 文档太大但实现不跟进 | 中 | 每个阶段都产出报告并更新状态 |
+
+## 8. 下一步
+
+进入阶段 1：Harness 基础类型与事件封装。
+
+优先顺序：
+
+1. 新增 harness 包和纯类型定义。
+2. 增加单测锁定 event type 到 step 的映射。
+3. 新增 trace recorder，保持旧事件行为。
+4. 新增 execution control，保持取消行为。
+5. 替换 `story_service` 内部 helper 为代理调用。
+6. 运行阶段 1 验证命令并产出阶段 1 报告。
+
--- a/docs/planning/harness-stage-1-report.md
+++ b/docs/planning/harness-stage-1-report.md
@@ -0,0 +1,122 @@
+# Harness Engineering 改造阶段 1 报告
+
+**阶段**: 1 - Harness 基础类型与事件封装  
+**日期**: 2026-06-21  
+**状态**: 已完成  
+**范围**: 后端 harness 包、标准类型、trace recorder、execution control、定向测试  
+
+---
+
+## 1. 本阶段目标
+
+本阶段目标是先建立 Generation Harness Runtime 的最低可用支撑件，不重排主生成流程，不修改数据库结构，不破坏现有 API。
+
+目标包括：
+
+- 新增标准 workflow step、artifact、failure category 类型。
+- 将现有 event type 映射到标准 step/artifact。
+- 封装 job event 写入，统一补齐标准 trace metadata。
+- 封装取消检查，保留当前安全检查点语义。
+- 增加单元测试，确保新支撑件可独立验证。
+
+## 2. 已完成工作
+
+### 新增文件
+
+- `backend/app/services/harness/__init__.py`
+- `backend/app/services/harness/types.py`
+- `backend/app/services/harness/trace.py`
+- `backend/app/services/harness/control.py`
+- `backend/tests/test_harness_runtime.py`
+
+### 修改文件
+
+- `backend/app/services/story_service.py`
+  - 保留 `_record_job_event_if_present` 和 `_stop_if_job_cancel_requested` 原函数名。
+  - 内部改为代理到 `TraceRecorder` 和 `ExecutionControl`。
+  - 将 `GenerationJobCanceledError` 移入 harness control 模块。
+
+- `backend/app/services/provider_router.py`
+  - Provider 调用事件改为通过 `TraceRecorder` 写入。
+  - 保留原有 metadata 字段，例如 capability、adapter、strategy、latency、estimated cost、error。
+
+- `docs/technical/harness-engineering-modernization.md`
+  - 更新阶段 1 状态。
+
+## 3. 行为兼容性
+
+本阶段采用“只新增标准字段，不删除旧字段”的策略。
+
+新增写入到 `generation_job_events.event_metadata` 的标准字段包括：
+
+- `step`
+- `artifact`
+- `failure_category`
+- `retryable`
+- `blocks_main_result`
+
+现有事件顺序、event type、status、message 和既有 metadata 字段保持兼容。
+
+## 4. 验证结果
+
+已执行：
+
+```bash
+cd backend
+.venv/bin/python -m pytest tests/test_harness_runtime.py tests/test_generation_jobs.py
+.venv/bin/python -m ruff check app tests
+```
+
+结果：
+
+- `24 passed`
+- `ruff`: `All checks passed!`
+
+覆盖到的关键行为：
+
+- event type 到标准 workflow step 的映射。
+- event type 到 artifact 的映射。
+- trace metadata 不丢失旧字段。
+- TraceRecorder 能写入标准 metadata。
+- job 为 `None` 时 TraceRecorder 安全跳过。
+- ExecutionControl 能在 `cancel_requested` checkpoint 将 job 收敛为 `canceled`。
+- 现有 generation job、取消、重试、Provider 统计测试继续通过。
+
+## 5. 自审结论
+
+本阶段改动符合阶段 1 设计：
+
+- 没有引入外部框架。
+- 没有修改数据库迁移。
+- 没有修改 API schema。
+- 没有重排现有生成 workflow。
+- 没有删除旧 metadata 字段。
+- `story_service` 仍保留旧 helper 入口，降低后续阶段风险。
+
+## 6. 已知限制
+
+- 当前只有通过 `TraceRecorder` 写入的事件会自动带标准 metadata。直接调用 `record_generation_event` 的旧代码路径暂未全量迁移。
+- `failure_category` 目前只在显式传入时有具体值，Provider 错误自动分类留到后续阶段。
+- `AssetCompletionResult` 仍在 `story_service.py`，资产工作流拆分留到阶段 2。
+- `WorkflowPlan` 和执行器尚未实现，阶段 1 只完成运行时支撑件。
+
+## 7. 风险与处理
+
+| 风险 | 等级 | 当前处理 |
+| --- | --- | --- |
+| 新 metadata 影响前端 | 低 | 只新增字段，不删除字段 |
+| 取消语义回归 | 低 | `tests/test_generation_jobs.py` 已通过 |
+| Provider 聚合误算 | 低 | Provider 统计测试已通过 |
+| 直接调用 `record_generation_event` 的路径未标准化 | 中 | 后续阶段逐步迁移或在底层统一补齐 |
+
+## 8. 下一阶段建议
+
+进入阶段 2：资产工作流边界抽取。
+
+建议先做最小切片：
+
+1. 将 `AssetCompletionResult` 移到 harness 或 artifact workflow 模块，并保留兼容 import。
+2. 抽普通故事封面补全工作流，保持测试不变。
+3. 抽音频补全工作流，先覆盖缓存命中、生成成功、生成失败。
+4. 最后抽绘本图片工作流，因为它涉及并发生成和逐页事件顺序，风险略高。
+
--- a/docs/planning/harness-stage-2-report.md
+++ b/docs/planning/harness-stage-2-report.md
@@ -0,0 +1,121 @@
+# Harness Engineering 改造阶段 2 报告
+
+**阶段**: 2 - 资产工作流边界抽取  
+**日期**: 2026-06-21  
+**状态**: 已完成主要目标  
+**范围**: 封面、音频、持久化绘本缺失图片补全工作流抽取  
+
+---
+
+## 1. 本阶段目标
+
+本阶段目标是将资产补全职责从 `story_service.py` 中抽出，迁入 harness runtime 的 artifact workflow 层，同时保留原有函数签名和外部行为。
+
+阶段 2 不修改数据库结构，不修改 API schema，不改变前端行为。
+
+## 2. 已完成工作
+
+### 新增和扩展文件
+
+- `backend/app/services/harness/artifacts.py`
+  - 新增 `AssetCompletionResult`
+  - 新增 `asset_result_metadata`
+
+- `backend/app/services/harness/asset_workflows.py`
+  - 新增 `complete_cover_image_asset`
+  - 新增 `read_cached_audio_asset`
+  - 新增 `complete_audio_asset`
+  - 新增 `get_storybook_pages_data`
+  - 新增 `build_storybook_error_message`
+  - 新增 `resolve_storybook_image_status`
+  - 新增 `complete_storybook_image_assets`
+
+### 修改文件
+
+- `backend/app/services/story_service.py`
+  - 移除本地 `AssetCompletionResult` 定义，改为从 harness artifacts 引入。
+  - `_complete_cover_image_asset` 改为代理到 harness asset workflow。
+  - `_read_cached_audio_asset` 改为代理到 harness asset workflow。
+  - `_complete_audio_asset` 改为代理到 harness asset workflow。
+  - `_complete_storybook_image_assets` 改为代理到 harness asset workflow。
+  - 绘本错误信息和图片状态推导 helper 改为代理到 harness asset workflow。
+
+## 3. 行为兼容性
+
+本阶段保留了 `story_service.py` 内原有私有 helper 名称，因此调用方不需要调整。
+
+保持兼容的行为包括：
+
+- 普通故事封面生成成功和失败语义。
+- 封面失败时主内容仍可读，并进入可重试状态。
+- 音频缓存命中、缓存缺失修复、TTS 成功和 TTS 失败语义。
+- 音频失败时可选择阻塞或非阻塞，取决于 `raise_on_failure`。
+- 持久化绘本缺失封面/分页插图补全语义。
+- 绘本逐页图片事件和完成事件 metadata。
+- `retryable_assets` 行为。
+
+## 4. 验证结果
+
+已执行：
+
+```bash
+cd backend
+.venv/bin/python -m pytest tests/test_harness_runtime.py tests/test_generation_jobs.py tests/test_stories.py tests/test_audio_cache.py
+.venv/bin/python -m ruff check app tests
+```
+
+结果：
+
+- `72 passed`
+- `ruff`: `All checks passed!`
+
+覆盖到的关键行为：
+
+- 统一生成 job 队列和 worker 持久化。
+- 资产重试 job 事件。
+- 普通故事封面生成与重试。
+- 绘本分页图片重试。
+- 音频缓存、生成、失败和清理。
+- Provider 调用事件和聚合。
+- job 取消、重试和卡住任务收敛。
+
+## 5. 自审结论
+
+本阶段符合设计目标：
+
+- 资产补全职责已从 `story_service` 主体中显著抽离。
+- 外部 API 和数据库模型未变。
+- 当前主要测试通过。
+- harness 层开始承载 artifact workflow，但仍通过依赖注入函数调用 Provider 和文件缓存，便于测试与后续替换。
+
+## 6. 保留到后续阶段的内容
+
+首次绘本生成前的并发图片生成函数 `_generate_storybook_image_assets` 仍保留在 `story_service.py`。
+
+保留原因：
+
+- 它发生在绘本主记录持久化之前。
+- 它与“生成绘本结构 -> 可选并发生成图片 -> 持久化故事”的执行计划强相关。
+- 更适合在阶段 3 引入 `WorkflowPlan` 时一起整理，而不是在阶段 2 单独迁移。
+
+## 7. 风险与处理
+
+| 风险 | 等级 | 当前处理 |
+| --- | --- | --- |
+| 资产工作流迁移改变事件顺序 | 低 | generation job 和 story 测试已通过 |
+| 音频缓存修复逻辑回归 | 低 | `test_audio_cache.py` 已通过 |
+| 绘本图片补全状态误判 | 低 | 绘本重试测试已通过 |
+| 首次绘本并发图片仍在 service 内 | 中 | 阶段 3 处理 |
+
+## 8. 下一阶段建议
+
+进入阶段 3：Workflow Plan 与执行器。
+
+建议切片：
+
+1. 定义 `WorkflowPlan`、`WorkflowTask` 和模式枚举，不接入主流程。
+2. 为普通故事、完整故事、绘本、资产任务生成 plan 快照测试。
+3. 将 `_generate_generation_service_with_job` 的分支逐步迁移到 plan 构建。
+4. 处理首次绘本并发图片生成，把它纳入 storybook plan 的 asset step。
+5. 保持 `/api/generations` 和现有 job event 顺序兼容。
+
--- a/docs/planning/harness-stage-3-report.md
+++ b/docs/planning/harness-stage-3-report.md
@@ -0,0 +1,121 @@
+# Harness Engineering 改造阶段 3 报告
+
+**阶段**: 3 - Workflow Plan 与执行器  
+**日期**: 2026-06-21  
+**状态**: 已完成计划建模基线，执行器接管未启用  
+**范围**: 纯 WorkflowPlan 建模、计划快照测试  
+
+---
+
+## 1. 本阶段目标
+
+阶段 3 的完整目标是引入显式 `WorkflowPlan`，逐步减少 `_generate_generation_service_with_job` 中的分支逻辑。
+
+本次完成了最小安全切片：
+
+- 定义 plan 类型和 task 类型。
+- 为普通故事、带封面故事、绘本、资产任务生成计划。
+- 用快照测试锁定计划形状。
+- 暂不改变实际执行流，避免事件顺序和前端时间线发生非必要变化。
+
+## 2. 已完成工作
+
+### 新增文件
+
+- `backend/app/services/harness/plans.py`
+
+### 新增能力
+
+- `WorkflowMode`
+  - `story`
+  - `story_with_assets`
+  - `storybook`
+  - `asset_generation`
+  - `asset_retry`
+
+- `WorkflowTask`
+  - `key`
+  - `step`
+  - `artifact`
+  - `required`
+  - `recoverable`
+
+- `WorkflowPlan`
+  - `mode`
+  - `tasks`
+  - `to_snapshot()`
+
+- plan builder
+  - `build_story_plan(generate_images=...)`
+  - `build_storybook_plan(generate_images=...)`
+  - `build_asset_plan(output_mode=..., assets=...)`
+
+### 修改文件
+
+- `backend/tests/test_harness_runtime.py`
+  - 增加普通故事计划快照。
+  - 增加带封面故事计划快照。
+  - 增加绘本带图片计划快照。
+  - 增加资产重试计划去重测试。
+
+## 3. 为什么没有接入执行器
+
+本阶段有意没有新增运行时事件，例如 `workflow_planned`，也没有让 plan 接管 `_generate_generation_service_with_job`。
+
+原因：
+
+- 新 event type 会改变前端生成轨迹时间线，需要同步前端 label 和 progress 映射。
+- 当前生成 job 测试已经严格断言事件顺序。
+- 直接接管执行器会同时触碰 story、storybook、asset_generation、asset_retry 四条路径，风险偏高。
+- 先稳定 plan snapshot，可以让后续迁移按任务级别逐步推进。
+
+## 4. 验证结果
+
+已执行：
+
+```bash
+cd backend
+.venv/bin/python -m pytest tests/test_harness_runtime.py tests/test_generation_jobs.py
+.venv/bin/python -m ruff check app tests
+```
+
+结果：
+
+- `28 passed`
+- `ruff`: `All checks passed!`
+
+阶段 3 的计划建模未改变业务执行流，因此完整后端行为仍由阶段 2 的完整测试结果兜底。
+
+## 5. 自审结论
+
+本阶段符合“小步可验证”原则：
+
+- 新增模块不依赖数据库、FastAPI 或 Provider。
+- plan 只描述 workflow 形状，不执行副作用。
+- 所有任务均可 JSON snapshot，后续可写入 trace metadata 或用于执行器。
+- 没有影响现有 API、job event 顺序或前端。
+
+## 6. 保留到后续的内容
+
+| 内容 | 建议处理 |
+| --- | --- |
+| 执行器接管 `_generate_generation_service_with_job` | 分 story、storybook、asset 三次迁移 |
+| 首次绘本生成前并发图片生成 | 跟 storybook plan 的 image task 一起迁移 |
+| `workflow_planned` 事件 | 等前端 label 和 progress 映射准备好后再加入 |
+| plan 与 trace metadata 关联 | 先在 execution context 内部使用，再决定是否落库 |
+
+## 7. 下一阶段建议
+
+下一步有两条可选路线：
+
+1. **继续阶段 3B：执行器小步接管**
+   - 先让普通故事不带图片路径使用 plan。
+   - 再迁移普通故事带图片路径。
+   - 最后迁移绘本和资产任务。
+
+2. **进入阶段 4：Quality Gates**
+   - 在不改变执行器的前提下，为 Provider 输出增加确定性校验。
+   - 这条路线风险更低，对儿童内容质量收益更直接。
+
+建议优先做阶段 4 的低风险质量门，然后再回来做阶段 3B 的执行器迁移。
+
--- a/docs/planning/harness-stage-4-report.md
+++ b/docs/planning/harness-stage-4-report.md
@@ -0,0 +1,140 @@
+# Harness Engineering 改造阶段 4 报告
+
+**阶段**: 4 - Quality Gates 与输出验证  
+**日期**: 2026-06-21  
+**状态**: 已完成确定性质量门  
+**范围**: 文本故事和绘本结构输出校验、质量门失败事件、测试验证  
+
+---
+
+## 1. 本阶段目标
+
+阶段 4 的目标是在 Provider 输出进入持久化之前增加低成本、确定性的质量门。
+
+本阶段不调用额外 AI 模型，不增加外部服务成本，只做结构完整性和明显儿童安全风险检查。
+
+## 2. 已完成工作
+
+### 新增文件
+
+- `backend/app/services/harness/quality_gates.py`
+
+### 新增能力
+
+- `QualityGateCode`
+  - `missing_title`
+  - `missing_story_text`
+  - `missing_cover_prompt`
+  - `missing_storybook_page`
+  - `invalid_storybook_page_number`
+  - `missing_storybook_page_text`
+  - `unsafe_child_content`
+
+- `QualityGateIssue`
+  - 稳定 code
+  - 中文 message
+  - `failure_category`
+  - field
+
+- `QualityGateError`
+  - 聚合多个 issue
+  - 可输出 JSON-safe metadata
+
+- `validate_story_output`
+  - 检查标题
+  - 检查正文
+  - 检查封面 prompt
+  - 检查明显不适合 3-8 岁儿童的风险词
+
+- `validate_storybook_output`
+  - 检查标题
+  - 检查至少一页
+  - 检查页码有效且不重复
+  - 检查每页正文
+  - 检查明显不适合 3-8 岁儿童的风险词
+
+### 修改文件
+
+- `backend/app/services/story_service.py`
+  - 文本故事 Provider 输出后、持久化前执行 `validate_story_output`。
+  - 绘本 Provider 输出后、图片生成和持久化前执行 `validate_storybook_output`。
+  - 质量门失败会写入 `quality_gate_failed` job event。
+  - 质量门失败不会落库故事主记录。
+
+- `backend/app/services/harness/types.py`
+  - `quality_gate_failed` 映射到 `narrative_generation` step。
+  - `quality_gate_failed` 映射到 `story_text` artifact。
+
+- `backend/tests/test_harness_runtime.py`
+  - 增加质量门纯函数测试。
+
+- `backend/tests/test_generation_jobs.py`
+  - 增加 worker 质量门失败测试，确认 story 不落库、job failed、事件可解释。
+
+## 3. 行为语义
+
+质量门失败属于生成失败，而不是降级完成。
+
+原因：
+
+- 文本故事正文或绘本页结构是 blocking artifact。
+- 如果主内容本身不合格，系统不能保存为可读故事。
+- 图片、音频等 recoverable artifact 失败仍按原有 `degraded_completed` 或可重试逻辑处理。
+
+## 4. 验证结果
+
+已执行：
+
+```bash
+cd backend
+.venv/bin/python -m pytest tests/test_harness_runtime.py tests/test_generation_jobs.py
+.venv/bin/python -m ruff check app tests
+.venv/bin/python -m pytest
+```
+
+结果：
+
+- 定向测试：`33 passed`
+- 完整后端测试：`138 passed`
+- `ruff`: `All checks passed!`
+
+覆盖到的关键行为：
+
+- 质量门接受完整、安全的儿童故事。
+- 质量门拒绝空正文。
+- 质量门拒绝明显不适合儿童的风险词。
+- 质量门拒绝绘本重复页码。
+- worker 中质量门失败会写入 `quality_gate_failed`。
+- 质量门失败不会持久化 story。
+- 现有所有后端测试继续通过。
+
+## 5. 自审结论
+
+本阶段符合设计目标：
+
+- 没有引入额外 AI 调用。
+- 没有引入新依赖。
+- 没有改变 API schema。
+- 没有改变图片、音频资产失败降级语义。
+- 对儿童内容质量和结构完整性有了第一层确定性保护。
+
+## 6. 已知限制
+
+| 限制 | 后续建议 |
+| --- | --- |
+| 儿童安全词表很保守，只覆盖明显风险词 | 后续可接入可配置词表或轻量安全审核 Provider |
+| 当前 `quality_gate_failed` artifact 固定映射到 `story_text` | 后续可根据 story/storybook mode 写入更精确 artifact |
+| 质量门失败文案目前偏技术 | 后续可为前端增加更友好的用户提示 |
+| 未做模型评审式质量评分 | 先保留，避免增加成本和不稳定性 |
+
+## 7. 下一阶段建议
+
+进入阶段 5：Trace Analytics 与前端增量展示。
+
+建议切片：
+
+1. 后端 Provider/Job 聚合支持 `failure_category` 统计。
+2. 前端生成轨迹显示 `step` 和 `artifact` 的中文标签。
+3. 管理端 Provider dashboard 展示 failure category 聚合。
+4. 更新 smoke 脚本检查标准 metadata。
+
--- a/docs/technical/harness-engineering-modernization.md
+++ b/docs/technical/harness-engineering-modernization.md
@@ -0,0 +1,493 @@
+# Harness Engineering 架构改造技术设计
+
+**项目**: DreamWeaver 梦语织机  
+**版本**: 0.1  
+**日期**: 2026-06-21  
+**状态**: 阶段 0 已建立设计基线  
+**作者**: Codex  
+
+---
+
+## 1. 背景
+
+DreamWeaver 当前已经完成统一生成工作流的第一轮落地：`POST /api/generations` 会创建 `generation_jobs`，后台 worker 执行故事或绘本生成，`generation_job_events` 记录关键过程，前端通过 job 查询和故事状态展示进度、失败与重试入口。
+
+现有架构已经具备 harness engineering 的雏形：
+
+- `story_service` 负责上下文准备、主内容生成、故事落库、资产补全、状态同步和任务收敛。
+- `generation_jobs` 负责 job/event、进度摘要、取消、重试和 Provider 聚合。
+- `provider_router` 负责 Provider 选择、failover、熔断、成本和调用事件。
+- `story_status` 负责把文本、图片、音频状态推导为统一故事状态。
+
+当前主要问题不是缺少能力，而是生成运行时控制逻辑分散在多个 service 内。取消检查、事件记录、资产恢复、Provider 轨迹、失败分类和质量校验还没有形成显式的运行时边界。
+
+本设计的目标，是把现有“隐性 harness”升级为可观测、可恢复、可验证、可演进的 Generation Harness Runtime，同时保留当前 API、数据库和前端主行为。
+
+## 2. 目标
+
+### 2.1 产品目标
+
+- 家长提交故事或绘本生成后，能获得稳定、可解释、可恢复的结果。
+- 主内容生成成功后，即使图片或音频失败，也不影响阅读。
+- 用户能清楚看到任务步骤、失败原因和可重试资产。
+- 后续新增语音共创、更多内容模式或新资产类型时，复用同一套运行时模型。
+
+### 2.2 工程目标
+
+- 把 `story_service` 中的运行时控制职责抽到 harness 层。
+- 让 workflow step、artifact、trace、failure category 成为一等概念。
+- 保持 `/api/generations`、旧兼容接口、现有状态字段和主要测试行为不破坏。
+- 优先做渐进式重构，不引入复杂工作流引擎，不进行大爆炸重写。
+- 每个大阶段都产出阶段报告，包含实现、审查、验证和风险。
+
+### 2.3 非目标
+
+- 本轮不引入 Temporal、Dagster、LangGraph 等外部工作流引擎。
+- 本轮不彻底重做数据库结构。
+- 本轮不废弃旧生成接口，只继续保持兼容层指向统一入口。
+- 本轮不把 DreamWeaver 抽象成通用 agent 平台，所有抽象必须服务儿童故事生成业务。
+- 本轮不要求一次性完成所有 eval、质量门和 replay 能力。
+
+## 3. 架构原则
+
+1. **主内容优先可读**  
+   文本故事或绘本结构是 blocking artifact；封面、分页插图、音频是 recoverable artifact。
+
+2. **API 稳定优先**  
+   先重构内部边界，再考虑扩展响应字段。现有前端、smoke、测试不应被第一阶段打断。
+
+3. **事件结构稳定**  
+   继续复用 `generation_job_events`，但逐步标准化 metadata，避免每个调用点随手定义不同结构。
+
+4. **Provider 不等于产品能力**  
+   Provider 只是 tool invocation 的实现。产品能力应由 capability、workflow step、artifact 和 recovery policy 共同定义。
+
+5. **小步可验证**  
+   每个最小任务都必须能通过单测、局部测试或文档审查验证。
+
+## 4. 目标架构
+
+```mermaid
+flowchart TB
+  API["FastAPI API 层"] --> COMMAND["Generation Command"]
+  COMMAND --> HARNESS["Generation Harness Runtime"]
+
+  HARNESS --> CTX["Context Builder<br/>档案 / 宇宙 / 记忆 / 输入规范化"]
+  HARNESS --> PLAN["Workflow Plan<br/>story / storybook / asset_generation / asset_retry"]
+  HARNESS --> CONTROL["Execution Control<br/>取消 / 超时收敛 / 安全检查点"]
+  HARNESS --> TRACE["Trace Recorder<br/>job events / step metadata / provider trace"]
+  HARNESS --> ARTIFACT["Artifact Workflows<br/>story_text / storybook_pages / image / audio"]
+  HARNESS --> GUARD["Quality Gates<br/>schema / 儿童安全 / 内容完整性"]
+
+  ARTIFACT --> ROUTER["Provider Router<br/>策略 / failover / 熔断 / 成本"]
+  ROUTER --> ADAPTERS["Provider Adapters"]
+  HARNESS --> STATE["State Store<br/>stories / generation_jobs / generation_job_events"]
+  STATE --> FE["Vue 前端进度 / 详情 / 重试"]
+```
+
+## 5. 运行时核心概念
+
+### 5.1 Generation Command
+
+表示一次用户意图，来源包括：
+
+- `POST /api/generations`
+- `POST /api/generations/{story_id}/retry-assets`
+- `POST /api/generations/jobs/{job_id}/retry`
+- 旧兼容接口产生的同步生成调用
+
+标准字段：
+
+| 字段 | 说明 |
+| --- | --- |
+| `output_mode` | `story`、`storybook`、`asset_generation`、`asset_retry` |
+| `input_type` | `keywords`、`full_story`、`image`、`audio` 或资产组合 |
+| `user_id` | 当前用户 |
+| `story_id` | 已有故事 ID，可为空 |
+| `request_payload` | 原始请求的 JSON 安全快照 |
+
+### 5.2 Workflow Step
+
+第一阶段先将现有 event type 映射为标准 step，不立即改库：
+
+| Step | 当前事件 | 是否阻塞主内容 |
+| --- | --- | --- |
+| `request_acceptance` | `request_accepted`、`retry_queued` | 是 |
+| `worker_start` | `worker_started` | 是 |
+| `context_preparation` | `context_prepared` | 是 |
+| `narrative_generation` | `narrative_generated` | 是 |
+| `story_persistence` | `story_saved` | 是 |
+| `image_generation` | `cover_image_*`、`storybook_*image*` | 否 |
+| `audio_generation` | `audio_*` | 否 |
+| `postprocessing` | `postprocessing_queued` | 否 |
+| `completion` | `generation_completed`、`asset_*_completed` | 是 |
+| `cancellation` | `cancel_requested`、`generation_canceled` | 是 |
+| `stale_recovery` | `generation_stale_failed` | 是 |
+
+### 5.3 Artifact
+
+| Artifact | 来源 | 状态字段 | 恢复策略 |
+| --- | --- | --- | --- |
+| `story_text` | text provider | `text_status` | 失败则 job failed |
+| `storybook_pages` | storybook provider | `text_status` | 失败则 job failed |
+| `cover_image` | image provider | `image_status` | 失败后 `degraded_completed`，可重试 |
+| `page_image` | image provider | `image_status` | 部分页失败后 `degraded_completed`，可重试 |
+| `audio` | tts provider + file cache | `audio_status` | 失败后 `degraded_completed`，可重试 |
+| `achievement_memory` | Celery 后处理 | 事件记录 | 失败不影响主内容 |
+
+### 5.4 Failure Category
+
+第一阶段先在代码中定义枚举和 metadata 规范；后续逐步写入事件：
+
+| Category | 说明 |
+| --- | --- |
+| `provider_error` | 外部 Provider 返回失败或不可用 |
+| `schema_error` | Provider 输出无法解析或字段不完整 |
+| `safety_error` | 儿童安全或内容安全校验失败 |
+| `timeout` | 调用超时或 job 超时 |
+| `canceled` | 用户取消 |
+| `stale_job` | 后台任务卡住后被系统收敛 |
+| `storage_error` | 数据库、文件缓存或持久化失败 |
+| `validation_error` | 用户输入、档案或宇宙校验失败 |
+| `unknown_error` | 未归类错误 |
+
+### 5.5 Trace Metadata
+
+标准 event metadata 应逐步包含：
+
+```json
+{
+  "step": "narrative_generation",
+  "artifact": "story_text",
+  "capability": "text",
+  "adapter": "demo",
+  "provider_id": null,
+  "strategy": "priority",
+  "latency_ms": 42,
+  "estimated_cost_usd": 0.01,
+  "failure_category": null,
+  "error": null,
+  "retryable": false,
+  "blocks_main_result": true
+}
+```
+
+短期兼容要求：
+
+- 不删除现有 metadata 字段。
+- 新增字段必须向后兼容。
+- 前端仍可使用当前 `event_type`、`status`、`message`、`event_metadata`。
+
+## 6. 模块设计
+
+### 6.1 `app/services/harness/types.py`
+
+新增纯类型模块，不依赖数据库。
+
+职责：
+
+- 定义 `WorkflowStep`
+- 定义 `ArtifactKind`
+- 定义 `FailureCategory`
+- 定义 `StepStatus`
+- 定义 `TraceMetadata`
+- 定义从旧 event type 到标准 step 的映射函数
+
+验收：
+
+- 单测覆盖 event type 到 step 的映射。
+- 未知 event type 映射到 `unknown` 或保守默认，不抛出非预期异常。
+
+### 6.2 `app/services/harness/trace.py`
+
+封装 job event 写入。
+
+职责：
+
+- 提供 `TraceRecorder.record_step(...)`
+- 提供 `TraceRecorder.record_provider_call(...)`
+- 统一补齐 `step`、`artifact`、`failure_category`、`retryable`、`blocks_main_result`
+- 内部继续调用现有 `record_generation_event`
+
+验收：
+
+- 现有 `generation_job_events` 行为保持。
+- 新事件 metadata 含标准字段。
+- job 为空时安全跳过，兼容旧同步接口。
+
+### 6.3 `app/services/harness/control.py`
+
+封装执行控制。
+
+职责：
+
+- 提供 `ExecutionControl.stop_if_cancel_requested(...)`
+- 保留现有取消语义和 `GenerationJobCanceledError`
+- 后续可扩展 step timeout、checkpoint、stale recovery
+
+验收：
+
+- 取消中的 job 仍被标记为 `canceled`。
+- 现有取消测试继续通过。
+
+### 6.4 `app/services/harness/artifacts.py`
+
+第二阶段再拆。第一阶段先保留 `story_service` 中的资产函数，只把共享结果类型移动或桥接。
+
+职责：
+
+- 表达 `AssetCompletionResult`
+- 后续承载封面、绘本插图、音频工作流
+
+验收：
+
+- 资产重试行为不变。
+- `retryable_assets` 行为不变。
+
+### 6.5 `story_service` 改造方式
+
+第一阶段仅做低风险替换：
+
+- `_record_job_event_if_present` 代理到 `TraceRecorder`
+- `_stop_if_job_cancel_requested` 代理到 `ExecutionControl`
+- `AssetCompletionResult` 可先留在原文件，第二阶段再移动
+- 不重写 `generate_generation_service`、`run_generation_job_service` 主流程
+
+第二阶段再拆分：
+
+- `story_generation_workflow.py`
+- `storybook_generation_workflow.py`
+- `asset_generation_workflow.py`
+- `asset_retry_workflow.py`
+
+## 7. 阶段计划
+
+### 阶段 0: 设计与基线
+
+目标：
+
+- 产出本技术设计。
+- 产出阶段 0 报告。
+- 明确阶段拆解、验收标准和验证方式。
+
+最小任务：
+
+| ID | 任务 | 验收 |
+| --- | --- | --- |
+| H0-1 | 梳理现有统一生成 PRD、架构文档和测试 | 文档引用现有边界，不重复设计入口 |
+| H0-2 | 定义目标 runtime 架构 | 技术设计包含模块、数据、阶段计划 |
+| H0-3 | 拆分最小可执行任务 | 每个阶段有任务 ID 和验收标准 |
+| H0-4 | 建立阶段报告机制 | `docs/planning/` 下有阶段报告 |
+
+### 阶段 1: Harness 基础类型与事件封装
+
+目标：
+
+- 新增 harness 包。
+- 标准化 workflow step、artifact、failure category。
+- 用 `TraceRecorder` 封装事件写入。
+- 用 `ExecutionControl` 封装取消检查。
+
+最小任务：
+
+| ID | 任务 | 验收 |
+| --- | --- | --- |
+| H1-1 | 新增 `app/services/harness/__init__.py` | 后端 import 正常 |
+| H1-2 | 新增 `types.py` 枚举和映射 | 单测覆盖核心 event type |
+| H1-3 | 新增 `trace.py` | record 后 metadata 含 `step` |
+| H1-4 | 新增 `control.py` | 取消行为与旧逻辑一致 |
+| H1-5 | 替换 `story_service` 中事件和取消 helper 的内部实现 | 现有 API 行为不变 |
+| H1-6 | 补 `tests/test_harness_runtime.py` | 后端测试通过 |
+
+验证命令：
+
+```bash
+cd backend
+pytest tests/test_harness_runtime.py tests/test_generation_jobs.py
+ruff check app tests
+```
+
+阶段报告：
+
+- `docs/planning/harness-stage-1-report.md`
+
+### 阶段 2: 资产工作流边界抽取
+
+目标：
+
+- 将封面、绘本插图、音频补全从 `story_service` 中拆成 artifact workflow。
+- 保持当前 `StoryAssetStatus` 和 `sync_story_status` 语义。
+
+最小任务：
+
+| ID | 任务 | 验收 |
+| --- | --- | --- |
+| H2-1 | 移动或桥接 `AssetCompletionResult` | import 稳定 |
+| H2-2 | 抽普通故事封面工作流 | 封面生成、失败、重试测试通过 |
+| H2-3 | 抽绘本图片工作流 | 绘本逐页事件顺序不破坏 |
+| H2-4 | 抽音频工作流 | 音频缓存和失败状态测试通过 |
+| H2-5 | 补 artifact workflow 单测 | 资产相关测试通过 |
+
+验证命令：
+
+```bash
+cd backend
+pytest tests/test_stories.py tests/test_generation_jobs.py tests/test_audio_cache.py
+ruff check app tests
+```
+
+阶段报告：
+
+- `docs/planning/harness-stage-2-report.md`
+
+### 阶段 3: Workflow Plan 与执行器
+
+目标：
+
+- 用显式 `WorkflowPlan` 表达 story、storybook、asset_generation、asset_retry。
+- 将 `_generate_generation_service_with_job` 的分支压缩到计划构建和执行器。
+
+最小任务：
+
+| ID | 任务 | 验收 |
+| --- | --- | --- |
+| H3-1 | 定义 `WorkflowPlan` 和 `WorkflowTask` | 不依赖 FastAPI schema |
+| H3-2 | 为普通故事构建 plan | 不生成图片时步骤正确 |
+| H3-3 | 为完整故事构建 plan | 图片为 recoverable step |
+| H3-4 | 为绘本构建 plan | 绘本结构和图片步骤可区分 |
+| H3-5 | 为资产任务构建 plan | 重试和后台生成共用计划 |
+| H3-6 | 增加 plan 单测 | 核心模式计划快照稳定 |
+
+验证命令：
+
+```bash
+cd backend
+pytest tests/test_harness_runtime.py tests/test_generation_jobs.py tests/test_stories.py
+ruff check app tests
+```
+
+阶段报告：
+
+- `docs/planning/harness-stage-3-report.md`
+
+### 阶段 4: Quality Gates 与输出验证
+
+目标：
+
+- 在 Provider 输出进入持久化之前，加入低成本、确定性的质量门。
+- 后续可扩展模型评审，但第一轮避免额外 AI 成本。
+
+最小任务：
+
+| ID | 任务 | 验收 |
+| --- | --- | --- |
+| H4-1 | 定义 quality gate 接口 | 不绑定具体 Provider |
+| H4-2 | 文本故事完整性检查 | 标题、正文、封面 prompt 缺失可识别 |
+| H4-3 | 绘本结构检查 | 页数、页码、正文、图片 prompt 可识别 |
+| H4-4 | 儿童内容基础安全检查 | 明显不适龄词或空内容阻断 |
+| H4-5 | gate 失败写入 `failure_category` | job event 可解释 |
+
+验证命令：
+
+```bash
+cd backend
+pytest tests/test_harness_runtime.py tests/test_generation_jobs.py tests/test_stories.py
+ruff check app tests
+```
+
+阶段报告：
+
+- `docs/planning/harness-stage-4-report.md`
+
+### 阶段 5: Trace Analytics 与前端增量展示
+
+目标：
+
+- 前端继续消费现有 job/event，但可展示标准 step、artifact、failure category。
+- 管理端可按 failure category 聚合失败原因。
+
+最小任务：
+
+| ID | 任务 | 验收 |
+| --- | --- | --- |
+| H5-1 | 后端聚合支持标准 step/failure category | 旧字段兼容 |
+| H5-2 | 用户端生成轨迹展示 step 名称 | 移动端不溢出 |
+| H5-3 | 管理端 Provider dashboard 增加 failure category | 构建通过 |
+| H5-4 | 更新 smoke 脚本校验标准 metadata | demo smoke 通过 |
+
+验证命令：
+
+```bash
+cd backend
+pytest
+ruff check app tests
+cd ../frontend
+npm run build
+cd ../admin-frontend
+npm run build
+```
+
+阶段报告：
+
+- `docs/planning/harness-stage-5-report.md`
+
+## 8. 需求与验收
+
+### 功能需求
+
+| ID | 优先级 | 需求 | 验收标准 |
+| --- | --- | --- | --- |
+| FR-001 | MUST | 系统必须保留统一生成 API 行为 | `/api/generations` 测试继续通过 |
+| FR-002 | MUST | 系统必须有标准 workflow step 类型 | 核心 event type 可映射到 step |
+| FR-003 | MUST | 系统必须有标准 artifact 类型 | story、storybook、image、audio 可区分 |
+| FR-004 | MUST | 系统必须标准化 job event metadata | 新事件含 `step`，旧字段不删除 |
+| FR-005 | MUST | 用户取消语义必须保持 | 取消测试继续通过 |
+| FR-006 | SHOULD | Provider 调用应记录标准 trace 字段 | provider event 含 capability、adapter、latency、cost、step |
+| FR-007 | SHOULD | 资产工作流应从主 service 拆出 | `story_service` 行数和职责减少 |
+| FR-008 | SHOULD | 输出验证应在持久化前执行 | schema 缺失可被测试捕获 |
+| FR-009 | COULD | 前端展示标准 step/failure category | 构建通过且无布局溢出 |
+
+### 非功能需求
+
+| ID | 优先级 | 需求 | 验收标准 |
+| --- | --- | --- | --- |
+| NFR-001 | MUST | 向后兼容 | 现有测试和 smoke 主链路不破坏 |
+| NFR-002 | MUST | 可测试 | 每个新增 harness 模块有单测 |
+| NFR-003 | MUST | 可观测 | job/event 可以解释 step、artifact、失败原因 |
+| NFR-004 | SHOULD | 低耦合 | harness 类型模块不依赖 FastAPI 和 SQLAlchemy |
+| NFR-005 | SHOULD | 性能稳定 | 不新增阻塞式外部调用 |
+| NFR-006 | SHOULD | 中文一致性 | 文档、用户可见文案和新增注释使用简体中文 |
+
+## 9. 风险与缓解
+
+| 风险 | 影响 | 缓解 |
+| --- | --- | --- |
+| 过度抽象导致改造变慢 | 中 | 第一阶段只抽类型、trace、control，不拆主流程 |
+| 事件 metadata 变化影响前端 | 中 | 只新增字段，不删除旧字段 |
+| 取消/重试语义被破坏 | 高 | 优先跑 `tests/test_generation_jobs.py` |
+| Provider trace 与 job event 重复 | 低 | 保持 Provider 事件专注调用层，workflow 事件专注产品步骤 |
+| 文档与实现偏离 | 中 | 每个阶段报告必须记录实现偏差 |
+| 质量门误伤内容 | 中 | 第四阶段先做确定性低风险检查，模型评审延后 |
+
+## 10. 审查清单
+
+每个阶段完成前必须检查：
+
+- [ ] 是否保持 `/api/generations` 行为兼容
+- [ ] 是否有对应测试或验证命令
+- [ ] 是否没有引入不必要的外部框架
+- [ ] 是否没有重写无关功能
+- [ ] 是否保留用户已有工作区改动
+- [ ] 是否更新阶段报告
+- [ ] 是否更新本设计中的阶段状态或偏差记录
+
+## 11. 当前状态
+
+| 阶段 | 状态 | 备注 |
+| --- | --- | --- |
+| 阶段 0 | 已完成设计基线 | 已建立本设计与阶段 0 报告 |
+| 阶段 1 | 已完成基础实现 | 已新增 harness 类型、trace recorder、execution control，并通过定向测试 |
+| 阶段 2 | 已完成主要资产补全抽取 | 封面、音频、持久化绘本缺失图片补全已迁入 harness asset workflows |
+| 阶段 3 | 已完成计划建模基线 | 已定义 WorkflowPlan/WorkflowTask 和核心模式计划快照；执行器接管留待后续 |
+| 阶段 4 | 已完成确定性质量门 | 已接入文本故事和绘本结构完整性/儿童安全基础检查 |
+| 阶段 5 | 待执行 | Trace Analytics 与前端展示 |