dsh-dl-server 0.1.0 → 0.1.1

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.
Files changed (3) hide show
  1. package/README.md +91 -18
  2. package/README.zh.md +91 -16
  3. package/package.json +15 -6
package/README.md CHANGED
@@ -3,15 +3,39 @@
3
3
  English | [中文](README.zh.md)
4
4
 
5
5
  **DLS** — DSH Download Server
6
- A global download service for DeepSeek Harness: visible across sessions, owned per session, persistent queue, pausable and resumable.
6
+ A persistent download queue for DeepSeek Harness.
7
7
 
8
- > DLS is all you need
8
+ > Downloads should not live inside a session.
9
+
10
+ ---
11
+
12
+ ## Install
13
+
14
+ ### From the UI (recommended)
15
+
16
+ ```
17
+ Settings → Plugins → Install a third-party plugin → Add plugin
18
+ ```
19
+
20
+ Type **`dsh-dl-server`**, confirm, then **restart DSH once**.
21
+
22
+ ### From the command line
23
+
24
+ ```sh
25
+ dsh plugin add dsh-dl-server
26
+ ```
27
+
28
+ > `dsh` must be on your PATH. The desktop build ships one at
29
+ > `…\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd`; if you have never added it, use the UI path.
30
+
31
+ **Requires DSH 0.2.1-rc.5 or newer.**
32
+ **aria2 is optional** — install it for 16-way segmented downloading, or skip it and the plugin falls back to a single-stream transfer. Same features, less speed.
9
33
 
10
34
  ---
11
35
 
12
36
  ## Why
13
37
 
14
- Every existing DSH downloader is one tool function that blocks until the file lands. They make downloads **fast**; they don't solve three things:
38
+ Most DSH downloaders are one tool function that blocks until the file lands. They make downloads **fast**; they don't solve three things:
15
39
 
16
40
  - the download dies when the session or the turn ends
17
41
  - there is no queue, no pause, no resume
@@ -19,27 +43,76 @@ Every existing DSH downloader is one tool function that blocks until the file la
19
43
 
20
44
  DLS is the **queue layer**, not the transport layer.
21
45
 
22
- ## Status
46
+ ```
47
+ Jobs live in DSH, not in a session.
48
+ ```
49
+
50
+ A download started in one session is visible to every other session — progress, destination, everything. But only the session that started it can pause, resume, or cancel it.
51
+
52
+ ---
23
53
 
24
- `v0.1` — scaffold. Design: [SPEC.md](SPEC.md).
54
+ ## The seven tools
25
55
 
26
- | Module | State |
56
+ | Tool | What it does |
27
57
  | --- | --- |
28
- | Data model | done |
29
- | Persistent domain | done |
30
- | Transport (aria2 JSON-RPC + single-stream fallback) | done |
31
- | Queue engine (scheduling, ownership, pause reasons, checkpoints, recovery) | done |
32
- | Seven tools | done |
33
- | Real DSH install / verification | done (DSH 0.2.1-rc.5) |
34
- | Hermetic tests (`npm test`) | done |
35
- | User panel (v3) | later |
58
+ | `download_enqueue` | Queue a job, **return immediately** with a job id |
59
+ | `download_status` | Inspect the queue or a single job (`J#1042`) |
60
+ | `download_wait` | Block until a job reaches a terminal state, with a timeout |
61
+ | `download_pause` | Pause, **keeping the bytes already on disk** |
62
+ | `download_resume` | Continue from the last checkpoint |
63
+ | `download_cancel` | Cancel, optionally dropping the partial file |
64
+ | `download_cleanup` | Drop records (the default scope leaves downloaded files alone) |
65
+
66
+ ## Example
67
+
68
+ ```
69
+ You: download these two PDFs into D:\Papers and tell me when they're done
70
+ ```
71
+
72
+ The agent calls `download_enqueue` twice and gets `J#10` / `J#11` back, then `download_wait`.
73
+
74
+ Because enqueue returns immediately, it can fire off ten downloads without waiting for any of them.
75
+
76
+ ---
77
+
78
+ ## Measured
79
+
80
+ Same machine, same file:
81
+
82
+ | Setup | Throughput |
83
+ | --- | --- |
84
+ | TUNA mirror · single connection | 43.98 MB/s |
85
+ | TUNA mirror · 16 threads (another plugin) | 54.20 MB/s |
86
+ | TUNA mirror · **DLS** | **61.08 MB/s** (saturates a 500 Mbps link) |
87
+ | HuggingFace · single-stream fallback | 1.00 MB/s |
88
+ | HuggingFace · **DLS** | **6.96 MB/s** (7×) |
89
+
90
+ The last row is the point: **on a per-connection-throttled host, segmentation beats bandwidth.**
91
+
92
+ ---
93
+
94
+ ## Behaviour worth knowing
95
+
96
+ - **Ownership is per session.** Any session on the machine can *see* every job; only the owner can mutate one.
97
+ - **`cleanup(scope="all")` deletes files.** The default `allWithoutFiles` only drops records.
98
+ - **Checkpoints live in DSH storage**, not as lock files dropped into your home directory — the plugin does not depend on `TMPDIR` or the working directory.
99
+ - **When aria2 is unavailable** the transport degrades to a single Node stream. No features lost, some speed lost.
100
+
101
+ ---
102
+
103
+ ## Docs
104
+
105
+ - [SPEC.md](SPEC.md) — the 565-line design doc: comparison with four sibling plugins, what was borrowed from PCL2, and the v1 trade-offs
106
+ - [CONTRIBUTING.md](CONTRIBUTING.md) — layout, how to run the tests, what not to touch
107
+ - [SECURITY.md](SECURITY.md) — how to report a vulnerability, and what counts as one
36
108
 
37
- ## Tools (planned)
109
+ ## Roadmap
38
110
 
39
111
  ```
40
- download_enqueue download_status download_wait
41
- download_pause download_resume download_cancel
42
- download_cleanup
112
+ v1 queue + persistence + seven tools + aria2 transport ← released
113
+ v1.1 disk headroom / silent failures / session fairness / mirrors
114
+ v2 shell interception / torrents / own segmented engine / content addressing
115
+ v3 user panel + callbacks into the agent
43
116
  ```
44
117
 
45
118
  ## License
package/README.zh.md CHANGED
@@ -5,13 +5,37 @@
5
5
  **DLS** — DSH Download Server
6
6
  大肥鱼自己的下载服务器插件
7
7
 
8
- > DLS is all you need
8
+ > 下载不该活在会话里。
9
9
 
10
10
  ---
11
11
 
12
- ## 为什么
12
+ ## 装
13
13
 
14
- 现成的 DSH 下载插件都是「一个工具函数 + 阻塞等到下完」。它们让下载**变快**，但没解决三件事：
14
+ ### 方式一：界面（推荐）
15
+
16
+ ```
17
+ 设置 → 插件 → 安装第三方插件 → 添加插件
18
+ ```
19
+
20
+ 输入框里填 **`dsh-dl-server`**，确认，然后**重启一次 DSH**。
21
+
22
+ ### 方式二：命令行
23
+
24
+ ```sh
25
+ dsh plugin add dsh-dl-server
26
+ ```
27
+
28
+ > `dsh` 需要先在 PATH 里。桌面版自带的那份在
29
+ > `…\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd`，没加过 PATH 的话用方式一。
30
+
31
+ **要求 DSH 0.2.1-rc.5 或以上。**
32
+ **aria2 可选** —— 装了走 16 线程分段，没装走单流兜底，一样能下，只是慢一些。
33
+
34
+ ---
35
+
36
+ ## 它解决什么
37
+
38
+ 现有的 DSH 下载插件几乎都是「一个工具函数 + 阻塞等到文件落地」。它们让下载**变快**，但没解决三件事：
15
39
 
16
40
  - 会话或回合结束，下载就断了
17
41
  - 不能排队、不能暂停恢复
@@ -19,25 +43,76 @@
19
43
 
20
44
  DLS 做的是**队列层**，不是传输层。
21
45
 
22
- ## 状态
46
+ ```
47
+ 任务活在 DSH 里，不活在会话里
48
+ ```
49
+
50
+ 一个会话发起的下载，其他会话都能看见进度和落盘路径；但只有发起它的那个会话能暂停、续传、取消。
51
+
52
+ ---
23
53
 
24
- `v0.1` 脚手架阶段。完整设计见 [SPEC.md](SPEC.md)。
54
+ ## 七个工具
25
55
 
26
- | 模块 | 状态 |
56
+ | 工具 | 作用 |
27
57
  | --- | --- |
28
- | 数据模型 | ✅ |
29
- | 持久化 domain | ✅ |
30
- | `download_status` | 最小实现 |
31
- | 队列引擎 | 待做 |
32
- | 传输层（aria2 / Node 兜底） | 待做 |
33
- | 其余六个工具 | 待做 |
58
+ | `download_enqueue` | 入队，**立刻返回** jobId，不等下载 |
59
+ | `download_status` | 看队列和单个任务的进度（`J#1042` 这种 id） |
60
+ | `download_wait` | 等某个任务到终态，带超时 |
61
+ | `download_pause` | 暂停，**保留已下字节** |
62
+ | `download_resume` | 从断点接着下 |
63
+ | `download_cancel` | 取消，可选删掉半截文件 |
64
+ | `download_cleanup` | 清记录（默认不动已下载的文件） |
65
+
66
+ ## 用它
67
+
68
+ ```
69
+ 你： 把这两个 PDF 下到 D:\Papers，下完告诉我
70
+ ```
71
+
72
+ agent 会调 `download_enqueue` 两次拿到 `J#10` / `J#11`，然后 `download_wait`。
73
+
74
+ **入队就返回**，所以它可以一次发十个，不用等。
75
+
76
+ ---
77
+
78
+ ## 实测
79
+
80
+ 同一台机器，同一个文件：
81
+
82
+ | 场景 | 结果 |
83
+ | --- | --- |
84
+ | 清华 TUNA 源 · 单连接 | 43.98 MB/s |
85
+ | 清华 TUNA 源 · 16 线程（其他插件） | 54.20 MB/s |
86
+ | 清华 TUNA 源 · **DLS** | **61.08 MB/s**（跑满 500M 链路） |
87
+ | HuggingFace · 单流兜底 | 1.00 MB/s |
88
+ | HuggingFace · **DLS** | **6.96 MB/s**（7 倍） |
89
+
90
+ 最后一个说明问题：**被限速的源上，分段比带宽更值钱。**
91
+
92
+ ---
93
+
94
+ ## 已知行为（不是 bug）
95
+
96
+ - **归属按会话**：同一台机器上任何会话都能**看见**全部任务，但只有 owner 能改。
97
+ - **`cleanup(scope="all")` 会删文件**；默认的 `allWithoutFiles` 只删记录。
98
+ - **断点落在 DSH 的存储里**，不是自己往用户目录丢锁文件 —— 所以不看 TMPDIR 或 cwd 的脸色。
99
+ - **aria2 不可用时自动降级**到 Node 单流，功能不减，速度降。
100
+
101
+ ---
102
+
103
+ ## 文档
104
+
105
+ - [SPEC.md](SPEC.md) —— 565 行设计说明，含四个同类插件的对比、从 PCL2 借了什么、v1 的取舍
106
+ - [CONTRIBUTING.md](CONTRIBUTING.md) —— 代码布局、怎么跑测试、哪些地方别乱动
107
+ - [SECURITY.md](SECURITY.md) —— 漏洞怎么报，什么算漏洞什么不算
34
108
 
35
- ## 工具（规划）
109
+ ## 路线
36
110
 
37
111
  ```
38
- download_enqueue download_status download_wait
39
- download_pause download_resume download_cancel
40
- download_cleanup
112
+ v1 队列 + 持久化 + 七个工具 + aria2 传输 ← 已发布
113
+ v1.1 磁盘余量 / 静默失败 / 会话公平 / 镜像表
114
+ v2 拦截钩子 / 种子 / 自研分段 / 内容寻址
115
+ v3 用户面板 + 操作回传
41
116
  ```
42
117
 
43
118
  ## 许可
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-dl-server",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "DLS — DSH Download Server: a global, session-aware, persistent download queue for DeepSeek Harness.",
5
5
  "type": "module",
6
6
  "main": "lib/index.js",
@@ -14,7 +14,7 @@
14
14
  "cordis.patch.yml",
15
15
  "LICENSE",
16
16
  "README.md",
17
- "README.en.md"
17
+ "README.zh.md"
18
18
  ],
19
19
  "keywords": [
20
20
  "deepseek-harness",
@@ -37,18 +37,27 @@
37
37
  "url": "https://github.com/Jestions-dev/dsh-download-server/issues"
38
38
  },
39
39
  "engines": {
40
- "node": ">=20"
40
+ "node": ">=20",
41
+ "dsh": ">=0.2.1-rc.1 <0.3.0-0"
41
42
  },
42
43
  "scripts": {
43
44
  "test": "node --test",
44
45
  "check": "node --check lib/index.js && node --check lib/domain.js && node --check lib/types.js"
45
46
  },
46
47
  "dependencies": {
47
- "@deepseek-ai/cordis": "~4.1.0",
48
- "@deepseek-ai/dsh-storage": "^0.2.2-rc.1",
49
- "@deepseek-ai/dsh-storage-domain": "^0.2.2-rc.1",
50
48
  "zod": "^4.4.3"
51
49
  },
50
+ "peerDependencies": {
51
+ "@deepseek-ai/dsh-storage-domain": ">=0.2.0-rc.1 <0.3.0-0"
52
+ },
53
+ "peerDependenciesMeta": {
54
+ "@deepseek-ai/dsh-storage-domain": {
55
+ "optional": true
56
+ }
57
+ },
58
+ "devDependencies": {
59
+ "@deepseek-ai/dsh-storage-domain": "^0.2.2-rc.1"
60
+ },
52
61
  "dsh": {
53
62
  "bundle": {
54
63
  "patch": "./cordis.patch.yml"