AICompass

切换主题

贡献指南 ​

欢迎您！AICompass 是一个由中山大学人工智能学院学生会发起，由学院同学共同建设的开放性学习平台，旨在分享课程资源、学习经验，互相帮助。

建设方向和目标 ​

课程方面：

  • 为学院的每一门课程进行详细的介绍，包括课程风格、内容，课程重要性、之后的应用，和在整个知识体系的地位
  • 为每一门课整理一份学习资源列表（如优质网课、博客等），帮助之后的同学更好、更快的学会这门课程
  • 为每一门课整理一份应试指南，包括可公开的历年真题、复习笔记、复习策略、应试技巧、考试难度等等
  • 为每一门课提供有价值的拓展方向，帮助衔接课内和应用，或者提供可深度探索的学习方向

经验方面

  • 希望能够汇集科研入门（包括入门资源、方向介绍、课题组介绍等）、保研经验/资源、考研经验/资源、实习&就业经验等涉及大学学习和升学的方方面面。

本项目完全开源、工程浩大，需要朋友们一同参与、共同建设，欢迎学院的各位同学加入到这个项目的建设中来，实现互相帮助，将自己踩过的坑、深受帮助的好资源分享给之后的朋友。

贡献方式 ​

方式一：网站提交（推荐） ​

访问 提交贡献 页面，选择课程、上传文件（课件/笔记/试卷等）、可选撰写课程说明，提交后系统会自动创建 GitHub PR。您可以在 PR 中继续编辑，将文件链接和内容加到课程页面中。

上传的文件会存储在阿里云 OSS 上，不占用 Git 仓库空间。

方式二：GitHub PR（进阶） ​

熟悉 Git 的同学可以通过传统的 Fork → 编辑 → Pull Request 流程贡献。下文有详细的步骤教学。

如果您不熟悉 Git，也可以将内容整理好后发送邮件至 cuikq@mail2.sysu.edu.cn，维护者会帮助您添加到项目中。

第一步：配置本地开发环境 ​

为了在提交前预览您的修改效果，我们强烈建议您在本地计算机上运行本项目。

步骤 1：准备工作 ​

在开始之前，请确保您的电脑已经安装了以下软件：

  • Git: 一个版本控制系统，用于下载和管理项目代码。
  • Node.js: 本项目基于 Node.js 构建。请确保您的 Node.js 版本在 18 或以上（推荐 20+）。

步骤 2：克隆项目仓库 ​

首先，您需要将本项目的代码仓库（Repository）复制一份到您自己的 GitHub 账号下，这个过程叫做 Fork。

  1. 访问 AICompass GitHub 仓库主页。
  2. 点击页面右上角的 Fork 按钮。

完成后，在您自己的 GitHub 主页下就会出现一个名为 AICompass 的仓库。接下来，使用 Git 将这个仓库克隆到您的本地电脑上。

bash
# 将下面的 "Your-GitHub-Username" 替换为您的 GitHub 用户名
git clone https://github.com/Your-GitHub-Username/AICompass.git

# 进入项目目录
cd AICompass

步骤 3：安装项目依赖 ​

本项目使用 npm（Node.js 包管理器）管理依赖。执行以下命令来安装它们：

bash
npm install

步骤 4：在本地运行网站 ​

一切就绪！现在，启动 VitePress 的开发服务器：

bash
npm run dev

您会看到类似下面的输出：

  vitepress v1.6.4

  ➜  Local:   localhost:5173/
  ➜  Network: use --host to expose

现在，打开您的浏览器，访问终端显示的本地地址（通常是 localhost:5173），您就可以看到和线上完全一样的网站了！并且，当您修改并保存文件时，网页会自动刷新（热更新），非常方便。

第二部分：如何添加或修改内容 ​

添加一门新的课程页面 ​

假设您想为“大三下学期”添加一门名为《深度学习》的新课程，请遵循以下步骤：

1. 创建 Markdown 文件

  • 在 docs/ 目录下，找到对应的学期文件夹。对于“大三下学期”，对应的文件夹为 ThirdYear_2 。
  • 在该文件夹下，创建一个新的 Markdown 文件，例如 DeepLearning.md。

2. 编写课程内容

打开 DeepLearning.md 文件，您可以参考项目中的 model.md 模板或其他已有的课程页面来组织内容。一个典型的课程页面结构如下：

markdown
# 深度学习

## 如何认识这门课
这部分可以介绍课程的重要性、主要内容和学习这门课的价值。以及这门课在之后课程的应用

## 优质学习资源
- [优质课程视频](链接)
- [推荐阅读的书籍或文章](链接)

## 复习资料及应试策略
- [往年试题（通过WPS云文档分享）](WPS链接)
- 复习建议和重点。
- [希望分享的笔记](链接) 

## 拓展资料
一些相关的进阶内容、课程，相应的科研方向，或有趣的应用。

3. 更新网站导航栏

为了让用户能在网站的侧边栏导航中找到您新添加的页面，您需要修改 .vitepress/config.mts 文件。

  • 打开 .vitepress/config.mts 文件。
  • 找到 sidebar: 配置部分。
  • 在对应的学期列表下，添加新的一行。

修改前：

typescript
'/ThirdYear_2/': [
  {
    text: '大三下学期',
    collapsed: false,
    items: [
      { text: '智能机器人', link: '/ThirdYear_2/Robotics' },
    ]
  }
],

修改后：

typescript
'/ThirdYear_2/': [
  {
    text: '大三下学期',
    collapsed: false,
    items: [
      { text: '智能机器人', link: '/ThirdYear_2/Robotics' },
      { text: '深度学习', link: '/ThirdYear_2/DeepLearning' }, // 新增此行
    ]
  }
],

注意：text: '深度学习' 是显示在侧边栏上的名称，link: '/ThirdYear_2/DeepLearning' 是文件的实际路径（省略 .md 后缀）。

保存 .vitepress/config.mts 文件后，本地开发服务器会自动重新构建网站。刷新您的浏览器，就能在侧边栏看到新的课程链接了！

如何分享文件 ​

为了保持项目仓库的轻量化，请不要直接将试题、笔记、教材等大文件（如 PDF, ZIP，大于 1MB）上传到 Git 仓库中。

方式一：通过贡献表单上传（推荐） ​

在 提交贡献 页面直接拖拽上传文件，文件会存储在阿里云 OSS 上并自动生成链接，无需手动处理。上传后链接会出现在自动创建的 PR 中，您可以将其复制到课程页面的相应位置。

第三部分：提交您的贡献 ​

当您在本地完成修改并确认无误后，就可以将您的贡献提交到主仓库了。

  1. 提交代码到您的 Fork

    bash
    # 查看您的修改状态
git status

# 添加您修改过的所有文件
git add .

# 创建一个有意义的提交信息
git commit -m "feat: Add Deep Learning course to ThirdYear_2"

# 推送到您在 GitHub 上的仓库
git push

  2. 创建 Pull Request (PR)

    • 回到您在 GitHub 上的 AICompass 仓库页面。
    • 您会看到一个黄色的提示条，提示您“This branch is 1 commit ahead of SYSU-SAIA:main.”。
    • 点击右侧的 “Contribute” -> “Open pull request” 按钮。
    • 在新的页面，为您的 PR 添加一个清晰的标题和描述，说明您做了哪些修改。
    • 点击 “Create pull request”。

完成以上步骤后，项目维护者会收到通知。他们会对您的提交进行审核（Code Review），如果没有问题，就会将其合并（Merge）到主项目中。您的贡献就正式成为 AICompass 的一部分了！

再次感谢您的贡献和支持，如果您有兴趣加入到网站的维护当中来，或对网站的构建思路和发展方式有更好的提议，欢迎发送邮件到cuikq@mail2.sysu.edu.cn

中山大学人工智能学院 · 学生共建

AICompass 团队