社团培训 on 望境

Agent 与 Vibe Coding：从想法到可验证交付

Mon, 21 Sep 2026 11:00:00 +0800

版本：v1.0.0 适用对象：希望用 Coding Agent 辅助真实开发的初学者示例工具：通用方法为主，Codex 为操作示例最后核验：2026-09-21

学习目标

完成本教程后，你应该能够：

区分聊天助手、Coding Agent、Agentic Coding 与 Vibe Coding；
判断什么任务适合交给 Agent，什么任务必须谨慎或禁止自动执行；
用“目标、上下文、约束、完成条件”写出可执行任务；
通过计划、权限、测试和 Diff 审查控制 Agent 工作；
识别幻觉、需求漂移、提示词注入、秘密泄露和依赖风险；
把“代码生成了”变成“结果有证据、可审查、可回退”。

配套材料：

一、四个容易混淆的概念

1.1 聊天助手

聊天助手主要根据对话生成解释、建议或代码片段。它可以告诉你“应该修改哪里”，但通常不会自动读取整个仓库、执行命令、观察错误并继续修正。

1.2 Coding Agent

Coding Agent 不只是回答问题，还能在被授予的环境中使用工具：读取文件、搜索代码、修改内容、运行构建和测试，再根据结果继续工作。它形成的是“观察—行动—反馈”循环。

工具能力扩大了效率，也扩大了风险。一个只能给建议的模型说错了，你可以不复制；一个拥有写权限和终端的 Agent 判断错了，可能直接改变文件。因此权限、范围和验收比“提示词是否优美”更重要。

1.3 Agentic Coding

Agentic Coding 是一种开发方式：人定义目标与边界，Agent 承担有工具反馈的多步执行，人通过计划、测试、审查和批准保持控制。重点不是让 Agent 独自写更多代码，而是让整个过程可以检查。

1.4 Vibe Coding

Vibe Coding 通常指用自然语言快速表达想法，让 AI 大量生成和迭代代码，人在早期更关注体验与方向，而不是逐行编写。

它有两种截然不同的用法：

探索方式：快速做原型、验证交互、比较设计方向，失败成本可控；
交付方式：把生成结果直接用于真实用户、生产数据或基础设施，却没有理解、测试与审查。

前者可以很高效，后者风险很高。问题不在“凭感觉开始”，而在“凭感觉结束”。

二、Agent 能做什么，不能替你承担什么

Agent 擅长	人必须负责
快速搜索陌生仓库	确认真正目标与优先级
生成重复结构和初稿	决定产品、伦理与业务边界
运行构建、测试和静态检查	授予权限并承担外部影响
根据错误日志反复修正	判断测试是否足以证明正确
总结差异和风险	审查最终 Diff 与发布决定

Agent 可以报告“测试通过”，但人仍要确认：运行的是不是正确测试？是否跳过了失败？测试是否覆盖真实需求？环境是否与生产一致？

在高影响领域——身份认证、支付、医疗建议、法律结论、生产数据库、密钥、权限、基础设施——不能只凭生成结果接受改动。应增加领域专家、独立测试、变更审批和可回退发布。

三、把模糊想法变成任务契约

官方 OpenAI 文档给出的实用默认结构是：Goal、Context、Constraints、Done when。中文可以写成目标、上下文、约束、完成条件。

3.1 一个过于模糊的请求

`1`	`帮我把网站做得更好看、更专业。`

Agent 不知道“专业”意味着什么，也不知道哪些文件能改、是否允许装框架、怎样验证完成。它只能猜。

3.2 一个可执行的请求

## 目标
为 Hugo 技术手记首页增加“学习主题”区块，展示 Web、服务器、Agent 三张卡片。

## 上下文
- 工作目录：development/web-development/example/hugo-tech-notes
- 首页模板：layouts/home.html
- 样式：static/css/main.css
- 项目不使用主题、Node.js 或前端框架。

## 约束
- 不修改现有文章内容和 GitHub Pages 工作流。
- 使用语义化 HTML；键盘焦点可见。
- 720px 以下为单列，宽屏为三列。
- 不安装依赖，不访问外部服务，不执行发布。

## 完成条件
- `hugo --minify --cleanDestinationDir` 成功。
- 首页生成三张卡片，移动端无横向滚动。
- `git diff` 只包含首页模板与必要样式。
- 汇报验证结果、未验证项和风险。

这不是为了限制创造力，而是把不能靠猜测的决策说清楚。可直接复制配套的 agent-task-brief.md 填写。

3.3 完成条件必须能观察

“代码质量高”“体验很好”无法直接判定。更好的完成条件包括：

某个命令退出码为 0；
页面在指定宽度没有溢出；
错误输入返回明确提示；
新增行为由测试覆盖；
最终 Diff 不包含指定目录；
文档链接均能解析到存在的文件。

主观质量仍然重要，但要安排人工验收，而不是假装它已经被自动证明。

四、从计划到验收的闭环

图 1：任务不是在 Agent 生成代码时结束，而是在证据充分、差异可解释并由人接受时结束。

4.1 先探索，再计划

对于跨多个文件、需求含糊或风险较高的任务，先让 Agent只读探索：

项目入口在哪里？
当前实现采用什么结构？
有哪些测试、构建和部署约定？
是否存在 AGENTS.md、README 或贡献指南？
当前工作区是否有用户未提交的修改？

计划应该说明修改行为、数据流、验证方式和边界，而不是只列文件名。若关键产品选择仍不明确，应在动手前询问。

在 Codex 中，复杂任务可以先使用 Plan 模式，让工具收集上下文、澄清问题并形成实施计划。具体入口和快捷键可能随界面更新，以当前官方说明为准。

4.2 小步实现

一次修改越大，错误越难定位。更稳妥的顺序是：

建立最小可运行改动；
运行最接近改动的检查；
观察结果并修正；
再扩展下一块；
最后运行完整检查并审阅 Diff。

Agent 应保存用户现有改动，不应为了“回到干净状态”擅自重置工作区。遇到冲突时先报告重叠，而不是覆盖。

4.3 验证不是一句话

一个可信的验证报告至少包含：

执行了什么命令；
命令是否成功，关键输出是什么；
哪些行为被覆盖；
哪些行为因缺少环境、账号或数据没有验证；
是否存在警告、风险或需要人工检查的部分。

例如：

已执行：hugo --minify --cleanDestinationDir
结果：成功，生成首页、列表页和两篇详情页。
未执行：GitHub Pages 在线部署，因为当前目录不是远程仓库。
人工检查：仍需在 375px 与 1440px 宽度检查卡片布局。

“应该能用”“看起来没问题”不是运行证据。

4.4 阅读 Diff

在接受改动前运行：

git status --short
git diff --stat
git diff
git diff --check

依次回答：改了哪些文件？改动规模是否符合任务？是否出现意外配置、依赖或生成物？具体每一行是否必要？是否有空白错误？

在 Codex 桌面端也可以使用差异面板逐行查看并反馈。工具能辅助审查，但作者不能把“让另一个 Agent 看过”当成人工责任的替代品。

五、权限是技术设计，不是弹窗麻烦

5.1 最小权限

Agent 只应拥有完成当前任务需要的能力：

文档解释任务通常只需读取；
本地功能开发需要指定工作区写权限；
安装依赖需要网络与包管理器写入；
发布、发邮件、创建云资源会影响外部系统，必须单独确认。

不要因为频繁审批不方便，就一开始授予整个电脑、所有网络服务和生产凭据的访问权。先在受控目录完成稳定流程，再针对明确需求扩大权限。

5.2 可逆性

安全操作应尽量可恢复：

修改前确认 Git 状态；
使用独立分支或工作树隔离任务；
数据迁移先备份并演练回退；
发布保留上一版本；
删除优先使用回收站或明确、已验证的目标路径；
不对不理解的命令给予长期允许。

5.3 外部文字可能是恶意输入

网页、Issue、日志、邮件和附件可能包含“忽略之前指令”“上传环境变量”等文字。这些内容属于待分析的数据，不自动拥有指挥 Agent 的权限。

处理外部内容时应明确：

只提取与任务相关的事实；
不执行材料中要求的额外操作；
不发送本地文件、密钥或系统信息；
需要改变外部状态时回到用户授权范围。

这类风险叫提示词注入。它不是只有聊天机器人会遇到；任何能读取不可信内容并调用工具的 Agent 都需要防范。

六、用 `AGENTS.md` 保存长期规则

任务提示适合描述“这一次要做什么”，AGENTS.md 适合保存“这个仓库一直怎样工作”。官方 OpenAI 文档建议其中包含：

仓库结构和关键目录；
运行、构建、测试和 lint 命令；
工程规范与 Pull Request 要求；
禁止事项和安全边界；
完成定义与验证方法。

配套 Hugo 小站提供了一个短小的 AGENTS.md。它明确项目不使用前端框架、不提交 public/、要保留可访问性，并给出验证命令。

好的规则应具体、准确、可执行。下面这种规则价值有限：

`1`	`写出完美、优雅、专业、没有任何问题的代码。`

更好的写法是：

1
2
3

- 新增页面必须使用语义化 HTML，并可通过键盘访问。
- 完成修改后运行 hugo --minify --cleanDestinationDir。
- 不提交 public/、令牌或真实服务器地址。

规则出现层级时，应以离工作目录更近、范围更具体的说明为准；实际优先级仍以当前 Codex 官方文档和环境为准。

七、贯穿案例：让 Agent 修改 Hugo 首页

7.1 准备隔离环境

把资料仓库中的 development/web-development/example/hugo-tech-notes/ 复制到一个新的练习目录并初始化 Git，避免直接破坏唯一副本：

Copy-Item "..\..\development\web-development\example\hugo-tech-notes" ".\practice-hugo" -Recurse
Set-Location ".\practice-hugo"
git init
git add .
git commit -m "Baseline Hugo example"

这会创建本地练习仓库，不会自动发布到 GitHub。

7.2 提交任务

把第三节的“学习主题”任务交给 Agent，并明确：先检查 AGENTS.md 和当前实现，复杂处先计划，禁止安装依赖与发布。

观察 Agent 是否：

先读取目录和现有模板；
注意到 AGENTS.md；
只修改必要文件；
运行 Hugo 构建；
如实报告无法完成的视觉检查。

7.3 人工验收

hugo --minify --cleanDestinationDir
git status --short
git diff --check
git diff

然后运行 hugo server -D，在窄屏和宽屏打开页面，使用键盘遍历链接与按钮。填写 review-checklist.md。

若发现问题，用证据反馈：

1
2
3

在 375px 宽度下，第三张卡片导致页面横向滚动。Elements 显示
.topic-card 设置了 min-width: 420px。请移除固定最小宽度，保持宽屏三列，
然后重新构建并说明修改后的验证结果。不要改文章内容。

具体症状、环境、定位证据和边界比“还是不对，再改改”更容易得到稳定结果。

八、七类高频风险

8.1 幻觉

Agent 可能编造不存在的文件、参数、API 或测试结果。应让它先搜索真实项目，并要求提供命令与结果。涉及最新产品、版本和平台界面时查官方文档。

8.2 需求漂移

“顺手优化”可能演变成重构、换框架、升级依赖。通过明确禁止项、限制文件范围和检查 Diff 控制漂移。

8.3 能构建不等于正确

编译或构建只能证明某些语法和依赖成立，不能证明交互、业务语义、可访问性和安全。验收标准要覆盖用户能观察到的行为。

8.4 秘密泄露

不要把 .env、SSH 私钥、云密钥、Cookie 或生产数据库内容直接交给 Agent。日志也可能包含令牌。提交前进行秘密扫描并阅读 Diff。

8.5 破坏性操作

删除、强制推送、覆盖配置、数据库迁移和生产部署都可能难以恢复。要求 Agent 先解析精确目标、备份、说明影响并等待必要批准。

8.6 未审查依赖

Agent 可能为了一个小功能安装多个包。每个新依赖都增加供应链、许可证、体积和维护成本。先问原生能力是否足够，再核对包名、来源、版本与锁文件差异。

8.7 自动化错误被放大

一次手工错误影响一个任务；定时任务或批量 Agent 可能重复错误。流程应先手工稳定，再自动化，并设置范围、停止条件、日志和异常通知。

九、何时适合 Vibe，何时必须收紧

9.1 适合快速探索

一次性原型和视觉方向；
隔离环境中的学习项目；
可轻易删除的脚手架；
多个方案的低成本比较；
没有真实用户数据的演示。

即使如此，也应限制目录与权限，避免泄露本机信息。

9.2 必须工程化

真实用户、账号、权限与支付；
生产数据和不可逆迁移；
公网服务器、安全配置与供应链；
医疗、金融、法律等高影响决策；
团队共享基础设施和长期维护系统。

此时需要设计评审、测试策略、安全审查、分阶段发布、监控和回退。自然语言沟通仍然有用，但不能替代工程门禁。

十、常见错误方式

错误 1：只说“帮我做完”

后果是 Agent 自行决定范围、技术栈和完成标准。改用任务契约，并指明相关文件与验证命令。

错误 2：不让 Agent 运行测试

只生成代码会把最低成本的反馈丢掉。允许与任务相符的构建和测试，并要求报告未验证内容。

错误 3：看到绿色就接受

测试可能与需求无关，甚至没有实际执行。查看命令、退出状态、关键输出与 Diff。

错误 4：把所有规则塞进每次提示

重复规则容易遗漏和冲突。稳定的仓库约定放入简洁准确的 AGENTS.md，任务提示只写本次变化。

错误 5：把 Agent 当成责任主体

“AI 写的”不能解释事故。授权发布的人仍要理解风险、审查证据并承担决策责任。

十一、练习

把“做一个博客”改写成包含四要素的任务契约。
为 Hugo 示例站写三条仓库级规则和两条本次任务约束，解释它们为何不应混在一起。
让 Agent 只读分析一次构建失败，不授权写入；检查它是否先收集证据。
人为在任务中加入冲突要求，例如“不能改 CSS”和“必须改变颜色”，观察 Agent 是否澄清。
阅读一个 Agent 生成的 Diff，至少找出功能、测试、安全和可维护性四类检查项。

十二、交付检查清单

任务包含目标、上下文、约束和可观察完成条件。
Agent 的工作目录与权限符合最小范围。
外部网页、Issue、日志和附件被当作不可信数据处理。
没有暴露凭据、个人数据或内部地址。
新依赖确有必要，来源与锁文件变化已检查。
构建、测试、lint 或类型检查实际运行并记录结果。
未验证项被明确列出，没有用推测冒充执行。
git diff 只包含预期修改，用户已有改动得到保留。
高影响操作有批准、备份、分阶段发布和回退方法。
最终结果由能够理解需求与风险的人验收。

十三、小结

Agent 的价值来自它能在真实环境中读取、修改、运行并根据反馈迭代；风险也来自同一能力。可靠使用方法不是寻找一句“万能提示词”，而是建立任务契约、计划、最小权限、小步实现、自动验证、Diff 审查和人工验收。

Vibe Coding 可以让想法更快变成原型，但从原型走向交付时，必须把感觉转化为规格，把生成转化为证据，把权限转化为责任。最值得培养的能力不是让 Agent 写得更多，而是能够判断结果何时可信、何时必须停止。

参考资料

以上官方资料最后核验于 2026-09-21。Codex 的界面、命令和功能成熟度可能变化，操作前应再次查看 OpenAI Docs；本教程刻意不绑定具体模型名称、价格或套餐。

服务器：从网络请求到 Linux 部署

Mon, 21 Sep 2026 10:00:00 +0800

版本：v1.0.0 适用对象：理解基本网页概念、第一次接触 Linux 服务器的读者示例环境：Windows 11 客户端、Ubuntu LTS 服务器、Nginx 最后核验：2026-09-21

验证边界：本教程的配置依据 Ubuntu、Nginx 与 Certbot 官方资料编写，但没有在真实公网主机、域名和防火墙上执行。当前环境也没有安装 Nginx。所有服务器命令都必须在你自己的 Ubuntu 主机上逐步验证；不要把示例当成已经成功的运行记录。

学习目标

完成本教程后，你应该能够：

区分服务器、云服务器、Web 服务器、进程和端口；
解释 DNS、HTTP、HTTPS、正向代理和反向代理；
使用 SSH 密钥连接 Ubuntu，并理解普通用户与 sudo；
用 UFW 只开放必要端口；
用 Nginx 发布 Hugo 静态文件；
在域名解析生效后通过 Certbot配置 HTTPS；
根据状态、日志和网络请求定位部署问题。

一、先建立正确的服务器概念

1.1 服务器既可以指机器，也可以指程序

日常交流中的“服务器”可能有两种含义：

服务器主机：一台持续联网、运行 Linux 的计算机或虚拟机；
服务器程序：等待请求并提供服务的进程，例如 Nginx、数据库或后端 API。

云服务器通常是云平台提供的虚拟机。买到云服务器并不等于网站已经上线：你仍要配置账号、网络规则、Web 服务器、站点文件、域名、证书、更新和备份。

1.2 IP、端口与进程

IP 地址帮助网络找到主机，端口帮助操作系统把连接交给正确进程。常见端口包括：

端口	常见用途	是否应对公网开放
22/TCP	SSH 远程管理	需要管理时开放，最好限制来源并使用密钥
80/TCP	HTTP	公开网站需要，也常用于证书验证和跳转
443/TCP	HTTPS	生产网站通常需要
3000、8000	开发服务器	通常只绑定本机，不直接暴露公网
5432、3306	PostgreSQL、MySQL	除非架构明确要求，否则不要直接暴露公网

“程序启动了”和“公网能访问”是两件事。还要检查程序监听地址、主机防火墙、云平台安全组、DNS 和上游网络。

1.3 DNS 与域名

DNS 把 DOMAIN 解析为服务器 IP。部署单台 IPv4 服务器时，常见做法是创建 A 记录：

1
2
3

名称：notes（或 @）
类型：A
值：SERVER_IP

若服务器配置了可用 IPv6，再添加 AAAA 记录。不要仅因为控制台允许填写就添加错误 IPv6；客户端可能优先尝试它，导致部分用户无法访问。

DNS 有缓存和 TTL，修改不会在所有位置瞬间生效。可在 Windows 查询：

1
2

# 运行环境：Windows PowerShell 7；只读查询
Resolve-DnsName DOMAIN

在 Ubuntu 查询：

1
2

# 运行环境：Ubuntu Bash；只读查询
getent ahosts DOMAIN

只有返回预期地址，才进入证书签发步骤。

二、HTTP、HTTPS 与代理

2.1 HTTP 是请求与响应协议

浏览器可能发送：

1
2
3

GET /posts/ HTTP/1.1
Host: DOMAIN
Accept: text/html

服务器返回状态行、响应头和正文。Nginx 可以直接从磁盘读取 HTML，也可以把请求转发给后端程序。

2.2 HTTPS 增加什么

HTTPS 是在 TLS 安全连接中传输 HTTP，主要提供：

机密性：旁观者不能直接读出传输内容；
完整性：传输内容不容易被悄悄篡改；
身份验证：浏览器依据受信任证书确认访问的域名。

证书不能修复弱密码、过期系统、错误权限或应用漏洞。它只是分层安全中的一层。

2.3 正向代理与反向代理

二者都“代替一方与另一方通信”，但站的位置不同：

正向代理代表客户端访问外部服务，外部服务看到的主要是代理；
反向代理代表服务端接收请求，再转给内部应用，用户通常只看到统一域名。

Nginx 既能直接提供静态文件，也常用作反向代理。例如把公网的 /api/ 请求转发给只监听 127.0.0.1:8000 的应用。本文部署静态 Hugo 站点，因此不需要后端进程。

三、部署拓扑与占位符

图 1：UFW 控制主机端口，Nginx 按域名选择 server block，再读取 Hugo 构建文件。云平台安全组是主机外的另一层，图中未展开。

全文使用以下占位符：

占位符	含义	示例格式，不可直接照搬
`SERVER_IP`	公网 IPv4 地址	`203.0.113.10`
`DOMAIN`	完整域名	`notes.example.com`
`SSH_USER`	日常管理用户	`deploy`
`SITE_ROOT`	Nginx 站点根目录	`/srv/tech-notes/current`
`LOCAL_PUBLIC`	Windows 本地 Hugo 输出	`C:\path\to\public`

文档示例地址 203.0.113.0/24 专门保留用于说明，不是你的服务器。执行命令前先替换占位符，并用 Get-Location、pwd、whoami 确认自己在哪里、以谁的身份操作。

四、第一次连接与 SSH 密钥

4.1 先确认云平台边界

创建主机时至少记录：Ubuntu 版本、公网地址、初始用户名、登录方式和安全组规则。不要在教程、Issue 或聊天记录中公开密码与私钥。

Windows 自带 OpenSSH 客户端。首次连接：

1
2

# 运行环境：Windows PowerShell 7
ssh SSH_USER@SERVER_IP

首次看到主机指纹时，不要无条件输入 yes。应从云控制台或可信渠道核对指纹；否则可能连接到错误主机。

4.2 生成密钥

先检查是否已有密钥，避免覆盖：

`1`	`Get-ChildItem "$env:USERPROFILE\.ssh" -ErrorAction SilentlyContinue`

若确实需要新密钥：

1
2

# 会在用户 .ssh 目录创建密钥；设置可靠口令
ssh-keygen -t ed25519 -C "web-server-admin"

私钥通常是 id_ed25519，不能发送给服务器或他人；.pub 才是公钥。将公钥添加到服务器用户的 ~/.ssh/authorized_keys。Windows 未必提供 ssh-copy-id，可以从云控制台添加，也可以在已登录会话中谨慎粘贴公钥。

完成后另开一个终端验证密钥登录。在验证成功以前，保持当前 SSH 会话，不要急着关闭密码登录或重启 SSH。

4.3 不要直接照抄“关闭密码登录”

SSH 配置错误会把你锁在服务器外。若需要加固，应使用 /etc/ssh/sshd_config.d/ 中的独立片段，先阅读当前 Ubuntu OpenSSH 文档，再按顺序执行：

# 只检查配置语法，不应用更改
sudo sshd -t

# 查看服务状态
sudo systemctl status ssh --no-pager

只有 sshd -t 成功、密钥登录已在第二个会话验证、云控制台有救援入口时，才考虑重新加载服务。本文不提供“一键禁用密码”的命令，因为不同镜像、云初始化和配置优先级可能不同。

五、用户、更新和最小权限

日常部署不应长期直接使用 root。Ubuntu 安装时创建的初始用户通常可通过 sudo 临时获得管理权限。

先做只读检查：

whoami
id
lsb_release -a
sudo -l

更新软件索引与已安装包会改变系统状态，安排维护窗口后执行：

1
2

sudo apt update
sudo apt upgrade

不要在不了解影响时加 -y 自动确认。升级内核或关键服务后可能需要重启；先看提示、确认当前业务和回退能力。

最小权限原则包括：

只给需要的账号 SSH 权限；
应用文件由适当用户维护，Nginx 只需读取；
不把数据库、开发服务器和管理面板随意暴露公网；
不把私钥、云 API Token 或备份放进站点根目录；
定期安装安全更新，并确认更新是否真正生效。

六、配置 UFW 防火墙

Ubuntu 常用 UFW 管理主机防火墙。启用前最重要的一步是保留 SSH 访问。

先检查云安全组和当前状态：

# 只读
sudo ufw status verbose
sudo ufw app list
sudo ss -lntp

用 dry-run 查看将产生的规则：

`1`	`sudo ufw --dry-run allow OpenSSH`

确认无误后，下面命令会修改防火墙：

# 先允许 SSH，避免启用防火墙后失联
sudo ufw allow OpenSSH

# 启用防火墙；保持当前 SSH 会话并另开会话验证
sudo ufw enable
sudo ufw status numbered

此时只放行了 SSH。云安全组和 UFW 都可能拦截连接，排错时要分别检查，不能只看其中一层。安装 Nginx 后再开放 HTTP/HTTPS。

七、安装并检查 Nginx

下面命令会安装软件并启动服务：

1
2

sudo apt update
sudo apt install nginx

确认安装产生了 Nginx 应用配置后，再开放 HTTP 与 HTTPS：

sudo ufw app list
sudo ufw --dry-run allow 'Nginx Full'
sudo ufw allow 'Nginx Full'
sudo ufw status verbose

安装后先在服务器内部检查：

1
2
3

systemctl status nginx --no-pager
curl -I http://127.0.0.1/
sudo ss -lntp | grep ':80'

预期能看到 Nginx 运行、HTTP 响应以及 80 端口监听。随后从 Windows 检查：

`1`	`curl.exe -I http://SERVER_IP/`

如果本机成功、公网失败，重点检查 UFW、安全组和公网地址；如果本机也失败，先看 Nginx 状态与日志。

八、构建和上传 Hugo 站点

8.1 在本地构建

不要把 Hugo 源文件全扔给 Nginx。先在 Windows 构建：

1
2

Set-Location ".\examples\hugo-tech-notes"
hugo --minify --cleanDestinationDir --baseURL "https://DOMAIN/"

检查 public/index.html。生产 baseURL 必须与最终 HTTPS 地址一致。

8.2 在服务器准备目录

本教程使用 /srv/tech-notes/current。创建目录会修改服务器：

1
2
3

sudo mkdir -p /srv/tech-notes/current
sudo chown -R SSH_USER:SSH_USER /srv/tech-notes
sudo chmod -R u=rwX,go=rX /srv/tech-notes

这里让部署用户拥有写权限，其他用户只有读取和进入目录的权限。不要机械使用 chmod -R 777；它把问题掩盖成过度授权。

8.3 上传文件

在 Windows 的 hugo-tech-notes 目录执行：

1
2

# 把 public 目录中的内容递归上传到站点根目录
scp -r ".\public\*" "SSH_USER@SERVER_IP:/srv/tech-notes/current/"

PowerShell 的通配符与隐藏文件行为可能随工具而异。上传后必须在服务器核对：

1
2

find /srv/tech-notes/current -maxdepth 2 -type f | sort | head -50
test -f /srv/tech-notes/current/index.html && echo 'index exists'

更成熟的发布应使用版本目录、原子软链接切换和保留上一版，以便回退；本教程先建立最小流程，不把简单复制包装成零停机发布。

九、配置 Nginx 站点

配套配置在 nginx-site.conf。先在本地阅读，再把 DOMAIN 与 SITE_ROOT 替换为实际值。

在服务器备份已有配置：

`1`	`sudo cp /etc/nginx/sites-available/default /etc/nginx/sites-available/default.backup`

将配置保存到 /etc/nginx/sites-available/DOMAIN，并把：

1
2

server_name DOMAIN;
root SITE_ROOT;

替换为真实值。启用站点：

1
2

# 会创建符号链接；若目标已存在，先检查而不是强制覆盖
sudo ln -s /etc/nginx/sites-available/DOMAIN /etc/nginx/sites-enabled/DOMAIN

最关键的门禁：

`1`	`sudo nginx -t`

只有看到配置语法和测试成功，才重载：

1
2

sudo systemctl reload nginx
curl -I -H "Host: DOMAIN" http://127.0.0.1/

如果新站点正常，再评估是否删除默认站点的软链接。不要直接删除原配置文件；保留可恢复副本。

十、域名与 HTTPS

10.1 证书签发前检查

Certbot 的 Nginx 插件需要找到匹配域名的 server block，ACME 验证还要求域名正确指向服务器并可从公网访问。逐项确认：

1
2
3

# Windows：DNS 应返回 SERVER_IP
Resolve-DnsName DOMAIN
curl.exe -I http://DOMAIN/

服务器上确认：

1
2
3

sudo nginx -t
sudo ufw status verbose
curl -I -H "Host: DOMAIN" http://127.0.0.1/

10.2 使用当前官方说明安装 Certbot

Certbot 安装方式会变化，必须在执行当天打开 Certbot Instructions 或 Ubuntu 的 TLS 证书文档，选择 Nginx + 当前 Ubuntu 版本。不要从多年以前的博客复制安装命令。

安装完成后，常见签发方式是：

1
2

# 会申请证书并修改匹配的 Nginx 配置
sudo certbot --nginx -d DOMAIN

该命令会改变 Nginx 配置。执行前先备份 /etc/nginx 中的站点配置，并确认 DOMAIN 真实可控。签发后验证：

sudo nginx -t
sudo systemctl status nginx --no-pager
sudo certbot renew --dry-run
curl -I https://DOMAIN/

浏览器出现锁图标只是基础现象；还要检查证书域名、有效期、HTTP 到 HTTPS 跳转和实际内容。

十一、日志驱动的排错方法

11.1 四层定位

按从近到远的顺序检查：

进程层：Nginx 是否运行，配置能否通过 nginx -t？
主机层：是否监听端口，UFW 是否允许？
公网层：云安全组和路由是否允许，IP 是否正确？
域名与 TLS 层：DNS 是否指向该主机，证书是否匹配？

常用只读命令：

systemctl status nginx --no-pager
sudo journalctl -u nginx --since "30 minutes ago" --no-pager
sudo tail -n 100 /var/log/nginx/tech-notes.error.log
sudo tail -n 100 /var/log/nginx/tech-notes.access.log
sudo ss -lntp
curl -vI http://127.0.0.1/

11.2 常见症状

症状	优先检查
`Connection timed out`	安全组、UFW、错误 IP、路由
`Connection refused`	服务未监听、监听地址或端口错误
Nginx 默认页	`server_name` 未匹配、默认站点仍接管请求
`403 Forbidden`	目录权限、文件权限、站点根路径、日志
`404 Not Found`	上传目录、URL 路径、`try_files`、大小写
HTTPS 证书不匹配	DNS、Certbot `-d` 域名、错误 server block
样式仍是旧版	浏览器/CDN 缓存、上传遗漏、错误站点根目录

不要一次修改多处。先保存日志和命令输出，只改变一个假设，再重复验证。

十二、发布、回退与维护

12.1 发布前后

发布前：

在本地完成 Hugo 构建和页面检查；
备份当前 Nginx 配置与站点版本；
确认磁盘空间、域名和目标目录；
记录本次构建来源，例如 Git 提交号。

发布后：

从服务器内部和外部各请求一次；
打开首页、文章列表和一篇详情页；
检查错误日志与证书；
确认旧版本仍能恢复。

12.2 一个更安全的目录思路

/srv/tech-notes/
├─ releases/
│  ├─ 20260921-100000/
│  └─ 20260922-093000/
└─ current -> releases/20260922-093000/

上传到新版本目录、检查完整性后，再切换 current 软链接。回退时把链接指回上一版本。真正的原子发布还要处理权限、并发、清理策略和自动化失败；这属于进阶内容。

12.3 持续维护

安装安全更新并处理需要重启的情况；
监控磁盘、内存、证书续期和错误率；
定期验证备份能够恢复，而不是只确认备份文件存在；
删除不用的账号、端口和服务；
对配置变更保留版本记录和回退步骤。

十三、GitHub Pages 还是自有服务器

需求	GitHub Pages	自有 Ubuntu + Nginx
静态站点	很适合	适合
服务器维护	平台负责	自己负责
自定义 Nginx/系统服务	不支持	支持
后端进程与数据库	不直接支持	可以，但维护成本更高
学习运维	较少	完整
攻击面与责任	相对较小	账号、更新、端口、日志、备份均需负责

若目标只是公开 Hugo 文档，Pages 通常更省心。选择 VPS 应源于明确需求，而不是认为“自己有服务器才算真正的网站”。

十四、练习

画出浏览器、DNS、云安全组、UFW、Nginx 和站点目录之间的路径。
用 curl -I 对比请求 IP 与请求域名时的响应，解释 Host 的作用。
阅读配套 Nginx 配置，指出每条 location 的匹配对象。
写一份发布检查清单，其中必须包含备份、验证与回退。
假设出现 403，列出三个可能原因及对应的只读检查命令。

十五、上线检查清单

DNS 的 A/AAAA 记录与真实网络配置一致。
SSH 密钥登录已在第二个会话验证，私钥未上传或泄露。
UFW 与云安全组只开放必要端口。
nginx -t 成功，Nginx 服务状态正常。
SITE_ROOT 中包含最新 index.html，权限允许 Nginx 读取。
HTTP 能访问后再申请证书，HTTPS 与续期 dry-run 均成功。
内部、外部、域名和 HTTPS 四条访问路径均验证。
日志中没有持续错误，旧版本与配置可以恢复。
没有把密钥、Token、备份或配置副本暴露在站点目录。

十六、小结

把网站放上服务器不是一条神秘命令，而是一条可以逐层验证的链路：DNS 找到主机，安全组和防火墙允许连接，Nginx 监听端口并匹配域名，再从正确目录读取 Hugo 生成的文件。HTTPS 在此基础上增加身份验证与传输保护。

可靠运维的关键不是记住所有命令，而是每次操作前知道它会改变什么、如何检查、失败后怎样恢复。

参考资料

以上官方资料最后核验于 2026-09-21。Certbot 的安装命令与支持系统变化较快，实操当天必须再次核对。

Web 开发：从网页到 Hugo 网站

Mon, 21 Sep 2026 09:00:00 +0800

版本：v1.0.0 适用对象：第一次系统学习 Web 开发的读者本地环境：Windows 11、PowerShell 7、Git、Hugo Extended 最后核验：2026-09-21

学习目标

完成本教程后，你应该能够：

解释网页、网站、浏览器、前端、后端和服务器之间的关系；
看懂 URL，并描述一次网页请求的大致过程；
理解 HTML、CSS、JavaScript 各自负责什么；
在本地运行并修改一个完整的 Hugo 静态网站；
构建生产文件，并理解 GitHub Pages 自动部署流程；
使用浏览器开发者工具排查常见问题。

配套项目位于 example/hugo-tech-notes/。教程中的操作只修改这个示例目录，不要求改动任何现有项目。

一、网页、网站与 Web 开发

1.1 网页不是“浏览器里的截图”

网页通常是一份 HTML 文档。HTML 描述标题、段落、链接、图片、导航等结构；浏览器读取文档后，把它排版并绘制到屏幕上。CSS 改变颜色、间距和布局，JavaScript 让页面响应点击、输入或网络数据。

网站是一组通过链接和共同导航组织起来的网页及相关资源。例如，一个技术博客可能包含首页、文章列表、每篇文章的详情页、CSS、JavaScript 和图片。浏览器一次只能显示某个页面，但这些页面共同组成网站。

容易混淆的几个词：

词语	主要职责	示例
浏览器	请求资源、解释 HTML/CSS/JS、绘制页面	Chrome、Firefox、Edge
前端	直接运行或呈现在浏览器中的界面	HTML、CSS、JavaScript
后端	在服务器上处理业务、权限和数据	Python、Java、Go、Node.js 服务
数据库	持久保存并查询结构化数据	PostgreSQL、MySQL
Web 服务器	接收 HTTP 请求并返回文件或转发请求	Nginx、Apache
静态网站生成器	构建时把内容和模板生成 HTML	Hugo

本教程的示例是静态网站：访问者请求时，服务器直接返回已经生成好的 HTML、CSS 和 JavaScript，不需要每次查询数据库再拼页面。静态不等于没有交互；浏览器端 JavaScript 仍可以切换主题、过滤内容或请求外部 API。

1.2 Web 开发不只是写页面

一个可交付的网站至少要同时回答这些问题：

内容是否清楚，HTML 结构是否有语义？
小屏幕、键盘操作和辅助技术能否使用？
文件如何组织、构建和版本控制？
地址、缓存、错误页面和搜索引擎信息是否合理？
怎样部署，出错时去哪里看日志？

因此，“会写一个漂亮页面”和“能维护一个网站”不是同一件事。本教程先把最小闭环走通，再逐步增加复杂度。

二、输入网址后发生了什么

图 1：浏览器先找到服务器，再请求 HTML 和页面依赖的其他资源。图中省略了缓存、CDN、TLS 握手等细节。

假设访问：

`1`	`https://notes.example.com/posts/http/?from=course#dns`

它可以拆成：

部分	示例	作用
协议	`https`	约定通信方式，并通过 TLS 加密与验证身份
主机名	`notes.example.com`	通过 DNS 查找服务器地址
路径	`/posts/http/`	指向站点中的资源
查询参数	`?from=course`	向服务端或前端传递附加参数
片段	`#dns`	定位页面内部位置，通常不发送给服务器

一次简化请求包括：

浏览器检查本地缓存，并通过 DNS 查询主机名对应的 IP 地址；
浏览器与服务器建立网络连接；HTTPS 还要建立 TLS 安全连接；
浏览器发送 HTTP 请求，例如 GET /posts/http/；
服务器返回状态码、响应头和 HTML；
浏览器解析 HTML，继续请求其中引用的 CSS、JavaScript、字体和图片；
浏览器构建页面结构，计算布局并绘制到屏幕上。

常见状态码：

200 OK：请求成功；
301、308：资源永久移动，浏览器应访问新地址；
403 Forbidden：服务器理解请求，但拒绝访问；
404 Not Found：资源不存在，常见于路径或大小写错误；
500 Internal Server Error：服务器执行时发生错误。

状态码只能说明这一层的结果。首页返回 200，不代表页面引用的 CSS 也一定成功；所以排错时要观察每个请求。

三、HTML、CSS 与 JavaScript

3.1 HTML：描述结构与含义

<!doctype html>
<html lang="zh-CN">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>技术手记</title>
  </head>
  <body>
    <header>
      <nav aria-label="主导航">
        <a href="/">首页</a>
        <a href="/posts/">文章</a>
      </nav>
    </header>
    <main>
      <article>
        <h1>第一篇技术笔记</h1>
        <p>从语义清楚的结构开始。</p>
      </article>
    </main>
  </body>
</html>

header、nav、main、article 不是为了“看起来高级”，而是告诉浏览器、搜索引擎和辅助技术每块内容的角色。标题也应按层级组织：页面主标题通常是一个 h1，其下再使用 h2、h3，不要只因为字号需要就跳级。

3.2 CSS：控制呈现与布局

:root {
  --background: #f7f4ec;
  --text: #17211d;
  --accent: #006d5b;
}

body {
  margin: 0;
  background: var(--background);
  color: var(--text);
  font-family: system-ui, sans-serif;
}

.card-grid {
  display: grid;
  grid-template-columns: repeat(3, 1fr);
  gap: 1rem;
}

@media (max-width: 720px) {
  .card-grid { grid-template-columns: 1fr; }
}

响应式设计不是把桌面页面整体缩小，而是让内容在不同空间重新排布。示例在宽屏显示三列，窄屏改成一列。还应尽量使用弹性宽度、合适的行长和清晰的焦点样式。

3.3 JavaScript：响应事件和改变状态

const button = document.querySelector('.theme-toggle');

button?.addEventListener('click', () => {
  document.documentElement.dataset.theme = 'dark';
});

这段代码寻找按钮，监听点击，再改变根元素的属性。CSS 可以根据这个属性应用深色主题。?. 表示按钮不存在时不继续调用，避免简单页面直接报错。

JavaScript 能增强体验，但不应破坏基本访问路径。例如导航最好仍然使用 <a href="...">，而不是只有执行 JavaScript 才能跳转。

四、为什么在这里使用 Hugo

纯手写两个页面很容易；写五十篇文章时，手动复制导航、页脚和 <head> 就会造成重复和不一致。Hugo 把三类材料组合起来：

content/：Markdown 内容和 Front Matter 元数据；
layouts/：把内容放到 HTML 结构中的模板；
static/：直接复制的 CSS、JavaScript 和图片；
hugo.toml：站点标题、地址、语言等配置。

图 2：开发时 Hugo 提供本地预览；发布时生成可直接托管的 public/。

Hugo 在构建阶段完成模板渲染，不要求生产服务器运行 Hugo。这让静态站点易于部署，也减少了服务器运行时组件。但登录、订单、私有数据等动态业务仍需要后端或外部服务。

五、运行配套网站

5.1 安装并检查 Hugo

Hugo 官方在 Windows 上提供 Winget 包。下面的命令会在系统中安装软件，执行前先确认你允许本机安装：

1
2

# 运行环境：Windows PowerShell 7；会修改本机软件安装状态
winget install Hugo.Hugo.Extended

关闭并重新打开 PowerShell，然后检查：

1
2

hugo version
git --version

教程验证使用 Hugo Extended 0.166.0。若版本不同，先阅读 Hugo 发布说明；不要看到命令成功就假定输出完全相同。

5.2 启动本地开发服务器

在本资料包根目录运行：

1
2
3

# 运行环境：Windows PowerShell 7
Set-Location ".\examples\hugo-tech-notes"
hugo server -D

终端会显示本地地址，通常是 http://localhost:1313/。浏览器打开后应看到“技术手记”首页和两篇示例文章。-D 表示预览标记为草稿的内容；生产构建默认不发布草稿。

按 Ctrl+C 停止服务器。

5.3 认识项目结构

hugo-tech-notes/
├─ content/
│  ├─ _index.md
│  └─ posts/
│     ├─ _index.md
│     ├─ first-note.md
│     └─ http-notes.md
├─ layouts/
│  ├─ baseof.html
│  ├─ home.html
│  ├─ list.html
│  └─ single.html
├─ static/
│  ├─ css/main.css
│  └─ js/main.js
├─ .github/workflows/hugo.yaml
└─ hugo.toml

baseof.html 是公共外壳；home.html、list.html 和 single.html 分别负责首页、列表页和单篇内容。模板中的 {{ ... }} 是 Hugo 模板表达式，例如 {{ .Title }} 读取当前页面标题。

5.4 新增一篇文章

复制已有文章最直观，也可以使用 Hugo 命令。为了避免覆盖现有文件，先检查目标：

`1`	`Test-Path ".\content\posts\my-web-note.md"`

结果应为 False。然后创建内容骨架：

`1`	`hugo new content posts/my-web-note.md`

打开文件，填写：

---
title: "我的 Web 学习记录"
date: 2026-09-21T10:00:00+08:00
description: "记录第一次运行 Hugo 网站。"
tags: [Web, Hugo]
draft: true
---

## 我完成了什么

我能够在本地启动 Hugo，并通过浏览器访问站点。

保持 hugo server -D 运行，保存后浏览器会刷新。准备发布时把 draft 改为 false。

5.5 构建生产文件

`1`	`hugo --minify --cleanDestinationDir`

--minify 压缩可压缩输出；
--cleanDestinationDir 清理目标目录中不再由当前构建生成的文件；
结果写入 public/。

检查关键页面：

1
2
3

Test-Path ".\public\index.html"
Test-Path ".\public\posts\index.html"
Get-ChildItem ".\public\posts" -Recurse -Filter index.html

这里的 public/ 是生成物，不是内容源。修改它会在下次构建时丢失，因此 .gitignore 已将其排除。

六、部署到 GitHub Pages

6.1 发布前替换占位符

hugo.toml 中的地址是：

`1`	`baseURL = 'https://GITHUB_USER.github.io/REPOSITORY/'`

把 GITHUB_USER 和 REPOSITORY 替换为实际 GitHub 用户名与仓库名。项目站点通常位于 https://用户名.github.io/仓库名/，组织或用户主页仓库的规则不同，必须以 GitHub Pages 当前文档为准。

6.2 初始化并推送仓库

以下命令会创建本地 Git 历史并准备远程推送。把远程地址替换后再执行：

git init
git add .
git status
git commit -m "Create Hugo technical notes site"
git branch -M main
git remote add origin https://github.com/GITHUB_USER/REPOSITORY.git
git push -u origin main

git status 是必要检查，不是装饰。它让你在提交前确认没有密钥、public/ 或无关文件。

6.3 理解工作流

.github/workflows/hugo.yaml 在推送 main 时执行：

安装固定版本 Hugo；
检出仓库；
由 configure-pages 取得正确的 Pages 基础地址；
构建 public/；
上传 Pages artifact；
部署到 github-pages 环境。

工作流显式申请 contents: read、pages: write 和 id-token: write，没有授予不需要的仓库写权限。

在 GitHub 仓库打开 Settings → Pages，把发布源设为 GitHub Actions。再到 Actions 查看构建与部署日志。只有工作流成功，并且实际页面能访问，才算完成线上部署。

七、用开发者工具排错

按 F12 或浏览器菜单打开开发者工具：

Elements / Inspector：查看实际 DOM 和最终生效的 CSS；
Console：查看 JavaScript 错误和主动输出；
Network：查看每个请求的 URL、状态码、类型和耗时；
Lighthouse / Performance：辅助发现性能与可访问性问题，但分数不是唯一目标。

建议按证据排查：

终端中 Hugo 是否报告模板或 Front Matter 错误？
Network 中失败的是 HTML、CSS、JavaScript 还是图片？
失败请求的完整 URL 是否包含正确的仓库子路径？
Console 是否有脚本语法错误？
Elements 中元素是否存在，只是被 CSS 隐藏或覆盖？

八、可访问性、SEO、性能与缓存

8.1 可访问性

使用 header、nav、main、article 等语义元素；
图片提供与用途相符的 alt，纯装饰图使用空 alt；
链接文字说明去向，不要大量使用“点击这里”；
所有操作可用键盘完成，并保留清晰焦点；
不只依赖颜色传达错误或状态；
尊重 prefers-reduced-motion，避免强制动画。

配套站点包含“跳到正文”链接、导航标签、按钮状态和减少动画设置，可以在源码中逐一寻找。

8.2 SEO

搜索引擎优化的基础不是堆关键词，而是让页面能被正确理解：独立标题、准确摘要、清楚的标题层级、稳定链接、站点地图和可抓取内容。Hugo 会根据内容生成 sitemap.xml；仍需保证正文真正回答读者问题。

8.3 性能与缓存

压缩图片，优先使用合适尺寸和现代格式；
避免为了一个小功能加载庞大脚本；
CSS 和 JavaScript 若长期缓存，最好使用内容哈希文件名；
HTML 更新频繁，不宜盲目设置极长缓存；
用 Network 面板测量真实请求，不凭文件数量猜性能。

九、常见错误

9.1 本地正常，Pages 样式丢失

常见原因是把资源写成 /css/main.css，部署到项目子路径后它会指向域名根目录。示例使用 Hugo 的 relURL：

`1`	`{{ "css/main.css" \| relURL }}`

同时在工作流构建时使用 Pages 返回的基础地址。

9.2 修改 `public/` 后又消失

public/ 是输出。应修改 content/、layouts/ 或 static/，再重新构建。

9.3 新文章本地看不到

检查文件是否在 content/、Front Matter 是否闭合、draft 是否为 true。草稿需要 hugo server -D 才显示。

9.4 页面能打开但 JavaScript 没反应

先看 Console，再确认脚本是否在 Network 中成功加载、选择器是否匹配、代码是否等 DOM 加载后执行。示例通过 defer 加载脚本。

9.5 自动部署失败

先阅读失败步骤的日志，不要反复重跑掩盖原因。检查 Pages 发布源、工作流权限、Hugo 版本、配置语法和基础地址。不要把失败简单归因于“GitHub 有问题”。

十、练习

新增一篇非草稿文章，为它添加两个标签，并在列表页找到它。
给首页增加“学习主题”区块，但保持移动端单列布局。
故意把 CSS 路径改错，用 Network 面板记录状态码，再修复。
关闭 JavaScript，确认导航和文章仍能访问；解释哪些功能消失。
用键盘 Tab 遍历页面，修复任何看不清或到不了的交互元素。

十一、发布前检查清单

hugo --minify --cleanDestinationDir 成功完成。
首页、文章列表和每篇详情页都能打开。
手机宽度下没有横向滚动或文字溢出。
Network 中没有意外 404，Console 中没有未处理错误。
标题层级、链接文字、图片替代文字和键盘焦点合理。
baseURL、仓库名和 Pages 发布源正确。
Git 差异中没有 public/、密钥、令牌或本地绝对路径。
Actions 成功后实际访问线上地址，而不是只看绿色图标。

十二、小结

Web 开发的主线可以概括为：浏览器通过 URL 和 HTTP 取得资源，HTML 负责结构，CSS 负责呈现，JavaScript 负责交互；Hugo 在构建阶段把重复的模板与独立内容组合为静态文件；GitHub Actions 再把这些文件部署到 Pages。

理解这条链路后，遇到错误就不必只靠刷新或重新复制代码。你可以判断问题发生在内容、模板、资源路径、构建还是部署阶段，并用终端日志与开发者工具验证判断。

参考资料

以上官方资料最后核验于 2026-09-21。

团队开发与 Git 操作指南

Mon, 14 Sep 2026 09:00:00 +0800

版本：v1.0.0 状态：生效适用对象：首次参与团队开发、尚未系统使用 Git 与 GitHub 的成员主要环境：Windows 11、PowerShell、Git、GitHub、Visual Studio Code 最后更新：2026-09-14

前言

团队开发的核心不是让多人同时修改文件，而是让每一项改动都有明确来源、可被检查、可以撤销，并在进入稳定分支前得到验证。本指南从版本控制的基本概念开始，逐步讲解 Git 命令、GitHub 协作、功能分支、Fork、Pull Request、代码评审以及本项目采用的 main-only 流程。

阅读本指南时，请先理解命令会改变什么状态，再复制命令。每次执行会修改分支、提交或远程仓库的操作前，至少运行一次 git status，并确认当前仓库、当前分支和待提交文件都符合预期。

本指南使用虚构仓库 team-demo、虚构组织 example-org 和占位账号 your-name。请将示例中的占位内容替换为实际值，不要直接照搬仓库地址或身份信息。

图 1 团队成员围绕共享版本库完成开发与评审

第一章团队开发与版本控制

1.1 团队开发解决什么问题

个人开发时，一个人通常同时决定修改内容、验证方式和发布时间。团队开发则需要多人在同一套代码和文档上工作。如果缺少约定，常见后果包括互相覆盖文件、无法判断某项修改由谁引入、错误进入稳定版本，以及出现问题后无法快速恢复。

团队协作需要回答五个问题：谁负责这项任务，修改发生在哪个分支，为什么要修改，谁验证过修改，以及出现问题时如何撤销。Git 保存文件版本和历史，GitHub 保存远程仓库并承载任务、评审与权限控制。二者共同提供技术基础，但团队仍需建立明确的工作流程。

1.2 团队成员的基本职责

角色	主要职责	不应省略的动作
任务负责人	明确目标、范围和验收条件	在开发前说明什么算完成
开发者	在独立分支完成修改并自检	检查差异、提交范围和验证结果
评审者	检查正确性、风险和可维护性	阅读实际 diff，不只看 PR 描述
测试或验收人员	按约定场景验证结果	记录通过项、失败项和证据
合并或发布负责人	确认门禁并执行合并或发布	检查审批、自动检查和回退条件

一个人可以同时承担多个角色，但在关键改动中，作者不应成为唯一评审者。评审的价值在于引入第二视角，而不是完成形式上的点击。

1.3 版本控制的基本对象

仓库 Repository：保存文件、提交历史、分支和标签的集合。
工作区 Working tree：当前磁盘上可以直接编辑的文件。
暂存区 Staging area：下一次提交准备包含的改动集合。
提交 Commit：某一时刻的受控快照，包含作者、时间、说明和父提交关系。
分支 Branch：指向一条提交历史的可移动引用。
合并 Merge：把一条分支的改动整合到另一条分支。
远程仓库 Remote：通过网络访问的仓库副本，通常托管在 GitHub。

图 2 Git 本地状态与远程仓库之间的数据流

1.4 安全操作顺序

执行 Git 操作前，按以下顺序检查：

使用 Get-Location 确认 PowerShell 当前目录。
使用 git status 确认这是 Git 仓库并查看当前分支。
使用 git diff 和 git diff --staged 查看未暂存与已暂存差异。
使用 git branch --show-current 再次确认目标分支。
只在状态符合预期时执行提交、合并、推送或撤销操作。

安全提示：命令执行成功不代表操作对象正确。进入了错误目录或停留在错误分支时，正确命令仍会产生错误结果。

第二章 Git 与 GitHub

2.1 什么是 Git

Git 是分布式版本控制系统。每次正常克隆都会得到仓库历史的本地副本，因此开发者可以在本地查看历史、创建分支和提交改动。Git 负责跟踪文件内容和提交关系，不要求必须使用 GitHub。

Git 的主要用途是：记录版本、比较差异、并行开发、合并成果和恢复已知状态。git status、git add、git commit、git branch 和 git merge 等命令均由 Git 提供。

2.2 什么是 GitHub

GitHub 是托管 Git 仓库并提供协作功能的网络平台。除保存远程仓库外，它还提供账号和组织管理、Issue、Pull Request、代码评审、分支保护、自动检查、发布记录等功能。

简单地说，Git 管理版本历史，GitHub 让团队围绕这份历史协作。没有 GitHub 也可以使用 Git；没有安装 Git，也可以在 GitHub 网页上执行少量编辑，但无法完整使用本地开发和验证流程。

图 3 Git 与 GitHub 的职责关系

2.3 GitHub 的核心对象

对象	作用	初学者需要记住的内容
Account	个人身份	提交邮箱和 GitHub 账号应正确关联
Organization	团队或组织空间	仓库权限通常由组织统一管理
Repository	远程仓库	包含代码、历史、Issue、PR 和设置
Issue	任务或问题记录	应写清背景、目标、验收和负责人
Pull Request	合并请求	用于提议、讨论、检查和合并改动
Review	代码评审	可评论、批准或要求修改
Checks	自动检查结果	构建、测试或规则通过后才可合并
Actions	自动化工作流	常用于检查、构建、部署和定时任务
Release	面向使用者的版本记录	通常关联标签、说明和构建产物

2.4 仓库可见性和权限

公开仓库允许任何人查看，私有仓库只对获授权的账号开放。可见性不等于修改权限。一个人能够查看仓库，并不表示他可以推送分支或合并 PR。

常见权限从低到高包括只读、问题管理、写入、维护和管理。团队应遵循最小权限原则：只授予成员完成职责所需的权限。主分支和阶段分支应使用分支保护规则，要求通过 PR、状态检查和必要审批后才能合并。

2.5 Clone Fork 和下载 ZIP 的区别

操作	得到什么	是否保留 Git 历史	典型用途
Clone	远程仓库的本地 Git 副本	是	日常开发和提交
Fork	自己账号下的远程仓库副本	是	无上游写权限或隔离协作
Download ZIP	当前文件的压缩包	否	只查看或临时使用文件

下载 ZIP 后得到的目录通常没有 .git，无法直接执行正常的 pull、commit 和 push 流程。需要参与协作时，应使用 clone；没有原仓库写权限时，通常先 fork，再 clone 自己的 Fork。

第三章 Windows 环境准备

3.1 安装 Git

从 Git 官方下载页获取 Windows 安装程序。安装过程中，如果团队没有特殊要求，可保留默认选项。安装完成后重新打开 PowerShell，运行：

`1`	`git --version`

预期输出包含版本号，例如 git version 2.x.x.windows.x。如果提示找不到 git，先关闭并重新打开终端；仍无效时检查 Git 是否安装成功以及 PATH 配置。

3.2 安装 VS Code

从 Visual Studio Code 官方网站下载安装。VS Code 内置 Git 图形界面，但仍使用计算机上安装的 Git。仅安装 VS Code 不能替代 Git。

在 VS Code 中按 Ctrl+Shift+G 可以打开“源代码管理”视图。按 Ctrl+Shift+P 打开命令面板，可搜索 Git: Clone、Git: Create Branch 等操作。

3.3 配置身份

首次提交前配置用户名和邮箱：

1
2
3

git config --global user.name "Your Name"
git config --global user.email "you@example.com"
git config --global init.defaultBranch main

检查配置：

1
2
3

git config --global --list
git config --show-origin --get user.name
git config --show-origin --get user.email

user.name 和 user.email 会写入新提交。它们不是 GitHub 登录凭据。邮箱应使用团队认可的地址，或使用 GitHub 提供的隐私邮箱。

3.4 配置认证

使用 HTTPS 克隆时，GitHub 不接受把账号密码直接当作 Git 操作密码。Windows 上通常由 Git Credential Manager 打开浏览器完成授权并安全保存凭据。个人访问令牌只应授予必要范围，不能写入仓库、截图、聊天记录或脚本。

SSH 方式使用公钥和私钥。公钥可添加到 GitHub，私钥只能保存在本人可信设备中。初学者如果没有团队统一 SSH 配置，可先使用 HTTPS。

建议为 GitHub 账号启用双重认证，并妥善保存恢复方式。收到异常登录或授权提示时，应先确认域名和操作来源。

3.5 第一次克隆

命令行方式：

Set-Location D:\Work
git clone https://github.com/example-org/team-demo.git
Set-Location .\team-demo
git status
git remote -v

VS Code 方式：

按 Ctrl+Shift+P。
选择 Git: Clone。
粘贴仓库 HTTPS 地址。
选择用于保存仓库的父目录。
克隆完成后选择“打开”。
只在确认仓库来源可信后接受 Workspace Trust。

预期结果是 git status 显示当前分支和干净工作区，git remote -v 显示名为 origin 的远程地址。

第四章 Git 基础操作

4.1 初始化仓库

只有在创建全新仓库时才使用 git init：

New-Item -ItemType Directory team-demo
Set-Location .\team-demo
git init
git status

已有远程仓库时应使用 git clone，不要先 git init 再手工复制文件，否则容易产生两套无关历史。

VS Code 中可打开空目录，进入“源代码管理”，选择“初始化仓库”。初始化只创建本地仓库，不会自动在 GitHub 上创建远程仓库。

4.2 查看状态和差异

git status
git status --short
git diff
git diff --staged
git log --oneline --graph --decorate -10

git status 展示当前分支、未跟踪文件、已修改文件和暂存状态。
git diff 展示尚未暂存的改动。
git diff --staged 展示下一次提交将包含的改动。
git log 展示已经提交的历史。

VS Code 的“源代码管理”视图会列出 Changes 和 Staged Changes。单击文件可打开差异编辑器。提交前应逐个查看文件，而不是只看文件数量。

4.3 暂存和提交

1
2
3

git add README.md
git diff --staged
git commit -m "docs: clarify setup steps"

git add 不是把文件上传到 GitHub，而是把当前版本放入暂存区。只有暂存区中的内容会进入下一次提交。

需要暂存多个明确文件时，可逐个列出：

`1`	`git add README.md docs\guide.md`

对初学者，不建议不检查就使用 git add .。它可能把临时文件、调试输出或敏感配置一起加入暂存区。

在 VS Code 中，单击文件右侧的 + 将其暂存；输入提交信息后选择“提交”。提交后仍需 push，远程仓库才会收到本地提交。

4.4 编写提交信息

推荐格式：

`1`	`type(scope): summary`

常用类型：

类型	用途	示例
`feat`	新增功能	`feat(search): add keyword filter`
`fix`	修复问题	`fix(login): handle expired session`
`docs`	修改文档	`docs(git): add fork workflow`
`test`	新增或调整测试	`test(api): cover invalid token`
`refactor`	不改变外部行为的重构	`refactor(cache): isolate key builder`
`build`	构建与依赖	`build: pin tool version`
`ci`	自动化流水线	`ci: run checks on pull requests`
`chore`	其他维护	`chore: remove obsolete sample`

提交信息应说明这次提交完成了什么，不要使用 update、change、fix stuff 等无法追踪意图的词。一个提交只表达一个可解释、可验证、可回滚的意图。

4.5 分支操作

查看和创建分支：

1
2
3

git branch
git branch --show-current
git switch -c feature/profile-page

切换已有分支：

`1`	`git switch main`

删除已经合并的本地分支：

`1`	`git branch -d feature/profile-page`

-d 会阻止删除尚未合并的分支。-D 会强制删除，初学者不应在未确认提交已保存时使用。

VS Code 可单击窗口左下角的分支名称，或在命令面板使用 Git: Create Branch 和 Git: Checkout to。

4.6 远程仓库操作

git remote -v
git fetch origin
git pull --ff-only
git push

fetch 下载远程引用，但不修改当前工作区。
pull 通常等于先 fetch 再把远程变化整合到当前分支。
push 把本地提交发送到远程仓库。

第一次推送新分支：

`1`	`git push -u origin feature/profile-page`

-u 建立上游跟踪关系。之后在该分支通常可以直接运行 git push 和 git pull。

4.7 合并分支

把 feature/profile-page 合入当前分支前，应先切换到接收改动的分支：

1
2

git switch main
git merge feature/profile-page

团队仓库通常要求通过 GitHub PR 合并，因此不应在本地直接合并后推送受保护分支。上面命令主要用于理解合并和处理个人分支。

4.8 使用 gitignore

.gitignore 告诉 Git 哪些未跟踪文件不应纳入版本控制。常见内容：

# 本地环境变量
.env
.env.*

# 构建和依赖目录
node_modules/
dist/

# 编辑器和系统文件
.vscode/
Thumbs.db

.gitignore 不会自动停止跟踪已经提交的文件。敏感文件一旦进入历史，应立即停止传播、撤销相关凭据，并联系仓库管理员处理历史和访问风险；仅新增 .gitignore 不足以消除泄露。

第五章功能分支与 Pull Request

5.1 默认协作模型

功能分支模型适合大多数小型和中型团队。稳定分支受到保护，每项任务在独立分支完成，通过 Pull Request 接受检查后再合并。

图 4 功能分支与 Pull Request 协作闭环

5.2 开始任务

开始修改前确认任务的目标、范围、验收方式和负责人。然后更新稳定分支：

git status
git switch main
git fetch origin
git pull --ff-only origin main

如果 git status 显示未提交修改，不要直接切换或拉取。先判断这些修改应提交、暂存到 stash，还是安全撤销。

从最新 main 创建工作分支：

1
2

git switch -c feature/profile-page
git branch --show-current

分支名应简短、可读，并体现工作类型。避免使用 my-branch、test1 或个人姓名作为长期命名方式。

5.3 修改和提交

完成一个逻辑单元后检查：

git status
git diff
git add src\profile.js tests\profile.test.js
git diff --staged
git commit -m "feat(profile): add profile summary"

提交前至少确认：没有无关格式化、没有调试输出、没有凭据、没有遗漏必要测试或文档。提交并不要求一次完成整个任务，可以用多个聚焦提交逐步保存工作。

5.4 推送并创建 PR

`1`	`git push -u origin feature/profile-page`

在 GitHub 仓库页面选择创建 Pull Request，确认：

base repository 是团队仓库。
base branch 是计划合入的分支。
compare branch 是自己的工作分支。
Files changed 只包含本任务改动。
PR 描述写明原因、改动、验证结果和风险。

工作尚未完成但希望提前讨论时，可创建 Draft PR。Draft 表示仍在进行中，不应请求最终合并。

5.5 响应评审

评审者提出修改后，在同一个工作分支继续编辑、提交和 push。GitHub 会自动更新 PR：

1
2
3

git add src\profile.js
git commit -m "fix(profile): handle missing display name"
git push

不要为了每条意见创建新 PR。完成修改后回复评审会话，说明采用了什么处理方式；只有确认问题已处理时才将会话标记为 resolved。

5.6 合并和清理

当审批和自动检查通过后，由有权限的成员合并。普通功能 PR 推荐使用 Squash and merge，使一个 PR 在目标分支上形成一个清晰提交。

合并后更新本地仓库：

git switch main
git pull --ff-only origin main
git branch -d feature/profile-page
git fetch --prune origin

删除分支前确认 PR 已合并且重要提交已进入目标分支。GitHub 页面可删除远程工作分支；fetch --prune 用于清理已经不存在的远程跟踪引用。

第六章 Fork 协作

6.1 何时使用 Fork

Fork 适用于贡献者没有原仓库写权限、跨组织协作、开源贡献或需要更强权限隔离的情况。具有团队仓库写权限的内部成员通常使用同仓库功能分支，流程更直接。

条件	同仓库功能分支	Fork
对原仓库有写权限	推荐	可用但通常没有必要
对原仓库无写权限	不可直接推送	推荐
远程仓库数量	一个	原仓库和个人 Fork 两个
PR 来源	同仓库分支	个人 Fork 分支
权限隔离	较弱	较强

6.2 理解 origin 和 upstream

在 Fork 流程中，建议统一使用：

1
2
3

upstream = 原始团队仓库
origin   = 自己账号下的 Fork
local    = 本地克隆

图 5 Fork 模式中的 upstream origin 和 local

origin 和 upstream 只是远程名称，但行业惯例采用上面的含义。运行命令前应通过 git remote -v 核对，不要只凭名称猜测地址。

6.3 创建并配置 Fork

打开原始 GitHub 仓库。
选择页面右上角的 Fork。
选择自己的账号作为 Owner，创建 Fork。
克隆自己的 Fork：

1
2
3

git clone https://github.com/your-name/team-demo.git
Set-Location .\team-demo
git remote -v

添加原仓库为 upstream：

1
2

git remote add upstream https://github.com/example-org/team-demo.git
git remote -v

预期结果：origin 指向 your-name/team-demo，upstream 指向 example-org/team-demo。

6.4 同步上游

更新个人 Fork 的 main：

git status
git fetch upstream
git switch main
git merge --ff-only upstream/main
git push origin main

fetch upstream 只下载上游状态。merge --ff-only 仅在本地 main 没有额外分叉时快进更新；如果失败，应先调查本地 main 为什么含有独立提交，不要立刻改用强制推送。

6.5 创建跨仓库 PR

从已同步的 main 创建分支：

git switch -c docs/clarify-installation
git add docs\installation.md
git commit -m "docs(setup): clarify Windows installation"
git push -u origin docs/clarify-installation

创建 PR 时检查四个字段：

base repository：原始团队仓库 example-org/team-demo。
base branch：上游希望接收改动的分支，例如 main。
head repository：个人 Fork your-name/team-demo。
compare branch：个人工作分支 docs/clarify-installation。

评审期间继续向 origin 的同一工作分支 push，PR 会自动更新。上游合并后，同步自己的 main，再删除个人工作分支。

6.6 Fork 常见错误

origin 指向了原仓库：重新核对 git remote -v，必要时使用 git remote set-url origin <个人Fork地址>。
没有 upstream：使用 git remote add upstream <原仓库地址>。
PR 方向相反：关闭错误 PR，重新选择正确的 base 与 compare。
Fork 落后：先 fetch upstream 并同步目标基线，再更新功能分支。
无法 push：确认推送目标是有权限的个人 Fork，而不是无写权限的 upstream。

第七章 main-only 分支与交付

7.1 使用场景

本项目采用单一 main 长期分支。开发集成、验收和发布基线均围绕 main 的可审计提交完成；测试环境和发布候选使用固定提交 SHA、CI 记录和 Tag 表达，不创建额外长期环境分支。

`1`	`agent/* → main`

工作分支合并后删除；main 负责保存唯一长期基线，发布候选和回滚点由 Tag 及测试证据记录。

7.2 分支职责

分支	主要职责	允许进入的内容	典型门禁
`main`	唯一长期集成、验收和发布基线	通过 PR 和 CI 检查的任务改动	构建、静态/类型检查、测试、发布记录
`agent/*`	单项功能、修复、重构或文档任务	与一个任务边界对应的可审查改动	本地验证、影响面检查、PR、CI

main 应受保护。开发者从最新 main 创建 agent/<任务说明> 短期工作分支，通过 PR 和 CI 合入 main，不直接在 main 提交或推送。本项目不设置 Reviewer 数量作为强制合并门禁，由 Owner 完成检查和合并。

7.3 正向交付

普通功能从最新 main 创建：

1
2
3

git switch main
git pull --ff-only origin main
git switch -c agent/search-filter

完成后通过 agent/search-filter → main PR 合并。PR 必须记录源分支、目标分支、纳入范围、验证结果、已知风险和回退方式。发布候选从已合入 main 的固定 SHA 创建 Tag，不创建长期候选分支。

7.4 并行开发和批次边界

多个任务可以并行使用各自的短期工作分支；每个 PR 必须明确提交范围，避免把无关改动带入 main。发布候选以选定的 main SHA、Tag、构建摘要和测试记录冻结；测试期间的新改动必须通过新的 PR 合入 main，不得修改既有候选证据。

7.5 测试缺陷

测试缺陷从最新 main 创建临时 agent/* 修复分支：

1
2
3

git switch main
git pull --ff-only origin main
git switch -c agent/test-empty-result

修复通过 PR 合回 main 后，以新的提交 SHA 重新生成受影响的测试和发布候选证据。不得在已冻结的 Tag 或已发布提交上直接修复，也不需要在环境分支之间回流。

7.6 发布阶段缺陷和 Hotfix

正式版本的紧急问题也从 main 创建 agent/*：

1
2
3

git switch main
git pull --ff-only origin main
git switch -c agent/session-expiry

紧急修复必须保持最小范围，验证后通过 PR 合入 main，再创建新的 PATCH Tag。回滚以最近一次已验证 Tag 为准，不设置额外长期回流分支。

7.7 Cherry pick 的边界

git cherry-pick <commit> 会把指定提交的改动复制到当前分支，并生成新的提交。它适合回补单一、独立的修复，不适合替代正常分支晋级。

使用前检查：

git status
git branch --show-current
git show <commit>
git cherry-pick <commit>

使用后重新运行测试并在 PR 中记录原始提交。不得在长期分支之间进行无记录的 cherry-pick。

第八章 Pull Request 与代码评审

8.1 PR 描述模板

## 背景
说明为什么需要这项修改，以及关联的 Issue。

## 改动
- 列出本 PR 实际完成的内容。
- 明确未包含的内容。

## 验证
- 命令或操作：
- 结果：

## 影响和风险
- 受影响范围：
- 已知风险：
- 回退方式：

## 作者检查
- [ ] 已查看全部 diff
- [ ] 未包含凭据或无关文件
- [ ] 已完成必要测试
- [ ] 目标分支正确

8.2 三种 Review 结果

Comment：提出问题或建议，不代表批准或阻断。
Approve：评审者认为改动满足合并要求。
Request changes：存在必须处理的问题，处理前不应合并。

评审意见应指向具体文件和行为，说明风险或期望结果。例如，“空列表时这里会访问第一个元素，建议先处理长度为零的情况”比“这里写得不好”更容易执行。

8.3 作者自检

创建 PR 前确认：

改动与任务范围一致。
每个文件都经过 diff 检查。
提交中没有凭据、临时文件和调试输出。
测试和检查结果真实可复现。
PR 目标仓库和目标分支正确。
描述说明了为什么修改，而不只是重复文件名。
回退方式与风险相匹配。

8.4 评审者检查

评审者至少检查：

需求和实际改动是否一致。
正常路径、异常路径和边界条件是否合理。
是否引入越权、敏感信息或不可信输入风险。
是否存在无关改动、重复实现或难以维护的结构。
测试能否覆盖关键行为和历史缺陷。
分支方向、检查结果和合并方式是否正确。

8.5 常见 PR 问题

PR 过大：拆成可以独立评审和验证的改动，不把功能、重构、依赖升级和格式化混在一起。
目标分支错误：在合并前修改 base branch，重新检查完整 diff。
分支落后：先 fetch，再按团队规定合并目标分支或更新候选基线。
自动检查失败：阅读失败日志并修复根因，不重复点击直到偶然通过。
评审会话未处理：逐项回复修改结果或解释不采纳的理由。

第九章冲突处理与安全撤销

9.1 为什么出现冲突

当两个分支修改同一文件的相同区域，Git 无法自动判断最终内容，就会标记冲突。冲突不是 Git 损坏，而是需要开发者理解双方意图并作出选择。

冲突文件可能包含：

"<<<<<<< HEAD"
当前分支的内容
"======="
待合并分支的内容
">>>>>>> other-branch"

不要只删除标记后提交。应确认两侧修改的目的，决定保留一侧、组合两侧或重新编写正确结果。

9.2 命令行解决冲突

发生冲突后：

1
2

git status
git diff --name-only --diff-filter=U

逐个编辑冲突文件，完成后：

1
2
3

git add path\to\resolved-file
git status
git commit

如果尚未完成任何有价值的冲突解决，可以取消本次合并：

`1`	`git merge --abort`

9.3 使用 VS Code Merge Editor

VS Code 会在“源代码管理”视图中列出冲突文件。打开文件后可使用 Merge Editor 查看 Current、Incoming 和 Result。选择内容后必须检查 Result，而不是仅点击 Accept Current 或 Accept Incoming。

保存解决结果，暂存文件，完成合并提交，再执行受影响的测试。界面按钮只是帮助编辑，不能替代对业务含义的判断。

9.4 按状态选择撤销方式

当前状态	推荐操作	说明
未暂存修改	`git restore <file>`	丢弃工作区修改，执行前检查 diff
已暂存但未提交	`git restore --staged <file>`	取消暂存，不丢弃工作区内容
本地最新提交需修改	新提交修正，或在未共享时谨慎 amend	是否改写历史取决于是否已推送
已推送提交需撤销	`git revert <commit>`	创建反向提交，保留公共历史
合并进行中且需取消	`git merge --abort`	返回合并开始前状态

git reset --hard 会同时移动分支并丢弃工作区与暂存区内容。强制推送会覆盖远程历史。这两类操作不属于初学者日常流程；确需使用时，应先取得负责人确认并建立可恢复备份。

9.5 使用 revert

查看目标提交：

1
2
3

git show <commit>
git revert <commit>
git status

revert 不删除原提交，而是创建一个撤销其效果的新提交，因此适合已经共享的分支。发生冲突时按正常冲突流程解决，然后完成 revert。

第十章故障排查

10.1 排查原则

先使用只读命令收集状态，再决定修改动作。推荐顺序：

Get-Location
git status
git branch --show-current
git remote -v
git log --oneline --graph --decorate -10
git diff
git diff --staged

不要在原因不明时连续执行 reset、clean、强制推送或删除分支。这些命令可能让原本容易恢复的问题变得不可恢复。

10.2 常见问题表

现象	可能原因	先检查	安全处理
`not a git repository`	当前目录不在仓库内	`Get-Location`、查看父目录	进入正确仓库目录
修改出现在错误分支	开始工作前未切分支	`git status`、`git branch --show-current`	先保存改动，再创建正确分支
push 被拒绝	远程已有新提交或无权限	`git fetch`、`git remote -v`	核对权限和分支差异后同步
non-fast-forward	本地与远程分叉	`git log --graph --all`	按团队规则合并或更新，不强推
无法认证	凭据过期或授权范围不足	仓库地址、凭据管理器、账号权限	重新授权或联系管理员
PR 文件异常多	基线或目标分支选错	PR base、`git merge-base`	改正 base 或从正确基线重建分支
Fork 无法同步	upstream 未配置或本地主分叉	`git remote -v`、`git log`	添加 upstream，调查独立提交
detached HEAD	检出了具体提交	`git status`	从当前提交创建分支保存工作
已提交敏感信息	文件进入提交历史	`git show`、确认暴露范围	立即撤销凭据并联系管理员
阶段修复未回流	只修复了高阶段分支	比较各长期分支	创建回流 PR 并完成验证

10.3 保存错误分支上的修改

修改尚未提交时，可以直接从当前位置创建正确分支：

1
2

git switch -c fix/correct-branch
git status

如果目标分支已经存在，可先暂存到 stash：

1
2
3

git stash push -u -m "temporary work before branch switch"
git switch fix/correct-branch
git stash pop

stash pop 可能产生冲突。执行前应确认目标分支，执行后检查 git status 和差异。

10.4 Push 被拒绝

先确认推送对象：

git branch -vv
git remote -v
git fetch origin
git log --oneline --graph --decorate --all -15

如果远程分支包含新提交，按团队规则更新本地分支并解决冲突。不要把 git push --force 当作通用解决方案。受保护分支被拒绝通常是正确行为，应创建 PR，而不是尝试绕过规则。

10.5 Detached HEAD

如果在 detached HEAD 状态完成了有价值的提交，先创建分支保存：

`1`	`git switch -c rescue/saved-work`

确认提交已由新分支引用后，再决定如何通过 PR 合入正确目标。不要在未保存引用时随意切换到其他提交。

附录 A 高频命令速查

目的	命令	是否修改状态
查看状态	`git status`	否
查看当前分支	`git branch --show-current`	否
查看未暂存差异	`git diff`	否
查看已暂存差异	`git diff --staged`	否
查看历史	`git log --oneline --graph`	否
下载远程状态	`git fetch origin`	更新远程引用，不改工作区
创建并切换分支	`git switch -c <branch>`	是
暂存文件	`git add <file>`	是
取消暂存	`git restore --staged <file>`	是
提交	`git commit -m "message"`	是
首次推送分支	`git push -u origin <branch>`	修改远程仓库
安全更新当前分支	`git pull --ff-only`	可能修改工作区和本地历史
合并分支	`git merge <branch>`	可能修改工作区和历史
撤销已共享提交	`git revert <commit>`	创建新提交
删除已合并本地分支	`git branch -d <branch>`	是

附录 B 操作检查清单

B.1 开始工作前

已确认任务目标、范围和验收条件。
PowerShell 位于正确仓库目录。
git status 没有未处理修改。
当前处于正确基线分支。
已 fetch 并安全更新基线。
已为任务创建独立工作分支。

B.2 提交前

已查看 git diff。
只暂存本次提交需要的文件。
已查看 git diff --staged。
没有凭据、调试输出或无关格式化。
已执行与改动匹配的检查或测试。
提交信息准确说明单一意图。

B.3 创建 PR 前

分支已经推送到正确远程仓库。
base repository 和 base branch 正确。
Files changed 只包含任务范围内的改动。
PR 描述包含背景、改动、验证、风险和回退。
已处理可见的自动检查失败。
已指定合适的评审者。

B.4 阶段晋级前

源分支和目标分支正确。
本批次范围和候选提交已明确。
当前阶段门禁全部满足。
缺陷修复已经回流到较低阶段分支。
PR 记录验证证据、风险和回退方式。
没有未经批准的越级合并。

B.5 合并后

已确认 PR 实际进入正确目标分支。
已更新本地基线分支。
已删除不再需要的工作分支。
Issue、发布记录或阶段记录已更新。
后续分支需要回流时已创建对应 PR。

附录 C 术语表

术语	含义
Git	分布式版本控制系统
GitHub	Git 仓库托管与协作平台
Repository	保存文件、提交、分支和标签的仓库
Working tree	当前可编辑的工作区文件
Staging area	下一次提交准备包含的暂存内容
Commit	带有说明和父级关系的版本快照
Branch	指向提交历史的可移动引用
Remote	远程仓库的名称与地址配置
origin	默认远程名；Fork 流程中通常指个人 Fork
upstream	Fork 流程中通常指原始仓库
Clone	把远程 Git 仓库复制到本地
Fork	在自己的托管账号下创建远程仓库副本
Pull Request	请求将一个分支的改动合入另一个分支
Review	对 PR 差异进行评论、批准或要求修改
Merge	整合两条提交历史
Conflict	Git 无法自动决定合并结果的重叠修改
HEAD	当前检出位置的引用
Tag	指向特定提交的固定版本标记
Hotfix	针对正式稳定版本的紧急最小修复
CI	持续集成，自动执行构建、测试和检查

附录 D 参考资料

本指南的 Git 命令和平台术语以以下官方资料为主要依据。软件界面可能更新，使用时以官方最新说明为准。

变更记录

v1.0.0 2026-09-14：首次发布，包含 Git 与 GitHub 基础、功能分支、Fork、Pull Request、多阶段分支、评审、冲突、安全撤销和排错内容。

一文真正读懂卷积神经网络（CNN）：从卷积公式到 PyTorch 实践

Fri, 04 Sep 2026 09:00:00 +0800

CNN（Convolutional Neural Network，卷积神经网络）是一类擅长处理网格状数据的深度学习模型。我们最熟悉的网格状数据就是图像，所以 CNN 常常用于图像分类、检测和分割。除此之外，它也可以处理语音时频图、时间序列和三维体数据。

如果只把 CNN 记成“卷积层 + 池化层 + 全连接层”，我们也许能照着代码搭出模型，却不一定真正理解它为什么有效。因此，这篇文章会从图像在计算机中的表示方式讲起，再一步步介绍卷积、池化、归一化、感受野和训练过程。文章最后还准备了一个可以直接运行的 CIFAR-10 分类示例，方便我们把前面的概念落到代码上。

图 1：典型 CNN 数据流。空间分辨率通常逐层减小，通道数通常逐层增加，但这不是必须遵守的定律。

一. CNN 解决了全连接网络的什么问题？

在介绍 CNN 之前，我们先看看普通全连接网络面对图像时会遇到什么问题。一张 RGB 图像可以表示为 $C\times H\times W$ 的张量。如果图像大小为 $224\times224$，那么仅输入就包含 $3\times224\times224=150{,}528$ 个数。假设再把它们直接连接到 1,000 个神经元，大约需要 1.5 亿个权重。这不仅计算代价很高，还会把原本相邻的像素当成彼此无关的数字，忽略图像本身的空间结构。

CNN 主要通过下面三个特点来解决这个问题：

局部连接：每个输出只关注输入中的一小块区域。这很符合图像的特点，因为相邻像素之间通常比距离很远的像素联系更紧密。
参数共享：同一个卷积核会在图像的不同位置重复使用。也就是说，如果它学会了检测某种边缘，就不需要在每个位置从头学一遍。
分层表示：浅层通常先学习边缘、颜色和纹理，更深的网络层再把这些局部模式组合起来，逐渐形成物体部件甚至更完整的语义特征。

参数共享还带来一个重要性质：当输入图像平移时，卷积得到的特征图也会跟着平移，这种性质叫作平移等变性。不过，“等变”并不等于“不变”：它不能保证图像无论怎样平移，分类结果都完全一样。下采样、边界处理、数据增强和最后的特征聚合方式，都会影响模型对平移的适应能力。

二. 输入不是“图片”，而是张量

在我们眼中，输入是一张张图片；但在神经网络眼中，它们其实是由数字组成的多维数组，也就是张量。深度学习框架常用下面两种方式排列图像数据：

NCHW：$(N,C,H,W)$，PyTorch 默认使用；
NHWC：$(N,H,W,C)$，部分框架和硬件更偏好。

其中，$N$ 表示一次送入模型的图像数量，$C$ 表示通道数，$H$ 和 $W$ 分别表示高度和宽度。例如，一批有 64 张 CIFAR-10 彩色图像，每张图像包含 3 个颜色通道，尺寸为 $32\times32$，那么它在 PyTorch 中的形状就是 $(64,3,32,32)$。

常见预处理包括：

$$ x'=\frac{x/255-\mu}{\sigma} $$

这里的 $\mu$ 和 $\sigma$ 分别是均值和标准差，应当在训练集上按通道统计。验证集和测试集要使用同样的变换。在训练阶段，我们还常会通过随机裁剪、翻转和颜色扰动来增加数据的多样性；而在验证和测试时，则不应再使用会随机改变样本语义的增强。

三. 卷积层：局部加权求和

3.1 从一次卷积计算说起

卷积操作的基本想法并不复杂：用一个较小的卷积核在输入上滑动，每到一个位置，就将对应元素相乘后求和。对于单通道输入，当卷积核大小为 $K_h\times K_w$、步幅为 $S_h,S_w$、膨胀率为 $D_h,D_w$ 时，输出位置 $(i,j)$ 的计算可以写成：

$$ Y_{i,j}=b+\sum_{u=0}^{K_h-1}\sum_{v=0}^{K_w-1} W_{u,v}\,X_{iS_h+uD_h-P_h,\;jS_w+vD_w-P_w}. $$

如果计算位置超出了输入边界，就按照填充规则处理。这里还有一个容易混淆的细节：严格意义上的数学卷积会先翻转卷积核，而 PyTorch 等深度学习框架通常直接计算互相关（cross-correlation）。不过，由于卷积核的参数是从数据中学出来的，翻不翻转并不影响模型的表达能力，所以大家仍然习惯把这一运算叫作“卷积”。

图 2：一个 3×3 核在 5×5 输入上滑动。图中只展开了一个输出位置的计算。

3.2 多输入通道与多输出通道

真实的彩色图像通常包含多个通道。因此，卷积核不仅要在高和宽的方向上滑动，还要同时覆盖全部输入通道。先不考虑分组卷积，第 $o$ 个输出通道可以写成：

$$ Y_{n,o,i,j}=b_o+ \sum_{c=0}^{C_{in}-1}\sum_{u=0}^{K_h-1}\sum_{v=0}^{K_w-1} W_{o,c,u,v}\,X_{n,c,iS_h+uD_h-P_h,jS_w+vD_w-P_w}. $$

简单来说，一个普通卷积核会跨过所有输入通道，最后生成一张特征图。如果设置 $C_{out}$ 组卷积核，就会得到 $C_{out}$ 张特征图。此时权重张量的形状为：

$$ (C_{out},\ C_{in}/G,\ K_h,\ K_w), $$

其中 $G$ 就是 groups。普通卷积中 $G=1$；当 $G=C_{in}$ 时，就进入了深度卷积（depthwise convolution）的核心情形。

3.3 输出尺寸

卷积计算完成后，特征图究竟会变成多大？要回答这个问题，我们先定义卷积核的有效尺寸：

$$ K_{eff}=D(K-1)+1. $$

则高度方向输出尺寸为：

$$ H_{out}=\left\lfloor \frac{H_{in}+2P_h-D_h(K_h-1)-1}{S_h}+1 \right\rfloor, $$

宽度同理：

$$ W_{out}=\left\lfloor \frac{W_{in}+2P_w-D_w(K_w-1)-1}{S_w}+1 \right\rfloor. $$

例如，当 $H_{in}=32,K=3,S=1,P=1,D=1$ 时，可以算得 $H_{out}=32$，也就是说卷积前后的高度没有变化。这就是我们常说的 same-size 卷积。需要注意的是，不同框架对字符串 padding="same" 与步幅组合的支持可能不同，实际使用时应以具体的 API 文档为准。

图 3：填充、步幅和膨胀率分别影响边界、采样间隔与有效感受范围。

3.4 参数量与计算量

分组卷积的可训练参数量为：

$$ \#\mathrm{params}=C_{out}\left(\frac{C_{in}}{G}K_hK_w+\mathbf{1}_{bias}\right). $$

以 Conv2d(3, 32, 3, padding=1) 为例，若包含偏置：

$$ 32\times(3\times3\times3+1)=896. $$

从公式中可以看出，卷积层的参数量与输入图像的高和宽无关。不过，图像越大，卷积核需要滑动的位置越多，乘加运算量仍然会增长。粗略的乘加次数为：

$$ \mathrm{MACs}=H_{out}W_{out}C_{out}\frac{C_{in}}{G}K_hK_w. $$

还要留意，不同工具的统计方式并不完全一致。有的工具把一次乘法和一次加法合计为 1 MAC，有的则计为 2 FLOPs。所以在比较模型时，最好一并说明统计口径。

四. 激活函数：让网络学会更复杂的特征

如果层与层之间只有线性变换，那么无论堆叠多少层，整个网络最后仍然只相当于一次线性变换，无法表示复杂的特征。激活函数的作用，就是为网络引入非线性。ReLU 是 CNN 中最经典的激活函数：

$$ \operatorname{ReLU}(x)=\max(0,x),\qquad \operatorname{ReLU}'(x)= \begin{cases} 1,&x>0\\ 0,&x<0 \end{cases} $$

ReLU 的计算很简单，并且在正半轴能保持稳定的梯度。它也有缺点：有些神经元可能长期落在负半轴，输出和梯度一直为 0，从而停止更新，这就是所谓的“死亡 ReLU”。一种常见的替代方案是 Leaky ReLU：

$$ \operatorname{LeakyReLU}(x)=\max(\alpha x,x),\quad \alpha>0. $$

GELU、SiLU 等更平滑的激活函数，在现代网络中也很常见。没有哪一种激活函数能在所有任务上都表现最好，实际使用时仍然需要通过验证集进行选择。

五. 归一化：让中间特征更稳定

随着网络不断加深，中间特征的数值范围可能发生较大变化，这会给训练带来困难。二维批归一化（Batch Normalization，BN）会针对每个通道，利用一个 mini-batch 中 $N,H,W$ 这些位置上的数值统计均值和方差：

$$ \hat{x}=\frac{x-\mu_B}{\sqrt{\sigma_B^2+\epsilon}},\qquad y=\gamma\hat{x}+\beta. $$

$\gamma$ 和 $\beta$ 是可以通过训练学习的参数。BN 在训练时使用当前批次的统计量，同时更新移动统计量；在推理时，通常使用训练阶段积累下来的统计量。正因如此，训练前需要调用 model.train()，验证或推理前则要调用 model.eval()。

当批量很小时，BN 计算出的统计量可能不够稳定，这时可以考虑 GroupNorm 或 LayerNorm。常见的卷积块顺序是 Conv → BN → ReLU。如果 BN 紧跟在卷积层后，并且开启了仿射参数，那么卷积层的偏置通常可以关闭，因为 BN 中已经有可学习的平移量 $\beta$。

六. 池化与下采样

对窗口 $\Omega_{i,j}$，最大池化和平均池化分别为：

$$ y_{i,j}^{max}=\max_{(u,v)\in\Omega_{i,j}}x_{u,v}, \qquad y_{i,j}^{avg}=\frac{1}{|\Omega_{i,j}|}\sum_{(u,v)\in\Omega_{i,j}}x_{u,v}. $$

图 4：2×2、步幅为 2 的最大池化与平均池化。

池化层本身没有需要学习的权重。它的主要作用是降低特征图的空间分辨率，从而减少计算，同时扩大后续单元的有效感受野。最大池化倾向于保留局部区域中的强响应，平均池化则保留局部平均信息。

池化可以带来一定的局部平移鲁棒性，但不能简单地说“池化一定能防止过拟合”。模型是否过拟合，还会受到模型容量、数据量、数据增强、正则化方法和训练过程等多种因素的影响。

在现代 CNN 中，人们也常用带步幅的卷积来完成可学习的下采样。到了分类网络的末端，则经常使用全局平均池化：

$$ z_c=\frac{1}{HW}\sum_{i=1}^{H}\sum_{j=1}^{W}x_{c,i,j}, $$

它会把每个通道压缩成一个数。这样既能避免使用庞大的全连接层，也让模型可以接收一定范围内、尺寸不完全相同的输入。

七. 感受野：深层为什么能看到更大范围？

感受野，指的是某个特征位置在理论上会受到输入图像中哪些像素的影响。我们可以把它理解为该位置在原图上“能看到的范围”。设第 $l$ 层之前的感受野为 $r_{l-1}$，相邻特征点在原输入上的间隔为 $j_{l-1}$，则：

$$ j_l=j_{l-1}S_l, $$$$ r_l=r_{l-1}+(K_l-1)D_lj_{l-1}, $$

初始时 $r_0=j_0=1$。两个步幅为 1 的 3×3 卷积叠加后，可以得到 5×5 的理论感受野；叠加三个时，则可以得到 7×7 的理论感受野。按单通道简化计算，三个 3×3 卷积只需要 $3\times9=27$ 个空间核权重，少于单个 7×7 卷积核的 49 个权重，而且中间还多了两次非线性变换。

不过，理论感受野并不等于有效感受野。在真实网络中，感受野内部不同位置对输出的影响通常并不均匀。

八. 分类头、Softmax 与交叉熵

经过前面的卷积主干和全局平均池化后，模型已经把一张图像压缩成了一组特征。接下来，线性层会生成 $C$ 个 logits：

$$ \mathbf{z}=W\mathbf{h}+\mathbf{b}. $$

logits 可以理解为模型对各个类别给出的原始分数。Softmax 会再把这些分数转换为概率：

$$ p_c=\frac{e^{z_c}}{\sum_{k=1}^{C}e^{z_k}}. $$

单个样本、真实类别为 $y$ 时，交叉熵为：

$$ \mathcal{L}=-\log p_y =-z_y+\log\sum_{k=1}^{C}e^{z_k}. $$

实际编程时，我们应当使用数值更稳定的组合实现。PyTorch 的 nn.CrossEntropyLoss 接收的是未归一化的 logits，它在内部已经完成了等价于 log_softmax + NLLLoss 的计算。因此，训练代码中不要在输入交叉熵损失前手动调用 softmax。

九. CNN 是怎样学会卷积核的？

前面介绍的卷积核并不是由人手工指定的，而是模型在训练过程中逐渐学会的。训练的目标，是让模型在训练集上的平均损失尽可能小。我们还可以在目标中加入权重衰减等正则项：

$$ \min_{\theta}\ \frac{1}{N}\sum_{i=1}^{N}\mathcal{L} \bigl(f_{\theta}(x_i),y_i\bigr)+\lambda R(\theta). $$

一次 mini-batch 的训练大致包含下面几个步骤：

进行前向传播，得到 logits 和损失；
进行反向传播，利用链式法则计算 $\nabla_{\theta}\mathcal{L}$；
由优化器更新参数，例如最基本的 SGD：

$$ \theta_{t+1}=\theta_t-\eta\nabla_{\theta}\mathcal{L}_t; $$

在独立的验证集上观察模型的泛化能力，并据此调整超参数。测试集只留到最后做一次正式评估。

Dropout、权重衰减、数据增强、早停和增加数据量，都可以帮助缓解过拟合，但具体怎样选择，仍然要看验证集上的表现。只看到训练损失下降，并不能说明模型没有过拟合。我们必须把训练集和验证集的指标放在一起观察。

十. 一个尺寸可以逐层核对的小型 CNN

理解了前面的概念后，我们再来看一个具体的网络。下面这个小型 CNN 适用于 32×32 的 RGB 图像，每一层的输出尺寸都可以直接核对：

阶段	操作	输出形状（省略批维）
输入	—	$3\times32\times32$
Block 1	3×3 Conv, BN, ReLU	$32\times32\times32$
Block 2	3×3 Conv, stride 2, BN, ReLU	$64\times16\times16$
Block 3	3×3 Conv, stride 2, BN, ReLU	$128\times8\times8$
聚合	Global Average Pooling	$128\times1\times1$
分类	Flatten, Linear	$10$ logits

核心模型代码如下：

import torch
from torch import nn


class SmallCNN(nn.Module):
    def __init__(self, num_classes: int = 10):
        super().__init__()
        self.features = nn.Sequential(
            nn.Conv2d(3, 32, 3, padding=1, bias=False),
            nn.BatchNorm2d(32),
            nn.ReLU(inplace=True),

            nn.Conv2d(32, 64, 3, stride=2, padding=1, bias=False),
            nn.BatchNorm2d(64),
            nn.ReLU(inplace=True),

            nn.Conv2d(64, 128, 3, stride=2, padding=1, bias=False),
            nn.BatchNorm2d(128),
            nn.ReLU(inplace=True),
        )
        self.pool = nn.AdaptiveAvgPool2d(1)
        self.classifier = nn.Linear(128, num_classes)

    def forward(self, x: torch.Tensor) -> torch.Tensor:
        x = self.features(x)
        x = self.pool(x)
        x = torch.flatten(x, 1)
        return self.classifier(x)  # logits，不要在这里 softmax


model = SmallCNN()
dummy = torch.randn(8, 3, 32, 32)
assert model(dummy).shape == (8, 10)

完整且可运行的 CIFAR-10 训练与评估脚本，可以在同目录的 cnn_cifar10.py 中找到。脚本中包含了训练和测试数据变换、训练循环、评估函数、随机种子和最佳权重保存。这里不预先承诺某一个准确率，因为实际结果会受随机性、PyTorch 版本、硬件、训练轮数和超参数等多种因素影响。

十一. 从经典 CNN 到现代架构

LeNet-5（1998）：把局部感受野、共享权重和下采样用于手写字符识别，是 CNN 发展史上的标志性系统之一。将 CNN 简单归为某一个人的“单独发明”并不严谨；相关思想由多项早期工作逐步形成，LeCun、Bottou、Bengio 与 Haffner 的论文系统展示了其在文档识别中的效果。
AlexNet（2012）：在大规模 ImageNet 任务中结合深层 CNN、GPU 训练、ReLU、数据增强与 Dropout，显著推动了深度学习在视觉领域的普及。
VGG（2014）：展示了重复堆叠小型 3×3 卷积的简洁设计。
ResNet（2015/2016）：通过快捷连接学习残差映射：

$$ \mathbf{y}=\mathcal{F}(\mathbf{x},W)+\mathbf{x}, $$

这种结构缓解了深层普通网络中的优化退化问题。这里所说的“退化”，是指更深的普通网络反而出现更高的训练误差，它和过拟合并不是一回事。

此后，深度可分离卷积、空洞卷积、注意力机制以及 ConvNeXt 等设计也相继出现。如今，视觉 Transformer 已经成为一条重要的技术路线，但 CNN 凭借局部性、计算效率和成熟的工具链，仍然广泛用于分类、检测、分割、姿态估计、医学影像和端侧部署等任务。

十二. 常见误区与排错清单

误区 1：卷积核都是 Sobel、锐化或高斯核

Sobel、锐化和高斯核这些手工滤波器，很适合帮助我们理解局部滤波。但是，CNN 中的卷积核通常从随机初始化出发，再通过反向传播从数据中学习。第一层有时会学出类似边缘或颜色检测器的模式，而更深层的特征就很难再用某个传统滤镜单独解释了。

误区 2：特征图数量由输入通道数决定

输出通道数不是由输入通道数自动决定的，而是由卷积层中的卷积核组数决定，对应参数就是 out_channels。每个普通卷积核都会跨越所有输入通道。

误区 3：网络越深一定越好

增加深度可以提高模型的表达能力，但也会增加优化难度、计算量、内存开销和过拟合风险。残差连接能让深层网络更容易优化，却不能保证只要继续增加层数，验证集上的性能就一定会提升。

误区 4：测试准确率越高，模型就一定可用

准确率很重要，但它不是唯一标准。我们还需要检查数据泄漏、类别不平衡、分布偏移、校准、鲁棒性、推理延迟和错误代价。对于不均衡数据，只报告总体准确率往往还不够，最好补充每类召回率、宏平均 F1、混淆矩阵或其他适合当前任务的指标。

训练排错清单

输入形状是否为模型期望的 NCHW，像素归一化是否与预训练权重匹配？
CrossEntropyLoss 前是否误加了 softmax？类别标签是否为 [0,C) 的整数？
每个 epoch 是否正确切换 model.train() 与 model.eval()？
验证时是否使用 torch.inference_mode()，并关闭随机数据增强？
是否同时记录训练损失、训练指标和验证指标，而不是仅观察一条曲线？
是否先让模型在极小数据集上过拟合，以验证数据、损失和梯度链路确实可工作？
保存的是验证指标最优权重，还是未经选择的最后一个 epoch？

十三. 小结

回过头来看，CNN 的核心并不是使用某种固定滤镜，而是让共享的小型卷积核从数据中学习，先在局部区域提取模式，再通过非线性、下采样和多层组合，逐渐得到分层特征。如果理解了下面四点，就基本抓住了 CNN 的主干：

卷积层通常执行互相关；权重由数据学习；
输出尺寸由输入、填充、步幅、核大小和膨胀率共同决定；
参数共享显著减少参数，并带来平移等变性；
模型的最终性能来自完整的训练系统，不只取决于网络层数。数据划分、数据增强、损失函数、优化、正则化和评估方法同样重要。

参考资料

参考文章：一文读懂卷积神经网络（CNN），知乎专栏。
Yann LeCun, Léon Bottou, Yoshua Bengio, Patrick Haffner, Gradient-Based Learning Applied to Document Recognition, Proceedings of the IEEE, 1998.
Alex Krizhevsky, Ilya Sutskever, Geoffrey E. Hinton, ImageNet Classification with Deep Convolutional Neural Networks, NeurIPS 2012.
Kaiming He, Xiangyu Zhang, Shaoqing Ren, Jian Sun, Deep Residual Learning for Image Recognition, CVPR 2016.
PyTorch Conv2d 官方文档：运算定义、参数、分组与输出尺寸。
PyTorch BatchNorm2d 官方文档：训练/推理统计量与计算公式。
PyTorch CrossEntropyLoss 官方文档：logits、类别索引与交叉熵定义。

附录：完整训练脚本

下面是 CIFAR-10 训练与评估的完整脚本，也可以直接下载：cnn_cifar10.py。

"""A compact, reproducible CIFAR-10 CNN baseline used by the companion blog.

Run:
    python cnn_cifar10.py --epochs 20 --data-dir ./data

The script downloads CIFAR-10 when it is not already present.
"""

from __future__ import annotations

import argparse
import random
from pathlib import Path

import numpy as np
import torch
from torch import nn
from torch.utils.data import DataLoader, Subset
from torchvision import datasets, transforms


CIFAR10_MEAN = (0.4914, 0.4822, 0.4465)
CIFAR10_STD = (0.2470, 0.2435, 0.2616)


class SmallCNN(nn.Module):
    def __init__(self, num_classes: int = 10) -> None:
        super().__init__()
        self.features = nn.Sequential(
            nn.Conv2d(3, 32, 3, padding=1, bias=False),
            nn.BatchNorm2d(32),
            nn.ReLU(inplace=True),
            nn.Conv2d(32, 64, 3, stride=2, padding=1, bias=False),
            nn.BatchNorm2d(64),
            nn.ReLU(inplace=True),
            nn.Conv2d(64, 128, 3, stride=2, padding=1, bias=False),
            nn.BatchNorm2d(128),
            nn.ReLU(inplace=True),
        )
        self.pool = nn.AdaptiveAvgPool2d(1)
        self.classifier = nn.Linear(128, num_classes)

    def forward(self, x: torch.Tensor) -> torch.Tensor:
        x = self.features(x)
        x = self.pool(x)
        x = torch.flatten(x, 1)
        return self.classifier(x)


def seed_everything(seed: int) -> None:
    random.seed(seed)
    np.random.seed(seed)
    torch.manual_seed(seed)
    if torch.cuda.is_available():
        torch.cuda.manual_seed_all(seed)


def make_loaders(
    data_dir: Path,
    batch_size: int,
    workers: int,
    seed: int,
    validation_size: int,
) -> tuple[DataLoader, DataLoader, DataLoader]:
    train_transform = transforms.Compose(
        [
            transforms.RandomCrop(32, padding=4),
            transforms.RandomHorizontalFlip(),
            transforms.ToTensor(),
            transforms.Normalize(CIFAR10_MEAN, CIFAR10_STD),
        ]
    )
    test_transform = transforms.Compose(
        [
            transforms.ToTensor(),
            transforms.Normalize(CIFAR10_MEAN, CIFAR10_STD),
        ]
    )
    augmented_train_set = datasets.CIFAR10(
        data_dir, train=True, download=True, transform=train_transform
    )
    evaluation_train_set = datasets.CIFAR10(
        data_dir, train=True, download=False, transform=test_transform
    )
    test_set = datasets.CIFAR10(data_dir, train=False, download=True, transform=test_transform)
    if not 1 <= validation_size < len(augmented_train_set):
        raise ValueError("validation-size must be between 1 and the training-set size")
    generator = torch.Generator().manual_seed(seed)
    indices = torch.randperm(len(augmented_train_set), generator=generator).tolist()
    validation_indices = indices[:validation_size]
    training_indices = indices[validation_size:]
    train_set = Subset(augmented_train_set, training_indices)
    validation_set = Subset(evaluation_train_set, validation_indices)
    pin_memory = torch.cuda.is_available()
    train_loader = DataLoader(
        train_set,
        batch_size=batch_size,
        shuffle=True,
        num_workers=workers,
        pin_memory=pin_memory,
        persistent_workers=workers > 0,
    )
    test_loader = DataLoader(
        test_set,
        batch_size=batch_size,
        shuffle=False,
        num_workers=workers,
        pin_memory=pin_memory,
        persistent_workers=workers > 0,
    )
    validation_loader = DataLoader(
        validation_set,
        batch_size=batch_size,
        shuffle=False,
        num_workers=workers,
        pin_memory=pin_memory,
        persistent_workers=workers > 0,
    )
    return train_loader, validation_loader, test_loader


def train_one_epoch(
    model: nn.Module,
    loader: DataLoader,
    loss_fn: nn.Module,
    optimizer: torch.optim.Optimizer,
    device: torch.device,
) -> tuple[float, float]:
    model.train()
    loss_sum = 0.0
    correct = 0
    count = 0
    for images, labels in loader:
        images = images.to(device, non_blocking=True)
        labels = labels.to(device, non_blocking=True)

        optimizer.zero_grad(set_to_none=True)
        logits = model(images)
        loss = loss_fn(logits, labels)
        loss.backward()
        optimizer.step()

        batch_size = labels.size(0)
        loss_sum += loss.item() * batch_size
        correct += (logits.argmax(dim=1) == labels).sum().item()
        count += batch_size
    return loss_sum / count, correct / count


@torch.inference_mode()
def evaluate(
    model: nn.Module,
    loader: DataLoader,
    loss_fn: nn.Module,
    device: torch.device,
) -> tuple[float, float]:
    model.eval()
    loss_sum = 0.0
    correct = 0
    count = 0
    for images, labels in loader:
        images = images.to(device, non_blocking=True)
        labels = labels.to(device, non_blocking=True)
        logits = model(images)
        loss = loss_fn(logits, labels)
        batch_size = labels.size(0)
        loss_sum += loss.item() * batch_size
        correct += (logits.argmax(dim=1) == labels).sum().item()
        count += batch_size
    return loss_sum / count, correct / count


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(description="Train a small CNN on CIFAR-10")
    parser.add_argument("--data-dir", type=Path, default=Path("data"))
    parser.add_argument("--epochs", type=int, default=20)
    parser.add_argument("--batch-size", type=int, default=128)
    parser.add_argument("--learning-rate", type=float, default=3e-3)
    parser.add_argument("--weight-decay", type=float, default=5e-4)
    parser.add_argument("--workers", type=int, default=2)
    parser.add_argument("--validation-size", type=int, default=5_000)
    parser.add_argument("--seed", type=int, default=42)
    parser.add_argument("--output", type=Path, default=Path("small_cnn_best.pt"))
    return parser.parse_args()


def main() -> None:
    args = parse_args()
    if args.epochs < 1 or args.batch_size < 1 or args.workers < 0:
        raise ValueError("epochs and batch-size must be positive; workers cannot be negative")

    seed_everything(args.seed)
    device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
    train_loader, validation_loader, test_loader = make_loaders(
        args.data_dir,
        args.batch_size,
        args.workers,
        args.seed,
        args.validation_size,
    )
    model = SmallCNN().to(device)
    loss_fn = nn.CrossEntropyLoss()
    optimizer = torch.optim.AdamW(
        model.parameters(), lr=args.learning_rate, weight_decay=args.weight_decay
    )
    scheduler = torch.optim.lr_scheduler.CosineAnnealingLR(optimizer, T_max=args.epochs)

    with torch.inference_mode():
        shape = model(torch.zeros(2, 3, 32, 32, device=device)).shape
    assert shape == (2, 10), f"Unexpected output shape: {shape}"

    best_accuracy = -1.0
    args.output.parent.mkdir(parents=True, exist_ok=True)
    print(f"device={device}; parameters={sum(p.numel() for p in model.parameters()):,}")
    for epoch in range(1, args.epochs + 1):
        train_loss, train_accuracy = train_one_epoch(model, train_loader, loss_fn, optimizer, device)
        validation_loss, validation_accuracy = evaluate(
            model, validation_loader, loss_fn, device
        )
        scheduler.step()
        print(
            f"epoch={epoch:02d} "
            f"train_loss={train_loss:.4f} train_acc={train_accuracy:.2%} "
            f"val_loss={validation_loss:.4f} val_acc={validation_accuracy:.2%}"
        )
        if validation_accuracy > best_accuracy:
            best_accuracy = validation_accuracy
            torch.save(
                {
                    "model_state": model.state_dict(),
                    "validation_accuracy": validation_accuracy,
                    "epoch": epoch,
                    "classes": test_loader.dataset.classes,
                },
                args.output,
            )

    checkpoint = torch.load(args.output, map_location=device)
    model.load_state_dict(checkpoint["model_state"])
    test_loss, test_accuracy = evaluate(model, test_loader, loss_fn, device)
    print(
        f"best_val_acc={best_accuracy:.2%}; "
        f"test_loss={test_loss:.4f}; test_acc={test_accuracy:.2%}; "
        f"checkpoint={args.output}"
    )


if __name__ == "__main__":
    main()

社团培训 on 望境

Agent 与 Vibe Coding：从想法到可验证交付

学习目标

一、四个容易混淆的概念

1.1 聊天助手

1.2 Coding Agent

1.3 Agentic Coding

1.4 Vibe Coding

二、Agent 能做什么，不能替你承担什么

三、把模糊想法变成任务契约

3.1 一个过于模糊的请求

3.2 一个可执行的请求

3.3 完成条件必须能观察

四、从计划到验收的闭环

4.1 先探索，再计划

4.2 小步实现

4.3 验证不是一句话

4.4 阅读 Diff

五、权限是技术设计，不是弹窗麻烦

5.1 最小权限

5.2 可逆性

5.3 外部文字可能是恶意输入

六、用 AGENTS.md 保存长期规则

七、贯穿案例：让 Agent 修改 Hugo 首页

7.1 准备隔离环境

7.2 提交任务

7.3 人工验收

八、七类高频风险

8.1 幻觉

8.2 需求漂移

8.3 能构建不等于正确

8.4 秘密泄露

8.5 破坏性操作

8.6 未审查依赖

8.7 自动化错误被放大

九、何时适合 Vibe，何时必须收紧

9.1 适合快速探索

9.2 必须工程化

十、常见错误方式

错误 1：只说“帮我做完”

错误 2：不让 Agent 运行测试

错误 3：看到绿色就接受

错误 4：把所有规则塞进每次提示

错误 5：把 Agent 当成责任主体

十一、练习

十二、交付检查清单

十三、小结

参考资料

服务器：从网络请求到 Linux 部署

学习目标

一、先建立正确的服务器概念

1.1 服务器既可以指机器，也可以指程序

1.2 IP、端口与进程

1.3 DNS 与域名

二、HTTP、HTTPS 与代理

2.1 HTTP 是请求与响应协议

2.2 HTTPS 增加什么

2.3 正向代理与反向代理

三、部署拓扑与占位符

四、第一次连接与 SSH 密钥

4.1 先确认云平台边界

4.2 生成密钥

4.3 不要直接照抄“关闭密码登录”

五、用户、更新和最小权限

六、配置 UFW 防火墙

七、安装并检查 Nginx

八、构建和上传 Hugo 站点

8.1 在本地构建

8.2 在服务器准备目录

8.3 上传文件

九、配置 Nginx 站点

十、域名与 HTTPS

10.1 证书签发前检查

10.2 使用当前官方说明安装 Certbot

十一、日志驱动的排错方法

11.1 四层定位

11.2 常见症状

十二、发布、回退与维护

12.1 发布前后

12.2 一个更安全的目录思路

六、用 `AGENTS.md` 保存长期规则

9.2 修改 `public/` 后又消失

第一章团队开发与版本控制