helloloop 0.2.1 → 0.6.1

package/src/runner_execute_task.mjs

@@ -0,0 +1,301 @@
+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,
+  maybeSwitchEngine,
+  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,
+  );
+
+  const nextResolution = await maybeSwitchEngine(execution, state.engineResolution, previousFailure, "执行阶段");
+  if (nextResolution) {
+    return { action: "switch", previousFailure, engineResolution: nextResolution };
+  }
+  if (engineResult.recoveryFailure?.recoverable === false) {
+    return {
+      action: "return",
+      result: buildFailureResult(
+        execution,
+        "engine-failed",
+        previousFailure,
+        state.failureHistory.length,
+        state.engineResolution,
+      ),
+    };
+  }
+  if (isHardStopFailure("engine", previousFailure)) {
+    return {
+      action: "return",
+      result: buildFailureResult(
+        execution,
+        "engine-failed",
+        previousFailure,
+        state.failureHistory.length,
+        state.engineResolution,
+      ),
+    };
+  }
+  return { action: "continue", previousFailure };
+}
+
+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);
+
+  const nextResolution = await maybeSwitchEngine(execution, state.engineResolution, previousFailure, "任务复核阶段");
+  if (nextResolution) {
+    return { action: "switch", previousFailure, engineResolution: nextResolution };
+  }
+  if (reviewResult.raw?.recoveryFailure?.recoverable === false) {
+    return {
+      action: "return",
+      result: buildFailureResult(
+        execution,
+        "task-review-failed",
+        previousFailure,
+        state.failureHistory.length,
+        state.engineResolution,
+      ),
+    };
+  }
+  if (isHardStopFailure("review", previousFailure)) {
+    return {
+      action: "return",
+      result: buildFailureResult(
+        execution,
+        "task-review-failed",
+        previousFailure,
+        state.failureHistory.length,
+        state.engineResolution,
+      ),
+    };
+  }
+  return { action: "continue", previousFailure };
+}
+
+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 === "switch") {
+        state.previousFailure = outcome.previousFailure;
+        state.engineResolution = outcome.engineResolution;
+        continue;
+      }
+      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,
+  );
+}

package/src/runner_execution_support.mjs

@@ -0,0 +1,155 @@
+import {
+  rememberEngineSelection,
+  resolveEngineSelection,
+} from "./engine_selection.mjs";
+import { nowIso } from "./common.mjs";
+import {
+  loadBacklog,
+  loadPolicy,
+  loadProjectConfig,
+  loadRepoStateText,
+  loadVerifyCommands,
+  saveBacklog,
+} from "./config.mjs";
+import { getTask, selectNextTask, unresolvedDependencies, updateTask } from "./backlog.mjs";
+import { makeRunDir } from "./runner_status.mjs";
+import { resolveRuntimeRecoveryPolicy } from "./runtime_recovery.mjs";
+
+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);
+}
+
+export async function resolveExecutionSetup(context, options = {}) {
+  const policy = loadPolicy(context);
+  const projectConfig = loadProjectConfig(context);
+  const backlog = loadBacklog(context);
+  const task = resolveTask(backlog, options);
+  if (!task) {
+    return {
+      idleResult: { 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 maxAttemptsPerStrategy = Math.max(1, Number(options.maxAttempts || policy.maxTaskAttempts || 1));
+  const configuredStrategies = Math.max(1, Number(options.maxStrategies || policy.maxTaskStrategies || 1));
+  const engineResolution = options.engineResolution?.ok
+    ? options.engineResolution
+    : await resolveEngineSelection({
+      context,
+      policy,
+      options,
+      interactive: !options.yes,
+    });
+
+  return {
+    context,
+    options,
+    policy,
+    backlog,
+    projectConfig,
+    repoStateText: loadRepoStateText(context),
+    task,
+    verifyCommands,
+    runDir: makeRunDir(context, task.id),
+    requiredDocs: [...(projectConfig.requiredDocs || []), ...(options.requiredDocs || [])],
+    constraints: [...(projectConfig.constraints || []), ...(options.constraints || [])],
+    maxAttemptsPerStrategy,
+    maxStrategies: policy.stopOnFailure ? 1 : configuredStrategies,
+    engineResolution,
+  };
+}
+
+function updateTaskAndBuildResult(execution, status, result) {
+  updateTask(execution.backlog, execution.task.id, {
+    status,
+    finishedAt: nowIso(),
+    lastFailure: result.ok ? "" : (result.summary || ""),
+    attempts: result.attempts,
+  });
+  saveBacklog(execution.context, execution.backlog);
+  return result;
+}
+
+export function buildFailureResult(execution, kind, summary, attempts, engineResolution) {
+  return updateTaskAndBuildResult(execution, "failed", {
+    ok: false,
+    kind,
+    task: execution.task,
+    runDir: execution.runDir,
+    summary,
+    attempts,
+    engineResolution,
+  });
+}
+
+export function buildBlockedResult(execution, summary, attempts, engineResolution) {
+  return updateTaskAndBuildResult(execution, "blocked", {
+    ok: false,
+    kind: "task-blocked",
+    task: execution.task,
+    runDir: execution.runDir,
+    summary,
+    attempts,
+    engineResolution,
+  });
+}
+
+export function buildDoneResult(execution, finalMessage, attempts, engineResolution) {
+  return updateTaskAndBuildResult(execution, "done", {
+    ok: true,
+    kind: "done",
+    task: execution.task,
+    runDir: execution.runDir,
+    finalMessage,
+    attempts,
+    engineResolution,
+  });
+}
+
+export async function maybeSwitchEngine(execution, engineResolution, previousFailure, phaseLabel) {
+  const recoveryPolicy = resolveRuntimeRecoveryPolicy(execution.policy);
+  if (!recoveryPolicy.allowEngineSwitch) {
+    return null;
+  }
+  return null;
+}
+
+export function recordFailure(failureHistory, strategyIndex, attemptIndex, kind, summary) {
+  failureHistory.push({
+    strategyIndex,
+    attemptIndex,
+    kind,
+    summary,
+  });
+}
+
+export function buildAttemptState(runDir, strategyIndex, attemptIndex, makeAttemptDir) {
+  return {
+    strategyIndex,
+    attemptIndex,
+    attemptDir: makeAttemptDir(runDir, strategyIndex, attemptIndex),
+  };
+}
+
+export function bumpFailureForNextStrategy(previousFailure, maxAttemptsPerStrategy) {
+  return [
+    previousFailure,
+    "",
+    `上一种策略已连续失败 ${maxAttemptsPerStrategy} 次。下一轮必须明确更换实现或排查思路，不能重复原路径。`,
+  ].join("\n").trim();
+}

package/src/runner_loop.mjs

@@ -0,0 +1,106 @@
+import { selectNextTask, summarizeBacklog } from "./backlog.mjs";
+import { loadBacklog, loadPolicy } from "./config.mjs";
+import { reanalyzeCurrentWorkspace } from "./analyzer.mjs";
+import { runOnce } from "./runner_once.mjs";
+
+function shouldRunMainlineReanalysis(options, summary, reanalysisPasses, maxReanalysisPasses) {
+  return Boolean(options.fullAutoMainline)
+    && summary.pending === 0
+    && summary.inProgress === 0
+    && summary.failed === 0
+    && summary.blocked === 0
+    && reanalysisPasses < maxReanalysisPasses;
+}
+
+function buildMainlineReopenedResult(nextTask, engineResolution) {
+  return {
+    ok: true,
+    kind: "mainline-reopened",
+    task: null,
+    summary: [
+      "主线终态复核发现仍有剩余工作，已自动重建 backlog 并继续推进。",
+      `下一任务：${nextTask.title}`,
+    ].join("\n"),
+    engineResolution,
+  };
+}
+
+function buildMainlineCompleteResult(engineResolution) {
+  return {
+    ok: true,
+    kind: "mainline-complete",
+    task: null,
+    summary: "主线终态复核通过：开发文档目标已闭合，没有发现新的剩余任务。",
+    engineResolution,
+  };
+}
+
+function buildMainlineFailureResult(continuation, engineResolution) {
+  return {
+    ok: false,
+    kind: "mainline-reanalysis-failed",
+    task: null,
+    summary: continuation.summary || "主线终态复核失败。",
+    engineResolution,
+  };
+}
+
+export async function runLoop(context, options = {}) {
+  const policy = loadPolicy(context);
+  const explicitMaxTasks = Number(options.maxTasks);
+  const maxTasks = Number.isFinite(explicitMaxTasks) && explicitMaxTasks > 0
+    ? explicitMaxTasks
+    : (options.fullAutoMainline ? Number.POSITIVE_INFINITY : Math.max(1, Number(policy.maxLoopTasks || 1)));
+  const maxReanalysisPasses = Math.max(0, Number(options.maxReanalysisPasses || policy.maxReanalysisPasses || 0));
+  const results = [];
+  let engineResolution = options.engineResolution || null;
+  let completedTasks = 0;
+  let reanalysisPasses = 0;
+
+  while (completedTasks < maxTasks) {
+    const result = await runOnce(context, { ...options, engineResolution });
+    results.push(result);
+    if (result.engineResolution?.ok) {
+      engineResolution = result.engineResolution;
+    }
+    if (options.dryRun || !result.ok || !result.task) {
+      break;
+    }
+
+    completedTasks += 1;
+    const backlog = loadBacklog(context);
+    if (selectNextTask(backlog, options)) {
+      continue;
+    }
+
+    const summary = summarizeBacklog(backlog);
+    if (!shouldRunMainlineReanalysis(options, summary, reanalysisPasses, maxReanalysisPasses)) {
+      break;
+    }
+
+    reanalysisPasses += 1;
+    const continuation = await reanalyzeCurrentWorkspace(context, {
+      ...options,
+      engineResolution,
+      yes: true,
+    });
+    if (continuation.engineResolution?.ok) {
+      engineResolution = continuation.engineResolution;
+    }
+    if (!continuation.ok) {
+      results.push(buildMainlineFailureResult(continuation, engineResolution));
+      break;
+    }
+
+    const continuedNextTask = selectNextTask(loadBacklog(context), options);
+    if (continuedNextTask) {
+      results.push(buildMainlineReopenedResult(continuedNextTask, engineResolution));
+      continue;
+    }
+
+    results.push(buildMainlineCompleteResult(engineResolution));
+    break;
+  }
+
+  return results;
+}

package/src/runner_once.mjs

@@ -0,0 +1,29 @@
+import { selectNextTask, summarizeBacklog } from "./backlog.mjs";
+import { loadBacklog, writeStateMarkdown, writeStatus } from "./config.mjs";
+import { executeSingleTask } from "./runner_execute_task.mjs";
+import { renderStatusMarkdown } from "./runner_status.mjs";
+
+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;
+}

package/src/runner_status.mjs

@@ -0,0 +1,104 @@
+import path from "node:path";
+
+import { sanitizeId, tailText, timestampForFile } from "./common.mjs";
+import { renderTaskSummary, selectNextTask, summarizeBacklog } from "./backlog.mjs";
+import { loadBacklog } from "./config.mjs";
+
+export function makeRunDir(context, taskId) {
+  return path.join(context.runsDir, `${timestampForFile()}-${sanitizeId(taskId)}`);
+}
+
+export function makeAttemptDir(runDir, strategyIndex, attemptIndex) {
+  return path.join(
+    runDir,
+    `strategy-${String(strategyIndex).padStart(2, "0")}-attempt-${String(attemptIndex).padStart(2, "0")}`,
+  );
+}
+
+export function isHardStopFailure(kind, summary) {
+  const normalized = String(summary || "").toLowerCase();
+  if (!normalized) {
+    return false;
+  }
+  if (kind === "engine" && 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));
+}
+
+export function buildFailureSummary(kind, payload) {
+  if (kind !== "engine") {
+    return payload.summary;
+  }
+
+  return [
+    `${payload.displayName} 执行失败，退出码：${payload.code}`,
+    payload.recoverySummary || "",
+    "",
+    "stdout 尾部：",
+    tailText(payload.stdout, 60),
+    "",
+    "stderr 尾部：",
+    tailText(payload.stderr, 60),
+  ].join("\n").trim();
+}
+
+export function buildExhaustedSummary({
+  failureHistory,
+  maxStrategies,
+  maxAttemptsPerStrategy,
+}) {
+  const lastFailure = failureHistory.at(-1)?.summary || "未知失败。";
+  return [
+    `已按 Ralph Loop 执行 ${maxStrategies} 轮策略、每轮最多 ${maxAttemptsPerStrategy} 次重试，当前任务仍未收敛。`,
+    "",
+    "最后一次失败信息：",
+    lastFailure,
+  ].join("\n").trim();
+}
+
+export 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");
+}
+
+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");
+}