Split project into frontend and backend

This commit is contained in:
2026-08-13 16:24:36 +08:00
commit f051146486
274 changed files with 953932 additions and 0 deletions
+106
View File
@@ -0,0 +1,106 @@
---
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
@@ -0,0 +1,109 @@
# 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 通过或明确报告真实失败原因。
@@ -0,0 +1,91 @@
# Output Contract
## Reducer run
所有普通减速器生成结果必须写入:
```text
output/runs/<run_name>/
input_snapshot/
formula/
kinematics/
placement/
cad/
validation/
exports/
```
关键文件:
```text
formula/formula_instance.json
formula/parameter_search_report.json
formula/topology_graph.json
kinematics/kinematic_solution.json
kinematics/motion_samples.json
placement/placement_plan.json
cad/reducer.step
cad/reducer.model.json
cad/reducer.session.json
cad/assembly_manifest.json
cad/build_meta.json
validation/assembly_snapshot.json
validation/validation_report.json
```
工业级 reducer 还应包含:
```text
formula/industrial_parameters.json
formula/assembly_topology.json
cad/component_steps/*.step
cad/industrial_parameters.json
cad/assembly_topology.json
```
## Joint module run
关节模组生成结果必须写入:
```text
output/runs/<run_name>/
reducer/
external_step_metrics.json
joint_placement.json
joint_module.step
joint_module_manifest.json
joint_module_validation_report.json
joint_interference_report.json
```
`reducer/` 内部继续使用 reducer run 的标准结构:
```text
reducer/input_snapshot/
reducer/formula/
reducer/kinematics/
reducer/placement/
reducer/cad/
reducer/validation/
```
## URDF export
URDF 导出结果必须写入 `output/runs/<run_name>/exports/urdf/` 或其子目录。必须包含:
```text
*.urdf
package.xml
validation_report.json
export_manifest.json
meshes/
```
URDF 必须体现传动关系,不能只导出固定几何。当前项目用 `mimic` joint 表达太阳轮输入和行星架输出之间的传动比。
## 路径规则
- CLI 的 `--input` 必须在 `input/` 下。
- CLI 的 `--output` 必须在 `output/` 下。
- 不允许写入项目根目录、`src/`、`tests/`、`docs/` 作为生成结果。
- 不允许把生成物复制到旧目录或临时参考目录作为交付。
@@ -0,0 +1,110 @@
# Reducer Generation Flow
## 1. 确认项目根目录
工作目录必须是项目根目录,并且至少包含:
```text
pyproject.toml
src/
input/
output/
```
如果这些目录不存在,不要猜测路径,也不要在其他目录生成文件。先报告 `project_root_not_found`。
## 2. 选择输入
普通减速器 requirement 必须来自:
```text
input/requirements/reducers/
```
关节模组 requirement 必须来自:
```text
input/requirements/joint_modules/
```
自动关节设计使用的电机 STEP 和外壳 Python 必须来自:
```text
input/assets/
```
不要读取旧 `output/runs` 的结果作为本次设计依据。旧输出只能用于用户明确要求“查看历史结果”时读取,不能作为验证通过依据。
## 3. 执行 reducer run
优先使用一条 `run` 命令完成求解、CAD 生成、读回和验证:
```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
```
只有调试单阶段问题时才拆开执行 `solve`、`generate`、`validate`。
## 4. 执行 joint-run
关节模组使用:
```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
```
执行后必须读取:
```text
output/runs/<run>/joint_module_validation_report.json
output/runs/<run>/joint_module_manifest.json
```
## 5. 执行 auto-joint-run
自动关节设计使用:
```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
```
如果外壳包络不足、轴线识别失败或几何干涉失败,必须报告失败,不能调整报告为通过。
## 6. 判断结果
Reducer run 成功标准:
```text
validation/validation_report.json overall_passed == true
cad/reducer.step exists and non-empty
placement/placement_plan.json exists
```
Joint run 成功标准:
```text
joint_module_validation_report.json overall_passed == true
joint_module.step exists and non-empty
reducer/validation/validation_report.json exists
```
## 7. 返回给用户
必须返回 Markdown 文件链接,例如:
```markdown
[reducer.step](</absolute/path/output/runs/name/cad/reducer.step>)
[validation_report.json](</absolute/path/output/runs/name/validation/validation_report.json>)
```
不要只返回纯路径。
@@ -0,0 +1,113 @@
# Topology JSON Authoring Guide
这份说明给只负责创建构型 JSON 的机械工程师使用。构型 JSON 只描述机械构件和关系,不填写齿数、模数、目标速比、三维坐标或输出文件。
## 文件位置
```text
src/configurations/<family_name>/topology.template.json
```
`family_name` 必须和 JSON 顶层 `family` 一致。
## 顶层字段
```json
{
"template_id": "<family>_v0_1",
"family": "<family>",
"description": "one sentence",
"nodes": [],
"relations": []
}
```
## node 字段
每个 node 表示一个构件或参考对象:
```json
{
"id": "sun",
"kind": "gear",
"role": "sun",
"gear_type": "external",
"repeat": "single",
"formula_ref": "nodes.sun",
"stage_id": null,
"local_role": "sun"
}
```
填写规则:
- `kind`: `gear`、`carrier`、`housing`、`axis`
- `gear_type`: 外齿轮填 `external`,内齿圈填 `internal`,非齿轮填 `null`
- `repeat`: 单个构件填 `single`,按行星数量重复的行星轮填 `planet_count`
- `stage_id/local_role`: 多级构型用于表达级内角色;单级可以省略或填 `null`
不要在模板里手写 `planet_1..planet_n`。只写一个 `planet`,并设置 `repeat = planet_count`。
## relation 字段
每个 relation 表示构件之间的机械关系:
```json
{
"id": "sun_planet_external_mesh",
"source": "sun",
"target": "planet",
"relation_type": "external_mesh",
"carrier_ref": "carrier",
"mesh_id": "sun_planet",
"formula_ref": "relations.sun_planet_external_mesh",
"stage_id": null
}
```
允许的 `relation_type`:
```text
external_mesh
internal_mesh
revolute_joint
coaxial
fixed
rigid
```
常用关系:
- `sun --external_mesh--> planet`,`carrier_ref = carrier`
- `ring --internal_mesh--> planet`,`carrier_ref = carrier`
- `planet --revolute_joint--> carrier`
- `sun/ring/carrier --coaxial--> main_axis`
- `ring --fixed--> housing`
- `s1_output --rigid--> s2_input`
## 不要填写的内容
不要在 topology JSON 中填写:
- 目标速比
- 齿数
- 模数
- 行星数量候选
- 坐标和轴线
- STEP 路径
- 材料和颜色
- 验证结果
这些内容分别属于 requirement、参数求解、PlacementPlan、CAD 输出和 validation report。
## 提交前检查
- `template_id` 唯一。
- `family` 和目录名一致。
- 所有 relation 的 `source/target/carrier_ref` 都能在 nodes 中找到。
- 齿轮 `gear_type` 正确。
- 行星轮使用 `repeat = planet_count`。
- 行星啮合填写了 `carrier_ref`。
- 所有主运动构件都有 `coaxial` 到 `main_axis`。
- 固定关系用 `fixed`,刚性连接用 `rigid`。
- 没有使用未注册 relation type。
@@ -0,0 +1,70 @@
# Validation Checklist
## Reducer 验收
读取:
```text
output/runs/<run>/formula/formula_instance.json
output/runs/<run>/placement/placement_plan.json
output/runs/<run>/cad/assembly_manifest.json
output/runs/<run>/validation/validation_report.json
```
必须满足:
- `validation_report.overall_passed == true`
- `formula_instance.run_id == placement_plan.run_id`
- `formula_instance.run_id == assembly_manifest.run_id`
- `formula_instance.derived.ratio` 满足 requirement 的 `target_ratio ± ratio_tolerance`
- `cad/reducer.step` 存在且非空
- `cad/reducer.model.json` 存在且非空
- `cad/reducer.session.json` 存在且非空
- `placement/placement_plan.json` 存在
- `assembly_manifest.components[*].center_xyz_mm` 与 `placement_plan.component_poses[*].center_xyz_mm` 一致
## 必须关注的验证项
validation report 中以下类别不能失败:
- 静态公式验证:齿数正整数、齿数大于 17、齿数闭合、行星均布、中心距、外径、行星间隙。
- 运动学验证:速比、方向、fixed member 速度为 0、rigid 两端速度相等、残差。
- 拓扑关系验证:`external_mesh`、`internal_mesh`、`revolute_joint`、`fixed`、`rigid`、`coaxial`。
- 齿轮啮合验证:中心距、齿顶齿根间隙、backlash、齿相位、运动采样残差。
- 工业物理关系验证:轴承、销轴、螺栓、配合、间隙、联轴和刚性连接。
- OCP 几何检测:不得有未允许的正体积干涉。
## Joint module 验收
读取:
```text
output/runs/<run>/joint_module_manifest.json
output/runs/<run>/joint_module_validation_report.json
output/runs/<run>/joint_interference_report.json
output/runs/<run>/reducer/validation/validation_report.json
```
必须满足:
- `joint_module_validation_report.overall_passed == true`
- `joint_module.step` 存在且非空
- 电机 STEP、外壳 STEP、减速器 STEP 来源真实存在
- 电机轴线、外壳轴线、减速器主轴同轴检查通过
- 电机输出到太阳轮输入的关系存在
- 齿圈固定到外壳关系存在
- 行星架输出关系存在
- reducer 内部 validation report 通过
## 失败处理
如果验证失败,不能说生成成功。必须报告:
- 失败文件链接
- 失败 check code
- message
- actual
- expected
- 如果是干涉:component pair、common volume、possible cause、suggested fix
如果 SimpleCADAPI 或 OCP 缺失,报告环境错误。不要跳过后声称成功。