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，优先覆盖教育主题弱相关、不同年龄段长度边界和绘本分页一致性。
|
||||
Reference in New Issue
Block a user