@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
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
Notable user-facing changes are recorded here. Colocad remains alpha software; supported geometry and measured workloads define each release's scope.
|
|
4
|
+
|
|
5
|
+
## [0.1.0-alpha.8](https://github.com/Coloopx/colocad/releases/tag/v0.1.0-alpha.8) - 2026-11-10
|
|
6
|
+
|
|
7
|
+
### Fixed
|
|
8
|
+
|
|
9
|
+
- Exact query snapshots for direct `face_hole_grid` / `hole_grid` stock. Cylinder seam edges contain nested lazy UV lines that the native writer did not materialize. Prepare their exact backing data on the serialization copy, preserving topology identity and support geometry; no mesh/STEP fallback or geometry healing.
|
|
10
|
+
- Linux release builds now isolate and lock architecture-specific Cargo caches, preventing concurrent registry extraction races.
|
|
11
|
+
|
|
12
|
+
### Added and updated
|
|
13
|
+
|
|
14
|
+
- Publish the expanded English/Chinese modeling best practices, handbook, harness lifecycle, troubleshooting and skill guidance introduced after alpha.7. The executable query/edit example now uses `face_hole_grid` directly.
|
|
15
|
+
- Add [CadQuery coverage and design comparison](docs/cadquery-comparison.md), [Chinese report](docs/cadquery-comparison.zh-CN.md) and a machine-readable mapping of all 150 API-index entries. This is a bounded source/contract audit, not full API parity or a new performance result.
|
|
16
|
+
- Add [ROADMAP](ROADMAP.md) / [Chinese roadmap](ROADMAP.zh-CN.md): architecture and implementation state, capability gaps, deterministic and live-agent benchmark tracks, and the planned RSI code/tool/skill improvement cycle. G4 runner implementation and campaign acceptance remain pending.
|
|
17
|
+
- Rust executor is now 0.5.1. SDK/query schemas are unchanged; updated execution fingerprints invalidate older checkpoints.
|
|
18
|
+
|
|
19
|
+
### Validation
|
|
20
|
+
|
|
21
|
+
- 129 Rust tests, 42 Node tests, six deterministic integration tests, schema verification and offline viewer checks.
|
|
22
|
+
- Grid regression covers the bundled plate, all six face directions, global grid, seam/loop descriptors, snapshot relocation, parameter/count edits, stale references and CLI replay.
|
|
23
|
+
- [Release evidence](docs/evidence/release-alpha.8.json) records the exact three-platform package checks, independent OCCT readback and retained red cases. Historical alpha.7 archives, tag and failure records remain unchanged.
|
|
24
|
+
|
|
25
|
+
## [0.1.0-alpha.7](https://github.com/Coloopx/colocad/releases/tag/v0.1.0-alpha.7) — 2026-11-09
|
|
26
|
+
|
|
27
|
+
### Added
|
|
28
|
+
|
|
29
|
+
- Exact, revision-bound B-rep queries through `CadClient.query`, `ModelingSession.query`, `cad_query` and `colocad query`. Reopened or relocated snapshots preserve identity; edits invalidate old observations.
|
|
30
|
+
- Bounded composable topology selection, trim-aware face evaluation, primitive named datums and datum-driven assembly mates with explicit direction and physical residuals.
|
|
31
|
+
- Analytic through/blind/counterbored hole recognition, plane-scoped hole groups, declared/recognized `planar_hole_mount/v1` interfaces, all-hole compatibility checks and geometry-driven external STEP replacement.
|
|
32
|
+
- Explicit part-pair separation, contact, overlap and containment measurements, plus required checks at bounded pose samples. Read-only queries perform no geometry rebuild, STEP export or tessellation.
|
|
33
|
+
- Geometry-reference highlights in recorded CLI/offline review, revision-aware compact agent feedback, capability-gated Pi query tools and updated English/Chinese modeling guidance.
|
|
34
|
+
|
|
35
|
+
### Fixed
|
|
36
|
+
|
|
37
|
+
- Required disjoint or tangent cuts now fail with `NO_MATERIAL_REMOVED` instead of silently returning unchanged stock.
|
|
38
|
+
- Selection tolerance is validated separately from minimum feature size, permitting the specified `1e-5 mm` query precision.
|
|
39
|
+
- Checkpoint reuse requires a source/compiler/target execution fingerprint, preventing an unchanged development version from restoring geometry made under old feature semantics.
|
|
40
|
+
- The process-interruption regression now resolves the packaged native when no development override is set.
|
|
41
|
+
|
|
42
|
+
### Verification
|
|
43
|
+
|
|
44
|
+
- G1–G3 accepted in their declared domains: 127 Rust tests, 41 Node tests, six deterministic integration tests, offline browser checks, and all 24 frozen geometry cases (18 positives, six correct rejections).
|
|
45
|
+
- Independent OCCT readback validates significant exact deliveries, including the 82-solid KK60/accessory reconstruction and geometry-driven foreign replacements.
|
|
46
|
+
- Two actual Pi inference tasks run with agent, harness, SDK and native in the same Linux arm64 1 vCPU / 512 MiB cgroup. The product task edits an existing sourced assembly; it does not reconstruct that product from images. Its measured peak is 370.57 MiB with no OOM.
|
|
47
|
+
- Fresh archive installations verify the SDK, CLI, packaged native, query/edit/reopen behavior and foreign mounting replacements on macOS arm64, Linux arm64 and Linux x64. Linux checks run offline at 1 vCPU / 512 MiB; x64 uses emulation.
|
|
48
|
+
|
|
49
|
+
See [G1 evidence](specs/experiments/0004/README.md), [G2/G3 evidence and failures](specs/experiments/0005/README.md), [release archive evidence](docs/evidence/release-alpha.7.json) and the [query guide](docs/engineering-queries.md).
|
|
50
|
+
|
|
51
|
+
### Compatibility and limits
|
|
52
|
+
|
|
53
|
+
- This is Colocad's JSON/TypeScript API, not a CadQuery Python or API compatibility layer. Existing modeling entry points remain available.
|
|
54
|
+
- Conical, intersecting, side-open and spline-based bore recognition can be partial. Certified allowed contact is bounded to supported opposing planar polyhedral faces; curved-contact certification and region-restricted measurement remain unsupported.
|
|
55
|
+
- Semantic intent is re-evaluated after edits. Missing or ambiguous references fail explicitly; arbitrary topology changes do not guarantee one-to-one identity.
|
|
56
|
+
- Resource figures apply to the recorded workloads. G4 has not started, and this release establishes no new speed/memory ratio against build123d. Native editable SOLIDWORKS acceptance is unchanged.
|
|
57
|
+
|
|
58
|
+
## [0.1.0-alpha.6](https://github.com/Coloopx/colocad/releases/tag/v0.1.0-alpha.6) — 2026-11-07
|
|
59
|
+
|
|
60
|
+
- Documented the SDK → CLI/tools → skill workflow, agent integration examples, CLI visualization and source-backed HIWIN KK60 showcase.
|
|
61
|
+
- Improved release verification and publishing integrity checks. Native geometry binaries were unchanged from alpha.4.
|
|
62
|
+
- Exact engineering queries and mounting-interface APIs were not included in this version.
|
|
63
|
+
|
|
64
|
+
Earlier release notes remain in [GitHub Releases](https://github.com/Coloopx/colocad/releases).
|
package/README.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
**Parametric CAD for agents. Local Rust geometry, a TypeScript SDK, a CLI, and an inspectable modeling history.**
|
|
6
6
|
|
|
7
|
-
[中文](README.zh-CN.md) · [Documentation](docs/README.md) · [npm](https://www.npmjs.com/package/@coloopx/colocad) · [Releases](https://github.com/Coloopx/colocad/releases) · [Model behind the cover](examples/hiwin-kk60/README.md)
|
|
7
|
+
[中文](README.zh-CN.md) · [Documentation](docs/README.md) · [npm](https://www.npmjs.com/package/@coloopx/colocad) · [Changelog](CHANGELOG.md) · [Releases](https://github.com/Coloopx/colocad/releases) · [Model behind the cover](examples/hiwin-kk60/README.md)
|
|
8
8
|
|
|
9
9
|
Colocad turns explicit modeling instructions into editable source, exact STEP geometry and visual review artifacts. It runs alongside the agent and its harness **inside the same sandbox**. The npm package includes the compiled Rust kernel; installed modeling needs no Python, Rust toolchain, network or separate CAD service.
|
|
10
10
|
|
|
@@ -13,6 +13,7 @@ Colocad turns explicit modeling instructions into editable source, exact STEP ge
|
|
|
13
13
|
## What you can build
|
|
14
14
|
|
|
15
15
|
- **Parts and assemblies:** parametric features, repeated part definitions, exact STEP and PNG/GLB/STL previews.
|
|
16
|
+
- **Engineering queries (alpha.7):** exact topology, composable selection, datums, holes/groups, mounting interfaces and measured assembly relationships. [Supported domains](docs/engineering-queries.md).
|
|
16
17
|
- **Agent workflows:** SDK tools and a bundled skill for interpreting dimensions, planning features, editing and checking results.
|
|
17
18
|
- **Human review:** persistent build attempts, source/receipt inspection, offline single-file HTML and four-view MP4/GIF replay.
|
|
18
19
|
|
|
@@ -32,7 +33,7 @@ flowchart LR
|
|
|
32
33
|
Requires **Node.js 22+** on **Linux x64, Linux arm64 or macOS arm64**.
|
|
33
34
|
|
|
34
35
|
```sh
|
|
35
|
-
npm install @coloopx/colocad@0.1.0-alpha.
|
|
36
|
+
npm install @coloopx/colocad@0.1.0-alpha.8
|
|
36
37
|
```
|
|
37
38
|
|
|
38
39
|
The package ships JS/TS APIs, the CLI, native executables, viewer and complete skill. Rust source is in [crates/agent-cad](crates/agent-cad); the npm tarball contains compiled binaries. [Package and model formats](docs/concepts.md).
|
|
@@ -166,14 +167,24 @@ For unchanged geometry, saved-mesh observation was 5.6×–16.8× faster than Co
|
|
|
166
167
|
|
|
167
168
|
## Support and limits
|
|
168
169
|
|
|
169
|
-
- Native packages: Linux x64/arm64 and macOS arm64, Node.js 22+. [Release verification](docs/evidence/release-alpha.
|
|
170
|
+
- Native packages: Linux x64/arm64 and macOS arm64, Node.js 22+. [Release verification](docs/evidence/release-alpha.8.json).
|
|
170
171
|
- Editable JSON/programs and exact STEP are supported; STEP does not preserve a commercial CAD application's native feature tree.
|
|
171
172
|
- General editable SOLIDWORKS output on Linux remains incomplete. The experimental Windows author requires licensed SOLIDWORKS, and a native rebuild pass is still unverified. [Native author status](docs/native-solidworks.md).
|
|
172
173
|
- CAD checks, drawing interpretation, edit preservation, fit and manufacturing readiness are separate claims. [Validation scope](docs/validation.md).
|
|
173
174
|
- A 512 MiB CAD test is not a memory guarantee for an entire resident agent, browser or video encoder.
|
|
175
|
+
- Alpha.8 fixes exact query snapshots for `face_hole_grid` and `hole_grid` seam curves. [Regression and installed-package evidence](docs/evidence/release-alpha.8.json).
|
|
176
|
+
|
|
177
|
+
## Coverage and roadmap
|
|
178
|
+
|
|
179
|
+
[CadQuery design and API coverage](docs/cadquery-comparison.md) maps all 150 entries in its API index, with explicit gaps and evidence. [ROADMAP](ROADMAP.md) records the current architecture, scoped G1-G3 acceptance and planned benchmark/RSI cycle. The G4 runner is not yet implemented.
|
|
174
180
|
|
|
175
181
|
## Documentation and help
|
|
176
182
|
|
|
183
|
+
Available in alpha.7: [exact queries and geometry-backed assembly](docs/engineering-queries.md), with a [runnable external STEP example](examples/engineering-queries/README.md). The [four ordered goals](specs/0005-capability-reliability-and-optimization.md) track functional coverage, geometry reliability, engineering usability, then benchmark-driven optimization. The SDK, CLI, tool schema and all three native targets ship together; this is a Colocad API, not CadQuery Python/API compatibility.
|
|
184
|
+
|
|
185
|
+
G1–G3 are accepted for the [declared workloads](specs/experiments/0005/README.md): 24/24 geometry cases independently verified, 127 Rust / 41 Node tests, and two live Pi tasks in Linux arm64 **1 vCPU / 512 MiB**. Peak cgroup memory was **256 MiB** for the corpus with a minimal supervisor and **371 MiB** for resident Pi/harness plus the 82-solid actuator edit and preview; zero OOM. This is resource/correctness acceptance, not a new build123d speed comparison or full industry-wide parity. G4 has not started.
|
|
186
|
+
|
|
187
|
+
|
|
177
188
|
[Getting started](docs/getting-started.md) · [API](docs/api.md) · [Agent handbook](docs/agent-modeling-handbook.md) · [Skill](skills/colocad/SKILL.md) · [Troubleshooting](docs/troubleshooting.md) · [All documentation](docs/README.md)
|
|
178
189
|
|
|
179
190
|
For a bug or feature request, [open an issue](https://github.com/Coloopx/colocad/issues) with the package version, platform, minimal model and relevant receipt. Remove credentials and private source material.
|
package/README.zh-CN.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
**面向 agent 的参数化 CAD:本地 Rust 几何内核、TypeScript SDK、CLI,以及可追溯的建模过程。**
|
|
6
6
|
|
|
7
|
-
[English](README.md) · [文档](docs/README.zh-CN.md) · [npm](https://www.npmjs.com/package/@coloopx/colocad) · [Releases](https://github.com/Coloopx/colocad/releases) · [封面模型](examples/hiwin-kk60/README.md)
|
|
7
|
+
[English](README.md) · [文档](docs/README.zh-CN.md) · [npm](https://www.npmjs.com/package/@coloopx/colocad) · [更新日志](CHANGELOG.md) · [Releases](https://github.com/Coloopx/colocad/releases) · [封面模型](examples/hiwin-kk60/README.md)
|
|
8
8
|
|
|
9
9
|
Colocad 把明确的建模指令转成可编辑源、精确 STEP 和可视化产物。Agent、harness 与 CAD 程序都在**同一个沙箱内部**。npm 包自带编译好的 Rust 内核,安装后建模无需 Python、Rust 工具链、网络或独立 CAD 服务。
|
|
10
10
|
|
|
@@ -32,7 +32,7 @@ flowchart LR
|
|
|
32
32
|
需要 **Node.js 22+**,支持 **Linux x64、Linux arm64、macOS arm64**。
|
|
33
33
|
|
|
34
34
|
```sh
|
|
35
|
-
npm install @coloopx/colocad@0.1.0-alpha.
|
|
35
|
+
npm install @coloopx/colocad@0.1.0-alpha.8
|
|
36
36
|
```
|
|
37
37
|
|
|
38
38
|
安装包包含 JS/TS API、CLI、原生可执行文件、查看器和完整 skill。Rust 源码位于 [crates/agent-cad](crates/agent-cad),npm 包携带编译产物。[模型与产物格式](docs/concepts.md)。
|
|
@@ -166,14 +166,24 @@ npx colocad render ./actuator/session ./modeling.mp4
|
|
|
166
166
|
|
|
167
167
|
## 支持范围与限制
|
|
168
168
|
|
|
169
|
-
- 原生包支持 Linux x64/arm64、macOS arm64,要求 Node.js 22+。[发布验证](docs/evidence/release-alpha.
|
|
169
|
+
- 原生包支持 Linux x64/arm64、macOS arm64,要求 Node.js 22+。[发布验证](docs/evidence/release-alpha.7.json)。
|
|
170
170
|
- 支持可编辑 JSON/程序和精确 STEP;STEP 不保存商业 CAD 软件的原生特征树。
|
|
171
171
|
- Linux 通用可编辑 SOLIDWORKS 输出尚未完成。实验性 Windows author 需要授权 SOLIDWORKS,软件内重建验收仍未通过验证。[原生导出状态](docs/native-solidworks.md)。
|
|
172
172
|
- 几何有效、读图正确、可编辑、能配合和可制造需要各自的证据。[验证范围](docs/validation.md)。
|
|
173
173
|
- CAD 的 512 MiB 测试不代表常驻 agent、浏览器和视频编码器的整体内存预算。
|
|
174
|
+
- alpha.8 修复 `face_hole_grid` 与 `hole_grid` 接缝曲线的精确查询快照。[回归与安装包证据](docs/evidence/release-alpha.8.json)。
|
|
175
|
+
|
|
176
|
+
## 能力覆盖与路线图
|
|
177
|
+
|
|
178
|
+
[CadQuery 设计与 API 覆盖报告](docs/cadquery-comparison.zh-CN.md)逐项映射其 API 索引的 150 个入口,列出缺口和证据。[ROADMAP](ROADMAP.zh-CN.md)总结架构、G1–G3 验收范围以及后续 benchmark/RSI 路线;G4 自动执行器尚未实现。
|
|
174
179
|
|
|
175
180
|
## 文档与帮助
|
|
176
181
|
|
|
182
|
+
alpha.7 已提供:[精确查询与几何驱动装配](docs/engineering-queries.zh-CN.md),以及[可运行的外部 STEP 例子](examples/engineering-queries/README.md)。[四阶段目标](specs/0005-capability-reliability-and-optimization.zh-CN.md)依次为功能覆盖、几何可靠性、工程可用性、benchmark 驱动优化。SDK、CLI、工具 schema 和三平台原生内核同步交付;这是 Colocad 自己的查询 API,不提供 CadQuery Python/API 兼容层。
|
|
183
|
+
|
|
184
|
+
G1–G3 已按[明确的验收范围](specs/experiments/0005/README.md)通过:24/24 几何案例独立验证、127 项 Rust / 41 项 Node 测试,以及 Linux arm64 **1 vCPU / 512 MiB** 内的两条真实 Pi 任务。语料执行加最小调度器的 cgroup 峰值约 **256 MiB**;驻留 Pi/harness 加 82 实体执行器改参和预览约 **371 MiB**,无 OOM。这是正确性与资源验收,不是新一轮 build123d 性能比较,也不代表全部工业场景对等;G4 尚未启动。
|
|
185
|
+
|
|
186
|
+
|
|
177
187
|
[入门](docs/getting-started.md) · [API](docs/api.md) · [完整建模指南](docs/agent-modeling-handbook.zh-CN.md) · [Skill](skills/colocad/SKILL.md) · [故障排查](docs/troubleshooting.md) · [全部文档](docs/README.zh-CN.md)
|
|
178
188
|
|
|
179
189
|
问题和功能建议请[提交 issue](https://github.com/Coloopx/colocad/issues),附上版本、平台、最小模型和相关回执,并移除凭证及私密资料。
|
package/ROADMAP.md
ADDED
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
# Colocad roadmap
|
|
2
|
+
|
|
3
|
+
Updated **2026-11-10**. [中文](ROADMAP.zh-CN.md) · [CadQuery coverage](docs/cadquery-comparison.md) · [Ordered acceptance spec](specs/0005-capability-reliability-and-optimization.md).
|
|
4
|
+
|
|
5
|
+
This roadmap separates shipped architecture, scoped acceptance and planned experiments. Colocad targets a practical independent modeling/assembly stack for agents; it does not claim full CadQuery/build123d equivalence. **G4's automated benchmark/optimization runner is planned, not shipped or accepted.**
|
|
6
|
+
|
|
7
|
+
## Current design
|
|
8
|
+
|
|
9
|
+
```mermaid
|
|
10
|
+
flowchart TD
|
|
11
|
+
A[Agent and harness inside sandbox] --> B[SDK / CLI / capability-gated tools]
|
|
12
|
+
B --> C[Explicit parameters, feature graph and assembly intent]
|
|
13
|
+
C --> D[Local Rust executor / pinned SolidCore]
|
|
14
|
+
D --> E[Exact STEP and native query snapshots]
|
|
15
|
+
E --> F[Queries, datums, interfaces and required checks]
|
|
16
|
+
F --> A
|
|
17
|
+
B --> G[Persistent accepted source and session receipts]
|
|
18
|
+
G --> H[CLI viewer / offline HTML / optional animation]
|
|
19
|
+
E --> I[Independent evaluator outside the agent input boundary]
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
Agent, harness, SDK and native executor share one sandbox. The independent evaluator can run in a separate test environment; reference geometry must not be exposed to a drawing-reconstruction agent. The modeling package does not require a separate CAD service.
|
|
23
|
+
|
|
24
|
+
- **Deterministic execution:** schema-validated parameters, features and named occurrences produce exact geometry; source edits are explicit. The model interprets materials through the harness's existing file/image tools, not a built-in image-to-CAD endpoint.
|
|
25
|
+
- **Read-only engineering observation:** exact revision-bound snapshots support selection, descriptors, supported hole/group recognition, semantic datums/interfaces and pair checks. Re-query after edits; persist recipes rather than incidental face numbers.
|
|
26
|
+
- **Usable persistence:** accepted source, failed attempts, receipts and mesh observations survive a session. CLI starts human review/export. Camera changes reuse saved geometry when possible.
|
|
27
|
+
- **Distribution:** npm contains the SDK, CLI, skill/docs and precompiled macOS arm64/Linux arm64/Linux x64 executables. Optional rendering and independent verification have additional dependencies.
|
|
28
|
+
|
|
29
|
+
## Implementation and acceptance state
|
|
30
|
+
|
|
31
|
+
| Area | State | Evidence / remaining boundary |
|
|
32
|
+
| --- | --- | --- |
|
|
33
|
+
| Modeling, parameters, local sketch solver, assembly and preview | Implemented in declared domains | [Capabilities](crates/agent-cad/src/capabilities.rs), [coverage report](docs/cadquery-comparison.md); not a general industrial success-rate claim |
|
|
34
|
+
| G1: selectors, datums, bores/groups, mounting interfaces | Accepted for the SDD 0004 contract | [G1 ledger](specs/experiments/0004/README.md); complex recognition/contact domains remain partial/unsupported |
|
|
35
|
+
| G2: geometric reliability | Frozen 24-case corpus accepted | [G2/G3 ledger](specs/experiments/0005/README.md); 18 positives and six required rejections are not a representative population estimate |
|
|
36
|
+
| G3: edit/reference/replacement/recovery and sandbox usability | Accepted on recorded tasks | Semantic lifecycle and two live Pi tasks; resource conclusions apply to those workloads |
|
|
37
|
+
| Alpha.8 grid snapshot repair | Release regression | [Evidence](docs/evidence/release-alpha.8.json); adds a combination missed by alpha.7's frozen corpus without rewriting that corpus's results |
|
|
38
|
+
| CadQuery coverage audit | Documented | 150 index entries mapped; no complete API compatibility or 150-case differential test |
|
|
39
|
+
| G4 benchmark and retrospective improvement | **Planned** | Protocol below and SDD 0005; existing benchmarks are inputs, not a completed autonomous loop |
|
|
40
|
+
| General native editable commercial CAD | Incomplete | [SOLIDWORKS status](docs/native-solidworks.md); STEP and source editability are different claims |
|
|
41
|
+
|
|
42
|
+
New failures re-open the affected gate for the changed candidate. A historical green record does not excuse a newly reproduced supported-path defect. Every release must retain earlier failing evidence and add new acceptance evidence.
|
|
43
|
+
|
|
44
|
+
## Prioritized capability work
|
|
45
|
+
|
|
46
|
+
1. **Query-to-feature bridge:** let more typed geometric recipes drive fillet, shell and other feature operands. Acceptance: cardinality/ambiguity, split/merge/delete, fresh re-resolution after edits and imported-part variants. Do not store old query refs as a shortcut.
|
|
47
|
+
2. **Missing query primitives:** spatial selection, radius ranking and explicit body/wire scope where justified by tasks. Specify whole-shape versus support-surface semantics and resource bounds before expanding the schema.
|
|
48
|
+
3. **Sketch/interchange breadth:** prioritize DXF profiles, general 2D offsets and spline/curve operations using a source-backed task corpus. Import/export representation, units, topology and edit preservation need separate checks.
|
|
49
|
+
4. **Difficult geometric families:** expand foreign STEP, intersecting bores, blends, thin walls and sweeps/surfaces. Include valid difficult cases and invalid controls; unsupported cases stay visible in denominators.
|
|
50
|
+
5. **Assembly verification:** extend curved-contact and region-specific checks only with independent reference cases. Continuous travel needs a distinct collision/motion contract; more discrete poses do not establish it.
|
|
51
|
+
|
|
52
|
+
These are planned scope expansions, not hidden requirements already satisfied by G1–G3. Dates and broad parity claims follow evidence, not an API-name count.
|
|
53
|
+
|
|
54
|
+
## Benchmark tracks
|
|
55
|
+
|
|
56
|
+
| Track | Inputs and experiment | Acceptance and metrics |
|
|
57
|
+
| --- | --- | --- |
|
|
58
|
+
| A — deterministic execution | Paired Colocad/CadQuery/build123d programs derived from the same geometry specification; primitive, grid, boolean, blend, shell, surface and assembly families | Independent exact readback first; cold time-to-STEP, resident edits, snapshot load/query, preview and export measured separately; peak cgroup, OOM, artifacts |
|
|
59
|
+
| B — engineering lifecycle | Imported parts, parameter/topology edits, compatible and incompatible replacements, interrupted/reopened sessions | Semantic intent, reference invalidation, required compatibility and pair checks, false acceptance, recovery success, latency/resource cost |
|
|
60
|
+
| C — live agent reconstruction | Licensed source packs for whole products and parts; drawings/views/BOM as available; identical task and budget per paired run | Geometry, interfaces, topology, edit challenges, tool repairs, tokens/cost and end-to-end duration; human-review artifacts retained |
|
|
61
|
+
| D — controlled skill/tool changes | Same agent/model, tools, source split and budget; change one prompt, skill reference or feedback abstraction | Held-out task success, invalid/unsupported claims, repair count, cost and context size; scripted tests alone do not prove prompt effectiveness |
|
|
62
|
+
|
|
63
|
+
CadQuery and build123d are distinct baselines even though both use OCCT. Use idiomatic implementations reviewed for unnecessary rebuilding and equivalent caching policies. Freeze their versions independently. For kernel effects hold geometry fixed; for agent outcomes hold the task fixed and report the resulting model/harness/tool configuration. Do not attribute a whole-system difference solely to the kernel.
|
|
64
|
+
|
|
65
|
+
### Drawing quality and editability
|
|
66
|
+
|
|
67
|
+
[CADArena's official methodology](https://normal.ai/research/cadarena/methodology) separates geometry and editability, keeps reference geometry/jigs out of agent inputs, and uses real manufacturer drawings. Its original report uses 18 licensed drawings and a FrontierCAD score combining geometry with editability. We borrow those evaluation principles; **we do not claim access to its licensed dataset/verifier, an official score, or a reproduction of its leaderboard**.
|
|
68
|
+
|
|
69
|
+
Our proposed evaluator will publish its own rubric and version:
|
|
70
|
+
|
|
71
|
+
- Reject missing/invalid geometry before scoring; compare at correct units. If alignment is permitted, allow translation/rotation, not rescaling or reflection.
|
|
72
|
+
- Check shape, reference material/clearance regions and topology separately. Bounding box or total volume alone cannot locate a wrong hole.
|
|
73
|
+
- Exercise predeclared edits and component replacements; measure intended downstream changes and preserved invariants. Inspect feature intent with a disclosed rubric where needed, and report judge disagreement rather than silently converting it to fact.
|
|
74
|
+
- Report geometry, editability and resource metrics separately. A combined score, if adopted, must retain its components and be labelled Colocad's evaluator, not FrontierCAD.
|
|
75
|
+
- Include no-output, crash, timeout, OOM and unsupported trials in the task denominator. Success-only timing distributions must be labelled; failed runs are never quietly dropped.
|
|
76
|
+
|
|
77
|
+
### Dataset and measurement controls
|
|
78
|
+
|
|
79
|
+
Before running a campaign, freeze a manifest containing provenance/license, hashes, units, given/derived/assumed dimensions, required outputs, editable variables, tolerances, evaluator and split. Start with the existing regressions, source-backed KK60 product and foreign-interface fixtures. Acquire additional whole-product materials with sufficient geometry and redistribution permission; the historical examples are development data, not unseen holdouts.
|
|
80
|
+
|
|
81
|
+
Use development reproducers, a frozen regression set and held-out **product families**, including unseen parameter/topology combinations. Keep holdout reference/jig assets outside the candidate agent's workspace. Repeatedly tuning against a public test case makes it development data; rotate a versioned holdout rather than continuing to call it unseen.
|
|
82
|
+
|
|
83
|
+
Use matched native hardware for platform comparisons. Linux x64 under arm64 emulation can validate correctness but cannot establish native x64 performance. Pin CPU/memory/network, OS/compiler/native/SDK hashes and cache policy. For the target 1 vCPU / 512 MiB budget distinguish CAD-only, installation and resident agent/harness measurements. Browser/video encoding has a separate budget.
|
|
84
|
+
|
|
85
|
+
Use at least five repetitions for a pilot, then preregister the promotion run size and objective. A proposed default is 20 paired runs with randomized order, median/spread and paired confidence intervals; use sufficient samples before reporting tail percentiles. Record raw timings and cgroup peak/events, including descendants and charged cache pages. Query/preview reuse cannot be compared to fresh modeling.
|
|
86
|
+
|
|
87
|
+
## RSI: auditable improvement of code, tools and skill
|
|
88
|
+
|
|
89
|
+
Here **RSI means an agent-operated iterative improvement loop** over this repository and its guidance. It does not mean model-weight training or autonomous unrestricted publication. The optimization agent may propose source/skill changes; an independent, frozen evaluator decides whether they work.
|
|
90
|
+
|
|
91
|
+
```mermaid
|
|
92
|
+
flowchart LR
|
|
93
|
+
B[Freeze baseline and task split] --> R[Run paired workloads]
|
|
94
|
+
R --> F[Classify failure or bottleneck]
|
|
95
|
+
F --> M[Minimize reproducer and trace first divergence]
|
|
96
|
+
M --> P[One bounded candidate change]
|
|
97
|
+
P --> G[Correctness and resource gates]
|
|
98
|
+
G --> H[Paired measurements and held-out challenge]
|
|
99
|
+
H --> D{Promote?}
|
|
100
|
+
D -->|accepted| B
|
|
101
|
+
D -->|rejected or inconclusive| L[Retain failure, revert candidate]
|
|
102
|
+
L --> F
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Each iteration records baseline/candidate commit, native/skill/tool hashes, hypothesis, affected family, source/split/evaluator hashes, command/environment, raw traces, smallest reproducer, original product regression, independent checks, resource/cost data and `accepted | rejected | inconclusive` with rationale.
|
|
106
|
+
|
|
107
|
+
Promotion rules:
|
|
108
|
+
|
|
109
|
+
1. A required correctness failure, incompatible-part false acceptance, swallowed ambiguity/degradation or stale reference rejects the candidate regardless of speed. The proposer cannot modify the frozen evaluator, expected geometry, tolerance or task denominator to pass.
|
|
110
|
+
2. A correctness repair needs the original red case, affected-family regressions, independent geometry checks and no new required regression. It need not claim a speed gain. The alpha.8 seam repair is this type of work, not evidence that the G4 runner exists.
|
|
111
|
+
3. A performance candidate needs a predeclared improvement objective beyond measured noise, with no correctness/resource regression outside its accepted budget. A suggested initial threshold is a ≥5% paired median improvement with a 95% paired interval supporting the direction; the campaign freezes the actual threshold before observing candidates. Report tradeoffs and rejected hypotheses.
|
|
112
|
+
4. A skill/tool candidate needs held-out live-agent evidence under the same model and budget. Better scripted behavior or prettier output does not establish a higher modeling success rate.
|
|
113
|
+
5. Bound iterations, inference spend and wall time. Stop on repeated inconclusive candidates or exhausted budget; preserve the best accepted baseline and unresolved findings. Merging/releasing remains a separately authorized maintainer action, never an automatic consequence of a score.
|
|
114
|
+
|
|
115
|
+
## G4 delivery milestones
|
|
116
|
+
|
|
117
|
+
| Milestone | Planned artifact | Exit criterion |
|
|
118
|
+
| --- | --- | --- |
|
|
119
|
+
| G4.0 — protocol and corpus | Versioned manifests, license checks, paired task specifications and holdout boundary | Independent review of metrics/tolerances/splits; valid and invalid controls; relevant G1–G3 gates current |
|
|
120
|
+
| G4.1 — runner and baseline | CLI runner, isolated execution, resource collection and immutable result bundles | Repeatable runs for all three backends; deliberate crash/OOM/timeout/no-output accounting; independent readback |
|
|
121
|
+
| G4.2 — agent tracks | Drawing/product and skill/tool ablation protocols | Fixed model/harness/budget, retained traces, predeclared edit challenges and unseen family evaluation |
|
|
122
|
+
| G4.3 — first improvement cycle | One complete candidate, plus rejected/inconclusive evidence when encountered | Original failure/bottleneck → red test → bounded patch → regression/holdout → justified accept/revert |
|
|
123
|
+
| G4.4 — recurring campaigns | Versioned reports and maintainer review of proposed changes | No benchmark contamination, preserved history and reproducible results; no unattended publish path |
|
|
124
|
+
|
|
125
|
+
G4 acceptance requires an executed end-to-end cycle and inspectable artifacts. Writing this roadmap, fixing one defect or reusing an old speed chart does not satisfy it.
|
package/ROADMAP.zh-CN.md
ADDED
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
# Colocad 路线图
|
|
2
|
+
|
|
3
|
+
更新:**2026-11-10**。[English](ROADMAP.md) · [CadQuery 覆盖报告](docs/cadquery-comparison.zh-CN.md) · [四阶段规范](specs/0005-capability-reliability-and-optimization.zh-CN.md)。
|
|
4
|
+
|
|
5
|
+
目标是形成可供 agent 实用的独立机械建模与装配系统。**G1–G3 已在声明范围内验收;G4 的自动 benchmark/回溯优化执行器仍是规划,尚未交付或验收。** 不把已有局部成绩解释成完整取代 CadQuery/build123d。
|
|
6
|
+
|
|
7
|
+
## 当前设计和实现
|
|
8
|
+
|
|
9
|
+
运行链是:同一沙箱内的 agent/harness → SDK、CLI 或能力门控工具 → 显式参数/特征/装配图 → 本地 Rust executor 与固定 SolidCore → 精确 STEP、查询快照、回执和 session。查询、测量与相关图片返回 agent;CLI 启动人类查看器、离线 HTML 或动画导出。独立验证器可在另一验证环境运行,参考几何不进入读图 agent 的输入。
|
|
10
|
+
|
|
11
|
+
| 项目 | 当前状态 | 证据与边界 |
|
|
12
|
+
| --- | --- | --- |
|
|
13
|
+
| 参数建模、局部草图求解、装配、预览 | 声明范围内实现 | [能力契约](crates/agent-cad/src/capabilities.rs),不是全部工业几何成功率 |
|
|
14
|
+
| G1:查询、选择、基准、孔组和接口 | 按 SDD 0004 验收 | [实验台账](specs/experiments/0004/README.md);复杂孔和接触领域有明确限制 |
|
|
15
|
+
| G2:几何可靠性 | 冻结的 24 个案例通过 | 18 个正例、6 个正确拒绝;不能当总体成功率 |
|
|
16
|
+
| G3:改参、替换、恢复、沙箱可用性 | 记录的工作负载通过 | [生命周期和两条真实 Pi 任务](specs/experiments/0005/README.md);资源结果有指定范围 |
|
|
17
|
+
| alpha.8 孔阵列快照修复 | 新增发布回归 | [证据](docs/evidence/release-alpha.8.json);补上此前冻结案例未覆盖的组合,不改写历史记录 |
|
|
18
|
+
| CadQuery 设计/覆盖核对 | 已形成报告 | API 索引 150 项分类,不是 150 项对照运行通过 |
|
|
19
|
+
| G4:benchmark 与自优化循环 | **规划中** | 下文定义执行器、数据和验收;现有 benchmark 不等于循环已完成 |
|
|
20
|
+
| 通用商业 CAD 原生参数树 | 未完成 | [SOLIDWORKS 状态](docs/native-solidworks.md);参数源可编辑和原生文件可编辑分别验收 |
|
|
21
|
+
|
|
22
|
+
图像与图纸仍由模型通过 harness 阅读,再形成明确参数与建模指令;没有自动 image-to-CAD 端点。查询 ref 绑定当前版本,持久化的是可重算的设计规则。出现新的受支持路径缺陷时,重新打开候选版本相关验收项;旧的绿灯不能替代新证据。
|
|
23
|
+
|
|
24
|
+
## 能力扩展优先级
|
|
25
|
+
|
|
26
|
+
1. **查询到建模特征的衔接。** 扩展可用于圆角、抽壳等操作的语义选择配方;验收数量/歧义、拆分/合并/删除、改参和外部模型变体,不能直接存旧 ref。
|
|
27
|
+
2. **通用查询补缺。** 按任务补空间选择、半径排序及合理的 wire/body 范围;先定义实体/支撑曲面语义和预算。
|
|
28
|
+
3. **草图与交换格式。** 优先用真实任务验证 DXF、一般二维 offset 和 spline;单位、拓扑和参数保留分别验收。
|
|
29
|
+
4. **几何困难族。** 扩充外部 STEP、相交孔、圆角、薄壁、扫掠和曲面样本;正例和非法输入同时存在,不靠拒绝所有难题提高分数。
|
|
30
|
+
5. **装配检查扩展。** 曲面接触、局部区域测量和连续运动需要独立契约与参考案例;增加离散姿态不能宣称全行程无碰撞。
|
|
31
|
+
|
|
32
|
+
这些是后续范围扩展,不是已经完成的 G1–G3 中隐含的全面对齐承诺。
|
|
33
|
+
|
|
34
|
+
## Benchmark 四条实验线
|
|
35
|
+
|
|
36
|
+
| 实验线 | 固定什么 | 验证和测量什么 |
|
|
37
|
+
| --- | --- | --- |
|
|
38
|
+
| A:确定性执行 | 同一几何规格,Colocad/CadQuery/build123d 各自合理实现 | 独立几何通过后比较冷启动 STEP、常驻改参、快照/查询、预览,记录 cgroup/OOM/产物 |
|
|
39
|
+
| B:工程生命周期 | 外部零件、改参/拓扑变化、兼容和不兼容替换、进程中断 | 设计意图、旧引用拒绝、配合/接口、误接受、恢复和资源 |
|
|
40
|
+
| C:真实 agent 读图 | 合法完整资料、同一任务与预算、模型/harness/工具版本 | 几何、接口、拓扑、编辑挑战、修复次数、推理成本和端到端耗时 |
|
|
41
|
+
| D:skill/tool 调优 | 同一模型、资料划分、工具和预算,只改一个因素 | 未见产品族成功率、错误声明、修复数、上下文与成本;脚本回归不代替此实验 |
|
|
42
|
+
|
|
43
|
+
CadQuery 与 build123d 分别固定版本和实现。执行效率实验固定几何;agent 实验固定任务并披露模型/harness/工具组合。检查是否有多余重建、缓存策略不对等等偏差,不把整体差异全部归因于几何内核。
|
|
44
|
+
|
|
45
|
+
## 如何借鉴 CADArena
|
|
46
|
+
|
|
47
|
+
[官方方法](https://normal.ai/research/cadarena/methodology)用真实制造商图纸,分开评估几何和可编辑性,并把参考几何/接口 jig 排除在 agent 输入之外。我们采用这种评估思路;**尚未取得其授权数据或验证器,不声称复现官方榜单或 FrontierCAD 分数。**
|
|
48
|
+
|
|
49
|
+
我们拟建立独立、版本化的评分规则:
|
|
50
|
+
|
|
51
|
+
- 先检查有效闭合几何与正确单位。允许对齐时只做平移/旋转,不通过缩放或镜像掩盖尺寸错误。
|
|
52
|
+
- 分别检查外形、关键接口区域的材料/净空、实体/孔腔拓扑。包围盒和总体积相同不足以证明孔位置正确。
|
|
53
|
+
- 运行预先指定的改参和替换挑战,检查目标变化与应保持的不变量;必要的特征树人工/模型判断使用公开 rubric,并保留分歧。
|
|
54
|
+
- 分别报告几何、编辑性和资源;如果增加总分,保留组成项并标注为我们自己的评估。
|
|
55
|
+
- 无产物、崩溃、超时、OOM 和 unsupported 均进入任务分母;仅成功任务的耗时单独标识。
|
|
56
|
+
|
|
57
|
+
数据清单必须在实验前固定来源/授权、hash、单位、给定/推导/假设尺寸、交付物、编辑参数、容差和验证器。现有回归、KK60 和外部安装接口可作为开发集;还需取得足够完整且允许使用/分发的新整机材料。已有示例不能再算陌生 holdout。
|
|
58
|
+
|
|
59
|
+
开发复现集、冻结回归集、按**产品族**划分的 holdout 分开;增加未见参数与拓扑组合。holdout 参考与 jig 不在候选 agent 的工作区内。反复看过的题转入开发集,不能继续叫未见测试。
|
|
60
|
+
|
|
61
|
+
资源固定 CPU/内存/网络、OS/编译器/native/SDK 和缓存策略。1 vCPU/512 MiB 分别测 CAD-only、安装、常驻 agent+harness;浏览器/编码另列。arm64 上模拟 x64 只能验正确性,不能代表原生 x64 性能。
|
|
62
|
+
|
|
63
|
+
每组至少 5 次作试跑;正式候选验收提前固定次数和目标,建议从 20 次随机顺序配对运行开始,报告中位数、波动与配对区间。尾分位需要足够样本。保留原始时序、cgroup 峰值和事件、子进程/缓存页口径;不能把缓存预览与全新建模相比。
|
|
64
|
+
|
|
65
|
+
## RSI:可审计的工程自优化
|
|
66
|
+
|
|
67
|
+
这里 RSI 指 agent 对**代码、工具抽象和 skill**做有证据的迭代,不是训练模型权重或不受约束地自行发布。优化 agent 提出候选,独立冻结的验证器判定结果。
|
|
68
|
+
|
|
69
|
+
循环为:**冻结基线 → 配对运行 → 定位失败/瓶颈 → 回溯首次偏差并最小化复现 → 一个假设一个候选 → 正确性和资源门槛 → 配对测量及 holdout → 接受、拒绝或无法定论 → 保留记录**。
|
|
70
|
+
|
|
71
|
+
每轮记录基线/候选 commit、native/skill/tool hash、假设、受影响族、资料/划分/验证器 hash、命令和环境、原始 trace、最小复现、原产品回归、独立验证、资源/推理成本、结论和理由。
|
|
72
|
+
|
|
73
|
+
验收规则:
|
|
74
|
+
|
|
75
|
+
1. 必需几何回归、误接受不兼容零件、吞掉歧义/降级或复用旧引用,均拒绝候选,不论多快。提案者不能通过修改冻结的参考、容差或分母让自己通过。
|
|
76
|
+
2. 正确性修复需要原始失败、受影响族回归、独立回读且无新增必需回归;不强求速度提升。alpha.8 接缝修复属于此类,但不代表 G4 自动执行器已完成。
|
|
77
|
+
3. 性能候选必须改善预先声明目标且超过噪声,不能突破资源预算或造成未接受的回退。可从中位数改善 ≥5%、95% 配对区间支持同一方向开始,但阈值必须提前冻结,不能看过结果再定。
|
|
78
|
+
4. skill/tool 候选还需要相同模型和预算下的未见任务实测;脚本表现和动画外观都不是建模成功率。
|
|
79
|
+
5. 限制轮数、推理花费和总时间;连续无法定论或耗尽预算就停,保留最后被接受的基线和未解决问题。合并/发布仍是另行授权的维护动作,不由分数自动触发。
|
|
80
|
+
|
|
81
|
+
## G4 交付顺序
|
|
82
|
+
|
|
83
|
+
| 里程碑 | 计划交付 | 完成判据 |
|
|
84
|
+
| --- | --- | --- |
|
|
85
|
+
| G4.0 | 协议、资料清单、授权、配对规格和 holdout 边界 | 指标/容差/划分独立评审;正负控制;相关 G1–G3 证据有效 |
|
|
86
|
+
| G4.1 | CLI runner、隔离执行、资源采集、不可变结果包 | 三套后端可重复运行;崩溃/OOM/超时/无产物计数;独立回读 |
|
|
87
|
+
| G4.2 | 读图/整机与 skill/tool 消融实验 | 固定模型/harness/预算、完整 trace、编辑挑战和未见产品族 |
|
|
88
|
+
| G4.3 | 第一轮完整优化 | 失败/瓶颈→红测试→通用补丁→回归/holdout→有理由的接受或回退 |
|
|
89
|
+
| G4.4 | 周期报告与候选维护流程 | 不污染测试、保留历史、可复现;没有无人值守发包路径 |
|
|
90
|
+
|
|
91
|
+
必须实际跑完并保存证据才验收 G4。写路线图、修复一个 bug 或沿用旧性能图都不算完成。
|
package/bin/colocad.mjs
CHANGED
|
@@ -1,15 +1,22 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
-
import { readFile } from "node:fs/promises";
|
|
3
|
-
import { compileTree, build, kernelModel } from "../src/index.mjs";
|
|
2
|
+
import { readFile, writeFile } from "node:fs/promises";
|
|
3
|
+
import { compileTree, build, kernelModel, CadClient } from "../src/index.mjs";
|
|
4
4
|
import { ModelingSession, exportSessionHtml } from "../src/session.mjs";
|
|
5
5
|
import { startViewer, parseViewOptions } from "../src/view-server.mjs";
|
|
6
6
|
import { renderSession, parseRenderOptions } from "../src/render.mjs";
|
|
7
7
|
import { writeSolidWorks } from "../src/solidworks.mjs";
|
|
8
8
|
const [cmd, input, output, ...flags] = process.argv.slice(2);
|
|
9
|
-
const help =
|
|
10
|
-
"colocad build TREE.json NEW_DIRECTORY [--preview]\ncolocad plan TREE.json\ncolocad record MODEL.json SESSION_DIRECTORY [--label TEXT]\ncolocad replay SESSION_DIRECTORY OUTPUT.html\ncolocad view SESSION_DIRECTORY [--no-open] [--port PORT] [--export OUTPUT.html] [--cutaway] [--view iso|front|side|top]\ncolocad render SESSION_DIRECTORY OUTPUT.mp4|OUTPUT.gif [--width N] [--height N] [--fps N] [--seconds-per-step N]\ncolocad solidworks NATIVE-JOB.json NEW_FILE.SLDPRT";
|
|
9
|
+
const help = "colocad query REVISION_DIR REQUEST.json [--out NEW_RECEIPT.json]\n"+
|
|
10
|
+
"colocad build TREE.json NEW_DIRECTORY [--preview] [--queryable]\ncolocad plan TREE.json\ncolocad record MODEL.json SESSION_DIRECTORY [--label TEXT] [--queryable]\ncolocad replay SESSION_DIRECTORY OUTPUT.html\ncolocad view SESSION_DIRECTORY [--no-open] [--port PORT] [--export OUTPUT.html] [--cutaway] [--view iso|front|side|top]\ncolocad render SESSION_DIRECTORY OUTPUT.mp4|OUTPUT.gif [--width N] [--height N] [--fps N] [--seconds-per-step N]\ncolocad solidworks NATIVE-JOB.json NEW_FILE.SLDPRT";
|
|
11
11
|
try {
|
|
12
12
|
if (cmd === "--help" || cmd === "-h" || !cmd) console.log(help);
|
|
13
|
+
else if(cmd==='query'&&input&&output&&(flags.length===0||(flags.length===2&&flags[0]==='--out'))){
|
|
14
|
+
const bytes=await readFile(output);if(bytes.length>2*1024*1024)throw Error('Query input exceeds 2 MiB');
|
|
15
|
+
const client=new CadClient({outputRoot:input,queryRoots:[input],wallMs:120000});
|
|
16
|
+
const receipt=await client.query(input,JSON.parse(bytes));
|
|
17
|
+
if(flags.length)await writeFile(flags[1],JSON.stringify(receipt,null,2)+'\n',{flag:'wx'});
|
|
18
|
+
if(receipt.ok)console.log(JSON.stringify(receipt));else{console.error(JSON.stringify(receipt));process.exitCode=1;}
|
|
19
|
+
}
|
|
13
20
|
else if (cmd === "render" && input && output) {
|
|
14
21
|
console.log(JSON.stringify(await renderSession(input,output,parseRenderOptions(flags))));
|
|
15
22
|
}
|
|
@@ -31,26 +38,27 @@ try {
|
|
|
31
38
|
if (raw.length > 2 * 1024 * 1024) throw Error("Input exceeds 2 MiB");
|
|
32
39
|
const spec = JSON.parse(raw.toString("utf8"));
|
|
33
40
|
let res;
|
|
34
|
-
if (cmd === "record" && output
|
|
41
|
+
if (cmd === "record" && output) {
|
|
42
|
+
let label=input,queryable;for(let i=0;i<flags.length;i++){if(flags[i]==='--queryable'&&queryable===undefined)queryable=true;else if(flags[i]==='--label'&&flags[i+1]!==undefined)label=flags[++i];else throw Error(help);}
|
|
35
43
|
let session;
|
|
36
44
|
try { session=await ModelingSession.create(output,{wallMs:120000}); }
|
|
37
45
|
catch(error) { if(error.code!=="EEXIST") throw error; session=await ModelingSession.open(output,{wallMs:120000}); }
|
|
38
|
-
res=await session.build(spec.format==="colocad/1"?kernelModel(spec):spec,{label
|
|
46
|
+
res=await session.build(spec.format==="colocad/1"?kernelModel(spec):spec,{label,queryable});
|
|
39
47
|
if(!res.ok) process.exitCode=1;
|
|
40
48
|
}
|
|
41
49
|
else if (cmd === "plan" && !output) res = compileTree(spec);
|
|
42
50
|
else if (
|
|
43
51
|
cmd === "build" &&
|
|
44
52
|
output &&
|
|
45
|
-
|
|
53
|
+
flags.every(flag=>['--preview','--queryable'].includes(flag))&&new Set(flags).size===flags.length
|
|
46
54
|
)
|
|
47
|
-
res = await build(spec, output, { preview: flags.
|
|
55
|
+
res = await build(spec, output, { preview: flags.includes('--preview'),queryable:flags.includes('--queryable') });
|
|
48
56
|
else if (cmd === "solidworks" && output && !flags.length)
|
|
49
57
|
res = await writeSolidWorks(spec, output);
|
|
50
58
|
else throw Error(help);
|
|
51
59
|
console.log(JSON.stringify(res));
|
|
52
60
|
}
|
|
53
61
|
} catch (e) {
|
|
54
|
-
console.error(JSON.stringify({ error: e.message }));
|
|
62
|
+
console.error(JSON.stringify(cmd==='query'?{ok:false,error:{code:'CLI_QUERY_ERROR',message:e.message}}:{ error: e.message }));
|
|
55
63
|
process.exitCode = 1;
|
|
56
64
|
}
|
package/docs/README.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
Build locally with **SDK → CLI/tools → skill**. The skill guides modeling decisions; the SDK and Rust kernel execute them. Agent, harness and CAD process share the same sandbox and filesystem.
|
|
6
6
|
|
|
7
|
-
These guides target **@coloopx/colocad 0.1.0-alpha.
|
|
7
|
+
These guides target **@coloopx/colocad 0.1.0-alpha.8**, Node.js 22+, Linux x64/arm64 or macOS arm64. The project is still alpha; documentation does not imply complete CAD coverage.
|
|
8
8
|
|
|
9
9
|
[中文开发指南](README.zh-CN.md)
|
|
10
10
|
|
|
@@ -19,12 +19,23 @@ These guides target **@coloopx/colocad 0.1.0-alpha.6**, Node.js 22+, Linux x64/a
|
|
|
19
19
|
| Use Claude Code | [Claude Code integration](integrations/claude-code.md) |
|
|
20
20
|
| Use Codex | [Codex integration](integrations/codex.md) |
|
|
21
21
|
| Model efficiently from dimensions or views | [Best practices](best-practices.md) |
|
|
22
|
+
| Query, declare installation intent, replace a part and verify edits | [Practical workflow and runnable example](best-practices.md#query-declare-intent-assemble-then-challenge-the-edit), [query API](engineering-queries.md) |
|
|
22
23
|
| Diagnose a failed call or installation | [Troubleshooting](troubleshooting.md) |
|
|
23
24
|
| Run examples and contribute a change | [Contributing](../CONTRIBUTING.md) |
|
|
24
25
|
| Compare execution performance and limits | [Performance evidence](performance.md) |
|
|
25
26
|
| Check native SOLIDWORKS export status | [Native author](native-solidworks.md) |
|
|
26
27
|
| Understand what has actually been tested | [Integration verification](integrations/verification.md), [geometry validation](validation.md) |
|
|
28
|
+
| Check G1–G3 acceptance, Linux limits and live-agent traces | [Frozen corpus, lifecycle and sandbox evidence](../specs/experiments/0005/README.md) |
|
|
29
|
+
| Contribute geometry queries and assembly interfaces | [SDD 0004 revision 2 — contract and 28 acceptance cases](../specs/0004-engineering-query-and-assembly-interfaces.md), [implementation evidence](../specs/experiments/0004/README.md) |
|
|
27
30
|
|
|
28
|
-
Runnable adapters and their regression tests live in [examples/integrations](../examples/integrations/README.md).
|
|
31
|
+
Runnable adapters and their regression tests live in [examples/integrations](../examples/integrations/README.md). The standalone SDK example pins the published alpha.3 compatibility baseline; current Pi/session adapters use this checkout and the matching native. The complete Pi example project is in GitHub. Alpha.5 also packages the compact adapter and guided workflow example. The skill, assets and its helper scripts **are** included.
|
|
29
32
|
|
|
30
33
|
Performance depends on workload and execution mode. See the [README measurements](../README.md#performance), with their startup, geometry and memory accounting, before choosing a budget. A 512 MiB CAD benchmark is not a 512 MiB guarantee for a resident LLM harness plus CAD.
|
|
34
|
+
|
|
35
|
+
- [Exact geometry queries and datum-driven assembly (alpha.7)](engineering-queries.md)
|
|
36
|
+
- [Four ordered goals and benchmark/retrospective optimization](../specs/0005-capability-reliability-and-optimization.md)
|
|
37
|
+
|
|
38
|
+
## Coverage and roadmap
|
|
39
|
+
|
|
40
|
+
- [CadQuery coverage and design comparison](cadquery-comparison.md), including the 150-entry mapping.
|
|
41
|
+
- [ROADMAP](../ROADMAP.md): architecture, accepted scope, planned benchmarks and RSI promotion rules.
|
package/docs/README.zh-CN.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
colocad 的分层是 **SDK 为基础,CLI / 工具负责调用,skill 指导建模流程**。Agent、harness 和 Rust CAD 进程都在同一个沙箱内,共享项目目录。现有 harness 负责模型推理、权限、会话和产物保存,不需要额外部署 CAD 服务。
|
|
6
6
|
|
|
7
|
-
本文对应 `@coloopx/colocad@0.1.0-alpha.
|
|
7
|
+
本文对应 `@coloopx/colocad@0.1.0-alpha.8`,要求 Node.js 22+;预编译内核支持 Linux x64/arm64、macOS arm64。工程仍处于 alpha 阶段。
|
|
8
8
|
|
|
9
9
|
## 从材料到交付的完整指南
|
|
10
10
|
|
|
@@ -15,7 +15,7 @@ colocad 的分层是 **SDK 为基础,CLI / 工具负责调用,skill 指导
|
|
|
15
15
|
在已有 Node 项目根目录执行;没有 `package.json` 时先运行 `npm init -y`:
|
|
16
16
|
|
|
17
17
|
```sh
|
|
18
|
-
npm install --save-exact @coloopx/colocad@0.1.0-alpha.
|
|
18
|
+
npm install --save-exact @coloopx/colocad@0.1.0-alpha.8
|
|
19
19
|
./node_modules/.bin/colocad build \
|
|
20
20
|
node_modules/@coloopx/colocad/examples/manifold.json ./manifold-v1 --preview
|
|
21
21
|
```
|
|
@@ -76,7 +76,7 @@ test ! -e .agents/skills/colocad && \
|
|
|
76
76
|
- 失败要报告具体特征。不要为了生成图片静默跳过切孔或圆角;显式降级也应保留在交付说明中。
|
|
77
77
|
- 性能分别测冷启动到 STEP、连续改参、缓存预览、包含推理的完整 agent 周期。CAD 的 512 MiB 基准不等于整个 agent/harness 也只需 512 MiB。
|
|
78
78
|
|
|
79
|
-
[
|
|
79
|
+
[建模、查询、接口装配与改参复验最佳实践](best-practices.zh-CN.md) · [常见故障](troubleshooting.md) · [贡献与回归](../CONTRIBUTING.md)
|
|
80
80
|
|
|
81
81
|
## 当前验证边界
|
|
82
82
|
|
|
@@ -85,3 +85,12 @@ test ! -e .agents/skills/colocad && \
|
|
|
85
85
|
参数 JSON 可重建,STEP 是精确几何;二者不等于 SOLIDWORKS 原生特征树。Linux 通用可编辑 `.SLDPRT` 尚未完成,Windows author 尚缺授权软件内的完整回读重建验收。[接入验证范围](integrations/verification.md) · [几何与原生输出验证](validation.md)
|
|
86
86
|
|
|
87
87
|
[性能证据与测量边界](performance.md) · [SOLIDWORKS 原生导出状态](native-solidworks.md)
|
|
88
|
+
|
|
89
|
+
## 工程查询与装配接口(alpha.7)
|
|
90
|
+
|
|
91
|
+
[SDD 0004 中文实施说明](../specs/0004-engineering-query-and-assembly-interfaces.zh-CN.md)与[英文规范](../specs/0004-engineering-query-and-assembly-interfaces.md)第 2 版已纳入 CadQuery 对照评审,定义可组合选择、几何基准、面/孔/轴查询、稳定引用、安装接口与 28 项验收。支持域内的 G1–G3 已通过验收,alpha.7 包含 SDK、CLI 与三平台原生实现。[实验台账](../specs/experiments/0004/README.md)保留迭代过程;[安装包验证](evidence/release-alpha.7.json)检查实际交付。
|
|
92
|
+
|
|
93
|
+
- [精确查询与几何基准装配(alpha.7)](engineering-queries.zh-CN.md)
|
|
94
|
+
- [CadQuery 覆盖与设计对比](cadquery-comparison.zh-CN.md):150 个 API 索引入口的映射与缺口。
|
|
95
|
+
- [ROADMAP](../ROADMAP.zh-CN.md):当前架构、验收范围、benchmark 与 RSI 规划。
|
|
96
|
+
- [四阶段目标与 benchmark / 回溯优化](../specs/0005-capability-reliability-and-optimization.zh-CN.md)
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Agent CAD handbook
|
|
2
2
|
|
|
3
|
-
A complete workflow for source preparation, modeling tools, agent guidance, validation and tuning. This describes the implemented Colocad alpha.
|
|
3
|
+
A complete workflow for source preparation, modeling tools, agent guidance, validation and tuning. This describes the implemented Colocad alpha.7 interfaces and recommendations informed by actual use and primary sources. It is not a claim of universal optimal prompting or autonomous industrial reconstruction.
|
|
4
4
|
|
|
5
5
|
[完整中文指南](agent-modeling-handbook.zh-CN.md) · [Research and evidence](agent-modeling-research.md) · [Packaged skill](../skills/colocad/SKILL.md)
|
|
6
6
|
|
|
@@ -20,9 +20,9 @@ Colocad does not currently expose an automatic image-to-CAD endpoint. The KK60 c
|
|
|
20
20
|
|
|
21
21
|
## Keep the tools understandable
|
|
22
22
|
|
|
23
|
-
Register the existing capabilities, validation, build, preview and edit tools first; enable sketch solving or STEP inspection when needed. Preserve schemas and `$defs`. `cad_validate` is input preflight, not a shape check. Plain `cad_edit` takes `{model, parameters}`; recorded editing takes `{parameters}` and uses the accepted source. The harness owns paths, budgets, permissions and artifact retention inside the same sandbox.
|
|
23
|
+
Register the existing capabilities, validation, build, preview and edit tools first; enable capability-gated `cad_query` for measured geometry/assembly work, and sketch solving or STEP inspection when needed. Preserve schemas and `$defs`. `cad_validate` is input preflight, not a shape check. Plain `cad_edit` takes `{model, parameters}`; recorded editing takes `{parameters}` and uses the accepted source. The harness owns paths, budgets, permissions and artifact retention inside the same sandbox.
|
|
24
24
|
|
|
25
|
-
Return the failing feature/code, revision paths/hashes, relevant geometry and timing, cache information and **all** degradations. Keep complete traces and large meshes on disk. The [compact adapter](../examples/integrations/compact-tools.mjs) implements this without changing execution semantics. The [guided workflow](../examples/integrations/guided-workflow.mjs) performs actual builds, quantitative edits, failure recovery, observation and CLI HTML export:
|
|
25
|
+
Return the failing feature/query ID and code, `query_revision_id`, revision paths/hashes, relevant geometry and timing, coverage/ambiguity, cache information and **all** degradations. Keep complete traces and large meshes on disk. The [compact adapter](../examples/integrations/compact-tools.mjs) implements this without changing execution semantics. The [guided workflow](../examples/integrations/guided-workflow.mjs) performs actual builds, quantitative edits, failure recovery, observation and CLI HTML export:
|
|
26
26
|
|
|
27
27
|
```sh
|
|
28
28
|
node examples/integrations/guided-workflow.mjs ./out/guided-workflow
|
|
@@ -47,6 +47,14 @@ For each meaningful change: validate, build, inspect its receipt and a relevant
|
|
|
47
47
|
|
|
48
48
|
A display explosion is not motion verification. One matching total volume cannot locate a misplaced hole. [Modeling-loop reference](../skills/colocad/references/modeling-loop.md).
|
|
49
49
|
|
|
50
|
+
## Use exact queries to preserve assembly intent
|
|
51
|
+
|
|
52
|
+
Enable exact query artifacts on the accepted build, then observe a specific definition or occurrence in an explicit coordinate space and tolerance. Narrow the support plane before its openings/groups, inspect coverage and cardinality, and retain ambiguity. Persist a supported semantic recipe in `Model.datums`/`Model.interfaces`, not an observed topology ref or incidental face index. Named interface attachments then drive mates and required compatibility/relationship checks.
|
|
53
|
+
|
|
54
|
+
After an edit or source replacement, obtain the new revision, re-evaluate recipes and check required fit/clearance. Stale refs, missing faces and incompatible patterns are actionable failures, not a reason to bind a convenient candidate. A positive unsigned boundary distance does not alone establish clearance; inspect relationship and overlap. Unsupported/partial evidence cannot certify absence or fit.
|
|
55
|
+
|
|
56
|
+
The [best-practice walkthrough](best-practices.md#query-declare-intent-assemble-then-challenge-the-edit) includes a runnable alpha.7 query/edit/rejection example. The [external installation example](../examples/engineering-interfaces/README.md) extends it to three compatible and two incompatible sources using the same geometric recipe and independent STEP validation. [Exact supported domains](engineering-queries.md).
|
|
57
|
+
|
|
50
58
|
## Guide the agent without overloading it
|
|
51
59
|
|
|
52
60
|
The skill entry point routes to materials, modeling loop, tool contracts, prompts, tuning and history. Load only what the current task needs. Give the model a concise task contract and the relevant source views, accepted state and checks. Ask for inspectable dimensions, decisions and artifacts rather than a hidden chain of thought.
|
|
@@ -57,7 +65,7 @@ The skill entry point routes to materials, modeling loop, tool contracts, prompt
|
|
|
57
65
|
|
|
58
66
|
Separate interpretation quality from geometry correctness and execution performance. For wrong dimensions, improve source/frame interpretation first. For broken edits, fix dependencies. For tool confusion/context cost, reduce overlap and return focused evidence. For execution time, inspect feature, validation, export and preview timings before optimizing. Reuse clients/checkpoints and shared definitions; reuse a checked mesh for camera-only changes.
|
|
59
67
|
|
|
60
|
-
Comparisons with build123d need the same verified geometry, output requirements, precision, cold/warm policy and hardware limits. Report repeat counts, distributions, failures and memory accounting. An edited film duration is not a benchmark; cached observation is not equivalent to a fresh build.
|
|
68
|
+
Comparisons with build123d need the same verified geometry, output requirements, precision, cold/warm policy and hardware limits. Report repeat counts, distributions, failures and memory accounting. An edited film duration is not a benchmark; cached observation is not equivalent to a fresh build. Separate snapshot creation/load/query time from modeling, export and preview. CAD-only resource figures cannot be reused as a resident-agent or video-encoder budget. [G3](../specs/experiments/0005/README.md) records specific resident Pi workloads; [archive acceptance](evidence/release-alpha.7.json) additionally includes installation. G4 has not started.
|
|
61
69
|
|
|
62
70
|
To evaluate skill changes, hold source packs, tasks, model/provider versions, tools and budget fixed, change one factor, and retain unseen tasks. Measure dimensions/features, edit preservation, fit claims, unsupported claims, correction count, inference cost and end-to-end time. Scripted regressions prove implementation contracts; they do not prove a prompt's success rate on unseen drawings. [Tuning reference](../skills/colocad/references/tuning.md).
|
|
63
71
|
|