# lesson-site

**Repository Path**: blackfox/lesson-site

## Basic Information

- **Project Name**: lesson-site
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-09-17
- **Last Updated**: 2026-09-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 课程讲义站点

本站点独立存放在 `lesson-site`；备课技能工作区不再混合存放站点源码。

VitePress 讲义预览系统，按课时组织内容。

```bash
npm install
npm run validate:site
npm run dev      # 默认 http://localhost:3000
npm run build
npm test         # 备课技能校验器正反向用例
```

端口、`base`、host、站点标题等见 [`CONFIG.md`](./CONFIG.md)，在 `docs/.vitepress/config.mts` 里改。顶栏品牌名读 `config.title`，不要在主题里写死。

新增一次课时，把讲义和资料放到：

```text
docs/courses/<courseId>/lesson-NN/index.md       # 讲义
docs/courses/<courseId>/lesson-NN/exercises.md   # 习题预览
docs/courses/<courseId>/lesson-NN/interactive.md # 可选互动页包装
docs/courses/<courseId>/lesson-NN/assets/html/interactive.html
```

课次页会根据 `courses.json` 自动显示“讲义 / 习题 / 互动”切换。站点数据会在 `npm run dev` / `npm run build` 前重新扫描；开发服务运行中新增课次后，重启开发服务即可刷新课程导航。


## 课程资料

每课包含 `materials.json` / `materials.md`。最终 PPT 和学习通习题 DOCX 的真源在 `lesson-site/deliverables/<courseId>/lesson-NN/`，发布时按体积分流：

| 体积 | 处理 |
|---|---|
| `< 1 MB` | 复制进课次 `assets/files/`，学生直接下载 |
| `>= 1 MB` | 不落地，只登记学习通附件地址，避免部署包膨胀 |

```bash
# 按体积自动分流
python3 ../skills/lesson-material-kit/scripts/publish.py --site-root . --course-id aigc --lesson-no 6

# 大附件拿到学习通地址后回填（状态自动变 ready）
python3 ../skills/lesson-material-kit/scripts/publish.py --site-root . --course-id aigc --lesson-no 6 \
  --slides-url "https://学习通附件地址"

# 调整阈值（字节，默认 1048576）
python3 ../skills/lesson-material-kit/scripts/publish.py --site-root . --course-id aigc --lesson-no 6 \
  --max-local-size 524288
```

大附件未上传时清单里是 `"url": ""` + `"status": "pending"`，页面显示“待上传”且不给可点击链接。查所有待补地址：`grep -rn '"url": ""' docs`。

## 部署（Docker）

对齐 `geekai-docs`：先构建静态站，再打 Nginx 镜像推到阿里云，服务器用 compose 跑在 **3001**。

```bash
# 构建静态站 + 打镜像（在 build/ 目录执行）
cd build
./build.sh v1.0.0        # 只构建
./build.sh v1.0.0 push   # 构建并推送到阿里云
```

服务器目录建议：

```text
docker/
  docker-compose.yaml
  conf/nginx/          # 从仓库 build/conf/nginx 拷过去
  logs/nginx/
```

```bash
# 更新 tag 后
docker compose pull
docker compose up -d
# 访问 http://服务器:3001
```

构建产物是 `docs/.vitepress/dist`，由 Dockerfile `COPY` 进镜像。`deliverables/`、`node_modules/`、`docs/.vitepress/cache/` 都不进镜像；校验器还会拦住任何试图放进 `docs/` 的 `.ppt/.pptx/.doc/.docx`。


## 互动学习页

新增互动页统一用 `skills/interactive-lesson-kit` 的 **format-v3**（不要手写旁路结构）。可回改源稿在 `deliverables/<courseId>/lesson-NN/interactive-plan.json`，生成器写入 `interactive.md` 与 `assets/html/interactive.html`。交付前跑 `validate.py` + `interactive_smoke.mjs`。

## 讲义内容红线（站点侧）

讲义内容规则以备课工作区根目录 `CLAUDE.md` 为准。站点构建会强制执行这些门禁：

- 学生机命令一律 **Windows cmd**（代码块标 `bat`），路径 `D:\AIGC\lesson-<课次号>`（课次号不补零）。
- **禁止** `/images/placeholder.svg` 一类截图占位；缺失本地图会让构建失败。
- 提示词等文本素材应内联进讲义；`< 1 MB` 的课件/导入包可进 `assets/files/`，更大的只登记学习通地址。