API7 网关 AI Agent Skill：共享 CLI 约定

什么是 a7

a7 是用于 API7 企业版的 Go CLI 工具。它支持对当前 API7 企业版资源类型执行命令式 CRUD 操作、声明式配置同步、上下文管理以及调试工具。

• 二进制文件：a7
• 模块：github.com/api7/a7
• Go 版本：1.22+
• 命令模式：名词-动词（a7 <resource> <action> [flags]）。
• 双 API 架构：
  • 控制面 API：/api/*（例如网关组）。
  • 运行时 Admin API：/apisix/admin/*（例如路由、服务和消费者）。
• 网关组作用域：所有运行时资源都必须通过 --gateway-group 或 -g 限定在一个网关组中。

项目结构

a7/
├── cmd/a7/main.go                  # 入口
├── pkg/cmd/                        # 命令实现
│   ├── root/root.go                # 根命令，注册所有子命令
│   ├── factory.go                  # 依赖注入：IOStreams、HttpClient、Config
│   ├── route/                      # a7 route list|get|create|update|delete -g <group>
│   ├── service/                    # a7 service ... -g <group>
│   ├── gateway-group/              # a7 gateway-group list|get|create|update|delete
│   ├── consumer/                   # a7 consumer ... -g <group>
│   ├── ssl/                        # a7 ssl ... -g <group>
│   ├── plugin/                     # a7 plugin list|get
│   ├── config/                     # a7 config sync|diff|dump|validate -g <group>
│   └── context/                    # a7 context create|use|list|delete|current
├── pkg/api/                        # API 客户端和类型
│   ├── client.go                   # 使用令牌进行身份认证的 HTTP 封装
│   └── types_*.go                  # 各资源的 Go 结构体（Route、Upstream 等）
├── pkg/iostreams/                  # I/O 抽象（TTY 检测）
├── pkg/cmdutil/                    # 共享工具（错误、导出器、标志）
├── pkg/tableprinter/               # 表格渲染
├── pkg/httpmock/                   # 单元测试用 HTTP 模拟
├── internal/config/                # 上下文和配置文件管理（~/.config/a7/）
├── test/fixtures/                  # 单元测试用 JSON 固定数据
├── test/e2e/                       # E2E 测试（构建标签：e2e）
├── skills/                         # AI Agent Skill 文件
└── docs/                           # 项目文档

架构模式

工厂模式（依赖注入）

每条命令都会接收一个包含 IOStreams、HttpClient() 和 Config() 的 *cmd.Factory，不使用全局状态。

type Factory struct {
    IOStreams   *iostreams.IOStreams
    HttpClient func() (*http.Client, error)
    Config     func() (config.Config, error)
}

Config() 接口提供以下方法：

• Token()：返回身份认证令牌（前缀为 a7ee）。
• GatewayGroup()：返回默认网关组。
• TLSSkipVerify()：返回 TLS 校验设置。
• CACert()：返回自定义 CA 证书路径。

命令模式（Options + NewCmd + Run）

每条命令都遵循相同的结构：

type Options struct {
    IO     *iostreams.IOStreams
    Client func() (*http.Client, error)
    Config func() (config.Config, error)
    GatewayGroup string // 运行时资源必填
    // 命令专用字段
}

func NewCmdXxx(f *cmd.Factory) *cobra.Command { ... }
func xxxRun(opts *Options) error { ... }

身份认证

API7 企业版使用 X-API-KEY 请求头。令牌的前缀为 a7ee。

PATCH 方法

对于使用 PATCH 的 update 操作，a7 支持 JSON Patch（RFC 6902）。

支持的资源类型

资源	关键字段	API 路径（前缀）
网关组	id	/api/gateway_groups
路由	id	/apisix/admin/routes
服务	id	/apisix/admin/services
消费者	username	/apisix/admin/consumers
SSL	id	/apisix/admin/ssl
全局规则	id	/apisix/admin/global_rules
流式路由	id	/apisix/admin/stream_routes
Proto	id	/apisix/admin/protos
Secret	id	/apisix/admin/secrets/{manager}/{id}
插件元数据	plugin_name	/apisix/admin/plugin_metadata/{name}
插件（只读）	name	/apisix/admin/plugins
凭证	id	/apisix/admin/consumers/{username}/credentials

注意：运行时资源（路由、服务、消费者等）始终通过请求 URL 或请求头限定在网关组内。上游以内联方式定义在服务或路由中，而不是作为独立资源。

常用命令

make build          # 构建到 ./bin/a7
make test           # 单元测试
make test-e2e       # E2E 测试（需要 API7 企业版实例）
make lint           # golangci-lint
make fmt            # gofmt
make docker-up      # 启动本地组件栈

配置同步流程

声明式配置系统（a7 config sync/diff/dump/validate）以网关组为作用域：

a7 config sync -f config.yaml --gateway-group default

version: "1"
routes:
  - id: my-route
    name: my-route
    paths:
      - /api/*
    service_id: my-service
services:
  - id: my-service
    name: my-service
    upstream:
      type: roundrobin
      nodes:
        - host: httpbin
          port: 8080
          weight: 1

---

本页面由 api7/a7 仓库中的 a7-shared/SKILL.md 生成。你可以在 AI Agent Skills 页面查看所有技能。