Slicewise

Slicewise — 面向 Bambu Studio 的打印前决策与审计 MCP 服务

English | 繁體中文

https://github.com/user-attachments/assets/76e04c37-36cf-41d4-abff-4d0e62fe6b4f

Slicewise 让 Claude Code、Codex、Gemini CLI 或任何其他 Model Context Protocol 客户端能够使用 Bambu Studio 的预设、切片器和模型检查功能：在打印前判断模型是否会打印失败，决定要更改哪些设置以及原因，然后审计切片结果，查看哪些设置实际生效。

它不会控制打印机。不使用 MQTT、不上传文件、不启动打印。

• 与 GUI 切片结果一致的命令行切片。 Bambu Studio 的命令行会忽略预设的 inherits，因此从命令行切片内置预设时，会悄无声息地退回内置默认值。Slicewise 会先展开继承链（以及每台打印机的 G-code 模板），然后读取切片后的 3MF，并逐项报告每个覆盖设置是否生效。
• 切片前检查可打印性。 支持 STL、3MF 和 OBJ（包括 Tinkercad 导出文件）：检查超出打印床范围、无法接触打印床的悬空部件、非流形网格、陡峭悬垂、小接触面、高而细的部件、薄壁特征和翘曲风险。
• 检查部件之间的间隙。 检查打印原位成型机构的最小间隙，帮助你在打印前判断铰链是否会粘连。
• 参数知识层。 说明设置的作用、单位、合理范围，以及调高或调低设置的影响；支持基于目标的方案（安全、快速、坚固、表面质量、经济）和基于症状的诊断（翘曲、拉丝、大象脚、喷嘴碰撞……）。
• 非破坏性部件编辑。 创建包含负部件、修改器以及支撑阻挡器／强制器的 Bambu 项目 3MF 文件，完全遵循 Bambu Studio 的存储方式，不涉及几何引擎。
• 可在 GUI 中显示的用户预设。 仅写入用户配置文件夹；绝不会修改系统预设。

非官方项目。与 Bambu Lab 无关联，也未获其认可或赞助。 工具说明和消息均为英文。bambu_diagnose 和 bambu_plan_settings 也能匹配以中文描述的症状和目标（例如翹邊、省時）。

目录

• 快速开始
• 工具
• 为什么展平很重要
• 悬空部件检测
• 非破坏性部件编辑
• 配置
• 边界
• 支持矩阵
• 开发
• 许可证和商标

快速开始

需要 Node.js 22 或更高版本。切片需要在本地安装 Bambu Studio；参数和模型工具无需安装它也能运行。

Claude Code：

claude mcp add slicewise \
  -e BAMBU_MODEL_DIR="$HOME/Desktop/bambu-work" \
  -e BAMBU_OUTPUT_DIR="$HOME/Desktop/bambu-work/out" \
  -- npx -y @gjlmotea/slicewise-mcp

其他客户端（Codex、Gemini CLI、Cursor、Claude Desktop……）：

{
  "mcpServers": {
    "slicewise": {
      "command": "npx",
      "args": ["-y", "@gjlmotea/slicewise-mcp"],
      "env": {
        "BAMBU_MODEL_DIR": "/Users/you/Desktop/bambu-work",
        "BAMBU_OUTPUT_DIR": "/Users/you/Desktop/bambu-work/out"
      }
    }
  }
}

然后让 Agent 调用 bambu_get_status：它会显示 Bambu Studio 数据文件夹、是否找到切片器、预设数量、Studio 中当前选定的打印机和耗材，以及模型工具可能读取的文件夹。

macOS 隐私提示。 macOS 限制访问 ~/Desktop、~/Documents 和 ~/Downloads。如果模型工具返回 EPERM，请在“系统设置”中授予 MCP 主机（实际执行文件，例如 claude CLI，而不是 Claude 桌面应用）访问权限并重启它，或者将 BAMBU_MODEL_DIR 指向不受限制的文件夹。

工具

共 16 个工具，名称均以 bambu_ 为前缀。

区域	工具	功能
参数	bambu_plan_settings	打印前：设定目标（安全、快速、牢固、表面、经济），并获取按所防止的故障分组的设置；如果提供了模型，还会根据模型几何形状调整设置
	bambu_optimize_print_in_place	为原位打印部件创建保守的用户流程预设（首层速度较慢、限制外墙速度、减慢悬垂部分的速度；除非另有要求，否则不自动添加裙边）
	bambu_describe_parameters	参数的含义、单位、范围、调高或调低的代价以及相关设置
	bambu_diagnose	打印后：根据症状生成按顺序排列的修复建议，每次只更改一项
	bambu_resolve_preset	展开预设，并显示每个值来自哪一层
	bambu_compare_presets	比较两个已展开预设之间的差异
	bambu_list_presets	可选预设（已过滤抽象父预设和 G-code 模板条目）
	bambu_save_user_preset	写入用户预设，重启后即可在 Studio 中看到
切片	bambu_slice	展开预设、切片、报告层数、耗时和耗材用量（多色打印时按颜色统计），并审核每一项覆盖设置
模型	bambu_inspect_model	检查 STL、3MF 或 OBJ 几何信息：三角形数、边界、体积、面积、封闭网格和部件
	bambu_check_printability	检查尺寸、悬空部件、非流形几何、悬垂、占地面积、长宽比、薄特征和翘曲
	bambu_measure_clearance	测量 3MF 或 OBJ 中部件之间的最小间隙，并提供补偿建议
	bambu_compose_model	构建包含负体积、修改器和支撑控制部件的 Bambu 项目 3MF
	bambu_inspect_project	读取任意 Bambu 项目 3MF 中的对象和部件
搜索	bambu_search_models	通过官方 API 搜索 Thingiverse；MakerWorld 和 Printables 仅提供搜索链接
状态	bambu_get_status	数据文件夹、切片器、预设、当前选择和允许的文件夹

为什么展开预设很重要

Bambu Lab 的出厂预设采用四层继承链。叶子预设声明了几十个键，其余键则从上层继承：

0.20mm Standard @BBL X1C  <-  fdm_process_single_0.20  <-  fdm_process_single_common  <-  fdm_process_common

将叶子预设通过 --load-settings 传递给 CLI 时，不会解析 inherits。只有叶子预设自己的键会生效；其他所有设置都会回退到可执行文件的内置默认值，而这些默认值并非 Bambu Lab 的出厂值。在 X1 Carbon 0.4 喷嘴、0.20mm Standard、Bambu PLA Basic 和 20 mm 立方体上测得：

设置	原始预设	展开后
sparse_infill_density	20%（内置默认值）	15%（出厂预设）
top_shell_layers	4	5
elefant_foot_compensation	0	0.15
enable_arc_fitting	0	1
brim_width	0	5
打印时间	10m 11s	8m 45s

这是 bambulab/BambuStudio#1704 的原因（CLI 和 GUI 切片结果不同）。

另外还处理了两个容易踩坑的问题：

• 打印机 G-code 位于预设之外。 从 Studio 02.07 开始，起始、耗材更换、层更换和结束 G-code 都会在 system/BBL.json 中单独注册为 <preset> template <key> 条目。仅跟随 inherits 最终会得到一个通用起始序列，无法匹配任何 Bambu 打印机。Slicewise 会逐层应用这些模板；在 P2S 0.4 上，生成的 G-code 与 GUI 的逐字节完全一致。
• CLI 可能会关闭擦料塔。 当所有已加载的耗材预设名称相同时（五个槽位使用不同颜色的 Generic PLA），CLI 会将它们判定为同一卷耗材，并关闭擦料塔。在这种情况下，Slicewise 会传递项目自身的耗材颜色。对于一块四色 P2S 打印板，仅展开预设时，结果为 40.10 g / 2h 6m，且没有擦料塔，G-code 也是通用的；应用模板和颜色后，结果为 43.68 g / 2h 18m，与 GUI 完全一致。

悬空部件检测

一个真实案例：在 Tinkercad 中用方盒搭建的生日蛋糕插牌。腿部止于 z = 50 mm，身体从 z = 51 mm 开始。Bambu Studio 提示“无法在没有支撑的情况下打印悬空对象”，但启用支撑并不是正确的解决办法：支撑会填满 1 mm 的间隙，移除支撑时腿就会断裂。包围盒和悬垂角度看起来都没问题，关键在于连通性。

因此，bambu_check_printability 会：

1. 按共享顶点将几何体拆分成壳体（也适用于 STL 网格集合）；负零件、修改器和支撑阻挡器／强制器不是实体。
2. 将表面接触或相互穿插的壳体合并为实体。
3. 使用逐壳体的射线奇偶校验，将被其他壳体完全包围的实体合并起来（对多个重叠壳体组成的整个实体统计交点时，奇数 + 奇数 = 偶数，会错误地判定为“外部”）。
4. 报告每个未接触热床的实体：其抬升高度、可能应与其连接的实体（优先列出已接触热床的实体）以及间隙。

2 mm 或更小的间隙会被标记为可能的建模接缝：应通过增加一些重叠来修复模型，而不是添加支撑。这只是经验法则，并非绝对准确：捕获球、铰链等原位打印的预留间隙也会落在同一范围内，因此报告会要求你确认设计意图。更宽的间隙属于需要支撑的真实悬垂。

非破坏性部件编辑

Bambu Studio 的负零件、修改器和支撑控制并非网格编辑。它们是在 3MF 中带有 subtype 标签的额外部件：

<part id="2" subtype="negative_part">
  <metadata key="name" value="hole"/>
</part>

因此，bambu_compose_model 不需要布尔运算引擎，也不需要 GUI 自动化。它只接受五种子类型，取自 Bambu Studio 源码中的 ModelVolume::type_to_string()：normal_part、negative_part、modifier_part、support_blocker、support_enforcer。此列表有意设为封闭列表。Studio 的读取器会静默地将未知字符串视为实体零件，因此一个字母拼写错误就会把“将其切除”变成“将其作为实体添加”，且不会报错。使用一个顶部带有相同实体的 20 mm 立方体进行测量：不添加部件时，高 20.00 mm；negative_part 时，高 15.00 mm；normal_part 时，高 25.00 mm。

配置

变量	默认值	含义
BAMBU_MODEL_DIR	未设置	模型工具可以读取的文件夹，使用平台路径分隔符连接。未设置时，模型工具会拒绝所有路径
BAMBU_OUTPUT_DIR	未设置	切片和合成后的 3MF 文件的存放位置（也可读取）。未设置时，切片和合成操作会拒绝运行
BAMBU_STUDIO_PATH	依平台而定	Bambu Studio 可执行文件
BAMBU_DATA_DIR	依平台而定	Bambu Studio 数据文件夹（系统和用户预设）
BAMBU_SLICE_TIMEOUT_MS	300000	单次切片的超时时间
THINGIVERSE_TOKEN	未设置	Thingiverse 应用令牌；没有令牌时，搜索结果只返回链接

平台	数据文件夹	可执行文件
macOS	~/Library/Application Support/BambuStudio	/Applications/BambuStudio.app/Contents/MacOS/BambuStudio
Windows	%APPDATA%\BambuStudio	%ProgramFiles%\Bambu Studio\bambu-studio.exe
Linux	~/.config/BambuStudio	~/.local/bin/bambu-studio

边界

• 不控制打印机。 实体设备的操作不可逆且可能很危险，因此我们有意将其排除在范围之外。如有需要，请搭配使用打印机控制 MCP。
• 仅读取允许的文件夹。 拒绝访问 BAMBU_MODEL_DIR（和输出文件夹）以外的路径，包括 .. 路径遍历和前缀相同的相邻路径（/models-evil 不会通过对 /models 的检查）。
• 仅写入用户配置文件夹和输出文件夹。 绝不写入系统预设；如果存在同名用户预设，也绝不会在不提示的情况下覆盖。
• 不把浏览器自动化伪装成 API。 MakerWorld 和 Printables 没有官方公共 API，因此这里只提供搜索链接，不提供抓取的结果。
• 不猜测。 如果症状未知，bambu_diagnose 会明确说明，并列出它能识别的症状，因为错误猜测可能让情况变得更糟。
• 不进行破坏性几何操作。 布尔运算的结果交由切片器处理；计算新网格（合并、切割、浮雕文字）应使用 Blender 或 OpenSCAD。
• 测量间隙需要零件边界。 bambu_measure_clearance 可读取 3MF 和 OBJ；STL 是一整片未分割的三角形集合，因此该工具会说明这一点，而不是返回空报告。
• 仅读取现有项目，不重写。 bambu_inspect_project 可读取任何 Bambu 项目 3MF；bambu_compose_model 始终会写入新文件。

支持矩阵

	状态
macOS + Bambu Studio 02.07	已在真实硬件上验证，包括 GUI 对比和端到端切片
原厂预设	已使用 X1C、P1S 和 P2S 的 0.4 喷嘴预设进行测试
Windows、Linux	已实现默认路径，但尚未在真实安装环境中验证
多喷嘴打印机（H2D…）	尚未验证；每个喷嘴的设置均为数组，因此覆盖前请使用 bambu_resolve_preset 检查

欢迎提交 Bug 报告，请注明你的 OS、Studio 版本和打印机型号。

开发

pnpm install
pnpm verify   # typecheck, 226 tests, build, stdio smoke test

冒烟测试使用 fixture 数据文件夹，因此无需 Bambu Studio 即可运行（包括在 CI 中）。node scripts/verify-real-slicer.mjs 会端到端运行真实切片器，并且有意不纳入 verify。

src/
  domain/        pure logic: preset flattening, parameter knowledge, slicing audit, model geometry, 3MF
  ports/         PresetStore, Slicer, ModelCatalog
  adapters/      Bambu Studio CLI, preset store, Thingiverse, hand-off catalogs
  application/   BambuService
  server/        tool registration and schemas

ZIP 读取器和写入器、STL 和 OBJ 解析器以及 3MF 构建器均为手写；运行时依赖只有 MCP SDK 和 zod。

更新关键基准

src/domain/parameters/known-keys.ts 是生成文件：其中包含扁平化 Bambu Studio 配置的 568 个设置键，用于检查覆盖项中的拼写错误（Bambu Studio 会静默忽略未知键）。当 Bambu Studio 版本新增参数时，请重新生成：

node scripts/verify-real-slicer.mjs   # writes a .gcode.3mf
# take the key list from Metadata/project_settings.config in that file and overwrite known-keys.ts

它并未包含每种打印机的所有键：多喷嘴型号和其他型号可能有额外键，因此未知键会作为警告报告，而不是错误。

许可证和商标

MIT。Bambu Lab、Bambu Studio 和 MakerWorld 是 Bambu Lab 的商标。Thingiverse 和 Printables 是其各自所有者的商标。本项目与它们均无关联，也未获得它们的认可。本项目会将 Bambu Studio 的命令行界面作为独立进程运行，不包含任何 Bambu Studio（AGPL-3.0）代码。