@coloopx/colocad 0.1.0-alpha.3 → 0.1.0-alpha.5
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/NOTICE.md +2 -0
- package/README.md +130 -4
- package/README.zh-CN.md +111 -4
- package/bin/colocad.mjs +28 -4
- package/docs/README.md +28 -0
- package/docs/README.zh-CN.md +85 -0
- package/docs/agent-modeling-handbook.md +68 -0
- package/docs/agent-modeling-handbook.zh-CN.md +222 -0
- package/docs/agent-modeling-research.md +22 -0
- package/docs/api.md +95 -0
- package/docs/best-practices.md +45 -0
- package/docs/concepts.md +37 -0
- package/docs/getting-started.md +53 -0
- package/docs/integrations/claude-code.md +52 -0
- package/docs/integrations/codex.md +55 -0
- package/docs/integrations/overview.md +53 -0
- package/docs/integrations/pi.md +73 -0
- package/docs/integrations/verification.md +30 -0
- package/docs/modeling-history.md +60 -0
- package/docs/modeling-workflow.zh-CN.md +77 -0
- package/docs/troubleshooting.md +25 -0
- package/docs/validation.md +23 -0
- package/examples/hiwin-kk60/README.md +55 -0
- package/examples/hiwin-kk60/model.mjs +94 -0
- package/examples/hiwin-kk60/run.mjs +14 -0
- package/examples/hiwin-kk60/sources.json +88 -0
- package/examples/integrations/README.md +47 -0
- package/examples/integrations/compact-tools.mjs +27 -0
- package/examples/integrations/guided-workflow.mjs +31 -0
- package/kernel/native/darwin-arm64/agent-cad +1 -1
- package/kernel/native/darwin-arm64/manifest.json +1 -2
- package/kernel/native/linux-arm64/agent-cad +1 -1
- package/kernel/native/linux-arm64/manifest.json +1 -2
- package/kernel/native/linux-x64/agent-cad +2 -2
- package/kernel/native/linux-x64/manifest.json +2 -3
- package/kernel/release.json +4 -4
- package/package.json +40 -4
- package/skills/colocad/SKILL.md +18 -8
- package/skills/colocad/assets/product-brief.example.json +20 -0
- package/skills/colocad/references/history.md +19 -0
- package/skills/colocad/references/materials.md +37 -0
- package/skills/colocad/references/modeling-loop.md +33 -0
- package/skills/colocad/references/prompt-patterns.md +70 -0
- package/skills/colocad/references/tool-contracts.md +33 -0
- package/skills/colocad/references/tuning.md +30 -0
- package/src/render.mjs +72 -0
- package/src/session.d.mts +34 -0
- package/src/session.mjs +140 -0
- package/src/view-server.mjs +50 -0
- package/viewer/THREE-LICENSE +21 -0
- package/viewer/dist/index.js +4236 -0
- package/viewer/dist/standalone.js +4236 -0
- package/viewer/index.d.ts +18 -0
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
{
|
|
2
|
+
"product": "HIWIN KK60 Standard, 5 mm lead, 300 mm rail, one A block, no motor/cover/switch",
|
|
3
|
+
"source": {
|
|
4
|
+
"publisher": "HIWIN Corporation",
|
|
5
|
+
"productUrl": "https://hiwin.com/products/kk-series-ballscrew-stages/kk-series/",
|
|
6
|
+
"catalogUrl": "https://hiwin.com/wp-content/uploads/2026/08/HIWIN-Ballscrew-Driven-Stages-Catalog-1.pdf",
|
|
7
|
+
"documentCode": "K99TE16-1906",
|
|
8
|
+
"downloaded": "2026-11-07",
|
|
9
|
+
"pages": {
|
|
10
|
+
"modelCode": 15,
|
|
11
|
+
"screwDiameterLead": 16,
|
|
12
|
+
"dimensionDrawing": 22
|
|
13
|
+
},
|
|
14
|
+
"pdfPages": {
|
|
15
|
+
"modelCode": 18,
|
|
16
|
+
"screwDiameterLead": 19,
|
|
17
|
+
"dimensionDrawing": 25
|
|
18
|
+
},
|
|
19
|
+
"sha256": "be54c5158ef723dfe2d97be26403b3970f5bc6c9290352e3d6b321d4560481c0"
|
|
20
|
+
},
|
|
21
|
+
"catalogDimensionsMm": {
|
|
22
|
+
"railLength": 300,
|
|
23
|
+
"overallLength": 370,
|
|
24
|
+
"railWidth": 60,
|
|
25
|
+
"carriageHeight": 33,
|
|
26
|
+
"screwAxisHeight": 23,
|
|
27
|
+
"railTopHeight": 22,
|
|
28
|
+
"carriageLength": 82,
|
|
29
|
+
"carriageMetalLength": 51,
|
|
30
|
+
"carriageWidth": 42,
|
|
31
|
+
"stroke": 210,
|
|
32
|
+
"screwDiameter": 12,
|
|
33
|
+
"lead": 5,
|
|
34
|
+
"driveShaftDiameter": 6,
|
|
35
|
+
"railMountHoles": {
|
|
36
|
+
"count": 6,
|
|
37
|
+
"diameter": 5.5,
|
|
38
|
+
"counterboreDiameter": 9.5,
|
|
39
|
+
"counterboreDepth": 4.7,
|
|
40
|
+
"xPitch": 30,
|
|
41
|
+
"zPitch": 100,
|
|
42
|
+
"G": 50
|
|
43
|
+
},
|
|
44
|
+
"carriageMountHoles": {
|
|
45
|
+
"count": 4,
|
|
46
|
+
"thread": "M5 x 0.8",
|
|
47
|
+
"depth": 8,
|
|
48
|
+
"pitch": [
|
|
49
|
+
30,
|
|
50
|
+
30
|
|
51
|
+
]
|
|
52
|
+
},
|
|
53
|
+
"motorSupport": {
|
|
54
|
+
"width": 59.6,
|
|
55
|
+
"height": 44.5,
|
|
56
|
+
"bottomOffset": 0.5,
|
|
57
|
+
"length": 59,
|
|
58
|
+
"registerDiameter": 28,
|
|
59
|
+
"boltCircleDiameter": 40
|
|
60
|
+
},
|
|
61
|
+
"datumSlots": {
|
|
62
|
+
"width": 15,
|
|
63
|
+
"depth": 1.5
|
|
64
|
+
}
|
|
65
|
+
},
|
|
66
|
+
"datumInterpretations": [
|
|
67
|
+
"X is width, Y is vertical, Z is the travel axis; overall Z=0..370.",
|
|
68
|
+
"Rail Z=7..307; three mounting stations Z=57,157,257, measured from the right rail end using G=50.",
|
|
69
|
+
"Mid-stroke carriage center Z=157; travel +/-105 gives full block envelope Z=11..303.",
|
|
70
|
+
"Screw axis Y=23 was checked on the enlarged SECTION A-A, not inferred from the 15 mm side-hole dimension."
|
|
71
|
+
],
|
|
72
|
+
"assumptions": [
|
|
73
|
+
"U-rail internal wall/floor profile, chamfers, groove radii and guide ball spacing are reconstructed. They are not manufacturing dimensions.",
|
|
74
|
+
"Screw groove uses four cubic circular-section lofts per turn, repeated 56 times. This is a geometric helix approximation, not the manufacturer's gothic-arch ground raceway.",
|
|
75
|
+
"Ball-nut internals and recirculation passages are not disclosed in the catalog. The nut is an annular envelope; no recirculation or load rating is claimed.",
|
|
76
|
+
"Support bearing race dimensions and rolling balls are illustrative and are not a sourced bearing SKU.",
|
|
77
|
+
"Motor bracket window, support screws, coupling/spider and wiper seats use documented example geometry where the catalog does not dimension them.",
|
|
78
|
+
"Threaded holes use nominal diameter cylinders; screws have plain shanks and real hex sockets. Thread geometry and tolerance fits are not modeled.",
|
|
79
|
+
"Motion uses the nominal screw relation 360 degrees per 5 mm; no dynamic/contact or preload simulation is performed.",
|
|
80
|
+
"Colors distinguish components; they do not establish manufacturer materials. No production mass or structural rating is claimed."
|
|
81
|
+
],
|
|
82
|
+
"notIncluded": [
|
|
83
|
+
"optional motor",
|
|
84
|
+
"optional cover/bellows",
|
|
85
|
+
"optional limit switches",
|
|
86
|
+
"proprietary recirculation geometry"
|
|
87
|
+
]
|
|
88
|
+
}
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
# Runnable integration examples
|
|
2
|
+
|
|
3
|
+
This example project installs published `@coloopx/colocad@0.1.0-alpha.3`. It does not depend on a locally compiled kernel. Node.js 22+ and one of the package's supported platforms are required.
|
|
4
|
+
|
|
5
|
+
From the repository root:
|
|
6
|
+
|
|
7
|
+
```sh
|
|
8
|
+
npm ci --prefix examples/integrations --ignore-scripts
|
|
9
|
+
npm test --prefix examples/integrations
|
|
10
|
+
node examples/integrations/sdk.mjs ./out/sdk-example
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
`sdk.mjs` validates a four-hole plate, renders it, changes the camera using its cached mesh, changes the bore diameter and saves the current source. It prints the artifact paths. Its output root can be reused because the SDK creates new revision subdirectories.
|
|
14
|
+
|
|
15
|
+
| File | Purpose |
|
|
16
|
+
| --- | --- |
|
|
17
|
+
| [sdk.mjs](sdk.mjs) | Actual SDK modeling/edit/observation cycle |
|
|
18
|
+
| [pi-tools.mjs](pi-tools.mjs) | Five Pi tools, schema preservation, error mapping and PNG attachment |
|
|
19
|
+
| [pi-core.mjs](pi-core.mjs) | Construct a Pi core agent with a caller-supplied model and stream function |
|
|
20
|
+
| [pi-extension.mjs](pi-extension.mjs) | Register the same tools in Pi coding agent |
|
|
21
|
+
| [integration.test.mjs](integration.test.mjs) | Real native calls and Pi loop/extension/skill discovery regression tests |
|
|
22
|
+
|
|
23
|
+
The test model stream is scripted; no LLM provider or credentials are needed. The test asserts a failed edit reaches the agent as an error and the subsequent corrected call exports STEP. It measures integration correctness, not model intelligence or drawing reconstruction success.
|
|
24
|
+
|
|
25
|
+
Use the [Pi guide](../../docs/integrations/pi.md) to connect real inference. [Codex](../../docs/integrations/codex.md) and [Claude Code](../../docs/integrations/claude-code.md) use the bundled skill and local CLI. These example files live in GitHub and are not part of the existing alpha.3 tarball.
|
|
26
|
+
|
|
27
|
+
## Record history in the source checkout
|
|
28
|
+
|
|
29
|
+
The original SDK tests still pin the published alpha.3 package as a compatibility baseline. The new recorded paths import this checkout's `/session` module and use its native executable.
|
|
30
|
+
|
|
31
|
+
```sh
|
|
32
|
+
node examples/integrations/recorded-pi.mjs ./out/recorded-pi
|
|
33
|
+
node examples/integrations/shell-harness.mjs codex ./out/codex-project
|
|
34
|
+
node examples/integrations/shell-harness.mjs claude-code ./out/claude-project
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
`recorded-pi.mjs` runs an actual Pi tool loop with a scripted stream: build, failed edit, correction, then offline replay. `shell-harness.mjs` installs the complete skill into the corresponding project skill directory and executes its helper and the record/replay CLI. These validate local tool integration, not live Codex/Claude inference. The Pi extension opts into recording when `COLOCAD_SESSION_DIR` is set. SDK callers pass `cadSession` to `createCadAgent`. All code runs in the same sandbox.
|
|
38
|
+
|
|
39
|
+
## Compact feedback and a complete guided workflow (alpha.5)
|
|
40
|
+
|
|
41
|
+
`compact-tools.mjs` preserves the existing schemas and error/degradation semantics while returning measurements, timing and references to full receipts. It is transport-neutral. `guided-workflow.mjs` executes real native modeling, analytic edit checks, failure recovery, cached observation and CLI HTML export. Both files are included in the alpha.5 package.
|
|
42
|
+
|
|
43
|
+
```sh
|
|
44
|
+
node examples/integrations/guided-workflow.mjs ./out/guided-workflow
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Read the [handbook](../../docs/agent-modeling-handbook.md) for materials, tool abstractions, skill structure, prompt examples and tuning. The walkthrough's decisions are scripted; no live-model reconstruction score is claimed.
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
// Transport-neutral adapter: keep full receipts on disk and send a focused result
|
|
2
|
+
// to the model. Host adapters still decide how to attach a PNG and flag errors.
|
|
3
|
+
import {join} from 'node:path';
|
|
4
|
+
import {createSessionTools} from '../../src/session.mjs';
|
|
5
|
+
export function compactReceipt(receipt){
|
|
6
|
+
if(!receipt.ok||!Array.isArray(receipt.data?.features))return structuredClone(receipt);
|
|
7
|
+
const d=receipt.data,features=d.features;
|
|
8
|
+
const artifacts=Object.fromEntries(Object.entries(d.artifact_sha256??{})
|
|
9
|
+
.filter(([name])=>/^(model|preview)\.(json|step|png|mesh\.json|glb|stl)$/.test(name))
|
|
10
|
+
.map(([name,sha256])=>[name,{path:join(d.artifact_directory,name),sha256}]));
|
|
11
|
+
return {ok:true,...(receipt.session_step?{session_step:receipt.session_step}:{}),data:{
|
|
12
|
+
artifact_directory:d.artifact_directory,source_artifact_directory:d.source_artifact_directory,
|
|
13
|
+
model_hash:d.model_hash,source_hash:d.source_hash,geometry:structuredClone(d.geometry),
|
|
14
|
+
timing_ms:structuredClone(d.timing_ms),validation:structuredClone(d.validation),artifacts,
|
|
15
|
+
feature_summary:{count:features.length,reused:features.filter(f=>f.cache_hit).length,
|
|
16
|
+
slowest:[...features].sort((a,b)=>(b.elapsed_ms??0)-(a.elapsed_ms??0)).slice(0,3).map(f=>({id:f.id,elapsed_ms:f.elapsed_ms,cache_hit:f.cache_hit})),
|
|
17
|
+
degradations:features.filter(f=>f.degradation).map(f=>({id:f.id,...structuredClone(f.degradation)}))},
|
|
18
|
+
}};
|
|
19
|
+
}
|
|
20
|
+
export async function createCompactSessionTools(session,{include=['cad_capabilities','cad_validate','cad_build','cad_preview','cad_edit']}={}){
|
|
21
|
+
const tools=await createSessionTools(session),enabled=new Set(include);
|
|
22
|
+
for(const name of enabled)if(!tools.some(t=>t.name===name))throw Error('Unknown CAD tool: '+name);
|
|
23
|
+
return tools.filter(t=>enabled.has(t.name)).map(tool=>({...tool,
|
|
24
|
+
description:tool.description+' Results summarize measurements and timing; full receipts remain in the recorded session. Report every listed degradation.',
|
|
25
|
+
async execute(args){const result=compactReceipt(await tool.execute(args));if(result.session_step)result.receipt_file=join(session.root,'steps',result.session_step,'receipt.json');return result;},
|
|
26
|
+
}));
|
|
27
|
+
}
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
// Executable tool-contract walkthrough; the decision sequence is scripted, not LLM inference.
|
|
2
|
+
import {readFile,writeFile} from 'node:fs/promises';
|
|
3
|
+
import {join,resolve} from 'node:path';
|
|
4
|
+
import {fileURLToPath,pathToFileURL} from 'node:url';
|
|
5
|
+
import {execFile} from 'node:child_process';
|
|
6
|
+
import {promisify} from 'node:util';
|
|
7
|
+
import {ModelingSession} from '../../src/session.mjs';
|
|
8
|
+
import {createCompactSessionTools} from './compact-tools.mjs';
|
|
9
|
+
const exec=promisify(execFile);
|
|
10
|
+
export async function runGuidedWorkflow(directory){
|
|
11
|
+
const root=resolve(directory),session=await ModelingSession.create(join(root,'session'),{title:'Guided workflow: build, check, edit, recover, inspect'});
|
|
12
|
+
const tools=await createCompactSessionTools(session);const calls=[];
|
|
13
|
+
const call=async(name,args)=>{const result=await tools.find(t=>t.name===name).execute(args);calls.push({tool:name,result});return result;};
|
|
14
|
+
const model=JSON.parse(await readFile(new URL('../../skills/colocad/assets/plate-grid.json',import.meta.url)));
|
|
15
|
+
const caps=await call('cad_capabilities',{});if(!caps.ok||!caps.data.operations.includes('face_hole_grid'))throw Error('Required operation unavailable');
|
|
16
|
+
const validation=await call('cad_validate',{model});if(!validation.ok)throw Error(JSON.stringify(validation.error));
|
|
17
|
+
const first=await call('cad_build',{model});if(!first.ok)throw Error(JSON.stringify(first.error));
|
|
18
|
+
const bored=await call('cad_edit',{parameters:{holeDiameter:8}});if(!bored.ok)throw Error(JSON.stringify(bored.error));
|
|
19
|
+
// Quantitative feedback comes from the analytic feature intent, not just the renderer.
|
|
20
|
+
const expectedRemoved=4*Math.PI*(4**2-3**2)*6;
|
|
21
|
+
if(Math.abs(first.data.geometry.volume_mm3-bored.data.geometry.volume_mm3-expectedRemoved)>.01)throw Error('Hole-size edit failed volume check');
|
|
22
|
+
const invalid=await call('cad_edit',{parameters:{nonexistent:1}});if(invalid.ok||invalid.error.code!=='UNKNOWN_PARAMETER')throw Error('Expected visible failed edit');
|
|
23
|
+
const accepted=await session.source();if(accepted.parameters.holeDiameter!==8)throw Error('Failure replaced accepted source');
|
|
24
|
+
const preview=await call('cad_preview',{model:accepted,options:{view:'top'}});if(!preview.ok)throw Error(JSON.stringify(preview.error));
|
|
25
|
+
const longer=await call('cad_edit',{parameters:{length:100}});if(!longer.ok)throw Error(JSON.stringify(longer.error));
|
|
26
|
+
const [lo,hi]=longer.data.geometry.bbox_mm;if(Math.abs(hi[0]-lo[0]-100)>1e-6)throw Error('Length edit did not update the envelope');
|
|
27
|
+
const html=join(root,'review.html');await exec(process.execPath,[fileURLToPath(new URL('../../bin/colocad.mjs',import.meta.url)),'replay',session.root,html]);
|
|
28
|
+
const result={scope:'Scripted tool-contract workflow, not a live model evaluation',passed:true,html,steps:(await session.read()).steps.length,calls,measurements:{holeEditRemovedMm3:expectedRemoved,finalLengthMm:hi[0]-lo[0]}};
|
|
29
|
+
await writeFile(join(root,'workflow.json'),JSON.stringify(result,null,2)+'\n');return result;
|
|
30
|
+
}
|
|
31
|
+
if(process.argv[1]&&import.meta.url===pathToFileURL(process.argv[1]).href){const r=await runGuidedWorkflow(process.argv[2]??'./out/guided-workflow');console.log(JSON.stringify({passed:r.passed,scope:r.scope,steps:r.steps,html:r.html,measurements:r.measurements}));}
|
|
@@ -1,4 +1,4 @@
|
|
|
1
1
|
[diffend] Oversized file quarantined before diffing.
|
|
2
2
|
name: package/kernel/native/darwin-arm64/agent-cad
|
|
3
3
|
size: 35996736 bytes
|
|
4
|
-
sha256:
|
|
4
|
+
sha256: e3cbc7abf95cc0911e5e9a1dae565c52e7bafe927f5bf7a42901aa9a48f2bca9
|
|
@@ -1,4 +1,4 @@
|
|
|
1
1
|
[diffend] Oversized file quarantined before diffing.
|
|
2
2
|
name: package/kernel/native/linux-arm64/agent-cad
|
|
3
3
|
size: 35525448 bytes
|
|
4
|
-
sha256:
|
|
4
|
+
sha256: 9e2e965f2e136d2fe31009738be8c42e98b39ccccf838c6f22b07d7ead39e714
|
|
@@ -1,4 +1,4 @@
|
|
|
1
1
|
[diffend] Oversized file quarantined before diffing.
|
|
2
2
|
name: package/kernel/native/linux-x64/agent-cad
|
|
3
|
-
size:
|
|
4
|
-
sha256:
|
|
3
|
+
size: 46383744 bytes
|
|
4
|
+
sha256: 33031163011d5fb73f12366362f74cdb72115e452c66116e5a53bb433eb1779e
|
package/kernel/release.json
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
|
-
"version": "0.1.0-alpha.
|
|
2
|
+
"version": "0.1.0-alpha.5",
|
|
3
3
|
"sha256": {
|
|
4
|
-
"
|
|
5
|
-
"linux-
|
|
6
|
-
"
|
|
4
|
+
"darwin-arm64": "e3cbc7abf95cc0911e5e9a1dae565c52e7bafe927f5bf7a42901aa9a48f2bca9",
|
|
5
|
+
"linux-arm64": "9e2e965f2e136d2fe31009738be8c42e98b39ccccf838c6f22b07d7ead39e714",
|
|
6
|
+
"linux-x64": "33031163011d5fb73f12366362f74cdb72115e452c66116e5a53bb433eb1779e"
|
|
7
7
|
}
|
|
8
8
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@coloopx/colocad",
|
|
3
|
-
"version": "0.1.0-alpha.
|
|
3
|
+
"version": "0.1.0-alpha.5",
|
|
4
4
|
"description": "Parametric feature instructions, a local Rust B-rep kernel and an experimental SolidWorks author",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
@@ -26,7 +26,15 @@
|
|
|
26
26
|
"types": "./kernel/dist/index.d.ts",
|
|
27
27
|
"import": "./kernel/dist/index.js"
|
|
28
28
|
},
|
|
29
|
-
"./schema": "./kernel/schemas/model.schema.json"
|
|
29
|
+
"./schema": "./kernel/schemas/model.schema.json",
|
|
30
|
+
"./session": {
|
|
31
|
+
"types": "./src/session.d.mts",
|
|
32
|
+
"import": "./src/session.mjs"
|
|
33
|
+
},
|
|
34
|
+
"./viewer": {
|
|
35
|
+
"types": "./viewer/index.d.ts",
|
|
36
|
+
"import": "./viewer/dist/index.js"
|
|
37
|
+
}
|
|
30
38
|
},
|
|
31
39
|
"bin": {
|
|
32
40
|
"colocad": "bin/colocad.mjs"
|
|
@@ -47,15 +55,43 @@
|
|
|
47
55
|
"skills/colocad",
|
|
48
56
|
"kernel/release.json",
|
|
49
57
|
"scripts/check-release.mjs",
|
|
50
|
-
"README.zh-CN.md"
|
|
58
|
+
"README.zh-CN.md",
|
|
59
|
+
"viewer/dist",
|
|
60
|
+
"viewer/index.d.ts",
|
|
61
|
+
"viewer/THREE-LICENSE",
|
|
62
|
+
"examples/hiwin-kk60/model.mjs",
|
|
63
|
+
"examples/hiwin-kk60/run.mjs",
|
|
64
|
+
"examples/hiwin-kk60/README.md",
|
|
65
|
+
"examples/hiwin-kk60/sources.json",
|
|
66
|
+
"examples/integrations/compact-tools.mjs",
|
|
67
|
+
"examples/integrations/guided-workflow.mjs",
|
|
68
|
+
"docs/*.md",
|
|
69
|
+
"docs/integrations/*.md"
|
|
51
70
|
],
|
|
52
71
|
"scripts": {
|
|
53
72
|
"test": "node --test test/*.test.mjs",
|
|
54
73
|
"build:kernel": "node scripts/build-kernel.mjs",
|
|
55
|
-
"prepack": "node scripts/check-release.mjs"
|
|
74
|
+
"prepack": "node scripts/check-release.mjs",
|
|
75
|
+
"build:viewer": "node scripts/build-viewer.mjs",
|
|
76
|
+
"test:viewer": "node test/viewer.browser.mjs",
|
|
77
|
+
"test:integrations": "npm test --prefix examples/integrations",
|
|
78
|
+
"test:render": "node test/render.browser.mjs"
|
|
56
79
|
},
|
|
57
80
|
"publishConfig": {
|
|
58
81
|
"access": "public",
|
|
59
82
|
"registry": "https://registry.npmjs.org"
|
|
83
|
+
},
|
|
84
|
+
"devDependencies": {
|
|
85
|
+
"esbuild": "0.28.2",
|
|
86
|
+
"playwright": "1.65.0",
|
|
87
|
+
"three": "0.187.0"
|
|
88
|
+
},
|
|
89
|
+
"peerDependencies": {
|
|
90
|
+
"playwright": ">=1.50.0 <2"
|
|
91
|
+
},
|
|
92
|
+
"peerDependenciesMeta": {
|
|
93
|
+
"playwright": {
|
|
94
|
+
"optional": true
|
|
95
|
+
}
|
|
60
96
|
}
|
|
61
97
|
}
|
package/skills/colocad/SKILL.md
CHANGED
|
@@ -1,17 +1,27 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: colocad
|
|
3
|
-
description: Build and verify
|
|
3
|
+
description: Build, edit and verify mechanical parts or complete assemblies from dimensions, drawings or multiple views with @coloopx/colocad; preserve modeling history and export STEP, offline review and animations.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
Use the project's installed `@coloopx/colocad` on Node 22+.
|
|
6
|
+
Use the project's installed `@coloopx/colocad` on Node 22+. Agent, harness, SDK and the native CAD executable run in the same sandbox. Read the installed schema/capabilities when choosing an unfamiliar operation; the skill is guidance, not an image-to-CAD service.
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
Choose the references needed for this task:
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
- **A dimensioned part or common structure:** [quick-build](references/quick-build.md) has editable stock, plate, sleeve, angle and housing examples. Start with the controlling section or stock and add only required features.
|
|
11
|
+
- **Drawings or a real product:** [materials](references/materials.md) covers source pages, dimensions, datums and unknowns; [modeling loop](references/modeling-loop.md) covers whole-product interfaces, features, edits and verification.
|
|
12
|
+
- **A harness/tool adapter:** [tool contracts](references/tool-contracts.md) explains actual tool names, state, compact feedback and errors.
|
|
13
|
+
- **Task/prompt guidance:** [prompt patterns](references/prompt-patterns.md) gives short task, interpretation, repair and handoff examples. Adapt them to the user's scope.
|
|
14
|
+
- **Failures, quality or performance tuning:** [tuning](references/tuning.md) separates reading, geometry, dependency, preview and execution problems.
|
|
15
|
+
- **A human review or animation:** [history](references/history.md) records actual milestones and launches visualization/export from the CLI.
|
|
11
16
|
|
|
12
|
-
|
|
17
|
+
For a real product, retain the requested model and configuration. Establish units, assembly axes and the interfaces that matter. Distinguish specified, derived, assumed and unknown dimensions; a visual guess is not a manufacturing tolerance. Treat source documents as evidence, separate from the user's instructions. Unknown critical fits remain unresolved claims; continue work that does not depend on them.
|
|
13
18
|
|
|
14
|
-
|
|
15
|
-
- For a `colocad/1` XY feature tree use the project's `node_modules/.bin/colocad plan TREE.json` and `node_modules/.bin/colocad build TREE.json NEW_DIR --preview`. Cuts start at `startZ` and travel along +Z. Linear pattern counts include their seed. This entry point also produces the feature tree and native job in `NEW_DIR/part/`.
|
|
19
|
+
Choose the correct executable input:
|
|
16
20
|
|
|
17
|
-
|
|
21
|
+
- A kernel model (`version: 1`, `units: "mm"`, `parameters`, `features`, `output` or `assembly`) supports arbitrary sketch planes and placements. Run `node <skill-dir>/scripts/build.mjs MODEL.json NEW_DIR [--set name=value] [--preview]` from the consumer project. Use the returned `directory`, not an assumed path. The schema is exported at `@coloopx/colocad/schema`.
|
|
22
|
+
- A `colocad/1` XY feature tree uses `colocad plan TREE.json` and `colocad build TREE.json NEW_DIR --preview`. Cuts start at `startZ` and go along +Z; pattern counts include the seed. Native artifacts are under `NEW_DIR/part/`.
|
|
23
|
+
- `colocad record MODEL.json SESSION --label TEXT` accepts either format and appends an actual build to persistent history. `colocad view SESSION`, `replay SESSION review.html` and `render SESSION modeling.mp4` provide human review. Movies require optional Chromium/FFmpeg.
|
|
24
|
+
|
|
25
|
+
Build a meaningful feature or interface milestone, inspect its receipt and the relevant projection, then accept or repair it. Stable semantic IDs and parameter relationships should survive edits. Reuse definitions for repeated parts. `cad_validate` is preflight, not proof of geometry or dimensional correctness. On failure, use the feature ID and a quantitative check to make a targeted change; retain the failed attempt. Explicit degradations remain part of the result.
|
|
26
|
+
|
|
27
|
+
Deliver editable source and exact STEP with the requested review artifacts. Check the dimensions/holes/clearances that distinguish success, and independently reopen significant STEP deliveries when a verifier is available. Say which checks ran. Rendering establishes appearance; fit, motion, editability and manufacturing claims require their own evidence.
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
{
|
|
2
|
+
"purpose": "Evidence handoff example; this is not executable kernel model JSON",
|
|
3
|
+
"product": {"manufacturer":"HIWIN","series":"KK60 standard","configuration":"5 mm lead / 300 mm rail / one A block / open / no motor or switches"},
|
|
4
|
+
"units":"mm",
|
|
5
|
+
"frame":{"x":"width","y":"vertical","z":"travel","overallZ":[0,370]},
|
|
6
|
+
"sources":[{"id":"hiwin-catalog","url":"https://hiwin.com/wp-content/uploads/2026/08/HIWIN-Ballscrew-Driven-Stages-Catalog-1.pdf","revision":"K99TE16-1906","pdfPage":25,"printedPage":22,"views":["SECTION A-A","VIEW B","top","side"]}],
|
|
7
|
+
"dimensions":[
|
|
8
|
+
{"id":"railLength","value":300,"state":"specified","source":"hiwin-catalog","locator":"length table, 300 mm row"},
|
|
9
|
+
{"id":"screwAxisHeight","value":23,"state":"specified","source":"hiwin-catalog","locator":"SECTION A-A"},
|
|
10
|
+
{"id":"carriageHeight","value":33,"state":"specified","source":"hiwin-catalog","locator":"SECTION A-A"},
|
|
11
|
+
{"id":"stroke","value":210,"state":"specified","source":"hiwin-catalog","locator":"length table, A1 column"},
|
|
12
|
+
{"id":"midStrokeZ","value":157,"state":"derived","relation":"rail origin 7 + railLength / 2"},
|
|
13
|
+
{"id":"guideBallRadius","value":1.5,"state":"assumed","reason":"Catalog does not dimension rolling elements; reconstruction only"},
|
|
14
|
+
{"id":"nutRecirculationPath","value":null,"state":"unknown","affects":["OEM internal geometry","functional ball circulation"]}
|
|
15
|
+
],
|
|
16
|
+
"interfaces":[{"id":"carriage-to-rail","datums":["travel axis Z","rail bottom Y=0"],"checks":["carriage height 33","rail/carriage overlap at travel -105,0,105"]}],
|
|
17
|
+
"acceptance":[{"quantity":"screwAxisHeight","expected":23,"numericCheckTolerance":0.01,"note":"Reconstruction check threshold, not a manufacturer tolerance"}],
|
|
18
|
+
"delivery":["editable model","whole-product STEP","recorded session","CLI-exported offline HTML","requested animation"],
|
|
19
|
+
"claimScope":"Catalog interfaces and documented reconstruction; no manufacturing or recirculation certification"
|
|
20
|
+
}
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# Persistent modeling history
|
|
2
|
+
|
|
3
|
+
Use this workflow when the user wants to inspect construction steps or hand off an offline replay. It requires a colocad build that lists `record` and `replay` in `colocad --help`; the older npm alpha.3 CLI does not include these commands.
|
|
4
|
+
|
|
5
|
+
Save each meaningful geometry or assembly milestone as JSON, then run from the project:
|
|
6
|
+
|
|
7
|
+
```sh
|
|
8
|
+
./node_modules/.bin/colocad record model.json ./history --label "Bore the hub"
|
|
9
|
+
./node_modules/.bin/colocad view ./history
|
|
10
|
+
./node_modules/.bin/colocad replay ./history ./history.html
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
`record` accepts a kernel model or a `colocad/1` feature tree, appends a real build with a preview, and prints the receipt. Reuse the session directory for later attempts. A failed build exits nonzero and stays in history. Change the cause, then record a corrected attempt; do not delete the failed step to imply uninterrupted success.
|
|
14
|
+
|
|
15
|
+
Choose steps that explain geometry: blank → bore/cut → shaped blade → repeated placements → full assembly. Avoid recording only final part placement if the user asked how the kernel constructed the shape. A milestone is an actual build call; internal feature timings remain in the receipt.
|
|
16
|
+
|
|
17
|
+
The HTML is self-contained and includes orbit/view controls, display-only clipping/explosion, the inputs and receipts, and the final exact STEP. Review playback uses a presentation cadence; recorded call durations are shown separately. Preserve the entire session directory if every intermediate STEP must remain available. A camera change or clipping plane does not modify the saved exact model.
|
|
18
|
+
|
|
19
|
+
For a modeling animation use the same CLI: `colocad render SESSION ./modeling.mp4` (or `.gif`). This requires optional Playwright/Chromium and FFmpeg. It replays actual persisted geometry in four views, preserving measured call times. Review pacing, cutaway and explosion are presentation only. Do not present the film duration as build time or a benchmark.
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# Prepare evidence for a mechanical model
|
|
2
|
+
|
|
3
|
+
Use for a drawing-based part or a specific product. A small dimensioned stock part does not need a large evidence bundle.
|
|
4
|
+
|
|
5
|
+
## Identify the target and the source
|
|
6
|
+
|
|
7
|
+
Record the manufacturer/model, variant, optional equipment, units and requested fidelity. An entire actuator is the target; its drawings and BOM describe that target. Do not silently replace it with a generic assembly or a simpler test piece.
|
|
8
|
+
|
|
9
|
+
Keep an original source URL/file, revision/date, PDF page and checksum when reproducibility matters. Preserve the full page as context, then provide readable detail crops with the view name and crop location. Text extraction helps find dimensions; the rendered page establishes which extension lines, section or component a number belongs to. Do not crop away the datum or section identifier needed to interpret it.
|
|
10
|
+
|
|
11
|
+
A useful source order is: explicit drawing dimensions and notes, tables for the exact variant, dimensioned sections, then calibrated geometry measurements. A photograph or uncalibrated render supports shape interpretation, not exact dimensions. More views can resolve correspondence but cannot expose every hidden passage or tolerance.
|
|
12
|
+
|
|
13
|
+
For a PDF, existing Poppler tools can prepare the evidence:
|
|
14
|
+
|
|
15
|
+
```sh
|
|
16
|
+
pdftotext -layout catalog.pdf catalog.txt
|
|
17
|
+
pdftoppm -f 25 -singlefile -scale-to 2400 -png catalog.pdf page-25
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
These are material-preparation tools, not requirements of the CAD runtime. Do not add Python/PDF tooling to the modeling sandbox unless the task needs it.
|
|
21
|
+
|
|
22
|
+
## Separate evidence states
|
|
23
|
+
|
|
24
|
+
| State | Record | Example |
|
|
25
|
+
| --- | --- | --- |
|
|
26
|
+
| Specified | Value, unit, source/page/view/annotation | KK60 screw axis height 23 mm, SECTION A-A |
|
|
27
|
+
| Derived | Formula and referenced dimensions | Hole stations from rail end and G/pitch |
|
|
28
|
+
| Assumed | Value/range, reason and affected claims | Unpublished bearing race dimensions |
|
|
29
|
+
| Unknown | Missing quantity and what it prevents checking | Proprietary ball-recirculation path |
|
|
30
|
+
|
|
31
|
+
Write one shared coordinate convention and the local frame of each part. Name which view corresponds to +/−X, Y or Z; orthographic, perspective and section views are different evidence. Check diameter vs radius, through vs blind, depth origin, units, and normal vs special-order blocks before generating cutters.
|
|
32
|
+
|
|
33
|
+
Keep manufacturing tolerance and reconstruction acceptance tolerance separate. A 0.01 mm numerical check chosen for your model is not a 0.01 mm manufacturer tolerance. For image-derived dimensions, record calibration and uncertainty. If uncertainty prevents a required interface from being checked, request that specific missing fact while continuing independent parts.
|
|
34
|
+
|
|
35
|
+
## Minimal handoff to the modeling stage
|
|
36
|
+
|
|
37
|
+
Provide the selected source pages/crops, dimension table, coordinate frame, interface list, assumptions and acceptance checks. [The product brief](../assets/product-brief.example.json) is a filled example of this evidence convention, not a new executable kernel schema. Do not put its provenance fields into a kernel model with `additionalProperties: false`.
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# Whole-product modeling loop
|
|
2
|
+
|
|
3
|
+
Read for assemblies, drawing reconstruction or edits whose dependencies matter.
|
|
4
|
+
|
|
5
|
+
## From product evidence to an executable model
|
|
6
|
+
|
|
7
|
+
1. Establish the assembly envelope, primary axes and interface datums. Identify unique part definitions and repeated occurrences. Attach an acceptance check to the interfaces that matter to the request.
|
|
8
|
+
2. Select the controlling cross-section or stock for each unique part. Use extrude/revolve for prismatic/turned structure; cut real bores and cavities; use loft/sweep when geometry requires it. A rotated or copied solid is an assembly occurrence, not a new manufactured part definition.
|
|
9
|
+
3. Preserve relationships in parameters/expressions. Examples: a centered hole pattern follows width edits; the nut's translation and screw rotation share the lead relation. Assign meaningful, stable feature/part IDs. Do not rely on an incidental edge number surviving a Boolean or parameter edit.
|
|
10
|
+
4. Validate the JSON and declared budgets, then build a meaningful milestone. Read `ok`, geometry, timings and degradations; inspect a projection or section aimed at the changed feature. A small subassembly can resolve an interface before an expensive complete build.
|
|
11
|
+
5. Compare a quantitative result with the target. Correct the interpretation, feature or parameter that caused the error. Preserve the last accepted model and the failed attempt; changing unrelated dimensions obscures the cause.
|
|
12
|
+
6. Assemble and check the whole selected configuration. Reopen STEP independently for significant delivery. Test at least the edits or poses required by the request, keeping paired interfaces consistent. Persist the session and launch `view/replay/render` from the CLI for human review.
|
|
13
|
+
|
|
14
|
+
This is an adaptive loop, not a mandatory approval gate between every feature. Use fewer milestones for a simple part. For a long product, keep checkpoints that explain both shape construction and assembly.
|
|
15
|
+
|
|
16
|
+
## Match evidence to the claim
|
|
17
|
+
|
|
18
|
+
| Claim | A useful check |
|
|
19
|
+
| --- | --- |
|
|
20
|
+
| Outer size | Exact STEP/B-rep bounding dimensions against the drawing |
|
|
21
|
+
| Hole/cavity | Axis, radius/depth and material probes inside/outside; a rendered circle is insufficient |
|
|
22
|
+
| Assembly fit | Common axes and exact interference/clearance for the relevant pairs |
|
|
23
|
+
| Motion | Rebuilt required poses and the coupling relation; an exploded-view animation is not motion validation |
|
|
24
|
+
| Editable design intent | Perturb a meaningful parameter and recheck dependent geometry/interfaces |
|
|
25
|
+
| Manufacturing-ready | Required dimensions, tolerances, materials, processes and functional validation; do not infer these from a catalog render |
|
|
26
|
+
|
|
27
|
+
Negative material checks matter: verify that a supposed opening is empty and adjacent stock remains. A global volume can match despite a misplaced hole. Avoid probing exactly on an edge or boundary when testing inside/outside classification.
|
|
28
|
+
|
|
29
|
+
## State that survives a long session
|
|
30
|
+
|
|
31
|
+
Keep source IDs and coordinate conventions, accepted model path/hash, exposed parameters, interface checks, latest receipt, unresolved assumptions, and the next targeted test. Reload the current accepted source after a failure or context reset. In `ModelingSession`, recorded `cad_edit` takes only `{parameters}` and uses that accepted source.
|
|
32
|
+
|
|
33
|
+
The KK60 example illustrates this process. Enlarging the manufacturer's section corrected the screw axis to 23 mm; the real helical B-rep exposed an internal STEP budget defect; independent material probes and rail/carriage checks established specific geometry claims. Its undisclosed nut recirculation remains unmodeled. Do not reuse its assumed internal dimensions as a universal actuator design.
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# Prompt patterns for agent CAD work
|
|
2
|
+
|
|
3
|
+
These are adaptable examples, not an instruction to force every task through every stage. Keep the user's product and intended delivery. Separate the task from quoted source evidence. Ask for concise decisions, dimensions and checks rather than a hidden chain of thought.
|
|
4
|
+
|
|
5
|
+
## Product brief
|
|
6
|
+
|
|
7
|
+
```text
|
|
8
|
+
Use the colocad skill to reconstruct the specified whole product/configuration.
|
|
9
|
+
Input evidence: the listed manufacturer pages, drawings, tables and views.
|
|
10
|
+
Target: editable source + exact STEP + recorded modeling session + CLI HTML review.
|
|
11
|
+
Record units, coordinate datums, required interfaces and which dimensions are
|
|
12
|
+
specified, derived, assumed or unknown. Prioritize the interfaces and details
|
|
13
|
+
needed for this task. Keep unknown internals explicit; do not substitute a generic
|
|
14
|
+
product. Continue independent work if one critical detail is missing.
|
|
15
|
+
For each meaningful milestone, build, inspect the relevant view/section and report
|
|
16
|
+
measured deviations. Preserve failed attempts. Export the requested movie through
|
|
17
|
+
colocad render, with recorded call time separate from playback duration.
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
## Interpret only the evidence needed now
|
|
21
|
+
|
|
22
|
+
```text
|
|
23
|
+
Interpret the supplied overall view and SECTION A-A for the carriage/screw interface.
|
|
24
|
+
Return a compact dimension table: quantity, value/unit, evidence state, page/view,
|
|
25
|
+
reference datum and uncertainty. Match extension lines to their dimensions.
|
|
26
|
+
List conflicting or missing interface values. Do not infer a hidden tolerance from
|
|
27
|
+
pixel size. Then identify the local frames and checks needed to model this interface.
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## Plan one modeling milestone
|
|
31
|
+
|
|
32
|
+
```text
|
|
33
|
+
Using the accepted dimensions and assembly datums, produce the next feature graph.
|
|
34
|
+
Name features and repeated part definitions semantically. Express dependent sizes
|
|
35
|
+
and placements in parameters. Identify the check that will distinguish a correct
|
|
36
|
+
result from a plausible-looking one. Use only installed supported operations.
|
|
37
|
+
Validate, build and inspect the result; retain the executable JSON and receipt.
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
## Repair from specific feedback
|
|
41
|
+
|
|
42
|
+
```text
|
|
43
|
+
The accepted revision is the recorded source at the given path/hash.
|
|
44
|
+
The attempted change failed at the supplied feature ID with this error/measurement.
|
|
45
|
+
Inspect that feature, its operands and local frame. Make a targeted correction;
|
|
46
|
+
keep required geometry and dimensional intent. Re-run the affected check before
|
|
47
|
+
accepting. If an optional treatment is explicitly omitted, retain its degradation
|
|
48
|
+
record and say which claim is weakened.
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## Check editability or product fit
|
|
52
|
+
|
|
53
|
+
```text
|
|
54
|
+
Test the requested dimension change/pose in the actual CAD model. Recheck the
|
|
55
|
+
specified dependent interfaces, hole placement and envelope. Report numerical
|
|
56
|
+
results and the source of each target. Render comparison views, then independently
|
|
57
|
+
read back STEP when available. Distinguish untested pairs and unknown internals
|
|
58
|
+
from passed checks; do not use appearance alone as evidence of fit.
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## Handoff after a long run
|
|
62
|
+
|
|
63
|
+
```text
|
|
64
|
+
Persist: product/configuration; source identifiers; units and datums; accepted
|
|
65
|
+
model path/hash; session path/latest step; parameters and dependency decisions;
|
|
66
|
+
passed checks with values; failed attempts; unresolved assumptions; next targeted
|
|
67
|
+
check. Keep large meshes and receipts as file references rather than inline text.
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
For performance requests, additionally specify the same input/geometry, output requirements, cold or warm start, preview precision, hardware/container limits and measurement window. Never reuse a construction movie's edited duration as a benchmark.
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# Tool contracts for a local CAD harness
|
|
2
|
+
|
|
3
|
+
The existing harness owns inference, permissions, output locations and artifact retention. Bind SDK functions to that harness; do not introduce a CAD service or remote scheduling layer for this package. The agent supplies geometry inputs, not arbitrary executable paths or process flags.
|
|
4
|
+
|
|
5
|
+
## Expose tools at the useful level
|
|
6
|
+
|
|
7
|
+
Start with the five tools used by the executable Pi adapter; enable sketch solving or STEP inspection when that workflow needs them. Keep the SDK's schema and `$defs` intact instead of rewriting an approximate subset.
|
|
8
|
+
|
|
9
|
+
| Existing tool | Meaning | Important boundary |
|
|
10
|
+
| --- | --- | --- |
|
|
11
|
+
| `cad_capabilities` | Read operations, limits and unsupported cases | Installed version is authoritative |
|
|
12
|
+
| `cad_validate` | Check input/parameters/dependencies/budgets | Does not build or validate the resulting shape |
|
|
13
|
+
| `cad_build` | Execute an explicit model and return exact artifacts | Creates a new revision; inspect errors/degradations |
|
|
14
|
+
| `cad_preview` | Produce a view, reusing eligible saved mesh | Geometry, pose or precision changes can require work |
|
|
15
|
+
| `cad_edit` | Rebuild changed named parameters | Plain tools take `{model,parameters}`; recorded tools take `{parameters}` |
|
|
16
|
+
| `cad_solve_sketch` | Local sketch constraints/residuals/DOF | Local solution/rank is not proof of global uniqueness |
|
|
17
|
+
| `cad_inspect_step` | Inspect a registered STEP asset and its instances | Import budgets and supported representations apply |
|
|
18
|
+
|
|
19
|
+
The current API does not provide `image_to_cad`, an automatic drawing-dimension extractor, or a universal exact measurement tool in this tool set. Use the harness's file/image tools for evidence and an appropriate independent geometry verifier for checks. The SDK's `inspect` reads a report; it is not an arbitrary geometric query engine.
|
|
20
|
+
|
|
21
|
+
## Keep feedback focused and inspectable
|
|
22
|
+
|
|
23
|
+
A useful response includes `ok`, the failing feature/code/message, revision and artifact paths/hashes, solid count, bounds/volume, relevant measurements, timings, cache reuse and every degradation. Keep full feature traces and source files on disk. Return relevant details or a PNG when they change the next decision; do not send STEP text, complete meshes or every intermediate image back to the model.
|
|
24
|
+
|
|
25
|
+
The repository's `examples/integrations/compact-tools.mjs` wraps `createSessionTools` without changing tool schemas or error meaning. It retains full receipts, returns a compact feature summary and points to the original receipt. `guided-workflow.mjs` exercises real builds, dimension edits, an invalid edit, recovery, cached observation and CLI HTML export. The sequence is scripted; it is not an LLM success-rate evaluation.
|
|
26
|
+
|
|
27
|
+
For a provider that expects an error flag or thrown error, map `ok:false` into that provider's tool-error convention. Preserve the structured detail so the agent can repair the exact cause. A successful transport call is not automatically a successful CAD operation. An `on_fail:record` result still contains omissions and cannot satisfy a required omitted feature.
|
|
28
|
+
|
|
29
|
+
## Reuse and persistence
|
|
30
|
+
|
|
31
|
+
Use one client/session for sequential revisions of one modeling task. Separate independent tasks' output roots. A session stores accepted inputs and failed attempts; archive its directory before the sandbox expires. `preview` can reuse a checked mesh; observation-only artifacts may point to `source_artifact_directory` for the exact STEP. Avoid overlapping writes to one session.
|
|
32
|
+
|
|
33
|
+
Prefer a small semantic set of SDK tools over an RPC endpoint per primitive. Repeated geometry can be generated in a program/feature graph and sent in a meaningful build. Keep enough milestones to inspect geometry creation, not just the final assembly.
|