mirror of
https://gitcode.com/JianFeeeee/homeagent-sdk.git
synced 2026-10-02 23:24:16 +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 是**可选**的：读不到只警告不中断，检索退化为原行为。
插件 SDK 文档站
用 MkDocs Material 构建的 SDK 文档站。API 参考不是手写的 ——
它从 sdk/*.go 的源码注释生成，因为手抄必然与代码漂移。
目录结构
mkdocs.yml 站点配置（导航、主题、中文检索）
docs/
├── index.md ┐
├── versions.md │
├── guide/*.md ├─ 手写：指南、边界说明、版本
├── api/index.md │
├── javascripts/ │
│ └── api-search.js │ 自建 API 检索（按名称/描述/签名）
├── stylesheets/extra.css ┘
├── api/*.md ┐ 生成物 —— 勿手改
├── examples/index.md │ （build 时覆盖）
└── assets/api-index.json ┘
tools/apidoc/ 生成器（本仓 Go 代码，零外部依赖）
├── extract.go 从源码提取符号、注释、分层
├── tiers.go 应用能力分层（public / builtin / bridge）
├── tiers.json **能力边界的事实源**（每条附源码依据）
├── gensite/main.go 渲染 Markdown + 检索索引
├── gensite/usages.go 从 example/ 抽取真实调用点
└── build.sh 一键生成 + 构建
构建
tools/apidoc/build.sh # 生成 + 构建到 site_build/
tools/apidoc/build.sh serve # 本地预览（http://127.0.0.1:8000）
依赖：Go 1.21+、mkdocs-material（pip install mkdocs-material）、
jieba（中文检索分词，pip install jieba）。
两条设计原则
① API 参考从源码生成。 签名、说明、示例全部来自 sdk/*.go 的文档注释。
发现文档不对时，改的是源码注释，然后重新生成。生成页首行有「勿手改」标记。
② 能力边界是可核对的事实，不是印象。 哪些 API 外部插件拿不到，
逐条记在 tools/apidoc/tiers.json，每条都写清可复核的依据
（文件:行号、或 grep 结论）。判断标准是：
| 依据 | 含义 |
|---|---|
tools/hmapdev/templates/proc_main.go.tmpl 的 base.Set* 调用 |
外部插件运行时实际注入哪些能力 |
internal/sdk |
内置插件用的完整接口（对照出外部缺什么） |
internal/plugin/proc/protocol.go |
外部插件能发哪些 RPC |
文档站上每条「仅内置」告警都带这个依据，读者可自行核对。
为什么这个边界值得单独维护
写这个站时，实测发现文档与源码有三处不符（现已在站内更正）：
PluginMgr()曾被写成「仅内置可用」——实际桥接显式注入了它。 真正的区别是方法数：公开面 3 个，内部面 9 个（两个包里同名不同接口）。Events()曾被当作可用的事件订阅入口——实际桥接不注入 subscriber， 外部插件拿到的恒为 nil（SetEventSubscriber全仓无调用点）。 外部插件的事件订阅实际由生成的运行时走events.subscribeRPC 完成。UnregisterOutputChannel易被当成「可用但会报错」——实际返回 nil， 静默无效（桥不注入 unregister），不报错也不注销。
检索
站内有两套检索，互补：
- MkDocs 内置搜索（右上角）：全文检索，中文走 jieba 分词。
- 自建 API 检索（首页与 API 参考页的输入框）：读
assets/api-index.json， 专门解决「按描述找 API」——搜「注册工具」能找到RegisterTool， 搜「崩溃」能找到SetAutoRestart，并可区分公开/仅内置。
自建检索支持四类查询：名称、描述（中英文）、限定符.方法
（如 memory.recall）、签名片段（如 (string) error）。
维护提示
- 改了
sdk/*.go的注释或签名 → 重跑build.sh，改动自动进文档。 - 改了能力边界 → 改
tiers.json，不要直接改生成的.md。 - 新增示例插件 → 自动出现在「示例插件」页的用法表里（扫
example/）。 site_build/是构建产物，已 gitignore，不要提交。