Ralph TUI - 创建 Beads
将 PRD 转换为 beads(epic + 子任务),用于 ralph-tui 自主执行。
注意: 此技能已与 ralph-tui 的 Beads tracker 插件捆绑。未来的 tracker 插件(Linear、GitHub Issues 等)将捆绑自己的任务创建技能。
任务
获取 PRD(markdown 文件或文本)并在 .beads/beads.jsonl 中创建 beads:
- 提取质量门:从 PRD 的“质量门”部分提取
- 为功能创建一个 epic bead
- 为每个用户故事创建 子 beads(附加质量门)
- 设置 beads 之间的 依赖关系(schema → 后端 → UI)
- 输出准备用于
ralph-tui run --tracker beads
第1步:提取质量门
在 PRD 中查找“质量门”部分:
## 质量门
每个用户故事都必须通过以下命令:
- `pnpm typecheck` - 类型检查
- `pnpm lint` - 代码检查
对于 UI 故事,还需包括:
- 使用 dev-browser 技能在浏览器中验证
提取:
- 通用门: 适用于所有故事的命令(例如
pnpm typecheck) - UI 门: 仅适用于 UI 故事的命令(例如浏览器验证)
如果没有质量门部分: 询问用户应该通过哪些命令,或使用合理的默认值如 npm run typecheck。
输出格式
Beads 使用 bd create 命令配合 HEREDOC 语法 以安全处理特殊字符:
# 创建 epic(链接回源 PRD)
bd create --type=epic \
--title="[功能名称]" \
--description="$(cat <<'EOF'
[PRD 中的功能描述]
EOF
)" \
--external-ref="prd:./tasks/feature-name-prd.md"
# 创建子 bead(质量门附加在验收标准中)
bd create \
--parent=EPIC_ID \
--title="[故事标题]" \
--description="$(cat <<'EOF'
[包含验收标准(含质量门)的故事描述]
EOF
)" \
--priority=[1-4]
关键: 始终使用
<<'EOF'(单引号)作为 HEREDOC 定界符。这可以防止 shell 解释描述中的反引号、$variables和()。
故事大小:头号规则
每个故事必须能在一次 ralph-tui 迭代(约一个 agent 上下文窗口)内完成。
ralph-tui 每次迭代都会生成一个新的 agent 实例,且不保留之前工作的记忆。如果故事太大,agent 会在完成之前耗尽上下文。
适当大小的故事:
- 添加数据库列 + 迁移
- 向现有页面添加 UI 组件
- 使用新逻辑更新 server action
- 向列表添加筛选下拉框
太大(需要拆分):
- “构建整个仪表盘” → 拆分为:schema、查询、UI 组件、筛选器
- “添加身份验证” → 拆分为:schema、中间件、登录 UI、会话处理
- “重构 API” → 拆分为每个端点或模式一个故事
经验法则: 如果你不能用 2-3 句话描述更改,则故事太大。
故事排序:依赖优先
故事按依赖顺序执行。较早的故事不能依赖于较晚的故事。
正确顺序:
- Schema/数据库更改(迁移)
- Server actions/后端逻辑
- 使用后端的 UI 组件
- 聚合数据的仪表盘/摘要视图
错误顺序:
- ❌ UI 组件(依赖于尚不存在的 schema)
- ❌ Schema 更改
使用 bd dep add 添加依赖
使用 bd dep add 命令指定哪些 beads 必须先完成:
# 先创建 beads
bd create --parent=epic-123 --title="US-001: 添加 schema" ...
bd create --parent=epic-123 --title="US-002: 创建 API" ...
bd create --parent=epic-123 --title="US-003: 构建 UI" ...
# 然后添加依赖(issue 依赖于 block-er)
bd dep add ralph-tui-002 ralph-tui-001 # US-002 依赖于 US-001
bd dep add ralph-tui-003 ralph-tui-002 # US-003 依赖于 US-002
语法: bd dep add <issue> <depends-on> — issue 依赖于(被阻塞于)depends-on。
ralph-tui 会:
- 将阻塞的 beads 显示为“blocked”,直到依赖完成
- 在依赖未关闭时,从不选择该 bead 执行
- 在处理 bead 时,在提示中包含依赖上下文
正确的依赖顺序:
- Schema/数据库更改(无依赖)
- 后端逻辑(依赖于 schema)
- UI 组件(依赖于后端)
- 集成/打磨(依赖于 UI)
验收标准:质量门 + 故事特定
每个 bead 的描述应包含验收标准,包括:
- 故事特定标准:来自 PRD(此故事完成什么)
- 质量门:来自 PRD 的质量门部分(附加在末尾)
好的标准(可验证):
- “在 investor 表中添加
investorType列,默认值为 'cold'” - “筛选下拉框具有选项:全部、Cold、Friend”
- “点击切换开关显示确认对话框”
差的标准(模糊):
- ❌ “工作正常”
- ❌ “用户可以轻松做 X”
- ❌ “良好的用户体验”
- ❌ “处理边缘情况”
转换规则
- 首先从 PRD 提取质量门
- 每个用户故事 → 一个 bead
- 第一个故事:无依赖(创建基础)
- 后续故事:依赖于前一个故事(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)
bd create --type=epic \
--title="朋友外联通道" \
--description="$(cat <<'EOF'
用于 Deck 反馈的暖外联
EOF
)" \
--external-ref="prd:./tasks/friends-outreach-prd.md"
# US-001:无依赖(第一个 - 创建 schema)
bd 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 故事(也有浏览器验证)
bd 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
bd dep add ralph-tui-002 ralph-tui-001
# US-003:UI 故事
bd 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
bd dep add ralph-tui-003 ralph-tui-002
输出位置
Beads 写入到:.beads/beads.jsonl
创建后,运行 ralph-tui:
# 处理特定 epic
ralph-tui run --tracker beads --epic ralph-tui-abc
# 或让它自动选择最佳任务
ralph-tui run --tracker beads
ralph-tui 会:
- 处理指定 epic 内的 beads(或选择最佳可用任务)
- 每个 bead 完成后关闭它
- 所有子任务完成后关闭 epic
- epic 完成后输出
<promise>COMPLETE</promise>
创建 Beads 前的检查清单
- 已从 PRD 提取质量门(如果缺失则询问用户)
- 每个故事可在一次迭代中完成(足够小)
- 故事按依赖顺序排序(schema → 后端 → UI)
- 质量门已附加到每个 bead 的验收标准中
- UI 故事具有浏览器验证(如果质量门中指定了)
- 验收标准是可验证的(不模糊)
- 没有故事依赖于较晚的故事(仅依赖较早的故事)
- 创建 beads 后使用
bd dep add添加了依赖