需要管理 Apifox 项目资源、运行接口自动化测试或配置…

适用于通过 Apifox CLI 管理 Apifox 项目资源、运行测试套件、查看报告及维护 Runner、定时任务、通知等 CI/CD 配置。

适用场景

解决思路

1. 用 Apifox CLI 完成用户请求；不要凭记忆拼 payload，优先让 CLI 的 `--help`、`cli-schema`、`cli-schema validate`、`agentHints.nextSteps` 驱动下一步。
2. 首次处理 Apifox CLI 任务时，先轻量确认 CLI 可用：运行 `apifox --version`、`apifox --help`。
3. 如果 `apifox` 不存在或无法输出版本，先安装 CLI：运行 `npm i -g apifox-cli@latest --registry=https://registry.npmmirror.com/`。
4. 安装后执行 `apifox login --with-token <TOKEN>` 登录；API 访问令牌可在 Apifox 客户端或网页端「用户头像 → 账号设置 → API 访问令牌」创建。
5. 不要每次默认升级；只有命令返回版本过低、unknown command、参数缺失疑似旧版导致，或用户任务依赖新能力时，才建议升级。
6. 查看全局帮助：运行 `apifox --help`。
7. 查看命令帮助：运行 `apifox <command> --help`。
8. 查看子命令帮助：运行 `apifox <command> <subcommand> --help`。
9. 使用全局参数 `--project <projectId>` 指定项目 ID。
10. 使用全局参数 `--branch <branchName>` 指定分支名；纯数字值兼容旧 branchId。
11. 使用全局参数 `--access-token <token>` 覆盖当前登录 token。
12. 使用全局参数 `--api-base-url <url>` 指定私有部署地址。
13. 未登录时让用户提供 API 访问令牌，执行 `apifox login --with-token <TOKEN>`。
14. 将 Apifox CLI 鉴权凭证存在 `~/.apifox/config.toml`；不要把 token 打印到日志、提交到仓库或写进普通聊天摘要。
15. 如果用户未指定项目，先查看当前工作区是否存在 `.apifox/settings.json`；如其中有常用默认 `projectId`，优先使用该项目。
16. 项目 ID 可推荐用户从「项目设置 - 基本设置 - 项目 ID」获取；或先执行 `apifox project list`，给用户确认需执行命令的目标项目。
17. 写入任何本地配置文件前先询问用户。
18. 强制：执行 `create` 或 `update` 命令前必须先获取完整的资源定义和数据格式，并在正式执行前通过 `cli-schema validate` 校验写入准确。
19. 查对应资源执行命令的 JSON schema：运行 `apifox cli-schema get <schemaKey>`。
20. 生成资源的 JSON 数据文件。
21. 校验：运行 `apifox cli-schema validate <schemaKey> --file <path>`。
22. 只有 `validate` 无误后，才执行真实 `create` 或 `update` 命令。
23. 命令输出结果后，优先读取 JSON 输出里的 `agentHints.nextSteps` 继续执行或恢复。
24. 具体命令、参数、schema key 以当前 CLI 输出为准：运行或查看 `apifox <command> --help`、`apifox cli-schema list`、`agentHints.nextSteps`。
25. 如本 skill 与当前 CLI 输出不一致，以当前 CLI 输出执行，并同步修正本 skill 的事实性描述。
26. 执行写入被 AI（CLI 来源）权限限制时，若用户未声明，不要替用户选择，优先询问写入方式：开启目标分支的直接编辑权限，或在 AI 分支上编辑目标分支数据。
27. 如用户需直接编辑主分支、迭代分支或通用分支数据，请用户在 Apifox 客户端 2.8.32+ 版本在「项目设置 - 功能设置 - AI 功能设置 - 外部 AI 编辑权限」开启直接编辑权限的开关。
28. 如用户选择 AI 分支，按流程执行：step1 创建 AI 分支并指定来源分支；step2 按实际需要导入（pick-to）来源分支资源；step3 按用户需求编辑 AI 分支；step4 完成后，提醒用户确认是否发起合并请求或合并。
29. 从 CLI 直接执行合并/合并请求时，要求来源分支和目标分支的直接编辑权限开关均已开启；否则请提醒用户先打开对应分支类型的权限开关，或直接在客户端手动触发合并。
30. 把 AI 分支作为给 AI/自动化修改项目资源的隔离分支，避免直接污染源分支。
31. 注意 AI 分支若在 24 小时内与来源分支无差异，将自动归档。
32. 注意 AI 分支初始为空，不会自动克隆源分支资源；编辑/删除来源分支已有资源前，先导入到 AI 分支。
33. 在 AI 分支中新建资源无需先导入。
34. 注意 AI 分支修改不会自动写回源分支；完成后必须让用户确认是否立刻合并或发起合并请求。
35. 目标主分支受保护时（isProtected），优先走 `merge-request`，不要直接 `merge`。
36. 登录 token、本地配置写入、私有部署地址，必须询问用户。
37. 创建/切换 AI 分支、导入源分支资源到 AI 分支，必须询问用户。
38. 删除、归档、覆盖导入、批量更新等破坏性操作，必须询问用户。
39. 将 AI 分支改动 merge / merge-request 回源分支，必须询问用户。
40. 是否升级 CLI，必须询问用户。
41. 未登录时，执行 `apifox login --with-token <TOKEN>`。
42. 不知道项目时，执行 `apifox project list`。
43. 不知道命令参数时，执行 `apifox <command> --help`。
44. 参数或 schema 错误时，先跑 `cli-schema get` / `cli-schema validate`。
45. AI 写入受限时，解释 AI 分支/权限开关，让用户选择。
46. 私有部署时，加 `--api-base-url https://your-server`。

适用边界 · 注意事项

• 没有 Apifox 账号、API 访问令牌或未安装/无法安装 apifox CLI 时。
• 仅做通用 HTTP 调试，不涉及 Apifox 项目资源、自动化测试或 CI/CD 配置时。
• 目标分支 AI 写入权限未开启，且用户不愿创建/使用 AI 分支或走 merge-request 流程时。