dsh-deeptutor 0.1.5 → 0.1.7

package/README.md

@@ -143,6 +143,10 @@ Two skills ship inside this package (`skills/deeptutor` and
 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)
 
 ```bash

package/README.zh.md

@@ -100,6 +100,8 @@ npm publish
 
 升级包版本时会就地覆盖 skill 文件;包未携带的文件不会被删除。
 
+`skills/` 下的文件与 `TecFancy/pi-extensions` 中的同名技能逐字节一致(以 pi 仓库为唯一来源,保持 agent 中立)。上游修改后执行 `node scripts/sync-skills.mjs ../pi-extensions` 同步。
+
 ## 配置(环境变量,与 agent 无关)
 
 ```bash

package/lib/config.js

@@ -44,6 +44,7 @@ export function configGuide() {
         '   export DEEPTUTOR_REMOTE_HOME="remote-DEEPTUTOR_HOME-workspace"\n' +
         "   Verify serve is running on the server (ssh to it: curl http://127.0.0.1:8001/api/v1/system/status)\n" +
         "   Verify passwordless SSH login works (ssh alias + BatchMode)\n" +
+        'PowerShell users: use $env:VAR="value" instead of export VAR=value.\n' +
         "Restart the agent after configuring.\n");
 }
 export const CAPABILITIES = [

package/lib/http-api.js

@@ -31,6 +31,7 @@ export async function ensureApi() {
         return true;
     if (!SSH_HOST)
         return false; // Local deployment: fall back to local CLI when serve is down, no tunnel needed
+    let tunnelDead = false;
     if (!tunnelProc || tunnelProc.exitCode !== null) {
         tunnelProc = spawn("ssh", [
             "-N",
@@ -48,9 +49,17 @@ export async function ensureApi() {
             "ConnectTimeout=10",
             SSH_HOST,
         ], { stdio: "ignore", windowsHide: true });
+        // Fast-fail: a tunnel that exits immediately (bad alias, port in use,
+        // refused connection) is not going to recover — stop waiting for it.
+        tunnelProc.once("exit", () => {
+            tunnelDead = true;
+            tunnelProc = null;
+        });
         tunnelProc.unref();
     }
     for (let i = 0; i < 20; i++) {
+        if (tunnelDead)
+            return false;
         if (await apiProbe(1000))
             return true;
         await new Promise((r) => setTimeout(r, 500));
@@ -62,7 +71,15 @@ export async function apiJson(path, init, opts = {}) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 60_000);
     const onAbort = () => controller.abort();
-    opts.signal?.addEventListener("abort", onAbort, { once: true });
+    // An already-aborted signal never fires its "abort" event again — check the
+    // flag first so a pre-aborted call fails immediately instead of running to
+    // completion against a still-open controller.
+    if (opts.signal?.aborted) {
+        controller.abort();
+    }
+    else {
+        opts.signal?.addEventListener("abort", onAbort, { once: true });
+    }
     try {
         const res = await fetch(`${API_BASE}${path}`, { ...init, signal: controller.signal });
         if (!res.ok)

package/lib/index.js

@@ -127,6 +127,10 @@ export function apply(ctx) {
                 });
             }
             catch (err) {
+                if (exec.signal.aborted) {
+                    // user cancelled mid-CLI-run: report it as a cancellation, not a failure
+                    throw new Error("[deeptutor_run cancelled]");
+                }
                 throw new Error(configGuide() +
                     `[deeptutor_run failed (HTTP and CLI both unavailable)] ${err?.message ?? String(err)}`);
             }
@@ -158,7 +162,7 @@ export function apply(ctx) {
             },
             top_k: {
                 type: "number",
-                description: "Number of hits to return, default 5",
+                description: "Number of hits to return, default 5 (applied locally to the CLI search result; the deeptutor CLI has no --top-k flag)",
             },
             max_chars: {
                 type: "number",
@@ -215,7 +219,8 @@ export function apply(ctx) {
                     console.log(`[deeptutor] kb ${args.action} HTTP failed, falling back to CLI: ${err?.message}`);
                 }
             }
-            // CLI fallback (local or SSH)
+            // CLI fallback (local or SSH). NOTE: `kb search` has no --top-k flag
+            // (verified on deeptutor CLI 1.5.x); top_k is applied locally below.
             let argv;
             if (args.action === "list") {
                 argv = ["kb", "list", "--format", "json"];
@@ -234,8 +239,6 @@ export function apply(ctx) {
                     "--mode",
                     args.mode ?? "hybrid",
                 ];
-                if (args.top_k)
-                    argv.push("--top-k", String(args.top_k));
             }
             const { stdout, stderr, code, killed } = await runCli(argv, {
                 signal: exec.signal,
@@ -250,16 +253,32 @@ export function apply(ctx) {
             let body = stdout.trim() || "(empty result)";
             if (args.action === "search") {
                 try {
-                    const arr = JSON.parse(stdout);
-                    if (Array.isArray(arr)) {
-                        body = arr
-                            .map((s, i) => {
-                            const text = s.text ?? s.content ?? s.snippet ?? JSON.stringify(s);
-                            const src = s.source ?? s.doc_name ?? s.file ?? "";
-                            return `[${i + 1}]${src ? `  source: ${src}` : ""}\n${typeof text === "string" ? text : JSON.stringify(text)}`;
-                        })
-                            .join("\n\n");
-                        body = `${arr.length} hits:\n\n` + body;
+                    const parsed = JSON.parse(stdout);
+                    const fmtHit = (s, i) => {
+                        const text = s.text ?? s.content ?? s.snippet ?? JSON.stringify(s);
+                        const src = s.source ?? s.doc_name ?? s.file ?? "";
+                        const title = s.title ? `  title: ${s.title}` : "";
+                        const score = typeof s.score === "number" ? `  score: ${s.score}` : "";
+                        return `[${i + 1}]${src ? `  source: ${src}` : ""}${title}${score}\n${typeof text === "string" ? text : JSON.stringify(text)}`;
+                    };
+                    // Current deeptutor CLI (1.5.x) returns an object
+                    // { query, answer, content, sources, provider }; older builds
+                    // returned a bare array of hits. Accept both.
+                    if (Array.isArray(parsed)) {
+                        const hits = args.top_k ? parsed.slice(0, args.top_k) : parsed;
+                        body = `${hits.length} hits:\n\n` + hits.map(fmtHit).join("\n\n");
+                    }
+                    else if (parsed && typeof parsed === "object") {
+                        const parts = [];
+                        if (parsed.query)
+                            parts.push(`Query: ${parsed.query}`);
+                        if (typeof parsed.answer === "string" && parsed.answer.trim())
+                            parts.push(`Answer: ${parsed.answer.trim()}`);
+                        const sources = Array.isArray(parsed.sources) ? parsed.sources : [];
+                        const hits = args.top_k ? sources.slice(0, args.top_k) : sources;
+                        parts.push(`${hits.length} hits:`);
+                        parts.push(hits.map(fmtHit).join("\n\n"));
+                        body = parts.join("\n\n");
                     }
                 }
                 catch {

package/lib/turn.d.ts

@@ -1,3 +1,4 @@
+import { runCli } from "./cli-exec.ts";
 export interface TurnResult {
     answer: string;
     errors: string[];
@@ -19,6 +20,13 @@ export interface RunParams {
 export declare function collectEvent(state: TurnResult, e: any): void;
 /** Execute one turn over WebSocket (streaming). */
 export declare function wsRunTurn(params: RunParams, timeoutMs: number, signal?: AbortSignal): Promise<TurnResult>;
-/** Execute one turn via the CLI (local or SSH). */
-export declare function cliRunTurn(params: RunParams, timeoutMs: number, signal?: AbortSignal): Promise<TurnResult>;
+/**
+ * Build the `deeptutor run` argv for a capability turn (pure, unit-tested).
+ * Scalar config values go as repeatable --config k=v; object/array values are
+ * collected into --config-json (the CLI's documented form for complex config)
+ * instead of being stringified into a k=<json> value that no parser expects.
+ */
+export declare function buildRunArgs(params: RunParams): string[];
+/** Execute one turn via the CLI (local or SSH). `run` is injectable for tests. */
+export declare function cliRunTurn(params: RunParams, timeoutMs: number, signal?: AbortSignal, run?: typeof runCli): Promise<TurnResult>;
 export declare const fmtTurnResult: (capability: string, r: TurnResult, maxChars: number) => string;

package/lib/turn.js

@@ -110,8 +110,13 @@ export function wsRunTurn(params, timeoutMs, signal) {
         };
     });
 }
-/** Execute one turn via the CLI (local or SSH). */
-export async function cliRunTurn(params, timeoutMs, signal) {
+/**
+ * Build the `deeptutor run` argv for a capability turn (pure, unit-tested).
+ * Scalar config values go as repeatable --config k=v; object/array values are
+ * collected into --config-json (the CLI's documented form for complex config)
+ * instead of being stringified into a k=<json> value that no parser expects.
+ */
+export function buildRunArgs(params) {
     const argv = ["run", params.capability, params.prompt, "--format", "json"];
     for (const kb of params.kbs ?? [])
         argv.push("--kb", kb);
@@ -121,11 +126,26 @@ export async function cliRunTurn(params, timeoutMs, signal) {
         argv.push("--session", params.session_id);
     if (params.language)
         argv.push("--language", params.language);
-    for (const [k, v] of Object.entries(params.config ?? {}))
-        argv.push("--config", `${k}=${typeof v === "object" ? JSON.stringify(v) : v}`);
-    const { stdout, stderr, code, killed } = await runCli(argv, { signal, timeoutMs });
-    if (killed)
-        throw new Error(`CLI execution timed out (${Math.round(timeoutMs / 1000)}s)`);
+    const complexConfig = {};
+    for (const [k, v] of Object.entries(params.config ?? {})) {
+        if (typeof v === "object" && v !== null)
+            complexConfig[k] = v;
+        else
+            argv.push("--config", `${k}=${v}`);
+    }
+    if (Object.keys(complexConfig).length > 0) {
+        argv.push("--config-json", JSON.stringify(complexConfig));
+    }
+    return argv;
+}
+/** Execute one turn via the CLI (local or SSH). `run` is injectable for tests. */
+export async function cliRunTurn(params, timeoutMs, signal, run = runCli) {
+    const { stdout, stderr, code, killed } = await run(buildRunArgs(params), { signal, timeoutMs });
+    if (killed) {
+        // A kill can come from the user cancelling (signal) or from the timeout;
+        // report the real reason instead of always blaming the timeout.
+        throw new Error(signal?.aborted ? "Aborted" : `CLI execution timed out (${Math.round(timeoutMs / 1000)}s)`);
+    }
     if (code !== 0)
         throw new Error(`CLI exit=${code}: ${stderr || "(no stderr)"}`);
     const state = { answer: "", errors: [], toolCalls: [] };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-deeptutor",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "DeepTutor bridge bundle for DeepSeek Harness: learning capabilities, knowledge bases, and note archiving (HTTP/WS first, CLI fallback; auto-adapts local/remote deployment).",
   "keywords": [
     "dsh",
@@ -12,6 +12,9 @@
     "agent"
   ],
   "license": "MIT",
+  "engines": {
+    "node": ">=20.11"
+  },
   "type": "module",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -47,7 +50,8 @@
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
     "prepack": "npm run build && npm run typecheck",
-    "pack:check": "npm pack --dry-run"
+    "pack:check": "npm pack --dry-run",
+    "test": "node --test --experimental-strip-types"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",

package/scripts/md-to-html.js

@@ -9,7 +9,7 @@
  *
  * Features: headings, fenced code blocks, inline code/bold/italic/links, lists,
  * task lists, blockquotes, pipe tables, hr, quiz answer collapsing (<details>),
- * raw HTML passthrough, HTML escaping. Zero npm dependencies (Node >= 22).
+ * raw HTML passthrough, HTML escaping. Zero npm dependencies (Node >= 20.11 — uses import.meta.dirname).
  */
 "use strict";
 
@@ -29,22 +29,41 @@ function parseArgs(argv) {
     collapse: true,
   };
   const positional = [];
+  const valueFlags = new Set(["--out", "--title", "--theme", "--lang"]);
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    if (a === "--out") opts.out = argv[++i];
-    else if (a === "--title") opts.title = argv[++i];
-    else if (a === "--theme") opts.theme = argv[++i] === "dark" ? "dark" : "light";
-    else if (a === "--toc") opts.toc = true;
-    else if (a === "--lang") opts.lang = argv[++i];
+    if (a === "--toc") opts.toc = true;
     else if (a === "--no-collapse") opts.collapse = false;
     else if (a === "--help" || a === "-h") {
       printHelp();
       process.exit(0);
+    } else if (valueFlags.has(a)) {
+      const value = argv[i + 1];
+      if (value === undefined || value.startsWith("--")) {
+        fail(`Missing value for ${a} (e.g. --out out.html)`);
+      }
+      i++;
+      if (a === "--out") opts.out = value;
+      else if (a === "--title") opts.title = value;
+      else if (a === "--theme") {
+        if (value !== "dark" && value !== "light") {
+          fail(`Invalid --theme value "${value}": expected dark or light`);
+        }
+        opts.theme = value;
+      } else if (a === "--lang") opts.lang = value;
+    } else if (a.startsWith("--")) {
+      fail(`Unknown option: ${a} (run with --help for usage)`);
     } else positional.push(a);
   }
   return { opts, positional };
 }
 
+/** Print an error to stderr and exit non-zero (CLI contract: never silently swallow bad flags). */
+function fail(message) {
+  console.error(`[html-doc] ${message}`);
+  process.exit(1);
+}
+
 function printHelp() {
   console.log(`md-to-html.js — Markdown → self-contained HTML
 
@@ -330,7 +349,16 @@ function main() {
       : "";
 
   const generated = new Date().toISOString().slice(0, 10);
-  const templatePath = path.join(import.meta.dirname, "..", "assets", "template.html");
+  // The same converter ships in two locations (skills/html-doc/scripts/ and a
+  // package-root scripts/ copy); resolve the template wherever we are.
+  const templateCandidates = [
+    path.join(import.meta.dirname, "..", "assets", "template.html"),
+    path.join(import.meta.dirname, "..", "skills", "html-doc", "assets", "template.html"),
+  ];
+  const templatePath = templateCandidates.find((p) => fs.existsSync(p));
+  if (!templatePath) {
+    fail(`template.html not found (looked in: ${templateCandidates.join(", ")})`);
+  }
   let template = fs.readFileSync(templatePath, "utf8");
   template = template
     .replace(/\{\{TITLE\}\}/g, esc(title))

package/scripts/sync-skills.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+/**
+ * Copy the shared skill files from a pi-extensions checkout into this repo.
+ * The pi repo is the single source of truth; the files must be agent-neutral.
+ *
+ * Usage:
+ *   node scripts/sync-skills.mjs [path-to-pi-extensions]
+ * Default source: ../pi-extensions
+ */
+import { copyFileSync, existsSync, mkdirSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const piRoot = resolve(process.argv[2] ?? join(here, "..", "pi-extensions"));
+
+// [pi source, this-repo destination]
+// The bundle uses the root scripts/ copy at runtime (src/html-render.ts);
+// the skill copy ships inside the package. Both must stay identical.
+const FILES = [
+  ["skills/deeptutor/SKILL.md", "skills/deeptutor/SKILL.md"],
+  ["skills/deeptutor/README.md", "skills/deeptutor/README.md"],
+  ["skills/html-doc/SKILL.md", "skills/html-doc/SKILL.md"],
+  ["skills/html-doc/assets/template.html", "skills/html-doc/assets/template.html"],
+  ["skills/html-doc/scripts/md-to-html.js", "scripts/md-to-html.js"],
+  ["skills/html-doc/scripts/md-to-html.js", "skills/html-doc/scripts/md-to-html.js"],
+];
+
+let failures = 0;
+for (const [src, dst] of FILES) {
+  const from = join(piRoot, src);
+  const to = join(here, dst);
+  if (!existsSync(from)) {
+    console.error(`[sync-skills] missing source: ${from}`);
+    failures++;
+    continue;
+  }
+  mkdirSync(dirname(to), { recursive: true });
+  copyFileSync(from, to);
+  console.log(`[sync-skills] ${src} -> ${dst}`);
+}
+if (failures > 0) {
+  console.error("[sync-skills] some sources missing — is the pi-extensions path correct?");
+  process.exit(1);
+}
+console.log("[sync-skills] done — review the diff, then commit.");

package/skills/deeptutor/README.md

@@ -1,9 +1,16 @@
-# DeepTutor Learning Assistant (dsh bundle + SKILL)
+# DeepTutor Learning Assistant (extension / bundle + SKILL)
 
 > This README is the human-facing documentation; `SKILL.md` is the agent-facing instruction file (loaded on demand).
-> Bundle: the `dsh-deeptutor` npm package (tools) ｜ Skill: `skills/deeptutor/SKILL.md` (shipped inside the same package, installed to `~/.dsh/skills/deeptutor/`)
+> The same code ships in two ecosystems — edit in `pi-extensions` first, then sync to `dsh-deeptutor` (see Maintenance).
 
-Bridges **DeepTutor** (open-source personalized tutoring platform) into dsh: combines your **personal knowledge bases** (RAG retrieval) with **authoritative web sources** to generate learning content, self-test questions, and study plans — then archives your notes to a DeepTutor notebook for later review.
+Bridges **DeepTutor** (open-source personalized tutoring platform) into your
+agent: combines your **personal knowledge bases** (RAG retrieval) with
+**authoritative web sources** to generate learning content, self-test
+questions, and study plans — then archives your notes to a DeepTutor notebook
+for later review.
+
+- **pi** — extension `extensions/deeptutor/` (entry: `index.ts`) + skill `skills/deeptutor/SKILL.md` (repo: `TecFancy/pi-extensions`)
+- **dsh** — npm bundle `dsh-deeptutor` (the same TypeScript core) + the same skill, installed to `~/.dsh/skills/deeptutor/` (repo: `TecFancy/dsh-deeptutor`)
 
 ## Features
 
@@ -18,10 +25,17 @@ Bridges **DeepTutor** (open-source personalized tutoring platform) into dsh: com
 
 ## Installation
 
-The `deeptutor` skill ships inside the `dsh-deeptutor` npm package. The bundled
-installer (`scripts/install-profile.mjs` in the package, or
-`pnpm dlx dsh-deeptutor --profile web`) installs the bundle **and** copies this
-skill to `~/.dsh/skills/deeptutor/` (dsh auto-discovers skills there):
+### pi
+
+```bash
+# Install the pi package (extension + SKILL)
+pi install git:github.com/TecFancy/pi-extensions
+
+# Local development: /reload after editing (local path installs are not copied)
+pi install D:/source/personal/pi-extensions
+```
+
+### dsh
 
 ```bash
 # One-shot: bundle + skill, from the published package
@@ -81,26 +95,35 @@ The agent follows the SKILL workflow automatically:
 | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Connection timeout / host resolution failure    | ① Check `DEEPTUTOR_SSH_HOST` is set and SSH passwordless login works ② Is `deeptutor serve` running? (`curl http://127.0.0.1:8001/api/v1/system/status`)                           |
 | Tool returns "No DEEPTUTOR_* env vars detected" | One-time hint on first call; configure per the Configuration section and restart the agent                                                                                         |
-| Local CLI garbled output / crashes              | The extension injects `PYTHONUTF8=1` automatically; verify Python ≥ 3.11 otherwise                                                                                                 |
+| Local CLI garbled output / crashes              | The tools inject `PYTHONUTF8=1` automatically; verify Python ≥ 3.11 otherwise                                                                                                      |
 | DNS resolution fails (Windows)                  | Common on corporate networks: if `nslookup` works but curl/python can't resolve, fix `C:\Windows\System32\drivers\etc\hosts` (when appending entries, always start with a newline) |
 | CLI-only package missing modules                | Official `packaging/deeptutor-cli` has incomplete deps; `pip install <module>` per the error (known: loguru, fastapi)                                                              |
 
 ## FAQ
 
 **Q: Can local and remote be used at the same time?**
-A: Yes. Switching only requires changing env vars (set/remove `DEEPTUTOR_SSH_HOST`); the SKILL and bundle stay unchanged.
+A: Yes. Switching only requires changing env vars (set/remove `DEEPTUTOR_SSH_HOST`); the SKILL and tools stay unchanged.
 
 **Q: What if I change servers or ports?**
-A: Only env vars change (`DEEPTUTOR_SSH_HOST` / `DEEPTUTOR_API_BASE` / remote paths) — never the SKILL or bundle.
+A: Only env vars change (`DEEPTUTOR_SSH_HOST` / `DEEPTUTOR_API_BASE` / remote paths) — never the SKILL or tools.
 
 **Q: Is the knowledge base list hardcoded?**
 A: No. Tools query `deeptutor_kb list` dynamically; new bases are picked up automatically.
 
 **Q: Can other agents (Claude Code / Codex) use it?**
-A: Yes. The SKILL follows the Agent Skills standard and can be linked into `~/.agents/skills/`; the tools themselves are registered by the dsh bundle.
+A: Yes. The SKILL follows the Agent Skills standard and can be linked into `~/.agents/skills/`; the `deeptutor_*` tools are registered by the pi extension or the dsh bundle.
 
 ## Maintenance
 
-- Bundle features: edit the relevant file under `src/` (`index.ts` for tool wiring, `cli-exec.ts`/`http-api.ts`/`turn.ts` for transport logic, `config.ts` for env vars/helpers) → rebuild with `npm run build`
-- SKILL content: edit `skills/deeptutor/SKILL.md` (keep the `name` + `description` frontmatter)
-- Release: bump the version in `package.json`, push a `v*` tag, then `npm publish` (see the repo README)
+Shared skill files (`skills/deeptutor/*`, `skills/html-doc/*`) live **in this
+repo (pi-extensions)** and are kept agent-neutral. `dsh-deeptutor` ships
+byte-identical copies; after editing, sync with:
+
+```bash
+cd ../dsh-deeptutor && node scripts/sync-skills.mjs ../pi-extensions
+```
+
+- pi code: edit the relevant file under `extensions/deeptutor/` (`index.ts` for tool wiring, `cli-exec.ts`/`http-api.ts`/`turn.ts` for transport logic, `config.ts` for env vars/helpers) → `/reload` to verify
+- dsh code: same files under `dsh-deeptutor/src/` → rebuild with `npm run build`
+- Release pi: push a tag to GitHub, then `pi install git:github.com/TecFancy/pi-extensions@<tag>`
+- Release dsh: bump the version in `package.json`, push a `v*` tag → CI publishes to npm

package/skills/deeptutor/SKILL.md

@@ -12,7 +12,7 @@ questions, and study plans, then archives notes to a DeepTutor notebook.
 This skill is **agent-agnostic**: every action below has two equivalent
 drivers —
 
-- **dsh (with the dsh-deeptutor bundle installed):** the `deeptutor_*` tools.
+- **pi / dsh (with the pi deeptutor extension or the `dsh-deeptutor` bundle installed):** the `deeptutor_*` tools.
   They auto-adapt local/remote deployment (HTTP/WS first with an automatic
   SSH tunnel, CLI fallback) and stream progress.
 - **Any agent / plain CLI:** the `deeptutor` executable directly (local
@@ -30,7 +30,7 @@ what matters.
 
 ## Configuration (env vars, agent-agnostic)
 
-Nothing is hardcoded in this skill; all server parameters come from environment variables (put them in `~/.bashrc` or `~/.zshrc`; any agent — dsh / Claude Code / Codex / opencode — inherits them at startup). **Deployment mode adapts automatically**:
+Nothing is hardcoded in this skill; all server parameters come from environment variables (put them in `~/.bashrc` or `~/.zshrc`; any agent — pi / dsh / Claude Code / Codex / opencode — inherits them at startup). **Deployment mode adapts automatically**:
 
 ```bash
 # Remote deployment (DeepTutor on a server, reached through an SSH tunnel)
@@ -44,8 +44,8 @@ export DEEPTUTOR_REMOTE_HOME="/home/ubuntu/my-deeptutor"
 # export DEEPTUTOR_LOCAL_BIN="deeptutor"             # local CLI path (default: deeptutor on PATH)
 ```
 
-- **dsh path:** API reachable (local serve or tunnel) → HTTP/WS; unreachable →
-  local CLI or SSH CLI fallback automatically. The bundle starts/recycles
+- **Tools path:** API reachable (local serve or tunnel) → HTTP/WS; unreachable →
+  local CLI or SSH CLI fallback automatically. The extension/bundle starts/recycles
   the SSH tunnel; local mode needs no tunnel.
 - **Plain CLI path:** run `deeptutor <subcommand>` locally, or
   `ssh <DEEPTUTOR_SSH_HOST> <DEEPTUTOR_REMOTE_BIN> <subcommand>` for remote
@@ -54,7 +54,7 @@ export DEEPTUTOR_REMOTE_HOME="/home/ubuntu/my-deeptutor"
 
 ## Actions Cheat Sheet
 
-| Action                       | dsh (tools)                      | CLI equivalent (`deeptutor …`)                               |
+| Action                       | Tools (`deeptutor_*`)            | CLI equivalent (`deeptutor …`)                               |
 | ---------------------------- | -------------------------------- | ------------------------------------------------------------ |
 | List knowledge bases         | `deeptutor_kb action=list`       | `kb list --format json`                                      |
 | Search a knowledge base      | `deeptutor_kb action=search`     | `kb search <kb> "<query>" --format json --mode hybrid`       |
@@ -96,13 +96,13 @@ in `--help`, report that to the user instead of guessing.
 
 - `web_search` for **authoritative sources**: official docs (Microsoft Learn / learn.microsoft.com), official blogs, trusted tutorials. Keep the source links.
 - Search the user's personal knowledge base (pick the right one: dotnet-related → their dotnet base, database → sqlserver) to get their own curated notes:
-  - pi: `deeptutor_kb action=search kb=<kb> query="<topic>"`
+  - Tools: `deeptutor_kb action=search kb=<kb> query="<topic>"`
   - CLI: `deeptutor kb search <kb> "<topic>" --format json`
   - Always list bases first (`deeptutor_kb action=list` / `deeptutor kb list --format json`) — never assume names.
 
 ### 2. Deep Solve
 
-- pi: `deeptutor_run capability=deep_solve prompt="<topic>" kbs=[<kb>] tools=[rag, web_search] language=zh`
+- Tools: `deeptutor_run capability=deep_solve prompt="<topic>" kbs=[<kb>] tools=[rag, web_search] language=zh`
 - CLI: `deeptutor run deep_solve "<topic>" --kb <kb> --tool rag --tool web_search --language zh --format json`
 
 **Always record the returned `session_id`** — reuse it for every follow-up turn so DeepTutor keeps the context (chat history, knowledge bases, tools).
@@ -113,7 +113,7 @@ Continue with the same `session_id`: details, code examples, common pitfalls, di
 
 ### 4. Self-test
 
-- pi: `deeptutor_run capability=deep_question prompt="<topic essentials>" session_id=<same> config={num_questions: 5} kbs=[<kb>] language=zh`
+- Tools: `deeptutor_run capability=deep_question prompt="<topic essentials>" session_id=<same> config={num_questions: 5} kbs=[<kb>] language=zh`
 - CLI: `deeptutor run deep_question "<topic essentials>" --session <same> --config num_questions=5 --kb <kb> --language zh --format json`
 
 ### 5. Output a study plan
@@ -137,7 +137,7 @@ Node converter):
 node skills/html-doc/scripts/md-to-html.js <answer.md> --out <page.html> --title "<主题>" --toc
 ```
 
-On dsh, `deeptutor_run` does this automatically when given the `html` param:
+When given the `html` param, `deeptutor_run` does this automatically:
 
 ```
 deeptutor_run capability=deep_solve  prompt=<topic>  kbs=[...]  tools=[rag, web_search]
@@ -152,7 +152,7 @@ Then tell the user the HTML file paths so they can open them in a browser.
 
 Store the final notes/plan in a server notebook (e.g. `dotnet-learning`) so they can be retrieved for review later:
 
-- dsh: `deeptutor_note notebook=<name> title="<t>" type=solve content=<markdown>`
+- Tools: `deeptutor_note notebook=<name> title="<t>" type=solve content=<markdown>`
 - CLI:
   ```bash
   deeptutor notebook list                       # find the notebook id
@@ -172,7 +172,8 @@ explicit request — never proactively.
 
 ## Notes
 
-- On dsh, calls go through HTTP/WS first (tunnel), falling back to SSH CLI automatically when the tunnel is down; `deeptutor_run` streams over WebSocket so progress is visible.
+- Tool calls go through HTTP/WS first (tunnel), falling back to SSH CLI automatically when the tunnel is down; `deeptutor_run` streams over WebSocket so progress is visible.
+- CLI-only flags (not exposed as `deeptutor_run` tool parameters): `--config-json` (complex config; the tools pass config through the API's `config` parameter instead), `--notebook-ref`, `--history-ref`.
 - `deep_research` can take minutes: give a generous timeout (900+) or split long tasks.
 - Results may be truncated (default 30000 chars) — ask to continue for the full content.
 - RAG hits can be noisy; treat official sources as authoritative and point out conflicts to the user.

package/skills/html-doc/SKILL.md

@@ -18,7 +18,7 @@ Convert Markdown into a beautiful, self-contained local HTML file (single file,
 html-doc/
 ├── SKILL.md               # this file
 ├── scripts/
-│   └── md-to-html.js      # zero-dependency Markdown → HTML converter (Node ≥ 18)
+│   └── md-to-html.js      # zero-dependency Markdown → HTML converter (Node ≥ 20.11)
 └── assets/
     └── template.html      # default HTML template (CSS + JS, customizable)
 ```
@@ -86,6 +86,6 @@ Edit `assets/template.html` — it uses `{{TITLE}}`, `{{BODY}}`, `{{THEME}}`, `{
 
 ## Notes
 
-- Zero dependencies — only `node` (≥ 18) is required; no npm install needed
+- Zero dependencies — only `node` (≥ 20.11, uses `import.meta.dirname`) is required; no npm install needed
 - Output is fully self-contained: inline CSS + JS, no external fonts/CDN (offline-friendly)
 - Escaping is handled: content is HTML-escaped before insertion. Raw-HTML passthrough is intentionally narrow (`<details>`/`<summary>` only) since `deeptutor_run` feeds model/web_search-sourced answers into this converter automatically — a wider tag whitelist would let untrusted `<script>`/`on*=` content ride along into the generated local HTML.