| name | apifox-cli-checkup |
| description | Apifox CLI 使用检查与版本确认：命令成功但页面没看到、创建后 list/get 找不到、测试运行失败、报告缺失、agentHints/help/实际行为不一致，或怀疑本机 CLI 版本不是最新时使用。 |
| metadata | {"requires":{"bins":["apifox"]},"cliHelp":"apifox --help; apifox update --help; apifox cli-schema --help"} |
CLI 使用检查与版本确认
前置条件：先阅读 ../apifox-cli/SKILL.md。若旧总入口与本 skill 的规则冲突，以当前 apifox <command> --help 和本 skill 为准。根据资源类型再读取对应业务 skill。
本 skill 用于公开 CLI 使用排查，不依赖内部接口或内部代码。目标是确认命令、项目、分支、环境、资源 ID、报告位置和 CLI 版本是否一致，再回到具体业务 skill 修正资源结构。Agent 排查时优先以当前 help、schema validate、get 回读和 agentHints 组成闭环，不要只看 summary 文案。
何时使用
- CLI 返回成功，但 Apifox 页面没看到资源或展示不完整。
- 创建后
list/get 找不到资源。
- 测试用例、测试场景或测试套件运行失败。
- 本地报告或云端报告找不到、没有步骤详情。
agentHints、help、示例或实际命令行为互相矛盾。- 用户或测试同学反馈“我这边没有这个参数”“命令不认识”，需要确认 CLI 版本。
先做 5 件事
- 记录原始命令、projectId、branch、resourceId、environmentId、文件路径和是否带
--api-base-url。
- 执行
apifox --version，确认本机 CLI 版本；参数不存在时先看是否需要更新。
- 执行对应
apifox <command> --help，以当前公开 help 为准，不凭旧文档或记忆使用参数。
- 用对应
list/get 回读资源，确认是否写入了预期项目、分支、模块、目录或分类。
- 如果是运行或报告问题，先区分本地报告和云端报告：未带
--upload-report 时，不要去云端报告列表找本次结果。
版本检查
先看版本和命令 help：
apifox --version
apifox import --help
apifox test-case category --help
如果测试说明里要求的新参数没有出现在 help 中，优先更新 CLI：
apifox update
非交互环境或确认直接更新时：
apifox update --yes
如果自动更新提示影响排查，可以让用户在 shell 配置里设置禁用每日检查，但这不会影响手动 apifox update：
export APIFOX_CLI_DISABLE_UPDATE_CHECK=1
版本排查结论必须写清：当前 apifox --version、命令路径（如 which apifox）、缺失的参数名、建议更新方式。
help 与提示冲突
- 公开文档、agentHints、历史示例和实际行为不一致时，优先以当前
apifox <command> --help 和实测为准。
- 不主动推荐 help 未公开的隐藏别名。
success=false 时以真实 success 字段和退出码为准，不要相信 summary 里的成功语义。- 如果命令提示下一步但实际参数不存在，记录为 CLI 提示问题，并使用 help 中公开的替代命令。
页面看不到资源
优先检查：
- 是否写入了正确 project。
- 是否带了正确
--branch。
- 是否资源在 AI 分支中，且页面当前查看的是同一分支。
- 是否写入到了预期模块或目录。
- 测试用例是否使用了有效
categoryId。
- Apifox 原生格式二次导入时，是否因为模块策略导致资源进入了新模块。
常用回读命令：
apifox endpoint list --project <projectId> --branch <branchName>
apifox test-case list --project <projectId> --endpoint <endpointId> --branch <branchName>
apifox test-scenario get <scenarioId> --project <projectId> --branch <branchName> --with-case-detail
如果 get/list 能看到，但页面看不到，先确认页面筛选条件、分支、模块、目录、分类是否一致；不要直接重建资源。
测试用例排查
- 创建前必须用
apifox test-case category --project <projectId> 获取有效 categoryId。
- 当前
test-case category 不支持 --endpoint；按接口查看用例用 test-case list --endpoint <endpointId>。
test-case get 能看到结构，只说明资源已保存，不代表 requestBody、断言、提取变量和脚本一定能运行。- 运行失败时检查 environment、变量、请求体、前后置脚本、断言和报告详情。
测试场景排查
test-scenario create 只创建场景元数据；复杂步骤需要后续 import-steps、add-ref 或 update --file。- 创建或更新后先
test-scenario get --with-case-detail，确认步骤树和 HTTP 详情展开正常。
- 步骤间变量为空时，检查是否运行完整场景、步骤编号、响应路径、提取变量和环境选择。
- 不要把
test-case 的结构直接写成 test-scenario 步骤。
运行与报告排查
- 未指定
--environment 时，服务端可能使用项目默认环境；为了复现，建议显式指定。
- 本地报告看
--out-dir 和 --out-file。
- 只有运行时带
--upload-report，云端 test-report list/get/download 才能看到本次报告。
- 报告没有步骤详情时，先对比本地 JSON 和云端报告；本地也没有详情时，回查运行对象和资源结构。
- 有副作用的测试不要在生产环境默认执行。
常见分流
| 现象 | 处理 |
|---|
| 新参数不识别 | apifox --version、which apifox，必要时 apifox update --yes |
| 创建成功但页面没看到 | 检查 project、branch、模块、目录、分类、页面筛选 |
| test-case 页面看不到 | 检查 categoryId、endpoint、branch；用 test-case list --endpoint 回读 |
| 场景步骤不展示 | test-scenario get --with-case-detail，确认 create 后是否真正写入 steps |
| run-config 或运行前失败 | 确认 case/scenario/endpoint/environment/branch 都存在且一致 |
| 云端报告找不到 | 确认运行时是否带 --upload-report |
| agentHints 和 help 冲突 | 以当前 help 和实测为准，记录提示问题 |
