From 7210cc2517e689e3b369b64611709d270306b860 Mon Sep 17 00:00:00 2001
From: Codex <codex@local>
Date: Sat, 11 Jul 2026 05:15:41 +0200
Subject: [PATCH] fix: restore k3s download command rendering

Co-Authored-By: Codex <noreply@openai.com>
---
 .../trans-k3s-download-command-builder.md     | 19 ++++++++++++++++++
 scripts/src/ssh-runtime.ts                    |  1 +
 scripts/src/ssh.test.ts                       | 20 +++++++++++++++++++
 scripts/src/ssh.ts                            |  2 +-
 4 files changed, 41 insertions(+), 1 deletion(-)
 create mode 100644 docs/MDTODO/trans-k3s-download-command-builder.md

diff --git a/docs/MDTODO/trans-k3s-download-command-builder.md b/docs/MDTODO/trans-k3s-download-command-builder.md
new file mode 100644
index 00000000..f98c7676
--- /dev/null
+++ b/docs/MDTODO/trans-k3s-download-command-builder.md
@@ -0,0 +1,19 @@
+# 修复 trans k3s download 命令构造
+
+- 来源：<https://github.com/pikasTech/unidesk/issues/1742>
+- 范围：仅修复 k3s route 的受控 download 命令构造、定向测试与原入口验收。
+- 禁止项：不新增第二套 k3s 命令 authority，不绕过 trans，不弱化下载字节数与 SHA-256 校验。
+
+
+## R1 [in_progress]
+
+闭环修复 [UniDesk #1742](https://github.com/pikasTech/unidesk/issues/1742) 的 trans k3s download 未定义命令构造器，完成任务后将详细报告写入[任务报告](./details/trans-k3s-download-command-builder/R1_Task_Report.md)。
+### R1.1 [completed]
+
+复现并确认 [#1742](https://github.com/pikasTech/unidesk/issues/1742) 的唯一 k3s 命令构造 authority 与回归测试断点，完成任务后将详细报告写入[任务报告](./details/trans-k3s-download-command-builder/R1.1_Task_Report.md)。
+### R1.2 [completed]
+
+最小修复 [#1742](https://github.com/pikasTech/unidesk/issues/1742) 并通过定向测试、语法检查和 diff 检查，完成任务后将详细报告写入[任务报告](./details/trans-k3s-download-command-builder/R1.2_Task_Report.md)。
+### R1.3 [in_progress]
+
+通过 [#1742](https://github.com/pikasTech/unidesk/issues/1742) 原始 trans k3s download 入口验证字节数、SHA-256 和结构化输出，提交 PR 与 preflight，完成任务后将详细报告写入[任务报告](./details/trans-k3s-download-command-builder/R1.3_Task_Report.md)。
\ No newline at end of file
diff --git a/scripts/src/ssh-runtime.ts b/scripts/src/ssh-runtime.ts
index c3b9d5c2..6a762edf 100644
--- a/scripts/src/ssh-runtime.ts
+++ b/scripts/src/ssh-runtime.ts
@@ -24,6 +24,7 @@ import { readTransSshBackendConfig, type TransSshBackendConfig } from "./trans-c
 import { readCliOutputPolicy } from "./output";
 import { readHostK8sPublicHost } from "./host-k8s-config";
 import {
+  buildK3sTargetCommand,
   buildWindowsPowerShellInvocation,
   effectiveApplyPatchV2Invocation,
   normalizeSshOperationArgs,
diff --git a/scripts/src/ssh.test.ts b/scripts/src/ssh.test.ts
index 0f26b875..b28779c8 100644
--- a/scripts/src/ssh.test.ts
+++ b/scripts/src/ssh.test.ts
@@ -11,6 +11,7 @@ import {
   formatSshStdoutTruncationHint,
   formatSshTruncationCompletionSummary,
   parseSshInvocation,
+  remoteCommandForRoute,
   sshTruncationCompletionSummary,
   sshCaptureBackendPlan,
   sshStderrStreamMaxBytes,
@@ -219,6 +220,25 @@ describe("ssh direct argv boundaries and plane diagnostics", () => {
   });
 });
 
+describe("ssh k3s file transfer command builder", () => {
+  test("routes download stream commands through the shared k3s target builder", () => {
+    const invocation = parseSshInvocation(
+      "NC01:k3s:hwlab:deployment:hwlab-cloud-api",
+      ["download", "/tmp/trace.json", "/tmp/trace.json"],
+    );
+    const remoteCommand = remoteCommandForRoute(
+      invocation.route,
+      ["sh", "-c", "cat -- \"$1\"", "unidesk-download", "/tmp/trace.json"],
+    );
+
+    expect(remoteCommand).toContain("'KUBECONFIG=/etc/rancher/k3s/k3s.yaml'");
+    expect(remoteCommand).toContain("'kubectl' 'exec' '-n' 'hwlab'");
+    expect(remoteCommand).toContain("'deployment/hwlab-cloud-api'");
+    expect(remoteCommand).toContain("'cat -- \"$1\"'");
+    expect(remoteCommand).toContain("'/tmp/trace.json'");
+  });
+});
+
 describe("ssh host apply-patch fs backend", () => {
   test("uses POSIX bulk fs operations for host routes", async () => {
     const invocation = parseSshInvocation("D601:/mnt/f/Work/ConStart", ["apply-patch"]);
diff --git a/scripts/src/ssh.ts b/scripts/src/ssh.ts
index 27eaa0b7..114af8df 100644
--- a/scripts/src/ssh.ts
+++ b/scripts/src/ssh.ts
@@ -1367,7 +1367,7 @@ function buildK3sTargetObjectCommand(action: "get" | "describe", route: ParsedSs
   return shellArgv(["env", `KUBECONFIG=${nativeK3sKubeconfig}`, "kubectl", action, "-n", route.namespace, normalizeK3sRouteResource(route.resource), ...args]);
 }
 
-function buildK3sTargetCommand(route: ParsedSshRoute, command: string[], options: { stdin?: boolean } = {}): string {
+export function buildK3sTargetCommand(route: ParsedSshRoute, command: string[], options: { stdin?: boolean } = {}): string {
   return buildK3sExecCommand([...k3sRouteTargetArgs(route), ...(options.stdin === true ? ["--stdin"] : []), "--", ...command]);
 }