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 生成分享链接（编码）

构造原始 URL：以基础方案（如 https）、主机、路径及查询参数组成 URL，确保所有参数值已进行 URL 百分比编码。
提取负载部分：定位首个 :// 结束位置，取出其后的全部字符（即路径、查询和片段）。
十六进制编码：将该字符串按字节转换为小写十六进制序列。
拼装 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 解析分享链接（解码）

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

5. 安全与隐私考量

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

6. 实现参考

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

Markdown 格式