@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.
Files changed (34) hide show
  1. package/README.md +133 -99
  2. package/README.zh-CN.md +145 -79
  3. package/docs/README.md +7 -4
  4. package/docs/README.zh-CN.md +9 -3
  5. package/docs/agent-modeling-handbook.md +68 -0
  6. package/docs/agent-modeling-handbook.zh-CN.md +222 -0
  7. package/docs/agent-modeling-research.md +22 -0
  8. package/docs/api.md +95 -0
  9. package/docs/best-practices.md +45 -0
  10. package/docs/concepts.md +37 -0
  11. package/docs/getting-started.md +53 -0
  12. package/docs/integrations/claude-code.md +52 -0
  13. package/docs/integrations/codex.md +55 -0
  14. package/docs/integrations/overview.md +53 -0
  15. package/docs/integrations/pi.md +73 -0
  16. package/docs/integrations/verification.md +30 -0
  17. package/docs/modeling-workflow.zh-CN.md +77 -0
  18. package/docs/native-solidworks.md +12 -0
  19. package/docs/performance.md +62 -0
  20. package/docs/troubleshooting.md +25 -0
  21. package/docs/validation.md +23 -0
  22. package/examples/hiwin-kk60/README.md +1 -1
  23. package/examples/integrations/README.md +47 -0
  24. package/examples/integrations/compact-tools.mjs +27 -0
  25. package/examples/integrations/guided-workflow.mjs +31 -0
  26. package/kernel/release.json +1 -1
  27. package/package.json +5 -2
  28. package/skills/colocad/SKILL.md +17 -9
  29. package/skills/colocad/assets/product-brief.example.json +20 -0
  30. package/skills/colocad/references/materials.md +37 -0
  31. package/skills/colocad/references/modeling-loop.md +33 -0
  32. package/skills/colocad/references/prompt-patterns.md +70 -0
  33. package/skills/colocad/references/tool-contracts.md +33 -0
  34. package/skills/colocad/references/tuning.md +30 -0
package/README.zh-CN.md CHANGED
@@ -1,129 +1,195 @@
1
- # colocad
1
+ # Colocad
2
2
 
3
- [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)
3
+ ![HIWIN KK60 线性执行器:真实建模与装配过程的四视图回放](showcase/hiwin-kk60/modeling.gif)
4
4
 
5
- 让沙箱内的 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)在本仓库。
5
+ **面向 agent 的参数化 CAD:本地 Rust 几何内核、TypeScript SDK、CLI,以及可追溯的建模过程。**
6
6
 
7
- ## 真实工业产品:从厂家图纸到整机及建模动画
7
+ [English](README.md) · [文档](docs/README.zh-CN.md) · [npm](https://www.npmjs.com/package/@coloopx/colocad) · [Releases](https://github.com/Coloopx/colocad/releases) · [封面模型](examples/hiwin-kk60/README.md)
8
8
 
9
- [HIWIN KK60 执行器实例](examples/hiwin-kk60/README.md)对应真实目录配置:300 mm 导轨、5 mm 导程、210 mm 行程,包含 **52 个原生特征、81 个命名实例、16 个持久化建模阶段**。螺旋槽、安装孔、导轨滚道均为实际 B-rep 几何。
9
+ Colocad 把明确的建模指令转成可编辑源、精确 STEP 和可视化产物。Agent、harness 与 CAD 程序都在**同一个沙箱内部**。npm 包自带编译好的 Rust 内核,安装后建模无需 Python、Rust 工具链、网络或独立 CAD 服务。
10
10
 
11
- ![实际建模记录的四视图回放](showcase/hiwin-kk60/modeling.gif)
11
+ **项目处于 alpha 阶段。** 已有机械零件、装配体、性能记录和可复现示例;尚不能完整替代 build123d,也不等于经过制造验收的 CAD 系统。[支持范围与限制](#支持范围与限制)。
12
12
 
13
- [MP4 动画](showcase/hiwin-kk60/modeling.mp4) · [可编辑模型](showcase/hiwin-kk60/model.json) · [独立验证](showcase/hiwin-kk60/verification.json) · [尺寸来源与假设](examples/hiwin-kk60/sources.json)
13
+ ## 可以用来做什么
14
+
15
+ - **零件和装配体:** 参数化特征、重复零件实例、精确 STEP,以及 PNG/GLB/STL 预览。
16
+ - **Agent 建模:** SDK 工具与随包 skill,支持尺寸解释、特征规划、改参和结果检查。
17
+ - **人类审阅:** 保存成功与失败的构建,检查源和回执,输出单文件离线 HTML、四视图 MP4/GIF。
18
+
19
+ SDK 是基础,CLI 和工具适配器负责接入 harness,skill 指导建模决策。图纸与图片由 agent 作为证据解释;colocad 执行明确的几何指令。
20
+
21
+ ```mermaid
22
+ flowchart LR
23
+ A[Agent + skill] --> H[现有 harness]
24
+ H --> C[CLI / SDK 工具]
25
+ C --> K[本地 Rust 内核]
26
+ K --> F[STEP + 源 + 回执 + 网格]
27
+ F --> V[CLI 查看器 / HTML / 动画]
28
+ ```
29
+
30
+ ## 安装
31
+
32
+ 需要 **Node.js 22+**,支持 **Linux x64、Linux arm64、macOS arm64**。
14
33
 
15
34
  ```sh
16
- node node_modules/@coloopx/colocad/examples/hiwin-kk60/run.mjs ./actuator
17
- npx colocad view ./actuator/session
18
- npx colocad replay ./actuator/session ./actuator.html
19
- # 视频导出另需 Playwright/Chromium 和 FFmpeg。
20
- npx colocad render ./actuator/session ./modeling.mp4
35
+ npm install @coloopx/colocad@0.1.0-alpha.6
21
36
  ```
22
37
 
23
- 这是依据厂家目录进行的整机复建,未公开的轴承、滚道与回珠细节有明确近似/缺失标注,不能作为制造认证模型。动画读取实际保存的建模结果,播放节奏与实测构建耗时分开显示,不构成 build123d 性能比较。参见[实际操作流程](docs/modeling-workflow.zh-CN.md)和 [CLI 可视化与导出](docs/modeling-history.md)。
38
+ 安装包包含 JS/TS API、CLI、原生可执行文件、查看器和完整 skill。Rust 源码位于 [crates/agent-cad](crates/agent-cad),npm 包携带编译产物。[模型与产物格式](docs/concepts.md)。
24
39
 
25
- ## 100 秒能交付多少版绳驱灵巧手?
40
+ ## 快速开始
26
41
 
27
- **colocad 交付 44 版,build123d 交付 33 版:交付量多 33.3%,采样峰值内存低 57.1%。** 两边按同一组参数逐版建模、装配。每条刻线代表一份含 43 个实体的整手 STEP 已写入持久存储。
42
+ 在你的 Node 项目中运行:
28
43
 
29
- ![绳驱灵巧手建模与装配的 10 倍速回放:两边交付 44 和 33 版,采样峰值内存分别为 130.9 和 304.9 MiB。](showcase/tendon-hand/window/hand-window-peak-en.gif)
44
+ ```sh
45
+ # 构建随包歧管示例,保存源、回执和几何。
46
+ npx colocad record node_modules/@coloopx/colocad/examples/manifold.json ./history \
47
+ --label "Build the manifold"
30
48
 
31
- 动图底部显示两边**从开始到当前时刻采到的最高内存**,共用 0–512 MiB 刻度。要看每次建模之间内存如何回落,可打开[瞬时内存回放(MP4)](https://github.com/Coloopx/colocad/raw/refs/heads/main/showcase/tendon-hand/window/hand-window-zh-CN.mp4)或[原始采样](showcase/tendon-hand/evidence/window-optimized.json)。
49
+ # 启动交互式查看器。
50
+ npx colocad view ./history
32
51
 
33
- | 同一改参队列,1 vCPU / 512 MiB | colocad 优化内核 | build123d |
34
- |---|---:|---:|
35
- | 100 秒内交付的完整整手 | **44 份** | 33 份 |
36
- | 首份 STEP | **2.223 s** | 3.010 s |
37
- | 共同前 33 份交付耗时中位数 | **2.234 s** | 2.855 s |
38
- | 连续 100 秒内的最高采样内存 | **130.9 MiB** | 304.9 MiB |
52
+ # 导出单文件 HTML,其中包含最终 STEP 下载。
53
+ npx colocad replay ./history ./review.html
54
+ ```
39
55
 
40
- 各运行一个真实窗口,每版新起 CAD 进程。这次原始记录使用 alpha.2 SDK 和优化后的 Linux arm64 内核。alpha.3 已内置同一份二进制。内存约每 25 ms 采样,包含子进程、临时文件和计入本容器的文件缓存。两边计入的 STEP 都已独立回读。[单文件回放与 STEP 下载](https://github.com/Coloopx/colocad/raw/refs/heads/main/showcase/tendon-hand/window/hand-window.html) · [建模细节与单次原速回放](showcase/tendon-hand/assembly-performance.md)
56
+ 示例包含拉伸、盲孔切除、圆角、线性阵列和口袋。修改 JSON 后再次 `record` 到同一个 history 目录,即可追加版本;失败尝试也会保留。`view` 展示启动时的快照,新增版本后需重新打开。[首个零件与改参教程](docs/getting-started.md)。
41
57
 
42
- 以下静态表记录 npm **0.1.0-alpha.2 自带内核**的历史基线。新进程交付导轨和歧管分别快 22.0× 和 12.9×,峰值内存分别为 build123d 的 7.7% 和 8.0%。
58
+ 也可以通过 SDK 使用相同的本地内核:
43
59
 
44
- <details>
45
- <summary>查看四种任务的静态对照图</summary>
60
+ ```js
61
+ import { ModelingSession } from '@coloopx/colocad/session';
62
+
63
+ const session = await ModelingSession.create('./sdk-history');
64
+ const result = await session.build({
65
+ version: 1, units: 'mm', parameters: { length: 60 },
66
+ features: [{ id: 'stock', op: 'box', origin: [0, 0, 0],
67
+ size: [{ param: 'length' }, 30, 8] }],
68
+ output: 'stock',
69
+ });
70
+ if (!result.ok) throw new Error(JSON.stringify(result.error));
71
+ await session.edit({ length: 80 });
72
+ ```
46
73
 
47
- ![四种任务的交付 STEP 耗时与实测峰值内存](docs/benchmarks/time-to-step.zh-CN.svg)
74
+ 无需记录会话时,直接使用 `CadClient`。[SDK、CLI 与工具 API](docs/api.md)。
48
75
 
49
- </details>
76
+ ## 从 CLI 启动可视化与导出
77
+
78
+ ![CLI 启动的建模历史查看器:KK60 装配体](https://raw.githubusercontent.com/Coloopx/colocad/main/showcase/hiwin-kk60/viewer.png)
50
79
 
51
- | 独立交付物 | 首份 STEP:colocad / build123d | 交付速度比¹ | 沙箱峰值:colocad / build123d | 内存占对方 |
52
- |---|---:|---:|---:|---:|
53
- | 三槽导轨 | 113 / 2,485 ms | **22.0×** | 20.0 / 259.3 MiB | **7.7%** |
54
- | 四盲孔歧管 | 230 / 2,963 ms | **12.9×** | 20.7 / 258.7 MiB | **8.0%** |
55
- | 绳驱手近节指骨 | 259 / 2,244 ms | **8.6×** | 21.4 / 260.1 MiB | **8.2%** |
56
- | 43 实体整手 | 3,952 / 3,293 ms | **0.83×** | 52.7 / 271.3 MiB | **19.4%** |
80
+ 查看时间线、源、特征、回执与选中的零件;切换镜头、显示剖切/爆炸视图、下载产物。离线 HTML 内嵌渲染代码和几何。需要集成到现有界面时,可使用 `@coloopx/colocad/viewer`。
57
81
 
58
- ¹ 速度比为 build123d 用时 ÷ colocad 用时,按未取整的读数计算。Linux arm64、1 vCPU、512 MiB。每组预热后交替运行五轮,**耗时取中位数,内存取五轮容器 cgroup 峰值最大值**。计入启动、导入、建模、后端自身的检查及 STEP 导出;不含安装、容器启动、预览、模型推理或常驻 agent。单件和整手使用各自对应的公开接口。
82
+ | 命令 | 输入 | 结果 |
83
+ | --- | --- | --- |
84
+ | `colocad plan TREE.json` | `colocad/1` 特征树 | 编译并检查原生建模任务 |
85
+ | `colocad build TREE.json NEW_DIR --preview` | 特征树 | STEP、可编辑源和预览 |
86
+ | `colocad record MODEL.json SESSION` | 特征树或 kernel JSON | 构建并保存建模里程碑 |
87
+ | `colocad view SESSION` | 已保存会话 | 本地交互查看器 |
88
+ | `colocad replay SESSION review.html` | 已保存会话 | 单文件离线 HTML |
89
+ | `colocad render SESSION modeling.mp4` | 已保存会话 | 四视图动画,也支持 `.gif` |
59
90
 
60
- [原始读数:导轨与歧管](docs/benchmarks/runs.json) · [原始读数:指骨与整手](showcase/tendon-hand/evidence/scope.json) · [四视图、可编辑整手和 STEP](showcase/tendon-hand/README.md) · [离线数据卡](https://github.com/Coloopx/colocad/raw/refs/heads/main/docs/benchmarks/time-to-step.html)
91
+ 无桌面的沙箱使用 `colocad view ./history --no-open --port 8787`,配合 harness 现有端口转发;监听地址为 `127.0.0.1`。
61
92
 
62
- **旧版整手基线。** 另一项 100 秒、按顺序改参的实测中,colocad 交付 24 份整手 STEP,build123d 交付 30 份;每份都是完整的 43 个实体,已逐件回读。[两端交付时间戳与几何核对](showcase/tendon-hand/evidence/window.json)
93
+ ```sh
94
+ # 可选的视频依赖;还需在宿主安装 FFmpeg。
95
+ npm install -D playwright
96
+ npx playwright install chromium
97
+ npx colocad render ./history ./modeling.mp4 --width 1280 --height 800 --fps 15
98
+ ```
99
+
100
+ 动画读取**实际保存的 CAD 版本**,真实调用耗时与剪辑后的播放时长分别显示。构建几何、导出 HTML 无需 Chromium 或 FFmpeg。[完整历史与渲染指南](docs/modeling-history.md)。
63
101
 
64
- ## SDK、CLI、skill 怎么选?
102
+ ## 接入你的 agent
65
103
 
66
- SDK 是基础,CLI / 工具负责执行,skill 提供建模步骤与常用结构。完整文档从[中文开发指南](docs/README.zh-CN.md)开始,包含模型格式、改参、预览复用、失败处理和产物保存。
104
+ 复制完整 skill,包含 references、scripts 和可编辑形状资产:
67
105
 
68
- | 使用环境 | 接入文档 |
106
+ ```sh
107
+ # Codex 项目技能;Claude Code 改用 .claude/skills。
108
+ mkdir -p .agents/skills
109
+ cp -R node_modules/@coloopx/colocad/skills/colocad .agents/skills/colocad
110
+ ```
111
+
112
+ 已有同名 skill 时,更新前保留本地定制。然后给 agent 一个具体任务:
113
+
114
+ > 使用 colocad skill,构建 100 × 50 × 6 mm 安装板,中心对称布置 3 × 2 个 Ø6 通孔,两向孔距 32、30 mm。保存可编辑源与建模会话,检查尺寸,通过 CLI 导出 STEP 和离线 HTML。
115
+
116
+ | Harness | 接入方式 |
69
117
  | --- | --- |
70
- | Pi agent core / Pi coding agent | [工具适配器、extension 与 skill](docs/integrations/pi.md) |
71
- | Claude Code | [项目 skill + 本地 CLI](docs/integrations/claude-code.md) |
72
- | Codex | [skill 安装、调用与产物检查](docs/integrations/codex.md) |
73
- | 自建 harness | [同沙箱架构、会话状态与产物生命周期](docs/integrations/overview.md) |
118
+ | Codex | [项目 skill 与 CLI](docs/integrations/codex.md) |
119
+ | Claude Code | [项目 skill 与本地工具](docs/integrations/claude-code.md) |
120
+ | Pi core / coding agent | [类型化工具适配与扩展](docs/integrations/pi.md) |
121
+ | 自建 harness | [SDK schema、状态和产物生命周期](docs/integrations/overview.md) |
74
122
 
75
- [可运行示例与接入回归](examples/integrations/README.md) · [建模最佳实践](docs/best-practices.md) · [常见故障](docs/troubleshooting.md) · [贡献指南](CONTRIBUTING.md)
123
+ [完整建模指南](docs/agent-modeling-handbook.zh-CN.md)涵盖材料预备、尺寸不确定性、工具抽象、提示词、建模闭环、验证和调优。[可运行工具示例](examples/integrations/README.md)执行真实建模、数值核对和失败恢复;决策序列是脚本化的,不是 LLM 自主建模成功率测试。
76
124
 
77
- 运行 `npm install @coloopx/colocad@0.1.0-alpha.3` 即可安装优化后的装配内核和完整 skill。沙箱内的 harness 可加载 `node_modules/@coloopx/colocad/skills/colocad/SKILL.md`,也可以把整个 `colocad` skill 目录复制到 agent 的技能目录。
125
+ ## 实例:完整线性执行器
78
126
 
79
- 常见机械件可以让 agent 直接按尺寸搭建。例如「做一块 100 × 50 × 6 mm 的安装板,钻 3 × 2 个 Ø6 通孔,两向孔距 32 和 30 mm」。skill 自带可改参的孔阵列、轴套、角码、开口壳和四种基础实体。参见[基础形状与结构的命令示例](skills/colocad/references/quick-build.md)。
127
+ 封面依据厂家图纸重建 **HIWIN KK60,导轨 300 mm、导程 5 mm、行程 210 mm**,包含 **52 个最终特征、81 个命名实体实例、16 个建模里程碑**。丝杠螺旋槽是实际切出的几何,另有导轨沟槽、安装孔、滑台、轴承和联轴器。
80
128
 
81
- - **应用或 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`。全程在同一沙箱内。
83
- - **从多视图交给 agent:** 从 [skills/colocad](skills/colocad/SKILL.md) 安装 skill;下个回合输入「用 `$colocad` 读这四张图,生成可编辑模型和 STEP,并标出推断的内部结构」。[完整安装命令、SDK 装配示例和重放步骤](showcase/tendon-hand/README.md#try-it-with-your-agent)。
129
+ ```sh
130
+ node node_modules/@coloopx/colocad/examples/hiwin-kk60/run.mjs ./actuator
131
+ npx colocad view ./actuator/session
132
+ npx colocad render ./actuator/session ./modeling.mp4
133
+ ```
84
134
 
85
- 以 Linux arm64 为例,安装后可执行文件就在 `node_modules/@coloopx/colocad/kernel/native/linux-arm64/agent-cad`。npm 分发编译产物;要读或修改 `.rs` 源文件,请用上面的 GitHub 源码链接。
135
+ 独立 OCCT 检查覆盖 16 份 STEP、64 个材料探针和指定位置的导轨/滑台间隙。未公开内部结构明确标为近似或省略;这是产品目录重建,不是可直接生产的完整图纸。动画也不是速度基准。
86
136
 
87
- ## 两个建模后端做出来的东西一样吗?
137
+ [MP4](showcase/hiwin-kk60/modeling.mp4) · [可编辑模型](showcase/hiwin-kk60/model.json) · [验证结果](showcase/hiwin-kk60/verification.json) · [尺寸与假设](examples/hiwin-kk60/sources.json) · [完整离线交付包](https://github.com/Coloopx/colocad/releases/download/v0.1.0-alpha.4/hiwin-kk60-delivery.zip)
88
138
 
89
- ![左列 colocad,右列 build123d。上排为三槽传感器导轨,下排从底部看四盲孔歧管,可见孔列和矩形浅槽。](docs/benchmarks/step-comparison.png)
139
+ ## 性能
90
140
 
91
- 左右两列分别从相同参数独立建模、导出 STEP,再用同一套 OCCT 三角化参数、相机和光照出图。四份 STEP 回读都是有效的单实体。导轨各有 22 个面、56 条边;歧管各有 27 个面、54 条边。两个零件分别做 A−B、B−A,测得差集体积均为 **0 mm³**(布尔容差 0.000001 mm)。[逐件几何核对](docs/benchmarks/step-checks.json)
141
+ 性能取决于几何和执行方式。在同一个 **43 实体绳驱灵巧手**的 100 秒版本队列实测中,Colocad 完成交付 **44 份 STEP,build123d 为 33 份**,最高采样沙箱内存低 **57.1%**。
92
142
 
93
- 只看歧管几何阶段,build123d 是 43.8 ms,colocad 是 53.7 ms;build123d 导入则用了 2.45 s。端到端提速不能当作纯几何运算提速。[分阶段数据与复现方法](benchmarks/readme/README.md)
143
+ ![10 倍速回放:STEP 交付数和截至当前的最高采样沙箱内存](showcase/tendon-hand/window/hand-window-peak-en.gif)
94
144
 
95
- ## 如果 agent 只是转动视角呢?
145
+ | 相同版本队列,1 vCPU / 512 MiB | Colocad | build123d |
146
+ | --- | ---: | ---: |
147
+ | 100 秒完整 STEP 交付 | **44** | 33 |
148
+ | 第一份 STEP | **2.223 s** | 3.010 s |
149
+ | 相同前 33 个输入的任务耗时中位数 | **2.234 s** | 2.855 s |
150
+ | 最高采样 cgroup 内存 | **130.9 MiB** | 304.9 MiB |
96
151
 
97
- 首次预览会保存网格。同一个零件从等轴视图切到俯视图,SDK 可以用 `observeArtifact` 重新出图,跳过精确建模和三角化。同一版 colocad 在同样沙箱预算下得到以下五轮中位数:
152
+ 每个后端运行一个窗口,每次改版新起 CAD 进程。内存约每 25 ms 采样,包含子进程、临时文件和计入容器的文件缓存;所有计数 STEP 均已回读。原始运行使用 alpha.2 SDK 和首次随 alpha.3 发布的优化内核,并非 alpha.6 的新实测。GIF 展示截至当前的最高采样值,而非瞬时内存。[方法与原始数据](showcase/tendon-hand/window/README.md)。
98
153
 
99
- | 切到俯视图 | 完整重建并出图 | 复用网格出图 | 加速比 |
100
- | :--- | ---: | ---: | ---: |
101
- | 导轨 | 108.8 ms | 19.4 ms | **5.6×** |
102
- | 歧管 | 223.8 ms | 13.3 ms | **16.8×** |
154
+ <details>
155
+ <summary>冷启动零件与缓存预览结果</summary>
103
156
 
104
- 每对输出的 PNG、GLB、STL 三个文件均逐字节相同。这一组只比较 colocad 的两条路径;SDK 已加载,计时包括启动本地 Rust 进程和写出显示文件。改几何参数需要生成新版本。[预览耗时和文件哈希](docs/benchmarks/preview-runs.json)
157
+ ![四个历史任务的 STEP 耗时和内存对比](docs/benchmarks/time-to-step.zh-CN.svg)
105
158
 
106
- ## 试跑并改参
159
+ 已发布 alpha.2 内核在传感器导轨、歧管上的 time-to-STEP 分别快 **22.0×、12.9×**,峰值内存分别为 build123d 的 **7.7%、8.0%**。两边在 Linux arm64、1 vCPU / 512 MiB 下预热后各测 5 个独立进程/cgroup;计入启动、导入、建模、校验和导出,不含安装、预览、推理或常驻 agent。这不是所有操作的优势:歧管几何计算为 53.7 ms,而 build123d 为 43.8 ms,旧版完整手模型也曾更慢。
107
160
 
108
- 需要 Node.js 22+。输出目录必须是新目录。
161
+ 对未改变的几何,复用网格观察在两个零件上比 Colocad 自身重建后渲染快 5.6×–16.8×。这是内部缓存路径对比,不是 build123d 对比。
109
162
 
110
- ```sh
111
- npm install @coloopx/colocad@0.1.0-alpha.3
112
- npx colocad build node_modules/@coloopx/colocad/examples/manifold.json ./manifold --preview
113
- ```
163
+ </details>
114
164
 
115
- 打开 `manifold/part/model.step` 检查实体;`preview.png`、`model.glb` 和 `model.stl` 用于查看。歧管由六边形拉伸、盲孔切除、上缘圆角、引用种子孔的线性阵列和矩形浅槽构成。将 `instances` 从 4 改到 3,少切一个 Ø6 × 8 mm 的盲孔,实测恢复材料 **226.195 mm³**,与圆柱体积一致。[验证记录](docs/evidence/scoped-runner.json)
165
+ [完整性能证据与边界](docs/performance.md) · [含 STEP 下载的离线对比](https://github.com/Coloopx/colocad/raw/refs/heads/main/docs/benchmarks/comparison.html)。
116
166
 
117
- ```js
118
- import { readFile } from 'node:fs/promises';
119
- import { build } from '@coloopx/colocad';
167
+ ## 支持范围与限制
168
+
169
+ - 原生包支持 Linux x64/arm64、macOS arm64,要求 Node.js 22+。[发布验证](docs/evidence/release-alpha.6.json)。
170
+ - 支持可编辑 JSON/程序和精确 STEP;STEP 不保存商业 CAD 软件的原生特征树。
171
+ - Linux 通用可编辑 SOLIDWORKS 输出尚未完成。实验性 Windows author 需要授权 SOLIDWORKS,软件内重建验收仍未通过验证。[原生导出状态](docs/native-solidworks.md)。
172
+ - 几何有效、读图正确、可编辑、能配合和可制造需要各自的证据。[验证范围](docs/validation.md)。
173
+ - CAD 的 512 MiB 测试不代表常驻 agent、浏览器和视频编码器的整体内存预算。
174
+
175
+ ## 文档与帮助
120
176
 
121
- const tree = JSON.parse(await readFile('./node_modules/@coloopx/colocad/examples/manifold.json', 'utf8'));
122
- tree.parameters.instances = 3;
123
- const result = await build(tree, './three-port-manifold', { preview: true });
124
- console.log(result.step);
177
+ [入门](docs/getting-started.md) · [API](docs/api.md) · [完整建模指南](docs/agent-modeling-handbook.zh-CN.md) · [Skill](skills/colocad/SKILL.md) · [故障排查](docs/troubleshooting.md) · [全部文档](docs/README.zh-CN.md)
178
+
179
+ 问题和功能建议请[提交 issue](https://github.com/Coloopx/colocad/issues),附上版本、平台、最小模型和相关回执,并移除凭证及私密资料。
180
+
181
+ ## 开发与贡献
182
+
183
+ ```sh
184
+ git clone https://github.com/Coloopx/colocad.git
185
+ cd colocad
186
+ npm ci
187
+ npm run build:kernel
188
+ npm test
125
189
  ```
126
190
 
127
- 公开特征接口支持矩形、圆和多边形草图拉伸、切除、按 Z 平面选边的定半径圆角,以及沿 X/Y 的拉伸或切除阵列。[类型定义](src/index.d.mts) · [更底层的内核 API](kernel/src/client.ts)
191
+ 源码构建需要 Rust 工具链,并拉取固定版本的 SolidCore。查看器、视频和 Pi 接入测试另有依赖;安装、测试和发布方法见 [CONTRIBUTING.md](CONTRIBUTING.md)。欢迎提交 issue 和 pull request。
192
+
193
+ ## 许可证与致谢
128
194
 
129
- **交付边界:** Linux 已验证 STEP、网格和改参。Linux 直接生成复杂、可在 SOLIDWORKS 里编辑和重建的原生 `.SLDPRT` 尚未完成。仓库中的 Windows 作者程序已针对 SOLIDWORKS 2024 接口编译,尚未在有授权的 SOLIDWORKS 上完成回读重建。[验证说明](docs/validation.md) · [从源码构建](README.md#build-and-verify-from-source)
195
+ Colocad 应用代码使用 [MIT 许可证](LICENSE)。内核基于 [SolidCore](https://github.com/tangency-labs/solidcore),其中包含源自 NVIDIA USD BRep / SMLib 的工作;查看器使用 Three.js。依赖许可证与归属见 [NOTICE.md](NOTICE.md) 和 [kernel/licenses](kernel/licenses)。工业实例与 HIWIN 无隶属或背书关系。
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.6**, 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) |
@@ -20,8 +21,10 @@ These guides target **@coloopx/colocad 0.1.0-alpha.3**, Node.js 22+, Linux x64/a
20
21
  | Model efficiently from dimensions or views | [Best practices](best-practices.md) |
21
22
  | Diagnose a failed call or installation | [Troubleshooting](troubleshooting.md) |
22
23
  | Run examples and contribute a change | [Contributing](../CONTRIBUTING.md) |
24
+ | Compare execution performance and limits | [Performance evidence](performance.md) |
25
+ | Check native SOLIDWORKS export status | [Native author](native-solidworks.md) |
23
26
  | Understand what has actually been tested | [Integration verification](integrations/verification.md), [geometry validation](validation.md) |
24
27
 
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.
28
+ Runnable adapters and their regression tests live in [examples/integrations](../examples/integrations/README.md). They install the published npm release. The complete Pi example project is in GitHub. Alpha.5 also packages the compact adapter and guided workflow example. The skill, assets and its helper scripts **are** included.
26
29
 
27
- 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.
30
+ Performance depends on workload and execution mode. See the [README measurements](../README.md#performance), with their startup, geometry and memory accounting, before choosing a budget. A 512 MiB CAD benchmark is not a 512 MiB guarantee for a resident LLM harness plus CAD.
@@ -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.6`,要求 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.6
15
19
  ./node_modules/.bin/colocad build \
16
20
  node_modules/@coloopx/colocad/examples/manifold.json ./manifold-v1 --preview
17
21
  ```
@@ -79,3 +83,5 @@ test ! -e .agents/skills/colocad && \
79
83
  接入示例用已发布 npm 包执行实际 Rust 建模,并经过 Pi core 工具循环、错误恢复、扩展加载和 skill 发现测试。模型回复采用确定性脚本,因此这是接入回归,不是未知图纸上的自主建模成功率测试。Claude Code 尚未做实机推理验收。
80
84
 
81
85
  参数 JSON 可重建,STEP 是精确几何;二者不等于 SOLIDWORKS 原生特征树。Linux 通用可编辑 `.SLDPRT` 尚未完成,Windows author 尚缺授权软件内的完整回读重建验收。[接入验证范围](integrations/verification.md) · [几何与原生输出验证](validation.md)
86
+
87
+ [性能证据与测量边界](performance.md) · [SOLIDWORKS 原生导出状态](native-solidworks.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.6 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)