text-to-cad 的 SDF 里 mesh 资源该怎么选 URI 形式？model:// 与 package:// 的记录约定
【免费下载链接】text-to-cadA library of agent skills for CAD, CAE and CAM项目地址: https://gitcode.com/GitHub_Trending/tex/text-to-cad
在 text-to-cad 仓库的sdfskill 中编写或修改.sdf文件时，<mesh>的<uri>写什么形式，直接决定目标消费者（Gazebo 等仿真器、ROS 包环境、纯可视化工具）能否加载到网格资源。这个仓库的约定是：SDF 只引用几何与 mesh 资源、不重新生成它们（见 skills/sdf/references/interoperability.md），而资源解析是环境相关的（environment-dependent）——同一个 URI 通过本地验证，不代表在目标仿真环境里也能解析。因此实际操作路径是三步：先按消费者环境选定 URI 形式，再把选择记录进.sdf顶部的设计台账（design ledger），最后用 bundled validator 做结构校验。
先确定目标消费者，再选 URI 形式
skills/sdf/references/sdf-workflow.md 给出的选择标准是：mesh URI 要么对.sdf文件的位置保持稳定，要么使用消费者能理解的 simulator/package URI 约定。文档列出的可用形式及适用条件如下：
| URI 形式 | 解析预期 | 何时使用 |
|---|---|---|
| 相对本地路径 | 相对.sdf文件所在目录解析 | 模型自包含（self-contained），mesh 放在.sdf旁边 |
file:// | 绝对本地文件 | 需要固定绝对路径的本地资源 |
model:// | 仿真器模型路径（simulator model path）下解析 | 资源随仿真器模型包（simulator model package）分发 |
package:// | 仿真器/ROS 包环境下解析 | 仿真环境会解析包根目录（package roots）时 |
fuel://、http://、https:// | 外部资源 | 仅当消费者预期会抓取外部资产时 |
model://和package://并不是"更高级"的写法，而是把解析责任交给不同环境：用model://的前提是资源会落在目标环境的仿真器模型路径下；用package://的前提是目标环境按 ROS/package 方式解析包根目录；两者都不满足时，不要硬凑外部 URL——interoperability.md 明确要求"记录目标消费者能解析哪种 URI 形式"，而不是假设某种形式通用。
选错形式不会立即报错：bundled validator 对model://、package://等已知外部 scheme 不做本地文件系统解析就放行，这正是后面要把选择记录进台账的原因。
还有一条资源归属边界：mesh 资产由 CAD/mesh 工作流拥有——每个 link 一个资产、在 link 自身坐标系下导出、并记录源单位。如果 mesh 本身是错的，修导出，不要在 SDF 里用 pose 去凑。
记录约定：写进设计台账的 Mesh URI policy
按 skills/sdf/SKILL.md 的工作流，写 XML 之前先建好设计台账，其规范位置是.sdf文件顶部的注释块。skills/sdf/references/design-ledger.md 中专门有一张 "Mesh URI policy" 表，这就是model://与package://的记录约定——逐行声明每种 URI 形式是否允许、预期如何解析、备注什么：
| URI kind | Allowed? | Resolution expectation | Notes | |---|---|---|---| | Relative local path | | Relative to the `.sdf` file location | | | `file://` | | Absolute local file | | | `model://` | | Simulator model path | | | `package://` | | Simulator/ROS package environment | | | `fuel://`, `http://`, `https://` | | External resource | |填写时至少落实三件事：
- Allowed? 列给出判断：当前模型允许哪些形式。例如自包含模型只允许 Relative local path；
model://、package://行要么标注不允许，要么在 Notes 里写明部署前提（例如"仅当部署到 ROS 包环境时使用package://"）。 - Geometry 表同步记录：同一台账的 Geometry 部分要求每个 visual/collision 记录 "URI or dimensions"、"Mesh units"、"Scale"，保证 mesh 单位约定和缩放可审计。
- 未解析的外部 URI 必须上报：台账的 "Assumptions to report" 清单明确包含 "unresolved external URI" 以及 mesh 单位/缩放假设；llm-guardrails.md 也强调 mesh 单位、scale、外部 URI 是否能在部署环境解析属于"不允许静默推断"的范畴，只能来自 manifest、CAD 导出配置或显式假设。
如果 SDF 引用的是已导出的 mesh 资产，interoperability.md 还要求记录六项：源几何文件、导出 mesh 路径、mesh 单位约定、mesh 原点约定、visual scale、碰撞简化决策。
XML 中的 URI 必须与上面的记录一致。结构示意如下（代码块为示例，model://后的模型名与资源路径必须替换为目标环境中实际可解析的值，不能照抄）：
<visual name="base_visual"> <geometry> <mesh> <uri>model://model_name/meshes/asset.dae</uri> </mesh> </geometry> </visual>用 bundled validator 校验
校验命令（python是解释器占位，按 SKILL.md 说明，裸python不可用时换成python3、项目虚拟环境解释器或已配置的解释器路径；path/to/model.sdf替换为你的实际文件路径）：
python scripts/validate path/to/model.sdf python scripts/validate path/to/model.sdf --strict针对 mesh URI，validation.md 描述的校验行为是：
- mesh URI 值非空；
- 本地 mesh 引用按
.sdf文件位置解析，文件不存在时报错（missing_mesh_file）——这是本地相对路径能被"证实"的部分； model://、package://、fuel://、http://、https://属于已知外部 scheme，accepted without local filesystem resolution，即放行但不验证真实可达性；- 其他未知 scheme 给出 warning（
unresolved_mesh_uri_scheme）。
--strict会把 warning 当作失败处理；任一目标文件失败时 validator 以非零退出。如果目标环境装有 Gazebo 工具链，可以再跑一次面向目标消费者的解析检查：
gz sdf --check path/to/model.sdf或者通过 validator 的--gz-check auto/--gz-check required/--gz-check never选项控制外部检查的触发方式。gz sdf --check是可选的目标消费者校验，环境里没有gz时按跳过上报，不算 bundled 校验失败（除非显式用了--gz-check required）。
边界与限制
- bundled validator 只能确认本地相对路径，无法证明外部仿真器资源路径在目标环境可解析（interoperability.md 的表述是 "it cannot prove external simulator resource paths unless the target environment is available"）。
model:///package://写得合规，最终仍要靠目标环境的真实加载来验证。 - bundled 校验是轻量预检（preflight），不是 libsdformat/Gazebo 的替代品；涉及兼容性时用目标仿真器的 parser 和 loader。
- URI 风格（preferred URI style、mesh 位置、不允许未解析外部 URI 等）属于 "project policy" 类别，与 SDF 结构有效性分开；文档明确不要仅因违反项目偏好就拒绝合法的 SDF，策略问题优先用 warning 和 strict 模式表达。
- mesh 几何本身不属于 SDF 层的判断范围：mesh 不对时回到其拥有工作流修导出，不要在 SDF 里用 pose/scale 补救。
收尾：按报告格式交代
按 SKILL.md 要求的报告格式，完成 SDF 任务时要写明：跑过的检查及结果（bundled validation、gz sdf --check、simulator load、viewer handoff）、跳过的外部检查及原因、假设清单（例如"假设 mesh 单位是米"、外部 URI 未解析）、以及需要仿真器验证的风险。URI 选择的正确性最终落在两件事上：台账里 Allowed/Resolution expectation 的记录与 XML 中的实际写法一致，且目标消费者环境里真的能加载到 mesh。
【免费下载链接】text-to-cadA library of agent skills for CAD, CAE and CAM项目地址: https://gitcode.com/GitHub_Trending/tex/text-to-cad
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
