初始化仓库

2026-06-02 23:14:41 +08:00
commit 0bc3f02670
520 changed files with 191097 additions and 0 deletions
@@ -0,0 +1,935 @@
+# 使用指南
+
+cc-connect 完整功能使用指南。
+
+## 目录
+
+- [会话管理](#会话管理)
+- [权限模式](#权限模式)
+- [API Provider 管理](#api-provider-管理)
+- [模型选择](#模型选择)
+- [工作目录切换（`/dir`、`/cd`）](#工作目录切换dircd)
+- [引用查看（`/show`）](#引用查看show)
+- [飞书配置 CLI](#飞书配置-cli)
+- [微信个人号配置 CLI](#微信个人号配置-cli)
+- [Claude Code Router 集成](#claude-code-router-集成)
+- [语音消息（语音转文字）](#语音消息语音转文字)
+- [语音回复（文字转语音）](#语音回复文字转语音)
+- [图片与文件回传](#图片与文件回传)
+- [定时任务 (Cron)](#定时任务-cron)
+- [多机器人中继](#多机器人中继)
+- [守护进程模式](#守护进程模式)
+- [多工作区模式](#多工作区模式)
+- [Web 管理后台（Beta）](#web-管理后台beta)
+- [Bridge — 外部适配器接入（Beta）](#bridge--外部适配器接入beta)
+- [配置参考](#配置参考)
+
+---
+
+## 会话管理
+
+每个用户拥有独立的会话和完整的对话上下文。通过斜杠命令管理：
+
+| 命令 | 说明 |
+|------|------|
+| `/new [名称]` | 创建新会话 |
+| `/list` | 列出当前项目的会话 |
+| `/switch <id>` | 切换到指定会话 |
+| `/current` | 查看当前会话 |
+| `/history [n]` | 查看最近 n 条消息 |
+| `/usage` | 查看账号/模型限额使用情况 |
+| `/provider [...]` | 管理 API Provider |
+| `/model [switch <alias>]` | 列出可用模型或按别名切换 |
+| `/dir [路径]` | 查看或切换 Agent 工作目录 |
+| `/show <引用>` | 按引用查看文件、目录或代码片段 |
+| `/allow <工具名>` | 预授权工具 |
+| `/reasoning [等级]` | 查看或切换推理强度（Codex）|
+| `/mode [名称]` | 查看或切换权限模式 |
+| `/stop` | 停止当前执行 |
+| `/help` | 显示可用命令 |
+
+会话中 Agent 请求工具权限时，回复 **允许** / **拒绝** / **允许所有**。
+
+也可以为项目开启“空闲后自动切换新会话”：
+
+```toml
+[[projects]]
+name = "demo"
+reset_on_idle_mins = 60
+```
+
+开启后，如果用户长时间未发消息，下一条普通消息会自动进入一个新的会话；旧会话仍会保留在 `/list` 中，不会被删除。
+
+### 切换模型时保留历史
+
+`/model` 切换模型时保留当前会话——agent 会在新模型下继续对话（不额外消耗 token）。注意模型切换作用于共享的 agent 实例——如果多个平台使用同一个 project，模型变更会影响所有平台。
+
+---
+
+## 权限模式
+
+所有 Agent 支持运行时切换权限模式，通过 `/mode` 命令。
+
+### Claude Code 模式
+
+| 模式 | 配置值 | 行为 |
+|------|--------|------|
+| 默认 | `default` | 每次工具调用需确认 |
+| 接受编辑 | `acceptEdits` / `edit` | 文件编辑自动通过 |
+| 自动模式 | `auto` | 由 Claude 自动判断何时需要确认 |
+| 计划模式 | `plan` | 只规划不执行 |
+| YOLO | `bypassPermissions` / `yolo` | 全部自动通过 |
+
+### Codex 模式
+
+| 模式 | 配置值 | 行为 |
+|------|--------|------|
+| 建议 | `suggest` | 仅受信命令自动执行 |
+| 自动编辑 | `auto-edit` | 模型自行决定 |
+| 全自动 | `full-auto` | 自动通过 + 沙箱保护 |
+| YOLO | `yolo` | 跳过所有审批 |
+
+### Cursor Agent 模式
+
+| 模式 | 配置值 | 行为 |
+|------|--------|------|
+| 默认 | `default` | 工具调用前询问 |
+| 强制执行 | `force` / `yolo` | 自动批准所有 |
+| 规划模式 | `plan` | 只读分析 |
+| 问答模式 | `ask` | 问答风格，只读 |
+
+### Gemini CLI 模式
+
+| 模式 | 配置值 | 行为 |
+|------|--------|------|
+| 默认 | `default` | 每次需确认 |
+| 自动编辑 | `auto_edit` / `edit` | 编辑自动通过 |
+| 全自动 | `yolo` | 自动批准所有 |
+| 规划模式 | `plan` | 只读规划 |
+
+### Qoder CLI / OpenCode / iFlow CLI
+
+| 模式 | 配置值 | 行为 |
+|------|--------|------|
+| 默认 | `default` | 标准权限 |
+| YOLO | `yolo` | 跳过所有检查 |
+
+### 配置示例
+
+```toml
+[projects.agent.options]
+mode = "default"
+# allowed_tools = ["Read", "Grep", "Glob"]
+```
+
+运行时切换：
+```
+/mode          # 查看当前和可用模式
+/mode yolo     # 切换到 YOLO 模式
+/mode default  # 切回默认
+```
+
+---
+
+## API Provider 管理
+
+运行时切换 API Provider，无需重启。
+
+### 配置 Provider
+
+```toml
+[projects.agent.options]
+work_dir = "/path/to/project"
+provider = "anthropic"
+
+[[projects.agent.providers]]
+name = "anthropic"
+api_key = "sk-ant-xxx"
+
+[[projects.agent.providers]]
+name = "relay"
+api_key = "sk-xxx"
+base_url = "https://api.relay-service.com"
+model = "claude-sonnet-4-20250514"
+
+[[projects.agent.providers.models]]
+model = "claude-sonnet-4-20250514"
+alias = "sonnet"
+
+[[projects.agent.providers.models]]
+model = "claude-opus-4-20250514"
+alias = "opus"
+
+[[projects.agent.providers.models]]
+model = "claude-haiku-3-5-20241022"
+alias = "haiku"
+
+# MiniMax — 兼容 OpenAI 接口，1M 超长上下文
+[[projects.agent.providers]]
+name = "minimax"
+api_key = "your-minimax-api-key"
+base_url = "https://api.minimax.io/v1"
+model = "MiniMax-M2.7"
+
+# Bedrock、Vertex 等
+[[projects.agent.providers]]
+name = "bedrock"
+env = { CLAUDE_CODE_USE_BEDROCK = "1", AWS_PROFILE = "bedrock" }
+```
+
+### CLI 命令
+
+```bash
+cc-connect provider add --project my-backend --name relay --api-key sk-xxx --base-url https://api.relay.com
+cc-connect provider list --project my-backend
+cc-connect provider remove --project my-backend --name relay
+cc-connect provider import --project my-backend  # 从 cc-switch 导入
+```
+
+### 聊天命令
+
+```
+/provider                   查看当前 Provider
+/provider list              列出所有
+/provider add <名称> <key> [url] [model]
+/provider remove <名称>
+/provider switch <名称>
+/provider <名称>            切换快捷方式
+```
+
+### 环境变量映射
+
+| Agent | api_key → | base_url → |
+|-------|-----------|------------|
+| Claude Code | `ANTHROPIC_API_KEY` | `ANTHROPIC_BASE_URL` |
+| Codex | `OPENAI_API_KEY` | `OPENAI_BASE_URL` |
+| Gemini CLI | `GEMINI_API_KEY` | 使用 `env` 字段 |
+| OpenCode | `ANTHROPIC_API_KEY` | 使用 `env` 字段 |
+| iFlow CLI | `IFLOW_API_KEY` | `IFLOW_BASE_URL` |
+
+---
+
+## 模型选择
+
+通过 `[[providers.models]]` 为每个 Provider 预配置可选模型列表。每个条目包含 `model`（模型标识符）和可选的 `alias`（别名，显示在 `/model` 中）。
+
+### 配置模型
+
+```toml
+[[projects.agent.providers]]
+name = "openai"
+api_key = "sk-xxx"
+
+[[projects.agent.providers.models]]
+model = "gpt-5.3-codex"
+alias = "codex"
+
+[[projects.agent.providers.models]]
+model = "gpt-5.4"
+alias = "gpt"
+
+[[projects.agent.providers.models]]
+model = "gpt-5.3-codex-spark"
+alias = "spark"
+```
+
+### 聊天命令
+
+```
+/model              列出可用模型（格式：alias - model）
+/model switch <alias>      按别名切换模型
+/model switch <name>       按完整名称切换模型
+/model <alias>             兼容旧写法，仍然可用
+```
+
+配置了 `models` 时，`/model` 直接显示该列表，不发起 API 请求。未配置时，自动从 Provider API 获取或使用内置备选列表。
+
+---
+
+## 工作目录切换（`/dir`、`/cd`）
+
+可直接在聊天中切换 Agent 下一次会话的工作目录。
+
+### 聊天命令
+
+```
+/dir                    查看当前工作目录和最近历史
+/dir <路径>             切换到指定路径（相对或绝对）
+/dir <序号>             按历史序号切换目录
+/dir -                  返回上一个目录
+/dir help               查看命令用法
+/cd <路径>              `/dir <路径>` 的兼容别名
+```
+
+### 行为说明
+
+- 目录切换会作用于当前项目的下一次会话。
+- 相对路径基于当前 Agent 工作目录解析。
+- 目录历史按项目隔离，可通过序号快速切换。
+- `/cd` 为兼容保留，建议优先使用 `/dir`。
+
+示例：
+
+```text
+/dir ../another-repo
+/dir 2
+/dir -
+```
+
+---
+
+## 本地引用展示配置（`[projects.references]`）
+
+可选启用对 Agent 输出中的本地文件 / 目录 / 代码位置引用进行标准化与重渲染，提升在 IM 平台中的可读性。
+
+这是一个 **opt-in** 功能：
+
+- 未配置 `[projects.references]` 时，现有行为保持不变
+- 只有命中 `normalize_agents` 和 `render_platforms` 时，才会启用
+
+### 推荐配置
+
+```toml
+[projects.references]
+normalize_agents = ["all"]
+render_platforms = ["all"]
+display_path = "relative"
+marker_style = "emoji"
+enclosure_style = "code"
+```
+
+### 字段说明
+
+- `normalize_agents`
+  - 控制哪些 Agent 输出参与这套引用处理
+  - 当前初始支持：`codex`、`claudecode`、`all`
+
+- `render_platforms`
+  - 控制在哪些平台发送前应用展示重写
+  - 当前初始支持：`feishu`、`weixin`、`all`
+
+- `display_path`
+  - 控制路径主体的显示层级
+  - 可选值：`absolute`、`relative`、`basename`、`dirname_basename`、`smart`
+
+- `marker_style`
+  - 控制前缀标记样式
+  - 可选值：`none`、`ascii`、`emoji`
+
+- `enclosure_style`
+  - 控制路径主体的包裹样式
+  - 可选值：`none`、`bracket`、`angle`、`fullwidth`、`code`
+
+### 支持的引用输入
+
+当前初始支持识别这些常见形式：
+
+- 绝对路径
+- 相对路径
+- 文件 / 目录引用
+- `path:line`
+- `path:line:col`
+- `path:start-end`
+- `path#L42`
+- Markdown 本地文件链接
+- Claude 风格的反引号绝对路径引用
+
+### 行为说明
+
+- 只处理 Agent 输出：
+  - thinking
+  - final response
+  - stream preview
+  - progress / card 中的 Agent 文本
+
+- 不处理：
+  - 系统消息
+  - `/workspace`、`/dir`、`/status` 等命令回复
+  - raw tool result
+
+- 网页链接会保持原样，不会被本地引用重写逻辑污染
+
+### 推荐默认值说明
+
+当前最推荐的组合是：
+
+- `display_path = "relative"`
+- `marker_style = "emoji"`
+- `enclosure_style = "code"`
+
+这样通常会得到类似：
+
+- `📄 ui/recovery_contact_form.tsx:11`
+- `📁 docs/spec.v1/`
+
+如果不希望使用 emoji，更推荐：
+
+- `display_path = "dirname_basename"`
+- `marker_style = "ascii"`
+- `enclosure_style = "code"`
+
+---
+
+## 引用查看（`/show`）
+
+可直接基于一个文件 / 目录 / 代码位置引用查看内容，而不必手写 `/shell sed ...`。
+
+### 聊天命令
+
+```text
+/show <路径>                  查看文件前 80 行
+/show <路径:行号>             查看该行附近上下文
+/show <路径:起止行>           查看指定 range
+/show <目录路径/>             查看一级目录列表
+```
+
+支持的输入形式包括：
+
+- 绝对路径
+- 相对路径（相对当前 Agent 工作目录）
+- `path:line`
+- `path:line:col`
+- `path:start-end`
+- `path#L42`
+- Markdown 本地文件链接，如：
+  - `[file.ts](/abs/path/file.ts#L42)`
+
+### 行为说明
+
+- 文件，无位置：
+  - 默认显示文件前 80 行
+- `path:line` / `path#L42`：
+  - 默认显示该位置附近上下文
+- `path:start-end`：
+  - 默认显示该 range
+- 目录：
+  - 默认显示一级目录内容
+
+说明：
+
+- `/show` 只解析“纯引用文本”，不解析前端展示层包装后的 `📄 ...` / `[FILE] ...` 这类样式
+- `/show` 属于本地文件系统查看命令，与 `/shell`、`/dir` 类似，默认受 `admin_from` 权限控制
+- 执行 Shell 命令支持 `!` 快捷前缀：`!ls -la` 等同于 `/shell ls -la`，`! --timeout 300 npm install` 可指定超时时间
+
+示例：
+
+```text
+/show ui/recovery_contact_form.tsx
+/show svc/recovery_session_reconciler.go:12
+/show svc/recovery_session_reconciler_test.go:8-17
+/show docs/spec.v1/
+```
+
+---
+
+## 飞书配置 CLI
+
+可以直接通过 CLI 完成飞书/Lark 机器人创建或关联，并自动写回 `config.toml`：
+
+```bash
+# 推荐：统一入口
+cc-connect feishu setup --project my-project
+cc-connect feishu setup --project my-project --app cli_xxx:sec_xxx
+
+# 强制模式（一般不需要）
+cc-connect feishu new --project my-project
+cc-connect feishu bind --project my-project --app cli_xxx:sec_xxx
+```
+
+区别说明：
+- `setup`：统一入口。没传凭证时等价 `new`，传了 `--app` 时等价 `bind`。
+- `new`：强制二维码新建，不接受 `--app`。
+- `bind`：强制关联已有机器人，必须提供凭证。
+
+行为说明（通用）：
+- `setup` 默认走二维码新建；传入 `--app` 时自动切换到关联已有机器人。
+- `--project` 不存在会自动创建。
+- 项目存在但没有 `feishu/lark` 平台时会自动补一个平台配置。
+- 命令会回填凭证（`app_id` / `app_secret`）；扫码新建场景下飞书通常会预配权限和事件订阅。
+- 建议在飞书开放平台再核验一次发布状态与可用范围。
+- 运行时平台配置还支持可选 `domain` 覆盖 Feishu/Lark API 域名；这不会改变 `setup/new/bind` 的引导地址。
+
+---
+
+## 微信个人号配置 CLI
+
+个人微信走 **ilink 机器人网关**（HTTP 长轮询，与 OpenClaw `openclaw-weixin` 同类）。可直接用 CLI 扫码登录或绑定已有 Token，并写回 `config.toml`。
+
+**完整图文流程与配置项说明见：[docs/weixin.md](./weixin.md)。**
+
+```bash
+# 推荐：终端展示二维码 + URL，微信扫码确认后自动写配置
+cc-connect weixin setup --project my-project
+
+# 已有 Bearer Token（例如从 OpenClaw 导出）
+cc-connect weixin bind --project my-project --token '<token>'
+cc-connect weixin setup --project my-project --token '<token>'
+
+# 强制只走扫码（不接受 --token）
+cc-connect weixin new --project my-project
+```
+
+区别说明：
+
+- `setup`：未传 `--token` 时走扫码；传了 `--token` 时等同绑定并可选校验。
+- `new`：强制扫码。
+- `bind`：强制绑定，必须 `--token`。
+
+行为说明：
+
+- `--project` 不存在时会自动创建项目；项目里没有 `weixin` 平台时会自动追加一块 `[[projects.platforms]]`。
+- 扫码成功后会写入 `token`，以及网关返回的 `base_url`（若有）、`ilink_bot_id` → `account_id` 等。
+- 默认 `--set-allow-from-empty=true`：若 `allow_from` 为空，会用扫码用户的 ilink ID 预填，便于收紧权限。
+- 绑定时默认调用 `getUpdates` 校验 Token；可用 `--skip-verify` 跳过。
+- 首次使用后请在微信里 **先发一条消息**，以便缓存 `context_token`，否则可能无法回复。
+
+常用参数：`--api-url`、`--cdn-url`、`--timeout`、`--qr-image`、`--route-tag`、`--bot-type`、`--debug`（详见 `cc-connect weixin help` 或 [weixin.md](./weixin.md)）。
+
+---
+
+## Claude Code Router 集成
+
+[Claude Code Router](https://github.com/musistudio/claude-code-router) 可将请求路由到不同模型提供商。
+
+### 安装配置
+
+1. 安装：`npm install -g @musistudio/claude-code-router`
+
+2. 配置 `~/.claude-code-router/config.json`：
+```json
+{
+  "APIKEY": "your-secret-key",
+  "Providers": [
+    {
+      "name": "deepseek",
+      "api_base_url": "https://api.deepseek.com/chat/completions",
+      "api_key": "sk-xxx",
+      "models": ["deepseek-chat", "deepseek-reasoner"],
+      "transformer": { "use": ["deepseek"] }
+    }
+  ],
+  "Router": {
+    "default": "deepseek,deepseek-chat",
+    "think": "deepseek,deepseek-reasoner"
+  }
+}
+```
+
+3. 启动：`ccr start`
+
+4. 配置 cc-connect：
+```toml
+[projects.agent.options]
+router_url = "http://127.0.0.1:3456"
+router_api_key = "your-secret-key"
+```
+
+---
+
+## 语音消息（语音转文字）
+
+发送语音消息，自动转文字。
+
+**支持平台：** 飞书、企业微信、Telegram、LINE、Discord、Slack
+
+**前置条件：** OpenAI/Groq API Key，`ffmpeg`
+
+### 配置
+
+```toml
+[speech]
+enabled = true
+provider = "openai"    # 或 "groq"
+language = ""          # "zh"、"en" 或留空自动检测
+
+[speech.openai]
+api_key = "sk-xxx"
+
+# [speech.groq]
+# api_key = "gsk_xxx"
+# model = "whisper-large-v3-turbo"
+```
+
+### 安装 ffmpeg
+
+```bash
+# Ubuntu/Debian
+sudo apt install ffmpeg
+
+# macOS
+brew install ffmpeg
+```
+
+---
+
+## 语音回复（文字转语音）
+
+将 AI 回复合成语音发送。
+
+**支持平台：** 飞书
+
+### 配置
+
+```toml
+[tts]
+enabled = true
+provider = "qwen"        # 或 "openai"
+voice = "Cherry"
+tts_mode = "voice_only"  # "voice_only" | "always"
+max_text_len = 0
+
+[tts.qwen]
+api_key = "sk-xxx"
+```
+
+### TTS 模式
+
+| 模式 | 行为 |
+|------|------|
+| `voice_only` | 仅当用户发语音时才语音回复 |
+| `always` | 始终语音回复 |
+
+切换：`/tts always` 或 `/tts voice_only`
+
+---
+
+## 图片与文件回传
+
+当 Agent 在本地生成了图片、PDF、日志包、报表等文件，需要把结果直接发回当前聊天时，可以使用 `cc-connect send` 的附件模式。
+
+**当前支持平台：**
+- 飞书
+- Telegram
+
+### 什么时候需要先执行 setup
+
+如果当前 Agent 不是“原生 system prompt 注入”类型，升级到包含该功能的版本后，建议先在聊天里执行一次：
+
+```text
+/bind setup
+```
+
+或者：
+
+```text
+/cron setup
+```
+
+这两个命令写入的是同一份 cc-connect 指令。执行任意一个即可。这样 Agent 才会知道：
+- 普通文本回复直接正常输出
+- 生成附件后用 `cc-connect send --image/--file` 回传
+
+如果你以前已经执行过 setup，也建议升级后重新执行一次，以刷新到最新指令。
+
+### 配置开关
+
+如果你想禁用 agent 主动回传附件，可以在 `config.toml` 里加入：
+
+```toml
+attachment_send = "off"
+```
+
+默认值是 `on`。这个开关与 agent 的 `/mode` 独立，只影响 `cc-connect send --image/--file` 这条图片/文件回传路径。
+
+### CLI 用法
+
+```bash
+cc-connect send --image /absolute/path/to/chart.png
+cc-connect send --file /absolute/path/to/report.pdf
+cc-connect send --file /absolute/path/to/report.pdf --image /absolute/path/to/chart.png
+```
+
+说明：
+- `--image` 用于图片附件。
+- `--file` 用于任意文件附件。
+- `--message` 可选，用于先发一段说明文字，再发附件。
+- `--image` 和 `--file` 都可以重复多次。
+- 建议使用绝对路径，避免 Agent 当前工作目录变化导致找不到文件。
+- 如果设置了 `attachment_send = "off"`，图片/文件回传会被拒绝，但普通文本回复仍然正常。
+
+### 典型场景
+
+1. Agent 生成了截图或图表，需要直接发给用户。
+2. Agent 生成了 PDF、Markdown 导出、日志包或补丁文件，需要作为附件交付。
+3. Agent 想告诉用户“结果已生成”，同时附上一个或多个文件。
+
+### 注意事项
+
+- 这个命令是给“附件回传”用的，不要拿它代替普通文本回复。
+- 只能发送本机上 Agent 可访问到的文件。
+- 必须存在活跃会话；如果当前项目没有活动聊天上下文，命令会失败。
+- 平台本身仍可能有文件大小或文件类型限制。
+
+---
+
+## 定时任务 (Cron)
+
+创建自动执行的定时任务。
+
+### 聊天命令
+
+```
+/cron                                          列出所有任务
+/cron add <分> <时> <日> <月> <周> <任务描述>      创建任务
+/cron del <id>                                 删除任务
+/cron enable <id>                              启用
+/cron disable <id>                             禁用
+```
+
+示例：
+```
+/cron add 0 6 * * * 帮我收集 GitHub trending 并总结
+```
+
+### CLI 命令
+
+```bash
+cc-connect cron add --cron "0 6 * * *" --prompt "总结 GitHub trending" --desc "每日趋势"
+cc-connect cron list
+cc-connect cron edit <job-id> <field> <value>   # 可改 cron_expr / prompt / enabled / mute / timeout_mins 等
+cc-connect cron del <job-id>
+```
+
+可选：`--session-mode new-per-run` 每次触发使用新的 agent 会话（默认 `reuse` 与旧行为一致）。`--timeout-mins N` 设置单次调度最长等待分钟数（`0` 表示不限制；省略为 30 分钟）。
+
+### 自然语言（Claude Code）
+
+> "每天早上6点帮我总结 GitHub trending"
+
+Claude Code 会自动创建定时任务。对依赖记忆文件的其他 Agent，先执行一次 `/cron setup` 或 `/bind setup`，效果相同。
+
+---
+
+## 多机器人中继
+
+跨平台机器人通信，群聊多机器人协作。
+
+### 群聊绑定
+
+```
+/bind              查看绑定
+/bind claudecode   添加 claudecode 项目
+/bind gemini       添加 gemini 项目
+/bind -claudecode  移除 claudecode
+```
+
+### 机器人间通信
+
+```bash
+cc-connect relay send --to gemini "你觉得这个架构怎么样？"
+```
+
+---
+
+## 守护进程模式
+
+后台服务运行。
+
+```bash
+cc-connect daemon install --config ~/.cc-connect/config.toml
+cc-connect daemon start
+cc-connect daemon stop
+cc-connect daemon restart
+cc-connect daemon status
+cc-connect daemon logs [-f]
+cc-connect daemon uninstall
+```
+
+---
+
+## 多工作区模式
+
+一个 bot 服务多个工作区，每个频道一个独立工作目录。
+
+### 配置
+
+```toml
+[[projects]]
+name = "my-project"
+mode = "multi-workspace"
+base_dir = "~/workspaces"
+
+[projects.agent]
+type = "claudecode"
+```
+
+### 命令
+
+```
+/workspace                    查看当前绑定
+/workspace bind <名称>        绑定本地文件夹
+/workspace init <git-url>     克隆仓库并绑定
+/workspace unbind             解除绑定
+/workspace list               列出所有绑定
+```
+
+### 工作原理
+
+- 频道名 `#project-a` → 自动绑定 `base_dir/project-a/`
+- 每个频道有独立的会话和 Agent 状态
+
+---
+
+## Web 管理后台（Beta）
+
+> **状态：Beta。** 此功能自 v1.2.2-beta.5 起可用，UI 和 API 在后续版本中可能调整。
+
+内嵌在二进制中的全功能管理界面，支持项目管理、会话管理、定时任务编辑、全局设置、聊天界面、多语言等。
+
+### 快速启用（聊天命令）
+
+最简单的方式，在聊天中发送：
+
+```
+/web setup
+```
+
+该命令会自动在 `config.toml` 中启用 **Management API** 和 **Bridge**，生成 token，并返回访问地址。首次启用后需要执行 `/restart` 使配置生效。
+
+启用后，打开返回的地址（默认 `http://localhost:9820`），用显示的 token 登录即可。
+
+### 查看状态
+
+```
+/web           # 或 /web status — 查看 Web 管理后台的地址和启用状态
+```
+
+### 手动配置
+
+在 `config.toml` 中添加：
+
+```toml
+[management]
+enabled = true
+port = 9820                     # 管理后台监听端口
+token = "your-secret-token"     # 登录 token；/web setup 会自动生成
+cors_origins = ["*"]            # 允许的 CORS 来源；留空则不设置 CORS 头
+```
+
+然后重启 cc-connect。
+
+### 构建选项
+
+Web 前端资源默认编译进二进制。如果想排除（减小约 1MB）：
+
+```bash
+make build-noweb
+# 或
+go build -tags 'no_web' ./cmd/cc-connect
+```
+
+使用 `no_web` 构建时，`/web` 命令会提示 Web 管理后台不可用。
+
+### Management API
+
+API 与 Web UI 共用同一端口。基础 URL：`http://<host>:<port>/api/v1`
+
+所有 API 请求需要 `Authorization: Bearer <token>` 请求头。
+
+主要接口：
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| `GET` | `/api/v1/status` | 系统状态（版本、运行时间、已连接平台） |
+| `POST` | `/api/v1/restart` | 重启 cc-connect |
+| `POST` | `/api/v1/reload` | 重新加载配置 |
+| `GET` | `/api/v1/projects` | 项目列表 |
+| `GET` | `/api/v1/sessions?project=<name>` | 查询项目的会话列表 |
+| `GET` | `/api/v1/cron` | 定时任务列表 |
+| `GET` | `/api/v1/settings` | 获取全局设置 |
+| `PATCH` | `/api/v1/settings` | 更新全局设置 |
+
+完整 API 参考：[management-api.md](./management-api.md)（[中文版](./management-api.zh-CN.md)）
+
+---
+
+## Bridge — 外部适配器接入（Beta）
+
+> **状态：Beta。** 此功能自 v1.2.2-beta.5 起可用，协议在后续版本中可能调整。
+
+Bridge 提供 WebSocket + REST 服务，让外部适配器（自定义 UI、机器人、脚本等）可以接入 cc-connect —— 发送消息、接收 Agent 事件、管理会话。
+
+### 通过聊天启用
+
+`/web setup` 命令会同时启用 Bridge 和管理后台，无需额外操作。
+
+### 手动配置
+
+在 `config.toml` 中添加：
+
+```toml
+[bridge]
+enabled = true
+port = 9810                     # Bridge 监听端口（与管理后台分开）
+token = "your-bridge-secret"    # WebSocket 和 REST 的认证 token
+path = "/bridge/ws"             # WebSocket 端点路径
+cors_origins = ["*"]            # 允许的 CORS 来源；留空则不设置 CORS
+```
+
+然后重启 cc-connect。
+
+### 认证方式
+
+所有 Bridge 连接需要 token 认证，支持三种方式：
+
+- URL 参数：`?token=<bridge-token>`
+- 请求头：`Authorization: Bearer <bridge-token>`
+- 请求头：`X-Bridge-Token: <bridge-token>`
+
+### WebSocket 接入
+
+连接地址：
+
+```
+ws://<host>:<bridge-port>/bridge/ws?token=<bridge-token>
+```
+
+WebSocket 支持双向通信 —— 向 Agent 发送消息，并实时接收 Agent 的文本回复、工具调用、权限请求等事件。
+
+### REST API
+
+与 WebSocket 共用同一端口。
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| `GET` | `/bridge/sessions?session_key=...&project=...` | 查询会话列表 |
+| `POST` | `/bridge/sessions` | 创建新会话 |
+| `GET` | `/bridge/sessions/{id}?session_key=...&project=...` | 获取会话详情及历史 |
+| `DELETE` | `/bridge/sessions/{id}?session_key=...&project=...` | 删除会话 |
+| `POST` | `/bridge/sessions/switch` | 切换当前活跃会话 |
+
+完整协议参考：[bridge-protocol.md](./bridge-protocol.md)（[中文版](./bridge-protocol.zh-CN.md)）
+
+### 端口汇总
+
+| 服务 | 默认端口 | 配置块 |
+|------|---------|--------|
+| 管理后台（Web UI + API） | 9820 | `[management]` |
+| Bridge（WebSocket + REST） | 9810 | `[bridge]` |
+
+---
+
+## 配置参考
+
+完整配置示例见 [config.example.toml](../config.example.toml)。
+
+### 项目结构
+
+```toml
+[[projects]]
+name = "my-project"
+
+[projects.agent]
+type = "claudecode"  # 或 codex, cursor, gemini, qoder, opencode, iflow
+
+[projects.agent.options]
+work_dir = "/path/to/project"
+mode = "default"
+provider = "anthropic"
+
+[[projects.platforms]]
+type = "feishu"  # 或 wps-xiezuo, dingtalk, telegram, slack, discord, wecom, weixin, line, qq, qqbot
+
+[projects.platforms.options]
+# 平台特定配置
+```