tc-run

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: tc-run — từ file test case đầy đủ đến report từng lô

Skill: tc-run — 从完整 test case 文件到分批 report

Bóc từ phiên Payroll SIT 15/09/2026 (335 TC, 7 sheet). Tool tất định:

harness/scripts/tc-xlsx.py

(extract · classify · plan · report). Runtime chạy lô:

/orca-graph

. Trình duyệt: claude-in-chrome trên phiên user đã đăng nhập (SSO). Report: MCP

tester-kit

→

tao_report_test

从 Payroll SIT 15/09/2026 会话中提取（335 个 TC、7 个 sheet）。确定性工具：

harness/scripts/tc-xlsx.py

（extract · classify · plan · report）。批次执行 Runtime：

/orca-graph

。浏览器：claude-in-chrome，使用用户已登录的会话（SSO）。Report：MCP

tester-kit

→

tao_report_test

。

WHAT

内容（WHAT）

Purpose và context

目的与上下文

Purpose: biến MỘT file test case .xlsx đầy đủ thành kết quả PASS/FAIL/BLOCK có ảnh từng TC và mỗi lô một report .xlsx tester-kit.
Trigger (when to use): User đưa một file test case .xlsx (SIT/UAT/regression) và muốn "chạy xem", "break nhỏ", "xuất report".
Non-goals: KHÔNG dùng để viết test case mới (đó là
```
/uat-nonit-testcase
```
), không dùng cho unit test code.

**目的：**将一个完整的 test case .xlsx 文件转换为带每个 TC 截图的 PASS/FAIL/BLOCK 结果，并为每个批次生成一份 .xlsx tester-kit report。
**触发条件（何时使用）：**用户提供一个 test case .xlsx 文件（SIT/UAT/regression），并希望“运行查看”、“拆分成小批次”、“导出 report”。
**非目标：**不用于编写新的 test case（那是
```
/uat-nonit-testcase
```
），也不用于代码的 unit test。

Mental model

思维模型

xlsx → tcs.json (extract) → nhãn ui|calc|perf|security|gap (classify) → PLAN theo lô → orca-graph (t1 hitl đăng nhập → các lô song song → report) → results/<lô>.json + shots/<id>.png → report-<lô>.xlsx → summary.md

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

。

Input và output contract

输入与输出约定

	Field	Required?	Ý nghĩa
In	file test case .xlsx	có	nhiều sheet, cột Test Case ID/Description/Steps/Expected/Priority/Type
In	URL app + phiên đăng nhập	có	user tự đăng nhập trong tab claude-in-chrome (HITL)
In	dữ liệu đầu vào calc	không	persona/kỳ lương do user chuẩn bị; thiếu thì TC `calc` không chạy
Out	`tcs.json` + bảng phân loại theo sheet	có	số `ui` / `calc` / `perf` / `security` / `gap`
Out	PLAN.md + graph	có	lô ≤ 8 TC, graph ≤ 20 node
Out	`results/<lô>.json` + `shots/<id>.png`	có	PASS/FAIL/BLOCK + actual + evidence từng TC
Out	`report-<lô>.xlsx` + `summary.md`	có	report tester-kit mỗi lô; tổng hợp theo lô

	字段	必填？	含义
输入	test case .xlsx 文件	是	多个 sheet，列包括 Test Case ID/Description/Steps/Expected/Priority/Type
输入	app URL + 已登录会话	是	用户自行在 claude-in-chrome tab 中登录（HITL）
输入	calc 输入数据	否	用户准备的 persona/发薪周期；缺失时不运行 `calc` TC
输出	`tcs.json` + 按 sheet 分类的表格	是	`ui` / `calc` / `perf` / `security` / `gap` 的数量
输出	PLAN.md + graph	是	每批 ≤ 8 个 TC，graph ≤ 20 node
输出	`results/<lô>.json` + `shots/<id>.png`	是	PASS/FAIL/BLOCK + 每个 TC 的 actual + evidence
输出	`report-<lô>.xlsx` + `summary.md`	是	每批一份 tester-kit report；按批次汇总

Rules và capabilities

规则与能力

RULE-01 (MUST): Kết quả từng TC phải có ảnh thật + actual quan sát được; không có ảnh thì không được PASS.
RULE-02 (MUST):
```
calc
```
chỉ chạy khi có dữ liệu đầu vào (persona/kỳ lương) do user chuẩn bị; không tự bịa số.
RULE-03 (MUST):
```
security
```
và
```
perf
```
ghi rõ "ngoài phạm vi tự động" trong summary, không lặng lẽ bỏ.
RULE-04 (MUST): Lô ≤ 8 TC để ảnh và context không phình; graph ≤ 20 node (giới hạn orca-graph) → file > ~150 TC ui thì chia nhiều PLAN (graph mẹ → con).
RULE-05 (MUST): Report đúng schema tester-kit:
```
priority
```
High/Medium/Low (P0,P1→High, P2→Medium, P3→Low),
```
description
```
gồm STEPS/EXPECTED/ACTUAL/STATUS.
Capabilities: đọc xlsx + phân loại tất định; điều khiển trình duyệt trên phiên user đã đăng nhập; ghi file kết quả/ảnh cục bộ; gọi dịch vụ xuất report.

RULE-01 (MUST)：每个 TC 的结果必须包含真实截图 + 可观察到的 actual；没有截图不得判定为 PASS。
RULE-02 (MUST)：只有在用户准备好输入数据（persona/发薪周期）时才运行
```
calc
```
；不得自行编造数字。
RULE-03 (MUST)：在 summary 中明确注明
```
security
```
和
```
perf
```
“超出自动化范围”，不得静默忽略。
RULE-04 (MUST)：每批 ≤ 8 个 TC，避免截图和 context 膨胀；graph ≤ 20 node（orca-graph 限制）→ 超过约 150 个 UI TC 的文件需拆分为多个 PLAN（父 graph → 子 graph）。
RULE-05 (MUST)：Report 必须符合 tester-kit schema：
```
priority
```
为 High/Medium/Low（P0,P1→High，P2→Medium，P3→Low），
```
description
```
包含 STEPS/EXPECTED/ACTUAL/STATUS。
能力：读取 xlsx + 确定性分类；在用户已登录的会话中控制浏览器；写入本地结果文件/截图；调用 report 导出服务。

Failure boundaries

失败边界

Gặp trang login/SSO → blocked chờ user đăng nhập trong chính tab; không nhập mật khẩu, không bấm SSO thay user.
Bước cần Lưu/Xoá/Cập nhật trên dữ liệu thật → TC đó BLOCK "cần môi trường SIT riêng", trừ khi user cho phép rõ.
TC
```
calc
```
thiếu dữ liệu đầu vào,
```
gap
```
steps rỗng → không chạy, liệt kê trong summary (partial).
Không chụp được ảnh → TC không được PASS.

遇到 login/SSO 页面 → blocked，等待用户在同一 tab 中登录；不得输入密码，也不得代替用户点击 SSO。
某一步需要在真实数据上执行“保存/删除/更新” → 该 TC 标记为 BLOCK“需要独立的 SIT 环境”，除非用户明确允许。
```
calc
```
TC 缺少输入数据、
```
gap
```
TC 的 steps 为空 → 不运行，并在 summary 中列出（partial）。
无法截图 → TC 不得判定为 PASS。

HOW

方法（HOW）

Main workflow

主要流程

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	deterministic	file .xlsx	Bóc + phân loại ( `tc-xlsx.py extract` rồi `classify` ), báo bảng theo sheet	`tcs.json` + bảng	heuristic sai → sửa nhãn `auto` , nói rõ TC nào
W02	deterministic	`tcs.json`	Sinh PLAN theo lô rồi dựng graph ( `orca-graph.py build --strict` )	PLAN + graph	build lỗi → sửa PLAN rồi lặp
W03	effect	URL app	Phiên đăng nhập HITL, ghi `app.json` → `set t1 done_user_reported`	đã login	thấy login/SSO → dừng nhờ user
W04	effect	lô	Chạy từng lô: lock → dispatched → làm → set done, chụp ảnh, so Expected	`results/<lô>.json`	ghi dữ liệu thật → BLOCK TC đó
W05	effect	results	Report mỗi lô qua `tao_report_test` + `summary.md`	`report-<lô>.xlsx` , summary	—
W06	deterministic	graph	Theo dõi tiến độ trên cockpit, `audit` câu trả lời model	tiến độ	—

Chi tiết từng bước (nguồn chân lý cho W01–W06):

Bóc + phân loại (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
```
Báo user bảng theo sheet: bao nhiêu
```
ui
```
(chạy được bằng trình duyệt),
```
calc
```
(cần dữ liệu đầu vào, kiểm số),
```
perf
```
,
```
security
```
(SSO/đăng nhập, không tự động hoá an toàn),
```
gap
```
(steps rỗng/chờ nghiệp vụ). Heuristic sai thì sửa nhãn
auto
trong tcs.json và nói rõ đã sửa TC nào.

Sinh PLAN theo lô rồi dựng 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 luôn là

hitl

(khảo sát app + phiên đăng nhập); các lô song song; task cuối xuất report. Mỗi lô là một node có

verify

= file results đủ số TC.

Phiên đăng nhập — HITL, không được vượt: mở URL trong tab claude-in-chrome; thấy trang login/SSO → dừng, nhờ user bấm đăng nhập trong chính tab đó. Không nhập mật khẩu, không bấm nút SSO thay user. Đăng nhập xong → ghi
```
app.json
```
(
```
logged_in: true
```
, menu thật) →
```
set t1 done_user_reported
```
.
Chạy từng lô (
```
lock
```
→
```
dispatched
```
→ làm →
```
set done
```
): mỗi TC theo Test Steps bằng
```
find
```
/
```
computer
```
/
```
read_page
```
, chụp ảnh
```
shots/<id>.png
```
, so Expected →
```
PASS|FAIL|BLOCK
```
+
```
actual
```
+
```
evidence
```
. Dừng trước mọi Lưu/Xoá/Cập nhật trên dữ liệu thật → BLOCK "cần môi trường SIT riêng", trừ khi user cho phép rõ. Ghi
```
results/<lô>.json
```
.
Report mỗi lô:
```
tc-xlsx.py report results/<lô>.json --tcs tcs.json --url <URL>
```
→ payload → gọi MCP
```
tao_report_test
```
→ chép xlsx về
```
report-<lô>.xlsx
```
. Cuối cùng
```
summary.md
```
: PASS/FAIL/BLOCK theo lô, TC cần người, TC calc/perf/security còn lại.
Theo dõi tiến độ trên cockpit (
```
control-room.html
```
);
```
audit
```
câu trả lời model như orca-graph.

步骤	类型	输入	操作	输出/退出条件	失败/下一步
W01	deterministic	file .xlsx	提取 + 分类（ `tc-xlsx.py extract` 后执行 `classify` ），并汇报按 sheet 统计的表格	`tcs.json` + 表格	heuristic 有误 → 修正 `auto` 标签，并明确说明涉及哪些 TC
W02	deterministic	`tcs.json`	按批次生成 PLAN，然后构建 graph（ `orca-graph.py build --strict` ）	PLAN + graph	build 失败 → 修正 PLAN 后重试
W03	effect	app URL	HITL 登录会话，写入 `app.json` → `set t1 done_user_reported`	已登录	出现 login/SSO → 停止并请求用户登录
W04	effect	批次	运行每个批次：lock → dispatched → 执行 → set done，截图，对照 Expected	`results/<lô>.json`	写入真实数据 → 该 TC 标记为 BLOCK
W05	effect	results	通过 `tao_report_test` 为每个批次生成 report + `summary.md`	`report-<lô>.xlsx` 、summary	—
W06	deterministic	graph	在 cockpit 上跟踪进度，通过 `audit` 审核模型回答	进度	—

以下各步骤的详细信息是 W01–W06 的事实来源：

提取 + 分类（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

向用户汇报按 sheet 统计的表格：有多少

ui

（可通过浏览器运行）、

calc

（需要输入数据，用于数值校验）、

perf

、

security

（SSO/登录，无法安全自动化）、

gap

（steps 为空/等待业务定义）。heuristic 有误时，在 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 导出 report。每个批次是一个 node，其

verify

= results 文件中包含足够数量的 TC。 3. **登录会话——HITL，不得越权：**在 claude-in-chrome tab 中打开 URL；如果出现 login/SSO 页面 → 停止，请用户在同一个 tab 中点击登录。不得输入密码，也不得代替用户点击 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. 每个批次的 report：

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

审核模型的回答。

Branches

分支

ID	Kind	Guard	Hành vi	Skip / failure	Rejoin
B01	recovery	heuristic classify gán nhãn sai	sửa nhãn `auto` trong tcs.json, nói rõ đã sửa TC nào	—	W02
B02	conditional_required	file > ~150 TC ui (vượt 20 node)	chia nhiều PLAN (graph mẹ → con)	—	W03
B03	user_optional	user cho phép rõ ghi dữ liệu thật	chạy cả bước Lưu/Xoá/Cập nhật	không cho phép → BLOCK "cần môi trường SIT riêng"	W04
B04	conditional_required	có TC `calc` và user đã chuẩn bị persona/kỳ lương	chạy TC calc, kiểm số	thiếu dữ liệu → không chạy, ghi summary	W05

ID	Kind	Guard	行为	跳过/失败	汇合点
B01	recovery	heuristic classify 分配了错误标签	修正 tcs.json 中的 `auto` 标签，并明确说明修改了哪些 TC	—	W02
B02	conditional_required	file > 约 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

Validation và stopping

验证与停止条件

Mỗi lô là một node có

verify

= file results đủ số TC; PASS chỉ khi có ảnh thật + actual. Dừng khi mọi node lô done và mỗi lô có report; TC còn lại (calc/perf/security/gap, BLOCK) liệt kê trong

summary.md

每个批次都是一个 node，其

verify

= results 文件中包含足够数量的 TC；只有在有真实截图 + actual 时才能 PASS。当所有批次 node 都 done 且每个批次都有 report 时停止；剩余 TC（calc/perf/security/gap、BLOCK）列在

summary.md

中。

Examples

示例

Positive: file SIT Payroll 335 TC, 7 sheet → classify ra phần
```
ui
```
→
```
plan --batch 8 --only ui
```
→ user đăng nhập SSO trong tab → mỗi lô 8 TC có
```
shots/<id>.png
```
+
```
results/<lô>.json
```
→
```
report-<lô>.xlsx
```
+
```
summary.md
```
PASS/FAIL/BLOCK theo lô.
Boundary/failure: TC yêu cầu bấm "Lưu" bảng lương trên dữ liệu thật, user chưa cho phép → TC đó BLOCK "cần môi trường SIT riêng", không bấm; TC không chụp được ảnh → không PASS.

**正向：**SIT Payroll 文件包含 335 个 TC、7 个 sheet → 分类得到
```
ui
```
部分 →
```
plan --batch 8 --only ui
```
→ 用户在 tab 中完成 SSO 登录 → 每个包含 8 个 TC 的批次生成
```
shots/<id>.png
```
+
```
results/<lô>.json
```
→ 输出
```
report-<lô>.xlsx
```
+
```
summary.md
```
，并按批次汇总 PASS/FAIL/BLOCK。
**边界/失败：**某个 TC 要求在真实数据上点击“保存”工资表，但用户尚未允许 → 该 TC 标记为 BLOCK“需要独立的 SIT 环境”，不执行点击；TC 无法截图 → 不得判定为 PASS。

Recap

回顾

/tc-run

= xlsx →

tc-xlsx.py extract/classify

→ PLAN theo lô → orca-graph → chạy trên phiên đã login → results JSON + ảnh →

tao_report_test

mỗi lô → summary. Use-case bất ngờ: chạy

classify

trên file test case của team để thấy ngay bao nhiêu % là gap/chờ nghiệp vụ trước khi ai đó hứa ngày xong.

/tc-run

= xlsx →

tc-xlsx.py extract/classify

→ 按批次生成 PLAN → orca-graph → 在已登录的会话中执行 → results JSON + 截图 → 为每批调用

tao_report_test

→ summary。意外用例：运行

classify

处理团队的 test case 文件，立即查看有多少 test case 属于 gap/等待业务定义，从而在有人承诺完成日期之前先掌握实际情况。