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:
1 parent
d05ebfb5b0
commit
26a0f2f4f4
6 files changed
+60
-2
No files matched your search
@@ -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,
|
||||
}),
|
||||
"已保存",
|
||||
)
|
||||
}
|
||||
|
||||
@@ -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),
|
||||
|
||||
@@ -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,
|
||||
}
|
||||
|
||||
@@ -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 服务)"
|
||||
|
||||
@@ -26,6 +26,10 @@
|
||||
<span class="badge" style="background:#eef6ee;color:#3a7">passthrough</span>
|
||||
透传内部 REST 服务(OCR / 文生图 / TTS),访问 <code>/apixp/<slug>/<路径尾部></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
@@ -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] POST /<tail>/base64 json, {image_base64:string} POST /<tail>/url?url= json, {} 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 : "<slug>") + '/<尾部></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); });
|
||||
|
||||
Reference in new issue
Block a user