awesome-lark-bots

# Awesome Lark Bots — 飞书 AI 机器人团队

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
[![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-blue.svg)](https://raw.githubusercontent.com/umarqadri345/awesome-lark-bots/main/planner/lark_bots_awesome_3.9-beta.1.zip)

**[English](#english)** | **中文**

一套在飞书（Lark）上运行的开源 AI 机器人，覆盖**创意脑暴、项目规划、日常助手、素材 Prompt 生成、舆情监控、新闻聚合、自媒体全流程编排**七大场景。

> **这是一个活跃探索中的项目。** 我们把它开源出来，是因为相信 AI + 飞书的自动化工作流有很大的想象空间，也希望有更多人一起来完善它。欢迎提 Issue、提 PR，或者单纯 star 一下表示支持。

### 为什么做这个？

我们相信 **不需要给 AI 完整的系统权限，也能让它帮你把大部分工作干了。**

思路很简单：

- **日常自动化**（脑暴、规划、舆情采集、内容创作、定时发布……）→ 部署在云端，用**飞书聊天**作为交互入口，随时随地发条消息就能触发，轻量、安全、低权限
- **深度任务**（复杂架构设计、大规模代码重构……）→ 需要时再用 Claude Code 等重型工具，按需授权

大多数工作场景不需要把钥匙全交给 AI。一个聊天窗口 + 几个专注的机器人，够了。

---

## 七个机器人一览

| 机器人 | 一句话介绍 | 在飞书上怎么用 | 启动命令 |
|--------|-----------|---------------|----------|
| **自媒体助手** ⚗️ | 自媒体全流程编排：选题→脑暴→创作→质量自动修正→存储，AgentLoop 加持 | 发消息：`春天穿搭分享` 或 `深度：新品发布会` | `python3 -m conductor` |
| **脑暴机器人** | 5 个 AI 角色 + AgentLoop 联网调研，四种模式 + 飞书文档读取 | 发消息：`策略：增长靠补贴还是产品` / 粘贴飞书链接 | `python3 -m brainstorm` |
| **规划机器人** | 六步规划（每步可联网搜索）+ Agency 比稿 + 飞书文档读写 + Handoff 卡片 | 发消息：`规划：Q3 策略` / 粘贴飞书链接 | `python3 -m planner` |
| **助手机器人** | 备忘+线程（双向同步看板）、项目管理（Bitable）、财务、翻译、智能聊天 | 发消息：`创建项目 Q2营销` / `翻译 xxx` | `python3 -m assistant` |
| **素材 Bot** | 生成 AI 工具 prompt + 执行 Brief → 多维表格素材管理 | 发消息：`春日樱花的抖音预告` / `安排制作` | `python3 -m creative` |
| **舆情监控** | 15 个社媒平台 + Web Search（Tavily/DDG）采集，三阶段补量 | 发消息：`周报` / `采集 咖啡品牌 @微博 7天` | `python3 -m sentiment` |
| **早知天下事** | 多源新闻聚合 + AI 分析，每日推送新闻简报 | 发消息：`新闻` / `科技新闻` | `python3 -m newsbot` |

> ⚗️ **自媒体助手**目前处于探索阶段——基本框架已搭好，能跑通"选题→脑暴→规划→创作→存储"全流程，但在内容自动生成的质量把控和自媒体平台自动发布方面，还有很多需要探索和优化的空间。我们非常欢迎社区一起来完善这个模块。

七个机器人**共享底层模块**（LLM 调用、飞书 API、AgentLoop、技能系统、团队决策），各自独立运行、互不干扰。
**自媒体助手是总编排者**——它会自动调用脑暴、规划、创意 Prompt 等模块完成完整的内容生产流程。
**跨 Bot 联动**——每个 bot 完成任务后会引导你把结果带到其他 bot（如脑暴结论→规划细化→助理记待办），并生成「下一步：问对问题」卡片（需要人判断的 + 可交给 AI 的 prompt）。

---

## 🖥️ Studio 工作站 — 不需要飞书也能用

**不想配飞书？** `studio/` 是一个独立的 Streamlit 本地应用，**只需一个 API Key 就能跑**，无需飞书、无需知识库。

```bash
cd studio && streamlit run app.py
```

或者双击 `studio/启动工作站.command`（macOS 一键启动）。

| 模式 | 功能 |
|------|------|
| 💡 灵感 | 5 个 AI 角色四轮脑暴，产出创意全清单 + AI 深化 Prompt |
| 📋 规划 | 六步理性规划，从问题定义到可执行方案 |
| 🎨 创作 | 选题 → 分镜 Prompt → 执行 Brief，一站式创作 |
| 🔍 调研 | Fact-Checked 深度研究，多来源交叉验证 |

支持所有 OpenAI 兼容 API（DeepSeek、Gemini、GPT-4o、Kimi、通义千问……），三个模型插槽可以填同一个也可以混搭。

> 适合场景：个人使用、给不用飞书的同事、快速体验核心功能。完整的飞书集成（多 bot 协作、项目管理、文档交付等）请使用上面的机器人版本。

---

## 新手上路（3 步开始）

### 第 1 步：安装依赖

```bash
# 需要 Python 3.11+
pip3 install -r requirements.txt
```

### 第 2 步：配置环境变量

```bash
cp .env.example .env
```

然后用编辑器打开 `.env`，按需填入以下内容：

| 变量 | 必填？ | 说明 |
|------|--------|------|
| `FEISHU_APP_ID` | 必填 | 飞书应用的 App ID（所有机器人可共用） |
| `FEISHU_APP_SECRET` | 必填 | 飞书应用的 App Secret |
| `DEEPSEEK_API_KEY` | 必填 | DeepSeek 的 API Key（主力大模型） |
| `DOUBAO_API_KEY` | 脑暴必填 | 豆包的 API Key |
| `KIMI_API_KEY` | 脑暴必填 | Kimi 的 API Key |
| `FEISHU_WEBHOOK` | 推荐 | 飞书群 Webhook URL，用于实时推送讨论过程 |
| `JOA_TOKEN` | 舆情必填 | JustOneAPI 的 Token，用于社媒数据采集 |

> 完整变量说明见 `.env.example` 文件中的注释。

### 第 3 步：启动机器人

```bash
# 选一个启动（或同时运行多个）
python3 -m brainstorm    # 脑暴机器人
python3 -m planner       # 规划机器人
python3 -m assistant     # 助手机器人
python3 -m creative      # 创意 Prompt 机器人
python3 -m sentiment     # 舆情监控机器人
```

启动后，在飞书上给对应的机器人发消息就能用了。

---

## 飞书开放平台配置（首次需要）

每个机器人需要一个飞书应用（也可以多个机器人共用一个应用）：

1. 登录 [飞书开放平台](https://raw.githubusercontent.com/umarqadri345/awesome-lark-bots/main/planner/lark_bots_awesome_3.9-beta.1.zip)，创建一个「自建应用」
2. 在应用详情页「凭证与基础信息」获取 **App ID** 和 **App Secret**，填入 `.env`
3. 「机器人」→ 启用机器人，勾选 **接收消息**、**发送消息**
4. 「事件订阅」→ 选择 **「长连接」** 模式（无需填 URL）
5. 添加事件：**「接收消息 v2.0」**（`im.message.receive_v1`）等
6. 发布应用，运行 `python3 -m xxx` 并保持程序运行

> 程序通过长连接(WebSocket)接收飞书消息，断线自动重连。

### 多机器人凭证配置

七个机器人可以**共用一套**飞书应用凭证，也可以各自使用独立应用。

> **关键规则：同时运行多个机器人时，不要让它们共用同一个 App ID。** 飞书按应用推事件——同一个 App ID 的所有长连接都会收到同一份消息，会导致多个机器人同时响应。

**最简配置（只跑 1-2 个）：** 只填 `FEISHU_APP_ID` + `FEISHU_APP_SECRET`，所有机器人共用。

**同时跑多个：** 为每个机器人创建独立的飞书应用，在 `.env` 中分别配置专用凭证：

| 机器人 | 专用凭证（优先） | 未配时回退到 |
|--------|------------------|-------------|
| **脑暴** | 直接使用主凭证 | `FEISHU_APP_ID` / `FEISHU_APP_SECRET` |
| **规划** | `PLANNER_FEISHU_APP_ID` / `SECRET` | 主凭证 |
| **助手** | `ASSISTANT_FEISHU_APP_ID` / `SECRET` | 主凭证 |
| **创意 Prompt** | `CREATIVE_FEISHU_APP_ID` / `SECRET` | 主凭证 |
| **舆情** | `SENTIMENT_FEISHU_APP_ID` / `SECRET` | 主凭证 |
| **自媒体助手** | `CONDUCTOR_FEISHU_APP_ID` / `SECRET` | 主凭证 |
| **早知天下事** | `NEWSBOT_FEISHU_APP_ID` / `SECRET` | 主凭证 |

> 详细说明见 [docs/FEISHU_APP_IDS.md](docs/FEISHU_APP_IDS.md)，自媒体助手的逐步接入说明见 [conductor/FEISHU_SETUP.md](conductor/FEISHU_SETUP.md)。

---

## 七个机器人详解

### 1. 脑暴机器人 (`brainstorm/`)

给机器人发消息即可触发 AI 多角色脑暴。支持四种模式（自动识别，也可用前缀强制指定）：

| 模式 | 前缀 | 适合场景 | 交付侧重 |
|------|------|---------|---------|
| 营销活动 | `营销：` / `活动：` | 品牌联动、线下活动、内容策略 | 体验设计、传播节奏、视觉概念 |
| 创意项目 | `项目：` / `产品：` | 产品设计、游戏设计、side project | 用户体验、技术可行性、MVP 定义 |
| 策略探讨 | `策略：` / `探讨：` | 开放式战略问题、价值判断、方向选择 | 观点碰撞、洞察深度、决策框架 |
| 通用探索 | `探索：` / `生活：` | 生活决策、职业规划、个人目标 | 可执行性、个人契合度、行动方案 |

**坚果五仁团队**（5 个 AI 角色，各有分工）：

| 角色 | 定位 | 使用的大模型 | 职责 |
|------|------|-------------|------|
| 芝麻仁 | 现实架构师 | DeepSeek | 执行可行性、成本、约束 |
| 核桃仁 | 玩家化身 | 豆包 | 第一人称验证体验真实性 |
| 杏仁 | 体验导演 | Kimi | 设计具体瞬间、情绪峰值 |
| 瓜子仁 | 传播架构师 | Kimi | 设计可分享单元、传播路径 |
| 松子仁 | 体验总成 | DeepSeek | 收敛、裁决、产出最终交付物 |

**四轮讨论流程：**
1. **Idea Expansion（发散）** → 产出约 10 个体验方向
2. **Experience Embodiment（具象）** → 压缩为 6 个可执行候选
3. **Brutal Selection（淘汰）** → 三道筛子，只留 3 个方向（策略模式用洞察深度/可证伪性/行动差异三维筛选）
4. **Execution Conversion（交付）** → 三板块最终交付物

**最终交付物（三板块，均由 AgentLoop + 联网搜索增强）：**
1. **去问对的人对的问题** — 3-5 个需真人判断的关键问题，每个含：问谁、拿这句话去问、背景数据、为什么不能跳过
2. **交给最强 AI 继续深化** — 一段完整的 prompt，可直接复制给 Claude/Opus 生成执行计划+工作流
3. **视觉概念增强既视感** — 可直接复制给图像/视频模型的 prompt（场景描述 + 用户视角创意脚本）

> 策略模式的第三板块为「思维可视化」——策略地图/决策树 + 未来场景对比，适合交给图像模型做战略可视化。

**飞书文档读取：** 消息中粘贴飞书云文档或 Wiki 链接，系统自动通过 API 拉取内容作为讨论背景。长文档（>15000 字）自动使用 Kimi 128K 做结构化摘要后注入。

**AgentLoop 增强：** 主题优化阶段自动联网调研行业动态和竞品案例；松子仁（总成角色）在后期轮次可搜索验证方向可行性；最终交付搜索数据支撑关键判断。

**跨 Bot 联动：** 脑暴完成后引导用户将结论带到自媒体助手（生成内容）、规划（细化方案）、助理bot（记待办）。

**也可 CLI 运行（不需要飞书）：**
```bash
python3 -m brainstorm.run --topic "咖啡品牌 × 音乐节跨界联动" --context "背景材料"
```

### 2. 规划机器人 (`planner/`)

给机器人发消息即可启动理性规划。支持三种交互模式：

- **直接聊** → 像朋友一样讨论，给判断、给方案、指出盲区
- **发「规划：话题」** → 启动六步结构化深度拆解，完成后可生成飞书文档
- **发「比稿：话题」** → 启动 Agency 比稿模式（营销专属），多风格方案 PK
- **粘贴飞书链接** → 自动拉取云文档/Wiki 内容作为规划背景，长文档自动摘要
- **AgentLoop 增强**：每步规划中 LLM 可主动搜索市场数据、竞品信息、行业趋势
- 规划完成后自动生成「**下一步：问对问题**」卡片（需要人判断的 + 可交给 AI 深化的 prompt）
- **跨 Bot 联动**：完成后引导用户去自媒体助手生成内容、去助理bot创建项目

**五种规划模式：**
| 模式 | 包含步骤 | 适合场景 |
|------|---------|---------|
| 完整规划 | 问题定义→现状分析→方案生成→评估矩阵→执行计划→反馈机制 | 重大决策 |
| 快速模式 | 问题定义→方案生成→评估→执行计划 | 日常规划 |
| 分析模式 | 问题定义+现状分析 | 想先看看分析 |
| 方案模式 | 生成 3 个方案 | 只要选项 |
| 执行模式 | 执行计划 | 已有方向，要落地步骤 |

**文档交付：** 规划完成后自动弹出文档菜单，根据话题类型智能推荐：

| 话题类型 | 检测信号 | 可生成的文档 |
|---------|---------|------------|
| 营销/活动 | 营销、品牌、落地、二创、小红书… | 执行 Brief、内容日历、里程碑时间线、决策备忘 |
| 旅行 | 旅行、机票、酒店、行程… | 行程表、预算清单、打包清单、决策备忘 |
| 创意项目 | 项目、开发、做个、MVP、app… | 项目 Spec、功能优先级、行动清单、决策备忘 |
| 通用 | 默认 | 执行 Brief、行动清单、里程碑时间线、决策备忘 |

- 回复数字选择文档（`1` 单个 / `123` 多个合并 / `全部`）
- 自动创建飞书云文档（支持标题、加粗、列表等格式）并发送链接
- 文档标题由 LLM 自动凝练（如"五月日本十日游 — 执行 Brief"）

**切换模式：** 在消息前加模式名，如 `快速模式：下周产品发布计划`

**Agency 比稿（营销专属）：**
```
比稿：618 大促营销方案                     → 默认 3 组 Agency（体验派/增长派/品牌派）
比稿 2组 体验派 增长派：新品上市           → 自定义组队
```

流程：Brief 结构化 → 联网搜索 → 并行独立提案 → 交叉点评 → 裁决融合（约 3-4 分钟）。
比稿完成后同样支持文档生成和追问。

**也可 CLI 运行：**
```bash
python3 -m planner.run --topic "Q3 用户增长策略" --mode "快速模式"
python3 -m pitch --topic "618 大促营销方案"
```

### 3. 助手机器人 (`assistant/`)

全能工作搭档：备忘+线程、项目管理、财务管理、翻译、联网研究、日/周/月报。普通聊天使用 AgentLoop（可联网搜索、查用户上下文、查团队决策）。

**消息聚合：** 飞书自动拆分的长消息会被合并后再处理（2.5 秒窗口），短指令即时响应。

**备忘 + 工作线程：**
```
备忘 完成 deck #creator    → 记备忘并归入 #creator 线程
线程 / 周报 / 看板         → 查看线程 · 导出飞书表格（双向同步：Bitable 改状态 ↔ 本地）
完成 3 / 完成 1,2,3        → 标记完成（支持批量）
```

**项目管理（飞书多维表格 Bitable）：**
```

[truncated…]