故障排查与旧接口
先根据错误选择下一步；不要用删除目录、传 Token 或反复重试来掩盖条件不满足。
| 现象 | 含义 | 下一步 |
|---|---|---|
找不到 aria2c |
实际传输依赖缺失 | chathfd setup；需安装时显式 setup --install |
| 安装失败或无包管理器 | 管理器、权限或系统环境不满足 | 按提示在交互终端安装；不要把密码放入参数 |
| 元数据 HTTP/网络错误 | 端点、仓库或网络不可用 | 检查仓库卡、repo-type 与已有网络设置；用 --endpoint 明确选择 |
| 没有匹配文件 | include/exclude 没选到内容 | 检查仓库相对路径，并给通配符加引号 |
| 超过 10 GiB | 所选文件体量大 | 先 --dry-run；确认资源后才用 --allow-large |
| 目录属于另一选择 | endpoint/repo/type/commit/文件集合发生变化 | 选择新目录；不要删掉记录后假装续传 |
| 已有文件无下载记录 | 无法确认旧文件来源 | 另选目录，保留原文件 |
文件大小错误且无 .aria2 |
不可安全续传的旧文件 | 明确移走该文件后用新目录重试 |
| 下载中断 | aria2 传输未完成 | 在同一固定 commit 与文件集合下重跑 |
| gated/private 仓库被拒绝 | 当前工具不支持认证 | 使用官方工具及其正式授权流程；勿把 Key 放进本命令 |
从旧 HFD 迁移
下表是接口对照，不是承诺旧别名或参数仍可用。
| 旧用法 | 当前用法 | 差异 |
|---|---|---|
hfd REPO_ID |
chathfd download REPO_ID |
根命令与下载动作分开 |
-d / --dataset |
--repo-type dataset |
当前没有 -d 别名 |
-x 4 |
--connections 4 |
单文件连接数；--jobs 另控并发文件 |
--tool wget |
无对应后端 | 当前只使用 aria2 |
--hf_username / --hf_token |
无对应参数 | 当前只下载公开仓库 |
| 机器上写死的共享目录 | 显式 --local-dir |
当前不管理共享挂载或全局缓存 |
| 自动抓取外部 hfd.sh | 无需外部 hfd.sh | 包内 Python 实现与 aria2 协作 |
旧脚本的别名、后端路径或日志可能包含机器配置，不能把它们直接复制到公开文档。旧接口示例中也不要填入真实令牌。需要新后端或认证能力时应先明确契约，而不是假设改一个端点就能支持。