agentworkshop 0.2.2 → 0.4.0

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

@@ -15,29 +15,15 @@
 // ============================================================
 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'
-
-/** 服务端生命周期事件清单(宿主触发;文档见 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 { LIFECYCLE_EVENTS, CLIENT_EVENTS } from './lifecycle.mjs'
 
 export default {
   SDK_VERSION,
@@ -47,6 +33,7 @@ export default {
   createRouteTable,
   validatePluginModule,
   pluginKvExists,
+  createPlatformClient,
   CLIENT_SDK_VERSION,
   createClientContext,
   LIFECYCLE_EVENTS,

package/sdk/lifecycle.mjs

@@ -0,0 +1,25 @@
+// ============================================================
+// AgentWorkShop SDK — 生命周期事件清单(宿主触发;单一事实源)
+// ============================================================
+
+/** 服务端生命周期事件清单(宿主触发;文档见 docs/plugins.md) */
+export const LIFECYCLE_EVENTS = Object.freeze([
+  'plugin:host:init',
+  'config:changed',
+  'event:*',
+  'daq:sample',
+  'dcw:write',
+  'line:start',
+  'line:stop',
+  'server:close',
+])
+
+/** 客户端生命周期事件清单 */
+export const CLIENT_EVENTS = Object.freeze([
+  'client:init',
+  'event:*',
+  'page:change',
+  'client:destroy',
+])
+
+export default { LIFECYCLE_EVENTS, CLIENT_EVENTS }

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

@@ -3,10 +3,10 @@
  * 插件经 ctx.route(method, path, handler) 注册;handler(event) 返回值由 nitro 序列化。
  * 鉴权由插件自行处理(v1 不强制;可经 resolveUser 复用业务鉴权)。
  */
-import { defineEventHandler, createError } from 'h3'
+import { defineEventHandler, createError, readBody } from 'h3'
 import { getPluginHost } from '@/server/services/workshop/plugins/host.mjs'
 
-export default defineEventHandler((event) => {
+export default defineEventHandler(async (event) => {
   const host = getPluginHost()
   if (!host) throw createError({ statusCode: 503, statusMessage: 'plugin host not ready' })
   const name = String(event.context.params?.name ?? '')
@@ -15,5 +15,8 @@ export default defineEventHandler((event) => {
   if (!handler) {
     throw createError({ statusCode: 404, statusMessage: `plugin route not found: ${event.method} /api/plugins/${name}${path}` })
   }
+  // 预读 body 挂到 event(插件 handler 无 h3 导入能力,经 event.awBody 消费)
+  const awBody = await readBody(event).catch(() => undefined)
+  ;(event as Record<string, unknown>).awBody = awBody
   return handler(event)
 })

package/server/api/workshop/plugins/[name]/disable.post.ts

@@ -0,0 +1,19 @@
+/**
+ * POST /api/workshop/plugins/:name/disable —— 停用插件(admin;热重载生效)。
+ */
+import { defineEventHandler, createError } from 'h3'
+import { resolveUser, requireAdmin } from '@/server/api/workshop/caller'
+import { pluginManifest, reloadPluginHost, setPluginEnabled } from '@/server/services/workshop/plugins/host.mjs'
+
+export default defineEventHandler(async (event) => {
+  const user = resolveUser(event)
+  requireAdmin(event)
+  const name = String(event.context.params?.name ?? '')
+  if (!pluginManifest().some(p => p.name === name)) {
+    throw createError({ statusCode: 404, statusMessage: `plugin not found: ${name}` })
+  }
+  setPluginEnabled(name, false)
+  await reloadPluginHost()
+  const p = pluginManifest().find(x => x.name === name)
+  return { ok: true, enabled: p?.enabled ?? false, by: user.name }
+})

package/server/api/workshop/plugins/[name]/enable.post.ts

@@ -0,0 +1,19 @@
+/**
+ * POST /api/workshop/plugins/:name/enable —— 启用插件(admin;热重载生效)。
+ */
+import { defineEventHandler, createError } from 'h3'
+import { resolveUser, requireAdmin } from '@/server/api/workshop/caller'
+import { pluginManifest, reloadPluginHost, setPluginEnabled } from '@/server/services/workshop/plugins/host.mjs'
+
+export default defineEventHandler(async (event) => {
+  const user = resolveUser(event)
+  requireAdmin(event)
+  const name = String(event.context.params?.name ?? '')
+  if (!pluginManifest().some(p => p.name === name)) {
+    throw createError({ statusCode: 404, statusMessage: `plugin not found: ${name}` })
+  }
+  setPluginEnabled(name, true)
+  await reloadPluginHost()
+  const p = pluginManifest().find(x => x.name === name)
+  return { ok: true, enabled: p?.enabled ?? true, by: user.name }
+})

package/server/api/workshop/plugins/[name]/index.get.ts

@@ -0,0 +1,14 @@
+/**
+ * GET /api/workshop/plugins/:name —— 单插件详情(鉴权)。
+ */
+import { defineEventHandler, createError } from 'h3'
+import { resolveUser } from '@/server/api/workshop/caller'
+import { pluginManifest } from '@/server/services/workshop/plugins/host.mjs'
+
+export default defineEventHandler((event) => {
+  resolveUser(event)
+  const name = String(event.context.params?.name ?? '')
+  const p = pluginManifest().find(x => x.name === name)
+  if (!p) throw createError({ statusCode: 404, statusMessage: `plugin not found: ${name}` })
+  return p
+})

package/server/api/workshop/plugins/index.get.ts

@@ -0,0 +1,17 @@
+/**
+ * GET /api/workshop/plugins —— 插件管理清单(鉴权;含启停状态/路由/装载失败)。
+ * 网页「插件管理」页数据源。
+ */
+import { defineEventHandler } from 'h3'
+import { resolveUser } from '@/server/api/workshop/caller'
+import { getPluginHost, pluginManifest } from '@/server/services/workshop/plugins/host.mjs'
+
+export default defineEventHandler((event) => {
+  resolveUser(event)
+  const host = getPluginHost()
+  return {
+    plugins: pluginManifest(),
+    failures: host?.failures ?? [],
+    initedAt: host?.initedAt ?? null,
+  }
+})