让 AI 在你睡觉时写代码：Ralph 无人值守持续交付实战手册

核心问题：如何零干预地把“需求清单”变成“可上线代码”？
一句话答案：用 Ralph——一个 80 行 Bash 脚本的自治循环，让大模型重复“读故事→写代码→跑测试→提交”直到全部通过。

本文欲回答的核心问题

Ralph 到底是什么，与“普通 AI Copilot”有何本质差异？
它在真实项目里如何跑通“需求→代码→交付”最小闭环？
想把自己的项目塞进 Ralph，需要哪些文件、命令与心智准备？
哪些场景适合“睡觉交付”，哪些场景会踩坑？
作者第一次跑通 13 个需求后的复盘与微调建议。

1. 初见 Ralph：一条会自己转弯的流水线

1.1 它不是什么

不是新模型，也不是 VS Code 插件。
不是“帮你写一段函数”的助手，而是“把整棵需求树砍完才停”的伐木机器人。

1.2 它到底是什么

一段 Bash 循环 + 三段文本文件，把任何支持 CLI 的 AI 代理（Amp、Claude Code、Cursor 等）封装成“无人值守流水线”：

while(有未完成的用户故事) {
  1. 读 prd.json 挑最高优先级的失败故事；
  2. 读 progress.txt 获取历史模式与踩坑笔记；
  3. 写代码、跑类型检查、跑测试；
  4. 全绿就 commit，标记故事通过；
  5. 把新学到的套路写回 progress.txt；
}

内存只在三个地方落地：Git 历史、progress.txt、prd.json。循环结束，分支即产品。

1.3 一张图看懂数据流

┌----------┐     ┌----------┐     ┌----------┐
│ prd.json │----►│  AI 代理  │----►│ Git 仓库 │
└----------┘     └----------┘     └----------┘
     ▲                 │                 │
     └-----------------┴--------┐        │
                progress.txt◄---┴--------┘

图片来源：Unsplash

2. 跑起来的第一分钟：安装与 Hello World

2.1 前置清单

Node ≥ 18（类型检查与测试脚本用）
带 CLI 的 AI 代理，本文以 Amp 为例
项目里已配好 npm run typecheck 与 npm test
Git 仓库干净，可有主分支保护

2.2 四步复制粘贴

新建目录
```
mkdir -p scripts/ralph
```
把官方样板拖进来（见下文代码块）。
给脚本开执行权
```
chmod +x scripts/ralph/ralph.sh
```
试运行 3 个迭代
```
./scripts/ralph/ralph.sh 3
```

如果看到 ✅ Done! 说明故事已全部通过；若看到 ⚠️ Max iterations reached 就是故事太大或测试不过。

2.3 样板文件一览

# scripts/ralph/ralph.sh
#!/usr/bin/env bash
set -e
MAX_ITERATIONS=${1:-10}
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

for i in $(seq 1 $MAX_ITERATIONS); do
  echo "═══ Iteration $i ═══"
  OUTPUT=$(cat "$SCRIPT_DIR/prompt.md" | amp --dangerously-allow-all 2>&1 | tee /dev/stderr) || true
  echo "$OUTPUT" | grep -q "<promise>COMPLETE</promise>" && echo "✅ Done!" && exit 0
  sleep 2
done
echo "⚠️ Max iterations reached"; exit 1

// scripts/ralph/prd.json
{
  "branchName": "ralph/feature",
  "userStories": [
    {
      "id": "US-001",
      "title": "Add login form",
      "acceptanceCriteria": [
        "Email/password fields",
        "Validates email format",
        "typecheck passes"
      ],
      "priority": 1,
      "passes": false
    }
  ]
}

# scripts/ralph/prompt.md
# Ralph Agent Instructions
## Your Task
1. Read `scripts/ralph/prd.json`
2. Read `scripts/ralph/progress.txt`
...
(下文同原文，此处省略)

3. 把“小需求”切成“可闭环”的 5 条模式

3.1 尺寸定律

必须能塞进一次上下文窗口。经验值：标题 ≤ 12 字，验收点 ≤ 4 条，每条 ≤ 20 字。

反例（❌）	正例（✅）
构建完整权限系统	添加登录表单
实现 RBAC 角色管理	新增角色表及枚举类型

3.2 反馈定律

类型检查 + 单测必须在 30 秒内跑完，否则迭代节奏会被拖垮。作者第一次跑时把 Jest 全量集成测试塞进来，结果单次迭代 4 分钟，一晚只交付 5 个故事。

3.3 显性定律

验收点里少写“用户可正常使用”，多写“可在 localhost:3000/login 看到红色错误提示”。AI 不会读心，只能读字面。

3.4 模式累积

progress.txt 顶部放“Codebase Patterns”小节，Ralph 会在后续迭代里自动复用：

Migrations: 用 IF NOT EXISTS
React: useRef<Timeout | null>(null)
这些模式随项目成长而成长，相当于给 AI 装了“本地肌肉记忆”。

3.5 分支隔离

Ralph 会自动切 branchName 指定分支，跑完后直接推远程，人类白天 Review & Merge。主分支历史保持线性，回滚只需 revert 一个 PR。

4. 真实战报：13 个故事，1 小时，零人工

4.1 需求池

作者给的是一个内部评估系统，含登录、题库、评分、导出 CSV 四块大功能，被拆成 13 个用户故事，优先级从 1 到 5。

4.2 跑表数据

总迭代：15 次
单次平均：2 分 40 秒
失败再试：2 次（均为测试端口占用）
最终 commit：13 个，全部绿灯

4.3 意外收获

第 10 次迭代后，Ralph 在 progress.txt 里自己总结：“本仓库使用 Server Actions，需在 actions.ts 里 export 类型，否则类型检查会丢。” 后续故事全部自动遵守，省却人类重复提醒。

4.4 反思 / 踩坑

第一次 prd.json 里把“导出 CSV”写成“支持 Excel”，结果 AI 跑去实现 xlsx 依赖，包体积暴涨 7 MB。验收点必须写具体格式。
默认迭代 10 次不够，我故事多，显式加到 25 次才安心。
一定要加 set -e，否则测试失败仍会继续循环，醒来看到一串红叉很沮丧。

5. 进阶调校：让 Ralph 认得你的家规

5.1 自定义停止词

在 prompt.md 尾部加：

If you create a new table, always add `created_at DATETIME DEFAULT CURRENT_TIMESTAMP`.

一次写入，终生遵守。

5.2 浏览器快照

UI 故事用 Amp 的 dev-browser skill， Ralph 可在迭代里截图留证。脚本示例见原文，核心三步：启动浏览器服务 → 用 tsx 脚本访问 → 保存 tmp/screenshot.png。commit 前把截图路径写进 progress.txt，人类 Review 时一眼可见。

5.3 多代理切换

Claude Code 权限控制更严，可把 ralph.sh 里 amp --dangerously-allow-all 换成 claude --dangerously-skip-permissions，其余零改动。团队里谁喜欢用什么代理就换什么。

6. 什么时候别用 Ralph

场景	风险
大额支付接口	无人工 Code Review，合规难
探索式架构	需求模糊，循环会原地打转
安全敏感模块	密钥、SQL 注入需人眼审计
无测试仓库	缺失反馈，AI 把坑越埋越深

一句话： Ralph 适合“边界清晰、验证自动、犯错成本低”的功能层。

7. 实用摘要 / 操作清单

拆故事：每条≤4 验收点，能在 30 分钟人工完成为准。
配反馈：npm run typecheck + npm test < 30 秒。
建文件：ralph.sh prompt.md prd.json progress.txt。
跑循环：./ralph.sh 25 上床睡觉。
早上看 PR，绿色就合并，红色加故事或改验收点再来。

8. One-page Summary

Ralph = Bash 循环 + 文本契约。
契约 = prd.json（任务） + progress.txt（记忆）。
AI 代理在循环里不断读契约、写代码、跑测试、写记忆，直到任务全部通过。
人类只负责“拆小需求”和“早上点合并”。

FAQ

Q：只能用在 Node 项目吗？
A：任何含 CLI 代理 + 可执行测试的语言均可，Go、Python、Rust 都已验证。
Q：循环会不会无限消耗 API 费用？
A：设 MAX_ITERATIONS 硬上限，且每次迭代 2 秒 sleep，费用可控。
Q：多人协作会冲突吗？
A：Ralph 自动切独立分支，与人类并行开发，冲突概率同常规 feature 分支。
Q：如何彻底重置记忆？
A：删 progress.txt 与 prd.json，重新建即可，Git 历史仍保留。
Q：AI 写出的代码风格不统一怎么办？
A：在 prompt.md 里加“必须跑 npm run lint:fix 并一起提交”，风格即自动对齐。
Q：可以白天跑着玩吗？
A：可以，但 Ralph 设计初衷是“无人值守”，白天用不如直接对话 AI 来得快。
Q：Windows 能跑吗？
A：需用 WSL2 或 Git Bash，原生 PowerShell 路径解析会出错。
Q：故事之间依赖顺序怎么保证？
A：用 priority 字段，数字越小越先执行；若强依赖，可拆到不同 Ralph 批次。

Ralph实战手册：让AI在你睡觉时写代码，80行Bash实现无人值守交付