@citeark/agent 0.3.20

package/src/compute/local-codex-compiler.mjs

@@ -0,0 +1,52 @@
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import path from "node:path";
+import { prepareCompilationBundle, normalizeCompilationTask, compilerPrompt, acceptCompilerDraft } from "../research/compiler.mjs";
+import { reviewCompilerSources } from "../research/source-review.mjs";
+import { createLocalSourceReviewCompletion } from "../research/source-review-local-codex.mjs";
+import { composeAgentPrompt } from "../runtime/prompt.mjs";
+import { runLocalCodex } from "../runtime/local-codex.mjs";
+import { captureFinalWorkspace, updateRunState } from "../job.mjs";
+import { readJson, writeJson, createRunId } from "../util.mjs";
+
+// Only the execution transport and /job path mount change. The prepared task,
+// compiler prompt, normalization, coverage and source-review gates are shared.
+export const localizeCompilerPaths = (value, directory) => typeof value === "string"
+  ? value.replaceAll("/job/", `${directory}/`) : Array.isArray(value)
+    ? value.map((item) => localizeCompilerPaths(item, directory)) : value && typeof value === "object"
+      ? Object.fromEntries(Object.entries(value).map(([key, item]) => [key, localizeCompilerPaths(item, directory)])) : value;
+
+export async function runLocalCodexCompiler({ taskPath, runsDirectory, runId = createRunId(), prepareMarkdown,
+  validateResearch = async () => [], progress = () => {}, runCli = runLocalCodex }) {
+  const task = normalizeCompilationTask(await readJson(taskPath));
+  if (task.agent.runtime !== "codex" || !task.agent.model || task.agent.validationRetries !== 0)
+    throw new Error("Local CLI single-run compiler requires codex, an explicit model and validationRetries=0");
+  const bundle = await prepareCompilationBundle({ task, taskDirectory: path.dirname(path.resolve(taskPath)), runsDirectory, runId, prepareMarkdown });
+  bundle.runtimeAgent = { ...task.agent, authentication: "chatgpt_login" };
+  const cliDirectory = path.join(bundle.directories.execution, "local-codex");
+  await mkdir(cliDirectory, { recursive: true });
+  const instructions = await readFile(path.join(bundle.directories.input, "agent-instructions.md"), "utf8");
+  const prompt = localizeCompilerPaths(composeAgentPrompt(instructions, compilerPrompt(1, [])), bundle.directories.run);
+  await writeFile(path.join(cliDirectory, "prompt.txt"), prompt);
+  await writeJson(path.join(bundle.directories.input, "compile-task.json"), localizeCompilerPaths(bundle.runtimeTask, bundle.directories.run));
+  await updateRunState(bundle, { status: "running", sandbox: "local-codex-workspace-write", image: null,
+    startedAt: new Date().toISOString(), authentication: "chatgpt_login", model: task.agent.model });
+  try {
+    progress(task.compilationStage === "inventory" ? "本机 Codex CLI 开始模块二研究清单整理" : "本机 Codex CLI 开始复现准备");
+    const execution = await runCli({ prompt, cwd: bundle.directories.repository, directory: cliDirectory,
+      model: task.agent.model, effort: task.agent.effort, writableDirectories: [bundle.directories.output],
+      timeoutMs: task.environment.timeoutMinutes * 60_000, progress });
+    await writeJson(path.join(cliDirectory, "execution.json"), execution);
+    if (execution.code !== 0 || execution.timedOut) throw new Error("Local Codex compiler did not finish successfully; see retained execution logs");
+    progress(task.compilationStage === "inventory" ? "研究清单已返回，执行内容校验和独立来源复核" : "复现准备已返回，核对原始清单、实验覆盖与调度约束");
+    const complete = createLocalSourceReviewCompletion({ directory: path.join(bundle.directories.execution, "local-source-review"),
+      model: task.agent.model, effort: task.agent.effort, progress, runCli });
+    const accepted = await acceptCompilerDraft({ bundle, draft: await readJson(path.join(bundle.directories.output, "research.json")),
+      validateResearch, sourceReviewer: (options) => reviewCompilerSources({ ...options, complete }) });
+    await updateRunState(bundle, { status: "completed", finishedAt: new Date().toISOString(), output: "output/research.normalized.json",
+      normalizationWarnings: accepted.normalizationWarnings, usage: execution.usage });
+    return { bundle, ...accepted };
+  } catch (error) {
+    await updateRunState(bundle, { status: "invalid_result", finishedAt: new Date().toISOString(), validationIssues: [error.message] });
+    throw error;
+  } finally { await captureFinalWorkspace(bundle); }
+}

package/src/compute/measurement-hardware.mjs

@@ -0,0 +1,128 @@
+/** Scientific device constraints are applied before operational cost ranking. */
+// Metric spelling is only a hint; explicit scientific semantics own the gate.
+export const HARDWARE_SENSITIVE_METRIC = /(?:^|[_ -])(time|latency|throughput|memory|energy|runtime|duration|speed(?:up)?|joules?|watts?)(?:$|[_ -])/i;
+export function measurementRequiresHardwareProtocol(measurement) {
+  return measurement?.quantityKind === "device_performance";
+}
+
+export function measurementHardwareIssues(experiment, { requireDeclaration = false } = {}) {
+  const benchmark = experiment?.protocol?.benchmark;
+  const compute = experiment?.compute;
+  const measurements = Array.isArray(experiment?.measurements) ? experiment.measurements : [];
+  const sensitive = measurements.some(measurementRequiresHardwareProtocol);
+  const issues = [];
+  for (const measurement of measurements) {
+    if (requireDeclaration && measurement?.quantityKind === undefined
+      && HARDWARE_SENSITIVE_METRIC.test(String(measurement?.metric ?? ""))) {
+      issues.push(`Hardware-admission retry: classify measurement ${measurement?.reportedMeasurementId ?? measurement?.metric ?? "unknown"} with quantityKind before deciding whether hardware constraints apply.`);
+    }
+    if (measurement?.quantityKind !== undefined && !["device_performance", "operation_count", "numerical_result"].includes(measurement.quantityKind)) {
+      issues.push("measurement.quantityKind must be device_performance, operation_count or numerical_result");
+    }
+  }
+  if (requireDeclaration && sensitive && !benchmark?.device) {
+    issues.push("Hardware-boundary retry: declare protocol.benchmark.device as cpu or gpu from the scientific measurement, not from the cheapest available machine. Separate device-independent counts from device performance when necessary.");
+  }
+  if (requireDeclaration && sensitive && !benchmark?.hardwareBinding) {
+    issues.push("Hardware-admission retry: declare protocol.benchmark.hardwareBinding as required, not_required or unknown from the paper's measurement conditions. Do not infer portability from the currently available machine.");
+  }
+  if (requireDeclaration && sensitive && !benchmark?.hardwareBindingRationale) {
+    issues.push("Hardware-admission retry: explain the paper-grounded hardware-binding decision in protocol.benchmark.hardwareBindingRationale.");
+  }
+  if (requireDeclaration && sensitive && !benchmark?.hardwareBindingSources?.length) {
+    issues.push("Hardware-admission retry: cite the paper or repository locations establishing the hardware-binding decision in protocol.benchmark.hardwareBindingSources.");
+  }
+  if (benchmark?.device !== undefined && !["cpu", "gpu"].includes(benchmark.device)) {
+    issues.push("protocol.benchmark.device must be cpu or gpu");
+  }
+  if (benchmark?.device === "gpu" && (experiment?.compute?.accelerator !== "required" || experiment?.compute?.cpuFallbackAllowed !== false)) {
+    issues.push("Hardware-boundary retry: a GPU benchmark requires compute.accelerator=required and cpuFallbackAllowed=false. CPU timing or process RSS cannot replace GPU latency or device memory.");
+  }
+  if (benchmark?.requiredGpuTypes !== undefined && (!Array.isArray(benchmark.requiredGpuTypes)
+    || benchmark.requiredGpuTypes.some((value) => typeof value !== "string" || !value.trim()))) {
+    issues.push("protocol.benchmark.requiredGpuTypes must be an array of GPU type identifiers");
+  }
+  if (benchmark?.requiredGpuTypes?.length && benchmark.device !== "gpu") {
+    issues.push("protocol.benchmark.requiredGpuTypes requires device=gpu");
+  }
+  if (benchmark?.requiredGpuCount !== undefined && (!Number.isInteger(benchmark.requiredGpuCount) || benchmark.requiredGpuCount < 1)) {
+    issues.push("protocol.benchmark.requiredGpuCount must be a positive integer");
+  }
+  if (benchmark?.requiredVramGb !== undefined && (!(Number.isFinite(benchmark.requiredVramGb)) || benchmark.requiredVramGb <= 0)) {
+    issues.push("protocol.benchmark.requiredVramGb must be a positive finite number");
+  }
+  if (benchmark?.hardwareBinding !== undefined && !["required", "not_required", "unknown"].includes(benchmark.hardwareBinding)) {
+    issues.push("protocol.benchmark.hardwareBinding must be required, not_required or unknown");
+  }
+  if (benchmark?.hardwareBindingRationale !== undefined && (typeof benchmark.hardwareBindingRationale !== "string" || !benchmark.hardwareBindingRationale.trim())) {
+    issues.push("protocol.benchmark.hardwareBindingRationale must explain the source-grounded binding decision");
+  }
+  if (benchmark?.hardwareBindingSources !== undefined && (!Array.isArray(benchmark.hardwareBindingSources)
+    || benchmark.hardwareBindingSources.length === 0
+    || benchmark.hardwareBindingSources.some((source) =>
+      !source || typeof source.sourceId !== "string" || !source.sourceId.trim()
+      || typeof source.locator !== "string" || !source.locator.trim()))) {
+    issues.push("protocol.benchmark.hardwareBindingSources must contain sourceId and locator records");
+  }
+  if (benchmark?.comparisonIntent !== undefined && !["reference_conditions", "cross_hardware"].includes(benchmark.comparisonIntent)) {
+    issues.push("protocol.benchmark.comparisonIntent must be reference_conditions or cross_hardware");
+  }
+  if (benchmark?.comparisonRationale !== undefined && (typeof benchmark.comparisonRationale !== "string" || !benchmark.comparisonRationale.trim())) {
+    issues.push("protocol.benchmark.comparisonRationale must explain the intended comparison");
+  }
+  if (benchmark?.hardwareBinding === "required") {
+    if (benchmark.comparisonIntent !== "reference_conditions") {
+      issues.push("Hardware-admission retry: a paper-bound hardware measurement must use comparisonIntent=reference_conditions. A cross-hardware run is a separate exploratory question and cannot verify the reported value.");
+    }
+    if (typeof benchmark.referenceHardware !== "string" || !benchmark.referenceHardware.trim()) {
+      issues.push("protocol.benchmark.referenceHardware is required when hardwareBinding=required");
+    }
+    if (benchmark.device === "gpu" && !benchmark.requiredGpuTypes?.length) {
+      issues.push("Hardware-admission retry: a GPU-bound reported measurement must declare exact catalog GPU types in protocol.benchmark.requiredGpuTypes.");
+    }
+    if (benchmark.device === "gpu" && (!Number.isInteger(benchmark.requiredGpuCount) || benchmark.requiredGpuCount < 1)) {
+      issues.push("Hardware-admission retry: a GPU-bound reported measurement must declare protocol.benchmark.requiredGpuCount from the paper conditions.");
+    }
+    if (Number.isInteger(benchmark.requiredGpuCount) && Number(compute?.gpuCount ?? 0) < benchmark.requiredGpuCount) {
+      issues.push(`Hardware-admission retry: compute.gpuCount=${compute?.gpuCount ?? 0} is below the paper-bound requirement ${benchmark.requiredGpuCount}.`);
+    }
+    if (Number.isFinite(benchmark.requiredVramGb) && Number(compute?.minVramGb ?? 0) < benchmark.requiredVramGb) {
+      issues.push(`Hardware-admission retry: compute.minVramGb=${compute?.minVramGb ?? 0} is below the paper-bound per-GPU requirement ${benchmark.requiredVramGb} GiB.`);
+    }
+  }
+  return issues;
+}
+
+export function measurementHardwareConstraint(experiment) {
+  const benchmark = experiment?.protocol?.benchmark;
+  return {
+    device: benchmark?.device ?? null,
+    requiredGpuTypes: benchmark?.requiredGpuTypes ?? [],
+    requiredGpuCount: benchmark?.requiredGpuCount ?? null,
+    requiredVramGb: benchmark?.requiredVramGb ?? null,
+    referenceHardware: benchmark?.referenceHardware ?? null,
+    hardwareBinding: benchmark?.hardwareBinding ?? null,
+    hardwareBindingRationale: benchmark?.hardwareBindingRationale ?? null,
+    hardwareBindingSources: benchmark?.hardwareBindingSources ?? [],
+    comparisonIntent: benchmark?.comparisonIntent ?? null,
+    comparisonRationale: benchmark?.comparisonRationale ?? null,
+  };
+}
+
+export function measurementHardwareRejections(profile, constraint) {
+  const reasons = [];
+  if (constraint.device && profile.accelerator !== constraint.device) {
+    reasons.push(`科研测量要求 ${constraint.device} 设备，不能以 ${profile.accelerator} 替代`);
+  }
+  if (constraint.requiredGpuTypes.length && !constraint.requiredGpuTypes.some((type) =>
+    type.trim().toLowerCase() === String(profile.gpu?.type ?? "").trim().toLowerCase())) {
+    reasons.push(`科研测量限定 GPU 型号：${constraint.requiredGpuTypes.join("、")}`);
+  }
+  if (constraint.requiredGpuCount !== null && (profile.gpu?.count ?? 0) < constraint.requiredGpuCount) {
+    reasons.push(`科研测量要求至少 ${constraint.requiredGpuCount} 张 GPU`);
+  }
+  if (constraint.requiredVramGb !== null && (profile.gpu?.vramGb ?? 0) < constraint.requiredVramGb) {
+    reasons.push(`科研测量要求每张 GPU 至少 ${constraint.requiredVramGb} GiB 显存`);
+  }
+  return reasons;
+}

package/src/compute/remote-attempt.mjs

@@ -0,0 +1,226 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+import { redactString } from "../cap/redaction.mjs";
+import { pathExists, readJson } from "../util.mjs";
+
+const ERROR_TAIL_CHARACTERS = 4_000;
+const TRACE_TAIL_LINES = 240;
+
+export async function readRemoteAttempt(bundle, attempt) {
+  const target = path.join(
+    bundle.directories.execution,
+    `remote-attempt-${attempt}.json`,
+  );
+  return await pathExists(target) ? await readJson(target) : null;
+}
+
+export async function describeRemoteAgentFailure(bundle, attempt) {
+  const budgetFailurePath = path.join(bundle.directories.execution, "paper-budget-exhausted.json");
+  if (await pathExists(budgetFailurePath)) {
+    const recorded = await readJson(budgetFailurePath);
+    // A preserved process failure is evidence about that attempt, not a new
+    // spending decision. Reconcile it with the submitted result like any exit.
+    return {
+      attempt, exitCode: 1, failureCode: "paper.budget_exhausted",
+      failureCategory: "budget", failureStage: "execution", retryable: false,
+      message: redactString(`该次执行因预算停止${recorded.at ? `（${recorded.at}）` : ""}：${recorded.reason || "预算不足或价格无法确认"}`),
+    };
+  }
+  const remoteAttempt = await readRemoteAttempt(bundle, attempt);
+  const reportedExitCode = Number(remoteAttempt?.exitCode);
+  const agentExitCode = Number(remoteAttempt?.agentExitCode);
+  const agentFailed = Number.isInteger(agentExitCode) && agentExitCode !== 0;
+  const exitCode = agentFailed ? agentExitCode : reportedExitCode;
+  if (!Number.isInteger(exitCode) || exitCode === 0) return null;
+
+  const agentStalled = remoteAttempt?.agentStalled === true
+    || remoteAttempt?.agentStalled === 1;
+  const timedOut = remoteAttempt?.timedOut === true || remoteAttempt?.timedOut === 1;
+  const reportedCategory = typeof remoteAttempt?.failureCategory === "string"
+    ? remoteAttempt.failureCategory
+    : "agent";
+  const failureCategory = timedOut || agentStalled ? "timeout" : agentFailed ? "agent" : reportedCategory;
+  const reportedStage = typeof remoteAttempt?.failureStage === "string"
+    ? remoteAttempt.failureStage
+    : "execution";
+  const failureStage = agentStalled
+    ? reportedStage
+    : timedOut ? "execution" : agentFailed ? "execution" : reportedStage;
+  const retryable = timedOut || agentStalled ? false : agentFailed || remoteAttempt?.retryable !== false;
+  const diagnostics = failureCategory === "publication" || failureStage.includes("publication") || failureStage === "storage-headroom"
+    ? [await readDiagnosticFile(bundle, "publication-stderr.log")]
+    : await agentFailureDiagnostics(bundle);
+  const tail = redactString(diagnostics.filter(Boolean).join("\n").slice(-ERROR_TAIL_CHARACTERS))
+    .replaceAll(/\s+/g, " ")
+    .trim();
+  const accountFailure = bundle.runtimeAgent?.codexAccountId ? classifyProviderActionRequired(tail) : null;
+  if (accountFailure) return { attempt, exitCode, failureCategory: "provider", failureStage: "provider", failureCode: accountFailure.code, retryable: false, message: accountFailure.message, recoveryAction: accountFailure.recoveryAction };
+  const runtime = bundle.runtimeAgent?.runtime ?? "Agent";
+  if (diagnostics.some(value => value.startsWith("citeark.codex_capacity_retries_exhausted:"))) return { attempt, exitCode,
+    failureCategory: "provider", failureStage: "provider", failureCode: "codex.capacity_retry_exhausted", retryable: false,
+    message: "模型容量不足；同一环境内的等待恢复已达到上限，已停止并保留编译会话",
+    recoveryAction: "等待模型容量恢复后显式续跑" };
+  const prefix = agentStalled
+    ? `${runtime} 长时间没有有效进展，已由监督器终止并保留现场`
+    : timedOut
+    ? `${runtime} 已耗尽不可变执行时限`
+    : failureCategory === "publication"
+    ? `结果发布在 ${failureStage} 阶段失败`
+    : `${runtime} 第 ${attempt} 次执行失败`;
+  const publicationSuffix = agentFailed && reportedCategory === "publication"
+    ? `；随后结果发布也在 ${reportedStage} 阶段失败`
+    : "";
+  return {
+    attempt,
+    exitCode,
+    failureCategory,
+    failureStage,
+    failureCode: timedOut
+      ? remoteAttempt?.failureCode ?? "execution.runtime_budget_exhausted"
+      : remoteAttempt?.failureCode,
+    agentStalled,
+    timedOut,
+    retryable,
+    message: `${prefix}（退出码 ${exitCode}）${
+      tail ? `：${tail}` : "，但没有留下 stderr"
+    }${publicationSuffix}`,
+  };
+}
+
+/**
+ * Provider account/configuration failures cannot be repaired by rerunning the
+ * same compiler input. Convert raw runtime diagnostics into a stable, safe
+ * operator-facing reason and let the processing worker end the attempt.
+ */
+export function classifyProviderActionRequired(value) {
+  const diagnostic = value instanceof Error ? value.message : String(value ?? "");
+  if (/model.{0,160}is not supported when using Codex with a ChatGPT account/i.test(diagnostic)) {
+    return { code: "codex.subscription_model_unavailable", failureCategory: "provider", retryable: false,
+      message: "当前 Codex 订阅执行环境无法使用所选模型，已停止自动重试并保留诊断",
+      recoveryAction: "核对科学容器中的 Codex 版本及该账号的模型可用性，修复后显式续跑" };
+  }
+  if (/usage_limit_reached|you(?:'|’)ve hit your usage limit|your usage limit has been reached/i.test(diagnostic)) {
+    return { code: "codex.subscription_quota_exhausted", failureCategory: "provider", retryable: false,
+      message: "Codex 订阅额度已用尽；已停止本次处理并保留现场",
+      recoveryAction: "等待此账号额度恢复后再续跑" };
+  }
+  if (
+    (/\b402\b/.test(diagnostic) &&
+      /(?:api|provider|payment|credit|balance|openrouter|openai|anthropic)/i.test(diagnostic)) ||
+    /(?:insufficient|not enough|more)\s+(?:credit|credits|balance)/i.test(diagnostic) ||
+    /(?:credit|balance).{0,40}(?:exhausted|depleted|too low)/i.test(diagnostic)
+  ) {
+    return {
+      code: "provider_credit_exhausted",
+      failureCategory: "provider",
+      retryable: false,
+
+      message: "模型服务账户余额不足，本次处理已结束；充值或切换可用模型后可创建续跑",
+      recoveryAction: "充值模型服务账户，或切换到可用的模型配置后重试",
+    };
+  }
+  if (
+    /\b(?:401|403)\b/.test(diagnostic) &&
+    /(?:provider|api|auth|credential|token|key|unauthor|forbidden|openrouter|openai|anthropic)/i.test(diagnostic)
+  ) {
+    return {
+      code: "provider_credentials_invalid",
+      failureCategory: "provider",
+      retryable: false,
+
+      message: "模型服务凭证无效或无权访问，本次处理已结束；更新凭证后可创建续跑",
+      recoveryAction: "检查模型服务凭证与模型访问权限后重试",
+    };
+  }
+  return null;
+}
+
+/**
+ * The remote Agent process and the scientific result envelope are separate
+ * trust boundaries. A non-zero wrapper exit is useful attempt diagnostics, but
+ * it must not invalidate a result that already passed deterministic protocol
+ * validation. Only merge the remote failure into validation when the submitted
+ * envelope is itself missing or invalid.
+ */
+export function reconcileRemoteAgentOutcome({ validation, remoteFailure }) {
+  if (!remoteFailure) {
+    return { validation, blockingFailure: null };
+  }
+  const executionSucceeded = validation?.result?.execution?.status === "succeeded";
+  const preservedWorkspaceOutcome = validation?.normalization?.source === "platform-workspace-summary";
+  const requiresCompletedEvidence = ["timeout", "budget", "provider"].includes(remoteFailure.failureCategory);
+  if (validation.issues.length === 0 && (!requiresCompletedEvidence || executionSucceeded || preservedWorkspaceOutcome)) {
+    return { validation, blockingFailure: null };
+  }
+  return {
+    validation: {
+      ...validation,
+      issues: [...new Set([remoteFailure.message, ...validation.issues])],
+    },
+    blockingFailure: remoteFailure.retryable === false ? remoteFailure : null,
+  };
+}
+
+async function agentFailureDiagnostics(bundle) {
+  const [stderr, trace, relay] = await Promise.all([
+    readDiagnosticFile(bundle, "claude-stderr.log"),
+    readDiagnosticFile(bundle, "trace.jsonl"),
+    readDiagnosticFile(bundle, "provider-pro-relay.log"),
+  ]);
+  const traceError = structuredTraceError(trace);
+  const relayError = relay
+    .split(/\r?\n/)
+    .filter((line) => line.trim() && !/codex_pro_relay\.ready/.test(line))
+    .join("\n");
+  return [stderr, traceError, relayError];
+}
+
+async function readDiagnosticFile(bundle, name) {
+  return await readFile(
+    path.join(bundle.directories.execution, name),
+    "utf8",
+  ).catch(() => "");
+}
+
+function structuredTraceError(trace) {
+  const lines = trace.split(/\r?\n/).filter(Boolean).slice(-TRACE_TAIL_LINES).reverse();
+  for (const line of lines) {
+    let event;
+    try {
+      event = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (!event || typeof event !== "object") continue;
+    const kind = [event.type, event.event, event.status, event.error?.name]
+      .filter((value) => typeof value === "string")
+      .join(" ");
+    if (!event.error && !/(?:error|fail|abort|cancel)/i.test(kind)) continue;
+    const message = firstDiagnosticString([
+      event.error?.data?.message,
+      event.error?.message,
+      event.data?.message,
+      event.message,
+      event.reason,
+      event.error,
+    ]);
+    if (message) return `${kind || "runtime error"}: ${message}`;
+  }
+  return "";
+}
+
+function firstDiagnosticString(values) {
+  for (const value of values) {
+    if (typeof value === "string" && value.trim()) return value.trim();
+    if (value && typeof value === "object") {
+      try {
+        const serialized = JSON.stringify(value);
+        if (serialized && serialized !== "{}") return serialized;
+      } catch {
+        // Ignore non-serializable diagnostic payloads.
+      }
+    }
+  }
+  return "";
+}

package/src/compute/requirements.mjs

@@ -0,0 +1,124 @@
+import { isRecord } from "../util.mjs";
+
+export const ACCELERATOR_REQUIREMENTS = new Set(["none", "optional", "required"]);
+
+export function validateDeclaredComputeRequirement(value, label = "compute") {
+  const issues = [];
+  if (!isRecord(value)) return [`${label} 必须是对象`];
+  if (!ACCELERATOR_REQUIREMENTS.has(value.accelerator)) {
+    issues.push(`${label}.accelerator 必须是 none、optional 或 required`);
+  }
+  for (const field of ["cpuCores", "memoryGb"]) {
+    if (!isFinitePositive(value[field])) {
+      issues.push(`${label}.${field} 必须是大于 0 的有限数值`);
+    }
+  }
+  if (!isFiniteNonNegative(value.gpuCount)) {
+    issues.push(`${label}.gpuCount 必须是非负有限数值`);
+  } else if (value.accelerator !== "none" && value.gpuCount <= 0) {
+    issues.push(`${label}.gpuCount 在需要或可选 GPU 时必须大于 0`);
+  }
+  if (value.minVramGb !== undefined && value.minVramGb !== null && !isFinitePositive(value.minVramGb)) {
+    issues.push(`${label}.minVramGb 必须是大于 0 的有限数值或 null`);
+  }
+  if (typeof value.cpuFallbackAllowed !== "boolean") {
+    issues.push(`${label}.cpuFallbackAllowed 必须是布尔值`);
+  }
+  if (value.preemptionSafe !== undefined && typeof value.preemptionSafe !== "boolean") {
+    issues.push(`${label}.preemptionSafe 必须是布尔值`);
+  }
+  if (value.preferredGpuTypes !== undefined) {
+    if (!Array.isArray(value.preferredGpuTypes) || value.preferredGpuTypes.some((item) => typeof item !== "string" || !item.trim())) {
+      issues.push(`${label}.preferredGpuTypes 必须是非空字符串数组`);
+    }
+  }
+  if (value.estimatedDurationMinutes !== undefined) {
+    if (!isRecord(value.estimatedDurationMinutes)) {
+      issues.push(`${label}.estimatedDurationMinutes 必须是对象`);
+    } else {
+      for (const field of ["cpu", "gpu"]) {
+        if (value.estimatedDurationMinutes[field] !== undefined && value.estimatedDurationMinutes[field] !== null && !isFinitePositive(value.estimatedDurationMinutes[field])) {
+          issues.push(`${label}.estimatedDurationMinutes.${field} 必须是大于 0 的有限数值或 null`);
+        }
+      }
+    }
+  }
+  if (typeof value.rationale !== "string" || !value.rationale.trim()) {
+    issues.push(`${label}.rationale 必须是非空字符串`);
+  }
+  if (value.workloads !== undefined) {
+    if (!Array.isArray(value.workloads) || !value.workloads.length) issues.push(`${label}.workloads 必须是非空数组`);
+    else {
+      const ids = new Set();
+      for (const item of value.workloads) {
+        if (!isRecord(item) || typeof item.id !== "string" || !item.id.trim()
+          || typeof item.description !== "string" || !item.description.trim()) {
+          issues.push(`${label}.workloads 每项必须有计算身份和说明`); continue;
+        }
+        if (ids.has(item.id)) issues.push(`${label}.workloads 计算身份重复：${item.id}`);
+        ids.add(item.id);
+        for (const accelerator of ["cpu", "gpu"]) {
+          const duration = item.estimatedDurationMinutes?.[accelerator];
+          if (duration !== undefined && duration !== null && !isFinitePositive(duration)) issues.push(`${label}.workloads 时间必须是正数或未知`);
+        }
+      }
+    }
+  }
+  return issues;
+}
+
+export function resolveComputeRequirement(experiment) {
+  const declared = experiment?.compute;
+  if (declared) {
+    const issues = validateDeclaredComputeRequirement(declared);
+    if (issues.length) throw new TypeError(issues.join("；"));
+  }
+
+  const inferredAccelerator = experiment?.environment?.gpu === "all"
+    ? "required"
+    : experiment?.reproductionLevel === "official-checkpoint"
+      ? "optional"
+      : "none";
+  const accelerator = declared?.accelerator ?? inferredAccelerator;
+  const cpuFallbackAllowed = declared?.cpuFallbackAllowed ?? accelerator !== "required";
+  return {
+    schemaVersion: "0.1",
+    source: declared ? "research-declared" : "research-derived",
+    classification: classificationFor(accelerator),
+    accelerator,
+    cpuCores: declared?.cpuCores ?? experiment?.environment?.cpus ?? 4,
+    memoryGb: declared?.memoryGb ?? experiment?.environment?.memoryGb ?? 16,
+    gpuCount: declared?.gpuCount ?? (accelerator === "none" ? 0 : 1),
+    minVramGb: declared?.minVramGb ?? null,
+    preferredGpuTypes: [...(declared?.preferredGpuTypes ?? [])],
+    cpuFallbackAllowed,
+    preemptionSafe: declared?.preemptionSafe === true,
+    estimatedDurationMinutes: {
+      cpu: declared?.estimatedDurationMinutes?.cpu ?? null,
+      gpu: declared?.estimatedDurationMinutes?.gpu ?? null,
+    },
+    rationale: declared?.rationale ?? inferredRationale(experiment?.reproductionLevel, accelerator),
+  };
+}
+
+function classificationFor(accelerator) {
+  if (accelerator === "required") return "gpu-required";
+  if (accelerator === "optional") return "gpu-optional";
+  return "cpu-only";
+}
+
+function inferredRationale(reproductionLevel, accelerator) {
+  if (accelerator === "required") return "The fixed Research Plan requires a GPU execution environment.";
+  if (accelerator === "optional") return "Official checkpoint evaluation can usually run on CPU, but a GPU may shorten runtime.";
+  return reproductionLevel === "full-training"
+    ? "Full training does not by itself imply a GPU dependency; without an explicit GPU requirement, the experiment is scheduled as a CPU task."
+    : "This experiment declares no GPU dependency and is scheduled as a CPU task.";
+}
+
+function isFinitePositive(value) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0;
+}
+
+function isFiniteNonNegative(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}

package/src/compute/research-phases.mjs

@@ -0,0 +1,48 @@
+import { CiteArkError } from "../util.mjs";
+import { createCpuResearchPreparationWorkload } from "../workloads/cpu-research-preparation.mjs";
+import { createPhaseAwareReproductionWorkload } from "../workloads/phase-aware-reproduction.mjs";
+import { executeGcpBatchReproduction } from "./gcp-batch-executor.mjs";
+
+/** Machine transitions, not prescribed scientific steps. Deterministic run IDs
+ * reuse saved phase receipts on coordinator recovery instead of paying twice.
+ */
+export async function executeResearchPhases(options, execute = executeGcpBatchReproduction) {
+  const gcp = options.executorOptions?.gcpBatch ?? {};
+  const cpuDecision = gcp.cpuResearchComputeDecision;
+  if (!cpuDecision || options.workloadAdapter || options.computeDecision?.environment?.gpu !== "all") return execute(options);
+  // Every phase keeps the same cumulative paper budget and cancellation path.
+  // A phase count is not evidence that a scientific task has stopped progressing.
+  let checkpoint = null;
+  for (let cycle = 0; ; cycle++) {
+    const execution = await execute({ ...options,
+      runId: cycle ? `${options.runId}-gpu-${cycle}` : options.runId,
+      workloadAdapter: createPhaseAwareReproductionWorkload(),
+      executorOptions: { ...options.executorOptions, gcpBatch: { ...gcp,
+        ...(checkpoint ? { restoreCheckpointPrefix: checkpoint.checkpointPrefix,
+          restoreCheckpointBucket: checkpoint.bucket, reuseCompletedResultOnRestore: false } : {}),
+      } },
+    });
+    if (execution.dryRun || !execution.phaseHandoff) return execution;
+    checkpoint = execution.checkpoint;
+    options.progress?.("GPU 已结束本阶段，使用完整检查点回到 CPU 继续准备；预算与历史结果保持累计。");
+    const preparation = await execute({ ...options,
+      runId: `${options.runId}-cpu-${cycle + 1}`,
+      computeDecision: cpuDecision,
+      workloadAdapter: createCpuResearchPreparationWorkload({ runtimeBudgetMinutes: options.computeDecision.environment.timeoutMinutes }),
+      executorOptions: { ...options.executorOptions, gcpBatch: { ...gcp,
+        clients: gcp.assetPreparationClients ?? gcp.clients,
+        restoreCheckpointPrefix: checkpoint.checkpointPrefix,
+        restoreCheckpointBucket: checkpoint.bucket,
+        reuseCompletedResultOnRestore: false, keepStaging: true,
+      } },
+    });
+    if (preparation.preparation?.status !== "ready") {
+      const error = new CiteArkError(`CPU 继续准备未找到可执行路线：${preparation.preparation?.summary ?? "缺少交接结果"}`, {
+        failureCode: "research_preparation.no_viable_execution", retryable: false,
+      });
+      error.recoveryCheckpoint = preparation.checkpoint;
+      throw error;
+    }
+    checkpoint = preparation.checkpoint;
+  }
+}