From 7bad130e5da4570ee3a38857ff0c49e03495cb1c Mon Sep 17 00:00:00 2001
From: Codex <codex@local>
Date: Sun, 31 May 2026 15:57:27 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E8=AE=B0=E5=BD=95=20D601=20F103=20devi?=
 =?UTF-8?q?ce-pod=20gateway=20SOP?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/reference/spec-device-pod.md | 77 +++++++++++++++++++++++++++++++
 1 file changed, 77 insertions(+)

diff --git a/docs/reference/spec-device-pod.md b/docs/reference/spec-device-pod.md
index 8ecc8a44..3e9b82f7 100644
--- a/docs/reference/spec-device-pod.md
+++ b/docs/reference/spec-device-pod.md
@@ -270,6 +270,83 @@ manages: many devicePodId
 - mutating job 继续由 cloud-api 侧强制 lease/reason；CLI 只转发 `reason` 和 `leaseToken`，不在本地绕过。
 - `profile create` 这类本地 profile bootstrap 在正式默认路径中返回 `legacy_profile_create_removed`；管理员应使用 cloud-api admin API 管理服务端 profile/grant。
 
+## D601 F103 v0.2 Gateway SOP
+
+D601 Windows F103 gateway 的稳定命名使用 `gws_D601_F103`。不要因为当前 `devicePodId` 或样例设备名是 `device-pod-71-freq` / `71-FREQ`，把 gateway session 改成旧的 `gws_d601_win_71_freq`；profile route 和 Windows gateway 运行脚本必须使用同一组 F103 命名。
+
+Windows 侧固定入口：
+
+```text
+Task Scheduler: HWLAB-DevicePodGateway-D601-F103
+run script: C:\Users\liang\device-pod-gateway-rust\run-D601-F103.cmd
+local status: http://127.0.0.1:7001/status
+cloud API: http://74.48.78.17:19667
+```
+
+`run-D601-F103.cmd` 中的关键环境变量应保持为：
+
+```cmd
+set "HWLAB_GATEWAY_CLOUD_URL=http://74.48.78.17:19667"
+set "HWLAB_GATEWAY_ID=gtw_D601_F103"
+set "HWLAB_GATEWAY_SESSION_ID=gws_D601_F103"
+set "HWLAB_GATEWAY_RESOURCE_ID=res_windows_host"
+set "HWLAB_GATEWAY_BOX_ID=box_windows_host"
+set "HWLAB_GATEWAY_CMD_CAPABILITY_ID=cap_windows_cmd_exec"
+set "HWLAB_GATEWAY_CMD_EXEC_ENABLED=1"
+set "HWLAB_GATEWAY_MAX_INFLIGHT=4"
+set "HWLAB_GATEWAY_CMD_TIMEOUT_MS=120000"
+set "HWLAB_GATEWAY_PORT=7001"
+```
+
+v0.2 `device-pod-71-freq` 的服务端 profile route 必须和 gateway 注册保持一致：
+
+```json
+{
+  "gatewaySessionId": "gws_D601_F103",
+  "resourceId": "res_windows_host",
+  "capabilityId": "cap_windows_cmd_exec",
+  "hostWorkspaceRoot": "F:\\Work\\ConStart",
+  "hostCli": "node C:\\Users\\liang\\AppData\\Local\\Temp\\hwlab-v02-device-host-cli\\device-host-cli.mjs"
+}
+```
+
+重启 gateway 时使用计划任务，不从临时 shell 直接启动长期进程：
+
+```cmd
+schtasks /End /TN HWLAB-DevicePodGateway-D601-F103
+schtasks /Run /TN HWLAB-DevicePodGateway-D601-F103
+powershell -NoProfile -Command "Invoke-RestMethod http://127.0.0.1:7001/status | ConvertTo-Json -Depth 12"
+```
+
+通过 UniDesk Windows route 操作时，工作目录应直接定位到 gateway 目录，例如 `D601:win/c/Users/liang/device-pod-gateway-rust`，再读取 `run-D601-F103.cmd` 或查询 `/status`。`/status` 中至少应看到 `gatewaySessionId=gws_D601_F103`、`cloudUrl=http://74.48.78.17:19667`、`session.status=connected`、`outbound.lastPollError=null`。
+
+G14 v0.2 验收在 `G14:/root/hwlab-v02` 执行，先确认 Cloud Web 同源 CLI 能看到 device pod 状态，再用正式 `device-pod-cli` 创建并轮询 job：
+
+```bash
+bun tools/hwlab-cli/bin/hwlab-cli.ts client device-pods status device-pod-71-freq \
+  --base-url http://74.48.78.17:19666 \
+  --full
+
+COOKIE=$(node -pe 'require("./.state/hwlab-cli/session.json").cookie')
+bun tools/device-pod-cli.ts device-pod-71-freq:workspace:/ ls \
+  --api-base-url http://74.48.78.17:19667 \
+  --cookie "$COOKIE" \
+  --reason "v02 gws_D601_F103 smoke" \
+  --timeout-ms 120000 | tee /tmp/hwlab-device-pod-job.json
+
+JOB=$(node -e 'const fs=require("fs"); const payload=JSON.parse(fs.readFileSync("/tmp/hwlab-device-pod-job.json", "utf8")); console.log(payload.body.job.id)')
+
+bun tools/device-pod-cli.ts job status --pod-id device-pod-71-freq "$JOB" \
+  --api-base-url http://74.48.78.17:19667 \
+  --cookie "$COOKIE"
+
+bun tools/device-pod-cli.ts job output --pod-id device-pod-71-freq "$JOB" \
+  --api-base-url http://74.48.78.17:19667 \
+  --cookie "$COOKIE"
+```
+
+验收通过条件：`client device-pods status` 返回 `status=ok` 且 `blocker=null`；gateway sessions 中 `gws_D601_F103` 为 online；`device-pod-cli` job 进入 `completed`，且 D601 Windows gateway `/status.lastDispatch.operationId` 与该 job 的 `operationId` 一致并有 `lastResultAt`。旧 `gws_d601_win_71_freq` session 只能作为历史 stale 线索，不能作为 v0.2 F103 gateway 的目标命名。
+
 ## 测试规格
 
 ## T1