helloloop 0.3.1 → 0.7.0

package/src/prompt.mjs

@@ -2,6 +2,7 @@ import { formatList } from "./common.mjs";
 import {
   hasCustomProjectConstraints,
   listMandatoryGuardrails,
+  listMandatoryEngineeringPrinciples,
   resolveProjectConstraints,
 } from "./guardrails.mjs";
 
@@ -69,6 +70,7 @@ export function buildTaskPrompt({
     ...(task.docs || []),
   ]);
   const mandatoryGuardrails = listMandatoryGuardrails();
+  const mandatoryEngineeringPrinciples = listMandatoryEngineeringPrinciples();
   const effectiveConstraints = resolveProjectConstraints(constraints);
   const usingFallbackConstraints = !hasCustomProjectConstraints(constraints);
 
@@ -93,6 +95,7 @@ export function buildTaskPrompt({
     listSection("涉及路径", task.paths || []),
     listSection("验收条件", task.acceptance || []),
     listSection("内建安全底线", mandatoryGuardrails),
+    listSection("强制编码与产出基线", mandatoryEngineeringPrinciples),
     listSection(usingFallbackConstraints ? "默认工程约束（文档未明确时生效）" : "项目/用户约束", effectiveConstraints),
     repoStateText ? section("仓库当前状态", repoStateText) : "",
     failureHistory.length
@@ -104,11 +107,12 @@ export function buildTaskPrompt({
     listSection("完成前必须运行的验证", verifyCommands),
     section("交付要求", [
       "1. 直接在仓库中完成实现。",
-      "2. 运行验证；若失败，先分析根因，再修复并重跑。",
-      "3. 同一路径连续失败后，必须明确换一种实现或排查思路。",
-      "4. 除非遇到外部权限、环境损坏、文档缺口等硬阻塞，否则不要停止。",
-      "5. 用简洁中文总结变更、验证结果和剩余风险。",
-      "6. 不要提问，不要等待确认，直接完成。",
+      "2. 用户需求明确且当前任务可完成时，必须一次性做完本轮应交付的全部工作，不要做半成品后停下来问“是否继续”或“如果你要我可以继续”。",
+      "3. 运行验证；若失败，先分析根因，再修复并重跑。",
+      "4. 同一路径连续失败后，必须明确换一种实现或排查思路。",
+      "5. 除非遇到外部权限、环境损坏、文档缺口等硬阻塞，或确实需要用户做关键决策，否则不要停止。",
+      "6. 不要提问，不要等待确认，不要把“下一步建议”当成提前停下的理由，直接完成当前任务。",
+      "7. 最终只用简洁中文总结必要的变更、验证结果和剩余风险；禁止使用“如果你要”“如果你需要进一步…”“希望这对你有帮助”等套话收尾。",
     ].join("\n")),
   ].filter(Boolean).join("\n");
 }

package/src/prompt_session.mjs

@@ -0,0 +1,40 @@
+import fs from "node:fs";
+import { createInterface } from "node:readline/promises";
+
+let bufferedAnswers = null;
+let bufferedAnswerIndex = 0;
+
+function loadBufferedAnswers() {
+  if (!bufferedAnswers) {
+    bufferedAnswers = fs.readFileSync(0, "utf8").split(/\r?\n/);
+  }
+  return bufferedAnswers;
+}
+
+export function createPromptSession() {
+  if (process.stdin.isTTY) {
+    const readline = createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+    return {
+      async question(promptText) {
+        return readline.question(promptText);
+      },
+      close() {
+        readline.close();
+      },
+    };
+  }
+
+  return {
+    async question(promptText) {
+      process.stdout.write(promptText);
+      const answers = loadBufferedAnswers();
+      const answer = answers[bufferedAnswerIndex] ?? "";
+      bufferedAnswerIndex += 1;
+      return answer;
+    },
+    close() {},
+  };
+}

package/src/runner.mjs

@@ -1,341 +1,3 @@
-import path from "node:path";
-
-import {
-  ensureDir,
-  nowIso,
-  sanitizeId,
-  tailText,
-  timestampForFile,
-  writeText,
-} from "./common.mjs";
-import {
-  loadBacklog,
-  loadPolicy,
-  loadProjectConfig,
-  loadRepoStateText,
-  loadVerifyCommands,
-  saveBacklog,
-  writeStateMarkdown,
-  writeStatus,
-} from "./config.mjs";
-import {
-  getTask,
-  renderTaskSummary,
-  selectNextTask,
-  summarizeBacklog,
-  unresolvedDependencies,
-  updateTask,
-} from "./backlog.mjs";
-import { buildTaskPrompt } from "./prompt.mjs";
-import { runCodexExec, runVerifyCommands } from "./process.mjs";
-
-function makeRunDir(context, taskId) {
-  return path.join(context.runsDir, `${timestampForFile()}-${sanitizeId(taskId)}`);
-}
-
-function makeAttemptDir(runDir, strategyIndex, attemptIndex) {
-  return path.join(
-    runDir,
-    `strategy-${String(strategyIndex).padStart(2, "0")}-attempt-${String(attemptIndex).padStart(2, "0")}`,
-  );
-}
-
-function isHardStopFailure(kind, summary) {
-  const normalized = String(summary || "").toLowerCase();
-  if (!normalized) {
-    return false;
-  }
-
-  if (kind === "codex" && normalized.includes("enoent")) {
-    return true;
-  }
-
-  return [
-    "command not found",
-    "is not recognized",
-    "无法将",
-    "找不到路径",
-    "no such file or directory",
-    "permission denied",
-    "access is denied",
-  ].some((signal) => normalized.includes(signal));
-}
-
-function buildExhaustedSummary({
-  failureHistory,
-  maxStrategies,
-  maxAttemptsPerStrategy,
-}) {
-  const lastFailure = failureHistory.at(-1)?.summary || "未知失败。";
-  return [
-    `已按 Ralph Loop 执行 ${maxStrategies} 轮策略、每轮最多 ${maxAttemptsPerStrategy} 次重试，当前任务仍未收敛。`,
-    "",
-    "最后一次失败信息：",
-    lastFailure,
-  ].join("\n").trim();
-}
-
-function renderStatusMarkdown(context, { summary, currentTask, lastResult, nextTask }) {
-  return [
-    "## 当前状态",
-    `- backlog 文件：${context.backlogFile.replaceAll("\\", "/")}`,
-    `- 总任务数：${summary.total}`,
-    `- 已完成：${summary.done}`,
-    `- 待处理：${summary.pending}`,
-    `- 进行中：${summary.inProgress}`,
-    `- 失败：${summary.failed}`,
-    `- 阻塞：${summary.blocked}`,
-    `- 当前任务：${currentTask ? currentTask.title : "无"}`,
-    `- 最近结果：${lastResult || "暂无"}`,
-    `- 下一建议：${nextTask ? nextTask.title : "暂无可执行任务"}`,
-  ].join("\n");
-}
-
-function resolveTask(backlog, options) {
-  if (options.taskId) {
-    const task = getTask(backlog, options.taskId);
-    if (!task) throw new Error(`未找到任务：${options.taskId}`);
-    return task;
-  }
-  return selectNextTask(backlog, options);
-}
-
-function buildFailureSummary(kind, payload) {
-  if (kind === "codex") {
-    return [
-      `Codex 执行失败，退出码：${payload.code}`,
-      "",
-      "stdout 尾部：",
-      tailText(payload.stdout, 60),
-      "",
-      "stderr 尾部：",
-      tailText(payload.stderr, 60),
-    ].join("\n").trim();
-  }
-  return payload.summary;
-}
-
-async function executeSingleTask(context, options = {}) {
-  const policy = loadPolicy(context);
-  const projectConfig = loadProjectConfig(context);
-  const backlog = loadBacklog(context);
-  const repoStateText = loadRepoStateText(context);
-  const task = resolveTask(backlog, options);
-
-  if (!task) {
-    const summary = summarizeBacklog(backlog);
-    writeStatus(context, { ok: true, stage: "idle", summary });
-    writeStateMarkdown(context, renderStatusMarkdown(context, {
-      summary,
-      currentTask: null,
-      lastResult: "没有可执行任务",
-      nextTask: null,
-    }));
-    return { ok: true, kind: "idle", task: null };
-  }
-
-  const unresolved = unresolvedDependencies(backlog, task);
-  if (unresolved.length) {
-    throw new Error(`任务 ${task.id} 仍有未完成依赖：${unresolved.join(", ")}`);
-  }
-
-  const verifyCommands = Array.isArray(task.verify) && task.verify.length
-    ? task.verify
-    : loadVerifyCommands(context);
-  const runDir = makeRunDir(context, task.id);
-  const requiredDocs = [
-    ...(projectConfig.requiredDocs || []),
-    ...(options.requiredDocs || []),
-  ];
-  const constraints = [
-    ...(projectConfig.constraints || []),
-    ...(options.constraints || []),
-  ];
-  const maxAttemptsPerStrategy = Math.max(1, Number(options.maxAttempts || policy.maxTaskAttempts || 1));
-  const configuredStrategies = Math.max(1, Number(options.maxStrategies || policy.maxTaskStrategies || 1));
-  const maxStrategies = policy.stopOnFailure ? 1 : configuredStrategies;
-
-  if (options.dryRun) {
-    const prompt = buildTaskPrompt({
-      task,
-      repoStateText,
-      verifyCommands,
-      requiredDocs,
-      constraints,
-      strategyIndex: 1,
-      maxStrategies,
-      attemptIndex: 1,
-      maxAttemptsPerStrategy,
-    });
-    ensureDir(runDir);
-    writeText(path.join(runDir, "codex-prompt.md"), prompt);
-    return { ok: true, kind: "dry-run", task, runDir, prompt, verifyCommands };
-  }
-
-  updateTask(backlog, task.id, { status: "in_progress", startedAt: nowIso() });
-  saveBacklog(context, backlog);
-
-  let previousFailure = "";
-  const failureHistory = [];
-
-  for (let strategyIndex = 1; strategyIndex <= maxStrategies; strategyIndex += 1) {
-    for (let attemptIndex = 1; attemptIndex <= maxAttemptsPerStrategy; attemptIndex += 1) {
-      const prompt = buildTaskPrompt({
-        task,
-        repoStateText,
-        verifyCommands,
-        requiredDocs,
-        constraints,
-        previousFailure,
-        failureHistory,
-        strategyIndex,
-        maxStrategies,
-        attemptIndex,
-        maxAttemptsPerStrategy,
-      });
-      const attemptDir = makeAttemptDir(runDir, strategyIndex, attemptIndex);
-      const codexResult = await runCodexExec({ context, prompt, runDir: attemptDir, policy });
-
-      if (!codexResult.ok) {
-        previousFailure = buildFailureSummary("codex", codexResult);
-        failureHistory.push({
-          strategyIndex,
-          attemptIndex,
-          kind: "codex",
-          summary: previousFailure,
-        });
-        if (isHardStopFailure("codex", previousFailure)) {
-          updateTask(backlog, task.id, {
-            status: "failed",
-            finishedAt: nowIso(),
-            lastFailure: previousFailure,
-            attempts: failureHistory.length,
-          });
-          saveBacklog(context, backlog);
-          return { ok: false, kind: "codex-failed", task, runDir, summary: previousFailure };
-        }
-        continue;
-      }
-
-      const verifyResult = await runVerifyCommands(context, verifyCommands, attemptDir);
-      if (verifyResult.ok) {
-        updateTask(backlog, task.id, {
-          status: "done",
-          finishedAt: nowIso(),
-          lastFailure: "",
-          attempts: failureHistory.length + 1,
-        });
-        saveBacklog(context, backlog);
-        return {
-          ok: true,
-          kind: "done",
-          task,
-          runDir,
-          finalMessage: codexResult.finalMessage,
-        };
-      }
-
-      previousFailure = buildFailureSummary("verify", verifyResult);
-      failureHistory.push({
-        strategyIndex,
-        attemptIndex,
-        kind: "verify",
-        summary: previousFailure,
-      });
-      if (isHardStopFailure("verify", previousFailure)) {
-        updateTask(backlog, task.id, {
-          status: "failed",
-          finishedAt: nowIso(),
-          lastFailure: previousFailure,
-          attempts: failureHistory.length,
-        });
-        saveBacklog(context, backlog);
-        return { ok: false, kind: "verify-failed", task, runDir, summary: previousFailure };
-      }
-    }
-
-    previousFailure = [
-      previousFailure,
-      "",
-      `上一种策略已连续失败 ${maxAttemptsPerStrategy} 次。下一轮必须明确更换实现或排查思路，不能重复原路径。`,
-    ].join("\n").trim();
-  }
-
-  const exhaustedSummary = buildExhaustedSummary({
-    failureHistory,
-    maxStrategies,
-    maxAttemptsPerStrategy,
-  });
-  updateTask(backlog, task.id, {
-    status: "failed",
-    finishedAt: nowIso(),
-    lastFailure: exhaustedSummary,
-    attempts: failureHistory.length,
-  });
-  saveBacklog(context, backlog);
-  return { ok: false, kind: "strategy-exhausted", task, runDir, summary: exhaustedSummary };
-}
-
-export async function runOnce(context, options = {}) {
-  const result = await executeSingleTask(context, options);
-  const backlog = loadBacklog(context);
-  const summary = summarizeBacklog(backlog);
-  const nextTask = selectNextTask(backlog, options);
-
-  writeStatus(context, {
-    ok: result.ok,
-    stage: result.kind,
-    taskId: result.task?.id || null,
-    taskTitle: result.task?.title || "",
-    runDir: result.runDir || "",
-    summary,
-    message: result.summary || result.finalMessage || "",
-  });
-  writeStateMarkdown(context, renderStatusMarkdown(context, {
-    summary,
-    currentTask: result.task,
-    lastResult: result.ok ? "本轮成功" : (result.summary || result.kind),
-    nextTask,
-  }));
-
-  return result;
-}
-
-export async function runLoop(context, options = {}) {
-  const policy = loadPolicy(context);
-  const maxTasks = Math.max(1, Number(options.maxTasks || policy.maxLoopTasks || 1));
-  const results = [];
-
-  for (let index = 0; index < maxTasks; index += 1) {
-    const result = await runOnce(context, options);
-    results.push(result);
-    if (options.dryRun) break;
-    if (!result.ok || !result.task) break;
-    const backlog = loadBacklog(context);
-    if (!selectNextTask(backlog, options)) break;
-  }
-
-  return results;
-}
-
-export function renderStatusText(context, options = {}) {
-  const backlog = loadBacklog(context);
-  const summary = summarizeBacklog(backlog);
-  const nextTask = selectNextTask(backlog, options);
-
-  return [
-    "HelloLoop 状态",
-    "============",
-    `仓库：${context.repoRoot}`,
-    `总任务：${summary.total}`,
-    `已完成：${summary.done}`,
-    `待处理：${summary.pending}`,
-    `进行中：${summary.inProgress}`,
-    `失败：${summary.failed}`,
-    `阻塞：${summary.blocked}`,
-    "",
-    nextTask ? "下一任务：" : "下一任务：无",
-    nextTask ? renderTaskSummary(nextTask) : "",
-  ].filter(Boolean).join("\n");
-}
-
+export { runLoop } from "./runner_loop.mjs";
+export { runOnce } from "./runner_once.mjs";
+export { renderStatusText } from "./runner_status.mjs";

package/src/runner_execute_task.mjs

@@ -0,0 +1,255 @@
+import path from "node:path";
+
+import { rememberEngineSelection } from "./engine_selection.mjs";
+import { getEngineDisplayName } from "./engine_metadata.mjs";
+import { ensureDir, nowIso, writeText } from "./common.mjs";
+import { saveBacklog } from "./config.mjs";
+import { reviewTaskCompletion } from "./completion_review.mjs";
+import { updateTask } from "./backlog.mjs";
+import { buildTaskPrompt } from "./prompt.mjs";
+import { runEngineExec, runVerifyCommands } from "./process.mjs";
+import {
+  buildAttemptState,
+  buildBlockedResult,
+  buildDoneResult,
+  buildFailureResult,
+  bumpFailureForNextStrategy,
+  recordFailure,
+  resolveExecutionSetup,
+} from "./runner_execution_support.mjs";
+import {
+  buildExhaustedSummary,
+  buildFailureSummary,
+  isHardStopFailure,
+  makeAttemptDir,
+} from "./runner_status.mjs";
+
+async function handleEngineFailure(execution, state, attemptState, engineResult) {
+  const previousFailure = buildFailureSummary("engine", {
+    ...engineResult,
+    displayName: getEngineDisplayName(state.engineResolution.engine),
+  });
+  recordFailure(
+    state.failureHistory,
+    attemptState.strategyIndex,
+    attemptState.attemptIndex,
+    state.engineResolution.engine,
+    previousFailure,
+  );
+  return {
+    action: "return",
+    result: buildFailureResult(
+      execution,
+      "engine-failed",
+      previousFailure,
+      state.failureHistory.length,
+      state.engineResolution,
+    ),
+  };
+}
+
+function handleVerifyFailure(execution, state, attemptState, verifyResult) {
+  const previousFailure = buildFailureSummary("verify", verifyResult);
+  recordFailure(state.failureHistory, attemptState.strategyIndex, attemptState.attemptIndex, "verify", previousFailure);
+
+  if (isHardStopFailure("verify", previousFailure)) {
+    return {
+      action: "return",
+      result: buildFailureResult(
+        execution,
+        "verify-failed",
+        previousFailure,
+        state.failureHistory.length,
+        state.engineResolution,
+      ),
+    };
+  }
+  return { action: "continue", previousFailure };
+}
+
+async function handleReviewFailure(execution, state, attemptState, reviewResult) {
+  const previousFailure = reviewResult.summary;
+  recordFailure(state.failureHistory, attemptState.strategyIndex, attemptState.attemptIndex, "task_review", previousFailure);
+  return {
+    action: "return",
+    result: buildFailureResult(
+      execution,
+      "task-review-failed",
+      previousFailure,
+      state.failureHistory.length,
+      state.engineResolution,
+    ),
+  };
+}
+
+function handleIncompleteReview(execution, state, attemptState, reviewResult) {
+  const previousFailure = reviewResult.summary;
+  recordFailure(
+    state.failureHistory,
+    attemptState.strategyIndex,
+    attemptState.attemptIndex,
+    reviewResult.review.verdict === "blocked" ? "blocked" : "task_incomplete",
+    previousFailure,
+  );
+
+  if (reviewResult.review.verdict === "blocked") {
+    return {
+      action: "return",
+      result: buildBlockedResult(
+        execution,
+        previousFailure,
+        state.failureHistory.length,
+        state.engineResolution,
+      ),
+    };
+  }
+  return { action: "continue", previousFailure };
+}
+
+async function handleVerifyAndReview(execution, state, attemptState, engineResult) {
+  const verifyResult = await runVerifyCommands(execution.context, execution.verifyCommands, attemptState.attemptDir);
+  if (!verifyResult.ok) {
+    return handleVerifyFailure(execution, state, attemptState, verifyResult);
+  }
+
+  const reviewResult = await reviewTaskCompletion({
+    engine: state.engineResolution.engine,
+    context: execution.context,
+    task: execution.task,
+    requiredDocs: execution.requiredDocs,
+    constraints: execution.constraints,
+    repoStateText: execution.repoStateText,
+    engineFinalMessage: engineResult.finalMessage,
+    verifyResult,
+    runDir: attemptState.attemptDir,
+    policy: execution.policy,
+  });
+  if (!reviewResult.ok) {
+    return handleReviewFailure(execution, state, attemptState, reviewResult);
+  }
+  if (!reviewResult.review.isComplete) {
+    return handleIncompleteReview(execution, state, attemptState, reviewResult);
+  }
+
+  return {
+    action: "return",
+    result: buildDoneResult(
+      execution,
+      engineResult.finalMessage,
+      state.failureHistory.length + 1,
+      state.engineResolution,
+    ),
+  };
+}
+
+async function runAttempt(execution, state, attemptState) {
+  const prompt = buildTaskPrompt({
+    task: execution.task,
+    repoStateText: execution.repoStateText,
+    verifyCommands: execution.verifyCommands,
+    requiredDocs: execution.requiredDocs,
+    constraints: execution.constraints,
+    previousFailure: state.previousFailure,
+    failureHistory: state.failureHistory,
+    strategyIndex: attemptState.strategyIndex,
+    maxStrategies: execution.maxStrategies,
+    attemptIndex: attemptState.attemptIndex,
+    maxAttemptsPerStrategy: execution.maxAttemptsPerStrategy,
+  });
+
+  const engineResult = await runEngineExec({
+    engine: state.engineResolution.engine,
+    context: execution.context,
+    prompt,
+    runDir: attemptState.attemptDir,
+    policy: execution.policy,
+  });
+  if (!engineResult.ok) {
+    return handleEngineFailure(execution, state, attemptState, engineResult);
+  }
+  return handleVerifyAndReview(execution, state, attemptState, engineResult);
+}
+
+export async function executeSingleTask(context, options = {}) {
+  const execution = await resolveExecutionSetup(context, options);
+  if (execution.idleResult) {
+    return execution.idleResult;
+  }
+  if (!execution.engineResolution.ok) {
+    return {
+      ok: false,
+      kind: "engine-selection-failed",
+      task: execution.task,
+      summary: execution.engineResolution.message,
+      engineResolution: execution.engineResolution,
+    };
+  }
+
+  rememberEngineSelection(context, execution.engineResolution, options);
+  if (options.dryRun) {
+    const prompt = buildTaskPrompt({
+      task: execution.task,
+      repoStateText: execution.repoStateText,
+      verifyCommands: execution.verifyCommands,
+      requiredDocs: execution.requiredDocs,
+      constraints: execution.constraints,
+      strategyIndex: 1,
+      maxStrategies: execution.maxStrategies,
+      attemptIndex: 1,
+      maxAttemptsPerStrategy: execution.maxAttemptsPerStrategy,
+    });
+    ensureDir(execution.runDir);
+    writeText(path.join(execution.runDir, `${execution.engineResolution.engine}-prompt.md`), prompt);
+    return {
+      ok: true,
+      kind: "dry-run",
+      task: execution.task,
+      runDir: execution.runDir,
+      prompt,
+      verifyCommands: execution.verifyCommands,
+      engineResolution: execution.engineResolution,
+    };
+  }
+
+  updateTask(execution.backlog, execution.task.id, { status: "in_progress", startedAt: nowIso() });
+  saveBacklog(context, execution.backlog);
+
+  const state = {
+    engineResolution: execution.engineResolution,
+    previousFailure: "",
+    failureHistory: [],
+  };
+
+  for (let strategyIndex = 1; strategyIndex <= execution.maxStrategies; strategyIndex += 1) {
+    for (let attemptIndex = 1; attemptIndex <= execution.maxAttemptsPerStrategy; attemptIndex += 1) {
+      const outcome = await runAttempt(
+        execution,
+        state,
+        buildAttemptState(execution.runDir, strategyIndex, attemptIndex, makeAttemptDir),
+      );
+      if (outcome.action === "continue") {
+        state.previousFailure = outcome.previousFailure;
+        continue;
+      }
+      return outcome.result;
+    }
+
+    state.previousFailure = bumpFailureForNextStrategy(
+      state.previousFailure,
+      execution.maxAttemptsPerStrategy,
+    );
+  }
+
+  const exhaustedSummary = buildExhaustedSummary({
+    failureHistory: state.failureHistory,
+    maxStrategies: execution.maxStrategies,
+    maxAttemptsPerStrategy: execution.maxAttemptsPerStrategy,
+  });
+  return buildFailureResult(
+    execution,
+    "strategy-exhausted",
+    exhaustedSummary,
+    state.failureHistory.length,
+    state.engineResolution,
+  );
+}