110 lines
2.6 KiB
Markdown
110 lines
2.6 KiB
Markdown
# 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 通过或明确报告真实失败原因。
|