jw_JIAWEI WANGGitHub ↗
← 返回项目作品
01 / FEATURED · AI APPLICATION / CASE STUDY

MonashMate

校园行政助手 Agent

让每一次制度问答,
都有当前有效的依据。

面向校园行政与学生服务的个人项目。答案不仅要相关,还需要来自用户权限范围内、当前有效的制度版本。

ROLE个人项目 · 独立设计与开发
FOCUS校园行政助手 Agent
SOURCEGitHub ↗ · 私有仓库,需访问权限
GoGinCloudWeGo EinoNext.jsMySQLElasticsearchRedis Streams
01 / THE PROBLEM

为什么做这个项目

校园行政问答的难点,不只是找到一段相关文字。同一项制度可能存在多个版本,不同部门有不同适用范围,学生的一次提问也可能跨越多个业务流程。MonashMate 将检索、事实校验、任务编排和反馈回归放在同一条工程链路中,让答案的来源与适用边界可以被检查。

01

学生

政策问答、历史会话、引用展开与回答反馈。

02

部门管理员

管理权限范围内的制度、上传文档与查看版本历史。

03

系统管理员

跨部门知识管理、问题审核与策略回归对比。

02 / HOW IT WORKS

从输入,到可检查的结果

  1. 01

    识别与路由

    加载调用者权限,识别问题意图;信息不足时先澄清,在授权范围内选择部门。

  2. 02

    部门检索

    部门任务有界并发;每个部门依次执行 BM25 和向量召回,以 RRF 融合结果。

  3. 03

    事实回查

    批量回查 MySQL,剔除过期、无效或越权候选,并用事实层正文及元数据补齐证据。

  4. 04

    生成与验证

    组装会话和证据,检查引用、覆盖度与冲突,输出带来源的答案,或有限回答、转人工。

03 / SYSTEM DESIGN

架构与职责划分

把不同的职责放在明确的边界内,让每一步的输入、输出和失败方式都可以单独理解。

ARCHITECTURE MAPMonashMate · 可信问答架构
授权部门检索、MySQL 事实校验、上下文组装与引用验证的逻辑数据流。
蓝色:核心模块 · 虚线:辅助依赖 / 独立路径↔ 横向滑动查看完整架构

检索与校验由部门流程执行;箭头表示逻辑数据流,不表示数据库之间直接调用。

分层职责速览

01 / 交互层Next.js 学生端与管理员工作台
02 / 编排层Go / Gin API → Eino Graph → 部门任务
03 / 数据层Elasticsearch 负责召回,MySQL 管理制度事实
04 / 发布链路事务 Outbox → Redis Stream → 索引校验 → 版本激活

核心工程实现

部门作用域与 Hybrid RAG:BM25 → Vector → RRF

检索在已授权的部门范围内执行:先运行 BM25,再生成查询向量并执行向量召回,两路查询均带部门过滤。BM25 对制度名、数字和条款编号更敏感,向量检索补充语义相近的表达;RRF 按片段 ID 合并排名,累计 1 / (k + rank),避免直接比较两类分数量纲。仓库默认两路各取至多 20 个候选,k = 60,最终最多返回 5 条。

融合完成后批量回查 MySQL,检查制度所属部门、当前版本及生效区间,用事实层的正文和元数据替换索引内容,再交给可选重排器。ES 负责找到候选,MySQL 决定候选能否成为证据。当前 Campus 路径的向量请求失败或维度不符会使该次检索报错,避免静默改变检索语义。

制度发布状态机:事务 Outbox 与索引校验

上传内容经过 Python 解析与 Go 切分后,将待发布版本、片段与 Outbox 事件写入同一个 MySQL 事务。后台发布链路通过 Redis Stream 驱动向量生成和 Elasticsearch 索引写入;写入结束还要核对片段数量、ID 等信息,通过校验后才申请版本激活。

激活事务重新检查生效和过期时间并切换当前版本,使“文件已上传”和“新版可用于问答”成为不同状态。消费组可以认领超时未确认任务,失败重试耗尽后进入死信队列。发布失败时仍有效的旧版继续服务,避免半完成的索引覆盖线上依据。

Eino Graph 与有界部门任务扇出

全局 Graph 先识别意图、校验信息完整性,并依据调用者权限构造部门任务。部门执行器在同一 Go 进程内有界并发,各自具有超时与工具预算,可使用受控 ReAct 执行检索;整体请求另设截止时间,防止最慢部门无限拖延整次回答。

全局流程汇总各部门实际返回的证据,再决定完整回答、有限回答、澄清或转人工。部门任务隔离的是数据范围和执行预算,并非独立部署的微服务;缺失部门的证据不会被其他部门的结果自动补成已证实结论。

会话焦点、上下文组装与引用验证

Redis 会话焦点用于理解追问,MySQL 持久记忆补充背景,上下文组装器记录哪些材料被保留或舍弃。最终回答的引用只能来自本轮证据白名单,不能把模型生成的链接或历史对话中的说法直接作为制度依据。

验证器检查主张与引用的对应关系、问题覆盖度及证据冲突,必要时进入受控重新生成分支。对于没有足够材料支持的内容,保留回答边界或交给人工,避免把只覆盖部分问题的片段扩展成完整结论。

反馈 → 诊断回放 → 版本化发布回归

Business Trace 记录执行过程和证据决策。管理员将反馈归因到意图、检索、知识或回答生成问题,建立含正确预期、必需来源、必需短语和禁止结论的回放案例,比较基线与候选策略。诊断回放用于定位某一类失败。

正式发布资格由另一道完整回归决定:版本化套件覆盖七个部门、追问、跨部门、澄清和越权拒绝,要求零回归、零权限泄漏且至少改善一例。当前自动化仅创建预定义的证据摘录候选和回放草稿;人工审核记录与实际策略切换仍分开处理。

服务端授权、运行就绪与发布就绪

登录使用 bcrypt 校验密码并签发 HMAC 签名令牌;后续请求验签后重新读取用户状态与部门权限,使禁用账号或撤销授权能够影响下一次请求。前端按角色呈现工作台,服务端对实际数据访问独立校验。

/readyz 检查运行依赖,/releasez 另行检查真实模型评测证据。Prometheus、业务 Trace、集成测试与发布检查分别覆盖执行链路、权限边界以及 MySQL 当前片段与 ES 索引的一致性;运行可用和具备模型发布依据使用不同门槛。

04 / ENGINEERING DECISIONS

技术难点与设计取舍

01

为什么搜索索引不直接作为事实?

索引是召回入口,可能保留旧版本或存在发布延迟。把有效性判断放到 MySQL 事实层,可以在生成前统一核对制度版本、部门与生效区间。

02

为什么索引完成后才激活新版?

上传、解析、向量生成和索引写入不是同一个事务。先保存待发布状态,再校验索引片段,最后事务激活,可以让失败的发布任务恢复,并让仍有效的旧制度继续服务。

03

为什么单条改进还需要全量回归?

一个策略可能修好当前案例,却破坏其他部门或追问场景。诊断回放用于定位问题;正式发布审核还需完整版本化套件、零回归、零越权,并至少改善一例。

06 / VERIFY & REFLECT

如何验证,以及做到哪里

01

版本与权限

集成测试和回归样本覆盖制度有效性、部门作用域、越权拒绝及发布失败路径。

02

问答质量

版本化用例覆盖七个部门,以及追问、跨部门、澄清和拒绝场景;回放比较基线与候选。

03

运行可观测性

Prometheus 与 Business Trace 记录执行和发布过程;运行就绪与模型发布就绪分别检查。

CURRENT SCOPE

当前实现边界

部门任务在同一 Go 进程内运行,并通过任务权限、并发限制、截止时间与工具预算约束执行。当前反馈自动化提出预定义的证据摘录候选,正式策略调整仍需人工审核与后续发布决策。

继续阅读

README / 架构与代码导航 ↗发布与预览手册 ↗

MonashMate 为私有仓库,代码与文档链接需要仓库访问权限。

内容依据当前项目 README 与架构文档整理;展示工程设计和验证方式,不将示意图或流程描述作为实时运行数据。
NEXT PROJECT / 02

RelayIM-Go

分布式实时消息后端

↗