工程实践4 第11章：开发流程介绍¶

本章介绍工程实践4的核心开发流程，重点讲解如何借助 GitHub Codespaces 解决校园网络限制、如何通过配置文件驾驭 AI 编程 Agent，以及 AI 治理的基本原则。

1. GitHub Codespaces 在分支审查中的应用¶

1.1 问题背景：校园网络的挑战¶

在工程实践4的日常开发中，学生经常遭遇以下网络通信痛点：

场景	问题
克隆仓库	`git clone` 速度极慢（10 KB/s 以下）或超时
拉取依赖	`pip install` / `npm install` 频繁失败
AI 工具调用	GitHub Copilot、OpenAI API 在校园内网无法直连
预览效果	本地无法安装 Reflex / Node 环境，运行报错
分支对比审查	无法在本地快速切换分支、运行并对比 UI 差异

核心矛盾：评审同学提交的 PR 需要切换到对方的分支本地运行，但环境搭建耗时、网络不稳定导致体验极差，严重影响代码审查的质量和效率。

1.2 解决方案：GitHub Codespaces¶

GitHub Codespaces 是运行在 GitHub 云端的全功能 VS Code 开发环境，具备以下特性：

┌─────────────────────────────────────────────────────────┐
│           GitHub Codespaces 架构                         │
│                                                          │
│  浏览器 / VS Code Desktop                                │
│       ↕ WebSocket（HTTPS 443）                           │
│  Codespaces 容器（GitHub 数据中心）                       │
│       ↕ 直连 GitHub API / npm / PyPI                    │
│  GitHub 仓库                                             │
└─────────────────────────────────────────────────────────┘

对校园网的优势： - 所有网络请求发生在 GitHub 的数据中心，绕过校园出口带宽瓶颈 - 学生只需 HTTPS 443 端口访问浏览器，几乎不受校园防火墙限制 - Copilot 在 Codespaces 内开箱即用，无需额外代理配置

1.3 工作流：用 Codespaces 审查同学的分支¶

步骤 1：从 PR 界面一键启动 Codespace

在 GitHub 的 Pull Request 页面，点击右上角「Code」→「Codespaces」→「Create codespace on this branch」，系统自动：

拉取 PR 的源分支代码到云端容器
按照仓库根目录的 .devcontainer/devcontainer.json 安装依赖
在浏览器中打开 VS Code，直接进入对方的代码环境

步骤 2：运行项目，对比 UI 效果

# 在 Codespaces 终端中
reflex run          # 启动 Reflex 开发服务器（端口 3000）

Codespaces 会自动将端口 3000 转发（Port Forwarding），点击「在浏览器中打开」即可看到 PR 的实际运行效果，无需在本地安装任何环境。

步骤 3：对比分支差异

# 在 Codespaces 终端中切换到 main 分支对比
git stash
git checkout main
reflex run          # 端口 3001（VS Code 自动识别冲突并分配新端口）

此时两个标签页并排打开，可直观对比功能实现前后的 UI 差异。

步骤 4：添加审查意见

在 Codespaces 的 VS Code 界面中直接点击文件行号添加代码注释（Code Review Comment），提交后同步显示在 GitHub PR 的 Review 界面。

1.4 `.devcontainer` 配置规范¶

为确保所有同学的 Codespace 环境一致，仓库应提供标准配置：

// .devcontainer/devcontainer.json
{
  "name": "OA-EPP Dev",
  "image": "mcr.microsoft.com/devcontainers/python:3.11",
  "postCreateCommand": "pip install -r requirements.txt",
  "customizations": {
    "vscode": {
      "extensions": [
        "GitHub.copilot",
        "GitHub.copilot-chat",
        "ms-python.python",
        "charliermarsh.ruff"
      ]
    }
  },
  "forwardPorts": [3000, 8000],
  "portsAttributes": {
    "3000": { "label": "Reflex App", "onAutoForward": "openBrowser" }
  }
}

教师操作：在 OA-EPP 系统的「系统设置 → 仓库权限配置」中，可为每个学生仓库批量推送标准 .devcontainer 配置，确保 Codespaces 环境统一（对应功能需求 F-T-009）。

2. AI 治理¶

2.1 什么是 AI 治理¶

AI 治理（AI Governance）是指在使用 AI 工具辅助开发的过程中，建立规则、边界和责任机制，确保 AI 的输出可审计、可追溯、不产生安全或伦理风险。

在工程实践4中，AI 治理的核心关切点：

关切点	说明	本课程的应对措施
代码溯源	AI 生成的代码是否被原样提交，导致无法区分学生真实能力	所有 commit 需关联 Issue，PR 描述须说明 AI 参与比例
安全漏洞	AI 可能生成存在 SQL 注入、硬编码密钥等安全缺陷的代码	pr-agent 自动扫描安全警告，教师在 Code Review 中复核
版权合规	Copilot 生成的代码片段可能与开源代码高度相似	避免对关键业务逻辑直接使用 AI 补全；理解每一行代码
过度依赖	学生不理解代码含义，无法独立调试和演进	考试阶段禁用 Copilot；PR Review 要求口头解释实现思路
提示泄露	向 AI 提交包含学号、密码等敏感信息的 prompt	禁止在 prompt 中包含真实凭据；使用占位符或环境变量

2.2 负责任的 AI 使用原则（本课程规范）¶

理解优先：使用 Copilot 生成代码后，必须逐行理解其含义，方可提交
注明来源：PR 描述中用「AI 辅助」标注 AI 生成的主要模块
人工复核：涉及权限控制、数据校验的代码必须人工审查，不得直接接受 AI 建议
最小化授权：只在需要时启用 Copilot；在最终考核期间遵守禁用规定
数据保护：不向 AI 提交真实用户数据、数据库密码或 API 密钥

3. 编程 Agent 的配置、记忆与 Skill 功能¶

现代 AI 编程 Agent（如 GitHub Copilot Agent、Cursor、Cline 等）支持通过在仓库中放置特定的 Markdown 配置文件来定制化 Agent 的行为。掌握这些配置机制，是高效使用 AI 的核心能力之一。

3.1 配置功能：通过 `.md` 文件约束 Agent 行为¶

3.1.1 全局指令文件¶

文件路径	作用域	说明
`.github/copilot-instructions.md`	仓库全局	Copilot Chat / Agent 的默认行为约束，适用于所有对话
`.github/instructions/*.instructions.md`	按文件类型/目录匹配	通过 `applyTo` 字段限定生效范围，如「只对 Python 文件生效」
`AGENTS.md`（项目根目录）	仓库全局	OpenAI Codex / Claude Code 等 Agent 的指令文件

示例：.github/copilot-instructions.md

---
# 此文件约束所有 Copilot Agent 的行为
---

## 代码规范
- 所有 Python 文件使用 Ruff 格式化
- 函数命名使用 snake_case，类命名使用 PascalCase
- 禁止硬编码数据库连接字符串，必须从环境变量读取

## 提交规范
- commit message 格式：`feat(模块): 简要说明`
- 所有 commit 必须关联 Issue 编号

## 禁止行为
- 禁止生成包含 `eval()` 的代码
- 禁止直接输出 `print` 调试语句到生产代码

示例：.github/instructions/python.instructions.md（按文件类型生效）

---
applyTo: "**/*.py"
---
所有 Python 文件需在文件头部注明模块功能，
使用 `from __future__ import annotations` 启用延迟注解，
数据库操作必须使用参数化查询，禁止字符串拼接 SQL。

3.1.2 配置文件的加载机制¶

Agent 在每次对话开始时，按以下优先级加载配置：

1. 用户全局设置（~/.config/... 或 VS Code 用户设置）
2. 工作区设置（.vscode/settings.json）
3. 仓库级指令（.github/copilot-instructions.md）
4. 匹配当前文件的 .instructions.md（applyTo 筛选）
5. 当前对话的 session 指令（由 .prompt.md 注入）

越具体的规则优先级越高，后加载的规则覆盖前者。

3.1.3 Prompt 文件（`*.prompt.md`）¶

Prompt 文件定义可复用的对话模板，适合封装常见任务的标准提示词：

.github/prompts/
├── code-review.prompt.md       # 代码审查模板
├── write-test.prompt.md        # 编写测试用例模板
└── refactor-function.prompt.md # 重构函数模板

示例：write-test.prompt.md

---
mode: agent
description: 为选中的函数生成单元测试
---
分析选中的函数，生成完整的 pytest 单元测试文件：
1. 覆盖正常输入、边界值、异常输入三类场景
2. 使用 `pytest.mark.parametrize` 减少重复代码
3. Mock 外部依赖（数据库、网络请求）
4. 测试文件放在 `tests/` 目录，命名为 `test_<原文件名>.py`

3.2 记忆功能¶

Agent 的「记忆」解决了以下问题：如何让 Agent 在不同会话之间保持对项目上下文的了解？

3.2.1 记忆的层级结构¶

记忆层级（以 GitHub Copilot 增强插件为例）
├── 用户记忆（/memories/）
│     永久保存跨所有仓库的偏好、常见模式
│     例：「我喜欢用 TypeScript，不喜欢 any 类型」
│
├── 仓库记忆（/memories/repo/）
│     保存在当前仓库中的项目级知识
│     例：「本项目的数据库迁移命令是 reflex db upgrade」
│
└── 会话记忆（/memories/session/）
      仅在当前对话中有效的临时上下文
      例：「当前正在重构 auth 模块，不要修改 models.py」

3.2.2 记忆的写入与读取¶

手动触发：在对话中告诉 Agent「记住这个规则：……」，Agent 调用 storeMemory 工具写入文件。

自动总结：Agent 完成任务后，主动将本次的架构决策、踩坑经验写入记忆，供下次会话使用。

读取时机：Agent 每次回答与架构、规范、命名相关的问题前，先调用 queryMemory 检索已有知识，避免给出与项目规范冲突的建议。

3.2.3 记忆文件的最佳实践¶

<!-- /memories/repo/build-commands.md -->
## 构建与运行命令
- 启动开发服务器：`reflex run`（端口 3000）
- 执行数据库迁移：`reflex db makemigrations && reflex db upgrade`
- 运行测试：`pytest tests/ -v`
- 格式化代码：`ruff format . && ruff check --fix .`

## 项目约定
- 所有 State 类放在 `oa_epp/state/` 目录
- API 路由定义在 `oa_epp/backend/api.py`
- 禁止在 State 中直接写 SQL，必须通过 `db/queries.py` 中的函数

3.3 Skill 功能¶

Skill（技能）是将常见的多步骤工作流封装为可复用模块的机制，让 Agent 在识别到特定场景时自动调用标准化的操作流程。

3.3.1 Skill 文件结构¶

Skill 定义在 .github/skills/<skill-name>/SKILL.md：

.github/skills/
├── write-unit-tests/
│     └── SKILL.md    # 编写单元测试的完整工作流
├── fix-security-issue/
│     └── SKILL.md    # 修复安全漏洞的标准操作
└── pr-review/
      └── SKILL.md    # PR 代码审查的检查清单

3.3.2 SKILL.md 的内容结构¶

<!-- .github/skills/fix-security-issue/SKILL.md -->
# Skill: 修复安全漏洞

## 触发条件
当用户提到「安全漏洞」「SQL 注入」「XSS」「OWASP」时自动加载本技能。

## 工作流

### 第一步：定位问题
1. 使用 `grep_search` 搜索危险模式（如字符串拼接 SQL、`innerHTML =`）
2. 标记受影响的文件和行号

### 第二步：分析影响范围
- 检查该代码的调用链（使用 `vscode_listCodeUsages`）
- 确认是否有测试覆盖

### 第三步：修复
- SQL 注入 → 改用参数化查询（`?` 占位符或 ORM）
- XSS → 对输出进行 HTML 转义
- 硬编码密钥 → 移至环境变量，更新 `.env.example`

### 第四步：验证
- 运行相关测试：`pytest tests/ -k <相关模块>`
- 人工复核修改后的代码

## 输出格式
修复完成后，输出简要报告：
- 漏洞类型
- 受影响文件（行号）
- 修复方式摘要
- 是否需要进一步人工审查

3.3.3 Skill 与 Instructions 的区别¶

维度	Instructions（指令文件）	Skill（技能文件）
目的	约束 Agent 的默认行为和输出风格	提供特定任务的完整操作流程
加载时机	每次对话自动加载	按需加载（检测到相关意图时）
内容	规则、禁止事项、代码风格	步骤化工作流、工具调用序列
粒度	全局或按文件类型	按任务类型
示例	「所有变量名用小写下划线」	「如何完成一次完整的 PR Review」

3.3.4 本课程的 Skill 实践建议¶

在工程实践4中，建议团队在 .github/skills/ 下定义以下 Skill：

pr-checklist：PR 提交前的自检清单（代码质量、测试覆盖、文档更新）
debug-reflex-error：Reflex 框架常见报错的排查步骤
write-migration：数据库 Schema 变更的标准流程（Issue → 审批 → 迁移文件 → PR）
review-security：代码审查时的安全检查项（OWASP Top 10 对照）

4. 综合实践：在 Codespaces 中运用 AI Agent¶

以下是工程实践4中一个典型的 「用 Codespaces + Agent 完成 PR 审查」 完整流程：

1. 收到 PR 通知
   → 在 GitHub PR 页面点击「Codespaces」，一键启动云端环境

2. 加载项目上下文
   → Agent 自动读取 .github/copilot-instructions.md 和 memories/repo/
   → 了解本项目的技术栈、命名规范、禁止事项

3. 运行 PR 代码
   → 终端执行 `reflex run`，Codespaces 自动端口转发
   → 浏览器预览功能效果，发现 UI 与设计稿有出入

4. 触发 Skill：pr-review
   → 告诉 Agent 「开始 PR 审查，PR #42」
   → Agent 调用 pr-review Skill，按检查清单逐项核查：
     - 是否有对应 Issue？✓
     - 是否通过 CI？✓
     - 是否有测试？✗（缺失单元测试）
     - 是否有安全隐患？触发 fix-security-issue Skill 扫描

5. 生成审查报告
   → Agent 将审查意见整理为 GitHub Review Comments
   → 记录本次审查经验到 memories/session/

6. 关闭 Codespace
   → PR 审查完毕后停止 Codespace（避免消耗免费配额）

配额说明：GitHub 免费账户每月提供 120 小时 Codespaces 使用时间（2 核 CPU）和 15 GB 存储，对于工程实践4的日常使用完全足够。建议在不使用时及时停止（Stop）Codespace，避免后台空转消耗配额。

5. 快速原型设计与技术选型¶

5.1 快速原型设计工具¶

在进入正式编码之前，快速原型可以帮助团队对齐需求理解、发现交互问题，并大幅减少返工。以下工具能在数分钟内生成可交互的界面原型：

工具	特点	适用场景
Lovable	AI 驱动，自然语言描述 → 完整 React 应用，支持部署	需要快速生成有后端逻辑的全栈原型
Google Stitch	Google 官方 AI 原型工具，描述 → UI 组件+代码	快速生成 UI 组件和页面布局
v0.dev	Vercel 出品，生成 shadcn/ui 组件代码	React + Tailwind 技术栈的 UI 生成
bolt.new	StackBlitz 出品，浏览器内全栈开发环境	需要可运行的完整 Web 应用演示
Figma + AI 插件	设计师友好，生成高保真设计稿	视觉设计优先，需手工转代码

本课程使用的工具：工程实践4的 prototype/ 目录采用「AI 提示词生成静态 HTML + Tailwind CSS」方案，无需 Node.js 环境，任何浏览器直接打开即可预览。

5.2 用 AI 提示词生成原型静态页面¶

5.2.1 工作流程¶

1. 编写功能需求描述（以 docs/ 中的需求文档为输入）
        ↓
2. 向 AI（Copilot / Claude / GPT）发送提示词
        ↓
3. AI 生成 HTML + Tailwind CSS 静态页面
        ↓
4. 浏览器预览，调整细节
        ↓
5. 以静态原型为蓝图，实现 Reflex 组件

5.2.2 高质量提示词模板¶

生成一个学生端「课程列表」页面的静态 HTML 原型：

技术要求：
- 纯 HTML + Tailwind CSS CDN，无 JavaScript，无自定义 CSS
- 固定侧边栏布局：w-56, bg-white, border-r, fixed left-0 top-0
- 主内容区：ml-56, flex-1, p-6
- 配色方案：blue-600 作为主色

页面内容：
- 左侧导航：仪表盘/课程列表（active）/作业提交/成绩与反馈/课堂签到/在线考试/个人资料
- 主内容：课程卡片网格（3列），每张卡片包含课程名、教师、进度条、「进入课程」按钮
- 卡片数量：展示3门虚构课程（机器人系统/嵌入式开发/控制理论）

请直接输出完整 HTML 文件，不要解释。

5.2.3 静态原型转 Reflex 的映射规则¶

静态 HTML	Reflex 对应
`<aside class="...">`	`rx.el.aside(class_name="...")`
`<a href="xxx.html">`	`rx.link("文字", href="/xxx")`
`<div class="grid grid-cols-3">`	`rx.el.div(class_name="grid grid-cols-3")`
静态数据（硬编码课程名）	State 中的 `list[Course]` 变量
`<button onclick="...">`	`rx.button("...", on_click=State.handle_click)`
静态进度条宽度	`rx.el.div(style={"width": f"{State.progress}%"})`

转换原则：先保证外观 1:1 还原，再逐步将静态数据替换为 State 中的动态数据。

5.3 Reflex 与 Spring Boot + Vue 的对比¶

工程实践4选用 Reflex 作为开发框架，但在实际工程中需要了解它与主流企业级方案的差异，以便在不同场景下做出合理选择。

5.3.1 技术架构对比¶

Reflex（Python 全栈）               Spring Boot + Vue（前后端分离）
┌─────────────────────┐             ┌──────────────┐  ┌──────────────┐
│   Python State       │             │  Vue 3 前端   │  │ Spring Boot  │
│   （业务逻辑）        │             │  （UI 渲染）  │  │  后端 API    │
│        ↕             │             │      ↕        │  │      ↕       │
│   Reflex 编译器      │             │   HTTP/REST   │  │  JPA/MyBatis │
│        ↕             │             │   or GraphQL  │  │      ↕       │
│   React（前端）      │             └──────────────┘  │  MySQL/PG    │
│   WebSocket 同步     │                                └──────────────┘
└─────────────────────┘

5.3.2 全面对比¶

维度	Reflex	Spring Boot + Vue
学习曲线	低（只需 Python）	高（需同时掌握 Java/Spring + JS/Vue）
开发速度	快（全栈单语言，状态自动同步）	慢（前后端协作，接口联调耗时）
性能（并发）	中（Python GIL 限制，WebSocket 维持连接）	高（JVM JIT 优化，支持数万并发）
性能（响应延迟）	中（状态变更经 WebSocket 往返）	低（REST 无状态，CDN 缓存友好）
生产部署	简单（单进程，内置服务器）	复杂（需单独部署前端静态资源 + 后端服务）
扩展性	有限（垂直扩展为主）	强（水平扩展，微服务友好）
生态成熟度	新兴（2022年，组件库较少）	成熟（企业级首选，生态完备）
实时交互	天然支持（WebSocket 状态同步）	需额外集成（WebSocket/SSE/轮询）
适合团队规模	1-5 人小团队	5人以上，前后端分工明确
适合项目阶段	原型、MVP、内部工具	生产系统、高并发产品
嵌入式集成	方便（Python 可直接调用串口/GPIO 库）	需中间层（固件→Python/Node 桥接→Spring）

5.3.3 功能实现差异¶

功能	Reflex 实现	Spring Boot + Vue 实现
页面状态管理	Python `State` 类，字段自动同步到前端	Pinia/Vuex store，手动 fetch API
数据库操作	`with rx.session() as db:`	JPA Repository / MyBatis Mapper
表单验证	Python 侧 validator 方法	vee-validate（前端） + Bean Validation（后端）
实时更新	`rx.background` + `yield` 推送	WebSocket controller + Vue 监听
权限控制	State 中检查 `self.user_role`	Spring Security Filter Chain
文件上传	`rx.upload` 组件	Multipart Form + Vue el-upload

5.4 技术选型的一般方法¶

面对「用哪个框架」的问题，推荐按以下决策树逐步筛选：

步骤1：明确约束条件
  ├── 团队现有技术栈是什么？
  ├── 预期用户规模（并发数）是多少？
  └── 项目交付时间有多紧？

步骤2：评估关键需求
  ├── 是否需要高并发（>1000 QPS）？
  │     是 → 倾向 JVM/Go 方案
  │     否 → Python 方案可行
  ├── 是否有独立的前端团队/明确的前后端分工？
  │     是 → 前后端分离（Vue + REST API）
  │     否 → 全栈框架（Reflex / Next.js）
  └── 是否需要与嵌入式硬件直接通信？
        是 → Python（Reflex / FastAPI）优先
        否 → 任意框架

步骤3：原型验证
  先用成本最低的方案做可运行原型，验证核心假设，
  再根据实际反馈决定是否切换技术栈

核心原则：不存在「最好的框架」，只有「当前阶段最合适的框架」。选型时优先考虑团队能力和交付速度，而非技术先进性。

5.5 推荐研发路径：Reflex 原型 → Spring Boot + Vue 生产系统¶

对于工程实践4场景（原型快速验证 → 产品化演进），以下路径被证明是高效的：

阶段1：需求原型（第1-2周）
  工具：AI 提示词 → 静态 HTML + Tailwind CSS
  目的：对齐需求理解，与教师/用户确认交互设计
  产出：prototype/ 目录下的静态页面

阶段2：功能原型（第3-8周）
  工具：Reflex（Python 全栈）
  目的：实现完整功能，支持演示和迭代
  产出：可运行的 Reflex 应用，功能覆盖全部 Issue

阶段3：生产系统（毕业设计/企业项目）
  工具：Spring Boot + Vue 或 FastAPI + Vue
  目的：满足高并发、团队协作、运维需求
  产出：前后端分离的生产级应用

迁移成本分析：从 Reflex 迁移到 Spring Boot + Vue 时，以下内容可直接复用：

组件	复用比例	说明
数据模型（SQLModel/SQLAlchemy）	~80%	可转换为 JPA Entity 或 Pydantic → FastAPI
业务逻辑（State 方法）	~70%	可重构为 Service 层
UI 设计（Tailwind 类名）	~90%	直接用于 Vue 模板
数据库 Schema	~100%	相同的表结构，迁移脚本可复用
API 协议文档	~100%	Reflex 的状态变更逻辑即 API 草案

核心价值：Reflex 阶段解决的是「做什么」的问题，让团队在低成本下快速验证产品方向；Spring Boot + Vue 阶段解决的是「如何做好」的问题，在产品方向确定后进行工程化。跳过 Reflex 原型阶段直接用 Spring Boot + Vue 开发，往往会在不确定的需求上浪费大量工程时间。

6. 基于 GitHub 的持续软件产品开发¶

本节介绍如何将 GitHub 作为一个持续发展的软件产品开发平台，而非仅仅是代码存储工具。产品级开发意味着：代码质量持续可信、版本历史清晰可追溯、交付物自动生成、协作流程标准化。

6.1 Git Flow：主干稳定的分支策略¶

6.1.1 为什么 main 分支必须保持稳定¶

在多人协作的产品开发中，main 分支的稳定性是整个团队的信任基础：

任何人都可以直接从 main 部署，无需额外协调
CI/CD 流水线以 main 为基准触发自动测试和发布
出现线上问题时，main 是最可靠的回退点
Code Review 的质量以「能否合入 main」为衡量标准

后果：如果 main 经常包含不稳定代码，团队会对「当前版本是否可用」产生焦虑，协作效率大幅下降。

6.1.2 Git Flow 分支模型¶

main        ──────●────────────────────●──────→（始终可发布）
                  ↑                    ↑
release/1.0 ──●──┤             release/1.1 ──●──┤
              ↑                              ↑
develop  ─●──●──●──●──●──●──●──●──●──●──●──●──→（集成测试通过后）
           ↑     ↑     ↑              ↑
feature/  ─┘     └──┐  └──feature/B  └──feature/C
login           feature/A

hotfix/xxx ──●──→ 同时合入 main 和 develop

各分支职责：

分支	生命周期	职责	合入目标
`main`	永久	生产发布版本，每次合入打 Tag	—
`develop`	永久	集成分支，功能开发的汇聚点	main（通过 release）
`feature/xxx`	短期	单个功能/Issue 的开发	develop
`release/x.x`	短期	发布前的稳定化（只修 bug，不加功能）	main + develop
`hotfix/xxx`	紧急	生产环境紧急修复	main + develop

6.1.3 本课程的简化 Git Flow¶

对于工程实践4规模的项目，使用以下简化策略：

main    ──●──────────────────────●───────→（保护分支，只接受 PR）
          ↑                      ↑
          PR（通过 CI + Review）  PR（通过 CI + Review）
          ↑                      ↑
feat/F-S-001  feat/F-T-005  fix/xxx  feat/F-S-007

规则： 1. main 设为受保护分支（Protected Branch），禁止直接 push 2. 所有改动通过 Pull Request 合入，至少需要 1 人 Review 通过 3. PR 必须关联 Issue，CI 检查通过后方可合并 4. 每次发版（Sprint 结束）打一个语义化版本 Tag（如 v0.3.0）

6.2 自动生成 GitHub Release¶

6.2.1 语义化版本号（Semantic Versioning）¶

版本号格式：MAJOR.MINOR.PATCH（如 v1.2.3）

部分	何时递增	示例
MAJOR	有不兼容的 API 变更（BREAKING CHANGE）	`v1.0.0` → `v2.0.0`
MINOR	新增向后兼容的功能（feat）	`v1.2.0` → `v1.3.0`
PATCH	向后兼容的 bug 修复（fix）	`v1.2.3` → `v1.2.4`

6.2.2 GitHub Actions 自动创建 Release¶

# .github/workflows/release.yml
name: 自动发布 Release

on:
  push:
    tags:
      - 'v*.*.*'   # 当推送形如 v1.2.3 的 tag 时触发

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0   # 获取完整历史，用于生成 changelog

      - name: 生成 Release Notes
        uses: softprops/action-gh-release@v2
        with:
          generate_release_notes: true   # 自动汇总从上一个 Tag 到当前的所有 PR 标题
          body_path: CHANGELOG.md         # 也可指定手写的 changelog

触发流程：

# 1. 确认 main 分支稳定，所有功能已合入
git checkout main && git pull

# 2. 打语义化版本 Tag
git tag v1.3.0 -m "feat: 完成学生端全部功能"

# 3. 推送 Tag，GitHub Actions 自动触发 Release 创建
git push origin v1.3.0

GitHub 会自动在 Releases 页面生成版本说明，汇总该版本包含的所有 PR 和 commit。

6.3 用 Conventional Commits + BREAKING CHANGE 生成 Changelog¶

6.3.1 Conventional Commits 规范回顾¶

Conventional Commits 是一种结构化 commit message 格式，让工具能自动分析提交历史：

<类型>(<范围>): <简要描述>

<详细说明>

BREAKING CHANGE: <不兼容变更说明>

关键字段与版本号递增的关系：

commit 类型	版本递增	说明
`feat: ...`	MINOR（如 1.2.0 → 1.3.0）	新功能
`fix: ...`	PATCH（如 1.2.3 → 1.2.4）	Bug 修复
`BREAKING CHANGE: ...`	MAJOR（如 1.0.0 → 2.0.0）	不兼容变更
`docs:` / `style:` / `chore:`	无版本递增	不影响功能

6.3.2 BREAKING CHANGE 的正确使用¶

当做出以下改动时，必须在 commit footer 中标注 BREAKING CHANGE:：

修改 REST API 的请求/响应格式（删除字段、更改字段类型）
修改数据库 Schema（删除列、更改列类型，且无向后兼容迁移）
更改配置文件格式（不兼容旧配置）
修改通信协议（嵌入式项目的帧格式变更）

示例：

feat(后端API): 重构用户认证接口

将 /api/login 改为 /api/auth/token，请求体格式变更为
OAuth2 Password Grant 标准格式。

BREAKING CHANGE: /api/login 接口已废弃，客户端需更新为
/api/auth/token，参数 username/password 改为
grant_type=password&username=...&password=...

6.3.3 自动生成 Changelog¶

使用 git-cliff 或 conventional-changelog 工具，从 commit 历史自动生成格式化的 CHANGELOG.md：

# 安装 git-cliff（Rust 编写，速度快）
pip install git-cliff  # 或 brew install git-cliff

# 生成从上一个 Tag 到现在的 changelog
git cliff --latest -o CHANGELOG.md

# 生成完整历史 changelog
git cliff --output CHANGELOG.md

生成的 CHANGELOG.md 示例：

## [1.3.0] - 2024-03-15

### Features
- (学生端) 新增课堂签到功能 (#45)
- (教师端) 支持批量创建 GitHub Issues (#42)

### Bug Fixes
- (原型设计) 统一7个学生端页面侧边栏导航 (#41)

## [1.2.0] - 2024-03-01

### ⚠ BREAKING CHANGES
- (后端API) 重构用户认证接口，/api/login 已废弃 (#38)

### Features
- (教师端) 新增需求文档编辑器 Tab (#35)

6.3.4 在 GitHub Actions 中集成 Changelog¶

# .github/workflows/release.yml（增强版）
- name: 生成 Changelog
  uses: orhun/git-cliff-action@v3
  id: git-cliff
  with:
    config: cliff.toml
    args: --latest --strip header

- name: 创建 Release
  uses: softprops/action-gh-release@v2
  with:
    body: ${{ steps.git-cliff.outputs.content }}
    tag_name: ${{ github.ref_name }}

6.4 Git LFS：存储大文件¶

6.4.1 为什么 Git 不适合直接存储大文件¶

Git 将文件内容存储为对象，每次修改都保存完整副本。对于以下类型的文件，会导致仓库体积急剧膨胀：

视频教程（.mp4）、设计稿（.psd/.sketch）
嵌入式固件编译产物（.bin/.hex）
数据集（.csv/.pkl，MB 以上）
高清截图/文档图片

6.4.2 Git LFS 工作原理¶

普通文件：                     LFS 大文件：
仓库中存储实际内容               仓库中只存储指针文件
─────────────────            ─────────────────────
large_video.mp4               large_video.mp4（指针）
（500 MB 实际数据）             oid sha256:abc123...
                              size 524288000
                                    ↓
                              LFS 存储服务器
                              （GitHub LFS / 自建服务）

6.4.3 使用流程¶

# 1. 安装 Git LFS
git lfs install

# 2. 追踪指定类型的大文件
git lfs track "*.mp4"
git lfs track "*.bin"
git lfs track "docs/images/*.png"

# 3. 提交 .gitattributes（追踪规则文件）
git add .gitattributes
git commit -m "chore: 配置 Git LFS 追踪大文件类型"

# 4. 后续正常 add/commit/push，LFS 文件自动上传到 LFS 存储
git add tutorial_video.mp4
git commit -m "docs: 新增第11章讲解视频"
git push origin main

查看 LFS 存储状态：

git lfs ls-files     # 列出所有 LFS 追踪的文件
git lfs status       # 查看当前工作区 LFS 文件状态

配额提醒：GitHub 免费账户提供 1 GB LFS 存储和每月 1 GB 带宽。超出后需购买数据包（$5/月额外 50GB 存储 + 50GB 带宽）。教材类项目的图片/截图建议使用外链（如存储在 GitHub Release Assets 中），而非 LFS。

6.5 GitHub Pages：自动发布静态网页¶

6.5.1 适用场景¶

GitHub Pages 可以将仓库中的 HTML/Markdown 文件自动渲染为可访问的网站，适合：

项目文档网站（MkDocs / Docusaurus）
原型预览（直接访问 prototype/ 目录）
课程讲义的在线版本

6.5.2 两种发布方式¶

方式A：直接发布仓库分支

在仓库「Settings → Pages」中： - Source 选择 Deploy from a branch - Branch 选择 main / docs - 目录选择 /docs 或 /（根目录）

即可访问 https://<用户名>.github.io/<仓库名>/

方式B：GitHub Actions 自动构建发布

# .github/workflows/pages.yml
name: 发布文档网站

on:
  push:
    branches: [main]
    paths:
      - 'docs/**'
      - 'mkdocs.yml'

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: 安装依赖
        run: pip install mkdocs-material

      - name: 构建文档
        run: mkdocs build --site-dir public

      - name: 部署到 GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

6.5.3 本课程的 Pages 配置¶

OA-EPP 项目的 GitHub Pages 发布教材网站，访问地址为： https://roboticsystem.github.io/OA-EPP/

当 docs/ 目录下的 Markdown 文件合入 main 后，GitHub Actions 自动触发 MkDocs 构建并发布最新版本。

6.6 持续产品开发的完整闭环¶

综合以上机制，基于 GitHub 的产品开发形成以下闭环：

需求 → Issue          ┌──────────────────────────────────────┐
  ↓                   │         GitHub 自动化闭环              │
功能开发（feature 分支）│                                      │
  ↓                   │  push main                            │
PR → Code Review      │      ↓                                │
  ↓                   │  GitHub Actions CI                    │
合并到 main           │      ↓（测试通过）                     │
  ↓                   │  push tag v1.x.0                      │
打 Tag                │      ↓                                │
  ↓                   │  自动创建 Release（附 Changelog）      │
Changelog 生成        │      ↓                                │
  ↓                   │  GitHub Pages 更新文档网站             │
Release 发布          │      ↓                                │
  ↓                   │  通知团队（GitHub Notification）       │
用户反馈 → 新 Issue   └──────────────────────────────────────┘

每个 Sprint 的发布检查清单：

[ ] 所有 feature 分支已合并，关联 Issue 已关闭
[ ] CHANGELOG.md 已更新（或通过 git-cliff 自动生成）
[ ] 版本号符合语义化版本规范
[ ] Tag 已推送，GitHub Release 已自动创建
[ ] Release Notes 中包含本版本的主要变更和 BREAKING CHANGE
[ ] GitHub Pages 文档已更新到最新版本

7. AI 治理进阶：上下文管理与 Subagent 编程¶

7.1 AI 上下文溢出问题¶

7.1.1 什么是上下文窗口¶

每个 AI 模型在单次对话中能「看到」的内容是有限的，这个限制称为上下文窗口（Context Window）。超出这个限制，模型就会忘记早期的内容：

模型	上下文窗口	对应代码行数（近似）
GPT-4o	128K tokens	~10,000 行代码
Claude Sonnet 4.5	200K tokens	~15,000 行代码
Gemini 1.5 Pro	1M tokens	~75,000 行代码
本地模型（Ollama）	4K-32K tokens	~300-2,500 行代码

溢出的典型症状： - AI「忘记」了对话开头提到的需求或约定 - 代码生成与之前的风格/命名规范不一致 - 重复询问已经回答过的问题 - 对同一段代码给出前后矛盾的建议

7.1.2 防止上下文溢出的策略¶

策略一：会话分割（Session Splitting）

将大任务拆分为独立的子任务，每个子任务在新会话中完成：

❌ 错误做法：
一个超长会话中完成「需求分析→架构设计→编码→测试→文档」

✅ 正确做法：
会话1：需求分析 → 输出 requirements.md
会话2：架构设计（读取 requirements.md）→ 输出 architecture.md  
会话3：编码 Module A（读取 architecture.md）→ 输出代码
会话4：编码 Module B（读取 architecture.md）→ 输出代码
会话5：写测试（读取模块代码）→ 输出测试文件

策略二：压缩摘要（Summary Compression）

在会话中途生成摘要，替换掉冗长的历史记录：

<!-- 在会话中途请 AI 生成摘要 -->
提示词：「请将我们目前的讨论总结为一段结构化摘要，
包括：已确认的需求、已做的决策、当前进度、
待解决的问题。我将用这个摘要开启新会话。」

策略三：记忆外挂（External Memory）

将关键信息存储在文件中，而非依赖会话内记忆（详见第3节记忆功能）： - 项目规范 → .github/copilot-instructions.md - 架构决策 → /memories/repo/architecture.md - 会话进度 → /memories/session/current-task.md

策略四：精准定位（Precision Referencing）

减少无关上下文，只提供当前任务所需的信息：

❌ 提供整个项目的所有文件
✅ 只提供相关的3-5个文件
✅ 用文件路径+行号精确引用（"请修改 auth.py 第42-58行"）
✅ 粘贴具体的错误信息，而非"有个报错"

7.2 Subagent 编程架构¶

7.2.1 什么是 Subagent 编程¶

当任务复杂度超过单个 AI 对话的处理能力时，可以将任务分解为多个子任务，委派给多个 Subagent 并行处理。主 Agent 负责协调，Subagent 负责执行：

用户指令
    ↓
主 Agent（Main Agent）
    ├─ 分解任务
    ├─ 分配 Subagent
    └─ 汇总结果

    ↓委派           ↓委派           ↓委派
Subagent A       Subagent B       Subagent C
（前端代码）     （后端API）      （测试用例）
    ↓                ↓                ↓
  结果A            结果B            结果C
    └────────────────┴────────────────┘
                     ↓
               主 Agent 汇总
                     ↓
              最终输出给用户

7.2.2 Subagent 的使用场景¶

场景	主 Agent 职责	Subagent 职责
大型代码重构	分析影响范围，制定重构计划	各自重构单个模块
多文件搜索	汇总搜索结果	并行搜索不同目录/仓库
全栈功能开发	协调前后端接口	前端 Subagent + 后端 Subagent
代码审查	生成综合报告	分别审查安全性/性能/规范
文档生成	维护文档结构	并行生成各模块的文档

7.2.3 Subagent 的通信规则¶

Subagent 编程有几条重要的安全约束，违反会导致死循环或系统崩溃：

⚠️ Subagent 禁止调用协议同步工具（如 copilot_enhance_3210）
   只有主 Agent 可以调用此类工具

✅ 信息传递方式：
   主 Agent → Subagent：通过 prompt 参数传递上下文
   Subagent → 主 Agent：通过 return 值（最终一条消息）返回结果

✅ 并发规则：
   独立的只读任务（搜索、读取文件）可以并发执行
   有依赖关系的任务必须串行（先搜索，再基于结果修改）

在 GitHub Copilot Agent 中调用 Subagent 的示例：

# 主 Agent 将 Subagent 结果直接传递给下一步，无需摘要
result_A = runSubagent(
    agentName="Explore",
    prompt="快速分析 auth/ 目录的调用链，返回函数依赖图"
)
result_B = runSubagent(
    agentName="分析师", 
    prompt=f"基于以下调用图分析重构风险：\n{result_A}"
)
# 主 Agent 基于 result_B 执行实际修改

7.3 常见 AI 编程方法论¶

7.3.1 Superpowers 范式¶

Superpowers（超能力范式）描述了 AI 如何将开发者的能力量级提升，而非简单替代。核心理念：

"AI 不是让你少写代码，而是让你能驾驭更大规模的系统。"

三层超能力：

层级3：系统级超能力
  ● 跨仓库代码搜索与重构
  ● 自动化 Code Review（安全/性能/规范三维）
  ● 从自然语言直接生成完整功能模块

层级2：模块级超能力
  ● 理解并重构复杂业务逻辑
  ● 自动生成测试用例（含边界值和异常场景）
  ● 实时 pair programming（解释每一行代码的含义）

层级1：编辑级超能力（基础）
  ● 代码补全与多行建议
  ● 错误信息解释与修复建议
  ● 函数/变量命名建议

Superpowers 的实践原则： 1. 放大优势而非修补弱点：用 AI 处理繁琐的样板代码，把创造力留给架构设计 2. 保持主控：AI 生成代码后，人工理解并验证，而非盲目接受 3. 迭代精炼：首次生成通常只有 80% 正确，用追问和约束条件逐步精炼 4. 能力转移：将 AI 完成任务的方法内化为自己的能力，而非形成依赖

在 IDE 中激活 Superpowers 的工具链：

工具	主要功能	激活场景
GitHub Copilot（inline）	代码补全、函数生成	日常编码
Copilot Chat / Agent Mode	多步骤任务、代码解释	复杂功能开发
Cursor Composer	多文件协同编辑	跨文件重构
Cline / Aider	命令行 AI 编码	批量文件操作
PR Agent（GitHub App）	自动化 Code Review	PR 提交后

7.3.2 GSD（Get Stuff Done）方法论¶

GSD（Get Stuff Done，高效完成任务）是将 AI 编程融入日常开发工作流的实践方法论，核心是减少摩擦，快速推进。

GSD 的四大原则：

原则1：意图优先于实现（Intent over Implementation）

告诉 AI「你想要什么」，而非「如何实现」：

❌ 低效提示词：
「帮我写一个 for 循环，遍历 users 列表，
  对每个 user 调用 validate() 方法，
  如果返回 False 就 append 到 invalid_list」

✅ 高效提示词：
「过滤出 users 列表中未通过验证的用户，返回列表」

原则2：最小可验证步骤（Minimum Verifiable Steps）

每次 AI 生成代码后，立即运行验证，不积累未验证的改动：

修改一个功能 → 立即运行测试 → 通过后继续
            ↘ 不通过 → 立即修复，不继续往下开发

原则3：失败快速，恢复快速（Fail Fast, Recover Fast）

遇到 AI 生成的代码有问题时，不要反复追问同一个会话： 1. 用 git diff 检查改动范围 2. 如果改动超过预期，立即 git stash 或 git checkout . 回滚 3. 开启新会话，提供更精确的约束条件重新生成

原则4：任务分解到原子级别（Atomic Task Decomposition）

将大任务分解为每个步骤只改动1-3个文件的原子操作：

大任务：「实现用户登录功能」

原子任务分解：
  Step 1: 创建 User 数据库模型（1个文件）
  Step 2: 实现密码哈希工具函数（1个文件）
  Step 3: 实现登录 API 端点（1个文件）
  Step 4: 实现前端登录表单组件（1个文件）
  Step 5: 连接前后端，处理 Token 存储（2个文件）
  Step 6: 编写集成测试（1个文件）

GSD 与传统开发方式的效率对比：

阶段	传统方式耗时	GSD + AI 耗时	节省比例
样板代码（CRUD）	4 小时	20 分钟	92%
单元测试编写	3 小时	30 分钟	83%
代码注释/文档	2 小时	10 分钟	92%
Bug 定位	1 小时	15 分钟	75%
架构设计	3 小时	2 小时	33%
复杂业务逻辑	不变	不变	0%

关键洞察：AI 对「重复性、模式化」的工作效率提升显著；对「创造性、领域知识密集」的工作几乎没有加速作用。GSD 的价值在于把节省下来的时间专注于真正需要人类智慧的部分。

7.3.3 上下文工程（Context Engineering）¶

上下文工程是 AI 编程中的高级技能——精心设计提供给 AI 的信息，使其输出质量最大化。

五要素框架：

优质 AI 上下文 = 角色定义 + 任务约束 + 相关代码 + 期望格式 + 示例

要素	作用	示例
角色定义	激活 AI 的专业模式	「你是一个 Reflex 框架专家，熟悉其 State 机制」
任务约束	限制输出范围，防止过度生成	「只修改 courses.py，不要修改其他文件」
相关代码	提供足够的上下文，减少 AI 猜测	粘贴相关的数据模型定义和接口定义
期望格式	减少后处理工作	「输出完整的 Python 文件，不要解释」
示例（Few-shot）	对齐输出风格	「参考 assignments.py 中的写法」

反面示例（上下文工程失败）：

用户：「帮我修复一下 bug」

问题：
- 没有角色定义：AI 不知道技术栈
- 没有任务约束：AI 可能改动很多文件
- 没有相关代码：AI 只能猜测代码结构
- 没有期望格式：输出可能只有解释没有代码
- 没有示例：风格可能与项目不一致

正面示例（上下文工程成功）：

用户：「你是一个 Reflex 框架专家。
以下是 state/courses.py 的第42-58行代码：
[粘贴代码]

问题：当 courses 列表为空时，页面报 IndexError。
请只修改 state/courses.py，在第 50 行添加空列表检查。
输出修改后的完整函数，不需要解释。」

7.4 AI 治理视角下的 Subagent 风险¶

在 AI 治理中，Subagent 编程带来了新的风险维度：

风险	说明	缓解措施
权限扩散	Subagent 可能执行超出预期的文件操作	限制 Subagent 工具集（只读 vs 读写）
结果不可追溯	多个 Subagent 的操作难以归因	每个 Subagent 操作记录在 git commit 中
幻觉传播	Subagent A 的错误结论被 Subagent B 放大	关键决策节点插入人工验证
死循环	Subagent 互相调用或重复触发	禁止 Subagent 调用同步工具，设置最大深度
敏感数据泄露	Subagent 日志中包含 API 密钥等信息	审查 prompt 内容，使用环境变量替代硬编码

Subagent 的最佳实践总结：

✅ 主 Agent 统一协调，Subagent 只执行不决策
✅ Subagent 只读操作可以并发，写操作必须串行
✅ 每个 Subagent 任务范围明确，不超过3个文件
✅ Subagent 结果直接传递，不经主 Agent 二次摘要
✅ 敏感操作（push/delete）只允许主 Agent 执行
❌ 禁止 Subagent 调用协议同步工具
❌ 禁止 Subagent 之间直接通信

8. 工程实践4核心 VS Code 插件指南¶

本节列出工程实践4环境中预装的全部 VS Code 插件，说明每个插件的用途和在开发流程中的重要性。掌握这些工具是高效完成工程实践的前提。

查看当前已安装插件：在 VS Code 中按 Ctrl+Shift+X 打开扩展市场，切换到「已安装」标签页。

8.1 AI 辅助编程类（最核心）¶

这类插件直接决定 AI 辅助开发的质量上限，是工程实践4的核心生产力工具。

GitHub Copilot + Copilot Chat（内置）¶

项目	说明
插件ID	`GitHub.copilot` + `GitHub.copilot-chat`
版本要求	VS Code 1.85+
激活方式	登录 GitHub 账号，学生认证后免费使用

核心功能： - Inline Completion：在编辑器中实时补全代码（Tab 接受，Esc 拒绝） - Copilot Chat：侧边栏对话，支持 @workspace（全仓库上下文）、@terminal（终端上下文） - Agent Mode：多步骤任务自动化执行，支持调用工具链（见第3节） - Edit Mode（/edit）：指定文件范围进行 AI 辅助编辑

工程实践4中的关键用法：

@workspace 帮我找出所有还没有关联 Issue 的函数
/fix       修复当前选中代码的 bug
/tests     为选中的函数生成单元测试
/explain   解释这段代码的逻辑

Copilot Enhance Tool（`copilot-enhance.copilot-enhance-tool`）¶

项目	说明
插件ID	`copilot-enhance.copilot-enhance-tool`
作用	在 Agent 循环模式中提供协议同步节点 `copilot_enhance_3210`

本插件是 OA-EPP 项目的循环协作协议的核心组件。它生成一个自定义工具端点，使 AI Agent 能够在每轮任务完成后同步状态、接收下一条指令，实现「人机协作循环」：

用户指令 → AI 执行 → copilot_enhance_3210 同步 → 等待下一条指令

端口号随 VS Code 窗口变化自动生成，无需手动配置。

HackLM Memory（`hacklm.hacklm-memory`）¶

项目	说明
插件ID	`hacklm.hacklm-memory`
作用	为 AI 提供持久化记忆存储（`/memories/` 目录）

该插件实现了第3节中介绍的三层记忆机制（用户/仓库/会话），确保 AI 跨会话保持对项目上下文的了解。安装后 AI 可调用 storeMemory / queryMemory 工具，无需在每次会话中重复描述项目背景。

VS Code Chat Customizations Evaluations（`ms-vscode.vscode-chat-customizations-evaluations`）¶

项目	说明
插件ID	`ms-vscode.vscode-chat-customizations-evaluations`
作用	验证 `.github/copilot-instructions.md` 等配置文件的语法正确性

当 .github/instructions/*.instructions.md 中有 YAML frontmatter 语法错误时，本插件在编辑器中显示诊断信息，帮助修复配置文件。

8.2 Git 工作流类（高频使用）¶

Git 操作是工程实践4的日常核心，这组插件将命令行 Git 的复杂性转化为可视化界面。

GitLens（`eamodio.gitlens`）¶

项目	说明
插件ID	`eamodio.gitlens`
重要程度	⭐⭐⭐⭐⭐（必装）

GitLens 是 VS Code 中最强大的 Git 增强插件，提供：

行内 Blame：每行代码右侧显示「最后一次修改者、时间、commit 信息」
文件历史（Timeline）：查看任意文件的完整修改历史
交互式 Rebase：在 GUI 中拖拽调整 commit 顺序
Commit Graph：可视化分支合并图
Stash 管理：图形化管理未提交的临时存储

工程实践4重点用法：

Ctrl+Shift+G → 打开 Source Control 面板（含 GitLens 增强）
Alt+点击行号 → 查看该行的 commit 历史
右键文件 → 「Open File History」→ 查看谁、何时、为何修改

Git Graph（`mhutchie.git-graph`）¶

项目	说明
插件ID	`mhutchie.git-graph`
重要程度	⭐⭐⭐⭐（强烈推荐）

以交互式图形展示 Git 分支和合并历史，功能类似 gitk 或 SourceTree，但完全集成在 VS Code 中：

可视化查看所有分支的拓扑关系
点击任意 commit 查看详情（diff、文件列表）
支持在图中创建分支、合并、cherry-pick

打开方式：左下角状态栏点击「Git Graph」图标，或命令面板输入 Git Graph: View Git Graph。

Git Flow（`serhioromano.vscode-gitflow`）¶

项目	说明
插件ID	`serhioromano.vscode-gitflow`
重要程度	⭐⭐⭐（推荐）

将第6节介绍的 Git Flow 分支策略的常用操作封装为菜单命令：

命令面板 → Gitflow: Feature Start  → 自动创建 feature/xxx 分支
命令面板 → Gitflow: Feature Finish → 自动合并到 develop 并删除特性分支
命令面板 → Gitflow: Release Start  → 创建 release/x.x 分支

减少手动执行多条 git checkout -b / git merge 命令的出错概率。

Git Merger（`shaharkazaz.git-merger`）¶

项目	说明
插件ID	`shaharkazaz.git-merger`
重要程度	⭐⭐⭐（推荐）

简化 git merge 操作，提供合并冲突的可视化解决界面，特别适合不熟悉命令行 merge 流程的初学者。

8.3 GitHub 集成类¶

GitHub Pull Requests（`github.vscode-pull-request-github`）¶

项目	说明
插件ID	`github.vscode-pull-request-github`
重要程度	⭐⭐⭐⭐⭐（必装）

将 GitHub PR 和 Issue 工作流完整集成到 VS Code：

在 VS Code 中创建/审查 PR，无需切换到浏览器
行级 Code Review Comment：直接在代码行旁边写评审意见
Copilot 代码审查：一键触发 GitHub Copilot 对 PR 进行自动代码审查
Issue 引用：在 commit message 中输入 # 自动补全 Issue 编号

工程实践4重点用法： - 左侧活动栏「GitHub」图标 → 查看待处理的 PR 列表 - 打开 PR 后点击文件 → 进入 Code Review 模式，逐行审查

GitHub Repository Manager（`henriquebruno.github-repository-manager`）¶

项目	说明
插件ID	`henriquebruno.github-repository-manager`
作用	快速浏览和切换 GitHub 上的仓库，无需离开 VS Code

GitHub Issue Notebooks（`ms-vscode.vscode-github-issue-notebooks`）¶

项目	说明
插件ID	`ms-vscode.vscode-github-issue-notebooks`
作用	用 Jupyter Notebook 风格的界面编写 GitHub Issues/PR 搜索查询

支持类似 assignee:@me is:open 的 GitHub 搜索语法，在 VS Code 中直接查询、浏览 Issue 列表。

GitHub Codespaces Connector（`smartmanoj.github-codespaces-connector`）¶

项目	说明
插件ID	`smartmanoj.github-codespaces-connector`
作用	从本地 VS Code 连接到 GitHub Codespaces 远程开发环境

配合第1节介绍的 Codespaces 工作流，让本地 VS Code 也能连接到云端 Codespace，享受完整的本地编辑体验。

Codespace Tracker（`lucasgnunes.codespace-tracker`）¶

项目	说明
插件ID	`lucasgnunes.codespace-tracker`
作用	追踪 Codespaces 使用时间，防止超出免费配额

在状态栏显示当前 Codespace 的运行时长，帮助学生管理每月 120 小时的免费配额。

8.4 文档与展示类¶

Markdown Preview Enhanced（`shd101wyy.markdown-preview-enhanced`）¶

项目	说明
插件ID	`shd101wyy.markdown-preview-enhanced`
重要程度	⭐⭐⭐⭐（强烈推荐）

比 VS Code 内置 Markdown 预览功能强大得多，支持：

数学公式：行内 $E=mc^2$ 和块级 $$\int_0^\infty$$ 渲染
Mermaid 图表：直接在 Markdown 中渲染流程图、时序图、甘特图
代码块高亮：支持更多语言和主题
导出：直接导出为 PDF、HTML、Word

工程实践4重点用法： - Ctrl+Shift+V → 打开增强预览 - 预览界面右键 → 「Export」→ 生成 PDF 版实验报告

Marp（`marp-team.marp-vscode`）¶

项目	说明
插件ID	`marp-team.marp-vscode`
重要程度	⭐⭐⭐（推荐）

用 Markdown 编写幻灯片，支持： - 在 VS Code 中预览幻灯片效果 - 导出为 HTML、PDF、PPTX 格式 - 支持自定义主题

答辩演示建议：用 Marp 写答辩 PPT，与代码仓库同步管理，版本可追溯。

Docx Reader（`shahilkumar.docxreader`）¶

项目	说明
插件ID	`shahilkumar.docxreader`
作用	在 VS Code 中直接预览 `.docx` 文件，无需切换到 Word

8.5 容器与环境类¶

VS Code Containers（`ms-azuretools.vscode-containers`）¶

项目	说明
插件ID	`ms-azuretools.vscode-containers`
重要程度	⭐⭐⭐（推荐）

管理 Docker 容器和镜像，支持： - 查看运行中的容器状态 - 进入容器终端（exec -it） - 管理 Docker Compose 服务 - 配合 .devcontainer 实现可重现的开发环境

8.6 国际化¶

中文语言包（`ms-ceintl.vscode-language-pack-zh-hans`）¶

项目	说明
插件ID	`ms-ceintl.vscode-language-pack-zh-hans`
作用	将 VS Code 界面翻译为简体中文

8.7 插件重要性总结¶

插件	对应开发流程环节	重要程度
GitHub Copilot（内置）	AI 辅助编码	⭐⭐⭐⭐⭐
GitHub Pull Requests	PR / Code Review	⭐⭐⭐⭐⭐
GitLens	commit 历史 / blame	⭐⭐⭐⭐⭐
Copilot Enhance Tool	Agent 循环协作	⭐⭐⭐⭐⭐
HackLM Memory	AI 跨会话记忆	⭐⭐⭐⭐
Git Graph	分支可视化	⭐⭐⭐⭐
Markdown Preview Enhanced	文档预览 / 导出	⭐⭐⭐⭐
Git Flow	分支策略执行	⭐⭐⭐
Marp	答辩演示文稿	⭐⭐⭐
VS Code Containers	容器化开发环境	⭐⭐⭐
GitHub Codespaces Connector	远程云端开发	⭐⭐⭐
Git Merger	合并冲突解决	⭐⭐⭐

安装顺序建议：首先确保 GitHub Copilot（需学生认证）和 GitHub Pull Requests 正常工作，这是工程实践4中最高频使用的两个工具。其余插件按需安装，不要一次性安装所有插件，以免拖慢 VS Code 启动速度。

9. AI 编程常用提示词（Prompt）手册¶

好的提示词是高效使用 AI 编程工具的核心技能。本节提供工程实践4中最实用的提示词模板，涵盖调试、日志、CLI、TDD 等常见场景，可直接复制使用并按需修改。

使用说明：[方括号] 内的内容需替换为实际值；@workspace 告诉 Copilot Chat 搜索整个仓库；#file:xxx.py 将指定文件加入上下文。

9.1 调试类提示词¶

通用 Bug 调试¶

我遇到了以下报错，请帮我找出根本原因并提供修复方案：

错误信息：
[粘贴完整的错误 traceback]

相关代码文件：#file:[相关文件路径]

我已尝试过的方法：
- [已尝试的方案1]
- [已尝试的方案2]

请：
1. 解释错误的根本原因（不是表面现象）
2. 给出最小化的修复方案
3. 说明如何避免此类问题复现

逻辑错误调试（无报错但结果不对）¶

代码可以运行但结果不符合预期：

期望结果：[描述期望的输出]
实际结果：[描述实际的输出]

代码：#file:[文件路径]

请：
1. 逐步追踪数据流，找出逻辑偏差的位置
2. 在关键节点添加临时 print/assert 语句帮助定位
3. 修复逻辑错误

性能调试¶

以下代码在处理[数据规模]时响应时间超过[X]秒，
需要优化到[目标时间]以内：

#file:[文件路径]（关注第[行号范围]行）

请：
1. 识别性能瓶颈（时间复杂度分析）
2. 提出2-3种优化方案并对比其优缺点
3. 实现性能最优的方案，不改变函数接口

并发/异步 Bug 调试¶

以下异步代码存在 [竞态条件/死锁/未捕获异常]：

#file:[文件路径]

复现步骤：[描述如何触发问题]

请分析：
1. 异步调用链的执行顺序（画出时序）
2. 问题出现的时机和原因
3. 修复方案（优先使用语言内置机制，避免手写锁）

9.2 生成详细调试信息的提示词¶

添加结构化日志¶

为以下代码的关键路径添加结构化日志，
帮助在生产环境中追踪问题：

#file:[文件路径]

要求：
1. 使用 Python logging 模块（不使用 print）
2. 日志级别：
   - DEBUG：详细的变量值和执行流程
   - INFO：关键业务操作（用户登录、数据库写入）
   - WARNING：非预期但可恢复的情况
   - ERROR：需要立即关注的问题
3. 每条日志包含：时间戳、模块名、函数名、相关 ID
4. 不记录密码、Token 等敏感信息
5. 生产环境默认 INFO 级别，调试时可切换到 DEBUG

生成调试断言（Assert）¶

为以下函数在关键数据转换节点添加 assert 语句，
确保数据契约（data contract）在开发期间得到验证：

#file:[文件路径]

请在以下位置添加 assert：
1. 函数入口：验证参数类型和取值范围
2. 中间步骤：验证关键变量的不变量（invariants）
3. 函数出口：验证返回值的类型和范围

格式：assert 条件, "描述性错误信息（含变量当前值）"

生成调试版本的 Mock 数据¶

为以下函数生成详细的调试用 Mock 数据，
覆盖正常流程、边界条件和异常场景：

函数签名：[粘贴函数定义]

请生成3组 Mock 数据：
1. 正常输入（典型使用场景）
2. 边界输入（空列表、最大值、最小值）
3. 异常输入（None、错误类型、越界值）

并为每组数据说明预期的函数行为。

9.3 充分利用 CLI 接口的提示词¶

分析并优化 CLI 命令¶

我需要用命令行完成以下任务：[描述任务]

当前使用的命令：
[当前命令]

请：
1. 解释每个参数的含义
2. 指出可以简化或优化的地方
3. 提供更高效的替代命令
4. 如果可以用管道（|）或重定向改进，请说明

生成 Shell 脚本¶

帮我编写一个 Bash 脚本，自动完成以下任务：

任务描述：[详细描述]

要求：
1. 添加 set -euo pipefail（遇到错误立即退出）
2. 关键步骤输出进度信息（带时间戳）
3. 操作前检查依赖是否存在（command -v）
4. 支持 Ctrl+C 中断时的清理操作（trap）
5. 脚本顶部添加使用说明注释

运行环境：Ubuntu 22.04 / Bash 5.x

利用 GitHub CLI（`gh`）提高效率¶

帮我用 GitHub CLI（gh 命令）完成以下操作：
[描述操作]

当前 GitHub 仓库：[仓库名]

请提供完整的 gh 命令，并解释每个参数的含义。
如果需要多步骤，请按顺序列出并说明各步骤的目的。

调试 GitHub Actions Workflow¶

以下 GitHub Actions workflow 执行失败，
请帮我分析原因并修复：

Workflow 文件：#file:.github/workflows/[文件名]

失败日志：
[粘贴关键日志片段]

请：
1. 指出失败的具体步骤和原因
2. 修复 workflow 文件
3. 说明如何在本地用 act 工具模拟 CI 环境测试

分析和生成 Makefile / CMakeLists¶

帮我为以下项目生成 [Makefile / CMakeLists.txt]：

项目结构：
[描述源码目录结构]

构建要求：
- 目标平台：[x86_64 / arm-none-eabi]
- 编译器：[gcc / arm-none-eabi-gcc]
- 优化等级：[Debug / Release]
- 需要链接的库：[列举]

请：
1. 生成完整的构建文件
2. 添加 clean / install / test 目标
3. 注释说明每个变量和目标的用途

9.4 TDD（测试驱动开发）提示词¶

TDD 的核心循环：红（写失败测试） → 绿（写最少代码通过测试） → 重构（优化不改变行为）

步骤1：先写测试¶

我要实现以下功能，请先帮我写测试（不要写实现代码）：

功能描述：[详细描述功能需求]

函数签名（期望的接口）：
def [函数名]([参数]) -> [返回类型]:
    ...

请用 pytest 编写测试，覆盖：
1. 正常场景（至少3种典型输入/输出对）
2. 边界条件（空值、极值、临界值）
3. 异常场景（错误输入应抛出什么异常）
4. 使用 pytest.mark.parametrize 减少重复

测试文件命名：test_[模块名].py
测试函数命名：test_[功能描述]_[场景]

步骤2：根据测试实现代码¶

以下测试已经写好，请实现满足这些测试的最简代码：

测试文件：#file:tests/test_[模块名].py

要求：
1. 只实现让所有测试通过所需的最少代码
2. 不要添加测试没有覆盖到的功能
3. 代码放在 [模块路径] 文件中
4. 运行 pytest tests/test_[模块名].py 验证全部通过

步骤3：重构¶

以下代码所有测试已通过，请在不改变行为的前提下重构：

实现文件：#file:[文件路径]
测试文件：#file:tests/test_[文件名].py

重构目标：
- [ ] 消除重复代码（DRY 原则）
- [ ] 拆分过长函数（每个函数不超过20行）
- [ ] 改善命名（变量名/函数名更能表达意图）
- [ ] 提取常量（消除魔法数字）

重构后确保 pytest tests/test_[文件名].py 仍然全部通过。

生成集成测试¶

为以下模块之间的交互生成集成测试：

模块A：#file:[模块A路径]（提供 [功能] 接口）
模块B：#file:[模块B路径]（调用 [功能] 接口）

测试要覆盖：
1. 正常数据流（A产生数据，B正确处理）
2. A产生边界数据时，B的行为
3. A产生异常数据时，B的错误处理

Mock 规则：
- 数据库操作使用 pytest fixtures 提供临时数据库
- 外部HTTP调用使用 pytest-responses 拦截
- 不 Mock 被测试的核心业务逻辑

9.5 通用高效提示词¶

代码解释¶

请解释以下代码的工作原理，
目标读者是有 Python 基础但不熟悉本模块的同学：

#file:[文件路径]（第[行号]至[行号]行）

请从以下角度解释：
1. 这段代码解决了什么问题（What）
2. 核心算法/流程是什么（How）
3. 为什么这样设计（Why）——有什么设计取舍
4. 可能的改进方向

代码审查¶

请对以下代码进行代码审查，
模拟一个有5年经验的 Python 工程师的视角：

#file:[文件路径]

审查维度：
1. **正确性**：是否有 bug 或边界条件没有处理
2. **安全性**：是否有 OWASP Top 10 中提到的安全风险
3. **可读性**：命名、注释、代码结构是否清晰
4. **性能**：是否有明显的性能问题
5. **测试覆盖**：关键路径是否有测试

对每个问题：说明严重程度（Critical/Major/Minor）
并给出具体的修改建议。

重构遗留代码¶

以下是一段遗留代码，存在[命名混乱/重复代码/上帝函数]问题：

#file:[文件路径]

重构目标：[具体描述期望达到的状态]

约束条件：
1. 不改变公共接口（函数签名不变）
2. 保持向后兼容（不删除公共方法）
3. 分步提交（每次重构一个关注点）

请按以下顺序重构：
Step 1: [第一步，如「重命名变量」]
Step 2: [第二步，如「提取函数」]
Step 3: [第三步，如「消除重复」]

生成 API 文档¶

为以下模块生成 API 文档（Docstring 格式）：

#file:[文件路径]

文档格式：Google Style Docstring
每个函数必须包含：
- 一句话功能说明
- Args: 每个参数的类型、含义、是否可选
- Returns: 返回值类型和含义
- Raises: 可能抛出的异常类型
- Example: 至少一个完整的使用示例

快速原型提示词（结合第5节）¶

生成一个 [页面名称] 的静态 HTML 原型页面：

技术约束：
- 纯 HTML + Tailwind CSS CDN
- 不使用 JavaScript，不使用自定义 CSS
- 布局：固定侧边栏（w-56 fixed left-0 top-0）+ 主内容区（ml-56）

页面内容：
[详细描述页面的每个区域和数据]

导航菜单项：[列出所有菜单项，标注哪个是当前激活]
配色方案：[blue-600 学生端 / indigo-600 教师端]

直接输出完整 HTML 文件，不要解释。

9.6 提示词反模式（避免这些低效写法）¶

低效提示词	问题	改进版
「帮我写代码」	太模糊，无法产生有用输出	「帮我实现一个函数，输入为…，输出为…」
「修复这个 bug」（没有贴代码）	缺少上下文	「修复 #file:auth.py 第42行的 KeyError」
「优化一下」	优化目标不明确	「将此函数的时间复杂度从 O(n²) 降到 O(n)」
「你能帮我写 XXX 吗？」	冗余询问，AI 都会回答「能」	直接描述任务，不需要先确认
「写好了之后我再告诉你需求」	先执行后需求，必然返工	在同一条消息中提供完整约束
把1000行文件粘贴到聊天框	超出上下文，AI 质量下降	用 `#file:` 引用，只粘贴相关行