优质课精品课磨课工坊
📚 文档地图（先知道去哪查）
| 想知道什么 | 看哪个文件 |
|---|---|
| 八步流程各步产出什么 | 本文「这段磨课之旅能帮你做什么」 |
| 每一步的具体命令怎么敲 | references/pipeline.md（命令级实施手册） |
| 报错、打不开、转录失败怎么办 | references/faq.md（症状→原因→处理 + 错误码表 E01–E12） |
| 环境缺什么、我这台能不能跑 | scripts/doctor.py（一键体检，直接给修复命令） |
| 评判打分怎么算、权重多少 | references/evaluation-matrix.md |
| 各学科核心素养与检索关键词 | references/subject-guides.md |
| 精品课合规要求 | references/jingpinke-guide.md |
| 多来源检索的降级链路 | references/multi-source-search.md |
| 教案四维比对怎么做 | references/plan-compare.md |
> 遇到异常先去 references/faq.md 查错误码，不要凭猜测反复重试。
🔒 启动方式（唯一入口，务必留意）
本技能只通过两个说法启动：「打开磨课平台」或「启动磨课平台」。
- 说这两句 → 技能启动，随后自动建好工作台并用系统浏览器弹出主页，无需手动双击。
- 说其他任何词（如「磨课」「公开课」「优质课」「同课异构」「教案比对」等）→ 一律不启动本技能。
- 这样收窄是为了避免和本机其他教学类技能（备课、阅卷、试卷讲评等）互相抢触发、混淆。
启动后从检索主页填写课题、学段、学科、教材版本即可开工。
这段磨课之旅能帮你做什么
- 多平台检索：B 站自动检索优质公开课视频；微信视频号 / 基础教育精品课 / 国家中小学智慧教育平台走降级链路；另支持从微信、精品课、智慧平台、小红书四来源检索现成教案。
- 逐字稿转写：观看转录（尽量零下载），ASR 人工校正，得到可引用的逐字稿。
- 教案初稿（×3）：每份逐字稿按 10+1 维度解码 → 生成含「课堂步骤还原表」的教案 v1，多份同构可比。
- 多课对比评判：七维加权矩阵横向打分，每条结论附逐字稿时间戳证据，输出「应吸收的设计清单」。
- 推演自有教案：综合各课优点 + 本班学情，产出可落地的自有教案 v1。
- 教案比对（特色）：自有教案 × 网络检索教案，按「教学目标 / 教学重难点 / 教学环节 / 作业设计」四维比对，给出修订建议。
- 修订：名师课例对标修订 + 教师手动回灌，迭代到 v2/v3。
- 课件产出：教案 → PPT 大纲 → 样稿 → 美化；精品课模式可套教育部官方课件模板。
⚡ 启动后必做（第一步）
用户说「打开磨课平台」或「启动磨课平台」后，第一条命令就是建工作台并自动弹出外部系统浏览器——不要先追问课题参数。
标准流程分两步：先建台（前台，不弹窗），再弹外部浏览器（后台任务 + pythonw，看门狗防闪退）。
第 1 步：建台（前台 Bash，--no-open 不弹窗）
# ① 用户已给课题：建好工作台
python "<skills>/youzhi-jingpin-moke-gongfang/scripts/init_workbench.py" \
--subject 语文 --topic 荷塘月色 --stage 初中 --grade 八年级 --textbook 统编版 --no-open
# ② 用户只说了「打开磨课平台」：占位目录 + 建骨架
python "<skills>/youzhi-jingpin-moke-gongfang/scripts/init_workbench.py" --no-open
# ③ 已有目录：只刷新页面
python "<skills>/youzhi-jingpin-moke-gongfang/scripts/init_workbench.py" --workdir "<工作目录>" --no-open
第 2 步：弹外部浏览器（后台任务 + pythonw，关键：防闪退）
必须用后台任务 + pythonw 跑 launch_browser.py，不能用前台 Bash 直接弹——否则浏览器被沙箱清理 → 闪退。
- 为什么后台任务：
launch_browser.py用看门狗模式——启动 Edge 后proc.wait()阻塞守护（不轮询、不调用任何控制台程序），Edge 活着它就活着、Edge 关了它才退出。后台任务跨调用存活，看门狗才能常驻，Edge 就不会被父进程带走。 - 若 Edge 已在运行（用户日常浏览器），脚本直接把主页开进现有窗口，无需看门狗，后台任务立即结束即可。
# pythonw 路径：用 where pythonw 取得，或取与 python 同目录的 pythonw.exe
PYW=$(where pythonw | head -1)
"$PYW" "<skills>/youzhi-jingpin-moke-gongfang/scripts/launch_browser.py" \
"<工作目录>/index.html"
> 以上命令以 run_in_background: true 在 Bash 工具中执行（后台任务，pythonw 无控制台不弹黑窗）。
其他说明
- 每个阶段完成后重跑第 1 步刷新全站，再重跑第 2 步重新弹窗（或刷新现有窗口）。
- 本机直接跑（非 WorkBuddy 沙箱）：直接
python init_workbench.py（不加--no-open），脚本自动弹窗，无需看门狗。 - 无人值守 / 无图形环境（服务器、纯命令行）：跳过第 2 步，把
index.html绝对路径以文件卡片交付。 - 若脚本提示"自动弹出失败"，不要静默放过：把
index.html绝对路径交给用户并说明可手动双击，同时确认是否无图形环境。 - 只想重建页面、由外部自行打开时，仍可直接用
build_workbench.py --workdir <工作目录> [--no-open]。
⚠ 已知坑与维护注意（小黑窗，已根治）
现象：新建任务「打开磨课平台」后，系统不停弹出标题为 C:\WINDOWS\SYSTEM32\task... 的黑色空窗口。
根因：早版 launch_browser.py 看门狗每 3 秒用 subprocess.run(["tasklist", ...]) 轮询检测 Edge 是否在跑。脚本以 pythonw.exe（无控制台父进程）运行，而 tasklist.exe 是控制台子系统程序——没有父控制台时，Windows 会为它强制创建一个可见控制台窗口。轮询一次弹一个，表现为"不停弹小黑窗"。给 tasklist 加 CREATE_NO_WINDOW 在本机仍压不住，edge_preexisting 也依赖它做判断。
根治（v1.0.12，已落地）：launch_browser.py 全程不再调用 tasklist/taskkill 等任何控制台子进程。改为直接 subprocess.Popen([浏览器, index.html]) 拉起 Edge 并拿到 PID，然后 proc.wait() 阻塞守护——Edge 活着脚本就活着、Edge 关了脚本才退出，二者同生命周期，无需轮询。Edge 已在运行时 msedge <url> 把页面转发给现有实例并立即返回，脚本随之退出；Edge 未运行时新进程常驻到用户关闭。热循环里零控制台程序调用，黑窗从根上不可能出现。
维护铁律：在 pythonw / 无控制台上下文里，不要用 tasklist/taskkill/cmd 等控制台程序做轮询或检测；若必须调用，要么加 CREATE_NO_WINDOW，要么（更稳）改用 Popen+proc.wait() / proc.poll() 守护具体进程，彻底绕开控制台程序。
工作台一览
从检索主页填课题一键开工，主页与各步骤页实时呈现进度、产物与下一步操作。
| 页面 | 截图 |
|---|---|
| 检索主页（填参数、选来源） | |
| 主页（八步总览进度） | |
| 01 检索（候选选择，勾选进入对比） | |
| 03 教案v1（视频重选 + 另存/打印） | |
| 04 评判（横向矩阵表 + 每课画像） | |
| 07 修订（产物清单 + 另存/打印） | |
| 08 PPT（课件产出） |
> 截图为演示课题的完整磨课流程（基础教育精品课模式）。
差异化亮点
- 评判可溯源：每条结论绑定逐字稿时间戳 / 教案原文，杜绝「设计合理、建议加强」这类空泛评语。
- 精品课模式：内置 2025 基础教育精品课制作规范与官方课件模板，直接对齐评价指标。
- 全程可接管：每一步都能人工改写回灌，也能直接提交自有教案跳阶段 7 修订，不必从零跑。
适用人群
- 准备公开课 / 优质课 / 名师示范课 / 同课异构的初高中教师（语数英为精校学科，其余 K12 主要学科已全覆盖）
- 做同课异构研究、多课对比、公开课磨课的教研团队
- 需要把优质课例快速沉淀成本校教案与课件的备课者
依赖与环境（先体检，再看清单）
第一次使用前先跑一次体检，它会逐项告诉你缺什么、怎么补：
python "<skills>/youzhi-jingpin-moke-gongfang/scripts/doctor.py"
本技能已内置 5 套下游能力（转录 / 逐字稿解码 / 备课模板 / PPT 生成 / 微信教案检索），
脚本随包分发，不需要另装其他技能。只需准备下表的外部环境：
| 依赖 | 必需性 | 用途 | 安装 |
|---|---|---|---|
| ffmpeg | 必需（走字幕轨时可省） | 抽音轨供转录 | Win winget install Gyan.FFmpeg；Mac brew install ffmpeg |
| faster-whisper | 必需 | 语音转文字 | pip install faster-whisper，或 --venv 指向已有环境 |
| yt-dlp | 推荐 | B 站检索与取流 | pip install -U yt-dlp |
| Node.js | 可选 | 精品课官方模板渲染 | 装 LTS 版即可 |
| browser-skill | 可选 | 需登录态的检索源（视频号 / 精品课 / 智慧平台） | 不装则走「手动贴链接」降级 |
装完依赖重开终端（PATH 才生效），再跑一次 doctor.py 确认无 ❌ 项。
缺依赖时的具体报错与处理见 references/faq.md。
使用方式
- 表单入口：打开工作台检索主页，填写课题、学段、学科、教材版本，选择是否启用教案检索与四来源，一键开工。
- 对话入口：技能已启动后（即已说过「打开磨课平台」/「启动磨课平台」），在对话里对 AI 说「跑磨课工坊：八年级英语人称代词，仁爱版七下，找 3 个视频」，AI 按参数开工。注意：「跑磨课工坊」这句话本身不是触发词，它只在技能已启动后作参数输入使用。
- 启动后第一步（强制）：用户说「打开磨课平台」/「启动磨课平台」后，AI 必须先建工作台。用户未给课题时，用占位目录
磨课工坊_待填课题_<YYYYMMDD>建骨架，让用户在检索主页表单填写；拿到参数后再按<学科>_<课题>_<YYYYMMDD>正式建目录、写_meta.json并重建。 - 弹出方式：WorkBuddy 里触发时，建台用
--no-open，再以后台任务 + pythonw 跑launch_browser.py弹外部浏览器（看门狗防闪退）；本机直跑时脚本自动弹窗。详见「⚡ 启动后必做」。
发布信息
- 技能名：优质课精品课磨课工坊（display_name_en: Quality & Elite-Class Lesson-Refinement Workshop）
- 版本：v1.1.1
- 形态：单技能包（含内置 vendor 脚本、工作台模板、界面截图、参考文档）
