# 评测抓取链路上手指南：从页面提交到产物转存与结果展示

代码核对日期：2026-11-03。本文以本机 `eval-fe-search-chat`、`eval-crawl-admin`、`eval-crawl-crawl` 当前检出源码为准，主线为普通新建任务使用的两个 Biz 接口。调度服务只有客户端与生成契约可读，内部队列、精确退避和部署配置不作推断。

## 1. 先明确“抓取”在这个系统里的含义

这里的抓取，是把一批评测输入放到若干配置环境里执行，取得模型回答、消息、工具调用、trace、文件、截图等结果，整理为评测平台可读取的数据。抓取阶段为后续人评和自动评估准备材料，抓取成功不等于评估成功。

完整过程有三个容易被都叫作“成功”的时点：

1. HTTP 受理成功：前端提交接口成功返回。
2. 采样成功：目标模型/应用的会话执行产生结果，采样快照已保存。
3. 产物处理成功：本次启用的产物按策略完成、跳过或完成规定的异步交付，执行结果已上报。

这三者之间存在异步边界。页面出现“创建成功”时，后台可能还在解析题集、创建 Task，模型请求和文件转存通常也没有完成。

## 2. 参与系统与各自职责

| 层 | 核心职责 | 主要入口 |
|---|---|---|
| 前端 `eval-fe-search-chat` | 表单、场景选择、DTO 转换、两个 HTTP 请求、轮询和结果渲染 | `apps/evaluate`、`packages/evaluate-material` |
| Admin `eval-crawl-admin` | 权限/配置校验、项目与题目创建、业务数据、调度绑定、查询适配、对账、送标/评估衔接 | `views/biz_create_entry.go`、`service/bizcreate`、`service/repository` |
| Scheduler `aidp_crawl_scheduler` | Project/Task/Scene/Item 调度树、执行派发、执行身份与结果上报契约 | `CreateProject`、`CreateTask/BatchCreateTask`、`SubmitItemRes` |
| Crawl `eval-crawl-crawl` | 真正执行采样和产物采集，调用模型/应用及导出、trace、截图等下游 | `CreateExecution`、`CreateAsyncArtifactTask` |
| Biz MySQL | 业务配置、身份关系、状态、计数、产物引用与错误 | `biz_project/env/task/scene/artifact` |
| 对象存储 TOS | 采样 JSON、产物 JSON、转存文件及异步输入快照等大对象 | SampleStore、ArtifactStore、文件转存服务 |
| Redis / MQ / 配置系统 | 限流、幂等、锁、执行协调；特定投递路径与异步产物；运行配置 | 不应统一理解为“所有任务一定先走 Kafka” |

Admin 不在创建 HTTP 请求内等模型完成，前端也不直接向 trace 或 Office 服务采集材料。

```mermaid
flowchart TD
  UI["页面填写配置与输入"] --> P["POST biz/add_evaluate_project/"]
  P --> CFG["项目、环境入 Biz DB<br/>建立 Scheduler Project"]
  CFG --> EID["返回 evaluate_id"]
  EID --> T["POST biz/create_tasks/"]
  T --> INPUT["解析/取得具体题目<br/>异步创建与下发"]
  INPUT --> ROWS["Task × Env 展开 Scene<br/>建立 Scheduler Task/Scene/Items"]
  ROWS --> S1["stage1：Crawl 模型采样"]
  S1 --> SAMPLE[("TOS SampleResult<br/>Scene 保存 sample_result_ref")]
  SAMPLE --> S2["stage2：Crawl 产物采集与转存"]
  S2 --> OBJ[("产物 JSON / 文件 / 引用")]
  S2 --> STATUS["Biz 产物状态 + SubmitItemRes"]
  STATUS --> READ["Admin 查询/投影与状态对账"]
  OBJ --> READ
  READ --> SHOW["任务列表与结果预览"]
```

## 3. 前端从哪个页面、哪个函数开始

普通入口是抓取项目列表的“新建”，路由为 `/crawl/form/create`。文件路由经 `form/[mode]/page.tsx` 到普通抓取页面。一个表单同时包含项目基础信息、抓取环境、题目来源、Prompt 和高级配置。

提交函数链：

```text
normal-crawl-page 的提交按钮
  → useCrawlPageSubmit.handleSubmit
  → 表单/业务校验 + prepareProjectFormSubmit
  → 判断本次使用 origin 还是 next 链路
  → useSingleTaskSubmit
  → useCrawlTaskMutation / runCrawlTaskMutation
  → runNextLinkProjectSubmit
  → createBizProject
  → 取 evaluate_id
  → buildNextTaskPayload
  → createBizTasks
  → 创建成功提示，跳转项目列表
```

next 链路不是仅凭一个场景名称猜出来的。创建/复制会读取场景注册表 `/others/get_all_scene`，结合 app、显式场景、有效默认 recipe 等决定；编辑以项目保存的 `use_biz_storage` 为依据。这里讨论的两个 `/biz/` 接口，就是普通 next 新建分支。

入口：普通页面（`eval-fe-search-chat/apps/evaluate/src/routes/crawl/form/[mode]/create-crawl/normal-crawl/components/normal-crawl-page.tsx:80`）、提交校验（`eval-fe-search-chat/apps/evaluate/src/routes/crawl/form/[mode]/hooks/useCrawlPageSubmit.tsx:110`）、提交编排（`eval-fe-search-chat/apps/evaluate/src/routes/crawl/form/[mode]/data/crawlTask.mutation.ts:175`）、链路判断（`eval-fe-search-chat/apps/evaluate/src/routes/crawl/__domain/crawl-link-decision.ts:201`）。

## 4. 为什么一次提交拆成两个接口

两个接口分别回答两个问题：

- `POST /admin/label/biz/add_evaluate_project/`：这次抓取叫什么、属于谁、用哪些环境、启用哪些能力、从哪里取题、怎么限流、如何评估。
- `POST /admin/label/biz/create_tasks/`：往刚才的项目里放哪些具体题目，或启动什么取题流程。

前端严格先 await 创建项目，然后用返回的 `evaluate_id` 创建 Task。可选 `biz_project_id` 并不是这个后续请求实际使用的字段。国内 service 前缀是 `/admin/label`；后端 router 中能看到去掉网关前缀后的 `admin/biz/...` 路由，不要误以为是不同接口。

简化代码：

```ts
const projectRes = await createBizProject(projectPayload);
const evaluateId = String(projectRes.evaluate_id || eid || '');
const taskPayload = buildNextTaskPayload(params, evaluateId);
await createBizTasks(taskPayload);
```

项目请求失败或未取得 ID 时，不发 Task 请求。第二个请求失败时，当前前端没有把第一个已成功创建的项目自动回滚，也没有自动重跑整个双请求事务。

来源配置会在两处出现：Project 的 `query_src_info` 保存来源描述，Task 请求提交真正的取题/输入参数。它们复用 `buildNextTaskSourceData`，但仍是两个用途，不是创建 Project 时已执行了一遍题目。

入口：两请求顺序（`eval-fe-search-chat/apps/evaluate/src/routes/crawl/form/[mode]/data/crawlTask.mutation.ts:222`）、JSON service（`eval-fe-search-chat/apps/evaluate/src/services/next-link-crawl.ts:72`）、Project API（`eval-fe-search-chat/apps/evaluate/src/services/next-link-crawl.ts:119`）、Task API（`eval-fe-search-chat/apps/evaluate/src/services/next-link-crawl.ts:172`）、后端路由（`eval-crawl-admin/router/urls.go:43`）。

## 5. Project 请求的配置如何分层

以下综合后端可接收 DTO 说明配置分层，字段不代表当前普通前端均直接发送，也不是可直接照抄调用的完整有效环境配置。当前前端 Env adapter 不显式输出外层 `artifact_config`，产物策略通常由后端归一化与默认配置补齐：

```json
{
  "project": {
    "tenant_biz_id": "租户标识",
    "project_name": "我的第一次抓取",
    "owner": "当前用户",
    "query_src_info": {
      "source_type": 0,
      "query_list": [{"query": "介绍一下杭州"}]
    },
    "limit_info": {},
    "crawl_config": {},
    "schedule_config": {}
  },
  "envs": [{
    "env_idx": 0,
    "env_name": "环境 A",
    "app_id": "应用 ID",
    "biz_scene_type": "doubao_web",
    "env_config": {},
    "business_config": {},
    "output_config": {},
    "artifact_config": {}
  }]
}
```

| 配置 | 所在层 | 作用 |
|---|---|---|
| 项目名、owner、tenant、权限、业务线 | Project | 管理、权限、归属 |
| `query_src_info / prompt_config` | Project | 输入来源、题集与 Prompt 组织 |
| `limit_info` | Project | 限流组、自定义限流等策略 |
| `crawl_config` | Project | diff、过滤、意图、落地页等业务控制 |
| `schedule_config` | Project | 定时、周期、PPE lane 等调度上下文 |
| `auto_eval_info` | Project | 抓取之后自动评估的设置 |
| `env_config` | Env | 场景运行时输入，例如应用/模型、会话与下游参数 |
| `business_config` | Env | 业务补充与复用等配置 |
| `output_config` | Env | 输出/导出方式、落地页与工具等输出策略 |
| `artifact_config` | Env | 启用产物、required 声明及 overrides |

前端的 `query_config[]` 由 adapter 转为后端的 `envs[]`。`params_jsonstr` 可作为环境配置底稿，显式环境字段再合并；UI 校验和展示字段会过滤。环境配置不是一个任意字段都能塞进去且全部生效的无结构 JSON。

`artifact_config` 也会经过后端场景默认值与合法性归一化；例如 `need_screenshot` 会影响截图产物配置。前端没有传完整 artifact 配置，不意味着没有产物。

入口：Project adapter（`eval-fe-search-chat/apps/evaluate/src/routes/crawl/form/[mode]/adapters/next-link/projectAdapter.ts:8`）、Env 转换（`eval-fe-search-chat/apps/evaluate/src/routes/crawl/form/[mode]/adapters/next-link/utils.ts:413`）、后端 DTO（`eval-crawl-admin/views/biz_create_entry.go:193`）、DTO→Biz 模型（`eval-crawl-admin/views/biz_create_entry.go:2720`）、Env 归一化（`eval-crawl-admin/views/biz_create_entry.go:2979`）。

## 6. 创建 Project 时后端具体做什么

调用链为：`BizAddEvaluateProject → bizCreateProjectJSONEntry → Pipeline.CreateBizProject → ProjectRepository.Create → bindCreatedProject`。

主要步骤：

1. 解析 JSON，确认 tenant、项目名、owner 与登录身份一致。
2. 映射来源、限流、评估、权限和环境配置；检查复用、场景参数、模型路由等适用条件。
3. 在 owner 配额锁内校验当前并发项目/近期项目配额。
4. 数据库事务先创建 `evaluate_project` 壳行，再创建同 ID `biz_project`、多个 `biz_project_env`，最后回写壳的 `biz_project_id` 指针。
5. 事务完成后调用 Scheduler `CreateProject`，携带 `BizProjectID`、各环境的 AppID/SceneType/EnvIdx、Owner、Lane。
6. 把返回的 `schedule_project_id` 绑定回业务项目。
7. HTTP 返回 `evaluate_id`、可选 Biz ID 等信息。

这一步创建的是“装任务的项目及环境配置”，还没有等模型回答。

失败边界按当前实际实现说明：数据库事务内部失败会回滚；Scheduler 项目绑定在事务外。`bindCreatedProject` 绑定重试耗尽时返回错误，并尝试清理仍未绑定 Scheduler 的 Project、Env 与壳行。某些旧长注释仍描述保留成功，应以此实际函数分支为准。

入口：HTTP handler（`eval-crawl-admin/views/biz_create_entry.go:1824`）、Pipeline（`eval-crawl-admin/service/bizcreate/pipeline.go:901`）、原子落库（`eval-crawl-admin/service/repository/project.go:415`）、Scheduler Project 绑定（`eval-crawl-admin/service/repository/project_schedule_dispatch.go:86`）、绑定失败处理（`eval-crawl-admin/service/bizcreate/pipeline.go:868`）。

## 7. 创建 Task：输入从哪里来，何时真正落库

Task 请求最重要的关联字段是 `evaluate_id`。手动输入示意：

```json
{
  "evaluate_id": 123456,
  "source_type": 0,
  "query_list": [
    {"query": "介绍一下杭州"},
    {"query": "介绍一下苏州"}
  ]
}
```

一条 Task 可以携带多轮 prompt、历史对话、图片或文件，不应简单把 Task 永久理解成一个字符串。`QueryInfo` 会归一化为 `PromptDetailJSON`，原题元数据、透传字段、题集 ID、UUID 等另行保存。

前端 UI 的来源枚举与 API 枚举不是同一套数字：

| 页面来源 | API 来源类型 | 创建接口提交/后端处理 |
|---|---:|---|
| 手动输入/文件输入 | 0 | `query_list`；也兼容文件 ID 等形态 |
| 在线题集 | 100 | 题集及选题条件，后端取得完整题目并归一化 |
| 实时抓取 | 6 | 来源、抽样和终止条件；建立持续取题配置 |
| 历史数据 | 58 | 来源与 session_info 等条件，后端取历史输入 |
| session 回放/回放并抓取 | 52 / 60 | 专用会话来源信息与回放分支 |

普通 JSON 路径：

```text
BizCreateTasks
  → 校验 evaluate_id / 兼容 source_type→crawl_type
  → bizCreateTasksJSONEntry
  → 查项目、核对运行环境/PPE
  → 实时/历史等特殊来源分流
  → 普通来源解析成 QueryInfo[]
  → asyncBizCreateTasksByQueryInfosWithMethod
  → HTTP 先返回 task_count

后台 goroutine：
  → QueryInfo → CreateBizTaskInput[]
  → Pipeline.CreateBizTasks
  → LegacyCompatibilityBatch（此处“兼容”不等于落旧抓取事实表）
  → Repository 创建 evaluate_task 壳 + 同 ID biz_task + 每环境一个 biz_scene
  → Dispatcher 下发 Scheduler 并绑定 ID
```

异步上下文保留本次 LogID 和租户身份，不跟着原 HTTP 请求结束而直接失效。若后台失败，HTTP 可能已经成功返回，需继续看创建日志、业务行和调度绑定。`task_count` 首先是本次接受的输入数量，不是已经成功执行的题数。

Task 与 Scene 数据写入后，调度下发失败可以保留未绑定数据，供后续补偿；不要把项目创建期的清理语义套到所有 Task 失败。

入口：Task handler（`eval-crawl-admin/views/biz_create_entry.go:157`）、JSON 分流（`eval-crawl-admin/views/biz_create_entry.go:5715`）、输入归一化（`eval-crawl-admin/views/biz_create_entry.go:5849`）、后台异步受理（`eval-crawl-admin/views/biz_create_entry.go:5135`）、QueryInfo→Task（`eval-crawl-admin/views/biz_create_entry.go:5194`）、批量 Pipeline（`eval-crawl-admin/service/bizcreate/pipeline.go:1127`）、兼容分发实现（`eval-crawl-admin/service/bizcreate/legacy_compatibility.go:103`）。

## 8. 五种业务实体与两套身份

| 实体 | 表里的一行代表什么 | 与其他实体的关系 |
|---|---|---|
| Project | 一次抓取项目及公共配置 | 拥有环境、题目 |
| ProjectEnv | 一套项目环境配置 | 项目内 `env_idx` 区分环境 |
| Task | 一道评测输入/一个多轮会话输入 | 属于 Project，展开多个 Scene |
| Scene | 一道题在一个环境上的执行 | `Task × Env` |
| Artifact | 某个 Scene 的一种产物 | 如 message_list、trace、legacy_bundle |

例如两道题、三个普通豆包环境：2 个 Task，6 个 Scene，每个 Scene 两个调度 Item，共 12 个 Scheduler Item。Artifact 数随策略变化，且不是要求所有行在创建项目时立即存在。

```text
Project
├─ Env A / Env B / Env C：配置模板
├─ Task 1
│  ├─ Scene 1A → stage1 item、stage2 item → 多种 Artifact
│  ├─ Scene 1B → stage1 item、stage2 item → 多种 Artifact
│  └─ Scene 1C → stage1 item、stage2 item → 多种 Artifact
└─ Task 2
   └─ 同样按三个 Env 展开
```

特别注意：Artifact 不是 Scheduler Item。一个 stage2 Item 可以负责多种 Artifact，它们的 `schedule_item_id` 可以相同。

| 名称 | 含义 |
|---|---|
| `eid / evaluate_id` | 管理后台项目 ID，即 evaluate_project 壳 ID |
| `tid / task.id` | 管理后台 Task ID，即 evaluate_task 壳 ID |
| `biz_project_id / biz_task_id` | Biz 业务行主键；当前新建通常与壳同值，历史必须看壳指针 |
| `biz_project_env_id` | 某套环境配置的行 ID |
| `biz_scene_id` | 某道题×环境的执行实例 ID |
| `schedule_project/task/scene_id` | Scheduler 自己的节点 ID，回写到对应 Biz 行 |
| `TechItemID` | stage1 或 stage2 的真实 Scheduler Item ID |
| `ExecutorKey` | 一次调度执行身份，和 ItemID 一起做上报/幂等校验 |
| `Biz Log ID` | 平台执行检索标识，可带 stage 与本次启动时间 |
| `inner_log_id` | 模型/应用下游请求的日志标识，trace 回捞通常用它 |

新建壳与 Biz 同 ID 不代表可以完全绕过映射。历史数据不是都同值，`20_000_000_000` 阈值已废弃。读取先看壳的 `biz_project_id/biz_task_id`，不能凭 ID 大小选择新旧链路。

入口：模型定义（`eval-crawl-admin/models/biz/scene.go:5`）、Artifact 元数据（`eval-crawl-admin/models/biz/artifact.go:9`）、同 ID 项目事务（`eval-crawl-admin/service/repository/project.go:415`）、ID 阈值废弃说明（`eval-crawl-admin/models/biz/config_types.go:33`）。

## 9. Scheduler 如何接上 Crawl

Project 创建建立调度根节点；Task 下发提交它的 Scene 与 Item 子树。请求携带业务 ID、环境、AppID、SceneType、稳定 Biz LogID 和 PPE Lane。RPC 成功后绑定调度 ID，失败时业务身份与日志标识用于重试/补偿定位。

| 场景 | 调度阶段 |
|---|---|
| 普通模型采样场景 | stage1 `CreateExecution` + stage2 `CreateAsyncArtifactTask` |
| `session_replay` | 仅 stage2，从历史会话准备样本及回放产物 |
| `web_compete / app_compete` | 仅 stage1，采样/产物经该场景回调链路处理 |

因此“两阶段”是普通场景主线，不是所有场景的绝对公理。具体采样、转存动作还由 Scene recipe 和环境策略决定。

Crawl 的 RPC 返回 accepted，表示后台执行已经被接受；执行结果由 worker 主动 `SubmitItemRes` 给 Scheduler。Admin 不是收到模型完成 HTTP 回调后才逐题调用 stage2 的中心循环。

入口：调度请求结构（`eval-crawl-admin/service/repository/task_schedule_dispatch.go:643`）、阶段分支（`eval-crawl-admin/service/repository/task_schedule_dispatch.go:489`）、Crawl RPC 入口（`eval-crawl-crawl/handler.go:649`）、结果上报（`eval-crawl-crawl/service/harness_execution/scheduler_client_external.go:58`）。

### 有条件存在的 TaskDelivery 分支

代码中存在 durable / inline / BMQ / batch 投递协议，但不能画成两个 Biz 接口必经 BMQ。

普通 `Pipeline.CreateBizTasks` 走前文兼容分发。只有显式 `ResolveBizTasksCreator → AcceptOrdinaryBizTasks` 的相应自动取题/调用路径，才会按协议开关和灰度决定：

- 关闭协议：兼容持久化与调度。
- inline：durable 事务落库后执行投递 core。
- BMQ：先发布带稳定身份、输入哈希的 create command；消费者 materialize Task/Scene 后再执行投递和 ID 绑定。受理时 Task 可能尚未落库。
- 定时未到点：可只落库，延后下发。

Delivery 的 `prepared/published/bound/cancelled/quarantined` 表示“业务任务能否正确投递/绑定”，不表示模型抓取成功与否。重复消息通过稳定 create key、输入校验和版本约束处理，也不代表用户重复新建整个项目会全局去重。

入口：条件受理（`eval-crawl-admin/service/bizcreate/pipeline.go:298`）、投递路由（`eval-crawl-admin/service/taskdeliveryapp/provider.go:262`）、投递 core（`eval-crawl-admin/service/taskdelivery/core.go:665`）。

## 10. stage1：从受理到真正拿到模型回答

```text
CreateExecution
 → 同步校验 biz_ref/config/主键/调度环境
 → 运行时 Biz Log ID 加时间后缀
 → SamplingEngine.SubmitExecution
 → 抢跨实例执行 claim，提交 worker
 → RPC 返回 accepted

后台 worker
 → 心跳保活、入口 admission
 → 读取权威 Biz 上下文
 → SceneRouter 选择场景
 → 处理适用的完整结果复用
 → 按 recipe 执行采样模块
 → 保存 SampleResult 到 TOS
 → 回写 Scene 的样本引用
 → SubmitItemRes(stage1)
```

`BizContextResolver` 读取 Project/Env/Task/Scene，校验归属，解析 `biz_task.prompt_detail_json` 和环境运行配置，补齐应用、owner、legacy 坐标、限流、AB、diff 等信息。请求里的主键是定位依据，业务表里的配置是运行依据；不能认为 Scheduler RPC 必然携带整份表单。

当前 Harness 运行字段主要由 `env_config` 解析，例如豆包的 `doubao` 命名空间、Dola 的 `dola` 命名空间；`business_config` 可保存业务/兼容信息，但不应当成运行参数的统一权威来源。`ext` 等字段还会进入采样快照。

claim、心跳、限流作用不同：claim 避免重复执行；心跳维持当前执行者/租约并向调度侧报活；限流决定什么时候能使用模型、环境、产物下游等资源。入口 admission、环境 entry、轮间 prompt gate、产物令牌、截图设备池是不同层。出现“等待”时需先确定等待哪一层。

入口：受理 handler（`eval-crawl-crawl/service/harness_execution/handler.go:124`）、SamplingEngine 提交（`eval-crawl-crawl/service/harness_execution/sampling_engine.go:218`）、Biz 上下文（`eval-crawl-crawl/service/harness_execution/biz_context_resolver.go:56`）、Env 解析（`eval-crawl-crawl/service/harness_execution/project_env_config_resolver.go:50`）、幂等 claim（`eval-crawl-crawl/service/harness_execution/idempotency_guard.go:36`）、心跳（`eval-crawl-crawl/service/harness_execution/heartbeat.go:23`）。

### recipe 是运行模块清单

普通豆包场景的采样可以按下面顺序读，但具体模块以对应 recipe 为准：

```text
个性化 UID / AB 解析合并（适用场景）
 → 上下文归一化与 query plan
 → mock / precheck（适用场景）
 → 创建或复用会话
 → 等 onboarding 就绪
 → 保存评测 Flow 参数
 → 逐轮执行：
      prompt_gate
      → send_sse
      → confirm_reply
      → MA finalize / 授权 / 等待等场景逻辑
      → 每轮办公产物快照（适用场景）
 → First-Re 候选（适用场景）
 → save_round_result
```

`sampling.modules` 按顺序装配；`query_round` 是循环执行 inner modules 的复合模块。采样模块的 `Required()` 决定模块错误是否中断；它和产物策略的 `required_artifacts` 不是同一套机制。

引擎级 RetryAttempts 固定 0，失败交给调度层，但具体网络调用和模块内部仍可有有限重试，不能解读成每个 HTTP 只请求一次。

入口：Web recipe（`eval-crawl-crawl/ai_harness/scenes/doubao_web/recipe.yaml:59`）、App recipe（`eval-crawl-crawl/ai_harness/scenes/doubao_app/recipe.yaml:52`）、miniapp recipe（`eval-crawl-crawl/ai_harness/scenes/miniapp/recipe.yaml:68`）、模块执行（`eval-crawl-crawl/service/harness_execution/sampling_engine.go:1563`）。

### send_sse 和 confirm_reply 分工

`send_sse` 发送本轮 prompt、会话/section/cursor、round index 和评测参数；运行时保存消息 ID、SSE Log ID、首字延迟、接管/clarify 信号、首次消息列表等证据。

SSE 结束不代表消息存储已完整可读。`confirm_reply` 继续读取消息列表，确认当前轮回复结束，检查 `has_err`、安全策略、接管等状态，并把完整会话消息快照写回本轮 RoundResult，更新下一轮使用的 section 和消息游标。

这解释了为何“下游已经返回一些内容”与“确认回复仍未结束”可以同时出现。默认轮询次数/间隔还会受场景与运行配置影响，不能把一个默认值当所有任务统一的耗时上限。

入口：send_sse（`eval-crawl-crawl/ai_harness/modules/sampling/doubao/common/send_sse/module.go:68`）、SSE wire（`eval-crawl-crawl/service/harness_runtime_wire/sse_backend.go:86`）、confirm_reply（`eval-crawl-crawl/ai_harness/modules/sampling/doubao/common/confirm_reply/module.go:112`）、消息列表读取（`eval-crawl-crawl/service/harness_runtime_wire/message_list_backend.go:43`）。

## 11. SampleResult：stage1 与 stage2 之间的交接物

SampleResult 不是一个回复字符串，而是后续产物执行的证据包，通常包括：

- conversation ID、业务 item、完成时间。
- 每轮输入、消息/回复 ID、SSE 标识、完整消息快照。
- 消息 Ext 内的 `inner_log_id` 等回捞坐标。
- 每轮 OfficeArtifactSnapshots。
- SessionMeta：采样时的 app、UID、AB、环境、截图和运行参数。
- 回放场景的离线 trace、附件和旧 debug 信息。
- First-Re 候选引用，以及失败时的 SourceFailure 等信息。

普通保存过程为：JSON 序列化 → TOS Put → 返回 key/ref → 写回 `biz_scene.extra.harness.sample_result_ref` → 上报 stage1。稳定 key 形如：

```text
harness/<storage_scene_code>/sample/<biz_scene_id>/sample_result.json
```

实际必须看保存的 ref；存储 scene code 可能有兼容归一化。某些 `ref#message_list` 是对象内部子视图引用，不是另一个独立上传对象。

重要顺序是 **对象写成功 → DB 引用写成功 → stage1 成功上报**。TOS 有文件而 DB 没有引用，仍可能被判定为交接失败。TOS 与 MySQL 不属于同一个数据库事务。

失败时也可能持久化 partial sample：保留已经产生的会话与轮次证据，带上 `SourceFailure`。特定失败会以 `PARTIAL_SAMPLE_AVAILABLE` 交给后续证据回收，stage2 通常缩小到 message_list、trace、legacy_bundle 等集合。补采证据成功不会自动抹去原始采样失败。

入口：SampleResult 结构（`eval-crawl-crawl/service/harness_miniapp_runtime/types.go:406`）、采样保存模块（`eval-crawl-crawl/ai_harness/modules/sampling/doubao/common/save_round_result/module.go:45`）、TOS 保存（`eval-crawl-crawl/service/harness_miniapp_runtime/store.go:20`）、稳定 key（`eval-crawl-crawl/service/harness_sample_ref/ref.go:10`）、DB 引用回写（`eval-crawl-crawl/dal/biz_db/scene_execution.go:229`）、partial sample（`eval-crawl-crawl/service/harness_execution/sampling_engine.go:1180`）。

## 12. stage2：产物计划、并发、持久化和上报

普通 stage2 不重新向模型提问，而是根据 Scene 反查样本引用，加载 SampleResult，再执行产物计划。

```text
CreateAsyncArtifactTask
 → 同步校验 / artifact claim / 提交 worker / accepted
 → 心跳 + 解析上下文与 sample_result_ref
 → TOS 加载 SampleResult
 → artifact_config ∩ scene 支持集合 → effective policy
 → 识别已有成功、跳过或有效异步交付结果
 → 只准备 pending 产物
 → 限流、预加载消息、写 accepted/running
 → 按 recipe 分线执行
 → 每条线结束刷新 legacy_bundle
 → 全部线结束后 final flush
 → 合并历史与本次结果、写最终产物 DB 状态
 → SubmitItemRes(stage2)
```

普通场景引用缺失时有稳定 key 回退；session_replay 有专用样本准备逻辑，不能一律把 stage2 缺 ref 当成相同错误。

### 两个并发规则

1. 不同 artifact line 并发。
2. 同一 line 内串行；某个产物返回 error 后，该 line 停止，其他 line 可继续。

典型结构：

```mermaid
flowchart TD
  S["预加载 SampleResult / messages"] --> M["message_list line"]
  S --> T["trace line"]
  S --> O["Office / file / 其他 lines"]
  S --> D["截图 / 落地页等适用的异步交付线"]
  T --> FT["普通 trace → MoA → 校验 → 保存"]
  FT --> MCP["MCP IO"]
  FT -->|"失败时跳过 MCP，本线仍参与汇总"| L
  M --> L["legacy_bundle 分线刷新与最终汇总"]
  MCP --> L
  O --> L
  D --> L
  L --> R["保存各产物状态、结果引用<br/>向 Scheduler 上报阶段结果"]
```

message_list 和 trace 可以共用预加载样本，不是必须先等 `message_list.json` 文件上传后才查 trace。运行顺序以 recipe 的 `artifact_execution.lines` 为准，不能只看模块的 `DependsOn()` 自描述。

`required_artifacts` 用于范围/子集/支持能力校验。当前 runner 汇总并非只检查 required：本次 effective 执行的 enabled 产物若返回 error，也可能导致阶段失败。无适用素材而主动返回 `skipped`，与执行报错 `failed` 不同。

入口：stage2 worker（`eval-crawl-crawl/service/harness_execution/engine.go:903`）、策略解析（`eval-crawl-crawl/service/harness_execution/artifact_policy.go:240`）、复用已有结果（`eval-crawl-crawl/service/harness_execution/engine.go:1201`）、并发 lines（`eval-crawl-crawl/service/harness_execution/artifact_plan_runner.go:418`）、单线执行（`eval-crawl-crawl/service/harness_execution/artifact_plan_runner.go:937`）、阶段汇总（`eval-crawl-crawl/service/harness_execution/artifact_plan_runner.go:674`）。

## 13. “转存”至少有四种不同动作

| 动作 | 典型对象 | 主要发生时机 |
|---|---|---|
| 结构化快照序列化 | SampleResult、message_list、trace、MCP IO | stage1 / stage2 |
| 原始资源导出、下载、重新上传 | Markdown、PDF、PPTX、XLSX、源码 ZIP | 适用场景每轮采样确认后，或专用补偿路径 |
| 聚合索引与兼容格式生成 | office_ppt.json、legacy_bundle.json | stage2 |
| 可靠异步交付并回填真实结果 | 截图、落地页 | stage2 交付，独立 consumer 完成 |

MySQL 的 `result_key` 通常只是“去哪里取内容”的引用。一个 Office 产物索引 JSON 中，还会有指向真实 PPTX/PDF/ZIP 的二级引用。

```mermaid
flowchart LR
  SRC["模型消息中的 resource / 临时 URL"] --> EXP["调用导出服务<br/>取得指定版本的下载地址"]
  EXP --> DL["下载文件内容"]
  DL --> BIN[("文件对象存储<br/>PPTX / PDF / XLSX / ZIP 等")]
  BIN --> SNAP["本轮资源快照<br/>保存版本、消息坐标、文件引用"]
  SNAP --> SAMPLE[("SampleResult")]
  SAMPLE --> INDEX[("stage2 产物索引 JSON")]
  INDEX --> DB["biz_artifact.result_key / result_type"]
  DB --> PAGE["Admin 解析与页面展示"]
```

这不是所有产物都执行的统一流水线。例如 trace 是 JSON 回捞，截图是后台 capture，legacy_bundle 是聚合；不能给每类都强行套一个下载文件动作。

## 14. 各种产物究竟存的是什么

| 产物 | 来源与处理 | 常见结果 / 无素材行为 |
|---|---|---|
| `artifact_message_list` | SampleResult 中的消息快照 | message_list JSON；空消息可能失败 |
| `artifact_trace` | 消息 inner_log_id → 普通 trace → 适用的 MoA → 完整性校验 | trace JSON，另有 MoA 引用；回捞或完整性校验失败时，不进入本次主 trace 写入 |
| `artifact_mcp_io_log` | 已有 Shared trace 或 trace ref | 抽取 MCP IO JSON；无记录可 skipped |
| `artifact_office_doc` | 每轮冻结的 Doc 快照 | Doc 资源索引 JSON |
| `artifact_office_ppt` | 每轮冻结的 PPT 快照 | PPT 资源索引 JSON |
| `artifact_office_excel` | 每轮冻结的 Excel 快照 | Excel 资源索引 JSON |
| `artifact_miaoda` | 妙搭展示地址与源码归档快照 | 展示 URL + 源码 ZIP 的索引 |
| `artifact_file_block` | 文本、代码、压缩包、音视频等资源快照 | 按实际类型转存文件并写索引 |
| `artifact_screenshot` | 会话及采样时截图参数、最后轮/消息坐标 | pending 交付引用，后续回填真实截图 URI |
| `artifact_landing_page` | 页面抓取配置、输入、trace/cache selector | 异步交付、后续抓页结果 |
| `artifact_card_detect` | 消息卡片解析 | 每条消息 has_card 标记等 JSON |
| `artifact_card_render_raw` | 原始卡片 render/permission 素材 | raw card JSON；无素材可 skipped |
| `artifact_attachment` | 回放样本中已经取回的附件 | 附件结构化结果；不是重新向附件服务取一遍 |
| `artifact_legacy_bundle` | SampleResult + 当前完成的其他产物 | 兼容旧展示协议的聚合 JSON，允许部分结果 |
| `artifact_vm_bundle` | CUA/VM 执行产生的材料 | VM 运行索引、文件、录屏/截图等专门投影 |

并不是每个场景支持全部产物。最终执行集合由场景支持范围、环境 artifact_config、请求允许范围和当前执行状态共同决定。

## 15. Office / PPT / Excel / 妙搭的真实转存原理

### 15.1 为什么每轮采样后就导出

多轮可能反复编辑同一个资源。等整个会话结束再下载，会有丢失中间版本、只拿到最终版本或临时链接变化的问题。因此适用场景在每轮回复确认后解析消息资源，按 resource/version/message/block 身份去重，执行导出与转存，把结果冻结在 `Rounds[].OfficeArtifactSnapshots`。

这个步骤属于采样 recipe。它失败时可能报 `WEB_EXPORT_FAILED`：此时模型可能已有回答，但本轮样本证据保存未完成。

入口：每轮快照模块（`eval-crawl-crawl/ai_harness/modules/sampling/doubao/web/round_artifact_snapshot/module.go:38`）、消息资源收集（`eval-crawl-crawl/service/harness_miniapp_runtime/web_artifact_collector.go:74`）、快照结构（`eval-crawl-crawl/service/harness_miniapp_runtime/types.go:278`）。

### 15.2 Doc

按资源版本解析 Doc → 导出 Markdown → 上传 `content.md` → 获取 PDF 下载地址 → 下载/上传 `preview.pdf`；再按适用策略尝试源文件 ZIP 和在线副本。在线文档地址、Markdown、PDF、源码归档是不同对象。

入口：exportDoc（`eval-crawl-crawl/service/harness_runtime_wire/web_round_artifact_exporter.go:131`）、Markdown 导出（`eval-crawl-crawl/service/harness_runtime_wire/web_round_artifact_exporter.go:291`）。

### 15.3 PPT 与 Excel

PPT 走 Office 下载服务，解析 PDF/PPTX 地址，实际下载后分别保存 `main.pptx`、`preview.pdf`，再尝试 source ZIP 与在线副本。

Excel 保存 `main.xlsx`；当前分支不要求同时有 PDF，不能说所有 Office 产物都有 PDF 预览。

入口：exportOfficeFile（`eval-crawl-crawl/service/harness_runtime_wire/web_round_artifact_exporter.go:320`）、下载地址解析（`eval-crawl-crawl/service/harness_runtime_wire/web_round_artifact_exporter.go:524`）。

### 15.4 妙搭

妙搭资源 ID → 展示地址 → repo path/branch → clone 到临时目录 → 删除 `.git` 元数据 → ZIP 归档 → 上传产物存储 → 把展示 URL 和源码 ZIP 引用写进快照。

因此妙搭展示页和源码归档不是一个 URL；索引的 `render_type=html` 也不表示实际上传对象一定是 HTML 文件。

入口：exportMiaoda（`eval-crawl-crawl/service/harness_runtime_wire/web_round_artifact_exporter.go:384`）、repo 归档（`eval-crawl-crawl/helper/miaoda_eval.go:142`）、目录上传（`eval-crawl-crawl/service/tos.go:360`）。

### 15.5 file-block 与 WebView

file-block 选择可下载的 SourceURL/CDNURL/TOSKey，下载实际字节，按文件类型保存 `main.<ext>`。代码把 byte 转 string 传给上传函数，不等于把视频/压缩包都转成文本。

WebView 文档还可能通过 resource tree 获取节点文本并转存，是另一种分支。

入口：exportFileBlock（`eval-crawl-crawl/service/harness_runtime_wire/web_round_artifact_exporter.go:443`）、WebView 导出（`eval-crawl-crawl/service/harness_runtime_wire/web_round_artifact_exporter.go:188`）。

### 15.6 stage2 Office 模块主要聚合什么

以 PPT 模块为例：读取 SampleResult → 收集 `Rounds[].OfficeArtifactSnapshots` → 按类型筛选、去重 → 无素材 skipped → 保存 `office_ppt.json` 索引。真实 PPTX 的下载常已在采样阶段完成。

为了兼容历史缺少冻结快照的数据，legacy 解析仍可能有导出 fallback。因此也不能反过来说 stage2 或 legacy_bundle 永远不发网络请求。

入口：PPT executor（`eval-crawl-crawl/ai_harness/modules/artifact/doubao_web/office_ppt/executor.go:11`）、索引聚合（`eval-crawl-crawl/service/harness_miniapp_runtime/web_artifact_collector.go:125`）、旧数据 fallback（`eval-crawl-crawl/service/harness_miniapp_runtime/legacy_artifact_resolve.go:9`）。

## 16. 普通 trace、MoA、MCP IO 的区别与顺序

```text
最后有效轮次的消息快照
 → 恢复 PushMessage，提取 Ext.inner_log_id
 → 普通 flow trace RPC
 → legacy trace 映射
 → MoA cached HTTP（适用场景且开关启用）
 → MoA 强/弱依赖判定
 → trace 非空与完整性校验
 → Shared trace、MoA JSON、trace JSON
 → MCP IO 提取
```

普通 trace 国内 China-North 走 `GetTraceDoubaoCiciDebugByCached`，其他区域走对应非 cached 方法；RPC 错误、异常响应、空 spans 都会失败。这里存在有限请求重试，不能等同于 Scheduler 整个 stage2 重试。

MoA 使用独立 HTTP 接口 `/trace_data/cached`，参数是模型请求 inner Log ID 与业务 ID。`need_moa_trace` 可以由采样快照 Ext 决定强依赖，覆盖当前环境 live 配置。404、429、5xx 和网络/读取异常可归入可重试失败；强依赖失败导致 trace 产物失败，弱依赖可能只告警。

MCP IO 优先复用同次执行的 Shared trace；没有时读 trace 对象，再抽取工具输入/输出。它不是第三次独立回捞整个模型 trace 的服务。

入口：backend 执行顺序（`eval-crawl-crawl/service/harness_runtime_wire/trace_backend.go:34`）、普通 trace 下游（`eval-crawl-crawl/downstream/trace.go:38`）、MoA HTTP（`eval-crawl-crawl/service/harness_runtime_wire/moa_trace_backend.go:295`）、快照 Ext（`eval-crawl-crawl/ai_harness/modules/artifact/common/trace/snapshot_ext.go:14`）、完整性与发布（`eval-crawl-crawl/ai_harness/modules/artifact/common/trace/module.go:73`）、MCP IO（`eval-crawl-crawl/ai_harness/modules/artifact/common/mcp_io_log/module.go:45`）。

此前那次故障正好覆盖这一分支：普通 trace 空 spans 后仍继续 MoA；MoA 强依赖最终超时，trace line 失败，MCP IO 没继续，但其他产物和已有回答仍可保存。这只能说明该次执行，不应把一个样本错误泛化为所有项目。

之所以查询 `/trace_data/cached`，依据是当前 Crawl 的 MoA HTTP 调用实现，不是从页面 URL 猜测。你提供的 Biz Log ID 后缀 `stage2_20261102162507` 和当时日志对应的是 11 月 2 日这一轮产物执行；模型原始请求用另一个 `inner_log_id` 标识，不能把两者当作同一时间，也不能据此确定第一次回捞的时间。

关于先前提到的“三天过期”：当时只能看到原始请求日期与 stage2 日期约差三天，以及缓存未命中，没有读到 MoA 的保留策略或清理记录。这个时间差不能推出 TTL 为三天；缓存未命中、未生成、索引或参数问题需要 MoA 侧进一步证据区分，本文不把过期作为已证实根因。

## 17. 截图与落地页：可靠交付不等于实际完成

两者都有异步交付，但执行载荷与后台工作不同。下面的输入 SHA256、真机 capture 和截图投影流程专指截图，不能套给落地页。

截图输入由采样快照和消息坐标构造，包括 conversation、最后轮次 QueryIdx、最大 LastMessageIndex、UID、AB、截图导航参数、回放材料、产物身份与 generation。QueryIdx 和 LastMessageIndex 是两个不同坐标。

主 stage2 交付过程：

```text
准备 dispatch / generation
 → 输入规范化、计算 SHA256
 → 输入快照上传 content-addressed TOS key
 → DB 确认快照
 → MQ 发布取得 receipt
 → DB 确认 delivery
 → 返回 running + pending ref + TaskGate satisfied
```

后台截图 consumer：

```text
校验 dispatch/generation
 → 抢 lease、读 checkpoint
 → 检查匹配 legacy_bundle 依赖
 → 读取输入快照并校验 SHA256
 → 真机截图
 → 保存 source checkpoint
 → 把截图投影到 legacy_bundle
 → 保存 projected checkpoint
 → finalize 真实截图产物状态
```

如果中间失败重投，可以从 checkpoint 续做；旧 generation 不应覆盖新结果。设备占用、截图 RPC、OCR 判断等耗时属于截图 worker，主产物 worker不应同步等完整真机过程。

所以 stage2 的交付 gate 已通过时，截图产物仍可能是 running。排查截图要看独立交付、receipt、consumer 与终态，不能只看主 stage2。

入口：截图 module（`eval-crawl-crawl/ai_harness/modules/artifact/common/screenshot/module.go:61`）、可靠交付（`eval-crawl-crawl/service/harness_execution/deferred_artifact_publisher.go:162`）、交付 gate（`eval-crawl-crawl/service/harness_execution/deferred_artifact_publisher.go:270`）、截图 consumer（`eval-crawl-crawl/upstream/deferred_artifact/screenshot/pipeline.go:65`）、真机 wire（`eval-crawl-crawl/service/harness_runtime_wire/screenshot_backend.go:51`）。

落地页模块会先判断项目抓页配置，再固化 `flow_trace_indexes`、`search_cache_index` 等定位载荷，可靠发布到 MQ。它传给 Publisher 的输入 snapshot 为 nil，不采用截图那套输入快照 SHA256 与 capture 过程；后续 consumer 根据指定 trace/cache 线索定位 URL 并执行抓页、回填结果。两种产物只能在“异步交付与真实完成分离”这一层合并理解。

入口：落地页 module（`eval-crawl-crawl/ai_harness/modules/artifact/common/landing_page/module.go:61`）。

## 18. legacy_bundle、真实文件和数据库引用如何配合

`legacy_bundle` 是新 Harness 对老展示/导出协议的兼容聚合对象。它组合 SampleResult 与当前已有产物，生成 message_list、query_result_bundle_list、flow_chat、debug_info、flow_trace、工具信息、截图 URI、artifact_list、file_block_list 等结构。

每条产物线结束都会刷新一次，最后再 final flush。没有 trace ref 时，可以生成仍有回复、但缺 trace 的部分 bundle；随后独立截图 consumer 还可能回填截图。因此 bundle 存在与任务整体成功不是同义词。

First-Re 等候选场景还有额外严格校验，不应把允许部分结果泛化到所有候选。

存储契约也要分开：

| 存储对象 | 典型内容 | 引用 |
|---|---|---|
| 通用 Sample/Artifact JSON 存储 | SampleResult、message_list、trace、legacy_bundle 等 | 通常返回 key/ref |
| 文件产物存储 | md、PDF、PPTX、XLSX、source ZIP、源码包等 | key 或 URL，具体按客户端约定 |
| VM 产物存储 | VM bundle 及运行文件 | 独立 ArtifactTOS，可能返回公开 URL |
| MySQL 元数据 | 状态、错误、采样引用、产物引用、版本和异步交付信息 | 不等同于文件正文 |

不要假定所有对象都进同一个桶，也不要把逻辑常量当所有地域的物理桶名。真实目标、URL 前缀按当前地域配置解析，以实际返回 ref 为准。

常见路径外形：

```text
harness/<storage_scene>/sample/<scene-item>/sample_result.json
miniapp_artifacts/<scene-item>/message_list.json
miniapp_artifacts/<scene-item>/trace.json
miniapp_artifacts/<scene-item>/legacy_bundle.json
harness/<scene>/artifact/<scene-item>/office_ppt.json
cua-runs/<run>/<attempt>/rounds/round-001/artifacts/<type>/<identity>/main.pptx
```

同名参数也可能有不同含义：普通 sample key 的 BizItemID 通常取 SceneID，而每轮 Office exporter 的 `WebRoundArtifactExportInput.BizItemID` 当前取 TechItemID。查文件时要沿实际调用值，不要只看变量名字。

入口：legacy 聚合（`eval-crawl-crawl/ai_harness/modules/artifact/common/legacy_bundle/legacy_builders.go:49`）、缺 trace 兼容读取（`eval-crawl-crawl/ai_harness/modules/artifact/common/legacy_bundle/legacy_trace_debug.go:23`）、通用存储装配（`eval-crawl-crawl/service/harness_miniapp_runtime/factory.go:29`）、TOS backend（`eval-crawl-crawl/service/harness_runtime_wire/tos_backend.go:78`）、文件目标解析（`eval-crawl-crawl/service/tos.go:97`）、Office 路径构造（`eval-crawl-crawl/service/harness_runtime_wire/web_round_artifact_exporter.go:485`）。

## 19. 状态如何回写，为什么不是一套状态

单产物会写 `biz_artifact.biz_status/result_key/result_type/error_code/error_msg`，并在 `extra.harness` 保存样本引用、raw ref、重试信息及产物扩展。MoA 还可能通过 trace 产物扩展携带第二个 TOS 引用，不一定是独立 Artifact 行。

汇总完成后先同步最终产物状态，再把 success、retryable、rate_limited、error code/message、artifact_refs、failure_source 等转成 Scheduler `SubmitItemRes`。上报目标是 `ItemID + ExecutorKey`，不是随意传 TaskID。展示错误会追加运行时 Biz Log ID，原始错误另在日志和 failure source 中保留。

| 状态层 | 常见状态 / 解释 |
|---|---|
| Biz Project | init、running、pausing、stop、resuming、success、failed、overtime |
| Biz Task | init、running、success、failed、filtered、discarded |
| Biz Scene | init、running、success、failed |
| Artifact | accepted、running、succeed、failed、skipped |
| Scheduler Item | init、queue、running、success、fail |
| Delivery | prepared、published、bound、cancelled、quarantined |
| 自动评估 | 独立 wait/doing/success/fail 等，不代表抓取阶段状态 |

`CanRetry=true` 只是上报可重试，并不等于当前仍会自动重试。具体重试预算、退避及终态由调度策略与运行配置决定，不能从一句静态提示推出。

Admin 还有状态对账与恢复链路：读取 Scheduler project/task 统计与明细，检查计数和身份关系，再按版本/CAS 收敛 Biz Task/Project，保护 stop、pausing、resuming 等控制状态。这里不是一笔跨服务同步事务，所以状态短暂不一致可以出现。

`biz_project.total_task` 由 Biz Task 持久化事务累计，与 `schedule_task_id` 是否已经绑定是两个事实；不能把总题数解释为调度成功数。

入口：产物 DB 投影（`eval-crawl-crawl/dal/biz_db/artifact_execution.go:40`）、上报前同步（`eval-crawl-crawl/service/harness_execution/engine.go:1538`）、上报协议转换（`eval-crawl-crawl/service/harness_execution/scheduler_client_external.go:58`）、业务状态枚举（`eval-crawl-admin/models/biz/config_types.go:39`）、任务计数（`eval-crawl-admin/service/repository/task.go:3071`）、Admin 对账（`eval-crawl-admin/views/biz_project_reconcile.go:1183`）。

## 20. 数据如何回到列表和结果预览页

### 项目列表与题目列表

项目跳转链接保留 `eid`，Biz 项目附加 `use_biz_storage=1`。当前题目列表按 URL 标志选择 next 的 `/biz/evaluate_task/list?is_gpt=1` 或兼容列表接口；不能假定不带标志的直达 URL 总会先自动探测一次。

Biz 题目列表主要读取 DB 的 Task list index，合并人评 sidecar，再补最新 Artifact/Env 展示字段。它不会为每一行重新请求模型、查询 trace，通常也不逐行下载 TOS 正文。

入口：列表 URL（`eval-fe-search-chat/apps/evaluate/src/routes/crawl/project_list/utils/task-detail-url.ts:8`）、列表 API（`eval-fe-search-chat/apps/evaluate/src/services/next-link-crawl.ts:199`）、列表查询仓储（`eval-crawl-admin/service/repository/task_index.go:82`）。

### show_shot 结果预览

仓内页面通过 Neeko 动态模板与组件渲染。仓内 `evaluate-material` 实现请求共享读取入口：

```text
GET /admin/label/get_evaluate_task_by_env/
  eid=<项目ID>&task_id=<TaskID>&start_env=0&env_offset=10

GET /admin/label/get_evaluate_task/federation_debug_info/
```

它们不是简单改成 `/biz/get_evaluate_task_by_env`。共享后端入口按壳指针路由 Biz/legacy。

Biz 分支读取 Task/Project/Artifacts，按 env_idx 把 `artifact_legacy_bundle.result_key` 填入兼容的 `crawl_result`，再通过 formatter/TOS 读取器解析对象，返回回复、消息、debug、文件等信息；最新截图/落地页状态也可以补入展示。

前端按环境合并 `project_query_config[index]`、`crawl_result[index]` 和 debug，形成渲染用的 `env/crawlResult/envConfig/debugInfo`。浏览器可能随后按已返回的 URL 展示文件或图片，但这不等于直接读取 SampleResult 并自己跑后端产物计划。

动态模板/远程组件有独立线上版本。本文核验的是仓内实现，没有把本地组件版本当成线上当前必然加载版本。

入口：动态模板（`eval-fe-search-chat/apps/evaluate/src/routes/crawl/show_shot/page.tsx:93`）、前端读取 hook（`eval-fe-search-chat/packages/evaluate-material/src/components/evaluate-container/hooks/use-evaluate-container.ts:67`）、前端环境合并（`eval-fe-search-chat/packages/evaluate-material/src/stores/crawl-result/actions.ts:27`）、Biz 读取分支（`eval-crawl-admin/views/biz_task_read.go:390`）、Artifact→crawl_result（`eval-crawl-admin/service/repository/task_index_assembler.go:51`）、TOS 正文解析（`eval-crawl-admin/models/task.go:1851`）。

## 21. 需要从普通主线分开的几种情况

| 场景 | 和普通双接口/两阶段主线的区别 |
|---|---|
| 定时一次性抓取 | 可先创建 Task 而延迟下发，到点由定时流程推进 |
| 周期抓取 | 前端先建 periodic project 模板，再以 periodic_id 调创建任务；不是每次都直接调用普通 add 项目接口 |
| 实时来源 | 建立订阅与终止条件，题目随数据流产生，不是 HTTP 一次提交所有题目 |
| 项目编辑 | 主要更新配置，通常不重新创建全部 Task |
| Merlin/Vmok 嵌入表单 | 可由宿主拿参数发起后续请求，不能直接套普通页面 Hook |
| session_replay | 取得历史消息、离线 trace、附件后保存样本；回放 trace 不应走普通实时 trace RPC |
| web_compete/app_compete | 外部任务 pending/回调链路，只有 Stage1 调度 Item |
| doubao_cua/competitor_cua | VM/GymHub 与 runner bundle，不是普通聊天 SSE 和手机长截图实现 |
| dola_web | 场景配置与部分导出能力不同，不能套国内 Office/Miaoda 全集合 |

## 22. 重试、重抓、刷新和修复不是同一动作

| 动作 | 改变什么 | 是否重新请求模型 |
|---|---|---|
| Scheduler stage2 重试 | 同一业务样本的未完成产物执行与上报 | 普通场景不重新采样 |
| RefreshHarnessArtifacts | 按现有样本刷新指定产物 | 不重新采样；手动接口不等于自动补齐 Scheduler 全部终态 |
| 选题手动重抓 / ForkCompletedTask | 新建替代 Task/Scene，ReplaceTask，旧 Task discarded | 新执行会重新采样 |
| 项目失败恢复 | 调 RerunProject 并同步 Biz 失败状态 | 具体从哪个 Item 恢复需以 Scheduler 实际实现为准 |
| TaskDelivery repair | 修复 Task 投送、创建/调度绑定 | 不等于修复模型或 trace 运行失败 |

补采通常复用旧 SampleResult。改当前 Project/Env 配置不保证覆盖旧样本，尤其采样快照中保留的 `need_moa_trace` 等配置。关掉当前页面一个开关，不一定能改变旧样本的强依赖要求。

手动刷新也不等于只重读旧消息文件：message/trace/screenshot/legacy 等适用类型会设置 `ForceRefreshMessages=true`，重新读取当前会话消息，但仍不向模型重新提问；Office/Miaoda/file-block 等依然消费已经冻结的资源快照。

入口：手动产物刷新（`eval-crawl-crawl/service/harness_execution/handler.go:526`）、替代 Task 重抓（`eval-crawl-admin/service/repository/task_recrawl_fork.go:125`）、项目失败恢复（`eval-crawl-admin/service/projectfailrecover/recover.go:78`）、Delivery 修复（`eval-crawl-admin/service/taskdeliveryapp/provider.go:463`）。

## 23. 抓取结束后：自动评估与人评在哪里

抓取产物是评估的输入，不是评分本身。自动评估有独立 Project/Task 子状态；送标流程读取任务与产物，把它们组合成标注平台需要的数据。

旧 `evaluate_project/evaluate_task` 壳行还承担人评 sidecar：reviewer、盲测、评分模板、score_valid、highlight 等。展示时按白名单与 Biz 抓取事实合并，不能让人评字段覆盖抓取执行身份与状态。

因此“抓取成功但自动评估失败”“抓取有部分回复但尚未送标”“旧壳行存在但新抓取事实在 Biz”都需要分别解释。

入口：人评 sidecar（`eval-crawl-admin/helpers/biz_adapter/human_sidecar.go:13`）、自动评估状态（`eval-crawl-admin/models/biz/auto_eval_state.go:3`）、送标消费抓取结果（`eval-crawl-admin/biz/aidp/service/send_label_service.go:1210`）。

## 24. 第一次读代码与第一次排障的顺序

建议先拿“一个项目、一个输入、一个环境”顺着以下路径读，不必一开始读完所有场景和兼容分支。

| 顺序 | 先回答的问题 | 入口 |
|---|---|---|
| 1 | 页面到底发了什么 JSON，第二个请求如何拿 ID？ | `crawlTask.mutation.ts` → `projectAdapter/taskAdapter/sourceBuilders` |
| 2 | 配置保存到了哪里？ | `BizAddEvaluateProject` → `CreateBizProject` → ProjectRepository |
| 3 | 具体题目如何变成 Task/Scene，HTTP 是不是只受理？ | `BizCreateTasks` → JSON entry → async create → TaskRepository |
| 4 | 调度怎样派出两个阶段？ | TaskScheduleDispatcher → CreateTaskReq/Items → Crawl handler |
| 5 | 模型回答从哪个模块出来？ | SamplingEngine → scene recipe → send_sse / confirm_reply |
| 6 | 回答在哪里交给产物阶段？ | save_round_result → SampleResult → scene.extra.harness.sample_result_ref |
| 7 | 哪类产物失败，是否是上传失败？ | artifact policy → recipe lines → 对应 module / wire / exporter |
| 8 | 页面为什么显示当前状态和内容？ | biz_artifact → legacy_bundle → Admin read/formatter → 前端 renderer |

后端排障按证据链展开：

```text
eid / tid
 → 壳指针映射
 → Biz Project / Task / Env / Scene
 → schedule_*_id、TechItemID、ExecutorKey、Biz Log ID
 → 当前 stage、worker/claim/heartbeat/limiter
 → SampleResult 对象与 DB ref
 → effective artifacts、每条 line 的结果
 → 文件导出URL / 源下载 / TOS上传 / JSON索引 / DB引用分别检查
 → deferred receipt / checkpoint / consumer
 → SubmitItemRes 是否被 Scheduler 接收
 → 列表投影、详情解析与前端展示
```

| 表象 | 优先看哪层 |
|---|---|
| 创建项目接口直接报错 | 参数、身份、场景、配额、DB 事务、Scheduler 项目绑定 |
| 创建任务返回成功，但暂时没有题目 | 来源解析、异步创建日志、定时/实时、可选 BMQ materialize |
| 有 Task，但未开始执行 | schedule_task_id/scene_id 是否绑定、Scheduler Item 状态、准入/限流 |
| 模型已有文字但 stage1 失败 | confirm_reply、每轮 Office 导出、SampleResult TOS/DB交接 |
| trace 查询失败 | 内层 inner_log_id、普通 trace/MoA 原始错误、快照强依赖 |
| 文档有预览但下载失败 | preview 与 main 文件是否是两个对象、URL来源、源下载/转存/权限 |
| stage2 完成但截图 running | deferred 输入/receipt/generation、consumer 与 checkpoint |
| 详情有回复但列表失败 | partial bundle、其他产物失败、DB index 与最新 Artifact 状态 |
| 抓取成功但没评分 | 自动评估/送标/人评 sidecar，不能继续只查 Scheduler stage2 |

可用只读诊断路由 `GET /admin/label/biz/debug/schedule/diagnosis?legacy_project_id=<eid>&legacy_task_id=<tid>` 汇总身份映射与调度状态；它不是所有原始错误和 TOS 正文的替代品。

## 25. 用几条只读 SQL 认识数据关系

下面的 `<...>` 是占位符，先从壳映射拿到实际 Biz ID。SQL 只用于说明字段关系，不代表已经对线上执行。

```sql
SELECT id, biz_project_id FROM evaluate_project WHERE id = <eid>;
SELECT id, biz_task_id FROM evaluate_task WHERE id = <tid>;

SELECT id, schedule_project_id, biz_status, total_task, success_task, fail_task
FROM biz_project WHERE id = <biz_project_id>;

SELECT id, env_idx, env_name, biz_scene_type, env_config, artifact_config
FROM biz_project_env WHERE biz_project_id = <biz_project_id> ORDER BY env_idx;

SELECT id, biz_task_id, env_idx, biz_scene_type, biz_status,
       schedule_scene_id, error_code, error_msg, extra
FROM biz_scene WHERE biz_task_id = <biz_task_id> ORDER BY env_idx;

SELECT id, biz_scene_id, item_type, biz_status, result_key, result_type,
       schedule_item_id, error_code, error_msg, extra
FROM biz_artifact WHERE biz_task_id = <biz_task_id> ORDER BY env_idx, item_type;
```

随后用 Scene 的 `extra.harness.sample_result_ref` 看交接样本，用 Artifact 的 `result_key/result_type` 找产物。不要默认 `result_key` 总是完整 HTTP URL，也不要忽略它可能暂时是 deferred pending ref。

## 26. 当前核验的边界

- 本文梳理的是当前检出代码机制；没有把本地源码等同于线上任意时间的部署版本和配置。
- Scheduler 的完整服务实现不在本机。其 RPC 派发/上报契约已核对，精确队列算法、退避次数、内部状态聚合与 RerunProject 子项重置策略没有编造。
- 当前文件存在一些陈旧注释，例如项目创建失败清理、任务计数口径等；本文按实际函数实现整理。
- 整理过程没有触发真实创建、重抓、改状态，也未运行 Go 构建或测试。

