Aegis Psych Agent 是一个校园心理支持多 Agent 平台，围绕学生端倾诉、心理知识检索、风险识别、辅导员工作台和高风险工具执行闭环五个环节展开。

它不是一个简单的聊天机器人，而是将「学生侧即时支持」与「管理侧可审计干预」拆分为两套独立信息架构，并通过统一的后端 Agent Runtime Harness 处理意图路由、记忆注入、RAG 检索、风险报告、trace 落库与工具计划。

设计时重点解决三个工程问题：

关键事实一览

flowchart LR
    Student["学生端 /student"] --> API["FastAPI API 层"]
    Admin["管理员端 /admin"] --> API

    API --> Harness["AegisAgentHarness"]
    Harness --> Runtime["Agent Runtime<br/>默认 autonomous Blackboard"]

    Runtime --> Memory["MemoryAgent"]
    Runtime --> Lead["Lead / Supervisor Agent"]
    Runtime --> Risk["RiskGuardianAgent"]
    Runtime --> Knowledge["KnowledgeAgent"]
    Runtime --> Counselor["CounselorAgent"]
    Runtime --> Companion["CompanionAgent"]

    Knowledge --> RAG["Hybrid RAG<br/>BM25 + 本地向量 + 三引擎精排"]
    Harness --> Store["SQLite / MySQL / 可选 PostgreSQL<br/>messages, memory, reports, traces"]
    Harness --> ToolPlan["Governed ToolJob"]
    ToolPlan --> Queue["Tool Queue Worker"]
    Queue --> MCP["FastMCP / internal tools"]
    MCP --> Outputs["Excel, Alert, Email, Handoff, Audit"]

    Admin --> Eval["Eval & Harness Reports"]
    Eval --> Store

    classDef client fill:#E8F4FD,stroke:#4A90D9,stroke-width:1.5px,color:#1A4971
    classDef core fill:#FFF4E6,stroke:#E8A33D,stroke-width:1.5px,color:#7A4A00
    classDef agent fill:#F3EAFB,stroke:#9B72CF,stroke-width:1.5px,color:#4A2D73
    classDef store fill:#EAF6EC,stroke:#5BAF6F,stroke-width:1.5px,color:#1E5A2E
    classDef tool fill:#FDECEF,stroke:#D97A94,stroke-width:1.5px,color:#7A2338

    class Student,Admin client
    class API,Harness core
    class Runtime,Memory,Lead,Risk,Knowledge,Counselor,Companion,RAG agent
    class Store,Eval store
    class ToolPlan,Queue,MCP,Outputs tool

数据流说明：学生消息进入 Harness → 输入脱敏 → 意图路由 → 按意图决定是否检索 → 多 Agent 在黑板协议下协作 → 风险双通道判定 → 生成 ToolJob 而非直接执行 → 回复流式返回同时工具异步入队 → trace / 报告 / 审计全量落库。

默认使用 SQLite，零外部依赖即可完成端到端演示。

# 1. 克隆仓库
git clone https://github.com/shangguanyunji663/aegis-psych-agent.git
cd aegis-psych-agent

# 2. 创建并激活虚拟环境
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate

# 3. 安装依赖
pip install -r requirements.txt

# 4. 配置环境变量并初始化数据库
cp .env.example .env
python -m app.init_db

# 5. 启动服务
uvicorn app.main:app --host 127.0.0.1 --port 8091

切换到 MySQL（本机或 Compose 提供的 MySQL 8.0），在 .env 中设置：

DATABASE_URL=mysql+pymysql://root:你的密码@localhost:3306/aegis?charset=utf8mb4

首次启动自动建库建表（utf8mb4）；已有 SQLite 数据可通过 python -m scripts.migrate_sqlite_to_mysql 一键迁移，原文件保留为备份。

docker compose up --build

Compose 会启动应用、MySQL 8.0、Redis 与 Chroma。默认本地模式仍使用 SQLite；如需切换数据库或向量后端，在 .env 中调整 DATABASE_URL、VECTOR_ENABLED、VECTOR_BACKEND 等配置。

注意：依赖中包含 PostgreSQL 驱动，但当前 Compose 拓扑不启动 PostgreSQL 服务。

学生端 · 对话（信笺往来）	管理端 · 咨询工作台

界面支持三套设计概念（信笺往来 / 夜航电台 / 群岛图鉴），右下角切换器即时换形态；截图为「信笺往来」概念，数据来自本地演示环境。

普通启动默认不加载训练模型（RISK_QLORA_ENABLED=false），RiskGuardian 保持现有规则 / 通用 LLM 行为。

# Windows 示例
set AEGIS_TRAINING_ROOT=D:\AegisTraining
set AEGIS_QLORA_MODEL_DIR=%AEGIS_TRAINING_ROOT%\exports\aegis-risk-qwen3.5-2b-v9-merged

%AEGIS_TRAINING_ROOT%\envs\qlora-qwen35\python.exe ^
  %AEGIS_TRAINING_ROOT%\training\scripts\serve_risk_qlora.py ^
  --model-dir "%AEGIS_QLORA_MODEL_DIR%"

curl http://127.0.0.1:8301/health

RISK_QLORA_ENABLED=true
RISK_QLORA_URL=https://your-approved-qlora.example.com
RISK_QLORA_TIMEOUT_SECONDS=8

.
├── app/                         # 后端主包
│   ├── main.py                  # 应用入口：create_app 装配 + 路由注册
│   ├── config.py                # pydantic-settings 全局配置
│   ├── models.py                # 领域模型：Intent / RiskLevel / ChatResponse 等
│   ├── entities.py              # SQLAlchemy ORM 实体
│   ├── database.py              # 引擎 / 会话工厂 / 建表 / 迁移 / 就绪检查
│   ├── init_db.py               # 数据库初始化与默认账号引导
│   ├── assessment.py            # 规则式风险评估（高危/中危关键词单一来源）
│   ├── skills.py                # SkillRegistry：注册式 Skill、标准 Skill 与自动蒸馏
│   ├── core/                    # 横切原语：auth | privacy | runtime_services | network(SSRF 防护) | utils
│   ├── llm/                     # 模型后端：Mock / OpenAI / Ollama / RiskQloraClient + prompts
│   ├── agents/                  # 智能体层：classic | harness | model_profiles | orchestrator | runtime | skill_selection | langgraph_runtime
│   ├── autonomous/              # 自治协作：events | registry | board | coordinator | agents | runtime
│   ├── rag/                     # 检索与记忆：text | scoring | chunking | facts(L2) | memory(L3) | vector_store | reranker(CE 精排)
│   ├── repository/              # 持久化仓储：会话、L2 用户事实、知识库、报告与工具任务
│   ├── tools/                   # 工具治理：contracts（契约）| gateway（网关）
│   ├── services/                # 业务服务：report_case | tool_executor | tool_queue | tool_records | tool_governance
│   ├── api/                     # HTTP 路由：schemas | deps | middleware | pages | system | auth_routes | chat | admin
│   ├── evaluation/              # 评测：runner | rag | datasets | report_html | runtime_ab | judge + harness/
│   └── mcp/                     # MCP 边界：server（FastMCP 服务）| client（stdio 客户端）
├── knowledge/                   # 内置心理支持知识库（当前 173 篇 .md）
├── eval/                        # 评测 CLI 与 fixtures（路由 / 风险 / 安全 / 多轮 / 检索 / RAG 数据集）
├── skills/                      # 人工策展 Skill 规范；运行时可在 skills/auto/ 生成 auto Skill
├── frontend/                    # 前端：Vite + React 19 + TS（src/ 三概念 × 三页 + shared/ + lib/），产物 dist/ 由 FastAPI 同源托管
├── tests/                       # pytest 测试（16 个模块）
├── scripts/                     # 启动/联调/诊断：start-local | start-compose | smoke_chat | probe_glm
│                                #                migrate_sqlite_to_mysql | eval_risk_dual_path | run_benchmark | analyze_layers
│                                #                eval_minilm_ablation_tmp | eval_ce_tmp（第十九轮 RAG 对照评测）
│                                #                eval_bge_small_zh_recall | eval_ce_fusion | eval_v2_full | eval_retrieval_window（第二十一轮 RAG 对照评测）
├── docs/                        # 架构、安全、演示、教师手册与前端学习文档
│   └── records/                 # 迭代记录（第 1 ~ 21 轮）
├── Dockerfile
├── docker-compose.yml
└── requirements.txt

• 账号体系：学生自由注册；教师凭邀请码注册后进入咨询工作台。
• 会话管理：登录登出、会话创建与新会话切换；重命名/删除已提供 API（PATCH / DELETE /api/sessions/{id}），界面暂无对应按钮。
• 对话助手「小暖」：SSE 真流式输出，消息头像与入场动画、欢迎屏话题 chips；顶栏时段问候与服务状态圆点（60 秒自动刷新）。另有 POST /api/chat 非流式兼容路径。
• 实用卡片：「心情速选」2×2 图标卡一键填入表达、「需要立即帮助」（心理援助热线 12356 / 120）与「60 秒放松练习」。
• 三套设计概念：信笺往来（默认）/ 夜航电台 / 群岛图鉴，右下角切换器即时换形态，选择记在 localStorage；首屏服务端注入 html[data-theme="light"]（仅亮色一档，亮暗双模式已移除），概念由 html[data-concept] 驱动，切换无闪烁。
• 三类回复路径：低风险陪伴、心理咨询建议、高风险安全回应。低风险对话在生成时逐字直播，中/高风险回复经安全复核通过后再输出。
• 分层记忆注入：L2 跨会话当前有效事实 + L3 会话滚动摘要 + L4 最近原话窗口共同注入；当前有效事实优先于可能过期的摘要，避免旧状态干扰当前回应。
• 信息隔离：高风险内容不向学生暴露内部报告字段，避免二次伤害与信息泄露。

• 三列页签工作台：桌面端固定一屏、界面全中文。左列「个案 | 知识库 | 协作状态」、中列「风险报告 | 对话回放」、右列「详情检查器 + 工作台」。操作详见《咨询工作台使用手册（教师版）》。
• 风险处置：报告列表、状态流转与报告 trace 查看；个案创建、辅导员确认、备注追加与状态更新。
• 知识库运维：检索、内容上传（.md/.txt/.pdf）、重建索引与备份；向量索引重建另提供 /api/admin/knowledge/rebuild-vector。
• 工具与审计：ToolJob 与执行记录（ExcelRecord/AlertRecord）界面可查；「审计」页签查看操作审计；ToolAudit 与 DeadLetter 提供独立 API（tool-audits / dead-letters）。
• 运行态观测：Runtime 协作状态（编排引擎 / 调度 / 存储 / 队列与智能体名单）可视，模型状态在顶栏胶囊展示；Agent 模型配置与私有记忆提供 agent-models / agent-memories 查询接口。
• 评测入口：管理端可一键触发综合评测；Harness 验证另由命令行 python -m app.evaluation.harness.runner 执行。

Skill 自动蒸馏当前会直接重载并参与后续匹配，人工审核工作台尚未实现（见 Roadmap）。

• FastMCP Server：暴露 case create、case ack、case note add、alert、ledger、email、handoff、resource lookup 等工具。
• MCP Client：支持在平台内切换到 MCP 后端执行工具。
• 工具契约：限制角色、风险等级、审批要求、脱敏字段与最大重试次数。
• 后台 Worker：支持批量领取、依赖调度、失败重试、限流与 dead letter。
• 真实输出：Excel 写入、Alert 独立记录、邮件发送或日志投递、handoff Markdown 文件。

配置基于 pydantic-settings，优先级为：环境变量 > .env > .env.example 建议值 > Settings 代码默认值。 下表「默认」均指 Settings 代码默认值。

# 初始化数据库
python -m app.init_db

# 后端测试（只收集 tests/，scripts/ 下的联调脚本不在 pytest 范围）
python -m pytest tests -q

# 前端检查（第二十轮起为 Vite 工程，不再有手写前端脚本）
cd frontend && npm run lint && npm run build && cd ..

# 综合评测
python -m eval.run_eval

# RAG 独立评测（双口径 + 消融）
python -m app.evaluation.rag

# 本地性能 benchmark（并发 / 延迟 / 吞吐 / 缓存 / ToolJob）
python -m scripts.run_benchmark

# 工程 Harness 验证
python -m app.evaluation.harness.runner --suite all --output data/harness/latest.json

# 查看 MCP 能力
python -m app.mcp.server --list

评测体系基于人工构造、人工标注且贴近校园心理求助语料的代表性金标集。我们不筛选样本、不为追求满分而人为凑 100%，允许并保留非满分的真实通过率，用以暴露真实代码与能力边界。

QLoRA 训练侧证据：模型配置、八门槛验收记录与数据来源声明见 docs/training/（训练证据摘要层；权重与数据本体在隔离训练仓，不入本仓库）。

核心文档

• 架构说明
• 安全设计
• 咨询工作台使用手册（教师版）
• 前端学习指南
• QLoRA 微调参数与操作手册
• QLoRA 生产化改进路线
• 改进记录索引（历轮变更 + 指南修订台账 + 审阅档案）
• 演示脚本
• 逐文件学习指南

按「实现难度 × 实现意义」整理的演进清单。带 ✅ 的已在本仓库落地。

• ✅ 风险评估双通道：规则关键词 ∪ QLoRA / 通用 LLM 二次评估，任一判高危即高危，规则兜底
• ✅ 真实 QLoRA 验收：v9 冻结 stress 87 条八门槛全过，FPR 0、medium 召回 0.88、第三人称 0.82
• 危机转介资源可配置化：学校心理中心 / 紧急联系方式从硬编码改为按校配置、管理端可编辑（低难度）
• 对话数据字段级加密存储（中难度）
• 账号安全补齐：登录失败锁定、密码强度策略、会话撤销列表（低难度）
• 用户数据导出与删除（低难度）

• ✅ Function Calling 真接入：GLM 自主选择回复技能，规则白名单兜底
• ✅ 三运行时 A/B 评测：langgraph / autonomous / ordered 同数据集对比延迟 / trace / LLM 调用数
• ✅ LLM-as-Judge：模型为回复打共情性 / 安全性 / 结构性分数，进入评测报告
• ✅ LangGraph Checkpoint：SqliteSaver 持久化，长对话跨进程可恢复
• ✅ 记忆系统分层增强：L2 用户结构化事实（有效期截断 / 冲突消解）、L3 会话摘要、L4 最近原话窗口已接入三运行时 Prompt
• ✅ Skill 自动蒸馏闭环：默认第 3 次命中后生成并重载 skills/auto/ Skill，自动 Skill 不再次计数以避免递归膨胀
• 记忆系统进一步升级：结构化用户画像 / 情绪轨迹、历史会话向量检索、L1/L2 协同检索、L2 事实审计与纠错工作台（高难度）
• 自动 Skill 审核工作台：查看生成内容、审批启用 / 拒绝 / 回滚并记录审计（中难度）
• 主动关怀闭环：高危用户 N 天未跟进自动生成提醒任务（复用工具队列）（中难度）
• 词表外置：路由 / 技能触发关键词从代码抽到 YAML（低难度）

• CI/CD：GitHub Actions 跑 pytest + node check + harness（低难度）
• Alembic 迁移：消灭手写 DDL 与 ORM 的两份 schema 真相（中难度）
• request_id 贯通结构化日志（低难度）
• Prometheus 指标 + Grafana 面板（中难度）
• Docker Compose 全链路实测（待有 Docker 环境）

• 心理量表接入（PHQ-9 / GAD-7）：定期测评 → 分数趋势 → 与风险阈值联动（中难度）
• 群体心理态势仪表盘：全校风险分布 / 话题热度（中难度）
• 教师与管理员权限细分（低难度）
• 企业微信 / 钉钉 webhook 告警通道（低难度）

欢迎提交 Issue 与 Pull Request。为保障主分支质量与评测可信度，请先阅读以下约定。

# 1. Fork 本仓库后克隆到本地
git clone https://github.com/<你的用户名>/aegis-psych-agent.git
cd aegis-psych-agent

# 2. 新建分支（勿直接向 main 提交）
git checkout -b feat/<简短描述>     # 新功能
git checkout -b fix/<简短描述>      # 缺陷修复
git checkout -b docs/<简短描述>     # 文档更新

# 3. 开发并提交（遵循下方 commit 规范）
git add .
git commit -m "feat: 新增 XXX 能力"

# 4. 推送并创建 Pull Request
git push origin feat/<简短描述>

请在发起 PR 前确保以下条件全部满足：

• python -m pytest tests -q 全部通过
• 修改前端后执行 cd frontend && npm run lint && npm run build（dist/ 为 FastAPI 同源托管的产物，必须一起提交）
• 新增配置项已同步写入 .env.example 与本 README 的 配置说明 表格
• 新增依赖已写入 requirements.txt
• 未向仓库提交任何 AEGIS_TRAINING_ROOT 下的训练产物（脚本、数据、adapter、merged 模型、GGUF、报告）
• 未提交 .env、data/ 下的本地数据与密钥文件

采用 Conventional Commits 前缀，示例：

1. 禁止为提升指标而修改金标样本。eval/fixtures/ 下的数据集视为不可随意变更的基准，任何调整需在 PR 中说明理由，并同步更新本文档的指标口径说明。
2. 允许非满分的真实通过率。评测的目的是暴露边界，不是展示满分。
3. 引用指标必须注明口径与日期，不得将不同轮次、不同开关配置下的数字混用。
4. 新增能力建议同步补充对应的评测用例或 harness suite。

• 新增 Agent：在 app/agents/ 实现并在 runtime factory 注册，确保三档运行时（autonomous / langgraph / ordered）均可调用
• 新增工具：必须在 app/tools/contracts.py 声明契约（角色、风险等级、审批要求、脱敏字段、最大重试次数），禁止绕过 ToolJob 直连执行
• 新增记忆层：遵循 L1~L4 分层职责，避免将事实抽取逻辑散落到单个 Agent 内部
• 涉及风险判定：必须保证规则通道兜底始终有效，任何模型通道失败都应安全降级

提交 Issue 时请包含：复现步骤、运行环境（OS / Python 版本 / AI_PROVIDER 与 AGENT_RUNTIME 取值）、相关日志或 trace。涉及安全问题的 Issue 请避免公开披露具体学生数据。

本项目基于 MIT License 开源发布，版权归 shangguanyunji663 所有（Copyright (c) 2026）。

MIT 许可允许在保留版权声明的前提下自由使用、复制、修改、合并、发布、分发、再许可与销售本软件，但本软件「按原样」提供，不含任何明示或暗示的担保。

附加条款（请一并遵守）

本项目为心理支持场景的工程学习与系统展示项目，不提供医学诊断，不能替代专业心理咨询或危机干预服务。 未经专业评估，不建议将其直接用于真实生产心理咨询服务。 评测数据与指标反映测试集表现，不等同于临床有效性评估。

在二次分发或部署时，请确保使用者同样知悉上述声明。