agentworkshop 0.2.2 → 0.4.0

package/scripts/home-bootstrap.mjs

@@ -7,7 +7,7 @@
 // 原则：幂等（已存在绝不覆盖）、零依赖、任何失败只告警不阻断安装。
 // ============================================================
 import { randomBytes } from 'node:crypto'
-import { copyFileSync, existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import { copyFileSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -121,6 +121,31 @@ export function runBootstrap({ quiet = false, env = process.env } = {}) {
     seeds.push('plugins/README.md')
   }
 
+  // 8. 官方示例插件随包分发(sdk/examples/*):只复制目标缺失的目录,绝不覆盖用户改动;
+  //    新种子的示例默认**停用**(写入 plugins-state.json),经 aw plugin enable 开启
+  const examplesSrc = join(packageRoot, 'sdk', 'examples')
+  if (existsSync(examplesSrc)) {
+    const pluginsDir2 = join(home, 'plugins')
+    const stateFile = join(home, 'plugins-state.json')
+    let state = { version: 1, updatedAt: new Date().toISOString(), disabled: [] }
+    try {
+      state = JSON.parse(readFileSync(stateFile, 'utf8'))
+    }
+    catch { /* 首次无状态文件 */ }
+    state.disabled ??= []
+    for (const example of readdirSync(examplesSrc)) {
+      const dest = join(pluginsDir2, example)
+      if (existsSync(join(dest, 'index.mjs'))) continue // 已存在(或用户改过)——不动
+      cpSync(join(examplesSrc, example), dest, { recursive: true })
+      if (!state.disabled.includes(example)) state.disabled.push(example) // 默认停用
+      seeds.push(`plugins/${example}(默认停用)`)
+    }
+    state.updatedAt = new Date().toISOString()
+    const stateTmp = `${stateFile}.${process.pid}.tmp`
+    writeFileSync(stateTmp, `${JSON.stringify(state, null, 2)}\n`, 'utf8')
+    renameSync(stateTmp, stateFile)
+  }
+
   log(`[aw-home] ${home}  ${created.length ? `（新建 ${created.length} 项）` : '（已就绪）'}`)
   if (seeds.length) log(`[aw-home] 种子文件: ${seeds.join(', ')}`)
   return { home, created, seeds }

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,40 @@ 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 抛错;自动携带 cookie token) */
+    fetch: async (path, opt = {}) => {
+      const headers = { accept: 'application/json', ...(opt.body !== undefined ? { 'content-type': 'application/json' } : {}), ...(opt.headers ?? {}) }
+      // 自动注入 cookie 里的平台 token(Authorization: Bearer)——与全站 $http 拦截器同源
+      const mCookie = document.cookie.match(/(?:^|;\s*)token=([^;]+)/)
+      if (mCookie) headers.authorization = `Bearer ${decodeURIComponent(mCookie[1])}`
+      const res = await fetch(`${baseUrl}${path}`, {
+        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 +87,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/examples/line-sentinel/client.mjs

@@ -0,0 +1,31 @@
+// line-sentinel — 客户端徽标(实时显示采样计数与告警态)
+export function setup(ctx) {
+  const badge = ctx.el('div', {
+    id: 'line-sentinel-badge',
+    style: 'display:flex;align-items:center;gap:8px;padding:8px 12px;'
+      + 'border:1px solid rgba(53,224,160,.5);border-radius:10px;'
+      + 'background:rgba(6,18,14,.85);color:#35e0a0;'
+      + 'font:600 12px/1 ui-monospace,monospace;letter-spacing:.4px;'
+      + 'box-shadow:0 4px 18px rgba(0,0,0,.35);cursor:default',
+  }, ['🛡 line-sentinel · 待机'])
+
+  ctx.root().append(badge)
+
+  let n = 0
+  let alarms = 0
+
+  ctx.on('daq:sample', () => {
+    n++
+    badge.textContent = `🛡 line-sentinel · ${n} 样本 · ${alarms} 告警`
+  })
+
+  // 服务端告警状态变化经 event 桥可见(ops.log 或轮询 stats;此处演示事件订阅)
+  ctx.on('event:line.start', () => {
+    badge.style.borderColor = '#35e0a0'
+  })
+  ctx.on('event:line.stop', () => {
+    badge.style.borderColor = 'rgba(53,224,160,.35)'
+  })
+
+  ctx.log.info('哨兵徽标已挂载(右下角)')
+}

package/sdk/examples/line-sentinel/index.mjs

@@ -0,0 +1,102 @@
+/**
+ * line-sentinel — 产线哨兵(真实场景插件)
+ * ------------------------------------------------------------
+ * 职责:持续监视运行中产线的数采样本,越过告警阈值即记录并在 API 暴露;
+ * 心跳定时器自证存活;监听产线启停与配置变更;展示 SDK 全部能力面。
+ *
+ * 使用 SDK 面:ctx.hooks · ctx.api(平台客户端) · ctx.timer(自动回收)
+ *            · ctx.onDispose · ctx.kv · ctx.route · ctx.config.onChange
+ *            · ctx.events · ctx.logger
+ */
+export default {
+  name: 'line-sentinel',
+  version: '1.0.0',
+  description: '产线哨兵:数采越限告警 + 心跳 + 产线生命周期跟踪',
+  client: './client.mjs',
+
+  async setup(ctx) {
+    ctx.logger.info(`装载完成(scope=${ctx.scope}, sdk=${ctx.sdkVersion})`)
+
+    // 平台服务消费:启动时经 SDK API 客户端读取产线清单(自环调用)
+    try {
+      const lines = await ctx.api.lines.list()
+      ctx.kv.set('linesTotal', Array.isArray(lines) ? lines.length : 0)
+      ctx.logger.info(`平台产线清单: ${ctx.kv.get('linesTotal')} 条`)
+    }
+    catch (err) {
+      ctx.logger.warn('产线清单读取失败(服务启动中,跳过):', err?.message)
+    }
+
+    // 配置变更订阅(aw config set / 设置页写入 → runtime-settings.json 变化)
+    ctx.config.onChange(() => {
+      const theme = ctx.config.get('theme.primaryColor')
+      ctx.logger.info(`配置已变更,当前主题色: ${theme}`)
+      ctx.kv.set('lastConfigAt', new Date().toISOString())
+    })
+
+    // 产线生命周期跟踪(事件消费增强:运行中产线计数)
+    ctx.hooks.on('line:start', (p) => {
+      ctx.kv.set('running', true)
+      ctx.kv.bump('runningCount')
+      ctx.kv.set('lastRun', { lineId: p?.lineId, at: new Date().toISOString() })
+      ctx.logger.info(`▶ 产线开跑 ${p?.lineId}`)
+    })
+    ctx.hooks.on('line:stop', () => {
+      ctx.kv.set('running', false)
+      ctx.logger.info('■ 产线停止')
+    })
+
+    // 核心:数采样本越限告警(阈值可经插件 KV 配置,默认 180)
+    ctx.hooks.on('daq:sample', (s) => {
+      ctx.kv.bump('samples')
+      const threshold = Number(ctx.kv.get('threshold')) || 180
+      if (typeof s?.value === 'number' && s.value > threshold) {
+        const key = `alarm:${s.nodeId}`
+        const prev = ctx.kv.get(key) ?? { count: 0 }
+        ctx.kv.set(key, { count: (prev.count ?? 0) + 1, value: s.value, at: s.at })
+        if ((prev.count ?? 0) === 0) ctx.logger.warn(`⚠ 越限告警 ${s.nodeId}: ${s.value} > ${threshold}`)
+      }
+    })
+
+    // scene 实时事件订阅(糖衣)
+    ctx.events.on('daq.node.changed', (p) => {
+      ctx.logger.debug?.('节点变更', p?.op ?? '')
+    })
+
+    // 心跳定时器(服务关闭自动回收):活性自证经免鉴权 manifest ping 验证 REST 自环通道
+    ctx.timer.setInterval(() => {
+      ctx.kv.set('heartbeat', new Date().toISOString())
+      ctx.api.plugins.manifest()
+        .then(() => ctx.kv.set('apiOk', true))
+        .catch(() => ctx.kv.set('apiOk', false))
+    }, 5000)
+
+    // 清理登记(关停时宿主逐个调用)
+    ctx.onDispose(() => ctx.logger.info('哨兵清理:告警状态已随 KV 落盘'))
+
+    // 插件 API:综合报告
+    ctx.route('GET', '/report', () => {
+      const alarms = Object.entries(ctx.kv.all())
+        .filter(([k]) => k.startsWith('alarm:'))
+        .map(([k, v]) => ({ nodeId: k.slice(6), ...v }))
+      return {
+        plugin: ctx.name,
+        version: ctx.version,
+        running: ctx.kv.get('running') ?? false,
+        runningCount: ctx.kv.get('runningCount') ?? 0,
+        heartbeat: ctx.kv.get('heartbeat'),
+        apiChannel: ctx.kv.get('apiOk') === true ? 'ok' : ctx.kv.get('apiOk') === false ? 'down' : 'pending',
+        samplesWatched: ctx.kv.get('samples') ?? 0,
+        threshold: Number(ctx.kv.get('threshold')) || 180,
+        alarms,
+      }
+    })
+
+    ctx.route('POST', '/threshold', (event) => {
+      // 宿主 catchall 已预读 body 挂在 event.awBody
+      const v = Number(event.awBody?.threshold) || 180
+      ctx.kv.set('threshold', v)
+      return { ok: true, threshold: v }
+    })
+  },
+}

package/sdk/examples/ops-notifier/client.mjs

@@ -0,0 +1,23 @@
+// ops-notifier — 客户端通知(最近一次写控 toast)
+export function setup(ctx) {
+  const toast = ctx.el('div', {
+    style: 'display:none;padding:10px 14px;border:1px solid rgba(244,197,66,.6);'
+      + 'border-radius:10px;background:rgba(20,16,4,.88);color:#f4c542;'
+      + 'font:600 12px/1.5 ui-monospace,monospace;box-shadow:0 4px 18px rgba(0,0,0,.35)',
+  })
+  ctx.root().prepend(toast)
+
+  let timer = null
+  ctx.on('dcw:write', (w) => {
+    toast.textContent = w.ok
+      ? `✔ 写入 ${w.name} → ${w.eng}${w.source ? `(${w.source})` : ''}`
+      : `✖ 写入失败 ${w.name}`
+    toast.style.display = 'block'
+    clearTimeout(timer)
+    timer = setTimeout(() => {
+      toast.style.display = 'none'
+    }, 4000)
+  })
+
+  ctx.log.info('写控通知已就绪')
+}

package/sdk/examples/ops-notifier/index.mjs

@@ -0,0 +1,34 @@
+/**
+ * ops-notifier — 写控与产线事件回声(SDK 示例插件)
+ * 滚动记录最近写控/启停事件(内存 + KV 防抖落盘),提供 /recent 查询 API;
+ * 客户端以 toast 展示最近一次写控。展示 dcw:write / line:* 钩子与事件消费。
+ */
+const ROLL = 30
+
+export default {
+  name: 'ops-notifier',
+  version: '1.0.0',
+  description: '写控与产线事件回声:滚动记录最近事件 + 查询 API + 客户端通知',
+  client: './client.mjs',
+
+  async setup(ctx) {
+    ctx.logger.info('已装载 —— 监听 dcw:write 与产线启停')
+
+    const push = (entry) => {
+      const log = ctx.kv.get('recent') ?? []
+      log.unshift(entry)
+      ctx.kv.set('recent', log.slice(0, ROLL))
+    }
+
+    ctx.hooks.on('dcw:write', (w) => {
+      push({ kind: 'write', nodeId: w.nodeId, name: w.name, eng: w.eng, ok: w.ok, source: w.source, at: w.at })
+    })
+    ctx.hooks.on('line:start', p => push({ kind: 'line:start', lineId: p?.lineId, at: new Date().toISOString() }))
+    ctx.hooks.on('line:stop', p => push({ kind: 'line:stop', lineId: p?.lineId, at: new Date().toISOString() }))
+
+    ctx.route('GET', '/recent', () => ({
+      plugin: ctx.name,
+      recent: ctx.kv.get('recent') ?? [],
+    }))
+  },
+}