Skip to content

Releases: conanxin/CAD-CAM-Technology-docs

v1.0.0 - CAD/CAM Technology Docs Stable

Choose a tag to compare

@conanxin conanxin released this 01 Jul 01:35

Release Notes: v1.0.0 - CAD/CAM Technology Docs Stable

Tag: v1.0.0
Title: v1.0.0 - CAD/CAM Technology Docs Stable
Date: 2026-07-01
RC1 Validation: v1.0.0-rc1 验证通过(V10D)

Overview

这是 CAD/CAM Technology Docs 的第一个稳定版(v1.0.0)。从 v0.2.0 的课程化结构开始,经历了 v3-v4 工程案例化、v5-v6 FreeCAD 实操 + Capstone 项目、v7-v9 CadQuery 代码建模 + Assembly + Runtime/Portfolio、v10 首页 Showcase + 全站质量审计,最终形成完整的工程学习站。

项目定位

CAD/CAM Technology Docs 是一个从《CAD/CAM 技术基础》阅读笔记演进而来的现代化工程学习站,覆盖课程基础、FreeCAD 实操、STEP/STL 数据交换、CAM/G-code、Capstone 项目、CadQuery 代码化建模与 Assembly 装配体作品集。

核心特点

  • 课程化结构(8 章基础教材)
  • 完整的工程案例(CAD→G-code、数据交换、CAPP)
  • 实战线(FreeCAD 五步路线 + Capstone 项目)
  • 代码化建模(CadQuery + Assembly)
  • 作品集归档(V9 Runtime / Portfolio)
  • 现代化站点(Hero / 入口矩阵 / 推荐路径 / 能力矩阵 / v1.0 路线图)

入口链接

从旧笔记到现代课程站的演进

阶段 时间 主要交付
V1-V2 2024-06 旧 Sphinx 笔记 → 现代化 Sphinx + Furo + GitHub Pages;课程化结构(unit1-unit8)
V3-V4C 2024-06 工程案例(CAD→G-code、数据交换、CAPP)+ G-code 教学 + STEP/STL mini-lab + 工具链路线图
V5A-V5D 2024-06 FreeCAD 实操线(建模 → 导出 → CAM → 收口)
V6A-V6D 2024-06 支架 Capstone 项目线(5 阶段 + 项目档案 + 评分表 + 路径收口)
V7A-V7D 2024-06 CadQuery 代码化建模线(参数化 → 进阶特征 → 支架代码 → 学习路径)
V8A-V8D 2024-06 CadQuery Assembly 装配体线(多零件 → BOM → Placement → 学习路径)
V9A-V9D 2026-07 Runtime / Portfolio 作品集收口线
V10A 2026-07 首页 Showcase 化 + project-showcase 全景页
V10B 2026-07 全站质量审计(v1.0 readiness: READY)
V10C 2026-07 最终发布收口(本版本)
v1.0.0 本次 稳定版发布

主要功能模块

课程基础

  • 8 章完整教材(unit1-unit8)
  • 学习辅助(章节地图、词汇表、复习题、学习路径)
  • 课程总览、章节地图

工程案例

  • CAD → G-code 完整制造流程
  • 数据交换(STEP/STL/IGES 等格式)
  • CAPP 工艺路线

FreeCAD 实操线(V5A-V5D)

  • 带孔矩形板建模 + STEP/STL 导出
  • 导出检查清单
  • CAM 任务单
  • 五步学习路线收口

Capstone 项目线(V6A-V6D)

  • L 型支架综合项目(5 阶段)
  • 项目档案 + 评分表
  • Path Workbench 入门
  • 项目线收口

CadQuery 代码化建模线(V7A-V7D)

  • Python + CadQuery 参数化建模
  • 圆角/倒角/孔阵列/支架变体
  • 完整 L 型支架代码模型(与 V6A 几何一致)
  • V7 系列三步走收口

Assembly 装配体线(V8A-V8D)

  • 多零件装配(Location 概念)
  • BOM + 爆炸图 + 检查清单
  • 子装配 + 干涉检查
  • V8 系列三步走收口

Runtime / Portfolio 路线(V9A-V9D)

  • Capstone 作品集升级(V9A)
  • CadQuery 真实运行试点(V9B)
  • CadQuery 本地环境指南(V9C)
  • CadQuery 运行与作品集路线(V9D)

Showcase 首页(V10A)

  • Hero 区块(项目定位 + 当前版本 + GitHub 入口)
  • 六大入口矩阵(卡片式)
  • 推荐阅读路径(5 种读者类型)
  • 项目能力矩阵
  • v1.0 前路线图
  • 项目全景页(project-showcase)

质量门摘要

指标 结果
Sphinx 构建 ✅ 0 warning
py_compile code/cadquery ✅ 6/6 OK
py_compile scripts/cadquery ✅ 4/4 OK
本地链接审计 ✅ 47 HTML / 3,654 引用 / 0 broken
线上关键页面 ✅ 13/13 HTTP 200(首页 / project-showcase / V9B-D / search 等)
README 必含元素 ✅(一句话定位 / 快速入口 / 能力矩阵 / 版本演进 / v1.0 Roadmap)
Release/tag 基线 ✅ 一致

已知限制

1. 云端环境未能真实运行 CadQuery/OCP

限制:当前 GitHub Pages / Sphinx 构建环境为 Ubuntu + Python 3.10 + 无 OCCT 共享库。

影响

  • 6 个 CadQuery .py 文件通过 py_compile 语法检查,但 import cadquery 因 OCCT 不可用而失败
  • 云端不能真实生成 STEP/STL 文件
  • scripts/cadquery/smoke_test.py 在云端运行会失败

替代方案

  • 读者按 :doc:cadquery-local-environment-guide 在本地配置环境
  • 推荐 conda 路线(自动处理 OCCT 二进制)
  • 备选 pip 路线(需 Python 3.11+)

2. 不提交伪造 STEP/STL

原则:教学诚信优先于"看起来完成"。

具体措施

  • assets/cadquery-exports/ 目录仅包含 README 说明,不包含假 STEP/STL 文件
  • 所有 .gitignore 已忽略 *.step/*.stp/*.stl(本地导出默认不提交)
  • 真实的导出文件由读者按本地指南生成

3. 真实导出需按本地环境指南操作

读者如需在本地运行 CadQuery:

  1. 阅读 :doc:cadquery-local-environment-guide(V9C)
  2. 选择路线:conda(推荐)或 pip + Python 3.11+
  3. 运行 smoke test 验证环境
  4. 运行 V7/V8 示例,导出 STEP/STL
  5. verify_exports.py 验证导出文件格式

后续路线

v1.0.0 稳定版发布后,下一步可选方向:

  1. 真实软件截图 — 加入 SolidWorks / FreeCAD / Fusion 等软件的真实截图
  2. 第二 Capstone — 带圆角/倒角/多特征的 Capstone 综合项目
  3. 真实 CadQuery 环境运行结果 — 用 conda 在本地生成真实 STEP/STL 并归档
  4. 教学视频或录屏 — 录屏演示完整作品集提交流程
  5. 第二 Showcase 增强 — 增加 Mermaid 流程图、动态元素

v1.0.0 与 V10A/V10B 的关系

版本 角色
V10A 首页 Showcase 化(视觉升级)
V10B 全站质量审计(v1.0 readiness: READY)
V10C 最终发布收口(v1.0.0 release candidate 准备)
v1.0.0 稳定版发布(长期支持里程碑)

Build & Verification

项目 结果
Build Command sphinx-build -b html -W --keep-going . _build/html
Build Result ✅ succeeded
Warning Count 0
py_compile code/cadquery/*.py ✅ 6/6 OK
py_compile scripts/cadquery/*.py ✅ 4/4 OK
Local Link Audit ✅ 0 broken / 3,654 refs
Online URL Audit ✅ 13/13 HTTP 200
Release/Tag Consistency

Teaching Notes

  • 不新增大型课程内容
  • 不重写 unit1~unit8
  • 不破坏已完成的 V5/V6/V7/V8/V9 页面
  • 不引入后端、数据库或复杂前端
  • 保持 Sphinx + Furo + GitHub Pages 静态站路线
  • 教学诚信:不伪造 STEP/STL 文件

Released by OpenClaw Agent (longxia2) on 2026-07-01.

This is the first stable release (v1.0.0) of CAD/CAM Technology Docs.

v1.0.0-rc1 - Stable Release Candidate

Pre-release

Choose a tag to compare

@conanxin conanxin released this 01 Jul 01:26

Release Notes: v1.0.0 - CAD/CAM Technology Docs Stable

Tag: v1.0.0
Title: v1.0.0 - CAD/CAM Technology Docs Stable
Date: 2026-07-01

Overview

这是 CAD/CAM Technology Docs 的第一个稳定版(v1.0.0)。从 v0.2.0 的课程化结构开始,经历了 v3-v4 工程案例化、v5-v6 FreeCAD 实操 + Capstone 项目、v7-v9 CadQuery 代码建模 + Assembly + Runtime/Portfolio、v10 首页 Showcase + 全站质量审计,最终形成完整的工程学习站。

项目定位

CAD/CAM Technology Docs 是一个从《CAD/CAM 技术基础》阅读笔记演进而来的现代化工程学习站,覆盖课程基础、FreeCAD 实操、STEP/STL 数据交换、CAM/G-code、Capstone 项目、CadQuery 代码化建模与 Assembly 装配体作品集。

核心特点

  • 课程化结构(8 章基础教材)
  • 完整的工程案例(CAD→G-code、数据交换、CAPP)
  • 实战线(FreeCAD 五步路线 + Capstone 项目)
  • 代码化建模(CadQuery + Assembly)
  • 作品集归档(V9 Runtime / Portfolio)
  • 现代化站点(Hero / 入口矩阵 / 推荐路径 / 能力矩阵 / v1.0 路线图)

入口链接

从旧笔记到现代课程站的演进

阶段 时间 主要交付
V1-V2 2024-06 旧 Sphinx 笔记 → 现代化 Sphinx + Furo + GitHub Pages;课程化结构(unit1-unit8)
V3-V4C 2024-06 工程案例(CAD→G-code、数据交换、CAPP)+ G-code 教学 + STEP/STL mini-lab + 工具链路线图
V5A-V5D 2024-06 FreeCAD 实操线(建模 → 导出 → CAM → 收口)
V6A-V6D 2024-06 支架 Capstone 项目线(5 阶段 + 项目档案 + 评分表 + 路径收口)
V7A-V7D 2024-06 CadQuery 代码化建模线(参数化 → 进阶特征 → 支架代码 → 学习路径)
V8A-V8D 2024-06 CadQuery Assembly 装配体线(多零件 → BOM → Placement → 学习路径)
V9A-V9D 2026-07 Runtime / Portfolio 作品集收口线
V10A 2026-07 首页 Showcase 化 + project-showcase 全景页
V10B 2026-07 全站质量审计(v1.0 readiness: READY)
V10C 2026-07 最终发布收口(本版本)
v1.0.0 本次 稳定版发布

主要功能模块

课程基础

  • 8 章完整教材(unit1-unit8)
  • 学习辅助(章节地图、词汇表、复习题、学习路径)
  • 课程总览、章节地图

工程案例

  • CAD → G-code 完整制造流程
  • 数据交换(STEP/STL/IGES 等格式)
  • CAPP 工艺路线

FreeCAD 实操线(V5A-V5D)

  • 带孔矩形板建模 + STEP/STL 导出
  • 导出检查清单
  • CAM 任务单
  • 五步学习路线收口

Capstone 项目线(V6A-V6D)

  • L 型支架综合项目(5 阶段)
  • 项目档案 + 评分表
  • Path Workbench 入门
  • 项目线收口

CadQuery 代码化建模线(V7A-V7D)

  • Python + CadQuery 参数化建模
  • 圆角/倒角/孔阵列/支架变体
  • 完整 L 型支架代码模型(与 V6A 几何一致)
  • V7 系列三步走收口

Assembly 装配体线(V8A-V8D)

  • 多零件装配(Location 概念)
  • BOM + 爆炸图 + 检查清单
  • 子装配 + 干涉检查
  • V8 系列三步走收口

Runtime / Portfolio 路线(V9A-V9D)

  • Capstone 作品集升级(V9A)
  • CadQuery 真实运行试点(V9B)
  • CadQuery 本地环境指南(V9C)
  • CadQuery 运行与作品集路线(V9D)

Showcase 首页(V10A)

  • Hero 区块(项目定位 + 当前版本 + GitHub 入口)
  • 六大入口矩阵(卡片式)
  • 推荐阅读路径(5 种读者类型)
  • 项目能力矩阵
  • v1.0 前路线图
  • 项目全景页(project-showcase)

质量门摘要

指标 结果
Sphinx 构建 ✅ 0 warning
py_compile code/cadquery ✅ 6/6 OK
py_compile scripts/cadquery ✅ 4/4 OK
本地链接审计 ✅ 47 HTML / 3,654 引用 / 0 broken
线上关键页面 ✅ 13/13 HTTP 200(首页 / project-showcase / V9B-D / search 等)
README 必含元素 ✅(一句话定位 / 快速入口 / 能力矩阵 / 版本演进 / v1.0 Roadmap)
Release/tag 基线 ✅ 一致

已知限制

1. 云端环境未能真实运行 CadQuery/OCP

限制:当前 GitHub Pages / Sphinx 构建环境为 Ubuntu + Python 3.10 + 无 OCCT 共享库。

影响

  • 6 个 CadQuery .py 文件通过 py_compile 语法检查,但 import cadquery 因 OCCT 不可用而失败
  • 云端不能真实生成 STEP/STL 文件
  • scripts/cadquery/smoke_test.py 在云端运行会失败

替代方案

  • 读者按 :doc:cadquery-local-environment-guide 在本地配置环境
  • 推荐 conda 路线(自动处理 OCCT 二进制)
  • 备选 pip 路线(需 Python 3.11+)

2. 不提交伪造 STEP/STL

原则:教学诚信优先于"看起来完成"。

具体措施

  • assets/cadquery-exports/ 目录仅包含 README 说明,不包含假 STEP/STL 文件
  • 所有 .gitignore 已忽略 *.step/*.stp/*.stl(本地导出默认不提交)
  • 真实的导出文件由读者按本地指南生成

3. 真实导出需按本地环境指南操作

读者如需在本地运行 CadQuery:

  1. 阅读 :doc:cadquery-local-environment-guide(V9C)
  2. 选择路线:conda(推荐)或 pip + Python 3.11+
  3. 运行 smoke test 验证环境
  4. 运行 V7/V8 示例,导出 STEP/STL
  5. verify_exports.py 验证导出文件格式

后续路线

v1.0.0 稳定版发布后,下一步可选方向:

  1. 真实软件截图 — 加入 SolidWorks / FreeCAD / Fusion 等软件的真实截图
  2. 第二 Capstone — 带圆角/倒角/多特征的 Capstone 综合项目
  3. 真实 CadQuery 环境运行结果 — 用 conda 在本地生成真实 STEP/STL 并归档
  4. 教学视频或录屏 — 录屏演示完整作品集提交流程
  5. 第二 Showcase 增强 — 增加 Mermaid 流程图、动态元素

v1.0.0 与 V10A/V10B 的关系

版本 角色
V10A 首页 Showcase 化(视觉升级)
V10B 全站质量审计(v1.0 readiness: READY)
V10C 最终发布收口(v1.0.0 release candidate 准备)
v1.0.0 稳定版发布(长期支持里程碑)

Build & Verification

项目 结果
Build Command sphinx-build -b html -W --keep-going . _build/html
Build Result ✅ succeeded
Warning Count 0
py_compile code/cadquery/*.py ✅ 6/6 OK
py_compile scripts/cadquery/*.py ✅ 4/4 OK
Local Link Audit ✅ 0 broken / 3,654 refs
Online URL Audit ✅ 13/13 HTTP 200
Release/Tag Consistency

Teaching Notes

  • 不新增大型课程内容
  • 不重写 unit1~unit8
  • 不破坏已完成的 V5/V6/V7/V8/V9 页面
  • 不引入后端、数据库或复杂前端
  • 保持 Sphinx + Furo + GitHub Pages 静态站路线
  • 教学诚信:不伪造 STEP/STL 文件

Released by OpenClaw Agent (longxia2) on 2026-07-01.

This is the first stable release (v1.0.0) of CAD/CAM Technology Docs.

v0.10.0 - Homepage Showcase

Choose a tag to compare

Release Notes: v0.10.0 - Homepage Showcase

Tag: v0.10.0-homepage-showcase
Title: v0.10.0 - Homepage Showcase
Date: 2026-07-01

Overview

本次发布完成 V10A:首页视觉升级 + 全站 Showcase 化。把内容丰富但偏文档型的站点升级为作品集型学习站,使访问者打开首页后能立刻理解项目是什么、学习路线、有哪些实操线、有哪些 Capstone / CadQuery / Assembly / Portfolio 成果。

What's New

新增页面

文件 说明
project-showcase.rst 项目全景页(A-I 结构):项目起源、模块清单、演进时间线、Showcase 入口表、适合读者、后续规划

首页 index.rst 视觉升级

新增以下区块:

  • A. Hero 区块 — 项目一句话定位 + 当前版本 + GitHub Pages / GitHub Repo / Release / Showcase 入口
  • B. 六大入口 — 课程基础 / FreeCAD 实操线 / 工程案例 / Capstone 项目线 / CadQuery 代码建模 / Assembly 装配体线 / Runtime-Portfolio 收口线
  • C. 推荐阅读路径 — 5 种读者类型的明确入口(零基础 / 实操派 / 作品集派 / 代码派 / 装配派)
  • D. 项目能力矩阵 — 8 大能力模块 + 覆盖内容 + 对应页面 + 成熟度
  • E. v1.0 前路线图 — V10A → V10B → V10C → v1.0.0 路线
  • 保留原有"快速入口"和"如何使用本站"

新增 SVG 图示

文件 说明
_static/diagrams/site-showcase-map.svg 站点全景图:课程基础 → FreeCAD → Capstone → CadQuery → Assembly → Portfolio
_static/diagrams/v1-roadmap.svg v1.0 Roadmap:从 v0.9.x 到 V10A Showcase → V10B Quality Audit → V10C Release Closure → v1.0.0 Stable

新增 CSS 样式

文件 说明
_static/css/showcase.css 轻量 CSS:Hero / entry-card / path-card / roadmap-block / timeline 等样式

配置:在 conf.py 中追加 html_css_files = ['css/showcase.css']

特点

  • 不破坏 Furo 默认主题
  • 不引入外部字体或外部 CSS
  • 不依赖 JavaScript
  • 仅改善首页和 project-showcase 页的视觉层次

现有页面更新

文件 更新内容
conf.py 新增 html_css_files 配置(追加 showcase.css)
workflow-roadmap.rst 轻量加入 project-showcase 入口说明("下一步建议"区块 + 末尾"项目全景补充")
examples/index.rst 新增"从 Showcase 开始"区块 + 6 大分组入口
README.md 项目一句话定位 + 状态表 + 9 项快速入口表 + 完整能力矩阵(追加 V10A)+ V10A 教学亮点 + v1.0 Roadmap

Build & Verification

项目 结果
Build Command sphinx-build -b html -W --keep-going . _build/html
Build Result ✅ succeeded
Warning Count 0
py_compile code/cadquery/*.py ✅ 6/6 OK
py_compile scripts/cadquery/*.py ✅ 4/4 OK
showcase.css XML/CSS 加载 ✅ link 标签存在于 index.html
SVG XML 解析 ✅ 2/2 OK
project-showcase.html 生成
index.html Hero + 入口 + 矩阵 + 路线图 ✅ 全部存在

Teaching Notes

  • 不新增大型课程内容
  • 不重写 unit1~unit8
  • 不破坏 V5/V6/V7/V8/V9 页面
  • 不引入后端、数据库或复杂前端
  • 保持 Sphinx + Furo 静态站路线
  • 轻量 CSS 仅改善视觉层次,不破坏 Furo 默认主题
  • 2 个新 SVG 全部本地,无外部依赖
  • 构建保持 0 warning

后续规划

  • V10B:全站质量审计(链接失效检查、死链排查、Sphinx 0 warning、HTML/CSS 验证、SVG 引用检查)
  • V10C:最终发布收口(README 最终版、release notes、导航/标签收口)
  • v1.0.0:稳定版发布(长期支持里程碑)

Released by OpenClaw Agent (longxia2) on 2026-07-01.

v0.9.3 - CadQuery Runtime Portfolio Path

Choose a tag to compare

Release Notes: v0.9.3 - CadQuery Runtime Portfolio Path

Tag: v0.9.3-cadquery-runtime-portfolio-path
Title: v0.9.3 - CadQuery Runtime Portfolio Path
Date: 2026-07-01

Overview

本次发布完成 V9 系列的总入口与发布收口。V9A/V9B/V9C 分别解决了"作品集提交结构""运行诊断""本地环境配置",V9D 把三者整合为一条可发布的学习闭环,并新增 2 个 SVG 直观展示 V9 路线与运行层级关系。

What's New

新增页面

文件 说明
examples/cadquery-runtime-portfolio-path.rst V9 总入口与发布收口(A-J 结构)

页面结构

  • A. 这条路线解决什么问题 — V9 系列分工表 + 教学诚信说明
  • B. 三步学习路线 — V9A 作品集升级 → V9B 运行诊断 → V9C 本地导出(含 SVG)
  • C. 文件与脚本地图 — 9 个核心资源(页面、脚本、配置、README)
  • D. 真实运行状态说明 — py_compile → import → build → export → verify 五层关系(含 SVG)
  • E. 作品集提交建议 — 升级版作品集结构(含运行记录模块)
  • F. 学习完成标准 — 8 项完成标准表
  • G. 常见误区 — 7 条误区
  • H. 教学声明 — V9D 定位与边界
  • I. 相关页面 — 14 个链接
  • J. 相关脚本与资源 — 6 个文件

新增 SVG 图示

文件 说明
_static/diagrams/cadquery-runtime-portfolio-path.svg V9 三步路线总览图(V9A → V9B → V9C → 本地导出 → 作品集归档)
_static/diagrams/pycompile-import-export-levels.svg py_compile → import → build → export → verify 五层关系图

现有页面更新

文件 更新内容
examples/index.rst 新增案例 X(V9D)、推荐顺序 12、阅读顺序 26、toctree、对照表行
workflow-roadmap.rst 新增 V9D CadQuery 运行与作品集路线小节
README.md 版本号、亮点、能力矩阵(4 项)、教学亮点、快速入口(V9D 链接)、版本里程碑

V9 系列完成状态

版本 主题 Commit Tag
V9A Capstone 作品集升级 544ebf6 v0.9.0-capstone-portfolio-upgrade
V9B CadQuery 真实运行试点 2c96b52 v0.9.1-cadquery-runtime-export-pilot
V9C CadQuery 本地环境指南 98c9bd3 v0.9.2-cadquery-local-environment-guide
V9D CadQuery 运行与作品集路线 本次 v0.9.3-cadquery-runtime-portfolio-path

V9 系列封版,作品集线形成完整闭环:

  • V6A-V6D(图形化 Capstone 项目线)
  • V7A-V7D(代码化建模线)
  • V8A-V8D(装配体表达线)
  • V9A-V9D(运行、作品集、环境、收口)

Build & Verification

项目 结果
Build Command sphinx-build -b html -W --keep-going . _build/html
Build Result ✅ succeeded
Warning Count 0
py_compile code/cadquery/*.py ✅ 6/6 OK
py_compile scripts/cadquery/*.py ✅ 4/4 OK
新增 SVG XML 解析 ✅ 2/2 OK
新增页面 HTML 生成 ✅ 存在

Teaching Notes

  • 不新增第二个 Capstone(按要求)
  • 不新增真实软件截图(按要求)
  • 不重写 unit1~unit8(按要求)
  • 不破坏 V9A/V9B/V9C 页面(按要求)
  • 不提交假的 STEP/STL 文件(按要求)
  • 不引入后端/数据库/复杂前端(按要求)
  • 构建保持 0 warning(按要求)

V9D 仅作为 V9 系列的路线总入口与发布收口,不引入新代码或新脚本。


Released by OpenClaw Agent (longxia2) on 2026-07-01.

v0.9.2 - CadQuery Local Environment Guide

Choose a tag to compare

Release Notes: v0.9.2 - CadQuery Local Environment Guide

Tag: v0.9.2-cadquery-local-environment-guide
Title: v0.9.2 - CadQuery Local Environment Guide
Date: 2026-06-30

Overview

本次发布新增 CadQuery 本地环境配置指南与本地导出工作流。V9B 诊断了服务器端环境限制(OCCT 不可用),V9C 为读者提供在自己机器上运行 CadQuery 的完整路线。

What's New

新增页面

文件 说明
examples/cadquery-local-environment-guide.rst CadQuery 本地运行环境指南(A-J 结构)

页面结构

  • A. 本页解决什么问题 — V9B 后续、本地运行路线
  • B. 为什么 py_compile 通过不等于 CadQuery 可运行 — 语法检查 vs 运行依赖
  • C. 推荐本地环境路线 — 路线 1(Python venv)+ 路线 2(Conda 推荐)
  • D. 最小 smoke test — 最小验证代码
  • E. 运行本项目示例 — 6 个 .py 推荐顺序
  • F. 导出文件保存策略 — local-exports/ + .gitignore
  • G. 导出后检查 — 8 项检查清单 + 自动化脚本
  • H. 常见错误 — 9 条常见错误与解决方法
  • I. 相关页面 — 9 个链接
  • J. 相关脚本 — 5 个脚本文件

新增脚本文件

文件 说明
scripts/cadquery/smoke_test_cadquery.py 最小环境验证(import + box + export)
scripts/cadquery/run_plate_export.py 导出 plate_with_hole 到 local-exports/
scripts/cadquery/verify_exports.py 验证导出的 STEP/STL 文件格式
scripts/cadquery/README.md 脚本使用说明

新增可选文件

文件 说明
environment-cadquery.yml Conda 环境配置示例(不影响 Sphinx 构建)

.gitignore 更新

加入:

  • local-exports/
  • *.step / *.stp / *.stl
  • venv-cadquery/ / cad-env/
  • smoke_test.step / smoke_test.stl

现有页面更新

文件 更新内容
examples/cadquery-runtime-export-pilot.rst 新增"下一步:本地运行环境指南" + 链接
examples/cadquery-learning-path.rst 新增 V9C 本地环境指南说明
examples/cadquery-parametric-modeling.rst 新增 V9C 本地导出说明
examples/index.rst 新增案例 W(V9C)、推荐顺序 11、阅读顺序 25、toctree、对照表行
workflow-roadmap.rst 新增 V9C 本地环境指南说明
README.md 版本号、亮点、能力矩阵、快速入口、版本里程碑

Build & Verification

项目 结果
Build Command sphinx-build -b html -W --keep-going . _build/html
Build Result ✅ succeeded
Warning Count 0
py_compile code/cadquery/*.py ✅ 6/6 OK
py_compile scripts/cadquery/*.py ✅ 4/4 OK
smoke_test 运行 ❌ 环境受限(CadQuery 不可用),记录为环境限制

Teaching Notes

  • 不要求服务器端能跑 CadQuery
  • 不创建假 STEP/STL 文件
  • 优先教学诚信
  • 读者本地可按指南配置环境

Released by OpenClaw Agent (longxia2) on 2026-06-30.

v0.9.1 - CadQuery Runtime Export Pilot

Choose a tag to compare

Release Notes: v0.9.1 - CadQuery Runtime Export Pilot

Tag: v0.9.1-cadquery-runtime-export-pilot
Title: v0.9.1 - CadQuery Runtime Export Pilot
Date: 2026-06-30

Overview

本次发布是 V7/V8 代码示例的真实运行与导出试点。V7A-V9A 所有 CadQuery 代码都通过了 py_compile 语法检查,但没有真实生成模型。V9B 尝试在当前环境下真实运行 CadQuery 并导出 STEP/STL,把"代码仅语法通过"升级为"代码能真实生成"。

关键定位

  • V9B 仍可 PASS 即使环境受限(任务明确说"不把环境安装失败当作任务失败")
  • 不创建假的 STEP/STL 文件
  • 记录完整的环境诊断 + 真实运行结果
  • 为读者提供本地运行指导

What's New

新增文档页面

文件 说明
examples/cadquery-runtime-export-pilot.rst CadQuery 真实运行与导出试点主页(A-J 结构)

页面结构(A-J 节)

  • A. 为什么要做真实运行试点 — py_compile 不够,V9B 填补
  • B. 测试范围 — 6 个 .py 文件清单
  • C. 运行结果表 — 6/6 文件 py_compile OK,但 CadQuery import 都失败
  • D. 环境诊断 — OS/Python/pip/OCCT 详细诊断
  • E. 尝试诊断 — 7 种尝试 + 失败原因
  • F. 如果成功导出(教学性说明) — 标准流程
  • G. 如果环境受限(实际结果) — 不阻塞项目 + 读者本地指导
  • H. 常见问题 — 8 条 V9B 常见问题
  • I. 教学声明 — 教学诚信
  • J. 相关页面 — 9 个相关链接

新增资源包文件

文件 说明
assets/cadquery-exports/README.md 当前环境状态说明(无 STEP/STL 文件)

资源包特点

  • 包含任何假 STEP/STL 文件
  • 包含完整的环境说明
  • 包含读者本地运行指导
  • 包含文件检查建议

现有页面更新

文件 更新内容
examples/index.rst 新增"案例 V"(V9B)、推荐顺序 1→10、阅读顺序 24、toctree、对照表行
examples/cadquery-learning-path.rst 新增 V9B CadQuery 实际运行试点说明 + 链接
examples/cadquery-parametric-modeling.rst 新增 L 节 V9B 实际运行试点 + 链接
examples/step-stl-mini-lab.rst 新增 V9B CadQuery 实际运行说明 + 链接
workflow-roadmap.rst 新增 V9B 实际运行试点说明
README.md 版本号、亮点、能力矩阵、快速入口、版本演进、教学亮点

Build & Verification

项目 结果
Build Command sphinx-build -b html -W --keep-going . _build/html
Build Result ✅ succeeded
Warning Count 0
py_compile (6 .py) ✅ 6/6 OK
CadQuery import ❌ ModuleNotFoundError: No module named 'OCP'
CadQuery runtime ❌ 6/6 文件实际运行失败
STEP/STL 导出 ❌ 未生成(环境受限)

环境诊断结果

项目 状态
OS Ubuntu 22.04.5 LTS
Python 3.10.12 ⚠️ 偏旧
CadQuery 2.8.0 requires Python >=3.11 ❌ 不兼容
CadQuery 2.3.0 last Python 3.10 support ⚠️ 可装但需 OCP
OCP for Python 3.10 PyPI mirror 不可用
pythonocc-core PyPI mirror 不可用

结论:本环境未能真实运行 CadQuery。V9B 仍 PASS(按任务要求,环境安装失败不阻塞)。

Related Pages

Next Steps

候选方向:

  1. V9C — 真实软件截图(SolidWorks / FreeCAD / Fusion 360)整合到作品集
  2. V10A — 用 CadQuery 重做 V4B mini-lab(参数化立方体/圆柱体对比)
  3. V10B — 第二 Capstone(带圆角/倒角/多特征)
  4. V10C — 录屏演示 V6 → V7 → V8 → V9A 完整作品集提交流程
  5. V10D — 真实 OCCT 环境配置教程(conda/mamba)

Teaching Notes

本版本是真实环境诊断的记录:

  • 不替代 V7/V8 教学价值
  • 明确记录环境限制
  • 优先教学诚信(不创建假文件)
  • 任务可 PASS 即使环境受限

Released by OpenClaw Agent (longxia2) on 2026-06-30.

v0.9.0 - Capstone Portfolio Upgrade

Choose a tag to compare

Release Notes: v0.9.0 - Capstone Portfolio Upgrade

Tag: v0.9.0-capstone-portfolio-upgrade
Title: v0.9.0 - Capstone Portfolio Upgrade
Date: 2026-06-30

Overview

本次发布是 V6/V7/V8 三条学习线的整合收口。学完 V6 Capstone 项目线 + V7 CadQuery 代码化建模线 + V8 CadQuery Assembly 装配体线后,读者应该能够把三条线的成果合并为一个更完整的 Capstone 作品集

V9A 提供:

  • 升级版作品集结构(11 大类模块)
  • 推荐文件夹结构(含 cad-freecad/ / cadquery/ / assembly/ 等子目录)
  • V6/V7/V8 页面在作品集中的位置对照表
  • 作品集提交说明模板(10 节)
  • 自评升级清单(9 项检查 + 总评公式)
  • 8 条常见误区
  • 2 个资源包文件(portfolio-upgrade-template.md + portfolio-file-manifest-v2.md)

What's New

新增文档页面

文件 说明
examples/capstone-portfolio-upgrade.rst Capstone 作品集升级主页(A-I 结构)

页面结构(A-I 节)

  • A. 本页解决什么问题 — V6/V7/V8 三线整合
  • B. 升级后的作品集结构 — 11 大类模块(必选 + 进阶)
  • C. 推荐文件夹结构bracket-capstone-portfolio/ 完整目录
  • D. V6/V7/V8 对照表 — 各页面在作品集中的位置
  • E. 作品集提交说明模板 — 10 节模板
  • F. 自评升级清单 — 9 项检查 + 总评公式
  • G. 常见误区 — 8 条 V9A 特有误区
  • H. 教学声明 — 收口页性质
  • I. 相关页面 — 9 个相关链接

新增资源包文件

文件 说明
assets/bracket-capstone/portfolio-upgrade-template.md 升级版作品集说明模板(10 节)
assets/bracket-capstone/portfolio-file-manifest-v2.md 升级版文件清单(必选 ✅ / 进阶 ⭐ 标注)

现有页面更新

文件 更新内容
examples/bracket-project-portfolio.rst 新增 V9A 升级说明 + 链接
examples/capstone-learning-path.rst 新增 V7/V8 高级扩展 + V9A 链接
examples/cadquery-learning-path.rst 新增 V9A 作品集升级 + 链接
examples/cadquery-assembly-learning-path.rst 新增 V9A 作品集升级 + 链接
examples/index.rst 新增"案例 U"(V9A)、推荐顺序 1→9、阅读顺序 23、toctree、对照表行
workflow-roadmap.rst 新增 V9A 作品集整合说明
README.md 版本号、亮点、能力矩阵、快速入口、版本演进、教学亮点

Build & Verification

项目 结果
Build Command sphinx-build -b html -W --keep-going . _build/html
Build Result ✅ succeeded
Warning Count 0
py_compile (6 .py) ✅ 6/6 OK
CadQuery import ⚠️ 不可用(环境限制,不阻塞)

V6/V7/V8/V9A 完成状态

学习线 状态 范围
V6 Capstone 项目线 ✅ V6A-V6D 全部完成 图形化项目制学习
V7 CadQuery 单零件 ✅ V7A-V7D 全部完成 代码化单零件建模
V8 CadQuery Assembly ✅ V8A-V8D 全部完成 代码化多零件装配体
V9A 作品集升级 ✅ 完成 三线整合收口

Related Pages

Next Steps

候选方向:

  1. V9B — 真实软件截图(SolidWorks / FreeCAD / Fusion 360)整合到作品集
  2. V9C — CadQuery 真实环境运行(OCCT 安装)+ 真实 STEP 导出检查
  3. V10 — 用 CadQuery 重做 V4B mini-lab
  4. V10 — 第二 Capstone(带圆角/倒角/多特征)
  5. V10 — 录屏演示 V6 → V7 → V8 → V9A 完整作品集提交流程

Teaching Notes

本版本是 V6/V7/V8 的整合收口

  • 不重写 V6/V7/V8 内容
  • 仅作为"如何把三条线合并提交"的整合指南
  • 与 V6B 作品集模板兼容(保留 V6 基础 + 扩展 V7/V8)
  • 真实工程中应根据项目需求选择提交内容

Released by OpenClaw Agent (longxia2) on 2026-06-30.

v0.8.3 - Assembly Learning Path

Choose a tag to compare

Release Notes: v0.8.3 - Assembly Learning Path

Tag: v0.8.3-assembly-learning-path
Title: v0.8.3 - Assembly Learning Path
Date: 2026-06-30

Overview

本次发布是 V8 系列(代码化装配体)的收口页。V8A → V8B → V8C 三步走构成了"代码化装配体理解"的完整学习闭环,V8D 提供:

  • 三步学习路线图(V8A 入门 → V8B 进阶 → V8C mini-lab)
  • Assembly 代码文件地图(2 个 .py + 5 个资源包)
  • Assembly 与 Capstone 的关系(V6 / V7 / V8 三线对比)
  • 单零件 / 装配体 / BOM / G-code 的数据层级关系
  • 15+ 项完成标准 + 8 条常见误区 + 后续扩展方向

V8D 与 V7D 形成完整对照:V7D 是"单零件代码化建模"收口,V8D 是"多零件装配体"收口。

What's New

新增文档页面

文件 说明
examples/cadquery-assembly-learning-path.rst Assembly 学习路径收口页(A-J 结构)

页面结构(A-J 节)

  • A. 这条路线解决什么问题 — V8A/V8B/V8C 三阶段概览
  • B. 三步学习路线 — V8A 入门(2-3h)→ V8B 进阶(1-2d)→ V8C mini-lab(2-3d)
  • C. Assembly 代码文件地图 — 2 .py + 5 资源包
  • D. Assembly 与 Capstone 的关系 — V6 / V7 / V8 三线对比
  • E. 单零件、装配体、BOM、G-code 的层级关系 — 4 类数据对比
  • F. 学习完成标准 — 基础/进阶/综合/元 4 类共 15+ 项
  • G. 常见误区 — 8 条 V8 系列特有误区
  • H. 后续扩展方向 — 代码化 / 图形化结合 / 教学 / 工程 4 大类
  • I. 教学声明 — 收口页性质
  • J. 相关页面 — 10+ 个相关链接

新增 SVG 图示

文件 内容 尺寸
_static/diagrams/assembly-learning-path.svg V8 Assembly 三步学习路线图(V8A → V8B → V8C) 900×280
_static/diagrams/model-assembly-bom-gcode-levels.svg 单零件 / 装配体 / BOM / G-code 的数据层级关系 900×360

导航更新

文件 更新内容
examples/index.rst 新增"案例 T"(V8D)、推荐顺序 1→8、阅读顺序 22、toctree、对照表行
workflow-roadmap.rst 新增任务 1.15(V8D)、CAD 设计工具列表更新
README.md 版本号更新至 v0.8.3;新增"Assembly 学习路径"亮点;能力矩阵新增 V8D 行;快速入口新增 V8D 链接;版本演进新增 V8D 条目;教学亮点速览新增 V8D 条目

Build & Verification

项目 结果
Build Command sphinx-build -b html -W --keep-going . _build/html
Build Result ✅ succeeded
Warning Count 0
CadQuery import ⚠️ 不可用(环境限制,不阻塞)

Related Pages

Next Steps

候选方向:

  1. V9 — 用 CadQuery 重做 bracket-capstone-project 全部零件(含 V7C + V8 装配体版本)
  2. V9 — V6 作品集模板升级(加入 V8A/V8B/V8C 装配体补充)
  3. V9 — 真实软件截图(SolidWorks / FreeCAD / Fusion 360)
  4. V9 — 用 CadQuery 重做 V4B mini-lab
  5. V9 — 第二 Capstone(带圆角/倒角/多特征的复杂零件)

Teaching Notes

本版本是 V8 系列的收口页

  • 不重写 V8A/V8B/V8C 的内容
  • 不引入新代码或新特征
  • 仅作为"路线图 + 完成标准 + 扩展方向"导航
  • 与 V7D 形成完整对照:V7D 单零件收口 / V8D 多零件收口
  • 真实工程中应根据团队技能选择建模方式

Released by OpenClaw Agent (longxia2) on 2026-06-30.

v0.8.2 - Assembly Placement Mini-lab

Choose a tag to compare

Release Notes: v0.8.2 - Assembly Placement Mini-lab

Tag: v0.8.2-assembly-placement-mini-lab
Title: v0.8.2 - Assembly Placement Mini-lab
Date: 2026-06-30

Overview

本次发布是 V8A/V8B 的第三篇:Assembly 进阶 mini-lab。V8C 聚焦组件如何被精确放置、组织和检查

  • Placement / Location —— 显式位置表达
  • 全局 vs 局部坐标系 —— 坐标系区别
  • Nested Assembly —— 把相关组件组织成子装配
  • 教学型干涉检查 —— 结构化方法判断装配关系

V8A → V8B → V8C 是递进关系:V8A 多零件表达 → V8B 记录归档 → V8C 精确放置和检查。

What's New

新增文档页面

文件 说明
examples/cadquery-assembly-placement-mini-lab.rst Assembly Placement mini-lab 主页(A-K 结构)

页面结构(A-K 节)

  • A. 本页解决什么问题 — V8A → V8B → V8C 递进
  • B. Placement / Location 是什么 — 核心概念
  • C. 全局坐标系 vs 局部坐标系 — 5 类对比表
  • D. Nested Assembly / 子装配 — bolt_pair 子装配 + 教学型组织
  • E. 教学型代码示例 — PLACEMENT_TABLE + 子装配构造
  • F. 干涉检查与间隙检查的概念 — 教学型 ≠ 真实 OCCT 仿真
  • G. 装配关系检查表 — 7 类检查项
  • H. 与 V8A/V8B 的关系 — 递进路径
  • I. 常见误区 — 8 条 V8C 特有误区
  • J. 教学声明 — 教学性质
  • K. 相关页面 — 5 个相关链接

新增代码文件

文件 说明
code/cadquery/bracket_nested_assembly.py 嵌套装配体(bolt_pair 子装配 + PLACEMENT_TABLE)

代码特性

  • PLACEMENT_TABLE:教学型 dict 定义每个组件的 placement
  • build_bolt_pair_subassembly():构造 2 螺栓子装配
  • build_nested_assembly():构造主装配(base + vertical + bolt_pair + pin)
  • 嵌套结构清晰:子装配的 Location 是相对主装配,子装配内零件的 Location 是相对子装配
  • 教学声明:teaching example / not for industrial production / not a real interference solver

新增资源包文件

文件 说明
assets/bracket-capstone/assembly/placement-checklist.md Placement 检查清单(坐标系 + 组件位置 + 子装配 + 展示 vs 真实)
assets/bracket-capstone/assembly/interference-check-notes-template.md 干涉检查记录模板(6 类检查项 + 总结表 + 教学说明)

更新代码文档

文件 更新内容
code/cadquery/README.md 加入 V8C 文件说明(与 V8A 区别 / 学习目标 / 与 V8B 关系 / 资源包 / 环境不可用时)

新增 SVG 图示

文件 内容 尺寸
_static/diagrams/assembly-placement-coordinates.svg Assembly 坐标系与 Placement 关系图(全局 vs 局部 vs PLACEMENT_TABLE) 900×360
_static/diagrams/nested-assembly-structure.svg 嵌套装配体结构图(主装配 + 3 单独零件 + 1 子装配) 900×360

导航更新

文件 更新内容
examples/index.rst 新增"案例 S"(V8C)、推荐顺序 1→7、阅读顺序 21、toctree、对照表行
workflow-roadmap.rst 新增任务 1.14(V8C)、CAD 设计工具列表更新
README.md 版本号更新至 v0.8.2;新增"Assembly Placement mini-lab"亮点;能力矩阵新增 V8C 行;快速入口新增 V8C 链接;版本演进新增 V8C 条目;教学亮点速览新增 V8C 条目

Build & Verification

项目 结果
Build Command sphinx-build -b html -W --keep-going . _build/html
Build Result ✅ succeeded
Warning Count 0
py_compile (bracket_nested_assembly.py) ✅ OK
CadQuery import ⚠️ 不可用(环境限制,不阻塞)

Related Pages

Next Steps

候选方向:

  1. V8D — V8 系列收口页(V8A/V8B/V8C 三步走总览)
  2. V9 — 第二 Capstone(带圆角/倒角/多特征的复杂零件)
  3. V9 — V6 作品集模板升级(加入 V8A/V8B/V8C 装配体补充)
  4. V9 — 真实软件截图(SolidWorks / FreeCAD / Fusion 360)
  5. V9 — 用 CadQuery 重做 V4B mini-lab

Teaching Notes

本版本是 V8 系列的第三篇

  • V8A:能组织多零件
  • V8B:能记录和归档
  • V8C:能精确放置和检查

不替代商业 CAD 装配设计工具,不做真实工业约束求解和动画。


Released by OpenClaw Agent (longxia2) on 2026-06-30.

v0.8.1 - Assembly BOM & Checklist

Choose a tag to compare

Release Notes: v0.8.1 - Assembly BOM & Checklist

Tag: v0.8.1-assembly-bom-checklist
Title: v0.8.1 - Assembly BOM & Checklist
Date: 2026-06-30

Overview

本次发布是 V8A(CadQuery Assembly 入门)的进阶篇,聚焦装配体的工程表达:

  • BOM(Bill of Materials,零件清单)
  • 爆炸图(Exploded View,教学性拉开组件位置)
  • 装配检查清单(Assembly Checklist,结构化验证)

V8B 让读者理解"装配体 ≠ 几个 union 起来的实体",而是需要被检查、拆解、归档的工程对象。

What's New

新增文档页面

文件 说明
examples/cadquery-assembly-bom-checklist.rst Assembly BOM 与检查清单(A-J 结构)

页面结构(A-J 节)

  • A. 本页解决什么问题 — V8A 怎么组织多零件 → V8B 怎么被检查和归档
  • B. 从 Assembly 到 BOM — 6 维度对比表
  • C. 支架装配体 BOM 示例 — 4 组件 BOM 表格(编号/名称/数量/材料/作用/CadQuery 函数/检查要点)
  • D. 爆炸图如何帮助理解装配 — 教学型表达
  • E. 装配检查清单 — 8 类检查项
  • F. CadQuery 代码补充 — BOM_DATA 结构化数据示例
  • G. 装配体作品集归档 — 推荐归档清单
  • H. 常见误区 — 8 条 V8B 特有误区
  • I. 教学声明 — 教学性质
  • J. 相关页面 — 5 个相关链接

新增资源包文件

文件 说明
assets/bracket-capstone/assembly/assembly-bom-template.md BOM 模板(含项目信息/BOM 表格/字段说明/同步要求)
assets/bracket-capstone/assembly/assembly-checklist.md 装配体检查清单(含 8 大类检查项 + 常见问题 + 完成签名)
assets/bracket-capstone/assembly/assembly-notes-template.md 装配说明模板(含组件关系/修改记录/导出记录/自评/CAM 关系)

轻量增强现有代码

文件 更新内容
code/cadquery/bracket_assembly.py 轻量增加 BOM_DATA(list of dict)+ print_bom() + total_bom_quantity() + main 中打印 BOM

更新代码文档

文件 更新内容
code/cadquery/README.md 加入 V8B 文件说明(BOM_DATA 与 Assembly 代码同步 + 资源包目录 + 作品集关联指南)

新增 SVG 图示

文件 内容 尺寸
_static/diagrams/assembly-bom-relationship.svg Assembly 表达四件套(组件→BOM→检查清单→作品集归档) 900×280
_static/diagrams/bracket-exploded-view.svg 支架装配体教学爆炸图(4 组件 + 装配顺序编号 + 拆解箭头) 900×460

导航更新

文件 更新内容
examples/index.rst 新增"案例 R"(V8B)、推荐顺序 1→6、阅读顺序 20、toctree、对照表行
workflow-roadmap.rst 新增任务 1.13(V8B)、CAD 设计工具列表更新
README.md 版本号更新至 v0.8.1;新增"Assembly BOM 与检查清单"亮点;能力矩阵新增 V8B 行;快速入口新增 V8B 链接;版本演进新增 V8B 条目;教学亮点速览新增 V8B 条目

Build & Verification

项目 结果
Build Command sphinx-build -b html -W --keep-going . _build/html
Build Result ✅ succeeded
Warning Count 0
py_compile (bracket_assembly.py) ✅ OK(含新 BOM_DATA)
CadQuery import ⚠️ 不可用(环境限制,不阻塞)

Related Pages

Next Steps

候选方向:

  1. V8C — CadQuery 装配体进阶(约束、嵌套、动画演示)
  2. V9 — 第二 Capstone(带圆角/倒角/多特征的复杂零件)
  3. V9 — V6 作品集模板升级(加入 V8A/V8B 装配体补充)
  4. V9 — 真实软件截图(SolidWorks / FreeCAD / Fusion 360)
  5. V9 — 用 CadQuery 重做 V4B mini-lab(参数化立方体/圆柱体对比)

Teaching Notes

本版本是 V8 系列的第二篇

  • 不替代商业 CAD 装配设计工具
  • 螺栓 / 销钉 / 材料是教学示意值
  • 重点是让读者理解"装配体需要被检查和归档"
  • BOM、爆炸图、检查清单是工程表达的基本功

Released by OpenClaw Agent (longxia2) on 2026-06-30.