@visiblebase/core

@visiblebase/core 是 VisibleBase 的服务端运行时内核。

它负责这些共用能力：

挂载 Service / Plugin / AIService
初始化内置 products / env 表
校验 user_token 和 admin_secret_key
暴露统一的 /v1/* HTTP 路由
提供 env、数据库、hook 和鉴权上下文

安装

pnpm add @visiblebase/core

通常与 @visiblebase/node 一起使用：

pnpm add @visiblebase/core @visiblebase/node

最小示例

import { Base, AIService } from "@visiblebase/core";
import { node } from "@visiblebase/node";

const runtime = node({ database: "sqlite:./data.sqlite" });
const base = new Base({ runtime });

const ai = new AIService();
ai.use({
  id: "local-echo",
  name: "Local Echo",
  default: ["text"],
  actions: {
    text: async (ctx) => ({
      id: crypto.randomUUID(),
      role: "assistant",
      parts: [
        {
          type: "text",
          text: String(ctx.input.prompt ?? ""),
          state: "done",
        },
      ],
    }),
  },
});

base.use(ai);

启动 HTTP 服务：

import { serve } from "@hono/node-server";

await base.health();
serve({ fetch: base.router().fetch, port: 43127, hostname: "127.0.0.1" });

Service

Service 是一组 Action 的容器：

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

const notes = new Service({ id: "notes", name: "Notes" });

notes.action("create", async (ctx) => {
  return {
    ok: true,
    title: String(ctx.input.title ?? ""),
  };
});

notes.action("list", async () => {
  return { items: [] };
}, { method: "GET", auth: ["admin"] });

base.use(notes);

Base 会自动映射为：

POST /v1/notes/create
GET /v1/notes/list

AIService

AIService 负责模型目录和模态路由：

import { AIService, Provider } from "@visiblebase/core";

const deepseek = new Provider("deepseek", {
  baseURL: "https://api.deepseek.com/v1",
  envKey: "DEEPSEEK_API_KEY",
  text: myTextAction,
  stream: myStreamAction,
});

const ai = new AIService();
ai.use(
  deepseek.model({
    id: "deepseek-v4-flash",
    name: "DeepSeek V4 Flash",
    default: ["text", "stream"],
  }),
);

base.use(ai);

Plugin

插件用于封装多产品复用能力：

import { accountsPlugin } from "@visiblebase/plugin-accounts";
import { usagePlugin } from "@visiblebase/plugin-usage";

base.use(accountsPlugin());
base.use(usagePlugin());

插件路由当前只支持：

GET
POST

鉴权语义

默认 action 需要 user_token
auth: ["admin"] 只允许 admin_secret_key
auth: [] 表示免登录

对于用户侧请求，user_token 绑定 product 身份。如果请求体或 query 中传了 product_id，它必须与 token 里的 product 一致。

主要导出

Base
VisibleBase
Service
Plugin
AIService
Provider
TokenSigner
EnvService
ProductsService

文档

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