feat: update PlanningAgent to support SSE streaming with reasoning process display and fix UI spacing issues

2026-03-14 01:40:48 +08:00
parent 250192f699
commit 48c6f84239
10 changed files with 606 additions and 114 deletions
--- a/API_Gateway_Rules.md
+++ b/API_Gateway_Rules.md
@@ -0,0 +1,116 @@
+# Safe OS UI - API Gateway 路由转发规则文档
+
+本系统包含多个独立的后端AI服务（规划系统、开发平台、质量门禁等）。为了使前端统一指向单一入口并简化跨域和请求分发配置，建议使用 API Gateway 进行统一路由和负载均衡。
+
+以下是当前前端所有与后端服务交互的接口清单以及转发规则。Gateway 服务需要解析相应的路径前缀（Ingress Prefix），将请求 Rewrite 后转发至对应的内部后端服务。
+
+---
+
+## 整体架构与入口规则
+
+- **统一入口 URL**：`http://<api-gateway-host>:<port>` （前端将所有 API 请求指向此地址）
+- **核心路由匹配策略**：基于 URL前缀 进行正则匹配或前缀匹配。
+
+| 业务模块 | Ingress Prefix (外部路径) | Forward Target (内部服务地址) | Rewrite Rule (路径重写规则) |
+| --- | --- | --- | --- |
+| **Planning System** | `/planning-api/*` | `http://localhost:8090` | `/planning-api/(.*)` ➔ `/api/$1` |
+| **DevOps System** | `/devops-api/*` | `http://localhost:8000` | `/devops-api/(.*)` ➔ `/$1` |
+| **Quality Gate System** | `/quality-api/*` | `http://localhost:5000` | `/quality-api/(.*)` ➔ `/api/$1` |
+
+---
+
+## 1. 规划子系统接口 (Planning System) 
+**底层服务**: `http://localhost:8090`
+前缀重写规则：请求至统一入口 `.../planning-api/X` 会被转发至内部的 `.../api/X`。
+
+| 方法 | 外部暴露路径 (Gateway URL) | 内部转发路径 (Target URL) | 接口描述 |
+| --- | --- | --- | --- |
+| `POST` | `/planning-api/chat/stream` | `/api/chat/stream` | 铁三角 Agent：发送大系统规划/史诗业务需求内容（SSE流式数据返回） |
+| `POST` | `/planning-api/upload` | `/api/upload` | 文档上传：支持用户上传附件作为系统知识或输入来源 |
+
+---
+
+## 2. 研发自动引擎接口 (DevOps System)
+**底层服务**: `http://localhost:8000`
+前缀重写规则：请求至统一入口 `.../devops-api/X` 会被去掉前缀，转为后端的 `.../X`。该系统重度依赖**SSE (Server-Sent Events) 流式连接**，请在Gateway配置中确保不会缓冲或阻断流数据。
+
+| 方法 | 外部暴露路径 (Gateway URL) | 内部转发路径 (Target URL) | 接口描述 |
+| --- | --- | --- | --- |
+| `POST` | `/devops-api/session/start` | `/session/start` | 新建研发自动化任务会话 (Session) |
+| `POST` | `/devops-api/session/{sessionId}/clarify` | `/session/{sessionId}/clarify` | 基于需求说明进行需求澄清和补充 |
+| `GET` | `/devops-api/session/{sessionId}/pm/stream` | `/session/{sessionId}/pm/stream` | PM角色执行需求细化分析流程 (SSE流) |
+| `GET` | `/devops-api/session/{sessionId}/pm/refine/stream` | `/session/{sessionId}/pm/refine/stream` | 追加PM反馈，继续流式提炼需求 (SSE流) |
+| `GET` | `/devops-api/session/{sessionId}/qa/stream` | `/session/{sessionId}/qa/stream` | QA角色基于需求生成测试用例并执行评估 (SSE流) |
+| `GET` | `/devops-api/session/{sessionId}/qa/refine/stream` | `/session/{sessionId}/qa/refine/stream` | 追加QA用例反馈并更新测试集 (SSE流) |
+| `GET` | `/devops-api/session/{sessionId}/dev/stream` | `/session/{sessionId}/dev/stream` | 核心编码过程：依据需求、架构与测试生成最终业务/Java等工程代码 (SSE流) |
+| `POST` | `/devops-api/session/{sessionId}/test/run` | `/session/{sessionId}/test/run` | 运行集成编译与单元/端到端测试并获取结果 |
+| `GET` | `/devops-api/session/{sessionId}/test/fix/stream` | `/session/{sessionId}/test/fix/stream` | 针对测试错误进行的AI代码自动修复 (SSE流) |
+
+*注意： `{sessionId}` 属于路径层级中的动态参数，具体网关转发时使用泛类型或通配符放行。*
+
+---
+
+## 3. 代码质量门禁接口 (Quality Gate)
+**底层服务**: `http://localhost:5000`
+前缀重写规则：请求至统一入口 `.../quality-api/X` 会被转发至后端内部的 `.../api/X`。
+
+| 方法 | 外部暴露路径 (Gateway URL) | 内部转发路径 (Target URL) | 接口描述 |
+| --- | --- | --- | --- |
+| `GET` | `/quality-api/prs` | `/api/prs` | 获取 PR 扫描工单列表（支持多种查询参数） |
+| `GET` | `/quality-api/prs/history` | `/api/prs/history` | 获取 PR 处理历史，用于趋势看板 (e.g., `?limit=15`) |
+| `GET` | `/quality-api/prs/{prId}` | `/api/prs/{prId}` | 获取某一条指定 PR 扫描记录的详细执行状态及摘要 |
+| `GET` | `/quality-api/prs/{prId}/files` | `/api/prs/{prId}/files` | 拉取这条 PR 的被影响/改动的文件目录结构 |
+| `GET` | `/quality-api/prs/{prId}/file` | `/api/prs/{prId}/file` | 获取PR里指定文件的 Diff 对象（包含行内审查反馈），附带 `?path=xxx` 查询参数 |
+| `POST`| `/quality-api/prs/{prId}/merge` | `/api/prs/{prId}/merge` | 在门禁界面确认问题修缮无误后，合并该次 PR |
+| `POST`| `/quality-api/prs/{prId}/close` | `/api/prs/{prId}/close` | 门禁审查不通过，拒绝/关闭此条扫描和合并申请 |
+
+---
+
+## Nginx Gateway 配置示例 (参考)
+
+如果网关选用 Nginx，可快速参考如下配置来完成上述 Rewrite 与 Proxy：
+
+```nginx
+server {
+    listen 80;
+    server_name api-gateway.safe-os.local;
+
+    # 1. Planning API 转发
+    location /planning-api/ {
+        # 截取 /planning-api/ 后的内容，拼接到 /api/
+        rewrite ^/planning-api/(.*)$ /api/$1 break;
+        proxy_pass http://localhost:8090;
+        
+        # 启用流连接所需的头信息
+        proxy_set_header Connection '';
+        proxy_http_version 1.1;
+        chunked_transfer_encoding off;
+        proxy_buffering off;
+        proxy_cache off;
+    }
+
+    # 2. DevOps API 转发
+    location /devops-api/ {
+        # 截取 /devops-api/ 后的内容，直接拼接
+        rewrite ^/devops-api/(.*)$ /$1 break;
+        proxy_pass http://localhost:8000;
+
+        # 支撑 SSE (Server-Sent Events) 的流配置
+        proxy_set_header Connection '';
+        proxy_http_version 1.1;
+        chunked_transfer_encoding off;
+        proxy_buffering off;
+        proxy_cache off;
+        proxy_read_timeout 3600s; # 考虑大模型生成代码时间较长
+    }
+
+    # 3. Quality Gate API 转发
+    location /quality-api/ {
+        # 截取 /quality-api/ 后的内容，拼接到 /api/
+        rewrite ^/quality-api/(.*)$ /api/$1 break;
+        proxy_pass http://localhost:5000;
+    }
+}
+```
+
+以上文档即针对前端当前服务现状所整理的 API Gateway 路由规划规范，您可以直接根据此规范开发 API Gateway 或调整 Nginx 等负载均衡器的配置。