furlow-mcp

FURLOW

声明式 Discord 机器人框架

使用 YAML 构建功能强大的 Discord 机器人。无需编写代码。

commands:
  - name: ping
    description: Check bot latency
    actions:
      - reply:
          content: "Pong! ${client.ws.ping}ms"

功能

• 85 个操作：消息、管理、语音、频道等
• 71 个表达式函数：日期、数学、字符串、数组操作
• 50 个转换器：基于管道的数据转换
• Discord 网关、语音状态切换、组件交互和高级 FURLOW 事件（自动审核、调度器、管道）中的 59 个事件
• 作用域状态：全局、服务器、频道、用户和成员作用域
• 工作流：带参数的可复用操作序列
• 外部集成：HTTP、WebSocket、MQTT、TCP/UDP、Webhook

快速开始

# Install the CLI
npm install -g @furlow/cli

# Create a bot
furlow init my-bot
cd my-bot

# Add your Discord credentials to .env
echo "DISCORD_TOKEN=your_token_here" > .env
echo "DISCORD_CLIENT_ID=your_client_id_here" >> .env

# Start
furlow start

示例

version: "0.1"

identity:
  name: "My Bot"

presence:
  status: online
  activity:
    type: playing
    text: "with FURLOW"

commands:
  - name: hello
    description: Greet someone
    options:
      - name: user
        type: user
        description: Who to greet
    actions:
      - reply:
          content: "Hello, ${options.user.display_name || options.user.username}!"

  - name: roll
    description: Roll a dice
    options:
      - name: sides
        type: integer
        description: Number of sides
        min_value: 2
        max_value: 100
    actions:
      - reply:
          content: "🎲 You rolled **${random(1, options.sides || 6)}**"

events:
  - event: member_join
    actions:
      - send_message:
          channel: "${env.WELCOME_CHANNEL}"
          content: "Welcome ${member.displayName}!"

CLI 命令

命令	说明
furlow init [name]	创建新的机器人项目
furlow start [path]	运行机器人
furlow dev [path]	热重载开发模式
furlow validate <path>	验证 YAML 规范
furlow add <builtin>	添加内置模块
furlow build [path]	打包以供部署
furlow export <path>	导出 Discord 命令 JSON

文档

指南	说明
安装	设置和要求
快速开始	创建你的第一个机器人
配置	YAML 规范
操作参考	全部 85 个操作
表达式参考	函数和转换器
事件参考	事件类型
CLI 参考	命令行界面
管道参考	外部集成
示例	完整的机器人示例

软件包

软件包	说明
furlow	CLI 工具
@furlow/core	运行时引擎
@furlow/discord	Discord.js 适配器
@furlow/schema	TypeScript 类型
@furlow/storage	数据库适配器
@furlow/builtins	预构建模块
@furlow/pipes	HTTP、WebSocket、MQTT、TCP/UDP、Webhook、数据库、文件
@furlow/testing	测试工具

生产环境部署

将机器人部署到生产环境的简要检查清单。每个项目都对应一项 运行时保障——跳过某一项，之后通常会导致数据悄然丢失、 功能未按计划运行，或会话可被公开伪造。

必需的环境变量

# Discord
DISCORD_TOKEN=...
DISCORD_CLIENT_ID=...

# Storage (pick one)
DATABASE_URL=postgres://user:pass@host:5432/furlow   # production
# or for single-server bots:
SQLITE_PATH=/var/lib/furlow/bot.db

# Dashboard (only if running the web UI)
DASHBOARD_SECRET=$(openssl rand -hex 32)             # required in NODE_ENV=production
DISCORD_CLIENT_SECRET=...
DISCORD_CALLBACK_URL=https://dashboard.example.com/auth/discord/callback

在 NODE_ENV=production 时，如果未设置 DASHBOARD_SECRET，控制面板将拒绝启动——没有默认备用值。 WebSocket 连接也需要经过身份验证的会话；未通过身份验证的客户端会在升级时被拒绝， 无法订阅服务器数据流。

存储

• 对于运行多个进程或需要时间点恢复的任何部署，请使用 Postgres。SQLite 适配器适用于单服务器机器人和测试，但活跃用户超过几千后，写入争用会迅速恶化。
• 部署时运行数据库迁移。SQLite 适配器会按需创建表；Postgres 部署应预先创建 state.tables: 块中定义的表。
• 备份数据库。内置模块会持久化实际状态（警告、等级、AFK 状态、工单记录）；这些数据都无法重建。

调度与语音

• CLI 会启动一个 CronScheduler，每 60s 发出一次 scheduler_tick。 依赖它的内置功能（giveaways、polls、reminders）需要调度器运行——无需单独的 cron 进程。
• 语音播放需要 @discordjs/voice peer 和 PATH 中的 ffmpeg。music 内置功能使用的 voice_track_start / voice_track_end 事件仅在语音管理器初始化后触发。

进程监管

• 在进程监管器（systemd、pm2、Kubernetes Deployment）下运行 furlow start，并配置为退出时重启。机器人不会自行守护进程化。
• 转发 SIGTERM，以便干净地关闭网关连接。CLI 会在关闭时刷新待处理状态；使用 SIGKILL 终止可能会丢失最后一批写入。

仪表板安全加固

• 在仪表板前终止 TLS（nginx、Caddy、负载均衡器）。 生产环境中会将会话 Cookie 的 secure 设为 true，且不会通过纯 HTTP 发送。
• 在 Discord 开发者门户中，将 OAuth 回调 URL 限制为你部署的确切 DISCORD_CALLBACK_URL。
• POST 端点会将接受的字段列入白名单，并对未知或类型错误的键返回 400。如果扩展设置结构，请更新 apps/dashboard/server/routes/api.ts 中的白名单。

可观测性

• /health 返回进程运行时间；将其接入存活探针。
• /metrics 暴露 Prometheus 格式的计数器。添加一个指向仪表板进程的抓取任务。
• CLI 支持 --verbose，以便在事件排查期间进行结构化的逐事件日志记录。

许可证

MIT