zspace-cli

通过终端或 AI Agent 管理你的极空间（ZSpace）NAS——无需密码、SSH 或 DDNS。

mcp-name: io.github.skyzhao1223/zspace-cli

只需让 ZSpace 桌面客户端在 macOS 上保持登录状态。

📖 大文件分片上传的诞生记：一次 1.4GB 备份引发的逆向 (zh, CSDN) · CLI 指南：极空间 NAS 命令行管理指南 (zh, CSDN)

新手指南（无需编程） · 技能 — 包含适用于 AI Agent 的 9 个跨 NAS 整理技能 · 中文文档

---

安装

pip install zspace-cli        # base
pip install "zspace-cli[mcp]" # optional MCP support
zs check                      # ✓ reads the desktop client login state

前置条件： ZSpace 桌面客户端正在 macOS 上运行并已登录。

---

快速开始

zs ls /sata11/my/data/影视
zs find "权力的游戏"                  # full-text search
zs tree /sata11/my/data -d 3
zs up ./本地文件.mp4 /sata11/my/data/影视   # upload
zs up ./本地文件.mp4 /sata11/my/data/影视 --verify  # upload + MD5 round-trip check
zs down /sata11/my/data/影视/某文件.mkv ./下载 # download

from zspace_cli import ZSpaceClient

with ZSpaceClient() as zs:
    for f in zs.ls("/sata11/my/data"):
        print(f"{'📁' if f.is_dir else '📄'} {f.name}")

---

CLI 选项

命令	含义
zs check	验证桌面客户端代理是否可访问
zs ls [path]	列出目录（-a/--hidden、-l/--long）
zs info <path>	文件／目录详细信息
zs rename <path> <new>	重命名文件或目录
zs mv <src> <dest>	移动文件／目录
zs cp <src> <dest>	复制文件／目录
zs mkdir <parent> <name>	创建目录
zs rm <path>	将内容删除到个人回收站（-f/--force 跳过确认）。只有执行 zs recycle empty 后才会释放存储池空间
zs find <keyword> [path]	在 NAS 中进行全文搜索
zs tree [path]	树形视图（-d/--depth N，默认值为 2）
zs usage	存储概况——按存储池、用户和类别统计实际占用空间。唯一包含 Time Machine 备份、其他用户空间以及 Docker/RAID 开销的视图（--refresh、--wait N）
zs du <path>...	通过服务端统计目录大小。当 NAS 无法完成大型目录树的统计时，不会将部分统计结果当作最终结果；--walk 强制进行精确的客户端遍历
zs bigfiles [path]...	在服务端扫描最大文件（--min-size MiB、--top N）。扫描整个资料库中的 269 万个文件耗时 2 分 41 秒，而客户端遍历耗时 57 分钟
zs disks	每个磁盘的可用空间、温度、健康状况、碎片情况、通电时长，以及空盘位
zs smart [sn]	SMART 报告（--all 显示所有磁盘）
zs recycle list	列出回收站内容及原始位置（--public 查看共享回收站）
zs recycle restore <name>	将项目恢复到原始位置
zs recycle purge <name>	仅永久删除指定项目（-f/--force）
zs recycle empty	清空整个个人回收站——此操作不可撤销，因此会先列出内容（--public、-f）
zs recycle config	保留策略；-1 表示永不自动清理（--my-cycle N、--public-cycle N）
zs up <local> <remote_dir>	上传（使用 -n/--name 重命名；使用 --verify 进行上传后的 MD5 往返验证；大文件会自动切换为分片上传）
zs down <path> [dir]	下载
zs baidu check/ls/tasks/fails/retry	通过 NAS 的 /znetdisk/* 模块访问百度网盘（读取操作；retry 会修改任务状态）——详情
zs skill <dir>	将 Agent 技能复制到项目中（--list、--only a,b）
zs --config-dir <dir>	指定非默认的 vuex.json 位置（或设置 ZS_CONFIG_DIR）

zs check、zs ls、zs info、zs find、zs tree、zs usage、zs du、 zs bigfiles、zs disks、zs smart、zs recycle list/config 支持使用 --json 生成机器可读的输出。zs mv／zs cp／zs rm／zs down 支持在源路径中使用 * ? glob 模式。zs baidu check／ls／tasks／fails 也支持 --json。

ls 会自动分页浏览大型目录（NAS API 每次调用最多返回 50 个条目）。find 使用 NAS 全文索引，因此可以跨目录搜索。上传／下载会在真实终端中显示进度条，并以流式方式传输文件（不会将整个文件缓冲到内存中）。对 zs up 使用 --verify，可将上传的文件下载到临时目录，并将其 MD5 与本地源文件进行比对；验证默认关闭，因为它会使传输量翻倍。CJK 路径开箱即用。超过 64 MB 的文件会通过桌面客户端的分片 /v2/file/upload 协议上传（每片 2 MB），因为本地代理会对超大单请求正文返回 HTTP 413；较小文件遇到 413 时也会自动回退到分片上传。

---

Features

Operation	CLI	SDK	MCP
List directory	zs ls [path]	client.ls(path)	zspace_ls
File info	zs info <path>	client.info(path)	zspace_info
Rename	zs rename <path> <name>	client.rename(path, name)	zspace_rename
Create dir	zs mkdir <parent> <name>	client.mkdir(parent, name)	zspace_mkdir
Move	zs mv <src> <dest>	client.move(src, dest)	zspace_move
Copy	zs cp <src> <dest>	client.copy(src, dest)	zspace_copy
Delete	zs rm <path>	client.remove(path)	zspace_remove
Search	zs find <keyword>	client.search(kw)	zspace_search
Tree view	zs tree [path]	client.tree(path)	zspace_tree
Upload	zs up <local> <dir>	client.upload(local, dir, verify=False)	zspace_upload
Download	zs down <path> [dir]	client.download(path, dir)	zspace_download
Health check	zs check	client.is_connected()	zspace_check
Storage pools	zs check	client.pool_info()	zspace_pool_info
Disk diagnostics	—	client.disk_stats()	zspace_disk_stats
Storage profile	zs usage	client.usage_summary()	zspace_usage
Directory size	zs du <path>	client.statistic(path) / client.walk_stat(path)	zspace_du
Largest files	zs bigfiles [path]	client.find_large(paths)	zspace_bigfiles
Per-disk health	zs disks	client.disks() / client.free_bays()	zspace_disks
SMART report	zs smart [sn]	client.smart(sn)	zspace_smart
Recycle bin (read)	zs recycle list/config	client.recycle_list() / client.recycle_config()	zspace_recycle_list / zspace_recycle_config
Recycle bin (write)	zs recycle restore/purge/empty	client.recycle_restore() / recycle_purge() / recycle_empty()	zspace_recycle_restore / zspace_recycle_purge / zspace_recycle_empty (confirm-gated)
Baidu NetDisk (read side)	zs baidu check/ls/tasks/fails/retry	client.baidu_*()	—

---

与 AI Agent 搭配使用（Skills）

zs skill --list                           # see what's available
zs skill ~/your-project/.cursor/skills/   # install all (Cursor)
# zs skill ~/your-project/skills/         # Claude Code, etc.
zs skill ~/your-project/skills/ --only nas-report,photo-organizer   # or pick a few

然后告诉你的 Agent 诸如“列出 /sata11/my/data 中的文件”之类的任务。Skills 随软件包一同发布，因此任何安装了 zspace-cli 的机器都可以使用 zs skill。

除了 zspace-nas（ZSpace 文件操作的零配置基础），zs skill 还会安装一组 9 个跨 NAS 整理技能。它们的扫描器仅依赖标准库，可扫描任何已挂载路径（SMB/NFS），因此适用于 ZSpace、Synology、QNAP、UGREEN 等设备。它们都遵循相同的只读模式：扫描 → 大模型拟定旧→新方案 → 你确认 → Agent 执行（删除操作始终会先移入隔离区）。

技能	功能
nas-report	🧭 入口：生成整盘存储概况，并引导你使用合适的专业技能
file-sorter	🧹 整理任意混杂文件：识别 15 个类别中的 255 种扩展名（照片 / 视频 / 音频 / 文档 / 电子书 / 压缩包 / 安装程序 / 字体 / 代码 / 设计源文件 / CAD 图纸 / 磁盘映像……），计算每个文件的 old → new 路径，并识别 135 个文件夹名称别名（简体中文 + 繁体中文 + 英文），因此不会对已整理好的资源库重复整理。默认不会拆散项目文件夹
photo-organizer	照片/视频：按拍摄日期归档（--exif 通过 exiftool 读取实际拍摄日期，或在 macOS 上通过 mdls 读取）、整理截图/微信图片、连拍去重
music-organizer	音乐：Artist/Album/Track 目录结构、曲目编号、封面、内置 ID3v2 解析
work-organizer	工作文件：归档散落文件、整理混乱的版本和副本、归档过期文件
portfolio-organizer	作品集：项目结构、封面/README、将最终成品与源文件分开
download-cleaner	下载内容：筛查并清理（未完成文件/种子/安装程序/压缩包/未分类媒体）
dedup-finder	按内容精确去重（三级指纹：大小→文件头→完整 sha1，零误报）
backup-auditor	备份健康状况：版本轮换、过期检查、覆盖范围检查

从 nas-report 开始了解整体情况，然后运行它推荐的专业技能。最常用的组合是 dedup-finder + file-sorter。建议先去重——这样可以避免移动即将删除的数据，也能避免同名冲突；但反过来操作也不会漏掉任何内容：去重依据文件内容，与目录结构无关（已验证，两种顺序找到的重复文件组完全相同）。file-sorter 会报告 suspected copies: X MB (N% of the bytes to move)，你可以根据具体数字决定，而不必遵循固定规则。完整列表请参阅 skills/README.md。媒体资源库的命名属于独立项目：media-manager-skill。

---

工作原理

ZSpace 没有官方 CLI 或公共 API。zspace-cli 与桌面客户端的本地代理通信，因此只要客户端在线，即使处于 NAT 后也能使用：

Skill / zs / SDK / MCP  →  127.0.0.1:13579 (desktop client proxy)  →  NAS

免责声明 — 这是一个非官方、由社区维护的项目，与 ZSpace（极空间）无关联，也未获其认可。它依赖桌面客户端的本地代理接口，而该接口未经官方文档说明。它只读取你自己的机器上你自己的账户登录状态——不会绕过身份验证、破解加密，也不会触碰他人的数据。使用风险自负；请确保你的使用符合 ZSpace 用户协议和当地法律。

平台支持

适用于任何 ZSpace 桌面客户端会在 127.0.0.1:13579 暴露本地代理的操作系统。登录状态（vuex.json）会自动检测：

平台	默认位置
macOS	~/Library/Application Support/zspace/vuex.json
Windows	%APPDATA%\zspace\vuex.json（也会尝试 %LOCALAPPDATA%、%USERPROFILE%）
Linux	~/.zspace/vuex.json、~/.config/zspace/vuex.json（尽力检测）

如果客户端将文件存储在其他位置，请显式指定 CLI/SDK 使用的路径：

zs --config-dir ~/path/to/zspace-config check
ZS_CONFIG_DIR=~/path/to/zspace-config zs check   # or as an env var

Windows/Linux 配置位置是尽力猜测的结果（尚未在真实客户端上验证）。如果自动检测未找到你的文件，请提交 issue 并提供实际路径，以便将其加入支持列表。

Windows ARM 设备 — 某些 [mcp] 依赖项（例如 cryptography）并非每个版本都提供 ARM64 wheel，因此 pip install "zspace-cli[mcp]" 可能会尝试从源代码构建（速度慢，或因缺少 Rust 而失败）。请强制使用预构建 wheel： pip install --only-binary=:all: "zspace-cli[mcp]"。

MCP 配置（可选）

{
  "mcpServers": {
    "zspace": { "command": "zs-mcp", "args": [] }
  }
}

Docker（无头模式）

每次发布都会将多架构镜像（linux/amd64、linux/arm64）推送到 GHCR，因此无需构建：

docker pull ghcr.io/skyzhao1223/zspace-cli:latest   # or pin a release, e.g. :0.1.9
docker run --rm --network host \
  -e ZS_BASE_URL=http://127.0.0.1:13579 \
  -e ZS_CONFIG_DIR=/config \
  -v "$HOME/Library/Application Support/zspace:/config:ro" \
  ghcr.io/skyzhao1223/zspace-cli zs check

镜像的默认命令是 zs-mcp，因此 MCP 客户端可以直接运行 ghcr.io/skyzhao1223/zspace-cli 来启动服务；传入 zs … 则改为使用 CLI。标签包括 latest 和每个发布版本。

通过 compose 在容器中运行 CLI / MCP 服务，并连接到主机上的桌面客户端代理——镜像内无需桌面客户端：

export ZS_CONFIG_HOST_DIR="$HOME/Library/Application Support/zspace"   # macOS
# export ZS_CONFIG_HOST_DIR="$APPDATA/zspace"                          # Windows
# export ZS_CONFIG_HOST_DIR="$HOME/.zspace"                            # Linux
docker compose build
docker compose run --rm zspace-cli zs check
docker compose run --rm zspace-cli zs ls /sata11/my/data

它会以只读方式挂载主机的 ZSpace 配置（ZS_CONFIG_HOST_DIR），并通过 host.docker.internal 将 ZS_BASE_URL 指向主机。在 Linux 主机上，可使用 network_mode: host 或内置的 extra_hosts 映射。若要自行构建镜像，而非从 GHCR 拉取：

docker build -t zspace-cli .
docker run --rm --network host \
  -e ZS_BASE_URL=http://127.0.0.1:13579 \
  -e ZS_CONFIG_DIR=/config \
  -v "$HOME/Library/Application Support/zspace:/config:ro" \
  zspace-cli zs check

Glob 匹配

rm / mv / cp / down 支持 glob 模式（*、?、[...]、**），并会在 NAS 上展开：

zs rm "/sata11/my/data/影视/*.mkv" --force
zs cp "/sata11/my/data/**/*.mp4" /sata11/my/data/movies
zs down "/sata11/my/data/photos/*.jpg" ./photos

也可以通过 SDK 使用：client.glob("/sata11/my/data/**/*.mkv")。

---

API 参考

端点	关键参数
/v2/file/list	path、show_hidden、start、limit
/v2/file/info	path
/v2/file/modify	path、newname
/v2/file/newdir	parent、name、rename=0
/v2/file/move / copy	paths[]、to
/v2/file/remove	paths[]
/v2/file/create	二进制请求体，path 标头使用 UTF-8 字节（小文件上传；超过大小上限时代理会返回 413）
/v2/file/upload	分片上传：查询参数 uuid=md5(mtime_ms+size+target_path)；每个 2 MB 分片需设置标头 seek/split=1/size/path
/v2/file/download	GET path，remote_port=8050
/file_search/file_search	keyword

注意：接口参数名称并不常见（使用 parent / to，而不是 path / dest）——这是社区根据桌面客户端的行为记录的。

---

仓库结构

zspace-cli/
├── src/zspace_cli/
│   ├── cli.py         # Typer CLI (zs ...)
│   ├── client.py      # ZSpaceClient SDK (retry / stream / progress)
│   ├── auth.py        # vuex.json auto-detection + credential cache
│   ├── mcp_server.py  # MCP tools (zs-mcp)
│   └── skills/        # packaged skill copies shipped in the wheel (keep in sync!)
├── skills/            # skill sources — the source of truth (edit here)
├── scripts/mcp_smoke.py
├── tests/             # pytest (CLI + SDK + MCP + auth)
└── promo/             # launch/promo material (submodule)

---

集成

将 zspace-cli 与 Jellyfin / Emby / MoviePilot / MCP 客户端 / Docker 以及 media-manager-skill 搭配使用，为媒体库管理提供工具。

对于云盘 → NAS 工作流，可搭配 baidu-pan-skill：它能可靠下载百度网盘分享链接（提取 cookie、转存、断点续传分块下载、结构验证），随后由 zs up 接手，将大文件分片上传到 NAS。两者都以 Agent 技能形式提供，因此只需一条提示词即可驱动整个备份流程。

---

路线图

• 文件上传／下载
• Linux／Windows 客户端身份验证（尽力检测路径 + ZS_CONFIG_DIR）
• Docker 无头模式选项（ZS_BASE_URL + docker-compose.yml）
• 在 GHCR 上发布预构建的多架构镜像（ghcr.io/skyzhao1223/zspace-cli，每次发布时更新）
• 批量 glob 辅助功能（glob() + zs rm/mv/cp/down 模式）
• Agent 技能系列：9 个跨 NAS 整理工具（包括用于通用类型归档的 file-sorter）+ nas-report 入口，支持选择性安装（zs skill --list/--only）
• 可选的基于 EXIF 的照片日期识别（photo-organizer --exif：依次使用 exiftool、mdls，最后回退到 mtime）——#14
• 各技能的配置覆盖（skills/<name>/config.json：目录白名单／扩展名规则）——#15 · 已为全部 8 个扫描器提供（特意排除 nas-report）。各技能的配置键集合有所不同，其中 5 个技能的 whitelist_dirs 有 4 种不同效果——参见 skills/README.md 中的系列对照表
• 增长趋势报告（nas-report diff 对比两个快照：类别／目录增长量、增长率和预计时间）——#16

---

参与贡献

欢迎提交 PR——开发环境设置、质量检查标准和技能编写指南，请参阅 CONTRIBUTING.md（其中包括 CI 强制执行的 skills/ ↔ src/zspace_cli/skills/ 双份副本同步规则）。

• 🧭 不确定从哪里开始？ 可从 CONTRIBUTION_IDEAS.md （按难度标记的待办列表，包括逆向工程得出的 NAS API 说明）中选择，或查看 good first issue 标签
• 💬 问题与项目展示：Discussions
• 🔒 安全问题：通过 SECURITY.md 私下报告
• 🤝 本项目遵循 Contributor Covenant

法律声明

非官方社区项目，与 ZSpace／极空间无关联，也未获其认可。 本项目仅自动化操作你自己的机器上你自己的已登录桌面客户端—— 不处理密码，不绕过服务限制（会员专属功能会注明受限，绝不尝试规避）。API 说明记录的是观察到的客户端行为，以供互操作参考，可能会因客户端更新而失效。 如有疑虑或需要请求下架，请联系：[email protected]—— 我们会及时回应合理请求。每个 GitHub Release 都附带源代码归档；维护者也会在平台外保留 git bundle 镜像。

许可证

MIT