docs: document windows detached gateway launch
This commit is contained in:
Codex
@@ -38,6 +38,7 @@
|
||||
|
||||
- 在 `G14:k3s` 的 `hwlab-dev` namespace 手动建立一个 standalone `device-agent-71-freq` Pod/Deployment 和 ClusterIP Service。它暴露设备语义入口，例如 `/health`、`/skills`、`/workspace/*`、`/run`，并把真实硬件调用转成 HWLAB cloud-api 的 gateway operation，而不是在 Pod 内直接访问 Windows 硬件。
|
||||
- 在 `D601:win` 上启动 `hwlab-gateway`，作为 71-FREQ/ConStart/Keil/串口资源的外部 host bridge。gateway 通过公网或受控网络出站连接当前 G14 DEV cloud-api：`http://74.48.78.17:17667`，注册稳定的 `gatewaySessionId`、`resourceId` 和 `capabilityId`。
|
||||
- `hwlab-gateway` 是 Windows 长驻 outbound poll 进程，不能用 `tran D601:win cmd start ...` 或 PowerShell `Start-Process` 直接挂在一次性 tran 会话下；这种启动方式可能继承输出句柄或被 provider 按子进程树等待，导致 tran 卡住并阻塞后续 provider session。临时实验也应通过 Windows Task Scheduler、Windows Service、NSSM、PM2 service 或等价 detached launcher 启动，`tran` 只负责触发和读取状态；通用规则见 `docs/reference/windows-passthrough.md`。
|
||||
- D601 Windows gateway 的最小配置必须来自 profile 或环境变量，核心字段是 `HWLAB_GATEWAY_CLOUD_URL=http://74.48.78.17:17667`、`HWLAB_GATEWAY_ID`、`HWLAB_GATEWAY_SESSION_ID`、`HWLAB_GATEWAY_RESOURCE_ID`、`HWLAB_GATEWAY_CMD_CAPABILITY_ID`、`HWLAB_GATEWAY_CMD_EXEC_ENABLED=1`、`HWLAB_GATEWAY_DEMO_OPEN=1`、`HWLAB_GATEWAY_MAX_INFLIGHT` 和 `HWLAB_GATEWAY_CMD_TIMEOUT_MS`。这些值用于声明能力和执行边界，不得散落在 device-agent 代码里。
|
||||
- device-agent 访问 G14 集群内 cloud-api 时优先使用 `http://hwlab-cloud-api.hwlab-dev.svc.cluster.local:6667`。Node/undici `fetch` 会按 Fetch bad-port 规则拒绝 `6667`，因此 Node 实现必须使用 `node:http`/`node:https`、已有 repo-owned HTTP helper，或改用不触发 bad-port 的受控代理端口。
|
||||
- 71-FREQ 的 device profile 必须配置化保存，至少包含工程根目录、Keil project/target、默认串口波特率、gateway/resource/capability 选择器和 workspace 根。不得把 `F:\Work\ConStart`、工程名、串口号或 probe UID 硬编码进 device-agent 镜像。
|
||||
|
||||
@@ -28,6 +28,20 @@ tran <PROVIDER_ID>:win skills --limit 20
|
||||
|
||||
`<PROVIDER_ID>:win skills` 是 Windows 用户 skill 发现入口，默认读取当前 Windows 用户 `%USERPROFILE%\.agents\skills`，输出 JSON 中包含 `roots`、`counts` 和每个 skill 的 `name`、`path`、`skillFile`、`description`。需要同时读取 `%USERPROFILE%\.codex\skills` 时使用 `--scope all`；只看 Codex skill 时用 `--scope codex`。该入口用于替代手写 `cmd dir`、`powershell Get-ChildItem` 或宽泛扫描用户目录。
|
||||
|
||||
## 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 串行排队。
|
||||
|
||||
长驻 Windows 进程必须使用明确脱离当前 `tran` 会话的启动模型：
|
||||
|
||||
- 优先把启动参数写入节点私有 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。
|
||||
- 启动命令必须避免从 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、触发启动和读取状态。
|
||||
|
||||
## Skill Discovery
|
||||
|
||||
先用 UniDesk SSH 透传内置的 skill 发现入口确认目标节点上 WSL 与 Windows 两侧 skill 的实际位置：
|
||||
|
||||
Reference in New Issue
Block a user