文档

安装、结构与日常用法

这一页覆盖从装插件到日常学习的完整路径:项目怎么摆、学习台怎么打开、旧目录怎么迁、五个技能各管什么、数据在哪里。

安装与升级

插件要求 DSH ≥ 0.2.1-rc.5、Node 22.19+。装之前确认宿主版本,装完需要重启宿主。

bash
dsh plugin --profile web add dsh-ai-study-kit

需要 DSH ≥ 0.2.1-rc.5、Node 22.19+

装到哪个 profile

DSH 可以有多个 profile,插件装进哪个 profile,学习台就出现在哪个 profile 的侧栏。dsh plugin强制要求 --profile,把它放在 plugin 和add 之间;下面以 GUI 常用的 web 为例,换成你的 profile 名即可:

bash
dsh plugin --profile web add dsh-ai-study-kit

装完在插件管理里确认状态是 active,五项技能(ask-coach / study-coach / study-doctor / study-recap / study-podcast)会一起注册。

从 GitHub 或本地目录安装

也可以直接从仓库装,或指向本机克隆目录。适合跟进未发版的改动:

bash
dsh plugin --profile web add github:jerryjiao/dsh-ai-study-kit
dsh plugin --profile web add <本地克隆目录>

升级

没有单独的 update 子命令:重新执行一次安装命令即可,必要时在包名后加版本号锁定版本,然后重启宿主。升级插件不会动你的学习项目。

项目结构

学习项目是一个普通目录,只要三样东西:examples/、progress.json、study/。插件不要求你在某个固定位置建它。

目录结构
my-study/
├─ examples/
│  └─ git-basics/
│     ├─ questions.json
│     ├─ flashcards.json
│     ├─ plan.json
│     └─ theme-config.json
├─ progress.json
└─ study/
   └─ records/

examples/<theme>/ 里的文件

文件作用
questions.json题目、选项、正确答案与解析;答题页按题目 id 判分。
flashcards.json闪卡正反面;间隔重复的排期记在 progress.json,不写回这里。
plan.json学习计划:单元顺序、目标与 deadline,首页和教练都读它。
theme-config.json主题名称、显示配置等元信息。

MISSION.md 与 lessons/ 可选:有的话会出现在学习台和陪练里,没有也不影响答题和闪卡。

项目根不等于插件自带的 kit/

插件安装目录里的 kit/ 是技能读取的快照与参考资料,不是你的学习项目。别把progress.json 写进去,也别在里面改题目——升级插件时它会跟着包一起更新。你的项目放在任意目录,插件只读写你选中的那一个。

打开学习台

  1. 重启宿主后,侧栏出现「学习台」图标,点开即是首页。
  2. 面板右上角有项目下拉,可以填路径或从最近用过的项目里选。
  3. 项目下拉指向哪个目录,页面就读写哪个目录;换项目就是换一个路径。

没手动选过项目时,插件按这个顺序找:

  1. 上次用的项目;
  2. 当前启动目录(在哪个目录启动 DSH,就试哪个目录);
  3. ~/study-kit。

三个都没命中时,面板会提示你选目录。选过之后会记住,下次直接用。

旧布局迁移

旧版把内容放在 kit/apps/quiz-app/examples/ 这类目录里。插件会识别kit/apps/quiz-app、kit、apps/quiz-app 这几种旧结构,并提示你迁移,不会直接改动旧目录。

迁移按四步走,每一步都可停下:

  1. 备份整个旧目录(复制一份,或先提交到你自己的 git)。
  2. 把 examples/<theme>/ 与 progress.json 复制到新项目根。
  3. 校验:题目与答案条数对得上、已答记录还在、学习台能打开同一套题。
  4. 确认无误后,才删除旧目录。

迁移不改题目 id,已答记录和闪卡排期都能继续用。拿不准就先只备份、不删除——旧目录留着不影响新项目。

五个技能怎么用

技能都在会话里调用:敲斜杠命令,或者直接用自然语言说你要做什么。区别只是前者更明确,后者更随意。

/ask-coach 学习教练(主入口)

不知道下一步做什么时找它。它会先扫一遍进度、错题、到期闪卡和考期,报一份学习状态快照,再给出现在最该做的一件事和理由,最后带你执行。

会话
/ask-coach 我要学 git

/study-coach 陪练

坐下就学:开场报今天最该练什么,一段一段讲,讲完当场考;考不过就退回去补,不往下赶。

会话
/study-coach 继续学习

/study-doctor 体检

把题库、内容对齐、环境配置一起查一遍。有红项会按修复顺序列出来,告诉你先修哪个、为什么。

会话
/study-doctor 体检

/study-recap 错题串讲

把错题从「知道答案」讲到「知道为什么错」,串完交回给你重做。错题攒到三题以上时,教练通常会主动建议做一次。

会话
/study-recap 错题串讲

/study-podcast 播客

把没掌握的课或错题串讲合成双人播客,通勤路上听。生成播客要调用模型,这一步需要网络和你的模型配置。

会话
/study-podcast 通勤听

学习者只需要这五个命令。像装依赖、跑构建、复制文件这类工具链操作由技能在内部完成,不需要你记。

数据与备份

progress.json 是纯文本 JSON,按题目 id 记录学习状态。主要字段:

字段内容
answers每道题的作答记录:选了哪些、是否答对、作答时间。
srs闪卡复习排期:每张卡的下次到期时间与评级历史。
read已读课程或章节的记录。
settings偏好:每日新卡上限、自动前进、界面语言等。

还有少量元信息,例如上次使用的主题。写入采用「读—合并—写临时文件—重命名」,写到一半中断不会留下半个文件;文件损坏时插件会拒绝覆盖并报错,不会悄悄清空。

备份

拷走整个项目根即可,最少只要 examples/ 和progress.json。study/里是学习记录,想留也一起拷。把项目根放进你自己的 git 也可以;进度是运行数据,按需 ignore。

换机器

在新机器装插件、拷入项目根、打开学习台选中目录,进度就回来了。没有要登录的账号,也没有要恢复的云端数据。

隐私

  • 学习台页面与插件宿主只在本机回环上通信,不监听局域网或公网。
  • 没有账号、没有遥测、没有云同步;插件不向任何服务端上传你的学习数据。
  • 只读写你选定的那个项目目录,不扫描其他目录,不碰你的笔记和别的仓库。
  • 只有生成题目、产课、做播客这类需要模型的动作会走网络,用的是你自己配置的模型。
  • 官网与文档里的截图全部来自虚构的示例项目,不含真实用户数据。

故障排查

侧栏没有学习台图标

多半是装错了 profile,或者装完没重启宿主。先在插件管理里确认插件在你要用的那个 profile 下、状态是 active,再重启 DSH。

面板提示没找到项目

在右上角项目下拉里选一个目录,确认里面有 examples/<theme>/。探测顺序(上次项目 → 启动目录 →~/study-kit)没命中时,手动选一次就会记住。

进度不保存

先看项目目录是不是只读、当前用户有没有写权限;再确认 progress.json没有被别的程序占用。如果文件 JSON 损坏,宿主会报错并拒绝覆盖——修好它,或从备份恢复。

页面空白或提示构建产物缺失

从源码安装时插件包需要先构建:在插件仓库里跑 npm run build,再重新安装或重启宿主。