Feishu Claude Agent

飞书机器人 + Claude Agent SDK 完整功能版。让 Claude 通过飞书帮你处理文件、执行命令、搜索代码等任务。

架构

┌─────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  飞书机器人  │ ──→ │  FastAPI 服务器   │ ──→ │ Claude Agent SDK │
│  接收消息    │ ←── │  消息路由/转发    │ ←── │  执行任务        │
└─────────────┘     └──────────────────┘     └─────────────────┘

功能

• ✅ 接收飞书消息并回复
• ✅ Claude Agent 执行复杂任务
• ✅ 文件读取、编辑、创建
• ✅ 终端命令执行
• ✅ 代码库搜索
• ✅ 网络搜索
• ✅ 会话持续（多轮对话）
• ✅ 多用户并发支持
• ✅ 安全认证和速率限制

快速开始

方式一：Docker 部署（推荐）

# 克隆项目
git clone https://github.com/yourusername/feishu-claude-agent.git
cd feishu-claude-agent

# 复制配置文件
cp .env.example .env

# 编辑配置
vim .env

# 启动服务
docker-compose up -d

方式二：本地运行

1. 安装依赖

确保已安装 uv（推荐的 Python 包管理器）：

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# 或使用 pip
pip install uv

克隆项目并安装依赖：

git clone https://github.com/yourusername/feishu-claude-agent.git
cd feishu-claude-agent
uv sync

2. 配置环境变量

复制配置模板：

cp .env.example .env

编辑 .env 文件，填入你的配置：

# 必填配置
FEISHU_APP_ID=cli_xxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxx
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxx

# 安全配置（强烈建议配置）
ADMIN_API_KEY=your-secure-admin-key-here

# 工作目录
WORK_DIR=/Users/你的用户名/projects

3. 创建飞书应用

1. 访问 飞书开放平台
2. 创建企业自建应用
3. 开启「机器人」能力
4. 配置事件订阅：
   • 事件订阅地址：http://你的服务器地址:8080/webhook
   • 订阅事件：im.message.receive_v1（接收消息）
5. 获取 App ID 和 App Secret 填入 .env

4. 启动服务

# 使用 uv 运行
uv run python -m feishu_claude_agent

# 或者激活虚拟环境后直接运行
source .venv/bin/activate  # macOS/Linux
python -m feishu_claude_agent

5. 本地测试（可选）

如果需要在本地测试，可以使用 ngrok 暴露服务：

# 安装 ngrok
brew install ngrok  # macOS

# 启动隧道
ngrok http 8080

将 ngrok 提供的 URL（如 https://xxx.ngrok.io/webhook）填入飞书事件订阅地址。

配置说明

必填配置

配置项	说明
FEISHU_APP_ID	飞书应用 App ID
FEISHU_APP_SECRET	飞书应用 App Secret
ANTHROPIC_API_KEY	Anthropic API Key

安全配置

配置项	说明	默认值
ADMIN_API_KEY	管理 API 密钥，保护 /sessions 端点	无（端点禁用）
MAX_MESSAGE_LENGTH	最大消息长度（字符）	10000
RATE_LIMIT_PER_MINUTE	每用户每分钟请求限制	60
CLAUDE_PERMISSION_MODE	Agent 权限模式	auto

权限模式说明

模式	说明	安全性
interactive	用户确认所有操作	最高
auto	自动执行，危险操作需确认	中等（推荐）
acceptEdits	自动执行所有操作	最低（不推荐生产使用）

使用方法

在飞书中向机器人发送消息：

• 直接发消息：Claude 会处理并回复
• /help - 显示帮助
• /clear - 清除对话历史
• /status - 查看会话状态

管理 API

使用 ADMIN_API_KEY 访问管理端点：

# 查看所有会话
curl -H "X-Admin-Key: your-admin-key" http://localhost:8080/sessions

# 清除特定用户会话
curl -X DELETE -H "X-Admin-Key: your-admin-key" http://localhost:8080/sessions/user_open_id

项目结构

feishu-claude-agent/
├── .github/workflows/       # CI/CD 工作流
├── src/feishu_claude_agent/
│   ├── __init__.py          # 包入口
│   ├── __main__.py          # 运行入口
│   ├── config.py            # 配置管理
│   ├── server.py            # FastAPI 服务器
│   ├── feishu_handler.py    # 飞书消息处理
│   ├── claude_agent.py      # Claude Agent 封装
│   ├── session_manager.py   # 会话管理
│   └── validators.py        # 输入验证
├── tests/                   # 测试文件
├── Dockerfile               # Docker 构建
├── docker-compose.yml       # Docker Compose 配置
├── pyproject.toml           # 项目配置
├── .env.example             # 环境变量模板
└── README.md                # 说明文档

安全注意事项

⚠️ 重要安全提示：

1. 配置 ADMIN_API_KEY：未配置时，管理端点会返回 503 错误
2. 限制 WORK_DIR：Claude Agent 只能操作指定目录下的文件
3. 选择权限模式：生产环境建议使用 auto 或 interactive
4. 保护 API Key：不要将 .env 文件提交到版本控制
5. 配置签名验证：设置 FEISHU_VERIFICATION_TOKEN 验证请求来源

开发

运行测试

# 安装开发依赖
uv sync --dev

# 运行测试
uv run pytest --cov=src --cov-report=term-missing

# 代码检查
uv run ruff check src/ tests/

扩展开发

添加自定义工具

在 claude_agent.py 中修改 allowed_tools 列表：

allowed_tools=[
    "Read", "Write", "Edit", "Bash",
    "Glob", "Grep", "WebSearch", "WebFetch",
    # 添加更多工具...
]

修改系统提示词

编辑 claude_agent.py 中的 system_prompt：

system_prompt="""你的自定义提示词..."""

故障排查

常见问题

1. 机器人无响应

   • 检查服务是否正常运行：curl http://localhost:8080/health
   • 检查飞书事件订阅配置是否正确

2. 签名验证失败

   • 确认 FEISHU_VERIFICATION_TOKEN 配置正确
   • 检查飞书请求头中的签名信息

3. 权限错误

   • 检查 WORK_DIR 是否存在且可访问
   • 确认运行用户有足够的权限

获取帮助

• Claude Agent SDK 文档
• 飞书开放平台
• lark-oapi Python SDK

贡献

欢迎提交 Issue 和 Pull Request！请阅读 CONTRIBUTING.md 了解详情。

License

MIT