dsh-deeptutor 0.1.4 → 0.1.6

package/README.md

@@ -130,11 +130,18 @@ run on plain Node ≥ 20 ESM.
 
 ## Skills
 
-The agent-facing workflow lives in the `deeptutor` skill, installed at
-`~/.dsh/skills/deeptutor/SKILL.md` (auto-discovered by dsh). The companion
-`html-doc` skill (`~/.dsh/skills/html-doc/`) renders study answers to
-self-contained HTML pages; this plugin bundles the same converter under
-`scripts/md-to-html.js` and uses it when `deeptutor_run` gets an `html` path.
+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.
 
 ## Configuration (env vars, agent-agnostic)
 
@@ -159,6 +166,7 @@ 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
 ```

package/README.zh.md

@@ -93,7 +93,12 @@ npm publish
 
 ## Skills
 
-面向 agent 的工作流位于 `deeptutor` skill,安装于 `~/.dsh/skills/deeptutor/SKILL.md`(dsh 自动发现)。配套的 `html-doc` skill(`~/.dsh/skills/html-doc/`)将学习内容渲染为自包含 HTML 页面;本插件内置同一转换器(`scripts/md-to-html.js`),当 `deeptutor_run` 传入 `html` 路径时自动使用。
+本包携带两个 skill(`skills/deeptutor` 与 `skills/html-doc`),随包安装器每次运行时都会把它们复制到 `<DSH_HOME>/skills/<name>/`(dsh 自动发现)——所以 `pnpm dlx dsh-deeptutor` 一次装齐插件 **和** skill:
+
+- `deeptutor` — 面向 agent 的学习工作流(`~/.dsh/skills/deeptutor/SKILL.md`)
+- `html-doc` — 将学习内容渲染为自包含 HTML 页面(`~/.dsh/skills/html-doc/`);`deeptutor_run` 传入 `html` 路径时,插件内部使用同一转换器(`scripts/md-to-html.js`)
+
+升级包版本时会就地覆盖 skill 文件;包未携带的文件不会被删除。
 
 ## 配置(环境变量,与 agent 无关)
 
@@ -118,6 +123,7 @@ src/                 # TypeScript 源码(开发加载、类型检查)
 lib/                 # 编译产物(发布入口,由 npm run build 生成)
 scripts/md-to-html.js  # 零依赖 Markdown → HTML 转换器
 scripts/install-profile.mjs  # 一键 profile 安装器(以 `dsh-deeptutor` 二进制暴露)
+skills/              # 随包 skill:deeptutor/ + html-doc/(安装到 <DSH_HOME>/skills/)
 cordis.yml           # 开发 overlay:按绝对路径插入 src/index.ts
 cordis.patch.yml     # bundle patch:按包名插入插件
 ```

package/lib/index.js

@@ -158,7 +158,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 +215,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 +235,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 +249,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-deeptutor",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "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",
@@ -16,7 +16,7 @@
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
   "bin": {
-    "dsh-deeptutor": "./scripts/install-profile.mjs"
+    "dsh-deeptutor": "scripts/install-profile.mjs"
   },
   "exports": {
     ".": {
@@ -25,6 +25,7 @@
     },
     "./cordis.patch.yml": "./cordis.patch.yml",
     "./scripts/*": "./scripts/*",
+    "./skills/*": "./skills/*",
     "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
@@ -32,6 +33,7 @@
     "lib",
     "src",
     "scripts",
+    "skills",
     "cordis.patch.yml",
     "README.md",
     "README.zh.md"

package/scripts/install-profile.mjs

@@ -18,13 +18,22 @@
  * Options:
  *   -p, --profile <name>   dsh profile to install into (default: web)
  *   -h, --help             show this help
+ *
+ * Besides installing the bundle, the installer copies the package's bundled
+ * skills (`skills/deeptutor`, `skills/html-doc`) into
+ * `<DSH_HOME>/skills/<name>/`, where dsh auto-discovers them. Existing files
+ * are overwritten; files not shipped by the package are never deleted.
  */
 import { spawnSync } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { delimiter, join } from 'node:path';
+import { cpSync, existsSync, mkdirSync, readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 const PKG = 'dsh-deeptutor';
 const NAME = 'dsh-deeptutor-install';
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
+const SKILLS_DIR = join(SCRIPT_DIR, '..', 'skills');
 
 const USAGE = `usage: dsh-deeptutor [--profile <name>]
 
@@ -186,13 +195,39 @@ function main() {
 }
 
 function finish(profile) {
+  const skills = installSkills();
   console.log(`
 \u2714 ${PKG} installed into profile '${profile}'
-  \u00b7 dependency added and dsh.profile.bundles reconciled (bundle patch auto-registered)
+  \u00b7 dependency added and dsh.profile.bundles reconciled (bundle patch auto-registered)${skills}
 
 next steps:
   1. restart dsh  (the bundle list is resolved at boot)
   2. verify:      ${verifyHint(profile)}`);
 }
 
+/**
+ * Copy the package's bundled skills into <DSH_HOME>/skills/<name>/ (dsh
+ * auto-discovers skills there). Existing files are overwritten in place;
+ * anything not shipped by this package is left untouched. Returns a
+ * human-readable summary line (or '' when there is nothing to install).
+ */
+function installSkills() {
+  if (!existsSync(SKILLS_DIR)) {
+    console.error(`\n${NAME}: warning: no skills/ directory in this package — skill install skipped (old version?)`);
+    return '';
+  }
+  const dshHome = process.env.DSH_HOME || join(homedir(), '.dsh');
+  const installed = [];
+  for (const entry of readdirSync(SKILLS_DIR, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const src = join(SKILLS_DIR, entry.name);
+    const dest = join(dshHome, 'skills', entry.name);
+    mkdirSync(dest, { recursive: true });
+    cpSync(src, dest, { recursive: true, force: true });
+    installed.push(entry.name);
+  }
+  if (installed.length === 0) return '';
+  return `\n  \u00b7 skills installed: ${installed.join(', ')} -> ${join(dshHome, 'skills')}`;
+}
+
 main();

package/skills/deeptutor/README.md

@@ -0,0 +1,106 @@
+# DeepTutor Learning Assistant (dsh 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/`)
+
+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.
+
+## Features
+
+| Capability     | Description                                                                                                              |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| Deep Solve     | In-depth explanation of a topic grounded in knowledge bases + web search, with multi-turn follow-up (session continuity) |
+| Deep Question  | Generate exercises from the same learning session                                                                        |
+| Deep Research  | Long multi-stage research (report mode supported)                                                                        |
+| KB Retrieval   | RAG hits from your personal knowledge bases (dotnet / sqlserver / react, …)                                              |
+| Note Archiving | Save study notes/plans to a server notebook for searchable review                                                        |
+| Mastery Path   | Multi-stage learning path planning                                                                                       |
+
+## 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):
+
+```bash
+# One-shot: bundle + skill, from the published package
+pnpm dlx dsh-deeptutor --profile web
+
+# Or install the skill manually from a checkout
+xcopy /e /i skills\deeptutor %USERPROFILE%\.dsh\skills\deeptutor   # Windows
+cp -r skills/deeptutor ~/.dsh/skills/deeptutor                     # macOS/Linux
+```
+
+## Configuration (environment variables)
+
+Set these in `~/.bashrc` or `~/.zshrc` (inherited by any agent at startup — agent-agnostic):
+
+```bash
+# —— Remote deployment (DeepTutor on a server, via SSH tunnel) ——
+export DEEPTUTOR_SSH_HOST="tencent-cloud"           # SSH alias (set = remote mode)
+export DEEPTUTOR_API_BASE="http://127.0.0.1:8001"   # local tunnel address (change port here)
+export DEEPTUTOR_REMOTE_BIN="/home/ubuntu/my-deeptutor/.venv/bin/deeptutor"
+export DEEPTUTOR_REMOTE_HOME="/home/ubuntu/my-deeptutor"
+
+# —— Local deployment (DeepTutor on this machine) —— leave DEEPTUTOR_SSH_HOST unset for local mode
+# export DEEPTUTOR_LOCAL_BIN="deeptutor"            # local CLI path (default: deeptutor on PATH)
+# export DEEPTUTOR_HOME="/path/to/local-workspace"  # local workspace
+```
+
+**Deployment auto-adapts**: API reachable (local serve or tunnel) → HTTP/WS; unreachable → local CLI or SSH CLI fallback.
+
+## Usage
+
+Just talk to your agent:
+
+```
+Deep-dive Span<T> with my dotnet knowledge base, quiz me with 5 questions, then archive the notes to a notebook
+```
+
+The agent follows the SKILL workflow automatically:
+
+1. **Dual sourcing**: `web_search` for authoritative material (Microsoft Learn, etc.) + `deeptutor_kb search` on your personal KB
+2. **Deep Solve**: `deeptutor_run` (deep_solve, mount KB + rag + web_search, Chinese replies)
+3. **Follow-up turns**: reuse the returned `session_id` to continue context
+4. **Self-test**: `deep_question` (config `num_questions`)
+5. **Plan**: structured study plan combining authoritative links + KB highlights
+6. **Archive**: `deeptutor_note` into a notebook
+
+## Tools
+
+| Tool             | Key parameters                                                                                                                                             |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `deeptutor_run`  | `capability` (deep_solve / deep_question / deep_research / chat / mastery_path / …), `kbs`, `tools` (rag / web_search), `session_id`, `config`, `language` |
+| `deeptutor_kb`   | `list` / `search` (kb + query + mode) / `info`                                                                                                             |
+| `deeptutor_note` | `notebook` (auto-created), `title`, `type` (chat/question/research/solve), `content` (Markdown)                                                            |
+
+## Troubleshooting
+
+| Symptom                                         | Cause & fix                                                                                                                                                                        |
+| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 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                                                                                                 |
+| 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.
+
+**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.
+
+**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.
+
+## 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)

package/skills/deeptutor/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: deeptutor
+description: Combine DeepTutor personal knowledge bases (RAG) with authoritative web sources to generate learning content, self-test questions, and study plans, and archive notes to a notebook. Works with both local and remote DeepTutor deployments. Use when the user wants to learn/review a technical topic (e.g. .NET, C#, SQL Server, React), get a deep explanation grounded in their own knowledge bases, generate exercises, or plan their learning.
+---
+
+# DeepTutor Learning Assistant (Personal Knowledge Base)
+
+Combines the user's **personal knowledge bases** (RAG retrieval) with
+**authoritative web sources** to produce learning content, self-test
+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.
+  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
+  binary on PATH, or over SSH for remote deployments). No extension needed.
+
+Pick whichever path exists in your environment; the action, not the tool, is
+what matters.
+
+## When to Use
+
+- The user wants to learn or review a technical topic (.NET, C#, SQL Server, React, …)
+- The user wants content grounded in their own notes/knowledge bases
+- The user wants generated exercises, quizzes, or a learning plan
+- The user wants to archive study notes for later review
+
+## 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**:
+
+```bash
+# 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 (change port/server here)
+export DEEPTUTOR_REMOTE_BIN="/home/ubuntu/my-deeptutor/.venv/bin/deeptutor"
+export DEEPTUTOR_REMOTE_HOME="/home/ubuntu/my-deeptutor"
+
+# Local deployment (DeepTutor on this machine) — leave DEEPTUTOR_SSH_HOST unset for local mode
+# 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)
+```
+
+- **dsh path:** API reachable (local serve or tunnel) → HTTP/WS; unreachable →
+  local CLI or SSH CLI fallback automatically. The 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
+  deployments (the tunnel is the extension's job — CLI users don't need it).
+- Migrating to another server or port only requires changing env vars — never this skill.
+
+## Actions Cheat Sheet
+
+| Action                       | dsh (tools)                      | 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`       |
+| Show a knowledge base's info | `deeptutor_kb action=info`       | `kb info <kb>`                                               |
+| Run a learning capability    | `deeptutor_run capability=<cap>` | `run <cap> "<prompt>" --format json`                         |
+| Archive a note to a notebook | `deeptutor_note`                 | `notebook add-md <nb-id> <file> --title "<t>" --type <type>` |
+| View lightweight memory      | — (CLI only)                     | `memory show`                                                |
+| List / inspect sessions      | — (CLI only)                     | `session list` · `session show <id>`                         |
+| Show a notebook's records    | — (CLI only)                     | `notebook show <name>`                                       |
+| Inspect configuration        | — (CLI only)                     | `config show` (troubleshooting)                              |
+
+Capabilities: `deep_solve` / `deep_question` / `deep_research` / `chat` /
+`mastery_path` / `visualize` / `math_animator`.
+
+Useful `run` flags: `--kb <name>` (mount a knowledge base, repeatable),
+`--tool <name>` (`rag`, `web_search`, `reason`, …, repeatable),
+`--session <id>` (continue context), `--language zh`, `--config k=v`
+(repeatable; e.g. `--config num_questions=5`), `--config-json '{"..."}'`
+(complex config), `--notebook-ref <name>` / `--history-ref <id>` (reference
+notebooks or past sessions from the prompt).
+
+## Discovering Commands
+
+The command set evolves — this cheat sheet is a curated subset, not the full
+surface. Before using a command not listed here, **discover it from the CLI
+itself** and never invent flags:
+
+```bash
+deeptutor --help              # top-level commands
+deeptutor <cmd> --help        # one subcommand's options
+```
+
+Read the output, then use only what it shows. If a needed capability is not
+in `--help`, report that to the user instead of guessing.
+
+## Recommended Learning Workflow
+
+### 1. Gather material from both channels
+
+- `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>"`
+  - 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`
+- 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).
+
+### 3. Follow-up questions / targeted reinforcement
+
+Continue with the same `session_id`: details, code examples, common pitfalls, differences vs. authoritative sources.
+
+### 4. Self-test
+
+- pi: `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
+
+Combine all three material sources into a structured plan (Markdown):
+
+- Learning goals and prerequisites
+- Core concept list (marked: from personal KB / authoritative link)
+- Phased schedule (each phase: concept → authoritative reading → KB review → exercises)
+- Quiz questions and acceptance criteria
+- Reference list (authoritative links + KB hit sources)
+
+### 5b. Render study material to local HTML (recommended)
+
+When the user wants readable/browsable/printable study material, render the
+answers to a self-contained HTML page (dark/light toggle, TOC, collapsible
+quiz answers, print-friendly) with the **html-doc skill** (zero-dependency
+Node converter):
+
+```bash
+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:
+
+```
+deeptutor_run capability=deep_solve  prompt=<topic>  kbs=[...]  tools=[rag, web_search]
+  html="data/study/<topic>/knowledge.html"  html_title="<主题> · 知识点"  language=zh
+deeptutor_run capability=deep_question  prompt=<topic essentials>  config={num_questions: 5}
+  html="data/study/<topic>/quiz.html"  html_title="<主题> · 自测题"  language=zh
+```
+
+Then tell the user the HTML file paths so they can open them in a browser.
+
+### 6. Archive
+
+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>`
+- CLI:
+  ```bash
+  deeptutor notebook list                       # find the notebook id
+  deeptutor notebook create <name> --description "archived"   # only if missing
+  deeptutor notebook add-md <nb-id> <notes.md> --title "<t>" --type solve
+  ```
+
+## Safety Boundaries
+
+Read-only exploration is always fine: `kb list/info/search`, `memory show`,
+`session list/show`, `config show`, `notebook list/show`.
+
+Never run destructive commands: `kb delete`, `memory clear`, `session delete`,
+`notebook remove-record`. Creation/update commands (`kb create/add`,
+`notebook create/add-md/replace-md`, `session rename`) only on the user's
+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.
+- `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.
+- Do not delete knowledge bases or run destructive operations (see Safety
+  Boundaries above); `kb create/add` is fine, but only on the user's explicit
+  request, never proactively.
+- CLI output: add `--format json` for machine-readable events; without it you get human-readable text.

package/skills/html-doc/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: html-doc
+description: Generates self-contained, browser-ready HTML files from Markdown content (study notes, documentation, quiz/exercise sheets) using a zero-dependency Node converter and a polished built-in template with dark/light theme toggle, collapsible answers, and print-friendly layout. Use when the user wants local HTML output for reading, reviewing, or sharing learning material and docs.
+---
+
+# HTML Doc Generator
+
+Convert Markdown into a beautiful, self-contained local HTML file (single file, inline CSS/JS, no network needed to open). Ideal for study notes, knowledge summaries, and self-test question sheets.
+
+## When to Use
+
+- After a learning session (e.g. deeptutor deep_solve / deep_question), the user wants readable local HTML of the knowledge points and quiz questions
+- Converting any Markdown notes/docs into a polished local HTML page
+
+## Files
+
+```
+html-doc/
+├── SKILL.md               # this file
+├── scripts/
+│   └── md-to-html.js      # zero-dependency Markdown → HTML converter (Node ≥ 18)
+└── assets/
+    └── template.html      # default HTML template (CSS + JS, customizable)
+```
+
+## Usage
+
+```bash
+# Basic: write Markdown to a file, then convert
+node scripts/md-to-html.js notes.md --out notes.html --title "C# 抽象类学习笔记"
+
+# From stdin (any tool output piped in)
+cat notes.md | node scripts/md-to-html.js --title "Quiz" --theme dark --out quiz.html
+
+# Options
+#   --out <file>     output path (default: <input>.html)
+#   --title <text>   page title (default: input filename or "Document")
+#   --theme <mode>   dark | light (default: light; user can toggle in-page anyway)
+#   --toc            generate a table of contents from headings (h2/h3)
+#   --lang <code>    html lang attribute (default: zh-CN)
+#   --no-collapse    disable <details> wrapping for quiz answers (default: collapse enabled)
+```
+
+## Supported Markdown
+
+ATX headings (`#`–`######`), fenced code blocks (``` with optional language), inline code, bold, italic, links, unordered/ordered lists, task lists (`- [ ]` / `- [x]`), blockquotes, tables (pipe syntax), horizontal rules, paragraphs.
+
+Anything unsupported falls back to a plain `<p>` — output always stays valid.
+
+## Recommended Workflow for Study Material
+
+1. Collect the learning content (e.g. from deeptutor_run answer) as Markdown files under a docs folder, e.g. `~/study/abstract-class/`:
+   - `knowledge.md` — the deep-solve explanation
+   - `quiz.md` — the self-test questions (mark answers inside `<details>` blocks so they collapse)
+2. Convert each file:
+   ```bash
+   node scripts/md-to-html.js knowledge.md --out knowledge.html --title "C# 抽象类 · 知识点" --toc
+   node scripts/md-to-html.js quiz.md --out quiz.html --title "C# 抽象类 · 自测题" --toc
+   ```
+3. Open the HTML files in the browser (or tell the user the file paths).
+
+## Quiz Answer Collapsing
+
+The converter auto-detects quiz structure: any heading containing "答案" / "Answer" / "解析" / "Explanation" starts a `<details>` block whose following content (until the next heading) is collapsed. Also, a heading line that is immediately followed by content gets wrapped when the heading matches. This keeps the quiz readable while hiding answers until clicked.
+
+To be explicit, authors can also wrap answers manually:
+
+```markdown
+<details><summary>答案：C</summary>
+
+解析：...
+</details>
+```
+
+Raw `<details>`/`<summary>` blocks are preserved as-is (the only raw-HTML passthrough); everything else is treated as Markdown/text and HTML-escaped.
+
+## Customizing the Template
+
+Edit `assets/template.html` — it uses `{{TITLE}}`, `{{BODY}}`, `{{THEME}}`, `{{LANG}}`, `{{TOC}}`, `{{GENERATED}}` placeholders. Keep placeholders intact; the converter does simple string replacement. The built-in template includes:
+
+- CSS variables for light/dark theming with an in-page toggle button (remembers choice in localStorage)
+- Print stylesheet (answers stay collapsed on paper)
+- Code block styling with optional language badge
+- Table styling, blockquote styling, task-list checkboxes
+- Responsive layout (comfortable reading column)
+
+## Notes
+
+- Zero dependencies — only `node` (≥ 18) 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.