---
name: unidesk-trans
description: UniDesk SSH 透传与 apply-patch 语法 — `trans <route> <operation>` 分布式执行入口，包含 route 语法、workspace/k3s/Windows 路由、apply-patch envelope 格式、sh/bash/py/upload/download operation 和 60s 短连接约束。用户提到 trans、tran、ssh 透传、远端执行、apply-patch、apply_patch、远端 patch、k3s route、workspace route 时使用。
---

# UniDesk Trans

分布式 SSH 透传入口。`trans <route> <operation>` 中 route 只定位目标，后续 token 都属于 operation parser。

## 高频 route

```bash
trans D601:/home/ubuntu/workspace/unidesk-dev git status --short --branch
trans D601:k3s kubectl get pods -A
trans D601:k3s:namespace:workload[:container] logs --tail 120
trans D601:win ps <<'PS'
trans D601:win/c/test cat README.md
trans D601:win/c/test rg -i needle .
trans D601:win/c/test git diff --check
trans D601:win/c/test git commit -m 'fix: update docs'
trans gh:/owner/repo/issue/<number> cat
```

Host workspace、k3s、Windows、GitHub issue/PR route，sh/bash/argv/apply-patch/py/upload/download/kubectl/logs/skills/tcp-pool 操作，以及 apply-patch envelope 语法和 quoting 陷阱见 [references/full.md](references/full.md)。

## P0 边界

- 远端文本修改优先 `trans <route> apply-patch`；不要 download/upload/sed 拼临时 diff 代替 patch。
- Host/WSL 与 Windows route 的 `apply-patch` 优先走 fs adapter bulk update path；不要为了规避旧的 `read-b64-block` / `write-b64-argv` 慢路径改用临时脚本写文件。
- `sh`/`bash` 必须显式声明 shell；单进程命令优先 direct argv 或已知 operation。
- 普通 trans/ssh 短连接硬预算 60s；长 CI/CD、trace、logs、build、硬件流程必须 submit-and-poll。
- Windows route 的 `win` 是 route plane，operation 直接写 `ps`、`cmd`、`git` 或只读 fs 操作 `pwd|ls|cat|head|tail|stat|wc|rg`；不要写成 `trans D601:win/... win ps`，也不要把 POSIX shell 当 Windows shell。
- 扩展 Windows helper 时保持 operation-scoped PowerShell payload；不要把多操作大脚本塞进 single `EncodedCommand`。

## 何时读取 reference

- 不确定 route 语法、k3s/workspace/Windows 定位时，读 [references/full.md](references/full.md) 的 Route 语法段。
- 编写远端 patch 前，读 apply-patch 语法、上下文定位和常见失败段。
- 需要 shell heredoc、Python、upload/download 或超时处理时，读 Operation 和 60s 段。
