docs: specify trace pagination behavior

2026-06-16 15:28:35 +00:00
parent 548e51d146
commit 18dea37248
2 changed files with 5 additions and 3 deletions
@@ -153,7 +153,7 @@ 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 应通过 RESTful trace resource 自动请求完整可读事件，而不是让用户手工从原始日志中恢复上下文。
+工作台在增量刷新 trace、message 或 status 时，应保持用户已展开的详情状态和滚动位置。trace 压缩、sourceSeq 窗口或 event cap 只能影响默认摘要，不得吞掉可读 message、tool call、stderr/error 或 terminal 边界；需要完整事件时，Web 应通过 RESTful trace resource 自动请求完整可读事件，而不是让用户手工从原始日志中恢复上下文。RESTful trace resource 返回 `hasMore`、`nextSinceSeq` 或等价游标时，Web 必须继续通过同一资源入口分片请求，并在每个片段到达后立即合并渲染；不得等所有片段全部拉完才一次性显示，也不得为了补齐事件切换到 JSON-RPC、回放 Trace、内部 manager 或前端 fallback 路径。

 ### 6.6 CLIENT-WB-REQ-006 Trace阅读

@@ -165,13 +165,13 @@ Web工作台应提供面向用户的 Trace阅读视图，使用户默认看到

 Trace阅读视图必须把 trace id、session、thread、run、command、event count、hidden count、raw event、follow/pause 和审计类控制收束到 Agent 消息头部右上角的消息详情入口。Trace 展开体只允许展示用户可读的运行记录本体，不得直接渲染 trace meta panel、身份 chip、隐藏事件统计、噪声聚合说明、原始事件开关或跟随/到底部等调试控件；这些内容只有在用户点击消息详情入口后才可见。

-Web 工作台在会话恢复、session 切换、turn running、turn completed 或消息卡片重建时，必须按 traceId 自动调用 `GET /v1/agent/traces/{traceId}` 补齐 Trace阅读视图。`pending` 状态应展示加载转圈；completed 消息即使 final response 已可见，也必须自动加载对应 trace events，不得停留在空的“思考中...”记录。用户界面不得提供“回放 Trace”作为加载完整 trace 的必要操作。
+Web 工作台在会话恢复、session 切换、turn running、turn completed 或消息卡片重建时，必须按 traceId 自动调用 `GET /v1/agent/traces/{traceId}` 补齐 Trace阅读视图。`pending` 状态应展示加载转圈；completed 消息即使 final response 已可见，也必须自动加载对应 trace events，不得停留在空的“思考中...”记录。分片未拉完属于“加载中”，已经完成加载但仍无可读 Code Agent 消息才属于“思考中”。用户界面不得提供“回放 Trace”作为加载完整 trace 的必要操作。

 工具调用和命令输出行必须正文优先：时间、状态、tool 名称和耗时只作为紧凑 header，不得占用独立左列或固定半屏宽度；stdout、stderr、error、patch、命令结果和助手 Markdown 应获得完整可用宽度。终端完成行和 Agent 最终消息应显示真实轮次耗时，耗时来源应使用 trace 事实、首尾事件时间或服务端 elapsed 字段，不得在已完成运行中显示 `00:00:00` 这类伪完成耗时。

 Trace阅读视图属于工作态高密度界面。重复 trace row、message card、trace panel、warning 和 inline code 的圆角、间距和 padding 应保持紧凑；默认视觉层级以内容可扫读为主，不使用大圆角、大留白、嵌套卡片或装饰性布局制造工作区浪费。原始 trace 仍必须可审计，但只能作为消息详情入口中的主动展开内容，不得成为默认阅读面或 Trace 展开体的一部分。

-Trace阅读视图必须跟随 Code Agent turn 生命周期自动调整展开状态：任务开始、pending 转 running 或首次出现运行中 trace 时，工作台应自动展开对应 trace，使用户能立即看到进展；任务进入 completed、failed、canceled、timeout、blocked 或出现 final response 等终态时，工作台应自动折叠对应 trace，回到正文和最终结果优先的阅读状态。自动折叠不得删除 trace、隐藏错误或阻止用户手动重新展开查看详情。
+Trace阅读视图必须跟随 Code Agent turn 生命周期自动调整展开状态：任务开始、pending 转 running 或首次出现运行中 trace 时，工作台应自动展开对应 trace，使用户能立即看到进展；运行中的 turn 进入 completed、failed、canceled、timeout、blocked 或出现 final response 等终态时，工作台应自动折叠对应 trace，回到正文和最终结果优先的阅读状态。自动折叠不得删除 trace、隐藏错误或阻止用户手动重新展开查看详情。若会话或 trace 在补拉前已经处于 final/terminal 状态，后续历史分片补拉完成不得触发自动折叠，也不得覆盖用户手动展开或折叠状态。

 命令输入区应提供单一主按钮承载当前 turn 的主要动作：没有运行中 turn 时为发送新 Turn；存在运行中 turn 且输入框为空时为取消；存在运行中 turn 且输入框非空时为 Steer。工作台不得在运行已结束后继续显示独立的“取消运行中 Trace”按钮，也不得让发送、取消和 Steer 以多个并列主动作长期同时出现。

@@ -120,6 +120,8 @@ Agent 接口不得通过 session latest、浏览器历史、旧 cache 或内部

 Trace 查询必须采用无状态 RESTful 资源形态：`GET /v1/agent/traces/{traceId}` 是客户端读取 Code Agent trace events、runnerTrace、terminalEvidence、finalResponse 和 traceSummary 的权威入口。请求只依赖 method、path、query、auth 主体和后端业务事实；Web 不得使用动作式 `/v1/agent/chat/trace/{traceId}` 作为恢复会话、切换 session 或 completed 消息加载 trace 的前端路径，也不得把浏览器 workspace snapshot、localStorage 或消息 stub 拼成 trace 响应。

+Trace resource 必须支持按事件位置继续读取，例如 `sinceSeq` / `cursor` 与 `limit` 这类 query 参数。服务端返回超长 trace 时应按完整事件边界截断，并在同一个资源响应中给出 `range`、`hasMore`、`nextSinceSeq` 或等价阶段性位置，使客户端可以继续请求下一段；响应不得返回半条事件，不得要求 JSON-RPC、回放按钮、内部 manager path 或第二套 trace endpoint 才能补齐完整可读事件。分页请求必须保持无状态和幂等：同一 `traceId`、同一位置参数、同一权限主体下重复请求不得污染 trace 事实。
+
 `POST /v1/agent/chat`、`GET /v1/agent/turns/{traceId}` 和 result 入口可以返回 `traceUrl` 指针，但该指针必须指向 RESTful trace resource。trace resource 可以为了短返回默认裁剪事件，但完整事件补齐、终态 final response、AgentRun run/command identity、错误和脱敏边界仍由同一 trace resource 表达；客户端不得要求用户手动“回放 Trace”才能获得完成态 trace。

 ### 6.4 CLIENT-API-REQ-004 资源与管理接口