cawcut CawPlan TestCase Import — A1 用例导入 TestRail
cawplan skill check
硬门禁（MUST）
- preview-first → 框 4 执行闸 →
execute --confirm；禁止跳闸。 - 数据源：已有展开用例 →
INLINE；仅测试点 →REQUIREMENT。禁止source.type=VERSION。 - Suite / Section 确认闸：
mappings get后 框 3（Suite）→ 框 3.5（Section 归属）（顺序固定）须用户确认后才可 preview / convert。禁止静默使用default_suite_id（不做推荐标注）或静默复用/推断parent_section_id。SUITE_NOT_IN_PROJECT/SECTION_NOT_IN_SUITE/SECTION_NOT_FOUND→ 停止。同会话已确认且未换 Suite/Section → 可复用（import-rules §ConfirmState）。框 3.5 每次导入都问，仅 Intent 显式命中或 ConfirmState 复用时免弹。Version 全程无感：不弹窗、不推断确认，仅 Intent 显式命中或用例自带值才写入，否则不传（结果里注明"未指定版本"）。 - 用户展示：
ux.md §Glossary；preview_id/job_id/UUID 默认隐藏；跟随用户主语言；Agent 自行AskUserQuestion（不写入allowed-tools）。 - TestRail 超链接：
§Preview/§Result/§AsyncHandoff中 Suite ID、Section ID、Case ID 必须可点击跳转（ux §TestRailLinks）；禁止仅裸数字 ID。 - 热接力：P1/P1b → 自动
INLINE，跳过框 0、框 1（ux.md §Trigger）；不跳过框 3、框 3.5（除非ux §Intent显式命中 Suite/Section，或§ConfirmState复用）；Version 无感，不涉及跳过判断。 - INLINE body 组装：数据来自同会话
cawplan-testcase-generate时，禁止手写 camelCase→snake_case 转换脚本或逐条手算source_case_key/priority——须先落一份与 A3csv-template-mapping.md同构的 interim JSON（camelCase，照抄字段，不做映射），框 3/3.5 确认后再用scripts/convert_generate_to_import.js转换为 body（import-rules.md §Convert）。convert因个别用例steps/expected不合规失败时，Agent 可读取<out>.errors.json、征得用户同意后从 interim JSON 摘除对应整条用例重跑（只删条目，不改内容值），不属于此处禁止的"手算字段"。 - 异步 Job（
to_create > 50）：execute成功后 禁止默认jobs poll；须先走ux §AsyncHandoff+ 框 6。仅用户显式选「等到完成」才进入框 6b 等待循环。JobRUNNING时 禁止 重复execute。 - 失败后重试前必核实副作用：
execute（同步或异步）判定失败后（已知错误码或未知错误码），禁止直接复用旧preview_id或立即新开 preview 重新execute——失败可能只是批次级判定，execute内部可能已产生真实副作用（如 Section 已建到 TestRail）。须先按import-rules §RetrySafety核实，再决定下一步。
Reference 加载（MUST）
| 时机 | Read | 禁止 |
|---|---|---|
| 交互 / 路由 / Preview / 报告 / 错误 / 异步 | ux.md 对应 § |
一次性 Read 全部 references |
| body 字段 / 转换 / CLI / BE 缺口 / 异步 / 确认态 | import-rules.md 对应 § |
— |
禁止：直连 TestRail API、持有 TestRail Key、跳过 preview。
允许命令
| 用途 | 命令 |
|---|---|
| 映射 | qa-insights testrail mappings get <product_id> |
| Section 查找（框 3.5 按名称查找时用） | qa-insights testrail sections list <product_id> <suite_id> [--refresh] |
| 新建 Suite（框 3「新增」分支用） | qa-insights testrail suite-create <product_id> --name <name> |
| 刷新 Requirement | api GET .../qa/requirements/<id>、.../testpoints（仅 REQUIREMENT 源） |
| INLINE 转换（同会话 A3 用例） | node scripts/convert_generate_to_import.js <interim_json> --suite-id <n> [--version-name "x.x.x"] [-o <out.json>] |
| 预览 | qa-insights testrail import preview <product_id> |
| 执行 | qa-insights testrail import execute <product_id> --preview-id <id> --confirm |
| 异步 | jobs get（默认，查 progress）· jobs poll（仅用户明确要求等到完成且接受长时间阻塞） |
Workflow
| Step | 动作 | Detail |
|---|---|---|
| 0 | 解析 product_id、数据源、source.type |
ux §Trigger · ux §Intent · import-rules §数据源 |
| 0.5 | 缺上下文 → 框 0/1 | ux §Prompts |
| 1 | mappings get；记录 suites[]、default_suite_id、testrail_origin |
import-rules §Suite · ux §TestRailLinks |
| 1.5 | 框 3 Suite → 框 3.5 Section 归属（如选「已有」，sections list 匹配）（顺序固定；可复用 §ConfirmState） |
ux §SuiteConfirm · ux §SectionConfirm · 先于 convert/preview |
| 2 | 组装 body（INLINE + A3 → interim JSON → convert 用已确认 suite_id/parent_section_id，version_name 若命中 Intent 或用例自带则一并带上） |
import-rules §body · §Convert · §Section · §Version |
| 3 | import preview；ux §Preview 表头含 Suite+版本；存 preview_id |
to_fail>0 → 框 5，停止 |
| 4 | 框 4 执行闸（重复 Suite+版本） | ux §Prompts · to_create>50 → ux §AsyncEstimate |
| 5 | import execute --confirm |
同步 → Step 7；job_id → Step 6a |
| 6a | 异步交付（默认） | ux §AsyncHandoff · 框 6 · import-rules §AsyncJob |
| 6b | 等到完成（可选） | jobs get 循环 · ux §AsyncProgress · ux §AsyncTimeout |
| 7 | 导入报告 | ux §Result |
T1 衔接：同会话 cawplan-testcase-generate → 本 Skill（INLINE）。落 interim JSON → 框 3/3.5 确认 → convert_generate_to_import.js → preview。Requirement 直导仅无 case 明细时。
换 Suite / 换 Section 归属：用户说换 Suite/Section → 清除对应 §ConfirmState → 重走框 3（连带清 Section）或框 3.5 → 须新 preview。换版本：用户提到新版本 → 直接更新 confirmed_version_name（无需弹窗）→ 须新 preview。
异步续接：同会话「查导入状态」→ jobs get（ux §Intent）；须已存 job_id + product_id。
错误（Agent）
| code | 处理 |
|---|---|
TESTRAIL_UNAVAILABLE |
ux §Errors；勿重复 execute |
PREVIEW_EXPIRED |
重新 preview（Suite/版本仍有效则复用 §ConfirmState） |
SUITE_NOT_IN_PROJECT |
ux §Errors；停止 |
SECTION_NOT_IN_SUITE / SECTION_NOT_FOUND |
ux §Errors；重走框 3.5 |
SUITE_CREATE_RATE_LIMITED / SUITE_MODE_NOT_SUPPORTED |
ux §Errors；改走框 3「已有」分支 |
validation / 缺 source.type |
自行修复；不向用户暴露 |
auth/403 |
ux §Errors |
UNKNOWN（Job 超时） |
jobs get 对账 · ux §AsyncTimeout |
CONFIRMATION_REQUIRED |
补 --confirm |
Job RUNNING（6a 后查状态） |
jobs get → ux §AsyncProgress；勿重复 execute |
execute 返回 failed === to_create 且 failed_cases[].error 单一 |
import-rules §Diagnosis；大概率系统性问题而非本批数据问题；先走 §RetrySafety，不引导"改数据重试" |
| 不在本表中的未知 code | ux §UnknownError；停止，不擅自重试；整理 product_id/preview_id/job_id/错误码/failed_cases 样例供用户判断是否上报 |
References
- ux.md — 友好名、路由、Suite/Section 确认、版本无感规则、Preview、异步、报告、错误、未知错误兜底
- import-rules.md — 数据源、Suite/Section/Version、ConfirmState、body、Convert、CLI、异步 Job、失败信号识别、重试前副作用核实、BE 缺口