全新上下文循环 cperion/ralphi

ralphi

ralph —— 一个可恢复的全新上下文循环，两套 harness 共用。一个参数背后是两套协议：

| kind | 目标 | 轮次 | 最终审计 |
| build（默认） | 在仓库里做出真实改动 | 一个工作单元，验证并提交 | 独立验证器针对目标运行项目检查 |
| design | 找出最简单的目标架构 | 一次设计调查 | 独立可实施性审计 |

一次调用会在项目仓库内创建（或恢复）docs/ralph/<slug>/，每轮用全新智能体跑 N 轮，然后执行审计。状态随代码一起提交；STATE.json 在中断后仍能保留。

无需手动设置：不用复制模板，不用创建文件。

用法

ralph({ goal: "Add cursor pagination to GET /items, tests included", rounds: 8 })

ralph({ kind: "design", goal: "Design the module structure and data types for X", rounds: 16 })

| 参数 | 含义 |
| goal | 目标。build 模式下：完成时必须成立的条件。design 模式下：问题、行为、约束、非目标。 |
| kind | build（默认）或 design。 |
| constraints | 仅限硬约束：边界、兼容性、运行时、不变量。 |
| paths | 工作或设计必须考虑的现有文件/目录。 |
| rounds | 本次调用要跑的轮数。默认 24，上限 64；后续调用可追加。build 模式在目标验证通过后提前停止，所以这是上限，不是配额。 |
| name | 稳定的目录名。复用即恢复该次运行。 |
| project | 拥有 docs/ralph/ 的仓库根目录。默认取包含工作区的 git 根目录，否则取工作区。 |
| answer | 用户对上一次 needs-input 运行所提问题的回答。其他情况省略。 |

长时间运行：调用会阻塞当前回合。取消会保留每个已完成的轮次；用相同的 name 和 goal 再次调用即可继续。build 模式下，某轮报告 done 会立即触发独立验证器：接受目标则提前停止，拒绝则把具体缺口喂给下一轮。剩余轮次绝不会浪费在无谓的忙碌上。

创建的内容

位于项目仓库内，因此记录随代码一起版本化，并由 worker 提交：

docs/ralph/<slug>/
STATE.json controller-owned resume marker (next / in-progress round)
rounds.jsonl per-round reports (controller-owned)
runs.jsonl one record per call (controller-owned)
AUDIT.json independent verification result
ANSWERS.md controller-owned trail of user questions and answers
rounds/ per-round report files (pi port)
LOG.md append-only per-round record

kind=design 额外创建：

CONTRACT.md goal + constraints + paths
ARCHITECTURE.md best-known design; changes need evidence
QUESTIONS.md material open questions
experiments/ prototypes, benchmarks, re-derivations

kind=build 额外创建：
GOAL.md 目标 + 约束 + 路径 PLAN.md 当前方案，已完成 / 下一步 NOTES.md 长期有效的发现、命令、选定的解释 work/ 临时文件

一轮做什么

build：读 GOAL.md、PLAN.md、NOTES.md、LOG.md，检查仓库和 git 状态；从上一份报告的 next 接着做；从 PLAN.md 里挑价值最高的一步；实现它，只要还能安全推进就继续做（不是只做第一处小改动）；跑项目的检查并修复问题；提交；更新那三个文件；报告 {action, summary, evidence, next, blocked, ask}。一轮结束时，仓库必须可衡量地更接近目标：不要求一轮做完整个目标，敷衍的工作会被打回。审计是一个全新的验证者，自己跑检查，返回 {satisfied, evidence, gaps} —— 它不相信日志。

design：读那四个设计文件；写三个候选问题，按重要性排序，追最重要的那个，直到用证据回答它（如果第一个问题不重要，就去追下一个，而不是结束这一轮）；选 continue、simplify、experiment 或 rederive（只定契约，先独立设计）；更新文件，提交，报告 {mode, question, evidence, decision, next, ask}。审计会尝试实现契约，并报告它第一次不得不自行发明语义的地方。

用户提问

一轮没有直接联系用户的通道，但也不必靠猜。当某个归用户拍板的决定会改变工作方向时，这一轮设置 ask，而不是自己编一个需求，也不是宣称自己 blocked：

- 控制器通过宿主的问题服务把问题转给用户，此时 ralph 调用仍然开着；
- 答案写进 ANSWERS.md 和 STATE.json，下一轮以 userAnswer 收到，必须先应用它；
- 如果转达跑不起来（没有应答者，或者 ralph 是在子代理里启动的），调用以状态 needs-input 结束，问题放在结果里。调用方去问用户，然后用同一个 name 和 goal 加上 answer 重新调用 ralph。

推进纪律

这一轮的提示词就是防止偷懒小步走的控制面。每一轮：

- 从上一份报告的 next 开始，不重做 LOG.md 或 NOTES.md 里已经记录过的探索；
- 只要还能安全推进就继续做，而不是停在第一处改动，或者停在一个现在就能执行的下一步；
- 把「blocked」只当作外部且具体的情况（缺凭证、服务不可用），绝不当作「这需要不止一轮」，也绝不当作归用户拍板的决定 —— 那些走 ask；
- 把 next 写成自包含的续接契约：哪个文件、哪处改动、哪条命令、哪个结果能证明它。

提前完成

build 模式在目标达成后不得继续工作。一轮 build 会设置只有跑完检查、并认为验收标准已满足时，才写 done: true。之后控制器会：

1. 立刻运行独立验证器（不等轮次预算）；
2. 验证器认可时，以 complete 停止，并输出一行提前停止说明；
3. 否则把验证器给出的具体缺口作为反馈传入下一轮，让这一轮去修真正的缺口，而不是靠猜；
4. 连续两次验证都以相同缺口否决目标时，以 blocked 停止——这种分歧循环自己解决不了。

design 模式保留完整搜索预算：它是一次探索，不是完成条件，只在调用结束时按审计结果停止。

恢复

每轮前后都会原子写入 STATE.json。如果 harness 或机器在调用中途停止，用相同的 name、kind 和 goal 再调一次：

- 已完成的轮次绝不重跑；
- 报告已写好的轮次直接读取，不重跑（pi）；
- 中途被打断的轮次按原编号重试；
- 向用户提问过的轮次，从下一轮带着答案继续——无论答案是实时转达的，还是在 needs-input 结果之后以 answer 提供的；
- 恢复的粒度是「被打断的那一轮」，不是整段对话；
- 同名但 goal 或 kind 不同会被拒绝，不会混在一起。

审查一次运行

git log --oneline -- docs/ralph/<slug>
git diff <start>.. -- docs/ralph/<slug>/

kind=build：先读 AUDIT.json——satisfied=false 表示目标没达成，gaps 说明缺什么。kind=design：AUDIT.json 里 material=true 表示设计仍有可实施性缺口。

安装 / 更新

两个 harness 注册的是同一个工具名，ralph。

DSH

在 DSH 配置档里以 bundle @local/dsh-plugin-arch-loop 安装（包名是历史遗留，现在提供的是 ralph）。用 plugin_manager / install_bundle 指向本仓库安装，然后重启 DSH。

工具可以注册在 host 作用域（每个智能体都能用）、预设内部，或两者都注册。如果同一预设里自带的 tool-ralph 行是启用的，请禁用它：作用域内的内置 ralph 会遮住这个。

需要 DSH 0.2.1-rc.2 或更新版本：一次性子进程通过 ctx.subagents.startActivation({ delivery: "caller" }) 启动。在 0.2.0-rc.2 上工具能加载，但第一次调用会失败，因为那个版本暴露的是 ctx.subagents.start()。插件只导入 Node 内置模块，所以没有 peer dependency 来强制这条要求——升级后用 dsh --version 检查。

改完 plugin.js 或任一补丁后，重启 DSH：运行中的进程只导入一次模块代。

cordis.patch.yml 里的配置：

| 字段 | 默认值 | 含义 |
| provider | spawn | 新子代理服务商；必须支持结构化输出。 |
| maxRounds | 64 | 每次调用的上限。 |
| defaultRounds | 24 | 省略 rounds 时使用。 |

pi

扩展位于 pi/。安装：

pi install ./pi

每一轮都会启动一个新的 pi 子进程，只带内置工具（read,write,edit,bash,grep,find,ls），在项目根目录下运行，继承父级的模型和思考等级。子进程写出 rounds/rNNN.json，由工具校验。改完代码后执行 /reload。

有意保留的限制

- 轮次是恢复的粒度：子进程在一轮中途挂掉就重试，不会接着对话中途继续。
- rederive 的盲区（设计如此）靠流程约束，不做强制。
- 目前没有单轮的实际耗时超时；控制手段是中断再恢复。
- 只有一个审计器/校验器，不是对抗式评审团。
- 完成与否取决于单次调用的预算加上审计结论；重启后不会自动续跑——用同样的名字和目标重新调用。
- 问题转交要求调用方正是当前存活的根智能体。在另一个智能体内部启动的 ralph 会以 needs-input 结束，而不是一直阻塞。
- pi 移植版不转交用户问题；pi 的一轮只能靠猜，或者报告 blocked。