mcpField
A
apifox-cli

apifox-cli

github.com/apifox开发17579 次安装16 周前更新
代码仓库

关于 apifox-cli

apifox-cli 是指导 Agent 使用 Apifox CLI 的技能，涵盖命令与 schema 查询、写入前校验。它还说明项目选择、分支权限及敏感操作的确认要求。

主要功能

  1. 01依据 CLI 输出确认命令和 schema
  2. 02写入前校验资源数据
  3. 03指导项目与分支选择
  4. 04保护令牌和本地配置
  5. 05破坏性操作前要求确认

适用场景

  1. 01准备并校验 Apifox 资源变更
  2. 02在 AI 分支中处理改动
  3. 03排查命令或 schema 错误

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/apifox/apifox-cli-skills --skill apifox-cli

安装后在 Claude Code 中输入/apifox-cli确认已加载。

详细介绍

Apifox CLI

使用 Apifox CLI 完成用户请求；不要凭记忆拼凑 payload，优先根据 CLI 的 --help、cli-schema、cli-schema validate 和 agentHints.nextSteps 推进下一步。

新会话检查

  • 首次处理 Apifox CLI 任务时，先简单确认 CLI 可用：apifox --version、apifox --help。
  • 如果 apifox 不存在或无法输出版本，先安装 CLI：npm i -g apifox-cli@latest --registry=https://registry.npmmirror.com/。
  • 安装后执行 apifox login --with-token <TOKEN> 登录。API 访问令牌可在 Apifox 客户端或网页端「用户头像 → 账号设置 → API 访问令牌」中创建。
  • 不要每次都默认升级；只有命令返回版本过低、unknown command、参数缺失疑似由旧版导致，或用户任务依赖新能力时，才建议升级。

基础用法

apifox --help
apifox <command> --help
apifox <command> <subcommand> --help

常用全局参数：

--project <projectId>     项目 ID
--branch <branchName>     分支名；纯数字值兼容旧 branchId
--access-token <token>    覆盖当前登录 token
--api-base-url <url>      私有部署地址

登录与项目

  • 未登录时请用户提供 API 访问令牌，然后执行：apifox login --with-token <TOKEN>。
  • Apifox CLI 的鉴权凭证保存在 ~/.apifox/config.toml；不要将 token 打印到日志、提交到仓库或写入普通聊天摘要。
  • 如果用户未指定项目，先检查当前工作区是否存在 .apifox/settings.json；如果其中有常用默认 projectId，优先使用该项目。
  • 可建议用户从「项目设置 - 基本设置 - 项目 ID」获取项目 ID；也可先执行 apifox project list，让用户确认要执行命令的目标项目。
  • 写入任何本地配置文件前，先询问用户。

写入标准流程

强制要求：执行 create 或 update 命令前，必须先获取完整的资源定义和数据格式，并在正式执行前通过 cli-schema validate 校验写入内容的准确性。具体流程：

  1. 查询对应资源执行命令的 JSON schema：apifox cli-schema get <schemaKey>
  2. 生成资源的 JSON 数据文件。
  3. 校验：apifox cli-schema validate <schemaKey> --file <path>
  4. 只有 validate 无误后，才能执行真正的 create 或 update 命令。

命令输出结果后，优先读取 JSON 输出中的 agentHints.nextSteps，继续执行或恢复操作。

CLI 事实优先

  • 具体命令、参数和 schema key 以当前 CLI 输出为准：apifox <command> --help、apifox cli-schema list、agentHints.nextSteps。
  • 如果本 skill 与当前 CLI 输出不一致，以当前 CLI 输出为准，并同步修正本 skill 中的事实性描述。

CLI 写入权限声明

  • 执行写入时若受到 AI（CLI 来源）权限限制，且用户未声明，不要替用户选择；优先询问用户选择写入方式：开启目标分支的直接编辑权限，或在 AI 分支上编辑目标分支数据。
  • 如果用户需要直接编辑主分支、迭代分支或通用分支数据，请用户在 Apifox 客户端 2.8.32+ 版本中前往「项目设置 - 功能设置 - AI 功能设置 - 外部 AI 编辑权限」，开启直接编辑权限开关。
  • 如果用户选择 AI 分支，流程如下： step1：创建 AI 分支并指定来源分支； step2：根据实际需要，将来源分支资源导入（pick-to）； step3：根据用户需求编辑 AI 分支； step4：完成后，提醒用户确认是否发起合并请求或合并。
  • 直接通过 CLI 执行合并或合并请求时，要求来源分支和目标分支的直接编辑权限开关均已开启；否则请提醒用户先打开对应分支类型的权限开关，或直接在客户端手动触发合并。

AI 分支说明

  • AI 分支是供 AI/自动化修改项目资源的隔离分支，可避免直接影响源分支。
  • 如果 AI 分支在 24 小时内与来源分支无差异，将自动归档。
  • AI 分支初始为空，不会自动克隆源分支资源；编辑或删除来源分支中已有的资源前，请先将其导入 AI 分支。
  • 在 AI 分支中新建资源无需先导入。
  • AI 分支中的修改不会自动写回源分支；完成后必须让用户确认是否立即合并或发起合并请求。
  • 目标主分支受保护时（isProtected），优先使用 merge-request，不要直接使用 merge。

必须询问用户

  • 登录 token、写入本地配置、私有部署地址。
  • 创建或切换 AI 分支、将源分支资源导入 AI 分支。
  • 删除、归档、覆盖导入、批量更新等破坏性操作。
  • 将 AI 分支的更改 merge / merge-request 回源分支。
  • 是否升级 CLI。

故障恢复

现象处理
未登录apifox login --with-token <TOKEN>
不知道项目apifox project list
不知道命令参数apifox <command> --help
参数或 schema 错误先运行 cli-schema get / cli-schema validate
AI 写入受限解释 AI 分支/权限开关，让用户选择
私有部署添加 --api-base-url https://your-server

评论

支持 Markdown