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

tools/apidoc/gensite/usages.go

@@ -0,0 +1,118 @@
+package main
+
+import (
+	"bufio"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+)
+
+// Usage 是一条真实用法：某个示例插件在某行用了这个 API。
+//
+// 为什么要有它：API 参考最容易变成「签名罗列」——读者看得到参数，
+// 却不知道该怎么用。SDK 的源码注释里几乎没有可运行示例（实测只有 7 行缩进
+// 代码块），但 example/ 下有 21 个**真实可编译**的示例插件。把它们里的调用点
+// 反查到每个 API 上，读者就能直接跳到能跑的代码。
+type Usage struct {
+	Plugin string `json:"plugin"` // 示例名（example 下的目录名）
+	File   string `json:"file"`   // 相对 SDK 仓根的路径
+	Line   int    `json:"line"`
+	Code   string `json:"code"` // 该行原文（裁剪首尾空白）
+}
+
+var callRe = regexp.MustCompile(`\.([A-Z][A-Za-z0-9_]*)\s*\(`)
+
+// scanUsages 遍历 example/ 下所有 .go 文件，找出每个 API 的真实调用点。
+//
+// names 是要找的符号名集合（越小越快）。只扫 example/，不扫 tools/——
+// 工具链自己也会调 SDK，那属于内部实现，不是「用法示例」。
+func scanUsages(exDir string, names map[string]bool) map[string][]Usage {
+	out := map[string][]Usage{}
+	_ = filepath.Walk(exDir, func(path string, info os.FileInfo, err error) error {
+		if err != nil || info.IsDir() {
+			return nil
+		}
+		if !strings.HasSuffix(path, ".go") {
+			return nil
+		}
+		rel, _ := filepath.Rel(filepath.Dir(exDir), path)
+		plugin := pluginName(path, exDir)
+		f, err := os.Open(path)
+		if err != nil {
+			return nil
+		}
+		defer f.Close()
+		sc := bufio.NewScanner(f)
+		sc.Buffer(make([]byte, 0, 64*1024), 1024*1024)
+		line := 0
+		for sc.Scan() {
+			line++
+			text := sc.Text()
+			trimmed := strings.TrimSpace(text)
+			// 跳过注释行：注释里提到 API 名不算「用法」。
+			if strings.HasPrefix(trimmed, "//") || strings.HasPrefix(trimmed, "*") {
+				continue
+			}
+			for _, m := range callRe.FindAllStringSubmatch(text, -1) {
+				name := m[1]
+				if !names[name] {
+					continue
+				}
+				out[name] = append(out[name], Usage{
+					Plugin: plugin, File: rel, Line: line, Code: truncate(trimmed, 110),
+				})
+			}
+		}
+		return nil
+	})
+	for k := range out {
+		sort.Slice(out[k], func(i, j int) bool {
+			if out[k][i].Plugin != out[k][j].Plugin {
+				return out[k][i].Plugin < out[k][j].Plugin
+			}
+			return out[k][i].Line < out[k][j].Line
+		})
+		// 每个 API 最多留 4 条，避免页面被用法淹没；优先保留不同插件。
+		out[k] = dedupeByPlugin(out[k], 4)
+	}
+	return out
+}
+
+// pluginName 从路径里取示例名：example/<plugin>/....go → <plugin>。
+func pluginName(path, exDir string) string {
+	rel, err := filepath.Rel(exDir, path)
+	if err != nil {
+		return "?"
+	}
+	parts := strings.Split(rel, string(filepath.Separator))
+	if len(parts) > 0 {
+		return parts[0]
+	}
+	return "?"
+}
+
+func dedupeByPlugin(in []Usage, limit int) []Usage {
+	seen := map[string]int{}
+	var out []Usage
+	for _, u := range in {
+		if seen[u.Plugin] >= 1 {
+			continue
+		}
+		seen[u.Plugin]++
+		out = append(out, u)
+		if len(out) >= limit {
+			break
+		}
+	}
+	return out
+}
+
+func truncate(s string, n int) string {
+	r := []rune(s)
+	if len(r) <= n {
+		return s
+	}
+	return string(r[:n]) + "…"
+}