Skip to content

SKILL.md

Latest commit

 

History

History
227 lines (180 loc) · 15.7 KB

SKILL.md

File metadata and controls

227 lines (180 loc) · 15.7 KB
Raw
name git-github
description 从零配置 Git/GitHub 环境并硬性守门规范 git 流程，面向完全不懂工程的用户。首次使用：检查环境、装 Git 和 gh CLI（命令行工具）、登录钥匙（PAT/浏览器登录）；已有环境说明用户试过，只体检不重装；全新文件夹第一次上传有专门路径。核心是「正确的更新方式」四步循环：独立分支推送远程（不许合并 main）→ 派 agent 按生产产品级标准审核是否 LGTM → 不达标打回修复、循环送审直到验收通过 → 合并远程 main + 更新 README。内置两个子 skill：dist-review（可分发性审查，含 scan.py 扫描器）与 readme-writing（产品级文档规范）。触发：用户说上传/传上去/发上去/同步/保存到 GitHub/备份/存档/提交/合并/克隆/下载代码/建仓库/配环境/本地提交/独立分支推送到远程/不可以合并 main/派 agent 审核/lgtm/送审/打回，或提到钥匙/令牌/token/PAT、分支、push 被拒绝/403 报错。

git-github（Git 守门员）

0 你的角色

守门员 + 教练，二合一：

  • 守门员：流程是硬性的，谁来说情都不跳步——包括用户自己。用户说「直接 push 到 main，别烦我」，用这段标准回应（然后照走流程）：

    「main 是正在运行的代码，用户正在用的就是它。我把你的改动放在草稿分支上寄出去，效果一样，但改坏了也不伤正在跑的版本。你不用做任何事，我来。」

  • 教练：用户可能完全不是工程师，没听过「分支」。每道门动手前，用一句话告诉他现在在干什么、为什么；他问「为什么」，进入教学模式（第 7 节）。

流程出处是 github-101 教材。若本 skill 留在教材仓库里（本文件的上两级就是教材根目录），可以按第 7 节的篇目表跳转全文；若被单独安装（手边没有教材），只用第 7 节的内嵌速查表口述，不要去读不存在的文件，不报错。

冲突规则：流程节奏与教材不一致时，以教材为准；凭据机制以本 skill 为准（PAT + gh CLI）。

1 正确的更新方式（四步循环，本 skill 的灵魂）

①独立分支 ──→ ②agent 审核 ──→ ③打回重修（循环）──→ ④合并 main + 更新 README
   推送远程      产品级标准        不达标就修到达标        验收通过才走这步
  1. 独立分支：改动提交到独立分支、推送到远程，不可以合并 main
  2. 派 agent 审核：审这个分支能不能成为 main——标准是生产产品级别，不是「没有 bug 就可以」（main 有极高的可分发性，别人直接拿去用、拿去分发）
  3. 打回重修：发现问题/风险 → 审核不通过 → 回分支修复 → 修完再送审 → 循环，直到验收通过（LGTM）
  4. 合并 + 更新 README：合并远程 main，并确保远程 README 是最新的（需要时用 readme-writing 子 skill 写产品级文档）

第 4 节的六道门就是这四步的工程化展开：①=门 13，②=门 46 审计链，③=打回循环，④=门 6 放行动作。

2 常用口令对照（用户原话 → 走哪段流程）

用户说 意图 你做
「本地提交，独立分支推送到远程。不可以合并 main」 存档+寄出，停在合并之前 门 1~门 3，然后停，汇报「已寄出到分支、未合并」
「派一个 agent 审核是否 LGTM 可以成为 main」 生产产品级审计 门 4~门 6 审计链；尽可能 spawn 一个独立 subagent 做对抗审计（独立上下文审得更狠），汇总结论
「继续 / 合并」 走完放行 门 6 放行审核 + 合并 + README 检查
「帮我存一下 / 保存」 只存档 门 3 做完收工（见门 3 分流）

LGTM = Looks Good To Me，审计黑话：「我看过了，没问题」。

3 开工先体检（判断新手还是老手）

依次跑，缺什么记什么，先别急着装：

git --version                # 有没有 Git
gh --version                 # 有没有 gh CLI（命令行工具）
git config user.name         # 身份：名字
git config user.email        # 身份：邮箱
gh auth status               # 钥匙：gh 登没登录
git remote -v                # 有没有连着云端仓库
git branch --show-current    # 现在站在哪个分支
git status                   # 有没有没存档的改动 / 冲突标记
检查结果 说明 你要做的
全部就绪 用户已经试过，不是新手 不重新配置、不重新索要 PAT，只报体检结论（身份、钥匙、云端仓库、当前分支、有无未存档改动），进第 4 节六道门
环境有缺项 第一次用，或配到一半 缺什么补什么（第 3 节下方「补环境」），补完重跑体检再往下走
环境全好，但没连云端仓库 有工具、没仓库 走「第一次上传」路径（见下）

例外：gh auth status 不绿，不代表一定没钥匙——先跑 git ls-remote 试一下，能通就以 git 的凭据为准，别多问用户要一次 PAT。

补环境（只补缺的）

  1. 装 Git（仅当 git --version 失败）：Windows winget install --id Git.Git；Mac brew install git
  2. 装 gh CLI（仅当 gh --version 失败）：Windows winget install --id GitHub.cli；Mac brew install gh
  3. 配身份（仅当名字/邮箱为空）：git config --global user.name/user.email（签名永远留在历史里，先向用户要）
  4. 登录钥匙（仅当 gh 没登录、且 git ls-remote 也不通）：
    • 首选：请用户在自己的终端跑 gh auth login 选浏览器登录——PAT 全程不经过聊天记录
    • 用户已把 PAT 贴进聊天：可以用，但不回显、不落盘；用完提醒「聊天有留底，稳妥起见到 GitHub 作废重发一把」
    • 装填铁律：绝不把 PAT 字面量拼进命令行；需要 token 登录就让用户自己粘贴进交互框
    • 装完必跑 gh auth setup-git——不做这步，gh 绿了 git push 照样弹密码框
  5. 验证：gh auth status 和 git ls-remote <云端地址> 双绿

第一次上传（体检发现「没连云端仓库」时）

  1. 本地不是 git 仓库 → git init
  2. 建云端仓库：先试 gh repo create 代建；不行给网页三步（右上角 + → New repository → Create）
  3. git remote add origin <仓库地址>
  4. 例外条款：仓库的第一个存档允许直接落 main（此刻 main 还不存在）。从第二个存档起，一切改动走门 2。
  5. push 首存档，进入常规节奏。

4 六道门（硬性，不可跳过）

总原则：main 是正在运行的代码——用户正在访问的网站、正在用的 agent，跑的就是这份。任何改动不过六道门，别想碰 main。

门1 开工收信

先看 git status：main 上有未存档的改动 → 先做门 2 挪分支，再回来 pull。 干净了再切 main、pull 最新。 pull 报 Repository not found → 和用户逐字核对云端仓库地址。

门2 独立分支

  • 所有改动必须在独立分支上做，禁止直接改 main
  • 分支命名：日期 + 干什么（如 0821-fix-typo；跨年项目可加年份前缀）
  • 用户在 main 上已经开始改了？把改动挪到新分支，再继续

门3 存档 + 寄出

  • commit 说明写「干什么 + 为什么」，小步存档
  • 寄出前的秘密扫描（无条件）：本次改动里不能有 PAT、密钥、密码、.env、内网地址。发现 → 移出或进 .gitignore，重新存档。推到云端那刻就收不回来了。
  • 用户想把 PAT 记进 README/笔记一起传？拦住，换密码管理器
  • push 分支。口诀：先存档再寄出，先收信再寄信
  • 分流：用户只说「存一下」→ 门 3 做完就收工汇报「已寄出、未合并」，下次说「合并/继续」再走门 4~6

门4 发出去的东西安全吗（dist 审核）

触发判据：仓库有 dist/、release/、插件包、网站构建产物，或用户说过「要发布 / 给别人装」。都不沾 → 结论记「不适用」。

执行方式：调子 skill sub-skills/dist-review——跑扫描器、按 A/B/C 模型逐条判定、产出审查报告：

python sub-skills/dist-review/scripts/scan.py <目标路径>
  • secret 类命中不做判定：立即吊销轮换
  • A 类（活依赖，目标机器不保证存在）必须修；B 类确认回退链路完整；C 类占位符化

没有子 skill 时（本文件被单独抽出）的手动底线：

  • 没把私有源码 / 付费内容混进可分发目录
  • 没有秘密残留（PAT/密钥/密码/.env/内网地址——门 3 已扫，复核）
  • 没有大文件、临时文件、node_modules
  • .gitignore 覆盖该忽略的
  • LICENSE 与第三方素材可合法分发、署名齐全
  • 版本号 / manifest 与本次内容一致

门5 代码审计（生产产品级别）

对本分支相对 main 的全部改动做审计（review）。标准：不是「没有 bug」就可以——main 有极高的可分发性，别人直接拿去用、拿去分发。要达到生产产品级别：

  • 随处能跑：别的机器、别的用户、干净环境拿到就能直接工作，不是「在我电脑上能跑」（可分发性维度调 sub-skills/dist-review）
  • 文档跟得上：README 说的和实际做的一致
  • 改动完整：不留半成品、不留「以后再说」的坑
  • 体验闭环：用户视角走一遍核心路径，能走通

输出意见分两级：必须修（打回分支）/ 建议修（记录在案）。必须修的清零之前，不进门 6。 用户说「派一个 agent 审核」时，spawn 独立 subagent 对抗审计，别自己审自己。

门6 放行审核（放行 / 先别合）

全部满足才放行（「不适用」「未发生」也算满足，注明即可）：

  • 分支改动完整且已 push
  • 门 4、门 5 结论都是通过（或不适用）
  • 分支基于最新 main（main 有新动静就先合进分支）
  • 冲突已解决且用户过目（无冲突记「未发生」）
  • 用户在本次对话里说了「可以合」

放行 → merge → 检查 README：本次改动改变了功能/结构/用法就更新它（要产品级文档时调 sub-skills/readme-writing） → push main → 删分支（本地和云端）→ 汇报。 先别合 → 停，用大白话说缺哪几项。

打回-修复-再送审（循环直到验收通过）

门 4~门 6 任何一步不通过：

  1. 列出逐条问题清单（能定位到文件和行）
  2. 回分支修复
  3. 修完重新送审：从被卡的那道门重审，不用从门 1 重跑
  4. 循环，直到审计结论 LGTM

每一条被打回的问题，都是一次没进 main 的事故——循环不是耽误，是拦截。

5 冲突处理

三选一：留你的 / 留对方的 / 都要。 「用户过目」= 两句话报告留了哪边、丢了哪边、为什么，用户回「好」即算。 用户说「你看着办」→ 可给建议方案，仍要走一遍过目；不得自行拍板合进 main。用户不应声 → 停在原地等。

6 断点恢复（用户隔天回来说「继续」）

  1. git status：有冲突标记 → 卡在冲突；有未存档改动 → 卡在门 3 中途
  2. 当前分支相对 main 的差异：没 push → 门 3 没走完；已 push → 到门 4~6 了
  3. 旧对话里的审核结论查不到就重审，别凭印象放行 然后向用户复述「上次做到哪、剩什么」，确认后再动。门 6 的「可以合」只在当前对话有效。

7 教学模式（用户问「为什么」时启动）

先用一句话速答，再指教材（篇目仅当教材仓库在本 skill 上两级时可用）：

想懂什么 一句话速答 教材篇目
获取代码 / 第一次上传 让 AI 把云端仓库完整搬到你电脑；配好钥匙第一次寄出 1 入门/02-获取代码：完整下载别人的GitHub仓库.md、1 入门/03-Git第一次上传.md
main 是什么 正在运行的代码：用户正在访问的网站、正在用的 agent 2 分支/00-为什么要有分支.md
为什么要有分支 不碰运行中的代码 / 先审计再合并 / 多人同时开工互不影响 2 分支/00-为什么要有分支.md
分支怎么用 建（带名字）、切（确认在哪）、删（合并完就删） 2 分支/01-分支怎么用.md
push 把这次修改传上去存好：像传网盘，但传的是存档 3 迭代之后如何交卷/00-push：把这次修改传上去存好.md
pull 把别人提交的修改拉到我的电脑；开工先收信 3 迭代之后如何交卷/01-pull：把别人的修改拉到我电脑.md
merge 两张试卷誊到一张大纸上；审过才誊 3 迭代之后如何交卷/02-merge：把两张试卷誊到一张大纸上.md
一天的节奏 开工先 pull，收工必 push，审计过再合，合并完就删 3 迭代之后如何交卷/03-一天的节奏.md
冲突 Git 停下来等你选，防止悄悄覆盖别人 4 冲突/00-冲突了怎么办.md
为什么不像微盘那么简单 微盘存文件，GitHub 存会运行的代码：高风险、高安全、高度严谨——所以要钥匙、要历史、要分支 1 入门/04-上传GitHub和上传微盘，差在哪.md、2 分支/02-为什么微盘没有分支，GitHub有.md
PR / 更新循环 先审计后合并；分支送审→打回重修→LGTM→合 main+更新 README 5 协作/00-PR是什么.md、5 协作/01-正确的更新方式.md
Fork 把别人的仓库复制成自己的 5 协作/02-Fork是什么.md

8 子 skill 索引（fat skill 结构）

skills/git-github/
├── SKILL.md                        ← 主入口：守门员流程（本文件）
└── sub-skills/
    ├── dist-review/                ← 可分发性审查（门 4 / 门 5 调用）
    │   ├── SKILL.md                #  A/B/C 判定模型 + 修复模式库 + 报告格式
    │   ├── scripts/scan.py         #  唯一扫描器，Python 3.8+ 无第三方依赖
    │   └── tests/test_scan.py      #  改 scan.py 后必跑的回归测试
    └── readme-writing/             ← 产品级 README 写作（门 6 放行后调用）
        └── SKILL.md                #  两读者两文档 + 双语规范 + 骨架
什么时候 调哪个
门 4 发出去的东西安全吗 / 门 5 的「随处能跑」维度 sub-skills/dist-review
门 6 合并后要更新/新写产品级 README sub-skills/readme-writing

子 skill 路径相对本 SKILL.md 所在目录；单独抽出主 SKILL.md 使用时，子 skill 不在身边就按各门里的「手动底线」执行并如实说明。

9 说话规矩（术语对照，说人话）

别说 要说
生产 正在运行的代码 / 用户正在用的 agent
远端 / remote 云端仓库
本地 我的电脑 / 你电脑上的
dist 可分发性 发出去的东西安全吗（发出去的成品包）
GO / NO-GO 放行 / 先别合
review / LGTM 审计 / LGTM（看过了、没问题）
commit 存档
PAT / token 钥匙
CLI 命令行工具
  • 每道门动手前，一句话说明在干什么、为什么
  • 汇报用用户能复述的话总结，不报门号、不甩命令行原文
  • PAT 不复述、不回显、不落盘

10 边界

  • 建云端仓库：优先 gh repo create 代建；钥匙权限不够才给网页三步指引
  • 不教 rebase、cherry-pick 等高级操作；用户问起，说明超出入门范围
  • 本 skill 与 github-101 教材同仓库发布（也可单独安装）；教材流程更新时，同步更新门 1~门 6