Print a ScadBuddy output through Bambuddy - read the dialog's choices, pick a spool per slot, the nozzle size, quality and plate, options and project, run it with the user's approval, and follow its progress. Use when asked to print, send, queue or slice a generated model, or to explain why a print was refused or failed, and to link or dismiss the prints ScadBuddy did not start (Import print, the print watcher, Unsorted imports).
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-15
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- description
- Print a ScadBuddy output through Bambuddy - read the dialog's choices, pick a spool per slot, the nozzle size, quality and plate, options and project, run it with the user's approval, and follow its progress. Use when asked to print, send, queue or slice a generated model, or to explain why a print was refused or failed, and to link or dismiss the prints ScadBuddy did not start (Import print, the print watcher, Unsorted imports).
03 SKILL.md 正文
Printing a ScadBuddy output through Bambuddy
ScadBuddy renders, and Bambuddy prints. Bambuddy owns printers, spools, presets,
the queue and projects. ScadBuddy "stores no second copy of printer, spool,
preset or project state" and "reimplements no decision Bambuddy already makes"
(docs/superpowers/specs/2026-09-24-print-flow-design.md, introduction). Follow
the same rule: report Bambuddy's answers, and don't second-guess them.
Sources, relative to the root of eh-homelab/ScadBuddy:
docs/superpowers/specs/2026-09-27-spool-first-print-design.md("spool-first spec"): §2 for the flow, §3 for what each step reads, §4 for how presets are derived, §4.5 for errors versus warnings, §6 for what Bambuddy decides. It supersedes the print-flow spec's §2 rule that a pipeline is never bypassed.docs/superpowers/specs/2026-09-24-print-flow-design.md("print-flow spec"): §3 to §5 for filaments, §6 for progress, §7 for projects.docs/superpowers/specs/2026-09-27-ai-integration-design.md("AI spec"): §8 for tiers and approvals, §11 for analyzers.docs/superpowers/specs/2026-09-22-scadbuddy-design.md("main spec"): §7 for Bambuddy integration and extruder order.backend/openapi.jsonfor every route named below (all under/api/v1).
The ScadBuddy MCP tools arrive with issue #251. A print tool wraps the run
behind a single approval (AI spec §5.1): read the choices, then run with them.
The routes below are what it calls. Use the tool when you have it. There is no
pipeline or eligibility step in the print dialog any more (spool-first spec §0).
A file already in Bambuddy's library (#313) prints the same way as an output; only
the 3MF it slices differs (#1749). The /api/v1/print/library/{file_id}/… routes
mirror the output ones, and every print tool takes library_file_id (a file from
GET /api/v1/print/library, the list_library tool) in place of output_id
(#1756).
Approvals come first
Sending, printing and deleting are outward. Outward actions always need a
human approval in the ScadBuddy UI, in every auth mode, including disabled
(AI spec §8.1 and §8.2).
- In the in-app harness, the session waits in
waiting_approvalwhile the UI shows a confirmation card (AI spec §8.2). - Over
/mcp(external clients such as Claude Code), an outward tool is two steps.preparereturns a pending action id and a summary.confirmcompletes only after the user approves in the UI (AI spec §8.2).
So before you prepare a print, tell the user what will happen: which printer, how many copies, the spool for each slot, the nozzle size, quality and plate, and any warnings (§3 below). Never say a print started until progress (§6 below) says so. Don't retry a denied action with different wording.
1. Start from an output
You print an output, which is a render kept with Generate
(POST /api/v1/models/{slug}/outputs, main spec §8). If there isn't one yet, use
the customize skill first. GET /api/v1/outputs/{output_id}/plates lists its
plates, and ScadBuddy's own renders always have one plate (backend/openapi.json,
that route's description).
Printers and their paths
ScadBuddy keeps a printer registry, one row per physical printer keyed by its
serial (backend/scadbuddy/api/printers.py; plan
docs/superpowers/plans/2026-10-16-printer-identity-native-path.md). A row links
the Bambuddy printer it is, a LAN connection, or both, and preferred_path says
how a print reaches it: native over the LAN, bambuddy through Bambuddy, auto
the LAN when it answers. list_printers and discover_printers read it. No tool
links a printer over the LAN: its access code is a device credential, typed
only in Settings > Printers (PUT /api/v1/printers/{printer_id}/lan is listed as
not a tool in agent/src/tools/coverage.ts). Send the user there, or open it with
browser_navigate to /settings/printing#printers, and never ask for the code in chat.
print_output takes a registry printer (its id) in place of
printer_id: the run prints on the Bambuddy printer the row links and is
recorded with the row. Sent together, printer_id decides: a row merged away or
unlinked since falls back to its row, and only a row that links another Bambuddy
printer now is refused (backend/scadbuddy/bambuddy/print_run.py _named_printer). A row that
links no Bambuddy printer prints over the LAN, as the browser's print dialog prints
it (#4646, agent/src/tools/print.ts printerOf): name it only by printer, with no
printer_id. Whether a run goes over the LAN is the server's call
(backend/scadbuddy/printers/hot_path.py hot_path_native), which the choices report
as lan_printers when read with printer. On such a run get_print_choices and
get_print_filaments (with printer) offer the printer's loaded trays as the spools,
each under a negative spool_id (backend/scadbuddy/bambuddy/trays.py
tray_spool_id) that filament_plan takes; there is no project (a project_id is
refused; folder_id names one of ScadBuddy's own folders, list_print_projects with
native) and nothing is queued on Bambuddy. get_printers_now lists both
ids and says which link answered (path).
2. Assemble the request
The print dialog reads everything it offers in one call,
GET /api/v1/print/outputs/{output_id}/choices?printer_id= (ChoicesView in
backend/openapi.json; spool-first spec §3): the printers, the installed nozzles
and the four nozzle sizes, the quality tiers and processes for the size, the
plates with the one the printer's last print used, the model's remembered
choices, and the filament step (slots, spools and a suggestion).
The run body is PrintRunRequest in backend/openapi.json: printer_id,
filament_plan, choices, plate_id / all_plates, options, project_id
and copies. choices is PrintChoices: nozzles (one size for the job),
tier (fine / standard / draft) or a process_name, bed_type, and any
per-slot filament_overrides (spool-first spec §2).
| Step | Read with | Notes |
|---|---|---|
| Everything above | GET /api/v1/print/outputs/{output_id}/choices?printer_id= |
One read for the whole dialog (spool-first spec §3). |
| Filaments | GET /api/v1/print/outputs/{output_id}/filaments?printer_id=&plate_id= |
The plate's slots and the whole spool inventory, already joined (print-flow spec §3). all_plates=true answers for every plate at once. |
| Plate | choices.bed_type, plate_id / all_plates |
Preselected from the printer's last print, then the plate remembered with PUT /api/v1/print/printers/{printer_id}/bed-type (spool-first spec §4.4). |
| Remembered choices | PUT /api/v1/print/models/{slug}/choices |
The printer and spools last chosen for this model (backend/openapi.json). |
| Options | GET /api/v1/settings/print-options |
The sparse PrintOptions overlay (#88; backend/openapi.json, PrintOptions). |
| Project | GET /api/v1/print/projects |
Bambuddy's projects, with their library folders (print-flow spec §7). |
The filament plan
A FilamentPlan is one chosen spool per plate slot (print-flow spec §1). Slot
order is extruder order, which is the order of the model's colour parameters
(main spec §7).
- The route's opening selection matches the same material first, then the nearest colour, preferring loaded spools and never offering one spool twice (print-flow spec §5). Present it as a suggestion. Every slot stays the user's choice.
- Traps in the data (print-flow spec §3):
used_grams: 0means unknown, not zero.remain: -1means unknown, not empty./inventory/assignmentscovers every printer, butinventory-remaincovers one. The route does this join for you, so don't redo it.
- The only warnings (print-flow spec §4). None of them blocks a run:
- The spool isn't loaded: name where it is (
storage_location, or the other printer). - Not enough filament:
remaining_g < used_grams × copies, and only when the grams are known. - A slot has nothing chosen.
- The spool isn't loaded: name where it is (
- ScadBuddy sends no
ams_mapping. Bambuddy's scheduler computes it against the printer it actually dispatches to (print-flow spec §4). Don't invent one.
3. The run: slice, then queue
There is one submit, POST /api/v1/print/outputs/{output_id}/run. ScadBuddy
derives the printer, process and per-slot filament presets from choices and the
chosen spools (spool-first spec §4), slices through Bambuddy, waits for the slice
job, then POST /queue/ on the one printer the dialog is scoped to. No pipeline
runs on this path.
The route answers 202 with a PrintRun (status: "running") and slices and
queues in the background, because the slices outlast the proxies in front.
Follow GET /api/v1/print/runs/{run_id} until status is succeeded (its
result is the PrintRunResult below) or failed (its error carries the
type, status and detail of the refusal). The body's optional request_id
names one deliberate print: send a new one per print and the same one on a
retry of it. The same request (same request_id) for the same output again
answers 200 with that run (repeated: true) while it is in flight, or for
ten minutes after it succeeded or failed with may_have_queued: true, and queues
nothing more; a failed run that never tried to queue holds nothing, so repeating
it tries again. A new request_id with
the same choices is a new print (backend/openapi.json; #470). print_output
makes a new one per call, and re-sends that call's POST with the same id when no
answer from ScadBuddy arrived. If it still reports no answer, or names a run it
started but could not read, follow that run or check Bambuddy's queue rather
than calling print_output again. A failed run with may_have_queued: true had already
tried to queue (a queue call that timed out, or a later plate failing after an
earlier one was queued): tell the user to check Bambuddy's queue, and do not
print again until they have, since another print would be a second one.
- Errors are a 422 before anything is sliced, and name the slot or setting:
mixed nozzle sizes, or a slot with no filament preset for the nozzle
(spool-first spec §4.5). A slot error needs the uploaded file, so it arrives
as the run's
failederrorwith that 422, not as the POST's answer. - Warnings come back in the result and never block: spool not loaded, nozzle
not installed, a nozzle of the chosen size mounted in the other flow on a
side the slice may use (
hf-mounted, #797), a Generic filament preset fallback, or a plate that differs from the last print (spool-first spec §4.3, §4.5). An output's flow (Standard or High Flow) is sliced as chosen for each side (#484), so choosing the mounted nozzle's flow for its side avoidshf-mounted. When both sides could print their chosen flows and those differ, the print goes to the High Flow side. A library file that Bambuddy slices (an unsliced 3MF) is sliced as chosen too: with High Flow chosen, the slicer gets a copy of it, uploaded to the library folder, that states each side's flow; the file itself is never changed. A sliced file, an STL or a 3MF from another slicer prints as it is, taken as Standard whatever is chosen (#484). Tell the user about the ones you can predict before they approve.
Which AMS tray and extruder each spool feeds, and which rack nozzle is used, stay Bambuddy's and the printer's decisions (spool-first spec §6). The run does not check the chosen size against the mounted nozzles, so do not warn that a multi-color print needs the size on both sides: a two-colour print sliced for 0.2 mm printed through the one 0.2 mm nozzle (spool-first spec §4.3, #768).
The simpler send path, POST /api/v1/outputs/{output_id}/send with
{mode: "library"}, only uploads the 3MF to the library folder and attaches the
edit link. It never slices or queues; mode: "queue" is refused with a 422
(backend/openapi.json, SendRequest; spool-first spec §0, the #312 note). To
print, use the run above. Sending is outward too.
4. After the run: the result
A succeeded run's result, a PrintRunResult, reports route (always slice_queue), slice_job_id,
queue_item_ids, library_file_id, copies, bambuddy_url and warnings
(backend/openapi.json). Give the user the bambuddy_url and every warning.
A run that went over the LAN has path: "native" and no queue item or Bambuddy URL
(PrintRunResult.path and lan in backend/scadbuddy/bambuddy/print_run.py):
print_output and get_print_run answer with a follow handle instead, the
get_print_progress call that follows it and each plate's subtask_name
(agent/src/tools/print.ts followed).
5. Projects
A project is Bambuddy's (print-flow spec §7). POST /api/v1/print/projects
creates one, or links an existing one, together with its library folder. Attaching
queue entries and archives is a separate call,
POST /api/v1/print/outputs/{output_id}/project. Call it once the ids exist:
queue entries appear once a plate is queued, and archives only
after the print finishes. Calling it again later is how archives land on the
project (print-flow spec §7). The project routes need Bambuddy's Manage
Projects scope, which the key may not have (print-flow spec §7).
6. Follow progress
GET /api/v1/print/outputs/{output_id}/progress follows whichever route ran
(print-flow spec §6; backend/openapi.json, PrintProgress):
nullmeans the output was never printed. That is an answer, not an error.settledsays when to stop. An all-plates print reads "Slicing…" until one of its plates has a queue entry, and a plate can fail before it is ever queued.- Show Bambuddy's
error_messageword for word, next to thefixthe route suggests (change the mapping, retry). Don't paraphrase it (print-flow spec §6).
7. Errors that name a scope
Every Bambuddy call declares the API-key scope it needs, so a 401 or 403 names
the missing scope (CLAUDE.md, section "Bambuddy iframe facts";
backend/scadbuddy/bambuddy/errors.py). Sending needs Manage Library,
printing also needs Manage Queue, and listing printers needs Read Status
(main spec §7).
Tell the user which scope to add to the key in Bambuddy. The key itself never
leaves the server (CLAUDE.md, section "Bambuddy iframe facts").
8. Print analyzers (coming with #284)
Analyzers inspect a print before it runs and propose diffs against the base request that this flow already builds. They never propose a profile of their own (AI spec §11; issue #284). The run already slices then queues, so an accepted diff lands on that same request:
- Filament-level settings go in
filament_overrideson the queue item. - Process-level settings become a derived local preset.
- The 3MF's
project_settings.configis used only if it is shown to beat the resolved process preset. Main spec §3 measured the preset winning.
Each of these is on AI spec §3.2's "to verify" list, so don't rely on any of them until a PR verifies it. Analyzer sessions can read and propose, but they can't send or print (issue #284, "Agent-mode analyzers"). Every proposed value needs a source. A value without one is the analyzer's judgement, and is never applied automatically (AI spec §2, D10).
9. Prints ScadBuddy did not start
Import print (#4698) links such a print to a model by hand, and the print watcher
(#4699) does it with no user step (README.md, section "The print watcher (#4699)").
The tools are in agent/src/tools/prints.ts.
- The watcher is off by default. Only a person switches it on or changes it, in
Settings → Printing; the API refuses an agent with 403
person_only(backend/scadbuddy/api/settings.pyPRINT_WATCH).get_settingsreads it. - It links a print to a model only when earlier imports of the same file name one
model, or the job's name has exactly one model's words. Every other print goes to
Unsorted imports, with a
reasonand suggested models (backend/scadbuddy/print_watch/sweep.py, module docstring step 3). - For a print Bambuddy archived:
list_auto_imports(state: inboxis Unsorted imports). To link one, show the user the suggestions, let them choose, thenget_print_sourcesandimport_print. To take one out of the inbox,dismiss_auto_import, only when the user says it is not worth keeping. - For a print on a LAN-only printer (no Bambuddy link, so no archive):
list_lan_auto_imports,link_lan_auto_import(neverimport_print) anddismiss_lan_auto_import. A linked LAN-only print is not inlist_printsor on the model's Prints tab; it is in Activity (backend/CLAUDE.md, the print watcher's phase 4 paragraph).
04 同仓库更多 Skills
filament-intake
Use when adding purchased filament to the spool inventory from receipts or invoices (Bambu Lab, Best Buy, Micro Center, Amazon), when spool cost should include sales tax, when ScadBuddy's price book or job cost needs the new spool prices, when downloading or importing 3dfilamentprofiles.com slicer profiles, or when a spool needs per-nozzle presets for the H2C. Also when 3dfilamentprofiles answers 429 "Vercel Security Checkpoint", Micro Center answers 403, or a Bambu RFID spool duplicates a manually added one.
customize
Drive the ScadBuddy customizer for a template - read its parameter schema and presets, choose values, render and inspect the preview, check the plate fit, and keep the result as an output. Use when asked to make, tweak or preview a customized model (a keychain with a name, a box of a given size) on a ScadBuddy instance.
authoring
How to write and edit ScadBuddy OpenSCAD templates (model.scad) so the customizer, the per-colour print parts and the fonts come out right. Use when creating, editing, reviewing or debugging a .scad template for ScadBuddy, or when a render shows the wrong font, the wrong colours, open parts or unexpected parameters. Also covers FDM design rules (hole and fit clearance, wall thickness, overhangs, bridges) and OpenSCAD pitfalls (coincident faces, use vs include, leftover modifiers).
hello
Fixture skill for the plugin vetting tests.
scadbuddy-run-forensics
Find out what a ScadBuddy print, slice or order operation actually did by reading its Temporal workflow history, instead of trusting the HTTP reply or the run record. Answers whether a run whose reply was lost reached the printer, which sliced library file it produced, why an activity failed (ERROR STATE refusal, heartbeat timeout on the sliced upload, workflow task timeouts, "no spool chosen"), and which spools and trays a LAN send used. Use it whenever a ScadBuddy MCP call times out or its transport drops, the API answers HTTP 500 "Workflow Task in failed state" or "did not answer", get_print_progress reads null while the printer is clearly busy, or before resending any print, and for any "did it actually go", "what happened to my run", "which file did it make" question.
h2c-print-from-scadbuddy
Print a ScadBuddy output or library file on the Bambu H2C (Bambuddy printer 1, "3DP-31B-598") and see it through to a cleared bed. Covers the LAN print_output recipe with negative tray ids, the Bambuddy-queue route for when bed levelling, flow dynamics, nozzle offset or vibration calibration must be forced on, verifying the AMS mapping over MQTT, watching progress, plate-clear holds between plates, stopping and restarting, and what to do when the reply is lost, the printer answers ERROR STATE, or progress reads null. Use this whenever the user says print, send it, reprint, queue it in Bambuddy, stop it, "is it done", "is it mapped", "turn on flow calibration", or asks why a ScadBuddy print did not start, even when they do not name the H2C or ScadBuddy.