From 17162ae3ac99b7576387a85c968f356d0b9578cd Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 16 Jun 2026 10:27:25 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=9B=BA=E5=8C=96=20RESTful=20?= =?UTF-8?q?=E7=8A=B6=E6=80=81=E5=85=A5=E5=8F=A3=E8=BE=B9=E7=95=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../PJ2026-01/specs/PJ2026-010401-web-workbench.md | 2 +- .../PJ2026-01/specs/PJ2026-010403-api-contract.md | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) 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 038d74d9..58c31359 100644 --- a/project-management/PJ2026-01/specs/PJ2026-010401-web-workbench.md +++ b/project-management/PJ2026-01/specs/PJ2026-010401-web-workbench.md @@ -119,7 +119,7 @@ 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 自身返回；session 运行状态的唯一入口是按 `sessionId` 绑定的 session 状态 API；Code Agent turn/trace 阅读状态的唯一入口是按 `traceId` 绑定的 trace/result snapshot API。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`，当前 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 文案呈现。 Agent 请求应采用短连接 submit 加 result/trace 轮询。`POST /v1/agent/chat` 或等价入口返回执行标识后，工作台通过 result 和 trace path 获取终态与可读过程，不持有一次长 HTTP 请求等待整个模型 turn。后端 result 已完成时，消息卡片必须替换为真实 final response；仍在 pending 或 trace 缺失时应显示明确状态，而不是把“result ready for polling”类中间文本当作最终回复。 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 38b9a4a3..8c370055 100644 --- a/project-management/PJ2026-01/specs/PJ2026-010403-api-contract.md +++ b/project-management/PJ2026-01/specs/PJ2026-010403-api-contract.md @@ -96,6 +96,8 @@ API契约应定义 Cloud Web origin 下的相对 path、JSON-RPC envelope 和 ro 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 服务。 +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 作为事实来源。 + ### 6.2 CLIENT-API-REQ-002 鉴权主体 | 编号 | 短名 | 主责模块 | 关联模块 |