# Rust ICSP 原生规划核心设计 ## 1. 目标 在不改变现有上层业务接口的前提下，使用 Rust 重新实现当前 C# 版本的 ICSP 和 clamped-zero 三次样条算法，并通过稳定的 C ABI 供 .NET 8 调用。 第一阶段必须实现： - Rust `cdylib` 中的 clamped-zero 三次样条系数求解。 - 样条位置求值和每段一至三阶导数绝对值峰值解析计算。 - ICSP 初始分段时长、迭代缩放、最优结果保存和最终收敛判定。 - C# P/Invoke 适配层。 - Rust 与现有 C# 算法的自动对拍测试。 - Windows x64 和 Linux x64 原生库加载边界。 第一阶段不实现： - `SelfAdaptIcspPlanner` 的补中点逻辑。 - 轨迹稠密采样、J519 发送采样和触发绑定。 - 正运动学、MoveJoint 和 MovePose。 - FANUC 协议、Socket 和运行时状态机。 - 删除或替换现有 C# ICSP 实现。 ## 2. 总体架构 新增原生算法模块和 C# 适配模块： ```text ControllerClientTrajectoryOrchestrator | ICSP 规划接口 / \ C# ICspPlanner RustIcspPlanner | Flyshot.Native.Interop | C ABI | flyshot_planning Rust cdylib ``` 现有 `ICspPlanner` 保持不变，继续作为行为基准和回退实现。Rust 规划器返回的数据仍由 C# 组装成现有 `PlannedTrajectory`，因此领域层、兼容层和运行时不感知原生对象。 ## 3. Rust 模块边界 原生模块建议位于： ```text native/ flyshot-native-planning/ Cargo.toml src/ lib.rs error.rs ffi.rs icsp.rs spline.rs ``` 各文件职责： - `spline.rs`：三对角方程求解、样条系数、位置求值、解析导数峰值。 - `icsp.rs`：纯 Rust ICSP 输入、迭代规划和结果模型。 - `ffi.rs`：C ABI 数据结构、指针校验、结果分配与释放。 - `error.rs`：原生错误分类和 UTF-8 错误信息。 - `lib.rs`：只导出稳定 ABI，不导出内部算法符号。 Rust 内部算法不依赖 .NET 类型、JSON、日志框架、网络或文件系统。 ## 4. C ABI 设计 ABI 使用固定宽度整数、C 布局结构和连续 `double` 数组。路点输入采用行优先扁平布局： ```text [waypoint0_joint0, waypoint0_joint1, ..., waypoint1_joint0, waypoint1_joint1, ...] ``` 主要入口： ```c int32_t flyshot_icsp_plan( const double* waypoints, int32_t waypoint_count, int32_t dof, const double* velocity_limits, const double* acceleration_limits, const double* jerk_limits, const FlyshotIcspOptions* options, FlyshotIcspResult** result); void flyshot_icsp_result_free(FlyshotIcspResult* result); const char* flyshot_last_error_message(void); ``` `FlyshotIcspOptions` 包含： - `threshold` - `max_iterations` - `enforce_final_scale` - `final_scale_tolerance` `FlyshotIcspResult` 包含： - `waypoint_times` 及长度 - `segment_durations` 及长度 - `segment_scales` 及长度 - `iterations` - `threshold` 调用成功返回 `0`。输入非法、数值计算失败、未收敛和内部异常使用不同错误码。错误文本由线程局部存储保存，只保证在当前线程下一次原生调用前有效。 所有结果内存都由 Rust 分配，并且只能通过 `flyshot_icsp_result_free` 释放。C# 不直接释放 Rust 分配的数组。 所有可预期失败必须在 FFI 内转换为错误码，FFI 路径不得依赖 panic 表达业务错误。Debug 和测试构建使用 `catch_unwind` 检测遗漏的 panic；Release 使用 `panic=abort`，此时 `catch_unwind` 不能恢复 panic，因此实现必须通过边界校验避免索引越界、空指针解引用和显式 `unwrap`。任何构建模式都不得让 Rust unwind 穿过 C ABI。 ## 5. C# 适配层 新增一个只负责原生互操作的 C# 项目，建议命名为： ```text src/Flyshot.Native.Planning/ ``` 包含： - `NativeIcspMethods`：使用 `LibraryImport` 声明 C ABI。 - `NativeIcspSafeHandle`：封装 Rust 结果指针和释放函数。 - `RustIcspPlanner`：把 `TrajectoryRequest` 转换为连续数组，再把结果转换为 `PlannedTrajectory`。 - `NativePlanningLibraryResolver`：按当前操作系统和体系结构解析原生库。 - `NativePlanningException`：携带原生错误码和错误文本。 原生库逻辑名称固定为 `flyshot_planning`： - Windows：`flyshot_planning.dll` - Linux：`libflyshot_planning.so` C# 适配层负责： - 检查输入自由度和数组长度。 - 固定数组，避免调用期间被 GC 移动。 - 将 Rust 返回数据复制到托管数组。 - 无论成功或失败都正确释放结果句柄。 - 将原生错误转换为包含诊断信息的 C# 异常。 `RustIcspPlanner` 的构造参数和 `Plan` 行为应与 `ICspPlanner` 对齐，但第一阶段不自动替换现有依赖注入注册。 ## 6. 数值一致性 Rust 实现必须逐项复刻当前 C# 行为： - 初始段时长使用相邻路点的关节空间欧氏距离。 - 使用 clamped-zero 边界条件求三次样条。 - 每轮解析计算各段速度、加速度和 jerk 峰值。 - 分段倍率分别使用一次方、平方根和立方根。 - 收敛指标为 `sum(abs(scale - 1))`。 - 始终保存历史最小收敛指标对应的结果。 - 迭代范围与当前 C# 保持一致，即包含第 `max_iterations` 轮。 - 最终按 `global_scale > 1 + tolerance` 判定是否失败。 第一阶段采用以下对拍容差： - 路点时间：绝对误差不超过 `1e-9`。 - 段时长：绝对误差不超过 `1e-9`。 - 段缩放：绝对误差不超过 `1e-9`。 - 最终 threshold：绝对误差不超过 `1e-9`。 - 迭代次数：必须完全一致。 如果真实样本因浮点指令或编译器优化无法满足 `1e-9`，必须先定位首个分歧计算步骤，再基于证据调整容差，不直接放宽整个测试。 ## 7. 测试策略 遵循 TDD，先增加失败测试，再实现 Rust 和 C# 适配。 测试分四层： 1. Rust 单元测试 - 三次样条边界值。 - 一至三阶导数。 - 解析峰值。 - ICSP 收敛与不收敛。 - 非法指针之外的纯算法输入校验。 2. Rust FFI 测试 - 正常调用和结果释放。 - 空指针、错误维度、非有限数。 - 错误码与错误文本。 - 重复释放由 C# `SafeHandle` 防止，不把未定义行为包装成可接受用法。 3. C# 互操作测试 - 原生库加载。 - 托管数组到 C ABI 的转换。 - 结果复制和释放。 - 原生错误到 C# 异常的转换。 4. C#/Rust 对拍测试 - 仓库中的稳定规划样本。 - 当前 `PlanningCompatibilityTests` 使用的基础输入。 - 多自由度、多路点和极限参数。 - `maxIterations=0` 的未收敛路径。 - 至少一个父目录真实样本固化后的 golden case。 对拍测试必须同时调用现有 `ICspPlanner` 和 `RustIcspPlanner`，不能把预期值只写成 Rust 自身输出。 ## 8. 构建与发布 本地构建脚本负责： - 执行 `cargo build --release`。 - 根据目标平台复制原生库到 C# 测试和发布输出目录。 - Windows x64 构建 Rust `x86_64-pc-windows-msvc`。 - Linux x64 构建 Rust `x86_64-unknown-linux-gnu`。 第一阶段不要求在 Windows 主机上完成 Linux 交叉编译；Linux 原生库可以在 Linux 构建环境生成。仓库必须提供对应命令和 CI/离线构建说明。 发布时原生库与托管程序集放在同一部署目录。现有 Obfuscar 继续处理 `Flyshot.*.dll` 托管程序集，不处理 Rust 原生库。 Rust Release 配置启用： ```toml [profile.release] lto = true codegen-units = 1 strip = "symbols" panic = "abort" ``` ## 9. 回退与上线边界 第一阶段只提供显式的 Rust 规划器，不改变生产默认算法。完成全部对拍和跨平台验证后，再单独设计配置切换： ```text Planning:Backend = Managed | Rust ``` 原生库缺失、架构不匹配或加载失败时，显式选择 Rust 后应返回清晰错误，不静默回退。静默回退会掩盖部署缺陷，也无法确认现场实际使用的是哪套算法。 保留 C# 实现至少经过一个完整现场验证周期。后续是否删除托管算法，需要独立评审，不属于本设计范围。 ## 10. 验收标准 - Rust 单元测试全部通过。 - C# 原生互操作测试全部通过。 - 选定样本的 C#/Rust 对拍全部通过。 - `dotnet test` 和解决方案构建通过。 - Windows x64 实际加载 `.dll` 并完成规划。 - Linux x64 实际加载 `.so` 并完成规划。 - 缺少原生库时能得到明确且可诊断的错误。 - 现有 C# `ICspPlanner` 和上层运行链路行为不变。 ## 11. 第一阶段落地状态（2026-06-23） 当前已落地： - `native/flyshot-native-planning` Rust `cdylib`，包含 clamped-zero 样条、 一至三阶导数解析峰值、ICSP 迭代和稳定 C ABI。 - `src/Flyshot.Native.Planning` 托管互操作项目，包含显式平台解析、 `LibraryImport`、`SafeHandle`、错误码转换和结果复制。 - Rust 样条、ICSP、FFI 测试，以及 C#/Rust `1e-9` 自动对拍测试。 - `build/Copy-NativePlanningArtifacts.ps1`，用于初始化 Windows MSVC 环境、 构建原生库并复制到测试或发布目录。 - Windows x64 已实际生成并加载 `flyshot_planning.dll` 完成规划。 当前上线边界保持不变： - 默认生产路径继续使用 C# `ICspPlanner`。 - Rust 规划器只允许显式选择，库缺失、路径不一致或架构不支持时返回明确错误。 - Linux x64 的源码、库名和构建脚本边界已落地，但 `.so` 的实际加载验证必须在 Linux x64 构建环境执行后才能标记完成。