ncm-dl 0.1.0__tar.gz

ncm_dl-0.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.3
+Name: ncm-dl
+Version: 0.1.0
+Summary: Small uv/Python CLI for downloading NetEase Cloud Music tracks.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# ncm-dl
+
+`ncm-dl` 是一个基于 uv/Python 的网易云音乐命令行下载工具。
+
+运行时只用 Python 标准库，不依赖第三方包。配置优先读取环境变量，命令行参数可以覆盖环境变量。
+
+## 用法
+
+```bash
+cd ~/ncm-dl
+
+uv run ncm-dl search "晴天"
+uv run ncm-dl download 186016 --output ~/音乐
+uv run ncm-dl url 186016
+```
+
+`download` 也可以写成 `dl`：
+
+```bash
+uv run ncm-dl dl 186016
+```
+
+下载整个网易云歌单并生成 Navidrome 可导入的 M3U：
+
+```bash
+export MUSIC_U='your_cookie_value'
+uv run ncm-dl playlist 你的歌单ID \
+  --music-root /opt/navidrome/music \
+  --level lossless \
+  --navidrome-scan \
+  --navidrome-import \
+  --navidrome-sudo \
+  --sync
+```
+
+先不下载、只确认歌单是否能读取：
+
+```bash
+uv run ncm-dl playlist 你的歌单ID --dry-run --limit 10
+```
+
+默认会把歌曲下载到：
+
+```text
+/opt/navidrome/music/netease/<歌单名-歌单ID>/
+```
+
+并生成：
+
+```text
+/opt/navidrome/music/playlists/<歌单名-歌单ID>.m3u
+```
+
+M3U 里的歌曲路径会相对 `--music-root` 写入，适合 Navidrome 扫描和 `navidrome pls import`。
+
+## 环境变量
+
+支持这些环境变量：
+
+| 变量 | 作用 |
+| --- | --- |
+| `MUSIC_U` | 网易云 `MUSIC_U` cookie，用于付费/VIP/无损歌曲。 |
+| `OUTPUT_DIR` | 默认下载目录。 |
+| `LEVEL` | 默认音质：`standard`、`higher`、`exhigh`、`lossless`、`hires`。默认 `exhigh`。 |
+| `LIMIT` | 默认搜索结果数量。默认 `10`。 |
+| `OVERWRITE` | 设为 `1`、`true` 或 `yes` 时，默认覆盖同名文件。 |
+| `CHECK_MD5` | 设为 `0`、`false` 或 `no` 时，默认关闭 MD5 校验。 |
+| `NAVIDROME_MUSIC_ROOT` | `playlist` 命令默认音乐库根目录。默认 `/opt/navidrome/music`。 |
+| `NAVIDROME_BIN` | `playlist --navidrome-import` 使用的 Navidrome 可执行文件。默认 `navidrome`。 |
+| `NAVIDROME_CONFIG` | Navidrome 配置文件。默认 `/etc/navidrome/navidrome.toml`。 |
+| `NAVIDROME_USER` | 导入歌单所属的 Navidrome 用户。默认第一个管理员。 |
+| `NAVIDROME_SUDO` | 设为 `1`、`true` 或 `yes` 时，导入步骤使用 `sudo navidrome`。 |
+| `NAVIDROME_SYNC` | 设为 `1`、`true` 或 `yes` 时，导入时加 `--sync`。 |
+| `NCM_TIMEOUT` | 下载超时时间，单位秒。默认 `60`。 |
+| `NCM_USER_AGENT` | 自定义请求 User-Agent。 |
+
+示例：
+
+```bash
+export MUSIC_U='your_cookie_value'
+export OUTPUT_DIR="$HOME/音乐"
+export LEVEL=lossless
+
+uv run ncm-dl dl 186016
+```
+
+## 说明
+
+- 本工具不会把 `MUSIC_U` 写入磁盘。
+- 如果歌曲没有返回可播放 URL，通常需要设置有效网易云账号的 `MUSIC_U`。
+- 网易云返回 MD5 时会默认校验下载文件；只有排查问题时才建议使用 `--no-md5`。

ncm_dl-0.1.0/README.md

@@ -0,0 +1,91 @@
+# ncm-dl
+
+`ncm-dl` 是一个基于 uv/Python 的网易云音乐命令行下载工具。
+
+运行时只用 Python 标准库，不依赖第三方包。配置优先读取环境变量，命令行参数可以覆盖环境变量。
+
+## 用法
+
+```bash
+cd ~/ncm-dl
+
+uv run ncm-dl search "晴天"
+uv run ncm-dl download 186016 --output ~/音乐
+uv run ncm-dl url 186016
+```
+
+`download` 也可以写成 `dl`：
+
+```bash
+uv run ncm-dl dl 186016
+```
+
+下载整个网易云歌单并生成 Navidrome 可导入的 M3U：
+
+```bash
+export MUSIC_U='your_cookie_value'
+uv run ncm-dl playlist 你的歌单ID \
+  --music-root /opt/navidrome/music \
+  --level lossless \
+  --navidrome-scan \
+  --navidrome-import \
+  --navidrome-sudo \
+  --sync
+```
+
+先不下载、只确认歌单是否能读取：
+
+```bash
+uv run ncm-dl playlist 你的歌单ID --dry-run --limit 10
+```
+
+默认会把歌曲下载到：
+
+```text
+/opt/navidrome/music/netease/<歌单名-歌单ID>/
+```
+
+并生成：
+
+```text
+/opt/navidrome/music/playlists/<歌单名-歌单ID>.m3u
+```
+
+M3U 里的歌曲路径会相对 `--music-root` 写入，适合 Navidrome 扫描和 `navidrome pls import`。
+
+## 环境变量
+
+支持这些环境变量：
+
+| 变量 | 作用 |
+| --- | --- |
+| `MUSIC_U` | 网易云 `MUSIC_U` cookie，用于付费/VIP/无损歌曲。 |
+| `OUTPUT_DIR` | 默认下载目录。 |
+| `LEVEL` | 默认音质：`standard`、`higher`、`exhigh`、`lossless`、`hires`。默认 `exhigh`。 |
+| `LIMIT` | 默认搜索结果数量。默认 `10`。 |
+| `OVERWRITE` | 设为 `1`、`true` 或 `yes` 时，默认覆盖同名文件。 |
+| `CHECK_MD5` | 设为 `0`、`false` 或 `no` 时，默认关闭 MD5 校验。 |
+| `NAVIDROME_MUSIC_ROOT` | `playlist` 命令默认音乐库根目录。默认 `/opt/navidrome/music`。 |
+| `NAVIDROME_BIN` | `playlist --navidrome-import` 使用的 Navidrome 可执行文件。默认 `navidrome`。 |
+| `NAVIDROME_CONFIG` | Navidrome 配置文件。默认 `/etc/navidrome/navidrome.toml`。 |
+| `NAVIDROME_USER` | 导入歌单所属的 Navidrome 用户。默认第一个管理员。 |
+| `NAVIDROME_SUDO` | 设为 `1`、`true` 或 `yes` 时，导入步骤使用 `sudo navidrome`。 |
+| `NAVIDROME_SYNC` | 设为 `1`、`true` 或 `yes` 时，导入时加 `--sync`。 |
+| `NCM_TIMEOUT` | 下载超时时间，单位秒。默认 `60`。 |
+| `NCM_USER_AGENT` | 自定义请求 User-Agent。 |
+
+示例：
+
+```bash
+export MUSIC_U='your_cookie_value'
+export OUTPUT_DIR="$HOME/音乐"
+export LEVEL=lossless
+
+uv run ncm-dl dl 186016
+```
+
+## 说明
+
+- 本工具不会把 `MUSIC_U` 写入磁盘。
+- 如果歌曲没有返回可播放 URL，通常需要设置有效网易云账号的 `MUSIC_U`。
+- 网易云返回 MD5 时会默认校验下载文件；只有排查问题时才建议使用 `--no-md5`。

ncm_dl-0.1.0/pyproject.toml

@@ -0,0 +1,14 @@
+[project]
+name = "ncm-dl"
+version = "0.1.0"
+description = "Small uv/Python CLI for downloading NetEase Cloud Music tracks."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = []
+
+[project.scripts]
+ncm-dl = "ncm_dl.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.8.0,<0.9.0"]
+build-backend = "uv_build"

ncm_dl-0.1.0/src/ncm_dl/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

ncm_dl-0.1.0/src/ncm_dl/cli.py

@@ -0,0 +1,529 @@
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import subprocess
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+API_BASE = "https://music.163.com"
+DEFAULT_UA = (
+    "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 "
+    "(KHTML, like Gecko) Chrome/126.0 Safari/537.36"
+)
+LEVEL_TO_BR = {
+    "standard": 128000,
+    "higher": 192000,
+    "exhigh": 320000,
+    "lossless": 999000,
+    "hires": 1999000,
+}
+
+
+class NCMError(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True)
+class Song:
+    id: int
+    name: str
+    artists: str
+    album: str
+    duration_ms: int
+
+
+@dataclass(frozen=True)
+class SongURL:
+    url: str
+    size: int
+    md5: str
+    ext: str
+    level: str
+    br: int
+
+
+@dataclass(frozen=True)
+class Playlist:
+    id: int
+    name: str
+    track_ids: list[int]
+
+
+def env(name: str, default: str | None = None) -> str | None:
+    value = os.environ.get(name)
+    if value is None or value == "":
+        return default
+    return value
+
+
+def request_json(
+    endpoint: str,
+    *,
+    query: dict[str, Any] | None = None,
+    form: dict[str, Any] | None = None,
+    music_u: str | None = None,
+    timeout: int = 20,
+) -> dict[str, Any]:
+    url = API_BASE + endpoint
+    if query:
+        url += "?" + urllib.parse.urlencode(query)
+
+    data = None
+    headers = {
+        "Accept": "application/json,text/plain,*/*",
+        "Referer": "https://music.163.com/",
+        "User-Agent": env("NCM_USER_AGENT", DEFAULT_UA) or DEFAULT_UA,
+    }
+    if music_u:
+        headers["Cookie"] = f"MUSIC_U={music_u}"
+    if form:
+        data = urllib.parse.urlencode(form).encode()
+        headers["Content-Type"] = "application/x-www-form-urlencoded"
+
+    req = urllib.request.Request(url, data=data, headers=headers)
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            raw = resp.read().decode("utf-8")
+    except urllib.error.HTTPError as exc:
+        raise NCMError(f"HTTP {exc.code}: {url}") from exc
+    except urllib.error.URLError as exc:
+        raise NCMError(f"request failed: {exc.reason}") from exc
+
+    try:
+        parsed = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise NCMError(f"invalid JSON from {endpoint}: {raw[:120]}") from exc
+    if not isinstance(parsed, dict):
+        raise NCMError(f"unexpected response from {endpoint}")
+    return parsed
+
+
+def parse_song(raw: dict[str, Any]) -> Song:
+    artists_raw = raw.get("artists") or raw.get("ar") or []
+    album_raw = raw.get("album") or raw.get("al") or {}
+    artists = ", ".join(a.get("name", "") for a in artists_raw if a.get("name"))
+    return Song(
+        id=int(raw["id"]),
+        name=str(raw.get("name") or "Unknown"),
+        artists=artists or "Unknown",
+        album=str(album_raw.get("name") or "Unknown"),
+        duration_ms=int(raw.get("duration") or raw.get("dt") or 0),
+    )
+
+
+def song_detail(song_id: int, music_u: str | None) -> Song:
+    data = request_json(
+        "/api/song/detail/",
+        query={"ids": json.dumps([song_id], separators=(",", ":"))},
+        music_u=music_u,
+    )
+    songs = data.get("songs") or []
+    if not songs:
+        raise NCMError(f"song not found: {song_id}")
+    return parse_song(songs[0])
+
+
+def search_songs(keyword: str, limit: int, music_u: str | None) -> list[Song]:
+    data = request_json(
+        "/api/search/get/web",
+        form={"s": keyword, "type": 1, "limit": limit, "offset": 0, "total": "true"},
+        music_u=music_u,
+    )
+    songs = ((data.get("result") or {}).get("songs")) or []
+    return [parse_song(song) for song in songs]
+
+
+def playlist_detail(playlist_id: int, music_u: str | None) -> Playlist:
+    data = request_json(
+        "/api/v6/playlist/detail",
+        query={"id": playlist_id, "n": 100000, "s": 8},
+        music_u=music_u,
+    )
+    playlist = data.get("playlist") or {}
+    if not playlist:
+        raise NCMError(f"playlist not found: {playlist_id}")
+
+    track_ids = []
+    for item in playlist.get("trackIds") or []:
+        try:
+            track_ids.append(int(item["id"]))
+        except (KeyError, TypeError, ValueError):
+            continue
+
+    if not track_ids:
+        for item in playlist.get("tracks") or []:
+            try:
+                track_ids.append(int(item["id"]))
+            except (KeyError, TypeError, ValueError):
+                continue
+
+    if not track_ids:
+        raise NCMError(f"playlist has no tracks: {playlist_id}")
+
+    return Playlist(
+        id=int(playlist.get("id") or playlist_id),
+        name=str(playlist.get("name") or f"playlist-{playlist_id}"),
+        track_ids=track_ids,
+    )
+
+
+def song_url(song_id: int, level: str, music_u: str | None) -> SongURL:
+    level = level.lower()
+    if level not in LEVEL_TO_BR:
+        raise NCMError(f"unknown level: {level}")
+
+    data = request_json(
+        "/api/song/enhance/player/url/v1",
+        query={
+            "ids": json.dumps([song_id], separators=(",", ":")),
+            "level": level,
+            "encodeType": "flac" if level in {"lossless", "hires"} else "mp3",
+        },
+        music_u=music_u,
+    )
+    items = data.get("data") or []
+
+    if not items or not items[0].get("url"):
+        data = request_json(
+            "/api/song/enhance/player/url",
+            query={"ids": json.dumps([song_id], separators=(",", ":")), "br": LEVEL_TO_BR[level]},
+            music_u=music_u,
+        )
+        items = data.get("data") or []
+
+    if not items or not items[0].get("url"):
+        raise NCMError("没有拿到可播放 URL；付费/VIP 歌曲请设置 MUSIC_U")
+
+    item = items[0]
+    ext = str(item.get("type") or "").lower()
+    if ext not in {"mp3", "flac"}:
+        path = urllib.parse.urlparse(str(item["url"])).path
+        suffix = Path(path).suffix.lstrip(".").lower()
+        ext = suffix if suffix in {"mp3", "flac"} else "mp3"
+    return SongURL(
+        url=str(item["url"]),
+        size=int(item.get("size") or 0),
+        md5=str(item.get("md5") or ""),
+        ext=ext,
+        level=str(item.get("level") or level),
+        br=int(item.get("br") or 0),
+    )
+
+
+def clean_filename(value: str) -> str:
+    value = re.sub(r'[\\/:*?"<>|]+', " ", value)
+    value = re.sub(r"\s+", " ", value).strip(" .")
+    return value or "Unknown"
+
+
+def output_path(song: Song, info: SongURL, output_dir: Path) -> Path:
+    return output_dir / f"{clean_filename(song.artists)} - {clean_filename(song.name)}.{info.ext}"
+
+
+def playlist_output_path(song: Song, info: SongURL, output_dir: Path) -> Path:
+    return output_dir / f"{clean_filename(song.artists)} - {clean_filename(song.name)} [{song.id}].{info.ext}"
+
+
+def format_size(size: int) -> str:
+    if size <= 0:
+        return "unknown"
+    units = ["B", "KiB", "MiB", "GiB"]
+    value = float(size)
+    unit = units[0]
+    for unit in units:
+        if value < 1024 or unit == units[-1]:
+            break
+        value /= 1024
+    return f"{value:.1f} {unit}"
+
+
+def download_file(url: str, dest: Path, expected_md5: str, overwrite: bool) -> None:
+    if dest.exists() and not overwrite:
+        raise NCMError(f"文件已存在: {dest}，可加 --overwrite 覆盖")
+
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    tmp = dest.with_suffix(dest.suffix + ".part")
+    headers = {"User-Agent": env("NCM_USER_AGENT", DEFAULT_UA) or DEFAULT_UA}
+    req = urllib.request.Request(url.replace("http://", "https://", 1), headers=headers)
+
+    try:
+        with urllib.request.urlopen(req, timeout=int(env("NCM_TIMEOUT", "60") or "60")) as resp:
+            total = int(resp.headers.get("Content-Length") or 0)
+            md5 = hashlib.md5()
+            written = 0
+            last_print = 0.0
+            with tmp.open("wb") as f:
+                while True:
+                    chunk = resp.read(1024 * 256)
+                    if not chunk:
+                        break
+                    f.write(chunk)
+                    md5.update(chunk)
+                    written += len(chunk)
+                    now = time.monotonic()
+                    if now - last_print >= 0.5:
+                        print_progress(written, total)
+                        last_print = now
+    except Exception:
+        if tmp.exists():
+            tmp.unlink()
+        raise
+
+    print_progress(tmp.stat().st_size, total)
+    print()
+
+    if expected_md5 and md5.hexdigest().lower() != expected_md5.lower():
+        tmp.unlink(missing_ok=True)
+        raise NCMError("MD5 校验失败")
+
+    tmp.replace(dest)
+
+
+def print_progress(written: int, total: int) -> None:
+    if total > 0:
+        percent = min(100, written * 100 // total)
+        bar_width = 24
+        filled = min(bar_width, written * bar_width // total)
+        bar = "#" * filled + "-" * (bar_width - filled)
+        msg = f"\r[{bar}] {percent:3d}% {format_size(written)}/{format_size(total)}"
+    else:
+        msg = f"\rdownloaded {format_size(written)}"
+    print(msg, end="", flush=True)
+
+
+def add_common(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--music-u", default=env("MUSIC_U"), help="网易云 MUSIC_U cookie；默认读取环境变量 MUSIC_U")
+    parser.add_argument("--level", default=env("LEVEL", "exhigh"), choices=sorted(LEVEL_TO_BR), help="音质等级；默认读取环境变量 LEVEL，未设置则 exhigh")
+
+
+def bool_env(name: str, default: bool = False) -> bool:
+    value = env(name)
+    if value is None:
+        return default
+    return value.lower() in {"1", "true", "yes", "on"}
+
+
+def cmd_search(args: argparse.Namespace) -> int:
+    songs = search_songs(args.keyword, args.limit, args.music_u)
+    if not songs:
+        print("没有找到歌曲")
+        return 1
+    for idx, song in enumerate(songs, 1):
+        duration = f"{song.duration_ms // 60000}:{song.duration_ms // 1000 % 60:02d}" if song.duration_ms else "?:??"
+        print(f"{idx:2d}. {song.id}  {song.name} - {song.artists}  [{song.album}] {duration}")
+    return 0
+
+
+def cmd_url(args: argparse.Namespace) -> int:
+    info = song_url(args.song_id, args.level, args.music_u)
+    print(info.url)
+    return 0
+
+
+def cmd_download(args: argparse.Namespace) -> int:
+    out = Path(args.output or env("OUTPUT_DIR", ".") or ".").expanduser()
+    song = song_detail(args.song_id, args.music_u)
+    info = song_url(args.song_id, args.level, args.music_u)
+    dest = Path(args.file).expanduser() if args.file else output_path(song, info, out)
+
+    print(f"歌曲: {song.name} - {song.artists}")
+    print(f"专辑: {song.album}")
+    print(f"音质: {info.level} {info.br // 1000 if info.br else '?'} kbps, {format_size(info.size)}")
+    print(f"输出: {dest}")
+    download_file(info.url, dest, info.md5 if args.check_md5 else "", args.overwrite)
+    print(f"完成: {dest}")
+    return 0
+
+
+def m3u_entry_path(path: Path, music_root: Path) -> str:
+    resolved = path.resolve()
+    try:
+        return resolved.relative_to(music_root.resolve()).as_posix()
+    except ValueError:
+        return str(resolved)
+
+
+def write_m3u(path: Path, playlist_name: str, tracks: list[tuple[Song, Path]], music_root: Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="utf-8", newline="\n") as f:
+        f.write("#EXTM3U\n")
+        f.write(f"#PLAYLIST:{playlist_name}\n")
+        for song, track_path in tracks:
+            duration = song.duration_ms // 1000 if song.duration_ms else 0
+            f.write(f"#EXTINF:{duration},{song.artists} - {song.name}\n")
+            f.write(m3u_entry_path(track_path, music_root) + "\n")
+
+
+def navidrome_cmd(args: argparse.Namespace, *parts: str) -> list[str]:
+    cmd = [
+        args.navidrome_bin,
+        "--configfile",
+        args.navidrome_config,
+    ]
+    cmd.extend(parts)
+    if args.navidrome_sudo:
+        cmd.insert(0, "sudo")
+    return cmd
+
+
+def scan_navidrome(args: argparse.Namespace) -> int:
+    cmd = navidrome_cmd(args, "scan")
+    if args.navidrome_full_scan:
+        cmd.append("--full")
+    print("Navidrome 扫描:", " ".join(cmd))
+    return subprocess.run(cmd, check=False).returncode
+
+
+def import_to_navidrome(args: argparse.Namespace, m3u_path: Path) -> int:
+    cmd = navidrome_cmd(args, "pls", "import")
+    if args.navidrome_user:
+        cmd.extend(["--user", args.navidrome_user])
+    if args.sync:
+        cmd.append("--sync")
+    cmd.append(str(m3u_path))
+    print("Navidrome 导入:", " ".join(cmd))
+    return subprocess.run(cmd, check=False).returncode
+
+
+def cmd_playlist(args: argparse.Namespace) -> int:
+    playlist = playlist_detail(args.playlist_id, args.music_u)
+    track_ids = playlist.track_ids[: args.limit] if args.limit else playlist.track_ids
+
+    music_root = Path(args.music_root).expanduser()
+    default_dir = music_root / "netease" / f"{clean_filename(playlist.name)}-{playlist.id}"
+    output_dir = Path(args.output).expanduser() if args.output else default_dir
+    default_m3u = music_root / "playlists" / f"{clean_filename(playlist.name)}-{playlist.id}.m3u"
+    m3u_path = Path(args.m3u).expanduser() if args.m3u else default_m3u
+
+    print(f"歌单: {playlist.name} ({playlist.id})")
+    print(f"曲目: {len(track_ids)}/{len(playlist.track_ids)}")
+    print(f"输出目录: {output_dir}")
+    print(f"M3U: {m3u_path}")
+    if args.dry_run:
+        print("dry-run: 只读取歌单，不下载、不写 m3u、不导入 Navidrome")
+        for idx, song_id in enumerate(track_ids[:20], 1):
+            print(f"{idx:3d}. {song_id}")
+        if len(track_ids) > 20:
+            print(f"... 还有 {len(track_ids) - 20} 首")
+        return 0
+
+    output_dir.mkdir(parents=True, exist_ok=True)
+    downloaded: list[tuple[Song, Path]] = []
+    failures: list[tuple[int, str]] = []
+
+    for idx, song_id in enumerate(track_ids, 1):
+        print(f"\n[{idx}/{len(track_ids)}] {song_id}")
+        try:
+            song = song_detail(song_id, args.music_u)
+            info = song_url(song_id, args.level, args.music_u)
+            dest = playlist_output_path(song, info, output_dir)
+            print(f"歌曲: {song.name} - {song.artists}")
+            print(f"专辑: {song.album}")
+            print(f"音质: {info.level} {info.br // 1000 if info.br else '?'} kbps, {format_size(info.size)}")
+            print(f"输出: {dest}")
+            if dest.exists() and not args.overwrite:
+                print("已存在，跳过下载")
+            else:
+                download_file(info.url, dest, info.md5 if args.check_md5 else "", args.overwrite)
+            if dest.exists():
+                downloaded.append((song, dest))
+        except NCMError as exc:
+            failures.append((song_id, str(exc)))
+            print(f"失败: {song_id}: {exc}", file=sys.stderr)
+            if args.strict:
+                break
+
+    write_m3u(m3u_path, playlist.name, downloaded, music_root)
+    print(f"\n已写入 M3U: {m3u_path}")
+    print(f"成功匹配文件: {len(downloaded)}/{len(track_ids)}")
+    if failures:
+        print(f"失败: {len(failures)}")
+        for song_id, reason in failures[:20]:
+            print(f"- {song_id}: {reason}", file=sys.stderr)
+
+    if args.navidrome_scan:
+        rc = scan_navidrome(args)
+        if rc != 0:
+            return rc
+
+    if args.navidrome_import:
+        rc = import_to_navidrome(args, m3u_path)
+        if rc != 0:
+            return rc
+
+    return 1 if failures and args.strict else 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="ncm-dl", description="基于 uv/Python 的网易云音乐下载 CLI。")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("search", help="搜索歌曲")
+    add_common(p)
+    p.add_argument("keyword")
+    p.add_argument("--limit", type=int, default=int(env("LIMIT", "10") or "10"))
+    p.set_defaults(func=cmd_search)
+
+    p = sub.add_parser("url", help="输出歌曲真实播放 URL")
+    add_common(p)
+    p.add_argument("song_id", type=int)
+    p.set_defaults(func=cmd_url)
+
+    p = sub.add_parser("download", aliases=["dl"], help="按歌曲 ID 下载")
+    add_common(p)
+    p.add_argument("song_id", type=int)
+    p.add_argument("-o", "--output", default=env("OUTPUT_DIR"), help="输出目录；默认读取环境变量 OUTPUT_DIR，未设置则当前目录")
+    p.add_argument("-f", "--file", help="指定完整输出文件路径")
+    p.add_argument("--overwrite", action="store_true", default=env("OVERWRITE", "").lower() in {"1", "true", "yes"}, help="覆盖已存在的同名文件；也可用环境变量 OVERWRITE=true")
+    p.add_argument("--no-md5", dest="check_md5", action="store_false", default=env("CHECK_MD5", "true").lower() not in {"0", "false", "no"}, help="关闭 MD5 校验；也可用环境变量 CHECK_MD5=false")
+    p.set_defaults(func=cmd_download)
+
+    p = sub.add_parser("playlist", aliases=["pl"], help="按网易云歌单 ID 下载并生成 M3U")
+    add_common(p)
+    p.add_argument("playlist_id", type=int)
+    p.add_argument("-o", "--output", default=env("OUTPUT_DIR"), help="歌曲输出目录；默认 <music-root>/netease/<歌单名-id>")
+    p.add_argument("--music-root", default=env("NAVIDROME_MUSIC_ROOT", "/opt/navidrome/music"), help="Navidrome MusicFolder；默认 /opt/navidrome/music")
+    p.add_argument("--m3u", default=env("M3U_FILE"), help="M3U 输出文件；默认 <music-root>/playlists/<歌单名-id>.m3u")
+    p.add_argument("--limit", type=int, help="只处理前 N 首，便于测试")
+    p.add_argument("--overwrite", action="store_true", default=bool_env("OVERWRITE"), help="覆盖已存在的同名文件；也可用环境变量 OVERWRITE=true")
+    p.add_argument("--no-md5", dest="check_md5", action="store_false", default=not bool_env("CHECK_MD5_DISABLED") and env("CHECK_MD5", "true").lower() not in {"0", "false", "no"}, help="关闭 MD5 校验；也可用环境变量 CHECK_MD5=false")
+    p.add_argument("--dry-run", action="store_true", help="只读取歌单和打印计划，不下载、不写 m3u")
+    p.add_argument("--strict", action="store_true", help="遇到第一首失败就停止，并返回非 0")
+    p.add_argument("--navidrome-scan", action="store_true", help="下载后先调用 navidrome scan，让新文件进入媒体库")
+    p.add_argument("--navidrome-full-scan", action="store_true", help="配合 --navidrome-scan 使用，执行 navidrome scan --full")
+    p.add_argument("--navidrome-import", action="store_true", help="下载后调用 navidrome pls import 导入 M3U")
+    p.add_argument("--navidrome-bin", default=env("NAVIDROME_BIN", "navidrome"), help="navidrome 可执行文件路径")
+    p.add_argument("--navidrome-config", default=env("NAVIDROME_CONFIG", "/etc/navidrome/navidrome.toml"), help="Navidrome 配置文件")
+    p.add_argument("--navidrome-user", default=env("NAVIDROME_USER"), help="导入为指定 Navidrome 用户，默认第一个管理员")
+    p.add_argument("--navidrome-sudo", action="store_true", default=bool_env("NAVIDROME_SUDO"), help="导入步骤使用 sudo navidrome；也可用环境变量 NAVIDROME_SUDO=true")
+    p.add_argument("--sync", action="store_true", default=bool_env("NAVIDROME_SYNC"), help="导入时加 navidrome pls import --sync")
+    p.set_defaults(func=cmd_playlist)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return int(args.func(args) or 0)
+    except KeyboardInterrupt:
+        print("\n已中止", file=sys.stderr)
+        return 130
+    except NCMError as exc:
+        print(f"错误: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())