Files
Netcatty/components/terminal/hooks/useTerminalContextActions.ts
T
Yohannandyangheng 83e0e98795 feat(terminal): auto-upload clipboard images on paste (remote sessions, opt-in setting) (#2676)
* feat(terminal): 粘贴时自动上传剪贴板图片(远程会话,设置项控制)

- 新增设置项 autoUploadClipboardImageOnPaste(默认关闭):剪贴板含图片时,远程 SSH 会话中粘贴自动通过 SFTP 上传图片到远端 .netcatty-paste-images/ 并输入远端路径,无图则回退普通文本粘贴
- terminalClipboardPaste.ts:图片检查优先于本地文件/文本粘贴;上传失败上报错误提示,不上传时静默回退
- 统一四路粘贴入口:右键/中键(onPaste)、DOM paste 事件(useTerminalFilePaste)、绑定快捷键(createXTermRuntime case "paste")
- TerminalBehaviorSettings.tsx 新增设置开关,i18n 补齐 en/ru/zh-CN/zh-TW
- syncPayload.ts 设置同步白名单加入新字段
- 测试:terminalClipboardPaste.test.ts 新增 4 个用例(上传/回退/失败上报/本地不受影响)

Author: yangheng
Model: 42865985-ead4-417f-88a9-12012a3495fe/deepseek-v4-flash

* fix(terminal): 剪贴板图片上传异常时上报错误而非静默回退

- clipboardImagePaste.ts:readClipboardImage 抛错视为 no-image(读图失败与空剪贴板无法区分,可安全回退普通粘贴)
- terminalClipboardPaste.ts:确认剪贴板有图后上传流程抛异常(如 SFTP 无法打开)→ 上报 upload-failed 错误并停止,与右键菜单路径一致,不再静默粘贴无关剪贴板内容
- 测试:新增「上传抛异常 → 上报 upload-failed 且不粘贴」「读图失败 → no-image」2 个用例,18/18 通过

Author: yangheng
Model: 42865985-ead4-417f-88a9-12012a3495fe/deepseek-v4-flash

---------

Co-authored-by: yangheng <492238647@qq.com>
2026-08-05 10:29:37 +08:00

231 lines
7.5 KiB
TypeScript

import type { Terminal as XTerm } from "@xterm/xterm";
import { useCallback } from "react";
import type { RefObject } from "react";
import { netcattyBridge } from "../../../infrastructure/services/netcattyBridge";
import { logger } from "../../../lib/logger";
import { pasteTextIntoTerminal } from "../runtime/terminalUserPaste";
import { clearTerminalViewportAndSyncPty } from "../clearTerminalViewport";
import {
handleRemoteClipboardImageUpload,
type RemoteClipboardImageUploadResult,
} from "../clipboardImagePaste";
import { handleTerminalClipboardPaste } from "../terminalClipboardPaste";
import { getTerminalSelectionForClipboard } from "../normalizeTerminalSelection";
type BroadcastPasteRefs = {
sourceSessionId: string;
sessionRef: RefObject<string | null>;
isBroadcastEnabledRef?: RefObject<boolean | undefined>;
onBroadcastInputRef?: RefObject<((data: string, sourceSessionId: string) => void) | undefined>;
passwordPromptActiveRef?: RefObject<boolean | undefined>;
};
export const broadcastTerminalPasteData = (
data: string,
{
sourceSessionId,
sessionRef,
isBroadcastEnabledRef,
onBroadcastInputRef,
passwordPromptActiveRef,
}: BroadcastPasteRefs,
): boolean => {
if (
passwordPromptActiveRef?.current !== true
&& sessionRef.current
&& isBroadcastEnabledRef?.current
&& onBroadcastInputRef?.current
) {
onBroadcastInputRef.current(data, sourceSessionId);
return true;
}
return false;
};
export const useTerminalContextActions = ({
termRef,
sourceSessionId,
sessionRef,
onHasSelectionChange,
scrollOnPasteRef,
isBroadcastEnabledRef,
onBroadcastInputRef,
passwordPromptActiveRef,
isLocalConnection,
supportsRemoteImagePaste,
autoUploadClipboardImageOnPasteRef,
clearWipesScrollbackRef,
normalizeTextOnCopyRef,
terminalBackend,
getRemoteCwd,
scrollToBottomAfterProgrammaticInput,
onClipboardImageUploadResult,
}: {
termRef: RefObject<XTerm | null>;
sourceSessionId: string;
sessionRef: RefObject<string | null>;
onHasSelectionChange?: (hasSelection: boolean) => void;
scrollOnPasteRef?: RefObject<boolean>;
isBroadcastEnabledRef?: RefObject<boolean | undefined>;
onBroadcastInputRef?: RefObject<((data: string, sourceSessionId: string) => void) | undefined>;
passwordPromptActiveRef?: RefObject<boolean | undefined>;
isLocalConnection: boolean;
supportsRemoteImagePaste: boolean;
/** When true, paste auto-uploads a clipboard image (remote sessions only). */
autoUploadClipboardImageOnPasteRef?: RefObject<boolean | undefined>;
clearWipesScrollbackRef?: RefObject<boolean | undefined>;
/** When false, copy uses raw getSelection(). Default true when unset. */
normalizeTextOnCopyRef?: RefObject<boolean | undefined>;
terminalBackend: {
writeToSession: (sessionId: string, data: string, options?: { automated?: boolean }) => void;
clearSessionPtyBuffer?: (sessionId: string) => void;
};
getRemoteCwd?: () => Promise<string | null | undefined>;
scrollToBottomAfterProgrammaticInput?: (data: string) => void;
onClipboardImageUploadResult?: (result: RemoteClipboardImageUploadResult) => void;
}) => {
const broadcastUserPasteData = useCallback((data: string) => {
return broadcastTerminalPasteData(data, {
sourceSessionId,
sessionRef,
isBroadcastEnabledRef,
onBroadcastInputRef,
passwordPromptActiveRef,
});
}, [isBroadcastEnabledRef, onBroadcastInputRef, passwordPromptActiveRef, sessionRef, sourceSessionId]);
const onCopy = useCallback(() => {
const term = termRef.current;
if (!term) return;
const selection = getTerminalSelectionForClipboard(
term,
normalizeTextOnCopyRef?.current ?? true,
);
if (selection) {
navigator.clipboard.writeText(selection);
}
}, [normalizeTextOnCopyRef, termRef]);
const onPaste = useCallback(async () => {
const term = termRef.current;
if (!term) return;
try {
const bridge = netcattyBridge.get();
await handleTerminalClipboardPaste({
bridge,
autoUploadClipboardImage:
supportsRemoteImagePaste && autoUploadClipboardImageOnPasteRef?.current === true,
clipboardImageBridge: bridge ?? undefined,
getRemoteCwd,
isLocalConnection,
isSensitiveInput: () => passwordPromptActiveRef?.current === true,
onClipboardImageUploadResult,
readClipboardText: () => navigator.clipboard.readText(),
scrollOnPaste: scrollOnPasteRef?.current ?? false,
onPasteData: broadcastUserPasteData,
sessionId: sessionRef.current,
scrollToBottomAfterProgrammaticInput,
terminalBackend,
term,
});
} catch (err) {
logger.warn("Failed to paste from clipboard", err);
}
}, [
autoUploadClipboardImageOnPasteRef,
broadcastUserPasteData,
getRemoteCwd,
isLocalConnection,
onClipboardImageUploadResult,
passwordPromptActiveRef,
sessionRef,
supportsRemoteImagePaste,
termRef,
scrollOnPasteRef,
scrollToBottomAfterProgrammaticInput,
terminalBackend,
]);
const onUploadClipboardImage = useCallback(async () => {
const term = termRef.current;
if (!term) return;
try {
const bridge = netcattyBridge.get();
const result = await handleRemoteClipboardImageUpload({
bridge,
getRemoteCwd: getRemoteCwd ?? (async () => undefined),
isSensitiveInput: () => passwordPromptActiveRef?.current === true,
sessionId: supportsRemoteImagePaste ? sessionRef.current : null,
terminalBackend,
term,
scrollToBottomAfterProgrammaticInput,
});
onClipboardImageUploadResult?.(result);
} catch (err) {
logger.warn("Failed to upload clipboard image", err);
onClipboardImageUploadResult?.({ ok: false, reason: "upload-failed" });
}
}, [
getRemoteCwd,
passwordPromptActiveRef,
onClipboardImageUploadResult,
scrollToBottomAfterProgrammaticInput,
sessionRef,
supportsRemoteImagePaste,
termRef,
terminalBackend,
]);
const onPasteSelection = useCallback(() => {
const term = termRef.current;
if (!term) return;
const selection = getTerminalSelectionForClipboard(
term,
normalizeTextOnCopyRef?.current ?? true,
);
if (!selection || !sessionRef.current) return;
pasteTextIntoTerminal(term, selection, {
scrollOnPaste: scrollOnPasteRef?.current ?? false,
onPasteData: broadcastUserPasteData,
});
}, [broadcastUserPasteData, normalizeTextOnCopyRef, sessionRef, termRef, scrollOnPasteRef]);
const onSelectAll = useCallback(() => {
const term = termRef.current;
if (!term) return;
term.selectAll();
onHasSelectionChange?.(true);
}, [onHasSelectionChange, termRef]);
const onClear = useCallback(() => {
const term = termRef.current;
if (!term) return;
clearTerminalViewportAndSyncPty(term, {
wipeScrollback: clearWipesScrollbackRef?.current ?? true,
syncPty: () => {
const id = sessionRef.current;
if (id) {
terminalBackend.clearSessionPtyBuffer?.(id);
}
},
});
}, [clearWipesScrollbackRef, sessionRef, termRef, terminalBackend]);
const onSelectWord = useCallback(() => {
const term = termRef.current;
if (!term) return;
term.selectAll();
onHasSelectionChange?.(true);
}, [onHasSelectionChange, termRef]);
return {
onCopy,
onPaste,
onUploadClipboardImage: supportsRemoteImagePaste ? onUploadClipboardImage : undefined,
onPasteSelection,
onSelectAll,
onClear,
onSelectWord,
};
};