StudyMate 是 Miaotofu01/Study-Mate 里的数学/计算机学习工作流，站点信任档位「已验证」（L4 · 真实安装，本站已在 dsh 0.2.0-rc.2 下装成功），星标 560、综合分 67.7、周下载 1,425。装是装得上——「✓ 可直接安装」，但装得上不等于一次装顺。下面这五个地方最容易栽，按编号来。
坑一 · 缺 PyYAML 装不上
现象：npx -y @yunmiao/studymate@latest install 跑到依赖检查时报缺 PyYAML，命令中断。
原因：Python 不自带 PyYAML，而安装器只检测、不代装。它会在终端打印一条 pip 命令，很多人以为已自动装好，直接往下走。
解决：在系统终端里用安装器检测到的同一个解释器执行它给出的 pip 命令；完成后保留参数重跑原 npx 命令。看到 >>> 或提示缺少 pip 时按依赖安装说明处理。顺带把 jsonschema 也装上——完整课件校验需要它，缺了会跳过 schema 校验，你以为通过了，其实少了一道。
坑二 · Node 版本区间把 23.x 排除在外
现象：npm 报 EBADENGINE，装到一半被引擎检查拦下。
原因：engines.node 是 ^22.19.0 || >=24.0.0——这个区间不含 23.x。Node 23 上版本号看着新，反而不在支持范围内。
解决：切到 22.19+ 或 24+ 再装。这不是插件的 bug，是约束写死的区间，改 Node 版本比改插件现实。
坑三 · 站点说「未声明 dsh 版本约束」，README 却要求 0.1.5-rc.2+
现象：在老版本 DSH 上装完，重启、新建会话，看不到「学习模式」预设。
原因：这处差异要如实讲——package.json 里确实没有写 dsh 版本约束，所以本站「安装兼容性检查」只能报「未声明 dsh 版本约束」，这是静态检查的能力边界，不等于没要求；真实地板写在 README，要求 DSH 0.1.5-rc.2+。只信站点那一行就会踩进来。
解决：装插件前先把引擎升上去，npm install -g @deepseek-ai/dsh@latest，再跑安装命令。引用版本要求时也以 README 为准，并注明站点检查口径。
坑四 · 装完不重启等于没装
现象：安装器显示成功，新建会话却找不到「学习模式」。
原因：预设注册要在 DSH 启动时读取，当前进程不会热加载。两条路的档位还不同：桌面端用 desktop 档位，官方 CLI 默认注册到 web 档位——你重启的那个 DSH，得和安装到的档位是同一个。
解决：桌面端完全退出再重新打开（退出进程，不是关窗口）；CLI 则重启并新建会话。重启后新建会话时，模式里才会出现「学习模式」。
坑五 · 会话没开在学习工作区
现象：学了几节课，打开 ~/StudyMate 里却什么都没有。
原因：会话没开在学习工作区时，课程不会直接建在工作区，而是先建在会话目录下的 .studymate-stage/<slug>（全程零授权），结束时总控才问你放哪、然后一次 cp -a 搬过去。如果提前结束会话、或搬迁目的地选错了，数据就留在 stage 里，看起来"没学过"。
解决：会话直接开在 ~/StudyMate（权限选 workspace-write 或 danger-full-access），课程就地建，零授权也最省心。真要开在别处（比如某个代码仓），结束时把总控问的那个目的地选对——学习工作区／桌面／文档文件夹／用户根目录／先留着，别随手跳过。学习工作区默认在 ~/StudyMate，所有课件与记忆都存放在工作区。
想少踩一个坑就对照一遍清单
上面五处，前四处能在安装阶段解决，第五处是使用习惯。装之前建议先翻一遍 完整插件清单与汉化避坑指南，看看同类插件的中文清单与安装形态，再决定从哪条路装——桌面端与官方 CLI 的档位差别，对后面排查影响很大。另外站点详情页有句提醒值得照做：dsh 与插件都处于 developer-preview 阶段，装任何插件前建议先备份 ~/.dsh 配置，出问题好回滚。
顺带一提：这些不算坑，但同样会踩空
-
直接打开
templates/里的 HTML 没样式：这是设计如此，模板引用的是生成后的工作区相对路径。主页要从学习数据生成，跑python3 scripts/gen_home.py，再看<workspace>/index.html（还没科目时是空状态页）。 -
手改大纲 YAML 后节点指针错：改 YAML 大纲节点前先想清楚代价。
-
换机没搬数据：学习数据默认在独立的
~/StudyMate，不在 DSH 目录里，换机器要自己搬。 -
多宿主三套安装方式：DSH 预设走
npx那条；Codex / ChatGPT Work 要下载studymate-openai.zip手动导入；Antigravity 是node bin/studymate.mjs build-antigravity --install。走错入口，装不上不是插件的问题。
总结
五个坑的共同点：前置依赖、版本区间、引擎地板、重启时机、会话位置——全在"装之前"和"装之后一分钟"里；想对照同类插件的中文清单与安装形态见 完整插件清单与汉化避坑指南。
适合与不适合
适合：已装过一次、被 PyYAML 或版本区间卡住想找原因的人；在用 DSH 官方 CLI 或桌面端、需要确认档位与重启姿势的人；准备长期跟这门课、在意学习数据落在哪的人。 不适合：不愿在系统终端手动装 Python 依赖的人；Node 停在 23.x 且不改的人；期待"装完就自动出现学习模式、不用重启"的人；还有——如果你只想要一次问答式答疑、根本不需要路线图与课件，这些坑你其实没必要趟，用普通对话更直接。
标签：StudyMate、DeepSeek Harness、避坑指南、插件安装、PyYAML
本文由 DeepSeek Harness Hub 自动整理，数据来源于插件详情页。
