前言¶
DSH 的插件體系是「一切皆插件」，前端面板、服務端接口、模型工具都能由社區插件擴展。但多數插件解決的是工作流問題，少有把「沉浸式英語學習」搬進來的：在瀏覽器裏看 YouTube，劃詞查詞，攢成生詞本，再按間隔重複複習。
dsh-english-study 就是把這條鏈路塞進 DSH 的一個插件。它由 woshijing1991-cloud 維護，MIT 許可證，當前版本 0.1.0。定位是：面板掛在 DSH 左側圖標欄，配套一個本地 Python 網關，視頻、字幕、查詞記錄、生詞本全部落在本機 SQLite 裏，不連遠端服務、不做雲同步。
下面介紹它的功能、安裝方式、配置項和典型用法。
一、整體架構¶
插件由兩部分組成：一個 DSH 前端面板，加一個 Python 網關。面板負責渲染儀表盤、YouTube 列表、生詞本、複習隊列、詞典和報表；網關是純標準庫 Python（默認監聽 127.0.0.1:8788），所有數據寫入本地 data/*.db。數據流如下：
YouTube 頁面（Edge/Chrome + 瀏覽器擴展） ──點擊單詞──▶ 網關 127.0.0.1:8788 ──▶ data/*.db
DSH 面板（lib/client.js） ──同源──▶ /dsh-english-study/api/* ──▶ 網關 ──▶ data/*.db
有一個設計細節值得說明：面板不做跨域直連網關，而是通過插件把 /dsh-english-study/api/* 代理到上游 URL。這樣做的好處是避開 CORS 和混合內容問題，換端口時也只需要改一處配置。
二、核心功能¶
面板內可完成的主要能力：
- YouTube 播放：按話題聚合的首頁 feed、支持翻頁的真實搜索、官方
/embed/播放器（不下載視頻）、可點擊的字幕。視頻本身從不落盤。 - 點擊查詞：字幕裏的任意單詞都可以點，瀏覽器擴展會把單詞連同所在句子發給本地網關。
- 語境解釋：可選 AI 能力，接入任意 OpenAI 兼容的
/chat/completions端點。不配置時，面板只查本地詞典，完全不髮網絡請求。 - 生詞本 + SM-2：
again / good / easy三檔評分，按 SM-2 算法維護 ease factor、interval、lapses，待複習隊列帶角標計數。 - 沉浸統計：按天的觀看秒數、查詞次數、不同單詞數、連續天數。
- 報表與導出：網關提供的本地 HTML 頁面，支持 CSV 導出。
- 聽寫與句子收集：對已保存的詞做聽寫練習，保留喜歡的句子。
- 只讀模型工具：暴露
english_study，子方法stats/dict/due，讓智能體能回答「我今天該複習什麼」。
三、安裝與啓用¶
1. 把插件放進 DSH profile¶
先把倉庫克隆或拷貝到磁盤任意位置，例如 /opt/dsh-english-study，Windows 下用 D:/plugins/dsh-english-study。然後編輯 profile 的 package.json，默認路徑是 ~/.dsh/profiles/desktop/package.json：
{
"dependencies": {
"dsh-english-study": "file:/absolute/path/to/dsh-english-study"
},
"dsh": {
"profile": {
"bundles": [
// ...existing entries...
"dsh-english-study"
]
}
}
}
這裏的關鍵是：包聲明瞭 dsh.bundle.patch（cordis.patch.yml），所以只要列進 bundles，安裝器就會自動插入加載條目。不要再在自己的 profile 的 cordis.patch.yml 裏給這個插件加 insert 塊，重複的 loader id 會導致啓動檢查失敗。只有當 DSH 構建不支持 layered bundled patches 時，才改爲在那裏手寫 insert。
保存後讓 DSH 下次啓動時裝依賴，或手動跑 profile 的包管理器安裝。需要注意 file: 依賴是複製進 node_modules 而不是軟鏈，改完插件源碼要重新安裝或重新拷貝，否則跑的仍是舊副本。
2. 啓動本地網關¶
cd dsh-english-study/gateway
python server.py # 監聽 0.0.0.0:8788
沒有 pip install，也不需要數據庫遷移，data/english-study.db 首次運行自動創建。
Windows 下可以直接雙擊 start-gateway.cmd，錯誤信息會留在窗口裏；插件在網關未運行時也會自動拉起，除非 ES_GATEWAY_DIR 指向了別處。自動拉起的行爲分平臺：
- Windows：運行
start-gateway-hidden.cmd，腳本自己會設好ES_API/ES_MODEL。 - macOS / Linux：直接跑
python3 gateway/server.py，解釋器可用ES_PYTHON覆蓋。因爲繼承的是當前 shell 的環境，想讓 AI 生效就需要先導出ES_API/ES_MODEL/ES_KEY。
網關沒有任何鑑權，設計上就是給本機用的。除非確實想讓同一 Wi-Fi 下的手機訪問，否則把 ES_HOST 設成 127.0.0.1，並且不要把 8788 端口暴露到公網——不做端口轉發、不加公開反向代理。
3. 重啓 DSH 並驗證¶
宿主側代碼和 slot 註冊在啓動時收集，重啓 DSH、刷新界面後，左側圖標欄會出現 “English Study” 圖標。用兩個 curl 驗證：
# 1) 網關是否應答
curl -s http://127.0.0.1:8788/api/health
# {"ok":true,"ai":false,"model":"","local_only":true,"port":8788,"dict":false,...}
# 2) 插件路由是否掛到 DSH GUI 上
GUI_PORT=8045 # 換成你 DSH 設置裏顯示的端口
curl -s "http://127.0.0.1:${GUI_PORT}/dsh-english-study/api/client-ping"
# {"ok":true,"plugin":"dsh-english-study"}
返回裏 "ai":false 和 "local_only":true 是默認狀態，不是報錯；"dict":false 只說明還沒建詞典。
四、配置項¶
配置全部走環境變量或插件配置字段。核心功能不需要任何配置，默認值就能離線工作：
| 配置 | 環境變量 | 默認值 | 作用 |
|---|---|---|---|
| 網關端口 | ES_PORT |
8788 |
網關監聽端口，改動需同時同步插件側 gateway 配置 |
| 綁定地址 | ES_HOST |
0.0.0.0 |
0.0.0.0 允許同 Wi-Fi 設備訪問，127.0.0.1 僅限本機 |
| 網關目錄 | ES_GATEWAY_DIR |
插件自身目錄 | start-gateway*.cmd 所在位置，供自動拉起使用 |
| 上游 URL | ES_GATEWAY 或插件配置 gateway |
http://127.0.0.1:8788 |
插件把 /dsh-english-study/api/* 代理到哪裏 |
| AI 端點 | ES_API |
空 | OpenAI 兼容的 /chat/completions URL，空表示只用本地詞典 |
| AI 模型 | ES_MODEL |
空 | 發往端點的模型名，例如 deepseek-chat |
| AI key | ES_KEY（或 DEEPSEEK_API_KEY） |
空 | 只從環境讀，絕不寫盤 |
| Python 解釋器 | ES_PYTHON |
python / python3 |
.cmd 啓動器和 macOS/Linux 自動拉起使用；PATH 裏沒有時填完整路徑 |
| 基礎路徑 | 插件配置 basePath |
/dsh-english-study |
同源路由前綴 |
| 默認標籤頁 | 插件配置 defaultTab |
dashboard |
面板首個打開的標籤 |
| YouTube 代理 | ES_PROXY |
空（直連） | 例如 http://127.0.0.1:7890 |
除上表之外，README 還要求兩個外部環境條件：字幕功能依賴 PATH 上的 yt-dlp 且必須是較新版本——2024 年的舊版會報 Precondition check failed 或 No video formats found，apt 源裝的版本往往無法自更新，建議直接下 GitHub release 二進制。不做瀏覽的話不需要管它，面板照常運行，只是沒有可點擊字幕。另外，YouTube 首頁和搜索列表要有內容，需要提供 YT_INNERTUBE_KEY（YouTube web-client key），否則這兩個列表爲空，其餘功能不受影響。
五、典型用法¶
最輕量的用法：只配本地網關、不接 AI。經過上面的步驟啓動後，面板裏點 YouTube 視頻，點字幕單詞，查到的詞連同句子進入生詞本，之後在複習隊列裏按 認識 / 不認識 逐張過卡，評分驅動 SM-2 排期。攢幾天後，儀表盤上出現每日觀看秒數、查詞數、不同詞數、連續天數和最常查的詞。
想讓 Agent 參與複習安排，則在 DSH 側調用只讀工具 english_study。它有三個子方法：stats 給統計，dict 給本地詞典查詢，due 給當日待複習隊列。藉助 due，Agent 可以直接回答「今天我該複習哪些詞」，這也是這個插件和工作流結合的入口。
如果想讓每段字幕都帶 AI 語境解釋，就設置 ES_API / ES_MODEL / ES_KEY。不設的話不會請求任何網絡，行爲退化爲純本地詞典。
六、適用場景與注意¶
適合這幾類人：
- 想在 DSH 一個界面裏完成「看視頻 → 查詞 → 複習 → 統計」閉環，不想裝獨立生詞軟件的用戶；
- 在意數據歸屬，希望查詞記錄和生詞本完全留在本機，不經任何雲同步的用戶；
- 希望 Agent 能基於本地學習數據回答問題，而不是把內容丟給大模型的開發者。
需要注意的幾點：
- 插件以當前 DSH 進程的權限運行。它在你本機監聽端口、讀寫本地 SQLite、在你瀏覽器裏注入擴展，安裝前仍應通讀源碼，確認行爲與許可證（MIT）符合預期。
- 網關沒有鑑權。
ES_HOST保持127.0.0.1，不要暴露 8788 端口。 - 完整功能依賴 Windows 10/11（Edge 自動啓動、cookie 提取），網關本身跨平臺。macOS/Linux 上 AI 需要靠環境變量自行注入。
file:依賴是拷貝語義，改插件源碼後要重裝，否則跑的是舊副本。- 沒有
yt-dlp就沒有可點擊字幕；沒有YT_INNERTUBE_KEY，首頁和搜索列表爲空。這兩項不影響本地學習鏈路，但會影響視頻體驗。
七、結尾¶
dsh-english-study 的價值在於把「看 YouTube 學英語」這條鏈路完整搬進 DSH：點擊查詞、SM-2 複習、沉浸統計、CSV 導出都在本地完成，AI 解釋是可選增強而不是必需依賴。它和 DSH「一切皆插件」的思路一致，適合想要一個自託管學習面板的人。
- 社區目錄頁：https://www.skillhub.cn/plugins/woshijing1991-cloud/dsh-english-study
- GitHub：https://github.com/woshijing1991-cloud/dsh-english-study
