dsh-deeptutor 0.1.6 → 0.1.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +181 -177
- package/README.zh.md +133 -131
- package/cordis.patch.yml +17 -17
- package/lib/config.js +1 -0
- package/lib/http-api.js +18 -1
- package/lib/index.js +4 -0
- package/lib/turn.d.ts +10 -2
- package/lib/turn.js +27 -7
- package/package.json +74 -62
- package/scripts/install-profile.mjs +233 -233
- package/scripts/md-to-html.js +381 -353
- package/scripts/sync-skills.mjs +46 -0
- package/skills/deeptutor/README.md +129 -106
- package/skills/deeptutor/SKILL.md +183 -182
- package/skills/html-doc/SKILL.md +91 -91
- package/skills/html-doc/assets/template.html +420 -420
- package/skills/html-doc/scripts/md-to-html.js +381 -353
- package/src/cli-exec.ts +251 -251
- package/src/config.ts +71 -70
- package/src/html-render.ts +53 -53
- package/src/http-api.ts +98 -83
- package/src/index.ts +468 -464
- package/src/turn.ts +197 -174
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* Copy the shared skill files from a pi-extensions checkout into this repo.
|
|
4
|
+
* The pi repo is the single source of truth; the files must be agent-neutral.
|
|
5
|
+
*
|
|
6
|
+
* Usage:
|
|
7
|
+
* node scripts/sync-skills.mjs [path-to-pi-extensions]
|
|
8
|
+
* Default source: ../pi-extensions
|
|
9
|
+
*/
|
|
10
|
+
import { copyFileSync, existsSync, mkdirSync } from "node:fs";
|
|
11
|
+
import { dirname, join, resolve } from "node:path";
|
|
12
|
+
import { fileURLToPath } from "node:url";
|
|
13
|
+
|
|
14
|
+
const here = resolve(dirname(fileURLToPath(import.meta.url)), "..");
|
|
15
|
+
const piRoot = resolve(process.argv[2] ?? join(here, "..", "pi-extensions"));
|
|
16
|
+
|
|
17
|
+
// [pi source, this-repo destination]
|
|
18
|
+
// The bundle uses the root scripts/ copy at runtime (src/html-render.ts);
|
|
19
|
+
// the skill copy ships inside the package. Both must stay identical.
|
|
20
|
+
const FILES = [
|
|
21
|
+
["skills/deeptutor/SKILL.md", "skills/deeptutor/SKILL.md"],
|
|
22
|
+
["skills/deeptutor/README.md", "skills/deeptutor/README.md"],
|
|
23
|
+
["skills/html-doc/SKILL.md", "skills/html-doc/SKILL.md"],
|
|
24
|
+
["skills/html-doc/assets/template.html", "skills/html-doc/assets/template.html"],
|
|
25
|
+
["skills/html-doc/scripts/md-to-html.js", "scripts/md-to-html.js"],
|
|
26
|
+
["skills/html-doc/scripts/md-to-html.js", "skills/html-doc/scripts/md-to-html.js"],
|
|
27
|
+
];
|
|
28
|
+
|
|
29
|
+
let failures = 0;
|
|
30
|
+
for (const [src, dst] of FILES) {
|
|
31
|
+
const from = join(piRoot, src);
|
|
32
|
+
const to = join(here, dst);
|
|
33
|
+
if (!existsSync(from)) {
|
|
34
|
+
console.error(`[sync-skills] missing source: ${from}`);
|
|
35
|
+
failures++;
|
|
36
|
+
continue;
|
|
37
|
+
}
|
|
38
|
+
mkdirSync(dirname(to), { recursive: true });
|
|
39
|
+
copyFileSync(from, to);
|
|
40
|
+
console.log(`[sync-skills] ${src} -> ${dst}`);
|
|
41
|
+
}
|
|
42
|
+
if (failures > 0) {
|
|
43
|
+
console.error("[sync-skills] some sources missing — is the pi-extensions path correct?");
|
|
44
|
+
process.exit(1);
|
|
45
|
+
}
|
|
46
|
+
console.log("[sync-skills] done — review the diff, then commit.");
|
|
@@ -1,106 +1,129 @@
|
|
|
1
|
-
# DeepTutor Learning Assistant (
|
|
2
|
-
|
|
3
|
-
> This README is the human-facing documentation; `SKILL.md` is the agent-facing instruction file (loaded on demand).
|
|
4
|
-
>
|
|
5
|
-
|
|
6
|
-
Bridges **DeepTutor** (open-source personalized tutoring platform) into
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
##
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
1
|
+
# DeepTutor Learning Assistant (extension / bundle + SKILL)
|
|
2
|
+
|
|
3
|
+
> This README is the human-facing documentation; `SKILL.md` is the agent-facing instruction file (loaded on demand).
|
|
4
|
+
> The same code ships in two ecosystems — edit in `pi-extensions` first, then sync to `dsh-deeptutor` (see Maintenance).
|
|
5
|
+
|
|
6
|
+
Bridges **DeepTutor** (open-source personalized tutoring platform) into your
|
|
7
|
+
agent: combines your **personal knowledge bases** (RAG retrieval) with
|
|
8
|
+
**authoritative web sources** to generate learning content, self-test
|
|
9
|
+
questions, and study plans — then archives your notes to a DeepTutor notebook
|
|
10
|
+
for later review.
|
|
11
|
+
|
|
12
|
+
- **pi** — extension `extensions/deeptutor/` (entry: `index.ts`) + skill `skills/deeptutor/SKILL.md` (repo: `TecFancy/pi-extensions`)
|
|
13
|
+
- **dsh** — npm bundle `dsh-deeptutor` (the same TypeScript core) + the same skill, installed to `~/.dsh/skills/deeptutor/` (repo: `TecFancy/dsh-deeptutor`)
|
|
14
|
+
|
|
15
|
+
## Features
|
|
16
|
+
|
|
17
|
+
| Capability | Description |
|
|
18
|
+
| -------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
|
19
|
+
| Deep Solve | In-depth explanation of a topic grounded in knowledge bases + web search, with multi-turn follow-up (session continuity) |
|
|
20
|
+
| Deep Question | Generate exercises from the same learning session |
|
|
21
|
+
| Deep Research | Long multi-stage research (report mode supported) |
|
|
22
|
+
| KB Retrieval | RAG hits from your personal knowledge bases (dotnet / sqlserver / react, …) |
|
|
23
|
+
| Note Archiving | Save study notes/plans to a server notebook for searchable review |
|
|
24
|
+
| Mastery Path | Multi-stage learning path planning |
|
|
25
|
+
|
|
26
|
+
## Installation
|
|
27
|
+
|
|
28
|
+
### pi
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
# Install the pi package (extension + SKILL)
|
|
32
|
+
pi install git:github.com/TecFancy/pi-extensions
|
|
33
|
+
|
|
34
|
+
# Local development: /reload after editing (local path installs are not copied)
|
|
35
|
+
pi install D:/source/personal/pi-extensions
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
### dsh
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
# One-shot: bundle + skill, from the published package
|
|
42
|
+
pnpm dlx dsh-deeptutor --profile web
|
|
43
|
+
|
|
44
|
+
# Or install the skill manually from a checkout
|
|
45
|
+
xcopy /e /i skills\deeptutor %USERPROFILE%\.dsh\skills\deeptutor # Windows
|
|
46
|
+
cp -r skills/deeptutor ~/.dsh/skills/deeptutor # macOS/Linux
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## Configuration (environment variables)
|
|
50
|
+
|
|
51
|
+
Set these in `~/.bashrc` or `~/.zshrc` (inherited by any agent at startup — agent-agnostic):
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
# —— Remote deployment (DeepTutor on a server, via SSH tunnel) ——
|
|
55
|
+
export DEEPTUTOR_SSH_HOST="tencent-cloud" # SSH alias (set = remote mode)
|
|
56
|
+
export DEEPTUTOR_API_BASE="http://127.0.0.1:8001" # local tunnel address (change port here)
|
|
57
|
+
export DEEPTUTOR_REMOTE_BIN="/home/ubuntu/my-deeptutor/.venv/bin/deeptutor"
|
|
58
|
+
export DEEPTUTOR_REMOTE_HOME="/home/ubuntu/my-deeptutor"
|
|
59
|
+
|
|
60
|
+
# —— Local deployment (DeepTutor on this machine) —— leave DEEPTUTOR_SSH_HOST unset for local mode
|
|
61
|
+
# export DEEPTUTOR_LOCAL_BIN="deeptutor" # local CLI path (default: deeptutor on PATH)
|
|
62
|
+
# export DEEPTUTOR_HOME="/path/to/local-workspace" # local workspace
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
**Deployment auto-adapts**: API reachable (local serve or tunnel) → HTTP/WS; unreachable → local CLI or SSH CLI fallback.
|
|
66
|
+
|
|
67
|
+
## Usage
|
|
68
|
+
|
|
69
|
+
Just talk to your agent:
|
|
70
|
+
|
|
71
|
+
```
|
|
72
|
+
Deep-dive Span<T> with my dotnet knowledge base, quiz me with 5 questions, then archive the notes to a notebook
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
The agent follows the SKILL workflow automatically:
|
|
76
|
+
|
|
77
|
+
1. **Dual sourcing**: `web_search` for authoritative material (Microsoft Learn, etc.) + `deeptutor_kb search` on your personal KB
|
|
78
|
+
2. **Deep Solve**: `deeptutor_run` (deep_solve, mount KB + rag + web_search, Chinese replies)
|
|
79
|
+
3. **Follow-up turns**: reuse the returned `session_id` to continue context
|
|
80
|
+
4. **Self-test**: `deep_question` (config `num_questions`)
|
|
81
|
+
5. **Plan**: structured study plan combining authoritative links + KB highlights
|
|
82
|
+
6. **Archive**: `deeptutor_note` into a notebook
|
|
83
|
+
|
|
84
|
+
## Tools
|
|
85
|
+
|
|
86
|
+
| Tool | Key parameters |
|
|
87
|
+
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
88
|
+
| `deeptutor_run` | `capability` (deep_solve / deep_question / deep_research / chat / mastery_path / …), `kbs`, `tools` (rag / web_search), `session_id`, `config`, `language` |
|
|
89
|
+
| `deeptutor_kb` | `list` / `search` (kb + query + mode) / `info` |
|
|
90
|
+
| `deeptutor_note` | `notebook` (auto-created), `title`, `type` (chat/question/research/solve), `content` (Markdown) |
|
|
91
|
+
|
|
92
|
+
## Troubleshooting
|
|
93
|
+
|
|
94
|
+
| Symptom | Cause & fix |
|
|
95
|
+
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
96
|
+
| 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`) |
|
|
97
|
+
| Tool returns "No DEEPTUTOR_* env vars detected" | One-time hint on first call; configure per the Configuration section and restart the agent |
|
|
98
|
+
| Local CLI garbled output / crashes | The tools inject `PYTHONUTF8=1` automatically; verify Python ≥ 3.11 otherwise |
|
|
99
|
+
| 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) |
|
|
100
|
+
| CLI-only package missing modules | Official `packaging/deeptutor-cli` has incomplete deps; `pip install <module>` per the error (known: loguru, fastapi) |
|
|
101
|
+
|
|
102
|
+
## FAQ
|
|
103
|
+
|
|
104
|
+
**Q: Can local and remote be used at the same time?**
|
|
105
|
+
A: Yes. Switching only requires changing env vars (set/remove `DEEPTUTOR_SSH_HOST`); the SKILL and tools stay unchanged.
|
|
106
|
+
|
|
107
|
+
**Q: What if I change servers or ports?**
|
|
108
|
+
A: Only env vars change (`DEEPTUTOR_SSH_HOST` / `DEEPTUTOR_API_BASE` / remote paths) — never the SKILL or tools.
|
|
109
|
+
|
|
110
|
+
**Q: Is the knowledge base list hardcoded?**
|
|
111
|
+
A: No. Tools query `deeptutor_kb list` dynamically; new bases are picked up automatically.
|
|
112
|
+
|
|
113
|
+
**Q: Can other agents (Claude Code / Codex) use it?**
|
|
114
|
+
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.
|
|
115
|
+
|
|
116
|
+
## Maintenance
|
|
117
|
+
|
|
118
|
+
Shared skill files (`skills/deeptutor/*`, `skills/html-doc/*`) live **in this
|
|
119
|
+
repo (pi-extensions)** and are kept agent-neutral. `dsh-deeptutor` ships
|
|
120
|
+
byte-identical copies; after editing, sync with:
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
cd ../dsh-deeptutor && node scripts/sync-skills.mjs ../pi-extensions
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
- 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
|
|
127
|
+
- dsh code: same files under `dsh-deeptutor/src/` → rebuild with `npm run build`
|
|
128
|
+
- Release pi: push a tag to GitHub, then `pi install git:github.com/TecFancy/pi-extensions@<tag>`
|
|
129
|
+
- Release dsh: bump the version in `package.json`, push a `v*` tag → CI publishes to npm
|