@znmin/claude-remote-cli 0.4.0 → 0.5.0

package/src/client.js

@@ -1,232 +1,89 @@
-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, 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';
-import { ensureSSH } from './ssh-auth.js';
-export { sshArgs } from './ssh.js';
-
-export const DEFAULTS = {
-  root: '.local/share/claude-remote/projects', claude: 'claude',
-  ignores: ['.DS_Store', 'node_modules', '.venv', '__pycache__']
-};
-
-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))
-    throw new Error('端口必须在 1–65535 之间。');
-  if (typeof config.root !== 'string' || !/^\/?[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)*$/.test(config.root) ||
-      config.root.split('/').some(part => ['.', '..'].includes(part)))
-    throw new Error('远程根目录仅支持字母、数字、点、短横线、下划线和斜杠，不支持 ..。');
-  if (typeof config.claude !== 'string' || !config.claude || /[\r\n\0]/.test(config.claude) || config.claude.startsWith('-'))
-    throw new Error('远程 Claude 程序路径无效。');
-  if (!Array.isArray(config.ignores) || config.ignores.some(pattern => typeof pattern !== 'string' || !pattern))
-    throw new Error('忽略规则需要是非空字符串列表。');
-  if (config.client_id != null && (typeof config.client_id !== 'string' || !config.client_id))
-    throw new Error('配置文件中的 client_id 无效。');
-  return config;
-}
-
-export const remotePath = file => file.startsWith('/') ? quote(file) : '"$HOME"/' + quote(file);
-
-export function assertSynchronized(current) {
-  if (!current) throw new Error('同步会话不存在。');
-  if (current.conflicts?.length || current.excludedConflicts)
-    throw new Error('发现双向修改冲突，未自动覆盖。运行 claude-remote status 查看路径，备份后将两边文件统一，再运行 claude-remote flush。');
-  for (const side of ['alpha', 'beta']) {
-    const state = current[side] || {};
-    if (state.scanProblems?.length || state.transitionProblems?.length || state.excludedScanProblems || state.excludedTransitionProblems)
-      throw new Error('同步端点有文件处理错误，请运行 claude-remote status 查看详情。');
-    if (state.connected === false) throw new Error('同步端点已断开，请检查连接后重试。');
-  }
-  if (current.lastError) throw new Error('同步尚有错误：' + current.lastError);
-  if (current.paused) throw new Error('同步会话已暂停，请重新运行 claude 恢复。');
-}
-
-export class Client {
-  constructor(options = {}) {
-    this.env = options.env || process.env;
-    this.home = options.home || os.homedir();
-    this.cwd = options.cwd || process.cwd();
-    this.platform = options.platform || process.platform;
-    this.directory = options.configDir || this.env.CLAUDE_REMOTE_CONFIG_DIR || path.join(this.home, '.config', 'claude-remote');
-    this.configFile = path.join(this.directory, 'config.json');
-    this.registryFile = path.join(this.directory, 'projects.json');
-    this.lockFile = path.join(this.directory, 'npm-state');
-    this.execute = options.execute || execute;
-    this.ensureSSH = options.ensureSSH || ensureSSH;
-    this.ensureMutagen = options.ensureMutagen || ensureMutagen;
-    this.log = options.log || console.error;
-    this.warn = options.warn || console.error;
-    this.debug = (...messages) => {
-      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) {
-    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}（${config.mode === 'local' ? '本地执行' : '远程同步'}）。`);
-      this.debug(`配置文件：${this.configFile}`);
-      if (old.host && (old.host !== config.host || (old.mode || 'remote') !== config.mode))
-        this.log('停止旧同步：claude-remote stop --all');
-      return config;
-    });
-  }
-
-  async settings() {
-    return withLock(this.lockFile, async () => {
-      const stored = await readJSON(this.configFile, {});
-      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) {
-        config.client_id = randomUUID().replaceAll('-', '').slice(0, 12);
-        // Temporary environment overrides must not change the saved server.
-        await writeJSON(this.configFile, { ...stored, client_id: config.client_id });
-      }
-      return config;
-    });
-  }
-
-  async project(config) {
-    const local = await fs.realpath(this.cwd);
-    const home = await fs.realpath(this.home);
-    if (local === home || local === path.parse(local).root)
-      throw new Error('请进入具体项目目录；不允许同步整个用户目录或磁盘根目录。');
-    const git = path.join(local, '.git');
-    if (await exists(git) && (await fs.stat(git)).isFile())
-      throw new Error('当前目录的 .git 指向外部仓库，暂不支持 Git worktree/子模块；请使用普通独立仓库。');
-    // Keep the original Python implementation's stable project identifiers.
-    const identity = '[' + [config.client_id, config.host, config.port ?? null, config.root, local]
-      .map(value => JSON.stringify(value)).join(', ') + ']';
-    const key = createHash('sha256').update(identity).digest('hex').slice(0, 24);
-    return { name: 'claude-remote-' + key, local, remote: config.root + '/' + key,
-      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;
-  }
-
-  async sync(args, options = {}) {
-    const binary = await this.prepare();
-    return this.execute(binary, ['sync', ...args], { env: this.env, capture: true, ...options });
-  }
-
-  async sessions() {
-    const result = await this.sync(['list', '--label-selector', 'claude-remote=true', '--template', '{{json .}}'],
-      { capture: true, timeout: 30000 });
-    return JSON.parse(result.stdout) || [];
-  }
-
-  async flush(name) {
-    await this.sync(['flush', name], { timeout: 120000 });
-    assertSynchronized((await this.sessions()).find(session => session.name === name));
-  }
-
-  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 : timeout, check: !interactive });
-  }
-
-  async launch(config, extra) {
-    this.debug(`连接：${config.host}${config.port ? ':' + config.port : ''}，模式：${config.mode || 'remote'}`);
-    await this.ensureSSH(this, config);
-    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);
-    await this.prepare();
-    await withLock(this.lockFile, async () => {
-      const existing = await this.sessions();
-      const registry = await readJSON(this.registryFile, {});
-      for (const session of existing) {
-        if (session.name === item.name) continue;
-        const storedPath = session.alpha?.path || registry[session.name]?.local;
-        if (!storedPath) continue;
-        let other;
-        try { other = await fs.realpath(storedPath); }
-        catch (error) { if (error.code !== 'ENOENT') throw error; other = path.resolve(storedPath); }
-        const relative = path.relative(other, item.local);
-        const reverse = path.relative(item.local, other);
-        const inside = value => value === '' || (!value.startsWith('..' + path.sep) && value !== '..' && !path.isAbsolute(value));
-        if (inside(relative) || inside(reverse))
-          throw new Error(`目录与正在同步的项目重叠：${other}\n先运行：claude-remote stop --name ${session.name}`);
-      }
-      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.env.CLAUDE_REMOTE_DEBUG !== '1' || !this.tty });
-      } else {
-        const endpoint = config.host + ':' + (config.port != null ? config.port + ':' : '') +
-          (item.remote.startsWith('/') ? item.remote : '~/' + item.remote);
-        const args = ['create', '--name', item.name, '--label', 'claude-remote=true', '--mode', 'two-way-safe',
-          '--no-global-configuration', '--no-ignore-vcs', '--watch-polling-interval', '2'];
-        for (const pattern of config.ignores) args.push('--ignore', pattern);
-        await this.sync([...args, item.local, endpoint], { timeout: 180000, capture: this.env.CLAUDE_REMOTE_DEBUG !== '1' || !this.tty });
-      }
-      registry[item.name] = item;
-      await writeJSON(this.registryFile, registry);
-    });
-    this.debug(`本地：${item.local}\n远程：${config.host}:${item.remote}`);
-    this.log('正在同步…');
-    await this.flush(item.name);
-    this.debug('同步完成，启动远程 Claude Code。退出后继续后台同步；停止请运行 claude-remote stop。');
-    let code = 1;
-    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) {
-        this.warn(`退出时同步未确认完成：${error.message}\n会话保留，可用 claude-remote status 检查。`);
-        if (code === 0) code = 1;
-      }
-    }
-    return code;
-  }
-
-  async stop({ all = false, name } = {}) {
-    const selected = all || name ? name : (await this.project(await this.settings())).name;
-    return withLock(this.lockFile, async () => {
-      const available = (await this.sessions()).map(session => session.name);
-      const targets = all ? available : [selected];
-      if (!targets.length || targets.some(target => !available.includes(target)))
-        throw new Error('没有找到对应同步会话；运行 claude-remote status 查看。');
-      await this.sync(['terminate', ...targets], { timeout: 30000 });
-      this.log('已停止同步，保留本地和远程文件。');
-    });
-  }
-}
+import path from 'node:path';
+import os from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { quote, readJSON, restoreTerminal, withLock, writeJSON, execute } from './system.js';
+import { ensureSSH } from './ssh-auth.js';
+export { sshArgs } from './ssh.js';
+
+export const DEFAULTS = { root: '.local/share/claude-remote/projects', claude: 'claude' };
+
+// Saved by versions before 0.5.0 (server mode with file synchronization); ignored now.
+const OBSOLETE = ['mode', 'ignores'];
+
+export function validate(config) {
+  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))
+    throw new Error('端口必须在 1–65535 之间。');
+  if (typeof config.root !== 'string' || !/^\/?[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)*$/.test(config.root) ||
+      config.root.split('/').some(part => ['.', '..'].includes(part)))
+    throw new Error('远程根目录仅支持字母、数字、点、短横线、下划线和斜杠，不支持 ..。');
+  if (typeof config.claude !== 'string' || !config.claude || /[\r\n\0]/.test(config.claude) || config.claude.startsWith('-'))
+    throw new Error('远程 Claude 程序路径无效。');
+  if (config.client_id != null && (typeof config.client_id !== 'string' || !config.client_id))
+    throw new Error('配置文件中的 client_id 无效。');
+  return config;
+}
+
+export const remotePath = file => file.startsWith('/') ? quote(file) : '"$HOME"/' + quote(file);
+
+const withoutObsolete = config => Object.fromEntries(Object.entries(config).filter(([key]) => !OBSOLETE.includes(key)));
+
+export class Client {
+  constructor(options = {}) {
+    this.env = options.env || process.env;
+    this.home = options.home || os.homedir();
+    this.cwd = options.cwd || process.cwd();
+    this.platform = options.platform || process.platform;
+    this.directory = options.configDir || this.env.CLAUDE_REMOTE_CONFIG_DIR || path.join(this.home, '.config', 'claude-remote');
+    this.configFile = path.join(this.directory, 'config.json');
+    this.lockFile = path.join(this.directory, 'npm-state');
+    this.execute = options.execute || execute;
+    this.ensureSSH = options.ensureSSH || ensureSSH;
+    this.log = options.log || console.error;
+    this.warn = options.warn || console.error;
+    this.debug = (...messages) => {
+      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) {
+    return withLock(this.lockFile, async () => {
+      const old = await readJSON(this.configFile, {});
+      const config = validate({ ...DEFAULTS, ...withoutObsolete(input),
+        browserHeadless: input.browserHeadless ?? old.browserHeadless ?? false,
+        client_id: old.client_id || randomUUID().replaceAll('-', '').slice(0, 12) });
+      await writeJSON(this.configFile, config);
+      this.log(`已保存：${config.host}。`);
+      this.debug(`配置文件：${this.configFile}`);
+      return config;
+    });
+  }
+
+  async settings() {
+    return withLock(this.lockFile, async () => {
+      const stored = await readJSON(this.configFile, {});
+      const config = { ...DEFAULTS, ...withoutObsolete(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);
+      if (!config.host) throw new Error('尚未配置服务器。请运行：claude-remote configure 用户名@服务器（自定义端口加 --port 2222）。');
+      validate(config);
+      if (!config.client_id) {
+        config.client_id = randomUUID().replaceAll('-', '').slice(0, 12);
+        // Temporary environment overrides must not change the saved server.
+        await writeJSON(this.configFile, { ...stored, client_id: config.client_id });
+      }
+      return config;
+    });
+  }
+
+  async launch(config, extra) {
+    this.debug(`连接：${config.host}${config.port ? ':' + config.port : ''}`);
+    await this.ensureSSH(this, config);
+    const { launchLocal } = await import('./local-mode.js');
+    return launchLocal(this, config, extra);
+  }
+}

package/src/local/clipboard.js

@@ -0,0 +1,87 @@
+import * as fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+
+const TIMEOUT = 15000;
+const MAX_IMAGE = 64 * 1024 * 1024;
+
+// Windows: a bitmap on the clipboard (screenshots), or an image file copied in
+// Explorer. Both are re-encoded as PNG and written to stdout as base64.
+const WINDOWS_SCRIPT = `
+$ErrorActionPreference = 'Stop'
+Add-Type -AssemblyName System.Windows.Forms
+Add-Type -AssemblyName System.Drawing
+$image = [System.Windows.Forms.Clipboard]::GetImage()
+if ($null -eq $image -and [System.Windows.Forms.Clipboard]::ContainsFileDropList()) {
+  foreach ($file in [System.Windows.Forms.Clipboard]::GetFileDropList()) {
+    if ($file -match '\\.(png|jpe?g|gif|bmp|tiff?)$') {
+      try { $image = [System.Drawing.Image]::FromFile($file); break } catch { }
+    }
+  }
+}
+if ($null -eq $image) { exit 3 }
+$stream = New-Object System.IO.MemoryStream
+$image.Save($stream, [System.Drawing.Imaging.ImageFormat]::Png)
+[Console]::Out.Write([Convert]::ToBase64String($stream.ToArray()))
+`;
+
+// Runs a program and collects stdout as bytes. Resolves null on any failure:
+// an empty clipboard and a missing tool both just mean "no image".
+export function captureBytes(command, args, { timeout = TIMEOUT, env = process.env } = {}) {
+  return new Promise(resolve => {
+    let child;
+    try { child = spawn(command, args, { env, stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true }); }
+    catch { resolve(null); return; }
+    const chunks = []; let bytes = 0, failed = false;
+    const timer = setTimeout(() => { failed = true; child.kill(); }, timeout);
+    child.stdout.on('data', chunk => {
+      bytes += chunk.length;
+      if (bytes > MAX_IMAGE * 2) { failed = true; child.kill(); } else chunks.push(chunk);
+    });
+    child.once('error', () => { clearTimeout(timer); resolve(null); });
+    child.once('close', code => {
+      clearTimeout(timer);
+      resolve(failed || code !== 0 ? null : Buffer.concat(chunks));
+    });
+  });
+}
+
+const isPng = data => data?.length > 8 && data.readUInt32BE(0) === 0x89504e47;
+
+async function readWindows(run, env) {
+  const system = env.SystemRoot || env.SYSTEMROOT || 'C:\\Windows';
+  const powershell = path.join(system, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
+  const output = await run(powershell, ['-NoProfile', '-NonInteractive', '-Sta', '-ExecutionPolicy', 'Bypass',
+    '-Command', WINDOWS_SCRIPT], { env });
+  if (!output?.length) return null;
+  return Buffer.from(output.toString('ascii').trim(), 'base64');
+}
+
+async function readMac(run, env) {
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), 'ccr-clip-'));
+  const file = path.join(directory, 'clipboard.png');
+  try {
+    const result = await run('osascript', ['-e', 'set png_data to (the clipboard as «class PNGf»)',
+      '-e', `set fp to open for access POSIX file ${JSON.stringify(file)} with write permission`,
+      '-e', 'write png_data to fp', '-e', 'close access fp'], { env });
+    if (result === null) return null;
+    return await fs.readFile(file);
+  } catch { return null; }
+  finally { await fs.rm(directory, { recursive: true, force: true }); }
+}
+
+async function readLinux(run, env) {
+  if (env.WAYLAND_DISPLAY) {
+    const data = await run('wl-paste', ['--no-newline', '--type', 'image/png'], { env });
+    if (data?.length) return data;
+  }
+  return run('xclip', ['-selection', 'clipboard', '-t', 'image/png', '-o'], { env });
+}
+
+// Returns the image on THIS computer's clipboard as PNG bytes, or null.
+export async function readClipboardImage({ platform = process.platform, env = process.env, run = captureBytes } = {}) {
+  const read = platform === 'win32' ? readWindows : platform === 'darwin' ? readMac : readLinux;
+  const data = await read(run, env).catch(() => null);
+  return isPng(data) && data.length <= MAX_IMAGE ? data : null;
+}

package/src/local/server.js

@@ -11,6 +11,7 @@ import { Processes } from './processes.js';
 import { describeShell } from './shell.js';
 import { Browser } from './browser.js';
 import { MAX_RESULT } from './mcp-proxy.js';
+import { readClipboardImage } from './clipboard.js';
 
 const PACKAGE = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
 
@@ -44,7 +45,7 @@ const selector = z.string().min(1).max(4000);
 // `upstreams` maps names to developer MCP servers (see mcp-proxy.js), served at
 // /mcp/<name>. The map may be filled after the gateway starts.
 export async function startLocalServer({ root, env = process.env, headless = false, browser, log = console.error,
-  upstreams = new Map() } = {}) {
+  upstreams = new Map(), readClipboard = readClipboardImage } = {}) {
   const workspace = new Workspace(await fs.realpath(root));
   const processes = new Processes(workspace, env);
   browser ||= new Browser({ headless, log, env });
@@ -149,6 +150,20 @@ export async function startLocalServer({ root, env = process.env, headless = fal
     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; }
+    // The remote `xclip` stand-in fetches the LOCAL clipboard image here, so
+    // pasting a screenshot (Alt+V / Ctrl+V) in the remote Claude works.
+    if (request.url === '/clipboard/image') {
+      if (request.method !== 'GET') { response.writeHead(405, { Allow: 'GET' }).end(); return; }
+      try {
+        const image = await readClipboard({ env });
+        if (!image) { response.writeHead(204).end(); return; }
+        response.writeHead(200, { 'Content-Type': 'image/png', 'Content-Length': image.length }).end(image);
+      } catch (error) {
+        log('读取本机剪贴板失败：' + error.message);
+        if (!response.headersSent) response.writeHead(500).end();
+      }
+      return;
+    }
     let upstream;
     if (request.url !== '/mcp') {
       const match = request.url.match(/^\/mcp\/([A-Za-z0-9_-]{1,64})$/);

package/src/local-mode.js

@@ -5,6 +5,7 @@ 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';
+import { ALT_V_BINDING, ensureAltVBinding, installClipboardShim, KEYBINDING_MISSING } from './remote-clipboard.js';
 import { startLocalServer } from './local/server.js';
 import { installBrowser } from './local/browser.js';
 import { openTunnel } from './local/tunnel.js';
@@ -151,7 +152,7 @@ export async function launchLocal(client, config, extra, dependencies = {}) {
   // Prepare the browser while SSH connects; it is only needed before Claude starts.
   const browserReady = (dependencies.installBrowser || installBrowser)(client.log, { debug: client.debug, env: client.env });
   browserReady.catch(() => {}); // Reported when awaited below.
-  let gateway, tunnel, configFile, promptFile, cleaning;
+  let gateway, tunnel, configFile, promptFile, clipboardDirectory, cleaning;
   const upstreams = new Map(), abort = new AbortController();
   let connecting = Promise.resolve();
   const hash = createHash('sha256').update(config.client_id + '\0' + root).digest('hex').slice(0, 24);
@@ -162,7 +163,8 @@ export async function launchLocal(client, config, extra, dependencies = {}) {
       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 remote('rm -rf -- ' + remotePath(configFile) + ' ' + remotePath(promptFile) + ' ' + remotePath(clipboardDirectory),
+        { timeout: 5000, check: false }).catch(() => {});
     abort.abort();
     await gateway?.close();
     await connecting;
@@ -177,11 +179,13 @@ export async function launchLocal(client, config, extra, dependencies = {}) {
       .then(connected => { for (const [name, upstream] of connected) upstreams.set(name, upstream); })
       .catch(error => client.warn('MCP 连接失败：' + error.message));
     gateway = await (dependencies.startLocalServer || startLocalServer)({ root, env: client.env, upstreams,
+      readClipboard: dependencies.readClipboard,
       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 session = randomUUID();
     configFile = remoteDirectory + '/.local-mcp-' + session + '.json';
     promptFile = remoteDirectory + '/.local-prompt-' + session + '.md';
+    clipboardDirectory = remoteDirectory + '/.local-clipboard-' + session;
     await connecting;
     const endpoint = suffix => ({ type: 'http', url: `http://127.0.0.1:${tunnel.port}/mcp${suffix}`,
       headers: { Authorization: 'Bearer ' + gateway.token }, timeout: CALL_TIMEOUT });
@@ -191,22 +195,30 @@ export async function launchLocal(client, config, extra, dependencies = {}) {
     const prompt = localPrompt(root, { instructions: await projectInstructions(root), appended: extractAppendedPrompts(extra).prompts,
       platform: client.platform, mcpServers: [...upstreams.keys()] });
     // 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.
+    // config (first stdin line), the clipboard stand-in with its Authorization
+    // header (second line) and the prompt (the rest), then report the version.
+    // `read` consumes the pipe byte by byte, so nothing is lost between the 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' +
+      installClipboardShim(remotePath(clipboardDirectory), quote(`http://127.0.0.1:${tunnel.port}/clipboard/image`)) +
+      (client.platform === 'win32' ? ensureAltVBinding() : '') +
       '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。');
+    { input: JSON.stringify(mcp) + '\nAuthorization: Bearer ' + gateway.token + '\n' + prompt, timeout: 600000 });
+    if (!supportsLocalMode(version.stdout)) throw new Error('本地工具模式需要服务器 Claude Code 2.1.248 或更高版本。请先在服务器运行 claude update。');
+    if (version.stdout.includes(KEYBINDING_MISSING))
+      client.warn('服务器的 ~/.claude/keybindings.json 已存在但未绑定 Alt+V，按 Alt+V 无法粘贴本机截图。' +
+        '请在其 "bindings" 数组中加入：' + JSON.stringify(ALT_V_BINDING));
     await browserReady;
     client.debug(`本地执行模式：${root}\n文件、命令和浏览器在本机运行；项目文件不通过本模式同步。`);
     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.
+    // The clipboard stand-in goes first on PATH for Claude only, so pasting an
+    // image reads this computer's clipboard.
     const script = remoteEnvironment + 'cd -- ' + remotePath(remoteDirectory) + ' || exit 1; ' +
-      'trap ' + quote('rm -f -- ' + remotePath(configFile) + ' ' + remotePath(promptFile)) + ' EXIT; ' +
-      shellJoin([config.claude, ...args]);
+      'trap ' + quote('rm -rf -- ' + remotePath(configFile) + ' ' + remotePath(promptFile) + ' ' + remotePath(clipboardDirectory)) + ' EXIT; ' +
+      'PATH=' + remotePath(clipboardDirectory) + ':"$PATH" ' + shellJoin([config.claude, ...args]);
     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();

package/src/remote-claude.js

@@ -33,7 +33,7 @@ export function ensureRemoteClaude(command) {
   echo ${quote('找不到配置的 Claude 程序：' + command + '。请修正 --claude 路径，或配置 --claude claude 使用自动安装。')} >&2
   exit 127
 `;
-  // A failed download/installer must stop before any project directory is created or synced.
+  // A failed download/installer must stop before any session files are written.
   return 'set -e\n' + remoteEnvironment + '\n' +
     `if ! command -v ${quote(command)} >/dev/null 2>&1; then\n${missing}fi\n`;
 }