dsh-zspace 0.0.0-stage → 0.1.0

package/LICENSE

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

package/README.md

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

package/cordis.patch.yml

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

package/lib/auth.js

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

package/lib/client.d.ts

@@ -0,0 +1,63 @@
+/** Type surface for the dependency-free ZSpace client. */
+
+/** NAS business code or synthetic transport marker. */
+export type ZSpaceErrorCode = string;
+
+/** One ZSpace API or transport failure. */
+export declare class ZSpaceError extends Error {
+	readonly code: ZSpaceErrorCode;
+	readonly endpoint: string;
+	/** Actionable next step for known codes. */
+	readonly hint: string | undefined;
+	constructor(code: string, message: string, options?: { endpoint?: string; cause?: unknown });
+}
+
+/** Normalized NAS entry. */
+export interface ZSpaceEntry {
+	name: string;
+	path: string;
+	dir: boolean;
+	size: number;
+	modified: string;
+	created: string;
+	ext: string;
+}
+
+/** Client construction options. */
+export interface ZSpaceClientOptions {
+	baseUrl?: string;
+	configDir?: string;
+	apiVersion?: string;
+	credentials?: { token: string; nasId: string; deviceId: string; device?: string; appVersion?: string; username?: string };
+	homePath?: string;
+	publicPath?: string;
+	timeoutMs?: number;
+	maxRetries?: number;
+	retryDelayMs?: number;
+	pageSize?: number;
+	listMaxEntries?: number;
+	smallUploadMaxBytes?: number;
+	sliceSize?: number;
+}
+
+/** Cross-network ZSpace NAS client (desktop client local proxy). */
+export declare class ZSpaceClient {
+	readonly baseUrl: string;
+	readonly identity: { username: string; nasId: string; deviceId: string; vuexPath: string };
+	constructor(options?: ZSpaceClientOptions);
+	check(): Promise<boolean>;
+	pools(): Promise<Array<{ name: string; status: string; totalSize: number; freeSize: number }>>;
+	isDirectory(remotePath: string): Promise<boolean>;
+	homePath(): Promise<string>;
+	publicPath(): Promise<string>;
+	list(remotePath: string, options?: { showHidden?: boolean; maxEntries?: number }): Promise<{ entries: ZSpaceEntry[]; truncated: boolean }>;
+	info(remotePath: string): Promise<ZSpaceEntry>;
+	mkdir(remotePath: string): Promise<ZSpaceEntry>;
+	rename(remotePath: string, newName: string): Promise<ZSpaceEntry>;
+	move(remotePaths: string[], to: string): Promise<void>;
+	copy(remotePaths: string[], to: string): Promise<void>;
+	remove(remotePaths: string[]): Promise<void>;
+	download(remotePath: string, localDir: string, options?: { name?: string }): Promise<{ localPath: string; bytes: number }>;
+	readFile(remotePath: string, options?: { maxBytes?: number }): Promise<{ buffer: Buffer; truncated: boolean; bytes: number }>;
+	upload(localPath: string, remoteDir: string, options?: { name?: string; onProgress?: (sent: number, total: number) => void }): Promise<{ remotePath: string; bytes: number; method: "create" | "sliced" }>;
+}