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-10-03 23:54:12 +00:00 · 2026-09-24 12:08:37 +08:00
parent e97cafc8de
commit 0a6e2b7dc4
35 changed files with 8141 additions and 0 deletions
--- a/docs/guide/capability-boundary.md
+++ b/docs/guide/capability-boundary.md
@ -0,0 +1,75 @@
+# 能力边界：哪些 API 外部插件能用
+
+HomeAgent 有两类插件：
+
+| 类型 | 说明 | 分发 |
+|---|---|---|
+| **外部插件** | 第三方开发，编译成 `.hmap` 后安装 | 独立分发，**可闭源** |
+| **内置插件** | 编译进内核，`init()` 自注册 | 随内核发行，需合入主仓 |
+
+SDK 包是**同一个** `gitcode.com/JianFeeeee/homeagent-sdk/sdk`，但两类插件拿到的
+**能力不同**：外部插件跑在独立进程里，由内核通过桥接注入能力（IPC，不是共享内存里的直接调用）。
+
+本页说明边界在哪、为什么，以及**怎么在写代码前就知道某个 API 是否可用**。
+
+## 一句话规则
+
+> **公开 SDK 包里声明的符号，不等于外部插件拿得到。**
+
+原因是：有些能力只有进程内的内置插件才可能拥有（比如直接读事件发布通道、
+直接注入到内核 IO 层）。外部插件通过桥接运行时拿到的是一份**受注入的能力集合**。
+
+## 外部插件**不可用**的 API
+
+这些 API 在公开包里存在，但在外部插件路径上拿不到。文档里每条都带
+<span class="api-badge api-badge-builtin">仅内置</span> 标记，
+完整清单见 [仅内置插件可用](../api/builtin-only.md)。
+
+| API | 外部插件的实际情况 | 该用什么 |
+|---|---|---|
+| `sdk.PluginSDK.Events()` | **恒为 nil**。桥接运行时不注入 event subscriber（`SetEventSubscriber` 全仓无调用点） | 桥接运行时已按你的声明完成 `events.subscribe`；Lua 插件用 `sdk.events.subscribe` |
+| `sdk.PluginSDK.SetEventSubscriber` | 无人调用 | 同上 |
+| `UnregisterOutputChannel` | 桥接只注入 registrar、**不注入 unregistrar**，调用是**静默无效**（返回 nil，不报错也不注销） | `RegisterOutputChannel` 可用；注销需重载插件 |
+| `SocialAPI` 的写操作 | 公开接口只有 6 个**只读**方法 | 读用 `s.GetPerson` 等；写需内置插件 |
+| `EventSubscriber.Publish` | 公开接口**刻意只有 Subscribe**，没有 Publish | 只订阅 |
+| `PriorityL4` | 声明会被内核**夹到 L3** | 用 L1–L3 |
+| `RegisterChannel` / `ListChannels` / `OutputChan` / `InjectInput` / `InjectInterrupt` | 只存在于内核内部 SDK | `RegisterInputChannel` / `RegisterOutputChannel` / `InjectText` 等公开方法 |
+| `PluginMgr()` 的完整能力 | 公开 `PluginMgrAPI` **只有 3 个方法**（`ReloadOne` / `ListLoadedPlugins` / `IsPluginDisabled`） | 就这 3 个；`ReloadPlugins`/`Disable`/`Remove` 属内部接口 |
+
+!!! warning "两处常见的文档错误（本站已更正）"
+    1. **`PluginMgr()` 不是「仅内置可用」**。桥接模板显式注入了它
+       （`base.SetPluginMgrAPI(procPluginMgr{})`），公开 `PluginMgrAPI` 也注明
+       「外部插件可调用」。真正的区别是**方法数量**：公开面 3 个，内部面 9 个。
+       容易混淆是因为两个包里有**同名但不同**的接口：
+       `sdk.PluginMgrAPI`（3 方法）与 `internal/sdk.PluginManager`（9 方法）。
+    2. **`Events()` 恒为 nil 这件事以前没写清**。旧文档把 `Events()` 当作
+       可用的订阅入口，但桥接运行时不注入 subscriber。外部插件的事件订阅
+       实际由生成的运行时通过 `events.subscribe` 完成。
+
+## 判定依据来自哪里
+
+本站的「仅内置」标记不是猜的，逐条来自：
+
+1. **`tools/hmapdev/templates/proc_main.go.tmpl`** —— 外部插件运行时**实际注入**
+   哪些能力，看 `buildPluginSDK()` 里的 `base.Set*` 调用。
+2. **`internal/sdk`** —— 内置插件用的完整接口，与公开包对照。
+3. **内核 RPC 协议表**（`internal/plugin/proc/protocol.go`）—— 外部插件**能发哪些请求**。
+
+每条裁定的具体依据写在该 API 的告警框里，可以直接核对。
+
+## 怎么快速确认
+
+- 用 [API 搜索](../api/index.md) 搜 API 名或功能描述，带
+  <span class="api-badge api-badge-builtin">仅内置</span> 的就是外部不可用
+- 直接看 [仅内置插件可用](../api/builtin-only.md) 汇总页
+- 拿不准时，**读 `example/` 下的示例插件** —— 它们全是外部插件，
+  能被它们编译通过的写法，外部就一定可用
+
+## 为什么这样设计
+
+不是为了限制，而是**IPC 边界决定了能力边界**：外部插件跑在独立进程里，
+内核只能通过显式的注入点把能力交过去。凡是需要「持有内核内部数据结构」
+的能力（事件发布通道、IO 通道、插件注册表全量操作），进程外都无法安全暴露。
+
+这套边界同时带来好处：插件崩溃不会带崩内核（进程隔离），
+以及**插件可以闭源**（SDK 是 MIT，见[首页](../index.md#_3)）。
--- a/docs/guide/first-lua-plugin.md
+++ b/docs/guide/first-lua-plugin.md
@ -0,0 +1,111 @@
+# 第一个 Lua 插件
+
+Lua 插件适合**轻量、快速原型**：不需要 Go 编译环境，改完重启内核即可生效。
+但它有一个必须理解的限制 —— 执行模型是**被动回调**。
+
+## 执行模型（先读这段）
+
+Lua 插件跑在内核进程内的 gopher-lua 解释器里（单 Lua 状态 + 互斥锁）：
+
+- **被动回调**：`main.lua` 只在加载时执行一次。此后工具、阶段钩子、
+  输入输出通道全部由内核事件驱动回调你的 Lua 函数。**插件不能自己启动后台任务。**
+- **没有并发**：Lua 侧没有 goroutine、协程调度，也没有 `os` / `io` 库和 socket 监听。
+  唯一主动出站通道是 `sdk.http.get/post`（同步请求）。
+- **任何阻塞循环都会持锁卡死该插件的全部调用。**
+
+!!! warning "要常驻服务就用 Go 插件"
+    需要监听端口、后台轮询、定时任务的，请用 [Go 插件](first-plugin.md)
+    （可自行启动 goroutine）。Lua 侧的等价做法是**事件驱动**：把逻辑挂在
+    工具、阶段钩子或通道回调上。
+
+## 生成工程
+
+```bash
+hmapdev init myluaplugin --lua
+cd myluaplugin
+```
+
+结构：
+
+```
+myluaplugin/
+├── plg.json    — entry: "main.lua", targets: "lua"
+├── main.lua    — 插件实现
+├── sdk.lua     — SDK 模拟层（支持独立测试）
+└── README.md
+```
+
+## 一个完整的插件
+
+```lua
+-- main.lua
+local plugin = {
+  name = "myluaplugin"
+}
+
+function plugin.start(sdk)
+  sdk.log("info", "myluaplugin starting...")
+
+  sdk.register_tool("myluaplugin_hello", {
+    description = "向指定的人打招呼",
+    parameters = {
+      type = "object",
+      properties = {
+        who = { type = "string", description = "要打招呼的对象" }
+      },
+      required = { "who" }
+    }
+  }, function(args)
+    return { content = "hello, " .. (args.who or "world") .. "!" }
+  end)
+
+  sdk.log("info", "myluaplugin started")
+end
+
+function plugin.stop()
+  sdk.log("info", "myluaplugin stopped")
+end
+
+return plugin
+```
+
+## 本地测试
+
+`sdk.lua` 是纯 Lua 的 SDK 模拟实现，可以直接用解释器跑：
+
+```bash
+lua main.lua
+# [lua-plugin] info: myluaplugin starting...
+# [lua-plugin] register_tool: myluaplugin_hello
+# [lua-plugin] info: myluaplugin started
+```
+
+在内核里运行时，`sdk.*` 由 Go 层注入，`sdk.lua` 里所有 `-- !impl` 标记的函数
+会被替换成真实实现。
+
+## API 约定的两点
+
+- **注册类函数调用即时报错**（抛 Lua error）—— 注册失败不会静默。
+- **数据类函数统一返回 `(result, err)`**，`err` 为 nil 表示成功。
+  核心未装配的子系统（如 SocialAPI）返回空值而非报错。
+
+Lua 侧的 `sdk.*` 能力与外部 Go 插件对齐至 SDK 1.3.0（需内核 1.4.0+）。
+
+!!! note "历史提醒"
+    1.1–1.3 期间，媒体 / 注入标志位 / 优先级能力只在 Go 侧有，Lua 侧静默缺失。
+    现已全量对齐，并由 `internal/plugin/lua_surface_test.go` 的契约测试守住
+    「`sdk.lua` 承诺的每个函数都有运行时绑定」。
+
+## 构建
+
+```bash
+hmapdev build          # → dist/myluaplugin_lua.hmap
+```
+
+Lua 插件直接打包源码，不经过编译。
+
+## 下一步
+
+- [能力边界](capability-boundary.md) —— Lua 与 Go 外部插件的能力面一致
+- [打包与发布](packaging.md)
+- [示例](../examples/index.md) —— `example/luademo` 是 Lua 版参考实现
--- a/docs/guide/first-plugin.md
+++ b/docs/guide/first-plugin.md
@ -0,0 +1,162 @@
+# 第一个 Go 插件
+
+以下是一个**能直接跑起来**的最小插件：注册一个工具、声明一项配置、处理停止与卸载。
+
+## 1. 生成工程
+
+```bash
+hmapdev init myplugin
+cd myplugin
+```
+
+生成的结构：
+
+```
+myplugin/
+├── plg.json       — 插件元信息（名称、版本、入口、目标平台）
+├── plugin.go      — 插件实现
+├── go.mod         — 模块定义
+├── README.md
+└── thirdpart/     — 外部源码存放目录（可选）
+```
+
+`hmapdev build` 时会在构建目录自动生成子进程运行时（`z_proc_gen.go` 等），
+**不需要手工创建，也不要提交**。
+
+## 2. 插件实现
+
+插件的全部契约是一个 `Plugin` 接口（[API 参考](../api/lifecycle.md#plugin)）：
+
+| 方法 | 何时调用 |
+|---|---|
+| `Name() string` | 内核需要标识这个插件时 |
+| `Start(*sdk.PluginSDK) error` | 插件加载后。**在这里注册工具、通道、配置** |
+| `Stop() error` | 插件停止时（重载、禁用、内核退出都会触发） |
+
+再加一个工厂函数。**名字必须是 `NewPluginFactory`** —— 生成的运行时按这个名字调用：
+
+```go
+func NewPluginFactory(name string, config map[string]interface{}) (sdk.Plugin, error) {
+    return &Plugin{name: name}, nil
+}
+```
+
+!!! warning "不要写成 `NewPlugin`"
+    生成的子进程运行时调用的入口是 `NewPluginFactory`。仓库里有 3 个早期示例
+    同时保留了两个名字（`NewPlugin` 只是遗留别名），但新插件只写
+    `NewPluginFactory` 即可。写错名字的后果是**编译能过、加载时找不到入口**。
+
+## 3. 一个完整的例子
+
+这是一个「打招呼」工具，带一项配置：
+
+```go
+package main
+
+import (
+	"fmt"
+
+	"gitcode.com/JianFeeeee/homeagent-sdk/sdk"
+)
+
+type Plugin struct {
+	name string
+	sdk  *sdk.PluginSDK
+}
+
+func (p *Plugin) Name() string { return p.name }
+
+func (p *Plugin) Start(s *sdk.PluginSDK) error {
+	p.sdk = s
+
+	// ① 声明配置项：内核会把它渲染到 WebUI 设置页
+	s.Settings().RegisterDef(sdk.ConfigDef{
+		Key:         "plugin.myplugin.greeting",
+		Default:     "hello",
+		Type:        "string",
+		DisplayName: "问候语",
+		Description: "打招呼时使用的前缀",
+		Category:    "myplugin",
+	})
+
+	// ② 注册工具：模型看到 Description 后决定是否调用
+	tp := p.name + "_"
+	s.RegisterTool(tp+"hello", sdk.ToolDef{
+		Name:        tp + "hello",
+		Description: "向指定的人打招呼",
+		Parameters: map[string]interface{}{
+			"type": "object",
+			"properties": map[string]interface{}{
+				"who": map[string]interface{}{
+					"type":        "string",
+					"description": "要打招呼的对象",
+				},
+			},
+			"required": []string{"who"},
+		},
+	}, p.handleHello)
+
+	// ③ 卸载（插件被删除）前清理自己产生的数据。
+	//    注意与 Stop 的区别：Stop 在每次重载时也会触发。
+	s.RegisterOnRemoveHandler(func() {
+		fmt.Printf("[%s] 清理数据\n", p.name)
+	})
+
+	return nil
+}
+
+func (p *Plugin) Stop() error { return nil }
+
+func (p *Plugin) handleHello(args map[string]interface{}) (interface{}, error) {
+	who, _ := args["who"].(string)
+
+	greeting := "hello"
+	if v, err := p.sdk.Settings().Get("plugin.myplugin.greeting"); err == nil && v != "" {
+		greeting = v
+	}
+
+	return map[string]interface{}{
+		"content": fmt.Sprintf("%s, %s!", greeting, who),
+	}, nil
+}
+
+func NewPluginFactory(name string, config map[string]interface{}) (sdk.Plugin, error) {
+	return &Plugin{name: name}, nil
+}
+```
+
+## 4. 工具返回值的两条约定
+
+`ToolHandler` 返回 `(interface{}, error)`，模型侧看到的是一条 tool message：
+
+- **正常结果**：返回一个 map，把要展示给模型的文本放在 `content` 字段。
+  未识别的字段也会一并传给模型，可以放结构化数据。
+- **业务失败**：返回 `map[string]interface{}{"isError": true, "content": "原因"}`
+  **并返回 nil error**。这样模型能看到失败原因并自行调整；
+  若返回 Go 的 `error`，那是**工具调用本身出错**，语义不同。
+
+```go
+func errorResult(msg string) map[string]interface{} {
+	return map[string]interface{}{"isError": true, "content": msg}
+}
+```
+
+## 5. 构建与安装
+
+```bash
+hmapdev build            # 默认产出多平台 bundle
+# → dist/myplugin_bundle.hmap
+
+hmapdev build --no-bundle  # 只构建当前平台
+# → dist/myplugin_linux_amd64.hmap
+```
+
+安装到内核：在 WebUI 的插件管理页上传 `.hmap`，或从 URL / 本地路径安装。
+详见 [打包与发布](packaging.md)。
+
+## 下一步
+
+- [能力边界](capability-boundary.md) —— 哪些 API 外部插件能用
+- [工具（Tools）](../api/tools.md) —— `ToolDef` 的完整字段
+- [记忆（Memory）](../api/memory.md) —— 让插件读写长期记忆
+- [示例插件](../examples/index.md) —— `example/memo` 是个完整的可读实现
--- a/docs/guide/getting-started.md
+++ b/docs/guide/getting-started.md
@ -0,0 +1,62 @@
+# 环境与工具链
+
+`hmapdev` 是 SDK 仓提供的统一插件开发工具链，Go 与 Lua 两种插件都用它，
+最终产出 `.hmap` 插件包（工具名即取自这个包格式）。
+
+!!! note "改名说明"
+    1.2.0 起工具链由 `plugindev` 更名为 `hmapdev`；SDK 存储目录同时由
+    `~/.homeagent/plugindev/sdk` 迁到 `~/.homeagent/hmapdev/sdk`
+    （旧目录会自动继续沿用）。
+
+## 安装
+
+从源码构建：
+
+```bash
+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` 字段
+选择版本。两者**必须**一致，否则编译出的插件与内核协议可能错配。
+
+```bash
+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`。这是有意的：静默降级会产出与内核
+    协议不匹配的插件，那种失败要到运行时才暴露。
+
+## 源码调试
+
+不编译直接跑插件源码，输出调用轨迹：
+
+```bash
+hmapdev debug [dir]   # dir 默认当前目录
+```
+
+写 Lua 插件时更简单——`sdk.lua` 是 SDK 模拟层，可以直接用解释器跑：
+
+```bash
+lua main.lua
+```
+
+## 下一步
+
+- [第一个 Go 插件](first-plugin.md)
+- [第一个 Lua 插件](first-lua-plugin.md)
--- a/docs/guide/multi-platform.md
+++ b/docs/guide/multi-platform.md
@ -0,0 +1,56 @@
+# 多平台构建
+
+## 默认就是多平台
+
+`hmapdev build` 默认 bundle 模式，一次产出含三个平台的单个 `.hmap`：
+
+```
+dist/myplugin_bundle.hmap
+  └── plugin.bin.linux.amd64
+  └── plugin.bin.darwin.amd64
+  └── plugin.bin.windows.amd64
+```
+
+安装时内核挑当前平台那份，重命名为 `plugin.bin`。
+
+## 逐平台构建
+
+```bash
+hmapdev build --no-bundle        # 按 plg.json 的 targets 构建
+hmapdev build --target linux/arm64   # 追加一个目标
+```
+
+`plg.json` 里声明目标：
+
+```json
+{
+  "name": "myplugin",
+  "version": "1.0.0",
+  "targets": "linux/amd64,windows/amd64"
+}
+```
+
+单平台输出文件名：`{name}_{os}_{arch}.hmap`。
+
+## 交叉编译
+
+子进程插件**不再需要 cgo**，所以交叉编译不需要目标平台的 C 工具链 ——
+这是 v1.0.0 的收益之一。
+
+!!! note "bundle 模式忽略 `targets`"
+    固定构建 linux/amd64、darwin/amd64、windows/amd64。如果你只需要其中一个，
+    用 `--no-bundle` 更快。
+
+## 平台能力差异
+
+历史上有过一处真实的平台断层，现已消除：
+
+- **v1.0.0 之前**：Windows 上插件只看到 **3 个 stage 字段、且无法写回**。
+- **v1.0.0 起**：Windows 与其他平台**共用同一套 RPC 实现**，16 字段全可见 + 写回。
+
+因此**不必**为 Windows 写条件分支 —— 除非你的插件自己用了平台专有的外部命令。
+
+## 下一步
+
+- [打包与发布](packaging.md)
+- [环境与工具链](getting-started.md)
--- a/docs/guide/packaging.md
+++ b/docs/guide/packaging.md
@ -0,0 +1,114 @@
+# 打包与发布
+
+`hmapdev build` 一次完成编译与打包，产出 `.hmap` 分发包（zip 格式，内含
+`plugin.json` 清单 + 二进制）。
+
+## 命令
+
+```bash
+hmapdev build                      # 默认 bundle（多平台合集）
+hmapdev build --no-bundle          # 只构建 plg.json targets 里的平台
+hmapdev build --target linux/arm64 # 在 targets 基础上追加目标
+hmapdev build --outdir out         # 指定输出目录（默认 dist）
+hmapdev build --sdk-path <path>    # 覆盖 go.mod 的 replace 指向的 SDK
+hmapdev build --replace <mod@path> # 追加 go.mod replace（可多次）
+```
+
+执行流程：
+
+1. 读 `plg.json` 的 `targets` / `bundle` 决定构建目标
+2. 生成子进程运行时代码（`z_proc_gen.go`、`z_proc_shm_*.go`）
+3. **Go 插件**：`go build`（普通可执行文件，`CGO_ENABLED=0`）
+   **Lua 插件**：直接打包源码，不编译
+4. 生成 `plugin.json` 输出清单
+5. 打成 `.hmap`
+
+## 两个 JSON 的区别
+
+这一点经常混淆：
+
+| 文件 | 谁维护 | 作用 | 关键字段 |
+|---|---|---|---|
+| `plg.json` | **你** | 项目元信息，构建输入 | `targets`、`bundle` |
+| `plugin.json` | `hmapdev` 自动生成 | 构建产物清单 | `entry`、`platforms` |
+
+`plg.json` 里的 `sdk` 字段声明**本插件针对的 SDK 版本**；未命中本地 SDK 存储
+会明确报错（见[环境与工具链](getting-started.md)）。
+
+## 多平台（bundle）
+
+`build` 默认就是 bundle 模式：一次编译 linux/amd64、darwin/amd64、windows/amd64，
+产出一个含全部平台二进制的 `.hmap`；安装时内核挑当前平台那份。
+
+```bash
+hmapdev build              # → dist/myplugin_bundle.hmap
+hmapdev build --no-bundle  # → dist/myplugin_linux_amd64.hmap 等
+```
+
+!!! note "bundle 模式会忽略 `plg.json` 的 `targets`"
+    固定构建上述三个平台。交叉编译需要对应工具链（如 Linux 上构建 darwin 需要
+    clang / macOS SDK），缺工具链时会失败 —— 此时用 `--no-bundle` 只构建当前平台。
+
+bundle 包内按 `plugin.bin.<goos>.<goarch>` 区分，安装时重命名为 `plugin.bin`。
+
+## 产物形态
+
+子进程插件是**普通可执行文件**，不分平台后缀：
+
+| 平台 | 二进制 |
+|---|---|
+| Linux / macOS / Windows | `plugin.bin` |
+
+!!! warning "v1.0.0 破坏性变更：不再加载 `.so` / `.dll`"
+    外部插件从 C ABI 动态库改为**子进程 + 共享内存**。
+
+    - `plugin.so` / `plugin.dylib` / `plugin.dll` **不再被加载**。
+      新内核遇到旧产物会跳过并报可操作错误，不崩溃。
+    - **业务代码不用改一行** —— 公开 SDK 接口零改动，用新版 `hmapdev`
+      （原 `plugindev`）重编即可。
+    - `plg.json` 的 `entry` 字段对 Go 插件**已无意义**（写 `plugin.so` 也无妨），
+      现在只用于区分 Lua 插件。
+    - 产物不再需要 cgo，交叉编译无需目标平台 C 工具链。
+
+## 安装
+
+三种方式（`9876` 是 pluginmgr 的本地端口，默认只监听 `127.0.0.1`、无鉴权）：
+
+```bash
+# 从 URL 安装（仅 http/https，流式下载不落盘）
+curl -X POST http://127.0.0.1:9876/plugins \
+  -H "Content-Type: application/json" \
+  -d '{"url": "https://example.com/myplugin.hmap"}'
+
+# 从本地路径安装（读取文件，不移动原文件）
+curl -X POST http://127.0.0.1:9876/plugins \
+  -H "Content-Type: application/json" \
+  -d '{"path": "/path/to/myplugin.hmap"}'
+
+# 直接上传二进制
+curl -X POST http://127.0.0.1:9876/plugins \
+  --data-binary @dist/myplugin_bundle.hmap
+```
+
+安装后调用 `/api/v1/plugins/reload` 或重启内核生效。
+
+走 WebUI 的 HTTP API（默认 `8080`，需 `api_key` 鉴权，内部代理到 pluginmgr）：
+
+```bash
+curl -X POST http://127.0.0.1:8080/api/v1/plugins \
+  -H "Authorization: Bearer <api_key>" \
+  -H "Content-Type: application/json" \
+  -d '{"path": "/path/to/myplugin.hmap"}'
+```
+
+也可以在 WebUI 的插件管理页面上传。
+
+## 发布前自查
+
+- [ ] `plg.json` 的 `sdk` 版本与目标内核匹配
+- [ ] `version` 已递增（内核按版本判断是否需要重装）
+- [ ] 若插件有外部状态，`SetAutoRestart(false)` 或在 `Start` 里重建连接
+      （崩溃重启是**线性退避** 1s→2s→3s，5 分钟内第 4 次崩溃即停止，
+      见[生命周期](../api/lifecycle.md#pluginsdksetautorestart)）
+- [ ] `RegisterOnRemoveHandler` 里清理自己写下的数据文件
+- [ ] 在 `-race` 下跑一遍：插件的 `Start` 与工具的并发访问是最常见的竞态来源
--- a/docs/guide/security.md
+++ b/docs/guide/security.md
@ -0,0 +1,81 @@
+# 受限 SDK 与安全
+
+外部插件与内置插件的区别不只是「能不能调某个函数」，还包含一层**安全边界**：
+外部插件的进程不共享内核地址空间，能力通过显式注入点交过去。
+
+## 三层隔离
+
+| 层 | 机制 | 防住了什么 |
+|---|---|---|
+| **进程** | 插件跑在独立子进程 | 插件 panic / 内存越界**不会带崩内核** |
+| **能力** | 只注入显式声明的接口 | 插件拿不到未授权的内核内部结构 |
+| **权限** | 公开接口是内部接口的**只读子集** | 插件无法改写他人数据 |
+
+第一种是 v1.0.0 从 C ABI 动态库改为子进程 + 共享内存的直接收益：
+在此之前，插件 panic 会带崩 `homed`。
+
+## 受限接口是怎么实现的
+
+**按接口裁剪，而不是按方法裁剪。** 同一个概念在公开包与内部包里是**两个不同的
+接口声明**，公开的那个只保留安全子集：
+
+```go
+// 公开 SDK：6 个只读方法
+type SocialAPI interface {
+    GetPerson(name string) (*PersonProfile, error)
+    GetTrait(name, trait string) (string, bool)
+    GetRelations(name string) ([]SocialRelation, error)
+    GetNetwork(name string, depth int) ([]*PersonProfile, error)
+    ListPersons() ([]string, error)
+}
+```
+
+写操作只在内核内部接口里。这样外部插件**在类型层面就调不到**，
+不是靠运行时检查拦截。
+
+同理，`EventSubscriber` 公开版**刻意只有 `Subscribe`，没有 `Publish`**：
+
+```go
+// 插件可以订阅，但由内核决定投递哪些事件
+type EventSubscriber interface {
+    Subscribe(eventType EventType, handler EventHandler) func()
+}
+```
+
+## 进程边界带来的约束
+
+事件订阅是理解这层边界的典型例子。公开包里有一个 `Events() EventSubscriber`，
+但**外部插件拿到的恒为 nil** —— 桥接运行时不注入它（`SetEventSubscriber`
+在全仓没有调用点）。外部插件的事件订阅由生成的运行时通过 `events.subscribe`
+RPC 完成，Lua 插件走内部 SDK 的 `Subscribe`。
+
+这不是缺陷，而是进程边界的结果：跨进程无法共享内核的事件发布通道。
+详见[能力边界](capability-boundary.md)。
+
+## 共享内存中的数据面
+
+工具调用帧、Cleaner、输入输出通道、媒体块、文档与知识正文**都走共享内存**，
+RPC 只传偏移描述符。因此：
+
+- 大对象不经 JSON 序列化，避免了大 payload 的性能与内存放大；
+- StageContext 在同一份状态上读改写，消除了副本模型的 lost update
+  （实测由 35.8~36.8% 降到 0）。
+
+`SharedRef`（共享内存描述符）是**内部实现细节**，插件开发者看不到它 ——
+公开 SDK 只暴露普通字符串与 map。
+
+## 插件作者的实践建议
+
+- **不要在 `Start` 里长时间阻塞** —— 内核在等待它返回。
+- **工具处理器要可并发**：模型可能并发发起多个调用；共享状态用锁保护
+  （`example/memo` 用 `sync.RWMutex`）。
+- **写文件用原子替换**（临时文件 + rename），避免进程被强杀时截断数据。
+- **声明 `NoMemory`**：定时提醒、连接状态这类不是对话内容的东西，
+  别让它们污染记忆（`InjectOptions{NoMemory: true}`）。
+- **在 `-race` 下测**：插件重载瞬间的并发访问是历史高发缺陷。
+
+## 许可与分发
+
+SDK 是 **MIT**，插件可以**闭源分发**，可商用、可私有，无需回馈。
+这是刻意的：SDK 随插件静态链接（源码进入插件二进制），用传染性许可会
+强迫插件开源。内核本身是 AGPL-3.0-only，但那是内核的许可，与外部插件无关。