快速开始

约 1025 字大约 3 分钟

2026-09-15

0. 获取代码

不想自己编译的话用已构建版（内核已经编译好，装上就能跑）：

git clone -b release --depth 1 https://github.com/HL-z7/JiuLi.git
cd JiuLi && pnpm install

想跟最新提交、或要改内核源码，就用 master，并把首次启动交给 CLI（它会自动编译）：

git clone https://github.com/HL-z7/JiuLi.git
cd JiuLi && pnpm install && node jiuli b    # b = 编译内核

两个分支的差别、以及 GitHub 代理加速与 Gitee 镜像地址见安装部署。

1. 启动

pnpm install && node jiuli s      # 后台常驻
# 或
node .                            # 前台运行，能在终端直接敲指令

看到一个 > 提示符就说明标准输入适配器已经就绪，可以直接在终端里发指令：

> #玖璃帮助
> #状态
> #版本

机器人回复也会打印回终端，不需要协议端就能调通全流程。

2. 设置主人

默认主人是 stdin:stdin（终端），所以终端里可以直接设置真实账号：

> #设置主人
[10001] 请输入验证码
> 01M2JB80SEZBP3PX3ZKM9FHR3P
[10001] 设置主人完成

验证码同时会打到日志里（设置主人验证码 <code>）。写进 config/config/other.yaml：

master:
  - "stdin:stdin"
  - "机器人账号:你的账号"
masterQQ:
  - "你的账号"

也可以直接手改这个文件，改完重启生效。

已有一个主人时，直接用指令增删更省事：

> #新增主人 @某人          # 带 @ 或 QQ 号 → 主人直接添加
[12345678] 已被设置为主人
> #删除主人 12345678       # 只能由主人发起
[12345678] 已被移除主人

不带目标（#设置主人 / #新增主人）走验证码流程，任何人都能发起； #删除主人 会拒绝删掉最后一个主人，避免把自己锁在门外。

3. 接入协议端

# 个人 QQ：装 ICQQ 适配器
node jiuli a https://gitee.com/TimeRainStarSky/Yunzai-ICQQ-Plugin
node jiuli r                                             # 重启

QQ 官方机器人用 Yunzai-QQBot-Plugin，其它适配器同理（详见安装部署）。

#诊断 可以一次性看到适配器、在线账号、插件数、渲染状态。

4. 写第一个插件

node jiuli c my-plugin          # 生成 plugins/example/my-plugin.js
node jiuli c my-plugin --dsl    # 函数式 DSL 形态

改完存盘等两秒，热重载自动生效，不用重启（含 apps/、lib/ 深层文件；整图重载需 Node 22.15+，更老的 Node 上目录型插件要 #重启）。最小可用插件：

import { JiuLiPlugin } from 'jiuli'

export default class Hello extends JiuLiPlugin {
  constructor() {
    super({ name: '你好', rule: [{ reg: '^#你好$', fnc: 'hello' }] })
  }
  async hello(e) {
    await e.reply('你好呀')
  }
}

更多见插件开发。

常用指令

指令	说明
`#玖璃帮助` / `#帮助`	列出已加载插件的功能（`#帮助` 也能用，装了菜单插件时会被它接管）
`#状态`	运行状态（插件数、账号、渲染、内存）
`#版本`	框架与 Node 版本
`#诊断`	适配器 / 在线账号 / 插件 / 渲染自检
`#设置主人` / `#新增主人`	走验证码流程（见上）；带 `@用户` 或 QQ 号时主人可直接添加
`#删除主人`	主人直接移除：`#删除主人 @用户` 或 `#删除主人 12345678`
`#添加` `#删除` `#消息列表`	词条（自定义问答）
`#撤回`	主人指令：撤回触发消息与所引用的那条消息
`#重载`	补漏加载插件（详见热重载）
`#更新` / `#更新ICQQ` / `#全部更新`	更新框架本体 / 指定插件 / 全部（更新后自动重启）
`#更新日志`	查看最近提交
`#安装插件`	列出可安装插件；`#安装插件 <git 地址>` 或 `#安装ICQQ` 直接装（装完自动重启）
`#重启` `#停止`	重启 / 停止进程
`#日志`	把最近日志发到聊天里

完整清单看 plugins/system/（框架内置插件目录），每个文件一个功能。

无协议端的高级调试

Mock 适配器支持用 JSON 事件驱动，方便写脚本做回归：

JIULI_MOCK_STDIN=1 node .
{"type":"message","group_id":"123456","user_id":"10001","msg":"#玖璃帮助"}

（测试脚本属于开发用，不在仓库里；开发者本地保留 test/ 目录即可。）