agentworkshop 0.2.1 → 0.2.2

package/app/plugins/aw-plugins.client.ts

@@ -0,0 +1,79 @@
+/**
+ * aw 插件客户端装载器 —— 前端增强入口。
+ * - 启动期拉取 /api/plugins/manifest → 对含 client 的插件动态 import 脚本
+ * - 每个插件获得独立 ctx(sdk/client.mjs):事件订阅/Hooks/DOM 助手/私有挂载点
+ * - 事件桥:useTownBus(AEP 信封,与 WS 同源) → ctx.hooks(event:<type> / '*')
+ * - 错误隔离:单插件装载失败仅告警,不影响应用与其他插件
+ * 插件契约见 docs/plugins.md;信任模型与 aw commands 相同(仅装可信代码)。
+ */
+import { createClientContext } from '@/sdk/client.mjs'
+import type { TownBus } from '~/composables/workshop/useTownBus'
+
+export default defineNuxtPlugin(async (nuxtApp) => {
+  if (!import.meta.client) return
+
+  const loaded: Array<{ name: string, ctx: ReturnType<typeof createClientContext> }> = []
+
+  const bridgeFactory = (bus: TownBus | null) => (fn: (type: string, payload: unknown) => void) => {
+    if (!bus) return () => {}
+    return bus.subscribe((e) => {
+      try {
+        fn(e.type, e.payload)
+      }
+      catch (err) {
+        console.warn(`[aw-plugins] 事件分发异常:`, err)
+      }
+    })
+  }
+
+  try {
+    const res = await fetch('/api/plugins/manifest', { headers: { accept: 'application/json' } })
+    if (!res.ok) return
+    const body = await res.json().catch(() => null) as { plugins?: Array<{ name: string, hasClient?: boolean }> } | null
+    const plugins = (body?.plugins ?? []).filter(p => p.hasClient)
+    if (!plugins.length) return
+
+    let bus: TownBus | null = null
+    try {
+      bus = useTownBus()
+    }
+    catch {
+      bus = null // WS 总线不可用(离线)时插件仍可装载,只是无事件流
+    }
+
+    for (const p of plugins) {
+      try {
+        const mod = await import(/* @vite-ignore */ `/api/plugins/client/${encodeURIComponent(p.name)}`)
+        const setup = (mod as { setup?: unknown }).setup ?? (mod as { default?: { setup?: unknown } }).default?.setup
+        if (typeof setup !== 'function') {
+          console.warn(`[aw-plugins] ${p.name} 客户端入口缺少 setup(ctx)`)
+          continue
+        }
+        const ctx = createClientContext({
+          name: p.name,
+          eventBridge: bridgeFactory(bus),
+        })
+        await (setup as (ctx: unknown) => void | Promise<void>)(ctx)
+        void ctx.hooks.emit('client:init', { name: p.name })
+        loaded.push({ name: p.name, ctx })
+        console.info(`[aw-plugins] ✔ 客户端插件已装载: ${p.name}`)
+      }
+      catch (err) {
+        console.warn(`[aw-plugins] 客户端插件装载失败 ${p.name}:`, err)
+      }
+    }
+
+    // 页面切换广播(page:change)
+    if (loaded.length) {
+      nuxtApp.hooks.hook('page:finish', () => {
+        const route = useRoute()
+        for (const { ctx } of loaded) {
+          void ctx.hooks.emit('page:change', { path: route.path })
+        }
+      })
+    }
+  }
+  catch {
+    // 网络不可达/服务未就绪:静默(插件是增强层,绝不阻断应用)
+  }
+})

package/cli/commands/plugin.mjs

@@ -0,0 +1,169 @@
+// ============================================================
+// 指令:plugin — 插件管理(list / create 脚手架)
+// ------------------------------------------------------------
+// 插件目录(与配置根一致):
+//   project: <repo>/.AgentWorkShop/plugins/<name>/
+//   user:    ~/.AgentWorkShop/plugins/<name>/
+// 插件契约:入口 index.mjs 导出 { name, version?, description?,
+//   setup(ctx)?, client?: './client.mjs', routes?: [...] } —— 零导入依赖。
+// ============================================================
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { color } from '../core/logger.mjs'
+import { CliError } from '../core/errors.mjs'
+
+export const meta = {
+  name: 'plugin',
+  aliases: ['plugins', 'plug'],
+  group: '扩展',
+  summary: '插件管理:查看已装插件 / 脚手架新插件',
+  usage: 'aw plugin <list|create> [name] [--project|--global] [--force]',
+  description: [
+    '插件 = 配置根 plugins/<name>/ 下的 node 项目:入口 index.mjs 导出',
+    '{ name, setup(ctx) } 即自动装载(服务端钩子/API 路由),client.mjs 可选(浏览器增强)。',
+    '服务端钩子:daq:sample / dcw:write / line:start|stop / event:*(scene 全事件)/ server:close。',
+  ],
+  needsProject: false,
+}
+
+const ENTRY_TEMPLATE = name => `/**
+ * ${name} — AgentWorkShop 插件(入口)。
+ * setup(ctx) 服务端生命周期:ctx.hooks / ctx.config / ctx.kv / ctx.route / ctx.logger / ctx.http / ctx.events
+ * 完整契约见 docs/plugins.md。
+ */
+export default {
+  name: '${name}',
+  version: '0.1.0',
+  description: '${name} 插件',
+  client: './client.mjs',
+
+  async setup(ctx) {
+    ctx.logger.info('已装载 ✓')
+
+    // 示例:订阅数采采样(下发级),计数落插件私有 KV
+    ctx.hooks.on('daq:sample', (s) => {
+      ctx.kv.bump('samples')
+      void s
+    })
+
+    // 示例:产线生命周期
+    ctx.hooks.on('line:start', (p) => {
+      ctx.kv.set('lineRunning', true)
+      ctx.logger.info('产线开跑', p?.lineId)
+    })
+    ctx.hooks.on('line:stop', () => ctx.kv.set('lineRunning', false))
+
+    // 示例:注册插件 API → GET /api/plugins/${name}/stats
+    ctx.route('GET', '/stats', () => ({
+      plugin: ctx.name,
+      samples: ctx.kv.get('samples') ?? 0,
+      lineRunning: ctx.kv.get('lineRunning') ?? false,
+      at: new Date().toISOString(),
+    }))
+
+    // 示例:scene 实时事件订阅(与 WS 同源)
+    ctx.events.on('daq.node.changed', (p) => {
+      ctx.logger.debug('node changed', p)
+    })
+  },
+}
+`
+
+const CLIENT_TEMPLATE = name => `// ${name} — 客户端增强(可选;自包含 ESM,无裸导入)
+// ctx: on(type,fn) 事件订阅 / el() DOM 助手 / root() 私有挂载点 / log
+export function setup(ctx) {
+  const badge = ctx.el('div', {
+    style: 'padding:6px 10px;border:1px solid #2de0a0;border-radius:8px;color:#2de0a0;background:rgba(0,0,0,.55)',
+  }, [\`\${ctx.name} · 0\`])
+  ctx.root().append(badge)
+
+  let n = 0
+  ctx.on('daq:sample', () => {
+    n++
+    badge.textContent = \`\${ctx.name} · \${n} 样本\`
+  })
+
+  ctx.log.info('client ready')
+}
+`
+
+const PLUGIN_README = name => `# ${name}
+
+AgentWorkShop 插件。重启 \`aw start\` / \`aw dev\` 自动装载。
+
+- \`index.mjs\` — 服务端入口(setup(ctx))
+- \`client.mjs\` — 浏览器增强(可选)
+- API:GET /api/plugins/${name}/stats
+`
+
+export async function run(argv, ctx) {
+  const { flags, positionals } = argv
+  const sub = positionals[0] ?? 'list'
+
+  if (sub === 'list' || sub === 'ls')
+    return list(ctx)
+
+  if (sub === 'create' || sub === 'new' || sub === 'add')
+    return create(ctx, positionals[1], flags)
+
+  throw new CliError('USAGE', '用法: aw plugin <list|create> [name] [--project|--global]')
+}
+
+function scopes(ctx) {
+  return [
+    { scope: 'project', dir: ctx.root ? join(ctx.root, '.AgentWorkShop', 'plugins') : null, label: '项目级' },
+    { scope: 'user', dir: ctx.commandsDir?.global ? join(ctx.home, 'plugins') : join(ctx.home, 'plugins'), label: '用户级' },
+  ]
+}
+
+function list(ctx) {
+  console.log('')
+  console.log(`${color.bold('AgentWorkShop 插件')}  ${color.dim('— 配置根 plugins/ 目录,重启自动装载')}`)
+  let total = 0
+  for (const { dir, label } of scopes(ctx)) {
+    console.log('')
+    console.log(color.bold(`  ${label} ${color.dim(dir)}`))
+    if (!dir || !existsSync(dir)) {
+      console.log(`    ${color.dim('(目录不存在)')}`)
+      continue
+    }
+    const dirs = readdirSync(dir).filter(n => existsSync(join(dir, n, 'index.mjs')))
+    if (!dirs.length) {
+      console.log(`    ${color.dim('(空 —— aw plugin create <name> 创建)')}`)
+      continue
+    }
+    for (const name of dirs) {
+      total++
+      const hasClient = existsSync(join(dir, name, 'client.mjs'))
+      console.log(`    ${color.green('●')} ${color.cyan(name.padEnd(24))}${hasClient ? `${color.dim(' +client')}` : ''}`)
+    }
+  }
+  console.log('')
+  console.log(color.dim(`共 ${total} 个 · 契约: index.mjs 导出 { name, setup(ctx) } · 文档: docs/plugins.md`))
+  console.log('')
+  return 0
+}
+
+function create(ctx, name, flags) {
+  if (!name || !/^[a-z][a-z0-9-]{1,31}$/.test(name)) {
+    throw new CliError('USAGE', '用法: aw plugin create <name> [--project|--global](name: 小写字母开头,2-32 位 a-z0-9-)')
+  }
+  const global = Boolean(flags.global ?? flags.g)
+  const force = Boolean(flags.force ?? flags.f)
+  const target = global
+    ? join(ctx.home, 'plugins', name)
+    : join((ctx.root ?? process.cwd()), '.AgentWorkShop', 'plugins', name)
+
+  if (existsSync(join(target, 'index.mjs')) && !force) {
+    throw new CliError('CONFLICT', `插件已存在: ${target}(--force 覆盖)`)
+  }
+  mkdirSync(target, { recursive: true })
+  writeFileSync(join(target, 'index.mjs'), ENTRY_TEMPLATE(name), 'utf8')
+  writeFileSync(join(target, 'client.mjs'), CLIENT_TEMPLATE(name), 'utf8')
+  writeFileSync(join(target, 'README.md'), PLUGIN_README(name), 'utf8')
+
+  console.log(`${color.green('✔')} 插件已创建: ${color.bold(name)} → ${target}`)
+  console.log(`  › 重启服务自动装载;API 示例: ${color.cyan(`GET /api/plugins/${name}/stats`)}`)
+  console.log(`  › 查看列表: ${color.cyan('aw plugin list')}`)
+  return 0
+}

package/cli/commands/update.mjs

@@ -59,13 +59,22 @@ function cmpVersions(a, b) {
   return 0
 }
 
+/** 全局实际安装的版本(npm ls -g);拿不到回退 null */
+function globalVersion(name, registry) {
+  const ls = npmRun(['ls', '-g', '--depth=0', name], { registry })
+  return new RegExp(`${name}@(\\S+)`).exec(ls.stdout ?? '')?.[1] ?? null
+}
+
 export async function run(argv, ctx) {
   const { flags } = argv
   const registry = flags.registry ? String(flags.registry) : undefined
   const name = pkgName(ctx)
-  const current = packageVersion()
+  // 当前版本 = 全局实际安装的版本(即 `aw update` 要更新的对象);
+  // 拿不到(未全局安装)才回退运行中 CLI 版本
+  const global = globalVersion(name, registry)
+  const current = global ?? packageVersion()
 
-  console.log(`${color.cyan('›')} 当前版本: ${color.bold(`v${current}`)}`)
+  console.log(`${color.cyan('›')} 当前版本: ${color.bold(`v${current}`)}${global ? '' : color.dim(' (运行中 CLI;未检测到全局安装)')}`)
   console.log(`${color.cyan('›')} 查询 npm registry${registry ? ` (${registry})` : ''} ...`)
 
   const view = npmRun(['view', name, 'version'], { registry })
@@ -107,8 +116,7 @@ export async function run(argv, ctx) {
   }
 
   // 复核:从全局包清单读回实际安装版本
-  const ls = npmRun(['ls', '-g', '--depth=0', name], { registry })
-  const installed = new RegExp(`${name}@(\\S+)`).exec(ls.stdout ?? '')?.[1]
+  const installed = globalVersion(name, registry)
   if (installed) console.log(`${color.green('✔')} 更新完成: ${color.dim(current)} → ${color.bold(installed)}`)
   else console.log(`${color.green('✔')} 更新完成 → ${color.bold(latest)}`)
   console.log(`${color.dim('›')} 新开 aw 进程即运行新版本(当前进程仍是旧代码)`)

package/docs/plugins.md

@@ -0,0 +1,127 @@
+# AgentWorkShop 插件开发指南（SDK）
+
+> 插件 = 配置根 `plugins/<name>/` 下的一个 node 项目。基于内置 SDK 的生命周期钩子,
+> 可以同时增强**服务端**(数据/事件/API)与**浏览器**(面板/遥测/交互)。
+> 与 `aw` 指令同哲学:放入目录即装载,约定优于配置。
+
+## 一、快速开始
+
+```bash
+aw plugin create my-plugin            # 脚手架到 ~/.AgentWorkShop/plugins/(用户级)
+aw plugin create my-plugin --project  # 或项目级 <repo>/.AgentWorkShop/plugins/
+aw plugin list                        # 查看两处已装插件
+aw start                              # 重启即自动装载
+```
+
+目录结构(标准 node 项目形态):
+
+```
+plugins/my-plugin/
+├── index.mjs      # 服务端入口(必需): export default { name, setup(ctx) }
+├── client.mjs     # 浏览器增强(可选): export function setup(ctx)
+└── README.md
+```
+
+## 二、插件契约
+
+`index.mjs` 导出**普通对象**(零导入依赖——ctx 由宿主注入,这是全局安装零解析链约束下的标准形态;TypeScript 作者可 `import type { definePlugin } from 'agentworkshop/sdk'` 获得类型提示,构建期擦除):
+
+```js
+export default {
+  name: 'my-plugin',            // 必填,全局唯一
+  version: '1.0.0',
+  description: '…',
+  client: './client.mjs',       // 可选:浏览器增强入口(相对路径)
+  routes: [                     // 可选:声明式 API(也可在 setup 里 ctx.route())
+    { method: 'GET', path: '/health', handler: () => ({ ok: true }) },
+  ],
+  async setup(ctx) { /* 服务端生命周期 */ },
+}
+```
+
+## 三、服务端 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 |
+|---|---|---|
+| `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.on('daq:sample', fn)` / `ctx.on('event:daq.reading', fn)` / `ctx.on('*', fn)` | 实时事件订阅(与 WS 同源;另支持 `page:change`) |
+| `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 并装载。
+
+```js
+// client.mjs
+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}` })
+}
+```
+
+## 六、插件 API(增强后端)
+
+```js
+ctx.route('GET', '/stats', () => ctx.kv.all())
+ctx.route('POST', '/reset', () => { ctx.kv.set('samples', 0); return { ok: true } })
+```
+
+→ `GET/POST /api/plugins/my-plugin/stats|reset`。鉴权 v1 由插件自理(可在 handler 内复用
+`resolveUser(event)` 走业务鉴权)。
+
+## 七、完整示例
+
+`sdk/examples/sample-insight/` —— 订阅采样计数 + 统计 API + 浏览器徽标:
+
+```bash
+cp -r sdk/examples/sample-insight ~/.AgentWorkShop/plugins/
+aw start   # → GET /api/plugins/sample-insight/stats · 浏览器右下角徽标
+```
+
+## 八、发布与信任模型
+
+- 插件是**任意 node 代码**,与 aw commands 同信任模型:只安装/启用你信任的插件。
+- 插件随配置根走:repo 检出内 = `<repo>/.AgentWorkShop/plugins`(团队可 git 版本化);
+  全局安装 = `~/.AgentWorkShop/plugins`(AW_HOME 可重定向)。
+- 服务端生命周期结束(`server:close`)、卸载插件 = 直接删目录重启。
+
+## 九、SDK 版本对照
+
+| SDK | 随包 | 说明 |
+|---|---|---|
+| `sdk/hooks.mjs` | `agentworkshop/sdk`(0.2.2+) | HookBus(可独立用于任何 node 项目) |
+| `sdk/context.mjs` | 同上 | 服务端 ctx 工厂 + 路由表 + 插件校验 |
+| `sdk/client.mjs` | 同上 | 浏览器 ctx 工厂 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentworkshop",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "type": "module",
   "description": "AgentWorkShop 软件开发系统 - 基于 Nuxt 4 的配置驱动运行范式",
   "bin": {
@@ -10,6 +10,7 @@
   "files": [
     "bin",
     "cli",
+    "sdk",
     "app",
     "server",
     "shared",
@@ -24,7 +25,8 @@
     "docker-compose.yml",
     ".env.example",
     "README-zh.md",
-    "docs/cli.md"
+    "docs/cli.md",
+    "docs/plugins.md"
   ],
   "packageManager": "pnpm@11.9.0",
   "engines": {

package/scripts/home-bootstrap.mjs

@@ -40,6 +40,23 @@ export async function run(argv, ctx) {
 也可以用 \`aw register <path|url|npm:pkg> --global\` 自动注册到这里。
 `
 
+const PLUGINS_README = `# AW Home 插件目录
+
+每个子文件夹 = 一个插件(node 项目,入口 index.mjs),重启 aw start / aw dev 自动装载。
+
+\`\`\`
+plugins/
+└── my-plugin/
+    ├── index.mjs    # 服务端: export default { name, setup(ctx) }
+    └── client.mjs   # 浏览器增强(可选): export function setup(ctx)
+\`\`\`
+
+生命周期钩子: daq:sample · dcw:write · line:start|stop · event:*(scene 全事件) · server:close
+插件 API: ctx.route('GET', '/x', handler) → /api/plugins/my-plugin/x
+
+完整指南: docs/plugins.md · 脚手架: aw plugin create <name>
+`
+
 /**
  * 执行引导。返回 { home, created: string[], seeds: string[] }。
  * @param {{ quiet?: boolean, env?: NodeJS.ProcessEnv }} opts
@@ -53,7 +70,7 @@ export function runBootstrap({ quiet = false, env = process.env } = {}) {
   const seeds = []
 
   // 1. 目录骨架
-  for (const dir of [home, join(home, 'data'), join(home, 'logs'), join(home, 'commands')]) {
+  for (const dir of [home, join(home, 'data'), join(home, 'logs'), join(home, 'commands'), join(home, 'plugins')]) {
     if (!existsSync(dir)) {
       mkdirSync(dir, { recursive: true })
       created.push(dir)
@@ -97,6 +114,13 @@ export function runBootstrap({ quiet = false, env = process.env } = {}) {
     writeFileSync(readmeDest, COMMANDS_README, 'utf8')
   }
 
+  // 7. 插件目录说明(插件 = 配置根 plugins/<name>/ 的 node 项目,SDK 驱动,见 docs/plugins.md)
+  const pluginsReadme = join(home, 'plugins', 'README.md')
+  if (!existsSync(pluginsReadme)) {
+    writeFileSync(pluginsReadme, PLUGINS_README, 'utf8')
+    seeds.push('plugins/README.md')
+  }
+
   log(`[aw-home] ${home}  ${created.length ? `（新建 ${created.length} 项）` : '（已就绪）'}`)
   if (seeds.length) log(`[aw-home] 种子文件: ${seeds.join(', ')}`)
   return { home, created, seeds }

package/sdk/client.mjs

@@ -0,0 +1,76 @@
+// ============================================================
+// 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)
+//   ctx.on(type, fn)      scene 实时事件订阅(与 WS 同源;'*' 通配)
+//   ctx.el(tag, attrs, children)   DOM 助手(挂到任意面板/宿主节点)
+//   ctx.mount(selector|el, node)   挂载节点(缺失时挂 body 角落)
+//   ctx.log   前缀 console
+//   ctx.root  插件 UI 挂载点(懒创建,自动附加到 body,#aw-plugin-<name>)
+// ============================================================
+import { HookBus } from './hooks.mjs'
+
+export const CLIENT_SDK_VERSION = '0.2.2'
+
+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 }) {
+  const hooks = new HookBus({ name: `client:${name}`, onError: err => console.warn(`[aw-plugin:${name}]`, err) })
+  let rootEl = null
+
+  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)),
+    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
+    },
+  }
+
+  // scene 事件桥 → ctx.hooks(event:<type> 与 '*' 均可订阅)
+  if (eventBridge) {
+    eventBridge((type, payload) => {
+      void hooks.emit(`event:${type}`, payload)
+    })
+  }
+
+  return ctx
+}
+
+export default { CLIENT_SDK_VERSION, createClientContext, el }