@coloopx/colocad 0.1.0-alpha.4 → 0.1.0-alpha.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,14 +1,111 @@
1
- # colocad
1
+ # Colocad
2
+
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)
2
6
 
3
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
+
7
105
  ## Reconstruct a real industrial product and replay its modeling history
8
106
 
9
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.
10
108
 
11
- ![Actual native construction and assembly, replayed in four views](showcase/hiwin-kk60/modeling.gif)
12
109
 
13
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)
14
111
 
@@ -74,12 +171,12 @@ The static scorecard below uses the **published alpha.2 binary**. With fresh too
74
171
 
75
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).
76
173
 
77
- 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.
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.
78
175
 
79
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)
80
177
 
81
178
  - **In an application or harness:** call `build(tree, newDir, { preview: true })` in the SDK. Use `CadClient.build(model)` for named multi-solid assemblies.
82
- - **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`.
83
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).
84
181
 
85
182
  ## What the two STEP writers produced
package/README.zh-CN.md CHANGED
@@ -1,14 +1,92 @@
1
1
  # colocad
2
2
 
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
+
3
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
+
7
86
  ## 真实工业产品:从厂家图纸到整机及建模动画
8
87
 
9
88
  [HIWIN KK60 执行器实例](examples/hiwin-kk60/README.md)对应真实目录配置:300 mm 导轨、5 mm 导程、210 mm 行程,包含 **52 个原生特征、81 个命名实例、16 个持久化建模阶段**。螺旋槽、安装孔、导轨滚道均为实际 B-rep 几何。
10
89
 
11
- ![实际建模记录的四视图回放](showcase/hiwin-kk60/modeling.gif)
12
90
 
13
91
  [MP4 动画](showcase/hiwin-kk60/modeling.mp4) · [可编辑模型](showcase/hiwin-kk60/model.json) · [独立验证](showcase/hiwin-kk60/verification.json) · [尺寸来源与假设](examples/hiwin-kk60/sources.json)
14
92
 
@@ -74,12 +152,12 @@ SDK 是基础,CLI / 工具负责执行,skill 提供建模步骤与常用结
74
152
 
75
153
  [可运行示例与接入回归](examples/integrations/README.md) · [建模最佳实践](docs/best-practices.md) · [常见故障](docs/troubleshooting.md) · [贡献指南](CONTRIBUTING.md)
76
154
 
77
- 运行 `npm install @coloopx/colocad@0.1.0-alpha.3` 即可安装优化后的装配内核和完整 skill。沙箱内的 harness 可加载 `node_modules/@coloopx/colocad/skills/colocad/SKILL.md`,也可以把整个 `colocad` skill 目录复制到 agent 的技能目录。
155
+ 运行 `npm install @coloopx/colocad@0.1.0-alpha.5` 即可安装优化后的装配内核和完整 skill。沙箱内的 harness 可加载 `node_modules/@coloopx/colocad/skills/colocad/SKILL.md`,也可以把整个 `colocad` skill 目录复制到 agent 的技能目录。
78
156
 
79
157
  常见机械件可以让 agent 直接按尺寸搭建。例如「做一块 100 × 50 × 6 mm 的安装板,钻 3 × 2 个 Ø6 通孔,两向孔距 32 和 30 mm」。skill 自带可改参的孔阵列、轴套、角码、开口壳和四种基础实体。参见[基础形状与结构的命令示例](skills/colocad/references/quick-build.md)。
80
158
 
81
159
  - **应用或 harness 集成:** 进程里直接调用 SDK 的 `build(tree, newDir, { preview: true })`;多实体装配用 `CadClient.build(model)`。
82
- - **终端或沙箱 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`。全程在同一沙箱内。
83
161
  - **从多视图交给 agent:** 从 [skills/colocad](skills/colocad/SKILL.md) 安装 skill;下个回合输入「用 `$colocad` 读这四张图,生成可编辑模型和 STEP,并标出推断的内部结构」。[完整安装命令、SDK 装配示例和重放步骤](showcase/tendon-hand/README.md#try-it-with-your-agent)。
84
162
 
85
163
  以 Linux arm64 为例,安装后可执行文件就在 `node_modules/@coloopx/colocad/kernel/native/linux-arm64/agent-cad`。npm 分发编译产物;要读或修改 `.rs` 源文件,请用上面的 GitHub 源码链接。
@@ -108,7 +186,7 @@ SDK 是基础,CLI / 工具负责执行,skill 提供建模步骤与常用结
108
186
  需要 Node.js 22+。输出目录必须是新目录。
109
187
 
110
188
  ```sh
111
- npm install @coloopx/colocad@0.1.0-alpha.3
189
+ npm install @coloopx/colocad@0.1.0-alpha.5
112
190
  npx colocad build node_modules/@coloopx/colocad/examples/manifold.json ./manifold --preview
113
191
  ```
114
192
 
package/docs/README.md CHANGED
@@ -1,15 +1,16 @@
1
1
  # Developer documentation
2
2
 
3
- [Actual modeling workflow](modeling-workflow.zh-CN.md) · [CLI modeling history and viewer (development)](modeling-history.md)
3
+ [Actual modeling workflow](modeling-workflow.zh-CN.md) · [CLI modeling history and viewer](modeling-history.md)
4
4
 
5
5
  Build locally with **SDK → CLI/tools → skill**. The skill guides modeling decisions; the SDK and Rust kernel execute them. Agent, harness and CAD process share the same sandbox and filesystem.
6
6
 
7
- These guides target **@coloopx/colocad 0.1.0-alpha.3**, Node.js 22+, Linux x64/arm64 or macOS arm64. The project is still alpha; documentation does not imply complete CAD coverage.
7
+ These guides target **@coloopx/colocad 0.1.0-alpha.5**, Node.js 22+, Linux x64/arm64 or macOS arm64. The project is still alpha; documentation does not imply complete CAD coverage.
8
8
 
9
9
  [中文开发指南](README.zh-CN.md)
10
10
 
11
11
  | Your task | Start here |
12
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) |
13
14
  | Create a part and edit a dimension | [Getting started](getting-started.md) |
14
15
  | Choose the model format and understand editability | [Models and artifacts](concepts.md) |
15
16
  | Call the SDK, CLI or tools | [API reference](api.md) |
@@ -22,6 +23,6 @@ These guides target **@coloopx/colocad 0.1.0-alpha.3**, Node.js 22+, Linux x64/a
22
23
  | Run examples and contribute a change | [Contributing](../CONTRIBUTING.md) |
23
24
  | Understand what has actually been tested | [Integration verification](integrations/verification.md), [geometry validation](validation.md) |
24
25
 
25
- Runnable adapters and their regression tests live in [examples/integrations](../examples/integrations/README.md). They install the published npm release. This example project is in GitHub; it is not included in the alpha.3 npm tarball. The skill, assets and its helper scripts **are** included.
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.
26
27
 
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.
@@ -1,17 +1,21 @@
1
1
  # 开发与接入指南
2
2
 
3
- [实际操作、输入输出与效果提升方法](modeling-workflow.zh-CN.md) · [CLI 查看器与离线导出(开发分支)](modeling-history.md)
3
+ [实际操作、输入输出与效果提升方法](modeling-workflow.zh-CN.md) · [CLI 查看器与离线导出](modeling-history.md)
4
4
 
5
5
  colocad 的分层是 **SDK 为基础,CLI / 工具负责调用,skill 指导建模流程**。Agent、harness 和 Rust CAD 进程都在同一个沙箱内,共享项目目录。现有 harness 负责模型推理、权限、会话和产物保存,不需要额外部署 CAD 服务。
6
6
 
7
- 本文对应 `@coloopx/colocad@0.1.0-alpha.3`,要求 Node.js 22+;预编译内核支持 Linux x64/arm64、macOS arm64。工程仍处于 alpha 阶段。
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)区分公开研究与本仓库实际执行结果。
8
12
 
9
13
  ## 先跑通一个零件
10
14
 
11
15
  在已有 Node 项目根目录执行;没有 `package.json` 时先运行 `npm init -y`:
12
16
 
13
17
  ```sh
14
- npm install --save-exact @coloopx/colocad@0.1.0-alpha.3
18
+ npm install --save-exact @coloopx/colocad@0.1.0-alpha.5
15
19
  ./node_modules/.bin/colocad build \
16
20
  node_modules/@coloopx/colocad/examples/manifold.json ./manifold-v1 --preview
17
21
  ```
@@ -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)
@@ -0,0 +1,222 @@
1
+ # Agent CAD 完整工作指南:资料、工具、建模闭环与调优
2
+
3
+ 本指南对应 colocad alpha.5 的 skill 和可运行示例。目标是把指定产品及其工程依据变成可编辑源、精确几何、可追溯检查和可供人类查看的过程。以下是基于仓库实作和公开资料整理的默认方法,不是已证明适用于所有模型/产品的最优提示词。
4
+
5
+ [English overview](agent-modeling-handbook.md) · [研究依据与适用边界](agent-modeling-research.md) · [随包 skill](../skills/colocad/SKILL.md) · [提示词模板](../skills/colocad/references/prompt-patterns.md) · [真实 KK60 产品](../examples/hiwin-kk60/README.md)
6
+
7
+ ## 1. 先明确输入输出和各层职责
8
+
9
+ **图像不是直接交给 colocad 执行的程序。** 用户可以提供文字要求、图纸/PDF、照片、多视图、BOM 或参考 CAD。Agent 使用其已有的阅读/视觉/检索工具解释证据,决定尺寸、基准和建模操作,再生成明确的 JSON/程序。colocad 确定性执行几何操作。这个边界不能被“图片转参数化指令”一句话省略。
10
+
11
+ ```mermaid
12
+ flowchart TD
13
+ U[用户目标:具体产品、配置、交付要求] --> E[来源、图纸视图、尺寸与未知项]
14
+ E --> P[Agent:整体布局、接口与特征规划]
15
+ P --> M[可编辑程序 / kernel JSON / feature tree]
16
+ M --> C[同一沙箱内的 CLI 或 SDK]
17
+ C --> K[本地 Rust:几何、校验、STEP、网格]
18
+ K --> Q[数值检查 + 相关视图 + 独立 STEP 回读]
19
+ Q -->|具体偏差| P
20
+ Q -->|接受版本| H[持久化会话和交付产物]
21
+ H --> V[colocad view / replay / render]
22
+ ```
23
+
24
+ | 层 | 负责 | 不应混淆的边界 |
25
+ | --- | --- | --- |
26
+ | 用户任务 | 产品、配置、目标精度、交付和授权 | 引用资料中的文字不自动变成新的执行指令 |
27
+ | Agent + skill | 阅读材料、推断、规划、选择工具、解释检查结果 | 模型对某类机械熟悉,不代表掌握该型号的隐藏尺寸 |
28
+ | Harness | 推理、工具绑定、目录、权限、预算和产物保留 | Agent 与 harness 都在沙箱内部;无需新建远程 CAD 调度层 |
29
+ | SDK / CLI | schema、参数/依赖检查、调用内核、会话记录 | 工具返回成功不等于图纸解释正确 |
30
+ | Rust 内核 | B-rep、几何操作、精确 STEP 和预览 | 不负责自动识别图纸或补全未公开制造规范 |
31
+ | 验证器 | 对明确目标做尺寸、材料、拓扑、配合/编辑检查 | 浏览器显示剖切/爆炸不修改精确模型,也不验证运动 |
32
+ | 人类可视化 | 查看阶段、零件、回执;导出 HTML/影片 | 视频播放长度与实际计算耗时分开 |
33
+
34
+ 实际 KK60 案例中,我提取目录文字、渲染整页和局部图,确认变型与基准,再手写 `model.mjs`。放大 SECTION A-A 后把丝杠中心高从误读的 15 mm 改成 23 mm;执行与回读随后验证这个选择。没有运行内置的“任意图纸自动重建模型”。
35
+
36
+ ## 2. 材料预备:先保证证据可以定位
37
+
38
+ ### 2.1 锁定完整产品
39
+
40
+ 记录厂家、型号、配置/长度/导程、版本、选配件、单位和用途。整机是建模目标,零件图和 BOM 是描述它的材料。不要把一个指定执行器替换成几块看起来类似的零件,也不要把为调试准备的小样例当作最终产品。
41
+
42
+ 优先寻找该配置的总装尺寸图、接口图、剖面、参数表和实物外观。零件/内部细节资料缺失时,分别写明可验证的外部接口和无法证实的内部结构。若有参考 CAD,可保留给验收;如果将其直接导入,应明确这是导入或复用,不宣称重新建模。
43
+
44
+ ### 2.2 为图像提供上下文
45
+
46
+ 保留原文件和 URL、日期/图纸版本、页码、文件哈希。先看完整页面确定单位、投影/剖视和表格对应,再裁出当前接口的可读细节,标明它来自哪里。不要只给一个没有基准和尺寸延长线的数字裁图。
47
+
48
+ ```sh
49
+ pdftotext -layout catalog.pdf catalog.txt
50
+ pdftoppm -f 25 -singlefile -scale-to 2400 -png catalog.pdf page-25
51
+ ```
52
+
53
+ 文字提取用来查找数值;图像用于判断数值属于哪个尺寸、视图或零件。照片可辅助外形和装配关系,未经标定的透视图片不能直接给出精确尺寸。多视图有助于消歧,但不能揭示所有隐藏通道或公差。
54
+
55
+ ### 2.3 建立尺寸与接口证据表
56
+
57
+ | 状态 | 保存什么 | 本次案例 |
58
+ | --- | --- | --- |
59
+ | 图纸给定 specified | 数值、单位、页/视图/标注位置 | 丝杠中心高 23 mm、滑台高 33 mm |
60
+ | 关系推导 derived | 表达式、依赖尺寸和基准 | 安装孔站位由 G、孔距和导轨端点推导 |
61
+ | 暂时假设 assumed | 数值/范围、理由、影响的结论 | 未公开轴承滚道尺寸 |
62
+ | 未知 unknown | 缺失内容和不能验证的事项 | 螺母回珠通道 |
63
+
64
+ 定义一个整机坐标系,另为每个零件定义局部 frame。检查直径/半径、通孔/盲孔、深度起点、正常/特殊滑块、角度方向和尺寸表行列。把“重建验收误差”与厂家制造公差分开;自己选择的 0.01 mm 检查阈值不能被写成厂家公差。
65
+
66
+ 需要保证的接口仍有关键未知时,指出缺失的具体值及影响,继续独立部分。不要为每一个非关键假设都停下来要求确认,也不要把未知静默改成确定值。[详细材料规则](../skills/colocad/references/materials.md) · [填好的产品 brief 示例](../skills/colocad/assets/product-brief.example.json)。
67
+
68
+ 推荐任务目录:
69
+
70
+ ```text
71
+ sources/ 原始来源索引、图纸页、必要局部图
72
+ product-brief.json 产品配置、尺寸状态、接口、验收范围(任务数据)
73
+ model.mjs 可编辑生成程序(需要程序化重复结构时)
74
+ model.json 实际送入内核的几何指令
75
+ session/ 每次输入、回执、STEP、网格和失败记录
76
+ verification.json 执行过的检查、数值、来源和未覆盖项
77
+ review.html CLI 导出的单文件查看器
78
+ modeling.mp4 可选;CLI 导出的实际阶段回放
79
+ ```
80
+
81
+ `product-brief.json` 是本指南的资料约定,不是内核接受的新 schema。不要把溯源字段随意塞进 `additionalProperties: false` 的 kernel JSON。
82
+
83
+ ## 3. 工具抽象:从下一步决策设计接口
84
+
85
+ 保留 SDK 的完整 schema 和引用定义,工具层选择少量明确的动作。不要给每个库函数都生成一个远程工具,也不要把所有工作藏在一个没有可检查结果的“生成产品”调用里。
86
+
87
+ | 实际可用入口 | 什么时候用 | Agent 应读取什么 |
88
+ | --- | --- | --- |
89
+ | `cad_capabilities` | 会话开始、选择不熟悉操作时 | 版本、操作、预算、明确不支持项 |
90
+ | `cad_validate` | 开始昂贵构建前 | 参数、依赖和预算错误;它不执行几何验证 |
91
+ | `cad_build` | 一个有意义的特征/接口阶段 | `ok`、几何、失败特征、时间、产物及降级 |
92
+ | `cad_preview` | 观察新的几何或换相关视角 | 实际图像;是否复用网格、源几何目录 |
93
+ | `cad_edit` | 修改已有命名参数 | 新版本尺寸、依赖是否跟随、接受的源 |
94
+ | `cad_solve_sketch` | 确实需要草图约束时 | 局部 DOF、约束残差与冲突 |
95
+ | `cad_inspect_step` | 需要检查/复用已登记 STEP 时 | 产品树、共享定义和变换、导入限制 |
96
+
97
+ 默认可先注册前五项,按任务加入后两项。`CadClient.inspect` 读取保存的报告,不是任意几何查询器;当前工具集也没有自动图纸尺寸识别工具。材料阅读使用现有 harness 的文件/图像工具,独立精确检查使用明确的几何验证程序。
98
+
99
+ 直接 `createCadTools(client)` 的 `cad_edit` 参数是 `{model, parameters}`;`createSessionTools(session)` 的参数是 `{parameters}`,由会话读取最后成功的源。接入时保留这个区别,避免失败后从错误或过时的模型开始改参。
100
+
101
+ ### 3.1 工具返回摘要,不丢失证据
102
+
103
+ 模型通常需要:错误码/feature ID、版本与产物路径、实体数、尺寸/体积、当前相关测量、时间、缓存命中和全部降级项。完整 feature trace、模型和网格保存在文件里,必要时按引用读取。不要每轮把 STEP 文本、大网格和全部历史图片塞回上下文。
104
+
105
+ [compact-tools.mjs](../examples/integrations/compact-tools.mjs) 是实际可运行的无传输层适配器:保持工具 schema/执行语义,压缩成功回执,保留失败/降级与完整回执路径。宿主负责把 `ok:false` 映射为其工具错误格式,并按需要附上 PNG。它是示例适配器,不是额外的 CAD 后台服务。
106
+
107
+ ### 3.2 执行一个完整工具闭环
108
+
109
+ ```sh
110
+ # 源码 checkout
111
+ node examples/integrations/guided-workflow.mjs ./out/guided-workflow
112
+ # 或安装包内的同一示例
113
+ node node_modules/@coloopx/colocad/examples/integrations/guided-workflow.mjs ./guided-workflow
114
+ ```
115
+
116
+ 这个例子实际执行能力查询、校验、建模、孔径修改、体积核对、失败改参、恢复接受的源、缓存观察、长度修改,最后通过 CLI 输出 HTML。检查孔径变化应移除的材料体积和最终长度。它证明工具契约和闭环实现可运行;决策序列是脚本化的,不宣称某个 LLM 在未知图纸上自主完成了这些步骤。
117
+
118
+ ## 4. 典型建模环节与信息流
119
+
120
+ | 环节 | 输入上下文 | Agent 的操作 | 输出和验收 |
121
+ | --- | --- | --- | --- |
122
+ | 目标定义 | 用户目标、产品配置 | 确定整体交付和必须保持的接口 | 产品 brief、成功条件 |
123
+ | 解释材料 | 当前接口的总图/剖面/表格 | 对应视图、建立尺寸证据和基准 | 带来源和不确定性的尺寸表 |
124
+ | 布局与特征规划 | 尺寸、接口、已有参数源 | 唯一零件定义、实例、依赖和局部 frame | 特征计划与具体检查 |
125
+ | 构建 | 当前明确 JSON | validate 后执行 build/record | 新版本、回执、精确几何 |
126
+ | 定向检查 | 变化特征及目标值 | 相关投影/剖面、数值/材料/配合检查 | 偏差和证据;接受或修复 |
127
+ | 改参验证 | 被接受的源和目标变更 | 改主参数、重建、复查依赖接口 | 可编辑性证据,保留失败 |
128
+ | 整机与交付 | 所有部件、必要姿态 | 组合检查、独立 STEP 回读 | 整机 STEP、会话、结果报告 |
129
+ | 人类审阅 | 已保存的真实结果 | CLI view/replay/render | 查看器、单文件 HTML、动画 |
130
+
131
+ 简单零件可合并这些环节。长任务在有工程意义的节点保存里程碑:截面/毛坯、关键孔腔、相配接口、子总成、整机。只记录零件放置不能解释建模过程;每一条微小操作都单独启动一轮模型推理也不经济。
132
+
133
+ ### 4.1 参数和特征设计
134
+
135
+ 从控制外形的截面开始。板/轴/球/锥可用单特征;套筒用带孔截面;壳体用壁厚/底厚和开口关系;重复孔用原生孔阵列;重复零件只建一个定义再实例化。优先复用[快速搭建资产](../skills/colocad/references/quick-build.md),替换实际参数和必要特征,避免从任意网格逼近规则结构。
136
+
137
+ 把中心对称、共轴、厚度、孔距和运动关系写为参数表达式。使用稳定的语义 feature ID、零件 ID 和明确局部坐标。几何引用和约束需要在编辑后仍表达设计意图,不能只让原始形状看起来对。[DIP-CAD 的研究](https://arxiv.org/abs/2609.22688v4)也将引用、局部坐标和编辑后依赖保持作为独立问题;其结果不等于本库已经获得相同成功率。
138
+
139
+ ### 4.2 失败恢复
140
+
141
+ 先分辨是读图错误、frame/单位、参数依赖、几何操作、预算、预览,还是工具传输失败。查看具体 feature ID、操作数和错误,缩小到能复现问题的子模型;不要同时改一批无关尺寸。
142
+
143
+ 保留失败输入和回执,从最后接受的源修复。不要靠删掉必需的孔、螺旋槽、圆角来换一个成功状态。用户明确允许的可选省略才可以降低对应交付范围,并保留降级说明。新证据应更新来源/假设记录,而非只改模型里的一个数值。
144
+
145
+ KK60 的真实螺旋槽让总装触发内部 STEP 实体数限制,最终修复的是内部序列化预算,同时维持外部导入限制;没有减少 56 圈螺纹来绕过问题。四视图镜头裁切则通过正交取景和包络测试修复,没有缩短精确模型。
146
+
147
+ ## 5. 提示词和 skill 怎么组织
148
+
149
+ `SKILL.md` 保留能力范围、入口选择和关键判断;材料处理、完整产品循环、工具契约、提示词、调优、可视化分别在按需读取的 references 中。基础形状和产品 brief 放 assets,确定性执行放 scripts/examples。不要把整份工程手册和所有例外都常驻系统提示。这与 [Anthropic 的 skill 编写建议](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)关于简洁、按需披露和按任务脆弱程度约束行为的原则一致。
150
+
151
+ 可以直接使用的任务提示:
152
+
153
+ ```text
154
+ 使用 colocad skill,依据提供的厂家/型号/配置材料重建完整产品。
155
+ 交付可编辑源、整机 STEP、建模会话,以及由 CLI 导出的离线 HTML 和指定动画。
156
+ 先确定单位、整体基准和关键接口;区分给定、推导、假设、未知尺寸。
157
+ 图像作为证据,由你解释并生成明确建模指令,不把未知隐藏结构写成确定制造尺寸。
158
+ 在有意义的几何/装配里程碑执行构建,检查相关视图和具体数值偏差。
159
+ 失败保留输入与回执,针对原因修复,不能省略必需几何来宣称成功。
160
+ 按目标做改参/配合/STEP 回读检查,列出实际通过与未覆盖的内容。
161
+ ```
162
+
163
+ 后续轮次只提供当前子系统所需的材料、接口、接受源和检查结果。修复提示写出错误/偏差和稳定 ID;检查提示写明目标值、误差和对应主张。长任务交接保留产品、基准、源文件/哈希、已通过检查、失败、未知项和下一项检查。[分阶段提示词](../skills/colocad/references/prompt-patterns.md)可按任务直接调整。
164
+
165
+ 这不是要求模型输出隐含推理链。需要的是可检查的尺寸表、设计决策、程序、执行结果和结论依据。
166
+
167
+ ## 6. 质量验收:把结论拆开
168
+
169
+ | 结论 | 需要的证据 | 单独不足以证明它的结果 |
170
+ | --- | --- | --- |
171
+ | 几何有效 | 实体/壳体有效性、体积、STEP 回读 | 进程退出 0 |
172
+ | 符合尺寸 | 有来源的关键尺寸和定位检查 | 单张漂亮渲染 |
173
+ | 内部孔腔正确 | 孔轴/直径/深度、内外材料点和剖面 | 外轮廓或总体积相似 |
174
+ | 可编辑 | 实际改变主参数,复查关联几何/接口 | JSON 里有 parameters 字段 |
175
+ | 能装配/运动 | 所需姿态和相关零件对的干涉/间隙、耦合关系 | 爆炸视图和插值动画 |
176
+ | 制造可用 | 必需公差、材料、工艺、功能/强度等相应验证 | 目录接口复建 |
177
+
178
+ [Parametric CAD Bench v3](https://arxiv.org/abs/2611.02659v1)把几何、规格和建模历史纳入评估,并区分创建、改参和工程图重建;它评的是完整 agent 系统。这里借用这种分开验收的思路,不把外部榜单成绩转写为 colocad 的成绩。
179
+
180
+ 本仓库的实证是:KK60 16 个阶段独立 STEP 回读、64 个材料探针、三个位置的特定导轨/滑块检查,以及工具/查看器/CLI 集成回归。未公开回珠通道、全部零件对干涉、载荷/寿命和制造公差仍不在通过项中。
181
+
182
+ ## 7. 调优:对准测量到的瓶颈
183
+
184
+ ### 7.1 理解与建模质量
185
+
186
+ - 尺寸错:先核对标注归属、单位、直径/半径、视图与局部 frame;增加清晰局部证据,不先加大推理长度。
187
+ - 编辑破坏关系:减少重复常量,绑定共用参数/基准;增加有意义的参数扰动检查。
188
+ - 工具选择反复:消除语义重叠,保留少量明确工具;按需载入 schema/reference,返回足够定位的错误。
189
+ - 上下文过大:保存详细工件,用路径/哈希引用;每轮加载相关图和摘要,避免重复发送全部网格/日志。
190
+
191
+ [工具设计建议](https://www.anthropic.com/research/writing-tools-for-agents)强调清晰职责、可操作反馈和有针对性的评估;[上下文工程建议](https://www.anthropic.com/research/effective-context-engineering-for-ai-agents)强调按需检索与保存关键状态。本指南的具体工具选择、回执字段和材料结构来自 colocad 的实际接口,不是直接套用外部产品的 API。
192
+
193
+ ### 7.2 执行性能与资源
194
+
195
+ 分开计时:资料读取/推理、进程启动、几何、校验、STEP、三角化、视图渲染、视频编码。先看 per-feature/native timings,再决定优化算法、共享定义、参数重算、缓存或显示精度。
196
+
197
+ 同一任务顺序复用 client/session。重复零件复用定义;只换镜头时复用已校验网格。预览可选择适合观察的精度,但比较时要固定参数。影片编码另外需要浏览器与 FFmpeg,不包含在纯几何运行的资源结论中。
198
+
199
+ 与 build123d 比较时固定输入几何、实例、精度、交付工件、环境和冷/热启动模式;先验证两边几何等价。报告重复次数、分布、失败和测量范围。内存明确 RSS/进程和/cgroup、采样频率、瞬时值还是截至当前峰值。保留原始采样;用峰值曲线展示时不能称为瞬时内存。
200
+
201
+ 本次 KK60 单次 Linux arm64、1 vCPU/512 MiB、禁网、含预览的原生总耗时为 24.192 秒;未测该次内存峰值,也未做同模型 build123d 对照。这个结果不能推导整个 resident agent/harness 或 Chromium 也只需要 512 MiB。[证据](../showcase/hiwin-kk60/evidence.json)。
202
+
203
+ ### 7.3 如何证明 skill/提示词真的更好
204
+
205
+ 固定资料包、目标产品、模型/provider 版本、工具、预算和随机设置,对比旧 skill 与单项改动。覆盖明确尺寸件、需要剖视解释的零件、编辑后仍须配合的装配和有歧义的材料;留出未参与调优的任务。测关键尺寸/特征、编辑保持、接口检查、无依据结论、修改次数、推理成本和端到端时间。
206
+
207
+ 先运行确定性契约回归,再做使用真实模型的对照评估。不能把工具脚本测试、一次成功案例或引用论文直接说成提示词优化成功率。当前新增指南经过链接/skill 校验、实际工具流程和打包回归;没有宣称完成跨模型盲测。
208
+
209
+ ## 8. 运行、审阅与交付
210
+
211
+ ```sh
212
+ npm install @coloopx/colocad@0.1.0-alpha.5
213
+ node node_modules/@coloopx/colocad/examples/hiwin-kk60/run.mjs ./actuator
214
+ npx colocad view ./actuator/session
215
+ npx colocad replay ./actuator/session ./actuator.html
216
+ # 已安装可选 Chromium / FFmpeg 时:
217
+ npx colocad render ./actuator/session ./modeling.mp4
218
+ ```
219
+
220
+ 完整会话应随 sandbox 产物保留。单文件 HTML 带模型、回执、网格和最终 STEP;需要所有中间 STEP 时交付完整 session 目录。给出具体文件、检查数值和限制,保留可重新执行的源,不只交一张图或一句“成功”。
221
+
222
+ [接入 Pi / Claude Code / Codex](integrations/overview.md) · [SDK/CLI API](api.md) · [历史与动画](modeling-history.md) · [故障排查](troubleshooting.md)