| name | jc-github-guide |
| description | Use when a user asks how to use GitHub, Git, repositories, pull requests, issues, deployment, or beginner AI-first mini-program development. |
面向小白用户的 GitHub 速查手册
快速索引
用户的问题如果匹配下面的关键词，直接去对应章节找指令模板：
Git / GitHub 大白话术语对照
读完这张表，你就知道大家在说什么了。
| 术语 | 大白话解释 |
|---|
| Git | 一个"版本记录器"，装在你电脑上，帮你记住代码的每一次改动。比如你改了 5 次，Git 就记了 5 个版本，随时可以回到任何一次。 |
| GitHub | 一个"代码网盘网站"，把 Git 记录的历史上传到云端。这样你可以分享给别人、和别人一起改。Git 是工具，GitHub 是网站，不是一个东西。 |
| 仓库（Repository / Repo） | 一个项目文件夹 + Git 的版本历史记录。一个项目就是一个仓库。 |
| 克隆（Clone） | 把 GitHub 上的整个仓库下载到你电脑上。不只是下载文件，还包括所有的历史版本。 |
| 提交（Commit） | 你改了一些代码，觉得可以"存档"了，就做一个 Commit。每个 Commit 是一张"快照"，记录了此刻所有文件的样子。 |
| 推送（Push） | 把你电脑上做的 Commit，上传到 GitHub 云端。这样别人就能看到你的改动了。 |
| 拉取（Pull） | 把 GitHub 上别人做的 Commit，下载到你自己电脑上。 |
| 分支（Branch） | 像游戏的"存档分支"——主线是一条，你要试新玩法就新开一分支，不会影响主线。改好了再"合并"回去。 |
| 合并（Merge） | 把两条分支的代码合到一起。 |
| 冲突（Conflict） | 两个人同时改了同一行代码，Git 不知道用谁的。需要你手动决定。 |
| Fork | 把别人的仓库"复印"一份到你自己名下。这样你可以随意改，不影响别人。 |
| Pull Request（PR） | "我改好了，请拉取我的代码"——请求仓库主人把你的改动合并到他的仓库。开源贡献的核心流程。 |
| Issue | 类似于"工单"或"留言板"——报 bug、提需求、讨论问题的地方。 |
| Star | 相当于"点赞收藏"。Star 越多，说明越多人觉得这个项目好。 |
| README | 每个仓库主页展示的介绍文件。一个项目有没有 README，决定了别人 5 秒内能不能看懂它是干嘛的。 |
| .gitignore | 一个配置文件，告诉 Git "这些文件别管它们，不用记录版本"。（比如 node_modules、.env 等） |
| SSH Key | 相当于你电脑和 GitHub 之间的"免密通行证"。配好了以后，push/pull 都不用输密码。 |
| main / master | 默认的主分支名。现在的项目一般叫 main，老项目可能叫 master。 |
| Actions | GitHub 自带的"自动化机器人"。比如你每次 Push 代码，自动帮你跑测试、自动部署网站。 |
| Release | 给某个版本打个标签，打包发布。比如"v1.0.0 正式发布"。 |
核心场景速查 {#scenarios}
以下是最常用的 5 个场景的指令模板。更多场景见 references/github_scenarios.md。
场景 1：创建新仓库并上传代码 {#场景1}
大白话：你电脑上写了一个项目，想把它放到 GitHub 上。
cd /你的项目路径/
git init
git add .
git commit -m "第一次提交：初始化项目"
git remote add origin https://github.com/你的用户名/仓库名.git
git push -u origin main
如果主分支叫 master（老仓库），把上面的 main 换成 master。
场景 2：把别人的代码下载到自己电脑上 {#场景2}
大白话：你看到一个好项目，想下载下来自己跑一跑。
git clone https://github.com/用户名/仓库名.git
git clone https://github.com/用户名/仓库名.git 我的文件夹名
git clone https://github.com/AIDC-AI/Pixelle-Video.git
下载完后，cd Pixelle-Video 进入项目目录就能用了。
场景 3：修改代码后更新到 GitHub {#场景3}
大白话：你在项目里改了点代码，想让 GitHub 上的代码也同步更新。
git status
git add .
git add 文件名1 文件名2
git commit -m "修复了登录页面的样式问题"
git push
场景 3.5：先拉取最新代码（别人也改了的情况下）
git pull
git add .
git commit -m "合并了远程更新"
git push
场景 4：给别人的开源项目提交代码 {#场景4}
大白话：你发现某开源项目有个 bug，想修好贡献回去。
流程一共 6 步（都在 GitHub 网页上操作 + 命令行配合）：
git clone https://github.com/你的用户名/项目名.git
cd 项目名
git checkout -b fix-login-bug
git add .
git commit -m "修复了登录时密码框无法输入的问题"
git push origin fix-login-bug
场景 5：解决代码冲突 {#场景5}
大白话：你和小明同时改了同一行代码，Git 不知道该用谁的。
当 git pull 或 git merge 报冲突时：
git status
git add 冲突文件名
git commit -m "解决了XXX冲突"
git push
如果冲突太复杂想放弃合并：
git merge --abort
使用 AI 工具操作 GitHub {#ai-tools}
如果你在用 Claude Code / OpenCode / Codex / Cursor 等 AI 编码工具，它们本身就可以帮你执行 Git 命令，你不需要自己敲。
模式 1：让 AI 直接帮你操作
直接告诉 AI，用大白话说你要干嘛：
"帮我把当前项目的代码提交到 GitHub，commit 信息写'修复首页加载慢的问题'"
"帮我把这个项目从 GitHub 上下载到本地"
"帮我创建一个新分支叫 feat-dark-mode，然后切换过去"
"帮我在 GitHub 上搜一下有没有好用的 Python 爬虫项目，stars 要超过 1000"
AI 会自动帮你执行对应的 Git 命令。
模式 2：命令我也能看懂，我自己敲
如果你更想自己敲，告诉 AI：
"我要把代码推送到 GitHub，给我命令，我一条一条执行"
模式 3：代码审查
"对比一下 main 分支和我当前分支的区别，看看我改了哪些"
"帮我写一个 Pull Request 的描述，总结我这次做了什么改动"
模式 4：看不懂就让它解释
"git status 输出是：...（贴上去）。帮我用大白话解释这是什么意思"
"为什么 git push 报这个错：...（贴错误信息）"
AI-first 微信小程序开发指南 {#miniprogram-guide}
核心概念：你不会编程、不懂架构、不会用 GitHub，这些都不重要。你只需要像产品经理一样——描述你想要的、在微信开发者工具里看效果、不满意就告诉 AI 改。AI 是给你干活的工程师。
下面六步走完，你就能做出一个能跑的小程序。
总体路线图
| 阶段 | 干什么 | 做完的标志 |
|---|
| 0 | 需求梳理 | AI 理解你想做什么，输出功能清单 |
| 1 | 环境准备 | 注册好微信小程序账号 + 装好开发者工具 |
| 2 | 选组件库 | 确定用哪套组件库，AI 帮你装好 |
| 3 | 搭建骨架 | 所有页面创建完毕，TabBar 能点击 |
| 4 | 逐页开发 | 每个页面内容写好了，能正常预览 |
| 5 | 打磨细节 | 交互顺滑、样式满意 |
| 6 | 上线发布 | 提交审核，用户能用 |
阶段 0：需求梳理 — 你究竟想做什么？
先不要急着写代码。用大白话告诉 AI 你想做什么，让它帮你理清思路。
"我想做一个微信小程序，功能是 [用大白话描述]。请帮我梳理成一张功能清单，列出需要哪些页面，每页有什么内容和交互。先不要写代码，我们先确认方向。"
检查 AI 的输出：它理解对了吗？有没有漏掉你想做的功能？确认无误后再进入下一步。
阶段 1：环境准备 — 把工具装好
- 去 微信公众平台 注册小程序账号（个人就能注册，注意：个人主体不能做电商/外卖/社交等类目）
- 登录后获取 AppID（开发 → 开发管理 → 开发设置）
- 下载 微信开发者工具
- 用 AppID 在开发者工具里新建项目
"我已注册微信小程序并获取了 AppID。请告诉我如何在微信开发者工具里创建一个新项目，选择什么模板、填什么参数。我选择不使用云开发。"
如果需要用到 GitHub（比如下载 vant-weapp 等组件库），参考本指南的场景 2 下载代码。
阶段 2：选型 — 选什么组件库？
大白话：组件库就是别人写好的现成按钮、列表、弹窗、导航栏。你不用从零画一个按钮，直接用就行。
根据你的需求，从下面五选一：
推荐决策：把你的需求告诉 AI，让它帮你选——
"我想做一个小程序，类型是 [电商/工具/展示/管理]，大概有 [X] 个页面，风格偏好是 [简洁/专业/活泼]。根据这些条件，帮我从 vant-weapp / WeUI / TDesign / iView Weapp / 纯原生 中推荐最合适的，并说明理由。"
选定后，让 AI 帮你安装（以 vant-weapp 为例）：
"我要用 vant-weapp 组件库开发微信小程序。请帮我用 npm 方式安装 vant-weapp 并完成配置（包括修改 app.json、project.config.json 等）。先只做配置，不写页面代码。"
关键提示：安装完 npm 包后，记得在微信开发者工具里点击"工具 → 构建 npm"，否则组件不生效。
阶段 3：搭建项目骨架
现在让 AI 把你所有页面的"空壳"搭好。
"基于阶段 0 整理的功能清单，帮我搭建小程序的项目骨架：1) 配置 app.json（包括所有页面路由和底部 TabBar）2) 为每个页面创建 .wxml / .wxss / .js / .json 四个文件 3) 写好全局样式 app.wxss。用 [选定的组件库] 的导航组件。先做空壳，不填内容。"
做完后在开发者工具里点编译，确认：TabBar 能切换、每个页面能正常显示（虽然是空的）。
阶段 4：逐页开发 — 核心循环
这是最关键的阶段。一次只做一页，每页的流程如下：
- 告诉 AI 这一页要展示什么、有什么交互
- AI 生成代码
- 你在开发者工具里预览
- 不满意就描述问题让 AI 改
每页的 prompt 模板：
"现在开发 [页面名] 页面。需要展示：[具体要展示的内容列表]。用户点击 [某处] 后 [跳转/弹窗/切换]。请用 [组件库] 的 [具体组件名，如 van-button、van-cell、van-tabbar] 来实现。同时生成 wxml 结构、wxss 样式、js 逻辑和 json 配置。不要生成其他页面的代码。"
逐一完成所有页面。每完成一页就预览一次，确认没问题再做下一页。
阶段 5：打磨细节
全页做完后，开始打磨：
| 要检查的 | 怎么告诉 AI |
|---|
| 样式不满意 | "首页的按钮在手机上显示太小了，请调大一些，圆角也加大一点。" |
| 页面跳转有问题 | "点击商品卡片后没有跳转到详情页，帮我检查一下。" |
| 数据没显示 | "列表页是空的，没有显示商品数据。请帮我加上模拟数据。" |
| 交互不流畅 | "页面切换时感觉卡顿，帮我优化一下性能。" |
| 颜色/字体 | "整体颜色太素了，帮我改成暖色调，主色用 #FF6B35。" |
技巧：把开发者工具的截图贴给 AI（如果能发图片），或者描述"我看到的"vs"我期望的"，AI 就能精准修改。
阶段 6：上线发布
- 在开发者工具右上角点击"上传"，填好版本号（如 1.0.0）和备注
- 去 微信公众平台 → 管理 → 版本管理
- 找到刚上传的版本，点击"提交审核"
- 等待审核（通常 1-7 天）
提交前让 AI 做最后检查：
"我的小程序要提交审核了，帮我检查：1) 所有页面路径是否正确 2) 有没有硬编码的测试数据 3) 是否符合微信小程序的基本规范。如果有问题请列出。"
审核通过后，点击"发布"即可。如果审核被驳回：
"我的小程序审核被驳回了，原因是 [贴驳回原因]。请帮我修改对应的代码。"
GitHub 常见错误速查
| 错误信息 | 大白话原因 | 怎么修 |
|---|
fatal: not a git repository | 你不在一个 Git 项目文件夹里 | cd 到正确的项目目录，或者先 git init |
Permission denied (publickey) | SSH Key 没配 | 去看 场景 7 |
error: failed to push some refs | 远程有你本地没有的更新，或者你本地落后了 | 先 git pull 再 git push |
Please tell me who you are | 没设置用户名和邮箱 | git config --global user.name "你的名字" 和 git config --global user.email "你的邮箱" |
fatal: refusing to merge unrelated histories | 本地和远程是两个不相关的仓库 | git pull origin main --allow-unrelated-histories |
Your branch is ahead of 'origin/main' by X commits | 你本地有一些提交还没推送到 GitHub | git push |
.DS_Store 文件老是出现 | macOS 系统文件，应该在 .gitignore 里忽略 | 在 .gitignore 里加一行 .DS_Store |
Updates were rejected because the remote contains work | 远程有别人推的新代码 | git pull --rebase 再 git push |
fatal: detected dubious ownership | 文件夹的所有者和当前用户不一致 | git config --global --add safe.directory /路径 |
更多场景
完整 19 个场景的指令模板、大白话解释和注意事项，见：references/github_scenarios.md
环境检查脚本：scripts/git_check.sh — 运行它检查你的 Git 有没有配置好。
微信小程序完整开发指南（含组件库对比、逐页 prompt 模板、常见坑汇总）：references/wechat_miniprogram_guide.md
