zspace-cli

极空间 (ZSpace) NAS をターミナルまたは AI エージェントから管理できます — パスワード不要、SSH 不要、DDNS 不要。

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

macOS 上で ZSpace デスクトップクライアントにログインしたままにしておくだけです。

📖 大容量ファイルの分割アップロードがどのように生まれたか：一次 1.4GB 备份引发的逆向 (zh, CSDN) · CLI ガイド：极空间 NAS 命令行管理指南 (zh, CSDN)

初心者ガイド（コーディング不要） · Skills — AI エージェント向けの NAS 横断オーガナイザー 9 種を含む · 中文文档

---

インストール

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

前提条件： macOS 上で ZSpace デスクトップクライアントが起動し、ログインしていること。

---

クイックスタート

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/* モジュール経由の Baidu NetDisk（読み取り側。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 は 1 回の呼び出しで最大 50 エントリを返します）。find は NAS の全文インデックスを使用するため、ディレクトリをまたいで検索します。アップロード/ダウンロードは実際のターミナルでプログレスバーを表示し、ファイルをストリーミングします（ファイル全体のバッファリングは行いません）。zs up に --verify を渡すと、アップロードされたファイルを一時ディレクトリにダウンロードし、その MD5 をローカルのソースと比較します。検証は転送量が 2 倍になるためオプトインです。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 エージェントとの併用（スキル）

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

次に、エージェントに「/sata11/my/data 内のファイルを一覧表示して」などと指示します。スキルは wheel に同梱されているため、zspace-cli がインストールされているマシンであればどこでも zs skill が動作します。

zspace-nas（ZSpace のファイル操作向けゼロ設定のベース）に加えて、zs skill は 9 種類の NAS 横断オーガナイザースキル 群をインストールします。これらのスキャナーは純粋な標準ライブラリのみで構成され、マウントされた 任意のパス（SMB/NFS）で動作するため、ZSpace、Synology、QNAP、UGREEN などで利用できます。すべて同じ読み取り専用パターンに従います: スキャン → LLM が old→new の計画を起草 → あなたが確認 → エージェントが実行（削除は常にまず隔離されます）。

スキル	機能
nas-report	🧭 エントリーポイント: ディスク全体のストレージプロファイル + 適切な専門スキルへのルーティング
file-sorter	🧹 あらゆる混在ファイル群: 15 カテゴリにわたる 255 の拡張子 を認識し（写真 / 動画 / 音声 / ドキュメント / 電子書籍 / アーカイブ / インストーラー / フォント / コード / デザインソース / CAD 図面 / ディスクイメージ…）、各 old → new パスを計算し、135 のフォルダ名エイリアス（簡体字 + 繁体字中国語 + 英語）を把握しているため、すでに整理済みのライブラリが再整理されることはありません。デフォルトではプロジェクトフォルダを分割しません
photo-organizer	写真/動画: 撮影日ごとの整理（--exif は exiftool 経由、または macOS では mdls 経由で実際の撮影日を読み取ります）、スクリーンショット/WeChat 画像、連写の重複排除
music-organizer	音楽: アーティスト/アルバム/トラック構造、トラック番号、カバー、組み込みの ID3v2 パース
work-organizer	仕事ファイル: 散在ファイルのアーカイブ、バージョン混乱、コピー、古いファイルのアーカイブ
portfolio-organizer	ポートフォリオ: プロジェクト構造、カバー/README、完成品とソースの分離
download-cleaner	ダウンロード: トリアージと整理（部分ファイル/トレント/インストーラー/アーカイブ/未整理メディア）
dedup-finder	コンテンツレベルの完全重複排除（サイズ→先頭→完全 sha1 の 3 段階フィンガープリント、誤検出ゼロ）
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 で公開する任意の OS で動作します。ログイン状態 (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 on 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 を直接実行してサーバーを起動できます。代わりに CLI を使用するには zs … を渡してください。タグは 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

グロブ

rm / mv / cp / down は 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)、ヘッダー seek/split=1/size/path を 2 MB スライスごとに
/v2/file/download	GET path、remote_port=8050
/file_search/file_search	keyword

注：インターフェースのパラメータ名は非標準です (path / dest ではなく parent / to) — デスクトップクライアントの動作に基づきコミュニティによって文書化されました。

---

リポジトリ構成

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 を組み合わせてください：Baidu NetDisk (百度网盘) の共有リンクを確実にダウンロードし (cookie 抽出、転送保存、再開可能なチャンクダウンロード、構造検証)、その後 zs up が NAS への分割大ファイルアップロードを引き継ぎます。どちらもエージェントスキルとして提供されるため、1 つのプロンプトでバックアップ全体を実行できます。

---

ロードマップ

• ファイルのアップロード/ダウンロード
• 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 パターン)
• エージェントスキルファミリー: 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 は意図的に除外)。キーセットはスキルごとに異なり、whitelist_dirs は 5 つのスキルで 4 つの異なる効果を持ちます — 詳細は skills/README.md のファミリーテーブルを参照してください
• 成長トレンドレポート (nas-report diff の 2 つのスナップショット: カテゴリ/ディレクトリの成長、レート & ETA) — #16

---

コントリビューション

PR を歓迎します — 開発環境のセットアップ、品質ゲート、スキル作成ガイド (CI が強制する skills/ ↔ src/zspace_cli/skills/ の二重コピー同期ルールを含む) については CONTRIBUTING.md を参照してください。

• 🧭 どこから始めればよいかわからない？ CONTRIBUTION_IDEAS.md (難易度タグ付きバックログ、リバースエンジニアリングされた NAS API ノートを含む) または good first issue ラベルから選んでください
• 💬 質問 & ショーケース: Discussions
• 🔒 セキュリティ問題: SECURITY.md による非公開報告
• 🤝 このプロジェクトは Contributor Covenant に従います

法的情報

非公式のコミュニティプロジェクトであり、ZSpace/极空间 とは提携しておらず、承認も受けていません。 これは あなた自身の マシン上で あなた自身の ログイン済みデスクトップクライアントを自動化するものです — パスワードの取り扱いも、サービスゲートのバイパスもありません (メンバーシップ限定機能はゲート付きとして文書化され、決して回避されません)。API ノートは観察されたクライアント動作の相互運用性ドキュメントであり、クライアントの更新により動作しなくなる可能性があります。 懸念事項や削除要請: [email protected] — 正当な要請には速やかに対応します。ソースアーカイブはすべての GitHub リリースに同梱されています。メンテナーはプラットフォーム外の git bundle ミラーを維持しています。

ライセンス

MIT