@coloopx/colocad 0.1.0-alpha.7 → 0.1.0-alpha.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,63 @@
1
+ # 建模、查询与装配最佳实践
2
+
3
+ 适用于 Colocad alpha.8 已支持的 API。[English](best-practices.md) · [完整建模手册](agent-modeling-handbook.zh-CN.md) · [查询契约与边界](engineering-queries.zh-CN.md)。
4
+
5
+ ## 从资料与控制结构开始
6
+
7
+ 先锁定产品型号、配置、单位、整机基准和交付要求。图纸/PDF、照片、BOM、参考 STEP 是证据;agent 用 harness 的阅读工具解释它们,再生成明确的参数和特征指令。给定、推导、假设和未知尺寸分别记录,关键接口未明确时保留未验证状态。
8
+
9
+ 板件从毛坯和孔阵列开始,套筒从内外径与长度开始,壳体从壁厚、底厚和开口关系开始。复用[快速结构资产](../skills/colocad/references/quick-build.md),但按实际产品修改。先完成主体与功能孔腔,再增加次要圆角;重复零件共享定义,尺寸关系写成参数表达式。
10
+
11
+ ## 按当前问题选择工具
12
+
13
+ | 当前问题 | 建议操作 |
14
+ | --- | --- |
15
+ | 只换镜头或图片尺寸 | 同一 client 的 `preview` 或保存网格的 `observeArtifact` |
16
+ | 改尺寸 | 从接受的源 `edit`,再检查受影响接口 |
17
+ | 已有零件的面、孔、轴或安装接口是什么 | 对接受版本的精确快照执行 `query` |
18
+ | 替换一份兼容 STEP | 重算语义基准/接口,求解配合,再跑必需检查 |
19
+ | 新建精确几何 | `build` 或 CLI `record` 保存新的里程碑 |
20
+ | 人类审阅/影片 | CLI `view`、`replay`、`render`,使用真实记录的结果 |
21
+
22
+ 常规建模可先注册 capabilities/validate/build/preview/edit;测量和装配工作加入 capability-gated `cad_query`,按需启用 STEP 检查和草图求解。SDK 的完整 schema 与 `$defs` 保留。Agent、harness、SDK、native 同处一个沙箱。
23
+
24
+ ## 查询 → 设计意图 → 装配 → 改参复验
25
+
26
+ 1. **构建可查询版本。** 普通模型按需设置 `{queryable:true}`;声明 `Model.datums` 或 `Model.interfaces` 时自动启用。保存回执中的 `artifact_directory` 与 `query_revision_id`。定义局部坐标用 `definition_id`;装配实例用 `instance_path`,并明确 `space` 和容差。
27
+ 2. **按安装意图缩小范围。** 先选安装平面,再找该面的开口和孔组。同法向可能同时选中盲孔底面;位置有关时用命名平面与 `planar_coplanar_with`。检查数量、额外孔、竞争候选和 coverage,不自动选第一项。
28
+ 3. **持久化选择规则。** 将受支持的选择/推导写入 `Model.datums`、`Model.interfaces`。快照 ref 是当次观察,不是跨改参的永久标识;不能塞进持久规则或绑定偶然的面编号。对称孔组需要设计给定或几何推导的方向,才能用于定向配合。
29
+ 4. **检查求解后的总成。** 使用命名附件、完整孔对应的 `interface_compatibility`,以及相关零件对的必需 `geometric_relationship`。正的边界距离不一定代表净空:包含关系也可能有正距离;同时看关系类型、重叠量和间隙阈值。
30
+ 5. **改参/替换后重查。** 从接受源重建,取得新版本并重跑规则和检查。缺失、歧义、不兼容作为失败留档,不靠更换面编号强行通过。用兼容与不兼容来源挑战同一装配规则。
31
+ 6. **交付可复核证据。** 保存参数源、完整 session、STEP、数值结果和未覆盖项;由 CLI 导出审阅。离散姿态检查不能证明连续全行程,爆炸动画也不能证明运动无碰撞。
32
+
33
+ 完整的外部 STEP 工作流见[安装接口例子](../examples/engineering-interfaces/README.md):三种兼容替换、两种正确拒绝,使用同一规则,并有独立 OCCT 验证。
34
+
35
+ ## 可以直接执行的改参示例
36
+
37
+ 在新项目安装 `@coloopx/colocad@0.1.0-alpha.8`,将[英文页的完整脚本](best-practices.md#run-the-editquery-loop-against-the-installed-package)保存为 `query-workflow.mjs`,执行:
38
+
39
+ ```sh
40
+ node query-workflow.mjs
41
+ ./node_modules/.bin/colocad replay ./query-session ./query-review.html
42
+ ./node_modules/.bin/colocad view ./query-session
43
+ ```
44
+
45
+ 脚本用 `box` 和 `face_hole_grid` 构造 80×50×6 mm 四孔板及精确快照,查询四个 Ø6 通孔,将孔径改为 Ø8,确认旧版本请求被拒绝,再检查新孔径、孔中心保持和解析体积。预期的旧引用错误保留在会话中。首次运行时 `query-session` 和 `query-review.html` 应尚不存在。
46
+
47
+ **版本说明:**alpha.8 已修复孔阵列精确快照,示例直接使用 `face_hole_grid`。升级 SDK 和配套 native;调预览精度不能修复 alpha.7 的问题。[原始失败](evidence/alpha.7-query-guidance.json) · [修复回归](evidence/release-alpha.8.json)。
48
+
49
+ 它验证的是尺寸件的实际 SDK/CLI 闭环,不是未知图纸重建成功率。
50
+
51
+ ## 返回足够决策的信息,保留完整证据
52
+
53
+ 简短工具反馈保留成功/失败、feature/query ID、`query_revision_id`、目标/坐标系、相关测量、coverage/歧义、时间、全部降级与完整回执路径。不要把成功调用的 partial 结果解释成“完整识别”或“没有孔/碰撞”;完整 STEP、网格和 trace 留在文件系统中。
54
+
55
+ 失败先分类:资料解释、frame/单位、选择歧义、几何操作、引用过期或预算。针对一个原因修复,再复查相关要求。查询版本过期应从最新接受版本重查;不要仅替换旧 ref 上的版本字符串。具体错误见[故障排查](troubleshooting.md)。
56
+
57
+ 尺寸、材料/孔腔、装配和可编辑性分别验收;重要交付用独立内核回读 STEP。渲染、总体积或零退出码不能独立证明全部正确。锥形/相交/侧开/样条孔识别可能为 partial;曲面接触认证、局部区域限定测量仍有明确支持边界。
58
+
59
+ ## 调优时保持测量口径
60
+
61
+ 分开记录建模、快照创建/加载、查询、STEP、三角化、渲染与推理。只为读现有几何时避免重建;先缩小查询范围和结果页,再考虑提高预算。
62
+
63
+ 内存看 cgroup 峰值、OOM、子进程与缓存页,RSS 作为补充。[alpha.7 安装包验收](evidence/release-alpha.7.json)包含 npm 安装,[G3 实验](../specs/experiments/0005/README.md)测的是另外的 CAD/驻留 agent 负载,不能混成同一指标。历史灵巧手对照也不能外推为全部复杂模型的性能保证。G4 benchmark/回溯优化尚未启动。
@@ -0,0 +1,105 @@
1
+ # Colocad and CadQuery: coverage and design
2
+
3
+ Audit date: **2026-11-10**, Colocad **0.1.0-alpha.8**. [中文](cadquery-comparison.zh-CN.md) · [Machine-readable mapping](cadquery-coverage.json) · [Roadmap](../ROADMAP.md).
4
+
5
+ Colocad is an independent agent-oriented mechanical CAD stack. It has useful native modeling, exact queries and geometry-driven assembly, but **does not replace the full CadQuery API or its geometry ecosystem**. It accepts neither CadQuery Python programs nor CadQuery selector strings. Similar operation names do not establish identical options, solver semantics or robustness.
6
+
7
+ ## How to read the audit
8
+
9
+ The inventory includes all **150 distinct entries** in the requested [CadQuery API index](https://cadquery.readthedocs.io/en/latest/apireference.html). Its source is pinned to [CadQuery commit b3f9afd](https://github.com/CadQuery/cadquery/blob/b3f9afd4f39cbd856d0c46aa30aa37b714b8f6cb/doc/apireference.rst); the JSON records its SHA-256. `/latest/` is mutable and is not a promise about an installed CadQuery version. Constructors, convenience methods and deep geometric operations each count as one index entry; these counts are **not a capability percentage or a differential-test pass rate**.
10
+
11
+ | Classification | Entries | Meaning |
12
+ | --- | ---: | --- |
13
+ | Supported domain | 36 | An analogous native operation exists within the stated Colocad contract. Not identical arguments or general equivalence. |
14
+ | Partial | 30 | Relevant native capability exists with material option, domain or semantic gaps. |
15
+ | Recipe | 29 | A caller can compose primitives or coordinates; no dedicated general equivalent is claimed. |
16
+ | Unsupported | 29 | No corresponding public contract. |
17
+ | Different abstraction | 26 | Explicit graph/session/typed JSON takes the place of stateful chaining; not drop-in compatibility. |
18
+
19
+ This is a source/schema audit with links to representative Colocad tests. We did **not** run 150 paired CadQuery/Colocad conformance tests. Low-level Shape/free-function APIs and plugins extend beyond this index and are discussed separately below. The [earlier detailed assembly review](../specs/reviews/0004-cadquery-2026-11-09.md) remains useful for constraint semantics.
20
+
21
+ ## Design comparison
22
+
23
+ | Dimension | CadQuery | Colocad | Practical consequence |
24
+ | --- | --- | --- | --- |
25
+ | Geometry stack | Python API over OCCT/OCP | TypeScript/JSON adapter over a local Rust executor and pinned SolidCore dependency | Different kernels and failure domains. Colocad does not use OCCT at runtime; independent OCCT verification is an optional test tool. |
26
+ | Modeling interface | Fluent Workplane, Sketch, lower-level Shape and free functions | Explicit parameter/feature graph, final definition IDs and instance graph | More explicit state and machine validation; fewer convenience/low-level APIs. |
27
+ | Intent | Relative workplanes, selectors, tags and reusable Python source | Expressions, named topology, recomputable datums/interfaces, required checks | Both can encode intent; neither automatically makes every edit stable. |
28
+ | Source editability | Python source is the parametric source | JSON/TS source plus accepted session source and receipts | STEP is geometry exchange, not native editable feature history. |
29
+ | Selection | Object/selector APIs and selector DSL | Bounded typed selection expressions, explicit cardinality, partial/ambiguity results | CadQuery code must be translated; Colocad query expressions are not accepted by every modeling feature selector. |
30
+ | Snapshot references | Tags/history belong to CadQuery's object/operation model | Immutable native snapshots and revision-bound topology refs | Refs survive reopen/relocation of the same snapshot; an edit requires a new query and semantic recipe resolution. |
31
+ | Sketches | Rich face/edge manipulation, constraints and construction workflows | Point/line/circle constraints and bounded local solve; explicit profiles | General sketch offsets, corner editing, interpolating splines and construction state remain gaps. |
32
+ | Surfaces | Low-level topology and free-function surface workflows | Bezier patches, bounded networks, bridges, sew and thicken | Colocad's surface operations are useful but do not prove broad surfacing or Class-A parity. |
33
+ | Assembly | Hierarchy, selection-based constraints and solve | Hierarchy, shared definitions, datums/attachments, mates, interfaces and pair checks | Constraint names cannot be mapped blindly: CadQuery `Axis` is not automatically a concentric mate. |
34
+ | Foreign parts | STEP import and geometric APIs | Registered STEP inputs, exact queries and declared installation recipes | Colocad supports tested compatible replacement families; arbitrary STEP inference remains unproven. |
35
+ | Engineering recognition | Users compose topology queries and modeling logic | Supported analytic bores, plane-scoped groups and planar mounting interface profiles | An extra domain layer, not proof that the lower-level CAD API is broader. Complex bores can be partial. |
36
+ | Human review | CAD viewers and ecosystem integrations | CLI starts persistent session viewer, offline HTML and optional video render | Colocad records actual steps and query overlays; rendered appearance does not certify fit. |
37
+ | Agent integration | Python execution can be wrapped by an agent harness | SDK, CLI, capability-gated tools and packaged skill | Agent, harness and CAD execute together in the sandbox; no additional CAD service is required. |
38
+ | Distribution | Python/native dependency environment | npm package with three precompiled native targets; Node 22+ | Installed modeling needs no Rust/Python compiler; Windows/native commercial CAD support remains separate. |
39
+ | Performance | Depends on workload, dependency build and execution strategy | Existing matched build123d studies and specific sandbox measurements | There is **no new CadQuery performance result** in this audit, and no universal 10× or memory ratio. |
40
+
41
+ The CadQuery descriptions above follow its official [API layers](https://cadquery.readthedocs.io/en/latest/primer.html), [design principles](https://cadquery.readthedocs.io/en/latest/designprinciples.html), [assembly constraints](https://cadquery.readthedocs.io/en/latest/assy.html#constraints), [free-function API](https://cadquery.readthedocs.io/en/latest/free-func.html) and [interchange formats](https://cadquery.readthedocs.io/en/latest/importexport.html). In particular, the free-function API provides an alternative without hidden Workplane state; it would be inaccurate to characterize all of CadQuery as a stateful chain. Its documented experimental history is not a guarantee of persistent topology identity across arbitrary edits.
42
+
43
+ ## Important gaps beyond the index
44
+
45
+ - **Selection-to-feature integration:** query selection supports more compositions than the modeling `EdgeSelector`/`FaceSelector`. A read-only query is not automatically a fillet/shell operand. Extending that bridge needs cardinality, edit and ambiguity tests.
46
+ - **Low-level B-rep construction:** no general user-facing Shape/Face/Edge/Wire authoring API equivalent to CadQuery/OCP. Surface patches and imported solids do not cover arbitrary topology construction or repair.
47
+ - **Sketch/freeform breadth:** general splines, offsets, text, parametric-function sampling, twist extrusion, advanced sweep options and 2D editing need separate contracts and corpora. Some shapes can be composed manually; that is not API coverage.
48
+ - **Interchange/ecosystem:** no full DXF/SVG/XCAF/XBF/3MF/etc. exporter matrix or Python plugin compatibility. General native editable SOLIDWORKS remains incomplete; [native export status](native-solidworks.md) applies.
49
+ - **Reliability:** a native operation existing does not establish CadQuery-level success on all imported surfaces, blends or thin walls. Current acceptance is the frozen G1–G3 scope, not a general industrial failure-rate estimate.
50
+ - **Engineering certification:** unsupported curved-contact exceptions, continuous-motion checks, threads/fit classes, structural loads, manufacturing tolerances and unknown source accuracy remain separate concerns.
51
+
52
+ ## What is actually verified
53
+
54
+ [G1–G3 evidence](../specs/experiments/0005/README.md) covers a 24-case frozen corpus, semantic lifecycle/replacement and two live Pi tasks; it does not cover all 150 CadQuery entries or unseen drawing reconstruction. [Alpha.8 release evidence](evidence/release-alpha.8.json) records the new snapshot regression and actual installed bundles. The original alpha.7 failure evidence remains preserved.
55
+
56
+ The repaired grid path is tested using the bundled four-hole asset, all six stock-face directions and the global grid operation, with native snapshot reopen, seam/loop descriptors and SDK edit/re-query. Independent STEP readback checks geometry rather than trusting native success alone. This is a regression closure, not a new speed benchmark.
57
+
58
+ Future comparison must separately measure deterministic kernel workloads and agent reconstruction from drawings. Use equivalent accepted geometry, edit challenges, identical budgets and independent reference data. The [roadmap](../ROADMAP.md#benchmark-tracks) defines that work and the guarded improvement loop.
59
+
60
+ ## API-index mapping
61
+
62
+ The following table groups every indexed entry exactly once. Implementation paths, test links and limits for each group are retained in [cadquery-coverage.json](cadquery-coverage.json). “Supported” always means the bounded analogous contract described above.
63
+
64
+ <!-- API mapping table is generated from the reviewed coverage JSON. -->
65
+ | Group / indexed APIs | Status | Mapping and boundary |
66
+ | --- | --- | --- |
67
+ | sketch-context: `Sketch`, `Workplane.sketch`, `Sketch.finalize`, `Sketch.copy`, `Sketch.located`, `Sketch.moved`, `Workplane`, `Workplane.center`, `Workplane.moveTo`, `Workplane.move`, `Workplane.placeSketch` | different abstraction | Explicit Profile/Sketch values and orthogonal Frame; caller owns source copies and frames. No mutable Workplane/Sketch chain or stack context compatibility. |
68
+ | sketch-state: `Sketch.tag`, `Sketch.select`, `Sketch.reset`, `Sketch.delete`, `Sketch.push` | different abstraction | Named sketch points/circles/constraints and explicit source edits. Not tag-based selection of arbitrary sketch faces or mutable selection state. |
69
+ | sketch-topology: `Sketch.faces`, `Sketch.edges`, `Sketch.vertices`, `Sketch.face`, `Sketch.edge`, `Sketch.assemble` | unsupported | No general sketch topology editing API. Solid snapshot queries do not supply an equivalent 2D face/edge editor. |
70
+ | basic-profiles: `Sketch.rect`, `Sketch.circle`, `Sketch.ellipse`, `Sketch.polygon`, `Workplane.rect`, `Workplane.circle`, `Workplane.ellipse`, `Workplane.polyline` | supported domain | rectangle/circle/ellipse/polygon profiles. Closed profile construction; not every CadQuery mode, construction geometry or stack overload. |
71
+ | profile-recipes: `Sketch.trapezoid`, `Sketch.slot`, `Sketch.regularPolygon`, `Workplane.slot2D` | recipe | Generate polygon or line/arc outline coordinates. Caller must compute the profile; no dedicated constructors or equality claim for every corner case. |
72
+ | lines-arcs: `Sketch.segment`, `Sketch.arc`, `Sketch.close`, `Workplane.lineTo`, `Workplane.threePointArc`, `Workplane.close` | supported domain | Outline line/three-point arc segments, or constrained sketch boundaries. Explicit end/via points and closed profiles; no fluent pending-edge behavior. |
73
+ | relative-lines: `Workplane.line`, `Workplane.vLine`, `Workplane.vLineTo`, `Workplane.hLine`, `Workplane.hLineTo`, `Workplane.polarLine`, `Workplane.polarLineTo`, `Workplane.sagittaArc`, `Workplane.radiusArc`, `Workplane.tangentArcPoint` | recipe | Compute endpoints/via points in the SDK caller and emit outline segments. Geometric branch and tangency decisions are caller responsibilities. |
74
+ | profile-arrays: `Sketch.rarray`, `Sketch.parray`, `Sketch.each`, `Sketch.distribute`, `Workplane.rarray`, `Workplane.polarArray`, `Workplane.each`, `Workplane.eachpoint` | recipe | Caller generates locations/source features; native pattern and shared occurrences cover repeated solids. No callback execution or edge-distribution/stack placement API in the native protocol. |
75
+ | sketch-advanced-edit: `Sketch.hull`, `Sketch.offset`, `Sketch.fillet`, `Sketch.chamfer`, `Sketch.clean`, `Workplane.offset2D` | unsupported | No public general 2D wire/face offset, hull, cleanup or selection-based corner editor. Internal profile offsets used by selected solid operations are not a general sketch API. |
76
+ | general-splines: `Sketch.spline`, `Workplane.spline`, `Workplane.parametricCurve`, `Workplane.parametricSurface`, `Workplane.ellipseArc`, `Workplane.twistExtrude`, `Workplane.text` | unsupported | No equivalent arbitrary interpolating spline, function-sampling curve/surface, elliptical arc, twist-extrusion or text API. Bezier path/control surfaces are different bounded capabilities. |
77
+ | sketch-constraints: `Sketch.constrain`, `Sketch.solve` | partial | Named geometric constraints, local numerical solver, residual and DOF diagnostics. Finite variable/equation budgets and selected point/line/circle constraints; no blanket nonlinear solver equivalence. |
78
+ | sketch-mirror-wire: `Workplane.mirrorX`, `Workplane.mirrorY`, `Workplane.wire` | recipe | Reflect profile coordinates and emit a closed outline/polygon. No pending-wire graph or automatic multi-wire assembly semantics. |
79
+ | basic-solids: `Workplane.box`, `Workplane.sphere`, `Workplane.cylinder` | supported domain | Native box/sphere/cylinder. Explicit placement and mm units; sphere angular truncation/stack overloads are not claimed. |
80
+ | wedge: `Workplane.wedge` | recipe | Extrude an explicit polygon or use a specified loft. No direct wedge signature. |
81
+ | booleans: `Workplane.cut`, `Workplane.union`, `Workplane.intersect` | supported domain | Native exact cut/union/intersect on feature IDs. Different kernel; no OCCT glue/tolerance compatibility or universal success-rate guarantee. |
82
+ | stack-combine: `Workplane.combine` | recipe | Explicit union graph, or separate named assembly instances. Fusion and assembly are distinct operations; no implicit stack combination. |
83
+ | extrusions: `Workplane.extrude`, `Workplane.cutBlind`, `Workplane.cutThruAll` | partial | extrude/draft_extrude/cutout with explicit frame and extent. Up-to-selected-face and automatic through-all semantics require explicit extent derivation; taper/offset restrictions differ. |
84
+ | holes: `Workplane.hole`, `Workplane.cboreHole` | partial | holes/face_holes/hole_grid/face_hole_grid and counterbore options. Explicit radius, depth and frame; not every Workplane context/automatic depth overload. |
85
+ | countersink: `Workplane.cskHole` | recipe | Subtract explicit cone/cylinder cutters. No dedicated countersink operation or complete countersink recognition contract. |
86
+ | loft-sweep: `Workplane.loft`, `Workplane.sweep`, `Workplane.revolve` | partial | profile_loft/loft/sweep/curve_sweep/pipe/revolve. Bounded corresponding sections; planar sweep or one line/arc/Bezier path; no general multi-rail/Frenet/twisted sweep parity. |
87
+ | finish-features: `Workplane.shell`, `Workplane.fillet`, `Workplane.chamfer`, `Workplane.split` | partial | Semantic edge selectors, native blends/shells and explicit split tools. Selector families and algorithm success domains differ; unequal-length chamfer and all CadQuery overloads are not established. |
88
+ | transforms: `Workplane.rotate`, `Workplane.translate`, `Workplane.mirror` | supported domain | Explicit rigid placement/rotation/translation/mirror. No stack semantics; mirror may produce a new feature or occurrence as specified. |
89
+ | center-rotation: `Workplane.rotateAboutCenter` | recipe | Compute/select the intended center and pass an explicit rotation origin. Bounding-box center and mass center must not be conflated. |
90
+ | dxf-svg: `Sketch.importDXF`, `Workplane.toSvg`, `Workplane.exportSvg`, `importers.importDXF`, `occ_impl.exporters.dxf.DxfDocument` | unsupported | No public DXF import/export or SVG projection API. PNG/HTML review is not vector drawing interchange. |
91
+ | step-import: `importers.importStep` | partial | Registered STEP assets, inspectStep/attachStep/import_step and native product hierarchy. Rigid placements and supported representations only; mixed units/nonrigid mappings and unsupported entities can be rejected. |
92
+ | export: `exporters.export`, `Assembly.save` | partial | Exact STEP solids/surfaces and assembly trees; STL/GLB/PNG plus feature source/session HTML. No equivalent full CadQuery exporter format matrix; STEP does not export editable native feature history. |
93
+ | stack: `Workplane.all`, `Workplane.size`, `Workplane.vals`, `Workplane.add`, `Workplane.val`, `Workplane.first`, `Workplane.item`, `Workplane.last`, `Workplane.end` | different abstraction | Explicit feature graph, IDs, session accepted source and query result arrays. No Workplane object stack/parent chain compatibility; host array access is not a modeling feature. |
94
+ | solid-topology: `Workplane.vertices`, `Workplane.faces`, `Workplane.edges` | supported domain | Revision-bound typed entities and composable query selections. Observed refs are invalidated by edits; query selectors are not automatically accepted by every modeling operation. |
95
+ | wire-topology: `Workplane.wires` | partial | Ordered face loops and edge uses. Loops on a solid are not standalone arbitrary wires. |
96
+ | body-topology: `Workplane.solids`, `Workplane.shells`, `Workplane.compounds` | unsupported | Definitions/instances expose part results, not these generic topology selections. No public solid/shell/compound entity selector. |
97
+ | spatial-selector: `NearestToPointSelector`, `BoxSelector` | unsupported | No direct general nearest-object or bounding-box selector in query expressions. A modeling Near selector and exported AABBs are not equivalent to these selectors. |
98
+ | direction-selectors: `BaseDirSelector`, `ParallelDirSelector`, `DirectionSelector`, `DirectionNthSelector`, `PerpendicularDirSelector`, `DirectionMinMaxSelector`, `CenterNthSelector` | partial | Planar-normal predicates, typed rank with projection/datum direction and explicit cardinality. Planar normal support does not cover arbitrary curve tangents; ties retained; semantics differ from CadQuery selectors. |
99
+ | metric-selectors: `LengthNthSelector`, `AreaNthSelector`, `TypeSelector` | supported domain | Typed class/range filters and rank by metric. Finite result budgets; tied rank is not silently reduced to one entity. |
100
+ | radius-rank: `RadiusNthSelector` | partial | Radius filters/descriptors are available; nth-radius ordering must be implemented by the caller. No native radius rank property. |
101
+ | logical-selectors: `BinarySelector`, `AndSelector`, `SumSelector`, `SubtractSelector`, `InverseSelector` | supported domain | Typed union/intersection/difference and bounded all/any/not predicates. Set/target scope is explicit; no Python selector object compatibility. |
102
+ | selector-dsl: `StringSyntaxSelector` | different abstraction | JSON selection algebra. CadQuery selector strings are not parsed or accepted. |
103
+ | assembly-tree: `Assembly`, `Assembly.add` | supported domain | Named hierarchical instances, shared definitions, rigid placements and STEP product tree. Different construction API and bounded instance/group counts. |
104
+ | assembly-constraints: `Assembly.constrain`, `Assembly.solve`, `Constraint` | partial | Named attachments/datums and fixed/coincident/concentric/plane/distance/revolute/prismatic mates. Local solver and explicit direction/residual rules; CadQuery Axis/Plane names do not have identical semantics. |
105
+ | appearance: `Color` | partial | Instance colors in Colocad preview/assembly metadata. No OCCT color class or full material/export appearance parity. |
@@ -0,0 +1,53 @@
1
+ # Colocad 与 CadQuery:覆盖和设计对比
2
+
3
+ 核对日期:**2026-11-10**;Colocad **0.1.0-alpha.8**。[English / 完整 API 表](cadquery-comparison.md) · [逐项数据](cadquery-coverage.json) · [路线图](../ROADMAP.zh-CN.md)。
4
+
5
+ **Colocad 已有可用的机械建模、精确查询与几何驱动装配层,但还不能完整替代 CadQuery。** 我们的优势方向是显式参数图、可持久化工具闭环、轻量部署及特定负载性能;CadQuery 的通用几何 API、草图、交换格式和生态覆盖仍更广。两者不是同一套 API,不能直接执行对方的建模程序。
6
+
7
+ ## 统计口径
8
+
9
+ 按用户指定的 [CadQuery API Reference](https://cadquery.readthedocs.io/en/latest/apireference.html) 建立 **150 个不同入口**的清单,固定到官方源码提交 [b3f9afd](https://github.com/CadQuery/cadquery/blob/b3f9afd4f39cbd856d0c46aa30aa37b714b8f6cb/doc/apireference.rst)。JSON 中保存来源摘要、每个入口的映射、实现路径、代表测试和边界。`latest` 文档可能继续变化,也不等于某个已安装版本。
10
+
11
+ | 分类 | 数量 | 解释 |
12
+ | --- | ---: | --- |
13
+ | 有对应原生能力 | 36 | 受支持范围内有类似操作;不代表参数、所有选项或行为完全相同 |
14
+ | 部分支持 | 30 | 有相关能力,但存在实质选项、范围或语义缺口 |
15
+ | 可以组合表达 | 29 | 由调用方计算坐标或组合基础操作;没有通用等价 API |
16
+ | 尚无公开能力 | 29 | 当前公共契约未提供相应功能 |
17
+ | 使用不同抽象 | 26 | 用显式图、会话或 JSON 替代状态链;不能直接互换 |
18
+
19
+ 这些是**源码/契约核对结果,不是 150 项配对测试的通过率**,不能加总成“覆盖率”。一个便利方法与复杂几何算法权重也不相同。该索引之外还有 Shape、底层拓扑、free functions 和插件生态;我们另外列出这些边界。
20
+
21
+ ## 工程能力对照
22
+
23
+ | 能力 | Colocad 当前实现 | 相对 CadQuery 的边界 |
24
+ | --- | --- | --- |
25
+ | 参数和工作平面 | 命名参数表达式、显式正交 frame、特征依赖 | 不兼容 Workplane 的栈、父链和隐式上下文 |
26
+ | 基础截面 | 矩形、圆、椭圆、多边形、线/圆弧闭合轮廓 | 一般草图拓扑编辑、offset/hull/二维圆角等未公开 |
27
+ | 草图约束 | 点/线/圆约束、局部求解、残差与自由度 | 有变量/方程预算;不声称全局唯一或所有约束对齐 |
28
+ | 拉伸、旋转、布尔 | 对应原生操作和确定性特征 ID | 所有选项、鲁棒性和内核结果不等同于 OCCT |
29
+ | 孔和阵列 | 普通孔、面孔、规则孔阵列、沉孔选项 | 沉头可组合圆锥切除;没有完整沉头 API/识别保证 |
30
+ | 放样、扫掠、薄壁、圆角 | 已有受限原生操作 | 通用多导轨、扭转、任意曲面和复杂失败率仍需扩展 |
31
+ | 曲面 | Bezier、受限网络、连接、编辑、缝合、加厚 | 不等于通用 Shape/free-function 曲面能力或 Class-A 认证 |
32
+ | 通用选择 | 面/边/点/环、组合、邻接、排序、严格数量检查 | 无 wire/solid/shell/compound 等价通用选择;无最近点/box selector;半径可过滤但不能原生 nth 排序 |
33
+ | 选择驱动特征 | 建模侧支持一组命名/几何选择器 | 查询表达式比建模选择器丰富,不能直接给任意 fillet/shell 使用 |
34
+ | 基准与装配 | 重算基准、命名附件、配合、接口规则 | 求解器语义有差异,不能照名称映射 CadQuery Axis/Plane |
35
+ | 孔组与接口识别 | 解析圆柱孔、按平面分组、平面安装接口 | 属于特定工程层,复杂孔可能 partial;不是任意 STEP 自动装配 |
36
+ | 引用和改参 | 同一快照重开保持引用;改参重新解析语义规则 | 不是永远不变的 face ID;拓扑歧义必须显式处理 |
37
+ | 外部 STEP | 来源登记、刚体层级导入、查询和兼容替换 | 混合单位、非刚体映射和部分表示受限;不是任意 CAD 文件兼容 |
38
+ | 导出 | 精确 STEP、STL、GLB、PNG、参数源、会话 HTML | DXF/SVG/XCAF/XBF/3MF 等矩阵未对齐;STEP 不携带原生参数树 |
39
+ | Agent 和人类审阅 | SDK + CLI + tools + skill;CLI 启动持久化查看与导出 | 工具闭环是产品设计差异,不能据此推断几何全面领先 |
40
+
41
+ CadQuery 同样强调相对定位和设计意图,并提供无隐式状态的 free-function API,不能把它简化成“只有 Python 链式调用”。官方依据:[设计原则](https://cadquery.readthedocs.io/en/latest/designprinciples.html)、[装配约束](https://cadquery.readthedocs.io/en/latest/assy.html#constraints)、[free functions](https://cadquery.readthedocs.io/en/latest/free-func.html)、[导入导出](https://cadquery.readthedocs.io/en/latest/importexport.html)。更细的约束语义分析见[早期评审](../specs/reviews/0004-cadquery-2026-11-09.md)。
42
+
43
+ ## 架构和部署
44
+
45
+ Colocad 的运行路径是 agent/harness → TS SDK 或 CLI → 本地 Rust executor → 固定版本 SolidCore。它们在同一个沙箱内运行。npm 包携带 macOS arm64、Linux arm64/x64 可执行文件,建模安装不需要 Python/Rust 工具链;独立 OCCT 回读属于验证环境。SolidCore 与 USD BRep 的上游关联不意味着 Colocad 使用 NVIDIA 原库、实现完全相同或有相同验证水平。
46
+
47
+ CadQuery 使用 Python/OCCT 生态;Colocad 使用自己的 JSON/TypeScript 契约。Colocad 的参数源、session、快照和展示文件分别承担可编辑性、审计、精确观察和人类审阅职责。原生商业 CAD 特征树是另外的能力,[通用可编辑 SOLIDWORKS 当前仍有缺口](native-solidworks.md)。
48
+
49
+ ## 证据与结论边界
50
+
51
+ [G1–G3](../specs/experiments/0005/README.md) 验收的是已声明范围、冻结的 24 个案例和两条真实 Pi 任务;不是所有 CadQuery API,也不是陌生图纸重建成功率。alpha.7 后续发现的孔阵列查询缺陷保留了失败证据;[alpha.8 回归记录](evidence/release-alpha.8.json)专门验证修复、六个面方向、全局孔阵列、改参/旧引用/重开和独立几何回读。
52
+
53
+ 本报告**没有新增 CadQuery 速度或内存实验**。历史 build123d 对照只适用于当时相同几何、精度、硬件与计时范围,不可外推成全面领先。后续按[路线图](../ROADMAP.zh-CN.md)分别做确定性执行、编辑装配、真实 agent 读图三条 benchmark,并先检查质量,再比较速度、内存和推理成本。