diff --git a/rust/crates/plugin-apix/src/api.rs b/rust/crates/plugin-apix/src/api.rs index 41369fd..3821543 100644 --- a/rust/crates/plugin-apix/src/api.rs +++ b/rust/crates/plugin-apix/src/api.rs @@ -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, + }), "已保存", ) } diff --git a/rust/crates/plugin-apix/src/apix.rs b/rust/crates/plugin-apix/src/apix.rs index 2e3fbb3..b4fded5 100644 --- a/rust/crates/plugin-apix/src/apix.rs +++ b/rust/crates/plugin-apix/src/apix.rs @@ -592,6 +592,7 @@ pub fn upsert( params: Option>, enabled: bool, note: Option<&String>, + usage_hint_raw: Option<&String>, ) -> Result { 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), diff --git a/rust/crates/plugin-apix/src/models.rs b/rust/crates/plugin-apix/src/models.rs index 7cebb38..4e93966 100644 --- a/rust/crates/plugin-apix/src/models.rs +++ b/rust/crates/plugin-apix/src/models.rs @@ -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 / multipart, fields=[file]; OCR 上传图片 + /// POST //base64 json, {image_base64:string} + /// POST //url?url= json, {} + /// Swagger: http://192.168.1.11:9003/docs + /// ``` + #[serde(default)] + pub usage_hint: String, #[serde(default)] pub created_at: i64, } diff --git a/tests/llm/e2e.sh b/tests/llm/e2e.sh index ba0c8ac..8d946cb 100755 --- a/tests/llm/e2e.sh +++ b/tests/llm/e2e.sh @@ -417,6 +417,15 @@ ck " 不存在的 slug 探测 → 404" 404 "$(code -b "$JAR" -X POST \ ck "★用量统计按 api/ 归组(与 LLM 上游天然分开)" yes \ "$(curl -s -b "$JAR" $API/api/admin/usage | has '"slot": *"api/search"')" ck "★趋势含 api/ 维度" 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 / multipart fields=[file]; POST //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 /" in it.get("usage_hint","") else "no")')" echo echo "【11.6】★ API 代理透传模式(/apixp//<尾部> → 内部 REST 服务)" diff --git a/www/apix.html b/www/apix.html index 8b70758..446d418 100644 --- a/www/apix.html +++ b/www/apix.html @@ -26,6 +26,10 @@ passthrough 透传内部 REST 服务(OCR / 文生图 / TTS),访问 /apixp/<slug>/<路径尾部>, 方法/请求体/Content-Type 原样转发,上游路径 = base + 尾部。 +

+ 调用语法提示(usage_hint): + passthrough 推荐填写一段机器可读文本,由 GET /api/v1/me 下发给用户 AI, + 让 AI 自己拼出调用语法(路径尾部/Content-Type/字段名/Swagger),不用看文档。 diff --git a/www/assets/apix.js b/www/assets/apix.js index af2fc5b..b6c769c 100644 --- a/www/assets/apix.js +++ b/www/assets/apix.js @@ -35,12 +35,14 @@ '' + '
' + '
' + + '
' + + '
' + '
' + (pt ? '
' + '💡 passthrough:调用方走 /apixp/' + IP.esc(it ? it.slug : "<slug>") + '/<尾部>,上游路径 = base + 尾部,' + '方法/请求体/Content-Type 原样转发。OCR 类的 multipart/form-data 也能透传。' + - '「测试」按钮会 GET 打上游根地址验连通性。' + + '「测试」按钮会 GET 打上游根地址验连通性。usage_hint 会原样通过 /api/v1/me 下发给用户 AI。' + '
' : '') + ''; @@ -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); });