diff --git a/project-management/PJ2026-01/specs/PJ2026-010401-web-workbench.md b/project-management/PJ2026-01/specs/PJ2026-010401-web-workbench.md index d81b9f2d..0e731f61 100644 --- a/project-management/PJ2026-01/specs/PJ2026-010401-web-workbench.md +++ b/project-management/PJ2026-01/specs/PJ2026-010401-web-workbench.md @@ -19,7 +19,7 @@ | 短名 | Web工作台 | | 层级 | L2 课题 | | 状态 | 已生效 | -| 实现引用版本 | draft-2026-06-20-p0-long-running-workbench; PJ2026-0104010803 唯一投影 draft-2026-06-20-p0-durable-facts-model | +| 实现引用版本 | draft-2026-06-20-p0-long-running-workbench; draft-2026-06-20-p0-error-diagnostics; PJ2026-0104010803 唯一投影 draft-2026-06-20-p0-durable-facts-model | | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | | 上级规格 | [PJ2026-0104 客户端](PJ2026-0104-client.md) | | 规格治理索引 | [规格治理](spec-governance.md) | @@ -73,6 +73,8 @@ Web工作台负责 HWLAB 登录后的浏览器主入口，使用户能够在同 | 共享 trace renderer | Web trace 面板和 HWLAB CLI `trace --render web` 共用的 trace row 转换语义。 | | Trace阅读视图 | 工作台中面向用户阅读 Code Agent trace 的默认视图，只展示用户可理解的助手消息、工具调用、命令输出、最终结果和真实耗时，把运行身份、隐藏统计和原始事件收束到消息详情入口。 | | 消息详情入口 | Agent 消息头部右上角的小型详情按钮，用于按需查看 trace id、session、run、command、raw event、隐藏统计和审计控制等调试信息。 | +| 错误诊断块 | 用户可见错误下方的低噪声诊断信息，展示可复制 OTel `trace_id`、request id、route、错误 code 和脱敏时间戳；它不替代主错误文案，也不改写 Workbench 状态。 | +| Trace Explorer 链接 | 根据运行配置中的 `observability.traceExplorerUrlTemplate` 生成的打开 trace backend 入口；只有模板存在且 `trace_id` 合法时显示，URL 只替换 `{trace_id}`。 | | Trace生命周期展开/折叠 | Code Agent turn 进入运行态时，Web 自动展开对应 Trace阅读视图；turn 进入终态时，Web 自动折叠该 Trace阅读视图，但仍允许用户手动重新打开。 | | 工作态高密度 | 面向持续排障、比较和重复操作的工业化界面密度要求：低圆角、低内边距、正文优先、辅助元信息折叠，避免装饰性卡片和大块留白抢占工作内容。 | | 正式公开入口 | 目标 node/lane 在 YAML 中声明的 Cloud Web public URL，用作用户访问、Playwright 验收、文档说明和故障复现入口。 | @@ -96,7 +98,7 @@ Web工作台负责 HWLAB 登录后的浏览器主入口，使用户能够在同 | 外部使用者 | 硬件研发用户、平台管理员、需要通过浏览器提交或观察任务的操作人员。 | | 外部输入 | 登录后访问请求、页面导航、会话选择、任务文本、引导/取消/重试操作、诊断查看操作和管理入口点击。 | | 受控资源 | Cloud Web shell、工作台路由、会话面板、对话面板、命令输入区、诊断弹窗、导航、响应式布局、composer policy 和共享 trace renderer。 | -| 外部输出 | 页面可见任务入口、会话状态、消息展示、命令反馈、诊断摘要、错误提示和可继续操作的 UI 状态。 | +| 外部输出 | 页面可见任务入口、会话状态、消息展示、命令反馈、诊断摘要、错误提示、可复制 OTel trace_id、可选 Trace Explorer 链接和可继续操作的 UI 状态。 | | 用户接口 | 目标 node/lane 的正式公开入口、Cloud Web `/workbench` 及相关登录后页面。 | | 系统边界 | Web工作台负责浏览器入口的布局、交互和展示契约；不拥有账号、Agent、硬件、评价或发布事实，只消费这些模块的服务端输出并以一致、低噪声、可操作的方式呈现。 | @@ -275,6 +277,12 @@ Web工作台应提供低噪声诊断反馈，使用户或管理员可以主动 诊断入口应位于全局工作台区域，例如 topbar 内的小型信息或告警按钮，并通过弹窗或详情面板承载完整状态。诊断内容不得单独占用主任务区一整行，也不得默认插入 conversation 正文；缺失能力仍必须回到对应业务模块修复，不能用诊断文案代替能力实现。 +所有用户可见错误都必须使用同一错误诊断块展示脱敏诊断字段。主文案先显示用户可理解的中文错误或业务 blocker；诊断行固定展示 `trace_id` 的复制入口，并在存在 `requestId`、route、error code、layer 或 observedAt 时以低噪声文本展示。没有服务端 trace id 的浏览器离线、DNS、CORS 或 network error 应使用前端 UI OTel trace id，并标记 `source=browser`，不得伪装成服务端 trace。 + +Trace Explorer 打开入口只由运行配置控制。前端不得在组件内硬编码 Tempo、Jaeger、Grafana 或平台内部地址；当 `observability.traceExplorerUrlTemplate` 缺失、`trace_id` 非 32 位十六进制或配置禁用打开入口时，只显示复制按钮。URL 构造只能替换 `{trace_id}`，不得拼接用户输入、`tracestate`、`baggage`、cookie、token、prompt、assistant 正文或 raw upstream payload。 + +错误诊断块适用于 Workbench admission 失败、projection blocker、transport timeout、SSE gap、trace hydration error、Skills/Gate/Performance 等普通页面 API 错误和全局 route exception。各页面不得各自拼接一套中文诊断文案或只抛出 `Error(response.error)`；API client 应保留结构化 `ApiError` / `ErrorDiagnostic`，字符串只作为最终用户文案。 + ### 6.4 CLIENT-WB-REQ-004 响应布局 | 编号 | 短名 | 主责模块 | 关联模块 | @@ -347,6 +355,8 @@ Web 工作台严禁读侧推理。`turn.status`、`message.status`、`session.ru Web 工作台必须把主消息投影、trace detail、session status 和 transport diagnostics 分仓保存。对已经带有 `sealedAt` 或等价 sealed 标记的 assistant message/turn，turn polling 失败、trace hydration 失败、SSE gap、realtime timeout、late compat wrapper error 或 elapsed timeout 只能更新诊断 bucket 或消息详情入口，不得替换主 timeline 的正文、finalResponse、message status 或 turn terminal。`showMessageText()`、message diagnostic selector、Trace 面板和组件模板不得让读侧诊断文案压过 sealed final response；需要修改 sealed 主正文时只能来自同一 durable projection 的新 revision、受控 replay/reprojection 或明确用户 mutation。 +错误诊断中的 `trace_id`、requestId、route、layer 和 code 只属于 diagnostic bucket。它们可以驱动复制按钮、Trace Explorer 链接、消息详情感叹号或 transport health 展示，但不得参与 `running`、`completed`、`failed`、`canceled`、`blocked`、finalResponse 选择、自动折叠、session active 选择或主消息正文替换。completed sealed final response 后出现的 polling、SSE 或 trace hydration 错误只能追加诊断，不得把主消息正文改成“连接上游失败”“等待超时”或同类读侧错误态。 + Web reducer/selectors 必须同时遵守无破坏性投影权。读侧路径中的 `forgetSession`、`replaceActiveSessionSelection(null)`、清空 messages、清空 tabs、把 composer 降级为 `session_required` 或把 route session 标记为 not-found/archived/deleted，都是 lifecycle mutation，不能由 GET/list/detail/messages/SSE 失败、空响应、404、route hydrate、refreshSessions 或 late response 触发。读侧只能把目标 session 的 loading、degraded、unknown、blocker 或 canonical lifecycle projection 展示出来；若需要删除、归档或失活，必须走后端 lifecycle projection 或用户显式 mutation 的成功结果。 初发刷新一致性是 Web 工作台的硬约束：同一 prompt 从 admission 开始生成稳定 userMessageId、assistantMessageId、turnId 和 traceId；初发 UI 可以 optimistic 展示这些 ID，但刷新、切换 session、SSE 重连和 REST 补洞必须用同 ID 的 durable message、part、turn 和 trace projection 确认。若 trace events 缺失，只影响 trace detail；主 timeline 的用户消息、assistant final response 和 turn terminal 状态不得因此退化为“思考中”。 @@ -389,6 +399,8 @@ mock 数据应优先来自目标 node/lane 的真实受控样本，而不是从 状态投影回归还必须覆盖 completed assistant 已 sealed 后的读侧失败负向用例：fixture 中 session messages API 返回 completed final response，随后 turn snapshot、trace event page、SSE 或 realtime diagnostic 失败。主 timeline 的 sealed final response 不变，诊断只显示在详情/感叹号/transport health 区域；Trace detail 延迟返回或分页缺口不得 remount 主消息卡片，也不得重置用户展开/折叠控制。 +错误诊断回归必须覆盖 HTTP 400、401、403、404、409、500、proxy timeout、network error、Workbench projection blocker 和 sealed final 后 transport error。fake-server fixture 应按正式 `HwlabErrorEnvelope` 或等价结构重放 `error.diagnostic.traceId`、requestId、route、code 和 `valuesRedacted=true`，并用用户可见 DOM 断言诊断块、复制入口和可选 Trace Explorer 链接；测试不得通过内部 store、localStorage 或测试专用后门读取诊断字段。 + 测试实现应优先使用用户可见文本、ARIA role 和稳定 DOM 标识断言，不通过内部 store、localStorage 或后端数据库直接判定通过。失败时必须保留 Playwright screenshot、trace 或等价 artifact；关键路径可以生成命名截图用于人工审阅。远程执行默认在目标 node/lane 上通过 UniDesk Playwright route 运行，截图和报告应回传到调用端，但这些 artifact 只是验证证据，不进入业务事实或监控指标。 ## 7. 过程控制 diff --git a/project-management/PJ2026-01/specs/PJ2026-010403-api-contract.md b/project-management/PJ2026-01/specs/PJ2026-010403-api-contract.md index 5179653b..9f9d0b87 100644 --- a/project-management/PJ2026-01/specs/PJ2026-010403-api-contract.md +++ b/project-management/PJ2026-01/specs/PJ2026-010403-api-contract.md @@ -19,7 +19,7 @@ | 短名 | API契约 | | 层级 | L2 课题 | | 状态 | 已生效 | -| 实现引用版本 | draft-2026-06-20-p0-workbench-pure-read-api; PJ2026-0104010803 唯一投影 draft-2026-06-20-p0-durable-facts-model; PJ2026-01050105 Web鉴权 draft-2026-06-18-p0-auth | +| 实现引用版本 | draft-2026-06-20-p0-workbench-pure-read-api; draft-2026-06-20-p0-error-diagnostics; PJ2026-0104010803 唯一投影 draft-2026-06-20-p0-durable-facts-model; PJ2026-01050105 Web鉴权 draft-2026-06-18-p0-auth | | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | | 上级规格 | [PJ2026-0104 客户端](PJ2026-0104-client.md) | | 规格治理索引 | [规格治理](spec-governance.md) | @@ -60,6 +60,10 @@ API契约负责定义 Cloud Web、HWLAB CLI 和自动化脚本共同使用的 RE | CanonicalPrincipal | `/auth/session` 和受保护业务 route 共享的最小身份结果，包含 `authMethod`、`identityAuthority`、`sessionKind`、actor 摘要和后端 capability 摘要；它是业务 route 的唯一身份输入。 | | 业务标识 | sessionId、turnId、traceId、runId、commandId、caseId 等用户可继续查询的稳定标识；projectId、workspaceId 和 conversationId 只能作为筛选、metadata 或兼容映射字段，不作为前端鉴权 authority。 | | 错误语义 | HTTP status、错误码、blocker、failureKind、route 和下一步提示组成的可定位失败表达。 | +| W3C trace context | `traceparent` / `tracestate` / `baggage` 等跨进程传播上下文；API 响应只允许把 `traceparent` 和脱敏后的 OTel trace id 暴露给客户端，不向用户展示 `tracestate`、`baggage` 或上游私有上下文。 | +| OTel trace_id | OpenTelemetry/W3C trace context 中的 16-byte 非全零 trace id，以 32 位十六进制字符串表达；它用于从用户截图或复制信息跳转到 trace backend，不替代业务 `traceId`、`sessionId`、`runId` 或权限判断。 | +| HwlabErrorEnvelope | API 用户可见失败响应的统一 JSON envelope，承载错误 code、用户文案、分类、层级、retryable 和脱敏诊断字段。 | +| ErrorDiagnostic | 错误诊断字段集合，至少包含 OTel trace id、request id、route、serviceId、observedAt 和 `valuesRedacted=true`；它只用于排障和复制，不参与 Workbench lifecycle 或 final response 判断。 | | Session detail | `GET /v1/workbench/sessions/{sessionId}` 这类按稳定 sessionId 或后端认可 opaque session handle 查询当前会话 metadata、消息指针和状态的 RESTful detail resource。 | | Conversation detail | 迁移期兼容资源；可返回 conversation metadata、sessionId、threadId 和 message seed，但不得继续作为 Web deep link 或前端 active session authority。 | | TurnSnapshot | 按 turnId 或 traceId 查询一次用户提交/steer/retry/cancel 生命周期、终态、message 指针和执行引用的 RESTful snapshot。 | @@ -79,9 +83,9 @@ API契约负责定义 Cloud Web、HWLAB CLI 和自动化脚本共同使用的 RE | 边界项 | 内容 | | --- | --- | | 外部使用者 | Cloud Web、HWLAB CLI、自动化脚本、平台管理员和需要同源 API 的浏览器客户端。 | -| 外部输入 | HTTP method、相对 path、JSON body、query、Web session cookie、Authorization header、sessionId、turnId、traceId 和业务参数；projectId、workspaceId、conversationId 只允许作为显式筛选或兼容 metadata 输入。 | +| 外部输入 | HTTP method、相对 path、JSON body、query、Web session cookie、Authorization header、`traceparent`、sessionId、turnId、traceId 和业务参数；projectId、workspaceId、conversationId 只允许作为显式筛选或兼容 metadata 输入。 | | 受控资源 | API path、schema、route policy、AuthPrincipal 摘要、错误码、响应摘要和兼容性契约。 | -| 外部输出 | JSON 响应、HTTP status、route、actor、业务标识、错误分类、脱敏状态、trace/result 指针和下一步查询提示。 | +| 外部输出 | JSON 响应、HTTP status、`traceparent`、`x-hwlab-otel-trace-id`、`x-request-id`、route、actor、业务标识、错误分类、脱敏状态、trace/result 指针和下一步查询提示。 | | 用户接口 | Cloud Web 同源 API、HWLAB CLI 同源 REST request/client 命令、HTTP API。 | | 系统边界 | API契约负责接口形态和错误表达；不拥有用户、Agent、硬件、CaseRun、账本或发布事实。 | @@ -226,6 +230,41 @@ API契约应保证成功和失败都以可定位 JSON 形式表达，至少包 默认响应不得输出爆炸或泄漏敏感值；需要完整 trace、原始响应或长日志时，必须通过显式展开参数、下载入口或已有业务产物获取。错误输出只负责说明失败，不替代缺失能力实现。 +Cloud API 请求入口必须统一 extract 或 create W3C `traceparent`，并把 OTel trace id、span id、request id、route 和 serviceId 绑定到同一次 request context。所有 200、4xx 和 5xx 响应都必须带 `traceparent`、`x-hwlab-otel-trace-id` 和 `x-request-id`；业务 handler、dependency client、dev-entrypoint proxy、AgentRun adapter、user-billing、HWPOD 或其他下游调用只能传播该 context，不能在同一请求内随机生成第二个用户可见 trace id。 + +用户可见 API 失败响应应统一使用 `HwlabErrorEnvelope` 或等价结构： + +```ts +interface HwlabErrorEnvelope { + ok: false; + status: number | "failed"; + error: { + code: string; + message: string; + userMessage?: string; + category?: string; + layer?: string; + retryable?: boolean; + diagnostic: { + traceId: string | null; + spanId?: string | null; + requestId?: string | null; + route?: string | null; + serviceId?: string | null; + observedAt: string; + valuesRedacted: true; + }; + }; + valuesRedacted: true; +} +``` + +`error.message` 和 `error.userMessage` 只承载用户可理解文案；`error.diagnostic.traceId` 承载可复制的 OTel trace id。响应不得向用户外显 `tracestate`、`baggage`、cookie、API key、完整 Authorization header、DB DSN、provider token、prompt、assistant 正文、tool 参数、stdout/stderr 长段、raw upstream payload 或可复用凭据。`traceparent` 可作为标准 header 返回，但默认页面只展示 `trace_id` 字段。 + +错误 envelope 的结构化日志必须记录同一 `trace_id`、`request_id`、`error.code`、route、status 和 layer，使日志、span 和用户错误诊断能关联。`trace_id` 不得作为 Prometheus label；如需 metrics 关联，只能通过低基数 route/status/code label、exemplar 或受控 debug payload 承载。 + +Workbench 投影 blocker、proxy timeout、鉴权失败、provider profile、web-performance、全局 route exception 和 dev-entrypoint proxy 错误都应映射到同一 envelope。历史 `{ error: string }` 字段可在迁移期作为 `userMessage` 展示兼容，但不得成为唯一错误事实；新增用户可见错误路径禁止只返回裸字符串、`reason` 或未脱敏 raw exception。 + ## 7. 过程控制 本规格不单独索引过程 issue；跨 L1 的内测、灰度和阶段活动索引统一保留在 [PJ2026-01 HWLAB 总规格](PJ2026-01-HWLAB.md) 的 `7. 过程控制`。 diff --git a/project-management/PJ2026-01/specs/PJ2026-0106-platform-ops.md b/project-management/PJ2026-01/specs/PJ2026-0106-platform-ops.md index ac4387d9..f5f2b311 100644 --- a/project-management/PJ2026-01/specs/PJ2026-0106-platform-ops.md +++ b/project-management/PJ2026-01/specs/PJ2026-0106-platform-ops.md @@ -41,7 +41,7 @@ - YAML-first 自动化分布式运维，包括 target、lane、node、service 声明、render、validate、受控下发和配置可见性。 - YAML-first 运维下的 SecretRef 子项，包括 sourceRef、targetKey、fingerprint、presence、轮换和敏感输出约束。 - FRP、Caddy、domain、TLS、public health 和公开入口漂移处理。 -- Prometheus metrics、scrape target、alert rule、服务健康指标、资源指标和运行面监控口径。 +- Prometheus metrics、OpenTelemetry tracing、scrape target、alert rule、服务健康指标、资源指标、trace backend 查询和运行面监控口径。 ### 2.3 范围外 @@ -61,7 +61,8 @@ | YAML-first | UniDesk 自有配置以 YAML 为真相源，运行面和 CLI 从 YAML 渲染、校验并受控下发。 | | SecretRef | YAML-first 运维中的密钥声明子项，指向密钥来源和目标 key，运行输出只披露摘要和存在性。 | | 公开入口 | FRP、Caddy、域名、TLS 和健康检查共同形成的外部访问面。 | -| Prometheus 运维监控 | 通过 Prometheus 采集 metrics、维护 scrape target、alert rule 和服务健康指标的运维监控能力。 | +| 运维监控 | 通过 Prometheus 采集 metrics、通过 OpenTelemetry 关联 trace/span，并维护 scrape target、trace backend、alert rule 和服务健康指标的运维监控能力。 | +| Trace Explorer URL 模板 | YAML-first 运维配置中声明的 trace backend 打开链接模板，只允许静态 URL 与 `{trace_id}` 占位符，用于客户端展示“打开 Trace”。 | ## 4. 系统边界和接口 @@ -70,11 +71,11 @@ | 边界项 | 内容 | | --- | --- | | 外部使用者 | HWLAB 各 L1 模块、平台管理员、发布操作人员和需要运行状态的自动化任务。 | -| 外部输入 | Git commit、PR merge、镜像产物、YAML 配置、SecretRef 子项、公开入口声明、metrics endpoint、服务健康指标和运行状态查询。 | -| 受控资源 | CI/CD pipeline、Git mirror、运行 lane、Kubernetes 资源、YAML-first 运维配置、SecretRef 下发、FRP/Caddy、Prometheus scrape target、metrics 和 alert rule。 | -| 外部输出 | 发布状态、source commit、配置渲染结果、Secret 摘要、public URL health、Prometheus target 状态、metrics 查询结果、alert 状态和运行支撑记录。 | -| 用户接口 | UniDesk CLI、HWLAB 控制面命令、受控 Secret 命令、平台基础设施命令、Prometheus 查询和告警入口。 | -| 系统边界 | 平台运维负责交付、YAML-first 自动化分布式运维、入口和 Prometheus 运维监控可控；不定义硬件、Agent、Harness、客户端或用户管理的业务成功标准。 | +| 外部输入 | Git commit、PR merge、镜像产物、YAML 配置、SecretRef 子项、公开入口声明、metrics endpoint、OTLP endpoint、Trace Explorer URL 模板、服务健康指标和运行状态查询。 | +| 受控资源 | CI/CD pipeline、Git mirror、运行 lane、Kubernetes 资源、YAML-first 运维配置、SecretRef 下发、FRP/Caddy、Prometheus scrape target、OTel Collector、trace backend、metrics 和 alert rule。 | +| 外部输出 | 发布状态、source commit、配置渲染结果、Secret 摘要、public URL health、Prometheus target 状态、metrics 查询结果、trace 查询摘要、Trace Explorer URL 模板摘要、alert 状态和运行支撑记录。 | +| 用户接口 | UniDesk CLI、HWLAB 控制面命令、受控 Secret 命令、平台基础设施命令、Prometheus 查询、OpenTelemetry trace 查询和告警入口。 | +| 系统边界 | 平台运维负责交付、YAML-first 自动化分布式运维、入口、Prometheus metrics 和 OpenTelemetry tracing 可控；不定义硬件、Agent、Harness、客户端或用户管理的业务成功标准。 | ## 5. 内部分工与规格索引 @@ -84,7 +85,7 @@ | 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 | 公开入口 | [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 | +| PJ2026-010605 | 运维监控 | [PJ2026-010605 运维监控](PJ2026-010605-observability-monitoring.md) | Prometheus metrics、OpenTelemetry tracing、scrape target、trace backend、alert rule、服务健康指标和资源指标 | 运行面 metrics endpoint、OTLP endpoint、各 L1 服务健康指标和关键请求 span | 全部 L1 | ## 6. 原子需求 @@ -136,8 +137,10 @@ YAML-first 运维的命令输出只能披露摘要、对象名、key 名、sourc | --- | --- | --- | --- | | 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 和服务健康指标表达服务状态与资源状态。 +平台运维应提供基于 Prometheus 和 OpenTelemetry 的运维监控能力，使 HWLAB 运行面能够通过 metrics endpoint、scrape target、OTLP endpoint、trace backend、alert rule 和服务健康指标表达服务状态、资源状态和单次请求因果链。 -Prometheus 运维监控只负责运维指标、采集目标、告警规则和监控口径。各 L1 提供自身服务健康指标和运行需求；平台运维负责把这些指标接入 Prometheus 并维护可查询、可告警的监控面。 +运维监控只负责运维指标、采集目标、trace backend、告警规则和监控口径。各 L1 提供自身服务健康指标、关键请求 span 语义和运行需求；平台运维负责把 metrics 接入 Prometheus，把 trace/span 接入 OpenTelemetry，并维护可查询、可告警、可回溯的监控面。 -Prometheus 监控不能替代业务功能实现、CaseRun 评价、Agent 状态模型、硬件事实或用户账本。业务成功仍由对应 L1 定义，监控只用于运行面健康和资源状态判断。 +运维监控不能替代业务功能实现、CaseRun 评价、Agent 状态模型、硬件事实或用户账本。业务成功仍由对应 L1 定义，监控只用于运行面健康、资源状态和单次请求因果链排障。 + +Trace Explorer URL 模板、OTLP endpoint、采样/导出开关、trace backend endpoint、Collector/Tempo/Jaeger/Grafana 等组件镜像和保留策略必须归属 YAML-first 运维配置；SPEC 只定义能力和脱敏边界，不硬编码具体 URL、token、namespace、采样率或保留周期。运行面对象和 trace 查询结果只能作为观测证据，不能反推为配置真相。 diff --git a/project-management/PJ2026-01/specs/PJ2026-010605-observability-monitoring.md b/project-management/PJ2026-01/specs/PJ2026-010605-observability-monitoring.md index 0498789f..76d6000a 100644 --- a/project-management/PJ2026-01/specs/PJ2026-010605-observability-monitoring.md +++ b/project-management/PJ2026-01/specs/PJ2026-010605-observability-monitoring.md @@ -58,6 +58,7 @@ | 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。 | | 用户可感知性能 | 用户在 Web、CLI 或 API 入口中直接感受到的等待时间、加载时间、首个可读内容出现时间和完整可用状态。 | @@ -75,7 +76,7 @@ | 外部使用者 | 平台管理员、发布操作人员、值守自动化、需要运行状态的各 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 查询结果、运行健康摘要、入口健康摘要和 redacted 失败阶段。 | +| 外部输出 | target 状态、metrics 查询结果、alert 状态、trace 查询结果、Trace Explorer URL 模板摘要、运行健康摘要、入口健康摘要和 redacted 失败阶段。 | | 用户接口 | Prometheus 查询、OpenTelemetry trace 查询、受控平台运维 CLI、发布状态摘要和各 L1 health/status 页面或命令。 | | 系统边界 | 运维监控负责运行面可观察、告警和单次请求因果链；不定义业务完成标准，不保存默认长证据，不把监控 green 或 trace 可查当作业务通过。 | @@ -169,7 +170,9 @@ sequenceDiagram #### 6.1.4 YAML 与 CLI 归属 -OTel Collector、trace backend、target route、namespace、image、storage、retention、sampling、endpoint、probe 和应用接入关系必须进入 `config/platform-infra/observability.yaml` 或后续确认的 owning YAML。正式入口必须是 `bun scripts/cli.ts platform-infra observability plan|apply|status|validate|trace` 或等价受控 CLI；`trans :k3s` 只能作为有界诊断底座，不能成为长期 mutate path。 +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 :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 至少覆盖： @@ -183,6 +186,8 @@ OTel Collector、trace backend、target route、namespace、image、storage、re 统一 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。 diff --git a/project-management/PJ2026-01/specs/PJ2026-01060505-workbench-performance.md b/project-management/PJ2026-01/specs/PJ2026-01060505-workbench-performance.md index e83efb64..a5dfb16c 100644 --- a/project-management/PJ2026-01/specs/PJ2026-01060505-workbench-performance.md +++ b/project-management/PJ2026-01/specs/PJ2026-01060505-workbench-performance.md @@ -19,7 +19,7 @@ | 短名 | Workbench性能 | | 层级 | L3 子课题 | | 状态 | 已生效 | -| 实现引用版本 | draft-2026-06-19-p0 | +| 实现引用版本 | draft-2026-06-19-p0; draft-2026-06-20-p0-error-diagnostics | | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | | 上级规格 | [PJ2026-010605 运维监控](PJ2026-010605-observability-monitoring.md) | | 关联规格 | [PJ2026-010401 Web工作台](PJ2026-010401-web-workbench.md)、[PJ2026-010403 API契约](PJ2026-010403-api-contract.md)、[PJ2026-010205 HWLAB接入](PJ2026-010205-hwlab-dispatch.md) | @@ -46,6 +46,7 @@ Workbench性能负责把 HWLAB Cloud Web 工作台中用户直接感知的等待 - Workbench REST、SSE、trace pagination、turn snapshot、API proxy、AgentRun adapter 操作的常规 RED 指标。 - 运行中 Code Agent turn 的无响应空闲时间、最近活动时间和投影刷新活性口径；该口径只衡量“多久没有新事实或可见进展”，不把 turn 总运行时长作为前端超时。 - 前端 RUM 与后端 Prometheus 指标的关联键、脱敏边界、低基数 label、histogram bucket、recording rule 和低样本告警边界。 +- 用户可见错误诊断中的 OTel `trace_id` 与性能观测的关联边界：trace id 可以进入错误诊断、日志、span 和受控 debug payload，不进入 Prometheus label、RUM 默认维度或 `/performance` 默认表格。 - 权威 observation history 或等价 read model、时间窗口查询、窗口内精确分位、桶化估算标记、样本数、freshness、source family 和数据质量字段。 - UniDesk YAML-first ops 形式的 D601 v0.3 Workbench 监控接入、scrape/render/status/summary CLI、告警/recording rule 配置和受控运维验证。 - D601 v0.3 Cloud Web `/performance` 性能监控工作台：以同一权威 summary/series 数据源展示中文化概览卡、趋势图、分布图、TopN 排行、数据新鲜度、采集健康和可访问表格 drill-down。 @@ -86,6 +87,7 @@ Workbench性能负责把 HWLAB Cloud Web 工作台中用户直接感知的等待 | 告警准入 | 指一个指标进入内部告警前必须满足的可信度条件，包括样本数量、freshness、窗口持续性、sourceFamily 和采集健康；低样本或暂无数据默认不能触发性能慢路径告警。 | | 性能监控工作台 | Cloud Web `/performance` 中面向管理员和值守人员的 dashboard 视图，用概览卡、趋势、分布、排行和表格 drill-down 展示 Workbench/RUM/API/Long Task 性能健康。 | | 低基数 label | Prometheus label 只能取有限稳定集合，例如 route template、journey、phase、eventKind、status，不包含 traceId、sessionId、runId 或用户输入。 | +| 诊断 trace_id | 用户可见错误诊断中的 OTel trace id，用于跳转 trace backend 和关联日志/span；它是高基数排障标识，只能进入 diagnostic、日志、span attribute、exemplar 或受控 debug payload，不得作为 Prometheus/RUM 默认聚合维度。 | | YAML-first UniDesk ops | UniDesk 自有运维事实先进入 YAML，再由受控 CLI 渲染、校验和下发；运行面对象只作为观测面，不反推配置真相。 | ## 4. 系统边界和接口 @@ -329,6 +331,8 @@ Workbench性能应至少提供以下 Prometheus 指标族：`hwlab_workbench_jou API 响应可使用 `Server-Timing` 暴露后端 phase 摘要，但该 header 只能包含阶段名和 duration，不包含敏感值或高基数 ID。 +用户可见错误的 OTel `trace_id` 不属于性能指标 label。它可以作为日志与 span 的 correlation 字段，也可以在支持 exemplar 的指标链路中作为受控 exemplar 或 debug payload 关联一次观测，但 `/performance` 默认 summary、TopN、chart series、problem row 和 RUM 上报维度不得按 trace id、request id、session id、run id 或用户输入聚合。需要从性能页面跳到单次 trace 时，必须通过用户显式点击错误诊断或受控 drill-down，而不是把高基数字段暴露成默认维度。 + ### 6.5 OPS-WBPERF-REQ-005 YAML-first UniDesk ops | 编号 | 短名 | 主责模块 | 关联模块 | @@ -383,6 +387,8 @@ Performance dashboard 的图表、表格、概览卡、tooltip、legend、空状 Performance 指标展示必须保持低基数和脱敏。默认 label、图表维度、TopN 名称和表格列不得包含 sessionId、traceId、runId、conversationId、userId、prompt、assistant 正文、tool 参数、stdout/stderr、Secret、token、DSN 或账号身份。长 route、event type、problem、outcome、statusClass 等维度必须使用 template、归一化枚举或低基数中文映射；无法确认脱敏的字段只能进入受控诊断证据，不得进入默认 dashboard。 +当 `/performance` 展示 API 错误率、proxy timeout 或 Workbench blocker 相关行时，默认只展示低基数 route template、status class、error code、layer、sample count 和窗口质量。单个 `trace_id` 只能在用户展开受控诊断或跳转到错误详情时显示，且必须与 [PJ2026-010403 API契约](PJ2026-010403-api-contract.md) 的 `HwlabErrorEnvelope` 脱敏边界一致。 + ### 6.9 OPS-WBPERF-REQ-009 单一权威观测模型 | 编号 | 短名 | 主责模块 | 关联模块 |