minas-webdav

小米智能存储（Xiaomi Smart Storage / MINAS）WebDAV 控制工具箱——不挂盘、不依赖 Samba，直接通过设备的 HTTPS WebDAV 端点（:5000）控制整个 /pool0/data 存储池。

三条能力线：

安装

pipx install minas-webdav            # CLI（推荐）
pip install "minas-webdav[mcp]"      # 需要 MCP server 时加 extra

要求 Python ≥ 3.10。除 [mcp] extra 外无第三方依赖（只用标准库）。 不装也可以：PYTHONPATH=. python3 -m minas_webdav --help。

前置条件

配套环境、设备版本与兼容性说明见 docs/ENVIRONMENT.md（Windows 11 / Python 3.10+ / 小米智能存储官方客户端 1.0.8.170 / mcp 2.x；NAS 服务面：nginx/1.24.0 + DAV:1,2）。

1. NAS 与本机同一局域网（默认 192.168.1.100:5000）
2. 官方客户端已登录过（证书在 %LOCALAPPDATA%\minasCert\）
3. 凭据文件在仓库外：%LOCALAPPDATA%\minasCred\credentials.env

MINAS_USER=...
MINAS_PASS=...

4. 非机密配置：复制 minas_webdav/minas_config.example.json 为 minas_webdav/minas_config.json（已 gitignore），填入真实 host / cn

快速开始

# 列目录（JSON 输出适合 agent）
python -m minas_webdav ls /pool0/data --json

# 存储池容量
python -m minas_webdav df

# 上传 / 下载（中文路径直接写）
python -m minas_webdav put ./local.txt "/pool0/data/agent操作区/a.txt"
python -m minas_webdav get "/pool0/data/agent操作区/a.txt" ./back.txt

# 整理
python -m minas_webdav mkdir /pool0/data/work
python -m minas_webdav mv /pool0/data/a.txt /pool0/data/work/a.txt
python -m minas_webdav cp /pool0/data/a.txt /pool0/data/a-copy.txt
python -m minas_webdav rm /pool0/data/work -r      # 递删前务必确认！

# 能力探测（写测试用唯一路径，自动清理）
python -m minas_webdav probe

# 本地代理（供挂 N 盘 / Explorer 使用）
python -m minas_webdav proxy

也可 pip install -e . 后直接用 minas-webdav / minas-webdav-proxy / minas-webdav-probe 命令。

挂 N 盘（可选）

.\scripts\挂载NAS为N盘.ps1     # 自动拉起代理 + net use N:
.\scripts\删除N盘文件.ps1 <路径> # 删掉资源管理器删不动的文件

命令一览

退出码：0 成功 · 1 错误 · 2 不存在 · 3 认证/网络。

项目结构

minas_webdav/
  config.py    # 配置与凭据加载（minas_config.json + credentials.env）
  cli.py       # 文件 CLI
  probe.py     # 能力探测
  proxy.py     # 本机反向代理（WebClient 兼容调优）
scripts/       # 挂 N 盘 / 清理脚本 + rclone.zip
docs/          # webdav-surface.md 协议实测结论

协议要点（详见 docs/webdav-surface.md）

• Host/SNI 必须用设备 CN（nas.<uid>.<hash>），不能裸用 IP
• PROPFIND Depth: infinity 被拒（403），递归必须逐层 Depth: 1
• MOVE/COPY 的 Destination 用百分号编码的纯路径；IP 形式的 URL 会 400
• 无认证访问返回 451；Basic 即可，mTLS 可选

安全约束

• 凭据与设备 CN 不进 Git（.gitignore 已挡 minas_config.json / *.env）
• 不写日志、不打印密码；不碰 SSH/Docker/固件
• 递归删除、批量动照片/备份目录前必须征得用户同意

Agent 接入

本项目同时提供两种 agent 接入方式（设计见 docs/agent-integration-design.md）：

安装 Skill（MiMoCode）：

Copy-Item -Recurse skill "$HOME\.config\mimocode\skills\minas-webdav"

注册 MCP（任意 MCP 客户端，stdio）：

pipx install 'minas-webdav[mcp]'   # 提供 minas-webdav-mcp

// 通用 mcpServers 形式
"minas-webdav": {
  "command": "minas-webdav-mcp",
  "args": []
}

# ~/.dsh/profiles/web/cordis.patch.yml
- insert:
    - id: mcp-minas
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: minas
        transport: stdio
        command: minas-webdav-mcp

或者一行装完（DSH 插件，会替你插入同样的那行配置）：

dsh plugin add dsh-minas-webdav

装完可用 dsh plugin 的补丁关掉它（- id: mcp-minas-webdav + disabled: true）。

证书与凭据只放本机（默认 ~/.dsh/minasCert、~/.dsh/minasCred/credentials.env，可用 MINAS_CERT_HOME / MINAS_CRED_FILE 覆盖），MCP 配置里不出现任何凭据。

改 CLI 后请同步更新 SKILL.md 命令表与 MCP 工具签名。

License

Apache-2.0，见 LICENSE 与 NOTICE。与 Xiaomi 无关联。

相关

• 挂 N 盘可选 rclone（官方下载；仓库不打包二进制）
• Samba 通道（仅 Z: 备份共享）是另一套：minas-skill（SMB 445）