MakerShelf 是原生 SwiftUI macOS 模型管理应用。将 MakerWorld 中文站、国际站的模型文件、介绍与图片归档到本机，也可以添加、编辑和整理自己的模型。
前往 MakerShelf 2.1 Release 查看版本说明与可用下载。
- 系统要求：macOS 14 或更新版本，支持 Apple Silicon 与 Intel。
- 自动发布资产：
MakerShelf-2.1-unsigned-macOS.zip，附带 SHA-256 校验文件；资产在发布工作流成功后提供。 - 当前自动构建未经过 Developer ID 签名和 Apple 公证，macOS 可能限制直接打开；也可从源码运行。
- 完整更新记录见 CHANGELOG。
| 功能 | 说明 |
|---|---|
| 模型库 | 网格 / 列表浏览，搜索、来源、作者、分类与归档状态筛选，支持排序和分页 |
| 模型详情 | 图片与完整图文介绍、模型文件、归档信息、来源链接；窄窗口使用详情弹窗 |
| 站点导入 | 单模型链接、当前账号收藏 / 发布内容、指定作者的公开作品 |
| 本地模型 | 拖放或选择文件，新建与编辑资料、模型文件、封面和展示图片 |
| 归档恢复 | 更新或重装后重新选择原 MakerShelf 归档目录，恢复模型、封面和文件关联 |
| 下载管理 | 进度、暂停、继续、取消与重试；同来源去重、并发上限和下载摘要 |
| 文件预览 | 3MF 包内图片，STL / OBJ 静态几何预览；支持放大与失败重试 |
| 图片归档 | 展示图优先压缩为最长边 1600 像素的 WebP，失败回退 JPEG 或原文件 |
| 运行日志 | 本地保存，支持级别、模块、关键词和本次运行筛选，以及复制、导出与清空 |
| 账号与偏好 | 双站点独立登录，钥匙串保存登录状态；归档目录、首选格式、并发与预览预算自动保存 |
- 在「设置 → 存储与下载」选择归档目录。
- 在「设置 → 站点账号」打开需要使用的站点登录页，完成官方登录。
- 点击「添加模型」，粘贴模型链接、读取账号内容，或选择「本地模型」添加自己的文件。
- 确认清单并加入下载队列；完成后可在模型库查看，或直接在访达中打开归档。
指定作者支持用户名、@用户名、数字 ID 和主页链接。公开模型及作者作品可先预览清单；当前账号收藏和部分文件下载需要对应站点登录。
本地导入会复制文件，不移动来源文件。可以选择 3MF / STL / OBJ 预览作为封面，也可以添加自己的展示图片；第一张展示图片作为封面。已归档模型支持从详情底部或卡片菜单进入编辑页，修改资料、图片和文件。
| 格式 | 保存原文件 | 应用内预览 |
|---|---|---|
| 3MF | 支持 | 读取包内打印盘或缩略图片 |
| STL | 支持 | 二进制 / ASCII 完整网格静态预览 |
| OBJ | 支持 | 单色网格静态预览，不读取材质与纹理 |
| STEP / STP | 支持 | 暂不支持，显示格式占位 |
| GCODE / AMF | 支持 | 暂不支持，显示格式占位 |
每个文件只展示自己的预览，不借用模型封面；更换文件后会刷新预览。STL / OBJ 使用固定视角，自动居中并提供多方向光照，优先输出 960 × 720 图片，预算充足时使用超采样抗锯齿。复杂模型依预算降低分辨率，不通过抽面生成缺失表面的图片。
在「设置 → 存储与下载 → STL 静态预览」调整候选像素预算和最长处理时间。已有图片可点击「按当前设置重新生成」，失败时可点击「重试预览」。STL 分块读取完整网格，大文件会增加处理时间；最低分辨率仍超预算或超时时会显示占位并记录原因。OBJ 限制为 64 MiB、50 万三角面、单面 1,024 顶点，凹多边形需要先三角化。
3MF 无有效包内图片、损坏、加密或超出读取限制时无法生成预览，不影响原文件保存。预览缓存最多保留 128 项，不写入来源模型目录。已保存的展示封面不会随临时预览自动替换。
在线模型和本地模型分别归档到以下目录：
归档目录/
├── 站点/作者_ID/模型名_ID/
└── 本地模型/模型名_ID/
├── models/
├── images/
├── description.html
└── metadata.json
模型库索引和偏好保存在本机，重启后保留。来源文件之后发生变化不会自动同步，可进入编辑页替换文件并保存。保存编辑时先建立完整临时归档，成功后再替换原归档。
此功能从 2.1 开始提供。
模型文件保存在你选择的归档目录里，模型列表索引和目录授权则保存在应用的本机数据中。如果更新、重装或更换构建后模型库为空，不必重新导入或下载全部模型：
- 点击空模型库中的「找回已有模型」，或打开「设置 → 存储与下载」。
- 在「找回已有模型」中点击「选择原目录并恢复」，选择以前的归档总目录，即包含「本地模型」「中文站」或「国际站」的目录，不要选择单个模型文件夹。
- 等待扫描完成，查看新增、更新、已存在数量和恢复提示，再点击「查看模型库」。已经选择了正确目录时，可直接点「扫描当前目录」。
恢复读取各模型的 metadata.json、models/、images/ 和 description.html，保留模型 ID、来源、作者与资料，并按实际位置重建文件和图片路径。原文件不复制、不移动、不改写；同一 ID 合并，重复恢复不会生成重复卡片。原目录整体搬家后，也可以选择新位置恢复。
兼容旧版站点下载的精简资料与本地模型的完整资料。旧资料没有保存的分类、材料等信息，优先从现有索引保留；原索引也丢失时使用默认值并给出提示。后续新下载会在归档中保存完整资料。
启动时，如果目录授权仍有效而索引为空或无法读取，会自动尝试恢复一次；如果授权丢失，需要通过系统目录选择器重新授权。损坏的索引会先备份再重建，无法备份则停止恢复。缺失、损坏、重复 ID 或无法读取的模型会给出提示；没有有效 metadata.json 的普通文件夹不属于此恢复入口，仍需通过「添加模型 → 本地模型」整理。
遇到下载、登录或预览问题时，打开「运行日志」，按模块、关键词与「仅本次运行」筛选，展开记录查看原因。预览失败可先点击文件行的「重试预览」；账号页提示持久保存失败时，可点击「重新保存登录状态」。
日志仅保存在本机，不会自动上传；支持复制单条记录和导出筛选结果。日志会过滤常见凭据与网址查询参数，但仍可能包含文件名和错误详情，分享前请检查内容。「清空」删除全部本地日志，而不只是当前筛选结果。
- 使用 Xcode 15 或更新版本打开
MakerShelf.xcodeproj。 - 选择共享 Scheme MakerShelf，运行目标为 My Mac。
- 启动后在设置中选择归档目录并连接需要使用的站点。
工程内置 ThirdParty/libwebp 本地 Swift Package，无需在线拉取该依赖。其许可随源码及应用资源分发。自动发布安装包由 GitHub Actions 构建。
在仓库根目录执行，本地打包需要完整 Xcode：
# 构建当前工程版本，生成 Apple Silicon / Intel 通用安装包
bash scripts/package.sh
# 只检查发布准备情况并显示计划，不创建标签或推送
bash scripts/release.sh
# 正式推送当前分支和版本标签，触发 GitHub Actions 构建及发布
bash scripts/release.sh --push打包产物位于 dist/：MakerShelf-版本-unsigned-macOS.zip 与同名 .sha256；构建日志保存在 build/logs/。安装包包含 App、LICENSE 和 NOTICE，未经过 Developer ID 签名或 Apple 公证。本地和 GitHub Actions 共用同一个打包脚本。
构建与登录辅助程序签名固定使用 Apple 工具入口，避免 Anaconda 等环境中的同名命令导致 Compile Login Helper 失败。
发布前需自行更新工程版本号与构建号、填写 CHANGELOG 正式版本条目和 .github/release-notes/v版本.md，并完成提交。发布脚本默认使用 origin 和 main，不会自动提交或覆盖已有远端标签。发布新版本时应递增版本号，不复用已有标签。参数、步骤和失败处理见发布流程。
MakerShelf.xcodeproj/ Xcode 工程与共享 Scheme
MakerShelf/
App/ 应用入口与路由
Domain/ 领域模型
Services/ 站点请求、归档、图片、预览与日志
Stores/ 页面状态与业务协调
Views/ 原生界面
Resources/ 应用图标、图片与示例数据
ThirdParty/libwebp/ WebP 源码与许可
scripts/package.sh 本地与自动发布共用的打包脚本
scripts/release.sh 发布检查、标签与推送脚本
.github/images/ README 界面图片
.github/release-notes/ 版本发布说明
.github/workflows/ 自动发布工作流
docs/功能梳理.md 功能职责与边界
docs/发布流程.md 版本、打包与发布流程
⌘N：添加模型。⌘K：进入模型库并聚焦搜索。⌘,：打开设置。
- MakerWorld 没有公开稳定的开发者 API，站点调整可能影响导入与下载。
- 付费、积分、地区和版权限制由站点决定，应用不会绕过访问限制。
- 指定作者仅支持公开发布的作品，不支持读取他人的收藏列表。
- 下载队列暂不跨应用重启恢复，已归档文件与模型库索引会保留。
- 当前没有断点续传校验值；继续任务时跳过已存在的本地文件。
- STL / OBJ 为静态图片，不支持旋转、测量或交互式三维查看；复杂模型的效果与性能需在目标设备确认。
MakerShelf 是独立社区项目，与 Bambu Lab 或 MakerWorld 没有关联，也未得到其官方认可。使用者应遵守站点条款、模型作者许可及所在地法律。
项目采用 Apache License 2.0，归属信息见 NOTICE。欢迎阅读贡献指南、行为准则、安全策略、功能梳理和发布流程，再提交 Issue 或 Pull Request。