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。

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

高频 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 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。
• sh/bash/argv/py/upload/download/kubectl/logs/skills/tcp-pool 操作见 references/operations.md。
• 跨 60 秒短连接的临时 build、GPU、模型或硬件 smoke 见 references/remote-experiment-smoke.md。
• apply-patch envelope 和 quoting 陷阱见 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 的参数合同；
  • 复用同一模板的后台 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。
• 编写远端 patch 前，读 references/apply-patch.md。
• 需要 shell heredoc、Python、upload/download 或超时处理时，读 references/operations.md。