@deepblend/dsh-blender-preset 0.2.20 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepblend/dsh-blender-preset",
-  "version": "0.2.20",
+  "version": "0.3.0",
   "type": "module",
   "description": "DeepBlend Agent-preset plane: ships the DeepBlend Studio agent presets and the deployer row that installs them into the DSH home.",
   "main": "lib/index.js",

package/presets/deepblend/skills/deepblend-studio/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: deepblend-studio
-description: Use when planning or producing a 3D animation with DeepBlend Studio — setting up a shot or product scene, bringing the user's own 3D model into a project, changing a Blender scene through SceneSpec patches, rendering and judging a preview, repairing a scene that measures badly, running, checking, cancelling or resuming a long final render, or delivering a finished video. Also use when a previous session's revision has to be restored.
+description: Use when planning or producing a 3D animation with DeepBlend Studio — setting up a shot or product scene, importing models or visual references, changing a scene through SceneSpec patches, reviewing previews against the saved goal, running or resuming a final render, delivering a video, or restoring a previous revision.
 ---
 
 # DeepBlend Studio
@@ -37,22 +37,157 @@ time (`RENDER_JOB_CONFLICT`).
 
 ## The order that works
 
+### Establish the visual target before building
+
+Record the intended object, dimensions, audience, material identities and delivery
+views in the project goal. Bind available reference images as immutable project assets
+through `project.referenceImages`; describing a file in the goal does not attach it.
+For the import, binding and evidence rules, read [Reference image workflow](references/reference-images.md).
+If no reference is
+available, state the chosen proportions and finish as assumptions. Break a product
+into named parts with distinct silhouettes, seams, thickness and material assignments.
+Choose a route for each part: import an authorized asset, use a supported procedural
+shape, or build a blockout pending a more capable modeling operation. A blockout is
+an intermediate result; describe its missing details explicitly.
+
+For rotational products, use `generator.shape: "lathe"` with an ordered
+`profile: [[radius, height], ...]`; returning along the inside models a real wall
+and base. Add profile points along curved shoulders instead of stacking cylinders.
+For a cylindrical ceramic cup with a connected semicircular handle, use
+`shape:"handled_cup"`. Defaults make a 40 mm radius, 105 mm high cup with 3 mm
+walls and a 5 mm base in a metre scene. `handleLower`/`handleUpper` locate the
+attachment centres; `handleRadius`, `rootRadius` and `rootLength` control the
+handle and flared roots. Dimensions constrain one another; an unsupported edit
+is refused before publication. The generated mesh is checked for topology, UVs
+and illegal intersections. Inspect actual clay and glazed root close-ups;
+these checks do not certify curvature continuity, manufacturing thickness or
+artistic quality. Existing modifier stacks can change the generated result.
+
+For handles and cables, use `shape: "curve"`, a three-dimensional `path`, `radius`,
+and `pathInterpolation: "bezier"` for smooth bends. Check joins and self-intersections;
+overlapping parts are not automatically fused into one solid.
+Use ordered entity `modifiers` for solidify (wall thickness), mirror, array and
+boolean union/difference/intersect. A boolean's `targetEntityId` names a separate
+single-mesh operand; set that operand's `visible:false` to avoid rendering it twice.
+Inspect the resulting junction: a watertight union does not automatically create
+a rounded transition. Generator bevel runs before these modifiers. Add
+`{type:"bevel",width:0.002,segments:6,angle:30}` after a boolean to round its new
+edges (width is a local distance; angle is in degrees). Overlap clamping can reduce
+the width on dense geometry, so inspect close-ups and adjust the join when needed.
+
+The entity bevel modifier accepts `miterInner:"arc"|"sharp"`. Omission preserves
+the existing arc behavior. Sharp can avoid crossing artifacts around curved bores;
+it does not guarantee a smooth union or solve the vessel-handle seam. This option
+does not belong to `generator.bevel`. Inspect real close-ups after changing it.
+
+Use these checkpoints before delivery:
+
+For environmental reflections and illumination, ingest an equirectangular
+HDR/EXR (linear Rec.709) or PNG/JPEG (sRGB), declare it, and set
+`world:{strength:0.6,environment:{assetId:"studio-environment",rotation:0}}`.
+Rotation is around world Z in radians. `world.set` replaces the whole block;
+retain the environment when adjusting strength, omit it to return to flat color.
+Check highlight placement on the product, not only the background image.
+
+For brushed metal, use a Principled material with `parameters.anisotropic` in
+[0,1] and `anisotropicRotation` in turns (0.25 = 90 degrees). Set a real tangent
+with `material.tangent.set`: `{mode:"uv",uvMap:"UVMap"}` follows that named UV
+map, or `{mode:"radial",axis:"z"}` follows Blender's cylindrical projection
+around the object's local x/y/z axis. Active anisotropy requires Cycles; emission
+materials reject these fields. Nonzero strength/rotation or their animation
+requires an explicit tangent. UV existence is checked on faces actually using
+the material, after local slot overrides, including evaluated native curves and
+text without changing their source data. Zero strength and rotation can
+remove tangent with null. Inspect changed highlights in a close-up; procedural
+noise can add microtexture but is not a substitute for anisotropic reflection.
+
+For procedural grain, set the full texture with material.texture.set. Coordinates
+default to object space. Use coordinates:"uv" and optional uvMap:"UVMap" to
+follow an authored surface layout; omitting the UV name uses the active render
+layer. Named maps must exist on every evaluated surface actually using the
+material; unused slots do not block compilation. UV mode requires principled
+or glass. On lathe UV (U around circumference, V along profile), noise with
+scale:1 and stretch:[0.0001,800,1] follows circumferential lines. Compare roughness
+and grain separately under fixed lighting and camera; UV frequency is layout
+relative, not a physical groove measurement.
+
+For image PBR, ingest PNG/JPEG maps and declare the returned assets, then use
+`material.images.set` with baseColor/roughness/metallic/normal/alpha/emissionColor
+bindings. Each binding names an assetId; optional scale and offset are UV vectors,
+uvMap names an existing UV layer. Scalar maps support channel r/g/b/a (default r),
+normal supports strength and expects OpenGL tangent-space data. Color maps are sRGB;
+numeric maps are Non-Color. Clear procedural texture before binding images. Maps
+replace their socket values; emissionColor still needs emissionStrength. Verify
+actual texture scale and surface response in a close-up, not only node existence.
+
+Revise existing geometry with `entity.generator.set` (replace the full generator)
+and `entity.modifiers.set` (replace the full ordered stack; [] clears it). Preserve
+entity identity so material, camera and animation references survive the edit.
+
+1. **Proportions:** inspect a neutral clay preview from front, side and three-quarter
+   views. Compare silhouette, scale and part placement with the goal/reference.
+2. **Geometry:** inspect a close-up for edge rounding, wall thickness, joins and
+   repeated details. Use the generator's bevel where suitable; increasing render
+   samples cannot repair a coarse silhouette or missing geometry.
+3. **Materials and lighting:** preserve imported materials unless an override is
+   intentional. Inspect metal reflections, surface roughness, glass transparency,
+   texture scale and contact shadows. Keep preview and final color transforms the
+   same so a finish approved in preview survives final rendering.
+4. **Motion:** inspect the first, middle and last frames and every important reveal.
+   Check intersections, framing and whether the lighting still describes the shape.
+
+For each checkpoint, record what was inspected, what remains wrong and the next
+specific change. A high composition/exposure score does not establish visual quality.
+When the current tools cannot produce an essential detail, report that limitation
+and propose an asset or supported construction that meets the requirement.
+
+To inspect geometry and finish independently, first call `blender_scene_get` for
+the revision and existing cameras. Call `blender_preview_render` with explicit
+`revision`, `cameraId`, `frame` and `mode:"clay"`; repeat with `mode:"beauty"` at
+the same camera and frame. For example:
+
+```json
+{"projectId":"product","revision":"r0003","cameraId":"camera-detail","frame":1,"mode":"clay","samples":16}
+```
+
+These inspections require Host API 6 or newer and attach the verified PNG when
+an attachment store is available. If the result says no image was attached, the
+model has not seen it; read the actual image before making visual claims. Images
+are rebuilt from SceneSpec in independent storage and do not alter the source
+revision or ordinary previews. Clay removes transparency, emission, textures and
+bump/normal response; imported shader displacement can change the rendered shape.
+It does not prove wall thickness, manifold geometry, no intersections or artistic
+approval. Use declared cameras for front, side, three-quarter and detail checks;
+if a needed camera is absent, add it through the normal revision workflow first.
+Record the source revision, camera, frame, mode and concrete findings, then patch
+the current revision and repeat the affected views with the same settings.
+
 1. **`blender_capabilities`** — what this Blender can actually do: engines, formats,
    GPU. Call it once per session before promising anything. It reports absence as
    data (`installed: false` plus a warning), never as a crash.
-2. **`blender_project_create`** — a project owns a SceneSpec, a revision history and
-   the render output. The first revision is `r0001`.
-3. **`blender_asset_ingest`** — only if the user brought a model file. It is a two-step
-   contract and the second step is easy to forget; see "Bringing in a model" below.
+2. **`blender_recipe_list` / `blender_project_create`** — inspect locally validated product recipes
+   before building a matching product from scratch. Create from the returned recipe id, version
+   and digest, with only its declared parameter overrides; never combine recipe with sceneSpec.
+   Recipe colors are scene-linear RGB, not hex/sRGB. Source/license/hash metadata does not prove
+   authorship or artistic quality. A project owns its SceneSpec, revision history and render output;
+   the first revision is `r0001`. If no recipe fits, use a supplied scene or the minimal scaffold route.
+3. **`blender_asset_ingest`** — import an authorized model or image into project storage.
+   Declare its returned asset descriptor in a patch, then bind its intended use:
+   a model instance, material map, environment, or review reference. See the model
+   workflow below and the reference image guide above.
 4. **`blender_scene_get`** — read before writing. Patching without reading is how a
    stale `baseRevision` produces a refusal you then have to diagnose.
 5. **`blender_scene_patch`** — the ONLY way to change a scene. There is no free-form
    edit and no script. See "Revision discipline" below.
 6. **`blender_preview_render` / `blender_preview_views`** — look at it. `preview_views`
-   renders several declared views in one Blender launch and returns a contact sheet.
+   renders several declared views in one Blender launch and returns contact sheet
+   paths and measurements as text. It does not attach those images automatically;
+   read the images before claiming to have seen them. Single-frame `preview_render`
+   attaches an independent inspection when an explicit beauty/clay mode is set.
 7. **`blender_visual_review`** — ask for a measured judgement (see "Who decides what").
-8. **`blender_visual_autofix`** — hand the loop a goal and let it iterate, when the
-   problem is one the measurements can see.
+8. **`blender_visual_autofix`** — iterate against the revision's saved goal and
+   reference images with a bounded budget. It requires evidenced artistic judgment
+   as well as technical measurements; it cannot rewrite the target to obtain a pass.
 9. **`blender_final_render`** — only once the preview is right. It returns as soon as
    the job is durable, not when it finishes.
 10. **`blender_job_status`** — poll it, or come back to it in a later turn. A render
@@ -82,6 +217,15 @@ Two steps follow it, and a scene that skips the second one has an asset nobody u
 import. Setting `license` on anything you downloaded is worth the argument: an asset
 whose provenance is unrecorded is one nobody can safely ship.
 
+For local .gltf/.glb buffers/images or .obj MTL/texture dependencies, pass sourceRoot when resources
+live above the model directory. Use the returned path and hash in asset.add;
+dependency changes create a new locked path even if the main-file hash is unchanged.
+Remote external dependencies are refused. Old declarations with unlocked core
+resources must be reimported from the complete local source; compilation refuses
+before clearing the scene. OBJ also includes an existing same-basename .mtl, even
+without mtllib. Used OBJ textures are embedded in checkpoints; undecodable or
+oversized images refuse compilation. Self-contained GLB keeps its single content-addressed file.
+
 ## Revision discipline
 
 - **One successful patch = one immutable revision.** Nothing rewrites history.
@@ -90,8 +234,9 @@ whose provenance is unrecorded is one nobody can safely ship.
 - **Retrying is safe.** An omitted idempotency key is derived from the patch itself, so
   an accidental resend returns the first result instead of making a second revision.
   Pass an explicit key only when you deliberately want the same operations twice.
-- **Going back is `blender_revision_restore`**, which moves the pointer forward to a
-  copy — it does not delete anything. Use it when a change measured worse.
+- **Going back is `blender_revision_restore`**, which selects an existing revision
+  as the current revision and preserves history. Read the current revision again
+  before the next patch. Use it when a change measured worse.
 - **Long renders resume; they do not restart.** `blender_final_render` with a
   `resumeJobId` renders only the frames that are missing or corrupt. The frames on disk
   are the authority, not the job record, so a render killed mid-frame resumes correctly.
@@ -116,11 +261,18 @@ hard to get wrong:
   the measured issues, and what the vision model *reported*. A reported finding is kept
   only if the view exists, the category is in the closed set, and the evidence is not
   empty. Never present a reported finding as a measurement.
-- **Autofix only adopts a fix that measurably improved the score.** A round that did not
-  improve is rolled back — the revision stays in history, but the project does not move
-  to a worse version. If the loop stops short of the goal it hands back the open issues
+- **Autofix separates technical and artistic quality.** It reviews geometry, materials,
+  lighting and goal fit even when the technical score passes. It can adopt an evidenced
+  artistic improvement at an unchanged technical score; regressions and unsupported
+  equal-score changes are rolled back. Missing artistic evidence is not approval.
+  Candidate comparisons receive both the baseline and candidate sheets. If the loop
+  stops short of the goal it hands back the open issues
   with their measurements and the revisions it tried; that handover is the state to
   continue from, not a failure to re-run.
+- **Reference claims need recorded image evidence.** A referenced dimension passes
+  only when its `referenceIds` cover every applicable attached reference. Technical
+  scores, successful uploads and scripted reviewer tests do not prove a visual match.
+  If the reviewer or image input failed, report that limitation rather than a pass.
 
 ## Reading the evidence you get back
 
@@ -142,3 +294,12 @@ hard to get wrong:
 - The workbench UI shows the same authoritative state you are reading. If a user says the
   panel disagrees with you, the panel is reading the host and the host is reading disk —
   find the difference rather than assuming either side.
+
+### 导入模型的部件材质
+
+先保存导入资产的检查点，再读 `blender_scene_get.assetParts` 的准确 partId；slotIndex 使用
+sourceMaterialSlots 的原始 index。materialSlots 只表示当前结果，可能已被整体覆盖合并。
+用 `entity.materialBindings.set` 完整替换局部绑定（保留未修改项），每项是
+`{partId,materialId,slotIndex?}`。省略槽位表示这个网格的全部槽，指定槽覆盖优先。
+保持原几何、UV 和面的材质索引；部件父路径不隐式选择后代。空数组恢复原材质或现有
+entity.materialId 的整体覆盖。局部图片材质同样要求被使用网格有对应 UV；不要猜选择器。

package/presets/deepblend/skills/deepblend-studio/references/reference-images.md

@@ -0,0 +1,100 @@
+# Reference images for DeepBlend review
+
+Use this workflow when a design goal includes photographs, sketches or material
+examples. References guide artistic review; they do not become geometry, material
+maps or environment lighting unless explicitly bound for those separate uses.
+
+## Save the target before reviewing
+
+1. Read the current revision with `blender_scene_get`. Identify what each image
+   should guide: `geometry`, `materials`, `lighting` or `goalFit`.
+2. Import the image using `blender_asset_ingest {projectId, sourcePath}`. A remote
+   `sourceUrl` uses that tool's existing approval flow. Reviews never fetch an image
+   URL directly. Keep the returned `assetId`, `type`, `path` and `sha256`.
+3. Send one `blender_scene_patch` against the revision you read. Use `asset.add`
+   for new assets, followed by `project.brief.set {goal, referenceImages}`. This
+   operation replaces the entire brief: preserve every reference still wanted.
+4. Review the resulting revision with `blender_visual_review`. Use
+   `blender_visual_autofix` when bounded corrective changes are wanted. Both read
+   the saved revision's references automatically.
+
+Each reference has this shape (replace the digest placeholder with the actual
+ingest result):
+
+```json
+{
+  "id": "finish-reference",
+  "assetId": "finish-photo",
+  "sha256": "<returned-sha256>",
+  "label": "Brushed champagne metal",
+  "purposes": ["materials", "lighting"],
+  "notes": "Match the finish and highlights, not the object shape"
+}
+```
+
+Rules that affect the request:
+
+- At most four static PNG/JPEG references. Each must be at most 8 MiB,
+  16,000,000 pixels and 8192 pixels per side. A smaller deployment asset limit
+  can constrain uploads further. Animated or malformed images are refused.
+- `id` must be unique. `purposes` must contain one to four distinct allowed values.
+  `label` is 1–160 characters; optional `notes` is at most 1000.
+- The asset must be declared in the same revision, with matching `sha256` and
+  `assets/raw/<sha256>.<type>` path. Do not resolve a newer same-name asset alias.
+- `goal` is at most 2000 characters. Both brief fields are required; `goal:""`
+  and `referenceImages:[]` clear the target. Clear a reference before removing
+  its asset, including when both operations share one patch.
+- UI uploads store assets only. The user must save the brief to create its new
+  revision. An unsaved draft does not change the reference set used for review.
+
+## Choose the main review subject
+
+Use `project.reviewSubject.set {entityId}` to save the entity measured for framing,
+exposure and occlusion; `entityId:null` restores automatic selection. Choose an
+existing non-empty entity, commonly the product body. This does not move cameras
+or replace the brief. Clear or replace the binding before removing the entity.
+A hidden bound entity stays selected and is reported unavailable.
+
+Automatic selection can choose a long accessory by bounding radius. For multipart
+products, inspect the resolved subject and save an explicit choice when needed.
+`subject-part` marks required body parts; independent `subject` objects are not
+implicitly parts. Artistic review must still inspect the full product and scene.
+Read the actual saved `review.subject` and its availability/reason in QA, not an
+unsaved selector draft. Missing measurements cannot establish technical or artistic
+pass even when the remaining numeric score is high.
+
+## Interpret the evidence
+
+`visual_review.score`, `pass` and `technicalPass` describe technical measurements.
+Read `artistic` separately. Each dimension needs an actual rendered `viewId`,
+specific visible evidence and sufficient confidence. For dimensions with references:
+
+- `pass` must cite **all** applicable `referenceIds`.
+- `needs_work` must cite at least one applicable reference showing a mismatch.
+- `unassessable` need not claim reference coverage. Hidden or missing evidence is
+  not approval; invented, duplicate or wrong-purpose IDs are rejected.
+
+The recorded `referenceImages` identify verified image inputs; check
+`reviewer.error` and `referenceInputError` before saying the model inspected them.
+Preserved images and hashes establish which inputs were used, not that the model's
+artistic judgment is correct. Do not claim online visual validation from scripted
+model replies or a green local test suite.
+
+## Keep the evaluation target fixed
+
+Autofix fixes the baseline's actual subject ID across candidate renders, including
+when camera targets, tags or dimensions change. It refuses subject selection,
+removal or hiding operations. A missing, hidden or unmeasured subject stops the
+baseline or conditionally restores the candidate. `REVIEW_SUBJECT_OPERATION_REFUSED`,
+`REVIEW_SUBJECT_CHANGED` and `REVIEW_SUBJECT_UNAVAILABLE` are round/handover reasons.
+
+Autofix cannot change the brief or delete/replace referenced assets. It compares
+`reviewInputsDigest` before accepting candidates. `REVIEW_INPUT_OPERATION_REFUSED`
+means the proposal was blocked; `REVIEW_INPUTS_CHANGED` means the candidate cannot
+be accepted against the earlier target. These are round/handover reasons.
+
+A failed candidate is restored only if the project is still on that candidate.
+On `REVISION_CONFLICT`, read the current revision and inspect intervening changes.
+Do not bypass that guard. On missing or changed reference bytes, restore the
+original asset or deliberately import and save a new target; do not silently
+substitute another picture. A legitimate target change starts a new review.