cad-coworker

CadQuery でパラメトリックな 3D モデルを設計し、cad-coworker のブラウザ GUI で スライダー / 数値入力からリアルタイムに微調整する。

設計（コードを書く）→ 微調整（GUI でスライダー）→ 確定（STL 出力 / パラメータ上書き保存）の 2 段構え。コードはエージェントが書き、寸法の追い込みは人間が GUI で手を動かす分担にできる。

旧 cad-designer スキル（コード生成のみ）の後継。CADEvolve RAG db / 部品別寸法リファレンスは 重いので外し、cad-coworker との連携ワークフローに絞っている。

ツールの場所・起動・モデル保存先

• cad-coworker ツール本体（独立リポジトリ）: [WORKSPACE]/skills/cad-coworker/
  • GitHub: https://github.com/karaage0703/cad-coworker（再クローン時はここから）
• 実モデルの .py 保存先: [WORKSPACE]/cad-scripts/
  • 例: stackchan_minimal_top.py / stackchan_minimal_bottom.py（スタックチャンのケース）、ashi_leg.py、stackchan_lego_foot.py
• 起動（DGX Spark spark-edbc、Tailscale 経由でブラウザアクセス）:

cd [WORKSPACE]/skills/cad-coworker && source .venv/bin/activate && \
  nohup cad-coworker --scripts [WORKSPACE]/cad-scripts --host 0.0.0.0 --port 8770 \
  > /tmp/cad-coworker.log 2>&1 &

• ブラウザ: http://<spark の Tailscale IP>:8770/（例: http://100.86.210.85:8770/）
• すでに起動済みか確認: curl -s http://localhost:8770/api/health
• viewer.js / index.html などフロントは静的配信なので、フロント変更だけならハードリロード（Ctrl+Shift+R）で反映。server.py を変えたらプロセス再起動が必要

AI agent workspace へのインストール

Codex / Claude / xangi などの agent workspace に skill として追加する場合は、public repository を skills/ に clone する。

• Codex: ~/.codex/skills/ または repo の .agents/skills/
• Claude Code: ~/.claude/skills/ または repo の .claude/skills/
• xangi: workspace の skills/

cd [AGENT_SKILLS_DIR]
git clone https://github.com/karaage0703/cad-coworker.git cad-coworker

clone 後、使っている agent の手順に従ってスキル一覧を再読み込みし、cad-coworker が使えることを確認する。

ユーザー向け依頼例:

cad-coworker スキルを使って、この workspace の cad-scripts にモデルを作って。cad-coworker を起動して、ブラウザで調整できるところまで確認して。

skill として実行するときは、次を最後まで行う:

1. [WORKSPACE]/cad-scripts/ の既存モデルと保存先を確認する。
2. 必要なら [WORKSPACE]/skills/cad-coworker で uv sync を実行する。
3. CadQuery スクリプトを [WORKSPACE]/cad-scripts/<name>.py に作る。
4. GUI に出す値はトップレベルのリテラル代入とコメント拡張で定義する。
5. cad-coworker --scripts [WORKSPACE]/cad-scripts --host 0.0.0.0 --port 8770 を起動する。
6. /api/health と対象スクリプトの params API を確認する。
7. ローカルまたはリモート環境からブラウザで開ける URL を案内し、調整できる状態にする。
8. 必要なら STL / STEP を出力し、生成ファイルのパスを報告する。

ワークフロー

Step 1: 要件確認

わかっている情報はスキップしてよい：

1. 何を作る？ → 部品の種類（ケース、フレーム、マウント等）
2. 寸法は？ → 主要寸法、取り付け穴の位置・ピッチ
3. 参照データは？ → 既存部品の図面 / 型番（M5Stack CoreS3、DYNAMIXEL XL330 等）

Step 2: CadQuery スクリプトを書く

[WORKSPACE]/cad-scripts/<名前>.py に生成する。cad-coworker が読めるよう、パラメータを冒頭に 「名前 = 値 # ラベル [単位] @ディレクティブ」形式で並べる。この形式だと GUI に自動で スライダー / 数値入力が展開される。

import cadquery as cq

# ===== パラメータ =====
WIDTH = 100.0   # 幅 [mm] @min=50 @max=200 @step=0.5 @group=本体
DEPTH = 80.0    # 奥行き [mm] @min=40 @max=160 @group=本体
HEIGHT = 30.0   # 高さ [mm] @min=10 @max=80 @group=本体
WALL = 2.0      # 肉厚 [mm] @min=1 @max=5 @step=0.2 @group=本体
FILLET = 2.0    # 角丸 [mm] @min=0 @max=10 @group=仕上げ

# ===== モデリング =====
body = (
    cq.Workplane("XY")
    .box(WIDTH, DEPTH, HEIGHT)
    .faces(">Z").shell(-WALL)   # shell を先に（fillet 後だと OCC が落ちやすい）
    .edges("|Z").fillet(FILLET)
)

# cad-coworker は CQGI 経由で評価するため show_object() を呼ぶ
show_object(body)

パラメータのコメント拡張（ディレクティブ）

書き方	意味
[mm]	単位（ラベル横に表示）
@min=50 @max=200	スライダーの下限・上限（省略時は値から自動推定）
@step=0.5	刻み幅
@group=本体	UI のグループ分け（fieldset 単位）
@label=外形幅	表示名を上書き
@hidden	UI に出さない（内部計算用パラメータ）
@choices=A,B,C	enum（プルダウン）

詳しい構文は [WORKSPACE]/skills/cad-coworker/docs/usage.md を参照。

Step 3: cad-coworker で開いて微調整

上の起動コマンドでサーバーを立て、ブラウザでスライダーを動かしながらプレビューを見て寸法を追い込む。 スクリプトを追加・編集したら、ヘッダのスクリプト選択で対象を選ぶ（mtime 監視で自動再読込）。

Step 4: 確定（出力 / 上書き保存）

GUI ヘッダのボタンで確定する：

• 「STL保存」 → 現在のパラメータで STL を生成しダウンロード（3D プリンタへ）
• 「上書き保存」 → 追い込んだ値で元の .py を上書き（コメント・@ ディレクティブ・計算式は保全。 書き換わるのはリテラルの代入値だけ）。ステータス欄に saved: N param(s) → <名前>.py が出れば成功

上書き保存した .py を git にコミットすれば、確定パラメータがソースとして残る。

設計で事故らないための最低限のルール

過去に干渉・寸法ミスで作り直した教訓から、最低限これだけは守る。

• 実測優先。公称値が実物と違うことがある（例: CoreS3 は公式 16mm でも実測 30mm）。 公式図面 PDF・eManual・実測値を先に確認してから寸法を決める。
• 全パーツを 1 スクリプトに。ボディ + マウント + 穴を 1 ファイルで生成し、パーツ追加のたびに 前のパーツが union から消えていないか確認する。
• 干渉チェックは数値で。各パーツの配置範囲を座標で出して重なりを計算で確認する。 「大丈夫だろう」で進めない。
• 3 面図セルフチェック。生成後に top / front / left / iso を画像出力して目視する。 左右対称か、部品が入るサイズか、ポート開口があるか、union 中にパーツが消えてないか。

from cadquery import exporters
for name, d in {"top": (0, 0, 1), "front": (0, -1, 0),
                "left": (-1, 0, 0), "iso": (1, 1, 1)}.items():
    exporters.export(body, f"/tmp/{name}.svg", opt={"projectionDir": d})
# SVG→PNG 変換して Read で目視確認

• 組み立てられるか常に意識する。固定方法（ネジ / スナップ / 圧入）・ネジのサイズと長さと本数・ ケーブル経路・上蓋装着後の抜き差しまで具体的に設計する。
• 3D プリントのはめ込みは公差 ±0.2mm を見込む。
• 貫通は cutThruAll、ボディ厚分だけ掘るなら cutBlind(-WALL)。上面の壁まで切らないよう注意。
• 造形サイズはプリンタのベッドに収める（例: Bambu Lab A1 mini は 180×180×180mm）。 収まらなければパーツ分割し、組み立て方法も設計に含める。
• ファイルにバージョン番号を付けない（top.py を上書き → git でバージョン管理）。

トラブルシュート

• GUI に「parse error」 → スクリプトの構文エラー。python <script>.py 単体で実行して確認。
• パラメータが出ない → 値がトップレベルの 名前 = リテラル 形式か確認（計算式やローカル変数は拾われない）。
• 上書き保存で値が変わらない → 計算式 (A * 2) は安全のため書き換え対象外（リテラルのみ）。
• モデルが画面外に飛ぶ → 解消済（カメラ全状態の保存復元）。再発したら viewer.js の captureCamera/restoreCamera を確認。
• 環境セットアップ（CadQuery / nlopt の aarch64 ビルド）は [WORKSPACE]/skills/cad-coworker/README.md 参照。

使用例

スタックチャンのケースの寸法調整したい
3Dモデル設計して
M5Stack CoreS3 のケース作って
cad-coworker 立ち上げて
STL出力して