dsh-deeptutor

English | 简体中文

A learning-assistant extension for DeepSeek Harness (dsh). It connects your
agent to a HKUDS/DeepTutor tutoring
service, so a dsh 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 harness.

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.

Migrated from the pi coding-agent extension
(TecFancy/pi-extensions, extensions/deeptutor + skills/deeptutor).

What it adds

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

Tool	What it does
deeptutor_run	Runs one learning capability: deep_solve (in-depth explanation), deep_question (self-test questions), deep_research, chat, mastery_path (learning-path planning), visualize / math_animator (visualization). 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.
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

The seven capabilities above are the fixed enum accepted by deeptutor_run.
The underlying DeepTutor CLI may expose more — enumerate the full command set
with deeptutor --help / deeptutor <cmd> --help. The deeptutor skill
instructs the agent to discover commands this way and, when the tool's enum
doesn't cover a capability, to drive the CLI directly (local binary or over
SSH).

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=data/study/csharp-covariance.html) — the answer comes back and a self-contained HTML page (plus the .md source) is written to disk.
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):

Requirements

• A working DeepSeek Harness (dsh) install. Bundle auto-registration via
  dsh plugin add is verified on dsh CLI 0.1.0-rc.6 + pnpm 8.15.6.
• A DeepTutor deployment, either:
  • Local — deeptutor serve running on this machine, or the deeptutor
    CLI on PATH (used as fallback);
  • Remote — DeepTutor on a server, reached through an auto-started SSH
    tunnel (with SSH CLI fallback).

Install into a 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.1.0" },
  "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 (skills/deeptutor and
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/); the bundle uses the same converter
  (scripts/md-to-html.js) when deeptutor_run gets an html path

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

The files under skills/ are byte-identical copies of the same skills in
TecFancy/pi-extensions (single source of truth, agent-neutral). Sync them
after upstream edits with node scripts/sync-skills.mjs ../pi-extensions.

Configuration (env vars, agent-agnostic)

# Remote deployment (DeepTutor on a server, reached through an SSH tunnel)
export DEEPTUTOR_SSH_HOST="tencent-cloud"           # SSH host alias (set = remote mode)
export DEEPTUTOR_API_BASE="http://127.0.0.1:8001"   # local tunnel address
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_API_BASE="http://127.0.0.1:8001"  # local serve port
# export DEEPTUTOR_LOCAL_BIN="deeptutor"             # local CLI path (default: deeptutor on PATH)

Restart dsh after changing env vars.

How it works

The plugin auto-detects the deployment: if a DeepTutor API is reachable (local
serve, or a remote server via tunnel), learning turns run over HTTP/WebSocket;
otherwise it falls back to the CLI — the local deeptutor binary, or the remote
binary over SSH. Remote mode starts the SSH tunnel on demand and tears it down
when the plugin unloads.

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 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)
skills/              # bundled skills: deeptutor/ + html-doc/ (installed to <DSH_HOME>/skills/)
cordis.yml           # dev overlay: insert src/index.ts by absolute path
cordis.patch.yml     # bundle patch: insert the package by name

src/index.ts registers the tools; config.ts holds env config;
cli-exec.ts local/SSH CLI execution; http-api.ts API probing + SSH tunnel;
turn.ts one learning turn (WebSocket / CLI event folding + formatting);
html-render.ts answer → self-contained HTML.