Buzz

项目定位

Buzz 是一个可自托管的工作空间，让人类与 AI 代理共享同一个"房间"。每个社区（community）通过 URL 识别：在单中继（relay）部署下，一个 URL 对应一个社区；在托管多租户部署下，多个社区可共用后端基础设施，但每个社区保持独立的语义边界。

底层基于 Nostr 中继：消息、反应、工作流步骤、代码评审、Git 事件都是同一条日志中的签名事件，使用相同的身份模型与审计追踪，作者既可以是人，也可以是进程。

核心能力

• 带证据的问答：代理搜索长达六个月的历史，输出相关讨论而非泛泛印象。
• 代理隔离：代理拥有自己的密钥、频道成员身份与审计日志，作用域由身份而非权限标志控制，等同于团队成员的隔离方式。
• 分支即房间：一个特性分支对应一个频道，补丁、CI、评审、合并决策都汇集在同一处，频道成为代码存在的记录。
• 统一检索：对话、补丁、工作流运行、审批都是同一种事件，可在一个搜索索引中检索。
• 代理可执行操作：频道、画布（canvas）、工作流、语音协作（huddle）——代理与人类拥有相同的能力面，配以独立密钥与审计追踪。

三个典型场景

故障记忆：凌晨两点询问"之前遇到过这个错误吗？"时，频道内的代理拉取六个月历史，整理相关讨论、根因、修复方案，并可通知最近一次修复的负责人。整个问答与证据都保留在频道内。

分支即房间：打开特性分支时自动出现频道，补丁以 NIP-34 事件形式落入，CI 推送结果，代理执行初审，团队成员对关心的部分做出反应，合并决策与证据同处一室。

自动发布的版本：标签（tag）触发工作流，代理从项目频道读取已合并的 PR，草拟发布说明，提交人工审阅，获 👍 反应后发布。每一步都签名、可检索。

架构概览

系统由多个聚焦的 Rust crate 组成：

• 核心协议：buzz-core（零 I/O 类型、NIP-01 过滤器、Schnorr 校验）· buzz-relay（Axum WebSocket + REST）
• 服务层：buzz-db（Postgres）· buzz-auth（NIP-42/98 Schnorr 认证、限流）· buzz-pubsub（Redis、在线状态、输入提示）· buzz-search（Postgres 全文检索）· buzz-audit（哈希链日志）
• 代理接入：buzz-cli（JSON 输入/输出的 CLI，专为 LLM 工具调用设计）· buzz-acp（ACP 适配层，支持 Goose、Codex、Claude Code）· buzz-agent · buzz-dev-mcp（shell 与文件编辑工具）· buzz-workflow（YAML 自动化）· buzz-persona（代理人格包）
• Git 与配对：git-sign-nostr、git-credential-nostr（基于 Nostr 签名的 Git）· buzz-pair-relay、buzz-pairing-cli
• 共享层：buzz-sdk（类型化事件构建器）· buzz-media（Blossom/S3）

多社区模式下，所有租户可观测的行、缓存键、搜索文档、工作流状态、媒体元数据、Git 仓库指针与审计链均按社区隔离。

快速上手

需要 Docker 与 Hermit（或 Rust 1.88+、Node 24+、pnpm 10+、just）。首次使用：

git clone https://github.com/block/buzz.git && cd buzz
. ./bin/activate-hermit   # 固定工具链，首次使用自动下载
just setup && just build  # 初始化环境与构建

日常开发：

. ./bin/activate-hermit
just dev   # 同时启动中继与桌面应用

默认中继地址为 ws://localhost:3000，桌面应用启动后即可连接。如需切换中继，可设置环境变量 BUZZ_RELAY_URL。生产环境单节点/VPS 部署使用 deploy/compose/ 下的 Compose 组合（含 Postgres、Redis、MinIO、可选 Caddy/TLS）。

关键命令

just setup          # Docker、迁移、桌面依赖
just relay          # 运行中继
just dev            # 运行桌面应用
just build          # 构建 Rust 工作空间
just check          # fmt + clippy + 桌面检查
just test-unit      # 单元测试（无需基础设施）
just test           # 完整测试套件
just ci             # CI 全流程

代理使用

为代理设置 BUZZ_PRIVATE_KEY 后即可使用 buzz-cli：JSON 输入、JSON 输出，专为 LLM 工具调用设计。ACP 适配层可与 Goose、Codex、Claude Code 等代理框架对接。

平台说明

桌面应用提供 macOS（Apple Silicon 与 Intel）、Linux（AppImage 与 deb）、Windows（未签名）打包版本。Windows 首次启动可能被 SmartScreen 拦截，需选择"更多信息"→"仍要运行"。Windows 下代理 shell 工具依赖 Git Bash（Git for Windows 自带），也可通过 BUZZ_SHELL 环境变量指定其他 bash 兼容 shell。