dsh-deeptutor 0.1.6 → 0.1.8

package/skills/deeptutor/SKILL.md

@@ -1,182 +1,183 @@
----
-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.
+---
+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 —
+
+- **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
+  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 — 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)
+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)
+```
+
+- **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
+  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                       | 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`       |
+| 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:
+  - 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
+
+- 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).
+
+### 3. Follow-up questions / targeted reinforcement
+
+Continue with the same `session_id`: details, code examples, common pitfalls, differences vs. authoritative sources.
+
+### 4. Self-test
+
+- 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
+
+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
+```
+
+When given the `html` param, `deeptutor_run` does this automatically:
+
+```
+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:
+
+- Tools: `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
+
+- 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.
+- 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

@@ -1,91 +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.
+---
+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 ≥ 20.11)
+└── 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` (≥ 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.