@coloopx/colocad 0.1.0-alpha.4 → 0.1.0-alpha.6
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/README.md +133 -99
- package/README.zh-CN.md +145 -79
- package/docs/README.md +7 -4
- package/docs/README.zh-CN.md +9 -3
- 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-workflow.zh-CN.md +77 -0
- package/docs/native-solidworks.md +12 -0
- package/docs/performance.md +62 -0
- package/docs/troubleshooting.md +25 -0
- package/docs/validation.md +23 -0
- package/examples/hiwin-kk60/README.md +1 -1
- 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/release.json +1 -1
- package/package.json +5 -2
- package/skills/colocad/SKILL.md +17 -9
- package/skills/colocad/assets/product-brief.example.json +20 -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
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
# Integrate with an existing harness
|
|
2
|
+
|
|
3
|
+
Keep the agent, harness, SDK and native CAD process in the **same sandbox**. Install colocad in the sandbox image or project dependency layer. Bind it to the harness's existing tool execution and artifact storage.
|
|
4
|
+
|
|
5
|
+
```mermaid
|
|
6
|
+
flowchart LR
|
|
7
|
+
subgraph Sandbox[One sandbox]
|
|
8
|
+
A[Agent + existing harness] --> B[Skill + shell tools]
|
|
9
|
+
A --> C[Typed CAD tools]
|
|
10
|
+
B --> D[Local SDK]
|
|
11
|
+
C --> D
|
|
12
|
+
D --> E[Rust child process]
|
|
13
|
+
E --> F[Revision files]
|
|
14
|
+
F --> A
|
|
15
|
+
end
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
| Harness | Recommended first route | Optional route |
|
|
19
|
+
| --- | --- | --- |
|
|
20
|
+
| Codex | Project skill + existing shell/image tools | Host-provided tool bridge |
|
|
21
|
+
| Claude Code | Project skill + existing Bash/Read tools | Host-provided MCP adapter |
|
|
22
|
+
| Pi coding agent | Project skill or explicit `--skill` | Local extension registering CAD tools |
|
|
23
|
+
| Pi agent core / custom TypeScript harness | `createCadTools` through a thin adapter | Existing shell tool + loaded skill instructions |
|
|
24
|
+
|
|
25
|
+
An MCP transport is optional integration code, not a shipped colocad server. A skill supplies workflow guidance; it does not grant filesystem access, install Node, or register typed tools by itself.
|
|
26
|
+
|
|
27
|
+
## Session lifecycle
|
|
28
|
+
|
|
29
|
+
1. Allocate a session output root from trusted harness state. Load the pinned package and skill once; record package and native versions.
|
|
30
|
+
2. Parse the task into dimensions, datum, constraints and explicit assumptions. Pick a kernel model or a feature tree deliberately.
|
|
31
|
+
3. Preflight the source, then build a geometry revision. Return failures with their feature ID so the agent can correct the relevant feature.
|
|
32
|
+
4. Inspect the result: geometry counts/bounds/volume, requested views and any internal regions. Persist the accepted source and receipt before moving to the next edit.
|
|
33
|
+
5. Return artifact references through the harness's existing attachment system. Upload or copy the source, STEP, receipt and useful previews before the sandbox is destroyed.
|
|
34
|
+
|
|
35
|
+
With typed tools, allocate one `CadClient` for each sequential modeling session. Do not share its mutable revision/cache state across unrelated concurrent sessions. Schedule independent jobs with separate clients and output roots, and cap concurrency according to actual sandbox memory. The Pi sample deliberately serializes modeling calls.
|
|
36
|
+
|
|
37
|
+
With shell tools, use argument arrays in a process API rather than interpolating model text into shell commands. Store JSON in a file. Agent-controlled dimensions belong in model input; executable paths, output roots and credentials belong to harness configuration. Keep normal harness permissions in force.
|
|
38
|
+
|
|
39
|
+
## Results and failures
|
|
40
|
+
|
|
41
|
+
A useful tool result includes the artifact directory, counts/bounds/volume, validation summary and timings. Keep detailed feature diagnostics in the full receipt and attach a PNG for visual inspection. A path in text is not itself an image input to a remote vision model. The [Pi adapter](../../examples/integrations/pi-tools.mjs) shows text/image content and full `details` together.
|
|
42
|
+
|
|
43
|
+
`cad_validate` success is only preflight. A nonzero child exit, a failed receipt or an explicit degraded feature must remain visible. Do not turn a failed build into a success containing an empty output path. Do not retry the same invalid geometry indefinitely; change the failing feature or report the unresolved constraint.
|
|
44
|
+
|
|
45
|
+
The `on_fail` record policy is an explicit degraded-model choice, not a general recovery default. Its object includes `kind: "record"`, a reason, omitted details and affected requirements. Check recorded degradations before accepting a revision; the Pi adapter includes these in model-visible text. Preserve the original exact model when using a simplified display/envelope representation.
|
|
46
|
+
|
|
47
|
+
## Resource and storage policy
|
|
48
|
+
|
|
49
|
+
Start with the default 30-second call budget and one active native operation. Increase the budget for a measured workload; do not infer a universal 512 MiB allowance from one benchmark. Account for agent runtime, Node, native descendants, previews and file cache in a real sandbox measurement.
|
|
50
|
+
|
|
51
|
+
For multiple camera angles, use the same client or `observeArtifact`. For repeated parts, reuse a part definition and place occurrences. Keep cache/source revisions while referenced; artifact cleanup is a host policy and must not delete a live observation's source STEP.
|
|
52
|
+
|
|
53
|
+
Use [Pi](pi.md), [Claude Code](claude-code.md) or [Codex](codex.md) for concrete setup. [Best practices](../best-practices.md) covers modeling and performance choices.
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
# Pi agent core and Pi coding agent
|
|
2
|
+
|
|
3
|
+
The adapter is tested with `@earendil-works/pi-agent-core@1.5.0` and `@earendil-works/pi-coding-agent@1.5.0`. Pi APIs have changed across releases: pin the versions in your harness and run the adapter tests before upgrading. Older harnesses can use the skill/CLI route without replacing their agent core.
|
|
4
|
+
|
|
5
|
+
## Pi agent core: register local tools
|
|
6
|
+
|
|
7
|
+
Clone the example project and install its lockfile:
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
git clone https://github.com/Coloopx/colocad.git
|
|
11
|
+
cd colocad/examples/integrations
|
|
12
|
+
npm ci --ignore-scripts
|
|
13
|
+
npm test
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
[pi-tools.mjs](../../examples/integrations/pi-tools.mjs) adapts colocad's JSON Schemas and receipts to Pi `AgentTool`s. [pi-core.mjs](../../examples/integrations/pi-core.mjs) constructs an agent with these tools. Your harness supplies its existing model, stream function and authentication:
|
|
17
|
+
|
|
18
|
+
```js
|
|
19
|
+
import { createCadAgent } from './pi-core.mjs';
|
|
20
|
+
|
|
21
|
+
// model, streamFn and getApiKey come from your existing harness configuration.
|
|
22
|
+
const agent = await createCadAgent({
|
|
23
|
+
model, streamFn, getApiKey,
|
|
24
|
+
outputRoot: '/workspace/cad-output/session-001',
|
|
25
|
+
});
|
|
26
|
+
await agent.prompt('Build an 80 × 50 × 6 mm mounting plate with four Ø6 holes. '
|
|
27
|
+
+ 'Use a centered 2 × 2 grid at 50 × 30 mm pitch. Export STEP and inspect a preview.');
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
This is a host wiring fragment, not a standalone provider login script. Pi core 1.5 requires a `streamFn`. For an existing agent, merge the returned tools into its tools array while idle, retaining your existing tools and context policies:
|
|
31
|
+
|
|
32
|
+
```js
|
|
33
|
+
import { createPiCadTools } from './pi-tools.mjs';
|
|
34
|
+
const cadTools = await createPiCadTools({ outputRoot: '/workspace/cad-output/session-001' });
|
|
35
|
+
agent.state.tools = [...agent.state.tools, ...cadTools]; // register once; names must be unique
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
The adapter preserves schema `$defs`, serializes CAD operations, throws on failed receipts, and attaches preview PNG content. It does not add a database or copy artifacts outside the sandbox. The harness still owns accepted model state, attachments, token budget and session persistence.
|
|
39
|
+
|
|
40
|
+
## Pi coding agent: use the extension
|
|
41
|
+
|
|
42
|
+
From the example project after `npm ci`:
|
|
43
|
+
|
|
44
|
+
```sh
|
|
45
|
+
./node_modules/.bin/pi --extension ./pi-extension.mjs
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
The extension registers five `cad_*` tools. Output defaults to `./cad-output`; set `COLOCAD_OUTPUT_DIR` in the shell launching Pi to choose a trusted absolute destination. Start it from the intended project directory and restart/rebind when changing projects. Use Pi's existing model/auth configuration.
|
|
49
|
+
|
|
50
|
+
For the modeling workflow as well, load the bundled skill:
|
|
51
|
+
|
|
52
|
+
```sh
|
|
53
|
+
./node_modules/.bin/pi --extension ./pi-extension.mjs \
|
|
54
|
+
--skill ./node_modules/@coloopx/colocad/skills/colocad
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Use `/skill:colocad` with the part description. The skill may use the shell helper for its starting assets; the extension adds direct typed tools. You can use either route independently.
|
|
58
|
+
|
|
59
|
+
## Skill-only integration
|
|
60
|
+
|
|
61
|
+
In a project where colocad and Pi are already installed:
|
|
62
|
+
|
|
63
|
+
```sh
|
|
64
|
+
mkdir -p .agents/skills
|
|
65
|
+
test ! -e .agents/skills/colocad && \
|
|
66
|
+
cp -R node_modules/@coloopx/colocad/skills/colocad .agents/skills/colocad
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Start Pi in that project and invoke `/skill:colocad`. Keep the complete folder: its instructions reference scripts, assets and supporting guides. Review the project skill under Pi's normal project trust flow. No global install or permissions bypass is required.
|
|
70
|
+
|
|
71
|
+
The example tests execute the actual Pi core loop with deterministic model responses, the actual extension loader, and the published Rust binary. They do not call a live model provider. See [verification scope](verification.md).
|
|
72
|
+
|
|
73
|
+
References checked 2026-11-07: [Pi core](https://github.com/earendil-works/pi/tree/main/packages/agent), [extensions](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/extensions.md), [skills](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/skills.md). The installed 1.5.0 declarations and CLI help were also checked.
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# Integration verification
|
|
2
|
+
|
|
3
|
+
Verified on **2026-11-07**, Node.js **22.23.3**, **macOS arm64**, using the public npm package **@coloopx/colocad@0.1.0-alpha.3** and its bundled Rust binary. Pi core, Pi AI and Pi coding agent are pinned to **1.5.0** in the example lockfile.
|
|
4
|
+
|
|
5
|
+
| Check | Result | What it establishes |
|
|
6
|
+
| --- | --- | --- |
|
|
7
|
+
| SDK validate → preview → camera change → parameter edit | Pass | Real geometry, cached observation, expected removed volume and persisted source |
|
|
8
|
+
| Pi adapter schemas, preview image, failure mapping and cancellation before dispatch | Pass | Complete `$defs`, valid PNG content, error results and no dispatch after pre-cancellation |
|
|
9
|
+
| Explicit degraded feature | Pass | The omitted fillet and native error remain in model-visible tool text |
|
|
10
|
+
| Pi core tool loop with a failed edit then corrected build | Pass | Actual agent loop propagates failure and resumes to a successful STEP export |
|
|
11
|
+
| Pi coding agent extension loader and skill discovery | Pass | Five executable CAD tools register; the complete skill is discoverable |
|
|
12
|
+
| Existing root Node regression suite | 5 passed | Feature compiler, edits, output collision handling and native-output refusal |
|
|
13
|
+
| Documented CLI and copied skill commands | Pass | Feature-tree planning/build/edit and kernel-model helpers execute from a consuming project |
|
|
14
|
+
| Independent OCCT STEP readback | 4 passed | Two manifold revisions and two copied-skill plates are valid single solids with checked material regions |
|
|
15
|
+
|
|
16
|
+
[Machine-readable results, volumes, probes and STEP hashes](../evidence/harness-integrations.json).
|
|
17
|
+
|
|
18
|
+
Reproduce the integration tests from the repository root:
|
|
19
|
+
|
|
20
|
+
```sh
|
|
21
|
+
npm ci --prefix examples/integrations --ignore-scripts
|
|
22
|
+
npm test --prefix examples/integrations
|
|
23
|
+
node examples/integrations/sdk.mjs ./out/sdk-example
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
The five integration tests run native CAD operations and actual Pi library code. The model response stream is deliberately scripted: no provider API key, inference request or autonomous model decision is involved. Thus the result verifies execution contracts and recovery, not unseen-drawing success rate or a model's ability to choose the correct CAD features.
|
|
27
|
+
|
|
28
|
+
Codex skill paths/invocation and Claude Code skill paths/invocation were checked against their official documentation. The bundled helper was run from both `.agents/skills/colocad` and `.claude/skills/colocad`. No Claude Code live session was run, and this test run did not evaluate a live Codex model reconstructing a drawing. The Pi live-provider schema negotiation remains dependent on the provider you configure.
|
|
29
|
+
|
|
30
|
+
This verification adds no new performance claims. Cross-platform npm release checks are recorded separately in [release-alpha.3.json](../evidence/release-alpha.3.json); the new adapter regression itself was run on macOS arm64. Native SOLIDWORKS acceptance remains subject to the [existing limitations](../validation.md).
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
# 实际建模操作、数据流与完整产品的验收
|
|
2
|
+
|
|
3
|
+
[完整方案:材料、工具、skill/提示词、调优](agent-modeling-handbook.zh-CN.md)在本次操作记录基础上给出可复用方法。
|
|
4
|
+
|
|
5
|
+
本说明区分已执行的操作与下一阶段拟采用的方法。熟悉某类机械的原理,有助于拆解设计;具体型号的尺寸、公差和内部结构仍需资料与测量支持。
|
|
6
|
+
|
|
7
|
+
## 当前实际执行了什么
|
|
8
|
+
|
|
9
|
+
本次实际完成的是 [HIWIN KK60 完整执行器复建](../examples/hiwin-kk60/README.md),配置为 300 mm 导轨、5 mm 导程、单滑块、无选配电机与罩壳。此前的涡扇仍只是合成几何测试件。
|
|
10
|
+
|
|
11
|
+
| 阶段 | 实际输入与操作 | 实际输出 |
|
|
12
|
+
| --- | --- | --- |
|
|
13
|
+
| 查资料与读图 | 厂家目录 PDF;提取尺寸文字,渲染第 25 页,再放大检查剖视图 | 指定型号/配置,尺寸来源、坐标基准与假设清单 |
|
|
14
|
+
| 纠正读图 | 放大 SECTION A-A,把误读的 15 mm 丝杠中心高纠正为 23 mm | 更新共轴零件与接口尺寸 |
|
|
15
|
+
| 编写几何程序 | 助手依据图纸、数值和接口编写 `model.mjs` | 52 个特征及 81 个命名实例的生成器;运行时开放行程参数 |
|
|
16
|
+
| 实际执行 | 生成明确的 kernel JSON,调用 `ModelingSession.build` | 16 个阶段的源文件、回执、精确 STEP、预览网格 |
|
|
17
|
+
| 处理失败 | 总装触发内部 STEP 的 10 万实体限制 | 修复内部序列化预算、增加 Rust 回归;保留原失败会话 |
|
|
18
|
+
| 独立检查 | 用 OCCT 读回 STEP,检查实体、体积、孔/槽材料点与行程端点 | 可复现的验证脚本与 JSON 结果 |
|
|
19
|
+
| 人类查看与交付 | `colocad view / replay / render` | 本地查看器、单文件 HTML、四视图 MP4/GIF、整机 STEP |
|
|
20
|
+
|
|
21
|
+
**图像转参数化指令是本次助手读图与编程产生的中间结果,不是要求用户预先提供的输入,也不是 colocad 内置的自动图像转换能力。** 我先读取文字/图像并形成尺寸判断,再编写程序,colocad 执行明确指令。当前没有经过盲测的“任意图纸一键工业级复建”结论。
|
|
22
|
+
|
|
23
|
+
资料不足的内部结构仍标为假设:螺旋槽是有几何实体的近似,螺母回珠通道未还原,不能将验证通过解释为制造精度认证。动画也没有隐藏这些范围说明。
|
|
24
|
+
|
|
25
|
+
## 更适合真实产品任务的输入
|
|
26
|
+
|
|
27
|
+
先确定唯一的产品目标:厂家、型号、变型、行程或尺寸配置、版本。目标交付是该配置的完整产品,零件图和 BOM 是输入资料。优先取得总装尺寸、剖面、零件图、接口图和实物照片;若有参考 CAD,可单独留给验收使用。
|
|
28
|
+
|
|
29
|
+
输入不必全是图片。矢量 PDF 的尺寸文字、厂家参数表、图纸图像、剖视图和必要的局部裁图各有作用。图像提供视图对应和空间结构;准确数值优先取尺寸标注/表格;清晰度不足或互相矛盾的标注不能靠视觉印象补成精确值。照片通常用于核对形态,不作为未经标定的尺寸来源。
|
|
30
|
+
|
|
31
|
+
## 从本次操作整理的工作方法:尚非盲测通过的通用能力
|
|
32
|
+
|
|
33
|
+
1. **固定完整产品的规格。** 建立单位、坐标系、投影法、型号配置和验收范围,先确定总装包络、主要轴线、运动方向与安装接口。
|
|
34
|
+
2. **建立可追溯的尺寸记录。** 每个关键参数记录原文件、页码、标注区域、数值和单位。分清图纸给定、由关系推导、暂时假设、尚未知四种状态。关键未知项应体现在完成度中。
|
|
35
|
+
3. **先规划总装约束。** 建立零件定义、实例、父子关系、基准与配合接口。不要先随意画一批零件,再靠移动拼成看起来相似的产品。
|
|
36
|
+
4. **生成小步的建模程序。** 助手按工程含义选择旋转、拉伸、切除、扫掠、放样、阵列等操作,使用稳定 ID、命名尺寸和关系式。先实现安装与运动接口,再处理次要外观细节。重复件复用定义。
|
|
37
|
+
5. **执行并读取反馈。** 每个有意义的里程碑由 CLI/SDK 实际构建,保存输入和回执。失败后根据 feature ID 和几何反馈修改,保留失败记录。不能用略去关键结构来换取成功状态。
|
|
38
|
+
6. **定向检查,再接受版本。** 内核有效性、图纸尺寸、装配关系分别验证。生成与原图一致的投影视角/剖面检查轮廓和孔位;独立回读 STEP 检查实体、体积及内部区域。调整参数后复查受影响的接口和整机包络。
|
|
39
|
+
|
|
40
|
+
建议中间数据与内核输入分开保存:
|
|
41
|
+
|
|
42
|
+
```text
|
|
43
|
+
product.json 型号、配置、单位、坐标与整机验收要求
|
|
44
|
+
sources/ 原始资料、页码与局部裁图
|
|
45
|
+
measurements.json 尺寸、来源、推导关系与未知项
|
|
46
|
+
interfaces.json 零件间接口、装配基准和运动关系
|
|
47
|
+
model.mjs 必要时使用的可编辑参数生成程序
|
|
48
|
+
model.json 给 colocad 的明确几何指令
|
|
49
|
+
history/ 每次实际执行的输入、回执、STEP 和预览
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
其中前四项是建议的任务数据约定,当前不是 colocad 内核 schema 的新增字段,也还没有自动提取器。不能把这些任意字段塞入 kernel model。
|
|
53
|
+
|
|
54
|
+
## 给助手的有效任务约束
|
|
55
|
+
|
|
56
|
+
比“照图做一个工业级模型”更明确的提示应包含:
|
|
57
|
+
|
|
58
|
+
```text
|
|
59
|
+
目标:还原指定厂家、型号、配置的完整产品。
|
|
60
|
+
依据:列出图纸/手册文件及其版本,指定优先来源。
|
|
61
|
+
单位与基准:确认投影法、总装坐标、主要轴线。
|
|
62
|
+
精度目标:列出应核对的尺寸、公差、配合和行程。
|
|
63
|
+
未知项:不得默默替换为确定尺寸;单独记录假设与影响。
|
|
64
|
+
执行:先列整体布局和接口,再分阶段建模;保留失败与修改。
|
|
65
|
+
验收:给出整机、关键接口、内部结构的测量与对应视图。
|
|
66
|
+
交付:可编辑源、整机 STEP、建模会话、CLI 导出的离线回放。
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
不要只靠一个很长的提示。每轮仅给当前子系统所需的清晰视图、相关尺寸和接口约束,并保留共享整机基准。让校验返回具体数值与误差,而非只有“看着不对”。这套方法是否提高成功率,应通过实际任务记录证明。
|
|
70
|
+
|
|
71
|
+
## 如何判断效果真的提升
|
|
72
|
+
|
|
73
|
+
在相同型号、资料、模型版本和预算下,比较尺寸识别正确率、关键特征遗漏、独立几何检查、装配接口误差、未知项数量与人工修改次数。推理时间/费用、CAD 执行、预览分别计量。执行器更快,不直接等于读图更准;实体数更多也不等于完整产品更准确。
|
|
74
|
+
|
|
75
|
+
对于滚珠丝杠执行器,完整产品验收应覆盖所选配置的轨道/壳体、滑台、丝杠螺母、支承与连接,以及实际公开资料能确定的内部结构;还包括轴线关系、安装孔位、行程端点和旋转—平移关系。仅有外形 CAD 时,不能据此声称滚道、滚珠回流和制造公差均已还原。
|
|
76
|
+
|
|
77
|
+
[CLI 查看与导出](modeling-history.md) · [本次真实产品实例](../examples/hiwin-kk60/README.md)
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
# Native SOLIDWORKS author (experimental)
|
|
2
|
+
|
|
3
|
+
The Windows entry point consumes the same job. It starts a blank part using the application's configured default, builds sketches with native lines and circles, calls extrusion/cut/fillet/pattern APIs and names the resulting features. The fillet uses body edges and the native pattern selects the original seed feature. There are no part-specific model files. Running it requires local Windows, .NET 8 and a licensed SOLIDWORKS installation with a valid default blank part configuration.
|
|
4
|
+
|
|
5
|
+
```powershell
|
|
6
|
+
colocad solidworks .\manifold\part\native-job.json .\manifold.SLDPRT
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
Use `COLOCAD_SW_INTEROP` for an alternate directory containing the local SOLIDWORKS interop DLLs. The completion check is designed to save a temporary part, reopen it, verify native types, radius, pattern seed, count, pitch and reference volume, then edit a driving extrusion dimension, rebuild, restore and check it. Only a successful check publishes the output. The current release has **no native runtime pass** for either complex part. The package includes no four-hole template and does not route jobs to another machine.
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
[Validation notes](validation.md) · [API](api.md)
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
# Performance evidence and reproduction
|
|
2
|
+
|
|
3
|
+
These measurements apply to the stated workloads and historical binaries. They are not a claim of universal superiority or a fresh benchmark of every release.
|
|
4
|
+
|
|
5
|
+
## How many tendon hands can an agent deliver in 100 seconds?
|
|
6
|
+
|
|
7
|
+
**colocad delivered 44 complete revisions to build123d’s 33 (+33.3%), with 57.1% lower peak sampled sandbox memory.** Both tools rebuilt and assembled the same 43-solid hand at each revision. Each tick marks a complete STEP handed off to storage.
|
|
8
|
+
|
|
9
|
+

|
|
10
|
+
|
|
11
|
+
The GIF shows the **highest memory sampled so far** for each tool on the same 0–512 MiB scale. For actual usage between builds, see the [instantaneous-memory replay (MP4)](https://github.com/Coloopx/colocad/raw/refs/heads/main/showcase/tendon-hand/window/hand-window-en.mp4) or the [timestamped samples](../showcase/tendon-hand/evidence/window-optimized.json).
|
|
12
|
+
|
|
13
|
+
| Same revision queue, 1 vCPU / 512 MiB | Optimized colocad | build123d |
|
|
14
|
+
|---|---:|---:|
|
|
15
|
+
| Complete hands delivered in 100 s | **44** | 33 |
|
|
16
|
+
| First STEP | **2.223 s** | 3.010 s |
|
|
17
|
+
| Median job time on the same first 33 inputs | **2.234 s** | 2.855 s |
|
|
18
|
+
| Highest sampled cgroup memory over the 100 s window | **130.9 MiB** | 304.9 MiB |
|
|
19
|
+
|
|
20
|
+
One measured window per backend, with a new CAD process for each revision. The original run used the alpha.2 SDK and the optimized Linux arm64 kernel now bundled in alpha.3. Memory samples taken about every 25 ms include subprocesses, tmpfs and charged file cache. Every counted STEP reopened successfully. [Measurement method](../showcase/tendon-hand/window/README.md) · [Detailed build and single-call replay](../showcase/tendon-hand/assembly-performance.md)
|
|
21
|
+
|
|
22
|
+
The static scorecard below uses the **published alpha.2 binary**. With fresh tool processes the sensor rail and manifold reached STEP 22.0× and 12.9× faster than build123d, using 7.7% and 8.0% of its peak memory.
|
|
23
|
+
|
|
24
|
+
<details>
|
|
25
|
+
<summary>See the static comparison across four workloads</summary>
|
|
26
|
+
|
|
27
|
+

|
|
28
|
+
|
|
29
|
+
</details>
|
|
30
|
+
|
|
31
|
+
| Deliverable | Time to STEP: colocad / build123d | Speedup¹ | Peak memory: colocad / build123d | Share of build123d peak |
|
|
32
|
+
| :--- | ---: | ---: | ---: | ---: |
|
|
33
|
+
| Sensor rail | 113 / 2,485 ms | **22.0×** | 20.0 / 259.3 MiB | **7.7%** |
|
|
34
|
+
| Port manifold | 230 / 2,963 ms | **12.9×** | 20.7 / 258.7 MiB | **8.0%** |
|
|
35
|
+
| Tendon-hand proximal link | 259 / 2,244 ms | **8.6×** | 21.4 / 260.1 MiB | **8.2%** |
|
|
36
|
+
| Complete 43-solid hand | 3,952 / 3,293 ms | **0.83×** | 52.7 / 271.3 MiB | **19.4%** |
|
|
37
|
+
|
|
38
|
+
¹ build123d time divided by colocad time from unrounded observations. Same Linux arm64 image, 1 vCPU, 512 MiB. Five fresh processes and cgroups per part and backend after warm-up. Time is the median wall clock including startup, imports, modeling, backend checks and STEP export. Memory is the maximum measured cgroup peak; charged pages, temporary outputs and tool descendants count. Installation, container startup, previews, inference and a resident agent are excluded.
|
|
39
|
+
|
|
40
|
+
[Rail/manifold samples](../docs/benchmarks/runs.json) · [Finger/hand samples](../showcase/tendon-hand/evidence/scope.json) · [Four-view hand study and CAD downloads](../showcase/tendon-hand/README.md) · [Offline scorecard](https://github.com/Coloopx/colocad/raw/refs/heads/main/docs/benchmarks/time-to-step.html)
|
|
41
|
+
|
|
42
|
+
**Historical alpha.2 result.** in a separate 100-second sweep of complete hand revisions, colocad delivered 24 STEPs to build123d’s 30. Every counted file reopened as a valid 43-solid assembly. [Timestamped outputs and paired geometry checks](../showcase/tendon-hand/evidence/window.json)
|
|
43
|
+
|
|
44
|
+
## What the two STEP writers produced
|
|
45
|
+
|
|
46
|
+

|
|
47
|
+
|
|
48
|
+
Each backend modeled the part from the same parameters. The images use the exported STEPs, the same mesher and camera. OCCT reopened each file as **one valid solid**. Both rail exports had 22 faces and 56 edges; both manifold exports had 27 faces and 54 edges. The two directional boolean differences measured **0 mm³** in both cases (boolean tolerance: 0.000001 mm). [Geometry checks](../docs/benchmarks/step-checks.json)
|
|
49
|
+
|
|
50
|
+
On the manifold, build123d’s modeling phase alone was **43.8 ms** to colocad’s **53.7 ms**, while build123d import alone took **2.45 s**. The table measures a fresh tool call, not the speed of an isolated boolean operation. [Stage timings and reproduction](../benchmarks/readme/README.md)
|
|
51
|
+
|
|
52
|
+
### When the agent only changes the camera
|
|
53
|
+
|
|
54
|
+
The first preview saves a display mesh. For a second view of unchanged geometry, the kernel SDK can load that mesh instead of rebuilding the solid or triangulating it again. Here are five-run medians for the same **top view**, comparing two paths inside colocad:
|
|
55
|
+
|
|
56
|
+
| Part | Rebuild part + render | Render from saved mesh | Speedup |
|
|
57
|
+
| :--- | ---: | ---: | ---: |
|
|
58
|
+
| Sensor rail | 108.8 ms | 19.4 ms | **5.6×** |
|
|
59
|
+
| Port manifold | 223.8 ms | 13.3 ms | **16.8×** |
|
|
60
|
+
|
|
61
|
+
The PNG, GLB and STL from both paths matched byte for byte on every pair. This test starts with the SDK already loaded and includes native process startup and display output. A geometry edit needs a new revision. [Preview measurements and hashes](../docs/benchmarks/preview-runs.json)
|
|
62
|
+
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# Troubleshooting
|
|
2
|
+
|
|
3
|
+
| Symptom | Check and action |
|
|
4
|
+
| --- | --- |
|
|
5
|
+
| Skill cannot be found | Check `.agents/skills/colocad/SKILL.md` for Codex/Pi or `.claude/skills/colocad/SKILL.md` for Claude Code; start in that project and refresh/restart discovery. |
|
|
6
|
+
| Skill helper cannot import colocad | Install the pinned package in the current project and run the helper from there. Copy the complete skill folder. |
|
|
7
|
+
| `colocad build` rejects `version: 1` | That CLI expects `format: "colocad/1"`. Use `CadClient` or the skill helper for a kernel model. |
|
|
8
|
+
| Output directory already exists | Pick a new revision destination for the CLI/helper. Keep earlier accepted output. `CadClient.outputRoot` can contain multiple revisions. |
|
|
9
|
+
| Unsupported platform / missing executable | Alpha.3 bundles Linux x64/arm64 and macOS arm64. Check `process.platform`, `process.arch` and the installed `kernel/native` directory. Source builds require a Rust toolchain and the pinned dependency. |
|
|
10
|
+
| Native launch fails | Check `LOCAL_EXECUTION_FAILED`, executable permissions, mount policy and `binary`/`AGENT_CAD_BINARY` overrides. Run the local CLI to isolate harness wiring. |
|
|
11
|
+
| `TIMEOUT` | Inspect the failing feature and workload. Simplify or split unnecessary work; adjust `wallMs` within 1–120,000 only when appropriate. Sandbox memory failures need sandbox diagnostics too. |
|
|
12
|
+
| `RESOURCE_LIMIT` / `OUTPUT_LIMIT` | Inspect capabilities and reduce model/mesh payload. SDK stdin is limited to 32 MiB; the feature-tree CLI accepts 2 MiB. |
|
|
13
|
+
| Unknown/missing parameter | Use an existing finite numeric parameter. `edit()` does not create parameters; update the owned source to add one. |
|
|
14
|
+
| An edit undoes a prior change | You reused stale source. Load the last accepted `model.json` or persist the merged parameters after each successful edit. |
|
|
15
|
+
| Preview succeeds but no STEP in its directory | A cached observation points to `source_artifact_directory`. Retrieve STEP from the source geometry revision. |
|
|
16
|
+
| Cached preview cannot be read | Retain its source directory and files; do not modify cache bytes. Rebuild from the saved model if the cache was pruned or is invalid. |
|
|
17
|
+
| Agent cannot see the rendered image | Attach PNG as image content or invoke the harness's image-reading tool. Printing the local filename alone is insufficient. |
|
|
18
|
+
| Provider rejects tool schema | Preserve root `$defs`; check the provider's schema restrictions. Use skill + shell tools if the provider cannot accept the complete schema. |
|
|
19
|
+
| No editable native SOLIDWORKS tree | STEP is not a feature-history file. The Windows author is experimental; generic Linux native authoring is not complete. |
|
|
20
|
+
|
|
21
|
+
Some low-level failures retain the legacy error code `WORKER_FAILED`. It is an error label in alpha.3, not a requirement to deploy a separate service. Native execution is local.
|
|
22
|
+
|
|
23
|
+
For a useful bug report, include package/platform/Node versions, minimal model JSON, the failed receipt, expected geometry and reproduction command. Remove credentials and private design data. Attach a small STEP and screenshot when shareable. Keep the original file if the failure depends on STEP import; otherwise reduce the model to the failing dependency chain.
|
|
24
|
+
|
|
25
|
+
See [Contributing](../CONTRIBUTING.md) for the test commands and [validation](validation.md) for known limitations.
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# Release validation
|
|
2
|
+
|
|
3
|
+
The same public build API compiled the two different feature trees in `examples/`. The manifold has one solid with 27 faces and 54 edges. OCCT read its STEP as a valid solid with volume 45,490.923866 mm³. Reducing the blind-port count from four to three restored 226.194671 mm³, matching π × 3² × 8. The rail has rectangular through-slots patterned along Y. Removing one slot restored 405 mm³. The validation script also probes points within and outside the blind ends, the pocket, and the fillet.
|
|
4
|
+
|
|
5
|
+

|
|
6
|
+
|
|
7
|
+
The native Windows author compiled against SOLIDWORKS 2024 interop 32.1.0. Runtime creation, feature edit, force rebuild and reopen in the vendor application remain unverified.
|
|
8
|
+
|
|
9
|
+
The Linux file-format experiment started with a synthesized envelope containing no part geometry or feature tree. On an empty source the pinned Rust encoder refuses synthesis without retained signature tokens. Providing a minimal envelope allowed a cube to round-trip as one solid with six faces. For the actual manifold, its exported STEP contains 54 explicit trim ranges. Of these, 32 are lines delimited by their vertices, 8 are closed full circles and 14 are clamped full-domain NURBS. Checking that the endpoints and natural domains agree permits equivalent vertex-delimited geometry. The experimental re-read then recovered one solid, 27 faces, 54 edges and zero neutral validation findings. This result contains a geometry partition only. Editable fillet selection ownership and native feature-pattern seed references still need to be serialized and independently proven. The CLI intentionally does not release these experimental bytes as an editable part.
|
|
10
|
+
|
|
11
|
+
The packaged npm archive was installed offline and invoked through the sandbox-local Pi bash tool in an Abelien Linux arm64 runner limited to 1 vCPU and 512 MiB. In the [scoped 0.1.0-alpha.2 run](evidence/scoped-runner.json) the manifold build with preview took 272 ms, the rail 84 ms and the pattern-count edit 181 ms. These are single tool-call wall times. The full cgroup peak includes the offline npm install, cache and files staged on tmpfs. See the JSON receipts in [evidence](evidence/).
|
|
12
|
+
|
|
13
|
+
We also tested the first two manifold operations with a freshly generated, matching B-rep and a sketch graph compiled directly from the same job. The independent decode of the experimental bytes recovered seven sketch entities across two sketches, one extrusion and one cut. The native operation-class and driving-scalar counts were both zero. Adding the rim fillet to the full graph produced a native encoder refusal at the edge-selection group. The records are in [native-prefix.json](evidence/native-prefix.json) and [native-full-refusal.txt](evidence/native-full-refusal.txt). These are file-format diagnostics, with no claim of successful rebuild in SOLIDWORKS.
|
|
14
|
+
|
|
15
|
+
The fillet selector separately found all six intended edges in the B-rep recovered for the state immediately preceding the fillet. Both adjacent faces and both endpoints are recorded for each edge. Mapping those input-state identities to persistent SOLIDWORKS operands remains open. In a second diagnostic without the fillet, file readback recovered the linear pattern (four instances along X at 18 mm pitch) and its link to the port-cut seed. Its native operation-class and driving-scalar counts were still zero. See [input-state edges](evidence/historical-selection.json) and [pattern diagnostic](evidence/native-pattern.json).
|
|
16
|
+
|
|
17
|
+

|
|
18
|
+
|
|
19
|
+
## npm release 0.1.0-alpha.3
|
|
20
|
+
|
|
21
|
+
The [archive checks and independent STEP measurements](evidence/release-alpha.3.json) cover macOS arm64, Linux arm64 and Linux x64. Both Linux installations ran offline with 1 vCPU and 512 MiB. The x64 check used an emulated x64 environment and exercised the x64 Node executable and native kernel. Each installation used the packaged CLI to build a manifold and the bundled skill to build a six-hole plate, a sleeve pair and a complete 43-solid hand. OCCT reopened all twelve STEP files. The hand report counted 21 measured instances and 22 translated reuses on each platform.
|
|
22
|
+
|
|
23
|
+
For a release, stage the three tested executables and their manifests under `kernel/native/<platform>/`. Record the corresponding SHA-256 values and npm version in `kernel/release.json`. The `prepack` check rejects missing executables and hashes that differ from the recorded build. Run `npm pack`, install that tarball in an empty consumer project on each platform, and run `node /path/to/checkout/test/validation/packed.mjs` from that project. Provide the hand model JSON as an optional argument to exercise all 43 occurrences. Publish that tested tarball directly.
|
|
@@ -4,7 +4,7 @@ This example models one complete configuration of a real product: **HIWIN KK60 s
|
|
|
4
4
|
|
|
5
5
|

|
|
6
6
|
|
|
7
|
-
[MP4](../../showcase/hiwin-kk60/modeling.mp4) · [Editable generated model](../../showcase/hiwin-kk60/model.json) · [Independent verification](../../showcase/hiwin-kk60/verification.json) · [Source dimensions and assumptions](sources.json)
|
|
7
|
+
[Complete offline delivery: HTML, STEP and session ZIP](https://github.com/Coloopx/colocad/releases/download/v0.1.0-alpha.4/hiwin-kk60-delivery.zip) · [MP4](../../showcase/hiwin-kk60/modeling.mp4) · [Editable generated model](../../showcase/hiwin-kk60/model.json) · [Independent verification](../../showcase/hiwin-kk60/verification.json) · [Source dimensions and assumptions](sources.json)
|
|
8
8
|
|
|
9
9
|
## Build, view and export through the CLI
|
|
10
10
|
|
|
@@ -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}));}
|
package/kernel/release.json
CHANGED
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.6",
|
|
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",
|
|
@@ -63,7 +63,10 @@
|
|
|
63
63
|
"examples/hiwin-kk60/run.mjs",
|
|
64
64
|
"examples/hiwin-kk60/README.md",
|
|
65
65
|
"examples/hiwin-kk60/sources.json",
|
|
66
|
-
"
|
|
66
|
+
"examples/integrations/compact-tools.mjs",
|
|
67
|
+
"examples/integrations/guided-workflow.mjs",
|
|
68
|
+
"docs/*.md",
|
|
69
|
+
"docs/integrations/*.md"
|
|
67
70
|
],
|
|
68
71
|
"scripts": {
|
|
69
72
|
"test": "node --test test/*.test.mjs",
|
package/skills/colocad/SKILL.md
CHANGED
|
@@ -1,19 +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.
|
|
18
24
|
|
|
19
|
-
|
|
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
|
+
}
|