课程库 › AI 主线 › 本地环境与 Git › 第 5 课

验收：把 U1.3 项目推上 GitHub —— 第一件公开作品

里程碑约 60 分钟

本课导读

U1.4 收官验收，也是一个里程碑时刻：把 U1.3 写的文件批量整理器搬进真实电脑、在真实文件上跑通、配上像样的 README、推上 GitHub——你的作品第一次拥有一个可以发给任何人的链接。整个过程就是本单元四课的综合演练：Python 环境、VS Code、命令行、Git，一个都不缺席。预计 60 分钟。

第零步：搬运代码（沙盒 → 真机）

下面是整理器的本地完整版——相比 U1.3 的沙盒版只多了两处：入口处的"测试现场生成"独立成函数（真实使用时不需要它），以及底部的运行入口。先通读一遍确认都是熟面孔：

Python

from pathlib import Path
import csv
import random


def make_test_folder(folder="test_chaos"):
  """生成测试现场（真实使用时不需要，用你自己的文件夹）"""
  root = Path(folder)
  root.mkdir(exist_ok=True)
  words = ["报销单", "截图", "合同", "数据", "会议", "方案"]
  exts = [".pdf", ".jpg", ".csv", ".txt"]
  random.seed(42)
  for i in range(18):
      name = f"{random.choice(words)}{random.randint(1, 999)}{random.choice(exts)}"
      (root / name).write_text(f"内容{i}", encoding="utf-8")
  return root


def organize(folder, dry_run=True):
  """按类型归档 + 统一改名 + 生成清单.csv；默认彩排（dry_run=True）"""
  root = Path(folder)
  groups = {}
  for p in sorted(root.iterdir()):
      if p.is_dir():
          continue
      kind = p.suffix.lstrip(".")
      groups.setdefault(kind, []).append(p)

  records = []
  for kind, files in sorted(groups.items()):
      target_dir = root / kind
      for i, p in enumerate(files, 1):
          new_name = f"{kind}-{i:02d}-{p.name}"
          if dry_run:
              print(f"[彩排] {p.name} → {kind}/{new_name}")
              continue
          target_dir.mkdir(exist_ok=True)
          size = len(p.read_text(encoding="utf-8"))
          p.rename(target_dir / new_name)
          records.append([p.name, f"{kind}/{new_name}", size])

  if not dry_run:
      with open(root / "清单.csv", "w", encoding="utf-8", newline="") as f:
          writer = csv.writer(f)
          writer.writerow(["原名", "新位置", "字数"])
          writer.writerows(records)
      print(f"完成：归档 {len(records)} 个文件，清单已生成")


# 运行入口：先在测试现场彩排，确认无误再真跑
folder = make_test_folder()
organize(folder)                    # 彩排
organize(folder, dry_run=False)     # 放行

from pathlib import Path
import csv
import random

def make_test_folder(folder="test_chaos"):
  """生成测试现场（真实使用时不需要，用你自己的文件夹）"""
  root = Path(folder)
  root.mkdir(exist_ok=True)
  words = ["报销单", "截图", "合同", "数据", "会议", "方案"]
  exts = [".pdf", ".jpg", ".csv", ".txt"]
  random.seed(42)
  for i in range(18):
      name = f"{random.choice(words)}{random.randint(1, 999)}{random.choice(exts)}"
      (root / name).write_text(f"内容{i}", encoding="utf-8")
  return root

def organize(folder, dry_run=True):
  """按类型归档 + 统一改名 + 生成清单.csv；默认彩排（dry_run=True）"""
  root = Path(folder)
  groups = {}
  for p in sorted(root.iterdir()):
      if p.is_dir():
          continue
      kind = p.suffix.lstrip(".")
      groups.setdefault(kind, []).append(p)

records = []
  for kind, files in sorted(groups.items()):
      target_dir = root / kind
      for i, p in enumerate(files, 1):
          new_name = f"{kind}-{i:02d}-{p.name}"
          if dry_run:
              print(f"[彩排] {p.name} → {kind}/{new_name}")
              continue
          target_dir.mkdir(exist_ok=True)
          size = len(p.read_text(encoding="utf-8"))
          p.rename(target_dir / new_name)
          records.append([p.name, f"{kind}/{new_name}", size])

if not dry_run:
      with open(root / "清单.csv", "w", encoding="utf-8", newline="") as f:
          writer = csv.writer(f)
          writer.writerow(["原名", "新位置", "字数"])
          writer.writerows(records)
      print(f"完成：归档 {len(records)} 个文件，清单已生成")

# 运行入口：先在测试现场彩排，确认无误再真跑
folder = make_test_folder()
organize(folder)                    # 彩排
organize(folder, dry_run=False)     # 放行

（在页面里跑一遍热热身没问题——但今天的主战场在你的电脑上。）

说明

真机第一戒：这个脚本会真的移动你电脑上的文件。所以它默认 dry_run=True（彩排），而且我们先永远只对 make_test_folder() 生成的测试文件夹动手。想整理真实的下载文件夹？先彩排、逐条人眼确认、想清楚再放行——沙盒时代结束了，敬畏心上线。

验收流程

分步操作

建项目文件夹并放入代码
终端进入 learnpath，mkdir file-organizer 再 cd file-organizer，然后 code . 打开 VS Code。新建 organizer.py，把上面的完整代码抄进去（建议手抄一遍主函数——这是最后一次整体过这段逻辑的机会）。
本地跑通：彩排 → 放行
终端执行 python organizer.py。应看到：18 条彩排计划 + 归档完成的提示。用 ls（或资源管理器）确认 test_chaos 里出现了分类子文件夹和清单.csv，用 VS Code 打开清单看一眼内容。
截图占位：本地运行 organizer.py 的终端输出与生成的文件夹结构
写 README.md
新建 README.md，按门面三问来写（模板见下方）。存盘后在 VS Code 里右键 README.md → 打开预览，检查渲染效果。
加一个最小 .gitignore
新建名为 .gitignore 的文件（注意开头有个点、没有后缀），写入一行：test_chaos/ ——测试现场是运行产物，不该进仓库。这是你的第一个 .gitignore，规矩从简。
本地存档
git init → git status（确认 test_chaos 没被列出——.gitignore 生效了）→ git add . → git commit -m "文件批量整理器：归档+改名+清单，支持彩排模式"。
截图占位：git status 显示 test_chaos 已被忽略
推上 GitHub
GitHub 上 New repository，仓库名 file-organizer，不勾初始化选项；按页面给出的 push an existing repository 命令接线并推送。刷新页面：代码和 README 门面都在线上了。
截图占位：GitHub 上的 file-organizer 仓库首页
终极检查：链接测试
复制仓库网址，用手机浏览器（或无痕窗口）打开——想象一位面试官点开它：README 能 10 秒说清项目价值吗？代码文件名清爽吗？达标即验收通过。

README 模板（按需修改，别整段照搬）：

# file-organizer 文件批量整理器

一键把混乱文件夹按类型归档：分类、统一重命名、生成 CSV 清单。
手工两小时的整理活，一秒完成。

## 功能
- 按扩展名归类到子文件夹（pdf/ jpg/ csv/ …）
- 统一命名：类型-序号-原名
- 自动生成 清单.csv（原名 / 新位置 / 字数）
- 彩排模式（dry_run）：先预览计划，确认再执行

## 使用
python organizer.py
默认对内置测试文件夹彩排 + 执行；整理自己的文件夹时
修改底部入口的 folder 并先保持 dry_run=True 预览。

## 技术点
pathlib 批量扫描与重命名 · 字典分组 · csv 报表 · 幂等可重复运行

单元综合测验

随堂测验0 / 10 题正确

1. Windows 安装 Python 时忘勾 PATH，最省事的补救是？

2. pip install pandas 这个命令在做什么？

3. VS Code 中让代码一键变符合 PEP8 的操作是？

4. 终端里 cd file-organizer 之后运行 python organizer.py，前提是？

5. 改完代码后，把改动同步到 GitHub 的完整节奏是？

6. .gitignore 文件的作用是？

7. 为什么本课坚持先对 make_test_folder 的测试文件夹运行，而不是直接整理下载文件夹？

8. README 的“门面三问”是？

9. git status 显示 test_chaos 没有出现在待提交列表，说明？

10. 完成本课后，你拥有的“第一件公开作品”指的是？

通关小结 + 一条新约定

你现在的装备：本机 Python + VS Code + 命令行 + Git/GitHub——真实开发者的标准四件套，一样不缺。GitHub 上还躺着一个有 README、有提交记录、能跑的真实项目。

从下个单元开始的双轨约定：课程代码块依然可以页面内直接运行（草稿纸不撤），但每课会附本地运行指引；建议练习和项目一律本地完成。U1.5 第一课就从 pip install 数据分析全家桶开始——你的 Python 即将迎来 pandas。

划选正文任意文字可高亮、批注或加入复习卡

讨论

载入中…