Add generation harness runtime
This commit is contained in:
111
docs/planning/harness-stage-0-report.md
Normal file
111
docs/planning/harness-stage-0-report.md
Normal file
@@ -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 报告。
|
||||
|
||||
122
docs/planning/harness-stage-1-report.md
Normal file
122
docs/planning/harness-stage-1-report.md
Normal file
@@ -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. 最后抽绘本图片工作流，因为它涉及并发生成和逐页事件顺序，风险略高。
|
||||
|
||||
121
docs/planning/harness-stage-2-report.md
Normal file
121
docs/planning/harness-stage-2-report.md
Normal file
@@ -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 顺序兼容。
|
||||
|
||||
121
docs/planning/harness-stage-3-report.md
Normal file
121
docs/planning/harness-stage-3-report.md
Normal file
@@ -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 的执行器迁移。
|
||||
|
||||
140
docs/planning/harness-stage-4-report.md
Normal file
140
docs/planning/harness-stage-4-report.md
Normal file
@@ -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。
|
||||
|
||||
Reference in New Issue
Block a user