mirror of
https://gitcode.com/JianFeeeee/homeagent-sdk.git
synced 2026-10-03 23:54:12 +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:
JianFeeeee
@ -268,18 +268,6 @@ const ContextPolicyPrune
|
||||
|
||||
<small>`plugin.go:45`</small>
|
||||
|
||||
### `IOInjector`
|
||||
|
||||
```go
|
||||
type IOInjector interface { InjectInterruptText(source, channel, text string) InjectText(source, channel, text string) InjectTextNoMemory(source, channel, text string) // I …
|
||||
```
|
||||
|
||||
IOInjector provides methods for injecting input and interrupts into the agent pipeline.
|
||||
All methods accept (source, channel) where channel is the target output channel
|
||||
for routing the agent's response.
|
||||
|
||||
<small>`plugin.go:220`</small>
|
||||
|
||||
### `PluginSDK.InjectInputMedia`
|
||||
|
||||
```go
|
||||
|
||||
@ -44,18 +44,6 @@ EventHandler processes a system event.
|
||||
|
||||
<small>`plugin.go:273`</small>
|
||||
|
||||
### `EventSubscriber`
|
||||
|
||||
```go
|
||||
type EventSubscriber interface { Subscribe(eventType EventType, handler EventHandler) func() }
|
||||
```
|
||||
|
||||
EventSubscriber allows plugins to subscribe to kernel events.
|
||||
This is a restricted interface: plugins can subscribe but the kernel
|
||||
controls which events are delivered.
|
||||
|
||||
<small>`plugin.go:278`</small>
|
||||
|
||||
### `EventType`
|
||||
|
||||
```go
|
||||
|
||||
@ -89,16 +89,6 @@ AutoRestart 返回插件是否允许自动重启。
|
||||
|
||||
<small>`plugin.go:791`</small>
|
||||
|
||||
### `Plugin`
|
||||
|
||||
```go
|
||||
type Plugin interface { Name() string Start(sdk *PluginSDK) error Stop() error }
|
||||
```
|
||||
|
||||
Plugin is the interface every plugin must implement.
|
||||
|
||||
<small>`plugin.go:13`</small>
|
||||
|
||||
### `PluginSDK.PluginMgr`
|
||||
|
||||
```go
|
||||
@ -110,17 +100,6 @@ May be nil if the host did not wire it.
|
||||
|
||||
<small>`plugin.go:653`</small>
|
||||
|
||||
### `PluginMgrAPI`
|
||||
|
||||
```go
|
||||
type PluginMgrAPI interface { // ReloadOne 重载单个插件（停止后重新加载）。 ReloadOne(name string) error // ListLoadedPlugins 列出已加载插件。 ListLoa …
|
||||
```
|
||||
|
||||
PluginMgrAPI 提供插件管理能力（外部插件可调用）。
|
||||
由 bridge 注入 dispatch 实现，走 C ABI CORE_PLUGIN_RELOAD_ONE 等。
|
||||
|
||||
<small>`plugin.go:284`</small>
|
||||
|
||||
### `PluginSDK.PluginName`
|
||||
|
||||
```go
|
||||
|
||||
@ -48,13 +48,3 @@ LLM returns the LLM provider API (may be nil if not available).
|
||||
|
||||
<small>`plugin.go:432`</small>
|
||||
|
||||
### `LLMAPI`
|
||||
|
||||
```go
|
||||
type LLMAPI interface { ListSources() []string SetSource(name string) error CurrentSource() string }
|
||||
```
|
||||
|
||||
LLMAPI provides access to the LLM provider manager.
|
||||
|
||||
<small>`llm.go:4`</small>
|
||||
|
||||
|
||||
@ -238,16 +238,6 @@ DocMemory returns the document memory API (may be nil if not available).
|
||||
|
||||
<small>`plugin.go:418`</small>
|
||||
|
||||
### `DocMemoryAPI`
|
||||
|
||||
```go
|
||||
type DocMemoryAPI interface { Query(text string, topK int) []*Doc Insert(doc *Doc) error // InsertWithMedia 写入文档并关联媒体。attachments 里带 Data 的会落进 …
|
||||
```
|
||||
|
||||
DocMemoryAPI provides access to the document vector store.
|
||||
|
||||
<small>`memory.go:74`</small>
|
||||
|
||||
### `Entity`
|
||||
|
||||
```go
|
||||
@ -258,22 +248,6 @@ Entity represents a named entity in the knowledge graph.
|
||||
|
||||
<small>`memory.go:13`</small>
|
||||
|
||||
### `PluginSDK.Knowledge`
|
||||
|
||||
```go
|
||||
func (s *PluginSDK) Knowledge() KnowledgeAPI
|
||||
```
|
||||
|
||||
Knowledge returns the knowledge store API (may be nil if not available).
|
||||
|
||||
**示例插件里的真实用法**
|
||||
|
||||
| 插件 | 位置 | 代码 |
|
||||
|---|---|---|
|
||||
| [`recoverydiag`](../examples/index.md#recoverydiag) | `example/recoverydiag/plugin.go:978` | `if p.sdk != nil && p.sdk.Knowledge() != nil {` |
|
||||
|
||||
<small>`plugin.go:425`</small>
|
||||
|
||||
### `Knowledge`
|
||||
|
||||
```go
|
||||
@ -290,15 +264,21 @@ Knowledge represents a knowledge entry.
|
||||
|
||||
<small>`knowledge.go:11`</small>
|
||||
|
||||
### `KnowledgeAPI`
|
||||
### `PluginSDK.Knowledge`
|
||||
|
||||
```go
|
||||
type KnowledgeAPI interface { Search(query string, topK int) ([]*Knowledge, error) Add(name, content string) error List() ([]string, error) }
|
||||
func (s *PluginSDK) Knowledge() KnowledgeAPI
|
||||
```
|
||||
|
||||
KnowledgeAPI provides access to the knowledge store.
|
||||
Knowledge returns the knowledge store API (may be nil if not available).
|
||||
|
||||
<small>`knowledge.go:4`</small>
|
||||
**示例插件里的真实用法**
|
||||
|
||||
| 插件 | 位置 | 代码 |
|
||||
|---|---|---|
|
||||
| [`recoverydiag`](../examples/index.md#recoverydiag) | `example/recoverydiag/plugin.go:978` | `if p.sdk != nil && p.sdk.Knowledge() != nil {` |
|
||||
|
||||
<small>`plugin.go:425`</small>
|
||||
|
||||
### `MediaAttachment`
|
||||
|
||||
@ -330,16 +310,6 @@ Memory returns the graph memory API (may be nil if not available).
|
||||
|
||||
<small>`plugin.go:404`</small>
|
||||
|
||||
### `MemoryAPI`
|
||||
|
||||
```go
|
||||
type MemoryAPI interface { Recall(query []string, depth int) ([]Entity, []Relation, error) Commit(triples []Triple) error Introspect() (map[string]interface{}, error) Merg …
|
||||
```
|
||||
|
||||
MemoryAPI provides access to the graph memory (entity-relation store).
|
||||
|
||||
<small>`memory.go:4`</small>
|
||||
|
||||
### `PersonProfile`
|
||||
|
||||
```go
|
||||
@ -370,17 +340,6 @@ Social returns the social graph API (may be nil if not available).
|
||||
|
||||
<small>`plugin.go:439`</small>
|
||||
|
||||
### `SocialAPI`
|
||||
|
||||
```go
|
||||
type SocialAPI interface { GetPerson(name string) (*PersonProfile, error) GetTrait(name, trait string) (string, bool) GetRelations(name string) ([]SocialRelation, error) G …
|
||||
```
|
||||
|
||||
SocialAPI provides read-only access to the social graph (person profiles and relationships).
|
||||
External plugins can query person traits and social networks but cannot modify them.
|
||||
|
||||
<small>`memory.go:100`</small>
|
||||
|
||||
### `SocialRelation`
|
||||
|
||||
```go
|
||||
@ -409,16 +368,6 @@ TextMemory returns the text memory API (may be nil if not available).
|
||||
|
||||
<small>`plugin.go:411`</small>
|
||||
|
||||
### `TextMemoryAPI`
|
||||
|
||||
```go
|
||||
type TextMemoryAPI interface { Append(evt TextEvent) error }
|
||||
```
|
||||
|
||||
TextMemoryAPI provides access to chronological text event storage.
|
||||
|
||||
<small>`memory.go:43`</small>
|
||||
|
||||
### `Triple`
|
||||
|
||||
```go
|
||||
|
||||
@ -195,11 +195,3 @@ sett 在 New 时一次性写入且无 setter，故不需要加锁。
|
||||
|
||||
<small>`plugin.go:401`</small>
|
||||
|
||||
### `SettingsAPI`
|
||||
|
||||
```go
|
||||
type SettingsAPI interface { // Get reads the plugin's own config value (config_<name> table). Get(key string) (interface{}, error) // Set writes a config value to the plugi …
|
||||
```
|
||||
|
||||
<small>`settings.go:3`</small>
|
||||
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -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 : "")));
|
||||
}
|
||||
|
||||
@ -71,6 +71,14 @@
|
||||
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;
|
||||
|
||||
Reference in New Issue
Block a user