fix: improve trans script migration hint

docs/reference/cli.md

@@ -251,7 +251,7 @@ exec /root/unidesk/scripts/trans "$@"
 
 主 server 上的人工/Codex 分布式敏捷操作必须直接写 `trans ...`，不要在 Codex 工具调用里退回完整 `bun scripts/cli.ts ssh ...` 前缀。例如 `trans D601:/home/ubuntu/workspace/hwlab-dev git status --short --branch`、`trans D601:k3s kubectl get pods -n hwlab-dev` 或 `trans D601:k3s:hwlab-dev:hwlab-cloud-web exec --cwd /tmp -- pwd`。`tran` 是历史兼容 wrapper 和 runner 固化入口；新写长期参考、AGENTS 索引和 CLI help 时优先写 `trans ...`。
 
-`trans` 同样遵守 route/operation 解析器；route 后面的第一个 token 不是原生 ssh 命令字符串。带变量展开、管道、重定向或多条命令的远端逻辑，默认使用 `trans G14:/root/hwlab sh <<'SH'`；`sh` 走目标节点 `/bin/sh`，并继承 provider-gateway/G14 已长期化的 proxy 环境。需要 Bash 专有语法，例如 `set -o pipefail`、数组、`[[ ... ]]` 或 `${var:0:8}` 子串展开时，必须把 operation 写成 `bash`，例如 `trans D601:/home/ubuntu/workspace/hwlab-v03 bash <<'BASH'`。需要临时单步执行一行远端 shell 逻辑、且不想先创建脚本文件或 heredoc 时，使用 `trans G14:/root/hwlab sh -- 'sed -n "1,20p" a && sed -n "1,20p" b'` 或 `bash -- '<bash command>'`，CLI 会把单个字符串放进目标节点对应 shell 的 `-c`，第二个 `sed`、管道和重定向都会留在远端；`sh --` 与 `bash --` 只接受一个 shell command 字符串，多 argv 单进程命令必须走 `argv`、`exec` 或已知直接子命令。`script` 和 `shell` operation 已移除并会失败；不得用 `--shell bash` 或旧名绕过显式 shell 选择。`sh` 和 `bash` helper 会在用户 shell 文本前注入一个极小的 POSIX 兼容 `printf` wrapper，使 `printf "--- section ---\n"` 这类高频排障分隔标题在 dash/sh 与 bash 下行为一致；direct argv 形态不注入该 wrapper。单进程命令才直接写成 argv，例如 `trans G14:/root/hwlab git status --short --branch`。遇到分布式开发摩擦时，优先补强 `trans`/`tran` 的 route/operation、stdin helper 或目标节点环境，并把稳定解法写回长期参考文档，不要退回多层 shell 字符串拼接。
+`trans` 同样遵守 route/operation 解析器；route 后面的第一个 token 不是原生 ssh 命令字符串。带变量展开、管道、重定向或多条命令的远端逻辑，默认使用 `trans G14:/root/hwlab sh <<'SH'`；`sh` 走目标节点 `/bin/sh`，并继承 provider-gateway/G14 已长期化的 proxy 环境。需要 Bash 专有语法，例如 `set -o pipefail`、数组、`[[ ... ]]` 或 `${var:0:8}` 子串展开时，必须把 operation 写成 `bash`，例如 `trans D601:/home/ubuntu/workspace/hwlab-v03 bash <<'BASH'`。需要临时单步执行一行远端 shell 逻辑、且不想先创建脚本文件或 heredoc 时，使用 `trans G14:/root/hwlab sh -- 'sed -n "1,20p" a && sed -n "1,20p" b'` 或 `bash -- '<bash command>'`，CLI 会把单个字符串放进目标节点对应 shell 的 `-c`，第二个 `sed`、管道和重定向都会留在远端；`sh --` 与 `bash --` 只接受一个 shell command 字符串，多 argv 单进程命令必须走 `argv`、`exec` 或已知直接子命令。`script` 和 `shell` operation 已移除并会失败；失败 JSON 必须保留用户入口名（`trans`/`tran`/`ssh`）、route、operation 和 `replacementExamples`，其中包含 `trans <route> sh -- '<command>'` 与 `trans <route> bash -- '<command>'` 形态；不得用 `--shell bash` 或旧名绕过显式 shell 选择。`sh` 和 `bash` helper 会在用户 shell 文本前注入一个极小的 POSIX 兼容 `printf` wrapper，使 `printf "--- section ---\n"` 这类高频排障分隔标题在 dash/sh 与 bash 下行为一致；direct argv 形态不注入该 wrapper。单进程命令才直接写成 argv，例如 `trans G14:/root/hwlab git status --short --branch`。遇到分布式开发摩擦时，优先补强 `trans`/`tran` 的 route/operation、stdin helper 或目标节点环境，并把稳定解法写回长期参考文档，不要退回多层 shell 字符串拼接。
 
 本地检索或引用 Markdown 命令片段时也要避免外层 shell 误解析。任何包含反引号的 pattern，例如文档里的 `` `trans ...` ``，都必须用单引号、`rg -F -e` 或 stdin/file 传入；禁止写进双引号参数，因为 shell 会先执行 backtick command substitution，可能在搜索旧文档时反而误触 `trans ... script` 这类已移除 operation。
 
@@ -260,7 +260,7 @@ exec /root/unidesk/scripts/trans "$@"
 
 - 长期参考、AGENTS 索引、CLI help、Codex 任务脚本、CI/CD 排障和人工远端操作必须统一把已知的远端 workspace 写在 route 的第一个 token，而不是塞进 `cd` 串。`route` 段只表达分布式定位，operation 段才执行命令；workspace 路径是定位信息，不是命令。
 - 标准形态是 `trans <provider>:/absolute/workspace <operation> [args...]`：例如 `trans G14:/root/hwlab git status --short --branch`、`trans G14:/root/hwlab-v02 sh -- 'git fetch origin v0.2 && git pull --ff-only origin v0.2'`、`trans D601:/home/ubuntu/workspace/unidesk-dev sh <<'SH'`、`trans D601:/home/ubuntu/workspace/hwlab-v03 bash <<'BASH'`、`trans G14:/root/hwlab apply-patch < patch.diff` 和 `trans G14:/root/hwlab glob --root . --pattern 'web/hwlab-cloud-web/*.ts' --contains session-tabs`。
-- 反面形态必须删除或迁移：`trans G14 sh -- 'cd /root/hwlab && git status --short --branch'`、`trans G14 sh <<'SH' cd /root/hwlab-v02 git fetch origin v0.2 SH`、`tran G14 sh -- 'cd /home/ubuntu/workspace/unidesk-dev && ...'`、`trans G14 script -- '...'`、`trans G14 shell '...'`、`bun scripts/cli.ts ssh G14 -- 'cd /root/hwlab && ...'`。这些写法把已知 workspace 写进 command 字符串，破坏 route/operation 分离，引入本地 shell 二次解析、远端 cwd 漂移和并行 worktree 切换摩擦，或继续使用已移除的模糊 shell 旧名。
+- 反面形态必须删除或迁移：`trans G14 sh -- 'cd /root/hwlab && git status --short --branch'`、`trans G14 sh <<'SH' cd /root/hwlab-v02 git fetch origin v0.2 SH`、`tran G14 sh -- 'cd /home/ubuntu/workspace/unidesk-dev && ...'`、route 后继续写旧的 `script` / `shell` operation、`bun scripts/cli.ts ssh G14 -- 'cd /root/hwlab && ...'`。这些写法把已知 workspace 写进 command 字符串，破坏 route/operation 分离，引入本地 shell 二次解析、远端 cwd 漂移和并行 worktree 切换摩擦，或继续使用已移除的模糊 shell 旧名。
 - 例外只限于一次性探测、临时 heredoc 草稿或旧文档复用；任何被复用第二次的 `cd <workspace> && ...` 都必须重写成 `trans <provider>:/absolute/workspace` 形式。
 - 当远端存在多个并行 workspace（例如 `G14:/root/hwlab` 与 `G14:/root/hwlab-v02`）时，route 必须显式带 workspace，CLI 的 `pwd` 输出、后续 `apply-patch` 的相对路径和 `sh`/`bash` 的 cwd 全部跟随该 workspace；切换 workspace 必须切换 route，不允许在同一次 `trans` 链里再 `cd`。
 - 本规则覆盖所有 host workspace 形态，包括 `G14:/root/hwlab`、`G14:/root/hwlab-v02`、`G14:/root/agentrun-v01`、`D601:/home/ubuntu/workspace/unidesk-dev`、`D601:/home/ubuntu/workspace/hwlab-dev`；provider-gateway 侧已经把它们注册为 host workspace route。

scripts/src/output.ts

@@ -66,6 +66,8 @@ function normalizeErrorPayload(command: string, error: unknown): Record<string,
     return { message };
   }
   if (error instanceof Error) {
+    const structured = structuredCliErrorPayload(error, message);
+    if (structured !== null) return structured;
     const debug = process.env.UNIDESK_CLI_DEBUG === "1" || process.env.UNIDESK_CLI_FULL_ERROR === "1" || process.env.UNIDESK_CLI_RAW_ERROR === "1";
     return {
       name: error.name,
@@ -78,6 +80,20 @@ function normalizeErrorPayload(command: string, error: unknown): Record<string,
   return { message };
 }
 
+function structuredCliErrorPayload(error: Error, message: string): Record<string, unknown> | null {
+  const record = error as Error & Record<string, unknown>;
+  if (!Object.prototype.hasOwnProperty.call(record, "replacementExamples") && !Object.prototype.hasOwnProperty.call(record, "migrationHint")) return null;
+  const payload: Record<string, unknown> = {
+    name: error.name,
+    message,
+  };
+  for (const key of ["code", "level", "entrypoint", "route", "operation", "replacementExamples", "migrationHint", "note"]) {
+    const value = record[key];
+    if (value !== undefined) payload[key] = value;
+  }
+  return payload;
+}
+
 function sshFileTransferErrorDetails(error: Error): Record<string, unknown> | null {
   if (error.name !== "SshFileTransferError") return null;
   const details = (error as Error & { details?: unknown }).details;

scripts/src/ssh.test.ts

@@ -74,3 +74,38 @@ describe("ssh stdout bounded streaming", () => {
     expect(hint).toContain("\"transport\":\"frontend-websocket\"");
   });
 });
+
+describe("ssh removed shell aliases", () => {
+  test("reports route-aware replacement examples for trans script", () => {
+    const previousEntrypoint = process.env.UNIDESK_SSH_ENTRYPOINT;
+    process.env.UNIDESK_SSH_ENTRYPOINT = "trans";
+    try {
+      parseSshInvocation("D601:/tmp", ["script", "--", "pwd"]);
+      throw new Error("expected script alias to fail");
+    } catch (error) {
+      expect(error).toBeInstanceOf(Error);
+      const payload = error as Error & {
+        code?: string;
+        entrypoint?: string;
+        route?: string;
+        operation?: string;
+        replacementExamples?: {
+          posixSh?: string;
+          bash?: string;
+        };
+      };
+      expect(payload.code).toBe("ssh-removed-shell-alias");
+      expect(payload.entrypoint).toBe("trans");
+      expect(payload.route).toBe("D601:/tmp");
+      expect(payload.operation).toBe("script");
+      expect(payload.replacementExamples?.posixSh).toBe("trans D601:/tmp sh -- 'pwd'");
+      expect(payload.replacementExamples?.bash).toBe("trans D601:/tmp bash -- 'pwd'");
+    } finally {
+      if (previousEntrypoint === undefined) {
+        delete process.env.UNIDESK_SSH_ENTRYPOINT;
+      } else {
+        process.env.UNIDESK_SSH_ENTRYPOINT = previousEntrypoint;
+      }
+    }
+  });
+});

scripts/src/ssh.ts

@@ -118,6 +118,36 @@ export interface SshRuntimeTimeoutHint {
   note: string;
 }
 
+export interface RemovedShellAliasReplacementExamples {
+  posixSh: string;
+  bash: string;
+  templatePosixSh: string;
+  templateBash: string;
+}
+
+export class SshRemovedShellAliasError extends Error {
+  code = "ssh-removed-shell-alias";
+  level = "error";
+  entrypoint: string;
+  route: string;
+  operation: string;
+  replacementExamples: RemovedShellAliasReplacementExamples;
+  migrationHint: string;
+  note = "`sh` runs POSIX /bin/sh; `bash` is only for Bash-specific syntax. The removed alias intentionally no longer chooses a hidden shell dialect.";
+
+  constructor(operation: string, route: string, operationArgs: string[]) {
+    const entrypoint = sshDisplayEntrypoint();
+    const replacementExamples = removedShellAliasReplacementExamples(entrypoint, route, operationArgs);
+    super(`${entrypoint} ${route} ${operation} operation has been removed because it hides the shell dialect; use explicit sh for POSIX /bin/sh or bash for Bash syntax`);
+    this.name = "SshRemovedShellAliasError";
+    this.entrypoint = entrypoint;
+    this.route = route;
+    this.operation = operation;
+    this.replacementExamples = replacementExamples;
+    this.migrationHint = `Rewrite as ${replacementExamples.posixSh} for POSIX shell, or ${replacementExamples.bash} for Bash syntax.`;
+  }
+}
+
 export interface SshStdoutTruncationHint {
   code: "ssh-stdout-truncated";
   level: "warning";
@@ -920,7 +950,7 @@ export function isSshSkillDiscoveryArgs(args: string[]): boolean {
   return subcommand === "skills" || subcommand === "skill-discover" || subcommand === "discover-skills" || (subcommand === "skill" && args[1] === "discover");
 }
 
-export function parseSshArgs(args: string[]): ParsedSshArgs {
+export function parseSshArgs(args: string[], routeRaw = "<route>"): ParsedSshArgs {
   const subcommand = args[0] ?? "";
   if (isSshFileTransferOperation(args)) {
     return { remoteCommand: null, requiresStdin: false, invocationKind: "helper" };
@@ -949,7 +979,7 @@ export function parseSshArgs(args: string[]): ParsedSshArgs {
     return { remoteCommand: null, requiresStdin: true, invocationKind: "helper" };
   }
   if (subcommand === "script" || subcommand === "shell") {
-    throw removedShellAliasError(subcommand);
+    throw removedShellAliasError(subcommand, routeRaw, args.slice(1));
   }
   if (subcommand === "sh" || subcommand === "bash") {
     return buildShellCommand(args.slice(1), subcommand, `ssh ${subcommand}`);
@@ -1035,7 +1065,7 @@ export function parseSshInvocation(target: string, args: string[]): ParsedSshInv
   if ((operationArgs[0] ?? "") === "k3s") {
     throw new Error(`ssh k3s shorthand is unsupported; use route syntax instead: trans ${route.providerId}:k3s ${operationArgs.slice(1).join(" ")}`.trim());
   }
-  return { providerId: route.providerId, route, parsed: parseSshArgs(operationArgs) };
+  return { providerId: route.providerId, route, parsed: parseSshArgs(operationArgs, route.raw) };
 }
 
 export function parseSshRoute(target: string): ParsedSshRoute {
@@ -1669,7 +1699,7 @@ function parseK3sControlPlaneOperation(route: ParsedSshRoute, args: string[]): P
     throw new Error("remote patch entrypoints are `apply-patch` for the default v2 engine and `apply-patch-v1` for the legacy helper");
   }
   if (operation === "script" || operation === "shell") {
-    throw removedShellAliasError(operation);
+    throw removedShellAliasError(operation, route.raw, args.slice(1));
   }
   if (operation === "sh" || operation === "bash") {
     return buildK3sScriptOperation(args.slice(1), operation, `ssh ${route.providerId}:k3s ${operation}`);
@@ -1678,7 +1708,7 @@ function parseK3sControlPlaneOperation(route: ParsedSshRoute, args: string[]): P
     if (args.length > 1) throw new Error(`ssh ${route.providerId}:k3s guard does not accept extra arguments`);
     return { remoteCommand: buildK3sGuardCommand(route.providerId), requiresStdin: false, invocationKind: "helper" };
   }
-  return { remoteCommand: buildK3sCommand(route.providerId, args), requiresStdin: false, invocationKind: "helper" };
+  return { remoteCommand: buildK3sCommand(route.providerId, route.raw, args), requiresStdin: false, invocationKind: "helper" };
 }
 
 function parseK3sTargetOperation(route: ParsedSshRoute, args: string[]): ParsedSshArgs {
@@ -1706,7 +1736,7 @@ function parseK3sTargetOperation(route: ParsedSshRoute, args: string[]): ParsedS
     throw new Error("remote patch entrypoints are `apply-patch` for the default v2 engine and `apply-patch-v1` for the legacy helper");
   }
   if (operation === "script" || operation === "shell") {
-    throw removedShellAliasError(operation);
+    throw removedShellAliasError(operation, route.raw, operationArgs);
   }
   if (operation === "sh" || operation === "bash") {
     return buildK3sScriptOperation([...targetArgs, ...operationArgs], operation, `ssh ${route.raw} ${operation}`);
@@ -1831,7 +1861,7 @@ function effectiveApplyPatchV2Invocation(invocation: ParsedSshInvocation, argv:
   };
 }
 
-function buildK3sCommand(providerId: string, args: string[]): string {
+function buildK3sCommand(providerId: string, routeRaw: string, args: string[]): string {
   const action = args[0] ?? "";
   if (action.length === 0 || action === "--help" || action === "-h" || action === "help") {
     throw new Error("ssh k3s requires a subcommand: guard, kubectl, get, describe, logs or exec");
@@ -1839,7 +1869,7 @@ function buildK3sCommand(providerId: string, args: string[]): string {
   if (action === "guard") return buildK3sGuardCommand(providerId);
   if (action === "exec") return buildK3sExecCommand(args.slice(1));
   if (action === "script" || action === "shell") {
-    throw removedShellAliasError(action);
+    throw removedShellAliasError(action, routeRaw, args.slice(1));
   }
   if (action === "sh" || action === "bash") {
     const parsed = buildK3sScriptOperation(args.slice(1), action, `ssh k3s ${action}`);
@@ -1920,8 +1950,34 @@ function buildK3sExecCommand(args: string[]): string {
   return shellArgv(["env", `KUBECONFIG=${nativeK3sKubeconfig}`, "kubectl", ...kubectlArgs]);
 }
 
-function removedShellAliasError(operation: string): Error {
-  return new Error(`ssh ${operation} operation has been removed because it hides the shell dialect; use explicit \`sh\` for POSIX /bin/sh or \`bash\` for Bash syntax`);
+function removedShellAliasError(operation: string, routeRaw: string, operationArgs: string[]): Error {
+  return new SshRemovedShellAliasError(operation, routeRaw, operationArgs);
+}
+
+function sshDisplayEntrypoint(): string {
+  const raw = process.env.UNIDESK_SSH_ENTRYPOINT?.trim();
+  return raw === "trans" || raw === "tran" || raw === "ssh" ? raw : "ssh";
+}
+
+function removedShellAliasReplacementExamples(entrypoint: string, route: string, operationArgs: string[]): RemovedShellAliasReplacementExamples {
+  const command = removedShellAliasInlineCommand(operationArgs);
+  const commandText = command === null ? "<command>" : command;
+  return {
+    posixSh: `${entrypoint} ${route} sh -- ${shellQuote(commandText)}`,
+    bash: `${entrypoint} ${route} bash -- ${shellQuote(commandText)}`,
+    templatePosixSh: `${entrypoint} ${route} sh -- '<command>'`,
+    templateBash: `${entrypoint} ${route} bash -- '<command>'`,
+  };
+}
+
+function removedShellAliasInlineCommand(operationArgs: string[]): string | null {
+  if (operationArgs.length === 0) return null;
+  const separatorIndex = operationArgs.indexOf("--");
+  if (separatorIndex >= 0) {
+    const command = operationArgs.slice(separatorIndex + 1);
+    return command.length === 1 ? command[0] ?? null : null;
+  }
+  return operationArgs.length === 1 && !(operationArgs[0] ?? "").startsWith("-") ? operationArgs[0] ?? null : null;
 }
 
 function buildK3sScriptOperation(args: string[], shell: "sh" | "bash", commandName: string): ParsedSshArgs {

scripts/ssh-cli.ts

@@ -7,13 +7,20 @@ import { runSsh } from "./src/ssh";
 
 const remoteOptions = extractRemoteCliOptions(process.argv.slice(2));
 const args = normalizeSshCommandArgs(remoteOptions.args);
-const commandName = args.join(" ") || "ssh";
+const commandName = displayCommandName(args);
 
 function normalizeSshCommandArgs(rawArgs: string[]): string[] {
   if (rawArgs[0] === "ssh") return rawArgs;
   return ["ssh", ...rawArgs];
 }
 
+function displayCommandName(normalizedArgs: string[]): string {
+  const rawEntrypoint = process.env.UNIDESK_SSH_ENTRYPOINT?.trim();
+  const entrypoint = rawEntrypoint === "trans" || rawEntrypoint === "tran" || rawEntrypoint === "ssh" ? rawEntrypoint : "ssh";
+  const displayArgs = normalizedArgs[0] === "ssh" ? normalizedArgs.slice(1) : normalizedArgs;
+  return [entrypoint, ...displayArgs].join(" ") || entrypoint;
+}
+
 function isGhContentRouteTarget(target: string | undefined): boolean {
   return typeof target === "string" && target.startsWith("gh:");
 }

scripts/tran

@@ -49,8 +49,12 @@ if [ -n "${CODE_QUEUE_SERVICE_ROLE:-}" ] || [ -n "${CODE_QUEUE_INSTANCE_ID:-}" ]
 fi
 
 if [ "$runner_env" = 1 ] && [ -n "$host" ] && [ "${UNIDESK_TRAN_LOCAL:-}" != "1" ]; then
+  UNIDESK_SSH_ENTRYPOINT=${UNIDESK_SSH_ENTRYPOINT:-tran}
+  export UNIDESK_SSH_ENTRYPOINT
   bun "$repo/scripts/ssh-cli.ts" --main-server-ip "$host" ssh "$@"
   exit $?
 fi
 
+UNIDESK_SSH_ENTRYPOINT=${UNIDESK_SSH_ENTRYPOINT:-tran}
+export UNIDESK_SSH_ENTRYPOINT
 bun "$repo/scripts/ssh-cli.ts" ssh "$@"

scripts/trans

@@ -7,4 +7,6 @@ if [ ! -f "$repo/scripts/ssh-cli.ts" ]; then
   repo=$(CDPATH= cd -- "$self_dir/.." && pwd)
 fi
 
+UNIDESK_SSH_ENTRYPOINT=${UNIDESK_SSH_ENTRYPOINT:-trans}
+export UNIDESK_SSH_ENTRYPOINT
 exec bun "$repo/scripts/ssh-cli.ts" ssh "$@"