对对队第二次团队作业——原型设计+概要设计

项目 内容
作业所属课程 软件工程 · 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/
posted @ 2026-11-20 17:22  玖驻  阅读(10)  评论(0)    收藏  举报