# Trans 操作

- 优先使用直接且有界的操作：
  - `cat` / `head` / `tail` / `rg`：读取远端文本；
  - `apply-patch <<'PATCH'`：修改远端文本；
  - `sh` / `bash`：只执行显式 shell 脚本，并保持输出简短；
  - `kubectl`：只做诊断和应急读取，正式 CI/CD 继续使用 UniDesk CLI；
  - `logs`：读取有界日志尾部，不输出完整 dump；
  - `py`：只用于 patch 不适用的一次性支持操作。

- `upload` / `download` 只用于二进制文件或需要整体搬运的生成物：
  - 已知文本扩展名或文件名默认在远端操作和本地目标写入前返回 `text-transfer-discouraged`；
  - 错误的第一条建议是 `cat` 或 `apply-patch <<'PATCH'`；
  - 确需整体搬运文本生成物时显式使用 `--allow-text-transfer`；
  - override 会记录在成功结果的 `transferPolicy`，且不会绕过字节数和 SHA-256 校验。

- Windows workspace 工具链：
  - Windows 安装或 PATH 中的普通命令使用 `trans <provider>:win/<drive>/<path> cmd ...`；
  - PowerShell 逻辑使用 `ps`；
  - `<provider>:/mnt/<drive>/...` 上找不到 `python` 只说明 WSL/host plane 缺少该命令，不能据此判断 Windows plane。

- Windows `download`：
  - drive-letter 路径自动映射到同一 provider 的 WSL `/mnt/<drive>` host route 做二进制流传输；
  - 例如 `trans D518:win download 'D:\tmp\image.png' /tmp/image.png`；
  - 相对路径使用 `win/<drive>/<path>` route workspace；
  - UNC 路径仍需先复制到 drive-letter 路径。

- `trans --help download`：
  - 首屏先展示文本读取短路径，再展示二进制 download；
  - 同时披露当前 `runtime.repoRoot` / `runtime.cliPath`；
  - 验证独立 worktree 时显式设置 `UNIDESK_TRANS_REPO_ROOT=<worktree>`。

- 普通 trans/SSH 必须满足短连接预算；长 build、CI/CD、trace、probe 或 rollout 使用受控 job/status submit-and-poll。

- 临时 build、Docker GPU、模型下载或硬件 smoke：
  - 使用 [远程临时实验 smoke](remote-experiment-smoke.md) 的单次参数化模板；
  - 长步骤只提交后台 job，后续使用有界 status/log tail 轮询；
  - 结束时输出统一 evidence 摘要，并复查资源前缀或 label 无残留。
