projectAIpopular/实现方案_v3_Web应用化.md

实现方案 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 页面，不上复杂状态库/微前端，控制依赖数量