@znmin/claude-remote-cli 0.4.0 → 0.4.1

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.4.0.tgz
+npm install -g ./znmin-claude-remote-cli-0.4.1.tgz
 ```
 
-若系统 npm 全局目录不可写，可使用 `npm install -g --prefix "$HOME/.local" ./znmin-claude-remote-cli-0.4.0.tgz`，并确保 `~/.local/bin` 在 PATH 中；卸载时也使用相同的 `--prefix`。
+若系统 npm 全局目录不可写，可使用 `npm install -g --prefix "$HOME/.local" ./znmin-claude-remote-cli-0.4.1.tgz`，并确保 `~/.local/bin` 在 PATH 中；卸载时也使用相同的 `--prefix`。
 
 npm 中不带作用域的 `claude-remote-cli` 属于其他项目。本项目使用独立的 `@znmin/claude-remote-cli` 作用域包名；请安装完整包名，或使用上述 GitHub 地址及本项目分发的 `.tgz` 文件。
 
@@ -175,6 +175,17 @@ Linux 上仍需安装 Playwright 所需的系统共享库，有窗口模式还
 
 启动时使用 `--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`）。暂不接受替换工具配置、加载插件、切换云会话等参数。
 
+#### 粘贴本机截图（0.4.1）
+
+本地模式下，截图后直接在 Claude 输入框按平时的图片粘贴快捷键（Windows 为 Alt+V，macOS/Linux 为 Ctrl+V），就能粘贴**本机**剪贴板里的图片，和在本机运行 Claude Code 一样显示为 `[Image #1]`。
+
+原理：Linux 版 Claude Code 通过 `xclip -selection clipboard -t TARGETS/image/png -o` 读取剪贴板图片。每个会话在服务器临时目录放一个 `xclip` 替身，只放在本次 Claude 进程的 PATH 最前面。替身通过同一条 SSH 反向隧道向本机工具服务请求剪贴板图片（`GET /clipboard/image`，校验同一个令牌）；令牌以 0600 文件保存，通过 `curl -H @文件` 读取，不出现在服务器进程列表里。其他 `xclip` 调用（读取文本、其他选区）交给服务器上原有的 `xclip`，只有在 Claude 请求图片时才会读取本机剪贴板。退出时替身和令牌文件随临时配置一起删除。
+
+- 快捷键：服务器上的 Linux 版 Claude 默认只认 Ctrl+V，而 Windows 终端会自己处理 Ctrl+V。因此从 Windows 启动时，如果服务器上没有 `~/.claude/keybindings.json`，会自动创建它并加入 `"alt+v": "chat:imagePaste"`（`--restricted` 下同样生效）。已有该文件时不会修改，只在启动时提示需要加入的那一行。
+- 本机读取方式：Windows 用 PowerShell 读取截图或资源管理器中复制的图片文件；macOS 用 `osascript`；Linux 用 `wl-paste` 或 `xclip`。
+- 服务器需要 `curl` 或 `python3`。
+- 服务器模式（`remote`）暂不支持；需要时可将图片保存到项目目录，同步后用 `@文件名` 引用。
+
 本地模式的路由规则、本地 CLAUDE.md 和用户传入的 `--append-system-prompt` 内容合并为一个文件，通过 SSH 标准输入写入服务器临时目录（权限 0600），再用 `--append-system-prompt-file` 加载；用户的追加内容排在路由规则之后，不会替换它。退出时与 MCP 配置一起删除。
 
 这是工具路由约束，不是对 Claude Code 主进程的系统隔离。认证、会话和日志仍在服务器，管理员管理策略继续生效。文件内容、命令结果和截图会经过服务器交给模型，不整体同步不代表数据不离开本机。
@@ -296,7 +307,7 @@ npm run test:windows   # Windows 上运行的客户端测试（CI 在 windows-la
 CLAUDE_REMOTE_INTEGRATION=1 CLAUDE_REMOTE_BROWSER_TEST=1 npm test
 
 npm pack
-npm install -g ./znmin-claude-remote-cli-0.4.0.tgz
+npm install -g ./znmin-claude-remote-cli-0.4.1.tgz
 
 # 确定包名、版本和使用条款后，使用有发布权限的 npm 账号发布
 npm login

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@znmin/claude-remote-cli",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Run Claude Code on an SSH server from macOS, Linux or Windows with local filesystem, terminal and browser tools, or remote bidirectional sync",
   "type": "module",
   "license": "UNLICENSED",

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-clipboard.js

@@ -0,0 +1,97 @@
+import { quote } from './system.js';
+
+// Claude Code on Linux reads a pasted image by running
+//   xclip -selection clipboard -t TARGETS -o      (is there an image?)
+//   xclip -selection clipboard -t image/png -o    (write it to a file)
+// This stand-in is put first on the remote Claude's PATH and answers those two
+// reads with the image on the LOCAL clipboard, fetched through the SSH reverse
+// tunnel. Every other call is passed on to the real xclip, if any.
+// The token stays in a 0600 file read with `curl -H @file`, so it never
+// appears in a process list on the server.
+export const XCLIP_SHIM = `#!/bin/sh
+# claude-remote: serve clipboard image reads from the LOCAL computer.
+dir=$(cd -- "$(dirname -- "$0")" && pwd -P)
+selection=primary target= output= previous=
+for argument in "$@"; do
+  case $previous in
+    -selection|-sel) selection=$argument ;;
+    -t|-target) target=$argument ;;
+  esac
+  case $argument in -o|-out) output=1 ;; esac
+  previous=$argument
+done
+
+real() {
+  PATH=$(printf '%s' "$PATH" | tr ':' '\\n' | grep -vxF -- "$dir" | paste -s -d: -)
+  export PATH
+  command -v xclip >/dev/null 2>&1 || exit 1
+  exec xclip "$@"
+}
+
+# Download the LOCAL clipboard image to $1; fails when there is none (HTTP 204).
+fetch() {
+  part=$1.part
+  rm -f -- "$part"
+  if command -v curl >/dev/null 2>&1; then
+    curl -sf --max-time 20 -H @"$dir/header" -o "$part" "$(cat -- "$dir/url")" 2>/dev/null
+  elif command -v python3 >/dev/null 2>&1; then
+    python3 - "$dir" "$part" <<'PYTHON' 2>/dev/null
+import sys, urllib.request
+directory, target = sys.argv[1], sys.argv[2]
+name, value = open(directory + '/header').read().strip().split(': ', 1)
+request = urllib.request.Request(open(directory + '/url').read().strip(), headers={name: value})
+with urllib.request.urlopen(request, timeout=20) as response, open(target, 'wb') as output:
+    output.write(response.read())
+PYTHON
+  else
+    return 1
+  fi
+  if [ -s "$part" ]; then mv -f -- "$part" "$1"; else rm -f -- "$part"; return 1; fi
+}
+
+if [ "$output" = 1 ] && [ "$selection" = clipboard ]; then
+  cache=$dir/clipboard.png
+  case $target in
+    TARGETS)
+      fetch "$cache" || exit 1
+      printf 'TARGETS\\nimage/png\\n'
+      exit 0 ;;
+    image/png)
+      # Reuse the image fetched by the TARGETS check a moment ago.
+      modified=$(stat -c %Y -- "$cache" 2>/dev/null || stat -f %m -- "$cache" 2>/dev/null || echo 0)
+      age=$(( $(date +%s) - modified ))
+      if [ ! -s "$cache" ] || [ "$age" -gt 30 ]; then fetch "$cache" || exit 1; fi
+      cat -- "$cache"
+      rm -f -- "$cache"
+      exit 0 ;;
+  esac
+fi
+real "$@"
+`;
+
+// Claude Code on Linux pastes images with Ctrl+V only, but Windows terminals
+// keep Ctrl+V for their own paste, so Windows users press Alt+V as they would
+// locally. This binding is honoured even with --restricted.
+export const ALT_V_BINDING = { context: 'Chat', bindings: { 'alt+v': 'chat:imagePaste' } };
+export const KEYBINDING_MISSING = 'CLAUDE_REMOTE_ALT_V_MISSING';
+
+// Creates ~/.claude/keybindings.json with the Alt+V binding when it does not
+// exist. An existing file is never edited; KEYBINDING_MISSING is printed
+// instead when it has no Alt+V entry, so the user can add it.
+export function ensureAltVBinding() {
+  const file = '"$HOME/.claude/keybindings.json"';
+  // Failing to write is not fatal: Ctrl+V still works where the terminal allows it.
+  return 'if [ ! -e ' + file + ' ]; then { mkdir -p -- "$HOME/.claude" && printf \'%s\\n\' ' +
+    quote(JSON.stringify({ bindings: [ALT_V_BINDING] }, null, 2)) + ' > ' + file + '; } 2>/dev/null || true\n' +
+    'elif ! grep -qi \'"alt+v"\' ' + file + ' 2>/dev/null; then echo ' + KEYBINDING_MISSING + '\nfi\n';
+}
+
+// Shell lines that install the stand-in into `directory` (an already quoted
+// remote path). The Authorization header is read from the next stdin line.
+export function installClipboardShim(directory, url) {
+  return 'mkdir -m 700 -- ' + directory + '\n' +
+    'IFS= read -r line; printf \'%s\\n\' "$line" > ' + directory + '/header\n' +
+    'printf \'%s\\n\' ' + url + ' > ' + directory + '/url\n' +
+    'cat > ' + directory + "/xclip <<'CLAUDE_REMOTE_XCLIP'\n" + XCLIP_SHIM + 'CLAUDE_REMOTE_XCLIP\n' +
+    'chmod 700 -- ' + directory + '/xclip\n';
+}