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 条)
This commit is contained in:
admin committed 2026-09-15 11:30:16 +08:00
1 parent d05ebfb5b0
commit 26a0f2f4f4
6 files changed
+60 -2

No files matched your search

+7 -1
View File
@@ -103,12 +103,18 @@ fn h_admin_apix_save(r: *mut ngx_http_request_t, _actor: Actor) -> Status {
params,
enabled,
p.get("note"),
p.get("usage_hint"),
) {
Ok(item) => {
util::log_notice(&format!("[api] 保存 API 代理 {slug} → {asset} (mode={})", item.mode));
http::ok(
r,
json!({ "slug": slug, "asset_id": item.asset_id, "mode": item.mode }),
json!({
"slug": slug,
"asset_id": item.asset_id,
"mode": item.mode,
"usage_hint": item.usage_hint,
}),
"已保存",
)
}
+16
View File
@@ -592,6 +592,7 @@ pub fn upsert(
params: Option<Vec<String>>,
enabled: bool,
note: Option<&String>,
usage_hint_raw: Option<&String>,
) -> Result<ApiProxy, String> {
let slug = validate_slug(slug_raw)?;
@@ -692,6 +693,19 @@ pub fn upsert(
Some(n) => util::trim(n).to_owned(),
None => existing.as_ref().map(|e| e.note.clone()).unwrap_or_default(),
};
let usage_hint = match usage_hint_raw {
Some(h) => {
let h = util::trim(h);
if h.is_empty() {
String::new()
} else {
// 截断到 1KB(够写 3-5 个端点说明)。机器可读文本通常几十到几百字节,
// 给 4 倍冗余。过长截断而非拒绝——管理员可以粘贴 Swagger 长片段。
h.chars().take(1024).collect()
}
}
None => existing.as_ref().map(|e| e.usage_hint.clone()).unwrap_or_default(),
};
let params = match params {
Some(p) => p,
None => existing.as_ref().map(|e| e.params.clone()).unwrap_or_default(),
@@ -713,6 +727,7 @@ pub fn upsert(
params,
enabled,
note,
usage_hint,
created_at,
};
data.items.insert(key.clone(), item.clone());
@@ -759,6 +774,7 @@ pub fn view(slug: &str, item: &ApiProxy, port: &str) -> Value {
"key_set": !item.key.is_empty(),
"key_mask": if item.key.is_empty() { "-".to_owned() } else { util::mask_key(&item.key) },
"note": item.note,
"usage_hint": item.usage_hint,
"created_at": item.created_at,
"created_at_text": util::fmt_time(item.created_at),
"url": call_url(slug, port, &item.mode),
+19
View File
@@ -67,6 +67,25 @@ pub struct ApiProxy {
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,
}