ralph-status

Ralph 状态报告

概述

Ralph 状态块是一份结构化、可由机器解析的进度报告，会在每次自主循环迭代结束时生成。它支持自动化监控、退出检测和进度跟踪。格式固定，必须严格遵守——机器解析依赖一致的结构。

开始时宣布：“本次迭代将生成 RALPH_STATUS 块。”

触发条件

• 每次自主循环迭代结束时（必须）
• 自主循环中的 BUILD 阶段完成后
• 监控系统需要进度数据时
• 需要评估退出门槛时
• autonomous-loop 技能调用此技能时

---

阶段 1：数据收集

目标： 收集状态块所需的所有指标。

1. 统计本次迭代完成的任务数
2. 统计修改的文件数（新建、编辑、删除）
3. 运行测试套件并记录结果
4. 确定主要工作类型
5. 检查是否存在阻碍因素或问题

指标收集表

指标	确定方法	示例
TASKS_COMPLETED_THIS_LOOP	统计本次迭代中标记为已完成的任务	1
FILES_MODIFIED	通过 git diff 或跟踪记录统计变更文件数	3
TESTS_STATUS	运行测试套件并记录总体结果	PASSING
WORK_TYPE	对主要活动进行分类	IMPLEMENTATION
阻碍因素	检查是否有任务无法继续	无

工作类型分类

工作类型	适用情况
IMPLEMENTATION	编写了新代码（功能、端点、服务）
TESTING	主要活动是编写或修复测试
DOCUMENTATION	主要活动是编写文档、规格说明或注释
REFACTORING	主要活动是在不改变行为的前提下重构

停止——在进入阶段 2 之前，不要继续：

• 已收集所有指标
• 已运行测试套件（不得假定测试已通过）
• 已确定工作类型

---

阶段 2：STATUS 评估

目标： 根据迭代结果确定正确的 STATUS 值。

STATUS 决策表

条件	STATUS 值	EXIT_SIGNAL
仍有任务，本次迭代完成了工作	IN_PROGRESS	false
仍有任务，本次迭代未完成工作（仅调查）	IN_PROGRESS	false
无法继续，需要外部输入	BLOCKED	false
所有任务已完成，所有测试通过	COMPLETE	评估阶段 3
所有任务已完成，但测试失败	IN_PROGRESS	false

STATUS 值定义

值	含义	循环操作
IN_PROGRESS	工作仍在进行，尚有任务或测试失败	继续循环
COMPLETE	所有计划工作均已完成，测试通过	评估退出门槛
BLOCKED	没有外部输入就无法继续	停止并报告

状态为 BLOCKED 时

1. 在 RECOMMENDATION 中清楚说明阻碍进展的因素
2. 设置 EXIT_SIGNAL: false（受阻不代表已完成）
3. 如果受阻状态持续多个迭代，熔断器可能会触发

停止——在进入阶段 3 之前，不要继续：

• 已确定 STATUS 值
• 如果状态为 BLOCKED，已清楚说明阻碍因素

---

阶段 3：EXIT_SIGNAL 评估

目标： 确定 EXIT_SIGNAL 应为 true 还是 false。

只有在同时满足以下所有条件时，EXIT_SIGNAL 才能设为 `true`：

条件	验证方法	必需
没有剩余任务	IMPLEMENTATION_PLAN.md 中没有未勾选的条目	是
所有测试通过	TESTS_STATUS 为 PASSING	是
最近一次迭代没有错误	执行过程干净，没有未解决的异常	是
没有有意义的工作剩余	没有 TODO、未完成的功能，且已完成代码审查	是

EXIT_SIGNAL 决策表

剩余任务	测试状态	错误	有意义的工作	EXIT_SIGNAL
是	任意	任意	任意	false
否	失败	任意	任意	false
否	通过	是	任意	false
否	通过	否	是	false
否	通过	否	否	true

双重条件退出门槛

循环编排器使用两个独立信号来确认退出：

1. 启发式检测： 最近的输出中，出现表示已完成的措辞（“全部完成”“一切通过”“没有剩余工作”）>= 2 次
2. 明确声明： 状态块中包含 EXIT_SIGNAL: true

两者必须同时为真。这样可以防止：

• 因随口提到完成而产生误报
• Claude 说“完成了”，但仍在有效地开展工作时提前退出

停止——除非已验证全部四项条件，否则不要将 EXIT_SIGNAL 设为 true。

---

阶段 4：阻止产出

目标： 按照精确格式编写 RALPH_STATUS 块。

每次循环迭代都必须以此精确格式结束。不得有任何变体。不得添加额外字段。不得缺少字段。

必需格式

---RALPH_STATUS---
STATUS: [IN_PROGRESS | COMPLETE | BLOCKED]
TASKS_COMPLETED_THIS_LOOP: [number]
FILES_MODIFIED: [number]
TESTS_STATUS: [PASSING | FAILING | NOT_RUN]
WORK_TYPE: [IMPLEMENTATION | TESTING | DOCUMENTATION | REFACTORING]
EXIT_SIGNAL: [false | true]
RECOMMENDATION: [one-line summary of next action or completion state]
---END_RALPH_STATUS---

字段规范

字段	类型	允许的值	描述
STATUS	枚举	IN_PROGRESS, COMPLETE, BLOCKED	当前迭代结果
TASKS_COMPLETED_THIS_LOOP	整数	0+	此次迭代完成的任务数
FILES_MODIFIED	整数	0+	更改的文件数（新建、编辑、删除）
TESTS_STATUS	枚举	PASSING, FAILING, NOT_RUN	此次迭代后测试套件的状态
WORK_TYPE	枚举	IMPLEMENTATION, TESTING, DOCUMENTATION, REFACTORING	主要活动类别
EXIT_SIGNAL	布尔值	false, true	是否已完成所有工作
RECOMMENDATION	字符串	自由文本（仅一行）	下一步操作或最终总结

RECOMMENDATION 指南

STATUS	RECOMMENDATION 内容
IN_PROGRESS	“下一步：[具体的下一项任务]”
COMPLETE	“所有任务均已完成，测试通过，[总结]”
BLOCKED	“受阻：[具体的阻塞原因]”

---

阶段 5：验证

目标： 在输出前确认状态块正确无误。

验证检查

检查项	规则	违反时的处理
格式精确	与模板逐字符匹配（值除外）	重写状态块
STATUS 一致性	COMPLETE 时必须评估 EXIT_SIGNAL	修正 STATUS 或 EXIT_SIGNAL
TESTS_STATUS 符合实际情况	值与实际测试运行结果一致	重新运行测试
EXIT_SIGNAL 有依据	仅在满足全部 4 项条件时设为 true	设为 false
存在 RECOMMENDATION	非空，且仅一行	添加建议
没有额外字段	仅包含定义的 7 个字段	删除多余字段

---

反模式／常见错误

反模式	失败原因	正确做法
省略状态块	循环无法评估是否退出，监控将失效	每次迭代都以状态块结束
测试失败时将 EXIT_SIGNAL 设为 true	提前退出，代码存在缺陷	验证全部 4 项条件
添加自定义字段	机器解析会失败	仅使用定义的 7 个字段
RECOMMENDATION 跨多行	换行会导致解析失败	仅用一行
未运行测试就填写 TESTS_STATUS	造成虚假信心	实际运行测试套件
仍有任务时将 STATUS 设为 COMPLETE	信号相互矛盾	检查 IMPLEMENTATION_PLAN.md
跳过 RECOMMENDATION	没有给下一次迭代提供指引	始终提供可执行的建议
BLOCKED 时将 EXIT_SIGNAL 设为 true	相互矛盾——受阻不等于完成	BLOCKED 时 EXIT_SIGNAL 始终为 false
更改分隔符格式	机器解析依赖精确的分隔符	必须使用 ---RALPH_STATUS---
猜测 FILES_MODIFIED	指标不准确	统计实际更改

---

防止自我合理化

切勿跳过状态块。除非已验证全部四项条件，否则切勿将 EXIT_SIGNAL 设为 true。切勿修改状态块格式。机器解析依赖精确、一致的结构。

如果你发现自己在想：

• “状态块只是额外负担……”——它是退出门控机制。绝不可跳过。
• “一切都完成了，EXIT_SIGNAL: true……”——先验证全部四项条件。
• “我会添加一个额外字段，提供更多详情……”——不行。详情请使用 RECOMMENDATION。
• “测试应该通过了，TESTS_STATUS: PASSING……”——运行测试。进行验证。然后再报告。

---

集成点

技能	关系	时间
autonomous-loop	上级 — 在每次迭代结束时调用此技能	每次迭代
circuit-breaker	使用方 — 监控停滞模式	读取状态块
verification-before-completion	上游 — 提供测试结果	生成状态块之前
监控仪表板	使用方 — 显示实时进度	读取状态块
日志聚合	使用方 — 分析历史性能	存储状态块

---

具体示例

示例：典型的 IN_PROGRESS 状态

---RALPH_STATUS---
STATUS: IN_PROGRESS
TASKS_COMPLETED_THIS_LOOP: 1
FILES_MODIFIED: 3
TESTS_STATUS: PASSING
WORK_TYPE: IMPLEMENTATION
EXIT_SIGNAL: false
RECOMMENDATION: Next: implement user authentication middleware
---END_RALPH_STATUS---

示例：完成状态

---RALPH_STATUS---
STATUS: COMPLETE
TASKS_COMPLETED_THIS_LOOP: 1
FILES_MODIFIED: 2
TESTS_STATUS: PASSING
WORK_TYPE: DOCUMENTATION
EXIT_SIGNAL: true
RECOMMENDATION: All tasks complete, tests passing, documentation updated
---END_RALPH_STATUS---

示例：受阻状态

---RALPH_STATUS---
STATUS: BLOCKED
TASKS_COMPLETED_THIS_LOOP: 0
FILES_MODIFIED: 0
TESTS_STATUS: PASSING
WORK_TYPE: IMPLEMENTATION
EXIT_SIGNAL: false
RECOMMENDATION: Blocked: need database credentials for integration test setup
---END_RALPH_STATUS---

示例：测试失败状态

---RALPH_STATUS---
STATUS: IN_PROGRESS
TASKS_COMPLETED_THIS_LOOP: 1
FILES_MODIFIED: 4
TESTS_STATUS: FAILING
WORK_TYPE: TESTING
EXIT_SIGNAL: false
RECOMMENDATION: 3 tests failing in auth module — investigating root cause next iteration
---END_RALPH_STATUS---

---

流程摘要

1. 完成本次迭代的工作（实现、测试、文档或重构）
2. 统计已完成的任务和已修改的文件
3. 运行测试套件并记录结果
4. 评估 STATUS 值
5. 评估 EXIT_SIGNAL 条件（只有全部 4 项均为 true 时，才可设为 true）
6. 按照精确格式编写 RALPH_STATUS 块
7. 提供清晰、可执行的 RECOMMENDATION

---

技能类型

RIGID — 必须严格遵循状态块格式。机器解析依赖一致的结构。不得添加字段、修改格式或跳过状态块。