GitHub 入门：从一个项目开始跑通全流程

来源：抖音视频 · 李小伊 Lee · 约 9 分 53 秒 · 作品 ID 7699786627421392166

作者拿一个真项目（BongoCat，桌面上的 Live2D 敲键盘猫）当教具，把 GitHub 从「打开页面看哪一眼」到「改完代码分享回去给作者」的整条路走了一遍，全程不用写一行代码。八个章节：读懂项目 → 下载别踩坑 → 问题与需求 → 更新不用蹲 → Fork 与 Clone → 让 AI 改代码 → 用 PR 贡献 → 从合并到发布。

对正在做电赛/嵌入式的你，这条的价值不在「猫」，而在它把「Fork → 本地改 → 提 PR」这条开源协作主链路讲透了——以后你在 GitHub 上找到一份别人的飞控/滤波/上位机代码，想改成自己能用的版本，就是这一套。

0. 先看这张：整条路

六个阶段，蛇形往下读：看懂 → 下载 → 反馈订阅 → 复制一份 → 让 AI 改 → 分享回去。红色虚线是闭环：你的改动被合并、作者发了新版，用户重新下载安装，才真的用得上。

1. 读懂项目：第一眼只看 README

此处配图暂缺，参阅原帖。

作者给的读页顺序：英文看不懂就先翻译（浏览器自带翻译 / 沉浸式翻译插件都行），然后直接往下翻找 README。README 直译就是「读我」，里面是「它是干什么的、什么电脑能装、作者最想给你看的信息」。而且很多项目带中文版，页面上可以直接切换。

视频里 BongoCat 的 README 原文（画面 OCR）：面向 Windows 和 macOS 的桌面陪伴应用，一只 Live2D 小猫住在屏幕上，眼神和爪子跟着鼠标动，你按的每个键它都有反应；可以换模型、拖窗口；完全开源、不收集任何数据；支持离线运行；灵感来自 MMmmmoko 的 Bongo-Cat-Mvero。

看懂了就顺手 Star：右上角的 Star 就是「收藏」，你在别人嘴里听到的「这项目多少 star」说的就是它；数字可以粗略判断热度（画面上是 24k，作者说大约 24000 个账号点过）。收藏之后就能在自己头像 → Stars 里把它翻出来，不怕再满世界找这只猫。

2. 下载别踩坑：Download ZIP 下来的不是软件

此处配图暂缺，参阅原帖。

这是标题里那个坑。绿色 Code 按钮 → Download ZIP，下载解压后是一堆文件夹和文件，没有安装包。作者的类比很准：想买块蛋糕回来直接吃，结果拿到的是配方。因为 GitHub 并没有一个通用的「下载安装」按钮——有的项目打开网页就能用，有的给安装包，有的要自己搭建。

能直接用的软件在 Releases（项目首页右侧），意思是「发布」，就是作者正式发布版本的地方：每个版本改了什么、有哪些文件可下、历史版本都在里面。标着 Latest 的就是最新版。

此处配图暂缺，参阅原帖。

作者提醒：如果项目没给快捷入口，就往下找 Assets（这个版本的下载文件列表）。看着多，但只需要记两条：视频演示中 Windows 使用 .exe、macOS 使用 .dmg。这只是该项目的例子：其他软件也可能提供 .msi、.msix、.pkg、压缩包或免安装版本，具体以项目发布说明为准。

3. 问题与需求：想加功能去 Issues

此处配图暂缺，参阅原帖。

用到一半觉得猫太安静，「能不能我打一个字它喵一声」——这个诉求就去 Issues（中文「问题」）：可以提新功能，也可以反馈使用中遇到的问题。但作者强调先别急着发，先看别人提过的，说不定你想的别人早想到了，作者还回复过「有这个计划」。

画面里 BongoCat 的 Issues 列表（OCR 原文，开放 24 条）很能说明这个区是什么气氛：

• [feat] 请求增加番茄钟功能 / 接入 OpenClaw、Hermes / 增加 Claude Code 等 AI 工具实时监控 / 根据麦克风输入变化口型
• [bug] BongoCat 无法置顶、开机启动 / 安装目录多套一层文件夹

feat 就是 feature（功能）的缩写，通常表示想改进或增加功能；bug 是运行中出的问题。你的想法确实没人提过，再点 New issue 按提示写清楚。

4. 更新不用蹲：Subscribe 与 Watch

此处配图暂缺，参阅原帖。

两条路，别搞混：

• 只想盯这一条 Issue：打开它，点右边的 Subscribe（订阅），后面有人回复、有新进展就通知你。
• 想知道整个项目什么时候发新版：回项目首页点右上角 Watch，四档可选：
  1. Participating and @mentions——跟我有关的再通知我（我参与过的讨论、有人 @ 我）；
  2. All Activity——这个项目所有动态都通知我；
  3. Ignore——彻底静音；
  4. Custom——自定义，可以只勾选 Releases，以后作者发新版本才通知你（画面里还能勾 Issues / Pull requests / Security alerts）。

5. Fork 与 Clone：先复制一份，再动手

改之前先看 LICENSE（开源协议），作者允许你怎么用、怎么改都写在里面。BongoCat 用的是 Apache-2.0：修改分享时要保留协议许可、标明修改。（作者顺带提了一嘴另一期讲过「开源项目能卖吗」。）

此处配图暂缺，参阅原帖。

你改不坏作者的项目，因为你碰不到他的代码。 点右上角 Fork（分叉）→ Create a new fork → 选自己的名字，你的账号下就多了一份，随便改，作者那边不变。

此处配图暂缺，参阅原帖。

画面上 Fork 完的仓库顶部会写 forked from ayangweb/BongoCat，以及 This branch is up to date with ...（和上游一致），旁边还有 Sync fork 用来把作者后来的更新同步回来。

把代码拿到电脑里有三种方式（作者给了三个，任选）：

1. 直接下载 Download ZIP 解压；
2. 终端里 git clone https://github.com/<你的用户名>/BongoCat.git；
3. 跟能操作本地文件的 Agent 说一句「把我 fork 后的仓库克隆到这个文件夹」——作者说这条可能更适合很多人的体质。

6. 让 AI 改代码：Branch / Commit / Push

此处配图暂缺，参阅原帖。

下载完就可以跟 AI 提需求了。视频里的原话是：「先读一下这个项目说明，把原版运行起来，再帮我加一个打字喵喵叫的功能，最后还能随时关掉。」

作者的两个保险动作很值得抄：

• 单独开一条 Branch（分支）专门开发这个功能。项目原本有一条主线叫 master（很多项目叫 main），新分支例如 feat/typing-meow，改坏了不影响主线，也方便作者 review。
• 改一部分就 Commit 一次。作者的类比：Commit 就像打游戏随时存档，失败了方便回退，不用等整个功能做完才存一次。

改完别光听 AI 说完成了，自己跑一遍。本地改完提交完，GitHub 上还没更新——还需要 Push（推），把这些改动上传到自己的仓库。

运行前先确认当前位置、当前分支和远端地址；上面的 feat/example 是示例，不是必须使用的分支名。

（这张命令表是我补的，视频里没有逐条讲命令。）

7. 用 PR 贡献：先读 CONTRIBUTING，再发 Pull Request

此处配图暂缺，参阅原帖。

想把改动交给原作者？先别急着交，看看项目里有没有 CONTRIBUTING（贡献指南）——作者希望你怎么提交、要做哪些检查一般都在里面。BongoCat 有 CONTRIBUTING.zh-CN.md，画面 OCR 出来的要点（这几条是真实文件内容，不是我编的）：

• 提交新议题或 PR 前，先搜索已有议题和 PR；
• 要大幅改变产品行为，先说明用户需求和预期结果再动手；
• 不要在同一次改动里夹带无关的清理或格式化；
• 改面向用户或贡献者的文档时，同一次改动里同步更新英文版和简体中文版；
• 公开文档要聚焦产品行为和使用流程，不要暴露内部项目代号、源码文件名；
• 开发环境：Windows 和 macOS，Linux 不是发布目标；装 rustup（仓库会固定工具链版本）、just、pnpm，然后在仓库根目录 just dev；另有一条 docs(contributing): require MSVC on Windows。

然后从自己 fork 的仓库里选中刚改的分支，向原项目发起 Pull Request（拉取请求，缩写 PR）——可以理解成一份合并申请：「猫叫功能我做好了，你看看要不要加进你自己的项目」。

对比一下前面第 3 节：Issue 是「我有个想法，能不能让猫叫」，PR 是「我已经做完了，你来验收」。

作者给的提交说明建议（这几条很实在）：

• 先问一下作者想不想要这个功能；
• 说明自己测试的情况；
• 主动说明用了 AI 辅助生成；
• 做好被讨论、被打回修改、甚至不被接受的准备。

8. 从合并到发布：还差最后一步

作者确认可以采纳，才会 Merge（合并），把你改动的代码合并进原项目——现在这份代码才算被正式接纳。

但大家电脑里的猫还不会叫：还要等作者发布包含这个功能的新版本，大家下载安装以后才能用上。这也就是第 4 节 Watch/Subscribe 的意义所在。

9. 收尾：作者的六句口诀

回到最开始那个满屏英文的界面，你已经知道从哪下手了：

不用一次记住所有按钮，先想自己要做什么，再找对应的入口，用几次就熟了。

此处配图暂缺，参阅原帖。

10. 这套流程对你有什么用

• 找开源项目当参考：电赛/嵌赛里常用的滤波器、PID、上位机、ROS 包、示波器固件，大多在 GitHub。按这条视频的顺序读：README 看能不能跑 → Releases 看有没有现成固件 → Issues 搜「你这个平台的坑有没有人踩过」。
• README 之外的隐藏信息：AGENTS.md、CONTRIBUTING.md、justfile、rust-toolchain.toml 这类文件，是判断「这个项目好不好上手/能不能让 AI 接手」的关键——这一点和 018 那条「把原理图做成 MD 给 AI 读」是同一个思路：先把项目上下文变成 AI 能读的文档，AI 才不会瞎猜。
• 让 AI 改别人的项目：照搬视频那句提示词的结构——「先读项目说明 → 把原版跑起来 → 再加我的功能 → 加个开关能随时关掉」。这句和 008 那条「别一句话让 AI 干完」完全对得上：把目标拆成可验证的小步，并且要求先跑通原版。
• 一定要开分支 + 小步 Commit。硬件调试也一样：改一个参数存一次档，炸了能立刻回到上一个能跑的状态。
• 提 PR 前先读 CONTRIBUTING，并主动声明用了 AI。这是开源社区的礼仪，也直接影响作者会不会收。