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

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.
Files changed (46) hide show
  1. package/CHANGELOG.md +44 -0
  2. package/README.md +9 -3
  3. package/README.zh-CN.md +8 -3
  4. package/bin/colocad.mjs +17 -9
  5. package/docs/README.md +7 -2
  6. package/docs/README.zh-CN.md +9 -2
  7. package/docs/agent-modeling-handbook.md +1 -1
  8. package/docs/agent-modeling-handbook.zh-CN.md +2 -2
  9. package/docs/api.md +9 -6
  10. package/docs/engineering-queries.md +122 -0
  11. package/docs/engineering-queries.zh-CN.md +74 -0
  12. package/docs/getting-started.md +1 -1
  13. package/docs/integrations/claude-code.md +1 -1
  14. package/docs/integrations/codex.md +1 -1
  15. package/docs/integrations/pi.md +17 -4
  16. package/docs/integrations/verification.md +7 -1
  17. package/examples/integrations/README.md +11 -2
  18. package/examples/integrations/compact-tools.mjs +1 -1
  19. package/kernel/dist/client.d.ts +5 -2
  20. package/kernel/dist/client.js +35 -7
  21. package/kernel/dist/generated.d.ts +297 -4
  22. package/kernel/dist/process.d.ts +1 -1
  23. package/kernel/dist/process.js +3 -3
  24. package/kernel/dist/query-generated.d.ts +181 -0
  25. package/kernel/dist/query-generated.js +1 -0
  26. package/kernel/dist/tools.d.ts +35 -0
  27. package/kernel/dist/tools.js +11 -2
  28. package/kernel/dist/types.d.ts +9 -0
  29. package/kernel/native/darwin-arm64/agent-cad +2 -2
  30. package/kernel/native/darwin-arm64/manifest.json +2 -2
  31. package/kernel/native/linux-arm64/agent-cad +2 -2
  32. package/kernel/native/linux-arm64/manifest.json +2 -2
  33. package/kernel/native/linux-x64/agent-cad +2 -2
  34. package/kernel/native/linux-x64/manifest.json +2 -2
  35. package/kernel/release.json +4 -4
  36. package/kernel/schemas/model.schema.json +1752 -135
  37. package/kernel/schemas/query.schema.json +1150 -0
  38. package/package.json +5 -2
  39. package/skills/colocad/references/tool-contracts.md +14 -2
  40. package/src/build.mjs +3 -2
  41. package/src/index.d.mts +2 -1
  42. package/src/session.d.mts +5 -3
  43. package/src/session.mjs +26 -10
  44. package/viewer/dist/index.js +179 -179
  45. package/viewer/dist/standalone.js +179 -179
  46. package/viewer/index.d.ts +2 -1
package/CHANGELOG.md ADDED
@@ -0,0 +1,44 @@
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.7](https://github.com/Coloopx/colocad/releases/tag/v0.1.0-alpha.7) — 2026-11-09
6
+
7
+ ### Added
8
+
9
+ - 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.
10
+ - Bounded composable topology selection, trim-aware face evaluation, primitive named datums and datum-driven assembly mates with explicit direction and physical residuals.
11
+ - 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.
12
+ - 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.
13
+ - Geometry-reference highlights in recorded CLI/offline review, revision-aware compact agent feedback, capability-gated Pi query tools and updated English/Chinese modeling guidance.
14
+
15
+ ### Fixed
16
+
17
+ - Required disjoint or tangent cuts now fail with `NO_MATERIAL_REMOVED` instead of silently returning unchanged stock.
18
+ - Selection tolerance is validated separately from minimum feature size, permitting the specified `1e-5 mm` query precision.
19
+ - Checkpoint reuse requires a source/compiler/target execution fingerprint, preventing an unchanged development version from restoring geometry made under old feature semantics.
20
+ - The process-interruption regression now resolves the packaged native when no development override is set.
21
+
22
+ ### Verification
23
+
24
+ - 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).
25
+ - Independent OCCT readback validates significant exact deliveries, including the 82-solid KK60/accessory reconstruction and geometry-driven foreign replacements.
26
+ - 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.
27
+ - 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.
28
+
29
+ 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).
30
+
31
+ ### Compatibility and limits
32
+
33
+ - This is Colocad's JSON/TypeScript API, not a CadQuery Python or API compatibility layer. Existing modeling entry points remain available.
34
+ - 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.
35
+ - Semantic intent is re-evaluated after edits. Missing or ambiguous references fail explicitly; arbitrary topology changes do not guarantee one-to-one identity.
36
+ - 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.
37
+
38
+ ## [0.1.0-alpha.6](https://github.com/Coloopx/colocad/releases/tag/v0.1.0-alpha.6) — 2026-11-07
39
+
40
+ - Documented the SDK → CLI/tools → skill workflow, agent integration examples, CLI visualization and source-backed HIWIN KK60 showcase.
41
+ - Improved release verification and publishing integrity checks. Native geometry binaries were unchanged from alpha.4.
42
+ - Exact engineering queries and mounting-interface APIs were not included in this version.
43
+
44
+ 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.6
36
+ npm install @coloopx/colocad@0.1.0-alpha.7
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,7 +167,7 @@ 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.6.json).
170
+ - Native packages: Linux x64/arm64 and macOS arm64, Node.js 22+. [Release verification](docs/evidence/release-alpha.7.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).
@@ -174,6 +175,11 @@ For unchanged geometry, saved-mesh observation was 5.6×–16.8× faster than Co
174
175
 
175
176
  ## Documentation and help
176
177
 
178
+ 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.
179
+
180
+ 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.
181
+
182
+
177
183
  [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
184
 
179
185
  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.6
35
+ npm install @coloopx/colocad@0.1.0-alpha.7
36
36
  ```
37
37
 
38
38
  安装包包含 JS/TS API、CLI、原生可执行文件、查看器和完整 skill。Rust 源码位于 [crates/agent-cad](crates/agent-cad),npm 包携带编译产物。[模型与产物格式](docs/concepts.md)。
@@ -166,7 +166,7 @@ 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.6.json)。
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)。
@@ -174,6 +174,11 @@ npx colocad render ./actuator/session ./modeling.mp4
174
174
 
175
175
  ## 文档与帮助
176
176
 
177
+ 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 兼容层。
178
+
179
+ 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 尚未启动。
180
+
181
+
177
182
  [入门](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
183
 
179
184
  问题和功能建议请[提交 issue](https://github.com/Coloopx/colocad/issues),附上版本、平台、最小模型和相关回执,并移除凭证及私密资料。
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 && (!flags.length || (flags.length===2 && flags[0]==="--label"))) {
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:flags[1]??input});
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
- (flags.length === 0 || (flags.length === 1 && flags[0] === "--preview"))
53
+ flags.every(flag=>['--preview','--queryable'].includes(flag))&&new Set(flags).size===flags.length
46
54
  )
47
- res = await build(spec, output, { preview: flags.length > 0 });
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.6**, 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.7**, 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
 
@@ -24,7 +24,12 @@ These guides target **@coloopx/colocad 0.1.0-alpha.6**, Node.js 22+, Linux x64/a
24
24
  | Compare execution performance and limits | [Performance evidence](performance.md) |
25
25
  | Check native SOLIDWORKS export status | [Native author](native-solidworks.md) |
26
26
  | Understand what has actually been tested | [Integration verification](integrations/verification.md), [geometry validation](validation.md) |
27
+ | Check G1–G3 acceptance, Linux limits and live-agent traces | [Frozen corpus, lifecycle and sandbox evidence](../specs/experiments/0005/README.md) |
28
+ | 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
29
 
28
- Runnable adapters and their regression tests live in [examples/integrations](../examples/integrations/README.md). They install the published npm release. 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.
30
+ 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
31
 
30
32
  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.
33
+
34
+ - [Exact geometry queries and datum-driven assembly (alpha.7)](engineering-queries.md)
35
+ - [Four ordered goals and benchmark/retrospective optimization](../specs/0005-capability-reliability-and-optimization.md)
@@ -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.6`,要求 Node.js 22+;预编译内核支持 Linux x64/arm64、macOS arm64。工程仍处于 alpha 阶段。
7
+ 本文对应 `@coloopx/colocad@0.1.0-alpha.7`,要求 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.6
18
+ npm install --save-exact @coloopx/colocad@0.1.0-alpha.7
19
19
  ./node_modules/.bin/colocad build \
20
20
  node_modules/@coloopx/colocad/examples/manifold.json ./manifold-v1 --preview
21
21
  ```
@@ -85,3 +85,10 @@ 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
+ - [四阶段目标与 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.6 interfaces and recommendations informed by actual use and primary sources. It is not a claim of universal optimal prompting or autonomous industrial reconstruction.
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
 
@@ -1,6 +1,6 @@
1
1
  # Agent CAD 完整工作指南:资料、工具、建模闭环与调优
2
2
 
3
- 本指南对应 colocad alpha.6 的 skill 和可运行示例。目标是把指定产品及其工程依据变成可编辑源、精确几何、可追溯检查和可供人类查看的过程。以下是基于仓库实作和公开资料整理的默认方法,不是已证明适用于所有模型/产品的最优提示词。
3
+ 本指南对应 colocad alpha.7 的 skill 和可运行示例。目标是把指定产品及其工程依据变成可编辑源、精确几何、可追溯检查和可供人类查看的过程。以下是基于仓库实作和公开资料整理的默认方法,不是已证明适用于所有模型/产品的最优提示词。
4
4
 
5
5
  [English overview](agent-modeling-handbook.md) · [研究依据与适用边界](agent-modeling-research.md) · [随包 skill](../skills/colocad/SKILL.md) · [提示词模板](../skills/colocad/references/prompt-patterns.md) · [真实 KK60 产品](../examples/hiwin-kk60/README.md)
6
6
 
@@ -209,7 +209,7 @@ KK60 的真实螺旋槽让总装触发内部 STEP 实体数限制,最终修复
209
209
  ## 8. 运行、审阅与交付
210
210
 
211
211
  ```sh
212
- npm install @coloopx/colocad@0.1.0-alpha.6
212
+ npm install @coloopx/colocad@0.1.0-alpha.7
213
213
  node node_modules/@coloopx/colocad/examples/hiwin-kk60/run.mjs ./actuator
214
214
  npx colocad view ./actuator/session
215
215
  npx colocad replay ./actuator/session ./actuator.html
package/docs/api.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # SDK, CLI and tool reference
2
2
 
3
- Targets `@coloopx/colocad@0.1.0-alpha.6`. The [public declarations](../src/index.d.mts) and [kernel declarations](../kernel/src/types.ts) are the complete type contracts.
3
+ Targets `@coloopx/colocad@0.1.0-alpha.7`. The [public declarations](../src/index.d.mts) and [kernel declarations](../kernel/src/types.ts) are the complete type contracts.
4
4
 
5
5
  ## Feature-tree SDK and CLI
6
6
 
@@ -20,7 +20,7 @@ colocad build TREE.json NEW_DIRECTORY [--preview]
20
20
  colocad solidworks NATIVE-JOB.json NEW_FILE.SLDPRT
21
21
  ```
22
22
 
23
- CLI success prints JSON to stdout. Failure prints an error to stderr and exits nonzero. Feature-tree CLI input is limited to 2 MiB. The third command is the [experimental Windows author](../README.md#native-solidworks-author-experimental).
23
+ CLI success prints JSON to stdout. Failure prints an error to stderr and exits nonzero. Feature-tree CLI input is limited to 2 MiB. The third command is the [experimental Windows author](native-solidworks.md).
24
24
 
25
25
  ## Kernel SDK
26
26
 
@@ -39,7 +39,9 @@ The host chooses `outputRoot`, a local directory for generated revisions, and op
39
39
  | `capabilities()` | Native version, supported operations, budgets and declared limitations |
40
40
  | `schema()` | Complete kernel model JSON Schema |
41
41
  | `validate(model)` | Cheap input/dependency/budget preflight; no geometric validity guarantee |
42
- | `build(model, previousRevision?)` | Build/check exact geometry and export a new revision; optional checkpoint source |
42
+ | `build(model, optionsOrRevision?)` | Build/check exact geometry; options include `queryable` and `previousRevision`; a legacy revision string remains supported |
43
+ | `querySchema()` | Exact-query JSON Schema from the installed native |
44
+ | `query(artifactDirectory, request)` | Read an exact snapshot using its `query_revision_id`, within host-configured `queryRoots` |
43
45
  | `edit(model, parameters)` | Change existing numeric parameters, then build; input remains unchanged |
44
46
  | `preview(model, options?)` | Build or reuse a matching display mesh and render it |
45
47
  | `observeArtifact(directory, options?)` | Render from a trusted saved mesh with integrity checks |
@@ -59,7 +61,7 @@ Build receipts include `artifact_directory`, `geometry`, `validation`, feature r
59
61
 
60
62
  Preview options include `view: "iso" | "top" | "bottom" | "front" | "back" | "left" | "right"`, image size, `chord_mm` and section settings. Use the schema for exact fields and limits. A different camera can reuse geometry; changing mesh precision or geometry can require new work.
61
63
 
62
- The kernel SDK limits serialized input to 32 MiB. Query capabilities for native feature, assembly and mesh budgets. The SDK has no in-flight `AbortSignal` contract in alpha.5: the Pi example checks cancellation before dispatch, while an already-running native call is bounded by `wallMs`.
64
+ The kernel SDK limits serialized input to 32 MiB. Query capabilities for native feature, assembly and mesh budgets. The SDK has no in-flight `AbortSignal` contract in alpha.7: the Pi example checks cancellation before dispatch, while an already-running native call is bounded by `wallMs`.
63
65
 
64
66
  ## Agent tools
65
67
 
@@ -69,15 +71,16 @@ The kernel SDK limits serialized input to 32 MiB. Query capabilities for native
69
71
  | --- | --- |
70
72
  | `cad_capabilities` | `{}` |
71
73
  | `cad_validate` | `{ model }` |
72
- | `cad_build` | `{ model }` |
74
+ | `cad_build` | `{ model, options?: { queryable?: boolean } }` |
73
75
  | `cad_preview` | `{ model, options? }` |
74
76
  | `cad_edit` | `{ model, parameters }` |
75
77
  | `cad_solve_sketch` | `{ sketch, parameters? }` |
76
78
  | `cad_inspect_step` | `{ model, asset }` |
79
+ | `cad_query` | `{ artifact_directory, request }`; session-bound form takes `{ request }` against the accepted artifact |
77
80
 
78
81
  Preserve the complete `inputSchema`, including root `$defs`. Do not wrap it without rewriting `$ref` locations. These definitions are transport-neutral; the package does not launch an MCP server. If a provider rejects the union-heavy schema, use the skill with shell tools or build a provider-specific schema adapter and test its validation behavior.
79
82
 
80
- The Pi example exposes the first five tools for a smaller modeling surface. It converts failed receipts into failed tool results and includes PNG bytes in image content when a preview is at most 4 MiB. The full model/source is in the artifact directory, not in a fabricated project ID.
83
+ The Pi example exposes the first five tools plus capability-gated `cad_query`. It converts failed receipts into failed tool results and includes PNG bytes in image content when a preview is at most 4 MiB. Build/edit feedback retains the query revision. See the [query guide](engineering-queries.md) for selection, datums, holes/groups, interfaces and supported geometric relationships.
81
84
 
82
85
  For STEP imports, use `attachStep(model, assetId, stepText)` from `@coloopx/colocad/kernel`. The host registers text under an opaque ID; the model need not choose arbitrary filesystem paths. The returned model is a copy. [Integration policy and lifecycle](integrations/overview.md).
83
86
 
@@ -0,0 +1,122 @@
1
+ # Exact queries and geometry-backed assembly
2
+
3
+ **Available in @coloopx/colocad 0.1.0-alpha.7**, including all three packaged native targets. For source development, build the native executable and SDK from the same checkout. [中文](engineering-queries.zh-CN.md) · [Runnable example](../examples/engineering-queries/README.md) · [Detailed contract](../specs/0004-engineering-query-and-assembly-interfaces.md).
4
+
5
+ Use this layer when a part's installation geometry must be measured or selected before assembly. The local Rust executable evaluates exact B-rep geometry; the SDK, CLI and agent tools share that implementation. No Python geometry workflow or separate service is required. Agent, harness and executable run in the same sandbox.
6
+
7
+ ## Readiness and compatibility
8
+
9
+ This layer is ready for the declared mechanical assembly workflows: exact topology selection, primitive datums, analytic bores/groups, planar mounting interfaces, geometry-driven replacement and explicit pair measurements. The release is alpha. Colocad uses its own JSON/TypeScript contracts; it does not run CadQuery Python programs or promise identical selector syntax or feature coverage.
10
+
11
+ G1–G3 acceptance covers the frozen 24-case corpus, lifecycle tests and two live agent tasks. [Release archive checks](evidence/release-alpha.7.json) verify the installed SDK/CLI/native together on macOS arm64 and Linux arm64/x64; x64 is emulated on an arm64 host. Unsupported recognition/contact domains are listed below and remain explicit partial/error results.
12
+
13
+ ## Build once, query the accepted revision
14
+
15
+ ```js
16
+ import { CadClient } from '@coloopx/colocad/kernel';
17
+ const cad = new CadClient({ outputRoot: './jobs' });
18
+ const built = await cad.build(model, { queryable: true });
19
+ if (!built.ok) throw Error(built.error.message);
20
+ const request = {
21
+ schema: 'colocad.query/1',
22
+ query_revision_id: built.data.query_revision_id,
23
+ target: { definition_id: 'part' }, // a final feature ID in this model
24
+ space: 'definition',
25
+ tolerance: { linear_mm: 1e-5, angular_rad: 1e-7 },
26
+ queries: [{
27
+ id: 'top', op: 'faces',
28
+ where: { planar_normal_aligned_with: [0, 0, 1] },
29
+ limit: 64
30
+ }]
31
+ };
32
+ const result = await cad.query(built.data.artifact_directory, request);
33
+ ```
34
+
35
+ A queryable build saves `query-manifest.json` plus exact `query-definition-*.smb` payloads. Reopen them in a fresh process or move the entire artifact directory: references retain identity. Queries do not replay features, read STEP, export STEP, heal geometry or generate preview meshes. The receipt reports definition loading, indexing and query time separately. Ordinary builds remain opt-in; a model declaring `datums` or `interfaces` automatically requires these artifacts. Explicitly disabling them with such a declaration fails.
36
+
37
+ Use `target: {instance_path: ['subassembly', 'instance']}` with `space: 'assembly'` for world-space measurements. Positions include the solved rigid translation; directions do not. Queries use normal solved placements, independently of exploded previews. Lengths and areas are invariant. The SDK confines paths to host-configured `queryRoots` (default `outputRoot`); agents cannot change that configuration through query JSON.
38
+
39
+ The CLI accepts the same request file:
40
+
41
+ ```sh
42
+ colocad record model.json session --queryable --label 'Queryable part'
43
+ # Use artifact_directory and query_revision_id from the build receipt.
44
+ colocad query ARTIFACT_DIRECTORY request.json --out receipt.json
45
+ colocad view session
46
+ ```
47
+
48
+ `--out` creates a new file and refuses to overwrite one. For a `colocad/1` tree, `colocad build tree.json NEW_DIR --queryable` also enables queries. `ModelingSession.query(request)` records the observation and source revision without changing accepted geometry. A query failure is retained in history. In `createSessionTools`, `cad_query` is bound to the latest accepted artifact; raw `createCadTools` takes an allowed artifact directory explicitly. With a queryable preview, the Query tab highlights native face/edge/loop outlines and datum/group markers. The build saves hash-bound `query-display.json`; these sampled outlines are display aids, never measurement authority. Exploding the viewer moves overlays with their parts without changing query coordinates.
49
+
50
+ ## Select intent, preserve ambiguity
51
+
52
+ Selections are bounded expressions, not executable code. Available operations are `entities`, `refs`, `filter`, `children`, `ancestors`, `siblings`, `union`, `intersection`, `difference`, `rank` and `expect`. Filters provide typed analytic classes, names, area/length/radius ranges, planar normal tests, loop roles and bounded `all`/`any`/`not`.
53
+
54
+ For a hole center on one installation face, select that face, then its inner loops, their circular edges, and derive point datums. Selecting all circular edges on the body would also collect the opposite openings. `siblings` requires an explicit shared child type: faces connected through an edge use `{kind:'siblings', input: selectedFace, entity:'face', via:'edge'}`. It does not return every face in the body.
55
+
56
+ `rank` returns the entire tied rank. An `expect` asserting one result fails on a tie, even when the page limit is one. Exact identity deduplicates entity sets; ordered loop edge uses preserve repeated seam uses. Cursors bind the revision, target, space, tolerance and operation. Snapshot `TopologyRef` values are observations, not permanent edit recipes; an edit invalidates old references.
57
+
58
+ Limits: 64 queries per batch, 256 results per page, expression depth 8 / 128 nodes, 200,000 adjacency visits, 2 MiB input, 8 MiB output and 64 MiB total exact snapshot payload. These are admission limits, not proof of a 512 MiB runtime envelope. Source accuracy remains unknown when the source does not specify it.
59
+
60
+ ## Name geometry for mates
61
+
62
+ A declaration belongs to a final part definition, independently of its assembly occurrences:
63
+
64
+ ```json
65
+ {
66
+ "id": "seat",
67
+ "definition": "part",
68
+ "tolerance": { "linear_mm": 0.00001, "angular_rad": 0.0000001 },
69
+ "derive": {
70
+ "kind": "selected",
71
+ "selection": {
72
+ "kind": "filter",
73
+ "input": { "kind": "entities", "entity": "face" },
74
+ "where": { "planar_normal_aligned_with": [0, 0, 1] }
75
+ },
76
+ "derive": { "kind": "plane" }
77
+ }
78
+ }
79
+ ```
80
+
81
+ Put declarations in `Model.datums`. IDs are unique within a definition. A selected primitive requires exactly one entity. `selected` supports vertex/circle points, analytic planes, cylinder/circle axes and straight-edge directions. Other recipes are `design_point`, ordered `point_difference`, and `frame`. A frame names an origin point and two nonparallel orthogonal directions (`x` and `z`, each with explicit positive/negative sense); it is right-handed. Its dependencies must occur earlier in the same definition. Persistent selections cannot contain prior-snapshot refs. Derived versus declared design intent remains visible in receipts.
82
+
83
+ Use `{instance:'part_occurrence', datum:'seat'}` instead of a numeric attachment frame. Plane mates consume a plane, concentric mates an axis, coincidence/distance a point, and fixed/prismatic/revolute mates require a full frame. A full frame can also provide these lower-dimensional attachments. `frame` and `datum` are mutually exclusive; omitted legacy attachment data still uses the original identity frame.
84
+
85
+ An internal basis completes a plane/axis only for numerical evaluation. It adds no physical orientation constraint: an axis plus an axial plane leaves rotation about that axis free. A cylinder axis alone cannot establish the axial origin required by a revolute joint. Declare the required point/frame or combine axis and plane constraints explicitly.
86
+
87
+ Read accepted named datums using `{id:'mount', op:'named_datums', ids:['seat']}`. Their source refs bind to the final query revision and transform with the chosen occurrence. Rebuilding after parameter edits reruns recipes. Missing, ambiguous, degenerate and incompatible datum kinds fail with structured errors; they do not silently select the first candidate.
88
+
89
+ ## Holes, groups and installation interfaces
90
+
91
+ `holes` recognizes connected analytic cylindrical bores with planar entrances/ends in consistently oriented closed solids. It distinguishes through, blind and counterbored holes, joins supported axial/angular split patches, and excludes external shafts. A counterbore is one physical hole with multiple segments. Conical tips, intersecting bores, side-open recesses and spline cylinders return partial coverage with source references; they are not silently called complete holes.
92
+
93
+ `hole_groups` accepts optional `support_faces` refs and `where: {pattern, member_count, equal_diameter}`. Patterns are linear, rectangular, circular or unstructured. It returns physical centers, axes, dimensions, residuals, competing subsets, excluded openings and symmetry. Plane-scoped coverage excludes uncertainty away from that support's topology, but retains its diagnostic. Recognition is bounded to 64 openings per support and 10,000 hypotheses; large searches fail `QUERY_LIMIT`.
94
+
95
+ `interfaces` observes named declarations (`ids`) or recognizes candidates (`profile: 'planar_hole_mount/v1'`, optional `support_faces` and group filter). Candidates do not acquire a unique engineering orientation from symmetric holes. Put persistent intent in `Model.interfaces`: uniquely select a plane and hole group, optionally a coaxial register, specify the group-center/axis-intersection/design-point origin, verification tolerance, pattern dimensions, bore sizes and termination. Add an explicit design direction or geometry-backed orientation datum when an oriented mate needs one. The declaration is reevaluated against the built geometry; unsupported, missing, multiple or incompatible results fail.
96
+
97
+ Use `{instance, interface, orientation?}` in a mate. Full-frame mates require an orientation; lower-dimensional mates retain unresolved freedoms. `interface_compatibility` checks all-hole correspondence, plane relation/gap, axis offsets, each side's diameter range and optional register radial clearance. It records ambiguity and actual paired refs. Independent diameter ranges do not prove bolt or thread fit.
98
+
99
+ The [complete external assembly example](../examples/engineering-interfaces/README.md) shows the actual typed declaration, replacement and error workflow. Relative filters accept `planar_normal_aligned_with: {datum}`, `planar_normal_parallel_to: {datum}`, and `planar_coplanar_with: {datum}`. The last requires a plane and uses both normal and offset, avoiding a blind-hole bottom with the same normal. Projection ranks also accept a named datum direction. Dependencies must be earlier in the definition; ordered circle-center differences follow a rigidly rotated source instead of relying on its global axes.
100
+
101
+ ## Exact relationships and acceptance checks
102
+
103
+ A read-only query can request:
104
+
105
+ ```js
106
+ { id: 'gap', op: 'measure',
107
+ a: { instance_path: ['shaft'] }, b: { instance_path: ['support'] } }
108
+ ```
109
+
110
+ The snapshot target and both measurement targets remain explicit. Definition space measures local shapes; assembly space uses solved occurrence poses. The result distinguishes separated, touching, overlapping, contained and indeterminate, with unsigned boundary distance, overlap volume, witness points and numerical tolerances. Containment can have a positive boundary gap; distance is not penetration depth. `items[0]` is also exposed as `measurement`. Indeterminate is a partial result; required assembly checks fail. Witness topology refs are marked unavailable where the copy-based solver cannot preserve their mapping.
111
+
112
+ `checks: [{kind:'geometric_relationship', a:{instance}, b:{instance}, tolerance, max_overlap_mm3, min_clearance_mm?, allowed_contacts?, pose_samples?}]` makes a required claim. Minimum clearance requires separation. Explicit pose deltas (at most 32) are evaluated individually and retained even on failure; this does not establish continuous-motion clearance. Required exact checks reject degraded feature ancestry and reduced representations.
113
+
114
+ Allowed contacts currently certify selected opposing planar faces on polyhedral solids by checking both complete solids against their support half-spaces. A single closest witness is insufficient. Other overlap is never exempted. Curved contact certification and region-restricted measurements fail explicitly as unsupported. Ordinary whole-part measurements support curved solids.
115
+
116
+ ## Evidence and boundaries
117
+
118
+ The foreign flange workflow passes base, different-housing and arbitrarily rotated replacement inputs while rejecting wrong pitch and missing holes. The complete KK60 reconstruction with an independently authored bracket passes 82-solid OCCT readback and nine explicit contact/gap samples. These cases, tolerances and provenance are retained in the [experiment ledger](../specs/experiments/0004/README.md); they are not a general industrial success rate.
119
+
120
+ Descriptors include native UV/periodicity, ordered pcurves, seam uses, adjacency and tolerances. Trimmed definition bounds are transformed AABBs and may be conservative after rotation; `bounds_semantics` identifies this. Query results do not certify machining tolerances, threads, load capacity or global uniqueness of a local mate solution. Broader reliability and target sandbox acceptance are governed by [the ordered goals](../specs/0005-capability-reliability-and-optimization.md).
121
+
122
+ Development checkpoints carry `execution_policy`, a deterministic fingerprint of the executor Rust sources, manifest/lockfile, compiler and target. A missing or different policy forces replay, even when the version string matches. This prevents a development upgrade from restoring old feature semantics. The [G3 evidence](../specs/experiments/0005/README.md) covers actual process interruption, reopen/relocation, semantic split/merge/delete, replacements and Linux resource limits.
@@ -0,0 +1,74 @@
1
+ # 精确查询与几何基准装配
2
+
3
+ **从 @coloopx/colocad 0.1.0-alpha.7 起提供,包含三平台预编译内核。** 源码开发仍需使用同一份 checkout 编译的内核和 SDK。[English](engineering-queries.md) · [可运行例子](../examples/engineering-queries/README.md) · [详细规范](../specs/0004-engineering-query-and-assembly-interfaces.zh-CN.md)。
4
+
5
+ 这层能力用于在装配前查询零件的安装几何。几何解释在本地 Rust 内核中完成,SDK、CLI 与 agent 工具共用实现;agent、harness 和可执行文件仍位于同一沙箱中。
6
+
7
+ ## 构建一次,查询已接受版本
8
+
9
+ `cad.build(model, {queryable:true})` 返回 `artifact_directory` 和 `query_revision_id`,并保存 `query-manifest.json` 与精确 `query-definition-*.smb`。将带预期版本号、目标、坐标系、容差和查询列表的请求交给 `cad.query(directory, request)`。完整 SDK 代码见英文页。
10
+
11
+ 查询不重放建模特征、不读 STEP、不导出 STEP、不修补几何、不生成网格。整个工件目录迁移或换进程重开后,快照引用保持一致。普通模型按需启用;声明 `Model.datums` 的模型自动启用,显式关闭会报错。SDK 的 `queryRoots` 由宿主配置,默认只允许 `outputRoot` 下的工件。
12
+
13
+ ```sh
14
+ colocad record model.json session --queryable --label '可查询零件'
15
+ # 采用构建回执里的 artifact_directory 与 query_revision_id。
16
+ colocad query ARTIFACT_DIRECTORY request.json --out receipt.json
17
+ colocad view session
18
+ ```
19
+
20
+ CLI 的 `--out` 拒绝覆盖已有文件。`colocad/1` 特征树也可使用 `colocad build tree.json NEW_DIR --queryable`。`ModelingSession.query(request)` 保存查询输入、回执和源版本,不替换已接受几何,失败查询同样留档。session 工具自动绑定最后接受的几何工件;原始 SDK 工具显式接收受宿主限制的工件路径。Query 页支持 native ref 绑定的拓扑轮廓高亮,见下文。
21
+
22
+ 定义坐标使用 `target:{definition_id:'part'}`;装配坐标使用 `target:{instance_path:['group','part_occurrence']}` 与 `space:'assembly'`。位置包含平移,方向不包含平移。查询采用求解后的正常装配位置,不随爆炸预览姿态变化。
23
+
24
+ ## 选择表达意图,歧义必须保留
25
+
26
+ 支持实体枚举、过滤、子拓扑、祖先、相邻拓扑、集合运算、排序和数量断言。筛选项包括名称、解析几何类型、面积/长度/半径范围、平面法向、内外环,以及有界的 `all/any/not`。
27
+
28
+ 安装面上的孔中心应按“指定平面 → 内环 → 圆边 → 圆心”查询,避免把背面的开口也选进来。`siblings` 显式指定共享子拓扑,例如通过边相邻的面:`{kind:'siblings',input:selectedFace,entity:'face',via:'edge'}`。
29
+
30
+ 排序并列时返回整个并列集合,随后 `expect:1` 必须失败;分页不能把歧义隐藏成唯一结果。集合按精确拓扑身份去重,环内重复使用的接缝边保留。游标绑定版本、目标、坐标系、容差和操作。快照引用用于观察;改参后旧引用会失效,持久化意图应使用语义选择配方。
31
+
32
+ 限制:每批 64 项查询、每页 256 项、表达式深度 8 / 128 节点、20 万次邻接访问、2 MiB 输入、8 MiB 输出、64 MiB 精确快照。它们是输入边界,不能据此宣称 512 MiB 沙箱已验收。源数据未声明的工程精度仍是未知。
33
+
34
+ ## 把基准直接用于配合
35
+
36
+ `Model.datums` 的声明包含 `id`、最终零件 `definition`、`tolerance` 和 `derive`。名称在同一定义中唯一;输出类型由推导规则确定。`selected` 配方使用通用选择,必须得到唯一实体,然后推导顶点/圆心、解析平面、圆柱/圆轴或直边方向。
37
+
38
+ 其他配方包括显式设计点 `design_point`、有序点差 `point_difference` 和完整 `frame`。frame 引用一个原点基准及 x/z 方向基准,每个方向显式选择正负;检查非退化和正交,构成右手系。依赖必须是同一定义中较早的声明;不能使用旧快照引用。回执区分几何推导与显式设计意图。
39
+
40
+ 附件可以写成 `{instance:'part_occurrence',datum:'seat'}`。平面配合需要 plane,同心需要 axis,点重合/距离需要 point;固定、滑动和转动关节需要完整 frame。完整 frame 也可提供低维附件。`frame` 与 `datum` 互斥;旧式附件全部省略时仍采用原有默认 frame。
41
+
42
+ 内部补出的数值基底不会增加工程约束。轴线加轴向平面保留绕轴的一个自由度;单独的圆柱轴线没有转动关节所需的轴向原点,需补足点/frame 或组合轴和平面约束。
43
+
44
+ 通过 `{id:'mount',op:'named_datums',ids:['seat']}` 回读命名基准。回执中的源拓扑引用绑定最终版本,并按目标实例变换。改参重建会重算配方;缺失、歧义、退化或类型不兼容均返回结构化错误。
45
+
46
+ ## 验收范围
47
+
48
+ 例子将 OCCT 独立生成的法兰 STEP 导入,选择孔轴和底面,用几何基准装配轴,导出 STEP;过粗的轴被精确碰撞检查拒绝。独立 OCCT 回读检查两个实体、解析体积及 0.2 mm 最小间隙。这是通用解析验证件,不是商业产品复原,也不是工业模型成功率语料。
49
+
50
+ G1 新增的相对筛选、专用描述、孔/沉孔识别、孔组、安装接口和测量见下文;更广泛的 G2/G3 验收由实验账本记录。装配包围盒由定义 AABB 刚性变换得到,旋转后可能偏宽。查询结果不证明加工精度、螺纹、承载能力或局部求解的全局唯一性。[四阶段目标与后续自优化循环](../specs/0005-capability-reliability-and-optimization.zh-CN.md)。
51
+
52
+
53
+ ## G1 扩展:孔、接口、测量与显示
54
+
55
+ 以[英文 API 指南](engineering-queries.md)和 Rust 生成的 schema 为字段依据。开发源代码新增:
56
+
57
+ - `holes`:封闭定向实体中的解析圆柱通孔、平底盲孔和沉孔;支持受限的轴向/角向分片合并,轴外表面不作为孔。锥底、相交孔、侧开口、样条圆柱明确返回 partial 和来源诊断。
58
+ - `hole_groups`:指定安装面或枚举支持面,识别直线、矩形、圆形和无结构孔组;保留子集、额外孔、尺寸、残差与对称性。每面最多 64 个开口、10,000 个候选假设。面范围内的完整性单独判断,远离该面的不支持几何仍保留诊断。
59
+ - `interfaces` / `Model.interfaces`:`planar_hole_mount/v1` 声明重建后重新验证几何,支持安装面、孔组、可选定位圆柱、原点、方向和尺寸要求。不能从对称孔组猜出工程方向。完整坐标系配合必须提供方向;缺失、歧义、尺寸不匹配会失败。
60
+ - 相对选择支持 `planar_normal_aligned_with: {datum}`、`planar_normal_parallel_to: {datum}`、`planar_coplanar_with: {datum}`。共面测试同时检查法向和位置,防止误选同法向的盲孔底。基准只能引用同一零件中更早的声明。
61
+ - `interface_compatibility`:验证所有孔的对应、平面方向/间距、孔轴偏移、双方直径范围与可选定位间隙;独立直径范围不代表已经验证螺纹或螺栓配合。
62
+ - `measure`:显式两个目标,返回分离/接触/重叠/包含/不确定、边界距离、重叠体积和见证点。正距离不排除实体包含。结果在 `items[0]` 和 `measurement` 中;不确定为 partial,必需的装配检查不通过。复制求解器无法可靠恢复的见证拓扑 refs 明确不可用。
63
+ - `geometric_relationship`:必需的整零件关系检查和最多 32 个显式姿态样本;不等同连续运动认证。允许接触目前仅支持多面体中可通过完整半空间证明的相对平面,其他碰撞不豁免;曲面接触认证、局部区域限定测量明确不支持。
64
+ - `colocad view SESSION` 的 Query 页可高亮 native ref 对应的面/边/环轮廓及基准/孔组。可查询 preview 在建模时保存有哈希绑定的 `query-display.json`,采样轮廓只作显示依据;查询不重建、不导出、不三角化。爆炸图跟随零件移动,不修改查询坐标。
65
+
66
+ `datums` 或 `interfaces` 自动要求精确快照,显式禁用会报错。外部 STEP 示例包含底座、不同外形替换件、任意旋转来源及错误孔距/缺孔拒绝。完整 KK60 加附件例子保留 82 个实体和九项行程检查,见[复现实例](../examples/engineering-interfaces/README.md)。以上是明确范围内的功能证据,G2/G3 的可靠性、生命周期和沙箱资源验收另行记录。
67
+
68
+ 开发检查点新增 `execution_policy`,绑定 Rust 源码、依赖锁、编译器与目标平台;缺失或不匹配即重新计算,不能因为版本字符串相同就复用旧语义。[G3 证据](../specs/experiments/0005/README.md)覆盖真实进程中断、重新打开/迁移、语义面拆分/合并/删除、零件替换和 Linux 沙箱限额。
69
+
70
+ ## 可用性与 CadQuery 的关系
71
+
72
+ 这层能力已可用于声明支持的机械装配工作流:精确拓扑选择、基本基准、解析孔/孔组、平面安装接口、几何驱动替换及显式零件对测量。当前仍为 alpha;使用 Colocad 自己的 JSON/TypeScript 契约,不执行 CadQuery Python 程序,也不保证其选择器语法或全部特征等价。
73
+
74
+ G1–G3 的冻结语料、生命周期与两条真实 agent 任务已验收;[alpha.7 安装包验证](evidence/release-alpha.7.json)进一步覆盖 macOS arm64、Linux arm64/x64 上包内 SDK/CLI/native 的实际调用,其中 x64 在 arm64 宿主模拟执行。锥形/相交/侧开孔识别可能为 partial;曲面接触认证与局部区域限定测量仍显式不支持。
@@ -10,7 +10,7 @@ Run in a new project directory:
10
10
  mkdir my-cad-project
11
11
  cd my-cad-project
12
12
  npm init -y
13
- npm install --save-exact @coloopx/colocad@0.1.0-alpha.6
13
+ npm install --save-exact @coloopx/colocad@0.1.0-alpha.7
14
14
  cp node_modules/@coloopx/colocad/examples/manifold.json manifold.json
15
15
  ./node_modules/.bin/colocad plan manifold.json
16
16
  ./node_modules/.bin/colocad build manifold.json ./manifold-v1 --preview
@@ -7,7 +7,7 @@ Use a project skill with Claude Code's existing Bash and file/image tools. Insta
7
7
  From your project's root (with a `package.json`; create one with `npm init -y` if needed):
8
8
 
9
9
  ```sh
10
- npm install --save-exact @coloopx/colocad@0.1.0-alpha.6
10
+ npm install --save-exact @coloopx/colocad@0.1.0-alpha.7
11
11
  mkdir -p .claude/skills
12
12
  test ! -e .claude/skills/colocad && \
13
13
  cp -R node_modules/@coloopx/colocad/skills/colocad .claude/skills/colocad
@@ -7,7 +7,7 @@ Install a project skill and let Codex use its existing terminal and image tools.
7
7
  From the root of a Node project:
8
8
 
9
9
  ```sh
10
- npm install --save-exact @coloopx/colocad@0.1.0-alpha.6
10
+ npm install --save-exact @coloopx/colocad@0.1.0-alpha.7
11
11
  mkdir -p .agents/skills
12
12
  test ! -e .agents/skills/colocad && \
13
13
  cp -R node_modules/@coloopx/colocad/skills/colocad .agents/skills/colocad