feishu-claude-code

飞书是遥控器，Claude Code 是在你电脑上真实干活的那只手。出门在外发一条飞书消息，电脑那边就开始跑代码、改文件、读文档。

与同类项目的差异

特性

消息类型全覆盖

• 文本、富文本 (post)、图片、文件 (PDF/Word/Excel/压缩包)、语音 (audio)、转发 (merge_forward)
• 群聊 @机器人 触发，私聊直接对话

飞书文档深度集成

• 文档链接自动识别并获取内容（docx/wiki/sheets/base/mindnotes/minutes）
• 长回复自动写入飞书文档，聊天里只发链接
• 文档评论 @机器人 自动回复
• ⚠️ 隐私提醒：Bot 会自动读取你发送的文档链接内容。群聊中请勿发送含敏感信息的文档链接。

文件回传

• Claude 生成的文件自动上传到飞书 Drive，返回下载链接
• 在回复中写 [[SEND_FILE:./report.md]] 即可触发
• 支持图片、文档、PDF、Excel 等任意文件类型

流式卡片输出

• Claude 实时思考过程可见
• 工具调用进度实时展示
• 支持卡片按钮交互（选项选择、模式切换）

Session 管理

• 跨设备恢复会话（手机上开始，电脑前继续）
• 群聊独立 session，互不干扰
• /ws 为不同群绑定不同工作目录

运维健壮

• 笔记本休眠唤醒自动重连
• DNS/网络抖动自动恢复
• launchd (macOS) / 启动脚本 (Windows) 保活

架构

┌──────────┐  WebSocket  ┌────────────────┐  subprocess  ┌────────────┐
│  飞书 App │◄───────────►│ feishu-bridge   │─────────────►│ claude CLI │
│  (用户)   │  长连接      │  (main.py)      │ stream-json  │  (本机)     │
└──────────┘             └────────────────┘              └────────────┘
                                │
                                │ subprocess (--as user)
                                ▼
                         ┌────────────┐
                         │  lark-cli   │  ← 用户 token，文档/文件/IM 操作
                         └────────────┘

关键设计决策：

• 收消息走 lark-cli WebSocket：App 鉴权，不暴露公网端口
• 发消息走 Python SDK (lark_oapi)：租户 token，流式卡片 patch
• 文档操作走 lark-cli：用户 token，直接以用户身份读写文档，无需额外授权

快速开始

前置条件

1. 飞书应用配置

1. 飞书开放平台 → 创建企业自建应用
2. 添加「机器人」能力
3. 权限管理 → 开启：
   • im:message — 获取与发送消息
   • im:message:send_as_bot — 以应用身份发消息
   • im:resource — 获取消息中资源文件
   • docx:document — 读写云文档
   • docx:document:write_only — 创建和修改文档（文档自动生成功能必需）
   • drive:file:upload — 上传文件
4. 事件与回调 → 使用长连接接收事件 → 添加 im.message.receive_v1
5. 凭证与基础信息 → 复制 App ID 和 App Secret
6. 版本管理与发布 → 创建版本 → 管理员审核通过

2. 安装

git clone https://github.com/H2O-YAOZE/feishu-claude-code.git
cd feishu-claude-code

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt

cp .env.example .env
# 编辑 .env，填入 App ID 和 App Secret

3. lark-cli 登录

npm install -g @larksuite/cli
lark-cli config init
lark-cli auth login --scope "docx:document:write_only drive:file:upload"

4. 启动

# 前台运行
python main.py

# Windows 后台（登录自动启动）
start_bridge.bat

# macOS 后台（launchd 保活）
# 先编辑 deploy/feishu-claude.plist：把 REPO_PATH 改为仓库路径，HOME_PATH 改为你的 home 目录
cp deploy/feishu-claude.plist ~/Library/LaunchAgents/com.zara.feishu-claude.plist
launchctl load ~/Library/LaunchAgents/com.zara.feishu-claude.plist

预期输出：

🚀 飞书 Claude Bot 启动中...
   App ID      : cli_xxx...
✅ 连接飞书 WebSocket 长连接（自动重连）...

命令速查

会话管理

模型与模式

工作目录

环境变量

License

MIT