前言¶
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
