docs: add workbench turn status budget spec
This commit is contained in:
Codex
@@ -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 的原入口验证结果，以及是否需要继续修订本规格。
|
||||
|
||||
Reference in New Issue
Block a user