agentworkshop 0.3.0 → 0.4.0

package/docs/plugins.md

@@ -1,8 +1,9 @@
-# AgentWorkShop 插件开发指南（SDK）
+# AgentWorkShop 插件开发指南
 
 > 插件 = 配置根 `plugins/<name>/` 下的一个 node 项目。基于内置 SDK 的生命周期钩子,
-> 可以同时增强**服务端**(数据/事件/API)与**浏览器**(面板/遥测/交互)。
+> 同时增强**服务端**(数据/事件/API)与**浏览器**(面板/遥测/交互)。
 > 与 `aw` 指令同哲学:放入目录即装载,约定优于配置。
+> SDK 全部成员的逐项详解见 [sdk.md](./sdk.md)——本文聚焦插件视角的装配与生命周期。
 
 ## 一、快速开始
 
@@ -22,9 +23,26 @@ plugins/my-plugin/
 └── README.md
 ```
 
-## 二、插件契约
+## 二、装载流程(项目启动时自动发现)
 
-`index.mjs` 导出**普通对象**(零导入依赖——ctx 由宿主注入,这是全局安装零解析链约束下的标准形态;TypeScript 作者可 `import type { definePlugin } from 'agentworkshop/sdk'` 获得类型提示,构建期擦除):
+```
+服务启动(nitro 插件 server/plugins/aw-plugins.ts)
+  └─ 宿主扫描(双作用域,同名项目级覆盖用户级)
+       ├─ <检出>/.AgentWorkShop/plugins/*/index.mjs   (project)
+       └─ ~/.AgentWorkShop/plugins/*/index.mjs        (user / AW_HOME 重定向)
+  └─ 逐插件: 动态 import → 形态校验 → createPluginContext → setup(ctx)
+  └─ 注册插件路由(/api/plugins/<name>/**) + 解析客户端入口
+  └─ emit plugin:host:init
+```
+
+- **错误隔离**:单插件装载/执行失败记入 `failures` 并告警,绝不拖垮主服务。
+- **修改插件文件后需重启服务**(插件目录不在热更新监听范围)。
+- 客户端插件由 `app/plugins/aw-plugins.client.ts` loader 在浏览器侧动态装载,互不影响。
+
+## 三、插件契约
+
+`index.mjs` 导出**普通对象**(零导入依赖——`ctx` 由宿主注入;TypeScript 可 type-only
+导入 `agentworkshop/sdk` 获得类型,运行时擦除):
 
 ```js
 export default {
@@ -39,51 +57,89 @@ export default {
 }
 ```
 
-## 三、服务端 ctx(SDK 注入)
-
-| 成员 | 说明 |
-|---|---|
-| `ctx.name / scope('project'\|'user') / dir` | 身份 |
-| `ctx.hooks` | 全局 HookBus:`on / once / off / emit`(异步串行、错误隔离、`*` 通配、连续失败熔断) |
-| `ctx.logger` | `debug/info/warn/error`,自动带插件名前缀 |
-| `ctx.config.get(key) / all()` | 有效配置只读(四层引擎) |
-| `ctx.kv` | 插件私有持久化:`get/set/all/bump`(内存态 + 200ms 防抖落盘 `data/plugins/<name>/kv.json`,高频钩子零竞态) |
-| `ctx.route(method, path, handler)` | 注册插件 API → `**/api/plugins/<name><path>**` |
-| `ctx.http.get/post(url, …)` | 带超时 fetch(仅 http/https,拒绝其他协议) |
-| `ctx.events.on(type, fn)` | scene 实时事件订阅(`event:*` 桥的糖) |
-| `ctx.paths` | `{ home, configRoot, dataDir }` |
-
-## 四、生命周期钩子(服务端)
-
-| 钩子 | 触发时机 | payload |
+## 四、服务端生命周期(完整)
+
+装载完成后,以下事件按业务发生顺序流经 `ctx.hooks`(**每个都可直接 `ctx.hooks.on` 消费**):
+
+### 4.1 `plugin:host:init`
+- **时机**:宿主装载完所有插件后(一次性)。
+- **payload**:`{ plugins: string[], failures: number }`。
+- **用途**:就绪自证;延迟初始化(依赖其他插件已注册路由的场景)。
+
+### 4.2 `daq:sample`
+- **时机**:数采**下发级**采样——与 WS `daq.reading` 同一点、按节点 `publishIntervalMs` 节拍。
+- **payload**:`{ nodeId, templateRef, value, state, at }`。
+- **用途**:越限告警、采样统计、实时联动。
+- **示例**:
+  ```js
+  ctx.hooks.on('daq:sample', (s) => {
+    if (s.value > (ctx.kv.get('threshold') ?? 180)) ctx.kv.bump('alarms')
+  })
+  ```
+
+### 4.3 `dcw:write`
+- **时机**:写控 ACK 之后(与运维入册同点、同 10s 去重节流)——**观察语义,不影响写控决策**。
+- **payload**:`{ nodeId, name, eng, prevValue, ok, source('manual'|'recipe'|'agent'|'rollback'), lineId, at }`。
+- **用途**:写审计、下发趋势、回写记录。
+
+### 4.4 `line:start` / `line:stop`
+- **时机**:产线开跑/停止(批次窗口开/闭)。
+- **payload**:`{ lineId, runId, recipeId?, productName? }` / `{ lineId, runId }`。
+- **用途**:批次开始联动、停线报告。
+
+### 4.5 `event:<type>` / `event:*`
+- **时机**:scene 全部实时事件(`device.created|updated|deleted`、`daq.reading`、
+  `daq.node.changed`、`daq.controller`、`ops.log` …)——与浏览器 WS 完全同源。
+- **消费**:`ctx.events.on('daq.reading', fn)`(糖衣)或 `ctx.hooks.on('event:daq.reading', fn)`。
+- **用途**:任意平台事件的观察与增强,无需自建 WS 连接。
+
+### 4.6 `config:changed`
+- **时机**:`runtime-settings.json` 变化(`aw config set` / 网页设置写入;宿主 fs.watch 防抖 300ms)。
+- **payload**:`{ at }`;配合 `ctx.config.get/all()` 读取新值。
+- **用途**:阈值热更新、联动参数刷新。
+
+### 4.7 `server:close`
+- **时机**:服务关闭——**先逐插件执行 `ctx.onDispose` 队列,再广播本事件**。
+- **payload**:`{ at }`。
+- **用途**:最终落盘、对外通知。
+
+## 五、服务端 ctx 全成员
+
+| 分组 | 成员 | 说明 |
 |---|---|---|
-| `plugin:host:init` | 宿主装载完所有插件后 | `{ plugins, failures }` |
-| `daq:sample` | DAQ 下发级采样(与 WS `daq.reading` 同点、同节拍) | `{ nodeId, templateRef, value, state, at }` |
-| `dcw:write` | 写控 ACK 后观察(与运维入册同点同去重) | `{ nodeId, name, eng, prevValue, ok, source, lineId, at }` |
-| `line:start` / `line:stop` | 产线开跑/停止 | `{ lineId, runId, recipeId? }` |
-| `event:<type>` / `event:*` | **scene 全部实时事件**(device.created · daq.node.changed · ops.log · daq.reading … 与 WS 同源) | 事件 payload |
-| `server:close` | 服务关闭 | `{ at }` |
-
-> v1 钩子为**观察语义**(不改变联锁/写控决策)。veto 类(拦截/改写)钩子在路线图中。
-
-## 五、浏览器增强(client.mjs)
-
-`client.mjs` 是**自包含 ESM**(不可用裸导入如 `vue`——浏览器原生动态加载),导出 `setup(ctx)`:
+| 身份 | `ctx.name / scope / dir / sdkVersion` | 插件名 / `'project'\|'user'` / 目录 / SDK 版本 |
+| 钩子 | `ctx.hooks` | HookBus:`on/once/off/emit`(异步串行、错误隔离、`'*'` 通配、连续失败 8 次熔断) |
+| 日志 | `ctx.logger` | `debug/info/warn/error`,自动前缀 `[插件名]` |
+| 配置 | `ctx.config.get(key)` / `all()` / `onChange(fn)` | 有效配置只读 + 变更订阅 |
+| 存储 | `ctx.kv.get/set/all/bump` | 插件私有 KV(内存态 + 200ms 防抖落盘,高频钩子零竞态) |
+| 定时 | `ctx.timer.setInterval/setTimeout` | **服务关闭自动回收**,杜绝定时器泄漏 |
+| 清理 | `ctx.onDispose(fn)` / `ctx.subscriptions.add(d)` | `server:close` 前逐个执行(先于广播) |
+| 路由 | `ctx.route(method, path, handler)` | 插件 API → `/api/plugins/<name><path>` |
+| 平台 | `ctx.api` | 平台 REST 客户端(自环 origin;鉴权端点 `ctx.api.setToken(token)`) |
+| 网络 | `ctx.http.get/post` | 通用请求(仅 http/https,默认 8s 超时) |
+| 事件 | `ctx.events.on(type, fn)` | scene 实时事件订阅 |
+| 路径 | `ctx.paths` | `{ home, configRoot, dataDir }` |
+
+> **鉴权说明**:`ctx.api` 自环调用遵循平台 REST 鉴权——免鉴权端点(manifest/ping)开箱即用;
+> 鉴权端点需 `ctx.api.setToken(token)`(token 可经 `AW_TOKEN` 环境变量注入插件)。
+> 仅需进程内数据时优先 `ctx.events`/`ctx.hooks`(零鉴权、零开销)。
+
+## 六、浏览器增强(client.mjs)
+
+`client.mjs` 为**自包含 ESM**(无裸导入),导出 `setup(ctx)`。loader
+(`app/plugins/aw-plugins.client.ts`) 启动期经 `/api/plugins/manifest` 发现并动态装载,
+事件与 WS 完全同源:
 
 | 成员 | 说明 |
 |---|---|
-| `ctx.on('daq:sample', fn)` / `ctx.on('event:daq.reading', fn)` / `ctx.on('*', fn)` | 实时事件订阅(与 WS 同源;另支持 `page:change`) |
+| `ctx.on(type, fn)` | `daq:sample` / `event:<type>` / `event:*` / `page:change` 订阅(pagehide 自动回收) |
+| `ctx.fetch(path, opt?)` | 同源平台 API(JSON + 信封解包,非 2xx 抛错) |
 | `ctx.el(tag, attrs, children)` | DOM 构建 |
-| `ctx.root()` | 插件私有挂载点(右下角,懒创建 `#aw-plugin-<name>`) |
-| `ctx.mount(target, node)` | 挂载到任意选择器/元素 |
-| `ctx.hooks` | 客户端本地 HookBus(`client:init` / `event:*` / `page:change`) |
-| `ctx.log` | 前缀 console |
-
-客户端脚本由服务端端点 `/api/plugins/client/<name>` 以 `text/javascript` 提供,应用启动时
-`aw-plugins.client.ts` loader 自动动态 import 并装载。
+| `ctx.root()` / `ctx.mount(target, node)` | 私有挂载点 / 任意位置挂载 |
+| `ctx.hooks` | 本地 HookBus(`client:init` / `page:change` / `client:destroy`) |
+| `ctx.dispose()` | 卸载(回收订阅 + 清空挂载点;pagehide 自动触发) |
 
 ```js
-// client.mjs
 export function setup(ctx) {
   const badge = ctx.el('div', { style: 'color:#35e0a0' }, ['⌁ 0'])
   ctx.root().append(badge)
@@ -92,36 +148,50 @@ export function setup(ctx) {
 }
 ```
 
-## 六、插件 API(增强后端)
+## 七、插件 API(增强后端)
 
 ```js
 ctx.route('GET', '/stats', () => ctx.kv.all())
-ctx.route('POST', '/reset', () => { ctx.kv.set('samples', 0); return { ok: true } })
+ctx.route('POST', '/reset', (event) => {
+  const body = event.awBody          // 宿主已预读 JSON body
+  ctx.kv.reset()
+  return { ok: true }
+})
 ```
 
-→ `GET/POST /api/plugins/my-plugin/stats|reset`。鉴权 v1 由插件自理(可在 handler 内复用
-`resolveUser(event)` 走业务鉴权)。
+→ `/api/plugins/<name><path>`。宿主 catchall 转发(exact-match),body 预读挂 `event.awBody`;
+v1 鉴权由插件自理(可在 handler 内 `resolveUser(event)` 复用业务鉴权)。
 
-## 七、完整示例
+## 八、真实案例:line-sentinel(产线哨兵)
 
-`sdk/examples/sample-insight/` —— 订阅采样计数 + 统计 API + 浏览器徽标:
+用户级安装,展示 SDK 全部能力面——源码 `~/.AgentWorkShop/plugins/line-sentinel/`:
 
-```bash
-cp -r sdk/examples/sample-insight ~/.AgentWorkShop/plugins/
-aw start   # → GET /api/plugins/sample-insight/stats · 浏览器右下角徽标
-```
+- **`ctx.api`**:启动读取平台产线清单(自环 REST)
+- **`ctx.hooks.on('daq:sample')`**:逐样本计数 + 越限告警(阈值可调)
+- **`ctx.hooks.on('line:start'/'line:stop')`**:运行态跟踪
+- **`ctx.config.onChange`**:配置热更新感知
+- **`ctx.timer`**:5s 心跳 + 免鉴权 manifest ping 自证 REST 通道
+- **`ctx.route`**:`GET /report` 综合报告、`POST /threshold` 阈值设置(`event.awBody`)
+- **`client.mjs`**:右下角实时徽标(样本数 + 告警数)
 
-## 八、发布与信任模型
+实测记录(dev 3127 / prod 3601 双形态):8 秒采样计数 288+、12 节点越限告警、
+心跳间隔 ~1s 内新鲜、浏览器徽标挂载零 pageerror。
 
-- 插件是**任意 node 代码**,与 aw commands 同信任模型:只安装/启用你信任的插件。
-- 插件随配置根走:repo 检出内 = `<repo>/.AgentWorkShop/plugins`(团队可 git 版本化);
-  全局安装 = `~/.AgentWorkShop/plugins`(AW_HOME 可重定向)。
-- 服务端生命周期结束(`server:close`)、卸载插件 = 直接删目录重启。
+## 九、调试与陷阱
 
-## 九、SDK 版本对照
+| 现象 | 原因 / 处理 |
+|---|---|
+| 改了插件代码没生效 | 插件目录不在热更新范围——**重启 `aw start` / `aw dev`** |
+| 客户端徽标没出现 | 打开浏览器 console 看 `[aw-plugins]` 告警;确认 manifest 中 `hasClient: true` |
+| 插件路由 404 | 路由为 exact-match;注意 method 与 path 前导 `/` |
+| `ctx.api` 鉴权 401 | 鉴权端点需 `ctx.api.setToken(token)`;免鉴权端点(manifest/ping)无需 |
+| 插件装载失败 | `aw dev/start` 启动日志有 `[aw-plugins] 装载失败` 详情;修复后重启 |
 
-| SDK | 随包 | 说明 |
-|---|---|---|
-| `sdk/hooks.mjs` | `agentworkshop/sdk`(0.2.2+) | HookBus(可独立用于任何 node 项目) |
-| `sdk/context.mjs` | 同上 | 服务端 ctx 工厂 + 路由表 + 插件校验 |
-| `sdk/client.mjs` | 同上 | 浏览器 ctx 工厂 |
+**信任模型**:插件是任意 node 代码,与 aw commands 同级——只安装/启用你信任的插件。
+
+## 十、发布与作用域
+
+- 用户级(全局):`~/.AgentWorkShop/plugins/` —— `AW_HOME` 可重定向。
+- 项目级(检出):`<repo>/.AgentWorkShop/plugins/` —— 团队可 git 版本化共享。
+- 同名指令式覆盖规则与 commands 一致:**项目级 > 用户级 > 内建**。
+- 卸载 = 删除目录后重启。

package/docs/sdk.md

@@ -0,0 +1,265 @@
+# AgentWorkShop SDK 开发与使用指南
+
+> SDK 是 AgentWorkShop 的**编程客户端与扩展基座**：外部项目经它消费平台 REST 服务；
+> 插件经它获得宿主注入的运行时上下文（钩子 / 配置 / 存储 / 定时器 / 平台 API / 事件流）。
+> 零第三方运行时依赖，Node ≥ 23.4 与现代浏览器双端可用。
+
+**版本**：与主包同步（`SDK_VERSION = 0.3.0`）· **协议**：ESM only
+**类型**：`agentworkshop/sdk` 自带 `index.d.mts`，TS 项目零配置获得完整提示。
+
+---
+
+## 1. 获取 SDK
+
+### 1.1 全局安装形态（含 CLI 与平台本体）
+
+```bash
+npm install -g agentworkshop
+```
+
+SDK 位于全局包内：`$(npm prefix -g)/node_modules/agentworkshop/sdk/`。
+插件**无需也不应该**直接 import 它（见 §2 的宿主注入模型），它主要服务两类人：
+
+- **外部项目集成**：把 AgentWorkShop 的产线/数采/写控/孪生能力嵌进你自己的 node 服务；
+- **插件开发**（TS）：仅导入类型获得完整 IntelliSense，运行时由宿主注入。
+
+### 1.2 项目依赖形态（推荐集成方）
+
+```bash
+npm install agentworkshop        # 作为依赖（含完整 SDK 与类型）
+```
+
+### 1.3 导入路径
+
+| 导入 | 内容 |
+|---|---|
+| `agentworkshop/sdk` | 全部门面（客户端 + 服务端 + 平台 REST 客户端 + 类型） |
+| `agentworkshop/sdk/client` | 仅浏览器端（`createClientContext`） |
+
+```js
+import { createPlatformClient, definePlugin, HookBus } from 'agentworkshop/sdk'
+```
+
+---
+
+## 2. 核心模型：两种身份，一个 SDK
+
+| 身份 | 形态 | SDK 的角色 |
+|---|---|---|
+| **外部集成者** | 普通依赖 | 直接调用 `createPlatformClient()` 消费平台 REST 面 |
+| **插件作者** | 导出 `{ name, setup(ctx) }` | `ctx` 即宿主注入的 SDK 上下文——**零导入依赖**，SDK 运行时由宿主提供 |
+
+> 为什么插件不直接 import SDK？全局安装的插件目录（`~/.AgentWorkShop/plugins/`）
+> 不在 node_modules 解析链上，宿主注入是唯一零坑形态（VSCode `activate(context)` 同范式）。
+
+---
+
+## 3. 平台 REST 客户端 `createPlatformClient`
+
+SDK 作为"项目服务客户端"的门面。自动携带鉴权、自动解包平台统一信封 `{ code, message, data } → data`、非 2xx 抛错（含 `err.status` 与 `err.body`）。
+
+### 3.1 创建
+
+```js
+import { createPlatformClient } from 'agentworkshop/sdk'
+
+const api = createPlatformClient({
+  baseUrl: 'http://127.0.0.1:3001',  // 缺省 ''（同源相对路径）；集成方填平台地址
+  token: '<bearer-token>',            // 可选；后续可 api.setToken() 更换
+  timeoutMs: 10_000,                  // 可选；单请求超时
+  logger,                             // 可选；请求失败时告警
+})
+```
+
+### 3.2 通用调用（任意平台路径）
+
+| 方法 | 签名 | 说明 |
+|---|---|---|
+| `api.call(method, path, body?)` | 底层 | 返回解包后的 `data` |
+| `api.get(path, query?)` | query 对象自动序列化 | `api.get('/api/workshop/dcw', { page: 1 })` |
+| `api.post(path, body?)` | JSON 序列化 | |
+| `api.patch(path, body?)` | | |
+| `api.delete(path)` | | |
+| `api.setToken(token)` | 链式 | 登录后 `api.setToken(res.token)` |
+
+### 3.3 资源面（开箱即用）
+
+| 资源 | 方法 |
+|---|---|
+| `api.users` | `login(email, password)` · `me()` · `list/get/create/update/remove` |
+| `api.lines` | CRUD + **`start(id, recipeId?)`** · `stop(id)` |
+| `api.products / api.recipes` | CRUD |
+| `api.dcwNodes` | 写控制节点 CRUD |
+| `api.daqNodes` | 数采节点 CRUD + `alarms()` |
+| `api.templates` | `daq()` / `dcw()` 信号模板注册表 |
+| `api.twins` | 数字孪生设备 CRUD |
+| `api.teams / api.agents / api.channels` | Agent 编组面 |
+| `api.plugins.manifest()` | 已装载插件清单（免鉴权） |
+| `api.ping()` | 存活探测（免鉴权） |
+
+### 3.4 示例：外部项目集成产线
+
+```js
+import { createPlatformClient } from 'agentworkshop/sdk'
+
+const api = createPlatformClient({ baseUrl: 'http://plant.local:3001' })
+
+const { token } = await api.users.login('you@example.com', 'secret')
+api.setToken(token)
+
+await api.lines.create({ name: '一号产线' })
+const line = (await api.lines.list())[0]
+
+await api.lines.start(line.id)                     // 开跑
+const nodes = await api.daqNodes.list({ lineId: line.id })
+console.log(`产线 ${line.name} 在线节点 ${nodes.filter(n => n.state !== 'offline').length}`)
+```
+
+---
+
+## 4. 插件上下文 `ctx`（完整成员）
+
+`setup(ctx)` 收到的 `ctx` 是宿主装配的 SDK 运行时。**全部成员一览**：
+
+| 分组 | 成员 | 类型 | 说明 |
+|---|---|---|---|
+| 身份 | `ctx.name` | `string` | 插件名（= 目录名/声明名） |
+| | `ctx.scope` | `'project' \| 'user'` | 装载作用域 |
+| | `ctx.dir` | `string` | 插件目录绝对路径 |
+| | `ctx.sdkVersion` | `string` | 宿主 SDK 版本 |
+| 钩子 | `ctx.hooks` | `HookBus` | 全局钩子总线（§5） |
+| 日志 | `ctx.logger` | `{ debug, info, warn, error }` | 自动前缀 `[插件名]` |
+| 配置 | `ctx.config.get(key)` | 任意 | 有效配置项（四层合并后） |
+| | `ctx.config.all()` | `Record<string, any>` | 全部有效配置快照 |
+| | `ctx.config.onChange(fn)` | 退订函数 | 订阅 `config:changed` |
+| 存储 | `ctx.kv.get(key)` / `set(key, v)` / `all()` / `bump(key, by?)` | | 插件私有 KV（内存态 + 200ms 防抖落盘，防竞态） |
+| 定时 | `ctx.timer.setInterval(fn, ms)` / `setTimeout(fn, ms)` | id | **服务关闭自动回收**，无需手动 clear |
+| 清理 | `ctx.onDispose(fn)` / `ctx.subscriptions.add(d)` | | 登记 `server:close` 时执行的清理 |
+| 路由 | `ctx.route(method, path, handler)` | boolean | 注册插件 API → `/api/plugins/<name><path>` |
+| 平台 | `ctx.api` | `PlatformClient` | 自环 REST 客户端（origin 由宿主权威解析） |
+| 网络 | `ctx.http.get(url)` / `post(url, body)` | `Response` | 通用请求（**仅 http/https**，8s 默认超时） |
+| 事件 | `ctx.events.on(type, fn)` / `off` | 退订函数 | scene 实时事件订阅（§5 `event:*` 糖衣） |
+| 路径 | `ctx.paths` | `{ home, configRoot, dataDir }` | 配置根信息（home 模式 = `~/.AgentWorkShop`） |
+| 数据 | `ctx.dataDir` | `string` | 插件私有数据目录（`data/plugins/<name>`） |
+
+### 4.1 `ctx.hooks` — 钩子总线
+
+```js
+const off = ctx.hooks.on('daq:sample', (sample) => {
+  ctx.kv.bump('samples')
+})
+ctx.hooks.once('server:close', () => { /* 收尾 */ })
+ctx.hooks.off('daq:sample', handler)   // 手动解绑
+await ctx.hooks.emit('my-plugin:custom', { hello: 1 })  // 插件间通信(其他插件可监听)
+```
+
+- **异步串行**：同 type 监听器按注册序 `await`，返回值链式传递（waterfall）。
+- **错误隔离**：单监听器抛错只计数告警，不影响兄弟监听器与主服务。
+- **熔断**：同一监听器连续失败 ≥ 8 次自动摘除（防病态插件刷屏）。
+- **`'*'` 通配**：`ctx.hooks.on('*', ({ type, payload }) => …)` 收全部事件。
+
+### 4.2 `ctx.kv` — 插件私有持久化
+
+- 存储位置：`<配置根>/data/plugins/<name>/kv.json`（200ms 防抖原子写盘）。
+- **内存态为准**：高频钩子（`daq:sample`）与低频钩子（`line:stop`）并发调用无读改写竞态。
+- 典型用途：计数器、告警状态、阈值配置、心跳时间戳。
+
+### 4.3 `ctx.timer` / `ctx.onDispose` — 生命周期安全的后台工作
+
+```js
+ctx.timer.setInterval(() => ctx.kv.set('heartbeat', Date.now()), 5000)  // 关闭自动回收
+ctx.onDispose(() => ctx.logger.info('插件清理完成'))                     // 显式清理登记
+```
+
+服务关闭序列：**先逐插件执行 onDispose 队列（逐个 try/catch）→ 再广播 `server:close`**。
+
+### 4.4 `ctx.route` — 插件 API（增强后端）
+
+```js
+ctx.route('GET', '/stats', () => ctx.kv.all())
+ctx.route('POST', '/reset', (event) => {
+  const body = event.awBody        // 宿主已预读 JSON body
+  ctx.kv.reset()
+  return { ok: true }              // 返回值由 nitro 序列化为 JSON
+})
+```
+
+→ `GET /api/plugins/<name>/stats`。v1 鉴权由插件自理（handler 内可用 `resolveUser(event)` 复用业务鉴权）。
+
+### 4.5 `ctx.api` vs `ctx.http` vs `ctx.events` — 怎么选
+
+| 需求 | 用 | 原因 |
+|---|---|---|
+| 读/写**平台业务数据**（产线、节点、孪生…） | `ctx.api` | 鉴权/信封/资源语义开箱即用 |
+| 调**外部系统**（MES、webhook、邮件网关） | `ctx.http` | 通用请求 + 协议守卫 |
+| 对**实时流**做反应（采样、告警、启停） | `ctx.events` / `ctx.hooks.on` | 进程内直连，零 HTTP 开销 |
+
+> 鉴权说明：`ctx.api` 自环调用遵循平台 REST 鉴权策略——免鉴权端点（manifest/ping）
+> 开箱即用；鉴权端点需 `ctx.api.setToken(token)`（token 可来自环境变量，如 `AW_TOKEN`）。
+> 服务端插件若仅需进程内数据，优先用 `ctx.events` 与 `ctx.hooks`（零鉴权、零开销）。
+
+---
+
+## 5. 生命周期事件（服务端，全部钩子）
+
+| 事件 | 触发时机 | payload | 典型用途 |
+|---|---|---|---|
+| `plugin:host:init` | 宿主装载完所有插件后 | `{ plugins: string[], failures: number }` | 就绪自证、延迟初始化 |
+| `config:changed` | `runtime-settings.json` 变化（`aw config set` / 设置页写入） | `{ at }` | 热更新阈值、刷新缓存的配置 |
+| `daq:sample` | 数采**下发级**采样（与 WS `daq.reading` 同点、按节点 publishIntervalMs 节拍） | `{ nodeId, templateRef, value, state, at }` | 越限告警、统计、联动 |
+| `dcw:write` | 写控 ACK 后观察（与运维入册同点、10s 去重） | `{ nodeId, name, eng, prevValue, ok, source, lineId, at }` | 写审计、趋势记录 |
+| `line:start` | 产线开跑 | `{ lineId, runId, recipeId, productName? }` | 批次开始联动 |
+| `line:stop` | 产线停止 | `{ lineId, runId }` | 批次收尾、报告生成 |
+| `event:<scene-type>` / `event:*` | scene 全部实时事件（`device.created` · `daq.node.changed` · `ops.log` …与 WS 同源） | 事件 payload | 任意平台事件的观察与增强 |
+| `server:close` | 服务关闭（disposables 回收之后） | `{ at }` | 最终落盘、对外通知 |
+
+> v1 钩子为**观察语义**——不改变联锁/写控决策；veto（拦截/改写）钩子在路线图。
+
+---
+
+## 6. 浏览器端 SDK（`agentworkshop/sdk/client`）
+
+插件 `client.mjs`（自包含 ESM，**无裸导入**）导出 `setup(ctx)`，由宿主 loader 动态装载：
+
+```js
+export function setup(ctx) {
+  const badge = ctx.el('div', { style: 'color:#35e0a0' }, ['⌁ 0'])
+  ctx.root().append(badge)                       // 私有挂载点(右下角)
+  let n = 0
+  ctx.on('daq:sample', () => { badge.textContent = `⌁ ${++n}` })
+  ctx.on('page:change', ({ path }) => ctx.log.info('page →', path))
+}
+```
+
+| 成员 | 说明 |
+|---|---|
+| `ctx.on(type, fn)` | 实时事件订阅（`daq:sample` / `event:<type>` / `event:*` / `page:change`），**pagehide 自动回收** |
+| `ctx.fetch(path, opt?)` | 同源平台 API 助手（自动 JSON + 信封解包；非 2xx 抛错） |
+| `ctx.el(tag, attrs, children)` | DOM 构建（style/class/事件 attrs 特判） |
+| `ctx.root()` | 插件私有挂载点 `#aw-plugin-<name>`（懒创建） |
+| `ctx.mount(target, node)` | 挂载到任意选择器/元素 |
+| `ctx.hooks` | 本地 HookBus（`client:init` / `page:change` / `client:destroy`） |
+| `ctx.dispose()` | 卸载：回收订阅 + 清空挂载点 + 广播 `client:destroy`（pagehide 自动触发，幂等） |
+
+---
+
+## 7. 类型与 TypeScript
+
+```ts
+import type { PluginDef, PluginContext, PlatformClient } from 'agentworkshop/sdk'
+
+export default {
+  name: 'typed-plugin',
+  async setup(ctx: PluginContext) {
+    const threshold: number = ctx.config.get('api.timeout')
+  },
+} satisfies PluginDef
+```
+
+运行时**不引入** SDK（保持零依赖形态）；类型在构建期擦除。
+
+## 8. 版本与兼容性策略
+
+- SDK 遵循 semver：patch = 修复；minor = 新增钩子/ctx 成员（向后兼容）；major = 破坏性契约变更。
+- `aw start` 启动时对配置根做校验与就地迁移——升级不丢数据。
+- 宿主在 ctx 中暴露 `ctx.sdkVersion`，插件可按版本特性降级。

package/i18n/locales/en.ts

@@ -23,6 +23,7 @@ export default {
     logs: 'Logs',
     users: 'Users',
     monitor: 'Runtime Monitor',
+    plugins: 'Plugins',
     settings: 'Settings',
   },
   header: {
@@ -1730,6 +1731,22 @@ export default {
     kvzhi95004: '{p0}✔ HITL 已应答:{p1}{p2}',
     ke67kwf005: '{p0}── 切换目标 · {\'$\'}{\'{\'}props.pid ? ',
   },
+  plugins: {
+    title: 'Plugins',
+    subtitle: 'Config-root plugins/ · toggles hot-reload instantly',
+    refresh: 'Refresh',
+    enabled: 'Enabled',
+    disabled: 'Disabled',
+    scopeProject: 'Project',
+    scopeUser: 'User',
+    hasClient: 'Client enhancer',
+    routes: 'API routes',
+    empty: 'No plugins yet — aw plugin create <name>, or aw plugin enable to turn on examples',
+    failures: 'Load failures',
+    loadFailures: '{n} plugin(s) failed to load, see server startup log',
+    enableFail: 'Toggle failed',
+    detail: 'Plugin detail',
+  },
   error: {
     backHome: 'Back to Home',
     lost: 'Page lost',

package/i18n/locales/zh-CN.ts

@@ -23,6 +23,7 @@ export default {
     logs: '日志管理',
     users: '用户管理',
     monitor: '运行时监控',
+    plugins: '插件管理',
     settings: '系统设置',
   },
   header: {
@@ -1729,6 +1730,22 @@ export default {
     kvzhi95004: '{p0}✔ HITL 已应答:{p1}{p2}',
     ke67kwf005: '{p0}── 切换目标 · {\'$\'}{\'{\'}props.pid ? ',
   },
+  plugins: {
+    title: '插件管理',
+    subtitle: '配置根 plugins/ 目录 · 启停即时热重载',
+    refresh: '刷新',
+    enabled: '已启用',
+    disabled: '已停用',
+    scopeProject: '项目级',
+    scopeUser: '用户级',
+    hasClient: '浏览器增强',
+    routes: 'API 路由',
+    empty: '暂无插件 —— aw plugin create <name> 创建,或 aw plugin enable 开启示例',
+    failures: '装载失败',
+    loadFailures: '{n} 个插件装载失败,详情见服务启动日志',
+    enableFail: '启停操作失败',
+    detail: '插件详情',
+  },
   error: {
     backHome: '返回首页',
     lost: '页面走失了',

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "agentworkshop",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "description": "AgentWorkShop 软件开发系统 - 基于 Nuxt 4 的配置驱动运行范式",
+  "license": "PolyForm-Noncommercial-1.0.0",
   "exports": {
     ".": {
       "types": "./sdk/index.d.mts",
@@ -41,7 +42,8 @@
     ".env.example",
     "README-zh.md",
     "docs/cli.md",
-    "docs/plugins.md"
+    "docs/plugins.md",
+    "docs/sdk.md"
   ],
   "packageManager": "pnpm@11.9.0",
   "engines": {

package/scripts/_dbg-docs-site-shot.mjs

@@ -0,0 +1,33 @@
+/**
+ * 文档站截图走查 — vitepress preview(127.0.0.1:4477)+ Edge + puppeteer-core。
+ * 用法:node scripts/_dbg-docs-site-shot.mjs
+ */
+import puppeteer from 'puppeteer-core'
+import fs from 'node:fs'
+
+const EDGE = 'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe'
+const BASE = 'http://127.0.0.1:4477/AgentWorkShop'
+const OUT = 'gui-test-screenshots/docs-site-v4'
+
+const PAGES = [
+  { name: "guide-getting-started", path: '/', width: 1440 },
+  { name: 'guide-getting-started', path: '/guide/getting-started', width: 1440 },
+  { name: 'license', path: '/guide/license', width: 1440 },
+]
+
+const main = async () => {
+  fs.mkdirSync(OUT, { recursive: true })
+  const browser = await puppeteer.launch({ executablePath: EDGE, headless: 'new' })
+  for (const p of PAGES) {
+    const page = await browser.newPage()
+    await page.setViewport({ width: p.width, height: 900, deviceScaleFactor: 1 })
+    await page.goto(`${BASE}${p.path}`, { waitUntil: 'networkidle0', timeout: 30000 })
+    await new Promise(r => setTimeout(r, 600))
+    await page.screenshot({ path: `${OUT}/${p.name}.png`, fullPage: true })
+    console.log('shot', p.name)
+    await page.close()
+  }
+  await browser.close()
+}
+
+main().catch(e => { console.error(e); process.exit(1) })