---
name: automated-3d-model-splitting
description: Split externally painted 3MF source regions into an assembled multi-part 3MF by planning shared seams and interfaces without repairing or merging source defects.
---

# 自动化 3D 模型拆件

Current release: `3.0.0`, positioned as automated painted-3MF model-part splitting.

## 执行准入与遇错退出

面数、原始与有效区域数、边界环数及点数均只作统计，不单独触发拒绝。不因边界分叉本身直接退出；根据实际闭环提取、残留自接触和接口构造证据逐阶段判断；加载预检保持 undetermined，未检查的边界关系与接口适配列为 pending。资源预算超限标记 budget_exceeded，不能称为几何复杂。

先按 [严格执行与低输出日志](references/execution-policy.md) 执行 `inspect` 和复杂度预检。多子模型未明确选定时，CLI 输出列表并以退出码 5 停止；向用户询问目标，不默认挑最大对象。用户已明确指定且能唯一匹配时直接使用对应 `--object-id`。超出配置预算或不能确定支持时不得宣称可以拆件；阶段预检通过仅允许继续检查，不能视为成品保证。

拆件运行中允许执行当前代码已实现、且符合既定约束的修复或恢复流程；流程完成后必须重新通过对应检查。没有适用的内置流程或修复仍失败时，记录原因并退出。禁止为了让当前模型通过而临时修改代码、Skill 内容、放宽阈值或跳过检查；这类修改属于另行授权的开发任务。正常阶段 03 简化、平滑与 2 mm 有界点接触处理继续执行。本次已恢复既有的生成面绕序/朝向修复、有限深度回退、有限连接带宽度候选和输出闭合流程；源文件不被改写，修复后仍须通过几何与回读验证。

默认只读退出码及摘要。日志分为 DEBUG、INFO、WARNING、ERROR；完整日志保存在本地。失败时先用 `rg`/`grep` 筛选 ERROR，再按阶段或接口编号限量读取；原因仍不明确才读取对应 DEBUG，禁止默认全文阅读。审核图片先看带编号总览，不清楚的候选再展开原始六视图。所有语义和阶段确认门槛仍有效。

## 安装与入口定位

用户只需提出“从 GitHub 仓库安装此 Skill 和所需依赖”即可启动安装流程，不需要提供脚本名、Python 路径或把确认规则写入请求。助手应读取仓库安装说明，选择环境、取得下述确认并执行安装，不能仅返回手动命令就视为完成。普通安装请求本身仍不构成消耗确认。

从仓库安装时使用仓库根目录下的 `tools/install_skill.py`，详细流程见仓库 `tools/INSTALL.md`。无交互终端时先在对话中展示以下原句并取得明确同意，再传入 `--accept-usage`；不得自行填写确认，也不得手动复制或单独执行 pip 绕过安装器。安装脚本属于仓库工具，不应假设它存在于已安装技能的 `tools/` 中。

> 拆件可能消耗较多 token，复杂模型有可能失败；如果没有 Coding Plan，请谨慎使用，并对 token 消耗做好预期。明确确认后才安装

安装成功后再次显示上述原句，不再要求确认。不单独询问套餐情况。首次安装请求、空回复不构成同意；同一次安装会话已有明确确认则复用。示例拆件需另行征求用户意愿；开发修改和隔离打包测试不触发安装确认。

支持 Python 3.10–3.12。安装时必须保留完整技能目录，包括 `SKILL.md`、`scripts/`、`references/`、`agents/`、`requirements.txt` 和许可文件；若有 `tools/` 也一并复制。安装运行依赖使用所选 Python 解释器的 `-m pip install -r`，参数指向该技能目录内的 `requirements.txt`。

本文所有 `scripts/...` 和 `references/...` 路径均相对于实际加载的 `SKILL.md` 所在目录，不是用户项目目录或仓库根目录。从其他目录执行时，使用所选解释器和入口脚本的绝对路径，并传入模型、输出及审核文件的绝对路径。无需切换用户项目目录。不要把本节路径占位符当作真实路径：

```bash
python -m pip install -r "/ABSOLUTE/SKILL_DIR/requirements.txt"
python "/ABSOLUTE/SKILL_DIR/scripts/split_painted_3mf.py" --version
python "/ABSOLUTE/SKILL_DIR/scripts/split_painted_3mf.py" --input "/ABSOLUTE/MODEL_DIR/model.3mf" --preflight-only
```

## 职责边界

拆件负责识别 source 区域、确定零件关系、规划双方共用的交接线、生成交接面与装配结构，并导出一个分组 3MF。识别时自动将总表面积小于 `1 mm²` 的连通涂色区域排除为噪声，不作为独立零件候选；原始 3MF 和原始涂色数据不被改写。输出零件在交接边界的邻域需要统一重布网格，使外壳真实服从冻结的平滑边界；其他小碎片、小孔、翻转面、退化面、非流形边和断开壳体默认原样保留。

只有交接线、交接面、本工具新增的几何以及交接边界邻域的输出外壳网格可以被调整。source 异常可写入 `source_diagnostics`，但必须标记为非阻断；只有无法形成一致交接线、交接面或必要生成结构时，当前接口才可失败。

## 生成网格的边界强约束

阶段 03 对所有有效边界统一执行等弧长简化和 4 mm 周期高斯平滑，再清理可量化的微小三维点接触，并把结果冻结为唯一共享边界。小环继续使用较高的原始点保留比例；若抽样或平滑导致明显形变，则保留更多原始点或原始轮廓。微小接触清理的累计丢弃周长及最大轮廓偏移均不得超过 2 mm，且不得虚构源顶点对应关系。阶段 04 与阶段 05 的榫、卯及连接面只能读取这份冻结边界；原始边界仅用于定位和判断材料侧，不得重新生成最终接口边界。残留接触按既有有界接触规则审核：可在 2 mm 约束内确认的微小接触记录诊断并继续，冻结坐标不改写；超出规则的交叉须退出，实际生成面、闭合与间隙检查仍可阻断。禁止在阶段 05 增加按接口选择的平滑或裁边分支。记录边界最大位移，并检查闭合、翻面、间隙和外形。旧的 `0.05 mm` 位移上限不再适用。

**平滑边界必须真正约束外壳表面的生成，不能只约束榫卯接口的那一圈线。** 所有零件的交接邻域统一从阶段 03 的冻结简化边界生成外壳过渡面，原始边界只供定位、表面形状和颜色归属参考。禁止把原始锯齿边、按整片源三角形删除形成的阶梯切口、或最近距离补出的薄带当成最终可见外轮廓。必须检查过渡面的轮廓、法向连续性、三角形质量、自交、翻面和闭合；仅有 watertight 或导出成功不能视为外观通过。不得针对单个零件或接口增加例外。

裁切区域必须沿源网格拓扑从指定接口开口生长，禁止仅凭三维距离在折叠表面的另一侧再次切入。可见源表面（例如顶盖和图案）不得被接口裁切后用平面封盖覆盖；若裁切产生新的大边界或把单个零件裂成多个非预期连通实体，应修正裁切侧，不能用自动封盖掩盖问题。

只读取用户指定的 `.3mf`。拒绝 STL、OBJ 或改扩展名的输入。使用 `scripts/split_painted_3mf.py`，不要使用 Blender 或切片器 UI。

## 100/1000 面语义审核

先按区域总表面积过滤噪声：

- `<1 mm²`：自动排除为噪声，不进入零件区域、边界和语义审核清单；源网格和涂色数据保持不变。
- `>=1 mm²`：再按面数与长细形状筛选审核候选。

面数只筛选剩余审核候选，不决定几何处置：

- `<=100` 面：`noise_candidate`；
- `101–999` 面：`small_region_candidate`；
- `>=1000` 面：不因面数审核；
- 长细条候选：不受面数限制，必须审核。

当符合审核条件的候选超过 `--max-region-review-candidates`（默认 10）时，按完整源表面积从大到小只审核前 N 个，其余候选自动分类为噪声并从独立零件识别中排除。该分类不删除或改写源面；面积相同时按最小源面索引稳定排序。

进入审核的前 N 个候选由用户分类为 `noise`、`part` 或 `uncertain`。`part` 必须作为独立零件进入识别，即使少于默认面数门槛；`noise` 不生成独立零件，源面由完整归属阶段保留到宿主零件。`uncertain` 继续按普通识别门槛处理。超过上限的候选自动分类为 `noise`。原始 3MF 的顶点、面与涂色数据不改写；输出时，归并到宿主的面使用宿主零件颜色，已识别零件的源面保持自身颜色。归属和输出颜色须在导出回读中核对。

首次识别不要求预先提供 `--visual-semantics-json`：未命名区域以零置信度的“待确认区域 Pxx”写入报告，一次运行即可生成边界图和审核文件，不能将占位标签当作已确认部件名称。阶段 03 完成后，完整拆件流程还必须经过识别结果确认。查看 `03_recognition_boundary_review.md` 与预览；如果识别有误，可在 `03_recognition_review.json` 的 `actions` 中明确写 `delete` 或 `merge`，再通过 `--recognition-review-json PATH` 重跑。应用修改后必须复核新报告，并将新 JSON 中 `user_confirmed` 设为 `true`；只有匹配当前结果指纹的确认才会进入装配。这里的删除/合并是独立的用户明确操作，不由 `noise`/`part`/`uncertain` 分类自动触发。

阶段 04 完成后同样必须停下供用户审核 `04_interface_table.md` 和冻结边界。`04_assembly_review.json` 绑定源文件、边界和当前榫卯规划；只在用户明确确认后设置 `user_confirmed=true`，用 `--assembly-review-json PATH` 进入阶段 05。发现错配时保持 `false`，在 `correction_requests` 逐项记录接口 ID、问题及用户要求；当要求更改榫方选择策略时，可明确设置 `direction_policy` 为 `smaller_area_first` 或 `larger_area_first`。按用户指令修正并重做阶段 04，再让用户确认新规划。未确认、存在待改项或规划指纹失效时，全流程和阶段工件续跑均不得进入阶段 05。

运行识别：

```bash
python scripts/split_painted_3mf.py --input model.3mf --recognize-only
```

若需要审核，命令以退出码 `4` 生成六视图和 `user_decisions.json`。检查图片、填写每项 `semantic_label`、`visual_confidence` 与 `classification`，设置 `user_confirmed=true`，然后运行：

```bash
python scripts/split_painted_3mf.py \
  --input model.3mf \
  --output model_split_parts.3mf \
  --region-review-json review/user_decisions.json \
  --resume-region-review-from STAGE_RUN_DIR
```

首次等待小区域审核时会保存阶段 02 网格及审核前的阶段 03 检查点。确认后使用终端打印的 `stage_artifacts` 运行目录续跑；校验源 SHA-256、工件清单、识别参数和实现指纹后，复用可见性与连通区域结果，不再解析源 3MF。旧运行若只有阶段 02 工件，也可使用同一入口；它跳过源 3MF 解析，但需要重算可见性与候选。审核候选变化时仍由原有审核 JSON 校验拒绝旧决定。

审核阈值 CLI：

```text
--noise-review-max-faces 100
--small-region-review-max-faces 999
--max-region-review-candidates 10
--region-review-json PATH
--resume-region-review-from RUN_DIR
--region-review-dir PATH
--region-review-resolution 320
```

旧版 `--min-faces`、`--tiny-component-policy`、`--tiny-component-auto-noise-max-faces` 和 `--tiny-component-review-*` 不兼容且不再接受。不得增加兼容别名或把旧参数静默映射到新参数。

## 图像语义审核硬门槛

小区域分类审核前，Codex 必须逐一审核前 N 个候选，优先查看带编号的多视图总览，仅对上下文或细节不清楚的候选展开原始多视图图像，提出具体部位名称、图像依据和置信度，再让用户决定 `noise`、`part` 或 `uncertain`。`F001` 等编号仅用于定位，不是语义标签。阶段 03 识别表对每个 P 区域同样必须给出部位判断、图像依据和置信度；“待确认区域 Pxx”不得作为已完成的语义识别。若阶段 03 已有 JSON 和预览图，使用 `scripts/render_semantic_review.py` 从工件生成审核表，不再读取原 3MF。缺少上述语义判断时，不得进入阶段 04 或阶段 05。

## Source 保持约束

- 不运行按 `<=2 mm` 区域归并或小口封闭。
- 除识别阶段 `<1 mm²` 连通涂色区域过滤规则外，不按 `<1%`、长度、体积或面数自动修复 source。
- 不对 source 执行全局 winding 修复；接口关系独立记录两侧的内向方向。
- source 小孔远离接口时忽略；碰到接口时重新规划接口，不修补整个 source。
- 孤立 source shell 原样输出，不虚构连接结构。

## 交接线与交接面

独立零件间的边界配对使用统一的双向覆盖判定：完整闭环仍按闭环配对；一条闭环接触多个零件时，阶段 03 冻结源共享边的对侧零件归属，阶段 04 只以该零件对的归属段计算双向长度覆盖率，各方向均须至少 80%。源边必须有唯一对侧归属；未确定段不猜测。独立平滑的两侧冻结线允许最多 2 mm 距离，记录覆盖率、P90 和未通过的零件对。同一榫方闭环有多个确认接触时，以源共享边相邻的榫方三角面总面积选择最大宿主，只为它构造榫卯；较小接触保留在诊断中，不再开槽。

识别完成后，第 04 阶段以冻结的简化边界为准，逐对规划接触零件的榫件、卯件和方向，不选择主体，也不建立父子树。接触两侧引用同一条识别边界。允许处理范围限于接口局部和新生成几何；不得以生成可打印实体为由改写无关 source。

交接审计至少记录：共享边界、生成面退化与方向、接口穿出、装配间隙、材料槽保持，以及输出 3MF 回读状态。接口外观诊断保留在报告中；无法闭合、绕序错误、装配余量错误、新增退化面或导出回读失败时不得把零件标记为完成。缺少第 04 阶段关系或必需方向等导致无法构造的输入仍作为执行错误；不得猜测补榫。source 自身的缺陷只在远离本次交接面的范围内记录，不自动修复。

简化边界由阶段 03 冻结。修改接口算法前阅读 [boundary-smoothing.md](references/boundary-smoothing.md)、[assembly-algorithm.md](references/assembly-algorithm.md) 和 [application-stages.md](references/application-stages.md)。

拆件流程阶段、输入输出和单步调试工件见 [application-stages.md](references/application-stages.md)。开发或诊断时可使用 `--stop-after-stage` 和 `--stage-artifacts-dir` 查看每个阶段的 JSON/NPZ 结果。

阶段 03 和 04 同时输出表格型 JSON（`03_recognition_table.json`、`04_interface_table.json`）及用户可读的 Markdown 表格（同名 `.md`），终端也打印表格；不输出 CSV。已有阶段 JSON 可通过 `scripts/render_stage_tables.py --run-dir RUN_DIR` 补生成表格，无需重读源模型。

已存在 02/03/04 阶段工件时，若只需重跑 05，使用 `scripts/run_stage05_from_artifacts.py --source-run-dir RUN_DIR --output-root OUTPUT_DIR`；该入口直接校验并读取既有 NPZ/JSON，不重读 3MF，也不重建识别边界。

若阶段 03 已完成，使用 `scripts/run_stage04_from_artifacts.py --source-run-dir RUN_DIR --input SOURCE.3mf --visual-semantics-json SEMANTICS.json --recognition-review-json RUN_DIR/03_recognition_review.json` 从已保存网格、区域和冻结边界生成阶段 04；不得为确认识别结果或补标签重读源 3MF。即使 `03_recognition_review_status.json` 仍显示待确认，只要审核 JSON 已由用户确认，该入口也会先核验源 SHA-256、工件清单、识别动作及最终结果指纹，再正式记录确认并继续。入口拒绝覆盖已有阶段 04 计划。

正式输出也可从主 CLI 续跑：

```bash
python scripts/split_painted_3mf.py --input model.3mf \
  --resume-stage05-from PREVIOUS_RUN_DIR --output model_split_parts.3mf \
  --stage-artifacts-dir NEW_ARTIFACT_ROOT
```

该入口核对源文件路径与 Stage 02 记录的 SHA-256，并验证 02/03/04 工件的校验和与冻结边界指纹。新生成的 Stage 04 工件还记录上游参数和实现指纹；续跑时若上游代码已变化则拒绝复用。旧工件无此记录时仍可按工件校验和与边界指纹复用，但不具备代码版本校验。入口只重新构造并验证 Stage 05；修改识别、边界或 Stage 04 算法时必须重新运行相应上游阶段。

## CLI 与执行

安装 `requirements.txt` 后先运行：

```bash
python scripts/split_painted_3mf.py --input model.3mf --preflight-only
```

CLI 只负责参数解析、输入校验、调用可测试服务、输出报告和退出码。不要把审核、分类或几何逻辑复制到 CLI。退出码 `4` 仅表示等待 source 区域语义确认；退出码 `3` 表示交接面、生成结构或包输出失败，不能用它表示无关 source 缺陷。

当前后续构建阶段直接消费第 04 阶段的榫方、卯方、方向和冻结共享边界；不得恢复主体推断或父子树递归。原 05/06/07 合并为 `interface-assembly`，早停参数为 `--stop-after-stage interface-assembly`。05 阶段以冻结边界的面积法向为统一构造轴，04 的榫卯方向只决定轴的朝向。按默认 0.50 比例生成椭圆内轮廓，只沿榫卯轴尝试一次三角剖分；不进行其他方向探索或该椭圆候选的投影/三维自相交扫描。闭合、绕序、退化面和卯侧厚度仍须通过。允许代码已实现的有限深度回退、连接带宽度候选、生成输出封口及绕序/朝向修复，不另造候选轮廓；既有流程耗尽或验证仍失败则退出。04 外圈在完整零件中只作为连接边界；保留源外观并将其局部接入交接面，不做布尔并集。最终发布保留原始颜色槽与逐面材料，要求完整零件及 3MF 回读通过。诊断报告必须区分：

```text
source_diagnostics: non_blocking
interface_validation: diagnostic_only
```

若本次识别生成 `03_recognition_boundaries.png`，最终回复必须内嵌显示该图片（`![边界预览](绝对路径)`），不能只给文件链接。回复前先确认图片文件存在且可读取；报告仍可另附链接。

关键不变量：对同一候选分别选择 `noise`、`part`、`uncertain` 时，source 顶点、面、颜色和组件成员必须一致；只有语义 metadata 可以不同。