学业航线

Graduation Planner

面向大学生的本地优先学业规划工具
把培养方案、成绩单、课程进度与学期计划整理成一条清晰的学业路径

产品速览 · 核心功能 · 快速开始 · 使用方式 · 接入 AI · 数据与隐私

Important

学业航线是学生个人规划工具，不是学校官方教务系统。AI 识别、课程匹配、成绩计算与毕业进度均需由用户依据本校最新文件人工核对。

为什么做这个项目

培养方案、成绩单和学期安排通常分散在不同文件中，学生需要反复查表，才能回答几个看似简单的问题：已经完成多少学分、还有哪些类别未完成、下学期应当安排什么课程，以及推免材料中的核心课成绩应如何计算。

学业航线把这些信息放进同一个由学生自己维护的工作区：AI 可以协助提取文件内容，但不会替用户作出最终判断；确认后的数据保存在当前浏览器中，并可随时导出备份。

产品速览

进度看板

集中展示总学分、课程状态与各课程类别完成情况，帮助学生快速了解当前进度和剩余学分。

课程管理

课程列表与课程类别保持同步，支持搜索、筛选、修改课程状态，以及维护学分和所属类别。

推免综测

从成绩单中选择核心课程，按 GPA 或百分制口径计算核心课成绩，并继续维护综测指标与权重。

核心功能

栏目	主要能力
进度看板	汇总已通过、在修、已规划与未修学分，展示各课程类别完成情况
课程管理	维护课程列表和课程类别，导入并核对培养方案与成绩单
学期规划	为计划修读课程指定学期，统计单学期总学分并提示负担
推免综测	选择核心课程，按 GPA 或百分制加权平均计算成绩；自定义综测指标与权重
AI 与数据	连接模型供应商，导出或恢复本地备份，管理本地数据

培养方案与成绩单

支持文字型 PDF 和 DOCX；扫描型文件的识别结果可能不完整
培养方案解析结果分为课程类别与具体课程两步确认
成绩单课程可严格匹配培养方案课程，也可由用户选择计入方式
AI 返回内容经过运行时结构校验，校验失败时不会直接写入本地数据
所有解析与匹配结果都保留人工确认入口

课程进度与学期规划

总学分进度与课程类别进度使用同一份课程数据
课程状态包括已通过、在修、计划修读、未修和未通过
计划修读课程必须指定学期
学期规划只判断每学期计划课程与总学分，并依据用户设置的提醒线提示负担

推免核心课与综测计算

可从成绩单提取课程名称、类别、学分、最终成绩和学分绩点
由用户勾选哪些课程计入核心课成绩
支持平均学分绩点 GPA 和百分制加权平均两种口径
等级制或合格制课程需要人工换算或二次确认后才能计入
综测指标名称、分数、权重和数量均可维护，权重合计必须为 100%

推免规则因学校、学院、专业和年份而异。本功能只提供计算与记录能力，不判断用户是否具备推免资格。

快速开始

下面的步骤会在你的电脑上运行学业航线。所有学业数据默认保存在当前浏览器中，不需要注册账号，也不需要部署服务器。

0. 最便利：利用 Agent

如果你正在使用 Codex 等具备终端和文件操作能力的智能体，可以直接把项目链接发给它：

https://github.com/ZzengYang/student-progress-planner

然后说明：“请把这个项目部署到我的电脑本地，安装依赖并启动，完成后告诉我访问地址。”Agent 可以协助下载仓库、检查环境、安装依赖并运行项目；遇到命令执行或文件访问确认时，请核对内容后再授权，不要向智能体发送 API Key 等敏感信息。

1. 准备运行环境

请先安装：

Node.js 20.9 或更高版本，建议使用当前长期支持版
Git，用于下载和更新项目
Corepack，Node.js 自带的包管理器调度工具；它会按项目配置使用 pnpm 10.28.0

安装 Node.js 和 Git 后，重新打开终端并检查版本：

node --version
git --version

检查 Corepack，并让它调用项目指定的 pnpm：

corepack --version
corepack pnpm --version

本教程后续统一使用 corepack pnpm ...。这种写法不要求把 pnpm 单独加入系统 PATH，在 Windows 上更不容易遇到“无法将 pnpm 识别为命令”的问题。

如果系统提示无法识别 corepack，请确认安装的是 Node.js 20.9 或更高版本。也可以改为全局安装 pnpm：

npm install --global pnpm@10.28.0
pnpm --version

使用全局安装方式时，可以把后续命令中的 corepack pnpm 简写为 pnpm。安装完成后若仍无法识别命令，请关闭当前终端，重新打开后再试。

2. 下载项目

推荐使用 Git：

git clone https://github.com/ZzengYang/student-progress-planner.git
cd student-progress-planner

如果不想使用 Git，也可以在 GitHub 项目页点击 Code → Download ZIP，解压文件后，在终端中进入解压得到的 student-progress-planner 文件夹。

Windows PowerShell 示例：

cd "C:\你的文件夹\student-progress-planner"

macOS / Linux 示例：

cd "/你的文件夹/student-progress-planner"

3. 安装项目依赖

确认终端当前位于项目根目录，其中应当能看到 package.json 和 pnpm-lock.yaml，然后运行：

corepack pnpm install --frozen-lockfile

首次安装需要下载依赖，耗时取决于网络状况。命令正常结束且没有红色错误信息，即表示安装完成。

4. 创建本地配置

Windows PowerShell：

Copy-Item .env.example .env.local

macOS / Linux：

cp .env.example .env.local

默认配置可以直接用于本地体验，不需要把 API Key 写入 .env.local。启动应用后，可以在「AI 与数据」页面临时连接自己的模型服务。

5. 启动应用

corepack pnpm dev

终端出现启动成功提示后，使用浏览器打开：

http://localhost:3000

如果 3000 端口已被占用，Next.js 可能会自动改用其他端口，请以终端显示的地址为准。运行期间不要关闭终端窗口。

6. 完成首次设置

首次打开应用后：

填写学校、年级、修读专业和培养方案总学分
如需 AI 解析文件，进入「AI 与数据」，选择供应商并填写自己的 API Key
进入「课程管理 → 文件导入」，上传培养方案并逐项确认解析结果
再上传成绩单，将已修课程匹配到培养方案
前往进度看板检查总学分与分类进度，并在课程列表中修正课程状态
根据需要使用学期规划或推免综测功能

不想立刻导入自己的文件时，也可以先选择体验示例方案，熟悉界面后再退出示例。

7. 停止和再次启动

在运行应用的终端中按 Ctrl + C 可以停止服务。以后再次使用时，只需进入项目目录并运行：

corepack pnpm dev

浏览器中的本地数据通常会继续保留，但仍建议在「AI 与数据」中定期导出 JSON 备份。清除浏览器站点数据、更换浏览器或更换访问地址可能导致原数据不可见。

8. 更新到最新版本

通过 Git 下载项目的用户，可以在项目目录运行：

git pull
corepack pnpm install --frozen-lockfile
corepack pnpm dev

使用 ZIP 下载的用户需要重新下载并解压最新版本。更新前建议先在应用中导出 JSON 备份。

使用方式

填写学校、年级和修读专业等基本信息
连接 OpenAI、DeepSeek 或 Kimi，使用自己的 API Key
上传培养方案，由 AI 提取课程类别、学分要求和具体课程
在写入前逐项确认，也可以手动新增、删除或修正信息
上传成绩单，将已修课程匹配到培养方案并确认课程状态
在进度看板、课程管理和学期规划中持续维护自己的学业路径

推免综测使用独立的成绩单数据，不会改动毕业进度与课程管理中的数据。

接入 AI

学业航线通过用户自己的模型 API Key 解析培养方案和成绩单。项目不会赠送模型额度，也不会要求把 API Key 写入代码或环境变量。

支持的模型供应商

供应商	默认模型	API Key 来源
OpenAI	`gpt-4.1-mini`	OpenAI Platform
DeepSeek	`deepseek-chat`	DeepSeek 开放平台
Kimi	`kimi-k3`	Kimi API 开放平台

默认模型会在切换供应商时自动填写；如果供应商调整了模型名称，也可以在页面中手动修改。API 服务通常需要单独开通或充值，网页端会员不一定包含 API 调用额度，具体规则以各供应商平台为准。

连接步骤

在所选模型供应商的开放平台创建 API Key
本地启动学业航线，进入左侧的「AI 与数据」页面
选择模型供应商
粘贴 API Key，并确认模型名称
点击「测试并连接」
显示连接成功后，进入「课程管理 → 文件导入」上传培养方案或成绩单
在解析结果对话框中逐项核对，确认后再写入本地数据

密钥与数据如何处理

API Key 只保存在当前浏览器标签页对应的会话存储中
关闭浏览器会话后通常需要重新连接
API Key 不会写入 IndexedDB、JSON 备份或应用日志
上传文件会先在本地部署的 Next.js 服务端提取文字
只有解析所需的文本、模型设置和 API Key 会发送给所选供应商
原始文件不会保存到学业航线的本地数据库

常见问题

连接测试失败

检查 API Key 是否有效、账户是否有可用额度、模型名称是否存在，以及当前网络能否访问供应商的 API 地址。

连接成功但文件解析失败

确认文件是受支持的 PDF 或 DOCX，并优先使用包含可选中文字的文件。扫描型 PDF 可能无法提取完整内容。

为什么每次重新打开都要填写 API Key

这是有意的隐私设计。密钥仅保存在当前浏览器会话，不随学业数据长期保存，也不会进入备份文件。

Warning

不要把 API Key 提交到 Git、截图、Issue 或 Pull Request。若密钥意外泄露，请立即前往对应供应商平台撤销并重新创建。

设计原则

只服务学生个人：不提供校方管理后台、审核流或学生排名
本地优先：确认后的学业数据默认保存在当前站点对应的浏览器 IndexedDB 中
AI 建议、人工决定：AI 只负责辅助提取，任何结果都应在写入前核对
自带密钥：用户可以自行选择模型供应商并使用自己的 API Key
模块相互隔离：毕业进度与推免计算分别保存，避免互相覆盖
可备份恢复：支持导出 JSON，并在导入时校验数据结构与版本

数据与隐私

培养方案、课程状态、学期规划和推免计算数据保存在当前浏览器的 IndexedDB 中
原始上传文件不会写入应用数据库或 JSON 备份
使用 AI 解析时，服务端会提取文件文字，并将必要文本和用户提供的 API Key 转发至所选模型供应商
API Key 只保存在当前浏览器会话，不写入 IndexedDB、备份文件或应用日志
清除站点数据、使用无痕模式、更换域名或更换设备，都可能使原有数据不可见
应用更新不会主动清空本地数据；数据结构升级通过版本迁移处理，无法安全迁移时会暂停自动保存以避免覆盖

请定期导出备份。完整说明见 PRIVACY.md。

技术结构

浏览器
├─ Next.js / React 用户界面
├─ IndexedDB 本地数据
└─ Session Storage 中的临时 API Key
        │
        ▼
Next.js 服务端接口
├─ 文件大小、来源与频率限制
├─ PDF / DOCX 文字提取
├─ AI 请求转发
└─ AI 返回结构校验
        │
        ▼
用户选择的模型供应商

主要技术：Next.js 16、React 19、TypeScript、Zod、IndexedDB、pdf-parse、Mammoth 和 Vitest。

开发与验证

pnpm dev
pnpm typecheck
pnpm test
pnpm format:check
pnpm build

项目目录：

app/          Next.js 页面与服务端接口
components/   业务界面组件
lib/          数据结构、存储、迁移、解析校验与计算逻辑
public/       静态资源
.github/      CI、Dependabot 与协作模板

环境变量

变量	默认值	说明
`OPENAI_API_KEY`	空	可选的服务端 OpenAI Key，仅在明确开启服务端 Key 时使用
`OPENAI_MODEL`	`gpt-4.1-mini`	服务端 OpenAI 默认模型
`ALLOW_SERVER_AI_KEY`	`false`	是否允许解析接口使用服务端 Key；建议保持关闭并由用户在页面中填写自己的 Key
`PARSE_RATE_LIMIT`	`12`	单 IP 每小时文件解析请求数
`PARSE_KEY_RATE_LIMIT`	`30`	同一 API Key 指纹每小时解析请求数
`AI_TEST_RATE_LIMIT`	`20`	单 IP 每小时 AI 连接测试次数

参与贡献

欢迎报告问题、讨论需求和提交改进。开始前请阅读 CONTRIBUTING.md；发现安全问题时，请遵循 SECURITY.md，不要在公开 Issue 中披露敏感细节。

提交代码前至少运行：

pnpm typecheck
pnpm test
pnpm format:check
pnpm build

请勿把真实成绩单、培养方案、API Key、备份文件或其他个人数据提交到仓库、Issue 或 Pull Request。

项目状态

当前版本是面向个人使用的 MVP 测试版，尚未承诺数据格式长期兼容、在线服务持续可用或计算结果具有官方效力。欢迎通过 GitHub Issues 提交问题和建议。

开源许可

本项目采用 MIT License。你可以在许可证条款范围内使用、复制、修改和分发本项目。

Name		Name	Last commit message	Last commit date
.github		.github
app		app
components		components
docs/screenshots		docs/screenshots
lib		lib
.editorconfig		.editorconfig
.env.example		.env.example
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
PRIVACY.md		PRIVACY.md
README.md		README.md
SECURITY.md		SECURITY.md
next-env.d.ts		next-env.d.ts
next.config.ts		next.config.ts
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation