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,
|
||||
}
|
||||
|
||||
Reference in new issue
Block a user