quick-eval

运行有界评估

仅启动选定的评估，然后说明其证据支持什么。 对于语音评估，成功意味着实际进行语音对话并检查录音； 仅保存资源或运行状态显示已完成并不足够。

预检与预算

根据客户提供的上下文，确认目标组织、工作区和 API 环境；仅凭身份验证无法确定组织。复用客户的 Agent、角色设定和测试集。启动前，阅读确切的用例和指标定义。使用 coval --agent agent doctor、资源 context 和 --help。 不要输出密钥，也不要更改计算机的全局账户配置。

维护本地会话台账，记录启动 ID、用例、指标测试和已用预算。 如果未提供预算，先提议进行一次连接检查调用，然后最多进行三次对话，作为入门评估，迭代次数为一次，并发数为一。这些是建议的默认值，并非支出授权。遵守已授权的数量；计划或审计请求不构成付费调用授权。更大的范围需要明确预算；如果结果不确定，不要悄悄增加预算。

展示具体计划：ID、命名用例、指标、迭代次数和并发数、基础版本／变体、最大调用次数、配置的单次调用时长，以及墙钟时间停止点。成本包括 Coval、已连接的提供方和指标测试。Coval 可能会添加请求 ID 之外的必需指标或依赖指标；检查实际输出，并将计划中的指标数量视为请求的工作量，而非精确的计费总额。只有在当前费率已知时才报出金额；否则报告调用次数和时长上限。

调用次数 = 选定用例数 × 迭代次数 × (1 + 变体数)，按每个角色设定运行计算，并对所有运行求和。单个变体也会运行基础 Agent。并发只影响速度，不影响总调用次数。对现有输出重新评分会产生指标工作量，但不需要新的语音调用。明确预留重跑预算，不要将重试视为免费。不要假设取消操作能立即阻止所有已排队的调用。

构建并检查确切请求

使用所选测试集中的显式 options.test_case_ids。不要因省略参数而启动整个测试集，也不要在配对比较中用随机子集替代。检查当前的 runs schema。

{
  "agent_id":"<selected-agent-id>",
  "persona_id":"<selected-persona-id>",
  "test_set_id":"<selected-set-id>",
  "metric_ids":["<selected-metric-id>"],
  "options":{"test_case_ids":["<selected-case-id>"],"iteration_count":1,"concurrency":1},
  "metadata":{"display_name":"First evaluation - connection check"},
  "config_overrides":{"simulation_timeout_seconds":120}
}

确认当前 API／Agent 类型支持时长覆盖；否则使用已验证的存储时长限制，或停止以解决限制问题。不要顺带修改现有 Agent 来设置该值。启动后验证已创建的资源／运行元数据；本地计划并不是服务器强制执行的支出上限。

使用此已安装技能目录中的可选仅限本地规划器：

python3 scripts/plan.py --launch run.json --remaining-simulations 3 --max-concurrency 1

--remaining-simulations 表示本会话已获授权的剩余预算。 对于多个角色设定／运行，将所有启动请求体放入一个 JSON 数组，并一起验证整个批次；该辅助工具会从相同的剩余预算中扣减每次启动的额度。它会检查显式子集、正数上限、基础版本 + 变体，以及调用上限。它不会进行身份验证、验证资源所有权、预留预算、强制执行服务器端限制或启动任何内容。请分别读取每项资源，以确认所有权和用例归属。保留请求的精确副本。

启动一次并跟进该次运行

coval --agent runs launch --input-json @run.json

检查 ok 和退出代码；立即保存返回的运行 ID。如果超时或响应不明确，请先检查近期符合条件的运行，再考虑再次启动。不要盲目重试 POST。API 错误不等于结果为空。

以合理的间隔（例如每 20–30 秒）轮询 coval --agent runs get <run-id>，直到运行结束或达到约定的截止时间。状态名称可能包含空格；请以当前响应为准。不要用 runs watch 无限等待。到达截止时间时，报告仍在进行的运行并保留其 ID。不要因为第一次运行较慢就启动第二次运行。只有在用户提出请求，或已纳入约定的停止策略时才取消，并核实取消后的状态。

审核结果，而不只是运行状态

对于小规模运行，请检查每段对话和每个选定指标：

coval --agent simulated-conversations list --run-id <run-id> --page-size 100
coval --agent simulated-conversations get <simulation-id>
coval --agent simulated-conversations metrics <simulation-id>
coval simulated-conversations audio <simulation-id> -o <local-recording.wav>

某些 CLI 版本不会提供分页令牌。要获取完整证据，可选用以下只读辅助工具，通过分页请求公共 API，并严格限定运行范围：

python3 scripts/fetch_run.py --run-id <run-id> --workspace-id <workspace-id> --out run-evidence.json

该工具从环境中读取 COVAL_API_KEY，使用 https://api.coval.dev/v1，并写入包含对话记录的本地私有文件。切勿粘贴或导出密钥，也不要将其读入终端输出。--max-conversations 限制读取数量（默认值为 100）；超过限制时，工具会报错，而不会默默声称数据完整。该工具适用于公共生产 API；对于其他明确选定的环境，请使用其文档所述的 API，并执行相同的范围限定和分页检查。不要为了让辅助工具正常工作而悄然切换环境。

快照会保留已被取代的指标输出，避免后续重新评分时悄然替换历史证据。请选择预期的输出 ID 和版本；同一指标的多个输出不代表额外的对话。如果标准子值缺失或被标记为已截断，请检查完整的指标详情。快照不包含原始运行时元数据；如果模型来源信息很重要，请单独获取确切的输出。

请检查：

• 预期与实际调用次数、选定的用例 ID，以及基础用例和变体用例的数量。
• 每段对话的状态和结束原因、对话双方的发言，以及调用方是否实际执行了该用例。区分模拟器／测试设计故障与 Agent 故障。
• 语音录音的获取情况和相关音频片段。has_audio 是可用性元数据，并不表示已实际听取。避免公开带签名的录音链接。
• 每个选定指标的状态和覆盖情况。FAILED、SKIPPED、CANCELLED、缺失值和 null 值都表示尚未评估，不能视为零分或通过。
• 数值、单位、极性、说明和各项标准的详情。仅由调用方引用的正确答案，不能证明助手回答正确。
• 捕获到的指标版本／模型元数据以及提示词／配置快照。如果无法获取历史版本证据，请如实说明，不要用今天的定义替代。

如果对话记录或指标结果尚未就绪，请针对相同 ID 进行有次数限制的只读轮询。切勿自动重新模拟。不要使用旧版 /eval/* 回退方案。

报告并停止

分别报告实际运行／资源 ID、请求数／实际观察数／评分数、执行失败、质量发现和未知项。使用用户所在组织／工作区上下文中已验证的应用 URL。说明实际听取、阅读和测量了哪些内容。一次小规模成功运行只是冒烟测试，不能代表生产环境中的普遍情况，也不能提供统计置信度。在本地保留原始证据；分享时请隐去敏感内容。

根据结果建议一个后续步骤。不要自动进行爬坡优化、修改 Agent 提示词、新增用例、更改指标默认值、安排任务或清理数据。