Expand generation harness observability

docs/technical/harness-engineering-modernization.md

@@ -1,10 +1,10 @@
 # Harness Engineering 架构改造技术设计
 
-**项目**: DreamWeaver 梦语织机  
-**版本**: 0.1  
-**日期**: 2026-06-21  
-**状态**: 阶段 0 已建立设计基线  
-**作者**: Codex  
+**项目**: 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
 
 ---
 
@@ -36,6 +36,7 @@ DreamWeaver 当前已经完成统一生成工作流的第一轮落地：`POST /a
 
 - 把 `story_service` 中的运行时控制职责抽到 harness 层。
 - 让 workflow step、artifact、trace、failure category 成为一等概念。
+- 让内容生成结果在持久化和发布前具备可追踪、可回归的评测结果。
 - 保持 `/api/generations`、旧兼容接口、现有状态字段和主要测试行为不破坏。
 - 优先做渐进式重构，不引入复杂工作流引擎，不进行大爆炸重写。
 - 每个大阶段都产出阶段报告，包含实现、审查、验证和风险。
@@ -50,19 +51,25 @@ DreamWeaver 当前已经完成统一生成工作流的第一轮落地：`POST /a
 
 ## 3. 架构原则
 
-1. **主内容优先可读**  
+1. **主内容优先可读**
    文本故事或绘本结构是 blocking artifact；封面、分页插图、音频是 recoverable artifact。
 
-2. **API 稳定优先**  
+2. **API 稳定优先**
    先重构内部边界，再考虑扩展响应字段。现有前端、smoke、测试不应被第一阶段打断。
 
-3. **事件结构稳定**  
+3. **事件结构稳定**
    继续复用 `generation_job_events`，但逐步标准化 metadata，避免每个调用点随手定义不同结构。
 
-4. **Provider 不等于产品能力**  
+4. **Provider 不等于产品能力**
    Provider 只是 tool invocation 的实现。产品能力应由 capability、workflow step、artifact 和 recovery policy 共同定义。
 
-5. **小步可验证**  
+5. **评测驱动优先**
+   生成成功不等于产品成功。每条新执行路径必须先定义可追踪 evaluation 事件、评分维度、阻断阈值和回归测试，再扩大迁移范围。
+
+6. **评测数据内部分级**
+   评测分数、维度、阈值和阻断细节属于内部质量资产与商业机密，不通过用户端接口或用户前端分发。用户端只展示可操作功能、可解释进度和可恢复状态。
+
+7. **小步可验证**
    每个最小任务都必须能通过单测、局部测试或文档审查验证。
 
 ## 4. 目标架构
@@ -78,6 +85,7 @@ flowchart TB
   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"]
@@ -112,10 +120,11 @@ flowchart TB
 
 | Step | 当前事件 | 是否阻塞主内容 |
 | --- | --- | --- |
-| `request_acceptance` | `request_accepted`、`retry_queued` | 是 |
+| `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_*` | 否 |
@@ -172,11 +181,204 @@ flowchart TB
 }
 ```
 
+### 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. 模块设计
 
@@ -431,6 +633,358 @@ 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. 需求与验收
 
 ### 功能需求
@@ -446,6 +1000,13 @@ npm run build
 | 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 |
 
 ### 非功能需求
 
@@ -457,6 +1018,12 @@ npm run build
 | 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. 风险与缓解
 
@@ -468,6 +1035,14 @@ npm run build
 | 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. 审查清单
 
@@ -490,4 +1065,14 @@ npm run build
 | 阶段 2 | 已完成主要资产补全抽取 | 封面、音频、持久化绘本缺失图片补全已迁入 harness asset workflows |
 | 阶段 3 | 已完成计划建模基线 | 已定义 WorkflowPlan/WorkflowTask 和核心模式计划快照；执行器接管留待后续 |
 | 阶段 4 | 已完成确定性质量门 | 已接入文本故事和绘本结构完整性/儿童安全基础检查 |
-| 阶段 5 | 待执行 | Trace Analytics 与前端展示 |
+| 阶段 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；用户侧继续不可见 |