ChatHFD 0.1.2__tar.gz → 0.1.4__tar.gz

chathfd-0.1.4/AGENTS.md

@@ -0,0 +1,8 @@
+# Agent Notes
+
+## Development Expectations
+
+- Keep changes minimal and reviewable.
+- Prefer doc-first CLI tests.
+- Sync docs and changelog with user-facing behavior.
+- Use interactive prompts only when arguments are missing and recoverable.

chathfd-0.1.4/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+## 2026-11-09 - 0.1.4
+
+### 文档
+
+- 补齐中英文多栏导航首页、快速开始、完整 CLI 参数参考、配置与续传、能力地图、接口树、Python 示例和故障排查。
+- 增加文档与真实 CLI/API 的一致性测试，明确模型配置小样例、公开仓库及验证边界。
+- 文档预览与正式部署共享发布锁，正式部署保留已有 dev 预览；预览语言入口保持在预览路径内。
+
+下载命令行为保持不变。
+
+## 2026-11-08 - 0.1.3
+
+### Added
+
+- 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.
+- Added `chathfd setup` to detect aria2c, suggest installation commands, and offer a confirmed `--install` path.
+
+### Changed
+
+- 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.
+
+## 2026-08-21 - 0.1.2
+
+### Changed
+
+- Migrated `--tree` and the new `--tree-brief` flag to ChatStyle's shared Click tree runtime with canonical root name `chathfd`.
+- Kept command parameter signatures in the default tree and omitted them in the brief tree while retaining command nodes and descriptions.
+- Updated runtime bounds to `chatstyle>=0.2.0,<0.3.0` and `chatenv>=0.2.10,<0.3.0`.
+- Added detailed and brief tree smoke coverage to package tests and CI.
+
+## 2026-08-12 - 0.1.1
+
+### Added
+
+- Added real root-only `chathfd --tree` generated from the Click command surface.
+- Added CLI contract tests for `--help`, `--version`, and `--tree`.
+
+### Changed
+
+- Aligned documentation URLs to `https://arch.gh.wzhecnu.cn/ChatHFD/`.
+- Enabled bilingual MkDocs navigation and Material icon rendering.
+- Hardened Preview Docs and tag-only OIDC publish workflows.
+
+## 2026-07-01 - 0.1.0
+
+### Added
+
+- Initial ChatHFD package scaffold with `chathfd` CLI.
+- ChatEnv provider entry point for `chathfd` configuration discovery.
+- CI and tag-driven Trusted Publisher workflow scaffold.

chathfd-0.1.4/DEVELOP.md

@@ -0,0 +1,26 @@
+# Development Guide
+
+## CLI Rules
+
+- Use `chatstyle>=0.2.0,<0.3.0` and `chatenv>=0.2.10,<0.3.0` as the canonical CLI interaction runtime.
+- Attach `chatstyle.add_tree_option` to the top-level Click group with the canonical `chathfd` root name.
+- Keep `--tree` as the detailed tree with command parameter signatures and `--tree-brief` as the signature-free view.
+- Prefer `CommandSchema`, `CommandField`, `add_interactive_option()`, and `resolve_command_inputs()` for new commands.
+- Missing required args should auto-enter interactive mode when recoverable.
+- `-i` forces interactive mode; `-I` disables prompting and must fail fast.
+- Prompt defaults must match actual execution defaults.
+- Sensitive values must stay masked in prompts and summaries.
+- Prefer lazy imports in CLI wiring and keep implementation imports local when possible.
+
+## Docs and Tests
+
+- Use doc-first CLI testing.
+- Put real CLI coverage under `tests/cli-tests/`.
+- Put mock/fake CLI coverage under `tests/mock-cli-tests/`.
+- Keep `README.md`, `docs/`, and `CHANGELOG.md` in sync with user-facing changes.
+
+## Automation
+
+- Keep automation small and reviewable.
+- Prefer commands that can run in CI without interactive prompts.
+- Ensure generated defaults are safe for local development.

chathfd-0.1.4/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md README.en.md CHANGELOG.md DEVELOP.md AGENTS.md mkdocs.yml
+recursive-include docs *.md
+include scripts/preserve_docs_preview.py
+recursive-include tests *.py *.md

chathfd-0.1.4/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: ChatHFD
+Version: 0.1.4
+Summary: ChatHFD: ChatArch Hugging Face Download tooling package
+Author-email: ChatArch <1073853456@qq.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ChatArch/ChatHFD
+Project-URL: Repository, https://github.com/ChatArch/ChatHFD
+Project-URL: Documentation, https://arch.gh.wzhecnu.cn/ChatHFD/
+Keywords: chathfd,chatarch,cli
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0
+Requires-Dist: chatstyle<0.3.0,>=0.2.0
+Requires-Dist: chatenv<0.3.0,>=0.2.10
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs<2.0,>=1.6; extra == "docs"
+Requires-Dist: mkdocs-material<10.0,>=9.5; extra == "docs"
+Requires-Dist: mkdocs-static-i18n<2.0,>=1.2; extra == "docs"
+Requires-Dist: mike<3.0,>=2.0; extra == "docs"
+Dynamic: license-file
+
+<div align="center">
+    <a href="https://pypi.python.org/pypi/ChatHFD"><img src="https://img.shields.io/pypi/v/ChatHFD.svg" alt="PyPI version" /></a>
+    <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>
+</div>
+
+<div align="center">[英文版](README.en.md) | [简体中文](README.md)</div>
+
+# ChatHFD
+
+ChatHFD 是 ChatArch 的 Hugging Face 模型与数据集下载工具。要求 Python 3.10+ 和 `aria2c`；只支持公开仓库，不在命令行传递 Token。
+
+## 文档导航
+
+| 你要做什么 | 文档入口 |
+| --- | --- |
+| 第一次安装与下载 | [快速开始](https://arch.gh.wzhecnu.cn/ChatHFD/quickstart/) |
+| 查看全部命令、参数与默认值 | [完整 CLI 树](https://arch.gh.wzhecnu.cn/ChatHFD/cli-tree/) |
+| 配置镜像、目录和续传 | [下载配置](https://arch.gh.wzhecnu.cn/ChatHFD/configuration/) |
+| 从 Python 调用 | [Python 接口](https://arch.gh.wzhecnu.cn/ChatHFD/python-api/)与[接口树](https://arch.gh.wzhecnu.cn/ChatHFD/interface-tree/) |
+| 查看当前支持范围 | [能力地图](https://arch.gh.wzhecnu.cn/ChatHFD/capability-map/) |
+| 解决失败或对照旧参数 | [故障排查](https://arch.gh.wzhecnu.cn/ChatHFD/troubleshooting/) |
+
+## 下载示例
+
+```bash
+pip install ChatHFD==0.1.4
+chathfd --tree
+chathfd setup  # 检查 aria2c；未安装时提示命令
+# 如确需安装：chathfd setup --install（还需确认）
+# 先预检 Qwen 模型中的小文件，不直接全量下载权重
+chathfd download Qwen/Qwen3.8-Flash-Next --include config.json --dry-run
+chathfd download Qwen/Qwen3.8-Flash-Next --include config.json --local-dir ./models/qwen-sample
+# 数学数据集：约 246 KB，包含 README、元数据和一个 Parquet 分片
+chathfd download MathArena/arxivmath-0926 --repo-type dataset --dry-run
+chathfd download MathArena/arxivmath-0926 --repo-type dataset --local-dir ./datasets/arxivmath-0926
+```
+
+默认端点为 `https://hf-mirror.com`；`HF_ENDPOINT` 环境变量或 `--endpoint` 可覆盖为其它 Hugging Face 兼容 HTTPS 端点（如 `https://huggingface.co`）。使用 `--include` / `--exclude`（可重复）筛选仓库路径，`--revision` 固定版本，`--jobs`（默认 5）控制并发文件数，`--connections`（默认 4）控制每文件连接数。下载通过 aria2 续传，完成后只核对文件大小，不做加密哈希校验。若已有文件大小不匹配且无 aria2 续传状态，命令会报错而不会删除它。
+
+默认最多选择 10 GiB 文件；如确需更大的全量权重，先看 `--dry-run` 的大小与磁盘空间，再明确使用 `--allow-large`。元数据响应的 commit SHA 会固定到下载 URL，目标目录也记录仓库、commit 和选中文件集合；再次运行同一集合可续传，分支更新、选中文件集合改变或目标目录已有未知文件时应另选目录。10 GiB 是元数据预检，不是服务器返回字节数的硬上限。`--dry-run` 不创建目标文件，即使超过 10 GiB 仍可预览。默认目录为 `./models/<org>/<repo>` 或 `./datasets/<org>/<repo>`。
+
+ModelScope 是独立仓库平台，不是 HF-Mirror 的 `HF_ENDPOINT` 替代地址；仅当该模型/数据集也在 ModelScope 发布时，另用其 SDK，例如 `modelscope download --model Qwen/Qwen2.5-0.5B-Instruct --local_dir ./model`。不能假定 HF 仓库 ID 在 ModelScope 同步存在，也不能把其 SDK 当作本命令的自动回退。
+
+参考：[HF-Mirror 下载说明](https://hf-mirror.com/) · [ModelScope CLI](https://www.modelscope.cn/docs/sdk/cli) · [Qwen 模型](https://huggingface.co/Qwen/Qwen3.8-Flash-Next) · [MathArena 数据集](https://huggingface.co/datasets/MathArena/arxivmath-0926)。
+
+## 当前 CLI 树（`--tree`）
+
+```text
+chathfd
+├── --help  # Show this message and exit.
+├── --version  # Show the version and exit.
+├── --tree  # Print the registered CLI tree and exit.
+├── --tree-brief  # Print the registered CLI tree without parameter signatures and exit.
+├── 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.
+└── setup [--install]  # Check the aria2c download engine and offer installation.
+```
+
+`--tree-brief` 省略子命令参数签名。`src/` 是源码；`tests/cli-tests/` 是真实 CLI 测试；`tests/mock-cli-tests/` 是模拟测试；`docs/` 是长期文档。扩展前请阅读 `DEVELOP.md` 和 `AGENTS.md`。

chathfd-0.1.4/README.en.md

@@ -0,0 +1,58 @@
+<div align="center">
+    <a href="https://pypi.python.org/pypi/ChatHFD"><img src="https://img.shields.io/pypi/v/ChatHFD.svg" alt="PyPI version" /></a>
+    <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>
+</div>
+
+<div align="center">[English](README.en.md) | [简体中文](README.md)</div>
+
+# ChatHFD
+
+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.
+
+## Documentation
+
+| Task | Guide |
+| --- | --- |
+| First installation and download | [Quickstart](https://arch.gh.wzhecnu.cn/ChatHFD/en/quickstart/) |
+| Every command, option and default | [Complete CLI Tree](https://arch.gh.wzhecnu.cn/ChatHFD/en/cli-tree/) |
+| Endpoint, destination and resume | [Configuration](https://arch.gh.wzhecnu.cn/ChatHFD/en/configuration/) |
+| 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/) |
+| Implemented scope | [Capability Map](https://arch.gh.wzhecnu.cn/ChatHFD/en/capability-map/) |
+| Failures and legacy flags | [Troubleshooting](https://arch.gh.wzhecnu.cn/ChatHFD/en/troubleshooting/) |
+
+## Examples
+
+```bash
+pip install ChatHFD==0.1.4
+chathfd --tree
+chathfd setup  # Check aria2c; if missing, show installation guidance
+# To install explicitly: chathfd setup --install (requires confirmation)
+# Inspect a small file in a recent open Qwen model (the full repo is ~360 GB)
+chathfd download Qwen/Qwen3.8-Flash-Next --include config.json --dry-run
+chathfd download Qwen/Qwen3.8-Flash-Next --include config.json --local-dir ./models/qwen-sample
+# Recent math dataset (~246 KB including its single Parquet shard)
+chathfd download MathArena/arxivmath-0926 --repo-type dataset --dry-run
+chathfd download MathArena/arxivmath-0926 --repo-type dataset --local-dir ./datasets/arxivmath-0926
+```
+
+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.
+
+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>`.
+
+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.
+
+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).
+
+## Current CLI tree (`--tree`)
+
+```text
+chathfd
+├── --help  # Show this message and exit.
+├── --version  # Show the version and exit.
+├── --tree  # Print the registered CLI tree and exit.
+├── --tree-brief  # Print the registered CLI tree without parameter signatures and exit.
+├── 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.
+└── setup [--install]  # Check the aria2c download engine and offer installation.
+```
+
+`--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.

chathfd-0.1.4/README.md

@@ -0,0 +1,58 @@
+<div align="center">
+    <a href="https://pypi.python.org/pypi/ChatHFD"><img src="https://img.shields.io/pypi/v/ChatHFD.svg" alt="PyPI version" /></a>
+    <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>
+</div>
+
+<div align="center">[英文版](README.en.md) | [简体中文](README.md)</div>
+
+# ChatHFD
+
+ChatHFD 是 ChatArch 的 Hugging Face 模型与数据集下载工具。要求 Python 3.10+ 和 `aria2c`；只支持公开仓库，不在命令行传递 Token。
+
+## 文档导航
+
+| 你要做什么 | 文档入口 |
+| --- | --- |
+| 第一次安装与下载 | [快速开始](https://arch.gh.wzhecnu.cn/ChatHFD/quickstart/) |
+| 查看全部命令、参数与默认值 | [完整 CLI 树](https://arch.gh.wzhecnu.cn/ChatHFD/cli-tree/) |
+| 配置镜像、目录和续传 | [下载配置](https://arch.gh.wzhecnu.cn/ChatHFD/configuration/) |
+| 从 Python 调用 | [Python 接口](https://arch.gh.wzhecnu.cn/ChatHFD/python-api/)与[接口树](https://arch.gh.wzhecnu.cn/ChatHFD/interface-tree/) |
+| 查看当前支持范围 | [能力地图](https://arch.gh.wzhecnu.cn/ChatHFD/capability-map/) |
+| 解决失败或对照旧参数 | [故障排查](https://arch.gh.wzhecnu.cn/ChatHFD/troubleshooting/) |
+
+## 下载示例
+
+```bash
+pip install ChatHFD==0.1.4
+chathfd --tree
+chathfd setup  # 检查 aria2c；未安装时提示命令
+# 如确需安装：chathfd setup --install（还需确认）
+# 先预检 Qwen 模型中的小文件，不直接全量下载权重
+chathfd download Qwen/Qwen3.8-Flash-Next --include config.json --dry-run
+chathfd download Qwen/Qwen3.8-Flash-Next --include config.json --local-dir ./models/qwen-sample
+# 数学数据集：约 246 KB，包含 README、元数据和一个 Parquet 分片
+chathfd download MathArena/arxivmath-0926 --repo-type dataset --dry-run
+chathfd download MathArena/arxivmath-0926 --repo-type dataset --local-dir ./datasets/arxivmath-0926
+```
+
+默认端点为 `https://hf-mirror.com`；`HF_ENDPOINT` 环境变量或 `--endpoint` 可覆盖为其它 Hugging Face 兼容 HTTPS 端点（如 `https://huggingface.co`）。使用 `--include` / `--exclude`（可重复）筛选仓库路径，`--revision` 固定版本，`--jobs`（默认 5）控制并发文件数，`--connections`（默认 4）控制每文件连接数。下载通过 aria2 续传，完成后只核对文件大小，不做加密哈希校验。若已有文件大小不匹配且无 aria2 续传状态，命令会报错而不会删除它。
+
+默认最多选择 10 GiB 文件；如确需更大的全量权重，先看 `--dry-run` 的大小与磁盘空间，再明确使用 `--allow-large`。元数据响应的 commit SHA 会固定到下载 URL，目标目录也记录仓库、commit 和选中文件集合；再次运行同一集合可续传，分支更新、选中文件集合改变或目标目录已有未知文件时应另选目录。10 GiB 是元数据预检，不是服务器返回字节数的硬上限。`--dry-run` 不创建目标文件，即使超过 10 GiB 仍可预览。默认目录为 `./models/<org>/<repo>` 或 `./datasets/<org>/<repo>`。
+
+ModelScope 是独立仓库平台，不是 HF-Mirror 的 `HF_ENDPOINT` 替代地址；仅当该模型/数据集也在 ModelScope 发布时，另用其 SDK，例如 `modelscope download --model Qwen/Qwen2.5-0.5B-Instruct --local_dir ./model`。不能假定 HF 仓库 ID 在 ModelScope 同步存在，也不能把其 SDK 当作本命令的自动回退。
+
+参考：[HF-Mirror 下载说明](https://hf-mirror.com/) · [ModelScope CLI](https://www.modelscope.cn/docs/sdk/cli) · [Qwen 模型](https://huggingface.co/Qwen/Qwen3.8-Flash-Next) · [MathArena 数据集](https://huggingface.co/datasets/MathArena/arxivmath-0926)。
+
+## 当前 CLI 树（`--tree`）
+
+```text
+chathfd
+├── --help  # Show this message and exit.
+├── --version  # Show the version and exit.
+├── --tree  # Print the registered CLI tree and exit.
+├── --tree-brief  # Print the registered CLI tree without parameter signatures and exit.
+├── 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.
+└── setup [--install]  # Check the aria2c download engine and offer installation.
+```
+
+`--tree-brief` 省略子命令参数签名。`src/` 是源码；`tests/cli-tests/` 是真实 CLI 测试；`tests/mock-cli-tests/` 是模拟测试；`docs/` 是长期文档。扩展前请阅读 `DEVELOP.md` 和 `AGENTS.md`。

chathfd-0.1.4/docs/capability-map.en.md

@@ -0,0 +1,49 @@
+# Capability Map
+
+<div class="grid cards" markdown>
+
+-   :material-download-outline: **Repository files**
+
+    ---
+
+    Public models and datasets, selection, revision and output.
+
+    [Run examples](quickstart.md)
+
+-   :material-shield-check-outline: **Preflight and resume**
+
+    ---
+
+    Explicit selection, commit pinning and destination identity; size-based completion checks.
+
+    [Read constraints](configuration.md#resume)
+
+-   :material-code-braces: **Reusable interfaces**
+
+    ---
+
+    CLI adapters call importable Python functions; aria2 transfers files.
+
+    [Interface mapping](interface-tree.md)
+
+</div>
+
+## Implemented
+
+| Capability | Interface | Boundary |
+| --- | --- | --- |
+| Models and datasets | `download`, `--repo-type` | Public repository files, not training or inference |
+| Compatible mirrors | `--endpoint`, `HF_ENDPOINT` | HF-Mirror by default; no cross-platform fallback |
+| Concurrency and resume | `--connections`, `--jobs` | Local aria2 and matching destination identity |
+| Selection and size preview | `--include`, `--exclude`, `--dry-run` | Metadata preflight, not a hard byte quota |
+| Engine preparation | `setup [--install]` | Explicit, confirmed system package installation |
+| Python calls | `download_repo`, `fetch_metadata`, `setup_aria2` | Still use Click output/errors; see API reference |
+
+## Outside the current boundary
+
+- Login, token management or forwarding for private/gated Hub repositories.
+- Native ModelScope downloads, wget backend or automatic replacement of old `hfd` aliases.
+- Global cache management, remote filesystem mounts, job queues or background daemons.
+- Upstream cryptographic verification, inference validation or dataset training pipelines.
+
+A successful config or README download is not a completed weight download. [Quickstart](quickstart.md#model) distinguishes small examples from full repositories.

chathfd-0.1.4/docs/capability-map.md

@@ -0,0 +1,49 @@
+# 能力地图
+
+<div class="grid cards" markdown>
+
+-   :material-download-outline: **仓库文件下载**
+
+    ---
+
+    公开模型、数据集、文件筛选、版本与目录。
+
+    [运行示例](quickstart.md)
+
+-   :material-shield-check-outline: **预检与续传**
+
+    ---
+
+    明确选择、commit 固定与目录身份；完成按大小检查。
+
+    [阅读约束](configuration.md#resume)
+
+-   :material-code-braces: **可复用接口**
+
+    ---
+
+    CLI 调用 importable Python 函数，aria2 执行传输。
+
+    [接口映射](interface-tree.md)
+
+</div>
+
+## 已实现
+
+| 能力 | 接口 | 边界 |
+| --- | --- | --- |
+| 模型与数据集 | `download`、`--repo-type` | 仅公开仓库文件，不启动训练或推理 |
+| 兼容镜像 | `--endpoint`、`HF_ENDPOINT` | 默认 HF-Mirror，无自动跨平台回退 |
+| 并发与续传 | `--connections`、`--jobs` | 需本机 aria2，目录身份须匹配 |
+| 文件和体量预检 | `--include`、`--exclude`、`--dry-run` | 元数据检查，不是网络硬限额 |
+| 下载器准备 | `setup [--install]` | 安装是显式、需确认的系统包操作 |
+| Python 调用 | `download_repo`、`fetch_metadata`、`setup_aria2` | 目前仍使用 Click 输出/异常，见接口页 |
+
+## 不在当前能力内
+
+- Hugging Face 私有或 gated 仓库登录、Token 管理及转发。
+- ModelScope 原生下载、wget 后端、旧 `hfd` 别名自动替换。
+- 全局缓存目录管理、跨机器挂载、下载任务队列、后台守护进程。
+- 上游加密哈希验收、模型推理验证或数据集训练流水线。
+
+不要把单个配置文件或 README 的成功下载称为“模型权重已经下载完成”。查看[快速开始](quickstart.md#model)区分小样例和完整仓库。

chathfd-0.1.4/docs/cli-tree.en.md

@@ -0,0 +1,88 @@
+# CLI Tree and command reference
+
+The complete tree comes from real `chathfd --tree` output, not a roadmap. Start with the brief view and then inspect each action.
+
+## Brief command tree
+
+```text
+chathfd
+├── --help  # Show this message and exit.
+├── --version  # Show the version and exit.
+├── --tree  # Print the registered CLI tree and exit.
+├── --tree-brief  # Print the registered CLI tree without parameter signatures and exit.
+├── download  # Download a public model or dataset with aria2c.
+└── setup  # Check the aria2c download engine and offer installation.
+```
+
+## Complete command tree
+
+```text
+chathfd
+├── --help  # Show this message and exit.
+├── --version  # Show the version and exit.
+├── --tree  # Print the registered CLI tree and exit.
+├── --tree-brief  # Print the registered CLI tree without parameter signatures and exit.
+├── 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.
+└── setup [--install]  # Check the aria2c download engine and offer installation.
+```
+
+## Root options
+
+| Option | Purpose | Effects |
+| --- | --- | --- |
+| `--help` | Help for the current command | No download |
+| `--version` | Installed package version | No download |
+| `--tree` | Registered tree with parameter signatures | No download |
+| `--tree-brief` | Same commands without signatures | No download |
+
+## Download action {#download}
+
+```text
+chathfd download REPO_ID [OPTIONS]
+```
+
+`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.
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `--repo-type [model|dataset]` | `model` | Repository type |
+| `--revision TEXT` | `main` | Branch, tag or commit |
+| `--endpoint TEXT` | `HF_ENDPOINT` or HF-Mirror | Compatible HTTPS origin; explicit option wins |
+| `--local-dir DIRECTORY` | Current-directory `models/` or `datasets/` + repo ID | Selected file output root |
+| `--include TEXT` | All files | Repeatable include glob |
+| `--exclude TEXT` | None | Repeatable exclude glob |
+| `--connections INTEGER` | `4`, range 1–10 | Connections/splits per file |
+| `--jobs INTEGER` | `5`, range 1–10 | Concurrent files |
+| `--dry-run` | Off | Query and list files/sizes without creating download files |
+| `--allow-large` | Off | Permit transfer of a selection over 10 GiB |
+| `--help` | — | Show action help only |
+
+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.
+
+```bash
+chathfd download Qwen/Qwen3.8-Flash-Next --include config.json --dry-run
+chathfd download MathArena/arxivmath-0926 --repo-type dataset --dry-run
+```
+
+## Engine preparation {#setup}
+
+```text
+chathfd setup [--install] [--help]
+```
+
+| Input | Behavior |
+| --- | --- |
+| No options | Check aria2c; print path when present or installation guidance otherwise |
+| `--install` | If missing, show the proposed command and require confirmation before a package-manager call |
+| `--help` | Show help without installation |
+
+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.
+
+## Output and exit behavior
+
+- Successful preview or verified download exits 0 and prints selection information; completed transfer adds size-verification output.
+- Invalid input, failed network/metadata or incomplete transfer fails nonzero. A start message is not a completion receipt.
+- 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.
+- No extra `model`, `dataset`, `login` or `mirror` subcommands exist. Legacy `hfd` flags are not current options.
+
+[Quickstart](quickstart.md) · [Python API](python-api.md) · [Legacy comparison](troubleshooting.md)

chathfd-0.1.4/docs/cli-tree.md

@@ -0,0 +1,88 @@
+# CLI 树与命令参考
+
+完整树来自真实 `chathfd --tree`，不是规划中的命令。参数很多时，先看简明树，再进入对应动作。
+
+## 简明命令树
+
+```text
+chathfd
+├── --help  # Show this message and exit.
+├── --version  # Show the version and exit.
+├── --tree  # Print the registered CLI tree and exit.
+├── --tree-brief  # Print the registered CLI tree without parameter signatures and exit.
+├── download  # Download a public model or dataset with aria2c.
+└── setup  # Check the aria2c download engine and offer installation.
+```
+
+## 完整命令树
+
+```text
+chathfd
+├── --help  # Show this message and exit.
+├── --version  # Show the version and exit.
+├── --tree  # Print the registered CLI tree and exit.
+├── --tree-brief  # Print the registered CLI tree without parameter signatures and exit.
+├── 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.
+└── setup [--install]  # Check the aria2c download engine and offer installation.
+```
+
+## 根选项
+
+| 选项 | 作用 | 副作用 |
+| --- | --- | --- |
+| `--help` | 当前命令帮助 | 无下载 |
+| `--version` | 已安装包版本 | 无下载 |
+| `--tree` | 真实注册树，包含参数签名 | 无下载 |
+| `--tree-brief` | 相同命令节点，省略参数签名 | 无下载 |
+
+## 下载动作 {#download}
+
+```text
+chathfd download REPO_ID [OPTIONS]
+```
+
+`REPO_ID` 为 `组织/仓库`，也接受 Hub 支持的单段旧仓库名。模型和数据集共用同一个动作；预览是选项，不是另一个子命令。
+
+| 参数 | 默认值 | 含义 |
+| --- | --- | --- |
+| `--repo-type [model|dataset]` | `model` | 仓库类型 |
+| `--revision TEXT` | `main` | 分支、标签或 commit |
+| `--endpoint TEXT` | `HF_ENDPOINT` 或 HF-Mirror | 兼容 HTTPS origin；显式选项优先 |
+| `--local-dir DIRECTORY` | 当前目录下 `models/` 或 `datasets/` + repo ID | 所选文件的输出根 |
+| `--include TEXT` | 不限制 | 可重复的包含 glob |
+| `--exclude TEXT` | 无 | 可重复的排除 glob |
+| `--connections INTEGER` | `4`，范围 1–10 | 每个文件的连接/分片数 |
+| `--jobs INTEGER` | `5`，范围 1–10 | 同时下载的文件数 |
+| `--dry-run` | 关闭 | 查询并列出文件/大小，不创建下载文件 |
+| `--allow-large` | 关闭 | 允许所选文件超过 10 GiB 后实际传输 |
+| `--help` | — | 仅显示本动作帮助 |
+
+实际传输创建目标文件与 `.chathfd` 记录，并调用 aria2。预检与传输完成条件见[下载配置](configuration.md)。公开仓库以外的登录、Token、wget 和 ModelScope 后端不在当前参数面内。
+
+```bash
+chathfd download Qwen/Qwen3.8-Flash-Next --include config.json --dry-run
+chathfd download MathArena/arxivmath-0926 --repo-type dataset --dry-run
+```
+
+## 下载器准备 {#setup}
+
+```text
+chathfd setup [--install] [--help]
+```
+
+| 参数 | 行为 |
+| --- | --- |
+| 无选项 | 检查 aria2c；存在时打印路径，缺失时给出安装指引 |
+| `--install` | 仅当缺失时提出明确安装命令；再次确认后才运行包管理器 |
+| `--help` | 显示帮助，不安装 |
+
+已有 aria2c 时不会重复安装。当前不安装外部 `hfd.sh`、不启动守护进程、不改镜像或下载目录配置。无人确认的安装不会继续；包管理器错误非零退出。
+
+## 输出与退出状态
+
+- 下载成功或预检完成：退出 0；输出选择信息，实际下载后输出按大小核验结果。
+- 参数错误、网络/元数据错误或实际下载不完整：非零退出；不要只解析“开始下载”字样判断成功。
+- `setup` 在检测/给出安装指引后可正常结束；退出 0 不等于缺失依赖已经安装，以 `aria2c ready` 和可执行文件为准。
+- 当前无 `model`、`dataset`、`login`、`mirror` 等额外子命令；勿把旧 `hfd` 参数当作本工具参数。
+
+[快速开始](quickstart.md) · [Python 接口](python-api.md) · [旧接口对照](troubleshooting.md)