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/tiers.go

@@ -0,0 +1,149 @@
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+)
+
+// Tier 是符号的可见级别。
+const (
+	TierPublic  = "public"  // 外部（第三方）插件可用
+	TierBuiltin = "builtin" // 仅内核内置插件可用
+	TierBridge  = "bridge"  // 桥接运行时注入的装配点（插件业务代码不调）
+)
+
+// tierTable 对应 tools/apidoc/tiers.json 的结构。
+type tierTable struct {
+	Public struct {
+		Source  string   `json:"_source"`
+		Methods []string `json:"methods"`
+	} `json:"public"`
+	Bridge struct {
+		Doc     string   `json:"_doc"`
+		Source  string   `json:"_source"`
+		Methods []string `json:"methods"`
+	} `json:"bridge"`
+	TierOverrides map[string]json.RawMessage `json:"tier_overrides"`
+	Interfaces    map[string]json.RawMessage `json:"interfaces"`
+}
+
+// applyTiers 把能力分层写回符号。分层表与源码一样是事实源：
+// 找不到分层表就报错，不静默降级——否则文档会悄悄丢掉「仅内置」标记。
+func applyTiers(p *Package) error {
+	path := tierPath()
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return fmt.Errorf("读取 %s: %w", path, err)
+	}
+	var t tierTable
+	if err := json.Unmarshal(data, &t); err != nil {
+		return fmt.Errorf("解析 %s: %w", path, err)
+	}
+
+	pub := map[string]bool{}
+	for _, m := range t.Public.Methods {
+		pub[m] = true
+	}
+	brg := map[string]bool{}
+	for _, m := range t.Bridge.Methods {
+		brg[m] = true
+	}
+
+	// tier_overrides 里既有 "_doc" 这类说明键（值是数组），也有真正的裁定
+	// （值是对象）。逐一解码，跳过 _ 开头的说明键。
+	overrides := map[string]struct {
+		Tier   string `json:"tier"`
+		Reason string `json:"reason"`
+	}{}
+	for name, raw := range t.TierOverrides {
+		if len(name) > 0 && name[0] == '_' {
+			continue
+		}
+		var v struct {
+			Tier   string `json:"tier"`
+			Reason string `json:"reason"`
+		}
+		if err := json.Unmarshal(raw, &v); err != nil {
+			return fmt.Errorf("tier_overrides[%s]: %w", name, err)
+		}
+		overrides[name] = v
+	}
+
+	// 接口级裁定先落到接口本身；其方法继承接口的 tier。
+	ifaceTier := map[string]string{}
+	for name, raw := range t.Interfaces {
+		if len(name) > 0 && name[0] == '_' {
+			continue
+		}
+		var v struct {
+			Tier string `json:"tier"`
+		}
+		if err := json.Unmarshal(raw, &v); err != nil {
+			return fmt.Errorf("interfaces[%s]: %w", name, err)
+		}
+		ifaceTier[name] = v.Tier
+	}
+
+	tierOf := func(s Symbol) (string, string) {
+		// 1) 逐符号覆盖优先（它带 reason，最有信息量）。
+		if o, ok := overrides[s.Name]; ok {
+			return o.Tier, o.Reason
+		}
+		// 2) 接口方法：跟随接口的 tier。
+		if s.Recv != "" {
+			if tier, ok := ifaceTier[s.Recv]; ok {
+				return tier, fmt.Sprintf("接口 %s 的层级裁定", s.Recv)
+			}
+		}
+		// 3) 桥接注入点。
+		if brg[s.Name] {
+			return TierBridge, "桥接运行时注入点（由 hmapdev 生成的 proc_main 调用，插件业务代码不调用）"
+		}
+		// 4) 显式公开名单。
+		if pub[s.Name] {
+			return TierPublic, "桥接模板注入或 proc* 实现，外部插件可用"
+		}
+		// 5) 公开包里的方法默认公开；内部专有符号不会出现在本包里。
+		if s.Recv == "PluginSDK" || s.Recv == "StageContext" {
+			return TierPublic, "公开 SDK 的方法，未列入 bridge/内置清单"
+		}
+		return TierPublic, ""
+	}
+
+	for i := range p.Symbols {
+		tier, reason := tierOf(p.Symbols[i])
+		p.Symbols[i].Tier = tier
+		p.Symbols[i].BuiltinOnly = tier == TierBuiltin
+		p.Symbols[i].TierReason = reason
+	}
+	for i := range p.Interfaces {
+		if tier, ok := ifaceTier[p.Interfaces[i].Name]; ok {
+			for j := range p.Interfaces[i].Methods {
+				p.Interfaces[i].Methods[j].Tier = tier
+				p.Interfaces[i].Methods[j].BuiltinOnly = tier == TierBuiltin
+			}
+		}
+	}
+	return nil
+}
+
+// tierPath 找 tiers.json：先看可执行文件旁，再看源码目录，最后看工作目录。
+// 这样 `go run ./tools/apidoc` 与编译后的二进制都能找到它。
+func tierPath() string {
+	candidates := []string{}
+	if exe, err := os.Executable(); err == nil {
+		candidates = append(candidates, filepath.Join(filepath.Dir(exe), "tiers.json"))
+	}
+	candidates = append(candidates,
+		filepath.Join("tools", "apidoc", "tiers.json"),
+		"tiers.json",
+	)
+	for _, c := range candidates {
+		if _, err := os.Stat(c); err == nil {
+			return c
+		}
+	}
+	return candidates[0]
+}