agentworkshop 0.7.49 → 0.7.51

package/scripts/start.mjs

@@ -11,7 +11,7 @@ import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { resolveRunMode } from '../shared/config/home.mjs'
-import { installLocalIso } from '../shared/local-time.mjs'
+import { setConfiguredTimeZone, installLocalIso, DEFAULT_TIME_ZONE } from '../shared/local-time.mjs'
 
 // 生产进程时间输出统一本地时区(先于 .env 预载与 worker 启动)
 installLocalIso()
@@ -59,6 +59,8 @@ const eff = loadEffective({
   env: { ...process.env, ...(argPort ? { PORT: argPort } : {}) },
   mode: 'prod',
 })
+setConfiguredTimeZone(String(eff.effective['time.timeZone'] ?? DEFAULT_TIME_ZONE))
+installLocalIso()
 
 const host = eff.effective['server.host'] ?? '0.0.0.0'
 const prodPort = eff.effective['server.prod.port'] ?? 3000

package/scripts/test-aw-skills.mjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+/**
+ * scripts/test-aw-skills.mjs —— skills/ 目录 skill 设计规范校验。
+ *
+ * 校验面(符合 agent skill 通用规范 + 本项目约定):
+ *   1. 结构:SKILL.md 存在、frontmatter(name/description)完整
+ *   2. 命名:目录名 = frontmatter name,kebab-case
+ *   3. 描述:第三人称可用性描述,长度 20~1024
+ *   4. 正文:有分节(## ),无 TODO/FIXME/TBD 占位
+ *   5. 工具引用:正文引用的 aw_* 工具必须真实存在于 mcp/aw-mcp-server.mjs 工具面
+ *   6. 文件引用:正文提到的仓库文件(docs/sdk/scripts/插件样例)必须真实存在
+ *
+ * 用法:node scripts/test-aw-skills.mjs   (FAIL 则退出码 1)
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+const REPO = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const SKILLS_DIR = join(REPO, 'skills')
+
+let pass = 0
+const fails = []
+const ok = (name, cond, detail = '') => {
+  if (cond) pass++
+  else fails.push(`${name}${detail ? ` — ${detail}` : ''}`)
+}
+
+function parseFrontmatter(text) {
+  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/)
+  if (!m) return null
+  const meta = {}
+  for (const line of m[1].split(/\r?\n/)) {
+    const kv = line.match(/^([a-zA-Z_-]+):\s*(.*)$/)
+    if (kv) meta[kv[1]] = kv[2].trim().replace(/^['"]|['"]$/g, '')
+  }
+  return { meta, body: text.slice(m[0].length) }
+}
+
+// ── 收集 skill ──
+ok('skills/ 目录存在', existsSync(SKILLS_DIR), SKILLS_DIR)
+if (!existsSync(SKILLS_DIR)) {
+  console.error(`✖ ${SKILLS_DIR} 不存在`)
+  process.exit(1)
+}
+const dirs = readdirSync(SKILLS_DIR).filter(d => statSync(join(SKILLS_DIR, d)).isDirectory())
+ok('skill 数量 ≥ 3', dirs.length >= 3, `实际 ${dirs.length}`)
+
+// ── 工具面对照表(从 MCP server 导入真实注册表)──
+const { buildToolDefs } = await import(pathToFileURL(join(REPO, 'mcp', 'aw-mcp-server.mjs')).href)
+const toolNames = new Set(buildToolDefs().map(t => t.name))
+
+for (const dir of dirs) {
+  const label = `skills/${dir}`
+  const file = join(SKILLS_DIR, dir, 'SKILL.md')
+  ok(`${label}: SKILL.md 存在`, existsSync(file))
+  if (!existsSync(file)) continue
+  const text = readFileSync(file, 'utf8')
+
+  const parsed = parseFrontmatter(text)
+  ok(`${label}: frontmatter 存在`, parsed != null)
+  if (!parsed) continue
+  const { meta, body } = parsed
+
+  ok(`${label}: name = 目录名`, meta.name === dir, `frontmatter=${meta.name}`)
+  ok(`${label}: name kebab-case`, /^[a-z0-9]+(-[a-z0-9]+)*$/.test(meta.name ?? ''), meta.name)
+  ok(`${label}: description 存在`, Boolean(meta.description))
+  ok(`${label}: description 长度 20~1024`, (meta.description ?? '').length >= 20 && (meta.description ?? '').length <= 1024, `len=${(meta.description ?? '').length}`)
+  ok(`${label}: description 含使用时机(当/when/需要)`, /当|需要|when|use/i.test(meta.description ?? ''))
+
+  ok(`${label}: 正文 ≥2 个 ## 分节`, (body.match(/^## /gm) ?? []).length >= 2)
+  ok(`${label}: 无 TODO/FIXME/TBD 占位`, !/\b(TODO|FIXME|TBD)\b/.test(body))
+
+  // 工具引用真实性
+  const referencedTools = [...new Set(body.match(/\baw_[a-z_]+\b/g) ?? [])]
+  ok(`${label}: 至少引用 3 个 MCP 工具`, referencedTools.length >= 3, `引用 ${referencedTools.length} 个`)
+  const ghost = referencedTools.filter(t => !toolNames.has(t))
+  ok(`${label}: 引用工具全部存在于 MCP 工具面`, ghost.length === 0, `幽灵工具: ${ghost.join(', ')}`)
+
+  // ── 设计质量 rubric(agent 可执行性)──
+  ok(`${label}: 编号步骤(### N.)≥4`, (body.match(/^### \d+\./gm) ?? []).length >= 4, `实际 ${(body.match(/^### \d+\./gm) ?? []).length}`)
+  ok(`${label}: 含验收清单/验证段`, /验收清单|## 验证|硬性|回环验收/i.test(body))
+  ok(`${label}: 含治理红线`, /红线|禁止|不要|绝不|fail-closed/i.test(body))
+  ok(`${label}: 含 MCP 开关前置(系统设置/AW_MCP_ENABLED)`, /系统设置 → MCP 集成|AW_MCP_ENABLED|mcpEnabled/.test(body))
+  ok(`${label}: 步骤含失败处置指引(400/被拒/超时语义)`, /400|被拒|超时|被拒/i.test(body))
+  // 工业操作类 skill(节点/闭环)工具面覆盖要求更高;插件开发以 CLI+文件编辑为主,阈值 3
+  const opHeavy = /节点|优化|Channel/.test(meta.description ?? '')
+  ok(`${label}: 工具引用丰富(${opHeavy ? '≥6' : '≥3'})`, referencedTools.length >= (opHeavy ? 6 : 3), `引用 ${referencedTools.length} 个`)
+  ok(`${label}: 行数 ≤ 220(规范:正文精炼)`, body.split(/\r?\n/).length <= 220, `${body.split(/\r?\n/).length} 行`)
+
+  // 仓库文件引用真实性(`docs/...` `sdk/...` `scripts/...` 反引号路径)
+  const refMatches = [...body.matchAll(/`((?:docs|sdk|scripts|tests|server|\.AgentWorkShop)\/[^`\s]+)`/g)].map(m => m[1])
+  for (const ref of [...new Set(refMatches)]) {
+    ok(`${label}: 引用文件存在 ${ref}`, existsSync(join(REPO, ref)))
+  }
+}
+
+console.log('')
+console.log(`═══ skill 规范校验:${pass} PASS / ${fails.length} FAIL(skills: ${dirs.join(', ')}) ═══`)
+for (const f of fails) console.log(`  ✖ ${f}`)
+console.log('')
+process.exit(fails.length ? 1 : 0)

package/scripts/test-twin-plugin-sdk.mjs

@@ -0,0 +1,30 @@
+/* eslint-disable @stylistic/max-statements-per-line */
+import assert from 'node:assert/strict'
+import { createPluginContext, TWIN_BRIDGE_KEY } from '../sdk/context.mjs'
+import { HookBus } from '../sdk/hooks.mjs'
+
+const registrations = []
+globalThis[TWIN_BRIDGE_KEY] = {
+  pending: [],
+  register(kind, payload, source) { registrations.push({ kind, payload, source }); return { ok: true } },
+  listProviders() { return [] },
+  getProviderHealth() { return { status: 'healthy' } },
+  resolveProvider() { return null },
+  validateProvider() { return { valid: true, errors: [], warnings: [] } },
+  retireProvider() { return { ok: true } },
+}
+const disposables = []
+const ctx = createPluginContext({
+  name: 'sdk-twin-test', scope: 'project', dir: process.cwd(), hooks: new HookBus(),
+  config: null, paths: { home: process.cwd(), configRoot: process.cwd(), dataDir: process.cwd() },
+  emitter: { registerRoute: () => true }, selfOrigin: 'http://127.0.0.1:3000',
+  onDispose: (fn) => { disposables.push(fn); return fn },
+})
+ctx.twin.registerPhysicsProvider({ manifest: { providerId: 'test-provider', version: '1.0.0' } })
+ctx.twin.registerScenePack({ scenePackId: 'test-scene', version: '1.0.0' })
+assert.equal(registrations.length, 2)
+assert.equal(registrations[0].kind, 'registerPhysicsProvider')
+assert.equal(registrations[1].kind, 'registerScenePack')
+assert.equal(ctx.twin.isRegistryAvailable(), true)
+for (const dispose of disposables) dispose()
+console.log('Twin SDK bridge: 5 passed / 0 failed')

package/sdk/context.mjs

@@ -1,3 +1,4 @@
+/* eslint-disable @stylistic/max-statements-per-line */
 // ============================================================
 // AgentWorkShop SDK — 服务端插件上下文工厂（宿主调用;插件经 setup(ctx) 获得）
 // ------------------------------------------------------------
@@ -15,6 +16,7 @@
 //   平台    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.twin   Twin Provider Registry 桥(注册/查询/健康)      [SDK]
 //   路径    ctx.paths   { home, configRoot, dataDir }                [SDK]
 // ============================================================
 import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs'
@@ -24,6 +26,236 @@ import { createPlatformClient } from './api.mjs'
 
 export const SDK_VERSION = '0.3.0'
 
+/**
+ * Twin Registry 的全局桥名称。
+ *
+ * 与 daq/dcw/omp 插件桥一样,SDK 先创建一个只负责排队的桥;服务端
+ * Registry 随后接管同一个对象并 drain pending entries。保留两个历史候选
+ * 名称的读取兼容,方便 Registry 模块先于插件宿主加载。
+ */
+export const TWIN_BRIDGE_KEY = '__twinPluginExt'
+const TWIN_BRIDGE_KEYS = Object.freeze([
+  TWIN_BRIDGE_KEY,
+  '__awTwinRegistryBridge',
+  '__twinRegistryBridge',
+])
+
+const TWIN_REGISTRATION_KINDS = new Set([
+  'registerPhysicsProvider',
+  'registerScenePack',
+  'registerObjectiveProfile',
+  'registerTrainingAdapter',
+  'registerSolverAdapter',
+])
+
+/**
+ * 查询面没有 Registry 时抛出的可识别错误。
+ * 注册面不会因为 Registry 尚未加载而抛错,而是进入全局桥 pending 队列。
+ */
+export class TwinRegistryUnavailableError extends Error {
+  constructor(operation = 'operation') {
+    super(`[sdk] Twin Registry unavailable for ${operation}; registration calls are queued until the server bridge attaches`)
+    this.name = 'TwinRegistryUnavailableError'
+    this.code = 'TWIN_REGISTRY_UNAVAILABLE'
+    this.operation = operation
+  }
+}
+
+function isTwinRegistryUnavailable(err) {
+  return err?.code === 'TWIN_REGISTRY_UNAVAILABLE' || err?.name === 'TwinRegistryUnavailableError'
+}
+
+function twinRegistrationReceipt(kind, source) {
+  return {
+    status: 'queued',
+    queued: true,
+    kind,
+    plugin: source?.plugin ?? source?.name ?? '',
+    source,
+  }
+}
+
+/**
+ * 调用 Registry 实例上的注册方法。
+ * Registry 既可以暴露与 SDK 同名的方法,也可以只暴露统一 register(kind,...)
+ * 方法;两种形态都由桥接层承认,避免 SDK 绑定 Registry 的内部类名。
+ */
+function dispatchTwinRegistration(target, kind, payload, source) {
+  if (!target || target === globalThis) throw new TwinRegistryUnavailableError(kind)
+  const explicit = target[kind]
+  if (typeof explicit === 'function') return explicit.call(target, payload, source)
+  if (typeof target.register === 'function') return target.register(kind, payload, source)
+  if (typeof target.registerEntry === 'function') return target.registerEntry({ kind, payload, source })
+  throw new TwinRegistryUnavailableError(kind)
+}
+
+/**
+ * 桥的默认实现。它本身不实现 Registry 语义,只提供：
+ *   - pending: 插件宿主早于服务端 Registry 时的注册队列;
+ *   - drain(onEntry): Registry 接管时回放,之后注册即时转发;
+ *   - attach(registry): 便捷接管方法(服务端也可以直接改写桥方法);
+ *   - call(method,...args): 查询面统一调用口。
+ *
+ * 这段实现故意放在 SDK 而不是 plugin host 中,这样旧插件无需 host 版本升级
+ * 就能安全地获得 ctx.twin;没有 Registry 时也不会影响插件 setup 成功。
+ */
+function createTwinRegistryBridge() {
+  const bridge = {
+    pending: [],
+    registry: null,
+    _drain: null,
+
+    register(kind, payload, source) {
+      if (!TWIN_REGISTRATION_KINDS.has(String(kind))) {
+        throw new Error(`[sdk] unknown Twin registration kind: ${String(kind)}`)
+      }
+      if (this.registry) return dispatchTwinRegistration(this.registry, kind, payload, source)
+      this.pending.push({ kind, payload, source })
+      this._drain?.()
+      return twinRegistrationReceipt(kind, source)
+    },
+
+    registerEntry(entry) {
+      return this.register(entry?.kind, entry?.payload, entry?.source)
+    },
+
+    /** Registry 调用此方法接管桥;加载顺序与插件宿主无关。 */
+    drain(onEntry) {
+      if (typeof onEntry !== 'function') throw new TypeError('[sdk] Twin bridge drain requires a function')
+      this._drain = () => {
+        const entries = this.pending.splice(0)
+        for (const entry of entries) onEntry(entry)
+      }
+      this._drain()
+    },
+
+    /** 便捷接管 API;等价于 registry 模块自行设置 drain + 查询方法。 */
+    attach(registry) {
+      if (!registry || (typeof registry !== 'object' && typeof registry !== 'function')) {
+        throw new TypeError('[sdk] Twin bridge attach requires a Registry object')
+      }
+      this.registry = registry
+      this.drain(entry => dispatchTwinRegistration(registry, entry.kind, entry.payload, entry.source))
+      return this
+    },
+
+    bind(registry) {
+      return this.attach(registry)
+    },
+
+    call(method, ...args) {
+      if (this.registry && typeof this.registry[method] === 'function') {
+        return this.registry[method](...args)
+      }
+      throw new TwinRegistryUnavailableError(method)
+    },
+
+    invoke(method, ...args) {
+      return this.call(method, ...args)
+    },
+
+    /** 未接管前清理某个插件遗留在队列中的注册,避免热重载产生幽灵项。 */
+    unregisterPlugin(sourceOrName) {
+      const plugin = typeof sourceOrName === 'string'
+        ? sourceOrName
+        : sourceOrName?.plugin ?? sourceOrName?.pluginName ?? sourceOrName?.name
+      if (!plugin) return 0
+      if (this.registry) {
+        const remove = this.registry.unregisterPlugin ?? this.registry.removePlugin
+        if (typeof remove === 'function') return remove.call(this.registry, sourceOrName)
+      }
+      let removed = 0
+      this.pending = this.pending.filter((entry) => {
+        const owner = entry?.source?.plugin ?? entry?.source?.pluginName ?? entry?.source?.name
+        if (owner === plugin) {
+          removed += 1
+          return false
+        }
+        return true
+      })
+      return removed
+    },
+  }
+  return bridge
+}
+
+/**
+ * 取得全局 Twin 桥。允许 Registry 模块先行放置自己的桥,也允许 SDK 先建
+ * 默认排队桥;不要在这里 import 服务端 Registry,否则插件 SDK 会产生循环依赖。
+ */
+export function getTwinRegistryBridge(preferred) {
+  if (preferred && (typeof preferred === 'object' || typeof preferred === 'function')) return preferred
+
+  const g = globalThis
+  for (const key of TWIN_BRIDGE_KEYS) {
+    const existing = g[key]
+    if (!existing || (typeof existing !== 'object' && typeof existing !== 'function')) continue
+    // 统一暴露 canonical key,但不覆盖 Registry 已放置的对象。
+    if (!g[TWIN_BRIDGE_KEY]) {
+      try { g[TWIN_BRIDGE_KEY] = existing }
+      catch { /* non-writable global is still usable through its original alias */ }
+    }
+    return existing
+  }
+
+  const bridge = createTwinRegistryBridge()
+  try { g[TWIN_BRIDGE_KEY] = bridge }
+  catch { /* 极端沙箱下 globalThis 只读;调用方仍会拿到本地桥对象 */ }
+  return bridge
+}
+
+function enqueueTwinRegistration(bridge, kind, payload, source) {
+  const entry = { kind, payload, source }
+  if (typeof bridge?.enqueue === 'function') {
+    return bridge.enqueue(kind, payload, source)
+  }
+  if (typeof bridge?.queue === 'function') {
+    return bridge.queue(kind, payload, source)
+  }
+  if (Array.isArray(bridge?.pending)) {
+    bridge.pending.push(entry)
+    bridge._drain?.()
+    return twinRegistrationReceipt(kind, source)
+  }
+  throw new TwinRegistryUnavailableError(kind)
+}
+
+function invokeTwinRegistration(bridge, kind, payload, source) {
+  if (typeof bridge?.[kind] === 'function') return bridge[kind](payload, source)
+  if (typeof bridge?.register === 'function') return bridge.register(kind, payload, source)
+  if (typeof bridge?.registerEntry === 'function') return bridge.registerEntry({ kind, payload, source })
+  return enqueueTwinRegistration(bridge, kind, payload, source)
+}
+
+/** 查询面兼容 direct method / call / invoke / dispatch / registry 五种桥接形态。 */
+function invokeTwinQuery(bridge, method, args) {
+  if (typeof bridge?.[method] === 'function') return bridge[method](...args)
+  if (typeof bridge?.call === 'function') return bridge.call(method, ...args)
+  if (typeof bridge?.invoke === 'function') return bridge.invoke(method, ...args)
+  if (typeof bridge?.dispatch === 'function') return bridge.dispatch(method, ...args)
+  if (bridge?.registry && typeof bridge.registry[method] === 'function') {
+    return bridge.registry[method](...args)
+  }
+  throw new TwinRegistryUnavailableError(method)
+}
+
+function maybeQueueAfterUnavailable(bridge, kind, payload, source, invoke) {
+  try {
+    const result = invoke()
+    if (result && typeof result.then === 'function') {
+      return result.catch((err) => {
+        if (!isTwinRegistryUnavailable(err)) throw err
+        return enqueueTwinRegistration(bridge, kind, payload, source)
+      })
+    }
+    return result
+  }
+  catch (err) {
+    if (!isTwinRegistryUnavailable(err)) throw err
+    return enqueueTwinRegistration(bridge, kind, payload, source)
+  }
+}
+
 /** 允许的对外请求协议守卫(拒绝 file:/data: 等;宿主/插件同守此规则) */
 function safeUrl(raw, timeoutMs = 8000) {
   const u = new URL(String(raw))
@@ -62,6 +294,78 @@ export function createPluginContext(opts) {
     return fn
   }
 
+  // ---- Twin Registry 桥 -------------------------------------------------
+  // 这里只保存插件身份,不 import 服务端 Registry。插件宿主与 Registry 的
+  // 加载顺序可以任意:SDK 先到则注册入队,Registry 先到则直接转发。
+  const twinBridge = getTwinRegistryBridge(opts.twinBridge)
+  const twinSource = {
+    plugin: String(name),
+    pluginName: String(name),
+    name: String(name),
+    scope,
+    dir: resolve(dir),
+    version: opts.pluginVersion ?? opts.version,
+    sdkVersion: SDK_VERSION,
+  }
+  let twinCleanupRegistered = false
+  const registerTwin = (kind, payload) => {
+    if (!twinCleanupRegistered) {
+      twinCleanupRegistered = true
+      onDispose(() => {
+        try {
+          if (typeof twinBridge.unregisterPlugin === 'function') {
+            twinBridge.unregisterPlugin(twinSource)
+          }
+          else if (typeof twinBridge.removePlugin === 'function') {
+            twinBridge.removePlugin(twinSource)
+          }
+          else if (Array.isArray(twinBridge.pending)) {
+            // 外部 Registry 若只实现 drain 而没有卸载 API,至少清除尚未
+            // 回放的当前插件项;已接管的项由 Registry 自己负责生命周期。
+            const plugin = twinSource.plugin
+            twinBridge.pending = twinBridge.pending.filter((entry) => {
+              const owner = entry?.source?.plugin ?? entry?.source?.pluginName ?? entry?.source?.name
+              return owner !== plugin
+            })
+          }
+        }
+        catch (err) {
+          logger.warn(`[${name}] Twin Registry 清理失败:`, err?.message ?? err)
+        }
+      })
+    }
+    return maybeQueueAfterUnavailable(
+      twinBridge,
+      kind,
+      payload,
+      twinSource,
+      () => invokeTwinRegistration(twinBridge, kind, payload, twinSource),
+    )
+  }
+  const twin = {
+    registerPhysicsProvider: provider => registerTwin('registerPhysicsProvider', provider),
+    registerScenePack: pack => registerTwin('registerScenePack', pack),
+    registerObjectiveProfile: profile => registerTwin('registerObjectiveProfile', profile),
+    registerTrainingAdapter: adapter => registerTwin('registerTrainingAdapter', adapter),
+    registerSolverAdapter: adapter => registerTwin('registerSolverAdapter', adapter),
+    listProviders: filter => invokeTwinQuery(twinBridge, 'listProviders', [filter]),
+    getProviderHealth: (providerId, version) => invokeTwinQuery(twinBridge, 'getProviderHealth', [providerId, version]),
+    resolveProvider: (providerId, version) => invokeTwinQuery(twinBridge, 'resolveProvider', [providerId, version]),
+    validateProvider: (providerId, version) => invokeTwinQuery(twinBridge, 'validateProvider', [providerId, version]),
+    retireProvider: (providerId, version) => invokeTwinQuery(twinBridge, 'retireProvider', [providerId, version]),
+    /** 只读诊断信息,便于插件决定是否把可选功能降级。 */
+    isRegistryAvailable: () => {
+      try {
+        invokeTwinQuery(twinBridge, 'listProviders', [])
+        return true
+      }
+      catch (err) {
+        if (isTwinRegistryUnavailable(err)) return false
+        throw err
+      }
+    },
+  }
+
   // ---- 定时器:自动登记回收,杜绝插件定时器泄漏 ----
   const timer = {
     setInterval: (fn, ms, ...rest) => {
@@ -202,6 +506,7 @@ export function createPluginContext(opts) {
       on: (type, fn) => hooks.on(type === '*' ? '*' : `event:${type}`, fn),
       off: (type, fn) => hooks.off(type === '*' ? '*' : `event:${type}`, fn),
     },
+    twin,
   }
   return ctx
 }

package/sdk/index.d.mts

@@ -3,6 +3,16 @@
 // 不存在 sdk/hooks.d.mts,故不得 import type from './hooks.mjs'(悬空引用)。
 
 export declare const SDK_VERSION: string
+/** Twin SDK 的 canonical global bridge key(服务端 Registry 与插件宿主共享)。 */
+export declare const TWIN_BRIDGE_KEY: '__twinPluginExt'
+
+/** ctx.twin 查询面不可用时的可识别错误;注册面会先进入 pending 队列。 */
+export declare class TwinRegistryUnavailableError extends Error {
+  readonly name: 'TwinRegistryUnavailableError'
+  readonly code: 'TWIN_REGISTRY_UNAVAILABLE'
+  readonly operation: string
+  constructor(operation?: string)
+}
 
 /** 生命周期钩子总线:异步串行、错误隔离、'*' 通配、连续失败自动熔断 */
 export declare class HookBus {
@@ -146,6 +156,143 @@ export interface PluginHostExtensions {
   }
 }
 
+/** Twin Registry 全局桥使用的注册类别(注册在 Registry 未加载时会排队)。 */
+export type TwinRegistrationKind
+  = | 'registerPhysicsProvider'
+    | 'registerScenePack'
+    | 'registerObjectiveProfile'
+    | 'registerTrainingAdapter'
+    | 'registerSolverAdapter'
+
+/** SDK 自动附带的插件来源信息,服务端 Registry 用于 lineage / hot-reload 清理。 */
+export interface TwinRegistrationSource {
+  plugin: string
+  pluginName?: string
+  /** 与 plugin 相同的兼容别名(旧桥实现可能读取 name) */
+  name?: string
+  scope?: 'builtin' | 'project' | 'user' | string
+  dir?: string
+  version?: string
+  sdkVersion?: string
+  [key: string]: unknown
+}
+
+/** 注册项在 Registry 尚未接管时的 pending 形态。 */
+export interface TwinPendingRegistration {
+  kind: TwinRegistrationKind
+  payload: unknown
+  source: TwinRegistrationSource
+}
+
+/** 注册未立即交给 Registry 时返回的确认对象。 */
+export interface TwinRegistrationReceipt {
+  status: 'queued'
+  queued: true
+  kind: TwinRegistrationKind
+  plugin: string
+  source: TwinRegistrationSource
+}
+
+/** Provider 查询过滤条件由服务端 Registry 解释,SDK 保持向前兼容。 */
+export interface TwinProviderFilter {
+  providerId?: string
+  version?: string
+  sceneKind?: string
+  scenePackId?: string
+  status?: string
+  capability?: string
+  [key: string]: unknown
+}
+
+/** Provider 健康结果由服务端返回;保留扩展字段以兼容后续 health contract。 */
+export interface TwinProviderHealth {
+  providerId?: string
+  version?: string
+  status?: string
+  healthy?: boolean
+  [key: string]: unknown
+}
+
+/**
+ * SDK 不冻结 Provider/Scene/Objective 的业务字段,只给常见能力提供可选提示。
+ * 详细 contract 由服务端 Registry 校验,这样旧插件和未来 schema 可以共存。
+ */
+export interface TwinPhysicsProvider {
+  manifest?: (...args: any[]) => any
+  validateScene?: (...args: any[]) => any
+  initialize?: (...args: any[]) => any
+  step?: (...args: any[]) => any
+  simulate?: (...args: any[]) => any
+  calibrate?: (...args: any[]) => any
+  health?: (...args: any[]) => any
+  [key: string]: unknown
+}
+
+export interface TwinScenePack {
+  sceneKind?: string
+  sceneSchemaVersion?: string
+  discover?: (...args: any[]) => any
+  compile?: (...args: any[]) => any
+  [key: string]: unknown
+}
+
+export interface TwinObjectiveProfile {
+  id?: string
+  version?: string
+  [key: string]: unknown
+}
+
+export interface TwinSolverAdapter {
+  id?: string
+  version?: string
+  inputSchema?: unknown
+  outputSchema?: unknown
+  run?: (...args: any[]) => any
+  cancel?: (...args: any[]) => any
+  health?: (...args: any[]) => any
+  [key: string]: unknown
+}
+
+/** Registry 调用可能是同步或异步;具体结果由服务端 contract 决定。 */
+export type TwinRegistryResult<T = any> = T | Promise<T>
+
+/**
+ * 全局桥契约(服务端 Registry 可直接实现,也可只实现其中的兼容形态)。
+ * 插件作者通常不需要直接使用它;该接口主要用于 Registry / 集成测试。
+ */
+export interface TwinRegistryBridge {
+  pending?: TwinPendingRegistration[]
+  register?(kind: TwinRegistrationKind, payload: unknown, source: TwinRegistrationSource): TwinRegistryResult<any>
+  registerEntry?(entry: TwinPendingRegistration): TwinRegistryResult<any>
+  enqueue?(kind: TwinRegistrationKind, payload: unknown, source: TwinRegistrationSource): TwinRegistryResult<any>
+  queue?(kind: TwinRegistrationKind, payload: unknown, source: TwinRegistrationSource): TwinRegistryResult<any>
+  drain?(onEntry: (entry: TwinPendingRegistration) => any): void
+  attach?(registry: unknown): TwinRegistryBridge
+  bind?(registry: unknown): TwinRegistryBridge
+  call?(method: string, ...args: any[]): TwinRegistryResult<any>
+  invoke?(method: string, ...args: any[]): TwinRegistryResult<any>
+  dispatch?(method: string, ...args: any[]): TwinRegistryResult<any>
+  registry?: Record<string, any> | null
+  unregisterPlugin?(source: TwinRegistrationSource | string): number | undefined
+  removePlugin?(source: TwinRegistrationSource | string): number | undefined
+  [key: string]: any
+}
+
+/** ctx.twin:插件向服务端 Twin Provider Registry 暴露的稳定 SDK 面。 */
+export interface TwinPluginApi {
+  registerPhysicsProvider(provider: TwinPhysicsProvider | unknown): TwinRegistryResult<any>
+  registerScenePack(pack: TwinScenePack | unknown): TwinRegistryResult<any>
+  registerObjectiveProfile(profile: TwinObjectiveProfile | unknown): TwinRegistryResult<any>
+  registerTrainingAdapter(adapter: unknown): TwinRegistryResult<any>
+  registerSolverAdapter(adapter: TwinSolverAdapter | unknown): TwinRegistryResult<any>
+  listProviders(filter?: TwinProviderFilter): TwinRegistryResult<any[]>
+  getProviderHealth(providerId: string, version?: string): TwinRegistryResult<TwinProviderHealth | any>
+  resolveProvider(providerId: string, version?: string): TwinRegistryResult<any>
+  validateProvider(providerId: string, version?: string): TwinRegistryResult<any>
+  retireProvider(providerId: string, version?: string): TwinRegistryResult<any>
+  isRegistryAvailable(): boolean
+}
+
 export interface PluginContext extends PluginHostExtensions {
   name: string
   /** 插件来源作用域(host.mjs discoverPluginDirs:builtin / project / user) */
@@ -188,6 +335,7 @@ export interface PluginContext extends PluginHostExtensions {
   api: PlatformClient
   http: PluginHttp
   events: { on(type: string, fn: (payload: any) => any): () => void, off(type: string, fn: (payload: any) => any): void }
+  twin: TwinPluginApi
 }
 
 export interface PluginRouteDef {
@@ -216,6 +364,7 @@ export interface PluginDef {
 export declare function definePlugin(def: PluginDef): PluginDef
 
 export declare function createPluginContext(opts: Record<string, any>): PluginContext
+export declare function getTwinRegistryBridge(preferred?: unknown): TwinRegistryBridge
 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