scad-load

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

scad-load

Quick Start

快速开始

Load an OpenSCAD file with all its dependencies:

bash

undefined

加载带有所有依赖项的OpenSCAD文件：

bash

undefined

Load main file with dependency tree

加载带有依赖树的主文件

/scad-load workshop/workbenches/mini-workbench.scad

Output includes:

输出包含：

- Dependency tree visualization

- 依赖树可视化

- Available modules and functions

- 可用模块和函数

- Customizer parameters

- 自定义器参数

- Configuration variables

- 配置变量

- File locations (project lib/, system libraries/)

- 文件位置（项目lib/、系统库/）

undefined

undefined

When to Use This Skill

何时使用本技能

Explicit Triggers

显式触发

User says: "load scad [file]"
User says: "/scad-load [file]"
User says: "load openscad context for [file]"
User says: "show dependencies for [file]"

用户输入："load scad [文件]"
用户输入："/scad-load [文件]"
用户输入："load openscad context for [文件]"
用户输入："show dependencies for [文件]"

Implicit Triggers

隐式触发

Before modifying OpenSCAD files (understand context first)
Debugging rendering errors (check dependency chain)
Understanding module availability (what can be called)
Investigating missing function errors
Planning refactoring work

修改OpenSCAD文件前（先了解上下文）
调试渲染错误（检查依赖链）
了解模块可用性（可调用的内容）
排查函数缺失错误
规划重构工作

Debugging Scenarios

调试场景

"Module X is undefined" errors → check dependency tree
"Variable Y is undef" → verify include vs use
Circular dependency suspected → detect loops
Library path issues → resolve library locations

"Module X is undefined"错误 → 检查依赖树
"Variable Y is undef" → 验证include与use的区别
疑似循环依赖 → 检测循环
库路径问题 → 解析库位置

What This Skill Does

本技能的功能

This skill provides systematic OpenSCAD file context loading:

Read target file - Load specified .scad file
Parse dependencies - Extract use/include statements recursively
Resolve paths - Find files in project lib/, system libraries/, relative paths
Extract API - Identify modules, functions, customizer parameters, variables
Detect issues - Circular dependencies, missing files, path resolution failures
Present summary - Structured overview with dependency tree and API surface

本技能提供系统化的OpenSCAD文件上下文加载：

读取目标文件 - 加载指定的.scad文件
解析依赖项 - 递归提取use/include语句
解析路径 - 在项目lib/、系统库/、相对路径中查找文件
提取API - 识别模块、函数、自定义器参数、变量
检测问题 - 循环依赖、文件缺失、路径解析失败
呈现摘要 - 结构化概述，包含依赖树和API接口

Instructions

操作说明

3.1. Load OpenSCAD File

3.1. 加载OpenSCAD文件

Read the specified file:

bash

undefined

读取指定文件：

bash

undefined

User provides path (absolute or relative to project root)

用户提供路径（绝对路径或相对于项目根目录的路径）

file_path = "workshop/workbenches/mini-workbench.scad"

Read file

读取文件

Read file_path


**Extract metadata:**
- File path (absolute)
- File size
- Module name (from filename)
- First-level use/include statements

Read file_path


**提取元数据：**
- 文件路径（绝对路径）
- 文件大小
- 模块名称（来自文件名）
- 一级use/include语句

3.2. Parse Dependencies

3.2. 解析依赖项

Extract include/use statements:

Use Grep to find dependency statements:

bash

undefined

提取include/use语句：

使用Grep查找依赖语句：

bash

undefined

Find all use/include statements

查找所有use/include语句

grep -E '^\s*(use|include)\s*<' file_path

Example matches:

匹配示例：

use <BOSL2/std.scad>

include <../../lib/assembly-framework.scad>

use <woodworkers-lib/std.scad>


**Resolve paths:**

Apply OpenSCAD path resolution rules:

1. **Angle brackets `<lib/file.scad>`:**
   - Check project `lib/` directory first
   - Check `~/Documents/OpenSCAD/libraries/` (macOS)
   - Check `~/.local/share/OpenSCAD/libraries/` (Linux)

2. **Relative paths `../../lib/file.scad`:**
   - Resolve relative to current file's directory
   - Convert to absolute path

3. **Library references `<BOSL2/std.scad>`:**
   - Check `~/Documents/OpenSCAD/libraries/BOSL2/std.scad` (macOS)
   - Check `~/.local/share/OpenSCAD/libraries/BOSL2/std.scad` (Linux)

**Recursive loading:**

For each dependency found:
- Check if already visited (circular dependency detection)
- Add to visited set
- Read dependency file
- Extract its use/include statements
- Recurse (up to max depth, default 5)

**Circular dependency detection:**

visited = set() stack = []

function load_dependencies(file, depth=0, max_depth=5): if depth > max_depth: return "Max depth reached"

if file in stack:
    return "CIRCULAR DEPENDENCY: " + " -> ".join(stack + [file])

stack.append(file)
visited.add(file)

# Parse use/include statements
# Recursively load each dependency

stack.pop()

undefined


**解析路径：**

应用OpenSCAD路径解析规则：

1. **尖括号路径 `<lib/file.scad>`：**
   - 优先检查项目`lib/`目录
   - 检查`~/Documents/OpenSCAD/libraries/`（macOS）
   - 检查`~/.local/share/OpenSCAD/libraries/`（Linux）

2. **相对路径 `../../lib/file.scad`：**
   - 相对于当前文件所在目录解析
   - 转换为绝对路径

3. **库引用 `<BOSL2/std.scad>`：**
   - 检查`~/Documents/OpenSCAD/libraries/BOSL2/std.scad`（macOS）
   - 检查`~/.local/share/OpenSCAD/libraries/BOSL2/std.scad`（Linux）

**递归加载：**

对于每个找到的依赖项：
- 检查是否已访问（循环依赖检测）
- 添加到已访问集合
- 读取依赖文件
- 提取其use/include语句
- 递归加载（最大深度默认5）

**循环依赖检测：**

visited = set() stack = []

function load_dependencies(file, depth=0, max_depth=5): if depth > max_depth: return "达到最大深度"

if file in stack:
    return "循环依赖: " + " -> ".join(stack + [file])

stack.append(file)
visited.add(file)

# 解析use/include语句
# 递归加载每个依赖项

stack.pop()

undefined

3.3. Extract API Surface

3.3. 提取API接口

Parse module definitions:

bash

undefined

解析模块定义：

bash

undefined

Find module definitions

查找模块定义

grep -E '^\smodule\s+\w+\s(' file_path

Example matches:

匹配示例：

module drawer_stack(width, x_start, drawer_start=0) {

module ww_cabinet_shell() {

module _helper_function() { # (private, prefixed with _)

module _helper_function() { # （私有模块，以下划线开头）


**Parse function definitions:**

```bash


**解析函数定义：**

```bash

Find function definitions

查找函数定义

grep -E '^\sfunction\s+\w+\s(' file_path

Example matches:

匹配示例：

function asmfw_section_internal_width(section_id) = ...

function calc_dimensions(w, h) = [w, h, w+h];


**Extract customizer parameters:**

```bash


**提取自定义器参数：**

```bash

Find customizer section comments

查找自定义器区块注释

grep -E '/*\s*[.]\s*/' file_path

Example matches:

匹配示例：

/* [Dimensions] */

/* [Display Options] */

Parameters follow section comments:

参数跟随区块注释：

wall_thickness = 18; // Wall panel thickness

wall_thickness = 18; // 墙板厚度

show_drawers = true; // Show drawer boxes

show_drawers = true; // 显示抽屉盒


**Extract configuration variables:**

```bash


**提取配置变量：**

```bash

Find top-level variable assignments

查找顶层变量赋值

grep -E '^\s*\w+\s*=' file_path | head -20

Distinguish from parameters by context (before/after customizer sections)

通过上下文区分参数（自定义器区块前后）


**Categorize API:**

- **Public modules:** No underscore prefix, documented
- **Private modules:** Underscore prefix (`_helper()`)
- **Public functions:** No underscore prefix
- **Private functions:** Underscore prefix
- **Customizer params:** In `/* [Section] */` blocks
- **Config variables:** Top-level assignments


**API分类：**

- **公共模块：** 无下划线前缀、已文档化
- **私有模块：** 下划线前缀（`_helper()`）
- **公共函数：** 无下划线前缀
- **私有函数：** 下划线前缀
- **自定义器参数：** 在`/* [Section] */`区块中
- **配置变量：** 顶层赋值

3.4. Present Context Summary

3.4. 呈现上下文摘要

Format output:

========================================
OpenSCAD File Context: mini-workbench.scad
========================================

File: /Users/.../workshop/workbenches/mini-workbench.scad
Size: 15.2 KB
Lines: 450

Dependency Tree:
----------------
mini-workbench.scad
├── lib/assembly-framework.scad (project lib)
│   ├── lib/materials.scad (project lib)
│   └── woodworkers-lib/std.scad (system library)
│       ├── woodworkers-lib/planes.scad
│       └── woodworkers-lib/cutlist.scad
├── BOSL2/std.scad (system library)
│   ├── BOSL2/transforms.scad
│   ├── BOSL2/attachments.scad
│   └── BOSL2/shapes3d.scad
└── lib/labels.scad (project lib)

Dependencies Loaded: 11 files
Max Depth Reached: 3 levels

Available Modules (Public):
----------------------------
- mini_workbench() - Main assembly module
- drawer_stack(width, x_start, drawer_start=0) - Creates vertical drawer stack
- dividers() - Renders all vertical dividers
- cabinet_shell() - Outer cabinet box

Available Functions (Public):
------------------------------
- None (uses framework functions)

Customizer Parameters:
----------------------
/* [Display Options] */
show_cabinet = true;         // Show cabinet shell
show_drawers = true;         // Show drawer boxes
show_faceplates = true;      // Show drawer faces
show_runners = true;         // Show drawer runners
show_dividers = true;        // Show vertical dividers

/* [Dimensions] */
total_width = 1650;          // Assembly total width
assembly_height = 500;       // Internal height
assembly_depth = 580;        // Front-to-back depth

Configuration Variables:
------------------------
ASMFW_SECTION_IDS = ["A", "B", "C", "D", "E"]
ASMFW_SECTION_WIDTHS = [253, 562, 562, 153, 120]
ASMFW_TOTAL_WIDTH = 1650
ASMFW_ASSEMBLY_HEIGHT = 500
ASMFW_ASSEMBLY_DEPTH = 580

Framework Functions Available:
-------------------------------
(from lib/assembly-framework.scad)
- asmfw_section_internal_width(section_id)
- asmfw_section_x_start(section_id)
- asmfw_section_x_end(section_id)
- asmfw_drawer_box_width(section_id)
- asmfw_faceplate_width(section_id)
- asmfw_runner_x_positions(section_id)

Key Insights:
-------------
✓ Uses assembly framework for automatic positioning
✓ 5-section cabinet (A, B, C, D, E)
✓ Drawer stacks in sections B and C
✓ Side-access tray in section D
✓ Tall drawer in section A
✓ All dimensions driven by framework configuration

Next Steps:
-----------
- Modify customizer parameters to change display
- Adjust ASMFW_SECTION_WIDTHS to resize sections
- Add new modules using framework functions
- Update drawer stack configurations in sections
========================================

输出格式：

========================================
OpenSCAD文件上下文: mini-workbench.scad
========================================

文件: /Users/.../workshop/workbenches/mini-workbench.scad
大小: 15.2 KB
行数: 450

依赖树:
----------------
mini-workbench.scad
├── lib/assembly-framework.scad (项目库)
│   ├── lib/materials.scad (项目库)
│   └── woodworkers-lib/std.scad (系统库)
│       ├── woodworkers-lib/planes.scad
│       └── woodworkers-lib/cutlist.scad
├── BOSL2/std.scad (系统库)
│   ├── BOSL2/transforms.scad
│   ├── BOSL2/attachments.scad
│   └── BOSL2/shapes3d.scad
└── lib/labels.scad (项目库)

已加载依赖项: 11个文件
达到的最大深度: 3层

可用公共模块:
----------------------------
- mini_workbench() - 主装配模块
- drawer_stack(width, x_start, drawer_start=0) - 创建垂直抽屉组
- dividers() - 渲染所有垂直分隔板
- cabinet_shell() - 外部柜体

可用公共函数:
------------------------------
- 无（使用框架函数）

自定义器参数:
----------------------
/* [显示选项] */
show_cabinet = true;         // 显示柜体外壳
show_drawers = true;         // 显示抽屉盒
show_faceplates = true;      // 显示抽屉面板
show_runners = true;         // 显示抽屉滑轨
show_dividers = true;        // 显示垂直分隔板

/* [尺寸] */
total_width = 1650;          // 装配总宽度
assembly_height = 500;       // 内部高度
assembly_depth = 580;        // 前后深度

配置变量:
------------------------
ASMFW_SECTION_IDS = ["A", "B", "C", "D", "E"]
ASMFW_SECTION_WIDTHS = [253, 562, 562, 153, 120]
ASMFW_TOTAL_WIDTH = 1650
ASMFW_ASSEMBLY_HEIGHT = 500
ASMFW_ASSEMBLY_DEPTH = 580

可用框架函数:
-------------------------------
(来自lib/assembly-framework.scad)
- asmfw_section_internal_width(section_id)
- asmfw_section_x_start(section_id)
- asmfw_section_x_end(section_id)
- asmfw_drawer_box_width(section_id)
- asmfw_faceplate_width(section_id)
- asmfw_runner_x_positions(section_id)

关键见解:
-------------
✓ 使用装配框架实现自动定位
✓ 5段式柜体（A、B、C、D、E）
✓ B和C段包含抽屉组
✓ D段是侧抽托盘
✓ A段是高抽屉
✓ 所有尺寸由框架配置驱动

下一步操作:
-----------
- 修改自定义器参数更改显示效果
- 调整ASMFW_SECTION_WIDTHS调整段宽
- 使用框架函数添加新模块
- 更新各段的抽屉组配置
========================================

Supporting Files

支持文件

scripts/

```
parse_scad.py
```
- OpenSCAD parser for extracting modules/functions/variables
```
resolve_paths.py
```
- Library path resolution utility
```
dependency_graph.py
```
- Builds and visualizes dependency tree

```
parse_scad.py
```
- 用于提取模块/函数/变量的OpenSCAD解析器
```
resolve_paths.py
```
- 库路径解析工具
```
dependency_graph.py
```
- 构建并可视化依赖树

references/

```
openscad-path-resolution.md
```
- Detailed path resolution rules
```
api-extraction-patterns.md
```
- Regex patterns for parsing OpenSCAD syntax
```
library-locations.md
```
- Standard library installation paths by OS

```
openscad-path-resolution.md
```
- 详细的路径解析规则
```
api-extraction-patterns.md
```
- 解析OpenSCAD语法的正则表达式模式
```
library-locations.md
```
- 各系统的标准库安装路径

examples/

```
example-output-simple.md
```
- Output for simple single-file .scad
```
example-output-complex.md
```
- Output for multi-dependency project file
```
example-circular-dependency.md
```
- Handling circular dependency detection

```
example-output-simple.md
```
- 简单单文件.scad的输出示例
```
example-output-complex.md
```
- 多依赖项目文件的输出示例
```
example-circular-dependency.md
```
- 循环依赖处理示例

Expected Outcomes

预期结果

Success Case

成功案例

✅ Loaded: workshop/workbenches/mini-workbench.scad
✅ Dependencies: 11 files resolved
✅ Modules: 4 public, 2 private
✅ Functions: 0 public (uses framework)
✅ Customizer params: 9 parameters in 2 sections
✅ No circular dependencies detected
✅ All library paths resolved

Ready to work with this file.

✅ 已加载: workshop/workbenches/mini-workbench.scad
✅ 依赖项: 11个文件已解析
✅ 模块: 4个公共模块，2个私有模块
✅ 函数: 0个公共函数（使用框架函数）
✅ 自定义器参数: 2个区块共9个参数
✅ 未检测到循环依赖
✅ 所有库路径已解析

可开始处理该文件。

Failure Case

失败案例

❌ Failed to load: workshop/cabinets/broken.scad

Issues Found:
1. Missing dependency: lib/missing-framework.scad
   - Referenced at line 5: include <lib/missing-framework.scad>
   - File not found in project lib/ or system libraries/

2. Circular dependency detected:
   - a.scad -> b.scad -> c.scad -> a.scad

3. Unresolved library: CustomLib/helper.scad
   - Not found in ~/Documents/OpenSCAD/libraries/
   - Not found in ~/.local/share/OpenSCAD/libraries/

Recommendations:
- Install missing library: CustomLib
- Fix circular dependency in a.scad/b.scad/c.scad
- Create missing file: lib/missing-framework.scad

❌ 加载失败: workshop/cabinets/broken.scad

发现问题:
1. 缺失依赖项: lib/missing-framework.scad
   - 在第5行引用: include <lib/missing-framework.scad>
   - 在项目lib/或系统库中未找到该文件

2. 检测到循环依赖:
   - a.scad -> b.scad -> c.scad -> a.scad

3. 未解析的库: CustomLib/helper.scad
   - 在~/Documents/OpenSCAD/libraries/中未找到
   - 在~/.local/share/OpenSCAD/libraries/中未找到

建议:
- 安装缺失的库: CustomLib
- 修复a.scad/b.scad/c.scad中的循环依赖
- 创建缺失文件: lib/missing-framework.scad

Requirements

要求

Tools:

Read (load .scad files)
Grep (extract use/include statements, parse syntax)
Bash (check file existence, resolve paths)

Knowledge:

OpenSCAD syntax (use vs include semantics)
Library path resolution (angle brackets vs relative)
Customizer format (
```
/* [Section] */
```
comments)
Module/function definition patterns

Environment:

Access to project directory
Access to system library directories (~/Documents/OpenSCAD/libraries/)

工具:

Read（加载.scad文件）
Grep（提取use/include语句、解析语法）
Bash（检查文件存在性、解析路径）

知识:

OpenSCAD语法（use与include的语义区别）
库路径解析（尖括号与相对路径）
自定义器格式（
```
/* [Section] */
```
注释）
模块/函数定义模式

环境:

可访问项目目录
可访问系统库目录（macOS:
```
~/Documents/OpenSCAD/libraries/
```
）

Red Flags to Avoid

需避免的警示情况

Don't load files without checking existence - Verify file exists before attempting to read
Don't assume library locations - Check both macOS and Linux paths
Don't skip circular dependency detection - Always track visited files in stack
Don't parse OpenSCAD with complex regex - Use simple patterns for module/function extraction
Don't load entire library files - Stop at max depth to avoid loading massive libraries
Don't ignore use vs include semantics - Include loads variables, use doesn't
Don't miss relative path resolution - Resolve paths relative to current file's directory
Don't overload context - Summarize library contents instead of loading full text
Don't skip customizer sections - These are critical for understanding configurable parameters
Don't assume underscore convention - Not all projects use
```
_private()
```
naming

不要在不检查文件存在性的情况下加载文件 - 读取前先验证文件是否存在
不要假设库位置 - 同时检查macOS和Linux路径
不要跳过循环依赖检测 - 始终用栈跟踪已访问文件
不要用复杂正则解析OpenSCAD - 使用简单模式提取模块/函数
不要加载整个库文件 - 达到最大深度时停止，避免加载庞大的库
不要忽略use与include的语义区别 - Include加载变量，use不加载
不要遗漏相对路径解析 - 相对于当前文件所在目录解析路径
不要过度加载上下文 - 汇总库内容而非加载完整文本
不要跳过自定义器区块 - 这些是了解可配置参数的关键
不要假设下划线命名约定 - 并非所有项目都使用
```
_private()
```
命名

Notes

注意事项

Path Resolution Priority:

Angle brackets
```
<file.scad>
```
:
- Project
```
lib/
```
  directory (highest priority)
- System libraries (macOS:
```
~/Documents/OpenSCAD/libraries/
```
  )
- System libraries (Linux:
```
~/.local/share/OpenSCAD/libraries/
```
  )
Relative paths
```
../lib/file.scad
```
:
- Relative to current file's directory
- Convert to absolute for consistency

Use vs Include:

```
use <file.scad>
```
- Imports modules/functions ONLY (no variables, no top-level code)
```
include <file.scad>
```
- Imports everything (modules, functions, variables, executes top-level code)

Max Depth Rationale:

Default max depth of 5 prevents loading entire library trees (e.g., BOSL2 has 50+ files). Focus on direct dependencies and first-level library interfaces.

Performance:

For large projects with many dependencies:

Cache resolved paths
Skip re-parsing already visited files
Summarize large libraries instead of extracting full API

路径解析优先级:

尖括号路径
```
<file.scad>
```
:
- 项目
```
lib/
```
  目录（优先级最高）
- 系统库（macOS:
```
~/Documents/OpenSCAD/libraries/
```
  ）
- 系统库（Linux:
```
~/.local/share/OpenSCAD/libraries/
```
  ）
相对路径
```
../lib/file.scad
```
:
- 相对于当前文件所在目录
- 转换为绝对路径以保持一致性

Use与Include的区别:

```
use <file.scad>
```
- 仅导入模块/函数（不导入变量、不执行顶层代码）
```
include <file.scad>
```
- 导入所有内容（模块、函数、变量、执行顶层代码）

最大深度的原因:

默认最大深度5可避免加载整个库树（例如BOSL2包含50+文件）。重点关注直接依赖和一级库接口。

性能:

对于有大量依赖的大型项目:

缓存已解析的路径
跳过重新解析已访问的文件
汇总大型库的内容而非提取完整API

scad-load

Original

Translation

scad-load

scad-load

Quick Start

快速开始

Load main file with dependency tree

加载带有依赖树的主文件

Output includes:

输出包含：

- Dependency tree visualization

- 依赖树可视化

- Available modules and functions

- 可用模块和函数

- Customizer parameters

- 自定义器参数

- Configuration variables

- 配置变量

- File locations (project lib/, system libraries/)

- 文件位置（项目lib/、系统库/）

Table of Contents

目录

When to Use This Skill

何时使用本技能

Explicit Triggers

显式触发

Implicit Triggers

隐式触发

Debugging Scenarios

调试场景

What This Skill Does

本技能的功能

Instructions

操作说明

3.1. Load OpenSCAD File

3.1. 加载OpenSCAD文件

User provides path (absolute or relative to project root)

用户提供路径（绝对路径或相对于项目根目录的路径）

Read file

读取文件

3.2. Parse Dependencies

3.2. 解析依赖项

Find all use/include statements

查找所有use/include语句

Example matches:

匹配示例：

use <BOSL2/std.scad>

use <BOSL2/std.scad>

include <../../lib/assembly-framework.scad>

include <../../lib/assembly-framework.scad>

use <woodworkers-lib/std.scad>

use <woodworkers-lib/std.scad>

3.3. Extract API Surface

3.3. 提取API接口

Find module definitions

查找模块定义

Example matches:

匹配示例：

module drawer_stack(width, x_start, drawer_start=0) {

module drawer_stack(width, x_start, drawer_start=0) {

module ww_cabinet_shell() {

module ww_cabinet_shell() {

module _helper_function() { # (private, prefixed with _)

module _helper_function() { # （私有模块，以下划线开头）

Find function definitions

查找函数定义

Example matches:

匹配示例：

function asmfw_section_internal_width(section_id) = ...

function asmfw_section_internal_width(section_id) = ...

function calc_dimensions(w, h) = [w, h, w+h];

function calc_dimensions(w, h) = [w, h, w+h];

Find customizer section comments

查找自定义器区块注释

Example matches:

匹配示例：

/* [Dimensions] */

/* [Dimensions] */

/* [Display Options] */