fix: guide remote text operations away from file transfer

scripts/src/ssh-file-transfer.ts

@@ -99,6 +99,15 @@ const fileTransferWriteRawChunkBytes = 131_072;
 const fileTransferWriteB64ChunkChars = 1_398_104;
 const fileTransferProgressEveryChunks = 16;
 
+const fileTransferUsageHint = {
+  code: "prefer-remote-text-operations",
+  message: "避免对远端文本反复 upload/download；读取优先使用 cat/rg，修改优先使用 apply-patch。upload/download 仅用于必要的二进制文件或生成物传输。",
+  preferredOperations: {
+    read: ["cat", "rg"],
+    edit: ["apply-patch"],
+  },
+};
+
 export function isSshFileTransferOperation(args: string[]): boolean {
   const subcommand = args[0] ?? "";
   return subcommand === "upload" || subcommand === "download";
@@ -132,6 +141,7 @@ export async function runSshFileTransferOperation(
       bytes: expected.bytes,
       sha256: expected.sha256,
       verified: true,
+      hint: fileTransferUsageHint,
       verification,
       transfer: write,
     }, null, 2)}\n`);
@@ -149,6 +159,7 @@ export async function runSshFileTransferOperation(
     bytes: download.bytes,
     sha256: download.sha256,
     verified: true,
+    hint: fileTransferUsageHint,
     verification: download.verification,
     transfer: download.transfer,
   }, null, 2)}\n`);