docs: align HWLAB runtime references with G14

This commit is contained in:
Codex
2026-05-26 08:08:43 +08:00
parent 025c9a7197
commit 24e0b94a09
11 changed files with 63 additions and 59 deletions
+5 -5
View File
@@ -6,9 +6,9 @@ Secret 或 token。
## 运行边界
- DEV Cloud Web 入口是 `http://74.48.78.17:16666/`,同源代理到
- DEV Cloud Web 入口是 `http://74.48.78.17:17666/`,同源代理到
`/v1/agent/chat`
- DEV API/edge 入口是 `http://74.48.78.17:16667/`;它不能替代 Workbench
- DEV API/edge 入口是 `http://74.48.78.17:17667/`;它不能替代 Workbench
同源聊天入口的真实回复证据。
- `internal/cloud/code-agent-chat.mjs``/v1/agent/chat` 的后端处理入口。
- `scripts/code-agent-chat-smoke.mjs` 是 Code Agent chat schema 与 readiness
@@ -100,7 +100,7 @@ Workbench trace 对已知 JSON-RPC gateway 响应应按普通 tool call 展示
Workbench 与 Code Agent 的用户请求必须是短连接 submit + 短连接 result/trace 轮询;浏览器或 cloud-web 不应持有一次长 HTTP 请求等待整个 Codex turn 结束。`POST /v1/agent/chat` 返回 `202` 后,前端轮询 `/v1/agent/chat/result/<traceId>` 获取终态,并用 `/v1/agent/chat/trace/<traceId>` 刷新可视 trace。
cloud-web 同源代理必须把短连接语义原样转发给 cloud-api,至少包括 `Prefer: respond-async``X-HWLAB-Short-Connection``X-Trace-Id`。如果这些 header 在 cloud-web 层被过滤,cloud-api 会把同一个请求当成长同步请求处理,用户入口会表现为 16666 卡住或代理超时,而 16667 直连 cloud-api 正常。此类问题应先比对同一 trace 在 16666 与 16667 的 submit 行为,再修代理 header 透传,而不是调大前端等待时间。
cloud-web 同源代理必须把短连接语义原样转发给 cloud-api,至少包括 `Prefer: respond-async``X-HWLAB-Short-Connection``X-Trace-Id`。如果这些 header 在 cloud-web 层被过滤,cloud-api 会把同一个请求当成长同步请求处理,用户入口会表现为 `17666` 卡住或代理超时,而 `17667` 直连 cloud-api 正常。此类问题应先比对同一 trace 在 `17666``17667` 的 submit 行为,再修代理 header 透传,而不是调大前端等待时间。
`/v1/agent/chat/result/<traceId>` 是终态摘要接口,不是完整 trace 下载接口。它可以携带压缩后的 `runnerTrace` 窗口用于传输保活,但 Workbench 用户界面不得把该窗口显示为“压缩窗口”或“显示全部”。只要结果或轮询快照声明 `eventsCompacted=true`,前端必须自动请求 `/v1/agent/chat/trace/<traceId>` 并用完整 trace 替换可视事件线;回放完成前只能显示“完整 trace 回放中/当前已载入”状态。result 响应仍必须保留 `eventCount``lastEvent``providerTrace``threadId/sessionId` 和终态 reply/blocker;完整 trace 只能从 `/v1/agent/chat/trace/<traceId>`、复制 JSON 或下载 trace 入口取得。默认 result trace 窗口上限由 `HWLAB_CODE_AGENT_RESULT_TRACE_EVENT_LIMIT` 控制;不要把数百个大 chunk 原样塞进 result 响应,避免 cloud-web 代理层或浏览器 fetch 把“正常执行中的大响应”表现成 503、非 JSON 或空响应。
@@ -160,7 +160,7 @@ Workbench 静态接线检查:
```sh
node scripts/dev-cloud-workbench-smoke.mjs --static
node scripts/dev-cloud-workbench-smoke.mjs --dom-only --url http://74.48.78.17:16666/
node scripts/dev-cloud-workbench-smoke.mjs --dom-only --url http://74.48.78.17:17666/
```
该命令验证 Workbench 默认页、同源只读边界和 `/v1/agent/chat` 前端主流程接线。它只产出
@@ -171,7 +171,7 @@ node scripts/dev-cloud-workbench-smoke.mjs --dom-only --url http://74.48.78.17:1
授权凭证注入后的真实 DEV 复测:
```sh
node scripts/code-agent-chat-smoke.mjs --live --url http://74.48.78.17:16666/
node scripts/code-agent-chat-smoke.mjs --live --url http://74.48.78.17:17666/
```
`--live` 会向真实 DEV `/v1/agent/chat` 发送一条最小聊天请求。输出只包含