agentworkshop 0.2.2 → 0.3.0

package/package.json

@@ -1,8 +1,23 @@
 {
   "name": "agentworkshop",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "type": "module",
   "description": "AgentWorkShop 软件开发系统 - 基于 Nuxt 4 的配置驱动运行范式",
+  "exports": {
+    ".": {
+      "types": "./sdk/index.d.mts",
+      "default": "./sdk/index.mjs"
+    },
+    "./sdk": {
+      "types": "./sdk/index.d.mts",
+      "default": "./sdk/index.mjs"
+    },
+    "./sdk/client": {
+      "types": "./sdk/client.d.mts",
+      "default": "./sdk/client.mjs"
+    },
+    "./package.json": "./package.json"
+  },
   "bin": {
     "aw": "bin/aw.mjs",
     "agentworkshop": "bin/aw.mjs"

package/scripts/dev-guard.mjs

@@ -60,6 +60,19 @@ const devHost = String(eff.effective['server.host'] ?? '0.0.0.0')
 const portSource = eff.sources['server.dev.port']
 console.log(`[config] 开发端口 -> ${devPort} (source: ${portSource}${hasPort ? ', CLI 显式覆盖生效' : ''})`)
 
+// 端口注入 worker 环境链(PORT):CLI 显式值优先,否则引擎有效值 —— 与实际监听端口一致。
+// 插件宿主(经 PORT env)自环调用 ctx.api 依赖此值;注意 nuxt dev 会自行覆盖 PORT,
+// 因此必须在重入之前于顶层 guard spawn 时就位 —— 见文件头部 guard 块的 env 透传。
+const cliPort = (() => {
+  const i = rest.indexOf('--port')
+  if (i >= 0 && rest[i + 1]) return rest[i + 1]
+  const eq = rest.find(a => a.startsWith('--port='))
+  return eq ? eq.slice(7) : null
+})()
+const effectivePort = cliPort ?? devPort
+process.env.PORT = String(effectivePort)
+console.log(`[config] worker PORT env -> ${effectivePort}`)
+
 const inject = [...rest]
 if (!hasPort) inject.push('--port', String(devPort))
 if (!hasHost) inject.push('--host', devHost)

package/sdk/api.mjs

@@ -0,0 +1,101 @@
+// ============================================================
+// AgentWorkShop SDK — 平台 REST 客户端
+// ------------------------------------------------------------
+// SDK 作为项目服务的 client:对平台 REST 面(/api/**)的类型化轻封装。
+// 三个使用形态:
+//   1) 插件内:   ctx.api.lines.list()          —— 宿主注入(自环 origin)
+//   2) 外部脚本: createPlatformClient({ baseUrl, token }).daq.nodes()
+//   3) 浏览器:   createPlatformClient({ baseUrl: '' })  同源相对路径
+// 资源方法返回原始 JSON body(data 字段已解包);4xx/5xx 抛错(含 status)。
+// ============================================================
+
+export function createPlatformClient({ baseUrl = '', token, logger, timeoutMs = 10000 } = {}) {
+  // baseUrl 支持函数(延迟解析):插件宿主的监听端口在 nitro listen 钩子后才确定
+  const resolveBase = () => String(typeof baseUrl === 'function' ? baseUrl() : (baseUrl ?? '')).replace(/\/+$/, '')
+  let authToken = token ?? null
+
+  async function call(method, path, body, opt = {}) {
+    const base = resolveBase()
+    const headers = { accept: 'application/json', ...(opt.headers ?? {}) }
+    if (authToken) headers.authorization = `Bearer ${authToken}`
+    if (body !== undefined) headers['content-type'] = 'application/json'
+    const res = await fetch(`${base}${path}`, {
+      method,
+      headers,
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+      signal: AbortSignal.timeout(opt.timeoutMs ?? timeoutMs),
+    })
+    const json = await res.json().catch(() => null)
+    if (!res.ok) {
+      const err = new Error(json?.message ?? `HTTP ${res.status} ${path}`)
+      err.status = res.status
+      err.body = json
+      if (logger) logger.warn(`API ${method} ${path} → ${res.status}`)
+      throw err
+    }
+    // 平台统一信封 { code, message, data } → 解包 data;非信封原样返回
+    return json && typeof json === 'object' && 'data' in json ? json.data : json
+  }
+
+  const resource = root => ({
+    list: (query = {}) => call('GET', `${root}${toQuery(query)}`),
+    get: id => call('GET', `${root}/${id}`),
+    create: body => call('POST', root, body),
+    update: (id, patch) => call('PATCH', `${root}/${id}`, patch),
+    remove: id => call('DELETE', `${root}/${id}`),
+  })
+
+  const client = {
+    /** 底层调用(任意平台路径;自动带 token 与信封解包) */
+    call,
+    get: (path, query = {}) => call('GET', `${path}${toQuery(query)}`),
+    post: (path, body) => call('POST', path, body),
+    patch: (path, body) => call('PATCH', path, body),
+    delete: path => call('DELETE', path),
+    setToken: (t) => {
+      authToken = t ?? null
+      return client
+    },
+    /** 平台健康(免鉴权) */
+    ping: () => call('GET', '/api/plugins/manifest'),
+
+    // ---- 业务资源面 ----
+    users: {
+      ...resource('/api/users'),
+      login: (email, password) => call('POST', '/api/users/login', { email, password }),
+      me: () => call('GET', '/api/users/me'),
+    },
+    lines: {
+      ...resource('/api/workshop/dcw/lines'),
+      start: (id, recipeId = '') => call('POST', `/api/workshop/dcw/lines/${id}/start`, { recipeId }),
+      stop: id => call('POST', `/api/workshop/dcw/lines/${id}/stop`),
+    },
+    products: resource('/api/workshop/dcw/products'),
+    recipes: resource('/api/workshop/dcw/recipes'),
+    dcwNodes: resource('/api/workshop/dcw'),
+    daqNodes: {
+      ...resource('/api/workshop/daq'),
+      alarms: () => call('GET', '/api/workshop/daq/alarms'),
+    },
+    templates: {
+      daq: () => call('GET', '/api/workshop/daq').then(d => d?.templates ?? []),
+      dcw: () => call('GET', '/api/workshop/dcw').then(d => d?.templates ?? []),
+    },
+    twins: resource('/api/workshop/device-twins'),
+    teams: resource('/api/workshop/teams'),
+    agents: resource('/api/workshop/agents'),
+    channels: resource('/api/workshop/channels'),
+    plugins: {
+      manifest: () => call('GET', '/api/plugins/manifest'),
+    },
+  }
+  return client
+}
+
+function toQuery(query) {
+  const entries = Object.entries(query ?? {}).filter(([, v]) => v !== undefined && v !== null && v !== '')
+  if (!entries.length) return ''
+  return `?${new URLSearchParams(Object.fromEntries(entries.map(([k, v]) => [k, String(v)]))).toString()}`
+}
+
+export default createPlatformClient

package/sdk/client.mjs

@@ -5,16 +5,18 @@
 //   export function setup(ctx) { ctx.on('daq.reading', d => { ... }) }
 // ctx 形态(浏览器侧,自包含、零框架依赖):
 //   ctx.name / ctx.sdkVersion
-//   ctx.hooks   客户端本地 HookBus(client:init / event:* / page:change)
-//   ctx.on(type, fn)      scene 实时事件订阅(与 WS 同源;'*' 通配)
+//   ctx.hooks   客户端本地 HookBus(client:init / event:* / page:change / client:destroy)
+//   ctx.on(type, fn)      scene 实时事件订阅(与 WS 同源;'*' 通配)——自动登记 pagehide 回收
+//   ctx.fetch(path, …)    同源平台 API 助手(JSON;自动解信封 data)
 //   ctx.el(tag, attrs, children)   DOM 助手(挂到任意面板/宿主节点)
 //   ctx.mount(selector|el, node)   挂载节点(缺失时挂 body 角落)
-//   ctx.log   前缀 console
 //   ctx.root  插件 UI 挂载点(懒创建,自动附加到 body,#aw-plugin-<name>)
+//   ctx.log   前缀 console
+//   ctx.dispose()  卸载:清空挂载点 + 回收订阅 + 广播 client:destroy(pagehide 自动触发)
 // ============================================================
 import { HookBus } from './hooks.mjs'
 
-export const CLIENT_SDK_VERSION = '0.2.2'
+export const CLIENT_SDK_VERSION = '0.3.0'
 
 function el(tag, attrs = {}, children = []) {
   const node = document.createElement(tag)
@@ -30,16 +32,36 @@ function el(tag, attrs = {}, children = []) {
   return node
 }
 
-export function createClientContext({ name, eventBridge }) {
+export function createClientContext({ name, eventBridge, baseUrl = '' }) {
   const hooks = new HookBus({ name: `client:${name}`, onError: err => console.warn(`[aw-plugin:${name}]`, err) })
+  const disposables = []
   let rootEl = null
+  let disposed = false
 
   const ctx = {
     name,
     sdkVersion: CLIENT_SDK_VERSION,
     hooks,
-    on: (type, fn) => (type === 'event:*' ? hooks.on('*', fn) : hooks.on(`event:${type}`, fn)),
-    off: (type, fn) => (type === 'event:*' ? hooks.off('*', fn) : hooks.off(`event:${type}`, fn)),
+    on: (type, fn) => {
+      const off = type === 'event:*' ? hooks.on('*', fn) : hooks.on(`event:${type}`, fn)
+      disposables.push(off)
+      return off
+    },
+    /** 同源平台 API(JSON;自动解 {data} 信封;非 2xx 抛错) */
+    fetch: async (path, opt = {}) => {
+      const res = await fetch(`${baseUrl}${path}`, {
+        headers: { accept: 'application/json', ...(opt.body !== undefined ? { 'content-type': 'application/json' } : {}), ...(opt.headers ?? {}) },
+        method: opt.method ?? (opt.body !== undefined ? 'POST' : 'GET'),
+        body: opt.body !== undefined ? JSON.stringify(opt.body) : undefined,
+      })
+      const json = await res.json().catch(() => null)
+      if (!res.ok) {
+        const err = new Error(json?.message ?? `HTTP ${res.status} ${path}`)
+        err.status = res.status
+        throw err
+      }
+      return json && typeof json === 'object' && 'data' in json ? json.data : json
+    },
     el,
     log: {
       info: (...a) => console.info(`[aw-plugin:${name}]`, ...a),
@@ -61,13 +83,35 @@ export function createClientContext({ name, eventBridge }) {
       ;(host ?? ctx.root()).append(node)
       return node
     },
+    /** 卸载:回收订阅 + 清空挂载点 + 广播 client:destroy(幂等) */
+    dispose: () => {
+      if (disposed) return
+      disposed = true
+      void hooks.emit('client:destroy', { name })
+      for (const d of disposables.splice(0)) {
+        try {
+          d()
+        }
+        catch { /* 单个回收失败不阻断 */ }
+      }
+      rootEl?.remove()
+      rootEl = null
+    },
   }
 
   // scene 事件桥 → ctx.hooks(event:<type> 与 '*' 均可订阅)
   if (eventBridge) {
-    eventBridge((type, payload) => {
+    const offBridge = eventBridge((type, payload) => {
       void hooks.emit(`event:${type}`, payload)
     })
+    disposables.push(offBridge)
+  }
+
+  // 页面卸载自动回收(pagehide 覆盖 bfcache 场景)
+  if (typeof document !== 'undefined') {
+    document.addEventListener('visibilitychange', () => {
+      if (document.visibilityState === 'hidden') ctx.dispose()
+    }, { once: true })
   }
 
   return ctx

package/sdk/context.mjs

@@ -1,22 +1,26 @@
 // ============================================================
 // AgentWorkShop SDK — 服务端插件上下文工厂（宿主调用;插件经 setup(ctx) 获得）
 // ------------------------------------------------------------
-// ctx 形态:
-//   ctx.name / ctx.scope('home'|'project') / ctx.dir        — 身份与目录
-//   ctx.hooks    HookBus                                     — 生命周期钩子(on/once/off/emit)
-//   ctx.logger   前缀日志(info/warn/error/debug)             — 插件名自动前缀
-//   ctx.config   { get(key), all() }                         — 有效配置只读(四层引擎)
-//   ctx.dataDir / ctx.kv { get,set,all,bump }                — 插件私有持久化(json 落配置根 data/plugins/<name>)
-//   ctx.route(method, path, handler)                         — 注册插件 API → /api/plugins/<name><path>
-//   ctx.http    { get,post } 带超时 fetch                     — 对外请求(仅 http/https)
-//   ctx.events  { on(type,fn) }                              — scene 实时事件订阅(event:* 桥的糖)
-//   ctx.paths    { home, configRoot, dataDir }               — 配置根信息
+// ctx 形态(运行时完整变量面):
+//   身份    ctx.name / ctx.scope('home'|'project') / ctx.dir / ctx.sdkVersion
+//   钩子    ctx.hooks   HookBus(生命周期 + event:*)                  [SDK]
+//   日志    ctx.logger  { debug, info, warn, error } 插件名前缀      [SDK]
+//   配置    ctx.config  { get(key), all(), onChange(fn) }            [SDK]
+//   存储    ctx.kv      { get,set,all,bump } 内存态+防抖落盘          [SDK]
+//   定时    ctx.timer   { setInterval, setTimeout } 服务关闭自动回收  [SDK]
+//   清理    ctx.onDispose(fn) / ctx.subscriptions                    [SDK]
+//   路由    ctx.route(method, path, handler) → /api/plugins/<name>… [SDK]
+//   平台    ctx.api     平台 REST 客户端(lines/daq/dcw/twins/teams…) [SDK]
+//   网络    ctx.http    { get, post } 带超时 fetch(仅 http/https)    [SDK]
+//   事件    ctx.events  { on(type,fn), off }  scene 实时事件          [SDK]
+//   路径    ctx.paths   { home, configRoot, dataDir }                [SDK]
 // ============================================================
 import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs'
-import { dirname, join, resolve } from 'node:path'
+import { join, resolve } from 'node:path'
 import { HookBus } from './hooks.mjs'
+import { createPlatformClient } from './api.mjs'
 
-export const SDK_VERSION = '0.2.2'
+export const SDK_VERSION = '0.3.0'
 
 /** 允许的对外请求协议守卫(拒绝 file:/data: 等;宿主/插件同守此规则) */
 function safeUrl(raw, timeoutMs = 8000) {
@@ -28,7 +32,7 @@ function safeUrl(raw, timeoutMs = 8000) {
 
 /**
  * 创建服务端插件上下文。
- * @param {{ name, scope, dir, hooks, logger, config, paths, emitter }} opts 宿主装配
+ * @param {{ name, scope, dir, hooks, logger, config, paths, emitter, onDispose, selfOrigin }} opts 宿主装配
  */
 export function createPluginContext(opts) {
   const { name, scope, dir, hooks, config, paths, emitter } = opts
@@ -41,6 +45,29 @@ export function createPluginContext(opts) {
     ...(opts.logger ?? {}),
   }
 
+  // ---- 订阅回收(VSCode subscriptions 范式):服务关闭时宿主逐个调用 ----
+  const disposables = []
+  const onDispose = (fn) => {
+    if (typeof fn === 'function') disposables.push(fn)
+    return fn
+  }
+
+  // ---- 定时器:自动登记回收,杜绝插件定时器泄漏 ----
+  const timer = {
+    setInterval: (fn, ms, ...rest) => {
+      const id = setInterval(fn, ms, ...rest)
+      if (typeof id === 'object' && id !== null && 'unref' in id) id.unref?.()
+      onDispose(() => clearInterval(id))
+      return id
+    },
+    setTimeout: (fn, ms, ...rest) => {
+      const id = setTimeout(fn, ms, ...rest)
+      if (typeof id === 'object' && id !== null && 'unref' in id) id.unref?.()
+      onDispose(() => clearTimeout(id))
+      return id
+    },
+  }
+
   // ---- 插件私有持久化:内存态为准 + 200ms 防抖落盘 —— 高频钩子(daq:sample)
   //      与低频钩子(line:stop)并发时无 read-modify-write 竞态(JS 同步内存操作原子) ----
   const kvDir = join(paths.dataDir, 'plugins', name)
@@ -77,6 +104,8 @@ export function createPluginContext(opts) {
     config: {
       get: key => config?.effective?.[key],
       all: () => ({ ...config?.effective }),
+      /** 运行时覆盖变更订阅(runtime-settings.json 变化;宿主 fs.watch 驱动) */
+      onChange: fn => hooks.on('config:changed', fn),
     },
     paths: { ...paths },
     dataDir: kvDir,
@@ -94,7 +123,21 @@ export function createPluginContext(opts) {
         return kvState[key]
       },
     },
+    timer,
+    onDispose,
+    /** 订阅式清理对象({ dispose(){} })集中登记 */
+    subscriptions: {
+      add: (d) => {
+        disposables.push(typeof d === 'function' ? d : (...a) => d.dispose?.(...a))
+        return d
+      },
+    },
     route: (method, path, handler) => emitter?.registerRoute(name, method, path, handler),
+    /** 平台 REST 客户端(自环 origin 延迟解析;鉴权端点请 ctx.api.setToken(token)) */
+    api: createPlatformClient({
+      baseUrl: typeof opts.selfOrigin === 'function' ? opts.selfOrigin : () => opts.selfOrigin,
+      logger,
+    }),
     http: {
       get: (url, opts2 = {}) => fetch(url, { ...safeUrl(url, opts2.timeoutMs), ...opts2 }),
       post: (url, body, opts2 = {}) => fetch(url, {
@@ -166,8 +209,6 @@ export function pluginKvExists(dataDir, name) {
   return existsSync(join(resolve(dataDir), 'plugins', name, 'kv.json'))
 }
 
-export { dirname }
-
 export default {
   SDK_VERSION,
   HookBus,

package/sdk/index.d.mts

@@ -0,0 +1,135 @@
+// AgentWorkShop SDK 类型声明(agentworkshop/sdk)
+import type { HookBus } from './hooks.mjs'
+
+export declare const SDK_VERSION: string
+
+/** 生命周期钩子总线:异步串行、错误隔离、'*' 通配、连续失败自动熔断 */
+export declare class HookBus {
+  constructor(opts?: { name?: string, onError?: (err: Error, meta?: { bus?: string, type?: string, fails?: number }) => void })
+  on(type: string, fn: (payload: any) => any): () => void
+  once(type: string, fn: (payload: any) => any): () => void
+  off(type: string, fn: (payload: any) => any): void
+  emit(type: string, payload?: any): Promise<any>
+  readonly size: number
+}
+
+export interface PluginLogger {
+  debug(...args: unknown[]): void
+  info(...args: unknown[]): void
+  warn(...args: unknown[]): void
+  error(...args: unknown[]): void
+}
+
+export interface PluginKv {
+  get(key: string): any
+  set(key: string, value: any): any
+  all(): Record<string, any>
+  bump(key: string, by?: number): number
+}
+
+export interface PluginHttp {
+  get(url: string, opts?: { timeoutMs?: number, headers?: Record<string, string> }): Promise<Response>
+  post(url: string, body?: unknown, opts?: { timeoutMs?: number, headers?: Record<string, string> }): Promise<Response>
+}
+
+/** 平台 REST 客户端(SDK 作为项目服务 client 的门面) */
+export interface PlatformClient {
+  call<T = any>(method: string, path: string, body?: unknown): Promise<T>
+  get<T = any>(path: string, query?: Record<string, unknown>): Promise<T>
+  post<T = any>(path: string, body?: unknown): Promise<T>
+  patch<T = any>(path: string, body?: unknown): Promise<T>
+  delete<T = any>(path: string): Promise<T>
+  setToken(token: string | null): PlatformClient
+  ping(): Promise<any>
+  users: { list(q?: any): Promise<any>, get(id: string): Promise<any>, create(b: any): Promise<any>, login(email: string, password: string): Promise<any>, me(): Promise<any> }
+  lines: { list(q?: any): Promise<any>, get(id: string): Promise<any>, create(b: any): Promise<any>, update(id: string, p: any): Promise<any>, remove(id: string): Promise<any>, start(id: string, recipeId?: string): Promise<any>, stop(id: string): Promise<any> }
+  products: { list(q?: any): Promise<any>, create(b: any): Promise<any> }
+  recipes: { list(q?: any): Promise<any>, create(b: any): Promise<any> }
+  dcwNodes: { list(q?: any): Promise<any>, create(b: any): Promise<any> }
+  daqNodes: { list(q?: any): Promise<any>, create(b: any): Promise<any>, alarms(): Promise<any> }
+  templates: { daq(): Promise<any[]>, dcw(): Promise<any[]> }
+  twins: { list(q?: any): Promise<any>, create(b: any): Promise<any> }
+  teams: { list(q?: any): Promise<any>, create(b: any): Promise<any> }
+  agents: { list(q?: any): Promise<any>, create(b: any): Promise<any> }
+  channels: { list(q?: any): Promise<any> }
+  plugins: { manifest(): Promise<any> }
+}
+
+export interface PluginContext {
+  name: string
+  scope: 'project' | 'user'
+  dir: string
+  sdkVersion: string
+  hooks: HookBus
+  logger: PluginLogger
+  config: {
+    get(key: string): any
+    all(): Record<string, any>
+    onChange(fn: (payload?: { at: string }) => any): () => void
+  }
+  paths: { home: string, configRoot: string, dataDir: string }
+  dataDir: string
+  kv: PluginKv
+  timer: {
+    setInterval(fn: (...args: any[]) => void, ms: number, ...rest: any[]): NodeJS.Timeout
+    setTimeout(fn: (...args: any[]) => void, ms: number, ...rest: any[]): NodeJS.Timeout
+  }
+  onDispose(fn: () => any): () => void
+  subscriptions: { add(d: { dispose(): any } | (() => any)): any }
+  route(method: string, path: string, handler: (event: any) => any): boolean
+  api: PlatformClient
+  http: PluginHttp
+  events: { on(type: string, fn: (payload: any) => any): () => void, off(type: string, fn: (payload: any) => any): void }
+}
+
+export interface PluginRouteDef {
+  method?: string
+  path: string
+  handler: (event: any) => any
+}
+
+export interface PluginDef {
+  name: string
+  version?: string
+  description?: string
+  setup?(ctx: PluginContext): void | Promise<void>
+  client?: string
+  routes?: PluginRouteDef[]
+}
+
+/** 显式糖:类型化定义插件(宿主同样接受裸对象导出) */
+export declare function definePlugin(def: PluginDef): PluginDef
+
+export declare function createPluginContext(opts: Record<string, any>): PluginContext
+export declare function createRouteTable(): {
+  register(name: string, method: string, path: string, handler: (event: any) => any): boolean
+  resolve(name: string, method: string, path: string): ((event: any) => any) | null
+  byPlugin(name: string): Array<{ method: string, path: string }>
+  readonly size: number
+}
+export declare function validatePluginModule(mod: any, source: string): { ok: boolean, def?: PluginDef, error?: string }
+export declare function pluginKvExists(dataDir: string, name: string): boolean
+
+export declare function createPlatformClient(opts?: { baseUrl?: string, token?: string, logger?: PluginLogger, timeoutMs?: number }): PlatformClient
+
+export declare const LIFECYCLE_EVENTS: readonly ['plugin:host:init', 'config:changed', 'event:*', 'daq:sample', 'dcw:write', 'line:start', 'line:stop', 'server:close']
+export declare const CLIENT_EVENTS: readonly ['client:init', 'event:*', 'page:change', 'client:destroy']
+
+/** 客户端插件上下文(sdk/client.mjs) */
+export declare const CLIENT_SDK_VERSION: string
+export interface ClientContext {
+  name: string
+  sdkVersion: string
+  hooks: HookBus
+  on(type: string, fn: (payload: any) => any): () => void
+  fetch<T = any>(path: string, opt?: { method?: string, body?: unknown, headers?: Record<string, string> }): Promise<T>
+  el(tag: string, attrs?: Record<string, unknown>, children?: Array<Node | string>): HTMLElement
+  mount(target: string | Element, node: Node): Node
+  root(): HTMLElement
+  log: PluginLogger
+  dispose(): void
+}
+export declare function createClientContext(opts: { name: string, eventBridge?: (fn: (type: string, payload: any) => void) => (() => void), baseUrl?: string }): ClientContext
+
+declare const _default: Record<string, unknown>
+export default _default

package/sdk/index.mjs

@@ -15,29 +15,15 @@
 // ============================================================
 import { SDK_VERSION, definePlugin, createPluginContext, createRouteTable, validatePluginModule, pluginKvExists } from './context.mjs'
 import { HookBus } from './hooks.mjs'
+import { createPlatformClient } from './api.mjs'
 import { CLIENT_SDK_VERSION, createClientContext } from './client.mjs'
+import { LIFECYCLE_EVENTS, CLIENT_EVENTS } from './lifecycle.mjs'
 
 export { SDK_VERSION, definePlugin, createPluginContext, createRouteTable, validatePluginModule, pluginKvExists } from './context.mjs'
 export { HookBus } from './hooks.mjs'
+export { createPlatformClient } from './api.mjs'
 export { CLIENT_SDK_VERSION, createClientContext } from './client.mjs'
-
-/** 服务端生命周期事件清单(宿主触发;文档见 docs/plugins.md) */
-export const LIFECYCLE_EVENTS = Object.freeze([
-  'plugin:host:init',
-  'event:*',
-  'daq:sample',
-  'dcw:write',
-  'line:start',
-  'line:stop',
-  'server:close',
-])
-
-/** 客户端生命周期事件清单 */
-export const CLIENT_EVENTS = Object.freeze([
-  'client:init',
-  'event:*',
-  'page:change',
-])
+export { LIFECYCLE_EVENTS, CLIENT_EVENTS } from './lifecycle.mjs'
 
 export default {
   SDK_VERSION,
@@ -47,6 +33,7 @@ export default {
   createRouteTable,
   validatePluginModule,
   pluginKvExists,
+  createPlatformClient,
   CLIENT_SDK_VERSION,
   createClientContext,
   LIFECYCLE_EVENTS,

package/sdk/lifecycle.mjs

@@ -0,0 +1,25 @@
+// ============================================================
+// AgentWorkShop SDK — 生命周期事件清单(宿主触发;单一事实源)
+// ============================================================
+
+/** 服务端生命周期事件清单(宿主触发;文档见 docs/plugins.md) */
+export const LIFECYCLE_EVENTS = Object.freeze([
+  'plugin:host:init',
+  'config:changed',
+  'event:*',
+  'daq:sample',
+  'dcw:write',
+  'line:start',
+  'line:stop',
+  'server:close',
+])
+
+/** 客户端生命周期事件清单 */
+export const CLIENT_EVENTS = Object.freeze([
+  'client:init',
+  'event:*',
+  'page:change',
+  'client:destroy',
+])
+
+export default { LIFECYCLE_EVENTS, CLIENT_EVENTS }

package/server/api/plugins/[name]/[...path].ts

@@ -3,10 +3,10 @@
  * 插件经 ctx.route(method, path, handler) 注册;handler(event) 返回值由 nitro 序列化。
  * 鉴权由插件自行处理(v1 不强制;可经 resolveUser 复用业务鉴权)。
  */
-import { defineEventHandler, createError } from 'h3'
+import { defineEventHandler, createError, readBody } from 'h3'
 import { getPluginHost } from '@/server/services/workshop/plugins/host.mjs'
 
-export default defineEventHandler((event) => {
+export default defineEventHandler(async (event) => {
   const host = getPluginHost()
   if (!host) throw createError({ statusCode: 503, statusMessage: 'plugin host not ready' })
   const name = String(event.context.params?.name ?? '')
@@ -15,5 +15,8 @@ export default defineEventHandler((event) => {
   if (!handler) {
     throw createError({ statusCode: 404, statusMessage: `plugin route not found: ${event.method} /api/plugins/${name}${path}` })
   }
+  // 预读 body 挂到 event(插件 handler 无 h3 导入能力,经 event.awBody 消费)
+  const awBody = await readBody(event).catch(() => undefined)
+  ;(event as Record<string, unknown>).awBody = awBody
   return handler(event)
 })