第十四章：高级配置——打造专属工作流

配置文件全解析

ralph.yml 是 Ralph 的核心配置文件。一个完整的配置文件有以下几个顶级部分：

event_loop:    # 循环控制参数
cli:           # 命令行和后端配置
core:          # 核心运行时参数
hats:          # 帽子角色定义
events:        # 自定义事件元数据
RObot:         # 人机协作配置

下面逐一解析每个部分的关键参数。

event_loop：循环控制

event_loop:
  # 触发循环结束的信号名称（保持默认即可）
  completion_promise: "LOOP_COMPLETE"
  
  # 最大迭代次数
  # 默认 150，复杂项目可以调高，简单任务可以调低
  max_iterations: 150
  
  # 最长运行时间（秒），防止循环永远跑下去
  # 默认 14400（4小时）
  max_runtime_seconds: 14400
  
  # 每隔多少次迭代保存检查点（用于中断恢复）
  checkpoint_interval: 5
  
  # 循环开始时发布的第一个事件
  starting_event: "work.start"
  
  # 必须出现过的事件，才允许 LOOP_COMPLETE（质量保证）
  # 确保完整工作流走完，防止某些帽子被跳过
  required_events: ["review.passed"]
  
  # 提示词文件路径（替代命令行 -p 参数）
  prompt_file: "PROMPT.md"

实际调优建议：

# 快速原型（不需要完整质量保证）
event_loop:
  max_iterations: 20
  required_events: []

# 高质量生产代码
event_loop:
  max_iterations: 200
  max_runtime_seconds: 28800  # 8 小时
  required_events: ["review.passed", "validation.passed"]

cli：后端和提示词配置

cli:
  # AI 后端选择
  # 可选：claude, kiro, gemini, codex, amp, copilot, opencode, pi, custom
  backend: "claude"
  
  # 提示词传递方式
  # "arg"：通过命令行 -p 参数传入
  # "file"：从 prompt_file 指定的文件读取
  prompt_mode: "arg"

切换后端：

# 使用 Kiro（速度更快，支持 AWS Bedrock）
cli:
  backend: "kiro"

# 使用 Gemini
cli:
  backend: "gemini"

core：运行时参数

core:
  # 规格文档目录（设计文档、需求文档放在这里）
  specs_dir: ".agents/scratchpad/"
  
  # 全局守则（注入到所有帽子的上下文里）
  guardrails:
    - "新鲜上下文每次迭代——把学到的东西保存到记忆里供下次使用"
    - "验证是必须的——测试/类型检查/lint 必须通过"
    - "YAGNI 原则——不写需求以外的功能"
    - "KISS 原则——最简单的能工作的方案"

guardrails 是最强大的自定义手段之一。它的内容会出现在每一顶帽子的上下文里，相当于给整个团队的全体成员都贴上了行为准则。

为不同项目定制守则：

# 安全敏感的项目
core:
  guardrails:
    - "任何用户输入都必须经过严格验证，防止注入攻击"
    - "敏感信息（密码、密钥）绝不能出现在日志里"
    - "所有 SQL 操作必须使用参数化查询"

# 面向初学者的教学代码
core:
  guardrails:
    - "代码必须有详细中文注释，面向初学者"
    - "避免复杂的设计模式，用最直接的实现"
    - "每个函数不超过 20 行"

背压验证：通过帽子指令实现

已在第八章详细介绍。背压验证不是通过 ralph.yml 里的 backpressure: 配置节来实现——这个配置节并不存在。正确的方式是在帽子的 instructions 里声明验证要求，AI 自己负责运行验证并附上证据：

hats:
  builder:
    name: "⚙️ Builder"
    triggers: ["tasks.ready"]
    publishes: ["review.ready"]
    instructions: |
      实现分配的任务。

      ## 背压要求
      在发出 review.ready 之前，你必须已完成：
      - tests: 运行 python -m pytest，全部通过
      - lint:  运行 flake8 .，0 个错误
      
      把实际输出结果附在事件载荷里。
      不要仅声称"测试通过"，要运行并提供输出摘要。

core.guardrails 可以用来把验证要求全局化，让它出现在所有帽子的上下文里：

core:
  guardrails:
    - "发出任何完成事件前，必须运行 pytest 并确认全部通过"
    - "不要声称测试通过——要实际运行，并把输出附在事件载荷里"

hats：自定义帽子

除了使用预设帽子，你可以添加专属帽子来满足特定需求：

示例：添加文档生成帽子

hats:
  # 在所有代码任务完成后，自动生成文档
  doc_writer:
    name: "📚 文档写手"
    triggers: ["LOOP_COMPLETE"]    # 在循环快结束时触发
    publishes: ["docs.complete"]
    instructions: |
      你是文档写手。检查本次实现的所有代码，
      更新 README.md，确保包含：
      1. 新增功能的使用说明
      2. API 变更说明
      3. 安装/运行命令（如有变化）
      
      文档语言：中文
      风格：简洁，面向技术用户

示例：添加安全审计帽子

hats:
  security_auditor:
    name: "🔒 安全审计"
    triggers: ["review.passed"]
    publishes: ["security.approved", "security.rejected"]
    default_publishes: "security.approved"
    instructions: |
      你是安全审计者。检查最近提交的代码是否有安全漏洞：
      
      必查项：
      - SQL 注入风险（确认所有 DB 查询使用参数化）
      - 命令注入风险（确认所有 shell 调用已转义）
      - 敏感信息泄露（确认没有 API key 硬编码）
      - 不安全的反序列化
      
      只有所有必查项通过，才发布 security.approved。
      否则发布 security.rejected 并说明具体问题。

配置继承：基础配置 + 项目配置

对于有多个项目的用户，可以建立一套"基础配置"，然后在各项目里继承和覆盖：

创建全局基础配置 ~/.ralph/base.yml：

# 个人通用设置
event_loop:
  max_iterations: 150
  max_runtime_seconds: 14400

cli:
  backend: claude

core:
  guardrails:
    - "代码注释用中文"
    - "发出完成事件前，必须运行测试并确认通过"

然后在项目的 ralph.yml 里只写差异：

# 继承基础配置
extends: "~/.ralph/base.yml"

# 覆盖项目特定设置
cli:
  backend: kiro  # 这个项目用 Kiro

hats:
  builder:
    name: "⚙️ Builder"
    triggers: ["tasks.ready"]
    publishes: ["review.ready"]
    instructions: |
      实现任务。发出 review.ready 前必须通过：
      - python -m pytest（全部通过）
      - mypy src/（0 个错误）
      把实际输出附在载荷里。

使用多个预设

你可以为不同场景准备多个预设文件：

项目根目录/
├── ralph.yml                    # 默认配置（日常开发用）
├── presets/
│   ├── quick-fix.yml            # 快速修复（减少迭代，不要求完整测试）
│   ├── full-feature.yml         # 完整功能开发（最严格）
│   ├── code-review.yml          # 代码审查
│   └── research.yml             # 研究调查

使用时：

# 日常开发
ralph run -p "添加搜索功能"

# 快速修复一个小 bug
ralph run -H presets/quick-fix.yml -p "修复登录按钮不响应的问题"

# 完整功能，要求最高质量
ralph run -H presets/full-feature.yml -p "实现支付功能"

常用配置速查

以下是一些常用的配置模式：

极简快速循环（原型阶段）

event_loop:
  max_iterations: 10
  required_events: []

hats:
  # 只用构建者，不用审查者和终结者
  builder:
    name: "⚙️ 快速构建者"
    triggers: ["work.start"]
    publishes: ["LOOP_COMPLETE"]
    instructions: |
      快速实现请求的功能，不需要完整的测试覆盖，
      确保代码能运行即可。

严格质量配置（生产代码）

event_loop:
  max_iterations: 200
  required_events: ["review.passed", "validation.passed"]

core:
  guardrails:
    - "测试覆盖率必须 > 80%"
    - "所有公共 API 必须有类型注解"
    - "没有 TODO 注释留在代码里"

hats:
  builder:
    name: "⚙️ Builder"
    triggers: ["tasks.ready"]
    publishes: ["review.ready"]
    instructions: |
      实现任务。发出 review.ready 前必须通过：
      - pytest --cov=src --cov-fail-under=80
      - mypy src/ --strict
      - black --check . && isort --check-only .
      - 确认没有 TODO/FIXME 残留：grep -rn 'TODO\|FIXME' src/ 应为空
      把实际输出附在载荷里。

本章小结

• event_loop 控制迭代次数、超时和必须经历的事件
• cli 配置 AI 后端和提示词传递方式
• core.guardrails 是全局行为准则，对所有帽子生效
• 背压验证通过帽子的 instructions 实现，而非独立配置节
• 自定义帽子让 Ralph 适应任何工作流
• 建议为不同场景（快速原型、生产质量）维护不同的预设文件

下一章，我们展望 AI 自动化时代的工作新范式，以及 Ralph 在其中扮演的角色。