用途:该技能面向在 SolidCraft 中新增或修改命令(即任何用户可见行为)的开发者,也适用于判断某段 crate 代码应归属何处。资料指出,工具栏、对话框、草图工具、命令面板、脚本、CLI、控制通道与 MCP 最终都通过 Session::execute(id, params) 调用同一套命令。
主要能力与规范:
- 命令定义:在 crates/engine/src/cmd/ 下的合适文件中添加 CommandSpec,并实现 run(fn(&mut Session, &Value) -> Result<Value>)。字段包括 id、label、工具栏标签页与面板(.at)、图标(.icon)、快捷键(.key)、参数文档(.params)、enabled(其错误字符串作为禁用按钮的提示)。
- id 命名:使用自有命名,点分、小写形式 <area>.<thing>[.<variant>],例如 solid.extrude 或 sketch.rectangle.two_point,不得使用其他产品的 id。
- 输入校验:先校验单位、范围、引用等输入,返回 BadParams,而不是构建出损坏的特征。资料强调参数是不可信的,并指向 skills/solidcraft-crash-safety/SKILL.md。
- schema:为命令提供输入输出 schema(crates/engine/src/schema/ 中的 contract 与 reply 类型,使用 checked!、.contract 和 .output 注册)。缺少 schema 时测试会警告,未来将变为强制;schema/unconverted.txt 只减不增,详见 docs/book/src/dev/schemas.md。
- 测试:引擎测试衡量结果,包括体积、面积、面/边/顶点数量,并与可手工推导的值比对;测试指南见 skills/solidcraft-tests/SKILL.md。
- 本地化:在待定语言文件中添加 cmd.<command id> 标签(cargo xtask i18n --add-missing 列出缺失项),缺少则测试失败,详见 skills/solidcraft-ui-text/SKILL.md。
- 帮助:功能区展示的命令还需 help.<command id>(先说明功能,再说明何时使用)并登记到 crates/ui-egui/src/command_help.rs 的 DOCUMENTED 中,缺少则测试失败。
- 生成文档:运行 cargo xtask features 查看 docs/features.md 的变化,但不要提交,主分支会在每次合并后重新生成。
- 若命令在设计文件中保存新内容,需添加格式文件,见 skills/solidcraft-file-formats/SKILL.md;若需要对话框或面板,见 skills/solidcraft-ui/SKILL.md。
使用方式与行为约束:程序化调用从不打开对话框;engine.execute 运行 JSON 形式。只有工具栏点击(ui.start)才会启动交互式工具与对话框,由它们再运行命令。对话框是前端表单,用于构建参数。修改设计的命令默认可撤销(会话先对文档做快照),失败的命令不会改变文档。
分层架构:cargo xtask layers 会在低层依赖高层时使构建失败。层级为 L0 geom -> L1 sketch、kernel、render -> L2 doc -> L3 io -> L4 engine -> L5 ui-egui -> apps。L5 以下不依赖 egui、eframe、winit、wgpu 或 rfd,UI crate 可替换;只有 crates/kernel 可以使用 truck。UI 层保持轻薄:面板读取引擎状态,并通过 app.run(id, params) 或 app.start(id) 执行操作。新模块的 mod 行应放入已有的排序分组,而不是在末尾新建分组(cargo fmt 会保持每组有序)。
适用场景:为 SolidCraft 添加或变更命令、定义命令 schema、补充命令测试与本地化/帮助文本、评审代码归属与分层是否合规。
限制与说明:资料未提供该技能的安装命令、运行环境要求、收费或价格信息,暂未提供。路线图由 ROADMAP.md 跟踪,里程碑任务完成时应更新。