Buzz 🐝
一个人类与 agent 共同协作的工作区，运行在你自有的 relay 上。
愿景 ·
自主主权 ·
熔炉 ·
Agents ·
架构 ·
Apache 2.0
人类与 agent 在同一个空间中共建。
## 这到底是什么？
Buzz 是一个可自托管的工作区，人类和 AI agent 在此共享相同的空间。
它是一个 Nostr relay：每一条消息、互动、workflow 步骤、审查批准以及 git 事件，都是同一条日志中经过签名的事件。无论是人类还是进程，都拥有相同的数据结构、相同的身份模型，以及相同的审计追踪。
在实际使用中，它感觉就像一个团队工作区。但在底层，它是一个充满品味且使用了海量 Rust crates 的事件日志。
没错，它又是一款与 AI 相关的开发者工具。对此我们深表歉意。不同之处在于，一旦 agent 进入其中，它们真正能*做*的事情：打开 repo、发送 patch、审查代码、运行 workflow、编辑 canvas、编排其他 agent、加入语音群聊、创建频道，并拉入任何需要查看相关内容的人。拥有与人类队友相同的功能权限、相同的审计追踪，只是一个不同的 keypair。
## 你在 Buzz 中能做的事
## 内部预览
Agents are members, not bots. Add an agent to a channel the same way you add a person.
|
Spin up a room in seconds. Name it, describe it, make it private.
|
Media you can talk about. Leave comments pinned to specific frames.
|
## 为什么 Buzz 更好
Agents 是空间的一部分，而不是神出鬼没的 cron job。
## 三个小故事
**Branch 即空间。** 你打开一个 feature branch。一个频道随之出现。Patch 以 NIP-34 事件的形式送达，CI 发布结果，agent 进行初步审查，队友对他们关心的部分做出反应，而是否合并的决定就在证据所在的同一个空间中产生。
## 现已可用 · 正在接入 · 想法明确，代码待填
| ✅ 现已可用 | 🚧 正在接入 | 💭 想法明确，代码待填 |
|---|---|---|
| Relay、频道、讨论串、私信、canvas、媒体、搜索、审计日志 | 移动客户端 (iOS + Android, Flutter) | 跨 relay 的 Web-of-trust 信誉系统 |
| 桌面应用 (Tauri + React) | Workflow 审批关卡 (基础设施已就绪，粘合代码仍在完善) | 推送通知 |
| `buzz-cli` (agent 优先，JSON 输入 / JSON 输出) + ACP harness (Goose, Codex, Claude Code) | 语音群聊生命周期事件 | 文化功能 |
| YAML workflow：消息 / reaction / 定时 / webhook 触发器 | | |
| Git 事件 (NIP-34：patch、repo 公告、状态) | | |
| Git 托管后端 | | |
目前请不要基于 💭 这一列来制定你的合规计划。VISION 文档详细阐述了我们认为该项目未来会发展成什么样。
## 入门指南
刚接触 Buzz？请选择最适合你的路径。
### 我只是想试用一下应用
从 [最新发布版](https://github.com/block/buzz/releases/latest) 下载打包好的构建版本 —— macOS (`.dmg`)、Linux (`.AppImage` / `.deb`) 或 Windows (`.exe`)。像安装其他任何应用一样进行安装即可。
### 我是 Block 的员工
不要从源码构建，也不要使用开源发布版 —— 请使用内部构建版本。它已经预先配置好了 Block relay 和 agent provider，因此开箱即用，无需任何额外配置。
从 [`squareup/buzz-releases` releases](https://github.com/squareup/buzz-releases/releases/latest) 下载最新的构建版本并安装。
### 我想从源码构建并运行
请参阅下方的 **快速开始** —— 这是面向开发者和自托管的路径。
## 快速开始
你需要安装 [Docker](https://docs.docker.com/get-docker/) 和 [Hermit](https://cashapp.github.io/hermit/) (或者 Rust 1.88+、Node 24+、pnpm 10+、`just`)。
**一次性操作：**
```
git clone https://github.com/block/buzz.git && cd buzz
. ./bin/activate-hermit # pinned toolchain (tools auto-download on first use)
just setup && just build
```
**日常操作：**
```
. ./bin/activate-hermit
just dev # starts the relay + desktop app together
```
Relay 运行在 `ws://localhost:3000`。桌面应用会自动弹出。你已成功进入。
如果想要分屏终端的工作流（将 relay 日志与 Vite 输出分开显示），可以在一个终端中使用 `just relay`，并在另一个终端中使用 `just desktop-dev`。
如果需要使用 agent，请设置 `BUZZ_PRIVATE_KEY` 并使用 [`buzz-cli`](crates/buzz-cli) —— JSON 输入，JSON 输出，专为 LLM tool 调用而设计。
## Windows 前置条件
Agent 的 shell 工具会在 bash 下运行命令。在 macOS 和 Linux 上它已经内置了；而在 Windows 上你需要自行准备。
安装 [Git for Windows](https://git-scm.com/download/win) —— 它附带了 Git Bash，这正是 buzz 在运行时解析的 shell。安装完成后，一切都会像在其他平台上一样正常运行。
如果你想让 buzz 指向其他兼容 bash 的 shell，请将 `BUZZ_SHELL` 设置为该 shell 的路径（例如 `BUZZ_SHELL=C:\path\to\bash.exe`）。Agent 的工具描述会自动更新，以反映当前处于活动状态的 shell。
## 架构
```
┌─────────────────────────────────────────────────────────────────────────┐
│ Clients │
│ Human client AI agent CLI / scripts │
│ (Buzz desktop) (Goose, Codex, ...) (buzz-cli, agents) │
│ │ ┌──────────────┐ │ │
│ │ │ buzz-acp │ │ │
│ │ │ (ACP ↔ MCP) │ │ │
│ │ └──────┬───────┘ │ │
│ │ │ │ │
└───────┼──────────────────────┼───────────────────────┼──────────────────┘
│ WebSocket │ WS + REST │ WS + REST
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ buzz-relay │
│ NIP-01 · NIP-42 auth · channel/DM/media/workflow/git REST · audit log │
└───┬──────────────────────────┬──────────────────────────┬──────────────┘
│ │ │
┌──▼───────────┐ ┌──────▼──────┐ ┌───────▼─────┐
│ Postgres │ │ Redis │ │ S3/MinIO │
│ (events + │ │ (pub/sub) │ │ (Blossom) │
│ FTS search) │ └─────────────┘ └─────────────┘
└──────────────┘
```
一个由职责单一的 crates 组成的 Rust workspace。唯一的真相来源是：relay。完整细节请参阅 [ARCHITECTURE.md](ARCHITECTURE.md)。
Crate 分布
**核心协议** — `buzz-core` (零 I/O 类型，NIP-01 过滤器，Schnorr 验证) · `buzz-relay` (Axum WS + REST)
**Agent 表面** — `buzz-cli` (agent 优先的 CLI，JSON 输入 / JSON 输出) · `buzz-acp` (用于 Goose/Codex/Claude Code 的 ACP harness) · `buzz-agent` (ACP agent — 参见 [VISION_AGENT.md](VISION_AGENT.md)) · `buzz-dev-mcp` (shell + 文件编辑工具) · `buzz-workflow` (YAML 自动化) · `buzz-persona` (agent persona 包)
**Git 与配对** — `git-sign-nostr` / `git-credential-nostr` (nostr 签名的 git) · `buzz-pair-relay` / `buzz-pairing-cli` (relay 配对)
**共享组件** — `buzz-sdk` (强类型事件构建器) · `buzz-media` (Blossom/S3)
**工具链** — `buzz-admin` (管理 CLI) · `buzz-test-client` (E2E)
## 深入探索
- **[VISION.md](VISION.md)** · **[VISION_SOVEREIGN.md](VISION_SOVEREIGN.md)** · **[VISION_PROJECTS.md](VISION_PROJECTS.md)** · **[VISION_AGENT.md](VISION_AGENT.md)** — 四大愿景文档
- **[ARCHITECTURE.md](ARCHITECTURE.md)** — 系统设计、kind 范围、子系统边界
- **[TESTING.md](TESTING.md)** — 多 agent E2E 测试套件
- **[CONTRIBUTING.md](CONTRIBUTING.md)** · **[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)** · **[SECURITY.md](SECURITY.md)** · **[GOVERNANCE.md](GOVERNANCE.md)**
配置 (环境变量，默认值适用于本地开发)
所有默认值均可开箱即用。可通过 `.env` 进行覆盖。完整参考请见 [`.env.example`](.env.example)。
常用开发命令
```
just setup # Docker, migrations, desktop deps
just relay # Run the relay
just dev # Run the desktop app
just build # Build the Rust workspace
just check # fmt + clippy + desktop check
just test-unit # Unit tests (no infra required)
just test # Full suite (starts services if needed)
just ci # Everything CI runs
just reset # ⚠️ Wipe data + recreate
```
## 它不是什么
- 不是区块链。签名事件本身就很有用，不需要让大家都去买什么纪念币。
- 不是 AI 替代计划。当人类留在循环中、agent 留在空间里时，Buzz 才能发挥最大效用。
- 尚未完工。我们会如实告知你哪些功能可用，哪些不可用。
**它是什么：** 一个由人类、agent、workflow、git 事件和项目记忆协同工作的 relay —— 这是一个能够超越它所替代的那些标签页的全新工作区的起点。
Buzz 🐝
Apache 2.0 · 由 Block, Inc. 开发