dsh-zspace 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # 变更日志
 
+## 0.1.2 — 2026-10-06
+
+新增一个写入类工具 + 一个配置项，并把文档里的真实池名换成占位符（**无破坏性变更**，工具表新增一行）：
+
+- 新增 `zspace_write`：把文本直接写到 NAS，省掉"先生成本地临时文件再上传"这一步。默认覆盖同名文件，`overwrite: false` 时先探测存在性并拒绝；体积受 `writeMaxBytes` 约束；底层复用同一条上传路径（自动决定单请求/分片），临时文件无论成败都会清理。
+- 新增配置项 `writeMaxBytes`（默认 5 MB），四处同步：Config schema、DEFAULTS、加载期校验、`cordis.patch.yml`。
+- 文档与工具描述里的示例路径由真实的 `/<具体池>/...` 泛化为 `/<pool>/...`（探测候选路径代码保留，那是发现算法的一部分）。
+- 清掉 0.1.1 拆分脚本引入的 19 处重复 JSDoc。
+- 验证：29 项 mock 测试（新增 zspace_write 的 4 类断言）+ 真机 21 步自检（新增"直写文本→读回内容比对"）。
+
 ## 0.1.1 — 2026-10-06
 
 纯内部重构，**对外行为与 API 不变**（`ZSpaceClient` / `ZSpaceError` / `createToolSpecs` / 12 个工具名与参数完全保持）：

package/README.md

@@ -41,6 +41,7 @@ dsh plugin --profile desktop add /绝对路径/dsh-zspace-0.1.0.tgz
 | `zspace_read` | 把小文本文件读进上下文（默认上限 256 KB，二进制自动识别） |
 | `zspace_download` | 从 NAS 下载到本机（默认落到 `~/Downloads/zspace`） |
 | `zspace_upload` | 上传本地文件，**大文件自动走分片协议**，中文文件名可用 |
+| `zspace_write` | 把文本**直接写到 NAS**（省掉本地临时文件），默认覆盖、可传 `overwrite: false` 拒绝覆盖 |
 | `zspace_mkdir` | 建目录 |
 | `zspace_rename` | 就地重命名 |
 | `zspace_move` | 移动到另一个目录（服务端操作，不下载） |
@@ -51,11 +52,11 @@ dsh plugin --profile desktop add /绝对路径/dsh-zspace-0.1.0.tgz
 
 | 写法 | 含义 |
 |---|---|
-| 省略 / `""` | 个人空间根（本机实测 `/sata1/my/data`） |
+| 省略 / `""` | 个人空间根（形如 `/<pool>/my/data`，实际值由插件探测） |
 | `home:相册` | 个人空间下的 `相册` |
-| `public:公共分组/skills` | 公共空间下的路径（本机 `/sata1/public/...`） |
+| `public:公共分组/skills` | 公共空间下的路径（形如 `/<pool>/public/...`） |
 | `docs/2026` | 相对个人空间根 |
-| `/sata1/my/data/x.txt` | NAS 绝对路径，原样使用 |
+| `/<pool>/my/data/x.txt` | NAS 绝对路径，原样使用 |
 
 两个根路径由插件按存储池自动探测（`/<pool>/my/data`、`/<pool>/public`），也可在配置里写死。
 
@@ -75,6 +76,7 @@ dsh plugin --profile desktop add /绝对路径/dsh-zspace-0.1.0.tgz
 | `homePath` / `publicPath` | 空＝自动探测 | 写死个人/公共空间根 |
 | `downloadDir` | 空＝`~/Downloads/zspace` | 默认下载目录 |
 | `readMaxBytes` | `262144` | `zspace_read` 上限 |
+| `writeMaxBytes` | `5242880` | `zspace_write` 单次写入上限（更大的内容用 `zspace_upload`） |
 | `listMaxEntries` | `2000` | 单次列目录/树的上限 |
 | `timeoutMs` / `maxRetries` | `60000` / `2` | 请求超时与瞬时失败重试 |
 | `smallUploadMaxBytes` | `8388608` | 超过就用分片上传 |

package/cordis.patch.yml

@@ -6,8 +6,9 @@
 # Every value below has a code-side default, so this patch stays valid even on
 # a host without patch-side helper evaluation. `homePath` / `publicPath` are
 # intentionally empty: the plugin discovers them from the NAS storage pools at
-# runtime (e.g. /sata1/my/data and /sata1/public), which keeps the same file
-# working on NAS models that name their pools differently.
+# runtime (personal space looks like /<pool>/my/data, public space like
+# /<pool>/public), which keeps the same file working on NAS models that name
+# their pools differently.
 
 - insert:
     - id: zspace
@@ -19,6 +20,7 @@
         publicPath: ""
         downloadDir: ""
         readMaxBytes: 262144
+        writeMaxBytes: 5242880
         listMaxEntries: 2000
         timeoutMs: 60000
         maxRetries: 2

package/lib/README.md

@@ -19,13 +19,13 @@ lib/
 │   ├── mutate.js    102 行  mkdir / rename / move / copy / remove
 │   ├── upload.js    129 行  单请求上传 + 分片协议
 │   └── download.js  128 行  流式下载、限量读入内存
-├── tools.js        66 行   工具注册表：建 ctx、按顺序调用 12 个工厂
+├── tools.js        68 行   工具注册表：建 ctx、按顺序调用 13 个工厂
 └── 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
+    └── <工具名>.js  35-120 行  每个工具一个文件：status ls stat find read
+                                download upload write mkdir rename move copy remove
 ```
 
 ## 依赖方向（严格单向，无环）

package/lib/client/browse.js

@@ -39,13 +39,6 @@ export async function list(client, remotePath, options = {}) {
 	return { entries, truncated };
 }
 
-/**
- * File or directory metadata.
- *
- * @param {string} remotePath - absolute remote path.
- * @returns {Promise<ReturnType<typeof toEntry>>} normalized entry.
- */
-
 /**
  * File or directory metadata.
  *

package/lib/client/download.js

@@ -43,14 +43,6 @@ export async function download(client, remotePath, localDir, options = {}) {
 	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.
  *
@@ -72,13 +64,6 @@ export async function readFile(client, remotePath, options = {}) {
 	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.
  *

package/lib/client/mutate.js

@@ -18,14 +18,6 @@ export async function mkdir(client, remotePath) {
 	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.
  *
@@ -38,14 +30,6 @@ export async function rename(client, remotePath, 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.
  *
@@ -57,14 +41,6 @@ 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.
  *
@@ -76,13 +52,6 @@ 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).
  *

package/lib/client/session.js

@@ -22,13 +22,6 @@ export function authHeaders(client) {
 	};
 }
 
-/**
- * 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`.

package/lib/client/spaces.js

@@ -27,12 +27,6 @@ export async function check(client) {
 	});
 }
 
-/**
- * Storage pools (`/zspool/info`), cached per client.
- *
- * @returns {Promise<Array<{name: string, status: string, totalSize: number, freeSize: number}>>} pools.
- */
-
 /**
  * Storage pools (`/zspool/info`), cached per client.
  *
@@ -51,13 +45,6 @@ export async function pools(client) {
 	return client._pools;
 }
 
-/**
- * Whether a remote directory can be listed.
- *
- * @param {string} remotePath - absolute remote path.
- * @returns {Promise<boolean>} true when listing succeeds.
- */
-
 /**
  * Whether a remote directory can be listed.
  *
@@ -74,17 +61,7 @@ export async function isDirectory(client, remotePath) {
 }
 
 /**
- * Locate the personal-space root, e.g. `/sata1/my/data`.
- *
- * Uses the configured path when set, otherwise tries `/<pool>/my/data` for
- * every storage pool and falls back to the historical `/sata11/my/data`.
- *
- * @returns {Promise<string>} personal-space root.
- * @throws {ZSpaceError} when no candidate is listable.
- */
-
-/**
- * Locate the personal-space root, e.g. `/sata1/my/data`.
+ * Locate the personal-space root, e.g. `/<pool>/my/data`.
  *
  * Uses the configured path when set, otherwise tries `/<pool>/my/data` for
  * every storage pool and falls back to the historical `/sata11/my/data`.
@@ -111,14 +88,7 @@ export async function homePath(client) {
 }
 
 /**
- * Locate the public-space root, e.g. `/sata1/public`.
- *
- * @returns {Promise<string>} public-space root.
- * @throws {ZSpaceError} when no candidate is listable (account may lack access).
- */
-
-/**
- * Locate the public-space root, e.g. `/sata1/public`.
+ * Locate the public-space root, e.g. `/<pool>/public`.
  *
  * @returns {Promise<string>} public-space root.
  * @throws {ZSpaceError} when no candidate is listable (account may lack access).

package/lib/client/transport.js

@@ -90,13 +90,6 @@ export function endpointUrl(client, endpoint, query) {
 	return url;
 }
 
-/**
- * Encode form fields, expanding arrays into repeated `key[]` entries.
- *
- * @param {Record<string, unknown>} fields - form fields.
- * @returns {string} urlencoded body.
- */
-
 /**
  * Encode form fields, expanding arrays into repeated `key[]` entries.
  *
@@ -116,15 +109,6 @@ export function formBody(client, fields) {
 	return parts.join("&");
 }
 
-/**
- * Retry a transport call with exponential backoff.
- *
- * @template T
- * @param {() => Promise<T>} attempt - one attempt.
- * @param {(error: unknown) => boolean} shouldRetry - retry predicate.
- * @returns {Promise<T>} the first successful result.
- */
-
 /**
  * Retry a transport call with exponential backoff.
  *
@@ -147,23 +131,6 @@ export async function retrying(client, attempt, shouldRetry) {
 	throw lastError;
 }
 
-/**
- * Send one buffered request.
- *
- * @param {object} options - request options.
- * @param {"GET"|"POST"} [options.method] - HTTP method.
- * @param {string} options.endpoint - API path.
- * @param {Record<string, unknown>} [options.query] - extra query values.
- * @param {Record<string, unknown>} [options.form] - form fields (merged with common params).
- * @param {Record<string, unknown>} [options.fields] - raw fields appended without common params.
- * @param {Buffer} [options.body] - raw request body.
- * @param {string} [options.filePath] - stream this file as the request body.
- * @param {Record<string, string>} [options.headers] - extra headers (override auth).
- * @param {string} [options.url] - absolute URL override (sliced upload).
- * @param {number} [options.timeoutMs] - per-attempt timeout.
- * @returns {Promise<{status: number, headers: import("node:http").IncomingHttpHeaders, text: string}>} response.
- */
-
 /**
  * Send one buffered request.
  *
@@ -268,15 +235,6 @@ export async function send(client, options) {
 	});
 }
 
-/**
- * Validate a buffered JSON response and unwrap its `data`.
- *
- * @param {{status: number, text: string}} response - raw response.
- * @param {string} endpoint - endpoint for error context.
- * @returns {any} the response `data` (or the whole body when it has none).
- * @throws {ZSpaceError} on HTTP failures, HTTP 413 and non-200 business codes.
- */
-
 /**
  * Validate a buffered JSON response and unwrap its `data`.
  *
@@ -306,14 +264,6 @@ export function parse(client, response, endpoint) {
 	return body.data !== undefined ? body.data : body;
 }
 
-/**
- * POST form fields and return the unwrapped `data`.
- *
- * @param {string} endpoint - API path.
- * @param {Record<string, unknown>} [fields] - form fields.
- * @returns {Promise<any>} response data.
- */
-
 /**
  * POST form fields and return the unwrapped `data`.
  *

package/lib/client/upload.js

@@ -52,18 +52,6 @@ export async function upload(client, localPath, remoteDir, options = {}) {
 	}
 }
 
-/**
- * Sliced upload (`/v2/file/upload`), the protocol the desktop client uses
- * for anything the local proxy will not pass through in one request.
- *
- * @param {string} localPath - local file.
- * @param {string} target - absolute remote file path.
- * @param {number} total - total byte size.
- * @param {import("node:fs").Stats} stat - local file stat.
- * @param {(sent: number, total: number) => void} [onProgress] - progress callback.
- * @returns {Promise<void>} resolves when the last slice was accepted.
- */
-
 /**
  * Sliced upload (`/v2/file/upload`), the protocol the desktop client uses
  * for anything the local proxy will not pass through in one request.

package/lib/client.js

@@ -69,12 +69,6 @@ export class ZSpaceClient {
 		this._pools = null;
 	}
 
-	/**
-	 * Desktop-client credentials, loaded lazily and re-read when `vuex.json` changes.
-	 *
-	 * @returns {{token: string, nasId: string, deviceId: string, username: string, device: string, appVersion: string, vuexPath?: string}}
-	 */
-
 	/**
 	 * Desktop-client credentials, loaded lazily and re-read when `vuex.json` changes.
 	 *

package/lib/config.js

@@ -27,6 +27,7 @@ const DEFAULTS = Object.freeze({
 	publicPath: "",
 	downloadDir: "",
 	readMaxBytes: 262_144,
+	writeMaxBytes: 5 * 1024 * 1024,
 	listMaxEntries: 2000,
 	timeoutMs: 60_000,
 	maxRetries: 2,
@@ -51,6 +52,8 @@ export const Config = z.object({
 	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. */
@@ -87,6 +90,7 @@ export function resolveConfig(config) {
 export function validateConfig(config) {
 	const bounds = [
 		["readMaxBytes", config.readMaxBytes],
+		["writeMaxBytes", config.writeMaxBytes],
 		["listMaxEntries", config.listMaxEntries],
 		["timeoutMs", config.timeoutMs],
 		["maxRetries", config.maxRetries],

package/lib/tools/ls.js

@@ -11,7 +11,7 @@ export function createLsTool(ctx) {
 		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 (/sata1/my/data/…), home:/…, public:/…, or relative to the personal space. Omit for the personal-space root." },
+			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}).` },

package/lib/tools/write.js

@@ -0,0 +1,73 @@
+/**
+ * `zspace_write` — one atomic capability.
+ *
+ * @module dsh-zspace/tools
+ */
+
+import fsp from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { humanSize } from "../format.js";
+
+export function createWriteTool(ctx) {
+	const { config, getClient, guarded, resolve } = ctx;
+	return {
+		name: "zspace_write",
+		description:
+			"Write text straight to a file on the 极空间 / ZSpace NAS (跨网络可用) — no local temp file needed. Use it to park generated notes, reports or config onto the NAS. Overwrites an existing file by default; pass overwrite=false to refuse replacing one. Size is capped by the writeMaxBytes config.",
+		parameters: {
+			path: { type: "string", required: true, description: "Remote file path (absolute, home:/, public:/, or relative to the personal space)." },
+			content: { type: "string", required: true, description: "UTF-8 text to write. Use zspace_upload for binary or large files." },
+			overwrite: { type: "boolean", description: "Allow replacing an existing file (default true)." },
+		},
+		outputSchema: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				path: { type: "string", required: true },
+				bytes: { type: "integer", required: true },
+				method: { type: "string", required: true },
+			},
+		},
+		call: (args) => ({ card: "generic", title: `zspace_write ${args.path}`, kind: "edit" }),
+		render: (_args, value) => [
+			{
+				type: "text",
+				text: `已写入 ${value.path}（${humanSize(value.bytes)}，${value.method === "sliced" ? "分片" : "单请求"}）`,
+			},
+		],
+		execute: (args) =>
+			guarded(async () => {
+				const client = getClient();
+				const target = await resolve(args.path);
+				const content = String(args.content ?? "");
+				const bytes = Buffer.byteLength(content, "utf8");
+				if (bytes === 0) throw new Error("zspace_write: `content` 不能为空");
+				if (bytes > config.writeMaxBytes) {
+					throw new Error(`zspace_write: 内容 ${bytes} 字节超过 writeMaxBytes=${config.writeMaxBytes}；大文件请用 zspace_upload`);
+				}
+				if (args.overwrite === false) {
+					const exists = await client
+						.info(target)
+						.then(() => true)
+						.catch(() => false);
+					if (exists) throw new Error(`zspace_write: ${target} 已存在（overwrite=false 时拒绝覆盖）`);
+				}
+
+				// 上传接口只吃本地文件，所以落一个临时文件再走同一条上传路径
+				// （单请求 / 分片由 client.upload 自己决定），最后无论如何都清理。
+				const staging = await fsp.mkdtemp(path.join(os.tmpdir(), "dsh-zspace-write-"));
+				const name = path.posix.basename(target);
+				const local = path.join(staging, name);
+				try {
+					await fsp.writeFile(local, content, "utf8");
+					const remoteDir = target.slice(0, target.lastIndexOf("/")) || "/";
+					const result = await client.upload(local, remoteDir, { name });
+					return { path: target, bytes: result.bytes, method: result.method };
+				} finally {
+					await fsp.rm(staging, { recursive: true, force: true });
+				}
+			}),
+	};
+}

package/lib/tools.js

@@ -19,6 +19,7 @@ import { createFindTool } from "./tools/find.js";
 import { createReadTool } from "./tools/read.js";
 import { createDownloadTool } from "./tools/download.js";
 import { createUploadTool } from "./tools/upload.js";
+import { createWriteTool } from "./tools/write.js";
 import { createMkdirTool } from "./tools/mkdir.js";
 import { createRenameTool } from "./tools/rename.js";
 import { createMoveTool } from "./tools/move.js";
@@ -57,6 +58,7 @@ export function createToolSpecs({ getClient, config }) {
 		createReadTool(ctx),
 		createDownloadTool(ctx),
 		createUploadTool(ctx),
+		createWriteTool(ctx),
 		createMkdirTool(ctx),
 		createRenameTool(ctx),
 		createMoveTool(ctx),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-zspace",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "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",