From 6d4d18bd59674f1ed331a4fa1fc7a358aae4803c Mon Sep 17 00:00:00 2001 From: Codex Date: Wed, 17 Jun 2026 15:12:43 +0000 Subject: [PATCH] docs: add workbench turn status budget spec --- .../PJ2026-01060505-workbench-performance.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) 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 104614ed..d8013e1b 100644 --- a/project-management/PJ2026-01/specs/PJ2026-01060505-workbench-performance.md +++ b/project-management/PJ2026-01/specs/PJ2026-01060505-workbench-performance.md @@ -247,6 +247,7 @@ session 切换必须分别记录 `first_visible` 和 `full_load`。first visible | PJ2026-0106050504 | Prometheus指标 | 本规格 6.4 | histogram/counter/gauge、低基数 label、Server-Timing 和 RED 指标 | 运维监控、API契约 | Dashboard、recording rule | | PJ2026-0106050505 | YAML运维 | 本规格 6.5 | UniDesk owning YAML、ops CLI、shared helper、scrape/rule/status/summary 渲染和运行面观测边界 | YAML运维、平台运维 | D601 v0.3 运维监控接入 | | PJ2026-0106050506 | 代码引用 | 本规格 6.6 | SPEC-first、代码文件头部 SPEC 标注和 issue 回写要求 | 规格治理、全部实现模块 | 后续实现和 review | +| PJ2026-0106050507 | TurnStatus预算 | 本规格 6.7 | turn status、trace refresh 和 AgentRun result/events 同步的用户可感知预算 | API契约、HWLAB接入、Agent编排 | Web poll、TraceTimeline、性能回归 | ## 6. 原子需求 @@ -314,8 +315,20 @@ UniDesk CLI 应提供薄 domain 入口，例如 `hwlab nodes observability plan| 实现文件不得只写 issue 编号、`latest`、`current` 或“按最新方案”作为规格引用。自动生成文件、第三方 vendored 文件、纯 YAML/config、锁文件和无法承载注释头的二进制产物不要求加源码头部，但对应生成器、渲染器或配置入口必须能追溯到本 SPEC。 +### 6.7 OPS-WBPERF-REQ-007 Turn status 快速返回预算 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| OPS-WBPERF-REQ-007 | TurnStatus预算 | PJ2026-0106050507 TurnStatus预算 | [API契约](PJ2026-010403-api-contract.md)、[HWLAB接入](PJ2026-010205-hwlab-dispatch.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[Web工作台](PJ2026-010401-web-workbench.md) | + +`/v1/agent/turns/:traceId` 是 Workbench TraceTimeline 和消息运行态的用户可见 poll 权威入口。该入口必须优先返回当前已知 turn snapshot、runnerTrace、finalResponse 或结构化 degraded reason，不得把一次 Web poll 同步阻塞在 AgentRun result/events 刷新、provider trace 拉取或后台 read model 补洞上。 + +Cloud API 可以在 turn status 请求内尝试刷新 AgentRun result/events，但刷新必须有独立的短预算；预算、开关和后续调整必须来自 YAML/env 配置，不得把具体数值写成第二真相。预算耗尽时，API 应返回已有快照并标记 `turn_status_degraded`、`agentrun_result_poll_failed`、`trace_refresh_timeout` 或等价低基数错误，后续 poll、SSE 或后台刷新仍可继续补齐最新事件。除非权限不匹配、trace 不存在或请求参数非法，turn status 不应因为上游刷新慢而让 Web 客户端超时。 + +该需求不得削弱功能正确性：terminal result、billing finalize、session owner record、conversation fact 和 trace terminal evidence 仍由最终同步或后续 poll 完成；快速返回只限制单次用户可见 poll 的等待预算，不丢弃 AgentRun 事实、不伪造 final response、不把未完成 turn 标记为完成。 + ## 7. 过程控制 -本规格的执行 issue 为 [HWLAB #1392](https://github.com/pikasTech/HWLAB/issues/1392)。该 issue 的 P0 阶段必须以本 SPEC 为前置：先确认本规格、父级 [PJ2026-010605 运维监控](PJ2026-010605-observability-monitoring.md)、[PJ2026-010401 Web工作台](PJ2026-010401-web-workbench.md) 和 [PJ2026-010403 API契约](PJ2026-010403-api-contract.md) 的引用关系，再进入后续实现。 +本规格的执行 issue 为 [HWLAB #1392](https://github.com/pikasTech/HWLAB/issues/1392)，性能问题修复执行 issue 为 [HWLAB #1422](https://github.com/pikasTech/HWLAB/issues/1422)。该类 issue 的 P0 阶段必须以本 SPEC 为前置：先确认本规格、父级 [PJ2026-010605 运维监控](PJ2026-010605-observability-monitoring.md)、[PJ2026-010401 Web工作台](PJ2026-010401-web-workbench.md) 和 [PJ2026-010403 API契约](PJ2026-010403-api-contract.md) 的引用关系，再进入后续实现。 后续实现 issue 或 PR 收口时必须回写：使用的 SPEC 编号和实现引用版本、触达的源码文件头部标注情况、Prometheus 指标/label 审查结果、D601 v0.3 public origin 的原入口验证结果，以及是否需要继续修订本规格。