booth-vault-toolhub

BOOTH 素材统一管理工具 —— VRChat / XR 创作者的 BOOTH 资产全流程工具链。 用 Rust 统一重写原 Python 双仓库（booth-keeper + booth-free-collector）， 一份引擎同时支撑 CLI / MCP / GUI 三种接口。

鸣谢

• GUI 设计提供：linnnnnnnnnnnnnnnnnnnnn/booth-keeper
• CLI 灵感提供：linnnnnnnnnnnnnnnnnnnnn/booth-free-collector

功能

• 下载：整店爬取 / 散链下载 BOOTH 免费商品（variation 级免费筛选、断点续传、假文件校验、限速防封）
• 整理：本地压缩包文件名含 7 位 ID → 按 ID 取元数据归档（无登录）
• 按名搜索：文件名无 ID 时，清洗生成搜索候选 → 评分选优 → 归档（UnityPackage 资源名二次验真）
• 巡检：文件夹图标三件套（cover.jpg + .folder_icon.ico + desktop.ini）完整性扫描 + 自动修复 + 版本巡检 + 错位纠正
• 自更新检查：GitHub releases.atom feed 取最新版本（成熟库 feed-rs 解析，无 API 配额限流；HTML 重定向/API 作兜底 + 403/429 退避 + 代理直连重试 + 显式超时），CLI/MCP/GUI（设置页「软件更新」入口）三端一致
• 三主题六配色 GUI：朱印（印泥/宣纸）/ 鎏金（金缮/漆）/ 古纹（青铜/青瓷）× 亮 / 暗，形制与色板分开，SVG 母题纹样与素材图。macOS 面板通透走系统 NSGlassEffectView（旧系统回落 NSVisualEffectView），其它平台 CSS backdrop-filter

架构

┌────────────────────────────────────────────┐
│  GUI (Tauri+React)    CLI (clap)   MCP (rmcp) │
│  └─────────────┬───────────────────────────┘ │
│                ▼                             │
│   ┌──────────────────────────────┐           │
│   │         engine crate          │ 分类/清洗/评分/解析/HTTP/归档/巡检 │
│   └──────────────┬───────────────┘           │
│                  ▼                           │
│   ┌──────────────────────────────┐           │
│   │     booth-shell (CLI 入口)     │ 文件夹图标 set/reset/audit │
│   └──────┬───────────────┬───────┘           │
│          ▼               ▼                   │
│   ┌──────────────┐  ┌──────────────┐         │
│   │  shell/win    │  │  shell/mac   │        │
│   └──────────────┘  └──────────────┘         │
└────────────────────────────────────────────┘

crate	目录	职责	平台
engine	engine/	纯函数层 + 网络 + 归档 + 巡检，三端共享单一事实源	三平台
shell-win	shell/win/	属性位 / desktop.ini / ICO / SHChangeNotify（图标三件套）	Windows only
shell-mac	shell/mac/	封面正方形化 + Finder 自定义文件夹图标	macOS only
booth-shell	booth-shell/	文件夹图标 CLI 通用入口（set/reset/audit），按平台分发 shell-win / shell-mac	三平台
booth-mcp	booth-mcp/	MCP stdio server，暴露四工具	三平台
gui	gui/	Tauri v2 + React 19 桌面应用	三平台

快速开始

构建

cargo build --release --workspace
# 产物：target/release/booth、booth-mcp、booth-shell

发布包（安装版/便携版）中 booth / booth-mcp / booth-shell 与主程序 booth-vault-toolhub 同目录（安装版在 C:\Program Files\booth-vault-toolhub\），agent/MCP 直接按此定位，无需另行安装。

MSI/NSIS 安装器均带可选组件页（booth CLI / booth MCP / booth Shell / Add to user PATH， 默认全勾选）：默认把安装目录加入当前用户 PATH（幂等，卸载自动移除）。 主程序每次启动会把自身目录写入用户环境变量 BOOTHVAULT_TOOLHUB（便携版同样生效）， agent 定位工具目录优先读该变量（验证路径存在），再回退 PATH / 常规位置。 macOS：写入 launchctl setenv + ~/Library/LaunchAgents/com.boothvault.toolhub.env.plist， 工具在 .app/Contents/MacOS/。

CLI

booth download <店铺URL|散链> [--cookie ...] [--out DIR]   # 下载免费商品（需 Cookie）
booth intake   <目录...> [--dry-run] [--on-unknown report|move|skip]
               [--on-ambiguous ask|skip|force] [--yes] [--out DIR]  # 混乱目录一键入库
booth mismatch [--base DIR] [--fix] [--id ID]...           # 错位检测；--fix 强制重归档
booth organize <本地包...> [--id ID] [--out DIR]           # 按 ID 整理归档
booth search   <本地文件...> [--id ID] [--base-dir DIR]    # 按名搜索整理
booth audit    [--base DIR] [--dry-run]                    # 图标三件套巡检
booth version-audit [--base DIR] [--fix]                   # 版本巡检；--fix 补免费文件
booth library  [--base DIR]                                # 列出库存
booth update-check [--proxy]                               # 工具自更新检查

• 全局 --json：结构化输出（MCP 依赖）
• 退出码：0 成功 / 1 有失败项 / 2 致命错误
• 每个子命令 --help 有详细说明

GUI

cd gui
npm install
npm run tauri dev        # 开发
npm run tauri build      # 打包

MCP

booth-mcp                # stdio server，暴露 download/organize/search/intake/mismatch/audit/version_audit/library…

客户端配置示例见 skills/booth/mcp.example.json。

Agent 技能（SKILL.md）

技能包在 skills/booth/，可用成熟安装器 skills.sh 安装：

# 从 GitHub 安装
npx skills add VRChatCN-Kipfel/booth-vault-toolhub --skill booth -a opencode -a claude-code

# 或本地仓库直接装
npx skills add ./skills/booth -a opencode -a claude-code

详见 skills/booth/README.md。

克隆仓库

git clone https://github.com/VRChatCN-Kipfel/booth-vault-toolhub.git

配置

配置文件（TOML，用户目录与应用目录两处支持）：

proxy = "http://127.0.0.1:7890"   # 可选；优先级 配置文件 > HTTPS_PROXY > 系统默认
proxy_enabled = true               # false = 强制直连（忽略环境变量/系统代理）
download_root = "D:/BOOTH"         # 归档根目录（不硬编码路径）
rate_limit_secs = 0.8              # 限速秒数（三端统一，防封）
cookie = ""                        # 免费文件下载也需登录；仅用户目录。CLI --cookie / MCP 参数优先

• 用户目录：{config_dir}/booth-vault-toolhub/config.toml（GUI 设置页写入这里，三端共用）
• 应用目录：exe 同目录或 CWD 的 config.toml

目录结构

<归档根目录>/
└── 类目中文tag/
    └── ID_标题/
        ├── ID_标题.ext   原文件（保留原文件名含版本号）
        ├── cover.jpg
        ├── booth.txt           标题/ID/店铺/条款（缺失不计入三件套损坏）
        ├── .folder_icon.ico    (隐藏)
        └── desktop.ini         (隐藏+系统)

开发

cargo build                 # 构建
cargo test                  # 单测
cargo clippy --all-targets --all-features
cargo fmt --check

许可

Apache License 2.0 — 见 LICENSE。

本项目部分逻辑参考并衍生自 linnnnnnnnnnnnnnnnnnnnn 的 MIT 开源项目（见 NOTICE），版权与许可声明在 NOTICE 中完整保留。