实机自检说明
swforge selftest 是给这台机器做的体检。v1.4.1 共十三项检查，每一项都在真实
SolidWorks 上跑，读回结果再判定。
为什么需要它
同类项目的用户报过这些问题（都有 issue 编号可查）：
- 切了文档但没真正激活，后续操作作用到错误的零件上（andrewbartels1 #91）
- 导出时顺手打开装配，用完不关，跑几次内存爆（#101）
- 自动标注的回读数返回 0，其实尺寸已经建出来了（#100）
- API 查询报出根本不存在的成员，LLM 照着编（#195）
- 连不上就卡住，报错看不出怎么修（vespo92 #1）
swforge 声称这些都处理了。声称不算数，所以做成可执行的检查。
另外，CI 跑不了实机（GitHub 的机器上没有 SolidWorks），
所以 32 个实机测试在 CI 里是跳过的。selftest 补的就是这块空白。
检查内容
v1.4 新增第十一项粗糙度类型/Ra/位置回读、第十二项 ±0.1 mm 公差回读及名义值不变。
v1.4.1新增第十三项显式配合，检查持久引用、原生配合面身份及几何误差；专项入口为 examples/verify_face_mates.py。
完整标注验收另运行 python examples/verify_annotations.py --work-dir <新目录> --keep，
包含保存重开与 PDF 渲染；详见 标注文档。
1. 连接与版本
读 SolidWorks 的版本号和一次 ping 的往返耗时。
失败含义：SolidWorks 没启动，或启动了但没注册到 COM。
2. 文档切换后真正激活
建两个零件，来回切三次，每次都回读 ActiveDoc 的标题。
为什么这么测：ActivateDoc 返回成功不等于真的切过去了。
同类项目就是漏了回读这一步，导致后续所有操作作用到错误的零件上。
失败含义：切了没生效，你的操作可能改到了别的零件。
3. 资源守卫与清扫
连建三个文档，看文档数有没有超上限，再用清扫收回。
为什么这么测：SolidWorks 默认只允许 8 个文档。用完不关的话， 跑到第 9 个就失败，而且报错往往看不懂。
失败含义：要么守卫没拦住（超了上限），要么清扫收不回来（泄漏）。
4. 几何回读准确
建一个 100×20×50 的板，回读体积，和理论值 100000 mm³ 比对。
为什么这么测：同类项目有过「回读返回 0」的问题 —— 调用看起来成功，实际什么都没读到。
判定标准：偏差必须小于 0.1%。
5. 材质真的赋上（密度≠1000）
建零件、赋 Q235、然后用 mass / volume 反算密度。
为什么这么测：这是本项目发现的坑 —— SolidWorks 的默认密度是 1000 kg/m³，也就是水的密度。 没赋材质时不会报错，只会让质量错 7.85 倍。
判定标准：反算密度必须是 7850 左右，不能是 1000。
6. 干涉体积精确
两个 20mm 立方沿 X 偏移 10mm 装在一起，重叠部分是 10×20×20 = 4000 mm³。
为什么这么测：同类项目这次调用经常返回 0 或 None。
判定标准：报告出干涉、给出体积、偏差小于 2%。
这一项在开发过程中抓到一个真 bug：
GetInterferences是属性不是方法，调用抛的TypeError被吞掉， 结果是「计数 1、明细空」。见 问题日志。
7. 配合真正加成功
两个零件分别在 x=0 和 x=60，加一个同心配合，看位置有没有变。
为什么这么测：AddMate5 的 errStatus 语义反直觉 ——
swAddMateError_NoError 的值是 1 不是 0，很容易把成功判成失败、
把失败判成成功。所以不看返回值，看位置有没有真的变。
判定标准：配合前后组件包围盒中心必须不同。
8. 出图与尺寸值正确
建一个 160×20×100 的板，出 A3 图，加受控标注，检查尺寸值。
为什么这么测：尺寸可能标出来但是错的值。 开发中就遇到过右视图标成 114 而实际是 120 —— 因为用模型坐标 X/Y 找极值，但右视图的屏幕水平方向对应模型 Z。
判定标准：尺寸数 ≥ 4、值不能是 0、必须出现总长 160。
9. API 反射探测
用 .NET 反射读 SolidWorks.Interop.sldworks.dll，列出 28 个关键 API
是否真的存在。
为什么这么测：同类项目有过「API 查询报出不存在的成员， LLM 照着编代码」的问题。这里的结论来自真实反射，不是查文档。
怎么读输出
[PASS] 干涉体积精确 11.61s 报告 1 处干涉，明细 1 条，体积 4000.0 mm³（理论 4000），偏差 0.00%
[FAIL] 材质真的赋上 3.59s 密度反算 1000 kg/m³（等于水的密度，材质没真赋上）
每一行三段：
- PASS / FAIL
- 耗时 —— 异常长说明这一步在重试
- 证据 —— 具体读到了什么，不是笼统的「成功/失败」
失败时额外给出「这一项对应的问题」，说明它保护的是什么。
退出码
| 码 | 含义 |
|---|---|
| 0 | 全部通过 |
| 1 | 有失败项（或连不上 SolidWorks） |
可以直接接进你自己的脚本或 CI：
swforge selftest
if ($LASTEXITCODE -ne 0) { Write-Host "这台机器功能不完整" }
参数
| 参数 | 作用 |
|---|---|
--only <词> |
只跑名称或标题含该词的检查 |
--keep |
保留产物目录，便于事后查看 |
--work-dir <路径> |
指定产物目录 |
--json |
输出 JSON，便于机器解析 |
例子：
swforge selftest --only interference --keep
swforge selftest --json
它不能验证什么
不要把这个当成「图纸可投产」的证明。
十三项检查验证的是工具的行为正确，不是你画的零件对。
以下这些它管不了：
- 设计本身合不合理
- 公差选得对不对
- 材料选得对不对
- 图纸满不满足你这个行业的具体规范
项目对外的定位一直是「把验证做到工具层面」，不是「替代工程师」。