Files

Yuyan 1f34d80083 Expand generation harness observability

2026-06-24 10:48:23 +08:00

48 KiB

Raw Blame History

Harness Engineering 架构改造技术设计

项目: DreamWeaver 梦语织机版本: 0.1 日期: 2026-06-23 状态: 阶段 0-15 当前切片已完成，主生成与资产任务均已写入 WorkflowPlan 快照，资产生成/重试已开始由 plan-driven executor 驱动，executor coverage 已进入 admin-only 聚合并嵌入 admin trace，admin-only harness readiness 审查已建立，用户侧 job event/request payload 已使用白名单脱敏，文本故事和绘本已纳入内部评测驱动，内部 golden replay 基线、覆盖摘要、admin-only evaluation analytics 和 admin-only 完整 trace 已建立作者: 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. 架构原则

主内容优先可读 文本故事或绘本结构是 blocking artifact；封面、分页插图、音频是 recoverable artifact。
API 稳定优先 先重构内部边界，再考虑扩展响应字段。现有前端、smoke、测试不应被第一阶段打断。
事件结构稳定 继续复用 generation_job_events，但逐步标准化 metadata，避免每个调用点随手定义不同结构。
Provider 不等于产品能力 Provider 只是 tool invocation 的实现。产品能力应由 capability、workflow step、artifact 和 recovery policy 共同定义。
评测驱动优先 生成成功不等于产品成功。每条新执行路径必须先定义可追踪 evaluation 事件、评分维度、阻断阈值和回归测试，再扩大迁移范围。
评测数据内部分级 评测分数、维度、阈值和阻断细节属于内部质量资产与商业机密，不通过用户端接口或用户前端分发。用户端只展示可操作功能、可解释进度和可恢复状态。
小步可验证 每个最小任务都必须能通过单测、局部测试或文档审查验证。

4. 目标架构

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 / 儿童安全 / 内容完整性"]
  HARNESS --> EVAL["Evaluators<br/>结构 / 安全 / 年龄适配 / 教育价值 / 可读性"]

  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`、`workflow_planned`	是
`worker_start`	`worker_started`	是
`context_preparation`	`context_prepared`	是
`narrative_generation`	`narrative_generated`	是
`evaluation`	`evaluation_completed`	是
`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 应逐步包含：

{
  "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
}

5.6 Evaluation Result

每次主内容生成必须逐步产出可追踪评测结果。第一阶段使用确定性启发式，后续可替换或叠加模型评测、人审样本集和离线 replay。

标准字段：

字段	说明
`overall_score`	`0.0-1.0` 总分
`passed`	是否通过当前阈值
`blocking`	是否阻断持久化或发布
`scores`	维度评分列表
`quality_gate`	质量门失败详情，可为空
`warnings`	非阻断风险提示

当前维度：

structure
safety
age_fit
educational_value
readability

标准事件：

workflow_planned
evaluation_completed

短期兼容要求：

不删除现有 metadata 字段。
新增字段必须向后兼容。
前端仍可使用当前 event_type、status、message、event_metadata。
用户端 API 和用户前端不得返回或展示 overall_score、维度分数、阈值、阻断策略或 golden replay 结果。

5.7 Workflow Plan Coverage

WorkflowPlan 是生成 harness 的显式执行骨架。当前主生成路径和资产路径都会写入 workflow_planned 事件：

模式	plan mode	关键任务	备注
普通故事无图片	`story`	`prepare_context`、`generate_narrative`、`evaluate_narrative`、`persist_story`、`queue_postprocessing`、`complete_generation`	当前最小 plan-aware 路径
普通故事带图片	`story_with_assets`	在普通故事任务基础上增加 `generate_cover_image`	封面图为 `required=false`、`recoverable=true`
绘本	`storybook`	`prepare_context`、`generate_storybook_pages`、`evaluate_storybook_pages`、可选 `generate_storybook_images`、`persist_storybook`、`queue_postprocessing`、`complete_generation`	绘本图片为可恢复资产
资产生成	`asset_generation`	`start_asset_generation`、`complete_image_asset` 或 `complete_audio_asset`、`complete_asset_generation`	图片/音频均为 `required=false`、`recoverable=true`
资产重试	`asset_retry`	`start_asset_retry`、`complete_image_asset` 或 `complete_audio_asset`、`complete_asset_retry`	同步重试路径也记录 plan

当前边界：

workflow_planned 可进入用户侧进度，因为它只描述产品步骤，不包含评分、阈值或 golden replay 信息。
用户端只返回 coarse plan metadata：plan_mode、planned_task_count、recoverable_task_count。
用户端不返回原始 plan.tasks、任务 key、内部阈值或执行策略。
evaluation_completed 只保留在内部事件、内部测试和 admin-only 聚合中。
用户端 job detail 会过滤 evaluation_completed。
用户端 trace summary 不统计 evaluation_completed 的事件数量、step、artifact 或失败分类。
用户端 trace summary 不统计 executor_completed 的事件数量、task key 或 result asset。

5.8 Public Event Metadata Sanitizer

用户侧 job detail 的 events[*].event_metadata 使用白名单输出。数据库中的内部 metadata 不被删除，内部分析、测试和 admin-only 能力仍可读取完整事件；普通用户 API 只返回产品可解释且可操作的字段。

允许公开的类别：

标准 step、artifact、failure_category。
资源状态和资产范围，如 asset、assets、status、image_status、audio_status。
用户可理解的执行上下文，如 mode、output_mode、input_type、page_count、page_number。
Provider 运营摘要，如 adapter、capability、strategy、latency_ms、estimated_cost_usd。
coarse plan 摘要：plan_mode、planned_task_count、recoverable_task_count。

禁止公开的类别：

evaluation_completed 事件本身。
overall_score、维度分数、评分 reason、阈值、质量门 issue 明细。
原始 plan 和 plan.tasks。
result_snapshot、内部错误原文、内部阈值、replay/golden case 信息。
任意未来新增 metadata 字段，除非显式加入白名单。

5.9 Internal Evaluation Replay

内部 evaluation replay 用于把固定 golden cases 和当前 evaluator 输出做对比，帮助我们在调整质量门、评分维度或 Provider 输出结构时快速发现评测基线漂移。

当前边界：

replay 输入和结果只用于后端测试、内部工具或未来 admin-only 能力。
replay fixture 不被线上生成链路自动读取。
replay 不新增公开 API，不改变用户端 schema，不进入用户前端 bundle。
用户端 trace summary 的 total_events 不统计内部 evaluation_completed。
replay 断言只检查内部质量事实：passed、blocking、overall_score 区间、维度存在性、质量门 issue code 和 warning。
replay case 可以携带内部覆盖标签：年龄段、内容形态、风险区域和标签集合。
replay suite 可以生成内部覆盖摘要：artifact、age_band、content_shape、risk_area、tags、outcome。

当前 golden case 覆盖：

完整普通故事通过。
较长普通故事通过。
普通故事空正文被质量门阻断。
普通故事封面提示词缺失被质量门阻断。
普通故事安全风险词被质量门阻断。
普通故事结构合格但在高阈值下因阅读体验偏短被评测阻断。
完整绘本分页通过。
绘本重复页码被质量门阻断。
绘本没有分页内容被质量门阻断。
绘本分页安全风险词被质量门阻断。
绘本分页正文过短触发内部 warning 并在高阈值下阻断。

5.10 Admin-Only Evaluation Analytics

内部评测 analytics 只允许在管理控制面读取，用于质量运营和评测策略复盘。该能力不得进入用户端 /api/generations 路由、用户前端类型或用户前端 bundle。

当前 admin-only 聚合字段：

字段	说明
`total_evaluations`	内部评测事件数量
`passed_evaluations`	通过数量
`blocked_evaluations`	阻断数量
`pass_rate`	通过率
`average_score`	总分平均值
`by_artifact`	按 `story_text` / `storybook_pages` 聚合
`by_output_mode`	按 story / storybook 聚合
`score_bands`	按分数段聚合
`dimension_scores`	各评分维度平均分
`quality_gate_issues`	质量门 issue code 聚合
`failure_categories`	质量门 failure category 聚合
`warnings`	内部 warning 文案聚合

安全边界：

只挂载在 admin router 下，受 ENABLE_ADMIN_CONSOLE 和 Basic Auth admin guard 保护。
不返回故事正文、绘本分页正文、用户 prompt、cover prompt、score reason、quality gate message、单条 evaluation event 或 job event 明细。
用户端 API 继续过滤 evaluation_completed。
用户端 trace summary 继续不统计内部 evaluation_completed。
用户端前端不包含该接口调用、类型定义或展示组件。

5.11 Admin-Only Executor Coverage

内部 executor coverage 用于审查 WorkflowPlan 是否真正驱动了资产执行，以及哪些 task key 仍只是计划占位或被当前 runner 忽略。该能力只属于管理控制面，不进入用户 API 或用户前端。

当前 admin-only 聚合字段：

字段	说明
`total_runs`	executor 完成事件数量
`total_planned_tasks`	计划任务总数
`total_executed_tasks`	实际执行任务总数
`total_ignored_tasks`	被 runner 忽略的任务总数
`coverage_ratio`	`executed / planned`
`by_plan_mode`	按 `asset_generation` / `asset_retry` 等模式聚合
`by_output_mode`	按生成 job 的 output mode 聚合
`executed_task_keys`	已执行 task key 聚合
`ignored_task_keys`	已忽略 task key 聚合
`result_assets`	返回资产聚合

安全边界：

只挂载在 admin router 下，受 ENABLE_ADMIN_CONSOLE 和 Basic Auth admin guard 保护。
executor_completed 事件、task key、ignored task key 和 result asset 明细不进入用户 job detail。
用户 job summary 如果短暂停留在内部 executor_completed step，会映射为安全公开的 workflow_planned。
用户 trace summary 不统计 executor_completed，避免通过事件数量或聚合维度泄露内部执行器结构。
用户前端不包含 /admin/executors/coverage 调用、类型定义或展示组件。

5.12 Admin Trace Executor Coverage Summary

管理端单个 generation trace 在完整事件流之外，额外返回 executor_coverage 摘要，用于一次请求内同时完成“看事件”和“看执行覆盖”的审查。

设计边界：

GET /admin/generations/jobs/{job_id}/trace 复用全局 executor coverage 的聚合函数，避免两个 admin 视图统计口径不一致。
trace 内嵌 summary 的 scope 为 admin_internal_job_executor_coverage，只统计当前 job 的 executor_completed 事件。
trace 内嵌 summary 允许返回 task key、ignored task key 和 result asset，因为该接口已经是 admin-only 完整内部 trace。
用户侧 /api/generations/jobs/{job_id}、/api/generations/{story_id}/jobs 和 /api/generations/{story_id}/trace-summary 均不返回该字段。

5.13 Admin-Only Harness Readiness

内部 harness readiness 用于在扩大 plan-driven executor 或评测策略接管范围前，给管理控制面提供一个聚合级别的上线前审查摘要。

输入来源：

内部 golden replay fixture，随后端 app 一起发布，避免运行环境缺少测试目录。
admin-only evaluation analytics 聚合。
admin-only executor coverage 聚合。

当前 readiness checks：

Check	说明	默认门槛
`golden_replay`	内部 golden cases 是否全部符合预期	必须全部通过
`runtime_evaluation_samples`	当前窗口是否有运行期 evaluation 样本	至少 1 条
`runtime_evaluation_quality`	运行期 evaluation 通过率和均分是否达标	pass rate >= 0.7，average score >= 0.7
`executor_coverage_samples`	当前窗口是否有 executor coverage 样本	至少 1 次 run
`executor_coverage_ratio`	executor 实际执行任务占计划任务比例	coverage ratio >= 0.2

安全边界：

只挂载在 admin router 下，受 ENABLE_ADMIN_CONSOLE 和 Basic Auth admin guard 保护。
只返回聚合结果、阈值、状态和 coverage summary。
不返回故事正文、绘本分页正文、用户 prompt、cover prompt、score reason、quality gate message 或单条事件明细。
用户端 API 和用户前端不包含该接口调用、类型定义或展示组件。

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`	后端测试通过

验证命令：

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 单测	资产相关测试通过

验证命令：

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 单测	核心模式计划快照稳定

验证命令：

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 可解释

验证命令：

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 通过

验证命令：

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

阶段 6: 新架构真实运行烟测

目标：

使用新代码启动本地 API 与 Celery worker。
复用 Docker demo stack 中的 PostgreSQL 与 Redis。
通过真实 HTTP API 覆盖登录、生成、worker 执行、故事落库、trace summary 和 provider stats。
覆盖主内容工作流与资源重试工作流。

最小任务：

ID	任务	验收
H6-1	启动本地新代码 API	`/health` 返回 `{"status":"ok"}`
H6-2	启动本地新代码 worker	生成任务可被 worker claim 并执行
H6-3	使用 dev 登录创建真实 cookie 会话	`/auth/session` 返回开发用户
H6-4	提交普通故事生成	job 进入 completed/degraded 且 story 落库
H6-5	查询 trace summary/provider stats	返回 step、artifact、provider 聚合
H6-6	执行图片资源重试	trace summary 聚合出 `image_generation` 与 `cover_image`
H6-7	清理临时进程并恢复 Docker worker	`docker compose ps` 环境回到可用状态

验证命令：

cd backend
DATABASE_URL='postgresql+asyncpg://dreamweaver:dreamweaver_password@localhost:52432/dreamweaver_db' \
CELERY_BROKER_URL='redis://localhost:52379/0' \
CELERY_RESULT_BACKEND='redis://localhost:52379/0' \
REDIS_URL='redis://localhost:52379/0' \
.venv/bin/python -m uvicorn app.main:app --host 127.0.0.1 --port 53000

DATABASE_URL='postgresql+asyncpg://dreamweaver:dreamweaver_password@localhost:52432/dreamweaver_db' \
CELERY_BROKER_URL='redis://localhost:52379/0' \
CELERY_RESULT_BACKEND='redis://localhost:52379/0' \
REDIS_URL='redis://localhost:52379/0' \
.venv/bin/celery -A app.core.celery_app worker --loglevel=info --concurrency=1

阶段报告：

docs/planning/harness-stage-6-report.md

阶段 7: 评测驱动与执行器最小接管

目标：

将“生成是否合格”从隐含质量门升级为结构化 evaluation result。
让普通故事、generate_images=false 的最小路径由 WorkflowPlan 参与执行。
在 job events 中记录 workflow_planned 和 evaluation_completed。
用测试锁住评分、阻断、事件顺序和 trace 聚合。

最小任务：

ID	任务	验收
H7-1	新增 deterministic evaluator	通过/阻断用例有单测
H7-2	新增 plan-aware executor helper	任务写入 `workflow_planned`
H7-3	普通故事无图片路径接入 plan	worker 事件序列包含 plan/evaluation
H7-4	质量门失败也写入 evaluation	failed job 可解释阻断原因
H7-5	增加评测驱动 QA 用例文档	覆盖功能、边界、错误和状态转换
H7-6	阶段报告记录 bug/风险	大 bug 可后续统一处理
H7-7	增加内部 golden replay 基线	固定样本可离线回放并被单测锁定
H7-8	增加 replay 覆盖摘要	年龄段、内容形态、风险区域和 outcome 分布可被单测锁定

验证命令：

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

阶段报告：

docs/planning/harness-stage-7-report.md

阶段 8: Admin-Only Evaluation Analytics

目标：

提供管理控制面内部评测摘要，用于质量运营和评测策略复盘。
明确 admin-only 权限边界，避免将评测数据分发给普通用户。
只返回聚合摘要，不返回原始内容、prompt、单条评测明细或评分 reason。

最小任务：

ID	任务	验收
H8-1	新增 admin evaluation analytics 服务	可聚合 `evaluation_completed`
H8-2	新增 admin-only 路由	`/admin/evaluations/analytics` 受 admin guard 保护
H8-3	支持 days/artifact 过滤	过滤测试通过
H8-4	锁定用户端隔离	用户端扫描无 evaluation analytics 入口
H8-5	阶段报告记录安全边界	明确不返回原始内容和单条明细

验证命令：

cd backend
.venv/bin/python -m pytest tests/test_admin_providers.py tests/test_generation_jobs.py
.venv/bin/python -m ruff check app tests

阶段报告：

docs/planning/harness-stage-8-report.md

阶段 9: WorkflowPlan 接管扩展

目标：

让普通故事无图片、普通故事带图片、绘本三条主生成路径都写入显式 workflow_planned。
将计划快照用于锁定事件顺序、可恢复资产任务和后续执行器迁移边界。
继续保持评测数据内部分级，用户端只看到可用进度和可恢复状态。

最小任务：

ID	任务	验收
H9-1	带图片故事路径记录 `story_with_assets` plan	事件顺序中 `workflow_planned` 位于 `worker_started` 与 `context_prepared` 之间
H9-2	绘本路径记录 `storybook` plan	plan 快照包含 `evaluate_storybook_pages` 和可恢复图片任务
H9-3	补主路径事件顺序测试	story、story_with_assets、storybook 三条路径均被测试覆盖
H9-4	锁定用户端评测隔离	用户 API 不返回 `evaluation_completed`、评分、维度或 replay 数据
H9-5	阶段报告记录执行偏差和验证结果	报告包含实现、审查、测试和风险

验证命令：

cd backend
.venv/bin/python -m pytest tests/test_generation_jobs.py
.venv/bin/python -m pytest
.venv/bin/python -m ruff check app tests
cd ../frontend
npm run build
cd ../admin-frontend
npm run build

阶段报告：

docs/planning/harness-stage-9-report.md

阶段 10: 资产计划与 Public Metadata Sanitizer

目标：

将 asset_generation 和 asset_retry 也纳入 WorkflowPlan 记录。
让用户侧 job event metadata 使用白名单脱敏，避免未来内部 metadata 扩展时误泄露质量策略。
保留用户前端需要的可解释字段：step、artifact、failure category、资源状态、Provider 运营摘要和 coarse plan 摘要。

最小任务：

ID	任务	验收
H10-1	后台资产生成记录 `asset_generation` plan	worker 事件顺序包含 `workflow_planned`
H10-2	资源重试记录 `asset_retry` plan	同步 retry events 包含 plan 快照
H10-3	旧封面/音频生成接口记录资产 plan	兼容接口不破坏现有响应
H10-4	用户 event metadata 白名单脱敏	用户 API 不返回原始 `plan.tasks`、`result_snapshot`、内部错误和阈值
H10-5	补资产计划和 sanitizer 回归测试	`tests/test_generation_jobs.py` 覆盖相关路径

验证命令：

cd backend
.venv/bin/python -m pytest tests/test_generation_jobs.py
.venv/bin/python -m pytest
.venv/bin/python -m ruff check app tests
cd ../frontend
npm run build
cd ../admin-frontend
npm run build

阶段报告：

docs/planning/harness-stage-10-report.md

阶段 11: Trace 访问分级与 Request Payload Sanitizer

目标：

用户侧 job detail 的 request_payload 改为白名单脱敏，避免内部调度参数、Provider override、评测策略或原始输入被接口原样回传。
新增 admin-only generation trace detail，在 admin_guard 保护下返回完整内部 request payload、workflow plan 和 evaluation metadata。
明确用户前端与管理控制面的 trace 数据边界，为后续 executor 接管保留完整取证能力。

最小任务：

ID	任务	验收
H11-1	用户侧 request payload 白名单脱敏	用户 job detail 只返回 output/input mode、资产、故事 ID、页数、图片请求开关等安全控制字段
H11-2	新增 admin-only trace detail 服务	管理端可按 job id 读取完整内部 request payload 和完整 event metadata
H11-3	新增 admin trace 路由与响应模型	`GET /admin/generations/jobs/{job_id}/trace` 受 `admin_guard` 保护
H11-4	补用户脱敏和 admin 完整 trace 测试	用户接口不含内部字段；admin 接口包含 `evaluation_completed` 和完整 plan
H11-5	阶段报告记录商业机密边界	报告说明用户端不分发评测数据，admin-only 数据用途和剩余风险

验证命令：

cd backend
.venv/bin/python -m pytest tests/test_generation_jobs.py tests/test_admin_providers.py -q
.venv/bin/python -m pytest
.venv/bin/python -m ruff check app tests
cd ../frontend
npm run build
cd ../admin-frontend
npm run build

阶段报告：

docs/planning/harness-stage-11-report.md

阶段 12: Plan-Driven Asset Executor 试点

目标：

让 WorkflowPlan 从“记录计划”进入“驱动执行”的第一步。
先接管低风险资产任务：asset_generation、asset_retry、旧封面生成、旧音频生成。
保留现有 asset workflow 的 provider 调用、状态同步、取消检查和事件记录，不把细节复制进 executor。
保持用户侧公开面不新增评测数据或内部 task metadata。

最小任务：

ID	任务	验收
H12-1	新增 `run_asset_plan`	按 `WorkflowTask.key` 顺序执行图片/音频任务，并返回执行结果
H12-2	后台 `asset_generation` 接入 plan runner	多资产 job 按 plan 顺序生成音频和图片，事件顺序稳定
H12-3	同步 `asset_retry` 接入 plan runner	图片/音频重试仍保持原有完成和失败语义
H12-4	旧封面/音频接口接入 plan runner	`/api/image/generate/{id}` 和 `/api/audio/{id}` 行为兼容
H12-5	补 executor 与资产路径回归测试	harness 单测覆盖执行顺序；generation job 测试覆盖组合资产执行

验证命令：

cd backend
.venv/bin/python -m pytest tests/test_harness_runtime.py tests/test_generation_jobs.py -q
.venv/bin/python -m pytest
.venv/bin/python -m ruff check app tests
cd ../frontend
npm run build
cd ../admin-frontend
npm run build

阶段报告：

docs/planning/harness-stage-12-report.md

阶段 13: Admin-Only Executor Coverage

目标：

将资产 executor 的执行结果记录成内部 executor_completed 事件。
新增 admin-only executor coverage 聚合，用于审查 plan-driven execution 覆盖率。
用户侧 job detail、job list 和 trace summary 继续隐藏内部 executor task key 与 coverage metadata。

最小任务：

ID	任务	验收
H13-1	executor result 生成 coverage metadata	metadata 包含 plan mode、planned/executed/ignored counts、task keys、result assets
H13-2	资产路径记录 `executor_completed`	asset generation/retry 和旧资源接口写入内部 executor 事件
H13-3	新增 admin-only coverage API	`GET /admin/executors/coverage` 受 admin guard 保护
H13-4	用户侧过滤 executor 事件和 step	用户 API 不返回 `executor_completed` 或 task keys
H13-5	补 admin coverage 与用户隔离测试	聚合、过滤、鉴权和用户隔离均被测试覆盖

验证命令：

cd backend
.venv/bin/python -m pytest tests/test_generation_jobs.py tests/test_admin_providers.py tests/test_harness_runtime.py -q
.venv/bin/python -m pytest
.venv/bin/python -m ruff check app tests
cd ../frontend
npm run build
cd ../admin-frontend
npm run build

阶段报告：

docs/planning/harness-stage-13-report.md

阶段 14: Admin Trace Executor Coverage Summary

目标：

让 admin-only 完整 generation trace 自带 executor coverage 摘要。
复用全局 executor coverage 聚合逻辑，保持 /admin/executors/coverage 与单 job trace 的统计口径一致。
修正用户 trace summary 的隔离边界，确保内部 executor_completed 不通过聚合数量或 task key 泄露。

最小任务：

ID	任务	验收
H14-1	抽出 executor coverage 纯聚合函数	全局 coverage API 与单 job trace 复用同一函数
H14-2	admin trace 返回 `executor_coverage`	`GET /admin/generations/jobs/{job_id}/trace` 包含当前 job executor summary
H14-3	用户 trace summary 过滤 `executor_completed`	用户 trace summary 不统计内部 executor 事件数量或 task key
H14-4	补 admin trace summary 与用户隔离测试	admin 可见覆盖摘要；用户 detail/list/trace summary 不可见
H14-5	阶段报告记录审查与验证	报告包含实现、风险、命令和结果

验证命令：

cd backend
.venv/bin/python -m pytest tests/test_generation_jobs.py tests/test_admin_providers.py tests/test_harness_runtime.py -q
.venv/bin/python -m pytest
.venv/bin/python -m ruff check app tests
cd ../frontend
npm run build
cd ../admin-frontend
npm run build

阶段报告：

docs/planning/harness-stage-14-report.md

阶段 15: Admin-Only Harness Readiness

目标：

建立一个 admin-only readiness audit，在扩大 harness 接管范围前给出聚合质量门。
复用 golden replay、evaluation analytics 和 executor coverage，避免新增独立统计口径。
保持用户侧完全不可见，不向用户端分发评测数据、executor task key 或 readiness 结果。

最小任务：

ID	任务	验收
H15-1	将 golden replay fixture 放入 app 内部路径	Docker 运行环境可读取内部 golden cases
H15-2	新增 admin harness readiness 服务	聚合 golden replay、evaluation analytics 和 executor coverage
H15-3	新增 admin-only readiness API	`GET /admin/harness/readiness` 受 admin guard 保护
H15-4	补 readiness ready/blocked/鉴权测试	ready、blocked、needs_attention 和 401 均被覆盖
H15-5	阶段报告记录安全边界和验证	报告说明不返回正文、prompt、score reason 或单条事件

验证命令：

cd backend
.venv/bin/python -m pytest tests/test_admin_providers.py tests/test_harness_runtime.py -q
.venv/bin/python -m pytest
.venv/bin/python -m ruff check app tests
cd ../frontend
npm run build
cd ../admin-frontend
npm run build

阶段报告：

docs/planning/harness-stage-15-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	构建通过且无布局溢出
FR-010	MUST	用户侧事件 metadata 必须白名单脱敏	用户 API 不返回评测分数、原始 plan、result snapshot 或内部错误原文
FR-011	MUST	用户侧 request payload 必须白名单脱敏	用户 job detail 不返回原始输入、内部调度参数、provider override 或评测策略
FR-012	SHOULD	管理控制面可读取完整内部 trace	admin-only trace endpoint 返回完整 request payload 和完整 event metadata
FR-013	SHOULD	资产任务应由 WorkflowPlan 驱动执行	asset generation/retry 按 plan task key 执行图片和音频任务
FR-014	SHOULD	管理控制面可审查 executor 覆盖率	admin-only coverage endpoint 聚合 executor runs、task counts 和 result assets
FR-015	SHOULD	管理端单 job trace 可审查 executor 覆盖摘要	admin-only trace endpoint 返回当前 job 的 executor coverage summary
FR-016	SHOULD	管理控制面可执行 harness readiness 审查	admin-only readiness endpoint 聚合 golden replay、evaluation analytics 和 executor coverage

非功能需求

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	中文一致性	文档、用户可见文案和新增注释使用简体中文
NFR-007	MUST	默认不公开内部 metadata	未加入白名单的新字段不会出现在用户侧 job event 响应中
NFR-008	MUST	Trace 数据访问分级	用户接口只返回安全公开字段；完整评测和内部调度数据仅在 admin guard 后提供
NFR-009	SHOULD	Executor 接管必须小步可回退	先接资产任务；主文本生成仍保持原有服务路径
NFR-010	MUST	Executor coverage 默认不公开	`executor_completed`、task keys 和 coverage metadata 不进入用户端接口
NFR-011	MUST	Admin trace 统计口径一致	单 job trace 与全局 executor coverage 复用同一聚合逻辑
NFR-012	MUST	Readiness 数据默认不公开	readiness endpoint 只在 admin guard 后提供，不返回正文、prompt、score reason 或单条事件

9. 风险与缓解

风险	影响	缓解
过度抽象导致改造变慢	中	第一阶段只抽类型、trace、control，不拆主流程
事件 metadata 变化影响前端	中	只新增字段，不删除旧字段
取消/重试语义被破坏	高	优先跑 `tests/test_generation_jobs.py`
Provider trace 与 job event 重复	低	保持 Provider 事件专注调用层，workflow 事件专注产品步骤
文档与实现偏离	中	每个阶段报告必须记录实现偏差
质量门误伤内容	中	第四阶段先做确定性低风险检查，模型评审延后
评测 analytics 泄露商业机密	高	仅 admin-only 聚合摘要；用户端 API/前端不接入；测试覆盖 admin guard 和用户端隔离
新增 trace metadata 误进用户 API	高	`public_generation_event_metadata` 使用 allowlist，新增字段默认不公开
请求 payload 混入内部字段	高	`public_generation_request_payload` 使用 allowlist，完整 payload 仅 admin-only trace endpoint 可见
Executor 抽象过早扩大范围	中	阶段 12 只接管资产 task key；主文本、评测和持久化暂不迁移
Executor coverage 泄露内部执行策略	中	`executor_completed` 全量过滤用户侧响应，只在 admin-only coverage/trace 中提供
Admin trace 与全局 coverage 口径漂移	中	抽出共享聚合函数，测试同时覆盖 admin trace 和全局 coverage API
Readiness 运行环境缺少 golden fixture	中	golden cases 放入 app 内部 harness fixtures，随 Docker `COPY app ./app` 发布
Readiness 聚合泄露内部内容	高	只返回聚合状态和覆盖摘要；测试断言不包含 story title、score reason 或 quality gate message

10. 审查清单

每个阶段完成前必须检查：

是否保持 /api/generations 行为兼容
是否有对应测试或验证命令
是否没有引入不必要的外部框架
是否没有重写无关功能
是否保留用户已有工作区改动
是否更新阶段报告
是否更新本设计中的阶段状态或偏差记录

11. 当前状态

阶段	状态	备注
阶段 0	已完成设计基线	已建立本设计与阶段 0 报告
阶段 1	已完成基础实现	已新增 harness 类型、trace recorder、execution control，并通过定向测试
阶段 2	已完成主要资产补全抽取	封面、音频、持久化绘本缺失图片补全已迁入 harness asset workflows
阶段 3	已完成计划建模基线	已定义 WorkflowPlan/WorkflowTask 和核心模式计划快照；执行器接管留待后续
阶段 4	已完成确定性质量门	已接入文本故事和绘本结构完整性/儿童安全基础检查
阶段 5	已完成 trace analytics 与前端展示	已新增 trace summary API，并在用户端/管理端生成轨迹中展示 step、artifact、failure category
阶段 6	已完成真实运行烟测	已通过本地新代码 API/worker + Docker PostgreSQL/Redis 覆盖主生成和图片资源重试链路
阶段 7	已完成 7A/7B/7C/7D/7E 当前切片	已接入 deterministic evaluator、`workflow_planned`、`evaluation_completed`、普通故事无图片 plan-aware 路径、绘本内部评测、内部 golden replay 和覆盖摘要；已修正并锁定用户侧不分发评测数据
阶段 8	已完成 admin-only evaluation analytics 当前切片	已新增 `/admin/evaluations/analytics` 聚合接口、admin guard 测试、days/artifact 过滤和用户端隔离扫描
阶段 9	已完成 WorkflowPlan 接管扩展当前切片	普通故事带图片和绘本路径已记录 plan 快照，三条主路径事件顺序与用户端评测隔离已由测试覆盖
阶段 10	已完成资产计划与 public metadata sanitizer 当前切片	资产生成/重试路径已记录 plan；用户侧 event metadata 改为白名单并隐藏原始 plan、result snapshot 和内部字段
阶段 11	已完成 trace 访问分级当前切片	用户侧 request payload 改为白名单；新增 admin-only 完整 trace endpoint 并覆盖鉴权和内部事件测试
阶段 12	已完成 plan-driven asset executor 当前切片	`run_asset_plan` 已按 plan task key 驱动图片/音频资产任务；后台资产生成、资源重试和旧封面/音频接口已接入
阶段 13	已完成 admin-only executor coverage 当前切片	资产 executor 已记录内部 `executor_completed`；新增 `/admin/executors/coverage`，用户侧继续过滤 executor 事件和 task keys
阶段 14	已完成 admin trace executor coverage summary 当前切片	admin trace 已内嵌单 job executor coverage 摘要；用户 trace summary 继续过滤内部 executor 事件
阶段 15	已完成 admin-only harness readiness 当前切片	新增 `/admin/harness/readiness` 聚合 golden replay、evaluation analytics 与 executor coverage；用户侧继续不可见

48 KiB Raw Blame History Unescape Escape

Harness Engineering 架构改造技术设计

1. 背景

2. 目标

2.1 产品目标

2.2 工程目标

2.3 非目标

3. 架构原则

4. 目标架构

5. 运行时核心概念

5.1 Generation Command

5.2 Workflow Step

5.3 Artifact

5.4 Failure Category

5.5 Trace Metadata

5.6 Evaluation Result

5.7 Workflow Plan Coverage

5.8 Public Event Metadata Sanitizer

5.9 Internal Evaluation Replay

5.10 Admin-Only Evaluation Analytics

5.11 Admin-Only Executor Coverage

5.12 Admin Trace Executor Coverage Summary

5.13 Admin-Only Harness Readiness

6. 模块设计

6.1 app/services/harness/types.py

6.2 app/services/harness/trace.py

6.3 app/services/harness/control.py

6.4 app/services/harness/artifacts.py

6.5 story_service 改造方式

7. 阶段计划

阶段 0: 设计与基线

阶段 1: Harness 基础类型与事件封装

阶段 2: 资产工作流边界抽取

阶段 3: Workflow Plan 与执行器

阶段 4: Quality Gates 与输出验证

阶段 5: Trace Analytics 与前端增量展示

阶段 6: 新架构真实运行烟测

阶段 7: 评测驱动与执行器最小接管

阶段 8: Admin-Only Evaluation Analytics

阶段 9: WorkflowPlan 接管扩展

阶段 10: 资产计划与 Public Metadata Sanitizer

阶段 11: Trace 访问分级与 Request Payload Sanitizer

阶段 12: Plan-Driven Asset Executor 试点

阶段 13: Admin-Only Executor Coverage

阶段 14: Admin Trace Executor Coverage Summary

阶段 15: Admin-Only Harness Readiness

8. 需求与验收

功能需求

非功能需求

9. 风险与缓解

10. 审查清单

11. 当前状态

48 KiB

Raw Blame History

6.1 `app/services/harness/types.py`

6.2 `app/services/harness/trace.py`

6.3 `app/services/harness/control.py`

6.4 `app/services/harness/artifacts.py`

6.5 `story_service` 改造方式