From 24e0b94a09adc415582386cd6a57b4452cdb70ad Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 26 May 2026 08:08:43 +0800 Subject: [PATCH] docs: align HWLAB runtime references with G14 --- AGENTS.md | 4 +- docs/reference/MVP-e2e-acceptance.md | 18 ++++---- docs/reference/architecture.md | 14 +++---- docs/reference/cloud-workbench.md | 12 +++--- docs/reference/code-agent-chat-readiness.md | 10 ++--- docs/reference/commander-collaboration.md | 2 +- docs/reference/dev-runtime-boundary.md | 4 +- docs/reference/dev-runtime-hotfix-runbook.md | 44 +++++++++++--------- docs/reference/documentation-governance.md | 2 +- docs/reference/gateway-outbound-demo.md | 6 +-- docs/reference/m3-loop-rollout-runbook.md | 6 +-- 11 files changed, 63 insertions(+), 59 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 9279939a..e3ac434d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -80,9 +80,9 @@ HWLAB 是硬件实验室运行面和控制面项目。本文是 agent、指挥 - DEV runtime hotfix 只读审计计划：`npm run dev-runtime:hotfix-audit` - Gateway 主动出站本地 smoke：`npm run gateway:demo:smoke`；经本地 edge-proxy 验证用 `npm run gateway:demo:edge-smoke`。 -## D601 k3s 只读观测 +## D601 legacy 只读回溯 -HWLAB DEV runtime（运行态）在 D601 原生 k3s；只读诊断或手动发布必须显式使用 `/etc/rancher/k3s/k3s.yaml`，详见 [docs/reference/dev-runtime-boundary.md](docs/reference/dev-runtime-boundary.md)。 +当前 HWLAB DEV/PROD runtime（运行态）以 G14 原生 k3s 与 GitOps 为准；D601 只保留 legacy 事故回放、迁移对比和历史证据查询，不作为当前开发、发布、验收或 hotfix 目标。需要观察当前运行态时使用 UniDesk route `G14:k3s`，细则见 [docs/reference/dev-runtime-boundary.md](docs/reference/dev-runtime-boundary.md)。 ## 禁止误判 diff --git a/docs/reference/MVP-e2e-acceptance.md b/docs/reference/MVP-e2e-acceptance.md index 8a2aade2..c7c708de 100644 --- a/docs/reference/MVP-e2e-acceptance.md +++ b/docs/reference/MVP-e2e-acceptance.md @@ -4,8 +4,8 @@ ## 适用范围 -- 当前 DEV 浏览器入口固定为 `http://74.48.78.17:16666/`。 -- 当前 DEV API、edge 和 live health 入口固定为 `http://74.48.78.17:16667/` 与 `http://74.48.78.17:16667/health/live`。 +- 当前 G14 DEV 浏览器入口固定为 `http://74.48.78.17:17666/`。 +- 当前 G14 DEV API、edge 和 live health 入口固定为 `http://74.48.78.17:17667/` 与 `http://74.48.78.17:17667/health/live`。 - 当前 MVP 上位约束是 `DC-DCSN-P0-2026-003` / [pikasTech/HWLAB#78](https://github.com/pikasTech/HWLAB/issues/78)：M3 虚拟硬件可信闭环必须证明 `res_boxsimu_1:DO1 -> hwlab-patch-panel -> res_boxsimu_2:DI1`。 - 当前默认前端方向以 [pikasTech/HWLAB#99](https://github.com/pikasTech/HWLAB/issues/99) 为准：`/` 必须是类 VS Code 的 Cloud Workbench，不是 Gate、status 或 diagnostics 首页。 @@ -58,7 +58,7 @@ ## 证据等级 -- `DEV-LIVE`：真实 DEV `16666/16667` 上的浏览器、API、runtime 或短生命周期授权操作证据。 +- `DEV-LIVE`：真实 G14 DEV `17666/17667` 上的浏览器、API、runtime 或短生命周期授权操作证据。 - `SOURCE`：源代码、静态检查、合同校验或未部署构建证据。 - `LOCAL`：本地浏览器、fixture 或本地服务证据。 - `DRY-RUN`：显式 dry-run 输出，不触碰 DEV runtime。 @@ -70,12 +70,12 @@ ## T1 DEV 入口与运行边界 -阅读 `AGENTS.md`，然后用浏览器或 Playwright 手动测试以下内容：打开 `http://74.48.78.17:16666/`，确认默认页是 HWLAB Cloud Workbench，不是 Gate、status、help 或 diagnostics；访问 `http://74.48.78.17:16667/health` 和 `http://74.48.78.17:16667/health/live`，确认返回 HWLAB DEV API/edge identity。报告必须写明 public `:6666/:6667` 未作为当前验收入口，UniDesk backend、provider-gateway 和 microservice proxy 未作为 HWLAB runtime 替代。 +阅读 `AGENTS.md`，然后用浏览器或 Playwright 手动测试以下内容：打开 `http://74.48.78.17:17666/`，确认默认页是 HWLAB Cloud Workbench，不是 Gate、status、help 或 diagnostics；访问 `http://74.48.78.17:17667/health` 和 `http://74.48.78.17:17667/health/live`，确认返回 HWLAB DEV API/edge identity。报告必须写明 legacy public `:16666/:16667` 和 public `:6666/:6667` 未作为当前验收入口，UniDesk backend、provider-gateway 和 microservice proxy 未作为 HWLAB runtime 替代。 通过标准： -- `16666` 根页可由浏览器打开，页面标题、主导航或首屏内容明确指向 HWLAB 云工作台。 -- `16667/health` 或 `16667/health/live` 返回 JSON，包含 HWLAB service identity 和 dev environment。 +- `17666` 根页可由浏览器打开，页面标题、主导航或首屏内容明确指向 HWLAB 云工作台。 +- `17667/health` 或 `17667/health/live` 返回 JSON，包含 HWLAB service identity 和 dev environment。 - 报告 issue 附桌面首屏截图和 API/health 摘要。 ## T2 Cloud Workbench 首屏、布局与中文 UX @@ -102,7 +102,7 @@ ## T4 Code Agent 真实 runner 能力 -阅读 `AGENTS.md`，然后用浏览器或 Playwright 手动测试以下内容：在 `16666` 工作台 Agent 区输入 `pwd` 和“列出你可用的 skills”，确认返回来自真实 Codex runner、workspace、tool calls 和 skills 注入，而不是 `openai-responses` text-chat-only。随后让 Agent 通过 `hwlab-cloud-api` 执行同一 M3 硬件任务，确认 agent trace 引用对应 hardware operation 和 audit。 +阅读 `AGENTS.md`，然后用浏览器或 Playwright 手动测试以下内容：在 `17666` 工作台 Agent 区输入 `pwd` 和“列出你可用的 skills”，确认返回来自真实 Codex runner、workspace、tool calls 和 skills 注入，而不是 `openai-responses` text-chat-only。随后让 Agent 通过 `hwlab-cloud-api` 执行同一 M3 硬件任务，确认 agent trace 引用对应 hardware operation 和 audit。 通过标准： @@ -136,7 +136,7 @@ 出现以下情况时停止后续 live 或 mutating 测试，并在报告 issue 中标为 `BLOCKED` 或 `failed`： -- 入口不是 `16666/16667`，或命中非 HWLAB DEV runtime。 +- 入口不是 G14 DEV `17666/17667`，或命中非当前 HWLAB DEV runtime。 - 需要读取或打印 Secret/token 明文。 - 需要触碰 PROD。 - 需要重启 UniDesk、Code Queue、backend-core 或无关基础设施。 @@ -147,7 +147,7 @@ ## 稳定来源 - [architecture.md](architecture.md)：MVP 边界、M3 trusted loop 和证据等级。 -- [dev-runtime-boundary.md](dev-runtime-boundary.md)：`16666/16667`、D601 k3s 和运行态边界。 +- [dev-runtime-boundary.md](dev-runtime-boundary.md)：G14 `17666/17667`、PROD `18666/18667`、G14 k3s 和运行态边界；D601 只作 legacy 回溯。 - [cloud-workbench.md](cloud-workbench.md)：Cloud Workbench 默认首页和 UX 约束。 - [code-agent-chat-readiness.md](code-agent-chat-readiness.md)：Code Agent 真实回复和 provider/runner blocker 判定。 - [m3-loop-rollout-runbook.md](m3-loop-rollout-runbook.md)：M3 live 操作授权、证据和失败分类。 diff --git a/docs/reference/architecture.md b/docs/reference/architecture.md index 15af2bd3..1a2a5ffc 100644 --- a/docs/reference/architecture.md +++ b/docs/reference/architecture.md @@ -7,14 +7,14 @@ M3 virtual hardware trusted loop before broadening the product surface. ## MVP Boundary -- Environment: `dev`. -- Public Cloud Web entry: `http://74.48.78.17:16666/`. -- Public API/edge entry: `http://74.48.78.17:16667/`. -- Legacy public `:6666` and `:6667` are historical and must not be used as - current browser or API acceptance targets. +- Environment: `dev` on G14 for MVP runtime work; `prod` on G14 exists as the GitOps-controlled production namespace and public FRP surface. +- Current DEV Cloud Web entry: `http://74.48.78.17:17666/`. +- Current DEV API/edge entry: `http://74.48.78.17:17667/`. +- Current PROD Cloud Web/API entries: `http://74.48.78.17:18666/` and `http://74.48.78.17:18667/`. +- Legacy public `:16666/:16667`, `:6666`, and `:6667` are historical or internal-port surfaces and must not be used as current browser or API acceptance targets. - UniDesk may support scheduling, CI, or CD. It is not a HWLAB runtime substitute. -- PROD is outside the current MVP execution path. +- M3 mutating proof remains DEV-first; PROD presence is verified through GitOps, Argo sync, Deployment readiness and public health, not through hardware mutation. ## Runtime Shape @@ -24,7 +24,7 @@ is: ```text browser or CLI -> master edge / frp public ports --> D601 hwlab-dev router +-> G14 hwlab-dev or hwlab-prod namespace -> HWLAB cloud/runtime services -> gateway, simulators, patch panel, agent services ``` diff --git a/docs/reference/cloud-workbench.md b/docs/reference/cloud-workbench.md index 05c060be..8fa719e4 100644 --- a/docs/reference/cloud-workbench.md +++ b/docs/reference/cloud-workbench.md @@ -1,7 +1,7 @@ # HWLAB Cloud Workbench Reference Cloud Workbench is the default user-facing frontend at -`http://74.48.78.17:16666/`. It must serve the #99 workbench direction and the +`http://74.48.78.17:17666/`. It must serve the #99 workbench direction and the #108 UX constraints while respecting the M3 boundary from `DC-DCSN-P0-2026-003`. @@ -17,7 +17,7 @@ Cloud Workbench is the default user-facing frontend at - `/gate` and `/diagnostics/gate` are internal diagnostic aliases served by the same Cloud Web app router. They may carry Gate, blocker, and M0-M5 evidence because they are not the default homepage. -- `http://74.48.78.17:16667/` remains the API/edge boundary. +- `http://74.48.78.17:17667/` remains the API/edge boundary. - Browser data sources are same-origin `/v1`, read-only `/json-rpc`, source reports, gate reports, and blocked reports. - Code Agent conversation 使用受控同源 `POST /v1/agent/chat` 通道。直接 @@ -85,7 +85,7 @@ The #108 constraints are current baseline: ## Evidence And Labels Visible runtime or evidence state must keep `SOURCE`, `LOCAL`, `DRY-RUN`, -`DEV-LIVE`, and `BLOCKED` distinct. Loading the page from `16666` proves only +`DEV-LIVE`, and `BLOCKED` distinct. Loading the page from `17666` proves only that Cloud Web is reachable. It does not prove DB readiness, M3, M4, M5, or a hardware loop. @@ -160,7 +160,7 @@ node web/hwlab-cloud-web/scripts/check.mjs node web/hwlab-cloud-web/scripts/build.mjs node scripts/dev-cloud-workbench-smoke.mjs --static node scripts/dev-cloud-workbench-layout-smoke.mjs --static -node scripts/dev-cloud-workbench-smoke.mjs --dom-only --url http://74.48.78.17:16666/ +node scripts/dev-cloud-workbench-smoke.mjs --dom-only --url http://74.48.78.17:17666/ ``` `npm run web:check` 是 Cloud Workbench 的 repo-owned 前端检查入口。它会 @@ -180,7 +180,7 @@ for internal diagnostics. This PR-class check is intentionally source-only and does not deploy, restart services, call public DEV, or run the full live Code Agent browser journey. -Live checks against `http://74.48.78.17:16666/` are read-only and must report +Live checks against `http://74.48.78.17:17666/` are read-only and must report blocked/skip instead of false green when the browser or network path is not available. @@ -221,7 +221,7 @@ npm run web:layout:live | --- | --- | --- | | SOURCE/static | `npm run web:check` 或 `npm run web:layout` | PR/source gate 默认运行，不依赖公网 DEV。 | | local-build | `npm run web:layout:build` | Cloud Web build/publish 前运行；会先刷新本地 `dist`。 | -| DEV live | `npm run web:layout:live` | DEV deploy 后对 `http://74.48.78.17:16666/` 运行，只证明 UI layout/clickability。 | +| DEV live | `npm run web:layout:live` | DEV deploy 后对 `http://74.48.78.17:17666/` 运行，只证明 UI layout/clickability。 | 报告字段必须能定位 `status=pass|blocked|skip`、`viewport`、`selector`、 `failureType` 和 artifact 路径。当前允许的 `failureType` 包括 `overlap`、 diff --git a/docs/reference/code-agent-chat-readiness.md b/docs/reference/code-agent-chat-readiness.md index a99b15e3..d930cdd7 100644 --- a/docs/reference/code-agent-chat-readiness.md +++ b/docs/reference/code-agent-chat-readiness.md @@ -6,9 +6,9 @@ Secret 或 token。 ## 运行边界 -- DEV Cloud Web 入口是 `http://74.48.78.17:16666/`，同源代理到 +- DEV Cloud Web 入口是 `http://74.48.78.17:17666/`，同源代理到 `/v1/agent/chat`。 -- DEV API/edge 入口是 `http://74.48.78.17:16667/`；它不能替代 Workbench +- DEV API/edge 入口是 `http://74.48.78.17:17667/`；它不能替代 Workbench 同源聊天入口的真实回复证据。 - `internal/cloud/code-agent-chat.mjs` 是 `/v1/agent/chat` 的后端处理入口。 - `scripts/code-agent-chat-smoke.mjs` 是 Code Agent chat schema 与 readiness @@ -100,7 +100,7 @@ Workbench trace 对已知 JSON-RPC gateway 响应应按普通 tool call 展示 Workbench 与 Code Agent 的用户请求必须是短连接 submit + 短连接 result/trace 轮询；浏览器或 cloud-web 不应持有一次长 HTTP 请求等待整个 Codex turn 结束。`POST /v1/agent/chat` 返回 `202` 后，前端轮询 `/v1/agent/chat/result/` 获取终态，并用 `/v1/agent/chat/trace/` 刷新可视 trace。 -cloud-web 同源代理必须把短连接语义原样转发给 cloud-api，至少包括 `Prefer: respond-async`、`X-HWLAB-Short-Connection` 和 `X-Trace-Id`。如果这些 header 在 cloud-web 层被过滤，cloud-api 会把同一个请求当成长同步请求处理，用户入口会表现为 16666 卡住或代理超时，而 16667 直连 cloud-api 正常。此类问题应先比对同一 trace 在 16666 与 16667 的 submit 行为，再修代理 header 透传，而不是调大前端等待时间。 +cloud-web 同源代理必须把短连接语义原样转发给 cloud-api，至少包括 `Prefer: respond-async`、`X-HWLAB-Short-Connection` 和 `X-Trace-Id`。如果这些 header 在 cloud-web 层被过滤，cloud-api 会把同一个请求当成长同步请求处理，用户入口会表现为 `17666` 卡住或代理超时，而 `17667` 直连 cloud-api 正常。此类问题应先比对同一 trace 在 `17666` 与 `17667` 的 submit 行为，再修代理 header 透传，而不是调大前端等待时间。 `/v1/agent/chat/result/` 是终态摘要接口，不是完整 trace 下载接口。它可以携带压缩后的 `runnerTrace` 窗口用于传输保活，但 Workbench 用户界面不得把该窗口显示为“压缩窗口”或“显示全部”。只要结果或轮询快照声明 `eventsCompacted=true`，前端必须自动请求 `/v1/agent/chat/trace/` 并用完整 trace 替换可视事件线；回放完成前只能显示“完整 trace 回放中/当前已载入”状态。result 响应仍必须保留 `eventCount`、`lastEvent`、`providerTrace`、`threadId/sessionId` 和终态 reply/blocker；完整 trace 只能从 `/v1/agent/chat/trace/`、复制 JSON 或下载 trace 入口取得。默认 result trace 窗口上限由 `HWLAB_CODE_AGENT_RESULT_TRACE_EVENT_LIMIT` 控制；不要把数百个大 chunk 原样塞进 result 响应，避免 cloud-web 代理层或浏览器 fetch 把“正常执行中的大响应”表现成 503、非 JSON 或空响应。 @@ -160,7 +160,7 @@ Workbench 静态接线检查： ```sh node scripts/dev-cloud-workbench-smoke.mjs --static -node scripts/dev-cloud-workbench-smoke.mjs --dom-only --url http://74.48.78.17:16666/ +node scripts/dev-cloud-workbench-smoke.mjs --dom-only --url http://74.48.78.17:17666/ ``` 该命令验证 Workbench 默认页、同源只读边界和 `/v1/agent/chat` 前端主流程接线。它只产出 @@ -171,7 +171,7 @@ node scripts/dev-cloud-workbench-smoke.mjs --dom-only --url http://74.48.78.17:1 授权凭证注入后的真实 DEV 复测： ```sh -node scripts/code-agent-chat-smoke.mjs --live --url http://74.48.78.17:16666/ +node scripts/code-agent-chat-smoke.mjs --live --url http://74.48.78.17:17666/ ``` `--live` 会向真实 DEV `/v1/agent/chat` 发送一条最小聊天请求。输出只包含 diff --git a/docs/reference/commander-collaboration.md b/docs/reference/commander-collaboration.md index 1f4eeda6..ae4691d1 100644 --- a/docs/reference/commander-collaboration.md +++ b/docs/reference/commander-collaboration.md @@ -5,7 +5,7 @@ ## 指挥作风 - 指挥官必须亲自掌握关键一手事实，不能只依赖 runner 的二手摘要。 -- 必须亲自查看 `http://74.48.78.17:16666/` 默认首屏、`/gate` 或内部诊断页、关键 PR diff、部署 revision、DEV 验收结果和失败证据。 +- 必须亲自查看 `http://74.48.78.17:17666/` 默认首屏、`/gate` 或内部诊断页、关键 PR diff、部署 revision、DEV 验收结果和失败证据。 - 一层 Code Queue 直接执行业务实现、修复、部署和验证是允许的基层指挥模式。 - 不得把战略判断、是否偏离用户目标的判断、关键 PR 最终审查、关键部署证据审查、指挥官自我反省和指挥规则更新外派给 runner。 - 不得为了 Gate 生成 Gate、为了报告生成报告、为了审查再派审查、为了管理继续拆管理；Gate、报告、预检和观测脚本只能作为真实上线、真实 E2E 或 blocker 解除的必要最小工具。 diff --git a/docs/reference/dev-runtime-boundary.md b/docs/reference/dev-runtime-boundary.md index c6c0fafb..2b4a5636 100644 --- a/docs/reference/dev-runtime-boundary.md +++ b/docs/reference/dev-runtime-boundary.md @@ -338,8 +338,8 @@ node scripts/dev-runtime-postflight.mjs --live --confirm-dev --confirmed-non-pro ``` Default `--check` is source-only. Live mode first reads -`http://74.48.78.17:16667/health/live` and -`http://74.48.78.17:16667/v1`. `/v1` must expose only the controlled +`http://74.48.78.17:17667/health/live` and +`http://74.48.78.17:17667/v1`. `/v1` must expose only the controlled same-origin M3 IO route `/v1/m3/io` with contract `m3-io-control-v1`; generic frontend gateway/box/patch-panel access is not a valid postflight substitute. The postflight only performs the M3 diff --git a/docs/reference/dev-runtime-hotfix-runbook.md b/docs/reference/dev-runtime-hotfix-runbook.md index f6cea908..19d382a4 100644 --- a/docs/reference/dev-runtime-hotfix-runbook.md +++ b/docs/reference/dev-runtime-hotfix-runbook.md @@ -13,41 +13,45 @@ DEV runtime hotfix 只能在以下条件同时满足时使用： - 操作前已经明确该任务不会抢占 M3 虚拟硬件可信闭环主线，也不会把热修证据升级成 M3 验收。 - 操作后必须创建或关联源码化 follow-up。#465 的持久化拆分是固定分工：#460 负责 Code Agent -> PC gateway `shell.exec` 能力路由，#461 负责 hotfix runner 源码化，#462 负责本 runbook 与只读审计，#463 负责 JSON-RPC `serviceId` 结构化诊断，#464 负责 DEV-LIVE smoke/harness。 -## D601 k3s 前置 +## G14 k3s 前置 -D601 裸 `kubectl` 不可信。所有只读观测、热修、回滚和复核都必须显式指定原生 k3s kubeconfig，并先确认节点： +当前 HWLAB DEV 运行态热修目标是 G14 `hwlab-dev` namespace。所有只读观测、热修、回滚和复核必须通过 UniDesk route `G14:k3s` 进入 G14 原生 k3s，并先确认目标 namespace 与节点： ```sh -export KUBECONFIG=/etc/rancher/k3s/k3s.yaml -kubectl get nodes -o jsonpath='{.items[*].metadata.name}' +tran G14:k3s kubectl get nodes -o wide +tran G14:k3s kubectl get ns hwlab-dev hwlab-prod ``` -结果必须包含 `d601`。出现 `docker-desktop`、`desktop-control-plane`、`127.0.0.1:11700` 或第二套 `hwlab-dev` 控制面时，停止 hotfix、回滚和验收判断。此边界与 [dev-runtime-boundary.md](dev-runtime-boundary.md) 和 [g14-gitops-cicd.md](g14-gitops-cicd.md) 保持一致。 +结果必须显示 G14 原生 k3s 中存在 `hwlab-dev`；需要验证 PROD 发布面时也必须显示 `hwlab-prod`。出现 D601 kubeconfig、Docker Desktop Kubernetes、`desktop-control-plane`、`127.0.0.1:11700` 或第二套 `hwlab-dev` 控制面时，停止 hotfix、回滚和验收判断。此边界与 [dev-runtime-boundary.md](dev-runtime-boundary.md) 和 [g14-gitops-cicd.md](g14-gitops-cicd.md) 保持一致。 ## kubectl 热修命令形状 运行面热修应优先使用小补丁、短连接和远端临时文件，避免把大对象穿过 shell argv、CLI 输出截断或 `kubectl apply` 的 last-applied annotation。 -推荐的 ConfigMap data 局部覆盖方式是：在本地生成只包含本次 key 的 merge patch，通过 D601 短连接写入远端临时文件，再让 `kubectl` 从真实文件读取： +推荐的 ConfigMap data 局部覆盖方式是：在本地生成只包含本次 key 的 merge patch，通过 G14 短连接写入远端临时文件，再让 `kubectl` 从真实文件读取。示例形状必须保持短连接；具体目标 ConfigMap、Deployment 和 key 按当次 issue 填写： ```sh -node - <<'NODE' | bun scripts/cli.ts ssh D601 argv bash -lc ' +tran G14:k3s script <<'SCRIPT' set -e -export KUBECONFIG=/etc/rancher/k3s/k3s.yaml -kubectl get nodes -o jsonpath="{.items[*].metadata.name}" | grep -w d601 >/dev/null +kubectl get ns hwlab-dev >/dev/null patch_file=/tmp/hwlab-hotfix.patch.json -cat > "$patch_file" +cat > "$patch_file" <<'PATCH_JSON' +{ + "metadata": { + "annotations": { + "hwlab.pikastech.com/hotfix-reason": "" + } + }, + "data": { + "": "" + } +} +PATCH_JSON kubectl -n hwlab-dev patch configmap --type merge --patch-file "$patch_file" rm -f "$patch_file" kubectl -n hwlab-dev rollout restart deployment/ kubectl -n hwlab-dev rollout status deployment/ --timeout=180s -' -const fs = require("node:fs"); -process.stdout.write(JSON.stringify({ - metadata: { annotations: { "hwlab.pikastech.com/hotfix-reason": "" } }, - data: { "": fs.readFileSync("", "utf8") } -})); -NODE +SCRIPT ``` 固定避坑规则： @@ -56,11 +60,11 @@ NODE - 不要把大 JSON patch 放进 `kubectl patch -p "$patch"` 或 shell argv；ConfigMap 覆盖源码文件时很容易触发 `Argument list too long`。用 stdin 写远端临时文件。 - 不要把多层脚本内联穿过 `ssh -> bash -lc -> kubectl exec -> sh -lc -> node/python/powershell`。这种路径会让 heredoc、`$!`、反引号、JSON 字符串、PowerShell 管道和中文内容被不同 shell 多次解释，常见结果是实验命令还没进入 pod 就被截断或改写。 - 可靠做法是把实验逻辑沉淀为 repo-owned 脚本，或先写入远端 `/tmp/*.mjs|*.sh|*.ps1`，再用 `kubectl cp`/ConfigMap 挂载到 pod，最后用 `kubectl exec -- node /tmp/script.mjs --arg value` 或等价 argv 形态执行。只允许在外层 shell 保留短命令和固定参数，不在命令行里嵌大段 JS/PowerShell/heredoc。 -- 需要从 pod 内验证同一份实验时，优先复用同一个脚本在 D601、pod 和 CI 中运行；不要把探测逻辑在每个通道手写一遍。若必须临时写脚本，文件名包含目标和 commit，issue 中记录脚本路径、commit、命令和输出摘要。 -- pod 内部、D601 host、FRP 公网入口可能使用不同端口语义。`127.0.0.1:6667` 是 HWLAB 内部 cloud-api 常用端口，但 `6667` 属于 WHATWG bad port；Node/undici `fetch` 会在发包前直接报 `bad port`，包括临时 gateway 自己 poll `http://127.0.0.1:6667` 的场景。运行面实验脚本和 gateway 传输层必须用 Node `http/https` 原生 request，或改走公网 `http://74.48.78.17:16667` / service mesh 中不被 bad-port 拦截的入口。 +- 需要从 pod 内验证同一份实验时，优先复用同一个脚本在 G14、pod 和 CI 中运行；不要把探测逻辑在每个通道手写一遍。若必须临时写脚本，文件名包含目标和 commit，issue 中记录脚本路径、commit、命令和输出摘要。 +- pod 内部、G14 host、FRP 公网入口可能使用不同端口语义。`127.0.0.1:6667` 是 HWLAB 内部 cloud-api 常用端口，但 `6667` 属于 WHATWG bad port；Node/undici `fetch` 会在发包前直接报 `bad port`，包括临时 gateway 自己 poll `http://127.0.0.1:6667` 的场景。运行面实验脚本和 gateway 传输层必须用 Node `http/https` 原生 request，或改走公网 `http://74.48.78.17:17667` / service mesh 中不被 bad-port 拦截的入口。 - 遇到 `fetch failed`、`bad port`、公网通而 pod loopback 不通时，先判断是不是实验工具栈限制，不要立即归因 cloud-api、FRP、k3s Service 或 gateway 离线。issue 复盘要记录具体 URL、调用库、错误字符串和替代入口。 - 清理临时进程时不要用会匹配到清理脚本自身 `cmdline` 的宽泛字符串，例如 `hwlab-gateway-hotfix`；`node -e` 本身会把该字符串放进 `/proc//cmdline`。清理脚本应匹配真实入口和参数组合，并显式排除 `process.pid`，或由启动脚本写 pidfile 后按 pidfile 清理。 -- 正式 smoke/check 不在 master server 上执行。master server 只负责源码编辑、Git、日志和指挥；仓库级 `check`、`node --test`、browser/layout smoke、`web/hwlab-cloud-web/scripts/check.mjs` 等正式验证必须改在 D601 hotfix worktree、repo-owned CI 或其他获批执行面运行。 +- 正式 smoke/check 不在 master server 上执行。master server 只负责源码编辑、Git、日志和指挥；仓库级 `check`、`node --test`、browser/layout smoke、`web/hwlab-cloud-web/scripts/check.mjs` 等正式验证必须改在 G14 `/root/hwlab`、G14 k3s/Tekton、repo-owned CI 或其他获批执行面运行。 - 验证 gateway 非阻塞或长命令并发时，不要把同一路 wrapper 的长轮询 `job-status`/状态查询当作唯一证据；忙碌 gateway 可能把后续短状态查询和只读调用一起排队，导致“状态检查卡住”掩盖真实根因。优先使用 repo-owned probe：保持一个慢命令在飞，再提交一个短命令测量 quick path 延迟；完成态判断优先读 job state/log/artifact 时间戳或 quick path 结果，而不是重复发同一路长轮询。 - 不要对已经很大的 hotfix ConfigMap 使用 `kubectl apply -f -`；`apply` 会尝试写入 `kubectl.kubernetes.io/last-applied-configuration`，可能超过 Kubernetes annotation 256 KiB 限制。局部更新用 `patch --type merge --patch-file`。 - 多文件运行面覆盖第一次创建 ConfigMap 时也不要默认用 `kubectl apply -f -`；如果 data 可能超过 annotation 限制，先 `kubectl delete configmap --ignore-not-found`，再 `kubectl create configmap --from-file=...`，随后用 Deployment annotation 记录 hotfix 版本并 rollout。正式 CD 收口时必须删除这些 unmanaged ConfigMap/volumeMount，不让热修覆盖继续漂在运行面。 diff --git a/docs/reference/documentation-governance.md b/docs/reference/documentation-governance.md index af91c5a3..1be17706 100644 --- a/docs/reference/documentation-governance.md +++ b/docs/reference/documentation-governance.md @@ -53,7 +53,7 @@ - `#121` 要求 issue 和长期文档中文化。 - `#122` 要求用户和参谋反馈默认高优先级并挂到 `#7`。 - `#123` 要求 docs-spec 规则固化进 HWLAB 长期参考文档，而不是只在 issue 里引用外部 skill；本文就是该规则的等价本地文档。 -- 当前 HWLAB 的 `16666/16667`、D601 工作区、M3 证据、Cloud Workbench 默认路由和 PR 工作流，分别由本目录的专项 reference 维护。 +- 当前 HWLAB 的 G14 DEV `17666/17667`、G14 PROD `18666/18667`、G14 工作区、M3 证据、Cloud Workbench 默认路由和 PR 工作流，分别由本目录的专项 reference 维护；D601 只作为 legacy 迁移/事故回放口径维护。 ## docs-spec 原文副本 diff --git a/docs/reference/gateway-outbound-demo.md b/docs/reference/gateway-outbound-demo.md index 827f9c0e..5c860291 100644 --- a/docs/reference/gateway-outbound-demo.md +++ b/docs/reference/gateway-outbound-demo.md @@ -31,7 +31,7 @@ Gateway 必须在 registration payload 和 `/v1/gateway/sessions` 中暴露 `inf | 变量 | 作用 | | --- | --- | -| `HWLAB_GATEWAY_CLOUD_URL` | cloud-api 或 edge-proxy 地址；本地可用 `http://127.0.0.1:6667`，DEV 可用 `http://74.48.78.17:16667`。 | +| `HWLAB_GATEWAY_CLOUD_URL` | cloud-api 或 edge-proxy 地址；本地可用 `http://127.0.0.1:6667`，当前 G14 DEV 可用 `http://74.48.78.17:17667`。 | | `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`。 | @@ -60,14 +60,14 @@ 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`，用于规避本地代理误触发。 -- 对 D601 pod 内部 `127.0.0.1:6667` 或 service `:6667` 做 Node 探测时，不要用 Web/undici `fetch`；`6667` 属于 WHATWG bad port，Node 会直接报 `bad port`。gateway 传输层和 repo-owned 探测脚本应使用 `http/https` 原生 request，公网 `:16667` 或浏览器入口不受这个限制。 +- 对 G14 pod 内部 `127.0.0.1:6667` 或 service `:6667` 做 Node 探测时，不要用 Web/undici `fetch`；`6667` 属于 WHATWG bad port，Node 会直接报 `bad port`。gateway 传输层和 repo-owned 探测脚本应使用 `http/https` 原生 request，公网 `:17667` 或浏览器入口不受这个限制。 ## DEV 使用 DEV cloud-api 部署包含 `/v1/gateway/*` 后，Windows gateway 可用以下方式主动连接： ```powershell -$env:HWLAB_GATEWAY_CLOUD_URL="http://74.48.78.17:16667" +$env:HWLAB_GATEWAY_CLOUD_URL="http://74.48.78.17:17667" $env:HWLAB_GATEWAY_ID="gtw_windows_1" $env:HWLAB_GATEWAY_SESSION_ID="gws_gtw_windows_1" $env:HWLAB_GATEWAY_CMD_EXEC_ENABLED="1" diff --git a/docs/reference/m3-loop-rollout-runbook.md b/docs/reference/m3-loop-rollout-runbook.md index dc8c32a4..54140f87 100644 --- a/docs/reference/m3-loop-rollout-runbook.md +++ b/docs/reference/m3-loop-rollout-runbook.md @@ -13,8 +13,8 @@ restart, or heavyweight e2e run. M3 is a DEV-only trusted-loop acceptance path, not a generic deployment or front-end acceptance path. -- Public frontend boundary: `http://74.48.78.17:16666/`. -- Public API/edge boundary: `http://74.48.78.17:16667/`. +- Public frontend boundary: `http://74.48.78.17:17666/`. +- Public API/edge boundary: `http://74.48.78.17:17667/`. - Historical public `:6666` and `:6667` endpoints are not current acceptance targets; internal k3s services may still use `6667`. - Runtime intent and artifact identity are reviewed through @@ -82,7 +82,7 @@ wiring are all observed. | Step | What to observe | Must have evidence | Failure class | Must not misread | | --- | --- | --- | --- | --- | -| 1 | Confirm the public DEV boundary and frozen route. | `http://74.48.78.17:16666` for frontend, `http://74.48.78.17:16667` for API/edge, internal `6667` only as a k3s port, and the checked-in docs or checklist that freeze those values. | `environment_blocker` | Do not treat legacy `:6666` or public `:6667` as acceptance targets. | +| 1 | Confirm the public DEV boundary and frozen route. | `http://74.48.78.17:17666` for frontend, `http://74.48.78.17:17667` for API/edge, internal `6667` only as a k3s port, and the checked-in docs or checklist that freeze those values. | `environment_blocker` | Do not treat legacy `:16666/:16667`, legacy `:6666`, or public `:6667` as acceptance targets. | | 2 | Confirm two box simulators and two gateway simulators are present and distinct. | Two observable `hwlab-box-simu` identities, two observable `hwlab-gateway-simu` identities, their resource/session IDs, and the shared DEV project. | `runtime_blocker` | Do not infer cardinality from one box, one gateway, or fixture-only output. | | 3 | Confirm one patch panel owns the route. | `hwlab-patch-panel` status, wiring, and the active connection from `res_boxsimu_1:DO1` to `res_boxsimu_2:DI1`. | `runtime_blocker` | Do not accept box loopback, direct box mutation, or a UI state edit as routing proof. | | 4 | Confirm the live loop operation. | Operation ID, trace ID, audit ID, and evidence ID tied to `res_boxsimu_1:DO1 -> hwlab-patch-panel -> res_boxsimu_2:DI1`. | `runtime_blocker` | Do not promote SOURCE, LOCAL, DRY-RUN, or edge-only evidence to PASS. |