WebDAV 文件管理技能

一组轻量 Shell 脚本，封装常见 WebDAV 操作。所有脚本共享同一个配置（webdav-common.sh），重复逻辑只在底层写一次。

快速开始

# 1. 配置凭据（三选一）
export WEBDAV_URL="https://your-server/dav"
export WEBDAV_USERNAME="your_user"
export WEBDAV_KEY="your_password"
# 或：写进技能目录下的 .env（自动加载，推荐）
# 或：在 Android 设置里建 WEBDAV_URL / WEBDAV_USERNAME / WEBDAV_KEY 三个变量

# 2. 跑通三个最常用命令
cd ~/.claude/skills/webdav-manager     # 改成你的实际安装目录
bash ./scripts/webdav-ls.sh /              # 列根目录
bash ./scripts/webdav-read.sh /README.md   # 读文件
bash ./scripts/webdav-write.sh /hello.txt "hi"  # 写文件

第一步报错 → 看 references/setup.md 脚本用法/参数细节 → 看 references/scripts.md 操作出错 → 看 references/troubleshooting.md 要加新脚本 → 看 references/extending.md 安全相关 → 看 references/security.md 改完脚本要回归 → 跑 bash tests/run.sh（需 .env 能连服务器）

目录结构

webdav-manager/                    # 技能安装目录（路径随安装位置而定）
├── SKILL.md              # 本文件（核心索引）
├── webdav-common.sh      # 公共工具库（重试、日志、错误处理、URL 编码、.env 加载）
├── .env                  # 可选，配置文件（需手动创建，权限 600）
├── references/           # 详细文档（按需查阅）
│   ├── setup.md
│   ├── scripts.md
│   ├── troubleshooting.md
│   ├── extending.md
│   └── security.md
├── tests/                # 自动化测试（改脚本后跑 run.sh 防回归）
│   ├── run.sh              # 入口：回归 + 边界
│   ├── regression.sh       # 23 项基础功能
│   └── verify.sh           # 4 项边界（抓已修 bug 复发）
└── scripts/
    ├── webdav-ls.sh          # 列出目录
    ├── webdav-read.sh        # 读取文件
    ├── webdav-write.sh       # 写入/创建文件
    ├── webdav-rm.sh          # 删除文件
    ├── webdav-upload.sh      # 上传本地文件
    ├── webdav-mkdir.sh       # 创建目录（支持 -p）
    ├── webdav-mv.sh          # 移动/重命名
    ├── webdav-cp.sh          # 复制
    ├── webdav-head.sh        # 检查存在性
    └── webdav-info.sh        # 详细属性（需 Python3）

脚本速查

| 需求 | 命令 | |------|------| | 列目录 | bash ./scripts/webdav-ls.sh <目录> | | 读文件 | bash ./scripts/webdav-read.sh <文件> | | 写文件 | bash ./scripts/webdav-write.sh <文件> <内容...> | | 删文件 | bash ./scripts/webdav-rm.sh <文件> | | 上传本地文件 | bash ./scripts/webdav-upload.sh <本地> [<远程>] | | 建目录（递归） | bash ./scripts/webdav-mkdir.sh -p <目录> | | 移动/重命名 | bash ./scripts/webdav-mv.sh <源> <目标> | | 复制 | bash ./scripts/webdav-cp.sh <源> <目标> | | 检查存在 | bash ./scripts/webdav-head.sh <文件> | | 详细属性 | bash ./scripts/webdav-info.sh <文件> |

完整参数、限制、退出码见 references/scripts.md。

常用工作流

cd ~/.claude/skills/webdav-manager/scripts    # 改成你的实际安装目录

# 浏览
bash ./webdav-ls.sh /                    # 列根目录
bash ./webdav-head.sh /important.md      # 确认文件存在

# 创建项目
bash ./webdav-mkdir.sh -p /project/src

# 写文件
bash ./webdav-write.sh /project/README.md "说明"
bash ./webdav-upload.sh ./local.csv /project/data.csv

# 整理
bash ./webdav-mv.sh /project/README.md /project/README_2026.md
bash ./webdav-cp.sh /project/data.csv /project/backup/data.csv
bash ./webdav-rm.sh /project/old.txt

关键约束

• 需要 bash——webdav_stream_copy 依赖 set -o pipefail（非 POSIX），/bin/sh 指向 dash 的系统上会失败。统一用 bash xxx.sh 调用
• 路径以 / 开头（远程绝对路径，如 /docs/file.txt）
• 路径中空格/中文/特殊字符会自动 URL 编码——无需手动处理
• write/upload/mkdir/mv/cp/rm 操作不可逆——write/upload 会覆盖同名文件，rm 不进回收站
• mv/cp 流式传输——GET|PUT 管道，内存恒定支持 GB 文件；先校验源存在（源缺失直接失败，不建目标）；非原子，中途断连可能残留部分文件
• 写入必须走 Content-Length，不能用 chunked 编码——printf ... | curl --data-binary @- 会被 curl 以 chunked 传输编码发送，部分 WebDAV 服务器会返回 201 但存下来的对象之后 GET 读不回来（curl exit 28/56 超时）。webdav_write 因此先落临时文件再 --upload-file；流式场景用 --upload-file -
• 日志走 stderr，stdout 只出数据——read/ls 可直接管道给 grep 等命令，不混入 [INFO]/[OK]
• 不同服务器的 HTTP 状态码可能不同（如已存在目录的 MKCOL：有的 409、有的 405、有的 201）——脚本同时识别这些情况
• 大文件无进度条和超时——传输 GB 级文件建议改造脚本加 --max-time 和 -#
• .env 文件权限必须 600——含明文密码（Windows 上 chmod 语义有限，需用 ACL 收紧）

完整约束、错误码、安全详见 references/ 下对应文档。

平台说明

脚本已做跨平台处理，可直接跑在 Linux / macOS / Windows Git Bash 上：

• 不写死安装路径——脚本用 dirname "$0" 自定位 webdav-common.sh，.env 同样按技能目录查找
• 不写死命令路径——curl/tail/sed/sleep 通过 command -v 探测并带绝对路径回退
• Windows Git Bash 的 MSYS2 参数转换已关闭——Git Bash 会把形似路径的参数和环境变量改写成 Windows 路径再传给原生 Windows 程序（实测远程路径 / 会被改成 Git 安装目录 E:/tool/Git/）。Python 调用统一走 webdav_python() helper 处理
• stdin 上传用 --upload-file -，不要用 /dev/stdin——MinGW 版 curl 不认 MSYS 的 /dev/stdin（报 cannot open '/dev/stdin'；被 MSYS 转换时更会变成 /proc/self/fd/0）
• Python 探测会实际执行一次——Windows 的 Microsoft Store 占位符 python3 在 PATH 里存在但无法运行

版本历史

| 版本 | 日期 | 改动 | |------|------|------| | 1.4.0 | 2026-09-30 | 跨平台移植 + 修 2 个真 bug：webdav_write 改走临时文件 + --upload-file（原先 --data-binary @- 触发 chunked 编码，部分服务器 PUT 返回 201 但对象之后 GET 读不回来）；webdav_stream_copy 改用 --upload-file -（MinGW curl 不认 /dev/stdin）；webdav_curl 改用 "$@" 保留参数边界（原先压平成字符串会把含空格的 XML 请求体拆散）；ls/head/write 修复覆盖环境变量 PATH；命令改为 command -v 探测（原写死 /usr/bin/curl）；脚本自定位 webdav-common.sh；关闭 MSYS2 参数转换（否则远程路径 / 被改写成 Git 安装目录）；Python 探测实跑验证 + PYTHONIOENCODING；shebang 改 bash；回归测试改为自建数据（原依赖特定测试服务器的固定文件）；文档去除写死的 /var/minis 路径 | | 1.3.0 | 2026-09-24 | 修复 7 个 bug：cp/mv 源缺失静默建 0 字节目标（加存在性预检+pipefail+--fail）、mv 删源失败保留源并警告、mkdir 含空格路径损坏（改 IFS 分词）、$TAIL/$SLEEP/$SED 含 / 变量拆词（加引号）、echo 选项吞并（改 printf '%s\n'）、日志污染 stdout（统一 stderr）、WEBDAV_URL 尾斜杠双斜杠 | | 1.2.0 | 2026-09-04 | 文档结构化拆分：精简 SKILL.md 至核心，详尽内容进 references/ 子目录（setup/scripts/troubleshooting/extending/security） | | 1.1.0 | 2026-09-04 | 路径自动 URL 编码、mkdir 支持 -p 递归、错误码透出到 stderr、.env 文件支持、脚本补全参数校验、head.sh/info.sh 修复 PROPFIND body 问题 | | 1.0.0 | 2025-08-15 | 初始版本：10 个基础脚本 + webdav-common.sh 公共库 |