From cb39079cf8759fb1ac35a900a71946c67546acf0 Mon Sep 17 00:00:00 2001 From: xuhaihui Date: Fri, 20 Feb 2026 23:06:04 +0800 Subject: [PATCH] docs: add Chinese (zh-CN) i18n support for VitePress documentation - Add locales configuration to .vitepress/config.ts with Chinese nav, sidebar, and UI labels - Create docs/zh/ directory with 24 translated markdown pages covering Guide, Reference, and SDK - Technical terms (daemon, ledger, actor, MCP, etc.) kept in English for consistency - Build verified: vitepress build passes with zero errors --- docs/.vitepress/config.ts | 107 ++++++++ docs/zh/guide/best-practices.md | 254 +++++++++++++++++++ docs/zh/guide/faq.md | 209 +++++++++++++++ docs/zh/guide/getting-started/cli.md | 221 ++++++++++++++++ docs/zh/guide/getting-started/docker.md | 312 +++++++++++++++++++++++ docs/zh/guide/getting-started/index.md | 111 ++++++++ docs/zh/guide/getting-started/web.md | 157 ++++++++++++ docs/zh/guide/im-bridge/dingtalk.md | 241 ++++++++++++++++++ docs/zh/guide/im-bridge/discord.md | 298 ++++++++++++++++++++++ docs/zh/guide/im-bridge/feishu.md | 277 ++++++++++++++++++++ docs/zh/guide/im-bridge/index.md | 79 ++++++ docs/zh/guide/im-bridge/slack.md | 273 ++++++++++++++++++++ docs/zh/guide/im-bridge/telegram.md | 222 ++++++++++++++++ docs/zh/guide/index.md | 33 +++ docs/zh/guide/operations.md | 152 +++++++++++ docs/zh/guide/use-cases.md | 157 ++++++++++++ docs/zh/guide/web-ui.md | 173 +++++++++++++ docs/zh/guide/workflows.md | 138 ++++++++++ docs/zh/index.md | 41 +++ docs/zh/reference/architecture.md | 219 ++++++++++++++++ docs/zh/reference/cli.md | 225 +++++++++++++++++ docs/zh/reference/features.md | 322 ++++++++++++++++++++++++ docs/zh/reference/positioning.md | 58 +++++ docs/zh/sdk/CLIENT_SDK.md | 76 ++++++ docs/zh/sdk/index.md | 26 ++ 25 files changed, 4381 insertions(+) create mode 100644 docs/zh/guide/best-practices.md create mode 100644 docs/zh/guide/faq.md create mode 100644 docs/zh/guide/getting-started/cli.md create mode 100644 docs/zh/guide/getting-started/docker.md create mode 100644 docs/zh/guide/getting-started/index.md create mode 100644 docs/zh/guide/getting-started/web.md create mode 100644 docs/zh/guide/im-bridge/dingtalk.md create mode 100644 docs/zh/guide/im-bridge/discord.md create mode 100644 docs/zh/guide/im-bridge/feishu.md create mode 100644 docs/zh/guide/im-bridge/index.md create mode 100644 docs/zh/guide/im-bridge/slack.md create mode 100644 docs/zh/guide/im-bridge/telegram.md create mode 100644 docs/zh/guide/index.md create mode 100644 docs/zh/guide/operations.md create mode 100644 docs/zh/guide/use-cases.md create mode 100644 docs/zh/guide/web-ui.md create mode 100644 docs/zh/guide/workflows.md create mode 100644 docs/zh/index.md create mode 100644 docs/zh/reference/architecture.md create mode 100644 docs/zh/reference/cli.md create mode 100644 docs/zh/reference/features.md create mode 100644 docs/zh/reference/positioning.md create mode 100644 docs/zh/sdk/CLIENT_SDK.md create mode 100644 docs/zh/sdk/index.md diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index d04438ab..de842788 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -17,6 +17,113 @@ export default defineConfig({ ['link', { rel: 'icon', type: 'image/svg+xml', href: '/cccc/logo.svg' }] ], + locales: { + root: { + label: 'English', + lang: 'en' + }, + zh: { + label: '简体中文', + lang: 'zh-CN', + link: '/zh/', + description: '多智能体协作内核', + themeConfig: { + nav: [ + { text: '指南', link: '/zh/guide/' }, + { text: '参考', link: '/zh/reference/architecture' }, + { text: 'SDK', link: '/zh/sdk/' }, + { text: '发布', link: '/release/' } + ], + + sidebar: { + '/zh/guide/': [ + { + text: '用户指南', + items: [ + { text: '简介', link: '/zh/guide/' } + ] + }, + { + text: '快速开始', + collapsed: false, + items: [ + { text: '概览', link: '/zh/guide/getting-started/' }, + { text: 'Web UI 快速上手', link: '/zh/guide/getting-started/web' }, + { text: 'CLI 快速上手', link: '/zh/guide/getting-started/cli' }, + { text: 'Docker 部署', link: '/zh/guide/getting-started/docker' } + ] + }, + { + text: '核心指南', + items: [ + { text: '使用场景', link: '/zh/guide/use-cases' }, + { text: '工作流', link: '/zh/guide/workflows' }, + { text: '运维手册', link: '/zh/guide/operations' }, + { text: 'Web UI', link: '/zh/guide/web-ui' }, + { text: '最佳实践', link: '/zh/guide/best-practices' }, + { text: '常见问题', link: '/zh/guide/faq' } + ] + }, + { + text: 'IM 桥接', + collapsed: false, + items: [ + { text: '概览', link: '/zh/guide/im-bridge/' }, + { text: 'Telegram', link: '/zh/guide/im-bridge/telegram' }, + { text: 'Slack', link: '/zh/guide/im-bridge/slack' }, + { text: 'Discord', link: '/zh/guide/im-bridge/discord' }, + { text: '飞书', link: '/zh/guide/im-bridge/feishu' }, + { text: '钉钉', link: '/zh/guide/im-bridge/dingtalk' } + ] + } + ], + '/zh/reference/': [ + { + text: '参考', + items: [ + { text: '产品定位', link: '/zh/reference/positioning' }, + { text: '架构', link: '/zh/reference/architecture' }, + { text: '功能特性', link: '/zh/reference/features' }, + { text: 'CLI', link: '/zh/reference/cli' } + ] + } + ], + '/zh/sdk/': [ + { + text: 'SDK', + items: [ + { text: '概览', link: '/zh/sdk/' }, + { text: '客户端 SDK', link: '/zh/sdk/CLIENT_SDK' } + ] + } + ] + }, + + outline: { + label: '本页目录' + }, + + lastUpdated: { + text: '最后更新' + }, + + docFooter: { + prev: '上一页', + next: '下一页' + }, + + darkModeSwitchLabel: '深色模式', + returnToTopLabel: '返回顶部', + sidebarMenuLabel: '菜单', + + footer: { + message: '基于 Apache-2.0 许可发布', + copyright: 'Copyright 2024-present CCCC Contributors' + } + } + } + }, + themeConfig: { logo: '/logo.svg', diff --git a/docs/zh/guide/best-practices.md b/docs/zh/guide/best-practices.md new file mode 100644 index 00000000..21c5472e --- /dev/null +++ b/docs/zh/guide/best-practices.md @@ -0,0 +1,254 @@ +# 最佳实践 + +充分利用 CCCC 的实用技巧。 + +## 成功的准备工作 + +### 编写好的 PROJECT.md + +在项目根目录放置 `PROJECT.md`。这是项目的"宪法"： + +```markdown +# 项目名称 + +## 目标 +一句话描述我们在构建什么。 + +## 约束 +- 必须使用 TypeScript +- 遵循现有代码模式 +- 未经批准不得引入外部依赖 + +## 架构 +代码库结构的简要概述。 + +## 当前重点 +我们目前正在做的事情。 +``` + +Agent 通过 `cccc_project_info` 读取此文件来了解上下文。 + +### 自定义协作手册 + +协作手册是 Agent 遵循的协作契约。你可以按工作组自定义。 + +#### 文件优先级 + +CCCC 按以下优先级加载协作内容： + +1. **工作组覆盖（CCCC_HOME）**：`CCCC_HOME/groups//prompts/CCCC_HELP.md`（最高优先级） +2. **内置默认**：`cccc.resources/cccc-help.md`（兜底） + +要自定义，请编辑工作组提示词覆盖（推荐：Web UI → 设置 → 指导）。 + +你也可以从 Web UI 中查看文件路径（它会显示每个工作组的确切覆盖路径）。 + +#### 条件内容标记 + +你可以使用条件标记向不同角色展示不同内容： + +```markdown +# 我的项目帮助 + +## 通用规则（所有角色可见） +- 遵循编码规范 +- 为新功能编写测试 + +## @role: foreman +### 仅 Foreman 可见的部分 +- 你负责协调团队 +- 对架构做最终决策 + +## @role: peer +### 仅 Peer 可见的部分 +- 专注于分配给你的任务 +- 向 foreman 报告阻塞问题 + +## @actor: impl-agent +### 仅 impl-agent 可见的部分 +- 你负责核心实现 +``` + +**标记语法：** +- `## @role: foreman` - 仅 foreman 可见 +- `## @role: peer` - 仅 peer 可见 +- `## @actor: ` - 仅特定 actor 可见 +- 无标记的部分对所有角色可见 + +#### Agent 如何使用协作手册 + +Agent 通过 MCP 工具访问协作内容： + +1. **`cccc_bootstrap`** - 在会话初始化时返回协作手册 +2. **`cccc_help`** - 按需返回协作内容 + +返回格式为： +```json +{ + "markdown": "<根据角色/actor 过滤的内容>", + "source": "CCCC_HOME/.../prompts/CCCC_HELP.md 或 cccc.resources/cccc-help.md" +} +``` + +Agent 读取 markdown 并语义化地遵循规则。没有特殊的解析——内容以清晰的命令式语言编写，AI 能自然理解。 + +#### 编写有效协作内容的技巧 + +- 使用命令式语言："必须使用 MCP" 而不是 "应该考虑使用 MCP" +- 具体明确："30 秒内回复" 而不是 "快速响应" +- 用清晰的标题结构方便导航 +- 为复杂工作流提供示例 +- 保持章节聚焦——每个部分一个主题 + +### 选择合适的 Agent 组合 + +| 场景 | 推荐配置 | +|------|----------| +| 单人开发 | 1 个 Claude agent | +| 编码 + 审查 | Claude（实现）+ Codex（审查） | +| 全栈项目 | 多个专业化 agent | +| 学习/探索 | 1 个 agent，交互模式 | + +### 正确配置运行时 + +使用推荐的自主运行标志： + +```bash +# Claude Code +cccc actor add impl --runtime claude +# 使用：claude --dangerously-skip-permissions + +# Codex +cccc actor add review --runtime codex +# 使用：codex --dangerously-bypass-approvals-and-sandbox --search +``` + +## 有效沟通 + +### 具体明确 + +❌ "修复这个 bug" +✅ "修复在移动端 Safari 上登录按钮无响应的问题" + +❌ "让它更快" +✅ "优化 getUserById 查询，目前耗时 500ms" + +### 合理使用 @提及 + +- `@all` 用于公告或通用问题 +- `@foreman` 用于协调决策 +- `@specific-agent` 用于定向任务 + +### 提供上下文 + +包含相关信息： +- 错误消息 +- 文件路径 +- 预期行为 vs 实际行为 +- 约束或偏好 + +### 使用回复保持对话有序 + +回复消息以保持对话组织性。Agent 能看到引用的上下文。 + +## 任务管理 + +### 拆分大型任务 + +不要这样："实现用户认证" + +使用里程碑： +1. 用户数据库 schema +2. 注册接口 +3. 登录接口 +4. 会话管理 +5. 密码重置流程 + +### 设定明确的完成标准 + +为每个任务定义"完成"： +- 测试通过 +- 无 lint 错误 +- 文档已更新 +- 代码已审查 + +### 使用 Context 面板 + +- **Vision**：保持项目目标可见 +- **Sketch**：记录技术方案 +- **Milestones**：跟踪主要阶段 +- **Tasks**：分解当前工作 +- **Notes**：记录发现和教训 + +## 多 Agent 协作 + +### 定义清晰的角色 + +| 角色 | 职责 | +|------|------| +| Foreman | 协调、决策、执行工作 | +| 实现者 | 编写代码、遵循规格 | +| 审查者 | 审查代码、提出改进建议 | +| 测试者 | 编写测试、发现 bug | + +### 避免冲突 + +- 将不同的文件/模块分配给不同的 agent +- 对共享资源使用顺序工作流 +- 让 foreman 解决冲突 + +### 定期同步 + +定期检查： +- 所有人是否对齐目标？ +- 有阻塞问题吗？ +- 有冲突的修改吗？ + +## 故障排除技巧 + +### Agent 无响应 + +1. 检查终端标签页是否有错误 +2. 验证 MCP 设置：`cccc setup --runtime ` +3. 尝试重启：在 Web UI 中点击"重启" +4. 检查 Daemon 健康状态和近期事件：`cccc daemon status` 和 `cccc tail -n 100` + +### 消息未投递 + +1. 确保 agent 已启动（绿色指示灯） +2. 检查收件箱：`cccc inbox --actor-id ` +3. 验证 `to` 字段是否正确 + +### 上下文变得陈旧 + +如果 agent 看起来混乱： +1. 重启以清除上下文 +2. 重新陈述当前目标 +3. 明确引用相关文件 + +### 陷入循环 + +如果 agent 不断重复： +1. 停止该 agent +2. 清除任务 +3. 用更清晰的指令重启 + +## 安全最佳实践 + +### 远程访问 + +- 远程访问时始终使用 `CCCC_WEB_TOKEN` +- 优先使用 Cloudflare Access 或 Tailscale，而非直接暴露 +- 不要直接将 8848 端口暴露到互联网 + +### Token 管理 + +- 将 token 存储在环境变量中 +- 不要将 token 提交到 git +- 定期轮换 token + +### 审查 Agent 的变更 + +- 推送前检查提交 +- 使用代码审查 agent +- 设置 CI/CD 安全防线 diff --git a/docs/zh/guide/faq.md b/docs/zh/guide/faq.md new file mode 100644 index 00000000..4c1e7ef2 --- /dev/null +++ b/docs/zh/guide/faq.md @@ -0,0 +1,209 @@ +# 常见问题 + +关于 CCCC 的常见问题解答。 + +## 安装与设置 + +### 如何安装 CCCC？ + +```bash +# 从 PyPI 安装 +pip install -U cccc-pair + +# 从 TestPyPI 安装（显式 RC 测试） +pip install -U --pre \ + --index-url https://test.pypi.org/simple \ + --extra-index-url https://pypi.org/simple \ + cccc-pair + +# 从源码安装 +git clone https://github.com/ChesterRa/cccc +cd cccc +pip install -e . +``` + +### 如何从旧版本（0.3.x）升级？ + +你必须先卸载旧版本： + +```bash +# pipx 用户 +pipx uninstall cccc-pair + +# pip 用户 +pip uninstall cccc-pair + +# 移除残留的可执行文件 +rm -f ~/.local/bin/cccc ~/.local/bin/ccccd +``` + +然后安装新版本。注意 0.4.x 与 0.3.x 的命令结构完全不同。 + +### 系统要求是什么？ + +- Python 3.9+ +- macOS、Linux 或 Windows（Windows 上推荐 WSL 以支持 PTY） +- 至少一个支持的 Agent 运行时 CLI + +### 如何检查 CCCC 是否正常工作？ + +```bash +cccc doctor +``` + +这会检查 Python 版本、可用的运行时和 Daemon 状态。 + +## Agent 相关 + +### 支持哪些 AI Agent？ + +- Claude Code (`claude`) +- Codex CLI (`codex`) +- GitHub Copilot CLI (`copilot`) +- Droid (`droid`) +- OpenCode (`opencode`) +- Gemini CLI (`gemini`) +- Amp (`amp`) +- Auggie (`auggie`) +- Cursor (`cursor`) +- Kilocode (`kilocode`) +- Neovate (`neovate`) +- Custom（任意命令） + +### Foreman 和 Peer 有什么区别？ + +- **Foreman**：第一个启用的 actor。负责协调工作，接收系统通知，可以管理其他 actor。 +- **Peer**：独立的专家。有自己的判断力，只能管理自己。 + +### 如何添加自定义 Agent？ + +```bash +cccc actor add my-agent --runtime custom --command "my-custom-cli" +``` + +### Agent 无法启动？ + +1. 检查终端标签页的错误消息 +2. 验证 MCP 已配置：`cccc setup --runtime ` +3. 确保 CLI 已安装且在 PATH 中 +4. 尝试：`cccc actor restart ` + +## 消息相关 + +### 如何向特定 Agent 发送消息？ + +```bash +cccc send "请执行 X" --to agent-name +``` + +或在 Web UI 中，在消息中输入 `@agent-name`。 + +### Agent 没有回复我的消息？ + +1. 检查 agent 是否正在运行（Web UI 中的绿色指示灯） +2. 检查收件箱：`cccc inbox --actor-id ` +3. 查看终端标签页的错误信息 +4. 尝试重启该 agent + +### 已读回执是如何工作的？ + +Agent 调用 `cccc_inbox_mark_read` 来标记消息为已读。这是累积的——标记消息 X 意味着 X 之前的所有消息都已读。 + +## 远程访问 + +### 如何从手机访问 CCCC？ + +**选项 1：Cloudflare Tunnel** +```bash +cloudflared tunnel --url http://127.0.0.1:8848 +``` + +**选项 2：IM Bridge** +```bash +cccc im set telegram --token-env TELEGRAM_BOT_TOKEN +cccc im start +``` + +**选项 3：Tailscale** +```bash +CCCC_WEB_HOST=$(tailscale ip -4) cccc +``` + +### 暴露 Web UI 安全吗？ + +始终设置认证 token： +```bash +export CCCC_WEB_TOKEN="your-secret-token" +cccc +``` + +使用 Cloudflare Access 或 Tailscale 增加安全层。 + +## 性能 + +### CCCC 占用多少资源？ + +- Daemon：极少（Python 异步） +- Web UI：标准 React 应用 +- Agent：取决于运行时 + +### Ledger 文件越来越大 + +CCCC 支持快照/压缩。大型 blob 单独存储在 `blobs/` 目录中。 + +### 如何降低消息延迟？ + +1. 确保 agent 已经在运行 +2. 使用特定的 @提及 而非广播 +3. 保持 Daemon 运行（不要频繁重启） + +## 故障排除 + +### Daemon 无法启动 + +```bash +cccc daemon status # 检查是否已在运行 +cccc daemon stop # 停止现有实例 +cccc daemon start # 重新启动 +``` + +### 端口 8848 被占用 + +```bash +CCCC_WEB_PORT=9000 cccc +``` + +### MCP 不工作 + +```bash +cccc setup --runtime # 重新运行设置 +cccc doctor # 检查配置 +``` + +### Web UI 无法加载 + +1. 检查 Daemon 是否在运行：`cccc daemon status` +2. 检查端口：http://127.0.0.1:8848/ +3. 检查浏览器控制台的错误 +4. 尝试其他浏览器 + +## 概念 + +### 什么是工作组（Working Group）？ + +工作组就像一个带有执行能力的 IM 群聊。它包括： +- 一个追加写入的 Ledger（消息历史） +- 一个或多个 Actor（agent） +- 可选的 Scope（项目目录） + +### 什么是 Ledger？ + +Ledger 是一个追加写入的事件流，存储所有消息、状态变更和决策。它是工作组的唯一真实来源。 + +### 什么是 MCP？ + +MCP（Model Context Protocol，模型上下文协议）是 Agent 与 CCCC 交互的方式。它提供了丰富的工具接口，用于消息通信、上下文管理、自动化和系统控制。 + +### 什么是 Scope？ + +Scope 是附加到工作组的项目目录。Agent 在 Scope 内工作，事件归属于 Scope。 diff --git a/docs/zh/guide/getting-started/cli.md b/docs/zh/guide/getting-started/cli.md new file mode 100644 index 00000000..828954be --- /dev/null +++ b/docs/zh/guide/getting-started/cli.md @@ -0,0 +1,221 @@ +# CLI 快速上手 + +通过命令行开始使用 CCCC。 + +## 第 1 步：进入项目目录 + +```bash +cd /path/to/your/project +``` + +## 第 2 步：创建工作组 + +```bash +cccc attach . +``` + +这会将当前目录绑定为"Scope"并创建一个工作组。 + +## 第 3 步：为运行时配置 MCP + +```bash +cccc setup --runtime claude # 或 codex, droid, opencode, copilot +``` + +这会配置 MCP（Model Context Protocol），使 Agent 能够与 CCCC 交互。 + +## 第 4 步：添加第一个 Agent + +```bash +cccc actor add assistant --runtime claude +``` + +第一个启用的 Actor 自动成为"Foreman"（协调者）。 + +## 第 5 步：启动 Agent + +```bash +cccc group start +``` + +或启动特定 Agent： + +```bash +cccc actor start assistant +``` + +## 第 6 步：发送消息 + +```bash +cccc send "你好！请自我介绍一下。" +``` + +## 第 7 步：查看响应 + +实时查看 Ledger： + +```bash +cccc tail -f +``` + +或查看收件箱： + +```bash +cccc inbox --actor-id assistant +``` + +## 添加更多 Agent + +添加第二个 Agent： + +```bash +cccc actor add reviewer --runtime codex +cccc actor start reviewer +``` + +发送给特定 Agent： + +```bash +cccc send "请实现这个功能" --to assistant +cccc send "请评审代码" --to reviewer +cccc send "请汇报状态" --to @all +``` + +## 回复消息 + +```bash +# 从 cccc tail 找到 event ID +cccc reply evt_abc123 "谢谢，看起来不错！" +``` + +## 常用命令 + +### 工作组管理 + +```bash +cccc groups # 列出所有工作组 +cccc use # 切换工作组 +cccc active # 显示当前工作组 +cccc group show # 显示工作组元数据 +cccc group start # 启动所有 Agent +cccc group stop # 停止所有 Agent +``` + +### Actor 管理 + +```bash +cccc actor list # 列出 Actor +cccc actor add --runtime # 添加 Actor +cccc actor start # 启动 Actor +cccc actor stop # 停止 Actor +cccc actor restart # 重启 Actor +cccc actor remove # 移除 Actor +``` + +### 消息 + +```bash +cccc send "message" # 不加 --to：使用默认接收者策略（默认：foreman） +cccc send "msg" --to @all # 显式广播 +cccc send "msg" --to assistant # 发送给特定 Actor +cccc reply "response" # 回复消息 +cccc inbox --actor-id assistant # 查看特定 Actor 的未读消息 +cccc tail -n 50 # 最近的事件 +cccc tail -f # 实时追踪事件 +``` + +### Daemon 控制 + +```bash +cccc daemon status # 检查状态 +cccc daemon start # 启动 Daemon +cccc daemon stop # 停止 Daemon +``` + +## 启动 Web UI（可选） + +使用 CLI 的同时，也可以打开 Web UI： + +```bash +cccc # 启动 Daemon + Web UI +``` + +或者仅启动 Web UI（Daemon 已在运行时）： + +```bash +cccc web +``` + +访问 http://127.0.0.1:8848/ + +## 环境变量 + +| 变量 | 默认值 | 说明 | +|------|--------|------| +| `CCCC_HOME` | `~/.cccc` | 运行时目录 | +| `CCCC_WEB_PORT` | `8848` | Web UI 端口 | +| `CCCC_LOG_LEVEL` | `INFO` | 日志详细程度 | + +## 工作流示例 + +```bash +# 设置 +cd ~/projects/my-app +cccc attach . +cccc setup --runtime claude +cccc actor add dev --runtime claude + +# 工作 +cccc group start +cccc send "请实现用户认证功能" + +# 监控 +cccc tail -f + +# 交互 +cccc reply evt_123 "请使用 JWT Token" +cccc send "进度如何？" --to dev + +# 清理 +cccc group stop +``` + +## 故障排查 + +### Daemon 无法启动？ + +```bash +cccc daemon status +cccc daemon stop # 停止卡住的实例 +cccc daemon start +``` + +### Agent 没有响应？ + +```bash +# 检查 Agent 状态 +cccc actor list + +# 重启 Agent +cccc actor restart + +# 检查 MCP 配置 +cccc setup --runtime +``` + +### 找不到工作组？ + +```bash +# 列出所有工作组 +cccc groups + +# 如需重新关联 +cd /path/to/project +cccc attach . +``` + +## 下一步 + +- [工作流](/zh/guide/workflows) — 学习协作模式 +- [CLI 参考](/zh/reference/cli) — 完整命令参考 +- [IM Bridge](/zh/guide/im-bridge/) — 设置移动端访问 diff --git a/docs/zh/guide/getting-started/docker.md b/docs/zh/guide/getting-started/docker.md new file mode 100644 index 00000000..47e7f2e0 --- /dev/null +++ b/docs/zh/guide/getting-started/docker.md @@ -0,0 +1,312 @@ +# Docker 部署 + +在 Docker 容器中运行 CCCC — 适用于服务器、团队和可复现环境。 + +## AI 辅助部署 + +复制下方提示词并粘贴给任意 AI 助手 — 它会引导你交互式完成整个部署。 + +::: details 点击复制 AI 部署提示词 + +```text +You are a deployment assistant for CCCC (Multi-Agent Collaboration Kernel). +Guide the user step-by-step through Docker deployment. Ask questions interactively, don't dump all steps at once. + +## What you're deploying +CCCC is a multi-agent collaboration hub. The Docker image includes Python 3.11, Node.js 20, +and pre-installed AI agent CLIs (Claude Code, Gemini CLI, Codex CLI, Factory CLI). + +## Step 1: Get the source code +Ask: "Do you already have the CCCC repo cloned? If yes, what's the path?" +If no: + git clone https://github.com/ChesterRa/cccc && cd cccc + +## Step 2: Build the image + docker build -f docker/Dockerfile -t cccc . +Note: multi-stage build — first compiles Web UI (Node.js), then packages Python daemon. +If build fails, check: Docker version >= 20.10, sufficient disk space, network access to npm/PyPI. + +## Step 3: Collect user config +Ask each one individually: +1. "What port do you want the Web UI on? (default: 8848)" +2. "Set a CCCC_WEB_TOKEN for authentication (any random string you choose):" +3. "Where are your project files? (absolute path, will be mounted to /workspace)" +4. "Which AI agent API keys do you have? (ANTHROPIC_AUTH_TOKEN / OPENAI_API_KEY / GEMINI_API_KEY)" + +## Step 4: Run the container +Build the docker run command from the user's answers: + docker run -d \ + -p {port}:8848 \ + -v cccc-data:/data \ + -v {project_path}:/workspace \ + -e CCCC_WEB_TOKEN={token} \ + -e {API_KEY_ENV}={api_key} \ + --name cccc \ + cccc + +## Step 5: Verify +Run these and report results: + docker logs cccc + docker exec cccc cccc doctor + +## Troubleshooting knowledge (use when relevant, don't preemptively dump): +- "cannot be used with root/sudo privileges": The Dockerfile uses a non-root `cccc` user. Ensure using the latest Dockerfile. +- Volume permission errors after upgrading: `docker run --rm -v cccc-data:/data python:3.11-slim chown -R 1000:1000 /data` +- Claude CLI onboarding already pre-configured via: `{"hasCompletedOnboarding":true}` in /home/cccc/.claude.json +- Custom Claude CLI config: `docker exec cccc sh -c 'cat > /home/cccc/.claude.json << EOF\n{your json}\nEOF'` +- Check runtime CLIs: `docker exec cccc claude --version` / `gemini --version` / `codex --version` + +## Optional: Docker Compose +If user prefers Compose, point them to the bundled docker/docker-compose.yml: + cp docker/.env.example docker/.env + # Edit docker/.env with their values (CCCC_WEB_TOKEN, API keys, port, workspace path, proxy) + # From project root: + docker compose --env-file docker/.env -f docker/docker-compose.yml up -d --build + # Or from docker directory: + cd docker && docker compose up -d --build + +## Key environment variables reference: +| Variable | Default | Description | +|----------|---------|-------------| +| CCCC_HOME | /data | Data directory | +| CCCC_WEB_HOST | 0.0.0.0 | Web bind address | +| CCCC_WEB_PORT | 8848 | Web port | +| CCCC_WEB_TOKEN | (none) | Auth token (required) | +| CCCC_DAEMON_TRANSPORT | tcp | IPC transport | +| CCCC_DAEMON_HOST | 127.0.0.1 | Daemon bind address | +| CCCC_DAEMON_PORT | 9765 | Daemon IPC port | +| ANTHROPIC_AUTH_TOKEN | (none) | Auth token for Claude | +| OPENAI_API_KEY | (none) | API key for Codex runtime | +| GEMINI_API_KEY | (none) | API key for Gemini CLI runtime | + +## Tone: concise, practical, one step at a time. Confirm each step succeeds before moving on. +``` + +::: + +## 前置条件 + +- [Docker](https://docs.docker.com/get-docker/)（20.10+） +- 至少一个 AI Agent API Key（如 Claude 的 `ANTHROPIC_AUTH_TOKEN`） + +## 快速开始 + +### 1. 构建镜像 + +```bash +git clone https://github.com/ChesterRa/cccc +cd cccc +docker build -f docker/Dockerfile -t cccc . +``` + +::: tip 构建说明 +构建使用多阶段方式：首先编译 Web UI（Node.js），然后打包包含预装 AI Agent CLI（Claude Code、Gemini CLI、Codex CLI）的 Python Daemon。 +::: + +### 2. 运行容器 + +```bash +docker run -d \ + -p 8848:8848 \ + -v cccc-data:/data \ + -v /path/to/your/projects:/workspace \ + -e CCCC_WEB_TOKEN=your-secret-token \ + -e ANTHROPIC_AUTH_TOKEN=sk-ant-xxx \ + --name cccc \ + cccc +``` + +在浏览器中打开 `http://localhost:8848` 访问 Web UI。 + +### 3. 验证 + +```bash +# 检查容器运行状态 +docker logs cccc + +# 健康检查 +docker exec cccc cccc doctor +``` + +## 配置 + +### 环境变量 + +| 变量 | 默认值 | 说明 | +|------|--------|------| +| `CCCC_HOME` | `/data` | 数据目录（工作组、Ledger、配置） | +| `CCCC_WEB_HOST` | `0.0.0.0` | Web 服务绑定地址 | +| `CCCC_WEB_PORT` | `8848` | Web 服务端口 | +| `CCCC_WEB_TOKEN` | _（无）_ | **必填。** Web UI 认证令牌 | +| `CCCC_DAEMON_TRANSPORT` | `tcp` | Daemon IPC 传输方式（`tcp` 或 `unix`） | +| `CCCC_DAEMON_HOST` | `127.0.0.1` | Daemon 绑定地址 | +| `CCCC_DAEMON_PORT` | `9765` | Daemon IPC 端口 | +| `ANTHROPIC_AUTH_TOKEN` | _（无）_ | Claude Code 运行时的认证令牌（不要与 `ANTHROPIC_API_KEY` 同时设置） | +| `ANTHROPIC_BASE_URL` | _（无）_ | Claude Code 自定义 API 端点 | +| `OPENAI_API_KEY` | _（无）_ | Codex 运行时的 API Key | +| `OPENAI_BASE_URL` | _（无）_ | Codex 自定义 API 端点 | +| `GEMINI_API_KEY` | _（无）_ | Gemini CLI 运行时的 API Key | + +### 卷挂载 + +| 容器路径 | 用途 | +|----------|------| +| `/data` | 持久化 CCCC 状态（工作组、Ledger、Daemon 配置） | +| `/workspace` | Agent 工作的项目文件 | + +::: warning 保护你的数据 +务必将 `/data` 挂载到命名卷或宿主机路径，以便在容器重启时持久化状态。 +::: + +## 高级用法 + +### 暴露 Daemon IPC 用于 SDK 访问 + +如需从容器外部访问 Daemon IPC（如 SDK 集成）： + +```bash +docker run -d \ + -p 8848:8848 \ + -p 9765:9765 \ + -v cccc-data:/data \ + -v /path/to/projects:/workspace \ + -e CCCC_WEB_TOKEN=your-secret-token \ + -e CCCC_DAEMON_HOST=0.0.0.0 \ + -e CCCC_DAEMON_ALLOW_REMOTE=1 \ + --name cccc \ + cccc +``` + +### 自定义 Claude CLI 配置 + +容器预配置了 Claude CLI（已跳过 Onboarding）。如需进一步自定义： + +```bash +# 从宿主机写入配置 +docker exec cccc sh -c 'cat > /home/cccc/.claude.json << EOF +{ + "hasCompletedOnboarding": true, + "customApiKey": "your-key" +} +EOF' + +# 或复制配置文件 +docker cp ~/.claude.json cccc:/home/cccc/.claude.json +``` + +### 使用 Docker Compose 运行 + +仓库自带 `docker/docker-compose.yml`。先复制并编辑环境变量文件： + +```bash +cp docker/.env.example docker/.env +# 编辑 docker/.env — 设置 CCCC_WEB_TOKEN、API Key、workspace 路径等 +``` + +创建数据卷（首次运行时需要，因为 Compose 文件使用 `external: true`）： + +```bash +docker volume create cccc-data +``` + +然后选择一种方式启动： + +```bash +# 方式 A：从项目根目录运行（推荐） +docker compose --env-file docker/.env -f docker/docker-compose.yml up -d --build + +# 方式 B：从 docker 目录运行 +cd docker +docker compose up -d --build +``` + +::: info 首次运行 vs 更新 +`--build` 会从源码构建镜像。后续运行中，如果镜像未变更，可省略此参数 — `docker compose up -d` 会复用现有镜像。 +::: + +`.env` 文件控制端口、卷、API Key 和构建代理。详见 `docker/.env.example`。 + +::: tip 在代理后构建 +在 `.env` 中设置 `HTTP_PROXY` 和 `HTTPS_PROXY`，以在 `docker compose build` 时传递代理设置。两个构建阶段（Node.js 和 Python）都会使用代理进行 `curl`、`npm` 和 `pip` 操作。 +::: + +#### 日常运维 + +```bash +# 更新部署（构建 + 重启） +docker compose --env-file docker/.env -f docker/docker-compose.yml up -d --build + +# 强制完全重建（无缓存） +docker compose --env-file docker/.env -f docker/docker-compose.yml up -d --build --no-cache + +# 查看日志 +docker compose --env-file docker/.env -f docker/docker-compose.yml logs -f + +# 停止 +docker compose --env-file docker/.env -f docker/docker-compose.yml down +``` + +### K8s Sidecar 模式 + +Kubernetes 部署时，Daemon 默认绑定 `127.0.0.1:9765` — 适合共享同一 Pod 网络命名空间的 Sidecar 容器。Pod 内通信无需额外配置。 + +## 故障排查 + +### "cannot be used with root/sudo privileges" + +Claude CLI 拒绝以 root 身份运行 `--dangerously-skip-permissions`。Dockerfile 已创建非 root 的 `cccc` 用户来处理此问题。如果看到此错误，请确保使用最新的 Dockerfile。 + +### 卷权限问题 + +如果之前以 root 运行容器后切换到非 root 用户，现有卷数据可能是 root 所有权： + +```bash +# 修复数据卷权限 +docker run --rm -v cccc-data:/data python:3.11-slim \ + chown -R 1000:1000 /data +``` + +### Agent CLI 未找到 + +镜像预装了 Claude Code、Gemini CLI 和 Codex CLI。如果运行时未被检测到： + +```bash +# 检查可用运行时 +docker exec cccc cccc doctor + +# 验证 CLI 可用性 +docker exec cccc claude --version +docker exec cccc gemini --version +docker exec cccc codex --version +``` + +### 容器日志 + +```bash +# 实时日志 +docker logs -f cccc + +# 最近 100 行 +docker logs --tail 100 cccc +``` + +## 预装工具 + +Docker 镜像包含： + +| 工具 | 用途 | +|------|------| +| Python 3.11 | CCCC Daemon 运行环境 | +| Node.js 20 | Agent CLI 运行环境（基于 npm 的工具） | +| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | Anthropic 的 AI 编码 Agent | +| [Gemini CLI](https://github.com/google/gemini-cli) | Google 的 AI 编码 Agent | +| [Codex CLI](https://github.com/openai/codex) | OpenAI 的 AI 编码 Agent | +| [Factory CLI](https://www.factory.ai/) | Factory 的 AI 编码 Agent | +| Git | 版本控制 | + +## 下一步 + +- [Web UI 快速上手](./web) — 通过可视化界面配置 Agent +- [CLI 快速上手](./cli) — 通过命令行管理 CCCC +- [运维手册](/zh/guide/operations) — 生产环境运维指南 +- [安全远程访问](/zh/guide/operations#_5-secure-remote-access) — 设置 Cloudflare Access 或 Tailscale diff --git a/docs/zh/guide/getting-started/index.md b/docs/zh/guide/getting-started/index.md new file mode 100644 index 00000000..c06a5a08 --- /dev/null +++ b/docs/zh/guide/getting-started/index.md @@ -0,0 +1,111 @@ +# 快速上手 + +10 分钟让 CCCC 跑起来。 + +## 选择你的方式 + +CCCC 提供两种上手方式： + +
+ +### [Web UI 快速上手](./web) + +**推荐大多数用户使用** + +- 可视化管理 Agent +- 点击式配置 +- 实时终端视图 +- 移动端友好 + +### [CLI 快速上手](./cli) + +**终端爱好者专属** + +- 命令行全面控制 +- 可脚本化、自动化 +- 适合 CI/CD 集成 +- 高级用户功能 + +### [Docker 部署](./docker) + +**适用于服务器和团队** + +- 一条命令部署 +- 预装 AI Agent CLI +- 卷持久化数据 +- Docker Compose 和 K8s 就绪 + +
+ +## 前置条件 + +两种方式都需要： + +- **Python 3.9+** +- 至少一个 AI Agent CLI： + - [Claude Code](https://docs.anthropic.com/en/docs/claude-code)（推荐） + - [Codex CLI](https://github.com/openai/codex) + - [GitHub Copilot CLI](https://docs.github.com/en/copilot) + - 或其他支持的运行时 + +## 安装 + +### 从旧版本升级 + +如果已安装旧版 cccc-pair（如 0.3.x），必须先卸载： + +```bash +# pipx 用户 +pipx uninstall cccc-pair + +# pip 用户 +pip uninstall cccc-pair + +# 如需清理残留二进制文件 +rm -f ~/.local/bin/cccc ~/.local/bin/ccccd +``` + +::: warning 0.4.x 版本的破坏性变更 +0.4.x 版本的命令结构与 0.3.x 完全不同。旧的 `init`、`run`、`bridge` 命令已替换为 `attach`、`daemon`、`mcp` 等。 +::: + +### 从 PyPI 安装 + +```bash +pip install -U cccc-pair +``` + +### 从 TestPyPI 安装（用于 RC 测试） + +```bash +pip install -U --pre \ + --index-url https://test.pypi.org/simple \ + --extra-index-url https://pypi.org/simple \ + cccc-pair +``` + +### 从源码安装 + +```bash +git clone https://github.com/ChesterRa/cccc +cd cccc +pip install -e . +``` + +## 验证安装 + +```bash +cccc doctor +``` + +此命令会检查 Python 版本、可用运行时和系统配置。 + +## 下一步 + +- [Web UI 快速上手](./web) — 使用可视化界面开始 +- [CLI 快速上手](./cli) — 使用命令行开始 +- [Docker 部署](./docker) — 在 Docker 容器中部署 CCCC +- [SDK 概览](/zh/sdk/) — 将 CCCC 集成到外部应用/服务 +- [使用场景](/zh/guide/use-cases) — 了解高投入产出比的真实场景 +- [运维手册](/zh/guide/operations) — 以运维级可靠性运行 CCCC +- [定位](/zh/reference/positioning) — 确定 CCCC 在你技术栈中的位置 diff --git a/docs/zh/guide/getting-started/web.md b/docs/zh/guide/getting-started/web.md new file mode 100644 index 00000000..d67d6016 --- /dev/null +++ b/docs/zh/guide/getting-started/web.md @@ -0,0 +1,157 @@ +# Web UI 快速上手 + +通过 Web 界面开始使用 CCCC。 + +## 第 1 步：启动 CCCC + +打开终端并运行： + +```bash +cccc +``` + +这会同时启动 Daemon 和 Web UI。 + +## 第 2 步：打开 Web UI + +在浏览器中访问： + +``` +http://127.0.0.1:8848/ +``` + +你应该能看到 CCCC Web 界面。 + +## 第 3 步：创建工作组 + +1. 点击侧边栏的 **+** 按钮 +2. 或者关联一个已有项目： + +```bash +# 在另一个终端中 +cd /path/to/your/project +cccc attach . +``` + +3. 刷新 Web UI 即可看到新工作组 + +## 第 4 步：添加第一个 Agent + +1. 点击顶部的 **Add Actor** +2. 填写表单： + - **Actor ID**：例如 `assistant` + - **Runtime**：选择你已安装的 CLI（如 Claude） + - **Runner**：PTY（终端）或 Headless +3. 点击 **Create** + +## 第 5 步：配置 MCP（仅首次需要） + +如果这是你第一次使用该运行时： + +```bash +cccc setup --runtime claude # 或 codex, droid 等 +``` + +这会配置 Agent 与 CCCC 的通信协议。 + +## 第 6 步：启动 Agent + +1. 在标签页中找到你的 Agent +2. 点击 **Play** 按钮启动 +3. 等待 Agent 初始化 + +Agent 的终端输出会显示在标签页中。 + +## 第 7 步：发送第一条消息 + +1. 点击 **Chat** 标签页 +2. 在输入框中输入： + ``` + 你好！请自我介绍一下。 + ``` +3. 按 `Ctrl+Enter` / `Cmd+Enter`，或点击发送 + +## 第 8 步：观察 Agent 工作 + +1. 切换到 Agent 标签页查看终端输出 +2. 观察 Agent 处理你的请求 +3. 响应会出现在 Chat 标签页中 + +## 添加更多 Agent + +要添加第二个协作 Agent： + +1. 再次点击 **Add Actor** +2. 使用不同的 ID（如 `reviewer`） +3. 可选择不同的运行时 +4. 启动 Agent + +现在你可以： +- 发送给所有人：直接输入消息 +- 发送给特定 Agent：使用 `@assistant` 或 `@reviewer` + +## 使用 Context 面板 + +点击 **Context** 打开侧面板： + +- **Vision**：设置项目目标 +- **Sketch**：记录执行方案 +- **Tasks**：跟踪工作项 +- **Notes**：记录心得 + +Agent 可以读取和更新这些共享上下文。 + +## Web UI 功能一览 + +| 功能 | 操作方式 | +|------|----------| +| 切换工作组 | 点击侧边栏中的工作组 | +| Agent 终端 | 点击 Agent 标签页 | +| 发送消息 | Chat 标签页输入框 | +| @提及 | 输入 `@` 触发自动补全 | +| 回复消息 | 点击回复图标 | +| 设置 | 顶部齿轮图标 | +| 主题 | 点击月亮/太阳图标 | + +## 快捷键 + +| 快捷键 | 操作 | +|--------|------| +| `Ctrl+Enter` / `Cmd+Enter` | 发送消息 | +| `Enter` | 换行 | +| `@` | 打开提及菜单 | +| `Escape` | 取消回复 / 关闭菜单 | +| `↑` `↓` | 导航提及菜单 | +| `Tab` / `Enter` | 选择提及 | + +## 故障排查 + +### Web UI 无法加载？ + +1. 检查 Daemon 是否运行： + ```bash + cccc daemon status + ``` + +2. 尝试其他端口： + ```bash + CCCC_WEB_PORT=9000 cccc + ``` + +### Agent 无法启动？ + +1. 检查终端标签页的错误信息 +2. 验证 MCP 配置： + ```bash + cccc setup --runtime + ``` + +### 看不到项目？ + +在项目目录中运行 `cccc attach .`，然后刷新 Web UI。 + +## 下一步 + +- [工作流](/zh/guide/workflows) — 学习协作模式 +- [Web UI 指南](/zh/guide/web-ui) — 详细 UI 文档 +- [IM Bridge](/zh/guide/im-bridge/) — 设置移动端访问 diff --git a/docs/zh/guide/im-bridge/dingtalk.md b/docs/zh/guide/im-bridge/dingtalk.md new file mode 100644 index 00000000..0ab7710b --- /dev/null +++ b/docs/zh/guide/im-bridge/dingtalk.md @@ -0,0 +1,241 @@ +# 钉钉设置 + +将你的 CCCC 工作组连接到钉钉，实现企业协作。 + +## 概览 + +钉钉适合： + +- 中国企业 +- 阿里巴巴生态用户 +- 已在使用钉钉的团队 + +CCCC 使用钉钉 Stream 模式（持久 WebSocket 连接）接收消息，使用钉钉开放 API 发送消息。不需要公网 URL。 + +## 前提条件 + +- 拥有管理员权限的钉钉企业账号 +- CCCC 已安装并运行 + +## 第一步：创建应用 + +1. 前往[钉钉开放平台](https://open.dingtalk.com/) +2. 使用企业管理员账号登录 +3. 点击 **应用开发** → **企业内部开发** +4. 点击 **创建应用** +5. 填写： + - 应用名称（例如 "CCCC Bot"） + - 应用描述 + - 应用图标 +6. 点击 **确认** + +## 第二步：配置权限 + +1. 进入 **权限管理** +2. 申请以下权限： + +| 权限 | 用途 | +|------|------| +| `Robot.SingleChat.ReadWrite` | 单聊机器人管理 | +| `qyapi_robot_sendmsg` | 机器人主动发送消息 | +| `qyapi_chat_read` | 读取群基本信息 | +| `qyapi_chat_manage` | 管理群聊（创建、更新、发送消息） | + +3. 点击启用每个权限（企业内部应用无需审批） + +## 第三步：启用机器人 + +1. 在 **应用能力** → **机器人** +2. 启用机器人能力 +3. 配置机器人设置： + - 机器人名称 + - 机器人头像 + +## 第四步：发布应用 + +1. 进入 **版本管理** +2. 创建新版本 +3. 配置可见范围： + - 全部员工 + - 指定部门 + - 指定用户 +4. 发布版本 + +## 第五步：配置并启动 CCCC + +1. 在应用管理中，进入 **凭证与基础信息** +2. 复制 **AppKey** 和 **AppSecret** +3. （可选）复制 **RobotCode**（如果在机器人设置中显示）——CCCC 有时可以在第一条入站消息后自动获取，但预先配置对附件发送更可靠 + +### 选项 A：通过 Web UI + +1. 打开 CCCC Web UI：`http://127.0.0.1:8848/` +2. 进入 **设置**（顶栏的齿轮图标） +3. 导航到 **IM Bridge** 标签页 +4. 选择 **钉钉** 作为平台 +5. 输入你的凭据： + - **App Key**：你的钉钉 AppKey + - **App Secret**：你的钉钉 AppSecret +6. 点击 **保存配置** — Bridge 会自动启动并显示 **运行中** 状态 + +### 选项 B：通过 CLI + +首先设置环境变量： + +```bash +export DINGTALK_APP_KEY="your_app_key" +export DINGTALK_APP_SECRET="your_app_secret" +export DINGTALK_ROBOT_CODE="your_robot_code" # 可选但推荐 +``` + +然后配置并启动 Bridge： + +```bash +cccc im set dingtalk \ + --app-key-env DINGTALK_APP_KEY \ + --app-secret-env DINGTALK_APP_SECRET \ + --robot-code-env DINGTALK_ROBOT_CODE + +cccc im start +``` + +验证是否运行中： + +```bash +cccc im status +``` + +两种方式都会保存到 `group.yaml`： + +```yaml +im: + platform: dingtalk + dingtalk_app_key_env: DINGTALK_APP_KEY + dingtalk_app_secret_env: DINGTALK_APP_SECRET + dingtalk_robot_code_env: DINGTALK_ROBOT_CODE +``` + +## 第六步：在钉钉中订阅 + +1. 在钉钉应用中找到机器人 +2. 添加到群聊或开始单聊 +3. 发送 `/subscribe` +4. 确认订阅 + +## 使用方法 + +### 向 Agent 发送消息 + +钉钉支持两种发送消息的方式： + +**私聊（隐式发送）** — 直接输入消息： + +``` +请检查一下代码质量 +``` + +**显式 `/send` 命令** — 指定收件人： + +``` +/send @foreman 请检查代码质量 +/send @all 请更新一下状态 +``` + +::: tip 隐式发送 +钉钉消息始终定向到机器人（通过群聊中的 @提及或单聊），所以纯文本会自动视为 `/send` 给 foreman。你只需要在指定其他 agent 时使用显式的 `/send` 命令。 +::: + +### 指定特定 Agent + +使用 `@提及` 语法配合 `/send` 命令： + +``` +/send @foreman 请分配今天的开发任务 +/send @reviewer 请审查最新的提交 +/send @all 请更新一下状态 +``` + +### 接收消息 + +订阅后，你会自动收到： +- Agent 的回复 +- 状态更新 +- 错误通知 + +使用 `/verbose` 切换是否接收 agent 之间的消息。 + +### 消息类型 + +钉钉支持多种消息类型： + +- **文本**：纯文本消息 +- **Markdown**：格式化文本 +- **链接**：URL 卡片 +- **ActionCard**：带按钮的交互卡片 + +CCCC 会自动选择合适的格式。 + +### 文件分享 + +在消息中附加文件。钉钉文件会被下载并存储到 CCCC 的 blob 存储中，然后转发给 agent。 + +## 命令参考 + +| 命令 | 描述 | +|------|------| +| `/subscribe` | 开始接收 CCCC 消息 | +| `/unsubscribe` | 停止接收消息 | +| `/send <消息>` | 发送给 foreman（默认） | +| `/send @ <消息>` | 发送给指定 agent | +| `/send @all <消息>` | 发送给所有 agent | +| `/send @peers <消息>` | 发送给非 foreman 的 agent | +| `/status` | 显示工作组和 agent 状态 | +| `/pause` | 暂停消息投递 | +| `/resume` | 恢复消息投递 | +| `/verbose` | 切换详细模式（查看所有 agent 消息） | +| `/help` | 显示可用命令 | + +## 故障排除 + +### "Invalid appkey" 错误 + +1. 在钉钉开放平台验证 AppKey +2. 检查环境变量是否设置正确 +3. 确保应用已发布 + +### "No permission" 错误 + +1. 检查所需权限是否已授予 +2. 验证应用对用户是否可见 +3. 确保应用版本已发布 + +### 机器人没有响应 + +1. 检查机器人是否已添加到聊天中 +2. 验证 Bridge 是否运行中： + ```bash + cccc im status + ``` +3. 查看日志： + ```bash + cccc im logs -f + ``` + +### 连接断开 + +如果连接意外断开： + +1. 检查网络连接 +2. 重启 Bridge： + ```bash + cccc im stop + cccc im start + ``` + +## 安全注意事项 + +- 妥善保管 AppSecret 并定期轮换 +- 使用最小必要权限 +- 定期审查机器人/应用访问权限 +- 定期审计消息日志 +- 限制机器人对必要员工的可见性 diff --git a/docs/zh/guide/im-bridge/discord.md b/docs/zh/guide/im-bridge/discord.md new file mode 100644 index 00000000..c3818fe7 --- /dev/null +++ b/docs/zh/guide/im-bridge/discord.md @@ -0,0 +1,298 @@ +# Discord 设置 + +将你的 CCCC 工作组连接到 Discord，实现社区访问。 + +## 概览 + +Discord 集成适合： + +- 开发者社区 +- 开源项目 +- 游戏和爱好群组 +- 公开协作 + +## 前提条件 + +- 一个拥有管理员权限的 Discord 服务器 +- CCCC 已安装并运行 + +## 第一步：创建 Discord 应用 + +1. 前往 [Discord Developer Portal](https://discord.com/developers/applications) +2. 点击 **New Application** +3. 输入名称（例如 "CCCC Bot"） +4. 接受条款并点击 **Create** + +## 第二步：创建 Bot + +1. 在你的应用中，进入侧边栏的 **Bot** +2. 点击 **Add Bot** +3. 点击 **Yes, do it!** 确认 + +### 配置 Bot 设置 + +在 Bot 部分： + +| 设置 | 推荐值 | +|------|--------| +| Public Bot | OFF（除非你希望他人添加它） | +| Requires OAuth2 Code Grant | OFF | +| Presence Intent | OFF | +| Server Members Intent | OFF | +| Message Content Intent | **ON**（必需！） | + +::: warning 重要 +**Message Content Intent** 必须启用，否则 bot 无法读取消息。 +::: + +## 第三步：获取 Bot Token + +1. 在 **Bot** 部分，点击 **Reset Token** +2. 确认并复制新 token +3. **安全保存此 token** + +::: danger 安全警告 +永远不要分享你的 bot token。如果泄露，请立即重新生成。 +::: + +## 第四步：设置 Bot 权限 + +1. 进入 **OAuth2** → **URL Generator** +2. 在 **Scopes** 下选择： + - `bot` + - `applications.commands`（可选，用于斜杠命令） + +3. 在 **Bot Permissions** 下选择： + +| 权限 | 用途 | +|------|------| +| Read Messages/View Channels | 查看频道和消息 | +| Send Messages | 回复用户 | +| Send Messages in Threads | 在线程中回复 | +| Embed Links | 富消息格式 | +| Attach Files | 分享文件 | +| Read Message History | 访问对话历史 | +| Add Reactions | 添加表情回应 | + +4. 复制底部生成的 URL + +## 第五步：将 Bot 添加到服务器 + +1. 在浏览器中打开第四步的 URL +2. 从下拉菜单中选择你的服务器 +3. 点击 **Continue** +4. 审查权限并点击 **Authorize** +5. 完成验证码 + +## 第六步：设置环境变量 + +```bash +# 添加到你的 shell 配置文件 +export DISCORD_BOT_TOKEN="your-bot-token-here" +``` + +## 第七步：配置 CCCC + +### 选项 A：通过 Web UI + +1. 打开 CCCC Web UI：`http://127.0.0.1:8848/` +2. 进入 **设置**（顶栏的齿轮图标） +3. 导航到 **IM Bridge** 部分 +4. 选择 **Discord** 作为平台 +5. 输入你的凭据： + - **Token 环境变量**：`DISCORD_BOT_TOKEN` +6. 点击 **保存** + +### 选项 B：通过 CLI + +```bash +cccc im set discord --token-env DISCORD_BOT_TOKEN +``` + +两种方式都会保存到 `group.yaml`： + +```yaml +im: + platform: discord + token_env: DISCORD_BOT_TOKEN +``` + +## 第八步：启动 Bridge + +```bash +cccc im start +``` + +## 第九步：在 Discord 中订阅 + +1. 在 bot 有权限的频道中 +2. 发送 `/subscribe` +3. 你应该会收到确认消息 + +## 使用方法 + +### 向 Agent 发送消息 + +在频道中，先 @提及 bot，然后使用 `/send` 命令： + +``` +@YourBotName /send 请审查最新的 Pull Request +``` + +在与 bot 的私信中，可以直接使用 `/send`： + +``` +/send 请审查最新的 Pull Request +``` + +::: warning 注意 +- 在频道中，必须先 @提及 bot 才能路由消息 +- @提及 bot 后，纯文本会被视为隐式发送给 foreman +- 需要指定 `@all` 或 `@peers` 等收件人时使用 `/send` +::: + +### 指定特定 Agent + +使用 `@提及` 语法配合 `/send` 命令： + +``` +/send @foreman 协调发布工作 +/send @tester 运行集成测试 +/send @all 请更新一下状态 +``` + +### 接收消息 + +订阅后，你会自动收到： +- Agent 的回复 +- 状态更新 +- 错误通知 + +使用 `/verbose` 切换是否接收 agent 之间的消息。 + +### 线程支持 + +创建线程进行聚焦讨论。CCCC 会跟踪线程上下文。 + +### 文件附件 + +在消息中附加文件。文件会存储到 CCCC 的 blob 存储中，然后转发给 agent。 + +### 嵌入消息 + +CCCC 会在适当时使用 Discord 嵌入格式（Embed）来提高可读性。 + +## 命令参考 + +| 命令 | 描述 | +|------|------| +| `/subscribe` | 开始接收 CCCC 消息 | +| `/unsubscribe` | 停止接收消息 | +| `/send <消息>` | 发送给 foreman（默认） | +| `/send @ <消息>` | 发送给指定 agent | +| `/send @all <消息>` | 发送给所有 agent | +| `/send @peers <消息>` | 发送给非 foreman 的 agent | +| `/status` | 显示工作组和 agent 状态 | +| `/pause` | 暂停消息投递 | +| `/resume` | 恢复消息投递 | +| `/verbose` | 切换详细模式（查看所有 agent 消息） | +| `/help` | 显示可用命令 | + +## 斜杠命令（可选） + +注册应用命令以获得更好的用户体验： + +1. 在 Developer Portal 中进入你的应用 +2. 导航到 **Bot** → **Interactions Endpoint URL** +3. 或使用 Discord API 注册命令 + +示例斜杠命令结构： +``` +/cccc send <消息> +/cccc status +/cccc agents +``` + +## 故障排除 + +### "Missing Access" 错误 + +Bot 缺少权限： + +1. 在服务器设置中检查 bot 的角色 +2. 确保角色具有必要的权限 +3. 验证频道特定的权限 + +### "Missing Intent" 错误 + +启用 Message Content Intent： + +1. 进入 Developer Portal → 你的应用 → Bot +2. 启用 **Message Content Intent** +3. 保存更改 +4. 重启 Bridge + +### Bot 显示离线 + +1. 检查 Bridge 是否运行中： + ```bash + cccc im status + ``` + +2. 验证 token： + ```bash + cccc im logs -f + ``` + +3. 如果需要，重新生成 token + +### 频率限制 + +Discord 有严格的频率限制： +- 降低消息发送频率 +- 使用 `/verbose off` 减少流量 +- 考虑批量更新 + +## 高级配置 + +### 指定频道 + +限制 bot 到特定频道： + +```yaml +im: + platform: discord + token_env: DISCORD_BOT_TOKEN + allowed_channels: + - 123456789012345678 # 频道 ID +``` + +获取频道 ID：在 Discord 设置中启用开发者模式，右键点击频道 → 复制 ID。 + +### 活动状态 + +设置 bot 的状态消息： + +```yaml +im: + platform: discord + token_env: DISCORD_BOT_TOKEN + activity: + type: watching # playing, streaming, listening, watching + name: "for commands" +``` + +### 多服务器 + +一个 bot 可以服务多个服务器。每个服务器需要： +1. 通过 OAuth URL 添加 bot +2. 在所需的频道中订阅 + +## 安全注意事项 + +- 保管好 bot token +- 将 bot 权限限制在所需范围内 +- 使用频道权限限制访问 +- 定期审查服务器角色 +- 考虑为你的服务器设置验证级别 +- 谨慎使用公共 bot — 任何人都可以添加它们 diff --git a/docs/zh/guide/im-bridge/feishu.md b/docs/zh/guide/im-bridge/feishu.md new file mode 100644 index 00000000..b64b7d42 --- /dev/null +++ b/docs/zh/guide/im-bridge/feishu.md @@ -0,0 +1,277 @@ +# 飞书（Lark）设置 + +将你的 CCCC 工作组连接到飞书，实现企业协作。 + +## 概览 + +飞书（也称 Lark 国际版）适合： + +- 中国企业 +- 已在使用飞书的团队 +- 字节跳动生态用户 + +## 前提条件 + +- 拥有管理员权限的飞书企业账号 +- CCCC 已安装并运行 + +## 第一步：创建应用 + +1. 前往[飞书开放平台](https://open.feishu.cn/app) +2. 点击 **创建自建应用** +3. 填写应用信息： + - 应用名称（例如 "CCCC Bot"） + - 应用描述 + - 应用图标 +4. 点击 **创建** + +## 第二步：配置权限 + +1. 进入 **权限管理** +2. 点击 **添加权限** +3. 在搜索框中搜索 `im:message` +4. 选择 **应用权限** 标签 +5. 点击 **全选** 选中所有 `im:message` 相关权限 +6. 同时搜索 `im:chat:readonly` 并启用（用于显示聊天标题） +7. 点击 **确认并申请** + +![飞书权限配置](/images/feishu-permissions.png) + +::: tip 所需权限 +| 权限 | 用途 | +|------|------| +| `im:message`（全部） | 发送和接收消息 | +| `im:chat:readonly` | 显示聊天/群组标题（可选，缺失时回退到聊天 ID） | +::: + +## 第三步：配置 CCCC + +1. 在应用管理后台，进入 **凭证与基础信息** +2. 复制 **App ID** 和 **App Secret** + +::: warning 安全提示 +请妥善保管 App Secret。永远不要将其提交到版本控制。 +::: + +### 选项 A：通过 Web UI + +1. 打开 CCCC Web UI：`http://127.0.0.1:8848/` +2. 进入 **设置**（顶栏的齿轮图标） +3. 导航到 **IM Bridge** 标签页 +4. 选择 **飞书/Lark** 作为平台 +5. 输入你的凭据： + - **App ID**：你的飞书 App ID（例如 `cli_a9e92055a5b89bc6`） + - **App Secret**：你的飞书 App Secret +6. 点击 **保存配置** + +![CCCC IM Bridge 配置](/images/cccc-im-bridge-feishu.png) + +### 选项 B：通过 CLI + +首先设置环境变量： + +```bash +export FEISHU_APP_ID="cli_your_app_id" +export FEISHU_APP_SECRET="your_app_secret" +``` + +然后配置 CCCC： + +```bash +cccc im set feishu \ + --app-key-env FEISHU_APP_ID \ + --app-secret-env FEISHU_APP_SECRET +``` + +两种方式都会保存到 `group.yaml`： + +```yaml +im: + platform: feishu + feishu_app_id_env: FEISHU_APP_ID + feishu_app_secret_env: FEISHU_APP_SECRET +``` + +## 第四步：启动 Bridge + +### 通过 Web UI + +在 IM Bridge 设置中点击 **保存配置** 按钮。Bridge 会自动启动并显示 **运行中** 状态。 + +### 通过 CLI + +```bash +cccc im start +``` + +验证是否运行中： + +```bash +cccc im status +``` + +## 第五步：启用长连接（推荐） + +::: warning 前提条件 +在配置事件订阅之前，CCCC IM Bridge 必须已经在运行。启用长连接后，CCCC 可以通过长连接接收事件（此模式不需要公开的回调 URL）。 +::: + +1. 返回[飞书开放平台](https://open.feishu.cn/app) +2. 导航到你的应用 → **事件与回调** +3. 在 **事件配置** 标签页，找到 **订阅方式** +4. 选择 **使用长连接接收事件**（推荐） +5. 点击 **保存** + +![飞书事件配置 - 长连接](/images/feishu-event-config.png) + +## 第六步：配置事件订阅 + +1. 在 **事件订阅** 中，点击 **添加事件** +2. 订阅以下事件： + +| 事件 | 用途 | +|------|------| +| `im.message.receive_v1` | 接收消息 | +| `im.message.message_read_v1` | 已读回执 | + +3. 点击 **保存** + +## 第七步：启用机器人 + +::: tip 为什么需要这一步？ +你必须启用机器人能力，这样用户才能在应用发布后找到并与机器人聊天。 +::: + +1. 在侧边栏中，进入 **应用能力** → **机器人** +2. 在 **机器人设置** 中，填写 **入门指引** 字段（例如 "cccc im"） +3. 点击 **保存** + +![飞书机器人设置](/images/feishu-bot-setting.png) + +## 第八步：发布应用 + +1. 进入 **版本管理与发布** +2. 创建新版本 +3. 提交审核（企业内部应用可能自动审批） +4. 审批通过后，发布到你的组织 + +## 第九步：在飞书中订阅 + +1. 在飞书应用中找到机器人 +2. 开始聊天或添加到群组 +3. 发送 `/subscribe` +4. 确认订阅 + +## 使用方法 + +### 向 Agent 发送消息 + +飞书支持两种发送消息的方式： + +**在群聊中** — @提及机器人并直接输入消息： + +``` +@YourBotName 请实现登录功能 +``` + +或使用显式的 `/send` 命令指定收件人： + +``` +@YourBotName /send @all 请更新一下状态 +``` + +**在私聊中** — 直接输入消息： + +``` +请实现登录功能 +``` + +::: tip 隐式发送 +当你 @提及机器人（在群聊中）或发送私聊消息时，纯文本会自动视为 `/send` 给 foreman。你只需要在指定其他 agent（如 `@all` 或 `@peers`）时使用显式的 `/send` 命令。 +::: + +### 指定特定 Agent + +使用 `@提及` 语法配合 `/send` 命令： + +``` +/send @backend 检查 API 端点 +/send @all 请更新一下状态 +/send @peers 请审查这个 PR +``` + +### 接收消息 + +订阅后，你会自动收到： +- Agent 的回复 +- 状态更新 +- 错误通知 + +使用 `/verbose` 切换是否接收 agent 之间的消息。 + +### 文件分享 + +在消息中附加文件。飞书文件会被下载并存储到 CCCC 的 blob 存储中，然后转发给 agent。 + +## 命令参考 + +| 命令 | 描述 | +|------|------| +| `/subscribe` | 开始接收 CCCC 消息 | +| `/unsubscribe` | 停止接收消息 | +| `/send <消息>` | 发送给 foreman（默认） | +| `/send @ <消息>` | 发送给指定 agent | +| `/send @all <消息>` | 发送给所有 agent | +| `/send @peers <消息>` | 发送给非 foreman 的 agent | +| `/status` | 显示工作组和 agent 状态 | +| `/pause` | 暂停消息投递 | +| `/resume` | 恢复消息投递 | +| `/verbose` | 切换详细模式（查看所有 agent 消息） | +| `/help` | 显示可用命令 | + +## 故障排除 + +### "Invalid app_id" 错误 + +1. 在飞书开放平台验证你的 App ID +2. 检查环境变量是否设置正确 +3. 确保应用已发布且审批通过 + +### "Permission denied" 错误 + +1. 进入 **权限管理** +2. 添加缺失的权限 +3. 提交新版本进行审批 + +### 机器人无法接收消息 + +1. 检查事件订阅是否已配置 +2. 验证应用是否已安装到聊天中 +3. 确保应用版本已发布 +4. 确保 CCCC IM Bridge 正在运行 + +### Token 过期 + +CCCC 会自动刷新 token，但如果问题持续： + +```bash +cccc im stop +cccc im start +``` + +## 高级配置 + +CCCC 目前支持： + +- 通过 REST API 发送消息 +- 通过长连接接收消息（Python `lark-oapi`） + +Webhook 回调（开发者服务器 URL）、消息卡片和加密设置目前不通过 CCCC 配置。 + +## 安全注意事项 + +- 将凭据存储在环境变量或密钥管理器中 +- 使用最小必要权限 +- 定期审查应用访问权限 +- 为敏感通信启用平台加密（可选） +- 通过飞书管理后台审计应用使用情况 diff --git a/docs/zh/guide/im-bridge/index.md b/docs/zh/guide/im-bridge/index.md new file mode 100644 index 00000000..07250184 --- /dev/null +++ b/docs/zh/guide/im-bridge/index.md @@ -0,0 +1,79 @@ +# IM Bridge 概览 + +将你的 CCCC 工作组桥接到主流 IM 平台，实现移动端访问。 + +## 什么是 IM Bridge？ + +IM Bridge 允许你： + +- 从手机向 Agent 发送消息 +- 接收更新和通知 +- 通过斜杠命令控制工作组 +- 分享文件和附件 + +## 支持的平台 + +| 平台 | 状态 | 最适合 | +|------|------|--------| +| [Telegram](./telegram) | ✅ | 个人使用，快速设置 | +| [Slack](./slack) | ✅ | 团队协作 | +| [Discord](./discord) | ✅ | 社区/游戏 | +| [飞书/Lark](./feishu) | ✅ | 企业（中国/全球） | +| [钉钉](./dingtalk) | ✅ | 企业（中国） | + +## 设计原则 + +- **1 个工作组 = 1 个 Bot**：每个工作组连接一个 bot 实例，保持简洁和隔离 +- **显式订阅**：用户必须先 `/subscribe` 才能接收消息 +- **轻量端口**：IM Bridge 仅转发消息；Daemon 是唯一的真实来源 + +## 通用命令 + +订阅任何平台后，以下命令通用： + +| 命令 | 描述 | +|------|------| +| `/send <消息>` | 发送给 foreman（默认） | +| `/send @ <消息>` | 发送给指定 actor | +| `/send @all <消息>` | 发送给所有 agent | +| `/send @peers <消息>` | 发送给非 foreman 的 agent | +| `/subscribe` | 开始接收消息 | +| `/unsubscribe` | 停止接收消息 | +| `/status` | 显示工作组状态 | +| `/pause` | 暂停消息投递 | +| `/resume` | 恢复消息投递 | +| `/verbose` | 切换详细模式 | +| `/help` | 显示帮助 | + +::: tip 隐式发送 +在所有平台上，@提及 bot（在群聊中）或直接发送纯文本消息会自动视为 `/send` 给 **foreman**。你只需要在指定其他 agent 时使用显式的 `/send` 命令。 +::: + +## CLI 命令 + +```bash +# 配置（平台特定，请参见各平台指南） +cccc im set --token-env + +# 控制 +cccc im start # 启动 IM Bridge +cccc im stop # 停止 IM Bridge +cccc im status # 检查 Bridge 状态 +cccc im logs # 查看日志 +cccc im logs -f # 实时跟踪日志 +``` + +## 快速开始 + +1. 从上方列表中选择一个平台 +2. 按照设置指南创建 bot +3. 使用 bot 凭据配置 CCCC +4. 启动 Bridge 并在聊天中订阅 + +## 下一步 + +- [Telegram 设置](./telegram) - 快速个人设置 +- [Slack 设置](./slack) - 团队协作 +- [Discord 设置](./discord) - 社区访问 +- [飞书/Lark 设置](./feishu) - 企业（中国/全球） +- [钉钉设置](./dingtalk) - 企业（中国） diff --git a/docs/zh/guide/im-bridge/slack.md b/docs/zh/guide/im-bridge/slack.md new file mode 100644 index 00000000..4076f0d0 --- /dev/null +++ b/docs/zh/guide/im-bridge/slack.md @@ -0,0 +1,273 @@ +# Slack 设置 + +将你的 CCCC 工作组连接到 Slack，实现团队协作。 + +## 概览 + +Slack 集成使用 Socket Mode 进行实时消息传递，适合： + +- 团队协作 +- 企业环境 +- 已有 Slack 工作区的团队 + +## 前提条件 + +- 一个拥有管理员权限的 Slack 工作区 +- CCCC 已安装并运行 + +## 第一步：创建 Slack App + +1. 前往 [Slack API Apps](https://api.slack.com/apps) +2. 点击 **Create New App** +3. 选择 **From scratch** +4. 输入应用名称（例如 "CCCC Bot"） +5. 选择你的工作区 +6. 点击 **Create App** + +## 第二步：启用 Socket Mode + +Socket Mode 允许 bot 无需暴露公开 URL 即可接收事件。 + +1. 在应用设置中，进入 **Socket Mode** +2. 将 **Enable Socket Mode** 切换为 ON +3. 点击 **Generate** 创建应用级 token +4. 为其命名（例如 "cccc-socket-token"） +5. 添加权限范围 `connections:write` +6. 点击 **Generate** +7. **复制 token**（以 `xapp-` 开头） + +::: tip +这是你的 App Token，用于 WebSocket 连接。 +::: + +## 第三步：配置 Bot 权限 + +1. 进入 **OAuth & Permissions** +2. 在 **Scopes** → **Bot Token Scopes** 下添加： + +| 权限范围 | 用途 | +|----------|------| +| `chat:write` | 发送消息 | +| `channels:history` | 读取公共频道消息 | +| `groups:history` | 读取私有频道消息 | +| `im:history` | 读取私信 | +| `mpim:history` | 读取群组私信 | +| `files:read` | 读取共享文件 | +| `files:write` | 上传文件 | +| `users:read` | 读取用户信息 | + +## 第四步：启用事件订阅 + +1. 进入 **Event Subscriptions** +2. 将 **Enable Events** 切换为 ON +3. 在 **Subscribe to bot events** 下添加： + +| 事件 | 用途 | +|------|------| +| `message.channels` | 公共频道的消息 | +| `message.groups` | 私有频道的消息 | +| `message.im` | 私信 | +| `message.mpim` | 群组私信 | +| `app_mention` | bot 被 @提及时 | + +4. 点击 **Save Changes** + +## 第五步：安装到工作区 + +1. 进入 **OAuth & Permissions** +2. 点击 **Install to Workspace** +3. 审查权限并点击 **Allow** +4. **复制 Bot Token**（以 `xoxb-` 开头） + +## 第六步：设置环境变量 + +```bash +# 添加到你的 shell 配置文件 +export SLACK_BOT_TOKEN="xoxb-your-bot-token" +export SLACK_APP_TOKEN="xapp-your-app-token" +``` + +::: warning 需要两个 Token +Slack 需要两个 token： +- **Bot Token**（`xoxb-`）：用于 API 调用 +- **App Token**（`xapp-`）：用于 Socket Mode 连接 +::: + +## 第七步：配置 CCCC + +### 选项 A：通过 Web UI + +1. 打开 CCCC Web UI：`http://127.0.0.1:8848/` +2. 进入 **设置**（顶栏的齿轮图标） +3. 导航到 **IM Bridge** 部分 +4. 选择 **Slack** 作为平台 +5. 输入你的凭据： + - **Bot Token 环境变量**：`SLACK_BOT_TOKEN` + - **App Token 环境变量**：`SLACK_APP_TOKEN` +6. 点击 **保存** + +### 选项 B：通过 CLI + +```bash +cccc im set slack \ + --bot-token-env SLACK_BOT_TOKEN \ + --app-token-env SLACK_APP_TOKEN +``` + +两种方式都会保存到 `group.yaml`： + +```yaml +im: + platform: slack + bot_token_env: SLACK_BOT_TOKEN + app_token_env: SLACK_APP_TOKEN +``` + +## 第八步：启动 Bridge + +```bash +cccc im start +``` + +## 第九步：在 Slack 中订阅 + +1. 邀请 bot 到频道： + ``` + /invite @your-bot-name + ``` +2. 在频道中发送 `/subscribe` +3. 你应该会收到确认消息 + +私信方式： +1. 在私信中找到 bot +2. 发送 `/subscribe` + +## 使用方法 + +### 向 Agent 发送消息 + +在频道中，先 @提及 bot，然后使用 `/send` 命令： + +``` +@YourBotName /send 请实现用户认证模块 +``` + +在与 bot 的私信中，可以直接使用 `/send`： + +``` +/send 请实现用户认证模块 +``` + +::: warning 注意 +- 在频道中，必须先 @提及 bot 才能路由消息 +- @提及 bot 后，纯文本会被视为隐式发送给 foreman +- 需要指定 `@all` 或 `@peers` 等收件人时使用 `/send` +::: + +### 指定特定 Agent + +使用 `@提及` 语法配合 `/send` 命令（使用 CCCC 的语法，而非 Slack 的）： + +``` +/send @foreman 审查最新的提交 +/send @backend-agent 修复 API 端点 +/send @all 请更新一下状态 +``` + +### 接收消息 + +订阅后，你会自动收到： +- Agent 的回复 +- 状态更新 +- 错误通知 + +使用 `/verbose` 切换是否接收 agent 之间的消息。 + +### 线程回复 + +在线程中回复以保持对话有序。CCCC 会保留线程上下文。 + +### 文件分享 + +在消息中附加文件。文件会上传到 CCCC 的 blob 存储中，然后转发给 agent。 + +## 命令参考 + +| 命令 | 描述 | +|------|------| +| `/subscribe` | 开始接收 CCCC 消息 | +| `/unsubscribe` | 停止接收消息 | +| `/send <消息>` | 发送给 foreman（默认） | +| `/send @ <消息>` | 发送给指定 agent | +| `/send @all <消息>` | 发送给所有 agent | +| `/send @peers <消息>` | 发送给非 foreman 的 agent | +| `/status` | 显示工作组和 agent 状态 | +| `/pause` | 暂停投递 | +| `/resume` | 恢复投递 | +| `/verbose` | 切换详细模式 | +| `/help` | 显示帮助 | + +## 故障排除 + +### "invalid_auth" 错误 + +Token 无效或已过期： + +1. 进入 **OAuth & Permissions** +2. 点击 **Reinstall to Workspace** +3. 更新 `SLACK_BOT_TOKEN` 环境变量 + +### "missing_scope" 错误 + +添加所需的权限范围： + +1. 进入 **OAuth & Permissions** +2. 在 **Bot Token Scopes** 下添加缺失的范围 +3. 重新安装应用 + +### Bot 无法接收消息 + +1. 检查 Socket Mode 是否已启用 +2. 验证 `SLACK_APP_TOKEN` 是否正确 +3. 确保在 **Event Subscriptions** 中已订阅事件 +4. 检查 bot 是否已被邀请到频道 + +### 连接断开 + +Socket Mode 连接可能偶尔断开。CCCC 会自动重连，但如果问题持续： + +```bash +cccc im stop +cccc im start +``` + +## 高级配置 + +### 频道限制 + +限制 bot 响应的频道： + +```yaml +im: + platform: slack + bot_token_env: SLACK_BOT_TOKEN + app_token_env: SLACK_APP_TOKEN + allowed_channels: + - C01234567 # 频道 ID + - C89012345 +``` + +### 自定义 Bot 名称 + +显示名称在 Slack 中设置： + +1. 进入 **App Home** +2. 在 **Your App's Presence in Slack** 下 +3. 编辑 **Display Name** + +## 安全注意事项 + +- Bot token 拥有广泛的访问权限 — 限制在必要的工作区 +- 定期审查频道成员 +- 考虑使用 Enterprise Grid 以获得额外控制 +- 审计谁可以在你的工作区安装应用 diff --git a/docs/zh/guide/im-bridge/telegram.md b/docs/zh/guide/im-bridge/telegram.md new file mode 100644 index 00000000..84ce96ab --- /dev/null +++ b/docs/zh/guide/im-bridge/telegram.md @@ -0,0 +1,222 @@ +# Telegram 设置 + +将你的 CCCC 工作组连接到 Telegram，实现移动端访问。 + +## 概览 + +Telegram 是最容易设置的平台，适合： + +- 个人使用 +- 快速原型验证 +- 独立开发者 + +## 前提条件 + +- 一个 Telegram 账号 +- CCCC 已安装并运行 + +## 第一步：创建 Bot + +1. 打开 Telegram，搜索 `@BotFather` +2. 开始聊天并发送 `/newbot` +3. 按提示操作： + - 选择显示名称（例如 "My CCCC Bot"） + - 选择用户名（必须以 `bot` 结尾，例如 `my_cccc_bot`） +4. BotFather 会给你一个 token，类似： + ``` + 123456789:ABCdefGHIjklMNOpqrsTUVwxyz + ``` +5. **保存此 token** — 下一步会用到 + +::: tip 推荐：关闭群组隐私模式 +如果你打算在群聊中使用 bot，请关闭群组隐私模式，让 bot 能看到所有消息： + +1. 向 BotFather 发送 `/mybots` +2. 选择你的 bot → **Bot Settings** → **Group Privacy** +3. 设置为 **Disabled** +::: + +## 第二步：配置 CCCC + +### 选项 A：通过 Web UI（推荐） + +1. 打开 CCCC Web UI：`http://127.0.0.1:8848/` +2. 进入 **设置**（顶栏的齿轮图标） +3. 导航到 **IM Bridge** 标签页 +4. 选择 **Telegram** 作为平台 +5. 输入你的 bot token： + - 直接粘贴 token（例如 `123456789:ABCdefGHIjklMNOpqrsTUVwxyz`） + - 或输入环境变量名（例如 `TELEGRAM_BOT_TOKEN`） +6. 点击 **保存配置** + +![CCCC IM Bridge 配置](/images/cccc-im-bridge-telegram.png) + +::: tip 安全最佳实践 +在生产环境中，请将 token 存储在环境变量中，而非直接粘贴： + +```bash +# 添加到你的 shell 配置文件（~/.bashrc、~/.zshrc 等） +export TELEGRAM_BOT_TOKEN="your-token-here" +``` + +然后在 Web UI 中输入 `TELEGRAM_BOT_TOKEN`。永远不要将 token 提交到 git。 +::: + +### 选项 B：通过 CLI + +```bash +# 使用环境变量名 +cccc im set telegram --token-env TELEGRAM_BOT_TOKEN + +# 验证配置 +cccc im config +``` + +两种方式都会保存配置到工作组的 `group.yaml`： + +```yaml +im: + platform: telegram + token_env: TELEGRAM_BOT_TOKEN +``` + +## 第三步：启动 Bridge 并订阅 + +### 启动 Bridge + +**通过 Web UI**：点击 **保存配置** — Bridge 会自动启动并显示 **运行中** 状态。 + +**通过 CLI**： + +```bash +cccc im start +``` + +验证是否运行中： + +```bash +cccc im status +``` + +### 在 Telegram 中订阅 + +1. 打开 Telegram，找到你的 bot（按用户名搜索） +2. 开始与 bot 聊天 +3. 发送 `/subscribe` +4. 你应该会收到确认消息 + +在群聊中： +1. 将 bot 添加到群组 +2. 在群组中发送 `/subscribe` +3. 所有已订阅的聊天都会收到 CCCC 的消息 + +## 使用方法 + +### 向 Agent 发送消息 + +Telegram 支持两种发送消息的方式： + +**在群聊中** — @提及 bot 并直接输入消息： + +``` +@YourBotName 请实现登录功能 +``` + +或使用显式的 `/send` 命令： + +``` +@YourBotName /send @all 请更新一下状态 +``` + +**在私聊中** — 直接输入消息： + +``` +请实现登录功能 +``` + +::: tip 隐式发送 +当你 @提及 bot（在群聊中）或发送私聊消息时，纯文本会自动视为 `/send` 给 foreman。你只需要在指定其他 agent（如 `@all` 或 `@peers`）时使用显式的 `/send` 命令。 +::: + +### 指定特定 Agent + +使用 `@提及` 语法配合 `/send` 命令： + +``` +/send @foreman 请审查这个 PR +/send @peer-1 运行测试 +/send @all 请更新一下状态 +``` + +### 接收消息 + +订阅后，你会自动收到： +- Agent 的回复 +- 状态更新 +- 错误通知 + +使用 `/verbose` 切换是否接收 agent 之间的消息。 + +### 文件附件 + +在消息中附加文件。文件会被下载并存储到 CCCC 的 blob 存储中，然后转发给 agent。 + +## 命令参考 + +| 命令 | 描述 | +|------|------| +| `/subscribe` | 开始接收 CCCC 消息 | +| `/unsubscribe` | 停止接收消息 | +| `/send <消息>` | 发送给 foreman（默认） | +| `/send @ <消息>` | 发送给指定 agent | +| `/send @all <消息>` | 发送给所有 agent | +| `/send @peers <消息>` | 发送给非 foreman 的 agent | +| `/status` | 显示工作组和 agent 状态 | +| `/pause` | 暂停消息投递 | +| `/resume` | 恢复消息投递 | +| `/verbose` | 切换详细模式（查看所有 agent 消息） | +| `/help` | 显示可用命令 | + +## 故障排除 + +### Bot 没有响应 + +1. 检查 Bridge 是否运行中： + ```bash + cccc im status + ``` + +2. 查看日志中的错误： + ```bash + cccc im logs -f + ``` + +3. 验证 token 是否正确 — 在 BotFather 中重新检查（`/mybots` → 选择 bot → **API Token**） + +### "Unauthorized" 错误 + +你的 token 无效。从 BotFather 获取新的 token： + +1. 向 BotFather 发送 `/mybots` +2. 选择你的 bot +3. 点击 **API Token** → **Revoke current token** +4. 在 CCCC 设置（Web UI）或环境变量中更新 token + +### 消息未投递 + +1. 确保已发送 `/subscribe` +2. 检查 CCCC Daemon 是否在运行 +3. 在 Web UI 中或通过 `cccc im status` 验证 Bridge 状态 + +### 频率限制 + +Telegram 有频率限制。如果你发送了很多消息： +- 消息可能会延迟 +- 考虑使用 `/verbose` 关闭详细模式以减少流量 + +## 安全注意事项 + +- 保管好你的 bot token +- 考虑为你的 Telegram 账号启用两步验证 +- 审查谁可以访问 bot 所在的聊天 +- Bot 可以看到它所在群组中的所有消息 diff --git a/docs/zh/guide/index.md b/docs/zh/guide/index.md new file mode 100644 index 00000000..c57d7121 --- /dev/null +++ b/docs/zh/guide/index.md @@ -0,0 +1,33 @@ +# 指南 + +根据你的角色和目标选择合适的章节。 + +## 如果你是 CCCC 新手 + +- [快速上手](/zh/guide/getting-started/) — 10 分钟完成首次设置 +- [Web UI 快速上手](/zh/guide/getting-started/web) — 偏好可视化操作 +- [CLI 快速上手](/zh/guide/getting-started/cli) — 偏好终端优先的工作流 + +## 如果你需要高投入产出比的实践模式 + +- [使用场景](/zh/guide/use-cases) — 生产级协作场景 +- [工作流](/zh/guide/workflows) — 常见执行模式 +- [最佳实践](/zh/guide/best-practices) — 稳定协作行为准则 + +## 如果你在日常工作中运维 CCCC + +- [运维手册](/zh/guide/operations) — 排障、恢复与升级流程 +- [Web UI 指南](/zh/guide/web-ui) — 控制面板操作说明 +- [IM Bridge](/zh/guide/im-bridge/) — 移动端/远程运维 + +## 如果你需要排障 + +- [常见问题](/zh/guide/faq) + +## 核心概念（简版） + +- **Working Group（工作组）**：带持久化历史的协作单元 +- **Actor（执行者）**：Agent 运行时会话（foreman/peer） +- **Scope（作用域）**：关联到工作组的目录上下文 +- **Ledger（账本）**：只追加的协作事件流 +- **Daemon（守护进程）**：单写入者，运维事实的唯一来源 diff --git a/docs/zh/guide/operations.md b/docs/zh/guide/operations.md new file mode 100644 index 00000000..4b108742 --- /dev/null +++ b/docs/zh/guide/operations.md @@ -0,0 +1,152 @@ +# 运维手册 + +本页面面向需要日常可靠运行 CCCC 的运维人员。 + +## 1) 运行时拓扑 + +默认运行时主目录： +- `CCCC_HOME=~/.cccc` + +关键路径： +- `~/.cccc/registry.json` +- `~/.cccc/daemon/ccccd.sock` +- `~/.cccc/daemon/ccccd.log` +- `~/.cccc/groups//group.yaml` +- `~/.cccc/groups//ledger.jsonl` + +## 2) 启动与健康检查 + +### 启动 + +```bash +cccc +``` + +### 健康基线 + +```bash +cccc doctor +cccc daemon status +cccc groups +``` + +预期结果： +- Daemon 可达 +- 运行时已检测到 +- 活跃的工作组列表可加载 + +## 3) 故障排查顺序 + +当工作组出现卡顿时： + +1. 检查 Daemon 健康状态。 +2. 检查工作组状态（`active/idle/paused/stopped`）。 +3. 检查 Actor 运行时状态。 +4. 检查消息义务（reply-required / attention 确认）。 +5. 检查自动化和投递节流。 + +常用命令： + +```bash +cccc daemon status +cccc actor list +cccc inbox --actor-id +cccc tail -n 100 -f +``` + +## 4) 快速恢复手册 + +### Actor 级恢复（首选） + +```bash +cccc actor restart +``` + +在工作组级重启之前，优先使用此方式。 + +### 工作组级恢复 + +```bash +cccc group stop +cccc group start +``` + +### Daemon 级恢复（最后手段） + +```bash +cccc daemon stop +cccc daemon start +``` + +## 5) 安全远程访问 + +基本要求： +- 设置 `CCCC_WEB_TOKEN`。 +- 使用 Cloudflare Access 或 Tailscale 作为网络边界。 + +禁止操作： +- 不要在没有访问网关的情况下直接暴露 Web UI。 +- 不要将密钥存储在代码仓库文件中。 + +## 6) 升级手册（RC 安全） + +### 升级前 + +1. 停止活跃的高风险会话。 +2. 备份 `CCCC_HOME`。 +3. 记录当前版本和基本运行状态。 + +### 升级 + +```bash +python -m pip install -U cccc-pair +``` + +### 升级后 + +```bash +cccc doctor +cccc daemon status +cccc mcp +``` + +进行一次小型端到端冒烟测试： +- 创建/加入工作组 +- 添加/启动 Actor +- 发送/回复消息 +- 验证 Ledger 和收件箱行为 + +## 7) 备份与恢复 + +### 备份（最小化） + +备份 `CCCC_HOME`： +- 注册表 +- Daemon 日志（可选） +- 所有工作组（`group.yaml`、Ledger、状态） + +### 恢复 + +1. 停止 Daemon。 +2. 恢复 `CCCC_HOME` 目录。 +3. 启动 Daemon 并通过 `cccc doctor` 验证。 + +## 8) 运维准则 + +- 保持单一信息源：决策应记录在 CCCC 消息中。 +- 对关键请求使用 `reply_required`。 +- 当范围明确时，优先使用指定收件人，而非广播。 +- 保持自动化聚焦于客观提醒，而非聊天噪音。 + +## 9) 升级处理清单 + +如果问题反复出现： + +1. 收集证据： + - 工作组 ID + - Actor ID + - 事件 ID + - 最近的 `cccc tail -n 100` +2. 记录可复现的操作序列。 +3. 划分严重级别（`P0/P1/P2`）。 +4. 在发布记录中登记修复或风险。 diff --git a/docs/zh/guide/use-cases.md b/docs/zh/guide/use-cases.md new file mode 100644 index 00000000..62986686 --- /dev/null +++ b/docs/zh/guide/use-cases.md @@ -0,0 +1,157 @@ +# 使用场景 + +本页聚焦高投入产出比的真实 CCCC 工作流。 + +## 如何阅读本页 + +每个场景包含： +- 目标 +- 最小化配置 +- 执行流程 +- 成功标准 +- 常见失败点 + +## 场景 1：Builder + Reviewer 配对 + +### 目标 + +在不增加人工评审瓶颈的情况下提升交付质量。 + +### 最小化配置 + +```bash +cd /path/to/repo +cccc attach . +cccc setup --runtime claude +cccc setup --runtime codex +cccc actor add builder --runtime claude +cccc actor add reviewer --runtime codex +cccc group start +``` + +### 执行流程 + +1. 向 `@builder` 发送实现任务。 +2. 向 `@reviewer` 发送评审标准（Bug 风险、回归风险、测试）。 +3. 要求 `@builder` 回复变更文件列表 + 理由。 +4. 要求 `@reviewer` 回复发现（严重程度 + 证据）。 +5. 由人类做出最终合并决策。 + +### 成功标准 + +- 更快的实现反馈循环。 +- 更少的遗漏回归。 +- 评审输出是可操作的，而非泛泛而谈。 + +### 常见失败点 + +- 任务范围过大。 +- 评审缺乏明确的验收标准。 +- 团队在关键请求中跳过义务语义（`reply_required`）。 + +## 场景 2：Foreman 主导的多 Agent 交付 + +### 目标 + +将一个中型项目拆分为并行轨道，同时保持对齐。 + +### 最小化配置 + +```bash +cccc actor add foreman --runtime claude +cccc actor add frontend --runtime codex +cccc actor add backend --runtime gemini +cccc actor add qa --runtime copilot +cccc group start +``` + +### 执行流程 + +1. Foreman 在 Context 中定义共享目标（`vision`、`sketch`、`milestones`）。 +2. 通过定向接收者分配聚焦任务。 +3. 通过自动化规则强制检查点提醒。 +4. Foreman 整合并解决冲突。 +5. QA Agent 在交付前验证关键验收标准。 + +### 成功标准 + +- 并行执行，无重大返工。 +- 每条轨道有清晰的所有权。 +- 决策历史可在 Ledger 中追溯。 + +### 常见失败点 + +- 缺少共享的架构基线。 +- Agent 在没有所有权规则的情况下编辑同一区域。 +- 没有明确的集成检查点。 + +## 场景 3：通过 IM Bridge 移动运维 + +### 目标 + +通过手机操作长期运行的工作组，同时保持可靠的审计追踪。 + +### 最小化配置 + +```bash +cccc im set telegram --token-env TELEGRAM_BOT_TOKEN +cccc im start +``` + +然后在 IM 聊天中执行 `/subscribe`。 + +### 执行流程 + +1. 在 IM 中接收进度/错误通知。 +2. 从手机向 `@foreman` 发送升级命令。 +3. 仅在需要深度调试时切换到 Web UI。 +4. 将所有关键决策保留在 CCCC 消息中（不仅仅是 IM 聊天记录）。 + +### 成功标准 + +- 无需笔记本电脑即可介入。 +- 关键上下文保留在 Ledger 中。 +- 减少通宵或外勤运维的停机时间。 + +### 常见失败点 + +- 暴露 Web UI 时未设置 Token/网关。 +- 将 IM 作为唯一的事实来源。 +- 没有重启/恢复预案。 + +## 场景 4：可重复的 Agent 基准测试框架 + +### 目标 + +运行可比较的多 Agent 会话，具备稳定的日志记录和可重放性。 + +### 最小化配置 + +1. 定义固定的任务提示和评估标准。 +2. 每次运行使用相同的工作组模板和运行时配置。 +3. 保持自动化策略的确定性。 + +### 执行流程 + +1. 创建基准工作组/模板。 +2. 使用不同的运行时组合运行多次会话。 +3. 收集 Ledger 和终端证据。 +4. 评估结果质量和运维稳定性。 + +### 成功标准 + +- 可比较的运行，配置差异小。 +- 可复现的证据集（`ledger`、状态产物、日志）。 +- 清晰的模型/运行时权衡信号。 + +### 常见失败点 + +- 运行之间存在隐性 Prompt 漂移。 +- 未受控的环境差异。 +- 消息中缺少运行元数据。 + +## 推荐阅读 + +- [运维手册](/zh/guide/operations) +- [定位](/zh/reference/positioning) +- [功能特性](/zh/reference/features) diff --git a/docs/zh/guide/web-ui.md b/docs/zh/guide/web-ui.md new file mode 100644 index 00000000..e992fbd2 --- /dev/null +++ b/docs/zh/guide/web-ui.md @@ -0,0 +1,173 @@ +# Web UI 指南 + +CCCC Web UI 是一个移动优先的控制面板，用于管理你的 AI Agent。 + +## 访问 Web UI + +启动 CCCC 后： + +```bash +cccc +``` + +在浏览器中打开 http://127.0.0.1:8848/。 + +## 界面概览 + +Web UI 包含以下主要区域： + +- **顶栏**：工作组选择器、设置、主题切换 +- **侧边栏**：工作组列表和导航 +- **标签页**：Chat 标签 + 每个 Agent 一个标签 +- **主区域**：聊天消息或终端视图 +- **输入框**：支持 @mention 的消息编辑器 + +## 管理工作组 + +### 创建工作组 + +1. 点击侧边栏的 **+** 按钮 +2. 或使用 CLI：`cccc attach /path/to/project` + +### 切换工作组 + +在侧边栏点击工作组即可切换。 + +### 工作组设置 + +1. 点击顶部的 **设置** 图标 +2. 可配置： + - 工作组标题 + - 引导文本（preamble/help） + - 自动化规则和引擎策略 + - 消息投递和默认设置 + - IM Bridge 设置 + +## 管理 Agent + +### 添加 Agent + +1. 点击 **Add Actor** 按钮 +2. 选择运行时（Claude、Codex 等） +3. 设置 Actor ID 和选项 +4. 点击 **Create** + +### 启动/停止 Agent + +- 点击 **Play** 按钮启动 Agent +- 点击 **Stop** 按钮停止 +- 使用 **Restart** 清除上下文并重启 + +### 查看 Agent 终端 + +点击 Agent 的标签页查看终端输出。 + +## 消息 + +### 发送消息 + +1. 在底部输入框中输入 +2. 按 `Ctrl+Enter` / `Cmd+Enter`，或点击发送 + +### @提及 + +输入 `@` 触发自动补全： + +- `@all` — 发送给所有 Agent +- `@foreman` — 发送给 Foreman +- `@peers` — 发送给所有 Peer +- `@` — 发送给特定 Agent + +### 回复 + +点击消息上的回复图标进行引用回复。 + +## Context 面板 + +Context 面板展示共享的项目状态： + +### Vision + +一句话项目目标。Agent 应与此对齐。 + +### Sketch + +执行计划或架构草图。静态内容，不含 TODO。 + +### Milestones（里程碑） + +粗粒度的项目阶段（通常 2-6 个）。 + +### Tasks（任务） + +带步骤和验收标准的详细工作项。 + +### Notes（笔记） + +经验教训、发现、警告。 + +### References（参考） + +有用的文件和 URL。 + +## 设置面板 + +通过齿轮图标访问： + +### 自动化 + +- **规则**：创建基于间隔 / 循环计划 / 一次性计划的提醒。 +- **动作**： + - `Send Reminder`（常规提醒投递） + - `Set Group Status`（运维操作，仅一次性） + - `Control Actor Runtimes`（运维操作，仅一次性） +- **一次性行为**：一次性规则触发后自动完成，可从已完成列表中清理。 +- **引擎策略**：配置内置推送（reply-required、attention ACK、unread）、Actor 空闲、keepalive、静默和帮助推送。 + +### IM Bridge + +配置 Telegram、Slack、Discord、飞书或钉钉集成。 + +### 主题 + +在浅色、深色或跟随系统主题间切换。 + +## 移动端使用 + +Web UI 响应式设计，在移动端表现良好： + +- 滑动切换标签页 +- 下拉刷新 +- 长按弹出上下文菜单 +- 支持移动浏览器（Chrome、Safari） + +## 远程访问 + +从局域网外部访问： + +### Cloudflare Tunnel（推荐） + +```bash +cloudflared tunnel --url http://127.0.0.1:8848 +``` + +### Tailscale + +```bash +CCCC_WEB_HOST=$(tailscale ip -4) cccc +``` + +### 安全 + +暴露 Web UI 时务必设置 `CCCC_WEB_TOKEN`： + +```bash +export CCCC_WEB_TOKEN="your-secret-token" +cccc +``` + +然后认证一次以建立会话 Cookie： + +- 打开 `http://YOUR_HOST:8848/?token=your-secret-token`（或 `.../ui/?token=...`） + +之后即可正常使用 Web UI，无需 `?token=...`。 diff --git a/docs/zh/guide/workflows.md b/docs/zh/guide/workflows.md new file mode 100644 index 00000000..b984e098 --- /dev/null +++ b/docs/zh/guide/workflows.md @@ -0,0 +1,138 @@ +# 工作流示例 + +使用 CCCC 协调 AI Agent 的常见模式。 + +## 单人开发 + 单 Agent + +最简配置：一个 Agent 辅助你开发。 + +### 配置 + +```bash +cd /your/project +cccc attach . +cccc actor add assistant --runtime claude +cccc +``` + +### 工作流 + +1. 打开 Web UI：http://127.0.0.1:8848/ +2. 启动 Agent +3. 通过聊天发送任务："实现登录功能" +4. 在终端标签页中观察 Agent 工作 +5. 审查变更并提供反馈 + +## 双 Agent 配对编程 + +一个 Agent 负责实现，另一个负责评审。 + +### 配置 + +```bash +cccc actor add implementer --runtime claude +cccc actor add reviewer --runtime codex +cccc group start +``` + +### 工作流 + +1. 向 `@implementer` 发送实现任务 +2. 完成后，让 `@reviewer` 评审代码 +3. 根据评审反馈迭代 + +### 技巧 + +- 评审者可以发现 Bug 并提出改进建议 +- 使用不同的运行时获得多样化视角 +- 保持任务聚焦且具体 + +## 多 Agent 团队 + +复杂项目可使用多个专业化 Agent。 + +### 配置示例 + +```bash +cccc actor add architect --runtime claude # 架构决策 +cccc actor add frontend --runtime codex # UI 实现 +cccc actor add backend --runtime droid # API 实现 +cccc actor add tester --runtime copilot # 测试 +``` + +### 协调 + +- 第一个启用的 Actor（architect）成为 Foreman +- Foreman 协调各 Peer 的工作 +- 使用 @mention 将任务定向到特定 Agent +- 使用 Context 面板维护共享理解 + +### 最佳实践 + +- 为每个 Agent 定义清晰的职责 +- 使用里程碑跟踪进度 +- 定期检查以确保对齐 + +## 通过手机远程监控 + +随时随地监控和控制你的 Agent。 + +### 配置方式 + +**方式 1：Cloudflare Tunnel（推荐）** + +```bash +# 快速方式（临时 URL） +cloudflared tunnel --url http://127.0.0.1:8848 + +# 稳定方式（自定义域名） +cloudflared tunnel create cccc +cloudflared tunnel route dns cccc cccc.yourdomain.com +cloudflared tunnel run cccc +``` + +**方式 2：IM Bridge** + +```bash +cccc im set telegram --token-env TELEGRAM_BOT_TOKEN +cccc im start +``` + +然后通过 Telegram 应用： +- 向 Agent 发送消息 +- 接收状态更新 +- 使用斜杠命令控制工作组 + +### 工作流 + +1. 设置远程访问 +2. 让 Agent 在开发机上持续运行 +3. 从手机监控和发送命令 +4. 接收重要事件通知 + +## 通宵任务 + +无人值守运行长时间任务。 + +### 配置 + +1. 定义明确的成功标准 +2. 设置 IM Bridge 用于通知 +3. 配置自动化超时 + +### 示例 + +```bash +# 配置通知 +cccc im set telegram --token-env TELEGRAM_BOT_TOKEN +cccc im start + +# 启动任务 +cccc send "请重构整个认证模块。每小时报告一次进度。" --to @foreman +``` + +### 监控 + +- IM Bridge 将更新推送到你的手机 +- 需要时通过 Web UI 查看进度 +- Agent 在完成或出错时发出通知 diff --git a/docs/zh/index.md b/docs/zh/index.md new file mode 100644 index 00000000..be5ade04 --- /dev/null +++ b/docs/zh/index.md @@ -0,0 +1,41 @@ +--- +layout: home + +hero: + name: CCCC + text: 多智能体协作内核 + tagline: 本地优先的控制平面，实现可靠的多智能体工程协作 + image: + src: /logo.svg + alt: CCCC + actions: + - theme: brand + text: 10 分钟快速上手 + link: /zh/guide/getting-started + - theme: alt + text: 高价值使用场景 + link: /zh/guide/use-cases + - theme: alt + text: SDK 集成 + link: /zh/sdk/ + +features: + - icon: "\U0001F916" + title: 多智能体运行时编排 + details: 在一个工作组中协调多个编码智能体，支持清晰的收件人语义和角色感知操作。 + - icon: "\U0001F4DD" + title: 持久化协作账本 + details: 每个事件都是仅追加且可重放的，便于调试、审计和恢复，不丢失上下文。 + - icon: "\U0001F310" + title: 统一控制平面 + details: Web UI、CLI、MCP 和 IM 桥接全部映射到同一个 Daemon 真实模型。 + - icon: "\U0001F4AC" + title: IM 级协作语义 + details: 支持 @路由、回复上下文、已读状态、关注确认和必须回复义务，实现可靠协调。 + - icon: "\U0001F527" + title: 自动化与运维 + details: 结合提醒、一次性运维操作和策略护栏，保持工作组持续运转。 + - icon: "\U0001F50C" + title: 远程就绪设计 + details: 桥接 Telegram、Slack、Discord、飞书和钉钉，支持移动运维和带外干预。 +--- diff --git a/docs/zh/reference/architecture.md b/docs/zh/reference/architecture.md new file mode 100644 index 00000000..e2ce74a8 --- /dev/null +++ b/docs/zh/reference/architecture.md @@ -0,0 +1,219 @@ +# 架构 + +> CCCC = Collaborative Code Coordination Center（协作代码协调中心） +> +> 全局 AI Agent 协作中枢：单一 daemon 管理多个工作组，Web/CLI/IM 作为入口。 + +## 核心概念 + +### 工作组（Working Group） + +- 类似 IM 群聊，但具备执行/投递能力 +- 每个工作组拥有一个追加写入的 ledger（事件流） +- 可绑定多个 Scope（项目目录） + +### Actor + +- **Foreman**：协调者 + 执行者（第一个启用的 actor 自动成为 foreman） +- **Peer**：独立专家（其他 actor） +- 支持 PTY（终端）和 Headless（仅 MCP）两种运行器 + +### Ledger + +- 唯一事实来源：`~/.cccc/groups//ledger.jsonl` +- 所有消息、事件和决策都记录在此 +- 支持快照/压缩 + +## 目录结构 + +默认：`CCCC_HOME=~/.cccc` + +``` +~/.cccc/ +├── registry.json # 工作组索引 +├── daemon/ +│ ├── ccccd.pid +│ ├── ccccd.log +│ └── ccccd.sock # IPC 套接字 +└── groups// + ├── group.yaml # 元数据 + ├── ledger.jsonl # 事件流（追加写入） + ├── context/ # 上下文（vision/sketch/tasks） + └── state/ # 运行时状态 + └── blobs/ # 大文本/附件（在 ledger 中引用） +``` + +## 架构分层 + +``` +┌─────────────────────────────────────────────────────────┐ +│ Ports（入口层） │ +│ Web UI (React) │ CLI │ IM Bridge │ MCP Server │ +├─────────────────────────────────────────────────────────┤ +│ Daemon (ccccd) │ +│ IPC Server │ Delivery │ Automation │ Runners │ +├─────────────────────────────────────────────────────────┤ +│ Kernel（内核层） │ +│ Group │ Actor │ Ledger │ Inbox │ Permissions │ +├─────────────────────────────────────────────────────────┤ +│ Contracts (v1) │ +│ Event │ Message │ Actor │ IPC │ +└─────────────────────────────────────────────────────────┘ +``` + +### 契约层（Contracts） + +- Pydantic 模型定义所有数据结构 +- 版本化：`src/cccc/contracts/v1/` +- 稳定边界，不含业务实现 + +### 内核层（Kernel） + +- Group/Scope/Ledger/Inbox/Permissions +- 依赖契约层，不依赖特定端口 + +### Daemon + +- 单写入者原则：所有 ledger 写入都经过 daemon +- IPC + 监督 + 投递/自动化 +- 管理 actor 生命周期 + +### 端口层（Ports） + +- 仅通过 IPC 与 daemon 交互 +- 不持有业务状态 + +## Ledger 模式（v1） + +### 事件信封 + +```jsonc +{ + "v": 1, + "id": "event-id", + "ts": "2025-01-01T00:00:00.000000Z", + "kind": "chat.message", + "group_id": "g_xxx", + "scope_key": "s_xxx", + "by": "user", + "data": {} +} +``` + +### 已知事件类型 + +| 类型 | 描述 | +|------|------| +| `group.create/update/attach/start/stop/set_state/settings_update/automation_update` | 工作组生命周期和配置 | +| `actor.add/update/start/stop/restart/remove` | Actor 生命周期 | +| `chat.message` | 聊天消息 | +| `chat.read` / `chat.ack` | 已读和确认事件 | +| `system.notify` / `system.notify_ack` | 系统通知和确认 | + +### chat.message 数据 + +```python +class ChatMessageData: + text: str + format: "plain" | "markdown" + to: list[str] # 接收者（空 = 广播） + reply_to: str | None # 回复哪条消息 + quote_text: str | None # 引用文本 + attachments: list[dict] # 附件元数据（内容存储在 CCCC_HOME blobs 中） +``` + +### 接收者语义（to 字段） + +| 标识 | 语义 | +|------|------| +| `[]`（空） | 广播 | +| `user` | 用户 | +| `@all` | 所有 actor | +| `@peers` | 所有 peer | +| `@foreman` | Foreman | +| `` | 特定 actor | + +## 文件和附件 + +### 设计原则 + +- **Ledger 只存引用，不存大二进制文件**：大文本/附件存放在 `CCCC_HOME` blobs 中（如 `groups//state/blobs/`）。 +- **默认不自动写入仓库**：附件属于运行时域（`CCCC_HOME`）；如需放入 scope/仓库，用户/agent 显式复制/导出。 +- **内容可移植**：附件使用 `sha256` 作为稳定标识，支持未来跨组/仓库复制和引用重写。 + +## 角色和权限 + +### 角色定义 + +- **Foreman = 协调者 + 执行者** + - 参与实际工作，不只是分配任务 + - 额外协调职责（接收 actor_idle、silence_check 通知） + - 可以添加/启动/停止任何 actor + +- **Peer = 独立专家** + - 拥有独立的专业判断 + - 可以质疑 foreman 的决策 + - 只能管理自己 + +### 权限矩阵 + +| 操作 | user | foreman | peer | +|------|------|---------|------| +| actor_add | ✓ | ✓ | ✗ | +| actor_start | ✓ | ✓（任意） | ✗ | +| actor_stop | ✓ | ✓（任意） | ✓（自己） | +| actor_restart | ✓ | ✓（任意） | ✓（自己） | +| actor_remove | ✓ | ✓（自己） | ✓（自己） | + +## MCP 服务器 + +MCP 以能力组的形式暴露（工具数量不硬编码）： + +### 协作控制（`cccc_*`） + +- 收件箱和引导：`cccc_inbox_*`、`cccc_bootstrap` +- 消息和文件：`cccc_message_*`、`cccc_file_send`、`cccc_blob_path` +- 工作组/actor 操作：`cccc_group_*`、`cccc_actor_*`、`cccc_runtime_list` +- 自动化：`cccc_automation_state`、`cccc_automation_manage` +- 项目/帮助信息：`cccc_project_info`、`cccc_help` + +### 上下文同步（`cccc_context_*` 及相关） + +- 上下文批量操作：`cccc_context_get`、`cccc_context_sync` +- 愿景/草图：`cccc_vision_update`、`cccc_sketch_update` +- 里程碑/任务：`cccc_milestone_*`、`cccc_task_*` +- 笔记/引用/在线状态：`cccc_note_*`、`cccc_reference_*`、`cccc_presence_*` + +### Headless 和通知 + +- Headless 运行器：`cccc_headless_*` +- 系统通知：`cccc_notify_*` + +### 诊断和终端记录 + +- 终端记录：`cccc_terminal_tail` +- 开发者诊断：`cccc_debug_*` + +## 技术栈 + +| 层级 | 技术 | +|------|------| +| Kernel/Daemon | Python + Pydantic | +| Web Port | FastAPI + Uvicorn | +| Web UI | React + TypeScript + Vite + Tailwind + xterm.js | +| MCP | stdio 模式，JSON-RPC | + +## 源码结构 + +``` +src/cccc/ +├── contracts/v1/ # 契约层 +├── kernel/ # 内核 +├── daemon/ # Daemon 进程 +├── runners/ # PTY/Headless 运行器 +├── ports/ +│ ├── web/ # Web 端口 +│ ├── im/ # IM Bridge +│ └── mcp/ # MCP 服务器 +└── resources/ # 内置资源 +``` diff --git a/docs/zh/reference/cli.md b/docs/zh/reference/cli.md new file mode 100644 index 00000000..b044ca33 --- /dev/null +++ b/docs/zh/reference/cli.md @@ -0,0 +1,225 @@ +# CLI 命令参考 + +CCCC CLI 完整命令参考。 + +## 全局命令 + +### `cccc` + +同时启动 daemon 和 Web UI。 + +```bash +cccc # 启动 daemon + Web UI +cccc --help # 显示帮助 +``` + +### `cccc doctor` + +检查环境并诊断问题。 + +```bash +cccc doctor # 完整环境检查 +``` + +### `cccc runtime list` + +列出可用的 Agent 运行时。 + +```bash +cccc runtime list # 列出已检测到的运行时 +cccc runtime list --all # 列出所有支持的运行时 +``` + +## Daemon 命令 + +### `cccc daemon` + +管理 CCCC daemon。 + +```bash +cccc daemon status # 检查 daemon 状态 +cccc daemon start # 启动 daemon +cccc daemon stop # 停止 daemon +``` + +注意： +- 如果 pid 文件对应的进程仍然存活但 IPC 无响应，`cccc daemon start` 会拒绝启动重复的 daemon。 +- 此时请先运行 `cccc daemon stop`（或清理过期的运行时状态）再重试启动。 + +## 工作组命令 + +### `cccc attach` + +创建或关联一个工作组。 + +```bash +cccc attach . # 将当前目录关联为 scope +cccc attach /path/to/project +``` + +### `cccc groups` + +列出所有工作组。 + +```bash +cccc groups # 列出工作组 +``` + +### `cccc use` + +切换到不同的工作组。 + +```bash +cccc use # 切换工作组 +``` + +### `cccc group` + +管理当前工作组。 + +```bash +cccc group create --title "my-group" # 创建工作组 +cccc group show # 显示工作组元数据 +cccc group update --group --title "..." # 更新标题/主题 +cccc group use . # 设置活跃 scope +cccc group start --group # 启动工作组的 actor +cccc group stop --group # 停止工作组的 actor +cccc group set-state idle --group # 设置状态：active/idle/paused/stopped +cccc group detach-scope --group +cccc group delete --group --confirm +``` + +## Actor 命令 + +### `cccc actor add` + +向工作组添加新的 actor。 + +```bash +cccc actor add --runtime claude +cccc actor add --runtime codex +cccc actor add --runtime custom --command "my-agent" +``` + +选项： +- `--runtime`：Agent 运行时（claude、codex、droid 等） +- `--command`：自定义命令（用于 custom 运行时） +- `--runner`：运行器类型（pty 或 headless） +- `--title`：显示标题 + +### `cccc actor` + +管理 actor。 + +```bash +cccc actor list # 列出 actor +cccc actor start # 启动 actor +cccc actor stop # 停止 actor +cccc actor restart # 重启 actor +cccc actor remove # 移除 actor +cccc actor update ... # 更新 actor 设置 +cccc actor secrets ... # 管理运行时专用密钥 +``` + +## 消息命令 + +### `cccc send` + +发送消息。 + +```bash +cccc send "Hello" # 不指定 --to：使用默认接收者策略（默认：foreman） +cccc send "Hello" --to @all # 显式广播 +cccc send "Hello" --to @foreman # 发送给 foreman +cccc send "Hello" --to peer-1 # 发送给特定 actor +``` + +### `cccc reply` + +回复消息。 + +```bash +cccc reply "Reply text" +``` + +### `cccc inbox` + +查看收件箱。 + +```bash +cccc inbox --actor-id # 查看 actor 未读消息 +cccc inbox --actor-id --mark-read +``` + +### `cccc tail` + +追踪 ledger。 + +```bash +cccc tail # 显示最近的事件 +cccc tail -n 50 # 显示最近 50 条事件 +cccc tail -f # 持续追踪新事件 +``` + +## IM Bridge 命令 + +### `cccc im` + +管理 IM Bridge。 + +```bash +cccc im set telegram --token-env TELEGRAM_BOT_TOKEN +cccc im set slack --bot-token-env SLACK_BOT_TOKEN --app-token-env SLACK_APP_TOKEN +cccc im set discord --token-env DISCORD_BOT_TOKEN +cccc im set feishu --app-key-env FEISHU_APP_ID --app-secret-env FEISHU_APP_SECRET +cccc im set dingtalk --app-key-env DINGTALK_APP_KEY --app-secret-env DINGTALK_APP_SECRET --robot-code-env DINGTALK_ROBOT_CODE + +cccc im start # 启动 IM bridge +cccc im stop # 停止 IM bridge +cccc im status # 检查 IM bridge 状态 +cccc im logs # 查看 IM bridge 日志 +cccc im logs -f # 持续追踪 IM bridge 日志 +``` + +## 安装配置命令 + +### `cccc setup` + +为 Agent 运行时配置 MCP。 + +```bash +cccc setup --runtime claude # 自动配置 Claude Code +cccc setup --runtime codex # 自动配置 Codex +cccc setup --runtime cursor # 打印手动配置说明 +``` + +## Web 命令 + +### `cccc web` + +仅启动 Web UI（需要 daemon 已运行）。 + +```bash +cccc web # 启动 Web UI +cccc web --port 9000 # 自定义端口 +``` + +## MCP 命令 + +### `cccc mcp` + +启动 MCP 服务器（用于 Agent 集成）。 + +```bash +cccc mcp # 启动 MCP 服务器（stdio 模式） +``` + +## 环境变量 + +| 变量 | 默认值 | 描述 | +|------|--------|------| +| `CCCC_HOME` | `~/.cccc` | 运行时主目录 | +| `CCCC_WEB_HOST` | `127.0.0.1` | Web UI 绑定地址 | +| `CCCC_WEB_PORT` | `8848` | Web UI 端口 | +| `CCCC_WEB_TOKEN` | （无） | Web UI 认证令牌 | +| `CCCC_LOG_LEVEL` | `INFO` | 日志级别 | diff --git a/docs/zh/reference/features.md b/docs/zh/reference/features.md new file mode 100644 index 00000000..c17d4bec --- /dev/null +++ b/docs/zh/reference/features.md @@ -0,0 +1,322 @@ +# 功能详解 + +CCCC 功能详细文档。 + +## IM 风格的消息系统 + +### 核心契约 + +- 消息是一等公民：一旦发送，即提交到 ledger +- 已读回执是显式的：Agent 调用 MCP 标记已读 +- 回复/引用是结构化的：`reply_to` + `quote_text` +- @提及实现精准投递 + +### 发送消息 + +```bash +# CLI +cccc send "Hello" # 不指定 --to：使用默认接收者策略（默认 foreman） +cccc send "Hello" --to @all +cccc reply "Reply text" + +# MCP +cccc_message_send(text="Hello", to=["@all"]) +cccc_message_reply(reply_to="evt_xxx", text="Reply") +``` + +### 已读回执 + +- Agent 调用 `cccc_inbox_mark_read(event_id)` 标记已读 +- 已读是累积的：标记 X 意味着 X 及之前的所有消息都已读 +- 游标存储在 `state/read_cursors.json` + +### 投递机制 + +``` +消息写入 ledger + ↓ +Daemon 解析 "to" 字段 + ↓ +对每个目标 actor： + ├─ PTY 运行中 → 注入终端 + └─ 否则 → 留在收件箱 + ↓ +等待 agent 调用 mark_read +``` + +投递格式： +``` +[cccc] user → peer-a: Please implement the login feature +[cccc] user → peer-a (reply to evt_abc): OK, please continue +``` + +## IM Bridge + +### 设计原则 + +- **1 个工作组 = 1 个 Bot**：简单、隔离、易理解 +- **显式订阅**：聊天必须 `/subscribe` 后才能接收消息 +- **端口层薄**：只做消息转发；daemon 是唯一的状态源 + +### 支持的平台 + +| 平台 | 状态 | Token 配置 | +|------|------|------------| +| Telegram | ✅ 完整 | `token_env` | +| Slack | ✅ 完整 | `bot_token_env` + `app_token_env` | +| Discord | ✅ 完整 | `token_env` | +| 飞书/Lark | ✅ 完整 | `feishu_app_id_env` + `feishu_app_secret_env` | +| 钉钉 | ✅ 完整 | `dingtalk_app_key_env` + `dingtalk_app_secret_env`（+ 可选 `dingtalk_robot_code_env`） | + +### 配置 + +```yaml +# group.yaml +im: + platform: telegram + token_env: TELEGRAM_BOT_TOKEN + +# Slack 需要双 token +im: + platform: slack + bot_token_env: SLACK_BOT_TOKEN # xoxb-... Web API + app_token_env: SLACK_APP_TOKEN # xapp-... Socket Mode +``` + +### IM 命令 + +| 命令 | 描述 | +|------|------| +| `/send ` | 使用工作组默认策略发送（默认：foreman） | +| `/send @ ` | 发送给特定 agent | +| `/send @all ` | 发送给所有 agent | +| `/send @peers ` | 发送给非 foreman 的 agent | +| `/subscribe` | 订阅，开始接收消息 | +| `/unsubscribe` | 取消订阅 | +| `/verbose` | 切换详细模式 | +| `/status` | 显示工作组状态 | +| `/pause` / `/resume` | 暂停/恢复消息投递 | +| `/help` | 显示帮助 | + +注意： +- 在私聊和群聊中 @bot 时，纯文本被视为隐式发送给默认接收者（默认：foreman）。 +- 在频道（Slack/Discord）中，先 @bot 再使用 `/send`（以避免平台斜杠命令冲突）。 +- 你可以在 Web UI 中配置默认接收者行为：设置 → 消息 → 默认接收者。 + +### CLI 命令 + +```bash +cccc im set telegram --token-env TELEGRAM_BOT_TOKEN +cccc im start +cccc im stop +cccc im status +cccc im logs -f +``` + +## Agent 引导 + +### 信息层次 + +``` +System Prompt（薄层） +├── 你是谁：Actor ID、角色 +├── 你在哪：工作组、Scope +└── 你能做什么：MCP 工具列表 + 关键提醒（见 cccc_help） + +MCP Tools（权威操作手册 + 执行接口） +├── cccc_help：操作指南（playbook） +├── cccc_project_info：获取 PROJECT.md +├── cccc_inbox_list / cccc_inbox_mark_read：收件箱 +└── cccc_message_send / cccc_message_reply：发送/回复 + +Ledger（完整记忆） +└── 所有历史消息和事件 +``` + +### 核心原则 + +- **要做**：一份权威操作手册（`cccc_help`） +- **要做**：内核层强制执行（RBAC 由 daemon 管控） +- **要做**：最小启动握手（Bootstrap） +- **不要做**：同一份内容写三个版本 + +### Agent 标准工作流 + +``` +1. 接收 SYSTEM 注入 → 知道自己是谁 +2. 调用 cccc_inbox_list → 获取未读消息 +3. 处理消息 → 执行任务 +4. 调用 cccc_inbox_mark_read → 标记已读 +5. 调用 cccc_message_reply → 回复结果 +6. 等待下一条消息 +``` + +## 自动化 + +自动化现在是一个规则引擎（用于提醒 + 运维操作），不仅仅是内置的催促。 + +### 规则触发器 + +| 触发器类型 | Web 标签 | 协议 | 典型用途 | +|------------|----------|------|----------| +| 间隔 | 每 N 分钟 | `every_seconds` | 站会/检查点提醒 | +| 定期计划 | 每日/每周/每月 | `cron` | 固定时间的定期提醒 | +| 一次性计划 | 倒计时/精确时间 | `at` | 一次性提醒和操作 | + +注意： +- Web UI 默认隐藏原始 cron 表达式编辑。 +- 运维操作特意限制为一次性触发。 + +### 规则动作 + +| 动作 | 配置方 | 触发器支持 | 描述 | +|------|--------|------------|------| +| `notify` | Web + MCP | 间隔/定期/一次性 | 向选定接收者发送系统通知 | +| `group_state` | Web（foreman/管理员） | 仅一次性 | 设置工作组状态（`active` / `idle` / `paused` / `stopped`） | +| `actor_control` | Web（foreman/管理员） | 仅一次性 | 启动/停止/重启选定的 actor 运行时 | + +### 一次性完成语义 + +- 一次性规则触发后自动标记为已完成。 +- 已完成的一次性规则会被禁用（不会重复触发）。 +- UI 支持清理已完成项目。 + +### 内置策略（与自定义规则分开） + +| 策略 | 配置 | 默认值 | 描述 | +|------|------|--------|------| +| 催促 | `nudge_after_seconds` | 300s | 未读消息超时提醒 | +| 要求回复催促 | `reply_required_nudge_after_seconds` | 300s | 要求回复义务的跟进 | +| 关注确认催促 | `attention_ack_nudge_after_seconds` | 600s | 关注消息缺少确认的跟进 | +| 未读催促 | `unread_nudge_after_seconds` | 900s | 收件箱仍有未读的提醒 | +| Actor 空闲 | `actor_idle_timeout_seconds` | 600s | Actor 空闲通知给 foreman | +| 保活 | `keepalive_delay_seconds` | 120s | Foreman 保活提醒 | +| 静默 | `silence_timeout_seconds` | 600s | 工作组静默通知给 foreman | +| 帮助催促 | `help_nudge_interval_seconds` / `help_nudge_min_messages` | 600s / 10 | 提示 actor 重新查阅 `cccc_help` | + +### 投递节流 + +| 配置 | 默认值 | 描述 | +|------|--------|------| +| `min_interval_seconds` | 0s | 连续投递之间的最小间隔（`0` 禁用节流） | + +## 运行时专用 Actor 密钥 + +CCCC 支持每个 actor 的私有环境变量，用于运行时定制（不同 actor 使用不同的模型/API 栈）。 + +- 存储在 `CCCC_HOME/state/secrets/actors/` 下的运行时状态中 +- 不写入工作组 ledger +- 不包含在工作组模板/蓝图中 +- 仅以键元数据形式可见（读取 API 从不返回值） + +CLI 接口： + +```bash +cccc actor secrets --set KEY=VALUE +cccc actor secrets --unset KEY +cccc actor secrets --keys +``` + +## 蓝图/工作组模板 + +CCCC Web 支持蓝图的导出/导入，用于可移植的工作组配置。 + +- 导出会捕获 actor、设置、自动化规则/代码片段和引导覆盖。 +- 导入使用替换语义（将传入的配置作为新的工作组设置应用）。 +- Ledger 历史被保留（导入不会重写历史事件）。 +- 环境密钥被有意排除。 + +### MCP 管理接口 + +```text +cccc_automation_state +cccc_automation_manage(op=create|update|enable|disable|delete|replace_all, ...) +``` + +`cccc_automation_manage` 为 Agent 的提醒管理做了优化： +- Foreman 可以管理所有 notify 提醒和完整替换。 +- Peer 只能管理自己的个人或共享的 notify 提醒。 +- 运维操作（`group_state`、`actor_control`）保持 Web/管理员面向。 + +## Web UI + +### Agent 标签页模式 + +- 每个 agent 是一个标签页 +- 聊天标签 + Agent 标签 +- 点击标签切换视图 +- 移动端：滑动切换 + +### 主要功能 + +- 工作组管理（创建/编辑/删除） +- Actor 管理（添加/启动/停止/编辑/删除） +- 消息发送（@提及自动补全） +- 消息回复（引用显示） +- 内嵌终端（xterm.js） +- 上下文面板（vision/sketch/tasks） +- 设置面板（自动化配置） +- IM Bridge 配置 + +### 主题系统 + +- 浅色/深色/跟随系统 +- CSS 变量定义所有颜色 +- 终端颜色自动适配 + +### 远程访问 + +推荐方案： + +- **Cloudflare Tunnel + Cloudflare Access（推荐）** + - 最佳体验：直接从手机浏览器访问 + - 强烈建议使用 Access 进行登录保护 + - 快速（临时 URL）：`cloudflared tunnel --url http://127.0.0.1:8848` + - 稳定（自定义域名）：使用 `cloudflared tunnel create/route/run` + +- **Tailscale（VPN）** + - 清晰的安全边界（Tailnet ACL） + - 建议仅绑定 tailnet IP：`CCCC_WEB_HOST=$TAILSCALE_IP cccc` + +## 多运行时支持 + +### 支持的运行时 + +| 运行时 | 命令 | 描述 | +|--------|------|------| +| amp | `amp` | Amp | +| auggie | `auggie` | Auggie (Augment CLI) | +| claude | `claude` | Claude Code | +| codex | `codex` | Codex CLI | +| cursor | `cursor-agent` | Cursor CLI | +| droid | `droid` | Droid | +| gemini | `gemini` | Gemini CLI | +| kilocode | `kilocode` | Kilo Code CLI | +| neovate | `neovate` | Neovate Code | +| opencode | `opencode` | OpenCode | +| copilot | `copilot` | GitHub Copilot CLI | +| custom | 自定义 | 任意命令 | + +### 安装配置命令 + +```bash +cccc setup --runtime claude # 配置 MCP（自动） +cccc setup --runtime codex +cccc setup --runtime droid +cccc setup --runtime amp +cccc setup --runtime auggie +cccc setup --runtime neovate +cccc setup --runtime gemini +cccc setup --runtime cursor # 打印配置指引（手动） +cccc setup --runtime kilocode # 打印配置指引（手动） +cccc setup --runtime opencode +cccc setup --runtime copilot +cccc setup --runtime custom +``` + +### 运行时检测 + +```bash +cccc doctor # 环境检查 + 运行时检测 +cccc runtime list # 列出可用运行时（JSON） +``` diff --git a/docs/zh/reference/positioning.md b/docs/zh/reference/positioning.md new file mode 100644 index 00000000..96cf8c34 --- /dev/null +++ b/docs/zh/reference/positioning.md @@ -0,0 +1,58 @@ +# 产品定位 + +本页定义 CCCC 是什么、不是什么，以及在哪些场景下能发挥最大价值。 + +## CCCC 是什么 + +CCCC 是一个**本地优先的协作内核**，面向多 Agent 工程协作场景。 + +核心价值： +- 持久化协作基底（追加写入的 ledger） +- 跨 Web/CLI/MCP/IM 的统一控制平面 +- 显式消息语义，确保可靠协调 +- 可运维的 actor 运行时模型 + +## CCCC 不是什么 + +CCCC 不是： +- 完整的可视化工作流设计器 +- 通用的企业 BPM 引擎 +- CI/CD 系统的替代品 +- 确定性批处理编排平台的替代品 + +CCCC 应当拥有协作状态和控制平面语义；其他系统可以拥有计算 DAG 和业务工作流。 + +## 理想使用场景 + +当你需要以下能力时，适合使用 CCCC： +- 多个编程 Agent 共享持久化上下文 +- 运维可靠的人机协作 +- 消息级别的问责机制（已读/确认/要求回复） +- 通过 IM Bridge 进行远程/移动端运维 + +## 不太适合的场景 + +如果你只需要以下能力，CCCC 可能不是最佳选择： +- 单 Agent 本地编程助手，无需团队协调 +- 纯 cron/批处理 ETL 编排 +- 重度 GUI 工作流建模，而非代码优先的控制方式 + +## 决策清单 + +如果以下大部分问题你的回答是"是"，则适合采用 CCCC： + +1. 我们是否需要持久化、可回放的协作历史？ +2. 我们是否需要多个 Agent 具备角色/接收者语义？ +3. 我们是否需要一个跨本地和远程入口的统一控制平面？ +4. 我们是否需要运维级别的恢复/排查工作流？ + +## 集成策略 + +推荐的分层方式： + +- CCCC：多 Agent 协作状态 + 控制平面 +- CI/CD：构建/测试/部署生命周期 +- 外部调度器：重度工作流定时/编排 +- IM 网关：远程运维和轻量级干预 + +这种分离使 CCCC 保持专注、可组合、易维护。 diff --git a/docs/zh/sdk/CLIENT_SDK.md b/docs/zh/sdk/CLIENT_SDK.md new file mode 100644 index 00000000..437b540a --- /dev/null +++ b/docs/zh/sdk/CLIENT_SDK.md @@ -0,0 +1,76 @@ +# CCCC 客户端 SDK + +将外部应用/服务与运行中的 CCCC daemon 集成的官方 SDK。 + +## 仓库和包 + +- 仓库：[ChesterRa/cccc-sdk](https://github.com/ChesterRa/cccc-sdk) +- Python 包：`cccc-sdk`（导入为 `cccc_sdk`） +- TypeScript 包：`cccc-sdk` + +## 与 CCCC 核心的关系 + +CCCC 核心（`cccc-pair`）是运行时系统： + +- daemon +- ledger/状态 +- Web/CLI/MCP/IM 端口 + +SDK 是客户端层： + +- 不启动/拥有 daemon 状态 +- 连接到已有的 daemon +- 使用与 Web/CLI/MCP 相同的控制平面语义 + +## 何时使用 SDK vs MCP + +当你在构建以下内容时使用 SDK： + +- 后端服务 +- Bot +- IDE 集成 +- Agent 运行时之外的自动化服务 + +当调用者是会话内的 Agent/工具运行时时使用 MCP。 + +## 安装 + +```bash +# Python +pip install -U cccc-sdk + +# TypeScript +npm install cccc-sdk +``` + +## 运行时要求 + +需要 CCCC daemon 已经在运行。 + +```bash +cccc daemon status +``` + +SDK 客户端会连接到 CCCC 运行时配置的 daemon 传输层（`CCCC_HOME`、daemon socket/TCP 设置）。 + +## 集成模型 + +典型的生产环境部署： + +1. 运行 CCCC 核心（`cccc-pair`）作为本地控制平面。 +2. 通过 SDK 连接你的应用/服务。 +3. 使用 SDK 调用进行工作组/actor/消息/上下文/自动化操作。 +4. 在 CCCC ledger 和工作组状态中保持运维事实来源。 + +## 兼容性说明 + +- SDK 和核心独立发布，但建议保持相同的主/次版本号以获得最佳兼容性。 +- 协议级别的详细信息，请参阅： + - `docs/standards/CCCS_V1.md` + - `docs/standards/CCCC_DAEMON_IPC_V1.md` + +## 下一步 + +具体的 API 示例和各语言的使用方式，请查阅 SDK 仓库文档： + +- [cccc-sdk README](https://github.com/ChesterRa/cccc-sdk) diff --git a/docs/zh/sdk/index.md b/docs/zh/sdk/index.md new file mode 100644 index 00000000..3f42b520 --- /dev/null +++ b/docs/zh/sdk/index.md @@ -0,0 +1,26 @@ +# SDK 概览 + +当你需要将 CCCC 与外部应用和服务集成时，可以使用官方 SDK。 + +## 官方 SDK + +- 仓库：[ChesterRa/cccc-sdk](https://github.com/ChesterRa/cccc-sdk) +- Python 包：`cccc-sdk`（导入为 `cccc_sdk`） +- TypeScript 包：`cccc-sdk` + +## 安装 + +```bash +pip install -U cccc-sdk +npm install cccc-sdk +``` + +## 与 CCCC 核心的关系 + +- CCCC 核心（`cccc-pair`）是运行时控制平面（daemon + ledger + ports）。 +- SDK 是该运行中的控制平面的客户端接口。 +- SDK 不替代核心，也不自行持久化状态。 + +## 下一步 + +- [客户端 SDK](./CLIENT_SDK)