codex-workspace-codegraph-mcp 0.2.0

package/src/tunnel.js

@@ -0,0 +1,232 @@
+import fs from 'node:fs/promises';
+import fsSync from 'node:fs';
+import http from 'node:http';
+import https from 'node:https';
+import os from 'node:os';
+import path from 'node:path';
+import zlib from 'node:zlib';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { findExecutable, parseArgs, randomToken, sleep } from './utils.js';
+
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = path.resolve(MODULE_DIR, '..');
+
+function cloudflaredAsset() {
+  const { platform, arch } = process;
+  if (platform === 'linux') {
+    if (arch === 'x64') return { name: 'cloudflared-linux-amd64', archive: false };
+    if (arch === 'arm64') return { name: 'cloudflared-linux-arm64', archive: false };
+    if (arch === 'arm') return { name: 'cloudflared-linux-arm', archive: false };
+    if (arch === 'ia32') return { name: 'cloudflared-linux-386', archive: false };
+  }
+  if (platform === 'win32') {
+    if (arch === 'x64') return { name: 'cloudflared-windows-amd64.exe', archive: false };
+    if (arch === 'ia32') return { name: 'cloudflared-windows-386.exe', archive: false };
+    if (arch === 'arm64') return { name: 'cloudflared-windows-arm64.exe', archive: false };
+  }
+  if (platform === 'darwin') {
+    if (arch === 'x64') return { name: 'cloudflared-darwin-amd64.tgz', archive: true };
+    if (arch === 'arm64') return { name: 'cloudflared-darwin-arm64.tgz', archive: true };
+  }
+  throw new Error(`暂不支持自动下载 cloudflared: ${platform}/${arch}`);
+}
+
+function download(url, destination, redirects = 0) {
+  if (redirects > 8) return Promise.reject(new Error('cloudflared 下载重定向过多'));
+  return new Promise((resolve, reject) => {
+    const request = https.get(url, { headers: { 'user-agent': 'codex-workspace-codegraph-mcp/0.2.0' } }, (response) => {
+      if ([301, 302, 303, 307, 308].includes(response.statusCode) && response.headers.location) {
+        response.resume();
+        download(new URL(response.headers.location, url).href, destination, redirects + 1).then(resolve, reject);
+        return;
+      }
+      if (response.statusCode !== 200) {
+        response.resume();
+        reject(new Error(`下载 cloudflared 失败: HTTP ${response.statusCode}`));
+        return;
+      }
+      const file = fsSync.createWriteStream(destination, { mode: 0o700 });
+      response.pipe(file);
+      file.on('finish', () => file.close(resolve));
+      file.on('error', reject);
+    });
+    request.on('error', reject);
+  });
+}
+
+function parseTarString(buffer, start, length) {
+  return buffer.subarray(start, start + length).toString('utf8').replace(/\0.*$/, '').trim();
+}
+
+async function extractFirstTarFile(tgzPath, outputPath) {
+  const compressed = await fs.readFile(tgzPath);
+  const tar = zlib.gunzipSync(compressed);
+  let offset = 0;
+  while (offset + 512 <= tar.length) {
+    const header = tar.subarray(offset, offset + 512);
+    if (header.every((byte) => byte === 0)) break;
+    const name = parseTarString(header, 0, 100);
+    const sizeText = parseTarString(header, 124, 12);
+    const type = String.fromCharCode(header[156] || 48);
+    const size = Number.parseInt(sizeText || '0', 8);
+    offset += 512;
+    if ((type === '0' || type === '\0') && name && path.basename(name).startsWith('cloudflared')) {
+      await fs.writeFile(outputPath, tar.subarray(offset, offset + size), { mode: 0o700 });
+      return;
+    }
+    offset += Math.ceil(size / 512) * 512;
+  }
+  throw new Error('未在 tgz 中找到 cloudflared 可执行文件');
+}
+
+async function ensureCloudflared(args) {
+  const explicit = String(args.cloudflared || process.env.CWMCP_CLOUDFLARED || '');
+  if (explicit) {
+    const found = await findExecutable(explicit);
+    if (!found) throw new Error(`找不到指定的 cloudflared: ${explicit}`);
+    return found;
+  }
+  const existing = await findExecutable('cloudflared');
+  if (existing) return existing;
+  if (args['no-download']) throw new Error('未安装 cloudflared，且指定了 --no-download');
+
+  const asset = cloudflaredAsset();
+  const cacheDirectory = path.join(os.homedir(), '.codex-workspace-mcp', 'bin');
+  await fs.mkdir(cacheDirectory, { recursive: true });
+  const binary = path.join(cacheDirectory, process.platform === 'win32' ? 'cloudflared.exe' : 'cloudflared');
+  try {
+    await fs.access(binary);
+    return binary;
+  } catch { /* download */ }
+
+  const temporary = path.join(os.tmpdir(), `${asset.name}-${process.pid}-${Date.now()}`);
+  const url = `https://github.com/cloudflare/cloudflared/releases/latest/download/${asset.name}`;
+  console.error(`[tunnel] 未检测到 cloudflared，正在下载官方发行文件：${asset.name}`);
+  await download(url, temporary);
+  if (asset.archive) await extractFirstTarFile(temporary, binary);
+  else await fs.rename(temporary, binary);
+  await fs.chmod(binary, 0o700);
+  await fs.rm(temporary, { force: true }).catch(() => {});
+  return binary;
+}
+
+function waitForHealth(port, timeoutMs = 30_000) {
+  const deadline = Date.now() + timeoutMs;
+  return new Promise((resolve, reject) => {
+    const attempt = () => {
+      const request = http.get(`http://127.0.0.1:${port}/health`, (response) => {
+        response.resume();
+        if (response.statusCode === 200) resolve();
+        else retry();
+      });
+      request.on('error', retry);
+      request.setTimeout(1000, () => request.destroy());
+    };
+    const retry = () => {
+      if (Date.now() >= deadline) reject(new Error(`MCP HTTP 服务未在端口 ${port} 就绪`));
+      else setTimeout(attempt, 250);
+    };
+    attempt();
+  });
+}
+
+function spawnTunnel(binary, port, label, emptyConfigPath) {
+  const args = ['tunnel', '--config', emptyConfigPath, '--no-autoupdate', '--protocol', 'http2', '--url', `http://127.0.0.1:${port}`];
+  const child = spawn(binary, args, { windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
+  let settled = false;
+  let resolveUrl;
+  let rejectUrl;
+  const urlPromise = new Promise((resolve, reject) => { resolveUrl = resolve; rejectUrl = reject; });
+  const parse = (chunk) => {
+    const text = chunk.toString('utf8');
+    for (const line of text.split(/\r?\n/).filter(Boolean)) {
+      const match = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/i.exec(line);
+      if (match && !settled) {
+        settled = true;
+        resolveUrl(match[0]);
+      }
+      if (process.env.CWMCP_TUNNEL_VERBOSE === '1') console.error(`[cloudflared:${label}] ${line}`);
+    }
+  };
+  child.stdout.on('data', parse);
+  child.stderr.on('data', parse);
+  child.on('error', (error) => { if (!settled) { settled = true; rejectUrl(error); } });
+  child.on('close', (code) => { if (!settled) { settled = true; rejectUrl(new Error(`${label} tunnel 提前退出，code=${code}`)); } });
+  return { child, urlPromise };
+}
+
+function killChild(child) {
+  if (!child || child.killed) return;
+  child.kill('SIGTERM');
+  setTimeout(() => child.kill('SIGKILL'), 2000).unref();
+}
+
+export async function runTunnelCli(argv = []) {
+  const args = parseArgs(argv);
+  const workspace = path.resolve(String(args.workspace || process.env.CWMCP_WORKSPACE || process.cwd()));
+  const mcpPort = Number(args['mcp-port'] || process.env.CWMCP_MCP_PORT || 8765);
+  const webPort = Number(args['web-port'] || process.env.CWMCP_WEB_PORT || 8766);
+  const token = String(args.token || process.env.CWMCP_ACCESS_TOKEN || randomToken());
+  const cloudflared = await ensureCloudflared(args);
+  const emptyConfigPath = path.join(os.tmpdir(), `cwmcp-cloudflared-${process.pid}.yml`);
+  await fs.writeFile(emptyConfigPath, '# intentionally empty: isolates Quick Tunnel from ~/.cloudflared/config.yaml\n');
+
+  const serverArgs = [path.join(PACKAGE_ROOT, 'bin', 'codex-workspace-mcp.js'), '--transport', 'http', '--workspace', workspace, '--host', '127.0.0.1', '--web-host', '127.0.0.1', '--mcp-port', String(mcpPort), '--web-port', String(webPort), '--token', token, '--no-browser'];
+  if (args['disable-codegraph']) serverArgs.push('--disable-codegraph');
+  if (args.sandbox) serverArgs.push('--sandbox', String(args.sandbox));
+  if (args['approval-policy']) serverArgs.push('--approval-policy', String(args['approval-policy']));
+
+  const server = spawn(process.execPath, serverArgs, {
+    cwd: workspace,
+    env: { ...process.env, CWMCP_ACCESS_TOKEN: token },
+    windowsHide: true,
+    stdio: ['ignore', 'ignore', 'pipe'],
+  });
+  server.stderr.on('data', (chunk) => {
+    if (process.env.CWMCP_TUNNEL_VERBOSE === '1') process.stderr.write(`[server] ${chunk}`);
+  });
+  server.on('error', (error) => console.error(`[server] ${error.message}`));
+
+  const children = [server];
+  const cleanup = async () => {
+    for (const child of children) killChild(child);
+    await fs.rm(emptyConfigPath, { force: true }).catch(() => {});
+  };
+
+  try {
+    await waitForHealth(mcpPort);
+    const mcpTunnel = spawnTunnel(cloudflared, mcpPort, 'mcp', emptyConfigPath);
+    const webTunnel = spawnTunnel(cloudflared, webPort, 'webui', emptyConfigPath);
+    children.push(mcpTunnel.child, webTunnel.child);
+    let timeoutHandle;
+    const timeout = new Promise((_, reject) => {
+      timeoutHandle = setTimeout(() => reject(new Error('等待 TryCloudflare URL 超时')), 60_000);
+      timeoutHandle.unref();
+    });
+    const [mcpBase, webBase] = await Promise.race([Promise.all([mcpTunnel.urlPromise, webTunnel.urlPromise]), timeout]);
+    clearTimeout(timeoutHandle);
+
+    console.log('');
+    console.log('Codex 风格本地代码 MCP 已启动（不需要 Codex/OpenAI 登录、订阅或 API Key）');
+    console.log(`工作区:       ${workspace}`);
+    console.log(`MCP 本地 URL:  http://127.0.0.1:${mcpPort}/mcp/${token}`);
+    console.log(`WebUI 本地 URL: http://127.0.0.1:${webPort}/?token=${encodeURIComponent(token)}`);
+    console.log('');
+    console.log(`MCP 公网 URL:  ${mcpBase}/mcp/${token}`);
+    console.log(`WebUI 公网 URL: ${webBase}/?token=${encodeURIComponent(token)}`);
+    console.log('');
+    console.log('以上 URL 包含访问令牌，请按密码处理。按 Ctrl+C 停止 MCP、WebUI 和两个 tunnel。');
+    console.log('TryCloudflare Quick Tunnel 仅适合测试；不支持 SSE，因此本服务使用 JSON-RPC POST。');
+
+    await new Promise((resolve) => {
+      const stop = () => resolve();
+      process.once('SIGINT', stop);
+      process.once('SIGTERM', stop);
+      server.once('close', stop);
+    });
+  } finally {
+    await cleanup();
+    await sleep(100);
+  }
+}

package/src/utils.js

@@ -0,0 +1,157 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export const FEEDBACK_TIMEOUT_SECONDS = 48 * 60 * 60;
+export const MAX_JSON_BODY_BYTES = 4 * 1024 * 1024;
+
+export function randomToken(bytes = 24) {
+  return crypto.randomBytes(bytes).toString('base64url');
+}
+
+export function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export function clampInteger(value, minimum, maximum, fallback) {
+  const parsed = Number.parseInt(String(value ?? ''), 10);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.max(minimum, Math.min(maximum, parsed));
+}
+
+export function asBoolean(value, fallback = false) {
+  if (value === undefined || value === null || value === '') return fallback;
+  return ['1', 'true', 'yes', 'on'].includes(String(value).toLowerCase());
+}
+
+export function parseJsonEnv(name, fallback) {
+  const raw = process.env[name];
+  if (!raw) return fallback;
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`${name} 必须是有效 JSON: ${error.message}`);
+  }
+}
+
+export function jsonText(value) {
+  return JSON.stringify(value, null, 2);
+}
+
+export function toolText(value) {
+  return {
+    content: [{ type: 'text', text: typeof value === 'string' ? value : jsonText(value) }],
+    structuredContent: typeof value === 'object' && value !== null ? value : undefined,
+  };
+}
+
+export function toolError(message, details = undefined) {
+  const payload = details === undefined ? { error: message } : { error: message, details };
+  return {
+    content: [{ type: 'text', text: jsonText(payload) }],
+    structuredContent: payload,
+    isError: true,
+  };
+}
+
+export async function readJsonBody(request, maxBytes = MAX_JSON_BODY_BYTES) {
+  const chunks = [];
+  let total = 0;
+  for await (const chunk of request) {
+    total += chunk.length;
+    if (total > maxBytes) throw Object.assign(new Error('请求体过大'), { statusCode: 413 });
+    chunks.push(chunk);
+  }
+  if (chunks.length === 0) return null;
+  try {
+    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+  } catch {
+    throw Object.assign(new Error('请求体不是有效 JSON'), { statusCode: 400 });
+  }
+}
+
+export function writeJson(response, statusCode, data, headers = {}) {
+  const body = Buffer.from(JSON.stringify(data));
+  response.writeHead(statusCode, {
+    'content-type': 'application/json; charset=utf-8',
+    'content-length': body.length,
+    'cache-control': 'no-store',
+    ...headers,
+  });
+  response.end(body);
+}
+
+export function writeText(response, statusCode, text, contentType = 'text/plain; charset=utf-8', headers = {}) {
+  const body = Buffer.from(text);
+  response.writeHead(statusCode, {
+    'content-type': contentType,
+    'content-length': body.length,
+    'cache-control': 'no-store',
+    ...headers,
+  });
+  response.end(body);
+}
+
+export async function fileExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function findExecutable(command) {
+  if (!command) return null;
+  if (command.includes(path.sep) || (path.sep === '\\' && command.includes('/'))) {
+    return (await fileExists(command)) ? command : null;
+  }
+  const pathValue = process.env.PATH || '';
+  const extensions = process.platform === 'win32'
+    ? (process.env.PATHEXT || '.EXE;.CMD;.BAT;.COM').split(';')
+    : [''];
+  for (const directory of pathValue.split(path.delimiter)) {
+    if (!directory) continue;
+    for (const extension of extensions) {
+      const candidate = path.join(directory, command + extension.toLowerCase());
+      if (await fileExists(candidate)) return candidate;
+      const upperCandidate = path.join(directory, command + extension.toUpperCase());
+      if (await fileExists(upperCandidate)) return upperCandidate;
+    }
+  }
+  return null;
+}
+
+export function parseArgs(argv) {
+  const result = { _: [] };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (!arg.startsWith('--')) {
+      result._.push(arg);
+      continue;
+    }
+    const [rawKey, inlineValue] = arg.slice(2).split('=', 2);
+    if (inlineValue !== undefined) {
+      result[rawKey] = inlineValue;
+    } else if (argv[index + 1] && !argv[index + 1].startsWith('--')) {
+      result[rawKey] = argv[index + 1];
+      index += 1;
+    } else {
+      result[rawKey] = true;
+    }
+  }
+  return result;
+}
+
+export function normalizeSlashes(value) {
+  return value.split(path.sep).join('/');
+}
+
+export function redactEnvironment(environment) {
+  const redacted = {};
+  const secretPattern = /(token|secret|password|passwd|key|credential|cookie|authorization)/i;
+  for (const [key, value] of Object.entries(environment)) {
+    redacted[key] = secretPattern.test(key) ? '<redacted>' : value;
+  }
+  return redacted;
+}

package/src/workspace.js

@@ -0,0 +1,297 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileExists, normalizeSlashes } from './utils.js';
+import { runProcess } from './process.js';
+
+const DEFAULT_IGNORES = new Set(['.git', 'node_modules', '.next', 'dist', 'build', 'target', '.venv', 'venv', '__pycache__', '.codegraph']);
+
+function isInside(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === '' || (!relative.startsWith('..' + path.sep) && relative !== '..' && !path.isAbsolute(relative));
+}
+
+async function nearestExistingAncestor(candidate) {
+  let current = candidate;
+  while (true) {
+    try {
+      await fs.lstat(current);
+      return current;
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+      const parent = path.dirname(current);
+      if (parent === current) throw error;
+      current = parent;
+    }
+  }
+}
+
+export class Workspace {
+  constructor(root, options = {}) {
+    this.requestedRoot = path.resolve(root);
+    this.root = this.requestedRoot;
+    this.maxReadBytes = options.maxReadBytes ?? 2_097_152;
+    this.maxOutputBytes = options.maxOutputBytes ?? 1_048_576;
+    this.commandTimeoutMs = options.commandTimeoutMs ?? 120_000;
+  }
+
+  async initialize() {
+    this.root = await fs.realpath(this.requestedRoot);
+    const stat = await fs.stat(this.root);
+    if (!stat.isDirectory()) throw new Error(`工作区不是目录: ${this.root}`);
+    return this;
+  }
+
+  async resolve(userPath = '.', { allowMissing = false } = {}) {
+    if (typeof userPath !== 'string' || userPath.includes('\0')) throw new Error('路径无效');
+    const lexical = path.resolve(this.root, userPath || '.');
+    if (!isInside(this.root, lexical)) throw new Error(`路径越过工作区边界: ${userPath}`);
+
+    if (!allowMissing) {
+      const real = await fs.realpath(lexical);
+      if (!isInside(this.root, real)) throw new Error(`符号链接越过工作区边界: ${userPath}`);
+      return real;
+    }
+
+    const ancestor = await nearestExistingAncestor(lexical);
+    const realAncestor = await fs.realpath(ancestor);
+    if (!isInside(this.root, realAncestor)) throw new Error(`路径父目录越过工作区边界: ${userPath}`);
+    return lexical;
+  }
+
+  relative(absolutePath) {
+    return normalizeSlashes(path.relative(this.root, absolutePath) || '.');
+  }
+
+  async metadata(userPath) {
+    const absolute = await this.resolve(userPath);
+    const stat = await fs.lstat(absolute);
+    return {
+      path: this.relative(absolute),
+      type: stat.isFile() ? 'file' : stat.isDirectory() ? 'directory' : stat.isSymbolicLink() ? 'symlink' : 'other',
+      size: stat.size,
+      modified_at: stat.mtime.toISOString(),
+      mode: `0${(stat.mode & 0o777).toString(8)}`,
+    };
+  }
+
+  async readFile(userPath, options = {}) {
+    const absolute = await this.resolve(userPath);
+    const stat = await fs.stat(absolute);
+    if (!stat.isFile()) throw new Error(`不是文件: ${userPath}`);
+    const maxBytes = Math.min(options.maxBytes ?? this.maxReadBytes, this.maxReadBytes);
+    const buffer = await fs.readFile(absolute);
+    if (buffer.includes(0)) throw new Error(`检测到二进制文件: ${userPath}`);
+    const truncatedByBytes = buffer.length > maxBytes;
+    const text = buffer.subarray(0, maxBytes).toString('utf8');
+    const lines = text.split(/\r?\n/);
+    const startLine = Math.max(1, Number(options.startLine || 1));
+    const endLine = Math.min(lines.length, Number(options.endLine || lines.length));
+    const selected = lines.slice(startLine - 1, endLine);
+    const numbered = options.lineNumbers === false
+      ? selected.join('\n')
+      : selected.map((line, index) => `${String(startLine + index).padStart(6)}\t${line}`).join('\n');
+    return {
+      path: this.relative(absolute),
+      start_line: startLine,
+      end_line: startLine + Math.max(0, selected.length - 1),
+      total_lines_in_loaded_prefix: lines.length,
+      file_size: stat.size,
+      truncated: truncatedByBytes || endLine < lines.length,
+      content: numbered,
+    };
+  }
+
+  async listDirectory(userPath = '.', options = {}) {
+    const absolute = await this.resolve(userPath);
+    const entries = await fs.readdir(absolute, { withFileTypes: true });
+    const includeHidden = options.includeHidden === true;
+    const result = [];
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+      if (!includeHidden && entry.name.startsWith('.')) continue;
+      const itemPath = path.join(absolute, entry.name);
+      let size = null;
+      if (entry.isFile()) {
+        try { size = (await fs.stat(itemPath)).size; } catch { /* ignored */ }
+      }
+      result.push({
+        name: entry.name,
+        path: this.relative(itemPath),
+        type: entry.isFile() ? 'file' : entry.isDirectory() ? 'directory' : entry.isSymbolicLink() ? 'symlink' : 'other',
+        size,
+      });
+    }
+    return result;
+  }
+
+  async findFiles(options = {}) {
+    const base = await this.resolve(options.path || '.');
+    const limit = Math.max(1, Math.min(5000, Number(options.limit || 500)));
+    const pattern = String(options.pattern || '').toLowerCase();
+    const extensions = Array.isArray(options.extensions)
+      ? new Set(options.extensions.map((value) => String(value).replace(/^\./, '').toLowerCase()))
+      : null;
+    const results = [];
+
+    const visit = async (directory) => {
+      if (results.length >= limit) return;
+      const entries = await fs.readdir(directory, { withFileTypes: true });
+      for (const entry of entries) {
+        if (results.length >= limit) break;
+        if (entry.isDirectory() && DEFAULT_IGNORES.has(entry.name)) continue;
+        const absolute = path.join(directory, entry.name);
+        if (entry.isDirectory()) {
+          await visit(absolute);
+        } else if (entry.isFile()) {
+          const relative = this.relative(absolute);
+          if (pattern && !relative.toLowerCase().includes(pattern)) continue;
+          if (extensions) {
+            const extension = path.extname(entry.name).slice(1).toLowerCase();
+            if (!extensions.has(extension)) continue;
+          }
+          results.push(relative);
+        }
+      }
+    };
+    await visit(base);
+    return { files: results, truncated: results.length >= limit };
+  }
+
+  async searchText(options = {}) {
+    const query = String(options.query || '');
+    if (!query) throw new Error('query 不能为空');
+    const base = await this.resolve(options.path || '.');
+    const limit = Math.max(1, Math.min(2000, Number(options.limit || 200)));
+    const fixed = options.regex !== true;
+    const caseSensitive = options.caseSensitive === true;
+    const glob = Array.isArray(options.glob) ? options.glob : options.glob ? [String(options.glob)] : [];
+
+    const rgArgs = ['--line-number', '--column', '--no-heading', '--color', 'never', '--max-count', String(limit)];
+    if (fixed) rgArgs.push('--fixed-strings');
+    if (!caseSensitive) rgArgs.push('--ignore-case');
+    for (const value of glob) rgArgs.push('--glob', value);
+    rgArgs.push('--', query, base);
+
+    try {
+      const result = await runProcess('rg', rgArgs, {
+        cwd: this.root,
+        timeoutMs: this.commandTimeoutMs,
+        maxOutputBytes: this.maxOutputBytes,
+      });
+      if (result.code === 0 || result.code === 1) {
+        const matches = result.stdout.split(/\r?\n/).filter(Boolean).slice(0, limit).map((line) => {
+          const match = /^(.*?):(\d+):(\d+):(.*)$/.exec(line);
+          if (!match) return { raw: line };
+          return { path: this.relative(match[1]), line: Number(match[2]), column: Number(match[3]), text: match[4] };
+        });
+        return { engine: 'ripgrep', matches, truncated: matches.length >= limit };
+      }
+    } catch { /* fallback below */ }
+
+    return this.#searchTextFallback(base, query, { limit, fixed, caseSensitive });
+  }
+
+  async #searchTextFallback(base, query, options) {
+    const files = (await this.findFiles({ path: this.relative(base), limit: 5000 })).files;
+    const matches = [];
+    const flags = options.caseSensitive ? 'g' : 'gi';
+    const regex = options.fixed ? null : new RegExp(query, flags);
+    const needle = options.caseSensitive ? query : query.toLowerCase();
+    for (const relative of files) {
+      if (matches.length >= options.limit) break;
+      const absolute = await this.resolve(relative);
+      const stat = await fs.stat(absolute);
+      if (stat.size > this.maxReadBytes) continue;
+      const buffer = await fs.readFile(absolute);
+      if (buffer.includes(0)) continue;
+      const lines = buffer.toString('utf8').split(/\r?\n/);
+      for (let index = 0; index < lines.length && matches.length < options.limit; index += 1) {
+        const haystack = options.caseSensitive ? lines[index] : lines[index].toLowerCase();
+        const column = options.fixed ? haystack.indexOf(needle) : lines[index].search(regex);
+        if (column >= 0) matches.push({ path: relative, line: index + 1, column: column + 1, text: lines[index] });
+      }
+    }
+    return { engine: 'node-fallback', matches, truncated: matches.length >= options.limit };
+  }
+
+  async discoverInstructions(cwd = '.') {
+    const current = await this.resolve(cwd);
+    const currentStat = await fs.stat(current);
+    const directory = currentStat.isDirectory() ? current : path.dirname(current);
+    const relative = path.relative(this.root, directory);
+    const segments = relative ? relative.split(path.sep) : [];
+    const directories = [this.root];
+    let cursor = this.root;
+    for (const segment of segments) {
+      cursor = path.join(cursor, segment);
+      directories.push(cursor);
+    }
+
+    const documents = [];
+    let totalBytes = 0;
+    const maxBytes = 64 * 1024;
+    for (const item of directories) {
+      const override = path.join(item, 'AGENTS.override.md');
+      const normal = path.join(item, 'AGENTS.md');
+      const selected = (await fileExists(override)) ? override : (await fileExists(normal)) ? normal : null;
+      if (!selected) continue;
+      const buffer = await fs.readFile(selected);
+      const remaining = maxBytes - totalBytes;
+      if (remaining <= 0) break;
+      const content = buffer.subarray(0, remaining).toString('utf8');
+      totalBytes += Buffer.byteLength(content);
+      documents.push({ path: this.relative(selected), content, truncated: buffer.length > remaining });
+    }
+    return { workspace: this.root, cwd: this.relative(directory), documents };
+  }
+
+  async writeFile(userPath, content, options = {}) {
+    const absolute = await this.resolve(userPath, { allowMissing: true });
+    const exists = await fileExists(absolute);
+    if (options.createOnly && exists) throw new Error(`文件已存在: ${userPath}`);
+    if (options.overwrite === false && exists) throw new Error(`拒绝覆盖已有文件: ${userPath}`);
+    await fs.mkdir(path.dirname(absolute), { recursive: true });
+    const temporary = `${absolute}.cwmcp-${process.pid}-${Date.now()}.tmp`;
+    await fs.writeFile(temporary, String(content), 'utf8');
+    await fs.rename(temporary, absolute);
+    return { path: this.relative(absolute), bytes: Buffer.byteLength(String(content)), created: !exists };
+  }
+
+  async editFile(userPath, oldText, newText, expectedOccurrences = 1) {
+    const absolute = await this.resolve(userPath);
+    const original = await fs.readFile(absolute, 'utf8');
+    if (!oldText) throw new Error('old_text 不能为空');
+    const count = original.split(oldText).length - 1;
+    if (count !== expectedOccurrences) {
+      throw new Error(`old_text 实际出现 ${count} 次，期望 ${expectedOccurrences} 次；未写入`);
+    }
+    const updated = original.split(oldText).join(newText);
+    await this.writeFile(this.relative(absolute), updated, { overwrite: true });
+    return { path: this.relative(absolute), replacements: count, bytes_before: Buffer.byteLength(original), bytes_after: Buffer.byteLength(updated) };
+  }
+
+  async createDirectory(userPath) {
+    const absolute = await this.resolve(userPath, { allowMissing: true });
+    await fs.mkdir(absolute, { recursive: true });
+    return { path: this.relative(absolute) };
+  }
+
+  async movePath(fromPath, toPath, overwrite = false) {
+    const from = await this.resolve(fromPath);
+    const to = await this.resolve(toPath, { allowMissing: true });
+    if (!overwrite && await fileExists(to)) throw new Error(`目标已存在: ${toPath}`);
+    await fs.mkdir(path.dirname(to), { recursive: true });
+    if (overwrite && await fileExists(to)) await fs.rm(to, { recursive: true, force: true });
+    await fs.rename(from, to);
+    return { from: this.relative(from), to: this.relative(to) };
+  }
+
+  async deletePath(userPath, recursive = false) {
+    const absolute = await this.resolve(userPath);
+    if (absolute === this.root) throw new Error('拒绝删除工作区根目录');
+    const stat = await fs.lstat(absolute);
+    if (stat.isDirectory() && !recursive) throw new Error('删除目录必须设置 recursive=true');
+    await fs.rm(absolute, { recursive, force: false });
+    return { path: this.relative(absolute), deleted: true, type: stat.isDirectory() ? 'directory' : 'file' };
+  }
+}