AryaVora621/agentcad

agentcad は何をしますか？

1. 基本ルール

agentcadで構築されたジオメトリから実測していない寸法、クリアランス、または「合格」を報告してはなりません。 パラメータは意図であり、証拠ではありません。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/: ビューごとに1つのPNGと sheet.png
agentcad view my-part                      # ライブビューア（人間用）

1. モデリング中またはモデリング前に、仕様の検査を先に記述します（セクション3）。
2. agentcad check --json を実行します。すべての FAIL を読みます: summary, measured, limit, where。
3. where が示す位置のジオメトリを修正します。再実行します。要件自体が変更されない限り、FAIL を消すために limit を編集してはいけません。
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")

距離の範囲は、ネジが実際に穴の近くにあり、14mm離れてオーバーラップがゼロではないことを証明します。

「プリンターに収まる」は組み込みの bed_fit ゲートです。agentcad.toml の [printer] を実際のマシンに設定します（profile または bed = [X, Y, Z]）。「壁が十分に強い」は [checks] の min_wall_mm です。

4. プローブソリッド

要件から相手側の部品の代役を構築します。モデル自身のパラメータからは決して構築しません。M4ネジは直径4.0mmの円柱です。54mmのボールは半径54mmの球です。ケーブルはその経路に沿った円柱です。手は手の大きさの箱です。プローブが穴を構築するために使用した同じ変数を読み取る場合、そのチェックは決して失敗しません。

プローブは cq.Workplane または cq.Shape オブジェクトで、既に使用フレームにあります。.translate で配置し、パーツ名が受け入れられる場所（ctx.interference、ctx.distance、ctx.slide、ctx.play）に渡します。

5. チェックが失敗できることを証明する

一度も失敗したことがないチェックは推測です。チェックを書いた後：

1. 必ずそれをトリップさせる方法でジオメトリ（またはプローブ）を壊します：穴を3mmずらす、クリアランスを0に縮める、プローブを1mm大きくする。
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 少なくとも1つのFAIL、2 使用法または設定エラー（agentcad.toml の未知のキーを含む）、3 モデルコードが例外を発生させるか、有効なソリッドを生成しなかった。2と3は「結果なし」として扱い、合格として扱わない。

agentcad check --json は、"schema": "agentcad.report/1" と checks リストを含む1つのドキュメントを出力します。各チェックには id、part、status (PASS, WARN, FAIL, SKIP, ERROR)、summary、measured、limit、where があります。プロジェクトチェックが例外を発生させた場合は ERROR になり、実行は継続されます。

ビルドの比較は agentcad diff OLD NEW（2つの manifest.json ファイルまたは2つのビルドフォルダ；体積、バウンディングボックス、パーツセット）で行い、編集後の意図しない変更を検出します。リスクのある変更の前に、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と報告したが、チェックがパラメータを読み取っていたため、パーツは溝の外側14mmにあった。
• プリントフレームをスキップする。プレートが印刷面を下にしてモデリングされ、約6100mm2の未サポート天井があった。これは、オーバーハングが印刷方向でチェックされなかったためである。
• ペアごとの干渉をスキップする。アセンブリ内で2つのパーツが50cm3オーバーラップした。これは、誰も使用姿勢で干渉を実行しなかったためである。
• 粗いエクスポート公差。回転体の粗いSTLエクスポートにより、2.0mmの壁を1.5mmでスライスするファセットが生成された。修正: エクスポート公差0.02mm、角度公差0.05rad（[export] のデフォルト）。
• 未測定の説明文。設計書に外径29～33.5mmと記載されていたが、モデルは19mmだった。説明文に書くすべての数値を測定すること。
• 「ビルドできるか」だけでゲートを設定する。再ビルドは唯一のゲートを通過したが、すべての内部チャネルが密閉され、注ぎ口が中実だった。機能経路をトレースする：水、ケーブル、または空気の経路に沿ってプローブをスイープする。
• 全体のみをチェックする。アセンブリは全体的に安定していたが、単一の緩んだステージだけで6度傾いた。各緩いサブスタックをチェックする。
• 古いレポートを信頼する。古いレポートが書き込まれた後にビルドがクラッシュしたため、ゲートレポートが古くなっていた。agentcadはアトミックにビルドするが、それでもレポートのタイムスタンプを最後の編集と比較し、編集後は毎回再実行する。
• 画像を信頼する。きれいなレンダリングは上記のすべてを隠蔽した。

10. 参考文献

• references/design-for-printing.md: FDM部品の向き、壁厚、はめ合い、ネジ穴、またはスナップフィーチャーを選択する前に読んでください。
• references/cadquery-patterns.md: CadQuery操作が失敗した場合、予期しない形状を返した場合、またはセレクタ、シェル、フィレット、プローブソリッドが必要な場合に読んでください。
• references/verification-playbook.md: 仕様のチェックを計画するとき、動作や機能をテストするとき、または別のエージェントのCADをレビューするときに読んでください。