Stage 0 — 基础准备（Foundations）

这一关先检查你是否会用后面一定会用到的四种工具。会的话就直接跳过。不会也没关系。照着下面的小练习做一次即可。

何时可以跳过这个阶段

看看下面四件事。你不需要背指令。但你要能自己查资料并完成：

• 用 Python 向 API (Application Programming Interface) 拿公开资料，再从 JSON (JavaScript Object Notation) 里找出一个值。
• 用 Git 复制专案（clone）、开工作线（branch）、保存版本（commit），再把版本送到网络上（push）。两次修改撞在一起时，知道要留下什么（合并冲突）。
• 用 CLI（命令行界面） 切换资料夹、建立文件并执行 Python 程序。
• 看懂 YAML 与 JSON。它们都是用文字保存资料的格式。

四项都能做到，就直接前往 Stage 1 — LLM 基础。只要有一项不确定，就完成本页的主要练习。需要时再展开补充内容。

📌 学习目标

完成这一关后，你可以：

• 让 Python 从 API 获取数据，再读出 JSON 里需要的部分。
• 从终端运行程序，并找到程序创建的文件。
• 认出项目仓库、查看版本历史，并用 Git 保存一个版本。
• 认出 YAML、JSON 和 API token（让程序登录的秘密文字），知道哪些内容不能公开。

🔑 核心名词

先认识执行程序和交换资料的工具，再看项目网站如何保存及分享修改。

分类	名词	白话解释	本章用途或界线
程序与执行	Python	程序语言；用它写出指令，再执行程序。	主练习用 Python 取得资料。
	Terminal（终端）	让你输入和查看文字指令的视窗。	在这里执行主练习。
	CLI（Command-Line Interface，命令行界面）	用文字指令与程序互动的介面。	例如输入 Python 指令。
	Shell（命令解释器）	解读并执行输入的指令，例如 PowerShell 或 Bash。	它通常在终端中运作。
资料与介面	API（Application Programming Interface，应用程序接口）	让程序依规则与另一个程序或服务互动的介面。	不只用于网站。
	JSON（JavaScript Object Notation）	以文字表示结构化资料的格式。	主练习读取 API 回传的资料；不是程序脚本。
	YAML（YAML Ain’t Markup Language）	另一种文字资料格式，常用于设定。	缩排有意义；不是程序脚本。
	API token	让程序证明身份的秘密凭证，像一把钥匙。	不要公开或上传；主练习不需要。
平台与项目	GitHub	分享程序码、工具、教材与线上资源的平台，许多开源项目在这里协作。	公开不代表一定是开源；要查看授权。
	Git	记录文件版本的工具，可以在自己的电脑上使用。	Git 与 GitHub 是不同的东西。
	Repository（Repo）	存放一个项目文件及版本记录的地方，也叫仓库。	本页项目就是一个 repository。
认识项目	README	项目的介绍文件，通常说明用途和如何开始。	先读它，找到学习入口。
	License	授权文件，说明别人可以如何使用、修改或分享作品。	是否开源与使用条件要看实际授权。
	Issue	项目中用来讨论问题、建议或待办事项的页面。	先观察，不必发表。
修改与协作	Branch	一条独立的修改工作线；main 常是大家共用的主要工作线。	可先在自己的工作线修改。
	Commit	像替项目拍一张有说明的快照，保存选定的修改与作者、时间、说明、识别码（hash）。	编辑器的储存不等于 commit；历史可以分支。
	Push	把本机的版本记录送到 GitHub 上对应的工作线。	送出不会自动合并到 main。
	Pull Request（PR）	提出一组修改，让其他人检查并讨论是否接受。	提出 PR 不代表修改已合并。
	Merge	把一条工作线的修改合并到另一条工作线。	检查并同意后，才能将修改合进 main。

History（版本历史） 是项目保存的版本记录；它可以分支，不一定是一条依时间排列的直线。Diff（差异） 比较修改前后的内容。Commit 中的作者名称、时间、说明与识别码有助追查，但作者标签本身不能证明身份。

例如：在 branch 修正一个错字 → 在本机做 commit → push 到 GitHub 的 branch → 提出 PR 请人检查 → 同意后 merge 进 main。每一步有不同用途；PR 不会因此自动合并。

打开原图（新标签页）

想继续查阅，可看 GitHub 官方入门、授权说明与 Git 版本历史。

把改好的文件放上 GitHub

你想修改一份文件，怎么让别人看到？

1. Branch（分支）：开一条自己的修改工作线。
2. 修改与保存：改好文件，保存并检查。
3. git add／Staging Area（暂存区）：选出这次要记录的修改。
4. Commit（版本记录）：在电脑留下一笔修改记录。
5. Push（上传）：把版本送到 GitHub 的分支。
6. PR → Review → Merge：提出修改、检查，确认后合进 main。
7. Pull（获取更新）：把 GitHub 的更新带回电脑。

想自己试一次？看命令

先在自己的练习项目操作，按设置指南装好 Git 并连上 GitHub。

Clone（克隆项目）：把文件与版本历史下载到电脑，见官方步骤。

origin 是这个例子中 GitHub 仓库的名称。先在终端进入项目文件夹，从 main 开始。

git switch -c docs/my-first-update

开好分支后，修改 README.md 并保存，再依次执行：

git status
git diff
git add README.md
git commit -m "docs: clarify the introduction"
git push -u origin docs/my-first-update

到 GitHub 开 PR：来源选 docs/my-first-update，目标选 main。Review（审查）就是检查修改。自己的练习项目可自行检查；合作项目按它的批准规则。

PR 合并后，用 git status 确认没有未提交的修改，再执行：

git switch main
git pull --ff-only

没有别人项目的写入权限？先 Fork，在自己账号创建副本，见官方教程。

看一笔真实修改

看本项目的截图，按红框编号找位置。手机可打开原图放大。

1. Commit：一笔修改记录。 Commit 原页

打开原图（新标签页）

• ① 版本编号（SHA）：找回这一笔版本。
• ② 作者与编写时间：作者栏记录的名字与日期。
• ③ 修改说明（Message）：这次改了什么。
• ④ 分支（Branch）：这里显示 main 分支。
• ⑤ 更改文件数：这笔改了 10 个文件。
• ⑥ 前后差异（Diff）：绿色＋是新增的文字。

2. PR：请人检查修改。 PR #343 原页

打开原图（新标签页）

• ① PR 标题与编号：这个修改提案的编号。
• ② 来源分支（from）：修改从这条分支来。
• ③ 目标分支（into）：修改要合进 main。
• ④ 讨论、版本、检查、差异：看讨论、版本、检查和差异。
• ⑤ 已合并（Merged）：紫色 Merged：已合并。

3. Issue：提出问题。 Issue #314 原页

打开原图（新标签页）

• ① 问题标题与编号：用一句话说出问题。
• ② 状态（Closed）：已结束跟踪，不一定修好了。
• ③ 问题描述：做了什么？发生了什么？
• ④ 受影响的文件：指出出问题的文件。

再认识几个小区别

• 作者（Author）是修改的作者；提交者（Committer）是记录版本的人，两者可能不同。
• Commit 时间不是 Push 上传时间。
• 红框是教学标记；Diff 的红色减号才表示删除。
• Checks 看自动检查；Conversation 看讨论；Files changed 看差异。
• PR 编号与 Commit 的版本编号是不同的东西。

🛠 动手练习：做一个 GitHub 数据小工具

成果： 让 Python 从 GitHub 获取公开数据，把结果显示在屏幕上、写入文件，再用 Git 保存。这项主要练习不需要账号、API token 或付费服务。

先花五分钟用浏览器观察：打开本项目，找出 README、License 和 Issues，再打开 commit 历史，选一笔查看作者、时间、说明、识别码与 diff。公开显示的作者 email 是记录中的标签，不是登入凭证，也不能单凭它验证作者身份。不需要建立 Issue 或 PR。

1. 创建程序

创建一个新文件夹。把下面内容保存为 github_profile.py：

import json
import sys
from pathlib import Path
from urllib.request import Request, urlopen

if hasattr(sys.stdout, "reconfigure"):
    sys.stdout.reconfigure(encoding="utf-8", errors="replace")

url = "https://api.github.com/users/torvalds"
request = Request(url, headers={"User-Agent": "stage-0-practice"})

with urlopen(request, timeout=10) as response:
    profile = json.load(response)

result = f"{profile['login']} 有 {profile['followers']} 位关注者"
print(result)
Path("result.txt").write_text(result + "\n", encoding="utf-8")

API 是程序获取数据的入口。JSON 是这次收到的数据格式。

2. 运行程序

在终端进入该文件夹，然后运行：

python github_profile.py

屏幕会显示账号和关注者数量。文件夹里也会多出 result.txt。关注者数量会变化。不需要和别人的屏幕一样。

3. 用 Git 保存成果

git init
git add github_profile.py result.txt
git commit -m "Add GitHub profile checker"

如果 Git 第一次要求姓名或 email，按屏幕提示设置后，再运行一次 git commit。这些信息是版本的作者标签，不是密码。

✅ 完成检查

• 终端显示 GitHub 账号和关注者数量。
• result.txt 中有相同结果。
• git log --oneline 能看到刚才的 commit，也能在项目的 History 找到一笔修改及其 Diff。
• 程序和 commit 中没有密码或 API token。

四项都完成后，就可以前往 Stage 1 — LLM 基础。如果卡住，展开下面最接近问题的部分。不必一次读完。

⏱️ 展开时间、环境与这一关存在的原因

时间： 完全不熟时预留 1–2 周，约 5–15 小时。已经会其中几项的话，只补不熟的部分。

环境： 准备仍受支持的 Python 3、Git、文本编辑器和终端。终端就是输入文字指令的窗口。Windows 可以使用 PowerShell。macOS 或 Linux 可以使用系统终端。

先确认工具可以运行：

python --version
git --version

后面的 AI agent 教材会直接使用 Python、Git、命令行和配置文件。Stage 0 不会教完所有内容。它只帮助你找出不熟的地方，再告诉你去哪里补充。

🧰 展开 Python、Git、命令行与 YAML／JSON 补充练习

只做你还不熟的项目：

1. Python： 把主要练习 URL 里的 torvalds 换成自己的 GitHub 账号或其他公开账号。确认程序仍能读出 login 和 followers。
2. Git： 创建一个新 branch（不直接修改原版本的工作线），修改输出文字，再做一次 commit。接着把练习放到自己的远程 Git 项目，并运行 git push。
3. 命令行： 创建 src、tests、docs 三个文件夹。从不同路径运行主要练习，并找出 result.txt 实际写到哪里。
4. JSON： 把 API 响应保存成文件，找出 name、public_repos 和 followers 三个字段。
5. YAML： 创建一个含有 username 和 output_file 的小配置文件，练习缩进、字符串和布尔值。YAML 对空格很敏感。不要使用 Tab 缩进。

遇到错误时，先读最后一行错误信息。再确认当前文件夹、文件名和 Python 版本。一次只改一件事。这样才能知道哪个修改有效。

🔐 展开选修：安全地体验 GitHub API 验证

主要练习不需要 token。Token 是一串让 GitHub 认出你的秘密文字。只有想理解“登录后的 API”时才做这一题。

1. 按 GitHub 官方说明 创建 fine-grained personal access token。Fine-grained 表示你可以只开放需要的权限。
2. 使用最短的有效期限，不加入额外权限。GET /user 对 fine-grained token 不要求任何权限。
3. 把 token 放进环境变量 GITHUB_TOKEN。环境变量是电脑暂时保存数据、让程序读取的位置。不要把 token 写进 Python、Markdown、截图、终端历史或 Git commit。
4. 调用 https://api.github.com/user 两次。第一次不带 token，应返回 401，意思是尚未登录。第二次带 token，应返回 200，意思是 GitHub 接受了请求。
5. 练习结束后，回到 GitHub 设置页撤销 token，并清除环境变量。

Bash 可以这样避免把输入显示在屏幕上：

read -s GITHUB_TOKEN && export GITHUB_TOKEN
curl -sS -o /dev/null -w "无 token: %{http_code}\n" \
  -H "Accept: application/vnd.github+json" \
  https://api.github.com/user
curl -sS -o /dev/null -w "有 token: %{http_code}\n" \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Accept: application/vnd.github+json" \
  https://api.github.com/user
unset GITHUB_TOKEN

PowerShell 7.1 以上可以这样做：

$env:GITHUB_TOKEN = Read-Host -MaskInput "Paste token"
$withoutToken = Invoke-WebRequest -Uri https://api.github.com/user `
  -Headers @{ Accept = "application/vnd.github+json" } `
  -SkipHttpErrorCheck
$withToken = Invoke-WebRequest -Uri https://api.github.com/user -Headers @{
  Authorization = "Bearer $env:GITHUB_TOKEN"
  Accept = "application/vnd.github+json"
} -SkipHttpErrorCheck
"无 token: $($withoutToken.StatusCode)"
"有 token: $($withToken.StatusCode)"
Remove-Item Env:GITHUB_TOKEN

Token 就像程序使用的临时钥匙。拿到它的人可能以你的身份操作。所以权限越少、期限越短越安全。

🗺️ 展开名词与 Agent 全景补充

• CLI（命令行接口）： 在终端输入文字指令来操作电脑。
• API（应用程序接口）： 让两个程序按固定规则交换数据的入口。
• JSON／YAML： 用文本保存结构化数据的两种格式。JSON 常见于 API。YAML 常见于配置文件。
• Git： 记录文件版本的工具。commit 是一次带说明的版本快照。

看到其他不懂的词，先查术语表。想知道 agent 为什么可能出现在终端、聊天软件或设备上，再看Agent 全景地图。这两份都不是开始主要练习前的必读内容。

🎯 精选学习资源

需要补哪一项能力时，再找对应入口。不用把 18 个资源全部读完。

学习资源与 GitHub 验证指引核查：2026-08-27 UTC

推荐度 是学习优先顺序，不是 GitHub 的热门数字。按照项目规则，⭐⭐⭐⭐⭐ 代表“没有它就会卡住”；下面都是补充资源，所以诚实使用 ⭐⭐⭐⭐（强烈推荐）或 ⭐⭐⭐（扎实参考），不用假五星。

主题	资源	适合谁	推荐度	为什么推荐／备注
Python	Python Crash Course	想跟着一本书从头练习	⭐⭐⭐⭐	代码免费并配有练习；完整教材需要购买书籍。
	Real Python	学过一点，想查一个问题	⭐⭐⭐⭐	文章按主题分开，遇到问题时容易查找。
	Corey Schafer YouTube	喜欢看英文视频	⭐⭐⭐	用视频从基础语法讲到实际应用。
	Boot.dev	喜欢一边操作一边学	⭐⭐⭐	部分内容免费；完整后端路线需要付费。
	Python 官方繁体中文教程	做完第一次练习，想查正确语法	⭐⭐⭐⭐	官方参考资料；它预期你已经懂一点编程。
Git	Pro Git book	想完整理解 Git	⭐⭐⭐⭐	免费的完整参考书。
	Atlassian Git Tutorials	想用图看懂 branch、merge 和操作顺序	⭐⭐⭐⭐	用图解说明常见工作流程。
	Pro Git — Undoing Things	Git 操作出错，想安全恢复	⭐⭐⭐⭐	先说明哪些操作可能丢失资料，再教你如何恢复。
	git-flight-rules	基本方法不够，想查更多问题	⭐⭐⭐	收录更多 Git 问题与处理方式。
CLI／Shell	The Art of Command Line	想有顺序地学命令行	⭐⭐⭐⭐	从新手指令一路介绍到较进阶的操作。
	Microsoft Learn — PowerShell	使用 Windows，想从第一步开始	⭐⭐⭐⭐	Microsoft 官方的 PowerShell 入门教材。
	tldr pages	只想先看一个指令怎么用	⭐⭐⭐⭐	用短小、可复制的例子解释常用指令。
REST API	MDN — HTTP	想知道 API 背后怎么传资料	⭐⭐⭐⭐	Mozilla 维护的 HTTP 参考资料。
	Postman Learning Center	想用图形界面试 API	⭐⭐⭐⭐	不用先写程序，也能看到发送的内容和收到的资料。
	HTTPie	想从命令行调用 API	⭐⭐⭐	指令通常比原始 curl 写法更容易阅读。
YAML／JSON	YAML 官网	需要查 YAML 的正确写法	⭐⭐⭐	语法和正式规范的官方入口。
	JSON 介绍	第一次接触 JSON	⭐⭐⭐⭐	用短例子说明 JSON 怎么装资料。
	jq	想从命令行整理 JSON	⭐⭐⭐⭐	可以筛选和整理 API 返回的资料。

---

✅ 完成 Stage 0 了吗？ 接着前往 Stage 1 — LLM 基础，完成第一次 LLM API 调用，并学习 token、context window 与成本估算。