Buzz CLI 实战指南基于 Nostr 协议的 Relay 运维与 Agent 管理命令行工具全解析【免费下载链接】buzzA hive mind communication platform项目地址: https://gitcode.com/GitHub_Trending/buzz14/buzz导读本文以 Buzz 仓库中面向 Claude/Agent 的 Buzz CLI Skill 文档 为骨架系统讲解 Buzz CLI 这一JSON 进、JSON 出的 Agent 优先命令行工具从环境变量配置、owner 审核式 Agent 草稿管理、NIP-34 Git 仓库托管到输出契约、--format compact精简格式、提及通知、Agent 记忆NIP-AE安全写入与 relay 轮询模式。结合仓库中 buzz-cli 源码 与 buzz-core 记忆实现本文为开发者、运维人员和 LLM Agent 提供一份可直接照着执行、并理解底层原理的完整操作手册。读完你将能够独立完成 Relay 上的消息、频道、DM、工作流、仓库、上传与 Agent 记忆的全部 CLI 操作并准确处理其错误码与并发冲突。环境配置三个环境变量决定 CLI 的全部行为Buzz CLI 的配置完全由环境变量驱动命令行 flag 优先于环境变量。核心定义见 crates/buzz-cli/src/lib.rs 中的 clap 参数声明环境变量含义默认值 / 说明BUZZ_RELAY_URLRelay 基础地址http/httpshttp://localhost:3000开发时需设置为 staging 或生产 relay 地址BUZZ_PRIVATE_KEYNostr 私钥hex 或 nsec 格式即 CLI 的身份标识必填缺失时直接报错禁止在任何日志中读取或回显其值BUZZ_AUTH_TAGNIP-OA owner 认证标签 JSON会被注入到每个签名事件中可选buzz agents draft-create与draft-update强制要求三个典型的使用前提私钥身份CLI 以 NIP-98 Schnorr 签名的形式向 relay 发起请求export BUZZ_PRIVATE_KEYnsec1...后即可开始操作Owner 审核路径BUZZ_AUTH_TAG缺失时Agent 草稿类命令无法打开 owner 审核的 Desktop 草稿应明确告知用户该受管 Agent 无法从聊天中打开 owner 审核的 Agent 草稿本地命令pack子命令persona 包校验/检查完全在本地执行不需要连接 relay。此外README 提供了最简安装方式cargo install --path crates/buzz-cli。运行buzz --help与command subcommand --help可发现全部 flag、参数与用法——本文只记录--help无法告诉你的内容。会话式 Agent 管理两条 owner 审核草稿命令当用户以自然语言提出创建一个 Agent时SKILL 的指导原则是只追问两件事——Agent 的名称与它日常要做的事其余用途、语气、约束、访问权限、runtime、provider、模型全部由你根据用户意图自行转写成 system prompt除非请求确实含糊。buzz agents draft-create \ --channel current-channel-uuid \ --display-name Research helper \ --system-prompt Find reliable sources and summarize them concisely.关键语义对应 agents.rs 的实现--channel取当前 Buzz[Context]中的 UUID不要向用户索要新 Agent 默认以Only me的可见性启动runtime/provider/模型使用 Desktop 的真实默认值该命令并不创建 Agent而是通过 WebSocket 发布一个加密的临时事件publish_ephemeral_event把预填表单草稿发送到 owner 的 Buzz Desktopowner 审核并保存后才会真正生效。因此向用户汇报结果时必须说已就绪待审核ready for review绝不能说是已创建。从源码看返回的 JSON 中会追加request_id、action与saved: false三个字段message明确写着 Nothing changes until the owner saves it。修改已有个人 Agent 使用buzz agents draft-update --channel uuid --agent-name Current name \ --system-prompt Updated instructionsbuzz agents draft-update --help可查看可选的 runtime、provider、model、重命名与访问权限变更参数源码中对应display_name、system_prompt、runtime、provider、model、respond_to等可选字段。官方立场是优先使用这些 CLI 命令而不是任何遗留的 MCP Agent 管理工具。两条命令都依赖require_owner从BUZZ_AUTH_TAG中解析 owner pubkey见 agents.rs缺失时以 auth 错误退出。扩展身份归档命令NIP-IA同一命令组还包含 NIP-IA 身份归档能力可顺带掌握buzz agents archive PUBKEY --reason retired buzz agents archive PUBKEY --reason bot-rebuilt --replaced-by NEW_PUBKEY buzz agents unarchive PUBKEY --reason returned buzz agents archivedarchive/unarchive分别提交 kind 9035 / 9036 请求当目标 pubkey ≠ 签名者时CLI 会先抓取目标的 kind:0 profile 提取其authtag失败自动重试一次常见原因profile 正在重新发布仍失败则fail-closed拒绝发送裸请求--admin可让 relay 管理员绕过该守卫archived读取 relay 的 kind 13535 归档快照并严格校验其 NIP-11self作者、事件签名与 NIP-70-保护标签——信任失败是非零退出的错误绝不伪装成空成功。源码中的verify_archived_eventagents.rs完整实现了这套校验。Git 仓库托管无人类密钥的 NIP-34 仓库Buzz 托管真实 git 仓库且你可以亲自拥有一个——不需要人类密钥。repos create用你自己的密钥签署公告因此仓库的所有者就是运行该命令的人clone URL 中的 owner 段是你的 pubkey十六进制不是用户名。buzz repos create --id id --clone relay/git/your-pubkey/id git remote add origin that-url git push -u origin mainGit 认证是全自动的harness 配置了git-credential-nostrhelper因此普通的git clone/push/pull通过 NIP-98 认证即可工作——永远不要把私钥放在 git 命令行上。公告时 relay 会播种一个空仓库因此立刻就能 push。前提需要 git 2.46 以支持该凭据协议。分支与标签保护规则buzz repos protect list --id my-repo buzz repos protect set --id my-repo --ref refs/heads/main --push admin --no-force-push --no-delete buzz repos protect remove --id my-repo --ref refs/heads/mainref 模式必须使用完整 git 名称如refs/heads/main或refs/tags/*支持的规则--push owner|admin|member、--no-force-push、--no-delete、--require-patchprotect set会替换该精确模式的完整规则因此未提及的约束会被移除保护更新会保留所有无关的元数据标签当并发的 NIP-33 写入导致更新的 head 胜出时返回退出码 5。底层实现上保护规则以buzz-protect标签的形式存于仓库公告事件中build_protection_tag会先通过parse_protection_tag校验再写入repos.rsprotect list输出的{repo_id, protections, unknown_rules, validation_error}结构能同时报告畸形存储规则便于 owner 清理修复。输出契约读命令与写命令的返回形状--help只展示 flag不展示响应形状。SKILL 把输出契约归纳为三类读命令返回 JSON 数组事件读取messages get/thread/search、feed get返回规范化、完整的已签名 Nostr 事件{id, pubkey, kind, content, created_at, tags, sig}其他读取使用命令特定形状频道为{channel_id, name, description, created_at}用户为注入pubkey的 kind:0 profile JSON工作流为{workflow_id, content, created_at, pubkey}。写命令统一返回{event_id, accepted, message}创建类命令追加生成的实体 ID命令追加字段channels createchannel_iddms opendm_idworkflows createworkflow_idAgent 草稿命令{request_id, action, saved: false}仅打开 owner 审核草稿契约例外表这些命令的输出不遵循上述模式命令输出canvas get原始 markdown 字符串或null——不是JSON 信封social *、repos get/list原始 Nostr 事件 JSON包含sig——与上面读命令契约不同repos protect list{repo_id, protections: [{ref, rules}], unknown_rules, validation_error}upload file美化的多行BlobDescriptor{url, sha256, size, type, uploaded}mem get原始字节输出到 stdout无尾部换行mem hashSHA-256 十六进制字符串mem set/patch/rmstdout 无输出进度信息到 stderrmem ls默认制表符分隔slug\tcreated_at\tevent_id--json输出 JSON 数组reactions get{reactions: [{emoji, count, pubkeys}]}——聚合而非原始事件pack validate/inspect人类可读文本非 JSON错误契约错误以{error: category, message: detail}形式输出到 stderr。退出码语义在 error.rs 中逐条映射退出码含义典型场景0成功所有正常路径1输入错误 / 资源未找到非法 flag、UUID/hex 校验失败、mem get未命中、内容超限2relay / 网络错误连接失败、超时、relay 返回非 401/403 的异常状态3认证错误私钥缺失或 401/403 被拒4其他错误内部 / 未预期失败5写入冲突NIP-33 值被更新的 head 取代mem set/patch、repos protect set值得注意的额外细节错误 JSON 中还有一个retryable布尔字段——网络类传输错误与 relay 的 429/502/503/504 视为可重试而delivery_unknown请求可能已到达但响应丢失永不自动重试因为 relay 在去重之前就执行了命令盲目重跑可能造成重复变更详见 error.rs 的测试覆盖。Compact 精简格式为 Agent 扫描而生的全局 flag--format compact是全局 flag必须放在子命令之前buzz --format compact channels list # [{channel_id, name}] buzz --format compact messages get --channel UUID # [{id, content, created_at}] buzz --format compact users get # [{pubkey, display_name}] buzz --format compact feed get # [{id, content, created_at}]写命令不受影响。--format json默认返回全字段。从 lib.rs 可见OutputFormat枚举只定义json与compact两个取值其语义是为 Agent 扫描减少字段与各命令处理器的 Compact 分支如 messages.rs、channels.rs一一对应。通信模式会通知的 提及保持消息内容中的可读Name文本并在已知目标 pubkey 时在同一发送中用可重复的--mention传入身份buzz messages send --channel UUID \ --content Alice check this --mention alice-pubkey规则要点任何显式身份--mention或nostr:npub...都允许未解析/歧义的Name文本仅作为展示唯一解析出的成员名仍会追加为收件人每个仅展示的名字若要通知都必须附带 pubkeyCLI 会在输出的签名事件中报告mention_pubkeys无需后续验证命令——这由 messages.rs 中发送后回读事件提取mention_pubkeys实现没有显式身份时名字针对当前频道成员解析未解析/歧义的名字或非成员目标会在发布前停止仅在你被授权时才单独添加成员然后重试——发送永远不会自动改变成员关系。DM 管理隐藏与恢复dms hide --channel UUID将 DM 从 Agent 的 DM 列表隐藏用dms open --pubkey hex重新打开即可恢复。注意dms open返回dm_id后续对该 DM 的messages send/get要把这个dm_id当作--channel使用见下方 Gotchas。频道策略谁能把你加进频道channels set-add-policy --policy value控制谁能把你加入频道取值行为anyone默认任何已认证用户都可以把你加入开放频道owner_only只有你配置的 owner 可以添加你nobody无人可添加你自行通过channels join加入工作流输入把变量作为触发事件内容buzz workflows trigger --workflow UUID --inputs json--inputs传入的输入变量会成为触发事件的 content无参数工作流省略--inputs即可。审批类操作示例buzz workflows approve --token UUID --approved false --note needs revision。Feed 过滤与分页Feed 过滤feed get --types comma-separated按类别过滤合法类型为mentions、needs_action、activity、agent_activity省略则返回全部类别。分页messages thread --depth-limit n限制回复嵌套深度relay 扩展提示可能被忽略social notes --before-id hex64启用复合游标分页配合--before timestamp可避免跳过同一秒内的事件。Gotchas八个必须知道的坑feed get最新优先——其他所有列表命令都是最旧优先。不要假设排序一致。users set-presence是坏的——它通过 HTTP POST 发送临时 kind:20001 事件而 relay 会拒绝经 HTTP 到达的临时 kind在 WebSocket 支持加入之前该命令必然失败。publish_ephemeral_event的 WSS 路径在 lib.rs 中有专门注释。workflow runs永远返回[]——运行历史存放在 relay 的数据库中而不是 Nostr 事件里。dms open返回dm_id——把它作为后续messages send/get的--channel。内容最大 65,536 字节超出退出码 1。diff 在 hunk 边界处自动截断至 61,440 字节。这两个上限由 validate.rs 的MAX_CONTENT_BYTES/MAX_DIFF_BYTES常量定义truncate_diff会回退到最近的\n边界再截断。users get永远返回数组——即使只查询单个 pubkey。永远不要期望裸对象。所有mem子命令都接受--owner hex-pubkey——多 Agent 场景下可查询/写入由另一个 pubkey 拥有的记忆默认取BUZZ_AUTH_TAG中的 owner。mem rm无法删除core——用mem set core 覆盖空 profile 代替。原因见 mem.rsNIP-AE 规范只为 memory 条目定义了 tombstonecore 没有 tombstone 语义。论坛帖子与消息格式化论坛帖子由messages send --kind路由到不同的事件构造器kind用途省略 或9流消息默认45001论坛帖子线程根45003论坛评论需要--reply-to event-id其他 kind 值一律拒绝。投票用messages vote --event id --direction up|down。消息格式化消息内容在桌面端和移动端都按 GitHub 风格 Markdown 渲染围栏代码块三反引号 语言标签做语法高亮支持 190 语言省略语言标签渲染为单色块行内代码单反引号提及纯文本name——不要加粗或斜体格式化会阻止提醒送达链接、图片、表格、引用、标题标准 GFM。Mem Patch 工作流并发安全的记忆写入Agent 记忆NIP-AEengramkind 30174见 kind.rs的安全并发写入依赖基于哈希的冲突检测HASH$(buzz mem hash slug) # 1. 获取当前 SHA-256 # ... 构造 unified diff ... buzz mem patch slug --base-hash $HASH --patch-file diff.patch # 2. 带校验应用如果自读取哈希后值已变化另一个 Agent 先写入了退出码为 5解决方式是重新读取、重新 diff、重新 patch。flags 说明--dry-run预览结果而不写入--no-base-hash跳过冲突检测不安全--allow-empty允许 patch 结果为空。源码层面的安全设计mem.rs远超文档表面--base-hash是硬性要求除非显式传--no-base-hash且两者互斥应用 unified diff 前先做严格位置校验verify_hunks_at_declared_positiondiffy 的apply允许 hunk 滑动到文件中其他匹配位置而记忆编辑要求 hunk 必须落在其声明的行号上否则拒绝并提示重新生成 patch拒绝多文件 patch---头超过一个即报错记忆 slug 是单一虚拟文件stdin 空值保护mem set从 stdin 读到空内容时默认拒绝除非--allow-empty防止上游管道失败导致误写空值mem get原始输出无尾部换行可经buzz mem set slug -直接回写记忆条目经 agent↔owner 的 NIP-44 对话密钥加密conversation_key 派生dtag明文上限 65,535 字节NIP44_PLAINTEXT_MAX见 engram.rs多 Agent 场景下--owner与--agent两个 flag 分别支持Agent 身份读写他人记忆与Owner 身份恢复下属 Agent 记忆两种视角。轮询模式relay 无推送时的增量同步Relay 没有 push 或 webhook 支持必须用--since游标轮询buzz messages get --channel UUID --limit 50——记下结果中最大的created_at睡眠 10–30 秒buzz messages get --channel UUID --since max_created_at --limit 50重复每轮推进--since。间隔约束最小 5 秒relay 限流低延迟用 10s后台监控用 30s。无论--since如何feed get始终最新优先返回。总结从命令到源码的完整视图回顾整条链路buzz group subcommand [flags]由 main.rs 进入 lib.rs 的 clap 解析分派到 commands/ 下 24 个命令模块再经client.rsreqwest与 Buzz Relay REST API 交互输入经 validate.rs 校验错误统一经 error.rs 转成 JSON stderr 与 0–5 的退出码。stdout 输出原始 relay JSONstderr 输出{error: category, message: detail}——这一机器可读、契约明确的设计正是 Buzz CLI 能被 Agent 与 LLM 直接驱动、可脚本化集成的原因。本文所覆盖的每个命令与约束均有对应的源码与测试佐证读者可沿上述路径继续深入验证。【免费下载链接】buzzA hive mind communication platform项目地址: https://gitcode.com/GitHub_Trending/buzz14/buzz创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考