## AI 助手 (`ai`)

接入大模型的设置与测试连接、模型评分表、可用状态与额度、会话记录、助手外观。

鉴权: 用户 · 文档: https://www-demo.kuxitong.com/zh/docs/api/ai

### GET `/api/v2/ai/conversations`

列出我的 AI 会话 · 鉴权: 用户

```sh
curl "https://panel.example.com/api/v2/ai/conversations" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### GET `/api/v2/ai/conversations/{id}`

获取我的 AI 会话 · 鉴权: 用户

```sh
curl "https://panel.example.com/api/v2/ai/conversations/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### DELETE `/api/v2/ai/conversations/{id}`

删除我的 AI 会话 · 鉴权: 用户

```sh
curl -X DELETE "https://panel.example.com/api/v2/ai/conversations/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### GET `/api/v2/ai/look`

获取我的助手外观 · 鉴权: 用户

```sh
curl "https://panel.example.com/api/v2/ai/look" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### PUT `/api/v2/ai/look`

保存我的助手外观 · 鉴权: 用户

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `name` | string | 有 | 助手名;空 = 用缺省名。 |
| `pet` | AiPet | 有 | 助手形象:orb 光球、cat 猫、dog 狗、bot 机器人、ai 按 AI 定制的参数(spec)画。 可选值: ["orb","cat","dog","bot","ai"] |
| `spec` | AiLookSpec |  | AI 定制形象的参数清单(白名单内的取值,面板用固定的 SVG 部件按它画)。AiLook 里没有 = 没定制过。 写外观时 pet=ai 或 theme=custom 必须带上(code=required),不带则沿用已存的那份;服务端按同一白名单再核并规整(颜色转小写、主色压暗到白字看得清)。 |
| `theme` | AiTheme | 有 | 助手主题色:蓝、青、日落、莫兰迪、墨色,custom 取 AI 定制参数(spec)里的三色。只作用于助手面板自己。 可选值: ["blue","teal","sunset","morandi","ink","custom"] |

```sh
curl -X PUT "https://panel.example.com/api/v2/ai/look" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### GET `/api/v2/ai/look/avatar`

取我上传的助手头像 · 鉴权: 用户

```sh
curl "https://panel.example.com/api/v2/ai/look/avatar" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### PUT `/api/v2/ai/look/avatar`

上传我的助手头像 · 鉴权: 用户

```sh
curl -X PUT "https://panel.example.com/api/v2/ai/look/avatar" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### DELETE `/api/v2/ai/look/avatar`

移除我上传的助手头像 · 鉴权: 用户

```sh
curl -X DELETE "https://panel.example.com/api/v2/ai/look/avatar" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### POST `/api/v2/ai/look/generate`

让 AI 按描述出一份定制形象 · 鉴权: 用户

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `text` | string | 有 | 想要的样子,去掉控制字符与尖括号后最长 60 个字。 |

```sh
curl -X POST "https://panel.example.com/api/v2/ai/look/generate" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### POST `/api/v2/ai/messages`

向 AI 助手发一句话 · 鉴权: 用户

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `context` | AiContext |  | 当前页面上下文:只有页名与打开的那条的 id,数据由服务端现取。首版带详细数据的页:home 首页、attack_logs 攻击记录(ref = 记录 id)、sites 网站列表(ref = 网站 id);其余页只带页名。 |
| `conversation_id` | integer |  | 接着哪段会话说;不带则开新会话(标题取这句的开头)。 |
| `text` | string | 有 | 想要的样子,去掉控制字符与尖括号后最长 60 个字。 |

```sh
curl -X POST "https://panel.example.com/api/v2/ai/messages" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### GET `/api/v2/ai/models`

列出 AI 模型评分表 · 鉴权: 仅管理员

```sh
curl "https://panel.example.com/api/v2/ai/models" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### POST `/api/v2/ai/plans/cancel`

取消 AI 助手的计划 · 鉴权: 用户

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `plan_id` | AiPlanKey | 有 | 计划号(随机,32 位十六进制)。 |

```sh
curl -X POST "https://panel.example.com/api/v2/ai/plans/cancel" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### POST `/api/v2/ai/plans/execute`

执行 AI 助手的计划 · 鉴权: 用户

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `password` | string |  | 当前登录口令。 |
| `plan_id` | AiPlanKey | 有 | 计划号(随机,32 位十六进制)。 |
| `totp_code` | string |  | 动态口令(TOTP)的 6 位当前码;账号须已启用动态口令。 |

```sh
curl -X POST "https://panel.example.com/api/v2/ai/plans/execute" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### POST `/api/v2/ai/plans/revise`

修改 AI 助手计划的参数 · 鉴权: 用户

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `domain` | string | 有 | 网站域名。 |
| `origin` | string | 有 | 源站地址(IP 或域名)。 |
| `plan_id` | AiPlanKey | 有 | 计划号(随机,32 位十六进制)。 |
| `port` | integer | 有 | 回源端口。 |
| `upid` | integer | 有 | 用哪份已购套餐(须属计划的属主租户)。 |

```sh
curl -X POST "https://panel.example.com/api/v2/ai/plans/revise" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### GET `/api/v2/ai/plans/{plan_id}`

获取 AI 助手的计划 · 鉴权: 用户

```sh
curl "https://panel.example.com/api/v2/ai/plans/{plan_id}" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### GET `/api/v2/ai/settings`

获取 AI 助手接入设置 · 鉴权: 仅管理员

```sh
curl "https://panel.example.com/api/v2/ai/settings" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### PUT `/api/v2/ai/settings`

保存 AI 助手接入设置 · 鉴权: 仅管理员

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `api_key` | string |  | API 密钥;不传沿用已存的,传空串清掉(助手随之不可用)。只封存入库,不回显。 |
| `api_type` | AiApiType | 有 | 接口类型:openai 为 OpenAI 兼容(/chat/completions,国内多数服务商也走它);claude 为 Anthropic 原生(/messages);moonshot 为 Kimi(OpenAI 兼容,预设地址不同)。 可选值: ["openai","claude","moonshot"] |
| `base_url` | string |  | 服务地址(公网 HTTPS);从没保存过为空。 |
| `model` | string | 有 | 模型名。 |

```sh
curl -X PUT "https://panel.example.com/api/v2/ai/settings" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### POST `/api/v2/ai/settings/probe`

测试 AI 助手连接 · 鉴权: 仅管理员

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `api_key` | string |  | API 密钥;不传沿用已存的,传空串清掉(助手随之不可用)。只封存入库,不回显。 |
| `api_type` | AiApiType | 有 | 接口类型:openai 为 OpenAI 兼容(/chat/completions,国内多数服务商也走它);claude 为 Anthropic 原生(/messages);moonshot 为 Kimi(OpenAI 兼容,预设地址不同)。 可选值: ["openai","claude","moonshot"] |
| `base_url` | string |  | 服务地址(公网 HTTPS);从没保存过为空。 |
| `model` | string | 有 | 模型名。 |

```sh
curl -X POST "https://panel.example.com/api/v2/ai/settings/probe" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### GET `/api/v2/ai/status`

获取 AI 助手可用状态 · 鉴权: 用户

```sh
curl "https://panel.example.com/api/v2/ai/status" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

AI 助手对象:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `api_key` | string |  | API 密钥;不传沿用已存的,传空串清掉(助手随之不可用)。只封存入库,不回显。 |
| `api_type` | AiApiType |  | 接口类型:openai 为 OpenAI 兼容(/chat/completions,国内多数服务商也走它);claude 为 Anthropic 原生(/messages);moonshot 为 Kimi(OpenAI 兼容,预设地址不同)。 可选值: ["openai","claude","moonshot"] |
| `available` | boolean |  | 是否显示并可用助手;代登录会话为 true 但只读(reason=delegated)。 |
| `avatar_ver` | integer |  | 头像版本;0 = 没传头像(显示所选形象),大于 0 时用 GET /ai/look/avatar 取图,换图后变大。 |
| `base_url` | string |  | 服务地址(公网 HTTPS);从没保存过为空。 |
| `cert_id` | integer |  | 申请的证书。 |
| `cname` | string |  | 建站响应给的接入名;等解析时让用户把域名 CNAME 到它。 |
| `code` | string |  | 失败细分:blocked 地址被拒(内网等)、auth 密钥被拒、rate_limited 上游限流、timeout 超时、refused 模型拒答、protocol 回包格式不对、http 其他状态码、connect 连不上。 |
| `connect_ms` | integer |  | 连通耗时毫秒(最近一次请求)。 |
| `context` | AiContext |  | 当前页面上下文:只有页名与打开的那条的 id,数据由服务端现取。首版带详细数据的页:home 首页、attack_logs 攻击记录(ref = 记录 id)、sites 网站列表(ref = 网站 id);其余页只带页名。 |
| `conversation_id` | integer |  | 接着哪段会话说;不带则开新会话(标题取这句的开头)。 |
| `created_at` | string |  | 创建时刻。 |
| `detail` | string |  | 给管理员看的说明(含上游错误摘要,不含密钥)。 |
| `domain` | string | 有 | 网站域名。 |
| `error` | string |  | 失败原因。 |
| `expires_at` | string |  | 过了不能再执行。 |
| `fetched_on` | string |  | 取数日期。 |
| `first_token_ms` | integer |  | 已跑各轮里最慢的首字毫秒。 |
| `high_risk` | boolean |  | 执行前要当场复核本人。 |
| `id` | integer |  | 会话 id。 |
| `items` | AiConversation[] |  | 会话(不带消息)。 |
| `key_set` | boolean |  | 是否已设置 API 密钥(密钥本身不回显)。 |
| `kind` | AiPlanKind |  | create_site 新增网站(先只开 HTTP,加好解析后再申请证书);delete_site 删除网站(高危,执行前复核本人)。 可选值: ["create_site","delete_site"] |
| `messages` | AiMessage[] |  | 全部消息(只在获取单个会话时有)。 |
| `model` | string |  | 模型名。 |
| `name` | string |  | 助手名;空 = 用缺省名。 |
| `ok` | boolean |  | 是否通过。 |
| `origin` | string | 有 | 源站地址(IP 或域名)。 |
| `outdated` | boolean |  | 取数超过 90 天,面板提示「评分可能过时」。 |
| `params` | AiPlanParams |  | 冻结的计划参数。新增网站有 domain、origin、port、upid、package(管理员代建另有 tenant_id);删除网站有 site_id,site_name 与 domains 给人核对。 |
| `password` | string |  | 当前登录口令。 |
| `pet` | AiPet |  | 助手形象:orb 光球、cat 猫、dog 狗、bot 机器人、ai 按 AI 定制的参数(spec)画。 可选值: ["orb","cat","dog","bot","ai"] |
| `plan_id` | AiPlanKey | 有 | 计划号(随机,32 位十六进制)。 |
| `port` | integer | 有 | 回源端口。 |
| `probe_first_token_ms` | integer |  | 探测 3 轮里最慢的首字毫秒;没通过为 0。 |
| `probe_ok` | boolean |  | 保存时探测是否通过;换模型或密钥后清零。 |
| `probe_round_ms` | integer |  | 探测 3 轮里最慢的整轮毫秒;没通过为 0。 |
| `probed_at` | string |  | 探测通过的时刻;没通过为 null。 |
| `ready` | boolean |  | 设置是否可用(有密钥、有模型且探测通过);授权另判,见 /ai/status。 |
| `reason` | string |  | 不可用的原因:unlicensed 没开通;expired 授权已过期;not_configured 管理员还没接好模型;delegated 代登录会话(仅 available=true 时出现,只读不能发送);demo 演示模式。 可选值: ["unlicensed","expired","not_configured","delegated","demo"] |
| `reauth_methods` | AiReauthMethod[] |  | 高危计划可用的复核方式;不高危为空。 |
| `revoking_until` | string |  | 服务商已收回授权时,此刻前照常可用。 |
| `round_ms` | integer |  | 已跑各轮里最慢的整轮毫秒。 |
| `rounds` | integer |  | 跑完的轮数(通过时为 3)。 |
| `site_id` | integer |  | 建好的网站。 |
| `spec` | AiLookSpec |  | AI 定制形象的参数清单(白名单内的取值,面板用固定的 SVG 部件按它画)。AiLook 里没有 = 没定制过。 写外观时 pet=ai 或 theme=custom 必须带上(code=required),不带则沿用已存的那份;服务端按同一白名单再核并规整(颜色转小写、主色压暗到白字看得清)。 |
| `state` | AiPlanState |  | proposed 待执行;running 执行中;wait_dns 网站已建、等用户加解析(再执行即申请证书);done 完成;failed 失败(见 error);cancelled 已取消;superseded 已被改参数后的新计划取代。 可选值: ["proposed","running","wait_dns","done","failed","cancelled","superseded"] |
| `step` | string |  | 没通过时停在哪一步:connect 连不上或上游报错;tool 没按格式调用工具报数;echo 复述不对;first_token 首字超时;round 整轮超时。 可选值: ["connect","tool","echo","first_token","round"] |
| `text` | string | 有 | 想要的样子,去掉控制字符与尖括号后最长 60 个字。 |
| `theme` | AiTheme |  | 助手主题色:蓝、青、日落、莫兰迪、墨色,custom 取 AI 定制参数(spec)里的三色。只作用于助手面板自己。 可选值: ["blue","teal","sunset","morandi","ink","custom"] |
| `title` | string |  | 标题(首条提问的开头)。 |
| `totp_code` | string |  | 动态口令(TOTP)的 6 位当前码;账号须已启用动态口令。 |
| `updated_at` | string |  | 最后一条消息时刻(保留期按它算)。 |
| `upid` | integer | 有 | 用哪份已购套餐(须属计划的属主租户)。 |
| `usage` | object |  | 本人生成后的用量与额度(本次已计入)。 |
| `version` | string |  | 评分口径版本。 |