# offline-interactive-course

**Repository Path**: OrangeCatDuster/offline-interactive-course

## Basic Information

- **Project Name**: offline-interactive-course
- **Description**: 这是一个强大的SKILL，可以开启多并发Agent共同生成一套可交互的学习材料，形象易懂。
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-01
- **Last Updated**: 2026-11-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# offline-interactive-course · 离线交互式工程课程

把一个工程主题做成**断网时用浏览器直接打开**的分章交互式教程：首页加每章一个 HTML，含 2D/3D 交互演示、KaTeX 公式、易错与避坑、算例、自测、术语表。

本目录是一个完整的 Agent Skill：自带页面模板、离线 three.js 与 KaTeX、两套已校核的共享计算模型，以及只依赖 Node.js 和本机 Chrome/Edge 的检查脚本。

> 许可证：本项目自有代码与课程成品均采用 **MIT**。第三方组件（three.js、KaTeX）各自保留其 MIT 许可。完整条款见 [开源声明.md](开源声明.md)。

---

## 目录

- [它能做什么](#它能做什么)
- [产出长什么样](#产出长什么样)
- [环境要求](#环境要求)
- [快速开始](#快速开始)
- [目录结构](#目录结构)
- [脚本速查](#脚本速查)
- [领域包](#领域包)
- [质量门槛](#质量门槛)
- [作为 Agent Skill 使用](#作为-agent-skill-使用)
- [常见问题](#常见问题)
- [已知限制](#已知限制)
- [许可](#许可)

---

## 它能做什么

| 能力 | 说明 |
| --- | --- |
| 生成新课 | 主题 → 大纲 → 脚手架 → 逐章写 → 全量验收，一条命令链跑完 |
| 续写课程 | 在已有课程目录追加章节，注册表重写、已写好的章节不覆盖 |
| 复核课程 | 逐章查知识点与交互逻辑错误，每处修改都要有推导、复算或实测依据 |
| 升级版式 | 旧课程换成当前模板的 `course.css` / `course.js`，保留注册表与章节内容 |
| 造新领域 | 领域包机制：一份共享计算模型 + 校核脚本，全课数字统一、跨章一致 |

**内置两个已校核的领域包**：

- `fe-structural` —— 结构有限元：单元、网格、材料、接触、静力与非线性、模态、隐式与显式动力学、强度屈曲、疲劳、碰撞跌落。
- `vehicle-mbd` —— 车辆多体：悬架与五连杆、轮胎、转向、K&C、操稳、平顺性、整车。

**不适用**：只问一个概念且不需要成套资料；分析测试平台失败用例、跑自动化用例、写测试脚本、分析缺陷单。

---

## 产出长什么样

```text
<课程目录>/
  index.html                       首页：课程名、篇与章卡片、主题筛选
  ch01_<slug>.html … chNN_<slug>.html   每章一个文件，文件名只用 ASCII 小写
  assets/css/course.css            共用样式（版式合同）
  assets/js/course.js              注册表 + VMD 框架：导航、控件、自测、曲线、2D 画布、3D、色表
  assets/js/vmd-models.js          共享计算模型：纯计算、无 DOM
  assets/lib/three.min.js          three.js r147（UMD，全局 THREE）
  assets/lib/OrbitControls.js      three.js r147 examples/js 经典脚本
  assets/lib/katex/…               KaTeX 与字体
```

整门课是一个文件夹，**双击 `index.html` 就能离线打开**：无 CDN、无远程字体、无 `fetch`、无 `type="module"`。所有三方库与字体随包分发。

### 页面合同要点

- `<head>` 顺序固定：charset → viewport → 一条 `<meta name="author">` → title → `katex.min.css` → `course.css` → `katex.min.js` → `auto-render.min.js` → `three.min.js` → `OrbitControls.js` → `course.js` → `vmd-models.js` → 本章 `<style>`。
- 章末四块固定顺序：本章避坑清单 → 自测题 → 术语表 → 本章小结与延伸阅读。
- 每个 HTML **只保留一处可见署名**（章首 `.meta` 的第一个 chip）和**一条** `<meta name="author">`。
- 正文内容列最宽 2100 px；侧栏 408–600 px 且不超过 36% 视口，1100 px 以下收成抽屉；3D 渲染区固定宽:高 = √2:1。

细则见 [course-contract.md](course-contract.md)。

---

## 环境要求

| 依赖 | 要求 |
| --- | --- |
| Node.js | **≥ 18**（本机实测 v22.17.0 通过） |
| 浏览器 | Chromium 内核任一：Edge / Chrome / Chromium（本机实测 Edge 156，headless + WebGL 可用） |
| npm 包 | **不需要** |
| Python | **不需要** |
| 联网 | **不需要** |

自检：

```bash
node scripts/doctor.js [<课程目录>]
```

输出 `DOCTOR: OK` 才继续。找不到浏览器时设置 `OCC_BROWSER=<浏览器可执行文件路径>`；WebGL 不可用时 3D 检查会报降级，需换有显卡的机器或开启硬件加速。

### 环境变量

| 变量 | 作用 |
| --- | --- |
| `OCC_BROWSER` | 浏览器可执行文件路径（自动查找失败时用） |
| `OCC_COURSE` | 课程目录（命令行不方便传中文路径时用） |
| `OCC_OUT` | 报告与截图目录，默认系统临时目录下的 `occ-reports/<课程目录名>/` |

---

## 快速开始

以一门新课为例，从零到验收共 8 步。命令都在本技能目录下运行；在别处运行时写成 `node <技能目录>/scripts/…`。

### 1. 环境自检

```bash
node scripts/doctor.js
```

### 2. 写大纲

两份文件，派写章任务前必须冻结：

- `outline.json` —— 课程名、作者、领域包、篇与章；脚手架据此生成注册表、首页与占位页。格式见 [template/outline.example.json](template/outline.example.json)。
- `大纲.md` —— 全课约定（单位制、正负号、坐标方向、符号表、共用数字）+ 每章任务书。

一门课按五篇展开，篇名随领域改，顺序不改：共同语言 → 部件与建模要素 → 分析方法 → 性能评价 → 实战。

### 3. 脚手架

```bash
node scripts/scaffold.js <课程目录> --outline=<outline.json> --pack=<包> [--demo]
```

`--pack` 取 `fe-structural` / `vehicle-mbd` / `none`；`--demo` 让第一章填成样板章。命令**可重复运行**：已写好的章节不会被覆盖。

### 4. 模型校核

```bash
node packs/<包>/test_models.js <课程目录>
```

输出 `ALL CHECKS PASSED` 才允许派发写章任务。**以后每次改模型都要重跑**，并让引用了改动数字的章节复核正文与演示读数。

### 5. 写章

每章一个任务，任务书模板见 [subagent-brief.md](subagent-brief.md)。平台支持并行子任务时并行跑，否则主任务按同一份任务书串行做。多任务编排、进度跟踪与故障恢复见 [orchestration.md](orchestration.md)。

写作过程中随时自查：

```bash
node scripts/status.js <课程目录>        # 每章大小、h2 数、演示数、残留占位、修改时间
```

### 6. 全量验收

```bash
node scripts/verify_all.js <课程目录> --final --probe
```

通过标准：`VERIFY: ALL PASSED`。

### 7. 抽查

```bash
node scripts/shots.js <课程目录> --3d --sheet   # 全部 3D 演示拼成总览图
```

再手工打开首页、第 1 章、一个 2D 曲线、一道自测题。

### 8. 交付

交付说明写清：课程目录、章数、验收结论、已知限制、偏离用户要求之处。

---

## 目录结构

```text
offline-interactive-course/
  SKILL.md                 本文件：流程、门槛、索引
  README.md                项目说明（本文件）
  开源声明.md              许可证与第三方组件声明
  course-contract.md       页面、样式、脚本合同与 API 速查（含版式合同）
  authoring-guide.md       内容怎么写透：小节结构、数量门槛、算例、易错与避坑、演示设计
  quality-checklist.md     写作与复核共用的错误清单
  subagent-brief.md        写章任务书模板
  review-brief.md          逐章复核任务书模板
  orchestration.md         多任务并行编排、进度跟踪、续跑与故障恢复
  template/                课程模板：assets、首页、占位页、样板章、大纲示例
  packs/                   领域包：fe-structural、vehicle-mbd
  scripts/                 脚手架、升级、校验、浏览器检查、截图、静态服务
```

---

## 脚本速查

全部脚本只依赖 Node.js ≥ 18 与本机 Chromium 内核浏览器。浏览器类脚本通过 `lib/cdp.js` 以无头模式直接驱动浏览器（Chrome DevTools Protocol 走管道），用临时用户目录，结束后自动删除。

用法：`node scripts/<脚本> <课程目录> [chNN …] [选项]`。章节可写章号（`ch05`）或文件名；不写就是首页加全部注册章节。

| 脚本 | 用途 | 通过标准 |
| --- | --- | --- |
| `doctor.js` | 环境自检：Node 版本、浏览器、无头 WebGL、报告目录 | `DOCTOR: OK` |
| `scaffold.js` | 按大纲 JSON 新建或更新课程 | 复制资产、装领域包、写注册表、生成首页与占位页 |
| `upgrade_assets.js` | 旧课程换模板版 `course.css` / `course.js` | 保留注册表，不动章节与模型 |
| `verify_all.js` | 依次跑下面几项并汇总 | `VERIFY: ALL PASSED` |
| `validate_course.js` | 静态合同：注册表与文件、离线资源、head 顺序、署名、id 等 | `errors=0` |
| `lint_content.js` | 内容扫描：公式里的 `<`、残留占位、重复脚本块等 | `errors=0` |
| `check_pages.js` | 逐页打开并滚动：脚本错误、资源失败、公式、链接、署名 | `TOTAL_ISSUES=0` |
| `quiz_check.js` | 自测题可提交性、多选正确项、解析不按位置引用 | `TOTAL_PROBLEMS=0` |
| `demo_probe.js` | 每个演示的控件拖到两端：NaN/Infinity、重算超时 | `TOTAL_ANOMALIES=0` |
| `layout_check.js` | 多宽度版式：1280 / 1920 / 2560 | `TOTAL_ISSUES=0` |
| `status.js` | 写作进度：占位页、大小、h2、演示数、残留占位 | `STATUS done=N/N` |
| `shots.js` | 截图（`--3d` / `--demos` / `--top` / `--el=`），`--sheet` 拼总览图 | — |
| `serve.js` | 本地静态服务，给打不开 `file://` 的内置浏览器预览 | 只监听 127.0.0.1 |

`scaffold.js` 常用选项：`--outline=`（必填）、`--pack=none|fe-structural|vehicle-mbd|<包目录>`、`--demo`、`--force-assets`、`--force-models`、`--force-index`、`--dry-run`。

`verify_all.js` 常用选项：`--author=`、`--final`（占位页算错误）、`--quick`、`--probe`、`--widths=`。

详细参数与报告位置见 [scripts/README.md](scripts/README.md)。

---

## 领域包

领域包是一份共享计算模型 `vmd-models.js` 加上它的校核脚本。课程的公式、示例对象和全课共用数字都从包里来，各章只引用，不另造。

| 包 | 适用课程 | 校核 |
| --- | --- | --- |
| `none`（模板自带骨架） | 任何主题的起步；只带一个单自由度振子示例 | 无 |
| `fe-structural` | 结构有限元：单元、网格、材料、接触、静力与非线性、模态、隐式与显式动力学、强度屈曲、疲劳、碰撞 | 38 项数值校核 |
| `vehicle-mbd` | 车辆多体：悬架与五连杆、轮胎、转向、K&C、操稳、平顺、整车 | 18 项闭式解与冒烟校核 |

两个包的模型都只用纯计算、不碰 DOM，末尾挂到 `VMD` 命名空间；共用数据放 `VMD.data`，模型放各自的 `VMD.fe` / `VMD.veh`。

新建一个包的步骤见 [packs/README.md](packs/README.md)。

---

## 质量门槛

交付前全部满足；任一不满足就改到满足为止。

| 检查 | 命令 | 通过标准 |
| --- | --- | --- |
| 一键验收 | `verify_all.js --final --probe` | `VERIFY: ALL PASSED` |
| 静态合同 | `validate_course.js` | `errors=0` |
| 内容扫描 | `lint_content.js` | `errors=0`；提醒逐条看过 |
| 逐页检查 | `check_pages.js` | `TOTAL_ISSUES=0` |
| 自测与导航 | `quiz_check.js --dump` | `TOTAL_PROBLEMS=0`，逐题核对过答案 |
| 多宽度版式 | `layout_check.js`（1280、1920、2560） | `TOTAL_ISSUES=0` |
| 演示控件 | `demo_probe.js` | `TOTAL_ANOMALIES=0`；"观察要点"里的数字能在读数里复现 |
| 共享模型 | `packs/<包>/test_models.js` | `ALL CHECKS PASSED` |

**内容量的默认门槛（全面型课程，每章）**：正文 9–12 个 h2 小节；避坑与易错框 ≥ 12 个；带完整数字的算例 ≥ 3 个；交互演示 ≥ 4 个；章末避坑清单 ≥ 10 条；自测 ≥ 10 题且至少 3 道多选；术语 ≥ 15 条；正文约 1.6 万字以上。用户要的是短课时，在大纲里写明下调。

完整清单见 [quality-checklist.md](quality-checklist.md)——每条都配了曾经真实出现过的例子。

---

## 作为 Agent Skill 使用

本目录根部的 `SKILL.md` 带标准 frontmatter（`name` / `author` / `description`），可直接作为一个技能目录安装：

```text
C:\Users\Tao\.minimax\skills\offline-interactive-course\
  SKILL.md
  course-contract.md
  authoring-guide.md
  ...
```

安装后即可用自然语言触发，例如"写一门关于显式动力学与接触的离线交互式教程"、"复核这门课程的知识点和交互逻辑"、"把旧课程升级到当前版式"。`description` 字段已经写明适用与不适用场景，以及有限元、隐式与显式、结构仿真、车辆多体、悬架、轮胎、K&C、操稳、平顺等触发词。

> 若换用其他支持 `SKILL.md` 约定的 Agent 运行时，把整个目录复制到该运行时的技能目录即可，其余文件结构不用改。

**使用时的路径约定**：课程只写入用户指定的目录；报告、截图、草稿等临时文件放进临时目录（`--out=<临时目录>` 或 `OCC_OUT`）；续写或修改已有课程时在原目录改，不复制出第二套 `assets/`。

---

## 常见问题

**打不开浏览器里的 `file://` 页面**
用本地静态服务预览：`node scripts/serve.js <课程目录> --port=8765`，然后访问 `http://127.0.0.1:8765/`。

**Windows 终端中文乱码**
PowerShell 里先执行 `[Console]::OutputEncoding = [System.Text.Encoding]::UTF8`，或直接读脚本写出的 UTF-8 报告文件（`<out>/check_pages.txt` 等）。PowerShell 5 把多行命令写成临时脚本按本地编码读入，**中文路径会坏**——涉及中文路径时用单行命令（`;` 连接）或写成 Node 脚本，或先 `cd` 到课程目录再运行。

**3D 检查报降级**
WebGL 在当前机器不可用。换有显卡的机器或开启硬件加速；无头模式默认走 `--use-angle=d3d11`，没有可用显卡时退回 SwiftShader 软件渲染（较慢但能出图）。

**脚手架报"找不到字符串"**
替换类工具有时在已写入的情况下仍报找不到。重试前先搜索确认内容是否其实已经写入，再决定要不要重试——盲目重试容易把同一段脚本写两遍（`lint_content.js` 会报逐字重复的脚本块）。

**页面出现 "ResizeObserver loop …" 提示**
这是已被 `course.js` 忽略的浏览器提示，不是脚本错误。

**自测选项顺序看起来乱了**
选项按题干哈希打乱显示，这是设计如此。因此解析必须按内容说，不写"选 B""前两项"。

---

## 已知限制

- 每页 3D 视图不超过 5 个（WebGL 上下文上限）。
- 课程正文里的公式不支持对数轴（自己取 `log10` 并用 `xTickFormat`）；3D 场景 Z 轴向上、单位米。
- `upgrade_assets.js` 会列出旧版独有的公开 API 并停止，不会静默替换。
- 写章与复核期间 `course.js` / `course.css` / `vmd-models.js` 冻结：任务只汇报公共库缺陷，全部任务结束后统一修。
- 示例参数是**教学取值**，不写成任何量产产品或具体牌号的数据；演示里构造的"试验数据"一律标注"教学构造数据"。
- 软件菜单、关键字、默认值、报错原文不作定论，一律写"以所用软件版本的文档为准"。

---

## 许可

本项目自有代码（`SKILL.md`、`scripts/`、`template/`、`packs/`、各 Markdown 文档）与由本技能生成的课程成品（正文、算例、插图）均采用 **MIT** 许可。

随包分发的第三方组件**各自保留其原始许可**，本项目不改变也不替代它们：

| 组件 | 版本 | 许可 |
| --- | --- | --- |
| three.js（`three.min.js`） | r147（`THREE.REVISION = 147`） | MIT，Copyright 2010-2022 Three.js Authors |
| three.js OrbitControls（`OrbitControls.js`） | r147 `examples/js` 经典脚本 | MIT（与 `three.min.js` 同版本） |
| KaTeX（`katex.min.js`、`katex.min.css`、`auto-render.min.js`、`fonts/`） | 0.19.1 | MIT，见 `template/assets/lib/katex/LICENSE.txt` |

版权声明、MIT 全文、合规使用要求与选型理由见 **[开源声明.md](开源声明.md)**。

> 第三方组件的原始声明随包保留在 `template/assets/lib/three.min.js` 的文件头与 `template/assets/lib/katex/LICENSE.txt`；分发本项目时请勿删除这两处。

---

## 本机实测记录

2026-11-01 在 Windows 11 / PowerShell 7 环境下实测：

```text
node scripts/doctor.js                              → DOCTOR: OK
node packs/fe-structural/test_models.js             → 38 ok / 0 FAIL / ALL CHECKS PASSED
node packs/vehicle-mbd/test_models.js               → 18 ok / 0 FAIL / ALL CHECKS PASSED
```

环境：Node.js v22.17.0、Edge 156.0.4314.58（headless）、WebGL 走 ANGLE D3D11 可用。