用途：帮助 Sails 构建者维护类型化流水线，覆盖 IDL 生成、Rust 客户端生成与集成接线。当已发布合约演进或引入新部署版本时，应让生成客户端路径与既定切换计划兼容，而非假设一次重新生成即可替换所有消费者。
默认 JS/TS 路径：以程序 .idl 为接口唯一来源；用 sails-js 或 sails-js-cli 生成常规客户端，获得 lib.ts 与类型化 program/service 类，避免手写 payload 代码；配合 @gear-js/api 的 GearApi 连接节点；仅在需要动态运行时控制时使用 sails-js 与 sails-js-parser 路径的 parseIdl。
构建脚本路径：先检查仓库 build.rs，再考虑手动 IDL 步骤。专用 Rust 客户端 crate 优先使用标准 Sails 构建辅助路径：在 [build-dependencies] 中声明 sails-rs = { version = "...", features = ["build"] }，并在 main 中调用 sails_rs::build_client::<Program>();。直接使用 sails-idl-gen 加 sails-client-gen 仅作为非标准布局或自定义生成需求的手动回退。生成产物位置不固定，可能在 OUT_DIR、客户端 crate 输出路径或仓库自定义位置。
生成客户端陷阱：面向 IDL 的公开 map 键应优先使用原始类型或元组（如 u64、(u32, u32)、ActorId）；自定义结构体键（如 BTreeMap<Pos, V>）可能因生成类型缺少有序键 trait 而在客户端解码失败，除非已确认支持。
已发布合约演进：每个 .idl 视为一个已部署程序版本的接口契约；新版本改变公开接口时，不要假设所有消费者能同时切换；切换期间应保留新旧生成客户端，供前端、测试、脚本或迁移工具使用；重新生成是发布工作的一部分，但重新生成本身不等于兼容性验证。
前端 IDL 交接：当 Sails 程序 IDL 被独立工作区或仓库的前端消费时，应在前端项目检入 IDL 快照以便独立构建，并记录刷新命令：从 Rust 工作区重新生成 IDL 后复制到前端快照位置并重新生成 TypeScript 客户端。若 IDL 仅在 Rust 构建时生成于 OUT_DIR，前端构建时将不可用。
适用场景：build.rs 或生成接线不再产出预期产物；客户端 crate 与程序变更脱节；测试构建原始 payload 而非使用生成客户端；本地冒烟需要类型化客户端路径。
限制与护栏：调试前先确保生成产物与程序契约一致；工作区支持时测试与冒烟优先使用生成客户端流程；sails-js 不是运行时目标，而是生成与动态 IDL 流程使用的 JavaScript 客户端库；标准 Vara Sails 应用不应以原始 ABI、ethers 风格绑定或手写 SCALE payload 替代标准路径；不应因缺少代码生成而绕过 Sails 流水线；当仓库可用 sails-rs 构建辅助时，不应将 sails-idl-gen 加 sails-client-gen 记录为默认专用客户端路径。