dsh-zspace 0.1.0 → 0.1.2

package/lib/config.js

@@ -0,0 +1,109 @@
+/**
+ * Plugin configuration: the schema the host validates against, the code-side
+ * defaults (so direct construction works without the loader), and the bounds
+ * check that fails at load time instead of at the first tool call.
+ *
+ * @module dsh-zspace/config
+ */
+
+import z from "@deepseek-ai/schemastery";
+
+import { DEFAULT_API_VERSION, DEFAULT_BASE_URL } from "./auth.js";
+
+/**
+ * Code-side defaults.
+ *
+ * The Cordis loader already applies `Config`'s defaults, but `apply` is also
+ * reachable through direct construction (tests, tooling), so the plugin
+ * resolves its own defaults instead of trusting the caller.
+ *
+ * @type {Record<string, any>}
+ */
+const DEFAULTS = Object.freeze({
+	baseUrl: DEFAULT_BASE_URL,
+	configDir: "",
+	apiVersion: DEFAULT_API_VERSION,
+	homePath: "",
+	publicPath: "",
+	downloadDir: "",
+	readMaxBytes: 262_144,
+	writeMaxBytes: 5 * 1024 * 1024,
+	listMaxEntries: 2000,
+	timeoutMs: 60_000,
+	maxRetries: 2,
+	smallUploadMaxBytes: 8 * 1024 * 1024,
+	sliceSize: 2 * 1024 * 1024,
+	promptEnabled: true,
+	promptOrder: 60,
+});
+
+export const Config = z.object({
+	/** Desktop client local proxy. */
+	baseUrl: z.string().default(DEFAULT_BASE_URL),
+	/** Explicit directory holding `vuex.json`; empty means auto-detect. */
+	configDir: z.string().default(""),
+	/** NAS web API version sent as the `version` parameter. */
+	apiVersion: z.string().default(DEFAULT_API_VERSION),
+	/** Personal-space root override; empty means discover from storage pools. */
+	homePath: z.string().default(""),
+	/** Public-space root override; empty means discover from storage pools. */
+	publicPath: z.string().default(""),
+	/** Default local directory for downloads; empty means `~/Downloads/zspace`. */
+	downloadDir: z.string().default(""),
+	/** Byte cap for `zspace_read`. */
+	readMaxBytes: z.natural().default(262_144),
+	/** Byte cap for `zspace_write` text content (bigger writes belong in `zspace_upload`). */
+	writeMaxBytes: z.natural().default(5 * 1024 * 1024),
+	/** Entry ceiling for one listing/tree call. */
+	listMaxEntries: z.natural().default(2000),
+	/** Per-request timeout in milliseconds. */
+	timeoutMs: z.natural().default(60_000),
+	/** Retries for transient transport/5xx failures. */
+	maxRetries: z.natural().default(2),
+	/** Files above this size upload with the sliced protocol. */
+	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),
+	/** Whether to contribute the NAS guide to the system prompt. */
+	promptEnabled: z.boolean().default(true),
+	/** Ordering of that section. */
+	promptOrder: z.natural().default(60),
+});
+
+/**
+ * Merge caller config over the defaults, ignoring explicit `undefined`.
+ *
+ * @param {Record<string, any>|undefined} config - caller config.
+ * @returns {Record<string, any>} effective config.
+ */
+export function resolveConfig(config) {
+	const given = Object.fromEntries(Object.entries(config ?? {}).filter(([, value]) => value !== undefined));
+	return { ...DEFAULTS, ...given };
+}
+
+/**
+ * Reject unusable configuration at load time instead of at the first tool call.
+ *
+ * @param {Record<string, any>} config - schema-validated config.
+ * @throws {Error} when a numeric bound is not a positive integer.
+ */
+export function validateConfig(config) {
+	const bounds = [
+		["readMaxBytes", config.readMaxBytes],
+		["writeMaxBytes", config.writeMaxBytes],
+		["listMaxEntries", config.listMaxEntries],
+		["timeoutMs", config.timeoutMs],
+		["maxRetries", config.maxRetries],
+		["smallUploadMaxBytes", config.smallUploadMaxBytes],
+		["sliceSize", config.sliceSize],
+		["promptOrder", config.promptOrder],
+	];
+	for (const [field, value] of bounds) {
+		if (!Number.isInteger(value) || value < 0 || (field !== "maxRetries" && value < 1)) {
+			throw new Error(`zspace: 配置项 ${field}=${value} 必须是非负整数（maxRetries 可为 0，其余至少为 1）`);
+		}
+	}
+	if (!/^https?:\/\//.test(config.baseUrl)) {
+		throw new Error(`zspace: baseUrl 必须以 http:// 或 https:// 开头（当前 ${config.baseUrl}）`);
+	}
+}

package/lib/index.js

@@ -5,146 +5,27 @@
  * proxy, which relays to the NAS over 极空间's cloud/P2P channel. No LAN
  * address, no DDNS, no WebDAV, no SSH, no Python.
  *
- * This module is the thin host adapter: it validates config, owns the client
- * lifecycle, contributes one system-prompt section, and converts the plain
- * tool specs from `./tools.js` into registered host tools.
+ * This entry point only wires things together: it validates config, owns the
+ * client lifecycle, contributes the guide section, and registers the tools
+ * described in `./tools/`. Configuration lives in `./config.js`, the guide text
+ * in `./prompt.js`, the protocol in `./client/`.
  *
  * @module dsh-zspace
  */
 
-import z from "@deepseek-ai/schemastery";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 
-import { DEFAULT_API_VERSION, DEFAULT_BASE_URL } from "./auth.js";
 import { ZSpaceClient } from "./client.js";
+import { Config, resolveConfig, validateConfig } from "./config.js";
+import { guideText } from "./prompt.js";
 import { createToolSpecs } from "./tools.js";
 
 export const name = "zspace";
 
 export const inject = ["tools", "systemPrompt"];
 
-export const Config = z.object({
-	/** Desktop client local proxy. */
-	baseUrl: z.string().default(DEFAULT_BASE_URL),
-	/** Explicit directory holding `vuex.json`; empty means auto-detect. */
-	configDir: z.string().default(""),
-	/** NAS web API version sent as the `version` parameter. */
-	apiVersion: z.string().default(DEFAULT_API_VERSION),
-	/** Personal-space root override; empty means discover from storage pools. */
-	homePath: z.string().default(""),
-	/** Public-space root override; empty means discover from storage pools. */
-	publicPath: z.string().default(""),
-	/** Default local directory for downloads; empty means `~/Downloads/zspace`. */
-	downloadDir: z.string().default(""),
-	/** Byte cap for `zspace_read`. */
-	readMaxBytes: z.natural().default(262_144),
-	/** Entry ceiling for one listing/tree call. */
-	listMaxEntries: z.natural().default(2000),
-	/** Per-request timeout in milliseconds. */
-	timeoutMs: z.natural().default(60_000),
-	/** Retries for transient transport/5xx failures. */
-	maxRetries: z.natural().default(2),
-	/** Files above this size upload with the sliced protocol. */
-	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),
-	/** Whether to contribute the NAS guide to the system prompt. */
-	promptEnabled: z.boolean().default(true),
-	/** Ordering of that section. */
-	promptOrder: z.natural().default(60),
-});
+export { Config };
 
-/**
- * Code-side defaults.
- *
- * The Cordis loader already applies `Config`'s defaults, but `apply` is also
- * reachable through direct construction (tests, tooling), so the plugin
- * resolves its own defaults instead of trusting the caller.
- *
- * @type {Record<string, any>}
- */
-const DEFAULTS = Object.freeze({
-	baseUrl: DEFAULT_BASE_URL,
-	configDir: "",
-	apiVersion: DEFAULT_API_VERSION,
-	homePath: "",
-	publicPath: "",
-	downloadDir: "",
-	readMaxBytes: 262_144,
-	listMaxEntries: 2000,
-	timeoutMs: 60_000,
-	maxRetries: 2,
-	smallUploadMaxBytes: 8 * 1024 * 1024,
-	sliceSize: 2 * 1024 * 1024,
-	promptEnabled: true,
-	promptOrder: 60,
-});
-
-/**
- * Merge caller config over the defaults, ignoring explicit `undefined`.
- *
- * @param {Record<string, any>|undefined} config - caller config.
- * @returns {Record<string, any>} effective config.
- */
-function resolveConfig(config) {
-	const given = Object.fromEntries(Object.entries(config ?? {}).filter(([, value]) => value !== undefined));
-	return { ...DEFAULTS, ...given };
-}
-
-/**
- * Reject unusable configuration at load time instead of at the first tool call.
- *
- * @param {Record<string, any>} config - schema-validated config.
- * @throws {Error} when a numeric bound is not a positive integer.
- */
-function validateConfig(config) {
-	const bounds = [
-		["readMaxBytes", config.readMaxBytes],
-		["listMaxEntries", config.listMaxEntries],
-		["timeoutMs", config.timeoutMs],
-		["maxRetries", config.maxRetries],
-		["smallUploadMaxBytes", config.smallUploadMaxBytes],
-		["sliceSize", config.sliceSize],
-		["promptOrder", config.promptOrder],
-	];
-	for (const [field, value] of bounds) {
-		if (!Number.isInteger(value) || value < 0 || (field !== "maxRetries" && value < 1)) {
-			throw new Error(`zspace: 配置项 ${field}=${value} 必须是非负整数（maxRetries 可为 0，其余至少为 1）`);
-		}
-	}
-	if (!/^https?:\/\//.test(config.baseUrl)) {
-		throw new Error(`zspace: baseUrl 必须以 http:// 或 https:// 开头（当前 ${config.baseUrl}）`);
-	}
-}
-
-/**
- * The system-prompt section describing the NAS and its path conveniences.
- *
- * @param {Record<string, any>} config - plugin config.
- * @returns {string} guide text.
- */
-function guideText(config) {
-	const down = config.downloadDir || "~/Downloads/zspace";
-	return [
-		"### 极空间 NAS（dsh-zspace）",
-		"已通过极空间桌面客户端的本地代理接入这台 NAS，**跨网络可用**（不需要同一局域网、WebDAV 或 SSH，仅要求本机桌面客户端保持登录）。",
-		"- 远程路径写法：`home:`＝个人空间根、`public:`＝公共空间根、相对路径＝相对个人空间、以 `/` 开头＝NAS 绝对路径；两个根的真实位置先跑 `zspace_status` 查看。",
-		"- 只读：`zspace_ls`（支持 depth 递归）、`zspace_stat`、`zspace_find`（按名称在目录树里遍历查找，受 depth/scanLimit 预算限制，结果里会报告扫了多少项）、`zspace_read`（小文本读入上下文）、`zspace_download`（下载到本机，默认 " +
-			down +
-			"）。",
-		"- 写入：`zspace_upload`（大文件自动分片、支持中文名）、`zspace_mkdir`、`zspace_rename`、`zspace_move`、`zspace_copy`、`zspace_remove`（进回收站，必须显式 confirm=true）。",
-		"- 删除/移动/重命名属于破坏性操作：先用 `zspace_ls` 或 `zspace_stat` 核实目标，再执行；批量删除前先向用户确认。",
-	].join("\n");
-}
-
-/**
- * Mount the plugin: own the client lifecycle, add the guide section, register
- * every tool.
- *
- * @param {import("@deepseek-ai/cordis").Context} ctx - plugin context.
- * @param {Record<string, any>} config - validated config.
- * @returns {void}
- */
 export function apply(ctx, config) {
 	const settings = resolveConfig(config);
 	validateConfig(settings);

package/lib/prompt.js

@@ -0,0 +1,26 @@
+/**
+ * The system-prompt section that teaches the model this NAS's path conventions
+ * and which tools to reach for. Only injected when `promptEnabled` is true.
+ *
+ * @module dsh-zspace/prompt
+ */
+
+export /**
+ * The system-prompt section describing the NAS and its path conveniences.
+ *
+ * @param {Record<string, any>} config - plugin config.
+ * @returns {string} guide text.
+ */
+function guideText(config) {
+	const down = config.downloadDir || "~/Downloads/zspace";
+	return [
+		"### 极空间 NAS（dsh-zspace）",
+		"已通过极空间桌面客户端的本地代理接入这台 NAS，**跨网络可用**（不需要同一局域网、WebDAV 或 SSH，仅要求本机桌面客户端保持登录）。",
+		"- 远程路径写法：`home:`＝个人空间根、`public:`＝公共空间根、相对路径＝相对个人空间、以 `/` 开头＝NAS 绝对路径；两个根的真实位置先跑 `zspace_status` 查看。",
+		"- 只读：`zspace_ls`（支持 depth 递归）、`zspace_stat`、`zspace_find`（按名称在目录树里遍历查找，受 depth/scanLimit 预算限制，结果里会报告扫了多少项）、`zspace_read`（小文本读入上下文）、`zspace_download`（下载到本机，默认 " +
+			down +
+			"）。",
+		"- 写入：`zspace_upload`（大文件自动分片、支持中文名）、`zspace_mkdir`、`zspace_rename`、`zspace_move`、`zspace_copy`、`zspace_remove`（进回收站，必须显式 confirm=true）。",
+		"- 删除/移动/重命名属于破坏性操作：先用 `zspace_ls` 或 `zspace_stat` 核实目标，再执行；批量删除前先向用户确认。",
+	].join("\n");
+}

package/lib/tools/copy.js

@@ -0,0 +1,37 @@
+/**
+ * `zspace_copy` — one atomic capability.
+ *
+ * @module dsh-zspace/tools
+ */
+
+export function createCopyTool(ctx) {
+	const { getClient, guarded, resolve } = ctx;
+	return {
+		name: "zspace_copy",
+		description: "Copy files or directories into another directory on the 极空间 / ZSpace NAS (server-side copy, no download).",
+		parameters: {
+			paths: { type: "array", required: true, items: { type: "string" }, description: "Source paths." },
+			to: { type: "string", required: true, description: "Destination directory." },
+		},
+		outputSchema: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				ok: { type: "boolean", required: true },
+				count: { type: "integer", required: true },
+				to: { type: "string", required: true },
+			},
+		},
+		call: (args) => ({ card: "generic", title: `zspace_copy ${(args.paths ?? []).length} 项`, kind: "edit" }),
+		render: (_args, value) => [{ type: "text", text: `已复制 ${value.count} 项 → ${value.to}` }],
+		execute: (args) =>
+			guarded(async () => {
+				const client = getClient();
+				const sources = await Promise.all((args.paths ?? []).map(item => resolve(item)));
+				if (sources.length === 0) throw new Error("zspace_copy: `paths` must not be empty");
+				const destination = await resolve(args.to);
+				await client.copy(sources, destination);
+				return { ok: true, count: sources.length, to: destination };
+			}),
+	};
+}

package/lib/tools/download.js

@@ -0,0 +1,44 @@
+/**
+ * `zspace_download` — one atomic capability.
+ *
+ * @module dsh-zspace/tools
+ */
+
+import path from "node:path";
+import { humanSize } from "../format.js";
+
+export function createDownloadTool(ctx) {
+	const { config, downloadDir, expandLocalPath, getClient, guarded, resolve } = ctx;
+	return {
+		name: "zspace_download",
+		description:
+			"Download one file from the 极空间 / ZSpace NAS to this machine (跨网络可用). Returns the absolute local path. Default local directory: " +
+			`${config.downloadDir || "~/Downloads/zspace"}.`,
+		parameters: {
+			path: { type: "string", required: true, description: "Remote file path." },
+			dir: { type: "string", description: "Local destination directory. Pass an absolute path or `~/…` (a plain relative path resolves against the DSH host process directory). Default: the configured download directory." },
+			name: { type: "string", description: "Local file name override (default: the remote base name)." },
+		},
+		outputSchema: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				remotePath: { type: "string", required: true },
+				localPath: { type: "string", required: true },
+				bytes: { type: "integer", required: true },
+			},
+		},
+		call: (args) => ({ card: "generic", title: `zspace_download ${args.path}`, kind: "edit" }),
+		render: (_args, value) => [
+			{ type: "text", text: `已下载 ${value.remotePath} → ${value.localPath}（${humanSize(value.bytes)}）` },
+		],
+		execute: (args) =>
+			guarded(async () => {
+				const client = getClient();
+				const target = await resolve(args.path);
+				const localDir = expandLocalPath(args.dir) || downloadDir();
+				const result = await client.download(target, localDir, { name: args.name });
+				return { remotePath: target, localPath: result.localPath, bytes: result.bytes };
+			}),
+	};
+}

package/lib/tools/find.js

@@ -0,0 +1,76 @@
+/**
+ * `zspace_find` — one atomic capability.
+ *
+ * @module dsh-zspace/tools
+ */
+
+export function createFindTool(ctx) {
+	const { clampInt, entryLine, findByName, getClient, guarded, resolve } = ctx;
+	return {
+		name: "zspace_find",
+		description:
+			"Find files or folders by name inside the 极空间 / ZSpace tree (case-insensitive substring). It scans directories, so it is bounded: pass `path` to narrow the search, and raise `depth` / `scanLimit` when you need more coverage. The result reports how many entries were inspected and whether the scan stopped early — always mention that when reporting a negative result.",
+		parameters: {
+			keyword: { type: "string", required: true, description: "Name fragment to look for (case-insensitive)." },
+			path: { type: "string", description: "Directory to scan (absolute, home:/, public:/, or relative). Default: scan both the personal space and the public space." },
+			depth: { type: "integer", description: "Maximum recursion depth, 1-8 (default 4)." },
+			limit: { type: "integer", description: "Maximum matches to return, 1-500 (default 50)." },
+			scanLimit: { type: "integer", description: "Maximum entries to inspect, 1-20000 (default 2000)." },
+		},
+		outputSchema: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				keyword: { type: "string", required: true },
+				roots: { type: "array", required: true, items: { type: "string" } },
+				matches: {
+					type: "array",
+					required: true,
+					items: {
+						type: "object",
+						additionalProperties: false,
+						properties: {
+							name: { type: "string", required: true },
+							path: { type: "string", required: true },
+							dir: { type: "boolean", required: true },
+							size: { type: "integer", required: true },
+							modified: { type: "string", required: true },
+						},
+					},
+				},
+				scanned: { type: "integer", required: true },
+				truncated: { type: "boolean", required: true },
+			},
+		},
+		call: (args) => ({ card: "generic", title: `zspace_find ${args.keyword}`, kind: "search" }),
+		render: (_args, value) => {
+			const scope = value.roots.join("、");
+			const tail = value.truncated ? `（已扫 ${value.scanned} 项后停止，结果可能不完整）` : `（已扫 ${value.scanned} 项）`;
+			return [
+				{
+					type: "text",
+					text:
+						value.matches.length === 0
+							? `在 ${scope} 中没有找到名称含「${value.keyword}」的文件 ${tail}`
+							: `${value.matches.map(entry => entryLine(entry)).join("\n")}\n共 ${value.matches.length} 项，范围 ${scope} ${tail}`,
+				},
+			];
+		},
+		execute: (args) =>
+			guarded(async () => {
+				const client = getClient();
+				const keyword = String(args.keyword ?? "").trim();
+				if (keyword === "") throw new Error("zspace_find: `keyword` must not be blank");
+				const roots = args.path ? [await resolve(args.path)] : [await client.homePath(), await client.publicPath()];
+				const { matches, scanned, truncated } = await findByName({
+					client,
+					roots,
+					keyword,
+					depth: clampInt(args.depth, 4, 1, 8),
+					limit: clampInt(args.limit, 50, 1, 500),
+					scanLimit: clampInt(args.scanLimit, 2000, 1, 20_000),
+				});
+				return { keyword, roots, matches, scanned, truncated };
+			}),
+	};
+}

package/lib/tools/ls.js

@@ -0,0 +1,72 @@
+/**
+ * `zspace_ls` — one atomic capability.
+ *
+ * @module dsh-zspace/tools
+ */
+
+export function createLsTool(ctx) {
+	const { clampInt, config, entryLine, getClient, guarded, resolve, walkDirectory } = ctx;
+	return {
+		name: "zspace_ls",
+		description:
+			"List a 极空间 / ZSpace NAS directory (跨网络可用). `path` accepts an absolute NAS path, `home:` / `public:` prefixes, or a path relative to the personal space; omit it for the personal-space root. Set `depth` > 1 to walk a subtree. Large directories are paged automatically.",
+		parameters: {
+			path: { type: "string", description: "Remote directory. Absolute (/<pool>/my/data/…), home:/…, public:/…, or relative to the personal space. Omit for the personal-space root." },
+			depth: { type: "integer", description: "How many levels to list, 1-6 (default 1)." },
+			showHidden: { type: "boolean", description: "Include hidden entries (default false)." },
+			limit: { type: "integer", description: `Maximum entries to return (default 200, cap ${config.listMaxEntries}).` },
+		},
+		outputSchema: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				root: { type: "string", required: true },
+				entries: {
+					type: "array",
+					required: true,
+					items: {
+						type: "object",
+						additionalProperties: false,
+						properties: {
+							name: { type: "string", required: true },
+							path: { type: "string", required: true },
+							dir: { type: "boolean", required: true },
+							size: { type: "integer", required: true },
+							modified: { type: "string", required: true },
+							depth: { type: "integer", required: true },
+						},
+					},
+				},
+				count: { type: "integer", required: true },
+				truncated: { type: "boolean", required: true },
+			},
+		},
+		call: (args) => ({ card: "generic", title: `zspace_ls ${args.path ?? "home:"}`, kind: "search" }),
+		render: (_args, value) => {
+			const lines = value.entries.map(entry => entryLine(entry, true));
+			const tail = value.truncated ? `\n… 结果被截断（只显示前 ${value.count} 项，可提高 limit 或缩小范围）` : "";
+			return [
+				{
+					type: "text",
+					text: `${value.root}（${value.count} 项）\n${lines.join("\n") || "(空目录)"}${tail}`,
+				},
+			];
+		},
+		presentationMeta: (_args, value) => ({ count: value.count }),
+		execute: (args) =>
+			guarded(async () => {
+				const client = getClient();
+				const root = await resolve(args.path);
+				const depth = clampInt(args.depth, 1, 1, 6);
+				const budget = clampInt(args.limit, 200, 1, config.listMaxEntries);
+				const { entries, truncated } = await walkDirectory({
+					client,
+					root,
+					depth,
+					showHidden: args.showHidden === true,
+					budget,
+				});
+				return { root, entries, count: entries.length, truncated };
+			}),
+	};
+}

package/lib/tools/mkdir.js

@@ -0,0 +1,34 @@
+/**
+ * `zspace_mkdir` — one atomic capability.
+ *
+ * @module dsh-zspace/tools
+ */
+
+export function createMkdirTool(ctx) {
+	const { getClient, guarded, resolve } = ctx;
+	return {
+		name: "zspace_mkdir",
+		description: "Create one directory on the 极空间 / ZSpace NAS.",
+		parameters: {
+			path: { type: "string", required: true, description: "Remote directory to create (absolute, home:/, public:/, or relative to the personal space)." },
+		},
+		outputSchema: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				ok: { type: "boolean", required: true },
+				path: { type: "string", required: true },
+			},
+		},
+		call: (args) => ({ card: "generic", title: `zspace_mkdir ${args.path}`, kind: "edit" }),
+		render: (_args, value) => [{ type: "text", text: `已创建目录 ${value.path}` }],
+		execute: (args) =>
+			guarded(async () => {
+				const client = getClient();
+				const target = await resolve(args.path);
+				if (target === "/") throw new Error("zspace_mkdir: 不能创建根目录");
+				await client.mkdir(target);
+				return { ok: true, path: target };
+			}),
+	};
+}

package/lib/tools/move.js

@@ -0,0 +1,37 @@
+/**
+ * `zspace_move` — one atomic capability.
+ *
+ * @module dsh-zspace/tools
+ */
+
+export function createMoveTool(ctx) {
+	const { getClient, guarded, resolve } = ctx;
+	return {
+		name: "zspace_move",
+		description: "Move files or directories into another directory on the 极空间 / ZSpace NAS.",
+		parameters: {
+			paths: { type: "array", required: true, items: { type: "string" }, description: "Source paths (absolute, home:/, public:/, or relative)." },
+			to: { type: "string", required: true, description: "Destination directory." },
+		},
+		outputSchema: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				ok: { type: "boolean", required: true },
+				count: { type: "integer", required: true },
+				to: { type: "string", required: true },
+			},
+		},
+		call: (args) => ({ card: "generic", title: `zspace_move ${(args.paths ?? []).length} 项`, kind: "edit" }),
+		render: (_args, value) => [{ type: "text", text: `已移动 ${value.count} 项 → ${value.to}` }],
+		execute: (args) =>
+			guarded(async () => {
+				const client = getClient();
+				const sources = await Promise.all((args.paths ?? []).map(item => resolve(item)));
+				if (sources.length === 0) throw new Error("zspace_move: `paths` must not be empty");
+				const destination = await resolve(args.to);
+				await client.move(sources, destination);
+				return { ok: true, count: sources.length, to: destination };
+			}),
+	};
+}

package/lib/tools/paths.js

@@ -0,0 +1,84 @@
+/**
+ * Path conventions: remote prefixes, remote resolution, local path expansion.
+ *
+ * @module dsh-zspace/tools
+ */
+
+import os from "node:os";
+import path from "node:path";
+import { joinRemote } from "../format.js";
+
+const HOME_PREFIXES = ["home:", "my:", "个人空间:"];
+const PUBLIC_PREFIXES = ["public:", "share:", "公共空间:"];
+
+/**
+ * Collapse redundant slashes and strip a trailing slash (except for root).
+ *
+ * @param {string} remotePath - raw remote path.
+ * @returns {string} normalized path.
+ */
+export function normalizeRemote(remotePath) {
+	const collapsed = String(remotePath).replace(/\/{2,}/g, "/");
+	if (collapsed.length > 1 && collapsed.endsWith("/")) return collapsed.replace(/\/+$/, "");
+	return collapsed;
+}
+
+/**
+ * Build the remote-path resolver for one plugin instance.
+ *
+ * Accepted forms:
+ * - empty / omitted → personal-space root
+ * - `home:` / `my:` → personal space
+ * - `public:` / `share:` → public space
+ * - a relative path → resolved against the personal space
+ * - an absolute `/...` path → used as-is
+ *
+ * @param {{client: import("./client.js").ZSpaceClient}} context - plugin context.
+ * @returns {(input?: string) => Promise<string>} resolver.
+ */
+export function createResolver({ client }) {
+	return async (input) => {
+		const raw = String(input ?? "").trim();
+		if (raw === "") return await client.homePath();
+		if (raw.startsWith("/")) return normalizeRemote(raw);
+		for (const prefix of HOME_PREFIXES) {
+			if (raw.toLowerCase().startsWith(prefix)) {
+				return normalizeRemote(joinRemote(await client.homePath(), raw.slice(prefix.length)));
+			}
+		}
+		for (const prefix of PUBLIC_PREFIXES) {
+			if (raw.toLowerCase().startsWith(prefix)) {
+				return normalizeRemote(joinRemote(await client.publicPath(), raw.slice(prefix.length)));
+			}
+		}
+		return normalizeRemote(joinRemote(await client.homePath(), raw));
+	};
+}
+
+/**
+ * Resolve a local path argument.
+ *
+ * The plugin runs inside the DSH host process, so a relative path resolves
+ * against that process's working directory — **not** the agent's session
+ * workspace. `~/` is expanded so a model can still say `~/Downloads`.
+ *
+ * @param {unknown} input - caller-provided path.
+ * @returns {string} absolute local path ("" for blank input).
+ */
+export function expandLocalPath(input) {
+	const raw = String(input ?? "").trim();
+	if (raw === "") return "";
+	if (raw === "~") return os.homedir();
+	if (raw.startsWith("~/")) return path.join(os.homedir(), raw.slice(2));
+	return path.resolve(raw);
+}
+
+/**
+ * Default local directory for downloads when none is configured.
+ *
+ * @param {Record<string, any>} config - plugin config.
+ * @returns {string} absolute local directory.
+ */
+export function defaultDownloadDir(config) {
+	return config.downloadDir || path.join(os.homedir(), "Downloads", "zspace");
+}