solidcraft三维建模

SolidCraft 是一个单文件、零安装、无 GUI 的参数化实体建模器（Rust / truck 内核，MIT OR
Apache-2.0，单位 mm、Z 轴向上）。本技能把它的命令行能力封装成一条稳定链路：

定位/安装 → 写脚本 → 静态检查 → 执行（装配体先建组件树 → 先存 .solidcraft → 后导 STEP）
        → 回读复核 → 目视渲染 → 交付（按需用桌面本体打开 .solidcraft，让用户自己转着看）

什么时候用

• 用户要求建模并导出 STEP / STL / OBJ / 3MF，尤其是「按参数生成」「批量出件」；
• 需要底板孔系、沉孔、圆角、阵列、扫掠、放样、旋转体这类规则实体；
• 需要标准件装配（ISO 4762 内六角圆柱头螺钉、螺母、垫圈、销、轴承）；
• 需要装配体 STEP（嵌套组件结构）：多实体模型交付给下游 CAD 时要能按件装配、
  替换与出明细表（见约定 6）；
• 需要装配干涉检查或无 GUI 出三视图/等轴测图；
• 需要齿轮 / 花键这类「齿面必须光滑」的件：渐开线齿廓用单段样条 + 精确圆弧拼，
  一张齿面就是一张 B 样条面（G1 相切、偏差 0.4 µm 量级）——照
  @references/involute-gear.md 的生成器与复核协议做，不要用折线插齿；
• 需要参数化重建：改几个参数，模型自动重算并重新导出；
• 需要单侧 / 扭转类曲面（莫比乌斯带、螺旋带、绞龙叶片、扭转梁）：surface.sweep 的 twist
  一圈即成单张闭合面，闭合截面再 surface.stitch 得实体——面域与解析积分差 0.0007% 量级，
  照 @references/recipes.md 配方 E 抄；不要先做面再 surface.thicken（非可定向面必然失败，
  见 P2-11）；
• 需要钣金折弯件（盒子 / 支架类：底板 + 四壁 90° 折弯，要展开图与折弯表）：照
  @references/recipes.md 配方 H 抄——草图点位用参数表达式锚定，规则 bend_radius
  写 "Thickness" 跟随料厚，改一个参数整个盒体连同四壁自动重算；
  不要用「实心盒抽壳」近似钣金（convert 路线的展开图尺寸不可信，见配方 H 第二节）；
• 需要公式驱动的轮廓（凸轮型线、非圆过渡、变径螺旋、齿廓修形）：用 sketch.equation_curve
  按参数式 x(t) / y(t)（或 explicit: true 的 y = f(x)）生成拟合样条，公式可引用设计参数，
  改参数轮廓自动重算，再用 solid.extrude/revolve/sweep 消费——照 @references/recipes.md
  配方 I 抄。注意：无头会话里该命令显示 enabled: false 是「未进入草图」的上下文门控，
  sketch.create 之后即可执行，别因为没有 enabled: true 就判定不可用；
• 需要省掉参考线、直接拿模型边定位（孔中心到板边、边到边、点到边）：sketch.dimension 的
  entities 收 {"edge": [x,y,z], "body": "件名"} 与 {"vertex": …}，引擎先投影进草图再量；
  只测量必须带 driven: true，给 value 才是驱动——照配方 J 抄；
• 需要让用户自己交互查看模型：交付 .solidcraft 工程文件，并用桌面本体打开
  （自由旋转/剖切/测量/改参，见约定 5）。

不适合：极端 Class-A 自由曲面（surface.* 到 0.30.1 仍是只剩 surface.fillet 一条未实现，
其余 18 条可用，但复杂拼接仍以试做为先）、需要真实螺纹几何、需要工程图标注。
这几类请改用具备 OCCT 能力的引擎。

十一个必须遵守的约定（否则会静默出错或交付物不全）

SolidCraft 有几处不报错、退出码仍为 0 但结果错误的行为，另有交付口径、上游跟随口径、
安装落点口径、版本说明口径、命名口径与下载源口径各一条。以下十一条是硬约定：前四条是「会静默出错」的坑，第 5、6 条是
「交付物不全 / 交付物不可用」，第 7 条是「与上游保持同步」，第 8 条是「装在哪里、更新覆盖哪里」，
第 9 条是「每次更新后把上游全部版本说明过一遍」，第 10 条是「建模步骤一律中文命名」，
第 11 条是「初次安装与更新一律先比 GitHub / Gitee 两源版本」。

1. 草图有内环时必须显式声明，否则孔会凭空消失。
   草图里「矩形 + 圆」拉伸，若只写 solid.extrude {distance}，即使写 profiles: "all"，
   圆也不会变成孔——体积等于完整矩形，rc=0、无警告、面数也正常。
   做法：用 solid.hole 造孔（不依赖草图内外环判定）；确实要用草图内环时，必须显式给
   profiles: [外轮廓索引]。

2. 参数化选中边/面，不要用点坐标。
   solid.fillet / chamfer / shell 的选择集只接受字面数字：写表达式或字符串数字一律
   rc=1；就算写死数字，尺寸一变拾取点就落到实体外，重建直接失败。
   做法：用 {"body": 件名, "index": 下标}，下标先经 model.edges / model.faces
   取得（实测同一拓扑下标跨尺寸稳定）。

3. file.export 永远放在脚本最后。
   导出是即时副作用，不参与整脚本回滚：某一步失败时退出码为 1，但磁盘上早已留下半成品。
   做法：导出放最末；调用方以退出码为准，rc≠0 时先清理产物再重试。

4. 先存工程文件（.solidcraft），再导 STEP——每次建模都必须这样，无例外。
   .solidcraft 是唯一可回放、可改参的源（内含明文参数表与特征时间线）；STEP/STL/OBJ/3MF
   只是它的一次派生快照，不带参数、不可改。而 file.export 是即时副作用、不参与回滚：
   一旦 rc≠0，或事后用户要「把某个尺寸改一下」，没有工程文件就只能从零重建——这是本技能
   最昂贵的一类返工。
   做法：脚本倒数第一步用 file.save_as（或 file.save + path）写工程文件，最后一步才
   file.export 导 STEP。 正确顺序：

json {"command": "inspect.measure", "params": {}}, {"command": "file.save_as", "params": {"path": "零件.solidcraft"}}, // ← 先存工程文件 {"command": "file.export", "params": {"path": "零件.step", "format": "step"}} // ← 后导 STEP

工程文件名与本件同名（<件名>.solidcraft），落在同一工作目录。
sc.py lint 已把「只导出、不存工程文件」列为 P1-5 风险并返回 1；sc.py run 也会在漏存时
打印提醒。 交付时工程文件与 STEP 一并交给用户，二者缺一不可。

5. 用户想自由查看模型时，用 SolidCraft 桌面本体打开工程文件（.solidcraft）——不要只给图。

渲染出的 PNG 只能看「我选定的那几个角度」，STEP 虽在多数 CAD 里能打开，却与参数、特征时间线
脱钩。.solidcraft 才是桌面本体的原生工程格式：打开后可自由旋转/缩放、剖切、测量、
翻特征时间线与改参重算——这正是用户说「我想自己看看模型」时真正想要的东西。
换言之，这是约定 4 的第二个理由：没有工程文件，用户就只能看死图。

做法：

bash python scripts/sc.py open 零件.solidcraft # 用桌面本体打开（分离进程，不阻塞） python scripts/sc.py open --check 零件.solidcraft # 只报告本体路径与文件，不启动

• 本机若已注册 .solidcraft 文件关联，双击工程文件同样能打开（Windows 下关联写在
  HKCR\Solidcraft.Design\shell\open\command，指向桌面本体的 exe）。
• sc.py open 按「显式 --gui / 环境变量 SOLIDCRAFT_GUI → 本机系统安装目录 →
  与 CLI 同目录 → 常见安装路径 → Windows 文件关联反查 → macOS 应用包」定位桌面本体，
  本机那份优先（约定 8）。官方 portable 发行包内本就含桌面本体，约定 8 起它随 CLI
  一并安装/覆盖，正常不必另装。
• 找不到本体时不要伪造成功：如实说明本机没有桌面版，跑
  python scripts/sc.py upstream --force 让技能按约定 8 补齐本机安装（含本体）；
  仍不可得再从官方 Releases 手工获取
  <https://github.com/tangency-labs/solidcraft/releases>，并退回无头方案——
  用 snapshot 多出几个视角的 PNG 交付。
• 只在用户明确要求「自己看 / 打开看看 / 旋转查看」时才调用；建完模型不要自动弹窗打扰。
  无人值守、远程或服务器环境里没有桌面可用，直接走 PNG。

6. 装配体（≥2 个实体）导出 STEP 前，必须先用 component.* 建立组件树——否则 STEP 是「一个零件里塞了 N 块实体」，不是装配。
   不建组件时，引擎把 N 个 MANIFOLD_SOLID_BREP 全部写进同一个 shape representation，
   NEXT_ASSEMBLY_USAGE_OCCURRENCE = 0（实测 6005 轴承：13 个实体 → 1 个
   ADVANCED_BREP_SHAPE_REPRESENTATION）。下游 CAD（SolidWorks / UG / CATIA / FreeCAD）
   打开得到的是一个零件的多重实体：不能按件装配、替换、隐藏，也出不了明细表——而用户拿到
   装配体 STEP，要的正是这层结构。这个错误不报错、rc=0、体积也对，只有打开 STRUCTURE 树才看得见。

做法（三件事）：

• 归位：component.from_bodies {bodies: ["外圈", "内圈", …]} —— 每个实体各成一个组件，
  组件名随实体名，挂到当前激活组件下。
• 嵌套：子装配先 component.create {name: "滚珠组", parent: "root"}（默认激活新组件），
  再在激活态下 component.from_bodies 把实体归进去，最后 component.activate {component: "root"}
  回到根。实测两级树 root → 滚珠组 → 球1/球2 正确生成，STEP 内 NAUO = 4 条、父子指向准确。
• 实例复用：同规格重复件（滚珠、螺钉）不要各造一份几何——occurrence.copy {occurrence: "滚珠:1", translate: [x, y, z]} 复用同一组件定义、只增加放置。实测「1 份几何 + 3 个放置」
  = 6.8 KB，而「3 份独立几何」= 15.1 KB；STEP 里 3 条 NAUO 指向同一个 PRODUCT_DEFINITION，
  各带独立的 ITEM_DEFINED_TRANSFORMATION（位姿）。旋转放置用 occurrence.move（支持
  axis + angle），occurrence.copy 本身只接受 translate。

计量口径不变：inspect.measure 与 inspect.interference 会自动展开实例（实测 3 个放置
全部计入总量，checked=4），所以原有复核手法照旧；要按组件/放置逐项定位时用
component.properties {component: "root"}，返回每件所属 component id、path（occurrence id）
与世界坐标（含 placement_count）。

单件模型（1 个实体）不需要组件树，不要为凑格式硬加。

sc.py lint 已把「装配体平铺导出」列为 P1-6 风险并返回 1；sc.py run 也会打印提醒；
sc.py stepinfo 结果.step 可直接读出成品 STEP 的装配结构（PRODUCT 数 / NAUO 数 / 嵌套深度），
用来复核交付物里确实有嵌套组件——判到「平铺」时它同样返回 1。 组件树会随 .solidcraft 一起入库（document.json 的
components + occurrences），回放与改参后结构不丢。

7. 每天第一次调用本技能时，先检测上游版本；检测到落后就立即自动更新。
   本技能包随包锁定的上游资料版本与引擎门槛都会随时间过期（资料与二进制与该仓库的
   release 同源推进）。做法：不必手工判断，交给 sc.py 的每日惰性检测——本技能当天
   第一次被调用时会在后台发起一次检测，检测到版本落后即自动更新上游资料、官方全书
   docs/ 与 CLI 引擎；检测走分离进程、当日只跑一次，不阻塞任何建模命令；网络不可达
   或目录只读时静默跳过并如实记录，绝不伪装成功。

bash python scripts/sc.py upstream # 检测 + 落后即自动更新（当日已检测且无需再动则跳过联网） python scripts/sc.py upstream --check # 只检测不更新（有落差时退出码 1，便于脚本判定） python scripts/sc.py upstream --force # 忽略「当日已检测」的节流，强制重查

• 状态与日志落在 ~/.solidcraft/state/（技能包目录可能只读，故不写包内）；
  ~/.solidcraft/state/upstream.log 是完整更新日志。
• 置环境变量 SOLIDCRAFT_NO_UPDATE_CHECK=1 可完全关闭检测（CI、纯离线环境）。
• 检测失败不等于建模失败：任何情况下都不要因检测问题中断、推迟或反复重试建模任务；
  结论不是「已是最新 / 已更新」时，照原计划继续建模，把结论如实转述给用户即可。

8. 本机系统安装优先；更新时「有则就地覆盖、无则托管目录首次安装」。
   本机常常已经装过 SolidCraft（安装包或便携包解压在 Program Files、%LOCALAPPDATA% 等处）。
   若技能再自己存一份，就会出现两份并存、版本打架：ensure 拿不准用哪份，用户手工升级后
   也可能感知不到。用户口径（约定 8）：

• 调用：建模用 CLI、用户看模型用桌面本体，都优先用本机系统已安装的那份。
  「本机」= PATH 与常见安装位置（C:–F: 各盘的 \Program Files\solidcraft、
  %LOCALAPPDATA%\Programs\solidcraft 等），不含托管目录 ~/.solidcraft/bin。托管目录只是兜底——本机没装时
  它才是正式安装位置；本机已装时那里只放一个指向本机的引用（同卷硬链接优先，
  跨盘或链接失败时退化为同源副本，SHA256 相同），保证连接器的固定路径始终可用。
• 更新落点：本机已安装 → 就地覆盖（CLI + 桌面本体 + README + 合规文件，与官方
  portable 包逐文件一致）；未安装 → 托管目录首次安装，之后也在那里覆盖。
• 覆盖流程：先 SHA256 校验官方发行包，再逐个 os.replace 原子替换，不留半成品。
  覆盖桌面本体时若本体正在运行，Windows 会拒绝写入——先请用户关闭本体再重试。
• 目标目录不可写（例如装在系统盘的 Program Files，需管理员权限）：Windows 上弹 UAC
  授权窗，用户点「确定」后由提权进程完成覆盖；用户点「否」或提权失败 → 降级到托管目录，
  并在输出里明确报出原因，绝不伪装成功，也不阻塞建模。
• 安全阀：若本机版本低于托管副本（说明本机覆盖升级没成功），本次改用托管那份，
  免得引擎被钉在旧版；下一次 upstream 仍会继续尝试覆盖本机。
  ⚠ 但「引擎是否落后」这条判据必须落在本机那份上（local_install_behind），
  不能看当前选中的那份——否则安全阀会把「本机仍是旧版」遮蔽成「已是最新」，
  本机永远补不上（踩过：upstream --force 打印「均为最新」却什么都没做）。

bash python scripts/sc.py versions # 本机安装 / 托管副本 / 实际选用 / 更新去向，一屏看清 python scripts/sc.py ensure --json # 含 local_install_dir 与 install_dir 两个字段

• 环境变量：SOLIDCRAFT_NO_ELEVATE=1 不弹 UAC（CI / 无人值守）；
  SOLIDCRAFT_NO_GUI_INSTALL=1 只装/覆盖 CLI、不装桌面本体。

9. 每次上游更新完，都要把全部 release 说明再过一遍并续写总结。
   上游会在一版里塞进改变脚本写法的事实（命令改名、选择集语义、STEP 导出行为、设计文件格式版本），
   而这些只出现在 release notes 里，docs/ 未必同步。只看最新一版会漏掉中间版本的破坏性变更。

• 原文：upstream-release-notes.json（scripts/fetch_release_notes.py --fetch 抓 GitHub
  全部 release 并去噪：剔除 New Contributors / 下载清单 / chore-ci 类 PR，还原被硬换行切碎的段落）。
• 中文总结：references/upstream-changelog.md，逐版本给出「新增 / 修复 / 兼容性」与
  「对本技能的影响」，并维护一张设计文件格式版本表（格式变了就是旧引擎打不开新文件）。
• 覆盖面判定：总结里每个版本末尾有 <!-- COVERED: vX.Y.Z --> 标记；
  sc.py upstream 会把它和上游 release 列表比对，只要有版本没被总结就在输出里点名。
• 做法（更新完引擎后立刻做，不要攒）：
  bash python scripts/fetch_release_notes.py --status # 报出尚未总结的版本（旧→新） python scripts/fetch_release_notes.py --show <tag> # 读该版本的去噪正文
  然后按 references/upstream-changelog.md 第六节的模板补一节（放在最前面，保持新→旧顺序），
  必须带上 <!-- COVERED: <tag> -->，否则下次更新会重复提示。
• 门槛联动：若新版本出现破坏性命令变更、或本技能依赖的能力下移，同步改
  scripts/sc.py 的 MIN_VERSION 与 build_connector_config.py 的 MIN_VER（两处必须一致）。
• 这一步不影响建模：抓不到说明就如实记下，继续建模，下次调用再补。

10. 建模步骤一律中文命名——草图、实体、特征、参数、组件、实例全部用中文名。
    引擎在省略名字时会给出 Sketch1 / Body1 / Extrude3 这类序号自动名，而序号会随
    步骤增删漂移。.solidcraft 的「改参重算」全靠按名定位：名字一旦被自动名顶替，
    targets / bodies / parameters.change 在下一轮修改时就找不到对象，只能从零重建。

    • 命名落点：sketch.create 的 name；solid.* 的 body_name（结果实体）与 name（特征）；
      parameters.add 的 name；component.create / parts.insert / construct.* / joint.* 的 name。
    • 必须含汉字，允许混合写法（M6螺钉、Q235钢、上截面）；材料牌号、钣金规则、配置名、
      渲染设置名、库条目名不受此限（material.* / sheet.* / config.* / render.* / library.*）。
    • 引用同名：targets / bodies / sketch / component / occurrence 一律照抄声明时的中文名；
      组件实例是 滚轮:1 这种「名:序号」，名称里不要出现 : / #，否则引用会被拆错。
    • 参数就是改参入口：parameters.add 的名字用中文，comment 写中文说明（含义 / 单位 / 依据）。
      改参用 {"command": "parameters.change", "params": {"name": "板厚", "expression": "12 mm"}}，
      引用它的草图、特征与装配位姿会自动重算——前提是这些对象当初有中文名。
    • 实测坑：中文实体名在 .solidcraft 与桌面本体里完好；写成 STEP 后，引擎自家 eval
      只解出第一个 \X2\…\X0\ 转义（底板 → 底\X2\677F\X0\）。名称对账请对工程文件做，
      不要对 STEP 的 name 字段做；sc.py stepinfo 已内置转义还原。
    • 旧脚本可逐步改：body.rename / parameters.rename / component.rename 改名后引用跟随；
      sc.py lint 会把纯英文名列为 P2-10 并返回 1（--skip-naming 可临时只看 P1 项）。

11. 初次安装与更新的下载源：先比 GitHub 与 Gitee 的最新 release，谁新用谁；同版优先 Gitee。
    两个源都会发布同一套发行包（Gitee 是镜像仓 seaworld/solidcraft-release-copy）。国内直连
    GitHub 常被阻断，Gitee 又快又稳；但镜像可能落后一版、也可能个别资产没同步过去。

    口径（四条，按顺序判定）：

    1. 每次初次安装或更新，先查两源 releases/latest 的 tag，比出版本高低；
    2. 谁的版本新，就从谁下载（Gitee 更新走 Gitee，GitHub 更新走 GitHub）；
    3. 两源版本一致 → 优先 Gitee；
    4. Gitee 上找不到该版本、或没有当前平台/架构的那个资产 → 回退 GitHub
       （GitHub 侧仍按 ghfast.top → ghproxy.net → 官方直连 的顺序兜底）。
    • 这一步只决定「从哪下」，不改「下哪个版本」：装的仍是本技能锁定的门槛之上、检测到的最新版，
      不会因为 Gitee 上出现一个更新 tag 就跳版。
    • 校验和按实际取用的源读同名 SHA256SUMS.txt（两源该文件实测逐字节一致），校验不通过即弃用该源。
    • 对比结果缓存 30 分钟（~/.solidcraft/cache/sources.json），避免每次调用都打 Gitee 匿名接口。
    • 逃生口：SOLIDCRAFT_NO_GITEE=1 只用 GitHub（排查「是不是 Gitee 那边的问题」）；
      SOLIDCRAFT_GITEE_REPO=<owner/repo> 换镜像仓。
    • 连接器侧（点「连接」触发的一次性自举）同一套原则：PowerShell 与 POSIX sh 各实现一遍，
      因为它必须自包含、不能依赖 sc.py。
      bash python scripts/sc.py sources # 两源版本、本次选谁、为什么、当前平台资产在不在 python scripts/sc.py sources --json # 机器可读 python scripts/sc.py sources --refresh # 忽略 30 分钟缓存，强制重查

另外两条口径：

• 引擎自报的体积/质量只能作参考，不能作权威。 实测自报值与异核回读偏差在
  ±0.02% 以内但符号不定。关键件请用 eval 回读 STEP 取数，或手工核算。
• 默认材质密度是 1.29 g/cm³，不是钢也不是木材。报重量前必须显式指定材质——
  用 material.create（自定义密度）或 material.assign（内置 Steel/Aluminum/…），
  之后 inspect.measure 的 mass_g 才可信（实测 100 cm³ × 7.85 = 785.0 g，与手算一致）。

快速开始

所有命令通过 Bash 调用 scripts/sc.py。脚本只依赖 Python 标准库。

第 1 步：确保引擎就绪（本机系统安装优先）

python scripts/sc.py ensure --json
python scripts/sc.py versions        # 想看清「本机安装 / 托管副本 / 实际选用 / 更新去向」时
python scripts/sc.py sources         # 想看清「两源谁新、本次从哪下、为什么」时

ensure 按「环境变量 SOLIDCRAFT_CLI → PATH → 常见安装位置 → 托管目录」的顺序探测。
前四段命中的都属于「本机系统安装」（约定 8）：只要版本不低于门槛（0.30.1）就直接复用，
绝不重复下载。仅在完全找不到或版本过低时才下载官方发行包（约定 11：先比 GitHub 与 Gitee
两源版本，谁新用谁，同版优先 Gitee，Gitee 缺该版本或该资产才回 GitHub；GitHub 侧再按
ghfast.top → ghproxy.net → 官方直连 兜底），并用官方 SHA256 校验后按约定 8 的落点安装：

• 本机已安装 → 就地覆盖那份安装（CLI + 桌面本体 + README + 合规文件）；
  目录不可写则弹 UAC 授权窗，被拒则降级到托管目录并如实报出；
• 本机未安装 → ~/.solidcraft/bin/ 首次安装，之后也在那里覆盖。

返回值中 action 为 reused 表示复用了已有安装，installed 表示本次才安装；
local_install_dir 是本机安装目录（没有则为 null），install_dir 是本次（及以后）更新的落点。

第 2 步：写建模脚本

脚本是 JSON 数组，每步形如 {"command": "命令id", "params": {...}}。
格式细节、参数表达式规则见 @references/script-format.md；
可直接改用的成套模板见 templates/ 目录（7 个模板均已内置「先 file.save_as 存工程文件、
后 file.export 导 STEP」的正确顺序；装配类模板另含组件树；实体/草图/参数全部中文命名，
可照抄）。

第 3 步：静态检查（强烈建议，代价近乎为零）

python scripts/sc.py lint 建件脚本.json

自动拦截上面五条 P1 约定（孔被吞、选择集用表达式、导出不在最后、只导出不存工程文件、
装配体平铺导出）与约定 10 的中文命名（P2-10），命中即返回 1。
这一步能挡掉绝大部分「图能打开但机械上讲不通」「事后无法改参」「下游 CAD 打不开装配树」的返工。
（约定 5 是交互口径，无法静态判定——用户说要自己看时，照约定 5 做。）

第 4 步：执行

# 标准姿势：先存工程文件（脚本内 file.save_as 或命令行 --save），再导产物
python scripts/sc.py run 建件脚本.json --results --workdir ./out --save 零件.solidcraft
python scripts/sc.py run 建件脚本.json --out 零件.step --out 零件.stl

# 仅当脚本里已写 file.save_as 时，才可省略 --save

• --save 与脚本内的 file.save_as 二者取一即可，但必须有：这是约定 4 的落地点。
  首选写在脚本里（可复现、可归档）；临时试算才用 --save。
• --results 输出逐步回执（含每步耗时、新建/变更/移除的实体）；
  注意：以 .solidcraft 工程文件为输入时不能加 --results（引擎会把它当 UTF-8 文本读）。
• 报错里的 step N 是 1 起算，而 --results 数组是 0 起算，对号时要减 1。
• 若脚本既有导出、又没存工程文件、命令行也没给 --save，sc.py run 会打印醒目提醒。
• 装配体（≥2 实体）的脚本里，组件树步骤要排在所有建模步骤之后、file.save_as 之前
  （约定 6）：先造完并布尔完所有实体，再 component.from_bodies / component.create 归位，
  最后才存工程、导 STEP。归位之后再改几何会让实体落回当前激活组件，结构变乱。

第 5 步：回读复核

python scripts/sc.py eval 结果.step        # 体数/体积/面积/重心/包围盒/面型分类
python scripts/sc.py stepinfo 结果.step    # 装配结构：PRODUCT 数 / NAUO 数 / 嵌套深度

eval 返回体数、体积、面积、重心、包围盒、面/边/点计数与面类型分类。用它核对：
体数是否符合预期、体积是否落在手算值附近、圆柱面数量是否说明圆角/孔真的存在。

装配体必须再看 stepinfo：eval 只数实体，看不出这层实体是「装配」还是「一个零件里的一堆体」。
stepinfo 会直接报出 PRODUCT / PRODUCT_DEFINITION / NEXT_ASSEMBLY_USAGE_OCCURRENCE 计数与
组件树层数，并给出「装配」或「平铺」的判定——这是交付前唯一能确认嵌套组件真的写进 STEP 的检查。

第 6 步：目视渲染（无 GUI 出图）

python scripts/sc.py snapshot 建件脚本.json --out 等轴测.png --view iso
python scripts/sc.py snapshot 建件脚本.json --out 俯视.png --view top --width 1000 --height 780

可选视角：iso / front / back / top / bottom / left / right。
CPU 光栅化，800×600 约 0.3 秒。

> PNG 是给你（模型自己）复核用的，只能证明「几何长对了」。用户要自己看模型时走第 7 步。

第 7 步：让用户自己查看（用桌面本体打开工程文件）

触发条件：用户说「打开看看」「我想自己转一下」「旋转查看」「看下这个模型」之类，
或明确要求交互式查看。否则不要弹窗。

python scripts/sc.py open 零件.solidcraft          # 用桌面本体打开（分离进程，立即返回）
python scripts/sc.py open --check 零件.solidcraft   # 只报告本体路径与目标文件，不启动
python scripts/sc.py open --gui "<本体可执行文件路径>" 零件.solidcraft   # 显式指定本体

• 优先打开 .solidcraft 工程文件，不是 .step：工程文件带参数表与特征时间线，
  用户能在界面里自由旋转/剖切/测量/改参重算。.step/.iges/.json 也能被本体打开，
  但那是「导入一份几何」，没有历史与参数。
• 本机若已注册 .solidcraft 文件关联，双击工程文件等价于本节做法（见
  @references/install-and-verify.md 的桌面本体落点）。
• 本体同样遵循约定 8：本机系统安装的那份优先；官方发行包内本就含本体，
  随 CLI 一并安装/覆盖，所以正常不需要用户另装。
• 找不到桌面本体时：如实说明，并先跑 python scripts/sc.py upstream --force 让技能按
  约定 8 补齐本机安装（含本体）；仍不可得再退回 PNG 多视角交付，不要假装已打开；
  命令行会把安装指引与降级建议一并打印出来。

参数化重建（改参数、重导出的闭环）

> 这就是约定 4 的存在理由：.solidcraft 是唯一能进入这条闭环的入口。
> 每次建模都必须先产出工程文件、再产出 STEP——工程文件是交付物，不是可选项。

# 1) 建 + 存工程包（.solidcraft 是 zip，内含 document.json 明文参数表与特征时间线）
python scripts/sc.py run 建件脚本.json --save 工程.solidcraft --results

# 2) 载入工程、改参数、重建、导出
python scripts/sc.py run 参数覆写脚本.json --in 工程.solidcraft --out 变体.step

三个易踩的点：

• 重放工程文件不会重新执行 file.export（导出只在当初那次执行产生副作用）。
  要出图必须显式给 --out：run 工程.solidcraft --out 结果.step。
• 中文名不要拿 STEP 去对账：写进 STEP 时按 ISO 10303-21 转义是正确的，但引擎自家 eval
  读回只解出第一个 \X2\…\X0\ 转义（底板 → 底\X2\677F\X0\）。要按名对账请对
  .solidcraft 工程文件做（eval 件.solidcraft 名字完好），或用 component.properties；
  sc.py stepinfo 已内置转义还原。下游 CAD（SolidWorks / UG / FreeCAD）显示正常。
• 交付清单固定为「工程文件 + 派生件」两段：<件名>.solidcraft 在前，<件名>.step（及
  需要的 .stl/.obj/.3mf）在后。只交 STEP 视为未完成——用户将无法改参。
• 装配体的工程文件里必须有组件树（约定 6）：document.json 的 components + occurrences
  会连位姿一起入库，回放和改参后结构不丢；只保存实体、不建组件，交付的工程文件也一样是平铺的。
• 用户要自己查看时，用桌面本体打开这份工程文件（约定 5）：python scripts/sc.py open 件.solidcraft。

中文命名就是改参接口

[
  {"command": "parameters.add", "params": {"name": "板厚", "expression": "10 mm", "comment": "底板厚度；改这一处即可"}},
  {"command": "solid.box", "params": {"length": "板长", "width": "板宽", "height": "板厚", "body_name": "底板"}},
  {"command": "solid.hole", "params": {"diameter": "孔径", "position": ["孔边距", "孔边距", 0], "targets": ["底板"]}}
]

• 改一个尺寸：parameters.change {name: "板厚", expression: "16 mm"} —— 依赖它的拉伸、孔深、
  圆角、装配位姿一起重算，不用碰几何步骤。
• 改一个特征：edit_feature / timeline.* 按中文特征名定位，不依赖步骤序号；
  序号会随插入/删除漂移，名字不会。
• 出一批变体：parameters.list 读参数表 → 批量 parameters.change → file.export 到新文件名，
  一份工程文件覆盖一个系列。
• 命名口径：2–6 个汉字、见名知义、同一设计内唯一（底板 / 上截面 / 滚轮组），
  不要 零件1、不要 Part、不要纯拼音缩写；参数名优先用工程术语（板厚、孔径、孔边距）。

装配体建模（组件树 → 嵌套 STEP）

> 约定 6 的可执行版本。多实体模型必须走这条路，否则交付的 STEP 只是一个「塞了 N 块实体的零件」。

三步骨架（可直接改写 templates/assembly-components.json）：

[
  {"command": "solid.cylinder", "params": {"diameter": 47, "height": 12, "base": [0,0,0], "body_name": "外圈"}},
  {"command": "solid.cylinder", "params": {"diameter": 6.35, "height": 6.35, "base": [15.63,0,3.175], "body_name": "滚珠"}},

  {"command": "component.from_bodies", "params": {"bodies": ["外圈"]}},
  {"command": "component.create", "params": {"name": "滚珠组", "parent": "root"}},
  {"command": "component.from_bodies", "params": {"bodies": ["滚珠"]}},
  {"command": "occurrence.copy", "params": {"occurrence": "滚珠:1", "translate": [0, 0, 0]}},
  {"command": "component.activate", "params": {"component": "root"}},

  {"command": "component.properties", "params": {"component": "root"}},
  {"command": "file.save_as", "params": {"path": "轴承.solidcraft"}},
  {"command": "file.export", "params": {"path": "轴承.step", "format": "step"}}
]

要点：

• component.create 会激活新组件，紧接着的 component.from_bodies 就落进它；记得
  component.activate {"component": "root"} 回根，否则后面的实体全跑进这个子装配。
• 重复件用 occurrence.copy 而不是复制实体：几何只存一份，STEP 体积随重复数几乎不增长
  （10 颗滚珠 ≈ 一份几何 + 10 条 NAUO）。旋转放置用 occurrence.move {occurrence, axis, angle}。
• 归位后不要再改几何：solid.* 只作用于当前激活组件的实体。
• component.insert_design {path: "零件.solidcraft"} 可把另一个工程当外部引用组件插入
  （自顶向下设计）；component.links / update_links / break_link 管理这些引用。
• 交付前用 sc.py stepinfo 件.step 读回结构自证；用 component.properties 逐件核对体积与位姿。
• 参考：@references/recipes.md 配方 F（6005 轴承嵌套装配实测）、
  @references/command-reference.md 的装配命令族。

命令目录

引擎自带 570 条命令（0.30.1 实测 570 条，其中 443 条启用）。0.30.1 的命令面与 0.30.0
逐条相同（新增 0、移除 0、启停 0），只有 14 条参数文案/签名放宽，没有一条改变实体：
parts.insert 增加英制紧固件（hex_cap_screw_inch / hex_nut_inch / washer_sae / washer_uss，
规格写 1/2-13 UNC、1/2，长度仍按 mm）、sheet.perforate 新增 sketch + profiles
（只在草图轮廓内打孔）、solid.pattern.circular 的原点坐标可写长度表达式、sketch.rectangle.rounded
的角点坐标可写表达式、construct.plane.tangent 新增 reference + angle、solid.move 新增
occurrences（按组件复制，而不是把实体拷进活动组件）、sketch.trim 回执新增 offset_released、
parts.library 的族信息新增 system: metric|inch；两处会改变脚本读法：
① file.save / file.save_as 拒收 .step / .stl / .dxf 这类「按名字会被当成别的文件」的路径
（导出请用 file.export*）；② parameters.add / change / list 的 value 统一改为 mm（角度为度），
用户自定义单位移到新增的 display_value，读这些回执的脚本要复核。
0.30.0 是格式 46 → 47 的功能版：较 0.29.0
新增 15 条、移除 0、启停变化 0、参数签名变化 26 条：最实用的是五条专用导出命令
file.export_step / file.export_stl / file.export_3mf / file.export_obj / file.export_urdf
（每格式一条，可各自绑快捷键，回执直接给 bytes）与图像比对 inspect.compare_picture
（模型轮廓对参考 PNG/JPEG，回重叠率、边缘差 mm、叠加图）；其余为 construct.plane.axis_point、
component.hide_history / show_history、component.move_sketches.to_parts、render.compare.divider、
ui.assistant，以及三条上下文门控项（render.result.select / discard 需先渲染、
sketch.spline.remove_point 需在草图内）——没有一条改变实体。
参数侧扩能（全部可选，不传即与 0.29.0 一致）：sketch.offset 新增 instances（一次多份等距偏移）、
sketch.construction_line.* 新增 length（定长线段而非无限长）、绘制椭圆即可输入长短半径、
loft / surface.loft 可从一个草图取两个截面、inspect.measure 支持构造几何与 names_only。
0.29.0 为 555 / 431（新增 2 条：assembly.mass_properties（整装配质量/质心/惯量，只读）
与 view.status_details（界面状态与接缝连续性诊断，只读）；真正扩能在参数放宽——
solid.align 的 axes、sketch.equation_curve 的 variable_unit、矩形/圆坐标写表达式、
sketch.chamfer.* 与 sketch.fillet 的 points 一次多个角、sketch.offset 默认串链、
select.set 面/边可只用点或索引、joint.edit 可重拾两侧）。
0.28.0 为 553 / 430（新增 11 条：body.print_face（打印面）+
sketch.construction_line 及其 .horizontal / .vertical / .angle / .parallel /
.perpendicular / .tangent_at / .tangent_external / .tangent_two / .bisector（10 条构造线，
无头会话里因「未进入草图」显示不可执行））。
0.27.1 较 0.26.1 新增 14 条（7 条设置档、component.move_features、
component.paste_from_design、browser.reparent、occurrence.align、view.status_items、
sketch.equation_curve 与 .edit）。
新增里没有一条会改变实体；两条方程曲线命令在无头会话里显示不可执行，原因是
「尚未进入草图」的上下文门控，不是未实现——「尚未支持」清单仍是 3 条
（surface.fillet、render.compare、render.batch），与 0.26.1 相同。
参数签名变化 17 条，唯一扩展建模能力的是 sketch.dimension 可量模型边/顶点（先投影进草图）、
sketch.intersect / sketch.project 新增 projection_link（默认 true，即旧行为）、
parts.insert 新增 button_head_cap_screw（ISO 7380-1，M3–M16）；
不传新参数即与 0.26.1 完全一致，存量脚本无需改动。
0.28.0 为 553 / 430（新增 11 条、移除 0、启停 0、参数签名变化 12）：新增的是
body.print_face（打印面：标定某体哪个平面朝下，切片导出据此摆放，设计本身不动）与
sketch.construction_line.* 10 条（无限长构造线，非实体图元）；参数签名里唯一扩展建模能力的是
parts.insert 的 at 可传多孔位数组（一个组件、每孔一座、一孔一关节）。
0.29.0 也没有新增任何能改变实体的建模命令（七模板体积与 0.28.0 逐位一致、8 个 STEP 逐字节相同）。
0.30.1 同样零建模增量（七模板体积与 0.30.0 逐位一致、8 个 STEP 逐字节相同），
但它把设计文件格式从 47 抬到 48，门槛随之从 0.30.0 前移到 0.30.1——
格式 48 的内容来源是带表达式的圆周阵列原点、从草图生成的孔排轮廓、相切平面的参考与角度。
这是第四个「修订号版本抬格式」先例（前三个：0.22.1 / 0.23.1 / 0.24.1）。
0.30.0 也是零建模增量（七模板体积与 0.29.0 逐位一致、8 个 STEP 逐字节相同），
它把设计文件格式从 46 抬到 47（组件可从历史栏隐藏、跨组件面引用记住存放位置、过轴线与点的构造平面），
门槛随之从 0.29.0 前移到 0.30.0。
0.29.0 把格式从 45 抬到 46（按选定轴对齐、方程曲线变量带区间单位、链接设计文件摘要），
门槛随之从 0.28.0 前移到 0.29.0。
0.28.0 同样零建模增量（七模板体积与 0.27.1 逐位一致），把格式从 44 抬到 45
（浏览器组嵌套与排序、点云属性与过滤、打印面），门槛随之从 0.27.0 前移到 0.28.0。
0.27.1 为 542 / 429（新增 14 条设置档/归位/界面状态命令，零建模增量，格式仍 44），
0.27.0 把格式从 43 抬到 44（方程曲线 + 装进 History 文件夹的关节），门槛随之到 0.27.0。
0.26.1 为 528 / 417（新增 14 条、启停 4 条转正，零建模增量，格式仍 43），
0.26.0 为 514 / 399（新增 21 条，唯一新增的几何相关族是 pointcloud.*——点云是参考几何、
永不成实体、不导出 STEP），那一次改的是设计文件格式 41 → 43。
0.25.1 为 493 / 379（修复版，命令面零增删，只修装配 Join 跨组件合并的回归），
0.25.0 同为 493 / 379（较 0.24.1 新增 11 条但 8 条未实现、3 条纯 GUI 回显，零建模增量），
0.24.1 为 482 / 376（较 0.24.0 新增 8 条建模与文件互操作命令：solid.cone、sketch.transform、
canvas.to_sketch、sketch.drawing_bounds、component.copy_bodies、occurrence.reparent、
file.send_to_slicer、file.open_in_easyprint），
0.24.0 为 474 / 369（新增 11 条：九条 view.* 视图控制、sketch.arc3d、document.revision），
0.23.1 为 463 / 359（新增 component.cycle_color 与 inspect.colored_components），
0.23.0 为 461 / 357（那次命令面一条没动，改的是设计文件格式 37 与 GUI），
0.22.1 为 461 / 357（新增 inspect.parameter_sweep 与 sheet.path_flange），
0.22.0 为 459 / 355（新增大头：render.* +32、frame.* +4、view.* 标准视图 +7、browser.* +2），
0.21.0 为 411 / 309，0.16.2 为 394 / 294——命令数随版本增长，不要背数字。查询：

python scripts/sc.py commands            # 全部
python scripts/sc.py commands fillet     # 按关键字过滤
python scripts/sc.py commands --json     # 机器可读

常用命令的分组索引与参数要点见 @references/command-reference.md。

上游学习资料（upstream-*）

上游源码仓库有三个资料文件夹（skills/、examples/、docs/）。本技能包内容一个不删，
但在 SkillHub 版里三者一律不随包内嵌，改由安装后按需从上游官方源下载（平台对文件类型与
包体有硬限制，瘦包才能通过校验；WorkBuddy 标准发布包 solidcraft-modeling-<版本>.zip
内嵌前两者，仅 docs/ 按需下载）：

包根目录另有 5 个授权文件（upstream-LICENSE-MIT.txt、upstream-LICENSE-APACHE.txt、
upstream-NOTICE.txt、upstream-ATTRIBUTION.md、upstream-THIRD-PARTY-LICENSES.txt），
是再分发上游文本的合规要求。本版前三个补了 .txt 扩展名（内容逐字节未改）——
SkillHub 只收白名单内的文件类型，无扩展名的文件会被判「不允许的文件类型」而拒收整包。

目录结构经双下划线扁平化（docs/book/src/guide/mcp.md → upstream-docs/book__src__guide__mcp.md），
完整映射表与版本固定在 upstream-manifest.json。

上游资料的按需下载

三个资料文件夹全部登记在 manifest 的 pending_docs[] 中（共 485 个文件 / 42.3 MB），
安装后补齐：

python scripts/fetch_upstream.py --check      # 看缺什么
python scripts/fetch_upstream.py              # 补齐（幂等；先写 .part 再原子改名，可中断续跑）
python scripts/fetch_upstream.py --detach      # 后台分离进程，立即返回（推荐）
python scripts/fetch_upstream.py --budget 600  # 限时 600 秒，到点收工，下次继续
python scripts/fetch_upstream.py --all         # 连授权文件一起逐字节校验自愈

首次使用本技能时，用 --detach 起一个后台补齐进程即可，不要等它跑完——下载耗时与该次
建模任务无关，资料缺席也不影响任何建模与导出功能；upstream-skills/ 与 upstream-examples/
只在翻上游 skill 定义、参考手册与可跑范例时才用到，需要时再补也不迟。

下载走镜像（ghfast.top → ghproxy.net → 官方直连）回退，每个文件按长度 + git blob sha
双重校验后才落盘，未通过校验的一律丢弃并列入失败清单。

上游发新版后如何跟进

资料版本与 CLI 二进制版本都按同一 tag 对齐。本技能每天第一次被调用时会自动检测上游版本，
检测到落后即自动更新资料、docs/ 与 CLI 引擎（见约定 7）——通常不需要手工介入。
需要主动核查或强制重查时：

python scripts/sc.py upstream           # 检测 + 落后即自动更新（当日已检测则跳过联网）
python scripts/sc.py upstream --check   # 只检测不更新（有落差时退出码 1）

手工逐步执行（两步都幂等）：

python scripts/sync_upstream.py --tag v0.13.1    # 重建清单（pending 清单随之刷新，不落盘资料）
python scripts/fetch_upstream.py                 # 按新清单补齐 docs / skills / examples

sc.py ensure 固定 CLI 二进制版本；sync_upstream.py 固定资料版本。本（SkillHub）版
sync_upstream.py 按瘦包口径运行（不内嵌资料、授权文件名带扩展名）。

参考文档

模板

以下 7 个模板均经端到端实测通过，可直接改用。模板内已按约定 4 内置
file.save_as（存工程文件）→ file.export（导 STEP）的顺序；多实体模板另按约定 6 内置组件树；
草图、实体、参数一律中文命名（约定 10），照抄即合规、可直接过 lint：

下表回执为 SolidCraft 0.30.1（2026-11-03 复测）（较 0.30.0 命令面 570/443 → 570/443，
新增 0 条、移除 0、启停 0、参数签名变化 14，无新增改变实体的建模命令）：
7 个模板（含钣金折弯盒）lint rc=0、run rc=0；用 0.30.1 探测引擎与本版对跑，体积/面数/边数
逐位一致（rel=0.00e+00），7 个 STEP 与 0.30.0 逐字节相同（连齿轮样张共 8 个），与 0.18.3 以降各版也全部逐位一致；
STEP 装配结构不变。
⚠ 样条齿轮样张仍带微漂：0.30.1 下体积 224,772.2039489307 mm³（与 0.30.0 / 0.29.0 / 0.28.0 同值，
相对解析基线 3.38e-10），面/边/顶点 303/902/602 完全不变——判据为「相对偏差 ≤1e-6 且面/边/顶点全等」，
详见 @references/pitfalls.md 的格式号一节。
本次对照脚本见正文口径：SOLIDCRAFT_CLI=<解压引擎> sc.py --no-strict run … 与基线各跑一遍取
total.volume_mm3。齿轮样张 m2/z50 解析基线仍为 224,772.20402488284 mm³ / 303 面（902 边 / 602 顶点）。
无头快照（sc.py snapshot）实测仍走 GPU 渲染器（1280×800 PNG 正常产出）。
工程文件实证 document.json 的 format = solidcraft/48（七模板 + 齿轮样张共 8 个工程包逐个核对；
0.30.0 写的是 47，0.30.0 及更早打不开 0.30.1 存的文件）。
工程文件会明显变大：0.17.0 起 file.save_as 默认 cache: true（把已求值模型压进工程包），
如 batch-export 的 .solidcraft 由 864 B 升至 23,186 B；要控制体积就显式写 "cache": false
（回到 874 B），代价是本体重开时按时间线重算、且失去内嵌缩略图。
未指定材质时质量按默认密度 1.29 g/cm³ 计（报重量前务必 material.assign，见后文口径）。

生成脚本后请先跑 python scripts/sc.py lint <脚本> 再执行；
交付装配体前再跑 python scripts/sc.py stepinfo <件>.step 确认嵌套结构已写入。

> 引擎升级不需要改存量脚本：0.14.0 → … → 0.29.0 → 0.30.0 → 0.30.1 二十四次升级，模板的
> 体积回执始终逐位一致或仅在 1e-7 相对量级内微漂（51,618.767 / 185,840.37 / 98,535.235 /
> 168,000.000 / 125,673.66 mm³），STEP 装配结构（NAUO 条数与层级）也从未变化。
> 唯一出现过数值微漂的是样条齿轮样张（0.26.1 起，相对 3.4e-10），七个实体模板始终逐位一致。
> 唯一会变的是工程文件体积与格式号（0.17.0 起的模型缓存；0.18.3 起格式 29、0.19.0 起格式 30、0.20.0 起格式 31、0.21.0 起格式 34（号段跳过 32/33 为 rc 占用）、0.22.0 起格式 35、0.22.1 起格式 36、0.23.0 起格式 37、0.23.1 起格式 38、0.24.0 起格式 39、0.24.1 起格式 40、0.25.0 起格式 41（0.25.1 仍是 41）、0.26.0 起格式 43（跳过 42，不存在写 format 42 的发行版；0.26.1 仍是 43）、0.27.0 起格式 44（0.27.1 仍是 44）、0.28.0 起格式 45、0.29.0 起格式 46、0.30.0 起格式 47、0.30.1 起格式 48）。所以升级后只需复核三点：
> lint rc=0、run rc=0、stepinfo 的 NAUO 结构。
> 0.26.0 / 0.27.0 / 0.28.0 / 0.29.0 / 0.30.0 / 0.30.1 都是「格式前移即门槛前移」的一版：0.26.0 从 41 跳到 43
> （0.25.1 及更早打不开），0.27.0 从 43 到 44（0.26.x 及更早打不开 0.27.x 存的文件），
> 0.28.0 从 44 到 45（0.27.x 及更早打不开 0.28.0 存的文件），0.29.0 从 45 到 46
> （0.28.x 及更早打不开 0.29.0 存的文件），0.30.0 从 46 到 47
> （0.29.x 及更早打不开 0.30.0 存的文件），0.30.1 从 47 到 48
> （0.30.0 及更早打不开 0.30.1 存的文件），六次都同步抬了门槛。
> 而 0.25.1、0.26.1、0.27.1 都是「版本前进、格式不动」的一版
> （分别只修装配 Join 回归、安全与渲染补丁、SolidCraft 95 主题可读性与旧设计重建），
> 门槛没动、只抬默认下载版本——两种情形都要按正文的格式号判断，不看版本号。

已知限制

• 引擎门槛 0.30.1（默认下载版本 0.30.1，本轮两个开关同版）：低于门槛的副本（0.9.x – 0.30.0）不予选用。
  三条理由：① 0.30.1 起设计文件格式升到 48（0.30.0 为 47、0.29.0 为 46、0.28.0 为 45、0.27.0 / 0.27.1 为 44、0.26.0 / 0.26.1 为 43、0.25.0 / 0.25.1 为 41、
  0.24.1 为 40、0.24.0 为 39、0.23.1 为 38、0.23.0 为 37、0.22.1 为 36、0.22.0 为 35、
  0.21.0 为 34、0.20.0 为 31、0.19.0 为 30、0.18.4 为 29、0.17.0–0.18.2 为 28；
  32/33 号段为 rc 占用、42 与 43 同版一并引入，均属跳过号），
  0.30.0 及更早打不开 0.30.x 存的工程文件
  ——0.22.1 / 0.23.1 / 0.24.1 / 0.30.1 都是修订号版本却抬了格式的先例，
  既别看版本号位数猜、也别看命令面计数猜，混用会让交付链路
  直接断在「对方打不开」这一步；② 本技能配方直接依赖的 solid.loft 导轨（rails/rail_fit）、
  solid.extrude 的双面/到对象/薄壁（direction/distance2/to/thin）与 solid.fillet 的
  变半径 + fit: reduce 从 0.17.0 才齐备；③ 装配交付所需的 assembly.bom（物料清单）与
  component.metadata.set（图号）只在 0.17.0 起存在。
  只装了旧版的机器上，ensure/init 会跳过它并走下载或覆盖流程；sc.py versions 会标出
  「低于门槛」这个未被采用的原因。升级后必须同时确认桌面本体也已换版（同目录 solidcraft.exe）——
  只换 CLI 会留下半装，旧本体打不开新格式文件，versions 会显式打「⚠ 半装」提示。
  门槛与默认下载版本是两个独立开关：门槛只跟 writes design file format N 走，
  默认下载版本跟最新正式版走。0.30.1 是「格式 47 → 48、门槛与默认版本同时前移」的情形
  （与 0.26.0、0.27.0、0.28.0、0.30.0 同型）；0.27.1 是「格式仍 44、门槛不动（0.27.0）、只抬默认下载版本」的情形，
  0.25.1 与 0.26.1 是同型的两个先例。
  两种情形都只看正文的格式号，不看版本号位数、也不看命令数是否变化。**
• 曲面能力随版本变化明显。实测 0.10.0：surface.* 全部不可用；实测 0.11.0：仅
  surface.ruled / boundary / blend / untrim / fillet 与 inspect.continuity 未实现；
  实测 0.13.1：surface.ruled / blend / untrim 已转可用；实测 0.14.0：surface.* 18 条只剩
  surface.fillet（#769）未实现，inspect.continuity（#770）仍未实现；
  实测 0.17.0：surface.* 19 条中 18 条可用（surface.boundary 支持三/四条曲线环与曲线网建面），
  inspect.continuity 也已转可用——整个引擎真正未实现的命令只剩 surface.fillet 这 1 条
  （404 条中其余 101 条禁用里，97 条是 sketch.* 交互态前置，material.edit / material.delete
  需先建物理材质，diagnostics.crash_test 需设环境变量）。0.17.0 新增的 10 条命令见
  @references/command-reference.md §1.2。
  solid.boundary_fill 仍是另一个命令（布尔语义），不要与 surface.boundary 混用。
  → 动手前先跑 python scripts/sc.py commands surface 确认当前版本的实际可用集合。
• surface.thicken 对开式（非可定向）曲面必然失败（the thickened surface does not close）：
  单侧曲面没有连续的全局法向，±t/2 偏置在接缝处错开一个壁厚。要实体就扫闭合截面再
  surface.stitch（缝合前体积为负、缝合后转正）。详见 @references/pitfalls.md P2-11。
• 带扭转的扫掠体首选 surface.sweep + twist（0.17.0 实测一圈成单侧面，见
  @references/recipes.md 配方 E 与 templates/mobius-strip.json）；只有扭转律沿程非线性或
  截面形状中途变化时，才退回「逐段两截面 solid.loft + operation:"join"」的绕路
  （48 段 −0.36%、144 段 −0.02%，见同配方第八节）。
• parts.insert 的螺钉坐姿由拾取点决定且不报错（同一个孔，拾取孔口与拾取孔壁中点会得到
  相反的朝向）。标准件装配必须渲染目视复核，不能只看 rc=0 和干涉数为 0。
• 草图文本依赖 Liberation Sans，中文文本渲染能力未验证。
• 安装位置与更新去向遵循约定 8：本机系统已装 SolidCraft（CLI 或桌面本体）→ 一律用本机那份，
  更新时就地覆盖；本机未装 → 托管目录 ~/.solidcraft/bin/ 首次安装并在那里覆盖。
  在只有 CLI 的机器（或无桌面环境）上，「用本体打开」不可用，须按约定 5 退回多视角 PNG。
• 覆盖正在运行的桌面本体会被 Windows 拒绝（文件占用）——更新前请先关闭本体。
• 平铺 STEP 的坑不会自己暴露（约定 6）：不建组件树时 STEP 里只有 1 个 shape representation，
  rc=0、体积面数全对、eval 也读得出 13 个实体——只有 stepinfo 或在下游 CAD 里看
  结构树才能发现。交付装配体前务必跑一次 stepinfo。
• 装配命令族（component.* / occurrence.* / joint.*）在无头 CLI 下实测可用
  （0.14.0 全族 36 条命令均为启用态：component 17 + occurrence 4 + joint 15——
  component.from_bodies / component.create / component.activate / component.list /
  component.properties / occurrence.copy / occurrence.move / component.insert_design /
  joint.create / joint.solve 等；0.14.0 新增 joint.gear / joint.rack_pinion /
  joint.screw / joint.reach，运动副与逆运动学也跟着进了无头能力）：
  但没有「一次调用把选中实体建成多级树」的批量命令，层级要靠 create + activate 逐层搭。
• 钣金命令族 sheet.* 13 条全部启用（0.14.0 起 12 条，0.22.1 增 path_flange：flat_pattern / unfold / fold /
  refold / flange / path_flange / hem / perforate / export_dxf / export_bend_table 等）。
  折弯盒配方已验证（0.20.0 首测、0.23.1 复测，照 @references/recipes.md 配方 H 与
  templates/sheet-metal-box.json 抄）：草图 → sheet.flange base → sheet.flange edge
  的链路稳定、改参闭环可用。仍未固化的：hem（卷边）、perforate（冲孔）、
  复杂多壁/非 90° 折弯、unfold/refold 往返；边缘法兰 height 按「底面到外侧面总高」
  语义、展开图必须走 base flange 路线（见配方 H 第二节）；edge_names 是存档机制、
  CLI 输入只认拾取点。
• 未覆盖：运动仿真求解（joint.* 只在装配求解层面验证过，未做时域仿真）、配置表、云/PDM。

在 WorkBuddy 中的名称（规则，勿单方面改）

显示名的单一真源是工作区根的 release_names.py：python build_release.py 每次构建先写入、
后复查（SKILL.md 的 display_name / display_name_en / 一级标题 + connector-meta.json
的 name / name_zh / name_en），两侧不一致直接判不通过，因此不会出现「技能包叫 A、连接器叫 B」。
本机测试版只在真源值后加「（测试版）」后缀（见 install_local_test.py）。

来源与许可

本技能封装的是第三方开源软件 SolidCraft（<https://github.com/tangency-labs/solidcraft>，
官网 <https://solidcraft.io>），作者 Ben Herbruck，双许可 MIT OR Apache-2.0，无 GPL 传染。
> 仓库 2026-10 由个人账号 bherbruck/solidcraft 迁到 Tangency Labs 组织（同一个 repo，
> 旧地址 301 跳转仍有效）；技能内所有脚本的 REPO 已改新名，并把旧名留作 REPO_LEGACY 回退。

• 本技能不重打包该软件的任何二进制：一律下载官方原版发行包并用官方 SHA256SUMS.txt
  校验完整性后安装（按约定 8 落到本机安装目录或托管目录）。技能包自身只含文本与脚本，
  二进制随 .zip / .tar.gz 交付物一并留在本地缓存中，不再分发。
• 也可完全跳过下载：只要用户本机已装有版本不低于门槛的 SolidCraft，技能直接复用（约定 8）。
• 上游仓库的文本资料（skill 定义、文档、范例脚本）依 MIT OR Apache-2.0 再分发；
  授权文件随包提供于 upstream-LICENSE-MIT.txt、 upstream-LICENSE-MIT.txt、
  upstream-LICENSE-APACHE.txt、upstream-NOTICE.txt、upstream-ATTRIBUTION.md、
  upstream-THIRD-PARTY-LICENSES.txt。
• upstream-skills/、upstream-examples/、upstream-docs/ 均不随包分发，由用户在安装后自行
  从其官方源下载（见上一节），避免包体超限与被平台判为不允许的文件类型。
• 卸载：删除 ~/.solidcraft 目录即可（不影响用户自行安装的 SolidCraft）；删除技能包目录亦不影响。
• 本技能内的命令参考与坑清单来自对官方文档与实际运行的实测整理；实测环境为
  Windows / SolidCraft 0.9.0 – 0.30.1（门槛 ≥0.30.1，默认下载 0.30.1）。上游处于活跃开发期，API 尚未冻结，行为可能随版本变化；
  本技能每天第一次被调用时会自动检测并跟进上游版本（约定 7），因此应以 sc.py commands
  与实测回执为准，而不是以文档中标注的某个历史版本号为准。