---
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