dsh-deeptutor 0.1.11 → 0.2.1

package/.agents/skills/deeptutor/README.md

@@ -1,7 +1,7 @@
-# DeepTutor Learning Assistant (extension / bundle + SKILL)
+# DeepTutor Learning Assistant (dsh bundle + SKILL)
 
 > This README is the human-facing documentation; `SKILL.md` is the agent-facing instruction file (loaded on demand).
-> The same code ships in two ecosystems — edit in `pi-extensions` first, then sync to `dsh-deeptutor` (see Maintenance).
+> The bundle and this skill both live in `TecFancy/dsh-deeptutor`.
 
 Bridges **DeepTutor** (open-source personalized tutoring platform) into your
 agent: combines your **personal knowledge bases** (RAG retrieval) with
@@ -9,8 +9,8 @@ agent: combines your **personal knowledge bases** (RAG retrieval) with
 questions, and study plans — then archives your notes to a DeepTutor notebook
 for later review.
 
-- **pi** — extension `extensions/deeptutor/` (entry: `index.ts`) + skill `skills/deeptutor/SKILL.md` (repo: `TecFancy/pi-extensions`)
-- **dsh** — npm bundle `dsh-deeptutor` (the same TypeScript core) + the same skill, installed to `~/.dsh/skills/deeptutor/` (repo: `TecFancy/dsh-deeptutor`)
+Shipped as the npm bundle `dsh-deeptutor` for DeepSeek Harness (dsh); the
+installer also copies this skill to `~/.dsh/skills/deeptutor/`.
 
 ## Features
 
@@ -25,25 +25,13 @@ for later review.
 
 ## Installation
 
-### pi
-
-```bash
-# Install the pi package (extension + SKILL)
-pi install git:github.com/TecFancy/pi-extensions
-
-# Local development: /reload after editing (local path installs are not copied)
-pi install D:/source/personal/pi-extensions
-```
-
-### dsh
-
 ```bash
 # One-shot: bundle + skill, from the published package
 pnpm dlx dsh-deeptutor --profile web
 
 # Or install the skill manually from a checkout
-xcopy /e /i skills\deeptutor %USERPROFILE%\.dsh\skills\deeptutor   # Windows
-cp -r skills/deeptutor ~/.dsh/skills/deeptutor                     # macOS/Linux
+xcopy /e /i .agents\skills\deeptutor %USERPROFILE%\.dsh\skills\deeptutor   # Windows
+cp -r .agents/skills/deeptutor ~/.dsh/skills/deeptutor                     # macOS/Linux
 ```
 
 ## Configuration (environment variables)
@@ -51,9 +39,8 @@ cp -r skills/deeptutor ~/.dsh/skills/deeptutor                     # macOS/Linux
 Set these in `~/.bashrc` or `~/.zshrc` (inherited by any agent at startup — agent-agnostic):
 
 ```bash
-# —— Remote deployment (DeepTutor on a server, via SSH tunnel) ——
+# —— Remote deployment (DeepTutor on a server, driven over SSH) ——
 export DEEPTUTOR_SSH_HOST="tencent-cloud"           # SSH alias (set = remote mode)
-export DEEPTUTOR_API_BASE="http://127.0.0.1:8001"   # local tunnel address (change port here)
 export DEEPTUTOR_REMOTE_BIN="/home/ubuntu/my-deeptutor/.venv/bin/deeptutor"
 export DEEPTUTOR_REMOTE_HOME="/home/ubuntu/my-deeptutor"
 
@@ -62,7 +49,7 @@ export DEEPTUTOR_REMOTE_HOME="/home/ubuntu/my-deeptutor"
 # export DEEPTUTOR_HOME="/path/to/local-workspace"  # local workspace
 ```
 
-**Deployment auto-adapts**: API reachable (local serve or tunnel) → HTTP/WS; unreachable → local CLI or SSH CLI fallback.
+**How calls run**: the tools always drive the DeepTutor CLI — the local binary, or the remote one over SSH when `DEEPTUTOR_SSH_HOST` is set. `deeptutor serve` does not need to be reachable.
 
 ## Usage
 
@@ -93,37 +80,31 @@ The agent follows the SKILL workflow automatically:
 
 | Symptom                                         | Cause & fix                                                                                                                                                                        |
 | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Connection timeout / host resolution failure    | ① Check `DEEPTUTOR_SSH_HOST` is set and SSH passwordless login works ② Is `deeptutor serve` running? (`curl http://127.0.0.1:8001/api/v1/system/status`)                           |
+| Connection timeout / host resolution failure    | ① Check `DEEPTUTOR_SSH_HOST` is set and SSH passwordless login works ② Does the remote CLI run? (`ssh <alias> <DEEPTUTOR_REMOTE_BIN> kb list --format json`)                           |
 | Tool returns "No DEEPTUTOR_* env vars detected" | One-time hint on first call; configure per the Configuration section and restart the agent                                                                                         |
 | Local CLI garbled output / crashes              | The tools inject `PYTHONUTF8=1` automatically; verify Python ≥ 3.11 otherwise                                                                                                      |
 | DNS resolution fails (Windows)                  | Common on corporate networks: if `nslookup` works but curl/python can't resolve, fix `C:\Windows\System32\drivers\etc\hosts` (when appending entries, always start with a newline) |
 | CLI-only package missing modules                | Official `packaging/deeptutor-cli` has incomplete deps; `pip install <module>` per the error (known: loguru, fastapi)                                                              |
+| `No such command 'kb'` / capability unknown     | DeepTutor 1.7+ ships features as modules; check `deeptutor module list`, then `deeptutor module install <name>` (e.g. `knowledge`, `notebook`, `solve`)                           |
 
 ## FAQ
 
 **Q: Can local and remote be used at the same time?**
 A: Yes. Switching only requires changing env vars (set/remove `DEEPTUTOR_SSH_HOST`); the SKILL and tools stay unchanged.
 
-**Q: What if I change servers or ports?**
-A: Only env vars change (`DEEPTUTOR_SSH_HOST` / `DEEPTUTOR_API_BASE` / remote paths) — never the SKILL or tools.
+**Q: What if I change servers?**
+A: Only env vars change (`DEEPTUTOR_SSH_HOST` / remote paths) — never the SKILL or tools.
 
 **Q: Is the knowledge base list hardcoded?**
 A: No. Tools query `deeptutor_kb list` dynamically; new bases are picked up automatically.
 
 **Q: Can other agents (Claude Code / Codex) use it?**
-A: Yes. The SKILL follows the Agent Skills standard and can be linked into `~/.agents/skills/`; the `deeptutor_*` tools are registered by the pi extension or the dsh bundle.
+A: Yes. The SKILL follows the Agent Skills standard and can be linked into `~/.agents/skills/`; the `deeptutor_*` tools are registered by the dsh bundle; other agents use the plain CLI path described in the SKILL.
 
 ## Maintenance
 
-Shared skill files (`skills/deeptutor/*`, `skills/html-doc/*`) live **in this
-repo (pi-extensions)** and are kept agent-neutral. `dsh-deeptutor` ships
-byte-identical copies; after editing, sync with:
-
-```bash
-cd ../dsh-deeptutor && node scripts/sync-skills.mjs ../pi-extensions
-```
+The bundle code (`src/`) and this skill live in `TecFancy/dsh-deeptutor`; edit both there.
 
-- pi code: edit the relevant file under `extensions/deeptutor/` (`index.ts` for tool wiring, `cli-exec.ts`/`http-api.ts`/`turn.ts` for transport logic, `config.ts` for env vars/helpers) → `/reload` to verify
-- dsh code: same files under `dsh-deeptutor/src/` → rebuild with `npm run build`
-- Release pi: push a tag to GitHub, then `pi install git:github.com/TecFancy/pi-extensions@<tag>`
-- Release dsh: bump the version in `package.json`, push a `v*` tag → CI publishes to npm
+- Code: `src/index.ts` for tool wiring, `cli-exec.ts` / `turn.ts` for CLI execution, `config.ts` for env vars/helpers → `npm run typecheck && npm test && npm run build`
+- Skill: edit `.agents/skills/deeptutor/` directly and keep it in step with the tool parameters
+- Release: bump the version in `package.json`, push a `v*` tag → CI publishes to npm

package/.agents/skills/deeptutor/SKILL.md

@@ -12,9 +12,9 @@ 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.
+- **dsh (with the `dsh-deeptutor` bundle installed):** the `deeptutor_*` tools.
+  They drive the DeepTutor CLI for you, locally or over SSH for remote
+  deployments.
 - **Any agent / plain CLI:** the `deeptutor` executable directly (local
   binary on PATH, or over SSH for remote deployments). No extension needed.
 
@@ -30,27 +30,27 @@ what matters.
 
 ## 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**:
+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)
+# Remote deployment (DeepTutor on a server, driven over SSH)
 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.
+- **Tools path:** the bundle runs the local `deeptutor` CLI, or the remote one
+  over SSH when `DEEPTUTOR_SSH_HOST` is set. `deeptutor serve` does not need to
+  be reachable from this machine.
 - **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.
+  deployments.
+- DeepTutor 1.7+ ships `kb`, `notebook` and most capabilities as optional
+  modules; `deeptutor module list` shows which are installed and enabled.
+- Migrating to another server only requires changing env vars — never this skill.
 
 ## Actions Cheat Sheet
 
@@ -172,8 +172,8 @@ 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`.
+- Tool calls run the DeepTutor CLI (locally or over SSH) and return when the turn finishes; there is no live progress stream.
+- CLI-only flags (not exposed as `deeptutor_run` tool parameters): `--notebook-ref`, `--history-ref`. The tool's `config` object is passed as `--config k=v` for scalars and `--config-json` for nested values.
 - `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.

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

@@ -360,13 +360,22 @@ function main() {
     fail(`template.html not found (looked in: ${templateCandidates.join(", ")})`);
   }
   let template = fs.readFileSync(templatePath, "utf8");
-  template = template
-    .replace(/\{\{TITLE\}\}/g, esc(title))
-    .replace(/\{\{BODY\}\}/g, html)
-    .replace(/\{\{TOC\}\}/g, tocHtml)
-    .replace(/\{\{THEME\}\}/g, opts.theme)
-    .replace(/\{\{LANG\}\}/g, opts.lang)
-    .replace(/\{\{GENERATED\}\}/g, generated);
+  // One pass over the template with a replacer function: the inserted text is
+  // used verbatim (a replacement *string* would expand `$$`, `$&`, `` $` ``,
+  // `$'`), and text already inserted (e.g. a literal `{{TOC}}` in the body)
+  // is never scanned for placeholders again.
+  const values = {
+    TITLE: esc(title),
+    BODY: html,
+    TOC: tocHtml,
+    THEME: opts.theme,
+    LANG: opts.lang,
+    GENERATED: generated,
+  };
+  template = template.replace(
+    /\{\{(TITLE|BODY|TOC|THEME|LANG|GENERATED)\}\}/g,
+    (_, key) => values[key],
+  );
 
   if (opts.out) {
     fs.writeFileSync(opts.out, template, "utf8");

package/README.md

@@ -12,9 +12,6 @@ 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.
 
-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:
@@ -61,10 +58,14 @@ study page, then archived to a notebook):
   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);
-  - **Remote** — DeepTutor on a server, reached through an auto-started SSH
-    tunnel (with SSH CLI fallback).
+  - **Local** — the `deeptutor` CLI installed on this machine (on `PATH`, or
+    pointed to by `DEEPTUTOR_LOCAL_BIN`);
+  - **Remote** — DeepTutor installed on a server you can reach with
+    passwordless SSH; the plugin runs the server's CLI over SSH.
+
+  Tested against DeepTutor 1.7.1. Since 1.7 the `kb` and `notebook` commands
+  and most capabilities come from optional modules; check that the ones you
+  use are installed and enabled with `deeptutor module list`.
 
 ## Install into a profile (bundle)
 
@@ -124,7 +125,7 @@ install`:
 
 ```json
 {
-  "dependencies": { "dsh-deeptutor": "^0.1.0" },
+  "dependencies": { "dsh-deeptutor": "^0.2.0" },
   "dsh": {
     "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-deeptutor"] }
   }
@@ -163,34 +164,40 @@ Two skills ship inside this package (`.agents/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 `.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`.
+The skills are maintained in this repo under `.agents/skills/`.
 
 ## Configuration (env vars, agent-agnostic)
 
 ```bash
-# Remote deployment (DeepTutor on a server, reached through an SSH tunnel)
+# Remote deployment (DeepTutor on a server, driven over SSH)
 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.
 
+**Windows, local mode:** point `DEEPTUTOR_LOCAL_BIN` at `deeptutor.exe`
+(for a pip/venv install: `<venv>\Scripts\deeptutor.exe`). A `.cmd`/`.bat`
+wrapper also works: one that only forwards `%*` to an `.exe` is bypassed and
+the `.exe` is run directly; any other wrapper runs through `cmd.exe`, which
+cannot pass multi-line prompts, so those calls fail with a hint to use the
+`.exe`.
+
 ## 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.
+Every tool call drives the DeepTutor CLI: the local `deeptutor` binary, or the
+remote binary over SSH when `DEEPTUTOR_SSH_HOST` is set. `deeptutor serve` does
+not need to be reachable from this machine.
+
+Earlier versions tried the HTTP/WebSocket API first (`/api/v1/...` through an
+SSH tunnel) and only then fell back to the CLI. DeepTutor 1.7 serves those
+routes under different paths and behind a login, so the probe always failed
+and each call waited about 30 seconds before reaching the CLI. That path was
+removed; `DEEPTUTOR_API_BASE` is no longer read.
 
 ## Develop against a checkout (no publish needed)
 
@@ -226,6 +233,6 @@ 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);
+`cli-exec.ts` local/SSH CLI execution; `win-cmd.ts` starting a `.cmd`/`.bat` CLI on Windows;
+`turn.ts` one learning turn (CLI JSONL event folding + formatting);
 `html-render.ts` answer → self-contained HTML.

package/README.zh.md

@@ -6,8 +6,6 @@
 
 只要对 agent 说 *"给我讲讲 async/await"*,它就能跑一次 deep-solve,把答案渲染成可在浏览器打开的自包含 HTML 学习页,再把摘要归档进你的笔记本。
 
-本扩展由 pi 编码 agent 扩展迁移而来(`TecFancy/pi-extensions`,`extensions/deeptutor` + `skills/deeptutor`)。
-
 ## 它带来什么
 
 三个 agent 可见工具,当你请求学习帮助时由模型调用:
@@ -41,8 +39,10 @@
 
 - 可用的 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 回退)。
+  - **本地** —— 本机装有 `deeptutor` CLI(在 PATH 上,或由 `DEEPTUTOR_LOCAL_BIN` 指定);
+  - **远程** —— DeepTutor 装在一台能免密 SSH 登录的服务器上,插件经 SSH 调用服务器上的 CLI。
+
+  已在 DeepTutor 1.7.1 上验证。从 1.7 起,`kb`、`notebook` 命令和大部分 capability 由可选模块提供,用 `deeptutor module list` 确认要用的模块已安装并启用。
 
 ## 安装到 profile(bundle 方式)
 
@@ -79,7 +79,7 @@ dsh --profile web --dump-config | grep dsh-deeptutor
 
 ```json
 {
-  "dependencies": { "dsh-deeptutor": "^0.1.0" },
+  "dependencies": { "dsh-deeptutor": "^0.2.0" },
   "dsh": {
     "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-deeptutor"] }
   }
@@ -110,27 +110,29 @@ bundle 清单(`dsh.bundle.patch → cordis.patch.yml`)负责插入插件行;上
 
 升级包版本时会就地覆盖 skill 文件;包未携带的文件不会被删除。
 
-`skills/` 下的文件与 `TecFancy/pi-extensions` 中的同名技能逐字节一致(以 pi 仓库为唯一来源,保持 agent 中立)。上游修改后执行 `node scripts/sync-skills.mjs ../pi-extensions` 同步。
+skill 就在本仓库的 `.agents/skills/` 下维护。
 
 ## 配置(环境变量,与 agent 无关)
 
 ```bash
-# 远程部署(DeepTutor 在服务器上,通过 SSH 隧道访问)
+# 远程部署(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。
 
+**Windows 本地模式:** 把 `DEEPTUTOR_LOCAL_BIN` 指向 `deeptutor.exe`(pip/venv 安装时是 `<venv>\Scripts\deeptutor.exe`)。`.cmd`/`.bat` 包装脚本也能用:只把 `%*` 转给某个 `.exe` 的包装脚本会被绕过,直接运行那个 `.exe`;其他包装脚本经 `cmd.exe` 运行,而 `cmd.exe` 传不了多行提示词,这类调用会报错并提示改用 `.exe`。
+
 ## 工作原理
 
-插件自动适配部署模式:若 DeepTutor API 可达(本地 `serve`,或经隧道的远程服务器),学习回合走 HTTP/WebSocket;否则回退到 CLI —— 本地的 `deeptutor` 二进制,或经 SSH 的远程二进制。远程模式按需启动 SSH 隧道,插件卸载时自动拆除。
+每次工具调用都走 DeepTutor CLI:本地的 `deeptutor` 二进制,或在设置了 `DEEPTUTOR_SSH_HOST` 时经 SSH 调用远程二进制。本机不需要能访问 `deeptutor serve`。
+
+早期版本先尝试 HTTP/WebSocket API(经 SSH 隧道访问 `/api/v1/...`),失败后才回退到 CLI。DeepTutor 1.7 的这些接口换了路径并要求登录,探测总是失败,每次调用都要先等约 30 秒才轮到 CLI。这条路径已移除,`DEEPTUTOR_API_BASE` 不再读取。
 
 ## 源码开发(无需发布)
 
@@ -163,4 +165,4 @@ 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。
+`src/index.ts` 注册工具;`config.ts` 环境配置;`cli-exec.ts` 本地/SSH CLI 执行;`win-cmd.ts` 在 Windows 上启动 `.cmd`/`.bat` 形式的 CLI;`turn.ts` 单次学习回合(CLI JSONL 事件折叠与格式化);`html-render.ts` 答案 → 自包含 HTML。

package/lib/cli-exec.js

@@ -7,6 +7,7 @@ import { rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { DEEPTUTOR_BIN, DEEPTUTOR_HOME, LOCAL_BIN, SSH_HOST } from "./config.js";
+import { resolveLocalCommand } from "./win-cmd.js";
 // Remote runner: reads argv from a JSON file and executes without a shell (avoids all quoting/escaping).
 const PY_RUNNER = [
     "import json, subprocess, sys",
@@ -53,6 +54,7 @@ function execFileResolved(file, args, opts = {}) {
         const child = execFile(file, args, {
             env: opts.env ? { ...process.env, ...opts.env } : process.env,
             windowsHide: true,
+            windowsVerbatimArguments: opts.windowsVerbatimArguments,
             timeout: opts.timeoutMs,
         }, (err, stdout, stderr) => {
             const e = err;
@@ -109,8 +111,17 @@ export async function runCli(args, opts = {}) {
     if (SSH_HOST) {
         return sshExec([DEEPTUTOR_BIN, ...args], opts);
     }
-    // Local mode: execute directly (force UTF-8 output to avoid Windows cp1252 console crashes)
-    const res = await execFileResolved(LOCAL_BIN, args, { signal: opts.signal, timeoutMs: opts.timeoutMs, env: { PYTHONUTF8: "1", PYTHONIOENCODING: "utf-8" } });
+    // Local mode: execute directly (force UTF-8 output to avoid Windows cp1252 console crashes).
+    // On Windows a .cmd/.bat LOCAL_BIN needs special handling (spawn EINVAL otherwise, issue #8).
+    const cmd = resolveLocalCommand(LOCAL_BIN, args);
+    if (cmd.error)
+        return { stdout: "", stderr: cmd.error, code: 1, killed: false };
+    const res = await execFileResolved(cmd.file, cmd.args, {
+        signal: opts.signal,
+        timeoutMs: opts.timeoutMs,
+        env: { PYTHONUTF8: "1", PYTHONIOENCODING: "utf-8" },
+        windowsVerbatimArguments: cmd.windowsVerbatimArguments,
+    });
     const out = res.stdout ?? "";
     const [stdout, stderr] = out.split("__DT_STDERR__");
     return {

package/lib/config.d.ts

@@ -1,16 +1,16 @@
 /**
  * DeepTutor bridge: shared configuration (env vars) and small helpers.
  *
+ * Every call goes through the deeptutor CLI. DeepTutor 1.7 moved its HTTP/WS routes off
+ * /api/v1 and put them behind a login, so the plugin no longer talks to `deeptutor serve`.
+ *
  * Config (optional env vars, agent-agnostic):
  *   DEEPTUTOR_SSH_HOST    SSH host alias (remote deployment; unset/empty = local deployment)
- *   DEEPTUTOR_API_BASE    API base URL (default http://127.0.0.1:8001, local or tunnel port)
- *   DEEPTUTOR_LOCAL_BIN   local deeptutor executable (local CLI fallback; default: deeptutor on PATH)
- *   DEEPTUTOR_REMOTE_BIN  remote deeptutor binary path (remote CLI fallback)
- *   DEEPTUTOR_REMOTE_HOME remote DEEPTUTOR_HOME workspace (remote)
+ *   DEEPTUTOR_LOCAL_BIN   local deeptutor executable (default: deeptutor on PATH)
+ *   DEEPTUTOR_REMOTE_BIN  remote deeptutor binary path (remote deployment)
+ *   DEEPTUTOR_REMOTE_HOME remote DEEPTUTOR_HOME workspace (remote deployment)
  */
 export declare const SSH_HOST: string;
-export declare const API_BASE: string;
-export declare const TUNNEL_PORT: number;
 export declare const LOCAL_BIN: string;
 export declare const DEEPTUTOR_BIN: string;
 export declare const DEEPTUTOR_HOME: string;

package/lib/config.js

@@ -1,22 +1,21 @@
 /**
  * DeepTutor bridge: shared configuration (env vars) and small helpers.
  *
+ * Every call goes through the deeptutor CLI. DeepTutor 1.7 moved its HTTP/WS routes off
+ * /api/v1 and put them behind a login, so the plugin no longer talks to `deeptutor serve`.
+ *
  * Config (optional env vars, agent-agnostic):
  *   DEEPTUTOR_SSH_HOST    SSH host alias (remote deployment; unset/empty = local deployment)
- *   DEEPTUTOR_API_BASE    API base URL (default http://127.0.0.1:8001, local or tunnel port)
- *   DEEPTUTOR_LOCAL_BIN   local deeptutor executable (local CLI fallback; default: deeptutor on PATH)
- *   DEEPTUTOR_REMOTE_BIN  remote deeptutor binary path (remote CLI fallback)
- *   DEEPTUTOR_REMOTE_HOME remote DEEPTUTOR_HOME workspace (remote)
+ *   DEEPTUTOR_LOCAL_BIN   local deeptutor executable (default: deeptutor on PATH)
+ *   DEEPTUTOR_REMOTE_BIN  remote deeptutor binary path (remote deployment)
+ *   DEEPTUTOR_REMOTE_HOME remote DEEPTUTOR_HOME workspace (remote deployment)
  */
 export const SSH_HOST = process.env.DEEPTUTOR_SSH_HOST ?? "";
-export const API_BASE = process.env.DEEPTUTOR_API_BASE ?? "http://127.0.0.1:8001";
-export const TUNNEL_PORT = Number(new URL(API_BASE).port || 8001);
 export const LOCAL_BIN = process.env.DEEPTUTOR_LOCAL_BIN ?? "deeptutor";
 export const DEEPTUTOR_BIN = process.env.DEEPTUTOR_REMOTE_BIN ?? "/home/ubuntu/my-deeptutor/.venv/bin/deeptutor";
 export const DEEPTUTOR_HOME = process.env.DEEPTUTOR_REMOTE_HOME ?? "/home/ubuntu/my-deeptutor";
 // Whether the user explicitly configured anything (show a one-time hint when not)
 const IS_CONFIGURED = Boolean(process.env.DEEPTUTOR_SSH_HOST ||
-    process.env.DEEPTUTOR_API_BASE ||
     process.env.DEEPTUTOR_LOCAL_BIN ||
     process.env.DEEPTUTOR_REMOTE_BIN ||
     process.env.DEEPTUTOR_REMOTE_HOME);
@@ -25,25 +24,25 @@ export function configHint() {
     if (IS_CONFIGURED || configHintShown)
         return "";
     configHintShown = true;
-    return ("⚠️ No DEEPTUTOR_* env vars detected; running in local-deployment mode (local serve / local CLI).\n" +
-        '   Local deployment: export DEEPTUTOR_API_BASE="http://127.0.0.1:8001" (serve port; optional DEEPTUTOR_LOCAL_BIN)\n' +
-        '   Remote deployment: export DEEPTUTOR_SSH_HOST="your-ssh-alias" plus DEEPTUTOR_API_BASE\n' +
-        "   (See the SKILL's Configuration section; changing server/port only requires env vars)\n");
+    return ("⚠️ No DEEPTUTOR_* env vars detected; running in local-deployment mode (deeptutor CLI on PATH).\n" +
+        '   Local deployment: optionally export DEEPTUTOR_LOCAL_BIN="/path/to/deeptutor"\n' +
+        '   Remote deployment: export DEEPTUTOR_SSH_HOST="your-ssh-alias" plus DEEPTUTOR_REMOTE_BIN / DEEPTUTOR_REMOTE_HOME\n' +
+        "   (See the SKILL's Configuration section; changing server only requires env vars)\n");
 }
 export function configGuide() {
     return ("\n--- Configuration troubleshooting ---\n" +
-        "Local deployment (deeptutor runs on this machine):\n" +
-        '   export DEEPTUTOR_API_BASE="http://127.0.0.1:8001" (serve port)\n' +
+        "Local deployment (deeptutor installed on this machine):\n" +
         '   export DEEPTUTOR_LOCAL_BIN="deeptutor" (local CLI path, optional)\n' +
         "   Note: do NOT set DEEPTUTOR_SSH_HOST (empty = local mode)\n" +
-        "   Verify serve is running: curl http://127.0.0.1:8001/api/v1/system/status\n" +
-        "Remote deployment (deeptutor on a server):\n" +
+        "   Verify the CLI works: deeptutor kb list --format json\n" +
+        "Remote deployment (deeptutor on a server, driven over SSH):\n" +
         '   export DEEPTUTOR_SSH_HOST="your-ssh-alias"\n' +
-        '   export DEEPTUTOR_API_BASE="http://127.0.0.1:8001" (local tunnel address; port must match the server\'s serve)\n' +
         '   export DEEPTUTOR_REMOTE_BIN="remote-deeptutor-binary-path"\n' +
         '   export DEEPTUTOR_REMOTE_HOME="remote-DEEPTUTOR_HOME-workspace"\n' +
-        "   Verify serve is running on the server (ssh to it: curl http://127.0.0.1:8001/api/v1/system/status)\n" +
         "   Verify passwordless SSH login works (ssh alias + BatchMode)\n" +
+        "   Verify the remote CLI works: ssh <alias> <DEEPTUTOR_REMOTE_BIN> kb list --format json\n" +
+        "DeepTutor 1.7+: the kb / notebook commands and most capabilities need their modules\n" +
+        "   installed and enabled (check with: deeptutor module list).\n" +
         'PowerShell users: use $env:VAR="value" instead of export VAR=value.\n' +
         "Restart the agent after configuring.\n");
 }

package/lib/index.d.ts

@@ -1,19 +1,18 @@
 /**
  * DeepTutor bridge plugin for DeepSeek Harness (dsh).
  *
- * Migrated from the pi coding-agent extension (TecFancy/pi-extensions,
- * extensions/deeptutor + skills/deeptutor). Registers three model-facing tools:
- *   - deeptutor_run  — execute a DeepTutor learning capability (HTTP/WS first, CLI fallback)
+ * Registers three model-facing tools:
+ *   - deeptutor_run  — execute a DeepTutor learning capability
  *   - deeptutor_kb   — list / search / info knowledge bases
  *   - deeptutor_note — archive a Markdown learning note to a server notebook
  *
- * Deployment auto-detection:
- *   - Local: deeptutor serve runs on this machine → API probe succeeds directly; if serve is
- *     not running, falls back to the local CLI (DEEPTUTOR_LOCAL_BIN).
- *   - Remote: serve runs on a server (listening on 127.0.0.1 only) → an SSH tunnel is started
- *     automatically to reach the API; if the tunnel is unavailable, falls back to the SSH CLI.
+ * Transport: every tool drives the deeptutor CLI.
+ *   - Local: DEEPTUTOR_SSH_HOST unset → runs the local CLI (DEEPTUTOR_LOCAL_BIN).
+ *   - Remote: DEEPTUTOR_SSH_HOST set → runs the server's CLI over SSH.
+ * The HTTP/WS API was dropped: DeepTutor 1.7 moved it off /api/v1 and put it behind
+ * a login, so the old probe always 404'd and cost ~30s per call before the CLI ran anyway.
  *
- * Env config (agent-agnostic): DEEPTUTOR_SSH_HOST / DEEPTUTOR_API_BASE / DEEPTUTOR_LOCAL_BIN /
+ * Env config (agent-agnostic): DEEPTUTOR_SSH_HOST / DEEPTUTOR_LOCAL_BIN /
  * DEEPTUTOR_REMOTE_BIN / DEEPTUTOR_REMOTE_HOME — see src/config.ts and
  * .agents/skills/deeptutor/SKILL.md.
  */