936 lines
26 KiB
Markdown
936 lines
26 KiB
Markdown
# 使用指南
|
||
|
||
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]
|
||
# 平台特定配置
|
||
```
|