跳到主要内容

📚 Everpast-AI 协作指南

欢迎来到 Everpast-AI ！本项目使用 Git 进行版本控制，并使用 Git LFS (Large File Storage) 来管理大文件（如图片、视频、模型文件等）。

无论你使用的是 Windows 还是 macOS，习惯使用命令行、VS Code 还是 Obsidian，本指南都将帮助你顺利配置环境并丝滑地参与团队协作。

AIGC by Gemini and loong

🧠 1. 一分钟理解 Git 核心逻辑​

在开始敲命令之前，理解 Git 的“四个区域”至关重要：

  • 工作区 (Working Directory): 你当前在电脑上看到的文件夹和文件。
  • 暂存区 (Staging Area): 一个准备提交的“草稿箱”。你修改了文件后，需要先 add 到这里。
  • 本地仓库 (Local Repository): 存储在你电脑上的历史记录。你 commit 之后，文件就安全地保存在这里了。
  • 远程仓库 (Remote Repository): GitLab 上的中央服务器（也就是大家共享代码的地方）。你需要 push 才能将本地的修改同步给其他人，通过 pull 获取他人的最新修改。

🛠️ 2. 环境安装 (Git & Git LFS)​

⚠️ 极其重要：由于本项目包含大文件，团队中的每一个人在克隆（Clone）代码之前，都必须安装 Git 和 Git LFS！

Windows 用户​

  1. 安装 Git: 访问 Git for Windows 下载并一路“下一步”安装。
  2. 安装 Git LFS: 访问 Git LFS 官网 下载 Windows 安装包并运行。
  3. 激活 LFS: 打开 Git Bash 或 PowerShell，运行一次以下命令（全局生效，只需运行一次）： 
    git lfs install

macOS 用户​

  1. 安装 Homebrew (如果还没有的话): 
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  2. 安装 Git 和 Git LFS: 
    brew install git git-lfs
  3. 激活 LFS: 打开终端 (Terminal)，运行一次： 
    git lfs install

⚙️ 3. 初始配置 & 获取项目​

3.1 配置个人信息​

告诉 Git 你是谁，这样提交记录里才会显示你的名字。在终端运行：

git config --global user.name "你的真实姓名或花名"
git config --global user.email "你的工作邮箱"

3.2 克隆项目 (Clone)​

你有两种方式将远程代码下载到本地。选择其中一种即可：

推荐方式：HTTPS 克隆 (适合不想折腾密钥的新手)​

每次推送（Push）时可能需要输入 GitLab 的账号密码（大多数系统会自动记住）。

git clone https://gitlab.l.nmgjg.com.cn/everpast-AI/doc.git

进阶方式：SSH 克隆 (一劳永逸，无需频繁输密码)​

如果你在 GitLab 上看到 Your account does not have an SSH key. 的提示，说明你还没有配置密钥。

  1. 生成 SSH 密钥： 运行 ssh-keygen -t ed25519 -C "你的邮箱"，然后一路回车。
  2. 查看并复制密钥： 运行 cat ~/.ssh/id_ed25519.pub，将输出的那一大段文本复制下来。
  3. 添加到 GitLab： 登录 GitLab -> 右上角头像 -> Edit Profile -> SSH Keys -> Add new key，将复制的文本粘贴进去并保存。
  4. 测试和信任主机: 在 VS Code 中打开集成终端，在终端中手动输入 SSH 测试命令 ssh -T git@gitlab.l.nmgjg.com.cn -p 222 然后输入 yes确认
  5. 克隆项目： 
    git clone git@gitlab.l.nmgjg.com.cn:222:everpast-AI/doc.git

💻 4. 基础命令与日常工作流​

每天开始工作时，请遵循以下标准的“拉、改、存、推”工作流：

  1. 拉取最新进度 (Pull): 在开始修改文件前，先获取同事的最新提交。 
    git pull origin main
  2. 修改文件: 使用你喜欢的编辑器（VS Code, Obsidian 等）进行工作。
  3. 暂存更改 (Add): 将修改好的文件放入暂存区。 
    git add .   # 这里的点代表暂存当前目录下的所有修改
  4. 提交更改 (Commit): 给你的修改写一段简短清晰的描述。 
    git commit -m "docs: 更新了第一章的系统架构图"
  5. 推送到远程 (Push): 将你的本地记录同步到 GitLab。 
    git push origin main

🐘 5. Git LFS 操作指南 (大文件管理)​

LFS 在大部分情况下是静默运行的，只要你执行过 git lfs install，日常的 pull/push 操作会自动处理大文件。

如果你需要向项目中添加一种新的大文件格式（例如新增了 .psd 文件）：

  1. 告诉 LFS 跟踪这种文件格式： 
    git lfs track "*.psd"
  2. 非常重要： 上述命令会修改 .gitattributes 文件。你必须将这个文件也提交上去，否则别人的电脑不知道要用 LFS 处理它： 
    git add .gitattributes
    git add your-large-file.psd
    git commit -m "chore: 添加对 psd 文件的 LFS 跟踪并上传设计图"
    git push origin main

🛠️ 6. 工具链集成工作流​

如果你不想敲黑乎乎的命令行，我们推荐以下图形化界面操作：

🆚 针对 VS Code 用户​

VS Code 完美内置了 Git 支持：

  1. 打开项目： 在 VS Code 中打开 doc 文件夹。
  2. 源代码管理： 点击左侧边栏的第三个图标（源代码管理模块，或者按 Ctrl+Shift+G / Cmd+Shift+G）。
  3. 操作流：
    • Add: 将鼠标悬停在修改的文件上，点击 + 号（相当于 git add）。
    • Commit: 在上方的文本框中输入提交信息，点击 提交(Commit) 按钮。
    • Push/Pull: 点击左下角状态栏的循环刷新小图标（同步更改）。

同时，你也可以安装 GitLab插件和 Markdown All in One 和 Office Viewer 插件以获得更好的使用体验

💎 针对 Obsidian 用户 (构建个人知识库)​

如果你用 Obsidian 写 Markdown 文档，可以通过插件实现自动同步：

  1. 安装插件： 在 Obsidian 的第三方插件库中搜索并安装 Obsidian Git。
  2. 配置插件：
    • 设置 Commit message (提交信息)，例如：vault backup: {{date}}。
    • 设置自动备份间隔时间 (例如每 30 分钟自动 Commit 和 Push 一次)。
    • 注意： 确保你已经在终端里完整配置过 Git 并至少成功拉取/推送过一次代码，插件才能正常工作。

🚨 7. 团队协作注意事项 (避坑指南)​

  • ⚠️ 先 Pull，再 Push： 每次准备推代码前，先执行一次 git pull。这能避免 90% 的代码冲突问题。
  • ❌ 绝对不要提交敏感信息： 密码、API Key、数据库连接字符串等，绝对不能出现在代码中！
  • 👻 善用 .gitignore： 一些本地生成的临时文件（如 .DS_Store、node_modules/、.obsidian/workspace）不需要同步给所有人，确保它们已经被添加到了项目根目录的 .gitignore 文件中。
  • 💬 提交信息要有意义： 拒绝写 update、1111、修改bug 这种不知所云的 commit message。请按照团队规范或直白地描述：[动作]: [修改了什么]，例如 fix: 修复了首页图片不显示的Bug。
  • LFS 连带责任： 如果你发现拉下来的图片打不开、视频不能播，说明你忘记在本地执行 git lfs install 了，请安装后重新 git lfs pull。

其他技巧

1. 开启“自动抓取”（Autofetch）—— 最实用的提醒功能​

VS Code 默认不一定会频繁去问远程仓库：“喂，有更新吗？”。你需要手动开启这个开关，让它每隔几分钟自动执行一次 git fetch。

  • 操作步骤 ：
  1. 按下 Ctrl + , 打开设置。
  2. 搜索 git.autofetch。
  3. 勾选 Git: Autofetch 。
  4. （可选）搜索 git.autofetchPeriod，默认是 180 秒，你可以改短一点。
  • 效果 ： 开启后，一旦远程有更新，VS Code 左下角的 状态栏 （那个类似 🔄 的图标旁边）就会出现一个“向下的小箭头”和数字，提示你有多少个提交待拉取。

2. 状态栏的“同步”按钮​

在 VS Code 底部状态栏的左侧，你会看到一个包含分支名（比如 main）和同步图标的地方：

  • 点击它 ：它会自动执行 git pull（拉取）和 git push（推送）。
  • 配置自动同步 ：如果你希望每次 Commit 之后自动帮你同步到远程，可以搜索设置： Git: Post Commit Command -> 设置为 sync。 这样你只要一点提交勾号，它就顺便帮你推上去了。

3. 强力辅助：GitLens 插件​

如果你在进行深度协作（多人高频修改文档），单纯的 VS Code 自带工具可能不够看。强烈建议安装 GitLens 。

  • 实时提醒 ：它会在状态栏或者侧边栏非常清晰地显示“你落后远程多少个 Commit”。
  • 代码透视 ：当你光标停在某一行时，它会淡淡地显示“XX天前，某某某改了这里”，这在改文档时简直是神迹，能瞬间知道谁对这段话负责。

⚠️ 协作中的“避坑”指南​

虽然“自动同步”很爽，但在多人写 doc 时，请务必注意：

  1. 频繁 Commit，小步快跑 ：不要写了几千字才提交一次。多提交，能有效减少冲突。
  2. 先 Pull 后写 ：养成习惯，开始写之前点一下同步，保证你在最新的版本上动笔。
  3. 冲突处理 ：如果两个人同时改了同一行，VS Code 会跳出红色的冲突提示。这时候不要慌，它会让你选“保留我的”、“保留他们的”还是“两个都要”。