cclark 文档

cclark 是 unified-icc 网关的飞书前端。它通过飞书事件长连接接收群聊或话题消息，把文本转发给 unified-icc 管理的 tmux 后端 AI 编程助手，并将输出以文本或交互卡片形式发回飞书。

架构概览:

飞书群/话题
       │  WebSocket 事件
       ▼
┌─────────────────────┐
│  FeishuWSClient     │  ws_client.py
└──────────┬──────────┘
           │ FeishuMessageEvent
           ▼
┌─────────────────────┐
│  handlers/message.py│  #help / #new / #status / #verbose
│  session_creation.py│  #mkdir / provider / mode
└──────────┬──────────┘
           │ create_window / send_to_window
           ▼
┌─────────────────────┐
│  unified-icc         │  tmux + provider + monitor
└──────────┬──────────┘
           │ on_message / on_status
           ▼
┌─────────────────────┐
│  FeishuAdapter      │  text / card / screenshot
└──────────┬──────────┘
           │ REST API
           ▼
      飞书消息

核心能力

• 每聊天一会话：每个飞书聊天绑定一个 cclark 管理的 tmux 窗口，#new 会清理同聊天旧窗口。

• 文本向导：#new 进入目录 / provider / mode 向导，目录阶段支持 #mkdir <name>。

• 显式帮助：#help 随时可用；无会话时普通消息返回帮助而不是隐式启动 Claude。

• 详细流式输出：#verbose on 使用交互卡片展示 regular output 和 thinking output。

• 权限提示桥接：Claude terminal permission prompt 会显示为飞书卡片，当前通过回复卡片中列出的编号操作。

• 多智能体支持：Claude Code、Codex、Gemini CLI、Pi、Shell。

目录

• 安装
  • 环境要求
  • 从源码安装
  • 将 cclark 安装为 CLI
  • 验证安装
  • 配置飞书机器人
  • 配置文件
• 配置参考
  • 配置来源
  • FeishuConfig 单例
  • 频道 ID 模型
  • 工具栏 TOML 配置
• 架构设计
  • 系统层级
  • 关键数据流
  • 状态和持久化
  • 权限模式
  • 启动顺序
• 模块参考
  • feishu_client — 飞书 REST API 客户端
  • config — 配置单例
  • adapter — FeishuAdapter（FrontendAdapter 实现）
  • webhook — HTTP Health-Check Server
  • event_parsers — 飞书 JSON → FeishuMessageEvent
  • state — 流式状态和工具栏状态
  • user_preferences — 用户 MRU 目录和读取偏移量
  • handlers — 事件处理器模块
  • cards — 飞书卡片构建器
  • main — CLI 入口点
• 故障排查
  • 启动失败
  • 飞书 WebSocket 事件
  • 目录浏览器 / 会话创建
  • 智能体相关

快速开始

mkdir -p ~/.unified-icc
cp config.yaml.example ~/.unified-icc/config.yaml
# 填入 app_id / app_secret
cclark

飞书内发送：

#help
#new

相关项目

项目	说明
unified-icc	核心网关 — tmux 会话、provider、窗口和 transcript 管理
ccgram	原始 Telegram 前端（上游参考）

索引和表格

• {ref}`genindex`

• {ref}`modindex`

• {ref}`search`