先预览，再运行

以下命令只读取案例，不启动应用、不调用模型、不创建结果目录，也不需要配置真实模型：

conda run -n py3.11 python -m evals.run --list-groups
conda run -n py3.11 python -m evals.run --list-suites
conda run -n py3.11 python -m evals.run --suite smoke --mode direct --list
conda run -n py3.11 python -m evals.prompt_compare --group complex_vehicle --list

--list列出案例名、客户端模式和相对路径；列表末尾显示本次选择数量及目录中的总数量。--list-groups和--list-suites的计数也会应用当前筛选条件。

目录分组与测试集

--group精确选择现有目录，不靠名称子串猜测分组：

分组	数量	主要覆盖
`collection_skip_known_info`	12	已知信息跳过、缺项补充、人伤不确定、单方数量推断
`complex_vehicle`	2	首次明确三车事故即转人工，未知字段不补造
`customer_feedback`	4	客户原始反馈、连续呼叫、已知信息不重复问
`non_motor_vehicle`	14	非机动车参与、零机动车提取、保留已知事实、类型更正
`no_false`	2	ASR噪声不误转人工
`time_confirmation`	2	独立确认完整时间、补充信息保留、更正后重新确认
`photo_button_guidance`	12	单双车按钮指引、失败处理、不重复说明
`photo_skip_plate_confirm`	4	当前拍照步骤转换，不额外确认车牌

--suite选择跨目录测试集，定义集中在suites.yaml，只引用案例路径，不复制输入或断言：

测试集	两种模式合计	适用场景
`smoke`	12	修改后的快速回归；配合`--mode direct`仅6个案例
`collection`	36	采集提示词、表单保持、时间与事故分流
`vehicle_count`	22	数量推断、零机动车、类型更正、三车和客户反馈
`safety`	20	复杂事故、非机动车、ASR噪声、不确定人伤
`photo`	16	拍照节点和按钮交互
`feedback`	6	客户反馈，包括三车立即转人工
`full`	52	全量回归；不提供筛选条件也执行全量

详细场景索引及保留历史文件名的原因见cases/README.md。

局部测试示例

先启动待测试API，再运行远程HTTP评估：

# 只测试三车分流，先预览再执行
conda run -n py3.11 python -m evals.run --group complex_vehicle --mode direct --list
conda run -n py3.11 python -m evals.run --group complex_vehicle --mode direct

# 数量相关案例，仅direct客户端
conda run -n py3.11 python -m evals.run --suite vehicle_count --mode direct

# 同时选两个目录
conda run -n py3.11 python -m evals.run --group time_confirmation --group complex_vehicle

# 拍照测试集内只选双车，排除按钮失败场景
conda run -n py3.11 python -m evals.run --suite photo --case dual --exclude-case failure

# 指定服务及结果目录
conda run -n py3.11 python -m evals.run --suite smoke --base-url http://127.0.0.1:8000 --output-dir evals/results/smoke

本地LangGraph评估使用完全相同的筛选方式：

conda run -n py3.11 python -m evals.prompt_compare --suite smoke --mode direct --output-dir evals/results/local-smoke
conda run -n py3.11 python -m evals.prompt_compare --suite feedback --output-dir evals/results/local-feedback
conda run -n py3.11 python -m evals.prompt_compare --suite full --workers 4 --output-dir evals/results/local-full

执行本地评估需要配置AGENT_BACKEND=langgraph和真实的LLM_PROVIDER；建议用AGENT_STORAGE=memory隔离评估会话。--output-dir在实际执行时必填，预览时不必填。metadata.json记录筛选条件、选中的案例名、所有案例及提示词哈希，便于核对本轮覆盖范围。

远程入口继续支持python evals/run.py、EVAL_BASE_URL、--timeout、--insecure、--no-save；本地入口继续支持--prompt-dir提示词快照和--workers并发度。两个入口均支持--cases-dir指定其他案例目录。

筛选与去重规则

同类参数内部取并集：重复--group、--suite或--case表示任意一个匹配。
不同参数之间取交集：例如--suite photo --mode direct --case dual只选拍照集中的direct双车案例。
--case保持原有的案例名子串匹配；--exclude-case最后按名称子串排除。
重叠测试集中的同一个文件只执行一次，不因重复指定测试集而复制会话。
未知分组、未知测试集或空选择返回配置错误，避免把“没有跑任何案例”当作成功。
案例名必须唯一，避免输出文件相互覆盖。

此次整理未删除、移动或改写任何原案例。核对结果：同一客户端模式内，没有输入和断言完全相同的重复文件，也没有完整输入序列相同的文件。direct和browser_addon的相似案例验证不同请求模式与阶段码，保留为独立覆盖；只想测一种模式时使用--mode减少执行量。共同的欢迎和时间确认轮次是对话上下文的一部分，不单独抽掉。

新增案例与断言

把YAML放入现有目录，或新建业务目录；目录自动成为--group。新案例会自动纳入全量执行；按需要更新suites.yaml中的跨目录路径规则。套件定义放在cases目录外，避免被当成对话案例读取。

name: direct_example
clientMode: direct
steps:
  - input: 新对话
    expect:
      stageCode: "1001"
  - input: 继续办理
    expect:
      stageCode: "1002"

clientMode为direct或browser_addon，后者的阶段断言需要browser_addon.前缀。同一文件的各轮共享一个新生成的sessionId，不同文件使用不同sessionId。每个案例在首个失败轮次停止，并尝试清理会话。

可选断言：

字段	含义
`form`	累计表单的部分精确相等，包含类型检查
`formMatches`	自由文本字段的正则检查
`formAbsent`	尚不得提取的字段
`replyMatches`	回复必须匹配的正则
`replyNotMatches`	回复禁止匹配的正则

一个案例包含任意表单断言时，执行器全程请求needFormUpdate: true，跨轮合并SSE表单增量。因此未重复返回不变字段可以接受，后续错误覆盖会失败。SSE错误也使本轮失败。仅有注释、没有回复断言的旧案例仍需要查看实际对话。

当前边界：完整倒车撞固定物且无其他车辆参与线索按1辆处理；已知至少3辆机动车参与立即转人工；单/双车进入拍照前需要独立确认时间。非机动车参与的既有分支保留必要采集及时间确认。通过FastGPT评估当前提示词时，应先导入本仓库workflow/20261027快照；案例中的历史版本注释保留供追溯。

结果与补充语义检查

运行时打印每轮输入、回复和断言结果。远程入口默认保存到evals/results/<timestamp>/；本地入口保存到指定目录：

*.md：可读对话记录。
*.json：每轮阶段码、回复、表单增量、累计表单和断言。
本地入口另保存metadata.json、summary.json及运行日志。

两个入口实际执行时，任一案例失败返回1，配置错误返回2，通过返回0。--list等预览成功返回0。

prompt_probes.py用于局部状态快照和历史回放，独立于cases；time_boundary.py检查历史时间来源边界。它们不读取suites.yaml。示例：

conda run -n py3.11 python -m evals.prompt_probes --runtime --case complex_ --output evals/results/complex-probes.json
conda run -n py3.11 python -m evals.prompt_probes --runtime --exclude-case missing_historical_time_anchor --output evals/results/probes.json

missing_historical_time_anchor是此前用户要求暂缓的历史时间基准检查；仅显式排除时跳过，排除项单独记录，不能计为通过。本次整理没有改变这个边界。