🛠️ 面向 CDT 团队的测试用例全链路自动化上传 Skill

📋 概述

本 Skill 专为 CDT 团队打造，旨在完全替代原有 Web 上传工具。通过对接 Jira Xray 内部接口，实现测试用例从解析/生成、校验、去重到上传的全链路自动化，提供更安全、高效、智能的用例管理体验。

🚀 两种工作模式总览

模式	名称	输入源	核心处理机制	输出与上传形式
模式 A	XMind 解析上传	固定节点结构的 XMind 文件	按路径规则逆向提取，生成 UTF-8 BOM 标准格式	批量 CSV 导入至 Jira Xray
模式 B	AI 需求生成上传	自然语言需求描述	AI 自动生成（正常/边界/异常场景），Markdown 表格交互确认	明确确认后批量上传至 Xray

🔀 详细工作流图解

模式 A：XMind 解析上传流程

模式 B：AI 需求生成上传流程

🧠 核心技术能力矩阵

本 Skill 具备六大核心技术能力，确保上传过程的确定性、安全性与健壮性：

⚙️ 全链路时序与安全防护机制

下图展示了从触发到最终上传完成的安全防护与异步处理时序：

💬 触发关键词

用户可通过以下自然语言或指令唤醒该 Skill 的相关功能：

中文指令：上传测试用例、导入 Jira、解析 XMind、生成测试用例
英文指令：test case upload、import 提示：直接描述需求（如 “帮我根据这段需求生成测试用例并导入 Jira”）亦可自动触发模式 B 工作流。

量化价值和 SKILL 排行榜

测试用例自动上传 Skill —— 版本变更说明

这份文档面向部门内部用户，告诉你最新版的 skill 跟以前比多了 / 改了什么。每次版本更新都会更新这个文档。

📦 当前版本：v1.4.0
📅 更新日期：2026-07-15
👤 维护人：zhangsan

一句话总结

v1.4.0 的核心目标：Token 全自动抓取，零点击——不用再手动 F12 复制 X-Acpt。对 Kiro 说"帮我自动抓一下 Token"，它会自动拉起/复用你已登录的 Edge、自动开调试开关、自动点确认框，从当前会话把 Token 抓出来、校验、存好，并回显有效期。不新开浏览器、不触发二次短信验证。

v1.3.0 的核心目标：XMind 结构自动检测，新人不用记"该说什么"——发指令直接传文件即可，Kiro 看一眼路径自己判断该用什么布局，仅在机器分不清时让用户一句话确认。

v1.1.0 的核心目标：让用户少打字、错了能救、省心。从老平台和初版 skill 的"严格按流程一步一步走"，升级为"一句话发完走人，AI 主动复述、回显、放行"。

具体表现：

同事场景：原来要每次手动指定项目 / 邮箱 / XMind 结构 → 现在一次保存 profile，之后一句话搞定
新人场景：原来不知道"该说什么"才能让 AI 听懂 → 现在首条响应给齐三种输入方式 + 默认值 + 快捷选项
错传场景：原来一旦传错只能找 admin → 现在文档清楚告诉每种错的救法

全量功能清单（看这一张表就够）

🆕 = 本版新增 / 🔧 = 本版优化 / ✓ = 既有功能保留

模式 A：XMind 解析上传

能力	状态	说明
解析 XMind 文件并上传 Jira	✓	沿用原 `converter.py` 解析规则
标准 4 段结构（含 Description 层）	✓	layout=`standard`（默认）
紧凑 3 段结构（无 Description 层）	✓	layout=`compact`，匹配同事自定义画法
结构自动检测（`detect_layout`）	🆕 v1.3.0	解析前先调一次，按硬性边界条件 + 路径样例判定
4 段路径零确认直传	🆕 v1.3.0	路径恰好 4 段时机器可独立判定为 compact
5+ 段路径"AI 推荐 + 用户确认"	🆕 v1.3.0	取代老版"用户口头声明结构"——展示样例供肉眼核对
段数不一致主动报错	🆕 v1.3.0	提前在 A0 阶段拦截，不再盲解析后才报"未找到用例"
结构声明安全闸（防字段错位）	✓ v1.1.0	v1.3.0 改为机器先判，仅在 needs_confirmation 时让用户介入
解析摘要 + 上传结果合并为单条消息	✓ v1.1.0	减少一轮往返；模式 A 全自动跑完不再问"是否继续"

模式 B：AI 需求生成上传

能力	状态	说明
纯文字需求生成测试用例	✓	老版就有
PDF / Word（.docx）/ Markdown / 截图等附件作为需求来源	🆕	Kiro 原生读取附件能力，新版本明确文档化支持范围
多附件组合（如 PDF 需求 + 原型图截图）	🆕	同上
AI 复述识别要点环节	🆕	收到附件后 AI 必须先复述读到的内容供用户确认，防误读
生成正常 / 边界 / 异常用例	✓	三类场景覆盖策略
用户增删改用例	✓	修改后重新展示，循环到确认
强制确认才上传	✓	安全闸，未明确确认禁止上传

参数收集与交互

能力	状态	说明
一次性输入所有参数（一句话指定项目 + 邮箱 + 文件 + 结构）	🆕	旧版必须分步问
回显即走，不阻塞确认	🆕	收到参数后回显一次随即继续，不再发"是否正确？"
首条响应聚合发出（项目列表 + 邮箱要求 + XMind 结构一次给齐）	🆕	减少新人无效往返
三种项目输入方式（序号 / Key / 名称关键词，任选其一）	🆕	老版只接受 Key
`resolve_project()` 确定性查表	🆕	杜绝 AI 心算映射"序号 2 → ?Key" 错误
默认配置（QR247 + zhangsan@testerhome.com）	✓	显式回复"用默认"才生效

快捷复用（个人定制）

能力	状态	说明
last_run（"用上次"）	🆕	自动记录最近一次成功上传的项目 + 邮箱 + layout，下次一句话复用
具名 profile（"用 <name> 的配置"）	🆕	个人/团队成员各持其名，一次保存长期复用，互不干扰
profile 增删改查命令	🆕	保存 / 列出 / 删除 / 查看详情
CLI 命令行支持	🆕	`python main.py prefs save --name xxx ...` 等

Token 管理

能力	状态	说明
本地 Token 文件存储	✓	`<skill_root>\.jiraToken\jira_token_store.txt`
在线校验接口判定有效性（HTTP 200）	✓	不本地解码 JWT
格式预检 + 兼容 jwt= 参数粘贴	✓	老版已有
连续 3 次失败自动提示重抓	✓	老版已有
Token 失效后清晰话术引导（F12 抓取步骤）	🔧	USER_GUIDE 里写了完整流程
从已登录浏览器自动抓取 X-Acpt（全自动零点击）	🆕 v1.4.0	CDP 连接当前浏览器会话，免手动复制、不二次登录；自动拉起/复用 Edge + 自动勾开关 + 自动点 Allow
抓取→校验→保存一站式 + Token 详情回显	🆕 v1.4.0	`grab_and_store_token()`；回显获取方式/保存时间/有效期/剩余时长/校验结果
CLI：`token grab` / `token info`	🆕 v1.4.0	`python -m scripts.browser_token_grabber --mode auto`；`token info` 查看有效期
依赖 `websocket-client` + `pywinauto`	🆕 v1.4.0	仅本机回环连接；pywinauto 用于自动勾开关/点确认框

上传与结果反馈

能力	状态	说明
调用 Xray 内部导入 API + 轮询 jobId	✓	与原 Web 工具一致
幂等保护（相同内容 + 相同项目自动拦截重复上传）	🆕	老版没有，传两次会创建两批 Issue
`view_url` 用 JQL 精确过滤本批次 Issue	🆕	老平台跳转后是整个项目，找不到这次传的；新版只显示这次的
请求超时不重试（防止重复导入）	🆕	老版会盲重试
轮询期 Token 失效立即终止（不空等 60 秒）	🆕	同时提示用户先到 Jira 核对再决定是否重传
明确反馈 JOB 终态	🔧	successful / unsuccessful / failed / duplicate_upload / timeout 各有处理话术
REST API URL 不暴露给用户	🆕	反馈中只用可点击的 markdown 链接，不展示 `/rest/api/2/issue/...`

错误处理与文档

能力	状态	说明
结构化异常表（按 `error/status` 字段对号入座）	🆕	老版散落各处，AI 凭直觉处理
USER_GUIDE.md 用户指南（含 PDF）	🆕	部门内部分享文档
CHANGELOG.md 变更说明	🆕	即本文档
17 条 MUST 强制约束	🔧	从 27 条精简到 17 条，按流程/调用/交互/安全分块
"输错了怎么办"专题章节	🆕	5.6 节，5 种典型场景的救法
"上传错了会怎么样"专题章节	🆕	7 节，三道防线 + 四种救法 + 不能做的事

跟原 Web 工具相比

项	原 Web 工具	v1.3.0
触发方式	打开网页填表	Kiro 里一句话
模式 A：XMind 上传	✅	✅ + 支持紧凑 3 段结构
模式 B：需求生成	❌	✅ + 支持 PDF/Word/截图
项目选择	下拉框（必须用 Key）	序号/Key/名称三选一，确定性查表
跳转链接	看到整个项目（找不到本批次）	用 JQL 只显示本批次 Issue
幂等保护	❌（重复点会创建两批）	✅ 内容指纹去重
Token 管理	手动每次填	本地存储 + 自动校验 + 失效提示
个人配置记忆	❌	✅ last_run + 具名 profile
错误信息	"Upload failed"	按字段定位到行号 + 中文原因
命令行支持	❌	✅ `python main.py xmind/generate/token/prefs ...`

跟同事自制脚本（如 `upload_xmind.py`）相比

项	自制脚本	v1.3.0
Token 校验	通常没有，跑了才发现失效	启动就检查，失效立即提示
幂等保护	❌	✅
多种 XMind 结构	只支持自己的	standard + compact 两种内置
跨人共享	改邮箱要改代码	各自保存 profile
错误重试逻辑	通常会无脑重试 → 重复创建 Issue	超时不重试 + Token 失效不空等
维护成本	每个人维护自己的	团队共用一份

💡 强烈建议：如果你之前在用自己的脚本，可以把项目 + 邮箱 + 你的 XMind 画法保存成一个 profile，然后把脚本扔了。新版能做到的事更多、更稳。

老用户迁移 / 新人上手 1 分钟速通

老用户（之前用过 web 工具或自制脚本）

1. 把整个 testcase-jira-importer-skill 文件夹拷到你的工作区 .kiro/skills/
2. python -m scripts.main setup（一次性：配镜像→装依赖→校验，顺序固定）
3. 第一次抓 Token（看 USER_GUIDE 5.1 节，推荐用自动抓取，全自动零点击）
4. 在 Kiro 里发：上传 D:\xxx.xmind 到 <你的项目> 负责人 <你的邮箱> 结构按标准画的
5. 成功后说：保存为 <你的英文名>
6. 以后每次：上传 D:\xxx.xmind 用 <你的英文名> 的配置

新人（从来没用过）

1. 先看 USER_GUIDE.md 第 1 节准备环境
2. 第 2 节看一句话上传示例
3. 第 5 节抓 Token
4. 试一次。错了看第 6 节常见错误

已知限制（v1.3.0 还没做的）

❌ 批量目录上传：暂不支持一次传一整个文件夹的 XMind，需要连续发多条指令
❌ 在线工具直连（Figma / Confluence / 飞书链接）：需要你先导出为 PDF / 图片再传
❌ Issue 字段后期修改：本 skill 只负责上传，改字段去 Jira 网页或 Bulk Change
❌ 删除接口：Skill 不主动删除已上传的 Issue（防止误删），需要在 Jira 手工操作
❌ 多语言用例生成：Mode B 默认按你的需求语言生成，没有强制中英对照
❌ profile 跨机同步：profile 文件存在本地，换电脑要手动拷贝

这些都在 backlog 里，按需求优先级排期。

反馈渠道

遇到 bug：截图 + Kiro 反馈消息（含 jobId）+ USER_GUIDE 错误代码 → 提给 skill 维护人
想加新功能：直接说需求场景，不用想"该不该提"
想要新项目支持：把项目名 + 项目 Key + 项目 ID 发过来即可加入 PROJECT_LIST

历史版本

v1.4.0 (2026-07-15) — 当前

新增：setup 一体化环境初始化（新同事首次使用必做，顺序固定）

能力	状态	说明
CLI `python -m scripts.main setup`	🆕	固定顺序：① 配置清华镜像（不联网、必定成功）→ ② 用镜像升级 pip → ③ 一次性装齐全部依赖 → ④ 校验能否正常导入。全部通过才提示"可以开始使用"
CLI `python -m scripts.main setup-mirror`	🆕	仅配置清华镜像（不装依赖），供已装好依赖、只是想换源的场景单独使用

面向没走国内镜像、下载依赖经常超时的同事，尤其是新同事首次使用
顺序不可颠倒：若先装依赖再配镜像，装依赖那一步走的还是慢/超时的默认源，等于让解决方案依赖问题本身；setup 已固化正确顺序
全部通过 python -m pip 而非裸 pip，避免多 Python 环境下命令指向错乱
依赖没装齐时，「自动抓取 Token」会直接告知环境未就绪并给出安装建议，不会盲目去操作 Edge 窗口
换回官方源：python -m pip config unset global.index-url

核心改进：Token 自动抓取，告别手动 F12 复制

能力	状态	说明
`browser_token_grabber.py` 新模块	🆕	通过 Chrome DevTools Protocol 连接已登录浏览器抓取 X-Acpt
`grab_and_store_token()` 一站式入口	🆕	抓取 → 复用 `validate_token()` 校验 → `save_token()` 保存
无需新开浏览器 / 不触发二次登录	🆕	直接操作用户当前已登录的窗口，规避短信验证死循环
自动刷新触发	🆕	激活并刷新 Xray 触发页生成带 X-Acpt 的请求
自动拉起/复用 Edge + 自动勾开关	🆕	端口未就绪时自动开 Edge、键盘导航到 `edge://inspect` 并勾选调试开关；已就绪则直接复用
自动点击 "Allow remote debugging?" 确认框	🆕	用 pywinauto(UI Automation) 持续扫描点击，全程零点击
Token 详情回显	🆕	展示获取方式/保存时间/JWT 签发与过期时间/剩余时长/在线校验结果
CLI `token grab` / `token info`	🆕	`python -m scripts.browser_token_grabber --mode auto`；`token info` 查看有效期
SKILL 第一步「Token 无效时」改为优先推荐自动抓取	🔧	手动粘贴降级为兜底方案
新增依赖 `websocket-client` + `pywinauto`	🆕	仅本机回环连接调试端点，不发起外部请求

为什么做这个改动：

手动从 F12 Network 复制 X-Acpt 步骤繁琐，新人容易复制错/复制不全
若用全新浏览器实例重新登录会触发二次手机短信验证，无法走通
新版利用现代 Edge 的"对当前进程开启远程调试"能力：保持已登录窗口不动，脚本自动开调试开关 + 自动点确认框，全程零点击

使用前提：

安装依赖：python -m pip install websocket-client pywinauto
Edge 使用平时登录 Jira 的默认用户配置
正常情况下用户无需任何点击；脚本会自动开/复用 Edge、勾开关、点 Allow

关键实现要点（踩过的坑）：

就绪检测必须用 TCP 连接测试，不能用 /json/version HTTP 端点——edge://inspect 开关模式出于安全不暴露该端点（只暴露 /devtools/browser/<uuid> WebSocket），否则会误判"永远未就绪"
edge://inspect/#remote-debugging 带 # 锚点用命令行参数打开不可靠，改用"开空白窗口 + 键盘 Ctrl+L 输网址回车"导航
Allow 确认框是渲染在浏览器主窗口内的 Pane（非独立顶层窗口），需在主窗口子树用 descendants(control_type='Button') 递归查找；且要持续点击（每次连接都会弹、有竞态）

已知限制：

仅 Windows + Chromium 内核 Edge（依赖 pywinauto 的 UI Automation）
未装 pywinauto 时降级为"手动开开关 + 手动点 Allow"
App-Bound Encryption（Edge 127+）导致"后台复制登录态起新实例"不可行，故只能操作当前真实登录的 Edge（mode='launch' 保留为实验实现，ABE 环境会失败）
只取请求头 X-Acpt（qsh=context-qsh）；不采用 iframe URL 里的 jwt=（单次 qsh，校验会失败）
Token 有效期实测约 15 分钟（JWT exp-iat=900 秒）

v1.3.0 (2026-06-03)

核心改进：XMind 结构自动检测，告别每次都要"声明结构"

能力	状态	说明
`detect_layout()` 自动检测叶子路径	🆕	解析前先调一次，按硬性边界条件判定可信度
`format_detect_result()` 友好展示	🆕	把检测结果拼成对话友好文本（含路径样例）
4 段路径零确认	🆕	路径恰好 4 段时机器可以独立判定为 compact，无需用户介入
5+ 段路径"AI 推荐 + 用户一句话确认"	🆕	取代老版的"用户口头声明结构"——展示路径样例供肉眼核对
段数不一致时主动报错	🆕	不再盲解析后才报"未找到用例"，提前在 A0 阶段拦截
强制约束第 8 条同步更新	🔧	"解析前必须调 detect_layout"+ 4 种分支处理规则
USER_GUIDE 6.3.1 / 6.3.2 新增故障场景	🆕	needs_confirmation / 段数不一致两种新现象的处理说明