build-interactive-tutorial

Files (39)

• SKILL.md
• .gitkeep · assets/compiler/
• builder.py · assets/compiler/
• linter.py · assets/compiler/
• parser.py · assets/compiler/
• server.py · assets/
• .gitkeep · assets/static/
• app.js · assets/static/
• index.html · assets/static/
• style.css · assets/static/
• chart.umd.min.js · assets/static/vendor/chart/
• codemirror.min.css · assets/static/vendor/codemirror/
• codemirror.min.js · assets/static/vendor/codemirror/
• go.min.js · assets/static/vendor/codemirror/mode/go/
• python.min.js · assets/static/vendor/codemirror/mode/python/
• cytoscape.min.js · assets/static/vendor/cytoscape/
• KaTeX_AMS-Regular.woff2 · assets/static/vendor/katex/fonts/
• KaTeX_Caligraphic-Regular.woff2 · assets/static/vendor/katex/fonts/
• KaTeX_Main-Bold.woff2 · assets/static/vendor/katex/fonts/
• KaTeX_Main-Italic.woff2 · assets/static/vendor/katex/fonts/
• KaTeX_Main-Regular.woff2 · assets/static/vendor/katex/fonts/
• KaTeX_Math-BoldItalic.woff2 · assets/static/vendor/katex/fonts/
• KaTeX_Math-Italic.woff2 · assets/static/vendor/katex/fonts/
• KaTeX_Size1-Regular.woff2 · assets/static/vendor/katex/fonts/
• KaTeX_Size2-Regular.woff2 · assets/static/vendor/katex/fonts/
• KaTeX_Size3-Regular.woff2 · assets/static/vendor/katex/fonts/
• KaTeX_Size4-Regular.woff2 · assets/static/vendor/katex/fonts/
• katex.min.css · assets/static/vendor/katex/
• katex.min.js · assets/static/vendor/katex/
• curriculum-design-matrix.md · references/
• dsl-spec.md · references/
• pedagogy-scaffolds.md · references/
• security-and-sandboxing.md · references/
• visual-and-pedagogy-design-spec.md · references/
• .gitkeep · scripts/
• compile.py · scripts/
• new_topic.py · scripts/
• serve.py · scripts/
• .gitkeep · tutorials/

SKILL.md (first lines)

# Build Interactive Tutorial

将 `tutorials/<topic>/{manifest.md, lessons/*.md}` 编译为交互式学习站点的引擎技能。

## 流水线总览

```text
lessons/*.md ──parser.py──▶ AST ──linter.py──▶ 绿 ──builder.py──▶ dist/
                                                    │
                                    server.py ◀─────┘ （静态托管 + 沙箱执行 + /api/check）
```

浏览器端永不解析 Markdown：高亮 Token 在构建期预计算，运行时只做交互编排。

## 工作流

### P0 环境探测
探测宿主工具链（go/rustc/gcc/python/node…），能力清单写入教程 manifest；
缺失的语言标记为只读模式，不阻塞其他语言。

### P1 课程解构
用 7-Track 框架拆解目标主题 → [curriculum-design-matrix.md](references/curriculum-design-matrix.md)。
每课一个原子概念，核心叙述 150~250 字，30 秒内可触发首次运行与旋钮交互。
项目暗线贯穿全局，配置实战任务里程碑。
`scripts/new_topic.py` 生成 tutorials/<topic>/ 骨架。

### P2 苏格拉底与费曼式创作
按 DSL 规范写课：[dsl-spec.md](references/dsl-spec.md)。
遵循四大铁律（一课一旋钮、预测-验证闭环、对比出真知、物理锚定与类比失效边界）。
结合 Wave 1 语义块：
- `:::challenge`：实战挑战与 `/api/check` 自动化断言判定；
- `:::spotbug`：费曼老师找茬题；
- `:::reflect`：直觉自述与模型对齐；
- `:::compare`：双栏并排概念对比；
- `panel: tabs[...]` / `panel: visualizer[...]`：右侧多态工作台过程动画。

### P3 编译闭环
`python skills/build-interactive-tutorial/scripts/compile.py <topic>`
四重质检不绿不许过：缩进严谨性 / 可编译探测 / 交互块完备性 / 高亮预编译。
linter 报告是唯一验收依据，禁止肉眼放行。

### P4 交付验证
server.py 拉起本地服务，按 Pre-flight 清单逐项核对（死循环超时、CJK 渲染、
光标对齐、目录树交互）。交付物默认 `dist/{index.html, data.js}`，`--single` 出单文件。

## 物理红线（不可协商）

1. 双层编辑器必须 `font-variant-ligatures: none !important;`
2. 行号容器必须 `white-space: pre !important;`
3. 自动补全严禁劫持 Enter 换行
4. subprocess 一律列表传参，禁 `shell=True`；服务只绑 127.0.0.1
5. 等宽字体栈显式绑定 CJK 回退；注释禁伪斜体；依赖变动必须回写根 requirements.txt

## 目录职责

| 路径 | 内容 |
|---|---|
| assets/compiler/ | parser / linter / builder / highlight（冻结引擎，改前先评审） |
| assets/static/ | Docked Studio 壳 + aquascope SVG 渲染器 |
| assets/server.py | http.server 沙箱服务，127.0.0.1 only |
| references/ | 课程矩阵 / 教学法 / DSL 规范 / 沙箱安全 |
| scripts/ | new_topic.py、compile.py 薄封装 |

里程碑状态与待办见仓库 README 技能表备注列。

From Windy-Dance/PearSkills, Apache-2.0.

More from Windy-Dance/PearSkills