minimal-agent 0.10.0 → 0.12.0

package/src/tools/shared/fileUtils.ts

@@ -0,0 +1,504 @@
+/**
+ * ============================================================
+ *  src/tools/shared/fileUtils.ts —— Read/Edit/Write 共享工具函数
+ * ------------------------------------------------------------
+ *  从 kakadeai 主仓库提炼的核心能力，剥离 UI/LSP/权限等高级层：
+ *    1. 设备文件路径拦截（防止 /dev/zero 等阻塞）
+ *    2. 路径安全校验 + 规范化（null byte / UNC / ~ 展开）
+ *    3. 行尾符检测与保持（CRLF vs LF）
+ *    4. 引号风格保留（弯引号 ↔ 直引号归一化）
+ * ============================================================
+ */
+
+import { randomUUID } from 'node:crypto';
+import { statSync } from 'node:fs';
+import { chmod, mkdir, open, readFile, rename, rm, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, extname, resolve } from 'node:path';
+
+import { getWorkingDir } from '../../bootstrap/workingDir.js';
+
+// -------------------- 1. 设备文件路径拦截 --------------------
+
+const BLOCKED_DEVICE_PATHS = new Set([
+  '/dev/zero',
+  '/dev/random',
+  '/dev/urandom',
+  '/dev/full',
+  '/dev/stdin',
+  '/dev/tty',
+  '/dev/console',
+  '/dev/stdout',
+  '/dev/stderr',
+  '/dev/fd/0',
+  '/dev/fd/1',
+  '/dev/fd/2',
+]);
+
+const WINDOWS_BLOCKED_NAMES = new Set(['NUL', 'CON', 'PRN', 'AUX', 'COM1', 'COM2', 'LPT1']);
+
+export function isBlockedDevicePath(filePath: string): boolean {
+  // 用 forward-slash 归一化：path.normalize 在 Windows 上会把 / 转成 \，
+  // 黑名单是 POSIX 字面量永远对不上，所以直接做反斜杠 → 正斜杠的归一化
+  const slashed = filePath.replaceAll('\\', '/');
+
+  if (BLOCKED_DEVICE_PATHS.has(slashed)) return true;
+
+  if (
+    slashed.startsWith('/proc/') &&
+    (slashed.endsWith('/fd/0') || slashed.endsWith('/fd/1') || slashed.endsWith('/fd/2'))
+  ) {
+    return true;
+  }
+
+  const baseName = slashed.split('/').pop() ?? '';
+  if (WINDOWS_BLOCKED_NAMES.has(baseName.toUpperCase())) {
+    return true;
+  }
+
+  return false;
+}
+
+// -------------------- 2. 路径安全校验 + 规范化 --------------------
+
+export type PathValidationResult =
+  | { ok: true; resolvedPath: string }
+  | { ok: false; error: string };
+
+export function validateAndResolvePath(
+  rawPath: string,
+  workingDir: string,
+): PathValidationResult {
+  if (rawPath.includes('\0')) {
+    return { ok: false, error: '路径包含非法字符（null byte）' };
+  }
+
+  // 在 resolve 之前先按原始路径检查设备文件：
+  // Windows 上 resolve('D:\\workdir', '/dev/zero') → 'D:\\dev\\zero'，已丢失 POSIX 语义
+  if (isBlockedDevicePath(rawPath)) {
+    return { ok: false, error: `不允许读取设备文件：${rawPath}。该路径可能产生无限输出或阻塞进程。` };
+  }
+
+  const expanded = expandPath(rawPath);
+  const resolved = resolve(workingDir, expanded);
+
+  // resolve 后再查一次（兜底 Windows 设备名如 NUL/CON 经 resolve 后仍能 baseName 命中）
+  if (isBlockedDevicePath(resolved)) {
+    return { ok: false, error: `不允许读取设备文件：${resolved}。该路径可能产生无限输出或阻塞进程。` };
+  }
+
+  if (process.platform === 'win32' && /^\\\\/.test(resolved)) {
+    return { ok: false, error: '不支持 UNC 路径（\\\\server\\share 格式），请使用本地路径' };
+  }
+
+  return { ok: true, resolvedPath: resolved };
+}
+
+function expandPath(p: string): string {
+  if (p.startsWith('~/') || p === '~') {
+    return resolve(homedir(), p.slice(2));
+  }
+  return p;
+}
+
+/**
+ * 工具入口便捷封装：自动以 getWorkingDir() 为锚点做路径规范化 + 安全校验。
+ * 等价于 `validateAndResolvePath(rawPath, getWorkingDir())`。
+ * 让 Read / Write / Edit / MultiEdit 不必各自 import getWorkingDir。
+ */
+export function resolveToolPath(rawPath: string, cwd = getWorkingDir()): PathValidationResult {
+  return validateAndResolvePath(rawPath, cwd);
+}
+
+// -------------------- 3. 行尾符检测与保持 --------------------
+
+export type LineEndingType = 'CRLF' | 'LF';
+
+export function detectLineEndingsForString(content: string): LineEndingType {
+  let crlfCount = 0;
+  let lfCount = 0;
+
+  for (let i = 0; i < content.length; i++) {
+    if (content[i] === '\n') {
+      if (i > 0 && content[i - 1] === '\r') {
+        crlfCount++;
+      } else {
+        lfCount++;
+      }
+    }
+  }
+
+  return crlfCount > lfCount ? 'CRLF' : 'LF';
+}
+
+export async function detectFileLineEndings(filePath: string): Promise<LineEndingType> {
+  try {
+    const handle = await readFile(filePath, { encoding: 'utf8' });
+    const head = handle.slice(0, 4096);
+    return detectLineEndingsForString(head);
+  } catch {
+    return 'LF';
+  }
+}
+
+export function applyLineEnding(content: string, ending: LineEndingType): string {
+  if (ending === 'CRLF') {
+    return content.replaceAll('\r\n', '\n').split('\n').join('\r\n');
+  }
+  return content;
+}
+
+// -------------------- 3.5 二进制扩展名拦截 --------------------
+
+// 上游 D:\code\kakadeai\constants\files.ts:5-112 BINARY_EXTENSIONS Set 的裁剪版：
+// 故意剔除 .log / .csv / .tsv / .dat / .data / .lock —— 这些经常被人当文本读。
+// 保留纯二进制：图片 / 文档 / 可执行 / 编译产物 / 压缩包 / 多媒体 / 字体 / 数据库 / wasm。
+export const BINARY_EXTENSIONS = new Set<string>([
+  '.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp', '.ico', '.tiff', '.tif',
+  '.pdf', '.doc', '.docx', '.xls', '.xlsx', '.ppt', '.pptx',
+  '.exe', '.dll', '.so', '.dylib', '.o', '.a',
+  '.pyc', '.pyo', '.class', '.jar',
+  '.zip', '.tar', '.gz', '.bz2', '.7z', '.rar', '.iso',
+  '.mp3', '.mp4', '.mov', '.avi', '.mkv', '.wav', '.flac', '.ogg',
+  '.ttf', '.otf', '.woff', '.woff2',
+  '.sqlite', '.sqlite3', '.db',
+  '.psd', '.ai', '.bin', '.wasm',
+]);
+
+export function hasBinaryExtension(filePath: string): boolean {
+  const ext = extname(filePath).toLowerCase();
+  return BINARY_EXTENSIONS.has(ext);
+}
+
+// -------------------- 3.7 自动 snapshot（Edit/MultiEdit 拦截路径用） --------------------
+
+/**
+ * 自动读取文件前 N 行作为 snippet，给 Edit/MultiEdit 在 assertFresh 拦截时注入到错误响应里。
+ *
+ * 双限制：
+ *   - SNAPSHOT_MAX_LINES = 200 行（防止小行长文件吃 context）
+ *   - SNAPSHOT_MAX_BYTES = 32KB（防止超长单行 minified 文件撑爆 context）
+ *   两个阈值任一命中都拒绝读全量。
+ *
+ * 失败 reason：
+ *   - 'binary'      → 命中二进制扩展名黑名单
+ *   - 'too-large'   → 文件 > 32KB（不读全文，让模型走显式 Read）
+ *   - 'unreadable'  → stat 或 read 失败
+ *
+ * 调用方负责：
+ *   1. 在拿到 ok=true 后调 recordRead(filePath, { truncated: snap.truncated })
+ *   2. 把 snippet 拼到 error 字符串里
+ *   3. ok=false 时根据 reason 给模型可读的 fallback 消息
+ */
+const SNAPSHOT_MAX_LINES = 200;
+const SNAPSHOT_MAX_BYTES = 32 * 1024;
+
+export type AutoSnapshotResult =
+  | { ok: true; snippet: string; truncated: boolean; totalLines: number }
+  | { ok: false; reason: 'too-large' | 'binary' | 'unreadable'; sizeBytes?: number };
+
+export async function tryAutoSnapshot(filePath: string): Promise<AutoSnapshotResult> {
+  // 1. 二进制扩展名拒绝
+  if (hasBinaryExtension(filePath)) {
+    return { ok: false, reason: 'binary' };
+  }
+
+  // 2. stat 拿大小
+  let sizeBytes: number;
+  try {
+    const st = statSync(filePath);
+    if (!st.isFile()) return { ok: false, reason: 'unreadable' };
+    sizeBytes = st.size;
+  } catch {
+    return { ok: false, reason: 'unreadable' };
+  }
+
+  // 3. 字节阈值
+  if (sizeBytes > SNAPSHOT_MAX_BYTES) {
+    return { ok: false, reason: 'too-large', sizeBytes };
+  }
+
+  // 4. 读全文（已知 <= 32KB）
+  let content: string;
+  try {
+    content = await readFile(filePath, 'utf8');
+  } catch {
+    return { ok: false, reason: 'unreadable' };
+  }
+
+  // 5. 行数阈值：超过 200 行截断
+  const allLines = content.split('\n');
+  const totalLines = allLines.length;
+  const truncated = totalLines > SNAPSHOT_MAX_LINES;
+  const lines = truncated ? allLines.slice(0, SNAPSHOT_MAX_LINES) : allLines;
+
+  // 拼带行号的 snippet（与 Read 工具输出风格一致）
+  const numbered = lines
+    .map((line, i) => `${String(i + 1).padStart(6, ' ')}\t${line}`)
+    .join('\n');
+
+  return { ok: true, snippet: numbered, truncated, totalLines };
+}
+
+// -------------------- 3.6 BOM 编码探测 --------------------
+
+export type FileBomEncoding = 'utf8' | 'utf8-bom' | 'utf16le';
+
+export interface TextFileSnapshot {
+  content: string;
+  encoding: FileBomEncoding;
+  lineEnding: LineEndingType;
+  bytes: Buffer;
+}
+
+/** Decode the text encodings that the editing tools can preserve losslessly. */
+export async function readTextFile(filePath: string): Promise<TextFileSnapshot> {
+  const bytes = await readFile(filePath);
+  let encoding: FileBomEncoding = 'utf8';
+  let content: string;
+  if (bytes.length >= 2 && bytes[0] === 0xff && bytes[1] === 0xfe) {
+    encoding = 'utf16le';
+    content = bytes.subarray(2).toString('utf16le');
+  } else if (bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf) {
+    encoding = 'utf8-bom';
+    content = bytes.subarray(3).toString('utf8');
+  } else {
+    content = bytes.toString('utf8');
+  }
+  return { content, encoding, lineEnding: detectLineEndingsForString(content), bytes };
+}
+
+export function encodeTextFile(content: string, encoding: FileBomEncoding): Buffer {
+  if (encoding === 'utf16le') {
+    return Buffer.concat([Buffer.from([0xff, 0xfe]), Buffer.from(content, 'utf16le')]);
+  }
+  if (encoding === 'utf8-bom') {
+    return Buffer.concat([Buffer.from([0xef, 0xbb, 0xbf]), Buffer.from(content, 'utf8')]);
+  }
+  return Buffer.from(content, 'utf8');
+}
+
+/** Write beside the destination, fsync, then replace it. Same-directory temp files keep rename atomic. */
+export async function atomicWriteFile(
+  filePath: string,
+  data: string | Uint8Array,
+  encoding: FileBomEncoding = 'utf8',
+): Promise<void> {
+  const parent = dirname(filePath);
+  await mkdir(parent, { recursive: true });
+  const temp = resolve(parent, `.${randomUUID()}.minimal-agent.tmp`);
+  const backup = resolve(parent, `.${randomUUID()}.minimal-agent.bak`);
+  const bytes = typeof data === 'string' ? encodeTextFile(data, encoding) : Buffer.from(data);
+  const prior = await stat(filePath).catch(() => null);
+  const handle = await open(temp, 'wx', prior?.mode);
+  try {
+    await handle.writeFile(bytes);
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  if (prior) await chmod(temp, prior.mode).catch(() => {});
+  try {
+    await rename(temp, filePath);
+  } catch (error) {
+    if (process.platform !== 'win32' || !prior) {
+      await rm(temp, { force: true }).catch(() => {});
+      throw error;
+    }
+    // Windows cannot always replace an open destination. Keep a rollback copy.
+    await rename(filePath, backup);
+    try {
+      await rename(temp, filePath);
+      await rm(backup, { force: true });
+    } catch (replaceError) {
+      await rename(backup, filePath).catch(() => {});
+      await rm(temp, { force: true }).catch(() => {});
+      throw replaceError;
+    }
+  }
+  // Persist the directory entry as well as the file contents. Some platforms do
+  // not permit opening directories; durability is best-effort there.
+  const directory = await open(parent, 'r').catch(() => undefined);
+  if (directory) {
+    try { await directory.sync(); } catch {}
+    await directory.close().catch(() => {});
+  }
+}
+
+/**
+ * 读文件前 3 字节，返回 BOM 类型。
+ * - EF BB BF → utf8-bom
+ * - FF FE    → utf16le
+ * - 其它 / 空 / 出错 → utf8（默认）
+ */
+export async function detectFileBomEncoding(filePath: string): Promise<FileBomEncoding> {
+  let fh: Awaited<ReturnType<typeof open>> | null = null;
+  try {
+    fh = await open(filePath, 'r');
+    const buf = Buffer.alloc(3);
+    const { bytesRead } = await fh.read(buf, 0, 3, 0);
+    if (bytesRead >= 3 && buf[0] === 0xef && buf[1] === 0xbb && buf[2] === 0xbf) {
+      return 'utf8-bom';
+    }
+    if (bytesRead >= 2 && buf[0] === 0xff && buf[1] === 0xfe) {
+      return 'utf16le';
+    }
+    return 'utf8';
+  } catch {
+    return 'utf8';
+  } finally {
+    if (fh) {
+      try {
+        await fh.close();
+      } catch {}
+    }
+  }
+}
+
+// -------------------- 4. 引号风格保留 --------------------
+
+export const LEFT_SINGLE_CURLY_QUOTE = '\u2018';
+export const RIGHT_SINGLE_CURLY_QUOTE = '\u2019';
+export const LEFT_DOUBLE_CURLY_QUOTE = '\u201C';
+export const RIGHT_DOUBLE_CURLY_QUOTE = '\u201D';
+
+export function normalizeQuotes(str: string): string {
+  return str
+    .replaceAll(LEFT_SINGLE_CURLY_QUOTE, "'")
+    .replaceAll(RIGHT_SINGLE_CURLY_QUOTE, "'")
+    .replaceAll(LEFT_DOUBLE_CURLY_QUOTE, '"')
+    .replaceAll(RIGHT_DOUBLE_CURLY_QUOTE, '"');
+}
+
+export function findActualString(
+  fileContent: string,
+  searchString: string,
+): string | null {
+  if (fileContent.includes(searchString)) {
+    return searchString;
+  }
+
+  const normalizedSearch = normalizeQuotes(searchString);
+  const normalizedFile = normalizeQuotes(fileContent);
+
+  const searchIndex = normalizedFile.indexOf(normalizedSearch);
+  if (searchIndex !== -1) {
+    return fileContent.substring(searchIndex, searchIndex + searchString.length);
+  }
+
+  return null;
+}
+
+export function preserveQuoteStyle(
+  oldString: string,
+  actualOldString: string,
+  newString: string,
+): string {
+  if (oldString === actualOldString) {
+    return newString;
+  }
+
+  const hasDoubleQuotes =
+    actualOldString.includes(LEFT_DOUBLE_CURLY_QUOTE) ||
+    actualOldString.includes(RIGHT_DOUBLE_CURLY_QUOTE);
+  const hasSingleQuotes =
+    actualOldString.includes(LEFT_SINGLE_CURLY_QUOTE) ||
+    actualOldString.includes(RIGHT_SINGLE_CURLY_QUOTE);
+
+  if (!hasDoubleQuotes && !hasSingleQuotes) {
+    return newString;
+  }
+
+  let result = newString;
+
+  if (hasDoubleQuotes) {
+    result = applyCurlyDoubleQuotes(result);
+  }
+  if (hasSingleQuotes) {
+    result = applyCurlySingleQuotes(result);
+  }
+
+  return result;
+}
+
+function isOpeningContext(chars: string[], index: number): boolean {
+  if (index === 0) return true;
+  const prev = chars[index - 1];
+  return (
+    prev === ' ' ||
+    prev === '\t' ||
+    prev === '\n' ||
+    prev === '\r' ||
+    prev === '(' ||
+    prev === '[' ||
+    prev === '{' ||
+    prev === '\u2014' ||
+    prev === '\u2013'
+  );
+}
+
+function applyCurlyDoubleQuotes(str: string): string {
+  const chars = [...str];
+  const result: string[] = [];
+  for (let i = 0; i < chars.length; i++) {
+    if (chars[i] === '"') {
+      result.push(
+        isOpeningContext(chars, i)
+          ? LEFT_DOUBLE_CURLY_QUOTE
+          : RIGHT_DOUBLE_CURLY_QUOTE,
+      );
+    } else {
+      result.push(chars[i]!);
+    }
+  }
+  return result.join('');
+}
+
+function applyCurlySingleQuotes(str: string): string {
+  const chars = [...str];
+  const result: string[] = [];
+  for (let i = 0; i < chars.length; i++) {
+    if (chars[i] === "'") {
+      const prev = i > 0 ? chars[i - 1] : undefined;
+      const next = i < chars.length - 1 ? chars[i + 1] : undefined;
+      const prevIsLetter = prev !== undefined && /\p{L}/u.test(prev);
+      const nextIsLetter = next !== undefined && /\p{L}/u.test(next);
+
+      if (prevIsLetter && nextIsLetter) {
+        result.push(RIGHT_SINGLE_CURLY_QUOTE);
+      } else {
+        result.push(
+          isOpeningContext(chars, i)
+            ? LEFT_SINGLE_CURLY_QUOTE
+            : RIGHT_SINGLE_CURLY_QUOTE,
+        );
+      }
+    } else {
+      result.push(chars[i]!);
+    }
+  }
+  return result.join('');
+}
+
+// -------------------- 5. 字符串搜索/替换共享工具 --------------------
+
+/** 统计 needle 在 haystack 中出现多少次（不重叠）。 */
+export function countOccurrences(haystack: string, needle: string): number {
+  if (needle.length === 0) return 0;
+  let count = 0;
+  let pos = 0;
+  while ((pos = haystack.indexOf(needle, pos)) !== -1) {
+    count++;
+    pos += needle.length;
+  }
+  return count;
+}
+
+/**
+ * 全部替换。
+ * 不用 String.prototype.replaceAll(string, string) 与 String.prototype.replace 是
+ * 为了规避 replacement 字符串中 `$&` / `$1` 等被当作回填模式解释的问题。
+ */
+export function splitReplaceAll(haystack: string, needle: string, replacement: string): string {
+  return haystack.split(needle).join(replacement);
+}

package/src/tools/shared/killTree.ts

@@ -0,0 +1,50 @@
+/**
+ * ============================================================
+ *  src/tools/shared/killTree.ts —— 中断/超时时杀「整棵进程树」
+ * ------------------------------------------------------------
+ *  win32 的 `child.kill('SIGTERM')` 只 TerminateProcess **直接子进程**：在飞的孙进程
+ *  （shell 里的实际命令 / 逐张 spawn 的生图子进程 / bun test·构建·服务 …）会变孤儿继续
+ *  跑，还占着 stdout 管道让 'close' 永不触发 —— 表现为「点了停止、agent 停了、活儿还在
+ *  后台跑」的"中断看起来没生效"（2026-07-02 生图事故；同类问题后来在 Bash 长命令复现）。
+ *
+ *   - win32：`taskkill /pid <pid> /T /F` 杀整棵树；taskkill 自身失败再兜底 kill 直接子进程。
+ *   - POSIX：调用方须 `spawn({ detached: true })` 让子进程自成进程组，这里 `kill(-pid)` 掀整组；
+ *     失败兜底同上。
+ *
+ *  两个消费者（genimage / bash）都需要，按「两次规则」升为共享 util。
+ * ============================================================
+ */
+
+import { spawn } from 'node:child_process';
+
+export function killTree(child: ReturnType<typeof spawn>): void {
+  const pid = child.pid;
+  const fallback = () => {
+    try {
+      child.kill('SIGTERM');
+    } catch {
+      /* ignore */
+    }
+  };
+  if (!pid) {
+    fallback();
+    return;
+  }
+  if (process.platform === 'win32') {
+    try {
+      const killer = spawn('taskkill', ['/pid', String(pid), '/T', '/F'], {
+        stdio: 'ignore',
+        windowsHide: true,
+      });
+      killer.on('error', fallback);
+    } catch {
+      fallback();
+    }
+  } else {
+    try {
+      process.kill(-pid, 'SIGTERM');
+    } catch {
+      fallback();
+    }
+  }
+}

package/src/tools/shared/permanentDeleteGuard.js

@@ -0,0 +1,26 @@
+/** Minimal recoverability boundary for model-issued shell commands. */
+const BASH_DELETE = [
+    /(?:^|[;&|\n])\s*(?:sudo\s+)?(?:rm|unlink|rmdir)\b/i,
+    /(?:^|[;&|\n])\s*find\b[^\n;&|]*\s-delete\b/i,
+];
+const GIT_CLEAN = /(?:^|[;&|\n])\s*git\b[^\n;&|]*\bclean\b([^\n;&|]*)/i;
+const POWERSHELL_DELETE = [
+    /(?:^|[;|\n])\s*(?:Remove-Item|Clear-RecycleBin)\b/i,
+    /(?:^|[;|\n])\s*(?:del|erase|rd|rmdir|rm|ri)\b/i,
+    /\.Delete\s*\(/i,
+];
+export function permanentDeleteReason(command, shell) {
+    let hit = (shell === 'bash' ? BASH_DELETE : POWERSHELL_DELETE).some((pattern) => pattern.test(command));
+    if (!hit && shell === 'bash') {
+        const gitClean = GIT_CLEAN.exec(command);
+        const options = gitClean?.[1] ?? '';
+        const dryRun = /--dry-run\b/.test(options) ||
+            /(?:^|\s)-[a-z]*n[a-z]*(?:\s|$)/i.test(options);
+        hit = Boolean(gitClean &&
+            !dryRun &&
+            /(?:^|\s)-[a-z]*f[a-z]*(?:\s|$)|--force\b/i.test(options));
+    }
+    return hit
+        ? '该命令会绕过系统回收站永久删除文件。请改用 Trash；清理 Git 未跟踪文件请用 Trash(action="git-clean")。'
+        : undefined;
+}

package/src/tools/shared/permanentDeleteGuard.ts

@@ -0,0 +1,34 @@
+/** Minimal recoverability boundary for model-issued shell commands. */
+const BASH_DELETE = [
+  /(?:^|[;&|\n])\s*(?:sudo\s+)?(?:rm|unlink|rmdir)\b/i,
+  /(?:^|[;&|\n])\s*find\b[^\n;&|]*\s-delete\b/i,
+];
+const GIT_CLEAN = /(?:^|[;&|\n])\s*git\b[^\n;&|]*\bclean\b([^\n;&|]*)/i;
+const POWERSHELL_DELETE = [
+  /(?:^|[;|\n])\s*(?:Remove-Item|Clear-RecycleBin)\b/i,
+  /(?:^|[;|\n])\s*(?:del|erase|rd|rmdir|rm|ri)\b/i,
+  /\.Delete\s*\(/i,
+];
+export function permanentDeleteReason(
+  command: string,
+  shell: 'bash' | 'powershell',
+): string | undefined {
+  let hit = (shell === 'bash' ? BASH_DELETE : POWERSHELL_DELETE).some(
+    (pattern) => pattern.test(command),
+  );
+  if (!hit && shell === 'bash') {
+    const gitClean = GIT_CLEAN.exec(command);
+    const options = gitClean?.[1] ?? '';
+    const dryRun =
+      /--dry-run\b/.test(options) ||
+      /(?:^|\s)-[a-z]*n[a-z]*(?:\s|$)/i.test(options);
+    hit = Boolean(
+      gitClean &&
+      !dryRun &&
+      /(?:^|\s)-[a-z]*f[a-z]*(?:\s|$)|--force\b/i.test(options),
+    );
+  }
+  return hit
+    ? '该命令会绕过系统回收站永久删除文件。请改用 Trash；清理 Git 未跟踪文件请用 Trash(action="git-clean")。'
+    : undefined;
+}

package/src/tools/shared/schemas.ts

@@ -0,0 +1,20 @@
+/**
+ * ============================================================
+ *  src/tools/shared/schemas.ts —— 工具 Zod 输入 schema 公共片段
+ * ------------------------------------------------------------
+ *  抽出 Read / Write / Edit / MultiEdit 共享的 file_path 字段，
+ *  统一 min length 校验与 describe 文案。
+ *  动作动词通过参数注入（读取 / 写入 / 编辑）。
+ * ============================================================
+ */
+
+import { z } from 'zod';
+
+export type FilePathAction = '读取' | '写入' | '编辑';
+
+export function filePathField(action: FilePathAction) {
+  return z
+    .string()
+    .min(1, '必须提供 file_path')
+    .describe(`要${action}的文件路径（绝对路径优先，相对路径基于 working dir 解析）`);
+}