对对队第二次团队作业——原型设计+概要设计
| 项目 | 内容 |
|---|---|
| 作业所属课程 | 软件工程 · 2024 级 Class56 |
| 作业要求 | 第二次团队作业——原型设计+概要设计 |
| 作业的目标 | 在第一次作业完成选题、需求分析与系统规划的基础上,用原型确定界面与交互、用概要设计确定架构与数据组织,并给出开发计划与分工,为后续编码和杀手级功能留出时间。本次作业重点在提交两份设计文档,博客用于展示设计成果与协作过程。 |
| 团队名称 | 对对队 |
| 团队成员学号-名字 | 3124004179-王嵘烨、3124004170-李建鑫、3124004189-周微 |
| 项目名称 | 锚(TopViewbot) |
一、原型设计
原型使用专用原型设计工具绘制,包含前台应用原型与后台管理原型两套,交互说明、文本说明与规则说明均在原型中标注,并已发布为公开可访问的在线预览(链接见第五节)。
前台应用(6 个模块、18 个页面)
- 会话工作区:工作台首页、新建会话、对话主区、Agent 控制台、授权确认弹窗、文件预览。会话绑定独立工作目录;推理、工具调用、正文按 part 增量推送并可折叠回看;高风险动作先授权,拒绝后命令不执行。
- 资源管理:工作目录浏览、文件上传、终端面板。终端保留 scrollback,输出超长自动截断并提示;运行中禁止重复提交。
- 自动化中心:定时任务(cron)、Webhook 管理、运行历史。cron 需预览下次触发时间;Webhook secret 仅创建时可见一次;运行历史可展开详情、可重放且重投幂等。
- 可观测面板:指标面板展示请求量、工具耗时分布、失败率,时间窗口可切换并支持下钻到会话。
- 设置中心:模型与 Provider、MCP 服务、技能 Skills、用户偏好、浏览器扩展中继、隧道与安全六个设置页;MCP 配置修改后热生效;隧道未设密码拒绝开启。
- 登录页:用户名固定为 topviewbot,密码错误 5 次锁定 60 秒;未设密码时自动跳过。
后台管理(6 个页面):系统总览、用户与鉴权、工具权限、运行治理、数据管理、审计日志。其中令牌 TTL 为 720 分钟,改密码后旧令牌全部失效;运行治理可强制释放超时租约但需二次确认;审计日志支持按运行编号检索与导出。
前台突出特点
- 会话绑定工作目录,文件与终端能力被限制在该目录内,越权默认拒绝;
- 过程可折叠回看,每次工具调用都做成可展开卡片并配唯一运行编号;
- 入口切换不断线,从本机切到隧道后仍是同一会话;
- 安全前置,隧道开启前强制设密码、提交类动作强制确认。
二、概要设计
2.1 架构(自顶向下)
系统分四层,自上而下依赖:接入层 → 编排层 → 能力层 → 运行时层。换任何一层都不动其他三层,这是整个设计的总约束。
- 接入层:浏览器 Web UI、手机隧道(HTTPS/WSS)、Webhook、MR 事件,负责"从哪进来";
- 编排层:AgentRuntime(会话与运行权中枢)、Controller(一次任务编排)、权限与租约,负责"一次任务怎么调度";
- 能力层:文件与终端工具、浏览器中继、平台包(MR/飞书)、MCP 服务、Skills,负责"能做什么";
- 运行时层:Bun 进程与并发、SQLite 会话存储、Outbox 投递、指标与观测,负责"靠什么撑住"。
技术选型为 Bun 运行时、Vue 3 + Vite 前端、HTTP + SSE 通信、SQLite 存储、扩展 + WebSocket 浏览器中继、Provider 抽象。
总体架构分层图、功能模块结构图与功能模块思维导图见《对对队_系统设计说明书》图 2-1、图 2-2 与 §2.4。
2.2 UML 设计
| 图 | 用途 | 本文要点 |
|---|---|---|
| 用例图 | 需求分析 | 3 类参与者(用户、管理员、外部系统)、10 个用例,覆盖从会话到 MR 评审的完整需求 |
| 活动图 | 业务流程 | 一次会话任务的完整流程,含"会话 busy 返回 409""高风险等待授权""用户拒绝后留痕"三个判定 |
| 类图 | 系统结构 | 9 个核心类,体现接口实现、组合关系与基数 |
| 时序图 | 重要算法模块 | 真实浏览器接管填表的端到端流程,共 13 条带编号消息,体现 WebSocket 连接代次绑定与提交前确认 |
| 协作图 | 对象协作与消息传递 | 以文件编辑为例,6 个对象、12 条编号消息,展示界面—编排—权限—工具—文件系统之间的交互 |
设计上重点体现三处取舍:运行权互斥(会话 busy 直接返回 409,不落库不覆盖)、高风险授权(提交类动作与跨项目访问必须确认)、旧代次丢弃(取消后旧代次的写入无效,解决并发串扰)。
以上五类 UML 图均以矢量图收录于《对对队_系统设计说明书》§3,图号、图注与图表清单见该文档 §12.1,在 PDF 中可无级放大查看。
2.3 数据库设计
数据库采用 SQLite,单文件存储,符合"本机是能力、数据不留云"的定位。
- ER 图:以
SESSION为枢纽,向消息与分片、偏好注入、运行与投递、模型来源四条链路展开,共 9 个实体;PART实体把消息拆为推理、工具调用、正文等片段,支撑按 part 增量推送与折叠回看。 - 关系数据模型:9 张关系表(PROJECT、SESSION、MESSAGE、PART、PREFERENCE、AUTOMATION、RUN、OUTBOX、PROVIDER),满足 1NF / 2NF、基本满足 3NF;从属表外键级联删除,字典表限制删除;枚举与评分字段使用 CHECK 约束。
OUTBOX用delivered+attempts两字段实现幂等投递,重投先查 delivered 避免重复副作用。 - 对象关系映射:实体类与库表一一对应,类图中的组合关系统一映射为级联删除;API Key 不进入任何表,独立存于本地
auth.json,从数据模型层面保证密钥不进上下文与日志。
ER 图(图 3-1)、关系模式主外键图(图 4-1)与对象—关系映射总图(图 6-1)均收录于《对对队_数据库设计说明书》,图表清单见该文档 §11.1。
三、团队协作记录
3.1 开发计划与完成情况
| 阶段 | 主要工作 | 里程碑 | 产出(对应提交) |
|---|---|---|---|
| 1 | 仓库初始化,搭建工程骨架 | M1 项目建立 | Initial commit——初始目录与构建配置 |
| 2 | 接入多用户与登录鉴权 | M2 鉴权可用 | feat: add muti-user and login;同日 LGTM 合并评审 |
| 3 | 界面头部改版 | M3 界面调整 | change the header 及对应 LGTM |
| 4 | 前端 UI 功能开发 | M4 界面成型 | feat/UI;随后 fix、LGTM 迭代 |
| 5 | 修复构建问题 | M5 构建通过 | fix: 修复所有 TypeScript 构建错误 |
| 6 | 补充保障逻辑 | M6 稳定性加固 | add ensure 及对应 LGTM |
| 7 | 发布可用版本 | M7 发布 | realease(发布前有一次 Revert "realease" 后重发) |
| 8 | 本次作业设计文档归档 | M8 设计定稿 | docs: 提交——两份设计说明书 PDF 收录至 docs/design/ |
3.2 分工安排
| 成员 | 角色 | 负责的详细开发部分 | 本次作业贡献 |
|---|---|---|---|
| 3124004179-王嵘烨 | 内核与运行时 | 编排层与运行时层;AgentRuntime、Controller、Session/Part 模型;并发与租约;Provider 抽象;数据库 Schema 与迁移 | 总体架构、类图、时序图;统筹与博客统稿 |
| 3124004170-李建鑫 | 前端与浏览器中继 | 前台/后台全部原型;Vue 3 工作台与 SSE 渲染;Agent 控制台;浏览器扩展与 browser-mcp-server 中继;隧道交互 | 原型设计、用例图、活动图 |
| 3124004189-周微 | 平台适配、测试与文档 | 数据库设计与 ER 图;验收标准与测试用例;MR/飞书平台包;项目管理看板维护 | 《数据库设计说明书》全文、协作图、两份说明书交叉校对 |
| 全队共同 | — | — | 文档互审、统一符号与编号、GitHub 提交与 PR 评审 |
3.3 协作过程记录
本项目以第一次作业《软件需求规格说明书》的 F01–F10 功能需求与 20 条非功能需求为共同输入,三人按内核运行时 / 前端浏览器中继 / 平台测试文档三条线并行推进,线内各自负责,线间交叉评审。
任务与代码管理。 团队以 GitHub 仓库为唯一协作平台:功能开发拆为 Issues 跟踪(仓库可见 feat: add muti-user and login、feat/UI、fix、add ensure、realease 等任务项),改动通过 Pull Request 合并(提交信息中的 LGTM 即评审通过标记),源码与文档随提交留痕(见 3.1 节的提交记录)。
三条线的分工与衔接。
- 内核运行时线负责编排层与运行时层:会话与运行权管理、Provider 抽象、工具调度与并发治理,并产出系统架构、类图与时序图,为另外两条线提供接口契约。
- 前端浏览器中继线负责全部原型与前端:工作台与 SSE 流式渲染、Agent 控制台、浏览器扩展中继,并产出用例图与活动图,把架构契约落实为可交互界面。
- 平台测试文档线负责数据库设计、验收标准与测试用例、MR/飞书平台适配,并承担本次设计文档的整理与质量把关:统一两份说明书的章节编号、图形符号与缩写定义,校对 ER 图与 ORM 映射,保证文档口径一致、可交叉引用。这条线的产出以设计文档、测试用例与规范约定为主,是本次作业交付物能成型的关键环节。
交叉评审。 三条线的产出先各自成稿,再整组互审:架构与界面是否对得上接口、DESIGN 文档的图号是否与正文引用一致、数据库表是否与类图对应。通过评审后合并入仓库统一版本。这样即使三人工作在不同模块,最终交付的原型、两份说明书与博客仍是一套自洽的材料。
四、原型与后端设计展示
- 原型在线预览:http://10.21.76.30:4096/
- 后端设计图(架构分层图、功能模块图、五类 UML 图、ER 图、关系模式主外键图、对象—关系映射总图)全部以矢量图收录于两份设计说明书 PDF(链接见第五节),可无级放大查看,图号与图注见各文档的图表清单;各图的设计要点已在本文第二节结合文字逐项说明,博客不重复放置图片。
五、交付物与链接
| 交付物 | 链接 |
|---|---|
| GitHub 团队仓库 | https://github.com/lokidundun/TopViewbot |
| 对对队_系统设计说明书.pdf | 在线预览 / 下载 |
| 对对队_数据库设计说明书.pdf | 在线预览 / 下载 |
| 原型在线预览链接 | http://10.21.76.30:4096/ |

浙公网安备 33010602011771号