dsh-zspace 0.1.2 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # 变更日志
 
+## 0.3.0 — 2026-10-07
+
+**双通道**：同一网络时直连 NAS 的 WebDAV，跨网络继续走桌面客户端云中转，插件自动选路。工具名与参数**完全不变**（仍是 13 个），既有配置继续可用。
+
+- 新增 `lib/client/webdav.js`：WebDAV 传输层（PROPFIND 列目录/取元信息、MKCOL、PUT、GET（含 Range）、MOVE、COPY、DELETE、Basic 鉴权、namespace 无关的 multistatus 解析、NAS 路径 ↔ DAV 路径双向映射）。
+- 新增 `lib/client/router.js`：选路与回退。`auto`（默认）按**可达性**探测（1.5s PROPFIND，结果缓存 60s）；**运行中** WebDAV 失败（超时/拒绝连接/5xx）会标记下线 30s 并在**同一次调用内**改用中转重试，业务错误（401/403/404/405/409、`N00…`）不触发回退。
+- 新增配置：`transportMode`(auto/webdav/relay)、`webdavUrl`、`webdavUser`、`webdavPassword`、`webdavHomePath`、`webdavPublicPath`、`webdavProbeTimeoutMs`。**密码建议只放环境变量 `ZS_WEBDAV_PASSWORD`（可选 `ZS_WEBDAV_USER`），不要写进 patch**。
+- `zspace_status` 增加 `transport` / `webdavUrl` / `webdavProbe` 字段，并说明当前在用哪条通道、不可用时两边的原因。
+- WebDAV 通道的收益：直连低延迟、不依赖桌面客户端在线、目录列表一次 `PROPFIND` 拿全（没有中转 50 行分页）。注意 `zspace_remove` 在直连通道下是 NAS 侧删除语义（是否进回收站由 NAS 决定）。
+- 验证：**36 项测试**（新增 `test/webdav.test.js` 7 项，含真 socket 的 mock WebDAV 服务器、鉴权失败/不可达探测、auto 选路、运行期回退、强制模式不回退）；真机自检新增通道诊断步骤（配了密码时还会跑一遍 WebDAV 直连写→读往返）。
+
 ## 0.1.2 — 2026-10-06
 
 新增一个写入类工具 + 一个配置项，并把文档里的真实池名换成占位符（**无破坏性变更**，工具表新增一行）：

package/README.md

@@ -30,11 +30,28 @@ dsh plugin --profile desktop add /绝对路径/dsh-zspace-0.1.0.tgz
 2. 该账号对目标空间有权限（个人空间 / 公共空间）；
 3. 不需要给 NAS 开任何端口，也不需要 DDNS。
 
+## 双通道：同网络直连 WebDAV，跨网络走云中转
+
+插件对同一套工具**自动选路**，判断依据是**可达性**而不是 IP 网段（本机在 `192.168.31.x` 也能直连 `<nas-ip>` 的 NAS）：
+
+| 情况 | 通道 | 条件 |
+|---|---|---|
+| 能直连 NAS（同网络） | **WebDAV 直连** | 配了 `webdavUrl` + 环境变量 `ZS_WEBDAV_PASSWORD`；1.5s PROPFIND 探测通过即启用 |
+| 跨网络 / WebDAV 不可达 | 桌面客户端云中转（默认） | 桌面客户端已登录并在运行 |
+
+- WebDAV 通道的好处：延迟更低、不依赖桌面客户端在线、目录列表一次 `PROPFIND` 拿全（没有中转的 50 行分页）。
+- 运行中 WebDAV 掉了（换网、NAS 重启）会**自动回退到中转并在同一次调用内重试**，只损失一点延迟，不会让工具调用失败；30s 后重新探测。
+- `transportMode`：`auto`（默认）/ `webdav`（强制，失败直接报错）/ `relay`（保持旧行为）。
+- 路径映射：NAS 的 `/sata1/my/data/...` ↔ WebDAV 的 `<webdavHomePath>/...`（默认根 `/`）；公共空间由 `webdavPublicPath` 指定（默认空＝不在 WebDAV 暴露，相关路径自动回到中转）。
+- 极空间要在「系统设置 → 文件服务」里开启 WebDAV（默认端口 `5005`，本机实测可用；`5006` 是自签 HTTPS，证书校验会失败）。
+- 密码只走环境变量（`ZS_WEBDAV_PASSWORD`，可选 `ZS_WEBDAV_USER`），**不要写进 patch 文件**——patch 是明文，会被备份/截图带走。
+- `zspace_remove` 在 WebDAV 通道下是 NAS 侧的删除语义（是否进回收站由 NAS 决定）；要确保进回收站请用 `transportMode: relay`。
+
 ## 工具
 
 | 工具 | 作用 |
 |---|---|
-| `zspace_status` | 探活：代理、账号、NAS、存储池余量、个人/公共空间根路径与条目数。其它工具报错时先跑它 |
+| `zspace_status` | 探活：**当前通道**（WebDAV 直连 / 云中转）、代理、账号、NAS、存储池余量、个人/公共空间根路径与条目数。其它工具报错时先跑它 |
 | `zspace_ls` | 列目录，支持 `depth` 递归与 `limit` 预算；自动分页（NAS 单页 50 条） |
 | `zspace_stat` | 单个文件/目录的元信息（大小、修改/创建时间） |
 | `zspace_find` | 按名称在目录树里查找（大小写不敏感子串），会报告扫描了多少条目、是否提前停止 |
@@ -75,6 +92,12 @@ dsh plugin --profile desktop add /绝对路径/dsh-zspace-0.1.0.tgz
 | `apiVersion` | `2.3.2026042401` | NAS Web API 版本号参数 |
 | `homePath` / `publicPath` | 空＝自动探测 | 写死个人/公共空间根 |
 | `downloadDir` | 空＝`~/Downloads/zspace` | 默认下载目录 |
+| `transportMode` | `auto` | 通道：`auto` / `webdav` / `relay` |
+| `webdavUrl` | 空＝关闭 | WebDAV 地址，如 `http://<nas-ip>:5005/` |
+| `webdavUser` | 空 | WebDAV 账号（NAS 账号）；密码走 `ZS_WEBDAV_PASSWORD` |
+| `webdavPassword` | 空 | 密码兜底项，建议留空改用环境变量 |
+| `webdavHomePath` / `webdavPublicPath` | `/` / 空 | 个人/公共空间在 WebDAV 里的路径（空＝公共空间不暴露） |
+| `webdavProbeTimeoutMs` | `1500` | 直连探测超时 |
 | `readMaxBytes` | `262144` | `zspace_read` 上限 |
 | `writeMaxBytes` | `5242880` | `zspace_write` 单次写入上限（更大的内容用 `zspace_upload`） |
 | `listMaxEntries` | `2000` | 单次列目录/树的上限 |

package/cordis.patch.yml

@@ -3,6 +3,11 @@
 # A patch replaces the targeted row's whole `config`, so a profile that
 # overrides this row must restate every key it wants to keep.
 #
+# WebDAV fast path: when the machine can reach the NAS directly (same network),
+# `transportMode: auto` probes this URL and uses it; otherwise every call falls
+# back to the desktop client relay. The password is NOT stored here — set
+# ZS_WEBDAV_PASSWORD in the host environment (and optionally ZS_WEBDAV_USER).
+#
 # 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
@@ -26,5 +31,12 @@
         maxRetries: 2
         smallUploadMaxBytes: 8388608
         sliceSize: 2097152
+        transportMode: auto
+        webdavUrl: ""
+        webdavUser: ""
+        webdavPassword: ""
+        webdavHomePath: /
+        webdavPublicPath: ""
+        webdavProbeTimeoutMs: 1500
         promptEnabled: true
         promptOrder: 60

package/lib/README.md

@@ -17,6 +17,9 @@ lib/
 │   ├── spaces.js    153 行  代理探活、存储池、个人/公共空间根探测
 │   ├── browse.js     64 行  分页列目录、单条元信息
 │   ├── mutate.js    102 行  mkdir / rename / move / copy / remove
+│   ├── relay.js     31 行  中转通道聚合（把下面各能力汇总成一个面）
+│   ├── webdav.js   520 行  WebDAV 直连通道（PROPFIND/PUT/MOVE/COPY + 路径双向映射）
+│   ├── router.js    99 行  选路：auto 探测 / 强制 / 运行期回退
 │   ├── upload.js    129 行  单请求上传 + 分片协议
 │   └── download.js  128 行  流式下载、限量读入内存
 ├── tools.js        68 行   工具注册表：建 ctx、按顺序调用 13 个工厂

package/lib/client/relay.js

@@ -0,0 +1,30 @@
+/**
+ * Relay transport: everything through the desktop client's local proxy.
+ *
+ * This is the original (cross-network) path, kept as one uniform surface so the
+ * router can treat it and the WebDAV transport interchangeably. Each function
+ * here is a straight re-export of the capability module that implements it.
+ *
+ * @module dsh-zspace/client/relay
+ */
+
+export { check, homePath, isDirectory, pools, publicPath } from "./spaces.js";
+export { info, list } from "./browse.js";
+export { copy, mkdir, move, remove, rename } from "./mutate.js";
+export { upload, uploadSliced } from "./upload.js";
+export { download, openDownload, readFile } from "./download.js";
+
+/** Transport name used by the router and status output. */
+export const name = "relay";
+
+/**
+ * How to probe this transport. The relay is "up" when the desktop client's
+ * local proxy answers — the same check the plugin has always used.
+ *
+ * @param {import("../client.js").ZSpaceClient} client - live client.
+ * @returns {Promise<boolean>} whether the proxy answers.
+ */
+export async function probe(client) {
+	const { check } = await import("./spaces.js");
+	return await check(client);
+}

package/lib/client/router.js

@@ -0,0 +1,132 @@
+/**
+ * Transport router — WebDAV fast path vs. desktop-client relay.
+ *
+ * The plugin always speaks the same tool surface; this module decides which
+ * transport serves a call:
+ *
+ * | mode | behaviour |
+ * |---|---|
+ * | `auto` (default) | probe WebDAV once per minute; usable → WebDAV, otherwise relay |
+ * | `webdav` | always WebDAV (failures surface loudly) |
+ * | `relay` | always the desktop-client relay (previous behaviour) |
+ *
+ * "Same network" is decided by **reachability**, not by comparing IP prefixes:
+ * a machine on `192.168.31.x` may still route straight to a NAS on
+ * `<nas-ip>`, and a machine on the NAS's own subnet may have WebDAV
+ * disabled. A 1.5s PROPFIND answers that question directly.
+ *
+ * Runtime failures on the WebDAV path (timeouts, refused connections, 5xx)
+ * mark it down for a cooldown and retry the same call over the relay, so losing
+ * the LAN mid-session only costs latency — never a failed tool call. Business
+ * errors (401/403/404/405/409, `N00…` codes) are *not* transport failures and
+ * are returned as-is.
+ *
+ * @module dsh-zspace/client/router
+ */
+
+import * as relay from "./relay.js";
+import { ZSpaceError } from "./errors.js";
+import * as webdav from "./webdav.js";
+
+/** How long a probe result is trusted. */
+const PROBE_TTL_MS = 60_000;
+
+/** How long to stay on the relay after a WebDAV runtime failure. */
+const DOWN_COOLDOWN_MS = 30_000;
+
+/** Methods served by a transport (the rest are relay internals). */
+export const ROUTED_METHODS = [
+	"check",
+	"pools",
+	"isDirectory",
+	"homePath",
+	"publicPath",
+	"list",
+	"info",
+	"mkdir",
+	"rename",
+	"move",
+	"copy",
+	"remove",
+	"download",
+	"readFile",
+	"upload",
+];
+
+/**
+ * Whether an error means "this transport is unusable right now" (as opposed to
+ * a legitimate answer about the path or the credentials).
+ *
+ * @param {unknown} error - thrown value.
+ * @returns {boolean} true when falling back to the relay is the right move.
+ */
+export function isTransportFailure(error) {
+	const code = String(/** @type {{code?: string}} */ (error)?.code ?? "");
+	if (["ETIMEDOUT", "EDAV", "EPROXY", "ECONNREFUSED", "ECONNRESET", "ENETUNREACH", "EAI_AGAIN"].includes(code)) return true;
+	if (/^HTTP(5\d\d)$/.test(code)) return true;
+	return error instanceof TypeError; // undici network failures
+}
+
+/**
+ * Which transport should serve the next call.
+ *
+ * @param {import("../client.js").ZSpaceClient} client - live client.
+ * @returns {Promise<"webdav"|"relay">} chosen transport.
+ */
+export async function selectTransport(client) {
+	const mode = client.transportMode || "auto";
+	if (mode !== "webdav" && mode !== "auto") return "relay";
+	if (!webdav.configured(client)) return "relay";
+	if (mode === "webdav") return "webdav";
+	if (client._webdavDownUntil && Date.now() < client._webdavDownUntil) return "relay";
+
+	const cached = client._webdavProbe;
+	if (cached && Date.now() - cached.at < PROBE_TTL_MS) return cached.usable ? "webdav" : "relay";
+
+	const result = await webdav.probe(client);
+	client._webdavProbe = { at: Date.now(), ...result };
+	return result.usable ? "webdav" : "relay";
+}
+
+/**
+ * Human-readable transport state for `zspace_status`.
+ *
+ * @param {import("../client.js").ZSpaceClient} client - live client.
+ * @returns {Promise<{transport: string, configured: boolean, probe: Record<string, any>|null}>} report.
+ */
+export async function transportReport(client) {
+	const transport = await selectTransport(client);
+	return {
+		transport,
+		configured: webdav.configured(client),
+		probe: client._webdavProbe ?? null,
+	};
+}
+
+/**
+ * Run one capability through the selected transport, with relay fallback.
+ *
+ * @param {import("../client.js").ZSpaceClient} client - live client.
+ * @param {string} method - capability name (see {@link ROUTED_METHODS}).
+ * @param {unknown[]} args - arguments after the client.
+ * @returns {Promise<any>} capability result.
+ */
+export async function dispatch(client, method, args) {
+	const transport = await selectTransport(client);
+	const implementation = transport === "webdav" ? webdav : relay;
+	const fn = /** @type {Record<string, Function>} */ (implementation)[method];
+	if (typeof fn !== "function") throw new ZSpaceError("ENOTIMPL", `传输 ${transport} 未实现 ${method}`);
+	try {
+		return await fn(client, ...args);
+	} catch (error) {
+		if (transport !== "webdav" || client.transportMode === "webdav" || !isTransportFailure(error)) throw error;
+		client._webdavDownUntil = Date.now() + DOWN_COOLDOWN_MS;
+		client._webdavProbe = {
+			at: Date.now(),
+			reachable: false,
+			usable: false,
+			reason: `运行中失败，${Math.round(DOWN_COOLDOWN_MS / 1000)}s 内走中转：${error?.message ?? error}`,
+		};
+		return await /** @type {Record<string, Function>} */ (relay)[method](client, ...args);
+	}
+}

package/lib/client/webdav.js

@@ -0,0 +1,622 @@
+/**
+ * WebDAV transport — the same-network fast path.
+ *
+ * When the machine can reach the NAS directly (typical on the same LAN), every
+ * file operation can go over the NAS's built-in WebDAV service
+ * (`http://<nas>:5005/`) instead of the desktop client's cloud relay: lower
+ * latency, no dependency on the client being logged in, and directory listing
+ * without the relay's 50-row page limit.
+ *
+ * The plugin's tools speak **NAS paths** (`/sata1/my/data/...`), so this module
+ * translates between those and the WebDAV layout:
+ *
+ * ```
+ * NAS  /sata1/my/data/相册/a.jpg   <->  WebDAV  <webdavHomePath>/相册/a.jpg
+ * NAS  /sata1/public/img/b.png     <->  WebDAV  <webdavPublicPath>/img/b.png
+ * ```
+ *
+ * The NAS-side roots come from config (`homePath` / `publicPath`) or, failing
+ * that, a one-off relay lookup — so results look identical no matter which
+ * transport served them.
+ *
+ * @module dsh-zspace/client/webdav
+ */
+
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+
+import { joinRemote, toEntry } from "../format.js";
+import { ZSpaceError } from "./errors.js";
+
+/** Environment variable carrying the WebDAV password (kept out of config files). */
+export const PASSWORD_ENV = "ZS_WEBDAV_PASSWORD";
+
+/** Environment variable carrying the WebDAV user name. */
+export const USER_ENV = "ZS_WEBDAV_USER";
+
+export const name = "webdav";
+
+/**
+ * Resolve WebDAV credentials: environment first, config as a fallback.
+ *
+ * @param {import("../client.js").ZSpaceClient} client - live client.
+ * @returns {{user: string, password: string, complete: boolean}} credentials.
+ */
+export function credentials(client) {
+	const user = process.env[USER_ENV] || client.webdavUser || "";
+	const password = process.env[PASSWORD_ENV] || client.webdavPassword || "";
+	return { user, password, complete: Boolean(user && password) };
+}
+
+/**
+ * Whether this transport has everything it needs to be used at all.
+ *
+ * @param {import("../client.js").ZSpaceClient} client - live client.
+ * @returns {boolean} true when a URL and complete credentials are configured.
+ */
+export function configured(client) {
+	return Boolean(String(client.webdavUrl ?? "").trim()) && credentials(client).complete;
+}
+
+/**
+ * Base URL without a trailing slash.
+ *
+ * @param {import("../client.js").ZSpaceClient} client - live client.
+ * @returns {string} base URL.
+ */
+function baseUrl(client) {
+	return String(client.webdavUrl ?? "").replace(/\/+$/, "");
+}
+
+/**
+ * Percent-encode every path segment (keeps the separators).
+ *
+ * @param {string} remotePath - DAV path.
+ * @returns {string} encoded path.
+ */
+function encodePath(remotePath) {
+	return String(remotePath)
+		.split("/")
+		.map(segment => encodeURIComponent(segment))
+		.join("/");
+}
+
+/**
+ * Join two DAV paths with single slashes.
+ *
+ * @param {string} base - base path.
+ * @param {string} rest - remainder.
+ * @returns {string} joined path, always starting with `/`.
+ */
+function joinDav(base, rest) {
+	const left = `/${String(base).replace(/^\/+|\/+$/g, "")}`;
+	const right = String(rest).replace(/^\/+/, "");
+	const joined = right === "" ? left : `${left === "/" ? "" : left}/${right}`;
+	return joined.startsWith("/") ? joined : `/${joined}`;
+}
+
+/**
+ * One HTTP request against the WebDAV endpoint.
+ *
+ * @param {import("../client.js").ZSpaceClient} client - live client.
+ * @param {object} options - request options.
+ * @param {string} options.method - HTTP method (PROPFIND/MKCOL/MOVE/... allowed).
+ * @param {string} options.davPath - DAV path (already NAS-relative, not encoded).
+ * @param {Record<string, string>} [options.headers] - extra headers.
+ * @param {BodyInit|null} [options.body] - request body.
+ * @param {number} [options.timeoutMs] - per-request timeout.
+ * @returns {Promise<Response>} fetch response.
+ */
+async function request(client, { method, davPath, headers = {}, body = null, timeoutMs }) {
+	const { user, password } = credentials(client);
+	const authorization = `Basic ${Buffer.from(`${user}:${password}`, "utf8").toString("base64")}`;
+	const init = {
+		method,
+		headers: { Authorization: authorization, ...headers },
+		signal: AbortSignal.timeout(timeoutMs ?? client.timeoutMs ?? 60_000),
+	};
+	if (body !== null) {
+		init.body = body;
+		init.duplex = "half";
+	}
+	try {
+		return await fetch(`${baseUrl(client)}${encodePath(davPath) || "/"}`, init);
+	} catch (error) {
+		const timedOut = error?.name === "TimeoutError" || error?.name === "AbortError";
+		throw new ZSpaceError(
+			timedOut ? "ETIMEDOUT" : "EDAV",
+			timedOut ? `WebDAV 请求超时：${method} ${davPath}` : `WebDAV 请求失败（${method} ${davPath}）：${error?.message ?? error}`,
+			{ endpoint: davPath, cause: error },
+		);
+	}
+}
+
+/**
+ * Turn a non-2xx response into a ZSpaceError with an actionable message.
+ *
+ * @param {Response} response - fetch response.
+ * @param {string} action - what was attempted (for the message).
+ * @returns {Promise<void>} resolves for success statuses.
+ * @throws {ZSpaceError} for failures.
+ */
+async function assertOk(response, action) {
+	if (response.ok || response.status === 207) return;
+	const status = response.status;
+	const hints = {
+		401: "WebDAV 凭据被拒：检查 webdavUser 与 ZS_WEBDAV_PASSWORD（极空间用 NAS 账号密码，不是桌面客户端 token）",
+		403: "WebDAV 无权限：确认该账号对该目录可读写",
+		404: "路径不存在：先 zspace_ls 上级目录确认拼写",
+		405: "目标已存在或方法不被支持",
+		409: "父目录不存在或状态冲突：先建父目录",
+		507: "NAS 空间不足",
+	};
+	throw new ZSpaceError(`HTTP${status}`, `${action} 失败：HTTP ${status}${hints[status] ? ` — ${hints[status]}` : ""}`, { endpoint: action });
+}
+
+/**
+ * Local name of a DAV href, decoded and stripped down to a DAV path.
+ *
+ * @param {string} href - raw href from a PROPFIND response.
+ * @returns {string} decoded DAV path.
+ */
+function hrefToDavPath(href) {
+	let value = String(href ?? "");
+	try {
+		value = new URL(value, "http://placeholder").pathname;
+	} catch {
+		/* keep raw value */
+	}
+	try {
+		value = decodeURIComponent(value);
+	} catch {
+		/* keep encoded value */
+	}
+	if (value.length > 1) value = value.replace(/\/+$/, "");
+	return value;
+}
+
+/**
+ * Parse a PROPFIND multistatus body without a full XML dependency.
+ *
+ * Namespace prefixes differ between servers (`D:`, `d:`, `lp1:`), so every tag
+ * is matched by its local name.
+ *
+ * @param {string} xml - response body.
+ * @returns {Array<{href: string, name: string, dir: boolean, size: number, modified: string}>} parsed entries.
+ */
+export function parseMultiStatus(xml) {
+	const entries = [];
+	for (const block of String(xml).matchAll(/<(?:[\w-]+:)?response\b[\s\S]*?<\/(?:[\w-]+:)?response>/gi)) {
+		const chunk = block[0];
+		const href = /<(?:[\w-]+:)?href[^>]*>([\s\S]*?)<\/(?:[\w-]+:)?href>/i.exec(chunk)?.[1] ?? "";
+		const type = /<(?:[\w-]+:)?resourcetype[^>]*>([\s\S]*?)<\/(?:[\w-]+:)?resourcetype>/i.exec(chunk)?.[1] ?? "";
+		const size = /<(?:[\w-]+:)?getcontentlength[^>]*>(\d*)</i.exec(chunk)?.[1] ?? "0";
+		const modified = /<(?:[\w-]+:)?getlastmodified[^>]*>([\s\S]*?)</i.exec(chunk)?.[1] ?? "";
+		const davPath = hrefToDavPath(href);
+		const stamp = Date.parse(modified);
+		entries.push({
+			href: davPath,
+			name: davPath === "/" ? "/" : davPath.slice(davPath.lastIndexOf("/") + 1),
+			dir: /collection/i.test(type),
+			size: Number(size) || 0,
+			modified: Number.isFinite(stamp) ? String(Math.floor(stamp / 1000)) : "",
+		});
+	}
+	return entries;
+}
+
+/**
+ * Translate a NAS path the tools use into a WebDAV path.
+ *
+ * @param {import("../client.js").ZSpaceClient} client - live client.
+ * @param {string} nasPath - NAS path such as `/sata1/my/data/a.txt`.
+ * @returns {Promise<string>} DAV path.
+ * @throws {ZSpaceError} when the path is outside both known roots.
+ */
+export async function toDavPath(client, nasPath) {
+	const roots = await nasRoots(client);
+	const homeDav = client.webdavHomePath || "/";
+	const publicDav = client.webdavPublicPath || "";
+	const value = String(nasPath);
+	if (roots.home && (value === roots.home || value.startsWith(`${roots.home}/`))) {
+		return joinDav(homeDav, value.slice(roots.home.length));
+	}
+	if (publicDav && roots.public && (value === roots.public || value.startsWith(`${roots.public}/`))) {
+		return joinDav(publicDav, value.slice(roots.public.length));
+	}
+	throw new ZSpaceError(
+		"DAV_PATH",
+		`WebDAV 通道无法映射该路径（不在个人/公共空间根下）：${value}。可在配置里写死 homePath / publicPath，或改用 home: / public: 前缀。`,
+	);
+}
+
+/**
+ * Translate a WebDAV path back into the NAS path shape the tools expect.
+ *
+ * @param {import("../client.js").ZSpaceClient} client - live client.
+ * @param {string} davPath - DAV path.
+ * @returns {Promise<string>} NAS path.
+ */
+export async function fromDavPath(client, davPath) {
+	const roots = await nasRoots(client);
+	const homeDav = (client.webdavHomePath || "/").replace(/\/+$/, "") || "/";
+	const publicDav = (client.webdavPublicPath || "").replace(/\/+$/, "");
+	const value = davPath === "/" ? "/" : davPath.replace(/\/+$/, "");
+	if (publicDav && (value === publicDav || value.startsWith(`${publicDav}/`))) {
+		return joinRemote(roots.public || "/public", value.slice(publicDav.length));
+	}
+	const rest = homeDav === "/" ? value : value.slice(homeDav.length);
+	return joinRemote(roots.home || "", rest);
+}
+
+/**
+ * NAS-side roots, resolved once: config first, then a relay lookup.
+ *
+ * @param {import("../client.js").ZSpaceClient} client - live client.
+ * @returns {Promise<{home: string, public: string}>} NAS roots ("" when unknown).
+ */
+export async function nasRoots(client) {
+	if (client._davRoots) return client._davRoots;
+	let home = client.configuredHomePath || client._homePath || "";
+	let publicSpace = client.configuredPublicPath || client._publicPath || "";
+	if (!home || !publicSpace) {
+		// The relay knows the real roots; one lookup is cheaper than making the
+		// user restate them. It is fine for this to fail — the caller then gets a
+		// clear "set homePath/publicPath" error.
+		const relay = await import("./relay.js");
+		if (!home) home = await relay.homePath(client).catch(() => "");
+		if (!publicSpace) publicSpace = await relay.publicPath(client).catch(() => "");
+	}
+	client._davRoots = { home, public: publicSpace };
+	return client._davRoots;
+}
+
+/**
+ * Reachability + credential probe, used by the router.
+ *
+ * @param {import("../client.js").ZSpaceClient} client - live client.
+ * @returns {Promise<{reachable: boolean, usable: boolean, status?: number, reason: string}>} probe result.
+ */
+export async function probe(client) {
+	if (!String(client.webdavUrl ?? "").trim()) {
+		return { reachable: false, usable: false, reason: "未配置 webdavUrl" };
+	}
+	if (!credentials(client).complete) {
+		return { reachable: false, usable: false, reason: `缺少 WebDAV 凭据（设置 ${USER_ENV} 与 ${PASSWORD_ENV}）` };
+	}
+	try {
+		const response = await request(client, {
+			method: "PROPFIND",
+			davPath: "/",
+			headers: { Depth: "0" },
+			timeoutMs: client.webdavProbeTimeoutMs ?? 1500,
+		});
+		if (response.status === 401 || response.status === 403) {
+			return { reachable: true, usable: false, status: response.status, reason: `可达但凭据被拒（HTTP ${response.status}）` };
+		}
+		if (response.status >= 500) {
+			return { reachable: true, usable: false, status: response.status, reason: `服务端错误（HTTP ${response.status}）` };
+		}
+		return { reachable: true, usable: true, status: response.status, reason: `可达（HTTP ${response.status}）` };
+	} catch (error) {
+		return {
+			reachable: false,
+			usable: false,
+			reason: error?.code === "ETIMEDOUT" ? "探测超时（多半不在同一网络）" : `不可达：${error?.message ?? error}`,
+		};
+	}
+}
+
+/**
+ * Connectivity in the shape the tools expect.
+ *
+ * @param {import("../client.js").ZSpaceClient} client - live client.
+ * @returns {Promise<boolean>} whether WebDAV is usable right now.
+ */
+export async function check(client) {
+	return (await probe(client)).usable;
+}
+
+/**
+ * Storage pools are a relay-only concept (WebDAV does not expose them).
+ *
+ * @returns {Promise<Array<never>>} always empty.
+ */
+export async function pools() {
+	return [];
+}
+
+/**
+ * Whether a path exists and is a collection.
+ *
+ * @param {import("../client.js").ZSpaceClient} client - live client.
+ * @param {string} nasPath - NAS path.
+ * @returns {Promise<boolean>} true for existing directories.
+ */
+export async function isDirectory(client, nasPath) {
+	try {
+		const entry = await info(client, nasPath);
+		return entry.dir === true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * NAS path of the personal-space root.
+ *
+ * @param {import("../client.js").ZSpaceClient} client - live client.
+ * @returns {Promise<string>} NAS path.
+ */
+export async function homePath(client) {
+	const roots = await nasRoots(client);
+	if (!roots.home) throw new ZSpaceError("NOHOME", "WebDAV 模式下无法确定个人空间根：请在配置里设置 homePath");
+	return roots.home;
+}
+
+/**
+ * NAS path of the public-space root.
+ *
+ * @param {import("../client.js").ZSpaceClient} client - live client.
+ * @returns {Promise<string>} NAS path.
+ */
+export async function publicPath(client) {
+	const roots = await nasRoots(client);
+	if (!roots.public) throw new ZSpaceError("NOPUBLIC", "WebDAV 模式下无法确定公共空间根：请在配置里设置 publicPath（或它在 WebDAV 里不可见）");
+	return roots.public;
+}
+
+/**
+ * List one directory (single PROPFIND, no 50-row paging).
+ *
+ * @param {import("../client.js").ZSpaceClient} client - live client.
+ * @param {string} nasPath - NAS directory.
+ * @param {{showHidden?: boolean, maxEntries?: number}} [options] - listing options.
+ * @returns {Promise<{entries: Array<ReturnType<typeof toEntry>>, truncated: boolean}>} listing.
+ */
+export async function list(client, nasPath, options = {}) {
+	const davPath = await toDavPath(client, nasPath);
+	const response = await request(client, { method: "PROPFIND", davPath, headers: { Depth: "1" } });
+	await assertOk(response, `PROPFIND ${nasPath}`);
+	const xml = await response.text();
+	const self = davPath === "/" ? "/" : davPath.replace(/\/+$/, "");
+	const maxEntries = options.maxEntries ?? client.listMaxEntries ?? 2000;
+	const entries = [];
+	let truncated = false;
+	for (const raw of parseMultiStatus(xml)) {
+		if (raw.href === self || raw.href === `${self}/`) continue;
+		if (!raw.name) continue;
+		if (!options.showHidden && raw.name.startsWith(".")) continue;
+		if (entries.length >= maxEntries) {
+			truncated = true;
+			break;
+		}
+		const nas = await fromDavPath(client, raw.href);
+		entries.push(
+			toEntry({
+				name: raw.name,
+				path: nas,
+				is_dir: raw.dir ? "1" : "0",
+				size: String(raw.size),
+				modify_time: raw.modified,
+			}),
+		);
+	}
+	entries.sort((a, b) => Number(b.dir) - Number(a.dir) || a.name.localeCompare(b.name, "zh"));
+	return { entries, truncated };
+}
+
+/**
+ * Metadata for one path.
+ *
+ * @param {import("../client.js").ZSpaceClient} client - live client.
+ * @param {string} nasPath - NAS path.
+ * @returns {Promise<ReturnType<typeof toEntry>>} normalized entry.
+ */
+export async function info(client, nasPath) {
+	const davPath = await toDavPath(client, nasPath);
+	const response = await request(client, { method: "PROPFIND", davPath, headers: { Depth: "0" } });
+	await assertOk(response, `PROPFIND ${nasPath}`);
+	const [first] = parseMultiStatus(await response.text());
+	if (!first) throw new ZSpaceError("N001315", `文件不存在（${nasPath}）`);
+	return toEntry({
+		name: first.name === "/" ? davPath.slice(davPath.lastIndexOf("/") + 1) : first.name,
+		path: nasPath,
+		is_dir: first.dir ? "1" : "0",
+		size: String(first.size),
+		modify_time: first.modified,
+	});
+}
+
+/**
+ * Create a directory (MKCOL).
+ *
+ * @param {import("../client.js").ZSpaceClient} client - live client.
+ * @param {string} nasPath - NAS directory to create.
+ * @returns {Promise<ReturnType<typeof toEntry>>} created entry.
+ */
+export async function mkdir(client, nasPath) {
+	const davPath = await toDavPath(client, nasPath);
+	const response = await request(client, { method: "MKCOL", davPath });
+	if (response.status === 405) throw new ZSpaceError("N001212", `目录已存在：${nasPath}`);
+	await assertOk(response, `MKCOL ${nasPath}`);
+	return toEntry({ name: nasPath.slice(nasPath.lastIndexOf("/") + 1), path: nasPath, is_dir: "1", size: "0" });
+}
+
+/**
+ * Rename in place (MOVE within the same directory).
+ *
+ * @param {import("../client.js").ZSpaceClient} client - live client.
+ * @param {string} nasPath - NAS path to rename.
+ * @param {string} newName - new base name.
+ * @returns {Promise<ReturnType<typeof toEntry>>} renamed entry.
+ */
+export async function rename(client, nasPath, newName) {
+	const parent = nasPath.slice(0, nasPath.lastIndexOf("/"));
+	const target = `${parent}/${newName}`;
+	await movePath(client, nasPath, target);
+	return toEntry({ name: newName, path: target, is_dir: "0", size: "0" });
+}
+
+/**
+ * MOVE one NAS path to an absolute destination (used by rename/move).
+ *
+ * @param {import("../client.js").ZSpaceClient} client - live client.
+ * @param {string} from - source NAS path.
+ * @param {string} to - destination NAS path.
+ * @returns {Promise<void>} resolves when accepted.
+ */
+async function movePath(client, from, to) {
+	const source = await toDavPath(client, from);
+	const destination = await toDavPath(client, to);
+	const response = await request(client, {
+		method: "MOVE",
+		davPath: source,
+		headers: { Destination: `${baseUrl(client)}${encodePath(destination)}`, Overwrite: "F" },
+	});
+	if (response.status === 412) throw new ZSpaceError("N001212", `目标已存在：${to}`);
+	await assertOk(response, `MOVE ${from} -> ${to}`);
+}
+
+/**
+ * Move several paths into a target directory.
+ *
+ * @param {import("../client.js").ZSpaceClient} client - live client.
+ * @param {string[]} nasPaths - sources.
+ * @param {string} to - destination directory.
+ * @returns {Promise<void>} resolves when accepted.
+ */
+export async function move(client, nasPaths, to) {
+	for (const source of nasPaths) {
+		const name = source.slice(source.lastIndexOf("/") + 1);
+		await movePath(client, source, `${to.replace(/\/+$/, "")}/${name}`);
+	}
+}
+
+/**
+ * Copy several paths into a target directory.
+ *
+ * @param {import("../client.js").ZSpaceClient} client - live client.
+ * @param {string[]} nasPaths - sources.
+ * @param {string} to - destination directory.
+ * @returns {Promise<void>} resolves when accepted.
+ */
+export async function copy(client, nasPaths, to) {
+	for (const source of nasPaths) {
+		const name = source.slice(source.lastIndexOf("/") + 1);
+		const from = await toDavPath(client, source);
+		const target = await toDavPath(client, `${to.replace(/\/+$/, "")}/${name}`);
+		const response = await request(client, {
+			method: "COPY",
+			davPath: from,
+			headers: { Destination: `${baseUrl(client)}${encodePath(target)}`, Overwrite: "F" },
+		});
+		if (response.status === 412) throw new ZSpaceError("N001212", `目标已存在：${to}/${name}`);
+		await assertOk(response, `COPY ${source} -> ${to}`);
+	}
+}
+
+/**
+ * Delete paths (WebDAV DELETE — recycle-bin behaviour is the NAS's call).
+ *
+ * @param {import("../client.js").ZSpaceClient} client - live client.
+ * @param {string[]} nasPaths - paths to delete.
+ * @returns {Promise<void>} resolves when accepted.
+ */
+export async function remove(client, nasPaths) {
+	for (const target of nasPaths) {
+		const davPath = await toDavPath(client, target);
+		const response = await request(client, { method: "DELETE", davPath });
+		await assertOk(response, `DELETE ${target}`);
+	}
+}
+
+/**
+ * Download a file to a local directory.
+ *
+ * @param {import("../client.js").ZSpaceClient} client - live client.
+ * @param {string} nasPath - NAS file.
+ * @param {string} localDir - local destination directory.
+ * @param {{name?: string}} [options] - name override.
+ * @returns {Promise<{localPath: string, bytes: number}>} written file.
+ */
+export async function download(client, nasPath, localDir, options = {}) {
+	const davPath = await toDavPath(client, nasPath);
+	const response = await request(client, { method: "GET", davPath });
+	await assertOk(response, `GET ${nasPath}`);
+	if (!response.body) throw new ZSpaceError("EDAV", `WebDAV 未返回内容：${nasPath}`);
+	const dest = path.join(localDir, options.name || path.posix.basename(nasPath));
+	await fsp.mkdir(localDir, { recursive: true });
+	try {
+		await pipeline(Readable.fromWeb(response.body), 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 file into memory.
+ *
+ * @param {import("../client.js").ZSpaceClient} client - live client.
+ * @param {string} nasPath - NAS file.
+ * @param {{maxBytes?: number}} [options] - byte cap.
+ * @returns {Promise<{buffer: Buffer, truncated: boolean, bytes: number}>} content.
+ */
+export async function readFile(client, nasPath, options = {}) {
+	const maxBytes = options.maxBytes ?? 262_144;
+	const davPath = await toDavPath(client, nasPath);
+	const response = await request(client, { method: "GET", davPath, headers: { Range: `bytes=0-${maxBytes - 1}` } });
+	await assertOk(response, `GET ${nasPath}`);
+	if (!response.body) return { buffer: Buffer.alloc(0), truncated: false, bytes: 0 };
+	const buffer = Buffer.from(await response.arrayBuffer());
+	const truncated = response.status === 206 ? buffer.length >= maxBytes : buffer.length > maxBytes;
+	return { buffer: buffer.subarray(0, maxBytes), truncated, bytes: Math.min(buffer.length, maxBytes) };
+}
+
+/**
+ * Upload a local file (single PUT).
+ *
+ * @param {import("../client.js").ZSpaceClient} client - live client.
+ * @param {string} localPath - local file.
+ * @param {string} remoteDir - NAS destination directory.
+ * @param {{name?: string}} [options] - name override.
+ * @returns {Promise<{remotePath: string, bytes: number, method: "put"}>} upload result.
+ */
+export async function upload(client, localPath, remoteDir, options = {}) {
+	const stat = await fsp.stat(localPath);
+	const name = options.name || path.basename(localPath);
+	const target = joinRemote(remoteDir, name);
+	const davPath = await toDavPath(client, target);
+	const response = await request(client, {
+		method: "PUT",
+		davPath,
+		headers: { "Content-Type": "application/octet-stream", "Content-Length": String(stat.size) },
+		body: Readable.toWeb(fs.createReadStream(localPath)),
+	});
+	await assertOk(response, `PUT ${target}`);
+	return { remotePath: target, bytes: stat.size, method: "put" };
+}
+
+/**
+ * Not used by the WebDAV transport (PUT is never sliced).
+ *
+ * @returns {Promise<never>} always throws.
+ */
+export async function uploadSliced() {
+	throw new ZSpaceError("EDAV", "WebDAV 通道不使用分片上传");
+}
+
+/**
+ * Not used by the WebDAV transport (download() opens its own request).
+ *
+ * @returns {Promise<never>} always throws.
+ */
+export async function openDownload() {
+	throw new ZSpaceError("EDAV", "WebDAV 通道请使用 download()");
+}

package/lib/client.js

@@ -24,13 +24,12 @@
  */
 
 import { DEFAULT_API_VERSION, loadCredentials, resolveBaseUrl } from "./auth.js";
-import { identity, authHeaders, commonParams } from "./client/session.js";
-import { check, pools, isDirectory, homePath, publicPath } from "./client/spaces.js";
-import { list, info } from "./client/browse.js";
-import { mkdir, rename, move, copy, remove } from "./client/mutate.js";
-import { upload, uploadSliced } from "./client/upload.js";
-import { download, readFile, openDownload } from "./client/download.js";
-import { endpointUrl, formBody, retrying, send, parse, post, DEFAULT_PAGE_SIZE } from "./client/transport.js";
+import { authHeaders, commonParams, identity } from "./client/session.js";
+import { DEFAULT_PAGE_SIZE, endpointUrl, formBody, parse, post, retrying, send } from "./client/transport.js";
+import { uploadSliced } from "./client/upload.js";
+import { openDownload } from "./client/download.js";
+import { dispatch, transportReport } from "./client/router.js";
+import * as webdav from "./client/webdav.js";
 export { ZSpaceError } from "./client/errors.js";
 
 export class ZSpaceClient {
@@ -49,6 +48,12 @@ export class ZSpaceClient {
 	 * @param {number} [options.listMaxEntries] - directory listing ceiling.
 	 * @param {number} [options.smallUploadMaxBytes] - above this, upload sliced.
 	 * @param {number} [options.sliceSize] - sliced upload chunk size.
+	 * @param {"auto"|"webdav"|"relay"} [options.transportMode] - transport preference (default `auto`).
+	 * @param {string} [options.webdavUrl] - WebDAV base URL, e.g. `http://<nas-ip>:5005/`.
+	 * @param {string} [options.webdavUser] - WebDAV user (NAS account); password from `ZS_WEBDAV_PASSWORD`.
+	 * @param {string} [options.webdavHomePath] - DAV path mapped to the personal space (default `/`).
+	 * @param {string} [options.webdavPublicPath] - DAV path mapped to the public space (empty = not exposed).
+	 * @param {number} [options.webdavProbeTimeoutMs] - LAN probe timeout (default 1500).
 	 */
 	constructor(options = {}) {
 		this.baseUrl = resolveBaseUrl(options.baseUrl);
@@ -61,12 +66,22 @@ export class ZSpaceClient {
 		this.listMaxEntries = options.listMaxEntries ?? 2000;
 		this.smallUploadMaxBytes = options.smallUploadMaxBytes ?? 8 * 1024 * 1024;
 		this.sliceSize = options.sliceSize ?? 2 * 1024 * 1024;
+		this.transportMode = options.transportMode || "auto";
+		this.webdavUrl = options.webdavUrl || "";
+		this.webdavUser = options.webdavUser || "";
+		this.webdavPassword = options.webdavPassword || "";
+		this.webdavHomePath = options.webdavHomePath || "/";
+		this.webdavPublicPath = options.webdavPublicPath || "";
+		this.webdavProbeTimeoutMs = options.webdavProbeTimeoutMs ?? 1500;
 		this.configuredHomePath = options.homePath || "";
 		this.configuredPublicPath = options.publicPath || "";
 		this._credentials = options.credentials ?? null;
 		this._homePath = null;
 		this._publicPath = null;
 		this._pools = null;
+		this._webdavProbe = null;
+		this._webdavDownUntil = 0;
+		this._davRoots = null;
 	}
 
 	/**
@@ -98,55 +113,73 @@ export class ZSpaceClient {
 	}
 
 	async check() {
-		return await check(this);
+		return await dispatch(this, "check", []);
 	}
 
 	async pools() {
-		return await pools(this);
+		return await dispatch(this, "pools", []);
 	}
 
 	async isDirectory(remotePath) {
-		return await isDirectory(this, remotePath);
+		return await dispatch(this, "isDirectory", [remotePath]);
 	}
 
 	async homePath() {
-		return await homePath(this);
+		return await dispatch(this, "homePath", []);
 	}
 
 	async publicPath() {
-		return await publicPath(this);
+		return await dispatch(this, "publicPath", []);
 	}
 
 	async list(remotePath, options = {}) {
-		return await list(this, remotePath, options);
+		return await dispatch(this, "list", [remotePath, options]);
 	}
 
 	async info(remotePath) {
-		return await info(this, remotePath);
+		return await dispatch(this, "info", [remotePath]);
 	}
 
 	async mkdir(remotePath) {
-		return await mkdir(this, remotePath);
+		return await dispatch(this, "mkdir", [remotePath]);
 	}
 
 	async rename(remotePath, newName) {
-		return await rename(this, remotePath, newName);
+		return await dispatch(this, "rename", [remotePath, newName]);
 	}
 
 	async move(remotePaths, to) {
-		return await move(this, remotePaths, to);
+		return await dispatch(this, "move", [remotePaths, to]);
 	}
 
 	async copy(remotePaths, to) {
-		return await copy(this, remotePaths, to);
+		return await dispatch(this, "copy", [remotePaths, to]);
 	}
 
 	async remove(remotePaths) {
-		return await remove(this, remotePaths);
+		return await dispatch(this, "remove", [remotePaths]);
 	}
 
 	async upload(localPath, remoteDir, options = {}) {
-		return await upload(this, localPath, remoteDir, options);
+		return await dispatch(this, "upload", [localPath, remoteDir, options]);
+	}
+
+	/**
+	 * Probe the WebDAV fast path (reachability + credentials), as reported by `zspace_status`.
+	 *
+	 * @returns {Promise<{reachable: boolean, usable: boolean, status?: number, reason: string}>} probe result.
+	 */
+	async probeWebdav() {
+		return await webdav.probe(this);
+	}
+
+	/**
+	 * Which transport the next call will use, plus the last probe result.
+	 *
+	 * @returns {Promise<{transport: string, configured: boolean, probe: Record<string, any>|null}>} transport report.
+	 */
+	async transportReport() {
+		return await transportReport(this);
 	}
 
 	async uploadSliced(localPath, target, total, stat, onProgress) {
@@ -154,11 +187,11 @@ export class ZSpaceClient {
 	}
 
 	async download(remotePath, localDir, options = {}) {
-		return await download(this, remotePath, localDir, options);
+		return await dispatch(this, "download", [remotePath, localDir, options]);
 	}
 
 	async readFile(remotePath, options = {}) {
-		return await readFile(this, remotePath, options);
+		return await dispatch(this, "readFile", [remotePath, options]);
 	}
 
 	async openDownload(remotePath) {

package/lib/config.js

@@ -33,6 +33,13 @@ const DEFAULTS = Object.freeze({
 	maxRetries: 2,
 	smallUploadMaxBytes: 8 * 1024 * 1024,
 	sliceSize: 2 * 1024 * 1024,
+	transportMode: "auto",
+	webdavUrl: "",
+	webdavUser: "",
+	webdavPassword: "",
+	webdavHomePath: "/",
+	webdavPublicPath: "",
+	webdavProbeTimeoutMs: 1500,
 	promptEnabled: true,
 	promptOrder: 60,
 });
@@ -64,6 +71,20 @@ export const Config = z.object({
 	smallUploadMaxBytes: z.natural().default(8 * 1024 * 1024),
 	/** Slice size for the sliced upload protocol (NAS remote mode caps at 2 MB). */
 	sliceSize: z.natural().default(2 * 1024 * 1024),
+	/** Transport preference: `auto` (LAN WebDAV when reachable), `webdav`, or `relay`. */
+	transportMode: z.string().default("auto"),
+	/** WebDAV base URL, e.g. `http://<nas-ip>:5005/`; empty disables the fast path. */
+	webdavUrl: z.string().default(""),
+	/** WebDAV user (the NAS account). The password belongs in `ZS_WEBDAV_PASSWORD`, not here. */
+	webdavUser: z.string().default(""),
+	/** WebDAV password fallback; prefer the `ZS_WEBDAV_PASSWORD` environment variable. */
+	webdavPassword: z.string().default(""),
+	/** DAV path that maps to the personal space (default `/` = WebDAV root). */
+	webdavHomePath: z.string().default("/"),
+	/** DAV path that maps to the public space; empty means it is not exposed over WebDAV. */
+	webdavPublicPath: z.string().default(""),
+	/** LAN probe timeout in milliseconds. */
+	webdavProbeTimeoutMs: z.natural().default(1500),
 	/** Whether to contribute the NAS guide to the system prompt. */
 	promptEnabled: z.boolean().default(true),
 	/** Ordering of that section. */
@@ -96,6 +117,7 @@ export function validateConfig(config) {
 		["maxRetries", config.maxRetries],
 		["smallUploadMaxBytes", config.smallUploadMaxBytes],
 		["sliceSize", config.sliceSize],
+		["webdavProbeTimeoutMs", config.webdavProbeTimeoutMs],
 		["promptOrder", config.promptOrder],
 	];
 	for (const [field, value] of bounds) {
@@ -103,6 +125,18 @@ export function validateConfig(config) {
 			throw new Error(`zspace: 配置项 ${field}=${value} 必须是非负整数（maxRetries 可为 0，其余至少为 1）`);
 		}
 	}
+	if (!["auto", "webdav", "relay"].includes(config.transportMode)) {
+		throw new Error(`zspace: transportMode=${config.transportMode} 必须是 auto / webdav / relay 之一`);
+	}
+	if (config.transportMode === "webdav" && !config.webdavUrl) {
+		throw new Error("zspace: transportMode=webdav 时必须配置 webdavUrl");
+	}
+	if (config.webdavUrl && !/^https?:\/\//.test(config.webdavUrl)) {
+		throw new Error(`zspace: webdavUrl 必须以 http:// 或 https:// 开头（当前 ${config.webdavUrl}）`);
+	}
+	if (!config.webdavHomePath.startsWith("/")) {
+		throw new Error(`zspace: webdavHomePath 必须以 / 开头（当前 ${config.webdavHomePath}）`);
+	}
 	if (!/^https?:\/\//.test(config.baseUrl)) {
 		throw new Error(`zspace: baseUrl 必须以 http:// 或 https:// 开头（当前 ${config.baseUrl}）`);
 	}

package/lib/index.js

@@ -44,6 +44,13 @@ export function apply(ctx, config) {
 			listMaxEntries: settings.listMaxEntries,
 			smallUploadMaxBytes: settings.smallUploadMaxBytes,
 			sliceSize: settings.sliceSize,
+			transportMode: settings.transportMode,
+			webdavUrl: settings.webdavUrl,
+			webdavUser: settings.webdavUser,
+			webdavPassword: settings.webdavPassword,
+			webdavHomePath: settings.webdavHomePath,
+			webdavPublicPath: settings.webdavPublicPath,
+			webdavProbeTimeoutMs: settings.webdavProbeTimeoutMs,
 		});
 		return () => {
 			client = undefined;

package/lib/tools/status.js

@@ -11,7 +11,7 @@ export function createStatusTool(ctx) {
 	return {
 		name: "zspace_status",
 		description:
-			"Check the 极空间 / ZSpace NAS link behind this plugin. Probes the desktop client's local proxy, resolves the personal-space and public-space roots, reports storage pools with free space, and lists both roots once. Run it first when another zspace_* tool fails, or to confirm cross-network access (no LAN/WebDAV/SSH needed).",
+			"Check the 极空间 / ZSpace NAS link behind this plugin. Reports which transport is in use (direct WebDAV on the same network, or the desktop client's cloud relay when away), probes the relay, resolves the personal-space and public-space roots, reports storage pools with free space, and lists both roots once. Run it first when another zspace_* tool fails.",
 		parameters: {},
 		outputSchema: {
 			type: "object",
@@ -39,6 +39,9 @@ export function createStatusTool(ctx) {
 						},
 					},
 				},
+				transport: { type: "string", required: true },
+				webdavUrl: { type: "string", required: true },
+				webdavProbe: { type: "string", required: true },
 				message: { type: "string", required: true },
 			},
 		},
@@ -52,7 +55,10 @@ export function createStatusTool(ctx) {
 				{
 					type: "text",
 					text: [
-						`极空间在线：${value.username || "(未知账号)"} @ ${value.nasId}，代理 ${value.baseUrl}`,
+						`极空间在线：${value.username || "(未知账号)"} @ ${value.nasId}`,
+						value.transport === "webdav"
+							? `通道：WebDAV 直连（${value.webdavUrl}）— 同网络快路径`
+							: `通道：桌面客户端云中转（${value.baseUrl}）${value.webdavUrl ? `；WebDAV 未启用：${value.webdavProbe}` : ""}`,
 						`个人空间 ${value.homePath}（${value.homeEntries} 项）`,
 						`公共空间 ${value.publicPath}（${value.publicEntries} 项）`,
 						pools ? `存储池：\n${pools}` : "存储池：未获取到",
@@ -64,11 +70,16 @@ export function createStatusTool(ctx) {
 			guarded(async () => {
 				const client = getClient();
 				const baseUrl = client.baseUrl;
-				const proxy = await client.check();
-				if (!proxy) {
+				const transport = await client.transportReport();
+				const webdavProbe = transport.probe?.reason ?? (transport.configured ? "尚未探测" : `未完整配置（需要 webdavUrl + ZS_WEBDAV_PASSWORD）`);
+				const reachable = await client.check().catch(() => false);
+				if (!reachable) {
 					return {
 						ok: false,
 						baseUrl,
+						transport: transport.transport,
+						webdavUrl: client.webdavUrl ?? "",
+						webdavProbe,
 						username: "",
 						nasId: "",
 						homePath: "",
@@ -76,7 +87,9 @@ export function createStatusTool(ctx) {
 						homeEntries: 0,
 						publicEntries: 0,
 						pools: [],
-						message: `连不上极空间桌面客户端本地代理 ${baseUrl}：请确认桌面客户端已安装、已登录并在运行（跨网络访问也依赖它做云中转）。`,
+						message:
+							`两条通道都不可用：WebDAV ${client.webdavUrl ? webdavProbe : "未配置"}；桌面客户端本地代理 ${baseUrl} 无响应。` +
+							" 同网络时请在极空间开启 WebDAV 并设置 ZS_WEBDAV_PASSWORD；跨网络时需要桌面客户端已登录并运行。",
 					};
 				}
 				const identity = client.identity;
@@ -102,6 +115,9 @@ export function createStatusTool(ctx) {
 				return {
 					ok: home.error === "" || publicSpace.error === "",
 					baseUrl,
+					transport: transport.transport,
+					webdavUrl: client.webdavUrl ?? "",
+					webdavProbe,
 					username: identity.username,
 					nasId: identity.nasId,
 					homePath: home.value.root,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-zspace",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "极空间（ZSpace）NAS plugin for DeepSeek Harness: cross-network agent tools for browsing, searching, reading, uploading and organizing NAS files through the desktop client's relay — no LAN, no WebDAV, no SSH, no Python.",
   "type": "module",
   "license": "MIT",