Files
ssw__ipass/rust/crates/plugin-apix/src/models.rs
T
admin 26a0f2f4f4 feat(apix): usage_hint 字段 —— /api/v1/me 帮用户 AI 自动发现调用语法 (1.0.22)
`desc` 是中文给运维看的,`params` 只对 vendor 有意义(passthrough 是空数组)。
`/api/v1/me` 把条目下发给用户 AI 后,AI 必须能自己拼出:
- 路径尾部是什么(/ocr /ocr/base64 /ocr/url)
- 每个端点的 Content-Type(multipart 还是 json)
- 上游字段名 / Swagger 在哪

加 `usage_hint` 字段:管理员按 OpenAPI 风格填写自由格式,由 /api/v1/me
原样透传给用户 AI。AI 直接解析,无需再读人工文档。

设计要点:
- 不进 shm(热路径只查 base/key/asset_id/mode,进 shm 占带宽)
- 截断到 1KB(够写 3-5 个端点说明,长 Swagger 截断而非拒绝)
- 默认空字符串,向后兼容旧数据
- passthrough 推荐填,vendor 可选填

改动:
- models.rs: ApiProxy 加 usage_hint 字段
- apix.rs: upsert 收 usage_hint_raw + 截断;view 回显
- api.rs: save 解析 usage_hint;响应回显
- www/apix.html: 描述加 usage_hint 解释
- www/assets/apix.js: 表单加 textarea + 提交带 usage_hint
- tests/llm/e2e.sh: §11.5 加 1 条 usage_hint 写入与回显断言
- 回归 227/0 全绿(修复断言 1 条)
2026-09-15 11:30:16 +08:00

101 lines
4.4 KiB
Rust
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
//! API 代理持久化模型(`api-proxies.json`:以 slug 为 key)。
//!
//! 字段名与旧版 `data/api-proxies.json` **逐字对应**,以便新版直接接管旧数据文件。
use serde::{Deserialize, Serialize};
use std::collections::BTreeMap;
/// API 代理表(`api-proxies.json`)。
///
/// 与 `llm-upstreams.json` 同构:每条记录 = 一个供应商(自带基址与密钥),
/// 由 `slug` 区分。调用方访问 `/apix/<slug>?参数=值`,网关用本记录里的密钥
/// 转发到供应商、并把响应原样返回。不同供应商彼此独立、互不耦合。
///
/// `key` 是供应商真 Key,**敏感级别等同 `users.json`**(data/ 已 gitignore)。
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ApiProxyStore {
/// slug → 代理映射
#[serde(default)]
pub items: BTreeMap<String, ApiProxy>,
}
impl Default for ApiProxyStore {
fn default() -> Self {
Self { items: BTreeMap::new() }
}
}
/// 单个 API 代理条目:指向某一家供应商的一个可调用的资产。
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ApiProxy {
/// 供应商侧的资产 id(如 `searxng-search`),决定具体调用哪个资产。
/// **vendor 模式必填**;passthrough 模式用不到(上游路径由 URL 尾部决定),可留空。
pub asset_id: String,
/// 供应商名称(仅展示用,管理员自填,例如 `provider-x` / 客户自定)
#[serde(default)]
pub supplier: String,
/// 供应商基址,如 `https://api.example.com`
#[serde(default)]
pub base: String,
/// 供应商 API Key(`ak_...`)。留空 = 未配置,热路径直接 503。
/// **敏感**:写盘与回显都按密钥处理,管理台只回显掩码。
/// passthrough 模式下若上游不需要鉴权可留空(不下发任何鉴权头)。
#[serde(default)]
pub key: String,
/// 代理模式:
/// - `vendor`(默认):单一供应商收口 `POST {base}/api/v1/ai/request`,
/// 请求体由网关按 `asset_id` 拼装(见 `apix.rs`)。
/// - `passthrough`:透传模式,原样转发客户端的方法/请求体/Content-Type,
/// 上游路径 = `{base} + /apixp/<slug> 之后的 URI 尾部`,用于 OCR / 文生图 /
/// TTS 这类「多端点、多 body、无 asset 市场」的内部 REST 服务。
#[serde(default = "default_mode")]
pub mode: String,
/// 展示名(中文)
#[serde(default)]
pub name: String,
/// 一句话说明
#[serde(default)]
pub desc: String,
/// **声明式参数清单**(如 `["q"]`)。
///
/// 只用于给调用方看的文档(管理台把 `?q=关键词` 拼出来、账号态接口回显),
/// 转发时**不按它过滤**——过滤要靠读请求体,而 access 阶段读不到。
/// 供应商侧自己会拒绝不认识的参数,拦在网关意义不大。
#[serde(default)]
pub params: Vec<String>,
#[serde(default = "default_true")]
pub enabled: bool,
#[serde(default)]
pub note: String,
/// 调用语法提示(**机器可读**的描述字段,专为 passthrough / 复杂 vendor 设计)。
///
/// 为什么需要:`/api/v1/me` 把这条发给用户 AI 后,AI 必须能**自己拼出**调用语法——
/// 路径尾部是什么、什么 Content-Type、上游 Swagger 在哪。`desc` 是中文给运维看的,
/// `params` 只对 vendor 有意义,对 passthrough 是空数组,没法告诉 AI 怎么调。
/// `usage_hint` 是管理员按建议格式(自由文本)填写的结构化提示,AI 直接解析。
///
/// 不进 shm:热路径只查 base/key/asset_id/mode,`usage_hint` 只在管理台 +
/// `/api/v1/me` 拉清单时回显,进 shm 反而占带宽。
///
/// 建议格式(OpenAPI 风格):
/// ```text
/// POST /<tail> multipart, fields=[file]; OCR 上传图片
/// POST /<tail>/base64 json, {image_base64:string}
/// POST /<tail>/url?url=<dst> json, {}
/// Swagger: http://192.168.1.11:9003/docs
/// ```
#[serde(default)]
pub usage_hint: String,
#[serde(default)]
pub created_at: i64,
}
fn default_true() -> bool {
true
}
/// 默认代理模式 = vendor(向后兼容旧数据:没有 `mode` 字段的条目就是 vendor)。
fn default_mode() -> String {
"vendor".to_owned()
}