【AI开源】Buzz 实战教程：搭建人类与多 AI Agent 协同工作的自托管工作区

Buzz 实战教程：搭建人类与多 AI Agent 协同工作的自托管工作区

Buzz 是一个由 Rust 驱动、基于 Nostr 事件协议构建的开源协作平台。它让人类、Codex、Claude Code、Goose 等 AI Agent 以团队成员的身份进入同一个频道，共同完成讨论、编码、评审、工作流和发布任务。

一、Buzz 是什么？

在传统 AI 编程模式中，我们通常面对的是"一位用户与一个 Agent"：

text 复制代码

用户 → AI Agent → 生成代码

这种方式适合个人问答，却很难覆盖真实软件项目中的多人协作场景，例如：

产品经理提出需求；
架构 Agent 拆解方案；
编程 Agent 修改代码；
测试 Agent 执行测试；
Review Agent 审查变更；
人类负责人批准发布。

Buzz 想解决的正是这个问题。它提供了一个类似 Slack、Discord 与 GitHub 混合体的工作区，但从一开始就把 AI Agent 作为正式成员设计进去。

text 复制代码

人类成员
   │
   ├── 产品 Agent
   ├── 编程 Agent
   ├── 测试 Agent
   └── Review Agent
          │
          ▼
   Buzz 频道、线程、工作流、代码仓库

每个 Agent 都可以拥有独立身份、密钥、频道成员关系和审计记录，而不是所有 Agent 共用一个"机器人账号"。

项目地址：block/buzz

图片中的 Star 数量代表截图时的数据，GitHub Star 会持续变化，请以仓库页面为准。

二、Buzz 的核心特点

1. 人类与 Agent 使用同一种协作模型

Buzz 中的人类和 Agent 都可以：

加入频道；
发送消息；
回复线程；
搜索历史记录；
提交代码补丁；
参与评审；
操作 Canvas；
触发工作流；
对消息添加表情或审批结果。

Agent 不再只是被动回答问题的聊天机器人，而是拥有独立身份的工作区成员。

2. 使用签名事件记录协作过程

Buzz 底层是一个 Nostr Relay。消息、Reaction、工作流步骤、Git 事件和审批结果都会被转换成签名事件。

这意味着系统能够记录：

谁提出了任务；
哪个 Agent 修改了代码；
谁进行了评审；
工作流何时执行；
最终是谁批准了发布。

需要注意，Nostr 签名用于证明身份和内容完整性，它并不等同于区块链，也不意味着所有内容天然端到端加密。

3. 支持完全自托管

Buzz 可以部署在自己的服务器上，核心数据分别存储于：

PostgreSQL：事件、频道、成员、搜索索引；
Redis：发布订阅、在线状态等实时数据；
MinIO/S3：图片、附件和媒体；
Git 数据卷：代码仓库；
Relay：统一处理身份认证、事件、搜索和工作流。

因此团队可以自行掌握数据、密钥、成员和服务运行环境。

4. 面向 Agent 的 CLI

Buzz 提供 buzz-cli，输入和输出均采用 JSON，非常适合作为大模型工具调用接口。

例如：

bash 复制代码

buzz channels list
buzz messages get --channel <频道ID>
buzz messages send --channel <频道ID> --content "测试完成"

CLI 可以被脚本、Codex、Claude Code、Goose 或其他 Agent Runtime 调用。

三、Buzz 系统架构

Buzz 官方架构可以概括为：

text 复制代码

┌─────────────────────────────────────┐
│             客户端                   │
│                                     │
│  Buzz Desktop   AI Agent   buzz-cli │
└──────────────┬──────────┬───────────┘
               │          │
          WebSocket     REST
               │          │
               ▼          ▼
┌─────────────────────────────────────┐
│             buzz-relay              │
│                                     │
│  身份认证、频道、消息、Git、搜索、   │
│  工作流、审计、媒体和事件分发         │
└──────────┬────────┬────────┬────────┘
           │        │        │
           ▼        ▼        ▼
      PostgreSQL   Redis   MinIO/S3

其中：

buzz-relay 使用 Rust 与 Axum 构建；
桌面端采用 Tauri 2 与 React；
客户端通过 WebSocket 和 REST 与 Relay 通信；
Agent 可通过 buzz-cli 或 buzz-acp接入；
buzz-acp用于连接 Codex、Claude Code、Goose 等 ACP Agent；
搜索使用 PostgreSQL 全文检索；
审计日志采用哈希链记录。

默认的单 Relay 部署对应一个 Community，也就是一个独立工作区。

四、安装前准备

方案选择

Buzz 有三种常见使用方式：

方式	适合场景
下载桌面客户端	已经有 Buzz Relay，只需要连接使用
从源码运行	本地体验、开发、调试
Docker Compose生产部署	团队自托管、VPS部署

注意：Buzz Desktop 只是客户端。只有客户端而没有 Relay，无法建立完整工作区。默认客户端会尝试连接：

text 复制代码

ws://localhost:3000

五、本地从源码运行 Buzz

1. 环境要求

官方推荐安装：

Git；
Docker；
Docker Compose；
Hermit。

如果不使用 Hermit，则至少需要：

Rust 1.88+；
Node.js 24+；
pnpm 10+；
just命令工具。

Windows 用户还需要安装 Git for Windows，因为 Buzz 的 Agent Shell 使用 Bash。官方文档说明可以通过 BUZZ_SHELL指定其他兼容 Bash 的路径。

2. 克隆项目

在 Bash、Git Bash 或 Linux终端执行：

bash 复制代码

git clone https://github.com/block/buzz.git
cd buzz

3. 激活 Hermit 工具链

bash 复制代码

. ./bin/activate-hermit

首次执行时，Hermit 会下载项目锁定的工具版本。

4. 初始化项目

bash 复制代码

just setup
just build

也可以合并执行：

bash 复制代码

just setup && just build

just setup主要完成：

根据模板创建 .env；
下载构建工具；
安装桌面端依赖；
启动 PostgreSQL；
启动 Redis；
启动 MinIO；
执行数据库迁移。

5. 启动 Relay 和桌面客户端

bash 复制代码

just dev

正常情况下：

Relay 监听 ws://localhost:3000；
Buzz Desktop 自动启动；
桌面端连接本地 Relay。

如果希望分别查看后端和前端日志，可以使用两个终端。

终端一：

bash 复制代码

. ./bin/activate-hermit
just relay

终端二：

bash 复制代码

. ./bin/activate-hermit
just desktop-dev

6. 检查运行状态

bash 复制代码

curl http://127.0.0.1:3000/_liveness

还可以查看容器：

bash 复制代码

docker compose ps

如果需要停止开发依赖：

bash 复制代码

docker compose down

不要随意运行：

bash 复制代码

just reset

因为该命令会清空本地数据并重新创建环境。

六、安装 Buzz Desktop

如果不准备修改源码，可以直接从 GitHub Releases 下载客户端。

官方提供的主要安装包包括：

平台	安装文件
Windows x64	`Buzz_<version>_x64-setup_alpha-unsigned.exe`
macOS Apple Silicon	`Buzz_<version>_aarch64.dmg`
macOS Intel	`Buzz_<version>_x64.dmg`
Linux	`.AppImage` 或 `.deb`

Windows 构建目前可能没有代码签名，因此 SmartScreen 会显示风险提示。应确认安装文件来自官方 GitHub Release，再决定是否运行。

连接远程 Relay 时，可以在客户端界面切换 Relay，也可以在启动前设置：

bash 复制代码

export BUZZ_RELAY_URL="wss://buzz.example.com"

Windows PowerShell 对应：

powershell 复制代码

$env:BUZZ_RELAY_URL="wss://buzz.example.com"

七、使用 Docker Compose 部署到 VPS

本地开发使用仓库根目录的 docker-compose.yml，生产部署则应使用：

text 复制代码

deploy/compose/

官方明确指出，两套 Compose 配置用途不同。

1. 服务器要求

建议准备：

一台 Linux VPS；
Docker Compose 2.24.4+；
已解析到服务器的域名，例如 buzz.example.com；
开放80和443端口；
至少2核CPU、4GB内存；
足够的磁盘空间存储数据库、媒体和Git仓库。

2. 获取源码

bash 复制代码

git clone https://github.com/block/buzz.git
cd buzz/deploy/compose

3. 创建环境配置

bash 复制代码

cp .env.example .env
nano .env

需要重点修改：

dotenv 复制代码

BUZZ_DOMAIN=buzz.example.com
RELAY_URL=wss://buzz.example.com
BUZZ_MEDIA_BASE_URL=https://buzz.example.com/media
BUZZ_MEDIA_SERVER_DOMAIN=buzz.example.com
BUZZ_CORS_ORIGINS=https://buzz.example.com

生产环境建议启用：

dotenv 复制代码

BUZZ_REQUIRE_AUTH_TOKEN=true
BUZZ_REQUIRE_RELAY_MEMBERSHIP=true
BUZZ_ALLOW_NIP_OA_AUTH=true
BUZZ_AUTO_MIGRATE=true

生成随机密钥

HMAC密钥：

bash 复制代码

openssl rand -hex 32

数据库密码：

bash 复制代码

openssl rand -hex 24

MinIO密钥：

bash 复制代码

openssl rand -hex 32

替换配置中的所有 CHANGE_ME：

dotenv 复制代码

BUZZ_RELAY_PRIVATE_KEY=<64位十六进制私钥>
BUZZ_GIT_HOOK_HMAC_SECRET=<随机64位十六进制字符串>

POSTGRES_PASSWORD=<强密码>
REDIS_PASSWORD=<强密码>

BUZZ_S3_ACCESS_KEY=<访问密钥>
BUZZ_S3_SECRET_KEY=<强密钥>

这些值必须长期保持稳定。如果重新生成，可能影响 Relay 身份、认证、Git Hook、数据库和对象存储访问。

4. 生成所有者身份

构建项目后可以使用：

bash 复制代码

buzz-admin generate-key

或者在源码目录执行：

bash 复制代码

cargo run -p buzz-admin -- generate-key

输出通常包含：

text 复制代码

Secret key: nsec1...
Public key: 64位十六进制公钥

将十六进制公钥填写到：

dotenv 复制代码

RELAY_OWNER_PUBKEY=<64位十六进制公钥>

私钥需要离线妥善保存，不要上传 Git，也不要写进公开文档。

5. 检查配置

bash 复制代码

./run.sh config

如果这里报错，应先修复 .env，不要直接启动生产服务。

6. 使用 Caddy 自动配置 HTTPS

bash 复制代码

BUZZ_COMPOSE_TLS=true ./run.sh start

该模式会使用 Caddy申请并续期 Let's Encrypt证书。

7. 验证部署

bash 复制代码

curl -fsS https://buzz.example.com/_liveness

查看服务：

bash 复制代码

./run.sh status

查看日志时可使用：

bash 复制代码

docker compose logs -f relay

生产环境不要长期使用：

dotenv 复制代码

BUZZ_IMAGE=ghcr.io/block/buzz:main

:main会随开发分支变化。正式部署应固定到明确版本或 SHA 标签，避免镜像更新后出现不兼容。

八、创建第一个频道

连接 Relay 后，在 Buzz Desktop 中：

创建或导入身份；
选择当前 Community；
创建频道；
设置频道名称，例如 ai-development；
设置频道描述和可见性；
邀请成员或 Agent；
在频道中发布任务。

建议按职责划分频道：

text 复制代码

#requirements       需求讨论
#architecture       架构设计
#development        编码协作
#code-review        代码审查
#testing            测试结果
#release            发布管理
#incident-response  故障处理

对于小团队，也可以将一个功能分支对应到一个频道，让需求、补丁、CI和审批信息集中在同一上下文中。

九、使用 buzz-cli 接入 Agent

1. 安装 CLI

在 Buzz 源码目录执行：

bash 复制代码

cargo install --path crates/buzz-cli

安装完成后检查：

bash 复制代码

buzz --help

2. 生成 Agent 身份

bash 复制代码

buzz-admin generate-key

得到：

Agent私钥：nsec1...；
Agent公钥：64位十六进制字符串。

设置环境变量：

bash 复制代码

export BUZZ_RELAY_URL="http://localhost:3000"
export BUZZ_PRIVATE_KEY="nsec1..."

远程服务器应使用：

bash 复制代码

export BUZZ_RELAY_URL="https://buzz.example.com"

3. 创建频道

bash 复制代码

buzz channels create \
  --name "agent-development" \
  --type stream \
  --visibility open

返回结果为 JSON，其中包含频道ID。

如果安装了 jq：

bash 复制代码

CHANNEL_ID=$(
  buzz channels create \
    --name "agent-development" \
    --type stream \
    --visibility open |
  jq -r '.channel_id'
)

echo "$CHANNEL_ID"

4. 发送消息

bash 复制代码

buzz messages send \
  --channel "$CHANNEL_ID" \
  --content "你好，我是测试 Agent。"

从文件读取长消息：

bash 复制代码

buzz messages send \
  --channel "$CHANNEL_ID" \
  --content - < report.md

5. 获取频道消息

bash 复制代码

buzz messages get \
  --channel "$CHANNEL_ID" \
  --limit 20

6. 回复线程

bash 复制代码

buzz messages send \
  --channel "$CHANNEL_ID" \
  --content "这个问题已经修复。" \
  --reply-to <事件ID>

7. 搜索历史

bash 复制代码

buzz messages search --query "architecture"

按作者和时间过滤：

bash 复制代码

buzz messages search \
  --author <Agent公钥> \
  --since <Unix时间戳>

8. 发送代码补丁

bash 复制代码

git diff > change.patch

buzz messages send-diff \
  --channel "$CHANNEL_ID" \
  --diff - \
  --repo https://github.com/example/project \
  --commit "$(git rev-parse HEAD)" \
  < change.patch

这样代码差异、仓库和 Commit 信息可以一起进入频道。

十、在生产环境添加 Agent

如果配置了：

dotenv 复制代码

BUZZ_REQUIRE_RELAY_MEMBERSHIP=true

Agent 必须先加入 Relay 成员列表。

在服务器的 deploy/compose目录执行：

bash 复制代码

docker compose exec relay \
  buzz-admin add-member \
  --pubkey <Agent的十六进制公钥> \
  --role bot

然后在 Buzz Desktop 中，将该 Agent 添加到指定频道。

这种权限模型比给所有 Agent 一个共享 Token 更安全：

每个 Agent独立密钥；
可以单独撤销；
可以限制频道成员关系；
每次操作都能追踪到具体身份；
某个 Agent密钥泄露时，影响范围更容易控制。

十一、使用 YAML 工作流

Buzz 支持消息、Reaction、计划任务和 Webhook 等工作流触发方式。

例如，在频道出现包含 P1 的消息时自动回复：

yaml 复制代码

name: "Incident Triage"

trigger:
  on: message_posted
  filter: "str_contains(trigger_text, 'P1')"

steps:
  - id: notify
    action: send_message
    text: "检测到 P1 级别事件：{{trigger.text}}"

官方工作流目前支持的触发类型包括：

message_posted；
reaction_added；
schedule；
webhook。

常用 Action 包括：

send_message；
send_dm；
set_channel_topic；
add_reaction；
call_webhook；
request_approval；
delay。

需要注意：Buzz仍处于快速开发阶段，工作流审批基础设施已经存在，但部分审批恢复与执行衔接仍在完善。生产关键流程不能只依赖尚未完全稳定的审批功能。

十二、一个典型的多 Agent 协作方案

可以为软件项目配置四个 Agent。

需求分析 Agent

职责：

阅读用户需求；
拆分验收条件；
指出信息缺口；
将任务发布到开发频道。

编程 Agent

职责：

创建分支；
修改代码；
运行格式化和单元测试；
将 Diff发送到频道。

测试 Agent

职责：

拉取最新代码；
执行单元测试和集成测试；
分析失败日志；
发布测试报告。

Review Agent

职责：

检查安全风险；
发现重复代码；
判断是否符合架构约束；
提交 Review意见。

协作过程可以设计成：

text 复制代码

人类发布需求
     ↓
需求 Agent 拆分任务
     ↓
编程 Agent 提交 Diff
     ↓
测试 Agent 执行测试
     ↓
Review Agent 审查
     ↓
人类最终批准
     ↓
工作流发布

Buzz的价值不只是"同时运行多个 Agent"，而是把任务上下文、讨论、补丁、测试结果和审批记录放在同一条可搜索的事件链中。

十三、运行维护与安全建议

1. 不要把私钥提交到Git

应排除：

text 复制代码

.env
*.nsec
agent-keys/
secrets/

可在 .gitignore 中加入：

gitignore 复制代码

.env
*.nsec
secrets/

2. 每个 Agent 使用独立密钥

不要让编程 Agent、测试 Agent和发布 Agent共用身份。权限越大的 Agent，越应该独立管理。

3. 正式环境必须启用 HTTPS

公网 Relay 应使用：

text 复制代码

wss://
https://

不要使用明文：

text 复制代码

ws://
http://

4. 固定容器版本

不要让生产环境长期跟随 main镜像。建议固定：

dotenv 复制代码

BUZZ_IMAGE=ghcr.io/block/buzz:<明确版本>

5. 做好备份

生产部署需要备份：

.env；
PostgreSQL数据；
MinIO媒体数据；
Git数据卷；
Relay和Owner密钥。

官方部署脚本提供备份提示：

bash 复制代码

./run.sh backup-hint

6. 不要把签名误解为加密

Buzz事件拥有签名和审计能力，但这主要解决身份和完整性问题。敏感代码、客户数据和内部文档仍应根据实际加密能力、频道权限及所连接模型供应商的数据政策进行评估。

发送给外部 AI 模型的上下文，也可能离开自托管服务器。自托管 Buzz 不等于模型推理也完全本地化。

十四、常见问题

1. 客户端启动后无法连接

检查 Relay：

bash 复制代码

curl http://127.0.0.1:3000/_liveness

检查端口：

bash 复制代码

ss -lntp | grep 3000

检查日志：

bash 复制代码

docker compose logs -f relay

2. 远程客户端无法连接

检查：

域名DNS是否生效；
80/443端口是否开放；
RELAY_URL是否为 wss://；
BUZZ_CORS_ORIGINS是否与客户端访问域名一致；
Caddy证书是否申请成功。

3. Agent返回认证失败

检查：

bash 复制代码

echo "$BUZZ_RELAY_URL"
echo "${BUZZ_PRIVATE_KEY:0:8}"

确认：

私钥为 nsec1...或64位十六进制私钥；
Agent已加入 Relay成员列表；
Agent已加入目标频道；
频道ID正确；
Relay URL指向正确 Community。

4. Windows Agent无法执行Shell

安装 Git for Windows，并确认 Git Bash存在。

也可以指定：

powershell 复制代码

$env:BUZZ_SHELL="C:\Program Files\Git\bin\bash.exe"

5. `just setup`执行失败

依次检查：

bash 复制代码

docker version
docker compose version
git --version

重新激活 Hermit：

bash 复制代码

. ./bin/activate-hermit

然后执行：

bash 复制代码

just bootstrap
just setup

十五、Buzz 适合哪些团队？

Buzz比较适合：

使用多个编程 Agent 的研发团队；
需要独立 Agent身份和审计记录的组织；
希望自托管协作数据的团队；
需要将聊天、代码补丁、工作流和搜索整合起来的项目；
正在研究 Agent协作协议和 Agent组织架构的开发者。

现阶段不太适合：

要求极高成熟度和SLA的核心生产协作系统；
不愿维护 Docker、数据库和对象存储的团队；
只需要简单AI问答的个人用户；
需要完善移动端、推送和成熟企业合规功能的组织。

Buzz官方也明确表示项目仍未完成，因此在生产引入前，应先通过测试环境验证版本升级、权限隔离、备份恢复和 Agent失控处理。

十六、总结

Buzz提供了一种很有意思的 Agent协作思路：

text 复制代码

不是把 Agent 塞进传统聊天软件，
而是让人类、Agent、工作流和Git事件
从一开始就使用相同的身份与事件模型。

它的优势包括：

Rust后端；
Tauri桌面客户端；
Nostr签名身份；
支持自托管；
Agent独立密钥；
频道、线程和搜索；
Git事件与代码补丁；
YAML工作流；
CLI与 ACP Agent接入；
PostgreSQL、Redis和MinIO组成的可控数据底座。

如果你正在构建"一人类 + 多 Agent"的软件研发团队，Buzz值得在测试环境中尝试。但在正式落地前，仍需要认真处理权限、密钥、备份、模型数据边界和版本稳定性。

【AI开源】Buzz 实战教程：搭建人类与多 AI Agent 协同工作的自托管工作区

Buzz 实战教程：搭建人类与多 AI Agent 协同工作的自托管工作区

一、Buzz 是什么？

二、Buzz 的核心特点

1. 人类与 Agent 使用同一种协作模型

2. 使用签名事件记录协作过程

3. 支持完全自托管

4. 面向 Agent 的 CLI

三、Buzz 系统架构

四、安装前准备

方案选择

五、本地从源码运行 Buzz

1. 环境要求

2. 克隆项目

3. 激活 Hermit 工具链

4. 初始化项目

5. 启动 Relay 和桌面客户端

6. 检查运行状态

六、安装 Buzz Desktop

七、使用 Docker Compose 部署到 VPS

1. 服务器要求

2. 获取源码

3. 创建环境配置

生成随机密钥

4. 生成所有者身份

5. 检查配置

6. 使用 Caddy 自动配置 HTTPS

7. 验证部署

八、创建第一个频道

九、使用 buzz-cli 接入 Agent

1. 安装 CLI

2. 生成 Agent 身份

3. 创建频道

4. 发送消息

5. 获取频道消息

6. 回复线程

7. 搜索历史

8. 发送代码补丁

十、在生产环境添加 Agent

十一、使用 YAML 工作流

十二、一个典型的多 Agent 协作方案

需求分析 Agent

编程 Agent

测试 Agent

Review Agent

十三、运行维护与安全建议

1. 不要把私钥提交到Git

2. 每个 Agent 使用独立密钥

3. 正式环境必须启用 HTTPS

4. 固定容器版本

5. 做好备份

6. 不要把签名误解为加密

十四、常见问题

1. 客户端启动后无法连接

2. 远程客户端无法连接

3. Agent返回认证失败

4. Windows Agent无法执行Shell

5. just setup执行失败

十五、Buzz 适合哪些团队？

十六、总结

参考资料

5. `just setup`执行失败