全部题目、规范、评分、提交见 题面.pdf。 本 README 只讲怎么把环境跑起来；没在这里出现的规格细节，一律以题面为准。
- Python 3.8+，仅标准库（不允许第三方运行时依赖）；
- 开发工具只需
pytest（测试）与autopep8（风格，CI 会检查）； - VS Code 打开仓库会推荐安装
ms-python.autopep8插件（.vscode/extensions.json），保存即格式化即可过风格检查。
# 1. 用 GitHub 的 Use this template 创建你自己的仓库，然后 clone
git clone https://github.com/<你的用户名>/<你的仓库>.git
cd <你的仓库> # 直接在 main 分支上开发
# 创建虚拟环境
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate
# 2. 装依赖
python -m pip install pytest autopep8
# 3. 启用 AI 会话归档钩子（课程要求，见下方第 3 节）
python -m pip install 'agent-session-commit[pre-commit]==0.1.3' -i https://pypi.org/simple
agent-session-commit install --pre-commit # 交互选择你的 AI 助手与会话目录
# 4. 跑测试（刚到手：全部 skip，CI 是绿的）
python -m pytest
# 5. 看演示
python main.py
# 6. 打开 题面.pdf 读题，开始实现 src/main/__init__.py 里的 TODO本课程允许使用 AI，提交的 commit 需要携带 AI 会话归档作为透明化记录：每次 git commit 后，钩子会把新增会话自动 amend 进同一个提交（.agent-sessions/bundles/），不产生额外的归档提交。支持 Claude Code、OpenAI Codex CLI、GitHub Copilot CLI、Qoder、ZCode、Trae、Tencent CodeBuddy 等（完整名单见 AgentLedger）。
- 配置是仓库本地的：每个 clone 运行一次
agent-session-commit install --pre-commit，方向键选择 agent、确认其会话目录即可； - 不想用 TUI 可手动配置：
git config --local agent-session.agent claude、git config --local agent-session.source "<会话目录>"，然后python -m pip install 'pre-commit>=3.2.0' && pre-commit install； - 归档是普通 Git 内容且会推送到公开仓库——不要在 AI 会话里粘贴令牌等敏感信息；
- 换了 agent 或目录就重跑一次安装命令；卸载：从
.pre-commit-config.yaml移除该条目后重跑pre-commit install。
- 写代码：全部作业在
src/main/__init__.py，按题面各题规范补全每个标有 TODO 的函数；注释里标注了对应的题面主题，推荐顺序 Q1 → Q6。 - 跑测试：
python -m pytest—— 可见测试是规格书的一部分，未实现的函数自动 skip，实现一个、对应测试亮一个。本地全绿 ≠ 满分（见题面）。 - 看演示：
python main.py（等价于PYTHONPATH=src python -m main），随实现进度逐段点亮，不进测试。 - Q6 自测：
python tools/run_seeds.py --q6（200 张固定地图统计），单 seed 渲染python tools/run_seeds.py --q6 --seed <N> --render，Bonus 模式python tools/run_seeds.py --bonus。
| 路径 | 说明 | 能否修改 |
|---|---|---|
src/main/__init__.py |
你的全部作业（TODO 所在） | ✅ |
README.md |
仅末尾两个"你来写"小节 | ✅ |
题面.pdf |
题面（唯一规格说明） | ❌ 勿改 |
src/main/legacy_patrol.py |
Q7 模块（与主体同步发布，修复其缺陷） | Q7 时 ✅ |
.pre-commit-config.yaml |
AI 会话归档钩子配置 | ❌ 勿改 |
src/tests/、tools/、.github/、conftest.py、pytest.ini、main.py |
测试与基础设施 | ❌ 勿改 |
CI 只允许修改 src/main/**、README.md 与 .agent-sessions/**（AI 会话归档）——其余文件改了直接红；autopep8 --diff 非空即败。提交方式（push、问卷、commit 粒度）见题面"提交与验收"一节。