umputun/ralphex

使用 Claude Code 自主执行计划

*ralphex 是一个独立的 CLI 工具，可以在终端中从 git 仓库的根目录运行。它编排 Claude Code 自主执行实施计划 - 无需 IDE 插件或云服务，只需 Claude Code 和一个二进制文件。* Claude Code 功能强大但是交互式的 - 它需要你监视、批准并指导每一步。对于跨越多个任务的复杂功能，这意味着需要数小时的人工看护。更糟糕的是，随着长时间会话中上下文逐渐填满，模型的质量会下降 - 它开始犯错、忘记先前的决定，并生成质量更差的代码。 ralphex 解决了这两个问题。每个任务都在一个具有最少上下文的全新 Claude Code 会话中执行，使模型在整个计划执行期间保持敏锐。编写一个包含任务和验证命令的计划，启动 ralphex，然后离开即可。回来看时会发现你的功能已经实现、审查并提交 - 或者查看进度日志以了解它的执行情况。

任务执行截图


审查模式截图


Web 仪表板截图


## 功能 - **零设置** - 开箱即用，具有合理的默认值，无需配置 - **自主任务执行** - 逐一执行计划任务并自动重试 - **交互式计划创建** - 通过 `--plan` 标志与 Claude 对话创建计划 - **多阶段代码审查** - 5 个代理 → codex → 2 个代理审查流水线 - **自定义审查代理** - 可通过 `{{agent:name}}` 模板系统和用户定义的提示词配置代理 - **自动创建分支** - 根据计划文件名创建 git 分支 - **计划完成跟踪** - 将已完成的计划移动到 `completed/` 文件夹 - **自动提交** - 在每个任务和审查修复后提交 - **实时监控** - 带有时间戳、颜色和详细日志的流式输出 - **Web 仪表板** - 使用 `--serve` 标志在浏览器中实时查看 - **Docker 支持** - 在隔离的容器中运行，以实现更安全的自主执行 - **通知** - 在完成/失败时通过 Telegram、Email、Slack、Webhook 或自定义脚本发送可选警报 - **Worktree 隔离** - 通过 `--worktree` 标志并行运行多个计划 - **多种模式** - 完整执行、仅任务、仅审查、仅外部审查或计划创建 ## 快速开始 确保已[安装](#installation) ralphex 并且你的项目是一个 git 仓库。你需要在 `docs/plans/` 中有一个[计划文件](#plan-creation)，例如： ``` # Plan: My Feature ## 验证命令 - `go test ./...` ### Task 1: 实现功能 - [ ] Add the new functionality - [ ] Add tests ``` 然后运行： ``` ralphex docs/plans/my-feature.md ``` ralphex 将创建分支、执行任务、提交结果、运行多阶段审查，并在完成后将计划移动到 `completed/`。 ## 工作原理 ralphex 通过自动代码审查分四个阶段执行计划，外加一个可选的 finalize 步骤。

执行流程图


### 阶段 1：任务执行 1. 读取计划文件并找到第一个未完成的任务（带有 `- [ ]` 复选框的 `### Task N:`） 2. 将任务发送给 Claude Code 执行 3. 在每个任务后运行验证命令（测试、代码检查工具） 4. 将复选框标记为完成 `[x]`，提交更改 5. 重复此过程，直到所有任务完成或达到最大迭代次数 **运行中转向：** 在任务迭代期间按 Ctrl+\ (SIGQUIT) 可暂停执行。ralphex 会取消当前的 Claude 会话并提示“按 Enter 继续，按 Ctrl+C 中止”。暂停时，你可以编辑计划文件 — 按 Enter 后，同一任务将在重新读取计划的新会话中重新运行。按 Ctrl+C 可干净地中止。Windows 上不支持此功能。 ### 阶段 2：首次代码审查 通过 Claude Code Task 工具**并行**启动 5 个审查代理： | 代理 | 目的 | |-------|---------| | `quality` | Bug、安全问题、竞态条件 | | `implementation` | 验证代码是否达到既定目标 | | `testing` | 测试覆盖率和质量 | | `simplification` | 检测过度工程化 | | `documentation` | 检查是否需要更新文档 | Claude 会验证发现的问题，修复已确认的问题，并进行提交。 *[默认代理](https://github.com/umputun/ralphex/tree/master/pkg/config/defaults/agents)提供了通用的、与语言无关的审查步骤。可以根据你的特定需求、语言和工作流对它们进行自定义和调整。详情请参见[自定义](#customization)。* ### 阶段 3：外部审查（可选） 1. 运行外部审查工具（默认为 codex，或自定义脚本） 2. Claude 评估发现的问题，修复有效的问题 3. 迭代直到没有未解决的问题 当出现以下情况时循环终止：所有问题均已解决、达到最大迭代次数、检测到僵局（通过 `--review-patience`）或通过 Ctrl+\ (SIGQUIT) 手动中断。 **僵局检测：** 当外部工具和 Claude 无法就发现的问题达成一致时，循环可能会浪费 Token 一直迭代到最大次数。设置 `--review-patience=N`（或在配置中设置 `review_patience`）以在连续 N 轮没有提交或工作树更改时终止。 **手动中断：** 在外部审查循环期间按 Ctrl+\ (SIGQUIT) 可立即终止它。当前的执行器运行会通过上下文取消机制被取消。在任务阶段，Ctrl+\ 是暂停操作 — 参见[阶段 1：任务执行](#phase-1-task-execution)。Windows 上不支持此功能。 支持的审查工具： - **codex**（默认）：OpenAI Codex 用于独立的代码审查 - **custom**：你自己的脚本，可封装任何 AI（OpenRouter、本地 LLM 等） - **none**：完全跳过外部审查 有关使用自定义脚本的详细信息，请参见[自定义外部审查](#custom-external-review)。 ### 阶段 4：第二次代码审查 1. 启动 2 个代理（`quality` + `implementation`）进行最终审查 2. 仅关注关键/主要问题 3. 迭代直到未发现任何问题 4. 成功后将计划移动到 `completed/` 文件夹 *第二次审查代理可通过 `prompts/review_second.txt` 进行配置。* ### Finalize 步骤（可选） 在所有审查阶段成功完成后，ralphex 可以运行一个可选的 finalize 步骤。默认禁用。 **功能：** 运行具有可自定义提示词的单次 Claude Code 会话。默认的 `finalize.txt` 提示词会将提交变基到默认分支上，并有选择地将相关提交压缩成逻辑组。 **如何启用：** 在 `~/.config/ralphex/config` 或 `.ralphex/config` 中设置 `finalize_enabled = true`。 **行为：** - 仅运行一次（无迭代循环） - 尽力而为 — 失败会被记录但不会阻碍成功 - 在具有审查流水线的模式下触发：完整模式、仅审查模式、仅外部审查模式 - 使用任务颜色（绿色）进行输出 **自定义：** 编辑 `~/.config/ralphex/prompts/finalize.txt`（或 `.ralphex/prompts/finalize.txt`）以更改审查后执行的操作。示例：推送到远程仓库、发送通知、运行部署脚本或任何完成后的自动化操作。像 `{{DEFAULT_BRANCH}}` 这样的模板变量可用。 ### 计划移动行为（可选） 成功执行后，ralphex 会将计划文件移动到 `docs/plans/completed/` 中。默认启用。 **如何禁用：** 在 `~/.config/ralphex/config` 或 `.ralphex/config` 中设置 `move_plan_on_completion = false`。默认值为 `true`。 **何时禁用：** 在外部管理计划文件生命周期的工作流（例如，规格驱动工具，其中计划位于一个 bundle 内，由单独的归档步骤使用）应选择退出，以免 ralphex 与外部工具的文件布局发生冲突。 ### 仅审查模式 仅审查模式（`--review`）对当前分支上已有的更改运行完整的审查流水线（阶段 2 → 阶段 3 → 阶段 4）。这在更改是通过 ralphex 之外的方式（例如 Claude Code 的内置计划模式、手动编辑、其他 AI 代理或任何其他工作流）进行时非常有用。 **工作流程：** 1. 在功能分支上进行更改（使用任何工具或工作流） 2. 提交更改 3. 运行 `ralphex --review` ralphex 将分支与默认分支进行比较（`git diff master...HEAD`），启动多代理审查，并迭代修复直到所有代理报告无误。不需要计划文件 — 如果提供，它会为审查者提供有关预期更改的附加上下文。 ``` # 切换到包含现有更改的 feature 分支 git checkout feature-auth # 对这些更改运行 review pipeline ralphex --review # 可选择传入 plan 文件以提供上下文 ralphex --review docs/plans/add-auth.md ``` ### Worktree 隔离 `--worktree` 标志在 `.ralphex/worktrees/` 处的隔离 git worktree 中运行计划执行，允许在同一个仓库上并行执行多个计划而不会产生分支冲突。 **支持的模式：** `--worktree` 仅适用于完整模式和 `--tasks-only`。对于 `--review`、`--external-only` 和 `--plan`，它会被静默忽略 — 这些模式从当前目录运行。 **在 worktree 分支上重新运行审查：** 如果任务阶段在 worktree 中完成，但审查阶段需要重新运行，请 `cd` 进入 worktree 目录并从那里运行审查： ``` # 找到 worktree ls .ralphex/worktrees/ # 从中运行 review cd .ralphex/worktrees/my-feature-branch ralphex --review # 或者 ralphex --external-only ``` Worktree 在成功完成后会自动移除。如果运行被中断，worktree 目录可能会保留，并且可以重用或手动删除。 ### 计划创建 可以通过以下几种方式创建计划： - **[Claude Code](#claude-code-integration-optional)** - 使用斜杠命令如 `/ralphex-plan` 或你自己的计划工作流 - **手动** - 直接在 `docs/plans/` 中编写 markdown 文件 - **`--plan` 标志** - 处理整个流程的集成选项 - **自动检测** - 在 master/main 上不带参数运行 `ralphex` 时，如果没有计划存在，会提示创建计划 `--plan` 标志提供了更简单的集成体验： ``` ralphex --plan "add health check endpoint" ``` Claude 会探索你的代码库，通过终端选择器（fzf 或数字回退）提出澄清问题，并在 `docs/plans/` 中生成一个完整的计划文件。在审查草稿时，你可以接受、通过文本反馈进行修改、在 `$EDITOR` 中打开进行交互式批注或拒绝它。 **示例会话：** ``` $ ralphex --plan "add caching for API responses" [10:30:05] analyzing codebase structure... [10:30:12] found existing store layer in pkg/store/ QUESTION: Which cache backend? > Redis In-memory File-based Other (type your own answer) [10:30:45] ANSWER: Redis [10:31:00] continuing plan creation... [10:32:05] plan written to docs/plans/add-api-caching.md Continue with plan implementation? > Yes, execute plan No, exit ``` 创建计划后，你可以选择继续立即执行，或者退出以便稍后运行 ralphex。进度会记录到 `.ralphex/progress/progress-plan-.txt`。 ## 安装 ### 从源代码安装 ``` go install github.com/umputun/ralphex/cmd/ralphex@latest ``` ### 使用 Homebrew ``` brew install umputun/apps/ralphex ``` ### 从 releases 下载 从 [releases](https://github.com/umputun/ralphex/releases) 下载相应的二进制文件。 ### 使用 Docker 下载包装脚本并安装到 PATH： ``` curl -sL https://raw.githubusercontent.com/umputun/ralphex/master/scripts/ralphex-dk.sh -o /usr/local/bin/ralphex chmod +x /usr/local/bin/ralphex ``` 该脚本默认使用 Go 镜像（`ralphex-go`）。对于其他语言，请从安装了你的工具链的基础镜像构建自定义镜像（示例见[可用镜像](#available-images)），然后让包装脚本指向它： ``` export RALPHEX_IMAGE=my-ralphex ``` 然后像往常一样使用 `ralphex` - 它在预装了 Claude Code 和 Codex 的容器中运行。脚本会在启动时显示它正在使用的镜像。 **为什么要使用 Docker？** ralphex 使用 `--dangerously-skip-permissions` 运行 Claude Code，赋予它执行命令和修改文件的完全访问权限。在容器中运行提供了隔离 - Claude 只能访问挂载的项目目录，而不能访问你的整个系统。这使得自主执行的安全性大大提高。

隔离详情

**容器可以访问（读写）：** - 挂载在 `/workspace` 的项目目录 - 创建、修改、删除文件的完全访问权限 - 项目内的 Git 操作（分支、提交等） **容器可以访问（只读）：** - `~/.claude/` - 凭据和设置（启动时复制，不修改） - `~/.codex/` - codex 凭据（如果存在） - `~/.config/ralphex/` - 用户级别的 ralphex 配置 - `~/.gitconfig` - 用于提交的 git 身份 - 全局 gitignore (`core.excludesFile`) - 自动检测并挂载 - `.ralphex/` - 项目级别的配置（如果存在**容器无法访问：** - 挂载目录之外的主机文件系统 - 其他项目或仓库 - `~/.ssh`、`~/.aws` 等目录中的 SSH 密钥、AWS 凭据或其他机密 - 系统文件、二进制文件或配置 - 其他正在运行的进程或容器 **网络：** 完全的网络访问权限（Claude API 调用所需） **权限：** 以非 root 用户运行，无提升的权限

**卷挂载：** - **只读**：`~/.claude` 和 `~/.codex` 挂载到 `/mnt/`，在启动时复制以保持隔离 - **读写**：项目目录（`/workspace`） - ralphex 在此处创建分支、编辑代码和提交 - **额外挂载**：通过 `-v`/`--volume` 标志或 `RALPHEX_EXTRA_VOLUMES` 环境变量设置的用户自定义卷 **要求：** - Python 3.9+（用于包装脚本） - Docker 已安装并正在运行 - `~/.claude/` 中的 Claude Code 凭据（或设置 `$CLAUDE_CONFIG_DIR`） - `~/.codex/` 中的 Codex 凭据（可选，用于 codex 审查阶段） - `~/.gitconfig` 中的 Git 配置（用于提交） **环境变量：** - `RALPHEX_IMAGE` - 要使用的 Docker 镜像（默认：`ghcr.io/umputun/ralphex-go:latest`）。CLI 标志：`--image` - `RALPHEX_PORT` - 使用 `--serve` 时 Web 仪表板的端口（默认：`8080`）。CLI 标志：`--port` - `RALPHEX_CONFIG_DIR` - 自定义配置目录（默认：`~/.config/ralphex`）。覆盖提示词、代理和设置的全局配置位置 - `CLAUDE_CONFIG_DIR` - Claude 配置目录（默认：`~/.claude`）。用于替代的 Claude 安装（例如，`~/.claude2`）。适用于 Docker 包装脚本（卷挂载和钥匙串派生）和非 Docker 使用（直接传递给 Claude Code）。钥匙串服务名称从路径自动派生。 - `RALPHEX_EXTRA_VOLUMES` - 额外的卷挂载，以逗号分隔（例如，`/data:/mnt/data:ro,/models:/mnt/models`）。没有 `:` 的条目会被静默跳过 - `RALPHEX_EXTRA_ENV` - 额外的环境变量，以逗号分隔（例如，`DEBUG=1,API_KEY`）。格式：`VAR=value` 或 `VAR`（从主机继承）。带有显式值的敏感名称（KEY、SECRET、TOKEN 等）会发出安全警告 - 使用仅名称的形式以安全地传递凭据 - `RALPHEX_DOCKER_SOCKET` - 启用 Docker socket 挂载：`1`、`true` 或 `yes`（仅限 Docker 包装脚本）。CLI 标志：`--docker` - `RALPHEX_DOCKER_NETWORK` - Docker 网络模式（例如，`host`、`my-network`）。适用于访问 docker-compose 服务。CLI 标志：`--network` - `TZ` - 覆盖容器时区（默认：通过 `/etc/localtime` 从主机自动检测）。示例：`TZ=Europe/Berlin ralphex docs/plans/feature.md` - `RALPHEX_CLAUDE_PROVIDER` - Claude 提供商模式：`default` 或 `bedrock`（仅限 Docker 包装脚本） **Docker socket 支持：** `--docker` 标志（或 `RALPHEX_DOCKER_SOCKET=1`）将主机 Docker socket 挂载到容器中，从而支持 testcontainers 和依赖 Docker 的工作流： ``` ralphex --docker docs/plans/feature.md ralphex --docker --dry-run # verify socket mount in command ``` - 自动检测 socket GID 并传递 `DOCKER_GID` 环境变量以进行基础镜像组设置 - 在 Linux 上发出安全警告（macOS 具有 VM 隔离，无需警告） - 如果 socket 文件不存在则报错退出（快速失败，无静默降级） **AWS Bedrock 支持：** 当设置了 `--claude-provider=bedrock` 或 `RALPHEX_CLAUDE_PROVIDER=bedrock` 时： - 跳过钥匙串凭据提取（Bedrock 认证不需要） - AWS 凭据通过 `aws configure export-credentials` 自动从 `AWS_PROFILE` 导出 - 必需的 Bedrock 环境变量会传递给容器：`CLAUDE_CODE_USE_BEDROCK`、`AWS_REGION`、凭据 Bedrock 所需环境： - `AWS_REGION` - 启用了 Bedrock 的 AWS 区域 - `AWS_PROFILE` 或 `AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY` - 身份验证 注意：使用 `--claude-provider=bedrock` 时会自动设置 `CLAUDE_CODE_USE_BEDROCK=1`。 ``` # 使用 AWS profile（自动导出凭证） export AWS_PROFILE=my-bedrock-profile export AWS_REGION=us-east-1 ralphex --claude-provider=bedrock docs/plans/feature.md # 或使用环境变量进行会话级设置 export RALPHEX_CLAUDE_PROVIDER=bedrock ralphex docs/plans/feature.md ``` 有关详细的 IAM 策略和设置说明，请参见 [Bedrock 设置文档](docs/bedrock-setup.md)。 **额外的卷挂载：** ``` # 通过 CLI flags（可使用多个 -v） ralphex -v /data:/mnt/data:ro -v /models:/mnt/models docs/plans/feature.md # 通过环境变量（逗号分隔） RALPHEX_EXTRA_VOLUMES="/data:/mnt/data:ro,/models:/mnt/models" ralphex docs/plans/feature.md ``` **额外的环境变量：** ``` # 通过 CLI flags（可使用多个 -E） ralphex -E DEBUG=1 -E API_KEY docs/plans/feature.md # 通过环境变量（逗号分隔） RALPHEX_EXTRA_ENV="DEBUG=1,LOG_LEVEL=verbose" ralphex docs/plans/feature.md # name-only 形式从主机继承值（推荐用于 secrets） export API_KEY=secret123 ralphex -E API_KEY docs/plans/feature.md # 包含逗号的值需要 -E flag（环境变量会按逗号分割） ralphex -E "TAGS=foo,bar,baz" docs/plans/feature.md ``` **调试：** ``` ralphex --dry-run docs/plans/feature.md # show docker command without executing ``` `--dry-run` 标志会打印将要执行的完整 `docker run` 命令。对于调试容器配置或复制命令以供手动执行非常有用。 注意：当将命令复制到不同的 shell 时，继承的环境变量（不带 `=value` 的 `-E FOO`）将不起作用。请使用显式值以确保可移植性。 **更新：** ``` ralphex --update # pull latest docker image ralphex --update-script # update the wrapper script itself ```

可用镜像

发布了两个镜像： | 镜像 | 描述 | |-------|-------------| | `ghcr.io/umputun/ralphex:latest` | 包含 Claude Code、Codex 和核心工具的基础镜像 | | `ghcr.io/umputun/ralphex-go:latest` | Go 开发（在基础镜像上扩展了 Go 工具链） | **基础镜像包含：** | 工具 | 版本 | 用途 | |------|---------|---------| | Claude Code | latest | AI 编程助手 | | Codex | latest | 外部代码审查 | | Node.js/npm | 24.x | Claude Code 所需 | | Python/pip | 3.x | 脚本和自动化 | | git | 2.x | 版本控制 | | docker-cli | - | 用于容器工作流的 Docker 客户端 | | make | 4.x | 构建自动化 | | gcc, musl-dev | - | 用于原生扩展的 C 编译器 | | bash | 5.x | Shell | | fzf | - | 用于计划选择的模糊查找器 | | ripgrep | - | 快速搜索（被 Claude Code 使用） | **Go 镜像额外包含：** | 工具 | 版本 | 用途 | |------|---------|---------| | Go | 1.26.0 | Go 编译器和运行时 | | golangci-lint | latest | Go 代码检查工具 | | moq | latest | Mock 生成器 | | goimports | latest | 导入格式化工具 | **对于 Go 项目**，使用 `-go` 镜像： ``` RALPHEX_IMAGE=ghcr.io/umputun/ralphex-go:latest ralphex docs/plans/feature.md ``` **对于其他语言**，通过扩展基础镜像并添加你的语言工具链来创建自定义镜像。Go 镜像（`Dockerfile-go`）展示了此模式： ``` FROM ghcr.io/umputun/ralphex:latest # 从官方发行版安装 go ARG GO_VERSION=1.26.0 RUN ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/') && \ wget -qO- "https://go.dev/dl/go${GO_VERSION}.linux-${ARCH}.tar.gz" | tar -xz -C /usr/local ENV GOROOT=/usr/local/go ENV GOPATH=/home/app/go ENV PATH="${PATH}:${GOROOT}/bin:${GOPATH}/bin" # 安装 go tools RUN wget -qO- https://raw.githubusercontent.com/golangci/golangci-lint/HEAD/install.sh | sh -s -- -b /usr/local/bin && \ GOBIN=/usr/local/bin go install github.com/matryer/moq@latest && \ GOBIN=/usr/local/bin go install golang.org/x/tools/cmd/goimports@latest ``` Rust、Java 或任何其他语言也采用相同方法： ``` FROM ghcr.io/umputun/ralphex:latest # rust RUN apk add --no-cache rust cargo ENV CARGO_HOME=/home/app/.cargo PATH="${PATH}:${CARGO_HOME}/bin" # java RUN apk add --no-cache openjdk21-jdk ENV JAVA_HOME=/usr/lib/jvm/java-21-openjdk PATH="${PATH}:${JAVA_HOME}/bin" ``` 构建并使用： ``` docker build -t my-ralphex -f Dockerfile.python . RALPHEX_IMAGE=my-ralphex ralphex docs/plans/feature.md ```

使用自定义端口的示例： ``` RALPHEX_PORT=3000 ralphex --serve --port=3000 docs/plans/feature.md ``` ## 使用方法 **注意：** 必须从仓库根目录（即 `.git` 所在的位置）运行 ralphex。 ``` # 使用 task loop + reviews 执行 plan ralphex docs/plans/feature.md # 使用 fzf 选择 plan，如果不存在则以交互方式创建一个 ralphex # review-only 模式（跳过 task 执行） ralphex --review docs/plans/feature.md # external-only 模式（跳过 tasks 和首次 review，仅运行 external review loop） ralphex --external-only # tasks-only 模式（仅运行 task 阶段，跳过所有 reviews） ralphex --tasks-only docs/plans/feature.md # 在隔离的 git worktree 中运行（仅限 full 和 tasks-only 模式） ralphex --worktree docs/plans/feature.md # 覆盖用于 review diff 的默认分支 ralphex --review --base-ref develop ralphex --review --base-ref abc1234 --skip-finalize # 在当前项目中初始化本地 .ralphex/ config（注释掉的默认值） ralphex --init # 交互式创建 plan ralphex --plan "add user authentication" # 使用自定义 max iterations ralphex --max-iterations=100 docs/plans/feature.md # 限制 external review iterations（0 = 自动，从 max-iterations 派生） ralphex --max-external-iterations=5 docs/plans/feature.md # 在 3 轮未更改后终止 external review（stalemate detection） ralphex --review-patience=3 docs/plans/feature.md # 在 rate limit 时等待并重试（而不是退出） ralphex --wait=1h docs/plans/feature.md # 为 tasks 和 reviews 使用不同的模型（例如，tasks 用 opus，reviews 用 sonnet） ralphex --task-model=opus --review-model=sonnet docs/plans/feature.md # 在不编辑 config 的情况下为单次运行使用 provider overrides ralphex --claude-command=/path/to/codex-as-claude.sh --claude-args= --external-review-tool=custom --custom-review-script=/path/to/review.sh docs/plans/feature.md # 设置 per-session timeout 以终止挂起的 claude sessions ralphex --session-timeout=30m docs/plans/feature.md # 在 5 分钟无输出时终止 claude session（idle detection） ralphex --idle-timeout=5m docs/plans/feature.md # 使用 web dashboard ralphex --serve docs/plans/feature.md # 自定义端口的 web dashboard ralphex --serve --port=3000 docs/plans/feature.md ``` ### 选项 | 标志 | 描述 | 默认值 | |------|-------------|---------| | `-m, --max-iterations` | 最大任务迭代次数 | 50 | | `--max-external-iterations` | 覆盖外部审查迭代限制（0 = 自动） | 0 | | `--review-patience` | 在 N 轮无更改后终止外部审查（0 = 禁用） | 0 | | `-r, --review` | 跳过任务执行，运行完整的审查流水线 | false | | `-e, --external-only` | 跳过任务和首次审查，仅运行外部审查循环 | false | | `-c, --codex-only` | `--external-only` 的别名（已弃用） | false | | `-t, --tasks-only` | 仅运行任务阶段，跳过所有审查 | false | | `-b, --base-ref` | 覆盖用于审查差异的默认分支（分支名称或提交哈希） | 自动检测 | | `--skip-finalize` | 即使在配置中启用也跳过 finalize 步骤 | false | | `--task-model` | 用于任务执行的模型，格式为 `model[:effort]`（例如，`opus`、`opus:high`、`:medium`）。Effort 值：`low`、`medium`、`high`、`xhigh`、`max`。作为 `--model ` 和/或 `--effort ` 附加到 `claude_command`；自定义包装器可能会忽略或实现这些标志 | 空 | | `--review-model` | 用于审查阶段的模型，格式为 `model[:effort]`（回退到 `--task-model`）。语法和包装器行为与 `--task-model` 相同 | 空 | | `--claude-command` | 为本次运行覆盖兼容 Claude 的命令 | 配置/默认 | | `--claude-args` | 为本次运行覆盖兼容 Claude 的命令参数。使用 `--claude-args=` 可清除已配置/默认的参数 | 配置/默认 | | `--external-review-tool` | 为本次运行覆盖外部审查工具（`codex`、`custom` 或 `none`） | 配置/默认 | | `--custom-review-script` | 为本次运行覆盖自定义外部审查脚本 | 配置/默认 | | `--wait` | 触发速率限制后重试前的等待时长（例如，`1h`、`30m`） | 禁用 | | `--session-timeout` | claude 的每次会话超时时间（例如，`30m`、`1h`）。会终止挂起的会话 | 禁用 | | `--idle-timeout` | 当指定时间内无输出时终止 claude 会话（例如，`5m`）。在每行输出时重置 | 禁用 | | `--worktree` | 在隔离的 git worktree 中运行（仅限完整和仅任务模式） | false | | `--plan` | 交互式创建计划（提供描述） | - | | `-s, --serve` | 启动 Web 仪表板进行实时流式输出 | false | | `-p, --port` | Web 仪表板端口（与 `--serve` 一起使用） | 8080 | | `-w, --watch` | 要监视进度文件的目录（可重复） | - | | `-d, --debug` | 启用调试日志 | false | | `--no-color` | 禁用彩色输出 | false | | `--init` | 在当前项目中初始化本地 `.ralphex/` 配置 | - | | `--reset` | 交互式将全局配置重置为嵌入的默认值 | - | | `--dump-defaults` | 将原始嵌入默认值提取到指定目录 | - | | `--config-dir` | 自定义配置目录（环境变量：`RALPHEX_CONFIG_DIR`） | `~/.config/ralphex` | ## 计划文件格式 计划是带有任务部分的 Markdown 文件。每个任务都有由 Claude 标记为已完成的复选框。 ``` # Plan: 添加用户认证 ## 概述 Add JWT-based authentication to the API. ## 验证命令 - `go test ./...` - `golangci-lint run` ### Task 1: 添加 auth middleware - [ ] Create JWT validation middleware - [ ] Add to router for protected routes - [ ] Add tests - [ ] Mark completed ### Task 2: 添加 login endpoint - [ ] Create /api/login handler - [ ] Return JWT on successful auth - [ ] Add tests - [ ] Mark completed ``` **要求：** - 任务标题必须使用 `### Task N:` 或 `### Iteration N:` 格式（N 可以是整数或非整数，如 `2.5`、`2a`） - 复选框：`- [ ]`（未完成）或 `- [x]`（已完成） - 复选框只能放在任务部分（`### Task N:` 或 `### Iteration N:`）。不要将复选框放在成功标准、概述或上下文中 — 它们会导致额外的循环迭代。当它们出现时代理会优雅地处理，但计划作者应避免使用它们以获得最佳行为。 - 包含带有测试/代码检查命令的 `## Validation Commands` 部分 - 将计划放在 `docs/plans/` 目录中（可通过 `plans_dir` 配置） ## 审查代理 审查流水线是完全可自定义的。ralphex 附带适用于任何语言的合理默认值，但你可以修改代理、添加新代理或完全替换提示词以匹配你的特定工作流。 ### 默认代理 这 5 个代理涵盖了常见的审查问题，开箱即用。根据你的需求自定义或替换它们： | 代理 | 阶段 | 目的 | |-------|-------|---------| | `quality` | 第 1 次和第 2 次 | Bug、安全问题、竞态条件 | | `implementation` | 第 1 次和第 2 次 | 验证代码是否达到既定目标 | | `testing` | 仅第 1 次 | 测试覆盖率和质量 | | `simplification` | 仅第 1 次 | 检测过度工程化 | | `documentation` | 仅第 1 次 | 检查是否需要更新文档 | ### 代理选项 (Frontmatter) 代理文件支持可选的 YAML frontmatter 用于每个代理的配置： ``` --- model: haiku agent: code-reviewer --- Review the code for quality issues... ``` | 选项 | 值 | 描述 | |--------|--------|-------------| | `model` | `haiku`、`sonnet`、`opus` | 此代理使用的 Claude 模型 | | `agent` | 任何字符串 | Claude Code Task 工具子代理类型 | 这两个选项都是可选的。没有 frontmatter 时，代理使用默认模型和 `general-purpose` 子代理类型。完整的模型 ID（例如 `claude-sonnet-4-5-20250929`）会被标准化为短关键字（`sonnet`），因为 Claude Code 仅接受 `haiku`、`sonnet`、`opus`。无效的模型值会被丢弃并发出警告。 ### 模板语法 自定义提示词文件支持变量展开。所有变量都使用 `{{VARIABLE}}` 语法。 **可用变量：** | 变量 | 描述 | 示例值 | |----------|-------------|---------------| | `{{PLAN_FILE}}` | 正在执行的计划文件的路径 | `docs/plans/feature.md` | | `{{PROGRESS_FILE}}` | 进度日志文件的路径 | `.ralphex/progress/progress-feature.txt` | | `{{GOAL}}` | 人类可读的目标描述 | `implementation of plan at docs/plans/feature.md` | | `{{DEFAULT_BRANCH}}` | 默认分支名称（可通过 `--base-ref` 或 `default_branch` 配置覆盖） | `main`、`master`、`origin/main` | | `{{agent:name}}` | 展开为指定代理的 Task 工具指令 | （见下文） | **代理引用：** 使用 `{{agent:name}}` 语法在提示词文件中引用代理： ``` Launch the following review agents in parallel: {{agent:quality}} {{agent:implementation}} {{agent:testing}} ``` 每个 `{{agent:name}}` 都会展开为 Task 工具指令，告诉 Claude Code 运行该代理。代理内容中的变量也会被展开，因此代理可以使用 `{{DEFAULT_BRANCH}}` 或其他变量。 ### 自定义 整个系统专为自定义而设计 - 包括任务执行和审查： **代理文件**（`~/.config/ralphex/agents/`）： - 首次运行时，ralphex 会将 5 个默认代理文件作为注释掉的模板安装。它们作为示例 — 完全被注释掉时，它们是不活动的，将使用嵌入的默认值。取消注释并编辑以进行自定义 - 每个文件的回退机制：对于每个代理，ralphex 会检查本地 `.ralphex/agents/` → 全局 `~/.config/ralphex/agents/` → 嵌入默认值。这 5 个嵌入代理始终是基线 — 从磁盘删除代理文件不会禁用它，嵌入版本将作为回退使用 - 要禁用特定代理，请从提示词文件（`review_first.txt`、`review_second.txt`）中删除其 `{{agent:name}}` 引用，而不是代理文件本身 - 添加新的 `.txt` 文件以创建自定义代理（在提示词中使用 `{{agent:name}}` 引用它们） - 运行 `ralphex --init` 以创建带有注释掉默认值的本地 `.ralphex/` 项目配置 - 运行 `ralphex --reset` 以交互式恢复默认值，或手动删除所有文件 - 运行 `ralphex --dump-defaults ` 以提取原始默认值以供比较 - 使用 `/ralphex-update` Claude Code 技能将更新后的默认值智能合并到自定义文件中 - 或者，直接在提示词文件中引用已安装在你的 Claude Code 中的代理（见下例） **提示词文件**（`~/.config/ralphex/prompts/`）： - `task.txt` - 任务执行提示词 - `review_first.txt` - 综合审查（默认：5 个与语言无关的代理 - quality、implementation、testing、simplification、documentation；可自定义） - `codex.txt` - codex 评估提示词（Claude 评估 codex 输出） - `codex_review.txt` - codex 审查提示词（发送给 codex 外部审查工具） - `custom_review.txt` - 自定义外部审查提示词（发送给自定义审查脚本） - `custom_eval.txt` - 自定义评估提示词（Claude 评估自定义工具输出） - `review_second.txt` - 最终审查，仅限关键/主要问题（默认：2 个代理 - quality、implementation；可自定义） - `make_plan.txt` - 交互式计划创建提示词 - `finalize.txt` - 可选的 finalize 步骤提示词（默认禁用） **注释行和 Markdown 标题：** 文件顶部以 2 行或更多连续注释行（以 `#` 开头）组成的起始块被视为元注释，在加载时会被剥离。顶部的单个 `# Title` 会被保留（被视为 Markdown 标题）。文件正文中稍后出现的注释行将始终被保留： ``` # 此单行标题保留为 markdown 标题 check for SQL injection # 此正文中间的注释也被保留 check for XSS ``` *仅*包含注释行（每行都以 `#` 开头）的文件被视为未修改的模板，并回退到嵌入的默认值。这就是被注释掉的默认文件的工作方式 — 一旦你添加任何非注释内容，文件将被原样使用。 注意：不支持行内注释（`text # comment` 会保留整行）。 **示例：** - 为金融科技项目添加专注于安全的代理 - 如果过度工程化不是问题，从提示词文件中删除 `{{agent:simplification}}` - 创建特定语言的代理（Python linting、TypeScript 类型） - 修改提示词以更改每个阶段运行的代理数量 **直接使用 Claude Code 代理：** 无需创建代理文件，你可以直接在提示词文件中引用安装在你的 Claude Code 中的代理： ``` # 在 review_first.txt 中 - 仅列出 agent 名称及其 prompts Agents to launch: 1. qa-expert - "Review for bugs and security issues" 2. go-test-expert - "Review test coverage and quality" 3. go-smells-expert - "Review for code smells" ``` ## 要求 - `claude` - Claude Code CLI - `fzf` - 用于计划选择（可选） - `codex` - 用于外部审查（可选） ## 配置 ralphex 使用位于 `~/.config/ralphex/` 的配置目录（可使用 `--config-dir` 或 `RALPHEX_CONFIG_DIR` 覆盖），结构如下： ``` ~/.config/ralphex/ ├── config # main configuration file (INI format) ├── prompts/ # custom prompt templates │ ├── task.txt │ ├── review_first.txt │ ├── review_second.txt │ ├── codex.txt │ ├── codex_review.txt │ ├── custom_review.txt │ ├── custom_eval.txt │ ├── make_plan.txt │ └── finalize.txt └── agents/ # custom review agents (*.txt files) ``` 首次运行时，ralphex 会创建此目录及默认配置。 **注释模板：** - 配置文件安装时所有内容都被注释掉（带有 `# ` 前缀） - 仅取消注释你要自定义的设置 - 保持全注释状态的文件会随新默认值自动更新 - 一旦你取消注释任何设置，文件将被保留且不会被覆盖 ### 本地项目配置 项目可以使用项目根目录中的 `.ralphex/` 目录覆盖全局设置。运行 `ralphex --init` 以创建带有注释掉默认值的配置： ``` project/ ├── .ralphex/ # optional, project-local config │ ├── config # overrides specific settings │ ├── prompts/ # custom prompts for this project │ └── agents/ # custom agents for this project ``` **优先级：** CLI 标志 > 本地 `.ralphex/` > 全局 `~/.config/ralphex/` > 嵌入默认值 使用 `--config-dir` 或 `RALPHEX_CONFIG_DIR` 覆盖全局配置位置。这对于维护不同工作流的独立代理/提示词集非常有用。 与提供商相关的 CLI 标志（`--claude-command`、`--claude-args`、`--external-review-tool` 和 `--custom-review-script`）遵循相同的优先级，并仅为当前调用覆盖配置。这对于切换包装器或审查工具而无需维护单独的配置目录非常有用。 **合并行为：** - **配置文件**：逐字段覆盖（本地值覆盖全局值，缺失字段回退） - **提示词**：逐文件回退（每个提示词文件：本地 → 全局 → 嵌入） - **代理**：逐文件回退（每个代理文件：本地 → 全局 → 嵌入，与提示词相同） ### 配置选项 | 选项 | 描述 | 默认值 | |--------|-------------|---------| | `claude_command` | Claude CLI 命令 | `claude` | | `claude_args` | Claude CLI 参数 | `--dangerously-skip-permissions --output-format stream-json --verbose` | | `task_model` | 用于任务执行的模型，格式为 `model[:effort]`（例如，`opus`、`opus:high`、`:medium`）。Effort：`low`、`medium`、`high`、`xhigh`、`max`。作为 `--model ` 和/或 `--effort ` 附加到 `claude_command`；自定义包装器可能会忽略或实现这些标志 | 空 | | `review_model` | 用于审查阶段的模型，格式为 `model[:effort]`。如果为空，则回退到 `task_model`。语法和包装器行为与 `task_model` 相同 | 空 | | `codex_enabled` | 启用 codex 审查阶段 | `true` | | `codex_command` | Codex CLI 命令 | `codex` | | `codex_model` | Codex 模型 ID | `gpt-5.4` | | `codex_reasoning_effort` | 推理努力级别 | `xhigh` | | `codex_timeout_ms` | Codex 超时时间（毫秒） | `3600000` | | `codex_sandbox` | 沙箱模式 | `read-only` | | `external_review_tool` | 外部审查工具（`codex`、`custom`、`none`） | `codex` | | `custom_review_script` | 自定义审查脚本的路径（当 `external_review_tool = custom` 时） | - | | `max_external_iterations` | 覆盖外部审查迭代限制（0 = 自动，从 `max_iterations` 派生） | `0` | | `review_patience` | 在连续 N 轮无更改后终止外部审查（0 = 禁用） | `0` | | `iteration_delay_ms` | 迭代之间的延迟 | `2000` | | `task_retry_count` | 任务重试次数 | `1` | | `finalize_enabled` | 在审查后启用 finalize 步骤 | `false` | | `move_plan_on_completion` | 成功后将已完成的计划文件移动到 `docs/plans/completed/`（对于外部计划生命周期工作流可禁用） | `true` | | `use_worktree` | 在隔离的 git worktree 中运行每个计划（仅限完整和仅任务模式） | `false` | | `plans_dir` | 计划目录 | `docs/plans` | | `default_branch` | 覆盖自动检测的用于审查差异的默认分支 | 自动检测 | | `vcs_command` | 用于 git 后端的 VCS 命令（对于 hg 仓库，设置为转换脚本） | `git` | | `commit_trailer` | 附加到所有 ralphex 编排的 git 提交的 trailer 行 | 禁用 | | `color_task` | 任务执行阶段颜色（十六进制） | `#00ff00` | | `color_review` | 审查阶段颜色（十六进制） | `#00ffff` | | `color_codex` | Codex 审查颜色（十六进制） | `#ff00ff` | | `color_claude_eval` | Claude 评估颜色（十六进制） | `#64c8ff` | | `color_warn` | 警告消息颜色（十六进制） | `#ffff00` | | `color_error` | 错误消息颜色（十六进制） | `#ff0000` | | `color_signal` | 完成/失败信号颜色（十六进制） | `#ff6464` | | `color_timestamp` | 时间戳前缀颜色（十六进制） | `#8a8a8a` | | `color_info` | 信息消息颜色（十六进制） | `#b4b4b4` | | `claude_error_patterns` | 在 claude 输出中检测的模式（以逗号分隔） | `You've hit your limit,API Error:,cannot be launched inside another Claude Code session,Not logged in,Your usage allocation has been disabled by your admin` | | `codex_error_patterns` | 在 codex 输出中检测的模式（以逗号分隔） | `Rate limit,quota exceeded,You've hit your usage limit` | | `claude_limit_patterns` | 触发等待+重试的 claude 限制模式（以逗号分隔） | `You've your limit,Your usage allocation has been disabled by your admin` | | `codex_limit_patterns` | 触发等待+重试的 codex 限制模式（以逗号分隔） | `Rate limit,quota exceeded,You've hit your usage limit` | | `wait_on_limit` | 触发速率限制后重试前的等待时长（例如，`1h`、`30m`） | 禁用 | | `session_timeout` | claude 的每次会话超时时间（例如，`30m`、`1h`）。会终止挂起的会话 | 禁用 | | `idle_timeout` | 当指定时间内无输出时终止 claude 会话（例如，`5m`）。在每行输出时重置 | 禁用 | 颜色使用 24 位 RGB（真彩色），所有现代终端（iTerm2、Kitty、Terminal.app、Windows Terminal、GNOME Terminal、Alacritty、Zed、VS Code 等）原生支持。较旧的终端将优雅降级。使用 `--no-color` 可完全禁用颜色。 错误模式使用不区分大小写的子字符串匹配。当在 claude 或 codex 输出中检测到模式时，ralphex 会优雅退出并附带提示信息，建议如何检查使用情况/状态。多个模式以逗号分隔，每个模式的空白会被修剪。 **速率限制重试：** 限制模式（`claude_limit_patterns`、`codex_limit_patterns`）工作方式类似，但支持可选的等待+重试行为。当设置了 `--wait`（或配置中的 `wait_on_limit`）时，匹配到限制模式会触发等待，然后自动重试而不是退出。如果没有设置 `--wait`，限制模式会回退到错误模式行为。限制模式会在错误模式之前被检查 — 如果同一字符串同时匹配两者，当启用等待时限制模式优先。 **升级注意事项：** 自定义了 `codex_limit_patterns` 或 `codex_error_patterns` 为先前默认值（`Rate limit,quota exceeded`）的用户将在更新时保留该自定义。要获取新的 OpenAI 计划配额措辞，请将 `,You've hit your usage limit` 附加到自定义列表中（或将该行重新注释掉以继承嵌入的默认值）。当 ChatGPT 计划配额耗尽时，Codex 会在 stderr 上发出此消息；如果没有该模式，`--wait` 将无法对其进行重试。 ### 自定义提示词 将自定义提示词文件放在 `~/.config/ralphex/prompts/` 中以覆盖内置提示词。缺失的文件将回退到嵌入的默认值。有关代理自定义，请参见[审查代理](#review-agents)部分。 ### 自定义外部审查 使用你自己的 AI 工具进行外部代码审查而不是 codex。这允许与 OpenRouter、本地 LLM 或任何自定义流水线集成。 **配置：** ``` # 在 ~/.config/ralphex/config 中 external_review_tool = custom custom_review_script = ~/.config/ralphex/scripts/my-review.sh ``` 对于无需编辑配置的一次性运行，使用 `--external-review-tool=custom --custom-review-script=/path/to/script.sh`。 **脚本接口：** 你的脚本接收一个单一参数：包含审查指令的提示词文件的路径。脚本将发现的问题输出到 stdout - ralphex 将它们传递给 Claude 进行评估和修复。 ``` #!/bin/bash # 示例：~/.config/ralphex/scripts/my-review.sh prompt_file="$1" # 读取 prompt（包含 diff 说明、目标、review 重点） prompt=$(cat "$prompt_file") # 调用你的 AI 工具（OpenRouter、本地 LLM 等） # 使用 curl 调用 OpenRouter 的示例： curl -s https://openrouter.ai/api/v1/chat/completions \ -H "Authorization: Bearer $OPENROUTER_API_KEY" \ -H "Content-Type: application/json" \ -d "{ \"model\": \"anthropic/claude-3.5-sonnet\", \"messages\": [{\"role\": \"user\", \"content\": $(echo "$prompt" | jq -Rs .)}] }" | jq -r '.choices[0].message.content' ``` **预期输出格式：** - 将发现的问题作为结构化列表写入 stdout - 使用格式：`file:line - 问题描述` - 没有问题时输出 `NO ISSUES FOUND` **迭代行为：** 外部审查循环默认最多运行 `max(3, max_iterations/5)` 次迭代。可通过 `max_external_iterations` 配置选项或 `--max-external-iterations` CLI 标志覆盖（0 = 自动）。 提示词中的 `{{DIFF_INSTRUCTION}}` 变量会随每次迭代进行调整： - **第一次迭代**：`git diff main...HEAD`（功能分支中的所有更改） - **后续迭代**：`git diff`（仅上次修复后未提交的更改） 这让审查工具可以在修复后专注于剩余问题。 ### 通知 ralphex 可以在执行完成或失败时发送通知。通知是可选的，默认禁用，并且是尽力而为的 - 失败会被记录但绝不会影响退出代码。 ``` # 在 ~/.config/ralphex/config 或 .ralphex/config 中 notify_channels = telegram, webhook notify_telegram_token = 123456:ABC-DEF notify_telegram_chat = -1001234567890 notify_webhook_urls = https://hooks.example.com/notify ``` 支持的渠道：`telegram`、`email`、`slack`、`webhook`、`custom`（脚本）。配置错误的渠道会在启动时被检测到。 有关设置指南、消息格式示例和自定义脚本集成的详细信息，请参见[通知文档](https://github.com/umputun/ralphex/blob/master/docs/notifications.md)。 **提示词自定义：** 自定义 `~/.config/ralphex/prompts/custom_review.txt` 以修改发送到脚本的提示词。可用变量： - `{{DIFF_INSTRUCTION}}` - 适合当前迭代的 git diff 命令 - `{{GOAL}}` - 关于正在实现的内容的人类可读描述 - `{{PLAN_FILE}}` - 计划文件的路径 - `{{PROGRESS_FILE}}` - 带有先前审查迭代的进度日志的路径 - `{{DEFAULT_BRANCH}}` - 检测到的默认分支（main、master 等） - `{{PREVIOUS_REVIEW_CONTEXT}}` - 先前的审查上下文（第一次迭代时为空，后续迭代时填充） 自定义 `~/.config/ralphex/prompts/custom_eval.txt` 以修改 Claude 评估工具输出的方式。 **Docker 注意事项：** 在 Docker 中运行 ralphex 时，你的脚本必须在容器内可访问： - 挂载你的脚本目录：`-v ~/.config/ralphex/scripts:/home/app/.config/ralphex/scripts:ro` - 确保脚本依赖项可用（基础镜像中包含 curl、jq 等） - 环境变量（API 密钥）必须传递给容器：`-e OPENROUTER_API_KEY` ### 为 Claude 阶段使用替代提供商 `claude_command` 和 `claude_args` 配置选项允许你用任何生成兼容 `stream-json` 输出的 CLI 替换 Claude Code。这意味着 codex、GitHub Copilot CLI、Gemini CLI、本地 LLM 或任何其他工具都可以驱动任务执行和审查阶段 — 你只需要一个包装脚本来转换工具的输出格式。使用 `--claude-command` 和 `--claude-args` 可以在不更改配置的情况下为单次运行选择包装器。 包含的工作示例： - [`scripts/codex-as-claude/codex-as-claude.sh`](https://github.com/umputun/ralphex/blob/master/scripts/codex-as-claude/codex-as-claude.sh) 封装 codex 以生成兼容 Claude 的事件 - [`scripts/copilot-as-claude/copilot-as-claude.sh`](https://github.com/umputun/ralphex/blob/master/scripts/copilot-as-claude/copilot-as-claude.sh) 封装 GitHub Copilot CLI 并将其原生 JSONL 流转换为兼容 Claude 的事件 要使用内置的 Copilot 包装器： ``` # 在 ~/.config/ralphex/config 或 .ralphex/config 中 claude_command = /path/to/scripts/copilot-as-claude/copilot-as-claude.sh claude_args = ``` 使用 `copilot login` 或设置 `COPILOT_GITHUB_TOKEN`、`GH_TOKEN` 或 `GITHUB_TOKEN` 之一进行身份验证。设置 `COPILOT_MODEL` 以选择模型。 包装器以原生自动驾驶模式运行 Copilot，带有 `--autopilot --no-ask-user --allow-all` 标志，以便任务和审查阶段可以跨多个模型轮次继续，而无需手动干预。 对于 ralphex 计划创建，它会切换到 `--autopilot --allow-all`，以便澄清可以通过 `<<>>` 信号浮出水面，而不是被无人值守问题路径所抑制。 要使用内置的 codex 包装器： ``` # 在 ~/.config/ralphex/config 或 .ralphex/config 中 claude_command = /path/to/scripts/codex-as-claude/codex-as-claude.sh claude_args = ``` 或者为单次调用选择它： ``` ralphex --claude-command=/path/to/scripts/codex-as-claude/codex-as-claude.sh --claude-args= docs/plans/feature.md ``` 在配置中将 `claude_args` 设置为空是可选的。请注意，由于配置回退行为，默认的 Claude 标志（`--dangerously-skip-permissions`、`--output-format stream-json`、`--verbose`）可能仍会被传递。当你需要为单次运行显式清除已配置/默认的参数时，请使用 CLI 形式 `--claude-args=`。包装脚本应该优雅地忽略未知标志 — 包含的脚本通过其 `*) shift ;;` 捕获所有项来实现这一点。 包含的 Codex 和 Copilot 包装器要求 `PATH` 中有 `jq` 用于 JSON 转换。 提供商特定的环境变量： - `COPILOT_MODEL`、`COPILOT_GITHUB_TOKEN`、`GH_TOKEN`、`GITHUB_TOKEN` - Copilot 模型选择和无头身份验证 - `CODEX_MODEL` - 要使用的 codex 模型（默认：codex 默认） - `CODEX_SANDBOX` - 沙箱模式（默认：`danger-full-access`） - `CODEX_VERBOSE` - 设置为 `1` 以在流中包含命令执行输出（默认：`0`，仅显示代理消息） 有关为其他提供商编写包装器的详细指南，请参见[自定义提供商文档](https://github.com/umputun/ralphex/blob/master/docs/custom-providers.md)。 ### 可配置的 VCS 后端 ralphex 可以通过 `vcs_command` 配置选项和自定义提示词文件与 Mercurial 仓库配合使用。 ``` # 在 ~/.config/ralphex/config 或 .ralphex/config 中 vcs_command = ~/.config/ralphex/scripts/hg2git.sh ``` 在 [`scripts/hg2git/hg2git.sh`](https://github.com/umputun/ralphex/blob/master/scripts/hg2git/hg2git.sh) 中包含了一个参考转换脚本。它将 ralphex 在内部使用的约 15 个 git 子命令映射到 Mercurial 等效项，并具有基于阶段的提交逻辑（在 draft 阶段使用 amend，在 public 阶段使用 commit）。需要 bash 4.0+（用于 diff 统计信息解析中的关联数组）。 你还需要自定义提示词文件，以替换 Claude 在审查期间作为 bash 命令执行的 git 命令。有关完整的设置说明、提示词替换示例、`.hgignore` 设置和已知限制，请参见 [Mercurial 支持文档](https://github.com/umputun/ralphex/blob/master/docs/hg-support.md)。

常见问题解答

**我安装了 ralphex，接下来该怎么做？** 在 `docs/plans/` 中创建一个计划文件（格式请参见[快速开始](#quick-start)），然后运行 `ralphex docs/plans/your-plan.md`。ralphex 将自动创建分支、执行任务并运行审查。 **为什么有两个审查阶段？** 第一次审查是综合性的（默认 5 个代理），第二次是最终检查，仅关注关键/主要问题（2 个代理）。参见[工作原理](#how-it-works)。 **如何使用我自己的 Claude Code 代理？** 在提示词文件中按名称直接引用它们，例如，`qa-expert - "Review for bugs"`。参见[自定义](#customization)。 **如果未安装 codex 怎么办？** Codex 是可选的。如果未安装，codex 审查阶段会自动跳过。 **我可以只运行审查而不执行任务吗？** 可以，使用 `--review` 标志对当前分支上已有的更改运行完整的审查流水线（阶段 2 → 阶段 3 → 阶段 4）。这适用于通过任何工具所做的更改 — Claude Code 的内置模式、手动编辑、其他代理等。切换到功能分支，提交更改，然后运行 `ralphex --review`。详情请参见[仅审查模式](#review-only-mode)。 **我可以在非 git 目录中运行 ralphex 吗？** 不能直接运行，但 ralphex 通过 `vcs_command` 配置选项和转换脚本支持 Mercurial 仓库。设置请参见[可配置的 VCS 后端](#configurable-vcs-backend)。 **如果我的仓库没有提交怎么办？** 当仓库为空时，ralphex 会提示创建初始提交。这是必需的，因为 ralphex 需要分支来实现功能隔离。回答“y”让 ralphex 暂存所有文件并创建初始提交，或者先手动创建一个 `git add . && git commit -m "initial commit"`。 **我应该在 master 还是功能分支上运行 ralphex？** 对于完整模式，从 master 开始 - ralphex 会自动从计划文件名创建分支。对于 `--review` 模式，首先切换到你的功能分支 - 审查使用 `git diff master...HEAD` 与 master 进行比较。 **自定义后如何恢复默认代理？** 运行 `ralphex --reset` 以交互式重置全局配置。选择要重置的组件（配置、提示词、代理）。或者，手动删除 `~/.config/ralphex/agents/` 中的所有 `.txt` 文件。要将更新后的默认值智能合并到自定义文件中（保留你的更改），请使用 `/ralphex-update` Claude Code 技能或 `ralphex --dump-defaults ` 提取默认值以供手动比较。 **如何禁用默认代理？** 从 `~/.config/ralphex/agents/` 删除代理文件不会禁用它 - 嵌入的默认值将作为回退使用。要禁用特定代理，请编辑提示词文件（`review_first.txt`、`review_second.txt`）并删除该代理的 `{{agent:name}}` 引用。 **本地 .ralphex/ 配置如何与全局配置交互？** 优先级：CLI 标志 > 本地 `.ralphex/config` > 全局 `~/.config/ralphex/config` > 嵌入默认值。每个设置都会覆盖相应的全局设置 — 无需复制整个文件。对于代理：逐文件回退（本地 → 全局 → 嵌入），与提示词相同。覆盖一个代理而无需复制所有其他代理。 **如果 ralphex 失败，未提交的更改会怎样？** ralphex 在每个完成的任务后都会提交。如果执行失败，已完成的任务已经提交到功能分支。来自失败任务的未提交更改将保留在工作目录中供手动检查。 **如果 ralphex 在执行过程中被中断怎么办？** 已完成的任务已经提交到功能分支。要恢复，重新运行 `ralphex docs/plans/.md`。ralphex 通过计划中的 `[x]` 复选框检测已完成的任务，并从第一个未完成的任务继续。对于审查会话，只需重新启动即可。审查从迭代 1 重新运行，但先前迭代的修复仍保留在代码库中。 **我可以在 ralphex 运行时调整计划或改变方向吗？** 可以，根据情况有两种方法： 1. **编辑 CLAUDE.md** — 用于行为更改（编码风格、库、约束）。每个任务都在启动时读取 CLAUDE.md 的新 Claude Code 会话中运行，因此更改会在下一个任务或迭代自动生效。无需停止 ralphex。 2. **停止、编辑计划、重新运行** — 用于结构性更改（重新排序任务、添加/删除任务、更改要求）。按 Ctrl+C 停止，编辑计划文件（取消选中 `[x]` → `[ ]` 以重做任务、添加新任务、修改描述），然后重新运行 `ralphex docs/plans/.md`。ralphex 会从第一个未完成的任务开始，并适应更新后的计划。 **进度文件和计划文件有什么区别？** 进度文件（`.ralphex/progress/progress-*.txt`）是实时执行日志 — 可使用 `tail` 命令监视它。计划文件跟踪任务状态（`[ ]` 与 `[x]`）。要恢复，在计划文件上重新运行 ralphex；它会自动找到未完成的任务。 **在运行 ralphex 之前我需要提交更改吗？** 视情况而定。如果计划文件是唯一的未提交更改，ralphex 会在创建功能分支后自动提交它并继续执行。如果其他文件有未提交的更改，ralphex 会显示一个有用的错误并提供选项：暂时隐藏（`git stash`）、先提交（`git commit -am "wip"`）或使用仅审查模式（`ralphex --review`）。 **agents/ 和 prompts/ 有什么区别？** 代理定义检查什么（审查指令）。提示词定义工作流如何运行（执行步骤、信号处理）。 **我可以在所有任务完成后运行自定义步骤吗？** 可以。自定义 `prompts/task.txt` 以在任务生命周期的任何点注入额外步骤。一种常见的模式是添加一个“门控步骤”，在所有任务完成之后但在发出完成信号之前运行。例如，在最后一个任务之后运行代码异味检查： ``` STEP 3 - COMPLETE (after validation passes): - ...existing steps... - If NO more [ ] checkboxes in the entire plan, proceed to STEP 4 STEP 4 - STYLE CHECK (only when all tasks are done): - Use /smells skill to analyze all files changed on this branch - Fix all reported style and code quality issues - Run tests and linter again to verify fixes - Commit fixes if any: fix: address code smell findings - Output exactly: <<>> ``` 这之所以有效是因为 ralphex 只检查 `ALL_TASKS_DONE` 信号 — 它不关心前面有多少步骤。同样的方法适用于任何工具或技能：安全扫描、格式化、文档生成等。将其放在 `~/.config/ralphex/prompts/task.txt` 中用于全局使用，或放在 `.ralphex/prompts/task.txt` 中用于特定项目。 **我可以将 ralphex 与 Claude Pro 计划一起使用吗？** 可以。Pro 计划更频繁地触及速率限制。使用 `--wait` 自动暂停并重试而不是退出： ``` ralphex --wait=1h docs/plans/feature.md ``` 当检测到速率限制时，ralphex 会等待指定的持续时间然后重试。执行需要更长的时间但可以无人值守完成。你也可以在配置中设置 `wait_on_limit = 1h` 以将其设为默认值。 **我可以使用 Cursor CLI 而不是 Claude Code 吗？** 可以。[Cursor CLI](https://cursor.com/cli) 已经过社区测试，可以作为直接替代方案。在 `~/.config/ralphex/config` 中配置： ``` claude_command = agent claude_args = --force --output-format stream-json ``` 主要区别：`agent` 命令（而不是 `claude`）、`--force` 标志（而不是 `--dangerously-skip-permissions`）。流格式和信号是兼容的。*注意：这是社区测试的，非官方支持。兼容性取决于 Cursor 维持与 Claude Code 的兼容性。* **我可以使用 codex、GitHub Copilot CLI 或其他模型进行任务执行而不是 Claude 吗？** 可以。使用内置的其中一个包装脚本将提供商输出转换为 Claude 的 stream-json 格式： ``` claude_command = /path/to/scripts/copilot-as-claude/copilot-as-claude.sh claude_args = ``` 对于 Copilot，使用 `copilot login` 或 `COPILOT_GITHUB_TOKEN`、`GH_TOKEN`、`GITHUB_TOKEN` 之一进行身份验证，并设置 `COPILOT_MODEL` 以覆盖默认模型。 内置的 Copilot 包装器以原生自动驾驶模式运行 Copilot，带有 `--autopilot --no-ask-user --allow-all`，用于无人值守的任务和审查执行。 对于 ralphex 计划创建，它会切换到 `--autopilot --allow-all`，以便澄清可以通过 `<<>>` 信号浮出水面，而不是被无人值守问题路径所抑制。 Codex 通过其包装器以相同的方式工作： ``` claude_command = /path/to/scripts/codex-as-claude/codex-as-claude.sh claude_args = ``` 设置 `CODEX_MODEL` 环境变量以选择模型。有关内置的 Copilot 示例以及为其他工具编写包装器的详细信息，请参见[使用替代提供商](#using-alternative-providers-for-claude-phases)和[自定义提供商文档](https://github.com/umputun/ralphex/blob/master/docs/custom-providers.md)。 **如何使用多个 Claude 账户？** 设置 `CLAUDE_CONFIG_DIR` 环境变量以指向备用 Claude 配置目录： ``` CLAUDE_CONFIG_DIR=~/.claude2 ralphex docs/plans/feature.md ``` 这与 Claude Code 本身使用的环境变量相同。使用 Docker 时，包装脚本会挂载指定目录并从路径派生出正确的 macOS 钥匙串服务名称。不使用 Docker 时，环境变量直接传递给子 Claude Code 进程。每个 Claude 安装都根据其配置目录将凭据存储在唯一的钥匙串条目下。不需要额外的配置 — 只需将 `CLAUDE_CONFIG_DIR` 指向正确的目录。 **我可以在所有阶段完成后运行某些操作（通知、变基提交等）吗？** 可以。在配置中启用 finalize 步骤，设置 `finalize_enabled = true`。它在成功的审查阶段之后运行一次（尽力而为 — 失败会被记录但不会阻碍成功）。默认的 `finalize.txt` 提示词会变基到默认分支上，并有选择地将提交压缩成逻辑组。自定义 `~/.config/ralphex/prompts/finalize.txt` 以执行其他操作，如发送通知、推送到远程仓库或运行自定义脚本。

## Web 仪表板 `--serve` 标志启动基于浏览器的仪表板，用于实时监控计划执行。 ``` ralphex --serve docs/plans/feature.md # web dashboard：http://localhost:8080 ``` ### 功能 - **实时流式输出** - 用于实时输出更新的 SSE 连接 - **阶段导航** - 按全部/任务/审查/Codex 阶段过滤 - **可折叠部分** - 带有展开/折叠的组织输出 - **文本搜索** - 查找文本并高亮显示（键盘快捷键：`/` 聚焦，`Escape` 清除） - **自动滚动** - 跟随输出，点击禁用 - **延迟加入支持** - 新客户端接收完整历史记录 仪表板使用带有与终端输出匹配的特定阶段颜色的深色主题。使用 `--serve` 时，所有文件和 stdout 日志记录将照常继续。 ### 多会话模式 `--watch` 标志允许同时监控多个 ralphex 会话： ``` # 监视特定目录以获取进度文件 ralphex --serve --watch ~/projects/frontend --watch ~/projects/backend # 在 config 文件中配置监视目录 # watch_dirs = /home/user/projects, /var/log/ralphex ``` 多会话功能： - **会话侧边栏** - 列出所有已发现的会话，点击切换（键盘快捷键：`S` 切换） - **活跃检测** - 通过文件锁定为运行中的会话提供脉动指示器 - **自动发现** - 新会话在开始时自动出现 ## Claude Code 集成（可选） ralphex 可从终端独立运行。或者，你可以向 Claude Code 添加斜杠命令以获得更集成的体验。 ### 可用命令 | 命令 | 描述 | |---------|-------------| | `/ralphex` | 启动并监控 ralphex 执行，带有交互式模式/计划选择 | | `/ralphex-plan` | 创建结构化实施计划，带有引导式上下文收集 | | `/ralphex-adopt` | 将各种源格式（OpenSpec、spec-kit、GitHub/GitLab issues、通用任务列表、自由格式 Markdown）的计划转换为 ralphex 格式的计划 | | `/ralphex-update` | 将更新后的嵌入默认值智能合并到自定义提示词/代理中 | ### 安装 ralphex CLI 是主要接口。Claude Code 技能（`/ralphex`、`/ralphex-plan`、`/ralphex-adopt` 和 `/ralphex-update`）是可选的便捷命令。 **通过插件市场安装（推荐）** ``` # 添加 ralphex marketplace /plugin marketplace add umputun/ralphex # 安装插件 /plugin install ralphex@umputun-ralphex ``` 优点：当市场刷新时（在 Claude Code 启动时）自动更新。 **手动安装（替代方案）** 斜杠命令定义托管在： - [`/ralphex`](https://ralphex.com/assets/claude/ralphex.md) - [`/ralphex-plan`](https://ralphex.com/assets/claude/ralphex-plan.md) - [`/ralphex-adopt`](https://ralphex.com/assets/claude/ralphex-adopt.md) - [`/ralphex-update`](https://ralphex.com/assets/claude/ralphex-update.md) 要安装，请让 Claude Code "install ralphex slash commands" 或手动将文件复制到 `~/.claude/commands/`。 ### 使用方法 安装完成后： ``` # 在 Claude Code 对话中 /ralphex-plan add user authentication # creates plan interactively /ralphex docs/plans/auth.md # launches execution "check ralphex" # gets status update ``` `/ralphex` 命令在后台运行 ralphex 并根据请求提供状态更新。`/ralphex-plan` 命令引导你通过上下文发现和方法选择来创建结构良好的计划。 ## 面向 LLM 有关针对 LLM 优化的文档，请参见 [llms.txt](llms.txt)。 ## 许可证 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。

标签：AI编程助手, Claude Code, EVTX分析, Git自动化, Go语言, SOC Prime, 上下文管理, 代码审查, 任务编排, 大型语言模型, 开发工具, 开源框架, 持续集成, 日志审计, 程序破解, 网络安全研究, 自主AI, 自动代码生成, 自动化执行, 请求拦截, 软件开发自动化