pikasTech-unidesk/.agents/skills/unidesk-trans/SKILL.md

name, description

name	description
unidesk-trans	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

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 见 references/routes.md；sh/bash/argv/py/upload/download/kubectl/logs/skills/tcp-pool 操作见 references/operations.md；apply-patch envelope 和 quoting 陷阱见 references/apply-patch.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 慢路径改用临时脚本写文件。
• 当前 HWLAB node/lane source workspace 的正式预检/同步入口是 bun scripts/cli.ts hwlab nodes control-plane source-workspace sync --node <node> --lane <lane> --confirm 和 source-workspace status；不要把裸 trans <node>:<workspace> git fetch ... 当成当前 HWLAB node/lane workspace 预检/修复入口。
• 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/routes.md。
• 编写远端 patch 前，读 references/apply-patch.md。
• 需要 shell heredoc、Python、upload/download 或超时处理时，读 references/operations.md。