Beads Wisps 使用指南用 vapor 相分子管理一次性运维工作【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads运营类工作流——发布检查清单、健康巡检、诊断任务——一旦关闭它们产生的 bead 就失去了任何审计价值。Wisps蜃景分子正是在这种场景下诞生的它们是实例化于vapor 相气态相的分子molecule是你能用正常bd命令照常推进的真实 bead只是被打上了Ephemeraltrue标记从而不参与同步、也不进入共享审计轨迹之后可以整体批量删除。本文以 docs/workflows/wisps.md 为核心结合 Beads 仓库的 CLI 实现主要位于 cmd/bd与存储层代码系统讲解 Wisps 的定义、与持久分子Pour的差异、完整生命周期操作、批量管理与回收策略以及何时该提升squash而非焚毁burn一个 Wisp。什么是 Wisps从概念上讲Wisp 具备三个核心特征本质是普通 issueWisp 是主数据库中设置了 ephemeral 标记的 issue你可以用所有常规bd命令bd ready、bd update、bd close正常推进它它只是活不过自己的使命。本地优先设计默认被排除在联邦推送之外federation.exclude_types默认为[wisp]也不属于共享审计轨迹的一部分。批量删除关闭后由bd purge或bd mol wisp gc批量清理。这一设计在配置层有直接印证在 internal/config/config.go 中Beads 显式设置了默认值v.SetDefault(federation.exclude_types, []string{wisp})其注释说明这正是从联邦推送中排除的 issue 类型隐私过滤器。也就是说Wisp 从配置层面就是一个刻意与共享审计轨迹隔离的隐私安全区——巡检、排障、发布执行这些过程数据不会污染主审计流。在存储与 API 层同样存在完整的 ephemeral 支持例如 internal/storage/dolt/ephemeral_routing.go 专门负责 ephemeral 记录的读写路由internal/httpapi/reads.go 等 HTTP API 也提供对 ephemeral 记录的处理说明 Wisp 机制贯穿 CLI、存储与 HTTP API 三层。Wisp 与 Pour气态与液态的选择bd mol命令族用物相来区分两种分子实例化方式见 cmd/bd/mol.go 的命令总览Pour浇铸bd mol pour—— 液态相liquid phase实例化出持久分子写入历史、参与同步适合任何日后值得回引用的工作。Wisp蜃景bd mol wisp—— 气态相vapor phase实例化出临时分子用完即焚适合发布执行、运维循环、健康检查。两者在实现上的分水岭就是spawnMolecule函数中的ephemeral参数见 cmd/bd/mol.go它把Ephemeral: ephemeral写进CloneOptions再交给底层的cloneSubgraph去实例化整个子图。也就是说bd mol pour与bd mol wisp共享同一套子图克隆与变量替换机制唯一的差异就是这一个 ephemeral 开关。维度分子bd mol pourWispbd mol wisp持久性永久属于历史的一部分临时任务结束即清除同步像普通 bead 一样同步默认排除在联邦推送之外适用场景功能开发、任何日后值得引用的事发布执行、运维循环、健康检查Formula 的 vapor 相声明Formulas配方可以声明phase vapor来推荐 wisp 实例化——此时如果仍然执行 pour浇铸一个 vapor 相配方Beads 会给出警告。这给了团队一种把运维流程固化成模板并默认以临时实例落地的标准化手段同一个发布配方既可以被浇铸成带审计的持久分子也可以被实例化成用完即删的 wisp取舍权交给操作者。Wisp 的完整生命周期Wisp 的生命周期可以拆成创建 → 执行 → 收尾三个阶段官方文档给出的操作序列如下# 1. 创建 —— 从 proto 模板实例化或临时即兴创建 bd mol wisp proto-id [--var keyvalue] bd create One-off check --ephemeral # 2. 执行 —— 常规 bd 操作对 wisp issue 完全可用 bd ready --mol wisp-id bd update id --claim bd close id # 3a. 保留squash 提升为持久记录清除 ephemeral 标记 bd mol squash wisp-id # 3b. 焚毁直接删除不生成 digest bd mol burn wisp-id创建模板实例化与即兴创建两条创建路径各有适用场景bd mol wisp proto-id [--var keyvalue]从一个 proto模板实例化出整套工作子图--var用于替换模板中的{{key}}变量。适合把标准化流程发布、巡检快速展开为一次性执行副本。bd create One-off check --ephemeral即兴创建一个带 ephemeral 标记的单一 issue适合临时想到的快速检查。在 cmd/bd/create.go 中可以看到--ephemeral与--no-history是互斥的--ephemeral and --no-history are mutually exclusive而--storage-class ephemeral则是--ephemeral的完整拼写形式同样与--no-history互斥如果显式指定了其他 storage-class如versioned/unversioned又与 ephemeral 语义冲突命令会直接拒绝。这说明 ephemeral 是一个独立的wisp-plane气态平面记录概念与 durable持久类记录是正交的两套语义不能混用。执行与普通 issue 无异Wisp 是真实的 bead这一设计决定了它的执行路径零学习成本bd ready、bd update --claim、bd close等所有常规命令都直接作用于 wisp issue。这也正是文档所称real beads you work through normally的工程落地——CLI 层没有为 wisp 另起一套命令只是在其生命周期收尾时提供专用操作。收尾的两种结局每个 wisp 最终都要面对二选一bd mol squash wisp-id把 wisp 的临时子 issue 汇总成一份摘要 digest并将子项提升为持久记录清除Ephemeraltrue标记。从 cmd/bd/mol_squash.go 的实现看squash 会收集分子下所有 ephemeral 子 issue → 生成摘要 digestEphemeralfalse永久保留→ 清除子项的 wisp 标记完成提升 → 若根节点也是 wisp 则自动关闭它并清除其标记避免该根节点在每个 wisp 表导出周期中被反复重新发射。bd mol burn wisp-id不生成 digest 直接删除且不可逆。burn 的细节与安全护栏cmd/bd/mol_burn.go 的实现给出了 burn 的完整行为按相分流Wispephemeral走直接删除路径burnWispMolecule持久分子mol走级联删除路径burnPersistentMolecule会同步到远端。批量支持bd mol burn bd-a1 bd-b2 bd-c3可一次焚毁多个分子并自动按 ephemeral/持久分类处理。安全选项--dry-run预览将删除的内容、--force或-y跳过确认、不传--force时会有Continue? [y/N]交互确认wisp 焚毁在单个事务内原子完成burnWisps通过transact包裹任一删除失败则整体回滚杜绝部分删除。明确提示burn 前会提醒不会生成 digest若想保留摘要请用bd mol squash。从源码注释看burn 的典型适用对象包括废弃的巡检循环、崩溃或失败的工作流、以及不想保留的测试/调试分子。管理 Wisps列表、GC 与全量清除官方文档给出三个管理命令bd mol wisp list # 列出当前上下文中的所有 wisps bd mol wisp gc # 垃圾回收陈旧/废弃的 wisps bd purge --force # 删除所有已关闭的 ephemeral beadsbd purge的实现位于 cmd/bd/purge.go其定位是删除已关闭的 ephemeral beads 以回收空间并且与处理持久记录的bd prune明确分工、互不越界。值得注意的几个细节默认安全bd purge不带--force时只是预览DryRun: dryRun || !force必须显式加--force才真正执行删除。时效过滤bd purge --older-than 7d --force只清理关闭 7 天以上的记录。模式过滤bd purge --pattern *-wisp-*只清除 ID 匹配 glob 的记录适合只清理某一批特定命名的 wisp。这些参数让bd purge从一刀切变成可精细控制的批量回收可以在运维节奏中定期执行。强制物相用 bond 覆盖相位bd mol bond在组合工作时接受相位覆盖。官方文档的示例非常典型bd mol bond mol-critical-bug wisp-patrol --pour # 把巡检中发现的 bug 持久化为正式记录这个场景精准体现了 wisp 的价值在一次 wisp 巡检wisp-patrol中发现了严重 bug你并不想让这次巡检本身进入审计轨迹但 bug 本身必须被正式记录。--pour覆盖让组合结果以持久相位落地实现了过程临时、成果永久的完美分工。最佳实践什么该 wisp什么该 pourWisps 用于运维循环——巡检、发布执行、诊断任务这类结束即无价值的工作。Molecules 用于受跟踪工作——任何有审计价值的内容都应该 pour而不是 wisp。删除之前先 squash——如果 wisp 暴露出了值得保留的成果用bd mol squash提升它burn 不可逆。定期垃圾回收——bd mol wisp gc或bd purge --force防止临时记录堆积占用存储。从仓库的测试覆盖也能看出这条工作流是被认真对待的一等公民例如 internal/storage/dolt/count_include_wisps_test.go 验证统计是否包含 wisp、internal/storage/dolt/demote_to_wisp_test.go 验证降级为 wisp 的路径、cmd/bd/import_promoted_wisp_embedded_test.go 验证被 squash 提升后的 wisp 在导入导出中的表现。这些测试共同确认了 wisp 在创建、计数、降级、提升、导入导出各环节的行为一致性。小结Wisps 是 Beads 为过程无价、结果归零的运维类工作设计的轻量记录形态以Ephemeraltrue标记与持久记录区隔默认不参与联邦推送与审计轨迹配合bd mol wisp创建、bd mol squash提升、bd mol burn焚毁、bd purge批量回收组成完整的生命周期闭环。理解 Wisp 与 Pour 的分工、掌握 squash/burn 的取舍是让 Beads 仓库在长期演进中保持审计轨迹干净、存储不膨胀的关键实践。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/12 11:05:39 · 阅读 1.2k Beads Wisps 使用指南：用 vapor 相分子管理一次性运维工作
Beads Wisps 使用指南用 vapor 相分子管理一次性运维工作【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads运营类工作流——发布检查清单、健康巡检、诊断任务——一旦关闭它们产生的 bead 就失去了任何审计价值。Wisps蜃景分子正是在这种场景下诞生的它们是实例化于vapor 相气态相的分子molecule是你能用正常bd命令照常推进的真实 bead只是被打上了Ephemeraltrue标记从而不参与同步、也不进入共享审计轨迹之后可以整体批量删除。本文以 docs/workflows/wisps.md 为核心结合 Beads 仓库的 CLI 实现主要位于 cmd/bd与存储层代码系统讲解 Wisps 的定义、与持久分子Pour的差异、完整生命周期操作、批量管理与回收策略以及何时该提升squash而非焚毁burn一个 Wisp。什么是 Wisps从概念上讲Wisp 具备三个核心特征本质是普通 issueWisp 是主数据库中设置了 ephemeral 标记的 issue你可以用所有常规bd命令bd ready、bd update、bd close正常推进它它只是活不过自己的使命。本地优先设计默认被排除在联邦推送之外federation.exclude_types默认为[wisp]也不属于共享审计轨迹的一部分。批量删除关闭后由bd purge或bd mol wisp gc批量清理。这一设计在配置层有直接印证在 internal/config/config.go 中Beads 显式设置了默认值v.SetDefault(federation.exclude_types, []string{wisp})其注释说明这正是从联邦推送中排除的 issue 类型隐私过滤器。也就是说Wisp 从配置层面就是一个刻意与共享审计轨迹隔离的隐私安全区——巡检、排障、发布执行这些过程数据不会污染主审计流。在存储与 API 层同样存在完整的 ephemeral 支持例如 internal/storage/dolt/ephemeral_routing.go 专门负责 ephemeral 记录的读写路由internal/httpapi/reads.go 等 HTTP API 也提供对 ephemeral 记录的处理说明 Wisp 机制贯穿 CLI、存储与 HTTP API 三层。Wisp 与 Pour气态与液态的选择bd mol命令族用物相来区分两种分子实例化方式见 cmd/bd/mol.go 的命令总览Pour浇铸bd mol pour—— 液态相liquid phase实例化出持久分子写入历史、参与同步适合任何日后值得回引用的工作。Wisp蜃景bd mol wisp—— 气态相vapor phase实例化出临时分子用完即焚适合发布执行、运维循环、健康检查。两者在实现上的分水岭就是spawnMolecule函数中的ephemeral参数见 cmd/bd/mol.go它把Ephemeral: ephemeral写进CloneOptions再交给底层的cloneSubgraph去实例化整个子图。也就是说bd mol pour与bd mol wisp共享同一套子图克隆与变量替换机制唯一的差异就是这一个 ephemeral 开关。维度分子bd mol pourWispbd mol wisp持久性永久属于历史的一部分临时任务结束即清除同步像普通 bead 一样同步默认排除在联邦推送之外适用场景功能开发、任何日后值得引用的事发布执行、运维循环、健康检查Formula 的 vapor 相声明Formulas配方可以声明phase vapor来推荐 wisp 实例化——此时如果仍然执行 pour浇铸一个 vapor 相配方Beads 会给出警告。这给了团队一种把运维流程固化成模板并默认以临时实例落地的标准化手段同一个发布配方既可以被浇铸成带审计的持久分子也可以被实例化成用完即删的 wisp取舍权交给操作者。Wisp 的完整生命周期Wisp 的生命周期可以拆成创建 → 执行 → 收尾三个阶段官方文档给出的操作序列如下# 1. 创建 —— 从 proto 模板实例化或临时即兴创建 bd mol wisp proto-id [--var keyvalue] bd create One-off check --ephemeral # 2. 执行 —— 常规 bd 操作对 wisp issue 完全可用 bd ready --mol wisp-id bd update id --claim bd close id # 3a. 保留squash 提升为持久记录清除 ephemeral 标记 bd mol squash wisp-id # 3b. 焚毁直接删除不生成 digest bd mol burn wisp-id创建模板实例化与即兴创建两条创建路径各有适用场景bd mol wisp proto-id [--var keyvalue]从一个 proto模板实例化出整套工作子图--var用于替换模板中的{{key}}变量。适合把标准化流程发布、巡检快速展开为一次性执行副本。bd create One-off check --ephemeral即兴创建一个带 ephemeral 标记的单一 issue适合临时想到的快速检查。在 cmd/bd/create.go 中可以看到--ephemeral与--no-history是互斥的--ephemeral and --no-history are mutually exclusive而--storage-class ephemeral则是--ephemeral的完整拼写形式同样与--no-history互斥如果显式指定了其他 storage-class如versioned/unversioned又与 ephemeral 语义冲突命令会直接拒绝。这说明 ephemeral 是一个独立的wisp-plane气态平面记录概念与 durable持久类记录是正交的两套语义不能混用。执行与普通 issue 无异Wisp 是真实的 bead这一设计决定了它的执行路径零学习成本bd ready、bd update --claim、bd close等所有常规命令都直接作用于 wisp issue。这也正是文档所称real beads you work through normally的工程落地——CLI 层没有为 wisp 另起一套命令只是在其生命周期收尾时提供专用操作。收尾的两种结局每个 wisp 最终都要面对二选一bd mol squash wisp-id把 wisp 的临时子 issue 汇总成一份摘要 digest并将子项提升为持久记录清除Ephemeraltrue标记。从 cmd/bd/mol_squash.go 的实现看squash 会收集分子下所有 ephemeral 子 issue → 生成摘要 digestEphemeralfalse永久保留→ 清除子项的 wisp 标记完成提升 → 若根节点也是 wisp 则自动关闭它并清除其标记避免该根节点在每个 wisp 表导出周期中被反复重新发射。bd mol burn wisp-id不生成 digest 直接删除且不可逆。burn 的细节与安全护栏cmd/bd/mol_burn.go 的实现给出了 burn 的完整行为按相分流Wispephemeral走直接删除路径burnWispMolecule持久分子mol走级联删除路径burnPersistentMolecule会同步到远端。批量支持bd mol burn bd-a1 bd-b2 bd-c3可一次焚毁多个分子并自动按 ephemeral/持久分类处理。安全选项--dry-run预览将删除的内容、--force或-y跳过确认、不传--force时会有Continue? [y/N]交互确认wisp 焚毁在单个事务内原子完成burnWisps通过transact包裹任一删除失败则整体回滚杜绝部分删除。明确提示burn 前会提醒不会生成 digest若想保留摘要请用bd mol squash。从源码注释看burn 的典型适用对象包括废弃的巡检循环、崩溃或失败的工作流、以及不想保留的测试/调试分子。管理 Wisps列表、GC 与全量清除官方文档给出三个管理命令bd mol wisp list # 列出当前上下文中的所有 wisps bd mol wisp gc # 垃圾回收陈旧/废弃的 wisps bd purge --force # 删除所有已关闭的 ephemeral beadsbd purge的实现位于 cmd/bd/purge.go其定位是删除已关闭的 ephemeral beads 以回收空间并且与处理持久记录的bd prune明确分工、互不越界。值得注意的几个细节默认安全bd purge不带--force时只是预览DryRun: dryRun || !force必须显式加--force才真正执行删除。时效过滤bd purge --older-than 7d --force只清理关闭 7 天以上的记录。模式过滤bd purge --pattern *-wisp-*只清除 ID 匹配 glob 的记录适合只清理某一批特定命名的 wisp。这些参数让bd purge从一刀切变成可精细控制的批量回收可以在运维节奏中定期执行。强制物相用 bond 覆盖相位bd mol bond在组合工作时接受相位覆盖。官方文档的示例非常典型bd mol bond mol-critical-bug wisp-patrol --pour # 把巡检中发现的 bug 持久化为正式记录这个场景精准体现了 wisp 的价值在一次 wisp 巡检wisp-patrol中发现了严重 bug你并不想让这次巡检本身进入审计轨迹但 bug 本身必须被正式记录。--pour覆盖让组合结果以持久相位落地实现了过程临时、成果永久的完美分工。最佳实践什么该 wisp什么该 pourWisps 用于运维循环——巡检、发布执行、诊断任务这类结束即无价值的工作。Molecules 用于受跟踪工作——任何有审计价值的内容都应该 pour而不是 wisp。删除之前先 squash——如果 wisp 暴露出了值得保留的成果用bd mol squash提升它burn 不可逆。定期垃圾回收——bd mol wisp gc或bd purge --force防止临时记录堆积占用存储。从仓库的测试覆盖也能看出这条工作流是被认真对待的一等公民例如 internal/storage/dolt/count_include_wisps_test.go 验证统计是否包含 wisp、internal/storage/dolt/demote_to_wisp_test.go 验证降级为 wisp 的路径、cmd/bd/import_promoted_wisp_embedded_test.go 验证被 squash 提升后的 wisp 在导入导出中的表现。这些测试共同确认了 wisp 在创建、计数、降级、提升、导入导出各环节的行为一致性。小结Wisps 是 Beads 为过程无价、结果归零的运维类工作设计的轻量记录形态以Ephemeraltrue标记与持久记录区隔默认不参与联邦推送与审计轨迹配合bd mol wisp创建、bd mol squash提升、bd mol burn焚毁、bd purge批量回收组成完整的生命周期闭环。理解 Wisp 与 Pour 的分工、掌握 squash/burn 的取舍是让 Beads 仓库在长期演进中保持审计轨迹干净、存储不膨胀的关键实践。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考