YI3D git:20260801.e58c576A

Immutable. This exact content never changes and is served at /api/v1/blob/e60f2dadc6d935e4.

---
name: YI3D
description: 生成 YI3D Python 建模脚本，通过 IpcClient.py 传入脚本全路径执行，并根据返回结果进行迭代重试直到成功或达到停止条件。
---

# Yi3D Python 建模

## 工作流程

1. 调用 `./scripts/IpcClient.py`，使用 `--method ping` 检查 IPC 连通性。
2. 若 `ping` 无响应、超时或连接失败，直接启动工作目录下的 `./YI3D`（Windows 上为 `./YI3D.exe`），启动后重新 `ping` 确认连通。
3. 调用 `./scripts/IpcClient.py --method command --argument "NewFile"` 新建文档。
4. 学习 `../../scripts/` 目录下的 Yi3D Python 脚本。
4. 生成建模脚本文件。
5. 调用 `./scripts/IpcClient.py`，传入脚本完整路径执行建模。
6. 读取执行结果。
7. 若执行成功但用户明确表示模型不满意且要求“重新创建”或“按反馈修改”，先调用 `./scripts/IpcClient.py` 并使用 `--method command --argument "Undo"` 回退上一次建模结果，再进入下一轮重建。
8. 若执行成功且用户满意，结束流程。
9. 若执行失败，修改脚本并继续重试，最多迭代 10 次。

## IPC 协议文档

- 在调用 `./scripts/IpcClient.py` 前，先阅读同目录下的 `./references/ipc_method_guide.md`。
- 与 IPC 交互时，必须遵循 `ipc_method_guide.md` 中定义的 method 语义、参数与返回判断规则。
- 调用 Python 时，默认先检查 `../../python3` 下的 Python（`python.exe` 或 `python`）；若不存在再回退系统 Python。

## 参考范围硬约束

- 示例学习范围限定为仓库内非 `scripts/agent/` 的 `.py` 源文件。
- 严禁参考 `scripts/agent/` 目录下的任何脚本；不得把该目录中的脚本作为 API 用法、建模策略、实现范例或纠错依据来源。
- 严禁参考任何 `__pycache__/` 目录、`.pyc` 文件、`.pyc.*` 文件，以及任何基于这些缓存文件反编译、还原或推导出的内容。

## 建模原则

- 先阅读 `../../scripts/` 下与目标最接近的示例脚本，再决定建模策略，不要直接凭空假设 API。
- Sketch 图元是 2D 坐标；其在 3D 中的位置与朝向由 `SketchPlane`（`normal` + `xDir`）决定。
- SketchPlane 必须先做右手系验算再建模：`yDir = normal × xDir`。禁止把草图 `v` 方向默认当成世界 `+Z`（或任意固定方向）。
- 创建每一个 SketchPlane 后，必须立即计算 `yDir = normal × xDir` 并做方向断言（例如校验 `v` 方向是否与预期世界方向一致）。若断言不通过，必须直接报错并停止本次建模，禁止继续执行后续特征创建。
- Yi3D 中 `SketchArc` 只能创建逆时针（CCW）圆弧，不能直接创建顺时针圆弧。
- 拉伸深度与 `normal` 同向约定：`depth > 0` 沿 `normal` 增厚，`depth < 0` 沿 `-normal` 增厚。
- 优先使用拉伸体 `Extrusion.create` 构造主体外形；只有当拉伸明显不适合时，才使用旋转、扫掠、螺旋等更复杂特征。
- 对可直接创建的基础形体（如 Box、Cylinder、Cone、Sphere、Torus、Tube），凡是能用”闭合草图 + Extrusion.create”等效构建的，默认优先使用拉伸体替代，不直接调用原语创建。
- 若必须直接创建基础形体或调用 `setPosition`/`setRotation` 定位，必须先查阅 `./references/primitive_coordinate_systems.md`，确认该形体的局部坐标系原点位置和旋转顺序（Z→X→Y），再做位置与朝向计算。
- 需要开孔、挖槽、去料时，优先先生成刀具体，再使用 `Difference.create` 做差集；仅在已有明确成功先例时才优先使用 `Extrusion.createCut`。
- 需要组合多个实体时，优先使用 `Union.create`，避免依赖不清楚的隐式合并行为。
- 草图必须严格校验为完全闭合轮廓。
- 对称、阵列、圆周分布类结构，必须同时处理位置和旋转，不能只旋转不重新定位。
- 参数应显式命名并集中放在脚本开头，至少包括关键尺寸、厚度、圆角、孔径、数量等，避免把魔法数字散落在建模逻辑里。
- 做布尔运算前，应检查主体与刀具体的相对位置、尺寸和重叠关系，避免生成不相交或过度相交的无效结果。
- 每次迭代只修改一个主要问题：例如先修正位置分布，再修正齿形或叶片造型，避免一次改太多导致难以定位失败原因。

## 输出要求

- 新脚本默认写入仓库内合适的 `scripts/agent/` 路径，文件名应能准确描述模型用途。
- 执行后必须读取 IPC 返回结果，并在回复中明确说明是否成功。

## 常见零件优先建模策略

- 手机壳：
  先用圆角矩形草图拉伸外壳主体，再用内轮廓拉伸或刀具体差集掏空；摄像头孔、按键孔、接口孔优先单独建刀具体后差集。不要一开始就用复杂曲面拟合外壳圆角。
- 直齿圆柱齿轮：
  优先使用样条拟合渐开线齿廓草图，再拉伸成实体；前 3 次重试必须严格使用样条渐开线（允许调整样条点、端点衔接和分段策略），不得提前退回直线段近似。仅当连续 3 次样条方案仍因草图闭合失败、拼接不稳或拉伸失败时，才允许退回到直线段近似渐开线齿廓。
  若改用离散点或直线段近似渐开线，必须额外核对齿顶圆弧角宽小于齿根圆弧角宽，避免把外齿轮廓误写成“圆盘开槽”轮廓。
  IPC 返回 `NoError` 后，仍应继续做几何语义校验：当前得到的是外齿实体，还是只有齿槽被切出来的圆盘；两者都可能脚本执行成功。
- 叶轮/涡轮：
  先做轮毂、轴、外环等基础回转体，再做叶片。叶片优先从单个叶片原型开始，确认位置和朝向后再做圆周阵列。没有必要时不要一开始做复杂扭曲扫掠叶片。
- 支架/连接件：
  优先用草图拉伸搭主体，再补加强筋、安装孔、倒角等细节。结构件优先保证孔位、板厚、安装面关系正确，再处理圆角和外观。
- 盖板/法兰：
  优先用二维轮廓拉伸，孔阵列和开槽优先用刀具体差集。圆周孔阵列必须先验证单孔位置正确，再复制到整圈。
- 旋转体零件：
  截面明确且轴对称时优先使用 `Revolution.create`，例如轴套、轮毂、垫圈、滚轮。若主要特征来自平面轮廓厚度变化，则仍优先考虑拉伸。

## 失败后的重试规则

- 布尔失败：
  先检查主体和刀具体是否真实相交；再检查刀具体是否完全穿透或切入深度不足；必要时先简化几何，再恢复复杂特征。优先先验证单个布尔，再扩大到多个刀具体。
- 阵列错位：
  先检查是否只旋转了姿态而没有同步更新位置；圆周阵列应同时按极坐标计算位置和旋转角。先把数量降到 `3` 或 `4` 个验证分布，再恢复目标数量。
- 草图不闭合：
  优先检查轮廓端点是否精确重合、圆弧起止角是否连续、样条与相邻边界是否接上。齿轮齿廓若优先使用样条，应先验证单齿闭环，再扩展到整圈；其他场景先做最小闭环验证再增加复杂段。对直齿圆柱齿轮，前 3 次重试必须严格使用样条渐开线；若第 3 次后仍失败，再退回直线段近似/拟合。
- 草图多次闭合失败：
  连续 3 次仍无法保证闭合时，必须放弃复杂曲线写法，改用直线段模拟复杂曲线后再建模。
- 拉伸失败：
  先确认草图是单一闭合轮廓或符合目标特征要求；若草图太复杂，先拆成多个简单拉伸再布尔组合。不要在草图未验证前叠加多个孔或自由曲线。
- 差集结果反了：
  先确认当前建的是“主体外轮廓”还是“齿槽/孔槽刀具体”。如果结果变成开槽圆盘或实体缺失，说明主体和刀具体角色可能写反了。
- 齿形或叶片方向反了：
  优先检查相位公式、镜像方向、起始角定义，不要第一反应就整体镜像模型。每次只改一侧齿廓或一个叶片原型，确认方向正确后再复制到整圈。
- 直齿轮执行成功但变成开槽圆盘：
  优先检查渐开线相位公式、半齿厚角与齿廓极角的对应关系，以及齿顶角宽是否确实小于齿根角宽；这通常不是布尔失败，而是单齿闭合轮廓把“齿”和“槽”定义反了。
- 结果看起来都堆在一侧：
  通常是局部原型旋转了，但基准点仍在同一个位置。应先修正原型局部坐标，再修正阵列位置公式。
- IPC 返回 `RunScriptError`：
  先检查脚本是否引用了已删除或未定义变量，再检查 API 参数数量和类型；最后再怀疑几何逻辑。优先修语法和变量问题，因为这类问题最容易造成假象。
- 结果虽然成功但形状不对：
  不要只看 `NoError` 就认为模型正确。应把“脚本执行成功”和“几何结果正确”分开判断，并在回复中明确说明当前验证层级。
  对直齿圆柱齿轮，至少补做一次齿顶/齿根角宽关系检查；若齿顶比齿根更宽，通常说明齿廓相位公式写反了。

## 脚本生成提示词模板

### 直齿圆柱齿轮

当用户要求生成直齿圆柱齿轮，优先按下列模板收敛需求和实现脚本：

```text
使用 YI3D 生成直齿圆柱齿轮。

参数：
- 模数 MODULE = 3.0
- 齿数 TOOTH_COUNT = 24
- 压力角 PRESSURE_ANGLE_DEG = 20.0
- 齿宽 THICKNESS = 24.0
- 中心孔直径 BORE_DIAMETER = 12.0
- 齿顶高系数 ADDENDUM_COEFF = 1.0
- 顶隙系数 CLEARANCE_COEFF = 0.25
- 侧隙 BACKLASH = 0.0

建模要求：
- 将关键参数集中放在脚本开头，避免魔法数字。
- 使用标准 20 度全齿高渐开线齿形，分度圆齿厚按 s = pi * MODULE / 2 - BACKLASH 计算。
- 左右渐开线齿廓优先使用 SketchSpline.createByFitPoints 创建样条。
- 齿顶圆和齿根圆优先使用 SketchArc.create 创建圆弧，不要用折线段代替，除非圆弧导致闭合或拉伸失败。
- 整圈外轮廓必须按每个齿同时计算位置和旋转角，不能只旋转局部齿形而不更新位置。
- 草图必须形成单一闭合外轮廓；生成后用 Extrusion.create 拉伸成实体。
- 中心孔不要直接依赖草图内环；优先单独创建圆形刀具体并使用 Difference.create 做差。
- 脚本默认写入 scripts/agent/create_spur_gear.py。
- 执行 skills/YI3D/scripts/IpcClient.py，传入脚本完整路径。
- 只有 IPC 返回 NoError 后才报告脚本执行成功。

几何校验：
- 校验齿顶圆弧角宽小于齿根圆弧角宽，避免把外齿轮廓误写成圆盘开槽轮廓。
- 校验中心孔直径小于齿根圆直径。
- 明确区分“脚本执行成功”和“齿轮语义正确”；NoError 后仍需说明已做哪些几何语义校验。

失败回退：
- 若样条齿廓导致草图闭合失败、拉伸失败或 IPC 返回 RunScriptError，先检查样条端点是否和相邻圆弧端点一致。
- 若圆弧方向导致闭合失败，先检查 start_angle/end_angle 是否沿外轮廓方向连续。
- 若连续失败，再将渐开线样条退回为直线段近似，但必须保留齿顶角宽小于齿根角宽的校验。
```

## 备注

- TODO: 增加失败分类与重试上限策略。
- TODO: 增加日志与输出规范。