@capyclaw/foundation 0.0.0-stage → 0.1.0

package/abi/spec.mjs

@@ -0,0 +1,198 @@
+/**
+ * 插件描述符：应用插件唯一需要写的东西。
+ *
+ *   import { createPlugin, skillProvider } from '@capyclaw/foundation/abi'
+ *
+ *   export const { name, inject, apply } = createPlugin({
+ *     name: 'canvas',
+ *     requires: ['canvas.runtime@^1'],
+ *     implements: [skillProvider({ skill: './skills/canvas' })],
+ *   }, import.meta.url)
+ *
+ * 设计要点：
+ * - 构建器在模块加载期就校验 schema，坏描述符不会活到 activate；
+ * - 描述符是纯数据 + 函数，不 import 内核、不持有 ctx；
+ * - createPlugin 产出的是普通 Cordis 插件形状（name/inject/apply），
+ *   装配细节全部收回内核的 mount。
+ */
+import { ABI_MAJOR, getInterfaceKind } from './kinds.mjs'
+import { validateSchema } from './schema.mjs'
+import { validateInterface } from './validate.mjs'
+import { AbiError, ERROR_CODES, toAbiError } from './errors.mjs'
+
+const PLUGIN_NAME_RE = /^[a-z0-9][a-z0-9-]*$/
+const CAPABILITY_NAME_RE = /^[a-zA-Z][a-zA-Z0-9]*(?:[.-][a-zA-Z0-9*]+)*$/
+const RANGE_RE = /^(?:\^|~|>=|<=|>|<|=)?[0-9x*][0-9A-Za-z.*-]*$/
+
+const KINDS = Object.freeze({
+  'skill-provider': 'skill-provider@1',
+  'tool-provider': 'tool-provider@1',
+  'runtime-driver': 'runtime-driver@1',
+  'http-router': 'http-router@1',
+  'ui-panel': 'ui-panel@1',
+  'lifecycle-hook': 'lifecycle-hook@1',
+  raw: 'raw@1',
+})
+
+/**
+ * 校验并冻结一个接口描述符。
+ * @param {string} kind
+ * @param {object} options
+ */
+export function defineInterface(kind, options) {
+  const definition = getInterfaceKind(kind)
+  if (!definition) {
+    throw new AbiError(ERROR_CODES.E_KIND_UNKNOWN, `未知接口种类 ${kind}`, {
+      kind,
+      known: Object.keys(KINDS).map((key) => KINDS[key]),
+    })
+  }
+  if (options === null || typeof options !== 'object' || Array.isArray(options)) {
+    throw new AbiError(ERROR_CODES.E_SCHEMA, `${kind} 的描述符必须是对象`, { kind })
+  }
+  const errors = validateSchema(options, definition.schema)
+  definition.extra?.(options, errors)
+  if (errors.length) {
+    throw new AbiError(ERROR_CODES.E_SCHEMA, `${kind} 描述符非法：${errors.join('；')}`, { kind, errors })
+  }
+  return Object.freeze({ kind, ...options })
+}
+
+/* ------------------------------------------------------------------------- */
+/* 六个接口构建器 + 逃生舱                                                     */
+/* ------------------------------------------------------------------------- */
+
+export const skillProvider = (options) => defineInterface(KINDS['skill-provider'], options)
+export const toolProvider = (options) => defineInterface(KINDS['tool-provider'], options)
+export const runtimeDriver = (options) => defineInterface(KINDS['runtime-driver'], options)
+export const httpRouter = (options) => defineInterface(KINDS['http-router'], options)
+export const uiPanel = (options) => defineInterface(KINDS['ui-panel'], options)
+export const lifecycleHook = (options) => defineInterface(KINDS['lifecycle-hook'], options)
+
+/** 逃生舱：必须同时导出 apply，且不得与其他接口混用。 */
+export const rawPlugin = (apply) => defineInterface(KINDS.raw, { apply })
+
+/* ------------------------------------------------------------------------- */
+/* 插件定义                                                                    */
+/* ------------------------------------------------------------------------- */
+
+function parseCapability(entry, field) {
+  if (typeof entry !== 'string' || !entry.trim()) {
+    throw new AbiError(ERROR_CODES.E_PLUGIN_SHAPE, `${field} 的每一项必须是非空字符串`, { entry })
+  }
+  const at = entry.lastIndexOf('@')
+  if (at <= 0 || at === entry.length - 1) {
+    throw new AbiError(ERROR_CODES.E_PLUGIN_SHAPE, `${field} 项 "${entry}" 必须写成 name@range`, { entry })
+  }
+  const name = entry.slice(0, at)
+  const range = entry.slice(at + 1)
+  if (!CAPABILITY_NAME_RE.test(name)) {
+    throw new AbiError(ERROR_CODES.E_PLUGIN_SHAPE, `${field} 项 "${entry}" 的能力名非法`, { entry, name })
+  }
+  if (!RANGE_RE.test(range)) {
+    throw new AbiError(ERROR_CODES.E_PLUGIN_SHAPE, `${field} 项 "${entry}" 的版本范围非法`, { entry, range })
+  }
+  return Object.freeze({ name, range, raw: entry })
+}
+
+/**
+ * @param {{
+ *   name: string,
+ *   apiVersion?: number,
+ *   description?: string,
+ *   requires?: string[],
+ *   provides?: string[],
+ *   implements: object[]
+ * }} options
+ */
+export function definePlugin(options = {}) {
+  const { name, apiVersion = ABI_MAJOR, description, requires = [], provides = [], implements: impls } = options
+
+  if (!PLUGIN_NAME_RE.test(String(name || ''))) {
+    throw new AbiError(ERROR_CODES.E_PLUGIN_SHAPE, `插件名必须是 kebab-case：${name}`, { name })
+  }
+  if (!Number.isInteger(apiVersion) || apiVersion !== ABI_MAJOR) {
+    throw new AbiError(ERROR_CODES.E_ABI_MISMATCH,
+      `插件声明 ABI v${apiVersion}，内核只支持 v${ABI_MAJOR}`, { name, apiVersion, supported: ABI_MAJOR })
+  }
+  if (!Array.isArray(impls) || impls.length === 0) {
+    throw new AbiError(ERROR_CODES.E_PLUGIN_SHAPE, '插件必须实现至少一个接口', { name })
+  }
+  if (description !== undefined && typeof description !== 'string') {
+    throw new AbiError(ERROR_CODES.E_PLUGIN_SHAPE, 'description 必须是字符串', { name })
+  }
+
+  for (const impl of impls) {
+    if (!impl || typeof impl !== 'object' || typeof impl.kind !== 'string') {
+      throw new AbiError(ERROR_CODES.E_PLUGIN_SHAPE, 'implements 的每一项必须是 define* 产出的描述符', { name })
+    }
+    const { definition, errors } = validateInterface(impl)
+    if (!definition) {
+      throw new AbiError(ERROR_CODES.E_KIND_UNKNOWN, `未知接口种类 ${impl.kind}`, { name, kind: impl.kind })
+    }
+    if (errors.length) {
+      throw new AbiError(ERROR_CODES.E_SCHEMA, `${impl.kind} 描述符非法：${errors.join('；')}`, {
+        name, kind: impl.kind, errors,
+      })
+    }
+  }
+
+  if (impls.some((impl) => getInterfaceKind(impl.kind)?.exclusive) && impls.length > 1) {
+    throw new AbiError(ERROR_CODES.E_PLUGIN_SHAPE, 'raw@1 不得与其他接口混用', { name })
+  }
+
+  const requiresEntries = requires.map((entry) => parseCapability(entry, 'requires'))
+  const providesEntries = provides.map((entry) => parseCapability(entry, 'provides'))
+  for (const entry of providesEntries) {
+    if (/^[\^~<>=]/.test(entry.range)) {
+      throw new AbiError(ERROR_CODES.E_PLUGIN_SHAPE,
+        `provides 必须写精确版本，不能写范围：${entry.raw}`, { entry: entry.raw })
+    }
+  }
+
+  return Object.freeze({
+    kind: 'plugin',
+    name,
+    apiVersion,
+    description,
+    requires: Object.freeze(requiresEntries),
+    provides: Object.freeze(providesEntries),
+    implements: Object.freeze([...impls]),
+  })
+}
+
+/* ------------------------------------------------------------------------- */
+/* Cordis 接缝                                                                 */
+/* ------------------------------------------------------------------------- */
+
+/**
+ * 把插件定义编译成普通 Cordis 插件：{ name, inject, apply }。
+ *
+ * apply 的返回值是 disposer（与仓内既有插件一致），内核在卸载时调用。
+ * 形状错误（schema / 能力 / 唯一性）同步抛出，让插件加载直接失败；
+ * 运行时就绪（子进程拉起等）异步进行，通过 os.report() 观测。
+ *
+ * @param {object} definition definePlugin 的结果，或直接传 definePlugin 的入参
+ * @param {string} baseUrl 插件入口的 import.meta.url，用于解析相对路径
+ */
+export function createPlugin(definition, baseUrl) {
+  const spec = definition?.kind === 'plugin' ? definition : definePlugin(definition)
+
+  function apply(ctx, config = {}) {
+    const os = ctx?.os
+    if (!os || typeof os.mount !== 'function') {
+      throw new AbiError(ERROR_CODES.E_KERNEL_MISSING,
+        'ctx.os 不可用：请先安装并启用 @capyclaw/foundation', { plugin: spec.name })
+    }
+    if (!baseUrl) {
+      throw new AbiError(ERROR_CODES.E_BASE_URL_MISSING,
+        'createPlugin 需要第二参数 baseUrl（传 import.meta.url）', { plugin: spec.name })
+    }
+    const handle = os.mount(spec, config, { baseUrl })
+    return () => handle.dispose()
+  }
+
+  return Object.freeze({ name: spec.name, inject: ['os'], apply, spec })
+}
+
+export { toAbiError }

package/abi/validate.mjs

@@ -0,0 +1,24 @@
+/**
+ * 描述符校验：把「kind 之外的全部字段」交给对应接口的 schema。
+ *
+ * 单独成模块，是因为 spec（构建期）与 loader（加载期）必须用同一套判定；
+ * 只要两处各写一遍，迟早会出现「构建能过、加载失败」或反过来。
+ */
+import { getInterfaceKind } from './kinds.mjs'
+import { validateSchema } from './schema.mjs'
+
+/**
+ * @param {object} impl 描述符（含 kind）
+ * @returns {{ definition: object|null, errors: string[] }}
+ */
+export function validateInterface(impl) {
+  const definition = getInterfaceKind(impl?.kind)
+  if (!definition) {
+    return { definition: null, errors: [`未知接口种类 ${impl?.kind}`] }
+  }
+  const body = { ...impl }
+  delete body.kind
+  const errors = validateSchema(body, definition.schema)
+  definition.extra?.(body, errors)
+  return { definition, errors }
+}

package/abi/version.mjs

@@ -0,0 +1,82 @@
+/**
+ * 版本与范围：能力声明用 `^1` / `^1.2.0` / `>=1.2` / `1.x` / 精确版本。
+ *
+ * 只实现这份 ABI 需要的语义，不引入 semver 依赖：
+ * - `^1.2.3` → >=1.2.3 且同主版本；`^0.2.3` → >=0.2.3 且同次版本（0.x 约定）
+ * - `~1.2.3` → >=1.2.3 且同次版本
+ * - `1.x` / `1.*` → 同主版本
+ * - `>=` `>` `<=` `<` `=` 前缀
+ * - 裸版本 → 精确匹配（比较时忽略末位 0）
+ */
+
+export function parseVersion(text) {
+  if (typeof text !== 'string') return null
+  const match = /^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-[0-9A-Za-z.-]+)?$/.exec(text.trim())
+  if (!match) return null
+  return [Number(match[1]), Number(match[2] || 0), Number(match[3] || 0)]
+}
+
+function compareParts(a, b) {
+  for (let i = 0; i < 3; i++) {
+    if (a[i] !== b[i]) return a[i] < b[i] ? -1 : 1
+  }
+  return 0
+}
+
+export function compareVersions(a, b) {
+  const left = typeof a === 'string' ? parseVersion(a) : a
+  const right = typeof b === 'string' ? parseVersion(b) : b
+  if (!left || !right) return NaN
+  return compareParts(left, right)
+}
+
+/**
+ * @param {string} version 提供方版本，如 '1.2.3'
+ * @param {string} range 需求范围，如 '^1'
+ * @returns {boolean}
+ */
+export function satisfies(version, range) {
+  const current = parseVersion(version)
+  if (!current) return false
+  const raw = String(range ?? '').trim()
+  if (!raw || raw === '*' || raw === 'x') return true
+
+  if (raw.startsWith('^')) {
+    const base = parseVersion(raw.slice(1))
+    if (!base) return false
+    if (compareParts(current, base) < 0) return false
+    return base[0] === 0 ? current[0] === 0 && current[1] === base[1] : current[0] === base[0]
+  }
+  if (raw.startsWith('~')) {
+    const base = parseVersion(raw.slice(1))
+    if (!base) return false
+    return compareParts(current, base) >= 0 && current[0] === base[0] && current[1] === base[1]
+  }
+  if (raw.startsWith('>=')) {
+    const base = parseVersion(raw.slice(2))
+    return Boolean(base) && compareParts(current, base) >= 0
+  }
+  if (raw.startsWith('<=')) {
+    const base = parseVersion(raw.slice(2))
+    return Boolean(base) && compareParts(current, base) <= 0
+  }
+  if (raw.startsWith('>')) {
+    const base = parseVersion(raw.slice(1))
+    return Boolean(base) && compareParts(current, base) > 0
+  }
+  if (raw.startsWith('<')) {
+    const base = parseVersion(raw.slice(1))
+    return Boolean(base) && compareParts(current, base) < 0
+  }
+  if (raw.startsWith('=')) return satisfies(version, raw.slice(1))
+
+  const xRange = /^(\d+)(?:\.(\d+))?\.[x*]$/.exec(raw)
+  if (xRange) {
+    const major = Number(xRange[1])
+    const minor = xRange[2] === undefined ? null : Number(xRange[2])
+    return current[0] === major && (minor === null || current[1] === minor)
+  }
+
+  const exact = parseVersion(raw)
+  return Boolean(exact) && compareParts(current, exact) === 0
+}

package/cordis.patch.yml

@@ -0,0 +1,7 @@
+<!--
+  @capyclaw/foundation 的 bundle patch：在 Cordis 树里登记内核，产出 ctx.os。
+  应用插件由 loader 在各自的 apply 里挂载，不再单独产生 patch 行。
+-->
+- insert:
+    - id: capyclaw-foundation
+      name: '@capyclaw/foundation'

package/kit/index.mjs

@@ -0,0 +1,7 @@
+/**
+ * libc 入口：纯函数基建，零副作用。
+ *
+ * 迁移期直接复用 @capyclaw/plugin-kit；后续把这些实现内联进 foundation 时，
+ * 这个入口的导出面保持不变，应用侧一行都不用改。
+ */
+export * from '@capyclaw/plugin-kit'

package/lib/adapters/http-router.mjs

@@ -0,0 +1,45 @@
+/**
+ * http-router@1 适配器：routes(app) 往子 app 上挂路由，内核把子 app 挂到共享宿主的前缀下。
+ *
+ * 前缀冲突由 service-host 的 sharedHost.mount 检测（重复前缀直接抛错），
+ * 应用侧不接触 server、不选端口。
+ */
+import { AbiError, ERROR_CODES } from '../../abi/errors.mjs'
+
+export const kind = 'http-router@1'
+
+export function createHttpRouterAdapter({ ctx, net, log }) {
+  return {
+    kind,
+    compile(impl, { spec, config }) {
+      if (!ctx?.serviceHost?.createApp) {
+        throw new AbiError(ERROR_CODES.E_CAP_MISSING,
+          'ctx.serviceHost 不可用：无法创建子 app', { plugin: spec.name, capability: 'os.net' })
+      }
+
+      const app = ctx.serviceHost.createApp({ id: spec.name, title: spec.name })
+      try {
+        impl.routes(app, { spec, config, log })
+      } catch (error) {
+        throw new AbiError(ERROR_CODES.E_ADAPTER_THREW,
+          `路由注册失败：${error.message}`, { plugin: spec.name, cause: error })
+      }
+
+      let unmount
+      try {
+        unmount = net.mount(impl.mount, app)
+      } catch (error) {
+        throw new AbiError(ERROR_CODES.E_ADAPTER_THREW,
+          `挂载前缀 ${impl.mount} 失败：${error.message}`, { plugin: spec.name, prefix: impl.mount, cause: error })
+      }
+
+      log?.debug?.(`[foundation] ${spec.name} 路由挂到 ${impl.mount}`)
+      return {
+        app,
+        dispose: () => {
+          if (typeof unmount === 'function') unmount()
+        },
+      }
+    },
+  }
+}

package/lib/adapters/lifecycle-hook.mjs

@@ -0,0 +1,62 @@
+/**
+ * lifecycle-hook@1 的适配器。
+ *
+ * 运行时只执行 onStart / onStop；onInstall / onUpgrade 属于安装与升级流程，
+ * 由安装器（publisher / dsh profile 安装）在对应时点读取描述符后调用。
+ * 这里把它们登记进 hook 注册表，保证「声明了就找得到」。
+ */
+export const kind = 'lifecycle-hook@1'
+
+export function createHookRegistry() {
+  return {
+    install: [],
+    upgrade: [],
+    register(phase, entry) {
+      if (!this[phase]) throw new Error(`未知生命周期阶段 ${phase}`)
+      this[phase].push(entry)
+      return () => {
+        const index = this[phase].indexOf(entry)
+        if (index >= 0) this[phase].splice(index, 1)
+      }
+    },
+    list() {
+      return {
+        install: this.install.map((entry) => entry.plugin),
+        upgrade: this.upgrade.map((entry) => entry.plugin),
+      }
+    },
+  }
+}
+
+export function createLifecycleAdapter({ hooks, log }) {
+  return {
+    kind,
+    compile(impl, { spec }) {
+      const removers = []
+      if (typeof impl.onInstall === 'function') {
+        removers.push(hooks.register('install', { plugin: spec.name, run: impl.onInstall }))
+      }
+      if (typeof impl.onUpgrade === 'function') {
+        removers.push(hooks.register('upgrade', { plugin: spec.name, run: impl.onUpgrade }))
+      }
+      return {
+        async start() {
+          if (typeof impl.onStart === 'function') await impl.onStart({ plugin: spec.name })
+        },
+        dispose() {
+          if (typeof impl.onStop === 'function') {
+            try {
+              const result = impl.onStop({ plugin: spec.name })
+              if (result && typeof result.then === 'function') {
+                result.catch((error) => log?.error?.(`[foundation] ${spec.name} onStop 失败: ${error.message}`))
+              }
+            } catch (error) {
+              log?.error?.(`[foundation] ${spec.name} onStop 失败: ${error.message}`)
+            }
+          }
+          for (const remove of removers) remove()
+        },
+      }
+    },
+  }
+}

package/lib/adapters/runtime-driver.mjs

@@ -0,0 +1,79 @@
+/**
+ * runtime-driver@1 适配器：把描述符翻译成 broker 的服务规格。
+ *
+ * 应用侧不 spawn、不管重试、不做健康检查；这些由 service-broker 的 engine 负责。
+ * 端口由描述符或内核配置决定，应用不自己选端口。
+ */
+import { fileURLToPath } from 'node:url'
+
+import { AbiError, ERROR_CODES } from '../../abi/errors.mjs'
+
+export const kind = 'runtime-driver@1'
+
+export function createRuntimeDriverAdapter({ ctx, config, log }) {
+  const defaultPort = config.driverPort ?? 0
+
+  return {
+    kind,
+    compile(impl, mountContext) {
+      if (!ctx?.serviceBroker?.start || !ctx?.serviceBroker?.stop) {
+        throw new AbiError(ERROR_CODES.E_CAP_MISSING,
+          'ctx.serviceBroker 不可用：无法拉起长驻进程',
+          { plugin: mountContext.spec.name, capability: 'os.proc' })
+      }
+      if (!mountContext?.context?.baseUrl) {
+        throw new AbiError(ERROR_CODES.E_BASE_URL_MISSING,
+          `插件 ${mountContext.spec.name} 缺少 baseUrl，无法解析 ${impl.entry}`,
+          { plugin: mountContext.spec.name })
+      }
+
+      const entryPath = fileURLToPath(new URL(impl.entry, mountContext.context.baseUrl))
+      const port = impl.port ?? defaultPort
+      const portArg = impl.portArg || '--port'
+      const cmd = [
+        process.execPath,
+        entryPath,
+        portArg,
+        String(port),
+        ...(impl.args || []),
+      ]
+
+      const serviceSpec = {
+        id: impl.id,
+        cmd,
+        ports: { main: port },
+        url: 'http://127.0.0.1:${PORT}/',
+        keepAlive: true,
+      }
+      if (impl.health?.path) serviceSpec.healthPath = impl.health.path
+      if (impl.dir) {
+        serviceSpec.cwd = fileURLToPath(new URL(impl.dir, mountContext.context.baseUrl))
+      }
+      const env = impl.env?.({ spec: mountContext.spec, config: mountContext.config })
+      if (env && typeof env === 'object') serviceSpec.env = env
+
+      let stopped = false
+      return {
+        serviceSpec,
+        async start() {
+          const result = await ctx.serviceBroker.start(serviceSpec)
+          const failure = (result?.errors || []).find((item) => item.id === impl.id)
+          if (failure) {
+            throw new AbiError(ERROR_CODES.E_ADAPTER_THREW,
+              `长驻进程 ${impl.id} 启动失败：${failure.error}`, { plugin: mountContext.spec.name, id: impl.id })
+          }
+          log?.info?.(`[foundation] ${impl.id} 已由 broker 拉起（port ${port}）`)
+        },
+        dispose() {
+          if (stopped) return
+          stopped = true
+          try {
+            ctx.serviceBroker.stop(impl.id)
+          } catch (error) {
+            log?.warn?.(`[foundation] 停止 ${impl.id} 失败: ${error.message}`)
+          }
+        },
+      }
+    },
+  }
+}

package/lib/adapters/skill-provider.mjs

@@ -0,0 +1,56 @@
+/**
+ * skill-provider@1 的适配器：目录 → provider → ctx.skills。
+ *
+ * 应用包只写 `skillProvider({ skill: './skills/canvas' })`，
+ * frontmatter 解析、契约注记、注册与释放都在这里完成。
+ */
+import { readFileSync } from 'node:fs'
+import { basename, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { AbiError, ERROR_CODES } from '../../abi/errors.mjs'
+import { createSkillProvider } from '../skill/scan.mjs'
+
+export const kind = 'skill-provider@1'
+
+export function createSkillAdapter({ ctx, log }) {
+  return {
+    kind,
+    compile(impl, { spec, context }) {
+      const skills = ctx?.skills
+      if (!skills || typeof skills.registerProvider !== 'function') {
+        throw new AbiError(ERROR_CODES.E_CAP_MISSING,
+          'ctx.skills.registerProvider 不可用：skills 服务未加载', { plugin: spec.name })
+      }
+      if (!context?.baseUrl) {
+        throw new AbiError(ERROR_CODES.E_BASE_URL_MISSING,
+          `插件 ${spec.name} 缺少 baseUrl，无法解析 ${impl.skill}`, { plugin: spec.name })
+      }
+
+      const skillPath = fileURLToPath(new URL(impl.skill, context.baseUrl))
+      let contract = null
+      if (impl.contract) {
+        const contractPath = fileURLToPath(new URL(impl.contract, context.baseUrl))
+        try {
+          contract = JSON.parse(readFileSync(contractPath, 'utf8'))
+        } catch (error) {
+          throw new AbiError(ERROR_CODES.E_ADAPTER_THREW,
+            `契约快照不可读：${contractPath}`, { plugin: spec.name, cause: error })
+        }
+      }
+
+      const provider = createSkillProvider({
+        assetRoot: dirname(skillPath),
+        skillDirs: [basename(skillPath)],
+        providerName: impl.name || `dsh-${spec.name}`,
+        rank: impl.rank,
+        contract,
+        contractNote: impl.note,
+      })
+
+      const dispose = skills.registerProvider(() => provider)
+      log?.debug?.(`[foundation] ${spec.name} 注册 skill ${impl.skill}`)
+      return { provider, dispose: typeof dispose === 'function' ? dispose : () => {} }
+    },
+  }
+}

package/lib/adapters/tool-provider.mjs

@@ -0,0 +1,42 @@
+/**
+ * tool-provider@1 适配器：描述符里的 provide() 产出注册表，内核负责注册与反注册。
+ *
+ * 应用侧写法：
+ *   toolProvider({ namespace: 'browser', provide: () => registry })
+ *
+ * 工具实现不经过 foundation，foundation 只决定「什么时候挂上去、挂到哪个命名空间」。
+ */
+import { AbiError, ERROR_CODES } from '../../abi/errors.mjs'
+
+export const kind = 'tool-provider@1'
+
+export function createToolProviderAdapter({ ctx, log }) {
+  return {
+    kind,
+    compile(impl, { spec, config }) {
+      if (!ctx?.toolHost?.registerWithDsh) {
+        throw new AbiError(ERROR_CODES.E_CAP_MISSING,
+          'ctx.toolHost 不可用：无法注册工具面', { plugin: spec.name, capability: 'os.tools' })
+      }
+
+      let registry
+      try {
+        registry = impl.provide({ spec, config, log })
+      } catch (error) {
+        throw new AbiError(ERROR_CODES.E_ADAPTER_THREW,
+          `工具注册表构建失败：${error.message}`, { plugin: spec.name, cause: error })
+      }
+      if (!registry || !Array.isArray(registry.TOOLS)) {
+        throw new AbiError(ERROR_CODES.E_ADAPTER_THREW,
+          'provide() 必须返回 { TOOLS, TOOL_IMPL } 形状的注册表', { plugin: spec.name })
+      }
+
+      const dispose = ctx.toolHost.registerWithDsh(ctx, registry, { namespace: impl.namespace })
+      log?.debug?.(`[foundation] ${spec.name} 注册 ${registry.TOOLS.length} 个工具（${impl.namespace}）`)
+      return {
+        registry,
+        dispose: typeof dispose === 'function' ? dispose : () => {},
+      }
+    },
+  }
+}

package/lib/adapters/ui-panel.mjs

@@ -0,0 +1,55 @@
+/**
+ * ui-panel@1 适配器：把静态目录挂到共享宿主的挂载点。
+ *
+ * 文件读取、路径穿越防护、缓存头由 editor-host 负责；内核只负责解析目录与挂载。
+ */
+import { fileURLToPath } from 'node:url'
+
+import { AbiError, ERROR_CODES } from '../../abi/errors.mjs'
+
+export const kind = 'ui-panel@1'
+
+export function createUiPanelAdapter({ ctx, net, log }) {
+  return {
+    kind,
+    compile(impl, { spec, config, context }) {
+      if (!ctx?.serviceHost?.createApp || !ctx?.editorHost?.createEditorHost) {
+        throw new AbiError(ERROR_CODES.E_CAP_MISSING,
+          'ctx.editorHost / ctx.serviceHost 不可用：无法挂静态面板',
+          { plugin: spec.name, capability: 'os.ui' })
+      }
+      if (!context?.baseUrl) {
+        throw new AbiError(ERROR_CODES.E_BASE_URL_MISSING,
+          `插件 ${spec.name} 缺少 baseUrl，无法解析 ${impl.root}`, { plugin: spec.name })
+      }
+
+      const dir = fileURLToPath(new URL(impl.root, context.baseUrl))
+      const editor = ctx.editorHost.createEditorHost({
+        id: spec.name,
+        dir,
+        basePath: impl.mount,
+        index: impl.index,
+      })
+
+      const app = ctx.serviceHost.createApp({ id: spec.name, title: spec.name })
+      for (const route of editor.routes()) app.use(route)
+
+      let unmount
+      try {
+        unmount = net.mount(impl.mount, app)
+      } catch (error) {
+        throw new AbiError(ERROR_CODES.E_ADAPTER_THREW,
+          `挂载面板 ${impl.mount} 失败：${error.message}`, { plugin: spec.name, prefix: impl.mount, cause: error })
+      }
+
+      log?.debug?.(`[foundation] ${spec.name} 面板挂到 ${impl.mount}`)
+      return {
+        app,
+        editor,
+        dispose: () => {
+          if (typeof unmount === 'function') unmount()
+        },
+      }
+    },
+  }
+}