ChatHFD 0.1.3__tar.gz → 0.1.4__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. chathfd-0.1.4/AGENTS.md +8 -0
  2. chathfd-0.1.4/CHANGELOG.md +52 -0
  3. chathfd-0.1.4/DEVELOP.md +26 -0
  4. chathfd-0.1.4/MANIFEST.in +4 -0
  5. {chathfd-0.1.3/src/ChatHFD.egg-info → chathfd-0.1.4}/PKG-INFO +14 -3
  6. chathfd-0.1.4/README.en.md +58 -0
  7. {chathfd-0.1.3 → chathfd-0.1.4}/README.md +13 -2
  8. chathfd-0.1.4/docs/capability-map.en.md +49 -0
  9. chathfd-0.1.4/docs/capability-map.md +49 -0
  10. chathfd-0.1.4/docs/cli-tree.en.md +88 -0
  11. chathfd-0.1.4/docs/cli-tree.md +88 -0
  12. chathfd-0.1.4/docs/configuration.en.md +88 -0
  13. chathfd-0.1.4/docs/configuration.md +90 -0
  14. chathfd-0.1.4/docs/index.en.md +79 -0
  15. chathfd-0.1.4/docs/index.md +79 -0
  16. chathfd-0.1.4/docs/interface-tree.en.md +38 -0
  17. chathfd-0.1.4/docs/interface-tree.md +38 -0
  18. chathfd-0.1.4/docs/python-api.en.md +94 -0
  19. chathfd-0.1.4/docs/python-api.md +94 -0
  20. chathfd-0.1.4/docs/quickstart.en.md +116 -0
  21. chathfd-0.1.4/docs/quickstart.md +116 -0
  22. chathfd-0.1.4/docs/troubleshooting.en.md +34 -0
  23. chathfd-0.1.4/docs/troubleshooting.md +34 -0
  24. chathfd-0.1.4/mkdocs.yml +78 -0
  25. chathfd-0.1.4/scripts/preserve_docs_preview.py +46 -0
  26. {chathfd-0.1.3 → chathfd-0.1.4/src/ChatHFD.egg-info}/PKG-INFO +14 -3
  27. chathfd-0.1.4/src/ChatHFD.egg-info/SOURCES.txt +47 -0
  28. {chathfd-0.1.3 → chathfd-0.1.4}/src/chathfd/__init__.py +1 -1
  29. chathfd-0.1.4/tests/cli-tests/README.md +3 -0
  30. chathfd-0.1.4/tests/cli-tests/test_download.py +227 -0
  31. chathfd-0.1.4/tests/cli-tests/test_setup.py +71 -0
  32. chathfd-0.1.4/tests/code-tests/README.md +3 -0
  33. chathfd-0.1.4/tests/conftest.py +8 -0
  34. chathfd-0.1.4/tests/mock-cli-tests/README.md +3 -0
  35. chathfd-0.1.4/tests/test_docs.py +142 -0
  36. {chathfd-0.1.3 → chathfd-0.1.4}/tests/test_version.py +1 -1
  37. chathfd-0.1.3/src/ChatHFD.egg-info/SOURCES.txt +0 -17
  38. {chathfd-0.1.3 → chathfd-0.1.4}/LICENSE +0 -0
  39. {chathfd-0.1.3 → chathfd-0.1.4}/pyproject.toml +0 -0
  40. {chathfd-0.1.3 → chathfd-0.1.4}/setup.cfg +0 -0
  41. {chathfd-0.1.3 → chathfd-0.1.4}/src/ChatHFD.egg-info/dependency_links.txt +0 -0
  42. {chathfd-0.1.3 → chathfd-0.1.4}/src/ChatHFD.egg-info/entry_points.txt +0 -0
  43. {chathfd-0.1.3 → chathfd-0.1.4}/src/ChatHFD.egg-info/requires.txt +0 -0
  44. {chathfd-0.1.3 → chathfd-0.1.4}/src/ChatHFD.egg-info/top_level.txt +0 -0
  45. {chathfd-0.1.3 → chathfd-0.1.4}/src/chathfd/cli.py +0 -0
  46. {chathfd-0.1.3 → chathfd-0.1.4}/src/chathfd/config.py +0 -0
  47. {chathfd-0.1.3 → chathfd-0.1.4}/src/chathfd/download.py +0 -0
  48. {chathfd-0.1.3 → chathfd-0.1.4}/src/chathfd/setup.py +0 -0
  49. {chathfd-0.1.3 → chathfd-0.1.4}/tests/test_cli.py +0 -0
  50. {chathfd-0.1.3 → chathfd-0.1.4}/tests/test_workflow_contract.py +0 -0
@@ -0,0 +1,8 @@
1
+ # Agent Notes
2
+
3
+ ## Development Expectations
4
+
5
+ - Keep changes minimal and reviewable.
6
+ - Prefer doc-first CLI tests.
7
+ - Sync docs and changelog with user-facing behavior.
8
+ - Use interactive prompts only when arguments are missing and recoverable.
@@ -0,0 +1,52 @@
1
+ # Changelog
2
+
3
+ ## 2026-11-09 - 0.1.4
4
+
5
+ ### 文档
6
+
7
+ - 补齐中英文多栏导航首页、快速开始、完整 CLI 参数参考、配置与续传、能力地图、接口树、Python 示例和故障排查。
8
+ - 增加文档与真实 CLI/API 的一致性测试,明确模型配置小样例、公开仓库及验证边界。
9
+ - 文档预览与正式部署共享发布锁,正式部署保留已有 dev 预览;预览语言入口保持在预览路径内。
10
+
11
+ 下载命令行为保持不变。
12
+
13
+ ## 2026-11-08 - 0.1.3
14
+
15
+ ### Added
16
+
17
+ - Added `chathfd download` for public Hugging Face models and datasets with HF-Mirror default, selection preflight, aria2 concurrency/resume, dry-run, and an explicit 10 GiB size gate.
18
+ - Added `chathfd setup` to detect aria2c, suggest installation commands, and offer a confirmed `--install` path.
19
+
20
+ ### Changed
21
+
22
+ - Updated both CLI tree modes, bilingual docs and tests to reflect the real command surface. ModelScope is documented as a separate repository rather than an interchangeable mirror.
23
+
24
+ ## 2026-08-21 - 0.1.2
25
+
26
+ ### Changed
27
+
28
+ - Migrated `--tree` and the new `--tree-brief` flag to ChatStyle's shared Click tree runtime with canonical root name `chathfd`.
29
+ - Kept command parameter signatures in the default tree and omitted them in the brief tree while retaining command nodes and descriptions.
30
+ - Updated runtime bounds to `chatstyle>=0.2.0,<0.3.0` and `chatenv>=0.2.10,<0.3.0`.
31
+ - Added detailed and brief tree smoke coverage to package tests and CI.
32
+
33
+ ## 2026-08-12 - 0.1.1
34
+
35
+ ### Added
36
+
37
+ - Added real root-only `chathfd --tree` generated from the Click command surface.
38
+ - Added CLI contract tests for `--help`, `--version`, and `--tree`.
39
+
40
+ ### Changed
41
+
42
+ - Aligned documentation URLs to `https://arch.gh.wzhecnu.cn/ChatHFD/`.
43
+ - Enabled bilingual MkDocs navigation and Material icon rendering.
44
+ - Hardened Preview Docs and tag-only OIDC publish workflows.
45
+
46
+ ## 2026-07-01 - 0.1.0
47
+
48
+ ### Added
49
+
50
+ - Initial ChatHFD package scaffold with `chathfd` CLI.
51
+ - ChatEnv provider entry point for `chathfd` configuration discovery.
52
+ - CI and tag-driven Trusted Publisher workflow scaffold.
@@ -0,0 +1,26 @@
1
+ # Development Guide
2
+
3
+ ## CLI Rules
4
+
5
+ - Use `chatstyle>=0.2.0,<0.3.0` and `chatenv>=0.2.10,<0.3.0` as the canonical CLI interaction runtime.
6
+ - Attach `chatstyle.add_tree_option` to the top-level Click group with the canonical `chathfd` root name.
7
+ - Keep `--tree` as the detailed tree with command parameter signatures and `--tree-brief` as the signature-free view.
8
+ - Prefer `CommandSchema`, `CommandField`, `add_interactive_option()`, and `resolve_command_inputs()` for new commands.
9
+ - Missing required args should auto-enter interactive mode when recoverable.
10
+ - `-i` forces interactive mode; `-I` disables prompting and must fail fast.
11
+ - Prompt defaults must match actual execution defaults.
12
+ - Sensitive values must stay masked in prompts and summaries.
13
+ - Prefer lazy imports in CLI wiring and keep implementation imports local when possible.
14
+
15
+ ## Docs and Tests
16
+
17
+ - Use doc-first CLI testing.
18
+ - Put real CLI coverage under `tests/cli-tests/`.
19
+ - Put mock/fake CLI coverage under `tests/mock-cli-tests/`.
20
+ - Keep `README.md`, `docs/`, and `CHANGELOG.md` in sync with user-facing changes.
21
+
22
+ ## Automation
23
+
24
+ - Keep automation small and reviewable.
25
+ - Prefer commands that can run in CI without interactive prompts.
26
+ - Ensure generated defaults are safe for local development.
@@ -0,0 +1,4 @@
1
+ include README.md README.en.md CHANGELOG.md DEVELOP.md AGENTS.md mkdocs.yml
2
+ recursive-include docs *.md
3
+ include scripts/preserve_docs_preview.py
4
+ recursive-include tests *.py *.md
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: ChatHFD
3
- Version: 0.1.3
3
+ Version: 0.1.4
4
4
  Summary: ChatHFD: ChatArch Hugging Face Download tooling package
5
5
  Author-email: ChatArch <1073853456@qq.com>
6
6
  License-Expression: MIT
@@ -38,14 +38,25 @@ Dynamic: license-file
38
38
 
39
39
  ChatHFD 是 ChatArch 的 Hugging Face 模型与数据集下载工具。要求 Python 3.10+ 和 `aria2c`;只支持公开仓库,不在命令行传递 Token。
40
40
 
41
+ ## 文档导航
42
+
43
+ | 你要做什么 | 文档入口 |
44
+ | --- | --- |
45
+ | 第一次安装与下载 | [快速开始](https://arch.gh.wzhecnu.cn/ChatHFD/quickstart/) |
46
+ | 查看全部命令、参数与默认值 | [完整 CLI 树](https://arch.gh.wzhecnu.cn/ChatHFD/cli-tree/) |
47
+ | 配置镜像、目录和续传 | [下载配置](https://arch.gh.wzhecnu.cn/ChatHFD/configuration/) |
48
+ | 从 Python 调用 | [Python 接口](https://arch.gh.wzhecnu.cn/ChatHFD/python-api/)与[接口树](https://arch.gh.wzhecnu.cn/ChatHFD/interface-tree/) |
49
+ | 查看当前支持范围 | [能力地图](https://arch.gh.wzhecnu.cn/ChatHFD/capability-map/) |
50
+ | 解决失败或对照旧参数 | [故障排查](https://arch.gh.wzhecnu.cn/ChatHFD/troubleshooting/) |
51
+
41
52
  ## 下载示例
42
53
 
43
54
  ```bash
44
- pip install ChatHFD==0.1.3
55
+ pip install ChatHFD==0.1.4
45
56
  chathfd --tree
46
57
  chathfd setup # 检查 aria2c;未安装时提示命令
47
58
  # 如确需安装:chathfd setup --install(还需确认)
48
- # 先预检最新 Qwen 通用开放权重系列(此仓库约 360 GB,不要直接全量下载)
59
+ # 先预检 Qwen 模型中的小文件,不直接全量下载权重
49
60
  chathfd download Qwen/Qwen3.8-Flash-Next --include config.json --dry-run
50
61
  chathfd download Qwen/Qwen3.8-Flash-Next --include config.json --local-dir ./models/qwen-sample
51
62
  # 数学数据集:约 246 KB,包含 README、元数据和一个 Parquet 分片
@@ -0,0 +1,58 @@
1
+ <div align="center">
2
+ <a href="https://pypi.python.org/pypi/ChatHFD"><img src="https://img.shields.io/pypi/v/ChatHFD.svg" alt="PyPI version" /></a>
3
+ <a href="https://github.com/ChatArch/ChatHFD/actions/workflows/ci.yml"><img src="https://github.com/ChatArch/ChatHFD/actions/workflows/ci.yml/badge.svg" alt="Tests" /></a>
4
+ </div>
5
+
6
+ <div align="center">[English](README.en.md) | [简体中文](README.md)</div>
7
+
8
+ # ChatHFD
9
+
10
+ ChatHFD is ChatArch's tool for downloading Hugging Face models and datasets. Requires Python 3.10+ and `aria2c`. Public repositories only; no CLI token handling.
11
+
12
+ ## Documentation
13
+
14
+ | Task | Guide |
15
+ | --- | --- |
16
+ | First installation and download | [Quickstart](https://arch.gh.wzhecnu.cn/ChatHFD/en/quickstart/) |
17
+ | Every command, option and default | [Complete CLI Tree](https://arch.gh.wzhecnu.cn/ChatHFD/en/cli-tree/) |
18
+ | Endpoint, destination and resume | [Configuration](https://arch.gh.wzhecnu.cn/ChatHFD/en/configuration/) |
19
+ | Python integration | [Python API](https://arch.gh.wzhecnu.cn/ChatHFD/en/python-api/) and [Interface Tree](https://arch.gh.wzhecnu.cn/ChatHFD/en/interface-tree/) |
20
+ | Implemented scope | [Capability Map](https://arch.gh.wzhecnu.cn/ChatHFD/en/capability-map/) |
21
+ | Failures and legacy flags | [Troubleshooting](https://arch.gh.wzhecnu.cn/ChatHFD/en/troubleshooting/) |
22
+
23
+ ## Examples
24
+
25
+ ```bash
26
+ pip install ChatHFD==0.1.4
27
+ chathfd --tree
28
+ chathfd setup # Check aria2c; if missing, show installation guidance
29
+ # To install explicitly: chathfd setup --install (requires confirmation)
30
+ # Inspect a small file in a recent open Qwen model (the full repo is ~360 GB)
31
+ chathfd download Qwen/Qwen3.8-Flash-Next --include config.json --dry-run
32
+ chathfd download Qwen/Qwen3.8-Flash-Next --include config.json --local-dir ./models/qwen-sample
33
+ # Recent math dataset (~246 KB including its single Parquet shard)
34
+ chathfd download MathArena/arxivmath-0926 --repo-type dataset --dry-run
35
+ chathfd download MathArena/arxivmath-0926 --repo-type dataset --local-dir ./datasets/arxivmath-0926
36
+ ```
37
+
38
+ The default endpoint is `https://hf-mirror.com`. Override with `HF_ENDPOINT` or `--endpoint` for another Hugging Face-compatible HTTPS origin, such as `https://huggingface.co`. Repeat `--include` / `--exclude` to select repository paths, pin `--revision`, set `--jobs` (5 concurrent files by default) and `--connections` (4 connections per file by default). aria2 provides resume support. Completion checks file sizes, not cryptographic hashes. A pre-existing wrong-size file without aria2 state is rejected, not deleted.
39
+
40
+ Selections over 10 GiB require an explicit `--allow-large` after reviewing `--dry-run` and free space. Download URLs are pinned to the metadata response's commit SHA; the destination records the repository, commit, and selected file set. Rerunning the same set can resume, but a moved branch, changed selected set or unknown pre-existing files require a fresh destination. The 10 GiB gate is metadata preflight, not a hard limit on bytes sent by a server. Dry-run previews even oversized selections without creating destination files. The default destination is `./models/<org>/<repo>` or `./datasets/<org>/<repo>`.
41
+
42
+ ModelScope is a separate repository/SDK, not a drop-in replacement for `HF_ENDPOINT`. If the content is independently published there, use its CLI, e.g. `modelscope download --model Qwen/Qwen2.5-0.5B-Instruct --local_dir ./model`. Do not assume the same HF repo ID exists on ModelScope; this command does not silently fall back to it.
43
+
44
+ References: [HF-Mirror](https://hf-mirror.com/) · [ModelScope CLI](https://www.modelscope.cn/docs/sdk/cli) · [Qwen model](https://huggingface.co/Qwen/Qwen3.8-Flash-Next) · [MathArena dataset](https://huggingface.co/datasets/MathArena/arxivmath-0926).
45
+
46
+ ## Current CLI tree (`--tree`)
47
+
48
+ ```text
49
+ chathfd
50
+ ├── --help # Show this message and exit.
51
+ ├── --version # Show the version and exit.
52
+ ├── --tree # Print the registered CLI tree and exit.
53
+ ├── --tree-brief # Print the registered CLI tree without parameter signatures and exit.
54
+ ├── download <REPO-ID> [--repo-type REPO-TYPE] [--revision REVISION] [--endpoint ENDPOINT] [--local-dir LOCAL-DIR] [--include INCLUDE] [--exclude EXCLUDE] [--connections CONNECTIONS] [--jobs JOBS] [--dry-run] [--allow-large] # Download a public model or dataset with aria2c.
55
+ └── setup [--install] # Check the aria2c download engine and offer installation.
56
+ ```
57
+
58
+ `--tree-brief` omits parameter signatures. See `DEVELOP.md` and `AGENTS.md` before extending the package; `src/` contains source, `tests/cli-tests/` the real CLI tests, and `docs/` long-lived documentation.
@@ -9,14 +9,25 @@
9
9
 
10
10
  ChatHFD 是 ChatArch 的 Hugging Face 模型与数据集下载工具。要求 Python 3.10+ 和 `aria2c`;只支持公开仓库,不在命令行传递 Token。
11
11
 
12
+ ## 文档导航
13
+
14
+ | 你要做什么 | 文档入口 |
15
+ | --- | --- |
16
+ | 第一次安装与下载 | [快速开始](https://arch.gh.wzhecnu.cn/ChatHFD/quickstart/) |
17
+ | 查看全部命令、参数与默认值 | [完整 CLI 树](https://arch.gh.wzhecnu.cn/ChatHFD/cli-tree/) |
18
+ | 配置镜像、目录和续传 | [下载配置](https://arch.gh.wzhecnu.cn/ChatHFD/configuration/) |
19
+ | 从 Python 调用 | [Python 接口](https://arch.gh.wzhecnu.cn/ChatHFD/python-api/)与[接口树](https://arch.gh.wzhecnu.cn/ChatHFD/interface-tree/) |
20
+ | 查看当前支持范围 | [能力地图](https://arch.gh.wzhecnu.cn/ChatHFD/capability-map/) |
21
+ | 解决失败或对照旧参数 | [故障排查](https://arch.gh.wzhecnu.cn/ChatHFD/troubleshooting/) |
22
+
12
23
  ## 下载示例
13
24
 
14
25
  ```bash
15
- pip install ChatHFD==0.1.3
26
+ pip install ChatHFD==0.1.4
16
27
  chathfd --tree
17
28
  chathfd setup # 检查 aria2c;未安装时提示命令
18
29
  # 如确需安装:chathfd setup --install(还需确认)
19
- # 先预检最新 Qwen 通用开放权重系列(此仓库约 360 GB,不要直接全量下载)
30
+ # 先预检 Qwen 模型中的小文件,不直接全量下载权重
20
31
  chathfd download Qwen/Qwen3.8-Flash-Next --include config.json --dry-run
21
32
  chathfd download Qwen/Qwen3.8-Flash-Next --include config.json --local-dir ./models/qwen-sample
22
33
  # 数学数据集:约 246 KB,包含 README、元数据和一个 Parquet 分片
@@ -0,0 +1,49 @@
1
+ # Capability Map
2
+
3
+ <div class="grid cards" markdown>
4
+
5
+ - :material-download-outline: **Repository files**
6
+
7
+ ---
8
+
9
+ Public models and datasets, selection, revision and output.
10
+
11
+ [Run examples](quickstart.md)
12
+
13
+ - :material-shield-check-outline: **Preflight and resume**
14
+
15
+ ---
16
+
17
+ Explicit selection, commit pinning and destination identity; size-based completion checks.
18
+
19
+ [Read constraints](configuration.md#resume)
20
+
21
+ - :material-code-braces: **Reusable interfaces**
22
+
23
+ ---
24
+
25
+ CLI adapters call importable Python functions; aria2 transfers files.
26
+
27
+ [Interface mapping](interface-tree.md)
28
+
29
+ </div>
30
+
31
+ ## Implemented
32
+
33
+ | Capability | Interface | Boundary |
34
+ | --- | --- | --- |
35
+ | Models and datasets | `download`, `--repo-type` | Public repository files, not training or inference |
36
+ | Compatible mirrors | `--endpoint`, `HF_ENDPOINT` | HF-Mirror by default; no cross-platform fallback |
37
+ | Concurrency and resume | `--connections`, `--jobs` | Local aria2 and matching destination identity |
38
+ | Selection and size preview | `--include`, `--exclude`, `--dry-run` | Metadata preflight, not a hard byte quota |
39
+ | Engine preparation | `setup [--install]` | Explicit, confirmed system package installation |
40
+ | Python calls | `download_repo`, `fetch_metadata`, `setup_aria2` | Still use Click output/errors; see API reference |
41
+
42
+ ## Outside the current boundary
43
+
44
+ - Login, token management or forwarding for private/gated Hub repositories.
45
+ - Native ModelScope downloads, wget backend or automatic replacement of old `hfd` aliases.
46
+ - Global cache management, remote filesystem mounts, job queues or background daemons.
47
+ - Upstream cryptographic verification, inference validation or dataset training pipelines.
48
+
49
+ A successful config or README download is not a completed weight download. [Quickstart](quickstart.md#model) distinguishes small examples from full repositories.
@@ -0,0 +1,49 @@
1
+ # 能力地图
2
+
3
+ <div class="grid cards" markdown>
4
+
5
+ - :material-download-outline: **仓库文件下载**
6
+
7
+ ---
8
+
9
+ 公开模型、数据集、文件筛选、版本与目录。
10
+
11
+ [运行示例](quickstart.md)
12
+
13
+ - :material-shield-check-outline: **预检与续传**
14
+
15
+ ---
16
+
17
+ 明确选择、commit 固定与目录身份;完成按大小检查。
18
+
19
+ [阅读约束](configuration.md#resume)
20
+
21
+ - :material-code-braces: **可复用接口**
22
+
23
+ ---
24
+
25
+ CLI 调用 importable Python 函数,aria2 执行传输。
26
+
27
+ [接口映射](interface-tree.md)
28
+
29
+ </div>
30
+
31
+ ## 已实现
32
+
33
+ | 能力 | 接口 | 边界 |
34
+ | --- | --- | --- |
35
+ | 模型与数据集 | `download`、`--repo-type` | 仅公开仓库文件,不启动训练或推理 |
36
+ | 兼容镜像 | `--endpoint`、`HF_ENDPOINT` | 默认 HF-Mirror,无自动跨平台回退 |
37
+ | 并发与续传 | `--connections`、`--jobs` | 需本机 aria2,目录身份须匹配 |
38
+ | 文件和体量预检 | `--include`、`--exclude`、`--dry-run` | 元数据检查,不是网络硬限额 |
39
+ | 下载器准备 | `setup [--install]` | 安装是显式、需确认的系统包操作 |
40
+ | Python 调用 | `download_repo`、`fetch_metadata`、`setup_aria2` | 目前仍使用 Click 输出/异常,见接口页 |
41
+
42
+ ## 不在当前能力内
43
+
44
+ - Hugging Face 私有或 gated 仓库登录、Token 管理及转发。
45
+ - ModelScope 原生下载、wget 后端、旧 `hfd` 别名自动替换。
46
+ - 全局缓存目录管理、跨机器挂载、下载任务队列、后台守护进程。
47
+ - 上游加密哈希验收、模型推理验证或数据集训练流水线。
48
+
49
+ 不要把单个配置文件或 README 的成功下载称为“模型权重已经下载完成”。查看[快速开始](quickstart.md#model)区分小样例和完整仓库。
@@ -0,0 +1,88 @@
1
+ # CLI Tree and command reference
2
+
3
+ The complete tree comes from real `chathfd --tree` output, not a roadmap. Start with the brief view and then inspect each action.
4
+
5
+ ## Brief command tree
6
+
7
+ ```text
8
+ chathfd
9
+ ├── --help # Show this message and exit.
10
+ ├── --version # Show the version and exit.
11
+ ├── --tree # Print the registered CLI tree and exit.
12
+ ├── --tree-brief # Print the registered CLI tree without parameter signatures and exit.
13
+ ├── download # Download a public model or dataset with aria2c.
14
+ └── setup # Check the aria2c download engine and offer installation.
15
+ ```
16
+
17
+ ## Complete command tree
18
+
19
+ ```text
20
+ chathfd
21
+ ├── --help # Show this message and exit.
22
+ ├── --version # Show the version and exit.
23
+ ├── --tree # Print the registered CLI tree and exit.
24
+ ├── --tree-brief # Print the registered CLI tree without parameter signatures and exit.
25
+ ├── download <REPO-ID> [--repo-type REPO-TYPE] [--revision REVISION] [--endpoint ENDPOINT] [--local-dir LOCAL-DIR] [--include INCLUDE] [--exclude EXCLUDE] [--connections CONNECTIONS] [--jobs JOBS] [--dry-run] [--allow-large] # Download a public model or dataset with aria2c.
26
+ └── setup [--install] # Check the aria2c download engine and offer installation.
27
+ ```
28
+
29
+ ## Root options
30
+
31
+ | Option | Purpose | Effects |
32
+ | --- | --- | --- |
33
+ | `--help` | Help for the current command | No download |
34
+ | `--version` | Installed package version | No download |
35
+ | `--tree` | Registered tree with parameter signatures | No download |
36
+ | `--tree-brief` | Same commands without signatures | No download |
37
+
38
+ ## Download action {#download}
39
+
40
+ ```text
41
+ chathfd download REPO_ID [OPTIONS]
42
+ ```
43
+
44
+ `REPO_ID` is `organization/repository`, or a supported legacy single-name Hub repository. Models and datasets share one action; preview is an option, not a subcommand.
45
+
46
+ | Option | Default | Meaning |
47
+ | --- | --- | --- |
48
+ | `--repo-type [model|dataset]` | `model` | Repository type |
49
+ | `--revision TEXT` | `main` | Branch, tag or commit |
50
+ | `--endpoint TEXT` | `HF_ENDPOINT` or HF-Mirror | Compatible HTTPS origin; explicit option wins |
51
+ | `--local-dir DIRECTORY` | Current-directory `models/` or `datasets/` + repo ID | Selected file output root |
52
+ | `--include TEXT` | All files | Repeatable include glob |
53
+ | `--exclude TEXT` | None | Repeatable exclude glob |
54
+ | `--connections INTEGER` | `4`, range 1–10 | Connections/splits per file |
55
+ | `--jobs INTEGER` | `5`, range 1–10 | Concurrent files |
56
+ | `--dry-run` | Off | Query and list files/sizes without creating download files |
57
+ | `--allow-large` | Off | Permit transfer of a selection over 10 GiB |
58
+ | `--help` | — | Show action help only |
59
+
60
+ An actual transfer writes files and `.chathfd` records and invokes aria2. See [Configuration](configuration.md) for preflight and completion conditions. Login, token forwarding, wget and native ModelScope are outside the implemented option surface.
61
+
62
+ ```bash
63
+ chathfd download Qwen/Qwen3.8-Flash-Next --include config.json --dry-run
64
+ chathfd download MathArena/arxivmath-0926 --repo-type dataset --dry-run
65
+ ```
66
+
67
+ ## Engine preparation {#setup}
68
+
69
+ ```text
70
+ chathfd setup [--install] [--help]
71
+ ```
72
+
73
+ | Input | Behavior |
74
+ | --- | --- |
75
+ | No options | Check aria2c; print path when present or installation guidance otherwise |
76
+ | `--install` | If missing, show the proposed command and require confirmation before a package-manager call |
77
+ | `--help` | Show help without installation |
78
+
79
+ An existing aria2c is not reinstalled. This does not install external `hfd.sh`, launch a daemon or persist endpoint/output settings. Installation does not proceed without confirmation; manager errors fail nonzero.
80
+
81
+ ## Output and exit behavior
82
+
83
+ - Successful preview or verified download exits 0 and prints selection information; completed transfer adds size-verification output.
84
+ - Invalid input, failed network/metadata or incomplete transfer fails nonzero. A start message is not a completion receipt.
85
+ - Setup can exit normally after detecting or suggesting installation. Exit 0 alone does not prove a missing engine was installed; require `aria2c ready` and the executable.
86
+ - No extra `model`, `dataset`, `login` or `mirror` subcommands exist. Legacy `hfd` flags are not current options.
87
+
88
+ [Quickstart](quickstart.md) · [Python API](python-api.md) · [Legacy comparison](troubleshooting.md)
@@ -0,0 +1,88 @@
1
+ # CLI 树与命令参考
2
+
3
+ 完整树来自真实 `chathfd --tree`,不是规划中的命令。参数很多时,先看简明树,再进入对应动作。
4
+
5
+ ## 简明命令树
6
+
7
+ ```text
8
+ chathfd
9
+ ├── --help # Show this message and exit.
10
+ ├── --version # Show the version and exit.
11
+ ├── --tree # Print the registered CLI tree and exit.
12
+ ├── --tree-brief # Print the registered CLI tree without parameter signatures and exit.
13
+ ├── download # Download a public model or dataset with aria2c.
14
+ └── setup # Check the aria2c download engine and offer installation.
15
+ ```
16
+
17
+ ## 完整命令树
18
+
19
+ ```text
20
+ chathfd
21
+ ├── --help # Show this message and exit.
22
+ ├── --version # Show the version and exit.
23
+ ├── --tree # Print the registered CLI tree and exit.
24
+ ├── --tree-brief # Print the registered CLI tree without parameter signatures and exit.
25
+ ├── download <REPO-ID> [--repo-type REPO-TYPE] [--revision REVISION] [--endpoint ENDPOINT] [--local-dir LOCAL-DIR] [--include INCLUDE] [--exclude EXCLUDE] [--connections CONNECTIONS] [--jobs JOBS] [--dry-run] [--allow-large] # Download a public model or dataset with aria2c.
26
+ └── setup [--install] # Check the aria2c download engine and offer installation.
27
+ ```
28
+
29
+ ## 根选项
30
+
31
+ | 选项 | 作用 | 副作用 |
32
+ | --- | --- | --- |
33
+ | `--help` | 当前命令帮助 | 无下载 |
34
+ | `--version` | 已安装包版本 | 无下载 |
35
+ | `--tree` | 真实注册树,包含参数签名 | 无下载 |
36
+ | `--tree-brief` | 相同命令节点,省略参数签名 | 无下载 |
37
+
38
+ ## 下载动作 {#download}
39
+
40
+ ```text
41
+ chathfd download REPO_ID [OPTIONS]
42
+ ```
43
+
44
+ `REPO_ID` 为 `组织/仓库`,也接受 Hub 支持的单段旧仓库名。模型和数据集共用同一个动作;预览是选项,不是另一个子命令。
45
+
46
+ | 参数 | 默认值 | 含义 |
47
+ | --- | --- | --- |
48
+ | `--repo-type [model|dataset]` | `model` | 仓库类型 |
49
+ | `--revision TEXT` | `main` | 分支、标签或 commit |
50
+ | `--endpoint TEXT` | `HF_ENDPOINT` 或 HF-Mirror | 兼容 HTTPS origin;显式选项优先 |
51
+ | `--local-dir DIRECTORY` | 当前目录下 `models/` 或 `datasets/` + repo ID | 所选文件的输出根 |
52
+ | `--include TEXT` | 不限制 | 可重复的包含 glob |
53
+ | `--exclude TEXT` | 无 | 可重复的排除 glob |
54
+ | `--connections INTEGER` | `4`,范围 1–10 | 每个文件的连接/分片数 |
55
+ | `--jobs INTEGER` | `5`,范围 1–10 | 同时下载的文件数 |
56
+ | `--dry-run` | 关闭 | 查询并列出文件/大小,不创建下载文件 |
57
+ | `--allow-large` | 关闭 | 允许所选文件超过 10 GiB 后实际传输 |
58
+ | `--help` | — | 仅显示本动作帮助 |
59
+
60
+ 实际传输创建目标文件与 `.chathfd` 记录,并调用 aria2。预检与传输完成条件见[下载配置](configuration.md)。公开仓库以外的登录、Token、wget 和 ModelScope 后端不在当前参数面内。
61
+
62
+ ```bash
63
+ chathfd download Qwen/Qwen3.8-Flash-Next --include config.json --dry-run
64
+ chathfd download MathArena/arxivmath-0926 --repo-type dataset --dry-run
65
+ ```
66
+
67
+ ## 下载器准备 {#setup}
68
+
69
+ ```text
70
+ chathfd setup [--install] [--help]
71
+ ```
72
+
73
+ | 参数 | 行为 |
74
+ | --- | --- |
75
+ | 无选项 | 检查 aria2c;存在时打印路径,缺失时给出安装指引 |
76
+ | `--install` | 仅当缺失时提出明确安装命令;再次确认后才运行包管理器 |
77
+ | `--help` | 显示帮助,不安装 |
78
+
79
+ 已有 aria2c 时不会重复安装。当前不安装外部 `hfd.sh`、不启动守护进程、不改镜像或下载目录配置。无人确认的安装不会继续;包管理器错误非零退出。
80
+
81
+ ## 输出与退出状态
82
+
83
+ - 下载成功或预检完成:退出 0;输出选择信息,实际下载后输出按大小核验结果。
84
+ - 参数错误、网络/元数据错误或实际下载不完整:非零退出;不要只解析“开始下载”字样判断成功。
85
+ - `setup` 在检测/给出安装指引后可正常结束;退出 0 不等于缺失依赖已经安装,以 `aria2c ready` 和可执行文件为准。
86
+ - 当前无 `model`、`dataset`、`login`、`mirror` 等额外子命令;勿把旧 `hfd` 参数当作本工具参数。
87
+
88
+ [快速开始](quickstart.md) · [Python 接口](python-api.md) · [旧接口对照](troubleshooting.md)
@@ -0,0 +1,88 @@
1
+ # Configuration
2
+
3
+ <div class="grid cards" markdown>
4
+
5
+ - :material-web: **Endpoint**
6
+
7
+ ---
8
+
9
+ Use one Hugging Face-compatible HTTPS origin per invocation.
10
+
11
+ [Endpoint precedence](#endpoint)
12
+
13
+ - :material-folder-outline: **Output and resume**
14
+
15
+ ---
16
+
17
+ A destination belongs to one repository, commit and file selection.
18
+
19
+ [Destination identity](#resume)
20
+
21
+ - :material-speedometer: **Selection and concurrency**
22
+
23
+ ---
24
+
25
+ Control connections per file separately from concurrent files.
26
+
27
+ [Transfer settings](#selection)
28
+
29
+ </div>
30
+
31
+ ## Endpoint precedence {#endpoint}
32
+
33
+ | Source | Priority | Example |
34
+ | --- | --- | --- |
35
+ | CLI `--endpoint` | Highest | `--endpoint https://huggingface.co` |
36
+ | Process `HF_ENDPOINT` | Next | `HF_ENDPOINT=https://hf-mirror.com` |
37
+ | Built-in default | Last | `https://hf-mirror.com` |
38
+
39
+ ```bash
40
+ HF_ENDPOINT=https://hf-mirror.com chathfd download Qwen/Qwen3.8-Flash-Next --include config.json --dry-run
41
+ chathfd download Qwen/Qwen3.8-Flash-Next --endpoint https://huggingface.co --include config.json --dry-run
42
+ ```
43
+
44
+ The endpoint must be an HTTPS origin without userinfo, path, query or fragment. The CLI does not persist settings, automatically retry another mirror or silently fall back. Python `download_repo()` takes an explicit `endpoint`; it does not load `HF_ENDPOINT` for you.
45
+
46
+ ModelScope is not an interchangeable `HF_ENDPOINT`. It has separate repository IDs, availability and an SDK; ChatHFD has no ModelScope backend. Legacy token flags do not add authentication to the current downloader.
47
+
48
+ ## File selection and concurrency {#selection}
49
+
50
+ ```bash
51
+ chathfd download Qwen/Qwen3.8-Flash-Next \
52
+ --include 'config.json' --include 'generation_config.json' \
53
+ --exclude 'README*' --connections 4 --jobs 5 --dry-run
54
+ ```
55
+
56
+ - Repeat `--include` for an OR across patterns; without it all files are selected.
57
+ - Repeated `--exclude` patterns remove matching repository-relative paths; exclusion wins.
58
+ - Quote globs to prevent local shell expansion.
59
+ - `--connections` controls per-file connections/splits (default 4); `--jobs` concurrent files (default 5). Both CLI ranges are 1–10; their product is not a promise of actual active connections.
60
+ - `--revision` accepts a branch, tag or commit. Resolve URLs use the commit returned by metadata, even when the request names `main`.
61
+
62
+ ## Output and resume identity {#resume}
63
+
64
+ Without `--local-dir`, models use `./models/<org>/<repo>` and datasets `./datasets/<org>/<repo>`, relative to the invocation directory. This is not the standard Hugging Face cache layout and does not infer another machine's shared-storage paths.
65
+
66
+ ```text
67
+ <destination>/
68
+ ├── <selected repository files>
69
+ └── .chathfd/
70
+ ├── selection.json # endpoint/repo/type/commit/names and sizes
71
+ └── urls.txt # aria2 input list
72
+ ```
73
+
74
+ A repeat invocation must match endpoint, repository, type, commit and selected file set. Partial transfers require aria2 `.aria2` state; complete same-size files are skipped. Use a fresh directory when changing file sets, endpoint or commit. Unknown existing files, symlinks, path escapes, internal-name collisions and wrong-size files without resume state are rejected, not silently deleted or overwritten.
75
+
76
+ Dry-run checks metadata, selection and paths only. It creates no receipt and does not perform every destination-identity check required for an actual transfer; a successful preview does not guarantee a pre-existing destination can be reused.
77
+
78
+ ## Large selections and verification {#limits}
79
+
80
+ | Behavior | Contract |
81
+ | --- | --- |
82
+ | Selection above 10 GiB | Preview succeeds; transfer requires `--allow-large` |
83
+ | Hard network-byte quota | None; sizes come from server metadata |
84
+ | Completion | Files exist with expected size and no remaining aria2 state |
85
+ | Cryptographic hashes or inference | Not verified |
86
+ | Downloader configuration | Default aria2 config and netrc are disabled to avoid implicit credentials |
87
+
88
+ Continue with [all options](cli-tree.md#download) and [Troubleshooting](troubleshooting.md).