@capyclaw/foundation 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,32 @@
-# Temporary Holding Version
+# @capyclaw/foundation
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+dsh 插件基石层：接口 ABI、插件加载器与内核服务 `ctx.os`。
+
+应用插件不再写 `inject` / `apply` / provider 装配，只声明「我实现了哪个接口」：
+
+```js
+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)
+```
+
+## 三个入口
+
+| 入口 | 内容 | 谁用 |
+|---|---|---|
+| `.` | Cordis 插件，产出 `ctx.os` | dsh profile |
+| `./abi` | 描述符构建器、加载器、错误码、版本工具 | 应用插件 |
+| `./kit` | 纯函数基建（迁移期复用 plugin-kit） | 应用插件 |
+
+## 状态
+
+- ABI v1，六个接口适配器全部可用：`skill-provider` / `tool-provider` / `runtime-driver` /
+  `http-router` / `ui-panel` / `lifecycle-hook`，另有逃生舱 `raw@1`。
+- 能力表按 `ctx` 实际服务探测（见 `lib/kernel.mjs` 的 `detectCapabilities`），不做空头承诺。
+- 包当前为 `private`，未进入 registry；完成存量插件迁移后去掉并登记。
+
+设计规范见 `docs/spec/plugin-abi.md`，强制规则见 `docs/POLICY.md`。

package/abi/errors.mjs

@@ -0,0 +1,59 @@
+/**
+ * ABI 错误模型：稳定的错误码 + 结构化 detail。
+ *
+ * 约定：
+ * - 应用插件按 code 分支，不解析 message 文案；
+ * - message 面向人，detail 面向程序；
+ * - 所有加载期失败都必须是 AbiError，不允许裸 Error 穿透。
+ */
+
+/** 稳定错误码。新增只能追加，不得改语义。 */
+export const ERROR_CODES = Object.freeze({
+  /** 插件入口形状不对：缺 name / 没有 implements / 导出了 apply 等。 */
+  E_PLUGIN_SHAPE: 'E_PLUGIN_SHAPE',
+  /** 插件声明的 ABI 主版本与内核不兼容。 */
+  E_ABI_MISMATCH: 'E_ABI_MISMATCH',
+  /** 描述符的 kind 不在内核认识的接口表里。 */
+  E_KIND_UNKNOWN: 'E_KIND_UNKNOWN',
+  /** 描述符字段不满足接口 schema。 */
+  E_SCHEMA: 'E_SCHEMA',
+  /** 内核没有提供该能力（通常是 os.* 子系统缺失）。 */
+  E_CAP_MISSING: 'E_CAP_MISSING',
+  /** 唯一性接口被第二个插件实现（例如同 id 的 runtime-driver）。 */
+  E_DUP_INTERFACE: 'E_DUP_INTERFACE',
+  /** 同名插件被重复挂载。 */
+  E_DUP_PLUGIN: 'E_DUP_PLUGIN',
+  /** 内核没有为这个 kind 注册适配器（接口定义存在但实现未就绪）。 */
+  E_KIND_UNAVAILABLE: 'E_KIND_UNAVAILABLE',
+  /** 适配器在编译期抛错。 */
+  E_ADAPTER_THREW: 'E_ADAPTER_THREW',
+  /** 插件入口没有拿到 baseUrl，相对路径无法解析。 */
+  E_BASE_URL_MISSING: 'E_BASE_URL_MISSING',
+  /** 运行时没有 ctx.os：foundation 未安装或未启用。 */
+  E_KERNEL_MISSING: 'E_KERNEL_MISSING',
+})
+
+export class AbiError extends Error {
+  /**
+   * @param {string} code ERROR_CODES 中的一项
+   * @param {string} message 面向人的说明
+   * @param {Record<string, unknown>} [detail] 面向程序的结构化信息
+   */
+  constructor(code, message, detail = {}) {
+    super(`[${code}] ${message}`)
+    this.name = 'AbiError'
+    this.code = code
+    this.detail = detail
+    if (detail.cause instanceof Error) this.cause = detail.cause
+  }
+}
+
+export function isAbiError(error) {
+  return error instanceof AbiError
+}
+
+/** 把任意异常归一成 AbiError（已归一的原样返回）。 */
+export function toAbiError(error, code = ERROR_CODES.E_ADAPTER_THREW, detail = {}) {
+  if (error instanceof AbiError) return error
+  return new AbiError(code, error?.message || String(error), { ...detail, cause: error })
+}

package/abi/index.mjs

@@ -0,0 +1,19 @@
+/** 接口 ABI 的唯一入口：应用插件只需要 import 这个模块。 */
+export { ABI_MAJOR, INTERFACE_KINDS, INTERFACE_KIND_NAMES, getInterfaceKind } from './kinds.mjs'
+export {
+  defineInterface,
+  definePlugin,
+  createPlugin,
+  skillProvider,
+  toolProvider,
+  runtimeDriver,
+  httpRouter,
+  uiPanel,
+  lifecycleHook,
+  rawPlugin,
+} from './spec.mjs'
+export { createLoader } from './loader.mjs'
+export { validateInterface } from './validate.mjs'
+export { AbiError, ERROR_CODES, isAbiError, toAbiError } from './errors.mjs'
+export { validateSchema } from './schema.mjs'
+export { parseVersion, compareVersions, satisfies } from './version.mjs'

package/abi/kinds.mjs

@@ -0,0 +1,183 @@
+/**
+ * 接口种类表：定义「插件可以是什么」。
+ *
+ * 一条记录 = 一种插件形状。应用插件不写装配代码，只产出这里的描述符；
+ * 生命周期、注册、健康检查、日志包裹由内核的适配器统一完成。
+ *
+ * 版本规则：
+ * - 主版本写在 kind 后缀里（`skill-provider@1`），主版本不同就是不同接口；
+ * - 次版本只做增量字段，内核按主版本注册适配器；
+ * - 破坏性变更 = 新 kind（@2）+ 旧 kind 至少并存一个大版本。
+ */
+
+const nonEmpty = { type: 'string', minLength: 1 }
+const kebab = { type: 'string', pattern: '^[a-z0-9]+(?:-[a-z0-9]+)*$' }
+
+export const ABI_MAJOR = 1
+
+export const INTERFACE_KINDS = Object.freeze({
+  'skill-provider@1': Object.freeze({
+    kind: 'skill-provider@1',
+    major: 1,
+    title: '技能提供者',
+    summary: '把一个 SKILL.md 目录注册进 dsh skills 服务，可选附带契约快照与契约注记。',
+    unique: false,
+    schema: Object.freeze({
+      type: 'object',
+      required: ['skill'],
+      additionalProperties: false,
+      properties: {
+        name: kebab,
+        skill: nonEmpty,
+        contract: nonEmpty,
+        rank: { type: 'number', min: 0, max: 1000 },
+        note: { type: 'function' },
+      },
+    }),
+  }),
+
+  'tool-provider@1': Object.freeze({
+    kind: 'tool-provider@1',
+    major: 1,
+    title: '工具提供者',
+    summary: '声明一组工具并注册到工具面（注册表 / MCP 壳 / 能力报告）。',
+    unique: false,
+    schema: Object.freeze({
+      type: 'object',
+      required: ['namespace', 'provide'],
+      additionalProperties: false,
+      properties: {
+        namespace: kebab,
+        provide: { type: 'function' },
+        instructions: nonEmpty,
+        capabilities: { type: 'object' },
+      },
+    }),
+  }),
+
+  'runtime-driver@1': Object.freeze({
+    kind: 'runtime-driver@1',
+    major: 1,
+    title: '运行时驱动',
+    summary: '一个长驻进程的启动、就绪、健康与回收；端口由内核分配，应用不自己 spawn。',
+    unique: true,
+    uniqueBy: 'id',
+    schema: Object.freeze({
+      type: 'object',
+      required: ['id', 'entry'],
+      additionalProperties: false,
+      properties: {
+        id: kebab,
+        entry: nonEmpty,
+        args: { type: 'array', items: { type: 'string' } },
+        port: { type: ['number', 'string'] },
+        portArg: nonEmpty,
+        dir: nonEmpty,
+        env: { type: 'function' },
+        health: {
+          type: 'object',
+          required: ['path'],
+          additionalProperties: false,
+          properties: {
+            path: nonEmpty,
+            expect: { type: 'object' },
+            timeoutMs: { type: 'number', min: 1 },
+          },
+        },
+        restart: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            max: { type: 'integer', min: 0 },
+            backoffMs: { type: 'number', min: 0 },
+          },
+        },
+      },
+    }),
+  }),
+
+  'http-router@1': Object.freeze({
+    kind: 'http-router@1',
+    major: 1,
+    title: '路由挂载者',
+    summary: '把一组 HTTP 路由挂到内核的共享宿主上，前缀冲突由内核检测。',
+    unique: false,
+    schema: Object.freeze({
+      type: 'object',
+      required: ['mount', 'routes'],
+      additionalProperties: false,
+      properties: {
+        mount: { type: 'string', pattern: '^/' },
+        routes: { type: 'function' },
+        host: { type: 'string', enum: ['shared', 'own'] },
+      },
+    }),
+  }),
+
+  'ui-panel@1': Object.freeze({
+    kind: 'ui-panel@1',
+    major: 1,
+    title: '界面面板',
+    summary: '把静态资源目录挂到挂载点，缓存头与 404 兜底由内核处理。',
+    unique: false,
+    schema: Object.freeze({
+      type: 'object',
+      required: ['mount', 'root'],
+      additionalProperties: false,
+      properties: {
+        mount: { type: 'string', pattern: '^/' },
+        root: nonEmpty,
+        index: nonEmpty,
+        cache: { type: 'string', enum: ['no-store', 'revalidate', 'immutable'] },
+      },
+    }),
+  }),
+
+  'lifecycle-hook@1': Object.freeze({
+    kind: 'lifecycle-hook@1',
+    major: 1,
+    title: '生命周期钩子',
+    summary: '在安装 / 启动 / 停止 / 升级四个时点插入行为，时序与幂等由内核保证。',
+    unique: false,
+    schema: Object.freeze({
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        onInstall: { type: 'function' },
+        onStart: { type: 'function' },
+        onStop: { type: 'function' },
+        onUpgrade: { type: 'function' },
+      },
+    }),
+    /** schema 表达不了「至少一个钩子」，用额外校验补。 */
+    extra(impl, errors) {
+      const hooks = ['onInstall', 'onStart', 'onStop', 'onUpgrade'].filter((key) => typeof impl[key] === 'function')
+      if (!hooks.length) errors.push('$ 至少需要实现一个钩子（onInstall/onStart/onStop/onUpgrade）')
+    },
+  }),
+
+  'raw@1': Object.freeze({
+    kind: 'raw@1',
+    major: 1,
+    title: '原生插件（逃生舱）',
+    summary: '极少数需要自定义装配的插件；必须在 foundation.allowlist.json 登记，且不得与其他接口混用。',
+    unique: false,
+    exclusive: true,
+    schema: Object.freeze({
+      type: 'object',
+      required: ['apply'],
+      additionalProperties: false,
+      properties: {
+        apply: { type: 'function' },
+      },
+    }),
+  }),
+})
+
+/** 内核当前认识的 kind 列表（供错误信息与文档生成）。 */
+export const INTERFACE_KIND_NAMES = Object.freeze(Object.keys(INTERFACE_KINDS))
+
+/** 取接口定义；未知 kind 返回 undefined，由调用方转成 E_KIND_UNKNOWN。 */
+export function getInterfaceKind(kind) {
+  return INTERFACE_KINDS[kind]
+}

package/abi/loader.mjs

@@ -0,0 +1,249 @@
+/**
+ * 插件加载器：把描述符编译成运行时实例。
+ *
+ * 四段式，任何副作用都在最后一段：
+ *   1. validate  纯检查（形状 / 版本 / 能力 / 唯一性），不碰任何资源；
+ *   2. compile   逐个接口交给适配器；失败则回滚已编译的实例；
+ *   3. start     运行时就绪（子进程拉起、监听等），异步，失败进 failures；
+ *   4. commit    登记插件、能力与唯一性占用。
+ *
+ * 这样保证：坏描述符不会产生半个插件，也不会留下悬挂端口或子进程。
+ */
+import { ABI_MAJOR, getInterfaceKind } from './kinds.mjs'
+import { validateInterface } from './validate.mjs'
+import { AbiError, ERROR_CODES, toAbiError } from './errors.mjs'
+import { satisfies } from './version.mjs'
+
+/**
+ * @param {{
+ *   adapters: Record<string, { kind: string, compile: Function }>,
+ *   capabilities?: Record<string, string>,
+ *   log?: object,
+ *   abiMajor?: number
+ * }} options
+ */
+export function createLoader({ adapters = {}, capabilities = {}, log = null, abiMajor = ABI_MAJOR } = {}) {
+  /** @type {Map<string, { spec: object, entries: object[], handle: object }>} */
+  const plugins = new Map()
+  /** 唯一性占用：key -> 插件名 */
+  const uniques = new Map()
+  /** 已提供能力：name -> { plugin, version } */
+  const provided = new Map()
+  /** 运行期失败（start / 异步就绪） */
+  const failures = []
+
+  function adapterOf(kind) {
+    const adapter = adapters[kind]
+    if (!adapter || typeof adapter.compile !== 'function') {
+      throw new AbiError(ERROR_CODES.E_KIND_UNAVAILABLE,
+        `接口 ${kind} 已定义但内核没有注册适配器`, { kind, available: Object.keys(adapters) })
+    }
+    return adapter
+  }
+
+  function assertCapabilities(spec) {
+    const missing = []
+    for (const requirement of spec.requires) {
+      if (!requirement.name.startsWith('os.')) continue // 跨插件能力由 suite 组合期校验，运行时只报告
+      const version = capabilities[requirement.name]
+      if (!version) {
+        missing.push({ name: requirement.name, range: requirement.range, reason: '未提供' })
+      } else if (!satisfies(version, requirement.range)) {
+        missing.push({ name: requirement.name, range: requirement.range, reason: `提供 ${version}` })
+      }
+    }
+    if (missing.length) {
+      throw new AbiError(ERROR_CODES.E_CAP_MISSING,
+        `插件 ${spec.name} 需要的能力不可用：${missing.map((m) => `${m.name}@${m.range}（${m.reason}）`).join('，')}`,
+        { plugin: spec.name, missing })
+    }
+  }
+
+  function claimUniqueness(impls, pluginName, committed) {
+    const batch = new Map()
+    for (const impl of impls) {
+      const definition = getInterfaceKind(impl.kind)
+      if (!definition?.unique) continue
+      const key = definition.uniqueBy ? `${impl.kind}:${impl[definition.uniqueBy]}` : impl.kind
+      const owner = committed.get(key) || batch.get(key)
+      if (owner) {
+        throw new AbiError(ERROR_CODES.E_DUP_INTERFACE,
+          `接口 ${key} 已被 ${owner} 占用，${pluginName} 不能重复实现`, { key, owner, plugin: pluginName })
+      }
+      batch.set(key, pluginName)
+    }
+    return batch
+  }
+
+  /**
+   * 挂载一个插件。同步完成校验与注册，返回 handle。
+   * @param {object} spec definePlugin 的结果
+   * @param {object} [config]
+   * @param {{ baseUrl?: string }} [context]
+   */
+  function mount(spec, config = {}, context = {}) {
+    if (!spec || spec.kind !== 'plugin') {
+      throw new AbiError(ERROR_CODES.E_PLUGIN_SHAPE, 'mount 需要 definePlugin 产出的插件描述符', {
+        got: spec?.kind ?? typeof spec,
+      })
+    }
+    if (spec.apiVersion !== abiMajor) {
+      throw new AbiError(ERROR_CODES.E_ABI_MISMATCH,
+        `插件 ${spec.name} 声明 ABI v${spec.apiVersion}，内核为 v${abiMajor}`,
+        { plugin: spec.name, apiVersion: spec.apiVersion, abiMajor })
+    }
+    if (plugins.has(spec.name)) {
+      throw new AbiError(ERROR_CODES.E_DUP_PLUGIN, `插件 ${spec.name} 已挂载`, { plugin: spec.name })
+    }
+
+    /* 1. validate —— 纯检查，无副作用 */
+    assertCapabilities(spec)
+    for (const impl of spec.implements) {
+      const { definition, errors } = validateInterface(impl)
+      if (!definition) {
+        throw new AbiError(ERROR_CODES.E_KIND_UNKNOWN, `未知接口种类 ${impl.kind}`, { plugin: spec.name, kind: impl.kind })
+      }
+      if (errors.length) {
+        throw new AbiError(ERROR_CODES.E_SCHEMA, `${impl.kind} 描述符非法：${errors.join('；')}`,
+          { plugin: spec.name, kind: impl.kind, errors })
+      }
+      adapterOf(impl.kind)
+    }
+    const batchUniques = claimUniqueness(spec.implements, spec.name, uniques)
+
+    /* 2. compile —— 失败回滚 */
+    const entries = []
+    try {
+      for (const impl of spec.implements) {
+        const adapter = adapterOf(impl.kind)
+        let instance
+        try {
+          instance = adapter.compile(impl, { spec, config, context, log, loader: api })
+        } catch (error) {
+          throw toAbiError(error, ERROR_CODES.E_ADAPTER_THREW, { plugin: spec.name, kind: impl.kind })
+        }
+        entries.push({ impl, instance: instance || {} })
+      }
+    } catch (error) {
+      disposeEntries(entries)
+      throw error
+    }
+
+    /* 3. start —— 异步就绪，失败记录不抛出 */
+    const state = { disposed: false }
+    const ready = startEntries(spec, entries, state)
+
+    /* 4. commit */
+    const ownedProvides = []
+    for (const capability of spec.provides) {
+      provided.set(capability.name, { plugin: spec.name, version: capability.range })
+      ownedProvides.push(capability.name)
+    }
+    for (const [key, owner] of batchUniques) uniques.set(key, owner)
+
+    let disposed = false
+    const handle = {
+      name: spec.name,
+      spec,
+      interfaces: entries.map((entry) => entry.impl.kind),
+      ready,
+      dispose() {
+        if (disposed) return
+        disposed = true
+        state.disposed = true
+        disposeEntries(entries)
+        for (const key of batchUniques.keys()) uniques.delete(key)
+        for (const name of ownedProvides) provided.delete(name)
+        plugins.delete(spec.name)
+      },
+    }
+    plugins.set(spec.name, { spec, entries, handle })
+    return handle
+  }
+
+  function startEntries(spec, entries, state) {
+    const pending = []
+    for (const entry of entries) {
+      if (typeof entry.instance.start !== 'function') continue
+      pending.push(Promise.resolve()
+        .then(() => {
+          if (state.disposed) return undefined
+          return entry.instance.start()
+        })
+        .catch((error) => {
+          const normalized = toAbiError(error, ERROR_CODES.E_ADAPTER_THREW,
+            { plugin: spec.name, kind: entry.impl.kind, phase: 'start' })
+          failures.push(normalized)
+          log?.error?.(`[foundation] ${normalized.message}`)
+        }))
+    }
+    return Promise.all(pending).then(() => undefined)
+  }
+
+  function disposeEntries(entries) {
+    for (const entry of [...entries].reverse()) {
+      try {
+        entry.instance?.dispose?.()
+      } catch (error) {
+        const normalized = toAbiError(error, ERROR_CODES.E_ADAPTER_THREW,
+          { plugin: entry.impl.kind, phase: 'dispose' })
+        failures.push(normalized)
+        log?.error?.(`[foundation] ${normalized.message}`)
+      }
+    }
+    entries.length = 0
+  }
+
+  /** 当前可用的能力版本：内核承诺优先，其次插件提供。 */
+  function capability(name) {
+    return capabilities[name] || provided.get(name)?.version || null
+  }
+
+  /** 未解析的跨插件能力（运行时只报告，组合期才是硬闸）。 */
+  function unresolved() {
+    const out = []
+    for (const { spec } of plugins.values()) {
+      for (const requirement of spec.requires) {
+        if (requirement.name.startsWith('os.')) continue
+        if (provided.has(requirement.name) || capabilities[requirement.name]) continue
+        out.push({ plugin: spec.name, capability: requirement.name, range: requirement.range })
+      }
+    }
+    return out
+  }
+
+  /** 内核状态快照：给 os.report() 与健康检查用。 */
+  function report() {
+    const capabilityView = { ...capabilities }
+    for (const [name, info] of provided) capabilityView[name] = info.version
+    return {
+      abiVersion: abiMajor,
+      plugins: [...plugins.values()].map(({ spec, entries }) => ({
+        name: spec.name,
+        interfaces: entries.map((entry) => entry.impl.kind),
+        requires: spec.requires.map((r) => r.raw),
+        provides: spec.provides.map((p) => p.raw),
+      })),
+      capabilities: capabilityView,
+      unresolved: unresolved(),
+      failures: failures.map((error) => ({ code: error.code, message: error.message, detail: error.detail })),
+    }
+  }
+
+  function disposeAll() {
+    for (const { handle } of [...plugins.values()].reverse()) handle.dispose()
+    plugins.clear()
+    uniques.clear()
+    provided.clear()
+  }
+
+  const api = Object.freeze({
+    mount,
+    report,
+    capability,
+    disposeAll,
+    get size() { return plugins.size },
+  })
+
+  return api
+}

package/abi/schema.mjs

@@ -0,0 +1,98 @@
+/**
+ * 极简 schema 校验器：只覆盖 ABI 描述符需要的子集，不引入依赖。
+ *
+ * 支持的约束：type（含类型数组）/ required / properties / additionalProperties /
+ * items / minItems / enum / pattern / min / max / minLength / maxLength。
+ *
+ * 刻意不做的事：$ref、oneOf/anyOf、format、默认值填充。描述符是代码不是配置文件，
+ * 需要更强表达力时写 `extra()` 校验，而不是把 schema 语言做大。
+ */
+
+const TYPE_CHECKS = {
+  string: (v) => typeof v === 'string',
+  number: (v) => typeof v === 'number' && Number.isFinite(v),
+  integer: (v) => Number.isInteger(v),
+  boolean: (v) => typeof v === 'boolean',
+  object: (v) => v !== null && typeof v === 'object' && !Array.isArray(v),
+  array: (v) => Array.isArray(v),
+  function: (v) => typeof v === 'function',
+}
+
+function describe(value) {
+  if (value === null) return 'null'
+  if (Array.isArray(value)) return 'array'
+  return typeof value
+}
+
+/**
+ * @param {unknown} value
+ * @param {object} schema
+ * @param {string} [path] 出错时的字段路径根
+ * @returns {string[]} 错误列表；空数组表示通过
+ */
+export function validateSchema(value, schema, path = '$') {
+  const errors = []
+  visit(value, schema, path, errors)
+  return errors
+}
+
+function visit(value, schema, path, errors) {
+  if (!schema) return
+
+  if (schema.type !== undefined) {
+    const types = Array.isArray(schema.type) ? schema.type : [schema.type]
+    const known = types.filter((type) => TYPE_CHECKS[type])
+    if (known.length !== types.length) {
+      errors.push(`${path} 的 schema 声明了未知类型 ${types.join('|')}`)
+      return
+    }
+    if (!types.some((type) => TYPE_CHECKS[type](value))) {
+      errors.push(`${path} 应为 ${types.join('|')}，实际 ${describe(value)}`)
+      return
+    }
+  }
+
+  if (typeof value === 'string') {
+    if (schema.minLength !== undefined && value.length < schema.minLength) {
+      errors.push(`${path} 长度不得小于 ${schema.minLength}`)
+    }
+    if (schema.maxLength !== undefined && value.length > schema.maxLength) {
+      errors.push(`${path} 长度不得大于 ${schema.maxLength}`)
+    }
+    if (schema.pattern && !new RegExp(schema.pattern).test(value)) {
+      errors.push(`${path} 不匹配 ${schema.pattern}`)
+    }
+    if (schema.enum && !schema.enum.includes(value)) {
+      errors.push(`${path} 必须是 ${schema.enum.join(' | ')} 之一`)
+    }
+  }
+
+  if (typeof value === 'number') {
+    if (schema.min !== undefined && value < schema.min) errors.push(`${path} 不得小于 ${schema.min}`)
+    if (schema.max !== undefined && value > schema.max) errors.push(`${path} 不得大于 ${schema.max}`)
+  }
+
+  if (Array.isArray(value)) {
+    if (schema.minItems !== undefined && value.length < schema.minItems) {
+      errors.push(`${path} 至少需要 ${schema.minItems} 项`)
+    }
+    if (schema.items) {
+      value.forEach((item, index) => visit(item, schema.items, `${path}[${index}]`, errors))
+    }
+  }
+
+  if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+    const props = schema.properties || {}
+    for (const key of schema.required || []) {
+      if (value[key] === undefined) errors.push(`${path}.${key} 必填`)
+    }
+    if (schema.additionalProperties === false) {
+      for (const key of Object.keys(value)) {
+        if (!(key in props)) errors.push(`${path}.${key} 未知字段`)
+      }
+    }
+    for (const [key, sub] of Object.entries(props)) {
+      if (value[key] !== undefined) visit(value[key], sub, `${path}.${key}`, errors)
+    }
+  }
+}