| name | rust-ml-boundary |
| description | 将机器学习流程和算法逻辑严格限制在 Rust crates 内实现。当新增或修改异常检测、预测、特征提取、模型训练、推理行为,或补充算法评估指标(F1、Recall、MAE、RMSE、MASE)时使用。 |
Rust 机器学习职责边界
本技能用于强制执行架构边界:机器学习逻辑只允许存在于 Rust 中,而 Go 只负责插件集成和 FFI 传输编排。
顶层约束关系
本文件不是 Rust 顶层规范,而是 rust-core 的职责边界补充。
- 只要命中本技能,必须先遵守 /.claude/skills/rust-core/SKILL.md 里的全部通用 Rust 约束。
- 本文件只负责补充 算法流程归属、Go 与 Rust 的职责边界、前端不得承载算法逻辑 等专项约束。
- 如果本文件与
rust-core 出现表述重叠,以 rust-core 作为顶层基线,本文件只在机器学习流程归属场景中追加限制,不能放宽 rust-core 的要求。
何时使用
- 新增算法
- 修改训练、推理、评分、基线计算或特征工程
- 重构 pkg/plugin、pkg/rsod、rsod-ffi 和算法 crate 之间的代码边界
- 判断某段逻辑到底应该放在 Go 还是 Rust 中
必查文件
- pkg/plugin/datasource.go
- pkg/plugin/types.go
- pkg/rsod/rsod.go
- rsod/crates/rsod-ffi/src/lib.rs
- rsod/crates/rsod-*/src/
边界规则
- 所有机器学习算法流程都必须实现在 rsod/crates/ 下的 Rust crates 中。
- Go 是集成层,不是算法层。Go 可以解析查询、派生 ID、拆分时间范围、封送参数、调用 FFI、渲染结果,但不能实现模型逻辑。
- rsod-ffi 是传输层,不是算法层。它只负责在边界上转换 Arrow 和 JSON,然后立即委派给 Rust 算法 crate。
- 前端代码只能配置算法,不能重写算法。React 组件只负责参数与交互体验。
Go 允许做的事情
- 解析 datasource 查询 JSON
- 填充请求默认值并派生 UUID
- 拆分 current 和 history 时间窗口
- 将 Grafana frames 转换为 Arrow 兼容结构
- 调用粗粒度 FFI 函数
- 导入 Arrow 输出并渲染 Grafana 结果帧
Go 绝对不能做的事情
- 实现异常评分或预测数学逻辑
- 包含按算法定制的训练循环
- 执行会改变模型语义的特征工程
- 存放本应属于算法实现内部的模型特定判断分支
- 以方便调试或调用为由复制 Rust 算法代码
Rust 必须拥有的职责
- 领域算法主流程
- 会影响模型行为的特征提取与预处理语义
- 模型训练、推理、评分、置信区间生成和异常判定逻辑
- 超出传输层健全性检查之外的算法专属校验
变更工作流
- 先判断改动属于传输/集成问题,还是算法/领域逻辑问题。
- 如果改动影响模型语义,必须优先在 Rust crate 中实现。
- Go 侧变更应限制在新增参数、FFI 接线和结果渲染上。
- 如果边界契约发生变化,必须同步更新接口文档。
测试与评估规则
- Rust 中实现或修改的机器学习算法,必须使用仓库固定测试夹具进行评估;时序测试数据只能来自
dataset/testdata/。
- 禁止在单元测试或算法评估测试中内联长时序、临时生成独立 CSV,或改用仓库其他位置的散落数据副本。
outlier 类型算法在使用测试数据集评估时,必须至少报告适合异常检测任务的指标,默认包括 F1 和 Recall;如果补充 Precision、PR-AUC 或其他指标,只能作为附加信息,不能替代前两者。
outlier 类型算法的默认单元测试达标线为:F1 >= 0.80 且 Recall >= 0.85。如果某个公开 benchmark、论文复现实验或仓库既有稳定模型已经给出更高门槛,测试必须采用更严格的阈值。
forecast 类型算法在使用测试数据集评估时,必须同时报告 MAE、RMSE 和 MASE;不得只挑选其中单个指标来声明模型有效。
forecast 类型算法的默认单元测试达标线为:MASE < 1.0,且 MAE 与 RMSE 都必须优于对照基线至少 5%,即 MAE <= 0.95 * baseline_mae 且 RMSE <= 0.95 * baseline_rmse。
- 不允许为所有预测数据集统一设定跨量纲的固定绝对
MAE 或 RMSE 阈值;只有在测试夹具的量纲、取值范围和窗口完全固定,并且阈值来源在同一变更中写清楚时,才允许为该特定数据集补充更严格的绝对上限。
- 评估结论不能只写“效果更好”或“通过测试”;必须给出与任务类型匹配的指标值,并明确这些指标对应的数据集、窗口和评估口径。
- 任何声称达到可接受精度的算法改动,都必须提供可追溯的对照基线。该基线可以来自公开论文、公开 benchmark、业内常用标准,或仓库中已有稳定模型的历史结果,但来源必须在同一变更中写清楚。
- 新实现或修改后的算法,评估指标必须高于所引用的行业或公开基线;如果没有可核验的外部基线,必须先补充基线来源和阈值依据,再宣称算法达标。
- 如果数据集特性导致某个默认指标不适用,必须在代码或文档中明确说明原因,并补充同类型任务普遍接受的替代指标;不能直接跳过评估。
最低验证要求
- go test ./pkg/...
- cd rsod && cargo test
- 涉及算法实现、训练、推理或评估逻辑时,使用
dataset/testdata/ 下的固定数据执行针对性测试,并记录与任务类型匹配的评估指标:outlier 至少包含 F1 和 Recall,且默认断言 F1 >= 0.80、Recall >= 0.85
forecast 测试必须包含 MAE、RMSE 和 MASE,并默认断言 MASE < 1.0、MAE <= 0.95 * baseline_mae、RMSE <= 0.95 * baseline_rmse
- 如果宣称模型效果达标,必须同时记录所采用的公开/行业基线及“当前结果高于该基线”的依据
- 如果查询结构发生变化,重新检查 docs/interfaces/ts-go-interface.md 和 docs/interfaces/go-rust-interface.md
反模式
- 因为不想改 Rust,就把一小段机器学习逻辑塞进 Go
- 把 rsod-ffi 扩张成第二个算法层
- 前端默认值悄悄改变模型语义,却没有对应的 Rust 变更
- 用不匹配任务类型的指标评价算法,或只汇报有利于当前实现的单个指标
- 为不同量纲的预测数据集复用同一个固定
MAE / RMSE 绝对阈值
- 不引用外部或历史基线,就宣称模型结果达到行业水平