.pouch/skills/tester/SKILL.md

name, description

name	description
tester	维护并执行项目黑盒测试目录（.pouch/tester）：列出/增改用例，按分类或 id 跑脚本、浏览器或移动模拟器；支持用 Orca project id、项目名称或 terminal id 定位 Agent 执行环境并创建临时 terminal。触发词：/tester、列出测试、完善测试用例、 按分类测、跑 smoke、现场复测；测试环境由本机触发，正式环境由 app00 Agent terminal 委派部署。 默认风险最低档；local 配置的 HOST 默认是 127.0.0.1。

Tester：项目测试目录

开始时解析本 SKILL.md 所在目录为 <skill-dir>。项目根用 git rev-parse --show-toplevel。目录固定为目标测试项目的 <root>/.pouch/tester/；父仓库 和 Git submodule 可以各自拥有独立目录。

多测试项目 / 子项目

一个仓库可能同时包含后端测试目录和 app 等子项目测试目录。用例属于拥有 catalog.yaml 的项目，不能把多个 catalog 的 cases 合并成一份清单或共用一次运行快照。

开始列出或运行前，先发现目标仓库下的独立测试根：

python3 <skill-dir>/scripts/catalog.py roots --root <repo-root>

选择规则：

• <repo-root>/.pouch/tester/catalog.yaml 存在时，它是一个独立测试根；
• 同时检查 Git submodule 和一层普通子项目目录；
• 只有一个嵌套 catalog 时，可直接用该路径继续 list/select/run；
• 有多个 catalog 时由 tester 自动 fan-out，逐个项目分别执行，不等待用户选择，也不合并 cases；
• 每个测试根单独生成 .pouch/tester/runs/*.yaml/.csv，交付记录可分别引用这些快照。

如果父仓库没有 catalog 但子项目有 catalog，不能把“父目录无 catalog”报告为环境失败；先用 roots 找到子项目并继续。只有发现不到任何 catalog，才按缺少 tester 目录处理。

CLI 也有同样的保护：从父仓库执行 list/select/validate/run-script 时，若只发现一个 子 tester 根会自动进入该根；发现多个候选会自动 fan-out，每个根独立输出、独立校验、 独立生成运行记录。不需要、也不能通过在根 .pouch 里写一个未定义的 include 来拼接 子项目配置。

Agent 执行目标优先来自项目根 .pouch/agent.yaml 的 tester.<name> binding，由共享 agent-runtime 解析 environment、host、project、path 和 profile。.pouch/tester/local.yaml 仍是兼容覆盖层：解析 binding 后可 materialize 为旧 agent mapping，但不应再维护两套 互相矛盾的主配置；binding 名称不是固定枚举。

用脚本读写目录，不要把 cases/ 整库灌进上下文。术语与命名理由见 references/concepts.md：

python3 <skill-dir>/scripts/catalog.py <roots|list|select|show|validate|next-id|run-script> \
  --root <project-root> [参数]

运行目标可用 resolve_agent.py 按 Orca project id/名称或 terminal id 自动解析并写入 .pouch/tester/local.yaml 的 agent 配置；配置更新完成后输出生效配置列表。该列表是 更新结果，不是测试启动前的人工确认门槛。

用户给出 tester.<name> 时，先用共享 agent-runtime 校验并精确解析，再写入兼容的 tester agent 配置。

选择模式

• 先用 roots 检查当前仓库及子项目；没有任何 .pouch/tester/catalog.yaml，或用户说初始化 tester：执行「初始化」。
• 列出、有哪些测试、一共多少条：执行「列出」。
• 看某一条怎么测：执行「查看」。
• 加一条 / 完善 / 改验证 / 退役：执行「维护」。
• 检查目录是否完整：执行「检查」。
• 跑测试、按分类测、按 id 测、跑 smoke：执行「运行」。

边界（所有模式）

• local.yaml.example 的 HOST 默认是 127.0.0.1；如果目标不是本机，必须在 local.yaml 或环境变量中显式覆盖。local.yaml 不存在且没有环境变量时仍不猜 HOST，停下并记 environment-fail。
• 默认风险上限是 catalog 里的 default_max_risk。超出上限的条目标 skipped，禁止执行。
• risk 只能是 readonly / mutating / destructive，默认只跑 readonly。tag=smoke 只能配 risk=readonly。规则见 levels.md。
• driver=browser 必须开真实页面；driver=mobile 必须挂模拟器 session。二者都不得改成只打 API。
• automation=assisted|manual 需要人在场：无人值守时记 not-run，不要自己代跑人工步骤。见 concepts.md。
• 浏览器、移动模拟器按 catalog sessions 初始化一次，同一次运行内复用。
• Agent、环境、项目目录和 Orca terminal 生命周期见 execution.md：可以从 project id/名称或 terminal id 自动解析，更新后输出配置列表；每轮都新建 terminal，结束后关闭本轮创建的 terminal，不复用或关闭已有 terminal。
• 环境准备见 deployment.md：测试环境只调用 deployer 的本机 Compose 路径；正式环境只委派给本机 ~/code/app00 的 fresh Agent terminal，tester 不直接 SSH 或执行生产 Compose。
• HOST 只表示被测服务地址；远程执行目标使用 agent 配置。目标目录必须已有项目内容，找不到 Orca 项目记录时直接登记已有目录；目录本身不存在时停止，不创建空项目。
• 环境失败（连不上、缺浏览器、下游超时、session 挂了）不是产品失败。
• 移动端运行必须先通过 run.md 的平台环境闸门；Android 与 iOS 分开探测。目标平台没有可用设备/模拟器时，先停止移动用例，记 environment-fail，并按 run.md 的模板引导用户补齐环境，不能只报一个失败状态。
• 环境引导必须写明平台、具体缺失项、用户可执行的修复动作、验证命令和重跑方式。不得用 API 调用替代真实 Android/iOS session，也不得把环境缺失判成产品 fail。
• 不改产品代码，不提交，不把成绩单当操作手册。
• 禁止把完整 cases/ 贴进 prompt。筛选用 select，单条用 show。

初始化

用户点名才跑。已有 catalog.yaml 则不覆盖，转入「检查」。

1. 建 .pouch/tester/{cases,runs}/。
2. 若不存在，从 <skill-dir>/templates/ 拷 catalog.yaml 和 local.yaml.example。
3. 从模板生成的 local.yaml 默认使用 HOST: "127.0.0.1"；不要根据项目内容猜远程地址。
4. 跑 catalog.py validate --root <root>。无用例是「部分完成」，不是失败。

## tester 初始化：完成 | 部分完成 | 阻塞

已具备: …
待配置: 路径 + 字段 + 缺了会挡住哪步
下一步: 一句话

列出

python3 <skill-dir>/scripts/catalog.py list --root <project-root>

把脚本打印的分类表原样给用户。不要手算条数。清单 CSV 由独立脚本从 cases/*.yaml 生成：

python3 <skill-dir>/scripts/generate_cases_csv.py --root <project-root>

list 结束时也会跑它。告诉用户路径 .pouch/tester/cases.csv。不要手改 CSV，改用例走「维护」后再生成。该 CSV 只包含用例定义；运行结果只写入独立的 .pouch/tester/runs/<run-id>.yaml，不会回写清单。

查看

python3 <skill-dir>/scripts/catalog.py show --root <project-root> --id <CASE_ID>

只展示这一条的 how / expected / risk / driver / automation。字段对不上时再读 schema.md。

检查

只读。跑 validate。HOST 是否已配置只报「已设 / 未设」，不要把 local.yaml 全文贴出来。用初始化同一套报告，标题改为 ## tester 检查：…。

维护

读 maintain.md。写 tag/risk/automation 时读 levels.md 与 concepts.md。先 show 或 next-id，拟好条目给用户确认再写文件，然后 validate。

运行

读 run.md、execution.md、deployment.md 和 test-bundle.md。运行必须按以下顺序执行：

1. 先建立本轮测试矩阵，列出实际要测的产物、平台、commit、包/Bundle 身份、产物路径或下载地址，以及对应的 tester.<platform> 执行绑定。用户要求 Android+iOS 时，两行都必须出现；不能因为只拿到 Android 产物就缩小范围。
2. 对所有 tester 根的矩阵行做完整 preflight：先用 catalog.py select 校验平台、产物定位和 tester binding，再检查目标 Agent/环境/项目路径、Android/iOS 设备闸门和 HOST 可达。所有根的检查完成前不得创建测试 session 或开始任何测试用例。
3. 有任一根或任一行不可用时，先完成其它根的 preflight，再一次性输出完整不可用清单、观测结果、修复动作和可复制的验证命令，然后停止测试执行；不能先执行已通过 preflight 的根，也不能把缺失平台记成测试通过。
4. 只有矩阵所有行都可用，才创建本轮测试 terminal/session，按 select 结果执行并记录成绩。

测试环境由本机 deployer 触发，正式环境由 app00 Agent terminal 委派。随后按 agent 解析目标项目、目录和 Agent，更新配置并输出生效列表。移动端每个平台的产物位置必须由调用方给出，值为本地文件或 URL；缺了就停，不要猜 builder、CI release 或本机旧包。矩阵行记产物位置、身份和 tester.<platform> binding，并用 <skill-dir>/tester run --artifact android=<path-or-url> --artifact ios=<path-or-url> --platform android,ios 下载或取用、安装并准备本轮隔离 worktree。Android 在 tester.android、iOS 在 tester.ios 节点执行。未指定范围时等同「tag=smoke 且风险上限=默认且 automation=automated」。select 的 run_together 组按 run.md 整组执行。无论部署或测试成功、失败、超时还是中断，都要清理各自本轮创建的 terminal。

客户端用户旅程标准

双层测试与执行顺序

用例顶层类型是 test_type: integration | journey。旧目录没有该字段时保持兼容：已有 client_suite/journey 视为 journey，已有 integration_suite 视为 integration。集成 套件至少包括 api-contract、authorization、build-contract；旅程套件仍固定为 client-smoke、client-regression、safety。集成用例不需要客户端 session、platform 或 journey 字段，不能被客户端套件选中。

一次运行严格遵守：

test-preflight (blocked/environment-fail -> 不创建 session)
  -> integration
  -> journey (integration fail -> not-run，不创建 session)

test-preflight 的报告是环境证据，不计入 testcase 总数。服务不可达记 environment-fail；服务已达但契约断言错误记 integration fail；正确测试账号登录失败 仍记 journey fail。tester 的 run/bundle 入口必须接收 caller 提供的 preflight matrix， 没有 matrix 不得绕过闸门或伪造成功。

声明 client_suite（迁移期也接受 suite）的用例采用固定的三套客户端集合： client-smoke、client-regression、safety。前两者分别覆盖最短只读主路径和隔离测试 环境中的普通用户回归；safety 覆盖危险/权限边界场景，必须显式选择和授权，不能被 默认 smoke/full 扩入。选择某套客户端旅程可用：

python3 <skill-dir>/scripts/catalog.py select --root <root> --suite client-smoke
python3 <skill-dir>/scripts/catalog.py select --root <root> --suite client-regression --max-risk mutating
python3 <skill-dir>/scripts/catalog.py select --root <root> --suite safety --max-risk destructive

客户端用例必须声明 journey、fixture、session、cleanup 和 platform。旅程包含 goal、entry_state、actions、assertions、final_state、failure_policy；fixture 至少声明测试账号；session 指向 catalog 中可复用的 browser/mobile session；cleanup 要有 步骤或命令（只读也要显式说明无需清理）；platform 只能是 Android/iOS。具体字段见 references/schema.md。平台适配只能改操作层，不能把真实客户端操作换成 API 调用。

客户端运行器统一遵守 preflight → 启动 → 登录 → 旅程 → 断言 → 清理 → 报告。正确测试 账号登录失败是产品 fail；设备、产物、服务或 session 不可达才是 environment-fail。 fixture 或 cleanup 缺失会在 catalog.py select 的 preflight 阶段阻断，不产生虚假逐条结果。 前置用例失败后剩余条目写 not-run，主动排除/未授权写 skipped。成绩仍写现有 runs/<run-id>.yaml 并用 generate_run_csv.py 生成同名 CSV；清理失败作为 cleanup 证据 单独记录，不添加新的 result 值。