Quartermaster

这个项目的起因，是我想为一座水坝做一个原型。

不是什么严肃的事——就是一段短演示，也许效果不错的话还会继续。在动手构建任何东西之前，我想看看自己已经拥有哪些能加快进度的东西。于是我在资源库里搜索“水坝”：什么也没有找到。当然什么也找不到——没有任何资源的名字叫“水坝”。但在我已经拥有的四个包里，分散着弧形混凝土网格、一套水体系统、一些岩石地形。水坝需要的一切都在其中。这些东西我大多已经持有多年，却从未把这些碎片拼起来过。

这就是在两家商店拥有约 1,500 个资源带来的后果。其中几乎全部来自捆绑包和促销，没有一样被记住。而且不只是我——任何 AI 助手也都不知道。你向它求助时，它要么从零开始造一切，要么让你去买，而恰好合适、价值数百美元的东西就静静躺在你的磁盘上。

Quartermaster 会在本地为你的整个 Unity Asset Store 和 Fab 资源库建立索引，并通过 MCP 把它提供给编码代理。这正是那天我希望已经存在的工具：问起水坝，它会告诉你，你早就拥有弧形混凝土网格。

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
          validate_stack([...])           checks none of them fight each other
          import_asset_to_project(...)    unpacks into Assets/, demos stripped

每一条结果都是你已经付过钱的东西。没有什么是凭空捏造的。

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

为什么叫 Quartermaster？军需官的职责从来不是记住仓库里有什么——而是确保在行动时你已经装备齐全。这比“遗忘”更接近真正的问题。我并没有丢失任何东西；我知道自己拥有 一些东西。我做不到的是，在不先花上一个小时翻找的情况下，从“我想做一个水坝原型”走到“打开这四个包”——而 如果效果不错也许还会继续 经不起一个小时的翻找。以这种方式到来的想法不会遭到拒绝，它们只是悄无声息地没有发生，而你永远不会知道它们原本是否能够成真。

没人告诉你的部分

两家商店都不会承认你拥有什么。

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 客户端就是这么发的）。

这个技巧构成了这个项目的大部分。其余部分——搜索、lint 检查、解包——相比之下确实直截了当。

如果你打算自己动手改造，有两条来之不易的规则已经内建在设计之中：

• 浏览器必须优雅地关闭（taskkill 不带 /F）。突然终止会丢失 Unity 的设备信任 Cookie，之后每次会话你都会被要求进行 MFA 验证。

• 绝不要在无头模式下运行资源库抓取。即使 Cookie 有效，无头模式也会触发 Unity 的风控系统。

Related MCP server: Unity API Communicator MCP Server

你能得到什么

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

• 精确关键词：基于 SQLite FTS5。

• 自然语言意图：基于本地 ONNX 文本嵌入（BAAI/bge-small-en-v1.5）——“用于挡水的混凝土结构” 能搜出那些清单里从未提到水坝的网格和着色器。

• 跨模态视觉理解：基于 ONNX CLIP 嵌入（Qdrant/clip-ViT-B-32）——搜索 “哥特式大教堂” 会真正对你的截图和宣传渲染图打分，即使它们的文本描述只字未提，也能找到这些资源。 所有三种信号在你的 CPU 上通过 3 路倒数排名融合（RRF） 融合。没有 GPU、没有向量数据库进程、没有云 API——只有 ONNX Runtime 和一个 numpy 矩阵，与所有其他逻辑处于同一进程中。

在一个约 1,800 个资源的库上实测：两个模型常驻时 峰值内存约 480 MB，首次查询约 1.5 秒（加载 BGE 和 CLIP），之后 热查询约 110 ms。模型按需懒加载，所以从不搜索的代理永远不需要为它们付出代价。

你磁盘的真实状况。 扫描 %APPDATA%/Unity/Asset Store-5.x/ 和 Epic 的 VaultCache，因此每条结果都知道自己已下载还是仅云端。代理更喜欢本地资源——零下载的导入胜过 4 GB 的导入。

面向资源组合的 lint 检查器。 两个植被渲染器会互相冲突。没有核心 MicroSplat 的 MicroSplat 模块会悄无声息地什么都不做。仅支持 URP 的着色器放进 HDRP 项目会渲染成粉色。Quartermaster 能在你为它们耗掉一个下午之前就发现这些问题。

直接解包。 将缓存的 .unitypackage 文件直接解压到 Assets/，过程中丢弃 /Demo/、/Samples/、/Documentation/ 和 PDF——每个包通常减少 60–80% 的冗余体积。每个声明的路径都会被规范化并强制限定在 <project>/Assets/ 内；路径逃逸在结构上就不可能，而不仅仅是被过滤。

安装

独立捆绑包——从 发布页 下载 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

2. 采集并丰富。 运行时间长、可断点续跑、可安全重复运行——每次都会从上次停止的地方继续。

python -m src.store_client fetch unity
python -m src.store_client fetch fab
python -m src.store_client enrich            # descriptions and cover art, politely batched
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

连接你的代理：

选项 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。

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

代理工具

有两个文件可以让你教给 Quartermaster 你自己的词汇，无需修改代码：

• data/recipes.json——角色、前置依赖和精选组合。这就是冲突检查器推理的依据：哪些资源竞争同一个职责、什么需要什么、以及哪些组合被你视为已知可用的组合。

• data/concepts.json——CLIP 用来对你的截图打分的视觉词汇表。随附的列表是面向游戏形态的；如果你做的是建筑可视化或预演，请替换它并重新构建。

两者都是在运行时读取的纯 JSON，并且都在 docs/ 下有参考页面。

其他使用方式

• 桌面应用（run_desktop.bat）——PySide6 聚光灯搜索，带托盘图标；在 Windows 任意位置按 Win+Alt+V。它与你的代理并行运行而互不干扰——数据库以 WAL 模式运行，因此 GUI 写入时你的代理搜索不会阻塞任何一方。

• Web UI（run_ui.bat）——位于 http://localhost:7890 的深色模式仪表盘。

• 在 Unity 中——导入 editor_bridge/Quartermaster-Bridge.unitypackage，然后执行 Window > Quartermaster。无需离开编辑器即可搜索和导入。顺带一提：这个桥接包由 src/build_bridge.py 生成，它写出的正是 unpacker.py 所读取的同一种 tar 格式。这是有意为之的“吃自己的狗粮”。

安全

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

• 每个改变状态的端点都需要一个令牌（首次运行时生成，存储在 data/.auth_token 中，并为 Unity 桥接器镜像一份）。通过 X-Quartermaster-Token 或 Authorization: Bearer 发送；Web UI 会自动获得一个 SameSite=Strict cookie。

• 即使携带有效令牌，跨源请求也会被拒绝。

• 解包沙箱会折叠 .. 段，去除盘符和控制字符，将 Assets/ 之外的任何内容重新定位到 Assets/_Quartermaster_Imported/ 下，并断言最终路径位于项目内部——这是由测试强制保证的，而不是靠感觉（python run_tests.py -v）。

• 图片代理采用域名白名单，阻止私有网段和元数据端点，对每次重定向跳转重新验证，限制大小，并在缓存超过文件上限时清理最旧的条目。

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

配置

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

坦诚的局限性

• **Windows 优先。**缓存扫描假定使用 Windows 路径。MCP 搜索在任何地方都能用；本地导入检测则不行。

• **单机、单用户。**没有同步，没有服务器模式。这是有意为之。

• **采集即爬取。**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，也未获得它们的认可，与它们没有任何关联。Unity、Unity Asset Store、Fab 和 Unreal Engine 是其各自所有者的商标。是否自动化访问任何服务，需要你自己根据该服务的条款来决定，这个工具不会替你作出决定。

许可证

MIT。参见 LICENSE。