From 548e51d14608e3d74a92d64986ed30612bd58a6f Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 16 Jun 2026 13:58:34 +0000 Subject: [PATCH] docs: define Code Agent trace resource API --- .../PJ2026-01/specs/PJ2026-010401-web-workbench.md | 6 ++++-- .../PJ2026-01/specs/PJ2026-010403-api-contract.md | 4 ++++ 2 files changed, 8 insertions(+), 2 deletions(-) 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 58c31359..3b28e772 100644 --- a/project-management/PJ2026-01/specs/PJ2026-010401-web-workbench.md +++ b/project-management/PJ2026-01/specs/PJ2026-010401-web-workbench.md @@ -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 应通过 trace/result API 主动请求完整可读事件，而不是让用户手工从原始日志中恢复上下文。 +工作台在增量刷新 trace、message 或 status 时，应保持用户已展开的详情状态和滚动位置。trace 压缩、sourceSeq 窗口或 event cap 只能影响默认摘要，不得吞掉可读 message、tool call、stderr/error 或 terminal 边界；需要完整事件时，Web 应通过 RESTful trace resource 自动请求完整可读事件，而不是让用户手工从原始日志中恢复上下文。 ### 6.6 CLIENT-WB-REQ-006 Trace阅读 @@ -163,7 +163,9 @@ Web只负责浏览器交互与展示；CLI负责命令入口和结构化输出 Web工作台应提供面向用户的 Trace阅读视图，使用户默认看到从第一条有意义的助手消息、工具调用或最终结果开始的可读执行过程，而不是 request accepted、session reuse、thread/run/command 创建、runner job、backend 状态、token/chunk 或隐藏事件统计。 -Trace阅读视图必须把 trace id、session、thread、run、command、event count、hidden count、raw event、replay、follow/pause 和审计类控制收束到 Agent 消息头部右上角的消息详情入口。Trace 展开体只允许展示用户可读的运行记录本体，不得直接渲染 trace meta panel、身份 chip、隐藏事件统计、噪声聚合说明、原始事件开关或跟随/到底部等调试控件；这些内容只有在用户点击消息详情入口后才可见。 +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 的必要操作。 工具调用和命令输出行必须正文优先：时间、状态、tool 名称和耗时只作为紧凑 header，不得占用独立左列或固定半屏宽度；stdout、stderr、error、patch、命令结果和助手 Markdown 应获得完整可用宽度。终端完成行和 Agent 最终消息应显示真实轮次耗时，耗时来源应使用 trace 事实、首尾事件时间或服务端 elapsed 字段，不得在已完成运行中显示 `00:00:00` 这类伪完成耗时。 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 8c370055..11ecf1b0 100644 --- a/project-management/PJ2026-01/specs/PJ2026-010403-api-contract.md +++ b/project-management/PJ2026-01/specs/PJ2026-010403-api-contract.md @@ -118,6 +118,10 @@ API契约应定义显式 Agent session、chat、steer、cancel、result、trace Agent 接口不得通过 session latest、浏览器历史、旧 cache 或内部 manager 生成第二套 final response。Agent编排提供执行事实，用户管理校验 owner 和权限，客户端只稳定暴露用户入口。 +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 响应。 + +`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 资源与管理接口 | 编号 | 短名 | 主责模块 | 关联模块 |