ai-dev-harness 0.1.1 → 0.1.2

package/README.md

@@ -1,6 +1,6 @@
 # AI Dev Harness
 
-AI Dev Harness 是一个可分发的 TypeScript CLI，用来把 Claude Code / Codex 的研发任务变成可审计的执行闭环。
+AI Dev Harness 是一个可分发的 TypeScript CLI，用来把 Codex、Claude Code、Cursor Agent、Gemini CLI 的研发任务变成可审计的执行闭环。
 
 它的核心定位不是替代 Agent，也不是实现 MCP Client，而是：
 
@@ -8,7 +8,7 @@ AI Dev Harness 是一个可分发的 TypeScript CLI，用来把 Claude Code / Co
 
 ## 核心边界
 
-- Claude / Codex 负责：理解任务、调用 MCP、调用工具、使用 Skill、修改代码。
+- Codex / Claude / Cursor / Gemini 负责：理解任务、调用 MCP、调用工具、使用 Skill、修改代码。
 - Harness 负责：执行闭环、过程日志、验证命令、审计证据、总结、沉淀建议。
 - CodeGraph / Knowledge Graph 是 Agent 侧 MCP 工具源，不是 Harness 内部服务依赖。
 - Harness 会记录 MCP source metadata，但不会记录 bearer token 原文。
@@ -16,12 +16,13 @@ AI Dev Harness 是一个可分发的 TypeScript CLI，用来把 Claude Code / Co
 ## 包内容
 
 - CLI：`dist/cli.js`
-- Claude/Codex 对话集成安装器
+- Claude/Codex/Cursor/Gemini 对话集成安装器
 - Claude Skill：`.claude/skills/ai-dev-harness/`
 - Agent 辅助脚本：`.harness/ai-dev-harness/scripts/`
 - Git-native 项目技能：`skills/`
 - 可编辑模板：`templates/`
 
+线上安装使用手册见 `ONLINE_INSTALL_GUIDE.md`。
 同事试用手册见 `COLLEAGUE_TRIAL_GUIDE.md`。
 
 ## 快速开始
@@ -30,7 +31,8 @@ AI Dev Harness 是一个可分发的 TypeScript CLI，用来把 Claude Code / Co
 npm install
 npm run build
 node dist/cli.js init
-node dist/cli.js run --task "fix a small bug" --skill fix_bug --agent codex
+node dist/cli.js doctor
+node dist/cli.js smoke --agent codex --live
 ```
 
 CLI 应在业务 Git 仓库内初始化。`init` 会创建 `harness.yaml`、`skills/`、`AGENTS.md`、`TOOLS.md`、`SKILLS.md` 和 `runs/`。
@@ -40,29 +42,39 @@ CLI 应在业务 Git 仓库内初始化。`init` 会创建 `harness.yaml`、`ski
 ```bash
 node dist/cli.js init
 node dist/cli.js init --no-integration
+node dist/cli.js doctor
+node dist/cli.js smoke --agent claude --live
 node dist/cli.js run --task "add refund flow tests" --skill write_tests --agent claude
 node dist/cli.js run --task "analyze download startup flow. Do not modify repository files." --skill update_docs --agent claude --live
+node dist/cli.js run --task "fix a small bug" --skill fix_bug --agent cursor --live
+node dist/cli.js run --task "fix a small bug" --skill fix_bug --agent gemini --live
 node dist/cli.js verify --run <run_id_or_path>
 node dist/cli.js summarize --run <run_id_or_path>
-node dist/cli.js install-integration --agent both --target <repo>
+node dist/cli.js restore --run <run_id_or_path> --iteration 1
+node dist/cli.js runs metrics --json
+node dist/cli.js replay --run <run_id_or_path> --dry
+node dist/cli.js replay --run <run_id_or_path> --agent codex
+node dist/cli.js install-integration --agent all --target <repo>
 ```
 
-## Claude/Codex 对话触发
+## Claude/Codex/Cursor/Gemini 对话触发
 
 `harness init` 默认安装对话集成。也可以手动刷新：
 
 ```bash
-node "E:\ai native\dist\cli.js" install-integration --agent both --target "C:\path\to\repo"
+node "E:\ai native\dist\cli.js" install-integration --agent all --target "C:\path\to\repo"
 ```
 
 它会创建：
 
 - `.claude/skills/ai-dev-harness/SKILL.md`
 - `AGENTS.md` 中的 Harness 规则块
+- `.cursor/rules/ai-dev-harness.mdc`
+- `GEMINI.md` 中的 Harness 规则块
 - `.harness/ai-dev-harness/scripts/run-harness.ps1`
 - `.harness/ai-dev-harness/scripts/read-evidence.ps1`
 
-然后在 Claude Code 或 Codex 中自然提问：
+然后在 Claude Code、Codex、Cursor 或 Gemini 中自然提问：
 
 ```text
 Use AI Dev Harness to run update_docs: analyze the download startup flow. Do not modify repository files.
@@ -80,22 +92,49 @@ Use Harness to run fix_bug: fix the download resume progress issue.
 
 Harness 不直接调用 MCP。Agent 应在触发 Harness 前使用自己已配置的 MCP 工具，并按以下格式汇报：
 
+如果 CodeGraph 使用的是 `colbymchenry/codegraph`，默认优先调用 `codegraph_explore`。用任务里的业务流程、文件路径、函数/类/符号名或错误现象作为 query，并重点读取它返回的 grouped source、line-numbered source、call paths、dynamic dispatch hops 和 blast-radius summary。
+
+如果 Knowledge Graph 使用的是 `browser_knowledge_service`，推荐读取顺序：
+
+1. 用 `list_path`、`search_docs`、`search_sections`、`search_chunks` 缩小范围。
+2. RAG 场景优先用 `answer_context`；需要自控排序时用 `hybrid_search`。
+3. 定位 concept_id 后先用 `read_doc_outline` 看结构。
+4. 再用 `read_section`、`read_doc_range`、`read_chunk`、`get_related_chunks` 精读证据。
+5. 需要关系时用 `get_backlinks`，需要近期变更记录时用 `get_audit_log`。
+6. v1 不直接调用 `propose_doc` 写入知识库；只生成 `persist_suggestions.md`。
+
 ```text
 ## MCP Preflight Findings
 - CodeGraph tools used:
-- Related files:
-- Related symbols:
-- Callers / dependencies:
-- Impact scope:
+- CodeGraph primary query:
+- Source grouped by file:
+- Current line-numbered source:
+- Call paths:
+- Dynamic dispatch hops:
+- Blast-radius summary:
 - Knowledge Graph tools used:
+- Candidate concept_ids:
+- Read tools used:
+- Evidence sections/chunks:
 - ADRs / decisions:
 - Module notes:
 - API notes / runbooks:
+- Audit/backlink findings:
 - Missing context:
 ```
 
 关键 MCP 发现应被带入 Harness 的任务文本，进入审计证据。
 
+## OKF 知识沉淀
+
+`persist_suggestions.md` 按 PC 浏览器团队知识库规范生成 OKF 候选内容，不自动写入 Knowledge Graph。
+
+- 候选文档路径应落到 `/<project>/overview/`、`/<project>/features/`、`/<project>/metrics/`、`/<project>/api/`、`/<project>/playbooks/` 或 `/<project>/references/`。
+- 每个候选 concept 应包含 `type`、`title`、`description`、`tags`、`timestamp`；API/数据类建议补充 `resource`。
+- `## 相关` 必须使用有效 Markdown 链接，推荐 bundle 根相对路径。
+- `type: API Reference` 需要包含 `## 关键实现锚点` 和 `### Agent 使用建议`。
+- 合入知识库前应同步更新对应目录的 `index.md` 和 `log.md`，并人工检查敏感信息。
+
 ## 配置
 
 编辑业务仓库里的 `harness.yaml`：
@@ -106,6 +145,10 @@ agents:
     command: codex exec --full-auto -
   claude:
     command: claude -p -
+  cursor:
+    command: cursor-agent
+  gemini:
+    command: gemini
 mcp:
   codegraph:
     type: sse
@@ -123,10 +166,55 @@ verify:
       command: git status --short
 audit:
   path: runs
+loop:
+  maxIterations: 1
+  stopOn:
+    - same_failure_repeated
+    - max_iterations_reached
+policy:
+  protectedPaths:
+    - .github/
+    - scripts/release/
+    - security/
+  requireApproval:
+    - protected_path_change
+    - dependency_change
+    - delete_files
+    - public_api_change_declared
+    - security_change_declared
+  approvalMode: file
 ```
 
 MCP header 支持环境变量，例如 `${OKF_TOKEN}`。不要把真实 token 提交到 Git。
 
+`agents.*.command` 都可以按团队机器上的实际 CLI 改写。Harness 统一通过 stdin 把最终 prompt 传给执行器，不绑定 Codex、Claude、Cursor 或 Gemini 的内部能力。
+
+## 自纠偏循环
+
+Harness 会在每轮执行后进入 `Evaluate` 阶段，判断是否完成目标、Agent 契约是否满足、验证是否通过。
+
+默认 `loop.maxIterations: 1`，行为等同单轮执行。需要开启低风险自动重做时，在业务仓库 `harness.yaml` 中调大：
+
+```yaml
+loop:
+  maxIterations: 2
+  stopOn:
+    - same_failure_repeated
+    - max_iterations_reached
+```
+
+会自动进入下一轮的典型情况：
+
+- Agent 命令失败。
+- Agent 输出缺少 `Impact Analysis / Plan / Execution Notes / Verification Notes / Final Report`。
+- 验证命令失败。
+
+会停止并要求人工评审的典型情况：
+
+- 连续两轮出现同一种失败。
+- 达到最大循环轮次。
+- Agent 在报告里说明目标不明确、需要扩大范围、要改公共接口或安全策略。
+
 ## 运行证据
 
 每次 `run` 会创建 `runs/<run_id>/`：
@@ -134,12 +222,20 @@ MCP header 支持环境变量，例如 `${OKF_TOKEN}`。不要把真实 token
 - `intake.json`：任务、skill、agent、Git 状态。
 - `mcp_queries.jsonl`：Agent-driven MCP source metadata，不包含 token 原文。
 - `context_pack.md`：上下文组装协议、MCP source 记录、本地兜底上下文。
-- `agent_prompt.md`：发送给 Claude/Codex 的最终提示词。
+- `agent_prompt.md`：发送给当前执行器的最终提示词。
 - `plan.md`：Harness 执行阶段协议。
 - `execution.log`：Agent stdout/stderr。
 - `agent_contract.json`：Agent 必需章节检查结果。
 - `git_diff.patch`：代码变更。
 - `verify.json`：验证结果。
+- `verify_diagnostics.json`：从验证 stdout/stderr 提取的通用失败诊断。
+- `context_score.json`：Agent 是否按协议提供上下文证据的结构化评分。
+- `approval_required.json`：机械审批门禁结果。
+- `feedback.jsonl`：Harness 可见机器反馈事件，不记录 Agent 内部工具调用。
+- `checkpoint.json`：本轮 Git checkpoint 和 restore 支持状态。
+- `pre_iteration_diff.patch` / `post_iteration_diff.patch`：本轮前后 diff。
+- `loop_review.json`：每轮评估、失败归因和下一步动作。
+- `loop_report.md`：自纠偏循环的人类可读报告。
 - `summary.md`：评审/PR 总结。
 - `persist_suggestions.md`：知识沉淀建议。
 - `audit.jsonl`：完整审计事件流。
@@ -154,6 +250,43 @@ Harness 会检查 Agent 输出是否包含以下章节：
 
 检查结果写入 `agent_contract.json`，并记录到 `audit.jsonl`。
 
+每轮循环会额外生成 `iteration-<n>/` 子目录。根目录同名文件是最后一轮快照，方便旧脚本继续读取。
+
+## Checkpoint / Restore
+
+Harness 每轮开始记录 checkpoint。只有运行开始前工作区是 clean，才允许自动 restore：
+
+```bash
+node dist/cli.js restore --run <run_id_or_path> --iteration 1
+```
+
+如果运行前已有未提交改动，Harness 会拒绝自动恢复，避免覆盖用户手工改动。
+
+## Approval Gate
+
+Harness 只做机械门禁，不判断业务方案。默认会在以下情况写入 `approval_required.json` 并停止：
+
+- 命中 `policy.protectedPaths`。
+- 修改依赖文件，例如 `package.json`、lockfile。
+- 删除文件。
+- Agent 最终报告声明 `public_api_change_declared` 或 `security_change_declared`。
+
+## Metrics / Replay
+
+读取本地 `runs/` 证据生成运行指标：
+
+```bash
+node dist/cli.js runs metrics
+node dist/cli.js runs metrics --json
+```
+
+Replay 复用历史 run 的 task 和 skill，创建新的 run，不覆盖旧证据：
+
+```bash
+node dist/cli.js replay --run <run_id_or_path> --dry
+node dist/cli.js replay --run <run_id_or_path> --agent claude
+```
+
 ## Skill 规范
 
 内置 skill 会通过 `context.yaml` 告诉 Agent：
@@ -169,19 +302,21 @@ Harness 会检查 Agent 输出是否包含以下章节：
 mcp_preflight:
   codegraph:
     required: true
+    primary_tool: codegraph_explore
     ask_for:
-      - related_files
-      - related_symbols
-      - callers
-      - dependencies
-      - impact_scope
+      - relevant_source_grouped_by_file
+      - current_line_numbered_source_for_known_file_or_symbol
+      - call_paths_between_related_symbols
+      - dynamic_dispatch_hops
+      - blast_radius_summary
   knowledgeGraph:
     required: true
     ask_for:
-      - adr
-      - module_notes
-      - api_notes
-      - runbooks
+      - search_docs_or_search_chunks_for_defect_terms
+      - answer_context_for_direct_rag_context
+      - read_doc_outline_for_relevant_concepts
+      - read_section_or_read_doc_range_for_evidence
+      - get_backlinks_for_related_decisions
 stop_conditions:
   - root cause is unclear
   - impact scope cannot be determined

package/dist/agent.js

@@ -3,6 +3,9 @@ import { git, runCommand, truncate } from "./utils.js";
 function renderPrompt(input, contextPack) {
     return `你正在一个可审计的 AI 研发 Harness 中执行任务。请把它当作公司级研发任务，而不是随意聊天。
 
+当前循环轮次:
+${input.iteration ?? 1}
+
 任务:
 ${input.task}
 
@@ -31,7 +34,14 @@ ${input.skill.name}
    - 修改文件。
    - 已执行或延后的验证。
    - 残余风险。
-   - 知识沉淀建议。
+   - 知识沉淀建议。建议必须遵循 OKF v0.1 扩展：说明建议写入的项目目录、子域、type、title、description、相关 concept 链接、index.md/log.md 更新项；API 文档还要说明关键实现锚点和 Agent 使用建议。
+
+自纠偏规则:
+- 如果这是第 2 轮或更高轮次，先阅读上一轮失败诊断，只围绕失败原因做最小 rework。
+- 不要因为验证失败就绕过验证或删除验证。
+- 如果需要扩大范围、改公共接口、修改安全策略、或目标本身不明确，请停止并在 Final Report 中说明需要人工确认。
+
+${input.previousFeedback ? `上一轮反馈:\n${input.previousFeedback}\n` : ""}
 
 必须使用以下输出格式，标题不要改名:
 ## Impact Analysis
@@ -62,6 +72,19 @@ export function checkAgentContract(output) {
         missingSections
     };
 }
+function parseChangedFiles(status) {
+    return status
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((line) => {
+        const rename = line.match(/^R\s+(.+)\s+->\s+(.+)$/);
+        if (rename)
+            return rename[2];
+        return line.slice(3).trim();
+    })
+        .filter(Boolean);
+}
 async function executeAgent(input) {
     const contextPack = await readFile(input.contextPackPath, "utf8");
     const prompt = renderPrompt(input, contextPack);
@@ -73,9 +96,9 @@ async function executeAgent(input) {
         stderrPrefix: `[${input.agent}:stderr] `
     });
     await appendFile(input.executionLogPath, `## STDOUT\n${result.stdout}\n\n## STDERR\n${result.stderr}\n`, "utf8");
-    const changedFilesRaw = await git(input.cwd, "diff --name-only");
+    const changedFilesRaw = await git(input.cwd, "status --porcelain");
     const diff = await git(input.cwd, "diff --no-ext-diff");
-    const changedFiles = changedFilesRaw ? changedFilesRaw.split(/\r?\n/).filter(Boolean) : [];
+    const changedFiles = changedFilesRaw ? parseChangedFiles(changedFilesRaw) : [];
     return {
         status: result.exitCode === 0 ? "success" : "failed",
         exitCode: result.exitCode,
@@ -86,20 +109,11 @@ async function executeAgent(input) {
         error: result.exitCode === 0 ? undefined : `Agent command failed with exit code ${result.exitCode}`
     };
 }
-export class CodexAdapter {
-    command;
-    name = "codex";
-    constructor(command) {
-        this.command = command;
-    }
-    run(input) {
-        return executeAgent({ ...input, agent: this.name, command: this.command });
-    }
-}
-export class ClaudeAdapter {
+export class CliAgentAdapter {
+    name;
     command;
-    name = "claude";
-    constructor(command) {
+    constructor(name, command) {
+        this.name = name;
         this.command = command;
     }
     run(input) {
@@ -107,7 +121,5 @@ export class ClaudeAdapter {
     }
 }
 export function createAgentAdapter(agent, config) {
-    if (agent === "codex")
-        return new CodexAdapter(config.agents.codex.command);
-    return new ClaudeAdapter(config.agents.claude.command);
+    return new CliAgentAdapter(agent, config.agents[agent].command);
 }

package/dist/approval.js

@@ -0,0 +1,64 @@
+import { writeFile } from "node:fs/promises";
+import path from "node:path";
+import { git } from "./utils.js";
+function normalizeRel(file) {
+    return file.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+function matchesProtected(file, protectedPath) {
+    const normalized = normalizeRel(file);
+    const protectedNormalized = normalizeRel(protectedPath).replace(/\/?$/, "/");
+    return normalized === protectedNormalized.slice(0, -1) || normalized.startsWith(protectedNormalized);
+}
+function dependencyFile(file) {
+    const base = path.basename(file).toLowerCase();
+    return ["package.json", "package-lock.json", "yarn.lock", "pnpm-lock.yaml", "requirements.txt", "poetry.lock", "go.mod", "go.sum", "cargo.toml", "cargo.lock"].includes(base);
+}
+function declaredRisk(output, marker) {
+    return new RegExp(marker.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "i").test(output);
+}
+function deletedFilesFromNameStatus(nameStatus) {
+    return nameStatus
+        .split(/\r?\n/)
+        .filter((line) => line.startsWith("D\t"))
+        .map((line) => normalizeRel(line.slice(2)));
+}
+export async function evaluateApprovalGate(options) {
+    const changedFiles = options.agentResult.changedFiles.map(normalizeRel);
+    const unstagedNameStatus = await git(options.cwd, "diff --name-status");
+    const stagedNameStatus = await git(options.cwd, "diff --cached --name-status");
+    const deleted = Array.from(new Set([...deletedFilesFromNameStatus(unstagedNameStatus), ...deletedFilesFromNameStatus(stagedNameStatus)]));
+    const reasons = [];
+    const required = new Set(options.config.policy.requireApproval);
+    if (required.has("protected_path_change")) {
+        for (const file of changedFiles) {
+            const matched = options.config.policy.protectedPaths.find((protectedPath) => matchesProtected(file, protectedPath));
+            if (matched)
+                reasons.push({ type: "protected_path_change", detail: `${file} matches ${matched}` });
+        }
+    }
+    if (required.has("dependency_change")) {
+        for (const file of changedFiles.filter(dependencyFile))
+            reasons.push({ type: "dependency_change", detail: file });
+    }
+    if (required.has("delete_files")) {
+        for (const file of deleted)
+            reasons.push({ type: "delete_files", detail: file });
+    }
+    if (required.has("public_api_change_declared") && declaredRisk(options.agentOutput, "public_api_change_declared")) {
+        reasons.push({ type: "public_api_change_declared", detail: "Agent declared public API change." });
+    }
+    if (required.has("security_change_declared") && declaredRisk(options.agentOutput, "security_change_declared")) {
+        reasons.push({ type: "security_change_declared", detail: "Agent declared security change." });
+    }
+    const approval = {
+        required: reasons.length > 0,
+        reasons,
+        changedFiles,
+        mode: "file",
+        message: reasons.length
+            ? "Harness 已停止：本次变更触发审批门禁，请人工评审 approval_required.json。"
+            : "未触发审批门禁。"
+    };
+    await writeFile(options.approvalPath, `${JSON.stringify(approval, null, 2)}\n`, "utf8");
+    return approval;
+}

package/dist/audit.js

@@ -17,5 +17,6 @@ export async function prepareRunFiles(paths) {
     await ensureDir(paths.runDir);
     await writeJson(paths.intake, {});
     await writeFile(paths.mcpQueries, "", "utf8");
+    await writeFile(paths.feedback, "", "utf8");
     await writeFile(paths.audit, "", "utf8");
 }

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 恢复工作区，并清理本轮新增的未跟踪文件。" };
+}