# Agent 构型开发规范

当用户要求新增或维护减速器构型时，必须遵守本文档。不要直接在 solver、CAD、validator 中临时硬编码新构型。

## 必须新增或检查的内容

每个构型族必须具备：

```text
src/configurations/<family_name>/
  family.py
  topology.template.json
  placement_rules.py
input/requirements/reducers/<family_name>/
src/placement/<family_name>.py
```

并且必须注册：

- `src/configurations/registry.py`
- `src/placement/registry.py`

## 开发顺序

按以下顺序做，不要跳步：

```text
requirement
-> topology.template.json
-> configuration registry
-> topology runtime check
-> parameter solving rule
-> graph-driven kinematics
-> placement solver
-> CAD generator support
-> validators
-> tests
-> examples
```

## Topology 要求

节点必须写清楚：

```text
id / kind / role / gear_type / repeat / formula_ref / stage_id / local_role
```

关系必须写清楚：

```text
id / source / target / relation_type / carrier_ref / mesh_id / formula_ref / stage_id
```

只允许使用已经注册的 relation type：

```text
external_mesh
internal_mesh
revolute_joint
fixed
rigid
coaxial
```

如果需要新 relation type，先扩展 relation validator 和运动学方程生成，不能只改模板。

## Placement 要求

所有 CAD 组件的位姿必须来自 `PlacementPlan`。每个组件必须有：

```text
component_id
frame_id
translation_mm
rotation_axis_angle_deg
axis_xyz
center_xyz_mm
source_formula_refs
```

CAD generator 不能重新计算 planet、pin、bearing、spacer、bolt 坐标。manifest 与 placement plan 不一致必须验证失败。

## 参数和运动学要求

- 参数求解必须枚举候选并过滤，不能写死答案。
- family 专属公式放在 `family.py` 或 family rules。
- 最终 ratio 必须由图驱动运动学求解得到。
- fixed/rigid/input/output 边界必须从 requirement 或 topology 得到。

## CAD 和验证要求

- 生成失败必须真实失败，不允许输出假 STEP。
- `simplecadapi` 不可用时不得跳过后声称成功。
- OCP/PythonOCC 是实体干涉最终裁判。
- `validation_report.overall_passed` 只能由所有 check 结果汇总得到。
- 失败时必须返回失败 check code、actual、expected；几何干涉必须返回 component pair 和 possible cause。

## 最小测试

每个新构型至少补：

- registry 能加载构型。
- topology 能展开。
- parameter solver 能找到目标 ratio。
- kinematics ratio、direction、fixed speed 正确。
- placement plan 覆盖所有 manifest component。
- CAD 能真实生成 STEP/model/session。
- validation report 通过或明确报告真实失败原因。