Skip to content

Commit a8d24ac

Browse files
cursoragentxxg1413
cursoragent
and
xxg1413
committed
courses: add Hands-on with GitHub Copilot (report-tool core group)
Co-authored-by: P小二 <xxg1413@gmail.com>
1 parent f7f31ea commit a8d24ac

26 files changed

Lines changed: 2108 additions & 0 deletions

File tree

‎courses/hands-on-with-github-copilot/COURSE.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
---
2+
id: course-github-copilot
3+
type: course
4+
title: Hands-on with GitHub Copilot
5+
summary: The verified Python workflow — task contract, bounded change, objective verify.py evidence — taught hands-on with GitHub Copilot in VS Code, where the Agent role runs the loop and you supervise permissions, instructions files, and diffs.
6+
lang: en-US
7+
content_version: 1
8+
status: reviewed
9+
reviewed_on: 2026-10-11
10+
badge:
11+
id: course-github-copilot
12+
name_en: Reproduce with Copilot in the loop
13+
name_zh: Copilot 协同复现
14+
requires: All five checkpoints claimed (L01–L05)
15+
course_id: course-github-copilot
16+
---
17+
18+
# Hands-on with GitHub Copilot
19+
20+
> TL;DR: open VS Code with GitHub Copilot signed in, optionally install the
21+
> FlyPython Skill, and let the agent fetch this course — lesson 1 walks you
22+
> through all three steps and you download nothing. Open the Chat view,
23+
> pick the **Agent** role, and say **"start lesson 1"**. You finish with a
24+
> working report tool, a reproducible pass/fail command, and the Copilot
25+
> workflow: Agent/Plan/Ask roles, manual permissions, `.github` instructions
26+
> files, checkpoints, and diff review. The exercise core is the same one the
27+
> Claude Code, Codex, and Cursor courses use — only the tool you drive
28+
> changes.
29+
30+
## What you build
31+
32+
A small Python report tool that reads messy real-world data (CSV or JSON),
33+
isolates invalid rows instead of crashing, aggregates valid rows, and writes
34+
its report atomically. Three scenario "skins" ship with the course so you can
35+
practice on a domain you recognize:
36+
37+
| Skin | You are… | Data |
38+
| --- | --- | --- |
39+
| `scenario/excel-report/` | turning a weekly orders export into a region summary | `orders.csv` |
40+
| `scenario/data-monitor/` | checking service latency numbers from your servers | `metrics.csv` |
41+
| `scenario/api-tool/` | summarizing ticket data pulled from an internal API | `tickets.json` |
42+
43+
All three run through the same code and the same tests. The skills —
44+
contracts, error isolation, rounding, atomic writes, verification — are the
45+
actual product; the skins just make them concrete.
46+
47+
## Teaching contract (read this first, agent)
48+
49+
If you are GitHub Copilot teaching this course, follow these rules:
50+
51+
- **Audience:** a project owner who already has Copilot in their editor —
52+
often through work — and uses it for completions or chat, but has not
53+
yet trusted the agent to change a project end to end. Not a Python
54+
beginner tutorial; not a prompt-engineering course.
55+
- **Prerequisites:** Python 3.11+ on PATH, VS Code installed, and a GitHub
56+
account signed in to GitHub Copilot in VS Code. No packages to install —
57+
the course is standard library only. Whether the Copilot Free plan's
58+
monthly chat request allowance lasts the whole course is unverified at
59+
authoring time — see `REVIEW.md`.
60+
- **Tool:** authored against VS Code 1.134 with GitHub Copilot, as
61+
documented at code.visualstudio.com/docs/copilot (fetched 2026-10-11):
62+
the Chat view with the Copilot session target, the Agent/Plan/Ask roles,
63+
the Manual permissions / Allow all permission levels, Folder vs. New
64+
Worktree code isolation, `.github/copilot-instructions.md` and
65+
`.github/instructions/*.instructions.md` (`applyTo` front matter),
66+
Agent Skills in `.github/skills/`, and checkpoints. A live teaching
67+
run-through is pending — `REVIEW.md` records what has and has not been
68+
exercised. A VS Code or Copilot major change to these surfaces triggers a
69+
course re-review.
70+
- **Lesson order:** L01 → L02 → L03 → L04 → L05, one lesson per session.
71+
Never skip the checkpoint at the end of a lesson.
72+
- **Teaching style:** work from the files in this folder, not from general
73+
knowledge. Quote the exact contract line you are satisfying. Make the
74+
smallest change that moves a test from red to green. Never add
75+
dependencies, never edit `solution/`, and ask before touching any file
76+
not named in the current lesson. Keep the learner on **Manual
77+
permissions** — every edit and command waits for their approval. Read
78+
`AGENTS.md` in the repository root if one exists — Copilot reads it too.
79+
- **When to stop:** a lesson is done when its checkpoint command runs and
80+
the learner can say, in their own words, what failed and why. If the
81+
learner cannot, re-teach from the failing test, not from the solution.
82+
- **How to use `verify.py`:** the learner's command is plain
83+
`python verify.py` — it runs the suites, prints per-checkpoint status
84+
and earned claim codes, and exits non-zero while the gated checkpoints
85+
(l03, l04) are still open. `starter --expect-failure` and `solution`
86+
remain maintainer checks. "Done" means the default command shows every
87+
gate `[passed]` after the learner's bounded change.
88+
- **Honesty rules:** say what you did not verify. Do not claim the code is
89+
production-ready. Do not promise learning or career outcomes.
90+
91+
## What this course does NOT cover
92+
93+
Copilot plans and pricing, model selection, inline completions, the Copilot
94+
cloud agent on GitHub.com, Copilot code review on pull requests, MCP setup,
95+
organization policies, or selling anything. For those, the companion
96+
repository has guides and playbooks — link, don't improvise.
97+
98+
## Badge contract
99+
100+
- Badge: **Reproduce with Copilot in the loop Badge** (badge id `course-github-copilot`) — earned by claiming all five checkpoints.
101+
- Challenges: L01–L05 checkpoints, 10 points each; +50 course-badge bonus when all five are claimed on flypython.com.
102+
- Evidence: `python verify.py` — L03 (bounded change) and L04 (verify & review) are objectively gated by the suite; L01/L02/L05 are learner-attested.
103+
- Submission: each test-passed checkpoint prints a deterministic claim code; a reflection checkpoint prints one only after you answer its questions and run `python verify.py --attest ID`; record it on flypython.com against your account. Self-reported evidence, never a certificate.
104+
105+
## Folder map
106+
107+
```
108+
COURSE.md / COURSE_cn.md this file (EN / 中文)
109+
lessons/L01.md … L05.md lessons (each has an _cn.md pair)
110+
scenario/<skin>/ data files and scenario.json per skin
111+
TASK.md / TASK_cn.md the task contract the change must satisfy
112+
starter/report_tool.py the deliberately unfinished implementation
113+
solution/report_tool.py the reviewed solution (do not copy in lesson 3)
114+
tests/test_report_tool.py the contract suite (read-only)
115+
verify.py objective pass/fail evidence
116+
REVIEW.md maintainer run-through record
117+
```
118+
119+
## Evidence and licensing
120+
121+
The course folder is reviewed content: `REVIEW.md` records the last
122+
run-through with dates, tool versions, and observed deviations. Code in this
123+
folder is MIT-licensed; lesson prose is CC BY 4.0 (see repository `LICENSE`).
124+
Report teaching drift or unclear lessons via the repository's
125+
`course-feedback` issue form.

‎courses/hands-on-with-github-copilot/COURSE_cn.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
---
2+
id: course-github-copilot
3+
type: course
4+
title: "上手 GitHub Copilot"
5+
summary: "经过验证的 Python 工作流——任务契约、有界改动、客观 verify.py 证据——在 VS Code 的 GitHub Copilot 里手把手教：由 Agent 角色跑闭环，你监督权限、指令文件与 diff。"
6+
lang: zh-CN
7+
content_version: 1
8+
status: reviewed
9+
reviewed_on: 2026-10-11
10+
badge:
11+
id: course-github-copilot
12+
name_en: Reproduce with Copilot in the loop
13+
name_zh: Copilot 协同复现
14+
requires: 认领全部五个检查点（L01–L05）
15+
course_id: course-github-copilot
16+
---
17+
18+
# 上手 GitHub Copilot
19+
20+
> 一句话：打开已登录 GitHub Copilot 的 VS Code、（可选）装上 FlyPython
21+
> Skill、让 Agent 取回本课文件（第 1 课就是这三步，你什么都不用下载），
22+
> 打开 Chat 视图、选 **Agent** 角色，对它说**「开始第 1 课」**。完成时你会
23+
> 得到一个能跑的报表工具、一条可复现的通过/失败命令，以及 Copilot 工作流：
24+
> Agent/Plan/Ask 角色、手动权限、`.github` 指令文件、检查点与 diff 审查。
25+
> 练习核心与 Claude Code、Codex、Cursor 课程完全相同——变的只是你驱动的
26+
> 工具。
27+
28+
## 你要做的东西
29+
30+
一个小型 Python 报表工具：读进脏乱的真实数据（CSV 或 JSON）、隔离
31+
无效行而不是直接崩溃、聚合有效行、原子地写出报告。课程自带三个
32+
「场景皮肤」，让你在自己熟悉的领域里练习：
33+
34+
| 皮肤 | 你是…… | 数据 |
35+
| --- | --- | --- |
36+
| `scenario/excel-report/` | 把每周订单导出整理成区域汇总 | `orders.csv` |
37+
| `scenario/data-monitor/` | 检查自家服务器的延迟数据 | `metrics.csv` |
38+
| `scenario/api-tool/` | 汇总从内部 API 拉取的工单数据 | `tickets.json` |
39+
40+
三个皮肤跑的是同一份代码、同一套测试。真正的产品是这些技能——契约、
41+
错误隔离、舍入、原子写、验证——皮肤只是让它们变得具体。
42+
43+
## 教学契约（先读，Agent）
44+
45+
如果你是教授本课程的 GitHub Copilot，请遵守以下规则：
46+
47+
- **受众：** 编辑器里已经有 Copilot（常常是公司配的）、用它补全或聊天，
48+
但还没放心让 Agent 端到端改一个项目的项目所有者。这不是 Python 入门
49+
教程，也不是提示词工程课。
50+
- **前置条件：** PATH 上有 Python 3.11+，装有 VS Code，并用 GitHub 账号
51+
在 VS Code 里登录了 GitHub Copilot。无需安装任何包——课程只用标准库。
52+
Copilot Free 套餐每月的对话请求额度能否撑完整门课在编写时未经证实——
53+
见 `REVIEW.md`。
54+
- **工具：** 按 code.visualstudio.com/docs/copilot 上文档描述的 VS Code
55+
1.134 + GitHub Copilot 编写（2026-10-11 抓取）：选 Copilot 会话目标的
56+
Chat 视图、Agent/Plan/Ask 角色、Manual permissions / Allow all 两档
57+
权限、Folder 与 New Worktree 两种代码隔离、`.github/copilot-instructions.md`
58+
与 `.github/instructions/*.instructions.md`（`applyTo` front matter）、
59+
`.github/skills/` 下的 Agent Skills，以及检查点。真实授课实跑尚待
60+
完成——`REVIEW.md` 记录已验证与未验证的部分。VS Code 或 Copilot 在
61+
这些界面上的重大变更会触发课程重审。
62+
- **课序：** L01 → L02 → L03 → L04 → L05，一次课一个会话。
63+
绝不跳过课尾的检查点。
64+
- **教学风格：** 从本文件夹里的文件出发，不要凭通用知识发挥。引用
65+
你正在满足的那条契约原文。做让测试从红变绿的最小改动。绝不加
66+
依赖、绝不改 `solution/`、动当前课程未点名的任何文件前先询问。
67+
让学习者保持 **Manual permissions**——每处编辑、每条命令都等他批准。
68+
仓库根若有 `AGENTS.md`，读它——Copilot 同样会读。
69+
- **何时停下：** 一节课的检查点命令跑通、且学习者能用自己的话说清
70+
哪里坏了、为什么，这节课才算完。学习者说不出就从失败测试重新教，
71+
不要从 solution 教。
72+
- **如何使用 `verify.py`：** 学员命令就是 `python verify.py`——它跑套件、
73+
打印逐检查点状态与已获认领码，在门控检查点（l03、l04）未全通过时以
74+
非零退出。`starter --expect-failure` 与 `solution` 留作维护者检查。
75+
「完成」指学习者做完有界改动后，默认命令把所有门显示为 `[passed]`。
76+
- **诚实规则：** 说清你没验证什么。不要声称代码达到生产可用。不要
77+
承诺学习或职业结果。
78+
79+
## 本课程不覆盖什么
80+
81+
Copilot 套餐与定价、模型选择、行内补全、GitHub.com 上的 Copilot 云端
82+
Agent、拉取请求上的 Copilot 代码评审、MCP 配置、组织策略，以及任何
83+
推销内容。这些由配套仓库的指南与手册承载——给链接，不即兴发挥。
84+
85+
## 徽章契约
86+
87+
- 徽章：**Copilot 协同复现徽章**（badge id `course-github-copilot`）——认领全部五个检查点获得。
88+
- 挑战：L01–L05 检查点，各 10 分；在 flypython.com 上集齐五个再加 50 分课程徽章奖励。
89+
- 证据：`python verify.py`——L03（有界改动）与 L04（验证与评审）由套件客观把关；L01/L02/L05 为学习者自我报告。
90+
- 提交：测试通过的检查点打印确定性认领码；自报检查点要先回答课后问题，再运行 `python verify.py --attest ID` 才打印码；在 flypython.com 上记入你的账号。这是自我报告的证据，从来不是证书。
91+
92+
## 文件夹地图
93+
94+
```
95+
COURSE.md / COURSE_cn.md 本文件（EN / 中文）
96+
lessons/L01.md … L05.md 课文（每课都有一个 _cn.md 对）
97+
scenario/<skin>/ 每个皮肤的数据文件与 scenario.json
98+
TASK.md / TASK_cn.md 改动必须满足的任务契约
99+
starter/report_tool.py 有意未完成的实现
100+
solution/report_tool.py 评审过的解答（第 3 课不要抄）
101+
tests/test_report_tool.py 契约套件（只读）
102+
verify.py 客观的通过/失败证据
103+
REVIEW.md 维护者实跑记录
104+
```
105+
106+
## 证据与许可
107+
108+
本课程文件夹属于已评审内容：`REVIEW.md` 记录最近一次实跑——日期、
109+
工具版本、观察到的偏差。文件夹内代码采用 MIT 许可；课文文字采用
110+
CC BY 4.0（见仓库 `LICENSE`）。发现教学漂移或课程不清楚之处，请
111+
通过仓库的 `course-feedback` issue 表单反馈。

‎courses/hands-on-with-github-copilot/REVIEW.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Maintainer run-through record
2+
3+
## 2026-10-11 — authored from official documentation (mechanical verification only)
4+
5+
- Course authored against the VS Code GitHub Copilot documentation at
6+
code.visualstudio.com/docs/copilot, fetched 2026-10-11 (pages: local
7+
agents and session controls, custom instructions, review and revert
8+
agent changes, Agent Skills), and the shared `report-tool` core.
9+
`TASK.md`, `tests/`, `scenario/`, `starter/`, `solution/` are
10+
byte-identical to the Claude Code / Codex / Cursor course cores —
11+
enforced by the `core-group` check in `tools/verify_courses.py`.
12+
- Version reference: VS Code 1.134 with the Copilot harness on the Agent
13+
Host, as the documentation describes it on that date. No VS Code build
14+
was installed for this record.
15+
- Documented behaviors the lessons depend on (sourced, not observed):
16+
- Chat input controls: Session Target (Copilot), Agent role
17+
(Agent / Plan / Ask), Permissions (Manual permissions / Allow all),
18+
Code isolation (Folder / New Worktree; worktree sessions are always
19+
Allow all; the isolation choice exists only in the Agents window).
20+
- In Agent Host sessions edits are saved directly with no pending
21+
Keep/Undo state; review happens in the diff view and Source Control;
22+
Restore Checkpoint restores files and chat history but does not
23+
reverse completed terminal commands.
24+
- `chat.checkpoints.showFileChanges` and the
25+
`chat.tools.edits.autoApprove` glob setting for sensitive-file
26+
approval.
27+
- `.github/copilot-instructions.md` / `AGENTS.md` as always-on project
28+
instructions; `.github/instructions/*.instructions.md` attached by
29+
`applyTo` when the agent creates or modifies a matching file;
30+
References in the response show which instructions were used.
31+
- Agent Skills discovered from `.github/skills/<name>/SKILL.md`, where
32+
`<name>` must equal the skill's `name` field. Lesson 1 therefore
33+
installs the live FlyPython Skill (name `flypython-challenges`) at
34+
`.github/skills/flypython-challenges/SKILL.md`.
35+
- Commands and results (Linux, Python 3.12):
36+
- `python verify.py starter --expect-failure` — exit 0; the seven
37+
expected failures reproduced.
38+
- `python verify.py solution` — exit 0; 9/9 tests pass.
39+
- `python verify.py` — exit 1 on the shipped starter; l03/l04 `[open]`,
40+
l01/l02/l05 `[pending]`.
41+
- `python tools/verify_courses.py` — contract satisfied, core identical
42+
with the other `report-tool` members.
43+
- **Not done:** any run inside VS Code with Copilot. No Copilot account was
44+
used; every Copilot behavior described in the lessons is sourced from
45+
official documentation, not observed.
46+
47+
## Pending before this course can be called taught-in-tool
48+
49+
- One full agent-taught run-through with GitHub Copilot in VS Code
50+
("start lesson 1" through the Lesson 5 checkpoint) on a current build,
51+
recording observed deviations from `COURSE.md` here — in particular
52+
whether Manual permissions prompts before the Skill URL fetch, and
53+
whether the `applyTo` file shows up in References as Lesson 2 expects.
54+
- Whether the Copilot Free plan's monthly chat request allowance lasts the
55+
whole course is unverified.
56+
57+
## Deviation log
58+
59+
(none yet — no live run has happened)

‎courses/hands-on-with-github-copilot/TASK.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Task contract: scenario report tool (hands-on course core)
2+
3+
Change only `starter/report_tool.py`. Standard library only; no new
4+
dependencies.
5+
6+
- `load_records(path) -> list[dict]`:
7+
- `.csv` files load through `csv.DictReader`.
8+
- `.json` files load as a list of objects; a non-list or non-object payload
9+
raises `ValueError`.
10+
- Any other suffix raises `ValueError` naming the unsupported file.
11+
- `build_report(records, *, required_fields, numeric_field, group_field) -> dict`:
12+
- Returns `{"total", "valid", "invalid", "groups", "errors"}`.
13+
- Invalid rows never abort the run: each is collected in `errors` as
14+
`{"index": <row position>, "reason": <short string>}`. Invalid means:
15+
not a dict, missing or blank required field, or a non-numeric
16+
`numeric_field` value (booleans do not count as numbers).
17+
- Valid rows aggregate into `groups[group_value] = {"count": int,
18+
"total": float}`; each group total is rounded to two decimals.
19+
- `total = valid + invalid` must hold for every input.
20+
- `write_report(report, destination)`:
21+
- Writes JSON (UTF-8, indent 2, trailing newline) atomically: write a
22+
sibling temp file, then `os.replace`.
23+
- Creates missing parent directories.
24+
- Never leaves a `.tmp` file behind on success.
25+
- `run_scenario(scenario_dir) -> dict`:
26+
- Reads `scenario.json` (`data_file`, `required_fields`, `numeric_field`,
27+
`group_field`, `report_file`), processes the data file, writes the
28+
report inside the scenario directory, and returns the report.
29+
- `main(argv=None) -> int`:
30+
- Exactly one argument (the scenario directory). Otherwise print usage to
31+
stderr and return 2.
32+
- On success print `total=... valid=... invalid=...` to stdout and return 0.
33+
- On input failure print `error: ...` to stderr and return 1.
34+
35+
Done means `python verify.py starter` exits 0 with all nine tests passing,
36+
and `python verify.py starter --expect-failure` exits nonzero because the
37+
starter no longer reproduces the unfinished state.

0 commit comments

Comments
 (0)