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.
9.8 KiB
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.
- Carry over the model's settled facts (geometry validated, parameters named). Do not reopen modeling decisions here.
- 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.
- 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.
- Per sheet, fix the view set and alignment structure (front view anchored;
every other view
aligned to it — 长对正 / 高平齐 by construction, never by offsets). - Fix the datum scheme consistent with the model's functional interfaces
(
discipline/datums-and-coordinate-systems.md). - 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.
- 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:
- 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. - Measure. Call
plan.evaluate()and read the exact, digested numbers for the failing elements: per-elementviolations(what it hits, where, by how much) andcorridors(free translation distances). Work from these quantities — never from re-derived raw geometry. - Propose. Compose the next action-log JSON: one action per decision
(
rad/dia/lin/leadposition adjustments,acceptto 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. - Submit. Replay via
plan.apply(actions): the engine validates each action and rejects bad ones withviolations/corridorsresiduals, rolling the sheet back to the last consistent state. A rejection is data, not failure: read the residuals, revise the action, resubmit. - 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.
- 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.
- Read the PNG rendered from the final DXF (both sheets if multiple).
- 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).
- 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
- Final render:
plan.render(dxf, png)per sheet from the verdict-passed state (declarations + replayed action logs). - 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. - 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.