@coloopx/colocad 0.1.0-alpha.6 → 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.
- package/CHANGELOG.md +64 -0
- package/README.md +14 -3
- package/README.zh-CN.md +13 -3
- package/ROADMAP.md +125 -0
- package/ROADMAP.zh-CN.md +91 -0
- package/bin/colocad.mjs +17 -9
- package/docs/README.md +13 -2
- package/docs/README.zh-CN.md +12 -3
- package/docs/agent-modeling-handbook.md +12 -4
- package/docs/agent-modeling-handbook.zh-CN.md +21 -4
- package/docs/api.md +9 -6
- package/docs/best-practices.md +80 -3
- package/docs/best-practices.zh-CN.md +63 -0
- package/docs/cadquery-comparison.md +105 -0
- package/docs/cadquery-comparison.zh-CN.md +53 -0
- package/docs/cadquery-coverage.json +762 -0
- package/docs/engineering-queries.md +124 -0
- package/docs/engineering-queries.zh-CN.md +76 -0
- package/docs/getting-started.md +1 -1
- package/docs/integrations/claude-code.md +1 -1
- package/docs/integrations/codex.md +1 -1
- package/docs/integrations/overview.md +3 -1
- package/docs/integrations/pi.md +17 -4
- package/docs/integrations/verification.md +7 -1
- package/docs/troubleshooting.md +13 -1
- package/examples/integrations/README.md +11 -2
- package/examples/integrations/compact-tools.mjs +1 -1
- package/kernel/dist/client.d.ts +5 -2
- package/kernel/dist/client.js +35 -7
- package/kernel/dist/generated.d.ts +297 -4
- package/kernel/dist/process.d.ts +1 -1
- package/kernel/dist/process.js +3 -3
- package/kernel/dist/query-generated.d.ts +181 -0
- package/kernel/dist/query-generated.js +1 -0
- package/kernel/dist/tools.d.ts +35 -0
- package/kernel/dist/tools.js +11 -2
- package/kernel/dist/types.d.ts +9 -0
- package/kernel/native/darwin-arm64/agent-cad +2 -2
- package/kernel/native/darwin-arm64/manifest.json +2 -2
- package/kernel/native/linux-arm64/agent-cad +2 -2
- package/kernel/native/linux-arm64/manifest.json +2 -2
- package/kernel/native/linux-x64/agent-cad +2 -2
- package/kernel/native/linux-x64/manifest.json +2 -2
- package/kernel/release.json +4 -4
- package/kernel/schemas/model.schema.json +1752 -135
- package/kernel/schemas/query.schema.json +1150 -0
- package/package.json +8 -2
- package/skills/colocad/SKILL.md +1 -0
- package/skills/colocad/references/modeling-loop.md +15 -1
- package/skills/colocad/references/prompt-patterns.md +27 -1
- package/skills/colocad/references/quick-build.md +2 -0
- package/skills/colocad/references/tool-contracts.md +14 -2
- package/skills/colocad/references/tuning.md +5 -1
- package/src/build.mjs +3 -2
- package/src/index.d.mts +2 -1
- package/src/session.d.mts +5 -3
- package/src/session.mjs +26 -10
- package/viewer/dist/index.js +179 -179
- package/viewer/dist/standalone.js +179 -179
- package/viewer/index.d.ts +2 -1
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Agent CAD 完整工作指南:资料、工具、建模闭环与调优
|
|
2
2
|
|
|
3
|
-
本指南对应 colocad alpha.
|
|
3
|
+
本指南对应 colocad alpha.7 的 skill 和可运行示例。目标是把指定产品及其工程依据变成可编辑源、精确几何、可追溯检查和可供人类查看的过程。以下是基于仓库实作和公开资料整理的默认方法,不是已证明适用于所有模型/产品的最优提示词。
|
|
4
4
|
|
|
5
5
|
[English overview](agent-modeling-handbook.md) · [研究依据与适用边界](agent-modeling-research.md) · [随包 skill](../skills/colocad/SKILL.md) · [提示词模板](../skills/colocad/references/prompt-patterns.md) · [真实 KK60 产品](../examples/hiwin-kk60/README.md)
|
|
6
6
|
|
|
@@ -91,16 +91,17 @@ modeling.mp4 可选;CLI 导出的实际阶段回放
|
|
|
91
91
|
| `cad_build` | 一个有意义的特征/接口阶段 | `ok`、几何、失败特征、时间、产物及降级 |
|
|
92
92
|
| `cad_preview` | 观察新的几何或换相关视角 | 实际图像;是否复用网格、源几何目录 |
|
|
93
93
|
| `cad_edit` | 修改已有命名参数 | 新版本尺寸、依赖是否跟随、接受的源 |
|
|
94
|
+
| `cad_query` | 对接受版本测量/选择精确几何与安装接口 | `query_revision_id`、目标/坐标系、实际测量、coverage、歧义与来源引用 |
|
|
94
95
|
| `cad_solve_sketch` | 确实需要草图约束时 | 局部 DOF、约束残差与冲突 |
|
|
95
96
|
| `cad_inspect_step` | 需要检查/复用已登记 STEP 时 | 产品树、共享定义和变换、导入限制 |
|
|
96
97
|
|
|
97
|
-
|
|
98
|
+
默认可先注册前五项;测量与装配工作加入 capability-gated `cad_query`,按任务启用草图求解和 STEP 检查。`CadClient.inspect` 读取保存的报告,`CadClient.query` 才是精确几何查询入口;当前工具集没有自动图纸尺寸识别工具。材料阅读使用现有 harness 的文件/图像工具,重要交付仍用独立几何验证程序回读。
|
|
98
99
|
|
|
99
100
|
直接 `createCadTools(client)` 的 `cad_edit` 参数是 `{model, parameters}`;`createSessionTools(session)` 的参数是 `{parameters}`,由会话读取最后成功的源。接入时保留这个区别,避免失败后从错误或过时的模型开始改参。
|
|
100
101
|
|
|
101
102
|
### 3.1 工具返回摘要,不丢失证据
|
|
102
103
|
|
|
103
|
-
模型通常需要:错误码/feature ID
|
|
104
|
+
模型通常需要:错误码/feature 或 query ID、`query_revision_id`、产物路径、实体数、相关测量、coverage/歧义、时间、缓存命中和全部降级项。成功调用中的 partial 不能变成完整工程结论。完整 feature trace、模型和网格保存在文件里,必要时按引用读取。不要每轮把 STEP 文本、大网格和全部历史图片塞回上下文。
|
|
104
105
|
|
|
105
106
|
[compact-tools.mjs](../examples/integrations/compact-tools.mjs) 是实际可运行的无传输层适配器:保持工具 schema/执行语义,压缩成功回执,保留失败/降级与完整回执路径。宿主负责把 `ok:false` 映射为其工具错误格式,并按需要附上 PNG。它是示例适配器,不是额外的 CAD 后台服务。
|
|
106
107
|
|
|
@@ -144,6 +145,16 @@ node node_modules/@coloopx/colocad/examples/integrations/guided-workflow.mjs ./g
|
|
|
144
145
|
|
|
145
146
|
KK60 的真实螺旋槽让总装触发内部 STEP 实体数限制,最终修复的是内部序列化预算,同时维持外部导入限制;没有减少 56 圈螺纹来绕过问题。四视图镜头裁切则通过正交取景和包络测试修复,没有缩短精确模型。
|
|
146
147
|
|
|
148
|
+
### 4.3 精确查询与几何驱动装配(alpha.7)
|
|
149
|
+
|
|
150
|
+
构建时按需启用 `queryable`;声明 `Model.datums` 或 `Model.interfaces` 时自动需要精确快照。保存当前接受版本、工件路径和查询目标。定义局部测量用 `definition_id`,实例测量用 `instance_path` 与装配坐标,容差明确写入请求。
|
|
151
|
+
|
|
152
|
+
先选安装平面,再检查它的孔/孔组;只看法向可能选中同向盲孔底面,位置有关时用命名基准与 `planar_coplanar_with`。检查数量、额外孔、coverage 和对称歧义。将可重算的选择/推导规则放入命名基准或接口声明,再让附件驱动配合。快照 ref 是当前版本的观察,不能当永久面 ID。
|
|
153
|
+
|
|
154
|
+
装配后运行完整孔对应和相关零件对的必需检查。边界距离是无符号量,包含关系也可能有正距离,所以净空判断还要检查关系和重叠。改参或换 STEP 后取得新 `query_revision_id`,重算规则并复验;缺失、歧义、不兼容保留为失败,不靠手工换面编号通过。
|
|
155
|
+
|
|
156
|
+
[最佳实践](best-practices.zh-CN.md)提供查询→改参→拒绝旧引用→重查→CLI 审阅的可执行例子。[外部安装接口例子](../examples/engineering-interfaces/README.md)使用同一规则处理三种兼容来源和两种不兼容来源,并有独立回读。识别范围、曲面接触和离散姿态的边界见[查询指南](engineering-queries.zh-CN.md)。
|
|
157
|
+
|
|
147
158
|
## 5. 提示词和 skill 怎么组织
|
|
148
159
|
|
|
149
160
|
`SKILL.md` 保留能力范围、入口选择和关键判断;材料处理、完整产品循环、工具契约、提示词、调优、可视化分别在按需读取的 references 中。基础形状和产品 brief 放 assets,确定性执行放 scripts/examples。不要把整份工程手册和所有例外都常驻系统提示。这与 [Anthropic 的 skill 编写建议](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)关于简洁、按需披露和按任务脆弱程度约束行为的原则一致。
|
|
@@ -179,6 +190,8 @@ KK60 的真实螺旋槽让总装触发内部 STEP 实体数限制,最终修复
|
|
|
179
190
|
|
|
180
191
|
本仓库的实证是:KK60 16 个阶段独立 STEP 回读、64 个材料探针、三个位置的特定导轨/滑块检查,以及工具/查看器/CLI 集成回归。未公开回珠通道、全部零件对干涉、载荷/寿命和制造公差仍不在通过项中。
|
|
181
192
|
|
|
193
|
+
后续 [G1–G3 验收](../specs/experiments/0005/README.md)增加冻结的 24 个案例、语义引用/替换/恢复序列与两条真实 Pi 推理任务;[alpha.7 安装包验收](evidence/release-alpha.7.json)进一步验证三平台实际包。真实产品任务是在已接受的来源模型上改参/查询,不是从陌生图像自动重建整机,也不是 skill 改动的对照成功率实验。
|
|
194
|
+
|
|
182
195
|
## 7. 调优:对准测量到的瓶颈
|
|
183
196
|
|
|
184
197
|
### 7.1 理解与建模质量
|
|
@@ -194,12 +207,16 @@ KK60 的真实螺旋槽让总装触发内部 STEP 实体数限制,最终修复
|
|
|
194
207
|
|
|
195
208
|
分开计时:资料读取/推理、进程启动、几何、校验、STEP、三角化、视图渲染、视频编码。先看 per-feature/native timings,再决定优化算法、共享定义、参数重算、缓存或显示精度。
|
|
196
209
|
|
|
210
|
+
查询还应单列快照创建、加载和操作耗时。对已接受几何只做测量时,不重建或重新导出 STEP;先缩小目标、选择范围和结果页,再考虑增大预算。
|
|
211
|
+
|
|
197
212
|
同一任务顺序复用 client/session。重复零件复用定义;只换镜头时复用已校验网格。预览可选择适合观察的精度,但比较时要固定参数。影片编码另外需要浏览器与 FFmpeg,不包含在纯几何运行的资源结论中。
|
|
198
213
|
|
|
199
214
|
与 build123d 比较时固定输入几何、实例、精度、交付工件、环境和冷/热启动模式;先验证两边几何等价。报告重复次数、分布、失败和测量范围。内存明确 RSS/进程和/cgroup、采样频率、瞬时值还是截至当前峰值。保留原始采样;用峰值曲线展示时不能称为瞬时内存。
|
|
200
215
|
|
|
201
216
|
本次 KK60 单次 Linux arm64、1 vCPU/512 MiB、禁网、含预览的原生总耗时为 24.192 秒;未测该次内存峰值,也未做同模型 build123d 对照。这个结果不能推导整个 resident agent/harness 或 Chromium 也只需要 512 MiB。[证据](../showcase/hiwin-kk60/evidence.json)。
|
|
202
217
|
|
|
218
|
+
后续 G3 单独记录了包含驻留 Pi/harness 的指定负载;alpha.7 安装包检查还包含 npm 安装与缓存页。各自按对应记录解释,不能混合成同一内存指标。G4 benchmark/回溯优化尚未启动。
|
|
219
|
+
|
|
203
220
|
### 7.3 如何证明 skill/提示词真的更好
|
|
204
221
|
|
|
205
222
|
固定资料包、目标产品、模型/provider 版本、工具、预算和随机设置,对比旧 skill 与单项改动。覆盖明确尺寸件、需要剖视解释的零件、编辑后仍须配合的装配和有歧义的材料;留出未参与调优的任务。测关键尺寸/特征、编辑保持、接口检查、无依据结论、修改次数、推理成本和端到端时间。
|
|
@@ -209,7 +226,7 @@ KK60 的真实螺旋槽让总装触发内部 STEP 实体数限制,最终修复
|
|
|
209
226
|
## 8. 运行、审阅与交付
|
|
210
227
|
|
|
211
228
|
```sh
|
|
212
|
-
npm install @coloopx/colocad@0.1.0-alpha.
|
|
229
|
+
npm install @coloopx/colocad@0.1.0-alpha.7
|
|
213
230
|
node node_modules/@coloopx/colocad/examples/hiwin-kk60/run.mjs ./actuator
|
|
214
231
|
npx colocad view ./actuator/session
|
|
215
232
|
npx colocad replay ./actuator/session ./actuator.html
|
package/docs/api.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# SDK, CLI and tool reference
|
|
2
2
|
|
|
3
|
-
Targets `@coloopx/colocad@0.1.0-alpha.
|
|
3
|
+
Targets `@coloopx/colocad@0.1.0-alpha.7`. The [public declarations](../src/index.d.mts) and [kernel declarations](../kernel/src/types.ts) are the complete type contracts.
|
|
4
4
|
|
|
5
5
|
## Feature-tree SDK and CLI
|
|
6
6
|
|
|
@@ -20,7 +20,7 @@ colocad build TREE.json NEW_DIRECTORY [--preview]
|
|
|
20
20
|
colocad solidworks NATIVE-JOB.json NEW_FILE.SLDPRT
|
|
21
21
|
```
|
|
22
22
|
|
|
23
|
-
CLI success prints JSON to stdout. Failure prints an error to stderr and exits nonzero. Feature-tree CLI input is limited to 2 MiB. The third command is the [experimental Windows author](
|
|
23
|
+
CLI success prints JSON to stdout. Failure prints an error to stderr and exits nonzero. Feature-tree CLI input is limited to 2 MiB. The third command is the [experimental Windows author](native-solidworks.md).
|
|
24
24
|
|
|
25
25
|
## Kernel SDK
|
|
26
26
|
|
|
@@ -39,7 +39,9 @@ The host chooses `outputRoot`, a local directory for generated revisions, and op
|
|
|
39
39
|
| `capabilities()` | Native version, supported operations, budgets and declared limitations |
|
|
40
40
|
| `schema()` | Complete kernel model JSON Schema |
|
|
41
41
|
| `validate(model)` | Cheap input/dependency/budget preflight; no geometric validity guarantee |
|
|
42
|
-
| `build(model,
|
|
42
|
+
| `build(model, optionsOrRevision?)` | Build/check exact geometry; options include `queryable` and `previousRevision`; a legacy revision string remains supported |
|
|
43
|
+
| `querySchema()` | Exact-query JSON Schema from the installed native |
|
|
44
|
+
| `query(artifactDirectory, request)` | Read an exact snapshot using its `query_revision_id`, within host-configured `queryRoots` |
|
|
43
45
|
| `edit(model, parameters)` | Change existing numeric parameters, then build; input remains unchanged |
|
|
44
46
|
| `preview(model, options?)` | Build or reuse a matching display mesh and render it |
|
|
45
47
|
| `observeArtifact(directory, options?)` | Render from a trusted saved mesh with integrity checks |
|
|
@@ -59,7 +61,7 @@ Build receipts include `artifact_directory`, `geometry`, `validation`, feature r
|
|
|
59
61
|
|
|
60
62
|
Preview options include `view: "iso" | "top" | "bottom" | "front" | "back" | "left" | "right"`, image size, `chord_mm` and section settings. Use the schema for exact fields and limits. A different camera can reuse geometry; changing mesh precision or geometry can require new work.
|
|
61
63
|
|
|
62
|
-
The kernel SDK limits serialized input to 32 MiB. Query capabilities for native feature, assembly and mesh budgets. The SDK has no in-flight `AbortSignal` contract in alpha.
|
|
64
|
+
The kernel SDK limits serialized input to 32 MiB. Query capabilities for native feature, assembly and mesh budgets. The SDK has no in-flight `AbortSignal` contract in alpha.7: the Pi example checks cancellation before dispatch, while an already-running native call is bounded by `wallMs`.
|
|
63
65
|
|
|
64
66
|
## Agent tools
|
|
65
67
|
|
|
@@ -69,15 +71,16 @@ The kernel SDK limits serialized input to 32 MiB. Query capabilities for native
|
|
|
69
71
|
| --- | --- |
|
|
70
72
|
| `cad_capabilities` | `{}` |
|
|
71
73
|
| `cad_validate` | `{ model }` |
|
|
72
|
-
| `cad_build` | `{ model }` |
|
|
74
|
+
| `cad_build` | `{ model, options?: { queryable?: boolean } }` |
|
|
73
75
|
| `cad_preview` | `{ model, options? }` |
|
|
74
76
|
| `cad_edit` | `{ model, parameters }` |
|
|
75
77
|
| `cad_solve_sketch` | `{ sketch, parameters? }` |
|
|
76
78
|
| `cad_inspect_step` | `{ model, asset }` |
|
|
79
|
+
| `cad_query` | `{ artifact_directory, request }`; session-bound form takes `{ request }` against the accepted artifact |
|
|
77
80
|
|
|
78
81
|
Preserve the complete `inputSchema`, including root `$defs`. Do not wrap it without rewriting `$ref` locations. These definitions are transport-neutral; the package does not launch an MCP server. If a provider rejects the union-heavy schema, use the skill with shell tools or build a provider-specific schema adapter and test its validation behavior.
|
|
79
82
|
|
|
80
|
-
The Pi example exposes the first five tools
|
|
83
|
+
The Pi example exposes the first five tools plus capability-gated `cad_query`. It converts failed receipts into failed tool results and includes PNG bytes in image content when a preview is at most 4 MiB. Build/edit feedback retains the query revision. See the [query guide](engineering-queries.md) for selection, datums, holes/groups, interfaces and supported geometric relationships.
|
|
81
84
|
|
|
82
85
|
For STEP imports, use `attachStep(model, assetId, stepText)` from `@coloopx/colocad/kernel`. The host registers text under an opaque ID; the model need not choose arbitrary filesystem paths. The returned model is a copy. [Integration policy and lifecycle](integrations/overview.md).
|
|
83
86
|
|
package/docs/best-practices.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Modeling and integration best practices
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Applies to the supported Colocad alpha.8 APIs. [中文](best-practices.zh-CN.md) · [Complete agent handbook](agent-modeling-handbook.md) · [Query contract and limits](engineering-queries.md).
|
|
4
4
|
|
|
5
5
|
|
|
6
6
|
## Start from the structure that controls the part
|
|
@@ -19,6 +19,8 @@ Use stable named parameters for interface dimensions. Preserve feature IDs acros
|
|
|
19
19
|
| Parameter dimension | `edit()` against the latest accepted source; save the new source |
|
|
20
20
|
| Repeated identical components | Define the part once; place named assembly occurrences |
|
|
21
21
|
| Repeated face bores | Use a hole-grid/pattern operation where it represents the design |
|
|
22
|
+
| Measure an accepted part or installation interface | `query()` its exact snapshot with the current revision, explicit target, space and tolerance |
|
|
23
|
+
| Replace a compatible imported component | Re-evaluate semantic datum/interface declarations, solve mates and rerun required fit/clearance checks |
|
|
22
24
|
| Coarse clearance exploration | Use an explicit envelope/simplification, then check the final exact model |
|
|
23
25
|
| New exact geometry | Build a new revision and inspect the affected region |
|
|
24
26
|
|
|
@@ -26,12 +28,85 @@ Do not rebuild exact B-rep merely to orbit the view. Conversely, do not use a di
|
|
|
26
28
|
|
|
27
29
|
## Give the agent a small, useful tool surface
|
|
28
30
|
|
|
29
|
-
For routine parts, capabilities, validate, build, preview and edit are enough to start. Add STEP inspection
|
|
31
|
+
For routine parts, capabilities, validate, build, preview and edit are enough to start. Add capability-gated `cad_query` for measured geometry and assembly work; add STEP inspection or sketch solving when needed. Supply the skill for workflow guidance and assets; keep the full schema accessible instead of pasting it into every system prompt.
|
|
30
32
|
|
|
31
|
-
Keep model-facing results concise: success/failure,
|
|
33
|
+
Keep model-facing results concise: success/failure, failing feature/query ID, `query_revision_id`, relevant geometry, coverage/ambiguity, validation, paths and requested images. Store full receipts and timings on disk. A query result may be partial even when the call succeeds; retain its coverage and diagnostics. Never send a full STEP, mesh JSON or base64 PNG as ordinary text when the harness supports attachments.
|
|
32
34
|
|
|
33
35
|
Use a bounded correction loop: locate the failed feature, inspect its inputs and dependencies, change the cause, rebuild, then recheck earlier requirements. Preserve the previous accepted revision until the new one passes. Do not silently drop a failing cut to make a model appear complete.
|
|
34
36
|
|
|
37
|
+
## Query, declare intent, assemble, then challenge the edit
|
|
38
|
+
|
|
39
|
+
1. **Build once with exact query artifacts.** Use `{queryable:true}` when observations are needed. Declaring `Model.datums` or `Model.interfaces` enables them automatically. Record `artifact_directory` and `query_revision_id`; use `definition_id` for a part's local coordinates or `instance_path` for an assembly occurrence.
|
|
40
|
+
2. **Narrow by engineering intent.** Select the mounting plane, then its openings and hole group. A normal test alone can also match a blind-hole bottom; use a named plane with `planar_coplanar_with` when position matters. Assert cardinality and inspect partial coverage, extra holes and competing candidates.
|
|
41
|
+
3. **Persist a recipe.** Put supported geometric selection recipes in `Model.datums`/`Model.interfaces`. Refs from a query are observations of that revision; do not put them into a persistent recipe or use incidental face indices. Symmetric groups need an explicit or measured orientation datum for an oriented mate.
|
|
42
|
+
4. **Check the solved assembly.** Use named attachments, all-hole `interface_compatibility`, and required `geometric_relationship` checks for the relevant pairs. A positive boundary distance alone does not prove clearance: a contained part can have one. Require the appropriate relationship, overlap and clearance results.
|
|
43
|
+
5. **Edit or replace, then re-query.** Rebuild from accepted source, obtain the new revision and rerun the recipe/checks. Keep missing/ambiguous/incompatible outcomes as failed attempts; do not patch in new face numbers to force success. Use a compatible and an incompatible replacement to challenge the same assembly recipe.
|
|
44
|
+
6. **Deliver the evidence.** Retain source, session, exact STEP, numerical checks and unknowns. Export human review through `colocad view/replay/render`. Discrete checked poses do not certify continuous travel, and a display explosion is not a motion check.
|
|
45
|
+
|
|
46
|
+
### Run the edit/query loop against the installed package
|
|
47
|
+
|
|
48
|
+
Install `@coloopx/colocad@0.1.0-alpha.8` in a new project. Save this as `query-workflow.mjs`; keep `query-session` and `query-review.html` unused before the first run:
|
|
49
|
+
|
|
50
|
+
**Version note:** alpha.8 fixes grid exact snapshot creation. The example now uses `face_hole_grid` directly. Upgrade SDK and native together; preview precision was not the cause in alpha.7. [Original failure](evidence/alpha.7-query-guidance.json) / [Repair regression](evidence/release-alpha.8.json).
|
|
51
|
+
|
|
52
|
+
```js
|
|
53
|
+
import assert from 'node:assert/strict';
|
|
54
|
+
import {ModelingSession} from '@coloopx/colocad/session';
|
|
55
|
+
|
|
56
|
+
const model = {
|
|
57
|
+
version:1, units:'mm', parameters:{holeDiameter:6},
|
|
58
|
+
features:[
|
|
59
|
+
{id:'plate', op:'box', origin:[0,0,0], size:[80,50,6]},
|
|
60
|
+
{id:'mounts', op:'face_hole_grid', input:'plate', face:'pos_z',
|
|
61
|
+
center:[40,25], count:[2,2], spacing:[50,30],
|
|
62
|
+
radius:{op:'div', a:{param:'holeDiameter'}, b:2}, depth:6}
|
|
63
|
+
],
|
|
64
|
+
output:'mounts', preview:{width:320, height:240, chord_mm:1}
|
|
65
|
+
};
|
|
66
|
+
const session = await ModelingSession.create('./query-session');
|
|
67
|
+
const checked = r => { if (!r.ok) throw Error(JSON.stringify(r.error)); return r.data; };
|
|
68
|
+
const request = revision => ({
|
|
69
|
+
schema:'colocad.query/1', query_revision_id:revision,
|
|
70
|
+
target:{definition_id:model.output}, space:'definition',
|
|
71
|
+
tolerance:{linear_mm:1e-5, angular_rad:1e-7},
|
|
72
|
+
queries:[{id:'bores', op:'holes', where:{termination:'through'}}]
|
|
73
|
+
});
|
|
74
|
+
const observe = async (revision, diameter) => {
|
|
75
|
+
const r = checked(await session.query(request(revision)));
|
|
76
|
+
const result = r.results[0];
|
|
77
|
+
assert.equal(result.status, 'complete');
|
|
78
|
+
assert.equal(result.items.length, 4);
|
|
79
|
+
for (const hole of result.items) {
|
|
80
|
+
assert.ok(hole.segments.length > 0);
|
|
81
|
+
for (const segment of hole.segments)
|
|
82
|
+
assert.ok(Math.abs(segment.diameter_mm - diameter) < 1e-5);
|
|
83
|
+
}
|
|
84
|
+
assert.equal(r.execution.geometry_build_calls, 0);
|
|
85
|
+
return result.items.map(h => h.axis.point_mm.slice(0,2))
|
|
86
|
+
.sort((a,b) => a[0]-b[0] || a[1]-b[1]);
|
|
87
|
+
};
|
|
88
|
+
const initial = checked(await session.build(model, {queryable:true}));
|
|
89
|
+
const centers = await observe(initial.query_revision_id, 6);
|
|
90
|
+
const edited = checked(await session.edit({holeDiameter:8}));
|
|
91
|
+
const stale = await session.query(request(initial.query_revision_id));
|
|
92
|
+
assert.equal(stale.ok, false);
|
|
93
|
+
assert.equal(stale.error.code, 'QUERY_REVISION_MISMATCH');
|
|
94
|
+
const newCenters = await observe(edited.query_revision_id, 8);
|
|
95
|
+
centers.forEach((p,i) => p.forEach((x,j) =>
|
|
96
|
+
assert.ok(Math.abs(x-newCenters[i][j]) < 1e-5)));
|
|
97
|
+
assert.ok(Math.abs(edited.geometry.volume_mm3 - (80*50-4*Math.PI*4**2)*6) < 1e-5);
|
|
98
|
+
console.log({session:session.root, revision:edited.query_revision_id,
|
|
99
|
+
holes:4, diameter_mm:8, staleRefRejected:true});
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
```sh
|
|
103
|
+
node query-workflow.mjs
|
|
104
|
+
./node_modules/.bin/colocad replay ./query-session ./query-review.html
|
|
105
|
+
./node_modules/.bin/colocad view ./query-session
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
The old-revision error is intentional and remains in history. This verifies one dimensioned plate and edit; it is not a drawing-reconstruction study. For the complete foreign STEP → datums/interfaces → mates → exact checks → replacement workflow, use the [engineering-interface example](../examples/engineering-interfaces/README.md), including its three compatible and two incompatible sources and independent OCCT verifier.
|
|
109
|
+
|
|
35
110
|
## Acceptance beyond a screenshot
|
|
36
111
|
|
|
37
112
|
Check solid count, envelope, material volume and critical internal regions. For assemblies, check named occurrences, placements, repeated-part consistency and required clearances. A visually plausible rendering can hide fused fingers, solid-filled holes or inverted placements.
|
|
@@ -43,3 +118,5 @@ Keep a reproducible record: input model, relevant source views and assumptions,
|
|
|
43
118
|
Separate fresh-process time to STEP, resident-session edits, preview-only views and full agent turnaround. Record whether startup/import, STEP export, independent validation and inference are included. Measure memory for the sandbox/process tree, not just the parent Node process. Compare matched accepted geometry, not only successful exit codes.
|
|
44
119
|
|
|
45
120
|
The [100-second hand study](../showcase/tendon-hand/window/README.md) compares a fixed revision queue and explicitly excludes live-model inference. Its throughput and memory gains are workload-specific. A sequential primitive benchmark does not establish that all booleans or all complex assemblies are faster.
|
|
121
|
+
|
|
122
|
+
For query workloads, record snapshot creation/load and query time separately from build/STEP/preview time. Bound result pages and query scope before raising budgets. Cgroup peak includes descendants and charged file/cache pages; the [alpha.7 installation checks](evidence/release-alpha.7.json) include npm installation, while the [G3 runs](../specs/experiments/0005/README.md) measure different CAD/agent workloads. Keep their accounting separate. G4's benchmark/retrospective optimization campaign has not started.
|
|
@@ -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,并先检查质量,再比较速度、内存和推理成本。
|