# https://github.com/chenhg5/cc-connect 项目说明书 生成时间：2026-05-13 23:32:01 UTC ## 目录 - [项目概述](#overview) - [系统架构](#architecture) - [核心接口定义](#core-interfaces) - [Bridge 协议](#bridge-protocol) - [Agent 集成概述](#agent-overview) - [Agent 通信协议](#agent-protocols) - [Claude Code 集成](#claude-code-integration) - [Codex 集成](#codex-integration) - [平台集成概述](#platform-overview) - [飞书集成详解](#platform-feishu) ## 项目概述 ### 相关页面 相关主题：[系统架构](#architecture), [Agent 集成概述](#agent-overview), [平台集成概述](#platform-overview)
相关源码文件 以下源码文件用于生成本页说明： - [AGENTS.md](https://github.com/chenhg5/cc-connect/blob/main/AGENTS.md) - [core/i18n.go](https://github.com/chenhg5/cc-connect/blob/main/core/i18n.go) - [platform/wecom/inbound_file_test.go](https://github.com/chenhg5/cc-connect/blob/main/platform/wecom/inbound_file_test.go) - [web/index.html](https://github.com/chenhg5/cc-connect/blob/main/web/index.html) - [web/src/pages/Providers/ProviderList.tsx](https://github.com/chenhg5/cc-connect/blob/main/web/src/pages/Providers/ProviderList.tsx) - [web/src/pages/Skills/SkillList.tsx](https://github.com/chenhg5/cc-connect/blob/main/web/src/pages/Skills/SkillList.tsx) - [web/src/pages/Sessions/SessionList.tsx](https://github.com/chenhg5/cc-connect/blob/main/web/src/pages/Sessions/SessionList.tsx) - [web/src/pages/Projects/ProjectList.tsx](https://github.com/chenhg5/cc-connect/blob/main/web/src/pages/Projects/ProjectList.tsx) - [web/src/pages/Projects/ProjectDetail.tsx](https://github.com/chenhg5/cc-connect/blob/main/web/src/pages/Projects/ProjectDetail.tsx) - [web/src/pages/Chat/ChatView.tsx](https://github.com/chenhg5/cc-connect/blob/main/web/src/pages/Chat/ChatView.tsx)
# 项目概述 ## 项目简介 cc-connect 是一个多平台 AI 代理连接框架，旨在将不同的 AI 代理服务与多种即时通讯平台进行桥接整合。该项目采用 Go 语言作为后端核心，前端使用 React + TypeScript 构建管理界面，实现了统一配置管理、多平台支持、灵活的代理切换等核心功能。 项目的设计理念是提供一个 **中立的中间层**，使 AI 代理能力能够通过各种通讯平台（如飞书、微信、企业微信、Telegram、Discord 等）与用户进行交互。资料来源：[AGENTS.md:1-15]() ## 系统架构 cc-connect 采用分层架构设计，核心模块与平台模块解耦，便于扩展和维护。 ```mermaid graph TD subgraph 前端层["前端层 (React + TypeScript)"] A[Web 管理界面] B[Provider 管理] C[Project 管理] D[Session 会话] E[Skills 技能] end subgraph 核心层["核心层 (Go)"] F[core - 核心接口定义] G[agent - 代理实现] H[平台注册系统] I[i18n - 国际化] end subgraph 平台层["平台适配层"] J[飞书] K[企业微信] L[微信] M[Telegram] N[Discord] O[Slack] P[DingTalk] Q[更多平台...] end subgraph 外部服务 R[AI Provider] S[LLM API] end A --> F B --> H C --> H D --> H E --> H F --> G F --> H H --> J H --> K H --> L H --> M H --> N H --> O H --> P J --> R K --> R L --> R M --> R R --> S ``` 资料来源：[AGENTS.md:9-18]() ## 核心概念 ### Provider（提供商） Provider 是 AI 模型服务提供商的核心抽象，支持配置多个 AI 模型实例。每个 Provider 可以包含以下配置项： | 配置项 | 说明 | 可选值 | |--------|------|--------| | `name` | 提供商名称 | 字符串 | | `url` | API 端点地址 | URL 字符串 | | `model` | 默认模型标识 | 字符串 | | `models` | 模型列表 | 数组 | | `thinking` | 思考模式 | `enabled` / `disabled` | | `agent_types` | 支持的代理类型 | 字符串数组 | 资料来源：[web/src/pages/Providers/ProviderList.tsx:1-30]() ### Project（项目） Project 是工作空间的基本单位，每个项目包含独立的配置和会话管理。项目支持以下关键配置： | 配置项 | 说明 | 配置选项 | |--------|------|----------| | `workDir` | 工作目录路径 | 用户指定 | | `agentMode` | 权限模式 | `default` / `acceptEdits` / `plan` / `bypassPermissions` / `dontAsk` | | `showCtxIndicator` | 上下文指示器 | 布尔值 | | `replyFooter` | 回复元数据 | 布尔值 | 资料来源：[web/src/pages/Projects/ProjectDetail.tsx:1-40]() ### Session（会话） Session 管理与 AI 代理的交互状态，包含消息历史和实时状态： ```typescript interface Session { id: string; name: string; live: boolean; // 活跃状态 updated_at: string; // 最后更新时间 last_message: { role: 'user' | 'assistant'; content: string; }; } ``` 资料来源：[web/src/pages/Sessions/SessionList.tsx:1-20]() ### Skills（技能） Skills 系统允许扩展 AI 代理的能力，支持本地技能和预设技能库： | 技能类型 | 说明 | 配置项 | |----------|------|--------| | 本地技能 | 项目目录下定义的技能 | `project`, `agent_type`, `dirs` | | 预设技能 | 官方/社区提供的技能包 | `display_name`, `description`, `version`, `pricing` | 资料来源：[web/src/pages/Skills/SkillList.tsx:1-50]() ## 平台支持 cc-connect 支持多种即时通讯平台的集成，构建时可以通过 build tags 选择性排除不需要的平台： | 平台 | Build Tag | 说明 | |------|-----------|------| | 飞书 | 默认启用 | 企业协作平台 | | 企业微信 | `wecom` | 企业微信集成 | | 微信 | `weixin` | 微信消息通道 | | Telegram | `telegram` | 第三方 IM | | Discord | `discord` | 游戏社区平台 | | Slack | `slack` | 企业通讯工具 | | DingTalk | `dingtalk` | 钉钉集成 | | QQ / QQBot | `qq` / `qqbot` | 腾讯 QQ | | LINE | `line` | 台湾地区 IM | | 微博 | `weibo` | 社交媒体 | 禁用特定平台的编译方式：`go build -tags no_feishu no_telegram ...` 资料来源：[AGENTS.md:1-8]() ## 插件系统 cc-connect 采用插件化架构，新增平台或代理只需遵循以下流程： ### 添加新平台 1. 创建 `platform/newplatform/newplatform.go` 2. 实现 `core.Platform` 接口 3. 在 `init()` 中注册：`core.RegisterPlatform("newplatform", factory)` 4. 创建构建插件文件：`cmd/cc-connect/plugin_platform_newplatform.go` 5. 添加到 `Makefile` 的 `ALL_PLATFORMS` 6. 在 `config.example.toml` 添加配置示例 7. 编写单元测试 资料来源：[AGENTS.md:9-18]() ### 添加新代理 1. 创建 `agent/newagent/newagent.go` 2. 实现 `core.Agent` 和 `core.AgentSession` 接口 3. 在 `init()` 中注册：`core.RegisterAgent("newagent", factory)` 4. 创建构建插件文件 资料来源：[AGENTS.md:19-24]() ## 国际化的消息提示 项目内置完整的国际化（i18n）支持，支持以下语言： | 语言 | 代码 | 示例消息 | |------|------|----------| | 英语 | `en` | `Provider not found. Use /provider list` | | 简体中文 | `zh-CN` | `未找到 Provider，使用 /provider list` | | 繁体中文 | `zh-TW` | `未找到 Provider，使用 /provider list` | | 日语 | `ja` | `プロバイダが見つかりません` | | 西班牙语 | `es` | `Proveedor no encontrado` | 关键消息类型包括： - Provider 操作消息（切换、清除、列表） - Workspace 操作消息（绑定、路由） - 错误提示与帮助信息 资料来源：[core/i18n.go:1-60]() ## 前端架构 前端采用 React + TypeScript + TailwindCSS 构建，提供现代化的管理界面： ### 主要页面模块 | 模块 | 路径 | 功能 | |------|------|------| | ProviderList | `/Providers` | 全局 AI 提供商管理 | | ProjectList | `/Projects` | 项目列表与创建向导 | | ProjectDetail | `/Projects/:id` | 单个项目配置与设置 | | SkillList | `/Skills` | 技能管理与预设库 | | SessionList | `/Sessions` | 会话管理与消息历史 | | ChatView | `/Chat` | 实时聊天界面 | ### 状态管理 前端通过 React Hooks 管理状态，关键状态包括： - `providers`: 全局 AI 提供商列表 - `projects`: 项目列表 - `sessions`: 会话列表 - `currentSession`: 当前活跃会话 - `drawerOpen`: 会话抽屉开关状态 - `bridgeStatus`: WebSocket 桥接状态 资料来源：[web/src/pages/Chat/ChatView.tsx:1-30]() ## 消息处理 ### 企业微信文件消息 企业微信平台的文件消息采用 XML 格式传输，系统会解析以下字段： | 字段 | 说明 | |------|------| | `MsgType` | 消息类型（text/image/file 等） | | `MediaId` | 媒体文件 ID | | `FileName` | 文件名（含路径） | | `MsgId` | 消息唯一 ID | | `AgentID` | 企业应用 ID | 资料来源：[platform/wecom/inbound_file_test.go:1-25]() ## 项目构建与测试 ### 构建检查清单 提交代码前必须通过以下检查： 1. **编译通过**：`go build ./...` 2. **测试通过**：`go test ./...` 3. **无硬编码**：核心代码中无平台名称硬编码 4. **国际化完整**：新增用户可见字符串需包含所有语言翻译 5. **无敏感信息**：源码中不包含 API Key、Token 等凭据 资料来源：[AGENTS.md:25-32]() ## 技术栈总结 | 层级 | 技术选型 | |------|----------| | 后端核心 | Go 1.x | | 前端框架 | React 18 + TypeScript | | UI 样式 | TailwindCSS | | 状态管理 | React Hooks | | 国际化 | 自定义 i18n 模块 | | 构建工具 | Vite（前端）+ Makefile（后端） | | 测试框架 | Go testing | 资料来源：[web/index.html:1-10]() ## 设计理念 cc-connect 的核心设计原则： 1. **模块化解耦**：核心接口与平台实现分离，便于独立演进 2. **可插拔架构**：通过 build tags 实现平台按需编译 3. **统一配置管理**：通过 Web UI 或配置文件集中管理所有设置 4. **多语言支持**：内置 5 种语言的国际化消息 5. **开发者友好**：提供清晰的插件开发指南和代码规范 这种设计使得 cc-connect 能够灵活适应不同的部署场景，既可以作为单一平台桥接工具，也可以扩展为完整的多平台 AI 代理中控系统。 --- ## 系统架构 ### 相关页面 相关主题：[项目概述](#overview), [核心接口定义](#core-interfaces), [Bridge 协议](#bridge-protocol)
相关源码文件 以下源码文件用于生成本页说明： - [core/engine.go](https://github.com/chenhg5/cc-connect/blob/main/core/engine.go) - [core/bridge.go](https://github.com/chenhg5/cc-connect/blob/main/core/bridge.go) - [core/registry.go](https://github.com/chenhg5/cc-connect/blob/main/core/registry.go) - [web/src/pages/Providers/ProviderList.tsx](https://github.com/chenhg5/cc-connect/blob/main/web/src/pages/Providers/ProviderList.tsx) - [web/src/pages/Projects/ProjectDetail.tsx](https://github.com/chenhg5/cc-connect/blob/main/web/src/pages/Projects/ProjectDetail.tsx) - [web/src/pages/Sessions/SessionChat.tsx](https://github.com/chenhg5/cc-connect/blob/main/web/src/pages/Sessions/SessionChat.tsx) - [web/src/api/client.ts](https://github.com/chenhg5/cc-connect/blob/main/web/src/api/client.ts) - [INSTALL.md](https://github.com/chenhg5/cc-connect/blob/main/INSTALL.md) - [AGENTS.md](https://github.com/chenhg5/cc-connect/blob/main/AGENTS.md)
# 系统架构 ## 概述 cc-connect 是一个连接本地 AI 编程助手与即时通讯平台的中间件系统。其核心架构采用模块化设计，将 AI Agent（Claude Code、Codex、Cursor 等）、消息平台（Discord、Telegram、飞书等）和会话管理解耦，通过统一的引擎层进行协调调度。 架构设计遵循以下核心原则： - **插件化平台支持**：通过 `core.RegisterPlatform` 注册机制支持新平台的热插拔 - **多项目隔离**：每个项目拥有独立的工作目录、Agent 配置和会话上下文 - **统一消息协议**：不同平台的消息统一转换为内部标准格式进行处理 - **前端分离**：Web 管理界面与后端核心服务通过 REST API 解耦 ## 核心架构图 ```mermaid graph TB subgraph 前端层["前端层 (React + TypeScript)"] UI[Web Admin UI] API[API Client] end subgraph 后端核心["后端核心 (Go)"] ENG[Engine 引擎] BRG[Bridge 网桥] REG[Registry 注册表] end subgraph Agent层["Agent 层"] CLAUDE[Claude Code] CODEX[Codex] CURSOR[Cursor] GEMINI[Gemini CLI] QODER[Qoder] OPENCODE[OpenCode] IFLOW[iFlow] end subgraph 平台层["平台层 (Platform Plugins)"] DISCORD[Discord] TELEGRAM[Telegram] FEISHU[飞书] SLACK[Slack] DINGTALK[钉钉] WECOM[企业微信] WECHAT[微信] QQ[QQ/QQBot] LINE[Line] WEIBO[微博] end UI --> API API --> ENG ENG <--> BRG ENG <--> REG ENG <--> CLAUDE ENG <--> CODEX ENG <--> CURSOR ENG <--> GEMINI ENG <--> QODER ENG <--> OPENCODE ENG <--> IFLOW BRG <--> DISCORD BRG <--> TELEGRAM BRG <--> FEISHU BRG <--> SLACK BRG <--> DINGTALK BRG <--> WECOM BRG <--> WECHAT BRG <--> QQ BRG <--> LINE BRG <--> WEIBO ``` ## 核心组件 ### Engine（引擎） Engine 是系统的核心调度器，负责协调 Agent 与平台之间的通信。从前端代码可以看到，Engine 处理以下关键功能： - **Provider 管理**：管理 AI 模型提供商配置，包括 `base_url`、`model`、`thinking` 等参数 - **会话管理**：维护多个会话（Session）的生命周期，包括连接状态、消息历史 - **命令路由**：解析和执行用户命令，如 `/provider switch`、`/workspace bind` 等 ```typescript // 资料来源：web/src/pages/Providers/ProviderList.tsx:50-60 interface Provider { name: string; base_url?: string; model: string; models?: { model: string }[]; thinking?: string; agent_types?: string[]; endpoints?: Record; agent_models?: Record; agent_model_lists?: Record; } ``` ### Bridge（网桥） Bridge 负责维护与各消息平台的实时连接状态，实现消息的双向转发： - **连接状态管理**：追踪 `connecting`、`connected`、`disconnected`、`error` 等状态 - **消息编码/解码**：将内部消息格式与各平台专有格式相互转换 - **心跳机制**：通过心跳保持与平台的长连接活跃 ```typescript // 资料来源：web/src/pages/Sessions/SessionChat.tsx:30-40 bridgeStatus === 'connected' // 连接正常 bridgeStatus === 'connecting' // 连接中 bridgeStatus === 'disconnected' // 已断开 bridgeStatus === 'error' // 连接错误 ``` ### Registry（注册表） Registry 实现了 Agent 和 Platform 的注册发现机制： - **Agent 注册**：`core.RegisterAgent("agentname", factory)` 将新的 Agent 类型注册到系统 - **Platform 注册**：`core.RegisterPlatform("platformname", factory)` 将新的消息平台接入系统 - **工厂模式**：通过工厂函数延迟实例化，确保按需加载 ## Agent 架构 ### 支持的 Agent 类型 | Agent 类型 | 标识符 | 配置项 | 说明 | |-----------|--------|--------|------| | Claude Code | `claudecode` | `work_dir`, `mode` | Anthropic 官方 CLI | | Codex | `codex` | `work_dir`, `mode` | OpenAI Codex | | Cursor | `cursor` | `work_dir`, `mode` | Cursor IDE | | Gemini CLI | `gemini` | `work_dir`, `mode` | Google Gemini CLI | | Qoder | `qoder` | `work_dir`, `mode` | Qoder CLI | | OpenCode | `opencode` | `work_dir`, `mode` | OpenCode CLI | | iFlow | `iflow` | `work_dir`, `mode` | iFlow CLI | ### Agent 配置选项 ```toml # 资料来源：INSTALL.md:80-90 [projects.agent] type = "claudecode" # 或 "codex", "cursor", "gemini", "qoder", "opencode", "iflow" [projects.agent.options] work_dir = "/absolute/path/to/your/project" mode = "default" # 或 "acceptEdits", "plan", "bypassPermissions", "dontAsk" ``` ### Agent 模式说明 | 模式 | 标识符 | 权限级别 | 说明 | |------|--------|----------|------| | 默认 | `default` | 标准 | 正常权限运行 | | 编辑 | `acceptEdits` | 中等 | 自动接受代码编辑建议 | | 计划 | `plan` | 只读 | 仅生成计划不执行 | | 放行 | `bypassPermissions` | 最高 | 跳过所有权限检查 | | 不询问 | `dontAsk` | 高 | 不等待确认直接执行 | ## 平台架构 ### 支持的消息平台 cc-connect 通过插件化架构支持多种即时通讯平台： | 平台 | 标识符 | 消息类型 | 特性 | |------|--------|----------|------| | Discord | `discord` | 文本/文件/图片 | Webhook + Bot | | Telegram | `telegram` | 文本/文件/图片 | Bot API | | 飞书 | `feishu` | 文本/文件 | 机器人 | | Slack | `slack` | 文本/文件 | Webhook/Bot | | 钉钉 | `dingtalk` | 文本/文件 | 机器人 | | 企业微信 | `wecom` | 文本/文件 | 企业机器人 | | 微信 | `weixin` | 文本/文件 | 公众号/企业微信 | | QQ | `qq`/`qqbot` | 文本/文件 | QQ 机器人 | | Line | `line` | 文本 | Line Bot | | 微博 | `weibo` | 文本 | 微博消息 | ### 平台注册机制 新增平台需要完成以下步骤： 1. 创建平台目录 `platform//` 2. 实现 `core.Platform` 接口 3. 在 `init()` 函数中调用 `core.RegisterPlatform()` 4. 创建构建标签文件 `cmd/cc-connect/plugin_platform_.go` 5. 添加到 `Makefile` 的 `ALL_PLATFORMS` 变量 ```go // 资料来源：AGENTS.md:25-30 // 伪代码示例 func init() { core.RegisterPlatform("newplatform", newPlatformFactory) } ``` ## 会话管理架构 ### 会话生命周期 ```mermaid stateDiagram-v2 [*] --> 创建中: 新建项目 创建中 --> 活跃: 连接成功 活跃 --> 等待中: 消息发送 等待中 --> 活跃: 响应接收 活跃 --> 断开: 关闭连接 断开 --> 活跃: 重新连接 活跃 --> [*]: 项目删除 ``` ### 会话数据结构 ```typescript // 资料来源：web/src/pages/Sessions/SessionList.tsx:20-35 interface Session { id: string; name?: string; user_name?: string; live: boolean; // 是否活跃 last_message?: { role: 'user' | 'assistant'; content: string; }; updated_at?: string; created_at?: string; } ``` ## API 架构 ### API 客户端设计 前端通过统一的 `ApiClient` 类与后端通信： ```typescript // 资料来源：web/src/api/client.ts:1-30 class ApiClient { get(path: string, params?: Record): Promise post(path: string, body?: any): Promise put(path: string, body?: any): Promise patch(path: string, body?: any): Promise delete(path: string): Promise raw(path: string): Promise // 非 JSON 响应 } ``` ### 认证机制 API 使用 Bearer Token 进行认证： ```typescript // 资料来源：web/src/api/client.ts:20-25 const h: HeadersInit = {}; if (this.token) h['Authorization'] = `Bearer ${this.token}`; ``` ## 项目配置架构 ### 配置层级 ```mermaid graph TD A[config.toml] --> B[全局设置] A --> C[[projects]] C --> D[项目 1] C --> E[项目 N] D --> F[agent 配置] D --> G[platforms 配置] F --> H[type] F --> I[options] G --> J[platform 类型] G --> K[webhook/token] ``` ### 配置示例 ```toml # 资料来源：INSTALL.md:40-70 [log] level = "info" # debug, info, warn, error [[projects]] name = "my-project" [projects.agent] type = "claudecode" [projects.agent.options] work_dir = "/path/to/project" mode = "default" ``` ## 工作目录隔离 每个项目拥有独立的工作目录，确保项目间环境互不影响： ```typescript // 资料来源：web/src/pages/Projects/ProjectDetail.tsx:10-15 setWorkDir(e.target.value)} placeholder="/path/to/project" /> ``` ## 消息流转架构 ```mermaid sequenceDiagram participant User as 用户 participant Platform as 消息平台 participant Bridge as Bridge participant Engine as Engine participant Agent as AI Agent User->>Platform: 发送消息 Platform->>Bridge: 接收消息 Bridge->>Engine: 转发消息 Engine->>Agent: 转发给 Agent Agent-->>Engine: 生成响应 Engine-->>Bridge: 返回响应 Bridge-->>Platform: 推送消息 Platform-->>User: 显示响应 ``` ## 前端技术栈 | 层级 | 技术 | 职责 | |------|------|------| | UI 框架 | React 18 | 组件化开发 | | 语言 | TypeScript | 类型安全 | | 样式 | Tailwind CSS | 原子化样式 | | 状态管理 | React Hooks | 本地状态 | | 路由 | React Router | 页面导航 | | HTTP | Fetch API | 服务端通信 | ### 前端页面结构 | 页面 | 路径 | 功能 | |------|------|------| | ProviderList | `/providers` | AI 提供商管理 | | ProjectList | `/projects` | 项目列表 | | ProjectDetail | `/projects/:id` | 项目配置 | | SessionList | `/sessions` | 会话列表 | | SessionChat | `/sessions/:id/chat` | 聊天界面 | | SkillList | `/skills` | 技能管理 | ## 国际化 系统支持多语言界面，通过统一的翻译函数实现： ```go // 资料来源：core/i18n.go:10-40 MsgProviderSwitchHint: { LangEnglish: "`/provider switch ` to switch", LangChinese: "`/provider switch <名称>` 切换", LangTraditionalChinese: "`/provider switch <名稱>` 切換", LangJapanese: "`/provider switch <名前>` で切り替え", LangSpanish: "`/provider switch ` para cambiar", } ``` 支持语言：`en`（英语）、`zh`（简体中文）、`zh-TW`（繁体中文）、`ja`（日语）、`es`（西班牙语） ## 构建与部署 ### 构建标签 cc-connect 使用 Go 构建标签实现平台和 Agent 的条件编译： ```bash # 资料来源：AGENTS.md:30-35 //go:build !no_discord //go:build !no_telegram //go:build !no_feishu ``` 通过 `make build` 或 `make build PLATFORMS="discord,telegram"` 构建特定平台版本。 ### 配置文件优先级 1. `-config ` 命令行参数 2. `./config.toml` 当前目录 3. `~/.cc-connect/config.toml` 全局配置（推荐） ## 扩展指南 ### 新增 Agent 步骤 1. 创建 `agent//.go` 2. 实现 `core.Agent` 和 `core.AgentSession` 接口 3. 在 `init()` 中调用 `core.RegisterAgent()` 4. 创建 `cmd/cc-connect/plugin_agent_.go` 5. 添加到 `Makefile` 的 `ALL_AGENTS` ### 新增平台步骤 1. 创建 `platform//.go` 2. 实现 `core.Platform` 接口 3. 在 `init()` 中调用 `core.RegisterPlatform()` 4. 创建 `cmd/cc-connect/plugin_platform_.go` 5. 添加到 `Makefile` 的 `ALL_PLATFORMS` ## 总结 cc-connect 采用清晰的分层架构设计： - **前端层**：React + TypeScript 构建的管理界面 - **核心层**：Engine、Bridge、Registry 组成的调度核心 - **Agent 层**：支持多种 AI 编程助手的统一抽象 - **平台层**：插件化的即时通讯平台集成 这种架构使得系统具有良好的可扩展性和可维护性，能够方便地接入新的 Agent 类型和消息平台，同时保持核心逻辑的稳定性。 --- ## 核心接口定义 ### 相关页面 相关主题：[系统架构](#architecture), [Bridge 协议](#bridge-protocol)
相关源码文件 以下源码文件用于生成本页说明： - [AGENTS.md](https://github.com/chenhg5/cc-connect/blob/main/AGENTS.md) - [core/i18n.go](https://github.com/chenhg5/cc-connect/blob/main/core/i18n.go) - [CONTRIBUTING.md](https://github.com/chenhg5/cc-connect/blob/main/CONTRIBUTING.md) - [INSTALL.md](https://github.com/chenhg5/cc-connect/blob/main/INSTALL.md) - [web/src/pages/Providers/ProviderList.tsx](https://github.com/chenhg5/cc-connect/blob/main/web/src/pages/Providers/ProviderList.tsx)
# 核心接口定义 ## 概述 cc-connect 是一个将 AI 编码代理（如 Claude Code、Codex、Cursor 等）与多种消息平台（飞书、Telegram、Discord 等）连接的基础设施项目。其核心架构基于**接口驱动设计**，通过抽象层解耦代理实现与平台接入，使系统具备高度可扩展性。 核心接口体系包含三大支柱： | 接口类别 | 作用 | 关键文件 | |---------|------|---------| | **Agent 接口** | 定义 AI 代理的标准行为 | `agent/*/` | | **Platform 接口** | 定义消息平台的标准行为 | `platform/*/` | | **Provider 接口** | 定义模型供应商配置 | `core/provider.go` | 资料来源：[AGENTS.md:1-20]() ## 接口架构图 ```mermaid graph TD subgraph "接入层 (Platform)" P1[Feishu] P2[Telegram] P3[Discord] P4[Slack] end subgraph "核心层 (Core)" Core[Core Engine] Provider[Provider Manager] Session[Session Manager] end subgraph "代理层 (Agent)" A1[Claude Code] A2[Codex] A3[Cursor] A4[Gemini] end P1 & P2 & P3 & P4 --> Core Core --> Provider Core --> Session Session --> A1 & A2 & A3 & A4 style Core fill:#e1f5fe style Provider fill:#fff3e0 style Session fill:#e8f5e9 ``` ## 代理接口体系 ### Agent 接口 每个 AI 代理必须实现 `core.Agent` 和 `core.AgentSession` 接口。这种设计允许同一代理类型在不同工作目录下运行多个独立会话。 代理注册通过 `init()` 函数完成： ```go core.RegisterAgent("newagent", factory) ``` 资料来源：[AGENTS.md:35-44]() ### 支持的代理类型 | 代理类型 | 构建标签 | 配置标识 | |---------|---------|---------| | Claude Code | `no_claudecode` | `claudecode` | | Codex | `no_codex` | `codex` | | Cursor | `no_cursor` | `cursor` | | Gemini | `no_gemini` | `gemini` | | iFlow | `no_iflow` | `iflow` | | OpenCode | `no_opencode` | `opencode` | | Qoder | `no_qoder` | `qoder` | | ACP | `no_acp` | `acp` | 资料来源：[AGENTS.md:43-52]() ### 代理配置选项 代理的 `options` 配置块支持以下参数： | 参数 | 说明 | 可选值 | |------|------|--------| | `type` | 代理类型 | `claudecode`, `codex`, `cursor` 等 | | `work_dir` | 工作目录路径 | 绝对路径 | | `mode` | 运行模式 | `default`, `acceptEdits`, `plan`, `bypassPermissions`, `dontAsk` | 资料来源：[INSTALL.md:28-42]() ```toml [projects.agent] type = "claudecode" [projects.agent.options] work_dir = "/absolute/path/to/your/project" mode = "default" # 或 acceptEdits, plan, bypassPermissions, dontAsk ``` ## 平台接口体系 ### Platform 接口 消息平台通过实现 `core.Platform` 接口接入系统。接口支持可选扩展以提供更丰富的功能。 平台注册同样通过 `init()` 函数： ```go core.RegisterPlatform("newplatform", factory) ``` 资料来源：[AGENTS.md:17-33]() ### 支持的平台类型 | 平台 | 构建标签 | 配置标识 | |------|---------|---------| | 飞书 | `no_feishu` | `feishu` | | Telegram | `no_telegram` | `telegram` | | Discord | `no_discord` | `discord` | | Slack | `no_slack` | `slack` | | 钉钉 | `no_dingtalk` | `dingtalk` | | 企业微信 | `no_wecom` | `wecom` | | 微信 | `no_weixin` | `weixin` | | QQ | `no_qq` | `qq` | | QQ 机器人 | `no_qqbot` | `qqbot` | | LINE | `no_line` | `line` | | 微博 | `no_weibo` | `weibo` | 资料来源：[AGENTS.md:1-15]() ### 平台编译策略 cc-connect 采用**构建标签（Build Tags）** 实现选择性编译，每个平台/代理通过独立的 `plugin_*.go` 文件导入： ```go //go:build !no_feishu ``` #### 编译命令示例 | 场景 | 命令 | |------|------| | 排除指定平台 | `go build -tags 'no_discord no_dingtalk'` | | 仅包含特定代理 | `make build AGENTS=claudecode` | | 仅包含特定平台 | `make build PLATFORMS_INCLUDE=feishu,telegram` | | 排除多个组件 | `make build EXCLUDE=discord,dingtalk,qq` | 资料来源：[AGENTS.md:70-91]() ## Provider 接口体系 ### Provider 管理 Provider 负责管理与 AI 模型的连接配置，支持多种模型供应商的统一抽象。 ### Provider 配置结构 ```toml [[projects.providers]] name = "provider-name" type = "openai" # 或 anthropic, google 等 base_url = "https://api.example.com/v1" model = "gpt-4" thinking = "" # 支持 thinking 特性 ``` Provider 配置可通过 Web 界面或配置文件管理，支持预设模板导入。 资料来源：[web/src/pages/Providers/ProviderList.tsx:1-50]() ### Provider 预设系统 系统内置 Provider 预设，支持一键配置常用供应商： | 预设属性 | 说明 | |---------|------| | `tier` | 层级排序 | | `thinking` | 是否支持思考模式 | | `agent_types` | 支持的代理类型列表 | | `endpoints` | 自定义端点映射 | | `agent_models` | 代理特定模型配置 | | `agent_model_lists` | 模型列表配置 | 资料来源：[web/src/pages/Providers/ProviderList.tsx:80-95]() ## Session 管理 ### 会话生命周期 会话（Session）是连接平台消息与代理执行的桥梁。每个会话独立维护上下文状态。 会话支持以下操作： - `/workspace bind ` - 绑定工作区 - `/workspace route ` - 设置路由路径 - `/provider switch ` - 切换 Provider - `/provider clear` - 清除 Provider 选择 资料来源：[core/i18n.go:50-100]() ### 会话状态消息 | 消息键 | 英文 | 中文 | |-------|------|------| | `MsgWsBindSuccess` | ✅ Workspace bound | ✅ 工作区绑定成功 | | `MsgWsBindNotFound` | Workspace not found | 工作区不存在 | | `MsgProviderSwitched` | ✅ Provider switched | ✅ Provider 已切换 | | `MsgProviderNotFound` | ❌ Provider not found | ❌ 未找到 Provider | 资料来源：[core/i18n.go:1-80]() ## 项目配置模型 ### 完整配置结构 ```toml [[projects]] name = "my-project" [projects.agent] type = "claudecode" [projects.agent.options] work_dir = "/absolute/path/to/your/project" mode = "default" # 平台配置 [projects.platform] type = "feishu" # ... 平台特定配置 # Provider 配置 [[projects.providers]] name = "openai" model = "gpt-4" # 心跳配置（可选） [projects.heartbeat] interval_mins = 5 ``` 资料来源：[INSTALL.md:20-50]() ### 项目级功能开关 | 功能 | 配置项 | 说明 | |------|--------|------| | 上下文指示器 | `show_ctx_indicator` | 在回复后显示 `[ctx: ~N%]` | | 回复页脚 | `reply_footer` | 追加模型/用量元数据 | 资料来源：[web/src/pages/Projects/ProjectDetail.tsx:50-80]() ## 国际化接口 ### 消息定义格式 系统使用统一的国际化消息接口，支持多语言： | 语言 | 代码 | 说明 | |------|------|------| | 英语 | `en` | 默认语言 | | 中文 | `zh` | 简体中文 | | 繁体中文 | `zh-TW` | 繁体中文 | | 日语 | `ja` | 日语 | | 西班牙语 | `es` | 西班牙语 | 消息定义示例： ```go MsgProviderNotFound: { LangEnglish: "❌ Provider %q not found...", LangChinese: "❌ 未找到 Provider %q...", LangTraditionalChinese: "❌ 未找到 Provider %q...", LangJapanese: "❌ プロバイダ %q が見つかりません...", LangSpanish: "❌ Proveedor %q no encontrado...", }, ``` 资料来源：[core/i18n.go:1-50]() ## 扩展开发指南 ### 新增代理步骤 1. 创建 `agent/newagent/newagent.go` 2. 实现 `core.Agent` 和 `core.AgentSession` 接口 3. 在 `init()` 中注册：`core.RegisterAgent("newagent", factory)` 4. 创建 `cmd/cc-connect/plugin_agent_newagent.go` 含构建标签 5. 添加到 `Makefile` 的 `ALL_AGENTS` 6. 在 `config.example.toml` 添加配置示例 7. 编写单元测试 资料来源：[AGENTS.md:35-51]() ### 新增平台步骤 1. 创建 `platform/newplatform/newplatform.go` 2. 实现 `core.Platform` 接口 3. 在 `init()` 中注册：`core.RegisterPlatform("newplatform", factory)` 4. 创建构建标签文件 5. 添加到编译配置 6. 添加配置示例和测试 资料来源：[AGENTS.md:17-33]() ## 测试规范 ### 接口测试要点 | 测试类别 | 测试方法 | |---------|---------| | 代理测试 | 使用 channels 模拟事件流 | | 平台测试 | 模拟消息接收和响应 | | 卡片渲染 | 检查返回的 `*Card` 结构体 | | 会话测试 | 通过 channels 模拟事件流 | 资料来源：[AGENTS.md:60-65]() ## 编译检查清单 新增代码必须通过以下检查： | 检查项 | 命令 | 说明 | |--------|------|------| | 构建测试 | `go build ./...` | 确保无编译错误 | | 单元测试 | `go test ./...` | 所有测试通过 | | 硬编码检查 | `grep` 检查 | core 目录无平台/代理硬编码名称 | | 国际化 | 检查 | 所有用户可见字符串有翻译 | | 敏感信息 | 检查 | 代码中无 API keys、tokens | 资料来源：[AGENTS.md:22-31]() ## 总结 cc-connect 的核心接口体系采用简洁而强大的设计： - **接口抽象**：通过 `Agent`、`Platform`、`Provider` 三大接口抽象不同实现 - **插件化编译**：使用构建标签实现按需编译，减少二进制体积 - **国际化优先**：所有用户可见文本通过统一的 i18n 接口管理 - **配置驱动**：通过 TOML 配置文件灵活管理项目设置 这种设计使开发者能够以一致的方式添加新的代理类型或消息平台，同时保持核心引擎的稳定性和可测试性。 --- ## Bridge 协议 ### 相关页面 相关主题：[核心接口定义](#core-interfaces)
相关源码文件 以下源码文件用于生成本页说明： - [core/bridge.go](https://github.com/chenhg5/cc-connect/blob/main/core/bridge.go) - [core/bridge_capabilities.go](https://github.com/chenhg5/cc-connect/blob/main/core/bridge_capabilities.go) - [web/src/pages/Sessions/SessionChat.tsx](https://github.com/chenhg5/cc-connect/blob/main/web/src/pages/Sessions/SessionChat.tsx) - [web/src/pages/Chat/ChatView.tsx](https://github.com/chenhg5/cc-connect/blob/main/web/src/pages/Chat/ChatView.tsx) - [web/src/api/client.ts](https://github.com/chenhg5/cc-connect/blob/main/web/src/api/client.ts)
# Bridge 协议 ## 概述 Bridge 协议是 cc-connect 项目中的核心通信机制，用于在 Web 前端与后端引擎之间建立双向实时通信通道。它通过 WebSocket 技术实现低延迟的消息传递，支持多项目引擎管理、命令发布与订阅、以及卡片导航功能。 Bridge 协议的核心组件位于 `core/bridge.go` 和 `core/bridge_capabilities.go` 中，为整个应用提供可靠的前后端桥接能力。 --- ## 架构设计 ### 组件关系图 ```mermaid graph TD A[Web 前端] <-->|WebSocket| B[BridgeServer] B --> C[BridgePlatform] B --> D[bridgeAdapter] C --> E[Engine] E --> F[bridgeEngineRef] G[Providers] --> E H[Skills] --> E ``` ### 核心数据结构 | 组件 | 文件位置 | 职责 | |------|---------|------| | `BridgeServer` | `core/bridge.go` | WebSocket 服务器主控，管理多个项目平台 | | `BridgePlatform` | `core/bridge.go` | 单个项目的通信平台实例 | | `bridgeAdapter` | `core/bridge.go` | 消息适配器，处理协议转换 | | `bridgeEngineRef` | `core/bridge.go` | 引擎引用，管理引擎生命周期 | | `Engine` | `core/bridge.go` | 具体项目引擎实现 | 资料来源：[core/bridge.go:47-61]() --- ## BridgeServer 配置与初始化 ### 配置参数 `NewBridgeServer` 函数负责创建 Bridge 服务器实例，支持以下配置选项： | 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | `port` | int | 9810 | WebSocket 服务端口 | | `path` | string | `/bridge/ws` | WebSocket 路径（自动补全前缀 `/`）| | `token` | string | - | 认证令牌，insecure 模式下可为空 | | `insecure` | bool | false | 是否启用非安全模式（仅限本地开发）| | `corsOrigins` | []string | - | CORS 允许的源列表 | 资料来源：[core/bridge.go:47-59]() ### 安全机制 Bridge 协议实现了严格的安全验证： ```go // Validate security settings if token == "" && !insecure { slog.Error("bridge: token is required when insecure mode is not enabled", "help", "set bridge.token in config, or use insecure=true for local development only") return nil } if insecure && token == "" { slog.Warn("bridge: running in INSECURE mode without authentication - only use for local development!") } ``` 资料来源：[core/bridge.go:63-73]() **安全规则：** - 生产环境必须配置 `token` - `insecure` 模式仅用于本地开发 - 未配置 token 且未启用 insecure 模式时，服务器启动失败 --- ## 项目引擎管理 ### 注册引擎 使用 `RegisterEngine` 方法将项目引擎注册到 Bridge 服务器： ```go func (bs *BridgeServer) RegisterEngine(projectName string, engine *Engine, bp *BridgePlatform) { bs.enginesMu.Lock() defer bs.enginesMu.Unlock() if err := bp.Start(engine.handleMessage); err != nil { slog.Warn("bridge: platform start failed", "project", projectName, "error", err) } bp.SetCardNavigationHandler(engine.handleCardNav) } ``` 资料来源：[core/bridge.go:83-92]() ### 创建平台实例 每个项目引擎对应一个独立的 `BridgePlatform` 实例： ```go func (bs *BridgeServer) NewPlatform(projectName string) *BridgePlatform { return &BridgePlatform{server: bs, project: projectName} } ``` 资料来源：[core/bridge.go:76-79]() --- ## 能力快照机制 ### 快照数据结构 `bridgeCapabilitiesSnapshot` 定义了 Bridge 协议的能力快照格式： ```go type bridgeCapabilitiesSnapshot struct { Type string `json:"type"` Version int `json:"version"` Host bridgeCapabilitiesHost `json:"host"` Projects []bridgeProjectCapabilities `json:"projects"` } type bridgeCapabilitiesHost struct { ID string `json:"id"` Hostname string `json:"hostname"` CCConnectVersion string `json:"ccconnect_version"` Commit string `json:"commit"` BuildTime string `json:"build_time"` } type bridgeProjectCapabilities struct { Project string `json:"project"` Commands []string `json:"commands"` } ``` 资料来源：[core/bridge_capabilities.go:1-35]() ### 获取能力快照 能力快照通过以下流程生成： ```mermaid graph TD A[请求能力快照] --> B[获取所有项目名称] B --> C[排序项目列表] C --> D{遍历每个项目} D -->|获取引擎| E[bridgeEngineRef] E --> F[获取发布命令] F --> G[构建快照数据] G --> H[返回 JSON 响应] ``` 资料来源：[core/bridge_capabilities.go:4-28]() --- ## 前端集成 ### 连接状态管理 Web 前端通过 `web/src/api/client.ts` 中的 API 客户端与 Bridge 服务器通信： ```typescript export class ApiClient { async raw(path: string): Promise { const h: HeadersInit = {}; if (this.token) h['Authorization'] = `Bearer ${this.token}`; const res = await fetch(`${API_BASE}${path}`, { headers: h }); if (res.status === 401 && this.onUnauthorized) { this.onUnauthorized(); throw new ApiError('Unauthorized', 401); } if (!res.ok) throw new ApiError(res.statusText, res.status); return res.text(); } } ``` 资料来源：[web/src/api/client.ts:1-50]() ### 连接状态展示 前端 UI 根据 Bridge 连接状态显示不同的界面： | 状态 | 样式 | 消息键名 | |------|------|----------| | `connected` | 绿色图标 | `sessions.bridgeConnected` | | `error` | 琥珀色警告 | `sessions.bridgeDisconnected` | | `connecting` | 灰色加载动画 | `sessions.bridgeConnecting` | 资料来源：[web/src/pages/Sessions/SessionChat.tsx:1-20]() 资料来源：[web/src/pages/Chat/ChatView.tsx:1-15]() **连接中状态 UI：** ```tsx
{t('sessions.bridgeConnecting', 'Connecting to bridge...')}
``` 资料来源：[web/src/pages/Sessions/SessionChat.tsx:13-16]() --- ## 配置示例 ### config.toml 配置 ```toml [bridge] port = 9810 path = "/bridge/ws" token = "your-secret-token" insecure = false # 仅本地开发设为 true cors_origins = ["http://localhost:5173"] ``` ### 启动参数说明 | 参数 | 环境变量 | 说明 | |------|----------|------| | `port` | `BRIDGE_PORT` | 服务端口 | | `path` | `BRIDGE_PATH` | WebSocket 路径 | | `token` | `BRIDGE_TOKEN` | 认证令牌 | | `insecure` | `BRIDGE_INSECURE` | 非安全模式 | --- ## 错误处理 ### 常见错误场景 | 场景 | 错误消息 | 解决方案 | |------|----------|----------| | Token 缺失 | `bridge: token is required when insecure mode is not enabled` | 设置 `bridge.token` 或启用 `insecure=true` | | 平台启动失败 | `bridge: platform start failed` | 检查引擎配置和网络连接 | | 401 未授权 | `Unauthorized` | 验证 token 有效性 | 资料来源：[core/bridge.go:63-69]() --- ## 版本信息 能力快照中包含版本信息字段： | 字段 | 来源 | 说明 | |------|------|------| | `CCConnectVersion` | 编译时注入 | cc-connect 版本号 | | `Commit` | 编译时注入 | Git 提交哈希 | | `BuildTime` | 编译时注入 | 构建时间戳 | 资料来源：[core/bridge_capabilities.go:18-22]() --- ## 总结 Bridge 协议是 cc-connect 实现前后端实时通信的关键机制。它具有以下特点： - **基于 WebSocket**：提供低延迟的双向通信 - **多项目支持**：通过 `BridgePlatform` 管理多个独立项目 - **安全认证**：支持 token 验证和 CORS 控制 - **能力发现**：提供标准化的能力快照机制 - **状态监控**：前端可实时感知连接状态变化 --- ## Agent 集成概述 ### 相关页面 相关主题：[Claude Code 集成](#claude-code-integration), [Codex 集成](#codex-integration), [Agent 通信协议](#agent-protocols)
相关源码文件 以下源码文件用于生成本页说明： - [agent/acp/agent.go](https://github.com/chenhg5/cc-connect/blob/main/agent/acp/agent.go) - [agent/claudecode/claudecode.go](https://github.com/chenhg5/cc-connect/blob/main/agent/claudecode/claudecode.go) - [agent/codex/codex.go](https://github.com/chenhg5/cc-connect/blob/main/agent/codex/codex.go) - [core/agent.go](https://github.com/chenhg5/cc-connect/blob/main/core/agent.go) - [web/src/pages/Projects/ProjectDetail.tsx](https://github.com/chenhg5/cc-connect/blob/main/web/src/pages/Projects/ProjectDetail.tsx) - [web/src/pages/Providers/ProviderList.tsx](https://github.com/chenhg5/cc-connect/blob/main/web/src/pages/Providers/ProviderList.tsx) - [core/i18n.go](https://github.com/chenhg5/cc-connect/blob/main/core/i18n.go)
# Agent 集成概述 ## 简介 Agent 集成是 cc-connect 项目的核心功能模块，负责将多种 AI Agent 提供商统一接入到平台中。该模块通过抽象层设计，支持多种 Agent 运行时环境，包括 ACP Agent、Claude Code 和 Codex 等主流 AI 编程助手。 Agent 系统的设计目标是通过统一的接口规范，将不同提供商的 Agent 能力整合到同一个协作框架中，使开发者能够在项目中灵活切换和配置不同的 AI 助手，同时保持一致的用户体验和项目管理流程。 --- ## 架构设计 ### 整体架构 cc-connect 的 Agent 集成采用分层架构设计，从底层到顶层依次为： ```mermaid graph TD A[用户界面层] --> B[项目管理模块] B --> C[Provider 配置层] C --> D[Agent 抽象层] D --> E[具体 Agent 实现] E --> F[ACP Agent] E --> G[Claude Code] E --> H[Codex] style D fill:#e1f5fe style F fill:#fff3e0 style G fill:#fff3e0 style H fill:#fff3e0 ``` ### Agent 类型系统 系统支持多种 Agent 类型，通过 `agent_type` 字段进行标识和配置。不同的 Agent 类型对应不同的 AI 提供商和运行时环境。 | Agent 类型 | 提供商 | 主要用途 | 配置方式 | |-----------|--------|----------|----------| | acp | ACP | 通用 AI 协作 | base_url + model | | claude | Claude Code | Claude 编程助手 | claude_code 配置 | | codex | OpenAI Codex | 代码补全与生成 | codex 配置 | 资料来源：[web/src/pages/Projects/ProjectDetail.tsx:30-35](https://github.com/chenhg5/cc-connect/blob/main/web/src/pages/Projects/ProjectDetail.tsx) --- ## Agent 权限模式 ### 权限模式列表 每个 Agent 实例可以配置不同的权限模式，决定其执行操作时的权限级别。权限模式通过 `agentMode` 参数控制。 | 模式值 | 显示名称 | 说明 | |--------|----------|------| | default | 默认 | 标准权限，需要用户确认敏感操作 | | acceptEdits | edit | 自动接受编辑操作 | | plan | plan | 仅规划模式，不执行实际操作 | | bypassPermissions | yolo | 绕过权限检查，所有操作直接执行 | | dontAsk | dontAsk | 不询问，直接执行所有操作 | 资料来源：[web/src/pages/Projects/ProjectDetail.tsx:17-22](https://github.com/chenhg5/cc-connect/blob/main/web/src/pages/Projects/ProjectDetail.tsx) ### 权限模式配置界面 ```tsx ``` --- ## Provider 配置与 Agent 关联 ### Provider 模型 Provider 是 Agent 的配置容器，负责存储与特定 AI 服务提供商的连接配置。每个 Provider 可以包含多个模型配置和 Agent 类型支持。 ```typescript interface Provider { name: string; // Provider 唯一标识 base_url: string; // API 端点地址 model: string; // 默认模型 models: string[]; // 可用模型列表 agent_types?: string[]; // 支持的 Agent 类型 thinking?: string; // 思考模式配置 } ``` 资料来源：[web/src/pages/Providers/ProviderList.tsx:10-20](https://github.com/chenhg5/cc-connect/blob/main/web/src/pages/Providers/ProviderList.tsx) ### 思考模式配置 思考模式（Thinking）是 Agent 的重要特性之一，用于控制 AI 是否进行链式推理思考。 | 模式值 | 说明 | |--------|------| | 空字符串 | 使用 Provider 默认配置 | | enabled | 启用思考模式 | | disabled | 禁用思考模式 | ```tsx ``` 资料来源：[web/src/pages/Providers/ProviderList.tsx:90-105](https://github.com/chenhg5/cc-connect/blob/main/web/src/pages/Providers/ProviderList.tsx) --- ## 项目与 Agent 绑定 ### 项目配置结构 每个项目（Project）可以关联一个或多个 Agent 实例，通过 `agent_type` 和相关配置实现绑定关系。 ```typescript interface Project { name: string; // 项目名称 agent_type: string; // 关联的 Agent 类型 work_dir?: string; // 工作目录 agent_mode?: string; // 权限模式 sessions_count: number; // 关联的会话数量 heartbeat_enabled?: boolean; // 心跳功能开关 } ``` 资料来源：[web/src/pages/Projects/ProjectList.tsx:20-30](https://github.com/chenhg5/cc-connect/blob/main/web/src/pages/Projects/ProjectList.tsx) ### Agent 类型变更流程 ```mermaid graph LR A[选择 Agent 类型] --> B{类型是否改变?} B -->|是| C[显示警告提示] C --> D[重启项目生效] B -->|否| E[保持当前配置] D --> F[移除不兼容的 Provider] F --> G[应用新配置] ``` 当用户修改项目的 Agent 类型时，系统会显示警告提示，告知用户此操作需要重启项目，并且不兼容的 Provider 会被自动移除。 资料来源：[web/src/pages/Projects/ProjectDetail.tsx:40-42](https://github.com/chenhg5/cc-connect/blob/main/web/src/pages/Projects/ProjectDetail.tsx) --- ## Agent 实现类型 ### ACP Agent ACP Agent 是 cc-connect 的核心 Agent 实现，提供基于 ACP 协议的统一接口。 **主要特性：** - 支持多种模型配置 - 可配置的思考模式 - 多语言国际化支持 ### Claude Code Claude Code Agent 集成，允许直接调用 Claude Code 的能力。 **配置参数：** - `claude_code` 配置块 - 关联的 Provider base_url ### Codex OpenAI Codex 集成，用于代码补全和生成任务。 **配置参数：** - `codex` 配置块 - 支持 GPT-4 等模型 --- ## 会话与 Agent 交互 ### 会话状态 每个会话（Session）与特定的 Agent 实例关联，支持实时消息预览和状态指示。 | 状态字段 | 说明 | |----------|------| | live | 会话是否处于活跃状态 | | last_message | 最后一条消息内容 | | updated_at | 最后更新时间 | ```tsx
{s.name || s.user_name || s.id.slice(0, 8)} {s.live && }
``` 资料来源：[web/src/pages/Sessions/SessionList.tsx:15-22](https://github.com/chenhg5/cc-connect/blob/main/web/src/pages/Sessions/SessionList.tsx) --- ## 国际化和本地化 Agent 系统支持完整的国际化配置，通过 i18n 模块提供多语言消息支持。 **支持的语种：** | 语言代码 | 名称 | |----------|------| | en | English | | zh | 简体中文 | | zh-TW | 繁體中文 | | ja | 日本語 | | es | Español | ```go MsgProviderSwitchHint: { LangEnglish: "`/provider switch ` to switch | `/provider clear` to reset", LangChinese: "`/provider switch <名称>` 切换 | `/provider clear` 清除", LangTraditionalChinese: "`/provider switch <名稱>` 切換 | `/provider clear` 清除", LangJapanese: "`/provider switch <名前>` で切り替え | `/provider clear` でリセット", LangSpanish: "`/provider switch ` para cambiar | `/provider clear` para restablecer", } ``` 资料来源：[core/i18n.go:50-60](https://github.com/chenhg5/cc-connect/blob/main/core/i18n.go) --- ## 快速入门 ### 配置新的 Agent Provider 1. 打开 CC-Connect Admin 管理界面 2. 导航至 Global Providers 页面 3. 点击「Add」按钮添加新的 Provider 4. 填写以下必要信息： - Provider 名称 - API Base URL - 模型名称 - 可选：模型列表 ### 在项目中使用 Agent 1. 创建或选择已有项目 2. 在项目设置中配置 Agent 类型 3. 选择对应的权限模式 4. 绑定相关的 Provider 配置 ### 切换 Provider 使用命令 `/provider switch ` 可以动态切换当前使用的 Provider，使用 `/provider clear` 可以重置为默认配置。 资料来源：[core/i18n.go:45-55](https://github.com/chenhg5/cc-connect/blob/main/core/i18n.go) --- ## 配置参考 ### 项目级 Agent 配置 ```toml [project.my-project] agent_type = "acp" agent_mode = "default" work_dir = "/path/to/project" ``` ### Provider 级配置 ```toml [provider.anthropic] base_url = "https://api.anthropic.com" model = "claude-sonnet-4-20250514" thinking = "enabled" ``` --- ## 注意事项 1. **权限模式变更**：修改 `agent_mode` 后需要重启项目才能生效 2. **Agent 类型切换**：更换 Agent 类型会自动移除不兼容的 Provider 配置 3. **思考模式**：并非所有模型都支持思考模式，请参考具体模型的文档 4. **Provider 名称唯一性**：系统要求 Provider 名称全局唯一，重复添加会被拒绝 --- ## Agent 通信协议 ### 相关页面 相关主题：[Agent 集成概述](#agent-overview)
相关源码文件 以下源码文件用于生成本页说明： - [web/src/pages/Sessions/SessionChat.tsx](https://github.com/chenhg5/cc-connect/blob/main/web/src/pages/Sessions/SessionChat.tsx) - [web/src/pages/Chat/ChatView.tsx](https://github.com/chenhg5/cc-connect/blob/main/web/src/pages/Chat/ChatView.tsx) - [web/src/pages/Sessions/SessionList.tsx](https://github.com/chenhg5/cc-connect/blob/main/web/src/pages/Sessions/SessionList.tsx) - [core/i18n.go](https://github.com/chenhg5/cc-connect/blob/main/core/i18n.go)
# Agent 通信协议 ## 概述 Agent 通信协议是 CC-Connect 系统中实现多 Agent 之间消息传递、会话管理和状态同步的核心机制。该协议支撑了前端界面与后端 Agent 引擎之间的实时交互能力。 ## 会话管理机制 会话（Session）是 Agent 通信的基本单元，每个会话包含唯一的标识符、状态信息和消息历史记录。 ### 会话状态类型 | 状态类型 | 说明 | 标识 | |---------|------|------| | live | 会话处于活跃状态 | 绿色圆点指示器 | | inactive | 会话已暂停 | 无特殊标识 | | error | 连接错误 | 琥珀色警告显示 | 资料来源：[web/src/pages/Sessions/SessionList.tsx:4-5]() ### 会话消息结构 会话消息采用角色化结构，支持用户消息和 Agent 回复两种基本角色： ```typescript interface SessionMessage { role: 'user' | 'assistant'; content: string; timestamp?: string; } ``` 消息预览功能限制显示内容长度为 100 字符，并替换换行符为空格以保持布局整洁。资料来源：[web/src/pages/Sessions/SessionList.tsx:12-15]() ## 桥接连接机制 ### 连接状态监控 Agent 通信依赖桥接（Bridge）机制实现前端与后端的长连接通信。系统提供三种连接状态： | 状态 | 视觉反馈 | 触发条件 | |------|---------|---------| | connected | 绿色指示器 | 桥接连接正常 | | connecting | 加载动画 + "Connecting to bridge..." | 连接建立中 | | error | 琥珀色警告 + "Bridge disconnected" | 连接失败 | 资料来源：[web/src/pages/Sessions/SessionChat.tsx:3-9]() 和 [web/src/pages/Chat/ChatView.tsx:8-13]() ### 桥接连接流程 ``` graph TD A[前端发起连接] --> B{连接状态检查} B -->|成功| C[显示 connected 状态] B -->|进行中| D[显示 loading 动画] B -->|失败| E[显示 error 警告] C --> F[建立 WebSocket 通信] E --> G[触发重连机制] ``` ## 命令协议 Agent 通信支持多种命令操作，通过斜杠命令（Slash Commands）触发： ### Provider 相关命令 | 命令 | 功能 | 说明 | |------|------|------| | `/provider list` | 列出可用 Provider | 查看系统中配置的 AI 提供商 | | `/provider switch ` | 切换 Provider | 切换到指定名称的 Provider | | `/provider clear` | 重置 Provider | 清除当前 Provider 选择 | 资料来源：[core/i18n.go:1-10]() ### Workspace 相关命令 | 命令 | 功能 | |------|------| | `/workspace bind ` | 绑定工作区 | | `/workspace route ` | 设置路由路径 | ## 消息国际化 系统支持多语言消息提示，确保 Agent 通信过程中的用户反馈清晰易懂： | 语言 | Provider 切换提示 | Provider 未找到提示 | |------|------------------|-------------------| | English | `✅ Provider switched to **%s**` | `❌ Provider %q not found` | | Chinese | `✅ Provider 已切换至 **%s**` | `❌ 未找到 Provider %q` | | Japanese | `✅ プロバイダを %s に切り替えました` | `❌ プロバイダ %q が見つかりません` | | Spanish | `✅ Proveedor cambiado a **%s**` | `❌ Proveedor %q no encontrado` | 资料来源：[core/i18n.go:1-8]() ## 前端通信组件 ### ChatView 组件架构 ChatView 是核心通信视图组件，负责协调以下子组件： ```mermaid graph TD A[ChatView] --> B[SessionDrawer] A --> C[CommandResultPanel] A --> D[BridgeStatus] B --> E[会话列表] C --> F[命令结果展示] D --> G[连接状态指示器] ``` 组件接收以下属性： - `sessions`: 会话列表数据 - `currentSession`: 当前活跃会话 - `onSelect`: 会话切换回调 - `onNewSession`: 新建会话回调 资料来源：[web/src/pages/Chat/ChatView.tsx:1-20]() ### SessionDrawer 组件 会话抽屉组件提供侧边栏式会话管理界面，支持： - 会话列表展示 - 当前会话高亮 - 快速切换会话 - 新建会话入口 ## 状态管理 ### 会话状态同步 ```typescript // 会话状态更新流程 interface SessionState { id: string; name?: string; user_name?: string; live: boolean; last_message?: SessionMessage; updated_at?: string; created_at?: string; } ``` 会话列表按照最后更新时间排序，确保最近活跃的会话显示在列表顶部。 ## 错误处理 系统提供分级错误处理机制： 1. **连接错误**：桥接连接失败时显示琥珀色警告，并提供重连选项 2. **命令错误**：未知命令返回使用提示信息 3. **Provider 错误**：Provider 不存在时提示可用列表 错误信息支持多语言显示，错误提示文本存储在 `core/i18n.go` 国际化配置中。 --- ## Claude Code 集成 ### 相关页面 相关主题：[Agent 集成概述](#agent-overview)
相关源码文件 以下源码文件用于生成本页说明： - [agent/claudecode/claudecode.go](https://github.com/chenhg5/cc-connect/blob/main/agent/claudecode/claudecode.go) ⚠️ 未在当前上下文获取 - [agent/claudecode/session.go](https://github.com/chenhg5/cc-connect/blob/main/agent/claudecode/session.go) ⚠️ 未在当前上下文获取 - [agent/claudecode/claude_usage.go](https://github.com/chenhg5/cc-connect/blob/main/agent/claudecode/claude_usage.go) ⚠️ 未在当前上下文获取 - [web/src/pages/Providers/ProviderList.tsx](https://github.com/chenhg5/cc-connect/blob/main/web/src/pages/Providers/ProviderList.tsx) ✅ 已获取 - [web/src/pages/Projects/ProjectDetail.tsx](https://github.com/chenhg5/cc-connect/blob/main/web/src/pages/Projects/ProjectDetail.tsx) ✅ 已获取 - [core/i18n.go](https://github.com/chenhg5/cc-connect/blob/main/core/i18n.go) ✅ 已获取 > ⚠️ **注意**：Claude Code 集成核心源码文件（`agent/claudecode/*.go`）未包含在当前检索结果中。以下内容基于 Web 前端组件和 i18n 配置推断，可能与实际实现存在差异。建议查阅完整源码获取精确信息。
# Claude Code 集成 ## 概述 Claude Code 集成是 cc-connect 项目中连接 Claude Code Agent 的核心功能模块。该集成允许用户在 cc-connect 平台中配置和使用 Claude Code 作为 AI 代码助手 provider，实现与 Claude Code 的无缝对接。 ## 架构设计 ### 核心组件 Claude Code 集成主要包含以下核心模块： | 组件 | 文件路径 | 功能描述 | |------|----------|----------| | claudecode.go | agent/claudecode/ | Claude Code Agent 主逻辑实现 | | session.go | agent/claudecode/ | 会话管理功能 | | claude_usage.go | agent/claudecode/ | 使用量统计与计费追踪 | ### Provider 集成 Claude Code 作为一种特殊的 Agent Type（`codex`）集成到 cc-connect 的 Provider 系统中。用户可以在 Provider 配置界面选择或配置 Claude Code 作为 AI 服务提供商。 ```mermaid graph TD A[用户请求] --> B[cc-connect Core] B --> C{Provider 类型判断} C -->|codex| D[Claude Code Provider] C -->|其他| E[标准 Provider] D --> F[Claude Code Agent] E --> G[OpenAI/兼容 API] F --> H[Claude Code 执行环境] ``` ## 配置选项 ### Agent Mode 配置 在项目设置中，用户可以配置 Claude Code 的运行权限模式： | 模式值 | 显示名称 | 权限级别 | 使用场景 | |--------|----------|----------|----------| | `default` | default | 标准权限 | 常规开发任务 | | `acceptEdits` | acceptEdits (edit) | 自动接受编辑 | 信任的编辑操作 | | `plan` | plan | 仅计划模式 | 安全审查阶段 | | `bypassPermissions` | bypassPermissions (yolo) | 绕过权限检查 | 完全信任环境 | | `dontAsk` | dontAsk | 无需确认 | 自动化脚本 | 资料来源：[web/src/pages/Projects/ProjectDetail.tsx]() ### Provider 配置 Claude Code Provider 支持以下核心配置项： | 配置项 | 说明 | 必填 | |--------|------|------| | base_url | API 端点地址 | 是 | | model | 模型标识符 | 是 | | models | 模型列表（支持多模型） | 否 | | agent_type | Agent 类型（codex 表示 Claude Code） | 是 | | thinking | 思考模式（enabled/disabled/default） | 否 | 资料来源：[web/src/pages/Providers/ProviderList.tsx]() ### Codex 特有配置 对于 `agent_type` 为 `codex` 的 Claude Code Provider，还支持以下特有配置： | 配置项 | 说明 | 来源 | |--------|------|------| | wire_api | Codex Wire API 配置 | ProjectDetail.tsx | ## 会话管理 Claude Code 集成了 cc-connect 的会话管理系统，支持： - 实时会话列表展示 - 最后消息预览 - 会话时间戳显示 - 活跃会话状态指示（Live indicator） 资料来源：[web/src/pages/Sessions/SessionList.tsx]() ## 国际化支持 Claude Code 集成相关的消息已实现多语言支持： | 语言 | 语言代码 | 消息覆盖 | |------|----------|----------| | 英语 | en | ✅ 完整支持 | | 简体中文 | zh | ✅ 完整支持 | | 繁体中文 | zh-TW | ✅ 完整支持 | | 日语 | ja | ✅ 完整支持 | | 西班牙语 | es | ✅ 完整支持 | 资料来源：[core/i18n.go]() ## 使用流程 ### 1. 添加 Provider 在 cc-connect Web 界面的 Providers 页面，添加新的 Provider： 1. 选择或输入 Provider 名称 2. 配置 API 端点（base_url） 3. 设置模型标识符 4. 指定 Agent Type 为 `codex` 5. 根据需要配置 thinking 模式 ### 2. 创建/配置项目 将 Claude Code Provider 关联到项目： 1. 在项目设置中选择 Provider 2. 配置 Agent Mode（权限级别） 3. 设置工作目录 4. 启用/禁用心跳检测（可选） ### 3. 启动会话 与 Claude Code Agent 建立会话： 1. 在会话列表中创建新会话 2. 与 Claude Code 进行交互 3. 监控系统使用量和状态 ## 与其他 Provider 的对比 | 特性 | Claude Code (codex) | 标准 Provider | |------|---------------------|----------------| | Agent Mode | ✅ 支持 | ❌ 不适用 | | Wire API | ✅ 支持特有配置 | ❌ 不适用 | | 心跳检测 | ✅ 支持 | ✅ 支持 | | 多模型支持 | ✅ | ✅ | | thinking 配置 | ✅ | ✅ | ## 注意事项 1. **权限安全**：使用 `bypassPermissions` 或 `dontAsk` 模式时请确保环境安全 2. **API 配置**：Claude Code Provider 需要正确配置 API 端点和模型 3. **源码限制**：当前检索结果中未包含 `agent/claudecode/` 核心源码文件，建议查阅完整仓库以获取精确实现细节 --- ## Codex 集成 ### 相关页面 相关主题：[Agent 集成概述](#agent-overview)
相关源码文件 以下源码文件用于生成本页说明： - [agent/codex/codex.go](https://github.com/chenhg5/cc-connect/blob/main/agent/codex/codex.go) - [agent/codex/session.go](https://github.com/chenhg5/cc-connect/blob/main/agent/codex/session.go) - [agent/codex/provider_config.go](https://github.com/chenhg5/cc-connect/blob/main/agent/codex/provider_config.go) - [web/src/pages/Providers/ProviderList.tsx](https://github.com/chenhg5/cc-connect/blob/main/web/src/pages/Providers/ProviderList.tsx) - [AGENTS.md](https://github.com/chenhg5/cc-connect/blob/main/AGENTS.md)
# Codex 集成 ## 概述 Codex 集成是 cc-connect 项目中实现的一个可选 Agent 类型，允许用户通过统一的 cc-connect 接口与 OpenAI Codex（或兼容 Codex API 协议的服务）进行交互。该集成作为 cc-connect 的插件化 Agent 架构的一部分，通过实现 `core.Agent` 和 `core.AgentSession` 接口来提供完整的会话管理和消息处理能力。 ## 架构设计 ### 模块结构 Codex 集成位于 `agent/codex/` 目录下，包含三个核心文件： | 文件 | 职责 | |------|------| | `codex.go` | 主入口，实现 Agent 工厂函数和核心接口 | | `session.go` | 会话管理，处理消息流和状态维护 | | `provider_config.go` | Provider 配置管理，支持 per-agent 配置 | ### 插件注册机制 根据 cc-connect 的插件化架构设计，Codex Agent 通过 `init()` 函数注册到核心系统： ```go // 伪代码示例 func init() { core.RegisterAgent("codex", NewCodexAgent) } ``` 资料来源：[AGENTS.md]() ## 配置管理 ### Provider 配置结构 Codex 集成支持两种配置模式： 1. **全局配置**：通过 `config.toml` 或 `cc-connect provider add` 命令添加 2. **Per-Agent 配置**：允许每个项目/工作区独立配置 Codex 参数 ### wire_api 配置 Codex 集成支持 `wire_api` 参数，用于配置特殊的 API 协议处理： ```go config.wire_api // Codex 特定的 API 线协议配置 ``` 资料来源：[web/src/pages/Providers/ProviderList.tsx:1]() ### Thinking 配置 Codex Agent 支持 thinking 参数控制： | 值 | 行为 | |----|------| | 空字符串 | 使用 Provider 默认设置 | | `enabled` | 强制启用 thinking 模式 | | `disabled` | 强制禁用 thinking 模式 | 资料来源：[web/src/pages/Providers/ProviderList.tsx:1]() ## 界面集成 ### Provider 管理界面 在 cc-connect Web 管理界面的 **Provider List** 页面中，Codex 作为特殊的 Agent 类型进行配置： ``` Agent Type 选择: codex ``` 当选择 Codex 类型时，界面会显示额外的 `wire_api` 配置选项： ```tsx {agentType === 'codex' && (