docs(trans): clarify Windows toolchain plane
This commit is contained in:
Codex
@@ -32,6 +32,7 @@ Host workspace、k3s、Windows、GitHub issue/PR route 见 [references/routes.md
|
||||
- 普通 trans/ssh 短连接硬预算 60s；长 CI/CD、trace、logs、build、硬件流程必须 submit-and-poll。
|
||||
- `/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 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`。
|
||||
- Windows `git` helper 拒绝包含 `%` format 等需 shell review 的复杂参数时，按错误提示改用 `trans <route>:win/... ps '<PowerShell command>'`，不要反复改写 direct `git` argv 绕过校验。
|
||||
- 从本地 Bash 调用一行 Windows `ps` 时，PowerShell 表达式外层使用单引号，保护 `$`、`$_` 和 `$_.Property` 不被本地 shell 提前展开；复杂或多行 PowerShell 改用 `ps <<'PS'` heredoc。
|
||||
- 扩展 Windows helper 时保持 operation-scoped PowerShell payload；不要把多操作大脚本塞进 single `EncodedCommand`。
|
||||
|
||||
@@ -7,6 +7,8 @@ Prefer direct, bounded operations:
|
||||
- `logs`: tail bounded logs, not full dumps.
|
||||
- `py`, `upload`, `download`: one-off support operations when patch is not appropriate.
|
||||
|
||||
For a Windows workspace, run tools that belong to the Windows installation or PATH through the Windows plane: use `trans <provider>:win/<drive>/<path> cmd ...` for ordinary command-line tools and `ps` for PowerShell logic. For example, use `trans G14-WSL:win/d/Work/CONSTAR_workspace cmd python --version` or invoke a Python script there with `cmd python path\\to\\script.py ...`. A failed `python` lookup on `<provider>:/mnt/<drive>/...` describes only the WSL/host plane and is not evidence that Windows Python is absent.
|
||||
|
||||
`download` returns verified bytes/SHA-256 evidence. On Windows routes, drive-letter paths are automatically mapped through the same provider's WSL `/mnt/<drive>` host route for binary streaming; for example `trans D518:win download 'D:\tmp\image.png' /tmp/image.png` does not require manually rewriting the source path to `/mnt/d/tmp/image.png`. Relative Windows downloads use the `win/<drive>/<path>` route workspace, such as `trans D518:win/d/tmp download image.png /tmp/image.png`. UNC paths still need to be copied to a drive-letter path first.
|
||||
|
||||
Ordinary trans/SSH work must fit the short connection budget. Long build, CI/CD, trace, probe or rollout work must use submit-and-poll through a controlled job/status surface.
|
||||
|
||||
@@ -415,6 +415,8 @@ trans D601 glob --root /home/ubuntu/pikapython --pattern '**/*-test.cpp' --limit
|
||||
|
||||
当前稳定 plane 包括 `win` 和 `k3s`。`win` plane 的 operation 是 Windows 操作，不是 POSIX shell 别名：`<provider>:win ps` 在 WSL provider 上启动 Windows PowerShell，stdin heredoc 会被写入临时 `.ps1` 后执行；`<provider>:win cmd` 启动 Windows host 的 `cmd.exe`，stdin heredoc 会被写入临时 `.cmd` 后执行；`<provider>:win skills` 发现 Windows skill 目录。需要 Windows 当前目录时使用 slash 路由 `<provider>:win/<drive>/<path>`，例如 `D601:win/c/test ps` 会先在 PowerShell 内 `Set-Location -LiteralPath 'C:\test'`，`D601:win/c/test cmd cd` 会先在 cmd 内执行 `cd /d "C:\test"`。`D601:win/c/test git ...` 是 cmd convenience wrapper，覆盖 `status`、`diff`、非交互 `commit -m ...` 等常规 argv 形态；会打开编辑器或需要 shell 审阅的 git 命令仍用 `ps` 或 `cmd` 包装。`win32` 不是合法 plane，调用者必须改用 `win`。
|
||||
|
||||
Windows workspace 中依赖 Windows PATH、解释器、SDK 或编译工具链的操作必须优先在 `win` plane 执行，而不是先进入同一 provider 的 WSL `/mnt/<drive>` host workspace。WSL/host plane 与 Windows plane 是两套命令环境：前者出现 `python: command not found` 只证明 WSL PATH 中没有该命令，禁止据此判断 Windows 未安装 Python。Windows Python 的最小探测入口是 `trans G14-WSL:win/d/Work/CONSTAR_workspace cmd python --version`；需要 PowerShell 变量、管道或多步逻辑时改用同一路由的 `ps`。
|
||||
|
||||
`<provider>:win ps` 是 Windows PowerShell 专用入口，适合管道、变量、`Get-ChildItem`、`Start-Process`、`Test-Path` 和 Windows 路径脚本；不要用 host/k3s 的 `sh`/`bash` operation 表示 PowerShell。`ps` 和 `cmd` 都注入 UTF-8/Python 编码默认值；`cmd` 额外执行 `chcp 65001>nul`。典型用法：
|
||||
|
||||
```bash
|
||||
|
||||
Reference in New Issue
Block a user