优化skill，添加特征树、编辑窗口

SimpleCADAPI/skills/simplecadapi/references/agent-capabilities.md

@@ -0,0 +1,152 @@
+# SimpleCADAPI Agent Capability Guide
+
+This document is the required backend capability brief for CAD Agent Studio
+when considering the `simplecadapi` route. It is intentionally an Agent-facing
+decision document, not a geometry template.
+
+## Role
+
+Use this route when the Agent will author backend-native SimpleCADAPI Python
+source and the server will only execute, validate, normalize to DesignIR 3.0,
+and publish artifacts.
+
+SimpleCADAPI is strongest when its standard factories or replayable model graph
+capabilities materially improve correctness, editability, or validation.
+
+## Strong Fits
+
+- The primary requested object is a supported standard mechanical family:
+  spur, helical, herringbone, ring, or bevel gears; racks; cycloidal discs;
+  ball bearings; bolts; nuts; roller-chain sprockets; planetary or cycloidal
+  reducers; joint actuator assemblies.
+- The task benefits from `@model`, `ModelResult`, `capture_result`, model JSON,
+  graph replay, semantic tags, topology lineage, source mapping, QL inspection,
+  unit checking, tolerance chains, scene packages, or CAD translators.
+- The task needs strict STEP/B-Rep diagnostics, target/candidate comparison,
+  multi-view diagnostics, or slice XOR diagnostics.
+- The model is a reusable mechanical product family whose formulas should be a
+  deterministic SDK workflow rather than one-off source construction.
+
+## Weak Fits
+
+- The request is a custom machined part, flange, hub adapter, housing, bracket,
+  plate, or fixture where no SimpleCADAPI standard factory directly represents
+  the primary object.
+- Standard part words appear only as feature context. Examples: bolt holes,
+  screw clearances, nut pockets, bearing seats, gear-mounting holes. These are
+  features of another part, not requests to generate the standard part itself.
+- The requested shape needs freeform or multi-rail surface work outside the
+  documented SimpleCADAPI vocabulary.
+- The current source of truth is an existing build123d source and the user did
+  not request backend conversion.
+
+## Studio Documentation Discipline
+
+For CAD Agent Studio backend selection, this document is sufficient. Decide
+from the capability boundary here: what SimpleCADAPI is strong at, what it is
+weak at, and whether the primary requested object matches those strengths.
+
+Do not read SimpleCADAPI API manuals, SDK indexes, or per-function pages during
+ordinary backend selection. The selection task only needs to know what the tool
+can generate, not the exact API signatures.
+
+Prefer standard-library functions only when the standard component is the
+primary requested object and the factory actually covers it.
+
+## Agent Source Contract
+
+When choosing this backend, submit raw Python source to `generate_cad` with:
+
+- `selectedBackend = "simplecadapi"`
+- `sourceKind = "simplecadapi_python"`
+- A script that accepts `--step`, `--metadata`, and `--model-json`
+- STEP export written exactly to the `--step` path
+- Model JSON written exactly to the `--model-json` path
+- Metadata JSON written exactly to the `--metadata` path
+- stdout JSON is optional diagnostic output; file artifacts are the source of
+  truth for execution success
+
+The source should use one replayable `@model` entry point when model JSON or
+graph replay is part of the task. Capture explicit outputs with
+`capture_result(...)` and write the returned `ModelResult.model_json`.
+
+Do not submit diagnostic, API-probing, topology-probing, radius-sweep, or smoke
+test scripts as `nativeSource`. Do not use `inspect.signature(...)`, broad
+`dir(...)` dumps, trial loops, or intentional exceptions to discover the SDK or
+geometry at execution time. The source submitted to `generate_cad` must be the
+final model generator for the user's part and must write the requested file
+artifacts in one execution. If this compact reference is insufficient, report
+the missing reference instead of using `generate_cad` as an exploration tool.
+
+If exposing editable parameters, include a top-level block:
+
+```python
+# CAD_AGENT_PARAMETERS_START
+PARAMETERS = {
+    "example": 1.0
+}
+# CAD_AGENT_PARAMETERS_END
+```
+
+Each editable metadata parameter must include `name`, `value`, `unit`,
+`editable`, `binding_kind`, `parameter_path`, and `regenerate_adapter`.
+Use `binding_kind = "python_constant"` for parameters bound to the
+`PARAMETERS` block, or `model_graph_parameter` only when the parameter is
+actually replayable through the model graph. Use
+`regenerate_adapter = "simplecadapi"`.
+
+## Minimal Native Source Reference
+
+Use this compact API surface for Studio generation. It is included here so the
+Agent can write production source without reading API indexes during backend
+selection.
+
+```python
+import argparse
+import json
+from pathlib import Path
+import simplecadapi as scad
+
+@scad.model(graph_id="model")
+def build_model():
+    shape = scad.std.gear.make_spur_gear_rsolid(
+        n_teeth=24,
+        module=2.0,
+        pressure_angle=20.0,
+        gear_height=8.0,
+    )
+    scad.capture_result(value=shape)
+    return shape
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--step", required=True)
+    parser.add_argument("--metadata", required=True)
+    parser.add_argument("--model-json", required=True)
+    args = parser.parse_args()
+
+    result = build_model()
+    Path(args.model_json).write_text(result.model_json, encoding="utf-8")
+    scad.export_step(shapes=result.value, filename=args.step)
+    Path(args.metadata).write_text(json.dumps({"backend": "simplecadapi"}), encoding="utf-8")
+```
+
+Replace the body of `build_model()` with the requested standard component or
+workflow. Keep the CLI/output protocol unchanged.
+
+Common standard gear factories:
+
+- `scad.std.gear.make_spur_gear_rsolid(n_teeth: int, module: float, pressure_angle: float = 20.0, gear_height: float = 6.0, *, addendum_factor: float = 1.0, clearance_factor: float = 0.25, backlash: float = 0.0)`
+- `scad.std.gear.make_helical_gear_rsolid(n_teeth: int, module: float, pressure_angle: float = 20.0, helix_angle: float = 30.0, gear_height: float = 8.0, *, addendum_factor: float = 1.0, clearance_factor: float = 0.25, backlash: float = 0.0)`
+- `scad.std.gear.make_herringbone_gear_rsolid(n_teeth: int, module: float, pressure_angle: float = 20.0, helix_angle: float = 32.0, gear_height: float = 10.0, *, addendum_factor: float = 1.0, clearance_factor: float = 0.25, backlash: float = 0.0)`
+- `scad.std.gear.make_spur_ring_gear_rsolid(n_teeth: int, module: float, pressure_angle: float = 20.0, gear_height: float = 6.0, rim_thickness: float = 3.0, backlash: float = 0.0, *, addendum_factor: float = 1.0, clearance_factor: float = 0.25)`
+- `scad.std.gear.make_helical_ring_gear_rsolid(n_teeth: int, module: float, pressure_angle: float = 20.0, helix_angle: float = 25.0, gear_height: float = 8.0, rim_thickness: float = 3.0, backlash: float = 0.0, *, addendum_factor: float = 1.0, clearance_factor: float = 0.25)`
+- `scad.std.gear.make_straight_bevel_gear_rsolid(n_teeth: int, module: float, pitch_angle: float = 45.0, pressure_angle: float = 20.0, face_width: float = 8.0, *, addendum_factor: float = 1.0, clearance_factor: float = 0.25, backlash: float = 0.0)`
+
+## Decision Rule
+
+Choose SimpleCADAPI only when the primary requested model or required workflow
+matches its documented standard factories or graph/semantic capabilities. Do
+not select SimpleCADAPI merely because the prompt mentions a standard part word
+inside another feature. For example, a wheel hub adapter with bolt holes is a
+custom flange-like part unless the user asks to generate a bolt as the object.