# 使用 Apifox CLI 搭配 AI Agent

Apifox CLI 旨在将 Apifox 的 API 全生命周期能力引入 AI Agent 工作流。通过 Apifox CLI 和 Apifox AI Agent Skills，AI Agent 可以使用命令行工作流查询项目资源、运行自动化 API 测试、在写入前校验数据，以及管理 API 或测试资产。

Apifox CLI 适合 AI Agent 使用，因为它提供稳定、可验证的工程操作，而不是要求 Agent 逐个调用大量小工具。

:::tip[]
产品概览请参见 [Apifox CLI](https://apifox.com/apifox-cli/)。
:::

## AI Agent 可以用 Apifox CLI 做什么

安装并完成认证后，AI Agent 可以使用 Apifox CLI 协助完成以下任务：

- 查看和管理 API 资源，包括接口、数据模型、目录、参数、响应定义、响应示例和标签。
- 基于 API 定义创建和更新接口测试用例。
- 管理自动化测试场景和测试套件。
- 在命令行、本地脚本或 CI/CD 流水线中运行自动化测试场景和测试套件。
- 生成 CLI、HTML、JSON、JUnit 等格式的测试报告。
- 管理环境、变量和运行时配置。
- 导入和导出 30+ 种格式的 API 数据，例如 OpenAPI、Postman、HAR、JMeter、WSDL、Markdown 和 Apifox 原生格式。
- 管理 API 文档站点和共享文档。
- 管理测试数据集，用于数据驱动测试。
- 使用分支能力，包括用于安全隔离 Agent 生成变更的 AI 分支。

## 为什么使用 Apifox CLI，而不是只使用 MCP 工具？

MCP 工具通常暴露许多原子化 API 操作。Apifox CLI 则提供更高层级的命令，更贴近常见研发工作流。

相比只使用 MCP 工具，Apifox CLI 可以帮助 AI Agent：

- 执行更高粒度的操作，例如读取 → 校验 → 写入 → 验证。
- 通过 `cli-schema validate` 进行运行时 Schema 校验。
- 返回带有 `agentHints` 的结构化命令输出，引导下一步操作。
- 在写入前进行数据校验，提前发现创建或更新资源时可能出现的问题。
- 减少重复工具调用，降低 token 消耗。

## 前置要求

在通过 AI Agent 使用 Apifox CLI 前，请确保：

- 已安装 Node.js 和 npm/npx。
- 已拥有 Apifox 账号。
- 当前账号有权限访问需要让 Agent 操作的 Apifox 项目。
- 已安装 Apifox CLI。
- Apifox CLI 已通过 Apifox API 访问令牌完成认证。
- 已为你的 Agent 安装 Apifox AI Agent Skills。

:::tip[]
安装详情请参见 [Apifox CLI 安装引导](https://apifox.com/apifox-cli-installation-guide.md)。
:::

## 安装 Apifox CLI

安装或升级 Apifox CLI：

```bash
npm i -g apifox-cli@latest --registry=https://registry.npmmirror.com/
```

如果镜像源较慢或不可用，可以改用 npm 官方源：

```bash
npm install -g apifox-cli
```

验证安装结果：

```bash
apifox --version
```

你也可以直接让 AI Agent 阅读并执行安装引导：

```text
Read https://apifox.com/apifox-cli-installation-guide.md and follow instructions.
```

## 获取 API 访问令牌

在 Apifox 客户端或网页端中获取访问令牌：

1. 点击用户头像。
2. 打开 **账号设置**。
3. 进入 **API 访问令牌**。
4. 创建并复制 token。

:::warning[]
不要在日志、聊天消息、仓库文件或截图中打印 token。
:::

## 登录 Apifox CLI

使用 token 登录：

```bash
apifox login --with-token <TOKEN>
```

检查当前登录身份：

```bash
apifox whoami
```

列出可访问的项目：

```bash
apifox project list
```

如果已经知道项目 ID，可以通过资源查询命令验证访问权限：

```bash
apifox environment list --project <PROJECT_ID>
```

## 记录长期使用的工作项目

对于 Agent 工作流，建议将常用项目 ID 保存到 `.apifox/settings.json`。

项目 ID 获取路径：

```text
项目 → 项目设置 → 基本设置 → 项目 ID
```

然后创建 `.apifox/settings.json`：

```json
{
  "projectId": 123456
}
```

当用户请求没有明确指定项目时，AI Agent 可以使用此文件中保存的 `projectId`。

同时建议确保 `.apifox/.gitignore` 包含：

```gitignore
*.private.*
```

<!-- TODO: 添加截图，展示在项目设置中找到项目 ID 的位置。 -->

## 安装 Apifox AI Agent Skills

安装 Apifox AI Agent Skills，让 Agent 知道如何正确使用 Apifox CLI：

```bash
npx -y skills add https://apifox.com
```

该命令会启动交互流程，你可以选择要安装的 Skills、目标 AI Agent 和安装范围。

也可以通过 GitHub 仓库安装：

```bash
npx -y skills add https://github.com/apifox/apifox-cli-skills
```

如果当前环境无法访问官方安装源，请按照所用 AI Agent 的规则手动安装 Apifox AI Agent Skills。使用 `WebFetch` 获取：

```text
https://apifox.com/.well-known/agent-skills/index.json
```

然后根据其中的 `url` 字段下载并安装所需的 `SKILL.md` 文件。

推荐安装全部 8 个 Skills。至少应安装 `apifox-cli`。

<!-- TODO: 如有需要，添加 Skills 安装流程截图。 -->

## Apifox AI Agent Skills 如何提供帮助

Apifox CLI + `SKILL.md` 面向 AI Agent 集成而设计。Skills 系统通过以下方式帮助 Agent 正确使用 CLI：

- **任务感知调用**：Agent 可以根据任务匹配相关 Skills，无需反复指定 CLI 使用方式。
- **判断规则**：指导 Agent 何时需要校验、何时需要回读、何时不能猜测 ID。
- **工作流指导**：通过命令输出中的 `agentHints` 推荐下一步操作。
- **AI 分支安全机制**：可在隔离的 AI 分支中进行变更，避免直接污染项目数据。

当前 Apifox Skills 发现索引包含：

- `apifox-cli`
- `apifox-test-case`
- `apifox-test-automation`
- `apifox-test-scenario`
- `apifox-branch`
- `apifox-cli-checkup`
- `apifox-import-export`
- `apifox-workflow-api-lifecycle`

## 使用 AI 分支保障 Agent 生成变更的安全性

当 AI Agent 需要修改 API 或测试资产时，应尽量使用 AI 分支。

AI 分支可以帮助隔离 Agent 生成的变更：

- 将 Agent 修改与主分支隔离。
- 提醒用户这些变更尚未合并。
- 合并前需要用户确认。

<!-- TODO: 确认目标页面后，链接到 AI 分支文档。 -->

默认情况下，为了安全，项目写入权限可能受到限制。如需直接编辑主分支，请在项目 AI 功能设置中开启外部 AI 编辑权限。

<!-- TODO: 添加截图，展示项目 AI 功能设置和外部 AI 编辑权限。 -->

## 写入前校验数据

当 Agent 创建或更新结构化资源时，应在写入前使用 `cli-schema validate`。

例如：

```bash
apifox cli-schema validate test-case-create --file ./test-case.json
```

该校验可以帮助发现以下问题：

- 缺少必填字段。
- 类型不匹配。
- 结构错误。
- 枚举值无效。
- 字段名无效。

## Agent 工作流示例

一个典型的 Apifox CLI + AI Agent 工作流如下：

1. 用户要求 Agent 检查、测试或更新某个 Apifox 项目。
2. Agent 检查 `.apifox/settings.json`，或向用户询问目标项目 ID。
3. Agent 使用 `apifox whoami` 验证 CLI 登录状态。
4. Agent 通过 CLI 命令读取项目资源。
5. 如果需要写入数据，Agent 先准备本地 JSON 文件。
6. Agent 使用 `cli-schema validate` 校验文件。
7. Agent 通过 Apifox CLI 应用变更。
8. Agent 回读更新后的资源或测试结果，验证变更是否生效。
9. 如果变更发生在 AI 分支中，用户在合并前进行审查和确认。

## 通过 AI Agent 运行测试

Agent 可以使用 Apifox CLI 运行自动化 API 测试。

运行测试场景：

```bash
apifox run --access-token $APIFOX_ACCESS_TOKEN -t <testScenarioId> -e <environmentId> -r html,cli
```

运行测试套件：

```bash
apifox run --access-token $APIFOX_ACCESS_TOKEN --test-suite <testSuiteId> --project <projectId>
```

使用 `apifox run --help` 查看当前已安装 CLI 版本支持的最新命令选项。

## 最佳实践

使用 Apifox CLI 搭配 AI Agent 时，建议：

- 安全存储访问令牌。不要将 token 放入提示词、日志、仓库文件或截图中。
- 当 Agent 经常操作同一个项目时，将常用项目 ID 保存到 `.apifox/settings.json`。
- 使用 `apifox whoami` 验证当前登录身份。
- 当命令参数不明确时，使用 `apifox <command> --help` 查看说明。
- 在创建或更新结构化资源前使用 `cli-schema validate`。
- 对 Agent 生成的变更优先使用 AI 分支。
- 变更后回读资源或测试结果，验证操作结果。
- 使用 CI/CD 命令构建可重复的自动化测试工作流。

## 故障排查

| 问题 | 解决方案 |
| --- | --- |
| `apifox: command not found` | 重新全局安装 Apifox CLI，并确认 npm global bin 目录已加入 `PATH`。 |
| 未登录 | 重新执行 `apifox login --with-token <TOKEN>`。 |
| 项目不存在或无权限 | 检查项目 ID，并确认 token 对应账号有权限访问该项目。 |
| 不确定命令参数 | 执行 `apifox <command> --help` 查看最新用法。 |
| Invalid characters in header content | 检查环境变量初始值、认证请求头值，以及换行、多余空格等隐藏字符。 |