mirror of
https://gitcode.com/JianFeeeee/homeagent-sdk.git
synced 2026-09-25 19:38:06 +00:00
9b6abe1b73
## 问题（实测）
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 是**可选**的：读不到只警告不中断，检索退化为原行为。
124 lines
2.7 KiB
CSS
124 lines
2.7 KiB
CSS
/* API 即时检索与文档站的少量本地样式。
|
||
只补 Material 没覆盖的部分，不覆盖主题变量（保持深浅色自动适配）。 */
|
||
|
||
#api-search {
|
||
margin: 1.2rem 0 2rem;
|
||
}
|
||
|
||
.api-input {
|
||
width: 100%;
|
||
padding: 0.7rem 0.9rem;
|
||
font-size: 1rem;
|
||
border: 1px solid var(--md-default-fg-color--lightest);
|
||
border-radius: 0.3rem;
|
||
background: var(--md-default-bg-color);
|
||
color: var(--md-default-fg-color);
|
||
}
|
||
|
||
.api-input:focus {
|
||
outline: 2px solid var(--md-accent-fg-color);
|
||
outline-offset: 1px;
|
||
border-color: transparent;
|
||
}
|
||
|
||
.api-hint {
|
||
color: var(--md-default-fg-color--light);
|
||
font-size: 0.8rem;
|
||
margin: 0.6rem 0 0;
|
||
}
|
||
|
||
.api-count {
|
||
color: var(--md-default-fg-color--light);
|
||
font-size: 0.75rem;
|
||
margin: 0.8rem 0 0.4rem;
|
||
}
|
||
|
||
.api-results {
|
||
list-style: none;
|
||
margin: 0;
|
||
padding: 0;
|
||
}
|
||
|
||
.api-result {
|
||
padding: 0.55rem 0.6rem;
|
||
border-left: 3px solid var(--md-primary-fg-color);
|
||
margin-bottom: 0.4rem;
|
||
background: var(--md-code-bg-color);
|
||
border-radius: 0 0.2rem 0.2rem 0;
|
||
display: flex;
|
||
flex-wrap: wrap;
|
||
align-items: baseline;
|
||
gap: 0.45rem;
|
||
}
|
||
|
||
.api-name {
|
||
font-family: var(--md-code-font-family, monospace);
|
||
font-weight: 700;
|
||
font-size: 0.85rem;
|
||
}
|
||
|
||
.api-sig {
|
||
font-size: 0.72rem;
|
||
color: var(--md-default-fg-color--light);
|
||
background: none;
|
||
padding: 0;
|
||
overflow-wrap: anywhere;
|
||
}
|
||
|
||
.api-desc {
|
||
flex-basis: 100%;
|
||
font-size: 0.78rem;
|
||
color: var(--md-default-fg-color--light);
|
||
}
|
||
|
||
/* 「为何命中」的中文关键词（keywords.json 产出）。 */
|
||
.api-kw {
|
||
flex-basis: 100%;
|
||
font-size: 0.7rem;
|
||
color: var(--md-accent-fg-color);
|
||
opacity: 0.9;
|
||
}
|
||
|
||
.api-loc {
|
||
flex-basis: 100%;
|
||
font-size: 0.68rem;
|
||
color: var(--md-default-fg-color--lighter, var(--md-default-fg-color--light));
|
||
font-family: var(--md-code-font-family, monospace);
|
||
}
|
||
|
||
.api-badge {
|
||
font-size: 0.62rem;
|
||
padding: 0.08rem 0.34rem;
|
||
border-radius: 0.6rem;
|
||
font-weight: 600;
|
||
white-space: nowrap;
|
||
}
|
||
|
||
.api-badge-builtin {
|
||
background: rgba(245, 158, 11, 0.18);
|
||
color: #b45309;
|
||
border: 1px solid rgba(245, 158, 11, 0.5);
|
||
}
|
||
|
||
[data-md-color-scheme="slate"] .api-badge-builtin {
|
||
color: #fbbf24;
|
||
}
|
||
|
||
/* 「仅内置」告警块里的依据说明通常很长，窄屏下允许更小字号。 */
|
||
@media screen and (max-width: 44.98em) {
|
||
.api-sig { font-size: 0.68rem; }
|
||
}
|
||
|
||
/* 签名与长类型定义可能超出正文宽度（如 ContentBlock 的字段列表）。
|
||
highlight 代码块默认不换行，靠横向滚动；把默认改为换行显示，
|
||
因为文档读者更希望一眼看全签名而不是拖滚动条。 */
|
||
.md-typeset pre > code {
|
||
white-space: pre-wrap;
|
||
overflow-wrap: anywhere;
|
||
}
|
||
|
||
/* 接口方法表里的签名可能很长，允许在任意位置折行。 */
|
||
.md-typeset table code {
|
||
overflow-wrap: anywhere;
|
||
}
|