dsh-deeptutor 0.1.3 → 0.1.5

package/README.md

@@ -1,136 +1,177 @@
-# dsh-deeptutor
-
-**English** | [简体中文](https://github.com/TecFancy/dsh-deeptutor/blob/main/README.zh.md)
-
-DeepTutor bridge **bundle** for **DeepSeek Harness (dsh)**, migrated from the
-pi coding-agent extension (`TecFancy/pi-extensions`, `extensions/deeptutor` +
-`skills/deeptutor`).
-
-Registers three model-facing tools that drive the
-[HKUDS/DeepTutor](https://github.com/HKUDS/DeepTutor) tutoring service:
-
-| Tool | Purpose |
-|---|---|
-| `deeptutor_run` | Run a learning capability: `deep_solve` / `deep_question` / `deep_research` / `chat` / `mastery_path` / `visualize` / `math_animator` (HTTP/WS first, CLI fallback) |
-| `deeptutor_kb` | List / search / info the user's personal knowledge bases (RAG) |
-| `deeptutor_note` | Archive Markdown learning notes to a server notebook |
-
-The seven capabilities above are the fixed enum accepted by `deeptutor_run`.
-The underlying DeepTutor CLI may expose more — enumerate the full command set
-with `deeptutor --help` / `deeptutor <cmd> --help`. The `deeptutor` skill
-instructs the agent to discover commands this way and, when the tool's enum
-doesn't cover a capability, to drive the CLI directly (local binary or over
-SSH).
-
-Deployment auto-detects local vs. remote: local `serve` (or local CLI) on this
-machine, or a server reached through an auto-started SSH tunnel (with SSH CLI
-fallback).
-
-## Install into a profile (bundle)
-
-The package is published to npm as `dsh-deeptutor`. Install it with a single
-command — `dsh plugin add` forwards to pnpm and then reconciles the profile's
-`dsh.profile.bundles` against the installed state, so a `dsh.bundle`-declaring
-package like this one is registered automatically (verified on dsh CLI
-0.1.0-rc.6):
-
-```sh
-dsh plugin --profile web add dsh-deeptutor
-```
-
-Verify the bundle is mounted, then restart dsh (the bundle list is resolved
-at boot):
-
-```sh
-dsh --profile web --dump-config | grep dsh-deeptutor
-```
-
-If your dsh CLI does not auto-register the bundle (older versions, or you
-installed the dependency manually), add it to the profile manifest
-(`~/.dsh/profiles/<name>/package.json`) and run `dsh plugin --profile web
-install`:
-
-```json
-{
-  "dependencies": { "dsh-deeptutor": "^0.1.0" },
-  "dsh": {
-    "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-deeptutor"] }
-  }
-}
-```
-
-Alternatively, keep the manifest untouched and mount the bundle through a user
-patch layer (the npm package still has to be installed first):
-
-```yaml
-# overlay.yml — insert the bundle row via a user patch layer
-- insert:
-    - id: dsh-deeptutor
-      name: 'dsh-deeptutor'
-```
-
-```sh
-dsh web --patch ./overlay.yml
-```
-
-The bundle manifest (`dsh.bundle.patch → cordis.patch.yml`) inserts the plugin
-row; later patch layers can override or disable it by id.
-
-## Develop against a checkout (no publish needed)
-
-```sh
-dsh web --patch /path/to/dsh-deeptutor/cordis.yml
-```
-
-## Build & publish
-
-```sh
-npm install
-npm run build        # tsc → lib/ (relative .ts imports rewritten to .js)
-npm run typecheck
-npm pack             # inspect dsh-deeptutor-0.1.0.tgz
-npm publish          # set a scope/registry of your choice first
-```
-
-Node ≥ 22.6 (type stripping) is needed to load the raw `src/*.ts` via
-`--patch`; the published bundle ships compiled `lib/`, so installed profiles
-run on plain Node ≥ 20 ESM.
-
-## Skills
-
-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.
-
-## Configuration (env vars, agent-agnostic)
-
-```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
-export DEEPTUTOR_REMOTE_BIN="/home/ubuntu/my-deeptutor/.venv/bin/deeptutor"
-export DEEPTUTOR_REMOTE_HOME="/home/ubuntu/my-deeptutor"
-
-# Local deployment — leave DEEPTUTOR_SSH_HOST unset
-# export DEEPTUTOR_API_BASE="http://127.0.0.1:8001"  # local serve port
-# export DEEPTUTOR_LOCAL_BIN="deeptutor"             # local CLI path (default: deeptutor on PATH)
-```
-
-Restart dsh after changing env vars.
-
-## Layout
-
-```
-src/                 # TypeScript sources (dev loading, typecheck)
-lib/                 # compiled ESM (published entry, from `npm run build`)
-scripts/md-to-html.js  # zero-dependency Markdown → HTML converter
-cordis.yml           # dev overlay: insert src/index.ts by absolute path
-cordis.patch.yml     # bundle patch: insert the package by name
-```
-
-`src/index.ts` registers the tools; `config.ts` holds env config;
-`cli-exec.ts` local/SSH CLI execution; `http-api.ts` API probing + SSH tunnel;
-`turn.ts` one learning turn (WebSocket / CLI event folding + formatting);
-`html-render.ts` answer → self-contained HTML.
+# dsh-deeptutor
+
+**English** | [简体中文](https://github.com/TecFancy/dsh-deeptutor/blob/main/README.zh.md)
+
+DeepTutor bridge **bundle** for **DeepSeek Harness (dsh)**, migrated from the
+pi coding-agent extension (`TecFancy/pi-extensions`, `extensions/deeptutor` +
+`skills/deeptutor`).
+
+Registers three model-facing tools that drive the
+[HKUDS/DeepTutor](https://github.com/HKUDS/DeepTutor) tutoring service:
+
+| Tool | Purpose |
+|---|---|
+| `deeptutor_run` | Run a learning capability: `deep_solve` / `deep_question` / `deep_research` / `chat` / `mastery_path` / `visualize` / `math_animator` (HTTP/WS first, CLI fallback) |
+| `deeptutor_kb` | List / search / info the user's personal knowledge bases (RAG) |
+| `deeptutor_note` | Archive Markdown learning notes to a server notebook |
+
+The seven capabilities above are the fixed enum accepted by `deeptutor_run`.
+The underlying DeepTutor CLI may expose more — enumerate the full command set
+with `deeptutor --help` / `deeptutor <cmd> --help`. The `deeptutor` skill
+instructs the agent to discover commands this way and, when the tool's enum
+doesn't cover a capability, to drive the CLI directly (local binary or over
+SSH).
+
+Deployment auto-detects local vs. remote: local `serve` (or local CLI) on this
+machine, or a server reached through an auto-started SSH tunnel (with SSH CLI
+fallback).
+
+## Install into a profile (bundle)
+
+The package is published to npm as `dsh-deeptutor`. Recommended one-liner —
+runs the bundled installer (`scripts/install-profile.mjs`, exposed as the
+`dsh-deeptutor` binary), which wraps `dsh plugin add` and automatically
+handles the pnpm workspace-root check described below:
+
+```sh
+pnpm dlx dsh-deeptutor --profile web
+```
+
+From a checkout of this repo, the same installer runs directly:
+
+```sh
+node scripts/install-profile.mjs --profile web
+```
+
+Or run the underlying command yourself — `dsh plugin add` forwards to pnpm
+and then reconciles the profile's `dsh.profile.bundles` against the installed
+state, so a `dsh.bundle`-declaring package like this one is registered
+automatically (verified on dsh CLI 0.1.0-rc.6 + pnpm 8.15.6):
+
+```sh
+dsh plugin --profile web add dsh-deeptutor -w
+```
+
+> **Pitfall — pnpm workspace-root check.** The dsh profile scaffold always
+> writes a `pnpm-workspace.yaml` (`packages: ["."]`, `nodeLinker: hoisted`),
+> which makes the profile directory itself a pnpm workspace root. On
+> pnpm ≥ 8, `pnpm add` in a workspace root aborts with
+> `ERR_PNPM_ADDING_TO_ROOT` unless the workspace-root flag is explicit, so
+> the command above appends `-w`/`--workspace-root` (pnpm prints this error
+> on stdout on Windows, which is why a plain `dsh plugin add` without the
+> flag fails even though the output looks like a warning). Two ways to
+> handle it:
+>
+> 1. Use the installer / keep `-w` in the command (recommended — the
+>    installer tries the plain command first and adds `-w` automatically
+>    only when the check trips).
+> 2. Or allow the plain command permanently: add
+>    `ignore-workspace-root-check: true` to
+>    `~/.dsh/profiles/<name>/pnpm-workspace.yaml`, then
+>    `dsh plugin --profile web add dsh-deeptutor` works as written.
+
+Verify the bundle is mounted, then restart dsh (the bundle list is resolved
+at boot):
+
+```sh
+dsh --profile web --dump-config | grep dsh-deeptutor
+```
+
+If your dsh CLI does not auto-register the bundle (older versions, or you
+installed the dependency manually), add it to the profile manifest
+(`~/.dsh/profiles/<name>/package.json`) and run `dsh plugin --profile web
+install`:
+
+```json
+{
+  "dependencies": { "dsh-deeptutor": "^0.1.0" },
+  "dsh": {
+    "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-deeptutor"] }
+  }
+}
+```
+
+Alternatively, keep the manifest untouched and mount the bundle through a user
+patch layer (the npm package still has to be installed first):
+
+```yaml
+# overlay.yml — insert the bundle row via a user patch layer
+- insert:
+    - id: dsh-deeptutor
+      name: 'dsh-deeptutor'
+```
+
+```sh
+dsh web --patch ./overlay.yml
+```
+
+The bundle manifest (`dsh.bundle.patch → cordis.patch.yml`) inserts the plugin
+row; later patch layers can override or disable it by id.
+
+## Develop against a checkout (no publish needed)
+
+```sh
+dsh web --patch /path/to/dsh-deeptutor/cordis.yml
+```
+
+## Build & publish
+
+```sh
+npm install
+npm run build        # tsc → lib/ (relative .ts imports rewritten to .js)
+npm run typecheck
+npm pack             # inspect dsh-deeptutor-0.1.0.tgz
+npm publish          # set a scope/registry of your choice first
+```
+
+Node ≥ 22.6 (type stripping) is needed to load the raw `src/*.ts` via
+`--patch`; the published bundle ships compiled `lib/`, so installed profiles
+run on plain Node ≥ 20 ESM.
+
+## Skills
+
+Two skills ship inside this package (`skills/deeptutor` and
+`skills/html-doc`) and the bundled installer copies them to
+`<DSH_HOME>/skills/<name>/` (auto-discovered by dsh) whenever it runs — so
+`pnpm dlx dsh-deeptutor` installs the bundle **and** the skills in one shot:
+
+- `deeptutor` — the agent-facing learning workflow (`~/.dsh/skills/deeptutor/SKILL.md`)
+- `html-doc` — renders study answers to self-contained HTML pages
+  (`~/.dsh/skills/html-doc/`); the bundle uses the same converter
+  (`scripts/md-to-html.js`) when `deeptutor_run` gets an `html` path
+
+Installing a newer package version overwrites skill files in place; files not
+shipped by the package are never deleted.
+
+## Configuration (env vars, agent-agnostic)
+
+```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
+export DEEPTUTOR_REMOTE_BIN="/home/ubuntu/my-deeptutor/.venv/bin/deeptutor"
+export DEEPTUTOR_REMOTE_HOME="/home/ubuntu/my-deeptutor"
+
+# Local deployment — leave DEEPTUTOR_SSH_HOST unset
+# export DEEPTUTOR_API_BASE="http://127.0.0.1:8001"  # local serve port
+# export DEEPTUTOR_LOCAL_BIN="deeptutor"             # local CLI path (default: deeptutor on PATH)
+```
+
+Restart dsh after changing env vars.
+
+## Layout
+
+```
+src/                 # TypeScript sources (dev loading, typecheck)
+lib/                 # compiled ESM (published entry, from `npm run build`)
+scripts/md-to-html.js  # zero-dependency Markdown → HTML converter
+scripts/install-profile.mjs  # one-shot profile installer (exposed as the `dsh-deeptutor` binary)
+skills/              # bundled skills: deeptutor/ + html-doc/ (installed to <DSH_HOME>/skills/)
+cordis.yml           # dev overlay: insert src/index.ts by absolute path
+cordis.patch.yml     # bundle patch: insert the package by name
+```
+
+`src/index.ts` registers the tools; `config.ts` holds env config;
+`cli-exec.ts` local/SSH CLI execution; `http-api.ts` API probing + SSH tunnel;
+`turn.ts` one learning turn (WebSocket / CLI event folding + formatting);
+`html-render.ts` answer → self-contained HTML.

package/README.zh.md

@@ -1,107 +1,131 @@
-# dsh-deeptutor
-
-[English](https://github.com/TecFancy/dsh-deeptutor/blob/main/README.md) | **简体中文**
-
-面向 **DeepSeek Harness (dsh)** 的 DeepTutor 桥接 **bundle**,从 pi 编码 agent 扩展迁移而来(`TecFancy/pi-extensions`,`extensions/deeptutor` + `skills/deeptutor`)。
-
-注册三个模型可见工具,驱动 [HKUDS/DeepTutor](https://github.com/HKUDS/DeepTutor) 辅导服务:
-
-| 工具 | 用途 |
-|---|---|
-| `deeptutor_run` | 运行学习能力: `deep_solve` / `deep_question` / `deep_research` / `chat` / `mastery_path` / `visualize` / `math_animator`(优先 HTTP/WS,CLI 回退) |
-| `deeptutor_kb` | 列出 / 搜索 / 查看个人知识库(RAG)信息 |
-| `deeptutor_note` | 将 Markdown 学习笔记归档到服务端 notebook |
-
-上表 7 个 capability 是 `deeptutor_run` 工具接受的固定枚举。底层 DeepTutor CLI 可能支持更多命令——用 `deeptutor --help` / `deeptutor <cmd> --help` 可枚举完整命令集。`deeptutor` skill 会指示 agent 用这种方式动态发现命令;当工具的枚举未覆盖某能力时,agent 可直接调用 CLI(本地二进制或经 SSH)来驱动。
-
-部署模式自动适配:本机本地 `serve`(或本地 CLI),或通过自动建立的 SSH 隧道访问服务器(含 SSH CLI 回退)。
-
-## 安装到 profile(bundle 方式)
-
-包已发布到 npm(`dsh-deeptutor`)。一条命令即可安装:`dsh plugin add` 会转发给 pnpm 安装依赖,并把 profile 的 `dsh.profile.bundles` 与已安装状态对账,因此声明了 `dsh.bundle` 的包(如本插件)会被自动登记(已在 dsh CLI 0.1.0-rc.6 上验证):
-
-```sh
-dsh plugin --profile web add dsh-deeptutor
-```
-
-验证挂载,然后重启 dsh(bundle 列表在启动时解析):
-
-```sh
-dsh --profile web --dump-config | grep dsh-deeptutor
-```
-
-如果你的 dsh CLI 不会自动登记 bundle(旧版本,或手动安装依赖),请在 profile 清单(`~/.dsh/profiles/<name>/package.json`)中手动加入,再运行 `dsh plugin --profile web install`:
-
-```json
-{
-  "dependencies": { "dsh-deeptutor": "^0.1.0" },
-  "dsh": {
-    "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-deeptutor"] }
-  }
-}
-```
-
-也可以不动清单,改用用户 patch 层挂载 bundle(仍需先安装 npm 包):
-
-```yaml
-# overlay.yml —— 通过用户 patch 层插入 bundle 行
-- insert:
-    - id: dsh-deeptutor
-      name: 'dsh-deeptutor'
-```
-
-```sh
-dsh web --patch ./overlay.yml
-```
-
-bundle 清单(`dsh.bundle.patch → cordis.patch.yml`)负责插入插件行;上层 patch 层可按 id 覆盖或禁用。
-
-## 源码开发(无需发布)
-
-```sh
-dsh web --patch /path/to/dsh-deeptutor/cordis.yml
-```
-
-## 构建与发布
-
-```sh
-npm install
-npm run build        # tsc → lib/(相对 .ts import 改写为 .js)
-npm run typecheck
-npm pack             # 检查 dsh-deeptutor-0.1.0.tgz
-npm publish
-```
-
-通过 `--patch` 直接加载 `src/*.ts` 需要 Node ≥ 22.6(type stripping);发布的 bundle 自带编译后的 `lib/`,安装到 profile 后仅需普通 Node ≥ 20 ESM。
-
-## 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` 路径时自动使用。
-
-## 配置(环境变量,与 agent 无关)
-
-```bash
-# 远程部署(DeepTutor 在服务器上,通过 SSH 隧道访问)
-export DEEPTUTOR_SSH_HOST="tencent-cloud"           # SSH 主机别名(设置 = 远程模式)
-export DEEPTUTOR_API_BASE="http://127.0.0.1:8001"   # 本地隧道地址
-export DEEPTUTOR_REMOTE_BIN="/home/ubuntu/my-deeptutor/.venv/bin/deeptutor"
-export DEEPTUTOR_REMOTE_HOME="/home/ubuntu/my-deeptutor"
-
-# 本地部署 —— 不要设置 DEEPTUTOR_SSH_HOST
-# export DEEPTUTOR_API_BASE="http://127.0.0.1:8001"  # 本地 serve 端口
-# export DEEPTUTOR_LOCAL_BIN="deeptutor"             # 本地 CLI 路径(默认: PATH 上的 deeptutor)
-```
-
-修改环境变量后需重启 dsh。
-
-## 目录结构
-
-```
-src/                 # TypeScript 源码(开发加载、类型检查)
-lib/                 # 编译产物(发布入口,由 npm run build 生成)
-scripts/md-to-html.js  # 零依赖 Markdown → HTML 转换器
-cordis.yml           # 开发 overlay:按绝对路径插入 src/index.ts
-cordis.patch.yml     # bundle patch:按包名插入插件
-```
-
-`src/index.ts` 注册工具;`config.ts` 环境配置;`cli-exec.ts` 本地/SSH CLI 执行;`http-api.ts` API 探测 + SSH 隧道;`turn.ts` 单次学习回合(WebSocket / CLI 事件折叠与格式化);`html-render.ts` 答案 → 自包含 HTML。
+# dsh-deeptutor
+
+[English](https://github.com/TecFancy/dsh-deeptutor/blob/main/README.md) | **简体中文**
+
+面向 **DeepSeek Harness (dsh)** 的 DeepTutor 桥接 **bundle**,从 pi 编码 agent 扩展迁移而来(`TecFancy/pi-extensions`,`extensions/deeptutor` + `skills/deeptutor`)。
+
+注册三个模型可见工具,驱动 [HKUDS/DeepTutor](https://github.com/HKUDS/DeepTutor) 辅导服务:
+
+| 工具 | 用途 |
+|---|---|
+| `deeptutor_run` | 运行学习能力: `deep_solve` / `deep_question` / `deep_research` / `chat` / `mastery_path` / `visualize` / `math_animator`(优先 HTTP/WS,CLI 回退) |
+| `deeptutor_kb` | 列出 / 搜索 / 查看个人知识库(RAG)信息 |
+| `deeptutor_note` | 将 Markdown 学习笔记归档到服务端 notebook |
+
+上表 7 个 capability 是 `deeptutor_run` 工具接受的固定枚举。底层 DeepTutor CLI 可能支持更多命令——用 `deeptutor --help` / `deeptutor <cmd> --help` 可枚举完整命令集。`deeptutor` skill 会指示 agent 用这种方式动态发现命令;当工具的枚举未覆盖某能力时,agent 可直接调用 CLI(本地二进制或经 SSH)来驱动。
+
+部署模式自动适配:本机本地 `serve`(或本地 CLI),或通过自动建立的 SSH 隧道访问服务器(含 SSH CLI 回退)。
+
+## 安装到 profile(bundle 方式)
+
+包已发布到 npm(`dsh-deeptutor`)。推荐一条命令——运行随包发布的安装器(`scripts/install-profile.mjs`,以 `dsh-deeptutor` 二进制暴露),它包装 `dsh plugin add` 并自动处理下文所述的 pnpm workspace-root 检查:
+
+```sh
+pnpm dlx dsh-deeptutor --profile web
+```
+
+从本仓库检出目录运行同一个安装器:
+
+```sh
+node scripts/install-profile.mjs --profile web
+```
+
+或者自己执行底层命令:`dsh plugin add` 会转发给 pnpm 安装依赖,并把 profile 的 `dsh.profile.bundles` 与已安装状态对账,因此声明了 `dsh.bundle` 的包(如本插件)会被自动登记(已在 dsh CLI 0.1.0-rc.6 + pnpm 8.15.6 上验证):
+
+```sh
+dsh plugin --profile web add dsh-deeptutor -w
+```
+
+> **坑:pnpm workspace-root 检查。** dsh 的 profile 脚手架**总是**写入 `pnpm-workspace.yaml`(`packages: ["."]`、`nodeLinker: hoisted`),profile 目录本身就是 pnpm workspace 根。在 pnpm ≥ 8 上,`pnpm add` 在 workspace 根目录执行会因 `ERR_PNPM_ADDING_TO_ROOT` 中止,必须显式加 workspace-root 标志,所以上面的命令追加了 `-w`/`--workspace-root`(注意:Windows 上 pnpm 把这条错误打在 **stdout**,看起来像警告,实际是失败)。两种处理方式:
+>
+> 1. 使用安装器 / 命令保留 `-w`(推荐——安装器先试裸命令,只有检查触发时才自动补 `-w`)。
+> 2. 或者永久放行裸命令:在 `~/.dsh/profiles/<name>/pnpm-workspace.yaml` 中加入 `ignore-workspace-root-check: true`,之后 `dsh plugin --profile web add dsh-deeptutor` 按原样即可。
+
+验证挂载,然后重启 dsh(bundle 列表在启动时解析):
+
+```sh
+dsh --profile web --dump-config | grep dsh-deeptutor
+```
+
+如果你的 dsh CLI 不会自动登记 bundle(旧版本,或手动安装依赖),请在 profile 清单(`~/.dsh/profiles/<name>/package.json`)中手动加入,再运行 `dsh plugin --profile web install`:
+
+```json
+{
+  "dependencies": { "dsh-deeptutor": "^0.1.0" },
+  "dsh": {
+    "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-deeptutor"] }
+  }
+}
+```
+
+也可以不动清单,改用用户 patch 层挂载 bundle(仍需先安装 npm 包):
+
+```yaml
+# overlay.yml —— 通过用户 patch 层插入 bundle 行
+- insert:
+    - id: dsh-deeptutor
+      name: 'dsh-deeptutor'
+```
+
+```sh
+dsh web --patch ./overlay.yml
+```
+
+bundle 清单(`dsh.bundle.patch → cordis.patch.yml`)负责插入插件行;上层 patch 层可按 id 覆盖或禁用。
+
+## 源码开发(无需发布)
+
+```sh
+dsh web --patch /path/to/dsh-deeptutor/cordis.yml
+```
+
+## 构建与发布
+
+```sh
+npm install
+npm run build        # tsc → lib/(相对 .ts import 改写为 .js)
+npm run typecheck
+npm pack             # 检查 dsh-deeptutor-0.1.0.tgz
+npm publish
+```
+
+通过 `--patch` 直接加载 `src/*.ts` 需要 Node ≥ 22.6(type stripping);发布的 bundle 自带编译后的 `lib/`,安装到 profile 后仅需普通 Node ≥ 20 ESM。
+
+## Skills
+
+本包携带两个 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 无关)
+
+```bash
+# 远程部署(DeepTutor 在服务器上,通过 SSH 隧道访问)
+export DEEPTUTOR_SSH_HOST="tencent-cloud"           # SSH 主机别名(设置 = 远程模式)
+export DEEPTUTOR_API_BASE="http://127.0.0.1:8001"   # 本地隧道地址
+export DEEPTUTOR_REMOTE_BIN="/home/ubuntu/my-deeptutor/.venv/bin/deeptutor"
+export DEEPTUTOR_REMOTE_HOME="/home/ubuntu/my-deeptutor"
+
+# 本地部署 —— 不要设置 DEEPTUTOR_SSH_HOST
+# export DEEPTUTOR_API_BASE="http://127.0.0.1:8001"  # 本地 serve 端口
+# export DEEPTUTOR_LOCAL_BIN="deeptutor"             # 本地 CLI 路径(默认: PATH 上的 deeptutor)
+```
+
+修改环境变量后需重启 dsh。
+
+## 目录结构
+
+```
+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:按包名插入插件
+```
+
+`src/index.ts` 注册工具;`config.ts` 环境配置;`cli-exec.ts` 本地/SSH CLI 执行;`http-api.ts` API 探测 + SSH 隧道;`turn.ts` 单次学习回合(WebSocket / CLI 事件折叠与格式化);`html-render.ts` 答案 → 自包含 HTML。

package/cordis.patch.yml

@@ -1,17 +1,17 @@
-# dsh-deeptutor bundle patch: inserts the DeepTutor bridge plugin.
-#
-# Mount into a profile either by adding "dsh-deeptutor" to the profile's
-# `dsh.profile.bundles` list (recommended), or by inserting the same row
-# through a user patch layer:
-#
-#   - insert:
-#       - id: dsh-deeptutor
-#         name: 'dsh-deeptutor'
-#
-# The `name` is the npm package itself; the loader resolves it from the
-# profile's node_modules (installed via `dsh plugin` or the profile's own
-# package manager).
-
-- insert:
-    - id: dsh-deeptutor
-      name: 'dsh-deeptutor'
+# dsh-deeptutor bundle patch: inserts the DeepTutor bridge plugin.
+#
+# Mount into a profile either by adding "dsh-deeptutor" to the profile's
+# `dsh.profile.bundles` list (recommended), or by inserting the same row
+# through a user patch layer:
+#
+#   - insert:
+#       - id: dsh-deeptutor
+#         name: 'dsh-deeptutor'
+#
+# The `name` is the npm package itself; the loader resolves it from the
+# profile's node_modules (installed via `dsh plugin` or the profile's own
+# package manager).
+
+- insert:
+    - id: dsh-deeptutor
+      name: 'dsh-deeptutor'