fix: 收敛 trans 远端文本短路径

scripts/src/help.ts

@@ -31,8 +31,8 @@ export function rootHelp(): unknown {
       { command: "provider attach <providerId> [--master-server URL] [--up] [--force] | provider triage <providerId> [--observed-error text] [--observed-scope scope] [--microservice id ...] [--full|--raw]", description: "Generate the minimal external provider-gateway env/compose bundle or run the low-noise read-only provider health triage contract." },
       { command: "trans <route> [operation args...] (alias of ssh <route> ...)", description: "Open a Host SSH / WSL SSH maintenance session; provider WebSocket carries control and host.ssh.tcp-pool carries stdin/stdout/stderr data." },
       { command: "trans gh:/owner/repo[/pr|/issue][/number[/1]] ls|cat|rg|apply-patch", description: "Treat GitHub PRs/issues as virtual text directories; `issue ls --search/--state` covers filtered reads, `cat|rg` reads first-floor body text, and `apply-patch` updates `body.md` through UniDesk gh plus apply-patch v2." },
-      { command: "trans <route> apply-patch < patch.diff", description: "Default remote text patch entry: apply a standard patch with the local TypeScript v2 engine while the remote route only reads and writes files." },
-      { command: "trans <route> upload <local-file> <remote-file> | trans <route> download <remote-file> <local-file>", description: "Transfer whole files through SSH passthrough with automatic endpoint byte/SHA-256 verification; downloads stream stdout over host.ssh.tcp-pool." },
+      { command: "trans <route> apply-patch <<'PATCH'", description: "Default remote text patch entry: send a quoted stdin heredoc directly to the local TypeScript v2 engine while the remote route only reads and writes files." },
+      { command: "trans <route> upload|download [--allow-text-transfer] ...", description: "Transfer binary files or generated artifacts through SSH passthrough with automatic endpoint byte/SHA-256 verification; known text paths fail before transfer unless explicitly overridden." },
       { command: "trans <providerId> apply-patch-v1 [tool args...] < patch.diff", description: "Fallback to the injected legacy remote apply_patch helper directly over SSH passthrough and stream the patch from local stdin." },
       { command: "trans <providerId> py [script-args...] < script.py", description: "Run remote Python from local stdin through SSH passthrough without nested shell quoting; extra args become script argv." },
       { command: "trans <providerId> sh|bash [arg...] <<'SH|BASH' ...", description: "Run a remote POSIX sh or Bash body from local stdin; the operation name declares the shell dialect, and removed `script`/`shell` operations fail with a migration hint." },
@@ -258,8 +258,8 @@ const SSH_OPERATION_HELP: Record<SshHelpScope, SshOperationHelp> = {
   "apply-patch": {
     group: "patch",
     description: "默认远端文本修改入口；本地 v2 engine 计算变更，route 仅负责读写。",
-    usage: ["trans <route> apply-patch [--cwd /path] < patch.diff"],
-    notes: ["失败后重读当前目标块并缩小 hunk；不得自动回退 apply-patch-v1 或整文件 upload。"],
+    usage: ["trans <route> apply-patch <<'PATCH'"],
+    notes: ["直接在 quoted heredoc 中放置 Begin/End Patch envelope；不要先建临时 patch 文件。", "失败后重读当前目标块并缩小 hunk；不得自动回退 apply-patch-v1 或整文件 upload。"],
   },
   "apply-patch-v1": {
     group: "patch",
@@ -269,13 +269,14 @@ const SSH_OPERATION_HELP: Record<SshHelpScope, SshOperationHelp> = {
   upload: {
     group: "transfer",
     description: "上传必要的二进制文件或生成物并自动核对字节数与 SHA-256。",
-    usage: ["trans <route> upload <local-file> <remote-file>"],
-    notes: ["远端文本读取使用 cat/rg，修改使用 apply-patch。"],
+    usage: ["trans <route> apply-patch <<'PATCH'", "trans <route> upload <local-file> <remote-file>"],
+    notes: ["已知文本路径默认在传输前返回 text-transfer-discouraged；仅整体搬运生成物时显式加 --allow-text-transfer。"],
   },
   download: {
     group: "transfer",
     description: "下载必要的二进制文件或生成物并自动核对字节数与 SHA-256。",
-    usage: ["trans <route> download <remote-file> <local-file>"],
+    usage: ["trans <route> cat <remote-text-file>", "trans <route> download <remote-file> <local-file>"],
+    notes: ["已知文本路径默认在写本地目标前返回 text-transfer-discouraged；仅整体搬运生成物时显式加 --allow-text-transfer。"],
   },
 };
 
@@ -329,7 +330,7 @@ export function sshHelp(scope: SshHelpScope | undefined = undefined): unknown {
     boundaries: [
       "route 只定位目标，route 后的 token 全部交给 operation parser。",
       "单进程优先 argv；shell 逻辑显式使用 sh/bash，Windows 使用 ps/cmd。",
-      "远端文本读取优先 cat/rg，修改优先 apply-patch；upload/download 仅用于必要的二进制或生成物。",
+      "远端文本读取优先 cat/rg，修改优先 apply-patch heredoc；已知文本 upload/download 默认在传输前失败。",
       "普通 trans 短连接上限保持 60s；长流程使用受控 submit-and-poll 入口。",
     ],
     cwdSemantics: {
@@ -391,7 +392,7 @@ function sshDownloadHelp(): unknown {
     command: `${entrypoint} --help download`,
     output: "json",
     scope: "download",
-    description: "下载一个必要的二进制文件或生成物，并自动核对远端/本地字节数与 SHA-256；远端文本改用 cat/rg/apply-patch。",
+    description: "远端文本先用 cat/head/tail/rg；download 只整体搬运必要的二进制文件或生成物，并自动核对远端/本地字节数与 SHA-256。",
     runtime: {
       entrypoint,
       repoRoot,
@@ -405,15 +406,17 @@ function sshDownloadHelp(): unknown {
       },
     },
     usage: [
+      "trans <route> cat <remote-text-file>",
       "trans <route> download <remote-file> <local-file>",
-      "trans <route> download --inactivity-timeout-ms <milliseconds> <remote-file> <local-file>",
+      "trans <route> download --allow-text-transfer <generated-text-artifact> <local-file>",
       "trans --help download",
     ],
     options: {
       "--inactivity-timeout-ms <milliseconds>": "Allow a controlled progress-emitting download to stay open while data continues flowing; ordinary trans operations retain the short runtime budget.",
+      "--allow-text-transfer": "显式确认该文本路径属于需要整体搬运的生成物；默认文本读取仍使用 cat/head/tail/rg。",
     },
     contract: {
-      hint: "避免对远端文本反复 upload/download；读取优先使用 cat/rg，修改优先使用 apply-patch。",
+      hint: "已知文本路径在传输前返回 text-transfer-discouraged；读取优先使用 cat/head/tail/rg，修改优先使用 apply-patch heredoc。",
       pathOrder: ["remote-file", "local-file"],
       transport: "host.ssh.tcp-pool",
       strategy: "tcp-pool-stdout-stream",