tc-run

Skill：tc-run — 从完整测试用例文件到逐批次报告

摘自 2026 年 9 月 15 日的 Payroll SIT 会话（335 个 TC，7 个工作表）。确定性工具：harness/scripts/tc-xlsx.py （extract · classify · plan · report）。批次运行时：/orca-graph。浏览器：claude-in-chrome （使用已登录的用户会话，即 SSO）。报告：MCP tester-kit → tao_report_test。

WHAT

目的和背景

• 目的： 将一个完整的测试用例 .xlsx 文件转换为结果，每个 TC 都有 PASS/FAIL/BLOCK 状态和截图，每个批次生成一份 tester-kit .xlsx 报告。
• 触发条件（何时使用）： 用户提供一个测试用例 .xlsx 文件（SIT/UAT/回归），并希望“运行看看”“拆分成小批次”“导出报告”。
• 非目标： 不用于编写新测试用例（应使用 /uat-nonit-testcase），也不用于代码单元测试。

思维模型

xlsx → tcs.json（extract）→ 标签 ui|calc|perf|security|gap（classify）→ 按批次制定 PLAN → orca-graph（t1 HITL 登录 → 并行执行各批次 → report）→ results/<lô>.json + shots/<id>.png → report-<lô>.xlsx → summary.md。

输入和输出约定

	字段	必需？	含义
输入	测试用例 .xlsx 文件	是	多个工作表，包含 Test Case ID/Description/Steps/Expected/Priority/Type 列
输入	应用 URL + 登录会话	是	用户在 claude-in-chrome 标签页中自行登录（HITL）
输入	calc 输入数据	否	用户准备的 persona/工资周期；缺少时不运行 calc TC
输出	tcs.json + 按工作表分类的表格	是	ui/calc/perf/security/gap 数量
输出	PLAN.md + graph	是	每批 ≤ 8 个 TC，graph ≤ 20 个节点
输出	results/<lô>.json + shots/<id>.png	是	每个 TC 的 PASS/FAIL/BLOCK + 实际结果 + 证据
输出	report-<lô>.xlsx + summary.md	是	每批一份 tester-kit 报告；按批次汇总

规则和能力

• RULE-01（MUST）：每个 TC 的结果必须包含真实截图 + 可观察到的实际结果；没有截图就不能判为 PASS。
• RULE-02（MUST）：只有用户准备了输入数据（persona/工资周期）时才运行 calc；不得自行编造数字。
• RULE-03（MUST）：在 summary 中明确注明 security 和 perf“超出自动化范围”，不得悄悄跳过。
• RULE-04（MUST）：每批 ≤ 8 个 TC，避免截图和上下文过多；graph ≤ 20 个节点（orca-graph 的限制）→ 超过约 150 个 ui TC 的文件应拆分为多个 PLAN（父 graph → 子 graph）。
• RULE-05（MUST）：报告必须符合 tester-kit schema：priority 为 High/Medium/Low（P0、P1 → High，P2 → Medium，P3 → Low），description 包含 STEPS/EXPECTED/ACTUAL/STATUS。
• 能力：读取 xlsx 并进行确定性分类；控制用户已登录会话中的浏览器；在本地写入结果文件/截图；调用报告导出服务。

失败边界

• 遇到登录/SSO 页面 → blocked，等待用户在当前标签页登录；不得输入密码，也不得代替用户点击 SSO。
• 需要对真实数据执行保存/删除/更新的步骤 → 该 TC 标为 BLOCK，原因是“需要独立的 SIT 环境”，除非用户明确授权。
• calc TC 缺少输入数据、gap 的 steps 为空 → 不运行，并在 summary 中列出（partial）。
• 无法截图 → TC 不能判为 PASS。

HOW

主要工作流

步骤	类型	输入	操作	输出/退出	失败/后续
W01	deterministic	file .xlsx	提取 + 分类（tc-xlsx.py extract 然后 classify），按工作表报告表格	tcs.json + 表格	启发式分类错误 → 修改 auto 标签，并明确说明修改了哪些 TC
W02	deterministic	tcs.json	按批次生成 PLAN，然后构建 graph（orca-graph.py build --strict）	PLAN + graph	构建出错 → 修改 PLAN 后重试
W03	effect	URL app	HITL 登录会话，写入 app.json → set t1 done_user_reported	已登录	看到登录/SSO → 停止并请用户操作
W04	effect	批次	逐批运行：lock → dispatched → 执行 → set done，截图并对照 Expected	results/<lô>.json	写入真实数据 → 将该 TC 标记为 BLOCK
W05	effect	results	使用 tao_report_test 为每批生成报告 + summary.md	report-<lô>.xlsx，summary	—
W06	deterministic	graph	在 cockpit 上跟踪进度，audit 模型回答	进度	—

各步骤详情（W01–W06 的真实依据）：

1. 提取 + 分类（0 token）：

   python3 harness/scripts/tc-xlsx.py extract <file.xlsx> -o scratchpad/<tên>/tcs.json
   python3 harness/scripts/tc-xlsx.py classify scratchpad/<tên>/tcs.json
   

   按工作表向用户报告表格：ui（可通过浏览器运行）、calc（需要输入数据并检查数值）、perf、security（SSO/登录，无法安全地自动化）、gap（步骤为空/等待业务信息）的数量。若启发式分类错误，修改 tcs.json 中的 auto 标签，并明确说明修改了哪些 TC。
2. 按批次生成 PLAN，然后构建 graph：

   python3 harness/scripts/tc-xlsx.py plan tcs.json --app "<tên app (URL)>" --batch 8 --only ui -o llmwiki/wiki/sources/draft/DDMMYY-<tên>-PLAN.md
   python3 harness/scripts/orca-graph.py build <PLAN> --strict && orca-graph.py ask <id> parallel
   

   Task 1 始终为 hitl（调查 app + 登录会话）；各批次并行；最后一个 task 导出报告。每批是一个 verify = results 文件包含足够数量 TC 的 node。
3. **登录会话 — HITL，不得越界：**在 claude-in-chrome 的标签页中打开 URL；看到登录/SSO 页面 → 停止，并请用户在该标签页中亲自点击登录。不要输入密码，也不要代替用户点击 SSO 按钮。登录完成后 → 写入 app.json（logged_in: true，实际菜单）→ set t1 done_user_reported。
4. 逐批运行（lock → dispatched → 执行 → set done）：每个 TC 按 Test Steps 使用 find/computer/read_page 执行，截图至 shots/<id>.png，对照 Expected → PASS|FAIL|BLOCK + actual + evidence。在对真实数据执行任何保存/删除/更新操作前停止 → 标记为 BLOCK「需要独立的 SIT 环境」，除非用户明确允许。写入 results/<lô>.json。
5. 为每批生成报告：tc-xlsx.py report results/<lô>.json --tcs tcs.json --url <URL> → payload → 调用 MCP tao_report_test → 将 xlsx 复制到 report-<lô>.xlsx。最后生成 summary.md：按批次统计 PASS/FAIL/BLOCK、需要人工处理的 TC，以及剩余的 calc/perf/security TC。
6. 在 cockpit（control-room.html）上跟踪进度；像 orca-graph 一样 audit 模型回答。

分支

ID	类型	条件	行为	跳过/失败	汇合
B01	recovery	启发式分类错误地分配标签	修改 tcs.json 中的 auto 标签，并明确说明修改了哪些 TC	—	W02
B02	conditional_required	文件包含 > ~150 个 ui TC（超过 20 个 node）	拆分为多个 PLAN（父 graph → 子 graph）	—	W03
B03	user_optional	用户明确允许写入真实数据	执行包括保存/删除/更新在内的步骤	未获允许 → BLOCK「需要独立的 SIT 环境」	W04
B04	conditional_required	存在 calc TC 且用户已准备好 persona/工资周期	运行 calc TC 并检查数值	缺少数据 → 不运行，并在 summary 中记录	W05

验证和停止条件

每批是一个 verify = results 文件包含足够数量 TC 的 node；只有存在真实截图 + actual 时才可标记为 PASS。所有批次 node 均完成且每批都有报告时停止；将剩余 TC（calc/perf/security/gap、BLOCK）列入 summary.md。

示例

• **正向：**SIT Payroll 文件包含 335 个 TC、7 个工作表 → 分类得到 ui 部分 → plan --batch 8 --only ui → 用户在标签页中登录 SSO → 每批 8 个 TC 均有 shots/<id>.png + results/<lô>.json → report-<lô>.xlsx + summary.md 按批次统计 PASS/FAIL/BLOCK。
• **边界/失败：**TC 要求在真实数据的工资表上点击「保存」，但用户尚未允许 → 将该 TC 标记为 BLOCK「需要独立的 SIT 环境」，不点击；TC 未能截图 → 不得标记为 PASS。

回顾

/tc-run = xlsx → tc-xlsx.py extract/classify → 分批制定 PLAN → orca-graph → 在已登录的会话中运行 → results JSON + 图片 → 每批运行 tao_report_test → 汇总。 意外的用例：在团队的测试用例文件上运行 classify，就能立即看出有多少百分比属于缺口／等待业务方确认，然后再有人承诺完成日期。