pikasTech-unidesk/.agents/skills/unidesk-trans/references/operations.md

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 的单次参数化模板；
  • 长步骤只提交后台 job，后续使用有界 status/log tail 轮询；
  • 结束时输出统一 evidence 摘要，并复查资源前缀或 label 无残留。