@znmin/claude-remote-cli 0.2.5 → 0.2.7

package/README.md

@@ -25,10 +25,10 @@ npm install -g git+https://github.com/znmin/claude-remote-cli.git
 也可以从已下载的分发包安装：
 
 ```bash
-npm install -g ./znmin-claude-remote-cli-0.2.5.tgz
+npm install -g ./znmin-claude-remote-cli-0.2.7.tgz
 ```
 
-若系统 npm 全局目录不可写，可使用 `npm install -g --prefix "$HOME/.local" ./znmin-claude-remote-cli-0.2.5.tgz`，并确保 `~/.local/bin` 在 PATH 中；卸载时也使用相同的 `--prefix`。
+若系统 npm 全局目录不可写，可使用 `npm install -g --prefix "$HOME/.local" ./znmin-claude-remote-cli-0.2.7.tgz`，并确保 `~/.local/bin` 在 PATH 中；卸载时也使用相同的 `--prefix`。
 
 npm 中不带作用域的 `claude-remote-cli` 属于其他项目。本项目使用独立的 `@znmin/claude-remote-cli` 作用域包名；请安装完整包名，或使用上述 GitHub 地址及本项目分发的 `.tgz` 文件。
 
@@ -117,11 +117,22 @@ claude-remote configure my-server --mode local
 
 切换模式不会自动停止已有后台同步。若从旧模式切换且不希望旧项目继续同步，先运行 `claude-remote stop --all`。本地模式本身不创建同步会话，不上传整个项目。
 
-无需用户手工配置 MCP，默认提供 18 个工具：
+无需用户手工配置 MCP，默认提供 24 个工具：
 
 - 项目与文件：`workspace_info`、`read_file`、`write_file`、`edit_file`、`list_directory`、`search_text`。
 - 本地终端：`run_command`、`process_status`、`list_processes`、`stop_process`。
-- 浏览器：`browser_open`、`browser_snapshot`、`browser_click`、`browser_fill`、`browser_press`、`browser_screenshot`、`browser_logs`、`browser_close`。
+- 浏览器：`browser_open`、`browser_navigate`、`browser_snapshot`、`browser_click`、`browser_fill`、`browser_press`、`browser_select`、`browser_hover`、`browser_scroll`、`browser_wait_for`、`browser_evaluate`、`browser_screenshot`、`browser_logs`、`browser_close`。
+
+0.2.6 起：
+
+- `read_file` 单次返回内容有字符上限，超出时提前结束并给出 `next_offset`，从该行继续读取；行数统计不再把末尾换行算作一行。
+- 命令输出默认返回末尾 8000 字符；`process_status` 可用 `stream`、`offset`、`limit` 从头分页读取（每个输出流保留最近 256 KiB）。
+- `search_text` 支持 `regex`（正则）和 `glob`（如 `*.ts`、`src/**/*.{js,jsx}`）；在 Git 仓库中遵循 `.gitignore`，无权限读取的目录会被跳过并计数，不再导致整次搜索失败。
+- 浏览器元素选择器在多次快照间保持不变；快照包含 iframe（选择器形如 `frame=1 >> …`）和开放的 Shadow DOM 元素；截图支持整页和单个元素。
+- 本地项目的 `CLAUDE.md`、`.claude/CLAUDE.md`、`CLAUDE.local.md` 在启动时读取并放入系统提示（合计最多 64 KiB），不再依赖模型自行读取。
+- 关闭终端窗口（SIGHUP）或被 `kill`（SIGTERM）时也会清理浏览器、后台命令、SSH 隧道和服务器临时文件。
+- 0.2.7 起，SSH 断线等原因导致远程 Claude 异常结束时，会自动关闭它遗留的鼠标上报、焦点事件、括号粘贴和扩展键盘等终端模式，避免移动鼠标或按键时输出乱码。若仍显示异常（例如停留在全屏界面），可运行 `reset`。
+- 启动时浏览器检查与 SSH 连接并行，浏览器已就绪时不再调用 Playwright 安装程序；服务器上的版本检查和配置写入合并为一次往返。
 
 Git、npm、pnpm、Python、Go、Docker、数据库 CLI、`gh` 等共用本地终端，不需要逐项适配，仍需在本机安装并具备必要的登录、连接配置及权限。终端继承启动用户环境和登录 shell，默认工作目录为当前项目。长任务使用后台进程，再查询日志和停止；退出会话会停止仍受本工具管理的进程组，自行 daemonize 或逃离原进程组的程序不在自动清理保证内。
 
@@ -144,7 +155,9 @@ Linux 上仍需安装 Playwright 所需的系统共享库，有窗口模式还
 
 本地模式要求服务器允许 SSH TCP 转发，Claude Code 版本至少 **2.1.248**；已有版本过旧时会提示在服务器运行 `claude update`。每个会话创建仅监听本机回环地址的工具服务、随机令牌和 SSH 反向隧道；令牌通过 SSH 标准输入写入服务器 0600 临时配置，不出现在命令行参数或同步项目中。退出时清理配置、连接和浏览器。
 
-启动时使用 `--restricted`、`--tools "WebSearch,WebFetch"`、`--strict-mcp-config`，限定工具和设置来源、关闭普通 hooks。0.2.2 起恢复 `/config`、`/model`、`/help` 等内置交互命令，不再使用禁用整个命令菜单的 `--disable-slash-commands`；通过 `disableSkillShellExecution` 和 `disableBundledSkills` 单独关闭技能内联 shell 和内置技能工作流。恢复菜单不代表所有依赖服务器项目目录或原生工具的命令都适用于本地模式。设置面板修改的是服务器上的 Claude 配置；受限模式仍只加载托管配置和本次 `--settings`，不会恢复读取普通用户/项目 settings.json，因此偏好设置的跨会话持久化仍受该限制影响，可用 `claude --model sonnet` 明确指定启动模型。保留服务器上的订阅认证，不使用跳过 OAuth 的 `--bare`。本地连接失效时不会将文件或命令操作退回服务器执行。支持 `--continue`、`--resume`、`--model`、`--effort`、`-p` 和输入/输出格式；暂不接受替换工具配置、加载插件、切换云会话等参数。
+启动时使用 `--restricted`、`--tools "WebSearch,WebFetch"`、`--strict-mcp-config`，限定工具和设置来源、关闭普通 hooks。0.2.2 起恢复 `/config`、`/model`、`/help` 等内置交互命令，不再使用禁用整个命令菜单的 `--disable-slash-commands`；通过 `disableSkillShellExecution` 和 `disableBundledSkills` 单独关闭技能内联 shell 和内置技能工作流。恢复菜单不代表所有依赖服务器项目目录或原生工具的命令都适用于本地模式。设置面板修改的是服务器上的 Claude 配置；受限模式仍只加载托管配置和本次 `--settings`，不会恢复读取普通用户/项目 settings.json，因此偏好设置的跨会话持久化仍受该限制影响，可用 `claude --model sonnet` 明确指定启动模型。保留服务器上的订阅认证，不使用跳过 OAuth 的 `--bare`。本地连接失效时不会将文件或命令操作退回服务器执行。支持 `--continue`、`--resume`、`--model`、`--effort`、`--name`、`--fallback-model`、`-p` 和输入/输出格式；`--permission-mode` 支持 `default`、`manual`、`acceptEdits`、`plan`、`auto`、`dontAsk`（受限模式本身拒绝 `bypassPermissions`）。暂不接受替换工具配置、加载插件、切换云会话等参数。
+
+本地模式的路由规则、本地 CLAUDE.md 和用户传入的 `--append-system-prompt` 内容合并为一个文件，通过 SSH 标准输入写入服务器临时目录（权限 0600），再用 `--append-system-prompt-file` 加载；用户的追加内容排在路由规则之后，不会替换它。退出时与 MCP 配置一起删除。
 
 这是工具路由约束，不是对 Claude Code 主进程的系统隔离。认证、会话和日志仍在服务器，管理员管理策略继续生效。文件内容、命令结果和截图会经过服务器交给模型，不整体同步不代表数据不离开本机。
 
@@ -156,7 +169,7 @@ claude-remote flush                # 等待当前项目完成一次同步
 claude-remote stop                 # 停止当前目录在当前配置服务器上的同步
 claude-remote stop --all           # 停止本工具的所有同步会话
 claude-remote stop --name 名称     # 按 status 中的名称停止旧服务器上的映射
-claude-remote doctor               # 检查本地安装和服务器配置，不连接服务器
+claude-remote doctor               # 检查本地安装（含 Node 版本、SSH 工具、本地浏览器缓存）和服务器配置，不连接服务器
 claude-remote install-sync         # 手动重试同步工具准备
 claude-remote --help
 ```
@@ -216,13 +229,14 @@ CLAUDE_REMOTE_DEBUG=1 claude
 
 ```bash
 npm ci --ignore-scripts
+npm run lint
 npm test
 
 # 可选：真实本地同步与受控浏览器测试
 CLAUDE_REMOTE_INTEGRATION=1 CLAUDE_REMOTE_BROWSER_TEST=1 npm test
 
 npm pack
-npm install -g ./znmin-claude-remote-cli-0.2.5.tgz
+npm install -g ./znmin-claude-remote-cli-0.2.7.tgz
 
 # 确定包名、版本和使用条款后，使用有发布权限的 npm 账号发布
 npm login

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@znmin/claude-remote-cli",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "Run Claude Code on an SSH server with local filesystem, terminal and browser tools, or remote bidirectional sync",
   "type": "module",
   "license": "UNLICENSED",
@@ -28,8 +28,9 @@
   ],
   "scripts": {
     "postinstall": "node scripts/postinstall.js",
+    "lint": "eslint .",
     "test": "node --test test/*.test.js",
-    "prepublishOnly": "npm test"
+    "prepublishOnly": "npm run lint && npm test"
   },
   "keywords": [
     "claude",
@@ -55,5 +56,10 @@
   "homepage": "https://github.com/znmin/claude-remote-cli#readme",
   "bugs": {
     "url": "https://github.com/znmin/claude-remote-cli/issues"
+  },
+  "devDependencies": {
+    "@eslint/js": "9.39.5",
+    "eslint": "9.39.5",
+    "globals": "17.14.0"
   }
 }

package/src/cli.js

@@ -2,7 +2,7 @@ import { parseArgs } from 'node:util';
 import { createInterface } from 'node:readline/promises';
 import { Client, DEFAULTS } from './client.js';
 import { cachedBinary, ensureMutagen, VERSION } from './installer.js';
-import { exists, readJSON, which } from './system.js';
+import { exists, installSignalHandlers, readJSON, which } from './system.js';
 import { readFileSync } from 'node:fs';
 
 const PACKAGE = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
@@ -118,8 +118,16 @@ export async function main(asClaude, args = process.argv.slice(2), client = new
     await installBrowser(client.log, { debug: client.debug }); console.log('浏览器已就绪。'); return 0;
   }
   if (action === 'doctor') {
-    console.log(`Node.js：${process.version}\n平台：${process.platform}/${process.arch}`);
-    for (const tool of ['ssh', 'scp', 'tar']) console.log(`${tool}：${await which(tool, client.env.PATH) || '未安装'}`);
+    const [major, minor] = process.versions.node.split('.').map(Number);
+    const nodeOk = major > 20 || major === 20 && minor >= 11;
+    console.log(`Node.js：${process.version}${nodeOk ? '' : '（需要 20.11 或更高版本）'}\n平台：${process.platform}/${process.arch}`);
+    for (const tool of ['ssh', 'ssh-keygen', 'scp', 'tar']) console.log(`${tool}：${await which(tool, client.env.PATH) || '未安装'}`);
+    try {
+      const { browserReady } = await import('./local/browser.js');
+      const { chromium } = await import('playwright');
+      const ready = await browserReady();
+      console.log(`本地浏览器：${ready ? chromium.executablePath() : '尚未准备（本地模式首次启动或 claude-remote install-browser 时下载）'}`);
+    } catch (error) { console.log('本地浏览器：无法检查（' + error.message + '）'); }
     const cached = cachedBinary(client.env);
     console.log(`同步工具：${client.env.CLAUDE_REMOTE_MUTAGEN || (await exists(cached) ? cached : await which('mutagen', client.env.PATH)) || '首次使用时自动下载'}（目标版本 ${VERSION}）`);
     const config = await readJSON(client.configFile, {});
@@ -131,6 +139,7 @@ export async function main(asClaude, args = process.argv.slice(2), client = new
 }
 
 export async function entry(asClaude) {
+  installSignalHandlers();
   try { process.exitCode = await main(asClaude); }
   catch (error) {
     console.error('claude-remote：' + error.message);

package/src/client.js

@@ -2,7 +2,7 @@ import * as fs from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
 import { createHash, randomUUID } from 'node:crypto';
-import { execute, exists, quote, readJSON, shellJoin, which, withLock, writeJSON } from './system.js';
+import { execute, exists, quote, readJSON, restoreTerminal, shellJoin, which, withLock, writeJSON } from './system.js';
 import { ensureMutagen } from './installer.js';
 import { ensureRemoteClaude, remoteEnvironment as prefix } from './remote-claude.js';
 import { sshArgs } from './ssh.js';
@@ -67,6 +67,7 @@ export class Client {
       if (this.env.CLAUDE_REMOTE_DEBUG === '1') this.log(...messages);
     };
     this.tty = options.tty ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
+    this.restoreTerminal = options.restoreTerminal || (() => restoreTerminal());
   }
 
   async configure(input) {
@@ -204,6 +205,8 @@ export class Client {
     try {
       code = (await this.remote(config, prefix + 'cd -- ' + remotePath(item.remote) +
         ' && exec ' + shellJoin([config.claude, ...extra]), true)).code;
+      // A dropped connection leaves the remote UI's terminal modes switched on.
+      if (code !== 0) this.restoreTerminal();
     } finally {
       try { await this.flush(item.name); }
       catch (error) {

package/src/local/browser.js

@@ -1,3 +1,4 @@
+import * as fs from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
 import { createRequire } from 'node:module';
@@ -6,33 +7,93 @@ import { chromium } from 'playwright';
 import { execute, exists, withLock } from '../system.js';
 
 const require = createRequire(import.meta.url);
+const PLAYWRIGHT_VERSION = require('playwright/package.json').version;
 let preparation;
 
-export async function installBrowser(log = console.error, { debug = () => {} } = {}) {
+const cacheDirectory = () => process.env.CLAUDE_REMOTE_CACHE_DIR || path.join(os.homedir(), '.cache', 'claude-remote');
+export const browserMarker = () => path.join(cacheDirectory(), `browser-ready-${PLAYWRIGHT_VERSION}`);
+
+// The marker records which executable a completed install produced, so a
+// warm start skips spawning the Playwright installer entirely.
+export async function browserReady() {
+  const executable = chromium.executablePath();
+  try { return (await fs.readFile(browserMarker(), 'utf8')).trim() === executable && await exists(executable); }
+  catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+}
+
+export async function installBrowser(log = console.error, { debug = () => {}, force = false } = {}) {
+  if (!force && await browserReady()) { debug('浏览器缓存可用：' + chromium.executablePath()); return; }
+  if (force) preparation = null;
   if (!preparation) preparation = (async () => {
     const cli = path.join(path.dirname(require.resolve('playwright/package.json')), 'cli.js');
     // Keep the lock outside Playwright's cache: its installer replaces browser directories.
-    const lock = path.join(process.env.CLAUDE_REMOTE_CACHE_DIR || path.join(os.homedir(), '.cache', 'claude-remote'), 'browser-install');
-    await withLock(lock, async () => {
+    await withLock(path.join(cacheDirectory(), 'browser-install'), async () => {
+      if (!force && await browserReady()) return;
       if (!await exists(chromium.executablePath())) log('正在下载浏览器…');
       else debug('检查浏览器缓存：' + chromium.executablePath());
       // The CLI checks completion markers and prepares headed AND headless binaries.
       const result = await execute(process.execPath, [cli, 'install', 'chromium'], { capture: true, timeout: 600000 });
       if (!await exists(chromium.executablePath())) throw new Error('浏览器安装未完成：' + result.stderr);
+      await fs.mkdir(cacheDirectory(), { recursive: true });
+      await fs.writeFile(browserMarker(), chromium.executablePath() + '\n');
     });
   })().catch(error => { preparation = null; throw error; });
   await preparation;
 }
 
+// Runs inside each frame. Refs persist on elements across snapshots; the
+// per-document token keeps refs from a previous page from matching new ones.
+function collectElements({ limit, textLimit }) {
+  const attribute = 'data-claude-remote-ref';
+  window.__claudeRemote ||= { token: Math.random().toString(36).slice(2, 7), next: 0 };
+  const state = window.__claudeRemote;
+  const query = 'a,button,input,textarea,select,summary,[role="button"],[role="link"],[role="checkbox"],' +
+    '[role="radio"],[role="tab"],[role="menuitem"],[role="option"],[role="switch"],[contenteditable="true"],[onclick]';
+  const found = [];
+  const visit = root => {
+    for (const element of root.querySelectorAll(query)) found.push(element);
+    for (const element of root.querySelectorAll('*')) if (element.shadowRoot) visit(element.shadowRoot);
+  };
+  visit(document);
+  const elements = [];
+  for (const element of found) {
+    if (elements.length >= limit) break;
+    if (!element.getClientRects().length) continue;
+    let ref = element.getAttribute(attribute);
+    if (!ref || !ref.startsWith(state.token + '-')) {
+      ref = `${state.token}-${++state.next}`;
+      element.setAttribute(attribute, ref);
+    }
+    const item = { selector: `[${attribute}="${ref}"]`, tag: element.tagName.toLowerCase(),
+      text: (element.innerText || element.getAttribute('aria-label') || element.getAttribute('placeholder') ||
+        element.getAttribute('title') || '').trim().slice(0, 200) };
+    const type = element.getAttribute('type'); if (type) item.type = type;
+    const name = element.getAttribute('name'); if (name) item.name = name;
+    if (element.tagName === 'A' && element.getAttribute('href')) item.href = element.getAttribute('href').slice(0, 200);
+    if ('value' in element && typeof element.value === 'string' && element.value && type !== 'password')
+      item.value = element.value.slice(0, 200);
+    if (element.disabled) item.disabled = true;
+    if (element.checked) item.checked = true;
+    elements.push(item);
+  }
+  return { text: (document.body?.innerText || '').slice(0, textLimit), elements, more: found.length > elements.length };
+}
+
 export class Browser {
   constructor({ headless = false, log = console.error } = {}) {
-    this.headless = headless; this.log = log; this.pages = new Map(); this.logs = new Map(); this.reference = 0;
+    this.headless = headless; this.log = log; this.pages = new Map(); this.logs = new Map();
   }
 
   async start() {
     if (!this.starting) this.starting = (async () => {
       await installBrowser(this.log);
-      this.browser = await chromium.launch({ headless: this.headless });
+      try { this.browser = await chromium.launch({ headless: this.headless }); }
+      catch (error) {
+        // The cache marker may be stale (e.g. browsers removed by hand): reinstall once.
+        if (!/Executable doesn't exist|executable/i.test(error.message)) throw error;
+        await installBrowser(this.log, { force: true });
+        this.browser = await chromium.launch({ headless: this.headless });
+      }
       this.browser.on('disconnected', () => { this.starting = null; this.context = null; this.browser = null; this.pages.clear(); this.logs.clear(); });
       this.context = await this.browser.newContext({ viewport: { width: 1280, height: 800 } });
     })().catch(error => { this.starting = null; throw error; });
@@ -45,6 +106,15 @@ export class Browser {
     return page;
   }
 
+  // Selectors from iframes look like "frame=2 >> [data-claude-remote-ref=...]".
+  locator(page, selector) {
+    const match = selector.match(/^frame=(\d+) >> ([\s\S]+)$/);
+    if (!match) return page.locator(selector);
+    const frame = page.frames()[Number(match[1])];
+    if (!frame || frame.isDetached()) throw new Error('找不到对应 iframe，请重新调用 browser_snapshot。');
+    return frame.locator(match[2]);
+  }
+
   async open(url = 'about:blank') {
     await this.start();
     if (this.pages.size >= 16) throw new Error('浏览器页面过多，请先调用 browser_close 关闭部分页面。');
@@ -52,7 +122,7 @@ export class Browser {
     this.pages.set(id, page); this.logs.set(id, []);
     const record = message => {
       const entries = this.logs.get(id); if (!entries) return;
-      entries.push(message.slice(0, 1000)); if (entries.length > 100) entries.shift();
+      entries.push(message.slice(0, 1000)); if (entries.length > 200) entries.shift();
     };
     page.on('console', message => record(`${message.type()}: ${message.text()}`));
     page.on('pageerror', error => record('pageerror: ' + error.message));
@@ -63,38 +133,93 @@ export class Browser {
     return { ...await this.snapshot(id), ...(navigationError ? { navigation_error: navigationError } : {}) };
   }
 
+  async navigate(id, { url, action }) {
+    const page = this.page(id);
+    const options = { waitUntil: 'domcontentloaded', timeout: 30000 };
+    let navigationError;
+    try {
+      if (url) await page.goto(url, options);
+      else if (action === 'back') await page.goBack(options);
+      else if (action === 'forward') await page.goForward(options);
+      else if (action === 'reload') await page.reload(options);
+      else throw new Error('请提供 url，或 action 为 back、forward、reload 之一。');
+    } catch (error) {
+      if (!url && !action) throw error;
+      navigationError = error.message;
+    }
+    return { ...await this.snapshot(id), ...(navigationError ? { navigation_error: navigationError } : {}) };
+  }
+
   async snapshot(id) {
-    const page = this.page(id), generation = ++this.reference;
-    const state = await page.evaluate(generation => {
-      const elements = [...document.querySelectorAll('a,button,input,textarea,select,[role="button"],[contenteditable="true"]')]
-        .filter(element => element.getClientRects().length).slice(0, 200).map((element, i) => {
-          const ref = `r${generation}-${i}`;
-          element.setAttribute('data-claude-remote-ref', ref);
-          return { selector: `[data-claude-remote-ref="${ref}"]`, tag: element.tagName.toLowerCase(),
-            text: (element.innerText || element.getAttribute('aria-label') || element.getAttribute('placeholder') || '').slice(0, 200),
-            type: element.getAttribute('type') || undefined };
-        });
-      return { text: (document.body?.innerText || '').slice(0, 12000), elements };
-    }, generation);
-    return { page_id: id, url: page.url(), title: await page.title(), ...state };
+    const page = this.page(id);
+    const main = await page.mainFrame().evaluate(collectElements, { limit: 200, textLimit: 12000 });
+    const frames = [];
+    const all = page.frames();
+    for (let index = 0; index < all.length && frames.length < 10; index++) {
+      const frame = all[index];
+      if (frame === page.mainFrame() || frame.isDetached()) continue;
+      try {
+        const state = await frame.evaluate(collectElements, { limit: 50, textLimit: 2000 });
+        frames.push({ frame: index, url: frame.url(), text: state.text,
+          elements: state.elements.map(element => ({ ...element, selector: `frame=${index} >> ${element.selector}` })) });
+      } catch { /* detached or not yet loaded */ }
+    }
+    return { page_id: id, url: page.url(), title: await page.title(), text: main.text, elements: main.elements,
+      ...(main.more ? { more_elements: true } : {}), ...(frames.length ? { frames } : {}) };
   }
 
   async action(id, action, selector, value) {
     const page = this.page(id);
-    if (action === 'click') await page.locator(selector).click({ timeout: 15000 });
-    else if (action === 'fill') await page.locator(selector).fill(value, { timeout: 15000 });
+    const options = { timeout: 15000 };
+    if (action === 'click') await this.locator(page, selector).click(options);
+    else if (action === 'fill') await this.locator(page, selector).fill(value, options);
+    else if (action === 'hover') await this.locator(page, selector).hover(options);
+    else if (action === 'select') await this.locator(page, selector).selectOption(value, options);
     else if (action === 'press') {
-      if (selector) await page.locator(selector).press(value, { timeout: 15000 });
+      if (selector) await this.locator(page, selector).press(value, options);
       else await page.keyboard.press(value);
     }
     return this.snapshot(id);
   }
 
-  async screenshot(id) {
-    const buffer = await this.page(id).screenshot({ type: 'png', timeout: 15000 });
+  async scroll(id, { selector, x = 0, y = 0 }) {
+    const page = this.page(id);
+    if (selector) await this.locator(page, selector).scrollIntoViewIfNeeded({ timeout: 15000 });
+    else {
+      // mouse.wheel does not wait for the scroll to happen; give it a moment.
+      await page.mouse.wheel(x, y);
+      await page.waitForTimeout(200);
+    }
+    return this.snapshot(id);
+  }
+
+  async waitFor(id, { selector, text, state = 'visible', timeout = 10000 }) {
+    const page = this.page(id);
+    if (selector) await this.locator(page, selector).first().waitFor({ state, timeout });
+    else if (text) await page.getByText(text).first().waitFor({ state, timeout });
+    else await page.waitForLoadState('load', { timeout });
+    return this.snapshot(id);
+  }
+
+  async evaluate(id, expression) {
+    const result = await this.page(id).evaluate(expression);
+    return { page_id: id, result: result === undefined ? null : result };
+  }
+
+  async screenshot(id, { fullPage = false, selector } = {}) {
+    const page = this.page(id);
+    const options = { type: 'png', timeout: 15000 };
+    const buffer = selector ? await this.locator(page, selector).screenshot(options)
+      : await page.screenshot({ ...options, fullPage });
     return { content: [{ type: 'image', data: buffer.toString('base64'), mimeType: 'image/png' }] };
   }
 
+  readLogs(id, limit = 20) {
+    this.page(id);
+    const logs = this.logs.get(id);
+    return { logs: logs.slice(-limit), total: logs.length, truncated: logs.length > limit };
+  }
+
   async closePage(id) {
     await this.page(id).close(); this.pages.delete(id); this.logs.delete(id);
     return { closed: id };

package/src/local/processes.js

@@ -2,18 +2,47 @@ import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { quote } from '../system.js';
 
+// Characters retained per stream; older output is dropped but offsets stay absolute.
 const LIMIT = 256 * 1024;
+const PREVIEW = 8000;
 const delay = ms => new Promise(resolve => setTimeout(resolve, ms));
 
 export class Processes {
   constructor(workspace, env = process.env) { this.workspace = workspace; this.env = env; this.jobs = new Map(); }
 
-  status(id) {
+  job(id) {
     const job = this.jobs.get(id);
     if (!job) throw new Error('找不到本会话的进程。');
+    return job;
+  }
+
+  meta(id) {
+    const job = this.job(id);
     return { job_id: id, pid: job.child.pid, running: !job.ended, exit_code: job.code ?? null,
-      signal: job.signal ?? null, timed_out: Boolean(job.timedOut), stdout: job.stdout.slice(-8000), stderr: job.stderr.slice(-8000),
-      output_truncated: job.truncated || job.stdout.length > 8000 || job.stderr.length > 8000, cwd: job.cwd };
+      signal: job.signal ?? null, timed_out: Boolean(job.timedOut), cwd: job.cwd };
+  }
+
+  // Without a stream: the last PREVIEW characters of stdout and stderr.
+  // With a stream: a page starting at an absolute character offset.
+  status(id, { stream, offset, limit = PREVIEW } = {}) {
+    const job = this.job(id);
+    const totals = { stdout_total: job.stdout.dropped + job.stdout.text.length,
+      stderr_total: job.stderr.dropped + job.stderr.text.length };
+    if (!stream) {
+      const truncated = job.stdout.dropped > 0 || job.stderr.dropped > 0 ||
+        job.stdout.text.length > PREVIEW || job.stderr.text.length > PREVIEW;
+      return { ...this.meta(id), stdout: job.stdout.text.slice(-PREVIEW), stderr: job.stderr.text.slice(-PREVIEW),
+        output_truncated: truncated, ...totals,
+        ...(truncated ? { hint: '仅返回末尾输出。用 process_status 的 stream、offset、limit 参数分页读取更早的内容。' } : {}) };
+    }
+    const buffer = job[stream];
+    const total = buffer.dropped + buffer.text.length;
+    const start = Math.max(offset ?? 0, buffer.dropped);
+    const text = buffer.text.slice(start - buffer.dropped, start - buffer.dropped + limit);
+    const next = start + text.length;
+    return { ...this.meta(id), stream, offset: start, text, total, available_from: buffer.dropped,
+      next_offset: next < total ? next : null,
+      ...(offset !== undefined && offset < buffer.dropped ? { note: `前 ${buffer.dropped} 个字符已丢弃，仅保留最近 ${LIMIT} 个字符。` } : {}) };
   }
 
   async run(command, cwd = '.', timeoutMs = 30000, background = false, signal) {
@@ -25,15 +54,21 @@ export class Processes {
       cwd: directory, env: this.env, detached: true, stdio: ['ignore', 'pipe', 'pipe']
     });
     const id = randomUUID();
-    const job = { child, cwd: directory, stdout: '', stderr: '', truncated: false, ended: false };
+    const job = { child, cwd: directory, ended: false,
+      stdout: { text: '', dropped: 0 }, stderr: { text: '', dropped: 0 } };
     this.jobs.set(id, job);
     job.done = new Promise(resolve => {
       child.stdout.setEncoding('utf8'); child.stderr.setEncoding('utf8');
       for (const stream of ['stdout', 'stderr']) child[stream].on('data', chunk => {
-        if (job[stream].length + chunk.length > LIMIT) job.truncated = true;
-        job[stream] = (job[stream] + chunk).slice(-LIMIT);
+        const buffer = job[stream];
+        buffer.text += chunk;
+        if (buffer.text.length > LIMIT) {
+          const excess = buffer.text.length - LIMIT;
+          buffer.text = buffer.text.slice(excess);
+          buffer.dropped += excess;
+        }
       });
-      child.once('error', error => { job.stderr += error.message; job.code = 127; job.ended = true; resolve(); });
+      child.once('error', error => { job.stderr.text += error.message; job.code = 127; job.ended = true; resolve(); });
       child.once('close', (code, sig) => { job.code = code; job.signal = sig; job.ended = true; resolve(); });
     });
     if (background) {
@@ -57,8 +92,7 @@ export class Processes {
   }
 
   async stop(id) {
-    const job = this.jobs.get(id);
-    if (!job) throw new Error('找不到本会话的进程。');
+    const job = this.job(id);
     if (job.ended) return this.status(id);
     // Kill the owned group even if its parent shell has already exited.
     this.killGroup(job, 'SIGTERM');
@@ -68,9 +102,13 @@ export class Processes {
     return this.status(id);
   }
 
-  list() { return [...this.jobs.keys()].map(id => {
-    const { stdout, stderr, ...status } = this.status(id);
-    return { ...status, stdout_characters: this.jobs.get(id).stdout.length, stderr_characters: this.jobs.get(id).stderr.length };
-  }); }
+  list() {
+    return [...this.jobs.keys()].map(id => {
+      const job = this.jobs.get(id);
+      return { ...this.meta(id), stdout_characters: job.stdout.dropped + job.stdout.text.length,
+        stderr_characters: job.stderr.dropped + job.stderr.text.length };
+    });
+  }
+
   async close() { await Promise.allSettled([...this.jobs.keys()].map(id => this.stop(id))); }
 }

package/src/local/server.js

@@ -2,6 +2,7 @@ import http from 'node:http';
 import os from 'node:os';
 import { randomBytes, timingSafeEqual } from 'node:crypto';
 import * as fs from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { z } from 'zod';
@@ -9,13 +10,32 @@ import { Workspace } from './workspace.js';
 import { Processes } from './processes.js';
 import { Browser } from './browser.js';
 
-const text = value => {
-  const output = JSON.stringify(value);
-  // Claude persists very large MCP results on the server; local mode cannot use its Read tool.
-  const bounded = output.length <= 40000 ? output : JSON.stringify({ truncated: true,
-    message: '结果过大，请缩小查询范围或分页读取。本次只返回预览。', preview: output.slice(0, 16000) });
-  return { content: [{ type: 'text', text: bounded }] };
+const PACKAGE = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
+const MAX_RESULT = 40000;
+
+const shrink = (value, size) => {
+  if (typeof value === 'string')
+    return value.length > size ? value.slice(0, size) + `…[已截断 ${value.length - size} 字符]` : value;
+  if (Array.isArray(value)) return value.map(item => shrink(item, size));
+  if (value && typeof value === 'object')
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, shrink(item, size)]));
+  return value;
 };
+
+// Claude persists very large MCP results on the server, where local mode cannot
+// read them back. Keep the result structured and shorten its longest strings.
+export function boundedJSON(value) {
+  const output = JSON.stringify(value);
+  if (output.length <= MAX_RESULT) return output;
+  const message = '结果过大，已截断较长字段。请缩小查询范围或分页读取。';
+  for (let size = 16000; size >= 100; size = Math.floor(size / 2)) {
+    const shrunk = JSON.stringify({ ...shrink(value, size), truncated: true, message });
+    if (shrunk.length <= MAX_RESULT) return shrunk;
+  }
+  return JSON.stringify({ truncated: true, message, preview: output.slice(0, 16000) });
+}
+
+const text = value => ({ content: [{ type: 'text', text: boundedJSON(value) }] });
 const file = z.string().min(1).max(4096);
 const pageId = z.string().min(1);
 const selector = z.string().min(1).max(4000);
@@ -29,7 +49,7 @@ export async function startLocalServer({ root, env = process.env, headless = fal
   let closing = false;
 
   function createServer() {
-    const server = new McpServer({ name: 'claude-local-tools', version: '0.2.0' });
+    const server = new McpServer({ name: 'claude-local-tools', version: PACKAGE.version });
     const register = (name, description, inputSchema, handler, readOnly = false) => {
       server.registerTool(name, { description, inputSchema,
         annotations: { readOnlyHint: readOnly, idempotentHint: readOnly } }, async (args, extra) => {
@@ -42,7 +62,7 @@ export async function startLocalServer({ root, env = process.env, headless = fal
     register('workspace_info', 'Describe the LOCAL computer and project. All tools execute on this computer, not the SSH server.', {},
       () => ({ root: workspace.root, platform: os.platform(), shell: env.SHELL || '/bin/bash',
         instructions: 'Use local absolute or project-relative paths. Use background=true for development servers, then process_status for logs. Browser selectors come from browser_snapshot. Terminal commands run as the local user.' }), true);
-    register('read_file', 'Read a LOCAL project text file, with line numbers and a SHA-256 for safe replacement.', {
+    register('read_file', 'Read a LOCAL project text file, with line numbers and a SHA-256 for safe replacement. Large reads stop early and return next_offset to continue from.', {
       path: file, offset: z.number().int().min(1).default(1), limit: z.number().int().min(1).max(2000).default(200)
     }, args => workspace.read(args.path, args.offset, args.limit), true);
     register('write_file', 'Create a LOCAL file. Replacing an existing file requires its current SHA-256 from read_file.', {
@@ -53,16 +73,19 @@ export async function startLocalServer({ root, env = process.env, headless = fal
     }, args => workspace.edit(args.path, args.old_text, args.new_text, args.replace_all));
     register('list_directory', 'List LOCAL project files and directories, including hidden entries.', { path: file.default('.') },
       args => workspace.list(args.path), true);
-    register('search_text', 'Search literal text in LOCAL project files. Skips .git, node_modules, .venv, binary and large files.', {
+    register('search_text', 'Search text in LOCAL project files. Literal by default; set regex=true for JavaScript regular expressions. glob filters files (e.g. "*.ts", "src/**/*.{js,jsx}"). Follows .gitignore inside Git repositories and skips .git, node_modules, .venv, binary and large files.', {
       pattern: z.string().min(1).max(1000), path: file.default('.'), max_results: z.number().int().min(1).max(500).default(100),
-      case_sensitive: z.boolean().default(true)
-    }, args => workspace.search(args.pattern, args.path, args.max_results, args.case_sensitive), true);
+      case_sensitive: z.boolean().default(true), regex: z.boolean().default(false), glob: z.string().min(1).max(500).optional()
+    }, args => workspace.search(args.pattern, args.path, args.max_results, args.case_sensitive,
+      { regex: args.regex, glob: args.glob }), true);
     register('run_command', 'Run a shell command on the LOCAL computer in the project. Git/npm/Docker and other installed CLI tools share this tool. For servers or long jobs set background=true; use process_status for output and stop_process to stop.', {
       command: z.string().min(1).max(100000), cwd: file.default('.'), timeout_ms: z.number().int().min(100).max(120000).default(30000),
       background: z.boolean().default(false)
     }, (args, extra) => processes.run(args.command, args.cwd, args.timeout_ms, args.background, extra.signal));
-    register('process_status', 'Read status and bounded stdout/stderr from a process started by this session.', { job_id: z.string() },
-      args => processes.status(args.job_id), true);
+    register('process_status', 'Read status and output of a process started by this session. By default returns the last 8000 characters of stdout and stderr; pass stream with offset/limit to page through earlier output.', {
+      job_id: z.string(), stream: z.enum(['stdout', 'stderr']).optional(),
+      offset: z.number().int().min(0).optional(), limit: z.number().int().min(1).max(30000).default(8000)
+    }, args => processes.status(args.job_id, { stream: args.stream, offset: args.offset, limit: args.limit }), true);
     register('list_processes', 'List processes owned by this tool session, not all system processes.', {}, () => processes.list(), true);
     register('stop_process', 'Stop a process group started by this tool session, including a development server.', { job_id: z.string() },
       args => processes.stop(args.job_id));
@@ -78,10 +101,31 @@ export async function startLocalServer({ root, env = process.env, headless = fal
     register('browser_press', 'Press a key such as Enter, Escape or ControlOrMeta+A in a LOCAL page.', {
       page_id: pageId, selector: selector.optional(), key: z.string().min(1).max(100)
     }, args => browser.action(args.page_id, 'press', args.selector, args.key));
-    register('browser_screenshot', 'Capture the visible viewport of a LOCAL page as an image.', { page_id: pageId },
-      args => browser.screenshot(args.page_id), true);
-    register('browser_logs', 'Read recent browser console messages, page errors and failed network requests.', { page_id: pageId },
-      args => { browser.page(args.page_id); const logs = browser.logs.get(args.page_id); return { logs: logs.slice(-20), truncated: logs.length > 20 }; }, true);
+    register('browser_select', 'Choose option(s) of a <select> on a LOCAL page by value or label.', {
+      page_id: pageId, selector, values: z.union([z.string(), z.array(z.string()).max(50)])
+    }, args => browser.action(args.page_id, 'select', args.selector, args.values));
+    register('browser_hover', 'Hover over an element on a LOCAL page, e.g. to open a menu.', { page_id: pageId, selector },
+      args => browser.action(args.page_id, 'hover', args.selector));
+    register('browser_navigate', 'Navigate an open LOCAL page to a URL, or go back, forward or reload.', {
+      page_id: pageId, url: z.string().url().optional(), action: z.enum(['back', 'forward', 'reload']).optional()
+    }, args => browser.navigate(args.page_id, args));
+    register('browser_scroll', 'Scroll a LOCAL page: bring a selector into view, or scroll by x/y pixels.', {
+      page_id: pageId, selector: selector.optional(), x: z.number().int().default(0), y: z.number().int().default(0)
+    }, args => browser.scroll(args.page_id, args));
+    register('browser_wait_for', 'Wait until a selector or text reaches a state (default visible) on a LOCAL page, or until the page has loaded.', {
+      page_id: pageId, selector: selector.optional(), text: z.string().min(1).max(1000).optional(),
+      state: z.enum(['visible', 'hidden', 'attached', 'detached']).default('visible'),
+      timeout_ms: z.number().int().min(100).max(60000).default(10000)
+    }, args => browser.waitFor(args.page_id, { selector: args.selector, text: args.text, state: args.state, timeout: args.timeout_ms }), true);
+    register('browser_evaluate', 'Evaluate a JavaScript expression in a LOCAL page and return its JSON-serializable result.', {
+      page_id: pageId, expression: z.string().min(1).max(100000)
+    }, args => browser.evaluate(args.page_id, args.expression));
+    register('browser_screenshot', 'Capture a LOCAL page as an image: the viewport by default, the full page, or one element.', {
+      page_id: pageId, full_page: z.boolean().default(false), selector: selector.optional()
+    }, args => browser.screenshot(args.page_id, { fullPage: args.full_page, selector: args.selector }), true);
+    register('browser_logs', 'Read recent browser console messages, page errors and failed network requests.', {
+      page_id: pageId, limit: z.number().int().min(1).max(200).default(20)
+    }, args => browser.readLogs(args.page_id, args.limit), true);
     register('browser_close', 'Close a LOCAL browser tab opened by this session.', { page_id: pageId }, args => browser.closePage(args.page_id));
     return server;
   }

package/src/local/tunnel.js

@@ -3,7 +3,7 @@ import path from 'node:path';
 import os from 'node:os';
 import { spawn } from 'node:child_process';
 import { setTimeout as delay } from 'node:timers/promises';
-import { execute, exists } from '../system.js';
+import { execute, exists, trackChild } from '../system.js';
 import { sshBase } from '../ssh.js';
 
 export async function openTunnel(config, localPort, { env = process.env, run = execute } = {}) {
@@ -11,8 +11,8 @@ export async function openTunnel(config, localPort, { env = process.env, run = e
   const base = os.tmpdir().length > 55 ? '/tmp' : os.tmpdir();
   const directory = await fs.mkdtemp(path.join(base, 'ccr-'));
   const controlPath = path.join(directory, 'ssh');
-  const master = spawn('ssh', [...sshBase(config), '-M', '-S', controlPath, '-o', 'ControlPersist=no',
-    '-o', 'ExitOnForwardFailure=yes', '-N', '-T', config.host], { env, stdio: ['ignore', 'ignore', 'pipe'] });
+  const master = trackChild(spawn('ssh', [...sshBase(config), '-M', '-S', controlPath, '-o', 'ControlPersist=no',
+    '-o', 'ExitOnForwardFailure=yes', '-N', '-T', config.host], { env, stdio: ['ignore', 'ignore', 'pipe'] }));
   let closed = false, errorText = '', spawnError;
   const done = new Promise(resolve => {
     master.once('error', error => { spawnError = error; closed = true; resolve(); });

package/src/local/workspace.js

@@ -1,10 +1,47 @@
 import * as fs from 'node:fs/promises';
 import path from 'node:path';
+import { execFile } from 'node:child_process';
 import { createHash, randomUUID } from 'node:crypto';
 
 const hash = text => createHash('sha256').update(text).digest('hex');
 const inside = (root, target) => target === root || target.startsWith(root + path.sep);
 
+// Keep read_file results below the MCP response limit (JSON escaping adds overhead).
+const READ_BUDGET = 28000;
+const SKIPPED = new Set(['.git', 'node_modules', '.venv', '__pycache__']);
+const MAX_FILES = 10000;
+const escapeRegExp = text => text.replace(/[.+^${}()|[\]\\*?]/g, '\\$&');
+
+// Minimal glob: *, **, ?, {a,b}. Without a slash it matches the file name only.
+export function globMatcher(glob) {
+  let source = '';
+  for (let i = 0; i < glob.length; i++) {
+    const char = glob[i];
+    if (char === '*' && glob[i + 1] === '*') {
+      i++;
+      if (glob[i + 1] === '/') { i++; source += '(?:.*/)?'; } else source += '.*';
+    } else if (char === '*') source += '[^/]*';
+    else if (char === '?') source += '[^/]';
+    else if (char === '{' && glob.indexOf('}', i) > i) {
+      const end = glob.indexOf('}', i);
+      source += '(?:' + glob.slice(i + 1, end).split(',').map(escapeRegExp).join('|') + ')';
+      i = end;
+    } else source += escapeRegExp(char);
+  }
+  const pattern = new RegExp('^' + source + '$');
+  const byName = !glob.includes('/');
+  return relative => pattern.test(byName ? path.posix.basename(relative) : relative);
+}
+
+function gitFiles(directory) {
+  return new Promise(resolve => {
+    execFile('git', ['-C', directory, 'ls-files', '-z', '--cached', '--others', '--exclude-standard'],
+      { maxBuffer: 64 * 1024 * 1024, timeout: 15000 }, (error, stdout) => {
+        resolve(error ? null : stdout.split('\0').filter(Boolean));
+      });
+  });
+}
+
 export class Workspace {
   constructor(root) { this.root = root; }
 
@@ -35,8 +72,25 @@ export class Workspace {
     const content = await fs.readFile(target, 'utf8');
     if (content.includes('\0')) throw new Error('这是二进制文件，请通过终端或专用工具处理。');
     const lines = content.split('\n');
-    return { path: path.relative(this.root, target), sha256: hash(content), total_lines: lines.length,
-      content: lines.slice(offset - 1, offset - 1 + limit).map((line, i) => `${offset + i}: ${line}`).join('\n') };
+    if (lines.length > 1 && lines.at(-1) === '') lines.pop(); // A trailing newline is not an extra line.
+    const total = content === '' ? 0 : lines.length;
+    const output = [];
+    let used = 0, sizeLimited = false;
+    for (let i = offset - 1; i < Math.min(total, offset - 1 + limit); i++) {
+      const line = `${i + 1}: ${lines[i]}`;
+      if (used + line.length > READ_BUDGET) {
+        sizeLimited = true;
+        if (!output.length) output.push(line.slice(0, READ_BUDGET) + ` …[本行过长已截断，共 ${lines[i].length} 字符，请用终端查看]`);
+        break;
+      }
+      output.push(line);
+      used += line.length + 1;
+    }
+    const next = offset + output.length;
+    return { path: path.relative(this.root, target), sha256: hash(content), total_lines: total,
+      content: output.join('\n'),
+      ...(next <= total ? { next_offset: next } : {}),
+      ...(sizeLimited ? { truncated_by_size: true } : {}) };
   }
 
   async atomicWrite(target, content, mode = 0o644) {
@@ -83,35 +137,78 @@ export class Workspace {
       })) };
   }
 
-  async search(pattern, directory = '.', maxResults = 100, caseSensitive = true) {
+  // Candidate files relative to `directory`. Inside a Git work tree this follows
+  // .gitignore; otherwise it walks the tree and skips common dependency folders.
+  async candidates(directory) {
+    const fromGit = await gitFiles(directory);
+    // An empty list usually means the directory itself is ignored; search it explicitly.
+    if (fromGit?.length) {
+      const files = fromGit.filter(file => !file.split('/').some(part => SKIPPED.has(part))).sort();
+      return { files: files.slice(0, MAX_FILES), limited: files.length > MAX_FILES, errors: 0, source: 'git' };
+    }
+    const files = [];
+    let errors = 0, limited = false;
+    const walk = async relative => {
+      let entries;
+      try { entries = await fs.readdir(path.join(directory, relative), { withFileTypes: true }); }
+      catch { errors++; return; }
+      entries.sort((a, b) => a.name.localeCompare(b.name));
+      for (const entry of entries) {
+        if (files.length >= MAX_FILES) { limited = true; return; }
+        const child = relative ? relative + '/' + entry.name : entry.name;
+        if (entry.isDirectory()) { if (!SKIPPED.has(entry.name)) await walk(child); }
+        else if (entry.isFile()) files.push(child);
+      }
+    };
+    await walk('');
+    return { files, limited, errors, source: 'walk' };
+  }
+
+  async search(pattern, directory = '.', maxResults = 100, caseSensitive = true, { regex = false, glob } = {}) {
     const root = await this.resolve(directory);
+    let test;
+    if (regex) {
+      let expression;
+      try { expression = new RegExp(pattern, caseSensitive ? '' : 'i'); }
+      catch (error) { throw new Error('正则表达式无效：' + error.message); }
+      test = line => expression.test(line);
+    } else {
+      const needle = caseSensitive ? pattern : pattern.toLowerCase();
+      test = line => (caseSensitive ? line : line.toLowerCase()).includes(needle);
+    }
+    const matchesGlob = glob ? globMatcher(glob) : () => true;
+    const rootStat = await fs.stat(root);
+    const listing = rootStat.isFile() ? { files: [''], limited: false, errors: 0, source: 'file' } : await this.candidates(root);
+    const files = listing.files.filter(file => file === '' || matchesGlob(file));
     const results = [];
-    let scanned = 0, truncated = false;
-    const needle = caseSensitive ? pattern : pattern.toLowerCase();
-    const walk = async target => {
-      if (results.length >= maxResults || scanned >= 10000) { truncated = true; return; }
-      const stat = await fs.lstat(target);
-      if (stat.isSymbolicLink()) return;
-      if (stat.isDirectory()) {
-        for (const entry of await fs.readdir(target, { withFileTypes: true })) {
-          if (['.git', 'node_modules', '.venv', '__pycache__'].includes(entry.name)) continue;
-          await walk(path.join(target, entry.name));
-          if (truncated) break;
-        }
-      } else if (stat.isFile()) {
-        scanned++;
-        if (stat.size > 1024 * 1024) return;
+    let scanned = 0, errors = listing.errors, truncated = listing.limited;
+    const scan = async relative => {
+      const target = relative ? path.join(root, relative) : root;
+      try {
+        const stat = await fs.lstat(target);
+        if (!stat.isFile() || stat.size > 1024 * 1024) return null;
         const text = await fs.readFile(target, 'utf8');
-        if (text.includes('\0')) return;
-        for (const [i, line] of text.split('\n').entries()) {
-          if ((caseSensitive ? line : line.toLowerCase()).includes(needle)) {
-            results.push({ path: path.relative(this.root, target), line: i + 1, text: line.slice(0, 1000) });
-            if (results.length >= maxResults) { truncated = true; break; }
-          }
-        }
+        scanned++;
+        if (text.includes('\0')) return null;
+        const found = [];
+        for (const [i, line] of text.split('\n').entries())
+          if (test(line)) found.push({ path: path.relative(this.root, target), line: i + 1, text: line.slice(0, 1000) });
+        return found;
+      } catch (error) {
+        if (error.code !== 'ENOENT') errors++; // Deleted tracked files are not errors.
+        return null;
       }
     };
-    await walk(root);
-    return { results, scanned_files: scanned, truncated };
+    // Read in parallel batches but keep results in a stable path order.
+    for (let i = 0; i < files.length && !truncated; i += 32) {
+      for (const found of await Promise.all(files.slice(i, i + 32).map(scan))) {
+        for (const match of found || []) {
+          if (results.length >= maxResults) { truncated = true; break; }
+          results.push(match);
+        }
+        if (truncated) break;
+      }
+    }
+    return { results, scanned_files: scanned, truncated, source: listing.source, ...(errors ? { unreadable: errors } : {}) };
   }
 }

package/src/local-mode.js

@@ -1,7 +1,7 @@
 import * as fs from 'node:fs/promises';
 import path from 'node:path';
 import { createHash, randomUUID } from 'node:crypto';
-import { quote, shellJoin, which } from './system.js';
+import { onCleanup, quote, shellJoin, which } from './system.js';
 import { sshArgs } from './ssh.js';
 import { remotePath } from './client.js';
 import { ensureRemoteClaude, remoteEnvironment } from './remote-claude.js';
@@ -12,9 +12,14 @@ import { openTunnel } from './local/tunnel.js';
 const BOOLEAN_FLAGS = new Set(['--continue', '-c', '--print', '-p', '--verbose', '--no-session-persistence',
   '--include-partial-messages', '--replay-user-messages']);
 const VALUE_FLAGS = new Set(['--model', '--effort', '--max-turns', '--max-budget-usd', '--output-format',
-  '--input-format', '--session-id', '--append-system-prompt']);
+  '--input-format', '--session-id', '--append-system-prompt', '--permission-mode', '--name', '-n', '--fallback-model']);
+// --restricted refuses bypassPermissions anyway; reject it before connecting.
+const PERMISSION_MODES = new Set(['default', 'manual', 'acceptEdits', 'plan', 'auto', 'dontAsk']);
 const SUBCOMMANDS = new Set(['auth', 'mcp', 'install', 'update', 'doctor', 'agents', 'attach', 'gateway',
   'daemon', 'remote-control', 'rc', 'desktop', 'setup-token']);
+// Project instruction files read from the LOCAL project root, in Claude Code's order.
+const INSTRUCTION_FILES = ['CLAUDE.md', path.join('.claude', 'CLAUDE.md'), 'CLAUDE.local.md'];
+const INSTRUCTION_LIMIT = 64 * 1024;
 
 export function validateLocalArguments(args) {
   for (let i = 0; i < args.length; i++) {
@@ -27,30 +32,85 @@ export function validateLocalArguments(args) {
     const name = argument.split('=')[0];
     if (BOOLEAN_FLAGS.has(name) && argument === name) continue;
     if (VALUE_FLAGS.has(name) || name === '--resume' || name === '-r') {
-      if (argument.includes('=')) continue;
-      if (name === '--resume' || name === '-r') { if (args[i + 1] && !args[i + 1].startsWith('-')) i++; continue; }
-      if (args[i + 1] === undefined || args[i + 1].startsWith('-')) throw new Error(`${name} 缺少参数；以短横线开头的值请使用 ${name}=值。`);
-      i++; continue;
+      if (name === '--resume' || name === '-r') {
+        if (!argument.includes('=') && args[i + 1] && !args[i + 1].startsWith('-')) i++;
+        continue;
+      }
+      let value;
+      if (argument.includes('=')) value = argument.slice(argument.indexOf('=') + 1);
+      else {
+        if (args[i + 1] === undefined || args[i + 1].startsWith('-')) throw new Error(`${name} 缺少参数；以短横线开头的值请使用 ${name}=值。`);
+        value = args[++i];
+      }
+      if (name === '--permission-mode' && !PERMISSION_MODES.has(value))
+        throw new Error(`本地模式的 --permission-mode 仅支持 ${[...PERMISSION_MODES].join('、')}。`);
+      continue;
     }
     throw new Error(`本地模式暂不支持参数 ${name}；工具配置由本地模式统一管理。`);
   }
 }
 
-export function localClaudeArguments(configFile, root, extra) {
+// Pull --append-system-prompt values out of the forwarded arguments. They are
+// merged into the single prompt file so they cannot replace the routing rules.
+export function extractAppendedPrompts(args) {
+  const rest = [], prompts = [];
+  for (let i = 0; i < args.length; i++) {
+    const argument = args[i];
+    if (argument === '--') { rest.push(...args.slice(i)); break; }
+    if (argument === '--append-system-prompt') { prompts.push(args[++i]); continue; }
+    if (argument.startsWith('--append-system-prompt=')) { prompts.push(argument.slice(argument.indexOf('=') + 1)); continue; }
+    rest.push(argument);
+    if (VALUE_FLAGS.has(argument) && i + 1 < args.length) rest.push(args[++i]);
+  }
+  return { rest, prompts };
+}
+
+export async function projectInstructions(root) {
+  const sections = [];
+  let remaining = INSTRUCTION_LIMIT;
+  for (const name of INSTRUCTION_FILES) {
+    if (remaining <= 0) break;
+    let content;
+    try {
+      const file = await fs.realpath(path.join(root, name));
+      if (file !== root && !file.startsWith(root + path.sep)) continue; // Never follow links out of the project.
+      content = await fs.readFile(file, 'utf8');
+    } catch (error) {
+      if (['ENOENT', 'ENOTDIR', 'EISDIR'].includes(error.code)) continue;
+      throw error;
+    }
+    if (!content.trim()) continue;
+    const clipped = content.length > remaining ? content.slice(0, remaining) + `\n…[已截断，完整内容请用 read_file 读取 ${name}]` : content;
+    remaining -= clipped.length;
+    sections.push(`Contents of LOCAL ${name}:\n\n${clipped}`);
+  }
+  return sections.join('\n\n');
+}
+
+export function localPrompt(root, { instructions = '', appended = [] } = {}) {
+  const parts = [`All project operations run on the developer's LOCAL computer through the local MCP server. ` +
+    `The LOCAL project root is ${JSON.stringify(root)}. The server working directory is only for session metadata, not project files. ` +
+    'Call workspace_info before working. Use only local tools for file access, shell commands and browser operations. ' +
+    'For public information research, use the server-side WebSearch and WebFetch tools first; do not open the local browser for ordinary searches or reading public documentation. ' +
+    'Use the LOCAL browser for local development pages, localhost/loopback or developer LAN addresses, interactive UI testing, screenshots, or pages requiring interactive sign-in. ' +
+    'Never send local development URLs to server-side WebFetch. If WebSearch or WebFetch is unavailable or fails for ordinary public research, report it and ask before using the local browser as a fallback. ' +
+    'Project instructions from the LOCAL CLAUDE.md files are included below when present; also read CLAUDE.md files in LOCAL subdirectories with read_file when working there. ' +
+    'Use background commands for development servers, inspect their logs, and stop owned processes when finished. ' +
+    'If the local connection fails, report it and stop local project operations; never fall back to server filesystem, shell or browser tools.'];
+  if (instructions) parts.push('# Project instructions (LOCAL)\n\n' + instructions);
+  if (appended.length) parts.push('# Additional instructions from the user\n\n' + appended.join('\n\n'));
+  return parts.join('\n\n');
+}
+
+export function localClaudeArguments(configFile, promptFile, extra) {
   validateLocalArguments(extra);
+  const { rest } = extractAppendedPrompts(extra);
   return ['--restricted', '--tools', 'WebSearch,WebFetch', '--strict-mcp-config', '--mcp-config', configFile,
     // Keep built-in UI commands (/config, /model, /help) available. Disable
     // skill shell expansion separately instead of disabling the entire menu.
     '--setting-sources', '', '--settings', JSON.stringify({ disableAllHooks: true,
       disableSkillShellExecution: true, disableBundledSkills: true, enabledPlugins: {} }),
-    '--append-system-prompt', `All project operations run on the developer's LOCAL computer through the local MCP server. ` +
-    `The LOCAL project root is ${JSON.stringify(root)}. The server working directory is only for session metadata, not project files. ` +
-    'Call workspace_info before working. Use only local tools for file access, shell commands and browser operations. ' +
-    'For public information research, use the server-side WebSearch and WebFetch tools first; do not open the local browser for ordinary searches or reading public documentation. ' +
-    'Use the LOCAL browser for local development pages, localhost/loopback or developer LAN addresses, interactive UI testing, screenshots, or pages requiring interactive sign-in. ' +
-    'Never send local development URLs to server-side WebFetch. If WebSearch or WebFetch is unavailable or fails for ordinary public research, report it and ask before using the local browser as a fallback. ' +
-    'Read LOCAL CLAUDE.md with read_file if present. Use background commands for development servers, inspect their logs, and stop owned processes when finished. ' +
-    'If the local connection fails, report it and stop local project operations; never fall back to server filesystem, shell or browser tools.', ...extra];
+    '--append-system-prompt-file', promptFile, ...rest];
 }
 
 export function supportsLocalMode(output) {
@@ -65,36 +125,56 @@ export async function launchLocal(client, config, extra, dependencies = {}) {
   if (!await which('ssh', client.env.PATH)) throw new Error('找不到系统 SSH 客户端。');
   const root = await fs.realpath(client.cwd), home = await fs.realpath(client.home);
   if (root === home || root === path.parse(root).root) throw new Error('请进入具体项目目录，不允许以用户目录或磁盘根目录作为项目。');
-  const prepareBrowser = dependencies.installBrowser || installBrowser;
-  await prepareBrowser(client.log, { debug: client.debug });
-  const gateway = await (dependencies.startLocalServer || startLocalServer)({ root, env: client.env,
-    headless: client.env.CLAUDE_REMOTE_HEADLESS === undefined ? Boolean(config.browserHeadless) : client.env.CLAUDE_REMOTE_HEADLESS === '1', log: client.log });
-  let tunnel, configFile;
+  const prompt = localPrompt(root, { instructions: await projectInstructions(root), appended: extractAppendedPrompts(extra).prompts });
+  // Prepare the browser while SSH connects; it is only needed before Claude starts.
+  const browserReady = (dependencies.installBrowser || installBrowser)(client.log, { debug: client.debug });
+  browserReady.catch(() => {}); // Reported when awaited below.
+  let gateway, tunnel, configFile, promptFile, cleaning;
   const hash = createHash('sha256').update(config.client_id + '\0' + root).digest('hex').slice(0, 24);
   const remoteDirectory = config.root + '/local-' + hash;
   const remote = (script, { interactive = false, input, capture = !interactive, timeout = 30000, check = true } = {}) =>
     client.execute('ssh', sshArgs(config, script, { interactive, tty: interactive && client.tty,
       input: input !== undefined, controlPath: tunnel.controlPath }), { env: client.env, capture, input,
       timeout: interactive ? 0 : timeout, check });
+  const cleanup = () => cleaning ||= (async () => {
+    if (tunnel && configFile)
+      await remote('rm -f -- ' + remotePath(configFile) + ' ' + remotePath(promptFile), { timeout: 5000, check: false }).catch(() => {});
+    await gateway?.close();
+    await tunnel?.close();
+  })();
+  const removeCleanup = onCleanup(cleanup);
   try {
+    gateway = await (dependencies.startLocalServer || startLocalServer)({ root, env: client.env,
+      headless: client.env.CLAUDE_REMOTE_HEADLESS === undefined ? Boolean(config.browserHeadless) : client.env.CLAUDE_REMOTE_HEADLESS === '1', log: client.log });
     tunnel = await (dependencies.openTunnel || openTunnel)(config, gateway.port, { env: client.env, run: client.execute });
-    const version = await remote(ensureRemoteClaude(config.claude) + shellJoin([config.claude, '--version']), { timeout: 600000 });
-    if (!supportsLocalMode(version.stdout)) throw new Error('本地工具模式需要服务器 Claude Code 2.1.248 或更高版本。请先在服务器运行 claude update。');
-    configFile = remoteDirectory + '/.local-mcp-' + randomUUID() + '.json';
+    const session = randomUUID();
+    configFile = remoteDirectory + '/.local-mcp-' + session + '.json';
+    promptFile = remoteDirectory + '/.local-prompt-' + session + '.md';
     const mcp = { mcpServers: { local: { type: 'http', url: `http://127.0.0.1:${tunnel.port}/mcp`,
       headers: { Authorization: 'Bearer ' + gateway.token }, timeout: 180000 } } };
-    await remote('set -e; umask 077; mkdir -p -- ' + remotePath(remoteDirectory) + '; cat > ' + remotePath(configFile),
-      { input: JSON.stringify(mcp) });
+    // One round trip: install Claude if missing, store the token-bearing MCP
+    // config (first stdin line) and the prompt (the rest), then report the version.
+    // `read` consumes the pipe byte by byte, so nothing is lost between the two files.
+    const version = await remote(ensureRemoteClaude(config.claude) +
+      'umask 077; mkdir -p -- ' + remotePath(remoteDirectory) + '\n' +
+      'IFS= read -r line; printf \'%s\\n\' "$line" > ' + remotePath(configFile) + '\n' +
+      'cat > ' + remotePath(promptFile) + '\n' +
+      shellJoin([config.claude, '--version']) + ' </dev/null',
+    { input: JSON.stringify(mcp) + '\n' + prompt, timeout: 600000 });
+    if (!supportsLocalMode(version.stdout)) throw new Error('本地工具模式需要服务器 Claude Code 2.1.248 或更高版本。请先在服务器运行 claude update。');
+    await browserReady;
     client.debug(`本地执行模式：${root}\n文件、命令和浏览器在本机运行；项目文件不通过本模式同步。`);
-    const args = localClaudeArguments(path.posix.basename(configFile), root, extra);
-    // Keep the parent shell so EXIT can remove the token-bearing temporary config.
+    const args = localClaudeArguments(path.posix.basename(configFile), path.posix.basename(promptFile), extra);
+    // Keep the parent shell so EXIT can remove the token-bearing temporary files.
     const script = remoteEnvironment + 'cd -- ' + remotePath(remoteDirectory) + ' || exit 1; ' +
-      'trap ' + quote('rm -f -- ' + remotePath(configFile)) + ' EXIT; ' +
+      'trap ' + quote('rm -f -- ' + remotePath(configFile) + ' ' + remotePath(promptFile)) + ' EXIT; ' +
       shellJoin([config.claude, ...args]);
-    return (await remote(script, { interactive: true, check: false })).code;
+    const code = (await remote(script, { interactive: true, check: false })).code;
+    // A dropped connection leaves the remote UI's terminal modes switched on.
+    if (code !== 0) client.restoreTerminal();
+    return code;
   } finally {
-    if (tunnel && configFile) await remote('rm -f -- ' + remotePath(configFile), { timeout: 5000, check: false }).catch(() => {});
-    await gateway.close();
-    await tunnel?.close();
+    removeCleanup();
+    await cleanup();
   }
 }

package/src/remote-claude.js

@@ -10,15 +10,15 @@ export function ensureRemoteClaude(command) {
     installer=$(mktemp "\${TMPDIR:-/tmp}/claude-remote-install.XXXXXXXX")
     trap 'rm -f -- "$installer"' EXIT
     if command -v curl >/dev/null 2>&1; then
-      curl -fSL --connect-timeout 20 --max-time 120 --retry 2 \\
+      curl -fSL </dev/null --connect-timeout 20 --max-time 120 --retry 2 \\
         --output "$installer" https://claude.ai/install.sh
     elif command -v wget >/dev/null 2>&1; then
-      wget --timeout=120 --tries=3 --output-document="$installer" https://claude.ai/install.sh
+      wget </dev/null --timeout=120 --tries=3 --output-document="$installer" https://claude.ai/install.sh
     else
       echo '自动安装需要服务器提供 curl 或 wget，请先安装其中一个工具。' >&2
       exit 127
     fi
-    if ! bash "$installer" >&2; then
+    if ! bash "$installer" >&2 </dev/null; then
       echo 'Claude Code 官方安装失败，请检查上述输出、网络连接和目录权限后重试。' >&2
       exit 1
     fi

package/src/system.js

@@ -1,6 +1,7 @@
 import { spawn } from 'node:child_process';
 import { constants } from 'node:fs';
 import * as fs from 'node:fs/promises';
+import os from 'node:os';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import lockfile from 'proper-lockfile';
@@ -38,10 +39,73 @@ export async function writeJSON(file, value) {
   } finally { await fs.rm(temp, { force: true }); }
 }
 
+// Children and cleanup callbacks that must not outlive this CLI when the
+// terminal closes (SIGHUP) or the process is asked to stop (SIGTERM).
+const trackedChildren = new Set();
+const cleanups = new Set();
+let terminating = null;
+
+export function trackChild(child) {
+  trackedChildren.add(child);
+  child.once('close', () => trackedChildren.delete(child));
+  child.once('error', () => trackedChildren.delete(child));
+  return child;
+}
+
+export function onCleanup(callback) {
+  cleanups.add(callback);
+  return () => cleanups.delete(callback);
+}
+
+export function terminate(signal, { exit = code => process.exit(code), graceMs = 10000, terminal = process.stdout } = {}) {
+  if (terminating) return terminating;
+  const code = 128 + (os.constants.signals[signal] || 15);
+  terminating = (async () => {
+    // Cleanups first: they may still need live SSH connections (e.g. to delete
+    // remote temporary files). Whatever is left afterwards is stopped.
+    const pending = Promise.allSettled([...cleanups].map(callback => callback()));
+    let timer;
+    const limit = new Promise(resolve => { timer = setTimeout(resolve, graceMs); timer.unref?.(); });
+    await Promise.race([pending, limit]);
+    clearTimeout(timer);
+    for (const child of trackedChildren) {
+      try { child.kill('SIGTERM'); } catch { /* already gone */ }
+    }
+    restoreTerminal(terminal);
+    exit(code);
+  })();
+  return terminating;
+}
+
+// A remote full-screen program that loses its connection cannot switch off the
+// terminal modes it enabled, so mouse moves, focus changes and keys show up as
+// stray escape codes. Every sequence here only turns a mode off and is a no-op
+// when the mode is already off. The alternate screen (?1049l) is deliberately
+// left alone: leaving it when not active can move the cursor on some terminals.
+export const TERMINAL_RESET = [
+  '\x1b[?1000l', '\x1b[?1002l', '\x1b[?1003l', '\x1b[?1005l', '\x1b[?1006l', '\x1b[?1015l', // mouse reporting
+  '\x1b[?1004l', // focus in/out events
+  '\x1b[?2004l', // bracketed paste
+  '\x1b[=0;1u', '\x1b[<99u', // kitty keyboard protocol: clear flags, pop pushed levels
+  '\x1b[>4m', // xterm modifyOtherKeys
+  '\x1b[?1l', '\x1b>', // normal cursor keys and keypad
+  '\x1b[0m', '\x1b[?25h' // plain text attributes, visible cursor
+].join('');
+
+export function restoreTerminal(stream = process.stdout) {
+  if (!stream?.isTTY) return false;
+  try { stream.write(TERMINAL_RESET); return true; }
+  catch { return false; } // The terminal may already be gone (SIGHUP).
+}
+
+export function installSignalHandlers() {
+  for (const signal of ['SIGHUP', 'SIGTERM']) process.on(signal, () => { terminate(signal); });
+}
+
 export function execute(command, args = [], { capture = false, timeout = 0, check = true, env = process.env, input } = {}) {
   return new Promise((resolve, reject) => {
-    const child = spawn(command, args, { stdio: [input !== undefined ? 'pipe' : capture ? 'ignore' : 'inherit',
-      capture ? 'pipe' : 'inherit', capture ? 'pipe' : 'inherit'], env });
+    const child = trackChild(spawn(command, args, { stdio: [input !== undefined ? 'pipe' : capture ? 'ignore' : 'inherit',
+      capture ? 'pipe' : 'inherit', capture ? 'pipe' : 'inherit'], env }));
     if (input !== undefined) {
       child.stdin.on('error', () => {}); // An early remote failure is reported by the exit status.
       child.stdin.end(input);