dsh-deeptutor

Learning assistant extension for DeepSeek Harness (dsh), Claude Code (MCP) and pi: DeepTutor tutoring for your agent: deep explanations, self-test questions, learning paths, personal knowledge-base search (RAG), note archiving, and any other DeepTutor CLI

Packages

Package details

extensionskill

Install dsh-deeptutor from npm and Pi will load the resources declared by the package manifest.

$ pi install npm:dsh-deeptutor
Package
dsh-deeptutor
Version
0.4.0
Published
Nov 20, 2026
Downloads
4,360/mo · 1,070/wk
Author
smpower
License
MIT
Types
extension, skill
Size
264.4 KB
Dependencies
0 dependencies · 2 peers
Pi manifest JSON
{
  "skills": [
    "./.agents/skills"
  ],
  "extensions": [
    "./pi/deeptutor.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

dsh-deeptutor

English | 简体中文

A learning-assistant extension for DeepSeek Harness (dsh), Claude Code and pi. It connects your agent to a HKUDS/DeepTutor tutoring service, so a session can explain topics in depth, quiz you, plan learning paths, search your personal knowledge bases, and keep a study notebook, all without leaving the agent. In dsh it loads as a bundle; in Claude Code it installs as a plugin; in pi it installs as a pi package. In all three the same four tools are served over MCP by the bundled server, so the tools are defined once and only the install differs.

Ask the agent "teach me async/await" and it can run a deep-solve, render the answer as a self-contained HTML study page you can open in a browser, and archive a summary into your notebook.

What it adds

Four agent-facing tools that the model uses whenever you ask for learning help:

Tool What it does
deeptutor_run Runs one learning capability, e.g. deep_solve (in-depth explanation), deep_question (self-test questions), deep_research, chat, mastery_path (learning-path planning), visualize. Can mount your knowledge bases (kbs) and tools (rag, web_search, reason, code_execution, …); returns a session_id so later turns continue the same context, and can render the answer to an HTML study page.
deeptutor_kb Lists, searches, and inspects your personal knowledge bases (RAG)
deeptutor_note Archives Markdown study notes (plans, summaries, wrong answers) into a server notebook
deeptutor_cli Runs any other DeepTutor CLI command, behind safety tiers (below)

Following DeepTutor upgrades without plugin releases

The plugin does not mirror DeepTutor's command surface, so a DeepTutor upgrade that adds commands, capabilities or tools needs no plugin change:

  • Capabilities are discovered at runtime. deeptutor_run takes any capability name. The plugin reads deeptutor module list (JSON, cached for five minutes) to learn which capabilities the deployment's ready modules provide; a capability whose module is not ready fails fast with the reason and the list of available ones, and names no module lists are passed straight to the CLI (they may come from a DeepTutor plugin).

  • Every other command goes through deeptutor_cli. The agent discovers commands from the CLI itself (args: ["--help"], then ["kb", "--help"], …) instead of a list baked into the plugin. Safety tiers keep the passthrough honest about commands it has never seen:

    Tier Commands Behaviour
    read --help, verbs list / show / info / search / state / status / list-*, doctor, run runs directly
    confirm everything else, including verbs the plugin does not know yet runs only with confirm: true, which the agent may set only after you explicitly asked for that change
    blocked delete, remove*, clear, uninstall, rollback, login, …; interactive or long-running chat / start / stop / serve / init refused; run them in a terminal yourself
  • Drift check. Only the few CLI shapes the dedicated tools are built on (run --format json events, kb search, notebook add-md, module list) can break the plugin. npm run check:cli checks them against the deployment your env vars point at; run it after upgrading DeepTutor.

Example session

A typical flow when you ask your agent for learning help:

  1. Ask — "Explain C# generics covariance using my dotnet knowledge base, and generate a study page."
  2. The agent grounds the answer in your own material: deeptutor_kb (action=search, kb=dotnet).
  3. It runs a deep-solve: deeptutor_run (capability=deep_solve, kbs=[dotnet], html=/home/me/study/csharp-covariance.html) — the answer comes back and a self-contained HTML page (plus the .md source) is written to disk. The html path must be absolute; relative paths are rejected.
  4. It files a summary: deeptutor_note (notebook=dotnet-learning, type=solve).

Nothing here is a fixed script — the agent picks the tools and parameters based on what you ask for.

A real recording of exactly this flow (deep-solve on the async/await state machine, mounted on a dotnet-csharp knowledge base, rendered to an HTML study page, then archived to a notebook):

Final answer

Generated HTML study page

Requirements

  • An agent host: Claude Code (or another MCP client) with Node ≥ 20, a working DeepSeek Harness (dsh) install, 0.1.0-rc.6 or newer, or pi with Node ≥ 22.19 (the version pi itself requires). The manifest declares a version floor rather than a ceiling, so a new dsh release is never refused at install time; a scheduled probe boots the plugin against the current npm latest and next hosts instead and opens an issue when activation breaks. Bundle auto-registration via dsh plugin add was verified on dsh CLI 0.1.0-rc.6, 0.2.1-rc.2 and 0.2.1-rc.3.

  • A DeepTutor deployment, either:

    • Local — the deeptutor CLI installed on this machine (on PATH, or pointed to by DEEPTUTOR_LOCAL_BIN);
    • Remote — DeepTutor installed on a server you can reach with passwordless SSH; the plugin runs the server's CLI over SSH.

    Tested against DeepTutor 1.7.1. Since 1.7 the kb and notebook commands and most capabilities come from optional modules; check that the ones you use are installed and enabled with deeptutor module list.

Install into pi (package)

This package is also a pi package, so one command brings the skills and the tools:

pi install npm:dsh-deeptutor

To work from a checkout instead, pi install /path/to/dsh-deeptutor (add --local to write the declaration to .pi/settings.json for one project rather than your user settings). Restart pi, or run /reload, then check with /mcp that the deeptutor server connected and that the two skills are listed.

The skills arrive through pi.skills in package.json; the tools through pi.extensions → pi/deeptutor.ts, a ~30-line extension that registers the same scripts/mcp-launch.mjs server the Claude Code plugin runs, with a 30-minute request timeout because one deep_solve turn outlives pi's 60-second default. The server is registered with deferred exposure: the four tool schemas stay out of every request until the model reaches for them with tool_search, then it calls them directly. Pass --no-mcp to a pi run, or disable the server in /mcp, to hide the tools; the skills keep working either way.

Set the DEEPTUTOR_* env vars where pi can inherit them (see Configuration) and restart pi.

Without the package, a running pi finds the two skills on its own inside this repository, because it scans .agents/skills/ from the working directory up to the repository root. The tools then need one command:

pi mcp add deeptutor -- node /path/to/dsh-deeptutor/scripts/mcp-launch.mjs

That writes ~/.pi/agent/mcp.json (add -l for a project .pi/mcp.json).

Install into Claude Code (plugin)

This repo is also a Claude Code plugin marketplace. Inside Claude Code:

/plugin marketplace add TecFancy/dsh-deeptutor
/plugin install dsh-deeptutor@dsh-deeptutor

or from a shell:

claude plugin marketplace add TecFancy/dsh-deeptutor
claude plugin install dsh-deeptutor@dsh-deeptutor

The plugin brings the two skills (deeptutor, html-doc) and an MCP server named deeptutor that serves the four tools (Claude Code shows them as mcp__plugin_dsh-deeptutor_deeptutor__deeptutor_run and so on). Set the DEEPTUTOR_* env vars (see Configuration) where Claude Code can inherit them, then restart Claude Code.

The server is started by scripts/mcp-launch.mjs, which picks the first entry that works: compiled lib/ → the plugin's own src/ via Node's type stripping (Node ≥ 22.6, no network) → npx dsh-deeptutor@<plugin version> for older Node. Either way the server runs the code of the installed plugin version.

Other MCP clients (Codex, Cursor, …) can run the published bin directly:

{ "command": "npx", "args": ["-y", "-p", "dsh-deeptutor", "dsh-deeptutor-mcp"] }

Install into a dsh profile (bundle)

The package is published to npm as dsh-deeptutor. Recommended one-liner — runs the bundled installer (scripts/install-profile.mjs, exposed as the dsh-deeptutor binary), which wraps dsh plugin add and automatically handles the pnpm workspace-root check described below:

pnpm dlx dsh-deeptutor --profile web

From a checkout of this repo, the same installer runs directly:

node scripts/install-profile.mjs --profile web

Or run the underlying command yourself — dsh plugin add forwards to pnpm and then reconciles the profile's dsh.profile.bundles against the installed state, so a dsh.bundle-declaring package like this one is registered automatically:

dsh plugin --profile web add dsh-deeptutor -w

Pitfall — pnpm workspace-root check. The dsh profile scaffold always writes a pnpm-workspace.yaml (packages: ["."], nodeLinker: hoisted), which makes the profile directory itself a pnpm workspace root. On pnpm ≥ 8, pnpm add in a workspace root aborts with ERR_PNPM_ADDING_TO_ROOT unless the workspace-root flag is explicit, so the command above appends -w/--workspace-root (pnpm prints this error on stdout on Windows, which is why a plain dsh plugin add without the flag fails even though the output looks like a warning). Two ways to handle it:

  1. Use the installer / keep -w in the command (recommended — the installer tries the plain command first and adds -w automatically only when the check trips).
  2. Or allow the plain command permanently: add ignore-workspace-root-check: true to ~/.dsh/profiles/<name>/pnpm-workspace.yaml, then dsh plugin --profile web add dsh-deeptutor works as written.

Verify the bundle is mounted, then restart dsh (the bundle list is resolved at boot):

dsh --profile web --dump-config | grep dsh-deeptutor

If your dsh CLI does not auto-register the bundle (older versions, or you installed the dependency manually), add it to the profile manifest (~/.dsh/profiles/<name>/package.json) and run dsh plugin --profile web install:

{
  "dependencies": { "dsh-deeptutor": "^0.3.1" },
  "dsh": {
    "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-deeptutor"] }
  }
}

Alternatively, keep the manifest untouched and mount the bundle through a user patch layer (the npm package still has to be installed first):

# overlay.yml — insert the bundle row via a user patch layer
- insert:
    - id: dsh-deeptutor
      name: 'dsh-deeptutor'
dsh web --patch ./overlay.yml

The bundle manifest (dsh.bundle.patch → cordis.patch.yml) inserts the plugin row; later patch layers can override or disable it by id.

Skills

Two skills ship inside this package (.agents/skills/deeptutor and .agents/skills/html-doc) and the bundled installer copies them to <DSH_HOME>/skills/<name>/ (auto-discovered by dsh) whenever it runs — so pnpm dlx dsh-deeptutor installs the bundle and the skills in one shot:

  • deeptutor — the agent-facing learning workflow (~/.dsh/skills/deeptutor/SKILL.md)
  • html-doc — renders study answers to self-contained HTML pages (~/.dsh/skills/html-doc/); when deeptutor_run gets an html path, the converter and template are resolved as $HTML_DOC_SCRIPT / $HTML_DOC_TEMPLATE → the installed skill above → the copy bundled in this package. Editing the installed template (say, wiring KaTeX in) changes the next render without patching the plugin, and the tool result prints which layer supplied each file. The html path itself must be absolute.

Installing a newer package version overwrites skill files in place; files not shipped by the package are never deleted.

The Claude Code plugin and the pi package load the same skills straight from .agents/skills/. The skills are maintained in this repo under .agents/skills/.

Configuration (env vars, agent-agnostic)

# Remote deployment (DeepTutor on a server, driven over SSH)
export DEEPTUTOR_SSH_HOST="tencent-cloud"           # SSH host alias (set = remote mode)
export DEEPTUTOR_REMOTE_BIN="/home/ubuntu/my-deeptutor/.venv/bin/deeptutor"
export DEEPTUTOR_REMOTE_HOME="/home/ubuntu/my-deeptutor"

# Local deployment — leave DEEPTUTOR_SSH_HOST unset
# export DEEPTUTOR_LOCAL_BIN="deeptutor"             # local CLI path (default: deeptutor on PATH)

Restart dsh or Claude Code after changing env vars.

Windows, local mode: point DEEPTUTOR_LOCAL_BIN at deeptutor.exe (for a pip/venv install: <venv>\Scripts\deeptutor.exe). A .cmd/.bat wrapper also works: one that only forwards %* to an .exe is bypassed and the .exe is run directly; any other wrapper runs through cmd.exe, which cannot pass multi-line prompts, so those calls fail with a hint to use the .exe.

How it works

Every tool call drives the DeepTutor CLI: the local deeptutor binary, or the remote binary over SSH when DEEPTUTOR_SSH_HOST is set. deeptutor serve does not need to be reachable from this machine.

Earlier versions tried the HTTP/WebSocket API first (/api/v1/... through an SSH tunnel) and only then fell back to the CLI. DeepTutor 1.7 serves those routes under different paths and behind a login, so the probe always failed and each call waited about 30 seconds before reaching the CLI. That path was removed; DEEPTUTOR_API_BASE is no longer read.

Develop against a checkout (no publish needed)

dsh web --patch /path/to/dsh-deeptutor/cordis.yml

Build & publish

npm install
npm run build        # tsc → lib/ (relative .ts imports rewritten to .js)
npm run typecheck
npm test             # node:test + type stripping
npm run check:cli    # drift check against the live DeepTutor your env vars point at
claude plugin validate . --strict   # Claude Code plugin + marketplace manifests
npm pack             # inspect dsh-deeptutor-<version>.tgz
npm publish          # set a scope/registry of your choice first

Node ≥ 22.6 (type stripping) is needed to load the raw src/*.ts via --patch; the published bundle ships compiled lib/, so installed profiles run on plain Node ≥ 20 ESM.

Layout

src/                 # TypeScript sources (dev loading, typecheck)
lib/                 # compiled ESM (published entry, from `npm run build`)
scripts/md-to-html.js  # zero-dependency Markdown → HTML converter
scripts/install-profile.mjs  # one-shot profile installer (exposed as the `dsh-deeptutor` binary)
scripts/mcp-launch.mjs # starts the MCP server for the Claude Code plugin and the pi extension
pi/deeptutor.ts        # pi entry point: registers that MCP server with pi
scripts/check-cli.ts   # drift check against a live DeepTutor (`npm run check:cli`)
.agents/skills/       # bundled skills: deeptutor/ + html-doc/ (dsh installs them to <DSH_HOME>/skills/, Claude Code and pi load them in place)
.claude-plugin/       # Claude Code plugin.json (skills + MCP server) + marketplace.json
cordis.yml           # dev overlay: insert src/index.ts by absolute path
cordis.patch.yml     # bundle patch: insert the package by name

src/tools.ts defines the four tools once, host-neutral; index.ts registers them in dsh; mcp.ts serves them over MCP stdio (mcp-main.ts is the dsh-deeptutor-mcp bin) and that is what Claude Code and pi reach; cli-policy.ts holds the deeptutor_cli safety tiers; discovery.ts capability discovery; config.ts holds env config; cli-exec.ts local/SSH CLI execution; win-cmd.ts starting a .cmd/.bat CLI on Windows; turn.ts one learning turn (CLI JSONL event folding + formatting); html-render.ts answer → self-contained HTML.

License

MIT — see LICENSE.