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,
}
+9
View File
@@ -417,6 +417,15 @@ ck " 不存在的 slug 探测 → 404" 404 "$(code -b "$JAR" -X POST \
ck "★用量统计按 api/<slug> 归组(与 LLM 上游天然分开)" yes \
"$(curl -s -b "$JAR" $API/api/admin/usage | has '"slot": *"api/search"')"
ck "★趋势含 api/<slug> 维度" yes "$(curl -s -b "$JAR" "$API/api/admin/trend?days=7" | has '"slot": *"api/search"')"
ck "★usage_hint 写入与回显(1.0.22 能力目录 hint)" yes \
"$(curl -s -b "$JAR" -X POST $API/api/admin/apix/save \
-H 'Content-Type: application/json' \
-d "$(jbody slug med asset_id asset_26476ef1-4687-45 usage_hint 'POST /<tail> multipart fields=[file]; POST /<tail>/base64 json {image_base64:string}')" >/dev/null; \
curl -s -b "$JAR" $API/api/admin/apix | "$PY" -c '
import sys, json
d = json.load(sys.stdin)
it = next((x for x in d["data"]["items"] if x["slug"] == "med"), None)
print("yes" if it and "POST /<tail>" in it.get("usage_hint","") else "no")')"
echo
echo "【11.6】★ API 代理透传模式(/apixp/<slug>/<尾部> → 内部 REST 服务)"
+4
View File
@@ -26,6 +26,10 @@
<span class="badge" style="background:#eef6ee;color:#3a7">passthrough</span>
透传内部 REST 服务(OCR / 文生图 / TTS),访问 <code>/apixp/&lt;slug&gt;/&lt;路径尾部&gt;</code>,
方法/请求体/Content-Type 原样转发,上游路径 = base + 尾部。
<br><br>
<b>调用语法提示(<code>usage_hint</code>)</b>:
passthrough 推荐填写一段机器可读文本,由 <code>GET /api/v1/me</code> 下发给用户 AI,
让 AI <b>自己拼出</b>调用语法(路径尾部/Content-Type/字段名/Swagger),不用看文档。
</div>
</div>
<button class="btn-primary btn-sm" id="newApixBtn">+ 新建代理</button>
+5 -1
View File
@@ -35,12 +35,14 @@
'<input id="axParams" class="field-mono" type="text" placeholder="q" value="' + IP.esc(it ? IP.arr(it.params).join(",") : "") + '"></div>' +
'<div class="span-all"><label>说明</label>' +
'<input id="axDesc" type="text" placeholder="可选" value="' + IP.esc(it ? it.desc : "") + '"></div>' +
'<div class="span-all"><label>调用语法提示(usage_hint · passthrough 推荐填)</label>' +
'<textarea id="axUsageHint" class="field-mono" rows="5" placeholder="POST /<tail> multipart, fields=[file]&#10;POST /<tail>/base64 json, {image_base64:string}&#10;POST /<tail>/url?url= json, {}&#10;Swagger: http://192.168.1.11:9003/docs">' + IP.esc(it ? it.usage_hint || "" : "") + '</textarea></div>' +
'<div class="span-all checkbox"><label style="margin:0"><input type="checkbox" id="axEnabled" ' + ((!edit || it.enabled) ? "checked" : "") + '> 启用</label></div>' +
(pt
? '<div class="span-all muted" style="font-size:11.5px;border-left:3px solid #6a8;padding:6px 10px;background:rgba(0,128,0,0.04)">' +
'💡 <b>passthrough</b>:调用方走 <code>/apixp/' + IP.esc(it ? it.slug : "&lt;slug&gt;") + '/&lt;尾部&gt;</code>,上游路径 = base + 尾部,' +
'方法/请求体/Content-Type 原样转发。OCR 类的 multipart/form-data 也能透传。' +
'「测试」按钮会 GET 打上游根地址验连通性。' +
'「测试」按钮会 GET 打上游根地址验连通性。<b>usage_hint</b> 会原样通过 <code>/api/v1/me</code> 下发给用户 AI。' +
'</div>'
: '') +
'</form>';
@@ -83,6 +85,8 @@
key: card.querySelector("#axKey").value.trim(),
desc: card.querySelector("#axDesc").value.trim(),
params: card.querySelector("#axParams").value.trim(),
note: card.querySelector("#axNote") ? card.querySelector("#axNote").value.trim() : "",
usage_hint: card.querySelector("#axUsageHint").value,
enabled: card.querySelector("#axEnabled").checked
}).then(function (r) { IP.toast(r.msg); close(); return IP.reload(); })
.catch(function (err) { IP.toast(err.message, true); });