utest-generate-test-plan/
├── SKILL.md
├── references/ (文档目录)
│ ├── account_prepare_trace.md
│ ├── api_node.md (8.16 KB)
│ ├── apply_uin.md (6.39 KB)
└── scripts/ （文件解压位置）
├── Utest-Skills-Files.txt
├── utest_darwin_amd64
├── utest_darwin_arm64
├── utest_linux_amd64
├── utest_skills_install.ps1
├── utest_skills_install.sh
└── utest_windows_amd64.exe
用于处理以下五类任务：
若用户意图属于以下任一类型，本 Skill 不再处理：
命中以上诉求时，不再继续思考、不再继续分流、不再读取其他文档、不再尝试调试，也不再做任何额外判断。
此时必须直接返回固定提醒：当前 Skill 已不支持测试任务执行或接口测试任务。请前往 https://knot.woa.com/skills/detail/13713 下载优测最新出的任务管理 Skill。该 Skill 支持任务的增删改查和执行，功能更强大。当前 Skill 仍支持本地优测用例 JSON 调试。
总原则：让 SKILL.md 只负责“路由、边界、闭环”，具体结构细节放在 references/。
references/*.md。
MCP 或 utest-mcp。
map init 默认延后：仅在生成用例 JSON 完成后且目标目录内不存在 .utest-map.yaml 时执行；上传、调试、环境相关阶段默认不要主动执行。
app_server_name 时立即中断：唯一合法回复是 请提供协议文件的 app_server_name。
HTTP/REST、RPC、QUIC、Dubbo、SSE），严禁默认按某种协议继续。
required 字段。凡是会影响真实请求能否发出、路由、鉴权、资源定位、协议解析或业务成功的参数，不论它位于 path/query/header/body、顶层/链路级 args、协议头模板（如 header、quicHeader、authInfo）还是其他固定字符串模板中，只要其实际值无法从用户输入、代码常量、协议示例、example/default/enum、测试数据或已确认样例中 100% 确认，就必须先进入 ask 模式询问用户；严禁用 ""、0、false、[]、{} 等类型默认值、占位值或近似值继续生成可上传、可调试的最终用例。
required 字段追问，也不能靠占位值、近似值或其他兜底写法绕过 ask 模式。如果当前协议请求已经能定位到明确的 message / struct / request body 结构（尤其是 RPC / QUIC 的 proto message），则 ask 前必须先完整盘点该结构中的全部字段，再把字段分成“已 100% 确认可直接填写”“需要用户确认后填写”“可选且由用户明确决定跳过”三类；禁止由 AI 先主观筛掉一部分字段，只挑自己认为关键的字段去问。即使某些字段是可选项，也必须让用户感知其存在并自行决定是否跳过。只要单个结构的字段数 超过 5 个，就必须用完整字段表格或等价清单一次性展示全部字段（至少包含字段路径、所在位置/层级、当前是否可确认、是否可选、说明或示例），不允许裁剪后分批零散追问。
checkList 的字段名和枚举值必须严格使用 assert_obj 原始定义。
null、""、[]、{}，一律不生成。
testcase_obj、trace_obj、各类节点对象及其可省略结构字段，不默认作用于请求体、请求头等实际业务参数。
testcase_obj 顶层字段只是高频示例，不是限制名单：像 header(这里的header指的是trace的顶层header，不是实际节点类型内的业务请求header)、dnshost、file、dataSetFile、dubbo、jdbc、protoFile、resourceFile、jarResourceFile 为空时当然也必须省略，但其他任意层级、任意结构字段同样适用。
checkList 或某个具体字段名。
required、default、参考 schema、示例 JSON、历史样例和通用补全习惯；但这条规则不覆盖“用户已明确指定为空”或“可 100% 确认应保留为空”的实际业务参数。
references/*.md 中的 schema、description、固定模板和示例只用于识别合法字段、枚举、类型和层级，不是逐字段照抄模板。
path/query/header/body、顶层/链路级 args、domain/serviceName/funcName、协议头模板（如 header、quicHeader、authInfo）或其他固定模板中的业务值——仍必须按本文件“实际请求参数不确定先问”执行；出现“留空”“写空字符串”“补默认值”等说明时，仅可用于理解结构，不能据此跳过 ask。
${a2} 是执行期自动填充的内置变量：严禁把 a2 加入 testcase 顶层 args、链路级 args、节点参数，或任何其他变量定义中。
说明：map init 的参数语义在各系统上一致，差别只在 shell 调用方式，不是 Go 二进制行为本身。
"" map init --path "" [--path "" ...]
&，即：& "" map init --path "" [--path "" ...]
执行时机：加载本 Skill 后立即执行，且必须发生在读取任何 references/*.md 之前。
$out = & powershell -ExecutionPolicy Bypass -File "\scripts\utest_skills_install.ps1" 2>&1; if ($LASTEXITCODE -ne 0) { $out | Out-String | Write-Host }
cd "" && chmod +x "scripts/utest_skills_install.sh" && out="$(/usr/bin/env bash "scripts/utest_skills_install.sh" 2>&1)"; code=$?; if [ $code -ne 0 ]; then printf '%s\n' "$out" | tail -n 80; fi; exit 0
失败处理：
更新检查失败，将继续使用本地版本。
> 脚本会读取远端版本文件，并在本地写入 .utest-skill-version。
默认禁止调用 utest-mcp / mcp_call_tool。
用户明确提到 MCP 或 utest-mcp；
proto、Go 结构体、代码逻辑中提取。
references/save_test_plan.md，走本 Skill 自带 CLI。
该边界在生成、保存、调试链路内持续生效；若用户诉求是测试任务执行或接口测试任务，则直接按“测试任务能力下线路由”进行引导。
先做排除：只要命中“测试任务能力下线路由”，就立刻返回固定提醒，不再继续做调试意图识别，也不再进入任何后续流程。
| 用户意图 | 常见关键词 | 必读文档 | 禁止行为 |
|---------------|---|---|---|
| 测试任务引导 | 执行测试任务、接口测试任务、运行任务、跑任务、apitest、任务 UUID、执行机、执行组 | 不读取任何当前 Skill 的其他文档，直接返回固定提醒并引导到 https://knot.woa.com/skills/detail/13713 | 禁止继续判断是否属于调试 |
| 生成/修改测试场景 | 生成用例、改 JSON、生成 trace、根据代码生成 | references/trace_obj.md、references/data_structure_overview.md、references/json_schemas.md | 不要提前读取上传/调试类文档 |
| 平台保存/批量上传 | 上传、保存到平台、同步到优测 | references/save_test_plan.md | 禁止用 MCP 保存 |
| 用例调试 | case debug、debug 本地用例、调试优测用例、调试本地 JSON、调试本地文件、调试本地目录 | references/debug_case.md | 禁止误走保存/上传流程 |
| 环境拉取 | env pull、拉取环境、同步环境 | references/env_pull.md | 禁止误走 env save 或生成/调试流程 |
| 环境绑定数据集 | env bind-dataset、绑定数据集到环境、环境绑定数据集、给环境绑定数据集 | references/env_bind_dataset.md | 禁止误走 env save、env pull 或生成/调试流程 |
| 环境保存、上传 | env save、保存环境、上传 env、同步本地 env 到平台 | references/env_save.md | 禁止自动扫描目录或回退默认 env 文件 |
| 申请UIN | 申请uin、申请uin账号、申请账号、申请拨测账号、申请拨测uin、申请压测uin | references/apply_uin.md | 禁止误走测试任务引导、生成/上传/调试/环境流程 |
若用户说“生成并上传”或“生成后顺便调试”，按阶段串行处理：
save_test_plan.md 或 debug_case.md）。
在完成基础文档预读后，仅在需要时追加读取以下文档：
references/rpc_node.md
references/quic_node.md
references/proto_obj.md
references/api_node.md
references/dubbo_node.md
references/sse_node.md
references/if_node.md、references/while_node.md、references/parallel_node.md
references/account_prepare_trace.md
trpc_oidb / oidb → references/trpc_oidb.md
sso_* → references/sso_related.md
trpc-OVBU → references/ovbu.md
规则：只按当前节点/协议类型加载，不做全量扫读。
nodeType，或直接给出足以唯一指向某协议的材料（如 swagger/openapi、HTTP 方法+URL、proto/JCE、dubbo 配置、quicHeader 等）时，按该协议继续。
HTTP/REST、RPC、QUIC、Dubbo、SSE 等之间拿不准，必须先停下来询问用户：要生成什么协议？
满足以下任一条件，即视为需要协议文件的协议场景：
proto / JCE / TAF / tRPC / gRPC / QUIC 等协议内容；
rpc_node 或 quic_node；
nodeType=quic。
此时必须先读取 references/proto_obj.md，并执行以下校验：
app_server_name：立即中断 生成与落盘；唯一合法回复为：请提供协议文件的 app_server_name。
app_server_name：写入 protoFile，且 protoFile 对象里只能有 app_server_name，禁止捏造其他字段。
app_server_name 只能出现在 protoFile[].app_server_name。
app_server_name 复制、映射或回填到 domain、serviceName、funcName。
domain、serviceName、funcName 无法从用户输入、代码、服务注册逻辑中确认：不要猜、不要拿 app_server_name 顶替，必须中断并要求用户补充。
quic 是独立节点类型，必须使用 references/quic_node.md 中的 nodeType=quic、quicHeader、requestBodyType 等字段；禁止把 quic 塞进 rpc_node.protoType。
${a2} 是执行期自动填充的内置变量；严禁把 a2 加入 testcase 顶层 args、链路级 args、节点参数，或任何其他变量定义中。
references/account_prepare_trace.md 中的固定模板。
setup trace；除删除空字符串、空数组、空对象与 null 字段外，不要改节点顺序或其他业务字段值。
qqRedis.refreshUins(start, count) 默认使用 qqRedis.refreshUins(0, 500);；若用户明确要求修改，只允许调整第一个参数 start（uin 起始索引）和第二个参数 count（取数范围 / 导出账号数量）。
testcase/。
sys_polarisDiscover(namespace, serviceName[, env[, canaryLabel]])。
namespace 表示北极星命名空间；Production 表示正式，Development 表示测试，这两个属于 namespace 的示例值。建议优先使用全局变量，不写死。
serviceName 表示北极星服务名，只能来自用户明确提供的信息或代码中的服务注册逻辑；找不到或不确定时必须向用户询问，严禁猜测，也严禁用 app_server_name 顶替。
env 为可选项，表示北极星 env；由用户自己填写，只有在用户明确提供，或代码/配置中能够确认时才可填写；不确定时不要臆造。
canaryLabel 为可选项，表示金丝雀标签；只有在用户明确要求灰度流量，或代码/配置中能够确认时才可填写；默认不要猜测补齐。
domain也就是服务url ，需要使用北极星寻址时，serviceName 必须先确认；env、canaryLabel 只有在可确认时才允许拼入表达式。
protoType=sso_oidb 或 sso_pb，则 domain 固定使用全局变量 ${target}；同时在 testcase 顶层 args 中固定写入 target=${sys_polarisDiscover(Production,sso-internal)}。不是 env；不要改成其他服务名、其他 namespace 或其他 env，也不要把北极星表达式直接写进 domain。
main.go 中服务注册逻辑确认服务名、方法名和路由映射。
${sys_polarisDiscover(${namespace},a.b.c.d)}；若需要显式指定 namespace，可写 ${sys_polarisDiscover(Production,a.b.c.d)}；若需要显式指定 env，可写 ${sys_polarisDiscover(${namespace},a.b.c.d,user-env)}；若还需要指定金丝雀标签，可写 ${sys_polarisDiscover(${namespace},a.b.c.d,user-env,gray-tag)}。
required 校验，要把会影响请求能否真正跑通的参数值，与字段名、类型、层级这类结构性信息严格区分。
domain/serviceName/funcName/env/canaryLabel、顶层/链路级 args、协议头模板（如 header、quicHeader、authInfo）里被请求实际引用的变量或命令字。
example/default/enum、测试数据文件、已确认的历史样例。
path/query/header/body/args/domain/serviceName/funcName/headerTemplate/quicHeader/authInfo）、为什么必须提供、可接受的示例格式；不要逐字段零散追问。
message / struct / 请求体结构的请求，ask 前必须先完整盘点该结构中的全部字段，再分成“已确认可直接填写”“需要用户确认”“可选可跳过”三类；禁止只挑 AI 主观判断为关键的字段去问。
message / struct / 请求体结构的字段数 超过 5 个，就必须使用完整字段表格或等价清单一次性展示全部字段，不允许裁剪后分批零散追问。
QUIC 的 authInfo、quicHeader，或 RPC/SSO 头模板），其中出现的 uid、token、cmd、module、命令字、路由值等仍属于实际请求参数；只要实际值无法 100%确认，就必须先 ask，不能因为模板已存在就直接输出最终用例。
checkList）
在生成或修改 checkList 前，必须先以 references/json_schemas.md 中的 assert_obj 为准。
这一段是重点中的重点：断言最容易出错的不是字段名，而是字段内的取值被模型“脑补”错。尤其是 position、operator、checkType 这三个枚举值，必须逐个按 Schema 精确填写，严禁使用同义词、自然语言或看起来差不多的值。
必须遵守：
assert_obj 中没定义的字段，一律禁止输出。尤其不要臆造 field、path、expected、actual、values、expect、assertKey 等字段名。
position 只能是：code、header、body、bodyJson、publicVariable、rpc_response_header、varJson
operator 只能是：eq、ne、gt、lt、ge、le、ctn、n_ctn、belong、n_belong、exist、n_exist、regex_match
checkType 只能是：content、len、list
contains、notcontain、not_contains、in、not_in、match、bodyjson、jsonBody、text、length 等任何不在枚举中的值。只要不是 Schema 原文，就视为错误。
position="code" 或 position="body" 时，key 没有实际值，不要生成 key 字段；如果要校验 JSON 路径，必须使用 position="bodyJson"，不能写成 body。
position="code"
key 字段
checkType="content"
operator="eq"
expectValue=["200"]
position="bodyJson"
key 为响应 JSON 路径
expectValue 为字符串数组
checkList，确认每一项的字段名、position、operator、checkType 都能在 assert_obj 中找到原始定义；任何一个值不在枚举里，都必须立即重写。
当用户指定 CSV，或目标 JSON 同级目录存在 CSV 文件时启用：
${列名}。
file 或 file_obj 字段。
对每个即将输出的 testcase_obj 执行以下检查：
rpc_node 或 quic_node，则 protoFile[0].app_server_name 不得为空。
trace 下的 uuid 不得臆造；新建时留空或直接省略。
testcase_obj、trace_obj、各类节点对象及其可省略结构字段，若值为 null、空字符串、空数组、空对象，就直接省略；这条检查默认不作用于请求体、请求头等实际业务参数。
write_to_file 落盘。
map init 的意义是生成 .utest-map.yaml 或做必要补全。默认情况下，它只在生成用例 JSON 完成后，且目标目录内不存在 .utest-map.yaml 时执行；如果 .utest-map.yaml 已存在，则直接跳过。上传、调试、环境相关阶段默认不要执行；但如果用户明确要求“执行 map init”，则允许直接执行。
规则：
.utest-map.yaml；存在则不要执行 map init。
map init 不是 shell 内置命令，也不是外部需要现装的工具；它是 本 Skill 在 scripts 目录下预置的二进制执行包的子命令。
"" map init --path "" [--path "" ...]
&，即：& "" map init --path "" [--path "" ...]
scripts 下二进制的绝对路径，不要仅依赖相对路径，因为工作目录（CWD）可能随项目切换。
EXEC_PATH，只能继续核实本地 scripts 目录、修正路径或向用户说明；严禁因为“命令看起来不存在”就去联网下载、包管理安装或生成替代二进制。尤其禁止 curl / wget / Invoke-WebRequest 下载，禁止 npm / pnpm / yarn / pip / go install / brew / apt / choco / scoop 安装任何同名工具。
cmd /c "dir /a \scripts"
ls -la /scripts
--path 必须传绝对路径。
.utest-map.yaml 的目录提供代表性 JSON 文件路径并执行初始化；已存在 .utest-map.yaml 的目录不要重复执行。
生成阶段完成后，再提示用户是否需要上传，不要在生成前询问上传意愿。
推荐反馈方式：
> ✅ 测试场景已就绪：已按业务相关性生成本地优测用例
> 如需继续批量上传到优测平台，请直接说明。
仅当用户明确要求上传、保存或同步到平台时触发。
references/save_test_plan.md。
case save 相关参数（尤其 --protocol-type、--sync-type、--git-url、--git-path、--git-branch）未由用户明确提供，则必须直接向用户索取；禁止通过当前仓库、git remote -v、代码搜索或历史信息自行推断。
utest-mcp / MCP 的 SaveTestPlan 保存或更新用例。
apitest、指定执行机执行等，则直接返回固定提醒和下载地址，不再进入调试阶段，也不再判断用户是不是想调试。
case debug 时，才读取 references/debug_case.md，使用 case debug。
references/env_pull.md。
references/env_bind_dataset.md。
references/env_save.md。
references/apply_uin.md，使用 case apply-uin。
这些阶段不要混入生成/上传规则，除非用户明确要求进入下一个阶段。
以下行为一律视为错误：
checkList 时猜字段名，或输出 assert_obj 未定义字段。
checkList 时猜枚举值，或输出 contains、notcontain、bodyjson 这类不在 Schema 中的值。
map init。
.utest-map.yaml，却仍重复执行 map init。
app_server_name。
app_server_name 回填、映射或复制到 domain、serviceName、funcName。
serviceName 时仍继续猜值或拿近似字段顶替。
uuid。
apitest、任务 UUID 执行或指定执行机执行，却仍继续使用本 Skill 处理，或误走到 case debug。
HTTP/RPC/QUIC/Dubbo/SSE 任一协议继续生成。
path/query/header/body、args、模板字段）的字段名、类型、层级，却无法 100% 确认实际请求参数值时，仍继续生成可上传、可调试的最终 testcase。
""、0、false、[]、{} 等类型默认值、近似值或其他占位方式绕过 ask 模式。
required 字段追问，遗漏其他会影响请求实际通过的参数。
message / struct / 请求体结构后，仍由 AI 自行裁剪字段，只挑部分字段 ask，没有把完整字段清单展示给用户。
message / struct / 请求体结构字段数超过 5 个时，未使用完整字段表格或等价清单一次性展示全部字段，而是分批、零散或按主观判断省略字段。
共 3 个版本