前言¶
課堂場景裏，錄音容易，錄音之後的整理難。一段一小時的課，手動整理成總結、思維導圖、練習題，代價很高；直接丟給通用 Agent，又缺少「這節課講了什麼、錯題有沒有改完」這類上下文。dsh-classroom-mobile 針對的就是這一步：手機瀏覽器錄音，本機 Whisper 轉寫，再由 DSH Agent 生成總結、導圖和練習題，並用一個錯題門控把複習閉合掉。
先說清楚它是什麼：一個 DSH / cordis 插件，由 chengyu-xin1 維護，分類是工作流，當前 0 星。它不打包 APK，也不做原生 App。它的思路是 PC 端起一個 HTTP 服務，手機瀏覽器訪問它。
這是什麼¶
一句話定位：在 DSH 里加一個「課堂學習」工作流，覆蓋錄音、轉寫、總結、複習、專注報告這一整條鏈路。
它解決的是三個具體問題：
- 錄音之後沒有結構化的整理產物；
- 複習沒有約束，錯題改不改完都一樣能繼續錄音；
- 手機沒有 DSH 的移動端，需要一個在手機瀏覽器裏能用的入口。
README 裏明確寫了邊界，值得先記住：DSH 是桌面應用、沒有移動端；手機端等於手機瀏覽器訪問 PC 上本插件啓動的服務。專注功能只做檢測、記錄、報告，不會鎖定手機或強制專注。插件零 npm 依賴，只用 node 內置模塊，轉寫調用本機的 ffmpeg 和 python。
安裝與啓用¶
從 DSH 插件市場安裝，審覈通過後在命令行執行：
dsh plugin --profile desktop add github:chengyu-xin1/dsh-classroom-mobile
手動安裝適合本機開發或離線環境。先把整個目錄放到 D:\dsh-classroom-mobile，再複製到 DSH profile 的插件目錄：
Copy-Item -Recurse -Force "D:\dsh-classroom-mobile" `
"$env:USERPROFILE\.dsh\profiles\desktop\node_modules\dsh-classroom-mobile"
然後把包名加進 profile 的 package.json 的 dsh.profile.bundles 數組末尾，加 "dsh-classroom-mobile"。最後重啓 DSH。插件 apply() 會自動在 0.0.0.0:8765 起服務，端口被佔用時從 8766 起遞增。
換電腦或給別人裝，先跑環境準備腳本：
powershell -ExecutionPolicy Bypass -File scripts\setup.ps1
它依次檢查並準備 Node、Python、ffmpeg，安裝 faster-whisper（清華源），下載 Whisper small 模型（約 460 MB），下載 cloudflared。任何一步失敗都不會影響插件可用，只是對應能力缺失：沒有 faster-whisper 就手動粘貼文字，沒有 cloudflared 就只用局域網。可以用 -SkipModel、-SkipCloudflared 跳過下載。
手機訪問：公網隧道與局域網¶
插件啓動時用 cloudflared 建一條臨時 HTTPS 隧道，手機用流量或在別的 Wi-Fi 下都能打開：
https://xxxx-xxxx-xxxx.trycloudflare.com
HTTPS 還解決了手機瀏覽器「非安全上下文不能調用麥克風」的限制。cloudflared.exe 約 53 MB，倉庫不打包，插件第一次啓動會自動下載到 data\bin\cloudflared.exe，優先走 ghfast 鏡像；下載失敗時頁面照常可用，只是沒有公網地址。也可以手動放一份：
New-Item -ItemType Directory -Force D:\dsh-classroom-mobile\data\bin | Out-Null
Invoke-WebRequest -Uri https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-windows-amd64.exe `
-OutFile D:\dsh-classroom-mobile\data\bin\cloudflared.exe
非本機訪問需要 6 位訪問碼，存在 data\access.json。首次打開手機端會彈輸入框，也可以直接在 DSH 裏問「手機訪問碼是多少」。quick tunnel 每次重啓 DSH 可能換地址，隨時問「手機訪問地址」即可，工具 classroom_mobile_url 返回最新地址加訪問碼。關閉隧道用環境變量 DSH_CLASSROOM_MOBILE_TUNNEL=0，重啓後只用局域網。
如果隧道沒起來，電腦和手機連同一個 Wi-Fi 時可以用局域網地址：
http://<電腦局域網 IP>:8765
注意局域網 HTTP 下部分手機瀏覽器會拒絕錄音（非安全上下文），此時優先用公網 HTTPS 地址。所有業務數據只寫 D:\dsh-classroom-mobile\data，不上傳雲端。
錄音轉寫與課後整理流程¶
使用流程按順序是：
- 手機打開頁面，在「錄音」頁填課程標題，點「開始上課」。瀏覽器請求麥克風權限；錄音過程中每 30 秒自動切一個分片上傳，服務端逐片轉寫。
- 錄音頁字幕區每 3 秒刷新最近 5 段轉寫。轉寫引擎未就緒時頁面提示「轉寫引擎未就緒，可手動粘貼文字」，並給粘貼框兜底，音頻仍然照常保存。
- 點「結束並整理」停止錄音，結束專注計時。
- 在 DSH 對話框裏說「生成這節課的總結和導圖」，Agent 調用
classroom_mobile_digest，生成 5 條帶時間戳要點、mermaid 思維導圖、3 條知識拓展、5 道由易到難的題並寫入題目文件。 - 手機切到「總結 / 導圖 / 複習」頁刷新即可看到。
- 複習頁作答後，在 DSH 裏讓 Agent 批改（
classroom_mobile_grade）。未改正的錯題大於 0 時，手機端不允許開始新錄音，服務端也會返回 409。 - 課後在 DSH 裏說「結束專注/看看專注報告」，
classroom_mobile_focus輸出總時長、切走次數與累計離開時長、最長連續專注、番茄數。
轉寫引擎按順序降級。先安裝依賴：
python -m pip install faster-whisper
校園網建議加清華源。首次轉寫會把 small 模型（int8，約 460 MB）下載到 data\models，腳本默認走 HF_ENDPOINT=https://hf-mirror.com。pip 安裝失敗、模型下載失敗、python/ffmpeg 不可用時，音頻照存，transcript.md 寫入「[此段待轉寫]」，/api/state 返回 asrAvailable=false。任何情況下都不會僞造轉寫文字。
HTTP 接口與數據目錄¶
插件自帶一組 HTTP 接口，手機頁面就是它的客戶端：
| 方法 | 路徑 | 說明 |
|---|---|---|
| GET | / |
單文件手機頁面（內嵌 CSS/JS，中文，四頁籤） |
| GET | /api/state |
當前會話、錄音時長、待改正錯題數、ASR 狀態、端口 |
| POST | /api/session/start |
{title} 新建會話；有未改正錯題時 409 |
| POST | /api/audio |
二進制音頻分片，落盤後異步轉寫 |
| GET | /api/live |
最近 5 段轉寫（頁面 3 秒輪詢） |
| GET | /api/summary |
summary.md / mindmap.md 內容 |
| POST | /api/quiz/answer |
{index, answer} 手機端作答 |
| GET | /api/quiz/pending |
未改正錯題（同題以最新一條爲準，correct=true 出隊） |
| GET | /api/quiz/questions |
題目列表與作答狀態 |
| POST | /api/focus/event |
{type: start\|leave\|return\|stop} 專注事件 |
| POST | /api/transcript/manual |
{text} ASR 不可用時手動補錄 |
數據目錄結構固定：
D:\dsh-classroom-mobile\data\
current.json # 當前會話指針
models\ # faster-whisper 模型緩存
sessions\<yyyy-mm-dd>-<標題>\
meta.json # 錄音起止時間、分片狀態
audio\chunk-000.webm ... # 原始錄音分片
transcript.md # 增量轉寫，每段 "[mm:ss] 文本"
summary.md # Agent 生成的總結
mindmap.md # Agent 生成的 mermaid 思維導圖
quiz.jsonl # 出題 / 作答 / 批改記錄
focus.jsonl # 專注事件（start/leave/return/stop）
想不起 DSH 也能驗服務時，用內置腳本：
node --check src\index.js
node scripts\dev-server.js # 不起 DSH，直接起服務
node test\e2e.mjs # 端到端：上傳→轉寫→總結→錯題門控→專注報告
test\e2e.mjs 會往真實數據目錄寫一個「自動驗收測試」會話，運行結束會清理。
適用場景與注意¶
適合想在課堂裏用上 DSH，並且願意自己搭錄音轉寫鏈路的開發者或研究者：錄一節課，課後自動拿到總結、導圖、練習題和專注報告，複習閉環由錯題門控強制。
需要留意的地方：
- 插件以當前 DSH 進程權限運行，安裝前應檢查源碼與許可證（MIT），不要在未審閱的情況下直接裝到生產環境。
- 服務只在局域網內使用，沒有登錄鑑權，不要把端口暴露到公網；隧道地址有訪問碼兜底，但不要公開發布。
- 全屏 API 在手機上常被拒絕，失敗會靜默忽略，不影響錄音。
- 瀏覽器切後臺可能被系統暫停錄音，項目只記錄
visibilitychange，不保證後臺錄音連續。 - 真機（iOS Safari / 安卓 Chrome / 微信內置）的錄音編碼和後臺行爲未被自動化測試覆蓋，需要真機驗證。
- 專注報告只反映頁面可見性變化，不能證明「沒有分心」，也不是防沉迷工具。
結尾¶
這個插件的價值不在錄音本身，而在把「錄完」到「複習完」之間的鏈路打通：本地轉寫不經過第三方，總結和導圖交給 DSH Agent，錯題沒改完就不允許開始下一節課的錄音。對做課堂場景的人來看，這是一個可以直接組裝進 DSH 的工作流。目錄頁在 https://www.skillhub.cn/plugins/chengyu-xin1/dsh-classroom-mobile ，源碼在 https://github.com/chengyu-xin1/dsh-classroom-mobile 。
