dsh-zspace 0.3.2 → 0.3.3

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # 变更日志
 
+## 0.3.3 — 2026-10-11
+
+修 `zspace_write` 的**覆盖语义**（自 0.1.2 起工具描述承诺"默认覆盖"，实际在全网盘根级会失败——NAS 的 `/v2/file/create` 只做新建，同名返回"存在同名文件(夹)，创建失败"）：
+
+- **中转通道**：覆盖前先 `remove`（旧版进 NAS 回收站）再写；
+- **WebDAV 直连通道**：PUT 本身就是覆盖语义，**不做**删除（避免把"覆盖"变成永久删除）；
+- 目标不存在时不触发任何删除；`overwrite: false` 行为不变（存在即拒绝）；
+- 工具 description 同步写清两条通道不同的覆盖语义（按 `dsh-plugin` 的教训：给模型的文案也是对外契约）。
+- 验证：37 项单测（新增覆盖三分支：中转先删、WebDAV 不删、新文件不删）+ 真机自检新增「覆盖已有文件」步骤（两版写同一路径，读回第二版）。
+
 ## 0.3.2 — 2026-10-11
 
 修正**注入给模型的指南**滞后于工具演进的问题（只影响文档文案，行为不变）：

package/lib/tools/write.js

@@ -15,7 +15,7 @@ export function createWriteTool(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.",
+			"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 (relay transport: the previous version goes to the NAS recycle bin, since its create API only creates; WebDAV transport: the NAS overwrites in place); 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." },
@@ -47,12 +47,17 @@ export function createWriteTool(ctx) {
 				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 时拒绝覆盖）`);
+				const exists = await client
+					.info(target)
+					.then(() => true)
+					.catch(() => false);
+				if (exists) {
+					if (args.overwrite === false) throw new Error(`zspace_write: ${target} 已存在（overwrite=false 时拒绝覆盖）`);
+					// 中转通道的 /v2/file/create 只做「新建」，同名会被拒（"存在同名文件(夹)"），
+					// 所以先删（进 NAS 回收站）再写；直连 WebDAV 的 PUT 本身就是覆盖语义，
+					// 在那儿先删反而可能变成永久删除，故只在中转通道这么做。
+					const { transport } = await client.transportReport();
+					if (transport === "relay") await client.remove([target]);
 				}
 
 				// 上传接口只吃本地文件，所以落一个临时文件再走同一条上传路径

package/package.json

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