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

---
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。

遵循 `Skill(cli-spec)`：无输出、超时伪装成无匹配和 argv 边界丢失均视为 CLI 契约故障。

## 高频 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 D601:win/c/test git exact-commit status
trans D601:win/c/test git exact-commit plan --path src/main.c
trans D601:win/c/test git exact-commit run --path src/main.c --message 'fix: exact change' --confirm
trans D601:win/c/test git exact-commit gc-auto --confirm
trans gh:/owner/repo/issue/<number> cat
```

专项参考：

- Host workspace、k3s、Windows、GitHub issue/PR route 见 [references/routes.md](references/routes.md)。
- sh/bash/argv/py/upload/download/kubectl/logs/skills/tcp-pool 操作见 [references/operations.md](references/operations.md)。
- 跨 60 秒短连接的临时 build、GPU、模型或硬件 smoke 见 [references/remote-experiment-smoke.md](references/remote-experiment-smoke.md)。
- apply-patch envelope 和 quoting 陷阱见 [references/apply-patch.md](references/apply-patch.md)。

## P0 边界

- `trans --help` 是高频直接阅读入口：
  - 顶层默认使用紧凑文本，只展示 route 语法、operation 分组和 `trans --help <operation>` 下钻索引；JSON 必须由显式机器输出参数请求。
  - 顶层与 scoped help 都必须有界且直接返回；出现 `outputTruncated` 或 dump 即视为 CLI 缺陷。
  - 未知 help scope 和可预测参数错误必须紧凑、无 stack；只有显式 debug/raw 错误模式可以披露 stack，内部异常不得冒充输入错误。
  - 修复帮助过长时必须收敛信息结构，禁止提高 stdout 阈值。
  - 默认超限输出不得创建 dump；先返回语义化窄查询。
  - dump 只允许用于显式 `--full`、`--raw`、`UNIDESK_TRAN_STREAM_DUMP=1` 或确实无法预先界定的一次性异常证据。
- 远端文本修改直接使用 `trans <route> apply-patch <<'PATCH'`；不要先建临时 patch 文件，也不要 download/upload/sed 拼临时 diff 代替 patch。
- `upload` / `download` 仅用于必要的二进制文件或生成物：
  - 远端文本读取优先使用 `cat` / `head` / `tail` / `rg`；
  - 已知文本路径默认在传输和本地目标写入前返回 `text-transfer-discouraged`；
  - 确需整体搬运文本生成物时显式加 `--allow-text-transfer`，成功结果记录 override 且继续校验字节数和 SHA-256。
- `apply-patch` 检测到交互 TTY 且没有 stdin 时立即返回 `apply-patch-stdin-required` 和 quoted heredoc 示例，不等待 60 秒超时。
- Host/WSL 与 Windows route 的 `apply-patch` 优先走 fs adapter bulk update path；不要为了规避旧的 `read-b64-block` / `write-b64-argv` 慢路径改用临时脚本写文件。
- `apply-patch v2` 字节与完整性边界：
  - POSIX host/workspace 更新已有文件时必须保留原 mode，包括可执行位；新建文件继续服从目标端 umask，不按扩展名猜测权限。
  - localized replacement 必须保留纯 CRLF 和 `legacy-single-byte` 文件的原始字节风格。
  - legacy 文件只允许可保持的单字节 replacement。
  - original/final integrity mismatch 会重新只读采集当前文件并输出 adapter、stage、expected/current bytes、SHA-256、newline 和 encoding 摘要。
  - 诊断不披露文件正文，也不回退 `apply-patch-v1`。
- 当前 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。
  - `sh`/`bash` 不接受 `-c` 等 shell 选项；错误返回 `ssh-sh-option-unsupported`，并在连接前退出。
  - shell 逻辑使用 `trans <route> sh <<'SH' ... SH`；单进程直接使用 `trans <route> <command> [args...]`。
- 普通 trans/ssh 短连接硬预算 60s；长 CI/CD、trace、logs、build、硬件流程必须 submit-and-poll。
- 一次性远程实验不得临时发明第二套状态协议：
  - 使用 [远程临时实验 smoke](references/remote-experiment-smoke.md) 的参数合同；
  - 复用同一模板的后台 job、证据和清理合同。
- `/mnt/<drive>` WSL host workspace 由 root 透传执行时，CLI 自动把 workspace owner uid 桥接到进程级 `SUDO_UID`，让 Git 信任 Windows 挂载目录而不写全局 `safe.directory`；非 Git 命令和普通 Linux workspace 不改变所有权信任。
- 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 `rg`：
  - 调用 Windows PATH 中的原生 `rg.exe`。
  - 支持一个或多个 `-e|--regexp`、`--files`、`-g|--glob`、`--max-count`、`--max-files` 和 `--timeout-ms`。
  - stderr 固定输出 `UNIDESK_WINDOWS_RG_SUMMARY`，包含 `matched`、`fileCount`、`elapsedMs`、`timeout` 和 `encoding`。
  - 默认预算来自 `config/unidesk-cli.yaml#trans.windowsFs.rg`。
  - 超时输出 `UNIDESK_WINDOWS_RG_HINT code=timeout exitCode=124 action=narrow-scope-or-add-glob`。
  - 缺少 `rg.exe` 时返回 127 和安装或 PowerShell 替代提示。
- Windows `wc` 支持 `-l|--lines`、`-w|--words`、`-m|--chars` 和 `-c|--bytes`；`skills` 支持 `--name <精确名称>` 与 `--filter <文本>`，单个 skill 查询不应先拉取全量列表。
- Windows `head` / `tail`：
  - 支持 `-n N`、`-nN`、`--lines=N` 和 GNU 简写 `-N`。
  - 两者按行流式裁剪，不能在裁剪前因整文件超过通用读取门禁而失败。
  - PowerShell prelude 将 `Get-Content` 默认编码固定为 UTF-8，读取 UTF-8 Markdown 时应与 `cat` helper 保持一致。
- Windows `ps '<PowerShell source>'` 的单个参数按 PowerShell 源码执行；`ps <command> <arg...>` 的多个参数按 argv 边界执行，Windows native application 通过显式命令行引用保留 `python -c` 代码、路径、encoding 和字典 key 中的嵌套引号。
- `trans` / `tran` 是 PATH wrapper，不是 `bun scripts/cli.ts` 的根子命令；误写 `bun scripts/cli.ts trans ...` 时应读取结构化 `trans-root-cli-entrypoint-moved` 错误，并改用 `trans <route> <operation> [args...]`。
- cwd 语义按运行面分层：
  - host/workspace 将绝对 cwd 写入 route，例如 `trans NC01:/root/unidesk exec git status --short`；
  - k3s workload 使用 route cwd 后缀或 `exec --cwd /workspace -- <command>`；
  - host/workspace 误用 `exec|argv|sh|bash --cwd` 会在连接前返回 `trans-host-cwd-belongs-in-route` 与精确替代命令，禁止继续试探远端参数。
- Direct argv 会保留调用端已经形成的每个 argv token，包括空格和中文；需要 shell 语法时仍显式使用 `sh`、`bash`、Windows `cmd` 或 `ps`。
- Windows workspace 中依赖 Windows PATH、解释器或工具链的命令优先走 `<provider>:win/<drive>/<path> cmd|ps`；不得因同一 WSL provider 的 host/WSL plane 缺少 `python`、编译器或其他命令，就判断 Windows plane 也未安装。Windows Python 例如 `trans G14-WSL:win/d/Work/CONSTAR_workspace cmd python --version`。
- `/mnt/<drive>` workspace 的命令返回 `command not found` 时，CLI 会输出对应 `:win/<drive>/... cmd` 的 `UNIDESK_SSH_HINT`；该提示只建议核对 Windows plane，不改变原命令退出码。
- Windows `git` helper 拒绝包含 `%` format 等需 shell review 的复杂参数时，按错误提示改用 `trans <route>:win/... ps '<PowerShell command>'`，不要反复改写 direct `git` argv 绕过校验。
- Windows 固定脏 worktree 的精确提交规则：
  - 使用 `git exact-commit plan` 明确列出一个或多个 `--path`；
  - `run` 必须提供 `--message` 和 `--confirm`；
  - helper 使用临时 index 和 HEAD old-value CAS，只更新选中路径的 index，并验证未选中路径的 staged/unstaged 状态不变；
  - `status` 只读披露 `git count-objects -v`；
  - `gc-auto` 只调用 Git 自身的 `git gc --auto`，保留 reflog 和 recent-object 规则，禁止直接 `git prune`。
- 从本地 Bash 调用一行 Windows `ps` 时，PowerShell 表达式外层使用单引号，保护 `$`、`$_` 和 `$_.Property` 不被本地 shell 提前展开；复杂或多行 PowerShell 改用 `ps <<'PS'` heredoc。
- 单行 `ps` 源码若因本地 shell 展开而以缺失左值的 `=` 开始，CLI 在远端执行前返回 `ssh-windows-powershell-local-expansion`，并给出 `$p`、`$_` 的单引号示例和 quoted `PS` heredoc。
- 扩展 Windows helper 时保持 operation-scoped PowerShell payload；不要把多操作大脚本塞进 single `EncodedCommand`。

## 何时读取 reference

- 不确定 route 语法、k3s/workspace/Windows 定位时，读 [references/routes.md](references/routes.md)。
- 编写远端 patch 前，读 [references/apply-patch.md](references/apply-patch.md)。
- 需要 shell heredoc、Python、upload/download 或超时处理时，读 [references/operations.md](references/operations.md)。