agentworkshop 0.7.27 → 0.7.34

package/scripts/town-scene-clear.mjs

@@ -7,7 +7,7 @@ const BASE = 'http://127.0.0.1:3000'
 const login = await fetch(`${BASE}/api/users/login`, {
   method: 'POST',
   headers: { 'content-type': 'application/json' },
-  body: JSON.stringify({ email: 'zhangwei@awshop.io', password: 'Awshop@123' }),
+  body: JSON.stringify({ email: process.env.E2E_USER ?? 'zhangwei@awshop.io', password: process.env.E2E_PASS ?? 'Awshop@123' }),
 }).then(r => r.json())
 const H = { 'authorization': `Bearer ${login.data.token}`, 'content-type': 'application/json' }
 

package/sdk/client.d.mts

@@ -0,0 +1,110 @@
+// AgentWorkShop SDK 类型声明(agentworkshop/sdk/client)
+// ------------------------------------------------------------
+// 与 sdk/client.mjs 一一对应(浏览器侧;自包含、零框架依赖)。
+// 运行时命名导出: CLIENT_SDK_VERSION, createClientContext, default
+// default 额外携带模块私有的 el() 助手(命名导出不含 el)。
+// 消费方通常直接 import { createClientContext } from 'agentworkshop/sdk/client'。
+
+/** 客户端 SDK 版本(与 sdk/client.mjs CLIENT_SDK_VERSION 同步) */
+export declare const CLIENT_SDK_VERSION: string
+
+/** HookBus:异步串行、错误隔离、'*' 通配、连续失败自动熔断 */
+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
+}
+
+/** ctx.log:前缀 console(前缀 [aw-plugin:<name>]) */
+export interface ClientLogger {
+  info(...args: unknown[]): void
+  warn(...args: unknown[]): void
+  error(...args: unknown[]): void
+}
+
+/** ctx.ui.registerPanel 的入参(loader 注入宿主实现) */
+export interface ClientPanelEntry {
+  /** 目标插槽名(经 <PluginSlot slot-name> 渲染) */
+  slot: string
+  /** 面板名(插件内唯一) */
+  name: string
+  /** 面板标题(缺省时宿主回退 titleKey / name) */
+  title?: string
+  /** i18n 标题键(优先于 title) */
+  titleKey?: string
+  /** 同插槽内排序权重 */
+  order?: number
+  /** 渲染回调:入参为该面板的宿主容器节点 */
+  mount(el: HTMLElement): void
+}
+
+/** ctx.ui:UI 注入面(宿主未提供时为告警桩) */
+export interface ClientUi {
+  registerPanel(entry: ClientPanelEntry): () => void
+  /** 已知插槽名(宿主未提供时为 []) */
+  readonly slots: readonly string[]
+}
+
+/** ctx.t 的翻译参数(占位符插值) */
+export type ClientTranslateParams = Record<string, unknown>
+
+/** ctx:客户端插件上下文(由 createClientContext 返回) */
+export interface ClientContext {
+  /** 插件名(与插件 def.name 一致) */
+  name: string
+  /** SDK 版本(= CLIENT_SDK_VERSION) */
+  sdkVersion: string
+  /** 客户端本地 HookBus(client:init / event:* / page:change / client:destroy) */
+  hooks: HookBus
+  /** scene 实时事件订阅(与 WS 同源;type='*' 通配);返回解绑函数,dispose 时自动回收 */
+  on(type: string, fn: (payload: any) => any): () => void
+  /** 同源平台 API 助手(JSON;自动解 {data} 信封;非 2xx 抛错;自动携带 cookie token) */
+  fetch<T = any>(path: string, opt?: { method?: string, body?: unknown, headers?: Record<string, string> }): Promise<T>
+  /** DOM 助手:创建元素;attrs 支持 style / class / on<event> / 其余 setAttribute */
+  el(tag: string, attrs?: Record<string, unknown>, children?: Array<Node | string> | Node | string): HTMLElement
+  /** 挂载节点到选择器/元素(缺失时回落 ctx.root()) */
+  mount(target: string | Element, node: Node): Node
+  /** 插件 UI 挂载点(懒创建,自动附加到 body,#aw-plugin-<name>) */
+  root(): HTMLElement
+  /** UI 注入面(loader 注入;脱离宿主时为告警桩) */
+  ui: ClientUi
+  /** 插件命名空间翻译:ctx.t('settings.title') -> plugin.<name>.settings.title */
+  t(key: string, params?: ClientTranslateParams): string
+  /** 当前界面语言(loader 维护;i18n:changed 钩子在切换时广播;未注入时 '') */
+  readonly locale: string
+  /** 前缀 console 日志 */
+  log: ClientLogger
+  /** 卸载:回收订阅 + 清空挂载点 + 广播 client:destroy(幂等) */
+  dispose(): void
+}
+
+/**
+ * 创建客户端插件上下文(客户端 loader 调用)。
+ * @param opts.name        插件名(必填)
+ * @param opts.eventBridge scene 事件桥:注册回调并返回解绑函数
+ * @param opts.baseUrl     ctx.fetch 的前缀(baseUrl + path)
+ * @param opts.ui          UI 注入面(缺省告警桩)
+ * @param opts.t           翻译函数(缺省回退 plugin.<name>.<key>)
+ * @param opts.getLocale   当前语言读取器(缺省回退 '')
+ */
+export declare function createClientContext(opts?: {
+  name: string
+  eventBridge?: (fn: (type: string, payload: any) => void) => (() => void)
+  baseUrl?: string
+  ui?: ClientUi
+  t?: (key: string, params?: ClientTranslateParams) => string
+  getLocale?: () => string
+}): ClientContext
+
+/** 模块私有 el() 助手(default 导出可见;命名导出不含) */
+export declare function el(tag: string, attrs?: Record<string, unknown>, children?: Array<Node | string> | Node | string): HTMLElement
+
+declare const _default: {
+  CLIENT_SDK_VERSION: string
+  createClientContext: typeof createClientContext
+  el: typeof el
+}
+export default _default

package/sdk/client.mjs

@@ -1,124 +1,144 @@
-// ============================================================
-// 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 / 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.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.3.0'
-
-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, 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) => {
-      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),
-      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
-    },
-    /** 卸载:回收订阅 + 清空挂载点 + 广播 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) {
-    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
-}
-
-export default { CLIENT_SDK_VERSION, createClientContext, el }
+// ============================================================
+// 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 / 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.root  插件 UI 挂载点(懒创建,自动附加到 body,#aw-plugin-<name>)
+//   ctx.ui    UI 注入面:registerPanel({slot,name,title?,titleKey?,order?,mount(el)})
+//             向页面 <PluginSlot slot-name> 命名插槽注入面板;dispose 自动回收
+//   ctx.t(key, params?)      插件命名空间翻译(→ plugin.<name>.<key>;消息来自插件 i18n.json)
+//   ctx.locale               当前界面语言;i18n:changed 钩子在语言切换时广播
+//   ctx.log   前缀 console
+//   ctx.dispose()  卸载:清空挂载点 + 回收订阅/面板 + 广播 client:destroy(pagehide 自动触发)
+// ============================================================
+import { HookBus } from './hooks.mjs'
+
+export const CLIENT_SDK_VERSION = '0.3.0'
+
+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, baseUrl = '', ui, t, getLocale } = {}) {
+  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) => {
+      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),
+      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
+    },
+    /**
+     * UI 注入面(loader 注入;脱离宿主环境时为告警桩):
+     *   ui.registerPanel({ slot, name, title?, titleKey?, order?, mount(el) })
+     *     → 向命名插槽注册面板,返回注销函数;ctx.dispose 自动回收
+     *   ui.slots → 已知插槽名
+     */
+    ui: ui ?? {
+      registerPanel: () => console.warn(`[aw-plugin:${name}] ui 注入面不可用(宿主未提供)`),
+      slots: [],
+    },
+    /** 插件命名空间翻译:ctx.t('settings.title') → plugin.<name>.settings.title */
+    t: t ?? (key => `plugin.${name}.${key}`),
+    /** 当前界面语言(loader 维护;i18n:changed 钩子在切换时广播) */
+    get locale() {
+      return getLocale?.() ?? ''
+    },
+    /** 卸载:回收订阅 + 清空挂载点 + 广播 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) {
+    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
+}
+
+export default { CLIENT_SDK_VERSION, createClientContext, el }

package/sdk/context.mjs

@@ -16,7 +16,7 @@
 //   路径    ctx.paths   { home, configRoot, dataDir }                [SDK]
 // ============================================================
 import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs'
-import { join, resolve } from 'node:path'
+import { isAbsolute, join, relative, resolve, sep } from 'node:path'
 import { HookBus } from './hooks.mjs'
 import { createPlatformClient } from './api.mjs'
 
@@ -115,6 +115,24 @@ export function createPluginContext(opts) {
       all: () => ({ ...config?.effective }),
       /** 运行时覆盖变更订阅(runtime-settings.json 变化;宿主 fs.watch 驱动) */
       onChange: fn => hooks.on('config:changed', fn),
+      /**
+       * 声明式注册「本插件专属的配置分组」——插件调用 API 增加自己的分组。
+       * 分组 id 收敛进本插件命名空间(plugin-<name>[-<suffix>]),不会与别的插件撞车;
+       * 插件卸载/热重载时宿主自动摘除该分组,设置页不残留空分区。
+       * @example ctx.config.defineGroup({ id: 'conn', label: '连接', collapsed: true })
+       */
+      defineGroup: def => opts.registerGroup?.(def),
+      /**
+       * 声明式注册配置字段(等价于 manifest 的 settings[],但可在 setup 里按条件注册)。
+       * 不给 group 时落入本插件默认分组;key 自动编址 plugins.<name>.<key>。
+       * @example ctx.config.defineField({ key: 'token', type: 'string', default: '', group: 'conn' })
+       */
+      defineField: decl => opts.registerField?.(decl),
+      removeGroup: id => opts.removeGroup?.(id),
+      removeField: key => opts.removeField?.(key),
+      /** 本插件当前已注册的分组 / 字段(只读快照) */
+      groups: () => [...(opts.groups?.() ?? [])],
+      fields: () => [...(opts.fields?.() ?? [])],
     },
     paths: { ...paths },
     dataDir: kvDir,
@@ -197,6 +215,18 @@ export function createRouteTable() {
       }
       return out
     },
+    /** 卸下某插件的全部路由(装载失败回滚 / 热重载清理);返回移除条数 */
+    unregisterPlugin(name) {
+      let removed = 0
+      for (const key of [...table.keys()]) {
+        const [, n] = key.split(' ')
+        if (n === name) {
+          table.delete(key)
+          removed += 1
+        }
+      }
+      return removed
+    },
     get size() {
       return table.size
     },
@@ -215,9 +245,139 @@ export function validatePluginModule(mod, source) {
   if (def.client && typeof def.client !== 'string') {
     return { ok: false, error: `插件 client 必须是相对路径字符串: ${def.name}` }
   }
+  if (def.settings !== undefined && !Array.isArray(def.settings)) {
+    return { ok: false, error: `插件 settings 必须是声明数组: ${def.name}` }
+  }
   return { ok: true, def }
 }
 
+/**
+ * 路径包含判定 —— 必须用 relative() 而非 startsWith():
+ * `resolve(p).startsWith(resolve(dir))` 对兄弟同前缀目录(…/foo 与 …/foo-evil)会误判为在内,
+ * 使插件用 `client: '../foo-evil/x.mjs'` 逃逸出自身目录。返回 true 表示 p 确实位于 dir 之内。
+ */
+export function isPathInside(dir, p) {
+  const rel = relative(resolve(dir), resolve(p))
+  if (rel === '') return true
+  if (isAbsolute(rel)) return false
+  return rel !== '..' && !rel.startsWith('..' + sep)
+}
+
+const SETTING_TYPES = new Set(['string', 'number', 'boolean', 'select'])
+
+/** 分组 id 合法性(与 shared/config/groups.mjs 的 ID_RE 同规约) */
+const GROUP_ID_RE = /^[A-Za-z0-9_-]{1,48}$/
+
+/** 插件分组 id 命名空间(与 shared/config/groups.mjs 的 pluginGroupId 同规约) */
+function pluginGroupIdOf(pluginName, suffix) {
+  const ns = String(pluginName).replace(/[^A-Za-z0-9_-]/g, '-')
+  const sub = suffix == null || suffix === '' ? '' : `-${String(suffix).replace(/[^A-Za-z0-9_-]/g, '-')}`
+  return `plugin-${ns}${sub}`.slice(0, 48)
+}
+
+/** 插件声明的 group 名 → 命名空间内 id(default/插件名 → 插件主分组) */
+export function resolvePluginGroupId(pluginName, declaredId) {
+  const raw = String(declaredId ?? '').trim()
+  if (!raw || raw === 'default' || raw === String(pluginName)) return pluginGroupIdOf(pluginName)
+  if (GROUP_ID_RE.test(raw)) return pluginGroupIdOf(pluginName, raw)
+  return pluginGroupIdOf(pluginName)
+}
+
+/**
+ * 校验并规范化「插件配置分组」声明。
+ * 声明:{ id?, label, labelKey?, description?, order?, collapsed?, collapsible?, icon? }
+ * 分组 id 强制收敛进 `plugin-<name>[-<suffix>]` 命名空间。
+ * @returns {{ groups: object[], errors: string[] }}
+ */
+export function validatePluginGroups(pluginName, defs) {
+  const groups = []
+  const errors = []
+  const list = Array.isArray(defs) ? defs : []
+  list.forEach((g, i) => {
+    const tag = `plugin ${pluginName} 分组#${i}`
+    if (!g || typeof g !== 'object') {
+      errors.push(`${tag}: 不是对象`)
+      return
+    }
+    const label = String(g.label ?? g.labelKey ?? '').trim()
+    if (!label) {
+      errors.push(`${tag}: label 缺失`)
+      return
+    }
+    const id = resolvePluginGroupId(pluginName, g.id)
+    const group = {
+      id,
+      label,
+      description: String(g.description ?? ''),
+      order: Number.isFinite(Number(g.order)) ? Number(g.order) : 500,
+      collapsed: g.collapsed === true,
+      collapsible: g.collapsible !== false,
+      icon: g.icon ? String(g.icon) : '',
+      source: 'plugin',
+      plugin: pluginName,
+    }
+    if (g.labelKey) group.labelKey = String(g.labelKey)
+    groups.push(group)
+  })
+  return { groups, errors }
+}
+
+/**
+ * 校验并规范化插件设置声明(宿主装载期调用)。
+ * 声明:{ key, type: 'string'|'number'|'boolean'|'select', default, group?, label?, labelKey?,
+ *         description?, min?, max?, options? }
+ * 规范化为平台设置描述符:key 强制命名空间 `plugins.<plugin>.<key>`(与全局 schema 键
+ * 同一编址,进 SystemConfigService 后即可被前端设置页渲染、PATCH 校验、热生效)。
+ * 分组:group 缺省时落入本插件专属分组 `plugin-<name>` —— 每个插件的配置天然独立成区,
+ * 不与其他插件混在一个「plugins」大分组里。显式给 group 时收敛进本插件命名空间。
+ * 校验失败的条目跳过并返回 errors(宿主告警,不阻断装载)。
+ */
+export function validatePluginSettings(pluginName, defs, { defaultGroup } = {}) {
+  const out = []
+  const errors = []
+  for (const s of (Array.isArray(defs) ? defs : [])) {
+    const tag = `plugins.${pluginName}.${s?.key ?? '?'}`
+    if (!s || typeof s.key !== 'string' || !/^[A-Za-z0-9_-]+$/.test(s.key)) {
+      errors.push(`${tag}: key 缺失或含非法字符(仅字母数字_-)`)
+      continue
+    }
+    if (!SETTING_TYPES.has(s.type)) {
+      errors.push(`${tag}: type 必须是 ${[...SETTING_TYPES].join('/')}`)
+      continue
+    }
+    if (s.default === undefined) {
+      errors.push(`${tag}: 缺少 default(插件设置必须声明默认值)`)
+      continue
+    }
+    if (s.type === 'select') {
+      if (!Array.isArray(s.options) || s.options.length === 0 || !s.options.map(String).includes(String(s.default))) {
+        errors.push(`${tag}: select 必须给 options 数组且 default 在其中`)
+        continue
+      }
+    }
+    const desc = {
+      key: `plugins.${pluginName}.${s.key}`,
+      group: s.group ? resolvePluginGroupId(pluginName, s.group) : (defaultGroup ?? pluginGroupIdOf(pluginName)),
+      type: s.type,
+      label: String(s.label ?? s.key),
+      description: String(s.description ?? ''),
+      applies: 'live',
+      default: s.default,
+      plugin: pluginName,
+    }
+    if (s.labelKey) desc.labelKey = String(s.labelKey)
+    if (s.type === 'number') {
+      if (s.min !== undefined) desc.min = Number(s.min)
+      if (s.max !== undefined) desc.max = Number(s.max)
+      desc.default = Number(s.default)
+    }
+    if (s.type === 'boolean') desc.default = s.default === true
+    if (s.type === 'select') desc.options = s.options.map(o => String(o))
+    out.push(desc)
+  }
+  return { descriptors: out, errors }
+}
+
 /** 便捷:SDK 侧 definePlugin(纯类型糖;宿主同样接受裸对象) */
 export function definePlugin(def) {
   const check = validatePluginModule({ default: def }, def?.name ?? '(anonymous)')

package/sdk/index.d.mts

@@ -1,5 +1,6 @@
 // AgentWorkShop SDK 类型声明(agentworkshop/sdk)
-import type { HookBus } from './hooks.mjs'
+// 注意:此处的 HookBus 为本文件内联声明(对应运行时 sdk/hooks.mjs),
+// 不存在 sdk/hooks.d.mts,故不得 import type from './hooks.mjs'(悬空引用)。
 
 export declare const SDK_VERSION: string
 
@@ -57,7 +58,8 @@ export interface PlatformClient {
 
 export interface PluginContext {
   name: string
-  scope: 'project' | 'user'
+  /** 插件来源作用域(host.mjs discoverPluginDirs:builtin / project / user) */
+  scope: 'builtin' | 'project' | 'user'
   dir: string
   sdkVersion: string
   hooks: HookBus
@@ -119,11 +121,28 @@ 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 LIFECYCLE_EVENTS: readonly ['plugin:host:init', 'config:changed', 'permissions:changed', 'event:*', 'daq:sample', 'daq:frame', 'dcw:write', 'line:start', 'line:stop', 'server:close']
 export declare const CLIENT_EVENTS: readonly ['client:init', 'event:*', 'page:change', 'client:destroy']
 
-/** 客户端插件上下文(sdk/client.mjs) */
+/** 客户端插件上下文(sdk/client.mjs);完整声明见 agentworkshop/sdk/client */
 export declare const CLIENT_SDK_VERSION: string
+
+/** ctx.ui.registerPanel 入参(命名插槽 -> 宿主容器挂载) */
+export interface ClientPanelEntry {
+  slot: string
+  name: string
+  title?: string
+  titleKey?: string
+  order?: number
+  mount(el: HTMLElement): void
+}
+
+/** ctx.ui:UI 注入面(宿主未提供时为告警桩) */
+export interface ClientUi {
+  registerPanel(entry: ClientPanelEntry): () => void
+  readonly slots: readonly string[]
+}
+
 export interface ClientContext {
   name: string
   sdkVersion: string
@@ -133,10 +152,23 @@ export interface ClientContext {
   el(tag: string, attrs?: Record<string, unknown>, children?: Array<Node | string>): HTMLElement
   mount(target: string | Element, node: Node): Node
   root(): HTMLElement
+  /** UI 注入面:registerPanel / slots */
+  ui: ClientUi
+  /** 插件命名空间翻译:ctx.t('settings.title') -> plugin.<name>.settings.title */
+  t(key: string, params?: Record<string, unknown>): string
+  /** 当前界面语言(i18n:changed 钩子在切换时广播;未注入时 '') */
+  readonly locale: string
   log: PluginLogger
   dispose(): void
 }
-export declare function createClientContext(opts: { name: string, eventBridge?: (fn: (type: string, payload: any) => void) => (() => void), baseUrl?: string }): ClientContext
+export declare function createClientContext(opts?: {
+  name: string
+  eventBridge?: (fn: (type: string, payload: any) => void) => (() => void)
+  baseUrl?: string
+  ui?: ClientUi
+  t?: (key: string, params?: Record<string, unknown>) => string
+  getLocale?: () => string
+}): ClientContext
 
 declare const _default: Record<string, unknown>
 export default _default