@znmin/claude-remote-cli 0.1.0 → 0.2.0

package/README.md

@@ -1,12 +1,12 @@
 # claude-remote-cli
 
-在本地任意项目目录运行 `claude`，自动将目录双向同步到你指定的 SSH 服务器，并在服务器上运行真正的 Claude Code。
+在项目目录运行 `claude`，让 Claude Code 主进程运行在 SSH 服务器，文件、终端和浏览器操作在本机执行；也保留服务器执行和目录双向同步模式。
 
 本项目是独立的 SSH/同步封装，不是 Anthropic 官方客户端。它不提供服务器、Claude 账号或 API 服务。
 
 ## 安装
 
-要求：Node.js **20.11 或更高版本**、npm、OpenSSH（`ssh`/`scp`）和系统 `tar`。支持 macOS/Linux 的 x64、arm64；Windows 请在 WSL 内安装使用。本地无需 Python、Homebrew 或 Claude Code。
+要求：Node.js **20.11 或更高版本**、npm 和 OpenSSH 客户端。本地模式需要 `ssh`，服务器同步模式另外需要 `scp` 和系统 `tar`。支持 macOS/Linux 的 x64、arm64；Windows 请在 WSL 内使用。本地无需 Python、Homebrew 或 Anthropic 的 Claude Code。
 
 npm 包名为 `@znmin/claude-remote-cli`，安装后提供 `claude` 和 `claude-remote` 命令。
 
@@ -25,20 +25,27 @@ npm install -g git+https://github.com/znmin/claude-remote-cli.git
 也可以从已下载的分发包安装：
 
 ```bash
-npm install -g ./znmin-claude-remote-cli-0.1.0.tgz
+npm install -g ./znmin-claude-remote-cli-0.2.0.tgz
 ```
 
-若系统 npm 全局目录不可写，可使用 `npm install -g --prefix "$HOME/.local" ./znmin-claude-remote-cli-0.1.0.tgz`，并确保 `~/.local/bin` 在 PATH 中；卸载时也使用相同的 `--prefix`。
+若系统 npm 全局目录不可写，可使用 `npm install -g --prefix "$HOME/.local" ./znmin-claude-remote-cli-0.2.0.tgz`，并确保 `~/.local/bin` 在 PATH 中；卸载时也使用相同的 `--prefix`。
 
 npm 中不带作用域的 `claude-remote-cli` 属于其他项目。本项目使用独立的 `@znmin/claude-remote-cli` 作用域包名；请安装完整包名，或使用上述 GitHub 地址及本项目分发的 `.tgz` 文件。
 
-安装会自动准备 Mutagen 同步工具：复用 PATH 中的 0.18.1 版本，或从官方 GitHub Release 下载固定版本并校验内置 SHA-256。下载需要网络，工具和远程代理合计占用约百 MB 磁盘。安装时网络不可用不会让 npm 安装失败，第一次连接时会重试。
+依赖按模式准备：本地模式首次启动准备 Playwright Chromium，服务器模式首次启动准备 Mutagen 0.18.1。Mutagen 复用 PATH 中的匹配版本，或从官方 GitHub Release 下载并校验内置 SHA-256。浏览器和同步组件需要网络和额外磁盘空间；npm 安装本身不强制下载这些二进制文件。
 
 如果用户已经安装其他提供 `claude` 命令的软件，应先卸载旧客户端，避免 npm 命令冲突或 PATH 指向旧程序。无需使用 `--force` 覆盖。
 
 ## 开始使用
 
-服务器需要 Linux/macOS、可用的 SSH/SCP、Bash，以及**已经安装并完成认证的 Claude Code**。
+服务器需要 Linux/macOS、可用的 SSH/SCP 和 Bash。启动时会检查 Claude Code：
+
+- 已安装：直接使用已有程序。
+- 默认 `claude` 命令不存在：通过服务器上的 `curl` 或 `wget` 下载并执行 [Anthropic 官方原生安装器](https://github.com/anthropics/claude-code#get-started)，无需服务器安装 Node.js，也不会使用 `sudo`。
+- 安装完成：检查命令已可用，再开始目录同步并启动 Claude。首次启动时按 Claude 的提示完成账号认证；不会复制本机账号凭据。
+- 下载失败、安装失败或缺少 `curl`/`wget`：停止启动并报告原因，不建立新的项目同步会话。自动安装最多等待 10 分钟，可修复网络/权限后重试。
+
+安装过程只在默认命令缺失时触发，不会自动重装或升级已有 Claude Code。
 
 ```bash
 # 配置你的服务器，不会立即连接或上传文件
@@ -60,13 +67,60 @@ claude --continue
 
 未配置服务器时，也可以直接运行 `claude`，按终端提示输入服务器地址和端口。请勿把密码或私钥填入配置；登录使用 OpenSSH 原有认证流程和主机身份验证。
 
-若远程 Claude 不在登录环境的 PATH 或 `~/.local/bin` 中：
+若需要使用特定的 Claude 可执行文件，可指定绝对路径；自定义路径不存在时会提示修正配置，不会自动改用其他程序：
 
 ```bash
 claude-remote configure my-server --claude /absolute/path/to/claude
 ```
 
-## 同步管理
+## 本地执行模式（0.2.0）
+
+新配置默认使用 `local`；旧配置保持 `remote`，不会静默改变已有行为。两种模式都在服务器运行真实 Claude Code。
+
+| 模式 | 项目文件、命令、依赖和测试 | 浏览器 |
+| --- | --- | --- |
+| `local` | 直接在本机操作，不通过该模式同步项目 | 本机独立受控 Chromium |
+| `remote` | 文件双向同步，工具在服务器执行 | 使用服务器原有工具 |
+
+```bash
+claude-remote mode local          # 保存默认模式
+claude --local                   # 仅本次使用本地工具
+claude --remote                  # 仅本次使用旧的服务器模式
+claude-remote configure my-server --mode local
+```
+
+切换模式不会自动停止已有后台同步。若从旧模式切换且不希望旧项目继续同步，先运行 `claude-remote stop --all`。本地模式本身不创建同步会话，不上传整个项目。
+
+无需用户手工配置 MCP，默认提供 18 个工具：
+
+- 项目与文件：`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`。
+
+Git、npm、pnpm、Python、Go、Docker、数据库 CLI、`gh` 等共用本地终端，不需要逐项适配，仍需在本机安装并具备必要的登录、连接配置及权限。终端继承启动用户环境和登录 shell，默认工作目录为当前项目。长任务使用后台进程，再查询日志和停止；退出会话会停止仍受本工具管理的进程组，自行 daemonize 或逃离原进程组的程序不在自动清理保证内。
+
+终端工具运行非交互命令，不提供交互式 stdin/PTY；需要交互登录的 CLI，请先在本机终端登录。原生 `@文件` 补全和 IDE 索引没有自动映射到本地，项目文件通过本地 MCP 工具访问。
+
+文件工具限定项目内，拒绝路径穿越和指向项目外的符号链接；修改已有文件需要精确旧文本或读取时的 SHA-256。终端具有启动用户的正常系统权限，项目工作目录不是操作系统沙箱。本地模式可使用本机 Git worktree。
+
+浏览器使用独立窗口和临时上下文，不读取日常 Chrome 的登录态。启动本地模式时准备相应浏览器版本，后续使用缓存；收到浏览器工具调用时才打开窗口。可以打开本机 localhost，填写表单、点击、截图和读取控制台错误。
+
+```bash
+claude-remote install-browser
+claude-remote configure my-server --headless   # 无窗口
+claude-remote configure my-server --headed     # 恢复可见窗口
+CLAUDE_REMOTE_HEADLESS=1 claude --local
+```
+
+Linux 上仍需安装 Playwright 所需的系统共享库，有窗口模式还需图形环境。工具不会自动以 sudo 安装系统依赖；缺失时按 Playwright 的错误提示配置。
+
+本地模式要求服务器允许 SSH TCP 转发，Claude Code 版本至少 **2.1.248**；已有版本过旧时会提示在服务器运行 `claude update`。每个会话创建仅监听本机回环地址的工具服务、随机令牌和 SSH 反向隧道；令牌通过 SSH 标准输入写入服务器 0600 临时配置，不出现在命令行参数或同步项目中。退出时清理配置、连接和浏览器。
+
+启动时使用 `--restricted`、`--tools ""`、`--strict-mcp-config`，限定工具和设置来源、关闭普通 hooks 和自定义命令。保留服务器上的订阅认证，不使用跳过 OAuth 的 `--bare`。本地连接失效时不会退回服务器工具。支持 `--continue`、`--resume`、`--model`、`--effort`、`-p` 和输入/输出格式；暂不接受替换工具配置、加载插件、切换云会话等参数。
+
+这是工具路由约束，不是对 Claude Code 主进程的系统隔离。认证、会话和日志仍在服务器，管理员管理策略继续生效。文件内容、命令结果和截图会经过服务器交给模型，不整体同步不代表数据不离开本机。
+
+## 同步管理（仅服务器模式）
 
 ```bash
 claude-remote status               # 查看全部项目、同步错误和文件冲突
@@ -87,7 +141,7 @@ claude-remote --help
 CLAUDE_REMOTE_HOST=another-server CLAUDE_REMOTE_PORT=2222 claude
 ```
 
-## 文件行为
+## 文件同步行为（仅服务器模式）
 
 - 每台本机、每个 SSH 地址/端口、每个项目目录有独立的稳定编号，远程默认映射到 `~/.local/share/claude-remote/projects/<编号>`。启动时会显示两端路径。移动项目或更换 SSH 别名会产生新的编号。
 - 启动远程 Claude 前等待首次同步，退出时也尝试完成一次同步。连接或最终同步失败会返回非零退出码；会话保留以便检查和重连。
@@ -105,15 +159,18 @@ CLAUDE_REMOTE_HOST=another-server CLAUDE_REMOTE_PORT=2222 claude
 
 | 变量 | 用途 |
 | --- | --- |
+| `CLAUDE_REMOTE_MODE` | 临时选择 `local` 或 `remote` |
+| `CLAUDE_REMOTE_HEADLESS` | `1` 无窗口浏览器，`0` 可见窗口，覆盖配置 |
 | `CLAUDE_REMOTE_HOST` | 临时 SSH 别名或 user@host |
 | `CLAUDE_REMOTE_PORT` | 临时 SSH 端口 |
 | `CLAUDE_REMOTE_CONFIG_DIR` | 配置和映射索引目录，默认 `~/.config/claude-remote` |
 | `CLAUDE_REMOTE_CACHE_DIR` | 下载缓存父目录，默认 `~/.cache/claude-remote` |
 | `CLAUDE_REMOTE_MUTAGEN` | 使用自行准备的 Mutagen 可执行文件绝对路径（应为 0.18.1，并放置配套代理包） |
-| `CLAUDE_REMOTE_SKIP_DOWNLOAD=1` | npm 安装阶段跳过准备，首次连接时仍会自动准备 |
+| `CLAUDE_REMOTE_PREPARE_SYNC=1` | npm 安装阶段提前准备同步工具，默认按需准备 |
+| `CLAUDE_REMOTE_SKIP_DOWNLOAD=1` | 跳过安装阶段的同步工具准备 |
 | `CLAUDE_REMOTE_DEBUG=1` | 出错时显示调试信息 |
 
-`npm install --ignore-scripts` 也受支持，首次连接会补装同步工具。无法访问 GitHub 时，可先在可联网环境准备工具，或使用 `CLAUDE_REMOTE_MUTAGEN` 指向完整的本机安装。
+`npm install --ignore-scripts` 也受支持，首次使用各模式时准备对应组件。无法访问 GitHub 时可自行准备 Mutagen 并使用 `CLAUDE_REMOTE_MUTAGEN`。浏览器缓存由 Playwright 管理，支持其 `PLAYWRIGHT_BROWSERS_PATH` 环境变量。
 
 卸载：先用 `claude-remote stop --all` 停止后台同步，再 `npm uninstall -g @znmin/claude-remote-cli`。npm 卸载保留本地配置、缓存和两端项目文件。
 
@@ -123,11 +180,11 @@ CLAUDE_REMOTE_HOST=another-server CLAUDE_REMOTE_PORT=2222 claude
 npm ci --ignore-scripts
 npm test
 
-# 可选：本机真实 Mutagen 双向同步与冲突测试
-CLAUDE_REMOTE_INTEGRATION=1 npm test
+# 可选：真实本地同步与受控浏览器测试
+CLAUDE_REMOTE_INTEGRATION=1 CLAUDE_REMOTE_BROWSER_TEST=1 npm test
 
 npm pack
-npm install -g ./znmin-claude-remote-cli-0.1.0.tgz
+npm install -g ./znmin-claude-remote-cli-0.2.0.tgz
 
 # 确定包名、版本和使用条款后，使用有发布权限的 npm 账号发布
 npm login
@@ -136,6 +193,6 @@ npm publish --access public
 
 GitHub 仓库名为 `claude-remote-cli`，npm 包名为 `@znmin/claude-remote-cli`，命令名为 `claude` 和 `claude-remote`。发布账号必须拥有 npm 用户作用域 `@znmin`，或拥有同名 npm 组织的发布权限；GitHub 身份不会自动授予 npm 权限。当前 `license` 为 `UNLICENSED`，尚未指定开源许可证。
 
-测试覆盖全局安装、命令入口、项目隔离、参数引用、冲突阻断、下载校验和本地真实双向同步。由于尚未提供服务器，真实 SSH 认证、远程 Claude 交互、Linux 和其他 CPU 架构尚未实测。
+测试覆盖真实 MCP HTTP 调用、本机文件与进程、受控浏览器交互、本地真实同步、模拟 SSH/Claude 的完整启动清理链路，以及官方安装流程的隔离模拟。尚未提供服务器，真实 SSH 认证、Claude 模型端到端调用、Linux 和其他 CPU 架构尚未实测。
 
 参考：[npm 命令入口配置](https://docs.npmjs.com/cli/configuring-npm/package-json#bin)、[Mutagen 同步机制](https://mutagen.io/documentation/synchronization/)、[Mutagen SSH 支持](https://mutagen.io/documentation/transports/ssh/)。

package/THIRD_PARTY_NOTICES.md

@@ -1,6 +1,8 @@
 # Third-party components
 
-The npm package contains the JavaScript CLI source and depends on `proper-lockfile` (MIT) and its npm-managed dependencies. Their license files are included in their respective npm packages.
+The npm package contains the JavaScript CLI source and depends on `proper-lockfile` (MIT), the official `@modelcontextprotocol/sdk` (MIT), `zod` (MIT), `playwright` (Apache-2.0), and their npm-managed dependencies. Their license files are included in their respective npm packages.
+
+Playwright downloads its matching Chromium/browser components on first local-mode preparation. These components remain subject to their upstream licenses. A separate local browser context is used; this wrapper does not include the user's browser profile.
 
 Mutagen binaries are **not bundled in this npm package**. At setup/first use, the tool can reuse an existing Mutagen 0.18.1 installation, or download the matching v0.18.1 archive from the official release repository. SHA-256 values are pinned in `src/installer.js` from the official release's `SHA256SUMS` file.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@znmin/claude-remote-cli",
-  "version": "0.1.0",
-  "description": "Run Claude Code on your SSH server with safe bidirectional project synchronization",
+  "version": "0.2.0",
+  "description": "Run Claude Code on an SSH server with local filesystem, terminal and browser tools, or remote bidirectional sync",
   "type": "module",
   "license": "UNLICENSED",
   "engines": {
@@ -43,7 +43,10 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "proper-lockfile": "4.1.2"
+    "@modelcontextprotocol/sdk": "1.32.2",
+    "playwright": "1.64.1",
+    "proper-lockfile": "4.1.2",
+    "zod": "4.6.7"
   },
   "repository": {
     "type": "git",

package/scripts/postinstall.js

@@ -1,6 +1,6 @@
 import { ensureMutagen } from '../src/installer.js';
 
-if (process.env.CLAUDE_REMOTE_SKIP_DOWNLOAD !== '1') {
+if (process.env.CLAUDE_REMOTE_PREPARE_SYNC === '1' && process.env.CLAUDE_REMOTE_SKIP_DOWNLOAD !== '1') {
   try {
     await ensureMutagen();
     console.log('claude 已安装。运行 claude-remote configure 用户名@服务器，或直接运行 claude 开始配置。');
@@ -9,3 +9,4 @@ if (process.env.CLAUDE_REMOTE_SKIP_DOWNLOAD !== '1') {
     console.warn(`CLI 已安装，同步工具准备未完成：${error.message}\n首次连接时会重试。`);
   }
 }
+console.log('安装完成：运行 claude 配置服务器并启动。新配置默认本地执行；同步工具和浏览器在对应模式首次使用时自动准备。');

package/src/cli.js

@@ -3,31 +3,41 @@ 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 { readFileSync } from 'node:fs';
 
-const HELP = `@znmin/claude-remote-cli 0.1.0（非 Anthropic 官方客户端）
+const PACKAGE = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+
+const HELP = `${PACKAGE.name} ${PACKAGE.version}（非 Anthropic 官方客户端）
 
 安装后使用：
   claude                           首次引导设置服务器，之后启动远程 Claude Code
   claude --continue                将参数传给服务器上的 Claude
+  claude --local                   本次使用本地文件、终端和受控浏览器
+  claude --remote                  本次使用服务器工具与双向同步
   claude-remote configure [user@host] [--port 2222] [--claude /路径/claude]
+  claude-remote mode local|remote   切换默认执行模式
   claude-remote status              查看全部同步状态和冲突
   claude-remote flush               等待当前目录同步完成
   claude-remote stop [--all | --name 名称]
   claude-remote doctor              检查本地环境，不连接服务器
   claude-remote install-sync        准备同步工具（通常自动完成）
+  claude-remote install-browser     准备本地受控浏览器（本地模式自动完成）
   claude-remote run [Claude 参数]   启动远程 Claude
 
-configure 可选：--root 远程根目录、--ignore 忽略规则（可重复）。
-服务器需要已安装并认证的 Claude Code；此工具不提供服务器或 Claude 账号。
+configure 可选：--mode local|remote、--headless/--headed、--root 远程根目录、--ignore 忽略规则（可重复）。
+新配置默认使用本地执行；旧配置保持服务器模式，直到显式切换。
+服务器缺少默认 Claude Code 时会自动安装；首次启动需完成认证。
+此工具不提供服务器或 Claude 账号。
 退出 Claude 后会继续后台同步；停止请运行 claude-remote stop。
 `;
 
 async function configure(client, args) {
   const { values, positionals } = parseArgs({ args, allowPositionals: true, options: {
     port: { type: 'string' }, root: { type: 'string' }, claude: { type: 'string' },
-    ignore: { type: 'string', multiple: true }
+    ignore: { type: 'string', multiple: true }, mode: { type: 'string' }, headless: { type: 'boolean' }, headed: { type: 'boolean' }
   } });
   if (positionals.length > 1) throw new Error('仅接受一个 SSH 别名或 user@host。');
+  if (values.headless && values.headed) throw new Error('--headless 和 --headed 不能同时使用。');
   let host = positionals[0], port = values.port;
   if (!host) {
     if (!process.stdin.isTTY) throw new Error('请指定服务器：claude-remote configure 用户名@服务器');
@@ -39,24 +49,47 @@ async function configure(client, args) {
     } finally { prompt.close(); }
   }
   return client.configure({ host, port: port === undefined ? null : Number(port),
-    root: values.root || DEFAULTS.root, claude: values.claude || DEFAULTS.claude, ignores: values.ignore || [] });
+    root: values.root || DEFAULTS.root, claude: values.claude || DEFAULTS.claude, ignores: values.ignore || [],
+    mode: values.mode, browserHeadless: values.headed ? false : values.headless });
+}
+
+export function executionOptions(args) {
+  const forwarded = []; let mode, literal = false;
+  for (const arg of args) {
+    if (arg === '--') literal = true;
+    if (!literal && (arg === '--local' || arg === '--remote')) {
+      const selected = arg.slice(2);
+      if (mode && mode !== selected) throw new Error('--local 和 --remote 不能同时使用。');
+      mode = selected;
+    } else forwarded.push(arg);
+  }
+  return { mode, forwarded };
 }
 
 export async function main(asClaude, args = process.argv.slice(2), client = new Client()) {
   if (asClaude) {
+    const options = executionOptions(args);
+    args = options.forwarded;
+    if (args.length === 1 && ['--help', '-h'].includes(args[0])) { console.log(HELP); return 0; }
+    if (args.length === 1 && ['--version', '-v'].includes(args[0])) { console.log(`${PACKAGE.name} ${PACKAGE.version}`); return 0; }
     const saved = await readJSON(client.configFile, {});
     if (!saved.host && !client.env.CLAUDE_REMOTE_HOST) {
       if (args.includes('--help') || args.includes('-h')) { console.log(HELP); return 0; }
-      if (args.includes('--version')) { console.log('@znmin/claude-remote-cli 0.1.0'); return 0; }
+      if (args.includes('--version')) { console.log(`${PACKAGE.name} ${PACKAGE.version}`); return 0; }
       if (process.stdin.isTTY) await configure(client, []);
     }
-    return client.launch(await client.settings(), args);
+    const config = await client.settings();
+    return client.launch(options.mode ? { ...config, mode: options.mode } : config, args);
   }
   const [action, ...rest] = args;
   if (!action || ['--help', '-h', 'help'].includes(action)) { console.log(HELP); return 0; }
-  if (['--version', '-v'].includes(action)) { console.log('0.1.0'); return 0; }
+  if (['--version', '-v'].includes(action)) { console.log(PACKAGE.version); return 0; }
   if (action === 'configure') { await configure(client, rest); return 0; }
-  if (action === 'run') return client.launch(await client.settings(), rest[0] === '--' ? rest.slice(1) : rest);
+  if (action === 'mode') {
+    if (rest.length !== 1) throw new Error('用法：claude-remote mode local|remote');
+    await client.setMode(rest[0]); return 0;
+  }
+  if (action === 'run') return main(true, rest[0] === '--' ? rest.slice(1) : rest, client);
   if (action === 'stop') {
     const { values, positionals } = parseArgs({ args: rest, allowPositionals: true,
       options: { all: { type: 'boolean' }, name: { type: 'string' } } });
@@ -71,6 +104,10 @@ export async function main(asClaude, args = process.argv.slice(2), client = new
     await client.flush((await client.project(await client.settings())).name); return 0;
   }
   if (action === 'install-sync') { console.log('同步工具：' + await ensureMutagen({ env: client.env })); return 0; }
+  if (action === 'install-browser') {
+    const { installBrowser } = await import('./local/browser.js');
+    await installBrowser(client.log); 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) || '未安装'}`);
@@ -78,6 +115,7 @@ export async function main(asClaude, args = process.argv.slice(2), client = new
     console.log(`同步工具：${client.env.CLAUDE_REMOTE_MUTAGEN || (await exists(cached) ? cached : await which('mutagen', client.env.PATH)) || '首次使用时自动下载'}（目标版本 ${VERSION}）`);
     const config = await readJSON(client.configFile, {});
     console.log(`配置：${client.configFile}\n服务器：${client.env.CLAUDE_REMOTE_HOST || config.host || '尚未配置'}`);
+    console.log(`默认模式：${client.env.CLAUDE_REMOTE_MODE || config.mode || 'remote（旧配置）'}`);
     return 0;
   }
   throw new Error(`未知命令 ${action}。运行 claude-remote --help 查看用法。`);

package/src/client.js

@@ -4,6 +4,9 @@ import os from 'node:os';
 import { createHash, randomUUID } from 'node:crypto';
 import { execute, exists, quote, readJSON, 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';
+export { sshArgs } from './ssh.js';
 
 export const DEFAULTS = {
   root: '.local/share/claude-remote/projects', claude: 'claude',
@@ -11,6 +14,8 @@ export const DEFAULTS = {
 };
 
 export function validate(config) {
+  if (config.mode != null && !['local', 'remote'].includes(config.mode)) throw new Error('模式只能是 local 或 remote。');
+  if (config.browserHeadless != null && typeof config.browserHeadless !== 'boolean') throw new Error('browserHeadless 必须是布尔值。');
   if (!/^(?:[A-Za-z0-9_][A-Za-z0-9_.-]*@)?[A-Za-z0-9_][A-Za-z0-9_.-]*$/.test(config.host || ''))
     throw new Error('服务器请填写 SSH 别名或 user@host，不要包含端口、空格或 SSH 参数。IPv6 请使用 SSH 别名。');
   if (config.port != null && (!Number.isInteger(config.port) || config.port < 1 || config.port > 65535))
@@ -28,16 +33,6 @@ export function validate(config) {
 }
 
 export const remotePath = file => file.startsWith('/') ? quote(file) : '"$HOME"/' + quote(file);
-const prefix = 'export PATH="$HOME/.local/bin:$PATH"; ';
-
-export function sshArgs(config, script, { interactive = false, tty = false } = {}) {
-  const args = ['-o', 'ConnectTimeout=15', '-o', 'ServerAliveInterval=15', '-o', 'ServerAliveCountMax=3'];
-  if (!interactive) args.push('-n'); // Never consume piped Claude prompts during preflight.
-  if (tty) args.push('-tt');
-  if (config.port != null) args.push('-p', String(config.port));
-  args.push(config.host, 'bash -lc ' + quote(script));
-  return args;
-}
 
 export function assertSynchronized(current) {
   if (!current) throw new Error('同步会话不存在。');
@@ -73,11 +68,12 @@ export class Client {
     return withLock(this.lockFile, async () => {
       const old = await readJSON(this.configFile, {});
       const config = validate({ ...DEFAULTS, ...input,
+        mode: input.mode ?? old.mode ?? 'local', browserHeadless: input.browserHeadless ?? old.browserHeadless ?? false,
         ignores: [...DEFAULTS.ignores, ...(input.ignores || [])],
         client_id: old.client_id || randomUUID().replaceAll('-', '').slice(0, 12) });
       await writeJSON(this.configFile, config);
       this.log(`已配置服务器：${config.host}。进入项目目录后运行 claude。`);
-      this.log('旧服务器的后台同步不会自动停止；切换前可运行 claude-remote stop --all。');
+      this.log(`当前模式：${config.mode === 'local' ? '本地执行' : '服务器执行与双向同步'}。旧后台同步不会自动停止，可用 claude-remote stop --all 停止。`);
       return config;
     });
   }
@@ -88,6 +84,7 @@ export class Client {
       const config = { ...DEFAULTS, ...stored };
       if (this.env.CLAUDE_REMOTE_HOST) config.host = this.env.CLAUDE_REMOTE_HOST;
       if (this.env.CLAUDE_REMOTE_PORT !== undefined) config.port = Number(this.env.CLAUDE_REMOTE_PORT);
+      config.mode = this.env.CLAUDE_REMOTE_MODE || config.mode || 'remote';
       if (!config.host) throw new Error('尚未配置服务器。请运行：claude-remote configure 用户名@服务器（自定义端口加 --port 2222）。');
       validate(config);
       if (!config.client_id) {
@@ -115,6 +112,15 @@ export class Client {
       host: config.host, port: config.port ?? null };
   }
 
+  async setMode(mode) {
+    if (!['local', 'remote'].includes(mode)) throw new Error('模式只能是 local 或 remote。');
+    await withLock(this.lockFile, async () => {
+      const stored = await readJSON(this.configFile, {});
+      await writeJSON(this.configFile, { ...stored, mode });
+    });
+    this.log(`默认模式已设为 ${mode}。旧后台同步不会自动停止；如需停止请运行 claude-remote stop --all。`);
+  }
+
   async prepare() {
     if (!this.mutagen) this.mutagen = await this.ensureMutagen({ env: this.env });
     return this.mutagen;
@@ -136,12 +142,16 @@ export class Client {
     assertSynchronized((await this.sessions()).find(session => session.name === name));
   }
 
-  async remote(config, script, interactive = false) {
+  async remote(config, script, interactive = false, { timeout = 180000 } = {}) {
     return this.execute('ssh', sshArgs(config, script, { interactive, tty: interactive && this.tty }),
-      { env: this.env, timeout: interactive ? 0 : 180000, check: !interactive });
+      { env: this.env, timeout: interactive ? 0 : timeout, check: !interactive });
   }
 
   async launch(config, extra) {
+    if (config.mode === 'local') {
+      const { launchLocal } = await import('./local-mode.js');
+      return launchLocal(this, config, extra);
+    }
     for (const tool of ['ssh', 'scp']) if (!await which(tool, this.env.PATH))
       throw new Error(`找不到系统 ${tool}，请安装 OpenSSH 客户端。`);
     const item = await this.project(config);
@@ -162,9 +172,8 @@ export class Client {
         if (inside(relative) || inside(reverse))
           throw new Error(`目录与正在同步的项目重叠：${other}\n先运行：claude-remote stop --name ${session.name}`);
       }
-      await this.remote(config, prefix + `command -v ${quote(config.claude)} >/dev/null || ` +
-        "{ echo '服务器找不到 Claude Code，请先安装并登录，或配置 --claude 绝对路径。' >&2; exit 127; }; " +
-        'mkdir -p -- ' + remotePath(item.remote));
+      await this.remote(config, ensureRemoteClaude(config.claude) +
+        'mkdir -p -- ' + remotePath(item.remote), false, { timeout: 600000 });
       if (existing.some(session => session.name === item.name)) {
         await this.sync(['resume', item.name], { timeout: 60000, capture: !this.tty });
       } else {

package/src/local/browser.js

@@ -0,0 +1,108 @@
+import path from 'node:path';
+import os from 'node:os';
+import { createRequire } from 'node:module';
+import { randomUUID } from 'node:crypto';
+import { chromium } from 'playwright';
+import { execute, exists, withLock } from '../system.js';
+
+const require = createRequire(import.meta.url);
+let preparation;
+
+export async function installBrowser(log = console.error) {
+  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 () => {
+      log('正在准备本地受控浏览器（首次使用或升级时自动下载）……');
+      // 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);
+    });
+  })().catch(error => { preparation = null; throw error; });
+  await preparation;
+}
+
+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;
+  }
+
+  async start() {
+    if (!this.starting) this.starting = (async () => {
+      await installBrowser(this.log);
+      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; });
+    await this.starting;
+  }
+
+  page(id) {
+    const page = this.pages.get(id);
+    if (!page || page.isClosed()) throw new Error('找不到浏览器页面，请先调用 browser_open。');
+    return page;
+  }
+
+  async open(url = 'about:blank') {
+    await this.start();
+    if (this.pages.size >= 16) throw new Error('浏览器页面过多，请先调用 browser_close 关闭部分页面。');
+    const page = await this.context.newPage(), id = randomUUID();
+    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();
+    };
+    page.on('console', message => record(`${message.type()}: ${message.text()}`));
+    page.on('pageerror', error => record('pageerror: ' + error.message));
+    page.on('requestfailed', request => record(`requestfailed: ${request.url()} ${request.failure()?.errorText}`));
+    let navigationError;
+    try { await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 }); }
+    catch (error) { navigationError = error.message; record(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 };
+  }
+
+  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 });
+    else if (action === 'press') {
+      if (selector) await page.locator(selector).press(value, { timeout: 15000 });
+      else await page.keyboard.press(value);
+    }
+    return this.snapshot(id);
+  }
+
+  async screenshot(id) {
+    const buffer = await this.page(id).screenshot({ type: 'png', timeout: 15000 });
+    return { content: [{ type: 'image', data: buffer.toString('base64'), mimeType: 'image/png' }] };
+  }
+
+  async closePage(id) {
+    await this.page(id).close(); this.pages.delete(id); this.logs.delete(id);
+    return { closed: id };
+  }
+
+  async close() {
+    if (this.starting) await this.starting.catch(() => {});
+    await this.browser?.close();
+    this.browser = null; this.context = null; this.starting = null;
+    this.pages.clear(); this.logs.clear();
+  }
+}

package/src/local/processes.js

@@ -0,0 +1,76 @@
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { quote } from '../system.js';
+
+const LIMIT = 256 * 1024;
+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) {
+    const job = this.jobs.get(id);
+    if (!job) throw new Error('找不到本会话的进程。');
+    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 };
+  }
+
+  async run(command, cwd = '.', timeoutMs = 30000, background = false, signal) {
+    if ([...this.jobs.values()].filter(job => !job.ended).length >= 16) throw new Error('后台进程过多，请先停止部分进程。');
+    for (const [id, job] of this.jobs) if (this.jobs.size >= 64 && job.ended) this.jobs.delete(id);
+    const directory = await this.workspace.resolve(cwd);
+    const shell = this.env.SHELL || '/bin/bash';
+    const child = spawn(shell, ['-lc', `cd -- ${quote(directory)} && ${command}`], {
+      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 };
+    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);
+      });
+      child.once('error', error => { job.stderr += 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) {
+      await Promise.race([job.done, delay(80)]);
+      return this.status(id);
+    }
+    const abort = () => this.stop(id).catch(() => {});
+    signal?.addEventListener('abort', abort, { once: true });
+    const timer = setTimeout(() => { job.timedOut = true; abort(); }, timeoutMs);
+    try {
+      if (signal?.aborted) abort();
+      await job.done;
+      return this.status(id);
+    } finally { clearTimeout(timer); signal?.removeEventListener('abort', abort); }
+  }
+
+  killGroup(job, signal) {
+    if (!job.child.pid) return;
+    try { process.kill(-job.child.pid, signal); }
+    catch (error) { if (error.code !== 'ESRCH') throw error; }
+  }
+
+  async stop(id) {
+    const job = this.jobs.get(id);
+    if (!job) throw new Error('找不到本会话的进程。');
+    if (job.ended) return this.status(id);
+    // Kill the owned group even if its parent shell has already exited.
+    this.killGroup(job, 'SIGTERM');
+    await Promise.race([job.done, delay(1500)]);
+    this.killGroup(job, 'SIGKILL');
+    await Promise.race([job.done, delay(1000)]);
+    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 };
+  }); }
+  async close() { await Promise.allSettled([...this.jobs.keys()].map(id => this.stop(id))); }
+}

package/src/local/server.js

@@ -0,0 +1,141 @@
+import http from 'node:http';
+import os from 'node:os';
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import * as fs from 'node:fs/promises';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { z } from 'zod';
+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 file = z.string().min(1).max(4096);
+const pageId = z.string().min(1);
+const selector = z.string().min(1).max(4000);
+
+export async function startLocalServer({ root, env = process.env, headless = false, browser, log = console.error } = {}) {
+  const workspace = new Workspace(await fs.realpath(root));
+  const processes = new Processes(workspace, env);
+  browser ||= new Browser({ headless, log });
+  const token = randomBytes(32).toString('hex');
+  const transports = new Set();
+  let closing = false;
+
+  function createServer() {
+    const server = new McpServer({ name: 'claude-local-tools', version: '0.2.0' });
+    const register = (name, description, inputSchema, handler, readOnly = false) => {
+      server.registerTool(name, { description, inputSchema,
+        annotations: { readOnlyHint: readOnly, idempotentHint: readOnly } }, async (args, extra) => {
+        try {
+          const value = await handler(args, extra);
+          return Array.isArray(value?.content) ? value : text(value);
+        } catch (error) { return { isError: true, content: [{ type: 'text', text: error.message }] }; }
+      });
+    };
+    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.', {
+      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.', {
+      path: file, content: z.string().max(1024 * 1024), expected_sha256: z.string().regex(/^[a-f0-9]{64}$/).optional()
+    }, args => workspace.write(args.path, args.content, args.expected_sha256));
+    register('edit_file', 'Edit a LOCAL file by exact text replacement. Include enough context for a unique match.', {
+      path: file, old_text: z.string().min(1).max(1024 * 1024), new_text: z.string().max(1024 * 1024), replace_all: z.boolean().default(false)
+    }, 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.', {
+      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);
+    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('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));
+    register('browser_open', 'Open a page in a dedicated LOCAL browser. localhost is the developer computer. Does not attach to existing browser profiles.', {
+      url: z.string().url().or(z.literal('about:blank')).default('about:blank')
+    }, args => browser.open(args.url));
+    register('browser_snapshot', 'Inspect a LOCAL browser page and get visible text and selectors for interactive elements.', { page_id: pageId },
+      args => browser.snapshot(args.page_id), true);
+    register('browser_click', 'Click a selector on a LOCAL browser page. Use selectors from browser_snapshot.', { page_id: pageId, selector },
+      args => browser.action(args.page_id, 'click', args.selector));
+    register('browser_fill', 'Fill an input on a LOCAL browser page.', { page_id: pageId, selector, value: z.string().max(100000) },
+      args => browser.action(args.page_id, 'fill', args.selector, args.value));
+    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_close', 'Close a LOCAL browser tab opened by this session.', { page_id: pageId }, args => browser.closePage(args.page_id));
+    return server;
+  }
+
+  const httpServer = http.createServer(async (request, response) => {
+    const expected = Buffer.from('Bearer ' + token), actual = Buffer.from(request.headers.authorization || '');
+    if (actual.length !== expected.length || !timingSafeEqual(actual, expected)) {
+      response.writeHead(401).end('Unauthorized'); return;
+    }
+    if (closing) { response.writeHead(503).end(); return; }
+    // Browser pages cannot invoke this privileged endpoint; native MCP clients do not send Origin.
+    if (request.headers.origin) { response.writeHead(403).end('Origin not allowed'); return; }
+    if (request.url !== '/mcp') { response.writeHead(404).end(); return; }
+    if (request.method !== 'POST') { response.writeHead(405, { Allow: 'POST' }).end(); return; }
+    let server, transport;
+    try {
+      const chunks = []; let bytes = 0;
+      for await (const chunk of request) {
+        bytes += chunk.length;
+        if (bytes > 2 * 1024 * 1024) { response.writeHead(413).end('Request too large'); return; }
+        chunks.push(chunk);
+      }
+      let body;
+      try { body = JSON.parse(Buffer.concat(chunks).toString('utf8')); }
+      catch { response.writeHead(400).end('Invalid JSON'); return; }
+      server = createServer();
+      transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true });
+      transports.add(transport);
+      response.on('close', () => {
+        transports.delete(transport);
+        transport.close().catch(() => {}); server.close().catch(() => {});
+      });
+      await server.connect(transport);
+      await transport.handleRequest(request, response, body);
+    } catch (error) {
+      await transport?.close().catch(() => {}); await server?.close().catch(() => {});
+      if (!response.headersSent) response.writeHead(500).end('MCP request failed');
+      else response.end();
+      log('本地工具请求失败：' + error.message);
+    }
+  });
+  httpServer.requestTimeout = 30000;
+  httpServer.headersTimeout = 10000;
+  await new Promise((resolve, reject) => {
+    httpServer.once('error', reject); httpServer.listen(0, '127.0.0.1', resolve);
+  });
+  const port = httpServer.address().port;
+  return { port, token, workspace, processes, browser,
+    async close() {
+      closing = true;
+      await Promise.allSettled([...transports].map(transport => transport.close()));
+      await Promise.allSettled([processes.close(), browser.close()]);
+      httpServer.closeAllConnections();
+      await new Promise(resolve => httpServer.close(resolve));
+    }
+  };
+}

package/src/local/tunnel.js

@@ -0,0 +1,50 @@
+import * as fs from 'node:fs/promises';
+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 { sshBase } from '../ssh.js';
+
+export async function openTunnel(config, localPort, { env = process.env, run = execute } = {}) {
+  // Keep the control socket below the short Unix-domain path limit on macOS.
+  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'] });
+  let closed = false, errorText = '', spawnError;
+  const done = new Promise(resolve => {
+    master.once('error', error => { spawnError = error; closed = true; resolve(); });
+    master.once('close', () => { closed = true; resolve(); });
+  });
+  master.stderr.setEncoding('utf8');
+  master.stderr.on('data', chunk => { errorText = (errorText + chunk).slice(-8000); process.stderr.write(chunk); });
+  const stop = async () => {
+    if (!closed) {
+      await run('ssh', [...sshBase(config), '-S', controlPath, '-O', 'exit', config.host],
+        { env, capture: true, timeout: 5000, check: false }).catch(() => {});
+      master.kill('SIGTERM');
+      await Promise.race([done, delay(1000)]);
+      if (!closed) { master.kill('SIGKILL'); await done; }
+    }
+    await fs.rm(directory, { recursive: true, force: true });
+  };
+  const interrupt = () => master.kill('SIGINT');
+  process.on('SIGINT', interrupt);
+  try {
+    const deadline = Date.now() + 120000;
+    while (!await exists(controlPath)) {
+      if (closed) throw new Error('SSH 工具连接失败：' + (spawnError?.message || errorText.trim() || '连接已关闭'));
+      if (Date.now() > deadline) throw new Error('等待 SSH 登录超时。');
+      await delay(100);
+    }
+    const result = await run('ssh', [...sshBase(config), '-S', controlPath, '-O', 'forward',
+      '-o', 'ExitOnForwardFailure=yes', '-R', `127.0.0.1:0:127.0.0.1:${localPort}`, config.host],
+    { env, capture: true, timeout: 15000 });
+    const port = Number(result.stdout.trim());
+    if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error('无法获取 SSH 反向隧道端口。请检查服务器是否允许 TCP 转发。');
+    return { controlPath, port, close: stop };
+  } catch (error) { await stop(); throw error; }
+  finally { process.off('SIGINT', interrupt); }
+}

package/src/local/workspace.js

@@ -0,0 +1,117 @@
+import * as fs from 'node:fs/promises';
+import path from 'node:path';
+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);
+
+export class Workspace {
+  constructor(root) { this.root = root; }
+
+  async resolve(input = '.', writing = false) {
+    const candidate = path.resolve(this.root, input);
+    if (!inside(this.root, candidate)) throw new Error('文件路径必须位于当前项目内。');
+    let canonical;
+    try { canonical = await fs.realpath(candidate); }
+    catch (error) {
+      if (error.code !== 'ENOENT' || !writing) throw error;
+      let parent = path.dirname(candidate);
+      while (true) {
+        try { canonical = path.join(await fs.realpath(parent), path.relative(parent, candidate)); break; }
+        catch (e) {
+          if (e.code !== 'ENOENT' || parent === path.dirname(parent)) throw e;
+          parent = path.dirname(parent);
+        }
+      }
+    }
+    if (!inside(this.root, canonical)) throw new Error('符号链接指向项目外部，无法访问。');
+    return canonical;
+  }
+
+  async read(file, offset = 1, limit = 200) {
+    const target = await this.resolve(file);
+    const stat = await fs.stat(target);
+    if (!stat.isFile() || stat.size > 2 * 1024 * 1024) throw new Error('仅支持读取 2 MiB 以内的文本文件。');
+    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') };
+  }
+
+  async atomicWrite(target, content, mode = 0o644) {
+    await fs.mkdir(path.dirname(target), { recursive: true });
+    const temp = path.join(path.dirname(target), '.claude-write-' + randomUUID());
+    try {
+      await fs.writeFile(temp, content, { flag: 'wx', mode });
+      await fs.rename(temp, target);
+    } finally { await fs.rm(temp, { force: true }); }
+    return { path: path.relative(this.root, target), sha256: hash(content), bytes: Buffer.byteLength(content) };
+  }
+
+  async write(file, content, expectedSha256) {
+    const target = await this.resolve(file, true);
+    let mode;
+    try {
+      if ((await fs.stat(target)).size > 2 * 1024 * 1024) throw new Error('覆盖文件大小上限为 2 MiB。');
+      const old = await fs.readFile(target, 'utf8');
+      mode = (await fs.stat(target)).mode & 0o777;
+      if (!expectedSha256 || hash(old) !== expectedSha256)
+        throw new Error('文件已存在或发生变化；先 read_file，再提供匹配的 expected_sha256。');
+    } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    return this.atomicWrite(target, content, mode);
+  }
+
+  async edit(file, oldText, newText, replaceAll = false) {
+    const target = await this.resolve(file);
+    const stat = await fs.stat(target);
+    if (stat.size > 2 * 1024 * 1024) throw new Error('编辑文件大小上限为 2 MiB。');
+    const content = await fs.readFile(target, 'utf8');
+    const matches = content.split(oldText).length - 1;
+    if (!matches) throw new Error('找不到 old_text，请重新读取文件。');
+    if (matches > 1 && !replaceAll) throw new Error('old_text 出现多次，请提供更精确的上下文或使用 replace_all。');
+    const next = replaceAll ? content.split(oldText).join(newText) : content.replace(oldText, () => newText);
+    return this.atomicWrite(target, next, stat.mode & 0o777);
+  }
+
+  async list(directory = '.') {
+    const target = await this.resolve(directory);
+    const entries = await fs.readdir(target, { withFileTypes: true });
+    return { path: path.relative(this.root, target) || '.', truncated: entries.length > 500,
+      entries: entries.sort((a, b) => a.name.localeCompare(b.name)).slice(0, 500).map(entry => ({
+        name: entry.name, type: entry.isSymbolicLink() ? 'symlink' : entry.isDirectory() ? 'directory' : 'file'
+      })) };
+  }
+
+  async search(pattern, directory = '.', maxResults = 100, caseSensitive = true) {
+    const root = await this.resolve(directory);
+    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;
+        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; }
+          }
+        }
+      }
+    };
+    await walk(root);
+    return { results, scanned_files: scanned, truncated };
+  }
+}

package/src/local-mode.js

@@ -0,0 +1,94 @@
+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 { sshArgs } from './ssh.js';
+import { remotePath } from './client.js';
+import { ensureRemoteClaude, remoteEnvironment } from './remote-claude.js';
+import { startLocalServer } from './local/server.js';
+import { installBrowser } from './local/browser.js';
+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']);
+const SUBCOMMANDS = new Set(['auth', 'mcp', 'install', 'update', 'doctor', 'agents', 'attach', 'gateway',
+  'daemon', 'remote-control', 'rc', 'desktop', 'setup-token']);
+
+export function validateLocalArguments(args) {
+  for (let i = 0; i < args.length; i++) {
+    const argument = args[i];
+    if (argument === '--') break;
+    if (!argument.startsWith('-')) {
+      if (SUBCOMMANDS.has(argument)) throw new Error('本地模式不执行服务器管理子命令；请用 SSH 管理服务器上的 Claude。');
+      continue;
+    }
+    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;
+    }
+    throw new Error(`本地模式暂不支持参数 ${name}；工具配置由本地模式统一管理。`);
+  }
+}
+
+export function localClaudeArguments(configFile, root, extra) {
+  validateLocalArguments(extra);
+  return ['--restricted', '--tools', '', '--strict-mcp-config', '--mcp-config', configFile,
+    '--setting-sources', '', '--disable-slash-commands', '--settings', JSON.stringify({ disableAllHooks: 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. ' +
+    '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 tool work; never fall back to server tools.', ...extra];
+}
+
+export function supportsLocalMode(output) {
+  const match = output.match(/\b(\d+)\.(\d+)\.(\d+)\b/);
+  if (!match) return false;
+  const [major, minor, patch] = match.slice(1).map(Number);
+  return major > 2 || major === 2 && (minor > 1 || minor === 1 && patch >= 248);
+}
+
+export async function launchLocal(client, config, extra, dependencies = {}) {
+  validateLocalArguments(extra);
+  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);
+  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 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 });
+  try {
+    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 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) });
+    client.log(`本地执行模式：${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 script = remoteEnvironment + 'cd -- ' + remotePath(remoteDirectory) + ' || exit 1; ' +
+      'trap ' + quote('rm -f -- ' + remotePath(configFile)) + ' EXIT; ' +
+      shellJoin([config.claude, ...args]);
+    return (await remote(script, { interactive: true, check: false })).code;
+  } finally {
+    if (tunnel && configFile) await remote('rm -f -- ' + remotePath(configFile), { timeout: 5000, check: false }).catch(() => {});
+    await gateway.close();
+    await tunnel?.close();
+  }
+}

package/src/remote-claude.js

@@ -0,0 +1,39 @@
+import { quote } from './system.js';
+
+export const remoteEnvironment = 'export PATH="$HOME/.local/bin:$PATH"; ';
+
+export function ensureRemoteClaude(command) {
+  const missing = command === 'claude' ? `
+  echo '服务器未安装 Claude Code，正在执行官方安装流程……' >&2
+  (
+    set -e
+    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 \\
+        --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
+    else
+      echo '自动安装需要服务器提供 curl 或 wget，请先安装其中一个工具。' >&2
+      exit 127
+    fi
+    if ! bash "$installer" >&2; then
+      echo 'Claude Code 官方安装失败，请检查上述输出、网络连接和目录权限后重试。' >&2
+      exit 1
+    fi
+  )
+  hash -r
+  if ! command -v claude >/dev/null 2>&1; then
+    echo '安装器已退出，但仍找不到 Claude Code。请检查 ~/.local/bin/claude 或通过 --claude 指定绝对路径。' >&2
+    exit 127
+  fi
+  echo 'Claude Code 已安装，首次启动时请按提示完成账号认证。' >&2
+` : `
+  echo ${quote('找不到配置的 Claude 程序：' + command + '。请修正 --claude 路径，或配置 --claude claude 使用自动安装。')} >&2
+  exit 127
+`;
+  // A failed download/installer must stop before any project directory is created or synced.
+  return 'set -e\n' + remoteEnvironment + '\n' +
+    `if ! command -v ${quote(command)} >/dev/null 2>&1; then\n${missing}fi\n`;
+}

package/src/ssh.js

@@ -0,0 +1,16 @@
+import { quote } from './system.js';
+
+export function sshBase(config) {
+  const args = ['-o', 'ConnectTimeout=15', '-o', 'ServerAliveInterval=15', '-o', 'ServerAliveCountMax=3'];
+  if (config.port != null) args.push('-p', String(config.port));
+  return args;
+}
+
+export function sshArgs(config, script, { interactive = false, tty = false, input = false, controlPath } = {}) {
+  const args = sshBase(config);
+  if (!interactive && !input) args.push('-n');
+  if (tty) args.push('-tt');
+  if (controlPath) args.push('-S', controlPath, '-o', 'ControlMaster=no');
+  args.push(config.host, 'bash -lc ' + quote(script));
+  return args;
+}

package/src/system.js

@@ -38,9 +38,14 @@ export async function writeJSON(file, value) {
   } finally { await fs.rm(temp, { force: true }); }
 }
 
-export function execute(command, args = [], { capture = false, timeout = 0, check = true, env = process.env } = {}) {
+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: capture ? ['ignore', 'pipe', 'pipe'] : 'inherit', env });
+    const child = 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);
+    }
     let stdout = '', stderr = '', timedOut = false, overflow = false, killTimer;
     const interrupt = () => child.kill('SIGINT');
     process.on('SIGINT', interrupt);