# 🎓 ADE — Academic Decision Engine

> **确定性 · 可解释 · 可重放的学业决策引擎**
> 从「我觉得能毕业」到「证据链证明你能毕业」

[![Release](https://img.shields.io/badge/Release-v1.0.0--rc1-blue)](https://github.com/S4saK1/GDMU-MCP-Server/releases/tag/v1.0.0-rc1)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-green.svg)](https://www.python.org/)
[![CI: ADE Release](https://github.com/S4saK1/GDMU-MCP-Server/actions/workflows/ade-release.yml/badge.svg)](https://github.com/S4saK1/GDMU-MCP-Server/actions/workflows/ade-release.yml)
[![CI: Tests](https://github.com/S4saK1/GDMU-MCP-Server/actions/workflows/pytest.yml/badge.svg)](https://github.com/S4saK1/GDMU-MCP-Server/actions/workflows/pytest.yml)

本仓库由两层组件组成：

| 组件 | 说明 |
| --- | --- |
| [`academic_copilot/`](academic_copilot/) | **学业知识库与决策内核**：10 个专业培养方案数据集（2025）、学生数据源（导入 / GDMU 实时 / 演示）、毕业判定、补修规划、学业时间线、快照历史、WebUI |
| [`academic-copilot-framework/`](academic-copilot-framework/) | **ADE 确定性学业决策引擎**：培养方案编译器、规则引擎、审计快照、Matcher、Copilot、Planner、Simulation |

同时保留 [正方 V-9.0 教务系统 MCP 桥](#mcp-桥正方-v-90-教务系统)（`gdmu_mcp/` + `server.py`），让 AI 客户端直接查询课表、成绩、考试与选课。

---

## ✨ 亮点

| | 能力 | 说明 |
|---|---|---|
| 🎯 | **确定性** | 同输入必同输出；Replay Hash 与审计快照字节级可复现（ADR-0026） |
| 🔍 | **可解释** | 五层证据链：`Rule → Requirement → Matched Course → Evidence → Decision` |
| 🔁 | **可重放** | `ReplayEngine` 回答「为什么去年没毕业、今年毕业？」 |
| 🧩 | **Academic Matcher** | 课程本体（别名/等价/替代/依赖）驱动的课程解析，Rule Accuracy 95% |
| 🗺️ | **多专业** | 知识库：10 个专业培养方案数据集（2 official + 8 imported，来源如实标注）；ADE 基准：5 专业 / 50 CANONICAL / 500 合成成绩单 |
| 🤖 | **Copilot** | 自然语言 → 结构化意图 → 带证据的回答（计算路径无 LLM） |
| 🧭 | **Planner + What-if** | 补修计划生成与「删一门课会怎样」模拟 |
| 🚀 | **Release 工程** | `ade doctor` 健康检查、CI 流水线、Windows 安装器脚手架 |

---

## 🏗 架构总览

```mermaid
flowchart TD
    A[CLI / REST / MCP / SDK / Playground] --> B[AcademicCopilotFacade]
    B --> C[Copilot: 意图识别]
    B --> D[Planner + What-if]
    C --> E[DecisionContext + RuleEngine]
    D --> E
    E --> F[AuditSnapshot + 五层证据链]
    F --> G[Repository 层]
    G --> H[Knowledge / Rule / Ontology]
    H --> I[Compiler: PDF → AST → IR → plan JSON]
```

完整架构见 [Architecture Handbook](academic-copilot-framework/docs/architecture/01-overview.md) 与 [6 张架构图](academic-copilot-framework/docs/diagrams/architecture.svg)。

---

## 📦 10 个专业知识数据集（2025）

`academic_copilot/data/knowledge/` 收录 10 个专业的培养方案数据集，每个专业包含
`major.json`（专业元数据）/ `courses.json`（课程）/ `graduation.json`（毕业要求）：

| 专业代码 | 专业 | 学院 | 学制 | 总学分 | source_type |
| --- | --- | --- | --- | --- | --- |
| 050201 | 英语 | 外国语学院 | 4 年 | 124.0 | `official` |
| 101101 | 护理学 | 护理学院 | 4 年 | 185.0 | `official` |
| 100201 | 临床医学 | 第一临床医学院 | 5 年 | 230.0 | `imported` |
| 100701 | 药学 | 药学院 | 4 年 | 170.0 | `imported` |
| 080910T | 数据科学与大数据技术 | 信息工程学院 | 4 年 | 165.0 | `imported` |
| 082601 | 生物医学工程 | 生物医学工程学院 | 4 年 | 168.0 | `imported` |
| 101001 | 医学检验技术 | 医学技术学院 | 4 年 | 172.0 | `imported` |
| 101003 | 医学影像技术 | 医学技术学院 | 4 年 | 170.0 | `imported` |
| 101011T | 智能医学工程 | 生物医学工程学院 | 4 年 | 170.0 | `imported` |
| 120102 | 信息管理与信息系统 | 信息工程学院 | 4 年 | 160.0 | `imported` |

**来源标注约定**（[major.schema.json](academic_copilot/data/schema/major.schema.json)）：

- `official` = 真实来源整理 —— 来自仓库内培养方案文件（英语 `english_2023.json` / 护理学 `护理学_2023_v1.json`），`source_note` 注明来源文件与源方案年级；
- `imported` = 公开资料整理导入 —— **未与官方培养方案文档逐门核验，不构成任何官方依据**。

> 数据仅用于学业分析与研究；正式毕业判定以学校教务处出具的文件为准。

---

## 🚀 5 分钟快速开始

```bash
cd academic-copilot-framework/packages/ade

# 1. 构建知识库（5 个专业）
python -m compiler.cli knowledge build --verify

# 2. 健康检查（版本 / Hash / 知识库 / 规则 / Ontology / Benchmark / Replay）
python -m compiler.cli doctor
```

然后跑真实示例：

```bash
cd academic-copilot-framework/examples
python 01_basic_status.py     # Student → Audit → Response
python 02_risk.py             # 毕业风险评估
python 03_plan.py             # 补修计划
python 04_what_if.py          # 补修课程 → 重新判定
```

浏览器打开：

- [Playground](academic-copilot-framework/playground/index.html) — 交互式成绩单 / 判定 / 证据
- [Benchmark Dashboard](academic-copilot-framework/benchmark/index.html) — 指标可视化

> Demo 学生 Alice / Bob / Charlie 已在 `demo/students/`，无需导数据。

---

### 根模块：10 专业知识库 + WebUI

```bash
# 1. WebUI（Dashboard API + 静态资源，零新增 Python 依赖，默认 127.0.0.1:8787）
python -m academic_copilot.webui.server

# 2. 统一 MCP 入口（19 个教务数据工具 + 3 个 academic.* 决策工具）
python kernel_server.py

# 3. 前端（独立开发模式）
cd frontend && npm install && npm run dev
```

> WebUI 演示截图：[桌面端概览](docs/screenshots/webui-dashboard-desktop.png) · [移动端课程](docs/screenshots/webui-mobile-courses.png) · [WebUI 冒烟](docs/screenshots/webui-smoke.png)

> 教务实时采集（`server.py`）需要 `gdmu-agent` 运行时与本人账号会话，见下方[数据来源声明](#数据来源声明)。

---

## 📊 Benchmark

| 指标 | 数值 |
|---|---|
| Rule Accuracy（护理学，10 CANONICAL） | **95%** |
| Overall Accuracy | 80% |
| Matcher Accuracy | 100% |
| Alias / Equivalent Match Rate | 100% |
| Unmatched Courses | 0 |
| 专业 / CANONICAL / 合成成绩单 | 5 / 50 / 500 |
| 性能（10,000 学生） | 判定 4.6s · 审计 5.9s · 峰值内存 2.6MB |

详细数据：[multi_major_benchmark.md](academic-copilot-framework/validation/benchmarks/multi_major_benchmark.md) · [performance.md](academic-copilot-framework/validation/benchmarks/performance.md) · [Release Notes](academic-copilot-framework/RELEASE_NOTES_v1.0.0-rc1.md)

---

## 📚 文档

| 文档 | 位置 |
|---|---|
| 架构手册（10 篇） | [docs/architecture](academic-copilot-framework/docs/architecture) |
| API 参考（OpenAPI + 6 模块） | [docs/api](academic-copilot-framework/docs/api) |
| ADR 索引（31 条架构决策） | [docs/adr/README.md](academic-copilot-framework/docs/adr/README.md) |
| 快速开始 / FAQ / 贡献指南 | [docs/](academic-copilot-framework/docs) |
| 学术论文（Markdown + PDF） | [paper/ADE.pdf](academic-copilot-framework/paper/ADE.pdf) |
| 安全策略 / 行为准则 / 引用格式 | SECURITY · CODE_OF_CONDUCT · CITATION.cff |

---

## 🗂 仓库结构

```text
.
├── academic_copilot/             # 学业知识库与决策内核
│   ├── data/knowledge/           #   10 专业培养方案数据集（2025）
│   ├── knowledge_*/              #   知识库：数据集 / 注册 / 审计 / 发布 / 门控
│   ├── student_source/           #   学生数据源：导入 / GDMU 实时 / 演示
│   ├── student_profile/          #   学生画像（脱敏）
│   ├── curriculum/               #   课程解析与学分核算
│   ├── planning/ timeline/       #   补修规划 / 学业时间线
│   ├── snapshot_history/         #   快照历史与差异
│   └── webui/                    #   WebUI 服务端（127.0.0.1:8787）
├── frontend/                     # WebUI 前端（原生 JS + Vite + Vitest）
├── gdmu_mcp/ server.py           # 正方教务 MCP 桥
├── kernel_server.py              # 统一 MCP 入口（数据工具 + academic.* 工具）
├── scripts/                      # 数据集生成 / 审计 / 导出脚本
├── academic-copilot-framework/   # ADE 学业决策引擎
│   ├── packages/ade/             #   核心：compiler/knowledge/rule/decision/
│   │                             #         audit/matcher/copilot/planner/simulation
│   ├── validation/               #   验证工作区：golden cases + benchmark
│   ├── docs/                     #   架构 / API / ADR / 图
│   ├── examples/                 #   8 个可运行示例
│   ├── demo/                     #   开箱即用的演示学生
│   ├── playground/               #   交互式 Playground
│   ├── benchmark/                #   Benchmark 可视化
│   ├── plugins/                  #   插件 SDK（Notification/Rule/Planner/Matcher）
│   ├── installer/                #   Windows 安装器脚手架
│   └── paper/                    #   学术论文
└── docs/                         # 架构 / 数据源 / 知识治理文档
```

---

## 🧪 测试

```bash
python -m pytest tests -q                                  # 根模块测试
cd academic_copilot && python -m pytest tests -q           # 内核 / 知识库测试
cd frontend && npm test                                    # 前端测试（Vitest）
cd academic-copilot-framework/packages/ade && python -m pytest tests -q   # 426 tests
cd academic-copilot-framework/validation && python -m pytest tests -q     # 241 tests
```

CI 流水线（[ade-release.yml](.github/workflows/ade-release.yml)）：`push → Compile → Build → Validation → Ruff → Benchmark → Doctor → Docker → Release`

---

## 🔌 MCP 桥（正方 V-9.0 教务系统）

面向 Codex / Claude Desktop / Cursor 等 AI 客户端的 MCP 桥，覆盖课表、成绩、考试、选课、毕业规划全场景（19 个工具，专为 CAS 单点登录 + MFA 设计）。配置与工具清单见仓库根 `config.example.env` 与 [docs](docs/architecture-design.md)。

---

## 🤝 贡献

欢迎贡献！请先阅读 [CONTRIBUTING](academic-copilot-framework/docs/CONTRIBUTING.md) 与 [ADR 索引](academic-copilot-framework/docs/adr/README.md)，保持核心管线确定性与 Repository 边界。

## 📜 数据来源声明

- **培养方案数据**：`academic_copilot/data/knowledge/` 10 个专业中，`official`（英语 / 护理学）来自仓库内真实培养方案文件（官方 PDF 编译 IR，`source_note` 注明来源文件）；`imported`（其余 8 个）来自公开资料整理导入，**未与官方培养方案文档逐门核验，不构成任何官方依据**。
- **演示学生数据**：全部为合成数据或已掩码（学号 `2321****`、姓名 `测试学生`），不含真实身份证号 / 手机号 / 未掩码学号。
- **会话数据**：教务登录会话（`jw_session.json`）仅存本机，已被 `.gitignore` 排除，永不入库、不写入审计快照。
- **ADE 训练数据**：`academic-copilot-framework/packages/ade/data/source/` 收录官方公开培养方案 PDF 用于编译验证，仅供学习研究。

详细口径见 [DISCLAIMER.md](DISCLAIMER.md)、[STUDENT_DATA_SOURCE.md](docs/STUDENT_DATA_SOURCE.md)、[GDMU_STUDENT_DATA_SOURCE.md](docs/GDMU_STUDENT_DATA_SOURCE.md)。

## ⚖️ 免责声明

> 本工具面向**个人学业数据分析与研究**场景设计。

- **仅限本人账号使用**：禁止用于分析他人数据、批量采集或任何未经授权的访问。
- **仅限学习与研究用途**：使用者须遵守所在高校的学生管理规定与相关法律法规。
- **不构成毕业建议**：分析结果仅供辅助参考，正式毕业判定以学校教务处出具的文件为准。
- **功能边界**：本仓库不含自动化选课/抢课功能，也不鼓励将其扩展用于干扰教务系统正常运行。
- **作者不承担他人滥用责任**：使用者对自身行为负全部责任。

完整条款见 [DISCLAIMER.md](DISCLAIMER.md)。使用本工具即表示你已阅读、理解并同意上述条款。

## 📄 许可

[MIT](LICENSE)

> 引用本项目请使用 [CITATION.cff](academic-copilot-framework/CITATION.cff)。