第五章：你的第一个任务——从一句话到完整代码

本章目标

通过一个具体的实例，完整体验 Ralph 的工作流程：从你输入一句需求描述，到 Ralph 自动完成功能实现、测试、代码审查的全过程。

📌 本章李明轩在做什么：装好 Ralph 后，他决定给自己的"明轩说"工具箱（命令名 mx）写下第一个子命令——mx add，把脑子里临时冒出来的选题灵感秒速记到本地。本章我们陪他把这一条命令从一句话需求跑成可用代码。

示例任务：创建一个命令行工具 mx add，接受选题标题（可选标签），把灵感追加到本地 JSON 文件里，能够跨次运行持久化。

这个任务足够简单（不需要数据库、网络等复杂依赖），但也足够完整（需要参数解析、文件读写、错误处理、单元测试）。

📖 名词解释 · JSON / JSONL

JSON（JavaScript Object Notation）是一种几乎所有编程语言都能读写的数据格式，用 {} 包住的键值对表达结构化信息：

{"title": "明天的选题", "tags": ["ai", "职场"]}

JSONL（JSON Lines）是它的"多行版"：每行一条独立 JSON 记录，适合追加式写入（往文件末尾加一行，不用重写整个文件）。mx add 选这个格式就是因为每次只新增一条灵感。

进一步学习：维基百科：JSON · JSON Lines 规范

方式一：最简单的直接提示

最快的方式是直接用 ralph run 加上你的需求描述：

# 创建一个干净的项目目录
mkdir mx && cd mx
git init
ralph init --backend claude

# 直接运行
ralph run -p "创建一个 Python 命令行工具 mx，第一个子命令是 add：
接受一个位置参数（选题标题）和一个可选参数 --tag（逗号分隔的标签），
把一条灵感追加到当前目录下的 ideas.jsonl 文件里（每行一条 JSON），
每条记录包含：自动生成的 id、标题、标签列表、创建时间。
需要包含完整的错误处理和单元测试。"

-p 是 --prompt 的缩写，后面跟你的需求描述。

Ralph 启动后会进入 TUI 观察模式，你会看到类似这样的输出（此处为示意输出，真实排版会随版本演进，重点是"迭代号 / 活跃帽子 / 事件流向"这三点）：

📖 名词解释 · TUI

TUI（Text-based User Interface，文字用户界面）是在终端窗口里画出来的"可视化界面"——用字符拼接的边框、表格、进度条，支持键盘快捷键操作。比单纯滚动日志直观，又比网页 UI 轻量。Ralph 的 TUI 让你能实时看到当前哪顶帽子在工作、迭代号多少、运行了多久。

进一步学习：维基百科：Text-based user interface

===============================================================================
 ITERATION 1 | 📋 planner | 0s elapsed | 1/100
===============================================================================
  → tasks.ready

===============================================================================
 ITERATION 2 | ⚙️ builder | 1m 42s elapsed | 2/100
===============================================================================
  → review.ready  (tests=5/5 pass)

===============================================================================
 ITERATION 3 | 🧪 critic | 3m 5s elapsed | 3/100
===============================================================================
  → review.passed

===============================================================================
 ITERATION 4 | 🏁 finalizer | 4m 5s elapsed | 4/100
===============================================================================
  → LOOP_COMPLETE

Completion event LOOP_COMPLETE detected.

整个过程你不需要做任何事，喝杯水回来就完成了。

方式二：使用规划功能（推荐用于复杂任务）

对于更复杂的任务，Ralph 提供了一个专门的规划功能——ralph plan。这个功能会让 AI 通过问答方式，把你的模糊想法变成清晰的设计文档。

ralph plan "我想要一个本地网页，看到 mx add 记录的所有选题灵感，
按时间倒序显示，支持按标签筛选，双击某条可以打开详情编辑"

Ralph 的"审问者（Inquisitor）"角色会开始向你提问，一次一个，帮助澄清需求：

🎯 Inquisitor: 你希望这个看板在哪里打开？
   本地浏览器，还是做成桌面应用？

> 本地浏览器，自己电脑上看就好

🎯 Inquisitor: 灵感数量大概会到多少？
   几百条还是可能积累到上万条？

> 一个月 100 条左右，一年 1000 条到头了

🎯 Inquisitor: "详情编辑"里可以改哪些字段？
   删除功能要不要做？

> 标题、标签都能改，删除也要

... (继续问答直到需求清晰)

问答结束后，Ralph 会生成一份设计文档，保存在 .agents/scratchpad/ 目录里。然后你可以用这份文档启动实现阶段：

ralph run -H builtin:code-assist \
  --prompt ".agents/scratchpad/implementation/ideas-board/"

理解 Ralph 的实时输出

Ralph 启动后会进入一个终端界面（TUI），由三个区域组成（下图为示意，实际格式随版本略有不同）：

 ITERATION 3 | 🧪 critic | 3m 5s elapsed | 3/100
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
（AI 实时输出的内容在这里滚动显示）

Running tests...
  test_add_basic ... ok
  test_add_with_tags ... ok
Writing tests/test_add.py
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
:（输入 : 可以发送实时指引给 AI）

三个区域说明：

• 顶部 Header：ITERATION 当前 · 当前活跃帽子名称（带 emoji）· 本次迭代已用时间 · 当前/最大 迭代计数
• 中间内容区：AI 的实时输出流，可以用 j/k 上下滚动，g/G 跳到顶部/底部
• 底部 Footer：输入 : 可以输入指引消息实时发给 AI；! 发送紧急指引（AI 必须先处理完才能继续）

实际键盘快捷键（来自内置帮助 ?）：

检查完成的工作

循环结束后，让我们看看 Ralph 都做了什么：

# 查看创建的文件
ls -la

应该能看到：

mx/                      # Python 包
├── __init__.py
├── __main__.py          # python -m mx 的入口
├── cli.py               # 命令行参数解析
└── storage.py           # JSONL 存储逻辑
tests/
└── test_add.py          # 单元测试
README.md                # 使用说明（如果 AI 生成了的话）

# 运行测试，验证代码质量
python -m pytest tests/ -v

tests/test_add.py::test_add_basic PASSED
tests/test_add.py::test_add_with_tags PASSED
tests/test_add.py::test_add_empty_title_fails PASSED
tests/test_add.py::test_add_persists_across_runs PASSED
tests/test_add.py::test_add_unique_ids PASSED

5 passed in 0.18s

📖 名词解释 · pytest

pytest 是 Python 里最常用的测试框架——把"这段代码的预期行为"写成一个个以 test_ 开头的函数，pytest 自动找到并逐一运行，结果用 PASSED / FAILED 标记。Ralph 依赖测试来"证明代码真的能跑"：没通过测试的代码，审查者帽会拒绝接受。

进一步学习：pytest 官方文档 · 维基百科：单元测试

# 试用一下
python -m mx add "35 岁转型 AI 要避开的三个陷阱"
# ✓ 已记录（ID: 01HV5T3K2W，创建于 2026-04-21 23:18）

python -m mx add "大模型时代 RAG 到底还值不值得学" --tag ai,rag
# ✓ 已记录（ID: 01HV5T4G8Z，标签: ai, rag）

python -m mx add ""
# Error: 标题不能为空

检查 Ralph 的工作轨迹

Ralph 保存了完整的工作记录，你可以查看：

# 查看 AI 学到了什么（记忆文件）
cat .ralph/agent/memories.md

注：memories.md 不一定每次跑完都会生成——AI 只在它判断"这个经验值得跨会话记住"时才写入。如果本次只是简单功能实现，没有踩到坑，可能看不到这个文件，属正常现象。

如果 AI 确实学到了什么，你会看到类似：

# Memories

## Patterns

### mem-1776737169-c8c1
> 这个项目用 pytest 做测试，测试统一放在 tests/；灵感记录采用 JSONL（每行一条 JSON）便于追加，不用数据库
<!-- tags:  | created: 2026-04-21 -->

## Fixes

## Decisions

# 查看任务完成记录
cat .ralph/agent/tasks.jsonl

{"id":"task-1776737453-8ee8","title":"Implement mx add subcommand","description":"...","key":"code-assist:mx:step-01:implement-add","status":"closed","priority":3,"blocked_by":[],"loop_id":"primary-20260421-020921","created":"2026-04-21T02:10:53Z","started":"2026-04-21T02:11:39Z","closed":"2026-04-21T02:14:41Z"}

任务 ID 格式是 task-<Unix 时间戳>-<4 位 16 进制>，由系统生成；你在命令里引用时直接复制这个完整 ID 即可。

使用 PDD-to-Code 完整工作流

如果你想体验 Ralph 最完整的工作流——从模糊想法到可提交代码——可以使用 pdd-to-code-assist 预设：

ralph run -H builtin:pdd-to-code-assist \
  --prompt "为 mx 工具箱新增 list 子命令：
  按创建时间倒序列出所有灵感，
  支持 --tag 按标签筛选，
  支持 --limit N 限制显示条数。"

这个预设会调用 11 个不同的帽子角色，经历完整的流程：

审问者（Inquisitor）→ 架构师（Architect）→ 设计批评者（Design Critic）
→ 探索者（Explorer）→ 规划师（Planner）→ 任务写手（Task Writer）
→ 构建者（Builder）→ 批评者（Fresh-Eyes Critic）→ 终结者（Finalizer）
→ 验证者（Validator）→ 提交者（Committer）

整个流程可能需要 30 分钟到几小时，但会产出：

• 完整的设计文档
• 有测试覆盖的实现代码
• 通过质量检查的代码
• 格式规范的 Git 提交

如果任务失败了怎么办

有时候 Ralph 会遇到无法自动解决的问题，比如：

• 需要安装某个依赖但没有权限
• 需要你提供某个 API 密钥
• 任务描述太模糊，AI 不知道往哪个方向走

这时候 Ralph 会输出 build.blocked 事件并停止，告诉你具体卡在了哪里：

⚠️  Loop blocked: build.blocked
Reason: "Cannot install 'click' without pip. Please run:
         pip install click
         Then resume with: ralph run -p 'continue'"

按照提示操作后，用同样的提示词重新运行，Ralph 会从记忆里知道之前做了什么，继续从断点处推进。

快速命令速览

# 基本运行
ralph run -p "你的需求描述"

# 指定预设
ralph run -H builtin:code-assist -p "需求"

# 规划模式
ralph plan "模糊的想法"

# 查看所有运行中的循环
ralph loops

# 查看任务状态
ralph tools task list

# 查看事件历史
ralph events

# 清理工作状态，重新开始
ralph clean

本章小结

你已经完成了第一次 Ralph 体验。关键的感受应该是：

1. 你只需要描述"想要什么"，不需要告诉 AI "怎么做"
2. 循环是自动的，你可以去做别的事情
3. 质量是有保证的，测试必须通过才算完成
4. 过程是透明的，所有工作记录都保存在文件里

李明轩把这个套路记下了。但他很快发现：一个"通才帽子"干所有事，在自媒体场景里并不够用——选题要策划思维，写稿要文案思维，审校要挑剔思维，发布要细心执行。下一章我们介绍 Ralph 的帽子系统，让不同的 AI 角色各司其职。