Files
make-cad/docs/skill/references/workflows/engineering-drawing.md
T
NiJingzhe eaa6d46458 chore(example): drop 2D drawing scripts from u_link_motor_mount
The drawing declarations were exploratory scaffolding for the dxf engine
and outlived their purpose once the engine contracts landed; example
keeps only the 3D modeling chain (u_link/shell/assembly/export/verify).
Generated artifacts (dxf/png/diag/action-log) were already removed from
out/ — only 3D exports remain. Workflow doc now points at driving the
loop directly via SheetPlan (solve/evaluate/apply/render) with the
diag_png auto-diagnostic instead of the deleted driver script.
2026-09-01 19:10:41 +08:00

9.8 KiB
Raw Blame History

Workflow: Engineering Drawing Generation

Produce a GB-standard engineering drawing sheet set (DXF + PNG) from an already-validated part or product. This is a preliminary workflow; drawing is an output stage, so geometry must be final before entry. Layout follows the engine's division of labor: the solver computes deterministic truth (projection, measurements, collisions, rules R1–R7), and the agent refines the layout through a validate-and-rollback action loop.

Read domains/engineering-drawing.md first — this workflow does not repeat its solver rules or engine boundaries.

Standing discipline, binding for every role:

  • Geometry first, drawing second. Enter only with validated geometry and a settled datum story. A drawing never repairs a model; it exposes one.
  • Engine truth, agent choice. Every validity judgment (collision, R1–R7, coverage) is computed by the engine. The agent only arbitrates discrete choices (which side/row, which trade-off) through actions the engine validates or rejects with reasons. Never hand-edit a rendered DXF or PNG.
  • Declare, then arbitrate. Start from semantic declarations (SheetDecl + friends); run the action loop only on what the solver could not place cleanly. Actions refine a solvable declaration; they are not a substitute for one.
  • The action log is the decision log. Every layout change is an action in a replayable JSON file. Rebuilding from declarations plus replaying the action file must reproduce the sheet byte-for-byte.
  • Audit before render; two artifacts, one truth. report() is reviewed before rendering, and visual acceptance means reading the PNG rendered from the DXF — "no rule conflicts" alone is not acceptance.

Role map

# Role Reads (load before acting) Produces Exit gate
1 Drawing Requirement Confirmer domains/requirement-refinement.md, domains/engineering-drawing.md, model requirements (REQUIREMENTS.md/BUILD_PLAN.md if present) <part-dir>/DRAWING.md ⛔ user consent received
2 Sheet Planner DRAWING.md, discipline/datums-and-coordinate-systems.md per-sheet view/datum/dimension roster + R5 coverage ledger plan presented
3 Layout Arbiter sheet plan, domains/engineering-drawing.md, declaration/action API pages sheet declarations, action-log JSONs, solver-clean report report() R1–R7 ok or accepted-with-reason, R5 no MISS, no open warnings
4 Visual Reviewer rendered PNG only structured verdict verdict pass; failures become repair: items for Role 3
5 Drawing Exporter verdict-passed action logs, domains/engineering-drawing.md final DXF + PNG + archived action logs artifacts re-open cleanly

Role-switch protocol

Before starting a role's work, output exactly:

## [Role Switch: <Role Name>]
Reading: <role-owned files>
Artifact out: <path>

Then act only inside that role's scope. Roles 3 and 4 alternate per sheet:

Sheet_1: Role 3 declare + action loop -> Role 4 render verdict -> (repair:)*
Sheet_2: Role 3 declare + action loop -> Role 4 render verdict -> (repair:)*
...

A failed verdict does not advance the sheet; it appends a repair: item owned by the declarations or the action log, whichever owns the failure, and repeats the same Role 3/4 loop.


Role 1 — Drawing Requirement Confirmer ⛔

Convert the request into DRAWING.md. No declarations, no renders before this gate closes.

  1. Carry over the model's settled facts (geometry validated, parameters named). Do not reopen modeling decisions here.
  2. Decide-or-ask the drawing-level choices: sheet scale, view set (which views, which sheet each lives on), datum letters, which parameters are manufacturing-critical, and the notes/parameter-table split.
  3. Batch every blocking ambiguity into ONE ask round with conservative defaults first (domains/requirement-refinement.md). Record the rest in the Ask-or-Record ledger with basis.

Write DRAWING.md with: scale; per-sheet view roster; datum scheme; dimension roster seeds (parameter → kind/semantic guess); R5 ledger skeleton (every parameter → dimension carrier or notes/table); open assumptions.

Gate: the ask round returned and consent is recorded. Entering Role 2 without this gate is the cardinal violation.

Role 2 — Sheet Planner

From DRAWING.md only — no API detail, no coordinates.

  1. Per sheet, fix the view set and alignment structure (front view anchored; every other view aligned to it — 长对正 / 高平齐 by construction, never by offsets).
  2. Fix the datum scheme consistent with the model's functional interfaces (discipline/datums-and-coordinate-systems.md).
  3. Produce the dimension roster: for each parameter, its carrier dimension (kind, semantic, view, reference datum) or its notes/parameter-table destination. This roster IS the R5 coverage ledger.
  4. Flag parameters the engine cannot express yet (engine boundaries in the domain page) and route them to notes explicitly — never silently.

Present the plan in ≤10 lines. No approval gate; enter the Role 3/4 loop.

Role 3 — Layout Arbiter

Owns declarations and the agent-in-the-loop refinement cycle.

Phase A — declare. Author the SheetDecl per sheet from the roster: ViewDecls with align, DatumDecls first, DimDecls with covers, CenterDecl/LeaderDecl as planned. Solve, print report(), and read it line by line: fix declaration-level problems (wrong view, missing datum reference, duplicate measurement) by re-declaring, not by actions.

Phase B — the action loop. For everything the solver placed with warnings or left unsolved, iterate:

  1. See. Render the annotated review image (viz): gray = placed ok, blue = unsolved, red = warning, orange = accepted-with-reason; green arrows show each element's free movement corridors (how far it can translate, per direction). Read the red and blue elements first.
  2. Measure. Call plan.evaluate() and read the exact, digested numbers for the failing elements: per-element violations (what it hits, where, by how much) and corridors (free translation distances). Work from these quantities — never from re-derived raw geometry.
  3. Propose. Compose the next action-log JSON: one action per decision (rad/dia/lin/lead position adjustments, accept to bless a warning with a recorded reason). Actions are discrete choices — which side, which row, which trade-off (R1 squeeze vs arrow-off-arc vs new azimuth) — arbitrated by you, the agent.
  4. Submit. Replay via plan.apply(actions): the engine validates each action and rejects bad ones with violations/corridors residuals, rolling the sheet back to the last consistent state. A rejection is data, not failure: read the residuals, revise the action, resubmit.
  5. Verify blast radius. Diff the previous and new action logs (pixel diff of the two replays): red = newly covered, blue = vacated, gray = untouched. Confirm the action moved only what you intended.
  6. Loop 1–5 until every element is gray or orange (warn = 0), then run the full report() audit once more.

Exit gate: report() shows R1–R7 ok or accepted-with-reason, the R5 coverage table has no MISS, and no red/blue elements remain. Drive the loop directly against SheetPlan (solve / evaluate / apply / render); declaring SheetDecl.diag_png makes every solve/apply auto-refresh the annotated conflict image and return a must-read instruction with it.

Role 4 — Visual Reviewer

Rendered-PNG-only judgment, delegated in the same spirit as image verdicts in workflows/single-part-modeling.md: the reviewer sees the artifacts, not the reasoning.

  1. Read the PNG rendered from the final DXF (both sheets if multiple).
  2. Check, in order: views aligned as planned; hidden lines (虚线) and center lines present; arrows touch their geometry; texts sit clear of lines; datum boxes legible; the dimension arrangement communicates design intent (a formally clean sheet can still mislead — e.g. dimensioning a derived length instead of the functional one).
  3. Emit a structured verdict: pass, or an itemized list where each item names the owning artifact (declaration or action log).

A failed item becomes a repair: item for Role 3. Never patch the DXF.

Role 5 — Drawing Exporter

  1. Final render: plan.render(dxf, png) per sheet from the verdict-passed state (declarations + replayed action logs).
  2. Re-open the DXF (e.g. via ezdxf) and check the entity count matches the render report; confirm both artifacts regenerate deterministically from the same inputs.
  3. Deliver: DXF + PNG paths plus the archived action-log JSONs (they are part of the deliverable — the reproducible decision history).

Acceptance

  • report(): R1–R7 all ok, or accepted with recorded reasons.
  • R5: every model parameter has a carrier; no MISS.
  • Visual verdict passed; DXF re-opens with expected entity count; the sheet regenerates byte-for-byte from declarations + action log.
  • Engine boundaries routed explicitly (notes/table), never silently dropped.

Failure modes

  • Entering with unvalidated geometry: every downstream conflict then looks like a drawing bug but is a model bug.
  • Using actions to fight a wrong declaration: if report() shows structural problems (missing datum, duplicate measurement), re-declare — the action loop is for placement refinement, not for repairing semantics.
  • Trusting "no conflicts" over the PNG, or skipping the diff step so one action silently relocates a neighbor.
  • Losing the action log: without it the sheet is not reproducible; treat it as a deliverable, not scratch.
  • Hitting engine boundaries (no sections/hatching; horizontal/vertical linear dims only; radius labels same-side outward): restructure the view set or record the limitation; do not simulate missing features with leader-note spam.