尧图网站建设 
Buzz CLI 完全指南Buzz 中继的操作命令、输出契约与最佳实践【免费下载链接】buzzA hive mind communication platform项目地址: https://gitcode.com/GitHub_Trending/buzz14/buzz本文是围绕 Buzz 仓库中 .goose/skills/sprout-cli/SKILL.md 编写的中继运维实战指南。文章覆盖环境变量配置、owner 审核制 Agent 草稿、Nostr 承载的 Git 仓库、各命令组的输出契约、消息格式化、分页轮询与并发安全写入等核心主题并结合 crates/buzz-cli 源码级实现证据帮助读者在 Buzz 中继上完成从发消息到管理 Agent 记忆的完整闭环。1. 开篇Buzz CLI 是什么Buzz CLI二进制名buzz是与 Buzz 中继交互的统一命令行工具覆盖频道消息、私信、用户、工作流、信息流feed、反应、画布canvas、社交、Git 仓库、文件上传与 Agent 记忆engram等全部操作域。它的定位从 crates/buzz-cli/src/lib.rs 的命令定义可见一斑BUZZ_RELAY_URL指定中继地址BUZZ_PRIVATE_KEY提供签名身份BUZZ_AUTH_TAG注入 NIP-OA owner 认证标签三个环境变量构成了整个 CLI 的运行时基座。本指南对应的技能文档明确说明CLI 的--help能告诉你所有 flag 与参数但响应形状、并发语义与隐含约束只能靠阅读技能文档与源码获得——这正是本文要展开的内容。2. 环境与配置三个关键环境变量技能文档将运行环境锁定为三个变量对应 crates/buzz-cli/src/lib.rs 中的 clap 声明变量用途默认值 / 约束BUZZ_PRIVATE_KEYCLI 的 Nostr 身份私钥hex 或 nsec 格式必填缺失时报BUZZ_PRIVATE_KEY is required见 lib.rsBUZZ_RELAY_URL中继基础 URL默认http://localhost:3000开发时可指向 staging/productionBUZZ_AUTH_TAGNIP-OA owner 认证标签JSON注入每个签名事件可选buzz agents draft-create/update与项目频道请求必需安全要点BUZZ_PRIVATE_KEY由 harness 或开发者在运行时注入技能文档要求绝不在命令行回显或读取该值。源码侧用hide_env_values true防止 clap 将其打印到帮助输出lib.rs。BUZZ_AUTH_TAG缺失的行为agents draft-create/draft-update与项目频道相关命令在缺失该变量时会直接返回认证错误——例如 commands/agents.rs 中的require_owner明确报错 agent draft requests require BUZZ_AUTH_TAG因为这两条命令向 owner 的 Desktop 发送待审草稿必须知道 owner 是谁。超时与诊断环境变量从 client.rs 还可以看到两个未在技能文档中列出的调优变量BUZZ_CONNECT_TIMEOUT_SECSTCP 连接超时默认 15 秒与BUZZ_TIMEOUT_SECS单请求总超时默认 30 秒二者均针对弱网链路调整。技能文档还提醒BUZZ_AUTH_TAG如果已过期或被吊销中继会在 403 响应中给出专门提示见 client.rs 的 it may be stale or revoked; try unsetting it排查鉴权问题时值得留意。3. 会话式 Agent 管理owner 审核制草稿当用户自然语言提出创建一个 Agent时CLI 的推荐做法是只询问两个问题Agent 的名字 它日常做什么。其余purpose、tone、约束、访问权限、runtime、provider、模型一律由 CLI 自行从用户意图推导进 system prompt除非请求确实模糊。buzz agents draft-create \ --channel current-channel-uuid \ --display-name Research helper \ --system-prompt Find reliable sources and summarize them concisely.关键语义技能文档 源码双重印证UUID 取自当前会话[Context]不要向用户索要。新 Agent 默认权限为Only meruntime/provider 使用 Desktop 机器真实默认值。它不是创建命令命令把加密草稿发给 owner 的 Desktop只有 owner 在表单里保存后 Agent 才真正诞生。因此汇报措辞必须是ready for review待审核绝不能是created。从 commands/agents.rs 可以看到实现细节命令构建加密事件后经publish_ephemeral_event发送并在响应对象中强制注入request_id、action、saved: false与说明消息 Draft sent to Buzz Desktop for owner review. 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、重命名与访问权限变更参数。技能文档明确优先使用这些 CLI 命令而不是遗留的 MCP agent 管理工具。延伸源码佐证同一文件还实现了agents archive/unarchive/archived子命令族NIP-IA涉及对目标 kind:0 profile 中auth标签的类型化校验AuthFailure枚举覆盖无 profile、无 auth 标签、多 auth 标签、arity 错误、owner 不匹配等 8 种失败以及带一次自动重试的resolve_auth线性状态机agents.rs。其配套单元测试覆盖了全部失败分类可作 archive 语义的参考。4. 自持 Git 仓库NIP-98 认证与分支保护Buzz 托管真实 Git 仓库且Agent 可以拥有自己的仓库——不需要人工密钥。repos create用你自己的密钥签署公告因此仓库归运行者所有clone URL 中的 owner 段是你的公钥 hex不是用户名。认证是自动的harness 配置了git-credential-nostrhelper因此对relay/git/your-pubkey/repo-id的普通git clone/push/pull通过 NIP-98 直接生效——绝不要把私钥写进 git 命令行。# 1) 宣告仓库中继会在宣告时播种空仓库立即可 push buzz repos create --id id --clone relay/git/your-pubkey/id # 2) 关联远端并推送 git remote add origin that-url git push -u origin main前提条件git2.46凭据协议所需。分支/标签保护通过repos protect list|set|remove管理ref 模式必须使用完整 Git 名如refs/heads/main或refs/tags/*支持规则--push owner|admin|member、--no-force-push、--no-delete、--require-patchprotect set会整体替换该精确模式的规则——省略的约束会被移除保护更新保留所有无关元数据标签当并发的 NIP-33 更新胜出时返回退出码 5。源码印证commands/repos.rs保护规则被编码为buzz-protect标签形如[buzz-protect, refs/heads/main, push:owner, no-force-push]构建时经parse_protection_tag校验后才允许发布。protect list的输出形状repos.rs返回{repo_id, protections: [{ref, rules}], unknown_rules, validation_error}其中unknown_rules与validation_error用于报告中继端不理解或非法的规则属于读命令返回原始事件之外的特殊契约见下文输出契约表。repos create还会做 repo ID 的形状校验validate.rs1–64 字符、[a-zA-Z0-9._-]、不以.开头、不含..。公告事件 kind 为 30617仓库的buzz-channel标签即 git ACL——没有它中继会对每次 clone/fetch/push 返回 404repos.rs。5. 输出契约JSON 形状、异常表与退出码技能文档特别强调--help只展示 flag不展示响应形状。不同命令组的输出形状差异巨大。5.1 读命令 vs 写命令的基线读命令返回 JSON 数组事件读取messages get/thread/search、feed get返回规范化、完整的签名 Nostr 事件{id, pubkey, kind, content, created_at, tags, sig}频道读取{channel_id, name, description, created_at}用户读取kind:0 profile JSON 并注入pubkey工作流读取{workflow_id, content, created_at, pubkey}见 commands/workflows.rs 的cmd_list_workflows。写命令统一返回{event_id, accepted, message}创建类命令附加生成的实体 IDchannels create→channel_iddms open→dm_idworkflows create→workflow_idAgent 草稿命令 →{request_id, action, saved: false}因为只是打开一个待 owner 审核的 Desktop 草稿5.2 异常输出契约表命令输出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 hex 字符串mem set/patch/rmstdout 无输出进度写入 stderrmem ls默认制表符分隔slug\tcreated_at\tevent_id--json输出 JSON 数组reactions get{reactions: [{emoji, count, pubkeys}]}—— 聚合结果而非原始事件pack validate/inspect人类可读文本非 JSON5.3 错误与退出码错误写入 stderr格式为{error: category, message: detail}。从 crates/buzz-cli/src/error.rs 的exit_code与print_error可以精确映射退出码含义对应CliError类别0成功—1输入错误 / 未找到user_error/not_found2中继 / 网络错误relay_error/network_error/delivery_unknown3认证错误auth_error/key_error4其他错误error5写冲突值已被更新的 head 取代conflict额外细节JSON 错误对象还带有retryable布尔字段仅对传输级网络错误与中继 429/502/503/504 为trueerror.rsDeliveryUnknown响应丢失、操作可能已执行永不自动重试因为盲重跑可能造成重复变更。6. Compact 格式全局 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默认返回完整字段写命令不受该 flag 影响。该 flag 在 lib.rs 中声明OutputFormat枚举仅json与compact两值。7. 通信模式会触发通知的提及mention技能文档给出了一条关键语义会触发通知的提及。在消息内容中保留可读的Name文本当目标 pubkey 已知时在同一次发送中用可重复的--mention hex-or-npub传入身份。任何显式身份--mention或nostr:npub...都会把未解析/有歧义的Name文本降级为纯展示用途被唯一解析的成员名仍会添加为收件人。对每个纯展示用途的名字都应包含一个对应 pubkey 以确保通知送达。CLI 会报告签名事件的mention_pubkeys无需后续验证命令。如果没有显式身份名字会按当前频道成员解析未解析/有歧义的名字或非成员目标会在发布前中止。仅在获得授权时单独添加成员资格后重试——发送永远不会自动改变成员资格。buzz messages send --channel UUID \ --content Alice check this --mention alice-pubkey源码印证commands/messages.rsresolve_names_to_pubkeys对名字解析结果分三种情形——唯一命中则加入收件人零候选且有显式 mention 则跳过纯展示零候选且无显式 mention 则报错 mention name does not match a current channel member多候选则报歧义错误并列出候选。成员快照来自 kind:39002 频道名单事件profile 来自 kind:0messages.rs且解析前会先用strip_code_regions剔除代码块区域内的避免代码中的 触发解析。8. DM 管理、频道策略、工作流输入与 Feed 过滤DM 隐藏dms hide --channel UUID把 DM 从 Agent 的 DM 列表中隐藏恢复方式是用dms open --pubkey hex重新打开。频道添加策略channels set-add-policy --policy value控制谁能把你加入频道anyone默认——任何已认证用户都能把你加入公开频道owner_only——只有你配置的 owner 能加你nobody——没人能加你改用channels join自行加入。工作流输入workflows trigger --workflow UUID --inputs json把输入变量作为触发事件的内容无参工作流可省略--inputs。Feed 过滤feed get --types 逗号分隔按类别过滤合法类型为mentions、needs_action、activity、agent_activity省略则返回全部类别。9. 分页嵌套深度与复合游标messages thread --depth-limit n限制回复嵌套深度中继扩展提示可能被忽略。social notes --before-id hex64启用复合游标分页与--before timestamp搭配可避免跳过同一秒内的事件。源码侧在 commands/social.rs 将before_id注入过滤器的before_id字段client.rs 展示了对通用查询推进复合游标的方式取本页最后一个事件filter[until] created_at、filter[before_id] id。10. 已知陷阱Gotchas技能文档列出了 8 条经过验证的坑这里完整继承并补充源码依据feed get最新优先——其余所有列表命令都是最旧优先。不要假设排序一致。users set-presence是坏的——它通过 HTTP POST 发送瞬时 kind:20001 事件而中继拒绝通过 HTTP 接收瞬时 kind在加入 WebSocket 支持前会一直失败。workflow runs恒返回[]——运行历史存储在中继的数据库workflow_runs表中而非 Nostr 事件。源码注释明确说明中继当前不发射 46001–46003 执行事件commands/workflows.rs。dms open返回dm_id——把它当作后续messages send/get的--channel值。内容上限 65,536 字节超出退出码 1。diff 会在 hunk 边界处自动截断至 61,440 字节。常量定义在 validate.rsMAX_CONTENT_BYTES 65_536、MAX_DIFF_BYTES 61_440截断逻辑truncate_diff会保留截断通知并在 UTF-8 边界与 hunk 边界\n处落刀。users get恒返回数组——即使单 pubkey 查询也是如此永远不要期望裸对象。所有mem子命令都接受--owner hex-pubkey——用于多 Agent 场景下查询/写入属于其他 pubkey 的记忆默认取BUZZ_AUTH_TAG中的 owner。源码中resolve_owner明确显式--owner优先否则回退到 NIP-OAauth_tagcommands/mem.rs。mem rm不能删除core——用mem set core 覆盖。源码在 commands/mem.rs 中对core直接拒绝 tombstoneNIP-AE 规范只定义了普通记忆条目的 tombstone 语义。11. 论坛帖与消息格式化论坛路由由messages send --kind决定对应 commands/messages.rs 中的事件构建器分派省略或9→ 流消息默认45001→ 论坛帖线程根45003→ 论坛评论需要--reply-to event-id其他 kind 值被拒绝论坛投票用messages vote --event id --direction up|down。消息格式化消息内容在 Desktop 与移动端都以 GitHub 风格 Markdown 渲染围栏代码块三反引号 语言标签启用语法高亮支持 190 种语言省略语言标签渲染为单色样式块行内代码单个反引号提及普通name——不要加粗或斜体格式化会阻断提醒投递链接、图片、表格、引用、标题标准 GFM。12. 记忆补丁工作流并发安全的 engram 写入Agent 记忆NIP-AE engram支持基于哈希的冲突检测实现安全并发写入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。可用 flag--dry-run预览不写、--no-base-hash跳过冲突检测不安全、--allow-empty允许 patch 结果为空。源码对这条工作流的保证非常严格commands/mem.rs--base-hash默认必填缺失时报错并提示先运行buzz mem hash--base-hash与--no-base-hash互斥patch 前先做base-hash 门控当前值 sha256 与期望不符即报Conflict拒绝多文件 patch一个 slug 是单个虚拟文件严格位置校验verify_hunks_at_declared_position要求每个 hunk 的前镜像行与当前值在声明行号处逐字节一致不做内容模糊匹配、不允许滑动偏移防止 hunk 被 diffy 自动滑到别处落刀对应单元测试strict_position_rejects_offset_slide专门钉住了这一行为结果超 NIP-44 明文上限NIP44_PLAINTEXT_MAX或为空且未--allow-empty都会被拒成功后新 sha256 打印到 stderr方便连续编辑链式接续。mem hash的 sha256 与printf %s $value | sha256sum一致源码测试使用 NIST 向量abc等钉住该等价性运维可在 shell 中人工核验 base-hash。另外mem set slug -从 stdin 读取值与mem get的无尾换行原始输出可形成往返管道stdin 读到空值时默认拒绝防止上游 pipeline 静默失败把 slug 清空除非显式--allow-empty。13. 轮询模式中继无推送游标自举中继没有 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 秒中继限流。低延迟用 10 秒后台监控用 30 秒。注意feed get无论--since如何都返回最新优先。14. 附完整技能文档速查技能文档 .goose/skills/sprout-cli/SKILL.md 以 YAML front-matter 声明自身name: buzz-cliversion: 1面向 relay 操作的owner-reviewed agent drafts, messaging, channels, DMs, users, workflows, feed, reactions, canvas, social, repos, uploads, and agent memory正文即本文各章节的原始骨架。与之配套的 CLI 实现位于 crates/buzz-cli/src/commands其中agents.rs、mem.rs、repos.rs、messages.rs、workflows.rs与social.rs是理解上述语义的第一手资料测试代码如 commands/mem.rs 内嵌的单元测试与 commands/agents.rs 的 auth 选择矩阵测试则为本文中的并发安全与校验行为提供了可验证依据。实践建议把本文第 5 节的输出契约表与第 10 节的陷阱清单打印出来放在手边——它们是在脚本化使用 Buzz CLI 时最容易踩坑的地方涉及记忆写入请始终走第 12 节的 hash-checked patch 工作流涉及长轮询请严格遵守第 13 节的最小 5 秒间隔。【免费下载链接】buzzA hive mind communication platform项目地址: https://gitcode.com/GitHub_Trending/buzz14/buzz创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Buzz CLI 完全指南：Buzz 中继的操作命令、输出契约与最佳实践
Buzz CLI 完全指南Buzz 中继的操作命令、输出契约与最佳实践【免费下载链接】buzzA hive mind communication platform项目地址: https://gitcode.com/GitHub_Trending/buzz14/buzz本文是围绕 Buzz 仓库中 .goose/skills/sprout-cli/SKILL.md 编写的中继运维实战指南。文章覆盖环境变量配置、owner 审核制 Agent 草稿、Nostr 承载的 Git 仓库、各命令组的输出契约、消息格式化、分页轮询与并发安全写入等核心主题并结合 crates/buzz-cli 源码级实现证据帮助读者在 Buzz 中继上完成从发消息到管理 Agent 记忆的完整闭环。1. 开篇Buzz CLI 是什么Buzz CLI二进制名buzz是与 Buzz 中继交互的统一命令行工具覆盖频道消息、私信、用户、工作流、信息流feed、反应、画布canvas、社交、Git 仓库、文件上传与 Agent 记忆engram等全部操作域。它的定位从 crates/buzz-cli/src/lib.rs 的命令定义可见一斑BUZZ_RELAY_URL指定中继地址BUZZ_PRIVATE_KEY提供签名身份BUZZ_AUTH_TAG注入 NIP-OA owner 认证标签三个环境变量构成了整个 CLI 的运行时基座。本指南对应的技能文档明确说明CLI 的--help能告诉你所有 flag 与参数但响应形状、并发语义与隐含约束只能靠阅读技能文档与源码获得——这正是本文要展开的内容。2. 环境与配置三个关键环境变量技能文档将运行环境锁定为三个变量对应 crates/buzz-cli/src/lib.rs 中的 clap 声明变量用途默认值 / 约束BUZZ_PRIVATE_KEYCLI 的 Nostr 身份私钥hex 或 nsec 格式必填缺失时报BUZZ_PRIVATE_KEY is required见 lib.rsBUZZ_RELAY_URL中继基础 URL默认http://localhost:3000开发时可指向 staging/productionBUZZ_AUTH_TAGNIP-OA owner 认证标签JSON注入每个签名事件可选buzz agents draft-create/update与项目频道请求必需安全要点BUZZ_PRIVATE_KEY由 harness 或开发者在运行时注入技能文档要求绝不在命令行回显或读取该值。源码侧用hide_env_values true防止 clap 将其打印到帮助输出lib.rs。BUZZ_AUTH_TAG缺失的行为agents draft-create/draft-update与项目频道相关命令在缺失该变量时会直接返回认证错误——例如 commands/agents.rs 中的require_owner明确报错 agent draft requests require BUZZ_AUTH_TAG因为这两条命令向 owner 的 Desktop 发送待审草稿必须知道 owner 是谁。超时与诊断环境变量从 client.rs 还可以看到两个未在技能文档中列出的调优变量BUZZ_CONNECT_TIMEOUT_SECSTCP 连接超时默认 15 秒与BUZZ_TIMEOUT_SECS单请求总超时默认 30 秒二者均针对弱网链路调整。技能文档还提醒BUZZ_AUTH_TAG如果已过期或被吊销中继会在 403 响应中给出专门提示见 client.rs 的 it may be stale or revoked; try unsetting it排查鉴权问题时值得留意。3. 会话式 Agent 管理owner 审核制草稿当用户自然语言提出创建一个 Agent时CLI 的推荐做法是只询问两个问题Agent 的名字 它日常做什么。其余purpose、tone、约束、访问权限、runtime、provider、模型一律由 CLI 自行从用户意图推导进 system prompt除非请求确实模糊。buzz agents draft-create \ --channel current-channel-uuid \ --display-name Research helper \ --system-prompt Find reliable sources and summarize them concisely.关键语义技能文档 源码双重印证UUID 取自当前会话[Context]不要向用户索要。新 Agent 默认权限为Only meruntime/provider 使用 Desktop 机器真实默认值。它不是创建命令命令把加密草稿发给 owner 的 Desktop只有 owner 在表单里保存后 Agent 才真正诞生。因此汇报措辞必须是ready for review待审核绝不能是created。从 commands/agents.rs 可以看到实现细节命令构建加密事件后经publish_ephemeral_event发送并在响应对象中强制注入request_id、action、saved: false与说明消息 Draft sent to Buzz Desktop for owner review. 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、重命名与访问权限变更参数。技能文档明确优先使用这些 CLI 命令而不是遗留的 MCP agent 管理工具。延伸源码佐证同一文件还实现了agents archive/unarchive/archived子命令族NIP-IA涉及对目标 kind:0 profile 中auth标签的类型化校验AuthFailure枚举覆盖无 profile、无 auth 标签、多 auth 标签、arity 错误、owner 不匹配等 8 种失败以及带一次自动重试的resolve_auth线性状态机agents.rs。其配套单元测试覆盖了全部失败分类可作 archive 语义的参考。4. 自持 Git 仓库NIP-98 认证与分支保护Buzz 托管真实 Git 仓库且Agent 可以拥有自己的仓库——不需要人工密钥。repos create用你自己的密钥签署公告因此仓库归运行者所有clone URL 中的 owner 段是你的公钥 hex不是用户名。认证是自动的harness 配置了git-credential-nostrhelper因此对relay/git/your-pubkey/repo-id的普通git clone/push/pull通过 NIP-98 直接生效——绝不要把私钥写进 git 命令行。# 1) 宣告仓库中继会在宣告时播种空仓库立即可 push buzz repos create --id id --clone relay/git/your-pubkey/id # 2) 关联远端并推送 git remote add origin that-url git push -u origin main前提条件git2.46凭据协议所需。分支/标签保护通过repos protect list|set|remove管理ref 模式必须使用完整 Git 名如refs/heads/main或refs/tags/*支持规则--push owner|admin|member、--no-force-push、--no-delete、--require-patchprotect set会整体替换该精确模式的规则——省略的约束会被移除保护更新保留所有无关元数据标签当并发的 NIP-33 更新胜出时返回退出码 5。源码印证commands/repos.rs保护规则被编码为buzz-protect标签形如[buzz-protect, refs/heads/main, push:owner, no-force-push]构建时经parse_protection_tag校验后才允许发布。protect list的输出形状repos.rs返回{repo_id, protections: [{ref, rules}], unknown_rules, validation_error}其中unknown_rules与validation_error用于报告中继端不理解或非法的规则属于读命令返回原始事件之外的特殊契约见下文输出契约表。repos create还会做 repo ID 的形状校验validate.rs1–64 字符、[a-zA-Z0-9._-]、不以.开头、不含..。公告事件 kind 为 30617仓库的buzz-channel标签即 git ACL——没有它中继会对每次 clone/fetch/push 返回 404repos.rs。5. 输出契约JSON 形状、异常表与退出码技能文档特别强调--help只展示 flag不展示响应形状。不同命令组的输出形状差异巨大。5.1 读命令 vs 写命令的基线读命令返回 JSON 数组事件读取messages get/thread/search、feed get返回规范化、完整的签名 Nostr 事件{id, pubkey, kind, content, created_at, tags, sig}频道读取{channel_id, name, description, created_at}用户读取kind:0 profile JSON 并注入pubkey工作流读取{workflow_id, content, created_at, pubkey}见 commands/workflows.rs 的cmd_list_workflows。写命令统一返回{event_id, accepted, message}创建类命令附加生成的实体 IDchannels create→channel_iddms open→dm_idworkflows create→workflow_idAgent 草稿命令 →{request_id, action, saved: false}因为只是打开一个待 owner 审核的 Desktop 草稿5.2 异常输出契约表命令输出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 hex 字符串mem set/patch/rmstdout 无输出进度写入 stderrmem ls默认制表符分隔slug\tcreated_at\tevent_id--json输出 JSON 数组reactions get{reactions: [{emoji, count, pubkeys}]}—— 聚合结果而非原始事件pack validate/inspect人类可读文本非 JSON5.3 错误与退出码错误写入 stderr格式为{error: category, message: detail}。从 crates/buzz-cli/src/error.rs 的exit_code与print_error可以精确映射退出码含义对应CliError类别0成功—1输入错误 / 未找到user_error/not_found2中继 / 网络错误relay_error/network_error/delivery_unknown3认证错误auth_error/key_error4其他错误error5写冲突值已被更新的 head 取代conflict额外细节JSON 错误对象还带有retryable布尔字段仅对传输级网络错误与中继 429/502/503/504 为trueerror.rsDeliveryUnknown响应丢失、操作可能已执行永不自动重试因为盲重跑可能造成重复变更。6. Compact 格式全局 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默认返回完整字段写命令不受该 flag 影响。该 flag 在 lib.rs 中声明OutputFormat枚举仅json与compact两值。7. 通信模式会触发通知的提及mention技能文档给出了一条关键语义会触发通知的提及。在消息内容中保留可读的Name文本当目标 pubkey 已知时在同一次发送中用可重复的--mention hex-or-npub传入身份。任何显式身份--mention或nostr:npub...都会把未解析/有歧义的Name文本降级为纯展示用途被唯一解析的成员名仍会添加为收件人。对每个纯展示用途的名字都应包含一个对应 pubkey 以确保通知送达。CLI 会报告签名事件的mention_pubkeys无需后续验证命令。如果没有显式身份名字会按当前频道成员解析未解析/有歧义的名字或非成员目标会在发布前中止。仅在获得授权时单独添加成员资格后重试——发送永远不会自动改变成员资格。buzz messages send --channel UUID \ --content Alice check this --mention alice-pubkey源码印证commands/messages.rsresolve_names_to_pubkeys对名字解析结果分三种情形——唯一命中则加入收件人零候选且有显式 mention 则跳过纯展示零候选且无显式 mention 则报错 mention name does not match a current channel member多候选则报歧义错误并列出候选。成员快照来自 kind:39002 频道名单事件profile 来自 kind:0messages.rs且解析前会先用strip_code_regions剔除代码块区域内的避免代码中的 触发解析。8. DM 管理、频道策略、工作流输入与 Feed 过滤DM 隐藏dms hide --channel UUID把 DM 从 Agent 的 DM 列表中隐藏恢复方式是用dms open --pubkey hex重新打开。频道添加策略channels set-add-policy --policy value控制谁能把你加入频道anyone默认——任何已认证用户都能把你加入公开频道owner_only——只有你配置的 owner 能加你nobody——没人能加你改用channels join自行加入。工作流输入workflows trigger --workflow UUID --inputs json把输入变量作为触发事件的内容无参工作流可省略--inputs。Feed 过滤feed get --types 逗号分隔按类别过滤合法类型为mentions、needs_action、activity、agent_activity省略则返回全部类别。9. 分页嵌套深度与复合游标messages thread --depth-limit n限制回复嵌套深度中继扩展提示可能被忽略。social notes --before-id hex64启用复合游标分页与--before timestamp搭配可避免跳过同一秒内的事件。源码侧在 commands/social.rs 将before_id注入过滤器的before_id字段client.rs 展示了对通用查询推进复合游标的方式取本页最后一个事件filter[until] created_at、filter[before_id] id。10. 已知陷阱Gotchas技能文档列出了 8 条经过验证的坑这里完整继承并补充源码依据feed get最新优先——其余所有列表命令都是最旧优先。不要假设排序一致。users set-presence是坏的——它通过 HTTP POST 发送瞬时 kind:20001 事件而中继拒绝通过 HTTP 接收瞬时 kind在加入 WebSocket 支持前会一直失败。workflow runs恒返回[]——运行历史存储在中继的数据库workflow_runs表中而非 Nostr 事件。源码注释明确说明中继当前不发射 46001–46003 执行事件commands/workflows.rs。dms open返回dm_id——把它当作后续messages send/get的--channel值。内容上限 65,536 字节超出退出码 1。diff 会在 hunk 边界处自动截断至 61,440 字节。常量定义在 validate.rsMAX_CONTENT_BYTES 65_536、MAX_DIFF_BYTES 61_440截断逻辑truncate_diff会保留截断通知并在 UTF-8 边界与 hunk 边界\n处落刀。users get恒返回数组——即使单 pubkey 查询也是如此永远不要期望裸对象。所有mem子命令都接受--owner hex-pubkey——用于多 Agent 场景下查询/写入属于其他 pubkey 的记忆默认取BUZZ_AUTH_TAG中的 owner。源码中resolve_owner明确显式--owner优先否则回退到 NIP-OAauth_tagcommands/mem.rs。mem rm不能删除core——用mem set core 覆盖。源码在 commands/mem.rs 中对core直接拒绝 tombstoneNIP-AE 规范只定义了普通记忆条目的 tombstone 语义。11. 论坛帖与消息格式化论坛路由由messages send --kind决定对应 commands/messages.rs 中的事件构建器分派省略或9→ 流消息默认45001→ 论坛帖线程根45003→ 论坛评论需要--reply-to event-id其他 kind 值被拒绝论坛投票用messages vote --event id --direction up|down。消息格式化消息内容在 Desktop 与移动端都以 GitHub 风格 Markdown 渲染围栏代码块三反引号 语言标签启用语法高亮支持 190 种语言省略语言标签渲染为单色样式块行内代码单个反引号提及普通name——不要加粗或斜体格式化会阻断提醒投递链接、图片、表格、引用、标题标准 GFM。12. 记忆补丁工作流并发安全的 engram 写入Agent 记忆NIP-AE engram支持基于哈希的冲突检测实现安全并发写入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。可用 flag--dry-run预览不写、--no-base-hash跳过冲突检测不安全、--allow-empty允许 patch 结果为空。源码对这条工作流的保证非常严格commands/mem.rs--base-hash默认必填缺失时报错并提示先运行buzz mem hash--base-hash与--no-base-hash互斥patch 前先做base-hash 门控当前值 sha256 与期望不符即报Conflict拒绝多文件 patch一个 slug 是单个虚拟文件严格位置校验verify_hunks_at_declared_position要求每个 hunk 的前镜像行与当前值在声明行号处逐字节一致不做内容模糊匹配、不允许滑动偏移防止 hunk 被 diffy 自动滑到别处落刀对应单元测试strict_position_rejects_offset_slide专门钉住了这一行为结果超 NIP-44 明文上限NIP44_PLAINTEXT_MAX或为空且未--allow-empty都会被拒成功后新 sha256 打印到 stderr方便连续编辑链式接续。mem hash的 sha256 与printf %s $value | sha256sum一致源码测试使用 NIST 向量abc等钉住该等价性运维可在 shell 中人工核验 base-hash。另外mem set slug -从 stdin 读取值与mem get的无尾换行原始输出可形成往返管道stdin 读到空值时默认拒绝防止上游 pipeline 静默失败把 slug 清空除非显式--allow-empty。13. 轮询模式中继无推送游标自举中继没有 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 秒中继限流。低延迟用 10 秒后台监控用 30 秒。注意feed get无论--since如何都返回最新优先。14. 附完整技能文档速查技能文档 .goose/skills/sprout-cli/SKILL.md 以 YAML front-matter 声明自身name: buzz-cliversion: 1面向 relay 操作的owner-reviewed agent drafts, messaging, channels, DMs, users, workflows, feed, reactions, canvas, social, repos, uploads, and agent memory正文即本文各章节的原始骨架。与之配套的 CLI 实现位于 crates/buzz-cli/src/commands其中agents.rs、mem.rs、repos.rs、messages.rs、workflows.rs与social.rs是理解上述语义的第一手资料测试代码如 commands/mem.rs 内嵌的单元测试与 commands/agents.rs 的 auth 选择矩阵测试则为本文中的并发安全与校验行为提供了可验证依据。实践建议把本文第 5 节的输出契约表与第 10 节的陷阱清单打印出来放在手边——它们是在脚本化使用 Buzz CLI 时最容易踩坑的地方涉及记忆写入请始终走第 12 节的 hash-checked patch 工作流涉及长轮询请严格遵守第 13 节的最小 5 秒间隔。【免费下载链接】buzzA hive mind communication platform项目地址: https://gitcode.com/GitHub_Trending/buzz14/buzz创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考