核心原则：让规则在正确的地方执行
我们从经验中总结出了一个核心原则：
不要让模型记住所有规则。让规则在正确的地方执行。
这类似于 Agent 评估中的一个经验教训：
| 指标类型 | 归属地 |
|---|---|
| 确定性指标 | 脚本、代码、自动化检查 |
| 语义判断 | LLMs、模型推理 |
在 Apifox CLI + SKILL 中：
| 内容 | 执行位置 |
|---|---|
| 确定性结构校验 | CLI (cli-schema) |
| 任务判断与生成 | Agent |
让 CLI 校验结构，让 Agent 生成内容。
模型记忆的问题
当 AI Agent 协助创建或更新 Apifox 资源时，风险不仅在于生成内容。
真正的风险在于：在没有足够的结构或验证的情况下，将生成的内容写入真实项目。
Apifox 的资源是结构化的。考虑一个测试用例或测试场景包含的内容：
| 组件 | 复杂度 |
|---|---|
| 请求数据 | Method, URL, headers, body, auth |
| 断言 | 比较符、主体、目标值、条件 |
| 变量提取 | 变量名、类型、提取路径 |
| 前置脚本 | 请求前的脚本 |
| 后置脚本 | 响应后的脚本 |
| 步骤顺序 | 序列、依赖关系 |
| 环境引用 | 环境 ID、变量覆盖 |
如果 Agent 靠猜测来构建结构：
- 错误的字段名 → 写入失败
- 无效的枚举值 → 服务器拒绝
- 缺失必填字段 → 资源不完整
- 错误的类型 → UI 显示异常
- 错误的嵌套 → 测试行为不符合预期
cli-schema validate：质量门禁
我们原则最直接的体现就是 cli-schema validate。
apifox cli-schema validate test-scenario-update --file ./scenario-update.json
当 Agent 想要写入或更新测试场景时，让 AI 生成复杂的步骤结构是非常容易出错的。
validate 命令的作用：
- 确认字段名称
- 检查结构有效性
- 验证枚举值的有效性
- 校验类型约束
所有这些都在发起写入请求之前完成。
cli-schema 捕获的常见错误
以下是 Agent 经常犯的真实错误示例，而这些错误都能被 cli-schema validate 捕获：
| 错误值 | 正确值 | 上下文 |
|---|---|---|
global |
globals |
变量作用域类型 |
contains |
include |
断言比较符 |
responseBody |
responseJson |
响应体主体 |
"500" (字符串) |
500 (数字) |
毫秒延迟 |
equals |
equal |
断言比较符 |
header |
headers |
请求头字段 |
这些并非理论推测。我们是通过真实的 Agent 交互发现这些问题的。
每一个错误都会导致：
- 写入请求失败
- API 报错响应
- Agent 对出错原因感到困惑
- 多次重试尝试
- 重复调用导致的 Token 浪费
通过 cli-schema validate，这些错误在发起网络调用之前就在本地被捕获了。
设计哲学
让我们考虑一下其他替代方案：
方案 1：将规则写入 Prompt
如果我们把所有字段规则都写进 Agent 的 Prompt 中：
- 记录每个字段名
- 列出每个枚举值
- 解释每个类型约束
- 描述每个嵌套结构
结果：巨大的上下文负担。
一个完整的测试场景 Schema 很容易就需要 5,000+ Token 的描述。这是模型在执行每项任务时都必须携带的上下文，即使大多数规则在当时并不相关。
方案 2：依赖模型记忆
如果我们依赖模型去“记住”正确的结构：
- 模型在某些 API 模式上训练过
- 但并未针对 Apifox 的 Schema 进行专门训练
- 不同产品的字段名各不相同
- 枚举值是产品特有的
结果：高错误率。
模型对 Apifox 特有的约定没有完美的记忆。它会进行猜测——而猜测往往是错误的。
更好的方法：本地校验
让 Agent 生成草稿。让 CLI 在写入前执行校验。
# Agent 生成 JSON
# (Agent 不需要记住所有规则)
# CLI 校验
apifox cli-schema validate test-case-create --file ./test-case-create.json
# 如果有错，CLI 输出具体的错误信息
# Agent 根据错误进行调整
# 只有校验通过后才执行写入
apifox test-case create --project <projectId> --file ./test-case-create.json
Schema 的转变
cli-schema validate 改变了 Schema 的意义：
| 之前 | 之后 |
|---|---|
| Schema = 模型必须记住的知识 | Schema = 必须通过的质量门禁 |
| 通过失败的写入发现错误 | 通过本地校验发现错误 |
| 通过网络调用进行重试 | 通过本地调整进行修复 |
| 上下文负担 | 执行门槛 |
问题不会在无意义的往返网络请求中被消耗。
质量检查通过本地命令即可完成。
实际案例
让我们走一遍真实的工作流：
# Agent 读取接口详情
apifox endpoint get <endpointId> --project <projectId>
# Agent 生成测试用例 JSON
# (创建 ./test-case-create.json)
# 写入前进行校验
apifox cli-schema validate test-case-create --file ./test-case-create.json
如果校验通过：
apifox test-case create --project <projectId> --file ./test-case-create.json
如果校验失败：
Error: Field "assertions[0].comparator" has invalid value "contains"
Valid values: equal, not_equal, greater, less, include, not_include, exists, not_exists
Error: Field "extractors[0].type" has invalid value "global"
Valid values: globals, environment, collection, local
Suggestion: Fix these fields and re-validate before writing.
Agent 会：
- 读取具体的错误信息
- 准确理解哪里出错了
- 调整 JSON 文件
- 重新运行校验
- 仅在有效时继续执行
没有失败的写入。没有困惑的重试。没有浪费的 Token。
更深层的启示
这一原则不仅限于校验。
| 规则类型 | 归属地 |
|---|---|
| 字段名规则 | cli-schema |
| 枚举值规则 | cli-schema |
| 类型约束 | cli-schema |
| 工作流顺序 | SKILL |
| 下一步引导 | agentHints |
| 任务拆解 | Agent |
确定性规则 → 工程系统
语义判断 → Agent
下一步预告
既然我们已经建立了校验原则，接下来的问题是：
校验之后，CLI 如何引导 Agent 进入下一步？
在第四部分 agentHints：教 CLI 如何与 Agent 对话 中，我们将探讨带有“下一步建议”的结构化输出如何将 CLI 从一个命令执行器转变为工作流导航器。
核心要点
- 核心原则：规则属于执行层，而非上下文层。
cli-schema validate是写入前的质量门禁。- 常见错误：错误的字段名、无效的枚举、错误的类型。
- 校验在本地捕获错误，节省了网络往返。
- Schema 从“要记住的知识”转变为“要通过的门禁”。
- 确定性规则归于工程；语义判断归于 Agent。
下载 Apifox，在一个工作区内完成 API 的 设计、Mock、测试 和 文档 制作。了解更多关于 Apifox CLI 的信息，助力命令行 API 测试、CI 自动化和 AI Agent 工作流。
开发必备：API 全流程管理神器 Apifox
介绍完上文的内容，我想额外介绍一个对开发者同样重要的效率工具 —— Apifox。作为一个集 API 文档、调试、设计、测试、Mock、自动化测试于一体的工具，Apifox 是目前提升研发效率的首选。
如果你正在开发项目，不妨试试其极其友好的界面设计，它完全兼容 Postman 和 Swagger 数据格式，导入数据非常方便，，即使是新手也能很快上手，点击这里即可注册使用。
值得一提的是，除了个人和常规团队使用，针对有高安全合规要求、或需要在内网环境协作的企业，Apifox 还提供了深度定制的私有化部署方案。
获取专属报价与部署方案
详细的私有化部署系统架构与安全白皮书
针对您公司规模的专属报价单
免费的 1v1 专属产品演示 (Demo) 机会
