@capyclaw/foundation 0.0.0-stage → 0.1.0

package/lib/host.mjs

@@ -0,0 +1,22 @@
+/**
+ * @capyclaw/foundation 的 Cordis 入口：向同进程插件提供 ctx.os。
+ *
+ * 这是整个工程里唯一一处「把内核交给 dsh」的接缝。应用插件不 import 这个文件，
+ * 它们只在自己的 apply 里拿到 ctx.os。
+ */
+import { createKernel } from './kernel.mjs'
+
+export const name = 'capyclaw-foundation'
+
+export function apply(ctx, config = {}) {
+  const kernel = createKernel(ctx, config)
+  const dispose = ctx.provide('os', kernel.os)
+  console.log('[foundation] ready（abi v' + kernel.os.abi + '）')
+  return () => {
+    try {
+      kernel.dispose()
+    } finally {
+      if (typeof dispose === 'function') dispose()
+    }
+  }
+}

package/lib/kernel.mjs

@@ -0,0 +1,93 @@
+/**
+ * 内核装配：把 ABI 加载器、适配器与 os 子系统接到一起。
+ *
+ * 能力表是**探测出来**的，不是写死的：ctx 里没有 skills 服务，就不承诺 os.skills，
+ * 依赖它的插件在 mount 阶段拿到 E_CAP_MISSING，而不是运行到一半才炸。
+ *
+ * 惰性：os.net 只在第一次挂路由时创建共享宿主并 listen；纯 skill 插件不占端口。
+ */
+import { ABI_MAJOR } from '../abi/kinds.mjs'
+import { createLoader } from '../abi/loader.mjs'
+import { createSkillAdapter } from './adapters/skill-provider.mjs'
+import { createToolProviderAdapter } from './adapters/tool-provider.mjs'
+import { createRuntimeDriverAdapter } from './adapters/runtime-driver.mjs'
+import { createHttpRouterAdapter } from './adapters/http-router.mjs'
+import { createUiPanelAdapter } from './adapters/ui-panel.mjs'
+import { createHookRegistry, createLifecycleAdapter } from './adapters/lifecycle-hook.mjs'
+import { createEvents } from './subsystems/events.mjs'
+import { createLogger } from './subsystems/log.mjs'
+import { createNet } from './subsystems/net.mjs'
+
+/** 内核自身就能提供的能力（不依赖任何 dsh 服务）。 */
+export const BASE_CAPABILITIES = Object.freeze({
+  'os.events': '1.0.0',
+  'os.log': '1.0.0',
+  'os.caps': '1.0.0',
+})
+
+/** 按 ctx 里实际存在的服务生成能力表。 */
+export function detectCapabilities(ctx) {
+  const capabilities = { ...BASE_CAPABILITIES }
+  if (ctx?.skills?.registerProvider) capabilities['os.skills'] = '1.0.0'
+  if (ctx?.serviceHost?.createSharedHost && ctx?.serviceHost?.createApp) capabilities['os.net'] = '1.0.0'
+  if (ctx?.toolHost?.registerWithDsh) capabilities['os.tools'] = '1.0.0'
+  if (ctx?.serviceBroker?.start) capabilities['os.proc'] = '1.0.0'
+  if (ctx?.editorHost?.createEditorHost) capabilities['os.ui'] = '1.0.0'
+  return capabilities
+}
+
+export const KERNEL_VERSION = '0.1.0'
+export const ABI_VERSION = ABI_MAJOR
+
+export function createKernel(ctx, config = {}) {
+  const log = createLogger(ctx, config)
+  const events = createEvents({
+    onError: (error, topic) => log.error(`事件订阅者抛错 (${topic}): ${error.message}`),
+  })
+  const hooks = createHookRegistry()
+  const net = createNet(ctx, config)
+  const capabilities = detectCapabilities(ctx)
+
+  const adapters = {
+    'skill-provider@1': createSkillAdapter({ ctx, log }),
+    'tool-provider@1': createToolProviderAdapter({ ctx, log }),
+    'runtime-driver@1': createRuntimeDriverAdapter({ ctx, config, log }),
+    'http-router@1': createHttpRouterAdapter({ ctx, net, log }),
+    'ui-panel@1': createUiPanelAdapter({ ctx, net, log }),
+    'lifecycle-hook@1': createLifecycleAdapter({ hooks, log }),
+  }
+
+  const loader = createLoader({ adapters, capabilities, log })
+  const startedAt = Date.now()
+
+  const os = {
+    version: KERNEL_VERSION,
+    abi: ABI_VERSION,
+    mount: (spec, mountConfig = {}, meta = {}) => loader.mount(spec, mountConfig, meta),
+    report: () => ({
+      kernel: { version: KERNEL_VERSION, abi: ABI_VERSION, uptimeMs: Date.now() - startedAt },
+      ...loader.report(),
+    }),
+    events,
+    log,
+    hooks,
+    net,
+
+    /** 能力检查与自报。 */
+    caps: {
+      list: () => Object.keys(capabilities),
+      has: (name) => loader.capability(name) !== null,
+      version: (name) => loader.capability(name),
+      report: () => loader.report(),
+    },
+  }
+
+  return {
+    os,
+    dispose() {
+      loader.disposeAll()
+      events.clear()
+      void net.dispose()
+    },
+  }
+}

package/lib/skill/scan.mjs

@@ -0,0 +1,87 @@
+/**
+ * 技能扫描：SKILL.md 目录 → dsh skills provider。
+ *
+ * 这份实现是整个基石层里 skill-provider@1 的唯一实现。
+ * 此前 15 个包各自复制了一份 provider.mjs（sha256 相同），
+ * 迁移完成后由内核统一提供，应用包只声明目录。
+ */
+import { readFileSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { isAbsolute, join, sep } from 'node:path'
+
+const NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+const DEFAULT_RANK = 600
+
+export function parseSkill(raw, path) {
+  const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/u.exec(raw)
+  if (!frontmatter?.[1]) throw new Error(`skill ${path} 缺少 YAML frontmatter`)
+  const meta = {}
+  for (const line of frontmatter[1].split(/\r?\n/)) {
+    const match = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line)
+    if (match) meta[match[1]] = match[2].replace(/^['"]|['"]$/g, '').trim()
+  }
+  if (!meta.name || !meta.description) throw new Error(`skill ${path} 缺少 name/description`)
+  if (!NAME_RE.test(meta.name)) throw new Error(`skill ${path} name 必须是 kebab-case`)
+  return {
+    name: meta.name,
+    description: meta.description,
+    whenToUse: meta.whenToUse || undefined,
+    content: raw.slice(frontmatter[0].length).trim(),
+  }
+}
+
+/**
+ * @param {{
+ *   assetRoot: string,
+ *   skillDirs: string[],
+ *   providerName?: string,
+ *   rank?: number,
+ *   contract?: { version: string } | null,
+ *   contractNote?: (version: string, skillName: string) => string
+ * }} config
+ */
+export function createSkillProvider(config) {
+  const assetRoot = config.assetRoot
+  if (!assetRoot || !isAbsolute(assetRoot)) throw new Error('createSkillProvider: assetRoot 必须是绝对路径')
+  const rank = config.rank ?? DEFAULT_RANK
+  const dirs = config.skillDirs || []
+  if (!dirs.length) throw new Error('createSkillProvider: skillDirs 不能为空')
+
+  const candidates = dirs.map((dir) => {
+    if (!NAME_RE.test(dir)) throw new Error(`skill 目录名必须是 kebab-case：${dir}`)
+    const directory = join(assetRoot, dir)
+    const locator = join(directory, 'SKILL.md')
+    const parsed = parseSkill(readFileSync(locator, 'utf8'), locator)
+    if (parsed.name !== dir) throw new Error(`skill ${locator} name 必须是 ${dir}`)
+    return {
+      name: parsed.name,
+      description: parsed.description,
+      whenToUse: parsed.whenToUse,
+      invocation: { modelInvocable: true, userInvocable: true },
+      provider: config.providerName || 'dsh-plugin',
+      source: 'bundled',
+      rank,
+      resourceBase: { kind: 'directory', path: directory.split(sep).join('/') },
+      locator,
+    }
+  })
+
+  const byName = new Map(candidates.map((candidate) => [candidate.name, candidate]))
+  const noteFor = (name) => (config.contract && config.contractNote
+    ? config.contractNote(config.contract.contractVersion ?? config.contract.version, name)
+    : '')
+
+  return {
+    name: config.providerName || 'dsh-plugin',
+    list: () => Promise.resolve(candidates),
+    async get(candidate, options = {}) {
+      const hit = byName.get(candidate.name)
+      if (!hit) throw new Error(`未知 skill ${candidate.name}`)
+      const raw = await readFile(hit.locator, { encoding: 'utf8', signal: options.signal })
+      const parsed = parseSkill(raw, hit.locator)
+      const { rank: _rank, locator: _locator, ...summary } = hit
+      const note = noteFor(candidate.name)
+      return { ...summary, content: parsed.content + (note ? `\n\n---\n\n${note}` : '') }
+    },
+  }
+}

package/lib/subsystems/events.mjs

@@ -0,0 +1,55 @@
+/**
+ * 进程内事件总线：插件之间唯一的广播通道。
+ *
+ * 约定：emit 永不因订阅者抛错而中断；错误交给 onError 记录。
+ */
+export function createEvents({ onError } = {}) {
+  const listeners = new Map()
+
+  function on(topic, handler) {
+    if (typeof handler !== 'function') throw new TypeError('events.on 需要函数')
+    if (!listeners.has(topic)) listeners.set(topic, [])
+    listeners.get(topic).push(handler)
+    return () => off(topic, handler)
+  }
+
+  function once(topic, handler) {
+    const dispose = on(topic, (...args) => {
+      dispose()
+      handler(...args)
+    })
+    return dispose
+  }
+
+  function off(topic, handler) {
+    const bucket = listeners.get(topic)
+    if (!bucket) return
+    const index = bucket.indexOf(handler)
+    if (index >= 0) bucket.splice(index, 1)
+    if (!bucket.length) listeners.delete(topic)
+  }
+
+  function emit(topic, payload) {
+    const bucket = listeners.get(topic)
+    if (!bucket) return 0
+    let delivered = 0
+    for (const handler of [...bucket]) {
+      try {
+        handler(payload)
+        delivered++
+      } catch (error) {
+        onError?.(error, topic)
+      }
+    }
+    return delivered
+  }
+
+  return {
+    on,
+    once,
+    off,
+    emit,
+    topics: () => [...listeners.keys()],
+    clear: () => listeners.clear(),
+  }
+}

package/lib/subsystems/log.mjs

@@ -0,0 +1,27 @@
+/**
+ * 结构化日志：优先复用 dsh 的 ctx.logger，没有就退回 console。
+ *
+ * 插件不自己拼前缀，一律通过 log.child({ plugin }) 拿作用域。
+ */
+const LEVELS = ['debug', 'info', 'warn', 'error']
+
+function createScoped(underlying, scope) {
+  const prefix = scope ? `[${scope}]` : ''
+  const scoped = {}
+  for (const level of LEVELS) {
+    scoped[level] = (...args) => {
+      const message = args.map((arg) => (typeof arg === 'string' ? arg : JSON.stringify(arg))).join(' ')
+      const line = `${prefix} ${message}`.trim()
+      const fn = underlying?.[level]
+      if (typeof fn === 'function') fn.call(underlying, line)
+      else if (level !== 'debug') console[level](line)
+    }
+  }
+  scoped.child = (next) => createScoped(underlying, scope ? `${scope}:${next}` : next)
+  return scoped
+}
+
+export function createLogger(ctx, config = {}) {
+  const underlying = ctx?.logger
+  return createScoped(underlying, config.scope || 'foundation')
+}

package/lib/subsystems/net.mjs

@@ -0,0 +1,49 @@
+/**
+ * HTTP 共享宿主：内核持有的唯一监听面。
+ *
+ * 惰性：第一次有插件挂路由时才创建共享宿主并 listen，
+ * 只注册 skill 的插件不会因为装了 foundation 就占一个端口。
+ */
+import { AbiError, ERROR_CODES } from '../../abi/errors.mjs'
+
+export function createNet(ctx, config = {}) {
+  const http = config.http || {}
+  let host = null
+  let listening = null
+  let closed = false
+
+  function ensure() {
+    const serviceHost = ctx?.serviceHost
+    if (!serviceHost?.createSharedHost) {
+      throw new AbiError(ERROR_CODES.E_CAP_MISSING,
+        'ctx.serviceHost 不可用：无法挂载 HTTP 路由', { capability: 'os.net' })
+    }
+    if (!host) {
+      host = serviceHost.createSharedHost({ id: http.hostId || 'foundation-shared' })
+      listening = Promise.resolve(host.listen({ port: http.port ?? 0 }))
+    }
+    return host
+  }
+
+  return {
+    ensure,
+    mount(prefix, child) {
+      return ensure().mount(prefix, child)
+    },
+    children: () => (host ? host.children() : []),
+    ready() {
+      ensure()
+      return listening
+    },
+    async dispose() {
+      if (closed) return
+      closed = true
+      if (host) {
+        try {
+          await host.close()
+        } catch { /* 已关闭 */ }
+      }
+      host = null
+    },
+  }
+}

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@capyclaw/foundation",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "dsh 插件基石层：接口 ABI、插件加载器与内核服务 ctx.os。应用插件只声明接口，不写装配代码。",
+  "type": "module",
+  "main": "./lib/host.mjs",
+  "exports": {
+    ".": "./lib/host.mjs",
+    "./abi": "./abi/index.mjs",
+    "./kit": "./kit/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=18",
+    "dsh": "^0.2.0-rc.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "category": "service",
+    "platform": "both",
+    "apiVersion": "1.0.0"
+  },
+  "meta": {
+    "title": "插件基石层",
+    "description": "接口 ABI、插件加载器与 ctx.os 内核服务；应用插件只声明接口"
+  },
+  "files": [
+    "abi/",
+    "lib/",
+    "kit/",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@capyclaw/plugin-kit": "^0.2.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Maple496/capyclaw.git",
+    "directory": "packages/capyclaw-foundation"
+  }
+}