107 lines
4.8 KiB
Markdown
107 lines
4.8 KiB
Markdown
---
|
|
name: planetary-reducer-generator
|
|
description: Generate and validate planetary reducer and joint module data from this repository using the standardized input/output/placement/CAD/validation flow.
|
|
---
|
|
|
|
# Planetary Reducer Generator
|
|
|
|
## 何时使用
|
|
|
|
当用户要求在本项目中生成、验证、导出行星减速器、两级串联减速器、工业级减速器、关节模组或 URDF 时使用本 skill。
|
|
|
|
当前关节模组只支持同轴输入/输出接口的 `simple_2k_h` 和 `simple_2k_h_cascade`。`ferguson_wolfrom` 可以作为独立减速器和 reducer URDF 生成，但它的输入位于偏心行星销轴区域，暂不支持拼入当前同轴电机和外壳关节模组。
|
|
|
|
本 skill 是项目内流程规范，不是全局安装 skill。使用时以项目根目录为工作目录，项目根目录必须包含 `pyproject.toml`、`src/`、`input/`、`output/`。
|
|
|
|
## 硬规则
|
|
|
|
- 只能读取 `input/` 下的需求和资产；不要从旧输出目录反推设计。
|
|
- 所有生成结果只能写入 `output/runs/<run_name>/`。
|
|
- 不允许把已有 `output/runs` 文件当作本次通过依据；每次生成必须重新运行 CLI。
|
|
- 不允许伪造 STEP、`model.json`、`session.json`、`validation_report.json`。
|
|
- 不允许绕过 SimpleCADAPI、OCP/PythonOCC、图驱动运动学或验证器。
|
|
- SimpleCADAPI 或 OCP 缺失时必须真实失败并报告错误。
|
|
- 返回结果时必须给 Markdown 文件链接，不只给纯文本路径。
|
|
|
|
## 必读参考
|
|
|
|
- `references/reducer-generation-flow.md`：标准执行流程。
|
|
- `references/output-contract.md`：输出目录和关键文件契约。
|
|
- `references/validation-checklist.md`：验收检查清单。
|
|
- `references/configuration-development-standard.md`：新增或维护构型时必须遵守的开发规范。
|
|
- `references/topology-json-authoring-guide.md`：给机械工程师填写构型 JSON 的字段说明。
|
|
|
|
## 标准流程
|
|
|
|
1. 确认当前目录是项目根目录。
|
|
2. 选择 `input/` 下的 requirement 或外部资产。
|
|
3. 运行 CLI：普通减速器用 `run`，关节模组用 `joint-run`，自动设计关节模组用 `auto-joint-run`。
|
|
4. 读取对应 validation report。
|
|
5. 判断 `overall_passed`，并检查关键文件存在且非空。
|
|
6. 返回 STEP、公式实例、位姿计划、验证报告等 Markdown 文件链接和关键数值。
|
|
|
|
## 新增或维护构型
|
|
|
|
当用户要求新增复合行星、多级串联、差动行星、摆线针轮等构型时，先阅读 `references/configuration-development-standard.md`。新增构型必须通过 configuration registry、topology template、parameter solver、graph-driven kinematics、PlacementSolver、CAD generator 和 validators 的标准链路接入。
|
|
|
|
不要在 CLI、solver、CAD 或 validator 中临时写死构型逻辑。所有 CAD 组件位姿必须来自 `PlacementPlan`，所有验证必须读取真实生成结果。
|
|
|
|
如果用户只需要机械工程师创建新的 `topology.template.json`，优先把 `references/topology-json-authoring-guide.md` 交给他。该文档只解释 JSON 字段和填写规则，不要求机械工程师理解代码实现。
|
|
|
|
## 命令模板
|
|
|
|
Reducer:
|
|
|
|
```bash
|
|
PYTHONPATH=/Users/lk/Projects/cadSet/SimpleCADAPI/src:. \
|
|
/Users/lk/miniconda3/bin/python -m src.cli run \
|
|
--input input/requirements/reducers/simple_2k_h/simple_2kh_industrial_ratio_7p5_spur.json \
|
|
--output output/runs/industrial_ratio_7p5_spur
|
|
```
|
|
|
|
Joint module:
|
|
|
|
```bash
|
|
PYTHONPATH=/Users/lk/Projects/cadSet/SimpleCADAPI/src:. \
|
|
/Users/lk/miniconda3/bin/python -m src.cli joint-run \
|
|
--input input/requirements/joint_modules/3500_motor_housing.json \
|
|
--output output/runs/joint_3500_motor_housing
|
|
```
|
|
|
|
Auto joint module:
|
|
|
|
```bash
|
|
PYTHONPATH=/Users/lk/Projects/cadSet/SimpleCADAPI/src:. \
|
|
/Users/lk/miniconda3/bin/python -m src.cli auto-joint-run \
|
|
--motor-step input/assets/motors/3500_motor_part2.step \
|
|
--housing-python input/assets/housings/gear_housing.py \
|
|
--output output/runs/auto_joint_3500
|
|
```
|
|
|
|
URDF:
|
|
|
|
```bash
|
|
PYTHONPATH=/Users/lk/Projects/cadSet/SimpleCADAPI/src:. \
|
|
/Users/lk/miniconda3/bin/python -m src.cli export-urdf \
|
|
--joint-manifest output/runs/joint_3500_motor_housing/joint_module_manifest.json \
|
|
--reducer-instance output/runs/joint_3500_motor_housing/reducer/formula/formula_instance.json \
|
|
--output output/runs/joint_3500_motor_housing/exports/urdf
|
|
```
|
|
|
|
## 返回格式
|
|
|
|
成功时至少返回：
|
|
|
|
- `formula/formula_instance.json`
|
|
- `kinematics/kinematic_solution.json`
|
|
- `placement/placement_plan.json`
|
|
- `cad/reducer.step` 或 `joint_module.step`
|
|
- `validation/validation_report.json` 或 `joint_module_validation_report.json`
|
|
|
|
失败时返回：
|
|
|
|
- 失败阶段
|
|
- 错误文件链接，例如 `generation_error.json`、`joint_generation_error.json`、`urdf_export_error.json`
|
|
- validation 中失败的 check code、message、actual、expected
|
|
- 如果是几何干涉，返回 component pair、干涉体积、possible_cause、suggested_fix
|