Ralph + Claude Code 自主开发实战：从 PRD 到 15 个功能全部交付

30 分钟，15 个 User Story，从零到全部完成。这不是魔法，是 Ralph 自主开发工作流的实战记录。

什么是 Ralph？

Ralph 是一个轻量级的自主开发代理框架，核心理念很简单：

把需求写成结构化的 prd.json
Ralph 循环调用 AI 编码工具（Claude Code / Amp）
每轮只做一个 User Story
完成后自动标记 passes: true，继续下一个
全部完成输出 <promise>COMPLETE</promise>

它不是一个复杂的系统，而是一个 Bash 脚本 + CLAUDE.md 指令 + prd.json 任务清单 的组合。但正是这种简洁，让它极其可靠。

背景：AgentHub 知识库管理缺失

我们的 AgentHub 智能体平台已有基础的知识库功能（上传文档、检索），但用户反馈了一堆问题：

知识库创建后无法改名
一个文档分片数为 0（索引失败），无法重试
无法查看文档的分片内容
检索结果没有相似度分数
不支持批量上传
Excel 文件上传失败

对比 Dify 和 Coze，我们缺了太多管理功能。

第一步：生成 PRD 文档

按照 Ralph 的 PRD skill 规范，生成 tasks/prd-knowledge-base-management.md：

markdown

# PRD: 知识库管理功能增强

## Goals
- 允许用户编辑知识库名称和描述
- 允许用户查看、编辑、删除单个文档
- 提供分片列表查看和内容编辑能力
- 支持失败文档重新索引
- 检索结果附带相似度分数
- 支持批量上传文档

## User Stories

### US-001: 知识库更新 API（重命名/描述）
**Acceptance Criteria:**
- [ ] 新增 PUT /api/datasets/{id} 端点
- [ ] 验证 name 非空，长度不超过 100 字符
- [ ] Typecheck passes
...

关键原则：每个 Story 足够小，一轮就能完成。

第二步：转换为 prd.json

Ralph 不直接读 markdown，需要转成 JSON 格式：

json

{
  "project": "AgentHub",
  "branchName": "ralph/knowledge-base-management",
  "description": "知识库管理功能增强",
  "userStories": [
    {
      "id": "US-001",
      "title": "知识库更新 API",
      "acceptanceCriteria": [
        "新增 PUT /api/datasets/{id} 端点",
        "Typecheck passes"
      ],
      "priority": 1,
      "passes": false
    }
  ]
}

Story 排序的黄金法则：依赖在先，被依赖在后。

我们的顺序：

后端 Schema/API（US-001 ~ US-008）
前端 UI（US-009 ~ US-015）

前端 Story 不可能比后端 API 先完成——因为没有接口可调。

第三步：安装 Ralph 到项目

bash

mkdir -p scripts/ralph
cp /path/to/ralph/ralph.sh scripts/ralph/
cp /path/to/ralph/CLAUDE.md scripts/ralph/
chmod +x scripts/ralph/ralph.sh

目录结构：

agent-platform/
├── scripts/ralph/
│   ├── ralph.sh          # 主循环脚本
│   ├── CLAUDE.md          # Claude Code 的指令文件
│   ├── prd.json           # 任务清单
│   └── progress.txt       # 进度日志
├── backend/               # Spring Boot 后端
└── frontend/              # React 前端

第四步：启动 Ralph

标准方式（需要 amp 或 claude 可用）：

bash

cd scripts/ralph
./ralph.sh --tool claude 15

我们遇到的坑： claude --dangerously-skip-permissions 不能在 root 下运行。解决方案是用 --print --allowedTools 模式：

bash

claude --print --allowedTools 'Read,Write,Edit,Bash' <<PROMPT
Read prd.json. Pick the highest priority story where passes is false.
Implement it. Update prd.json when done.
PROMPT

手动用循环替代 ralph.sh：

bash

for i in $(seq 1 15); do
  claude --print --allowedTools 'Read,Write,Edit,Bash' <<PROMPT
  Read prd.json. Pick the highest priority story where passes is false.
  Implement that single story. Update prd.json to set passes: true.
  Append progress to progress.txt.
  PROMPT
done

执行过程：30 分钟实录

后端 API（US-001 ~ US-008）

Story	功能	耗时
US-001	`PUT /api/datasets/{id}` 更新知识库	~2min
US-002	`DELETE /datasets/{did}/documents/{docid}` 删文档	~2min
US-003	`PUT /datasets/{did}/documents/{docid}` 重命名文档	~2min
US-004	`GET /segments` 分片列表查询（分页）	~3min
US-005	`PUT /segments/{sid}` 分片编辑+重新向量化	~3min
US-006	`POST /reindex` 文档重新索引	~2min
US-007	检索结果返回相似度分数	~3min
US-008	`POST /documents/batch` 批量上传	~3min

前端 UI（US-009 ~ US-015）

Story	功能	耗时
US-009	知识库编辑按钮 + Modal	~2min
US-010	文档表格操作列（删除/重命名）	~3min
US-011	分片列表 Modal + 分页	~3min
US-012	分片内容编辑 Modal	~2min
US-013	失败文档重新索引按钮	~2min
US-014	检索结果颜色标签（相似度）	~2min
US-015	多文件批量上传 + 进度	~3min

总计：15 个 Story，~35 分钟，15 个 git commit。

Ralph 自动记录的学习笔记

每完成一个 Story，Ralph 会自动往 progress.txt 追加学习笔记。这些笔记对后续迭代非常有价值：

## Learnings for future iterations:
- GlobalExceptionHandler maps ResourceNotFoundException → 404 automatically
- Document has a datasetId field; always verify it matches the path variable
- RagService.indexDocument() already deletes old segments before re-creating
- Ant Design Upload with multiple calls beforeUpload per file
- Use [...array].sort() spread pattern to sort without mutating React state

这些模式知识让后续的 Agent 迭代不会重复踩坑。

关键经验总结

✅ 做对了什么

PRD 拆得够细 — 每个 Story 都是"加一个 API 端点"或"加一个按钮"的粒度
依赖顺序正确 — 后端先行，前端跟上，没有出现前端等接口的情况
验收标准可验证 — "Typecheck passes" 比 "works correctly" 有用一万倍
progress.txt 学习笔记 — 自动积累代码库知识，避免重复犯错

⚠️ 踩过的坑

root 下 Claude Code 限制 — --dangerously-skip-permissions 在 root/sudo 下被禁用
Excel 不支持 — 原来只支持 PDF/DOCX，需要额外添加 Excel 解析（这个 Ralph 没覆盖到，是人工发现后补的）
ralph.sh 的 CLAUDE.md 路径 — Claude Code 的工作目录和 CLAUDE.md 位置要匹配

📋 PRD 编写 checklist

[ ] 每个 Story 能在 2-3 句话内描述清楚
[ ] 后端 Story 排在前，前端排在后
[ ] 每个 Story 都有 "Typecheck passes"
[ ] UI Story 加上 "Verify in browser"
[ ] 验收标准是具体的（"按钮显示确认对话框"），不是模糊的（"UX 好"）

Ralph vs 手动开发对比

维度	手动逐个实现	Ralph 自动化
15 个功能耗时	2-3 天	~30 分钟
上下文切换	频繁（查代码→写→测→提交）	自动
遗漏率	容易忘更新 prd.json	自动标记
知识积累	靠记忆或手动文档	自动写入 progress.txt
一致性	容易风格不统一	遵循同一份 CLAUDE.md

适用场景

Ralph 特别适合：

功能补齐 — 已有代码框架，需要批量添加 CRUD 功能
API 端点批量开发 — 结构化的后端接口开发
组件批量开发 — 前端组件库、管理页面等
Bug 批量修复 — 把 bug 列表转成 Story 清单

不太适合：

架构设计 — 需要全局视野的决策
复杂重构 — 跨多模块的大型改动
一次性探索性任务 — 不知道怎么做的时候

快速上手

bash

# 1. 克隆 Ralph
git clone https://github.com/nicekid1/ralph.git

# 2. 复制到你的项目
mkdir -p your-project/scripts/ralph
cp ralph/ralph.sh your-project/scripts/ralph/
cp ralph/CLAUDE.md your-project/scripts/ralph/

# 3. 编写 prd.json（参照 Ralph 的 PRD skill）

# 4. 跑起来
cd your-project/scripts/ralph
./ralph.sh --tool claude 10

下一步： 我们正在探索把 Ralph 集成到 OpenClaw 的 heartbeat 机制中，让 AI 助手自动检测 TODO 列表并触发 Ralph 开发循环。自主开发，永不停止 🔄

Ralph + Claude Code 自主开发实战：从 PRD 到 15 个功能全部交付 ​

什么是 Ralph？ ​

背景：AgentHub 知识库管理缺失 ​

第一步：生成 PRD 文档 ​

第二步：转换为 prd.json ​

第三步：安装 Ralph 到项目 ​

第四步：启动 Ralph ​

执行过程：30 分钟实录 ​

后端 API（US-001 ~ US-008） ​

前端 UI（US-009 ~ US-015） ​

Ralph 自动记录的学习笔记 ​

关键经验总结 ​

✅ 做对了什么 ​

⚠️ 踩过的坑 ​

📋 PRD 编写 checklist ​

Ralph vs 手动开发对比 ​

适用场景 ​

快速上手 ​

Ralph + Claude Code 自主开发实战：从 PRD 到 15 个功能全部交付

什么是 Ralph？

背景：AgentHub 知识库管理缺失

第一步：生成 PRD 文档

第二步：转换为 prd.json

第三步：安装 Ralph 到项目

第四步：启动 Ralph

执行过程：30 分钟实录

后端 API（US-001 ~ US-008）

前端 UI（US-009 ~ US-015）

Ralph 自动记录的学习笔记

关键经验总结

✅ 做对了什么

⚠️ 踩过的坑

📋 PRD 编写 checklist

Ralph vs 手动开发对比

适用场景

快速上手