Add generation harness runtime

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 与前端展示 |