抓取 Danbooru Tags API 的全部 tag，保存为本地 CSV， 支持断点续传、增量更新与全量刷新。匿名访问、按 1 请求/秒限速，2026-10 实测 184 万行约 31 分钟。

• 断点续传 —— ID 游标降序扫描（不用会被限死在 100 万条的偏移分页），每页 flush CSV 并原子写断点，Ctrl-C / 断网后重跑同一条命令接着抓。
• 增量更新 —— hanatsumi update 只抓上次之后新增的 tag，秒级完成。
• 全量刷新 —— hanatsumi refresh 全量重扫到暂存文件，真正到达底部才原子替换， 期间旧文件可正常读取；用于同步 post_count、改名、废弃与删除。
• 校验恢复 —— hanatsumi verify 对账行数 / id 范围 / 坏行 / 重复 id，状态文件丢失可按 CSV 重建。

分页与限速的实测依据见 docs/api.md，完整设计（状态不变量、 update 与 refresh 的分工、日志与输出策略、退出码）见 docs/design.md。

安装

Python 3.10 及以上：

pip install hanatsumi

从源码（含开发工具 ruff / ty / pytest）：

git clone git@github.com:licyk/temp.git && cd temp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

快速开始

hanatsumi fetch       # 全量抓取：约 1837 页 / 31 分钟，随时 Ctrl-C，重跑同命令续传
hanatsumi status      # 看断点与 CSV 概况
hanatsumi update      # 之后每次同步新增的 tag（秒级）
hanatsumi refresh     # 让 post_count / 改名 / 废弃 / 删除也同步进来（约 1 小时）

hanatsumi 装好后是独立命令；也可以用 python -m hanatsumi fetch。

命令行

hanatsumi
├── fetch    [--out --state --delay --page-size --timeout --max-retries --max-pages -q]
├── update   [同上]                      增量抓取上次之后新增的 tag（需先全量完成）
├── refresh  [同上]                      全量重扫到暂存文件，成功后原子替换
├── status   [--out --state]             查看断点状态与 CSV 概况
├── verify   [--out --state --dups --init-state]   校验 CSV 与状态文件
├── reset    [--out --state --yes]       删除 CSV、状态文件与暂存文件
└── version                              显示版本与运行环境

抓取类命令（fetch / update / refresh）共用参数：

输出约定：逐页进度与日志在 stderr（不污染管道，日志等级带颜色）， status / verify / version 的表格在 stdout；--debug 在任何层级都可用。

[0:12] id   0% pages=13 rows=13,000 rate=1105/s cursor=2730104 eta=41:20  ← stderr，原地刷新
INFO  完成（max_pages）：pages=13 fetched=13,000 written=13,000 …         ← stderr，日志
INFO  状态：rows=13,000 range=[2730104, 2743978] complete=False
INFO  CSV：data/tags.csv

进度行里的 id NN% 是精确进度（已扫过的 id 区间占比，游标降到数据集底部即 100%）； eta= 是估算值，口径分两层：refresh 用上一次快照的行数当总数（行口径，很准）， 全新 fetch 只能按 id 区间线性外推（id 口径，偏保守）—— Danbooru 不提供总数， 且 id 密度极不均匀（实测 4%~96%），详见 docs/design.md。

输出文件

数据源更新了怎么办

update 只追加新 id，无法发现已有行的字段变化（Danbooru 不支持按更新时间过滤， 见 docs/api.md），所以需要准确 post_count 时跑 refresh； 推荐节奏：每天 update，每周 refresh。刷新完成后再跑一次 update 可补齐刷新期间新建的 tag。

故障恢复

开发

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

python -m pytest -q                      # 30 个离线用例
python -m ruff check hanatsumi tests     # lint
python -m ruff format --check hanatsumi tests
python -m ty check hanatsumi             # 类型检查（自动发现 .venv）

许可证

GPL-3.0