mirror of
https://gitcode.com/JianFeeeee/homeagent-sdk.git
synced 2026-09-26 04:13:15 +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 是**可选**的：读不到只警告不中断，检索退化为原行为。
70 lines
2.0 KiB
Markdown
70 lines
2.0 KiB
Markdown
<!-- 本页由 tools/apidoc/gensite 从源码生成，请勿手改；要改文档就改 sdk/*.go 的注释。 -->
|
||
|
||
# 事件（Events）
|
||
|
||
订阅内核事件。**注意**：外部分布式插件的事件订阅不走 `Events()`（该接口在外部插件路径上未被注入，恒为 nil），而是由 `hmapdev` 生成的运行时通过 `events.subscribe` 完成。详见下方说明。
|
||
|
||
## `EventSubscriber`
|
||
|
||
EventSubscriber allows plugins to subscribe to kernel events.
|
||
This is a restricted interface: plugins can subscribe but the kernel
|
||
controls which events are delivered.
|
||
|
||
| 方法 | 说明 |
|
||
|---|---|
|
||
| [`Subscribe`](#eventsubscribersubscribe) | |
|
||
|
||
### `EventSubscriber.Subscribe`
|
||
|
||
!!! warning "仅内核内置插件可用"
|
||
|
||
```go
|
||
Subscribe(eventType EventType, handler EventHandler) func()
|
||
```
|
||
|
||
<small>`plugin.go:279`</small>
|
||
|
||
### `Event`
|
||
|
||
```go
|
||
type Event struct { Type EventType `json:"type"` Source string `json:"source"` Payload map[string]interface{} `json:"payload"` T …
|
||
```
|
||
|
||
Event represents a system event published by the kernel.
|
||
|
||
<small>`plugin.go:265`</small>
|
||
|
||
### `EventHandler`
|
||
|
||
```go
|
||
type EventHandler func(evt *Event)
|
||
```
|
||
|
||
EventHandler processes a system event.
|
||
|
||
<small>`plugin.go:273`</small>
|
||
|
||
### `EventType`
|
||
|
||
```go
|
||
type EventType string
|
||
```
|
||
|
||
EventType identifies the kind of system event.
|
||
|
||
<small>`plugin.go:247`</small>
|
||
|
||
### `PluginSDK.Events`
|
||
|
||
!!! warning "仅内核内置插件可用"
|
||
实测全仓 SetEventSubscriber 只有定义、无任何调用点（grep -rn SetEventSubscriber --include=*.go 仅命中 sdk/plugin.go 的定义与 lua_plugin.go 的一句注释）。外部插件拿到的 Events() 恒为 nil。外部插件订阅事件走的是桥接运行时的 events.subscribe RPC（proc_main.go.tmpl:1421 在插件侧分发、内核 protocol.go MethodEventsSubscribe），Lua 插件则走内部 SDK 的 Subscribe。这正是 PLUGIN_DEV.md 里没有说清的一处。
|
||
|
||
```go
|
||
func (s *PluginSDK) Events() EventSubscriber
|
||
```
|
||
|
||
Events returns the event subscriber for listening to kernel events (may be nil if not available).
|
||
|
||
<small>`plugin.go:446`</small>
|
||
|