agentworkshop 0.2.1 → 0.3.0

package/sdk/client.mjs

@@ -0,0 +1,120 @@
+// ============================================================
+// AgentWorkShop SDK — 客户端插件上下文工厂（客户端 loader 调用）
+// ------------------------------------------------------------
+// 插件 client.mjs 导出:
+//   export function setup(ctx) { ctx.on('daq.reading', d => { ... }) }
+// ctx 形态(浏览器侧,自包含、零框架依赖):
+//   ctx.name / ctx.sdkVersion
+//   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.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.3.0'
+
+function el(tag, attrs = {}, children = []) {
+  const node = document.createElement(tag)
+  for (const [k, v] of Object.entries(attrs)) {
+    if (k === 'style') node.style.cssText = v
+    else if (k === 'class') node.className = v
+    else if (k.startsWith('on') && typeof v === 'function') node.addEventListener(k.slice(2), v)
+    else node.setAttribute(k, String(v))
+  }
+  for (const c of [].concat(children)) {
+    node.append(typeof c === 'string' ? document.createTextNode(c) : c)
+  }
+  return node
+}
+
+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) => {
+      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),
+      warn: (...a) => console.warn(`[aw-plugin:${name}]`, ...a),
+      error: (...a) => console.error(`[aw-plugin:${name}]`, ...a),
+    },
+    root: () => {
+      rootEl ??= (() => {
+        const found = document.getElementById(`aw-plugin-${name}`)
+        if (found) return found
+        const box = el('div', { id: `aw-plugin-${name}`, style: 'position:fixed;right:16px;bottom:16px;z-index:2147483000;font:12px/1.6 ui-monospace,monospace' })
+        document.body.append(box)
+        return box
+      })()
+      return rootEl
+    },
+    mount: (target, node) => {
+      const host = typeof target === 'string' ? document.querySelector(target) : target
+      ;(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) {
+    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
+}
+
+export default { CLIENT_SDK_VERSION, createClientContext, el }

package/sdk/context.mjs

@@ -0,0 +1,219 @@
+// ============================================================
+// AgentWorkShop SDK — 服务端插件上下文工厂（宿主调用;插件经 setup(ctx) 获得）
+// ------------------------------------------------------------
+// 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 { join, resolve } from 'node:path'
+import { HookBus } from './hooks.mjs'
+import { createPlatformClient } from './api.mjs'
+
+export const SDK_VERSION = '0.3.0'
+
+/** 允许的对外请求协议守卫(拒绝 file:/data: 等;宿主/插件同守此规则) */
+function safeUrl(raw, timeoutMs = 8000) {
+  const u = new URL(String(raw))
+  if (u.protocol !== 'http:' && u.protocol !== 'https:')
+    throw new Error(`协议不允许: ${u.protocol}(仅 http/https)`)
+  return { signal: AbortSignal.timeout(timeoutMs) }
+}
+
+/**
+ * 创建服务端插件上下文。
+ * @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
+  // 规范化 logger:宿主实现缺级时兜底 no-op(插件可用全套 debug/info/warn/error)
+  const logger = {
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    ...(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)
+  const kvFile = join(kvDir, 'kv.json')
+  const kvState = (() => {
+    try {
+      return JSON.parse(readFileSync(kvFile, 'utf8'))
+    }
+    catch {
+      return {}
+    }
+  })()
+  let kvFlushTimer = null
+  const kvFlush = () => {
+    clearTimeout(kvFlushTimer)
+    kvFlushTimer = setTimeout(() => {
+      try {
+        mkdirSync(kvDir, { recursive: true })
+        const tmp = `${kvFile}.${process.pid}.tmp`
+        writeFileSync(tmp, `${JSON.stringify(kvState, null, 2)}\n`, 'utf8')
+        renameSync(tmp, kvFile)
+      }
+      catch { /* 磁盘异常不阻断插件 */ }
+    }, 200)
+  }
+
+  const ctx = {
+    name,
+    scope,
+    dir: resolve(dir),
+    sdkVersion: SDK_VERSION,
+    hooks, // 宿主全局总线(与事件桥同源)
+    logger,
+    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,
+    kv: {
+      get: key => kvState[key],
+      set: (key, value) => {
+        kvState[key] = value
+        kvFlush()
+        return value
+      },
+      all: () => ({ ...kvState }),
+      bump: (key, by = 1) => {
+        kvState[key] = (Number(kvState[key]) || 0) + by
+        kvFlush()
+        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, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', ...(opts2.headers ?? {}) },
+        body: JSON.stringify(body ?? {}),
+        ...safeUrl(url, opts2.timeoutMs),
+      }),
+    },
+    events: {
+      on: (type, fn) => hooks.on(type === '*' ? '*' : `event:${type}`, fn),
+      off: (type, fn) => hooks.off(type === '*' ? '*' : `event:${type}`, fn),
+    },
+  }
+  return ctx
+}
+
+/** 宿主路由表(exact-match;插件 API 挂 /api/plugins/<name><path>) */
+export function createRouteTable() {
+  const table = new Map() // `${method} ${name} ${path}` → handler
+  return {
+    register(name, method, path, handler) {
+      if (typeof handler !== 'function') return false
+      const key = `${String(method).toUpperCase()} ${name} ${path.startsWith('/') ? path : `/${path}`}`
+      table.set(key, handler)
+      return true
+    },
+    resolve(name, method, path) {
+      return table.get(`${String(method).toUpperCase()} ${name} ${path.startsWith('/') ? path : `/${path}`}`) ?? null
+    },
+    byPlugin(name) {
+      const out = []
+      for (const key of table.keys()) {
+        const [m, n, ...rest] = key.split(' ')
+        if (n === name) out.push({ method: m, path: rest.join('/') })
+      }
+      return out
+    },
+    get size() {
+      return table.size
+    },
+  }
+}
+
+/** 校验插件入口导出(宿主装载前的形态检查) */
+export function validatePluginModule(mod, source) {
+  const def = mod?.default ?? mod
+  if (!def || typeof def !== 'object' || typeof def.name !== 'string' || !def.name.trim()) {
+    return { ok: false, error: `插件缺少 name 或不是对象: ${source}` }
+  }
+  if (def.setup && typeof def.setup !== 'function') {
+    return { ok: false, error: `插件 setup 不是函数: ${def.name}` }
+  }
+  if (def.client && typeof def.client !== 'string') {
+    return { ok: false, error: `插件 client 必须是相对路径字符串: ${def.name}` }
+  }
+  return { ok: true, def }
+}
+
+/** 便捷:SDK 侧 definePlugin(纯类型糖;宿主同样接受裸对象) */
+export function definePlugin(def) {
+  const check = validatePluginModule({ default: def }, def?.name ?? '(anonymous)')
+  if (!check.ok) throw new Error(check.error)
+  return def
+}
+
+/** 插件 KV 目录探测(存在性只读) */
+export function pluginKvExists(dataDir, name) {
+  return existsSync(join(resolve(dataDir), 'plugins', name, 'kv.json'))
+}
+
+export default {
+  SDK_VERSION,
+  HookBus,
+  createPluginContext,
+  createRouteTable,
+  validatePluginModule,
+  definePlugin,
+}

package/sdk/examples/sample-insight/client.mjs

@@ -0,0 +1,23 @@
+// sample-insight — 客户端增强(自包含 ESM,无裸导入)
+// 右下角徽标实时显示采样计数(事件与 WS 同源)
+export function setup(ctx) {
+  const badge = ctx.el('div', {
+    style: 'padding:8px 12px;border:1px solid #35e0a0;border-radius:10px;color:#35e0a0;'
+      + 'background:rgba(8,20,16,.82);font:600 12px/1 ui-monospace,monospace;'
+      + 'box-shadow:0 4px 16px rgba(0,0,0,.35);letter-spacing:.4px',
+  }, ['⌁ sample-insight · 0'])
+
+  ctx.root().append(badge)
+
+  let n = 0
+  ctx.on('daq:sample', () => {
+    n++
+    badge.textContent = `⌁ sample-insight · ${n} 样本`
+  })
+
+  ctx.on('page:change', ({ path }) => {
+    ctx.log.info('page →', path)
+  })
+
+  ctx.log.info('client ready — 右下角徽标已挂载')
+}

package/sdk/examples/sample-insight/index.mjs

@@ -0,0 +1,39 @@
+/**
+ * sample-insight — SDK 示例插件(服务端面)。
+ * 订阅下发级数采采样计数,并暴露插件 API:GET /api/plugins/sample-insight/stats
+ * 完整指南见 docs/plugins.md。
+ */
+export default {
+  name: 'sample-insight',
+  version: '1.0.0',
+  description: 'SDK 示例:数采采样计数 + 统计 API + 客户端徽标',
+
+  async setup(ctx) {
+    ctx.logger.info('示例插件已装载 —— daq:sample 计数中')
+
+    ctx.hooks.on('daq:sample', (s) => {
+      ctx.kv.bump('samples')
+      if (s?.nodeId) ctx.kv.set(`last:${s.nodeId}`, { value: s.value, at: s.at })
+    })
+
+    ctx.hooks.on('line:start', (p) => {
+      ctx.logger.info(`产线开跑: ${p?.lineId}`)
+      ctx.kv.set('lineRunning', true)
+    })
+
+    ctx.hooks.on('line:stop', () => ctx.kv.set('lineRunning', false))
+
+    ctx.route('GET', '/stats', () => ({
+      plugin: ctx.name,
+      version: ctx.sdkVersion,
+      samples: ctx.kv.get('samples') ?? 0,
+      lineRunning: ctx.kv.get('lineRunning') ?? false,
+      scope: ctx.scope,
+    }))
+
+    ctx.route('POST', '/reset', () => {
+      ctx.kv.set('samples', 0)
+      return { ok: true }
+    })
+  },
+}

package/sdk/hooks.mjs

@@ -0,0 +1,103 @@
+// ============================================================
+// AgentWorkShop SDK — HookBus（插件生命周期钩子总线）
+// ------------------------------------------------------------
+// 设计:
+//   · 异步串行触发(监听器按注册序 await,可返回值形成 waterfall)
+//   · 错误隔离:单监听器抛错不影响其他监听器,错误经 onError 上报
+//   · 支持通配符 '*'(接收 { type, payload })
+//   · 连续失败自动摘除(熔断):同一监听器连续失败超阈值自动停用,
+//     防止病态插件拖垮事件桥
+// ============================================================
+
+const FAILLIMIT = 8
+
+export class HookBus {
+  constructor({ name = 'hooks', onError } = {}) {
+    this.name = name
+    this.onError = onError ?? (() => {})
+    /** type → Array<{ fn, fails }> */
+    this.listeners = new Map()
+    this.count = 0
+  }
+
+  /** 注册监听器;type='*' 接收全部事件({type,payload})。返回解绑函数 */
+  on(type, fn) {
+    if (typeof type !== 'string' || typeof fn !== 'function') return () => {}
+    const list = this.listeners.get(type) ?? []
+    list.push({ fn, fails: 0 })
+    this.listeners.set(type, list)
+    this.count++
+    return () => this.off(type, fn)
+  }
+
+  /** 一次性监听(触发后自动解绑) */
+  once(type, fn) {
+    const off = this.on(type, async (arg) => {
+      off()
+      return fn(arg)
+    })
+    return off
+  }
+
+  off(type, fn) {
+    const list = this.listeners.get(type)
+    if (!list) return
+    const idx = list.findIndex(l => l.fn === fn)
+    if (idx >= 0) {
+      list.splice(idx, 1)
+      this.count--
+    }
+    if (!list.length) this.listeners.delete(type)
+  }
+
+  /**
+   * 触发事件:同名监听器按注册序串行 await;返回最后一个非 undefined 返回值。
+   * emit 永不抛错——监听器错误被隔离并计数,连续超限自动摘除(熔断)。
+   */
+  async emit(type, payload) {
+    const same = this.listeners.get(type)
+    const wild = this.listeners.get('*')
+    let result
+    if (same) {
+      for (const l of [...same]) {
+        const r = await this.#invoke(type, l, payload)
+        if (r !== undefined) result = r
+      }
+    }
+    if (wild) {
+      for (const l of [...wild]) {
+        await this.#invoke('*', l, { type, payload })
+      }
+    }
+    return result
+  }
+
+  async #invoke(type, l, payload) {
+    try {
+      return await l.fn(payload)
+    }
+    catch (err) {
+      l.fails++
+      try {
+        this.onError(err, { bus: this.name, type, fails: l.fails })
+      }
+      catch { /* 上报器自身错误忽略 */ }
+      if (l.fails >= FAILLIMIT) {
+        const list = this.listeners.get(type)
+        const idx = list?.indexOf(l) ?? -1
+        if (idx >= 0) {
+          list.splice(idx, 1)
+          this.count--
+        }
+      }
+      return undefined
+    }
+  }
+
+  /** 已注册监听器总数(诊断用) */
+  get size() {
+    return this.count
+  }
+}
+
+export default 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

@@ -0,0 +1,41 @@
+// ============================================================
+// AgentWorkShop SDK — 门面
+// ------------------------------------------------------------
+// 插件作者两种写法:
+//   1) 零依赖(推荐,全局安装零解析链约束下的标准形态):
+//        export default { name, version, setup(ctx), client: './client.mjs', routes: [...] }
+//      —— ctx 由宿主注入,本 SDK 对插件运行时非必需。
+//   2) 显式糖(本地开发/单体使用时):
+//        import { definePlugin } from 'agentworkshop/sdk'
+//        export default definePlugin({ ... })
+// 生命周期(宿主触发):
+//   服务端: setup(ctx) → plugin:host:init → event:*/daq:sample/dcw:write/line:start|stop
+//           → server:close
+//   客户端: client.mjs setup(ctx) → client:init → event:*/page:change
+// ============================================================
+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'
+export { LIFECYCLE_EVENTS, CLIENT_EVENTS } from './lifecycle.mjs'
+
+export default {
+  SDK_VERSION,
+  definePlugin,
+  HookBus,
+  createPluginContext,
+  createRouteTable,
+  validatePluginModule,
+  pluginKvExists,
+  createPlatformClient,
+  CLIENT_SDK_VERSION,
+  createClientContext,
+  LIFECYCLE_EVENTS,
+  CLIENT_EVENTS,
+}