random-api

通过配置把 HTTP API 映射成群聊斜杠命令，并将响应中的文本或图片发送到群里。

配置文件

安装插件并执行 erii reload 后，编辑：

plugins/config/random-api.json

修改配置后依次执行：

erii reload
erii refresh
erii plugin refresh random-api

也可以重启 Erii 使配置生效。

cmd、action 和 alias

cmd 是插件的一级命令，action.name 是一级命令下的具体操作，action.aliases 是直接调用该 action 的快捷命令。

{
  "cmd": "api",
  "actions": [
    {
      "name": "cat",
      "aliases": [
        "猫图"
      ]
    }
  ]
}

对应关系：

| 用户输入 | 解析结果 | |------------|----------------------------------| | /api cat | cmd=api，action=cat | | /猫图 | 通过 alias 直接调用 action=cat | | /api | 显示 action 使用说明 |

一个插件只有一个 cmd，但可以配置多个 action：

/api cat
/api weather 上海
/api search 关键词

最小示例

下面的配置提供 /random-api cat 和 /猫图 两种调用方式：

{
  "cmd": "random-api",
  "timeout-ms": 15000,
  "max-redirects": 5,
  "max-response-bytes": 10485760,
  "max-resource-bytes": 10485760,
  "max-resources": 3,
  "max-text-chars": 4000,
  "actions": [
    {
      "name": "cat",
      "aliases": [
        "猫图"
      ],
      "description": "获取一张随机猫图",
      "request": {
        "method": "GET",
        "url": "https://api.thecatapi.com/v1/images/search",
        "query": {
          "limit": "1"
        },
        "use-proxy": false
      },
      "response": {
        "type": "json",
        "text-paths": [],
        "resource-paths": [
          "$[0].url"
        ],
        "resource-kind": "image",
        "empty-message": "没有获取到猫图"
      },
      "send": {
        "text": {
          "enabled": false
        },
        "resource": {
          "enabled": true
        },
        "order": [
          "resource"
        ]
      }
    }
  ]
}

完整结构

{
  "cmd": "api",
  "timeout-ms": 15000,
  "max-redirects": 5,
  "max-response-bytes": 10485760,
  "max-resource-bytes": 10485760,
  "max-resources": 3,
  "max-text-chars": 4000,
  "actions": [
    {
      "name": "generate",
      "aliases": [
        "生成"
      ],
      "description": "根据提示词生成内容",
      "placeholders": [
        {
          "name": "prompt",
          "description": "生成提示词",
          "required": true,
          "source": "rest",
          "position": 0,
          "llm": {
            "enabled": false
          }
        },
        {
          "name": "style",
          "description": "生成风格",
          "default": "natural",
          "required": false,
          "source": "named",
          "llm": {
            "enabled": false
          }
        }
      ],
      "request": {
        "method": "POST",
        "base-url": "https://example.com",
        "path": "/v1/generate",
        "headers": {
          "Authorization": "Bearer your-api-key"
        },
        "query": {
          "format": "json"
        },
        "body": {
          "prompt": "{prompt}",
          "style": "{style}"
        },
        "content-type": "application/json",
        "use-proxy": false
      },
      "response": {
        "type": "json",
        "text-paths": [
          "$.message"
        ],
        "resource-paths": [
          "$.imageUrl"
        ],
        "resource-kind": "image",
        "empty-message": "API 没有返回可发送内容"
      },
      "send": {
        "text": {
          "enabled": true
        },
        "resource": {
          "enabled": true
        },
        "order": [
          "text",
          "resource"
        ]
      }
    }
  ]
}

调用示例：

/api generate 一只戴着墨镜的猫 style=cartoon
/生成 一只戴着墨镜的猫 style=cartoon

最终请求体：

{
  "prompt": "一只戴着墨镜的猫",
  "style": "cartoon"
}

全局配置

| 字段 | 默认值 | 说明 | |----------------------|-------------:|----------------------------------------| | cmd | random-api | 一级命令名，不包含 /，不能包含空白 | | timeout-ms | 15000 | 单次连接、请求和读取超时，单位毫秒 | | max-redirects | 5 | API 请求和图片下载允许的最大重定向次数 | | max-response-bytes | 10485760 | API 响应体大小上限 | | max-resource-bytes | 10485760 | 单张图片大小上限 | | max-resources | 3 | 一次命令最多发送的图片数量 | | max-text-chars | 4000 | 一次命令最多发送的文本字符数 | | actions | [] | API action 列表 |

max-response-bytes 和 max-resource-bytes 最大允许配置为 100 MiB。非 2xx HTTP 响应会被视为调用失败。

Action 配置

| 字段 | 必填 | 说明 | |----------------|------|-----------------------------------------------| | name | 是 | action 名称，例如 cat；在 /api cat 中使用 | | aliases | 否 | 直接调用该 action 的斜杠命令，例如 /猫图 | | description | 否 | action 说明，也会作为 LLM 参数提取上下文 | | placeholders | 否 | 命令参数定义 | | request | 是 | HTTP 请求定义 | | response | 否 | 响应提取规则 | | send | 否 | 文本和图片发送规则 |

action 名称不能重复；alias 不区分大小写且不能重复，也不能与一级 cmd 相同。

占位符

占位符可以用于 URL、path、header、query 和 body 中的字符串：

{
  "url": "https://example.com/users/{userId}",
  "headers": {
    "X-Token": "{token}"
  },
  "query": {
    "keyword": "{keyword}"
  },
  "body": {
    "prompt": "{prompt}"
  }
}

模板引用的占位符如果没有解析出值，请求会直接失败，不会把 {name} 原样发送给上游。

占位符字段

| 字段 | 默认值 | 说明 | |---------------|---------|--------------------------------------------------------------| | name | 无 | 占位符名称，只支持字母、数字、下划线和短横线，不能以数字开头 | | description | 空 | 参数说明，启用 LLM 时作为提取上下文 | | default | 无 | 没有输入值时使用的默认值 | | required | false | 是否必填 | | source | auto | 参数读取方式：auto、named、position 或 rest | | position | 无 | 从 0 开始的位置参数索引 | | llm.enabled | false | 缺少必填参数时是否使用 LLM 提取 |

source 读取方式

named 读取 name=value：

{
  "name": "city",
  "required": true,
  "source": "named"
}

/api weather city=上海

position 按位置读取，必须配置 position：

{
  "name": "city",
  "required": true,
  "source": "position",
  "position": 0
}

/api weather 上海

rest 从 position 开始合并剩余参数：

{
  "name": "prompt",
  "required": true,
  "source": "rest",
  "position": 0
}

/api generate 一只 戴着 墨镜的猫

解析结果为：

prompt=一只 戴着 墨镜的猫

auto 按以下顺序读取：

1. 同名的 name=value 参数。
2. 配置了 position 时读取对应位置参数。
3. action 只有一个占位符时，合并全部位置参数。
4. 使用 default。

已识别的 name=value 参数不会占用位置参数索引。

LLM 参数提取

只有同时满足以下条件才会调用 LLM：

• 占位符设置了 required: true。
• 普通参数解析后仍然缺失。
• 设置了 llm.enabled: true。

示例：

{
  "placeholders": [
    {
      "name": "city",
      "description": "城市名称",
      "required": true,
      "source": "auto",
      "llm": {
        "enabled": true
      }
    },
    {
      "name": "date",
      "description": "日期，例如今天、明天或 YYYY-MM-DD",
      "required": true,
      "source": "auto",
      "llm": {
        "enabled": true
      }
    }
  ],
  "request": {
    "method": "GET",
    "url": "https://example.com/weather",
    "query": {
      "city": "{city}",
      "date": "{date}"
    }
  }
}

/api weather 帮我看看上海明天的天气

LLM 只能填写当前缺失且允许 LLM 提取的占位符，不会覆盖用户已经明确提供的值。

Request 配置

| 字段 | 默认值 | 说明 | |----------------|--------------------|------------------------------------------------------| | method | GET | 支持 GET、POST、PUT、PATCH、DELETE、HEAD | | url | 无 | 完整请求 URL；设置后优先于 base-url 和 path | | base-url | 无 | API 基础 URL | | path | 无 | 与 base-url 拼接的路径 | | headers | {} | 请求头 | | query | {} | Query 参数 | | body | 无 | 字符串、对象或数组请求体 | | content-type | application/json | 请求体 Content-Type | | use-proxy | false | 是否使用 Erii 配置的代理 HTTP 客户端 |

必须配置 url，或者同时使用 base-url 与可选的 path。

插件只允许 HTTP 和 HTTPS URL。HTTPS 请求不会重定向到 HTTP；跨域重定向时会移除 Authorization、Cookie 和 Proxy-Authorization。

Response 配置

| 字段 | 默认值 | 说明 | |------------------|-----------------------------|---------------------------------------------| | type | auto | json、xml、text、resource 或 auto | | text-paths | [] | 需要提取并发送的文本路径 | | resource-paths | [] | 需要提取并发送的图片 URL 或 Base64 路径 | | resource-kind | image | 当前只支持 image | | empty-message | 没有从 API 返回可发送内容 | 没有提取到内容时发送的文本 |

不同响应类型的路径规则：

| type | 提取方式 | |------------|-----------------------------------------------------------------| | json | text-paths 和 resource-paths 使用 JSONPath | | xml | text-paths 和 resource-paths 使用 XPath | | text | 不配置 text-paths 时发送完整文本；配置时使用 $ 表示完整文本 | | resource | 未配置 resource-paths 时，将完整响应体作为图片 | | auto | 根据响应 Content-Type 自动判断 JSON、XML、文本或资源 |

JSONPath 指向的可选字段不存在时会被忽略。JSON 或 XML 响应格式错误仍会导致调用失败。

图片字段支持以下值：

https://example.com/image.png
base64://iVBORw0KGgo...
data:image/png;base64,iVBORw0KGgo...
iVBORw0KGgo...

URL 图片会由插件下载后发送，并受超时、重定向和图片大小限制。

Send 配置

{
  "send": {
    "text": {
      "enabled": true
    },
    "resource": {
      "enabled": true
    },
    "order": [
      "text",
      "resource"
    ]
  }
}

order 决定发送顺序，只能包含 text 和 resource，不能重复。启用的输出类型必须出现在 order 中，文本和图片不能同时禁用。

只发送文本：

{
  "send": {
    "text": {
      "enabled": true
    },
    "resource": {
      "enabled": false
    },
    "order": [
      "text"
    ]
  }
}

只发送图片：

{
  "send": {
    "text": {
      "enabled": false
    },
    "resource": {
      "enabled": true
    },
    "order": [
      "resource"
    ]
  }
}

常见问题

为什么配置了 action 后还有 cmd

cmd 用于把多个 API action 放在同一个命令命名空间下：

/api cat
/api dog
/api weather

如果只配置一个 action，可以给它设置 alias，让用户直接调用：

/猫图

修改 cmd 后命令没有变化

确认已经依次刷新配置缓存和插件生命周期：

erii reload
erii refresh
erii plugin refresh random-api

返回了 JSON，但没有发送任何内容

检查：

1. response.type 是否为 json 或 auto。
2. text-paths 或 resource-paths 是否为正确的 JSONPath。
3. 对应输出是否在 send 中启用并包含在 order 中。

图片发送失败

检查：

1. 图片 URL 是否为 HTTP 或 HTTPS。
2. URL 响应 Content-Type 是否为 image/*。
3. 图片是否超过 max-resource-bytes。
4. Base64 数据是否完整且不包含无效字符。