ralph-claude-code 多 Provider Agent 抽象ADR 0001 决策实录与七 CLI 能力矩阵解析【免费下载链接】ralph-claude-codeAutonomous AI development loop for Claude Code with intelligent exit detection项目地址: https://gitcode.com/GitHub_Trending/ra/ralph-claude-code导读本文深入解析 ralph-claude-codeRalph项目的第一份架构决策记录ADR 0001——Multi-Provider Agent Abstraction。它回答了 Ralph 自主开发循环中的一个根本问题当驱动循环的claude -p无头模式从订阅配额转向按 API token 计费时Ralph 如何摆脱对单一厂商的生死依赖文章完整还原了决策背景、被否决的替代方案订阅 TUI 驱动、实测的七款编码 CLI 能力矩阵以及各现有功能在不同 Provider 间的可移植性分析。读者将掌握 Ralph 走向 Provider 无关化的设计骨架、能力矩阵的正确阅读方式以及仓库源码中与这份 ADR 一一对应的实现证据。一、背景为什么 Ralph 必须做多 Provider 抽象Ralph 的自主开发循环autonomous development loop核心机制是反复以无头模式调用claudeCLIclaude -p …让 Agent 每轮执行一个任务、分析结果、决定继续或退出。这份 ADR 指出这种对单一 CLI 的依赖让 Ralph 的存续押注在了一个供应商决策上Anthropic 正在把claude -p无头模式的计费向 API credits按 token 计费迁移不再提供 OAuth/订阅配额路径。对一个核心价值是让 Agent 长时间持续循环运行的工具来说这构成存在性风险——每一次循环迭代都将按 token 计费且没有订阅配额可走。当时仓库评估了两条出路驱动订阅版 TUIMaestro /maestro-p方案用node-pty包装交互式claudeTUI把提示词敲进终端然后 tail 磁盘上的 JSONL 转录文件$CLAUDE_CONFIG_DIR/projects/cwd-slug/session-id.jsonl来收割模型输出——以此消耗 Max 订阅配额而非 API credits。变为 Provider 无关provider-agnostic把哪个 Agent CLI 来驱动循环做成一个配置开关让 Codex、Gemini、OpenCode、Droid、Kilocode、Copilot 或任何未来的无头编码 CLI 都能驱动 Ralph。无头claude只是众多按 API 计费选项之一。本 ADR 的职责就是在两者之间做出裁定并记录后续所有阶段适配器契约、抽象接缝、各 Provider 适配器所依赖的、经实际探测的能力矩阵。二、决策Ralph 将走向 Provider 无关决策结论选择方案 2——Ralph 将变为 Provider 无关。运行哪个 Agent成为一个配置项AGENT_PROVIDER解析优先级为环境变量 CLI 参数 .ralphrc在用户显式选择其他 Provider 之前Claude 作为参考适配器reference adapter默认行为保持逐字节byte-for-byte不变。整个工作被编排为抽象优先、增量落地分阶段 issue 索引位于multi-providerepicissue #310–#325工作顺序为 #310 → #311 → #312 → … → #325。其中[P0.1]#310本 ADR即方向裁定与能力矩阵[P0.2]#311下一份 ADR0002-agent-adapter-contract.md即适配器契约本 ADR 已在文末标注其为Next ADR。这一阶段化编排的意义在于先固化是什么、支持什么矩阵再定义怎么接入契约最后才写代码避免在方向未定时过早实现。被否决的替代方案驱动订阅版 TUImaestro-p方案巧妙且确实解决了计费问题但被否决理由有三维护跑步机Maintenance treadmill它依赖交互式TUI 的渲染细节和私有磁盘 JSONL 转录格式——两者都是未文档化的内部实现Anthropic 任何一次发布都可能改变导致驱动装置在毫无预警的情况下失效。ToS / 检测风险以机器规模自动化交互式客户端去消耗订阅配额与厂商计费意图相悖很可能违反服务条款一旦厂商做出检测/执行策略变更该方案甚至账号可能一夜之间被禁用。单一厂商锁定依旧存在即使永远可用它也只是买到了更便宜的Claude对偏好或已付费其他模型的用户毫无帮助。而 Provider 无关路径把厂商计费决策视为市场信号——让市场决定。每个 Provider 只是一个选项当某一个变贵或不可用时用户只需切换一个配置项而不是放弃 Ralph。三、Provider 能力矩阵七款 CLI 实测对照这份矩阵是 ADR 中信息密度最高的部分。它于2026-06-15对已安装的 CLI 逐一生效探测得出通过读取每个工具的--help及相关子命令--help。给出具体版本号是为了保证矩阵可复现。3.1 探测对象与版本Provider版本探测命令Claude参考实现2.1.177claude --versionCodexcodex-cli 0.137.0codex --versionGemini0.46.0gemini --versionOpenCode1.4.0opencode --versionKilocode0.22.0kilocode --versionDroid0.147.0droid --versionCopilotGitHub Copilot CLI 0.0.404copilot --version3.2 六维能力对照表ProviderHeadless 调用结构化输出按 id 续接预分配会话细粒度权限模型开关Claude参考-p/--print prompt--output-format json\|stream-json--resume id--session-id uuid--allowedTools/--disallowedTools--modelGemini-p/--prompt-o/--output-format json\|stream-json-r/--resume--session-id uuid--approval-mode default\|auto_edit\|yolo\|plan-m/--modelCodexcodex exec [PROMPT]支持 stdin--jsonJSONL·--output-schema file·-o/--output-last-message filecodex exec resume id--last—-s/--sandbox mode·--dangerously-bypass-approvals-and-sandbox-m/--modelDroiddroid exec [prompt]-o/--output-format json默认text·--input-format stream-json\|stream-jsonrpc-s/--session-id id·--fork id—--auto low\|medium\|high·--skip-permissions-unsafe-m/--model默认claude-opus-4-8OpenCodeopencode run [message]--format default\|json原始 JSON 事件-s/--session id·-c/--continue·--fork—--dangerously-skip-permissions-m/--model provider/modelKilocodekilocode --auto-j/--json需--auto·-i/--json-io双向-s/--session id·-c/--continue最近·-f/--fork shareId—--yolo-mo/--modelCopilot-p/--prompt text仅文本-s/--silent--stream mode--resume [id]·--continue—--allow-tool/--deny-tool/--allow-all--model3.3 探测中发现的关键修正与结论ADR 特意记录了相对 2026-06-14 初稿矩阵的修正这些细节正是未来实现适配器时最容易踩坑的地方Kilocode 支持按 id 续接通过-s/--session id另有-c/--continue只续最近会话、-f/--fork。初稿曾只列出 continue-last。Codex--json输出的是 JSONL最后一条 assistant 消息可用-o/--output-last-message捕获到文件可选的--output-schema能约束最终响应结构。Droid 的-o/--output-format默认是textJSON 必须显式请求多轮/流式输入用--input-format stream-json/stream-jsonrpc。默认模型为claude-opus-4-8。只有 Claude 和 Gemini 提供无竞态的预分配会话 id创建时传--session-id uuid。其他 Provider 都支持续接但只能按已发现的 id续接或 continue-last。Copilot 是降级特例完全没有机器可读输出开关--silent/--stream都是文本因此任何需要解析结构化事件的特性对它都不可用。注意ADR 明确将这份矩阵标注为时间点快照point-in-time snapshot——每个 CLI 的--help都可能在版本之间漂移升级 Provider 时必须重新探测。这是编写文章时也需要向读者强调的可复现性前提。四、功能可移植性Ralph 现有特性在跨 Provider 后的存亡矩阵解决能不能调用的问题本节解决调用之后 Ralph 的现有功能还剩多少。ADR 为每个适配器定义了需要在 capabilities 记录中声明的能力并逐项评估了 Ralph 既有特性的可移植性特性可移植性说明基于RALPH_STATUS文本块的退出检测全部 Provider 通用它是 Agent 输出的文本而非 Provider 的 JSON 字段因此在任何 Provider 上行为完全一致。这是 Ralph 的主要完成信号也是跨 Provider 迁移中风险最低的部分Token 计数 /MAX_TOKENS_PER_HOURProvider 受限仅当事件流携带 usage 信息时可用Claude、Gemini、Codex、Droid 大概率支持OpenCode / Kilocode 待定Copilot 无 → 禁用权限拒绝熔断#101Provider 受限需要机器可读的拒绝事件。Claude、Copilot 有丰富的权限flag但只有部分 CLI 会输出可解析的拒绝事件 → 按 Provider 逐个门控API 限额检测#100 / #183Provider 受限目前依赖 Claude 特有的rate_limit_eventJSON 结构每个 Provider 需要自己的模式否则该特性对其禁用会话连续性通用但有质量分层所有 Provider 都支持 resume只有 Claude 和 Gemini 支持预分配无竞态会话 id其余回退到按发现的 id 续接或 continue-last本节贯穿至后续所有阶段的治理规则是不受支持的特性必须以记录警告日志的方式优雅降级绝不静默误行为并且在用户选择不同AGENT_PROVIDER之前Claude 的行为保持不变。五、仓库源码印证ADR 不是空谈而是对现状的抽象ADR 0001 明确声明本 ADR 不含代码变更但它所描述的现状在仓库中有完整对应实现。理解这些实现才能理解为何Claude 默认行为不变这一不变量是可达成的。5.1claude -p的现状build_claude_command()ralph_loop.sh中的build_claude_command()是 Provider 无关化之后 Claude 适配器要重构的原型。它用全局数组CLAUDE_CMD_ARGS而非字符串拼接来保证 shell 注入安全依次追加可执行文件$CLAUDE_CODE_CMD默认claude对应矩阵中 Claude 的-p无头调用可选--model $CLAUDE_MODEL、--effort $CLAUDE_EFFORTissue #228CLAUDE_OUTPUT_FORMATjson时追加--output-format json对应矩阵结构化输出列CLAUDE_ALLOWED_TOOLS按逗号拆分后逐个作为独立数组元素追加到--allowedTools后repeated-args 格式CLAUDE_USE_CONTINUEtrue且存在 session id 时追加--resume id—— 源码注释明确解释了为何刻意不用--continueissue #151--continue会续接当前目录最近会话可能劫持用户活跃的 Claude Code 会话而--resume 具体 id只续接 Ralph 自己的会话有 loop context 时追加--append-system-prompt loop_context最后读取 prompt 文件内容以-p content传入注释指出 Claude CLI没有--prompt-file这类开关。值得注意的还有RALPH_VERBOSEtrue时的诊断日志issue #154它会打印将要传给 Claude 的 argv——但剔除 prompt 正文可能含敏感信息方便用户核对--allowedTools是否真正到达 Claude例如排查Bash(git *)拒绝问题。5.2 输出解析的现状lib/response_analyzer.shRalph 今天的输出分析位于lib/response_analyzer.sh其中与 ADR 能力矩阵直接对应的关键函数detect_output_format()判断输出是json还是text。它先检查首字符是否为{或[再用jq empty校验。特别地它对超大文件超过RALPH_JSONL_SAFE_MAX_BYTES默认 1 MB做了截断防护issue #250若大文件缺少type:result标记说明是 Claude 被中途 kill 导致的损坏 JSONL 流直接回退到 text 模式避免jq在畸形输入上挂死。这正是 ADR 0002 契约中detect_output_format()也防护截断 JSONL 流的出处。parse_json_response()处理三种 JSON 形态——扁平对象{status, exit_signal, ...}、Claude CLI 嵌套对象{result, sessionId, metadata:{...}}、Claude CLI stream-json 数组[{type:system...}, {type:result, sessionId, is_error...}]取最后一个result元素session id 从init/result元素合并。这三种形态正是 ADR 0002 中每个 Provider 的 normalizer 必须把原生输出折叠进单一分析结构的基线。5.3 路由先例SANDBOX_PROVIDERADR 选用的Provider 无关 配置开关 默认行为不变模式在仓库中已有成熟先例sandbox provider 路由。SANDBOX_PROVIDER值docker/e2b/ 空宿主机执行以相同方式解析环境变量 → CLI 参数 →.ralphrc见 templates/ralphrc.template 中SANDBOX_PROVIDER相关注释与 ralph_loop.sh 中大量case $SANDBOX_PROVIDER/if [[ $SANDBOX_PROVIDER ... ]]分发并由lib/sandbox_docker.sh的get_sandbox_status()等函数按 Provider 提供实现。这份 ADR 的后续实现ADR 0002 的适配器契约明确写道AGENT_PROVIDER的加载与分发将镜像这一已被验证的模式——这是无需引入新机制的关键可行性论据。六、落地路径与后续契约ADR 0002 预告ADR 0001 止步于方向 矩阵明确标注下一步是 ADR0002-agent-adapter-contract.md[P0.2]#311它被[P1.1]抽象接缝 适配器加载器、[P1.2]Claude 参考适配器、[P2.1]后续 Provider所阻塞/依赖。按本 ADR 的编排[P0.1]本 ADR方向裁定 能力矩阵[P0.2]ADR 0002定义适配器契约命令构建接口、输出归一化接口、能力声明 schema、注册约定[P1.1]实现接缝与加载器load_agent_adapter()[P1.2]把build_claude_command()与响应解析逻辑搬进lib/agents/claude.sh默认AGENT_PROVIDERclaude保证现有运行逐字节一致[P2.1]按矩阵逐 PR 接入新 Provider。本文不再展开契约细节但可以提示读者能力矩阵的降级特例如 Copilot 仅文本正是 ADR 0002 中supports_structured_output:false与RALPH_STATUS文本块承担退出检测的直接设计输入而templates/PROMPT.md中定义的---RALPH_STATUS---文本块含STATUS、FILES_MODIFIED、TESTS_STATUS、WORK_TYPE、EXIT_SIGNAL、RECOMMENDATION字段就是那份契约中权威完成信号的事实来源。七、后果评估正面厂商计费/可用性变化变成一次配置翻转而非存在性事件一份稳定、带版本引用的参考矩阵锚定了[P0.2]及全部 Phase 1 实现工作用户获得可选择性——逃离按 token 计费不再必须订阅 Claude TUI切换另一个 Provider 即可。负面 / 成本持续的 per-Provider 维护七款 CLI 的 flag、输出格式、会话模型各异每个--help都可能随版本漂移本 ADR 是时间点快照升级 Provider 需重新探测功能面不统一token / 权限 / API 限额检测必须逐个门控同一个 Ralph 运行在不同 Provider 上行为会不同Copilot 的纯文本输出必然导致一个真正降级的适配器。中性本 ADR不含代码变更只确认方向与矩阵实现从[P0.2]/[P1.1]开始。八、总结ADR 0001 是 Ralph 项目一次典型的用架构决策化解外部风险的记录它把Anthropic 计费政策变化这一外部不确定性通过Provider 能力矩阵 功能可移植性分级 优雅降级原则转化为内部可执行的工程路线图。对读者而言本文的六维能力对照表可以直接作为选择编码 CLI 时的能力参考build_claude_command()、detect_output_format()、parse_json_response()与SANDBOX_PROVIDER路由则是理解抽象接缝落点的第一手源码证据。若要继续深入推荐按顺序阅读下一份契约文档 docs/adr/0002-agent-adapter-contract.md以及其引用的 ralph_loop.shbuild_claude_command、lib/response_analyzer.sh、lib/sandbox_docker.sh 和 templates/PROMPT.md。【免费下载链接】ralph-claude-codeAutonomous AI development loop for Claude Code with intelligent exit detection项目地址: https://gitcode.com/GitHub_Trending/ra/ralph-claude-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
ralph-claude-code 多 Provider Agent 抽象：ADR 0001 决策实录与七 CLI 能力矩阵解析
ralph-claude-code 多 Provider Agent 抽象ADR 0001 决策实录与七 CLI 能力矩阵解析【免费下载链接】ralph-claude-codeAutonomous AI development loop for Claude Code with intelligent exit detection项目地址: https://gitcode.com/GitHub_Trending/ra/ralph-claude-code导读本文深入解析 ralph-claude-codeRalph项目的第一份架构决策记录ADR 0001——Multi-Provider Agent Abstraction。它回答了 Ralph 自主开发循环中的一个根本问题当驱动循环的claude -p无头模式从订阅配额转向按 API token 计费时Ralph 如何摆脱对单一厂商的生死依赖文章完整还原了决策背景、被否决的替代方案订阅 TUI 驱动、实测的七款编码 CLI 能力矩阵以及各现有功能在不同 Provider 间的可移植性分析。读者将掌握 Ralph 走向 Provider 无关化的设计骨架、能力矩阵的正确阅读方式以及仓库源码中与这份 ADR 一一对应的实现证据。一、背景为什么 Ralph 必须做多 Provider 抽象Ralph 的自主开发循环autonomous development loop核心机制是反复以无头模式调用claudeCLIclaude -p …让 Agent 每轮执行一个任务、分析结果、决定继续或退出。这份 ADR 指出这种对单一 CLI 的依赖让 Ralph 的存续押注在了一个供应商决策上Anthropic 正在把claude -p无头模式的计费向 API credits按 token 计费迁移不再提供 OAuth/订阅配额路径。对一个核心价值是让 Agent 长时间持续循环运行的工具来说这构成存在性风险——每一次循环迭代都将按 token 计费且没有订阅配额可走。当时仓库评估了两条出路驱动订阅版 TUIMaestro /maestro-p方案用node-pty包装交互式claudeTUI把提示词敲进终端然后 tail 磁盘上的 JSONL 转录文件$CLAUDE_CONFIG_DIR/projects/cwd-slug/session-id.jsonl来收割模型输出——以此消耗 Max 订阅配额而非 API credits。变为 Provider 无关provider-agnostic把哪个 Agent CLI 来驱动循环做成一个配置开关让 Codex、Gemini、OpenCode、Droid、Kilocode、Copilot 或任何未来的无头编码 CLI 都能驱动 Ralph。无头claude只是众多按 API 计费选项之一。本 ADR 的职责就是在两者之间做出裁定并记录后续所有阶段适配器契约、抽象接缝、各 Provider 适配器所依赖的、经实际探测的能力矩阵。二、决策Ralph 将走向 Provider 无关决策结论选择方案 2——Ralph 将变为 Provider 无关。运行哪个 Agent成为一个配置项AGENT_PROVIDER解析优先级为环境变量 CLI 参数 .ralphrc在用户显式选择其他 Provider 之前Claude 作为参考适配器reference adapter默认行为保持逐字节byte-for-byte不变。整个工作被编排为抽象优先、增量落地分阶段 issue 索引位于multi-providerepicissue #310–#325工作顺序为 #310 → #311 → #312 → … → #325。其中[P0.1]#310本 ADR即方向裁定与能力矩阵[P0.2]#311下一份 ADR0002-agent-adapter-contract.md即适配器契约本 ADR 已在文末标注其为Next ADR。这一阶段化编排的意义在于先固化是什么、支持什么矩阵再定义怎么接入契约最后才写代码避免在方向未定时过早实现。被否决的替代方案驱动订阅版 TUImaestro-p方案巧妙且确实解决了计费问题但被否决理由有三维护跑步机Maintenance treadmill它依赖交互式TUI 的渲染细节和私有磁盘 JSONL 转录格式——两者都是未文档化的内部实现Anthropic 任何一次发布都可能改变导致驱动装置在毫无预警的情况下失效。ToS / 检测风险以机器规模自动化交互式客户端去消耗订阅配额与厂商计费意图相悖很可能违反服务条款一旦厂商做出检测/执行策略变更该方案甚至账号可能一夜之间被禁用。单一厂商锁定依旧存在即使永远可用它也只是买到了更便宜的Claude对偏好或已付费其他模型的用户毫无帮助。而 Provider 无关路径把厂商计费决策视为市场信号——让市场决定。每个 Provider 只是一个选项当某一个变贵或不可用时用户只需切换一个配置项而不是放弃 Ralph。三、Provider 能力矩阵七款 CLI 实测对照这份矩阵是 ADR 中信息密度最高的部分。它于2026-06-15对已安装的 CLI 逐一生效探测得出通过读取每个工具的--help及相关子命令--help。给出具体版本号是为了保证矩阵可复现。3.1 探测对象与版本Provider版本探测命令Claude参考实现2.1.177claude --versionCodexcodex-cli 0.137.0codex --versionGemini0.46.0gemini --versionOpenCode1.4.0opencode --versionKilocode0.22.0kilocode --versionDroid0.147.0droid --versionCopilotGitHub Copilot CLI 0.0.404copilot --version3.2 六维能力对照表ProviderHeadless 调用结构化输出按 id 续接预分配会话细粒度权限模型开关Claude参考-p/--print prompt--output-format json\|stream-json--resume id--session-id uuid--allowedTools/--disallowedTools--modelGemini-p/--prompt-o/--output-format json\|stream-json-r/--resume--session-id uuid--approval-mode default\|auto_edit\|yolo\|plan-m/--modelCodexcodex exec [PROMPT]支持 stdin--jsonJSONL·--output-schema file·-o/--output-last-message filecodex exec resume id--last—-s/--sandbox mode·--dangerously-bypass-approvals-and-sandbox-m/--modelDroiddroid exec [prompt]-o/--output-format json默认text·--input-format stream-json\|stream-jsonrpc-s/--session-id id·--fork id—--auto low\|medium\|high·--skip-permissions-unsafe-m/--model默认claude-opus-4-8OpenCodeopencode run [message]--format default\|json原始 JSON 事件-s/--session id·-c/--continue·--fork—--dangerously-skip-permissions-m/--model provider/modelKilocodekilocode --auto-j/--json需--auto·-i/--json-io双向-s/--session id·-c/--continue最近·-f/--fork shareId—--yolo-mo/--modelCopilot-p/--prompt text仅文本-s/--silent--stream mode--resume [id]·--continue—--allow-tool/--deny-tool/--allow-all--model3.3 探测中发现的关键修正与结论ADR 特意记录了相对 2026-06-14 初稿矩阵的修正这些细节正是未来实现适配器时最容易踩坑的地方Kilocode 支持按 id 续接通过-s/--session id另有-c/--continue只续最近会话、-f/--fork。初稿曾只列出 continue-last。Codex--json输出的是 JSONL最后一条 assistant 消息可用-o/--output-last-message捕获到文件可选的--output-schema能约束最终响应结构。Droid 的-o/--output-format默认是textJSON 必须显式请求多轮/流式输入用--input-format stream-json/stream-jsonrpc。默认模型为claude-opus-4-8。只有 Claude 和 Gemini 提供无竞态的预分配会话 id创建时传--session-id uuid。其他 Provider 都支持续接但只能按已发现的 id续接或 continue-last。Copilot 是降级特例完全没有机器可读输出开关--silent/--stream都是文本因此任何需要解析结构化事件的特性对它都不可用。注意ADR 明确将这份矩阵标注为时间点快照point-in-time snapshot——每个 CLI 的--help都可能在版本之间漂移升级 Provider 时必须重新探测。这是编写文章时也需要向读者强调的可复现性前提。四、功能可移植性Ralph 现有特性在跨 Provider 后的存亡矩阵解决能不能调用的问题本节解决调用之后 Ralph 的现有功能还剩多少。ADR 为每个适配器定义了需要在 capabilities 记录中声明的能力并逐项评估了 Ralph 既有特性的可移植性特性可移植性说明基于RALPH_STATUS文本块的退出检测全部 Provider 通用它是 Agent 输出的文本而非 Provider 的 JSON 字段因此在任何 Provider 上行为完全一致。这是 Ralph 的主要完成信号也是跨 Provider 迁移中风险最低的部分Token 计数 /MAX_TOKENS_PER_HOURProvider 受限仅当事件流携带 usage 信息时可用Claude、Gemini、Codex、Droid 大概率支持OpenCode / Kilocode 待定Copilot 无 → 禁用权限拒绝熔断#101Provider 受限需要机器可读的拒绝事件。Claude、Copilot 有丰富的权限flag但只有部分 CLI 会输出可解析的拒绝事件 → 按 Provider 逐个门控API 限额检测#100 / #183Provider 受限目前依赖 Claude 特有的rate_limit_eventJSON 结构每个 Provider 需要自己的模式否则该特性对其禁用会话连续性通用但有质量分层所有 Provider 都支持 resume只有 Claude 和 Gemini 支持预分配无竞态会话 id其余回退到按发现的 id 续接或 continue-last本节贯穿至后续所有阶段的治理规则是不受支持的特性必须以记录警告日志的方式优雅降级绝不静默误行为并且在用户选择不同AGENT_PROVIDER之前Claude 的行为保持不变。五、仓库源码印证ADR 不是空谈而是对现状的抽象ADR 0001 明确声明本 ADR 不含代码变更但它所描述的现状在仓库中有完整对应实现。理解这些实现才能理解为何Claude 默认行为不变这一不变量是可达成的。5.1claude -p的现状build_claude_command()ralph_loop.sh中的build_claude_command()是 Provider 无关化之后 Claude 适配器要重构的原型。它用全局数组CLAUDE_CMD_ARGS而非字符串拼接来保证 shell 注入安全依次追加可执行文件$CLAUDE_CODE_CMD默认claude对应矩阵中 Claude 的-p无头调用可选--model $CLAUDE_MODEL、--effort $CLAUDE_EFFORTissue #228CLAUDE_OUTPUT_FORMATjson时追加--output-format json对应矩阵结构化输出列CLAUDE_ALLOWED_TOOLS按逗号拆分后逐个作为独立数组元素追加到--allowedTools后repeated-args 格式CLAUDE_USE_CONTINUEtrue且存在 session id 时追加--resume id—— 源码注释明确解释了为何刻意不用--continueissue #151--continue会续接当前目录最近会话可能劫持用户活跃的 Claude Code 会话而--resume 具体 id只续接 Ralph 自己的会话有 loop context 时追加--append-system-prompt loop_context最后读取 prompt 文件内容以-p content传入注释指出 Claude CLI没有--prompt-file这类开关。值得注意的还有RALPH_VERBOSEtrue时的诊断日志issue #154它会打印将要传给 Claude 的 argv——但剔除 prompt 正文可能含敏感信息方便用户核对--allowedTools是否真正到达 Claude例如排查Bash(git *)拒绝问题。5.2 输出解析的现状lib/response_analyzer.shRalph 今天的输出分析位于lib/response_analyzer.sh其中与 ADR 能力矩阵直接对应的关键函数detect_output_format()判断输出是json还是text。它先检查首字符是否为{或[再用jq empty校验。特别地它对超大文件超过RALPH_JSONL_SAFE_MAX_BYTES默认 1 MB做了截断防护issue #250若大文件缺少type:result标记说明是 Claude 被中途 kill 导致的损坏 JSONL 流直接回退到 text 模式避免jq在畸形输入上挂死。这正是 ADR 0002 契约中detect_output_format()也防护截断 JSONL 流的出处。parse_json_response()处理三种 JSON 形态——扁平对象{status, exit_signal, ...}、Claude CLI 嵌套对象{result, sessionId, metadata:{...}}、Claude CLI stream-json 数组[{type:system...}, {type:result, sessionId, is_error...}]取最后一个result元素session id 从init/result元素合并。这三种形态正是 ADR 0002 中每个 Provider 的 normalizer 必须把原生输出折叠进单一分析结构的基线。5.3 路由先例SANDBOX_PROVIDERADR 选用的Provider 无关 配置开关 默认行为不变模式在仓库中已有成熟先例sandbox provider 路由。SANDBOX_PROVIDER值docker/e2b/ 空宿主机执行以相同方式解析环境变量 → CLI 参数 →.ralphrc见 templates/ralphrc.template 中SANDBOX_PROVIDER相关注释与 ralph_loop.sh 中大量case $SANDBOX_PROVIDER/if [[ $SANDBOX_PROVIDER ... ]]分发并由lib/sandbox_docker.sh的get_sandbox_status()等函数按 Provider 提供实现。这份 ADR 的后续实现ADR 0002 的适配器契约明确写道AGENT_PROVIDER的加载与分发将镜像这一已被验证的模式——这是无需引入新机制的关键可行性论据。六、落地路径与后续契约ADR 0002 预告ADR 0001 止步于方向 矩阵明确标注下一步是 ADR0002-agent-adapter-contract.md[P0.2]#311它被[P1.1]抽象接缝 适配器加载器、[P1.2]Claude 参考适配器、[P2.1]后续 Provider所阻塞/依赖。按本 ADR 的编排[P0.1]本 ADR方向裁定 能力矩阵[P0.2]ADR 0002定义适配器契约命令构建接口、输出归一化接口、能力声明 schema、注册约定[P1.1]实现接缝与加载器load_agent_adapter()[P1.2]把build_claude_command()与响应解析逻辑搬进lib/agents/claude.sh默认AGENT_PROVIDERclaude保证现有运行逐字节一致[P2.1]按矩阵逐 PR 接入新 Provider。本文不再展开契约细节但可以提示读者能力矩阵的降级特例如 Copilot 仅文本正是 ADR 0002 中supports_structured_output:false与RALPH_STATUS文本块承担退出检测的直接设计输入而templates/PROMPT.md中定义的---RALPH_STATUS---文本块含STATUS、FILES_MODIFIED、TESTS_STATUS、WORK_TYPE、EXIT_SIGNAL、RECOMMENDATION字段就是那份契约中权威完成信号的事实来源。七、后果评估正面厂商计费/可用性变化变成一次配置翻转而非存在性事件一份稳定、带版本引用的参考矩阵锚定了[P0.2]及全部 Phase 1 实现工作用户获得可选择性——逃离按 token 计费不再必须订阅 Claude TUI切换另一个 Provider 即可。负面 / 成本持续的 per-Provider 维护七款 CLI 的 flag、输出格式、会话模型各异每个--help都可能随版本漂移本 ADR 是时间点快照升级 Provider 需重新探测功能面不统一token / 权限 / API 限额检测必须逐个门控同一个 Ralph 运行在不同 Provider 上行为会不同Copilot 的纯文本输出必然导致一个真正降级的适配器。中性本 ADR不含代码变更只确认方向与矩阵实现从[P0.2]/[P1.1]开始。八、总结ADR 0001 是 Ralph 项目一次典型的用架构决策化解外部风险的记录它把Anthropic 计费政策变化这一外部不确定性通过Provider 能力矩阵 功能可移植性分级 优雅降级原则转化为内部可执行的工程路线图。对读者而言本文的六维能力对照表可以直接作为选择编码 CLI 时的能力参考build_claude_command()、detect_output_format()、parse_json_response()与SANDBOX_PROVIDER路由则是理解抽象接缝落点的第一手源码证据。若要继续深入推荐按顺序阅读下一份契约文档 docs/adr/0002-agent-adapter-contract.md以及其引用的 ralph_loop.shbuild_claude_command、lib/response_analyzer.sh、lib/sandbox_docker.sh 和 templates/PROMPT.md。【免费下载链接】ralph-claude-codeAutonomous AI development loop for Claude Code with intelligent exit detection项目地址: https://gitcode.com/GitHub_Trending/ra/ralph-claude-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考