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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,26 @@
2
2
 
3
3
  Notable user-facing changes are recorded here. Colocad remains alpha software; supported geometry and measured workloads define each release's scope.
4
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
+
5
25
  ## [0.1.0-alpha.7](https://github.com/Coloopx/colocad/releases/tag/v0.1.0-alpha.7) — 2026-11-09
6
26
 
7
27
  ### Added
package/README.md CHANGED
@@ -33,7 +33,7 @@ flowchart LR
33
33
  Requires **Node.js 22+** on **Linux x64, Linux arm64 or macOS arm64**.
34
34
 
35
35
  ```sh
36
- npm install @coloopx/colocad@0.1.0-alpha.7
36
+ npm install @coloopx/colocad@0.1.0-alpha.8
37
37
  ```
38
38
 
39
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).
@@ -167,11 +167,16 @@ For unchanged geometry, saved-mesh observation was 5.6×–16.8× faster than Co
167
167
 
168
168
  ## Support and limits
169
169
 
170
- - Native packages: Linux x64/arm64 and macOS arm64, Node.js 22+. [Release verification](docs/evidence/release-alpha.7.json).
170
+ - Native packages: Linux x64/arm64 and macOS arm64, Node.js 22+. [Release verification](docs/evidence/release-alpha.8.json).
171
171
  - Editable JSON/programs and exact STEP are supported; STEP does not preserve a commercial CAD application's native feature tree.
172
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).
173
173
  - CAD checks, drawing interpretation, edit preservation, fit and manufacturing readiness are separate claims. [Validation scope](docs/validation.md).
174
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.
175
180
 
176
181
  ## Documentation and help
177
182
 
package/README.zh-CN.md CHANGED
@@ -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.7
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)。
@@ -171,6 +171,11 @@ npx colocad render ./actuator/session ./modeling.mp4
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
 
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.
@@ -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/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**, Node.js 22+, Linux x64/arm64 or macOS arm64. The project is still alpha; documentation does not imply complete CAD coverage.
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,6 +19,7 @@ These guides target **@coloopx/colocad 0.1.0-alpha.7**, 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) |
@@ -33,3 +34,8 @@ Performance depends on workload and execution mode. See the [README measurements
33
34
 
34
35
  - [Exact geometry queries and datum-driven assembly (alpha.7)](engineering-queries.md)
35
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.
@@ -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`,要求 Node.js 22+;预编译内核支持 Linux x64/arm64、macOS arm64。工程仍处于 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.7
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
- [详细最佳实践](best-practices.md) · [常见故障](troubleshooting.md) · [贡献与回归](../CONTRIBUTING.md)
79
+ [建模、查询、接口装配与改参复验最佳实践](best-practices.zh-CN.md) · [常见故障](troubleshooting.md) · [贡献与回归](../CONTRIBUTING.md)
80
80
 
81
81
  ## 当前验证边界
82
82
 
@@ -91,4 +91,6 @@ test ! -e .agents/skills/colocad && \
91
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
92
 
93
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 规划。
94
96
  - [四阶段目标与 benchmark / 回溯优化](../specs/0005-capability-reliability-and-optimization.zh-CN.md)
@@ -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. A 512 MiB CAD run does not cover a resident LLM harness or video encoder.
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
 
@@ -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
- 默认可先注册前五项,按任务加入后两项。`CadClient.inspect` 读取保存的报告,不是任意几何查询器;当前工具集也没有自动图纸尺寸识别工具。材料阅读使用现有 harness 的文件/图像工具,独立精确检查使用明确的几何验证程序。
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、版本与产物路径、实体数、尺寸/体积、当前相关测量、时间、缓存命中和全部降级项。完整 feature trace、模型和网格保存在文件里,必要时按引用读取。不要每轮把 STEP 文本、大网格和全部历史图片塞回上下文。
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 与单项改动。覆盖明确尺寸件、需要剖视解释的零件、编辑后仍须配合的装配和有歧义的材料;留出未参与调优的任务。测关键尺寸/特征、编辑保持、接口检查、无依据结论、修改次数、推理成本和端到端时间。
@@ -1,6 +1,6 @@
1
1
  # Modeling and integration best practices
2
2
 
3
- For the complete material preparation, tool/skill/prompt design, workflow and tuning guide, see the [agent modeling handbook](agent-modeling-handbook.md).
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 and sketch solving when the task requires them. Supply the skill for workflow guidance and assets; keep the full schema accessible instead of pasting it into every system prompt.
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, the failing feature if any, solid count, dimensions/volume, validation summary, artifact paths and a preview image. Store the detailed feature trace and timings for diagnostics. Never send a full STEP, mesh JSON or base64 PNG as ordinary text in the conversation when the harness supports image/file attachments.
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.