cc-connect 架构与设计思路分析

原文：raw/cc-connect-architecture-analysis.md · 仓库：https://github.com/chenhg5/cc-connect · 分析版本 HEAD c53f545（2026-06-10）

一句话定位

把本地 AI coding agent 连接到飞书、钉钉、Slack、Telegram、Discord、企业微信等消息平台的 Go bridge。它的核心是 Engine 把 platform message 转成 agent session 输入，并把 agent event/usage/attachment 转回聊天平台。这页和 claude-code codex ai-agent-plugin-patterns open-cowork 形成对比，重点帮助理解项目边界和选型位置。

核心架构图

┌──────────────── Messaging Platforms ────────────────┐
│ Feishu / Slack / Telegram / DingTalk / Discord / ... │
└──────────────┬───────────────────────────────────────┘
               │ platform adapter normalizes message
               v
┌──────────────────────────────┐
│ core.Engine                   │
│ sessions, queue, display, TTS,│
│ attachments, roles, heartbeat │
└───────┬───────────────┬──────┘
        │               │ optional relay/provider proxy
        v               v
┌──────────────────┐  ┌──────────────────────────────┐
│ Agent adapters    │  │ RelayManager / ProviderProxy  │
│ Claude/Codex/etc. │  │ bot-to-bot, request rewrite   │
└────────┬─────────┘  └──────────────────────────────┘
         │ CLI process / appserver / PTY
         v
┌──────────────────────────────────────────────────────┐
│ Local coding agent process and workspace             │
└──────────────────────────────────────────────────────┘

模块分层

层 / 模块	职责
CLI/daemon	读取 config、注册 agent/platform plugin、管理 daemon/restart/cron/send/provider 子命令。
核心 Engine	维护 project engine、session manager、消息队列、display/tts/attachment/usage footer。
Agent adapter	封装 Claude Code/Codex/Gemini/Cursor/Pi 等 CLI session、stdin/stdout/appserver/usage。
Platform adapter	把不同聊天平台的 webhook/long poll/socket 统一成 core.MessageHandler 调用。
Relay/provider/web	支持 bot-to-bot relay、Anthropic-compatible provider 字段重写和 web 管理界面。

关键数据流

Telegram message arrives
  │
  ├─ platform/telegram reconstructs reply context and checks allow_from
  │
  ├─ core.Engine chooses or creates project session and rate-limit queue
  │
  ├─ agent/codex or agent/claudecode sends prompt to local CLI/appserver
  │
  ├─ streaming events become platform text/card/attachment updates
  │
  └─ session state, usage footer, heartbeat and relay metadata are persisted

设计决策与哲学

双插件注册模型：agent 和 platform 分别通过 build-tag/plugin 文件注册，主程序不需要硬编码所有平台逻辑。
Engine 统一消息语义：core.Engine 是平台无关层，处理 session、队列、display、attachment 和 usage，降低每个平台 adapter 的复杂度。
ProviderProxy 是兼容性 shim 而非完整 gateway：providerproxy.go 只做 Anthropic thinking 字段重写等窄修复，适合本地 CLI 兼容，不承担多租户网关治理。

与同类项目的架构差异

维度	cc-connect	同类 A	同类 B
定位	消息平台远程驱动 coding agent	open-cowork: desktop host + sandbox	claude-tap: traffic observation
控制平面	Go daemon + config.toml	Electron/desktop UI	Python CLI proxy
风险边界	聊天平台权限与本地 agent 权限相连	本地 GUI/sandbox	本地 MITM/trace 数据

选型提示

如果你在快速理解或选型，先判断它是“执行任务的 agent/runtime”、“观察与计量工具”、“消息/插件 bridge”，还是“Kubernetes/GPU 控制面”。同一条 star 列表里的项目经常解决的是相邻但不同的问题：比如 trace viewer 不能替代 remote control bridge，GPU Operator 也不能替代 DRA driver 或 device plugin 的分配路径。