{t('setup.manualHint', 'For {{platform}}, please configure credentials in config.toml')}
{t('projects.agentTypeChangeHint', 'Changing agent type requires restart. Incompatible providers will be removed.')}
)}thinking: {p.thinking}
)} ``` Supported thinking modes: - `enabled` - Thinking explicitly enabled - `disabled` - Thinking explicitly disabled - `""` (empty) - Use default setting 资料来源：[web/src/pages/Providers/ProviderList.tsx:1-10]() ## Message Processing Flow ```mermaid graph LR A[Incoming Message] --> B[Platform Adapter] B --> C{Message Type?} C -->|Text| D[Parse Intent] C -->|Command| E[Handle Command] C -->|Media| F[Process Attachment] D --> G[Agent Processing] E --> G F --> G G --> H[Response Generation] H --> I[Markdown Rendering] I --> J[HTML Sanitization] J --> K[Platform Delivery] K --> L[End User] ``` ## Internationalization All platform-related user-facing messages support multiple languages: | Language | Code | |----------|------| | English | `en` | | Chinese (Simplified) | `zh` | | Chinese (Traditional) | `zh-TW` | | Japanese | `ja` | | Spanish | `es` | Provider-related messages include: - `MsgProviderSwitchHint`: Command hints for switching providers - `MsgProviderNotFound`: Error when provider doesn't exist - `MsgProviderSwitched`: Confirmation when provider changes 资料来源：[core/i18n.go:1-30]() ## Session Management Sessions are tracked per-platform with metadata: ```typescript interface Session { id: string; name?: string; user_name?: string; live?: boolean; updated_at?: string; created_at?: string; last_message?: { role: 'user' | 'bot'; content: string; }; } ``` 资料来源：[web/src/pages/Sessions/SessionList.tsx:1-20]() ## Markdown to HTML Rendering Platform integrations utilize the `MarkdownToSimpleHTML` function for rendering agent responses: ```go func MarkdownToSimpleHTML(md string) string ``` Features supported: - Code blocks with language syntax (``)
- Links (``)
- Headings converted to bold (``)
- Blockquotes (``)
- HTML escaping for special characters (`<`, `>`, `&`)
资料来源：[core/markdown_html_test.go:1-40]()
## Summary
Platform Integrations in cc-connect provide a unified, extensible system for connecting AI agents to multiple messaging platforms. The architecture emphasizes:
- **Modularity**: Each platform is a separate plugin
- **Flexibility**: Multiple connection methods (webhook, long polling, WebSocket)
- **Security**: Build tags allow excluding platforms
- **Internationalization**: Full multi-language support
- **Web Management**: Admin UI for platform configuration
---
## Configuration Guide
### 相关页面
相关主题：[Session Management](#page-session-management), [Web UI Administration](#page-web-ui)
相关源码文件
以下源码文件用于生成本页说明：
- [config/config.go](https://github.com/chenhg5/cc-connect/blob/main/config/config.go)
- [config.example.toml](https://github.com/chenhg5/cc-connect/blob/main/config.example.toml)
- [core/provider_presets.go](https://github.com/chenhg5/cc-connect/blob/main/core/provider_presets.go)
- [core/skill_presets.go](https://github.com/chenhg5/cc-connect/blob/main/core/skill_presets.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)
# Configuration Guide
## Overview
The cc-connect configuration system provides a flexible, multi-layered approach to managing AI provider settings, project configurations, and skill definitions. This guide covers all configuration aspects including global providers, project-specific settings, and skill presets.
## Configuration Architecture
The system uses a hierarchical configuration model with three primary layers:
```mermaid
graph TD
A[config.toml - Global Config] --> B[Project-level Settings]
B --> C[Provider Configuration]
C --> D[Model & API Settings]
E[Skill Presets] -.-> B
F[Provider Presets] -.-> C
```
## Global Configuration
Global settings are managed through `config.toml` located in the application root directory. This file contains default providers and system-wide settings that apply across all projects.
### Provider Configuration
Providers define the API endpoints and models used by agents. Each provider can be configured with multiple models and supports various agent types.
| Parameter | Type | Description | Required |
|-----------|------|-------------|----------|
| `name` | string | Unique provider identifier | Yes |
| `base_url` | string | API endpoint URL | Yes |
| `model` | string | Default model name | Yes |
| `models` | array | List of available models | No |
| `thinking` | string | Thinking mode: `enabled`, `disabled`, or empty for default | No |
| `agent_type` | string | Associated agent type (e.g., `codex`, `claude`) | No |
资料来源：[web/src/pages/Providers/ProviderList.tsx:1-50]()
### Agent Types
The system supports multiple agent types with different capability profiles:
| Agent Type | Description |
|------------|-------------|
| `codex` | Code-focused agent with extended capabilities |
| `claude` | Anthropic Claude-based agent |
| `default` | Standard agent configuration |
资料来源：[web/src/pages/Projects/ProjectDetail.tsx:1-30]()
### Permission Modes
Agents can operate in different permission modes controlling their operational boundaries:
| Mode | Description |
|------|-------------|
| `default` | Standard permission level |
| `acceptEdits` | Agent can directly edit files |
| `plan` | Agent only plans, does not execute |
| `bypassPermissions` | YOLO mode - skips permission checks |
| `dontAsk` | No confirmation prompts |
资料来源：[web/src/pages/Projects/ProjectDetail.tsx:30-60]()
## Provider Presets
Provider presets provide pre-configured settings for common AI providers, sorted by pricing tier.
### Tier System
Presets are organized into tiers reflecting cost and capability levels:
```mermaid
graph LR
A[Tier 1 - Premium] --> B[Tier 2 - Standard]
B --> C[Tier 3 - Budget]
C --> D[Tier 4 - Free/Local]
```
| Tier | Description | Example Providers |
|------|-------------|-------------------|
| 1 | Premium APIs | Claude, GPT-4 |
| 2 | Standard APIs | GPT-3.5, Gemini Pro |
| 3 | Budget APIs | Various open-source models |
| 4 | Free/Local | Local deployments, free tiers |
资料来源：[web/src/pages/Providers/ProviderList.tsx:80-120]()
### Adding Providers from Presets
```typescript
interface ProviderPreset {
name: string;
tier: number;
agent_types: string[];
models: string[];
thinking?: string;
}
```
The preset grid displays available presets sorted by tier. Existing provider names are filtered out using `Set` to prevent duplicates.
资料来源：[web/src/pages/Providers/ProviderList.tsx:100-150]()
## Project Configuration
Each project maintains its own configuration including agent type, working directory, and platform-specific settings.
### Project Settings Structure
| Setting | Type | Description |
|---------|------|-------------|
| `name` | string | Project identifier (alphanumeric, `-`, `_`) |
| `agent_type` | string | Agent type for this project |
| `work_dir` | string | Working directory path |
| `platforms` | array | Enabled platforms |
| `heartbeat_enabled` | boolean | Heartbeat monitoring status |
| `show_ctx_indicator` | boolean | Context usage indicator |
资料来源：[web/src/pages/Projects/ProjectList.tsx:1-50]()
### Heartbeat Configuration
Projects can enable heartbeat monitoring with the following settings:
| Parameter | Description |
|-----------|-------------|
| `interval_mins` | Monitoring interval in minutes |
| `paused` | Whether heartbeat is paused |
| `run_count` | Total heartbeat executions |
| `error_count` | Number of errors encountered |
资料来源：[web/src/pages/Projects/ProjectDetail.tsx:200-250]()
## Skill Presets
Skill presets define collections of skills organized by project type and agent capability.
### Skill Preset Structure
```typescript
interface SkillPreset {
project: string; // Project type identifier
agent_type: string; // Required agent type
dirs?: string[]; // Scan directories for skills
skills?: Skill[]; // Associated skills
}
```
| Field | Description |
|-------|-------------|
| `project` | Project category or type name |
| `agent_type` | Compatible agent type |
| `dirs` | Directories to scan for skill definitions |
| `skills` | Pre-configured skill list |
资料来源：[web/src/pages/Skills/SkillList.tsx:50-100]()
### Skill Structure
```typescript
interface Skill {
name: string; // Skill identifier
display_name?: string; // User-friendly name
description?: string; // Skill description
source: {
url?: string; // Source URL
name?: string; // Provider name
provider?: string; // Provider identifier
};
author?: string; // Skill author
url?: string; // Download URL
}
```
资料来源：[web/src/pages/Skills/SkillList.tsx:100-150]()
## CLI Configuration Commands
The command-line interface provides provider management commands:
| Command | Description |
|---------|-------------|
| `/provider list` | List all configured providers |
| `/provider switch ` | Switch active provider |
| `/provider clear` | Reset provider selection |
| `cc-connect provider add` | Add new provider via CLI |
资料来源：[core/i18n.go:1-100]()
### Provider Switching
When switching providers, the system validates provider existence and updates the active configuration:
```mermaid
sequenceDiagram
User->>CLI: /provider switch
CLI->>Config: Validate provider exists
Config-->>CLI: Provider found
CLI->>Config: Update active provider
Config-->>User: Provider switched to
```
资料来源：[core/i18n.go:100-150]()
## Configuration File Example
```toml
# Global Providers Section
[providers.openai]
base_url = "https://api.openai.com/v1"
model = "gpt-4"
models = ["gpt-4", "gpt-3.5-turbo"]
[providers.claude]
base_url = "https://api.anthropic.com"
model = "claude-3-sonnet-20240229"
thinking = "enabled"
# Project-specific Configuration
[project.my-project]
agent_type = "claude"
work_dir = "/path/to/project"
platforms = ["github"]
# Heartbeat Configuration
[heartbeat.my-project]
interval_mins = 5
```
## Platform-Specific Settings
Different platforms may require specific configuration:
| Platform | Required Settings |
|----------|------------------|
| `github` | Repository access, authentication token |
| `feishu` | App ID, App Secret, verification token |
| `telegram` | Bot token, webhook URL |
| `discord` | Bot token, guild ID |
| `slack` | Bot token, signing secret |
资料来源：[AGENTS.md:1-50]()
## Build Tags for Platform Support
Platform support is controlled via Go build tags:
```makefile
ALL_PLATFORMS = gemini iflow opencode qoder feishu telegram discord slack dingtalk wecom weixin qq qqbot line weibo
```
To exclude specific platforms:
```bash
go build -tags "no_gemini,no_iflow"
```
资料来源：[AGENTS.md:50-100]()
## Best Practices
1. **Provider Organization**: Use provider presets as templates and customize as needed
2. **Project Isolation**: Each project should have its own working directory
3. **Permission Mode**: Use `plan` mode for testing, `bypassPermissions` only when necessary
4. **Heartbeat**: Enable for long-running projects to monitor agent health
5. **i18n**: All user-facing strings should have translations for all supported languages
## Summary
The cc-connect configuration system provides a comprehensive framework for managing AI providers, projects, and skills. By understanding the hierarchical relationship between global settings, project configurations, and skill presets, administrators can effectively customize the system for various use cases and platform requirements.
---
## Session Management
### 相关页面
相关主题：[Configuration Guide](#page-configuration), [Core Components](#page-core-components)
相关源码文件
以下源码文件用于生成本页说明：
- [core/session.go](https://github.com/chenhg5/cc-connect/blob/main/core/session.go)
- [core/projectstate.go](https://github.com/chenhg5/cc-connect/blob/main/core/projectstate.go)
- [core/dir_history.go](https://github.com/chenhg5/cc-connect/blob/main/core/dir_history.go)
- [core/cron.go](https://github.com/chenhg5/cc-connect/blob/main/core/cron.go)
- [core/command.go](https://github.com/chenhg5/cc-connect/blob/main/core/command.go)
- [cmd/cc-connect/sessions.go](https://github.com/chenhg5/cc-connect/blob/main/cmd/cc-connect/sessions.go)
# Session Management
## Overview
Session Management is the core system responsible for maintaining conversational state between users and AI agents in cc-connect. Each session represents a single conversation context, preserving message history, working directory state, and agent configuration across interactions. The system enables users to switch between multiple concurrent conversations while maintaining isolation of context and state per session.
Sessions serve as the fundamental unit of work in cc-connect, allowing agents to maintain context across multiple requests, store conversation history, and provide seamless user experience through features like session switching, history retrieval, and live session indicators.
## Architecture Overview
```mermaid
graph TD
User[User] -->|Chat/CLI| WebUI[Web UI / CLI]
WebUI -->|Bridge| Bridge[Session Bridge]
Bridge -->|Manage| SessionMgr[Session Manager]
SessionMgr -->|Persist| Store[Session Store]
SessionMgr -->|Agent Comm| Agent[Agent Session]
Agent -->|Execute| CodeAgent[Claude Code / Codex / etc]
SessionMgr -->|State| ProjectState[Project State]
SessionMgr -->|History| DirHistory[Directory History]
SessionMgr -->|Schedule| Cron[Cron Jobs]
subgraph Per-Session
S1[Session 1]
S2[Session 2]
SN[Session N]
end
SessionMgr -.->|Created| S1
SessionMgr -.->|Created| S2
SessionMgr -.->|Created| SN
```
## Session Data Model
### Core Session Structure
```go
type Session struct {
ID string // Unique session identifier
ProjectName string // Associated project
Name string // Display name
UserName string // Creator identifier
ActiveSessionKeys []string // Active session references
Live bool // Currently active/in-use
CreatedAt time.Time // Creation timestamp
UpdatedAt time.Time // Last modification
LastMessage *HistoryEntry // Most recent message
Messages []HistoryEntry // Full message history
}
```
| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Unique session identifier (UUID) |
| `project_name` | string | Name of associated project |
| `name` | string | Human-readable session name |
| `user_name` | string | Creator's identifier |
| `live` | bool | Whether session is currently active |
| `created_at` | timestamp | Session creation time |
| `updated_at` | timestamp | Last activity time |
| `last_message` | HistoryEntry | Most recent message object |
| `messages_count` | int | Total message count |
### History Entry Structure
Each message in a session is stored as a `HistoryEntry`:
| Field | Type | Description |
|-------|------|-------------|
| `role` | string | "user" or "assistant" |
| `content` | string | Message content |
| `timestamp` | time.Time | Message timestamp |
| `thinking` | string | Optional reasoning content (Codex) |
## Session Lifecycle
### Lifecycle States
```mermaid
stateDiagram-v2
[*] --> Created: /new-session
Created --> Active: First Message
Active --> Active: Send Message
Active --> Paused: /history or Switch
Paused --> Active: Resume Session
Active --> Closed: /close or Timeout
Closed --> [*]: Cleanup
Created --> Deleted: /delete
Active --> Deleted: /delete
Paused --> Deleted: /delete
Deleted --> [*]
```
### Session Creation
Sessions are created in multiple scenarios:
1. **Explicit Creation**: Via `/new-session` command or CLI `cc-connect sessions new`
2. **Automatic on First Project Use**: When a project has no existing sessions
3. **Cron Job Sessions**: Fresh sessions created per cron run (when `session-mode: new-per-run`)
### Session Persistence
Sessions are persisted to storage with the following behavior:
- **Active Session Tracking**: `ActiveSessionKeys` array tracks currently active sessions per project
- **Last Message Cache**: The `LastMessage` field is updated after each exchange for quick retrieval
- **History Truncation**: When `limit > 0`, only the most recent N entries are retained (configurable per request)
## Project State Management
Sessions are scoped to projects. The `ProjectState` interface manages this relationship:
```go
type ProjectState interface {
GetActiveSessionKey(project string) string
SetActiveSessionKey(project, sessionKey string)
AddSession(project string, session Session) error
ListSessions(project string) ([]Session, error)
GetSession(project, sessionKey string) (*Session, error)
}
```
### Project-Session Relationship
| Project Setting | Session Behavior |
|----------------|------------------|
| `sessions_count` | Number of sessions for project |
| `active_session_keys` | Currently active session references |
| Per-project agent | Each session uses project's configured agent |
## Session History
### History Entry Format
Sessions store a chronological list of `HistoryEntry` objects:
```go
type HistoryEntry struct {
Role string `json:"role"`
Content string `json:"content"`
Timestamp time.Time `json:"timestamp"`
Thinking string `json:"thinking,omitempty"` // Codex reasoning
}
```
### History Retrieval Commands
| Command | Description | Source |
|---------|-------------|--------|
| `/history [n]` | Show last n messages (default 10) | `core/command.go` |
| `/reasoning [level]` | View/switch reasoning effort | `core/command.go` |
| SessionDrawer | UI component for browsing history | `SessionList.tsx` |
### History Display
In the web UI, session history is displayed with:
- **Role Indicators**: User messages show `User` icon, assistant messages show `Bot` icon
- **Timestamp**: Relative time display using `timeAgo()` function
- **Message Preview**: Last 100 characters of content, newlines replaced with spaces
- **Line Clamping**: Messages limited to 2 lines in list view
## Session Switching
### Switch Session Methods
```mermaid
graph LR
A[User] -->|/session| B[Switch Command]
A -->|UI Click| C[SessionDrawer]
B -->|Validate| D{Valid Session?}
D -->|Yes| E[Set Active Session]
D -->|No| F[Error: Not Found]
E --> G[Update ProjectState]
G --> H[Load Session Context]
C -->|Select| I[switchToSession]
I --> G
```
### Active Session Management
The system maintains a single active session per project:
```go
// ProjectState maintains active session key
func (ps *projectState) GetActiveSessionKey(project string) string
func (ps *projectState) SetActiveSessionKey(project, sessionKey string)
```
### Session Drawer Component
The `SessionDrawer` component in `web/src/pages/Sessions/SessionList.tsx` provides:
| Feature | Description |
|---------|-------------|
| Session List | All sessions for current project |
| Live Indicator | Green dot for currently active session |
| Quick Switch | Click to switch active session |
| New Session | Button to create fresh session |
| Message Preview | Shows last message in each session |
## Directory History Integration
Sessions track working directory changes via `DirHistory`:
```go
type DirHistory struct {
SessionID string // Associated session
Paths []string // Ordered list of visited directories
Index int // Current position in history
}
```
### Directory Commands
| Command | Description |
|---------|-------------|
| `/dir ` | Change to specified directory |
| `/dir reset` | Return to project's default directory |
| `/history` | Show directory visit history |
This allows agents to maintain working context across sessions when the same session is resumed.
## Scheduled Tasks (Cron) Integration
Sessions interact with the cron system through the `--session-mode` flag:
### Session Modes
| Mode | Behavior | Use Case |
|------|----------|----------|
| `reuse` (default) | Reuse same session across runs | Ongoing conversations |
| `new-per-run` | Fresh agent session each run | Isolated task execution |
```bash
# Example: Daily task with reused session
cc-connect cron add --cron "0 6 * * *" --prompt "Summarize emails" --desc "Morning Summary"
# Example: Task requiring fresh context each run
cc-connect cron add --cron "*/30 * * * *" --exec "df -h" --session-mode new-per-run
```
### Cron Session Configuration
| Parameter | Description |
|-----------|-------------|
| `--timeout-mins ` | Max minutes per run (0 = no limit, default 30) |
| `--session-mode` | `reuse` or `new-per-run` |
## CLI Session Commands
### Available Commands
```bash
# List sessions for current project
cc-connect sessions list
# Create new session
cc-connect sessions new
# Switch to session
cc-connect sessions switch
# Show session history
cc-connect sessions history [limit]
# Delete session
cc-connect sessions delete
```
### Session Options (from `cmd/cc-connect/sessions.go`)
| Option | Description |
|--------|-------------|
| `-p, --project ` | Target project (auto-detected from CC_PROJECT) |
| `-s, --session-key ` | Target session (auto-detected from CC_SESSION_KEY) |
## Bridge Communication
The web UI communicates with sessions via a bridge protocol:
```mermaid
sequenceDiagram
participant UI as ChatView
participant Bridge as Session Bridge
participant Session as Session Manager
UI->>Bridge: connect(project, sessionId)
Bridge->>Session: Register connection
Session-->>Bridge: session state
Bridge-->>UI: bridge status: connected
UI->>Bridge: send(message)
Bridge->>Session: Process message
Session->>Session: Update history
Session-->>Bridge: response
Bridge-->>UI: stream events
Note over Bridge: status: "connected" | "connecting" | "error" | "disconnected"
```
### Bridge Status States
| Status | Description | UI Display |
|--------|-------------|------------|
| `connected` | Active connection | Hidden |
| `connecting` | Establishing connection | Spinner + "Connecting..." |
| `error` | Connection failed | Warning icon + "Disconnected" |
| `disconnected` | No active bridge | Warning icon + "Disconnected" |
## Session Storage
### Storage Location
- **Default Directory**: `~/.cc-connect`
- **Session Data**: Stored in project-specific storage
- **Session Key Environment Variable**: `CC_SESSION_KEY`
### Storage Schema
```
~/.cc-connect/
├── projects/
│ └── /
│ └── sessions/
│ └── /
│ ├── meta.json # Session metadata
│ ├── messages.jsonl # Message history
│ └── context/ # Agent context files
```
## Agent-Specific Session Handling
### Codex Agent
The Codex agent includes special session handling (`agent/codex/session.go`):
```go
func patchSessionSource(sessionID, codexHome string) {
// Rewrites session_meta line in Codex JSONL transcript
// Sets source="cli" and originator="codex_cli_rs"
// Makes session visible in interactive codex terminal
}
```
### Session Context Loading
Codex sessions retry context loading with:
| Parameter | Value | Purpose |
|-----------|-------|---------|
| `codexContextUsageRetryCount` | 5 | Maximum retry attempts |
| `codexContextUsageRetryDelay` | 1 second | Delay between retries |
| `codexSessionCloseTimeout` | 5 seconds | Grace period for cleanup |
## Best Practices
1. **Session Naming**: Use descriptive names for easy identification
2. **History Cleanup**: Periodically delete old sessions to maintain performance
3. **Project Isolation**: Keep sessions scoped to their project for proper context
4. **Timeout Configuration**: Set appropriate `--timeout-mins` for long-running tasks
5. **Session Mode Selection**: Use `new-per-run` for isolated tasks, `reuse` for conversational agents
## Related Commands Reference
| Slash Command | Description |
|---------------|-------------|
| `/new-session` | Create a new session |
| `/sessions` | List/manage sessions |
| `/history [n]` | View message history |
| `/session ` | Switch to specific session |
| `/dir ` | Change working directory (session-scoped) |
---
## Web UI Administration
### 相关页面
相关主题：[Configuration Guide](#page-configuration), [Deployment and Operations](#page-deployment)
相关源码文件
以下源码文件用于生成本页说明：
- [web/src/App.tsx](https://github.com/chenhg5/cc-connect/blob/main/web/src/App.tsx)
- [web/src/pages/Dashboard.tsx](https://github.com/chenhg5/cc-connect/blob/main/web/src/pages/Dashboard.tsx)
- [web/src/api/index.ts](https://github.com/chenhg5/cc-connect/blob/main/web/src/api/index.ts)
- [cmd/cc-connect/web.go](https://github.com/chenhg5/cc-connect/blob/main/cmd/cc-connect/web.go)
- [core/web_manager.go](https://github.com/chenhg5/cc-connect/blob/main/core/web_manager.go)
# Web UI Administration
The Web UI Administration module in cc-connect provides a comprehensive, single-page administrative interface for managing the entire platform. Built with React and TypeScript, the web interface serves as the primary control center for administrators to configure projects, manage agent providers, monitor sessions, and administer scheduled cron jobs—all without requiring command-line interaction.
## Architecture Overview
The web administration system follows a client-server architecture where the React frontend communicates with the Go backend through a RESTful API. The backend serves both static assets and dynamic API endpoints, while the frontend manages routing, state, and user interactions.
```mermaid
graph TD
A[Browser Client] --> B[React SPA Frontend]
B --> C[API Client Layer]
C --> D[Go Backend API]
D --> E[(SQLite Database)]
D --> F[Platform Connectors
Feishu/WeChat]
D --> G[Agent Providers
Claude/Codex/Gemini]
B --> H[Dashboard]
B --> I[Projects]
B --> J[Sessions]
B --> K[Providers]
B --> L[Skills]
B --> M[Cron Jobs]
```
## Frontend Application Structure
### App Entry Point and Routing
The main application entry point (`web/src/App.tsx`) initializes the React application with routing capabilities. The application uses client-side routing to navigate between different administrative sections.
**资料来源：** [web/src/App.tsx:1-50]()
### Page Modules
The web interface is organized into several distinct page modules, each handling a specific domain of administrative functionality:
| Module | File Path | Purpose |
|--------|-----------|---------|
| Dashboard | `web/src/pages/Dashboard.tsx` | System overview, status metrics, quick links |
| Projects | `web/src/pages/Projects/ProjectList.tsx` | Project creation and management |
| Project Detail | `web/src/pages/Projects/ProjectDetail.tsx` | Per-project settings and configuration |
| Sessions | `web/src/pages/Sessions/SessionList.tsx` | Chat session history and management |
| Providers | `web/src/pages/Providers/ProviderList.tsx` | Agent provider configuration |
| Skills | `web/src/pages/Skills/SkillList.tsx` | Skill preset management |
| Cron Jobs | `web/src/pages/Cron/CronList.tsx` | Scheduled task administration |
**资料来源：** [web/src/pages/Dashboard.tsx:1-30]()
## Core Features
### Dashboard
The Dashboard provides an at-a-glance view of the system status. It displays key metrics including version information, uptime statistics, connected platform count, and total project count.
```typescript
// Key dashboard metrics displayed
{p.agent_type}
{p.platforms?.slice(0, 3).map((pl) => {pl} )}
{p.sessions_count} {t('nav.sessions').toLowerCase()}
{p.heartbeat_enabled && (
{job.mode || t('cron.modeDefault')}
{t('cron.project')}
{job.project}
{t('cron.lastRun')}
{formatTime(job.last_run)}
```
**资料来源：** [web/src/pages/Cron/CronList.tsx:1-50]()
## API Client Layer
The frontend communicates with the backend through an API client module (`web/src/api/index.ts`). This layer abstracts HTTP communication and provides typed interfaces for all administrative operations.
### Key API Operations
| Category | Operations |
|----------|------------|
| Projects | list, create, update, delete, get |
| Sessions | list, get, delete, clear history |
| Providers | list, create, update, delete |
| Skills | list presets, add to project |
| Cron | list, create, update, delete, trigger |
| System | status, restart, shutdown |
**资料来源：** [web/src/api/index.ts:1-100]()
## Backend Server
### Web Server Initialization
The Go backend initializes the web server with static file serving and API routing.
**资料来源：** [cmd/cc-connect/web.go:1-50]()
### Web Manager
The core web manager handles the lifecycle of the web interface, including configuration, middleware setup, and request routing.
```go
// Web server configuration structure
type WebConfig struct {
Host string
Port int
TLS bool
CertFile string
KeyFile string
}
```
**资料来源：** [core/web_manager.go:1-80]()
## Internationalization
The web interface supports multiple languages through an internationalization system defined in `core/i18n.go`. Supported languages include:
- English
- Simplified Chinese (简体中文)
- Traditional Chinese (繁體中文)
- Japanese (日本語)
- Spanish (Español)
The UI automatically detects the browser language and falls back to English when translations are unavailable.
## User Interface Components
### Common UI Elements
The interface uses a consistent component library including:
- **Card** - Container for grouped content
- **Badge** - Status indicators and labels
- **Button** - Action triggers with variants (primary, secondary, ghost)
- **Modal** - Dialog overlays for forms and confirmations
- **Input** - Form field components with validation
- **Badge variants** - default, outline, info, success for semantic coloring
### Dark Mode Support
All components support dark mode theming through CSS custom properties and Tailwind dark variants:
```typescript
// Example dark mode styling pattern
className="text-gray-900 dark:text-white bg-white dark:bg-white/[0.02]"
className="border-gray-200 dark:border-white/[0.06]"
```
## Configuration and State Management
The frontend uses React hooks for state management with several key patterns:
1. **Server State** - Data fetched from the API (projects, sessions, providers)
2. **UI State** - Local component state (modals, forms, selections)
3. **Preferences** - User settings like language and theme
### Key State Hooks
| Hook | Purpose |
|------|---------|
| `useProjects` | Fetch and cache project list |
| `useProviders` | Manage provider configurations |
| `useSessions` | Session listing and filtering |
| `useStatus` | System status polling |
## Security Considerations
The web interface handles sensitive operations including:
- API key management for provider configurations
- Project authentication credentials
- Session data access
All sensitive fields use password input types with visibility toggles:
```typescript
```
**资料来源：** [web/src/pages/Providers/ProviderList.tsx:150-180]()
## Data Flow Diagram
```mermaid
sequenceDiagram
participant User
participant ReactApp
participant API
participant GoBackend
participant Database
User->>ReactApp: Navigate to Projects
ReactApp->>API: GET /api/projects
API->>GoBackend: HTTP Request
GoBackend->>Database: Query projects
Database->>GoBackend: Project records
GoBackend->>API: JSON response
API->>ReactApp: Project list data
ReactApp->>User: Render ProjectList
```
## Conclusion
The Web UI Administration module provides a complete, production-ready administrative interface for cc-connect. Its modular design separates concerns across page components, while the typed API client ensures reliable communication with the backend. The support for dark mode, internationalization, and responsive design makes it suitable for deployment in varied operational environments.
---
## Deployment and Operations
### 相关页面
相关主题：[Quick Start Guide](#page-quickstart)
相关源码文件
以下源码文件用于生成本页说明：
- [cmd/cc-connect/update.go](https://github.com/chenhg5/cc-connect/blob/main/cmd/cc-connect/update.go)
- [cmd/cc-connect/daemon.go](https://github.com/chenhg5/cc-connect/blob/main/cmd/cc-connect/daemon.go)
- [daemon/manager.go](https://github.com/chenhg5/cc-connect/blob/main/daemon/manager.go)
- [daemon/systemd.go](https://github.com/chenhg5/cc-connect/blob/main/daemon/systemd.go)
- [core/runas.go](https://github.com/chenhg5/cc-connect/blob/main/core/runas.go)
- [core/updater.go](https://github.com/chenhg5/cc-connect/blob/main/core/updater.go)
# Deployment and Operations
This page covers the operational aspects of cc-connect, including installation, daemon management, service configuration, and system-level integration.
## Overview
cc-connect is a bridge application that connects local AI coding agents to messaging platforms. It supports multiple deployment scenarios ranging from manual binary execution to automated system service management across Linux (systemd), macOS (launchd), and Windows (Task Scheduler).
资料来源：[INSTALL.md](https://github.com/chenhg5/cc-connect/blob/main/INSTALL.md)
## Installation Methods
cc-connect offers four primary installation approaches depending on your environment and requirements.
### Package Manager Installation
**macOS (Homebrew):**
```bash
brew install cc-connect
```
**Linux (Homebrew):**
```bash
brew install cc-connect
```
资料来源：[INSTALL.md](https://github.com/chenhg5/cc-connect/blob/main/INSTALL.md)
### Pre-built Binary Download
Download platform-specific binaries from the [GitHub Releases](https://github.com/chenhg5/cc-connect/releases) page.
| Platform | Architecture | Artifact Pattern |
|----------|-------------|------------------|
| Linux | amd64 | `cc-connect--linux-amd64` |
| macOS | amd64 | `cc-connect--darwin-amd64` |
| macOS | ARM64 | `cc-connect--darwin-arm64` |
| Windows | amd64 | `cc-connect--windows-amd64.exe` |
**Installation Example (Linux):**
```bash
curl -L -o cc-connect https://github.com/chenhg5/cc-connect/releases/latest/download/cc-connect-linux-amd64
chmod +x cc-connect
sudo mv cc-connect /usr/local/bin/
```
**macOS Quarantine Removal:**
```bash
xattr -d com.apple.quarantine cc-connect
```
资料来源：[INSTALL.md](https://github.com/chenhg5/cc-connect/blob/main/INSTALL.md)
### Build from Source
Building from source requires Go 1.22 or later.
```bash
git clone https://github.com/chenhg5/cc-connect.git
cd cc-connect
make build
# Binary output: ./cc-connect
```
资料来源：[INSTALL.md](https://github.com/chenhg5/cc-connect/blob/main/INSTALL.md)
## Configuration File Management
cc-connect searches for configuration files in the following order:
1. `-config ` flag (explicit path)
2. `./config.toml` (current directory)
3. `~/.cc-connect/config.toml` (global, recommended)
If no configuration file exists, running `cc-connect` will automatically create a starter template at `~/.cc-connect/config.toml`.
### Manual Configuration Setup
```bash
mkdir -p ~/.cc-connect
# Option 1: Copy example from cloned repo
cp config.example.toml ~/.cc-connect/config.toml
# Option 2: Run cc-connect once to auto-generate
cc-connect
```
资料来源：[INSTALL.md](https://github.com/chenhg5/cc-connect/blob/main/INSTALL.md)
## Daemon Management
The daemon subsystem provides persistent background operation with automatic startup on system boot.
### Installing the Daemon
**Basic Installation:**
```bash
cc-connect daemon install --config ~/.cc-connect/config.toml
```
**Using Work Directory:**
```bash
cc-connect daemon install --work-dir ~/.cc-connect
```
**Installation Options:**
| Flag | Description | Default |
|------|-------------|---------|
| `--config PATH` | Path to config file | `~/.cc-connect/config.toml` |
| `--log-file PATH` | Custom log file location | Auto-generated |
| `--log-max-size N` | Max log size in MB | Configured value |
| `--work-dir DIR` | Directory containing config.toml | `~/.cc-connect` |
| `--force` | Overwrite existing unit | false |
资料来源：[cmd/cc-connect/daemon.go](https://github.com/chenhg5/cc-connect/blob/main/cmd/cc-connect/daemon.go)
### Daemon Lifecycle Commands
```bash
cc-connect daemon start # Start the service
cc-connect daemon stop # Stop the service
cc-connect daemon restart # Restart the service
cc-connect daemon status # Check current status
```
### Platform-Specific Implementation
The daemon manager delegates to platform-specific implementations:
- **Linux:** Creates a systemd user service 资料来源：[daemon/systemd.go](https://github.com/chenhg5/cc-connect/blob/main/daemon/systemd.go)
- **macOS:** Creates a LaunchAgent plist
- **Windows:** Creates a Task Scheduler task named `cc-connect`
```mermaid
graph TD
A[cc-connect daemon install] --> B{Platform Detection}
B -->|Linux| C[systemd User Service]
B -->|macOS| D[LaunchAgent Plist]
B -->|Windows| E[Task Scheduler Task]
C --> F[Auto-start on login]
D --> F
E --> G[Run at user logon]
```
资料来源：[daemon/manager.go](https://github.com/chenhg5/cc-connect/blob/main/daemon/manager.go)
## Log Management
### Viewing Logs
```bash
cc-connect daemon logs # Display current log
cc-connect daemon logs -f # Follow mode (tail -f equivalent)
cc-connect daemon logs -n 100 # Show last 100 lines
cc-connect daemon logs --log-file /path/to/log # Custom log file
```
### Log Rotation
Logs automatically rotate when they reach the configured maximum size. The system maintains one backup of the previous log file.
资料来源：[INSTALL.md](https://github.com/chenhg5/cc-connect/blob/main/INSTALL.md)
## Update Management
### Update Command
The update subsystem handles binary updates with signature verification.
```bash
cc-connect update [options]
```
**Update Options:**
| Flag | Description |
|------|-------------|
| `--channel ` | Update channel (stable/beta) |
| `--file ` | Install from local file |
| `--data-dir ` | Data directory for update metadata |
### Update Process Flow
```mermaid
graph TD
A[cc-connect update] --> B[Check Update Channel]
B --> C{Fetch Latest Version}
C -->|Version Available| D[Download Binary]
C -->|Up to Date| E[Exit: Already current]
D --> F{Verify Signature}
F -->|Valid| G[Replace Binary]
F -->|Invalid| H[Abort Update]
G --> I[Restart Service]
```
资料来源：[cmd/cc-connect/update.go](https://github.com/chenhg5/cc-connect/blob/main/cmd/cc-connect/update.go)
### Manual Update for Package Managers
**Homebrew:**
```bash
brew upgrade cc-connect
```
**Source Users:**
```bash
cd cc-connect
git pull
make build
```
After upgrading, restart the running cc-connect process to apply changes.
资料来源：[INSTALL.md](https://github.com/chenhg5/cc-connect/blob/main/INSTALL.md)
## Process Execution Model
### Privilege Escalation
The `runas` module handles process execution with appropriate privileges:
```mermaid
graph LR
A[Main Process] -->|Non-elevated| B[User Context]
A -->|Elevated tasks| C[runas Module]
C -->|sudo/elevation| D[Privileged Execution]
```
The module supports:
- Running commands with elevated privileges when required
- Managing user context for different operation modes
资料来源：[core/runas.go](https://github.com/chenhg5/cc-connect/blob/main/core/runas.go)
## Operational Best Practices
### Recommended Setup
1. **Use Global Config Location:** Store configuration at `~/.cc-connect/config.toml` for consistent access across terminal sessions.
2. **Install as System Service:** Use `daemon install` for production deployments to ensure automatic restart on system reboot.
3. **Configure Log Rotation:** Set appropriate `--log-max-size` value based on expected message volume.
4. **Monitor Log Output:** Regularly check `cc-connect daemon logs` for operational insights and error tracking.
### Configuration Structure
A typical multi-project production configuration:
```toml
[log]
level = "info"
[[projects]]
name = "backend"
[projects.agent]
type = "claudecode"
[projects.agent.options]
work_dir = "/path/to/backend"
mode = "default"
[[projects.platforms]]
type = "feishu"
[projects.platforms.options]
app_id = "cli_xxx"
app_secret = "xxx"
```
### Health Monitoring
The daemon status command provides current service state:
```bash
cc-connect daemon status
```
This reports whether the service is running, and if applicable, the uptime and last activity timestamp.
## Windows-Specific Considerations
On Windows, `daemon install` creates a Task Scheduler task that:
- Runs at user logon
- Starts immediately after installation
- Is named `cc-connect` in the Task Scheduler
资料来源：[INSTALL.md](https://github.com/chenhg5/cc-connect/blob/main/INSTALL.md)
---
---
## Doramagic 踩坑日志
项目：chenhg5/cc-connect
摘要：发现 39 个潜在踩坑项，其中 12 个为 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. 安装坑 · 来源证据：[Bug] cc-connect web服务商管理从 CC-Switch 导入服务商重名问题
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug] cc-connect web服务商管理从 CC-Switch 导入服务商重名问题
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_bbbf45839e1043e2afdedf3f1d87b55b | https://github.com/chenhg5/cc-connect/issues/1058 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。
## 3. 安装坑 · 来源证据：[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 暴露的待验证使用条件。
## 4. 安装坑 · 来源证据：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 相关条件，需在安装/试用前复核。
## 5. 配置坑 · 来源证据：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 相关条件，需在安装/试用前复核。
## 6. 配置坑 · 来源证据：WeChat ilink (weixin): image content is empty, not passed to agent
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：WeChat ilink (weixin): image content is empty, not passed to agent
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_17d4c5f39a5745c5bdfbc88cdac32056 | https://github.com/chenhg5/cc-connect/issues/1057 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。
## 7. 配置坑 · 来源证据：[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 暴露的待验证使用条件。
## 8. 安全/权限坑 · 失败模式：security_permissions: [Bug] cc-connect send uses default socket path in custom data_dir agent sessions
- 严重度：high
- 证据强度：source_linked
- 发现：Developers should check this security_permissions risk before relying on the project: [Bug] cc-connect send uses default socket path in custom data_dir agent sessions
- 对用户的影响：Developers may expose sensitive permissions or credentials: [Bug] cc-connect send uses default socket path in custom data_dir agent sessions
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Bug] cc-connect send uses default socket path in custom data_dir agent sessions. Context: Observed during installation or first-run setup.
- 防护动作：Do not recommend enabling privileged or credential-bearing paths until the source-backed risk is reviewed: https://github.com/chenhg5/cc-connect/issues/966
- 证据：failure_mode_cluster:github_issue | fmev_d8aeb38642d53571d47292761cca7247 | https://github.com/chenhg5/cc-connect/issues/966 | [Bug] cc-connect send uses default socket path in custom data_dir agent sessions, failure_mode_cluster:github_issue | fmev_105e57f4097e09e9e5c522a568ff4991 | https://github.com/chenhg5/cc-connect/issues/966 | [Bug] cc-connect send uses default socket path in custom data_dir agent sessions
## 9. 安全/权限坑 · 失败模式：security_permissions: [Bug] cc-connect 启动 Claude Code 时使用了 --dangerously-skip-permissions，但 最新版Claude Code 不允许 root...
- 严重度：high
- 证据强度：source_linked
- 发现：Developers should check this security_permissions risk before relying on the project: [Bug] cc-connect 启动 Claude Code 时使用了 --dangerously-skip-permissions，但 最新版Claude Code 不允许 root 用户使用这个标志
- 对用户的影响：Developers may expose sensitive permissions or credentials: [Bug] cc-connect 启动 Claude Code 时使用了 --dangerously-skip-permissions，但 最新版Claude Code 不允许 root 用户使用这个标志
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Bug] cc-connect 启动 Claude Code 时使用了 --dangerously-skip-permissions，但 最新版Claude Code 不允许 root 用户使用这个标志. Context: Observed when using linux
- 防护动作：Do not recommend enabling privileged or credential-bearing paths until the source-backed risk is reviewed: https://github.com/chenhg5/cc-connect/issues/1054
- 证据：failure_mode_cluster:github_issue | fmev_9f56ecf6ad99707575ffe84fc2c10e1b | https://github.com/chenhg5/cc-connect/issues/1054 | [Bug] cc-connect 启动 Claude Code 时使用了 --dangerously-skip-permissions，但 最新版Claude Code 不允许 root 用户使用这个标志
## 10. 安全/权限坑 · 来源证据：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 相关条件，需在安装/试用前复核。
## 11. 安全/权限坑 · 来源证据：[Bug] cc-connect 启动 Claude Code 时使用了 --dangerously-skip-permissions，但 最新版Claude Code 不允许 root 用户使用这个标志
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug] cc-connect 启动 Claude Code 时使用了 --dangerously-skip-permissions，但 最新版Claude Code 不允许 root 用户使用这个标志
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_c632e470b2d04852abae801be4d2aba2 | https://github.com/chenhg5/cc-connect/issues/1054 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。
## 12. 安全/权限坑 · 来源证据：[Bug] codex mode修改YOLO模式无效
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug] codex mode修改YOLO模式无效
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_ce58ad66fc4e4d2ea6f0bb4a43527cd0 | https://github.com/chenhg5/cc-connect/issues/233 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。
## 13. 安装坑 · 失败模式：installation: [Bug]
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: [Bug]
- 对用户的影响：Developers may fail before the first successful local run: [Bug]
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Bug]. Context: Observed when using node, windows
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_555d98ac56e7850b1c49e5892d2b6c48 | https://github.com/chenhg5/cc-connect/issues/933 | [Bug]
## 14. 安装坑 · 失败模式：installation: [Bug] codex mode修改YOLO模式无效
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: [Bug] codex mode修改YOLO模式无效
- 对用户的影响：Developers may fail before the first successful local run: [Bug] codex mode修改YOLO模式无效
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Bug] codex mode修改YOLO模式无效. Context: Observed when using macos
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_59a6433bec9f3dcf0981efd11a046df3 | https://github.com/chenhg5/cc-connect/issues/233 | [Bug] codex mode修改YOLO模式无效
## 15. 安装坑 · 失败模式：installation: [Bug] cursorSession error: unknown option '--trust
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: [Bug] cursorSession error: unknown option '--trust
- 对用户的影响：Developers may fail before the first successful local run: [Bug] cursorSession error: unknown option '--trust
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Bug] cursorSession error: unknown option '--trust. Context: Observed when using node, macos
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_279592e262a8c9114ffed9bcd68ca683 | https://github.com/chenhg5/cc-connect/issues/923 | [Bug] cursorSession error: unknown option '--trust
## 16. 安装坑 · 失败模式：installation: cc-connect 因 SSH 断开被 systemd 停止：需要文档化 `loginctl enable-linger`
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: cc-connect 因 SSH 断开被 systemd 停止：需要文档化 `loginctl enable-linger`
- 对用户的影响：Developers may fail before the first successful local run: cc-connect 因 SSH 断开被 systemd 停止：需要文档化 `loginctl enable-linger`
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: cc-connect 因 SSH 断开被 systemd 停止：需要文档化 `loginctl enable-linger`. Context: Observed when using node, linux
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_2ab77150cf90931385fb7741956a1f53 | https://github.com/chenhg5/cc-connect/issues/960 | cc-connect 因 SSH 断开被 systemd 停止：需要文档化 `loginctl enable-linger`, failure_mode_cluster:github_issue | fmev_5c45b25a78af1b25aea75c4cad91e50a | https://github.com/chenhg5/cc-connect/issues/960 | cc-connect 因 SSH 断开被 systemd 停止：需要文档化 `loginctl enable-linger`
## 17. 安装坑 · 失败模式：installation: v1.3.0
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v1.3.0
- 对用户的影响：Upgrade or migration may change expected behavior: v1.3.0
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.3.0. Context: Observed when using node, windows
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_a2ead0f4920aaffbc2c58e566c82e8e8 | https://github.com/chenhg5/cc-connect/releases/tag/v1.3.0 | v1.3.0
## 18. 安装坑 · 失败模式：installation: v1.3.3-beta.1
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v1.3.3-beta.1
- 对用户的影响：Upgrade or migration may change expected behavior: v1.3.3-beta.1
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.3.3-beta.1. Context: Observed when using node
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_2967bcebc65cc66231ca2bcd62e03f6f | https://github.com/chenhg5/cc-connect/releases/tag/v1.3.3-beta.1 | v1.3.3-beta.1
## 19. 安装坑 · 失败模式：installation: 生图 app-icon 请求未稳定转发到 generate-image，且 cc-connect 存在部署漂移风险
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: 生图 app-icon 请求未稳定转发到 generate-image，且 cc-connect 存在部署漂移风险
- 对用户的影响：Developers may fail before the first successful local run: 生图 app-icon 请求未稳定转发到 generate-image，且 cc-connect 存在部署漂移风险
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: 生图 app-icon 请求未稳定转发到 generate-image，且 cc-connect 存在部署漂移风险. Context: Observed during installation or first-run setup.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_f2c109d868a32136d97c513f8ac192bb | https://github.com/chenhg5/cc-connect/issues/967 | 生图 app-icon 请求未稳定转发到 generate-image，且 cc-connect 存在部署漂移风险
## 20. 安装坑 · 来源证据：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 相关条件，需在安装/试用前复核。
## 21. 安装坑 · 来源证据：生图 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 相关条件，需在安装/试用前复核。
## 22. 配置坑 · 可能修改宿主 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
## 23. 配置坑 · 失败模式：configuration: Feature Request: 终端与 IM 双通道统一会话管理
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: Feature Request: 终端与 IM 双通道统一会话管理
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Feature Request: 终端与 IM 双通道统一会话管理
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Feature Request: 终端与 IM 双通道统一会话管理. Context: Observed when using windows
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_eb8a9f26e9a7250936e6075aa04d1f9f | https://github.com/chenhg5/cc-connect/issues/968 | Feature Request: 终端与 IM 双通道统一会话管理
## 24. 配置坑 · 失败模式：configuration: Feishu: all messages permanently ignored as 'old message after restart' after every daemon re...
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: Feishu: all messages permanently ignored as 'old message after restart' after every daemon restart (v1.3.3-beta.2)
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Feishu: all messages permanently ignored as 'old message after restart' after every daemon restart (v1.3.3-beta.2)
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Feishu: all messages permanently ignored as 'old message after restart' after every daemon restart (v1.3.3-beta.2). Context: Observed when using linux
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_d77b163febfec4d4e69e2e4e32f620a1 | https://github.com/chenhg5/cc-connect/issues/972 | Feishu: all messages permanently ignored as 'old message after restart' after every daemon restart (v1.3.3-beta.2)
## 25. 配置坑 · 失败模式：configuration: [Feature] Preserve full interactive card schema on inbound
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: [Feature] Preserve full interactive card schema on inbound
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [Feature] Preserve full interactive card schema on inbound
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Feature] Preserve full interactive card schema on inbound. Context: Observed when using python
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_bc874b9a16a67215d86b2e2342c2ce30 | https://github.com/chenhg5/cc-connect/issues/936 | [Feature] Preserve full interactive card schema on inbound
## 26. 配置坑 · 失败模式：configuration: v1.3.0-rc.5
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v1.3.0-rc.5
- 对用户的影响：Upgrade or migration may change expected behavior: v1.3.0-rc.5
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.3.0-rc.5. Context: Source discussion did not expose a precise runtime context.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_742c16dbbbfed9286198088ba0f05c07 | https://github.com/chenhg5/cc-connect/releases/tag/v1.3.0-rc.5 | v1.3.0-rc.5
## 27. 配置坑 · 失败模式：configuration: v1.3.1
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v1.3.1
- 对用户的影响：Upgrade or migration may change expected behavior: v1.3.1
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.3.1. Context: Observed during version upgrade or migration.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_af9571ceb2092a140a16c2cfbe490ca1 | https://github.com/chenhg5/cc-connect/releases/tag/v1.3.1 | v1.3.1
## 28. 配置坑 · 失败模式：configuration: v1.3.2
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v1.3.2
- 对用户的影响：Upgrade or migration may change expected behavior: v1.3.2
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.3.2. Context: Source discussion did not expose a precise runtime context.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_a2bd7f299418ec4b6c3fe49f42c6e933 | https://github.com/chenhg5/cc-connect/releases/tag/v1.3.2 | v1.3.2
## 29. 配置坑 · 失败模式：configuration: v1.3.3-beta.2
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v1.3.3-beta.2
- 对用户的影响：Upgrade or migration may change expected behavior: v1.3.3-beta.2
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.3.3-beta.2. Context: Source discussion did not expose a precise runtime context.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_6d397fcba273f6fa44d3976dd8c91a69 | https://github.com/chenhg5/cc-connect/releases/tag/v1.3.3-beta.2 | v1.3.3-beta.2
## 30. 能力坑 · 能力判断依赖假设
- 严重度：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.
## 31. 运行坑 · 来源证据：出现网络波动后，一直显示这个retrying，只能手动重启吗？
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：出现网络波动后，一直显示这个retrying，只能手动重启吗？
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_8d8f7103758f4f46bffd9b411c81bbf6 | https://github.com/chenhg5/cc-connect/issues/102 | 来源类型 github_issue 暴露的待验证使用条件。
## 32. 维护坑 · 维护活跃度未知
- 严重度：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
## 33. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:1168978399 | https://github.com/chenhg5/cc-connect | no_demo; severity=medium
## 34. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:1168978399 | https://github.com/chenhg5/cc-connect | no_demo; severity=medium
## 35. 安全/权限坑 · 来源证据：[Bug] cursorSession error: unknown option '--trust
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug] cursorSession error: unknown option '--trust
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_d9323b9200ff491e8c6f408880565e86 | https://github.com/chenhg5/cc-connect/issues/923 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。
## 36. 安全/权限坑 · 来源证据：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 暴露的待验证使用条件。
## 37. 安全/权限坑 · 来源证据：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 暴露的待验证使用条件。
## 38. 维护坑 · 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
## 39. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:1168978399 | https://github.com/chenhg5/cc-connect | release_recency=unknown