beadboard-driver

BeadBoard Driver

概述

本技能是操作手册，用于在以 BeadBoard 为控制平面的外部仓库中执行 Agent 任务。

核心原则：明确状态 + 明确分配 + 明确证据。

什么是 BeadBoard

BeadBoard 是一个面向由 bd 驱动的 Agent 工作的实时仪表板——它通过实时界面显示 Agent 的在线状态、状态转换、集群进度以及 Agent 间邮件。人类使用 BeadBoard UI 进行观察和协调；Agent 使用本技能发出信号（心跳、状态转换、邮件），驱动仪表板显示相应内容。

Agent 几乎从不在 BeadBoard 仓库中工作。 你在自己的项目仓库中工作。bb 和 bd 可通过 PATH 全局使用。本技能使用的脚本（预检、邮件垫片等）都捆绑在本技能文件夹中——你的 Agent 运行时知道本技能的安装位置，并会提供路径作为 {baseDir}（即包含此 SKILL.md 的目录）。

铁律

No bead claims, handoffs, or completion statements without:
1) assignee set,
2) coordination checked,
3) evidence recorded.

要求

• bd 必须已安装并可通过 PATH 使用。
• bb 或 beadboard 必须已全局安装并可通过 PATH 使用。
• 从目标仓库根目录开始工作。
• 安装 bd：npm install -g beads-cli
• 安装 bb：从 GitHub 克隆并全局安装——具体命令见步骤 0 的引导部分

会话操作手册（不要跳过步骤）

步骤 0：阅读 project.md——优先使用缓存进行判断

ls project.md 2>/dev/null && echo "EXISTS" || echo "MISSING"

不存在 → 你是此项目中的第一个 Agent。 运行下方的引导清单，然后返回这里。

存在 → 阅读 project.md 顶部的环境状态缓存表。

• 所有行均为 pass → 完全跳过步骤 1，直接进入步骤 2。 环境已通过验证。
• 任意一行为 fail 或 unknown → 只运行对应的检查（见步骤 1），修复问题，更新 project.md，然后继续。

project.md 就是令牌预算。状态为绿色时请相信它。只对实际损坏的部分进行检查。

---

引导清单

{baseDir} 是包含此 SKILL.md 的目录的绝对路径，由 Agent 运行时（Claude Code、Codex 等）自动注入。如果运行时不会自动替换此路径，请找到技能安装路径并手动替换为绝对路径。

当 project.md 不存在时，按顺序运行一次。

A. 检查 bd（beads-cli）

which bd 2>/dev/null || where bd 2>/dev/null

如果缺失：

npm install -g beads-cli

B. 初始化 beads 数据库（如果尚未初始化）

ls .beads 2>/dev/null && echo "EXISTS — skip" || bd init

必须先完成此步骤，才能运行任何 bd config 命令。如果 .beads 已存在，则跳过。

C. 检查 bb（BeadBoard）

which bb 2>/dev/null || where bb 2>/dev/null

如果缺失——协调工作需要 bb。请询问用户：

“尚未安装 BeadBoard。它是 Agent 协调工作所必需的。你希望我现在安装吗？我会克隆仓库并全局安装。”

如果用户同意：

git clone https://github.com/zenchantlive/beadboard.git ~/beadboard
cd ~/beadboard && npm install && npm install -g .

D. 配置邮件委托程序

node {baseDir}/scripts/setup-mail-delegate.mjs

自动解析垫片的绝对路径并运行 bd config set mail.delegate。

E. 运行会话预检

node {baseDir}/scripts/session-preflight.mjs

必须通过检查后才能继续。此步骤会检查 bd、bb，并确认委托程序已设置。

F. 创建 project.md

cp {baseDir}/project.template.md ./project.md

填写环境状态缓存表和项目身份部分中的所有字段。将每个已验证行的状态设为 pass，并填写今天的日期。这样可以避免下一个 Agent 重新运行以上所有步骤。

在会话日志中追加：

| YYYY-MM-DD | `<your-agent-bead-id>` | Initial project.md created, all checks pass |

---

步骤 1：检查环境（若 project.md 中全部为 Green，则跳过）

仅当 project.md 中存在 fail 或 unknown 行时，才运行此步骤。

只运行失败的检查：

失败的行	修复命令
bd 不在 PATH 上	npm install -g beads-cli
bb 不在 PATH 上	克隆 + npm install -g .（参见 Bootstrap C）
.beads 数据库	bd init（参见 Bootstrap B）
mail.delegate	node {baseDir}/scripts/setup-mail-delegate.mjs
session-preflight	node {baseDir}/scripts/session-preflight.mjs — 修复它报告的问题

{baseDir} 是包含此 SKILL.md 的目录。Agent 运行时会自动替换它。

修复后：将 project.md 中对应行更新为 pass，并填入今天的日期。

如果在 Windows 原生环境或 WSL2 上运行，请参阅 Platform Notes。

步骤 2：创建 Agent Bead 身份并验证邮件

bd create --title="Agent: bb-<role-name>" --description="<scope>" --type=task --priority=0 --label="gt:agent,role:<orchestrator|ui|graph|backend|infra>"

# Register in bb coordination system and set identity
bb agent register --name <role-name> --role <orchestrator|ui|graph|backend|infra>
export BB_AGENT=<role-name>

命名约定： 将你的 bd bead 命名为 bb-<role-name>（例如 bb-silver-scribe）。在 bb 中注册相同名称 <role-name>（例如 silver-scribe）。设置 BB_AGENT=<role-name>。这会关联两个身份系统：bd agent state bb-silver-scribe ... 使用 bead ID；bd mail send 会自动使用 BB_AGENT。

术语	示例	用途
<role-name>	silver-scribe	bb agent register --name、BB_AGENT、bd mail --to
Bead 标题	bb-silver-scribe	bd create --title
<agent-bead-id>	beadboard-0m9	bd agent state、bd slot set、bd update --assignee
BB_AGENT 值	silver-scribe	通过 export 设置；自动注入所有 bd mail 调用

现在已设置 BB_AGENT，验证完整邮件堆栈：

node {baseDir}/scripts/ensure-bb-mail-configured.mjs

预期结果：ok: true，且 delegate 和 actor 匹配。如果失败，请参阅 Failure Modes。

继续之前先检查收件箱：

bd mail inbox

领取工作前，先阅读并确认所有待处理消息。未确认的 HANDOFF 或 DECISION 消息可能会影响后续任务。

然后设置生命周期状态：

bd agent state <agent-bead-id> spawning
bd agent state <agent-bead-id> running

步骤 3：在 project.md 中记录任何环境变更

已在步骤 0 中读取 project.md。只有本次会话期间发生了变更时，才在此处更新——例如安装了新软件包、重新配置了 delegate，或发现了新的平台问题。如果没有变更，则完全跳过此步骤。

如果在步骤 1 中修复了 fail/unknown 行，现在将对应行更新为 pass，并填入今天的日期。

步骤 4：阅读硬记忆和任务上下文

# Select your primary domain first:
# memory-arch | memory-workflow | memory-agent | memory-ux | memory-reliability
bd query "label=memory AND label=mem-canonical AND label=<domain> AND status=closed" --sort updated --reverse
bd ready
bd show <target-bead-id>

选择与你的任务相匹配的领域：memory-arch（架构决策）、memory-workflow（会话协议）、memory-agent（Agent 设置/身份）、memory-ux（UI/UX）、memory-reliability（错误/恢复）。领域锚点 ID 位于 references/memory-system.md。

bd ready 会列出所有无阻塞、未分配且可领取的任务。查看输出并选择一个 <target-bead-id>，传入 bd show。

最低限度：阅读任务契约、依赖项、成功标准和阻塞项。

步骤 5：通过指派对象和 Hook 槽位领取工作

bd update <target-bead-id> --status in_progress --assignee <agent-bead-id>
bd slot set <agent-bead-id> hook <target-bead-id>
bd agent state <agent-bead-id> working

不要使用 --claim。请明确指定 --assignee。

第 6 步：执行 + 心跳 + 通过 Mail 协调

执行期间：

bd agent heartbeat <agent-bead-id>

LLM Agent（Claude Code）： 在每轮开始时以及运行长时间命令（构建、测试）前立即发送心跳。轮次之间没有消息是正常的，不要将其视为健康状态异常。每 5 分钟一次的频率仅适用于由持久守护进程支持的 Agent。

注意： Witness 强制执行层目前尚未运行，因此不会在错过心跳时自动将 Agent 标记为 dead。心跳会被记录并显示在 BeadBoard 仪表板中，但目前不会强制执行。守护进程的实现属于未来的 epic。

通过委派邮件进行协调：

bd mail 与 bb agent： bd mail inbox/send/read/ack 是轻量封装，会通过已配置的 shim 委派给 bb agent inbox/send/read/ack，并自动注入 BB_AGENT 作为发件人身份。在本技能中始终使用 bd mail。某些参考文档中会将原始 bb agent 命令列为底层等效命令；只有在未配置 shim 或需要直接进行 bb 级调试时才使用它们。

bd mail inbox
bd mail send --to <agent-or-role> --bead <bead-id> --category <HANDOFF|BLOCKED|DECISION|INFO> --subject "<short>" --body "<details>"
bd mail read <message-id>
bd mail ack <message-id>

遇到阻塞时：

• 发送 BLOCKED
• 将 bd agent state <agent-bead-id> stuck 设为阻塞状态
• 仅在得到干预／回复后恢复

最低轮询时机和频率请参见 references/coordination-system.md → Inbox Polling Protocol。

第 7 步：验证关卡（代码更改）

npm run typecheck
npm run lint
npm run test

没有本次会话中新鲜的命令输出，不要声称问题已修复／工作已完成。

第 8 步：发布证据、关闭并更新缓存

bd update <target-bead-id> --notes "<commands run + key outputs + files changed>"
bd close <target-bead-id> --reason "<what was completed>"
bd slot clear <agent-bead-id> hook
bd agent state <agent-bead-id> done

更新 project.md 中的 Environment Status Cache：

• 如果运行了测试：将 Tests last run 行设为 pass／fail + 今天的日期
• 如果运行了 preflight：更新 session-preflight 行
• 如果本次会话运行了 bb agent register：将 bb agent registered 行更新为 pass | BB_AGENT=<name> + 今天的日期
• 在 Session Log 中追加一行：| YYYY-MM-DD | <agent-bead-id> | <what you verified/changed> |

此更新可以避免下一个 Agent 重新运行你的检查。

第 9 步：回顾记忆

如果存在可复用的经验：

• 创建／取代规范的记忆决策 bead

如果没有可复用的经验：

• 记录：Memory review: no new reusable memory.

危险信号

如果你即将进行以下操作，请停下并纠正：

• 不保留 --assignee 历史记录就关闭
• 在会话开始／领取／关闭时跳过 bd mail 检查
• 没有验证关卡输出就声称已完成
• 将项目上下文写入技能文件夹，而不是仓库的 project.md
• 使用旧文档中已弃用的直接命令模式

正确使用文档索引

• references/session-lifecycle.md： 完整的端到端会话流程。
• references/agent-state-liveness.md： Agent 状态、心跳频率、存活状态解读。
• references/coordination-system.md： 规范的 bb-mail 命令接口和类别语义。
• references/coord-events-sessions-ack.md： 触发器映射、收件箱轮询协议、从阻塞到恢复的操作说明。
• references/command-matrix.md： 日常操作的准确命令清单。
• references/failure-modes.md： 确定性的诊断和恢复路径。
• references/memory-system.md： 记忆锚点、注入协议、晋升／取代规则。
• references/archetypes-templates-swarms.md： Swarm 组成、molecule 操作、工作者派发模式。
• references/missions-realtime.md： 实时／watcher／事件故障排查。
• references/creating-beads.md： 按规范命名、设置依赖项和工作流来创建 epic、任务和子任务。

总结

如果严格遵循本运行手册，任何 Agent 都可以在不了解上下文的情况下进入工作，安全协调，并交付可审计的成果，避免偏离目标。

平台说明

环境变量语法

Shell	命令
bash / zsh（WSL2、Linux、macOS）	export BB_AGENT=<name>
PowerShell（Windows 原生）	$env:BB_AGENT = "<name>"
cmd.exe（Windows 原生）	set BB_AGENT=<name>

邮件委托路径格式

配置 bd config set mail.delegate "node <path>/bb-mail-shim.mjs" 时：

环境	路径格式示例
WSL2	node /home/<you>/<project-path>/skills/beadboard-driver/scripts/bb-mail-shim.mjs
Windows 原生环境	node C:\Users\<you>\<project-path>\skills\beadboard-driver\scripts\bb-mail-shim.mjs

二进制检测

预检脚本会检查 bd 和 bb 是否位于 PATH 中。在 Windows 原生环境中，系统会使用 where 而不是 which。如果预检报告某个二进制文件缺失，但它实际上已安装，请在 shell 中运行 where bd 和 where bb 进行验证，并确保你使用的 shell 中已正确设置 PATH。