dsh-zspace 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# 变更日志
+
+## 0.1.1 — 2026-10-06
+
+纯内部重构，**对外行为与 API 不变**（`ZSpaceClient` / `ZSpaceError` / `createToolSpecs` / 12 个工具名与参数完全保持）：
+
+- `lib/client.js` 857 → 197 行，按能力拆到 `lib/client/`：`errors` / `transport` / `session` / `spaces` / `browse` / `mutate` / `upload` / `download`；
+- `lib/tools.js` 805 → 66 行：12 个工具各自成文件（`lib/tools/<工具名>.js`），公共能力抽成 `shared` / `paths` / `walk`；
+- `lib/index.js` 206 → 87 行，配置抽到 `lib/config.js`、系统提示文案抽到 `lib/prompt.js`；
+- 新增 `lib/README.md`：目录职责表 + 依赖方向 + 「加一个工具/加一个客户端能力」的步骤；
+- 测试仍为 28 项 mock 用例，拆分前后全绿；真机自检脚本未改。
+
+## 0.1.0 — 2026-10-05
+
+首个版本：
+
+- 跨网络通道：桌面客户端本地代理 `127.0.0.1:13579` → 极空间云中转 → NAS，无需同一局域网 / WebDAV / SSH / Python；
+- 12 个工具：`zspace_status` `ls` `stat` `find` `read` `download` `upload` `mkdir` `rename` `move` `copy` `remove`；
+- 路径约定：`home:` / `public:` / 相对个人空间 / NAS 绝对路径，空间根按存储池自动探测；
+- 上传：≤8 MB 走 `/v2/file/create`，更大或遇 HTTP 413 自动回退桌面客户端分片协议（2 MB/片），中文文件名可用；
+- 安全：凭据实时读桌面端 `vuex.json`（不落库）；`zspace_remove` 强制 `confirm: true` 且 NAS 侧进回收站；错误码映射为可执行提示。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-zspace contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,123 @@
-# Temporary Holding Version
+# dsh-zspace
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/dsh-zspace.svg)](https://www.npmjs.com/package/dsh-zspace)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![dsh-plugin](https://img.shields.io/badge/awesome-dsh--plugin-listed-8a2be2.svg)](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
+
+极空间（ZSpace）NAS 的 **DeepSeek Harness 插件**：把 NAS 变成 agent 的原生工具 —— **跨网络可用**，不需要同一局域网、不需要 WebDAV、不需要 SSH、不需要 Python。
+
+```
+DSH 插件  →  http://127.0.0.1:13579  →  极空间桌面客户端（已登录）  →  极空间云中转 / P2P  →  NAS
+```
+
+认证直接复用桌面客户端自己的登录态（`vuex.json`），所以**换任何网络都能用**：只要跑 DSH 的这台机器上极空间桌面客户端在线即可。这正好补上 `dsh-webdav` 那类"必须同网段"方案的短板。
+
+## 安装
+
+```sh
+# 从 npm 安装（推荐）
+dsh plugin --profile desktop add dsh-zspace@latest
+
+# 或用仓库里的本地包
+dsh plugin --profile desktop add /绝对路径/dsh-zspace-0.1.0.tgz
+```
+
+装完**重启 DSH**（或在插件市场点「一键重启」）即可在会话里看到 `zspace_*` 工具。
+
+前置条件：
+
+1. 极空间桌面客户端已安装、**已登录并正在运行**（跨网络访问靠它做云中转）；
+2. 该账号对目标空间有权限（个人空间 / 公共空间）；
+3. 不需要给 NAS 开任何端口，也不需要 DDNS。
+
+## 工具
+
+| 工具 | 作用 |
+|---|---|
+| `zspace_status` | 探活：代理、账号、NAS、存储池余量、个人/公共空间根路径与条目数。其它工具报错时先跑它 |
+| `zspace_ls` | 列目录，支持 `depth` 递归与 `limit` 预算；自动分页（NAS 单页 50 条） |
+| `zspace_stat` | 单个文件/目录的元信息（大小、修改/创建时间） |
+| `zspace_find` | 按名称在目录树里查找（大小写不敏感子串），会报告扫描了多少条目、是否提前停止 |
+| `zspace_read` | 把小文本文件读进上下文（默认上限 256 KB，二进制自动识别） |
+| `zspace_download` | 从 NAS 下载到本机（默认落到 `~/Downloads/zspace`） |
+| `zspace_upload` | 上传本地文件，**大文件自动走分片协议**，中文文件名可用 |
+| `zspace_mkdir` | 建目录 |
+| `zspace_rename` | 就地重命名 |
+| `zspace_move` | 移动到另一个目录（服务端操作，不下载） |
+| `zspace_copy` | 服务端复制 |
+| `zspace_remove` | 删除（NAS 侧进回收站）；**必须显式传 `confirm: true`** |
+
+### 路径写法
+
+| 写法 | 含义 |
+|---|---|
+| 省略 / `""` | 个人空间根（本机实测 `/sata1/my/data`） |
+| `home:相册` | 个人空间下的 `相册` |
+| `public:公共分组/skills` | 公共空间下的路径（本机 `/sata1/public/...`） |
+| `docs/2026` | 相对个人空间根 |
+| `/sata1/my/data/x.txt` | NAS 绝对路径，原样使用 |
+
+两个根路径由插件按存储池自动探测（`/<pool>/my/data`、`/<pool>/public`），也可在配置里写死。
+
+### 本地路径
+
+`zspace_upload` 的 `localPath`、`zspace_download` 的 `dir` 建议传**绝对路径**或 `~/…`：插件跑在 DSH 宿主进程里，普通相对路径是按**宿主进程的工作目录**解析的（不是会话工作区）。找不到文件时的报错会把解析后的绝对路径打出来。
+
+## 配置
+
+写在 profile 的补丁层（`~/.dsh/profiles/<profile>/cordis.patch.yml`）里 `id: zspace` 那一条的 `config` 下，改完热加载：
+
+| 配置项 | 默认 | 说明 |
+|---|---|---|
+| `baseUrl` | `http://127.0.0.1:13579` | 桌面客户端本地代理（可用 `ZS_BASE_URL` 覆盖） |
+| `configDir` | 自动探测 | `vuex.json` 所在目录（可用 `ZS_CONFIG_DIR` 覆盖） |
+| `apiVersion` | `2.3.2026042401` | NAS Web API 版本号参数 |
+| `homePath` / `publicPath` | 空＝自动探测 | 写死个人/公共空间根 |
+| `downloadDir` | 空＝`~/Downloads/zspace` | 默认下载目录 |
+| `readMaxBytes` | `262144` | `zspace_read` 上限 |
+| `listMaxEntries` | `2000` | 单次列目录/树的上限 |
+| `timeoutMs` / `maxRetries` | `60000` / `2` | 请求超时与瞬时失败重试 |
+| `smallUploadMaxBytes` | `8388608` | 超过就用分片上传 |
+| `sliceSize` | `2097152` | 分片大小（远端模式上限 2 MB） |
+| `promptEnabled` / `promptOrder` | `true` / `60` | 是否向系统提示注入使用说明 |
+
+## 安全与边界
+
+- **只读别人的东西是不可能的**：插件不存任何凭据，每次调用从桌面客户端的 `vuex.json` 现读 token（按 mtime 缓存），客户端退出登录即失效。
+- **删除是两段式的**：`zspace_remove` 必须 `confirm: true`，且 NAS 侧进回收站，不是硬删。
+- **不做端口暴露**：所有流量经本机代理走极空间云通道，NAS 不需要公网入口。
+- 已知限制：
+  - 极空间**没有官方公开 API**，本插件走的是社区整理的桌面客户端接口，客户端大版本更新可能改动；
+  - NAS 网页层的 `/file_search/file_search` 在当前固件上**忽略关键字**（换任何关键词都返回同一批 100 项），所以 `zspace_find` 用的是**受限目录遍历**而不是该接口，结果会明确报告扫描范围；
+  - 单次 list 最多 50 条（插件已自动分页）；远端模式分片上限 2 MB/片。
+
+## 代码结构
+
+按「**一个文件 = 一个能独立解释的能力**」组织，完整职责表与扩展步骤见 [lib/README.md](lib/README.md)：
+
+```
+lib/index.js      插件接线（name/inject 转发 Config + apply）    lib/client/  协议按能力拆分
+lib/config.js     配置 schema、默认值、边界校验                  transport  URL/编码/重试/校验
+lib/prompt.js     系统提示里的用法说明                            spaces     探活、存储池、空间根
+lib/tools.js      工具注册表（只做注册）                          browse/mutate  列表 / 增删改
+lib/tools/*.js    12 个工具，各一个文件                            upload/download  分片上传 / 流式下载
+```
+
+依赖是严格单向无环：`index → tools → client → {errors,transport} → format/auth`。加一个工具 = 新建 `lib/tools/<名字>.js` + 在 `lib/tools.js` 注册一行。
+
+## 测试
+
+```sh
+node --test test/client.test.js test/tools.test.js test/adaptor.test.js   # 28 项单测/集成（mock 代理）
+node scripts/live-selftest.js                                            # 真机端到端自检（会创建并清理临时目录）
+```
+
+`live-selftest.js` 覆盖：探活 → 存储池 → 定位个人/公共空间 → 建目录 → 中文名单请求上传 → 强制多分片上传 → 详情 → 读取 → 下载并校验 sha256 → 服务端复制 → 重命名 → 遍历查找 → 移动 → 删除 → 确认消失。
+
+## 与已有极空间 skill 的关系
+
+本机的 `zspace-nas` / `zspace-public-access` 等 skill 依赖 `zspace-cli`（Python）或独立 Node 脚本；本插件把同一套协议**内置进 DSH**，不依赖 Python、不依赖额外命令，并且带输出 schema、错误提示与安全护栏。两者可以共存。
+
+## 许可
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,28 @@
+# dsh-zspace bundle patch: one row inserted over whatever layers came before it.
+#
+# A patch replaces the targeted row's whole `config`, so a profile that
+# overrides this row must restate every key it wants to keep.
+#
+# Every value below has a code-side default, so this patch stays valid even on
+# a host without patch-side helper evaluation. `homePath` / `publicPath` are
+# intentionally empty: the plugin discovers them from the NAS storage pools at
+# runtime (e.g. /sata1/my/data and /sata1/public), which keeps the same file
+# working on NAS models that name their pools differently.
+
+- insert:
+    - id: zspace
+      name: dsh-zspace
+      config:
+        baseUrl: http://127.0.0.1:13579
+        apiVersion: "2.3.2026042401"
+        homePath: ""
+        publicPath: ""
+        downloadDir: ""
+        readMaxBytes: 262144
+        listMaxEntries: 2000
+        timeoutMs: 60000
+        maxRetries: 2
+        smallUploadMaxBytes: 8388608
+        sliceSize: 2097152
+        promptEnabled: true
+        promptOrder: 60

package/lib/README.md

@@ -0,0 +1,74 @@
+# lib/ 结构与约定
+
+一句话：**一个文件 = 一个能独立解释的能力**。入口只做接线，协议只管传输，工具一个文件一个。
+
+```
+lib/
+├── index.js        87 行   插件入口：name / inject / Config 转发 / apply（生命周期 + 注册）
+├── config.js      105 行   配置：schemastery 的 Config、代码侧 DEFAULTS、边界校验
+├── prompt.js       26 行   系统提示里的用法说明（promptEnabled 开关）
+├── auth.js        174 行   从桌面客户端 vuex.json 取登录态（按 mtime 缓存）
+├── format.js       91 行   时间/大小/路径小工具（无 host 依赖，纯 Node）
+├── client.js      197 行   客户端 facade：持有会话状态，方法薄委托到 client/*
+├── client/
+│   ├── errors.js     56 行  NAS 业务码 + ZSpaceError（含 hint 提示）
+│   ├── transport.js 335 行  URL 形状、表单编码、重试、响应校验、流读取
+│   ├── session.js    79 行  Cookie、公共参数、安全身份
+│   ├── spaces.js    153 行  代理探活、存储池、个人/公共空间根探测
+│   ├── browse.js     64 行  分页列目录、单条元信息
+│   ├── mutate.js    102 行  mkdir / rename / move / copy / remove
+│   ├── upload.js    129 行  单请求上传 + 分片协议
+│   └── download.js  128 行  流式下载、限量读入内存
+├── tools.js        66 行   工具注册表：建 ctx、按顺序调用 12 个工厂
+└── tools/
+    ├── shared.js     52 行  clampInt / entryLine / guarded
+    ├── paths.js      84 行  home:/public:/相对/绝对 解析 + 本地路径（含 ~/）
+    ├── walk.js      118 行  walkDirectory（ls 递归）、findByName（受限查找）
+    └── <工具名>.js  35-116 行  每个工具一个文件：status ls stat find read
+                                download upload mkdir rename move copy remove
+```
+
+## 依赖方向（严格单向，无环）
+
+```
+index.js ──> config.js ──> auth.js
+    │            prompt.js
+    └──> tools.js ──> tools/<工具>.js ──> tools/{shared,paths,walk}.js
+                  └──> client.js ──> client/<能力>.js ──> client/{errors,transport}.js
+                                                       └──> format.js / auth.js
+```
+
+- `tools/<工具>.js` **互不 import**；公共能力走 `shared/paths/walk`。
+- `tools/<工具>.js` 通过工厂参数拿到依赖（`ctx`），不直接摸 client 单例：
+
+  ```js
+  export function createLsTool(ctx) {
+  	const { clampInt, config, entryLine, getClient, guarded, resolve, walkDirectory } = ctx;
+  	return { name: "zspace_ls", description, parameters, outputSchema, render, call, execute };
+  }
+  ```
+
+- `client/<能力>.js` 导出 `fn(client, ...args)` 纯函数，`client.js` 把方法名绑到同一个 `client` 实例；
+  好处是每块能力都能脱离 class 单测，而对外仍然是 `new ZSpaceClient()`。
+
+## 加东西的流程
+
+**加一个工具**（三步）
+
+1. `lib/tools/<名字>.js`：导出 `create<Name>Tool(ctx)`，返回
+   `{ name, description, parameters, outputSchema, render, call, execute }`；
+2. `lib/tools.js`：`import` 该工厂，并在 `createToolSpecs` 的 `return [...]` 里加一行 —— **顺序即模型看到的工具表顺序**，破坏性写入放后面；
+3. `test/tools.test.js`：补一条断言（路径解析/参数护栏/outputSchema 自洽）。
+
+**加一个客户端能力**
+
+1. `lib/client/<能力>.js`：`export async function foo(client, ...)`；
+2. `lib/client.js`：`import` 后加一个薄委托方法；
+3. `lib/client.d.ts`（对外 API 变了才动）。
+
+## 约定
+
+- 单文件控制在 ~200 行内（`transport.js` 是唯一例外：编码→发送→校验逻辑内聚在一起）；
+- 每个文件顶部一句话职责 + `@module dsh-zspace/...`；
+- 对外 API 只有 `lib/index.js`（插件）与 `lib/client.js`（`ZSpaceClient` / `ZSpaceError`）两个入口，子模块视为内部结构，不进 `package.json` 的 `exports`；
+- 逻辑改动必须让 28 项 mock 测试保持全绿，触及传输/上传时另跑 `node scripts/live-selftest.js` 真机验证。

package/lib/auth.js

@@ -0,0 +1,174 @@
+/**
+ * ZSpace desktop-client credential discovery.
+ *
+ * ZSpace (极空间) has no official public API. Every community integration —
+ * including the `zspace-cli` SDK and the published `zspace-*` skills — goes
+ * through the **logged-in desktop client's local proxy**:
+ *
+ *   DSH plugin  →  http://127.0.0.1:13579  →  极空间桌面客户端  →  云中转/P2P  →  NAS
+ *
+ * That relay is what makes cross-network access work: the DSH host never needs
+ * a LAN address, a port-forward, WebDAV or SSH, only a running, logged-in
+ * desktop client on the same machine.
+ *
+ * The proxy authenticates from the client's own `vuex.json` login state, so
+ * this module reads `token` / `nasId` / `deviceId` (plus the `device` and
+ * `version` fields the sliced-upload protocol needs) from that file instead of
+ * asking the user for a password.
+ *
+ * @module dsh-zspace/auth
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/** Default local proxy address of the ZSpace desktop client. */
+export const DEFAULT_BASE_URL = "http://127.0.0.1:13579";
+
+/**
+ * NAS API version string sent as the `version` common parameter. This is the
+ * desktop client's web-API version, not the client's own app version (which
+ * `vuex.json` carries separately and which the sliced upload protocol wants).
+ */
+export const DEFAULT_API_VERSION = "2.3.2026042401";
+
+/** Environment variable overriding the client config directory. */
+export const CONFIG_DIR_ENV = "ZS_CONFIG_DIR";
+
+/** Environment variable overriding the local proxy URL. */
+export const BASE_URL_ENV = "ZS_BASE_URL";
+
+const VUEX_FILENAME = "vuex.json";
+
+/**
+ * Raised when the desktop client's login state cannot be located or parsed.
+ * The message is written for the model to act on, not just for a log.
+ */
+export class ZSpaceAuthError extends Error {
+	/**
+	 * @param message - actionable explanation.
+	 * @param options - optional underlying cause.
+	 */
+	constructor(message, options) {
+		super(message, options);
+		this.name = "ZSpaceAuthError";
+	}
+}
+
+/**
+ * Candidate directories holding `vuex.json`, most likely first.
+ *
+ * macOS is where the desktop client is confirmed to store login state;
+ * Windows/Linux paths mirror `zspace-cli` so the same plugin keeps working
+ * when the DSH host runs there.
+ *
+ * @returns {string[]} absolute candidate directories.
+ */
+export function candidateConfigDirs() {
+	const home = os.homedir();
+	const dirs = [];
+	if (process.platform === "win32") {
+		for (const base of [process.env.APPDATA, process.env.LOCALAPPDATA, process.env.USERPROFILE]) {
+			if (base) dirs.push(path.join(base, "zspace"));
+		}
+	} else if (process.platform === "darwin") {
+		dirs.push(path.join(home, "Library", "Application Support", "zspace"));
+	} else {
+		dirs.push(path.join(home, ".zspace"), path.join(home, ".config", "zspace"), path.join(home, "zspace"));
+	}
+	// De-duplicate while preserving order (APPDATA and LOCALAPPDATA can alias).
+	return [...new Set(dirs)];
+}
+
+/**
+ * Locate `vuex.json`.
+ *
+ * Resolution order: the explicit `configDir` argument, then `$ZS_CONFIG_DIR`,
+ * then the platform defaults.
+ *
+ * @param {string} [configDir] - explicit directory override.
+ * @returns {string} path to `vuex.json`.
+ * @throws {ZSpaceAuthError} when no candidate holds the file.
+ */
+export function locateVuex(configDir) {
+	const candidates = configDir
+		? [configDir]
+		: process.env[CONFIG_DIR_ENV]
+			? [process.env[CONFIG_DIR_ENV]]
+			: candidateConfigDirs();
+	for (const dir of candidates) {
+		const file = path.join(dir, VUEX_FILENAME);
+		if (fs.existsSync(file)) return file;
+	}
+	const tried = candidates.map(dir => `  - ${path.join(dir, VUEX_FILENAME)}`).join("\n");
+	throw new ZSpaceAuthError(
+		`极空间登录态未找到（vuex.json）。请确认极空间桌面客户端已安装、已登录并在运行；` +
+			`或用环境变量 ${CONFIG_DIR_ENV} 指定配置目录。已尝试：\n${tried}`,
+	);
+}
+
+/** Cache of parsed credentials keyed by vuex.json path. @type {Map<string, {stamp: string, creds: object}>} */
+const credentialCache = new Map();
+
+/**
+ * Load the desktop client's login state.
+ *
+ * Parsed results are cached per file and invalidated when `vuex.json` changes
+ * (re-login or token refresh), so a long-lived DSH session does not re-read
+ * the file on every tool call.
+ *
+ * @param {string} [configDir] - explicit config directory override.
+ * @returns {{token: string, nasId: string, deviceId: string, username: string, device: string, appVersion: string, vuexPath: string}}
+ * @throws {ZSpaceAuthError} when the file is missing, unparseable or has no token.
+ */
+export function loadCredentials(configDir) {
+	const vuexPath = locateVuex(configDir);
+	const stat = fs.statSync(vuexPath);
+	const stamp = `${stat.mtimeMs}:${stat.size}`;
+	const cached = credentialCache.get(vuexPath);
+	if (cached && cached.stamp === stamp) return cached.creds;
+
+	let parsed;
+	try {
+		// The client writes a UTF-8 BOM on some versions.
+		parsed = JSON.parse(fs.readFileSync(vuexPath, "utf8").replace(/^\uFEFF/, ""));
+	} catch (error) {
+		throw new ZSpaceAuthError(`极空间登录态无法解析：${vuexPath}（${error.message}）`, { cause: error });
+	}
+	const state = parsed.state ?? parsed;
+	const user = state.user ?? {};
+	const nas = state.nas ?? {};
+	const app = state.app ?? {};
+	if (!user.token) {
+		throw new ZSpaceAuthError(`极空间登录态缺少 token（${vuexPath}）。请在桌面客户端重新登录后重试。`);
+	}
+	const creds = {
+		token: user.token,
+		nasId: nas.nasId ?? "",
+		deviceId: app.deviceId ?? "",
+		username: user.username ?? "",
+		device: app.device ?? "",
+		appVersion: app.version ?? "1.0",
+		vuexPath,
+	};
+	credentialCache.set(vuexPath, { stamp, creds });
+	return creds;
+}
+
+/**
+ * Resolve the local proxy URL: explicit setting, then `$ZS_BASE_URL`, then the
+ * default desktop-client port.
+ *
+ * @param {string} [configured] - value from the plugin config.
+ * @returns {string} base URL without a trailing slash.
+ */
+export function resolveBaseUrl(configured) {
+	const value = configured || process.env[BASE_URL_ENV] || DEFAULT_BASE_URL;
+	return String(value).replace(/\/+$/, "");
+}
+
+/** Drop the credential cache (tests and explicit re-login recovery). */
+export function clearCredentialCache() {
+	credentialCache.clear();
+}

package/lib/client/browse.js

@@ -0,0 +1,65 @@
+/**
+ * Read-only directory access: paged listing and single-entry metadata.
+ *
+ * @module dsh-zspace/client
+ */
+
+import { toEntry } from "../format.js";
+
+/**
+ * List one directory, paging until the NAS has no more rows.
+ *
+ * @param {string} remotePath - absolute remote directory.
+ * @param {{showHidden?: boolean, maxEntries?: number}} [options] - listing options.
+ * @returns {Promise<{entries: Array<ReturnType<typeof toEntry>>, truncated: boolean}>} listing.
+ */
+export async function list(client, remotePath, options = {}) {
+	const maxEntries = options.maxEntries ?? client.listMaxEntries;
+	/** @type {Array<ReturnType<typeof toEntry>>} */
+	const entries = [];
+	let start = 0;
+	let truncated = false;
+	for (;;) {
+		const data = await client.post("/v2/file/list", {
+			path: remotePath,
+			show_hidden: options.showHidden ? "1" : "0",
+			start: String(start),
+			limit: String(client.pageSize),
+		});
+		const page = Array.isArray(data?.list) ? data.list : [];
+		for (const row of page) entries.push(toEntry(row));
+		if (page.length < client.pageSize) break;
+		start += page.length;
+		if (entries.length >= maxEntries) {
+			truncated = true;
+			break;
+		}
+	}
+	if (entries.length > maxEntries) return { entries: entries.slice(0, maxEntries), truncated: true };
+	return { entries, truncated };
+}
+
+/**
+ * File or directory metadata.
+ *
+ * @param {string} remotePath - absolute remote path.
+ * @returns {Promise<ReturnType<typeof toEntry>>} normalized entry.
+ */
+
+/**
+ * File or directory metadata.
+ *
+ * @param {string} remotePath - absolute remote path.
+ * @returns {Promise<ReturnType<typeof toEntry>>} normalized entry.
+ */
+export async function info(client, remotePath) {
+	const data = await client.post("/v2/file/info", { path: remotePath });
+	return toEntry(data ?? {});
+}
+
+/**
+ * Create one directory.
+ *
+ * @param {string} remotePath - absolute path of the new directory.
+ * @returns {Promise<ReturnType<typeof toEntry>>} the created entry.
+ */

package/lib/client/download.js

@@ -0,0 +1,130 @@
+/**
+ * Downloads: streamed file download and capped reads into memory.
+ *
+ * @module dsh-zspace/client
+ */
+
+import fsp from "node:fs/promises";
+import fs from "node:fs";
+import https from "node:https";
+import http from "node:http";
+import path from "node:path";
+import { pipeline } from "node:stream/promises";
+import { ZSpaceError } from "./errors.js";
+import { readStream } from "./transport.js";
+
+/**
+ * Download one file to a local directory.
+ *
+ * @param {string} remotePath - absolute remote file.
+ * @param {string} localDir - local destination directory (created if needed).
+ * @param {{name?: string}} [options] - destination name override.
+ * @returns {Promise<{localPath: string, bytes: number}>} written file.
+ */
+export async function download(client, remotePath, localDir, options = {}) {
+	const name = options.name || path.posix.basename(remotePath);
+	const dest = path.join(localDir, name);
+	await fsp.mkdir(localDir, { recursive: true });
+	const response = await client.openDownload(remotePath);
+
+	const status = response.statusCode ?? 0;
+	const contentType = String(response.headers["content-type"] ?? "");
+	if (status >= 400 || contentType.includes("json")) {
+		const { buffer } = await readStream(response);
+		client.parse({ status, text: buffer.toString("utf8") }, "/v2/file/download");
+	}
+	try {
+		await pipeline(response, fs.createWriteStream(dest));
+	} catch (error) {
+		await fsp.rm(dest, { force: true });
+		throw new ZSpaceError("EDOWNLOAD", `写入本地文件失败：${dest}（${error.message}）`, { cause: error });
+	}
+	const stat = await fsp.stat(dest);
+	return { localPath: dest, bytes: stat.size };
+}
+
+/**
+ * Read the head of a remote file into memory.
+ *
+ * @param {string} remotePath - absolute remote file.
+ * @param {{maxBytes?: number}} [options] - byte cap.
+ * @returns {Promise<{buffer: Buffer, truncated: boolean, bytes: number}>} content.
+ */
+
+/**
+ * Read the head of a remote file into memory.
+ *
+ * @param {string} remotePath - absolute remote file.
+ * @param {{maxBytes?: number}} [options] - byte cap.
+ * @returns {Promise<{buffer: Buffer, truncated: boolean, bytes: number}>} content.
+ */
+export async function readFile(client, remotePath, options = {}) {
+	const maxBytes = options.maxBytes ?? 262_144;
+	const response = await client.openDownload(remotePath);
+	const status = response.statusCode ?? 0;
+	const contentType = String(response.headers["content-type"] ?? "");
+	if (status >= 400 || contentType.includes("json")) {
+		const { buffer } = await readStream(response);
+		client.parse({ status, text: buffer.toString("utf8") }, "/v2/file/download");
+	}
+	const { buffer, truncated } = await readStream(response, maxBytes);
+	response.destroy();
+	return { buffer, truncated, bytes: buffer.length };
+}
+
+/**
+ * Open a download response, retrying transient proxy failures.
+ *
+ * @param {string} remotePath - absolute remote file.
+ * @returns {Promise<import("node:http").IncomingMessage>} the open response (caller consumes it).
+ */
+
+/**
+ * Open a download response, retrying transient proxy failures.
+ *
+ * @param {string} remotePath - absolute remote file.
+ * @returns {Promise<import("node:http").IncomingMessage>} the open response (caller consumes it).
+ */
+export async function openDownload(client, remotePath) {
+	const url = client.endpointUrl("/v2/file/download", { path: remotePath, remote_port: "8050" });
+	return await client.retrying(
+		() =>
+			new Promise((resolve, reject) => {
+				const request = (client.baseUrl.startsWith("https:") ? https : http).request(
+					url,
+					{ method: "GET", headers: client.authHeaders() },
+					(response) => {
+						const status = response.statusCode ?? 0;
+						if (status >= 500 || status === 429) {
+							response.resume();
+							reject(new ZSpaceError(`HTTP${status}`, `HTTP ${status} 下载失败：${remotePath}`, { endpoint: "/v2/file/download" }));
+							return;
+						}
+						resolve(response);
+					},
+				);
+				request.setTimeout(client.timeoutMs, () => request.destroy(new ZSpaceError("ETIMEDOUT", `下载超时：${remotePath}`)));
+				request.on("error", (error) => {
+					if (error instanceof ZSpaceError) reject(error);
+					else reject(new ZSpaceError("EPROXY", `下载失败（${remotePath}）：${error.message}`, { endpoint: "/v2/file/download" }));
+				});
+				request.end();
+			}),
+		error =>
+			error instanceof ZSpaceError &&
+			(error.code === "ETIMEDOUT" || error.code === "EPROXY" || /^HTTP(5\d\d|429)$/.test(error.code)),
+	);
+}
+
+/**
+ * Upload a local file into a remote directory.
+ *
+ * Files at or below `smallUploadMaxBytes` use `/v2/file/create`; larger ones
+ * (and any request the local proxy rejects with HTTP 413) use the desktop
+ * client's sliced `/v2/file/upload` protocol.
+ *
+ * @param {string} localPath - local file.
+ * @param {string} remoteDir - absolute remote directory.
+ * @param {{name?: string, onProgress?: (sent: number, total: number) => void}} [options] - upload options.
+ * @returns {Promise<{remotePath: string, bytes: number, method: "create"|"sliced"}>} upload result.
+ */