idle-scholar
Idle-time micro-learning for DeepSeek Harness: turns the agent's waiting gaps
(tool calls, MCP connects, large file reads, subagent dispatches) into flash
cards — one card per waiting turn, never in the way.
Ships seed decks for English, Japanese, and the eight subjects of the
Chinese National Judicial Examination (法考: 刑法 · 民法 · 刑诉 · 民诉 · 行政法 ·
商经知 · 三国法 · 理论法). New subjects are plain JSON course packs — a
community deck is a PR that adds files.
How it works
The plugin teaches the model two things and gives it the cards:
- A system-prompt section — when a turn will keep the user waiting, show
one study card at the very start of that turn, then continue the main task.
- An embedded skill (
idle-scholar) — the full workflow: card formats,
course rotation, the "别学了" opt-out.
Three tools supply the content and track progress:
| Tool | What it does |
|---|
study_card | Draw a card (optional course / deck / type filters). Seen-weighting: never-seen cards first, immediate repeats excluded. |
study_status | Today's count vs the daily goal, streak, deck coverage, course catalog. |
study_switch | Change the default course; persisted across sessions. |
Progress (per-card seen counts, daily totals, streak) is stored in
$DSH_HOME/idle-scholar.json — out of the repository.
Installation (DSH plugin)
dsh plugin --profile web add /path/to/idle_scholar
Then reload the harness. On DeepSeek Harness ≥ 0.2.1-alpha.3 with hot reload
enabled, code updates to this plugin apply without a restart; a fresh install
still needs one. If your profile's cordis.patch.yml already has an
idle-scholar row, delete it first — duplicate registrations fail to boot.
Recreating a profile with dsh … --from-default-profile replaces that
profile, including its plugins — re-add the plugin afterwards.
Installation (standalone skill, any agent tool)
The skill is a portable Agent Skills file:
cp -r skills/idle-scholar ~/.claude/skills/ # or ~/.agents/skills, ~/.codex/skills, ...
Without the plugin tools, the skill still works: the model generates cards in
real time following skills/idle-scholar/references/course-topics.md.
Configuration
| Field | Default | Meaning |
|---|
enabled | true | Master switch. Gates the prompt section (the only nagging surface); tools and skill stay mounted. |
defaultCourse | 'en' | Course study_card draws from when no filter is passed. |
dailyGoal | 10 | Cards per day, used for progress reporting. |
promptSection | true | Expose the system-prompt section. |
skill | true | Register the embedded idle-scholar skill. |
coursesDir | — | Extra directory of course packs, loaded in addition to the bundled decks. |
stateFile | $DSH_HOME/idle-scholar.json | Progress file location. |
Course pack format
A deck is one JSON file at courses/<course>/<deck>.json:
{
"id": "en-vocab",
"course": "en",
"name": "English core vocabulary",
"cards": [
{
"id": "en-vocab-001",
"type": "vocab",
"prompt": "**serendipity** means?",
"hint": "noun, related to chance",
"answer": "The faculty of making fortunate discoveries by accident",
"explanation": "From The Three Princes of Serendip.",
"tags": ["CET6"]
},
{
"id": "en-quiz-001",
"type": "quiz",
"prompt": "Neither of the reports ___ been proofread.",
"choices": ["have", "has", "are", "were"],
"answer": 1,
"explanation": "neither of + plural noun takes a singular verb in formal grammar."
}
]
}
Card types: vocab (word card), quiz (multiple choice, answer is an index
into choices), concept (knowledge point), tip (culture / practical
advice). All cards need a non-empty explanation.
Contributing a new subject
- Create
courses/<course-id>/<deck-id>.json following the format above
(deck and card ids must be globally unique — test/decks.test.js enforces
it).
- Add the course and its decks to
skills/idle-scholar/references/course-topics.md so skill-only
deployments can generate on-topic cards.
- Update the course table in
skill.js (npm run skill regenerates
SKILL.md; npm run skill:check verifies it).
npm test — the deck validator will catch malformed cards.
Development
npm test # unit + fake-ctx + real cordis integration tests
npm run skill:check # SKILL.md is in sync with skill.js
Prerequisites: the integration tests import the DeepSeek Harness packages
(@deepseek-ai/cordis, dsh-tools, dsh-skill, dsh-system-prompt) at
runtime. They are peerDependencies — link them from your harness checkout
or profile, and the tests skip with a clear reason if they cannot resolve.
The versions this plugin develops against are pinned in devDependencies.
They are published to npm but not under the latest tag — npm's latest
for @deepseek-ai/dsh-tools is still the placeholder 0.0.1-rc.1, while this
plugin targets 0.2.1-alpha.4 (reached through the alpha dist-tag). Its
companion versions are @deepseek-ai/cordis 4.0.5-alpha.2 and
@deepseek-ai/schemastery 3.18.5-alpha.2; pin all three together. Note that
alpha.4 has no dedicated dsh-0-2-1-* dist-tag, so the exact version strings
in devDependencies are the only source of truth.
Roadmap
License
MIT
