agentworkshop 0.2.1 → 0.2.2

package/sdk/context.mjs

@@ -0,0 +1,178 @@
+// ============================================================
+// 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 }               — 配置根信息
+// ============================================================
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { HookBus } from './hooks.mjs'
+
+export const SDK_VERSION = '0.2.2'
+
+/** 允许的对外请求协议守卫(拒绝 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 }} 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 ?? {}),
+  }
+
+  // ---- 插件私有持久化:内存态为准 + 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 }),
+    },
+    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]
+      },
+    },
+    route: (method, path, handler) => emitter?.registerRoute(name, method, path, handler),
+    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 { dirname }
+
+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.mjs

@@ -0,0 +1,54 @@
+// ============================================================
+// 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 { CLIENT_SDK_VERSION, createClientContext } from './client.mjs'
+
+export { SDK_VERSION, definePlugin, createPluginContext, createRouteTable, validatePluginModule, pluginKvExists } from './context.mjs'
+export { HookBus } from './hooks.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 default {
+  SDK_VERSION,
+  definePlugin,
+  HookBus,
+  createPluginContext,
+  createRouteTable,
+  validatePluginModule,
+  pluginKvExists,
+  CLIENT_SDK_VERSION,
+  createClientContext,
+  LIFECYCLE_EVENTS,
+  CLIENT_EVENTS,
+}

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

@@ -0,0 +1,19 @@
+/**
+ * /api/plugins/:name/** —— 插件自注册 API 的转发层(exact-match)。
+ * 插件经 ctx.route(method, path, handler) 注册;handler(event) 返回值由 nitro 序列化。
+ * 鉴权由插件自行处理(v1 不强制;可经 resolveUser 复用业务鉴权)。
+ */
+import { defineEventHandler, createError } from 'h3'
+import { getPluginHost } from '@/server/services/workshop/plugins/host.mjs'
+
+export default defineEventHandler((event) => {
+  const host = getPluginHost()
+  if (!host) throw createError({ statusCode: 503, statusMessage: 'plugin host not ready' })
+  const name = String(event.context.params?.name ?? '')
+  const path = '/' + (event.context.params?.path ?? '').replace(/^\/+/, '')
+  const handler = host.routes.resolve(name, event.method, path)
+  if (!handler) {
+    throw createError({ statusCode: 404, statusMessage: `plugin route not found: ${event.method} /api/plugins/${name}${path}` })
+  }
+  return handler(event)
+})

package/server/api/plugins/client/[name].get.ts

@@ -0,0 +1,18 @@
+/**
+ * GET /api/plugins/client/:name —— 插件客户端脚本(text/javascript)。
+ * 自包含 ESM(无裸导入);客户端 loader 动态 import 后以 setup(ctx) 装载。
+ * 信任模型与 aw commands 相同:仅装载自己放入插件目录的可信代码。
+ */
+import { defineEventHandler, getRouterParam, setHeader, createError } from 'h3'
+import { readClientScript } from '@/server/services/workshop/plugins/host.mjs'
+
+export default defineEventHandler((event) => {
+  const name = String(getRouterParam(event, 'name') ?? '').replace(/\.mjs$/, '')
+  const r = readClientScript(name)
+  if (r.status !== 200) {
+    throw createError({ statusCode: r.status, statusMessage: r.status === 404 ? 'plugin client not found' : 'bad request' })
+  }
+  setHeader(event, 'content-type', r.contentType ?? 'text/javascript; charset=utf-8')
+  setHeader(event, 'cache-control', 'no-cache')
+  return r.code
+})

package/server/api/plugins/manifest.get.ts

@@ -0,0 +1,10 @@
+/**
+ * GET /api/plugins/manifest —— 已装载插件清单(免鉴权只读:名称/版本/作用域/路由/是否有客户端)。
+ * 客户端 loader 启动期拉取;未登录/服务未装载时返回空数组(前端静默)。
+ */
+import { pluginManifest } from '@/server/services/workshop/plugins/host.mjs'
+import { defineEventHandler } from 'h3'
+
+export default defineEventHandler(() => {
+  return { plugins: pluginManifest() }
+})

package/server/api/workshop/dcw/lines/[id]/start.post.ts

@@ -9,6 +9,7 @@ import { bindDcwBroadcast, getDcwController } from '@/server/services/workshop/d
 import { broadcastSceneEvent } from '@/server/services/workshop/scene-events'
 import { getActiveLineRun } from '@/server/services/workshop/dcw/line-run'
 import { recordOps } from '@/server/services/workshop/ops/ops'
+import { emitLineLifecycle } from '@/server/services/workshop/plugins/host.mjs'
 
 export default defineApiHandler(async (event) => {
   const user = resolveUser(event)
@@ -31,5 +32,6 @@ export default defineApiHandler(async (event) => {
     recipeId: active?.recipeId ?? String(body.recipeId ?? ''),
     detail: { runId: run.id, recipeId: body.recipeId ?? '' },
   })
+  emitLineLifecycle('line:start', { lineId: id, runId: run.id, recipeId: active?.recipeId ?? String(body.recipeId ?? ''), productName: active?.productName ?? '' })
   return { run, line: getDcwController().lineState(id) }
 })

package/server/api/workshop/dcw/lines/[id]/stop.post.ts

@@ -9,6 +9,7 @@ import { bindDcwBroadcast, getDcwController } from '@/server/services/workshop/d
 import { broadcastSceneEvent } from '@/server/services/workshop/scene-events'
 import { getActiveLineRun } from '@/server/services/workshop/dcw/line-run'
 import { recordOps } from '@/server/services/workshop/ops/ops'
+import { emitLineLifecycle } from '@/server/services/workshop/plugins/host.mjs'
 
 export default defineApiHandler(async (event) => {
   const user = resolveUser(event)
@@ -30,5 +31,6 @@ export default defineApiHandler(async (event) => {
     recipeId: active?.recipeId ?? '',
     detail: { runId: active?.runId ?? '' },
   })
+  emitLineLifecycle('line:stop', { lineId: id, runId: active?.runId ?? run?.id ?? '' })
   return { run, line: getDcwController().lineState(id) }
 })