ai-dev-harness 0.1.0 → 0.1.2

package/dist/checkpoint.js

@@ -0,0 +1,83 @@
+import { rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { git, runCommand } from "./utils.js";
+function normalizeRel(file) {
+    return file.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+function statusPath(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return "";
+    const rename = trimmed.match(/^R.?\s+(.+)\s+->\s+(.+)$/);
+    if (rename)
+        return normalizeRel(rename[2]);
+    return normalizeRel(trimmed.slice(3).trim());
+}
+function untrackedFiles(status) {
+    return status
+        .split(/\r?\n/)
+        .filter((line) => line.startsWith("?? "))
+        .map(statusPath)
+        .filter(Boolean);
+}
+function underRoot(file, root) {
+    const normalized = normalizeRel(file);
+    const normalizedRoot = normalizeRel(root).replace(/\/?$/, "/");
+    return normalized === normalizedRoot.slice(0, -1) || normalized.startsWith(normalizedRoot);
+}
+export async function createCheckpoint(options) {
+    const head = await git(options.cwd, "rev-parse HEAD");
+    const runRel = path.relative(options.cwd, options.runDir).replace(/\\/g, "/");
+    const runRoot = runRel.split("/")[0];
+    const rawStatusBefore = await git(options.cwd, "status --short");
+    const gitStatusBefore = rawStatusBefore
+        .split(/\r?\n/)
+        .filter((line) => {
+        const file = line.trim().slice(3).replace(/\\/g, "/");
+        return file && file !== runRoot && file !== `${runRoot}/` && !file.startsWith(`${runRoot}/`) && !file.startsWith(`${runRel}/`);
+    })
+        .join("\n");
+    const preDiff = await git(options.cwd, "diff --no-ext-diff");
+    const checkpoint = {
+        head,
+        baselineClean: !gitStatusBefore,
+        gitStatusBefore,
+        iteration: options.iteration,
+        restoreSupported: !gitStatusBefore && Boolean(head),
+        untrackedFilesBefore: untrackedFiles(gitStatusBefore),
+        excludedStatusRoots: [runRoot]
+    };
+    await writeFile(options.preDiffPath, preDiff, "utf8");
+    await writeFile(options.checkpointPath, `${JSON.stringify(checkpoint, null, 2)}\n`, "utf8");
+    return checkpoint;
+}
+export async function writePostIterationDiff(cwd, postDiffPath) {
+    const diff = await git(cwd, "diff --no-ext-diff");
+    await writeFile(postDiffPath, diff, "utf8");
+    return diff;
+}
+export async function restoreCheckpoint(cwd, checkpoint) {
+    if (!checkpoint.restoreSupported || !checkpoint.baselineClean) {
+        return {
+            ok: false,
+            message: "该 checkpoint 不支持自动 restore：运行开始前存在未提交改动，或缺少 Git HEAD。"
+        };
+    }
+    const currentStatus = await git(cwd, "status --short");
+    if (!currentStatus)
+        return { ok: true, message: "工作区已经是 clean，无需 restore。" };
+    const untrackedBefore = new Set((checkpoint.untrackedFilesBefore ?? []).map(normalizeRel));
+    const excludedRoots = checkpoint.excludedStatusRoots ?? [];
+    const newUntracked = untrackedFiles(currentStatus).filter((file) => !untrackedBefore.has(file) && !excludedRoots.some((root) => underRoot(file, root)));
+    const result = await runCommand("git restore --worktree --staged .", cwd, undefined, 60_000);
+    if (result.exitCode !== 0)
+        return { ok: false, message: result.stderr || "git restore failed" };
+    for (const file of newUntracked) {
+        const absolute = path.resolve(cwd, file);
+        const relative = path.relative(cwd, absolute);
+        if (relative.startsWith("..") || path.isAbsolute(relative))
+            continue;
+        await rm(absolute, { force: true, recursive: true });
+    }
+    return { ok: true, message: "已通过 git restore 恢复工作区，并清理本轮新增的未跟踪文件。" };
+}

package/dist/cli.js

@@ -1,26 +1,38 @@
 #!/usr/bin/env node
-import { readFile, writeFile } from "node:fs/promises";
+import { copyFile, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { AuditLogger, prepareRunFiles, writeJson } from "./audit.js";
-import { createAgentAdapter } from "./agent.js";
+import { checkAgentContract, createAgentAdapter } from "./agent.js";
+import { evaluateApprovalGate } from "./approval.js";
+import { createCheckpoint, restoreCheckpoint, writePostIterationDiff } from "./checkpoint.js";
 import { loadConfig, loadSkill } from "./config.js";
 import { buildContextPack } from "./context.js";
+import { writeContextScore } from "./contextScore.js";
+import { writeVerifyDiagnostics } from "./diagnostics.js";
+import { runDoctor } from "./doctor.js";
+import { feedbackEvent } from "./feedback.js";
 import { initHarness } from "./init.js";
 import { installIntegration } from "./integration.js";
-import { makeRunPaths } from "./runPaths.js";
+import { evaluateIteration, renderReworkFeedback, writeLoopArtifacts } from "./loop.js";
+import { collectRunMetrics, renderMetricsText } from "./metrics.js";
+import { buildReplayPlan, renderReplayPlan } from "./replay.js";
+import { makeIterationPaths, makeRunPaths } from "./runPaths.js";
 import { writeSummary } from "./summarize.js";
 import { runVerify } from "./verify.js";
-import { git, pathExists } from "./utils.js";
+import { ensureDir, git, pathExists } from "./utils.js";
+const booleanArgs = new Set(["dry", "json", "live", "no-integration"]);
 function parseArgs(argv) {
     const [command = "help", ...rest] = argv;
-    const args = {};
+    const args = { _: [] };
     for (let i = 0; i < rest.length; i += 1) {
         const item = rest[i];
-        if (!item.startsWith("--"))
+        if (!item.startsWith("--")) {
+            args._.push(item);
             continue;
+        }
         const key = item.slice(2);
         const next = rest[i + 1];
-        if (!next || next.startsWith("--"))
+        if (booleanArgs.has(key) || !next || next.startsWith("--"))
             args[key] = true;
         else {
             args[key] = next;
@@ -32,24 +44,48 @@ function parseArgs(argv) {
 function usage() {
     return `AI Dev Harness
 
-Usage:
+用法:
   harness init
-  harness run --task <text> --skill <name> --agent <codex|claude>
-  harness run --task <text> --skill <name> --agent <codex|claude> --live
+  harness init --no-integration
+  harness doctor
+  harness smoke --agent <codex|claude|cursor|gemini> [--live]
+  harness run --task <text> --skill <name> --agent <codex|claude|cursor|gemini>
+  harness run --task <text> --skill <name> --agent <codex|claude|cursor|gemini> --live
   harness verify --run <run_id_or_path>
   harness summarize --run <run_id_or_path>
-  harness install-integration --agent <claude|codex|both> [--target <repo>] [--command <harness command>]
+  harness restore --run <run_id_or_path> --iteration <n>
+  harness runs metrics [--json]
+  harness replay --run <run_id_or_path> [--dry] [--agent <codex|claude|cursor|gemini>]
+  harness install-integration --agent <claude|codex|cursor|gemini|both|all> [--target <repo>] [--command <harness command>]
 `;
 }
+async function commandDoctor(cwd) {
+    const config = await loadConfig(cwd);
+    const result = await runDoctor(cwd, config);
+    console.log(result.text);
+    if (result.failed)
+        throw new Error("doctor 检查失败，请先修复 FAIL 项。");
+}
+async function commandSmoke(cwd, args) {
+    const agentName = requireAgent(requireString(args, "agent"));
+    const live = Boolean(args.live);
+    await commandRun(cwd, {
+        task: "Smoke test only. Analyze repository context and do not modify repository files.",
+        skill: "update_docs",
+        agent: agentName,
+        live
+    });
+}
 function requireString(args, key) {
     const value = args[key];
     if (typeof value !== "string" || !value.trim())
-        throw new Error(`Missing required --${key}`);
+        throw new Error(`缺少必填参数 --${key}`);
     return value;
 }
 function requireAgent(value) {
-    if (value !== "codex" && value !== "claude")
-        throw new Error(`Invalid agent: ${value}. Expected codex or claude.`);
+    if (value !== "codex" && value !== "claude" && value !== "cursor" && value !== "gemini") {
+        throw new Error(`无效 agent：${value}。期望 codex、claude、cursor 或 gemini。`);
+    }
     return value;
 }
 function quoteCommandPath(filePath) {
@@ -63,17 +99,49 @@ async function resolveRunDir(cwd, runArg) {
     const underAudit = path.join(cwd, config.audit.path, runArg);
     if (await pathExists(underAudit))
         return underAudit;
-    throw new Error(`Run not found: ${runArg}`);
+    throw new Error(`未找到运行记录：${runArg}`);
 }
 async function commandInit(cwd) {
-    const result = await initHarness(cwd);
-    console.log(`Initialized AI Dev Harness in ${cwd}`);
-    console.log(`Created ${result.created.length} file(s), skipped ${result.skipped.length} existing file(s).`);
+    const packageRoot = path.resolve(path.dirname(process.argv[1]), "..");
+    const result = await initHarness(cwd, packageRoot);
+    console.log(`AI Dev Harness 初始化完成：${cwd}`);
+    console.log(`创建 ${result.created.length} 个文件，跳过 ${result.skipped.length} 个已存在文件。`);
+    if (process.argv.includes("--no-integration")) {
+        console.log("已跳过 Agent 对话集成。");
+        return;
+    }
+    const harnessCliPath = path.resolve(process.argv[1]);
+    const harnessCommand = `node ${quoteCommandPath(harnessCliPath)}`;
+    const integration = await installIntegration({ targetDir: cwd, harnessCommand, harnessCliPath, agent: "all", packageRoot });
+    console.log("Claude/Codex/Cursor/Gemini 对话集成已安装。");
+    console.log(`集成创建：${integration.created.length ? integration.created.join(", ") : "无"}`);
+    console.log(`集成更新：${integration.updated.length ? integration.updated.join(", ") : "无"}`);
+    console.log(`集成跳过：${integration.skipped.length ? integration.skipped.join(", ") : "无"}`);
 }
 function sayLive(live, message) {
     if (live)
         console.log(`[harness] ${message}`);
 }
+async function copyIfExists(from, to) {
+    if (await pathExists(from))
+        await copyFile(from, to);
+}
+async function syncIterationSnapshot(paths, iterationPaths) {
+    await copyIfExists(iterationPaths.contextPack, paths.contextPack);
+    await copyIfExists(iterationPaths.agentPrompt, paths.agentPrompt);
+    await copyIfExists(iterationPaths.plan, paths.plan);
+    await copyIfExists(iterationPaths.executionLog, paths.executionLog);
+    await copyIfExists(iterationPaths.agentContract, paths.agentContract);
+    await copyIfExists(iterationPaths.gitDiff, paths.gitDiff);
+    await copyIfExists(iterationPaths.verify, paths.verify);
+    await copyIfExists(iterationPaths.verifyDiagnostics, paths.verifyDiagnostics);
+    await copyIfExists(iterationPaths.contextScore, paths.contextScore);
+    await copyIfExists(iterationPaths.approvalRequired, paths.approvalRequired);
+    await copyIfExists(iterationPaths.feedback, paths.feedback);
+    await copyIfExists(iterationPaths.checkpoint, paths.checkpoint);
+    await copyIfExists(iterationPaths.preIterationDiff, paths.preIterationDiff);
+    await copyIfExists(iterationPaths.postIterationDiff, paths.postIterationDiff);
+}
 async function commandRun(cwd, args) {
     const task = requireString(args, "task");
     const skillName = requireString(args, "skill");
@@ -84,8 +152,8 @@ async function commandRun(cwd, args) {
     const paths = makeRunPaths(cwd, config, task);
     await prepareRunFiles(paths);
     const audit = new AuditLogger(paths.audit);
-    sayLive(live, `run started: skill=${skillName} agent=${agentName}`);
-    sayLive(live, `evidence directory: ${paths.runDir}`);
+    sayLive(live, `运行开始：skill=${skillName} agent=${agentName}`);
+    sayLive(live, `证据目录：${paths.runDir}`);
     await audit.event({ stage: "intake", event: "run_started", status: "started", detail: { task, skill: skillName, agent: agentName } });
     const isGitRepo = Boolean(await git(cwd, "rev-parse --show-toplevel"));
     const intake = {
@@ -103,81 +171,190 @@ async function commandRun(cwd, args) {
             stage: "intake",
             event: "git_repo_check",
             status: "failed",
-            detail: "Current directory is not a Git repository. Run inside a business Git repository before executing harness run."
+            detail: "当前目录不是 Git 仓库。请在业务 Git 仓库内执行 harness run。"
         });
         await audit.event({ stage: "run", event: "run_finished", status: "failed" });
-        throw new Error(`harness run must execute inside a Git repository. Evidence: ${paths.runDir}`);
+        throw new Error(`harness run 必须在 Git 仓库内执行。证据目录：${paths.runDir}`);
     }
-    sayLive(live, "building context pack with MCP first, local fallback second");
-    await audit.event({ stage: "context_pack", event: "build_started", status: "started" });
-    const contextPack = await buildContextPack({
-        cwd,
-        task,
-        config,
-        skill,
-        contextPackPath: paths.contextPack,
-        mcpLogPath: paths.mcpQueries,
-        audit
-    });
-    await audit.event({
-        stage: "context_pack",
-        event: "build_finished",
-        status: contextPack.degraded ? "degraded" : "succeeded"
-    });
-    sayLive(live, `context pack ${contextPack.degraded ? "degraded" : "ready"}: ${paths.contextPack}`);
-    const plan = `# Execution Plan
-
-The selected agent must:
-1. Read the context pack.
-2. Produce impact analysis.
-3. Make the smallest safe change.
-4. Leave enough evidence for review.
-5. Allow the harness to run verification and summarize results.
-`;
-    await writeFile(paths.plan, plan, "utf8");
-    await audit.event({ stage: "plan", event: "plan_written", status: "succeeded", detail: { path: paths.plan } });
-    sayLive(live, `plan written: ${paths.plan}`);
     const adapter = createAgentAdapter(agentName, config);
-    const agentCommand = agentName === "codex" ? config.agents.codex.command : config.agents.claude.command;
-    sayLive(live, `executing ${adapter.name}: ${agentCommand}`);
-    await audit.event({ stage: "execute", event: "agent_started", status: "started", detail: { agent: adapter.name, command: agentCommand } });
-    let agentResult;
-    try {
-        agentResult = await adapter.run({
+    const agentCommand = config.agents[agentName].command;
+    const maxIterations = Math.max(1, config.loop.maxIterations);
+    const evaluations = [];
+    let previousFeedback;
+    let agentResult = {
+        status: "failed",
+        exitCode: null,
+        stdout: "",
+        stderr: "",
+        changedFiles: [],
+        diff: "",
+        error: "Agent 未运行"
+    };
+    let verifyResult = { status: "skipped", commands: [] };
+    let contractCheck = { status: "failed", requiredSections: [], missingSections: [] };
+    let verifyDiagnostics;
+    let contextScore;
+    let approval;
+    for (let iteration = 1; iteration <= maxIterations; iteration += 1) {
+        const iterationPaths = makeIterationPaths(paths, iteration);
+        await ensureDir(iterationPaths.iterationDir);
+        await writeFile(iterationPaths.feedback, "", "utf8");
+        const checkpoint = await createCheckpoint({
+            cwd,
+            iteration,
+            checkpointPath: iterationPaths.checkpoint,
+            preDiffPath: iterationPaths.preIterationDiff,
+            runDir: paths.runDir
+        });
+        await feedbackEvent(iterationPaths.feedback, "checkpoint_created", { iteration, restoreSupported: checkpoint.restoreSupported });
+        sayLive(live, `正在构建 Context Pack（自纠偏循环 ${iteration}/${maxIterations}）`);
+        await audit.event({ stage: "context_pack", event: "build_started", status: "started", detail: { iteration } });
+        await buildContextPack({
             cwd,
             task,
+            config,
             skill,
-            contextPackPath: paths.contextPack,
-            promptPath: paths.agentPrompt,
-            executionLogPath: paths.executionLog,
-            live
+            contextPackPath: iterationPaths.contextPack,
+            mcpLogPath: paths.mcpQueries,
+            audit
+        });
+        await feedbackEvent(iterationPaths.feedback, "context_pack_created", { iteration, path: iterationPaths.contextPack });
+        await audit.event({
+            stage: "context_pack",
+            event: "build_finished",
+            status: "succeeded",
+            detail: { iteration }
         });
+        sayLive(live, `Context Pack 已生成：${iterationPaths.contextPack}`);
+        const plan = `# 执行阶段协议
+
+## 当前轮次
+${iteration}/${maxIterations}
+
+Agent 必须：
+1. 阅读 context_pack.md。
+2. 按固定格式输出影响分析。
+3. 制定最小修改计划。
+4. 执行最小安全变更。
+5. 说明验证计划和残余风险。
+6. 让 Harness 运行验证并生成总结。
+7. 如果上一轮失败，只围绕失败原因做最小 rework。
+`;
+        await writeFile(iterationPaths.plan, plan, "utf8");
+        await audit.event({ stage: "plan", event: "plan_written", status: "succeeded", detail: { path: iterationPaths.plan, iteration } });
+        sayLive(live, `阶段协议已写入：${iterationPaths.plan}`);
+        sayLive(live, `正在执行 ${adapter.name}：${agentCommand}`);
+        await feedbackEvent(iterationPaths.feedback, "agent_invoked", { iteration, agent: adapter.name });
         await audit.event({
             stage: "execute",
-            event: "agent_finished",
-            status: agentResult.status === "success" ? "succeeded" : "failed",
-            detail: { exitCode: agentResult.exitCode, changedFiles: agentResult.changedFiles, error: agentResult.error }
+            event: "agent_started",
+            status: "started",
+            detail: { agent: adapter.name, command: agentCommand, iteration }
         });
-    }
-    catch (error) {
-        agentResult = {
-            status: "failed",
-            exitCode: null,
-            stdout: "",
-            stderr: "",
-            changedFiles: [],
-            diff: "",
-            error: error instanceof Error ? error.message : String(error)
+        try {
+            agentResult = await adapter.run({
+                cwd,
+                task,
+                skill,
+                contextPackPath: iterationPaths.contextPack,
+                promptPath: iterationPaths.agentPrompt,
+                executionLogPath: iterationPaths.executionLog,
+                live,
+                iteration,
+                previousFeedback
+            });
+            await audit.event({
+                stage: "execute",
+                event: "agent_finished",
+                status: agentResult.status === "success" ? "succeeded" : "failed",
+                detail: { iteration, exitCode: agentResult.exitCode, changedFiles: agentResult.changedFiles, error: agentResult.error }
+            });
+        }
+        catch (error) {
+            agentResult = {
+                status: "failed",
+                exitCode: null,
+                stdout: "",
+                stderr: "",
+                changedFiles: [],
+                diff: "",
+                error: error instanceof Error ? error.message : String(error)
+            };
+            await audit.event({ stage: "execute", event: "agent_error", status: "failed", detail: { iteration, error: agentResult.error } });
+        }
+        await writeFile(iterationPaths.gitDiff, agentResult.diff, "utf8");
+        contractCheck = checkAgentContract(`${agentResult.stdout}\n${agentResult.stderr}`);
+        await writeJson(iterationPaths.agentContract, contractCheck);
+        await feedbackEvent(iterationPaths.feedback, "agent_contract_checked", { iteration, status: contractCheck.status, missingSections: contractCheck.missingSections });
+        await audit.event({
+            stage: "execute",
+            event: "agent_contract_check",
+            status: contractCheck.status === "passed" ? "succeeded" : "failed",
+            detail: { iteration, contractCheck }
+        });
+        sayLive(live, `Agent 执行完成：status=${agentResult.status} changedFiles=${agentResult.changedFiles.length} contract=${contractCheck.status}`);
+        sayLive(live, "正在运行验证命令");
+        await audit.event({ stage: "verify", event: "verify_started", status: "started", detail: { iteration } });
+        verifyResult = await runVerify(cwd, config, skill, iterationPaths.verify);
+        verifyDiagnostics = await writeVerifyDiagnostics(iterationPaths.verifyDiagnostics, verifyResult);
+        await feedbackEvent(iterationPaths.feedback, "verify_command_finished", { iteration, status: verifyResult.status });
+        await feedbackEvent(iterationPaths.feedback, "verify_diagnostics_created", { iteration, failedCommands: verifyDiagnostics.failedCommands.length });
+        await audit.event({
+            stage: "verify",
+            event: "verify_finished",
+            status: verifyResult.status === "passed" ? "succeeded" : "failed",
+            detail: { iteration, verifyResult }
+        });
+        sayLive(live, `验证完成：${verifyResult.status} ${iterationPaths.verify}`);
+        const agentOutput = `${agentResult.stdout}\n${agentResult.stderr}`;
+        contextScore = await writeContextScore(iterationPaths.contextScore, agentOutput);
+        await feedbackEvent(iterationPaths.feedback, "context_score_created", { iteration, status: contextScore.status, missing: contextScore.missing });
+        approval = await evaluateApprovalGate({
+            cwd,
+            config,
+            agentResult,
+            agentOutput,
+            approvalPath: iterationPaths.approvalRequired
+        });
+        if (approval.required)
+            await feedbackEvent(iterationPaths.feedback, "approval_gate_triggered", { iteration, reasons: approval.reasons });
+        agentResult.diff = await writePostIterationDiff(cwd, iterationPaths.postIterationDiff);
+        await writeFile(iterationPaths.gitDiff, agentResult.diff, "utf8");
+        const evaluation = evaluateIteration({
+            iteration,
+            maxIterations,
+            previous: evaluations.at(-1),
+            agentResult,
+            contractCheck,
+            verifyResult,
+            verifyDiagnostics,
+            contextScore,
+            approval
+        });
+        evaluations.push(evaluation);
+        const loopReview = {
+            status: evaluation.status === "passed" ? "passed" : "stopped",
+            maxIterations,
+            iterations: evaluations
         };
-        await audit.event({ stage: "execute", event: "agent_error", status: "failed", detail: agentResult.error });
+        await writeLoopArtifacts({ reviewPath: paths.loopReview, reportPath: paths.loopReport, review: loopReview });
+        await audit.event({
+            stage: "evaluate",
+            event: "iteration_evaluated",
+            status: evaluation.status === "passed" ? "succeeded" : "failed",
+            detail: evaluation
+        });
+        await feedbackEvent(iterationPaths.feedback, "loop_evaluated", { iteration, status: evaluation.status, failureType: evaluation.failureType });
+        await syncIterationSnapshot(paths, iterationPaths);
+        sayLive(live, `评估完成：${evaluation.status} failure=${evaluation.failureType}`);
+        if (evaluation.nextAction === "summarize")
+            break;
+        if (evaluation.nextAction === "stop")
+            break;
+        previousFeedback = renderReworkFeedback(evaluation);
+        await audit.event({ stage: "rework", event: "rework_scheduled", status: "started", detail: evaluation });
+        sayLive(live, `进入下一轮自纠偏：${evaluation.reason}`);
     }
-    await writeFile(paths.gitDiff, agentResult.diff, "utf8");
-    sayLive(live, `agent finished: status=${agentResult.status} changedFiles=${agentResult.changedFiles.length}`);
-    sayLive(live, "running verification commands");
-    await audit.event({ stage: "verify", event: "verify_started", status: "started" });
-    const verifyResult = await runVerify(cwd, config, skill, paths.verify);
-    await audit.event({ stage: "verify", event: "verify_finished", status: verifyResult.status === "passed" ? "succeeded" : "failed", detail: verifyResult });
-    sayLive(live, `verification ${verifyResult.status}: ${paths.verify}`);
     await writeSummary({
         task,
         skillName,
@@ -190,28 +367,30 @@ The selected agent must:
     });
     await audit.event({ stage: "summarize", event: "summary_written", status: "succeeded" });
     await audit.event({ stage: "persist", event: "suggestions_written", status: "succeeded" });
-    sayLive(live, `summary written: ${paths.summary}`);
-    sayLive(live, `persist suggestions written: ${paths.persistSuggestions}`);
-    const runPassed = verifyResult.status === "passed" && agentResult.status === "success";
+    sayLive(live, `总结已写入：${paths.summary}`);
+    sayLive(live, `知识沉淀建议已写入：${paths.persistSuggestions}`);
+    sayLive(live, `自纠偏报告已写入：${paths.loopReport}`);
+    const runPassed = evaluations.at(-1)?.status === "passed";
     await audit.event({ stage: "run", event: "run_finished", status: runPassed ? "succeeded" : "failed" });
-    console.log(`Run complete: ${paths.runId}`);
-    console.log(`Evidence: ${paths.runDir}`);
+    console.log(`运行完成：${paths.runId}`);
+    console.log(`证据目录：${paths.runDir}`);
     if (!runPassed)
-        throw new Error(`Harness run failed. Evidence: ${paths.runDir}`);
+        throw new Error(`Harness 运行失败。证据目录：${paths.runDir}`);
 }
 async function commandInstallIntegration(cwd, args) {
     const rawAgent = String(args.agent ?? "both");
-    if (rawAgent !== "claude" && rawAgent !== "codex" && rawAgent !== "both") {
-        throw new Error(`Invalid --agent ${rawAgent}. Expected claude, codex, or both.`);
+    if (rawAgent !== "claude" && rawAgent !== "codex" && rawAgent !== "cursor" && rawAgent !== "gemini" && rawAgent !== "both" && rawAgent !== "all") {
+        throw new Error(`无效 --agent ${rawAgent}。期望 claude、codex、cursor、gemini、both 或 all。`);
     }
     const targetDir = typeof args.target === "string" ? path.resolve(cwd, args.target) : cwd;
     const packageRoot = path.resolve(path.dirname(process.argv[1]), "..");
-    const harnessCommand = typeof args.command === "string" ? args.command : `node ${quoteCommandPath(path.resolve(process.argv[1]))}`;
-    const result = await installIntegration({ targetDir, harnessCommand, agent: rawAgent, packageRoot });
-    console.log(`Installed AI Dev Harness conversation integration in ${targetDir}`);
-    console.log(`Created: ${result.created.length ? result.created.join(", ") : "(none)"}`);
-    console.log(`Updated: ${result.updated.length ? result.updated.join(", ") : "(none)"}`);
-    console.log(`Skipped: ${result.skipped.length ? result.skipped.join(", ") : "(none)"}`);
+    const harnessCliPath = path.resolve(process.argv[1]);
+    const harnessCommand = typeof args.command === "string" ? args.command : `node ${quoteCommandPath(harnessCliPath)}`;
+    const result = await installIntegration({ targetDir, harnessCommand, harnessCliPath, agent: rawAgent, packageRoot });
+    console.log(`AI Dev Harness 对话集成已安装：${targetDir}`);
+    console.log(`创建：${result.created.length ? result.created.join(", ") : "无"}`);
+    console.log(`更新：${result.updated.length ? result.updated.join(", ") : "无"}`);
+    console.log(`跳过：${result.skipped.length ? result.skipped.join(", ") : "无"}`);
 }
 async function commandVerify(cwd, args) {
     const runDir = await resolveRunDir(cwd, requireString(args, "run"));
@@ -219,9 +398,47 @@ async function commandVerify(cwd, args) {
     const config = await loadConfig(cwd);
     const skill = await loadSkill(cwd, intake.skill);
     const result = await runVerify(cwd, config, skill, path.join(runDir, "verify.json"));
+    await writeVerifyDiagnostics(path.join(runDir, "verify_diagnostics.json"), result);
     const audit = new AuditLogger(path.join(runDir, "audit.jsonl"));
     await audit.event({ stage: "verify", event: "verify_rerun", status: result.status === "passed" ? "succeeded" : "failed", detail: result });
-    console.log(`Verify ${result.status}: ${runDir}`);
+    console.log(`验证 ${result.status}：${runDir}`);
+}
+async function commandRestore(cwd, args) {
+    const runDir = await resolveRunDir(cwd, requireString(args, "run"));
+    const iteration = Number(requireString(args, "iteration"));
+    if (!Number.isInteger(iteration) || iteration < 1)
+        throw new Error("--iteration 必须是正整数");
+    const checkpointPath = path.join(runDir, `iteration-${iteration}`, "checkpoint.json");
+    if (!(await pathExists(checkpointPath)))
+        throw new Error(`未找到 checkpoint：${checkpointPath}`);
+    const checkpoint = JSON.parse(await readFile(checkpointPath, "utf8"));
+    const result = await restoreCheckpoint(cwd, checkpoint);
+    const audit = new AuditLogger(path.join(runDir, "audit.jsonl"));
+    await audit.event({ stage: "restore", event: "restore_requested", status: result.ok ? "succeeded" : "failed", detail: { iteration, message: result.message } });
+    console.log(result.message);
+    if (!result.ok)
+        throw new Error(`restore 失败：${result.message}`);
+}
+async function commandRuns(cwd, args) {
+    const [subcommand] = args._ ?? [];
+    if (subcommand !== "metrics")
+        throw new Error(`未知 runs 子命令：${subcommand ?? ""}`);
+    const config = await loadConfig(cwd);
+    const metrics = await collectRunMetrics(cwd, config);
+    if (args.json)
+        console.log(JSON.stringify(metrics, null, 2));
+    else
+        console.log(renderMetricsText(metrics));
+}
+async function commandReplay(cwd, args) {
+    const runDir = await resolveRunDir(cwd, requireString(args, "run"));
+    const overrideAgent = typeof args.agent === "string" ? requireAgent(args.agent) : undefined;
+    const dry = Boolean(args.dry);
+    const plan = await buildReplayPlan(runDir, overrideAgent, dry);
+    console.log(renderReplayPlan(plan));
+    if (dry)
+        return;
+    await commandRun(cwd, { task: plan.task, skill: plan.skill, agent: plan.agent });
 }
 async function commandSummarize(cwd, args) {
     const runDir = await resolveRunDir(cwd, requireString(args, "run"));
@@ -252,7 +469,7 @@ async function commandSummarize(cwd, args) {
     });
     const audit = new AuditLogger(path.join(runDir, "audit.jsonl"));
     await audit.event({ stage: "summarize", event: "summary_rerun", status: "succeeded" });
-    console.log(`Summary refreshed: ${runDir}`);
+    console.log(`总结已刷新：${runDir}`);
 }
 async function main() {
     const cwd = process.cwd();
@@ -263,15 +480,25 @@ async function main() {
     }
     if (command === "init")
         return commandInit(cwd);
+    if (command === "doctor")
+        return commandDoctor(cwd);
+    if (command === "smoke")
+        return commandSmoke(cwd, args);
     if (command === "run")
         return commandRun(cwd, args);
     if (command === "verify")
         return commandVerify(cwd, args);
     if (command === "summarize")
         return commandSummarize(cwd, args);
+    if (command === "restore")
+        return commandRestore(cwd, args);
+    if (command === "runs")
+        return commandRuns(cwd, args);
+    if (command === "replay")
+        return commandReplay(cwd, args);
     if (command === "install-integration")
         return commandInstallIntegration(cwd, args);
-    throw new Error(`Unknown command: ${command}\n${usage()}`);
+    throw new Error(`未知命令：${command}\n${usage()}`);
 }
 main().catch((error) => {
     console.error(error instanceof Error ? error.message : String(error));