.pouch/skills/tester/references/schema.md

tester 目录字段

项目根 .pouch/tester/：

catalog.yaml           分类、风险阶梯、session、变量
local.yaml.example     HOST 与授权开关模板
local.yaml             本机覆盖，不提交
cases/<category>.yaml  一个分类一个文件（执行源）
cases.csv              给人看的扁平清单；skill 的 generate_cases_csv.py 读 cases/*.yaml 生成
runs/                  每次运行快照

catalog.yaml

字段	含义
categories	{id, title} 列表，id 与 cases/<id小写>.yaml 对应
risks	从低到高，只能是 safe → act → harm 的一段，且以 safe 开头。含义见 levels.md
default_max_risk	未指定时的运行上限，必须是 risks 里的值
vars	可替换变量，如 API_BASE: http://${HOST}:8095
auth_env	风险名 → 环境变量名。该档执行前变量必须为 true
gates	可选。项目细分闸名 → 环境变量。用在用例的 gate 上，不要拿它代替 risk
sessions	可复用会话。kind: browser / mobile；reuse: run（本轮结束关掉）或 persist（probe 活着就附着）
id_pattern	用例 id 正则
run_together	可选。成组执行：[{ids: [TC-…, TC-…], continue_on_fail: true}]。点到组内任一条，select 会按 ids 顺序把整组扩进命中列表。continue_on_fail: true 时组内前一条产品 fail 仍跑后一条（返回/收尾）。一个 id 只能属于一组。

local.yaml 与环境变量覆盖 HOST 和授权开关。查找顺序：环境变量 > local.yaml > catalog.yaml 的 vars。也认 HX_TEST_HOST 作为 HOST。

一条用例

写在对应分类文件的 cases: 列表里。

字段	必填	含义
id	是	匹配 id_pattern
category	是	必须等于文件声明的 category
title	是	短名
what	是	一句可观察的「测什么」
status	是	active / retired
suite	是	smoke / full / slow，判定见 levels.md
risk	是	safe / act / harm
gate	否	项目细分闸，必须在 catalog gates 里
surface	是	script / browser / mobile
session	browser/mobile 必填	指向 catalog sessions 的键
how	是	怎么测，见下
expected	是	怎么过，至少一条 {kind, value}
maps_to	否	对人文档的功能项 id
requires	否	前置标签
skip_unless	否	额外跳过条件（环境变量表达式）
setup	否	人话前置
cleanup	否	跑完回退
notes	否	备注

how

• script：how.run 是一条可在项目根执行的命令（可多行脚本）。没有 run 时 Agent 按 how.steps 做，仍不得发明未写明的请求。
• browser：how.url + how.steps。expected.kind 用 visible-text / url / interaction。
• mobile：how.steps，挂到 session 指定的模拟器。expected 同样是可观察信号。

可选 how.timeout，秒，默认 60。

expected.kind

api-status / api-field / script-exit / visible-text / url / interaction

判定

pass / fail / environment-fail / skipped