Molt Pi 制作器

您在 Molt Pi 制作器方面的 AI 指南。

功能简介

• 生成用于 GPIO、传感器和摄像头的 Python 代码
• 分步骤解释接线方式
• 在设备出现故障时提供故障排除指导
• 在搭建项目的过程中进行教学

快速入门

from gpiozero import LED
led = LED(17)
led.blink()

包含内容

• GPIO 引脚布局参考
• 常用库指南
• 从入门到高级的项目示例
• 故障排除技巧

项目状态

版本: v0.9.9 - 正在开发中
核心功能: 已实现并经过测试
测试覆盖率: 308 个测试，通过率 100%

当前已实现的功能

• 自主开发循环，具备智能退出检测功能
• 双重条件退出机制: 必须同时满足完成标志和显式 EXIT_SIGNAL 才能退出
• 每小时限流（100 次调用/小时，可配置）
• 具有高级错误检测功能的断路器，防止无限循环
• 响应分析器，具备语义理解能力及两阶段错误过滤功能
• 支持 JSON 输出格式，并自动回退至文本解析
• 会话连续性，可通过 --continue 标志保留上下文
• 会话过期功能，可配置超时时间（默认 24 小时）
• 现代化 CLI 标志：--output-format、--allowed-tools、--no-continue
• 多行错误匹配，准确检测卡死循环
• 处理 Claude API 的 5 小时使用限制，并向用户提示
• 集成 tmux 实现实时监控
• 支持 PRD 文件导入
• 使用 GitHub Actions 构建 CI/CD 流水线
• 专用卸载脚本，便于干净地移除程序
• 11 个测试文件中包含 308 个通过的测试用例

最新改进

v0.9.9 - EXIT_SIGNAL 退出机制与卸载脚本

• 修复了过早退出的 bug：完成标志现在需要 Claude 显式的 EXIT_SIGNAL: true
• 添加了双重条件检查，防止 Claude 报告仍在工作时退出
• 修复了 response_analyzer.sh 脚本，使其优先考虑显式 EXIT_SIGNAL 而非启发式判断
• 添加了专门的 uninstall.sh 卸载脚本，方便彻底移除 Ralph
• 可配置会话超时时间（默认 24 小时）
• 新增 32 个测试用例，用于验证 EXIT_SIGNAL 行为和会话过期功能
• 测试总数增至 308 个（原为 276 个）

v0.9.8 - 现代化 CLI 支持 PRD 导入

• 将 ralph_import.sh 脚本升级为使用 Claude Code CLI 的 JSON 输出格式
• 支持 --output-format json 参数，输出结构化响应
• 改进了错误处理，采用结构化的 JSON 错误信息
• 通过 JSON 数据增强文件验证功能
• 向后兼容旧版 CLI（自动回退至文本模式）
• 新增 11 个测试用例，用于验证现代化 CLI 功能

v0.9.7 - 会话生命周期管理

• 完整的会话生命周期管理，具备自动重置触发机制
• 会话将在断路器跳闸、手动中断或项目完成后自动重置
• 新增 --reset-session CLI 标志，用于手动重置会话
• 记录会话历史（最近 50 次状态转换），便于调试
• 新增 26 个测试用例，用于验证会话连续性功能

v0.9.6 - JSON 输出与会话管理

• 扩展了 parse_json_response() 函数，支持 Claude Code CLI 的 JSON 格式
• 新增会话管理函数：store_session_id()、get_last_session_id()、should_resume_session()
• 在 date_utils.sh 中添加了跨平台的纪元时间工具
• 新增 16 个测试用例，涵盖 Claude CLI 格式和会话管理功能

v0.9.5 - PRD 导入测试

• 新增 22 个全面的测试用例，用于验证 ralph_import.sh PRD 转换脚本
• 测试内容包括：文件格式支持、输出文件创建、项目命名以及错误处理

v0.9.4 - 项目初始化测试

• 新增 36 个全面的测试用例，用于验证 setup.sh 项目初始化脚本
• 测试内容包括：目录创建、模板复制、Git 初始化等

v0.9.3 - 安装测试

• 新增 14 个全面的测试用例，用于验证 install.sh 全局安装脚本
• 测试内容包括：目录创建、命令安装、依赖项检测等

v0.9.2 - 提示文件修复

• 修复了一个关键 bug：将不存在的 --prompt-file CLI 标志替换为 -p 标志
• 现代化 CLI 模式现在可以通过 -p "$(cat file)" 正确传递提示内容
• 在 build_claude_command() 函数中增加了对缺失提示文件的错误处理

v0.9.1 - 现代化 CLI 命令（第 1.1 阶段）

• 支持 --output-format json（默认）的 JSON 输出格式
• 使用 --continue 标志实现跨循环的上下文保持
• 通过 --allowed-tools 标志控制可用工具
• 构建了带有 kcov 覆盖率报告的 CI/CD 流水线

v0.9.0 - 断路器功能增强

• 修复了卡死循环检测中的多行错误匹配问题
• 消除了 JSON 字段中的误报（例如 "is_error": false）
• 添加了两阶段错误过滤，以实现更准确的检测

进展中

• 扩展测试覆盖率
• 日志轮转功能
• 干运行模式
• 配置文件支持（.ralphrc）
• 指标与数据分析跟踪
• 桌面通知
• Git 备份与回滚系统

距离 v1.0 的时间表: 约 4 周 | 完整路线图 | 欢迎贡献！

主要特性

• 自主开发循环 - 根据您的项目需求持续执行 Claude Code
• 智能退出检测 - 双重条件检查，需同时满足完成标志和显式 EXIT_SIGNAL
• 会话连续性 - 通过自动会话管理功能，在循环迭代中保持上下文
• 会话过期 - 可配置超时时间（默认 24 小时），到期后自动重置会话
• 速率限制 - 内置 API 调用管理功能，设有每小时调用上限及倒计时
• 5 小时 API 使用限制处理 - 检测 Claude 的 5 小时使用限制，并提供等待或退出选项
• 实时监控 - 实时仪表板显示循环状态、进度和日志
• 任务管理 - 结构化方法，提供优先级任务列表和进度跟踪
• 项目模板 - 提供快速设置新项目的最佳实践结构
• 全面日志记录 - 详细的执行日志，附带时间戳和状态跟踪
• 可配置超时时间 - 设置 Claude Code 操作的执行超时时间（1–120 分钟）
• 详细进度模式 - 可选的详细进度更新，用于执行过程中
• 响应分析器 - 基于 AI 的 Claude Code 响应分析工具，具备语义理解能力
• 断路器 - 具有高级错误检测功能，采用两阶段过滤、多行错误匹配和自动恢复机制
• CI/CD 集成 - 使用 GitHub Actions 工作流进行自动化测试
• 干净卸载 - 专用卸载脚本，确保彻底移除

快速入门

Ralph 有两个阶段：一次性安装和每个项目的初始化设置。

一次性安装              多次使用
+-----------------+          +----------------------+
| ./install.sh    |    ->    | ralph-setup project1 |
|                 |          | ralph-setup project2 |
| 添加全局命令    |          | ralph-setup project3 |
|                 |          | ...                  |
+-----------------+          +----------------------+

第一阶段：安装 Ralph（仅需一次）

在你的系统上全局安装 Ralph：

git clone https://github.com/frankbria/ralph-claude-code.git
cd ralph-claude-code
./install.sh

这会将 ralph、ralph-monitor 和 ralph-setup 命令添加到你的 PATH 中。

注意：你只需在每台设备上执行一次此操作。安装完成后，你可以选择删除克隆的仓库。

第二阶段：为新项目初始化（按项目进行）

对于每一个你想让 Ralph 参与开发的新项目：

选项 A：导入现有 PRD/规格文档

# 将现有 PRD/规格文档转换为 Ralph 格式（推荐）
ralph-import my-requirements.md my-project
cd my-project

# 审查并调整生成的文件：
# - PROMPT.md（Ralph 指令）
# - @fix_plan.md（任务优先级）
# - specs/requirements.md（技术规格）

# 开始自主开发
ralph --monitor

选项 B：手动初始化项目

# 创建空白的 Ralph 项目
ralph-setup my-awesome-project
cd my-awesome-project

# 手动配置项目需求
# 编辑 PROMPT.md 以写入项目目标
# 编辑 specs/ 目录下的详细规格
# 编辑 @fix_plan.md 以设定初始优先级

# 开始自主开发
ralph --monitor

后续使用（初始化之后）

一旦 Ralph 已安装且项目已初始化：

# 进入任意一个 Ralph 项目并运行：
ralph --monitor              # 集成 tmux 监控（推荐）

# 或者使用独立终端：
ralph                        # 终端 1：Ralph 循环
ralph-monitor               # 终端 2：实时监控仪表盘

卸载 Ralph

要从你的系统中完全移除 Ralph：

# 运行卸载脚本
./uninstall.sh

# 如果你已经删除了仓库，也可以下载并运行：
curl -sL https://raw.githubusercontent.com/frankbria/ralph-claude-code/main/uninstall.sh | bash

工作原理

Ralph 基于一个简单而强大的循环运作：

1. 读取指令 - 加载包含项目需求的 PROMPT.md
2. 执行 Claude 代码 - 根据当前上下文和优先级运行 Claude 代码
3. 跟踪进度 - 更新任务列表并记录执行结果
4. 评估完成情况 - 检查退出条件及项目完成信号
5. 重复 - 直到项目完成或达到限制为止

智能退出检测

Ralph 使用双重条件检查来防止在高效迭代过程中过早退出：

必须同时满足以下两个条件才会退出：

1. completion_indicators >= 2（基于自然语言模式的启发式检测）
2. Claude 在 RALPH_STATUS 块中明确发出的 EXIT_SIGNAL: true

示例行为：

第 5 轮：Claude 输出“阶段完成，进入下一个功能”
        → completion_indicators: 3（由模式判断出高置信度）
        → EXIT_SIGNAL: false（Claude 表示还需继续工作）
        → 结果：继续执行（尊重 Claude 的明确意图）

第 8 轮：Claude 输出“所有任务已完成，项目准备就绪”
        → completion_indicators: 4
        → EXIT_SIGNAL: true（Claude 确认已完成）
        → 结果：退出，并标记为“project_complete”

其他退出条件：

• @fix_plan.md 中的所有任务都被标记为完成
• Claude 代码连续多次发出“完成”信号
• 测试相关的循环次数过多（表明功能已完善）
• 达到 Claude API 的 5 小时使用上限（此时会提示用户等待或退出）

导入现有需求

Ralph 可以利用 Claude 代码将现有的 PRD、规格说明或其他需求文档转换为适合 Ralph 的格式。

支持的格式

• Markdown (.md) - 产品需求、技术规格
• 文本文件 (.txt) - 纯文本需求
• JSON (.json) - 结构化需求数据
• Word 文档 (.docx) - 商业需求
• PDF (.pdf) - 设计文档、规格说明
• 任何基于文本的格式 - Ralph 会智能解析内容

使用示例

# 转换 Markdown 格式的 PRD
ralph-import product-requirements.md my-app

# 转换文本格式的规格说明
ralph-import requirements.txt webapp

# 转换 JSON 格式的 API 规格
ralph-import api-spec.json backend-service

# 让 Ralph 自动根据文件名命名项目
ralph-import design-doc.pdf

生成的内容

Ralph-import 会创建一个完整的项目结构，包含：

• PROMPT.md - 转换后的 Ralph 开发指令
• @fix_plan.md - 将需求分解为优先级任务
• specs/requirements.md - 从原始文档中提取的技术规格
• 标准的 Ralph 目录结构 - 包含所有必要的目录和模板文件

转换过程智能且保留了你原有的需求，同时使其可被用于自主开发。

现代 CLI 特性（v0.9.8）

Ralph-import 利用现代 Claude 代码 CLI 功能以提高可靠性：

• JSON 输出格式：结构化的响应便于精确解析转换结果
• 自动回退机制：能够优雅地处理旧版 CLI 的文本解析
• 增强的错误报告：从 JSON 响应中提取具体的错误信息和代码
• 会话追踪：捕获会话 ID，以便在中断后继续转换

注意：这些特性需要 Claude 代码 CLI 2.0.76 或更高版本。较旧的版本将使用标准的文本输出。

配置

速率限制与断路器

Ralph 内置了智能的速率限制和断路器功能：

# 默认每小时 100 次调用
ralph --calls 50

# 结合集成监控
ralph --monitor --calls 50

# 查看当前使用情况
ralph --status

断路器会自动：

• 通过两阶段过滤检测 API 错误和速率限制问题
• 在连续 3 轮无进展或连续 5 轮出现相同错误时触发断路
• 避免因 JSON 字段中包含“error”而导致的误判
• 通过多行错误匹配准确检测卡住的循环
• 以半开状态逐步恢复
• 提供详细的错误跟踪和日志记录，包括状态历史

Claude API 5 小时限制

当 Claude 的 5 小时使用上限被达到时，Ralph 会：

1. 自动检测到限流错误
2. 提示你选择：
   • 选项 1：等待 60 分钟直到限流重置（带有倒计时）
   • 选项 2：正常退出（或在 30 秒超时后自动退出）
3. 防止无休止的重试循环浪费时间

自定义提示词

# 使用自定义提示词文件
ralph --prompt my_custom_instructions.md

# 带集成监控
ralph --monitor --prompt my_custom_instructions.md

执行超时

# 设置 Claude Code 执行超时（默认：15 分钟）
ralph --timeout 30  # 复杂任务的 30 分钟超时

# 带监控和自定义超时
ralph --monitor --timeout 60  # 60 分钟超时

# 快速迭代的短超时
ralph --verbose --timeout 5  # 带进度的 5 分钟超时

详细模式

# 启用执行过程中的详细进度更新
ralph --verbose

# 结合其他选项
ralph --monitor --verbose --timeout 30

会话连续性

Ralph 在循环迭代中保持会话上下文，以提高连贯性：

# 默认启用会话连续性，使用 --continue 标志
ralph --monitor                 # 使用会话连续性

# 不带会话上下文从头开始
ralph --no-continue             # 独立的迭代

# 手动重置会话（清除上下文）
ralph --reset-session           # 清除当前会话

# 检查会话状态
cat .ralph_session              # 查看当前会话文件
cat .ralph_session_history      # 查看会话转换历史

会话自动重置触发条件：

• 断路器打开（检测到停滞）
• 手动中断（Ctrl+C / SIGINT）
• 项目完成（正常退出）
• 手动重置断路器（--reset-circuit）
• 会话过期（默认：24 小时）

会话会持久化到 .ralph_session 文件中，过期时间可配置（默认：24 小时）。最近 50 次会话转换会被记录到 .ralph_session_history 文件中，用于调试。

退出阈值

在 ~/.ralph/ralph_loop.sh 中修改以下变量：

退出检测阈值：

MAX_CONSECUTIVE_TEST_LOOPS=3     # 连续 3 次仅测试循环后退出
MAX_CONSECUTIVE_DONE_SIGNALS=2   # 收到 2 次“完成”信号后退出
TEST_PERCENTAGE_THRESHOLD=30     # 如果 30% 及以上循环仅为测试，则标记

断路器阈值：

CB_NO_PROGRESS_THRESHOLD=3       # 连续 3 次无文件更改后打开断路器
CB_SAME_ERROR_THRESHOLD=5        # 连续 5 次出现相同错误后打开断路器
CB_OUTPUT_DECLINE_THRESHOLD=70   # 输出下降超过 70% 后打开断路器

完成指标与 EXIT_SIGNAL 门控：

completion_indicators	EXIT_SIGNAL	Result
>= 2	true	退出（“project_complete”）
>= 2	false	继续（Claude 仍在工作）
>= 2	缺失	继续（默认为 false）
< 2	true	继续（未达到阈值）

项目结构

Ralph 为每个项目创建标准化结构：

my-project/
├── PROMPT.md           # Ralph 的主要开发说明
├── @fix_plan.md        # 优先级任务列表（@ 前缀表示 Ralph 控制文件）
├── @AGENT.md           # 构建和运行指令
├── specs/              # 项目规格和需求
│   └── stdlib/         # 标准库规格
├── src/                # 源代码实现
├── examples/           # 使用示例和测试用例
├── logs/               # Ralph 执行日志
└── docs/generated/     # 自动生成的文档

最佳实践

编写有效提示词

1. 明确具体 - 清晰的需求带来更好的结果
2. 优先排序 - 使用 @fix_plan.md 引导 Ralph 的关注点
3. 设定边界 - 定义范围内外的内容
4. 包含示例 - 展示预期的输入/输出

项目规格

• 将详细需求放在 specs/ 目录下
• 使用 @fix_plan.md 跟踪优先级任务
• 保持 @AGENT.md 更新，包含构建指令
• 记录关键决策和架构设计

监控进度

• 使用 ralph-monitor 获取实时状态更新
• 检查 logs/ 目录中的详细执行历史
• 监控 status.json 文件以进行程序化访问
• 注意退出条件信号

系统要求

• Bash 4.0+ - 用于脚本执行
• Claude Code CLI - npm install -g @anthropic-ai/claude-code
• tmux - 推荐使用终端多路复用器进行集成监控
• jq - 用于状态跟踪的 JSON 处理工具
• Git - 版本控制（项目初始化为 Git 仓库）
• 标准 Unix 工具 - grep、date 等

测试要求（开发）

完整的测试指南请参阅 TESTING.md。

如果要运行测试套件：

# 安装 BATS 测试框架
npm install -g bats bats-support bats-assert

# 运行所有测试（308 个测试）
npm test

# 运行特定测试套件
bats tests/unit/test_rate_limiting.bats
bats tests/unit/test_exit_detection.bats
bats tests/unit/test_json_parsing.bats
bats tests/unit/test_cli_modern.bats
bats tests/unit/test_cli_parsing.bats
bats tests/unit/test_session_continuity.bats
bats tests/integration/test_loop_execution.bats
bats tests/integration/test_prd_import.bats
bats tests/integration/test_project_setup.bats
bats tests/integration/test_installation.bats

# 运行错误检测和断路器测试
./tests/test_error_detection.sh
./tests/test_stuck_loop_detection.sh

当前测试状态：

• 308 个测试分布在 11 个测试文件中
• 100% 通过率（308/308 通过）
• 全面的单元和集成测试
• 专门针对 JSON 解析、CLI 标志、断路器、EXIT_SIGNAL 行为以及安装流程的测试

关于覆盖率的说明：使用 kcov 测量 Bash 代码覆盖率时，在追踪子进程执行方面存在根本性限制。测试通过率（100%）是质量门槛。详情请参阅 bats-core#15。

安装 tmux

# Ubuntu/Debian
sudo apt-get install tmux

# macOS
brew install tmux

# CentOS/RHEL
sudo yum install tmux

监控与调试

实时仪表盘

# 推荐使用集成的 tmux 监控
ralph --monitor

# 在单独终端手动监控
ralph-monitor

实时显示：

• 当前循环次数和状态
• 已使用的 API 调用数及剩余限额
• 最近的日志条目
• 速率限制倒计时

tmux 控制键：

• Ctrl+B 后接 D - 从会话分离（Ralph 继续运行）
• Ctrl+B 后接 ←/→ - 切换窗格
• tmux list-sessions - 查看活动会话
• tmux attach -t <session-name> - 重新连接到会话

状态检查

# JSON 格式的状态输出
ralph --status

# 手动检查日志
tail -f logs/ralph.log

常见问题

• 速率限制 - Ralph 会自动等待并显示倒计时
• 5 小时 API 限制 - Ralph 会检测并提示用户采取行动（等待或退出）
• 卡住的循环 - 检查 @fix_plan.md 文件，查看是否存在不明确或冲突的任务
• 过早退出 - 如果 Ralph 过早停止，请检查退出阈值
• 过早退出 - 检查 Claude 是否设置了 EXIT_SIGNAL: false（Ralph 现在会尊重这一设置）
• 执行超时 - 对于复杂操作，可增加 --timeout 参数的值
• 缺少依赖项 - 确保已安装 Claude Code CLI 和 tmux
• tmux 会话丢失 - 使用 tmux list-sessions 和 tmux attach 重新连接
• 会话过期 - 默认情况下，会话会在 24 小时后过期；使用 --reset-session 可以重新开始

贡献说明

Ralph 正在积极寻求贡献者！我们正朝着 v1.0.0 版本努力，拥有清晰的优先级和详细的路线图。

请参阅 CONTRIBUTING.md 获取完整的贡献指南，其中包括：

• 入门和设置说明
• 开发工作流程和提交规范
• 代码风格指南
• 测试要求（必须达到 100% 的通过率）
• 拉取请求流程和代码审查指南
• 质量标准和检查清单

快速入门

# 分支并克隆
git clone https://github.com/YOUR_USERNAME/ralph-claude-code.git
cd ralph-claude-code

# 安装依赖并运行测试
npm install
npm test  # 所有 308 个测试必须通过

优先贡献领域

1. 测试实现 - 帮助扩展测试覆盖率
2. 功能开发 - 日志轮转、试运行模式、配置文件、指标
3. 文档编写 - 教程、故障排除指南、示例
4. 实际测试 - 使用 Ralph，报告 bug，分享反馈

每一次贡献都很重要，无论是修复错别字还是实现重大功能！

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

致谢

• 灵感来源于 Geoffrey Huntley 创造的 Ralph 技术
• 专为 Anthropic 的 Claude Code 构建
• 感谢社区的反馈与贡献

相关项目

• Claude Code - 驱动 Ralph 的 AI 编码助手
• Aider - Ralph 技术的原始实现

---

命令参考

安装命令（只需执行一次）

./install.sh              # 全局安装 Ralph
./uninstall.sh            # 从系统中移除 Ralph（专用脚本）
./install.sh uninstall    # 替代方案：从系统中移除 Ralph
./install.sh --help       # 显示安装帮助

Ralph 循环选项

ralph [OPTIONS]
  -h, --help              显示帮助信息
  -c, --calls NUM         设置每小时最大调用次数（默认：100）
  -p, --prompt FILE       设置提示文件（默认：PROMPT.md）
  -s, --status            显示当前状态并退出
  -m, --monitor           启动时开启 tmux 会话并进行实时监控
  -v, --verbose           在执行过程中显示详细进度更新
  -t, --timeout MIN       设置 Claude Code 执行超时时间（1-120 分钟，默认：15 分钟）
  --output-format FORMAT  设置输出格式：json（默认）或文本
  --allowed-tools TOOLS   设置允许使用的 Claude 工具（默认：Write,Bash(git *),Read）
  --no-continue           禁用会话连续性（每次循环都从头开始）
  --reset-circuit         重置断路器
  --circuit-status        显示断路器状态
  --reset-session         手动重置会话状态

项目相关命令

ralph-setup project-name     # 创建新的 Ralph 项目
ralph-import prd.md project  # 将 PRD/规格转换为 Ralph 项目
ralph --monitor              # 启动时启用集成监控
ralph --status               # 检查当前循环状态
ralph --verbose              # 启用详细进度更新
ralph --timeout 30           # 设置 30 分钟的执行超时
ralph --calls 50             # 限制每小时最多 50 次 API 调用
ralph --reset-session        # 手动重置会话状态
ralph-monitor                # 手动监控仪表板

tmux 会话管理

tmux list-sessions        # 查看当前活跃的 Ralph 会话
tmux attach -t <name>     # 重新连接到已分离的会话
# Ctrl+B 然后 D           # 分离会话（会话仍继续运行）

---

开发路线图

Ralph 处于积极开发阶段，正朝着 v1.0.0 版本稳步前进。完整路线图请参阅 IMPLEMENTATION_PLAN.md。

当前状态：v0.9.9

已完成内容：

• 核心循环功能，具备智能退出检测
• 双重退出条件（完成指标 + EXIT_SIGNAL）
• 速率限制（每小时 100 次调用）和断路器模式
• 具备语义理解能力的响应分析器
• 308 个全面测试（100% 通过率）
• tmux 集成和实时监控
• 支持现代 CLI JSON 解析的 PRD 导入功能
• 安装系统和项目模板
• 支持 JSON 输出的现代化 CLI 命令
• 使用 GitHub Actions 的 CI/CD 流程
• 全面的安装测试套件
• 自动重置触发器的会话生命周期管理
• 可配置超时的会话过期机制
• 专用的卸载脚本

测试覆盖率细分：

• 单元测试：164 个（CLI 解析、JSON、退出检测、速率限制、会话连续性）
• 集成测试：144 个（循环执行、边缘案例、安装、项目设置、PRD 导入）
• 测试文件：11 个

通往 v1.0.0 的路径（约 4 周）

增强测试

• 安装和设置工作流测试
• tmux 集成测试
• 监控仪表板测试

核心功能

• 日志轮转功能
• 试运行模式
• 配置文件支持 - .ralphrc

高级功能与完善

• 指标和分析跟踪
• 桌面通知
• Git 备份和回滚系统
• 端到端测试
• 最终文档和发布准备

详细进度跟踪请参阅 IMPLEMENTATION_STATUS.md。

如何贡献

Ralph 正在寻找贡献者！请参阅 CONTRIBUTING.md 获取完整指南。优先领域：

1. 测试实现 - 帮助扩展测试覆盖率（查看计划）
2. 功能开发 - 日志轮转、试运行模式、配置文件
3. 文档编写 - 使用示例、教程、故障排除指南
4. Bug 报告 - 实际使用中的反馈和边缘案例

---

准备好让 AI 构建你的项目了吗？ 从 ./install.sh 开始，剩下的就交给 Ralph 吧！

星标历史

Molt-Pi-Maker (Ralph) 快速上手指南

Molt-Pi-Maker（项目代号 Ralph）是一个基于 Claude Code 的自主开发循环工具，专为树莓派及嵌入式项目设计。它能自动生成 GPIO/传感器代码、解释接线细节、排查故障，并在构建过程中提供教学指导。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: Linux 或 macOS (Windows 用户建议使用 WSL2)。
• 核心依赖:
  • Git: 用于克隆仓库。
  • Python 3: 运行生成的 GPIO 代码（需安装 gpiozero 库）。
  • Node.js & npm: 用于运行底层 CLI 工具。
  • Claude Code CLI: 必须已安装并配置好 Anthropic API Key。
• 网络环境: 需要能够稳定访问 GitHub 和 Anthropic API。
  • 提示: 若在国内访问 GitHub 较慢，可配置本地 hosts 或使用加速代理。

安装步骤

安装过程分为两个阶段：全局安装（只需一次）和 项目初始化（每个新项目执行一次）。

第一阶段：全局安装 (One-time Install)

将工具安装到系统路径中：

git clone https://github.com/frankbria/ralph-claude-code.git
cd ralph-claude-code
./install.sh

注意: 执行成功后，系统中将新增 ralph, ralph-monitor, ralph-setup 和 ralph-import 命令。安装完成后，您可以删除克隆的仓库目录。

第二阶段：项目初始化 (Per-Project Setup)

为您想要开发的每个新项目创建工作环境。

方式 A：导入现有需求文档 (推荐)

如果您已有 PRD、技术规格书或需求文档（支持 .md, .txt, .json, .pdf, .docx 等格式）：

# 将现有文档转换为 Ralph 项目结构
ralph-import my-requirements.md my-pi-project
cd my-pi-project

# 启动自主开发循环（带实时监控）
ralph --monitor

方式 B：手动创建新项目

从零开始构建：

# 创建空白项目
ralph-setup my-awesome-project
cd my-awesome-project

# 手动编辑以下文件以定义目标：
# - PROMPT.md (项目目标指令)
# - specs/ (详细技术规格)
# - @fix_plan.md (任务优先级列表)

# 启动自主开发循环
ralph --monitor

基本使用

安装并初始化项目后，Molt-Pi-Maker 将进入“自主开发循环”模式。它会自动读取 PROMPT.md，调用 Claude Code 编写代码、测试并修复错误，直到任务完成。

1. 启动开发循环

在项目目录下运行：

ralph --monitor

• 该命令会启动一个集成 tmux 的监控面板，实时显示日志、进度和循环状态。
• 或者分屏运行：终端 1 运行 ralph，终端 2 运行 ralph-monitor。

2. 简单示例：控制 LED 灯

假设您的 PROMPT.md 中包含“让连接在 GPIO 17 的 LED 灯闪烁”的需求，工具将自动生成并执行类似以下的 Python 代码：

from gpiozero import LED
led = LED(17)
led.blink()

3. 会话管理

• 断点续传: 如果中途停止，下次运行可使用 --continue 标志保留上下文：

  ralph --continue --monitor
  

• 自动退出: 当所有任务完成且检测到明确的退出信号 (EXIT_SIGNAL: true) 时，循环会自动停止。

4. 卸载工具

如需完全移除工具：

# 在原克隆目录运行
./uninstall.sh

# 或直接从网络运行卸载脚本
curl -sL https://raw.githubusercontent.com/frankbria/ralph-claude-code/main/uninstall.sh | bash