聚合文件操作。按 ``action`` 派发：create / open / save / close / delete /
list / import / export。
- ``create`` / ``open`` / ``save`` / ``close`` / ``delete`` / ``list``:
  manage in-memory documents. ``open`` and ``save`` read/write the JSON
  scene format; ``create`` starts a new document (optional ``template`` /
  ``unit``).
- ``export``: write the current document to an interop format — step
  (recommended), dxf, stl, dwg or json — at ``path``.
- ``import``: load an interop file (.json / .dxf / .step / .dwg) as a new
  document.

When not to use: ``cad_file`` handles whole files/documents. For
per-object geometry edits use ``cad_object``; to import/export raw JSON
scene data (not files) use ``cad_json`` (import_scene/export_scene).

聚合对象操作。按 ``action`` 派发：create / read / update / delete / copy /
transform / list / boolean。
- ``create``: add an entity by ``type`` (line, circle, arc, rectangle,
  polygon, polyline, box, cylinder, sphere, cone) with ``params``;
  returns the new ``object_id`` and bounding box.
- ``read`` / ``update`` / ``delete`` / ``copy``: inspect, edit (geometry /
  layer / properties), remove, or duplicate an object by ``object_id``.
- ``transform``: apply a 4x4 matrix (column-major, translation in the
  fourth column) for translate / rotate / scale.
- ``list``: enumerate objects, optionally filtered by ``layer``.
- ``boolean``: combine objects (union / subtract / intersect) into a new
  mesh; requires the optional ``boolean`` extra.

When not to use: ``cad_object`` edits the current document's geometry.
For interop file formats use ``cad_file`` (import/export); for JSON
scene round-trips use ``cad_json``; for measurements on existing objects
use ``cad_measure``; for geometric validation use ``cad_validate``.

聚合图层操作。按 ``action`` 派发：create / read / update / delete / list。
Layers group objects for display and selection. ``create`` accepts
color / linetype / linewidth; ``update`` can also toggle ``visible`` /
``locked``; ``delete`` removes the layer *and* the objects on it.

When not to use: for per-object layer membership use ``cad_object``
(create/update with a ``layer``); for per-layer object counts use
``cad_status`` (target=layer). To hide objects without deleting them
prefer ``cad_layer`` (update visible=false).

按 ``action`` 执行 JSON 读写、解析、校验、导入与导出：
- load：读取文件原文
- parse：解析并报告结构
- validate：按 scene/geometry 模式校验
- import_geometry：将 JSON 几何导入当前文档
- export_geometry：将对象导出为 JSON
- import_scene：以 JSON 场景创建新文档
- export_scene：导出当前文档为 JSON 场景
- save：将 JSON 字符串写入文件

When not to use: ``cad_json`` operates on JSON text and scene data in
memory. To read/write the JSON scene as a whole file use ``cad_file``
(open/save); for interop formats (STEP/DXF/STL/DWG) use ``cad_file``
(import/export); for creating/editing individual geometry objects use
``cad_object``.

按 ``target`` 查询当前会话的各类状态（check/file/object/layer/health/
logs_get/logs_clear）。
- ``check``: overall session summary (open files, current document).
- ``file`` / ``object`` / ``layer``: live detail for one entity.
- ``health``: server version, uptime and registered tool count.
- ``logs_get`` / ``logs_clear``: read (with limit/level/source/job_id
  filters) or clear the in-memory log buffer.

When not to use: ``cad_status`` reports live session/server state. For
geometric *validation* (manifold checks, interference) or aggregate
document statistics use ``cad_validate`` (geometry/metrics); for
measuring distances/areas use ``cad_measure``.

聚合校验操作。按 ``action`` 派发：geometry / interference / topology / metrics。
- ``geometry``: check objects for self-intersections, degenerate faces and
  non-manifold edges (optional ``object_ids`` filter); returns issues with
  ``type`` / ``location`` / ``fix_suggestion``.
- ``interference``: detect box-box overlaps between objects, with overlap
  volume per pair.
- ``topology``: per-object vertex/edge/face counts and manifold status.
- ``metrics``: aggregate document stats (files, objects, layers, bbox,
  kinds) for the current session.

When not to use: ``cad_validate`` analyzes correctness and aggregates.
For simple geometric measurements (distance / area) use ``cad_measure``;
for live server/file/object status use ``cad_status``; for JSON scene
validation against the schema use ``cad_json`` (action=validate).

按 ``action`` 执行批处理操作：execute / schedule / status / cancel / list /
templates / run_script。
- ``execute``: run a list of tool calls synchronously (each ``command``
  has ``tool`` + ``arguments``); ``stop_on_error`` halts on the first
  failure.
- ``schedule`` / ``status`` / ``cancel`` / ``list``: create and manage
  one-off / cron / dependency-chained jobs (durable across restarts).
- ``templates``: list reusable Jinja2 command templates.
- ``run_script``: execute a sandboxed script (python / scr / batch).

When not to use: ``cad_batch`` sequences *other* tools. For a single
operation call the concrete aggregate directly (``cad_object``,
``cad_file``, ...). ``execute`` is synchronous — use ``schedule`` for
long-running work.

按 ``mode`` 渲染当前文档：
- ortho：2D 正交投影 PNG（top/front/side）
- view_3d：按存储的三维视图定义渲染 PNG
- section：平面剖切 PNG（plane=XY/YZ/XZ）
- explode：爆炸视图 PNG
- animation：orbit/turntable GIF 动画
- webgl：WebGL 增量同步 delta

When not to use: ``cad_render`` produces images / sync deltas only. To
store or edit a named view *definition* before rendering use
``cad_view``; for drawing-sheet exports (SVG/DXF/PDF) use
``cad_drawing`` (action=export); for interop geometry files use
``cad_file`` (export).

按 ``action`` 执行版本快照操作：save / list / diff / restore。
In-memory snapshots of the current document state. ``save`` captures a
labeled snapshot; ``diff`` compares two snapshots with ``deepdiff`` and
reports changed/added/removed fields; ``restore`` rolls the document back
to a snapshot.

When not to use: ``cad_version`` is for in-memory undo-like versioning.
For durable file persistence use ``cad_file`` (save/export); for
collaboration branches use ``cad_collab`` (tool=branch).

聚合 NLP 操作。按 ``action`` 派发：command / chat。
- ``command``: map free-form English/Chinese text to a CAD tool call
  (returns ``tool`` + ``arguments``; does NOT execute it). Ambiguous
  requests return candidate ``suggestions``.
- ``chat``: multi-turn dialogue with anaphora resolution — a create
  intent executes immediately and its object is remembered so "move it"
  / "把它" resolve to that object.

When not to use: ``cad_nlp`` is a convenience dispatcher. For
deterministic, schema-driven control prefer calling the concrete
aggregate tools directly (``cad_object``, ``cad_file``, ...). ``command``
only parses — you must dispatch the returned call yourself.

聚合 3D 视图操作。按 ``action`` 派发：create / read / list / update / delete。
Manages named ``View3DDefinition`` records (camera pose, projection,
section plane, explode offsets). Each view has a unique ``name`` per
document and an optional explicit ``view_id``.

When not to use: ``cad_view`` manages view *definitions* only — it does
not produce images. To render a stored view (or ortho / section / explode /
animation / webgl output) use ``cad_render`` (mode=view_3d etc.).

按 ``action`` 设置（set）或列出（list）当前文档的参数变量。Set with
``value`` and/or ``expr`` (expressions may reference other variables,
e.g. ``width * 2``); ``{name}`` tokens in CLI draw arguments interpolate
the resolved value.

When not to use: variables are document-scoped bookkeeping — do NOT use
them to store free-form strings (only numeric values), and use
``cad_object_update`` for geometry changes rather than variables.

按 ``action`` 执行约束操作：add / remove / list / solve。
Adds 2D sketch constraints between entities (e.g. coincidence, distance,
angle). ``solve`` runs the constraint solver and reports residual error;
the optional ``planegcs`` backend is used when installed.

When not to use: ``cad_constraint`` constrains *geometry*; for assembly
mating (parts) use ``cad_assembly`` (action=add_mate/solve). For direct
transforms use ``cad_object`` (action=transform).

聚合装配操作。按 ``action`` 派发：create / add_part / add_subasm /
add_mate / remove_part / solve / bom / explode。
- ``create``: initialize the document's assembly container.
- ``add_part`` / ``add_subasm``: build the tree; parts may reference a
  document ``entity_id`` and nest under a ``parent_id``.
- ``add_mate``: constrain two nodes (coincident / concentric / parallel /
  perpendicular / distance / angle).
- ``solve``: apply mates in order and return every node's world transform.
- ``bom``: flattened bill of materials (``format`` json or csv).
- ``explode``: radial offsets by tree depth (``direction`` x/y/z).

When not to use: ``cad_assembly`` composes *parts*, not geometry. Create
part geometry first with ``cad_object`` (create), then add it to the
assembly. For drawings of an assembly use ``cad_drawing``.

聚合工程图操作。按 ``action`` 派发：create / add_view / add_section /
add_dimension / add_tolerance / delete / export。
- ``create``: a sheet (paper A0-A4, title block).
- ``add_view`` / ``add_section``: main / projection / section / detail /
  isometric views over referenced entities.
- ``add_dimension``: ISO 129-1 dimensions (linear / angular / radial /
  diameter / ordinate).
- ``add_tolerance``: GD&T feature-control frames (position / flatness /
  parallelism / perpendicularity / concentricity).
- ``export``: write the sheet as svg / dxf / pdf at ``path``.

When not to use: ``cad_drawing`` produces engineering drawing sheets.
For plain 2D/3D preview images use ``cad_render``; for interop geometry
files use ``cad_file`` (export step/dxf/stl); for object geometry edits
use ``cad_object``.

聚合特征操作。按 ``action`` 派发：sweep / loft / fillet / chamfer /
pattern_linear / pattern_circular / pattern_mirror。
- ``sweep`` / ``loft``: create new solids from a profile (sweep along a
  ``path``) or between ``profile_ids`` (loft). OCCT-backed when the
  ``occ`` extra is installed, with analytic fallbacks otherwise.
- ``fillet`` / ``chamfer``: round or bevel edges — exact on the OCCT
  kernel, otherwise report ``requires_occ``.
- ``pattern_linear`` / ``pattern_circular`` / ``pattern_mirror``: copy an
  entity into an array (rigid transforms, available on every kernel).

When not to use: ``cad_feature`` derives new geometry from existing
entities. For editing a single object's parameters use ``cad_object``
(update/transform); for boolean combination use ``cad_object``
(action=boolean).

聚合仿真操作。按 ``action`` 派发：mesh / setup / run / result / list / delete。
- ``mesh``: generate a hexa8 hex mesh of an entity's bounding box (pure
  Python, always available).
- ``setup``: register a simulation (``kind`` = fea or kinematics).
- ``run``: execute synchronously, or schedule an async batch job with
  ``async_run``. FEA (CalculiX) and kinematics (PyBullet) backends are
  optional — absent engines report ``requires_sim``.
- ``result`` / ``list`` / ``delete``: inspect or remove simulations.

When not to use: ``cad_sim`` analyzes physical behavior. For geometric
*validity* checks use ``cad_validate`` (geometry/interference); for
meshing previews that are pure geometry use ``cad_object`` (read).

聚合协作操作。按 ``tool`` 派发到协作子域：session / branch / annotation /
presence / history / resolve / permission / sync。
- ``session``: create / list / join / leave / info a collaboration session
  over a document.
- ``branch``: fork / edit / merge / list document branches (CRDT).
- ``annotation``: add / list / close review annotations.
- ``presence``: set / get / list user presence.
- ``history``: applied operation history.
- ``resolve``: settle a branch-merge conflict (ours / theirs / latest).
- ``permission``: RBAC list / grant / check (viewer/editor/admin/owner).
- ``sync``: push operations + pull deltas/state — the WebSocket entry point.

When not to use: ``cad_collab`` coordinates *multi-user* work on a
document. For single-user edits use ``cad_object`` / ``cad_layer`` /
``cad_file`` directly; RBAC defaults to the session owner for unknown
users until an identity transport is configured.

聚合测量操作。按 ``action`` 派发：distance / area。
- ``distance``: Euclidean distance between ``point_a`` and ``point_b``
  (2D ``[x, y]`` or 3D ``[x, y, z]``), returns ``distance``.
- ``area``: measure an existing object by ``object_id`` — 2D kinds
  (circle / rectangle / polygon) return area (``mm^2``), 3D kinds
  (box / cylinder / sphere / cone) return volume (``mm^3``); ``kind``
  in the output reports which.

When not to use: ``cad_measure`` reads existing geometry. To query
object position / bounding box use ``cad_object`` (action=read) or
``cad_status`` (target=object); to validate mesh validity use
``cad_validate`` (action=geometry).

聚合插件工具。按 ``action`` 派发：install / uninstall / list / enable /
disable / manifest。
- ``install``: 触发 entry-point 发现，只从已安装发行版加载插件（不接收
  任意模块路径）。
- ``uninstall`` / ``enable`` / ``disable``: 按名字管理插件生命周期。
- ``list``: 触发 entry-point 发现并列出已安装插件。
- ``manifest``: 返回指定插件的静态声明（名称/版本/权限/依赖）。

Security: 插件与服务器运行在同一进程 / 信任域，未做进程级沙箱。
``install`` 只加载已安装发行版的 entry-point 插件（等价于 ``pip
install`` 的信任边界），不接受 ``module:attr`` 导入。仅从可信来源安装
插件；进程级沙箱是后续硬化项。

When not to use: 插件提供的实际建模能力应通过其注册的 MCP 工具直接调用；
``cad_plugin`` 只管理插件生命周期。

聚合 CAM 工具。按 ``action`` 派发：
- ``toolpath``: 从当前文档的矩形/多边形（轮廓）与圆（钻孔）生成 2.5 轴刀轨，
  返回轮廓数、钻孔数、刀轨长度与包围盒。
- ``simulate``: 返回仿真报告（刀轨长度 + 估算加工时间）。
- ``export_gcode``: 生成并写出 G-code（G0/G1 + 钻孔循环，M2 结束）。

When not to use: 需要完整 3D 刀具路径或刀轴控制时超出本工具范围；本工具
聚焦 2.5 轴轮廓铣削 + 钻孔。

聚合 glTF 工具。按 ``action`` 派发：
- ``export``: 将当前文档的实体（实体几何）导出为自包含 glTF 2.0 文件，
  颜色属性映射为 PBR ``baseColorFactor``。
- ``import``: 读取 glTF 文件并把每个 mesh 作为 ``mesh`` 实体导入当前文档。
- ``preview``: 返回当前文档 glTF 表示的概要（mesh 数 / 包围盒）。

When not to use: 需要 STEP/DXF/STL 等工程格式互操作时用 ``cad_file``
（import/export）；本工具专注 glTF 网格资产。