dsh-deeptutor 0.1.8 → 0.1.10

package/{skills → .agents/skills}/html-doc/scripts/md-to-html.js

@@ -349,11 +349,11 @@ function main() {
       : "";
 
   const generated = new Date().toISOString().slice(0, 10);
-  // The same converter ships in two locations (skills/html-doc/scripts/ and a
-  // package-root scripts/ copy); resolve the template wherever we are.
+  // The same converter ships in two locations (.agents/skills/html-doc/scripts/
+  // and a package-root scripts/ copy); resolve the template wherever we are.
   const templateCandidates = [
     path.join(import.meta.dirname, "..", "assets", "template.html"),
-    path.join(import.meta.dirname, "..", "skills", "html-doc", "assets", "template.html"),
+    path.join(import.meta.dirname, "..", ".agents", "skills", "html-doc", "assets", "template.html"),
   ];
   const templatePath = templateCandidates.find((p) => fs.existsSync(p));
   if (!templatePath) {

package/README.md

@@ -2,18 +2,28 @@
 
 **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`).
+A **learning-assistant extension for DeepSeek Harness (dsh)**. It connects your
+agent to a [HKUDS/DeepTutor](https://github.com/HKUDS/DeepTutor) tutoring
+service, so a dsh session can explain topics in depth, quiz you, plan learning
+paths, search your personal knowledge bases, and keep a study notebook — all
+without leaving the harness.
 
-Registers three model-facing tools that drive the
-[HKUDS/DeepTutor](https://github.com/HKUDS/DeepTutor) tutoring service:
+Ask the agent *"teach me async/await"* and it can run a deep-solve, render the
+answer as a self-contained HTML study page you can open in a browser, and
+archive a summary into your notebook.
 
-| Tool | Purpose |
+Migrated from the pi coding-agent extension
+(`TecFancy/pi-extensions`, `extensions/deeptutor` + `skills/deeptutor`).
+
+## What it adds
+
+Three agent-facing tools that the model uses whenever you ask for learning help:
+
+| Tool | What it does |
 |---|---|
-| `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 |
+| `deeptutor_run` | Runs one learning capability: `deep_solve` (in-depth explanation), `deep_question` (self-test questions), `deep_research`, `chat`, `mastery_path` (learning-path planning), `visualize` / `math_animator` (visualization). Can mount your knowledge bases (`kbs`) and tools (`rag`, `web_search`, `reason`, `code_execution`, …); returns a `session_id` so later turns continue the same context. |
+| `deeptutor_kb` | Lists, searches, and inspects your personal knowledge bases (RAG) |
+| `deeptutor_note` | Archives Markdown study notes (plans, summaries, wrong answers) into 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
@@ -22,9 +32,37 @@ 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).
+## Example session
+
+A typical flow when you ask your agent for learning help:
+
+1. **Ask** — *"Explain C# generics covariance using my dotnet knowledge base, and generate a study page."*
+2. The agent grounds the answer in your own material: `deeptutor_kb` (`action=search`, `kb=dotnet`).
+3. It runs a deep-solve: `deeptutor_run` (`capability=deep_solve`, `kbs=[dotnet]`, `html=data/study/csharp-covariance.html`) — the answer comes back and a self-contained HTML page (plus the `.md` source) is written to disk.
+4. It files a summary: `deeptutor_note` (`notebook=dotnet-learning`, `type=solve`).
+
+Nothing here is a fixed script — the agent picks the tools and parameters based
+on what you ask for.
+
+A real recording of exactly this flow (deep-solve on the async/await state
+machine, mounted on a `dotnet-csharp` knowledge base, rendered to an HTML
+study page, then archived to a notebook):
+
+![Final answer](docs/demo/en-final-answer.png)
+
+![Generated HTML study page](docs/demo/en-study-page.png)
+
+## Requirements
+
+- A working DeepSeek Harness (dsh) install, 0.1.0-rc.6 or any 0.2.x release
+  (compatibility re-verified on dsh 0.2.1-rc.2 / 0.2.1-rc.3). Bundle
+  auto-registration via `dsh plugin add` is verified on dsh CLI 0.1.0-rc.6 +
+  pnpm 8.15.6.
+- A DeepTutor deployment, either:
+  - **Local** — `deeptutor serve` running on this machine, or the `deeptutor`
+    CLI on `PATH` (used as fallback);
+  - **Remote** — DeepTutor on a server, reached through an auto-started SSH
+    tunnel (with SSH CLI fallback).
 
 ## Install into a profile (bundle)
 
@@ -46,7 +84,7 @@ 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):
+automatically:
 
 ```sh
 dsh plugin --profile web add dsh-deeptutor -w
@@ -108,30 +146,10 @@ 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
+Two skills ship inside this package (`.agents/skills/deeptutor` and
+`.agents/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:
 
@@ -143,9 +161,10 @@ Two skills ship inside this package (`skills/deeptutor` and
 Installing a newer package version overwrites skill files in place; files not
 shipped by the package are never deleted.
 
-The files under `skills/` are byte-identical copies of the same skills in
-`TecFancy/pi-extensions` (single source of truth, agent-neutral). Sync them
-after upstream edits with `node scripts/sync-skills.mjs ../pi-extensions`.
+The files under `.agents/skills/` are byte-identical copies of the same
+skills in `TecFancy/pi-extensions` (single source of truth, agent-neutral).
+Sync them after upstream edits with
+`node scripts/sync-skills.mjs ../pi-extensions`.
 
 ## Configuration (env vars, agent-agnostic)
 
@@ -163,6 +182,35 @@ export DEEPTUTOR_REMOTE_HOME="/home/ubuntu/my-deeptutor"
 
 Restart dsh after changing env vars.
 
+## How it works
+
+The plugin auto-detects the deployment: if a DeepTutor API is reachable (local
+`serve`, or a remote server via tunnel), learning turns run over HTTP/WebSocket;
+otherwise it falls back to the CLI — the local `deeptutor` binary, or the remote
+binary over SSH. Remote mode starts the SSH tunnel on demand and tears it down
+when the plugin unloads.
+
+## 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 test             # node:test + type stripping
+npm pack             # inspect dsh-deeptutor-<version>.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.
+
 ## Layout
 
 ```
@@ -170,7 +218,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/)
+.agents/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

@@ -2,23 +2,51 @@
 
 [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`)。
+面向 **DeepSeek Harness (dsh)** 的**学习辅助扩展**。它将 [HKUDS/DeepTutor](https://github.com/HKUDS/DeepTutor) 辅导服务接入你的 agent,让 dsh 会话能够深度讲解知识点、出题自测、规划学习路径、检索你的个人知识库,并把学习笔记归档到 notebook —— 全程不出 harness。
 
-注册三个模型可见工具,驱动 [HKUDS/DeepTutor](https://github.com/HKUDS/DeepTutor) 辅导服务:
+只要对 agent 说 *"给我讲讲 async/await"*,它就能跑一次 deep-solve,把答案渲染成可在浏览器打开的自包含 HTML 学习页,再把摘要归档进你的笔记本。
 
-| 工具 | 用途 |
+本扩展由 pi 编码 agent 扩展迁移而来(`TecFancy/pi-extensions`,`extensions/deeptutor` + `skills/deeptutor`)。
+
+## 它带来什么
+
+三个 agent 可见工具,当你请求学习帮助时由模型调用:
+
+| 工具 | 作用 |
 |---|---|
-| `deeptutor_run` | 运行学习能力: `deep_solve` / `deep_question` / `deep_research` / `chat` / `mastery_path` / `visualize` / `math_animator`(优先 HTTP/WS,CLI 回退) |
-| `deeptutor_kb` | 列出 / 搜索 / 查看个人知识库(RAG)信息 |
-| `deeptutor_note` | 将 Markdown 学习笔记归档到服务端 notebook |
+| `deeptutor_run` | 执行一次学习调用: `deep_solve`(深度讲解)/ `deep_question`(自测题)/ `deep_research` / `chat` / `mastery_path`(学习路径规划)/ `visualize` / `math_animator`(可视化)。可挂载你的知识库(`kbs`)与工具(`rag`、`web_search`、`reason`、`code_execution` 等);返回 `session_id`,后续轮次可延续同一上下文。 |
+| `deeptutor_kb` | 列出 / 搜索 / 查看你的个人知识库(RAG) |
+| `deeptutor_note` | 把 Markdown 学习笔记(计划、总结、错题等)归档到服务器 notebook |
+
+上表 7 个 capability 是 `deeptutor_run` 工具接受的固定枚举。底层 DeepTutor CLI 可能支持更多命令 —— 用 `deeptutor --help` / `deeptutor <cmd> --help` 可枚举完整命令集。`deeptutor` skill 会指示 agent 以这种方式动态发现命令;当工具的枚举未覆盖某能力时,agent 可直接调用 CLI(本地二进制或经 SSH)来驱动。
+
+## 示例会话
+
+一次典型的"求学习帮助"流程:
 
-上表 7 个 capability 是 `deeptutor_run` 工具接受的固定枚举。底层 DeepTutor CLI 可能支持更多命令——用 `deeptutor --help` / `deeptutor <cmd> --help` 可枚举完整命令集。`deeptutor` skill 会指示 agent 用这种方式动态发现命令;当工具的枚举未覆盖某能力时,agent 可直接调用 CLI(本地二进制或经 SSH)来驱动。
+1. **提问** —— *"用我的 dotnet 知识库讲讲 C# 泛型协变,并生成学习页。"*
+2. agent 先检索你的自有资料:`deeptutor_kb`(`action=search`,`kb=dotnet`)。
+3. 再执行深度讲解:`deeptutor_run`(`capability=deep_solve`,`kbs=[dotnet]`,`html=data/study/csharp-covariance.html`)—— 答案返回的同时,自包含 HTML 学习页(及配套 `.md` 源文件)写入磁盘。
+4. 最后归档摘要:`deeptutor_note`(`notebook=dotnet-learning`,`type=solve`)。
 
-部署模式自动适配:本机本地 `serve`(或本地 CLI),或通过自动建立的 SSH 隧道访问服务器(含 SSH CLI 回退)。
+以上不是固定脚本 —— agent 会根据你的提问自由选择工具与参数。
+
+以下是该流程的真实录制(async/await 状态机 deep-solve,挂载 `dotnet-csharp` 知识库,渲染 HTML 学习页,归档笔记本):
+
+![最终答复](docs/demo/final-answer.png)
+
+![生成的 HTML 学习页](docs/demo/study-page.png)
+
+## 环境要求
+
+- 可用的 DeepSeek Harness (dsh) 安装,0.1.0-rc.6 或任意 0.2.x 版本(已在 dsh 0.2.1-rc.2 / 0.2.1-rc.3 上重新验证兼容性)。`dsh plugin add` 自动登记 bundle 已在 dsh CLI 0.1.0-rc.6 + pnpm 8.15.6 上验证。
+- 一个 DeepTutor 部署,二选一:
+  - **本地** —— 本机运行 `deeptutor serve`,或 PATH 上有 `deeptutor` CLI(作为回退);
+  - **远程** —— DeepTutor 在服务器上,通过自动建立的 SSH 隧道访问(含 SSH CLI 回退)。
 
 ## 安装到 profile(bundle 方式)
 
-包已发布到 npm(`dsh-deeptutor`)。推荐一条命令——运行随包发布的安装器(`scripts/install-profile.mjs`,以 `dsh-deeptutor` 二进制暴露),它包装 `dsh plugin add` 并自动处理下文所述的 pnpm workspace-root 检查:
+包已发布到 npm(`dsh-deeptutor`)。推荐一条命令 —— 运行随包发布的安装器(`scripts/install-profile.mjs`,以 `dsh-deeptutor` 二进制暴露),它包装 `dsh plugin add` 并自动处理下文所述的 pnpm workspace-root 检查:
 
 ```sh
 pnpm dlx dsh-deeptutor --profile web
@@ -30,7 +58,7 @@ pnpm dlx dsh-deeptutor --profile web
 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 上验证):
+或者自己执行底层命令:`dsh plugin add` 会转发给 pnpm 安装依赖,并把 profile 的 `dsh.profile.bundles` 与已安装状态对账,因此声明了 `dsh.bundle` 的包(如本插件)会被自动登记:
 
 ```sh
 dsh plugin --profile web add dsh-deeptutor -w
@@ -38,7 +66,7 @@ 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`)。
+> 1. 使用安装器 / 命令保留 `-w`(推荐 —— 安装器先试裸命令,只有检查触发时才自动补 `-w`)。
 > 2. 或者永久放行裸命令:在 `~/.dsh/profiles/<name>/pnpm-workspace.yaml` 中加入 `ignore-workspace-root-check: true`,之后 `dsh plugin --profile web add dsh-deeptutor` 按原样即可。
 
 验证挂载,然后重启 dsh(bundle 列表在启动时解析):
@@ -73,27 +101,9 @@ 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:
+本包携带两个 skill(`.agents/skills/deeptutor` 与 `.agents/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`)
@@ -118,6 +128,29 @@ export DEEPTUTOR_REMOTE_HOME="/home/ubuntu/my-deeptutor"
 
 修改环境变量后需重启 dsh。
 
+## 工作原理
+
+插件自动适配部署模式:若 DeepTutor API 可达(本地 `serve`,或经隧道的远程服务器),学习回合走 HTTP/WebSocket;否则回退到 CLI —— 本地的 `deeptutor` 二进制,或经 SSH 的远程二进制。远程模式按需启动 SSH 隧道,插件卸载时自动拆除。
+
+## 源码开发(无需发布)
+
+```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 test             # node:test + type stripping
+npm pack             # 检查 dsh-deeptutor-<version>.tgz
+npm publish
+```
+
+通过 `--patch` 直接加载 `src/*.ts` 需要 Node ≥ 22.6(type stripping);发布的 bundle 自带编译后的 `lib/`,安装到 profile 后仅需普通 Node ≥ 20 ESM。
+
 ## 目录结构
 
 ```
@@ -125,7 +158,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/)
+.agents/skills/       # 随包 skill:deeptutor/ + html-doc/(安装到 <DSH_HOME>/skills/)
 cordis.yml           # 开发 overlay:按绝对路径插入 src/index.ts
 cordis.patch.yml     # bundle patch:按包名插入插件
 ```

package/lib/index.d.ts

@@ -14,7 +14,8 @@
  *     automatically to reach the API; if the tunnel is unavailable, falls back to the SSH CLI.
  *
  * Env config (agent-agnostic): DEEPTUTOR_SSH_HOST / DEEPTUTOR_API_BASE / DEEPTUTOR_LOCAL_BIN /
- * DEEPTUTOR_REMOTE_BIN / DEEPTUTOR_REMOTE_HOME — see src/config.ts and skills/deeptutor/SKILL.md.
+ * DEEPTUTOR_REMOTE_BIN / DEEPTUTOR_REMOTE_HOME — see src/config.ts and
+ * .agents/skills/deeptutor/SKILL.md.
  */
 import type { Context } from "@deepseek-ai/cordis";
 export declare const name = "dsh-deeptutor";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-deeptutor",
-  "version": "0.1.8",
-  "description": "DeepTutor bridge bundle for DeepSeek Harness: learning capabilities, knowledge bases, and note archiving (HTTP/WS first, CLI fallback; auto-adapts local/remote deployment).",
+  "version": "0.1.10",
+  "description": "Learning assistant extension for DeepSeek Harness (dsh): DeepTutor tutoring for your agent — deep explanations, self-test questions, learning paths, personal knowledge-base search (RAG), and note archiving (HTTP/WS first, CLI fallback; auto-adapts local/remote deployment).",
   "keywords": [
     "dsh",
     "dsh-plugin",
@@ -21,7 +21,8 @@
     "url": "https://github.com/TecFancy/dsh-deeptutor/issues"
   },
   "engines": {
-    "node": ">=20.11"
+    "node": ">=20.11",
+    "dsh": "^0.1.0-rc.6 || ^0.2.0-rc.1"
   },
   "type": "module",
   "main": "./lib/index.js",
@@ -36,7 +37,7 @@
     },
     "./cordis.patch.yml": "./cordis.patch.yml",
     "./scripts/*": "./scripts/*",
-    "./skills/*": "./skills/*",
+    "./.agents/skills/*": "./.agents/skills/*",
     "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
@@ -44,7 +45,8 @@
     "lib",
     "src",
     "scripts",
-    "skills",
+    ".agents/skills",
+    "docs",
     "cordis.patch.yml",
     "README.md",
     "README.zh.md"
@@ -63,12 +65,14 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6 || ^0.2.0-rc.1 || ^0.2.1-rc.1"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
+    "@deepseek-ai/cordis": "^4.0.5",
+    "@deepseek-ai/dsh-tools": "^0.2.1-rc.3",
     "@types/node": "^24.0.0",
+    "@types/semver": "^7.8.0",
+    "semver": "^7.8.5",
     "typescript": "^5.9.3"
   }
 }

package/scripts/install-profile.mjs

@@ -20,7 +20,7 @@
  *   -h, --help             show this help
  *
  * Besides installing the bundle, the installer copies the package's bundled
- * skills (`skills/deeptutor`, `skills/html-doc`) into
+ * skills (`.agents/skills/deeptutor`, `.agents/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.
  */
@@ -33,7 +33,7 @@ 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 SKILLS_DIR = join(SCRIPT_DIR, '..', '.agents', 'skills');
 
 const USAGE = `usage: dsh-deeptutor [--profile <name>]
 
@@ -213,7 +213,7 @@ next steps:
  */
 function installSkills() {
   if (!existsSync(SKILLS_DIR)) {
-    console.error(`\n${NAME}: warning: no skills/ directory in this package — skill install skipped (old version?)`);
+    console.error(`\n${NAME}: warning: no .agents/skills/ directory in this package — skill install skipped (old version?)`);
     return '';
   }
   const dshHome = process.env.DSH_HOME || join(homedir(), '.dsh');

package/scripts/md-to-html.js

@@ -349,11 +349,11 @@ function main() {
       : "";
 
   const generated = new Date().toISOString().slice(0, 10);
-  // The same converter ships in two locations (skills/html-doc/scripts/ and a
-  // package-root scripts/ copy); resolve the template wherever we are.
+  // The same converter ships in two locations (.agents/skills/html-doc/scripts/
+  // and a package-root scripts/ copy); resolve the template wherever we are.
   const templateCandidates = [
     path.join(import.meta.dirname, "..", "assets", "template.html"),
-    path.join(import.meta.dirname, "..", "skills", "html-doc", "assets", "template.html"),
+    path.join(import.meta.dirname, "..", ".agents", "skills", "html-doc", "assets", "template.html"),
   ];
   const templatePath = templateCandidates.find((p) => fs.existsSync(p));
   if (!templatePath) {

package/scripts/sync-skills.mjs

@@ -16,14 +16,15 @@ const piRoot = resolve(process.argv[2] ?? join(here, "..", "pi-extensions"));
 
 // [pi source, this-repo destination]
 // The bundle uses the root scripts/ copy at runtime (src/html-render.ts);
-// the skill copy ships inside the package. Both must stay identical.
+// the skill copy ships inside the package under .agents/skills/. Both must
+// stay identical.
 const FILES = [
-  ["skills/deeptutor/SKILL.md", "skills/deeptutor/SKILL.md"],
-  ["skills/deeptutor/README.md", "skills/deeptutor/README.md"],
-  ["skills/html-doc/SKILL.md", "skills/html-doc/SKILL.md"],
-  ["skills/html-doc/assets/template.html", "skills/html-doc/assets/template.html"],
+  ["skills/deeptutor/SKILL.md", ".agents/skills/deeptutor/SKILL.md"],
+  ["skills/deeptutor/README.md", ".agents/skills/deeptutor/README.md"],
+  ["skills/html-doc/SKILL.md", ".agents/skills/html-doc/SKILL.md"],
+  ["skills/html-doc/assets/template.html", ".agents/skills/html-doc/assets/template.html"],
   ["skills/html-doc/scripts/md-to-html.js", "scripts/md-to-html.js"],
-  ["skills/html-doc/scripts/md-to-html.js", "skills/html-doc/scripts/md-to-html.js"],
+  ["skills/html-doc/scripts/md-to-html.js", ".agents/skills/html-doc/scripts/md-to-html.js"],
 ];
 
 let failures = 0;

package/src/index.ts

@@ -14,7 +14,8 @@
  *     automatically to reach the API; if the tunnel is unavailable, falls back to the SSH CLI.
  *
  * Env config (agent-agnostic): DEEPTUTOR_SSH_HOST / DEEPTUTOR_API_BASE / DEEPTUTOR_LOCAL_BIN /
- * DEEPTUTOR_REMOTE_BIN / DEEPTUTOR_REMOTE_HOME — see src/config.ts and skills/deeptutor/SKILL.md.
+ * DEEPTUTOR_REMOTE_BIN / DEEPTUTOR_REMOTE_HOME — see src/config.ts and
+ * .agents/skills/deeptutor/SKILL.md.
  */
 import type { Context } from "@deepseek-ai/cordis";
 import { defineTool } from "@deepseek-ai/dsh-tools";