项目简介

cc-connect 是一个多平台 AI 代理连接框架，旨在将不同的 AI 代理服务与多种即时通讯平台进行桥接整合。该项目采用 Go 语言作为后端核心，前端使用 React + TypeScript 构建管理界面，实现了统一配置管理、多平台支持、灵活的代理切换等核心功能。

项目的设计理念是提供一个 中立的中间层，使 AI 代理能力能够通过各种通讯平台（如飞书、微信、企业微信、Telegram、Discord 等）与用户进行交互。资料来源：AGENTS.md:1-15

系统架构

cc-connect 采用分层架构设计，核心模块与平台模块解耦，便于扩展和维护。

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 可以包含以下配置项：

资料来源：web/src/pages/Providers/ProviderList.tsx:1-30

Project（项目）

Project 是工作空间的基本单位，每个项目包含独立的配置和会话管理。项目支持以下关键配置：

资料来源：web/src/pages/Projects/ProjectDetail.tsx:1-40

Session（会话）

Session 管理与 AI 代理的交互状态，包含消息历史和实时状态：

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 代理的能力，支持本地技能和预设技能库：

资料来源：web/src/pages/Skills/SkillList.tsx:1-50

平台支持

cc-connect 支持多种即时通讯平台的集成，构建时可以通过 build tags 选择性排除不需要的平台：

禁用特定平台的编译方式：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）支持，支持以下语言：

关键消息类型包括：

• Provider 操作消息（切换、清除、列表）
• Workspace 操作消息（绑定、路由）
• 错误提示与帮助信息

资料来源：core/i18n.go:1-60

前端架构

前端采用 React + TypeScript + TailwindCSS 构建，提供现代化的管理界面：

主要页面模块

状态管理

前端通过 React Hooks 管理状态，关键状态包括：

• providers: 全局 AI 提供商列表
• projects: 项目列表
• sessions: 会话列表
• currentSession: 当前活跃会话
• drawerOpen: 会话抽屉开关状态
• bridgeStatus: WebSocket 桥接状态

资料来源：web/src/pages/Chat/ChatView.tsx:1-30

消息处理

企业微信文件消息

企业微信平台的文件消息采用 XML 格式传输，系统会解析以下字段：

资料来源：platform/wecom/inbound_file_test.go:1-25

项目构建与测试

构建检查清单

提交代码前必须通过以下检查：

1. 编译通过：go build ./...
2. 测试通过：go test ./...
3. 无硬编码：核心代码中无平台名称硬编码
4. 国际化完整：新增用户可见字符串需包含所有语言翻译
5. 无敏感信息：源码中不包含 API Key、Token 等凭据

资料来源：AGENTS.md:25-32

技术栈总结

资料来源：web/index.html:1-10

设计理念

cc-connect 的核心设计原则：

1. 模块化解耦：核心接口与平台实现分离，便于独立演进
2. 可插拔架构：通过 build tags 实现平台按需编译
3. 统一配置管理：通过 Web UI 或配置文件集中管理所有设置
4. 多语言支持：内置 5 种语言的国际化消息
5. 开发者友好：提供清晰的插件开发指南和代码规范

这种设计使得 cc-connect 能够灵活适应不同的部署场景，既可以作为单一平台桥接工具，也可以扩展为完整的多平台 AI 代理中控系统。

概述

cc-connect 是一个连接本地 AI 编程助手与即时通讯平台的中间件系统。其核心架构采用模块化设计，将 AI Agent（Claude Code、Codex、Cursor 等）、消息平台（Discord、Telegram、飞书等）和会话管理解耦，通过统一的引擎层进行协调调度。

架构设计遵循以下核心原则：

• 插件化平台支持：通过 core.RegisterPlatform 注册机制支持新平台的热插拔
• 多项目隔离：每个项目拥有独立的工作目录、Agent 配置和会话上下文
• 统一消息协议：不同平台的消息统一转换为内部标准格式进行处理
• 前端分离：Web 管理界面与后端核心服务通过 REST API 解耦

核心架构图

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 等

// 资料来源：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<string, string>;
  agent_models?: Record<string, string>;
  agent_model_lists?: Record<string, string[]>;
}

Bridge（网桥）

Bridge 负责维护与各消息平台的实时连接状态，实现消息的双向转发：

• 连接状态管理：追踪 connecting、connected、disconnected、error 等状态
• 消息编码/解码：将内部消息格式与各平台专有格式相互转换
• 心跳机制：通过心跳保持与平台的长连接活跃

// 资料来源：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 配置选项

# 资料来源：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 模式说明

平台架构

支持的消息平台

cc-connect 通过插件化架构支持多种即时通讯平台：

平台注册机制

新增平台需要完成以下步骤：

1. 创建平台目录 platform/<platformname>/
2. 实现 core.Platform 接口
3. 在 init() 函数中调用 core.RegisterPlatform()
4. 创建构建标签文件 cmd/cc-connect/plugin_platform_<platformname>.go
5. 添加到 Makefile 的 ALL_PLATFORMS 变量

// 资料来源：AGENTS.md:25-30
// 伪代码示例
func init() {
    core.RegisterPlatform("newplatform", newPlatformFactory)
}

会话管理架构

会话生命周期

stateDiagram-v2
    [*] --> 创建中: 新建项目
    创建中 --> 活跃: 连接成功
    活跃 --> 等待中: 消息发送
    等待中 --> 活跃: 响应接收
    活跃 --> 断开: 关闭连接
    断开 --> 活跃: 重新连接
    活跃 --> [*]: 项目删除

会话数据结构

// 资料来源：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 类与后端通信：

// 资料来源：web/src/api/client.ts:1-30
class ApiClient {
  get<T>(path: string, params?: Record<string, string>): Promise<T>
  post<T>(path: string, body?: any): Promise<T>
  put<T>(path: string, body?: any): Promise<T>
  patch<T>(path: string, body?: any): Promise<T>
  delete<T>(path: string): Promise<T>
  raw(path: string): Promise<string>  // 非 JSON 响应
}

认证机制

API 使用 Bearer Token 进行认证：

// 资料来源：web/src/api/client.ts:20-25
const h: HeadersInit = {};
if (this.token) h['Authorization'] = `Bearer ${this.token}`;

项目配置架构

配置层级

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]

配置示例

# 资料来源：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"

工作目录隔离

每个项目拥有独立的工作目录，确保项目间环境互不影响：

// 资料来源：web/src/pages/Projects/ProjectDetail.tsx:10-15
<Input
  label={t('projects.workDir', 'Working directory')}
  value={workDir}
  onChange={(e) => setWorkDir(e.target.value)}
  placeholder="/path/to/project"
/>

消息流转架构

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: 显示响应

前端技术栈

前端页面结构

国际化

系统支持多语言界面，通过统一的翻译函数实现：

// 资料来源：core/i18n.go:10-40
MsgProviderSwitchHint: {
    LangEnglish:            "`/provider switch <name>` to switch",
    LangChinese:            "`/provider switch <名称>` 切换",
    LangTraditionalChinese: "`/provider switch <名稱>` 切換",
    LangJapanese:           "`/provider switch <名前>` で切り替え",
    LangSpanish:            "`/provider switch <nombre>` para cambiar",
}

支持语言：en（英语）、zh（简体中文）、zh-TW（繁体中文）、ja（日语）、es（西班牙语）

构建与部署

构建标签

cc-connect 使用 Go 构建标签实现平台和 Agent 的条件编译：

# 资料来源：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 <path> 命令行参数
2. ./config.toml 当前目录
3. ~/.cc-connect/config.toml 全局配置（推荐）

扩展指南

新增 Agent 步骤

1. 创建 agent/<agentname>/<agentname>.go
2. 实现 core.Agent 和 core.AgentSession 接口
3. 在 init() 中调用 core.RegisterAgent()
4. 创建 cmd/cc-connect/plugin_agent_<agentname>.go
5. 添加到 Makefile 的 ALL_AGENTS

新增平台步骤

1. 创建 platform/<platformname>/<platformname>.go
2. 实现 core.Platform 接口
3. 在 init() 中调用 core.RegisterPlatform()
4. 创建 cmd/cc-connect/plugin_platform_<platformname>.go
5. 添加到 Makefile 的 ALL_PLATFORMS

总结

cc-connect 采用清晰的分层架构设计：

• 前端层：React + TypeScript 构建的管理界面
• 核心层：Engine、Bridge、Registry 组成的调度核心
• Agent 层：支持多种 AI 编程助手的统一抽象
• 平台层：插件化的即时通讯平台集成

这种架构使得系统具有良好的可扩展性和可维护性，能够方便地接入新的 Agent 类型和消息平台，同时保持核心逻辑的稳定性。

概述

cc-connect 是一个将 AI 编码代理（如 Claude Code、Codex、Cursor 等）与多种消息平台（飞书、Telegram、Discord 等）连接的基础设施项目。其核心架构基于接口驱动设计，通过抽象层解耦代理实现与平台接入，使系统具备高度可扩展性。

核心接口体系包含三大支柱：

资料来源：AGENTS.md:1-20

接口架构图

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() 函数完成：

core.RegisterAgent("newagent", factory)

资料来源：AGENTS.md:35-44

支持的代理类型

资料来源：AGENTS.md:43-52

代理配置选项

代理的 options 配置块支持以下参数：

资料来源：INSTALL.md:28-42

[projects.agent]
type = "claudecode"
[projects.agent.options]
work_dir = "/absolute/path/to/your/project"
mode = "default"  # 或 acceptEdits, plan, bypassPermissions, dontAsk

平台接口体系

Platform 接口

消息平台通过实现 core.Platform 接口接入系统。接口支持可选扩展以提供更丰富的功能。

平台注册同样通过 init() 函数：

core.RegisterPlatform("newplatform", factory)

资料来源：AGENTS.md:17-33

支持的平台类型

资料来源：AGENTS.md:1-15

平台编译策略

cc-connect 采用构建标签（Build Tags） 实现选择性编译，每个平台/代理通过独立的 plugin_*.go 文件导入：

//go:build !no_feishu

#### 编译命令示例

资料来源：AGENTS.md:70-91

Provider 接口体系

Provider 管理

Provider 负责管理与 AI 模型的连接配置，支持多种模型供应商的统一抽象。

Provider 配置结构

[[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 预设，支持一键配置常用供应商：

资料来源：web/src/pages/Providers/ProviderList.tsx:80-95

Session 管理

会话生命周期

会话（Session）是连接平台消息与代理执行的桥梁。每个会话独立维护上下文状态。

会话支持以下操作：

• /workspace bind <workspace-name> - 绑定工作区
• /workspace route <absolute-path> - 设置路由路径
• /provider switch <name> - 切换 Provider
• /provider clear - 清除 Provider 选择

资料来源：core/i18n.go:50-100

会话状态消息

资料来源：core/i18n.go:1-80

项目配置模型

完整配置结构

[[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

项目级功能开关

资料来源：web/src/pages/Projects/ProjectDetail.tsx:50-80

国际化接口

消息定义格式

系统使用统一的国际化消息接口，支持多语言：

消息定义示例：

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

测试规范

接口测试要点

资料来源：AGENTS.md:60-65

编译检查清单

新增代码必须通过以下检查：

资料来源：AGENTS.md:22-31

总结

cc-connect 的核心接口体系采用简洁而强大的设计：

• 接口抽象：通过 Agent、Platform、Provider 三大接口抽象不同实现
• 插件化编译：使用构建标签实现按需编译，减少二进制体积
• 国际化优先：所有用户可见文本通过统一的 i18n 接口管理
• 配置驱动：通过 TOML 配置文件灵活管理项目设置

这种设计使开发者能够以一致的方式添加新的代理类型或消息平台，同时保持核心引擎的稳定性和可测试性。

概述

Bridge 协议是 cc-connect 项目中的核心通信机制，用于在 Web 前端与后端引擎之间建立双向实时通信通道。它通过 WebSocket 技术实现低延迟的消息传递，支持多项目引擎管理、命令发布与订阅、以及卡片导航功能。

Bridge 协议的核心组件位于 core/bridge.go 和 core/bridge_capabilities.go 中，为整个应用提供可靠的前后端桥接能力。

简介

Agent 集成是 cc-connect 项目的核心功能模块，负责将多种 AI Agent 提供商统一接入到平台中。该模块通过抽象层设计，支持多种 Agent 运行时环境，包括 ACP Agent、Claude Code 和 Codex 等主流 AI 编程助手。

Agent 系统的设计目标是通过统一的接口规范，将不同提供商的 Agent 能力整合到同一个协作框架中，使开发者能够在项目中灵活切换和配置不同的 AI 助手，同时保持一致的用户体验和项目管理流程。

概述

Agent 通信协议是 CC-Connect 系统中实现多 Agent 之间消息传递、会话管理和状态同步的核心机制。该协议支撑了前端界面与后端 Agent 引擎之间的实时交互能力。

会话管理机制

会话（Session）是 Agent 通信的基本单元，每个会话包含唯一的标识符、状态信息和消息历史记录。

会话状态类型

资料来源：web/src/pages/Sessions/SessionList.tsx:4-5

会话消息结构

会话消息采用角色化结构，支持用户消息和 Agent 回复两种基本角色：

interface SessionMessage {
  role: 'user' | 'assistant';
  content: string;
  timestamp?: string;
}

消息预览功能限制显示内容长度为 100 字符，并替换换行符为空格以保持布局整洁。资料来源：web/src/pages/Sessions/SessionList.tsx:12-15

桥接连接机制

连接状态监控

Agent 通信依赖桥接（Bridge）机制实现前端与后端的长连接通信。系统提供三种连接状态：

资料来源：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 相关命令

资料来源：core/i18n.go:1-10

Workspace 相关命令

消息国际化

系统支持多语言消息提示，确保 Agent 通信过程中的用户反馈清晰易懂：

资料来源：core/i18n.go:1-8

前端通信组件

ChatView 组件架构

ChatView 是核心通信视图组件，负责协调以下子组件：

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 组件

会话抽屉组件提供侧边栏式会话管理界面，支持：

• 会话列表展示
• 当前会话高亮
• 快速切换会话
• 新建会话入口

状态管理

会话状态同步

// 会话状态更新流程
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 集成是 cc-connect 项目中连接 Claude Code Agent 的核心功能模块。该集成允许用户在 cc-connect 平台中配置和使用 Claude Code 作为 AI 代码助手 provider，实现与 Claude Code 的无缝对接。

架构设计

核心组件

Claude Code 集成主要包含以下核心模块：

Provider 集成

Claude Code 作为一种特殊的 Agent Type（codex）集成到 cc-connect 的 Provider 系统中。用户可以在 Provider 配置界面选择或配置 Claude Code 作为 AI 服务提供商。

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 的运行权限模式：

资料来源：web/src/pages/Projects/ProjectDetail.tsx

Provider 配置

Claude Code Provider 支持以下核心配置项：

资料来源：web/src/pages/Providers/ProviderList.tsx

Codex 特有配置

对于 agent_type 为 codex 的 Claude Code Provider，还支持以下特有配置：

会话管理

Claude Code 集成了 cc-connect 的会话管理系统，支持：

• 实时会话列表展示
• 最后消息预览
• 会话时间戳显示
• 活跃会话状态指示（Live indicator）

资料来源：web/src/pages/Sessions/SessionList.tsx

国际化支持

Claude Code 集成相关的消息已实现多语言支持：

资料来源：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 的对比

注意事项

1. 权限安全：使用 bypassPermissions 或 dontAsk 模式时请确保环境安全
2. API 配置：Claude Code Provider 需要正确配置 API 端点和模型
3. 源码限制：当前检索结果中未包含 agent/claudecode/ 核心源码文件，建议查阅完整仓库以获取精确实现细节

概述

Codex 集成是 cc-connect 项目中实现的一个可选 Agent 类型，允许用户通过统一的 cc-connect 接口与 OpenAI Codex（或兼容 Codex API 协议的服务）进行交互。该集成作为 cc-connect 的插件化 Agent 架构的一部分，通过实现 core.Agent 和 core.AgentSession 接口来提供完整的会话管理和消息处理能力。

架构设计

模块结构

Codex 集成位于 agent/codex/ 目录下，包含三个核心文件：

插件注册机制

根据 cc-connect 的插件化架构设计，Codex Agent 通过 init() 函数注册到核心系统：

// 伪代码示例
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 协议处理：

config.wire_api // Codex 特定的 API 线协议配置

资料来源：web/src/pages/Providers/ProviderList.tsx:1

Thinking 配置

Codex Agent 支持 thinking 参数控制：

资料来源：web/src/pages/Providers/ProviderList.tsx:1

界面集成

Provider 管理界面

在 cc-connect Web 管理界面的 Provider List 页面中，Codex 作为特殊的 Agent 类型进行配置：

Agent Type 选择: codex

当选择 Codex 类型时，界面会显示额外的 wire_api 配置选项：

{agentType === 'codex' && (
    <div>
      <label>Codex Wire API</label>
      <select value={config.wire_api || ''} onChange={...} />
    </div>
)}

资料来源：web/src/pages/Providers/ProviderList.tsx:1

消息处理流程

graph TD
    A[用户消息] --> B[cc-connect Core]
    B --> C[Codex Agent]
    C --> D[Codex Session]
    D --> E[Codex API Provider]
    E --> F[API 响应]
    F --> G[Session 状态更新]
    G --> H[消息流返回]

与其他 Agent 的对比

添加新的 Agent 类型

如需参考 Codex 的实现方式来添加新的 Agent，可参考 AGENTS.md 中的指南：

1. 创建 agent/newagent/newagent.go
2. 实现 core.Agent 和 core.AgentSession 接口
3. 在 init() 函数中注册：core.RegisterAgent("newagent", factory)
4. 创建 cmd/cc-connect/plugin_agent_newagent.go 并添加 //go:build !no_newagent 标签
5. 在 Makefile 的 ALL_AGENTS 中添加新 Agent
6. 在 config.example.toml 中添加配置示例
7. 添加单元测试

资料来源：AGENTS.md

总结

Codex 集成展示了 cc-connect 插件化架构的灵活性。通过实现标准化的 Agent 接口，Codex 能够无缝融入 cc-connect 的会话管理、Provider 管理和配置系统。Per-agent 配置能力和 wire_api 特殊参数的支持，使得 Codex 集成能够适应不同的部署场景和 API 提供商需求。

简介

cc-connect 是一个多平台代理连接器，支持将多个 AI 编码助手平台（如 Claude Code、Cursor、Kimi 等）统一接入到单一界面进行管理。平台集成系统是 cc-connect 的核心架构之一，它通过标准化的 core.Platform 接口定义，允许以插件化方式加载和管理不同的即时通讯平台。

当前支持的平台包括飞书（Feishu）、Telegram、Slack、Discord、钉钉（DingTalk）、企业微信（WeCom）、微信（Weixin）、QQ、Line、微博（Weibo）等。

核心架构

平台接口设计

平台模块需要实现 core.Platform 接口，这是所有平台集成的核心契约。接口定义包含平台初始化、消息处理、会话管理等功能。

graph TD
    A[core.Platform 接口] --> B[平台初始化 init]
    A --> C[消息接收与处理]
    A --> D[会话管理]
    A --> E[平台配置]
    
    B --> B1[RegisterPlatform 注册]
    C --> C1[消息路由]
    D --> D1[Session 会话]
    E --> E1[配置解析]

平台注册机制

平台通过 init() 函数在启动时自动注册到核心系统：

core.RegisterPlatform("newplatform", factory)

此机制遵循 Go 语言的插件化设计理念，允许在编译时通过构建标签（build tags）选择性地包含或排除特定平台。资料来源：AGENTS.md:30

构建标签控制

平台的可选性通过 Go 构建标签实现，开发者可以使用 no_ 前缀的标签来排除不需要的平台：

编译示例：

# 排除飞书和钉钉平台
go build -tags "no_feishu,no_dingtalk"

资料来源：AGENTS.md:5-6

新增平台流程

步骤概览

graph LR
    A[创建平台目录] --> B[实现 Platform 接口]
    B --> C[注册平台 init]
    C --> D[创建构建文件]
    D --> E[添加到 Makefile]
    E --> F[添加配置示例]
    F --> G[编写单元测试]

详细步骤

#### 1. 创建平台目录结构

在 platform/ 目录下创建新平台目录：

platform/newplatform/
└── newplatform.go

#### 2. 实现 core.Platform 接口

创建 platform/newplatform/newplatform.go 文件，实现 core.Platform 接口以及可选的扩展接口。

#### 3. 注册平台

在 init() 函数中调用注册方法：

func init() {
    core.RegisterPlatform("newplatform", NewPlatform)
}

#### 4. 创建构建文件

创建 cmd/cc-connect/plugin_platform_newplatform.go，并添加构建标签：

//go:build !no_newplatform

package main

此文件用于在主程序中链接平台插件。

#### 5. 更新 Makefile

将新平台名称添加到 Makefile 中的 ALL_PLATFORMS 变量。

#### 6. 添加配置示例

在 config.example.toml 中添加该平台的配置示例段。

#### 7. 编写单元测试

为新平台创建对应的测试文件，确保核心功能覆盖。

资料来源：AGENTS.md:28-35

平台配置管理

Web 管理界面

cc-connect 提供了基于 Web 的配置管理界面，支持可视化配置各平台的连接参数。

#### Provider 配置

Provider 是平台配置的核心概念，用于定义 AI 模型提供商：

interface Provider {
  name: string;           // 提供商名称
  base_url?: string;      // API 基础地址
  model?: string;         // 默认模型
  models?: Model[];       // 模型列表
  api_key?: string;       // API 密钥
  thinking?: string;      // 思考模式设置
  agent_types?: string[]; // 支持的代理类型
}

资料来源：web/src/pages/Providers/ProviderList.tsx:1-50

#### Agent Type 支持

平台可支持的 Agent 类型包括：

Web 界面中通过多选按钮组进行 Agent 类型的选择和配置。资料来源：web/src/pages/Providers/ProviderList.tsx:100-120

国际化配置

平台相关的用户提示信息通过 core/i18n.go 进行多语言管理。当前支持的语言包括：

每条消息都定义了对应语言的翻译文本，确保用户在不同语言环境下获得一致体验。资料来源：core/i18n.go:1-50

项目与会话管理

项目系统

每个平台连接的项目（Project）包含以下核心配置：

interface Project {
  name: string;              // 项目名称
  agent_type: string;        // 代理类型
  platforms?: string[];     // 启用的平台列表
  work_dir?: string;        // 工作目录
  agent_mode?: string;      // 代理模式
  heartbeat_enabled?: boolean;  // 心跳功能启用
  sessions_count?: number;  // 会话数量
}

#### Agent Mode 选项

资料来源：web/src/pages/Projects/ProjectList.tsx:50-80

会话系统

会话（Session）代表用户与 AI 代理之间的单次交互：

interface Session {
  id: string;
  name?: string;
  user_name?: string;
  live?: boolean;           // 是否在线
  last_message?: {
    role: 'user' | 'assistant';
    content: string;
  };
  updated_at?: string;
  created_at?: string;
}

会话列表支持显示实时状态指示器、最后消息预览等功能。资料来源：web/src/pages/Sessions/SessionList.tsx:1-30

心跳机制

心跳（Heartbeat）功能用于维持项目与平台连接的活跃状态：

心跳配置项

资料来源：web/src/pages/Projects/ProjectDetail.tsx:1-30

心跳控制操作

技能系统

技能（Skills）允许在项目中预设和管理可用的工具集：

interface SkillPreset {
  name: string;
  display_name?: string;
  project: string;          // 所属项目
  agent_type: string;       // 代理类型
  skills?: Skill[];         // 技能列表
  dirs?: string[];          // 扫描目录
  source?: {
    url?: string;
    name?: string;
    provider?: string;
  };
  author?: string;
  description?: string;
  description_zh?: string;
  tags?: string[];
  version?: string;
  pricing?: string;
  url?: string;
}

技能来源可以是本地定义的技能，也可以是远程下载的技能包。资料来源：web/src/pages/Skills/SkillList.tsx:1-60

工作区管理

工作区（Workspace）功能允许用户绑定和管理多个工作空间：

资料来源：core/i18n.go:200-250

开发检查清单

新增平台时需要遵循以下检查流程：

1. 构建通过：go build ./...
2. 测试通过：go test ./...
3. 无硬编码：核心代码中不得有新的平台名称硬编码
4. 国际化完整：所有用户可见字符串需包含所有语言翻译
5. 无敏感信息：源码中不得包含 API Key、Token 等凭据

资料来源：AGENTS.md:8-16

相关文件结构

cc-connect/
├── core/
│   ├── platform.go          # Platform 接口定义
│   └── i18n.go             # 国际化支持
├── platform/
│   ├── feishu/             # 飞书平台
│   ├── telegram/           # Telegram 平台
│   ├── slack/              # Slack 平台
│   └── ...                 # 其他平台
├── web/
│   └── src/pages/
│       ├── Providers/      # 提供商管理
│       ├── Projects/       # 项目管理
│       ├── Sessions/       # 会话管理
│       └── Skills/         # 技能管理
└── cmd/cc-connect/
    └── plugin_platform_*.go # 平台插件构建文件

总结

平台集成系统采用插件化架构设计，通过标准接口和构建标签实现高度的灵活性和可扩展性。开发者可以通过遵循既定的开发流程快速添加新平台支持，同时系统提供的 Web 管理界面降低了运维复杂度。

Pitfall Log / 踩坑日志

项目：chenhg5/cc-connect

摘要：发现 24 个潜在踩坑项，其中 6 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Bug]。

1. 安装坑 · 来源证据：[Bug]

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_c85c0f8f48ac44c7a855066b2bfc3939 | https://github.com/chenhg5/cc-connect/issues/933 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：[Feature] Preserve full interactive card schema on inbound

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature] Preserve full interactive card schema on inbound
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_f50380a7aef54548ac053b1127a2916e | https://github.com/chenhg5/cc-connect/issues/936 | 来源类型 github_issue 暴露的待验证使用条件。

3. 安装坑 · 来源证据：cc-connect 因 SSH 断开被 systemd 停止：需要文档化 `loginctl enable-linger`

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：cc-connect 因 SSH 断开被 systemd 停止：需要文档化 loginctl enable-linger
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_3a818efa6ddf479aae0f026d1f06d491 | https://github.com/chenhg5/cc-connect/issues/960 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

4. 配置坑 · 来源证据：Feishu: all messages permanently ignored as 'old message after restart' after every daemon restart (v1.3.3-beta.2)

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Feishu: all messages permanently ignored as 'old message after restart' after every daemon restart (v1.3.3-beta.2)
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_7b001c45ac3449abaee3dd365bc4cc74 | https://github.com/chenhg5/cc-connect/issues/972 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。

5. 配置坑 · 来源证据：[Bug] cc-connect send uses default socket path in custom data_dir agent sessions

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug] cc-connect send uses default socket path in custom data_dir agent sessions
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_6136e384578b499ca63299322032211a | https://github.com/chenhg5/cc-connect/issues/966 | 来源类型 github_issue 暴露的待验证使用条件。

6. 安全/权限坑 · 来源证据：Feature Request: 终端与 IM 双通道统一会话管理

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature Request: 终端与 IM 双通道统一会话管理
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_befa8b4f1c7f4ef483d6d8b38ba06ba4 | https://github.com/chenhg5/cc-connect/issues/968 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

7. 安装坑 · 来源证据：v1.3.3-beta.1

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.3.3-beta.1
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_5eb39ef63cf14e56aff580db738dcd9f | https://github.com/chenhg5/cc-connect/releases/tag/v1.3.3-beta.1 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

8. 安装坑 · 来源证据：生图 app-icon 请求未稳定转发到 generate-image，且 cc-connect 存在部署漂移风险

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：生图 app-icon 请求未稳定转发到 generate-image，且 cc-connect 存在部署漂移风险
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_574cca97359b4bc1a8a8fa968ab758cb | https://github.com/chenhg5/cc-connect/issues/967 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

9. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
• 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
• 证据：capability.host_targets | github_repo:1168978399 | https://github.com/chenhg5/cc-connect | host_targets=claude, claude_code, cursor

10. 配置坑 · 来源证据：v1.3.0-rc.3

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.3.0-rc.3
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_9e274ec877304b369e551afc543b9bae | https://github.com/chenhg5/cc-connect/releases/tag/v1.3.0-rc.3 | 来源类型 github_release 暴露的待验证使用条件。

11. 配置坑 · 来源证据：v1.3.1

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.3.1
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_c2e03a5e0cc8465c968bcc252cc2926b | https://github.com/chenhg5/cc-connect/releases/tag/v1.3.1 | 来源类型 github_release 暴露的待验证使用条件。

12. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:1168978399 | https://github.com/chenhg5/cc-connect | README/documentation is current enough for a first validation pass.

13. 运行坑 · 来源证据：出现网络波动后，一直显示这个retrying，只能手动重启吗？

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：出现网络波动后，一直显示这个retrying，只能手动重启吗？
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_8d8f7103758f4f46bffd9b411c81bbf6 | https://github.com/chenhg5/cc-connect/issues/102 | 来源类型 github_issue 暴露的待验证使用条件。

14. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:1168978399 | https://github.com/chenhg5/cc-connect | last_activity_observed missing

15. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:1168978399 | https://github.com/chenhg5/cc-connect | no_demo; severity=medium

16. 安全/权限坑 · 存在安全注意事项

• 严重度：medium
• 证据强度：source_linked
• 发现：No sandbox install has been executed yet; downstream must verify before user use.
• 对用户的影响：用户安装前需要知道权限边界和敏感操作。
• 建议检查：转成明确权限清单和安全审查提示。
• 防护动作：安全注意事项必须面向用户前置展示。
• 证据：risks.safety_notes | github_repo:1168978399 | https://github.com/chenhg5/cc-connect | No sandbox install has been executed yet; downstream must verify before user use.

17. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:1168978399 | https://github.com/chenhg5/cc-connect | no_demo; severity=medium

18. 安全/权限坑 · 来源证据：v1.3.0

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.3.0
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_8f40f1ed300048309ccb1501f52a5fd3 | https://github.com/chenhg5/cc-connect/releases/tag/v1.3.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

19. 安全/权限坑 · 来源证据：v1.3.0-rc.4

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.3.0-rc.4
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_83a9e36b399040b69147511b6daa7275 | https://github.com/chenhg5/cc-connect/releases/tag/v1.3.0-rc.4 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

20. 安全/权限坑 · 来源证据：v1.3.0-rc.5

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.3.0-rc.5
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_dc65ca84aa28428b93104b658be55c16 | https://github.com/chenhg5/cc-connect/releases/tag/v1.3.0-rc.5 | 来源类型 github_release 暴露的待验证使用条件。

21. 安全/权限坑 · 来源证据：v1.3.2

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.3.2
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_2245b50ba3e94323b2228f6ed5b2b73e | https://github.com/chenhg5/cc-connect/releases/tag/v1.3.2 | 来源类型 github_release 暴露的待验证使用条件。

22. 安全/权限坑 · 来源证据：v1.3.3-beta.2

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.3.3-beta.2
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_4665651336a6450db47e6262a8926c7b | https://github.com/chenhg5/cc-connect/releases/tag/v1.3.3-beta.2 | 来源类型 github_release 暴露的待验证使用条件。

23. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:1168978399 | https://github.com/chenhg5/cc-connect | issue_or_pr_quality=unknown

24. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:1168978399 | https://github.com/chenhg5/cc-connect | release_recency=unknown