devart-dl 4.0.0__tar.gz → 4.0.2__tar.gz

{devart_dl-4.0.0 → devart_dl-4.0.2}/.env.example

@@ -1,5 +1,5 @@
 # DeviantArt Downloader - 环境变量示例
-# 复制此文件为 .env 并填入你的配置（仅当你通过环境变量传递配置时使用）
+# 本工具不会自动读取 .env；请把需要的值设置到终端或系统环境变量中。
 
 # ============================================
 # 认证配置 Authentication
@@ -34,6 +34,6 @@
 # ============================================
 # ⚠️ 重要：
 # 1. 不要将包含真实凭据的 .env 文件上传到 Git
-# 2. 不要分享你的 client_id / Cookie / OAuth 令牌
+# 2. client_id 不是秘密，但不要分享 Cookie 或 OAuth 令牌
 # 3. Cookie 过期后需重新登录（推荐改用 OAuth，自动续期）
 # 4. 使用代理时注意代理服务器的安全性

devart_dl-4.0.2/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: devart-dl
+Version: 4.0.2
+Summary: 专业的 DeviantArt 作品批量下载工具 - Professional DeviantArt batch downloader with anti-ban features
+Author: DeviantArt Downloader Team
+License-Expression: MIT
+Keywords: deviantart,downloader,scraper,art,gallery,batch-download,async,cli,anti-ban
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.3; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.12.0; extra == "dev"
+Requires-Dist: black>=23.12.0; extra == "dev"
+Requires-Dist: mypy>=1.7.1; extra == "dev"
+Requires-Dist: ruff>=0.1.7; extra == "dev"
+Requires-Dist: pre-commit>=3.6.0; extra == "dev"
+Requires-Dist: ipython>=8.18.0; extra == "dev"
+Dynamic: license-file
+
+# DeviantArt Downloader
+
+一个可靠、聚焦的 DeviantArt 下载 / 归档命令行工具。
+
+[English Documentation](README_EN.md) · [📖 完整文档](https://redtidev1918.github.io/deviantart-downloader/) · [更新日志](CHANGELOG.md)
+
+[![CI](https://github.com/redtidev1918/deviantart-downloader/actions/workflows/ci.yml/badge.svg)](https://github.com/redtidev1918/deviantart-downloader/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/devart-dl.svg)](https://pypi.org/project/devart-dl/)
+[![Python](https://img.shields.io/pypi/pyversions/devart-dl.svg)](https://pypi.org/project/devart-dl/)
+[![Downloads](https://img.shields.io/pypi/dm/devart-dl.svg)](https://pypi.org/project/devart-dl/)
+[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/Docs-文档站点-6366f1?style=flat-square)](https://redtidev1918.github.io/deviantart-downloader/)
+
+## 快速开始
+
+需要 Python 3.10 或更高版本。
+
+```bash
+python -m pip install -U devart-dl
+
+# 单张作品（也支持 fav.me 短链、裸 artwork id）
+devart-dl https://www.deviantart.com/username/art/title-123456
+
+# 画廊 / 作者全集
+devart-dl https://www.deviantart.com/username/gallery
+
+# 收藏夹 / 标签
+devart-dl https://www.deviantart.com/username/favourites
+devart-dl https://www.deviantart.com/tag/landscape
+```
+
+首次下载前建议使用 OAuth 登录：
+
+```bash
+devart-dl login oauth --client-id 你的_PUBLIC_CLIENT_ID
+devart-dl whoami
+```
+
+不会注册 OAuth 应用也可以使用 Cookie。完整图文式步骤见 **[登录与认证教程](https://redtidev1918.github.io/deviantart-downloader/#/LOGIN)**。
+
+> 普通用户无需手动下载 GitHub Release 里的 `.whl`、`.tar.gz` 或 Source code，运行上面的 `pip install` 即可。文件区别和 SHA256 校验方法见[完整文档](https://redtidev1918.github.io/deviantart-downloader/#/?id=github-release-%e9%87%8c%e7%9a%84%e6%96%87%e4%bb%b6%e6%98%af%e4%bb%80%e4%b9%88)。
+
+## 核心特性
+
+- **官方 API（OAuth）优先**：登录一次即可下载原图，无需导出 Cookie，也无需防封延时。
+- **URL 优先**：直接粘贴作品 / 画廊 / 收藏夹 / 标签链接即可下载。
+- **下载可靠**：HTTP Range 断点续传、自动重试、429 退避、原子落盘。
+- **下载档案**：`--archive` 用 SQLite 记住已下载，跨会话自动跳过。
+- **路径模板 + 元数据 sidecar**：`--directory`/`--filename` 模板与 `--write-info-json`。
+- **代理与降级**：支持 `--proxy`；未登录 OAuth 时自动回退 Cookie。
+
+完整的安装、登录认证、下载模式、配置参数、命令速查、Python 调用与常见问题，请看 **📖 文档站点**：
+
+👉 https://redtidev1918.github.io/deviantart-downloader/
+
+## 许可证与免责声明
+
+本项目基于 [MIT License](LICENSE) 开源。
+
+**注意**：本工具仅供个人学习和研究使用。使用者应遵守 DeviantArt 服务条款及版权规定，请勿用于商业用途或大规模抓取导致服务器过载。作者不对任何滥用后果负责。

devart_dl-4.0.2/README.md

@@ -0,0 +1,60 @@
+# DeviantArt Downloader
+
+一个可靠、聚焦的 DeviantArt 下载 / 归档命令行工具。
+
+[English Documentation](README_EN.md) · [📖 完整文档](https://redtidev1918.github.io/deviantart-downloader/) · [更新日志](CHANGELOG.md)
+
+[![CI](https://github.com/redtidev1918/deviantart-downloader/actions/workflows/ci.yml/badge.svg)](https://github.com/redtidev1918/deviantart-downloader/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/devart-dl.svg)](https://pypi.org/project/devart-dl/)
+[![Python](https://img.shields.io/pypi/pyversions/devart-dl.svg)](https://pypi.org/project/devart-dl/)
+[![Downloads](https://img.shields.io/pypi/dm/devart-dl.svg)](https://pypi.org/project/devart-dl/)
+[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/Docs-文档站点-6366f1?style=flat-square)](https://redtidev1918.github.io/deviantart-downloader/)
+
+## 快速开始
+
+需要 Python 3.10 或更高版本。
+
+```bash
+python -m pip install -U devart-dl
+
+# 单张作品（也支持 fav.me 短链、裸 artwork id）
+devart-dl https://www.deviantart.com/username/art/title-123456
+
+# 画廊 / 作者全集
+devart-dl https://www.deviantart.com/username/gallery
+
+# 收藏夹 / 标签
+devart-dl https://www.deviantart.com/username/favourites
+devart-dl https://www.deviantart.com/tag/landscape
+```
+
+首次下载前建议使用 OAuth 登录：
+
+```bash
+devart-dl login oauth --client-id 你的_PUBLIC_CLIENT_ID
+devart-dl whoami
+```
+
+不会注册 OAuth 应用也可以使用 Cookie。完整图文式步骤见 **[登录与认证教程](https://redtidev1918.github.io/deviantart-downloader/#/LOGIN)**。
+
+> 普通用户无需手动下载 GitHub Release 里的 `.whl`、`.tar.gz` 或 Source code，运行上面的 `pip install` 即可。文件区别和 SHA256 校验方法见[完整文档](https://redtidev1918.github.io/deviantart-downloader/#/?id=github-release-%e9%87%8c%e7%9a%84%e6%96%87%e4%bb%b6%e6%98%af%e4%bb%80%e4%b9%88)。
+
+## 核心特性
+
+- **官方 API（OAuth）优先**：登录一次即可下载原图，无需导出 Cookie，也无需防封延时。
+- **URL 优先**：直接粘贴作品 / 画廊 / 收藏夹 / 标签链接即可下载。
+- **下载可靠**：HTTP Range 断点续传、自动重试、429 退避、原子落盘。
+- **下载档案**：`--archive` 用 SQLite 记住已下载，跨会话自动跳过。
+- **路径模板 + 元数据 sidecar**：`--directory`/`--filename` 模板与 `--write-info-json`。
+- **代理与降级**：支持 `--proxy`；未登录 OAuth 时自动回退 Cookie。
+
+完整的安装、登录认证、下载模式、配置参数、命令速查、Python 调用与常见问题，请看 **📖 文档站点**：
+
+👉 https://redtidev1918.github.io/deviantart-downloader/
+
+## 许可证与免责声明
+
+本项目基于 [MIT License](LICENSE) 开源。
+
+**注意**：本工具仅供个人学习和研究使用。使用者应遵守 DeviantArt 服务条款及版权规定，请勿用于商业用途或大规模抓取导致服务器过载。作者不对任何滥用后果负责。

{devart_dl-4.0.0 → devart_dl-4.0.2}/da_downloader/__init__.py

@@ -1,6 +1,6 @@
 """DeviantArt Downloader — a reliable, focused downloader and archival CLI."""
 
-__version__ = "4.0.0"
+__version__ = "4.0.1"
 __author__ = "DeviantArt Downloader Team"
 
 from .download import Downloader, build_downloader, normalize_quality

{devart_dl-4.0.0 → devart_dl-4.0.2}/da_downloader/api.py

@@ -324,14 +324,24 @@ class DeviantArtAPI:
             None,
         )
         
-        if not full_view:
-            logger.warning("Full view not found, using base URI")
+        # 现代 DA 的 baseUri 本身就是原始文件（以图片/视频扩展名结尾）：
+        # 直接 baseUri + token 取原图即可。别拿它拼 fullview 的 /v1/fit|fill
+        # 变体模板——那些 URL 即使带 token 也可能返回 400/404（2026-09 实测）。
+        def _is_file_url(u: str) -> bool:
+            path = str(u).split('?', 1)[0].rstrip('/')
+            return bool(re.search(r'\.(?:png|jpe?g|gif|webp|mp4|m4v)$', path, re.I))
+
+        if _is_file_url(base_uri):
             url = base_uri
-        elif full_view.get('b'):
+        elif full_view and full_view.get('b'):
             url = str(full_view['b'])
-        elif 'c' in full_view:
+        elif full_view and 'c' in full_view:
             url = base_uri + str(full_view['c']).replace('<prettyName>', pretty_name)
+        elif full_view:
+            logger.warning("Full view has no usable URL, falling back to base URI")
+            url = base_uri
         else:
+            logger.warning("Full view not found, using base URI")
             url = base_uri
         
         if token:

{devart_dl-4.0.0 → devart_dl-4.0.2}/da_downloader/cli.py

@@ -50,7 +50,7 @@ Options (URL-first and subcommands):
   --filename TEMPLATE     filename template (default "{id}_{title}.{ext}")
   --quality NAME          original|best|preview (default best)
   --archive PATH          SQLite archive to skip already-downloaded
-  --cookies PATH          cookies file (falls back to saved session)
+  --cookies PATH          cookie file (otherwise env/session/cookies.txt)
   --write-info-json       write a metadata .json next to each file
   --overwrite             replace existing files
   --proxy URL --timeout S --retries N --limit N
@@ -72,7 +72,7 @@ def _version() -> str:
     try:
         return version("devart-dl")
     except PackageNotFoundError:
-        return "4.0.0"
+        return "4.0.1"
 
 
 def _looks_like_target(value: str) -> bool:
@@ -93,7 +93,9 @@ def _load_cookies(cookies_path: Optional[str]) -> str:
             return path.read_text(encoding="utf-8").strip()
         print(f"warning: cookies file not found: {cookies_path}", file=sys.stderr)
         return ""
-    return str(AuthManager().load_cookies() or "")
+    return os.environ.get("DEVIANTART_COOKIES", "").strip() or str(
+        AuthManager().load_cookies() or ""
+    )
 
 
 def _execute(

{devart_dl-4.0.0 → devart_dl-4.0.2}/da_downloader/official_api.py

@@ -222,6 +222,8 @@ def resolve_uuid(
 
         query = {
             "deviationid": identifier,
+            # 该接口自 2026 年起把 type 列为必填枚举（art/journal），缺失返回 400。
+            "type": "art",
             "include_session": "false",
             "csrf_token": csrf,
             "mature_content": True,

devart_dl-4.0.2/devart_dl.egg-info/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: devart-dl
+Version: 4.0.2
+Summary: 专业的 DeviantArt 作品批量下载工具 - Professional DeviantArt batch downloader with anti-ban features
+Author: DeviantArt Downloader Team
+License-Expression: MIT
+Keywords: deviantart,downloader,scraper,art,gallery,batch-download,async,cli,anti-ban
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.3; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.12.0; extra == "dev"
+Requires-Dist: black>=23.12.0; extra == "dev"
+Requires-Dist: mypy>=1.7.1; extra == "dev"
+Requires-Dist: ruff>=0.1.7; extra == "dev"
+Requires-Dist: pre-commit>=3.6.0; extra == "dev"
+Requires-Dist: ipython>=8.18.0; extra == "dev"
+Dynamic: license-file
+
+# DeviantArt Downloader
+
+一个可靠、聚焦的 DeviantArt 下载 / 归档命令行工具。
+
+[English Documentation](README_EN.md) · [📖 完整文档](https://redtidev1918.github.io/deviantart-downloader/) · [更新日志](CHANGELOG.md)
+
+[![CI](https://github.com/redtidev1918/deviantart-downloader/actions/workflows/ci.yml/badge.svg)](https://github.com/redtidev1918/deviantart-downloader/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/devart-dl.svg)](https://pypi.org/project/devart-dl/)
+[![Python](https://img.shields.io/pypi/pyversions/devart-dl.svg)](https://pypi.org/project/devart-dl/)
+[![Downloads](https://img.shields.io/pypi/dm/devart-dl.svg)](https://pypi.org/project/devart-dl/)
+[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/Docs-文档站点-6366f1?style=flat-square)](https://redtidev1918.github.io/deviantart-downloader/)
+
+## 快速开始
+
+需要 Python 3.10 或更高版本。
+
+```bash
+python -m pip install -U devart-dl
+
+# 单张作品（也支持 fav.me 短链、裸 artwork id）
+devart-dl https://www.deviantart.com/username/art/title-123456
+
+# 画廊 / 作者全集
+devart-dl https://www.deviantart.com/username/gallery
+
+# 收藏夹 / 标签
+devart-dl https://www.deviantart.com/username/favourites
+devart-dl https://www.deviantart.com/tag/landscape
+```
+
+首次下载前建议使用 OAuth 登录：
+
+```bash
+devart-dl login oauth --client-id 你的_PUBLIC_CLIENT_ID
+devart-dl whoami
+```
+
+不会注册 OAuth 应用也可以使用 Cookie。完整图文式步骤见 **[登录与认证教程](https://redtidev1918.github.io/deviantart-downloader/#/LOGIN)**。
+
+> 普通用户无需手动下载 GitHub Release 里的 `.whl`、`.tar.gz` 或 Source code，运行上面的 `pip install` 即可。文件区别和 SHA256 校验方法见[完整文档](https://redtidev1918.github.io/deviantart-downloader/#/?id=github-release-%e9%87%8c%e7%9a%84%e6%96%87%e4%bb%b6%e6%98%af%e4%bb%80%e4%b9%88)。
+
+## 核心特性
+
+- **官方 API（OAuth）优先**：登录一次即可下载原图，无需导出 Cookie，也无需防封延时。
+- **URL 优先**：直接粘贴作品 / 画廊 / 收藏夹 / 标签链接即可下载。
+- **下载可靠**：HTTP Range 断点续传、自动重试、429 退避、原子落盘。
+- **下载档案**：`--archive` 用 SQLite 记住已下载，跨会话自动跳过。
+- **路径模板 + 元数据 sidecar**：`--directory`/`--filename` 模板与 `--write-info-json`。
+- **代理与降级**：支持 `--proxy`；未登录 OAuth 时自动回退 Cookie。
+
+完整的安装、登录认证、下载模式、配置参数、命令速查、Python 调用与常见问题，请看 **📖 文档站点**：
+
+👉 https://redtidev1918.github.io/deviantart-downloader/
+
+## 许可证与免责声明
+
+本项目基于 [MIT License](LICENSE) 开源。
+
+**注意**：本工具仅供个人学习和研究使用。使用者应遵守 DeviantArt 服务条款及版权规定，请勿用于商业用途或大规模抓取导致服务器过载。作者不对任何滥用后果负责。

{devart_dl-4.0.0 → devart_dl-4.0.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "devart-dl"
-version = "4.0.0"
+version = "4.0.2"
 description = "专业的 DeviantArt 作品批量下载工具 - Professional DeviantArt batch downloader with anti-ban features"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -145,7 +145,6 @@ target-version = "py310"
 
 [tool.ruff.lint]
 # Enforced policy: high-signal checks only (real bugs), matching CI.
-# Style rules can be added per-directory once the legacy debt is paid.
 select = [
     "E9",  # runtime errors (syntax error, undefined name, unused bind)
     "F",   # pyflakes

{devart_dl-4.0.0 → devart_dl-4.0.2}/tests/test_cli.py

@@ -65,6 +65,11 @@ def test_oauth_login_requires_client_id(monkeypatch, capsys) -> None:
     assert "client-id" in capsys.readouterr().err
 
 
+def test_load_cookies_from_environment(monkeypatch) -> None:
+    monkeypatch.setenv("DEVIANTART_COOKIES", " auth=token; auth_secure=secret ")
+    assert cli._load_cookies(None) == "auth=token; auth_secure=secret"
+
+
 def test_oauth_whoami_without_session(monkeypatch, capsys) -> None:
     monkeypatch.setattr(cli.OAuthSession, "from_store", classmethod(lambda cls: None))
     assert cli._oauth_whoami([]) == 1

devart_dl-4.0.0/PKG-INFO

@@ -1,289 +0,0 @@
-Metadata-Version: 2.4
-Name: devart-dl
-Version: 4.0.0
-Summary: 专业的 DeviantArt 作品批量下载工具 - Professional DeviantArt batch downloader with anti-ban features
-Author: DeviantArt Downloader Team
-License-Expression: MIT
-Keywords: deviantart,downloader,scraper,art,gallery,batch-download,async,cli,anti-ban
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: End Users/Desktop
-Classifier: Topic :: Internet :: WWW/HTTP
-Classifier: Topic :: Multimedia :: Graphics
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Operating System :: OS Independent
-Classifier: Environment :: Console
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: requests>=2.31.0
-Provides-Extra: dev
-Requires-Dist: pytest>=7.4.3; extra == "dev"
-Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
-Requires-Dist: pytest-mock>=3.12.0; extra == "dev"
-Requires-Dist: black>=23.12.0; extra == "dev"
-Requires-Dist: mypy>=1.7.1; extra == "dev"
-Requires-Dist: ruff>=0.1.7; extra == "dev"
-Requires-Dist: pre-commit>=3.6.0; extra == "dev"
-Requires-Dist: ipython>=8.18.0; extra == "dev"
-Dynamic: license-file
-
-# DeviantArt Downloader
-
-一个可靠、聚焦的 DeviantArt 下载 / 归档命令行工具。
-
-[English Documentation](README_EN.md)
-
-[![CI](https://github.com/redtidev1918/deviantart-downloader/actions/workflows/ci.yml/badge.svg)](https://github.com/redtidev1918/deviantart-downloader/actions/workflows/ci.yml)
-[![PyPI](https://img.shields.io/pypi/v/devart-dl.svg)](https://pypi.org/project/devart-dl/)
-[![Python](https://img.shields.io/pypi/pyversions/devart-dl.svg)](https://pypi.org/project/devart-dl/)
-[![Downloads](https://img.shields.io/pypi/dm/devart-dl.svg)](https://pypi.org/project/devart-dl/)
-[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
-
-更新日志见 [CHANGELOG.md](CHANGELOG.md)。
-
----
-
-## 核心特性
-
-- **官方 API（OAuth）优先**：登录一次即可下载原图，无需导出 Cookie，也无需防封延时。
-- **URL 优先**：`devart-dl URL` 直接下载作品 / 画廊 / 收藏夹 / 标签 / fav.me 短链。
-- **下载可靠**：HTTP Range 断点续传、自动重试、429 退避、HTML/空文件校验、原子落盘。
-- **下载档案**：`--archive` 用 SQLite 记住已下载内容，跨会话自动跳过。
-- **路径模板**：`--directory` / `--filename` 支持 `{id}` `{title}` `{author}` `{published}` `{ext}` 等字段，并做路径安全清洗。
-- **元数据**：`--write-info-json` 在每个作品旁写一份 `.json` 元数据。
-- **代理与降级**：支持 `--proxy` 与代理环境变量；未登录 OAuth 时自动回退 Cookie。
-
----
-
-## 快速开始
-
-### 安装
-
-需要 Python 3.10 或更高版本。
-
-```bash
-pip install devart-dl
-```
-
-### 基本用法（URL 优先）
-
-```bash
-# 单张作品（也支持 fav.me 短链、裸 artwork id）
-devart-dl https://www.deviantart.com/username/art/title-123456
-
-# 画廊 / 作者全集
-devart-dl https://www.deviantart.com/username/gallery
-
-# 收藏夹
-devart-dl https://www.deviantart.com/username/favourites
-
-# 标签
-devart-dl https://www.deviantart.com/tag/landscape
-```
-
-### 登录（推荐 OAuth）
-
-```bash
-devart-dl login oauth --client-id 你的_PUBLIC_CLIENT_ID
-devart-dl whoami     # 验证登录状态
-devart-dl logout     # 撤销令牌
-```
-
-在 [deviantart.com/developers](https://www.deviantart.com/developers/) 注册一个 **Public** OAuth 应用，把 `http://127.0.0.1:8765/callback` 加入白名单。登录在浏览器中完成，无需把密码或 `client_secret` 交给 CLI。完整步骤见 [docs/LOGIN.md](docs/LOGIN.md)。
-
----
-
-## 主要功能
-
-### 下载模式
-
-URL 优先是最简单的方式；也保留显式子命令：
-
-```bash
-# URL 优先
-devart-dl https://www.deviantart.com/username/art/title-123456
-devart-dl https://www.deviantart.com/username/gallery
-devart-dl https://www.deviantart.com/username/gallery/12345   # 指定文件夹
-devart-dl https://www.deviantart.com/username/favourites
-devart-dl https://www.deviantart.com/tag/landscape
-
-# 显式子命令
-devart-dl url https://www.deviantart.com/username/art/title-123456
-devart-dl artist username
-devart-dl gallery username [gallery_id]
-devart-dl search all "digital art"
-devart-dl fav username folder_id
-```
-
-> 说明：显式子命令沿用旧用法、保持兼容；官方 API 暂不提供搜索端点，`search` 走 Cookie 回退路径。
-
-### 登录认证
-
-**官方 API（OAuth）优先**，Cookie 作为降级方案。
-
-1. **OAuth 登录（推荐）**
-
-   ```bash
-   devart-dl login oauth --client-id 你的_PUBLIC_CLIENT_ID
-   ```
-
-   - 注册 **Public** OAuth 应用，白名单精确加入 `http://127.0.0.1:8765/callback`。
-   - 登录会在浏览器中完成，令牌保存到 `~/.deviantart_dl/oauth.json`（0600），自动续期。
-   - 登录后下载命令自动走官方 API，原图来自官方下载接口。
-
-2. **Cookie 登录（降级方案）**
-
-   ```bash
-   devart-dl login interactive   # 交互式输入 Cookie
-   ```
-
-   或创建 `cookies.txt`、设置 `DEVIANTART_COOKIES` 环境变量。会话保存于 `~/.deviantart_dl/session.json`。
-
-### 下载档案与断点续传
-
-```bash
-# 用 SQLite 记住已下载内容，下次运行自动跳过（跨会话、跨目录都有效）
-devart-dl https://www.deviantart.com/username/gallery --archive ~/.devart-dl/archive.sqlite
-
-# 中断的下载从 .part 文件续传，无需重新下载整个文件
-```
-
-### 文件名 / 目录模板
-
-```bash
-devart-dl URL \
-  --directory "{author}/{published:%Y-%m}" \
-  --filename "{id}_{title}.{ext}"
-```
-
-可用字段：`{id}` `{title}` `{author}` `{username}` `{published}` `{filename}` `{ext}` `{index}`。路径会自动清洗（去除非法字符、Windows 保留名、`..` 穿越、超长名），确保结果在下载目录之内。
-
-### 元数据 sidecar
-
-```bash
-devart-dl URL --write-info-json
-# 生成 artwork.jpg 与 artwork.json（标题、作者、URL、发布时间、mature、媒体地址等）
-```
-
----
-
-## 配置参数
-
-### 常用选项
-
-| 选项 | 说明 | 默认值 |
-|------|------|--------|
-| `-d, --dest` | 下载根目录 | `./Downloads` |
-| `--directory` | 目录模板（如 `{author}/{published:%Y}`） | `{author}` |
-| `--filename` | 文件名模板（如 `{id}_{title}.{ext}`） | `{id}_{title}.{ext}` |
-| `--quality` | `original`（原图，需登录）/ `best`（默认）/ `preview`；旧 `o/f/p` 仍可用 | `best` |
-| `--archive` | SQLite 下载档案路径 | 无 |
-| `--write-info-json` | 写元数据 sidecar | 关 |
-| `--overwrite` | 覆盖已存在文件 | 关（跳过） |
-| `--cookies` | Cookie 文件路径 | 自动加载会话 |
-| `--proxy` | 代理地址 | 自动读环境变量 |
-| `--timeout` | 请求超时（秒） | `60` |
-| `--retries` | 最大重试次数 | `3` |
-| `--limit` | 每页数量 | `24` |
-
-### 输出选项
-
-- `-v, --verbose`：显示详细运行信息（含跳过原因）。
-- `-q, --quiet`：静默模式，仅显示汇总与错误。
-
----
-
-## 常用命令速查
-
-```bash
-# URL 优先（推荐）
-devart-dl <URL>
-
-# 显式子命令
-devart-dl url <artwork_url>
-devart-dl artist <username>
-devart-dl gallery <username> [gallery_id]
-devart-dl search <username|all> <query>
-devart-dl fav <username> <folder_id>
-
-# 登录 / 会话
-devart-dl login oauth --client-id <ID>   # OAuth 登录（推荐）
-devart-dl login interactive             # Cookie 登录（降级）
-devart-dl whoami                        # 查看登录状态
-devart-dl logout                        # 撤销令牌并清除本地会话
-
-# 其他
-devart-dl version
-```
-
----
-
-## 高级用法
-
-### 代理设置
-
-```bash
-# 命令行参数
-devart-dl URL --proxy http://127.0.0.1:7890
-
-# 环境变量（HTTP/HTTPS 代理）
-export HTTP_PROXY=http://127.0.0.1:7890
-export HTTPS_PROXY=http://127.0.0.1:7890
-export ALL_PROXY=http://127.0.0.1:7890
-```
-
-### Python 脚本调用
-
-```python
-from pathlib import Path
-from da_downloader import Downloader
-from da_downloader.download import build_downloader
-
-downloader = build_downloader(
-    destination=Path('downloads'),
-    archive=Path('archive.sqlite'),   # 可选：已下载自动跳过
-    quality='best',                   # original / best / preview
-    write_info_json=True,             # 每个作品旁写一份 metadata .json
-)
-
-results = downloader.download('https://www.deviantart.com/username/gallery')
-for r in results:
-    print(r.status, r.path)
-```
-
-已通过 `devart-dl login oauth` 登录时自动走官方 API，否则回退到 Cookie。
-
----
-
-## 常见问题
-
-**Q: 下载不完整 / 只下了一部分 / 像是跳着下？**
-A: 请升级到 **v3.4.0+**。旧版本只下载 Featured（精选）文件夹；v3.3.1 起遍历全部画廊文件夹，v3.4.0 起解析失败与网络失败会明确报错，且中断可 Range 续传。
-
-**Q: pip 安装后运行 `devart-dl` 报 ModuleNotFoundError？**
-A: 请升级到 **v3.4.0+**（`pip install -U devart-dl`），安装入口已修复。
-
-**Q: 出现 403 Forbidden？**
-A: 通常是未登录或 Cookie 过期。优先 `devart-dl login oauth`（官方 API）；或 `devart-dl login interactive` 更新 Cookie。
-
-**Q: 出现 429 Too Many Requests？**
-A: 使用官方 API（OAuth 登录）通常不会触发；Cookie 路径下会自动退避重试，若仍频繁 429，请暂停一段时间再试。
-
-**Q: 下载速度慢？**
-A: 建议配置代理（`--proxy`），或降低画质（`--quality preview`）。
-
-**Q: 如何导出 Cookie？**
-A: 推荐 Chrome/Edge 开发者工具 (F12) → Application → Cookies，复制 `auth` 和 `auth_secure` 字段；或 `devart-dl login interactive` 按提示粘贴。
-
----
-
-## 许可证与免责声明
-
-本项目基于 [MIT License](LICENSE) 开源。
-
-**注意**：本工具仅供个人学习和研究使用。使用者应遵守 DeviantArt 服务条款及版权规定，请勿用于商业用途或大规模抓取导致服务器过载。作者不对任何滥用后果负责。