人类主导，与 Claude 协作构建。 Hardflow 由人类维护者设计和引导，Claude（Anthropic 的 AI）作为结对编程助手。每个功能都由人类指定、审查和测试 —— AI 按指示编写代码，它不决定项目是什么或走向何方。我们公开说明这一点，是因为我们宁愿透明地介绍工具的构建方式，也不愿让任何人猜测。

状态 —— 积极开发中。 到 v1.21 为止的路线图功能已全部实现 —— 布尔切割循环（切割/切片/添加/合并/相交/刀痕），支持方框/圆形/多边形/N边形/槽形/星形/弧形形状，世界级 + 顶点/边捕捉，非破坏性流程，完整贴花子系统，资产/套件拼装系统，网格辅助工具（边权重、显示切换、重新计算法线），直接建模工具，用于绘制/推拉/偏移/捕捉的 编辑模式（v1.3），绘制中操作（刀痕、内嵌、阵列、镜像、切割倒角、倒角切割器、平面内旋转、印章、实时网格深度、实时布尔预览 —— v1.4/v1.6/v1.13），管道/线缆/跟随路径轮廓扫掠 + 放样，v1.10 视口 Gizmo，v1.11 直接建模深度（Blender 折线修剪 对等、推拉复制/重复/推断、偏移凹陷/面板链、对象模式 边倒角 + 环切，以及通过生成修改器的 拾取），v1.13 构建/布尔扩展（圆柱/圆锥/球体/管道基本体，槽形/星形/弧形切割形状，跟随路径扫掠，实时布尔预览 + 切割器选项），v1.14 超级建模模式（HardFlow 模式影子外壳 —— 刀痕 + 挤出动词，带 SURFACE 平面 + Tab 动词循环，每个模态的命令模式撤销现在驱动直接建模工具的实时预览 + 全或无布尔切割链，以及智能倒角 + 布尔 N 边形清理），v1.15 打磨与性能 优化（对不规则的布尔后网格进行拓扑安全的智能倒角，带边框的”高级”HUD 带半透明视口引导线，以及通过新的纯 core/preview_cache 剔除不相关目标 + 门控空闲重新评估的高多边形实时布尔预览），v1.16 贴花片 UV 编辑器（将贴花片刻成自由、不等的命名 UV 矩形 —— 绘制/手柄调整大小/移动/断头台分割 —— 存储在图像数据块上；贴花可借用任何区域），v1.17 画线布尔切割 + 背景移除（HardFlow 模式获得 切割/添加/切片/相交 动词 —— 轮廓被挤出为切割器并在共享外壳上对活动网格进行布尔运算 —— 贴花片获得 色度键 工具，使所选颜色透明，用于从绿幕/纯色背景中提取图形），v1.18 高度图贴花（图像贴花可携带 专用灰度高度图，独立于颜色驱动深度 —— 同时馈送视差遮挡 UV 偏移和新的法线浮雕 凹凸，带反转极性切换），v1.19 智能倒角验证（最后一个实验性项目已关闭 —— 支撑/保持环放置根据实时 Catmull-Clark 细分进行测量，拖动时带有”预期圆角半径”（~r=…）HUD 读数；环固定平面，细分圆角在半径 ≈ 倒角宽度处保持清晰），v1.20 竞争优势（付费竞品的主要功能 —— 围绕网格原点旋转的 径向/螺栓圆阵列 绘制中阵列，将绘制矩形扩展为 N 个百叶窗槽的 通风口/格栅绘制形状，以及 面板线 将选定边扫掠成凹槽接缝或凸起焊缝），v1.21 曲线升级（管道/线缆/扫掠获得 自由手绘点击或笔触绘制 + C 平滑路径 Catmull-Rom 样条，可提交为可编辑贝塞尔曲线；线缆获得 G 重力沉降，带真实场景碰撞，使绳索垂落在障碍物上；轮廓循环获得来自网格轮廓或曲线放样对象的 自定义截面；沿路径的细节 沿活动曲线重复细节网格）。纯逻辑核心已进行单元测试（144/144，无需 Blender），bpy 路径增加了无头覆盖（142/142，针对独立 bpy 构建实时运行并在 Blender 5.1.2 中验证）；模态工具的交互感受通过 tests/manual_checklist.md 进行检查。完整路线图请参见 ROADMAP.md，逐版本历史请参见 CHANGELOG.md。

_{逐个分组添加和切割布尔细节，然后转盘展示 —— 每一帧都是真实的 Hardflow 输出。}

_{以下每张图片都是真实的 Hardflow 输出 —— 由插件自身的布尔、形状和曲线函数构建的几何体，在 Blender 的 Workbench 中渲染。}

画线布尔切割 — 一个槽、一个圆角和一个切口直接切割进面板。	形状库 — 方框 / 圆形 / N边形 / 槽形 / 星形 / 弧形轮廓。
快速细节 — 凸起舱室、通风槽、端口和螺栓孔。	管道与扫掠 — 沿表面贴合的轮廓。

• 通过模态绘制的布尔运算 — 方框 / 圆形 / 多边形 / N边形 / 槽形 / 星形 / 弧形 / 通风口（格栅）形状；切割、切片（一分为二）、添加、合并（作为独立实体添加）、相交（保留重叠部分）、面（创建表面）和刀痕（刻线）模式（Tab 循环模式）。切换 J 可在绘制时 实时布尔预览 真实结果。绘制中阵列（A / D）包括一个 径向（螺栓圆） 轴，将副本围绕网格原点旋转。
• 数值精度 — 绘制时输入精确尺寸以锁定形状大小（半径/范围/分段），实现精确绘制。
• 世界级网格捕捉 — 与摄像机无关的网格，以米为单位保持一致（”绝对尺寸”世界网格）；←/→ 在 VIEW / SURFACE / EDGES / X / Y / Z 之间切换平面，Shift+←/→ 旋转网格。
• 多对象 — 使用单个切割器对所选所有网格应用 CUT/MAKE。
• 管道、线缆与扫掠 — 从绘制线条生成圆形管道，在其点之间垂挂的线缆/绳索，或 扫掠/跟随路径 将 L / U / T / I / 方框结构截面沿绘制路径推送。三者都支持 自由手绘笔触（点击 或 绘制 —— 笔触贴合表面并精简为干净锚点），C 将路径平滑为 Catmull-Rom 样条（提交后成为可编辑贝塞尔曲线）。线缆的 G 重力沉降 以真实场景碰撞松弛绳索，使其垂落在障碍物上；Shift+滚轮提供松弛量。P 轮廓循环包括来自平面网格轮廓或曲线放样对象的 自定义截面，沿路径的细节 沿活动曲线重复选定的细节网格（链节、线缆夹、波纹管）。
• 顶点/边捕捉 — 将绘制点锁定到现有几何体的角点/边/边中点；彩色光标反馈。
• 角度锁定 — 按住 Shift 将绘制方向锁定到 15°（可调）步长。
• 非破坏模式 — 不应用布尔运算，而是保留实时修改器；将切割器保存在单独集合中（非破坏性）。
• 从选区布尔 — 使用活动对象作为切割器对选中的网格进行布尔运算（差集/并集/交集/切片），无需绘制；尊重非破坏性流程。
• 构建基本体 — 在 3D 光标处放置立方体/平面/圆柱/圆锥/球体/管道，用于直接建模工具。
• 推/拉 — 投射面，然后沿法线拖动以向内或向外挤出，带世界网格捕捉、数值输入和 顶点/边推断；C 保留起始面（复制/堆叠），R 重复上次距离；点击或回车应用。
• 偏移 — 投射面并拖动以按测量距离向内插入其边界（网格捕捉、数值输入）；E 继续 挤出内部面 以实现即时凹陷或凸起面板；R 重复。
• 面板线 — 在编辑模式中选择边，一键将其扫掠成 凹槽 接缝或凸起 焊缝；开放条带、闭合环和 T/X 交叉点都能干净处理，可破坏性或作为实时切割器存储。
• 边工具（对象模式） — 边倒角（选择边或其整个环，拖动宽度，[ ] 分段；S 切换 智能倒角 —— 支撑/保持环 + N边形清理，使倒角在细分下保持完好，-/= 紧密度）和 环切（选择边，插入边环） —— 无需进入编辑模式即可进行边操作。所有直接建模工具还可通过 生成修改器（细分等）进行 拾取。
• HardFlow 模式（Ctrl+Shift+X）— 一种流线型”影子”绘制模式，拥有自己的模态循环（从不调用 Blender 原生工具）：在幽灵网格上绘制带捕捉的折线，然后 刀痕 到网格上或 挤出 为新实体，Tab 在会话中切换动词。←/→ 循环构建平面（VIEW / SURFACE / X / Y / Z），退格键回退一个点，整个会话作为一个 原子撤销步骤（每个模态的命令模式日志）提交；Esc 回滚整个会话。
• 构建网格 — 在 3D 光标处放下 XY / XZ / YZ 平面上的线框参考网格以进行建模（构建平面）；间距与捕捉工具的世界网格相同。
• 资产/套件拼装 — 从 .blend 库中将现成部件（”INSERT”）放置到表面上：滚轮缩放，[ ] 滚动，点击放置。部件可以是纯装饰、布尔切割器、贴合表面（收缩包裹），和/或赋予表面的材质/着色。以网格形式浏览套件文件夹，并将对象标记为 Blender 资产供资产浏览器使用。
• 实时放置预览 — 贴花和资产工具在点击前显示光标下的 真实 对象（不仅仅是线框轮廓），因此您能精确看到将获得什么；Esc 放弃。
• 贴花 — 将信息/面板/子集贴花粘贴到任何表面上；它们通过收缩包裹贴合并跟随目标（表面贴合细节）。滚轮缩放，[ ] 滚动，点击放置；从 N 面板”贴花”部分管理。每种类型驱动共享的 PBR 着色器（基础/金属/粗糙度/AO/法线/自发光/Alpha + 视差深度），细节可 烘焙 到目标的纹理中。
• 高度图贴花 — 图像贴花可携带 专用灰度高度图（或使用彩色图像自身的亮度），独立于反照率驱动深度：同时馈送 视差遮挡 UV 偏移（凹陷面板线在掠射角滑到唇后）和用于真实着色深度的 浮雕（凹凸） 法线扰动，带 反转高度 极性切换。可从 N 面板”深度（图像贴花）”部分访问。
• 贴花图像库 — 指向包含 PNG/JPG/TGA 图像的文件夹，从图标网格中放置其中任何一张作为贴花；图像按宽高比调整大小。
• 贴花片 — 将一张贴花片刻成网格并放置单个单元格（放置时用上下键循环单元格）。
• 贴花转移 — 将已放置的贴花移到不同的表面对象上；在保持世界姿态的同时重新定位其收缩包裹和父级。
• 图集化 — 将每个图像贴花的纹理打包到单个图集图像中，并合并到一个共享材质上（更少的材质/绘制调用）。
• 饼菜单、偏好面板、可自定义的捕捉设置。

到 v1.21 为止的每个路线图功能，按其为 Blender 免费带来的付费工具工作流分组。右列指向实现模块。

超级建模模式（v1.14+） — 三个新层面的 SketchUp 流畅度/专业管线演进：影子引擎（HardFlow 模式动词，现在带有 SURFACE 平面 + Tab 动词循环 + 键位映射/饼图入口），每个模态的原子宏（命令模式撤销，现在驱动直接建模工具和布尔切割链），以及 智能拓扑（智能倒角 + 布尔 N 边形清理）。参见矩阵末尾的 超级建模模式 小节。

布尔与绘制

绘制中操作（v1.4）

非破坏性工作流

网格工具（v1.0 / v1.5）

v1.13 移除了倒角/镜像/阵列/径向/对称/锐化/分割/清理修改器操作以及步进/锥度/滚花细节。对象模式 边倒角 和 环切（直接建模部分）覆盖了无需编辑模式的边操作；Blender 自身的倒角/镜像/阵列/对称修改器覆盖其余部分。剩余的网格管理辅助工具：

贴花（v0.7–v0.9 / v1.7）

资产/套件拼装（v1.0 / v1.8）

直接建模与曲线（v1.2 / v1.3 / v1.6 / v1.11 / v1.21）

编辑模式（v1.3）

工具智能（v1.9）

UX 与共享

超级建模模式

SketchUp 流畅度 / 专业硬表面管线的三个基础层面演进，全部落地（语法 + 纯逻辑 + 无头验证 —— 无头套件针对独立 bpy 构建实时运行；模态 GUI 在手动检查清单中）。智能倒角的支撑环放置已通过实时 Catmull-Clark 细分 验证（Blender 5.1.2，无头）—— 保持环将倒角附近的平面锁定，细分圆角在半径 ≈ 倒角宽度处保持清晰 —— 参见 docs/hardflow_mode_plan.md。

Blender 4.2+：编辑 > 偏好设置 > 获取扩展 > （右上角 ⌄） > 从磁盘安装 → 选择 hardflow zip 文件。

在对象模式下选择网格：

• Alt+Q → 饼菜单（所有工具）
• Ctrl+Shift+D → 直接绘制工具
• Ctrl+Shift+X → HardFlow 模式（刀痕动词；Tab 循环挤出 → 切割 → 添加 → 切片 → 相交）

绘制模式中：

模式： 切割 = 布尔差集 · 切片 = 将对象一分为二 · 添加 = 添加几何体（并集）· 合并 = 将绘制的形状作为独立实体添加（非布尔）· 相交 = 仅保留重叠部分 · 面 = 从绘制的形状创建表面（非布尔）· 刀痕 = 在不挤出的情况下刻划表面（零深度切割）。

其他工具： 构建基本体（立方体/平面/圆柱/圆锥/球体/管道）· 布尔（选区） · 边权重 · 显示切换 · 随机颜色/复制材质 · 重新计算法线 · 推/拉 · 偏移 · 边倒角 · 环切 · 面板线（从所选边生成凹槽/焊缝）· 构建网格 · 放样 · 管道（圆形/方形/矩形/自定义）/ 线缆（G 重力沉降）/ 扫掠（L/U/T/I/方框/自定义截面）—— 三者都支持自由手绘笔触，C 平滑路径 · 沿路径的细节 · 应用切割器 · 修改器堆栈管理器 —— 全部在 N 面板中。推/拉、偏移、绘制工具和捕捉也适用于 编辑模式（v1.3）。

v1.13 移除了倒角/镜像/阵列/径向/对称/锐化/分割/清理修改器工具以及步进/锥度/滚花细节；改用对象模式边倒角/环切和 Blender 自身的修改器。

HardFlow 模式： Ctrl+Shift+X、饼图 ▸ 编辑 ▸ HardFlow 模式，或标题菜单 ▸ 编辑 ▸ “HardFlow 模式：刀痕” / “…：挤出” / “…：切割”（或 F3）。点击放置带捕捉的点；←/→ 循环构建平面（VIEW / SURFACE — 锁定到第一次点击下的面 / X / Y / Z），Tab 在会话中循环活动动词（刀痕 → 挤出 → 切割 → 添加 → 切片 → 相交）而不退出会话，退格键回退，Z / 回车 / 双击提交，Esc 取消。在挤出中，PgUp / PgDn 设置深度。整个会话是一个撤销步骤。

智能倒角与拓扑（超级建模模式）： 在 边倒角 中按 S 添加支撑/保持环，使倒角在细分下保持完好（- / = 调整环对倒角的紧密度；HUD 的 ~r=… 显示倒角收敛到的圆角半径）。放置已通过实时 Catmull-Clark 细分验证 —— 环将倒角附近的平面锁定，细分圆角在半径 ≈ 倒角宽度处保持清晰。启用 N 面板 ▸ 切割器选项 ▸ 拓扑 ▸ 重新四边化切割 N 边形 以自动清理布尔切割/应用切割器留下的 N 边形，智能边倒角 以智能模式启动边倒角。（两者默认关闭。）

资产： N 面板”资产”→”来自 .blend 的资产”（或”资产库”网格）启动放置工具：滚轮 = 缩放，[ ] = 滚动，左键点击 = 放置，Esc = 取消。在此切换”资产作为切割器”、”贴合”和”传递着色”。

贴花： N 面板”贴花”→ 信息 / 面板 / 子集。在放置工具中：滚轮 = 缩放，[ ] = 滚动，左键点击 = 放置，Esc = 取消。

捕捉光标颜色： 🟡 角点 · 🟢 边中点 · 🔵 边上。

hardflow/
├── blender_manifest.toml   # 扩展标识（4.2+）
├── __init__.py             # 注册编排 + 键位映射
├── preferences.py          # 设置 + get_prefs() 访问器
├── core/                   # 纯逻辑（独立于 UI，可测试）
│   ├── raycast.py          # 屏幕 <-> 3D 投影，平面 (u,v)，表面射线
│   ├── grid.py             # 世界级 + 角度捕捉，形状 + 网格点，rotate_2d
│   ├── snap.py             # 顶点/边几何捕捉（纯 2D）
│   ├── snapping.py         # 每个绘制工具的统一 3D 捕捉（bpy 数据）
│   ├── offset.py           # 多边形内嵌/偏移数学，偏移工具（纯 2D）
│   ├── bevel.py            # 智能倒角支撑环放置数学（纯）
│   ├── geometry.py         # bmesh 构建（基本体/棱柱/管道/放样）+ 智能倒角 + N边形清理 + 编辑模式桥接
│   ├── boolean.py          # 破坏性 + 非破坏性布尔 + 回退
│   ├── command.py          # 纯命令模式日志（每个模态原子撤销）
│   ├── transform.py        # 线缆下垂 / 适配 / 自适应尺寸数学（纯）
│   ├── path.py             # 自由手绘笔触 / 样条数学 — RDP，Catmull-Rom（纯）
│   ├── physics.py          # 线缆重力沉降松弛 + 碰撞（纯）
│   ├── decal*.py / atlas.py# 贴花方向，图像库，贴花片/图集数学
│   ├── asset_lib.py        # .blend 套件库扫描（纯）
│   └── asset.py            # 追加 / 定向 / 绑定 INSERT + 资产扩展
├── operators/              # 用户操作
│   ├── draw_cut.py         # 主模态绘制（方框/圆形/多边形/N边形/槽形/星形/弧形；实时布尔）
│   ├── hardflow_mode.py    # HardFlow 模式外壳（影子引擎）— 刀痕 + 挤出动词
│   ├── base.py             # 操作层命令模式（MeshSnapshotCommand / BooleanCutCommand）
│   ├── hardops.py          # 边权重 / 显示 / 材质 / 重新计算法线辅助
│   ├── boolean_ops.py      # 从选定对象布尔
│   ├── cutters.py          # 非破坏性切割器管理（应用/选择/移除）
│   ├── pipe.py             # 管道/线缆/扫掠 — 自由手绘笔触，平滑路径，重力沉降，自定义轮廓，沿路径的细节
│   ├── face_tool.py        # 面拖动工具的共享模态基类（_FaceDragModal，命令支持的预览）
│   ├── push_pull.py        # 推/拉 — 复制/重复/推断（对象 + 编辑）
│   ├── offset.py           # 偏移 — 重复 + 凹陷/面板链（对象 + 编辑）
│   ├── edge_tool.py        # 对象模式边倒角 + 环切（共享 _EdgePickModal）
│   ├── construction.py     # 线框构建网格 + 放样/桥接
│   ├── decals.py           # 贴花放置 + 库 + 贴花片 + 图集 + 烘焙 + v1.7
│   └── assets.py           # INSERT 放置 + 库 + 标记 + 材质 + 导出
├── ui/                     # GPU 绘制，HUD，菜单
│   ├── draw.py             # gpu + blf 辅助
│   ├── pie.py              # 分类饼图（主 + 布尔/构建/编辑/曲线）
│   ├── menu.py             # 涵盖每个工具的 3D 视图标题下拉
│   ├── panel.py            # N 面板：工具，设置，切割器选项，修改器堆栈，切割器
│   ├── decal_panel.py / decal_library.py   # 贴花部分
│   └── asset_panel.py      # 资产 + 资产库部分
└── tests/                  # 测试
    ├── test_core.py        # 纯核心，无需 Blender（python tests/test_core.py）
    ├── test_blender.py     # 无头（blender --background --python ...）
    └── manual_checklist.md # 模态工具的点击检查清单

core/grid.py 和 core/snap.py 刻意保持不含 bpy，因此数学层可用纯 CPython 测试（python tests/test_core.py）。

分层规则：ui 和 operators → 可依赖 core；core 绝不 依赖 ui。新功能通常意味着向 core 添加纯函数，加上调用它的薄操作层。

Hardflow 是免费的，并将永远保持免费 —— GPLv3，无许可费，无付费层级。如果它为您替代了付费插件，并且您希望开发继续推进（新工具、Blender 版本维护、bug 修复），您可以通过 Patreon 支持：

给仓库点星和分享您的构建也有帮助。

非常欢迎贡献 —— 架构的设计使功能保持隔离且易于添加。从 CONTRIBUTING.md 开始了解设置、测试和分层规则，并请在报告 bug 时附上 系统控制台 输出（窗口 → 切换系统控制台）。

• 🐛 提交 Issue（bug 或功能请求）
• 💬 讨论 用于提问和分享构建
• 🔒 安全问题：参见 SECURITY.md（请私下报告）
• 🤝 参与即表示您同意 行为准则
• 🗺️ 想接手某项工作？ROADMAP.md 追踪已完成和下一步计划。

GPLv3。每个随 bpy 分发的 Blender 插件实际上都是 GPL，本项目也不例外。完整许可文本请参见 LICENSE 文件。