apidog-cli-checkup

CLI 用法检查与版本确认

前提条件：先阅读 ../apidog-cli/SKILL.md。如果稳定版入口技能与此技能冲突，请以当前的 apidog <command> --help 和此技能为准。然后根据资源类型阅读对应的领域技能。

此技能用于排查公开 CLI 的问题，不依赖内部 API 或内部代码。目标是确认命令、项目、分支、环境、资源 ID、报告位置和 CLI 版本，然后回到领域技能修复资源结构。Agent 应通过当前帮助、架构验证、get 回读和 agentHints 闭环；不要只相信摘要文本。

适用场景

• CLI 返回成功，但 Apidog 客户端中看不到资源，或显示不完整。
• 创建资源后，无法通过 list/get 找到该资源。
• 测试用例、测试场景或测试套件运行失败。
• 本地或云端报告缺失，或没有步骤详情。
• agentHints、帮助、示例或实际命令行为相互冲突。
• 用户或测试人员表示缺少参数或命令未知，需要确认 CLI 版本。

首要检查的五项内容

1. 记录原始命令、projectId、branch、resourceId、environmentId、文件路径，以及是否使用了 --api-base-url。
2. 运行 apidog --version 确认本地 CLI 版本；如果缺少某个参数，请检查是否需要更新。
3. 运行匹配的 apidog <command> --help；以当前公开帮助为准，不要依赖旧文档或记忆。
4. 使用匹配的 list/get 命令回读资源，并确认项目、分支、模块、文件夹或类别。
5. 对于运行或报告问题，要区分本地报告和云端报告。未使用 --upload-report 时，不要期望在云端报告列表中看到本地运行记录。

版本检查

先检查版本和命令帮助：

apidog --version
apidog import --help
apidog test-case category --help

如果帮助中缺少所需的新参数，请先更新 CLI：

apidog update

对于非交互式环境或已确认可直接更新的情况：

apidog update --yes

如果自动更新提示会干扰排查，用户可以在 shell 配置中关闭每日检查。这不会禁用手动执行 apidog update：

export APIDOG_CLI_DISABLE_UPDATE_CHECK=1

版本问题诊断必须包含当前的 apidog --version、命令路径（例如 which apidog）、缺少的参数名称，以及建议的更新方法。

帮助与提示冲突

• 如果公开文档、agentHints、历史示例和实际行为相互冲突，请优先参考当前的 apidog <command> --help 和实际测试。
• 不要主动推荐帮助中未公开的隐藏别名。
• 当 success=false 时，应以实际的 success 字段和退出代码为准，而不是听起来像成功的摘要。
• 如果提示建议了下一步操作，但相应参数并不存在，请将其记录为 CLI 提示问题，并使用帮助中公开的替代方法。

客户端中缺少资源

首先检查：

• 项目是否正确。
• --branch 是否正确。
• 资源是否位于 AI 分支中，而客户端当前查看的是另一个分支。
• 预期的模块或文件夹。
• 测试用例的 categoryId 是否有效。
• 对于原生格式的二次导入，检查模块导入策略是否将资源放入了新模块。

有用的回读命令：

apidog endpoint list --project <projectId> --branch <branchName>
apidog test-case list --project <projectId> --endpoint <endpointId> --branch <branchName>
apidog test-scenario get <scenarioId> --project <projectId> --branch <branchName> --with-case-detail

如果 get/list 能看到资源，但客户端看不到，请先确认客户端筛选条件、分支、模块、文件夹和类别。不要立即重新创建资源。

测试用例诊断

• 创建前，运行 apidog test-case category --project <projectId> 获取有效的 categoryId。
• 当前的 test-case category 不支持 --endpoint；要查看端点用例，请使用 test-case list --endpoint <endpointId>。
• test-case get 能看到结构只表示已保存；这并不能证明 requestBody、断言、提取器或脚本可以运行。
• 运行失败时，请检查环境、变量、请求体、前置/后置脚本、断言和报告详情。

测试场景诊断

• 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 和云端报告。如果本地详情也缺失，请检查运行目标和资源结构。
• 默认不要对生产环境运行会产生副作用的测试。

常见问题路由

症状	操作
新参数无法识别	检查 apidog --version、which apidog，如有需要，使用 apidog update --yes 更新
创建成功，但客户端中未显示	检查项目、分支、模块、文件夹、类别和客户端筛选条件
客户端中看不到测试用例	检查 categoryId、端点、分支；使用 test-case list --endpoint 读取并确认
未显示场景步骤	执行 test-scenario get --with-case-detail；确认步骤是在创建后写入的
缺少云端报告	确认运行时使用了 --upload-report