docs: 收编 HWLAB reference 到 OA 规格

2026-06-15 08:02:06 +00:00
parent 1952014e90
commit ad52c7c779
15 changed files with 310 additions and 7 deletions
@@ -112,6 +112,8 @@ HWPOD服务应把已授权且租约一致的操作请求路由到正确 HWPOD no

 节点路由必须禁止错误 HWPOD 复用。工具请求某个 `hwpod-id` 时，服务端只能使用该资源声明绑定的 node 和能力；无法找到声明或路由时必须返回明确失败。

+HWPOD 服务端只作为云端请求接收、租约校验、目标解析和网关路由 authority；Cloud Web、Agent 和 CLI 不应直接连接用户 PC 上的 gateway。网关主动出站后，服务端仍必须把命令领取、in-flight、超时、`gateway_busy` 和节点返回失败归一为可查询的 operation 状态，避免调用方把 HTTP dispatch timeout 误判为硬件动作结果。
+
 ### 6.4 HWPOD-SVC-REQ-004 结果归属

 | 编号 | 短名 | 主责模块 | 关联模块 |
@@ -56,6 +56,9 @@ AI网关负责靠近真实硬件执行受控动作并回传原始硬件事实，
 | adapter | 网关侧执行某类硬件动作的适配器，例如 debug probe、UART、board-comm、ioProbe 或 CANopen。 |
 | board-comm | 通过板侧通信协议访问目标固件接口的能力，可包含 JSON-RPC over TCP 等形态。 |
 | CANopen SDO | 通过 CANopen Service Data Object 读写设备对象字典的协议动作。 |
+| 主动出站 | 网关从用户 PC 或本地环境主动连接云端 HWPOD 服务领取命令，云端不需要入站访问用户网络。 |
+| in-flight 请求 | 网关已领取并在后台执行、尚未完成回传的长命令或硬件动作。 |
+| gateway_busy | 网关达到并发上限或暂时无法领取新操作时返回的结构化忙碌状态。 |
 | 安全恢复 | 在写操作前后把真实设备恢复到可继续使用状态的 reset、重新连接或清理输出能力。 |
 | 原始硬件事实 | 由节点直接观测或执行得到的协议响应、板外读数、probe 结果和错误语义。 |

@@ -66,9 +69,9 @@ AI网关负责靠近真实硬件执行受控动作并回传原始硬件事实，
 | 边界项 | 内容 |
 | --- | --- |
 | 外部使用者 | HWPOD服务、HWPOD工具、Agent编排、HarnessRL、平台管理员。 |
-| 外部输入 | 服务端路由请求、HWPOD spec 摘要、租约上下文、adapter 参数、workspace 路径、probe UID、通信端点和超时。 |
-| 受控资源 | HWPOD node、adapter、debug probe、UART、board-comm 连接、ioProbe、CANopen 通道、电压/电流/频率通道和节点日志摘要。 |
-| 外部输出 | 心跳、能力上报、健康状态、adapter 结果、原始硬件事实、恢复结果和错误分类。 |
+| 外部输入 | 服务端路由请求、HWPOD spec 摘要、租约上下文、adapter 参数、workspace 路径、probe UID、通信端点、超时和网关命令执行策略。 |
+| 受控资源 | HWPOD node、主动出站连接、in-flight 请求、adapter、debug probe、UART、board-comm 连接、ioProbe、CANopen 通道、电压/电流/频率通道和节点日志摘要。 |
+| 外部输出 | 心跳、能力上报、健康状态、in-flight 摘要、adapter 结果、原始硬件事实、恢复结果、`gateway_busy` 和错误分类。 |
 | 用户接口 | HWPOD node 协议、网关执行 API、节点侧工具适配器、board-comm/ioProbe 原始接口。 |
 | 系统边界 | AI网关负责真实硬件动作执行和原始事实生产；不拥有服务端资源真相、用户权限、客户端体验或 Harness 评价语义。 |

@@ -93,6 +96,8 @@ AI网关应上报节点心跳、能力、健康、可用性和运行形态，使

 节点健康必须覆盖 adapter 可用性，而不只是进程在线。debug probe、board-comm 端点、ioProbe、CANopen 通道或恢复能力不可用时，应以能力级状态暴露给服务端。

+AI网关默认采用主动出站连接模式：用户 PC、本地 gateway 或硬件盒子主动连接云端 HWPOD 服务并领取命令，云端不要求入站访问用户网络。网关注册和会话状态应暴露当前 in-flight 数量、并发上限和主要执行摘要，使一个长 Keil、下载或 Windows 命令不会遮蔽节点是否仍在心跳、是否仍能处理短状态查询。
+
 ### 6.2 HWPOD-GW-REQ-002 适配器执行

 | 编号 | 短名 | 主责模块 | 关联模块 |
@@ -103,6 +108,8 @@ AI网关应按 HWPOD spec 声明执行 debug、download、reset、UART、board-c

 适配器执行必须先确认目标身份和声明能力。对于真实频率源链路，网关应能把控制侧写入、板侧读回和外部电流/频率观测区分为不同事实来源。

+长时间执行的适配动作应作为网关内 in-flight 请求后台推进，poll loop 仍继续处理心跳、job-status、日志读取、取消和诊断请求。达到并发上限时，网关应返回结构化 `gateway_busy`，不得把请求静默排队到云端 dispatch timeout 后才暴露失败。
+
 ### 6.3 HWPOD-GW-REQ-003 安全恢复

 | 编号 | 短名 | 主责模块 | 关联模块 |
@@ -104,6 +104,8 @@ run 和 command 必须短返回并可后续轮询。业务客户端不得依赖

 Manager 只执行通用 schema、allowlist、idempotency、secret scope 和 executionPolicy 范围检查，不内建 HWLAB 用户角色、HWPOD 授权或 UniDesk 业务策略。业务授权由调用方完成后再委托 AgentRun，AgentRun 保存可审计字段和失败事实。

+Manager 公共 API 应采用短连接 JSON resource 形态表达 runs、commands、events、results、sessions、backends 和 health。长时间模型工作通过资源状态和分页 events 查询，不通过 SSE、WebSocket、长同步 HTTP 或 runner stdout 作为唯一完成信号。CLI 和业务客户端应调用同一 REST resource API；debug 命令可以暴露更小切片，但不得维护平行 mock-only 路径。
+
 ### 6.3 AR-CORE-REQ-003 Runner Claim 与回写

 | 编号 | 短名 | 主责模块 | 关联模块 |
@@ -125,6 +125,8 @@ Runtime装配应支持 SessionRef 到 backend thread/cache 的稳定映射，并

 Session PVC 只保存 Codex rollout 会话文件；provider Secret、完整 `CODEX_HOME`、Git workspace、auth/config、state sqlite、tmp 和 skills 不进入 PVC。runner replacement 必须复用同一 sessionId、threadId、profile 和 PVC；不得通过新 session、拼接历史 prompt 或伪造 resume 形成续跑表象。

+SessionRef 是 Web、CLI、Queue 和 HWLAB接入共享的会话连续性 authority。普通 follow-up、steer 和 result 轮询必须沿用同一 sessionId/threadId/profile/PVC 映射；session 不存在、failed、stale、canceled 或 PVC 不可用时，应返回结构化 blocker。Runtime装配不得自动创建替代 session，也不得把业务 conversationId、workspace project 或浏览器缓存当作 AgentRun session truth。
+
 ### 6.5 AR-RUNTIME-REQ-005 AipodSpec 声明式装配

 | 编号 | 短名 | 主责模块 | 关联模块 |
@@ -55,6 +55,7 @@
 | backendProfile | run 中选择的 provider/profile slug，例如 `codex`、`deepseek`、`minimax-m3`、`dsflash-go` 或动态 slug。 |
 | backendKind | backend 协议实现类型；`v0.1` 固定使用 `codex-app-server-stdio`。 |
 | Codex stdio backend | 通过 `codex app-server --listen stdio://` 执行 JSON-RPC over stdio turn 的 backend kind。 |
+| client request | Codex app-server stdio 协议中由 app-server 发给 runner client、需要显式响应的 JSON-RPC 请求。 |
 | Provider Profile 管理 | Manager 提供的服务端委托 API，用于 profile 状态查询、API key/config 写入和 canary 验证。 |
 | profile isolation | 不同 profile 的 SecretRef、CODEX_HOME、model、model catalog 和 upstream 配置互不污染。 |
 | model-catalog | `dsflash-go` 等 profile 使用的模型目录文件，用于声明模型元数据和上下文能力。 |
@@ -104,6 +105,10 @@ Adapter 输入必须来自 manager 持久化后的 run/command 和 RuntimeAssemb

 直接 Responses HTTP、OpenAI SDK wrapper、`codex exec` 一次性输出、fake provider、固定文本回复或本地 shell 模拟不能作为正式 backend 实现或综合联调通过证据。裸 HTTP 或 `codex exec --json` 只能作为 provider/upstream 诊断辅助。

+Codex stdio backend 必须把 app-server 发来的 JSON-RPC client request 当作一等协议处理，不能只等待 notification。request id 可以是数字或字符串；approval、tool input、elicitation 和未知 client request 都必须得到结构化响应，并追加可审计 trace event。忽略 client request 会让真实 assistant partial output 卡在等待状态，不能被包装成 completed。
+
+命令执行 trace 必须由 backend/result 层做有界裁剪和摘要，保留 command bytes、output bytes、truncated 标记、stderr 摘要和可展开入口。前端、CLI 或 prompt 不应要求 Code Agent 默认给 shell 命令加 `head`、`grep` 或管道来避免输出过长；输出裁剪属于 trace/result 表达职责，不是工具调用完成条件。
+
 ### 6.3 AR-BACKEND-REQ-003 Profile 隔离与切换

 | 编号 | 短名 | 主责模块 | 关联模块 |
@@ -57,6 +57,7 @@ HWLAB接入负责把 HWLAB Cloud API、Workbench、CLI、HWPOD 运行上下文
 | result envelope | AgentRun command result 的结构化输出，包含 status、terminalStatus、reply、failureKind、events 和 artifact 摘要。 |
 | HWPOD runtime context | HWLAB dispatcher 为单次 runner job 提供的 owner-scoped 硬件运行上下文。 |
 | transientEnv | 单次 runner job 的短期 env 上下文，由 AgentRun 转为短期 Secret 投影并脱敏输出。 |
+| 自然语言单一路由 | `/v1/agent/chat` 中自然语言请求统一进入 AgentRun Code Agent turn，不由 Cloud API 做关键词分流或文本 fallback。 |

 ## 4. 系统边界和接口

@@ -80,6 +81,7 @@ HWLAB接入负责把 HWLAB Cloud API、Workbench、CLI、HWPOD 运行上下文
 | PJ2026-01020503 | 结果映射 | 本规格 6.3 | events/result/terminal/failureKind 到 HWLAB trace/result | AgentRun Core、Backend Profile | 客户端、HarnessRL |
 | PJ2026-01020504 | 硬件上下文 | 本规格 6.4 | HWPOD/runtime transientEnv 和 tool credential 边界 | 硬件池、Runtime装配 | Runner job、Agent 执行 |
 | PJ2026-01020505 | 取消续跑 | 本规格 6.5 | durable cancel、SessionRef 和 same-run multi-command 接入 | Queue会话、Runtime装配 | HWLAB Workbench、CLI |
+| PJ2026-01020506 | 单一路由 | 本规格 6.6 | 自然语言请求统一委托 AgentRun Code Agent，显式控制 API 不截获聊天 | API契约、Backend Profile、Runtime装配 | Web工作台、HWLAB CLI |

 ## 6. 原子需求

@@ -132,3 +134,13 @@ AgentRun 只负责投影、脱敏和限制扩散，不解释 HWPOD 权限，也
 HWLAB接入应使用 AgentRun durable cancel、SessionRef、thread continuation 和 same-run multi-command loop 实现用户可见的取消、follow-up、steer 和续跑。

 取消必须幂等并写入 command/run 状态与 event；pending command 被取消后不得再创建 runner Job。会话续跑只认标准 SessionRef/threadId；无法续接时必须返回明确失败事实，不能拼接历史 prompt 或伪造继续会话。
+
+### 6.6 AR-HWLAB-REQ-006 自然语言单一路由
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| AR-HWLAB-REQ-006 | 单一路由 | PJ2026-01020506 单一路由 | [PJ2026-010403 API契约](PJ2026-010403-api-contract.md)、[后端Profile](PJ2026-010204-backend-profile.md)、[Runtime装配](PJ2026-010202-runtime-assembly.md) |
+
+HWLAB接入应把 `/v1/agent/chat` 的自然语言请求统一委托给 AgentRun Code Agent turn。Cloud API 只负责用户鉴权、显式 session、RuntimeAssembly 输入、trace/result 映射和结构化 blocker，不根据关键词把自然语言请求短路到 M3 Skill CLI、HWPOD shortcut、外网检查、普通 OpenAI 文本回复或其他旧路径。
+
+显式 `/v1/m3/io`、HWPOD node-ops、gateway 诊断或管理 API 可以作为独立控制面存在，但不得自动截获聊天自然语言。AgentRun Code Agent 不具备运行条件时，HWLAB接入应返回 AgentRun readiness blocker；不能降级为 source-only、mock、文本解释或历史 fixture。
@@ -115,6 +115,10 @@ Web工作台应让用户在主任务区直接选择或创建会话、阅读用

 会话输入只负责用户可见的交互和消息呈现。基本 Agent 调用必须进入 Agent编排提供的执行生命周期，并返回用户可查询的 run、command、session 或等价状态入口；用户权限和会话有效性由用户管理提供。单条用户消息、trace 详情或状态摘要不得在默认视图中抢占主任务区，使用户难以继续输入。

+Web工作台必须使用显式 Agent session：无 session 时先让用户创建或选择 session，session failed、stale 或 canceled 时保留失败状态并要求用户显式切换或新建。刷新页面、重新打开工作台或短连接 result 轮询只能恢复已选 session、thread 和 trace 状态；除非用户登出或主动清空对话，不得自动生成新 conversation、替换 session 或用历史 prompt 拼接出续跑表象。
+
+Agent 请求应采用短连接 submit 加 result/trace 轮询。`POST /v1/agent/chat` 或等价入口返回执行标识后，工作台通过 result 和 trace path 获取终态与可读过程，不持有一次长 HTTP 请求等待整个模型 turn。后端 result 已完成时，消息卡片必须替换为真实 final response；仍在 pending 或 trace 缺失时应显示明确状态，而不是把“result ready for polling”类中间文本当作最终回复。
+
 ### 6.3 CLIENT-WB-REQ-003 诊断反馈

 | 编号 | 短名 | 主责模块 | 关联模块 |
@@ -145,6 +149,8 @@ Web工作台应与 HWLAB CLI 共享 Code Agent composer policy、trace renderer

 Web只负责浏览器交互与展示；CLI负责命令入口和结构化输出；API契约负责 path、schema 和错误语义；Agent编排负责执行事实。Web trace row 错乱、final response 缺失或发送状态异常等问题，应能先通过 CLI `trace --render web`、同源 request/rpc 和显式 Agent session 命令定位到共享 renderer、API 契约或浏览器表现层，不能让 Web 和 CLI 各自维护一套 trace 解释。

+工作台在增量刷新 trace、message 或 status 时，应保持用户已展开的详情状态和滚动位置。trace 压缩、sourceSeq 窗口或 event cap 只能影响默认摘要，不得吞掉可读 message、tool call、stderr/error 或 terminal 边界；需要完整回放时，Web 应通过 trace/result API 主动请求完整可读事件，而不是让用户手工从原始日志中恢复上下文。
+
 ### 6.6 CLIENT-WB-REQ-006 Trace阅读

 | 编号 | 短名 | 主责模块 | 关联模块 |
@@ -117,6 +117,8 @@ HWLAB CLI 应提供显式 Code Agent session 创建、选择、状态、send、c

 普通 `send` 必须绑定显式 session 或已显式选中的 session；session 缺失、failed、stale 或 canceled 时，CLI 应返回结构化 blocker 和下一步命令，不得自动创建、滚动或替换 session。AgentRun 执行生命周期和 provider profile runtime 事实仍由 Agent编排负责。

+CLI 的 Agent 会话入口应以短连接资源操作为默认形态：创建、send、steer、cancel 快速返回 session、run、command、traceId 或下一步命令；完整模型 turn 通过 result/trace/status 轮询读取。CLI 不得为了“看起来像聊天”而长期阻塞等待 runner 完成，也不得在无 session 时用本地历史或默认 thread 静默续接。
+
 ### 6.4 CLIENT-CLI-REQ-004 Trace 与结果

 | 编号 | 短名 | 主责模块 | 关联模块 |
@@ -127,6 +129,8 @@ HWLAB CLI 应提供 result、trace、inspect 和 Web renderer 等入口，使用

 `trace --render web` 必须与 Web 工作台共享 trace row 语义，并支持默认摘要、sourceSeq 窗口、tail、tool summary 和完整展开。CLI 只呈现同一路径的 trace/result，不重新发明 final response、AgentRun events 过滤或 CaseRun aggregate 语义。

+CLI 默认输出应低噪声且可继续操作：终端命令只显示状态、标识符、摘要和下一步命令，`--full` 或 `--raw` 才展开完整事件、原始 envelope 或长输出。trace/result 缺失、events capped、partial assistant、provider blocker 或 session 不可用都应结构化表达，不能把 stdout 尾部、transport close 或已有 assistant delta 当作 completed。
+
 ### 6.5 CLIENT-CLI-REQ-005 全流程 CLI 复验

 | 编号 | 短名 | 主责模块 | 关联模块 |
@@ -126,6 +126,8 @@ API契约应定义 workbench workspace、Admin Access、provider profile、HWPOD

 资源与管理接口只定义调用形态和字段稳定性。HWPOD node-ops 的硬件语义归硬件池，provider profile runtime 归 Agent编排，权限和账号归用户管理，运行健康和公开入口归平台运维。

+Gateway 相关 API 只允许作为云端同源入口暴露：用户、Agent 或 smoke 调用 Cloud API / API契约中的 gateway/HWPOD path，由 HWPOD 服务再路由到主动出站的 AI 网关。API契约不得要求客户端直接访问用户 PC gateway，也不得把 gateway 本地端口、内网地址或临时 poll URL 写入正式客户端输出。
+
 ### 6.5 CLIENT-API-REQ-005 错误与输出合同

 | 编号 | 短名 | 主责模块 | 关联模块 |
@@ -83,8 +83,8 @@
 | PJ2026-010601 | 发布流水 | [PJ2026-010601 发布流水](PJ2026-010601-controlled-release.md) | CI/CD、PipelineRun、image、rollout、trigger-current 和发布状态 | Git commit、镜像配置、各 L1 发布需求 | 全部 L1 |
 | PJ2026-010602 | 源码同步 | [PJ2026-010602 源码同步](PJ2026-010602-source-sync.md) | Git mirror、source commit authority、bundle/mirror URL 和 lane source truth | Git remote、运行 lane、Agent 资源装配需求 | Agent编排、HarnessRL、客户端 |
 | PJ2026-010603 | YAML-first运维 | [PJ2026-010603 YAML运维](PJ2026-010603-yaml-first-ops.md) | YAML-first 自动化分布式运维；SecretRef、targetKey、fingerprint 是其密钥分发子项 | 各 L1 配置需求、密钥来源 | 全部 L1 |
-| PJ2026-010604 | 公开入口 | 本规格 6.4 | FRP、Caddy、domain、TLS、public health 和入口漂移处理 | 客户端/API 服务、运行 lane | 客户端、用户管理、Agent编排 |
-| PJ2026-010605 | 运维监控 | 本规格 6.5 | Prometheus metrics、scrape target、alert rule、服务健康指标和资源指标 | 运行面 metrics endpoint、各 L1 服务健康指标 | 全部 L1 |
+| PJ2026-010604 | 公开入口 | [PJ2026-010604 公开入口](PJ2026-010604-public-entry.md) | FRP、Caddy、domain、TLS、public health 和入口漂移处理 | 客户端/API 服务、运行 lane | 客户端、用户管理、Agent编排 |
+| PJ2026-010605 | 运维监控 | [PJ2026-010605 运维监控](PJ2026-010605-observability-monitoring.md) | Prometheus metrics、scrape target、alert rule、服务健康指标和资源指标 | 运行面 metrics endpoint、各 L1 服务健康指标 | 全部 L1 |

 ## 6. 原子需求

@@ -124,7 +124,7 @@ YAML-first 运维的命令输出只能披露摘要、对象名、key 名、sourc

 | 编号 | 短名 | 主责模块 | 关联模块 |
 | --- | --- | --- | --- |
-| OPS-L1-REQ-004 | 公开入口 | PJ2026-010604 公开入口 | [客户端](PJ2026-0104-client.md)、[用户管理](PJ2026-0105-user-management.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) |
+| OPS-L1-REQ-004 | 公开入口 | [PJ2026-010604 公开入口](PJ2026-010604-public-entry.md) | [客户端](PJ2026-0104-client.md)、[用户管理](PJ2026-0105-user-management.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) |

 平台运维应提供公开入口支撑能力，使 HWLAB 的 Web、API 和管理入口能够通过正确的 FRP、Caddy、域名、TLS 和 health 目标暴露到外部。

@@ -134,7 +134,7 @@ YAML-first 运维的命令输出只能披露摘要、对象名、key 名、sourc

 | 编号 | 短名 | 主责模块 | 关联模块 |
 | --- | --- | --- | --- |
-| OPS-L1-REQ-005 | 运维监控 | PJ2026-010605 运维监控 | [Agent编排](PJ2026-0102-agent-orchestration.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[客户端](PJ2026-0104-client.md)、[用户管理](PJ2026-0105-user-management.md) |
+| OPS-L1-REQ-005 | 运维监控 | [PJ2026-010605 运维监控](PJ2026-010605-observability-monitoring.md) | [Agent编排](PJ2026-0102-agent-orchestration.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[客户端](PJ2026-0104-client.md)、[用户管理](PJ2026-0105-user-management.md) |

 平台运维应提供基于 Prometheus 的运维监控能力，使 HWLAB 运行面能够通过 metrics endpoint、scrape target、alert rule 和服务健康指标表达服务状态与资源状态。

@@ -97,6 +97,8 @@

 具体服务的 lane 固定值、历史口径废弃项和运行面名称应写入对应服务专项规格；通用发布流水只定义隔离、受控入口、可追溯和不可绕过原则。

+CI/CD 目标必须由当前 issue、PR、CLI 参数或受控 lane 配置解析为明确 node + lane。G14 DEV/PROD、G14 v0.2、D601 v0.3 和后续 lane 都只是实例，不得把某个节点、namespace、GitOps path、FRP 端口或历史 `dev/prod` 口径写成通用默认。发布流水只能作用于被选中的 node/lane，不接管其他运行面。
+
 ### 6.2 OPS-RELEASE-REQ-002 镜像与 Promotion

 | 编号 | 短名 | 主责模块 | 关联模块 |
@@ -107,6 +109,8 @@

 需要 work-ready env image 的服务应在自身专项规格中声明工具和依赖要求；通用发布流水只保证镜像来源、digest、promotion 和运行面引用可追溯，不替业务模块定义运行时功能。

+Artifact catalog 的 per-service provenance 是镜像 digest 的身份证明，必须能说明 source commit、component input hash、Containerfile hash、build args hash、base image identity、reuse/build 状态和最终 digest。复用旧 artifact 前必须能证明旧 digest 对应的 source tree 与本轮输入一致；缺 digest、缺 provenance 或 hash 不一致时应重新发布，不得用旧 guard、历史 PipelineRun 成功或 mutable tag 伪装通过。
+
 ### 6.3 OPS-RELEASE-REQ-003 发布一致性判定

 | 编号 | 短名 | 主责模块 | 关联模块 |
@@ -106,6 +106,8 @@ mirror 输出应能说明 owner/repo、read URL、write URL、cache 状态和同

 具体服务的固定 source worktree、branch、remote 和历史废弃路径写入对应服务专项规格。开始开发、文档落库、发布或 render 前必须确认 source truth；临时 clone、运行副本、旧 worktree 或 master server 缓存不能替代它。

+node/lane source truth 必须与当前任务目标一致。D601 legacy、G14 legacy、retired workspace、runner checkout、pod 内副本和一次性迁移目录只能作为对照或历史来源；当 issue/CLI 选择 D601 v0.3、G14 v0.2 或其他正式 lane 时，预检、文档落库、render、发布和验收都应从该 lane 的固定 source worktree 和 branch 开始。
+
 ### 6.3 OPS-SOURCE-REQ-003 GitOps 与 Artifact Catalog

 | 编号 | 短名 | 主责模块 | 关联模块 |
@@ -116,6 +118,8 @@ mirror 输出应能说明 owner/repo、read URL、write URL、cache 状态和同

 GitOps 输出应能追溯 source commit、runtime path、image digest、manifest revision 和 artifact catalog path。source branch 不应包含 CI 自动构造物、runtime dump、Secret data 或临时报告。

+GitOps branch 只保存目标运行面 desired state 和 artifact catalog，不承载需求规格、阶段报告或手工 hotfix 过程记录。source branch 中的人写配置、源码和 OA 交叉引用是长期真相；GitOps promotion 产物不得被反向同步为 source truth。
+
 ### 6.4 OPS-SOURCE-REQ-004 GitBundle Source Authority

 | 编号 | 短名 | 主责模块 | 关联模块 |
@@ -111,6 +111,8 @@ YAML运维应提供 target、lane、node、service、namespace 和默认目标

 目标解析必须把默认值来源解释清楚，并允许操作人员显式指定 node 或 lane 覆盖默认选择。不同服务不得各自维护一套硬编码 G14、v0.1、namespace 或 service 名称；新增服务应复用同一类解析模式。

+当 issue、PR 或 CLI 已经明确 node/lane 时，YAML 解析只负责校验和解释该目标，不得用全局默认覆盖用户选择。没有明确目标时，CLI 可以读取 YAML default，但输出必须说明 default 来源、目标 node/lane、namespace、source truth 和公开入口，避免把历史 G14/v0.2、D601 legacy 或旧 `dev/prod` 口径误用为当前运行面。
+
 ### 6.3 OPS-YAML-REQ-003 Secret 绑定与敏感输出

 | 编号 | 短名 | 主责模块 | 关联模块 |
@@ -0,0 +1,126 @@
+# PJ2026-010604 公开入口
+
+## 修改历史
+
+| 版本 | 对应 commit id | 更新日期 | 变更说明 |
+| --- | --- | --- | --- |
+
+当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。
+
+## 正文
+
+## PJ2026-010604 公开入口需求规格
+
+## 1. 文档控制
+
+| 字段 | 内容 |
+| --- | --- |
+| 编号 | PJ2026-010604 |
+| 短名 | 公开入口 |
+| 层级 | L2 课题 |
+| 状态 | 已生效 |
+| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
+| 上级规格 | [PJ2026-0106 平台运维](PJ2026-0106-platform-ops.md) |
+| 规格治理索引 | [规格治理](spec-governance.md) |
+
+本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 HWLAB 公开入口的稳定使命、范围、术语、系统边界、内部分工和原子需求。
+
+## 2. 目的和范围
+
+### 2.1 目的
+
+公开入口负责把 HWLAB 目标 node/lane 的 Web、API、health 和必要管理入口通过受控 FRP、Caddy、域名、TLS 和 public URL 暴露给用户、内测执行者和自动化验收入口。
+
+本课题的目标状态是：正式用户入口来自 YAML 声明和受控状态查询，浏览器、CLI、测试大纲和 issue 复现都使用同一公开入口；实现端口、ClusterIP、node port、历史 FRP 端口和临时域名只作为诊断或迁移对照，不反向成为用户入口真相。
+
+### 2.2 范围内
+
+- node/lane Web public URL、API public URL、health URL 和 TLS 域名归属。
+- FRP remote port、Caddy route、managed block、DNS/TLS、public health 和入口漂移处理。
+- 同一公开入口下 Web route、API path、health path 的边界说明。
+- 公开入口状态、渲染目标、健康探针和失败摘要的受控输出。
+
+### 2.3 范围外
+
+- Web 页面布局、SPA route fallback 和用户交互归 [PJ2026-010401 Web工作台](PJ2026-010401-web-workbench.md)。
+- HTTP API path、JSON envelope、错误语义和同源路由归 [PJ2026-010403 API契约](PJ2026-010403-api-contract.md)。
+- 用户登录、API key、组织和权限归 [用户管理](PJ2026-0105-user-management.md)。
+- Agent、HWPOD、CaseRun 或业务接口的成功标准不由公开入口定义。
+- 具体域名、端口、证书文件、FRP 配置值和 Caddy upstream 数值以 YAML/config 和受控状态为准，不在本规格硬编码。
+
+## 3. 术语表
+
+| 术语 | 定义 |
+| --- | --- |
+| 公开入口 | 用户或自动化从外部访问 HWLAB 的 Web/API/health 地址集合。 |
+| public URL | YAML 和受控状态查询声明的正式外部 URL。 |
+| FRP | 将目标 node/lane 内部服务暴露到公网入口的反向代理通道。 |
+| Caddy managed block | 由受控 CLI 管理的 Caddy 配置片段，只更新所属服务块，不整文件覆盖共享配置。 |
+| public health | 通过公开入口访问的健康检查，证明入口链路到达目标运行面。 |
+| 入口漂移 | 文档、YAML、Caddy、FRP、DNS、TLS 或运行面状态之间的入口目标不一致。 |
+
+## 4. 系统边界和接口
+
+| 边界项 | 内容 |
+| --- | --- |
+| 外部使用者 | 硬件研发用户、内测用户、平台管理员、Web/CLI 自动化验收任务。 |
+| 外部输入 | node/lane 选择、YAML publicExposure、Web/API 服务声明、health path、domain/TLS/FRP/Caddy 配置请求。 |
+| 受控资源 | FRP client/server 配置、Caddy route、DNS/TLS 目标、public URL、public health 探针和入口状态摘要。 |
+| 外部输出 | Web public URL、API public URL、health URL、入口健康状态、漂移摘要和 redacted 失败原因。 |
+| 用户接口 | 受控平台运维 CLI、HWLAB lane 状态查询、Web/CLI 默认端点解析和 public health。 |
+| 系统边界 | 公开入口负责外部流量到正确 runtime 的连通和可解释状态；不定义 Web 页面、API 业务语义、用户权限或 Agent 执行结果。 |
+
+## 5. 内部分工与规格索引
+
+| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
+| --- | --- | --- | --- | --- | --- |
+| PJ2026-01060401 | URL真相 | 本规格 6.1 | public web/api/health URL、node/lane 归属和旧入口降级 | YAML运维、源码同步 | 客户端、内测说明 |
+| PJ2026-01060402 | 代理投递 | 本规格 6.2 | FRP、Caddy、TLS、DNS 和 managed block 投递 | YAML publicExposure、运行服务 | Web/API 访问 |
+| PJ2026-01060403 | Route边界 | 本规格 6.3 | Web route、API path、health path 和坏端口边界 | Web工作台、API契约 | CLI、Playwright、用户访问 |
+| PJ2026-01060404 | 漂移处理 | 本规格 6.4 | public URL、FRP、Caddy、DNS/TLS、runtime health 不一致时的状态归因 | 运维监控、YAML运维 | 平台管理员、用户反馈分流 |
+
+## 6. 原子需求
+
+### 6.1 OPS-PUBLIC-REQ-001 公开 URL 真相
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| OPS-PUBLIC-REQ-001 | URL真相 | PJ2026-01060401 URL真相 | [YAML运维](PJ2026-010603-yaml-first-ops.md)、[客户端](PJ2026-0104-client.md) |
+
+公开入口应以目标 node/lane 的 YAML 声明和受控状态查询作为 Web、API 和 health public URL 真相，使用户说明、CLI 默认端点、Playwright 验收和 issue 复现不会误用旧端口或其他 lane。
+
+FRP remote port、node 内部 service、ClusterIP、pod IP、历史 nip.io 域名和临时 port-forward 只能作为实现细节或诊断入口出现。缺少正式 public URL 时，应返回配置缺口，不得让调用者自动退回旧入口继续验收。
+
+### 6.2 OPS-PUBLIC-REQ-002 代理投递
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| OPS-PUBLIC-REQ-002 | 代理投递 | PJ2026-01060402 代理投递 | [YAML运维](PJ2026-010603-yaml-first-ops.md)、[发布流水](PJ2026-010601-controlled-release.md) |
+
+公开入口应通过受控 FRP、Caddy、DNS 和 TLS 投递目标 Web/API 服务，使外部流量到达声明的 node/lane runtime。
+
+Caddy 更新必须使用受控 managed block 合并，不能用某个服务的渲染结果整文件覆盖共享 Caddyfile。FRP、Caddy 和 TLS 输出只能包含目标、状态、fingerprint、health 和错误摘要，不输出 Secret、token、证书私钥或可复制凭据。
+
+### 6.3 OPS-PUBLIC-REQ-003 Route 边界
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| OPS-PUBLIC-REQ-003 | Route边界 | PJ2026-01060403 Route边界 | [PJ2026-010401 Web工作台](PJ2026-010401-web-workbench.md)、[PJ2026-010403 API契约](PJ2026-010403-api-contract.md) |
+
+公开入口应保持 Web route、API path 和 health path 的边界清楚：Web public URL 承载浏览器页面和 SPA history route，API public URL 承载 JSON API、JSON-RPC 和 health 语义。
+
+API/edge 直达入口不需要为页面 route 返回 HTML fallback；Web public 入口需要按 route policy 把 API path 分流到 API 服务。内部 `:6666`/`:6667` 这类实现端口不能作为浏览器验收默认入口；对 Node/undici bad-port 有限制的内部探测应使用 repo-owned probe、curl 或正式 public URL。
+
+### 6.4 OPS-PUBLIC-REQ-004 入口漂移处理
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| OPS-PUBLIC-REQ-004 | 漂移处理 | PJ2026-01060404 漂移处理 | [运维监控](PJ2026-010605-observability-monitoring.md)、[客户端](PJ2026-0104-client.md) |
+
+公开入口应在 YAML、FRP、Caddy、DNS/TLS、public health 或 runtime 服务不一致时输出可定位的漂移摘要，使平台管理员能判断问题位于入口投递、目标服务、域名证书还是业务接口。
+
+入口漂移处理只说明外部访问链路是否到达正确 runtime，不把 health 200、Caddy reachable 或 FRP connected 升级为 Web、登录、Agent、HWPOD 或 CaseRun 业务通过。
+
+## 7. 过程控制
+
+本规格不单独索引过程 issue；跨 L1 的内测、灰度和阶段活动索引统一保留在 [PJ2026-01 HWLAB 总规格](PJ2026-01-HWLAB.md) 的 `7. 过程控制`。
@@ -0,0 +1,125 @@
+# PJ2026-010605 运维监控
+
+## 修改历史
+
+| 版本 | 对应 commit id | 更新日期 | 变更说明 |
+| --- | --- | --- | --- |
+
+当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。
+
+## 正文
+
+## PJ2026-010605 运维监控需求规格
+
+## 1. 文档控制
+
+| 字段 | 内容 |
+| --- | --- |
+| 编号 | PJ2026-010605 |
+| 短名 | 运维监控 |
+| 层级 | L2 课题 |
+| 状态 | 已生效 |
+| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
+| 上级规格 | [PJ2026-0106 平台运维](PJ2026-0106-platform-ops.md) |
+| 规格治理索引 | [规格治理](spec-governance.md) |
+
+本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 HWLAB Prometheus 运维监控的稳定使命、范围、术语、系统边界、内部分工和原子需求。
+
+## 2. 目的和范围
+
+### 2.1 目的
+
+运维监控负责通过 Prometheus 和配套状态查询入口采集 HWLAB 运行面 metrics、scrape target、alert rule、服务健康指标和资源指标，使平台运维能够发现服务不可用、入口漂移、资源异常和发布后运行状态退化。
+
+本课题的目标状态是：各业务 L1 提供自己的服务健康和业务状态指标，平台运维统一接入 Prometheus 并输出可查询、可告警、可回溯的运维状态；监控只判断运行面健康和资源状态，不替代业务成功标准。
+
+### 2.2 范围内
+
+- Prometheus scrape target、metrics endpoint、alert rule 和服务健康指标接入。
+- Web/API/AgentRun/HWPOD/Harness/用户管理等服务的运行面健康、资源状态和公开入口健康观测。
+- 发布后 runtime readiness、resource usage、error rate、queue depth、target availability 和 alert 状态摘要。
+- 监控数据的受控查询、低噪声摘要、失败归因和敏感输出约束。
+
+### 2.3 范围外
+
+- Agent command、CaseRun、HWPOD operation 或用户账本的业务成功标准由对应 L1 定义。
+- 长 trace、原始日志、测试报告、截图、CaseRun registry 和用户反馈正文不进入本规格。
+- Prometheus 具体阈值、保留周期、告警路由、采样间隔和容量数值以 YAML/config 为准，不在本规格硬编码。
+- 监控告警不能代替发布流水、业务验证、CaseRun 评价或用户反馈分流。
+
+## 3. 术语表
+
+| 术语 | 定义 |
+| --- | --- |
+| Prometheus 运维监控 | 通过 Prometheus 采集、查询和告警 HWLAB 运行面 metrics 的运维能力。 |
+| scrape target | Prometheus 抓取 metrics 的目标服务、path 和 label 集合。 |
+| metrics endpoint | 服务暴露运行状态、资源状态和业务健康指标的 HTTP 端点。 |
+| alert rule | 对 metrics 表达告警条件的规则，具体阈值来自配置。 |
+| 运行健康 | 服务 ready、live、依赖可达、资源可用和错误率处于可接受状态的运维判断。 |
+| 业务通过 | 由业务 L1 原入口定义的功能成功，例如 Agent turn completed、HWPOD operation 成功或 CaseRun 通过。 |
+
+## 4. 系统边界和接口
+
+| 边界项 | 内容 |
+| --- | --- |
+| 外部使用者 | 平台管理员、发布操作人员、值守自动化、需要运行状态的各 L1 owner。 |
+| 外部输入 | 服务 metrics endpoint、health/readiness、runtime resource 指标、scrape 配置、alert rule 配置和查询请求。 |
+| 受控资源 | Prometheus target、metrics、alert rule、运行面状态摘要、服务健康指标和资源指标。 |
+| 外部输出 | target 状态、metrics 查询结果、alert 状态、运行健康摘要、入口健康摘要和 redacted 失败原因。 |
+| 用户接口 | Prometheus 查询、受控平台运维 CLI、发布状态摘要和各 L1 health/status 页面或命令。 |
+| 系统边界 | 运维监控负责运行面可观察和告警；不定义业务完成标准，不保存长证据，不把监控 green 当作业务通过。 |
+
+## 5. 内部分工与规格索引
+
+| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
+| --- | --- | --- | --- | --- | --- |
+| PJ2026-01060501 | Metrics接入 | 本规格 6.1 | metrics endpoint、scrape target 和 label 口径 | 各 L1 服务健康指标 | Prometheus 查询 |
+| PJ2026-01060502 | 告警规则 | 本规格 6.2 | alert rule、状态分类和配置来源 | Metrics接入、YAML运维 | 平台值守、发布判定 |
+| PJ2026-01060503 | 运行摘要 | 本规格 6.3 | health、readiness、resource、error rate 和入口健康摘要 | 公开入口、发布流水 | 管理员和各 L1 owner |
+| PJ2026-01060504 | 边界约束 | 本规格 6.4 | 监控与业务通过、长证据、敏感输出的边界 | 全部 L1 | 用户反馈和排障 |
+
+## 6. 原子需求
+
+### 6.1 OPS-MON-REQ-001 Metrics 接入
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| OPS-MON-REQ-001 | Metrics接入 | PJ2026-01060501 Metrics接入 | [YAML运维](PJ2026-010603-yaml-first-ops.md)、[发布流水](PJ2026-010601-controlled-release.md) |
+
+运维监控应接入 HWLAB 各运行服务的 metrics endpoint 和 scrape target，使服务 live、ready、resource、queue、error、latency 和依赖健康可以被 Prometheus 查询。
+
+各 L1 负责定义自身服务健康指标含义；平台运维负责统一接入、命名、label 和可查询状态。metrics 缺失应暴露为监控缺口，不得用日志 grep、一次性 curl 或人工截图替代长期监控。
+
+### 6.2 OPS-MON-REQ-002 告警规则
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| OPS-MON-REQ-002 | 告警规则 | PJ2026-01060502 告警规则 | [YAML运维](PJ2026-010603-yaml-first-ops.md)、[公开入口](PJ2026-010604-public-entry.md) |
+
+运维监控应通过配置化 alert rule 表达服务不可达、目标缺失、入口漂移、资源耗尽、错误率异常和发布后健康退化等运维风险。
+
+告警阈值、保留周期、通知路由和采样间隔由 YAML/config 承载；规格只定义告警能力和边界。告警输出应包含服务、target、rule、severity、状态和 redacted 摘要，不输出 Secret、token、DSN password 或完整日志。
+
+### 6.3 OPS-MON-REQ-003 运行摘要
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| OPS-MON-REQ-003 | 运行摘要 | PJ2026-01060503 运行摘要 | [发布流水](PJ2026-010601-controlled-release.md)、[公开入口](PJ2026-010604-public-entry.md) |
+
+运维监控应提供低噪声运行摘要，使平台管理员能查看目标 node/lane 的服务健康、公开入口健康、资源使用、队列积压、错误分类和最近告警状态。
+
+运行摘要用于判断运行面是否需要运维处理或发布回滚，不替代业务原入口。Web 可访问、API health 通过或 Prometheus green 只能证明运行面健康的一部分，不能证明 Agent、HWPOD、CaseRun、用户账本或内测业务用例通过。
+
+### 6.4 OPS-MON-REQ-004 监控边界
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| OPS-MON-REQ-004 | 边界约束 | PJ2026-01060504 边界约束 | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[HarnessRL](PJ2026-0103-harness-rl.md) |
+
+运维监控应明确区分运行健康、业务通过和长证据归属。监控只保存和展示运维指标、target 状态和告警摘要；长 trace、CaseRun registry、用户反馈原文、截图和执行日志仍保留在对应业务入口或 GitHub issue。
+
+缺失业务能力时，监控只能报告 blocker 或 health 降级，不能通过新增告警、证据采样或诊断文案伪装成能力完成。
+
+## 7. 过程控制
+
+本规格不单独索引过程 issue；跨 L1 的内测、灰度和阶段活动索引统一保留在 [PJ2026-01 HWLAB 总规格](PJ2026-01-HWLAB.md) 的 `7. 过程控制`。