mirror of https://gitcode.com/JianFeeeee/homeagent-sdk.git synced 2026-09-26 04:13:15 +00:00

Files

JianFeeeee 0a6e2b7dc4 docs: 插件 SDK 文档站（API 参考从源码生成 + 自建检索）

为插件作者建一个文档站，重点是**能按描述搜到 API**，以及**明确能力边界**。

## 为什么 API 参考要生成而不是手写

公开 API 面有 115 个符号、11 个接口。手抄必然与代码漂移——这是文档站最常见的
死法（本仓 README 里已经有过几处「文档说一套、代码是另一套」）。

所以 `tools/apidoc` 直接从 `sdk/*.go` 提取签名、文档注释与代码块示例，渲染成
`docs/api/*.md`。发现文档不对时改的是**源码注释**，不是生成物。生成页首行带
「勿手改」标记，防止有人改了下次构建白改。

- `extract.go`：go/ast + go/doc 提取（只用标准库，离线可跑，不引入依赖）
- `gensite/`：渲染 Markdown + 检索索引
- `gensite/usages.go`：从 `example/` 21 个示例插件里反查**真实调用点**，
  贴在每个 API 下（源码注释里几乎没有可运行示例，但示例插件都是能编译跑的真代码）

## 能力边界：写这个站时查出的三处文档错误

这是本次最有价值的部分。原以为「公开 SDK 里有的 API 外部插件都能用」，
实测对照桥接模板后发现三处不符，站内已更正：

1. **`PluginMgr()` 被写成「仅内置可用」——错的。** 桥接模板第 692 行显式
   `base.SetPluginMgrAPI(procPluginMgr{})`，公开 `PluginMgrAPI` 注释也写「外部插件可调用」。
   真正的区别是**方法数**：公开面 3 个（ReloadOne/ListLoadedPlugins/IsPluginDisabled），
   内部面 9 个。容易混淆是因为两个包里有同名但不同的接口。
2. **`Events()` 外部插件恒为 nil。** `SetEventSubscriber` 全仓只有定义、无调用点，
   故 subscriber 从未被注入。外部插件的事件订阅实际由生成的运行时走
   `events.subscribe` RPC 完成——旧文档把它当成可用入口，会让人写出必然失效的代码。
3. **`UnregisterOutputChannel` 是静默无效，不是报错。** 桥接只注入 registrar、
   不注入 unregistrar，于是 `regOutputUnreg == nil`，函数命中 else 分支**直接返回 nil**
   （sdk/plugin.go:539-549）——不报错、通道也没注销。

每条裁定的依据写进 `tools/apidoc/tiers.json`（文件:行号 或 grep 结论），
站上以告警框呈现，读者可自行核对。判断依据三源：桥接模板的 `base.Set*` 注入点、
`internal/sdk` 完整面、`internal/plugin/proc/protocol.go` 的 RPC 表。

## 检索（用户的核心诉求）

两套互补：

- **MkDocs 内置搜索**：全文，中文走 jieba 分词。
- **自建 API 检索**（`docs/javascripts/api-search.js` + `assets/api-index.json`）：
  支持四类查询——按名称、**按功能描述**（「注册工具」→ RegisterTool、
  「崩溃」→ SetAutoRestart）、按 `限定符.方法`（`memory.recall` → MemoryAPI.Recall）、
  按签名片段（`(string) error`）。并标出「仅内置」，避免外部插件作者踩空。

自建的理由：Material 内置搜索按整页文本索引，搜 `InjectText` 会列出所有提到它的
页面，但分不清哪条是它的定义；而且它要等 mkdocs build 才更新。

## 文档结构

- `docs/guide/`：快速开始、Go/Lua 首个插件、能力边界、打包发布、多平台、受限 SDK 与安全
- `docs/api/`：10 个按「你想做什么」划分的章节（工具/阶段/记忆/通道/配置/生命周期/
  事件/LLM/常量/桥接）+ 仅内置汇总页
- `docs/versions.md`：SDK 版本语义（跟随内核中版本、patch 恒为 .0）、
  1.0.0 是唯一破坏性变更、RPC 协议版本

## 验证

- `mkdocs build --strict` 零告警
- 23 个页面的全部站内链接与锚点可达（自动校验）
- 1440 / 768 / 390px 三视口：无横向溢出、无控制台错误
- 四种检索模式实测有结果且跳转锚点正确
- 构建产物 `site_build/` 已 gitignore

用法：`tools/apidoc/build.sh`（生成+构建）、`tools/apidoc/build.sh serve`（预览）。

2026-09-24 12:08:37 +08:00

1.9 KiB

Raw Blame History

环境与工具链

hmapdev 是 SDK 仓提供的统一插件开发工具链，Go 与 Lua 两种插件都用它，最终产出 .hmap 插件包（工具名即取自这个包格式）。

!!! note "改名说明" 1.2.0 起工具链由 plugindev 更名为 hmapdev；SDK 存储目录同时由 ~/.homeagent/plugindev/sdk 迁到 ~/.homeagent/hmapdev/sdk （旧目录会自动继续沿用）。

安装

从源码构建：

git clone https://gitcode.com/JianFeeeee/homeagent-sdk
cd homeagent-sdk/tools/hmapdev
go build -o hmapdev
# 把 hmapdev 放进 PATH，或直接用 ./hmapdev

也可以从 SDK 的 release 附件下载预编译二进制（hmapdev_linux_amd64 等）。

SDK 版本管理

hmapdev 会维护一份本地 SDK 存储，init 时按 plg.json 里的 sdk 字段选择版本。两者必须一致，否则编译出的插件与内核协议可能错配。

hmapdev sdk list            # 已安装的 SDK 版本
hmapdev sdk current         # 当前使用的版本
hmapdev sdk latest          # 最新可用版本
hmapdev sdk install v1.2.0  # 安装指定版本
hmapdev sdk use v1.2.0      # 切换版本
hmapdev sdk path            # 当前 SDK 路径

存储在 ~/.homeagent/hmapdev/sdk/<version>/。

!!! warning "版本未命中会明确报错" plg.json 声明的 sdk 版本若不在本地存储里，hmapdev 不会退回某个默认版本，而是报错并让你先 hmapdev sdk install。这是有意的：静默降级会产出与内核协议不匹配的插件，那种失败要到运行时才暴露。

源码调试

不编译直接跑插件源码，输出调用轨迹：

hmapdev debug [dir]   # dir 默认当前目录

写 Lua 插件时更简单——sdk.lua 是 SDK 模拟层，可以直接用解释器跑：

lua main.lua

1.9 KiB Raw Blame History Unescape Escape

环境与工具链

安装

SDK 版本管理

源码调试

下一步

1.9 KiB

Raw Blame History