Split project into frontend and backend
This commit is contained in:
@@ -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 缺失，报告环境错误。不要跳过后声称成功。
|
||||
Reference in New Issue
Block a user