zerosloney/dsh-ralph-loop

安装

## 这是什么

`dsh-ralph-loop` 是一个 **dsh bundle 包**，导出单个 cordis 插件：

| 能力 | 落点 |
| --- | --- |
| `ctx.ralph` 服务：`execute(task, testCmd, initialFiles)` 一键闭环 | 服务注册（`RalphService`） |
| 五阶段状态机 + 不可变状态快照 + `maxCycles` 硬上限 | 状态引擎（`engine.ts`） |
| `run_ralph_loop` 工具，LLM 可自主触发子图自愈 | `ctx.tools` |
| `ralph/*` 生命周期事件（start / cycle-start / reflect / learn / success / cycle-end / end） | `ctx.emit` 事件总线 |
| 每次执行独立的临时工作目录；测试 shell 通过 Harness Sandbox 约束 | 沙箱适配（`ctx.sandbox.confine` + `ctx.subprocess` + `node:fs`） |

## 设计要点（与设计文档的适配）

- 文档伪代码中的 `ctx.llm.chat(...)` 落地为 harness 原生 `ctx.llm.stream(GenerateOptions)` + 权威 `BlockAssembler`；Handle 的 JSON 生成经 `chatJson` + 容错 `extractJson`（去围栏/平衡括号提取）。
- **LLM 失败显式化**：harness 语义下适配器/路由错误（provider 未注册、限流、网络失败）不抛异常，而是以终止性 finish 块结束流——`chatText` 迭代后检查 `finish.kind`，`error`/`aborted` 转为异常上抛。配错 provider 会立刻报错并触发退避重试，而不是静默返回空串、把 `maxCycles` 个周期空烧完。
- 测试命令先构造当前平台的精确 shell argv，经 `ctx.sandbox.confine(argv, { mode: "workspace-write", workspaceRoot: <本次临时目录> })` 获得受限 argv，再交给 `ctx.subprocess.spawn`（collect 模式、树级终止、abort 超时）。Sandbox 缺失或不可用时 fail-closed，绝不回退到原始命令；插件自身仍使用 `node:fs` 准备/清理临时目录并执行路径守卫。
- **Sandbox 边界**：`ctx.sandbox` 主要约束测试进程的文件效果，不等于网络、凭据或全系统隔离；Windows 或其他后端可能报告 `partial`。`confined.enforcement` 不是 `full`（包括 `partial`）时默认 fail-closed，不执行测试命令，也不裸回退到原始 argv。沙箱运行器在执行命令前失败按 seam 的 `runnerFailureRules`（`allowedExitCodes` 门控 → 去除 `informationalLines` → 大小写不敏感匹配 `fatalSignatures`）识别为环境错误并中止执行，不作为测试失败进入自愈循环。`testCmd` 仍是任意 shell 命令，只应在受控任务和受信任的 Harness profile 中使用。
- 门禁唯一客观判据：退出码 `0`。测试命令超时（`testTimeoutMs`）按退出码 `-1` 走失败循环。
- Plan/Reflect 的提示词同时携带上次执行的 **stdout 与 stderr**（各尾部截断约 4KB——pytest/jest/go test 的失败摘要在 stdout 末尾），失败根因对反思节点完整可见。
- 代码生成 JSON 解析失败不抛错：作为一次失败循环（stderr 记录 `RALPH 方案解析失败`）进入 Reflect/Learn，下一轮自愈。生成结果不含任何 `{path: content}` 形状条目（嵌套值/空对象/非对象顶层）时同样按解析失败处理，不会静默用旧文件空跑一轮；codegen 提示词携带正/反例显式禁止 `{"files": {...}}` 包裹结构与嵌套值，预防这类周期；`maxTokens` 截断在失败原因中显式报告、并在生成文本尾部携带截断标记，与格式错误区分开。
- 超过 `maxCycles` 硬上限自动终止，返回带累积 `lessonsLearned` 的最终快照（`isPassed: false`）。`maxCycles` 在工具 schema 与引擎双重钳制在 1-20，防误调用烧配额。
- 整个闭环有总预算（`totalTimeoutMs`，默认 30 分钟；`execute` 可经 `deadlineMs` 覆盖）：预算通过内部 `AbortSignal` 主动中止正在进行的 `llm.stream` 与测试 subprocess（实际停止仍取决于适配器遵守取消信号），并返回带 `timedOut: true` 的最终快照、正常发出一次 `ralph/end`，防止挂起调用把工具调用钉死。外层 tool caller 自己 abort 时保留调用方原始取消 reason 并直接取消，不发正常 `ralph/end`。
- `autoReflectOnFailure: false` 时失败反思退化为确定性 stderr 片段，零模型调用。

## 安装

把 zerosloney/dsh-ralph-loop 加入你的 DSH 配置（web profile）即可启用。