@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.
Files changed (53) hide show
  1. package/NOTICE.md +2 -0
  2. package/README.md +130 -4
  3. package/README.zh-CN.md +111 -4
  4. package/bin/colocad.mjs +28 -4
  5. package/docs/README.md +28 -0
  6. package/docs/README.zh-CN.md +85 -0
  7. package/docs/agent-modeling-handbook.md +68 -0
  8. package/docs/agent-modeling-handbook.zh-CN.md +222 -0
  9. package/docs/agent-modeling-research.md +22 -0
  10. package/docs/api.md +95 -0
  11. package/docs/best-practices.md +45 -0
  12. package/docs/concepts.md +37 -0
  13. package/docs/getting-started.md +53 -0
  14. package/docs/integrations/claude-code.md +52 -0
  15. package/docs/integrations/codex.md +55 -0
  16. package/docs/integrations/overview.md +53 -0
  17. package/docs/integrations/pi.md +73 -0
  18. package/docs/integrations/verification.md +30 -0
  19. package/docs/modeling-history.md +60 -0
  20. package/docs/modeling-workflow.zh-CN.md +77 -0
  21. package/docs/troubleshooting.md +25 -0
  22. package/docs/validation.md +23 -0
  23. package/examples/hiwin-kk60/README.md +55 -0
  24. package/examples/hiwin-kk60/model.mjs +94 -0
  25. package/examples/hiwin-kk60/run.mjs +14 -0
  26. package/examples/hiwin-kk60/sources.json +88 -0
  27. package/examples/integrations/README.md +47 -0
  28. package/examples/integrations/compact-tools.mjs +27 -0
  29. package/examples/integrations/guided-workflow.mjs +31 -0
  30. package/kernel/native/darwin-arm64/agent-cad +1 -1
  31. package/kernel/native/darwin-arm64/manifest.json +1 -2
  32. package/kernel/native/linux-arm64/agent-cad +1 -1
  33. package/kernel/native/linux-arm64/manifest.json +1 -2
  34. package/kernel/native/linux-x64/agent-cad +2 -2
  35. package/kernel/native/linux-x64/manifest.json +2 -3
  36. package/kernel/release.json +4 -4
  37. package/package.json +40 -4
  38. package/skills/colocad/SKILL.md +18 -8
  39. package/skills/colocad/assets/product-brief.example.json +20 -0
  40. package/skills/colocad/references/history.md +19 -0
  41. package/skills/colocad/references/materials.md +37 -0
  42. package/skills/colocad/references/modeling-loop.md +33 -0
  43. package/skills/colocad/references/prompt-patterns.md +70 -0
  44. package/skills/colocad/references/tool-contracts.md +33 -0
  45. package/skills/colocad/references/tuning.md +30 -0
  46. package/src/render.mjs +72 -0
  47. package/src/session.d.mts +34 -0
  48. package/src/session.mjs +140 -0
  49. package/src/view-server.mjs +50 -0
  50. package/viewer/THREE-LICENSE +21 -0
  51. package/viewer/dist/index.js +4236 -0
  52. package/viewer/dist/standalone.js +4236 -0
  53. package/viewer/index.d.ts +18 -0
package/NOTICE.md CHANGED
@@ -3,3 +3,5 @@
3
3
  Colocad and the included Agent CAD application code are distributed under the MIT license. The Rust application builds against SolidCore at revision bff1569a4c3347ed9af67faab71578cadf84fde2. SolidCore includes work derived from NVIDIA USD BRep / SMLib. The kernel's Apache-2.0 license, notices, attribution and licenses of Rust dependencies ship in `kernel/licenses`. Source provenance is also recorded in `third_party`.
4
4
 
5
5
  The .NET author references SOLIDWORKS 2024 interop APIs. SOLIDWORKS is a trademark of its respective owner. A local licensed installation provides the proprietary COM application and its interop assemblies. The package contains Colocad's own managed assembly and source in the repository. The experimental file-format investigation uses the independently licensed cadmpeg project at d77e2dd2a9d154e7b432afb022c147864f2618bb.
6
+
7
+ The browser viewer bundles Three.js under the MIT license; its license is included in `viewer/THREE-LICENSE`. HIWIN and product names in the actuator reconstruction identify the source product; this project is not affiliated with or endorsed by the manufacturer. No manufacturer CAD or catalog PDF is redistributed.
package/README.md CHANGED
@@ -1,9 +1,124 @@
1
- # colocad
1
+ # Colocad
2
2
 
3
- [中文说明](README.zh-CN.md) · [npm package](https://www.npmjs.com/package/@coloopx/colocad) · [Download the offline comparison](https://github.com/Coloopx/colocad/raw/refs/heads/main/docs/benchmarks/comparison.html)
3
+ ![HIWIN KK60 linear actuator — actual native modeling and assembly in four views](showcase/hiwin-kk60/modeling.gif)
4
+
5
+ **HIWIN KK60 linear actuator** · [Modeling example](examples/hiwin-kk60/README.md) · [Watch MP4](showcase/hiwin-kk60/modeling.mp4) · [Independent checks](showcase/hiwin-kk60/verification.json)
6
+
7
+ [中文说明](README.zh-CN.md) · [Developer docs](docs/README.md) · [npm package](https://www.npmjs.com/package/@coloopx/colocad) · [Download the offline comparison](https://github.com/Coloopx/colocad/raw/refs/heads/main/docs/benchmarks/comparison.html)
4
8
 
5
9
  Generate a mechanical part from a JSON feature tree, export an exact STEP solid, and give an agent a PNG or 3D preview to inspect. **The npm package ships the compiled Rust CAD kernel.** The agent and harness call it locally in the same sandbox through the Node CLI or TypeScript API. No Python, Rust toolchain, network or separate service is required to build a part after installation.
6
10
 
11
+ ## Start here: SDK + CLI + skill
12
+
13
+ [End-to-end agent modeling handbook](docs/agent-modeling-handbook.md) · [Research and evidence](docs/agent-modeling-research.md)
14
+
15
+ The **SDK is the modeling foundation**. The CLI exposes it to a shell-based harness; the skill supplies modeling instructions, editable starter shapes and verification guidance. The agent, harness and CAD executable run inside the same sandbox. A recorded session provides the human-facing view of that work.
16
+
17
+ ```mermaid
18
+ flowchart LR
19
+ A[Agent + colocad skill] --> H[Harness]
20
+ H --> C[colocad CLI]
21
+ H --> S[TypeScript SDK]
22
+ C --> S
23
+ S --> K[Local Rust B-rep kernel]
24
+ K --> F[STEP + model + receipts + meshes]
25
+ F --> V[CLI viewer / HTML / MP4 / GIF]
26
+ ```
27
+
28
+ ### CLI: build, inspect and keep the modeling process
29
+
30
+ ```sh
31
+ npm install @coloopx/colocad@0.1.0-alpha.5
32
+
33
+ # Build the packaged example and persist an inspectable native revision.
34
+ npx colocad record node_modules/@coloopx/colocad/examples/manifold.json ./history \
35
+ --label "Build the manifold"
36
+
37
+ # Launch the viewer and open the browser.
38
+ npx colocad view ./history
39
+
40
+ # Export one self-contained HTML file, including the final STEP download.
41
+ npx colocad replay ./history ./review.html
42
+ ```
43
+
44
+ Record the next edited JSON into the **same** history directory to append a revision. Every attempted build retains its source and receipt; failures remain visible. `view` serves a snapshot, so reopen it after adding revisions. In a headless sandbox, use `colocad view ./history --no-open --port 8787` and the harness's existing port forwarding. The listener binds to `127.0.0.1`.
45
+
46
+ | CLI command | Input | Output / purpose |
47
+ | --- | --- | --- |
48
+ | `colocad plan TREE.json` | `colocad/1` feature tree | Compile a native modeling job without building geometry |
49
+ | `colocad build TREE.json NEW_DIR --preview` | `colocad/1` feature tree | STEP, editable tree, report and previews |
50
+ | `colocad record MODEL.json SESSION --label TEXT` | Feature tree **or** kernel model JSON | Build and append a persistent modeling milestone |
51
+ | `colocad view SESSION` | Recorded session | Local interactive viewer; optional `--export review.html` |
52
+ | `colocad replay SESSION review.html` | Recorded session | Single offline HTML, no listening process |
53
+ | `colocad render SESSION modeling.mp4` | Recorded session | Four-view animation, timing/hash manifest and poster; `.gif` also supported |
54
+
55
+ ### Visualization and animation are launched from the CLI
56
+
57
+ ![CLI-launched modeling-history viewer with the real KK60 assembly](https://raw.githubusercontent.com/Coloopx/colocad/main/showcase/hiwin-kk60/viewer.png)
58
+
59
+ The viewer includes a step timeline, source/feature/receipt inspector, part selection and visibility, four camera presets, display cutaway/explosion, and downloads of the current model and final STEP. The HTML embeds its rendering code and geometry; it works offline. The browser component is also available as `@coloopx/colocad/viewer` for a host application.
60
+
61
+ ```sh
62
+ # Optional dependencies for movie encoding only:
63
+ npm install -D playwright
64
+ npx playwright install chromium
65
+ # Install FFmpeg on your host, then export from the same persisted session:
66
+ npx colocad render ./history ./modeling.mp4 --width 1280 --height 800 --fps 15
67
+ npx colocad render ./history ./modeling.gif --width 960 --height 600 --fps 10
68
+ ```
69
+
70
+ Movies replay **actual saved CAD revisions** with four synchronized views and measured call times. Playback pacing and exploded placement are presentation controls; film duration is not CAD build time. Geometry builds and offline HTML export do not need Chromium or FFmpeg. [Complete CLI / recorder / renderer guide](docs/modeling-history.md).
71
+
72
+ ### SDK: call the same kernel from your harness
73
+
74
+ ```js
75
+ import { ModelingSession } from '@coloopx/colocad/session';
76
+
77
+ const session = await ModelingSession.create('./history', { title: 'Agent modeling' });
78
+ const model = {
79
+ version: 1, units: 'mm', parameters: { length: 60 },
80
+ features: [{ id: 'stock', op: 'box', origin: [0, 0, 0],
81
+ size: [{ param: 'length' }, 30, 8] }],
82
+ output: 'stock',
83
+ };
84
+ const result = await session.build(model, { label: 'Extrude the stock' });
85
+ if (!result.ok) throw new Error(JSON.stringify(result.error));
86
+ await session.edit({ length: 80 }, { label: 'Lengthen the stock' });
87
+ ```
88
+
89
+ Use `CadClient` for direct builds, edits and cached observation without a session; use `ModelingSession` when the modeling process must be persisted. `createCadTools` and `createSessionTools` expose tool schemas/executors for a harness adapter. [Runnable integrations](examples/integrations/README.md) cover Pi core/extension and the Codex/Claude local skill paths; scripted integration tests are distinguished from live model reasoning.
90
+
91
+ ### Skill: give the agent the complete modeling guide
92
+
93
+ Copy the **whole** bundled skill directory, including scripts, references and editable shape assets:
94
+
95
+ ```sh
96
+ # Codex project skill
97
+ mkdir -p .agents/skills
98
+ cp -R node_modules/@coloopx/colocad/skills/colocad .agents/skills/colocad
99
+
100
+ # For Claude Code, use .claude/skills/colocad instead.
101
+ ```
102
+
103
+ Then ask the agent to use the colocad skill, specify the product/dimensions and require a recorded session, exact STEP and CLI-exported review. For other harnesses, load `skills/colocad/SKILL.md` and register the SDK tools. The skill guides interpretation and verification; colocad executes explicit geometry instructions. [Codex](docs/integrations/codex.md) · [Claude Code](docs/integrations/claude-code.md) · [Pi](docs/integrations/pi.md) · [Actual drawing-to-model workflow](docs/modeling-workflow.zh-CN.md).
104
+
105
+ ## Reconstruct a real industrial product and replay its modeling history
106
+
107
+ The [HIWIN KK60 actuator example](examples/hiwin-kk60/README.md) reconstructs a specific manufacturer catalog configuration: 300 mm rail, 5 mm lead, 210 mm travel. Its **52 native features, 81 named occurrences and 16 persisted milestones** include a physically cut helical screw groove, guide tracks, mounting holes, bearings, carriage and coupling.
108
+
109
+
110
+ [Watch the MP4](showcase/hiwin-kk60/modeling.mp4) · [Edit the model](showcase/hiwin-kk60/model.json) · [Read the independent checks](showcase/hiwin-kk60/verification.json) · [Dimensions and assumptions](examples/hiwin-kk60/sources.json)
111
+
112
+ ```sh
113
+ node node_modules/@coloopx/colocad/examples/hiwin-kk60/run.mjs ./actuator
114
+ npx colocad view ./actuator/session
115
+ npx colocad replay ./actuator/session ./actuator.html
116
+ # Optional: Playwright/Chromium + FFmpeg are required for video encoding.
117
+ npx colocad render ./actuator/session ./modeling.mp4
118
+ ```
119
+
120
+ This is a catalog-based product reconstruction, with explicitly approximated internal races/bearings and no manufacturing certification. The animation reads actual saved CAD revisions; measured call times appear separately from edited playback. It is not a performance comparison. See [CLI history/rendering](docs/modeling-history.md) and the [actual agent modeling workflow](docs/modeling-workflow.zh-CN.md).
121
+
7
122
  ## How many tendon hands can an agent deliver in 100 seconds?
8
123
 
9
124
  **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.
@@ -45,12 +160,23 @@ The static scorecard below uses the **published alpha.2 binary**. With fresh too
45
160
 
46
161
  ## SDK, CLI or skill?
47
162
 
48
- Install with `npm install @coloopx/colocad@0.1.0-alpha.3`. This version bundles the optimized assembly kernel and the complete agent skill. The skill lives at `node_modules/@coloopx/colocad/skills/colocad/`. Point your harness at its `SKILL.md` or copy the whole directory into your agent’s skill collection.
163
+ **Start here:** [first part and edit](docs/getting-started.md) · [SDK/API reference](docs/api.md) · [modeling best practices](docs/best-practices.md).
164
+
165
+ | Your harness | Integration guide |
166
+ | --- | --- |
167
+ | Pi agent core / Pi coding agent | [Typed tool adapter, extension and skill](docs/integrations/pi.md) |
168
+ | Claude Code | [Project skill and local CLI](docs/integrations/claude-code.md) |
169
+ | Codex | [Project skill, invocation and artifact inspection](docs/integrations/codex.md) |
170
+ | Other harnesses | [Sandbox architecture, revision state and artifact lifecycle](docs/integrations/overview.md) |
171
+
172
+ The [runnable examples](examples/integrations/README.md) exercise the published package, real native builds and Pi tool-loop error recovery. See [what was verified](docs/integrations/verification.md) and [how to contribute](CONTRIBUTING.md).
173
+
174
+ Install with `npm install @coloopx/colocad@0.1.0-alpha.5`. This version bundles the optimized assembly kernel and the complete agent skill. The skill lives at `node_modules/@coloopx/colocad/skills/colocad/`. Point your harness at its `SKILL.md` or copy the whole directory into your agent’s skill collection.
49
175
 
50
176
  For a dimensioned part, try “Make a 100 × 50 × 6 mm plate with a centered 3 × 2 grid of Ø6 through-holes on 32 × 30 mm pitches.” The skill includes editable stock, hole grids, sleeves, brackets and open housings. [Quick-build commands and examples](skills/colocad/references/quick-build.md)
51
177
 
52
178
  - **In an application or harness:** call `build(tree, newDir, { preview: true })` in the SDK. Use `CadClient.build(model)` for named multi-solid assemblies.
53
- - **In a shell or agent tool call:** install `npm install @coloopx/colocad@0.1.0-alpha.3`. Run `./node_modules/.bin/colocad plan tree.json`, then `./node_modules/.bin/colocad build tree.json ./new-part --preview`. Open `new-part/part/model.step`.
179
+ - **In a shell or agent tool call:** install `npm install @coloopx/colocad@0.1.0-alpha.5`. Run `./node_modules/.bin/colocad plan tree.json`, then `./node_modules/.bin/colocad build tree.json ./new-part --preview`. Open `new-part/part/model.step`.
54
180
  - **From drawings with an agent:** install the [colocad skill](skills/colocad/SKILL.md). Start the next turn with “Use `$colocad` to reconstruct these four views, export STEP, and flag any internal details you inferred.” [Installation and assembly replay](showcase/tendon-hand/README.md#try-it-with-your-agent).
55
181
 
56
182
  ## What the two STEP writers produced
package/README.zh-CN.md CHANGED
@@ -1,9 +1,105 @@
1
1
  # colocad
2
2
 
3
- [English](README.md) · [npm 包](https://www.npmjs.com/package/@coloopx/colocad) · [下载单文件对比报告:含四份 STEP](https://github.com/Coloopx/colocad/raw/refs/heads/main/docs/benchmarks/comparison.html)
3
+ ![HIWIN KK60 线性执行器:真实建模与装配过程的四视图回放](showcase/hiwin-kk60/modeling.gif)
4
+
5
+ **HIWIN KK60 线性执行器** · [建模案例](examples/hiwin-kk60/README.md) · [MP4 动画](showcase/hiwin-kk60/modeling.mp4) · [独立验证](showcase/hiwin-kk60/verification.json)
6
+
7
+ [English](README.md) · [开发与接入指南](docs/README.zh-CN.md) · [npm 包](https://www.npmjs.com/package/@coloopx/colocad) · [下载单文件对比报告:含四份 STEP](https://github.com/Coloopx/colocad/raw/refs/heads/main/docs/benchmarks/comparison.html)
4
8
 
5
9
  让沙箱内的 agent 用 JSON 描述可改参的机械零件,输出 STEP 实体、PNG 预览和 GLB/STL 网格。**npm 包自带编译好的 Rust CAD 内核**:Linux x64、Linux arm64 和 macOS arm64 各一份。agent 和 harness 在同一沙箱里调用 Node CLI 或 TypeScript API,CLI 直接启动本地 Rust 程序。安装后建模不需要网络、Python、Rust 工具链或额外服务。[Rust 源码](crates/agent-cad/src)和[内核依赖版本](third_party/solidcore.lock.json)在本仓库。
6
10
 
11
+ ## 从这里开始:SDK + CLI + skill
12
+
13
+ [完整建模与 skill/提示词指南](docs/agent-modeling-handbook.zh-CN.md) · [研究依据](docs/agent-modeling-research.md)
14
+
15
+ **SDK 是建模基础,CLI 提供命令行入口,skill 指导 agent 选择几何操作和验收方法。** Agent、harness、SDK 与 Rust 可执行文件在同一个沙箱中运行。建模会话保存实际输入、结果与失败记录,供人类通过查看器检查。
16
+
17
+ ```mermaid
18
+ flowchart LR
19
+ A[Agent + colocad skill] --> H[Harness]
20
+ H --> C[colocad CLI]
21
+ H --> S[TypeScript SDK]
22
+ C --> S
23
+ S --> K[本地 Rust B-rep 内核]
24
+ K --> F[STEP + 模型 + 回执 + 网格]
25
+ F --> V[CLI 查看器 / HTML / MP4 / GIF]
26
+ ```
27
+
28
+ ### CLI:建模、查看、保存过程
29
+
30
+ ```sh
31
+ npm install @coloopx/colocad@0.1.0-alpha.5
32
+
33
+ # 构建随包提供的模型,同时记录一个真实建模阶段。
34
+ npx colocad record node_modules/@coloopx/colocad/examples/manifold.json ./history \
35
+ --label "Build the manifold"
36
+
37
+ # 启动交互式查看器并打开浏览器。
38
+ npx colocad view ./history
39
+
40
+ # 导出单文件 HTML,包含最终 STEP 的下载入口。
41
+ npx colocad replay ./history ./review.html
42
+ ```
43
+
44
+ 把修改后的 JSON 再 `record` 到同一个 `history` 目录,即可追加阶段。输入、回执和失败都保留。查看器展示会话快照;追加阶段后重新打开即可。在无桌面的沙箱中运行 `colocad view ./history --no-open --port 8787`,使用现有 harness 的端口转发。监听地址是 `127.0.0.1`。
45
+
46
+ | 命令 | 输入 | 结果 |
47
+ | --- | --- | --- |
48
+ | `colocad plan TREE.json` | `colocad/1` 特征树 | 编译原生建模任务,不生成几何 |
49
+ | `colocad build TREE.json NEW_DIR --preview` | `colocad/1` 特征树 | STEP、可编辑特征树、报告与预览 |
50
+ | `colocad record MODEL.json SESSION --label TEXT` | 特征树或内核模型 JSON | 构建并追加持久化建模阶段 |
51
+ | `colocad view SESSION` | 已保存会话 | 启动查看器,可加 `--export review.html` |
52
+ | `colocad replay SESSION review.html` | 已保存会话 | 导出离线单文件 HTML |
53
+ | `colocad render SESSION modeling.mp4` | 已保存会话 | 导出四视图动画、时间/哈希清单和封面,也支持 `.gif` |
54
+
55
+ ### 可视化与动画由 CLI 启动
56
+
57
+ ![CLI 建模历史查看器,显示本次 KK60 整机](https://raw.githubusercontent.com/Coloopx/colocad/main/showcase/hiwin-kk60/viewer.png)
58
+
59
+ 查看器提供阶段时间线、特征/源码/回执检查、零件选择与显隐、四种镜头、显示剖切与爆炸,以及模型和最终 STEP 下载。HTML 内嵌代码和几何,可离线打开。宿主界面也可使用 `@coloopx/colocad/viewer` 嵌入同一组件。
60
+
61
+ ```sh
62
+ # 以下依赖仅视频编码需要:
63
+ npm install -D playwright
64
+ npx playwright install chromium
65
+ # 在宿主安装 FFmpeg 后,直接从会话导出:
66
+ npx colocad render ./history ./modeling.mp4 --width 1280 --height 800 --fps 15
67
+ npx colocad render ./history ./modeling.gif --width 960 --height 600 --fps 10
68
+ ```
69
+
70
+ 动画回放实际保存的 CAD 阶段,四个镜头同步显示,并保留每步实测耗时。播放节奏和显示爆炸是展示设置;视频时长不能当作建模耗时。几何构建和 HTML 导出不依赖 Chromium/FFmpeg。[完整使用文档](docs/modeling-history.md)。
71
+
72
+ ### SDK 和 agent skill 如何接入
73
+
74
+ SDK 使用 `CadClient` 直接构建、改参和复用预览;需要持久化过程时使用 `ModelingSession.build / edit`。`createCadTools` 和 `createSessionTools` 给 harness 提供工具 schema 与执行器。[可运行集成示例](examples/integrations/README.md)覆盖 Pi core/extension 和 Codex/Claude 本地 skill 路径,并明确区分脚本化工具测试与真实模型推理。
75
+
76
+ ```sh
77
+ # Codex 项目:复制完整目录,保留脚本、参考文档和可编辑基础形状。
78
+ mkdir -p .agents/skills
79
+ cp -R node_modules/@coloopx/colocad/skills/colocad .agents/skills/colocad
80
+
81
+ # Claude Code 使用 .claude/skills/colocad 路径。
82
+ ```
83
+
84
+ 要求 agent 使用 colocad skill,提供目标产品/尺寸,并交付建模会话、精确 STEP 与 CLI 导出的可视化结果。其他 harness 可直接加载 `skills/colocad/SKILL.md` 并注册 SDK 工具。图纸理解与几何规划由 agent 完成,colocad 执行明确的建模指令。[实际操作流程](docs/modeling-workflow.zh-CN.md) · [Codex](docs/integrations/codex.md) · [Claude Code](docs/integrations/claude-code.md) · [Pi](docs/integrations/pi.md)。
85
+
86
+ ## 真实工业产品:从厂家图纸到整机及建模动画
87
+
88
+ [HIWIN KK60 执行器实例](examples/hiwin-kk60/README.md)对应真实目录配置:300 mm 导轨、5 mm 导程、210 mm 行程,包含 **52 个原生特征、81 个命名实例、16 个持久化建模阶段**。螺旋槽、安装孔、导轨滚道均为实际 B-rep 几何。
89
+
90
+
91
+ [MP4 动画](showcase/hiwin-kk60/modeling.mp4) · [可编辑模型](showcase/hiwin-kk60/model.json) · [独立验证](showcase/hiwin-kk60/verification.json) · [尺寸来源与假设](examples/hiwin-kk60/sources.json)
92
+
93
+ ```sh
94
+ node node_modules/@coloopx/colocad/examples/hiwin-kk60/run.mjs ./actuator
95
+ npx colocad view ./actuator/session
96
+ npx colocad replay ./actuator/session ./actuator.html
97
+ # 视频导出另需 Playwright/Chromium 和 FFmpeg。
98
+ npx colocad render ./actuator/session ./modeling.mp4
99
+ ```
100
+
101
+ 这是依据厂家目录进行的整机复建,未公开的轴承、滚道与回珠细节有明确近似/缺失标注,不能作为制造认证模型。动画读取实际保存的建模结果,播放节奏与实测构建耗时分开显示,不构成 build123d 性能比较。参见[实际操作流程](docs/modeling-workflow.zh-CN.md)和 [CLI 可视化与导出](docs/modeling-history.md)。
102
+
7
103
  ## 100 秒能交付多少版绳驱灵巧手?
8
104
 
9
105
  **colocad 交付 44 版,build123d 交付 33 版:交付量多 33.3%,采样峰值内存低 57.1%。** 两边按同一组参数逐版建模、装配。每条刻线代表一份含 43 个实体的整手 STEP 已写入持久存储。
@@ -45,12 +141,23 @@
45
141
 
46
142
  ## SDK、CLI、skill 怎么选?
47
143
 
48
- 运行 `npm install @coloopx/colocad@0.1.0-alpha.3` 即可安装优化后的装配内核和完整 skill。沙箱内的 harness 可加载 `node_modules/@coloopx/colocad/skills/colocad/SKILL.md`,也可以把整个 `colocad` skill 目录复制到 agent 的技能目录。
144
+ SDK 是基础,CLI / 工具负责执行,skill 提供建模步骤与常用结构。完整文档从[中文开发指南](docs/README.zh-CN.md)开始,包含模型格式、改参、预览复用、失败处理和产物保存。
145
+
146
+ | 使用环境 | 接入文档 |
147
+ | --- | --- |
148
+ | Pi agent core / Pi coding agent | [工具适配器、extension 与 skill](docs/integrations/pi.md) |
149
+ | Claude Code | [项目 skill + 本地 CLI](docs/integrations/claude-code.md) |
150
+ | Codex | [skill 安装、调用与产物检查](docs/integrations/codex.md) |
151
+ | 自建 harness | [同沙箱架构、会话状态与产物生命周期](docs/integrations/overview.md) |
152
+
153
+ [可运行示例与接入回归](examples/integrations/README.md) · [建模最佳实践](docs/best-practices.md) · [常见故障](docs/troubleshooting.md) · [贡献指南](CONTRIBUTING.md)
154
+
155
+ 运行 `npm install @coloopx/colocad@0.1.0-alpha.5` 即可安装优化后的装配内核和完整 skill。沙箱内的 harness 可加载 `node_modules/@coloopx/colocad/skills/colocad/SKILL.md`,也可以把整个 `colocad` skill 目录复制到 agent 的技能目录。
49
156
 
50
157
  常见机械件可以让 agent 直接按尺寸搭建。例如「做一块 100 × 50 × 6 mm 的安装板,钻 3 × 2 个 Ø6 通孔,两向孔距 32 和 30 mm」。skill 自带可改参的孔阵列、轴套、角码、开口壳和四种基础实体。参见[基础形状与结构的命令示例](skills/colocad/references/quick-build.md)。
51
158
 
52
159
  - **应用或 harness 集成:** 进程里直接调用 SDK 的 `build(tree, newDir, { preview: true })`;多实体装配用 `CadClient.build(model)`。
53
- - **终端或沙箱 agent:** 安装 `npm install @coloopx/colocad@0.1.0-alpha.3`;用 `./node_modules/.bin/colocad plan tree.json` 检查特征,再用 `./node_modules/.bin/colocad build tree.json ./new-part --preview`。成品在 `new-part/part/model.step`。全程在同一沙箱内。
160
+ - **终端或沙箱 agent:** 安装 `npm install @coloopx/colocad@0.1.0-alpha.5`;用 `./node_modules/.bin/colocad plan tree.json` 检查特征,再用 `./node_modules/.bin/colocad build tree.json ./new-part --preview`。成品在 `new-part/part/model.step`。全程在同一沙箱内。
54
161
  - **从多视图交给 agent:** 从 [skills/colocad](skills/colocad/SKILL.md) 安装 skill;下个回合输入「用 `$colocad` 读这四张图,生成可编辑模型和 STEP,并标出推断的内部结构」。[完整安装命令、SDK 装配示例和重放步骤](showcase/tendon-hand/README.md#try-it-with-your-agent)。
55
162
 
56
163
  以 Linux arm64 为例,安装后可执行文件就在 `node_modules/@coloopx/colocad/kernel/native/linux-arm64/agent-cad`。npm 分发编译产物;要读或修改 `.rs` 源文件,请用上面的 GitHub 源码链接。
@@ -79,7 +186,7 @@
79
186
  需要 Node.js 22+。输出目录必须是新目录。
80
187
 
81
188
  ```sh
82
- npm install @coloopx/colocad@0.1.0-alpha.3
189
+ npm install @coloopx/colocad@0.1.0-alpha.5
83
190
  npx colocad build node_modules/@coloopx/colocad/examples/manifold.json ./manifold --preview
84
191
  ```
85
192
 
package/bin/colocad.mjs CHANGED
@@ -1,20 +1,44 @@
1
1
  #!/usr/bin/env node
2
2
  import { readFile } from "node:fs/promises";
3
- import { compileTree, build } from "../src/index.mjs";
3
+ import { compileTree, build, kernelModel } from "../src/index.mjs";
4
+ import { ModelingSession, exportSessionHtml } from "../src/session.mjs";
5
+ import { startViewer, parseViewOptions } from "../src/view-server.mjs";
6
+ import { renderSession, parseRenderOptions } from "../src/render.mjs";
4
7
  import { writeSolidWorks } from "../src/solidworks.mjs";
5
8
  const [cmd, input, output, ...flags] = process.argv.slice(2);
6
9
  const help =
7
- "colocad build TREE.json NEW_DIRECTORY [--preview]\ncolocad plan TREE.json\ncolocad solidworks NATIVE-JOB.json NEW_FILE.SLDPRT";
10
+ "colocad build TREE.json NEW_DIRECTORY [--preview]\ncolocad plan TREE.json\ncolocad record MODEL.json SESSION_DIRECTORY [--label TEXT]\ncolocad replay SESSION_DIRECTORY OUTPUT.html\ncolocad view SESSION_DIRECTORY [--no-open] [--port PORT] [--export OUTPUT.html] [--cutaway] [--view iso|front|side|top]\ncolocad render SESSION_DIRECTORY OUTPUT.mp4|OUTPUT.gif [--width N] [--height N] [--fps N] [--seconds-per-step N]\ncolocad solidworks NATIVE-JOB.json NEW_FILE.SLDPRT";
8
11
  try {
9
12
  if (cmd === "--help" || cmd === "-h" || !cmd) console.log(help);
13
+ else if (cmd === "render" && input && output) {
14
+ console.log(JSON.stringify(await renderSession(input,output,parseRenderOptions(flags))));
15
+ }
16
+ else if (cmd === "view" && input) {
17
+ const options=parseViewOptions(process.argv.slice(4));
18
+ const viewer=await startViewer(input,options);
19
+ console.log(JSON.stringify({event:'viewer-ready',url:viewer.url,exportedHtml:viewer.exportedHtml}));
20
+ let closing=false;
21
+ const close=async()=>{if(closing)return;closing=true;await viewer.close();process.exitCode=0;};
22
+ process.once('SIGINT',close);process.once('SIGTERM',close);
23
+ }
24
+ else if (cmd === "replay" && input && output && !flags.length) {
25
+ console.log(JSON.stringify(await exportSessionHtml(input, output)));
26
+ }
10
27
  else {
11
- if (!input || !["plan", "build", "solidworks"].includes(cmd))
28
+ if (!input || !["plan", "build", "solidworks", "record"].includes(cmd))
12
29
  throw Error(help);
13
30
  const raw = await readFile(input);
14
31
  if (raw.length > 2 * 1024 * 1024) throw Error("Input exceeds 2 MiB");
15
32
  const spec = JSON.parse(raw.toString("utf8"));
16
33
  let res;
17
- if (cmd === "plan" && !output) res = compileTree(spec);
34
+ if (cmd === "record" && output && (!flags.length || (flags.length===2 && flags[0]==="--label"))) {
35
+ let session;
36
+ try { session=await ModelingSession.create(output,{wallMs:120000}); }
37
+ catch(error) { if(error.code!=="EEXIST") throw error; session=await ModelingSession.open(output,{wallMs:120000}); }
38
+ res=await session.build(spec.format==="colocad/1"?kernelModel(spec):spec,{label:flags[1]??input});
39
+ if(!res.ok) process.exitCode=1;
40
+ }
41
+ else if (cmd === "plan" && !output) res = compileTree(spec);
18
42
  else if (
19
43
  cmd === "build" &&
20
44
  output &&
package/docs/README.md ADDED
@@ -0,0 +1,28 @@
1
+ # Developer documentation
2
+
3
+ [Actual modeling workflow](modeling-workflow.zh-CN.md) · [CLI modeling history and viewer](modeling-history.md)
4
+
5
+ Build locally with **SDK → CLI/tools → skill**. The skill guides modeling decisions; the SDK and Rust kernel execute them. Agent, harness and CAD process share the same sandbox and filesystem.
6
+
7
+ These guides target **@coloopx/colocad 0.1.0-alpha.5**, Node.js 22+, Linux x64/arm64 or macOS arm64. The project is still alpha; documentation does not imply complete CAD coverage.
8
+
9
+ [中文开发指南](README.zh-CN.md)
10
+
11
+ | Your task | Start here |
12
+ | --- | --- |
13
+ | Prepare materials, design tools/skills/prompts and tune an agent workflow | [End-to-end handbook](agent-modeling-handbook.md), [research basis](agent-modeling-research.md) |
14
+ | Create a part and edit a dimension | [Getting started](getting-started.md) |
15
+ | Choose the model format and understand editability | [Models and artifacts](concepts.md) |
16
+ | Call the SDK, CLI or tools | [API reference](api.md) |
17
+ | Integrate with an existing sandbox/harness | [Integration architecture](integrations/overview.md) |
18
+ | Register tools in Pi agent core or Pi coding agent | [Pi integration](integrations/pi.md) |
19
+ | Use Claude Code | [Claude Code integration](integrations/claude-code.md) |
20
+ | Use Codex | [Codex integration](integrations/codex.md) |
21
+ | Model efficiently from dimensions or views | [Best practices](best-practices.md) |
22
+ | Diagnose a failed call or installation | [Troubleshooting](troubleshooting.md) |
23
+ | Run examples and contribute a change | [Contributing](../CONTRIBUTING.md) |
24
+ | Understand what has actually been tested | [Integration verification](integrations/verification.md), [geometry validation](validation.md) |
25
+
26
+ Runnable adapters and their regression tests live in [examples/integrations](../examples/integrations/README.md). They install the published npm release. The complete Pi example project is in GitHub. Alpha.5 also packages the compact adapter and guided workflow example. The skill, assets and its helper scripts **are** included.
27
+
28
+ Performance depends on workload and execution mode. See the [README measurements](../README.md#how-many-tendon-hands-can-an-agent-deliver-in-100-seconds), with their startup, geometry and memory accounting, before choosing a budget. A 512 MiB CAD benchmark is not a 512 MiB guarantee for a resident LLM harness plus CAD.
@@ -0,0 +1,85 @@
1
+ # 开发与接入指南
2
+
3
+ [实际操作、输入输出与效果提升方法](modeling-workflow.zh-CN.md) · [CLI 查看器与离线导出](modeling-history.md)
4
+
5
+ colocad 的分层是 **SDK 为基础,CLI / 工具负责调用,skill 指导建模流程**。Agent、harness 和 Rust CAD 进程都在同一个沙箱内,共享项目目录。现有 harness 负责模型推理、权限、会话和产物保存,不需要额外部署 CAD 服务。
6
+
7
+ 本文对应 `@coloopx/colocad@0.1.0-alpha.5`,要求 Node.js 22+;预编译内核支持 Linux x64/arm64、macOS arm64。工程仍处于 alpha 阶段。
8
+
9
+ ## 从材料到交付的完整指南
10
+
11
+ [全套建模、skill/提示词与调优指南](agent-modeling-handbook.zh-CN.md)覆盖资料预备、尺寸证据、工具抽象、典型 agent 闭环、验证、失败恢复和性能/质量调优;[研究依据](agent-modeling-research.md)区分公开研究与本仓库实际执行结果。
12
+
13
+ ## 先跑通一个零件
14
+
15
+ 在已有 Node 项目根目录执行;没有 `package.json` 时先运行 `npm init -y`:
16
+
17
+ ```sh
18
+ npm install --save-exact @coloopx/colocad@0.1.0-alpha.5
19
+ ./node_modules/.bin/colocad build \
20
+ node_modules/@coloopx/colocad/examples/manifold.json ./manifold-v1 --preview
21
+ ```
22
+
23
+ 查看 `manifold-v1/part/preview.png`,交付 `model.step`,保留 `feature-tree.json` 和 `report.json`。输出目录必须是新目录。这个示例包含拉伸、盲孔切除、圆角和阵列。
24
+
25
+ 常用结构可以从 skill 的参数模型开始:
26
+
27
+ ```sh
28
+ node node_modules/@coloopx/colocad/skills/colocad/scripts/build.mjs \
29
+ node_modules/@coloopx/colocad/skills/colocad/assets/plate-grid.json \
30
+ ./plate-v1 --set length=100 --set xCount=3 --set xPitch=32 --preview
31
+ ```
32
+
33
+ 命令返回实际 `directory`,其中有 `model.json`、STEP 和预览。这里是 kernel model;上面的歧管是 feature tree。两种格式的入口不同,不能混用。[格式与产物说明](concepts.md) · [完整入门](getting-started.md)
34
+
35
+ ## 接入哪个 harness
36
+
37
+ | 环境 | 推荐方式 | 安装位置 / 调用 |
38
+ | --- | --- | --- |
39
+ | Codex | 完整 skill + 自带终端和图像工具 | 项目 `.agents/skills/colocad`;`$colocad` |
40
+ | Claude Code | 完整 skill + Bash/Read | 项目 `.claude/skills/colocad`;`/colocad` |
41
+ | Pi coding agent | skill;需要直接工具时加 extension | `.agents/skills/colocad` 或 `--skill`;`/skill:colocad` |
42
+ | Pi agent core / 自建 TS harness | `createCadTools` 适配到现有工具注册机制 | 模型、鉴权、输出目录由现有 harness 提供 |
43
+
44
+ 以 Codex 为例,在项目根目录复制完整 skill:
45
+
46
+ ```sh
47
+ mkdir -p .agents/skills
48
+ test ! -e .agents/skills/colocad && \
49
+ cp -R node_modules/@coloopx/colocad/skills/colocad .agents/skills/colocad
50
+ ```
51
+
52
+ 已有 skill 时先检查本地修改,再替换整个目录。Claude Code 将目标目录换为 `.claude/skills/colocad`。不要只复制 `SKILL.md`:脚本、资产和参考文档都需要。
53
+
54
+ 可直接给 agent 的任务:
55
+
56
+ > 用 colocad 做一块 100 × 50 × 6 mm 的安装板,中心对称布置 3 × 2 个 Ø6 通孔,两向孔距 32、30 mm。保留可改参 JSON,导出 STEP,检查俯视和等轴视图,说明采用的基准与推断尺寸,返回产物路径。
57
+
58
+ 各环境的完整命令和验收方法见 [Codex](integrations/codex.md)、[Claude Code](integrations/claude-code.md)、[Pi core / coding agent](integrations/pi.md)。Pi 示例固定到 1.5.0;不要为了接入 CAD 自动升级已有 harness 的 Pi 依赖。旧版本可先采用 skill + CLI,并对自定义工具适配单独回归。
59
+
60
+ ## SDK 接入需要处理的事情
61
+
62
+ 实例化 `new CadClient({ outputRoot, wallMs: 30000 })`,按顺序执行 `validate → build/preview → 检查 → 接受版本`。`outputRoot` 由 harness 决定。`createCadTools` 提供 schema 和执行函数;Pi 适配示例将失败回执变成错误工具结果,并将 PNG 作为图像传回模型。
63
+
64
+ 每个独立建模会话使用自己的 client 和输出根目录;同一会话顺序执行,便于复用特征检查点和网格。`edit` 不会修改传入的模型对象,接受修改后必须保存新 `model.json` 或合并参数,避免下一次改参回退到旧版本。
65
+
66
+ 仅转视角使用缓存预览。观察产物目录可能只有预览;STEP 在 `source_artifact_directory` 指向的几何版本中。沙箱销毁前,用现有 harness 的产物机制保存 JSON、STEP、回执和预览。SDK 没有内置云存储或会话数据库。
67
+
68
+ [架构与生命周期](integrations/overview.md) · [SDK / CLI / 工具 API](api.md) · [可运行示例](../examples/integrations/README.md)
69
+
70
+ ## 建模最佳实践
71
+
72
+ - 从控制外形的截面或毛坯开始;板、轴套、角码、壳体优先参考[快速搭建指南](../skills/colocad/references/quick-build.md),按实际图纸改参数和特征。
73
+ - 先确定单位、基准、接口尺寸和未知项;稳定特征 ID,保留每次接受的参数源。四视图看不到的内部结构要明确标注推断。
74
+ - 重复零件只定义一次,用装配实例定位;物理上独立的关节不要随意融合成一个实体。
75
+ - `validate` 通过只代表预检查。验收还要看实体数、边界、体积、孔深和内部区域;重要交付独立回读 STEP。
76
+ - 失败要报告具体特征。不要为了生成图片静默跳过切孔或圆角;显式降级也应保留在交付说明中。
77
+ - 性能分别测冷启动到 STEP、连续改参、缓存预览、包含推理的完整 agent 周期。CAD 的 512 MiB 基准不等于整个 agent/harness 也只需 512 MiB。
78
+
79
+ [详细最佳实践](best-practices.md) · [常见故障](troubleshooting.md) · [贡献与回归](../CONTRIBUTING.md)
80
+
81
+ ## 当前验证边界
82
+
83
+ 接入示例用已发布 npm 包执行实际 Rust 建模,并经过 Pi core 工具循环、错误恢复、扩展加载和 skill 发现测试。模型回复采用确定性脚本,因此这是接入回归,不是未知图纸上的自主建模成功率测试。Claude Code 尚未做实机推理验收。
84
+
85
+ 参数 JSON 可重建,STEP 是精确几何;二者不等于 SOLIDWORKS 原生特征树。Linux 通用可编辑 `.SLDPRT` 尚未完成,Windows author 尚缺授权软件内的完整回读重建验收。[接入验证范围](integrations/verification.md) · [几何与原生输出验证](validation.md)
@@ -0,0 +1,68 @@
1
+ # Agent CAD handbook
2
+
3
+ A complete workflow for source preparation, modeling tools, agent guidance, validation and tuning. This describes the implemented Colocad alpha.5 interfaces and recommendations informed by actual use and primary sources. It is not a claim of universal optimal prompting or autonomous industrial reconstruction.
4
+
5
+ [完整中文指南](agent-modeling-handbook.zh-CN.md) · [Research and evidence](agent-modeling-research.md) · [Packaged skill](../skills/colocad/SKILL.md)
6
+
7
+ ## Start with the product and its evidence
8
+
9
+ Identify one manufacturer/model/configuration, units, required interfaces and deliverables. The whole product is the target; BOMs, drawings, sections, photographs and reference CAD are inputs describing it. Retain page/view identifiers, revisions and checksums when reproducibility matters. Read the overall page before detailed crops so dimensions remain attached to their datums and extension lines.
10
+
11
+ Separate **specified**, **derived**, **assumed** and **unknown** dimensions. Record formulas for derived quantities and the claims affected by unknowns. An uncalibrated photograph does not establish exact dimensions; a numerical acceptance threshold is not a manufacturer tolerance. Continue independent work when a critical interface is unresolved, while retaining that unresolved claim.
12
+
13
+ The [materials reference](../skills/colocad/references/materials.md) and [filled product brief](../skills/colocad/assets/product-brief.example.json) make this handoff concrete. The brief is evidence metadata, not executable kernel JSON.
14
+
15
+ ## The actual data flow
16
+
17
+ The agent reads text/images using its existing harness tools, decides dimensions and feature dependencies, and writes a generator or explicit model JSON. The local SDK/CLI invokes the Rust kernel; actual measurements, sections and independent STEP checks inform the next correction. Accepted and failed revisions persist in a session. Humans inspect it using `colocad view`, `replay` or `render`.
18
+
19
+ Colocad does not currently expose an automatic image-to-CAD endpoint. The KK60 case used PDF text extraction and rendered-page inspection, followed by an authored feature generator. Enlarging SECTION A-A corrected the screw-axis height to 23 mm. The final 16-stage history, 81-solid assembly and independent checks are [available as an example](../examples/hiwin-kk60/README.md), with proprietary internals explicitly approximated or omitted.
20
+
21
+ ## Keep the tools understandable
22
+
23
+ Register the existing capabilities, validation, build, preview and edit tools first; enable sketch solving or STEP inspection when needed. Preserve schemas and `$defs`. `cad_validate` is input preflight, not a shape check. Plain `cad_edit` takes `{model, parameters}`; recorded editing takes `{parameters}` and uses the accepted source. The harness owns paths, budgets, permissions and artifact retention inside the same sandbox.
24
+
25
+ Return the failing feature/code, revision paths/hashes, relevant geometry and timing, cache information and **all** degradations. Keep complete traces and large meshes on disk. The [compact adapter](../examples/integrations/compact-tools.mjs) implements this without changing execution semantics. The [guided workflow](../examples/integrations/guided-workflow.mjs) performs actual builds, quantitative edits, failure recovery, observation and CLI HTML export:
26
+
27
+ ```sh
28
+ node examples/integrations/guided-workflow.mjs ./out/guided-workflow
29
+ ```
30
+
31
+ This is a scripted contract walkthrough, not live-model inference. [Tool contracts](../skills/colocad/references/tool-contracts.md) explain the complete boundary, including what is not an implemented tool.
32
+
33
+ ## Model and verify meaningful milestones
34
+
35
+ Plan the assembly envelope and interfaces before individual details. Use controlling sections, extrusions/revolutions, real cuts, and loft/sweep only where needed. Link dependent dimensions and placements; reuse part definitions for repeated occurrences. Keep stable semantic IDs and local frames. [Quick structures](../skills/colocad/references/quick-build.md) cover stock, plate patterns, sleeves, brackets and housings.
36
+
37
+ For each meaningful change: validate, build, inspect its receipt and a relevant view, then compare a quantitative check with the target. Repair the specific interpretation/frame/feature that failed. Preserve failures and the accepted source. Do not remove required geometry to obtain a successful receipt. An explicit optional degradation weakens its associated claim.
38
+
39
+ | Claim | Evidence needed |
40
+ | --- | --- |
41
+ | Geometry is valid | Native checks and independent significant STEP readback |
42
+ | Dimensions match | Sourced interface measurements, not appearance alone |
43
+ | Bores/cavities exist | Axes/depths and material checks inside/outside |
44
+ | Design is editable | Actual parameter perturbation and dependent-interface checks |
45
+ | Assembly fits/moves | Required pose checks, relevant clearances/interferences and coupling relations |
46
+ | Manufacturing readiness | Required tolerances, materials, processes and corresponding functional validation |
47
+
48
+ A display explosion is not motion verification. One matching total volume cannot locate a misplaced hole. [Modeling-loop reference](../skills/colocad/references/modeling-loop.md).
49
+
50
+ ## Guide the agent without overloading it
51
+
52
+ The skill entry point routes to materials, modeling loop, tool contracts, prompts, tuning and history. Load only what the current task needs. Give the model a concise task contract and the relevant source views, accepted state and checks. Ask for inspectable dimensions, decisions and artifacts rather than a hidden chain of thought.
53
+
54
+ [Prompt patterns](../skills/colocad/references/prompt-patterns.md) cover the whole-product brief, evidence interpretation, feature planning, targeted repair, fit/edit verification and long-task handoff. They are adaptable examples, not approval gates between every operation or a fixed sequence for a simple part.
55
+
56
+ ## Tune the measured failure
57
+
58
+ Separate interpretation quality from geometry correctness and execution performance. For wrong dimensions, improve source/frame interpretation first. For broken edits, fix dependencies. For tool confusion/context cost, reduce overlap and return focused evidence. For execution time, inspect feature, validation, export and preview timings before optimizing. Reuse clients/checkpoints and shared definitions; reuse a checked mesh for camera-only changes.
59
+
60
+ Comparisons with build123d need the same verified geometry, output requirements, precision, cold/warm policy and hardware limits. Report repeat counts, distributions, failures and memory accounting. An edited film duration is not a benchmark; cached observation is not equivalent to a fresh build. A 512 MiB CAD run does not cover a resident LLM harness or video encoder.
61
+
62
+ To evaluate skill changes, hold source packs, tasks, model/provider versions, tools and budget fixed, change one factor, and retain unseen tasks. Measure dimensions/features, edit preservation, fit claims, unsupported claims, correction count, inference cost and end-to-end time. Scripted regressions prove implementation contracts; they do not prove a prompt's success rate on unseen drawings. [Tuning reference](../skills/colocad/references/tuning.md).
63
+
64
+ ## Deliver reproducible results
65
+
66
+ Return editable source, final exact STEP, the recorded session and requested CLI-exported HTML/movie. Archive the whole session when intermediate STEP files matter; the single HTML includes the final STEP and recorded meshes/receipts. State actual checks and unresolved limitations.
67
+
68
+ [CLI viewer and rendering](modeling-history.md) · [Harness integrations](integrations/overview.md) · [Real industrial-product example](../examples/hiwin-kk60/README.md)