nexus3-hf-cache

Imported from xjoker/nexus3-hf-cache (AGENTS.md). Install upstream with npx skills add xjoker/nexus3-hf-cache. Copyright stays with the author.

nexus3-hf-cache

Rust TUI/CLI 工具，用于主动管理 HuggingFace 模型在 Nexus3 proxy 中的缓存。

技术栈

• Rust edition 2024, MSRV 1.85
• tokio + reqwest (async HTTP)
• ratatui + crossterm (TUI)
• rusqlite (SQLite 持久化)
• clap (CLI), tracing (日志), toml (配置)

项目结构

src/
├── main.rs         # CLI 入口 (clap)
├── app.rs          # TUI 应用状态机
├── config.rs       # TOML 配置解析
├── db.rs           # SQLite schema + CRUD
├── models.rs       # 共享数据类型
├── nexus.rs        # Nexus3 REST API 客户端
├── hf.rs           # HuggingFace API 客户端
├── downloader.rs   # 下载引擎 (队列/并发/重试)
└── tui/
    ├── mod.rs      # TUI 事件循环
    ├── ui.rs       # 界面渲染
    └── widgets.rs  # 自定义组件

构建

cargo build --release

运行

# TUI 模式 (默认)
nexus3-hf-cache

# CLI 模式
nexus3-hf-cache init
nexus3-hf-cache add meta-llama/Llama-3-8B --priority 5
nexus3-hf-cache list
nexus3-hf-cache browse
nexus3-hf-cache daemon --once

# 配置验证
nexus3-hf-cache config --validate

配置

• 配置文件: data/config/config.toml
• 数据库: data/nexus3_hf_cache.db
• 环境变量覆盖: NEXUS3_BASE_URL, NEXUS3_REPOSITORY, HF_TOKEN 等

关键约束

• rusqlite Connection 不是 Send/Sync，不能跨 .await 持有
• DB 操作使用 db_update() 或在 block scope 内完成后 drop
• Nexus3 HuggingFace proxy 不支持 Xet 格式文件