dsh-deeptutor

English | 简体中文

DeepTutor bridge bundle for DeepSeek Harness (dsh), migrated from the pi coding-agent extension (TecFancy/pi-extensions, extensions/deeptutor + skills/deeptutor).

Registers three model-facing tools that drive the HKUDS/DeepTutor tutoring service:

Tool	Purpose
deeptutor_run	Run a learning capability: deep_solve / deep_question / deep_research / chat / mastery_path / visualize / math_animator (HTTP/WS first, CLI fallback)
deeptutor_kb	List / search / info the user's personal knowledge bases (RAG)
deeptutor_note	Archive Markdown learning notes to 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).

Deployment auto-detects local vs. remote: local serve (or local CLI) on this machine, or 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 (verified on dsh CLI 0.1.0-rc.6 + pnpm 8.15.6):

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.

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 pack             # inspect dsh-deeptutor-0.1.0.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.

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.

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.