Expand generation harness observability
This commit is contained in:
159
docs/planning/harness-stage-10-report.md
Normal file
159
docs/planning/harness-stage-10-report.md
Normal file
@@ -0,0 +1,159 @@
|
||||
# Harness Engineering 改造阶段 10 报告
|
||||
|
||||
**阶段**: 10 - 资产计划与 Public Metadata Sanitizer
|
||||
**日期**: 2026-06-22
|
||||
**状态**: 已完成当前切片
|
||||
**范围**: 资产生成/重试 WorkflowPlan、用户侧 job event metadata 白名单脱敏、回归测试和商业机密边界复核
|
||||
|
||||
---
|
||||
|
||||
## 1. 本阶段目标
|
||||
|
||||
阶段 10 的目标是把资产任务也纳入 Harness Engineering 的显式计划模型，并把用户侧事件 metadata 从“过滤少数内部事件”升级为“白名单公开”。
|
||||
|
||||
本阶段重点：
|
||||
|
||||
- `asset_generation` 写入 `workflow_planned`。
|
||||
- `asset_retry` 写入 `workflow_planned`。
|
||||
- 旧封面/音频兼容接口创建的资产 job 也写入 plan。
|
||||
- 用户侧 job detail 的 event metadata 使用 public sanitizer。
|
||||
- 内部数据库事件继续保留完整 metadata，供测试、内部分析和 admin-only 能力使用。
|
||||
|
||||
## 2. 已完成工作
|
||||
|
||||
### 资产 WorkflowPlan
|
||||
|
||||
修改文件：
|
||||
|
||||
- `backend/app/services/story_service.py`
|
||||
|
||||
新增行为：
|
||||
|
||||
- 后台 `asset_generation` worker 在执行资源补全前记录 `asset_generation` plan。
|
||||
- `/api/generations/{story_id}/retry-assets` 同步重试路径记录 `asset_retry` plan。
|
||||
- 旧 `/api/image/generate/{story_id}` 和 `/api/audio/{story_id}` 兼容路径记录 `asset_generation` plan。
|
||||
|
||||
资产 plan 快照：
|
||||
|
||||
- `plan.mode=asset_generation` 或 `asset_retry`
|
||||
- 图片任务使用 `complete_image_asset`
|
||||
- 音频任务使用 `complete_audio_asset`
|
||||
- 图片/音频任务均为 `required=false`、`recoverable=true`
|
||||
|
||||
### Public Metadata Sanitizer
|
||||
|
||||
修改文件：
|
||||
|
||||
- `backend/app/services/generation_jobs.py`
|
||||
|
||||
新增能力：
|
||||
|
||||
- `public_generation_event_metadata(...)`。
|
||||
- 用户侧 `public_generation_event_to_response(...)` 不再原样返回 event metadata。
|
||||
- `evaluation_completed` 事件继续完全过滤。
|
||||
- `workflow_planned` 只返回 coarse plan 摘要：
|
||||
- `plan_mode`
|
||||
- `planned_task_count`
|
||||
- `recoverable_task_count`
|
||||
|
||||
用户侧允许保留：
|
||||
|
||||
- `step`
|
||||
- `artifact`
|
||||
- `failure_category`
|
||||
- `asset` / `assets`
|
||||
- `status`
|
||||
- `mode`
|
||||
- `output_mode`
|
||||
- `input_type`
|
||||
- `page_count`
|
||||
- `page_number`
|
||||
- `adapter`
|
||||
- `capability`
|
||||
- `strategy`
|
||||
- `latency_ms`
|
||||
- `estimated_cost_usd`
|
||||
- 资源状态和少量可解释执行上下文
|
||||
|
||||
用户侧禁止返回：
|
||||
|
||||
- 原始 `plan`
|
||||
- 原始 `plan.tasks`
|
||||
- `result_snapshot`
|
||||
- 内部阈值
|
||||
- 内部错误原文
|
||||
- `overall_score`
|
||||
- 维度分数
|
||||
- 评分 reason
|
||||
- golden replay 信息
|
||||
|
||||
## 3. 测试覆盖
|
||||
|
||||
修改文件：
|
||||
|
||||
- `backend/tests/test_generation_jobs.py`
|
||||
|
||||
新增或更新覆盖：
|
||||
|
||||
- 更新 `asset_retry` 事件顺序，断言 `asset_retry` plan。
|
||||
- 更新 `asset_generation` worker 事件顺序，断言 `asset_generation` plan。
|
||||
- 新增 `test_user_generation_job_detail_sanitizes_public_event_metadata`，确认用户 API 不返回原始 plan、tasks、result snapshot、内部阈值和内部错误原文。
|
||||
|
||||
## 4. 验证结果
|
||||
|
||||
已执行：
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
.venv/bin/python -m pytest 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
|
||||
```
|
||||
|
||||
结果：
|
||||
|
||||
- 定向生成任务测试：`22 passed`
|
||||
- 后端全量测试：`152 passed`
|
||||
- Ruff：`All checks passed!`
|
||||
- 用户前端构建：通过
|
||||
- 管理端构建：通过
|
||||
|
||||
构建提示：
|
||||
|
||||
- `frontend` 和 `admin-frontend` 构建均提示 Browserslist/caniuse-lite 数据较旧。
|
||||
- `admin-frontend` 额外提示 `baseline-browser-mapping` 数据较旧。
|
||||
- 以上均为依赖数据 freshness 提示，不影响当前构建结果。
|
||||
|
||||
## 5. 自审结论
|
||||
|
||||
本阶段继续保持“内部完整、外部最小”的边界：
|
||||
|
||||
- 内部 event metadata 没有丢失，admin-only 和测试仍可读取完整 plan 与评测数据。
|
||||
- 用户侧 job event metadata 已从 denylist 走向 allowlist，未来新增内部字段默认不会公开。
|
||||
- 用户侧仍可看到进度、资源、Provider 和失败分类等可操作信息。
|
||||
- 原始 `plan.tasks`、内部阈值、内部错误原文和 result snapshot 不进入用户事件流。
|
||||
|
||||
## 6. Bug 与风险记录
|
||||
|
||||
已发现并即时修复的问题：
|
||||
|
||||
- 初次测试时 `asset_generation` 和 `asset_retry` 的旧事件顺序断言未包含 `workflow_planned`；已更新测试并增加 plan 快照断言。
|
||||
- sanitizer 测试最初用字符串搜索禁止 `plan`，误伤公开字段 `plan_mode`；已改为断言原始 `plan` key 不存在。
|
||||
|
||||
当前风险：
|
||||
|
||||
- `request_payload` 仍作为 job detail 字段返回，当前包含用户发起请求本身。后续如请求 payload 增加内部调度参数，需要单独做 payload sanitizer。
|
||||
- Provider 成本信息当前仍在用户侧展示，属于既有产品运营摘要。若商业策略变化，需要从 white list 中移除 `estimated_cost_usd` 并同步前端。
|
||||
- admin-frontend 当前复用用户侧 `/api/generations/jobs/{job_id}`，因此看到的是脱敏事件。未来如果管理端需要完整内部 event metadata，应新增 admin-only trace endpoint。
|
||||
|
||||
## 7. 后续建议
|
||||
|
||||
下一阶段建议进入阶段 11：
|
||||
|
||||
1. 设计 admin-only generation trace detail，让管理端在权限保护下查看完整内部 plan/evaluation/provider metadata。
|
||||
2. 为 `request_payload` 增加 public sanitizer，防止未来内部调度字段被用户端 job detail 透出。
|
||||
3. 继续推进 executor 小步接管，把资产 plan 从“记录事实”升级为“驱动执行”的最小执行单元。
|
||||
165
docs/planning/harness-stage-11-report.md
Normal file
165
docs/planning/harness-stage-11-report.md
Normal file
@@ -0,0 +1,165 @@
|
||||
# Harness Engineering 改造阶段 11 报告
|
||||
|
||||
**阶段**: 11 - Trace 访问分级与 Request Payload Sanitizer
|
||||
**日期**: 2026-06-22
|
||||
**状态**: 已完成当前切片
|
||||
**范围**: 用户侧 request payload 白名单脱敏、admin-only 完整生成 trace、回归测试和商业机密边界复核
|
||||
|
||||
---
|
||||
|
||||
## 1. 本阶段目标
|
||||
|
||||
阶段 11 承接阶段 10 的风险记录：事件 metadata 已经白名单脱敏，但用户侧 job detail 仍会原样返回 `request_payload`。如果后续 executor 或调度层把内部字段写入 payload，就可能把内部策略、Provider override 或评测配置分发给用户端。
|
||||
|
||||
本阶段目标：
|
||||
|
||||
- 用户侧 `GET /api/generations/jobs/{job_id}` 只返回安全公开的 request payload 字段。
|
||||
- 管理控制面新增完整 trace detail，用于内部审查、排障和评测驱动复盘。
|
||||
- 完整内部评测数据、workflow plan、原始 request payload 只在 `admin_guard` 后可见。
|
||||
|
||||
## 2. 已完成工作
|
||||
|
||||
### 用户侧 Request Payload Sanitizer
|
||||
|
||||
修改文件：
|
||||
|
||||
- `backend/app/services/generation_jobs.py`
|
||||
|
||||
新增能力：
|
||||
|
||||
- `public_generation_request_payload(...)`
|
||||
- 用户侧 `get_generation_job_detail(...)` 不再原样返回 `job.request_payload`
|
||||
- request payload 使用白名单公开
|
||||
|
||||
当前用户侧允许字段：
|
||||
|
||||
- `assets`
|
||||
- `child_profile_id`
|
||||
- `generate_images`
|
||||
- `input_type`
|
||||
- `output_mode`
|
||||
- `page_count`
|
||||
- `story_id`
|
||||
- `type`
|
||||
- `universe_id`
|
||||
|
||||
当前用户侧禁止字段：
|
||||
|
||||
- 原始 `data`
|
||||
- `education_theme`
|
||||
- 内部调度 token
|
||||
- Provider override
|
||||
- evaluation policy
|
||||
- 任意 dict 型内部配置
|
||||
|
||||
### Admin-Only 完整 Trace Detail
|
||||
|
||||
新增文件：
|
||||
|
||||
- `backend/app/services/admin_generation_trace.py`
|
||||
|
||||
修改文件：
|
||||
|
||||
- `backend/app/api/admin_providers.py`
|
||||
|
||||
新增接口：
|
||||
|
||||
```http
|
||||
GET /admin/generations/jobs/{job_id}/trace
|
||||
```
|
||||
|
||||
接口能力：
|
||||
|
||||
- 返回完整 `request_payload`
|
||||
- 返回完整 event stream
|
||||
- 不过滤 `evaluation_completed`
|
||||
- 不脱敏 `workflow_planned.event_metadata.plan.tasks`
|
||||
- 返回 `user_id` 供管理控制面审计
|
||||
- 继承 admin router 的 `admin_guard` 保护
|
||||
|
||||
## 3. 测试覆盖
|
||||
|
||||
修改文件：
|
||||
|
||||
- `backend/tests/test_generation_jobs.py`
|
||||
- `backend/tests/test_admin_providers.py`
|
||||
- `backend/tests/harness-evaluation-test-cases.md`
|
||||
|
||||
新增覆盖：
|
||||
|
||||
- `test_user_generation_job_detail_sanitizes_request_payload`
|
||||
- 断言用户 job detail 不返回原始 `data`
|
||||
- 断言用户 job detail 不返回内部调度 token、Provider override 或 evaluation policy
|
||||
- 断言用户 job detail 保留必要公开控制字段
|
||||
- `test_admin_generation_job_trace_returns_internal_event_stream`
|
||||
- 断言 admin trace 返回完整 request payload
|
||||
- 断言 admin trace 返回 `workflow_planned` 原始 plan tasks
|
||||
- 断言 admin trace 返回 `evaluation_completed` 和评分 metadata
|
||||
- `test_admin_generation_job_trace_requires_admin_auth`
|
||||
- 断言未通过 admin guard 时返回 `401`
|
||||
|
||||
## 4. 当前验证结果
|
||||
|
||||
已执行：
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
结果：
|
||||
|
||||
- 定向生成任务 + admin trace 测试：`31 passed`
|
||||
- 后端全量测试：`155 passed`
|
||||
- Ruff：`All checks passed!`
|
||||
- 用户前端构建：通过
|
||||
- 管理端构建：通过
|
||||
|
||||
补充敏感公开面扫描：
|
||||
|
||||
```bash
|
||||
rg -n "evaluations/analytics|EvaluationAnalytics|admin_evaluation|overall_score|golden|replay|evaluation_policy|provider_override|internal_dispatch_token" frontend/src backend/app/schemas backend/app/api/stories.py backend/app/services/generation_jobs.py
|
||||
```
|
||||
|
||||
结果：无命中。用户前端、公开 schema、用户 API 和用户 job service 未暴露评测 analytics、评分、golden/replay 或内部 request payload 字段。
|
||||
|
||||
构建提示：
|
||||
|
||||
- `frontend` 和 `admin-frontend` 构建均提示 Browserslist/caniuse-lite 数据较旧。
|
||||
- `admin-frontend` 额外提示 `baseline-browser-mapping` 数据较旧。
|
||||
- 以上均为依赖数据 freshness 提示，不影响当前构建结果。
|
||||
|
||||
## 5. 自审结论
|
||||
|
||||
本阶段把 trace 数据访问明确分成两层：
|
||||
|
||||
- 用户层：只看可用功能、进度、资源状态和少量安全控制字段。
|
||||
- 管理层：在 admin guard 后查看完整内部链路，用于调试、审查和评测驱动改进。
|
||||
|
||||
这满足“用户前端不能展示评测数据”的要求，并且比阶段 10 更稳：即使后续内部调度把更多策略字段写入 request payload，用户接口也不会默认公开。
|
||||
|
||||
## 6. Bug 与风险记录
|
||||
|
||||
已发现并即时修复的问题：
|
||||
|
||||
- 无新增运行时 bug。
|
||||
|
||||
当前风险：
|
||||
|
||||
- admin-frontend 当前还没有专门调用 `/admin/generations/jobs/{job_id}/trace` 的页面；管理端如果继续复用用户接口，看到的仍是脱敏 trace。这是安全默认值，但内部排障体验还可以继续增强。
|
||||
- 用户 request payload 白名单当前保守，不返回 `data` 和 `education_theme`。如果未来用户端确实需要展示“我刚才输入了什么”，应设计单独的用户输入回显字段，并避免混入内部调度字段。
|
||||
- admin trace 返回完整内部 metadata，必须继续保持在 admin-only router 下，不得被用户前端或公开 API 复用。
|
||||
|
||||
## 7. 后续建议
|
||||
|
||||
下一阶段建议进入阶段 12：
|
||||
|
||||
1. 推进 executor 小步接管，让 `WorkflowPlan` 从“记录计划”逐步变成“驱动最小任务执行”。
|
||||
2. 先选择资产生成或 asset retry 作为低风险 executor 试点。
|
||||
3. 管理端可后续增加 trace detail UI，但必须调用 admin-only endpoint，并明确标记为内部审查视图。
|
||||
150
docs/planning/harness-stage-12-report.md
Normal file
150
docs/planning/harness-stage-12-report.md
Normal file
@@ -0,0 +1,150 @@
|
||||
# Harness Engineering 改造阶段 12 报告
|
||||
|
||||
**阶段**: 12 - Plan-Driven Asset Executor 试点
|
||||
**日期**: 2026-06-22
|
||||
**状态**: 已完成当前切片
|
||||
**范围**: 资产任务 executor 最小接管、后台资产生成/资源重试/旧资源接口接入、回归测试和用户公开面边界复核
|
||||
|
||||
---
|
||||
|
||||
## 1. 本阶段目标
|
||||
|
||||
阶段 12 的目标是让 `WorkflowPlan` 不再只是 trace 快照，而是开始驱动一部分真实执行。为了控制风险，本阶段只接管资产任务，不迁移主文本生成、评测和故事持久化。
|
||||
|
||||
本阶段重点：
|
||||
|
||||
- 新增 plan-driven asset runner。
|
||||
- 后台 `asset_generation` 按 plan task key 执行图片/音频任务。
|
||||
- 同步 `asset_retry` 按 plan task key 执行图片/音频重试。
|
||||
- 旧封面和音频兼容接口也通过同一个 runner 执行。
|
||||
- 保留既有 asset workflow 对 provider、缓存、状态同步、取消检查和事件记录的职责。
|
||||
|
||||
## 2. 已完成工作
|
||||
|
||||
### Asset Executor Runner
|
||||
|
||||
修改文件：
|
||||
|
||||
- `backend/app/services/harness/executor.py`
|
||||
|
||||
新增能力：
|
||||
|
||||
- `AssetPlanRunResult`
|
||||
- `run_asset_plan(...)`
|
||||
|
||||
执行规则：
|
||||
|
||||
- 只支持 `asset_generation` 和 `asset_retry` plan。
|
||||
- `complete_image_asset` 调用 image handler。
|
||||
- `complete_audio_asset` 调用 audio handler。
|
||||
- `start_asset_*`、`complete_asset_*` 和未知非资产 task 记录为 ignored，不触发 provider handler。
|
||||
- 返回 task results、executed task keys 和 ignored task keys，便于单测和后续观测扩展。
|
||||
|
||||
### Story Service 接入
|
||||
|
||||
修改文件：
|
||||
|
||||
- `backend/app/services/story_service.py`
|
||||
|
||||
已接入路径：
|
||||
|
||||
- 后台 `asset_generation` worker。
|
||||
- 同步 `retry_story_assets`。
|
||||
- 旧 `generate_story_cover`。
|
||||
- 旧 `generate_story_audio`。
|
||||
|
||||
保持不变的职责：
|
||||
|
||||
- 图片/音频 provider 调用仍在 `asset_workflows`。
|
||||
- 音频缓存读写仍在 `asset_workflows`。
|
||||
- story 状态同步仍在 `asset_workflows`。
|
||||
- `cover_image_*`、`audio_*`、`storybook_*image*` 事件仍由 asset workflow 记录。
|
||||
- job 完成/失败语义保持原有 `finish_generation_job` 路径。
|
||||
|
||||
## 3. 测试覆盖
|
||||
|
||||
修改文件：
|
||||
|
||||
- `backend/tests/test_harness_runtime.py`
|
||||
- `backend/tests/test_generation_jobs.py`
|
||||
- `backend/tests/harness-evaluation-test-cases.md`
|
||||
|
||||
新增覆盖：
|
||||
|
||||
- `test_run_asset_plan_executes_asset_tasks_in_plan_order`
|
||||
- 验证 runner 按 plan task 顺序执行音频和图片。
|
||||
- 验证非资产生产 task 被记录为 ignored。
|
||||
- `test_run_asset_plan_ignores_unknown_non_asset_tasks`
|
||||
- 验证未知非资产 task 不触发 handler。
|
||||
- `test_asset_generation_job_worker_executes_assets_in_plan_order`
|
||||
- 验证后台组合资产 job 按 plan 顺序先生成音频再生成图片。
|
||||
- 验证 story 的 `audio_status` 和 `image_status` 均为 `ready`。
|
||||
- 验证 event stream 与 plan tasks 对齐。
|
||||
|
||||
## 4. 当前验证结果
|
||||
|
||||
已执行：
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
结果：
|
||||
|
||||
- Harness runtime + generation job 定向测试：`48 passed`
|
||||
- 后端全量测试：`158 passed`
|
||||
- Ruff：`All checks passed!`
|
||||
- 用户前端构建：通过
|
||||
- 管理端构建：通过
|
||||
|
||||
补充敏感公开面扫描：
|
||||
|
||||
```bash
|
||||
rg -n "evaluations/analytics|EvaluationAnalytics|admin_evaluation|overall_score|golden|replay|evaluation_policy|provider_override|internal_dispatch_token" frontend/src backend/app/schemas backend/app/api/stories.py backend/app/services/generation_jobs.py
|
||||
```
|
||||
|
||||
结果：无命中。用户前端、公开 schema、用户 API 和用户 job service 未暴露评测 analytics、评分、golden/replay 或内部 request payload 字段。
|
||||
|
||||
构建提示：
|
||||
|
||||
- `frontend` 和 `admin-frontend` 构建均提示 Browserslist/caniuse-lite 数据较旧。
|
||||
- `admin-frontend` 额外提示 `baseline-browser-mapping` 数据较旧。
|
||||
- 以上均为依赖数据 freshness 提示，不影响当前构建结果。
|
||||
|
||||
## 5. 自审结论
|
||||
|
||||
本阶段完成了 executor 接管的第一步，但没有扩大到主生成链路：
|
||||
|
||||
- `WorkflowPlan` 已能驱动资产 task 执行。
|
||||
- asset workflow 仍保持单一职责，负责真实 provider 调用和状态转换。
|
||||
- 事件流与用户可见行为保持兼容。
|
||||
- 用户侧仍只看到 coarse plan metadata；原始 `plan.tasks`、评测结果和内部调度数据不进入用户接口。
|
||||
|
||||
这个切片足够小，失败时也容易回滚：只需要把资产入口从 `run_asset_plan` 调回原来的顺序 `if "image"` / `if "audio"` 分支。
|
||||
|
||||
## 6. Bug 与风险记录
|
||||
|
||||
已发现并即时修复的问题：
|
||||
|
||||
- 接入 runner 后，原来的 `_retry_*` 私有薄封装不再被调用。已删除这些死代码，避免后续误读。
|
||||
|
||||
当前风险：
|
||||
|
||||
- `run_asset_plan` 当前只解释图片和音频 task，未知资产默认 ignored。未来如果新增视频、角色设定图等资产，需要显式增加 handler，而不是依赖 unknown task。
|
||||
- 主文本生成、评测和持久化仍未由 executor 驱动；它们当前仍是 plan-aware trace，而不是 plan-driven execution。
|
||||
- runner 当前不单独写入 task-level start/finish 事件，仍复用 asset workflow 的现有事件。若后续需要更细粒度 executor 审计，可以增加 admin-only 内部事件，但不能默认进入用户侧。
|
||||
|
||||
## 7. 后续建议
|
||||
|
||||
下一阶段建议进入阶段 13：
|
||||
|
||||
1. 将 `WorkflowPlan` 的 task result 纳入 admin-only trace 聚合，便于看 executor 执行覆盖率。
|
||||
2. 选择主文本生成中的低风险 task，例如 `queue_postprocessing` 或 `complete_generation`，继续小步接管。
|
||||
3. 若要接管 `evaluate_narrative`，必须先补更明确的评测数据隔离测试，避免任何评分字段进入用户前端。
|
||||
182
docs/planning/harness-stage-13-report.md
Normal file
182
docs/planning/harness-stage-13-report.md
Normal file
@@ -0,0 +1,182 @@
|
||||
# Harness Engineering 改造阶段 13 报告
|
||||
|
||||
**阶段**: 13 - Admin-Only Executor Coverage
|
||||
**日期**: 2026-06-23
|
||||
**状态**: 已完成当前切片
|
||||
**范围**: 内部 executor coverage 事件、admin-only coverage 聚合、用户侧 executor 数据隔离、回归测试
|
||||
|
||||
---
|
||||
|
||||
## 1. 本阶段目标
|
||||
|
||||
阶段 13 承接阶段 12 的 plan-driven asset executor：资产任务已经按 `WorkflowPlan` 执行，但内部还缺少跨 job 的覆盖率视角。本阶段把 executor 执行结果记录为内部事件，并新增管理控制面聚合，帮助我们审查计划任务是否真的被执行。
|
||||
|
||||
本阶段目标：
|
||||
|
||||
- 资产 executor 完成后写入内部 `executor_completed` 事件。
|
||||
- 管理端可聚合 executor runs、planned/executed/ignored task counts、task keys 和 result assets。
|
||||
- 用户端继续看不到 executor task keys、coverage metadata 或内部 executor step。
|
||||
|
||||
## 2. 已完成工作
|
||||
|
||||
### Executor Coverage Metadata
|
||||
|
||||
修改文件：
|
||||
|
||||
- `backend/app/services/harness/executor.py`
|
||||
- `backend/app/services/story_service.py`
|
||||
|
||||
新增能力：
|
||||
|
||||
- `AssetPlanRunResult.result_assets`
|
||||
- `AssetPlanRunResult.to_metadata(...)`
|
||||
- `record_executor_result(...)`
|
||||
|
||||
内部 metadata 包含：
|
||||
|
||||
- `plan_mode`
|
||||
- `planned_task_count`
|
||||
- `executed_task_count`
|
||||
- `ignored_task_count`
|
||||
- `result_count`
|
||||
- `executed_task_keys`
|
||||
- `ignored_task_keys`
|
||||
- `result_assets`
|
||||
|
||||
已接入路径：
|
||||
|
||||
- 后台 `asset_generation`
|
||||
- 同步 `asset_retry`
|
||||
- 旧 `generate_story_cover`
|
||||
- 旧 `generate_story_audio`
|
||||
|
||||
### Admin-Only Coverage Analytics
|
||||
|
||||
新增文件：
|
||||
|
||||
- `backend/app/services/admin_executor_coverage.py`
|
||||
|
||||
修改文件：
|
||||
|
||||
- `backend/app/api/admin_providers.py`
|
||||
|
||||
新增接口：
|
||||
|
||||
```http
|
||||
GET /admin/executors/coverage
|
||||
```
|
||||
|
||||
支持过滤：
|
||||
|
||||
```http
|
||||
GET /admin/executors/coverage?days=7
|
||||
GET /admin/executors/coverage?plan_mode=asset_retry
|
||||
```
|
||||
|
||||
返回聚合：
|
||||
|
||||
- total runs
|
||||
- total planned/executed/ignored task counts
|
||||
- coverage ratio
|
||||
- job/story/user counts
|
||||
- by plan mode
|
||||
- by output mode
|
||||
- executed task keys
|
||||
- ignored task keys
|
||||
- result assets
|
||||
|
||||
### 用户侧隔离
|
||||
|
||||
修改文件：
|
||||
|
||||
- `backend/app/services/generation_jobs.py`
|
||||
|
||||
隔离规则：
|
||||
|
||||
- 用户 job detail 过滤 `executor_completed` 事件。
|
||||
- 用户 job summary 如果内部 `current_step=executor_completed`，对外映射为 `workflow_planned` 和“工作流已规划”。
|
||||
- 用户公开 metadata 白名单不包含 executor task keys 或 coverage 字段。
|
||||
|
||||
## 3. 测试覆盖
|
||||
|
||||
修改文件：
|
||||
|
||||
- `backend/tests/test_generation_jobs.py`
|
||||
- `backend/tests/test_admin_providers.py`
|
||||
- `backend/tests/harness-evaluation-test-cases.md`
|
||||
|
||||
新增或更新覆盖：
|
||||
|
||||
- 资产生成/重试事件序列包含内部 `executor_completed`。
|
||||
- 用户 job detail 不返回 `executor_completed` 或 task keys。
|
||||
- 用户 job summary 不暴露内部 executor step。
|
||||
- admin trace 可读取完整 `executor_completed`。
|
||||
- admin coverage 聚合 total runs、task counts、coverage ratio、task keys 和 result assets。
|
||||
- admin coverage 支持 `plan_mode` 过滤并拒绝非法 plan mode。
|
||||
- admin coverage 未鉴权返回 `401`。
|
||||
|
||||
## 4. 当前验证结果
|
||||
|
||||
已执行：
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
结果：
|
||||
|
||||
- 定向 generation/admin/harness 测试：`59 passed`
|
||||
- 后端全量测试：`161 passed`
|
||||
- Ruff：`All checks passed!`
|
||||
- 用户前端构建：通过
|
||||
- 管理端构建：通过
|
||||
|
||||
补充敏感公开面扫描：
|
||||
|
||||
```bash
|
||||
rg -n "executors/coverage|ExecutorCoverage|admin_executor|executor_completed|executed_task_keys|ignored_task_keys|coverage_ratio|overall_score|golden|replay|evaluation_policy|provider_override|internal_dispatch_token" frontend/src backend/app/schemas backend/app/api/stories.py backend/app/services/generation_jobs.py
|
||||
```
|
||||
|
||||
结果：仅命中 `backend/app/services/generation_jobs.py` 中对 `executor_completed` 的过滤和 current step 映射逻辑。用户前端、公开 schema 和用户 API route 未暴露 executor coverage、task keys、评测分数、golden/replay 或内部 request payload 字段。
|
||||
|
||||
构建提示：
|
||||
|
||||
- `frontend` 和 `admin-frontend` 构建均提示 Browserslist/caniuse-lite 数据较旧。
|
||||
- `admin-frontend` 额外提示 `baseline-browser-mapping` 数据较旧。
|
||||
- 以上均为依赖数据 freshness 提示，不影响当前构建结果。
|
||||
|
||||
## 5. 自审结论
|
||||
|
||||
本阶段保留了“内部完整、用户最小”的边界：
|
||||
|
||||
- executor task keys 是内部执行证据，只进入 admin-only trace/coverage。
|
||||
- 用户端仍只看到可用功能和进度，不看到 task keys、coverage ratio 或内部 executor step。
|
||||
- admin coverage 聚合不返回故事正文、prompt 或评测评分 reason。
|
||||
|
||||
## 6. Bug 与风险记录
|
||||
|
||||
已发现并即时修复的问题：
|
||||
|
||||
- 初版 admin coverage bucket 使用通用模型，响应中出现无关字段 `null`。已拆成专用 bucket response model，减少管理端响应噪声。
|
||||
- `executor_completed` 会短暂写入 `job.current_step`。已在用户 summary 中映射为安全公开的 `workflow_planned`，并补测试防止泄露。
|
||||
|
||||
当前风险：
|
||||
|
||||
- `executor_completed` 当前只覆盖资产 executor。主文本、评测和持久化仍是 plan-aware，不应被 coverage 误解为全链路 executor 覆盖。
|
||||
- coverage ratio 使用 executed/planned 任务数，包含 start/complete 这类 ignored task，因此是执行器覆盖口径，不是产品成功率。
|
||||
- admin coverage 返回 task keys，必须保持 admin-only，不允许用户前端调用。
|
||||
|
||||
## 7. 后续建议
|
||||
|
||||
下一阶段建议进入阶段 14：
|
||||
|
||||
1. 在 admin trace detail 中增加 executor coverage summary，减少管理端自行解析事件。
|
||||
2. 选择 `queue_postprocessing` 或 `complete_generation` 这类低风险主链路 task 继续小步接管。
|
||||
3. 若要接管评测 task，先补更严格的用户侧敏感扫描和 contract tests。
|
||||
188
docs/planning/harness-stage-14-report.md
Normal file
188
docs/planning/harness-stage-14-report.md
Normal file
@@ -0,0 +1,188 @@
|
||||
# Harness Engineering 阶段 14 报告
|
||||
|
||||
**阶段**: Admin Trace Executor Coverage Summary
|
||||
**日期**: 2026-06-23
|
||||
**状态**: 已完成当前切片
|
||||
|
||||
## 1. 阶段目标
|
||||
|
||||
本阶段继续沿用原架构路径，不扩大 executor 对主文本生成、评测或持久化的接管范围，只增强管理控制面的审查能力。
|
||||
|
||||
目标：
|
||||
|
||||
- 让 admin-only 完整 generation trace 自带当前 job 的 executor coverage 摘要。
|
||||
- 复用全局 executor coverage 聚合逻辑，避免全局 coverage 与单 job trace 统计口径漂移。
|
||||
- 修正用户 trace summary 隔离规则，确保内部 `executor_completed` 不通过聚合数量、task key 或 result asset 泄露到用户侧。
|
||||
|
||||
## 2. 完成内容
|
||||
|
||||
### H14-1: 抽出 executor coverage 纯聚合函数
|
||||
|
||||
- 在 `app/services/admin_executor_coverage.py` 中新增 `summarize_executor_coverage_rows(...)`。
|
||||
- `GET /admin/executors/coverage` 继续返回原有结构，但内部改为复用共享聚合函数。
|
||||
- 聚合口径保持不变：runs、planned/executed/ignored task counts、coverage ratio、plan mode、output mode、task keys 和 result assets。
|
||||
|
||||
### H14-2: admin trace 返回 `executor_coverage`
|
||||
|
||||
- `app/services/admin_generation_trace.py` 在完整事件流之外，新增当前 job 的 `executor_coverage` 摘要。
|
||||
- trace 内嵌 summary 的 `scope` 为 `admin_internal_job_executor_coverage`。
|
||||
- `app/api/admin_providers.py` 的 `AdminGenerationJobTraceResponse` 增加 `executor_coverage` 字段。
|
||||
|
||||
### H14-3: 用户 trace summary 过滤 `executor_completed`
|
||||
|
||||
- `app/services/generation_jobs.py` 的 trace summary 聚合现在同时跳过 `evaluation_completed` 和 `executor_completed`。
|
||||
- 用户侧仍然只看到产品可解释的 workflow 进度，不看到内部 executor coverage、task keys 或 result assets。
|
||||
|
||||
### H14-4: 测试覆盖
|
||||
|
||||
- `tests/test_admin_providers.py` 增加 admin trace 内嵌 executor coverage 断言。
|
||||
- `tests/test_generation_jobs.py` 增加用户 trace summary 不包含 `executor_completed` 和 task key 的断言。
|
||||
- `backend/tests/harness-evaluation-test-cases.md` 增加 TC-ADM-008，并更新 TC-ST-010。
|
||||
|
||||
### H14-5: 文档同步
|
||||
|
||||
- `docs/technical/harness-engineering-modernization.md` 更新至阶段 0-14。
|
||||
- 新增 `Admin Trace Executor Coverage Summary` 设计章节。
|
||||
- 增加 FR-015、NFR-011、阶段 14 计划、风险缓解和当前状态。
|
||||
|
||||
## 3. 审查结论
|
||||
|
||||
### 用户侧商业机密隔离
|
||||
|
||||
本阶段没有向用户端新增任何 evaluation 或 executor coverage 数据。
|
||||
|
||||
用户侧继续隐藏：
|
||||
|
||||
- `evaluation_completed`
|
||||
- `executor_completed`
|
||||
- `overall_score`
|
||||
- 评分维度、阈值、golden replay
|
||||
- `executed_task_keys`
|
||||
- `ignored_task_keys`
|
||||
- `executor_coverage`
|
||||
|
||||
额外修正：
|
||||
|
||||
- 用户 trace summary 的 `total_events` 不再统计内部 `executor_completed`，避免通过事件数量暴露内部执行器步骤。
|
||||
|
||||
### 管理端审查能力
|
||||
|
||||
管理端现在可以在单个 trace 响应里同时查看：
|
||||
|
||||
- 完整 request payload。
|
||||
- 完整 event stream。
|
||||
- 完整 evaluation metadata。
|
||||
- 当前 job 的 executor coverage summary。
|
||||
|
||||
这让后续排查 plan-driven executor 迁移时，不必在完整 trace 和全局 coverage API 之间手动拼接数据。
|
||||
|
||||
### 架构边界
|
||||
|
||||
本阶段仍保持阶段 12 的保守边界：
|
||||
|
||||
- executor 只接管资产 task key。
|
||||
- 主文本生成、绘本主结构、评测和持久化仍走原服务路径。
|
||||
- admin-only 聚合能力不改变用户 API schema。
|
||||
|
||||
## 4. 验证记录
|
||||
|
||||
已通过：
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
.venv/bin/python -m pytest tests/test_admin_providers.py tests/test_generation_jobs.py tests/test_harness_runtime.py -q
|
||||
```
|
||||
|
||||
结果：
|
||||
|
||||
```text
|
||||
59 passed
|
||||
```
|
||||
|
||||
已通过：
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
.venv/bin/python -m ruff check app tests
|
||||
```
|
||||
|
||||
结果：
|
||||
|
||||
```text
|
||||
All checks passed!
|
||||
```
|
||||
|
||||
已通过：
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
.venv/bin/python -m pytest
|
||||
```
|
||||
|
||||
结果：
|
||||
|
||||
```text
|
||||
161 passed
|
||||
```
|
||||
|
||||
已通过：
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm run build
|
||||
```
|
||||
|
||||
结果：
|
||||
|
||||
```text
|
||||
vue-tsc && vite build
|
||||
✓ built
|
||||
```
|
||||
|
||||
备注：Browserslist 数据陈旧警告，不影响构建结果。
|
||||
|
||||
已通过：
|
||||
|
||||
```bash
|
||||
cd admin-frontend
|
||||
npm run build
|
||||
```
|
||||
|
||||
结果：
|
||||
|
||||
```text
|
||||
vue-tsc && vite build
|
||||
✓ built
|
||||
```
|
||||
|
||||
备注：Browserslist 与 baseline-browser-mapping 数据陈旧警告，不影响构建结果。
|
||||
|
||||
已通过用户侧敏感字段扫描：
|
||||
|
||||
```bash
|
||||
rg -n "executors/coverage|ExecutorCoverage|admin_executor|executor_coverage|executor_completed|executed_task_keys|ignored_task_keys|coverage_ratio|overall_score|golden|replay|evaluation_policy|provider_override|internal_dispatch_token" frontend/src backend/app/schemas backend/app/api/stories.py backend/app/services/generation_jobs.py
|
||||
```
|
||||
|
||||
扫描结果：
|
||||
|
||||
- 未在用户前端、用户 schema 或用户 story API 中发现 admin executor coverage、评测分数、golden replay、provider override 或内部 dispatch token。
|
||||
- 命中项仅位于 `generation_jobs.py` 的内部事件过滤和安全进度映射逻辑。
|
||||
|
||||
已通过：
|
||||
|
||||
```bash
|
||||
git diff --check
|
||||
```
|
||||
|
||||
## 5. 风险与后续建议
|
||||
|
||||
| 风险 | 状态 | 建议 |
|
||||
| --- | --- | --- |
|
||||
| admin trace 与全局 coverage 口径漂移 | 已缓解 | 已抽共享聚合函数，后续新增字段必须先进该函数 |
|
||||
| 用户 trace summary 暗含内部事件数量 | 已修正 | 保持内部事件 denylist，并继续用测试覆盖 |
|
||||
| executor 接管范围扩大过快 | 已控制 | 下一阶段仍应先围绕资产与 observability，不急于接管主生成 |
|
||||
| admin-only 数据误接用户前端 | 持续关注 | 每阶段继续运行敏感字段扫描 |
|
||||
|
||||
## 6. 阶段结论
|
||||
|
||||
阶段 14 完成了 admin trace 的审查能力增强，并补齐用户 trace summary 对 executor 内部事件的隔离。当前架构继续符合“评测驱动、admin-only 内部质量资产、用户侧只展示可用功能”的边界。
|
||||
228
docs/planning/harness-stage-15-report.md
Normal file
228
docs/planning/harness-stage-15-report.md
Normal file
@@ -0,0 +1,228 @@
|
||||
# Harness Engineering 阶段 15 报告
|
||||
|
||||
**阶段**: Admin-Only Harness Readiness
|
||||
**日期**: 2026-06-23
|
||||
**状态**: 已完成当前切片
|
||||
|
||||
## 1. 阶段目标
|
||||
|
||||
本阶段继续沿用原设计路径：不扩大 executor 对主生成链路的接管范围，而是建立一个内部 readiness 审查摘要，让后续每次扩大 harness 接管范围前都能先看聚合质量门。
|
||||
|
||||
目标：
|
||||
|
||||
- 将内部 golden replay、evaluation analytics 和 executor coverage 串成一个 admin-only readiness audit。
|
||||
- 保持 readiness 只返回聚合状态、阈值和覆盖摘要。
|
||||
- 避免把评测数据、executor task key 或 readiness 结果分发到用户端。
|
||||
- 修正运行环境风险：golden replay fixture 必须随 app 发布，而不是只存在于 tests 目录。
|
||||
|
||||
## 2. 完成内容
|
||||
|
||||
### H15-1: app 内部 golden replay fixture
|
||||
|
||||
- 将 `evaluation_golden_cases.json` 放入 `app/services/harness/fixtures/`。
|
||||
- `tests/test_harness_runtime.py` 改为读取 app 内部 fixture。
|
||||
- 这样 Docker 镜像 `COPY app ./app` 后，admin readiness 仍能读取 golden cases。
|
||||
|
||||
### H15-2: admin harness readiness 服务
|
||||
|
||||
- 新增 `app/services/admin_harness_readiness.py`。
|
||||
- 聚合输入：
|
||||
- 内部 golden replay。
|
||||
- `get_admin_evaluation_analytics(...)`。
|
||||
- `get_admin_executor_coverage(...)`。
|
||||
- 输出：
|
||||
- `status`: `ready`、`needs_attention` 或 `blocked`。
|
||||
- `thresholds`: 当前内部 readiness 阈值。
|
||||
- `checks`: 每个质量门的状态与聚合细节。
|
||||
- `golden_replay`、`evaluation_analytics`、`executor_coverage` 聚合摘要。
|
||||
|
||||
当前 checks：
|
||||
|
||||
| Check | 行为 |
|
||||
| --- | --- |
|
||||
| `golden_replay` | golden cases 未全部通过则 `blocked` |
|
||||
| `runtime_evaluation_samples` | 当前窗口没有 evaluation 样本则 `needs_attention` |
|
||||
| `runtime_evaluation_quality` | pass rate 或 average score 低于阈值则 `blocked` |
|
||||
| `executor_coverage_samples` | 当前窗口没有 executor run 则 `needs_attention` |
|
||||
| `executor_coverage_ratio` | coverage ratio 低于阈值则 `blocked` |
|
||||
|
||||
### H15-3: admin-only readiness API
|
||||
|
||||
- 新增 `GET /admin/harness/readiness`。
|
||||
- 复用 admin router 的 `admin_guard`。
|
||||
- 支持 `days` 查询参数，与 evaluation analytics 和 executor coverage 的窗口口径一致。
|
||||
|
||||
### H15-4: 测试覆盖
|
||||
|
||||
- `tests/test_admin_providers.py` 新增 readiness ready 路径测试。
|
||||
- 新增 low runtime quality blocked 路径测试。
|
||||
- 新增 admin auth required 测试。
|
||||
- 测试断言 readiness 响应不包含 story title、score reason 或 quality gate message。
|
||||
|
||||
### H15-5: 文档同步
|
||||
|
||||
- `docs/technical/harness-engineering-modernization.md` 更新至阶段 0-15。
|
||||
- `backend/tests/harness-evaluation-test-cases.md` 新增 TC-ADM-009、TC-ADM-010。
|
||||
- 本报告记录安全边界、审查结论和验证结果。
|
||||
|
||||
## 3. 审查结论
|
||||
|
||||
### 用户侧商业机密隔离
|
||||
|
||||
本阶段没有新增用户端接口、用户前端类型或用户前端展示。
|
||||
|
||||
用户侧继续不可见：
|
||||
|
||||
- `GET /admin/harness/readiness`
|
||||
- `golden_replay`
|
||||
- `evaluation_analytics`
|
||||
- `executor_coverage`
|
||||
- `overall_score`
|
||||
- 评分维度、评分 reason、阈值
|
||||
- `executed_task_keys`
|
||||
- `ignored_task_keys`
|
||||
- quality gate message
|
||||
|
||||
### 管理端输出边界
|
||||
|
||||
readiness 是 admin-only 聚合摘要。它允许管理端看到：
|
||||
|
||||
- 当前窗口的运行期 evaluation 聚合。
|
||||
- 当前窗口的 executor coverage 聚合。
|
||||
- golden replay 是否通过及覆盖标签分布。
|
||||
- readiness checks 和阈值。
|
||||
|
||||
它不返回：
|
||||
|
||||
- 故事正文。
|
||||
- 绘本分页正文。
|
||||
- 用户 prompt。
|
||||
- cover prompt。
|
||||
- score reason。
|
||||
- quality gate message。
|
||||
- 单条 evaluation event 或 executor event 明细。
|
||||
|
||||
### 架构边界
|
||||
|
||||
阶段 15 没有改变生成执行路径：
|
||||
|
||||
- 主文本生成仍走现有 service。
|
||||
- 绘本主结构仍走现有 service。
|
||||
- executor 仍只接管资产 task key。
|
||||
- readiness 只读聚合数据，不写入 job 或 story 状态。
|
||||
|
||||
## 4. 验证记录
|
||||
|
||||
已通过：
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
.venv/bin/python -m pytest tests/test_admin_providers.py -q
|
||||
```
|
||||
|
||||
结果：
|
||||
|
||||
```text
|
||||
13 passed
|
||||
```
|
||||
|
||||
已通过：
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
.venv/bin/python -m pytest tests/test_admin_providers.py tests/test_harness_runtime.py -q
|
||||
```
|
||||
|
||||
结果：
|
||||
|
||||
```text
|
||||
37 passed
|
||||
```
|
||||
|
||||
已通过：
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
.venv/bin/python -m ruff check app tests
|
||||
```
|
||||
|
||||
结果：
|
||||
|
||||
```text
|
||||
All checks passed!
|
||||
```
|
||||
|
||||
已通过：
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
.venv/bin/python -m pytest
|
||||
```
|
||||
|
||||
结果：
|
||||
|
||||
```text
|
||||
164 passed
|
||||
```
|
||||
|
||||
已通过：
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm run build
|
||||
```
|
||||
|
||||
结果：
|
||||
|
||||
```text
|
||||
vue-tsc && vite build
|
||||
✓ built
|
||||
```
|
||||
|
||||
备注：Browserslist 数据陈旧警告，不影响构建结果。
|
||||
|
||||
已通过：
|
||||
|
||||
```bash
|
||||
cd admin-frontend
|
||||
npm run build
|
||||
```
|
||||
|
||||
结果：
|
||||
|
||||
```text
|
||||
vue-tsc && vite build
|
||||
✓ built
|
||||
```
|
||||
|
||||
备注：Browserslist 与 baseline-browser-mapping 数据陈旧警告，不影响构建结果。
|
||||
|
||||
已通过用户侧敏感字段扫描：
|
||||
|
||||
```bash
|
||||
rg -n "harness/readiness|HarnessReadiness|admin_harness|golden_replay|evaluation_analytics|executor_coverage|executors/coverage|ExecutorCoverage|admin_executor|executor_completed|executed_task_keys|ignored_task_keys|coverage_ratio|overall_score|golden|replay|evaluation_policy|provider_override|internal_dispatch_token" frontend/src backend/app/schemas backend/app/api/stories.py backend/app/services/generation_jobs.py
|
||||
```
|
||||
|
||||
扫描结果：
|
||||
|
||||
- 未在用户前端、用户 schema 或用户 story API 中发现 readiness、admin evaluation analytics、executor coverage、评分、golden replay、provider override 或内部 dispatch token。
|
||||
- 命中项仅位于 `generation_jobs.py` 的内部事件过滤和安全进度映射逻辑。
|
||||
|
||||
已通过：
|
||||
|
||||
```bash
|
||||
git diff --check
|
||||
```
|
||||
|
||||
## 5. 风险与后续建议
|
||||
|
||||
| 风险 | 状态 | 建议 |
|
||||
| --- | --- | --- |
|
||||
| 生产镜像缺少 golden fixture | 已修正 | fixture 已放入 app 内部 harness fixtures |
|
||||
| readiness 结果被误接用户前端 | 持续关注 | 保持 admin-only 路由，并继续运行敏感字段扫描 |
|
||||
| 阈值过于简单 | 可接受 | 当前为阶段 15 最小门槛，后续可按真实样本调优 |
|
||||
| readiness 输出过细 | 已控制 | 只返回聚合，不返回原文、prompt、reason 或单条事件 |
|
||||
|
||||
## 6. 阶段结论
|
||||
|
||||
阶段 15 建立了 admin-only harness readiness 审查能力，把评测驱动从“有测试、有 analytics”推进到“扩大接管范围前有聚合质量门”。用户端仍然只展示可用功能和进度，不接触评测数据、内部执行覆盖或 readiness 结果。
|
||||
140
docs/planning/harness-stage-5-report.md
Normal file
140
docs/planning/harness-stage-5-report.md
Normal file
@@ -0,0 +1,140 @@
|
||||
# Harness Engineering 改造阶段 5 报告
|
||||
|
||||
**阶段**: 5 - Trace Analytics 与前端增量展示
|
||||
**日期**: 2026-06-21
|
||||
**状态**: 已完成
|
||||
**范围**: 后端 trace summary 聚合、用户端与管理端生成轨迹展示、完整验证
|
||||
|
||||
---
|
||||
|
||||
## 1. 本阶段目标
|
||||
|
||||
阶段 5 的目标是让阶段 1-4 写入的标准 harness metadata 变成可见、可分析的产品能力。
|
||||
|
||||
本阶段明确区分两类统计：
|
||||
|
||||
- Provider stats：只统计 Provider 调用成功率、延迟、成本和供应商失败。
|
||||
- Trace summary：统计 workflow step、artifact、failure category 等 harness 运行时语义。
|
||||
|
||||
这样质量门失败不会被误算为供应商失败，供应商看板和生成工作流看板各自保持语义清楚。
|
||||
|
||||
## 2. 已完成工作
|
||||
|
||||
### 后端
|
||||
|
||||
修改文件：
|
||||
|
||||
- `backend/app/schemas/story_schemas.py`
|
||||
- `backend/app/services/generation_jobs.py`
|
||||
- `backend/app/api/stories.py`
|
||||
- `backend/tests/test_generation_jobs.py`
|
||||
|
||||
新增 API：
|
||||
|
||||
```http
|
||||
GET /api/generations/{story_id}/trace-summary
|
||||
```
|
||||
|
||||
响应字段：
|
||||
|
||||
- `story_id`
|
||||
- `window_days`
|
||||
- `total_events`
|
||||
- `failed_events`
|
||||
- `by_step`
|
||||
- `by_artifact`
|
||||
- `failure_categories`
|
||||
|
||||
新增聚合能力：
|
||||
|
||||
- workflow step 聚合，例如 `image_generation`、`narrative_generation`
|
||||
- artifact 聚合，例如 `cover_image`、`story_text`
|
||||
- failure category 聚合，例如 `provider_error`、`schema_error`
|
||||
|
||||
### 用户端
|
||||
|
||||
修改文件：
|
||||
|
||||
- `frontend/src/types/generation.ts`
|
||||
- `frontend/src/components/GenerationTrace.vue`
|
||||
|
||||
新增展示：
|
||||
|
||||
- 流程事件总数
|
||||
- 失败事件数
|
||||
- 主要步骤
|
||||
- 主要失败类型
|
||||
- 单个事件下方展示标准 step、artifact、failure category
|
||||
|
||||
### 管理端
|
||||
|
||||
修改文件：
|
||||
|
||||
- `admin-frontend/src/components/GenerationTrace.vue`
|
||||
|
||||
新增展示与用户端保持一致：
|
||||
|
||||
- trace summary 卡片
|
||||
- 事件级 step/artifact/failure category 标签
|
||||
|
||||
## 3. 验证结果
|
||||
|
||||
已执行：
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
.venv/bin/python -m pytest
|
||||
.venv/bin/python -m ruff check app tests
|
||||
|
||||
cd ../frontend
|
||||
npm run build
|
||||
|
||||
cd ../admin-frontend
|
||||
npm run build
|
||||
```
|
||||
|
||||
结果：
|
||||
|
||||
- 后端完整测试：`139 passed`
|
||||
- 后端 ruff：`All checks passed!`
|
||||
- 用户端生产构建：通过
|
||||
- 管理端生产构建：通过
|
||||
|
||||
构建备注：
|
||||
|
||||
- Vite/Browserslist 输出了浏览器数据过期提示，不影响构建结果。
|
||||
- 管理端构建输出了 `baseline-browser-mapping` 数据偏旧提示，不影响构建结果。
|
||||
|
||||
## 4. 自审结论
|
||||
|
||||
本阶段符合设计目标：
|
||||
|
||||
- 没有混淆 Provider stats 和 workflow trace stats。
|
||||
- 前端只做增量展示，没有改变生成/重试主流程。
|
||||
- 新 API 有后端测试覆盖。
|
||||
- 用户端和管理端构建均通过。
|
||||
- 质量门失败、Provider 失败和资产失败现在都有更清楚的可观测语义。
|
||||
|
||||
## 5. 当前新架构状态
|
||||
|
||||
Harness engineering 改造主线已完成阶段 0-5：
|
||||
|
||||
- 设计基线完成。
|
||||
- Harness runtime 基础类型完成。
|
||||
- TraceRecorder 和 ExecutionControl 完成。
|
||||
- 资产工作流主要抽取完成。
|
||||
- WorkflowPlan 建模完成。
|
||||
- 确定性 Quality Gates 完成。
|
||||
- Trace Analytics 和前端展示完成。
|
||||
|
||||
## 6. 后续建议
|
||||
|
||||
下一步建议进入 **阶段 6：新架构实测与执行器小步接管**。
|
||||
|
||||
建议切片：
|
||||
|
||||
1. 使用 Docker demo stack 跑 smoke，验证真实 API/worker/前端联动。
|
||||
2. 在本地 demo provider 下创建故事和绘本，确认 trace summary 数据真实可见。
|
||||
3. 回到阶段 3B，让普通故事无图片路径先由 `WorkflowPlan` 驱动执行。
|
||||
4. 逐步迁移带图片故事、绘本和资产任务执行器。
|
||||
|
||||
222
docs/planning/harness-stage-6-report.md
Normal file
222
docs/planning/harness-stage-6-report.md
Normal file
@@ -0,0 +1,222 @@
|
||||
# Harness Engineering 改造阶段 6 报告
|
||||
|
||||
**阶段**: 6 - 新架构真实运行烟测
|
||||
**日期**: 2026-06-21
|
||||
**状态**: 已完成
|
||||
**范围**: 本地新代码 API、Celery worker、Docker PostgreSQL/Redis、真实 HTTP 生成链路、trace/provider 聚合验证
|
||||
|
||||
---
|
||||
|
||||
## 1. 本阶段目标
|
||||
|
||||
阶段 6 的目标是验证阶段 0-5 的新架构不只在单元测试和构建层面通过，也能在真实运行时闭环中工作。
|
||||
|
||||
本阶段重点验证：
|
||||
|
||||
- FastAPI 可以使用新代码启动。
|
||||
- Celery worker 可以消费新代码派发的 generation job。
|
||||
- `TraceRecorder` 写入的标准 metadata 能被 `trace-summary` 正确聚合。
|
||||
- 主内容生成和资源重试都能进入 harness 运行时视角。
|
||||
- Provider stats 继续只统计 Provider 调用，不与 workflow trace 混淆。
|
||||
|
||||
## 2. 运行环境
|
||||
|
||||
复用 Docker demo stack 中已运行的基础设施：
|
||||
|
||||
- PostgreSQL: `localhost:52432`
|
||||
- Redis: `localhost:52379`
|
||||
|
||||
本地新代码进程：
|
||||
|
||||
- API: `127.0.0.1:53000`
|
||||
- Worker: `celery -A app.core.celery_app worker --concurrency=1`
|
||||
|
||||
启动 API 使用的关键环境变量：
|
||||
|
||||
```bash
|
||||
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'
|
||||
```
|
||||
|
||||
## 3. 已执行烟测
|
||||
|
||||
### 3.1 健康检查
|
||||
|
||||
请求：
|
||||
|
||||
```bash
|
||||
curl -fsS http://127.0.0.1:53000/health
|
||||
```
|
||||
|
||||
结果：
|
||||
|
||||
```json
|
||||
{"status":"ok"}
|
||||
```
|
||||
|
||||
### 3.2 dev 登录与会话验证
|
||||
|
||||
通过 `/auth/dev/signin` 创建真实 cookie 会话，再查询 `/auth/session`。
|
||||
|
||||
结果：
|
||||
|
||||
```text
|
||||
login_status=302
|
||||
user_id=github:dev_user_001
|
||||
```
|
||||
|
||||
### 3.3 普通故事生成链路
|
||||
|
||||
请求：
|
||||
|
||||
```json
|
||||
{
|
||||
"output_mode": "story",
|
||||
"type": "keywords",
|
||||
"data": "星光书签, 小鹿, 学会复盘",
|
||||
"education_theme": "复盘与成长",
|
||||
"generate_images": false
|
||||
}
|
||||
```
|
||||
|
||||
结果：
|
||||
|
||||
```text
|
||||
job_id=a606878c-98a7-4d05-af95-629d0cd2f194
|
||||
poll=01 status=running step=request_accepted story_id=none
|
||||
poll=02 status=completed step=generation_completed story_id=59
|
||||
story_title=星光书签、小鹿、学会复盘的晚安冒险
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- API 成功创建 generation job。
|
||||
- Worker 成功 claim 并执行任务。
|
||||
- 故事成功落库。
|
||||
- job 以 `generation_completed` 收敛。
|
||||
|
||||
### 3.4 主生成 trace summary
|
||||
|
||||
结果：
|
||||
|
||||
```text
|
||||
trace_total_events=8
|
||||
trace_failed_events=0
|
||||
trace_steps=[
|
||||
{"name":"provider_invocation","count":2},
|
||||
{"name":"context_preparation","count":1},
|
||||
{"name":"narrative_generation","count":1},
|
||||
{"name":"story_persistence","count":1}
|
||||
]
|
||||
trace_artifacts=[
|
||||
{"name":"story_text","count":1}
|
||||
]
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- 标准 step 已可聚合。
|
||||
- `story_text` artifact 已可聚合。
|
||||
- 无失败事件。
|
||||
|
||||
### 3.5 图片资源重试链路
|
||||
|
||||
对 story `59` 执行：
|
||||
|
||||
```json
|
||||
{"assets":["image"]}
|
||||
```
|
||||
|
||||
结果：
|
||||
|
||||
```text
|
||||
retry_image_status=ready
|
||||
trace_before_total=8
|
||||
trace_after_total=15
|
||||
recent_jobs=[
|
||||
{"status":"completed","output_mode":"asset_retry","current_step":"asset_retry_completed","story_id":59},
|
||||
{"status":"completed","output_mode":"story","current_step":"generation_completed","story_id":59}
|
||||
]
|
||||
```
|
||||
|
||||
重试后 trace 聚合：
|
||||
|
||||
```text
|
||||
trace_after_steps=[
|
||||
{"name":"provider_invocation","count":4},
|
||||
{"name":"image_generation","count":2},
|
||||
{"name":"context_preparation","count":1},
|
||||
{"name":"narrative_generation","count":1},
|
||||
{"name":"story_persistence","count":1}
|
||||
]
|
||||
trace_after_artifacts=[
|
||||
{"name":"cover_image","count":2},
|
||||
{"name":"story_text","count":1}
|
||||
]
|
||||
```
|
||||
|
||||
Provider stats：
|
||||
|
||||
```json
|
||||
{
|
||||
"story_id": 59,
|
||||
"total_calls": 2,
|
||||
"successful_calls": 2,
|
||||
"failed_calls": 0,
|
||||
"by_provider": [
|
||||
{"capability":"image","adapter":"demo","call_count":1,"success_count":1,"failure_count":0},
|
||||
{"capability":"text","adapter":"demo","call_count":1,"success_count":1,"failure_count":0}
|
||||
],
|
||||
"failure_reasons": []
|
||||
}
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- 资源重试新建了 `asset_retry` job。
|
||||
- 图片生成进入 `image_generation` step。
|
||||
- 封面进入 `cover_image` artifact 聚合。
|
||||
- Provider stats 正确统计 text/image provider 调用。
|
||||
|
||||
## 4. Docker build 说明
|
||||
|
||||
本阶段尝试执行：
|
||||
|
||||
```bash
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
遇到两个与代码无关的外部阻塞：
|
||||
|
||||
1. 根目录 `.env` 中镜像代理覆盖为 `docker.1ms.run/library/node:18-alpine`，该镜像拉取失败。
|
||||
2. 改用官方镜像变量后，Docker Hub metadata 拉取出现网络 EOF。
|
||||
|
||||
因此本阶段没有把新镜像完整 build 成 Docker stack。为验证新代码运行时，本阶段改用本地 API/worker 进程连接现有 Docker PostgreSQL/Redis，覆盖了真实 HTTP、Celery、DB、Redis 和 demo provider 链路。
|
||||
|
||||
## 5. 自审结论
|
||||
|
||||
本阶段烟测通过，说明阶段 0-5 的 harness engineering 改造已经具备真实运行能力：
|
||||
|
||||
- 主内容生成链路可完成。
|
||||
- 资产重试链路可完成。
|
||||
- 标准 trace metadata 可以被后端聚合。
|
||||
- Provider stats 和 workflow trace stats 语义保持分离。
|
||||
- 前端新增的 trace summary 数据来源已经被真实 API 验证。
|
||||
|
||||
仍需注意：
|
||||
|
||||
- Docker 镜像重建受外部 registry/network 影响，后续在网络稳定或镜像源修复后应再跑一次完整 Docker build smoke。
|
||||
- 阶段 3 的 `WorkflowPlan` 当前仍是建模基线，执行器接管尚未开始。
|
||||
|
||||
## 6. 后续建议
|
||||
|
||||
下一步建议进入 **阶段 7：执行器小步接管**。
|
||||
|
||||
建议切片：
|
||||
|
||||
1. 先让普通故事、`generate_images=false` 的最小路径由 `WorkflowPlan` 驱动。
|
||||
2. 保持现有 `story_service` 作为外层编排入口，避免一次性迁移所有模式。
|
||||
3. 给执行器增加一条最小集成测试，验证 step 事件顺序、质量门和持久化行为。
|
||||
4. 再迁移带封面故事、绘本、资产生成和资产重试。
|
||||
252
docs/planning/harness-stage-7-report.md
Normal file
252
docs/planning/harness-stage-7-report.md
Normal file
@@ -0,0 +1,252 @@
|
||||
# Harness Engineering 改造阶段 7 报告
|
||||
|
||||
**阶段**: 7 - 评测驱动与执行器最小接管
|
||||
**日期**: 2026-06-22
|
||||
**状态**: 已完成 7A/7B/7C/7D/7E 当前切片
|
||||
**范围**: deterministic evaluator、evaluation trace、普通故事无图片路径的 WorkflowPlan 接入、内部 golden replay、覆盖摘要、测试与 QA 用例
|
||||
|
||||
---
|
||||
|
||||
## 1. 本阶段目标
|
||||
|
||||
阶段 7 的目标是响应“产品需要评测驱动”的长期要求：生成任务不能只用成功/失败判断质量，而要在主内容持久化前形成可追踪、可回归、可统计的 evaluation result。
|
||||
|
||||
本阶段只接管最小运行路径：
|
||||
|
||||
- `output_mode=story`
|
||||
- `generate_images=false`
|
||||
|
||||
不在本阶段迁移绘本、带图片故事、资产生成或资产重试执行器，避免一次性扩大风险。
|
||||
|
||||
## 2. 已完成工作
|
||||
|
||||
### 后端 harness
|
||||
|
||||
新增文件：
|
||||
|
||||
- `backend/app/services/harness/evaluators.py`
|
||||
- `backend/app/services/harness/executor.py`
|
||||
- `backend/app/services/harness/evaluation_replay.py`
|
||||
- `backend/tests/fixtures/evaluation_golden_cases.json`
|
||||
|
||||
新增能力：
|
||||
|
||||
- `EvaluationDimension`
|
||||
- `EvaluationScore`
|
||||
- `EvaluationResult`
|
||||
- `evaluate_story_output`
|
||||
- `EvaluationReplayCoverage`
|
||||
- `EvaluationReplayCase`
|
||||
- `EvaluationReplaySuiteResult.coverage_summary`
|
||||
- `ExpectedEvaluation`
|
||||
- `replay_evaluation_golden_cases`
|
||||
- `run_evaluation_replay_cases`
|
||||
- `record_workflow_plan`
|
||||
- `record_evaluation_result`
|
||||
|
||||
当前确定性评分维度：
|
||||
|
||||
- `structure`
|
||||
- `safety`
|
||||
- `age_fit`
|
||||
- `educational_value`
|
||||
- `readability`
|
||||
|
||||
### 内部 golden replay
|
||||
|
||||
阶段 7D 已建立第一组内部 golden cases，用固定样本锁住 deterministic evaluator 的回归基线。
|
||||
|
||||
阶段 7E 已将 golden cases 扩充到 11 个样本，并为每条 case 增加内部覆盖标签：
|
||||
|
||||
- `age_band`
|
||||
- `content_shape`
|
||||
- `risk_area`
|
||||
- `tags`
|
||||
|
||||
当前样本覆盖：
|
||||
|
||||
- 完整普通故事通过。
|
||||
- 较长普通故事通过。
|
||||
- 普通故事空正文被质量门阻断。
|
||||
- 普通故事封面提示词缺失被质量门阻断。
|
||||
- 普通故事安全风险词被质量门阻断。
|
||||
- 普通故事结构完整但阅读体验偏短，在高阈值下被评测阻断。
|
||||
- 完整绘本分页通过。
|
||||
- 绘本重复页码被质量门阻断。
|
||||
- 绘本没有分页内容被质量门阻断。
|
||||
- 绘本分页安全风险词被质量门阻断。
|
||||
- 绘本分页正文过短触发 warning，并在高阈值下被评测阻断。
|
||||
|
||||
当前覆盖摘要已由单测锁定：
|
||||
|
||||
- artifact: `story=6`、`storybook=5`
|
||||
- age_band: `3-4=4`、`5-6=4`、`7-8=1`、`unknown=2`
|
||||
- risk_area: `schema_error=4`、`happy_path=2`、`readability_warning=2`、`safety_error=2`、`length_boundary=1`
|
||||
- outcome: `passed=3`、`blocked=8`
|
||||
|
||||
实现边界：
|
||||
|
||||
- replay fixture 只被后端测试和内部工具读取。
|
||||
- 线上生成链路不会自动读取 golden cases。
|
||||
- 不新增用户端 API。
|
||||
- 不改变公开 schema。
|
||||
- 不把 replay 结果、评分、维度或阈值分发到用户前端。
|
||||
- 覆盖摘要只用于后端测试和内部评测基线审查，不进入用户端 API。
|
||||
|
||||
replay 会比较：
|
||||
|
||||
- `passed`
|
||||
- `blocking`
|
||||
- `overall_score` 区间
|
||||
- 必需维度是否存在
|
||||
- quality gate issue code
|
||||
- warning 文案片段
|
||||
- coverage summary
|
||||
|
||||
### 事件模型
|
||||
|
||||
新增标准 step：
|
||||
|
||||
- `evaluation`
|
||||
|
||||
新增事件：
|
||||
|
||||
- `workflow_planned`
|
||||
- `evaluation_completed`
|
||||
|
||||
新增进度：
|
||||
|
||||
- `workflow_planned`: `8%`，工作流已规划
|
||||
- `evaluation_completed`: `52%`，内容评测已完成
|
||||
|
||||
### story service
|
||||
|
||||
普通故事无图片路径现在会：
|
||||
|
||||
1. 构建 `WorkflowPlan`
|
||||
2. 写入 `workflow_planned`
|
||||
3. 准备上下文
|
||||
4. 调用文本 provider
|
||||
5. 执行 deterministic evaluator
|
||||
6. 写入 `evaluation_completed`
|
||||
7. 通过后写入 `narrative_generated`
|
||||
8. 持久化故事
|
||||
9. 收敛 job
|
||||
|
||||
质量门失败时会同时写入：
|
||||
|
||||
- `quality_gate_failed`
|
||||
- `evaluation_completed`
|
||||
|
||||
这样 failed job 的阻断原因和评分事实都能被追踪。
|
||||
|
||||
阶段 7C 已将绘本主内容纳入内部 deterministic evaluator：
|
||||
|
||||
- 绘本 Provider 输出后、持久化前执行 `evaluate_storybook_output`。
|
||||
- 绘本质量门失败会写入内部 `quality_gate_failed` 和 `evaluation_completed`。
|
||||
- 绘本评测通过会写入内部 `evaluation_completed`，artifact 标记为 `storybook_pages`。
|
||||
- 用户可访问的 job detail 仍会过滤 `evaluation_completed`。
|
||||
|
||||
### 前端与管理端
|
||||
|
||||
管理端生成轨迹已补充内部新事件/步骤中文标签：
|
||||
|
||||
- `workflow_planned`: 工作流规划
|
||||
- `evaluation_completed`: 内容评测
|
||||
- `evaluation`: 内容评测
|
||||
|
||||
安全边界修正：
|
||||
|
||||
- 用户端不展示评测分数、维度、通过率或阻断阈值。
|
||||
- 用户可访问的 job detail 不返回 `evaluation_completed` 事件。
|
||||
- 用户可访问的 `trace-summary` 不返回 `evaluation` 聚合对象。
|
||||
- 用户端生成轨迹组件不保留 `evaluation_completed` 和 `evaluation` 展示标签。
|
||||
- 评测 metadata 只保留在内部 job events 中，后续如需展示必须通过 admin-only 内部接口。
|
||||
|
||||
### Trace Summary
|
||||
|
||||
`GET /api/generations/{story_id}/trace-summary` 继续只返回用户可解释的工作流摘要：
|
||||
|
||||
- `total_events`
|
||||
- `failed_events`
|
||||
- `by_step`
|
||||
- `by_artifact`
|
||||
- `failure_categories`
|
||||
|
||||
该接口会跳过 `evaluation_completed`，且 `total_events` 也只统计公开事件，避免把评测分数、维度、阻断策略或内部评测步骤数量分发给普通用户。
|
||||
|
||||
## 3. 验证结果
|
||||
|
||||
已执行：
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
.venv/bin/python -m pytest tests/test_harness_runtime.py tests/test_generation_jobs.py
|
||||
.venv/bin/python -m ruff check app tests
|
||||
|
||||
.venv/bin/python -m pytest
|
||||
|
||||
cd ../frontend
|
||||
npm run build
|
||||
|
||||
cd ../admin-frontend
|
||||
npm run build
|
||||
```
|
||||
|
||||
最新结果：
|
||||
|
||||
- 定向测试：`42 passed`
|
||||
- Harness runtime 定向测试：`22 passed`
|
||||
- 后端完整测试：`146 passed`
|
||||
- Ruff：`All checks passed!`
|
||||
- 用户端构建：通过
|
||||
- 管理端构建：通过
|
||||
|
||||
构建备注：
|
||||
|
||||
- Vite/Browserslist 输出浏览器数据过期提示，不影响构建结果。
|
||||
- 管理端输出 `baseline-browser-mapping` 数据偏旧提示，不影响构建结果。
|
||||
|
||||
## 4. 自审结论
|
||||
|
||||
本阶段目前符合小步迁移原则：
|
||||
|
||||
- 没有引入外部评测服务和额外成本。
|
||||
- 没有改变 API 响应结构。
|
||||
- 公共 `trace-summary` 不分发 evaluation summary。
|
||||
- 公共 `trace-summary` 的 `total_events` 不统计 `evaluation_completed`。
|
||||
- 只接入普通故事无图片路径。
|
||||
- 质量门阻断仍然发生在持久化前。
|
||||
- evaluation metadata 已进入内部 job event，但用户接口会脱敏。
|
||||
- 用户端只展示可用功能和可解释状态，不展示评测数据。
|
||||
- 文本故事和绘本主内容都已经在持久化前进入内部 deterministic evaluator。
|
||||
- 内部 golden replay 已能在单测中检查评测基线漂移。
|
||||
- 内部 replay 覆盖摘要已能检查年龄段、内容形态、风险区域、标签和 outcome 分布。
|
||||
- replay 结果未接入任何用户端接口或前端展示。
|
||||
|
||||
## 5. Bug 与风险记录
|
||||
|
||||
当前没有必须立即阻断的已知 bug。
|
||||
|
||||
已发现并即时修复的问题：
|
||||
|
||||
- 首次插入 plan-aware 分支时，storybook 返回块缩进被补丁碰歪；已在继续测试前修复。
|
||||
- 后端新增 `workflow_planned` 和 `evaluation_completed` 后，用户端/管理端事件标签一开始没有同步；审查发现后已补中文标签并重新构建通过。
|
||||
- 阶段 7B 曾短暂把 evaluation summary 接入用户端和用户可访问 API；经产品安全边界复核后已移除，并补充测试确保公共响应不包含 `evaluation`、用户 job detail 不包含 `evaluation_completed`。
|
||||
- 阶段 7D 初次新增 replay 模块后 Ruff 发现 import 顺序问题；已用 Ruff 修复并重新跑定向测试。
|
||||
|
||||
后续风险：
|
||||
|
||||
- 当前 evaluator 是确定性启发式，适合做回归基线，但不能替代高质量模型评测或人工样本评审。
|
||||
- 当前 golden cases 已扩展到 11 条，但仍偏工程回归样本；后续需要补充真实用户输入分布、Provider 输出变体、教育主题缺失/弱相关、不同绘本页数和更细年龄分层。
|
||||
- 旧同步接口调用 `generate_and_save_story` 时也会执行 evaluator，但没有 job 时不会记录事件；这是兼容选择，后续可以考虑为同步接口生成 lightweight evaluation response。
|
||||
- 后续如果要看 evaluation summary，必须新建 admin-only 内部接口，并确认不会被用户端调用。
|
||||
|
||||
## 6. 后续建议
|
||||
|
||||
下一步继续阶段 8：
|
||||
|
||||
1. 设计 admin-only evaluation analytics，明确权限边界和脱敏规则。
|
||||
2. 逐步让带图片故事和绘本执行路径由 `WorkflowPlan` 接管。
|
||||
3. 扩充 golden cases 到真实用户输入分布和 Provider 输出变体。
|
||||
4. 在 Docker registry 网络恢复后重新跑完整 build smoke。
|
||||
142
docs/planning/harness-stage-8-report.md
Normal file
142
docs/planning/harness-stage-8-report.md
Normal file
@@ -0,0 +1,142 @@
|
||||
# Harness Engineering 改造阶段 8 报告
|
||||
|
||||
**阶段**: 8 - Admin-Only Evaluation Analytics
|
||||
**日期**: 2026-06-22
|
||||
**状态**: 已完成当前切片
|
||||
**范围**: admin-only 内部评测聚合、权限边界、过滤、测试和用户端隔离审查
|
||||
|
||||
---
|
||||
|
||||
## 1. 本阶段目标
|
||||
|
||||
阶段 8 的目标是在不泄露商业机密的前提下，让内部团队可以看到内容评测的聚合质量趋势。
|
||||
|
||||
本阶段只做管理控制面后端接口：
|
||||
|
||||
- 不做用户端接口。
|
||||
- 不做用户端前端展示。
|
||||
- 不做管理端可视化页面。
|
||||
- 不返回原始故事内容、prompt、单条 evaluation event 或评分 reason。
|
||||
|
||||
## 2. 已完成工作
|
||||
|
||||
### 后端服务
|
||||
|
||||
新增文件：
|
||||
|
||||
- `backend/app/services/admin_evaluation_analytics.py`
|
||||
|
||||
新增能力：
|
||||
|
||||
- 聚合内部 `evaluation_completed` 事件。
|
||||
- 支持 `days` 时间窗口过滤。
|
||||
- 支持 `artifact=story_text|storybook_pages` 过滤。
|
||||
- 汇总通过数、阻断数、通过率、平均分、artifact、output mode、score band、dimension score、quality gate issue、failure category 和 warning。
|
||||
|
||||
### Admin-only API
|
||||
|
||||
在既有 admin router 中新增：
|
||||
|
||||
```text
|
||||
GET /admin/evaluations/analytics
|
||||
```
|
||||
|
||||
该接口受现有 admin 控制面保护：
|
||||
|
||||
- `ENABLE_ADMIN_CONSOLE=true` 时才挂载 admin router。
|
||||
- 路由继承 `Depends(admin_guard)`。
|
||||
- Basic Auth 失败时返回 `401`。
|
||||
|
||||
查询参数：
|
||||
|
||||
- `days`: `1-365`
|
||||
- `artifact`: `story_text` 或 `storybook_pages`
|
||||
|
||||
### 响应边界
|
||||
|
||||
该接口只返回聚合摘要：
|
||||
|
||||
- `total_evaluations`
|
||||
- `passed_evaluations`
|
||||
- `blocked_evaluations`
|
||||
- `pass_rate`
|
||||
- `average_score`
|
||||
- `job_count`
|
||||
- `story_count`
|
||||
- `user_count`
|
||||
- `by_artifact`
|
||||
- `by_output_mode`
|
||||
- `score_bands`
|
||||
- `dimension_scores`
|
||||
- `quality_gate_issues`
|
||||
- `failure_categories`
|
||||
- `warnings`
|
||||
|
||||
该接口不会返回：
|
||||
|
||||
- 故事正文
|
||||
- 绘本分页正文
|
||||
- 用户 prompt
|
||||
- cover prompt
|
||||
- 单条 job event
|
||||
- 单条 evaluation event
|
||||
- 评分 reason
|
||||
- quality gate message
|
||||
|
||||
## 3. 验证结果
|
||||
|
||||
已执行：
|
||||
|
||||
```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/services/admin_evaluation_analytics.py app/api/admin_providers.py tests/test_admin_providers.py
|
||||
```
|
||||
|
||||
结果：
|
||||
|
||||
- Admin + 用户侧脱敏定向测试：`26 passed`
|
||||
- Ruff：`All checks passed!`
|
||||
|
||||
已做用户端隔离扫描：
|
||||
|
||||
```bash
|
||||
rg -n "evaluations/analytics|EvaluationAnalytics|admin_evaluation|evaluation_completed|overall_score|golden|replay" frontend/src backend/app/schemas backend/app/api/stories.py backend/app/services/generation_jobs.py
|
||||
```
|
||||
|
||||
扫描结论：
|
||||
|
||||
- 用户端前端没有 evaluation analytics 接口、类型或展示命中。
|
||||
- 用户端公开 schema 没有新增 evaluation analytics 响应模型。
|
||||
- 用户侧后端只保留 `evaluation_completed` 的过滤/脱敏逻辑。
|
||||
|
||||
## 4. 自审结论
|
||||
|
||||
本阶段符合评测数据内部分级原则：
|
||||
|
||||
- 评测 analytics 是 admin-only。
|
||||
- 用户端 API 没有新增评测数据。
|
||||
- 用户前端没有新增评测入口。
|
||||
- 响应为聚合摘要，不返回原始内容或单条评测明细。
|
||||
- 权限测试覆盖未授权访问。
|
||||
- 用户端脱敏测试继续通过。
|
||||
|
||||
## 5. Bug 与风险记录
|
||||
|
||||
已发现并即时修复的问题：
|
||||
|
||||
- 初次测试时 `dimension_scores` 的排序预期与实现不一致；实现按覆盖次数优先排序，更适合运营视图，因此已修正测试预期。
|
||||
|
||||
当前风险：
|
||||
|
||||
- 当前接口返回 warning 文案聚合。warning 文案来自内部 evaluator，目前不包含原始内容，但后续新增 warning 时必须避免拼接用户正文或 prompt。
|
||||
- 当前只做后端 admin API，尚未做管理端页面。后续做 UI 时仍需避免展示单条评测明细和原文内容。
|
||||
- analytics 聚合目前使用 Python 读取 JSON metadata 聚合，适合当前数据量和 SQLite/PostgreSQL 兼容；后续数据量变大时可考虑离线物化或数据库 JSON 聚合。
|
||||
|
||||
## 6. 后续建议
|
||||
|
||||
下一步建议进入阶段 9：
|
||||
|
||||
1. 继续让带图片故事和绘本路径由 `WorkflowPlan` 更完整接管。
|
||||
2. 或先做 admin-only evaluation analytics 的管理端只读页面，但必须保持聚合摘要边界。
|
||||
3. 扩充真实用户输入分布的 golden cases，特别是教育主题弱相关和不同年龄段样本。
|
||||
144
docs/planning/harness-stage-9-report.md
Normal file
144
docs/planning/harness-stage-9-report.md
Normal file
@@ -0,0 +1,144 @@
|
||||
# Harness Engineering 改造阶段 9 报告
|
||||
|
||||
**阶段**: 9 - WorkflowPlan 接管扩展
|
||||
**日期**: 2026-06-22
|
||||
**状态**: 已完成当前切片
|
||||
**范围**: 普通故事带图片、绘本生成路径的计划快照接入、事件顺序测试、用户端评测隔离复核
|
||||
|
||||
---
|
||||
|
||||
## 1. 本阶段目标
|
||||
|
||||
阶段 9 的目标是把 `WorkflowPlan` 从普通故事无图片路径扩展到三条主生成路径：
|
||||
|
||||
- 普通故事无图片：已在阶段 7 接入，本阶段继续作为基线。
|
||||
- 普通故事带图片：新增 `story_with_assets` plan。
|
||||
- 绘本：新增 `storybook` plan。
|
||||
|
||||
本阶段不重写完整执行器，也不改变用户侧 API 响应结构。目标是先让计划快照成为稳定的运行时事实，为后续把执行分支逐步迁移到 executor 打基础。
|
||||
|
||||
## 2. 已完成工作
|
||||
|
||||
### 后端生成路径
|
||||
|
||||
修改文件：
|
||||
|
||||
- `backend/app/services/story_service.py`
|
||||
|
||||
新增行为：
|
||||
|
||||
- `output_mode=storybook` 时，在调用 `generate_storybook_service` 前记录 `workflow_planned`。
|
||||
- `output_mode=story` 且 `generate_images=true` 时，在调用 `generate_full_story_service` 前记录 `workflow_planned`。
|
||||
- `generate_images=false` 的普通故事路径继续复用已有 `_execute_story_without_assets_plan`。
|
||||
|
||||
### WorkflowPlan 快照
|
||||
|
||||
普通故事带图片路径：
|
||||
|
||||
- `plan.mode=story_with_assets`
|
||||
- tasks 包含：
|
||||
- `prepare_context`
|
||||
- `generate_narrative`
|
||||
- `evaluate_narrative`
|
||||
- `persist_story`
|
||||
- `generate_cover_image`
|
||||
- `queue_postprocessing`
|
||||
- `complete_generation`
|
||||
- `generate_cover_image.required=false`
|
||||
- `generate_cover_image.recoverable=true`
|
||||
|
||||
绘本路径：
|
||||
|
||||
- `plan.mode=storybook`
|
||||
- tasks 包含：
|
||||
- `prepare_context`
|
||||
- `generate_storybook_pages`
|
||||
- `evaluate_storybook_pages`
|
||||
- `generate_storybook_images`
|
||||
- `persist_storybook`
|
||||
- `queue_postprocessing`
|
||||
- `complete_generation`
|
||||
- `generate_storybook_images.required=false`
|
||||
- `generate_storybook_images.recoverable=true`
|
||||
|
||||
### 测试
|
||||
|
||||
修改文件：
|
||||
|
||||
- `backend/tests/test_generation_jobs.py`
|
||||
|
||||
新增或更新覆盖：
|
||||
|
||||
- 新增 `test_story_with_images_worker_records_plan_before_assets`。
|
||||
- 更新绘本 worker 测试，断言 `workflow_planned` 事件顺序和 `storybook` plan 快照。
|
||||
- 继续确认用户 job detail 不返回 `evaluation_completed`。
|
||||
|
||||
### 文档
|
||||
|
||||
修改文件：
|
||||
|
||||
- `docs/technical/harness-engineering-modernization.md`
|
||||
- `backend/tests/harness-evaluation-test-cases.md`
|
||||
|
||||
新增内容：
|
||||
|
||||
- 设计文档新增 Workflow Plan Coverage。
|
||||
- 阶段计划新增阶段 9。
|
||||
- QA 用例新增带图片故事和绘本计划快照状态转换测试。
|
||||
|
||||
## 3. 验证结果
|
||||
|
||||
已执行：
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
.venv/bin/python -m pytest 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
|
||||
```
|
||||
|
||||
结果：
|
||||
|
||||
- 定向生成任务测试：`21 passed`
|
||||
- 后端全量测试：`151 passed`
|
||||
- Ruff：`All checks passed!`
|
||||
- 用户前端构建：通过
|
||||
- 管理端构建：通过
|
||||
|
||||
构建提示：
|
||||
|
||||
- `frontend` 和 `admin-frontend` 构建均提示 Browserslist/caniuse-lite 数据较旧。
|
||||
- `admin-frontend` 额外提示 `baseline-browser-mapping` 数据较旧。
|
||||
- 以上均为依赖数据 freshness 提示，不影响当前构建结果。
|
||||
|
||||
## 4. 自审结论
|
||||
|
||||
本阶段改动符合当前 Harness Engineering 路径：
|
||||
|
||||
- 改动面集中在生成入口，不重写 Provider、质量门或持久化逻辑。
|
||||
- 三条主路径的计划事件顺序一致：`worker_started` 后、`context_prepared` 前记录 `workflow_planned`。
|
||||
- 图片类任务在 plan 中明确为可恢复资产，不阻断主内容阅读。
|
||||
- `evaluation_completed` 继续作为内部事件存在，用户端 detail 和 trace summary 不分发评分数据。
|
||||
- 新增测试断言 plan 快照，而不是只断言事件名称，能更早发现后续执行器迁移时的计划漂移。
|
||||
|
||||
## 5. Bug 与风险记录
|
||||
|
||||
本阶段未发现需要统一后置处理的 bug。
|
||||
|
||||
当前风险：
|
||||
|
||||
- `_generate_generation_service_with_job` 仍保留分支式执行，只是补齐了 plan 记录。后续如果要真正由 executor 编排执行，需要继续拆分 story、storybook、asset workflow 的最小执行单元。
|
||||
- `workflow_planned` 当前在用户侧可见。它不包含评测分数、阈值或 replay 信息，可以展示为“工作流规划”；后续如果 plan metadata 增加内部策略字段，必须先做 public sanitizer。
|
||||
- 当前 plan 快照写入 job event metadata。数据量较小，适合现在的 trace 需求；后续若引入更复杂 DAG 或重放执行状态，可考虑独立表或压缩摘要。
|
||||
|
||||
## 6. 后续建议
|
||||
|
||||
下一阶段建议进入阶段 10：
|
||||
|
||||
1. 将资产生成和重试路径也纳入 `WorkflowPlan` 记录，统一 `asset_generation` 与 `asset_retry` 的计划快照。
|
||||
2. 为用户侧 job/event 输出增加公共 metadata sanitizer，明确允许字段白名单，避免未来 plan 或 trace 字段扩展时误泄露内部质量策略。
|
||||
3. 继续扩展评测驱动 golden cases，优先覆盖教育主题弱相关、不同年龄段长度边界和绘本分页一致性。
|
||||
@@ -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；用户侧继续不可见 |
|
||||
|
||||
Reference in New Issue
Block a user