Multi-channel AI Assistant powered by iflow CLI

These details have not been verified by PyPI

Project description

🤖 iflow-bot

 /$$ /$$$$$$$$ /$$                                 /$$$$$$$              /$$    
|__/| $$_____/| $$                                | $$__  $$            | $$    
 /$$| $$      | $$  /$$$$$$  /$$  /$$  /$$        | $$  \ $$  /$$$$$$  /$$$$$$  
| $$| $$$$$   | $$ /$$__  $$| $$ | $$ | $$ /$$$$$$| $$$$$$$  /$$__  $$|_  $$_/  
| $$| $$__/   | $$| $$  \ $$| $$ | $$ | $$|______/| $$__  $$| $$  \ $$  | $$    
| $$| $$      | $$| $$  | $$| $$ | $$ | $$        | $$  \ $$| $$  | $$  | $$ /$$
| $$| $$      | $$|  $$$$$$/|  $$$$$/$$$$/        | $$$$$$$/|  $$$$$$/  |  $$$$/
|__/|__/      |__/ \______/  \_____/\___/         |_______/  \______/    \___/

多渠道 AI 助手 - 基于 iflow CLI 构建的多平台消息机器人。

将 iflow 的强大 AI 能力扩展到多个通讯平台，让 AI 助手无处不在。

✨ 特性

🔌 多渠道支持 - Telegram、Discord、Slack、飞书、钉钉、QQ、WhatsApp、Email、Mochat
🧠 AI 驱动 - 基于 iflow CLI，支持多种模型（GLM-5、Kimi K2.5 等）
💾 会话管理 - 自动管理多用户会话，支持对话上下文
📁 工作空间 - 每个机器人实例拥有独立的工作空间和记忆系统
🔐 权限控制 - 支持白名单、提及触发等多种策略
🔄 思考模式 - 可选启用 AI 思考过程展示
⚡ 流式输出 - 支持 Telegram、钉钉 AI Card 实时流式输出
🔗 双模式通信 - 支持 CLI 和 ACP 两种与 iflow 的通信方式

🎬 演示

Telegram 流式输出

Telegram 流式输出演示

钉钉 AI Card 流式输出

钉钉 AI Card 流式输出演示

📋 前置要求

1. 安装 iflow CLI

iflow-bot 依赖 iflow CLI 运行，请先安装：

# 已有Node.js 22+
npm i -g @iflow-ai/iflow-cli@latest

# curl 方式
bash -c "$(curl -fsSL https://gitee.com/iflow-ai/iflow-cli/raw/main/install.sh)"

2. 登录 iflow

iflow

运行 iflow 后选择 OLogin with iFlow 登录
CLI 会自动打开浏览器跳转到心流平台
完成注册/登录后授权 iFlow CLI
自动返回终端，开始使用

按照提示完成登录流程。

🚀 快速开始

安装

方式一：pip 安装（推荐）

pip install iflow-bot

安装完成后即可直接使用：

iflow-bot --help
iflow-bot onboard
iflow-bot gateway start

方式二：从源码安装

# 克隆仓库
git clone https://github.com/your-repo/iflow-bot.git
cd iflow-bot

# 安装依赖（使用 uv）
uv sync

初始化配置

# 创建默认配置文件（pip 安装）
iflow-bot onboard

# 或源码安装
uv run iflow-bot onboard

# 或手动创建
mkdir -p ~/.iflow-bot
cp config.example.json ~/.iflow-bot/config.json

启动服务

pip 安装后：

# 前台运行（调试模式）
iflow-bot gateway run

# 后台运行
iflow-bot gateway start

# 查看状态
iflow-bot status

# 停止服务
iflow-bot gateway stop

源码安装后：

# 前台运行（调试模式）
uv run iflow-bot gateway run

# 后台运行
uv run iflow-bot gateway start

⚙️ 配置说明

配置文件位于 ~/.iflow-bot/config.json

完整配置示例

{
  "driver": {
    "mode": "acp",
    "acp_port": 8090,
    "acp_host": "localhost",
    "iflow_path": "iflow",
    "model": "minimax-m2.5", // 默认模型（glm-5、kimi-k2.5、minimax-m2.5 等）
    "yolo": true,
    "thinking": false,
    "max_turns": 40,
    "timeout": 300,
    "workspace": "~/.iflow-bot/workspace",
    "extra_args": []
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allow_from": []
    },
    "discord": {
      "enabled": false,
      "token": "YOUR_BOT_TOKEN",
      "allow_from": []
    },
    "slack": {
      "enabled": false,
      "bot_token": "xoxb-xxx",
      "app_token": "xapp-xxx",
      "allow_from": [],
      "group_policy": "mention"
    },
    "feishu": {
      "enabled": false,
      "app_id": "cli_xxx",
      "app_secret": "xxx",
      "encrypt_key": "",
      "verification_token": "",
      "allow_from": []
    },
    "dingtalk": {
      "enabled": false,
      "client_id": "xxx",
      "client_secret": "xxx",
      "robot_code": "xxx",
      "card_template_id": "xxx-xxx-xxx",
      "card_template_key": "content",
      "allow_from": []
    },
    "qq": {
      "enabled": false,
      "app_id": "xxx",
      "secret": "xxx",
      "allow_from": []
    },
    "whatsapp": {
      "enabled": false,
      "bridge_url": "http://localhost:3001",
      "bridge_token": "",
      "allow_from": []
    },
    "email": {
      "enabled": false,
      "consent_granted": false,
      "imap_host": "imap.gmail.com",
      "imap_port": 993,
      "imap_username": "your@email.com",
      "imap_password": "app_password",
      "smtp_host": "smtp.gmail.com",
      "smtp_port": 587,
      "smtp_username": "your@email.com",
      "smtp_password": "app_password",
      "from_address": "your@email.com",
      "allow_from": [],
      "auto_reply_enabled": true
    },
    "mochat": {
      "enabled": false,
      "base_url": "https://mochat.io",
      "socket_url": "https://mochat.io",
      "socket_path": "/socket.io",
      "claw_token": "xxx",
      "agent_user_id": "",
      "sessions": ["*"],
      "panels": ["*"]
    }
  },
  "log_level": "INFO",
  "log_file": ""
}

Driver 配置

参数	类型	默认值	说明
`mode`	string	`"acp"`	通信模式：`cli`（子进程调用）或 `acp`（Agent Communication Protocol）
`acp_port`	int	`8090`	ACP 模式下的端口号
`acp_host`	string	`"localhost"`	ACP 模式下的主机地址
`iflow_path`	string	`"iflow"`	iflow CLI 路径【保持默认即可】
`model`	string	`"glm-5"`	默认模型（glm-5、kimi-k2.5 等）
`yolo`	bool	`true`	自动确认模式
`thinking`	bool	`false`	显示 AI 思考过程
`max_turns`	int	`40`	单次最大对话轮次
`timeout`	int	`300`	超时时间（秒）
`workspace`	string	`~/.iflow-bot/workspace`	工作空间路径
`extra_args`	list	`[]`	额外的 iflow 参数

通信模式说明

ACP 模式（推荐）：

使用 Agent Communication Protocol 与 iflow 通信
支持实时流式输出，打字机效果
Gateway 启动时自动执行 iflow --experimental-acp --port 8090 --stream
会话状态持久化，重启后自动恢复

CLI 模式：

通过子进程调用 iflow CLI
每次对话独立启动进程
适合简单场景或调试

渠道配置

{
  "telegram": {
    "enabled": true,
    "token": "YOUR_BOT_TOKEN",
    "allow_from": ["user_id_1", "user_id_2"]
  }
}

在 @BotFather 创建机器人获取 Token
allow_from 为空表示允许所有用户

Discord

{
  "discord": {
    "enabled": true,
    "token": "YOUR_BOT_TOKEN",
    "allow_from": ["user_id_1"]
  }
}

在 Discord Developer Portal 创建应用
创建 Bot 用户并获取 Token
启用 Message Content Intent

Slack

{
  "slack": {
    "enabled": true,
    "bot_token": "xoxb-xxx",
    "app_token": "xapp-xxx",
    "allow_from": [],
    "group_policy": "mention"
  }
}

在 Slack API 创建应用
创建 Bot 并获取 Bot Token (xoxb-xxx)
启用 Socket Mode 获取 App Token (xapp-xxx)
group_policy 控制频道消息响应策略：
- mention: 只响应 @提及
- open: 响应所有消息
- allowlist: 只响应白名单频道

飞书 (Feishu/Lark)

{
  "feishu": {
    "enabled": true,
    "app_id": "cli_xxx",
    "app_secret": "xxx",
    "encrypt_key": "",
    "verification_token": "",
    "allow_from": []
  }
}

在飞书开放平台创建企业自建应用
启用机器人能力
配置事件订阅（使用 WebSocket，无需公网 IP）

钉钉 (DingTalk)

{
  "dingtalk": {
    "enabled": true,
    "client_id": "xxx",
    "client_secret": "xxx",
    "robot_code": "xxx",
    "card_template_id": "xxx-xxx-xxx",
    "card_template_key": "content",
    "allow_from": []
  }
}

在钉钉开放平台创建机器人
获取 Client ID 和 Client Secret
启用 Stream Mode（无需公网 IP）

AI Card 流式输出配置（可选，实现打字机效果）：

参数	说明
`robot_code`	机器人代码，群聊时需要配置
`card_template_id`	AI Card 模板 ID，在钉钉开发者后台创建
`card_template_key`	模板内容字段名，默认 `content`

创建 AI Card 模板：

登录钉钉开发者后台
进入「卡片平台」→「卡片模板」
创建模板，添加一个「文本」类型的字段
记录模板 ID 和字段名，配置到 card_template_id 和 card_template_key

流式输出效果：

用户发送消息后，机器人立即回复一张空白卡片
卡片内容实时更新，呈现打字机效果
无需等待完整响应，体验更流畅

QQ

{
  "qq": {
    "enabled": true,
    "app_id": "xxx",
    "secret": "xxx",
    "allow_from": []
  }
}

在 QQ 开放平台创建机器人
获取 App ID 和 Secret

{
  "whatsapp": {
    "enabled": true,
    "bridge_url": "http://localhost:3001",
    "bridge_token": "",
    "allow_from": []
  }
}

需要部署 WhatsApp Bridge（基于 baileys）

Email

{
  "email": {
    "enabled": true,
    "consent_granted": true,
    "imap_host": "imap.gmail.com",
    "imap_port": 993,
    "imap_username": "your@email.com",
    "imap_password": "app_password",
    "smtp_host": "smtp.gmail.com",
    "smtp_port": 587,
    "smtp_username": "your@email.com",
    "smtp_password": "app_password",
    "from_address": "your@email.com",
    "allow_from": ["sender@example.com"],
    "auto_reply_enabled": true
  }
}

重要: 使用 Gmail 需要创建应用专用密码

Mochat

{
  "mochat": {
    "enabled": true,
    "base_url": "https://mochat.io",
    "socket_url": "https://mochat.io",
    "socket_path": "/socket.io",
    "claw_token": "xxx",
    "agent_user_id": "",
    "sessions": ["*"],
    "panels": ["*"]
  }
}

🎮 CLI 命令

基础命令

# 查看版本
iflow-bot version
iflow-bot -v

# 查看帮助
iflow-bot --help

# 查看状态
iflow-bot status

# 初始化配置
iflow-bot onboard [--force]

Gateway 服务管理

# 后台启动服务
iflow-bot gateway start

# 前台运行（调试模式）
iflow-bot gateway run

# 停止服务
iflow-bot gateway stop

# 重启服务
iflow-bot gateway restart

配置管理

# 显示配置
iflow-bot config --show

# 编辑配置
iflow-bot config -e

# 切换模型
iflow-bot model glm-5
iflow-bot model kimi-k2.5
iflow-bot model minimax-m2.5

# 思考模式
iflow-bot thinking on
iflow-bot thinking off

会话管理

# 列出所有会话
iflow-bot sessions

# 过滤渠道
iflow-bot sessions --channel telegram

# 过滤聊天ID
iflow-bot sessions --chat-id 123456

# 清除会话映射
iflow-bot sessions --clear

定时任务 (Cron)

# 列出任务
iflow-bot cron list [-a]

# 添加间隔任务
iflow-bot cron add -n "喝水提醒" -m "该喝水了！" -e 300 -d --channel telegram --to "123456"

# 添加一次性任务
iflow-bot cron add -n "会议提醒" -m "开会！" -a "2024-12-25T10:00:00" -d --channel telegram --to "123456"

# 添加 cron 表达式任务
iflow-bot cron add -n "早报" -m "发送早报" -c "0 9 * * *" --tz "Asia/Shanghai" -d --channel telegram --to "123456"

# 启用/禁用任务
iflow-bot cron enable <id>
iflow-bot cron disable <id>

# 立即执行任务
iflow-bot cron run <id>

# 移除任务
iflow-bot cron remove <id>

iflow 命令透传

# iflow 基础透传
iflow-bot iflow --help
iflow-bot iflow -p "hello"

# MCP 命令
iflow-bot mcp --help

# Agent 命令
iflow-bot agent --help

# Workflow 命令
iflow-bot workflow --help

# Skill 命令
iflow-bot skill --help

# Commands 命令
iflow-bot commands --help

📁 目录结构

~/.iflow-bot/
├── botpy.log                # QQ bot 日志
├── config.json              # 配置文件
├── gateway.pid              # PID 文件（后台运行）
├── gateway.log              # Gateway 日志
├── session_mappings.json    # Session 会话映射
├── workspace/               # iflow 工作空间
│   ├── AGENTS.md            # Agent 行为指南
│   ├── BOOT.md              # 启动配置
│   ├── HEARTBEAT.md         # 心跳任务
│   ├── IDENTITY.md          # 身份标识
│   ├── SOUL.md              # AI 人格定义
│   ├── TOOLS.md             # 工具配置
│   ├── USER.md              # 用户信息
│   └── memory/              # 记忆目录
│       └── MEMORY.md        # 长期记忆
└── data/                    # 数据目录
    └── cron/                # 定时任务
        └── jobs.json        # 任务数据

🔧 开发

流式输出支持

iflow-bot 支持实时流式输出，让用户看到 AI "打字"的过程。

支持流式输出的渠道：

渠道	流式方式	说明
Telegram	编辑消息	实时编辑消息内容
钉钉	AI Card	使用钉钉卡片模板流式更新
Discord	编辑消息	实时编辑消息内容（计划中）
Slack	编辑消息	实时编辑消息内容（计划中）

配置要求：

需要使用 ACP 模式（driver.mode = "acp"）
钉钉需要额外配置 AI Card 模板

流式输出缓冲机制：

内容累积到 10-25 个字符（随机）时推送一次更新
避免过于频繁的 API 调用
确保最终消息包含所有内容

Session 会话管理

iflow-bot 自动管理多用户会话，支持跨渠道对话上下文。

Session 映射存储：

存储位置：~/.iflow-bot/session_mappings.json
格式：{渠道}:{聊天ID} -> {sessionId}

Session 恢复机制：

Gateway 重启后自动复用现有 ACP 进程
Session 失效时自动创建新会话
支持通过 CLI 管理会话

# 查看所有会话
iflow-bot sessions

# 清除会话映射
iflow-bot sessions --clear

项目结构

iflow-bot/
├── iflow_bot/
│   ├── __init__.py
│   ├── __main__.py          # 入口点
│   ├── bus/                 # 消息总线
│   │   ├── events.py        # 事件定义
│   │   └── queue.py         # 消息队列
│   ├── channels/            # 渠道实现
│   │   ├── base.py          # 基类
│   │   ├── telegram.py
│   │   ├── discord.py
│   │   ├── slack.py
│   │   ├── feishu.py
│   │   ├── dingtalk.py
│   │   ├── qq.py
│   │   ├── whatsapp.py
│   │   ├── email.py
│   │   ├── mochat.py
│   │   └── manager.py       # 渠道管理器
│   ├── cli/                 # CLI 命令
│   │   └── commands.py
│   ├── config/              # 配置管理
│   │   ├── schema.py        # 配置模型
│   │   └── loader.py
│   ├── cron/                # 定时任务
│   │   ├── service.py
│   │   └── types.py
│   ├── engine/              # 核心引擎
│   │   ├── adapter.py       # iflow 适配器
│   │   └── loop.py          # 消息循环
│   ├── heartbeat/           # 心跳服务
│   │   └── service.py
│   ├── session/             # 会话管理
│   │   └── manager.py
│   ├── templates/           # 模板文件
│   │   ├── AGENTS.md
│   │   ├── SOUL.md
│   │   └── ...
│   └── utils/               # 工具函数
│       └── helpers.py
├── tests/
├── pyproject.toml
└── README.md

📝 工作空间模板

工作空间包含 AI 的"人格"和记忆：

SOUL.md - 定义 AI 的核心人格和行为准则
USER.md - 用户信息和偏好
AGENTS.md - 工作空间行为指南
TOOLS.md - 可用工具和配置
MEMORY.md - 长期记忆（重要事件、决策）
memory/YYYY-MM-DD.md - 日常记忆日志

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 License

MIT

🙏 致谢

iflow CLI - 强大的 AI Agent CLI
nanobot - 轻量级 AI 机器人框架

Project details

These details have not been verified by PyPI

Release history Release notifications | RSS feed

0.4.6

Mar 18, 2026

0.4.5

Mar 16, 2026

0.4.4

Mar 15, 2026

0.4.2

Mar 13, 2026

0.4.1

Mar 13, 2026

0.4.0

Mar 13, 2026

0.3.9

Mar 11, 2026

0.3.8

Mar 10, 2026

0.3.7

Mar 10, 2026

0.3.6

Mar 10, 2026

0.3.5

Mar 8, 2026

0.3.4

Mar 6, 2026

0.3.3

Mar 4, 2026

0.3.1

Mar 2, 2026

0.3.0

Mar 2, 2026

0.2.6

Mar 1, 2026

0.2.5

Feb 28, 2026

0.2.4

Feb 27, 2026

0.2.3

Feb 26, 2026

This version

0.2.2

Feb 26, 2026

0.2.1

Feb 26, 2026

0.2.0

Feb 26, 2026

0.1.7

Feb 26, 2026

0.1.6

Feb 26, 2026

0.1.4

Feb 26, 2026

0.1.3

Feb 25, 2026

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

iflow_bot-0.2.2.tar.gz (8.2 MB view details)

Uploaded Feb 26, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

iflow_bot-0.2.2-py3-none-any.whl (131.0 kB view details)

Uploaded Feb 26, 2026 Python 3

File details

Details for the file iflow_bot-0.2.2.tar.gz.

File metadata

Download URL: iflow_bot-0.2.2.tar.gz
Upload date: Feb 26, 2026
Size: 8.2 MB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.7.6

File hashes

Hashes for iflow_bot-0.2.2.tar.gz
Algorithm	Hash digest
SHA256	`ad4b6bde38d7c88b53694f555c0ff09f01f032ec13bf510437abba022bf39231`
MD5	`70b868781f0e93f1ad27fd69f82456da`
BLAKE2b-256	`f4d064d1f31cf93172088bf06a1c794d73e5b38beaea641a9dce5aa85a04a36e`

See more details on using hashes here.

File details

Details for the file iflow_bot-0.2.2-py3-none-any.whl.

File metadata

Download URL: iflow_bot-0.2.2-py3-none-any.whl
Upload date: Feb 26, 2026
Size: 131.0 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.7.6

File hashes

Hashes for iflow_bot-0.2.2-py3-none-any.whl
Algorithm	Hash digest
SHA256	`338968992a5dbd41a09f346ee7d289ad5bef779988654edfb38c573fa980ccc7`
MD5	`421b1269a46e5bec7e286d58c730759c`
BLAKE2b-256	`d4431f3f96a5c65e02a148b0bd24f44af24110d3b5cfa934b582c836e0439817`

See more details on using hashes here.

iflow-bot 0.2.2

Navigation

Verified details

Maintainers

Unverified details

Meta

Classifiers

Project description

🤖 iflow-bot

✨ 特性

🎬 演示

Telegram 流式输出

钉钉 AI Card 流式输出

📋 前置要求

1. 安装 iflow CLI

2. 登录 iflow

🚀 快速开始

安装

初始化配置

启动服务

⚙️ 配置说明

完整配置示例

Driver 配置

通信模式说明

渠道配置

Telegram

Discord

Slack

飞书 (Feishu/Lark)

钉钉 (DingTalk)

QQ

WhatsApp

Email

Mochat

🎮 CLI 命令

基础命令

Gateway 服务管理

配置管理

会话管理

定时任务 (Cron)

iflow 命令透传

📁 目录结构

🔧 开发

流式输出支持

Session 会话管理

项目结构

📝 工作空间模板

🤝 贡献

📄 License

🙏 致谢

Project details

Verified details

Maintainers

Unverified details

Meta

Classifiers

Release history Release notifications | RSS feed

Download files

Source Distribution

Built Distribution

File details

File metadata

File hashes

File details

File metadata

File hashes