1. 项目背景与核心价值
去年在开发一个需要频繁调用AI代码生成工具的项目时，我发现一个痛点：每次在终端使用Claude Code/Codex CLI时，都需要守在电脑前等待结果，遇到需要人工确认的环节（比如选择生成方案、批准执行敏感操作）时尤其麻烦。更糟的是，当我在外面用手机时，完全无法参与这个流程。
这个开源项目就是为了解决这个痛点而生。它通过飞书机器人搭建了一个桥梁，让所有CLI交互都能在飞书App上完成。想象一下这样的场景：你在服务器上运行了一个需要人工确认的代码生成命令，此时飞书会立即弹出消息通知，你直接在手机上点击按钮就能完成确认，生成结果会自动同步回终端。
核心优势体现在三个维度：
- 跨设备协作：所有需要人工介入的环节都转移到飞书，开发者不再被绑定在终端前
- 审批流整合：敏感操作可以设置多级审批，直接在飞书聊天中完成
- 历史可追溯：所有交互记录自动保存在飞书，方便后续审计
2. 技术架构解析
2.1 整体通信流程
系统采用典型的双向通信架构：
code复制终端CLI -> 本地中转服务 -> 飞书机器人服务 <- 飞书App
↖_________________________↙
关键组件说明：
- CLI包装层：拦截原生Claude Code/Codex CLI的输出，将需要交互的内容通过HTTP API转发
- 本地中转服务：使用Go编写的常驻进程，负责：
- 维护WebSocket长连接
- 会话状态管理
- 超时重试机制
- 飞书机器人服务：部署在公网的可访问服务（可用云函数实现），处理：
- 飞书开放平台的事件订阅
- 消息卡片渲染
- 用户操作响应
2.2 飞书消息卡片设计
交互的核心载体是飞书的交互式消息卡片。我们针对不同场景设计了多种卡片模板：
代码选择场景：
json复制{
"header": {"title": "请选择生成方案"},
"elements": [
{
"tag": "div",
"text": {"content": "方案1：使用递归实现", "tag": "lark_md"}
},
{
"actions": [
{"tag": "button", "text": "选择", "type": "primary", "value": "opt1"}
]
}
]
}
敏感操作审批场景：
json复制{
"config": {"wide_screen_mode": true},
"elements": [
{
"tag": "markdown",
"content": "⚠️ 即将执行数据库迁移操作\n\n**SQL**:\n```sql\nALTER TABLE users DROP COLUMN phone;\n```"
},
{
"tag": "action",
"actions": [
{"tag": "button", "text": "批准执行", "type": "danger", "value": "approve"},
{"tag": "button", "text": "拒绝", "value": "reject"}
]
}
]
}
2.3 会话状态管理
采用Redis存储会话上下文，数据结构设计如下：
python复制{
"session_id": "abcd1234",
"cli_pid": 12345, # 本地CLI进程ID
"expire_at": 1698765432, # 过期时间戳
"context": { # 业务上下文
"current_step": "waiting_for_approval",
"available_options": ["opt1", "opt2"],
"last_code": "def foo():\n return 42"
}
}
3. 详细部署指南
3.1 前置条件准备
-
飞书开发者账号
- 在飞书开放平台创建企业自建应用
- 获取App ID和App Secret
- 配置事件订阅（需准备公网可访问的URL）
-
本地环境要求
- Python 3.8+（用于CLI包装层）
- Go 1.18+（用于中转服务）
- Redis 6.0+（会话存储）
3.2 核心组件安装
中转服务安装：
bash复制git clone https://github.com/your-repo/feishu-cli-bridge.git
cd feishu-cli-bridge/server
go build -o bridge
./bridge --config config.yaml
CLI包装层安装：
bash复制pip install feishu-cli-adapter
export CLAUDE_CODE_WRAPPER=feishu_adapter
3.3 飞书机器人配置
在config.yaml中配置飞书凭证：
yaml复制feishu:
app_id: cli_xxxxxxxx
app_secret: xxxxxxxxxxxx
verification_token: xxxxxxxx
encrypt_key: xxxxxxxx
redis:
addr: "localhost:6379"
password: ""
db: 0
需要特别配置的权限：
- 获取用户发给机器人的单聊消息
- 发送消息给单个用户
- 上传文件（用于返回生成结果）
4. 实战使用示例
4.1 基础代码生成流程
当执行常规代码生成时：
bash复制claude-code generate --lang python "实现快速排序"
飞书端会收到包含多个选项的消息卡片：
code复制[代码生成请求]
语言: Python
描述: 实现快速排序
方案1: 传统递归实现
方案2: 使用尾递归优化
方案3: 迭代实现
[选择按钮]
选择后，结果会实时显示在终端，同时完整代码会以飞书文档链接形式返回。
4.2 敏感操作审批场景
执行可能危险的操作时：
bash复制codex-cli db migrate --auto
触发审批流程：
code复制[数据库迁移审批]
操作类型: 自动迁移
影响表: users, orders
预估耗时: 2分钟
SQL预览:
ALTER TABLE users ADD COLUMN last_login TIMESTAMP;
CREATE INDEX idx_orders_user ON orders(user_id);
[批准] [拒绝] [修改后批准]
4.3 团队协作模式
在团队环境中，可以配置级联审批：
yaml复制# .codex-approval.yaml
approval_flows:
db_migration:
steps:
- role: developer
timeout: 10m
- role: dba
required: 2
timeout: 1h
production_deploy:
steps:
- role: tech_lead
- role: security
5. 高级配置与优化
5.1 安全加固方案
-
操作二次确认：对高风险操作强制要求输入验证码
python复制def generate_verification_code(): return str(random.randint(100000, 999999)) -
审批链签名：使用HMAC对审批操作签名
go复制func SignApproval(sessionID string, action string) string { h := hmac.New(sha256.New, []byte(secret)) h.Write([]byte(fmt.Sprintf("%s|%s", sessionID, action))) return hex.EncodeToString(h.Sum(nil)) } -
操作审计日志：所有审批记录落盘存储
sql复制CREATE TABLE cli_audit_log ( id BIGSERIAL PRIMARY KEY, session_id VARCHAR(64) NOT NULL, action_type VARCHAR(32) NOT NULL, operator VARCHAR(128) NOT NULL, operated_at TIMESTAMPTZ NOT NULL, context JSONB );
5.2 性能优化技巧
-
本地缓存策略：对高频访问的配置信息使用内存缓存
go复制type ConfigCache struct { sync.RWMutex data map[string]interface{} ttl time.Duration } -
消息压缩传输：对大型代码块进行gzip压缩
python复制import zlib def compress_code(code: str) -> bytes: return zlib.compress(code.encode(), level=6) -
连接池优化：调整Redis连接池参数
yaml复制redis: pool_size: 20 min_idle_conns: 5 max_retries: 3 dial_timeout: 500ms
6. 常见问题排查
6.1 消息未及时同步
症状：终端已执行命令，但飞书未收到通知
排查步骤：
- 检查中转服务日志：
bash复制
journalctl -u feishu-bridge -n 50 --no-pager - 验证飞书事件订阅状态：
bash复制curl -X POST https://open.feishu.cn/open-apis/event/v1/check \ -H "Authorization: Bearer {access_token}" - 测试Redis连接：
bash复制
redis-cli ping
6.2 审批操作超时
典型原因：
- 网络延迟导致消息往返时间过长
- Redis响应缓慢
- 飞书API限流
解决方案：
- 调整超时配置：
yaml复制timeouts: default: 300s # 默认超时 critical: 600s # 关键操作超时 - 实现心跳检测：
go复制func startHeartbeat(sessionID string) { ticker := time.NewTicker(30 * time.Second) defer ticker.Stop() for range ticker.C { redisClient.Expire(ctx, sessionKey(sessionID), 5*time.Minute) } }
6.3 移动端显示异常
常见问题：
- 代码块在手机端换行混乱
- 交互按钮错位
- 图片预览失败
调试方法：
- 使用飞书开发者工具预览消息卡片：
bash复制
feishu-tool preview-card card.json - 响应式设计建议：
json复制{ "config": { "wide_screen_mode": true, "enable_forward": true }, "elements": [ { "tag": "div", "text": { "content": "```python\n# 代码自动适配移动端显示\ndef hello():\n return 'world'\n```", "tag": "lark_md" } } ] }
7. 扩展应用场景
7.1 CI/CD集成
在GitLab CI中审批部署：
yaml复制deploy_prod:
stage: deploy
script:
- codex-cli deploy --env prod --require-approval
rules:
- if: $CI_COMMIT_BRANCH == "main"
审批通过后自动继续执行后续步骤。
7.2 多因素认证
敏感操作增加OTP验证：
python复制from pyotp import TOTP
def verify_otp(user_id, code):
secret = get_user_otp_secret(user_id)
totp = TOTP(secret)
return totp.verify(code)
7.3 数据科学工作流
Jupyter notebook集成：
python复制from feishu_cli import require_approval
@require_approval("data_load")
def load_production_data():
# 从生产环境加载数据
...
8. 项目维护建议
8.1 监控指标配置
建议监控的关键指标：
- 消息往返延迟（P99 < 2s）
- 审批超时率（< 1%）
- 飞书API调用错误率（< 0.5%）
Prometheus配置示例：
yaml复制scrape_configs:
- job_name: 'feishu_bridge'
static_configs:
- targets: ['localhost:9091']
8.2 升级策略
采用蓝绿部署方案：
- 新版本部署到备用环境
- 逐步迁移会话流量
- 监控错误率变化
- 完成切换后下线旧版本
回滚检查清单：
- 数据库schema兼容性
- 飞书API版本支持
- 客户端CLI版本要求
8.3 社区贡献指南
欢迎贡献的领域：
- 新的消息卡片模板
- 第三方CLI适配器
- 审计插件开发
代码提交规范：
- 分支命名：
feat/xxx或fix/xxx - 提交信息遵循Conventional Commits
- 新增功能需包含测试用例
- 文档同步更新