@visiblebase/base

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

它负责这些共用能力：

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

安装

pnpm add @visiblebase/base

需要 Node >=22.13.0。

最小示例

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

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/base";

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/base";
import { authPlugin } from "@visiblebase/plugin-auth";
import { usagePlugin } from "@visiblebase/plugin-usage";
import { stripePaymentPlugin } from "@visiblebase/plugin-payment-stripe";

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

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

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

插件路由按鉴权模式挂载：

auth: "public" 和 auth: "user"：/v1/plugins/{pluginId}/{path}
auth: "admin"：/api/admin/plugins/{pluginId}/{path}

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

文档

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

@visiblebase/core

Package Exports

Readme

@visiblebase/base

安装

最小示例

主要导出

业务表

插件

文档