dsh-gpt-tutor

Diagnosis-first tutoring for DeepSeek Harness. It decides what the learner is stuck on before deciding what to say, then renders one teaching card you can actually operate: drag a parameter and the figure, the area and the readout change with it.

中文说明 · 设计说明 · 研究依据 · 四域索引 · CHANGELOG

---

What it is not

Not a fixed pipeline. There is no "explain → example → quiz" script that fires on every question. The plugin gives the model a diagnosis table and a set of card blocks; which blocks appear, in what order, and whether anything is graded at all is decided per question. Ask "just explain it" and you get an explanation.

Install

Recommended: install from a packed tarball

git clone https://github.com/Nemushio/dsh-gpt-tutor
cd dsh-gpt-tutor
npm pack            # writes dsh-gpt-tutor-1.1.0.tgz

Then install that dsh-gpt-tutor-1.1.0.tgz as a local plugin package (the plugin manager, or plugin_manager action=install_bundle pointed at the archive's absolute path).

Why a tarball and not the directory. Pointing the installer at a directory records a link: dependency and makes the package manager re-resolve the entire profile tree. On a profile whose lockfile disagrees with its node_modules, that step deletes unrelated packages — one reported run printed Packages: +2 -17 and removed 17 of them. The DSH host then could not resolve this bundle, and the Web client failed with web boot: 1 entry did not activate. A tarball is an ordinary file dependency: no symlink, no lockfile re-resolve.

Alternative: install from the repository

plugin_manager  action=install_bundle  target=github:Nemushio/dsh-gpt-tutor

This needs pnpm's git support; if it fails, use the tarball.

Uninstall

Disable the plugin row first, then remove the dependency. If the profile still holds two residue entries — dsh-gpt-tutor in dependencies and in dsh.profile.bundles — delete both, or startup reports cannot resolve profile bundle and skips the plugin.

The bundle adds one Loader row, gpt-tutor. A successful install reports application: applied; a page refresh is needed the first time so the browser half of the plugin loads.

Requirements: DSH >=0.2.1-rc.2 <0.3.0, Node >=22. No runtime dependencies: the plugin imports only packages the dsh installation already provides.

Turn it on and off

Two independent switches, both in the Web UI:

1. The plugin row switch (Settings → Plugins). Disabling unloads the tools and the prompt section immediately; cards already in the transcript stay readable.
2. The settings form on the bundle page, generated from the plugin's own config schema:

Setting	Values	Effect
enabled	on/off	Off: no prompt section, and both tools refuse to run.
domain	auto, physics, probability, calculus, programming	Pins the subject instead of letting the model infer it.
strictness	socratic, balanced, answer-fast	How hard answers are withheld. answer-fast gives the full explanation and the answer in the first turn.
figure	on/off	Off: text and formulas only, no figure block.
maxChecks	0–3	Checks per card. 0 turns a card into explanation plus questions in prose.

Changes apply from the next request.

What a card can contain

A card is a title, one focus line, and up to six blocks in any order. Rules the plugin enforces, not suggestions:

• At least one block the learner must produce: check, predict or transfer.
• At most one figure. Two figures split attention; that is a rejection, not a warning.
• The graded answer may not appear in a figure caption, a help-ladder step, a hint, or as the reveal of its own prediction. Whole-sentence matching is not enough: a fragment like 2a or 1/4 inside a caption is caught too.
• A worked example may not restate the graded check. Changing the numbers is the intended fix; the checker compares digits and word overlap, so a cosmetic edit does not pass.

Block	Purpose	Notable fields
figure	One adjustable picture	kind, params, domain, series/expr/term, shade, readout, caption
refute	Name the wrong model, then the better one	claim, whyWrong, correct, misconceptionId
worked	Worked example with fading	problem, steps[{text, faded}], answer
predict	Commit before revealing (POE)	prompt, options, reveal
check	Graded item	kind: choice / numeric / text, answer, options, tolerance, feedback.ladder
transfer	Test the same idea on a changed case	prompt, differs, hint, answer
recall	Close with retrieval, not a summary	prompt, items

Wrong options can carry wrongFor: "<misconception id>", which must exist in the subject pack. That keeps a wrong answer diagnostic instead of decorative. Unknown ids are rejected with the field path.

text checks are never auto-graded: the card shows your text, shows the reference answer, and asks you to compare. Claiming an automatic verdict there would be a lie.

The eight figures

Drag any slider and the drawing, the shaded area and the readouts update in place. No new turn, no re-render of the conversation.

Figure	Subject	Parameters	Shows
density	probability, calculus	bounds, height	density curve, shaded interval, its area
freqgrid	probability	prevalence, sensitivity, specificity, population	2×2 natural-frequency table and positive predictive value
forces	physics	mass, angle, friction, applied force	incline, force arrows, net force, acceleration, static vs sliding
kinematics	physics	v₀, a, t	x(t) and v(t) with the current point
function	calculus	1–2 parameters, x₀	f(x), tangent, optional shaded area, slope at x₀
series	calculus	n, parameter	partial sums with points, plus the running total
memory	programming	initial value, pass mode, reassignment	caller and callee cells, whether the caller changed
trace	programming	iteration count	step table with the exit row

function alone covers the hole in (x²−a²)/(x−a), the secant-to-tangent limit, the tangent as local linearisation, and the definite integral as shaded signed area.

Subjects

Four packs ship today: university physics, probability, calculus, programming (C / C++ / Python / Java). Each pack is a Markdown file whose front matter declares its misconception catalogue; the model loads it on demand through the tutor_pack tool instead of paying for it in the system prompt.

Adding a fifth subject takes three steps and no JavaScript:

1. Copy packs/calculus.md to packs/<id>.md and rewrite it (front matter: id, title, figures, misconceptions with id / claim / whyWrong).
2. Add one entry to packs/index.json.
3. npm test — the pack contract test rejects missing ids, duplicate ids, thin catalogues, unknown figure names and over-long packs.

See docs/domains.md for the full walkthrough.

Limits worth knowing

• Slider positions and answers live in page memory. They survive scrolling, but not a page reload or a fork. The card itself re-renders from the session log, because its whole payload travels in the tool result.
• Only the four packs above are supported. Ask about chemistry and the plugin says so instead of pretending the card fits.
• Complex animation, 3D and multi-panel dashboards are not this plugin's job; the dsh-motion-ui plugin already covers them, and the teaching policy defers to it.
• The expression language is deliberately small (src/expr.js): arithmetic, comparisons, &&, ||, !, a conditional, and 17 named functions. No eval, no property access, no loops. If a figure needs more, use render_canvas instead.

Development

npm run build   # regenerate client.js from src/client-body.js + src/expr.js
npm run check   # syntax-check every runtime file
npm test        # 76 tests, single process

client.js is committed on purpose: installing this bundle must not require a build step. test/build.test.mjs fails if the committed file drifts from a fresh build, so edit src/, rebuild, then commit both.

Architecture in one line: index.js registers one prompt section and two tools; src/host.js owns them; src/lesson.js validates a card; src/packs.js loads the subject Markdown; src/expr.js is the only expression implementation, inlined into client.js at build time so the Host and the browser cannot disagree.

See docs/design.md for why the teaching model looks like this, and CONTRIBUTING.md for the rules a pull request must satisfy.

Licence

MIT. See LICENSE and NOTICE — the latter lists every source the teaching method and the misconception catalogues draw on, with its licence and exactly what was and was not taken.