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`（预览）。

mkdocs.yml

@@ -0,0 +1,128 @@
+# 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