mirror of
https://gitcode.com/JianFeeeee/homeagent-sdk.git
synced 2026-09-25 03:18:06 +00:00
0a6e2b7dc4
为插件作者建一个文档站，重点是**能按描述搜到 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`（预览）。
129 lines
3.7 KiB
YAML
129 lines
3.7 KiB
YAML
# HomeAgent 插件 SDK 文档站配置。
|
||
#
|
||
# 设计取舍：
|
||
# - 每页顶部都放「版本 + 编辑链接」，因为 SDK 与内核的协议版本会错配，
|
||
# 读者必须先能确认自己看的是哪一版。
|
||
# - 中文检索依赖 jieba（已装）；英文走内置分词。两者都不要额外服务。
|
||
# - docs/api/*.md 是**生成物**（tools/apidoc/gensite），页首会写明，防止手改。
|
||
|
||
site_name: HomeAgent 插件 SDK
|
||
site_description: 用 Go 或 Lua 为 HomeAgent 编写插件 —— API 参考与开发指南
|
||
site_url: https://sdk.homeagent.jianfgit.xyz/
|
||
copyright: MIT 许可 · JianFeeeee
|
||
|
||
docs_dir: docs
|
||
site_dir: site_build
|
||
|
||
theme:
|
||
name: material
|
||
language: zh
|
||
features:
|
||
- navigation.instant
|
||
- navigation.instant.progress
|
||
- navigation.tracking
|
||
- navigation.tabs
|
||
- navigation.sections
|
||
- navigation.indexes
|
||
- navigation.top
|
||
- toc.follow
|
||
- search.suggest
|
||
- search.highlight
|
||
- search.share
|
||
- content.code.copy
|
||
- content.code.annotate
|
||
- content.action.edit
|
||
palette:
|
||
- media: "(prefers-color-scheme: light)"
|
||
scheme: default
|
||
primary: indigo
|
||
accent: indigo
|
||
toggle:
|
||
icon: material/weather-night
|
||
name: 切换到深色
|
||
- media: "(prefers-color-scheme: dark)"
|
||
scheme: slate
|
||
primary: indigo
|
||
accent: indigo
|
||
toggle:
|
||
icon: material/weather-sunny
|
||
name: 切换到浅色
|
||
icon:
|
||
repo: fontawesome/brands/git-alt
|
||
|
||
plugins:
|
||
- search:
|
||
lang:
|
||
- zh
|
||
- en
|
||
separator: '[\s\u200b\-]'
|
||
# 中文按词切（jieba），否则整句变一个 token，检索不到。
|
||
jieba_dict: null
|
||
|
||
markdown_extensions:
|
||
- admonition
|
||
- attr_list
|
||
- def_list
|
||
- footnotes
|
||
- md_in_html
|
||
- tables
|
||
- toc:
|
||
permalink: true
|
||
toc_depth: 3
|
||
- pymdownx.details
|
||
# Material 的图标语法 :material-xxx: / :octicons-xxx: 依赖这个扩展。
|
||
# 没开时它们会**原样显示为文本**（实测首页四个卡片全花了）。
|
||
- pymdownx.emoji:
|
||
emoji_index: !!python/name:material.extensions.emoji.twemoji
|
||
emoji_generator: !!python/name:material.extensions.emoji.to_svg
|
||
- pymdownx.highlight:
|
||
anchor_linenums: true
|
||
- pymdownx.inlinehilite
|
||
- pymdownx.snippets
|
||
- pymdownx.superfences
|
||
- pymdownx.tabbed:
|
||
alternate_style: true
|
||
|
||
extra:
|
||
generator: false
|
||
social:
|
||
- icon: fontawesome/solid/code
|
||
link: https://gitcode.com/JianFeeeee/homeagent-sdk
|
||
name: SDK 源码
|
||
# 自定义检索端点在 docs/javascripts/api-search.js 里注册，
|
||
# 索引文件由 gensite 产出：docs/assets/api-index.json
|
||
|
||
nav:
|
||
- 首页: index.md
|
||
- 快速开始:
|
||
- 环境与工具链: guide/getting-started.md
|
||
- 第一个 Go 插件: guide/first-plugin.md
|
||
- 第一个 Lua 插件: guide/first-lua-plugin.md
|
||
- API 参考:
|
||
- api/index.md
|
||
- 工具（Tools）: api/tools.md
|
||
- 阶段钩子（Stages）: api/stages.md
|
||
- 记忆（Memory）: api/memory.md
|
||
- 输入/输出通道: api/channels.md
|
||
- 配置（Settings）: api/settings.md
|
||
- 生命周期（Lifecycle）: api/lifecycle.md
|
||
- 事件（Events）: api/events.md
|
||
- LLM 调用: api/llm.md
|
||
- 常量与枚举: api/constants.md
|
||
- 桥接装配点: api/bridge.md
|
||
- 其他类型: api/misc.md
|
||
- 仅内置插件可用: api/builtin-only.md
|
||
- 指南:
|
||
- 能力边界（哪些 API 外部可用）: guide/capability-boundary.md
|
||
- 打包与发布: guide/packaging.md
|
||
- 多平台构建: guide/multi-platform.md
|
||
- 受限 SDK 与安全: guide/security.md
|
||
- 示例插件:
|
||
- 总览: examples/index.md
|
||
- 版本与兼容: versions.md
|
||
|
||
extra_css:
|
||
- stylesheets/extra.css
|
||
|
||
extra_javascript:
|
||
- javascripts/api-search.js
|