parapoly-runtime 1.0.0 → 1.0.2

package/README.md

@@ -35,6 +35,25 @@ node node_modules/parapoly-runtime/cli/code3d-build.js ./my-project
 | `[workspace-dir]` | 项目目录路径（含 package.json），默认当前目录 |
 | `--no-bin` | 输出纯文本 .code3d.js（默认输出 gzip 的 .code3d.js.bin） |
 
+## Install AI Instructions
+
+安装 Code3D AI 编程辅助指令到当前项目（让 GitHub Copilot 等 AI 了解 Code3D API 规范）：
+
+```bash
+code3d-install-instructions
+
+# 或通过 node 直接运行
+node node_modules/parapoly-runtime/cli/code3d-install-instructions.js
+```
+
+或指定目标目录：
+
+```bash
+code3d-install-instructions ./my-project
+```
+
+安装后会在项目中生成 `.github/instructions/` 目录，AI 编程助手会自动读取其中的规范。
+
 ## Uninstall
 
 ```bash

package/cli/code3d-install-instructions.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+/**
+ * code3d-install-instructions CLI — 安装 Code3D AI 辅助编程指令文件
+ * 
+ * 用法:
+ *   code3d-install-instructions [target-dir]
+ * 
+ * 参数:
+ *   target-dir   目标项目目录，默认为当前目录
+ * 
+ * 功能:
+ *   将 Code3D 的 AI instructions 文件安装到目标项目的 .github/instructions/ 目录。
+ *   这些文件让 GitHub Copilot 等 AI 编程助手了解 Code3D 项目规范和 API，
+ *   从而在编写 .code3d.js 文件时提供更准确的代码建议。
+ * 
+ * 安装的文件:
+ *   .github/instructions/code3d-project-workspace.instructions.md
+ *   .github/instructions/code3d.instructions.md
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const targetDir = path.resolve(process.argv[2] || ".");
+const instructionsSource = path.join(__dirname, "..", "instructions");
+const instructionsTarget = path.join(targetDir, ".github", "instructions");
+
+// Validate target is a project directory
+if (!fs.existsSync(path.join(targetDir, "package.json"))) {
+    console.error(`❌ 目标目录不是一个有效的项目（未找到 package.json）: ${targetDir}`);
+    console.error("   用法: code3d-install-instructions [project-dir]");
+    process.exit(1);
+}
+
+// Validate source
+if (!fs.existsSync(instructionsSource)) {
+    console.error("❌ instructions/ 目录未找到，npm 包可能不完整。");
+    process.exit(1);
+}
+
+// Get instruction files
+const files = fs.readdirSync(instructionsSource).filter(f => f.endsWith(".instructions.md"));
+if (files.length === 0) {
+    console.error("❌ 未找到 .instructions.md 文件。");
+    process.exit(1);
+}
+
+// Create target directory and copy
+fs.mkdirSync(instructionsTarget, { recursive: true });
+
+console.log(`\n📋 安装 Code3D AI instructions 到: ${path.relative(process.cwd(), instructionsTarget) || instructionsTarget}\n`);
+
+let installed = 0;
+for (const file of files) {
+    const src = path.join(instructionsSource, file);
+    const dest = path.join(instructionsTarget, file);
+    const exists = fs.existsSync(dest);
+    fs.copyFileSync(src, dest);
+    console.log(`  ${exists ? "🔄" : "✅"} ${file}${exists ? " (已覆盖)" : ""}`);
+    installed++;
+}
+
+console.log(`\n✅ 已安装 ${installed} 个 AI instruction 文件。`);
+console.log("   GitHub Copilot 等 AI 编程助手将在编写 .code3d.js 时自动参考这些规范。\n");

package/instructions/code3d-project-workspace.instructions.md

@@ -0,0 +1,637 @@
+---
+applyTo: "**/code3d-workspace-config.json,**/package.json,**/*.code3d.js,**/.parapoly/**,**/*.part3d"
+description: "Code3D / 国基3D / 国基CAD 项目工作区规范：项目结构、模块编写、编译流程、多色组装等。适用于所有 code3d 3D 建模项目。"
+---
+# Code3D Project Workspace — AI 辅助 3D 建模指南
+
+当用户要求构建多文件 3D 项目时，按本规范组织代码和编译。
+
+## 项目结构
+
+```
+my-project/
+├── package.json                  # 项目名称/版本/入口（必须）
+├── code3d-workspace-config.json  # 编译配置（可选）
+├── .gitignore                    # 忽略 dist 输出目录
+├── main.code3d.js                # 入口文件
+├── .parapoly/                    # 运行时工具（由模板提供）
+│   └── parapoly-runtime/         # parapoly-runtime npm 包
+│       ├── parapoly_runtime.js
+│       ├── parapoly_runtime.d.ts
+│       ├── cli/
+│       │   └── code3d-build.js   # 编译 CLI
+│       ├── package.json
+│       └── README.md
+├── parts/                        # 子模块
+│   ├── wall.code3d.js
+│   └── details/
+│       └── window.code3d.js
+├── assets/                       # .part3d 资源文件
+│   └── model.part3d
+└── dist/                         # 编译输出（只生成一个文件）
+    └── project-name.code3d.js.bin
+```
+
+## 配置文件
+
+### package.json（必须）
+
+```json
+{
+    "name": "project-name",
+    "version": "1.0.0",
+    "main": "main.code3d.js"
+}
+```
+
+### code3d-workspace-config.json（可选，编译设置）
+
+```json
+{
+    "build": {
+        "output": "dist",
+        "bin": true
+    }
+}
+```
+
+## 模块编写规范
+
+每个 `.code3d.js` 必须：
+1. 定义 `let main = function(params) { ... }` 
+2. 返回 `PartBlock3dDocument` 实例
+3. 通过 `params` 接收参数（可选）
+
+```javascript
+let main = function(params) {
+    let block3d_doc = new PartBlock3dDocument()
+    let width = params?.width || 10
+    let height = params?.height || 8
+
+    // 构建几何
+    block3d_doc.box("union", width, height, 0.5, "#d4a574")
+
+    // 引用子模块
+    let window = use("./details/window.code3d.js", { size: 2 })
+    block3d_doc.add_part(window, "union", "window1")
+    block3d_doc.translate(3, 5, 0.3)
+
+    return block3d_doc
+}
+```
+
+## use() 函数
+
+### 语法
+```javascript
+let result = use(path, params)
+```
+
+- **path**: 模块路径（字符串）
+- **params**: 可选参数对象
+- **返回值**: `PartBlock3dDocument` 实例
+
+### 路径格式
+
+```javascript
+// 相对路径
+let wall = use("./parts/wall.code3d.js", { width: 10 })
+
+// 绝对路径
+let shell = use("E:/models/part.part3d", { recompile: true })
+
+// HTTP/HTTPS 远程文件
+let gun = use("https://poly.keepwork.com/parapoly-projects/block3d/1003_水枪.code3d.js")
+```
+
+### .part3d 参数
+
+```javascript
+use("./model.part3d")                        // 使用预编译数据
+use("./model.part3d", { recompile: true })   // 强制重新编译
+use("./model.part3d", { color: "#ff0000" })  // 覆盖颜色
+```
+
+## add_part() — 组合子文档
+
+将 `use()` 返回的文档组合到当前文档：
+
+```javascript
+let child = use("./child.code3d.js", { size: 5 })
+block3d_doc.add_part(child, "union", "child_name")
+block3d_doc.translate(x, y, z)   // 定位
+```
+
+参数：`add_part(doc, boolOp, nodeName, color?)`
+- `doc`: use() 返回的 PartBlock3dDocument
+- `boolOp`: `"union"` | `"difference"` | `"intersection"`
+- `nodeName`: 节点名（字符串，在当前文档内唯一）
+- `color`: 可选覆盖颜色
+
+## 编译
+
+### 命令
+
+```bash
+# 在项目目录运行（默认输出 .code3d.js.bin）
+node .parapoly/parapoly-runtime/cli/code3d-build.js
+
+# 指定项目目录
+node .parapoly/parapoly-runtime/cli/code3d-build.js ./my-project
+
+# 强制输出纯文本 .code3d.js
+node .parapoly/parapoly-runtime/cli/code3d-build.js --no-bin
+```
+
+### 编译流程
+
+1. 读取 `package.json` 和 `code3d-workspace-config.json`
+2. 收集所有 `.code3d.js` 和 `.part3d` 文件
+3. **语法检查**：验证 main 函数、return 语句、JS 语法
+4. 分析 `use()` 依赖，构建依赖图，检测循环依赖
+5. 下载远程文件，读取绝对路径文件
+6. 拓扑排序，生成单文件 bundle
+7. 可选输出 `.bin`（gzip 压缩，压缩率约 85-90%）
+
+### 编译错误定位
+
+编译和运行时错误会显示文件名和行号：
+```
+✗ ./parts/wall.code3d.js (行 12): Unexpected token '}'
+[./fence.code3d.js (行 14, 列 5)] xxxx is not defined
+```
+
+## 设计拆分原则
+
+将复杂模型拆分为多文件时遵循：
+
+1. **按功能拆分**：每个独立零件/组件一个文件
+2. **参数化复用**：相同形状不同尺寸通过 params 传递
+3. **层级嵌套**：入口 → 组件 → 子部件 → 细节（最多 3-4 级）
+4. **文件命名**：用功能描述命名，如 `wall.code3d.js`、`window.code3d.js`
+
+### 拆分示例：房屋场景
+
+```
+main.code3d.js          ← 场景入口：组合所有部件
+├── house.code3d.js     ← 房子：墙+门+屋顶
+│   ├── parts/wall.code3d.js    ← 墙体（含窗户）
+│   │   └── parts/details/window.code3d.js
+│   ├── parts/door.code3d.js
+│   └── parts/roof.code3d.js
+├── garden.code3d.js    ← 花园：树木+地面
+├── fence.code3d.js     ← 围栏（参数化长度）
+└── chimney.code3d.js   ← 烟囱
+```
+
+## 注意事项
+
+- `use()` 是同步的，文件在执行前已预加载
+- 相同 path+params 的 `use()` 调用会被缓存
+- 注释行中的 `use()` 不会被编译器收集
+- `.part3d` 的 UTF-8 BOM 会被自动剥离
+- 远程文件编译时下载嵌入，运行时无需网络
+- 编辑器打开 `.bin` 文件会自动解压加载
+
+## 子模块构建方向与组装
+
+子模块应在自身坐标系中沿正方向构建，由调用方通过 `rotate` + `translate` 定位到正确位置。
+
+### 关键原则
+
+1. **子模块沿正轴构建**：手柄、支架等长条形部件从 x=0 向 +X 延伸，由父模块旋转到实际朝向
+2. **凹/凸方向注意 Y 轴**：碗/锅等形状，凹面（开口）应朝 +Y（上方）。椭球切割时保留下半球得到碗形
+3. **rotate 在 translate 之前**：先旋转确定朝向，再平移到位
+4. **边缘重叠避免缝隙**：torus 做锅沿/轮圈时，应与主体有 0.1~0.2 的重叠，避免视觉上的缝隙
+
+### 示例：平底锅手柄组装
+
+```javascript
+// 手柄模块沿 +X 构建（x=0→x=18）
+// 父模块旋转 180° 使其朝 -X，再平移到锅体边缘
+let handle = use("./parts/handle.code3d.js", { length: 18 })
+block3d_doc.add_part(handle, "union", "handle")
+block3d_doc.rotate("y", 180)       // 翻转到 -X 方向
+block3d_doc.translate(-13, 5.5, 0) // 贴合锅体左侧边缘
+```
+
+### 示例：碗/锅形（椭球切割）
+
+```javascript
+// 椭球切割：保留下半球 → 凹面朝上
+block3d_doc.ellipsoid("union", r, depth, r, color)
+// 用 box 切掉上半部分（box 中心放在上方）
+block3d_doc.box("difference", d+2, d+2, d+2, color)
+block3d_doc.translate(0, depth, 0)  // box 覆盖 y=0 以上区域
+// 整体上移使锅底在 y=0
+```
+
+## 多色组装模式
+
+当一个模型需要多个颜色时，必须使用 `booleanEnabled=false` 外层包裹。
+
+### 原理
+
+- `booleanEnabled=true`：子节点合并为一个实体，**组颜色覆盖子节点颜色**
+- `booleanEnabled=false`：子节点保持独立，**各自保留自己的颜色**
+
+### 子模块多色模板
+
+```javascript
+let main = function(params) {
+    let block3d_doc = new PartBlock3dDocument()
+
+    // 外层：booleanEnabled=false 保留各部件颜色
+    block3d_doc.push_node("union", "assembly", "#主色", false)
+
+        // 部件A（红色）— 内部 boolean 合并
+        block3d_doc.push_node("union", "", "#ff0000", true)
+            block3d_doc.box("union", 10, 5, 10, "#ff0000")
+        block3d_doc.pop_node()
+        block3d_doc.translate(0, 0, 0)
+
+        // 部件B（蓝色）
+        block3d_doc.push_node("union", "", "#0000ff", true)
+            block3d_doc.sphere("union", 3, "#0000ff")
+        block3d_doc.pop_node()
+        block3d_doc.translate(0, 5, 0)
+
+    block3d_doc.pop_node()
+    return block3d_doc
+}
+```
+
+### 关键规则
+
+1. **子模块必须有 `booleanEnabled=false` 外层** — 这是 `add_part` 识别多色的信号
+2. **入口文件不需要外层包裹** — 根文档本身不会被 `run_node`
+3. **需要 boolean 运算的部件放在 `booleanEnabled=true` 的内层 group**
+4. **每个颜色一个 `push_node(..., true)` group** — 同色部件可合并到一个 group
+
+### 禁止：嵌套 booleanEnabled=true group 做差集
+
+```javascript
+// ❌ 错误 — 嵌套的 difference group transform 可能不生效
+block3d_doc.push_node("union", "", "#333", true)
+    block3d_doc.box("union", 10, 10, 10, "#333")
+    block3d_doc.push_node("difference", "", "#333", true)  // 嵌套!
+        block3d_doc.sphere("union", 4, "#333")
+    block3d_doc.pop_node()
+block3d_doc.pop_node()
+
+// ✅ 正确 — 同一 group 内直接用 difference 原语
+block3d_doc.push_node("union", "", "#333", true)
+    block3d_doc.box("union", 10, 10, 10, "#333")
+    block3d_doc.sphere("difference", 4, "#333")
+    block3d_doc.translate(0, 0, 0)  // 定位减法体
+block3d_doc.pop_node()
+```
+
+### difference 必须与被减实体在同一 booleanEnabled=true 组
+
+在 `booleanEnabled=false` 外层下，每个内层 `booleanEnabled=true` group 是独立执行的。
+**difference 只在自己所在的 group 内生效**。如果把 difference 放在单独的 inner group 里，它不会从相邻 group 中减去材料。
+
+```javascript
+// ❌ 错误 — 挂孔在单独的 inner group 里，difference 不会执行
+block3d_doc.push_node("union", "parts", "#333", false)
+    block3d_doc.push_node("union", "", "#333", true)  // group 1: 手柄
+        block3d_doc.box("union", 16, 1.2, 2.8, "#333")
+    block3d_doc.pop_node()
+    block3d_doc.translate(8, 0, 0)
+    block3d_doc.push_node("union", "", "#333", true)  // group 2: 挂孔
+        block3d_doc.cylinder("union", 2.2, 1.2, "#333")
+        block3d_doc.cylinder("difference", 1.0, 1.4, "#333")  // 不会生效!
+    block3d_doc.pop_node()
+    block3d_doc.translate(15, 0, 0)
+block3d_doc.pop_node()
+
+// ✅ 正确 — 所有需要布尔运算的几何体放在同一个 group
+block3d_doc.push_node("union", "parts", "#333", false)
+    block3d_doc.push_node("union", "", "#333", true)  // 全部放一起
+        block3d_doc.box("union", 16, 1.2, 2.8, "#333")
+        block3d_doc.translate(8, 0, 0)
+        block3d_doc.cylinder("union", 2.2, 1.2, "#333")
+        block3d_doc.translate(15, 0, 0)
+        block3d_doc.cylinder("difference", 1.0, 1.4, "#333")
+        block3d_doc.translate(15, 0, 0)
+    block3d_doc.pop_node()
+block3d_doc.pop_node()
+```
+
+### 单色子模块也必须有 booleanEnabled=false 外层
+
+即使子模块只有一种颜色，也**必须**使用 `booleanEnabled=false` 外层。
+否则 `add_part` 可能无法正确处理颜色，导致部件显示为白色。
+
+```javascript
+// ❌ 错误 — 直接用 booleanEnabled=true 作为顶层
+block3d_doc.push_node("union", "part", "#333", true)
+    block3d_doc.box("union", 4, 1.2, 3.5, "#333")
+block3d_doc.pop_node()
+
+// ✅ 正确 — 即使单色也包裹 false 外层
+block3d_doc.push_node("union", "part", "#333", false)
+    block3d_doc.push_node("union", "", "#333", true)
+        block3d_doc.box("union", 4, 1.2, 3.5, "#333")
+    block3d_doc.pop_node()
+block3d_doc.pop_node()
+```
+
+### 部件之间必须有几何重叠
+
+`add_part` 组装时，各部件之间必须有 **至少 0.5~1cm** 的几何重叠，否则会出现视觉缝隙。
+同一个 `booleanEnabled=true` 组内的 union 原语也必须重叠才能合并为一个整体。
+
+```javascript
+// ❌ 错误 — box 和 cylinder 不重叠（box 到 x=2, cylinder 从 x=2.25 开始）
+block3d_doc.box("union", 4, 1.2, 3.5, "#333")    // x: -2 ~ +2
+block3d_doc.cylinder("union", 1.75, 1.2, "#333")
+block3d_doc.translate(4, 0, 0)                     // center at x=4, edge at x=2.25
+
+// ✅ 正确 — cylinder 中心在 box 边缘处，产生充分重叠
+block3d_doc.box("union", 4, 1.2, 3.5, "#333")    // x: -2 ~ +2
+block3d_doc.cylinder("union", 1.75, 1.2, "#333")
+block3d_doc.translate(2, 0, 0)                     // center at x=2, edge at x=0.25, 与 box 重叠 1.75
+```
+
+### 手柄与锅体 translate 定位要点
+
+- 计算锅体在手柄高度处的**实际半径**（椭球/锥体随高度变化）
+- 手柄 translate 的 X 值应使连接段**嵌入锅壁 1~2cm**
+- 手柄 Y 值应与**锅沿高度**对齐（不是锅体中心）
+- torus 锅沿位置要与椭球切割后的**实际顶边对齐**（注意切割 box 的尺寸影响顶边位置）
+
+## 空心壳体构造
+
+### 椭球挖空模式
+
+```javascript
+block3d_doc.push_node("union", "", "#333", true)
+    // 外壳椭球
+    block3d_doc.ellipsoid("union", r, ry_outer, r, "#333")
+    // 切顶（保留下半碗形）
+    block3d_doc.box("difference", d+2, d+2, d+2, "#333")
+    block3d_doc.translate(0, ry_outer, 0)
+    // 内腔椭球（直接 difference，不要嵌套 group）
+    block3d_doc.ellipsoid("difference", r - wall, ry_inner, r - wall, "#333")
+    block3d_doc.translate(0, -wall, 0)
+block3d_doc.pop_node()
+block3d_doc.translate(0, ry_outer, 0)  // 整体上移
+```
+
+### 内腔尺寸规则（防止穿底）
+
+```
+外壳 Y 半径: ry_outer = depth + 1
+内腔 Y 半径: ry_inner = depth + 0.2  （≤ ry_outer - 0.8）
+```
+
+**核心约束**：`ry_inner` 必须比 `ry_outer` 小至少 0.8，否则内腔底部会穿透外壳。
+
+计算验证：
+- 外壳底部 y_bottom = -ry_outer
+- 内腔中心在 y = -wall，底部 = -wall - ry_inner
+- 底部壁厚 = (-wall - ry_inner) - (-ry_outer) = ry_outer - wall - ry_inner
+- 例: ry_outer=5.5, wall=0.3, ry_inner=4.7 → 底部壁厚 = 5.5 - 0.3 - 4.7 = 0.5cm ✓
+
+## 编译配置详细说明
+
+```json
+{
+    "name": "project-name",       // 项目名称，也是默认输出文件名
+    "version": "1.0.0",
+    "main": "main.code3d.js",     // 入口文件
+    "build": {
+        "output": "dist",         // 输出文件夹，默认 "dist"
+        "filename": "custom",     // 可选，覆盖输出文件名（不含扩展名）
+        "bin": false              // 可选，false 输出 .js；默认 true 输出 .js.bin
+    }
+}
+```
+
+输出文件名规则：
+- 基础名 = `build.filename` || `name`
+- 自动检测是否已含 `.code3d`，避免重复
+- bin 模式: `{基础名}.code3d.js.bin`（gzip 压缩）
+- js 模式: `{基础名}.code3d.js`（纯文本）
+
+## 编译工具位置
+
+```
+packages/parapoly-runtime/cli/code3d-build.js           # Node.js CLI 源码
+packages/parapoly-runtime/src/builder/code3dProjectBuilder.ts  # 浏览器/共享模块
+```
+
+## 项目模板位置
+
+```
+packages/parapoly-ai-to-3d/code3d-workspace-template/   # 项目模板（新建项目的基础）
+```
+
+模板内容：
+- `package.json` — 项目名称/版本/入口
+- `code3d-workspace-config.json` — 编译配置
+- `main.code3d.js` — 空入口文件
+- `.gitignore` — 忽略 dist/
+- `.parapoly/parapoly-runtime/` — 编译工具（由 parapoly-runtime 的 `npm run build` 自动同步）
+- `README.md` — 使用说明
+
+## 新建 code3d 项目
+
+新建项目时，必须将模板的 `.parapoly/` 目录拷贝到新项目中，确保项目可独立编译。
+
+步骤：
+1. 创建项目目录
+2. 拷贝 `code3d-workspace-template/.parapoly/` 到新项目的 `.parapoly/`
+3. 创建 `package.json`（修改 name）
+4. 创建 `code3d-workspace-config.json`（编译配置）
+5. 创建 `main.code3d.js` 入口文件
+6. 创建 `.gitignore`（忽略 dist/）
+
+`.parapoly/` 目录包含：
+- `parapoly-runtime/parapoly_runtime.js` — UMD 运行时库
+- `parapoly-runtime/parapoly_runtime.d.ts` — 类型声明
+- `parapoly-runtime/cli/code3d-build.js` — 编译 CLI 工具
+- `parapoly-runtime/package.json`
+- `parapoly-runtime/README.md`
+
+编译命令：
+```bash
+node .parapoly/parapoly-runtime/cli/code3d-build.js
+```
+
+如果已全局 link（`npm link`），也可直接：
+```bash
+code3d-build
+```
+
+## 示例项目位置
+
+```
+packages/parapoly-ai-to-3d/code3d-project-workspace-example/
+packages/parapoly-ai-to-3d/project-templates/平底锅/
+```
+
+## 参考范例库
+
+创建国基3D项目时，应搜索并参考以下目录中的 `.code3d.js` 和 `.part3d` 示例代码，学习建模手法和模式：
+
+```
+packages/parapoly-editor/public/parapoly-projects/
+```
+
+该目录包含大量已验证的 code3d 模型，涵盖各种形状、组装方式和参数化技巧。创建新模型时优先在此目录中搜索相似物体的实现作为参考。
+
+### 从 .part3d 文件提取设计参数
+
+.part3d 文件中保存了完整的参数化建模历史，可从中提取精确尺寸用于 code3d 项目：
+
+**1. 草图轮廓 → CSG 尺寸**
+
+从 `SkGeomLineComponent` 的 `start_point` / `end_point` 提取截面轮廓坐标：
+```
+点 (10, 0) → (10, 30) → (20, 30) → (20, 10) → (50, 10) → (50, 0) → (10, 0)
+```
+表示：内径=20(r=10), 颈外径=40(r=20), 颈高=20(y:10→30), 盘外径=100(r=50), 盘厚=10(y:0→10)
+
+**2. 旋转体 → cylinder / cone**
+
+`FeatureRevolveComponent` 的 `value: 360` + `ax2: [[0,0,0],[0,1,0]]` 表示绕 Y 轴 360° 旋转。
+在 code3d 中用同轴的 `cylinder` 组合等效：
+```javascript
+// 盘体（等效 r=50 段）
+block3d_doc.cylinder("union", disc_r, disc_h, color)
+// 颈部（等效 r=20 段）
+block3d_doc.cylinder("union", neck_r, neck_h, color)
+```
+
+**3. 拉伸圆 → 螺栓孔**
+
+`FeatureExtrudeComponent` 中 `value: 20` + `direction: [0,1,0]` 表示沿 Y 拉伸 20mm。
+草图中多个 `SkGeomCircleComponent`（半径 5）在分布圆上均匀排列 → 在 code3d 中用循环：
+```javascript
+for (let i = 0; i < bolt_n; i++) {
+    let angle = (360 / bolt_n) * i
+    let rad = angle * Math.PI / 180
+    let x = Math.cos(rad) * pcd_r
+    let z = Math.sin(rad) * pcd_r
+    block3d_doc.cylinder("difference", bolt_r, depth, color)
+    block3d_doc.translate(x, y_center, z)
+}
+```
+
+**4. 布尔差集 → difference**
+
+`FeatureNodeBoolean` 将拉伸体从旋转体中减去。在 code3d 中直接用 `"difference"` 布尔操作。
+
+### 建模模式映射表
+
+| Part3D 特征 | code3d 等效 |
+|---|---|
+| 草图 + 旋转 360° | `cylinder` / `cone`（同轴叠加） |
+| 草图 + 拉伸 | `box` / `cylinder`（沿方向） |
+| 布尔差集 | 原语 `"difference"` 操作 |
+| 均布圆上打孔 | `for` 循环 + 三角函数定位 |
+| 阶梯截面旋转 | 多个不同半径的 `cylinder` union |
+| 倒角/圆角 | code3d 暂不支持，可用 torus 近似边缘 |
+
+## Part3D 编辑器与 .part3d 文件
+
+### Part3D 编辑器概述
+
+Part3D 是国基CAD 的参数化实体建模编辑器，采用特征树（Feature Tree）驱动的建模方式，类似 SolidWorks/FreeCAD 的 Part Design 工作台。
+
+编辑器页面：`packages/parapoly-editor/pages/part3d.tsx`
+核心代码：`packages/parapoly-editor/src/editors/part3d/`
+运行时依赖：`packages/parapoly-runtime`
+
+### .part3d 文件格式
+
+- 文件后缀：`.part3d`
+- 格式：JSON（Sprite 序列化树）
+- 包含：FeatureContainer → 特征节点序列（草图、拉伸、倒角等）
+- 每个特征节点记录完整的参数化操作历史，可重新编译生成几何体
+
+### 特征节点类型
+
+**基础体：**
+- `FeatureNodeSetBox` — 长方体
+- `FeatureNodeSetSphere` — 球体
+- `FeatureNodeSetCylinder` — 圆柱体
+- `FeatureNodeSetCone` — 圆锥体
+- `FeatureNodeSetTorus` — 环形体
+- `FeatureNodeSetEllipsoid` — 椭球体
+- `FeatureNodeSetPrism` — 棱柱
+- `FeatureNodeSetStep` — STEP 导入体
+
+**草图+造型：**
+- `SkContainerNode` — 草图容器（2D 约束草图）
+- `FeatureNodeExtrude` — 拉伸
+- `FeatureNodeRevolve` — 旋转
+- `FeatureNodeSweep` — 扫掠
+- `FeatureNodeHelix` — 螺旋
+
+**修饰：**
+- `FeatureNodeChamfer` — 倒角
+- `FeatureNodeFillet` — 圆角
+- `FeatureNodeShell` — 抽壳
+- `FeatureNodeDraft` — 拔模
+
+**变换与布尔：**
+- `FeatureNodeMirror` — 镜像
+- `FeatureNodeBoolean` — 布尔运算
+- `FeatureNodeTransform` — 变换
+- `FeatureNodeDelete` — 删除体
+
+### 草图工具
+
+草图（SkContainerNode）支持的绘制和约束工具：
+
+**绘制：** 点、线段、圆弧、圆、B样条、矩形、多边形、腰形槽
+**约束：** 重合、点在线上、水平、垂直、平行、垂直、相切、等长、对称、锁定
+**尺寸：** 距离X/Y/自由、半径、直径、角度
+**编辑：** 裁剪、分割、圆角、倒角、对称复制
+**导入导出：** DXF、SVG
+
+### .part3d 示例位置
+
+```
+packages/parapoly-editor/public/parapoly-projects/part3d/
+├── 塑胶积木模型合集/
+├── 小方机器人/          ← 多零件装配示例
+│   ├── 小方上壳.part3d
+│   ├── 小方下壳.part3d
+│   ├── 小方中框.part3d
+│   └── ...
+└── 机械模型合集/
+```
+
+### 在 code3d 项目中引用 .part3d
+
+国基3D 项目可以通过 `use()` 引用 `.part3d` 文件作为子零件：
+
+```javascript
+// 引用本地 .part3d（使用预编译数据）
+let part = use("./assets/零件.part3d")
+block3d_doc.add_part(part, "union", "part_name")
+
+// 强制重新编译（修改 .part3d 后需要）
+let part2 = use("./assets/零件.part3d", { recompile: true })
+
+// 覆盖颜色
+let part3 = use("./assets/零件.part3d", { recompile: true, color: "#4488ff" })
+
+// 绝对路径引用
+let shell = use("E:/models/part3d/外壳.part3d", { recompile: true })
+
+// 远程 .part3d
+let remote = use("https://poly.keepwork.com/parapoly-projects/part3d/机械模型合集/04%20油标尺.part3d")
+```
+
+### code3d 引用 .part3d 的示例项目
+
+```
+packages/parapoly-ai-to-3d/code3d-project-workspace-example/   ← 含 .part3d 引用注释示例
+packages/parapoly-ai-to-3d/code3d-project-workspace-example2/  ← 小方机器人多零件装配
+```

package/instructions/code3d.instructions.md

@@ -0,0 +1,178 @@
+---
+applyTo: "**/*.code3d.js"
+---
+# ParaPoly Code3D Modeling Guide
+
+Generate `.code3d.js` scripts that create 3D models using the ParaPoly engine's `PartBlock3dDocument` API via constructive solid geometry (CSG) and transformation operations.
+
+## Output Format
+
+Every `.code3d.js` file MUST follow this structure:
+
+```javascript
+var object1, object2; // declare all node variable names used in push_node
+
+let main = function(){
+  let block3d_doc = new PartBlock3dDocument()
+  // ... build geometry here ...
+  return block3d_doc
+}
+```
+
+Key rules:
+- The file MUST define a `main` function that returns a `PartBlock3dDocument`
+- All node names used in `push_node` must be declared as `var` at the top
+- The function uses `let main = function(){...}` syntax (not `function main()`)
+- Colors are CSS hex strings like `"#ff0000"`
+
+## API Reference
+
+### Primitive Shapes
+
+All primitives take a boolean operation type as first parameter: `"union"`, `"difference"`, or `"intersection"`.
+The last parameter is always a color string (typically `"#ffc658"`).
+
+| Method | Parameters | Description |
+|--------|-----------|-------------|
+| `box(op, width_x, height_y, depth_z, color)` | Dimensions along each axis | Rectangular box |
+| `sphere(op, radius, color)` | Single radius | Sphere |
+| `cylinder(op, radius, height, color)` | Radius and height (along Y) | Cylinder |
+| `cone(op, top_radius, bottom_radius, height, color)` | Two radii and height | Truncated cone/cone |
+| `torus(op, outer_radius, inner_radius, color)` | Two radii | Torus/donut |
+| `prism(op, edges, radius, height, color)` | Edge count, radius, height | Regular polygon prism |
+| `ellipsoid(op, radius_x, radius_y, radius_z, color)` | Three radii | Ellipsoid |
+| `wedge(op, x, y, z, color)` | Three dimensions | Wedge shape |
+| `trapezoid(op, top_width, bottom_width, height, depth, color)` | Trapezoid profile extruded | Trapezoid |
+
+### Boolean Operations
+
+- `"union"` — Add/combine shapes together
+- `"difference"` — Subtract/cut shape from parent
+- `"intersection"` — Keep only overlapping region
+
+### Grouping (push_node / pop_node)
+
+```javascript
+block3d_doc.push_node(op, name, color, booleanEnabled)
+  // child shapes and operations go here
+block3d_doc.pop_node()
+```
+
+Parameters:
+- `op`: `"union"` | `"difference"` | `"intersection"` — how this group combines with siblings
+- `name`: String identifier (must match a `var` declared at top), e.g. `"object1"`
+- `color`: Hex color for this group/part, e.g. `"#ff0000"`
+- `booleanEnabled`: `true` to execute boolean ops within the group
+
+### Transformations
+
+Transformations apply to the LAST created primitive or the LAST popped group:
+
+```javascript
+block3d_doc.translate(x, y, z)        // Position the preceding shape/group
+block3d_doc.rotate(axis, degrees)     // axis: "x", "y", or "z"
+block3d_doc.scale(x, y, z)           // Scale factors
+block3d_doc.mirror(op, plane, color)  // plane: "x", "y", or "z"
+```
+
+**Critical Positioning Rules**:
+
+1. Every shape is created at its **parent group's origin** (0,0,0).
+2. `translate(x, y, z)` moves the **immediately preceding shape or popped group** to position (x, y, z).
+3. `rotate(axis, degrees)` rotates the **immediately preceding shape or popped group**.
+4. Each shape's translate is independent — they do NOT accumulate.
+5. If NO translate follows a shape/group, it stays at origin.
+6. To rotate an entire group, place `rotate()` AFTER `pop_node()`, not inside the group.
+
+### Edge Operations
+
+```javascript
+block3d_doc.fillet(radius, planeType)    // Round edges. planeType: "x","y","z","xy","xz","yz","xyz"
+block3d_doc.chamfer(size, planeType)     // Bevel edges
+```
+
+`fillet()` and `chamfer()` follow the same rule — they apply to the **immediately preceding shape or popped group**.
+
+### Color & Boolean in Groups
+
+`booleanEnabled` (4th parameter of `push_node`) controls whether child shapes are merged via boolean operations:
+
+- `booleanEnabled=true`: All children are merged into a single solid. The **group color overrides child colors**.
+- `booleanEnabled=false`: Children stay as separate parts. Each sub-group **preserves its own color**.
+
+**Multi-color assembly pattern** — use an outer group with `booleanEnabled=false` containing inner groups each with their own color:
+```javascript
+block3d_doc.push_node("union", "assembly", "#aaa", false)  // outer: no merge, colors preserved
+  block3d_doc.push_node("union", '', "#ff0000", true)       // red part (merged internally)
+    block3d_doc.box("union", 10, 5, 10, "#ff0000")
+  block3d_doc.pop_node()
+  block3d_doc.push_node("union", '', "#0000ff", true)       // blue part (merged internally)
+    block3d_doc.sphere("union", 3, "#0000ff")
+  block3d_doc.pop_node()
+  block3d_doc.translate(0, 5, 0)
+block3d_doc.pop_node()
+```
+
+### Sketching & Extrude
+
+```javascript
+block3d_doc.start_sketch(name, plane) // plane: "xy", "xz", "yz"
+  block3d_doc.line_segment(x1, y1, z1, x2, y2, z2)
+  block3d_doc.circle(x, y, z, radius)
+  block3d_doc.arc(x, y, z, radius, startAngle, endAngle, isDegree)
+block3d_doc.end_sketch()
+block3d_doc.extrude(op, length, color, bSolid, transform_matrix)
+block3d_doc.revolve(op, angle, axis, color, bSolid, transform_matrix)
+```
+
+## Coordinate System
+
+- **Default unit: millimeters (mm)** — all dimensions, radii, and positions are in mm
+- **Y-axis is UP**, X is left-right, Z is front-back
+- Origin (0,0,0) is the center of the model
+
+**All shapes are CENTERED at their translate position:**
+- `box(op, W, H, D)` at translate(x, y, z) → extends from (x-W/2, y-H/2, z-D/2) to (x+W/2, y+H/2, z+D/2)
+- `cylinder(op, R, H)` at translate(x, y, z) → extends from y-H/2 to y+H/2
+- `cone(op, topR, bottomR, H)` at translate(x, y, z) → topR at y+H/2, bottomR at y-H/2
+- `sphere(op, R)` at translate(x, y, z) → centered at (x, y, z)
+
+**Stacking formula**: To place leg under tabletop: `leg_y = -tabletop_H/2 - leg_H/2`
+
+## Key Patterns
+
+### Hollow Object (Cup/Vase)
+```javascript
+block3d_doc.cone("union", 3.2, 2.5, 9, "#ffc658")       // outer wall
+block3d_doc.cone("difference", 3, 2.3, 9, "#ffc658")    // inner hollow
+block3d_doc.translate(0, 0.3, 0)                         // offset up → thick bottom
+```
+
+### Handle Attached to Curved Body
+Use the **same shape as the body** for the difference cut:
+```javascript
+block3d_doc.push_node("union", '', "#fff", true)
+  block3d_doc.torus("union", 1.5, 0.35, "#ffc658")
+  block3d_doc.rotate("x", 90)
+block3d_doc.pop_node()
+block3d_doc.translate(3.5, 0, 0)
+block3d_doc.cone("difference", 3.2, 2.5, 9, "#ffc658")  // matches cup body shape exactly
+```
+
+### Table (Tabletop + Explicit Legs)
+```javascript
+block3d_doc.box("union", 20, 1.5, 12, "#ffc658")        // tabletop at origin
+// legs: cylinder height 10, centered at y=-5, top at y=0 meets tabletop
+block3d_doc.cylinder("union", 0.8, 10, "#ffc658")
+block3d_doc.translate(8, (-5), 4.5)
+```
+
+## Common Pitfalls
+
+1. **Boolean order matters**: `union` after `difference` fills the hole back in.
+2. **Don't cap hollow objects**: No solid disk at the mouth of a cup.
+3. **Match cut shapes to body**: Use cone to cut against cone, cylinder against cylinder — not sphere.
+4. **Centered geometry**: Shapes don't start at base. A cylinder(r, 10) at origin spans y=-5 to y=+5.
+5. **rotate/translate placement**: Must be placed AFTER the target shape or `pop_node()`. Placing inside a group only affects the last shape in the group, not the whole group.
+6. **booleanEnabled and colors**: If parent group has `booleanEnabled=true`, all children merge into one color. Use `false` on the outer group when children need distinct colors.
+7. **fillet scope**: `fillet()` rounds the immediately preceding shape/group. Place it right after `pop_node()` or the target primitive.

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "parapoly-runtime",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "ParaPoly 3D CAD Runtime — CSG modeling, sketch, and project builder",
   "main": "./parapoly_runtime.js",
   "types": "./parapoly_runtime.d.ts",
   "bin": {
-    "code3d-build": "./cli/code3d-build.js"
+    "code3d-build": "./cli/code3d-build.js",
+    "code3d-install-instructions": "./cli/code3d-install-instructions.js"
   },
   "keywords": [
     "3d",
@@ -19,6 +20,7 @@
     "parapoly_runtime.js",
     "parapoly_runtime.d.ts",
     "cli/",
+    "instructions/",
     "README.md"
   ]
 }