# ai+ URL 协议规范 - AI 大模型配置分享方案

> 发布日期：2026-05-27  

## 1. 引言

在 aardio 生态中，AI 大模型接口的配置通常包含 API 端点、密钥、模型名称及多项参数。为便于用户在实例间分享与导入配置，本文定义一个基于 URL 的纯文本方案 `ai+`，该方案通过简单的十六进制编码封装完整的接口调用信息，使其可被复制、粘贴及解析。

> aardio 标准库 web.rest.aiChat.settingForm 提供默认的 AI 大模型接口配置界面（ 用于 aardio autos，ImTip  ）。在该界面的配置列表中右键点击列表项，在右键弹出菜单中点击 `复制分享链接`，`粘贴分享链接`使用的就是 `ai+` 格式链接。直接点击配置列表底部的  图标新增配置，也会自动读取剪贴板中的 `ai+` 链接并输入到新增配置。

## 2. 术语与约定

- **`ai+` 方案**：自定义 URI 方案，格式为 `ai+<基础方案>://<编码负载>`。
- **基础方案**：原始 API 端点的方案，如 `https`、`http`。
- **原始 URL**：解码后得到的、包含完整查询参数的合法 URL。
- **负载**：原始 URL 除去方案及 `://` 前缀后的部分，经小写十六进制编码。

## 3. 协议格式

### 3.1 整体结构

```
ai+<基础方案>://<十六进制编码负载>
```

- `<基础方案>` 为实际 API 协议（如 `https`）。
- 使用 `://` 或  `:` 作为标准方案分隔符，`//` 是可选的部分（非必须） 。
- `<十六进制编码负载>` 为原始 URL 除去 `<基础方案>://` 后全部内容的逐字节十六进制表示（使用小写字母，无分隔符）。

### 3.2 原始 URL 格式

解码后的负载必须构成一个合法的 URL，其查询参数携带 AI 接口配置。各参数名按**蛇形命名法**，且值均经过标准 URL 编码。

参数定义如下：

| 参数名 | 类型 | 是否必需 | 说明 | 示例 |
|--------|------|----------|------|------|
| `key` | 字符串 | 建议 | API 密钥 | `sk-xxxxxxx` |
| `model` | 字符串 | 必需 | 模型标识符 | `deepseek-pro` |
| `temperature` | 字符串化的浮点数 | 可选 | 采样温度，0～2 | `0.7` |
| `protocol` | 字符串 | 可选 | 协议，取值：`openai`,`responses`,`anthropic`,`google`,`vertex"` | `responses` |
| `reasoning_effort` | 字符串 | 可选 | 推理强度等级，取值：`auto`、`none`、`low`、`medium`、`high`、`xhigh`、`max` | `high` |
| `extra_body` | URL 编码的 JSON 字符串 | 可选 | 额外的请求体字段，对应 aardio 中的 `extraParameters` 表序列化结果 | `{"thinking":{"type":"enabled"}}` |
| `extra_headers` | URL 编码的 JSON 字符串 | 可选 | 额外的 HTTP 请求头，对应 aardio 中的 `extraHeaders` 表序列化结果 | `{"x-grok-conv-id":"unique_session_id"}` |

## 4. 编码与解码流程

### 4.1 生成分享链接（编码）

1. **构造原始 URL**：以基础方案（如 `https`）、主机、路径及查询参数组成 URL，确保所有参数值已进行 URL 百分比编码。
2. **提取负载部分**：定位首个 `://` 结束位置，取出其后的全部字符（即路径、查询和片段）。
3. **十六进制编码**：将该字符串按字节转换为小写十六进制序列。
4. **拼装 `ai+` URL**：将基础方案替换为 `ai+<基础方案>`，后接 `://` 与上一步的十六进制序列。

> **示例**  
> 假设原始 URL 为 `https://api.example.com/v1?key=sk-abc&model=m1&temperature=0.5`，  
> 负载部分为 `api.example.com/v1?key=sk-abc&model=m1&temperature=0.5`，  
> 十六进制编码后得到：`6170692e6578616d706c652e636f6d2f76313f6b65793d736b2d616263266d6f64656c3d6d312674656d70657261747572653d302e35`，  
> 最终分享链接为：  
> `ai+https://6170692e657861 …（完整十六进制串）`

### 4.2 解析分享链接（解码）

1. **匹配 `ai+` 前缀**：若字符串不以 `ai+` 起始，则拒绝。
2. **分离基础方案与负载**：从 `ai+` 后的字符串中提取直到 `://` 之前的部分作为基础方案（如 `https`），其余为十六进制负载。
3. **解码负载**：将十六进制字符串还原为原始字节序列。
4. **重新组合 URL**：用基础方案添加 `://`，拼接负载，得到完整原始 URL。
5. **提取参数**：使用标准 URL 解析器拆分查询字符串，逐项读出 `key`、`model`、`temperature`、`reasoning_effort`、`extra_body` 等字段，并赋值到当前配置对象。

## 5. 安全与隐私考量

- **密钥以明文形式出现**：虽然负载经过十六进制编码，但这不提供加密保护，仅为基础混淆。任何人可轻易解码还原密钥。因此，分享链接仅适合在受信任环境中传输（除非是临时密钥）。
- **不包含签名与验证**：本协议不提供防篡改机制。接收方应自行判断来源可信度。

## 6. 实现参考

该协议已由 aardio 标准库 [string.aiPlus](../library-reference/string/aiPlus.html) 实现，并用于标准库 `web.rest.aiChat.settingForm` 创建的 AI 接口配置界面（配置项右键菜单里的“复制分享链接”和“粘贴分享链接”）。在 aardio 代码编辑器右键菜单点击 `粘贴与更正` 可识别 ai+ 链接并自动生成调用 API 接口的示例代码。