# @jsbot-tellus/core 中文文档

规范地址：https://npmcn.com/package/%40jsbot-tellus/core/

版本：2\.6\.0
npm 元数据更新时间：2026-11-01T14:09:15.235Z
中文译文更新时间：2026-11-01T14:19:23.283Z
软件包许可：AGPL-3\.0-or-later

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40jsbot-tellus/core
原文对照：https://npmcn.com/package/%40jsbot-tellus/core/?lang=original
项目主页：https://github.com/JsBot-Dev/JsBot-Tellus#readme
源码仓库：https://github.com/JsBot-Dev/JsBot-Tellus

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2.6 MB，408 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^24\.22\.1 \|\| \>=26\.12\.1
- 运行依赖：3 个
- 首次发布：2026-10-27T14:46:34.015Z
- 最新版本发布：2026-11-01T14:09:14.912Z
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

JsBot的新版本

## 安装

```sh
npm install @jsbot-tellus/core
```

也可以使用：`pnpm add @jsbot-tellus/core`、`yarn add @jsbot-tellus/core`、`bun add @jsbot-tellus/core`

## README

# JsBot-Tellus

基于 [`@snowluma/sdk`](https://www.npmjs.com/package/@snowluma/sdk) 的 OneBot 11 QQ 机器人框架。

当前版本采用「内核 + 插件」架构：

-   内核负责配置、连接、事件分发、命令匹配、权限、gating、消息发送、SQLite 存储和生命周期。
-   插件只通过 `PluginContext` 使用内核能力，不直接接触 SDK client、Router 或数据库。
-   SDK 只注册一个 middleware：`client.use(router.dispatch)`。
-   内置插件 `core`、`admin` 是普通源码，位于 `src/plugins/`，随内核一起编译。
-   `poke`、`llm` 等本地插件放在不跟踪的 `plugins/`，各自是独立包，从 `plugins/<id>/dist` 自动加载；缺少 `dist` 时会先尝试自动构建。

## 环境要求

-   Node.js `^24.22.1 || >=26.12.1`（与 `@snowluma/sdk` 保持一致）
-   npm

## 安装

```bash
npm install -g @jsbot-tellus/core
jsbot --config ./bot.config.json
```

也可以从源码运行，见下方快速开始。

## 快速开始

```bash
git clone https://github.com/JsBot-Dev/JsBot-Tellus
cd JsBot-Tellus
npm ci
cp bot.config.example.json bot.config.json
```

编辑 `bot.config.json`，至少填写连接地址和账号角色。然后：

```bash
# 构建并运行
npm run build
npm start

# 或者直接从源码运行
npm run start:source

# 开发模式（Watch）
npm run dev
```

默认配置路径是 `./bot.config.json`，默认数据目录是 `./data`。从旧版升级前请先备份并移走旧配置和数据库，见[迁移与回滚](https://npmcn.com/package/%40jsbot-tellus/core/docs/migration.md)。

## WebUI（可选）

在 `bot.config.json` 中启用管理后台：

```json
{
    "webui": {
        "enabled": true,
        "host": "127.0.0.1",
        "port": 8787,
        "username": "admin",
        "password": "至少 8 位"
    }
}
```

然后运行 `npm run build && npm start`，访问 `http://127.0.0.1:8787`。WebUI 默认关闭，提供运行状态、会话、插件、配置、KV、日志、事件和原始 OneBot action 管理。登录后拥有完整管理权限，默认只监听本机；远程访问请使用 HTTPS 反向代理。详见 [WebUI 文档](https://npmcn.com/package/%40jsbot-tellus/core/docs/webui.md)。

## 内置命令

| 命令 | 权限 | 作用 |
| --- | --- | --- |
| `/help`、`/h` | User | 按权限和当前会话启用状态列出命令 |
| `/status`、`/s` | User | 运行时长和插件状态 |
| `/role` | User | 显示当前用户角色 |
| `/utter <文本>` | Admin | 向当前会话发送文本 |
| `/utter raw <CQ>` | SuperAdmin | 发送原始 CQ 消息 |
| `/plugin list` | SuperAdmin | 列出已安装插件包 |
| `/plugin install` | SuperAdmin | 安装 npm 插件包 |
| `/plugin remove` | SuperAdmin | 卸载插件包 |
| `/plugin update` | SuperAdmin | 更新插件包 |

`/plugin` 的所有子命令（包括 `help` 和 `list`）都要求 SuperAdmin。`/utter.raw` 已迁移为 `/utter raw` 子命令。

## 内置与本地插件

内置插件是普通源码，不需要独立的 `package.json`：

```text
src/plugins/
  core/index.ts     /help、/status、/role
  admin/index.ts    /utter、/utter raw
  index.ts          内置插件清单
```

它们只依赖根 `package.json` 里的 `zod`，所以随内核一次 `tsc` 构建，产物在 `dist/plugins/`。

`poke`、`llm` 等本地插件放在 `plugins/`，该目录整体被 `.gitignore` 排除。每个插件都是独立包，有自己的 `package.json`、`tsconfig.json`、lockfile、`node_modules` 和构建脚本：

```bash
npm install --prefix plugins/poke
npm install --prefix plugins/llm
npm run build:plugin

node dist/app.js
```

应用启动时会固定扫描 `plugins/<id>/dist`，不需要路径参数。`plugins/` 中没有 `dist` 的本地插件如果带有 `build` 脚本且依赖已安装，会先自动执行 `npm run build` 再加载；没有 `build` 脚本、缺少 `node_modules` 或构建失败时会记录警告并跳过该插件。`plugins/` 中与内置插件同 ID 的插件也会被跳过。本地插件是普通 ESM 模块，默认导出、`plugin` 命名导出或 `plugins` 数组导出均可被加载。开发和发布方式见 [插件开发指南](https://npmcn.com/package/%40jsbot-tellus/core/docs/plugin-development.md)，示例位于 [`examples/plugins/hello`](https://npmcn.com/package/%40jsbot-tellus/core/examples/plugins/hello)。

## 在线安装插件包

在聊天中由 SuperAdmin 执行：

```text
/plugin install @scope/plugin@1.0.0
/plugin list
/plugin update @scope/plugin
/plugin remove @scope/plugin
```

-   只接受 npm registry 包，`name`、`name@版本`、`name@tag`、`@scope/name[@版本|tag]`；拒绝 git、file、URL、workspace、link 等来源。
-   包会直接安装到 `plugins/<插件id>/`，和本地插件一样从 `plugins/<插件id>/dist` 加载；不会放进共享的 `node_modules`。每个包带自己的依赖，不影响内核依赖。
-   首次安装时，一个包导出多个插件会使用包名作为目录（例如 `@scope/bundle` 对应 `plugins/@scope__bundle/`）。
-   安装、更新、卸载成功后会自动重启运行时并加载新插件，无需手动重启；进程本身不会退出。`/plugin list` 会标记“已加载”或“重启后生效”。安装状态保存在 `plugins/.jsbot-installed.json`。
-   默认使用 `--ignore-scripts`；只有显式设置 `installer.allowScripts=true` 才会执行 npm 生命周期脚本。
-   卸载不会修改 `plugins` 配置。如果配置里仍有对应插件 ID，命令会给出警告并跳过自动重启，需要在处理配置后手动重启；其它已安装包依赖被卸载插件 ID 时默认拒绝卸载，可使用 `/plugin remove <目标> --force` 强制卸载。

安装器默认关闭，需要显式设置 `installer.enabled=true`。启用后 `/plugin` 的所有子命令（包括只读的 `/plugin list`）都要求 SuperAdmin；安装的插件是运行在宿主进程中的完全可信代码。配置项见 [docs/configuration.md](https://npmcn.com/package/%40jsbot-tellus/core/docs/configuration.md#%E6%8F%92%E4%BB%B6%E5%AE%89%E8%A3%85%E5%99%A8)，发布要求见 [docs/plugin-api.md](https://npmcn.com/package/%40jsbot-tellus/core/docs/plugin-api.md#%E9%80%9A%E8%BF%87-npm-%E5%8F%91%E5%B8%83%E4%B8%8E%E5%AE%89%E8%A3%85)。

## CLI

```text
jsbot [options]

--config <path>      配置文件，优先级 CLI > BOT_CONFIG > ./bot.config.json
--data-dir <path>    数据目录，优先级 CLI > BOT_DATA_DIR > ./data
--log-level <level>  debug、info、warn、error，优先级 CLI > BOT_LOG_LEVEL
--help               显示帮助

本地插件固定从 ./plugins/<id>/dist 自动加载；缺少 dist 时会先自动构建。
```

## 开发与校验

```bash
npm run check         # 内核 TypeScript 类型检查（NodeNext + strict）
npm run check:webui   # WebUI 类型检查
npm run check:all     # 内核 + WebUI + 本地插件
npm test              # Vitest
npm run test:watch    # Vitest watch 模式
npm run format:check  # Prettier 检查
npm run build         # 构建内核、内置插件、WebUI 和 CLI
npm run smoke         # node dist/app.js --help

npm run check:plugin   # 自动检查 plugins 下的本地源码插件
npm run build:plugin   # 自动构建 plugins 下的本地源码插件
npm run plugin:gen -- my-plugin  # 生成并安装 plugins/my-plugin 模板依赖
```

## 发布

发布由 [`.github/workflows/cd.yaml`](https://npmcn.com/package/%40jsbot-tellus/core/.github/workflows/cd.yaml) 驱动：`main` 的 CI 成功后自动通过 npm Trusted Publisher 发布；已存在的版本会跳过。不需要版本标签。检查、构建和首次配置见[发布流程](https://npmcn.com/package/%40jsbot-tellus/core/docs/release.md)。

## 文档

-   [架构](https://npmcn.com/package/%40jsbot-tellus/core/docs/architecture.md)
-   [WebUI](https://npmcn.com/package/%40jsbot-tellus/core/docs/webui.md)
-   [插件开发](https://npmcn.com/package/%40jsbot-tellus/core/docs/plugin-development.md)
-   [插件 API](https://npmcn.com/package/%40jsbot-tellus/core/docs/plugin-api.md)
-   [配置](https://npmcn.com/package/%40jsbot-tellus/core/docs/configuration.md)
-   [迁移与回滚](https://npmcn.com/package/%40jsbot-tellus/core/docs/migration.md)
-   [功能对照](https://npmcn.com/package/%40jsbot-tellus/core/docs/feature-parity.md)
-   [发布流程](https://npmcn.com/package/%40jsbot-tellus/core/docs/release.md)

## 许可证

AGPL-3.0-or-later

## 常见问题

### @jsbot-tellus/core 是什么？

JsBot的新版本

### 如何安装 @jsbot-tellus/core？

在项目目录运行 npm install @jsbot-tellus/core，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 jsbot，可以用 npx jsbot 直接运行。

### @jsbot-tellus/core 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @jsbot-tellus/core 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @jsbot-tellus/core 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^24\.22\.1 \|\| \>=26\.12\.1。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @jsbot-tellus/core 可以商用吗？

@jsbot-tellus/core 使用 AGPL-3\.0-or-later 许可。最严格的 Copyleft：除分发外，通过网络向用户提供基于它的服务也需要开源对应源码。闭源 SaaS 使用前务必评估。以上为概括，不构成法律意见，请以许可原文为准。

### @jsbot-tellus/core 还在维护吗？

最新版本 2\.6\.0 发布于 2026/11/01（1 天前）；至今共发布 10 个版本，其中过去 12 个月发布了 10 个；首次发布于 2026/10/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。