企业官网建设流程全解析

• 教程
• 文档
• AI Agent
• 人工智能
• 大模型

本文对应仓库中的 stages/00-foundations.en.md（繁中原版为 stages/00-foundations.md）。Stage 0 是 awesome-agentic-ai-zh 学习地图的「可跳过准备关卡」（prerequisite gateway），它不教完整教程，而是用一个无需账号、无需 API token、无需付费的整合练习，同时检验 Python、Git、命令行与 YAML/JSON 四类技能——这些正是后续所有 Stage（从 LLM API 调用、Agent Loop 到多智能体系统）都会直接使用的基础设施。

读完本篇，你将能够：用 Python 从公开 API 取数据并解析 JSON、在终端中运行脚本并定位输出文件、用 Git 保存版本并处理合并冲突、识别 YAML 与 JSON 配置格式，并安全地理解 API token 的边界。

这一关在整张学习地图中的位置

在 stages/DESIGN.md 的「Stage 0 為什麼可以 skip」一节中，维护者明确写下了这个阶段的定位：

Stage 0 不是 stage——它是 prerequisite gateway。

• 已经会 Python / Git / CLI / JSON 的人 → 直接进入 Stage 1 — LLM 基础；
• 不会的人 → 用一个小工具同时练 Python、API、JSON、CLI 与 Git，避免在后续阶段被基础设施卡住。

全站学习顺序（Stage 0 → Stage 1 → Stage 2为共用基础）也在 README.md 中有明确入口：完全没写过代码的读者从 Stage 0 开始，零基础环境准备可搭配 resources/setup-guide.en.md。同时，脚本 scripts/check-stage-template.py 明确将 Stage 0 排除在标准章节模板检查之外——因为它刻意采用「短 intro + 可跳过判断」的结构，而不是完整的章节模板。

核心原则：这一关不需要你背命令，只需要你能自己查资料并完成任务。它的产出是能力清单，而不是记忆量。

何时可以跳过这一关：四项自查

打开这一关后，先做四项能力自查。每一项都对应后续 Agent 课程真实会用到的工具：

四者都熟练 → 直接跳往 Stage 1 — LLM 基础。只要有一项不确定，就完成本页的主练习，需要时再展开补充小节。

📌 学习目标

完成这一关后，你能够：

• 让 Python 从 API 拿数据，再读出 JSON 里需要的部分；
• 从终端运行程序，并找到程序创建的文件；
• 用 Git 保存一个版本，需要时可以回到这个版本；
• 认出 YAML、JSON 与 API token（让程序登录的秘密文字），知道哪些内容绝不能公开。

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

成果目标：让 Python 从 GitHub 拿公开数据，把结果显示在画面上、写进文件，再用 Git 保存。整个过程不需要账号、API token 或付费服务。

第 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']} has {profile['followers']} followers" print(result) Path("result.txt").write_text(result + "\n", encoding="utf-8")

这段代码里已经包含后续课程反复出现的三个核心动作：

1. 构造 HTTP 请求：Request(url, headers={"User-Agent": ...})设置了请求头。GitHub API 要求提供User-Agent，否则请求会被拒绝——这也是为什么它被显式写出来。
2. 解析 JSON：json.load(response)把响应体（JSON 文本）转成 Python 字典，随后通过profile['login']、profile['followers']取值。API（Application Programming Interface）是程序获取数据的入口，JSON（JavaScript Object Notation）是这次收到的数据格式。
3. 写文件：Path("result.txt").write_text(...)用 UTF-8 编码把结果落盘，为下一步的 Git 提交准备内容。

环境注意：Windows 终端使用 PowerShell，macOS/Linux 使用系统终端。sys.stdout.reconfigure处理了某些系统下中文/特殊字符的输出编码问题，保证跨平台一致。

第 2 步：运行程序

在终端进入该文件夹并执行：

python github_profile.py

画面会显示类似torvalds has 123456 followers的账号与粉丝数，文件夹里同时多出result.txt。粉丝数是动态数据，你的屏幕不需要与别人一致——这本身就是验证「从实时 API 取数据」成功的方式。

第 3 步：用 Git 保存成果

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

• git init把当前文件夹变成 Git 仓库；
• git add把两个文件放入暂存区；
• git commit保存一个带说明的版本快照（commit）。

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

合并冲突的最小认知

在第 2 步的git add与后续练习中，你可能会遇到「两次修改撞在一起」的情况——这就是合并冲突（merge conflict）。此时 Git 会在冲突文件中留下<<<<<<<、=======、>>>>>>>标记，你需要决定保留哪一方的改动（或手动合成两者），再重新git add与git commit。这一关只要求你知道「冲突时该留下什么、怎么手动解决」，不需要背完整合并命令——更系统的解法见 Pro Git 参考资源。

✅ 完成检查

完成主练习后，逐项勾选：

• 终端显示 GitHub 账号与粉丝数；
• result.txt包含相同结果；
• git log --oneline能看到刚才的 commit；
• 程序与 commit 里没有密码或 API token。

四项全部通过，即可前往 Stage 1 — LLM 基础。卡住时，展开下面「只做你不熟的部分」的补充练习即可，不必一次读完。

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

• 时间：完全不熟时预留 1–2 周，约 5–15 小时；已经会其中几项，只补不熟的部分。
• 环境：准备仍受支持的 Python 3、Git、文本编辑器与终端。先确认工具可运行：

python --version git --version

后续 AI agent 课程会直接使用 Python、Git、命令行与配置文件。Stage 0 不会教完所有内容——它只帮你找出还不熟的地方，并告诉你去哪里补。仓库内的 resources/setup-guide.en.md 为零基础读者提供了 Web / Desktop / IDE / CLI Agent / API 五选一的完整环境搭建入口，需要时可配合使用。

🧰 补充练习：Python、Git、命令行与 YAML/JSON

只做你还不知道的项目：

1. Python：把主练习 URL 中的torvalds换成自己的 GitHub 账号或其他公开账号，确认程序仍能读出login与followers。这验证了「程序逻辑不依赖特定数据源」。

2. Git：建立新分支（不直接改原版本的工作线），修改输出文字，再做一次 commit；然后把练习放到自己的远程 Git 项目并执行git push。练习要点：分支让实验与主线隔离，push才把版本送到线上。

3. 命令行：创建src、tests、docs三个文件夹；从不同路径运行主练习（例如python ../github_profile.py），观察result.txt实际写到哪个目录——这会帮你理解「相对路径」与「当前工作目录」的关系，也是后续所有运行练习的必备直觉。

4. JSON：把 API 响应保存到文件，再找出name、public_repos、followers三个字段。可以直接在 Python 里加一行把原始响应写盘，也可以用命令行工具jq快速验证：

curl -sS -H "User-Agent: stage-0-practice" \ https://api.github.com/users/torvalds | jq '{name, public_repos, followers}'

5. YAML：创建一个包含username与output_file的小配置文件，练习缩进、字符串与布尔值。YAML 对空格敏感，不要用 Tab 缩进。一个最小示例：

# config.yml username: torvalds output_file: result.txt save_json: true

对应读取代码可以是：

import yaml with open("config.yml", encoding="utf-8") as f: config = yaml.safe_load(f) print(config["username"], config["output_file"])

YAML 是后续 Stage 大量配置（如 mkdocs.yml、各范例的requirements.txt与仓库的 scripts/freshness-models.yml）的基础格式，而 JSON 是 API 交换的标准格式——两者都「用文本保存结构化数据」，只是 YAML 更偏人类可读、JSON 更偏程序通用。

排错通用心法：遇到错误时，先读错误信息的最后一行；再确认当前文件夹、文件名与 Python 版本；一次只改一件事，才能知道哪个修改有效。这也是 stages/DESIGN.md 中「一次只改一件事」这一全站练习原则在 Stage 0 的体现。

🔐 选做：安全地体验 GitHub API 验证

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

1. 按 GitHub 官方指南创建fine-grained personal access token（细粒度 token 意味着你只授予需要的权限）；
2. 使用最短的有效期，不添加额外权限（GET /user对 fine-grained token 不要求任何权限）；
3. 把 token 放进环境变量GITHUB_TOKEN。环境变量是电脑暂时保管数据、让程序读取的位置；
4. 调用https://api.github.com/user两次：第一次不带 token，应返回401（未登录）；第二次带 token，应返回200（请求被接受）；
5. 结束后回到 GitHub 设置页撤销 token，并清除环境变量。

安全红线：不要把 token 写进 Python 源码、Markdown、截图、终端历史或 Git commit——它就像一把临时钥匙，拿到的人可以以你的身份操作，因此权限越少、期限越短越安全。

Bash 可以避免把输入显示在画面上：

read -s GITHUB_TOKEN && export GITHUB_TOKEN curl -sS -o /dev/null -w "No token: %{http_code}\n" \ -H "Accept: application/vnd.github+json" \ https://api.github.com/user curl -sS -o /dev/null -w "With 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 "No token: $($withoutToken.StatusCode)" "With token: $($withToken.StatusCode)" Remove-Item Env:GITHUB_TOKEN

注意两条命令的-SkipHttpErrorCheck都用于把 HTTP 错误码当作正常返回值展示，而非抛出异常中断脚本。

🗺️ 名词与 Agent 全景速记

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

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

🎯 精选学习资源

需要补某一项能力时再找对应入口；不需要把 18 个资源全部读完。下表保留原文档的主题、适用人群、推荐度与备注，原文链接请回到 stages/00-foundations.en.md 中直接访问。

推荐度是学习优先级，不是 GitHub 热门数字。按项目规则，⭐⭐⭐⭐⭐ 代表「不看会卡住」；以下是补充资源，因此诚实使用 ⭐⭐⭐⭐（强烈建议）或 ⭐⭐⭐（扎实参考），不使用虚假五星。

学习资源与 GitHub 验证指引查核时间：2026-08-27 UTC（来自原文档的 freshness marker）。

下一步：进入 Stage 1

走完 Stage 0 后，前往Stage 1 — LLM 基础，完成第一次 LLM API 调用，并学习 token、context window 与成本估算。届时你已经拥有的四项基础能力——Python 取数、JSON 解析、终端运行、Git 版本管理——将全部派上用场：Stage 1 的第一次 API 调用就是「用 Python 请求一个接口并解析 JSON 响应」的翻版，只是数据源从 GitHub 换成了模型服务。

仓库中更多可执行的后续范例都位于 examples 目录，每个范例文件夹同时提供 Ollama 本机路径（Path A）与 Anthropic 云端路径（Path B）以及离线测试，方便你在不同预算与隐私偏好下继续练习。

• 教程
• 文档
• AI Agent
• 人工智能
• 大模型