# @bkm016/basalt 中文文档 规范地址：https://npmcn.com/package/%40bkm016/basalt/ 版本：0\.1\.29 npm 元数据更新时间：2026-11-07T19:34:05.330Z 中文译文更新时间：2026-11-08T05:29:43.366Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40bkm016/basalt 原文对照：https://npmcn.com/package/%40bkm016/basalt/?lang=original 项目主页：https://github.com/Bkm016/Basalt#readme 源码仓库：https://github.com/Bkm016/Basalt ## 关键信息（来自 npm 元数据） - 包体积（解压后）：21 MB，592 个文件 - 模块格式：ES Module - TypeScript 类型：未声明 - Node.js 要求：\>=18\.0\.0 - 运行依赖：0 个 - 首次发布：2026-10-23T15:04:25.426Z - 最新版本发布：2026-11-07T19:34:05.188Z - 近 30 天下载量：5100（2026-10-08 至 2026-11-06，npm 官方下载统计） - 已发布版本数：31（近 12 个月 31 个） ## 中文简介 本地首个AI软件工程代理运行时间和网络工作台 ## 安装 ```sh npm install @bkm016/basalt ``` 也可以使用：`pnpm add @bkm016/basalt`、`yarn add @bkm016/basalt`、`bun add @bkm016/basalt` ## README ![Basalt](https://npmcn.com/package/%40bkm016/basalt/packages/web/src/assets/icon.svg) # Basalt Basalt（玄武岩）是基于 [Bun](https://bun.sh/) 与严格 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）结构，严格约束包边界与单向依赖流向： ```text cli ──► builtins ──► plugin ──► core ──► protocol │ ▲ ▲ ▲ ▲ │ └───────────┼─────────┼──────────┤ └────────► server ────┼─────────┘ │ │ │ │ ▼ │ │ web ──────┴────────────────────┘ ``` ### 工作区包一览 | 包名 | 路径 | 职责说明 | | :-- | :-- | :-- | | `@basalt/protocol` | `packages/protocol` | 跨进程、服务端与 Web 客户端共享的唯一线协议（`PROTOCOL_VERSION = 4`）、消息契约与数据类型，零运行时与平台依赖。 | | `@basalt/core` | `packages/core` | 核心领域运行时（`Runtime`）、会话生命周期（`Session`）、SQLite 存储（`Store`）、上下文投影与折叠引擎（`Projection`）、全文搜索服务（`SearchService`）及插件宿主（`PluginHost`）。 | | `@basalt/plugin` | `packages/plugin` | 插件开发 SDK，导出 `definePlugin`、工具构造器、生命周期与条目 Hook 类型，以及供前端动态模块使用的 `@basalt/plugin/web` 桥接契约。 | | `@basalt/builtins` | `packages/builtins` | 基于 `@basalt/plugin` 实现的 17 个随包内置功能插件（含服务端逻辑、独立协议与配套 Web 视图），彼此之间零实现导入耦合。 | | `@basalt/server` | `packages/server` | 基于 `Bun.serve` 与 `Hono` 的 HTTP API（`/api/*`）、增量同步 WebSocket（`/api/ws`）、设备配对与令牌鉴权（`Auth`）及模型提供商管理（`ModelProviderManager`）。 | | `@basalt/web` | `packages/web` | React 19 前端工作台，包含设计令牌系统、通用 UI 原语（Radix UI + Motion）、会话流式视图、Shiki 按需语法高亮、Mermaid/KaTeX 渲染与插件动态视图插槽。 | | `@basalt/cli` | `packages/cli` | 命令行入口（`basalt`）、单实例进程锁管理、Windows 系统托盘集成、终端二维码配对引导及单文件可执行程序编译入口。 | * * * ## 内置插件模块 `@basalt/builtins` 中的所有模块均通过标准 `PluginHost` 装配，可在 Web 设置中心或通过管理 API 独立启用、禁用、查看状态或热重载： | 插件 ID | 名称 | 核心职责与提供能力 | | :-- | :-- | :-- | | `agents` | 子代理委派 | 提供 `task` / `task_job` 工具与子任务卡片视图；管理子会话生命周期、`readonly` 工具授权策略、跨会话历史引用与完成通知。 | | `automations` | 自动化 | 支持按 Cron 表达式与服务器时区定时启动项目会话自动执行任务，提供独立的自动化管理页面。 | | `basalt-creator` | Basalt Creator | 提供 `basalt_plugin` 工具与内嵌开发文档，支持在会话中创建、静态校验（`check`/`verify`）、无头 UI 测试（`ui_test`）及热加载用户插件。 | | `bash` | 进程与监控 | 提供 `bash`、`bash_job` 与 `monitor` 工具及后台任务卡片视图，管理会话级后台进程池、交互式标准输入与流式输出正则监控通知。 | | `browser` | 浏览器 | 提供 8 个延迟加载的 `browser_*` 工具，管理按会话/项目隔离的受控浏览器实例、可访问性树快照与端到端页面验证。 | | `computer-use` | 控制电脑 | 仅 Windows：提供延迟加载的 `computer_use` 工具与配套 `computer-use` 技能，通过已安装的 Codex 桌面端 helper 操作本机应用；操作应用前弹出授权（允许本次 / 本会话始终允许 / 拒绝），选择始终允许后本会话内所有应用都不再弹窗。 | | `context` | 上下文透视 | 提供 `GET /api/sessions/:id/context` 快照路由与右侧上下文透视面板（展示系统提示词分段、封存/折叠块、可用工具 Schema、待办与原始消息）。 | | `goal` | 持久目标 | 提供 `goal_create` / `goal_get` / `goal_update` 工具与目标状态栏，支持会话级长周期目标追踪、Token 预算控制、耗时统计与自动续跑审计。 | | `imagegen` | 图像生成 | 提供 `image_generation` 延迟工具与配套 `imagegen` 技能指南，支持文生图与基于参考图的视觉编辑。 | | `markdown-graph` | 图表渲染 | 将回复中的 `mermaid` 代码块实时渲染为流程图/时序图，将 `echarts` 代码块渲染为交互式数据图表。 | | `mcp` | MCP 集成 | 管理全局与项目级（`.mcp.json`）Model Context Protocol 服务器连接、OAuth 认证、工具快照同步及设置页管理视图；模型可经内置 `basalt_mcp` 工具直接安装与运维服务器。 | | `prompt-optimizer` | 提示词优化 | 在输入框提供草稿澄清与优化能力，使用显式选择的模型在独立请求中改写提示词，不污染当前会话历史。 | | `question` | 交互提问 | 提供主会话 `question` 工具、输入等待闸门（`waiting_user`）与交互式提问面板，支持单选、多选与自定义补充回答。 | | `session-ops` | 会话操作 | 提供会话复制（`duplicate`）、任意序号分叉（`fork`）、历史消息编辑（`edit`）与破坏性重放（`replay`）路由、命令及确认交互。 | | `skills` | 技能系统 | 扫描并管理全局与项目级技能目录（`SKILL.md`），提供 `skill` 按需加载工具、确定性系统提示词片段注入与设置页开关。 | | `stats` | 统计分析 | 提供一级统计分析页面，聚合全局、各项目与每日的运行耗时、Token 消耗、缓存命中率、模型吞吐量与工具调用分布。 | | `wake` | 定时唤醒 | 提供会话内 `wake` 工具（`set` / `list` / `cancel`），支持基于追加日志持久化的延时自唤醒通知，服务重启后自动恢复与补投。 | | `webfetch` | 网络访问 | 提供延迟加载的 `webfetch`（网页抓取转 Markdown/Text/HTML 及图片提取）与 `websearch`（多渠道联网搜索与回退）工具及配置测试页。 | * * * ## 快速开始 ### 全局安装 通过 npm 或 Bun 全局安装预构建、零外部依赖的 [`@bkm016/basalt`](https://www.npmjs.com/package/@bkm016/basalt)（约 4 MB，内嵌完整 Web 工作台）： ```bash # 通过 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 全局安装，并等所有对话空闲后按原参数重启，不会打断进行中的对话。也可以手动更新，运行中的服务同样会在空闲时切换到新版本： ```bash basalt update # 或直接用包管理器 npm i -g @bkm016/basalt@latest bun add -g @bkm016/basalt@latest ``` ### 从源码运行 需要安装 [Bun](https://bun.sh/) `>= 1.4.0`： ```bash 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`](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/)。 在工作台 **设置 → 远程访问** 里按向导走，全程不用进 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 选项 ```text 用法: basalt [选项] 后台启动服务，就绪后返回 basalt status 查看服务状态 basalt stop 停止服务 basalt restart 按原参数重启服务 basalt logs 查看最近后台日志 basalt pair 为运行中的服务生成新配对码和配对链接 basalt autostart 管理登录自启 basalt update 用安装时的 npm/bun 更新到最新版本（运行中的服务空闲时自动重启） basalt setup 把 basalt 所在目录加入 PATH（装完提示找不到命令时用） basalt plugin reload [--data <目录>] basalt tunnel set <主机名> [--token <令牌>] [--aud [--team <团队域名>]] basalt tunnel off | status 远程访问（Cloudflare 隧道） 选项: --host <地址> 监听地址（默认 127.0.0.1，仅本机回环） --port <端口> 监听端口（默认 7420） --open 启动后在浏览器里打开工作台（带配对链接） --foreground 在前台运行服务，供调试、launchd 和 systemd 使用 --replace 已有实例在运行时先停止旧实例再启动 --model 指定启动时默认使用的模型（如 anthropic/claude-sonnet-4-20250514） --demo 启用内置演示模型（demo/echo，无需 API Key） --data <目录> 指定运行时数据目录（默认遵循平台规范或 BASALT_HOME） --web-url <地址> 生成配对链接时使用的外部 Web 工作台地址 --allow-origin <来源> 允许跨域访问的 Web 来源，可多次传入；* 表示允许任意来源 --token <令牌> tunnel set 用：隧道令牌（更推荐用环境变量，避免进 shell 历史） --aud 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 中配置模型，或把所需变量配置到系统用户环境。 ### 环境变量 | 环境变量 | 说明 | | :-- | :-- | | `BASALT_HOME` | 显式指定 Basalt 数据根目录，优先级高于平台默认路径。 | | `BASALT_MODEL` | 默认启动模型标识符（格式为 `/`），命令行 `--model` 优先级高于此变量。 | | `BASALT_TOKEN` | 执行 `basalt plugin reload ` 等 CLI 进程外管理命令时，用于向已开启认证的运行中服务提供设备令牌。 | | `BASALT_TUNNEL_TOKEN` | `basalt tunnel set` 读取的 Cloudflare 隧道令牌，等价于 `--token`。 | | `BASALT_NO_UPDATE_CHECK` | 设为 `1` 时禁用后台自动检查与安装新版本；手动装好的新版本仍会在对话空闲时生效。 | | `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` 等 | 供显式指定的 pi 内置模型解析凭据；对应 provider 不会自动进入 Basalt 模型列表。 | ### 数据目录与存储布局 未指定 `--data` 与 `BASALT_HOME` 时，Basalt 按操作系统惯例存放运行时数据： - **Windows**：`%LOCALAPPDATA%\basalt`（或 `~\AppData\Local\basalt`） - **macOS**：`~/Library/Application Support/basalt` - **Linux / BSD**：`$XDG_DATA_HOME/basalt`（或 `~/.local/share/basalt`） 数据目录内核心文件结构： ```text / ├── basalt.db # 主 SQLite 数据库（会话、只追加条目日志、项目、插件迁移与 KV 存储） ├── search.db # 独立 Worker 维护的会话历史全文检索索引库 ├── models.json # Web 端配置的自定义模型提供商与脱敏凭据持久化文件 ├── devices.json # 已配对设备的元数据与令牌 SHA-256 哈希记录 ├── basalt.log # 后台服务标准输出与错误日志 ├── server.json # 单实例运行锁文件（记录当前活动服务的 PID、监听 URL 与托盘句柄） └── plugins/ # 用户级自定义插件目录（支持 .ts 或 /index.ts） ``` * * * ## 插件开发 Basalt 支持在用户数据目录 `/plugins/` 或项目工作区 `/.basalt/plugins/` 下编写进程内、完全信任的 Bun TypeScript 全栈插件。 ### 最小服务端插件示例 创建 `/plugins/hello.ts`： ```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 }) }, }) }, }) ``` 保存后可通过以下任一方式热重载插件，无需重启服务进程： ```bash basalt plugin reload hello ``` 或在 Web 工作台的「设置 → 插件」页面中点击重载。关于同目录 `web.tsx` 动态前端模块（Sidebar / Page / Tab / Card / Slot）、SQL 迁移、条目 Hook（`entry.before_append` / `entry.after_append`）与代际租约的完整契约，请参阅 [插件 SDK 文档](https://npmcn.com/package/%40bkm016/basalt/packages/plugin/README.md) 与 [宿主架构设计](https://npmcn.com/package/%40bkm016/basalt/DESIGN.md)。 * * * ## 构建、验证与开发脚本 在仓库根目录下执行以下命令进行日常开发、质量检查与生产构建： | 命令 | 说明 | | :-- | :-- | | `bun run dev` | 以守护模式启动本地 CLI 与内嵌 Web 服务：监听源码变更，重启前先整包预检，预检失败时保持当前服务运行不退出。 | | `bun test` | 运行所有工作区包的单元与集成测试套件。 | | `bun run typecheck` | 使用 `tsgo` 对所有工作区包执行严格 TypeScript 类型检查。 | | `bun run lint` | 使用 Biome 检查全仓代码规范、导入排序与格式一致性。 | | `bun run format` | 使用 Biome 自动格式化全仓代码。 | | `bun run build` | 编译内嵌完整 Web 前端资源的单文件可执行程序，产物位于 `packages/cli/dist/basalt`（Windows 下为 `basalt.exe`）。 | | `bun run build:web` | 构建可独立部署（如 Vercel）的静态 Web 工作台与 PWA 资产，产物位于 `packages/web/dist`（Shiki 语言包自动按需分块）。 | | `bun run build:npm` | 构建自包含、零外部依赖的 npm 发布包（含预构建 Web 静态目录与 Node/Bun 双运行时引导入口），产物位于 `packages/cli/dist/npm`。 | 如需交叉编译单文件可执行程序，可直接向构建脚本传入 `--target` 参数： ```bash 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`）。 * * * ## 工程文档索引 - [架构设计：宿主与功能插件边界](https://npmcn.com/package/%40bkm016/basalt/DESIGN.md) - [插件 SDK 与生命周期契约](https://npmcn.com/package/%40bkm016/basalt/packages/plugin/README.md) - [Web 工作台视觉与组件设计规范](https://npmcn.com/package/%40bkm016/basalt/packages/web/DESIGN.md) - [上下文透视侧栏设计说明](https://npmcn.com/package/%40bkm016/basalt/packages/web/CONTEXT-SIDEBAR.md) - [网络抓取与搜索插件配置说明](https://npmcn.com/package/%40bkm016/basalt/packages/builtins/src/webfetch/README.md) - [隔离浏览器插件架构说明](https://npmcn.com/package/%40bkm016/basalt/packages/builtins/src/browser/README.md) - [工程协作与代码规范](https://npmcn.com/package/%40bkm016/basalt/AGENTS.md) ## 常见问题 ### @bkm016/basalt 是什么？ 本地首个AI软件工程代理运行时间和网络工作台 ### 如何安装 @bkm016/basalt？ 在项目目录运行 npm install @bkm016/basalt，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 basalt，可以用 npx basalt 直接运行。 ### @bkm016/basalt 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/bkm016\_\_basalt 是否存在。 ### @bkm016/basalt 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @bkm016/basalt 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @bkm016/basalt 可以商用吗？ @bkm016/basalt 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @bkm016/basalt 的下载量有多少？ 根据 npm 官方下载统计，@bkm016/basalt 在 2026/10/08 – 2026/11/06 这 30 天内被下载 5,100 次，日均约 170 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @bkm016/basalt 还在维护吗？ 最新版本 0\.1\.29 发布于 2026/11/08（今天）；至今共发布 31 个版本，其中过去 12 个月发布了 31 个；首次发布于 2026/10/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。