cc-connect 飞书接入实践

概述

Claude Code 与飞书的集成分两个方向：

• 主动调用：Claude Code 通过 Lark MCP 主动调用飞书 API（发消息、读文档），见 Claude Code 集成飞书文档方案
• 被动响应（本文）：飞书群成员 @Bot 发指令，Bot 自动响应——通过 cc-connect 建立 WebSocket 长连接实现

本文记录被动响应的完整接入实践。核心要点：创建隔离的 Bot 工作空间，避免暴露源码仓库。

架构

飞书群 @MyBot "看看大家手上的任务"
    ↓ WebSocket 长连接（无需公网 IP）
cc-connect 守护进程
    ↓ spawn claude CLI（work_dir = bot 工作空间）
    ├── CLAUDE.md（角色指令）
    ├── .mcp.json（Jira + Lark MCP）
    ├── .claude/（commands + skills + team-registry）
    └── jira/（本地问题管理）
    ↓
cc-connect → 飞书回复

Bot 工作空间隔离

关键设计：Bot 不应直接运行在源码仓库中，需要独立工作空间。

project-root/
├── src/                # 源码（Bot 不可见）
├── other-modules/      # 源码（Bot 不可见）
├── CLAUDE.md           # 开发用
├── .claude/            # 开发用
└── bot-workspace/      # Bot 独立工作空间
    ├── .git/           # 独立 git 仓库（关键！）
    ├── CLAUDE.md       # Bot 专用角色指令
    ├── .mcp.json       # MCP 配置副本
    ├── .claude/        # commands/skills/registry 副本
    └── data/           # 迁入的管理数据

必须在 Bot 工作空间 git init：Claude Code 沿目录树向上查找 .git 确定项目根。没有独立 .git 时，Bot 会加载父目录的 CLAUDE.md，导致路径解析错误（如 .claude/team-registry.json 解析到父级目录）。

cc-connect 配置

# ~/.cc-connect/config.toml
[[projects]]
name = "my-bot"
[projects.agent]
type = "claudecode"
[projects.agent.options]
mode = "bypassPermissions"          # Bot 需自主操作，跳过权限确认
work_dir = "/path/to/bot-workspace" # 指向隔离工作空间
 
[[projects.platforms]]
type = "feishu"
[projects.platforms.options]
app_id = "cli_xxx"
app_secret = "your_app_secret"
share_session_in_channel = true     # 群内共享会话
reply_in_thread = true              # 在话题中回复

• work_dir 决定 Claude Code 的项目根目录，Bot 只能看到该目录下的文件
• share_session_in_channel = true：同一群的消息共享 session，保持上下文连续
• reply_in_thread = true：回复到消息话题，不刷屏

飞书开放平台配置

1. 应用需启用「机器人」能力
2. 权限：im:message.group:receive、im:message.p2p:receive、im:message:send_as_bot、contact:user.base:readonly
3. 事件订阅：选择「使用长连接接收事件」，添加 im.message.receive_v1
4. 修改权限/事件后需创建新版本并发布
5. 目标群中需手动添加机器人

踩坑记录

1. Bot 读取了父目录的配置文件

现象：Bot 读取的 team-registry.json 路径是父级 .claude/team-registry.json 而非 Bot 工作空间内的。

原因：Claude Code 沿目录树向上查找 CLAUDE.md 和 .claude/，父级的 CLAUDE.md 被加载，其中的相对路径基于父级项目根解析。

解决：在 Bot 工作空间执行 git init，让 Claude Code 以此为项目根，不再向上查找。

2. 飞书 @Bot 无反应

排查顺序：

1. cc-connect 日志是否显示 platform started project=xxx platform=feishu
2. 飞书开放平台「事件订阅」是否选择了长连接模式
3. 是否添加了 im.message.receive_v1 事件
4. 修改后是否发布了新版本
5. 目标群是否添加了机器人

3. 文件副本同步问题

Bot 工作空间的 .claude/ 和根目录的 .claude/ 是独立副本。修改 team-registry、commands 或 skills 时需两处同步。

相关链接

• cc-connect — 工具概览与架构
• Claude Code 集成飞书文档方案 — Lark MCP 配置（权限、Token 模式、工具预设）
• Claude Code