dsh-deeptutor 0.1.3 → 0.1.5

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.