---
applyTo: "MainShell/Motion/**/*.cs,**/*MotionController*.cs,**/*SafeAxisMotion*.cs,**/*AxisSpeedManager*.cs"
---

# Motion Control Instructions

## Motion Architecture
Motion control uses layered design:

- SafeAxisMotion as business entry
- MotionController as single-axis controller
- IAxis / IAxisFunc as platform abstraction

Keep this layering intact.

## 中文说明
运动控制采用固定分层：
- `SafeAxisMotion`：业务层入口
- `MotionController`：单轴控制器
- `IAxis / IAxisFunc`：平台抽象接口

不要破坏现有分层关系。

## MotionController Rules
- Constructor should receive `IAxis`
- Convert to `IAxisFunc` when motion command capability is needed
- Use `SemaphoreSlim` to serialize motion commands per axis
- Motion methods should support async/await and CancellationToken
- Perform status validation before motion:
  - servo/power status
  - alarm status
  - soft limit state
- Support timeout handling
- Raise motion lifecycle events such as MotionStarted / MotionFinished

## 中文说明
`MotionController` 设计规则：
- 构造函数接收 `IAxis`
- 需要运动控制能力时转换为 `IAxisFunc`
- 使用 `SemaphoreSlim` 保证单轴指令串行
- 运动方法支持 `async/await` 和 `CancellationToken`
- 运动前要检查伺服状态、报警状态、软限位状态
- 支持超时处理
- 可提供 `MotionStarted` / `MotionFinished` 事件

## Common Axis Properties
Prefer existing property patterns such as:
- AxisName
- CurrentPos
- IsBusy
- IsAlarm
- InPos

## 中文说明
常用属性保持与现有模式一致，例如：
- `AxisName`
- `CurrentPos`
- `IsBusy`
- `IsAlarm`
- `InPos`

## Motion Method Signatures
Keep compatibility with existing motion API patterns:
- MoveAbsAsync
- MoveRelAsync
- JogAsync
- StopAsync
- HomeAsync

## 中文说明
运动方法尽量保持现有签名风格兼容：
- `MoveAbsAsync`
- `MoveRelAsync`
- `JogAsync`
- `StopAsync`
- `HomeAsync`

## SafeAxisMotion Rules
- Prefer SafeAxisMotion for batch-safe movement
- Resolve axis name to IAxis and MotionController through existing repository mechanisms
- Preserve alarm integration and timeout behavior

## 中文说明
批量安全移动优先通过 `SafeAxisMotion` 实现：
- 通过现有机制把轴名解析为 `IAxis` 和 `MotionController`
- 保留报警集成和超时控制能力

## MotionResult Rules
- Use structured MotionResult
- Distinguish success, timeout, cancellation, and fault
- Use EnsureSuccess when caller expects exception-on-failure semantics

## 中文说明
`MotionResult` 应为结构化结果：
- 区分成功、超时、取消、异常
- 调用方需要"失败即抛异常"时，使用 `EnsureSuccess()`

## Speed Management
Use AxisSpeedManager for speed control where applicable.
Do not hardcode inconsistent speed logic if a unified speed manager already exists.

## 中文说明
速度管理优先通过 `AxisSpeedManager` 统一处理。  
如果已有统一速度管理器，不要在新代码里硬编码另一套速度逻辑。