1079 lines
48 KiB
Markdown
1079 lines
48 KiB
Markdown
# 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. 架构原则
|
||
|
||
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. **评测驱动优先**
|
||
生成成功不等于产品成功。每条新执行路径必须先定义可追踪 evaluation 事件、评分维度、阻断阈值和回归测试，再扩大迁移范围。
|
||
|
||
6. **评测数据内部分级**
|
||
评测分数、维度、阈值和阻断细节属于内部质量资产与商业机密，不通过用户端接口或用户前端分发。用户端只展示可操作功能、可解释进度和可恢复状态。
|
||
|
||
7. **小步可验证**
|
||
每个最小任务都必须能通过单测、局部测试或文档审查验证。
|
||
|
||
## 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 / 儿童安全 / 内容完整性"]
|
||
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 应逐步包含：
|
||
|
||
```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
|
||
}
|
||
```
|
||
|
||
### 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` | 后端测试通过 |
|
||
|
||
验证命令：
|
||
|
||
```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`
|
||
|
||
### 阶段 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` 环境回到可用状态 |
|
||
|
||
验证命令：
|
||
|
||
```bash
|
||
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 分布可被单测锁定 |
|
||
|
||
验证命令：
|
||
|
||
```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
|
||
```
|
||
|
||
阶段报告：
|
||
|
||
- `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 | 阶段报告记录安全边界 | 明确不返回原始内容和单条明细 |
|
||
|
||
验证命令：
|
||
|
||
```bash
|
||
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 | 阶段报告记录执行偏差和验证结果 | 报告包含实现、审查、测试和风险 |
|
||
|
||
验证命令：
|
||
|
||
```bash
|
||
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` 覆盖相关路径 |
|
||
|
||
验证命令：
|
||
|
||
```bash
|
||
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 数据用途和剩余风险 |
|
||
|
||
验证命令：
|
||
|
||
```bash
|
||
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 测试覆盖组合资产执行 |
|
||
|
||
验证命令：
|
||
|
||
```bash
|
||
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 与用户隔离测试 | 聚合、过滤、鉴权和用户隔离均被测试覆盖 |
|
||
|
||
验证命令：
|
||
|
||
```bash
|
||
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 | 阶段报告记录审查与验证 | 报告包含实现、风险、命令和结果 |
|
||
|
||
验证命令：
|
||
|
||
```bash
|
||
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 或单条事件 |
|
||
|
||
验证命令：
|
||
|
||
```bash
|
||
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；用户侧继续不可见 |
|