内容
# zspace-cli
**极空间 NAS 的命令行工具、Python SDK 和 MCP Server**
> 从终端、Python 脚本或 AI 智能体管理极空间 NAS 文件 — 零配置，无需 SSH。
[English](#features) | [中文](#功能特性)
---
## 为什么选择 zspace-cli？
极空间是国内知名的 NAS 品牌，但官方缺乏 CLI 工具和开发者 API。
**zspace-cli** 通过逆向工程极空间桌面客户端的内部 API，实现了**完整的文件管理功能**，并封装成：
- **`zs` 命令行工具** — 10 个命令涵盖所有文件操作，输出美观，基于 [Rich](https://github.com/Textualize/rich)
- **Python SDK** — `ZSpaceClient` 提供简洁、类型安全的接口，适用于自动化脚本
- **MCP Server** — 一行命令即可为 Claude、Cursor 或任何 MCP 兼容的 AI 智能体添加极空间文件管理功能
### 零配置
只需安装并运行。zspace-cli 直接读取运行中的极空间桌面客户端的认证令牌 — 无需密码、无需 SSH 密钥、无需端口转发。
```bash
pip install zspace-cli
zs check # ✓ 已连接，11.8 TB 总容量，1.2 TB 可用
zs ls # 列出 NAS 文件
```
---
## 功能特性
| 操作 | 命令行工具 | Python SDK | MCP Server |
|-----------|-----|-----|-----|
| 列出目录 | `zs ls [路径]` | `client.ls(路径)` | `zspace_ls` |
| 文件信息 | `zs info <路径>` | `client.info(路径)` | `zspace_info` |
| 重命名 | `zs rename <路径> <新名称>` | `client.rename(路径, 新名称)` | `zspace_rename` |
| 创建目录 | `zs mkdir <上级目录> <新目录名称>` | `client.mkdir(上级目录, 新目录名称)` | `zspace_mkdir` |
| 移动 | `zs mv <源路径> <目标路径>` | `client.move(源路径, 目标路径)` | `zspace_move` |
| 复制 | `zs cp <源路径> <目标路径>` | `client.copy(源路径, 目标路径)` | `zspace_copy` |
| 删除 | `zs rm <路径>` | `client.remove(路径)` | `zspace_remove` |
| 搜索 | `zs find <关键词>` | `client.search(关键词)` | `zspace_search` |
| 树形视图 | `zs tree [路径]` | `client.tree(路径)` | `zspace_tree` |
| 健康检查 | `zs check` | `client.is_connected()` | `zspace_check` |
---
## 安装
```bash
pip install zspace-cli
```
**前提条件：** 极空间桌面客户端已在 macOS 上运行并登录。
### 开启 MCP Server 支持
```bash
pip install "zspace-cli[mcp]"
```
---
## 快速开始
### 命令行工具
```bash
# 检查连接
zs check
# 列出文件
zs ls /sata11/my/data
zs ls -l /sata11/my/data/影视 # 详细模式
# 文件操作
zs mkdir /sata11/my/data 新文件夹
zs rename /sata11/my/data/旧名称 新名称
zs mv /sata11/my/data/文件.mp4 /sata11/my/data/影视
zs cp /sata11/my/data/重要文件 /sata11/my/data/备份
zs rm /sata11/my/data/临时文件
# 搜索与探索
zs find "权力的游戏"
zs tree /sata11/my/data -d 3
```
### Python SDK
```python
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}")
# 批量重命名视频
for f in zs.ls("/sata11/my/data/影视"):
if f.name.startswith("[raw]"):
new_name = f.name.replace("[raw]", "").strip()
zs.rename(f.path, new_name)
print(f"重命名：{new_name}")
# 整理文件
zs.mkdir("/sata11/my/data", "已整理")
zs.move("/sata11/my/data/散文件.pdf", "/sata11/my/data/已整理")
```
### MCP Server（适用于 AI 智能体）
在 Claude Desktop 或 Cursor 的 MCP 配置中添加：
```json
{
"mcpServers": {
"zspace": {
"command": "zs-mcp",
"args": []
}
}
}
```
然后询问你的 AI： "帮我把 NAS 上影视文件夹里的视频按年份整理一下"
---
## 工作原理
```
┌─────────────┐ ┌──────────────────┐ ┌──────────┐
│ zs 命令行工具 │ │ 极空间桌面客户端（代理） │ │ 极空间 │
│ Python SDK ├─────►│ 客户端（代理） ├─────►│ NAS │
│ MCP Server │ HTTP │ 127.0.0.1:13579 │ P2P │ 设备 │
└─────────────┘ └──────────────────┘ └──────────┘
```
极空间桌面客户端在本地 `127.0.0.1:13579` 建立了到 NAS 的加密代理。zspace-cli 通过这个代理调用和官方 Web UI 完全相同的 API，因此：
- 不需要 NAS 在局域网内
- 不需要配置 DDNS 或端口转发
- 不需要开启 SSH
- 只要桌面客户端在运行，就能操作
---
## API 参考
所有操作均通过极空间内部 API `127.0.0.1:13579` 进行。
| 端点 | 方法 | 关键参数 |
|----------|--------|---------------|
| `/v2/file/list` | POST | `path`, `show_hidden` |
| `/v2/file/info` | POST | `path` |
| `/v2/file/modify` | POST | `path`, `newname` |
| `/v2/file/newdir` | POST | `parent` （不是路径！），`name`，`rename=0` |
| `/v2/file/move` | POST | `paths[]` （数组），`to` （不是目标！） |
| `/v2/file/copy` | POST | `paths[]` （数组），`to` （不是目标！） |
| `/v2/file/remove` | POST | `paths[]` （数组） |
> **关键发现：** 参数名称不标准 — `newdir` 使用 `parent` 而不是 `path`，而 `move`/`copy` 使用 `to` 而不是 `dest`。这些参数是通过逆向工程极空间 Web UI 发现的。
---
## 技能
### 媒体管理器
一个 [Cursor AI Skill](https://docs.cursor.com/features/skills)，用于整理极空间 NAS 上的电影和 TV 系列。详见 [`skills/media-manager/`](skills/media-manager/)。
命名规范和通用方法论见独立项目 [media-naming-guide](https://github.com/skyzhao1223/media-naming-guide)。
---
## 路线图
- [ ] 文件上传/下载支持
- [ ] Linux 客户端支持
- [ ] Windows 客户端支持
- [ ] 无头部署的 Docker 镜像
- [ ] 支持 glob 模式的批量操作
- [ ] 文件监视/同步触发器
---
## 贡献
欢迎贡献！请先开启一个 issue 讨论您想更改的内容。
---
## 许可证
MIT
---
<details>
<summary><h2>中文说明</h2></summary>
## 功能特性
**zspace-cli** 是极空间 NAS 的命令行工具、Python SDK 和 MCP Server。
通过逆向工程极空间桌面客户端的内部 API，实现了**完整的文件管理功能**——无需 SSH，无需 WebDAV，零配置即可使用。
### 安装
```bash
pip install zspace-cli
```
**前提条件：** macOS 上已安装并登录极空间桌面客户端。
### 使用方法
```bash
# 检查连接
zs check
# 文件操作
zs ls # 列出目录
zs ls -l /sata11/my/data/影视 # 详细模式
zs info /sata11/my/data/影视 # 查看详情
zs mkdir /sata11/my/data 新文件夹 # 创建目录
zs rename /path/old new_name # 重命名
zs mv /path/src /path/dest # 移动
zs cp /path/src /path/dest # 复制
zs rm /path/to/delete # 删除
zs find "关键词" # 搜索
zs tree /sata11/my/data -d 3 # 树形视图
```
### MCP Server 配置（AI 智能体）
在 Claude Desktop 或 Cursor 的 MCP 配置中添加：
```json
{
"mcpServers": {
"zspace": {
"command": "zs-mcp",
"args": []
}
}
}
```
配置完成后，你可以用自然语言让 AI 管理你的 NAS 文件：
- "帮我把影视文件夹里的电影按年份分类"
- "查找所有大于 10GB 的文件"
- "把百度网盘文件夹里的文档移到文档同步文件夹"
### Cursor Skill: 影视文件管理
内置 [Cursor AI Skill](https://docs.cursor.com/features/skills)，可以让 AI 帮你整理 NAS 上的影视资源。详见 [`skills/media-manager/`](skills/media-manager/)。
命名规范和通用方法论见独立项目 [media-naming-guide](https://github.com/skyzhao1223/media-naming-guide)。
### 工作原理
极空间桌面客户端在本机 `127.0.0.1:13579` 建立了到 NAS 的加密代理。zspace-cli 通过这个代理调用和官方 Web UI 完全相同的 API，因此：
- 不需要 NAS 在局域网内
- 不需要配置 DDNS 或端口转发
- 不需要开启 SSH
- 只要桌面客户端在运行，就能操作
</details>
