AryaVora621/agentcad

agentcad 是做什么的？

1. 核心规则

绝不报告您未使用 agentcad 从构建几何体中实际测量得到的尺寸、间隙或 PASS 结果。参数是意图，而非证据。您在 model.py 中键入的值告诉您您想要什么，而非实际存在什么。

2. 工作循环

agentcad new my-part --template blank      # 或 bracket, box-with-lid
# 编辑 my-part/model.py 和 my-part/agentcad.toml
agentcad check my-part --json              # 构建，然后测量
agentcad render my-part                    # build/renders/: 每个视图一张 PNG，外加 sheet.png
agentcad view my-part                      # 实时查看器，供人类使用

1. 首先或在建模过程中编写针对需求的检查（第 3 节）。
2. 运行 agentcad check --json。阅读每个 FAIL：summary、measured、limit、where。
3. 在 where 命名的位置修复几何体。重新运行。除非需求本身发生了变化，否则不要编辑限制值来使 FAIL 消失。
4. 运行 agentcad render 并使用支持图像的工具打开 sheet.png。在说出它看起来正确之前先查看它。渲染能发现明显的错误（缺失特征、错误一侧）；但它们永远无法证明厚度、间隙或重叠。
5. 重复直到所有检查通过。在最后一次编辑后再次运行 agentcad check。

overhang 检查忽略位于热床上的面以及中心位于 first_layer_mm（默认 0.3）以下的下方面，因此底部边缘倒角不会被计入；豁免的区域报告为 first_layer_area_mm2。

使用 --only ID,ID 重新运行选定的检查，仅在 build/ 目录为最新时使用 --no-build。

3. 将需求转化为检查

需求中的每个功能需求都成为 checks(ctx) 中的一个检查。探测实体（第 4 节）替代与之配合的物体。以下所有名称均为真实 API。

配合变成间隙测量：

def checks(ctx):
    play = ctx.play("lid", "box", direction=(1, 0, 0), max_mm=2.0)
    ctx.expect("lid_side_play", play if play is not None else 2.0, min=0.15, max=0.4, part="lid")

“盖子能打开”变成滑动测试：

    sweep = ctx.slide("lid", "box", direction=(0, 0, 1), distance=15.0, steps=40)
    ctx.expect("lid_lifts_free", max(s["overlap_mm3"] for s in sweep), max=0.01, unit="mm3", part="lid")

“M4 螺丝能穿过”变成一个必须不碰撞且必须靠近孔的探测圆柱体：

    import cadquery as cq
    screw = cq.Workplane("XY").circle(2.0).extrude(30).translate((10, 0, -5))  # 4.0 mm 螺杆
    ctx.expect("screw_interference", ctx.interference("bracket", screw), max=0.01, unit="mm3", part="bracket")
    ctx.expect("screw_wall_gap", ctx.distance("bracket", screw), min=0.0, max=0.5, part="bracket")

距离范围证明了螺丝实际上靠近孔，而不是在 14 毫米外且没有重叠。

“能在打印机上打印”是内置的 bed_fit 检查：在 agentcad.toml 中设置 [printer] 为实际机器（profile 或 bed = [X, Y, Z]）。“壁厚足够坚固”是 [checks] 下的 min_wall_mm。

4. 探测实体

根据需求构建替代配合物的实体，永远不要从模型自身的参数中读取。一个 M4 螺丝是一个 4.0 mm 的圆柱体。一个 54 mm 的球体是一个 54 mm 的球体。一根线缆是沿其路径的圆柱体。一只手是与手尺寸相同的盒子。如果探测实体读取了与构建孔相同的变量，那么检查永远无法失败。

探测实体是已位于使用坐标系中的 cq.Workplane 或 cq.Shape 对象。使用 .translate 放置它们，并将它们传递给任何接受零件名称的地方（ctx.interference、ctx.distance、ctx.slide、ctx.play）。

5. 证明检查可以失败

一个您从未见过失败的检查只是一个猜测。编写它之后：

1. 以必然触发它的方式破坏几何体（或探测实体）：将孔移动 3 mm，将间隙缩小到 0，使探测实体变大 1 mm。
2. 运行 agentcad check。确认此检查在其自身的断言上 FAIL，并且数值是您期望的。
3. 恢复几何体并确认 PASS。

如果它在破坏状态下通过，那么该检查测量了错误的东西。在信任任何其他结果之前修复该检查。

6. 坐标系

坐标系	含义	被谁使用
model	零件在其自身坐标系中	build/step/<part>.step
use	装配后的姿态，Part.use	interference，探测实体，ctx.slide，ctx.play，build/assembly/
print	在热床上，z = 0 在底部，XY 居中，Part.print 旋转	bed_fit，bed_contact，overhang，min_wall，watertight，build/stl/

设置 Part.print = Pose(rx=180)（或任何旋转），以便每个零件无需支撑且层方向沿承重方向打印。首先选择放在热床上的面，然后在该坐标系中检查 overhang。购买的零件设置 printed=False。在方便的局部坐标系中建模零件，并使用 Part.use 放置它们。

7. 报告、退出码、差异比较和松散文件

退出码：0 全部通过（允许 WARN），1 至少一个 FAIL，2 用法或配置错误（包括 agentcad.toml 中的未知键），3 模型代码引发异常或未产生有效实体。将 2 和 3 视为“无结果”，而非通过。

agentcad check --json 打印一个带有 "schema": "agentcad.report/1" 和 checks 列表的文档。每个检查都有 id、part、status（PASS、WARN、FAIL、SKIP、ERROR）、summary、measured、limit、where。引发异常的项目检查变为 ERROR，运行继续。

使用 agentcad diff OLD NEW（两个 manifest.json 文件或两个构建文件夹；体积、边界框、零件集合）比较构建，以在编辑后捕捉意外的更改。在进行有风险的更改前，将 build/manifest.json 复制到其他地方。

要审查您未编写的 CAD，直接测量文件：

agentcad measure part.step --json
agentcad interfere a.stl b.stl --json
agentcad overhang part.stl --max-deg 45 --json
agentcad wall part.stl --thin 1.2 --json
agentcad fit part.stl --printer generic-220 --json

8. 何时停止

仅当以下所有条件都成立时才停止：

• 所有检查在最新的 agentcad check 运行中都通过，且该运行是在您最后一次编辑之后执行的；
• 需求中的每个要求都有对应的检查，并且您已亲眼见证过每个检查都失败（第 5 节）；
• 您已经查看了渲染结果；
• 您的总结引用了带有单位的测量数值（间隙、壁厚 p1、悬垂面积、热床适配）；
• 您说明了零件数量以及任何留待台架检查的内容（如卡扣力、实际打印机的公差、材料特性）。

9. 反模式及其导致的失败

• 读取参数而非构建后的形状。 一名工作人员报告燕尾槽滑块的间隙为 PASS，而实际上零件位于其槽外 14 mm 处，因为其检查读取了参数。
• 跳过打印坐标系。 一个平板被建模为面朝下打印，导致约 6100 mm2 的无支撑天花板，因为从未在打印方向上检查悬垂。
• 跳过成对干涉检查。 两个零件在装配体中重叠了 50 cm3，因为没有人运行在使用姿态下的干涉检查。
• 粗糙的导出公差。 对一个回转体的粗糙 STL 导出产生了一个小平面，将一个 2.0 mm 的壁切片成 1.5 mm。解决方法：导出公差 0.02 mm，角度公差 0.05 rad（[export] 中的默认值）。
• 未经验证的文本描述。 一份设计文档声称外径为 29 到 33.5 mm，而模型测量值为 19 mm。测量您写入文本描述中的每个数字。
• 仅以“能构建”作为检查标准。 一次重建通过了其唯一的检查标准，而同时所有内部通道被密封，一个喷嘴是实心的。追溯功能路径：沿着水路、线缆或气路路径扫描一个探测实体。
• 仅检查整体。 一个装配体整体上稳定，而其中一个松动的子级单独在 6 度时倾覆。检查每个松动的子堆栈。
• 信任过时的报告。 一份检查报告是过时的，因为在旧报告写入后构建崩溃了。agentcad 原子地构建，但仍然比较报告时间戳与您最后一次编辑的时间，并在每次编辑后重新运行。
• 信任图片。 一个干净的渲染隐藏了上述所有问题。

10. 参考

• references/design-for-printing.md：在为 FDM 零件选择方向、壁厚、配合、螺丝孔或卡扣特征之前阅读。
• references/cadquery-patterns.md：当 CadQuery 操作失败、返回意外形状，或您需要选择器、壳体、圆角或探测实体时阅读。
• references/verification-playbook.md：当为一份需求规划检查、测试运动或功能，或审查另一个智能体的 CAD 时阅读。