Smart Ralph
把功能需求变成结构化规格，再逐任务自动执行——为 Claude Code 与 Codex 打造的规格驱动开发插件。
- Star 数
- ★ 561
- 最近更新
- 1 个月前
- License
- MIT
- 主语言
- Shell
- FA 评分
- 73/100 · 存在缺口
30 秒速览
- 运行形态
- 可在哪里用
- 兼容但需适配Codex · Claude Code
- 费用
- 软件免费，模型调用费用自付
- 上手难度
- 低 · 几分钟可跑通
- 开始前需要
- 典型场景
- 在已有代码库上开发新功能的开发者：先运行 /ralph-specum:index 建立可检索索引，再让研究代理复用现有代码上下文生成规格
- 不适合
- 只使用 Claude Code 或 Codex 之外运行时的团队
- 不愿审查并信任插件 Stop 钩子的团队
- 需要量化基准数据来选型的团队
- 源码审查
- 73/100 · 存在缺口
这个 Agent 能做什么，适合哪些场景？
Smart Ralph（tzachbon/smart-ralph）是一个 MIT 许可的 Claude Code 插件，同时支持 OpenAI Codex，将 Ralph Wiggum 循环与结构化规格工作流结合。它先把功能请求转化为 research、requirements、design、tasks 四类规格文件，然后由专门的子代理（如 research-analyst、product-manager、architect-reviewer、task-planner、spec-executor）逐任务执行，每个任务都在全新上下文中开始。规格文件保留在项目的 specs/ 目录中，用户可以在每个阶段之间审查或修改；进度记录在 .progress.md，会话中断后可通过 /ralph-specum:start 恢复。大型目标可先用 /ralph-specum:triage 拆分成依赖感知的多个规格（epic）。此外还提供 ralph-speckit 备选插件以支持 GitHub Spec-Kit 方法论，以及 /ralph-specum:index 代码库索引功能，为研究代理生成可检索的组件规格。
用户调用 /ralph-specum:start [name] "goal"（Claude Code）或 $ralph-specum-start（Codex）后，Smart Ralph 依次执行：research-analyst 分析代码库并搜索网络；product-manager 撰写用户故事与验收标准；architect-reviewer 定义架构与权衡；task-planner 按 POC 优先拆分任务；spec-executor 逐任务实现，每个任务以全新上下文开始并依次经历 POC 验证、重构、测试、质量门（lint、类型、CI 检查）四个阶段。可用 /ralph-specum:triage 把大目标拆为 epic 计划；/ralph-specum:prototype 在安全阶段边界用临时 worktree 测试单个设计问题；/ralph-specum:index 扫描现有项目并在 specs/.index/ 下生成组件规格摘要。可选 --quick 跳过阶段间审批直接生成并执行；--tasks-size fine|coarse 控制任务粒度；[P] 标记低冲突并行任务，[VERIFY]/VE 任务表示显式验证。状态存储于 .ralph-state.json 与 .progress.md，规范产物写入 specs/<feature>/ 下的 research.md、requirements.md、design.md、tasks.md。
- 在已有代码库上开发新功能的开发者：先运行 /ralph-specum:index 建立可检索索引，再让研究代理复用现有代码上下文生成规格
- 目标横跨多个功能或系统的用户：用 /ralph-specum:triage 拆分成依赖感知的 epic 计划，逐个规格推进
- 希望在自动执行前逐阶段把关的团队：使用默认模式，在 research、requirements、design 等阶段之间审批后再继续
- 想快速拿到结果的个人开发者：使用 --quick 一次性生成全部规格并连续执行
- 遵循 GitHub Spec-Kit 治理流程的团队：改用 ralph-speckit 插件，获得项目宪法与需求到任务的可追溯性
- 对某个设计问题不确定的开发者：在阶段边界运行 /ralph-specum:prototype，用一次性原型验证后再进入设计
如何安装或部署这个 Agent？
Claude Code：在 Claude Code 中运行 /plugin marketplace add tzachbon/smart-ralph，然后 /plugin install ralph-specum@smart-ralph，安装后重启 Claude Code。Codex：运行 codex plugin marketplace add tzachbon/smart-ralph --sparse .agents/plugins --sparse plugins/ralph-specum-codex，再运行 codex plugin add ralph-specum@smart-ralph，之后开一个新的 Codex 任务，运行 /hooks 审查捆绑的 Stop 钩子并选择信任以启用自动任务执行。本地开发可克隆仓库后运行 claude --plugin-dir ./plugins/ralph-specum。
如何使用这个 Agent？
Claude Code 中执行 /ralph-specum:start user-auth "Add JWT authentication" 启动首个规格；加 --quick 可跳过阶段间审批；不带参数运行 /ralph-specum:start 可恢复当前活跃规格。Codex 中使用 $ralph-specum-start user-auth "Add JWT authentication"，或 $ralph-specum 让插件自行决定下一步；$ralph-specum-triage 用于跨多个功能的大目标。其他常用命令：/ralph-specum:research、/ralph-specum:requirements、/ralph-specum:design、/ralph-specum:tasks、/ralph-specum:implement（逐任务执行）、/ralph-specum:status（查看进度）、/ralph-specum:cancel（取消执行并清除循环状态）。Codex 在未信任 Stop 钩子前需每任务手动运行一次 $ralph-specum-implement。
这个 Agent 有哪些优点和局限？
- 规格文件（research/requirements/design/tasks）持久保留在项目中，可审查、可编辑、可恢复，执行透明
- 每个阶段由专职子代理负责，任务按 POC 验证→重构→测试→质量门的顺序推进，且有 lint/类型/CI 质量门
- triage 可把大目标拆成依赖感知的 epic 计划，index 可为已有代码库生成可检索组件规格，研究时复用
- 同时支持 Claude Code 与 Codex 两个平台，v3.0.0 起执行循环内置在插件 Stop 钩子中，无需再装独立的 Ralph Loop 插件
- 深度绑定 Claude Code 与 OpenAI Codex 两个宿主运行时，未提供其他模型或环境的适配路径
- Codex 需要审查并信任捆绑的 Stop 钩子才能自动执行任务，否则必须每任务手动运行 $ralph-specum-implement
- 从 v2.x 升级需注意 v3.0.0 将执行移入插件 Stop 钩子，可能需要卸载旧的 Ralph Loop 插件
- 默认模式下阶段间需人工审批，完整流程比单步执行耗时；--quick 模式则跳过原型询问，由插件自行做设计决策
- 仓库未提供性能、成功率等量化评估证据，采用前需自行试用验证
这个 Agent 与同类方案有什么区别？
仓库本身提供两种工作流：ralph-specum（规格存于 specs/，适合快速迭代）与 ralph-speckit（遵循 GitHub Spec-Kit，存于 .specify/specs/，带项目宪法与需求到任务的可追溯性，适合团队治理与审计）。此外 Smart Ralph v3.0.0 内置执行循环后，取代了此前需要单独安装的 Ralph Loop 插件。
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| Smart Ralph 当前 | 73 · 存在缺口 | Agent 插件 / 技能免费 + 模型费 | ★ 561 | 1 个月前 | Shell | Codex · Claude Code |
| OSpec | 50 · 缺口较多 | 命令行工具免费 + 模型费 | ★ 391 | 1 个月前 | JavaScript | Codex · Claude Code |
| Spec Kit | 78 · 表现良好 | 命令行工具 | ★ 142k | 今天 | Python | — |
| Autoprompt Skill | 69 · 存在缺口 | 命令行工具免费 + 模型费 | ★ 1.2k | 19 天前 | JavaScript | Codex · Claude Code |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
文档明确了最小化外部影响（原型的终端记录不可变、不授权 push/PR/issue 写操作）、分阶段审批检查点（quick 模式除外）、审批路径转移控制，以及 .ralph-state. 完成后删除、/cancel 清理回滚。扣分点：这些多为 README 声明，本次证据未见 Stop hook 与权限脚本的实际实现；敏感数据处理（如索引中记录 MCP/URL、凭据风险）未提及；发布者身份未经核验。
版本同步测试、锁生命周期测试、Windows/POSIX 进程控制测试显示内部一致性好，StateError、terminationUnverified、controlError 等失败信息设计具体。扣分点：失败信息质量主要经测试间接印证，文档层面故障恢复指引引用的 TROUBLESHOOTING.md 内容未提供；依赖可用性仅见 CI 安装 bats/jq/ripgrep。
面向 Claude Code 与 Codex 双平台，含 triage/prototype/index 多场景，Windows 原生与模拟测试均覆盖，环境适配强。扣分点：能力边界与触发精度主要靠命令表与流程图描述，边界条件（如非 git 项目、超大仓库索引）未见明确说明。
README 结构清晰，安装指引分平台且含本地开发与迁移说明，MIT LICENSE 文件齐全，CI 强制 semver 递增与版本同步，发布说明提到升级路径。扣分点：已知局限需查 TROUBLESHOOTING.md（内容未提供）；specum/speckit 双插件与 v2→v3 迁移对命名稳定性略增负担；CONTRIBUTING.md 内容未提供，维护承诺只能按引用计。
产物是留在项目内的 specs/ 结构化文件，可人工审阅编辑，任务级进度记录与恢复，输出可用性高。扣分点：相对原生 Claude Code 规划能力的边际价值未量化；loop 自动执行与每任务新上下文可能提高 token 成本，成本收益未讨论。
README 声明的锁、发布不可覆盖、删除源后凭收据发布等行为均有对应单元测试佐证，跨源一致性突出。扣分点：部分关键声明（Stop hook 行为、quick 模式转移策略）无实现文件可核对；事实与推断在文档中偶有混合，但总体区分尚可。
- Trust 判断主要基于 README 声明；安装前请自行审阅 Stop hook 脚本与插件源码，确认其权限行为与文档一致。
- --quick 模式会跳过阶段间审批，仅在可接受自动连续执行的受控环境中使用。
- 索引功能会记录外部 URL、MCP 服务器与已安装技能，注意其中可能含敏感环境信息，避免提交到公开仓库。
- 原型执行涉及进程启动与终止（含 taskkill/killpg），请在隔离或沙箱环境验证后再用于生产项目。
- TROUBLESHOOTING.md 与 CONTRIBUTING.md 内容未在本次证据中，故障恢复与贡献流程需自行核实。
最近版本
来自该项目 GitHub Releases 的最新发布记录，说明为上游原文摘录，未经本站改写或测试。
-
v4.0.0 v4.0.0 — Plugin Best Practices v2
发布说明摘录
Breaking Changes - Commands slimmed to thin orchestrators — procedural logic extracted into 13 references/ files (~60-88% line reduction per command) - Sequential Review Pattern removed — Layer 5 (Artifact Review) is now the single reviewer invocation per task - State updates require explicit jq merge — phase commands no longer use ambiguous JSON literals that could overwrite existing state fields Highlights …在 GitHub 查看 ↗ -
v3.1.1 v3.1.1 - Self-contained execution loop
发布说明摘录
What's New v3.0.0+ - Self-contained Execution Loop Smart Ralph is now fully self-contained with no external plugin dependencies. Key Changes: - 🎉 No more ralph-loop dependency - The execution loop is handled by the built-in stop-hook - 📦 Simpler installation - Just one plugin to install - 🔧 No version compatibility issues between plugins Migration from v2.x 1. Update Smart Ralph to v3.0.0+ 2. Restart Claude Code 3. Existing specs continue working - no changes needed 4. Optionally uninstall ralph-loop if you don't use it elsewhere Installation ```bash …在 GitHub 查看 ↗ -
v2.0.0 v2.0.0 - Ralph Wiggum Integration
发布说明摘录
Breaking Changes Ralph Wiggum plugin now required for task execution. Starting with v2.0.0, Smart Ralph delegates the execution loop to the official Ralph Wiggum plugin instead of using a custom stop-handler. Before upgrading Install the Ralph Wiggum dependency: ```bash /plugin install ralph-wiggum@claude-plugins-official ``` Then restart Claude Code. Migration Guide See [MIGRATION.md](https://github.com/tzachbon/smart-ralph/blob/main/MIGRATION.md) for detailed upgrade instructions. What Changed | Before (v1.x) | After (v2.0.0) | |---------------|----------------| …在 GitHub 查看 ↗