fix: 收敛受控 CLI 调用与诊断

scripts/src/help.ts

@@ -190,8 +190,12 @@ const SSH_OPERATION_HELP: Record<SshHelpScope, SshOperationHelp> = {
   },
   exec: {
     group: "process",
-    description: "在 k3s workload route 中运行进程，并可显式透传 stdin 或指定容器内 cwd。",
-    usage: ["trans <provider>:k3s:<namespace>:<workload>[:<container>] exec [--cwd /path] [--stdin] -- <command> [args...]"],
+    description: "运行单个远端进程；host/workspace 的 cwd 写入 route，k3s workload 用 --cwd 指定容器内目录。",
+    usage: [
+      "trans <provider>:/absolute/workspace exec <command> [args...]",
+      "trans <provider>:k3s:<namespace>:<workload>[:<container>] exec [--cwd /path] [--stdin] -- <command> [args...]",
+    ],
+    notes: ["host/workspace 不接受 exec --cwd；改写 route，例如 trans D601:/workspace exec git status。"],
   },
   git: {
     group: "process",
@@ -221,8 +225,9 @@ const SSH_OPERATION_HELP: Record<SshHelpScope, SshOperationHelp> = {
   },
   bash: {
     group: "shell",
-    description: "仅在需要 pipefail、数组、[[ ]] 等 Bash 语法时执行远端 Bash。",
-    usage: ["trans <route> bash <<'BASH'", "trans <route> bash -- '<bash command>'"],
+    description: "仅在需要 pipefail、数组、[[ ]] 等 Bash 语法时执行远端 Bash；cwd 由 route 选择。",
+    usage: ["trans <provider>:/absolute/workspace bash <<'BASH'", "trans <provider>:k3s:<namespace>:<workload>[/cwd] bash <<'BASH'", "trans <route> bash -- '<bash command>'"],
+    notes: ["host/workspace 不接受 bash --cwd；将绝对目录写入 route。"],
   },
   py: {
     group: "shell",
@@ -327,6 +332,11 @@ export function sshHelp(scope: SshHelpScope | undefined = undefined): unknown {
       "远端文本读取优先 cat/rg，修改优先 apply-patch；upload/download 仅用于必要的二进制或生成物。",
       "普通 trans 短连接上限保持 60s；长流程使用受控 submit-and-poll 入口。",
     ],
+    cwdSemantics: {
+      hostWorkspace: `${entrypoint} <provider>:/absolute/workspace exec|sh|bash ...`,
+      k3sWorkload: `${entrypoint} <provider>:k3s:<namespace>:<workload>[:<container>] exec --cwd /absolute/container/path -- <command>`,
+      rule: "host/workspace cwd 属于 route；k3s 容器 cwd 可由 route 后缀或 exec --cwd 指定。",
+    },
   };
 }
 
@@ -343,6 +353,7 @@ export function renderSshHelpText(scope: SshHelpScope | undefined = undefined):
       `patch: ${SSH_OPERATION_GROUPS.patch.join(" | ")}`,
       `transfer: ${SSH_OPERATION_GROUPS.transfer.join(" | ")}`,
       `scoped help: ${entrypoint} --help <operation>`,
+      `cwd: host/workspace uses <provider>:/absolute/workspace; k3s exec uses --cwd /absolute/container/path`,
       "boundary: route only selects the target; use sh/bash/ps/cmd explicitly for shell syntax.",
     ].join("\n");
   }