# 实现方案 v3：端云协同编程智能体系统 Web 应用化

> 编写日期：2026（git 记录）
> 状态：**Web 应用化权威设计**。在 v2（端云协同编程智能体系统）基础上，把系统做成一个**完整、可演示、可答辩的 Web 应用**。
> 前置依赖：v2 已落地（见 `实现方案_v2_端云协同编程智能体系统.md` 与 `README.md`），229 项测试全绿。
> 预期读者：负责实现的 AI Agent 或开发者。实现前必读：第 4 节（设计决策）、第 8 节（工程规约）。

---

## 0. 一页速览

- **后端**：保持 FastAPI + uvicorn **不重写**；仅把 `/chat` 从"同步等待"改为"异步任务 + SSE 事件流"，并**通过读 `workspace.json` 实现协作过程实时可视化**，**不触碰 `router_system` 核心逻辑**（保住 229 项测试）。
- **前端**：新建 **Vue 3 + Vite + TypeScript** SPA，Vite 构建产物输出到 `gateway/static`，由 FastAPI 单端口托管。四个页面：**对话 / 协作过程 / 检验队列 / 指标**。
- **实时性**：`POST /chat` 立即返回 `request_id`，后台 asyncio 任务跑协作管线，前端经 **SSE（Server-Sent Events）** 订阅 `/runs/{id}/stream`，把 Architect 与 Worker 一步步交接的「交流文本」过程实时画出来。
- **工程约束**：单端口部署、sqlite + 文件系统存储、不上 Celery/Redis/微服务；`router_system` 保持零第三方依赖。

---

## 1. 背景与动机

### 1.1 为什么做 Web 应用化

1. **v2 前端是单文件原生 HTML**（`gateway/static/index.html`，21KB），功能齐全但：
   - 代码无工程化组织，不便于扩展、维护与答辩展示"完整 Web 应用"。
   - 协作过程是静态展示，无法**实时看到** Architect/Worker 多轮交接。
2. **`/chat` 是同步阻塞**：协作管线多轮慢任务（本地小模型 + 大模型 API），前端只能干等，交互体验差，也无法演示"交流文本逐步推进"这一核心卖点。
3. **课题定位**是"系统设计与实现"，一个工程化、可视化、可量化的 Web 应用与课题目标匹配，且能体现工作量。

### 1.2 现有资产盘点（Web 层）

| 模块 | 现状 | v3 处置 |
|---|---|---|
| `gateway/api.py` | FastAPI，8 组端点 | **保留** + 新增 SSE / 任务管理 |
| `gateway/static/index.html` | 单文件前端 | **退役**，被 Vue SPA 构建产物取代 |
| `gateway/settings.py` | 用户可调设置 | 保留 |
| `router_system/*` | 纯标准库业务逻辑 | **一行不改**，只新增读接口 |
| `scripts/serve.py` | 启动网关 | 扩展为同时托管构建产物 |

---

## 2. 总体架构

```
浏览器 (Vue 3 SPA, 4 页面)
   │  REST + SSE
   ▼
gateway/ (FastAPI, 单进程 uvicorn)
   ├── POST /chat           → 提交后台任务，立即返回 request_id
   ├── GET  /runs/{id}/stream  (SSE) → 推送协作过程增量 + 最终结果
   ├── GET  /runs/{id}/status   → 任务状态 (pending/running/done/failed)
   ├── GET  /runs/{id}/workspace, /artifacts/{name}
   ├── GET/POST /review/*    → 人工检验队列
   ├── GET  /metrics          → 指标（供 ECharts 看板）
   ├── GET  /config           → 设置
   └── 静态托管 dist/（Vue 构建产物）
   │
   ├── jobs.py  ← 新增：asyncio 后台任务注册表 (request_id -> task+state)
   │
   └── router_system/  ← 保持零依赖，由后台任务调用
          pipeline.run(query)  # 边跑边写 runs/{id}/workspace.json
```

**数据流（一次对话）**：
1. 前端 POST /chat → 后端建后台任务，返回 `{request_id, status:"running"}`。
2. 后台任务调用 `pipeline.run(query)`；管线把「交流文本」增量写入 `runs/{id}/workspace.json`。
3. 前端打开 `GET /runs/{id}/stream`（SSE）；后端生成器**监视该文件**（mtime/内容变化），按事件推送。
4. 协作结束 → SSE 推送 `result`（最终答复 + token/cost/latency 指标）→ 前端渲染。

---

## 3. 技术栈选型

| 层 | 选型 | 理由 |
|---|---|---|
| 后端 | Python + FastAPI + uvicorn | `router_system` 为 Python 纯标准库，LLM/llama 集成均为 Python；**重写为巨大浪费** |
| 异步/SSE | FastAPI `StreamingResponse` + 自实现 SSE 格式（或 `sse-starlette`） | 单个轻依赖，实现协作实时推送 |
| 任务调度 | asyncio 后台任务（uvicorn 事件循环内） | 毕设量级足够；**不上 Celery/Redis** |
| 存储 | sqlite（review 已用）+ 文件系统 `runs/` | 够用、易解释、免装数据库服务 |
| 前端 | Vue 3 + Vite + TypeScript | 工程化 SPA，四页面，答辩加分 |
| 状态管理 | Pinia（可选，轻量） | 跨页共享运行状态/指标 |
| UI 组件 | Element Plus | 对话、表格、表单、队列管理开箱即用 |
| 可视化 | ECharts | 交流文本时间轴、token 曲线、指标看板 |
| 部署 | Vite `outDir=gateway/static` → FastAPI 静态托管，单端口 | 演示省心；可选 Docker 打包 |

---

## 4. 设计决策（不得推翻）

- **D1 后端不重写**：`gateway/api.py` 与 `router_system` 保持 Python；禁止改写成 Node/Go。
- **D2 /chat 异步化**：`POST /chat` 提交后台 asyncio 任务并立即返回 `request_id`，不再同步等待管线跑完。
- **D3 SSE 通过读文件实现，不改 pipeline 内核**：协作过程可视化靠 SSE 生成器监视 `runs/{id}/workspace.json`（管线已增量写该文件）。**不得修改 `router_system/pipeline.py` 以注入回调**，从而保住 229 项测试全绿。若未来要更精细事件，再作为独立优化（见 §9 展望），且需同步维护测试。
- **D4 任务状态可查询**：后台任务必须有独立状态（pending/running/done/failed + 错误信息 + 时间戳），供 `GET /runs/{id}/status` 与前端刷新后恢复。
- **D5 不上分布式中间件**：禁用 Celery / Redis / Kafka / 微服务；asyncio + sqlite + 文件系统即可满足。
- **D6 单端口部署**：Vue 构建产物输出到 `gateway/static`，由 FastAPI 统一托管；不另开前端 dev 服务器作为生产入口（dev 模式可单独起 Vite，仅本地开发用）。
- **D7 前端四页面划分**：对话 / 协作过程 / 检验队列 / 指标；用 Vue Router 管理路由。
- **D8 兼容降级**：无 API key / 无本地模型时 `/chat` 仍走 mock/降级路径（沿用 v2），Web 应用不可因此崩溃。
- **D9 参数化配置**：`/chat` 的领域、采样、熔断等沿用 v2 配置；Web 端不硬编码模型/金额参数。

---

## 5. 后端接口设计

### 5.1 变更端点

| 端点 | 变更 | 说明 |
|---|---|---|
| `POST /chat` | **改为异步** | 入参同 v2 `QueryRequest`；返回 `{request_id, status:"running"}`，后台跑管线 |
| `GET /runs/{id}/stream` | **新增（SSE）** | `text/event-stream`；事件：`status`（状态变化）、`workspace`（交流文本增量/快照）、`result`（最终答复+指标）、`error` |
| `GET /runs/{id}/status` | **新增** | 返回任务状态、已用轮次、token、错误等 |

### 5.2 不变端点（复用）

`POST /chat/legacy`、`GET /runs/{id}/workspace`、`GET /runs/{id}/artifacts/{name}`、`GET/POST /review/*`、`GET /metrics`、`GET/PUT /config`、`GET /health`。

### 5.3 SSE 事件协议（草稿）

```
data: {"type":"status","value":"running","request_id":"..."}
data: {"type":"workspace","version":N,"workspace":{...}}
data: {"type":"result","response":"...","api_input_tokens":123,"cost_est":0.01,"latency_ms":4200,...}
data: {"type":"error","detail":"..."}
```

- `workspace` 事件按文件变化频率推送；前端据此推进「交流文本」状态机可视化。
- `result` 为终态；此后连接由服务端关闭。

---

## 6. 前端页面设计

### 6.1 路由与视图

| 路由 | 页面 | 关键功能 |
|---|---|---|
| `/` | ChatView（对话） | 输入 query → POST /chat → 打开 SSE → 逐步可视化协作过程 + 展示最终答复/指标；历史运行列表 |
| `/runs/:id` | CollaborationView（协作过程） | 只读查看一次运行的「交流文本」完整 JSON、工件下载、时间轴 |
| `/review` | ReviewView（检验队列） | 待审列表、详情、verdict/correction 提交 |
| `/metrics` | MetricsView（指标） | ECharts：token 经济学（A1 vs A2）、快路径命中率、护栏熔断、检验统计 |

### 6.2 核心组件

- `WorkspaceTimeline.vue`：把「交流文本」按状态机（brief→implement→verify→decide→final_review→done）渲染为流程时间轴。
- `TokenEconomicsChart.vue`：A1 全量 vs A2 交流文本 的 token 对比图。
- `ReviewQueueTable.vue`：人工检验队列表格 + 提交表单。
- `SseClient.ts`：封装 EventSource + 断线重连 + 状态机事件分发。

---

## 7. 目录结构（新增）

```
gateway/
├── api.py            # 保留；新增 /chat 异步 + /runs/{id}/stream + /runs/{id}/status
├── jobs.py           # 新增：后台任务注册表（request_id -> Task + 状态）
└── static/           # Vite 构建产物（outDir 指向这里），FastAPI 静态托管
webapp/               # 新增：Vue 3 + Vite + TS 前端源码
├── index.html
├── vite.config.ts    # server.proxy /api -> localhost:8000；build.outDir -> ../gateway/static
├── package.json
└── src/
    ├── main.ts, App.vue, router.ts
    ├── api/            # rest.ts, sse.ts
    ├── views/          # ChatView, CollaborationView, ReviewView, MetricsView
    ├── components/     # WorkspaceTimeline, TokenEconomicsChart, ReviewQueueTable, ...
    └── stores/         # runStore.ts (Pinia, 可选)
```

---

## 8. 工程规约

1. **`router_system/` 零第三方依赖不变**；`gateway/` 可用 fastapi/uvicorn/pydantic/httpx（沿用 v2）。
2. **新增依赖需登记**：前端 Node 依赖记入 `webapp/package.json`；后端如引入 `sse-starlette` 需写入 `requirements.txt` 并说明理由。
3. **测试**：`.venv/Scripts/python.exe -m pytest tests -q` 必须**保持 229 项全绿**；新增 SSE/异步的测试用 `httpx.MockTransport` + 临时文件，不依赖真实模型/API key（沿用 v2 D4）。
4. **异步任务清理**：done/failed 任务定期回收（或按容量上限裁剪），防内存泄漏。
5. **Windows 兼容**：`pathlib` 路径、UTF-8、子进程 terminate→kill 兜底（沿用 v2 第 6 条）。
6. **金额敏感**：SSE/前端展示的 token/cost 均来自 v2 计量，不改动 `api_token_cap` 熔断逻辑。
7. 每任务一个 commit，格式 `feat(v3): Tn 描述`。

---

## 9. 实施步骤（T1–T6）

- **T1 后端异步化**：`jobs.py` + `POST /chat` 改为后台任务 + `GET /runs/{id}/status`。
- **T2 后端 SSE**：`GET /runs/{id}/stream`，生成器监视 `workspace.json`，推送 status/workspace/result。
- **T3 前端脚手架**：Vite 创建 Vue3+TS 工程，配 proxy 与 `outDir=gateway/static`；接入路由与 4 个空页面。
- **T4 对话页 + 协作可视化**：SseClient + WorkspaceTimeline，实现实时「交流文本」推进。
- **T5 检验队列页 + 指标页**：ReviewQueueTable + ECharts 看板。
- **T6 集成与部署**：`scripts/serve.py` 托管构建产物；`npm run build` 产物验证四页面；写测试覆盖 SSE 协议与任务状态机。

---

## 10. 验收标准

- [ ] `POST /chat` 立即返回 `request_id`（非阻塞）。
- [ ] SSE `/runs/{id}/stream` 能实时推送 status/workspace/result，断线可重连。
- [ ] 对话页能完整可视化一次协作的「交流文本」推进过程并展示最终答复与 token/cost。
- [ ] 检验队列页能列表/提交审核；指标页 ECharts 正常渲染。
- [ ] `pytest tests -q` 保持 229 项全绿（含新增 SSE/异步测试）。
- [ ] 单端口（FastAPI）访问即可完成全部四页面操作与演示。

---

## 11. 风险与规避

| 风险 | 规避 |
|---|---|
| SSE 读到文件抖动/重复 | 用 version + 文件 mtime/大小变化去重，前端按 version 合并 |
| 后台任务异常/进程重启丢状态 | `jobs.py` 记录状态与运行目录；重启后按 `runs/` 恢复"已完成"识别，进行中的标记为 failed/unknown |
| 长连接占资源 | SSE 空闲超时自动关闭；前端自动重连 |
| 引入 Node 工具链的复杂度 | 仅 dev 需要 npm；产物构建后为纯静态，演示/部署无需 Node |
| 前端过度设计 | 固定 4 页面，不上复杂状态库/微前端，控制依赖数量 |