主要功能
这个 WebDAV 客户端实现了以下功能：
✅ exists(path) - 检查文件或目录是否存在
✅ createDirectory(path) - 创建目录（支持递归创建）
✅ getFileContents(path, options) - 获取文件内容（支持 text/binary/json 格式）
✅ putFileContents(path, content, options) - 上传文件a内容（支持覆盖选项）
✅ getDirectoryContents(path) - 列出目录内容（支持扁平化返回子目录）
✅ deleteFile(path) - 删除文件或目录
✅ moveFile(fromPath, toPath) - 移动/重命名文件
✅ copyFile(fromPath, toPath) - 复制文件
特性
🔐 支持 Basic Authentication
🔄 自动处理路径标准化
📁 支持递归创建目录和扁平化返回子目录
⚠️ 完善的错误处理
WebDAVClient 使用文档（中文版 by chatgpt5）
下面是你当前 WebDAVClient 库的完整使用说明、示例、注意事项与常见问题排查。文档面向在 Tampermonkey / Userscript 环境里使用该客户端的场景（库实现依赖 GM_xmlhttpRequest）。
概览
WebDAVClient 是一个轻量的 WebDAV 客户端类，封装了常用的 WebDAV 操作：列目录、读取/写入文件、创建目录、删除/移动/复制文件等。它在 userscript 中通过 GM_xmlhttpRequest 发起请求，并模拟 fetch 风格的响应对象（提供 text(), json(), arrayBuffer() 方法）。
引入 / 安装（示例）
两种常见方式：
- 把类放到同一脚本中（直接定义 class）——你已有的做法。
- 把类放外部，并用
@require 引入（推荐复用）：
// @grant GM_xmlhttpRequest
// @connect *
// @require https://scriptcat.org/lib/4521/1.0.0/WebDAVClient.js?sha384-H3wUQ1kAa17QQ2r8YgdyAyJbQRuk9zm9e0dejIiiHAt2frfUwsSxOLOqsmOCiYIV
注意：如果 WebDAVClient 使用 GM_xmlhttpRequest，主 userscript 必须声明 @grant GM_xmlhttpRequest，否则外部脚本无法访问该 API。
如果想在页面 console 或页面脚本访问该类，需要在外部库末尾 globalThis.WebDAVClient = WebDAVClient;（否则类仅在 userscript 沙箱中可见）。
快速开始（实例化与基本用法）
// 假设 WebDAVClient 已可用（通过 @require 或内联定义）
const client = new WebDAVClient({
url: 'https://jike.teracloud.jp/dav/',
username: 'wilsons',
password: 'your-password',
savePath: '/cursor-chat-history', // 可选：仅作记录/业务用途
});
// 列出一级目录（默认）
const list = await client.getDirectoryContents('/cursor-chat-history');
// 列出包括子目录（递归）
const listAll = await client.getDirectoryContents('/cursor-chat-history', { recursive: true });
// 读取文本文件
const txt = await client.getFileContents('/cursor-chat-history/hello.html', { format: 'text' });
// 上传（PUT）文件（覆盖）
await client.putFileContents('/cursor-chat-history/hello.html', 'hello world', { overwrite: true });
// 创建目录（递归）
await client.createDirectory('/cursor-chat-history/sub/dir', { recursive: true });
// 删除
await client.deleteFile('/cursor-chat-history/old.txt');
// 移动 / 复制
await client.moveFile('/from/path.txt', '/to/path.txt', { overwrite: true });
await client.copyFile('/from/path.txt', '/to/copy.txt', { overwrite: false });
API 参考（方法与行为）
所有方法都是 async，遇到 HTTP 错误或网络异常会抛异常（throw）。调用时请 try/catch。
构造函数
new WebDAVClient({ url, username, password, savePath? })
url（必）：WebDAV 根 URL，示例：https://server.example/dav/。内部会去掉尾部 / 以便拼接。username, password（必）：用于构造 Basic Auth。savePath（可选）：仅为业务字段，不影响客户端功能。
_request(method, path, options)
内部方法，包装 GM_xmlhttpRequest，返回一个模拟 fetch 响应对象（含 ok, status, statusText, text(), json(), arrayBuffer()）。通常无需直接调用。
exists(path)
async exists(path) -> boolean
使用 HEAD 请求判断资源是否存在，无法连通或出错返回 false（并在控制台报错）。
createDirectory(path, options = { recursive: true })
创建目录；当 recursive: true 时会逐层 MKCOL。如果目录已存在且服务器返回 405（Method Not Allowed）会视为成功（因为 MKCOL 在已存在时常返回 405）。
getDirectoryContents(path, options = { recursive: false })
async getDirectoryContents(path, { recursive }) -> Array<{ filename, path, type }>
getFileContents(path, options = { format: 'text' })
读取文件。format 支持：'text'（默认），'binary'（返回 ArrayBuffer），'json'（返回解析后的对象）。请求二进制请用 format: 'binary'（会设置 responseType: 'arraybuffer'）。
putFileContents(path, content, options = { overwrite: true })
上传文件（PUT）。
content 可为字符串或二进制（若为二进制，需自己处理 Content-Type）。options.overwrite === false 时，只在文件不存在时写入；否则抛出错误。options.contentType 可指定 Content-Type。
deleteFile(path)
删除文件 / 目录（由服务器实现行为决定）。
moveFile(fromPath, toPath, options = { overwrite: false })
MOVE，会设置 Destination 为完整 URL（库会调用 _getFullUrl(toPath)），Overwrite 为 T/F。
copyFile(fromPath, toPath, options = { overwrite: false })
COPY 操作，参数与 moveFile 相同。
常见使用场景示例（更完整）
userscript 头部示例（@require 引入）
// ==UserScript==
// @name my-webdav-script
// @match *://*/*
// @grant GM_xmlhttpRequest
// @connect *
// @require https://scriptcat.org/lib/4521/1.0.0/WebDAVClient.js?sha384-H3wUQ1kAa17QQ2r8YgdyAyJbQRuk9zm9e0dejIiiHAt2frfUwsSxOLOqsmOCiYIV
// ==/UserScript==
实际操作示例（含错误处理）
(async () => {
try {
const client = new WebDAVClient({
url: 'https://jike.teracloud.jp/dav/',
username: 'wilsons',
password: await promptPassword() // 不要把密码硬编码
});
// 列出并打印一级文件
const list = await client.getDirectoryContents('/cursor-chat-history');
console.log('list:', list);
// 递归列出全部
const all = await client.getDirectoryContents('/cursor-chat-history', { recursive: true });
console.log('all files (flat):', all);
// 读文件
const text = await client.getFileContents('/cursor-chat-history/hello.html');
console.log('hello:', text);
// 写文件
await client.putFileContents('/cursor-chat-history/new.txt', 'hello from script', { overwrite: true });
console.log('uploaded');
} catch (err) {
console.error('WebDAV 操作出错:', err);
}
})();
排查与注意事项
1. Tampermonkey 权限 / 黑名单问题
2. 路径与 href 格式
- 服务器返回
<D:href> 可能是绝对路径（/dav/...）或完整 URL；库会用 new URL(href, baseUrl) 进行规范化。
- 注意
getDirectoryContents 默认跳过代表目录自身的 <href> 条目（即 /dav/dir/），所以不会把父目录重复列出。
3. macOS 产生的 ._* 文件
- 这些是 AppleDouble（资源叉）文件，会出现在目录中。库默认过滤
._* 和 .DS_Store。如果你想包含这些，请修改过滤逻辑（getDirectoryContents 返回处）。
4. 递归与性能
- 递归会对每个子目录额外发起一次
PROPFIND（Depth: 1）。大量文件或深目录会产生许多 HTTP 请求。若服务器允许 Depth: infinity，可考虑一次性请求（需要修改库；兼容性/权限问题多）。
- 若需要高性能同步，考虑服务器端支持或分页、增量 sync。
5. 安全提示
- 不要把明文密码硬编码发布到公开仓库或脚本头。可在运行时
prompt() 用户输入或使用受控存储（注意安全）。
- 若将类暴露到
window（globalThis.WebDAVClient = WebDAVClient），页面脚本与其他扩展可访问该构造函数，避免把敏感实例或凭证也放到全局。
常见问题（FAQ）
Q：为什么我看到 .DS_Store 或 ._xxx？
A：这是 macOS 文件系统的元数据或资源叉文件。库默认会过滤掉；若你想看到，修改过滤规则。
Q：getDirectoryContents 可以返回嵌套树结构吗？
A：当前实现返回扁平数组（目录与文件在同一数组中，type 字段标识目录）。如果你需要嵌套树（每个目录有 children），可以在 getDirectoryContents 内部修改实现。我可以帮你改成嵌套结构（只需修改该函数）。
Q：怎么在页面控制台使用 WebDAVClient？
A：确保外部库在末尾做了 globalThis.WebDAVClient = WebDAVClient;。并且脚本要运行在能访问该全局的上下文（注意 @grant 会导致脚本运行在沙箱，需显式挂到 window）。
Q：服务器返回非标准 XML / 命名空间不同怎么办？
A：库已做命名空间无关查找（getElementsByTagNameNS('*', ...)），能处理常见 D: / lp1: 前缀。如果遇到极端差异，请把 PROPFIND 响应贴上来，我会给出解析调整。
结语 / 推荐实践
- 对于 userscript：尽量把
WebDAVClient 放在外部并用 @require 引入（便于复用与维护），并在主脚本中不要硬编码密码。
- 在大目录或同步场景下，优先考虑服务器端支持更高效的
Depth: infinity 或专用同步接口。
- 若你希望我把
getDirectoryContents 改为返回嵌套树（children），或把库改成支持 Depth: infinity 的一次性采集、或改进对二进制上传/下载的示例，我只修改最小必要代码并把完整代码输出给你（并标注修改位置）。
