quartermaster

Quartermaster

这个项目始于我想做一个大坝原型。

不是什么大项目——一个简短的演示，也许做成了还会继续。动手之前，我想看看自己已经拥有的东西里，哪些能加快进度。于是我在素材库里搜索“dam”：没有任何结果。当然搜不到——没有素材会被称作大坝。但我已经拥有的四个素材包里，分散着弯曲的混凝土网格、水体系统和一些岩石地形。大坝所需的东西全都有。我拥有其中大部分素材已经好几年了，却从未把它们联系起来。

项目开始时，两个商店里的约 1,500 个素材就是这样让我束手无策的——而如今，这个素材库已经扩展到五个生态系统，涵盖超过 7,500 个素材。几乎全都来自捆绑包和促销活动，却没有一件被记在心上。而且不只是我——AI 助手也不知道。向它求助，它要么从头开始构建一切，要么让你去购物，而你硬盘里明明就有价值数百美元、恰到好处的素材。

Quartermaster 会在本地、你的机器上为你索引 Unity Asset Store、Fab、Quixel Megascans、Gumroad 和 Leartes Cosmos 中你拥有的所有素材，并通过 MCP 将它们提供给你的编码 Agent。这就是我当时希望能有的工具：询问大坝，它就会告诉你，你已经拥有弯曲的混凝土网格。

you    →  "I want to build a dam — what do I have to work with?"

agent  →  search_owned_assets(...)        finds the concrete meshes, water FX, terrain
          └─ Nordic Coastal Cliff (Quixel) · 5785 px/m · 2.03 × 2.92 × 2.44 m
             maps: Basecolor, Normal, Displacement, Cavity, AO, Roughness…
          validate_stack([...])           checks none of them fight each other
          import_asset_to_project(...)    unpacks into Assets/, demos stripped

每条结果都是你拥有或可以免费领取的素材——没有任何凭空捏造的内容。

输入描述，而不是名称——这些结果中没有任何一个与查询共享同一个词。

为什么叫 Quartermaster？军需官的职责从来不是记住仓库里有什么，而是在出发时确保你装备齐全。这比“忘记了”更接近真正的问题。我并没有丢失什么；我知道自己拥有一些东西。但我没法在不先花一小时翻找的情况下，从“我想做一个大坝原型”直接找到“打开这四个素材包”——而“也许做成了还会继续”这种想法，根本经不起一小时的翻找。以这种方式萌生的想法不会被否决，只会悄无声息地不了了之，你永远也不会知道它们原本能否实现。

索引内容

来源	收录内容	方式
Unity Asset Store	已拥有的素材包、描述、图库图片	经过身份验证的采集
Fab（Epic）	已拥有的 Unreal 和 Unity 商品	经过身份验证的采集
Quixel Megascans / Megaplants	素材目录，包含纹素密度、扫描面积和贴图列表	同步公开目录
Gumroad	已拥有的商品	经过身份验证的采集
Leartes Cosmos	已拥有和可领取的 Cosmos 素材库，包含丰富的截图图库（平均 18 张，最多 71 张）	经过身份验证的采集

所有内容都会存入同一个 SQLite 表，并通过同一个搜索界面提供，因此一次查询就能同时搜索所有来源。如果两者都能回答问题，Megascans 表面素材和 Unity 着色器就会在同一个查询中返回，不受引擎限制。

没人告诉你的部分

两家商店都不会告诉你自己拥有什么。

Unity 移除了 /account/purchases（自 2026 年 8 月起返回 404）。Fab 没有所有权 API、没有导出按钮，什么都没有。你的购买记录只存在于它们的私有 GraphQL 中，受 SSO、MFA 和机器人检测保护。

要访问这些记录，我们尝试了四次，其中三次都失败了：

1. Playwright 自带的 Chromium — Epic 的验证码直接拒绝它（提示“请启用 JavaScript”）。
2. 用 Playwright 驱动你的真实浏览器 — 会注入可检测的钩子；Epic 会在密码验证后再加一道安全屏障。
3. 登录期间连接调试器 — 结果相同。任何触及登录流程的操作都会触发标记。
4. 真正有效的方法：完全停止自动化登录。你通过普通浏览器窗口登录——不启用调试端口，你和商店之间也不加任何东西——因为触发风险系统的正是自动化本身。只有在你完成登录后，Quartermaster 才会连接到你亲自建立的会话，并重放商店自己的分页查询——使用它自己的 CSRF 标头，并按它自己的方式分块（每个请求 42 个 ID，因为这就是 Unity 客户端发送的数量）。

这个技巧构成了本项目的大部分。相比之下，其余部分——搜索、检查和解包——说实话都很简单。

设计中融入了两条来之不易的规则，如果你以后想自己动手修改：

• 必须正常关闭浏览器（使用 taskkill，不带 /F）。强制终止会丢失 Unity 的设备信任 Cookie，今后的每个会话都会要求进行 MFA 验证。
• 切勿在无头模式下获取资源库内容。即使 Cookie 有效，无头模式也会触发 Unity 的风险系统。

Quixel Megascans，以及为什么你的 Fab 资源库看起来不全

Fab 的资源库视图和 Megascans 目录并不是同一份清单，也没有导出功能能将两者对齐——你拥有的 Megascans 内容使用权可能远多于资源库页面显示的内容。不管原因是什么，实际结果都一样：你只能不断滚动、手动搜索自己早已拥有的内容。

Quartermaster 绕过了这个问题。它直接从 Fab 同步 Quixel Megascans 和 Quixel Megaplants 卖家目录——截至撰写本文时共有 5,580 个条目——而不依赖资源库视图显示的内容，并将它们与其他所有自有内容一并归档，按状态标记：

• vault_owned — 已在你的资源库中
• catalog_grant — 可依据 Epic Content License 免费领取，但尚未获取

两类内容都可以搜索，每条结果都会标明所属类别，因此 Agent 无需猜测，就能分辨“你拥有这个”和“你可以免费领取这个”。

Megascans 条目还会包含商品页面公布的实物规格——纹素密度、扫描面积和贴图列表（底色、法线、置换、凹陷、AO、粗糙度……）。这就是 Agent 只告诉你找到了“一块岩石”，和告诉你找到的是“一块扫描尺寸为 1×1 m、分辨率为 8192 px/m 且带置换贴图的岩石”之间的区别——而这正是决定它是否可用的关键。

python -m src.store_client sync-quixel      # catalog
python -m src.store_client enrich-quixel    # texel density, scan area, maps

你将获得什么

理解意图与视觉的搜索。 这是水坝问题。

• 通过 SQLite FTS5 搜索精确关键词。
• 通过本地 ONNX 文本嵌入（BAAI/bge-small-en-v1.5）理解自然语言意图——搜索 “用于蓄水的混凝土结构”，就能找到描述中从未提及水坝的网格和着色器。
• 通过 ONNX CLIP 嵌入（Qdrant/clip-ViT-B-32）实现跨模态视觉理解——搜索 “哥特式大教堂”，会直接为你的截图和宣传渲染图打分，即使资源的文字描述完全没有相关内容，也能找到它们。视觉匹配结果还会告诉你匹配的是哪张截图，而不只是封面图。
• 每条结果都会说明匹配依据。 每条命中结果都带有 match 字段——keyword、semantic+vision、keyword+semantic+vision——让你和你的 Agent 都能看到触发了哪些信号。对于描述毫无用处的资源，纯视觉命中与精确标题匹配是两种不同类型的结果，因此应当清楚标示。
• 从截图中提取概念标签。 离线视觉处理会根据视觉词汇表为每张图库图片打分，并将筛选出的标签写回 FTS 索引，因此，“中世纪村庄”和“黑暗恐怖氛围”也能成为可搜索关键词，即使资源描述从未提及它们。词汇表是可替换的 JSON 文件——请参阅 docs/concepts.md。

这三种信号通过 CPU 上的 三路倒数排名融合（RRF） 进行融合。无需 GPU、向量数据库进程或云端 API——ONNX Runtime 和 numpy 矩阵都在同一进程中运行。

在约 7,500 个资源的资源库上测得：两个模型常驻时峰值内存约为 520 MB，首次查询约需 1.4 秒（加载 BGE 和 CLIP），之后预热查询约需 85 毫秒。模型采用延迟加载，因此从不搜索的 Agent 无需承担它们的开销。

了解磁盘上的实际情况。 扫描 %APPDATA%/Unity/Asset Store-5.x/ 和 Epic 的 VaultCache，让每条结果都能标明资源是否已下载，或仅存于云端。Agent 会优先选择本地资源——无需下载即可导入的资源，胜过 4 GB 的下载项。

用于检查资源组合的检查器。 两个植被渲染器会互相冲突。没有 MicroSplat 核心模块的 MicroSplat 模块会悄无声息地失效。仅适用于 URP 的着色器在 HDRP 项目中会显示为粉色。Quartermaster 会在你为此耗费一下午之前发现这些问题。

直接解包。 将缓存的 .unitypackage 文件直接解压到 Assets/，并在导入时剔除 /Demo/、/Samples/、/Documentation/ 和 PDF 文件——通常可让每个包减少 60–80% 的冗余。所有声明的路径都会被规范化，并确保位于 <project>/Assets/ 内；路径逃逸在结构上不可能发生，而不仅仅是被过滤。

安装

独立版安装包——从 Releases 下载 Quartermaster-windows-x64.zip，解压到任意位置。无需安装 Python。

• Quartermaster.exe——桌面 GUI，支持 Win+Alt+V 聚焦搜索、商店资源采集、库浏览和直接解包。
• Quartermaster-mcp.exe——独立的 MCP stdio 服务，可供 Claude Desktop、Cursor、Antigravity 和 Windsurf 使用。

你的库数据会安全地存放在 %LOCALAPPDATA%\Quartermaster 中，因此升级时只需替换文件夹，不会丢失数据。

从源代码安装——需要 Python 3.10+。

git clone https://github.com/Tanshaydar/Quartermaster.git
cd Quartermaster
pip install -r requirements.txt

初始化你的库：

1. 登录。 这是唯一需要你亲自操作的一步。系统会打开一个普通浏览器窗口；双重验证和验证码的处理方式与平时完全相同。完成后关闭浏览器，登录会话会保存在本地。

python -m src.store_client login unity
python -m src.store_client login fab
python -m src.store_client login gumroad     # optional
python -m src.store_client login cosmos      # optional — Leartes Cosmos

2. 采集并补充信息。 任务可能运行较长时间，支持恢复，也可以安全地重复运行——每次都会从上次停止的位置继续。

python -m src.store_client fetch unity
python -m src.store_client fetch fab
python -m src.store_client fetch gumroad     # if you signed in above
python -m src.store_client fetch cosmos      # if you signed in above
python -m src.store_client sync-quixel       # Megascans/Megaplants catalog — no login needed
python -m src.store_client enrich            # descriptions and cover art, politely batched
python -m src.store_client enrich-quixel     # Megascans scan specs
python -m src.store_client fab-deep-media    # Fab only: plain HTTP is 403'd, galleries need the authed browser

3. 构建本地索引，然后扫描磁盘。

python -m src.semantic build     # text embeddings
python -m src.vision build       # screenshot embeddings + concept tagging
python -m src.local_scan         # which of them are already downloaded here

semantic build 和 vision build 能让你的资源支持搜索 “用于挡水的混凝土结构” 这类查询和视觉概念查询。跳过这两步，搜索仍然可用，但只能匹配精确关键词。

请在已有目录之后再运行 local_scan，而不是提前运行。若对空资源库进行扫描，由于没有可用于匹配文件名的内容，每个缓存包都会被单独登记为一个空条目。此操作没有危害——下一次扫描会将它们与实际目录对应起来——但在此之前，你会看到重复条目。

已经有商店导出的 CSV 文件？可以完全跳过浏览器：

python -m src.ingest             # eats any CSVs in data/seed/
python -m src.semantic build     # still needed — see the note above
python -m src.local_scan         # then find what's already on disk

连接你的 Agent：

选项 A：自动注册（一条命令）

# Standalone binary users:
Quartermaster-mcp.exe --register --all

# Source users:
python -m src.register --all             # Claude Desktop, Cursor, Windsurf, Antigravity
python -m src.register --all --dry-run   # look before you leap

注册时会合并现有客户端配置，并先创建 .quartermaster-backup。不会覆盖你的其他服务。

选项 B：手动配置 将服务配置块粘贴到客户端配置中：

独立二进制文件：

{
  "mcpServers": {
    "quartermaster": {
      "command": "C:/path/to/Quartermaster/Quartermaster-mcp.exe",
      "args": []
    }
  }
}

从源代码安装：

{
  "mcpServers": {
    "quartermaster": {
      "command": "python",
      "args": ["-m", "src.mcp_server"],
      "cwd": "C:/path/to/Quartermaster"
    }
  }
}

Claude Desktop 从 %APPDATA%/Claude/claude_desktop_config.json 读取配置，Cursor 使用 ~/.cursor/mcp.json，Windsurf 使用 ~/.codeium/windsurf/mcp_config.json。

说明

首次运行时的模型预热： 首次进行自然语言搜索或视觉搜索时，ONNX Runtime 会下载并在本地缓存嵌入模型（BAAI/bge-small-en-v1.5 和 clip-ViT-B-32）（约 150 MB）。加载到内存时，第一次查询可能需要 3–5 秒；之后每次查询约需 100 毫秒。

Agent 工具

工具	可回答的问题
search_owned_assets(query, ...)	我拥有哪些符合要求的资源？支持关键词与语义混合搜索。
get_asset_details(asset_id)	完整元数据、使用说明、图库和商店 URL。
get_stack_recommendations(brief)	根据功能简介推荐你拥有的资源包。
validate_stack(asset_ids)	这些资源会互相冲突吗？检查角色冲突和缺失的前置条件。
list_stack_recipes()	根据 你的 资源库筛选出的精选生产资源栈。
audit_project(project_dir)	检查目标项目的引擎、版本和渲染管线。
import_asset_to_project(asset_id, project_dir)	将本地资源包解包到 Assets/（将捆绑的 UPM 包解包到 Packages/）。
list_asset_categories()	按类别统计并展示数量。
get_vault_stats()	按来源和类别统计总量，并区分本地与云端。

通过两个文件即可让 Quartermaster 识别你自己的术语，无需修改代码：

• data/recipes.json——角色、前置条件和精选资源栈。冲突检查器会依据此文件进行判断：哪些资源争用同一用途、哪些资源依赖其他资源，以及你认可哪些资源组合。
• data/concepts.json——CLIP 用于评估截图的视觉词汇表。随附列表面向游戏；如果你从事建筑可视化或预演，可替换该列表并重新构建。

这两个文件都是运行时读取的普通 JSON 文件，并且在 docs/ 下都有对应的参考页面。

其他使用方式

• 桌面应用（run_desktop.bat）——带托盘图标的 PySide6 聚焦搜索；在 Windows 的任意位置按 Win+Alt+V。它会与 Agent 并行运行，不会妨碍 Agent——数据库以 WAL 模式运行，因此 GUI 写入时 Agent 搜索不会互相阻塞。

  不过，它不只是搜索栏，尽管这是你最常用的功能：

  • 在任意结果上按 空格键，即可像 Finder 一样查看全尺寸预览。详情窗格最多可显示 24 张图库图片，并在后台解码和缓存。
  • Megascans 条目会直接显示扫描规格——纹素密度、实际尺寸、PBR 贴图列表——让你无需打开商店页面，也能分辨 5785 px/m 的悬崖资产和 1 m 的平铺表面。
  • 在资源管理器中显示、解包到 Unity（使用与 MCP 工具相同的沙盒和示例内容剥离机制），以及复制上下文，可将资源的标题、发布者、渲染管线、格式、规格和磁盘路径整理成纯文本块，直接粘贴到聊天中。
  • 可按来源（Unity、Fab、Quixel、Gumroad、Cosmos）、渲染管线（HDRP、URP、Built-in）筛选，也可只显示已在磁盘上的内容。
  • 登录、采集和 Quixel 同步都可在此处执行，并显示实时进度和预计剩余时间，而且都支持续传。

• Web UI（run_ui.bat）——深色模式仪表板，地址为 http://localhost:7890。

• 在 Unity 中使用——导入 editor_bridge/Quartermaster-Bridge.unitypackage，然后选择 Window > Quartermaster。无需离开编辑器即可搜索和导入。补充说明：该桥接包由 src/build_bridge.py 生成，它写入的 tar 格式与 unpacker.py 读取的格式相同。这是刻意用于自我验证的。

安全性

此工具会保存商店会话并写入你的项目，因此会认真对待本地 API 的安全性：

• 每个会更改状态的端点都需要令牌（首次运行时生成，存储在 data/.auth_token，并为 Unity 桥接同步一份）。通过 X-Quartermaster-Token 或 Authorization: Bearer 发送；Web UI 会自动获取 SameSite=Strict Cookie。
• 即使令牌有效，也会拒绝跨源请求。
• 解包器沙盒会折叠 .. 路径段、剥离驱动器号和控制字符，将 Assets/ 之外的内容移至 Assets/_Quartermaster_Imported/ 下（格式正确的内嵌 UPM 包除外；此类包会被限制在自己的 Packages/<name>/ 文件夹中），并断言最终路径位于项目内——这由测试强制保证，而不是凭感觉（python run_tests.py -v）。
• 图像代理会通过域名允许列表进行限制，屏蔽私有地址段和元数据端点，重新验证每一次重定向，限制大小，并在缓存超过文件数上限后清理最旧的条目。

不会有任何数据回传。你的素材库、嵌入向量、磁盘路径和商店会话都会保留在这台机器上。

配置

config.json 中的可选键（首次运行时创建）：

键	默认值	用途
server_port	7890	Web UI / API 端口。
embedding_model	BAAI/bge-small-en-v1.5	任意兼容 fastembed 的模型。更改后需重建索引。
fab_vault_dirs	自动检测	覆盖 Fab VaultCache 位置。
strip_dirs / strip_exts	示例、文档、PDF	解包器要丢弃的内容。
enrich_batch_size / enrich_batch_pause	20 / 3s	丰富处理的请求节流设置。
media_cache_enabled	true	用于代理封面图的磁盘缓存。

已知限制

• 优先支持 Windows，也支持 Linux。 Windows 是经过测试的平台，Win+Alt+V 热键仅适用于 Windows。我们提供 linux-x64 构建版本，磁盘扫描也会查找 Linux 和 macOS 的缓存目录，但这些平台的使用量远不及 Windows。没有 macOS 构建版本。
• 一台机器，一个用户。 不支持同步，也没有服务模式。这是有意为之。
• 采集依赖抓取。 Unity 和 Fab 随时都可能更改内部实现，而且确实改过——这里的分块大小、端点和 GraphQL 结构仅在我发布当天准确，不保证以后一直如此。如果获取结果为空，data/store_harvest.log 会记录看到的每个 JSON 响应；排查问题可以从这里开始。
• 分类体系是启发式的。 类别根据词边界词元、商店标签，以及从截图中进行的零样本 CLIP 视觉概念挖掘，通过多模态方式推断。没有截图的高度风格化商品默认归入 Tools & Utilities，不过无论分配了什么类别，语义向量搜索和混合搜索始终会覆盖整个资源库。如何调整视觉词汇已记录在 docs/concepts.md 中。
• 索引仅覆盖资源包边界，商店元数据也很嘈杂。 搜索范围包括标题、描述、标签，以及图库截图的整图 CLIP 嵌入。它有两项结构性限制：
  1. 不索引内部资源： 不会解压归档文件并索引单个子网格、预制件或内部文件名（例如，在模块化环境资源包中搜索“pantile”或“curved concrete riser”等特定建筑子元素时，除非这些内容在商品介绍文字中有说明，或在图库渲染图中十分显眼，否则搜索不会命中）。
  2. 商店模板文案空洞无物： 相当一部分商店商品介绍（尤其是 Unity 的模板化 og:description）只有纯营销套话（“Elevate your workflow with...”），不含任何技术信息。视觉 CLIP 嵌入正是为了弥补这一点，但整图向量并非总能识别细粒度的子元素。
• 仅支持解包 Unity 资源。 Fab 资源可以编入索引并进行搜索，但显然不适用 .unitypackage 解包。

遇到问题时

请提交一个 issue。这是一个个人项目，所以我无法保证响应时间，但我确实会阅读这些问题。

根据症状，以下信息会有所帮助：

• 获取结果为空或内容不全。 这最可能是出问题的地方，因为商店会悄无声息地更改内部实现。data/store_harvest.log 会记录采集过程中看到的每个 JSON 响应——查看文件末尾就能了解完整诊断信息。请附上该文件。
• 搜索结果毫无用处。 先检查 python -m src.vision status。如果索引尚未构建，系统会悄悄退化为仅使用关键词搜索；大多数“搜索坏了”的反馈都是这个原因。
• 类别错误，或实际上并不存在的冲突。 这通常是知识库的问题，而不是代码问题——docs/recipes.md 和 docs/concepts.md 介绍了如何自行修复；如果你提交针对 data/recipes.json 的 PR，提供我无法用自己的资源进行测试的规则，我们也由衷欢迎。
• 独立版本无法启动。 它以 --windowed 模式运行，因此会静默失败。日志位于 %LOCALAPPDATA%\Quartermaster\data\crash.log。

如果你用它做出了很酷的东西，我真的很想听听。

关于各商店的说明

Quartermaster 会通过你自己登录的浏览器，在你自己的机器上读取你自己的账户。它不保存任何凭据，不会向我的任何服务器发送数据，也没有遥测功能——会话保存在本地浏览器配置文件中，资源库则保存在本地 SQLite 文件中。不存在可能泄露数据的共享后端。

本项目与 Unity Technologies、Epic Games、Gumroad 或 Leartes Studios 无关联，未获得其认可，也未与其建立联系。Unity、Unity Asset Store、Fab、Unreal Engine、Quixel、Megascans、Gumroad、Leartes 和 Cosmos 均为其各自所有者的商标。是否根据相关服务的条款自动访问任何服务，由你自行决定；本工具不会替你做决定。

许可证

MIT。请参阅 LICENSE。