English · Русский · 中文 · Español · Deutsch · Français · Português (BR) · 日本語

Flock

在你自己的服务器上运行一支 Claude Code AI 开发团队，并通过聊天来驱动它。 在 Telegram 或 VK 中描述一项功能；团队会为它制定计划、在分支上构建、测试、评审，并发起一个 PR——每个聊天都拥有各自隔离的工作区。

它基于你的 Claude Pro/Max 订阅（无按 token 计费）或一个 Anthropic API 密钥运行，以预构建的 Docker 镜像形式发布（无需构建步骤），并将每个聊天保持在各自的沙箱化工作区中。

快速上手（Docker）

git clone https://github.com/duckbugio/flock
cd flock/adapters/telegram
cp .env.example .env        # fill in the REQUIRED block (4 values)
docker compose up -d

这会拉取预构建镜像 ghcr.io/duckbugio/flock-telegram——无需构建，也无需 Ansible——然后给你的机器人发消息即可。最简 .env：

变量	含义
TELEGRAM_BOT_TOKEN	来自 @BotFather
TELEGRAM_BOT_USERNAME	你机器人的 @username（不带 @）
ALLOWED_USERS	允许使用该机器人的 Telegram 用户 ID，以逗号分隔
CLAUDE_CODE_OAUTH_TOKEN	claude setup-token（订阅）——或者设置 ANTHROPIC_API_KEY

.env.example 中的其余一切都有合理的默认值。日后可用 docker compose pull && docker compose up -d 更新。

Telegram 秘书模式

先在 @BotFather 为机器人启用秘书模式，再在 Telegram 中选择允许访问的私人聊天。账户所有者必须列在 ALLOWED_USERS 中。SECRETARY_MODE=approval 将草稿发给账户所有者，由其发送或丢弃；SECRETARY_MODE=auto 会立即回复。回复使用为机器人单独选定的 AI 服务商和模型（AI_BACKEND）；Telegram 不选择另一个 AI 模型。使用 Claude 时，秘书运行完整的 Flock 智能体，包含工具、MCP，以及每个 Business 聊天独立持久的会话。启用自动回复前，请在服务提供商处设置支出上限。英文详情。

目前秘书模式仅支持 AI_BACKEND=claude；使用其他服务商时，机器人继续运行，但不会处理 Business 消息。

只允许您信任其参与者使用 Flock 工具和 MCP 的聊天接入。审核仅控制回复发送：工具可能在您确认前运行，取消执行也无法撤销已完成的操作。

地区： 请托管在 Anthropic 支持的地区（部分国家/地区会被地理封锁，例如 RU/CN）——否则 Claude 调用会失败。

VK 在 adapters/vk/ 下采用相同的模式，构建于同一套核心之上，并以 ghcr.io/duckbugio/flock-vk 形式发布。它只附带一个环境变量模板（没有 compose 文件）：cp .env.example .env，然后 docker run --env-file .env ghcr.io/duckbugio/flock-vk。Claude 认证与核心设置都与 Telegram 一致；只有三个传输变量不同：

变量	含义
VK_BOT_TOKEN	社区访问令牌（VK 社区 → 管理 → API 使用 → 访问令牌）
VK_GROUP_ID	你社区的数字 id（长轮询服务器 + 提及解析）
VK_ALLOWED_USERS	允许使用该机器人的 VK 用户 ID，以逗号分隔

亮点

• 对话即任务来源——在聊天中描述你想要什么，然后评审返回的 PR；智能体的 shell 和编辑器都被沙箱化在容器内部。
• 一条真正的开发团队流水线，而非单个提示词——规格优先的验收标准、构建/回归门禁，以及一位打破循环的仲裁者。
• 多传输通道——如今有 Telegram 与 VK，二者都构建于同一套核心之上；新增一个平台只是一个轻量适配器，而非一次分叉。
• 无需入站 webhook 即可响应 PR——机器人会向你的 git 主机轮询新的评审评论，并将每条评论路由回发起该 PR 的聊天。
• 对订阅友好——使用 Claude Pro/Max 令牌（无按 token 计费）或 Anthropic API 密钥进行认证。

工作原理

You (in a chat): "implement X across the api + web services"
  → bot's Claude (Lead) → planner → confirm scope → coder ⇄ tester → PR per repo
                                                      → reviewer (inline comments) ⇄ coder → arbiter
                                                                                        ├ APPROVE → you merge
                                                                                        └ ESCALATE → asks you

五个子智能体——planner → coder → tester → reviewer → arbiter——作为原生 Claude Code 子智能体运行于 core/agents/。普通提问会被直接解答；构建请求则触发整个团队。arbiter 是感知风险、限制循环次数的打破循环者，让智能体永远不会无止境地空转。分支以 duck/<chatid>/<slug> 命名，以便 PR-webhook/轮询事件能路由回正确的聊天。

该开发团队是为微服务工作区而设计的：一项功能可以横跨多个服务，团队会协调各个分支并为每个仓库发起一个交叉链接的 PR。完整的流水线、防护栏与角色表见 core/README.md。

仓库结构（单体仓库）

平台无关的开发团队大脑位于 core/；每个平台都是 adapters/<name>/ 下一个共享它的轻量适配器。

适配器	路径	预构建镜像
Telegram	adapters/telegram/	ghcr.io/duckbugio/flock-telegram
VK	adapters/vk/	ghcr.io/duckbugio/flock-vk

未来的平台会复用同一套核心——参见 docs/multi-transport-plan.md。

接入 git 主机（可选但属核心）

在 .env 中设置以下内容，让团队能够克隆仓库并发起 PR（适用于 Gitea/GitHub/GitLab）：

GIT_HOST=git.example.com
GIT_USER=...
GIT_TOKEN=...                 # write-scoped PAT
GIT_AUTHOR_NAME=AI Team
[email protected]
# Poll the host for new PR comments (reliable; no inbound webhook needed):
GITEA_API_URL=https://git.example.com/api/v1
GITEA_POLL_INTERVAL=90

对于 github.com，还需设置 GH_TOKEN（= 你的 GIT_TOKEN），以便 gh CLI 能发起 PR。

轮询器是响应评审评论的推荐方式——它主动向外发起请求，因此即便你的主机无法访问机器人它也照样有效。当 ENABLE_PR_REVIEW=true 且设置了 GITEA_API_URL 时它处于激活状态。一种入站 webhook 加上 Caddy TLS 代理的替代方案仅通过 Ansible 部署提供（设置 webhook_domain）。

其他选项

• 语音消息： ENABLE_VOICE_MESSAGES=true、VOICE_PROVIDER=mistral|openai|local，外加 MISTRAL_API_KEY（或 OPENAI_API_KEY）。语音会被转写并作为命令运行。
• dind 边车容器： docker compose --profile dind up -d 为团队提供容器化的 linters/测试（设置 DOCKER_HOST=tcp://dind:2375）。
• 按聊天隔离： 每个聊天都会获得一个 /workspace/chat_<id>（一对一 → 私有；群组 → 一个共享工作区）；不同聊天彼此完全隔离并行运行，受 MAX_CONCURRENT_CHAT_RUNS 限制。在群组中，设置 REQUIRE_GROUP_MENTION=true 可让机器人仅在被 @提及或被回复时才响应。
• Ansible 部署（Telegram）：从 adapters/telegram/deploy 一条命令配置一台 VPS——将 inventories/example 复制为你自己的 inventories/<name>/（已 gitignore），填好 inventory/vars/vault，然后执行 ansible-playbook -i inventories/<name>/inventory.ini playbook.yml。该角色会拉取预构建镜像；设置 bot_image 以固定某个标签。

安全

• 白名单： 只有 ALLOWED_USERS（Telegram）/ VK_ALLOWED_USERS（VK）才能使用该机器人——切勿将其留空；它会授予对你服务器的 shell/编辑访问权限。
• 按聊天隔离： 不同聊天会获得各自独立的工作区。git 令牌在整个部署内共享——请据此设定其权限范围。
• 机密： 将它们保存在 .env（已 gitignore）中，或对于 Ansible，保存在某个真实实例的 vault.yml（已 gitignore，可用 ansible-vault 加密）中。只有 inventories/example/ 会被纳入版本控制。
• 沙箱： 智能体以非 root 用户运行；其 Bash/Edit 被限定在容器内，而非你的宿主机。

构建、lint、测试

本仓库使用 Task 作为其 CI 运行器——与 CI 所用的入口相同：

task lint      # format + vet + linters (in the dev-tools image)
task tests     # Go test suite
task build     # compile the binaries

许可证

MIT © DuckBug.

贡献与安全

参与贡献和报告安全漏洞的指南：CONTRIBUTING.md、CODE_OF_CONDUCT.md、SECURITY.md。