ralphcoder

v0.8.4

Published

a month ago

本地 Ralph Loop + 多智能体编排的公司编码工作台

0High
0Medium
0Low

nancyblockorg

ai coding-agent ralph workflow codex claude

RalphCoder

把“Ralph 循环 + 多智能体编排”落到公司编码里的本地 CLI 工具。

它不直接联网、不上传代码、不强依赖某个 LLM API。当前版本是：在公司项目里生成文件化任务状态和角色 Prompt，你把 Prompt 交给 Claude Code / Codex / Cursor 执行，确保每一轮都可审查、可回滚、可验收。

核心思想

Ralph Loop：每个 step 都可以新开 AI 会话执行，避免长上下文污染。
状态外置：任务、计划、结果、验收都写进 .ai/ralphcoder/tasks/<task_id>/。
多角色：Planner 只规划，Executor 只执行，Reviewer 专门挑刺，Reporter 生成 MR 描述。
公司安全：默认禁止无关重构、新依赖、生产配置、密钥、权限/支付/安全敏感改动。
证据优先：Prompt 自动带上 git status / diff stat / 推荐验证命令 / 风险路径扫描。

文件

tools/ralphcoder/
├── ralphcoder.py
└── README.md

初始化

建议第一次加 --gitignore，避免把本地 AI 工作流状态提交到公司仓库。

python /path/to/ralphcoder.py --project /path/to/company-repo init --gitignore

生成：

.ai/ralphcoder/
├── config.json
├── rules.md
├── prompts/
│   ├── planner.md
│   ├── executor.md
│   ├── reviewer.md
│   └── reporter.md
└── tasks/

创建任务

python /path/to/ralphcoder.py --project /path/to/company-repo new "修复订单导出时间筛选 bug" \
  --requirement "订单导出时 startTime/endTime 边界不包含当天 23:59:59，按需求修复并补测试"

输出一个 <task_id>，例如：

20260508-0901-修复订单导出时间筛选-bug

任务目录：

.ai/ralphcoder/tasks/<task_id>/
├── task.md
├── plan.md
├── status.md
├── worklog.md
├── result.md
├── review.md
└── final_report.md

最常用工作流

1. 规划：只读代码，不允许改

python /path/to/ralphcoder.py --project /path/to/company-repo prompt planner --task <task_id>

把输出粘给 Claude Code / Codex / Cursor，让它生成 plan.md。

2. 进入执行

python /path/to/ralphcoder.py --project /path/to/company-repo advance --task <task_id> --state executing --step 1
python /path/to/ralphcoder.py --project /path/to/company-repo prompt executor --task <task_id>

Executor 只允许执行当前 step。

3. 进入验收

python /path/to/ralphcoder.py --project /path/to/company-repo advance --task <task_id> --state reviewing
python /path/to/ralphcoder.py --project /path/to/company-repo prompt reviewer --task <task_id>

Reviewer 必须输出 PASS 或 FAIL 到 review.md。

4. 自动推进状态

新版支持 --auto，会根据当前状态和 review.md 自动判断下一步：

python /path/to/ralphcoder.py --project /path/to/company-repo advance --task <task_id> --auto

逻辑：

planning   -> executing
executing  -> reviewing
reviewing + PASS + 未到最后一步 -> executing 下一步
reviewing + PASS + 已到最后一步 -> reporting
reviewing + FAIL -> fixing
fixing     -> reviewing
reporting  -> done

5. 生成下一步 Prompt

不想记 planner/executor/reviewer/reporter 时，用：

python /path/to/ralphcoder.py --project /path/to/company-repo prompt next --task <task_id>

它会根据 status.md 自动输出下一步应该用的角色 Prompt。

6. 生成 MR 描述

python /path/to/ralphcoder.py --project /path/to/company-repo advance --task <task_id> --state reporting
python /path/to/ralphcoder.py --project /path/to/company-repo prompt reporter --task <task_id>

输出格式：

## 背景
## 修改内容
## 影响范围
## 验证方式
## 风险点
## 回滚方案
## 建议 commit message

辅助命令

查看任务状态

python /path/to/ralphcoder.py --project /path/to/company-repo status --task <task_id>

会显示：

当前 step
建议下一角色
review 结果
自动检测到的测试/构建命令
敏感路径风险扫描
git status

列出任务

python /path/to/ralphcoder.py --project /path/to/company-repo list

健康检查

python /path/to/ralphcoder.py --project /path/to/company-repo doctor

会检查：

RalphCoder 版本
工作流目录
是否 git repo
推荐验证命令
当前 git 状态
最近任务

导出任务包

python /path/to/ralphcoder.py --project /path/to/company-repo report --task <task_id>

适合发给同事或粘进 MR 说明。

自动检测验证命令

RalphCoder 会根据项目文件推荐验证命令：

package.json：npm run test/lint/typecheck/build
pnpm-lock.yaml：优先转成 pnpm
yarn.lock：优先转成 yarn
pom.xml：mvn test / mvn -DskipTests package
gradlew / build.gradle：./gradlew test / ./gradlew build
go.mod：go test ./... / go vet ./...
Python 项目：pytest / ruff check . / mypy .
Makefile：make test / make lint

你也可以在 .ai/ralphcoder/config.json 里手动指定：

{
  "verification_commands": [
    "npm run test:unit",
    "npm run lint"
  ]
}

风险扫描

Prompt 会自动附带 sensitive-looking changed paths，例如：

.env
secret
credential
password
token
private_key
prod
production
payment
permission
auth
migration

命中这些路径时，Reviewer 会更严格。

适用场景

适合：

小 bug 修复
接口参数/DTO 改造
补测试
中小型功能开发
老代码理解
MR 描述生成

谨慎：

权限/支付/安全逻辑
数据迁移
大规模重构
分布式事务/并发锁

后续可升级方向

直接对接 Codex / Claude Code CLI 自动跑角色
自动创建 git worktree 隔离每个任务
自动生成阶段 commit
支持 Web UI 看任务状态
支持团队共享 rules 模板

v0.3 新增：隔离 worktree

公司项目里最怕 AI 把你当前分支搞乱。可以给每个任务创建独立 git worktree：

python /path/to/ralphcoder.py --project /path/to/company-repo worktree create --task <task_id>

它会创建：

.ai/ralphcoder/worktrees/<task_id>/

并自动创建分支：

ai/<task_id>

之后在隔离目录里跑：

python /path/to/ralphcoder.py --project /path/to/company-repo/.ai/ralphcoder/worktrees/<task_id> prompt next --task <task_id>

查看 worktree：

python /path/to/ralphcoder.py --project /path/to/company-repo worktree list

删除 worktree：

python /path/to/ralphcoder.py --project /path/to/company-repo worktree remove --task <task_id> --force

v0.3 新增：Agent 命令包

生成可复制给命令行 agent 的执行包：

python /path/to/ralphcoder.py --project /path/to/company-repo pack next --task <task_id> --agent codex

支持：

generic / claude / codex / cursor

例如 Codex 包会生成：

python ralphcoder.py --project /repo prompt planner --task <task_id> --out /tmp/xxx.md
codex exec < /tmp/xxx.md
python ralphcoder.py --project /repo advance --task <task_id> --auto

v0.3 新增：审计快照

保存当前状态、diff、风险扫描、验证命令：

python /path/to/ralphcoder.py --project /path/to/company-repo snapshot --task <task_id>

输出在：

.ai/ralphcoder/tasks/<task_id>/snapshots/*.json

适合在每轮 AI 执行前后留审计点。

v0.4 新增：Guard 改动守卫

AI 改完后，先跑 guard：

python /path/to/ralphcoder.py --project /path/to/company-repo guard --task <task_id>

它会检查：

改动文件数量是否超过阈值
diff 行数是否超过阈值
是否改了敏感路径
是否出现计划外文件

输出：

.ai/ralphcoder/tasks/<task_id>/guard.md
.ai/ralphcoder/tasks/<task_id>/guard.json

严格模式，失败时返回非 0：

python /path/to/ralphcoder.py --project /path/to/company-repo guard --task <task_id> --strict

失败时标记任务 blocked：

python /path/to/ralphcoder.py --project /path/to/company-repo guard --task <task_id> --mark

配置在 .ai/ralphcoder/config.json：

{
  "guard": {
    "max_changed_files": 20,
    "max_diff_lines": 1200,
    "block_on_sensitive_paths": true
  }
}

v0.4 新增：run 半自动指挥台

run 会按顺序做：

snapshot -> guard -> 输出下一步 command pack

python /path/to/ralphcoder.py --project /path/to/company-repo run --task <task_id> --agent codex

如果你只想输出命令包，不做 guard：

python /path/to/ralphcoder.py --project /path/to/company-repo run --task <task_id> --agent codex --no-guard

如果想输出命令包后自动推进状态：

python /path/to/ralphcoder.py --project /path/to/company-repo run --task <task_id> --agent codex --auto-advance

v0.5 新增：finish 交付收口

生成最终交付/MR 报告：

python /path/to/ralphcoder.py --project /path/to/company-repo finish --task <task_id>

输出并写入：

.ai/ralphcoder/tasks/<task_id>/finish_report.md

包含：

推荐验证命令
guard 结果
changed files
diff stat
MR description draft
rollback 方案
commit message 建议

如果 guard 通过则标记 done，失败则标记 blocked：

python /path/to/ralphcoder.py --project /path/to/company-repo finish --task <task_id> --mark-done

严格模式：

python /path/to/ralphcoder.py --project /path/to/company-repo finish --task <task_id> --strict

v0.5 新增：install

安装成全局命令：

python /path/to/ralphcoder.py install --dir ~/.local/bin

然后确认 PATH：

export PATH="$HOME/.local/bin:$PATH"
ralphcoder --version

v0.5 新增：shell completion

Bash：

ralphcoder completion bash > ~/.ralphcoder-completion.bash
echo 'source ~/.ralphcoder-completion.bash' >> ~/.bashrc

Zsh：

ralphcoder completion zsh > ~/.ralphcoder-completion.zsh
echo 'source ~/.ralphcoder-completion.zsh' >> ~/.zshrc

npm / Web UI 使用

当前目录已经是一个 npm 包，可以本地安装：

cd /path/to/tools/ralphcoder
npm install -g .

安装后有两个命令：

ralphcoder --version
ralphcoder-ui

启动 Web 界面：

ralphcoder-ui --port=8765

然后浏览器打开：

http://127.0.0.1:8765

界面支持：

初始化项目
新建任务
查看任务列表
Run 指挥台
Prompt Next
创建 Worktree
Guard
Advance
Finish

注意：这个 UI 默认只监听 127.0.0.1，适合本机公司项目使用，不会主动暴露到公网。

如果还没发布到 npm registry，可以先用本地安装方式：

npm install -g /path/to/tools/ralphcoder

未来发布后可以变成：

npm install -g ralphcoder

v0.6 新增：auto 真正自动执行

之前 run 只生成命令包，不会真的调用 Codex/Claude。现在可以用 auto 直接执行：

ralphcoder --project /path/to/company-repo auto --task <task_id> --agent codex --max-rounds 1

或 Claude：

ralphcoder --project /path/to/company-repo auto --task <task_id> --agent claude --max-rounds 1

它会自动：

snapshot -> 生成当前 role prompt -> 调用 codex/claude -> guard after -> advance

常用参数：

--max-rounds 3        # 最多自动跑 3 轮
--timeout 1800        # 单轮最多 1800 秒
--no-guard-after      # 不跑后置 guard，不推荐
--no-advance          # 跑完不自动推进状态
--no-stop-on-guard    # guard 失败也继续，不推荐

UI 里也新增了 Auto 真执行 按钮。

v0.7 新增：界面内查看/编辑任务文件

Web UI 现在可以直接查看任务文件：

task.md
plan.md
status.md
worklog.md
result.md
review.md
guard.md
final_report.md
finish_report.md

可在界面编辑并保存：

task.md
plan.md
worklog.md
result.md
review.md

只读文件用于防止误改状态：

status.md
guard.md
final_report.md
finish_report.md

启动：

ralphcoder-ui --port=8765

然后打开：

http://127.0.0.1:8765

v0.8 界面优化

Web UI 进一步产品化：

左侧按“项目设置 / 创建任务 / 智能体执行 / 验收与交付”分区。
增加“推荐流程”导航。
任务文件用中文名展示：任务需求、执行计划、当前状态、工作日志、执行结果、验收意见、安全检查、交付报告。
支持复制当前文件、下载当前文件。
多轮自动执行前会二次确认，避免公司项目里误跑多轮。
增加操作提示、加载状态、错误 toast。

v0.8.1：自动执行可观测

之前点击“自动执行”会等待命令结束，页面看起来像闪烁/卡住。现在改为后台任务：

点击“自动执行”后立即返回后台任务 ID。
页面新增“后台任务”面板。
每 2 秒自动刷新 Codex/Claude 输出。
可看到 PID、运行状态、启动时间、结束时间、stdout/stderr。
后端新增 /api/job?id=... 和 /api/jobs。

这能判断 AI 是否正在执行、卡在哪一步、有没有报错。

v0.8.3：实时日志透传

这版修复了“自动执行没动静、日志要等结束才出现”的问题。

现在：

Python 用 -u 无缓冲模式运行。
UI 后台任务 runner 也强制 PYTHONUNBUFFERED=1。
Codex/Claude 的 stdout / stderr 会实时显示在后台任务面板。
你能看到它是在跑、卡住、报错，还是已经完成。

v0.8.4：后台任务状态修正

自测发现：Codex 失败时，Python 之前会把状态返回为 0，导致 UI 后台任务显示 success。现在已修复：

Agent 失败时 auto 返回非 0。
Guard 失败时 auto 返回非 0。
UI 后台任务会正确显示 failed。
已用临时 git 项目 + UI API 自测，确认能看到实时日志和 Codex 错误。