mirror of
https://gitcode.com/JianFeeeee/homeagent-sdk.git
synced 2026-09-25 19:38:06 +00:00
fix(docs): 中文搜不到英文注释的 API —— 补关键词层
## 问题(实测)
SDK 里 100 个有摘要的符号中 **66 个是英文注释**,例如:
RegisterTool registers a tool that the LLM can call.
于是搜「注册工具」——中文受众最自然的问法——**RegisterTool 得分 0,一条都搜不到**。
更糟的是逐字匹配把噪声顶上来了:搜「注册工具」返回 24 条,排第一的是
`SetToolBlocks`(描述里有「工具」二字),`RegisterTool` 根本不在列表里。
## 修法
不改源码注释(那会让代码与文档脱节),而是在检索索引上加一层**人工标注的
中文功能词**:`tools/apidoc/keywords.json`。
- `rules`:按符号名前缀/子串批量覆盖(`Register*` 全带「注册」,`*Memory*` 带「记忆」)
- `symbols`:逐符号补充(重点 API、或规则覆盖不到的)
词只进 `api-index.json` 的 `g` 字段,**不影响页面展示**;检索结果里会显示
(「为何命中」),读者能理解排序依据。
同时把中文逐字匹配从主信号降为**弱信号**(要求 60% 以上字符命中)——
它正是噪声来源:凡是含「工具」二字的说明都会被「注册工具」匹上。
## 结果
| 查询 | 修改前 | 修改后 |
|---|---|---|
| 注册工具 | 24 条,RegisterTool 缺席 | **7 条,RegisterTool 第一** |
| 崩溃 | 1 条 | 2 条(SetAutoRestart + AutoRestart)|
| InjectText | 7 条(含重复)| 6 条 |
| memory.recall | 1 条 | 1 条(不变)|
顺带修掉索引重复:接口会同时作为 `type` 符号与接口本身被加两次
(`MemoryAPI` 等 11 个各重复一条)。现在接口只走接口那条路径,索引 200 → 189 条。
keywords.json 是**可选**的:读不到只警告不中断,检索退化为原行为。
This commit is contained in:
@ -65,6 +65,17 @@
|
||||
else if (name.indexOf(ql) === 0) s += 600;
|
||||
else if (name.indexOf(ql) > 0) s += 350;
|
||||
|
||||
// 中文检索关键词(keywords.json 产出,字段 g)。
|
||||
// 为什么需要:SDK 里 66/100 个符号是英文注释(`RegisterTool registers a
|
||||
// tool that the LLM can call.`),懂中文的人搜「注册工具」会一条都找不到。
|
||||
// 关键词命中给较高权重(仅次于名称精确命中),因为它就是为「按功能找」准备的。
|
||||
var kws = item.g || [];
|
||||
for (var ki = 0; ki < kws.length; ki++) {
|
||||
var kw = String(kws[ki]).toLowerCase();
|
||||
if (kw === ql) { s += 480; break; }
|
||||
if (kw.indexOf(ql) >= 0) { s += 300; break; }
|
||||
}
|
||||
|
||||
// 限定符:PluginSDK.RegisterTool / IOInjector.InjectText。
|
||||
// 额外支持「去掉 API/SDK 后缀」与「去掉点号」两种写法,
|
||||
// 因为读者习惯写 `memory.recall`(RPC 名),而 Go 名是 `MemoryAPI.Recall`。
|
||||
@ -94,13 +105,17 @@
|
||||
}
|
||||
|
||||
// 中文按字匹配:中文没有词边界,逐字命中比整串更实用。
|
||||
// 注意只把它当作**弱信号**:光靠逐字会把「注册工具」匹到凡是含「工具」
|
||||
// 字样的任何东西(实测 ContextPolicyNone 的说明里有「工具调用」也会命中)。
|
||||
// 所以阈值卡在 60% 以上才算有效命中。
|
||||
if (/[\u4e00-\u9fa5]/.test(q)) {
|
||||
var hit = 0;
|
||||
var hay = desc + " " + kws.join(" ");
|
||||
for (var i = 0; i < q.length; i++) {
|
||||
if (desc.indexOf(q[i]) >= 0) hit++;
|
||||
if (hay.indexOf(q[i]) >= 0) hit++;
|
||||
}
|
||||
if (hit === q.length) s += 100; // 全部字都出现
|
||||
else s += hit * 8;
|
||||
var ratio = hit / q.length;
|
||||
if (ratio >= 0.6) s += Math.round(hit * 6);
|
||||
}
|
||||
|
||||
// 公开 API 略优先于「仅内置」——后者通常是噪声。
|
||||
@ -173,6 +188,10 @@
|
||||
var d = el("span", "api-desc", it.d);
|
||||
li.appendChild(d);
|
||||
}
|
||||
// 关键词是给检索用的;显示出来能让读者明白“为什么这条被匹配到”。
|
||||
if (it.g && it.g.length) {
|
||||
li.appendChild(el("span", "api-kw", it.g.slice(0, 6).join(" · ")));
|
||||
}
|
||||
if (it.f) {
|
||||
li.appendChild(el("span", "api-loc", it.f + (it.l ? ":" + it.l : "")));
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user