pikasTech-unidesk/project-management/PJ2026-01/specs/PJ2026-010605-observability-monitoring.md

PJ2026-010605 运维监控

修改历史

版本	对应 commit id	更新日期	变更说明

当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 待提交 版本。

正文

PJ2026-010605 运维监控需求规格

1. 文档控制

字段	内容
编号	PJ2026-010605
短名	运维监控
层级	L2 课题
状态	已生效
实现引用版本	draft-2026-06-26-p8-egress-job-friction
需求规格模板	ISO/IEC/IEEE 29148 需求规格模板
上级规格	PJ2026-0106 平台运维
规格治理索引	规格治理

本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 HWLAB 运维监控的稳定使命、范围、术语、系统边界、内部分工和原子需求。Prometheus 继续承载 metrics、dashboard、alert 和 Workbench 用户可感知性能指标；OpenTelemetry 首期只承载 tracing、span、trace id 关联和跨服务因果链路。Workbench 用户可感知性能监控的架构图、数据流图、时序图和实现引用要求由 PJ2026-01060505 Workbench性能 细化。

2. 目的和范围

2.1 目的

运维监控负责通过 Prometheus 和 OpenTelemetry 的分工协作采集 HWLAB 运行面 metrics、scrape target、alert rule、服务健康指标、资源指标和关键请求 trace，使平台运维能够发现服务不可用、入口漂移、资源异常、发布后运行状态退化，以及单个 Workbench/AgentRun 请求在 admission、billing、dispatch、projection 或 replay 阶段的失败位置。

本课题的目标状态是：各业务 L1 提供自己的服务健康、业务状态指标和关键链路 trace 语义，平台运维统一接入 Prometheus metrics 面和 OpenTelemetry tracing 面并输出可查询、可告警、可回溯的运维状态；监控只判断运行面健康、资源状态和单次请求因果链，不替代业务成功标准。

运维监控接入必须遵循 UniDesk YAML-first ops：scrape target、alert rule、recording rule、summary query、OTel Collector、trace backend、target/node/lane、namespace、endpoint、采样/保留/阈值等 UniDesk 自有运维事实必须归属 YAML；受控 CLI 负责读取、校验、渲染、apply/status/summary/trace。运行面对象、Prometheus 查询结果和 trace backend 查询结果只作为观测证据，不反推为配置真相。

2.2 范围内

• Prometheus scrape target、metrics endpoint、alert rule 和服务健康指标接入。
• OpenTelemetry Collector、trace backend、span 语义、trace context 传播和 trace 查询入口。
• Web/API/AgentRun/HWPOD/Harness/用户管理等服务的运行面健康、资源状态、公开入口健康和用户可感知性能观测。
• 发布后 runtime readiness、resource usage、error rate、queue depth、target availability 和 alert 状态摘要。
• AgentRun rolling recovery 与 cancel lifecycle 的 active runner、stale lease、cancel request、cancel delivery、terminal report retry、reconciler backlog、projection lag、late-write fencing 和 Job TTL cleanup 观测。
• provider-gateway egress TCP tunnel、backend-core egress bridge、受控 relay、异步 job 和 server lifecycle 命令的阶段化可见性。
• 监控和 trace 数据的受控查询、低噪声摘要、失败归因和敏感输出约束。

2.3 范围外

• Agent command、CaseRun、HWPOD operation 或用户账本的业务成功标准由对应 L1 定义。
• 完整 prompt、assistant 正文、tool 参数、命令输出、原始日志、测试报告、截图、CaseRun registry 和用户反馈正文不进入本规格或默认 trace attribute。
• Prometheus 具体阈值、保留周期、告警路由、采样间隔和容量数值以 YAML/config 为准，不在本规格硬编码。
• OpenTelemetry Collector image、trace backend image、存储模式、retention、采样率、endpoint 和服务接入关系以 YAML/config 为准，不在业务代码硬编码。
• 监控告警不能代替发布流水、业务验证、CaseRun 评价或用户反馈分流。

3. 术语表

术语	定义
Prometheus 运维监控	通过 Prometheus 采集、查询和告警 HWLAB 运行面 metrics 的运维能力。
OpenTelemetry tracing	通过 OTel Collector、trace backend、span 和 W3C trace context 关联单次请求跨服务因果链路的运维能力。
trace backend	保存并查询 trace/span 的平台组件，首期可由 Tempo 或 Jaeger 承担，部署事实由 YAML 控制。
Trace Explorer URL 模板	由 YAML 声明的 trace backend 打开链接模板，例如包含 {trace_id} 占位符的 Tempo、Jaeger 或 Grafana Explore URL；前端只替换合法 OTel trace id，不拼接其他用户输入。
span	一次请求在 admission、billing、AgentRun dispatch、projection、read/replay 等阶段中的一个可观察工作单元。
trace context	W3C traceparent/baggage 等跨进程传播上下文；业务 traceId/sessionId/runId/turnId 只能作为 span attribute，不能替代标准 trace context。
provider egress TCP tunnel	target node 上 provider-gateway egress proxy 通过 backend-core WebSocket 控制通道请求 master 侧打开 TCP 连接，并在两端转发字节流的出站链路。
async job 摘要	`server start
用户可感知性能	用户在 Web、CLI 或 API 入口中直接感受到的等待时间、加载时间、首个可读内容出现时间和完整可用状态。
YAML-first 运维监控	Prometheus scrape、rule、summary 和 target 归属先进入 UniDesk YAML，再通过受控 CLI 渲染和验证的运维形态。
rolling recovery signal	用于判断 manager/cloud-api rolling 后同一 run/command/runnerJob 是否恢复控制权的低基数 metrics、span attribute 和 CLI 摘要字段。
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 配置、OTLP trace/span、trace context、trace 查询请求和 metrics 查询请求。
受控资源	Prometheus target、metrics、alert rule、OTel Collector、trace backend、运行面状态摘要、服务健康指标、资源指标和 redacted trace 摘要。
外部输出	target 状态、metrics 查询结果、alert 状态、trace 查询结果、Trace Explorer URL 模板摘要、运行健康摘要、入口健康摘要和 redacted 失败阶段。
用户接口	Prometheus 查询、OpenTelemetry trace 查询、受控平台运维 CLI、发布状态摘要和各 L1 health/status 页面或命令。
系统边界	运维监控负责运行面可观察、告警和单次请求因果链；不定义业务完成标准，不保存默认长证据，不把监控 green 或 trace 可查当作业务通过。

5. 内部分工与规格索引

编号	模块或课题	规格文档	主责边界	上游依赖	下游支撑
PJ2026-01060501	OTel追踪	本规格 6.1	OTel Collector、trace backend、span 语义、trace context 和受控 trace 查询	HWLAB v0.3、AgentRun、用户账本、Web工作台	平台排障、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	用户反馈和排障
PJ2026-01060505	Workbench性能	PJ2026-01060505 Workbench性能	Web 工作台用户可感知性能、RUM、AgentRun event visible latency 和 Prometheus 指标口径	Web工作台、Agent编排、API契约	平台运维、客户端和性能回归调查
PJ2026-01060506	Metrics接入	本规格 6.6	metrics endpoint、scrape target 和 label 口径	各 L1 服务健康指标	Prometheus 查询
PJ2026-01060507	Rolling恢复观测	本规格 6.7	active runner、reconciler backlog、terminal retry、projection lag 和不可恢复 blocker 的查询口径	AgentRun核心、HWLAB接入、Workbench唯一投影、发布Lane	rolling 发布判定、故障收口
PJ2026-01060508	Web哨兵	PJ2026-01060508 Web哨兵	web-probe observe 的 YAML-first 生产哨兵、持续 canary、报告视图、dashboard 分析工作台和发布恢复验证	Web工作台、Workbench唯一投影、YAML运维、公开入口、发布流水	平台值守、CI/CD targetValidation、用户入口恢复判定
PJ2026-01060509	出站诊断	本规格 6.9	provider egress TCP tunnel、受控 relay、async job/server lifecycle 的阶段化日志、低噪声摘要和诊断入口	provider-gateway、backend-core、YAML运维、发布流水	D601/G14 runtime 出站排障、OpenFGA/Postgres/OA Event Flow 链路验收

6. 原子需求

6.1 OPS-MON-REQ-001 OTel 追踪

编号	短名	主责模块	关联模块
OPS-MON-REQ-001	OTel追踪	PJ2026-01060501 OTel追踪	YAML运维、Agent编排、客户端、用户管理

运维监控应在 platform-infra 提供 YAML-first OpenTelemetry tracing 能力，使一次 Workbench submit 或等价 API 请求可以沿 Cloud API admission、billing preflight、AgentRun dispatch、projection write、trace events read 和 Web replay 等阶段保留可查询 span。

OpenTelemetry 不替代 Prometheus。Prometheus 继续承载 metrics、dashboard、alert 和用户可感知性能指标；OTel tracing 只回答单个 traceId/sessionId/runId/turnId 跨服务断在哪个阶段。业务 ID 可以作为 span attribute 用于排查，但不能成为 Prometheus label，也不能替代 W3C trace context。

6.1.1 目标架构图

flowchart LR
  W[Workbench Web] --> API[HWLAB cloud-api]
  API --> Billing[user-billing]
  API --> AR[AgentRun manager]
  AR --> Runner[AgentRun runner]
  API --> Projection[projection/read model]
  API --> Metrics[Prometheus metrics endpoint]
  Billing --> Metrics
  AR --> Metrics
  API -- OTLP spans --> Collector[OTel Collector<br/>platform-infra]
  Billing -- OTLP spans --> Collector
  AR -- OTLP spans --> Collector
  Runner -- OTLP spans --> Collector
  Collector --> TraceBackend[Trace backend<br/>Tempo or Jaeger]
  Metrics --> Prometheus[Prometheus metrics面]
  CLI[UniDesk platform-infra observability CLI] --> Collector
  CLI --> TraceBackend
  CLI --> Prometheus

6.1.2 数据流图

flowchart TD
  Span[应用关键 span] --> Collector[OTel Collector]
  Collector --> Backend[trace backend]
  Metric[低基数 metrics] --> Prometheus[Prometheus]
  Backend --> TraceQuery[CLI trace query]
  Prometheus --> MetricQuery[CLI metrics/status query]
  TraceQuery --> Diagnose[按 traceId/sessionId/runId 定位失败阶段]
  MetricQuery --> Health[运行健康、趋势和告警判断]
  Diagnose -.关联.-> Health

数据流必须保持职责分离：trace backend 保存高基数字段和跨服务因果链；Prometheus 只保存低基数指标、alert 和趋势。CLI 可以把 metrics 摘要与 trace 查询结果放到同一排障报告中，但不能把两套存储合并为一个第二真相。

6.1.3 关键时序图

sequenceDiagram
  participant W as Workbench
  participant API as cloud-api
  participant B as user-billing
  participant AR as AgentRun
  participant P as projection
  participant OTel as OTel Collector
  participant TB as trace backend

  W->>API: POST /v1/agent/chat
  API->>OTel: span admission
  API->>B: billing_preflight with trace context
  B->>OTel: span billing_preflight
  API->>AR: dispatch command with trace context
  AR->>OTel: span agentrun_dispatch
  AR-->>API: runId/commandId
  API->>P: projection_write
  P->>OTel: span projection_write
  W->>API: replay/read trace events
  API->>OTel: span trace_events_read
  OTel->>TB: export spans

6.1.4 YAML 与 CLI 归属

OTel Collector、trace backend、target route、namespace、image、storage、retention、sampling、export 开关、OTLP endpoint、Trace Explorer URL 模板、probe 和应用接入关系必须进入 config/platform-infra/observability.yaml 或后续确认的 owning YAML。正式入口必须是 bun scripts/cli.ts platform-infra observability plan|apply|status|validate|trace 或等价受控 CLI；trans <target>:k3s 只能作为有界诊断底座，不能成为长期 mutate path。

Trace Explorer URL 模板必须作为 YAML 配置下发到需要展示“打开 Trace”的客户端运行配置中。模板只能包含 {trace_id} 占位符和运维确认的静态 URL 片段；前端替换前必须校验 trace id 为 32 位十六进制字符串。配置缺失、模板禁用或 trace id 非法时，客户端只显示复制入口。任何实现都不得把 trace backend 内部地址、Grafana token、cookie、API key、tracestate、baggage、prompt、assistant 正文或 raw upstream payload 放入模板或用户可见 URL。

首期应用侧手工 span 至少覆盖：

• POST /v1/agent/chat
• durable_admission
• billing_preflight
• agentrun_dispatch
• projection_write
• trace_events_read
• turn_status_read

统一 resource attributes 至少包含 service.name、deployment.environment、unidesk.node、hwlab.lane、k8s.namespace.name 和 git.commit。统一传播使用 W3C traceparent/baggage；traceId、sessionId、turnId、runId、commandId 只能作为 span attribute。

用户可见错误只展示 OTel trace id、request id、route、serviceId、error code、layer 和 redacted observedAt。traceparent 可以作为 HTTP header 传播和返回，tracestate 与 baggage 只能用于受控传播，不得进入用户错误面板、issue closeout 可复制凭据、日志摘要或默认 trace explorer URL。

6.1.5 代码引用规则

本需求范围内新增或修改的源码文件头部必须标注 SPEC: PJ2026-01060501 OTel追踪 draft-2026-06-19-p0，并用一句话说明文件职责。纯 YAML、生成 manifest、锁文件或第三方 CRD 如不能加头部，必须能从 owning YAML、渲染器或 CLI 命令追溯到本 SPEC。

6.2 OPS-MON-REQ-002 告警规则

编号	短名	主责模块	关联模块
OPS-MON-REQ-002	告警规则	PJ2026-01060502 告警规则	YAML运维、公开入口

运维监控应通过配置化 alert rule 表达服务不可达、目标缺失、入口漂移、资源耗尽、错误率异常和发布后健康退化等运维风险。

告警阈值、保留周期、通知路由和采样间隔由 YAML/config 承载；规格只定义告警能力和边界。告警输出应包含服务、target、rule、severity、状态和 redacted 摘要，不输出 Secret、token、DSN password 或完整日志。

6.3 OPS-MON-REQ-003 运行摘要

编号	短名	主责模块	关联模块
OPS-MON-REQ-003	运行摘要	PJ2026-01060503 运行摘要	发布流水、公开入口

运维监控应提供低噪声运行摘要，使平台管理员能查看目标 node/lane 的服务健康、公开入口健康、资源使用、队列积压、错误分类和最近告警状态。

运行摘要用于判断运行面是否需要运维处理或发布回滚，不替代业务原入口。Web 可访问、API health 通过或 Prometheus green 只能证明运行面健康的一部分，不能证明 Agent、HWPOD、CaseRun、用户账本或内测业务用例通过。

6.4 OPS-MON-REQ-004 监控边界

编号	短名	主责模块	关联模块
OPS-MON-REQ-004	边界约束	PJ2026-01060504 边界约束	客户端、Agent编排、硬件池、HarnessRL

运维监控应明确区分运行健康、业务通过和长证据归属。监控只保存和展示运维指标、target 状态和告警摘要；长 trace、CaseRun registry、用户反馈原文、截图和执行日志仍保留在对应业务入口或 GitHub issue。

缺失业务能力时，监控只能报告 blocker 或 health 降级，不能通过新增告警、证据采样或诊断文案伪装成能力完成。

6.5 OPS-MON-REQ-005 Workbench 用户可感知性能

编号	短名	主责模块	关联模块
OPS-MON-REQ-005	Workbench性能	PJ2026-01060505 Workbench性能	Web工作台、Agent编排、API契约

运维监控应把 Web 工作台的用户可感知性能纳入 Prometheus 与 RUM 口径，使用户发消息到首个可见 Code Agent 输出、AgentRun backend event 到 Web 可见、session 切换加载和首屏打开等路径可以被持续观测。

Workbench 性能监控只记录低基数指标、阶段耗时、状态分类和脱敏 correlation；不得把 traceId、sessionId、runId、prompt、assistant 正文、tool 参数、stdout/stderr、Secret 或用户个人信息写入 Prometheus label。具体架构、数据流、时序和代码引用规则由 PJ2026-01060505 Workbench性能 定义。

6.6 OPS-MON-REQ-006 Metrics 接入

编号	短名	主责模块	关联模块
OPS-MON-REQ-006	Metrics接入	PJ2026-01060506 Metrics接入	YAML运维、发布流水

运维监控应接入 HWLAB 各运行服务的 metrics endpoint 和 scrape target，使服务 live、ready、resource、queue、error、latency 和依赖健康可以被 Prometheus 查询。

各 L1 负责定义自身服务健康指标含义；平台运维负责通过 YAML-first UniDesk ops 统一接入、命名、label 和可查询状态。metrics 缺失应暴露为监控缺口，不得用日志 grep、一次性 curl、手工 kubectl apply 或人工截图替代长期监控。

6.7 OPS-MON-REQ-007 Rolling 恢复观测

编号	短名	主责模块	关联模块
OPS-MON-REQ-007	Rolling恢复	PJ2026-01060507 Rolling恢复观测	AgentRun核心、HWLAB接入、Workbench唯一投影、AgentRun发布Lane

运维监控应为 AgentRun/HWLAB rolling recovery 和 cancel lifecycle 提供可查询的低基数 metrics、trace span 和受控 CLI 摘要。最小观测对象包括 active runner 数、runner job observation phase、stale lease 数、cancel request accepted 数、cancel delivered 数、cancel terminalized 数、late-write-fenced 数、terminal report retry/outbox backlog、manager reconciler backlog、reconciler last success/error、projection lag、projection blocker 数、Job TTL cleanup 数和不可恢复 blocker 数。

rolling recovery 相关 span 应能用 OTel trace id/request id 关联 sessionId、traceId、runId、commandId、runnerJobId 和 jobName 的 redacted attribute。高基数业务 ID 只能作为 trace/span attribute 或 CLI 单次查询参数，不进入 Prometheus label；prompt、assistant 正文、tool 参数、stdout/stderr、Secret、完整 token、完整 DSN 和 provider payload 不得进入默认 metrics、span 或 issue closeout。

发布/rollout 前后的受控 CLI 摘要应能回答：仍在运行的 runner 数、已恢复控制权数量、cancel 当前阶段分布、terminal report retry 数、projection lag 最大值、不可恢复 blocker 数和最近一次 reconciler 错误。该摘要只用于定位和发布判定，不替代 P6 原入口 rolling/chaos 验收，也不能把可观测性 green 当作业务任务完成。

6.8 OPS-MON-REQ-008 Web 哨兵

编号	短名	主责模块	关联模块
OPS-MON-REQ-008	Web哨兵	PJ2026-01060508 Web哨兵	Web工作台、Workbench唯一投影、YAML运维、公开入口、发布流水

运维监控应提供 YAML-first Web 哨兵能力，把现有 web-probe observe start/status/command/collect/analyze 服务化为生产可用的持续 canary、报告视图和发布恢复验证入口。该能力只 wrap 现有 observe runner、control queue、artifact JSONL、collect 渲染和 observe analyze 报告，不新增第二套 Playwright runner、offline analyzer、finding classifier、dashboard 事实源或 Workbench 状态机。

Web 哨兵配置必须通过 node/lane root YAML 的 observability.webProbe.sentinel.enabled/configRefs 引用 runtime、scenario、promptSet、reportView、publicExposure、CI/CD 和 Secret owning YAML。parser 只校验引用、形状、类型和冲突；cadence、采样间隔、轮次、profile、prompt source、report view、retention、public exposure、maintenance 和 Secret 参数以 YAML 为准。

Web 哨兵 dashboard 应作为平台值守和问题分析工作台展示同一 observe/analyze 事实：首屏健康摘要、scheduler/maintenance、latest run、finding severity、runs history、run detail、turn-summary 和 trace-frame。Dashboard 不得新增采样器、analyzer、截图保存源或 Workbench 状态仲裁；自动刷新只能读取 bounded/redacted API。

Web 哨兵的首条生产 canary 应覆盖 workbench-dsflash-go-tool-call-10x：同一 HWLAB Workbench session 内十轮需要工具调用的任务，使用 dsflash-go backend profile，报告每轮 traceId、terminal status、tool-call evidence、耗时、慢 API、trace 顺序、terminal-not-last、session mismatch 和 final-response finding。dsflash-go profile、SecretRef、config 和 model catalog 缺失时必须结构化失败，不允许 fallback 到其他 profile。

发布流水可调用 Web 哨兵 maintenance start/stop。maintenance start 暂停告警但继续采样；maintenance stop 触发同一 observe CLI quick verify 和 analyze。CI/CD targetValidation 对 HWLAB Web 恢复的判断必须包含 quick verify、analysis report SHA、finding 摘要、public origin、scenario id 和 observer/run id；Argo green 但哨兵 red/timeout 时不得判定发布恢复成功。

6.9 OPS-MON-REQ-009 Provider 出站与 Job 可见性

编号	短名	主责模块	关联模块
OPS-MON-REQ-009	出站诊断	PJ2026-01060509 出站诊断	YAML运维、公开入口、发布流水

运维监控应为 provider-gateway egress TCP tunnel、backend-core egress bridge、受控 relay 和 CLI async job 提供阶段化可见性，使 D601/G14 等节点的 PostgreSQL、OpenFGA、OA Event Flow、Git mirror 或外部下载问题可以被定位到 provider 本地 proxy、backend-core open、master 侧 TCP connect、relay ACL、目标服务或调用方读写阶段。

provider egress tunnel 生命周期至少应记录：provider proxy 收到 client 请求、发出 egress_tcp_open、core 确认 opened、core connect failed/timeout、remote close、本地 open timeout、client close、pending buffer 超限和 idle close。日志和受控摘要必须包含 providerId、connectionId、目标 host/port、method、ageMs、pendingBytes 和低基数 failureKind；不得记录 TCP payload、PostgreSQL DSN 密码、HTTP Authorization、Secret、token 或完整业务正文。

server start|stop|rebuild|restart 等创建 .state/jobs 的命令默认必须返回 async job 摘要，而不是完整 JSON payload、完整 command、完整 runtime env 或 stdout/stderr。摘要至少包含 job id、目标 service、当前状态、stdout/stderr 路径、job status 查询命令和必要的 server logs/server status 后续命令。完整结构只能通过 --full/--raw 或 job status <id> 渐进展开。job 与常见自然输入 jobs、status|get|read 应指向同一受控状态入口，避免调用者因为别名缺失退回手工文件读取。

6.9.1 目标架构图

flowchart LR
  Pod[目标 runtime Pod] --> Proxy[provider-gateway egress proxy]
  Proxy -- egress_tcp_open/data/close --> Core[backend-core provider WS]
  Core --> Relay[受控 relay 或目标 TCP 服务]
  Relay --> Target[Postgres / OA Event Flow / external endpoint]
  Core --> Logs[backend-core logs]
  Proxy --> ProviderLogs[provider-gateway logs]
  CLI[UniDesk CLI job/status/triage] --> Logs
  CLI --> ProviderLogs

6.9.2 数据流图

flowchart TD
  Request[CONNECT 或 HTTP proxy 请求] --> LocalEvent[provider proxy stage event]
  LocalEvent --> OpenMsg[egress_tcp_open]
  OpenMsg --> CoreEvent[backend-core open/connect stage event]
  CoreEvent --> Outcome{connect outcome}
  Outcome -->|opened| DataFlow[egress_tcp_data 双向转发]
  Outcome -->|failed/timeout| CloseMsg[egress_tcp_close with failureKind]
  DataFlow --> CloseMsg
  CloseMsg --> Summary[provider triage / job status / logs 摘要]

6.9.3 关键时序图

sequenceDiagram
  participant C as Runtime client
  participant P as provider egress proxy
  participant B as backend-core
  participant R as Relay/Target
  participant CLI as UniDesk CLI

  C->>P: CONNECT host:port
  P->>P: log egress_proxy_tunnel_open_request
  P->>B: egress_tcp_open(providerId, connectionId, host, port)
  B->>B: log egress_tcp_open_requested/connect_start
  B->>R: TCP connect
  alt connect ok
    B->>P: egress_tcp_opened
    P->>P: log egress_proxy_tunnel_opened
    P-->>C: 200 Connection Established
  else connect failed or timeout
    B->>P: egress_tcp_close(error, failureKind)
    P->>P: log remote close
    P-->>C: connection close
  end
  CLI->>CLI: job status / logs / triage show bounded stage summary

6.9.4 代码引用规则

本需求范围内新增或修改的源码文件头部必须标注 SPEC: PJ2026-01060509 出站诊断 draft-2026-06-26-p8-egress-job-friction。纯配置、生成 manifest 或无法承载注释头的文件必须能从 owning CLI、渲染器或运行日志追溯到本 SPEC。

涉及 src/components/provider-gateway 的出站诊断行为、日志或能力标签变更必须在同一 source 变更中递增 src/components/provider-gateway/package.json 的 version。运行面验收必须通过 debug health、公网节点视图或 provider.upgrade 任务结果确认目标 provider 上报了新 providerGatewayVersion；只看到源码合并或 updater 日志不能视为 provider-gateway 诊断能力已经交付到 D601/G14。

7. 过程控制

本规格不单独索引过程 issue；跨 L1 的内测、灰度和阶段活动索引统一保留在 PJ2026-01 HWLAB 总规格 的 7. 过程控制。