dsh-quiz-tutorial
xiaobin118/dsh-quiz-tutorial
A study surface for exam prep: decks generated from review context, each question with a hand-worked solution, an automatic mistake log with redo/review, `/skill` deck generation, and delete/hide for decks. 15 bundled CNN and ML concept questions.
설치
dsh plugin --profile web add github:xiaobin118/dsh-quiz-tutorialREADME
dsh-quiz-tutorial · 刷题场
English · 中文
一个 DeepSeek Harness(dsh)插件:把任意复习内容变成题集,在 Web UI 里逐题练习——
题目在左,逐步手算解析在右,答错的题自动进错题本,并支持用 /skill dsh-quiz 直接让
Agent 出题。
用 /skill dsh-quiz 生成的「K-means 与 GMM 专项」题集;右侧是逐题手算解析。
功能
- 题集:左侧列表切换;内置 CNN / 机器学习概念题,也可以按任意学科生成新题集。
- 题目 + 解析:矩阵输入、2–6 个选项;作答后右侧展开正确答案、用到的公式、 带中间矩阵的逐步手算、易错点、每个错误选项的诊断。
- 公式渲染:题面/解析/速查卡由 DSH 的 KaTeX Markdown 渲染器显示——用
$...$/$$...$$写 LaTeX(\frac、\sum、\mu_k、\hat{x}、\sigma^2、bmatrix等);不执行 HTML, 远程图片/链接会被丢弃,旧题集里的 Unicode 数学会自动转成 LaTeX 兼容显示。 - 错题本:答错自动收录(跨题集),支持筛选、看解析、重做、标记已订正、 「重练全部未订正」队列;答对自动订正。
/skill dsh-quiz出题:在输入框输入/skill dsh-quiz 主题,Agent 会查重、 自己把答案和中间量算对,再保存成题集。- 删除 / 隐藏题集:自建题集卡片右上角 × 真正删除(同时清掉该题集在本地的作答与错题 记录);内置题集 × 隐藏,列表底部可恢复。
- 本地优先:题集与作答/错题记录都在本机(题集在
~/.dsh/dsh-quiz/decks/,进度在 localStorage),没有账号、没有遥测。 - 键盘
A–F/1–6选答案,←/→切题;深/浅色主题跟随宿主 token。
安装
需要 dsh web(0.2.0-rc.2 或更新;1.0.1 起两条 Web 路由复用 dsh 的 connection
信任栅栏,因此要求 Host 提供该服务)。包已发布到 npm:
dsh plugin --profile web add dsh-quiz-tutorial
备选安装方式(npm 不可用时从 GitHub 装同一个包):
dsh plugin --profile web add github:xiaobin118/dsh-quiz-tutorial
如果装过早期的开发 bundle
dsh-quiz,先移除它(dsh plugin --profile web remove dsh-quiz), 避免两个 bundle 注册同一个quiz面板。
装好后重启一次 dsh web(Host 侧的路由与技能不会热加载),刷新浏览器页面。
打开左侧栏的 刷题场。
如果是从仓库本地开发安装(
plugin_manager install_bundle/ 旧dsh-quiz包), 先移除旧 bundle 再装这个包,避免两个 bundle 注册同一个quiz面板。
用 /skill 出题
在对话输入框里:
/skill dsh-quiz 自编码器与 VAE
技能会要求 Agent:
- 先
quiz_list_decks查重; - 设计 5–10 题,自己算对每道题的答案和全部中间量;
- 用
quiz_save_deck保存完整题集 JSON; - 提示你打开刷题场、点「刷新题集」。
/skill dsh-quiz 生成题集后,Agent 回报题表;打开刷题场刷新即可练习。
也可以直接对 Agent 说「用 quiz_save_deck 按刚才复习的内容出一套题」。
错题本
- 答错的题自动收录,记录错误次数、最近出错时间、上次错选项;
- 筛选「未订正 / 已订正 / 全部」;每题可 看解析 / 重做 / 标记已掌握 / 移出;
- 重练全部未订正按最近出错顺序生成队列,答对自动标已订正,答错留在错题本;
- 「清空已订正」二次确认。
删除 / 隐藏题集
鼠标移到左侧题集卡片上,右上角出现 ×:
- 自建题集:真正删除
~/.dsh/dsh-quiz/decks/<id>.json,不可恢复;删除成功后该题集的 作答、错题记录和隐藏标记会一起清掉,不会污染之后同 id 的题集(包括恢复出来的内置版本); - 内置题集:从列表隐藏,安装包里的文件不动;列表底部「恢复隐藏的题集(N)」恢复;
- 所有题集都隐藏时,主区域会显示恢复按钮;
- 隐藏只作用于内置题集;从错题本点「看解析 / 重做」会自动把对应的隐藏题集恢复显示, 保证打开的是这道题所属的题集。
题集格式
题集是纯 JSON:id / title / subject / description / notes / questions,每道题包含
prompt / inputs / options / answer / formula / steps / pitfall。
- 文件名必须是
<id>.json;与内置题集同 id 表示「用户覆盖版本」; - 单套题集序列化后 ≤ 512 KiB,保存前按字节检查,超限直接报错、不写文件;
- 字段超长会报错而不是静默截断;题目 id 重复会报错而不是改名;
- 公式必须写 LaTeX 并用
$...$(行内)/$$...$$(独立)包住;不要用 Unicode 数学符号或裸_/^,新题集统一按 docs/deck-format.md 的 LaTeX 约定书写。
完整字段、约束、校验规则与公式写法见 docs/deck-format.md; 给 Agent 的出题规范见 skill.md。
内置题集的数字(包括干扰项)由 tools/gen_decks.py 计算并断言选项 唯一,不是手抄的:
python3 tools/gen_decks.py # 重新生成 decks/*.json 并打印每道题的答案
python3 tools/gen_decks.py --check # 只校验仓库里的题集与脚本输出一致
安全与隐私
- 两条 Web 路由(
GET /dsh-quiz/decks、POST /dsh-quiz/decks/delete)在任何处理之前 调用 dsh 的connection.requestRejection(req):Host/Origin 栅栏 + 浏览器会话校验; 缺失/空Host直接拒绝,POST必须是application/json; - 没有
connection服务时路由 fail-closed(503),不会退化成匿名可读/可删; - 题集内容只作为 React 文本渲染(公式渲染器同样不注入 HTML),插件不发外部请求、不读凭据、 不做遥测。
内置题集
ml-cnn:CNN 卷积 / 池化计算专项(10 题,含单通道卷积、零填充、步长、多通道、 ReLU、最大/平均/重叠/全局池化)ml-core:机器学习核心概念(5 题,过拟合、正则化、偏差-方差、precision/recall、数据泄漏)
开发
不需要构建,纯 ESM JavaScript:
index.js Host:/dsh-quiz/decks 路由、三个 quiz_* 工具、dsh-quiz 技能注册
client.js Web UI 的构建产物(DSH 只加载这一个文件,勿手改)
client/src/ Web UI 源码,按职责拆分:
base·locale·styles·text·math·state(宿主无关)
components·notebook·page·panel(React 组件与插件注册)
decks/*.json 内置题集
skill.md /skill 出题规范
tools/gen_decks.py 内置题集的生成与验算脚本
tools/build_client.mjs 把 client/src/*.js 拼成受版本控制的 client.js(无第三方依赖)
test/*.test.js node:test 回归测试(题集、校验上限、存储契约、路由栅栏、客户端)
docs/ 截图与题集格式文档
DSH 的客户端模块系统只服务每个包的一个 bundle(exports["./client"]),并且只把
require 解析到平台模块表,无法 import 包内相对模块,所以客户端源码在 client/src/、
运行产物仍是单个 client.js:
npm run build:client # 改完 client/src/*.js 后重新生成 client.js
npm run check # 语法检查 + 确认 client.js 与源码同步
npm test # node --test(无依赖、无网络)
python3 tools/gen_decks.py --check # 内置题集与生成脚本一致
本地测试建议用单独的 dsh profile / DSH_HOME,避免影响日常会话。Host 代码更新后需要
重启 dsh web;只改 client.js 时刷新页面即可。
更新日志
1.0.2
- 矩阵改用 KaTeX
bmatrix渲染(括号与列对齐由 KaTeX 负责),不再用自绘 HTML 网格; - 矩阵、输入与步骤中间量的标签、题集标题/学科、考点、难度、题面条件等所有题集内容都走同一套
KaTeX 渲染,
卷积结果 C($4\times4$)这类标签不会再显示成原始$...$; - 矩阵提供
aria-label(如「矩阵 [2, 4; 4, 3]」),KaTeX 的视觉输出对读屏器有纯文本替代。
1.0.1
安全与数据完整性修复(针对 1.0.0 的独立审计):
- 两条 Web 路由接入 dsh 的
connection信任栅栏(Host/Origin + 浏览器会话),空Host拒绝,POST要求application/json;没有connection时 fail-closed; - 题集大小改为统一的字节契约:保存前超过 512 KiB 直接报错、不落盘,读取同样按字节判断;
- 文本字段超长改为报错而不是静默截断;题目 id 重复改为报错而不是静默改名;
- 文件名与
<id>不一致的手写题集会被跳过并写进errors,删除/列表/保存使用同一地址; - 删除题集时清理它的作答、错题记录与隐藏标记;从错题本打开隐藏题集会先恢复显示;
- 题面/解析/速查卡的公式改为轻量渲染(
$...$、_{...}/^{...}、\frac、希腊字母等), 不再直接显示_{...}原文;skill.md、docs/deck-format.md统一了写法约定; - 修正
skill.md/docs/deck-format.md的示例(2×2 输入却写 4×4 输出 + 池化的矛盾), 示例改为完整可算的 1×1 结果;内置题集ml-cnn的干扰项改为脚本计算; - 新增
node:test回归测试与 CI(npm run check、npm test、生成脚本--check)。
未发布的后续修复(1.0.1 内)
- 公式改用 DSH 的 KaTeX Markdown 渲染器(
MarkdownText),题集按 LaTeX 书写;旧题集的 Unicode 数学在渲染时自动规范化,内置题集与生成脚本已迁移为显式 LaTeX; - 刷新按钮可见地报告结果:
已刷新:N 套题集(M 套用户题集) · 新增 X · 更新 Y、无变化提示、 最近刷新时间;宿主诊断/刷新失败改为可见的role="alert"横幅并提供重试; - 修复 1.0.1 的打包遗漏(客户端源码、生成脚本与测试随包分发)与 reduced-motion CSS 层级错误。
贡献
欢迎任何形式的贡献:新学科题集、UI/交互、zh/en 翻译、Host 代码、文档、bug 报告。
- 提交前读 CONTRIBUTING.md;题集贡献请遵守 docs/deck-format.md 与 skill.md 的「答案必须自己算对」规则;
- 新功能先开 issue 或 discussion 说明场景,避免大改方向不一致;
- 市场条目/新题集/截图都欢迎 PR。