# Stage 0 — 基础准备（Foundations） > [繁體中文](./00-foundations.md) | [English](./00-foundations.en.md) | **简体中文** 这一关先检查你是否会用后面一定会用到的四种工具。会的话就直接跳过。不会也没关系。照着下面的小练习做一次即可。 ## 何时可以跳过这个阶段 看看下面四件事。你不需要背指令。但你要能自己查资料并完成： - [ ] 用 **Python** 向 **API** (Application Programming Interface) 拿公开资料，再从 **JSON** (JavaScript Object Notation) 里找出一个值。 - [ ] 用 **Git** 复制专案（clone）、开工作线（**branch**）、保存版本（**commit**），再把版本送到网络上（**push**）。两次修改撞在一起时，知道要留下什么（合并冲突）。 - [ ] 用 **CLI（命令行界面）** 切换资料夹、建立文件并执行 Python 程序。 - [ ] 看懂 **YAML** 与 JSON。它们都是用文字保存资料的格式。 四项都能做到，就直接前往 [Stage 1 — LLM 基础](01-llm-basics.zh-Hans.md)。只要有一项不确定，就完成本页的主要练习。需要时再展开补充内容。 ## 📌 学习目标 完成这一关后，你可以： - 让 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 不会因此自动合并。 ![Git 与 GitHub 的修改流程：Branch 和 Commit 在本机保存修改，Push 上传，PR 请人检查，Merge 合并；每笔 Commit 留下可追查的记录。](../resources/diagrams/github-change-flow.zh-Hans.png) 想继续查阅，可看 [GitHub 官方入门](https://docs.github.com/en/get-started/using-github/hello-world)、[授权说明](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/licensing-a-repository)与 [Git 版本历史](https://git-scm.com/book/en/v2/Git-Basics-Viewing-the-Commit-History)。 ### 把改好的文件放上 GitHub 你想修改一份文件，怎么让别人看到？ 1. Branch（分支）：开一条自己的修改工作线。 2. 修改与保存：改好文件，保存并检查。 3. git add／Staging Area（暂存区）：选出这次要记录的修改。 4. Commit（版本记录）：在电脑留下一笔修改记录。 5. Push（上传）：把版本送到 GitHub 的分支。 6. PR → Review → Merge：提出修改、检查，确认后合进 `main`。 7. Pull（获取更新）：把 GitHub 的更新带回电脑。
想自己试一次？看命令 先在自己的[练习项目](https://docs.github.com/en/get-started/using-github/hello-world)操作，按[设置指南](https://docs.github.com/en/get-started/git-basics/set-up-git)装好 Git 并连上 GitHub。 Clone（克隆项目）：把文件与版本历史下载到电脑，见[官方步骤](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository)。 origin 是这个例子中 GitHub 仓库的名称。先在终端进入项目文件夹，从 `main` 开始。 ```bash git switch -c docs/my-first-update ``` 开好分支后，修改 `README.md` 并保存，再依次执行： ```bash 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` 确认没有未提交的修改，再执行： ```bash git switch main git pull --ff-only ``` 没有别人项目的写入权限？先 Fork，在自己账号创建副本，见[官方教程](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project)。
### 看一笔真实修改 看本项目的截图，按红框编号找位置。手机可打开原图放大。 **1. Commit：一笔修改记录。** [Commit 原页](https://github.com/WenyuChiou/awesome-agentic-ai-zh/commit/2956dc0b4960f6fecf5d3ab00f8b89bacc886e18) ![Commit：一笔修改记录](../resources/diagrams/github-commit-example.zh-Hans.png) - ① 版本编号（SHA）：找回这一笔版本。 - ② 作者与编写时间：作者栏记录的名字与日期。 - ③ 修改说明（Message）：这次改了什么。 - ④ 分支（Branch）：这里显示 main 分支。 - ⑤ 更改文件数：这笔改了 10 个文件。 - ⑥ 前后差异（Diff）：绿色＋是新增的文字。 **2. PR：请人检查修改。** [PR #343 原页](https://github.com/WenyuChiou/awesome-agentic-ai-zh/pull/343) ![PR：请人检查修改](../resources/diagrams/github-pr-example.zh-Hans.png) - ① PR 标题与编号：这个修改提案的编号。 - ② 来源分支（from）：修改从这条分支来。 - ③ 目标分支（into）：修改要合进 main。 - ④ 讨论、版本、检查、差异：看讨论、版本、检查和差异。 - ⑤ 已合并（Merged）：紫色 Merged：已合并。 **3. Issue：提出问题。** [Issue #314 原页](https://github.com/WenyuChiou/awesome-agentic-ai-zh/issues/314) ![Issue：提出问题](../resources/diagrams/github-issue-example.zh-Hans.png) - ① 问题标题与编号：用一句话说出问题。 - ② 状态（Closed）：已结束跟踪，不一定修好了。 - ③ 问题描述：做了什么？发生了什么？ - ④ 受影响的文件：指出出问题的文件。
再认识几个小区别 - 作者（Author）是修改的作者；提交者（Committer）是记录版本的人，两者可能不同。 - Commit 时间不是 Push 上传时间。 - 红框是教学标记；Diff 的红色减号才表示删除。 - Checks 看自动检查；Conversation 看讨论；Files changed 看差异。 - PR 编号与 Commit 的版本编号是不同的东西。
## 🛠 动手练习：做一个 GitHub 数据小工具 **成果：** 让 Python 从 GitHub 获取公开数据，把结果显示在屏幕上、写入文件，再用 Git 保存。这项主要练习不需要账号、API token 或付费服务。 先花五分钟用浏览器观察：[打开本项目](https://github.com/WenyuChiou/awesome-agentic-ai-zh)，找出 README、License 和 Issues，再打开 commit 历史，选一笔查看作者、时间、说明、识别码与 diff。公开显示的作者 email 是记录中的标签，不是登入凭证，也不能单凭它验证作者身份。不需要建立 Issue 或 PR。 ### 1. 创建程序 创建一个新文件夹。把下面内容保存为 `github_profile.py`： ```python 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. 运行程序 在终端进入该文件夹，然后运行： ```bash python github_profile.py ``` 屏幕会显示账号和关注者数量。文件夹里也会多出 `result.txt`。关注者数量会变化。不需要和别人的屏幕一样。 ### 3. 用 Git 保存成果 ```bash 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 基础](01-llm-basics.zh-Hans.md)。如果卡住，展开下面最接近问题的部分。不必一次读完。
⏱️ 展开时间、环境与这一关存在的原因 **时间：** 完全不熟时预留 1–2 周，约 5–15 小时。已经会其中几项的话，只补不熟的部分。 **环境：** 准备仍受支持的 Python 3、Git、文本编辑器和终端。终端就是输入文字指令的窗口。Windows 可以使用 PowerShell。macOS 或 Linux 可以使用系统终端。 先确认工具可以运行： ```bash 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 官方说明](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) 创建 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 可以这样避免把输入显示在屏幕上： ```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 以上可以这样做： ```powershell $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 是一次带说明的版本快照。 看到其他不懂的词，先查[术语表](../resources/glossary.zh-Hans.md)。想知道 agent 为什么可能出现在终端、聊天软件或设备上，再看[Agent 全景地图](../resources/agent-paradigms.zh-Hans.md)。这两份都不是开始主要练习前的必读内容。
## 🎯 精选学习资源 需要补哪一项能力时，再找对应入口。不用把 18 个资源全部读完。 学习资源与 GitHub 验证指引核查：2026-08-27 UTC `推荐度` 是学习优先顺序，不是 GitHub 的热门数字。按照项目规则，⭐⭐⭐⭐⭐ 代表“没有它就会卡住”；下面都是补充资源，所以诚实使用 ⭐⭐⭐⭐（强烈推荐）或 ⭐⭐⭐（扎实参考），不用假五星。
主题资源适合谁推荐度为什么推荐／备注
PythonPython Crash Course想跟着一本书从头练习⭐⭐⭐⭐代码免费并配有练习；完整教材需要购买书籍。
Real Python学过一点，想查一个问题⭐⭐⭐⭐文章按主题分开，遇到问题时容易查找。
Corey Schafer YouTube喜欢看英文视频⭐⭐⭐用视频从基础语法讲到实际应用。
Boot.dev喜欢一边操作一边学⭐⭐⭐部分内容免费；完整后端路线需要付费。
Python 官方繁体中文教程做完第一次练习，想查正确语法⭐⭐⭐⭐官方参考资料；它预期你已经懂一点编程。
GitPro Git book想完整理解 Git⭐⭐⭐⭐免费的完整参考书。
Atlassian Git Tutorials想用图看懂 branch、merge 和操作顺序⭐⭐⭐⭐用图解说明常见工作流程。
Pro Git — Undoing ThingsGit 操作出错，想安全恢复⭐⭐⭐⭐先说明哪些操作可能丢失资料，再教你如何恢复。
git-flight-rules基本方法不够，想查更多问题⭐⭐⭐收录更多 Git 问题与处理方式。
CLI／ShellThe Art of Command Line想有顺序地学命令行⭐⭐⭐⭐从新手指令一路介绍到较进阶的操作。
Microsoft Learn — PowerShell使用 Windows，想从第一步开始⭐⭐⭐⭐Microsoft 官方的 PowerShell 入门教材。
tldr pages只想先看一个指令怎么用⭐⭐⭐⭐用短小、可复制的例子解释常用指令。
REST APIMDN — HTTP想知道 API 背后怎么传资料⭐⭐⭐⭐Mozilla 维护的 HTTP 参考资料。
Postman Learning Center想用图形界面试 API⭐⭐⭐⭐不用先写程序，也能看到发送的内容和收到的资料。
HTTPie想从命令行调用 API⭐⭐⭐指令通常比原始 curl 写法更容易阅读。
YAML／JSONYAML 官网需要查 YAML 的正确写法⭐⭐⭐语法和正式规范的官方入口。
JSON 介绍第一次接触 JSON⭐⭐⭐⭐用短例子说明 JSON 怎么装资料。
jq想从命令行整理 JSON⭐⭐⭐⭐可以筛选和整理 API 返回的资料。
--- > ✅ **完成 Stage 0 了吗？** 接着前往 [**Stage 1 — LLM 基础**](01-llm-basics.zh-Hans.md)，完成第一次 LLM API 调用，并学习 token、context window 与成本估算。