agentworkshop 0.2.1 → 0.3.0

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,8 +1,23 @@
 {
   "name": "agentworkshop",
-  "version": "0.2.1",
+  "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"
@@ -10,6 +25,7 @@
   "files": [
     "bin",
     "cli",
+    "sdk",
     "app",
     "server",
     "shared",
@@ -24,7 +40,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/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/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/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