Basalt

Basalt（玄武岩）是基于 Bun 与严格 TypeScript 构建的本地优先、可扩展 AI 工程代理运行时与 Web 工作台。

它采用 启动即服务（Launch-as-a-Server） 与 微内核 + 全栈插件（Microkernel & Full-stack Plugins） 架构：服务直接运行在本地开发机上，具备完整的文件系统、Shell 进程、隔离浏览器与 MCP（Model Context Protocol）访问能力；前端工作台既可由单文件可执行程序直接内嵌提供，也可独立部署并通过一次性配对码与本地服务建立受保护的 HTTP / WebSocket 连接。

核心特性

• 单文件分发，启动即服务：可编译为内嵌 Web 工作台的零依赖单文件可执行程序；服务在本地运行并直连开发机环境，支持通过终端二维码或一次性配对码从桌面、手机或远程浏览器跨设备安全接入。
• 微内核与热插拔全栈插件：核心仅保留会话、存储与工具调度原语；17 个内置模块与自定义扩展共享同一套插件 SDK，支持后端路由、生命周期钩子与前端动态视图不停机热重载，并可在对话中直接编写、测试与加载新插件。
• 完备的工程代理工具链：原生提供文件并发读取与批量精确编辑、会话级后台进程管理与流式日志监控、受控隔离浏览器自动化（快照、交互、调试、截图）、联网搜索抓取，以及 MCP 与 Skills 生态无缝接入。
• 多代理协作与长周期自治：支持创建跨模型子代理任务并控制上下文继承策略；结合持久目标与预算控制（Goal）、延时自唤醒（Wake）与 Cron 定时任务（Automations），可独立推进跨阶段、长耗时的工程与运维工作。
• 长程上下文压缩与透视工作台：自动对超长对话执行分层封存与摘要折叠，在保持模型缓存高命中率的同时支持随时检索折叠原文；配套 React 19 工作台支持会话任意节点分叉重放、实时上下文构成透视、用量统计与多协议模型热切换。

系统架构与工作区

Basalt 采用 Bun Workspaces 管理的单仓多包（Monorepo）结构，严格约束包边界与单向依赖流向：

cli ──► builtins ──► plugin ──► core ──► protocol
 │         ▲           ▲         ▲          ▲
 │         └───────────┼─────────┼──────────┤
 └────────► server ────┼─────────┘          │
              │        │                    │
              ▼        │                    │
             web ──────┴────────────────────┘

工作区包一览

内置插件模块

@basalt/builtins 中的所有模块均通过标准 PluginHost 装配，可在 Web 设置中心或通过管理 API 独立启用、禁用、查看状态或热重载：

快速开始

全局安装

通过 npm 或 Bun 全局安装预构建、零外部依赖的 @bkm016/basalt（约 4 MB，内嵌完整 Web 工作台）：

# 通过 npm 全局安装（推荐，若本机尚未安装 Bun 会在首次启动时自动按需下载运行时）
npm i -g @bkm016/basalt

# 或使用 Bun 全局安装
bun i -g @bkm016/basalt

# 后台启动并打开工作台（就绪后命令返回，服务继续运行）
basalt --open

# 提示 command not found 时（Bun 的全局 bin 目录不在 PATH），先用完整路径运行一次 setup，再重开终端
~/.bun/bin/basalt setup

升级：服务运行时每 6 小时查一次 npm 上的最新版本，按安装方式自动用 npm 或 bun 全局安装，并等所有对话空闲后按原参数重启，不会打断进行中的对话。也可以手动更新，运行中的服务同样会在空闲时切换到新版本：

basalt update
# 或直接用包管理器
npm i -g @bkm016/basalt@latest
bun add -g @bkm016/basalt@latest

从源码运行

需要安装 Bun >= 1.4.0：

bun install
bun run dev                            # 启动开发服务器（支持热重载）
bun packages/cli/src/main.ts --demo --open  # 无需 API Key，使用内置演示模型体验工作台

配对与首次使用

1. 首次启动建议使用 basalt --open，服务就绪后会自动在浏览器中打开带配对链接的工作台。未使用 --open 或配对码已过期时，在服务所在机器上运行 basalt pair，即可生成 10 分钟有效的一次性配对码及配对链接。
2. 首次进入工作台若尚未配置模型，界面会引导前往「设置 → 模型」添加服务商与 API Key。

远程访问（Cloudflare 隧道）

用自己域名下的固定主机名，从手机或另一台电脑访问这台机器上的 Basalt。前提：域名托管在 Cloudflare，本机装好 cloudflared。

在工作台 设置 → 远程访问 里按向导走，全程不用进 Cloudflare 后台：

1. 连接 Cloudflare 账号：点「连接 Cloudflare」，Basalt 会给出一个授权链接。在浏览器（手机也行）里打开它，登录并选择你的域名，点授权。完成后页面自动继续。
2. 选一个访问地址：填该域名下的子域名，如 basalt.example.com。
3. 创建并连接：Basalt 通过 cloudflared 自动创建隧道、添加域名解析、写好转发配置并连接。

之后每次启动 basalt 都会自动带起隧道，随 Basalt 退出而退出，掉线自动重连；终端里的配对二维码和链接改用 https://basalt.example.com。授权证书和隧道凭据保存在数据目录的 cloudflared/ 下，不会写进你自己的 ~/.cloudflared。

已经在 Cloudflare 后台建好隧道的人，向导里点「我已有隧道令牌」，把后台给出的安装命令整段粘贴进来即可（也可用命令行：BASALT_TUNNEL_TOKEN=<令牌> basalt tunnel set basalt.example.com；basalt tunnel status / basalt tunnel off 查看或删除）。令牌模式下，隧道的服务地址要在 Cloudflare 里填 http://localhost:<端口>，设置页会显示端口。

可选：Cloudflare Access（再加一道只认你的登录）

配好之后在同一页的「Access 校验」点「配置引导」，再点弹窗里的链接直达你账号的 Cloudflare 应用程序页（账号 ID 从登录证书自动读出，令牌模式则先进入 Zero Trust）。点右上角「新建应用程序」，选「自托管和私有」、保持「公共 DNS」，点「继续使用」；「子域」填子域名（如 micode）、「域」下拉选根域（如 taboo.sh），路径留空；在「Access 策略」里点「创建新策略」，选「允许」、按「电子邮件」填你的邮箱；只允许指定 GitHub 用户时，再在「要求」里加「登录方法 = GitHub」，并在「身份验证」里关闭「接受所有可用的标识提供程序」、只选 GitHub（「应用即时身份验证」开启后会直接跳 GitHub），然后点「创建」；最后到应用的「其他设置」→「AUD 标签」，复制「令牌」下的字符串，回到 Basalt 点「设置」粘贴，团队域名会自动识别。之后经隧道进来的请求必须带 Cloudflare 签发的有效 JWT，否则被直接拒绝。

安全说明

• 配置了远程访问就不能用 --no-auth 启动，设置页也会拒绝在免认证服务上开启。
• 配了 Access 后，Basalt 会校验 Cloudflare 签发的 Cf-Access-Jwt-Assertion（签名、颁发者、Audience、有效期；公钥取自团队域名的 /cdn-cgi/access/certs）：经隧道进来且没有合法凭据的请求会被直接 403，即使 Access 策略被误改成放行也不会只剩 Basalt 自己的令牌守着公网。本机直连不受影响。
• 直接用 https://你的主机名 打开时，页面与 API 同源，无需额外设置。若用 basalt.work 等其他网址连接，需要在 Access 应用里为跨域请求开启「Bypass OPTIONS」，并在添加服务器时填写服务令牌请求头（CF-Access-Client-Id / CF-Access-Client-Secret）。
• 远程设备只能用终端里的配对码配对；「本机免码授权」对经隧道的请求不可用。

命令行与配置参考

CLI 选项

用法: basalt [选项]                       后台启动服务，就绪后返回
      basalt status                         查看服务状态
      basalt stop                           停止服务
      basalt restart                        按原参数重启服务
      basalt logs                           查看最近后台日志
      basalt pair                           为运行中的服务生成新配对码和配对链接
      basalt autostart <enable|disable|status> 管理登录自启
      basalt update                         用安装时的 npm/bun 更新到最新版本（运行中的服务空闲时自动重启）
      basalt setup                          把 basalt 所在目录加入 PATH（装完提示找不到命令时用）
      basalt plugin reload <id> [--data <目录>]
      basalt tunnel set <主机名> [--token <令牌>] [--aud <Audience> [--team <团队域名>]]
      basalt tunnel off | status             远程访问（Cloudflare 隧道）

选项:
  --host <地址>          监听地址（默认 127.0.0.1，仅本机回环）
  --port <端口>          监听端口（默认 7420）
  --open                 启动后在浏览器里打开工作台（带配对链接）
  --foreground           在前台运行服务，供调试、launchd 和 systemd 使用
  --replace              已有实例在运行时先停止旧实例再启动
  --model <provider/id>  指定启动时默认使用的模型（如 anthropic/claude-sonnet-4-20250514）
  --demo                 启用内置演示模型（demo/echo，无需 API Key）
  --data <目录>          指定运行时数据目录（默认遵循平台规范或 BASALT_HOME）
  --web-url <地址>       生成配对链接时使用的外部 Web 工作台地址
  --allow-origin <来源>  允许跨域访问的 Web 来源，可多次传入；* 表示允许任意来源
  --token <令牌>         tunnel set 用：隧道令牌（更推荐用环境变量，避免进 shell 历史）
  --aud <Audience>       tunnel set 用：Access 应用的 Audience 标签
  --team <团队域名>      tunnel set 用：Access 团队域名（不填按公共域名的登录跳转自动探测）
  --no-tray              不启动系统托盘图标
  --no-update-check      不自动检查和安装新版本（也可设 BASALT_NO_UPDATE_CHECK=1）
  --no-auth              关闭令牌认证（仅本机监听可用，或需配合 --allow-remote-no-auth）
  --insecure-http        允许在非本机回环地址上使用明文 HTTP 监听
  --allow-remote-no-auth 允许在非本机回环地址上关闭认证（极不安全，仅限受控隔离环境）
  -v, --version          显示版本
  -h, --help             显示帮助信息

默认 basalt 会在后台启动服务，等待 HTTP 就绪后返回终端；需要查看实时输出或由服务管理器托管时使用 --foreground。basalt restart 沿用当前实例的参数和工作目录，basalt logs 读取最近 256 KB 后台日志。

执行一次 basalt autostart enable 即可注册当前用户的登录自启：Windows 使用隐藏启动脚本，macOS 使用 LaunchAgent，Linux 使用 systemd 用户服务。启动项固定当前 Bun/npm 包入口，登录时不会联网安装或升级；disable 关闭自启，status 查看配置。启用时会沿用正在运行实例的参数，不会改变或重启当前服务。

自启只保存启动参数、数据目录和工作目录，不复制当前终端的环境变量。只在交互式 shell 中设置的 API Key、BASALT_MODEL 等变量不会自动带入登录会话；请在 Web 中配置模型，或把所需变量配置到系统用户环境。

环境变量

数据目录与存储布局

未指定 --data 与 BASALT_HOME 时，Basalt 按操作系统惯例存放运行时数据：

• Windows：%LOCALAPPDATA%\basalt（或 ~\AppData\Local\basalt）
• macOS：~/Library/Application Support/basalt
• Linux / BSD：$XDG_DATA_HOME/basalt（或 ~/.local/share/basalt）

数据目录内核心文件结构：

<dataDir>/
├── basalt.db        # 主 SQLite 数据库（会话、只追加条目日志、项目、插件迁移与 KV 存储）
├── search.db        # 独立 Worker 维护的会话历史全文检索索引库
├── models.json      # Web 端配置的自定义模型提供商与脱敏凭据持久化文件
├── devices.json     # 已配对设备的元数据与令牌 SHA-256 哈希记录
├── basalt.log       # 后台服务标准输出与错误日志
├── server.json      # 单实例运行锁文件（记录当前活动服务的 PID、监听 URL 与托盘句柄）
└── plugins/         # 用户级自定义插件目录（支持 <id>.ts 或 <id>/index.ts）

插件开发

Basalt 支持在用户数据目录 <dataDir>/plugins/ 或项目工作区 <project>/.basalt/plugins/ 下编写进程内、完全信任的 Bun TypeScript 全栈插件。

最小服务端插件示例

创建 <dataDir>/plugins/hello.ts：

import { definePlugin, Type, text, tool } from "@basalt/plugin"

export default definePlugin({
  id: "hello",
  name: "Hello Plugin",
  description: "最小工具与生命周期扩展示例",
  version: "1.0.0",
  apiVersion: 1,
  setup(b) {
    // 1. 注册供模型调用的工具
    b.registerTool(
      tool({
        name: "hello_greet",
        label: "问候",
        description: "向指定对象返回问候消息",
        parameters: Type.Object({
          target: Type.String({ minLength: 1 }),
        }),
        async execute(_callID, { target }) {
          return text(`你好，${target}！`)
        },
      }),
    )

    // 2. 注册自定义 HTTP 路由（自动复用宿主来源检查与令牌认证）
    b.registerRoute({
      method: "GET",
      path: "/api/plugins/hello/status",
      handler() {
        const recentSessions = b.sessions.list({ limit: 5 })
        return Response.json({ ok: true, recentCount: recentSessions.length })
      },
    })
  },
})

保存后可通过以下任一方式热重载插件，无需重启服务进程：

basalt plugin reload hello

或在 Web 工作台的「设置 → 插件」页面中点击重载。关于同目录 web.tsx 动态前端模块（Sidebar / Page / Tab / Card / Slot）、SQL 迁移、条目 Hook（entry.before_append / entry.after_append）与代际租约的完整契约，请参阅 插件 SDK 文档 与 宿主架构设计。

构建、验证与开发脚本

在仓库根目录下执行以下命令进行日常开发、质量检查与生产构建：

如需交叉编译单文件可执行程序，可直接向构建脚本传入 --target 参数：

bun scripts/build.ts cli --target=bun-windows-x64
bun scripts/build.ts cli --target=bun-darwin-arm64
bun scripts/build.ts cli --target=bun-linux-x64

版本发布

更新 packages/cli/package.json 中的 version 字段并推送至 main 分支，GitHub Actions 检测到 @bkm016/basalt 的该版本尚未发布到 npm 时，将自动构建 npm 包并发布（需在仓库机密中配置 NPM_TOKEN；包含 - 的版本号如 0.2.0-beta.1 将发布到 next 标签，不进入 latest）。

工程文档索引

• 架构设计：宿主与功能插件边界
• 插件 SDK 与生命周期契约
• Web 工作台视觉与组件设计规范
• 上下文透视侧栏设计说明
• 网络抓取与搜索插件配置说明
• 隔离浏览器插件架构说明
• 工程协作与代码规范