Fraq | 使用 Fraq CLI

Fraq CLI 是一个命令行工具，提供了快速创建和运行 Fraq 机器人项目的能力。

准备工作

安装 Node.js

你可以在 Node.js 官方网站查阅如何在你的操作系统上安装 Node.js。Fraq 所需的最低 Node.js 版本为 22，推荐安装最新的 LTS 版本。

安装 Fraq CLI

你可以用 npm i -g 在你的计算机上全局安装 Fraq CLI：

npm i -g @fraqjs/cli

安装完成后，你可以执行一次 fraq version 命令来查看是否安装成功。正常情况下，它会打印当前安装的 Fraq CLI 版本号。

启动 Milky 协议端

你可以在 Milky 的官方网站寻找并安装你喜欢的 Milky 协议端实现。安装完成后，你需要配置协议端监听的 IP 和端口，并且在协议端登录你的 QQ 账号。

安装 pnpm（可选）

pnpm 是一个快速、节省磁盘空间的包管理器。你可以在 pnpm 的官方网站查阅如何安装 pnpm。例如，使用 npm 来全局安装 pnpm：

npm i -g pnpm

Fraq 会按照 pnpm -> yarn -> npm 的顺序查找可用的包管理器，并使用第一个找到的包管理器来安装依赖。如果你希望固定使用某个包管理器，可以在 fraq.yml 中通过 packageManager 字段显式指定 npm、pnpm 或 yarn。

配置 Milky 连接

fraq.yml 中的 milky 字段用于配置与 Milky 协议端的连接：

milky:
  url: http://localhost:30001/ # 协议端地址
  accessToken: <如果你的 Milky 协议端配置了 token，请在这里添加>
  connectEvent: true # 是否监听协议端推送的事件

字段	含义
`url`	Milky 协议端的地址
`accessToken`	协议端要求的访问令牌。如果协议端配置了 token，需要在这里填写相同的 token
`connectEvent`	是否监听协议端推送的事件（如消息），默认 `true`。设为 `false` 后机器人不再接收消息等事件

安装与配置插件

你可以在配置文件的 plugins 字段下添加你想要安装的插件。例如：

plugins:
  status: # 状态监测插件，发送 `fraq` 命令可以查看 Fraq 机器人的运行状态
  retrieve: # 消息获取插件，回复一条消息并输入 `retrieve` 命令可以获取该消息的 Milky 消息段表示

每一个插件都对应一个 npm Registry 包。例如：

status 对应 fraq-plugin-status
retrieve 对应 fraq-plugin-retrieve
some-scope/foo 对应 @some-scope/fraq-plugin-foo，其中 some-scope 是 npm Registry 的 scope 名称
fraqjs/ai 对应 @fraqjs/plugin-ai，属于官方插件，不需要 fraq- 前缀

可以在插件市场中查找更多你喜欢的插件，并且在配置文件中添加它们。

谨慎对待你的每一个插件。群聊中的每一条消息都有意外触发指令的可能性，这会影响其他人的聊天体验，甚至导致你的机器人被移出群聊乃至封禁。后面的章节会介绍如何通过配置过滤器和触发方式来限制指令的触发，从而避免其他人的消息意外触发插件。

大多数插件都支持特定的配置。你可以在插件名称下添加配置字段。例如，status 插件支持配置命令名称，你可以在 plugins.status 下添加 commandName 字段来修改默认的触发命令：

plugins:
  status:
    commandName: status # 修改触发命令为 `status`

其他插件也可以通过类似的方式进行配置。你可以在插件的 README 中查找它们支持的配置字段。

插件依赖关系

此外，需要注意不同插件之间可能存在依赖关系。例如，chatsalt 插件依赖 Fraq 官方的 ai 和 kysely（数据库存储）插件，因此在安装 chatsalt 插件时，同时也需要安装 fraqjs/ai 和 fraqjs/kysely 插件：

plugins:
  fraqjs/ai:
    # 在这里配置 ai 插件
  fraqjs/kysely:
    # 在这里配置 kysely 插件
  chatsalt:
    # 在这里配置 chatsalt 插件

你可以在插件的 README 中查找它们的依赖关系。如果一个插件的依赖缺失，Fraq CLI 会在启动时打印出错误信息，并且提示你安装缺失的依赖插件。

测试工作区插件

开发插件时，可以通过顶层的 workspacePlugins 字段将插件名映射到本地包目录，而不必先发布到 npm Registry：

plugins:
  status:
    commandName: status

workspacePlugins:
  status: ../plugin-status

相对路径以 fraq.yml 所在目录为基准。工作区包的 package.json 中必须声明与插件名对应的 npm 包名；例如 status 对应 fraq-plugin-status，fraqjs/ai 对应 @fraqjs/plugin-ai。Fraq CLI 会将其作为本地 file: 依赖安装，并直接读取该 package.json 检查插件依赖关系。工作区插件不需要在 versions 中声明，也不会写入 versions.yml 或参与 outdated、update。

配置 `additionalDependencies`

部分插件可能会要求安装额外的依赖包，版本声明方式遵循 Semantic Versioning 规范。通常情况下，插件的 README 中会说明它们所依赖的额外依赖包及其版本要求。这部分的依赖会被直接注入到生成的 package.json 中，并且在安装依赖时会被自动安装。

配置日志等级

Fraq CLI 使用 @fraqjs/color-log 将日志打印到命令行中。你可以在配置文件中添加 logging.minLevel 字段来设置日志的最小等级。默认情况下，logging.minLevel 的值为 debug，这意味着所有等级的日志都会被打印到命令行中。你可以将其设置为 info、warn 或 error 来减少日志输出。

logging:
  minLevel: info # 设置日志最小等级为 info，低于 info 等级

从环境中读取配置

fraq.yml 支持使用 ${{ 类型:目标 }} 引用环境变量、文本文件以及其他 YAML/JSON 文件。例如：

milky:
  url: http://${{ env:MILKY_HOST }}:${{ env:MILKY_PORT }}
  accessToken: ${{ text:secrets/milky-token.txt }}

plugins: ${{ tree:config/plugins.yml }}

支持以下引用类型：

${{ env:NAME }} 读取环境变量。环境变量不存在时，Fraq CLI 会停止并报告错误。
${{ text:path }} 以 UTF-8 读取文本文件。Fraq CLI 会移除文件末尾的一个 LF 或 CRLF 换行符，并保留其他空白。
${{ tree:path }} 解析 .yml、.yaml 或 .json 文件，保留其中对象、数组、数字、布尔值和 null 等原生类型。

env 和 text 引用既可以独占一个值，也可以嵌入普通字符串；tree 引用必须独占整个值，不能写成 prefix-${{ tree:file.yml }}。只有配置值会被插值，字段名称不会被处理。

相对文件路径以包含该引用的文件为基准，因此被 tree 引用的文件可以继续使用相对于自身的 text 或 tree 引用。Fraq CLI 允许使用绝对路径和 ..，并会检测递归引用造成的循环。环境变量和文本文件的内容不会被再次插值。

如果需要将插值语法作为普通文本使用，请在开头增加一个 $：

example: $${{ env:NAME }} # 解析结果为字面量 `${{ env:NAME }}`

Watch 模式

fraq start 命令支持 --watch 参数，它会在启动 Fraq 机器人后，持续观察 fraq.yml 配置文件和工作区插件的有效入口点文件的变化。一旦这些文件发生变化，Fraq CLI 会自动重新加载配置或刷新本地依赖，并重启 Fraq 机器人。

fraq start --watch

使用 Fraq CLI