mirrors/pikasTech-unidesk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 收敛 workbench 会话恢复权威 API

Browse Source
This commit is contained in:
Codex
2026-06-16 22:56:25 +00:00
parent bd7f590543
commit 3a12063f25
2 changed files with 20 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files
project-management/PJ2026-01/specs/PJ2026-010401-web-workbench.md
+8 -5
View File
@@ -62,7 +62,8 @@ Web工作台负责 HWLAB 登录后的浏览器主入口，使用户能够在同
| 诊断入口 | 用户主动打开的工作台状态详情入口，通常以 topbar 内的小型按钮或状态图标呈现。 |
| 低噪声展示 | 诊断、trace、状态和辅助信息不抢占主任务区，也不伪装成用户或 Agent 正文。 |
| 响应式工作台 | 同一工作台在桌面和移动端按不同可视空间重排，但仍优先保证任务输入和状态理解。 |
| 同源业务入口 | Cloud Web 与 HWLAB CLI 通过同一 Web origin、相对 API path 和业务标识访问 HWLAB 能力的入口。 |
| 同源业务入口 | Cloud Web 与 HWLAB CLI 通过同一 Web origin、相对 REST/JSON API path 和业务标识访问 HWLAB 能力的入口。 |
| Conversation权威入口 | Web 工作台按 conversationId 恢复当前会话消息、session 绑定、thread、lastTraceId 和状态的 RESTful detail API。 |
| 共享 trace renderer | Web trace 面板和 HWLAB CLI `trace --render web` 共用的 trace row 转换语义。 |
| Trace阅读视图 | 工作台中面向用户阅读 Code Agent trace 的默认视图，只展示用户可理解的助手消息、工具调用、命令输出、最终结果和真实耗时，把运行身份、隐藏统计和原始事件收束到消息详情入口。 |
| 消息详情入口 | Agent 消息头部右上角的小型详情按钮，用于按需查看 trace id、session、run、command、raw event、隐藏统计和审计控制等调试信息。 |
@@ -91,7 +92,7 @@ Web工作台负责 HWLAB 登录后的浏览器主入口，使用户能够在同
| PJ2026-01040102 | 会话输入 | 本规格 6.2 | 会话选择、消息展示、命令输入和任务操作反馈 | Agent编排、用户管理 | 用户任务提交和继续操作 |
| PJ2026-01040103 | 诊断反馈 | 本规格 6.3 | 诊断入口、状态摘要和低噪声详情展示 | Agent编排、硬件池、HarnessRL、平台运维 | 用户排障、管理员观察 |
| PJ2026-01040104 | 响应布局 | 本规格 6.4 | 桌面多栏、侧栏折叠、移动端主任务区优先和输入区可达 | 全部工作台子模块 | 桌面和移动端用户 |
| PJ2026-01040105 | 同源体验 | 本规格 6.5 | Web 与 CLI 共享 composer policy、trace renderer 和同源 API 行为 | HWLAB CLI、API契约、Agent编排 | Web/CLI 排障和内测复现 |
| PJ2026-01040105 | 同源体验 | 本规格 6.5 | Web 与 CLI 共享 composer policy、trace renderer 和同源 REST/JSON API 行为 | HWLAB CLI、API契约、Agent编排 | Web/CLI 排障和内测复现 |
| PJ2026-01040106 | Trace阅读 | 本规格 6.6 | Code Agent trace 去噪、详情收纳、耗时、正文优先和单一主按钮状态 | Agent编排、API契约、用户管理 | 用户排障和任务继续操作 |
| PJ2026-01040107 | 公开入口 | 本规格 6.7 | 正式 Cloud Web public URL、history fallback 和旧入口降级边界 | 平台运维、API契约、用户管理 | 用户访问、Playwright 验收、内测说明 |
@@ -119,7 +120,9 @@ Web工作台应让用户在主任务区直接选择或创建会话、阅读用
Web工作台必须使用显式 Agent session：无 session 时先让用户创建或选择 session，session failed、stale 或 canceled 时保留失败状态并要求用户显式切换或新建。刷新页面、重新打开工作台或短连接 result 轮询只能恢复已选 session、thread 和 trace 状态；除非用户登出或主动清空对话，不得自动生成新 conversation、替换 session 或用历史 prompt 拼接出续跑表象。
会话列表、当前消息头、composer 主按钮和运行态动效必须先确定唯一权威 API，再由 Web 展示该 API 的结果；不得让 workspace selected conversation、snapshot、stub、localStorage、message 派生状态、trace 快照或浏览器临时缓存与权威 API 并列竞争、互相覆盖或按失败路径 fallback 成另一套数据源。已经定下来的权威 API 绑定如下：session rail 会话集合的唯一入口是 `/v1/agent/conversations`，当前 selected conversation 若需要出现在列表中，必须由该列表 API 在显式 query/path/body 参数要求下返回，不得由后端隐藏读取 Web workspace selected 状态实现；session 运行状态的唯一入口是按 `sessionId` 绑定的 session 状态 API；Code Agent turn/trace 阅读状态的唯一入口是按 `traceId` 绑定的 trace/result snapshot API。Web 只能把 route、用户显式选择或 workspace API 返回的稳定业务 id 作为权威 API 的显式参数，不得把前端拼接出的 status、final response、markdown、running 动效或 stub 传回后端变成事实。Web 在权威 API 失败时只能保留上一份成功结果或显示未加载/错误态，不得从 workspace selected snapshot、stub 或本地缓存拼出单条 session tab、running 状态或 final response。运行中的 turn 必须同时反映在主任务区和对应 session tab；已进入终态的 turn 不得继续以 `Code Agent 处理中`、running 动效或旧 snapshot 文案呈现。
会话列表、当前消息头、composer 主按钮和运行态动效必须先确定唯一权威 API，再由 Web 展示该 API 的结果；不得让 workspace selected conversation、snapshot、stub、localStorage、message 派生状态、trace 快照或浏览器临时缓存与权威 API 并列竞争、互相覆盖或按失败路径 fallback 成另一套数据源。已经定下来的权威 API 绑定如下：session rail 会话集合的唯一入口是 `/v1/agent/conversations`，当前 conversation 消息本体和 session/thread/lastTraceId 绑定的唯一入口是 `/v1/agent/conversations/{conversationId}`，session 运行状态的唯一入口是按 `sessionId` 绑定的 session 状态 API；Code Agent turn/trace 阅读状态的唯一入口是按 `traceId` 绑定的 trace/result snapshot API。深链恢复、刷新、从其他 session 切回和 route watcher 应走同一 conversation detail 加显式 select/update 路径，不得先用 workspace selected snapshot、列表摘要或空 stub 覆盖当前 `messages`，再等待另一路请求补齐。
当前 selected conversation 若需要出现在列表中，必须由列表 API 在显式 query/path/body 参数要求下返回，不得由后端隐藏读取 Web workspace selected 状态实现。Workspace API 只提供工作台选择、composer 配置和稳定业务 id，不作为 conversation 消息本体 authority；列表 API 只提供 rail 排序和摘要，不作为当前消息面板 authority。Web 只能把 route、用户显式选择或 workspace API 返回的稳定业务 id 作为权威 API 的显式参数，不得把前端拼接出的 status、final response、markdown、running 动效或 stub 传回后端变成事实。Web 在权威 API 失败时只能保留上一份成功结果或显示未加载/错误态，不得从 workspace selected snapshot、stub 或本地缓存拼出单条 session tab、running 状态或 final response。运行中的 turn 必须同时反映在主任务区和对应 session tab；已进入终态的 turn 不得继续以 `Code Agent 处理中`、running 动效或旧 snapshot 文案呈现。
Agent 请求应采用短连接 submit 加 result/trace 轮询。`POST /v1/agent/chat` 或等价入口返回执行标识后，工作台通过 result 和 trace path 获取终态与可读过程，不持有一次长 HTTP 请求等待整个模型 turn。后端 result 已完成时，消息卡片必须替换为真实 final response；仍在 pending 或 trace 缺失时应显示明确状态，而不是把“result ready for polling”类中间文本当作最终回复。
@@ -149,9 +152,9 @@ Web工作台应在桌面和移动端保持主任务区可用：桌面端可以
| --- | --- | --- | --- |
| CLIENT-WB-REQ-005 | 同源体验 | PJ2026-01040105 同源体验 | [PJ2026-010402 HWLAB CLI](PJ2026-010402-hwlab-cli.md)、[PJ2026-010403 API契约](PJ2026-010403-api-contract.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) |
Web工作台应与 HWLAB CLI 共享 Code Agent composer policy、trace renderer 和同源 API 语义，使浏览器工作流问题能用同一运行端点的 CLI 非视觉复现。
Web工作台应与 HWLAB CLI 共享 Code Agent composer policy、trace renderer 和同源 REST/JSON API 语义，使浏览器工作流问题能用同一运行端点的 CLI 非视觉复现。
Web只负责浏览器交互与展示；CLI负责命令入口和结构化输出；API契约负责 path、schema 和错误语义；Agent编排负责执行事实。Web trace row 错乱、final response 缺失或发送状态异常等问题，应能先通过 CLI `trace --render web`、同源 request/rpc 和显式 Agent session 命令定位到共享 renderer、API 契约或浏览器表现层，不能让 Web 和 CLI 各自维护一套 trace 解释。
Web只负责浏览器交互与展示；CLI负责命令入口和结构化输出；API契约负责 path、schema 和错误语义；Agent编排负责执行事实。Web trace row 错乱、final response 缺失或发送状态异常等问题，应能先通过 CLI `trace --render web`、同源 REST request 和显式 Agent session 命令定位到共享 renderer、API 契约或浏览器表现层，不能让 Web 和 CLI 各自维护一套 trace 解释。
工作台在增量刷新 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 路径。
project-management/PJ2026-01/specs/PJ2026-010403-api-contract.md
+12 -9
View File
@@ -29,13 +29,13 @@
### 2.1 目的
API契约负责定义 Cloud Web、HWLAB CLI 和自动化脚本共同使用的 HTTP API 入口语义，使同一用户请求在 Web、CLI 和 HTTP 调用下使用一致的 path、schema、鉴权主体、错误语义和结果标识。
API契约负责定义 Cloud Web、HWLAB CLI 和自动化脚本共同使用的 RESTful HTTP API 入口语义，使同一用户请求在 Web、CLI 和 HTTP 调用下使用一致的 method、path、query/body、schema、鉴权主体、错误语义和结果标识。
本课题的目标状态是：客户端入口可以通过同源 API 证明业务路径是否可用；后端业务事实改变时，API 契约负责稳定暴露字段和错误，而不在客户端侧发明第二套事实模型。
### 2.2 范围内
- Cloud Web 同源相对 path、JSON-RPC envelope、REST path、route policy 和绝对 URL 禁止边界。
- Cloud Web 同源相对 REST/JSON path、route policy 和绝对 URL 禁止边界。
- Web session、API key、AuthPrincipal、actor 摘要和权限错误在客户端入口中的表达。
- Agent session、chat、steer、cancel、result、trace 和 inspect 的用户可见 API 形态。
- Workbench workspace、Admin Access、provider profile、HWPOD node-ops、gateway 和性能摘要等入口的字段稳定性。
@@ -53,11 +53,12 @@ API契约负责定义 Cloud Web、HWLAB CLI 和自动化脚本共同使用的 HT
| 术语 | 定义 |
| --- | --- |
| 同源 API | Cloud Web origin 下的相对 HTTP API path，供浏览器和 HWLAB CLI 使用。 |
| 同源 API | Cloud Web origin 下的相对 REST/JSON HTTP API path，供浏览器和 HWLAB CLI 使用。 |
| route policy | 哪些 path 可以通过 Cloud Web 代理、哪些只能作为显式 Cloud API 诊断或内部服务调用的边界规则。 |
| AuthPrincipal | 后端根据 Web session 或 API key 恢复出的用户主体摘要。 |
| 业务标识 | sessionId、traceId、runId、commandId、workspaceId、caseId 等用户可继续查询的稳定标识。 |
| 错误语义 | HTTP status、错误码、blocker、failureKind、route 和下一步提示组成的可定位失败表达。 |
| Conversation detail | `GET /v1/agent/conversations/{conversationId}` 这类按稳定 conversationId 查询当前会话消息和绑定事实的 RESTful detail resource。 |
## 4. 系统边界和接口
@@ -69,16 +70,16 @@ API契约负责定义 Cloud Web、HWLAB CLI 和自动化脚本共同使用的 HT
| 外部输入 | HTTP method、相对 path、JSON body、query、Web session cookie、Authorization header、traceId、sessionId、workspaceId 和业务参数。 |
| 受控资源 | API path、schema、route policy、AuthPrincipal 摘要、错误码、响应摘要和兼容性契约。 |
| 外部输出 | JSON 响应、HTTP status、route、actor、业务标识、错误分类、脱敏状态、trace/result 指针和下一步查询提示。 |
| 用户接口 | Cloud Web 同源 API、HWLAB CLI 同源 request/rpc/client 命令、HTTP API。 |
| 用户接口 | Cloud Web 同源 API、HWLAB CLI 同源 REST request/client 命令、HTTP API。 |
| 系统边界 | API契约负责接口形态和错误表达；不拥有用户、Agent、硬件、CaseRun、账本或发布事实。 |
## 5. 内部分工与规格索引
| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
| --- | --- | --- | --- | --- | --- |
| PJ2026-01040301 | 同源路由 | 本规格 6.1 | Cloud Web 相对 path、JSON-RPC envelope、route policy 和绝对 URL 禁止边界 | 平台入口、Web工作台 | HWLAB CLI、Cloud Web |
| PJ2026-01040301 | 同源路由 | 本规格 6.1 | Cloud Web 相对 REST/JSON path、route policy 和绝对 URL 禁止边界 | 平台入口、Web工作台 | HWLAB CLI、Cloud Web |
| PJ2026-01040302 | 鉴权主体 | 本规格 6.2 | Web session、API key、actor 摘要和权限错误表达 | 用户管理 | Web、CLI、业务 API |
| PJ2026-01040303 | Agent接口 | 本规格 6.3 | session、chat、steer、cancel、result、trace 和 inspect API 形态 | Agent编排、用户管理 | Web工作台、HWLAB CLI |
| PJ2026-01040303 | Agent接口 | 本规格 6.3 | conversation、session、chat、steer、cancel、result、trace 和 inspect API 形态 | Agent编排、用户管理 | Web工作台、HWLAB CLI |
| PJ2026-01040304 | 资源接口 | 本规格 6.4 | workspace、access、provider、HWPOD node-ops、gateway 和性能摘要入口 | 全部业务 L1 | Web、CLI、admin |
| PJ2026-01040305 | 错误输出 | 本规格 6.5 | JSON 成功/失败响应、错误码、route/status、脱敏和渐进披露 | 全部业务 L1 | 用户、脚本、排障 |
@@ -90,14 +91,16 @@ API契约负责定义 Cloud Web、HWLAB CLI 和自动化脚本共同使用的 HT
| --- | --- | --- | --- |
| CLIENT-API-REQ-001 | 同源路由 | PJ2026-01040301 同源路由 | [PJ2026-010401 Web工作台](PJ2026-010401-web-workbench.md)、[PJ2026-010402 HWLAB CLI](PJ2026-010402-hwlab-cli.md)、[平台运维](PJ2026-0106-platform-ops.md) |
API契约应定义 Cloud Web origin 下的相对 path、JSON-RPC envelope 和 route policy，使浏览器与 HWLAB CLI 能通过同一同源入口访问业务 API。
API契约应定义 Cloud Web origin 下的相对 REST/JSON path 和 route policy，使浏览器与 HWLAB CLI 能通过同一同源入口访问业务 API。
同源路由必须拒绝把绝对 URL、内部服务地址或旧运行面端口作为正式用户入口。平台运维提供公开入口和代理支撑；API契约只规定客户端可依赖的 path 和错误形态。
API契约必须区分同源 API path 与浏览器 history route：`/auth*`、`/v1*`、`/json-rpc*`、`/health*` 等 API path 返回 JSON 语义，`/workbench`、`/login` 和其他 Cloud Web 页面路由由 Web工作台处理。API/edge 直达入口对页面路由返回 JSON 404 是正确边界，不应被改造成 SPA fallback；反过来，Web正式公开入口必须通过 route policy 把 API path 分流到 API 服务。
API契约必须区分同源 API path 与浏览器 history route：`/auth*`、`/v1*`、`/health*` 等 API path 返回 JSON 语义，`/workbench`、`/login` 和其他 Cloud Web 页面路由由 Web工作台处理。API/edge 直达入口对页面路由返回 JSON 404 是正确边界，不应被改造成 SPA fallback；反过来，Web正式公开入口必须通过 route policy 把 API path 分流到 API 服务。
RESTful API 必须保持无状态请求语义：在相同 method、path、query、body、auth 主体和相同后端业务事实下，应返回同一语义结果；服务端不得为了补齐某个列表或状态而隐藏读取浏览器 workspace selected、localStorage、Web snapshot、上一次页面状态或其他客户端临时状态。列表窗口需要包含某个当前资源时，必须通过显式 query/path/body 传入稳定业务 id，例如 conversation list 通过显式 include conversation id 请求把当前 conversation 纳入同一列表响应；服务端只能校验该 id 对当前 actor 是否可见并返回后端事实，不得接受客户端拼接出的 status、final response、markdown、running 动效或 stub 作为事实来源。
当前会话消息恢复必须使用 RESTful detail resource：`GET /v1/agent/conversations/{conversationId}` 是 conversation 消息、sessionId、threadId、lastTraceId、messageCount、firstUserMessagePreview 和会话状态的权威入口。`GET /v1/workbench/workspace` 可以返回 selected ids、workspace revision 和 composer 配置，但不得成为消息本体 authority；`GET /v1/agent/conversations` 可以返回 rail 摘要和显式 include 的列表项，但不得替代当前 conversation detail。前端恢复、深链、刷新和 session 切换必须以稳定 conversationId 调用同一 detail resource，不得在 detail resource 失败时切到 workspace snapshot、列表摘要、JSON-RPC、内部 manager、浏览器缓存或空 stub 继续构造当前消息面板。
### 6.2 CLIENT-API-REQ-002 鉴权主体
| 编号 | 短名 | 主责模块 | 关联模块 |
@@ -114,7 +117,7 @@ API契约应以 AuthPrincipal 摘要表达 Web session 和 API key 恢复出的
| --- | --- | --- | --- |
| CLIENT-API-REQ-003 | Agent接口 | PJ2026-01040303 Agent接口 | [Agent编排](PJ2026-0102-agent-orchestration.md)、[用户管理](PJ2026-0105-user-management.md)、[PJ2026-010401 Web工作台](PJ2026-010401-web-workbench.md) |
API契约应定义显式 Agent session、chat、steer、cancel、result、trace 和 inspect 的用户可见 HTTP 形态，使 Web 和 HWLAB CLI 能围绕同一 sessionId、conversationId、threadId、traceId、runId 和 commandId 操作。
API契约应定义显式 Agent conversation、session、chat、steer、cancel、result、trace 和 inspect 的用户可见 RESTful HTTP 形态，使 Web 和 HWLAB CLI 能围绕同一 sessionId、conversationId、threadId、traceId、runId 和 commandId 操作。
Agent 接口不得通过 session latest、浏览器历史、旧 cache 或内部 manager 生成第二套 final response。Agent编排提供执行事实，用户管理校验 owner 和权限，客户端只稳定暴露用户入口。