dsh-deeptutor 0.1.9 → 0.1.11

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

@@ -54,8 +54,12 @@ study page, then archived to a notebook):
 
 ## Requirements
 
-- A working DeepSeek Harness (dsh) install. Bundle auto-registration via
-  `dsh plugin add` is verified on dsh CLI 0.1.0-rc.6 + pnpm 8.15.6.
+- A working DeepSeek Harness (dsh) install, 0.1.0-rc.6 or newer. The manifest
+  declares a version floor rather than a ceiling, so a new dsh release is never
+  refused at install time; a scheduled probe boots the plugin against the
+  current npm `latest` and `next` hosts instead and opens an issue when
+  activation breaks. Bundle auto-registration via `dsh plugin add` was verified
+  on dsh CLI 0.1.0-rc.6, 0.2.1-rc.2 and 0.2.1-rc.3.
 - A DeepTutor deployment, either:
   - **Local** — `deeptutor serve` running on this machine, or the `deeptutor`
     CLI on `PATH` (used as fallback);
@@ -146,8 +150,8 @@ row; later patch layers can override or disable it by id.
 
 ## 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:
 
@@ -159,9 +163,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)
 
@@ -215,7 +220,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

@@ -39,7 +39,7 @@
 
 ## 环境要求
 
-- 可用的 DeepSeek Harness (dsh) 安装。`dsh plugin add` 自动登记 bundle 已在 dsh CLI 0.1.0-rc.6 + pnpm 8.15.6 上验证。
+- 可用的 DeepSeek Harness (dsh) 安装,0.1.0-rc.6 或更新版本。清单里只写下限不写上限,新版本 dsh 发布后不会再在安装时被拒绝;替代办法是定时拿 npm 上 `latest` 和 `next` 两个通道的宿主各冷启动一次,插件起不来就开 issue。`dsh plugin add` 自动登记 bundle 已在 dsh CLI 0.1.0-rc.6、0.2.1-rc.2 与 0.2.1-rc.3 上验证。
 - 一个 DeepTutor 部署,二选一:
   - **本地** —— 本机运行 `deeptutor serve`,或 PATH 上有 `deeptutor` CLI(作为回退);
   - **远程** —— DeepTutor 在服务器上,通过自动建立的 SSH 隧道访问(含 SSH CLI 回退)。
@@ -103,7 +103,7 @@ bundle 清单(`dsh.bundle.patch → cordis.patch.yml`)负责插入插件行;上
 
 ## 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`)
@@ -158,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,6 +1,6 @@
 {
   "name": "dsh-deeptutor",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "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",
@@ -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"
   },
   "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,7 @@
     "lib",
     "src",
     "scripts",
-    "skills",
+    ".agents/skills",
     "docs",
     "cordis.patch.yml",
     "README.md",
@@ -64,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"
   },
   "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/check-dsh-compat.mjs

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+/**
+ * Boot-verify dsh-deeptutor against the `dsh` on PATH.
+ *
+ * Why this exists: the manifest no longer caps the supported dsh line (that is
+ * what issue #5 was about), so the compatibility gate is replaced by this
+ * probe. The scheduled `dsh-compat` workflow runs it against the npm `latest`
+ * and `next` releases; run it by hand after a dsh upgrade as well.
+ *
+ * What it does, against a throwaway DSH_HOME:
+ *   1. packs this repository (prepack builds + typechecks) unless --spec is given;
+ *   2. installs the package into a fresh `compat` profile;
+ *   3. cold-boots that profile with a dead model endpoint;
+ *   4. asserts the plugin activated (no `did not activate` / import failure).
+ *
+ * Usage:
+ *   node scripts/check-dsh-compat.mjs [--spec <dir|tarball|npm-spec>] [--timeout 60]
+ *                                     [--dsh-bin dsh] [--json] [--keep-workspace]
+ *
+ * Exit codes: 0 = the plugin activated, 1 = it did not, 2 = inconclusive.
+ * The probe only reads and writes inside its own temporary DSH_HOME.
+ */
+import { spawnSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = resolve(fileURLToPath(new URL("..", import.meta.url)));
+const argv = process.argv.slice(2);
+
+function option(name, fallback) {
+  const index = argv.indexOf(name);
+  return index >= 0 && index + 1 < argv.length ? argv[index + 1] : fallback;
+}
+
+const dshBin = option("--dsh-bin", process.platform === "win32" ? "dsh.cmd" : "dsh");
+const npmBin = process.platform === "win32" ? "npm.cmd" : "npm";
+const timeoutSeconds = Number(option("--timeout", "60"));
+const jsonOutput = argv.includes("--json");
+const keepWorkspace = argv.includes("--keep-workspace");
+const specArgument = option("--spec", undefined);
+
+const PROFILE = "compat";
+const FAILURE = /did not activate|failed to import|plugin tree failed to load|Cannot find module|ERR_MODULE_NOT_FOUND/i;
+const ACTIVATED = /\[dsh-deeptutor\] plugin loaded/;
+
+function run(command, args, options = {}) {
+  return spawnSync(command, args, {
+    encoding: "utf8",
+    timeout: (options.timeoutSeconds ?? 180) * 1000,
+    killSignal: "SIGKILL",
+    input: "",
+    cwd: options.cwd ?? repoRoot,
+    env: { ...process.env, ...(options.env ?? {}) },
+  });
+}
+
+function tail(text, lines = 25) {
+  return String(text ?? "")
+    .trimEnd()
+    .split("\n")
+    .slice(-lines)
+    .join("\n");
+}
+
+/** The model/patch layer the boot probe needs: a real model name behind a dead port. */
+function writeProbePatch(profileDir) {
+  mkdirSync(profileDir, { recursive: true });
+  writeFileSync(
+    join(profileDir, "cordis.patch.yml"),
+    [
+      "# generated by scripts/check-dsh-compat.mjs — real model name behind a dead endpoint",
+      "- id: llm-compat",
+      "  config:",
+      "    models:",
+      "      - id: Qwen3.6-35B",
+      "        contextWindow: 262144",
+      "        maxTokens: 8192",
+      "- id: agent-default-model",
+      "  config:",
+      "    provider: deepseek-official",
+      "    model: Qwen3.6-35B",
+      "- id: \"@deepseek-ai/cordis-plugin-hmr\"",
+      "  disabled: true",
+      "",
+    ].join("\n"),
+  );
+}
+
+function main() {
+  const dshVersionProbe = run(dshBin, ["--version"], { timeoutSeconds: 30 });
+  if (dshVersionProbe.error !== undefined || dshVersionProbe.status !== 0) {
+    return {
+      verdict: "inconclusive",
+      stage: "dsh-version",
+      detail: `${dshBin} is not runnable: ${String(dshVersionProbe.error ?? dshVersionProbe.stderr)}`.trim(),
+      exitCode: 2,
+    };
+  }
+  const dshVersion = String(dshVersionProbe.stdout ?? "").trim().split("\n").pop() ?? "unknown";
+
+  const workspace = mkdtempSync(join(tmpdir(), "dsh-compat-"));
+  const dshHome = join(workspace, ".dsh");
+  const env = { DSH_HOME: dshHome };
+  const cleanup = () => {
+    if (!keepWorkspace) rmSync(workspace, { recursive: true, force: true });
+  };
+
+  try {
+    let spec = specArgument;
+    if (spec === undefined) {
+      // --cache: keep npm state inside the probe workspace, so a read-only or
+      // root-owned npm cache on the caller's machine cannot fail the probe.
+      const packed = run(npmBin, ["pack", "--pack-destination", workspace, "--cache", join(workspace, "npm-cache")], { timeoutSeconds: 300 });
+      if (packed.status !== 0) {
+        return { verdict: "inconclusive", stage: "pack", detail: tail(`${packed.stdout}\n${packed.stderr}`), exitCode: 2 };
+      }
+      const tarball = readdirSync(workspace).find((name) => name.endsWith(".tgz"));
+      if (tarball === undefined) {
+        return { verdict: "inconclusive", stage: "pack", detail: "npm pack produced no tarball", exitCode: 2 };
+      }
+      spec = join(workspace, tarball);
+    }
+
+    writeProbePatch(join(dshHome, "profiles", PROFILE));
+
+    // `-w`: dsh profiles are single-package pnpm workspaces and pnpm refuses
+    // to add to a workspace root without it (observed on pnpm 9 + dsh 0.2.1).
+    // Isolated pnpm store: a machine-wide store (store-dir in ~/.npmrc) can be
+    // read-only for this user, which would look like an install failure.
+    const install = run(
+      dshBin,
+      ["plugin", "--profile", PROFILE, "add", "-w", `--store-dir=${join(workspace, "pnpm-store")}`, spec],
+      { timeoutSeconds: 300, env },
+    );
+    if (install.status !== 0) {
+      return {
+        verdict: "fail",
+        stage: "install",
+        detail: tail(`${install.stdout}\n${install.stderr}`),
+        exitCode: 1,
+      };
+    }
+
+    const boot = run(dshBin, ["--profile", PROFILE, "ok"], {
+      timeoutSeconds,
+      env: {
+        ...env,
+        DEEPSEEK_BASE_URL: "http://127.0.0.1:9",
+        DEEPSEEK_API_KEY: "sk-compat-probe-000000000000000000000000",
+        DSH_PERMISSION_MODE: "danger-full-access",
+      },
+      cwd: dshHome,
+    });
+    const log = `${boot.stdout ?? ""}\n${boot.stderr ?? ""}`;
+    const timedOut = boot.error?.code === "ETIMEDOUT";
+    const failure = log.match(FAILURE);
+    if (failure !== null) {
+      return { verdict: "fail", stage: "boot", detail: tail(log), signature: failure[0], exitCode: 1 };
+    }
+    if (log.match(ACTIVATED) !== null) {
+      return { verdict: "pass", stage: "boot", detail: "plugin activation marker seen", exitCode: 0 };
+    }
+    if (timedOut) {
+      return { verdict: "pass", stage: "boot", detail: "boot stayed alive through the probe window without a failure signature", exitCode: 0 };
+    }
+    return { verdict: "inconclusive", stage: "boot", detail: tail(log), exitCode: 2 };
+  } finally {
+    cleanup();
+  }
+}
+
+const result = main();
+const versionProbe = run(dshBin, ["--version"], { timeoutSeconds: 30 });
+const report = {
+  dshBin,
+  dshVersion: String(versionProbe.stdout ?? "").trim().split("\n").pop() ?? "unavailable",
+  spec: specArgument ?? "(packed from the repository)",
+  ...result,
+};
+
+if (jsonOutput) {
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+} else {
+  const label = report.verdict === "pass" ? "PASS" : report.verdict === "fail" ? "FAIL" : "INCONCLUSIVE";
+  process.stdout.write(`[dsh-compat] ${label} · dsh ${report.dshVersion} · stage ${report.stage}\n`);
+  if (report.detail !== undefined && report.detail !== "") process.stdout.write(`${report.detail}\n`);
+  if (keepWorkspace) process.stdout.write(`[dsh-compat] workspace kept\n`);
+}
+process.exit(report.exitCode);

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";