dsh-zspace 0.1.0 → 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/README.md

@@ -91,10 +91,24 @@ dsh plugin --profile desktop add /绝对路径/dsh-zspace-0.1.0.tgz
   - 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   # 27 项单测/集成（mock 代理）
+node --test test/client.test.js test/tools.test.js test/adaptor.test.js   # 28 项单测/集成（mock 代理）
 node scripts/live-selftest.js                                            # 真机端到端自检（会创建并清理临时目录）
 ```
 

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/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.
+ */

package/lib/client/errors.js

@@ -0,0 +1,56 @@
+/**
+ * NAS business codes and the single error type every layer raises.
+ *
+ * @module dsh-zspace/client
+ */
+
+/**
+ * Business codes the desktop client treats as fatal during sliced uploads —
+ * retrying them only burns time (permission / conflicting dir / safe-box).
+ */
+export const UPLOAD_FATAL_CODES = new Set(["N001302", "N001331", "N001603", "N001397"]);
+
+/**
+ * One ZSpace API or transport failure.
+ *
+ * `code` is the NAS business code (`N001411`, …) when the response parsed,
+ * or a synthetic marker (`HTTP413`, `EPROXY`, …) otherwise.
+ */
+export class ZSpaceError extends Error {
+/**
+ * @param {string} code - NAS business code or synthetic marker.
+ * @param {string} message - human-readable message.
+ * @param {{endpoint?: string, cause?: unknown}} [options] - context.
+ */
+constructor(code, message, options = {}) {
+	super(message, options.cause === undefined ? undefined : { cause: options.cause });
+	this.name = "ZSpaceError";
+	this.code = String(code);
+	this.endpoint = options.endpoint ?? "";
+}
+
+/**
+ * Actionable next step for known codes, or `undefined`.
+ *
+ * @returns {string|undefined} hint text.
+ */
+get hint() {
+	const message = this.message;
+	if (this.code === "N001411" || /无权限/.test(message)) {
+		return "没有权限：确认该账号对目标路径可访问（「/」与裸盘根目录总是拒绝的，先 ls 已知的空间根，例如 home: 或 public:）。";
+	}
+	if (this.code === "N001315" || /不存在/.test(message)) {
+		return "路径不存在：先列出上级目录确认拼写，注意大小写与中文全角字符。";
+	}
+	if (this.code === "N001212") {
+		return "参数有误：路径必须以 / 开头（或用 home: / public: / 相对路径）。";
+	}
+	if (this.code === "HTTP413") {
+		return "本地代理拒绝超大请求体：大文件会自动改走分片上传，若仍失败请降低分片大小。";
+	}
+	if (this.code === "EPROXY") {
+		return "连不上极空间桌面客户端本地代理：确认客户端已安装、已登录并在运行（端口 13579）。";
+	}
+	return undefined;
+}
+}

package/lib/client/mutate.js

@@ -0,0 +1,103 @@
+/**
+ * Server-side mutations: mkdir, rename, move, copy, remove.
+ *
+ * @module dsh-zspace/client
+ */
+
+import { splitRemote, toEntry } from "../format.js";
+
+/**
+ * Create one directory.
+ *
+ * @param {string} remotePath - absolute path of the new directory.
+ * @returns {Promise<ReturnType<typeof toEntry>>} the created entry.
+ */
+export async function mkdir(client, remotePath) {
+	const { parent, name } = splitRemote(remotePath);
+	const data = await client.post("/v2/file/newdir", { parent, name, rename: "0" });
+	return toEntry(data ?? {});
+}
+
+/**
+ * Rename a file or directory in place.
+ *
+ * @param {string} remotePath - absolute current path.
+ * @param {string} newName - new base name (no directory part).
+ * @returns {Promise<ReturnType<typeof toEntry>>} the renamed entry.
+ */
+
+/**
+ * Rename a file or directory in place.
+ *
+ * @param {string} remotePath - absolute current path.
+ * @param {string} newName - new base name (no directory part).
+ * @returns {Promise<ReturnType<typeof toEntry>>} the renamed entry.
+ */
+export async function rename(client, remotePath, newName) {
+	const data = await client.post("/v2/file/modify", { path: remotePath, newname: newName });
+	return toEntry(data ?? {});
+}
+
+/**
+ * Move files or directories into a target directory.
+ *
+ * @param {string[]} remotePaths - absolute source paths.
+ * @param {string} to - absolute destination directory.
+ * @returns {Promise<void>} resolves when the NAS accepted the move.
+ */
+
+/**
+ * Move files or directories into a target directory.
+ *
+ * @param {string[]} remotePaths - absolute source paths.
+ * @param {string} to - absolute destination directory.
+ * @returns {Promise<void>} resolves when the NAS accepted the move.
+ */
+export async function move(client, remotePaths, to) {
+	await client.post("/v2/file/move", { paths: remotePaths, to });
+}
+
+/**
+ * Copy files or directories into a target directory.
+ *
+ * @param {string[]} remotePaths - absolute source paths.
+ * @param {string} to - absolute destination directory.
+ * @returns {Promise<void>} resolves when the NAS accepted the copy.
+ */
+
+/**
+ * Copy files or directories into a target directory.
+ *
+ * @param {string[]} remotePaths - absolute source paths.
+ * @param {string} to - absolute destination directory.
+ * @returns {Promise<void>} resolves when the NAS accepted the copy.
+ */
+export async function copy(client, remotePaths, to) {
+	await client.post("/v2/file/copy", { paths: remotePaths, to });
+}
+
+/**
+ * Delete files or directories (the NAS moves them to its recycle bin).
+ *
+ * @param {string[]} remotePaths - absolute paths to remove.
+ * @returns {Promise<void>} resolves when the NAS accepted the deletion.
+ */
+
+/**
+ * Delete files or directories (the NAS moves them to its recycle bin).
+ *
+ * @param {string[]} remotePaths - absolute paths to remove.
+ * @returns {Promise<void>} resolves when the NAS accepted the deletion.
+ */
+export async function remove(client, remotePaths) {
+	await client.post("/v2/file/remove", { paths: remotePaths });
+}
+
+/**
+ * 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.
+ */

package/lib/client/session.js

@@ -0,0 +1,79 @@
+/**
+ * Session view of the desktop client's login state: cookies, common params, safe identity.
+ *
+ * @module dsh-zspace/client
+ */
+
+/**
+ * Auth cookies for every request.
+ *
+ * @returns {Record<string, string>} request headers carrying the session.
+ */
+export function authHeaders(client) {
+	const creds = client.credentials;
+	return {
+		Cookie: [
+			`token=${creds.token}`,
+			`zenithtoken=${creds.token}`,
+			`nas_id=${creds.nasId}`,
+			`nasid=${creds.nasId}`,
+			`device_id=${creds.deviceId}`,
+		].join("; "),
+	};
+}
+
+/**
+ * Common form fields. These belong in the request **body**; the NAS rejects
+ * them in the query string with `N001212`.
+ *
+ * @returns {Record<string, string>} common fields.
+ */
+
+/**
+ * Common form fields. These belong in the request **body**; the NAS rejects
+ * them in the query string with `N001212`.
+ *
+ * @returns {Record<string, string>} common fields.
+ */
+export function commonParams(client) {
+	const creds = client.credentials;
+	return {
+		token: creds.token,
+		nasid: creds.nasId,
+		plat: "web",
+		version: client.apiVersion,
+		device_id: creds.deviceId,
+		_l: "zh_cn",
+	};
+}
+
+/**
+ * Build an endpoint URL with the mandatory random query suffix.
+ *
+ * @param {string} endpoint - API path, e.g. `/v2/file/list`.
+ * @param {Record<string, unknown>} [query] - extra query values.
+ * @returns {string} absolute URL.
+ */
+
+/**
+ * Identity of the account this client acts as (no secrets).
+ *
+ * @returns {{username: string, nasId: string, deviceId: string, vuexPath: string}} safe identity fields.
+ */
+export function identity(client) {
+	const creds = client.credentials;
+	return {
+		username: creds.username ?? "",
+		nasId: creds.nasId ?? "",
+		deviceId: creds.deviceId ?? "",
+		vuexPath: creds.vuexPath ?? "",
+	};
+}
+
+// ── transport ────────────────────────────────────────────────────────────
+
+/**
+ * Auth cookies for every request.
+ *
+ * @returns {Record<string, string>} request headers carrying the session.
+ */