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

196 lines
9.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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:
```markdown
## [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:
```text
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 `align`ed 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:
`ViewDecl`s with `align`, `DatumDecl`s first, `DimDecl`s 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.