docs: standardize trans passthrough alias
This commit is contained in:
Codex
@@ -4,7 +4,7 @@ Windows 透传用于让 WSL provider 通过 UniDesk 的 Host SSH / WSL SSH 维
|
||||
|
||||
## Architecture
|
||||
|
||||
标准链路是：本机或计算节点 CLI 调用 `bun scripts/cli.ts ssh <PROVIDER_ID> ...`，main server 的 backend-core 通过 provider-gateway 的既有 WebSocket 把终端流量转给目标 provider，provider-gateway 再用只读挂载的维护私钥连到目标 WSL sshd。进入 WSL 后，Windows-only 工具由 WSL 用户目录下的轻量 wrapper 调用 Windows 可执行文件。
|
||||
标准链路是：本机或计算节点 CLI 调用 `trans <PROVIDER_ID> ...`，main server 的 backend-core 通过 provider-gateway 的既有 WebSocket 把终端流量转给目标 provider，provider-gateway 再用只读挂载的维护私钥连到目标 WSL sshd。进入 WSL 后，Windows-only 工具由 WSL 用户目录下的轻量 wrapper 调用 Windows 可执行文件。
|
||||
|
||||
这条链路分三层维护：
|
||||
|
||||
@@ -17,9 +17,9 @@ Windows 透传用于让 WSL provider 通过 UniDesk 的 Host SSH / WSL SSH 维
|
||||
简单 Windows `cmd.exe` 命令不需要依赖节点侧 `win-cmd` wrapper。UniDesk CLI 内置 `win` route：
|
||||
|
||||
```bash
|
||||
tran <PROVIDER_ID>:win cmd ver
|
||||
tran <PROVIDER_ID>:win/c/test cmd cd
|
||||
tran <PROVIDER_ID>:win skills --limit 20
|
||||
trans <PROVIDER_ID>:win cmd ver
|
||||
trans <PROVIDER_ID>:win/c/test cmd cd
|
||||
trans <PROVIDER_ID>:win skills --limit 20
|
||||
```
|
||||
|
||||
`<PROVIDER_ID>:win` 只定位到 WSL provider 的 Windows host cmd 执行面，后面的 `cmd <command-line>` 才是操作。`<PROVIDER_ID>:win/<drive>/<path>` 使用 slash 语法设置 Windows cwd，例如 `D601:win/c/test` 会在 Windows cmd 内执行 `cd /d "C:\test"`。该入口固定在运行用户命令前设置 `chcp 65001>nul`、`set "PYTHONUTF8=1"` 和 `set "PYTHONIOENCODING=utf-8"`，因此中文 stdout/stderr 和 Python 子进程默认按 UTF-8 处理；环境变量必须使用 cmd 引号写法，避免 `set VAR=1 && ...` 把分隔符前的空格写进变量值。
|
||||
@@ -30,25 +30,25 @@ tran <PROVIDER_ID>:win skills --limit 20
|
||||
|
||||
## Windows Long-Lived Process Detach
|
||||
|
||||
`tran <PROVIDER_ID>:win cmd ...` 和 `tran <PROVIDER_ID> script -- powershell.exe ...` 适合短命令、只读探测和有界 skill 调用，不适合直接启动 Windows 长驻进程。Windows `cmd start`、`cmd /c ... &`、PowerShell `Start-Process -PassThru` 或带 stdout/stderr 重定向的子进程，仍可能被 provider-gateway/SSH broker 按子进程树或继承句柄等待；结果是远端进程其实已启动，但 `tran` 会持续占用 provider session，后续 D601/G14 高频调用被 provider session lock 串行排队。
|
||||
`trans <PROVIDER_ID>:win cmd ...` 和 `trans <PROVIDER_ID> script -- powershell.exe ...` 适合短命令、只读探测和有界 skill 调用，不适合直接启动 Windows 长驻进程。Windows `cmd start`、`cmd /c ... &`、PowerShell `Start-Process -PassThru` 或带 stdout/stderr 重定向的子进程，仍可能被 provider-gateway/SSH broker 按子进程树或继承句柄等待；结果是远端进程其实已启动，但 `trans` 会持续占用 provider session，后续 D601/G14 高频调用被 provider session lock 串行排队。
|
||||
|
||||
长驻 Windows 进程必须使用明确脱离当前 `tran` 会话的启动模型：
|
||||
长驻 Windows 进程必须使用明确脱离当前 `trans` 会话的启动模型：
|
||||
|
||||
- 优先把启动参数写入节点私有 profile 或 `.cmd`/`.ps1` 文件，再通过 Windows Task Scheduler、Windows Service、NSSM、PM2 Windows service 或同等 supervisor 启动。
|
||||
- 如果只是临时实验，使用 `schtasks /Create ... /TR "<cmd file>" /SC ONCE ... /F` 后再 `schtasks /Run ...`，并把 stdout/stderr 写入固定日志文件；验证用独立短命令读取 `tasklist`、`Get-CimInstance Win32_Process`、日志尾部和服务健康。
|
||||
- 不要在 `D601:win cmd` 内用 `start` 或 `Start-Process` 直接启动 `hwlab-gateway`、串口 monitor、Codex app-server、Keil job watcher 等长驻进程；如果误用了并导致 `tran` 卡住，应先停止对应 Windows PID 或本地被卡住的 tran/broker 进程，再改为 detached supervisor。
|
||||
- 不要在 `D601:win cmd` 内用 `start` 或 `Start-Process` 直接启动 `hwlab-gateway`、串口 monitor、Codex app-server、Keil job watcher 等长驻进程；如果误用了并导致 `trans` 卡住，应先停止对应 Windows PID 或本地被卡住的 trans/tran broker 进程，再改为 detached supervisor。
|
||||
- 启动命令必须避免从 WSL UNC cwd 进入 Windows cmd；长驻进程的 `cwd` 应是 Windows 盘符路径，例如 `F:\Work\HWLAB`，日志也写到同一节点私有 `.state` 或 skill state 目录。
|
||||
- 长驻进程的验收标准不是“启动命令返回”，而是独立短命令能看到 PID、日志首行、health endpoint 或 cloud-side session/resource/capability 已注册。
|
||||
|
||||
该规则尤其适用于 D601 Windows `hwlab-gateway` 连接 G14 HWLAB cloud-api 的场景：gateway 是长期 outbound poll 进程，必须由 detached launcher 或 supervisor 管理；`tran` 只负责创建/更新 launcher、触发启动和读取状态。
|
||||
该规则尤其适用于 D601 Windows `hwlab-gateway` 连接 G14 HWLAB cloud-api 的场景：gateway 是长期 outbound poll 进程，必须由 detached launcher 或 supervisor 管理；`trans` 只负责创建/更新 launcher、触发启动和读取状态。
|
||||
|
||||
## Skill Discovery
|
||||
|
||||
先用 UniDesk SSH 透传内置的 skill 发现入口确认目标节点上 WSL 与 Windows 两侧 skill 的实际位置：
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts ssh <PROVIDER_ID> skills --limit 80
|
||||
bun scripts/cli.ts ssh <PROVIDER_ID> skills --scope windows --limit 40
|
||||
trans <PROVIDER_ID> skills --limit 80
|
||||
trans <PROVIDER_ID> skills --scope windows --limit 40
|
||||
bun scripts/cli.ts --main-server-ip <MAIN_SERVER_IP> ssh <PROVIDER_ID> skills --scope wsl --limit 20
|
||||
```
|
||||
|
||||
@@ -167,12 +167,12 @@ keil list-devices -p <project.uvprojx>
|
||||
节点完成依赖 bootstrap 后，至少运行以下验证：
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts ssh <PROVIDER_ID> skills --limit 20
|
||||
bun scripts/cli.ts ssh <PROVIDER_ID> -- 'export PATH="$HOME/.local/bin:$PATH"; command -v win-cmd win-powershell win-py win-npm keil serial-monitor board-comm'
|
||||
bun scripts/cli.ts ssh <PROVIDER_ID> -- 'export PATH="$HOME/.local/bin:$PATH"; win-py -V; win-npm -v'
|
||||
bun scripts/cli.ts ssh <PROVIDER_ID> -- 'export PATH="$HOME/.local/bin:$PATH"; keil status'
|
||||
bun scripts/cli.ts ssh <PROVIDER_ID> -- 'export PATH="$HOME/.local/bin:$PATH"; serial-monitor ports'
|
||||
bun scripts/cli.ts ssh <PROVIDER_ID> -- 'export PATH="$HOME/.local/bin:$PATH"; board-comm debug build-jrpctcp-request get api'
|
||||
trans <PROVIDER_ID> skills --limit 20
|
||||
trans <PROVIDER_ID> -- 'export PATH="$HOME/.local/bin:$PATH"; command -v win-cmd win-powershell win-py win-npm keil serial-monitor board-comm'
|
||||
trans <PROVIDER_ID> -- 'export PATH="$HOME/.local/bin:$PATH"; win-py -V; win-npm -v'
|
||||
trans <PROVIDER_ID> -- 'export PATH="$HOME/.local/bin:$PATH"; keil status'
|
||||
trans <PROVIDER_ID> -- 'export PATH="$HOME/.local/bin:$PATH"; serial-monitor ports'
|
||||
trans <PROVIDER_ID> -- 'export PATH="$HOME/.local/bin:$PATH"; board-comm debug build-jrpctcp-request get api'
|
||||
```
|
||||
|
||||
硬件项目级验收还应覆盖真实 `build`、`program`、串口抓取和 `board-comm jrpctcp get api`。如果只有依赖检查通过但没有真实硬件闭环，不能宣称该工程已完成下载和通信验收。
|
||||
@@ -200,7 +200,7 @@ Code Queue 支持在提交任务时选择 `executionMode=windows-native`。该
|
||||
|
||||
- 只支持非主 server WSL Provider 和 Codex 模型；`minimax-m3` / `minimax-m2.7` / OpenCode port 不走该模式。
|
||||
- 工作目录必须在 `/mnt/<drive>/...` 下，供 `win-cmd` 转换为 Windows 盘符 cwd；D601 默认提示为 `/mnt/f/Work/ConStart`。
|
||||
- Windows 侧必须已安装 `codex`，且 WSL wrapper `win-cmd` 可用；可用 `bun scripts/cli.ts ssh D601 -- 'export PATH="$HOME/.local/bin:$PATH"; win-cmd "where codex && codex --version"'` 验证。
|
||||
- Windows 侧必须已安装 `codex`，且 WSL wrapper `win-cmd` 可用；可用 `trans D601 -- 'export PATH="$HOME/.local/bin:$PATH"; win-cmd "where codex && codex --version"'` 验证。
|
||||
- 任务 JSON、列表、Trace 摘要和前端卡片必须显示 `executionMode`，便于区分默认容器 Codex 与 Windows 原生 Codex。
|
||||
|
||||
## Remote Frontend Limits
|
||||
|
||||
Reference in New Issue
Block a user