CampusMind-Agent

# CampusMind-Agent ## 核心能力 - 学生端 SSE 流式聊天，前端可展示打字机式输出。 - Basic Auth 登录，支持学生和管理员角色隔离。 - LangGraph 多 Agent 工作流：Memory、Supervisor、Knowledge、RiskGuardian、Companion、Counselor，未安装 LangGraph 时自动回退到自研有限循环 runtime。 - 动态路由 RAG：先判断 `CHAT / CONSULT / RISK`，普通问题不查知识库，咨询和风险场景才进入检索增强。 - Chroma 向量 RAG 知识库：支持 Markdown、txt、PDF 文件上传，自动切块，使用 `text-embedding-3-small` 写入向量库，并与 BM25 关键词召回融合后进入本地 reranker；向量不可用时保留本地 BM25 + 词面检索兜底。 - 心理风险评估：高风险词典优先、LLM JSON 评估、关键词兜底。 - 后台报告：记录情绪标签、情绪分数、风险等级、置信度和摘要，但学生端不展示后台评估结果。 - 数据闭环：咨询/风险消息完整写入 MySQL，短期上下文写入 Redis，高风险消息写入 Excel 台账并通过邮件发送预警。 - 本地微调模型接入：支持通过 Ollama 加载 `mindbridge-qwen2.5-7b-ft-q4_k_m.gguf`。 - OpenAI-compatible API 接入：也可切换到云端模型。 - MCP 工具服务：暴露 Excel 报告写入和风险通知工具，后端高风险后处理通过 MCP client 调用这些工具。 - RAG 评测：Recall@K、Precision@K、MRR、NDCG@K、HitRate。 ## 技术栈 ```text 语言：Python Web 框架：FastAPI 服务运行：Uvicorn / ASGI 数据库：MySQL，SQLAlchemy ORM，PyMySQL 驱动 短期记忆：Redis 配置管理：pydantic-settings，.env AI 接入：Ollama，本地微调 GGUF 模型，OpenAI-compatible API，Mock Provider Agent 编排：LangGraph bounded agent loop，自研 runtime 兜底 RAG：本地知识库切块、OpenAI Embeddings、Chroma 向量库、BM25、分数融合、本地 reranker、上下文扩展 流式输出：Server-Sent Events 文档解析：pypdf Excel 台账：openpyxl 邮件预警：SMTP / smtplib 前端：原生 HTML / CSS / JavaScript 认证：Basic Auth 工具协议：MCP ``` 说明：当前 Python 版已经提供 LangGraph runtime，入口在 `app/agents/langgraph_runtime.py`；同时保留 `app/agents/runtime.py` 作为无框架兜底。RAG 默认使用 Chroma 本地持久化向量库做语义召回，同时用 BM25 做关键词召回，再融合并本地 rerank；未安装 Chroma、未配置 `OPENAI_API_KEY` 或向量服务异常时，会自动回退到本地 BM25 + `hybrid_score` reranker，避免演示环境中断。 ## 目录结构 ```text app/ ├── agents/ # LangGraph 多 Agent 编排和自研 runtime 兜底 ├── api/ # FastAPI 路由 ├── core/ # 配置、数据库、安全、启动初始化 ├── knowledge/ # 内置校园心理知识库 ├── mcp_tools/ # MCP 工具服务 ├── models/ # SQLAlchemy 实体 ├── rag_eval/ # RAG 评测脚本和数据集 ├── schemas/ # Pydantic DTO ├── services/ # AI、聊天、知识库、评估、报告、工具服务 └── static/ # 原生前端页面 models/mindbridge-qwen2.5-7b-ft/ ├── Modelfile # Ollama 模型定义 └── README.md # GGUF 模型放置说明 scripts/ ├── run-dev.sh ├── start-ollama.sh ├── create-finetuned-model.sh └── package-release.sh ``` ## Agent loop 每轮对话进入一个 LangGraph bounded agent loop，由 controller 根据共享状态自主选择下一个 Agent，最多执行 8 个 Agent 步，防止心理安全场景出现无限自主循环： ```text controller -> MemoryAgent / SupervisorAgent / KnowledgeAgent / RiskGuardianAgent / CompanionAgent / CounselorAgent -> controller -> END 或 max_steps=8 -> SSE 流式输出 ``` 各 Agent 分工： - `MemoryAgent`：优先从 Redis 读取本会话短期记忆；Redis 为空时从 MySQL 最近消息回填，并生成本轮记忆摘要。 - `SupervisorAgent`：判断 `CHAT / CONSULT / RISK`，决定是否进入心理支持链路。 - `KnowledgeAgent`：将学生输入改写为知识库查询词，执行 RAG 检索。 - `RiskGuardianAgent`：执行后台心理状态评估，同时保留高风险词库硬兜底。 - `CompanionAgent`：处理普通学习、编程、校园事务和闲聊。 - `CounselorAgent`：结合记忆、RAG 和风险评估，生成心理支持回复 prompt。 ## 安装依赖 ```bash pip install -r requirements.txt ``` `requirements.txt` 已包含： ```text langchain-core langgraph chromadb pymysql redis ``` 如果交付环境暂时无法安装 LangGraph，系统仍会自动回退到自研 runtime，不影响 Mock 演示和基本功能。 ## MySQL 和 Redis 配置 系统默认使用 MySQL 保存完整业务数据和完整聊天消息，使用 Redis 保存短期对话记忆。启动服务前先创建数据库： ```sql CREATE DATABASE mindbridge DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; CREATE USER 'mindbridge'@'%' IDENTIFIED BY 'mindbridge'; GRANT ALL PRIVILEGES ON mindbridge.* TO 'mindbridge'@'%'; FLUSH PRIVILEGES; ``` `.env` 中配置连接： ```env DATABASE_URL=mysql+pymysql://mindbridge:mindbridge@127.0.0.1:3306/mindbridge?charset=utf8mb4 REDIS_URL=redis://127.0.0.1:6379/0 REDIS_MEMORY_TTL_SECONDS=86400 REDIS_MEMORY_MAX_MESSAGES=40 ``` 完整聊天记录写入 MySQL 的 `chat_sessions`、`chat_messages` 等表；压缩后的长期会话记忆写入 `long_term_memories`，并记录来源消息数和版本。Redis 保存每个会话最近 `REDIS_MEMORY_MAX_MESSAGES` 条短期上下文以及长期摘要缓存，并通过 `REDIS_MEMORY_TTL_SECONDS` 自动过期。Redis 不可用时默认回退 MySQL；生产环境可设置 `REDIS_MEMORY_REQUIRED=true` 让服务快速失败，避免配置存在但实际未使用。 ## 快速启动 Mock 演示 Mock 模式不需要 Ollama 或模型文件，但仍需要 MySQL 和 Redis，适合先演示完整业务流程。 ```bash cd mindbridge-py python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt AI_PROVIDER=mock uvicorn app.main:app --host 127.0.0.1 --port 8080 ``` 浏览器打开： ```text http://127.0.0.1:8080 ``` 默认账号： ```text student / student123 admin / admin123 ``` ## Docker Compose 一键启动 仓库提供 `Dockerfile` 和 `docker-compose.yml`，会启动： - `mysql`：MySQL 8.4，容器内端口 `3306`，宿主机映射 `13306` - `redis`：Redis 7，容器内端口 `6379`，宿主机映射 `16379` - `app`：MindBridge FastAPI 服务，宿主机端口 `8080` 默认配置会让应用容器访问宿主机 Ollama： ```bash docker compose up -d --build ``` 如果 Ollama 已经有下列模型，容器即可使用真实本地聊天模型链路： ```text mindbridge-qwen2.5-7b-ft:latest ``` ## Chroma 向量库与快照 应用启动时会同步 `app/knowledge/*.md` 内置默认知识库到数据库。当前默认文档覆盖校园心理支持总则、风险等级策略、焦虑恐慌、情绪低落、睡眠作息、学业压力、考试季、人际关系、新生适应、咨询转介和隐私边界等主题；如果默认 md 内容发生变化，重启后对应来源会按当前切块规则刷新入库。 知识库默认优先使用 Chroma 持久化向量库，embedding 由 OpenAI `text-embedding-3-small` 提供。查询时会同时取向量候选和 BM25 候选，按配置权重融合后进入本地 reranker。没有 `OPENAI_API_KEY`、缺少 `chromadb` 或向量调用失败时，会回退到本地 BM25 + `hybrid_score` reranker： ```env OPENAI_API_KEY=你的_API_Key OPENAI_EMBEDDING_MODEL=text-embedding-3-small KNOWLEDGE_VECTOR_ENABLED=true KNOWLEDGE_VECTOR_REQUIRED=false KNOWLEDGE_CANDIDATE_K=16 KNOWLEDGE_HYBRID_VECTOR_WEIGHT=0.65 KNOWLEDGE_HYBRID_BM25_WEIGHT=0.35 KNOWLEDGE_RERANK_ENABLED=true CHROMA_PERSIST_DIR=data/chroma CHROMA_SNAPSHOT_DIR=data/chroma-snapshots ``` 管理员接口： ```bash curl -u admin:admin123 http://127.0.0.1:8080/api/admin/knowledge/status curl -u admin:admin123 -X POST http://127.0.0.1:8080/api/admin/knowledge/rebuild-vector curl -u admin:admin123 -X POST http://127.0.0.1:8080/api/admin/knowledge/backup ``` 当 `KNOWLEDGE_VECTOR_REQUIRED=false` 时，如果 Chroma 或 embedding 服务不可用，系统会降级到本地 BM25 + 词面 rerank；设为 `true` 则启动或检索失败时直接暴露错误。 ## 工具队列、限流与死信 心理报告生成后，工具链不会阻塞学生端流式回复，而是写入 `tool_jobs` 队列表： ```text EXCEL_REPORT CASE_CREATE -> ALERT_SEND ``` Excel 写入使用进程内锁串行化，个案创建保持幂等；预警发送使用独立线程池并支持每分钟限流。失败任务会按延迟重试，超过 `TOOL_QUEUE_MAX_ATTEMPTS` 后进入 `dead_letter_records`。 ```env TOOL_QUEUE_ENABLED=true TOOL_QUEUE_EXCEL_WORKERS=1 TOOL_QUEUE_EMAIL_WORKERS=2 ALERT_EMAIL_RATE_LIMIT_PER_MINUTE=30 ALERT_EMAIL_DELIVERY_MODE=log ``` `ALERT_EMAIL_DELIVERY_MODE=log` 适合本地演示；生产发邮件时改为 `smtp` 并配置 SMTP。 ## 邮件预警配置 高风险消息会触发心理报告，并由后端通过 MCP 工具调用完成 Excel 台账写入和邮件预警。发送邮件前需要在 `.env` 中配置 SMTP： ```env SMTP_HOST=smtp.example.com SMTP_PORT=587 SMTP_USERNAME=your-account@example.com SMTP_PASSWORD=your-smtp-password SMTP_USE_TLS=true SMTP_USE_SSL=false ALERT_EMAIL_FROM=your-account@example.com ALERT_EMAIL_TO=counselor@example.com,admin@example.com ALERT_EMAIL_SUBJECT_PREFIX=[MindBridge 高风险预警] ``` 未配置 SMTP 或收件人时，系统不会中断聊天流程，但会在 `alert_records` 中写入 `FAILED` 记录，提示缺少的配置项。 ## 接入本地微调 GGUF 模型 Python 版默认预留本地模型名： ```text mindbridge-qwen2.5-7b-ft:latest ``` 模型目录： ```text models/mindbridge-qwen2.5-7b-ft/ ``` 需要放入的 GGUF 权重： ```text models/mindbridge-qwen2.5-7b-ft/mindbridge-qwen2.5-7b-ft-q4_k_m.gguf ``` 如果本机已经有其他位置的 GGUF 模型文件，可以通过 `UPSTREAM_GGUF` 指定路径并建立软链接： ```bash UPSTREAM_GGUF=/path/to/mindbridge-qwen2.5-7b-ft-q4_k_m.gguf ./scripts/create-finetuned-model.sh ``` 创建 Ollama 模型： ```bash ./scripts/create-finetuned-model.sh ``` 启动 Ollama： ```bash ./scripts/start-ollama.sh ``` 启动 Python 服务： ```bash AI_PROVIDER=ollama ./scripts/run-dev.sh ``` 查看模型接入状态： ```bash curl -u student:student123 http://127.0.0.1:8080/api/agent/status ``` 返回结果中的 `finetunedModel.ggufExists` 和 `finetunedModel.modelfileExists` 会显示模型资产是否就绪。 同时 `agentFramework.active` 会显示当前实际使用的 Agent 编排框架： ```text langgraph custom ``` ## 接入 OpenAI-compatible API ```bash AI_PROVIDER=openai \ OPENAI_API_KEY=你的_API_Key \ OPENAI_MODEL=gpt-4o-mini \ OPENAI_EMBEDDING_MODEL=text-embedding-3-small \ uvicorn app.main:app --host 127.0.0.1 --port 8080 ``` 知识库向量检索也使用同一个 `OPENAI_API_KEY` 调用 embeddings API。相关配置： ```env KNOWLEDGE_VECTOR_ENABLED=true KNOWLEDGE_VECTOR_REQUIRED=false OPENAI_EMBEDDING_MODEL=text-embedding-3-small KNOWLEDGE_CANDIDATE_K=16 KNOWLEDGE_HYBRID_VECTOR_WEIGHT=0.65 KNOWLEDGE_HYBRID_BM25_WEIGHT=0.35 KNOWLEDGE_RERANK_ENABLED=true CHROMA_PERSIST_DIR=data/chroma CHROMA_COLLECTION_NAME=mindbridge_knowledge ``` 当 `KNOWLEDGE_VECTOR_REQUIRED=false` 时，缺少 API key 或 Chroma 不可用不会阻断聊天，系统会回退到本地 BM25 + `hybrid_score` reranker。若交付验收要求必须走 Chroma 向量检索，可设置 `KNOWLEDGE_VECTOR_REQUIRED=true`。 ## 调用示例 学生流式聊天： ```bash curl -N -u student:student123 \ -H 'Content-Type: application/json' \ -d '{"message":"我最近很焦虑，晚上总是睡不着"}' \ http://127.0.0.1:8080/api/chat/stream ``` 高风险示例，会触发心理报告、风险个案创建和预警工具计划；Excel 保留为台账输出，邮件/log 是预警通道之一： ```bash curl -N -u student:student123 \ -H 'Content-Type: application/json' \ -d '{"message":"我不想活了，感觉撑不下去了"}' \ http://127.0.0.1:8080/api/chat/stream ``` 管理员查看报告： ```bash curl -u admin:admin123 http://127.0.0.1:8080/api/admin/reports ``` 管理员追加知识库： ```bash curl -u admin:admin123 \ -H 'Content-Type: application/json' \ -d '{"source":"sleep-guide","content":"失眠时可先固定起床时间，减少睡前屏幕刺激，必要时联系校心理中心。"}' \ http://127.0.0.1:8080/api/admin/knowledge ``` 追加知识库时，系统会同步写入 MySQL 分块和 Chroma 向量库；已有分块会在首次向量检索时自动补建 Chroma 索引。 ## RAG 评测 项目包含两类互补评测：60条固定集用于Recall@K、MRR等确定性检索回归；12条人工参考集使用RAGAS 0.4.3评估Context Precision、Context Recall、Faithfulness和Answer Relevancy。RAGAS使用独立虚拟环境，避免其LangChain依赖影响生产Runtime。完整配置、命令和指标口径见 `docs/evaluation.md`。 ```bash AI_PROVIDER=mock python -m app.rag_eval.runner ``` 评测报告输出到： ```text target/rag-eval-report.json ``` ## 单元测试 当前 `tests/` 里的基础回归用例使用 Python 标准库 `unittest`，不依赖 `pytest`： ```bash python -m unittest discover -s tests ``` ## Agent Runtime Harness 线上对话通过 `MindBridgeAgentHarness` 组织一次 Agent run。Harness 不改变 LangGraph / custom runtime 内部的多 Agent 协作顺序，而是在外层统一管理： - 输入脱敏和 session 解析。 - Memory / Supervisor / Knowledge / RiskGuardian / Response Agent 调用。 - 心理报告落库和工具计划生成。 - 学生与助手消息持久化。 - Agent steps、知识召回、风险结果等 trace 数据输出。 因此 HTTP 层只负责认证和 SSE 流式输出，Agent 后处理逻辑集中在 runtime harness 内。 ## Engineering Harness 项目提供一键工程 harness，用 mock AI、临时 SQLite、内存短期记忆和本地输出验证核心链路： - Risk Safety Harness：高风险识别、报告生成、后台元数据不外显、工具队列入队。 - Agent Routing Harness：通过 `MindBridgeAgentHarness` 验证 CHAT / CONSULT / RISK 路由和多 Agent 步骤。 - Standard Skills Harness：验证 `skills/*/SKILL.md` 标准 Skill 加载、选择逻辑和交接摘要模板渲染。 - RAG Harness：基于内置评测集验证 Recall@K、MRR、NDCG 和 HitRate。 - API Harness：健康检查、认证授权、SSE 聊天、管理员知识库接口。 - Tool Queue Harness：Excel / case / alert 依赖、幂等、限流和 dead letter。 ```bash python3 -m app.harness.runner ``` 报告输出到： ```text target/harness/harness-report.json target/harness/rag-eval-report.json ``` ## MCP 工具服务 MCP Python 包建议使用 Python 3.10 或 3.11 安装运行。 ```bash python -m app.mcp_tools.server ``` 业务后端触发报告后处理时，默认通过异步工具队列复用同一套工具实现；关闭队列后会作为 MCP client 通过 stdio 启动同一个 MCP server。 暴露工具： - `mindbridge_excel_report` - `mindbridge_case_create` - `mindbridge_alert_send` - `mindbridge_alert_ack` - `mindbridge_case_note_add` - `mindbridge_alert_notify` 内置标准 Skills 位于 `skills/*/SKILL.md`，运行时由 `MindBridgeSkillRegistry` 加载： - `supportive_response_baseline`：心理咨询与风险回复的基础共情、边界和学生端表达规则。 - `high_risk_safety_plan`：高风险时引导模型优先完成短期安全计划。 - `anxiety_grounding_support`：焦虑、惊恐、崩溃场景的稳定化和 grounding 指引。 - `sleep_routine_support`：失眠、睡眠节律紊乱场景的安全睡眠建议。 - `academic_stress_planning`：考试、作业、论文、绩点压力的下一步拆解。 - `referral_resource_guidance`：校内心理中心、辅导员、可信任支持人和紧急资源转介。 - `counselor_handoff_summary`：生成给辅导员/管理员看的个案交接摘要模板。