75 lines
3.6 KiB
Markdown
75 lines
3.6 KiB
Markdown
# C-03 · 在线代码运行器（JS+Python，学练一体）
|
||
|
||
| 字段 | 值 |
|
||
|---|---|
|
||
| 项目 | 可乐工具 · `chunyu_project_react`（主体），后端可选 |
|
||
| 优先级 | P0 · M2 |
|
||
| 建议模型 | deepseek-v4.1-flash（主）/ **gpt-5.6-luna（安全审查）** |
|
||
| 依赖 | 无 |
|
||
| 预估 | 3.5 天 |
|
||
|
||
## 一、背景（为什么做）
|
||
|
||
1. 报告结论：学习模块讲编程课程却无处练代码——**课程与工具割裂**；"学完即练"是全竞品都没有的组合（`docs/产品问题分析与改造路线.md` P0-3）。
|
||
2. 竞品：菜鸟工具 24 种语言在线编译、ToolFk 有 Online Code Compiler——但它们都是**独立工具**，没有与课程内容绑定。我们的差异化 = 嵌在章节页里的随堂运行。
|
||
|
||
## 二、目标（交付物）
|
||
|
||
**MVP 技术路线（已拍板）：纯前端沙箱，零服务端执行**
|
||
- JS：`Web Worker` 沙箱执行（`postMessage` 收发，`importScripts` 禁用，超时 `terminate()`）
|
||
- Python：`Pyodide`（WASM，浏览器内运行；懒加载，独立 chunk）
|
||
- **不做服务端执行**（judge0 容器留到 Phase 2 按需评审）——安全与运维成本双低。
|
||
|
||
**组件交付**
|
||
1. `src/components/CodeRunner/`：
|
||
- `CodeRunner.tsx`：编辑器（复用项目现有编辑器风格，如 CodeMirror/Monaco 依项目现状）+ 运行按钮 + 输出面板 + 状态行（运行中/超时/错误）
|
||
- `worker-js.ts`：JS 执行 worker（捕获 console、异常；**硬超时 3s** 后 terminate 并显示"执行超时"）
|
||
- `pyodide-runner.ts`：Pyodide 加载（版本锁定；加载失败降级提示；执行超时同一策略）
|
||
2. 集成到 `CourseLearn.tsx` 章节页：本章节含代码示例时显示"随堂运行"面板（读章节内容里的代码块，一键装载）。
|
||
3. 独立工具入口（可选加分）：`/code-runner` 页面。
|
||
4. 安全设计（交 gpt-5.6-luna 审查）：
|
||
- worker 内无 DOM 访问；主线程无 `eval`/`new Function`
|
||
- Pyodide 网络请求策略（默认断网：不加载额外包）
|
||
- CSP 兼容性说明
|
||
|
||
## 三、执行步骤
|
||
|
||
```text
|
||
1. 侦察项目现有编辑器依赖与 CourseLearn 章节数据结构（代码块字段）
|
||
2. 实现 worker-js + 超时控制（先跑通最小闭环）
|
||
3. 接入 Pyodide（懒加载 + 失败降级）
|
||
4. 集成 CourseLearn 章节页
|
||
5. 安全自查清单逐条过 → 交安全审查模型复核
|
||
6. 构建体积核对（runner chunk 懒加载，不拖累主包）
|
||
```
|
||
|
||
## 四、验收标准
|
||
|
||
- [ ] JS 代码运行并显示输出（console.log、返回值、异常信息）
|
||
- [ ] Python（Pyodide）代码运行并显示输出
|
||
- [ ] **死循环（`while(1){}`）3 秒内终止，页面不冻结、可继续操作**
|
||
- [ ] 章节页"随堂运行"面板可用：装载本章代码 → 运行 → 看输出
|
||
- [ ] 首次加载 Pyodide 有 loading 态；失败有降级提示
|
||
- [ ] runner 相关代码全部懒加载（主包体积不增加 >10KB）
|
||
- [ ] 安全审查清单通过（审查模型签署）
|
||
|
||
## 五、验收命令（参考）
|
||
|
||
```bash
|
||
cd chunyu_project_react && npm run build
|
||
# 检查懒加载 chunk 分离
|
||
ls dist/assets | grep -iE "runner|pyodide"
|
||
# 浏览器手工：死循环用例、异常用例、中文输出用例
|
||
```
|
||
|
||
## 六、边界（不许做）
|
||
|
||
- 不做服务端代码执行（MVP 红线）
|
||
- 不引入重量级 IDE 依赖（不装完整 Monaco + language server；按项目现有编辑器能力办事）
|
||
- 不修改课程数据结构（只读章节内容）
|
||
- 不在 worker 里放开网络能力
|
||
|
||
## 七、交接
|
||
|
||
写 `PROGRESS_C-03.md`（含死循环终止的录屏/截图说明、安全审查结论、构建体积数据）。
|