mirrors/pikasTech-HWLAB
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add outbound gateway demo

Browse Source
This commit is contained in:
lyon
2026-05-23 23:39:58 +08:00
parent 194ca572c7
commit ab063880bd
11 changed files with 1149 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/reference/README.md
-47
View File
@@ -1,47 +0,0 @@
# HWLAB 长期参考入口
`docs/reference/` 是 HWLAB agent、指挥官和 runner 的长期参考目录，只记录长期稳定、可复用的规则、边界、入口、命令和验收标准。issue、日报、简报、一次性报告和执行流水账只能作为来源，不混入长期参考文档。
## 权威分工
| 规则 | 唯一权威出处 | 边界 |
| --- | --- | --- |
| `docs-spec` 本地权威、长期参考入库和过程文档蒸馏 | [documentation-governance.md](documentation-governance.md) | 该文件等价承担 `docs/reference/docs-spec.md` 的职责；其他 reference 只交叉引用，不另写一套文档治理规则。 |
| 中文优先的 issue、PR 和文档规则 | [chinese-first-documentation.md](chinese-first-documentation.md) | 英文标识可保真，解释、约束和验收口径必须中文化。 |
| 用户和参谋反馈默认高优先级分流 | [user-feedback-triage.md](user-feedback-triage.md) | `blocked`、等待上游或环境限制只描述状态，不能替代反馈优先级。 |
| 指挥官一手事实、真实推进和 PR 协作边界 | [commander-collaboration.md](commander-collaboration.md) | 本目录的文档治理规则不覆盖 [pikasTech/HWLAB#131](https://github.com/pikasTech/HWLAB/issues/131) 的指挥作风边界。 |
## 参考索引
| 主题 | 参考文档 |
| --- | --- |
| 中文优先规则 | [chinese-first-documentation.md](chinese-first-documentation.md) |
| 用户反馈分流规则 | [user-feedback-triage.md](user-feedback-triage.md) |
| 文档治理与 docs-spec 本地权威 | [documentation-governance.md](documentation-governance.md) |
| 架构和 M3 上位约束 | [architecture.md](architecture.md) |
| DEV 运行态、端口、k3s、DB readiness 和环境边界 | [dev-runtime-boundary.md](dev-runtime-boundary.md) |
| 部署正规化、`deploy.json` DEV CD 路径、SecretRef preflight、runner/host 边界、artifact 发布和 Cloud Web rollout | [deployment-publish.md](deployment-publish.md) |
| Cloud Workbench 默认界面和 UX 边界 | [cloud-workbench.md](cloud-workbench.md) |
| Code Agent chat 同源通道 readiness 与真实回复判定 | [code-agent-chat-readiness.md](code-agent-chat-readiness.md) |
| MVP E2E 验收测试与带编号测试报告 issue 规则 | [MVP-e2e-acceptance.md](MVP-e2e-acceptance.md) |
| 指挥官/runner 协作、PR 和 prompt handoff | [commander-collaboration.md](commander-collaboration.md) |
| M3 闭环 rollout runbook | [m3-loop-rollout-runbook.md](m3-loop-rollout-runbook.md) |
| runner GitHub 可见性与 prompt handoff | [runner-issue-visibility-handoff.md](runner-issue-visibility-handoff.md) |
## 当前稳定来源
- [pikasTech/HWLAB#7](https://github.com/pikasTech/HWLAB/issues/7)：指挥官看板、优先级顺序和当前 issue 状态；用户反馈必须挂到这里的醒目位置。
- [pikasTech/HWLAB#78](https://github.com/pikasTech/HWLAB/issues/78)：`DC-DCSN-P0-2026-003`，M3 虚拟硬件可信闭环方向和上位约束。
- [pikasTech/HWLAB#121](https://github.com/pikasTech/HWLAB/issues/121)：issue 和长期文档中文化要求。
- [pikasTech/HWLAB#122](https://github.com/pikasTech/HWLAB/issues/122)：用户和参谋反馈默认按高优先级用户反馈处理，并挂到 `#7`。
- [pikasTech/HWLAB#123](https://github.com/pikasTech/HWLAB/issues/123)：docs-spec 规则必须固化进 HWLAB 长期参考文档；本仓库由 [documentation-governance.md](documentation-governance.md) 作为等价本地权威。
- [pikasTech/HWLAB#131](https://github.com/pikasTech/HWLAB/issues/131)：指挥作风纠偏、一手事实优先和真实推进规则。
- [pikasTech/HWLAB#99](https://github.com/pikasTech/HWLAB/issues/99)：Cloud Workbench 默认前端方向。
- [pikasTech/HWLAB#108](https://github.com/pikasTech/HWLAB/issues/108)：禁止外层页面纵向滚动、中文 UI 和内部 Markdown 帮助页。
- [pikasTech/HWLAB#61](https://github.com/pikasTech/HWLAB/issues/61)：DEV 手动 rollout 复盘，以及走向 CLI 加 `deploy/deploy.json` 自动化的路径。
- [pikasTech/HWLAB#109](https://github.com/pikasTech/HWLAB/issues/109)：文档治理和长期参考体系。
- [pikasTech/HWLAB#116](https://github.com/pikasTech/HWLAB/issues/116)：服务部署正规化三阶段：长期参考、受控 CLI/脚本入口、UniDesk CI/CD 加镜像化交付。
- [pikasTech/HWLAB#235](https://github.com/pikasTech/HWLAB/issues/235)：Cloud API、DB、部署与运行态专题，承载 deploy.json、DEV CD、runtime 和 16666/16667 运行态收敛关系。
- [pikasTech/HWLAB#340](https://github.com/pikasTech/HWLAB/issues/340)：`deploy.json` DEV CD 路径长期化、master CLI wrapper、Secret preflight 和恢复后健康审计。
当 issue、报告或旧文档与本目录 reference 文档冲突时，先更新 reference 文档，再让 `AGENTS.md` 保持短索引。过程记录不得被改写；只能把稳定结论蒸馏进这里。
docs/reference/chinese-first-documentation.md
+1 -1
View File
@@ -29,7 +29,7 @@
## 验收标准
- `AGENTS.md` 能索引中文优先规则。
- `docs/reference/README.md` 的索引和来源说明中文主导。
- 不再维护 `README.md` / `docs/reference/README.md` 入口；`AGENTS.md` 作为唯一入口时，其索引和来源说明必须中文主导。
- 新增或更新长期参考时，中文解释覆盖“做什么、为什么、怎么判定、禁止什么”。
- 必要英文术语保留精确拼写，但不能让文档主体变回英文。
docs/reference/documentation-governance.md
+4 -4
View File
@@ -6,12 +6,12 @@
## AGENTS.md 规则
- `AGENTS.md` 只作为项目级顶级索引，用于快速定位命令、入口和长期参考文档。
- 与 `AGENTS.md` 同等作用的文档，例如 `CLAUDE.md`，只保留 `@AGENTS.md` 引导，避免多套口径漂移。
- `AGENTS.md` 是 agent、指挥官和 runner 的唯一入口，用于快速定位命令、入口和长期参考文档。
- 与 `AGENTS.md` 同等作用的文档，例如 `README.md`、`docs/reference/README.md`、`CLAUDE.md`，不得作为入口或索引；如果必须存在，只能说明应回到 `AGENTS.md`，避免多套口径漂移。
- 每个命令在 `AGENTS.md` 中只保留一条主索引；参数、背景、判定标准写入链接的 reference 文档。
- `AGENTS.md` 的主标题、章节名和列表摘要必须中文优先；`Agent`、`runner`、`Cloud Workbench`、命令和路径等可保留原文，但要放在中文语境中解释。
- 每个列表项只描述一个功能点，用一句中文概括，不在顶层展开实现细节。
- `AGENTS.md` 必须索引中文优先、用户反馈分流、PR 工作流、`#78` 上位约束和 `docs/reference/` 入口。
- `AGENTS.md` 必须直接索引中文优先、用户反馈分流、PR 工作流、`#78` 上位约束和各专项 `docs/reference/*.md`，不得再通过 README.md 二级入口跳转。
## docs/reference 长期参考规则
@@ -44,7 +44,7 @@
- 本文保留外部 `docs-spec` 的完整核心规则，使没有 skill 可见性的 runner 仍能执行 HWLAB 文档治理；它是 `#123` 要求的 repo 内权威落点。
- 每次任务涉及 `AGENTS.md`、`docs/reference/*.md` 或过程文档蒸馏时，runner 应先读取外部 `docs-spec` skill；如果外部规则与本文不同，必须在同一 PR 中同步更新本文并说明差异。
- 如果外部 skill 不可读，按本文执行，并在 PR body 中说明“使用仓库内 docs-spec 固化规则，外部 skill 不可用或未校验”。
- `docs/reference/README.md` 是长期参考入口；新增 reference 后必须更新该索引和 `AGENTS.md`。
- 本仓库覆盖外部通用 docs-spec 中的 README 入口口径：新增 reference 后只更新对应 reference 和 `AGENTS.md`，不得新增或维护 `README.md` / `docs/reference/README.md` 入口。
## HWLAB 当前应用
docs/reference/gateway-outbound-demo.md
+77
View File
@@ -0,0 +1,77 @@
# Gateway 主动出站 demo
本文是 `hwlab-gateway` 最小主动出站闭环的长期参考。该 demo 只验证 gateway 主动连接 cloud、cloud 下发命令、gateway 执行并回传结果；不得把它当作 M3 `DEV-LIVE` 虚拟硬件可信闭环，也不得替代 `BOX-SIMU / Gateway-SIMU / hwlab-patch-panel` 的 M3 验收链路。
## 边界
- `hwlab-gateway` 运行在用户 PC 或本地环境，主动访问 `hwlab-cloud-api`；cloud 不需要也不应入站访问 gateway。
- demo 采用普通 HTTP poll/result：gateway 调 `POST /v1/gateway/poll` 拉取命令，执行后调 `POST /v1/gateway/result` 回传 JSON-RPC response。
- `hardware.invoke.shell` 仍是 cloud-api 对外 RPC 方法；有在线 gateway 时通过主动出站链路派发，没有在线 gateway 时保留 `not_connected` 降级返回。
- 当前命令执行能力只用于受限 demo；正式真实硬件控制仍应沿用统一 capability、audit、evidence 和后续 WebSocket/设备身份设计。
## Cloud API 入口
- `GET /v1/gateway/sessions`：只读查看在线 gateway、队列深度和 last-seen。
- `POST /v1/gateway/poll`：gateway 主动注册、心跳并领取下一条待执行 JSON-RPC 请求。
- `POST /v1/gateway/result`：gateway 主动回传 JSON-RPC response，cloud-api 用 request id 完成等待中的 `hardware.invoke.shell`。
- `POST /json-rpc` 或 `POST /v1/rpc/hardware.invoke.shell`：用户、agent 或 smoke 仍只调用 cloud-api，不直连 gateway。
## Gateway 环境变量
| 变量 | 作用 |
| --- | --- |
| `HWLAB_GATEWAY_CLOUD_URL` | cloud-api 或 edge-proxy 地址；本地可用 `http://127.0.0.1:6667`，DEV 可用 `http://74.48.78.17:16667`。 |
| `HWLAB_GATEWAY_ID` | gateway 稳定身份，例如 `gtw_windows_1`。 |
| `HWLAB_GATEWAY_SESSION_ID` | gateway session id；不填时默认为 `gws_${HWLAB_GATEWAY_ID}`。 |
| `HWLAB_GATEWAY_CMD_EXEC_ENABLED=1` | 允许执行 shell 命令；未设置时 gateway 拒绝 `hardware.invoke.shell`。 |
| `HWLAB_GATEWAY_DEMO_OPEN=1` | demo 明确打开标记；本地 smoke 会设置。 |
| `HWLAB_GATEWAY_POLL_INTERVAL_MS` | poll 间隔，默认 500ms。 |
| `HWLAB_GATEWAY_CMD_TIMEOUT_MS` | 单条命令超时，默认 10000ms。 |
| `HWLAB_GATEWAY_CMD_OUTPUT_LIMIT_BYTES` | stdout/stderr 单路输出上限，默认 65536 bytes。 |
本地或内网存在代理时，必须显式设置：
```powershell
$env:NO_PROXY="localhost,127.0.0.1,::1"
$env:no_proxy="localhost,127.0.0.1,::1"
```
## 本地验证
优先使用一键 smoke，避免手动多终端状态不一致：
```powershell
npm run gateway:demo:smoke
npm run gateway:demo:edge-smoke
```
- `gateway:demo:smoke` 启动本地 `hwlab-cloud-api` 和 `hwlab-gateway`，验证 `hardware.invoke.shell` 返回 `stdout=hwlab-demo`。
- `gateway:demo:edge-smoke` 额外启动本地 `hwlab-edge-proxy`，验证普通 HTTP proxy 能转发 `/v1/gateway/poll`、`/v1/gateway/result` 和 `/json-rpc`。
- 两个 smoke 都会设置 `NO_PROXY/no_proxy`，用于规避本地代理误触发。
## DEV 使用
DEV cloud-api 部署包含 `/v1/gateway/*` 后，Windows gateway 可用以下方式主动连接：
```powershell
$env:HWLAB_GATEWAY_CLOUD_URL="http://74.48.78.17:16667"
$env:HWLAB_GATEWAY_ID="gtw_windows_1"
$env:HWLAB_GATEWAY_SESSION_ID="gws_gtw_windows_1"
$env:HWLAB_GATEWAY_CMD_EXEC_ENABLED="1"
$env:HWLAB_GATEWAY_DEMO_OPEN="1"
node .\cmd\hwlab-gateway\main.mjs
```
验证时从 cloud-api 侧调用 `hardware.invoke.shell`，不要尝试从 cloud 入站访问 Windows gateway。若 `GET /v1/gateway/sessions` 能看到对应 `gatewaySessionId` 且 JSON-RPC 返回 `dispatch.shellExecuted=true`，说明主动出站 demo 链路成立。
## 后续替换为 WebSocket
HTTP poll 是最小 demo 形态。后续替换成 WebSocket 时，应保留：
- `hardware.invoke.shell` 对外 RPC 方法名；
- JSON-RPC request/response envelope；
- gateway 执行器的 stdout/stderr/exitCode/timedOut 返回形态；
- audit/evidence 由 gateway/cloud 硬件通道产生的原则；
- cloud-web、agent 和 CLI 不直连 gateway 的边界。
只替换传输层：`/v1/gateway/poll` 和 `/v1/gateway/result` 合并到 gateway 主动建立的 `/v1/gateway/ws` 长连接。