Skip to content

README.zh.md

Latest commit

 

History

History
149 lines (109 loc) · 4.16 KB

README.zh.md

File metadata and controls

149 lines (109 loc) · 4.16 KB

ralphy-spec

English | 简体中文 | 한국어 | 日本語

规范驱动的 AI 开发 + 迭代执行。 结合 OpenSpec 和 Ralph 循环，实现可预测的 AI 辅助编码。

官网： https://ralphy-spec.org 文档： https://ralphy-spec.org/zh/docs/ 更新日志： https://ralphy-spec.org/zh/changelog/ · GitHub

快速开始

npx ralphy-spec init

CLI 基础用法：

ralphy-spec run --dry-run
ralphy-spec run
ralphy-spec status
ralphy-spec budget --json

然后使用你的 AI 工具对应的命令：

Cursor

命令 功能
/ralphy-plan 从需求创建规范
/ralphy-implement 迭代循环构建
/ralphy-validate 验证验收标准
/ralphy-archive 完成并归档

Claude Code

命令 功能
/ralphy-plan 从需求创建规范
/ralphy-implement 迭代循环构建
/ralphy-validate 验证验收标准
/ralphy-archive 完成并归档

OpenCode

使用自然语言配合 AGENTS.md：

  • "Follow AGENTS.md to plan [功能]"
  • "Follow AGENTS.md to implement [变更]"
  • "Follow AGENTS.md to validate"
  • "Follow AGENTS.md to archive [变更]"

配合 Ralph 循环运行器：

npm install -g @th0rgal/ralph-wiggum
ralph "Follow AGENTS.md to implement add-api. Output <promise>TASK_COMPLETE</promise> when done." --max-iterations 20

工作流示例

# 1. 规划：从你的想法创建规范
You: /ralphy-plan 添加 JWT 用户认证

# 2. 实现：AI 迭代构建
You: /ralphy-implement add-user-auth

# 3. 验证：确保测试通过
You: /ralphy-validate

# 4. 归档：完成变更
You: /ralphy-archive add-user-auth

创建的文件

.cursor/prompts/          # 或 .claude/commands/
├── ralphy-plan.md
├── ralphy-implement.md
├── ralphy-validate.md
└── ralphy-archive.md

AGENTS.md                 # OpenCode 使用

openspec/
├── specs/                # 真实来源
├── changes/              # 进行中的工作
├── archive/              # 已完成
└── project.md            # 上下文

ralphy-spec/              # 本地状态 + 可读产物（IDE 友好）
├── state.db              # SQLite 运行/任务日志
├── STATUS.md             # 实时状态（`ralphy-spec status` 优先读取）
├── TASKS.md              # 任务看板
├── BUDGET.md             # 花费/预算
├── runs/                 # 不可变运行日志（`runs/<runId>.md`）
├── logs/                 # 后端原始输出（尽力写入）
├── worktrees/            # Git worktree（启用 worktree 模式时）
└── tasks/                # 单任务产物（CONTEXT / REPAIR / NOTES）
    └── <taskId>/
        ├── CONTEXT.md
        ├── REPAIR.md
        └── NOTES.md

注意：如果检测到旧的 .ralphy/，会自动迁移到 ralphy-spec/ 并提示。

工作原理

Ralph Wiggum 循环： AI 重复接收相同提示直到任务完成。每次迭代，它都能看到文件中的之前工作并自我纠正。

OpenSpec： 先有规范后有代码。结构化的规范和验收标准确保 AI 知道要构建什么。

为什么结合使用：

问题 解决方案
聊天中的模糊需求 规范锁定意图
AI 中途停止 循环重试直到完成
无法验证 测试验证输出
工具特定设置 一条命令搞定所有

安装选项

# npx（推荐）
npx ralphy-spec init

# 全局安装
npm install -g ralphy-spec
ralphy-spec init

# 指定工具
ralphy-spec init --tools cursor,claude-code,opencode

致谢

基于以下项目：

许可证

BSD-3-Clause