@visiblebase/core

@visiblebase/core 是 VisibleBase 的服务端 Runtime。

它负责这些共用能力：

• 初始化默认 Runtime 数据库 products
• 校验 user_token
• 提供 Fetch 风格 HTTP handler
• 管理 Runtime .env
• 用 base.model(meta).handle() 注册场景模型和执行 handler

安装

pnpm add @visiblebase/core

需要 Node >=22.13.0。

最小示例

import { Base } from "@visiblebase/core";

const base = new Base();

base.model({
  id: "local-echo",
  name: "Local Echo",
  default: ["text"],
}).handle({
  text: async (ctx) => ({
    id: crypto.randomUUID(),
    role: "assistant",
    parts: [
      {
        type: "text",
        text: `echo: ${ctx.input.prompt}`,
        state: "done",
      },
    ],
  }),
});

const server = await base.serve({
  host: "127.0.0.1",
  port: 3001,
});

console.log(`VisibleBase listening on http://${server.host}:${server.port}`);

这段代码不要求你自己打开 SQLite 或手写 visiblebase_models。client.models() 读取的是 base.model(meta).handle() 注册出来的运行时目录。

默认情况下，Base 会在第一次 serve()、handleRequest()、models()、invoke() 或 table() 操作时自动初始化。常规使用不需要手动调用 init()。

主要导出

• Base
• VisibleBase
• 模型类型：ModelMeta、ModelHandlers、RuntimeModel
• 插件类型：BasePlugin、BasePluginRoute、BasePluginContext
• 默认数据库 schema：sqliteProducts、pgProducts
• DotenvRuntimeEnv

业务表

业务表通过 new Base({ schema }) 注册，然后用 base.table(name) 操作：

import { sqliteTable, text } from "drizzle-orm/sqlite-core";
import { Base } from "@visiblebase/core";

const notes = sqliteTable("notes", {
  id: text("id").primaryKey(),
  title: text("title").notNull(),
});

const base = new Base({
  schema: {
    notes,
  },
});

await base.table("notes").insert({
  id: "note_1",
  title: "First note",
});

const rows = await base.table("notes").select();

插件

插件用于把多个 client 产品会复用的 Base 能力封装起来，例如用户注册登录、支付、订阅权益、usage 扣费或通知。

import { Base } from "@visiblebase/core";
import { accountsPlugin } from "@visiblebase/plugin-accounts";
import { usagePlugin } from "@visiblebase/plugin-usage";
import { stripePaymentPlugin } from "@visiblebase/plugin-payment-stripe";

const base = new Base({
  plugins: [
    accountsPlugin(),
    usagePlugin(),
    stripePaymentPlugin(),
  ],
});

Base 使用者不需要为官方插件定义数据库表。插件包内部会声明自己的表，Base 在首次运行时自动创建。

models 和 products 也是默认内置插件。你不传 plugins 时，Base 会自动启用它们；你传入其他插件时，它们仍然保留；如果你传入同 ID 的 models 或 products 插件，则会替换默认实现。

插件路由统一挂到同一个 /v1/{pluginId}/{path} 空间。

• auth 不传：默认要求 user
• auth: ["admin"]：只允许 admin
• auth: []：免登录

如果你在开发插件，插件可以声明自己的 schema，并通过 ctx.table(name) 读写插件表；也可以通过 ctx.hook.before()、ctx.hook.after() 和 ctx.hook.onError() 介入 service 调用。

文档

• 仓库首页：visiblebase
• 文档目录：homepage/content/docs