Ralph TUI - 创建 Beads(beads-rust)
将 PRD 转换为 beads(史诗 + 子任务),用于 ralph-tui 基于 beads-rust(br CLI)的自主执行。
注意: 本技能使用 beads-rust 的
br命令。如果你安装的是原始 beads(bd),请改用ralph-tui-create-beads技能。
任务概述
获取一份 PRD(markdown 文件或文本),并使用 br 命令创建 beads:
- 从 PRD 中提取质量门禁
- 为该功能创建一个 epic bead
- 为每个用户故事创建 子 beads(附带质量门禁)
- 设置 beads 之间的 依赖关系(schema → 后端 → UI)
- 输出准备就绪,供
ralph-tui run --tracker beads-rust使用
步骤 1:提取质量门禁
在 PRD 中查找“质量门禁”部分:
## 质量门禁
以下命令必须在每个用户故事中通过:
- `pnpm typecheck` - 类型检查
- `pnpm lint` - 代码检查
对于 UI 故事,还需包含:
- 使用 dev-browser 技能在浏览器中验证
提取:
- 通用门禁: 适用于所有故事的命令(例如
pnpm typecheck) - UI 门禁: 仅适用于 UI 故事的命令(例如浏览器验证)
如果没有质量门禁部分: 询问用户哪些命令应该通过,或使用合理的默认值,如 npm run typecheck。
输出格式
Beads 使用 br create 命令配合 HEREDOC 语法 来安全处理特殊字符:
# 创建 epic(链接回原始 PRD)
br create --type=epic \
--title="[功能名称]" \
--description="$(cat <<'EOF'
[来自 PRD 的功能描述]
EOF
)" \
--external-ref="prd:./tasks/feature-name-prd.md"
# 创建子 bead(在验收标准中附带质量门禁)
br create \
--parent=EPIC_ID \
--title="[故事标题]" \
--description="$(cat <<'EOF'
[故事描述,包括包含质量门禁的验收标准]
EOF
)" \
--priority=[1-4]
关键: 始终使用
<<'EOF'(单引号)作为 HEREDOC 分隔符。这可以防止 shell 解释描述中的反引号、$variables和()。
故事大小:第一条规则
每个故事必须能在一次 ralph-tui 迭代中完成(大约一个代理上下文窗口)。
ralph-tui 每次迭代都会启动一个全新的代理实例,且没有之前工作的记忆。如果故事太大,代理会在完成前耗尽上下文。
大小合适的故事:
- 添加数据库列 + 迁移
- 在现有页面上添加 UI 组件
- 使用新逻辑更新服务器动作
- 在列表中添加筛选下拉菜单
太大的故事(请拆分):
- "构建整个仪表盘" → 拆分为:schema、查询、UI 组件、筛选器
- "添加认证" → 拆分为:schema、中间件、登录 UI、会话处理
- "重构 API" → 按端点或模式拆分为每个故事一个
经验法则: 如果你不能用 2-3 句话描述变更,那它就太大了。
故事排序:依赖优先
故事按依赖顺序执行。较早的故事不能依赖于较晚的故事。
正确顺序:
- Schema/数据库变更(迁移)
- 服务器动作 / 后端逻辑
- 使用后端的 UI 组件
- 聚合数据的仪表盘/摘要视图
错误顺序:
- ❌ UI 组件(依赖于尚不存在的 schema)
- ❌ Schema 变更
使用 br dep add 添加依赖
使用 br dep add 命令指定哪些 beads 必须首先完成:
# 先创建 beads
br create --parent=epic-123 --title="US-001: 添加 schema" ...
br create --parent=epic-123 --title="US-002: 创建 API" ...
br create --parent=epic-123 --title="US-003: 构建 UI" ...
# 然后添加依赖(issue 依赖于 blocker)
br dep add ralph-tui-002 ralph-tui-001 # US-002 依赖于 US-001
br dep add ralph-tui-003 ralph-tui-002 # US-003 依赖于 US-002
语法: br dep add <issue> <depends-on> — issue 依赖于(被阻塞于)depends-on。
ralph-tui 会:
- 在依赖项完成前,将阻塞的 beads 显示为“已阻塞”
- 当依赖项未关闭时,永远不会选择该 beads 执行
- 在处理一个 beads 时,在提示中包含依赖上下文
正确的依赖顺序:
- Schema/数据库变更(无依赖)
- 后端逻辑(依赖于 schema)
- UI 组件(依赖于后端)
- 集成/打磨(依赖于 UI)
验收标准:质量门禁 + 故事特定要求
每个 beads 的描述应包含验收标准,包括:
- PRD 中的故事特定标准(此故事要完成的内容)
- 来自 PRD 质量门禁部分的质量门禁(追加到末尾)
好的标准(可验证):
- "向 investor 表添加
investorType列,默认值为 'cold'" - "筛选下拉菜单包含选项:全部、Cold、Friend"
- "点击切换按钮显示确认对话框"
不好的标准(模糊):
- ❌ "能正常工作"
- ❌ "用户可以轻松地执行 X"
- ❌ "良好的用户体验"
- ❌ "处理边缘情况"
转换规则
- 首先从 PRD 中提取质量门禁
- 每个用户故事 → 一个 beads
- 第一个故事: 无依赖(创建基础)
- 后续故事: 依赖于它们的前置故事(UI 依赖于后端等)
- 优先级: 基于依赖顺序,然后是文档顺序(0=关键,2=中等,4=积压)
- 所有故事:
status: "open" - 验收标准: 故事标准 + 追加的质量门禁
- UI 故事: 还追加 UI 特定门禁(浏览器验证)
拆分大型 PRD
如果 PRD 中包含大型功能,请拆分它们:
原始:
"添加好友外展追踪功能,支持不同消息"
拆分为:
- US-001: 向数据库添加 investorType 字段
- US-002: 在投资者列表 UI 中添加类型切换
- US-003: 创建好友特定阶段推进逻辑
- US-004: 创建好友消息模板
- US-005: 为好友生成任务
- US-006: 按类型添加筛选
- US-007: 更新新投资者表单
- US-008: 更新仪表盘计数
每个都是一个可以独立完成并验证的专注变更。
示例
输入的 PRD:
# PRD: 好友外展
添加将投资者标记为“好友”以进行友好外展的功能。
## 质量门禁
以下命令必须在每个用户故事中通过:
- `pnpm typecheck` - 类型检查
- `pnpm lint` - 代码检查
对于 UI 故事,还需包含:
- 使用 dev-browser 技能在浏览器中验证
## 用户故事
### US-001: 向 investor 表添加 investorType 字段
**描述:** 作为开发者,我需要将投资者分类为 'cold' 或 'friend'。
**验收标准:**
- [ ] 添加 investorType 列:'cold' | 'friend'(默认 'cold')
- [ ] 生成并成功运行迁移
### US-002: 在投资者列表行中添加类型切换
**描述:** 作为 Ryan,我想直接从列表中切换投资者类型。
**验收标准:**
- [ ] 每行有 Cold | Friend 切换按钮
- [ ] 切换显示确认对话框
- [ ] 确认后:更新数据库中的类型
### US-003: 按类型筛选投资者
**描述:** 作为 Ryan,我想筛选列表以仅查看好友或 cold 投资者。
**验收标准:**
- [ ] 筛选下拉菜单:全部 | Cold | Friend
- [ ] 筛选条件持久化在 URL 参数中
输出的 beads:
# 创建 epic(链接回原始 PRD)
br create --type=epic \
--title="好友外展追踪" \
--description="$(cat <<'EOF'
针对 Deck 反馈的友好外展
EOF
)" \
--external-ref="prd:./tasks/friends-outreach-prd.md"
# US-001: 无依赖(第一个 - 创建 schema)
br create --parent=ralph-tui-abc \
--title="US-001: 向 investor 表添加 investorType 字段" \
--description="$(cat <<'EOF'
作为开发者,我需要将投资者分类为 'cold' 或 'friend'。
## 验收标准
- [ ] 添加 investorType 列:'cold' | 'friend'(默认 'cold')
- [ ] 生成并成功运行迁移
- [ ] pnpm typecheck 通过
- [ ] pnpm lint 通过
EOF
)" \
--priority=1
# US-002: UI 故事(也获得浏览器验证)
br create --parent=ralph-tui-abc \
--title="US-002: 在投资者列表行中添加类型切换" \
--description="$(cat <<'EOF'
作为 Ryan,我想直接从列表中切换投资者类型。
## 验收标准
- [ ] 每行有 Cold | Friend 切换按钮
- [ ] 切换显示确认对话框
- [ ] 确认后:更新数据库中的类型
- [ ] pnpm typecheck 通过
- [ ] pnpm lint 通过
- [ ] 使用 dev-browser 技能在浏览器中验证
EOF
)" \
--priority=2
# 添加依赖:US-002 依赖于 US-001
br dep add ralph-tui-002 ralph-tui-001
# US-003: UI 故事
br create --parent=ralph-tui-abc \
--title="US-003: 按类型筛选投资者" \
--description="$(cat <<'EOF'
作为 Ryan,我想筛选列表以仅查看好友或 cold 投资者。
## 验收标准
- [ ] 筛选下拉菜单:全部 | Cold | Friend
- [ ] 筛选条件持久化在 URL 参数中
- [ ] pnpm typecheck 通过
- [ ] pnpm lint 通过
- [ ] 使用 dev-browser 技能在浏览器中验证
EOF
)" \
--priority=3
# 添加依赖:US-003 依赖于 US-002
br dep add ralph-tui-003 ralph-tui-002
同步更改
创建 beads 后,同步以导出为 JSONL(用于 git 追踪):
br sync --flush-only
这将 SQLite 数据库导出到 .beads/issues.jsonl 以进行版本控制。
输出位置
Beads 存储在:.beads/ 目录(SQLite 数据库 + JSONL 导出)
创建后,运行 ralph-tui:
# 处理特定 epic
ralph-tui run --tracker beads-rust --epic ralph-tui-abc
# 或让它自动选择最佳任务
ralph-tui run --tracker beads-rust
ralph-tui 会:
- 处理指定 epic 中的 beads(或选择最佳可用任务)
- 每个 bead 完成后关闭它
- 所有子任务完成后关闭 epic
- 当 epic 完成时输出
<promise>COMPLETE</promise>
创建 Beads 前的检查清单
- 从 PRD 中提取了质量门禁(如果缺失则询问了用户)
- 每个故事可在一次迭代中完成(足够小)
- 故事按依赖顺序排序(schema → 后端 → UI)
- 质量门禁已追加到每个 beads 的验收标准中
- UI 故事包含浏览器验证(如果质量门禁中指定了)
- 验收标准是可验证的(不模糊)
- 没有故事依赖于较晚的故事(仅依赖于较早的故事)
- 创建 beads 后使用
br dep add添加了依赖 - 运行了
br sync --flush-only以导出供 git 追踪
与 beads(Go 版本)的差异
| 命令 | beads (bd) | beads-rust (br) |
|---|---|---|
| 创建 | bd create | br create |
| 依赖 | bd dep add | br dep add |
| 同步 | bd sync | br sync --flush-only |
| 关闭 | bd close | br close |
| 存储 | .beads/beads.jsonl | .beads/*.db + JSONL 导出 |