minimal-agent 0.10.0 → 0.12.0

package/src/tools/grep/grep.js

@@ -46,13 +46,17 @@ const inputSchema = z.object({
     '-A': z.number().int().min(0).optional().describe('匹配后展示几行上下文'),
     '-B': z.number().int().min(0).optional().describe('匹配前展示几行上下文'),
     '-C': z.number().int().min(0).optional().describe('匹配前后各展示几行（覆盖 -A/-B）'),
+    context: z.number().int().min(0).optional().describe('与 -C 相同：匹配前后各展示几行'),
+    multiline: z.boolean().optional().describe('启用跨行匹配（rg -U --multiline-dotall）'),
     head_limit: z
         .number()
         .int()
-        .positive()
+        .min(0)
         .optional()
-        .describe('输出最多保留前 N 行（防止结果过大）'),
+        .describe('输出最多保留前 N 行，默认 250；0 表示不限制'),
+    offset: z.number().int().min(0).optional().describe('跳过前 N 行/条目后再应用 head_limit'),
 });
+const MAX_CAPTURE_CHARS = DEFAULT_MAX_RESULT_SIZE_CHARS * 2;
 // ---------------- 2. JSON Schema（由 Zod 自动派生） ----------------
 const parameters = toToolParameters(inputSchema);
 // ---------------- 3. Description（搬自 kakadeai/tools/GrepTool/prompt.ts） ----------------
@@ -65,7 +69,7 @@ Usage:
 - Output modes: "content" shows matching lines, "files_with_matches" shows only file paths (default), "count" shows match counts
 - Pattern syntax: Uses ripgrep (not classic grep)`;
 // ---------------- 4. call() ----------------
-async function call(input, signal) {
+async function call(input, signal, runCwd = getWorkingDir()) {
     const args = [];
     // 输出模式（默认 files_with_matches）
     const mode = input.output_mode ?? 'files_with_matches';
@@ -79,8 +83,9 @@ async function call(input, signal) {
     if (mode === 'content' && input['-n'])
         args.push('-n');
     // 上下文行数：-C 优先，否则各加 -A/-B
-    if (typeof input['-C'] === 'number') {
-        args.push('-C', String(input['-C']));
+    const sharedContext = input['-C'] ?? input.context;
+    if (typeof sharedContext === 'number') {
+        args.push('-C', String(sharedContext));
     }
     else {
         if (typeof input['-A'] === 'number')
@@ -92,6 +97,8 @@ async function call(input, signal) {
         args.push('--glob', input.glob);
     if (input.type)
         args.push('--type', input.type);
+    if (input.multiline)
+        args.push('-U', '--multiline-dotall');
     // 安全：限制单文件输出大小（防止超大行）
     args.push('--max-columns', '500');
     args.push('--max-columns-preview');
@@ -99,8 +106,10 @@ async function call(input, signal) {
     args.push('--sort', 'modified');
     // pattern 必须用 -e 显式标记，否则以 - 开头的 pattern 会被当成 flag
     args.push('-e', input.pattern);
-    // 搜索路径
-    args.push(input.path ? resolve(input.path) : '.');
+    // 搜索路径：以 getWorkingDir() 为锚，而非裸 resolve()（后者落回 process.cwd()，
+    // 在 Desktop/Gateway 这类单进程内托管多工作区的宿主里会跟 getWorkingDir() 脱节，
+    // 相对 path 参数误锚到宿主进程自己的目录而非当前工作区）。resolve 对绝对路径行为不变。
+    args.push(input.path ? resolve(runCwd, input.path) : '.');
     // ---- 找 rg ----
     // 优先级：MINIMAL_AGENT_RIPGREP_PATH → 系统 PATH → Claude Code 自带的 rg
     const rgPath = await resolveRgPath();
@@ -117,21 +126,47 @@ async function call(input, signal) {
         };
     }
     // ---- spawn rg ----
-    let stdout = '';
+    const offset = input.offset ?? 0;
+    const headLimit = input.head_limit ?? 250;
+    const selectedLines = [];
+    let selectedChars = 0;
+    let totalLines = 0;
+    let pending = '';
+    let outputTruncated = false;
     let stderr = '';
     let exitCode = null;
     try {
         await new Promise((resolveP, rejectP) => {
             const child = spawn(rgPath, args, {
-                cwd: getWorkingDir(),
+                cwd: runCwd,
                 env: sanitizeCredentialEnv(),
                 signal,
                 windowsHide: true,
             });
             child.stdout.setEncoding('utf8');
             child.stderr.setEncoding('utf8');
-            child.stdout.on('data', (chunk) => (stdout += chunk));
-            child.stderr.on('data', (chunk) => (stderr += chunk));
+            child.stdout.on('data', (chunk) => {
+                pending += String(chunk);
+                const lines = pending.split('\n');
+                pending = lines.pop() ?? '';
+                for (const line of lines) {
+                    const index = totalLines++;
+                    const inPage = index >= offset && (headLimit === 0 || selectedLines.length < headLimit);
+                    if (!inPage)
+                        continue;
+                    if (selectedChars + line.length + 1 <= MAX_CAPTURE_CHARS) {
+                        selectedLines.push(line);
+                        selectedChars += line.length + 1;
+                    }
+                    else {
+                        outputTruncated = true;
+                    }
+                }
+            });
+            child.stderr.on('data', (chunk) => {
+                if (stderr.length < MAX_CAPTURE_CHARS)
+                    stderr += String(chunk).slice(0, MAX_CAPTURE_CHARS - stderr.length);
+            });
             child.on('error', (e) => rejectP(e));
             child.on('close', (code) => {
                 exitCode = code;
@@ -156,16 +191,22 @@ async function call(input, signal) {
             error: `rg 退出码 ${exitCode}：${stderr.slice(0, 500) || '(无 stderr)'}`,
         };
     }
-    // ---- head_limit + 大小兜底 ----
-    let content = stdout;
-    if (input.head_limit && input.head_limit > 0) {
-        const lines = content.split('\n');
-        if (lines.length > input.head_limit) {
-            content =
-                lines.slice(0, input.head_limit).join('\n') +
-                    `\n... (已截断到 ${input.head_limit} 行 / 共 ${lines.length} 行，保留最新匹配)`;
+    if (pending.length > 0) {
+        const index = totalLines++;
+        const inPage = index >= offset && (headLimit === 0 || selectedLines.length < headLimit);
+        if (inPage) {
+            if (selectedChars + pending.length <= MAX_CAPTURE_CHARS)
+                selectedLines.push(pending);
+            else
+                outputTruncated = true;
         }
     }
+    // ---- head_limit + 大小兜底 ----
+    let content = selectedLines.join('\n');
+    const hasMore = offset + selectedLines.length < totalLines;
+    if (offset > 0 || headLimit > 0 || hasMore || outputTruncated) {
+        content += `\n... (offset=${offset}，返回 ${selectedLines.length} 行 / 共 ${totalLines} 行${hasMore ? '，仍有后续结果' : ''}${outputTruncated ? '，本页达到输出硬上限' : ''})`;
+    }
     // 超长截断：保留头部（最新结果），丢弃尾部（旧结果）
     if (content.length > DEFAULT_MAX_RESULT_SIZE_CHARS) {
         content =
@@ -185,4 +226,5 @@ export const grepTool = {
     maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
     interruptBehavior: () => 'cancel',
     call,
+    callWithContext: (input, signal, context) => call(input, signal, context.cwd),
 };

package/src/tools/grep/grep.ts

@@ -0,0 +1,239 @@
+/**
+ * ============================================================
+ *  src/tools/grep.ts —— Grep 工具（基于 ripgrep 的内容搜索）
+ * ------------------------------------------------------------
+ *  对应 kakadeai 主仓库的 GrepTool。
+ *  实现策略：spawn 系统 `rg` 命令。
+ *  没装 ripgrep 时给"教学型"错误：
+ *    - macOS: brew install ripgrep
+ *    - Windows: scoop install ripgrep
+ *    - Ubuntu: sudo apt install ripgrep
+ *
+ *  为何不用纯 Node 实现？
+ *    递归遍历 + 正则 + glob 排除 + 字符编码处理 = 几百行；
+ *    最小化原则下复用 rg 子进程更划算。
+ * ============================================================
+ */
+
+import { spawn } from 'node:child_process';
+import { resolve } from 'node:path';
+import { z } from 'zod';
+
+import { getWorkingDir } from '../../bootstrap/workingDir.js';
+import { sanitizeCredentialEnv } from '../../config/configService.js';
+import type { Tool, ToolCallContext, ToolResult } from '../../types.js';
+import { resolveRgPath } from './rgPath.js';
+import { DEFAULT_MAX_RESULT_SIZE_CHARS } from '../types.js';
+import { toToolParameters } from '../../utils/zodToJson.js';
+
+// ---------------- 1. Zod 输入 schema ----------------
+const inputSchema = z.object({
+  pattern: z.string().min(1).describe('正则表达式（ripgrep 兼容语法）'),
+  path: z
+    .string()
+    .optional()
+    .describe('搜索的根目录或文件（默认当前工作目录）'),
+  glob: z
+    .string()
+    .optional()
+    .describe('文件名 glob 过滤，如 "*.ts"'),
+  type: z
+    .string()
+    .optional()
+    .describe('rg 的文件类型快捷名，如 "py"、"rust"、"js"'),
+  output_mode: z
+    .enum(['content', 'files_with_matches', 'count'])
+    .optional()
+    .describe('输出模式：content=匹配行；files_with_matches=只列文件；count=每文件计数'),
+  '-i': z.boolean().optional().describe('忽略大小写'),
+  '-n': z.boolean().optional().describe('显示行号（仅 content 模式）'),
+  '-A': z.number().int().min(0).optional().describe('匹配后展示几行上下文'),
+  '-B': z.number().int().min(0).optional().describe('匹配前展示几行上下文'),
+  '-C': z.number().int().min(0).optional().describe('匹配前后各展示几行（覆盖 -A/-B）'),
+  context: z.number().int().min(0).optional().describe('与 -C 相同：匹配前后各展示几行'),
+  multiline: z.boolean().optional().describe('启用跨行匹配（rg -U --multiline-dotall）'),
+  head_limit: z
+    .number()
+    .int()
+    .min(0)
+    .optional()
+    .describe('输出最多保留前 N 行，默认 250；0 表示不限制'),
+  offset: z.number().int().min(0).optional().describe('跳过前 N 行/条目后再应用 head_limit'),
+});
+type GrepInput = z.infer<typeof inputSchema>;
+const MAX_CAPTURE_CHARS = DEFAULT_MAX_RESULT_SIZE_CHARS * 2;
+
+// ---------------- 2. JSON Schema（由 Zod 自动派生） ----------------
+const parameters = toToolParameters(inputSchema);
+
+// ---------------- 3. Description（搬自 kakadeai/tools/GrepTool/prompt.ts） ----------------
+const description = `A powerful search tool built on ripgrep.
+
+Usage:
+- ALWAYS use Grep for content search tasks. Do NOT invoke \`grep\` or \`rg\` directly via Bash.
+- Supports full regex syntax (e.g., "log.*Error", "function\\s+\\w+")
+- Filter files with glob parameter (e.g., "*.js", "**/*.tsx") or type parameter (e.g., "js", "py", "rust")
+- Output modes: "content" shows matching lines, "files_with_matches" shows only file paths (default), "count" shows match counts
+- Pattern syntax: Uses ripgrep (not classic grep)`;
+
+// ---------------- 4. call() ----------------
+async function call(input: GrepInput, signal?: AbortSignal, runCwd = getWorkingDir()): Promise<ToolResult> {
+  const args: string[] = [];
+
+  // 输出模式（默认 files_with_matches）
+  const mode = input.output_mode ?? 'files_with_matches';
+  if (mode === 'files_with_matches') args.push('-l');
+  else if (mode === 'count') args.push('--count-matches');
+  // mode === 'content' 是 rg 默认行为，不加 flag
+
+  if (input['-i']) args.push('-i');
+  if (mode === 'content' && input['-n']) args.push('-n');
+
+  // 上下文行数：-C 优先，否则各加 -A/-B
+  const sharedContext = input['-C'] ?? input.context;
+  if (typeof sharedContext === 'number') {
+    args.push('-C', String(sharedContext));
+  } else {
+    if (typeof input['-A'] === 'number') args.push('-A', String(input['-A']));
+    if (typeof input['-B'] === 'number') args.push('-B', String(input['-B']));
+  }
+
+  if (input.glob) args.push('--glob', input.glob);
+  if (input.type) args.push('--type', input.type);
+  if (input.multiline) args.push('-U', '--multiline-dotall');
+
+  // 安全：限制单文件输出大小（防止超大行）
+  args.push('--max-columns', '500');
+  args.push('--max-columns-preview');
+
+  // 按修改时间降序排列（新文件/新匹配在前，与 Glob 的旧在前形成互补锁定模板）
+  args.push('--sort', 'modified');
+
+  // pattern 必须用 -e 显式标记，否则以 - 开头的 pattern 会被当成 flag
+  args.push('-e', input.pattern);
+
+  // 搜索路径：以 getWorkingDir() 为锚，而非裸 resolve()（后者落回 process.cwd()，
+  // 在 Desktop/Gateway 这类单进程内托管多工作区的宿主里会跟 getWorkingDir() 脱节，
+  // 相对 path 参数误锚到宿主进程自己的目录而非当前工作区）。resolve 对绝对路径行为不变。
+  args.push(input.path ? resolve(runCwd, input.path) : '.');
+
+  // ---- 找 rg ----
+  // 优先级：MINIMAL_AGENT_RIPGREP_PATH → 系统 PATH → Claude Code 自带的 rg
+  const rgPath = await resolveRgPath();
+  if (!rgPath) {
+    return {
+      ok: false,
+      error:
+        '找不到 ripgrep（rg）。可以三选一：\n' +
+        '  ① 装 Claude Code（自带 rg）：npm i -g @anthropic-ai/claude-code\n' +
+        '  ② 系统装 ripgrep：\n' +
+        '     macOS:   brew install ripgrep\n' +
+        '     Windows: scoop install ripgrep\n' +
+        '     Ubuntu:  sudo apt install ripgrep\n' +
+        '  ③ 在 .env 设置 MINIMAL_AGENT_RIPGREP_PATH=/绝对/路径/到/rg',
+    };
+  }
+
+  // ---- spawn rg ----
+  const offset = input.offset ?? 0;
+  const headLimit = input.head_limit ?? 250;
+  const selectedLines: string[] = [];
+  let selectedChars = 0;
+  let totalLines = 0;
+  let pending = '';
+  let outputTruncated = false;
+  let stderr = '';
+  let exitCode: number | null = null;
+
+  try {
+    await new Promise<void>((resolveP, rejectP) => {
+      const child = spawn(rgPath, args, {
+        cwd: runCwd,
+        env: sanitizeCredentialEnv(),
+        signal,
+        windowsHide: true,
+      });
+      child.stdout.setEncoding('utf8');
+      child.stderr.setEncoding('utf8');
+      child.stdout.on('data', (chunk) => {
+        pending += String(chunk);
+        const lines = pending.split('\n');
+        pending = lines.pop() ?? '';
+        for (const line of lines) {
+          const index = totalLines++;
+          const inPage = index >= offset && (headLimit === 0 || selectedLines.length < headLimit);
+          if (!inPage) continue;
+          if (selectedChars + line.length + 1 <= MAX_CAPTURE_CHARS) {
+            selectedLines.push(line);
+            selectedChars += line.length + 1;
+          } else {
+            outputTruncated = true;
+          }
+        }
+      });
+      child.stderr.on('data', (chunk) => {
+        if (stderr.length < MAX_CAPTURE_CHARS) stderr += String(chunk).slice(0, MAX_CAPTURE_CHARS - stderr.length);
+      });
+      child.on('error', (e) => rejectP(e));
+      child.on('close', (code) => {
+        exitCode = code;
+        resolveP();
+      });
+    });
+  } catch (e) {
+    const err = e as NodeJS.ErrnoException;
+    return { ok: false, error: `执行 rg 失败（${rgPath}）：${err.message}` };
+  }
+
+  // rg 的退出码语义：
+  //   0 = 找到匹配
+  //   1 = 没找到匹配（不算错）
+  //   2 = 真正的错误
+  if (exitCode === 1) {
+    return { ok: true, content: `(no matches for pattern: ${input.pattern})` };
+  }
+  if (exitCode !== 0) {
+    return {
+      ok: false,
+      error: `rg 退出码 ${exitCode}：${stderr.slice(0, 500) || '(无 stderr)'}`,
+    };
+  }
+
+  if (pending.length > 0) {
+    const index = totalLines++;
+    const inPage = index >= offset && (headLimit === 0 || selectedLines.length < headLimit);
+    if (inPage) {
+      if (selectedChars + pending.length <= MAX_CAPTURE_CHARS) selectedLines.push(pending);
+      else outputTruncated = true;
+    }
+  }
+
+  // ---- head_limit + 大小兜底 ----
+  let content = selectedLines.join('\n');
+  const hasMore = offset + selectedLines.length < totalLines;
+  if (offset > 0 || headLimit > 0 || hasMore || outputTruncated) {
+    content += `\n... (offset=${offset}，返回 ${selectedLines.length} 行 / 共 ${totalLines} 行${hasMore ? '，仍有后续结果' : ''}${outputTruncated ? '，本页达到输出硬上限' : ''})`;
+  }
+  // 超长截断：保留头部（最新结果），丢弃尾部（旧结果）
+  if (content.length > DEFAULT_MAX_RESULT_SIZE_CHARS) {
+    content =
+      content.slice(0, DEFAULT_MAX_RESULT_SIZE_CHARS) +
+      `\n\n... (输出超过 ${DEFAULT_MAX_RESULT_SIZE_CHARS} 字符，已截断尾部旧结果)`;
+  }
+
+  return { ok: true, content };
+}
+
+// ---------------- 5. 导出 ----------------
+export const grepTool: Tool<GrepInput> = {
+  name: 'Grep',
+  description,
+  inputSchema,
+  parameters,
+  isReadOnly: true,
+  isConcurrencySafe: true,
+  maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
+  interruptBehavior: () => 'cancel',
+  call,
+  callWithContext: (input, signal, context: ToolCallContext) => call(input, signal, context.cwd),
+};

package/src/tools/grep/rgPath.ts

@@ -0,0 +1,206 @@
+/**
+ * ============================================================
+ *  src/tools/rgPath.ts —— 解析 ripgrep 可执行文件路径
+ * ------------------------------------------------------------
+ *  策略（按优先级）：
+ *    ① MINIMAL_AGENT_RIPGREP_PATH 环境变量（手动指定，调试时最高优先）
+ *    ② 项目自带的 vendored rg —— vendor/ripgrep/<arch>-<platform>/rg(.exe)
+ *       这是默认路径！开箱即用，不依赖系统装没装。
+ *    ③ 系统 PATH 上的 rg (用户自己装的 brew/scoop/apt 版本)
+ *    ④ Claude Code 全局 npm 包自带的 rg（兜底）
+ *
+ *  借鉴：kakadeai/utils/ripgrep.ts 的 getRipgrepConfig，但砍掉了：
+ *    - 嵌入式 Bun 模式（我们不用 bun build 打包）
+ *    - 单线程 EAGAIN 重试（最小化版用不到）
+ *
+ *  vendor/ripgrep 6 个平台二进制（arm64/x64 × win32/darwin/linux）从
+ *  Claude Code 自带的同一份原料复制而来，许可证 MIT/Unlicense，可自由分发。
+ *  macOS 上首次跑可能需要 codesign（见 codesignIfNeeded 注释）。
+ *
+ *  用法：
+ *    const rg = await resolveRgPath();
+ *    if (!rg) → 返回友好错误
+ *    spawn(rg, args)
+ * ============================================================
+ */
+
+import { spawn } from 'node:child_process';
+import { chmodSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import { sanitizeCredentialEnv } from '../../config/configService.js';
+import { execSiblingDir } from '../../utils/greenRoot.js';
+import { findPackageRoot } from '../../utils/packageRoot.js';
+
+let cached: string | null | undefined;
+
+/**
+ * 解析一次 rg 路径，结果缓存（同一进程内复用）。
+ * 返回 null 表示找不到。
+ */
+export async function resolveRgPath(): Promise<string | null> {
+  if (cached !== undefined) return cached;
+  cached = await detect();
+  return cached;
+}
+
+/** 仅供测试重置缓存 */
+export function _resetRgCache(): void {
+  cached = undefined;
+}
+
+async function detect(): Promise<string | null> {
+  // ① 显式 env 覆盖
+  const fromEnv = process.env.MINIMAL_AGENT_RIPGREP_PATH;
+  if (fromEnv && existsSync(fromEnv)) return fromEnv;
+
+  // ② 项目自带的 vendored rg（默认路径！开箱即用）
+  const vendored = vendoredRgPath();
+  if (vendored && existsSync(vendored)) {
+    ensureExecutable(vendored);
+    return vendored;
+  }
+
+  // ②.5 绿色版（bun --compile 单文件）：exe 同级 vendor/ripgrep/<arch>-<platform>/rg
+  //   compile 后 import.meta.url 是虚拟路径，findPackageRoot 失效（② 命不中），
+  //   绿色目录把 vendor/ 摆在可执行文件旁边，从这里捞回来。dev/npm 下 exe 同级
+  //   没有 vendor/ → existsSync 过滤掉 → 不影响 ②/③/④ 原有优先级。
+  const sibling = resolve(
+    execSiblingDir(),
+    'vendor',
+    'ripgrep',
+    subdir(),
+    exeName(),
+  );
+  if (existsSync(sibling)) {
+    ensureExecutable(sibling);
+    return sibling;
+  }
+
+  // ③ PATH 上的 rg —— 直接试 spawn rg --version
+  if (await trySpawn('rg')) return 'rg';
+
+  // ④ Claude Code 全局 npm 包自带的 rg
+  for (const candidate of claudeCodeCandidates()) {
+    if (existsSync(candidate)) {
+      ensureExecutable(candidate);
+      return candidate;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * 项目内 vendor 路径：vendor/ripgrep/<arch>-<platform>/rg(.exe)
+ * 路径以本文件为锚点向上找，不依赖 cwd（用户在任何目录跑 minimal-agent 都行）。
+ */
+function vendoredRgPath(): string | null {
+  try {
+    const projectRoot = findPackageRoot(import.meta.url);
+    return resolve(projectRoot, 'vendor', 'ripgrep', subdir(), exeName());
+  } catch {
+    return null;
+  }
+}
+
+function subdir(): string {
+  return `${process.arch}-${process.platform}`;
+}
+function exeName(): string {
+  return process.platform === 'win32' ? 'rg.exe' : 'rg';
+}
+
+/**
+ * Unix 上 git/tarball/cp 偶尔会丢可执行位。Windows 不需要。
+ * 失败也忽略（最坏情况下后面 spawn 会报权限错，给出明确信号）。
+ */
+function ensureExecutable(path: string): void {
+  if (process.platform === 'win32') return;
+  try {
+    chmodSync(path, 0o755);
+  } catch {
+    /* ignore */
+  }
+}
+
+/**
+ * 试着 spawn 一下，看 --version 能不能跑通。
+ * 注意：直接传 'rg'（不是绝对路径）让 OS 解析 PATH，
+ * 在 Windows 上配合 NoDefaultCurrentDirectoryInExePath 防 PATH 劫持。
+ */
+function trySpawn(cmd: string): Promise<boolean> {
+  return new Promise((resolveP) => {
+    let settled = false;
+    const done = (ok: boolean) => {
+      if (settled) return;
+      settled = true;
+      resolveP(ok);
+    };
+    try {
+      const child = spawn(cmd, ['--version'], {
+        stdio: ['ignore', 'pipe', 'ignore'],
+        env: sanitizeCredentialEnv(),
+        windowsHide: true,
+      });
+      let stdout = '';
+      child.stdout.setEncoding('utf8');
+      child.stdout.on('data', (c) => (stdout += c));
+      child.on('error', () => done(false));
+      child.on('close', (code) =>
+        done(code === 0 && stdout.startsWith('ripgrep ')),
+      );
+      // 兜底超时：5 秒
+      setTimeout(() => {
+        try {
+          child.kill();
+        } catch {}
+        done(false);
+      }, 5_000);
+    } catch {
+      done(false);
+    }
+  });
+}
+
+/**
+ * 枚举 Claude Code 自带 rg 在常见安装路径下的位置。
+ * 不存在的路径不会被实际访问 —— 调用方用 existsSync 过滤。
+ */
+function claudeCodeCandidates(): string[] {
+  const arch = process.arch; // 'x64' | 'arm64' | ...
+  const platform = process.platform; // 'win32' | 'darwin' | 'linux' | ...
+  const subdir = `${arch}-${platform}`;
+  const exe = platform === 'win32' ? 'rg.exe' : 'rg';
+
+  // 各种 npm global 安装路径
+  const npmRoots: string[] = [];
+
+  if (platform === 'win32') {
+    // npm 默认 prefix: %APPDATA%/npm
+    if (process.env.APPDATA) {
+      npmRoots.push(resolve(process.env.APPDATA, 'npm', 'node_modules'));
+    }
+    // 也试试 user profile/AppData/Roaming（Bash on Windows 偶尔 APPDATA 没设）
+    if (process.env.USERPROFILE) {
+      npmRoots.push(
+        resolve(process.env.USERPROFILE, 'AppData', 'Roaming', 'npm', 'node_modules'),
+      );
+    }
+  } else {
+    // Unix：常见的 npm global prefix
+    const home = process.env.HOME ?? '';
+    if (home) {
+      npmRoots.push(resolve(home, '.npm-global', 'lib', 'node_modules'));
+      npmRoots.push(resolve(home, '.npm', 'lib', 'node_modules'));
+      npmRoots.push(resolve(home, 'node_modules'));
+    }
+    npmRoots.push('/usr/local/lib/node_modules');
+    npmRoots.push('/usr/lib/node_modules');
+    npmRoots.push('/opt/homebrew/lib/node_modules');
+  }
+
+  return npmRoots.map((root) =>
+    resolve(root, '@anthropic-ai', 'claude-code', 'vendor', 'ripgrep', subdir, exe),
+  );
+}