## 诊断流程样例
### 入口
```bash
cd /Users/bytedance/Documents/job-bu/data-analysis-workspace
python tools/fornax_ark_preflight.py \
--backend fornax \
--config configs/session_labeling.yaml \
--sample data/session_sample_100.jsonl \
--limit 3
```
### 输入
| 输入 | 来源 | 用途 |
| --- | --- | --- |
| `ARK_API_KEY` | `.env` 或环境变量 | 校验当前 key 是否能访问目标 Ark endpoint |
| `endpoint_id/model/project` | 标注配置文件 | 检查 endpoint 是否存在、是否有权限、是否被暂停 |
| `prompt_id/evaluator_id` | Fornax 链接或配置 | 区分资产读取与真实 evaluator 执行 |
| sample records | 待标注 CSV/JSONL 前 1-3 条 | 验证字段名、schema 和输出解析 |
### 步骤
1. 读取配置并打印脱敏后的后端摘要：backend、endpoint/evaluator、输入字段、期望输出字段。
2. 如果是 Ark：先做 endpoint/key 可见性检查，再跑 1 条 chat/completions dry-run；遇到 `InvalidEndpointOrModel.NotFound`、无权限、Safe Experience Mode 上限时直接 fail-fast。
3. 如果是 Fornax：先 `fornax-cli prompt get-by-id` 验证资产存在，但不把它当作推理成功；随后调用 evaluator，并强制把样本包装为 `input_data.input_fields.<key>`。
4. 对返回内容做 schema 校验：必须能解析成标注 JSON，且关键字段非空。
5. 对 401/JWT 失败执行一次登录态刷新或提示 `fornax-cli auth login`，刷新后重试 1 次；仍失败则停止，不进入全量。
6. 写出 `out/preflight/<run_id>.json`，包含 `ok`、`blocked_reason`、`retryable`、`next_action`。
### 成功信号
```json
{
"ok": true,
"backend": "fornax",
"dry_run_count": 3,
"schema_valid": true,
"resume_policy": "only_status_ok_is_done"
}
```
### 失败信号
```json
{
"ok": false,
"blocked_reason": "fornax_jwt_expired",
"retryable": true,
"next_action": "refresh fornax login, then rerun preflight; do not start full batch"
}
```
### 预期落地效果
批量标注不再从 5279 条全量开始试错，而是在 1-3 条 dry-run 阶段暴露 key 不一致、endpoint 暂停、Fornax 入参协议错误或 JWT 过期。长跑中断后也只把 `status=ok` 当作完成，失败行可自动重试或人工处理。