text-to-cad SDF 技能中的 LLM 护栏约束 Agent 编写 SDFormat 的规范与工程实践【免费下载链接】text-to-cadA library of agent skills for CAD, CAE and CAM项目地址: https://gitcode.com/GitHub_Trending/tex/text-to-cad在基于大语言模型LLM生成机器人仿真描述的工程实践中Agent 擅长把意图组织成文档结构却极不擅长悄无声息地猜出一个精确的空间变换或惯性张量。本文围绕 text-to-cad 仓库中 SDFSDFormat技能的护栏规范 llm-guardrails.md 展开系统讲解该技能如何把 Agent 的能力短板路由到显式设计账本、常量、辅助脚本、校验器和冒烟测试中去并结合仓库中配套的校验器源码skills/sdf/scripts/sdf/、设计账本模板design-ledger.md与工作流文档sdf-workflow.md给出可直接落地的 SDF 编写与验收标准。读完本文你将掌握一套完整的能力边界划分 强制溯源 可审计报告的 LLM 建模护栏方法论。核心假设Agent 强于结构组织弱于静默取值护栏文档开篇即给出该技能的基本假设assumptionAgent 在结构化 SDFormat 文档方面是有用的但在静默推导精确的空间、物理和仿真器特定数值方面是不可靠的。因此整个 SDF 技能的工作流设计目标就是把这些能力短板weaknesses显式地路由到五类受控手段中——显式的设计账本design ledger见 design-ledger.md显式常量与注释一次性辅助脚本throwaway helper scripts结构校验器bundled validator仿真器冒烟测试smoke tests见 smoke-tests.md。这一假设并非泛泛而谈它直接对应到技能主文件 SKILL.md 的核心规则第 8 条不要仅凭视觉印象推断空间变换……绝不徒手freehand计算数值——用公式或一次性辅助脚本惯性张量、单位换算。Agent 可以信赖做什么能力白名单文档用一份清单界定了 Agent 通常可以做得好的事情What agents can usually do well这也是使用 Agent 编写 SDF 时应该保留和利用的能力面将 SDF 模型或世界组织成 links、joints、frames、visuals、collisions、sensors、plugins 和 includes 的完整结构把用户意图转译成合理的plausible文档结构在命名显式给定时维持命名一致性编写小的、一次性的 Python 脚本用于派生数值与变换计算解释假设并创建检查清单checklists在示例就近nearby examples存在时保留既有模式。从源码结构看第 4 条能力在整个技能里被反复强调sdf-workflow.md 的编辑循环第 7 步要求派生数值——惯性张量、单位换算——必须用公式或一次性辅助脚本计算绝不徒手填写主技能 SKILL.md 甚至将gen_sdf()这类生成式契约明确排除没有gen_sdf()契约要求直接编写和编辑 XML。换言之Agent 的代码能力被限定在计算工具而非数值来源上。不应被静默推断的值黑名单清单护栏文档的价值核心在于一份明确的不可静默推断清单What agents should not be trusted to infer silently。以下九类值如果出现在 SDF 中必须有据可查否则就是违规#不可静默推断的值典型事故形态1精确的 link 位姿、frame 变换或 joint 原点模型整体错位、关节偏移2仅凭视觉主题visual theme判断的正向关节轴方向关节运动方向与指令相反3mesh 的单位、mesh scale 或坐标系约定模型放大/缩小 1000 倍mm vs m4仅凭渲染形状得到的质心或惯性张量仿真中爆炸、穿地5插件文件名、参数、topic、命名空间或 sensor schema插件加载失败、topic 无输出6某插件是仿真器运行时插件还是 CAD Viewer 可视化专用扩展把仅用于查看器的 motion 插件写进 SDF7目标仿真器对某个 SDFormat 版本或扩展的支持情况在旧版 libsdformat 下加载失败8碰撞几何对物理求解是否稳定动态物体抖动、卡进地面9外部 URI 在部署环境中能否解析模型/资源 404link mesh 缺失这九条与 frame-semantics.md 末尾的LLM guardrails小节相互呼应后者补充了关节轴符号、轴所在 frame、RPY 顺序与单位、mesh 原点约定、relative_toframe、嵌套作用域引用、传感器光学系变换、插件 frame/topic 语义等同样不可从散文推断的条目共同构成一份从代码与文档结构看哪些数值必须溯源的完整负面清单。强制缓解模式每个关键值的五种合法来源护栏文档给出了强制缓解模式Required mitigation pattern对于每一个空间、物理或仿真器特定的值必须使用以下来源之一用户提供的需求user-provided requirement上游几何、机器人描述、规划元数据、mesh 清单或模型包来源upstream source目标仿真器文档target simulator documentation标注了方法method的测量或计算值记录在账本注释块ledger comment block和最终报告中的显式假设。并伴随一条硬规则不要把猜测值藏在裸 XML 里——每一个不显然的数字都必须携带注释或账本行来指明其来源every non-obvious number carries a comment or a ledger line naming its source。设计账本假设的规范化载体第 5 类来源依赖设计账本机制。design-ledger.md 规定账本在编写 SDF XML之前创建或更新其规范位置是.sdf文件顶部的注释块大型世界可在相邻笔记中扩展目的是在空间与仿真假设变成难以审计的 XML 之前先把它们外部化。账本模板包含七张表与两个清单覆盖了护栏文档中所有不可静默推断的类别Document输出路径、来源文件、SDF 版本默认1.12除非被目标约束、文档类型model / world / model-in-world、目标消费者Gazebo / 其他仿真器 / 仅可视化 / 模型包、单位制米、千克、秒、弧度、坐标约定Model or world scope名称、静态/动态、canonical link、模型位姿及其relative_to、includes 的 URI 与用途Frames每个 frame 的作用域、挂载对象、位姿、位姿relative_to、用途与来源Links每个 link 是物理 link 还是 frame-like link、位姿、惯性来源、挂载的 sensor/pluginJoints类型、parent/child、位姿及其 frame、轴及其expressed_inframe、限位、正向运动约定positive motion、来源Geometryvisual/collision 归属、几何类型、位姿、URI 或尺寸、mesh 单位、scale、来源Inertials质量、质心位姿、惯性张量、方法/来源、置信度Sensors and plugins父级、位姿/frame、文件名/类型、参数、来源文档、假设Assumptions to report把所有猜测或推断值逐条列出——位姿、轴符号、mesh 单位/比例、质量/质心/惯性、目标仿真器行为、插件参数、未解析外部 URI、被跳过的校验或冒烟测试。这套账本设计正是缓解模式的落地Agent 的每一个推断都不再静默存在于 XML 里而是变成账本上一行可评审、可追溯到来源的条目。占位符策略什么情况下允许先占位护栏文档对占位符placeholder给出了严格的两段式策略允许条件只有当用户明确要求 scaffold脚手架、draft草稿或 minimal example最小示例时才允许使用占位符且必须标注为 placeholder并保持易于替换。可接受的占位符示例——用注释明确标注其待测量性质!-- placeholder_inertial: primitive approximation pending measured mass properties -- inertial mass0.5/mass ... /inertial不可接受的占位符这五条每一条都对应黑名单清单中的一项杜撰invented插件文件名向 SDF 文件添加 CAD Viewer 专用的 motion 插件对动态机器人随意给出惯性值却不加警告猜测 mesh scale 仅为了让视觉效果看起来合理为了让结果匹配某张预期截图而静默翻转关节轴。值得注意的是第二条smoke-tests.md 与 validation.md 都专门说明了 CAD Viewer 只把 SDF 插件、传感器、灯光、includes 和嵌套模型当作静态元数据处理——它不会执行 SDF 插件也不读取文件内编写的运动元数据。这解释了为什么把 Viewer 插件写进 SDF既不能带来仿真行为还会在交付给真正的仿真器时造成误导。空间推理检查表生成前必答的七问护栏文档要求在生成或修改 SDF 之前必须在账本或最终报告中回答以下问题。这张表把隐性推断变成了显性举证问题要求的证据每个位姿是在哪个 frame 中表达的relative_to、来源文件或有文档记载的默认值每个关节轴是在哪个 frame 中表达的expressed_in或有文档记载的默认值每个非 fixed 关节的正向运动是什么指令/测试期望或上游来源mesh 的单位与 scale 是否已知manifest、CAD 导出配置或显式假设visual 与 collision 位姿是否被有意设为不同仿真原因或来源几何惯性数据是测量、计算、近似还是省略方法与置信度插件与传感器参数是否抄自目标文档目标仿真器/版本以及来源这七问与 frame-semantics.md 的核心规则一一映射默认rotation_formateuler_rpy下位姿为 6 个值x y z roll pitch yawquat_xyzw下为 7 个值欧拉角默认是弧度degreestrue虽然合法但应避免relative_to省略时 SDF 会套用元素级默认通常是父 XML 元素的 frame这可能是合法的但极易误读。正是这种默认值机制使 SKILL.md 核心规则第 7 条把隐式 frame 默认值定性为SDF 的头号失败模式top failure mode并要求在每个非平凡的 pose 和 axis 上显式写出relative_to/expressed_in。编写风格可审计 XML 对照护栏文档用一对正反示例锁定了 SDF 的编写风格Authoring style。推荐模式——每个变换都携带来源注释、显式 frame 与单位约定!-- Source: project CAD frame export 2026-05-12. RPY radians. -- pose relative_tobase_link0.18 0 0.12 0 -0.2 0/pose应避免的模式pose0.18 0 .12 0 -11.5 0/pose文档给出的批判很精确第二种写法省略了 frame读者不知道该位姿相对谁表达、在未声明的情况下使用了角度制-11.5是角度而非弧度的迹象混用单位会让下游消费者按弧度解析、并且使得变换的来源无法被审计。这三点恰好是黑名单中frame 推断与单位约定推断的合并发作。从仓库工程角度看这条风格规则还能与校验器形成闭环validation.md 描述的 pose 检查项包括degreestrue未显式声明时给出 warning、非平凡的relative_to省略给出 warning、relative_to在局部作用域内可解析、嵌套::引用语法有效且可解析——也就是说应避免的模式写出来大概率会被 bundled validator 至少以 warning 形式标记配合--strict模式可以直接变成失败。校验器与护栏的关系便宜的确定性检查不是物理证明护栏文档Validation expectations一节给出了关键分寸感校验器应当捕捉便宜的确定性错误cheap deterministic mistakes但它无法证明设计在物理上或仿真器上是正确的。bundled validation 之后当任务依赖仿真器行为时应使用可选的外部检查与仿真器冒烟测试。并且被跳过的检查必须被显式报告——跳过一个检查不是自动的失败但它是相关的风险信息relevant risk information。Bundled validator 的实现印证仓库中该技能的校验入口是 scripts/validate/main.py它只是薄封装实际调用 sdf/cli.py 的main()诊断结果的统一数据结构定义在 sdf/findings.py严重级别被严格限定为三档findings.py 的Severity Literal[error, warning, info]error足以阻止写出输出warning表示可能是问题或未经验证的仿真器行为除非--strict输出仍会写出info是假设、被跳过的检查或有用的上下文。ValidationResult.ok属性只看errors是否为空findings.py而 CLI 在--strict时把warnings计入阻断计数cli.pyblocking len(validation.errors) (len(validation.warnings) if strict else 0)。每条Finding携带severity、code、message、pathXML 路径和hint文本模式逐条打印到 stderr--format json则输出机器可读的 findings 文档——这使报告哪些检查被跳过可以直接落进结构化报告。而gz sdf --check的外部检查由 sdf/external.py 实现其行为与护栏文档跳过要显式报告的要求逐条对应--gz-check never不运行但仍然写入一条info级 findinggz_check_skippedgz sdf --check skipped by requestexternal.pyPATH 上找不到gzauto模式下发warninggz_check_unavailablerequired模式下发errorexternal.py找到gz时把待校验 XML 写入临时文件并运行gz sdf --check失败记gz_check_failederror通过记gz_check_passedinfoexternal.py。也就是说跳过在实现层面永远会产生一条可被采集、可被引用的诊断记录而不是一片静默——这正是护栏文档最后一节不要只说文件是有效的要说哪个校验器或冒烟测试通过了的工程基础。校验边界能查什么、查不到什么validation.md 把 bundled checks 的覆盖面列得很完整根元素与version形状版本须为 1.4–1.12 的已知发布否则 warning、名称与作用域link/joint/frame/sensor 等在同一 frame-graph 命名空间内跨类型重名即为 error、poses六个/七个有限值、四元数归一化、degreestrue警告、relative_to解析、framesattached_to解析、附着链无环、jointsSDF 1.12 已知九种类型continuous, revolute, gearbox, revolute2, prismatic, ball, screw, universal, fixedworld可作 parent 不可作 child轴向量有限非零且归一化限位/动力学数值约束、几何与 mesh URIbox/cylinder/sphere/plane 尺寸有限为正、mesh URI 非空、本地引用相对.sdf位置解析、外部 scheme 不做本地解析、inertials质量正有限、惯性矩阵在半正定容差内、动态 link 缺惯性至少 warning、sensors 与 plugins名称唯一、type 来自已知列表、校验器不杜撰仿真器特定的插件 schema。文档特别点出了护栏所警告的那类便宜检查的盲区插件文件名和参数可以通过 bundled validation仍然会在目标仿真器加载时失败——请使用冒烟测试。smoke-tests.md 随后给出了逐层加深的检查阶梯bundled validation可用--strict让 warning 阻断交付→gz sdf --check尽量用将消费该文件的仿真器环境→ 仿真器加载检查无解析告警/插件错误、模型出现在预期位姿、动态模型不爆炸、不穿地、无无效惯性告警→ 关节运动检查指令一个小正位移确认运动方向、限位、连续关节→ CAD Viewer 静态评审确认 links/joints/frames/visuals/collisions 摆放正确includes/plugins/sensors/lights/嵌套模型按静态元数据列出并记录 Viewer 无法执行的仿真器专有行为→ sensor/plugin 检查插件库可加载、topic/service 出现、frame 名与账本一致。最后还定义了何时停下修复的停止条件bundled 校验有 error、required 策略下gz sdf --check失败、仿真器报告无效惯性或必需资源未解析、关节运动方向与文档记载的正向相反、任务必需的插件启动失败。文档还特别区分了四类判定防止项目偏好越权为合法性SDF 结构合法性、数值合理性、仿真器兼容性、项目策略mesh 位置、URI 风格、碰撞简化等——不要仅因违反项目策略就拒绝合法的 SDF除非任务或仓库要求该策略优先使用 warning 与 strict 模式控制。这与 sdf-workflow.md 的检查既有 SDF 的三问对 bundled validator 结构合法吗与目标 SDFormat/libsdformat/仿真器版本兼容吗满足本项目打包/mesh/工作流策略吗是同一思想的两面。Agent 的收尾行为报告而非宣称护栏文档的最后一节规定了 Agent 完成 SDF 任务后的强制报告行为Response behavior for agents。必须陈述创建或修改的.sdf路径运行过的检查及其结果被跳过的检查及原因假设与占位符需要仿真器验证的风险。并附一条纪律不要只说文件是有效的要说哪个校验器或冒烟测试通过了Do not simply say that the file is valid. Say which validator or smoke test passed.。这与 SKILL.md 的Required report shape完全一致该处给出了一个紧凑报告模板Validated: path/to/model.sdf Checks run: - bundled SDF validation: passed - gz sdf --check: skipped, gz not installed - simulator load: skipped, target simulator unavailable - viewer handoff: $cad-viewer link returned Assumptions: - Assumed mesh units are meters. - Assumed lidar frame is coincident with lidar_link. Risks: - Camera plugin filename was not verified in the target simulator environment.可以看到报告模板的五个分区checks run / checks skipped / assumptions / risks恰好逐条对应护栏文档的五个报告项——被跳过的检查在模板里以skipped, reason的形式出现与 external.py 产生的gz_check_skipped/gz_check_unavailableinfo/warning 记录一一对接。design-ledger.md 末尾的 Compact response template 也给出了同构的紧凑版本SDF source / Generated target / Target consumer / Bundled validation / External checks / Assumptions。小结一条可复用的护栏设计链把护栏文档放回 text-to-cad 的 SDF 技能全貌中skills/sdf/ 下的 SKILL.md、references 与 scripts它实际上构成了一条环环相扣的设计链能力边界声明白名单结构组织、脚本计算、假设说明与黑名单九类不可静默推断的值划清 Agent 的权限来源强制五个合法取值来源 每个不显然数字必须带来源注释/账本行的硬规则外部化载体设计账本七表把假设从 XML 内部搬到可评审的表格中风格规范显式relative_to/expressed_in、显式单位约定、来源注释杜绝不可审计的裸数值分层验证bundled 结构校验抓便宜的确定性错误→ 可选gz sdf --check外部解析→ 仿真器加载/关节运动/插件启动冒烟测试物理与行为正确性跳过必留痕报告纪律交付时声明哪个校验通过、哪些检查被跳过、假设是什么、风险在哪而非一句文件有效。对需要在 LLM 辅助下维护仿真模型文档SDFormat、URDF 等强 frame/单位/schema 约束的格式的团队这套边界—溯源—外部化—分层验证—强制报告的模式可以直接迁移而在本仓库内配套的参考文档 frame-semantics.md、validation.md、smoke-tests.md、design-ledger.md 与校验器源码 skills/sdf/scripts/sdf/ 提供了从规范到实现的完整对照。【免费下载链接】text-to-cadA library of agent skills for CAD, CAE and CAM项目地址: https://gitcode.com/GitHub_Trending/tex/text-to-cad创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 text-to-cad SDF 技能中的 LLM 护栏：约束 Agent 编写 SDFormat 的规范与工程实践
text-to-cad SDF 技能中的 LLM 护栏约束 Agent 编写 SDFormat 的规范与工程实践【免费下载链接】text-to-cadA library of agent skills for CAD, CAE and CAM项目地址: https://gitcode.com/GitHub_Trending/tex/text-to-cad在基于大语言模型LLM生成机器人仿真描述的工程实践中Agent 擅长把意图组织成文档结构却极不擅长悄无声息地猜出一个精确的空间变换或惯性张量。本文围绕 text-to-cad 仓库中 SDFSDFormat技能的护栏规范 llm-guardrails.md 展开系统讲解该技能如何把 Agent 的能力短板路由到显式设计账本、常量、辅助脚本、校验器和冒烟测试中去并结合仓库中配套的校验器源码skills/sdf/scripts/sdf/、设计账本模板design-ledger.md与工作流文档sdf-workflow.md给出可直接落地的 SDF 编写与验收标准。读完本文你将掌握一套完整的能力边界划分 强制溯源 可审计报告的 LLM 建模护栏方法论。核心假设Agent 强于结构组织弱于静默取值护栏文档开篇即给出该技能的基本假设assumptionAgent 在结构化 SDFormat 文档方面是有用的但在静默推导精确的空间、物理和仿真器特定数值方面是不可靠的。因此整个 SDF 技能的工作流设计目标就是把这些能力短板weaknesses显式地路由到五类受控手段中——显式的设计账本design ledger见 design-ledger.md显式常量与注释一次性辅助脚本throwaway helper scripts结构校验器bundled validator仿真器冒烟测试smoke tests见 smoke-tests.md。这一假设并非泛泛而谈它直接对应到技能主文件 SKILL.md 的核心规则第 8 条不要仅凭视觉印象推断空间变换……绝不徒手freehand计算数值——用公式或一次性辅助脚本惯性张量、单位换算。Agent 可以信赖做什么能力白名单文档用一份清单界定了 Agent 通常可以做得好的事情What agents can usually do well这也是使用 Agent 编写 SDF 时应该保留和利用的能力面将 SDF 模型或世界组织成 links、joints、frames、visuals、collisions、sensors、plugins 和 includes 的完整结构把用户意图转译成合理的plausible文档结构在命名显式给定时维持命名一致性编写小的、一次性的 Python 脚本用于派生数值与变换计算解释假设并创建检查清单checklists在示例就近nearby examples存在时保留既有模式。从源码结构看第 4 条能力在整个技能里被反复强调sdf-workflow.md 的编辑循环第 7 步要求派生数值——惯性张量、单位换算——必须用公式或一次性辅助脚本计算绝不徒手填写主技能 SKILL.md 甚至将gen_sdf()这类生成式契约明确排除没有gen_sdf()契约要求直接编写和编辑 XML。换言之Agent 的代码能力被限定在计算工具而非数值来源上。不应被静默推断的值黑名单清单护栏文档的价值核心在于一份明确的不可静默推断清单What agents should not be trusted to infer silently。以下九类值如果出现在 SDF 中必须有据可查否则就是违规#不可静默推断的值典型事故形态1精确的 link 位姿、frame 变换或 joint 原点模型整体错位、关节偏移2仅凭视觉主题visual theme判断的正向关节轴方向关节运动方向与指令相反3mesh 的单位、mesh scale 或坐标系约定模型放大/缩小 1000 倍mm vs m4仅凭渲染形状得到的质心或惯性张量仿真中爆炸、穿地5插件文件名、参数、topic、命名空间或 sensor schema插件加载失败、topic 无输出6某插件是仿真器运行时插件还是 CAD Viewer 可视化专用扩展把仅用于查看器的 motion 插件写进 SDF7目标仿真器对某个 SDFormat 版本或扩展的支持情况在旧版 libsdformat 下加载失败8碰撞几何对物理求解是否稳定动态物体抖动、卡进地面9外部 URI 在部署环境中能否解析模型/资源 404link mesh 缺失这九条与 frame-semantics.md 末尾的LLM guardrails小节相互呼应后者补充了关节轴符号、轴所在 frame、RPY 顺序与单位、mesh 原点约定、relative_toframe、嵌套作用域引用、传感器光学系变换、插件 frame/topic 语义等同样不可从散文推断的条目共同构成一份从代码与文档结构看哪些数值必须溯源的完整负面清单。强制缓解模式每个关键值的五种合法来源护栏文档给出了强制缓解模式Required mitigation pattern对于每一个空间、物理或仿真器特定的值必须使用以下来源之一用户提供的需求user-provided requirement上游几何、机器人描述、规划元数据、mesh 清单或模型包来源upstream source目标仿真器文档target simulator documentation标注了方法method的测量或计算值记录在账本注释块ledger comment block和最终报告中的显式假设。并伴随一条硬规则不要把猜测值藏在裸 XML 里——每一个不显然的数字都必须携带注释或账本行来指明其来源every non-obvious number carries a comment or a ledger line naming its source。设计账本假设的规范化载体第 5 类来源依赖设计账本机制。design-ledger.md 规定账本在编写 SDF XML之前创建或更新其规范位置是.sdf文件顶部的注释块大型世界可在相邻笔记中扩展目的是在空间与仿真假设变成难以审计的 XML 之前先把它们外部化。账本模板包含七张表与两个清单覆盖了护栏文档中所有不可静默推断的类别Document输出路径、来源文件、SDF 版本默认1.12除非被目标约束、文档类型model / world / model-in-world、目标消费者Gazebo / 其他仿真器 / 仅可视化 / 模型包、单位制米、千克、秒、弧度、坐标约定Model or world scope名称、静态/动态、canonical link、模型位姿及其relative_to、includes 的 URI 与用途Frames每个 frame 的作用域、挂载对象、位姿、位姿relative_to、用途与来源Links每个 link 是物理 link 还是 frame-like link、位姿、惯性来源、挂载的 sensor/pluginJoints类型、parent/child、位姿及其 frame、轴及其expressed_inframe、限位、正向运动约定positive motion、来源Geometryvisual/collision 归属、几何类型、位姿、URI 或尺寸、mesh 单位、scale、来源Inertials质量、质心位姿、惯性张量、方法/来源、置信度Sensors and plugins父级、位姿/frame、文件名/类型、参数、来源文档、假设Assumptions to report把所有猜测或推断值逐条列出——位姿、轴符号、mesh 单位/比例、质量/质心/惯性、目标仿真器行为、插件参数、未解析外部 URI、被跳过的校验或冒烟测试。这套账本设计正是缓解模式的落地Agent 的每一个推断都不再静默存在于 XML 里而是变成账本上一行可评审、可追溯到来源的条目。占位符策略什么情况下允许先占位护栏文档对占位符placeholder给出了严格的两段式策略允许条件只有当用户明确要求 scaffold脚手架、draft草稿或 minimal example最小示例时才允许使用占位符且必须标注为 placeholder并保持易于替换。可接受的占位符示例——用注释明确标注其待测量性质!-- placeholder_inertial: primitive approximation pending measured mass properties -- inertial mass0.5/mass ... /inertial不可接受的占位符这五条每一条都对应黑名单清单中的一项杜撰invented插件文件名向 SDF 文件添加 CAD Viewer 专用的 motion 插件对动态机器人随意给出惯性值却不加警告猜测 mesh scale 仅为了让视觉效果看起来合理为了让结果匹配某张预期截图而静默翻转关节轴。值得注意的是第二条smoke-tests.md 与 validation.md 都专门说明了 CAD Viewer 只把 SDF 插件、传感器、灯光、includes 和嵌套模型当作静态元数据处理——它不会执行 SDF 插件也不读取文件内编写的运动元数据。这解释了为什么把 Viewer 插件写进 SDF既不能带来仿真行为还会在交付给真正的仿真器时造成误导。空间推理检查表生成前必答的七问护栏文档要求在生成或修改 SDF 之前必须在账本或最终报告中回答以下问题。这张表把隐性推断变成了显性举证问题要求的证据每个位姿是在哪个 frame 中表达的relative_to、来源文件或有文档记载的默认值每个关节轴是在哪个 frame 中表达的expressed_in或有文档记载的默认值每个非 fixed 关节的正向运动是什么指令/测试期望或上游来源mesh 的单位与 scale 是否已知manifest、CAD 导出配置或显式假设visual 与 collision 位姿是否被有意设为不同仿真原因或来源几何惯性数据是测量、计算、近似还是省略方法与置信度插件与传感器参数是否抄自目标文档目标仿真器/版本以及来源这七问与 frame-semantics.md 的核心规则一一映射默认rotation_formateuler_rpy下位姿为 6 个值x y z roll pitch yawquat_xyzw下为 7 个值欧拉角默认是弧度degreestrue虽然合法但应避免relative_to省略时 SDF 会套用元素级默认通常是父 XML 元素的 frame这可能是合法的但极易误读。正是这种默认值机制使 SKILL.md 核心规则第 7 条把隐式 frame 默认值定性为SDF 的头号失败模式top failure mode并要求在每个非平凡的 pose 和 axis 上显式写出relative_to/expressed_in。编写风格可审计 XML 对照护栏文档用一对正反示例锁定了 SDF 的编写风格Authoring style。推荐模式——每个变换都携带来源注释、显式 frame 与单位约定!-- Source: project CAD frame export 2026-05-12. RPY radians. -- pose relative_tobase_link0.18 0 0.12 0 -0.2 0/pose应避免的模式pose0.18 0 .12 0 -11.5 0/pose文档给出的批判很精确第二种写法省略了 frame读者不知道该位姿相对谁表达、在未声明的情况下使用了角度制-11.5是角度而非弧度的迹象混用单位会让下游消费者按弧度解析、并且使得变换的来源无法被审计。这三点恰好是黑名单中frame 推断与单位约定推断的合并发作。从仓库工程角度看这条风格规则还能与校验器形成闭环validation.md 描述的 pose 检查项包括degreestrue未显式声明时给出 warning、非平凡的relative_to省略给出 warning、relative_to在局部作用域内可解析、嵌套::引用语法有效且可解析——也就是说应避免的模式写出来大概率会被 bundled validator 至少以 warning 形式标记配合--strict模式可以直接变成失败。校验器与护栏的关系便宜的确定性检查不是物理证明护栏文档Validation expectations一节给出了关键分寸感校验器应当捕捉便宜的确定性错误cheap deterministic mistakes但它无法证明设计在物理上或仿真器上是正确的。bundled validation 之后当任务依赖仿真器行为时应使用可选的外部检查与仿真器冒烟测试。并且被跳过的检查必须被显式报告——跳过一个检查不是自动的失败但它是相关的风险信息relevant risk information。Bundled validator 的实现印证仓库中该技能的校验入口是 scripts/validate/main.py它只是薄封装实际调用 sdf/cli.py 的main()诊断结果的统一数据结构定义在 sdf/findings.py严重级别被严格限定为三档findings.py 的Severity Literal[error, warning, info]error足以阻止写出输出warning表示可能是问题或未经验证的仿真器行为除非--strict输出仍会写出info是假设、被跳过的检查或有用的上下文。ValidationResult.ok属性只看errors是否为空findings.py而 CLI 在--strict时把warnings计入阻断计数cli.pyblocking len(validation.errors) (len(validation.warnings) if strict else 0)。每条Finding携带severity、code、message、pathXML 路径和hint文本模式逐条打印到 stderr--format json则输出机器可读的 findings 文档——这使报告哪些检查被跳过可以直接落进结构化报告。而gz sdf --check的外部检查由 sdf/external.py 实现其行为与护栏文档跳过要显式报告的要求逐条对应--gz-check never不运行但仍然写入一条info级 findinggz_check_skippedgz sdf --check skipped by requestexternal.pyPATH 上找不到gzauto模式下发warninggz_check_unavailablerequired模式下发errorexternal.py找到gz时把待校验 XML 写入临时文件并运行gz sdf --check失败记gz_check_failederror通过记gz_check_passedinfoexternal.py。也就是说跳过在实现层面永远会产生一条可被采集、可被引用的诊断记录而不是一片静默——这正是护栏文档最后一节不要只说文件是有效的要说哪个校验器或冒烟测试通过了的工程基础。校验边界能查什么、查不到什么validation.md 把 bundled checks 的覆盖面列得很完整根元素与version形状版本须为 1.4–1.12 的已知发布否则 warning、名称与作用域link/joint/frame/sensor 等在同一 frame-graph 命名空间内跨类型重名即为 error、poses六个/七个有限值、四元数归一化、degreestrue警告、relative_to解析、framesattached_to解析、附着链无环、jointsSDF 1.12 已知九种类型continuous, revolute, gearbox, revolute2, prismatic, ball, screw, universal, fixedworld可作 parent 不可作 child轴向量有限非零且归一化限位/动力学数值约束、几何与 mesh URIbox/cylinder/sphere/plane 尺寸有限为正、mesh URI 非空、本地引用相对.sdf位置解析、外部 scheme 不做本地解析、inertials质量正有限、惯性矩阵在半正定容差内、动态 link 缺惯性至少 warning、sensors 与 plugins名称唯一、type 来自已知列表、校验器不杜撰仿真器特定的插件 schema。文档特别点出了护栏所警告的那类便宜检查的盲区插件文件名和参数可以通过 bundled validation仍然会在目标仿真器加载时失败——请使用冒烟测试。smoke-tests.md 随后给出了逐层加深的检查阶梯bundled validation可用--strict让 warning 阻断交付→gz sdf --check尽量用将消费该文件的仿真器环境→ 仿真器加载检查无解析告警/插件错误、模型出现在预期位姿、动态模型不爆炸、不穿地、无无效惯性告警→ 关节运动检查指令一个小正位移确认运动方向、限位、连续关节→ CAD Viewer 静态评审确认 links/joints/frames/visuals/collisions 摆放正确includes/plugins/sensors/lights/嵌套模型按静态元数据列出并记录 Viewer 无法执行的仿真器专有行为→ sensor/plugin 检查插件库可加载、topic/service 出现、frame 名与账本一致。最后还定义了何时停下修复的停止条件bundled 校验有 error、required 策略下gz sdf --check失败、仿真器报告无效惯性或必需资源未解析、关节运动方向与文档记载的正向相反、任务必需的插件启动失败。文档还特别区分了四类判定防止项目偏好越权为合法性SDF 结构合法性、数值合理性、仿真器兼容性、项目策略mesh 位置、URI 风格、碰撞简化等——不要仅因违反项目策略就拒绝合法的 SDF除非任务或仓库要求该策略优先使用 warning 与 strict 模式控制。这与 sdf-workflow.md 的检查既有 SDF 的三问对 bundled validator 结构合法吗与目标 SDFormat/libsdformat/仿真器版本兼容吗满足本项目打包/mesh/工作流策略吗是同一思想的两面。Agent 的收尾行为报告而非宣称护栏文档的最后一节规定了 Agent 完成 SDF 任务后的强制报告行为Response behavior for agents。必须陈述创建或修改的.sdf路径运行过的检查及其结果被跳过的检查及原因假设与占位符需要仿真器验证的风险。并附一条纪律不要只说文件是有效的要说哪个校验器或冒烟测试通过了Do not simply say that the file is valid. Say which validator or smoke test passed.。这与 SKILL.md 的Required report shape完全一致该处给出了一个紧凑报告模板Validated: path/to/model.sdf Checks run: - bundled SDF validation: passed - gz sdf --check: skipped, gz not installed - simulator load: skipped, target simulator unavailable - viewer handoff: $cad-viewer link returned Assumptions: - Assumed mesh units are meters. - Assumed lidar frame is coincident with lidar_link. Risks: - Camera plugin filename was not verified in the target simulator environment.可以看到报告模板的五个分区checks run / checks skipped / assumptions / risks恰好逐条对应护栏文档的五个报告项——被跳过的检查在模板里以skipped, reason的形式出现与 external.py 产生的gz_check_skipped/gz_check_unavailableinfo/warning 记录一一对接。design-ledger.md 末尾的 Compact response template 也给出了同构的紧凑版本SDF source / Generated target / Target consumer / Bundled validation / External checks / Assumptions。小结一条可复用的护栏设计链把护栏文档放回 text-to-cad 的 SDF 技能全貌中skills/sdf/ 下的 SKILL.md、references 与 scripts它实际上构成了一条环环相扣的设计链能力边界声明白名单结构组织、脚本计算、假设说明与黑名单九类不可静默推断的值划清 Agent 的权限来源强制五个合法取值来源 每个不显然数字必须带来源注释/账本行的硬规则外部化载体设计账本七表把假设从 XML 内部搬到可评审的表格中风格规范显式relative_to/expressed_in、显式单位约定、来源注释杜绝不可审计的裸数值分层验证bundled 结构校验抓便宜的确定性错误→ 可选gz sdf --check外部解析→ 仿真器加载/关节运动/插件启动冒烟测试物理与行为正确性跳过必留痕报告纪律交付时声明哪个校验通过、哪些检查被跳过、假设是什么、风险在哪而非一句文件有效。对需要在 LLM 辅助下维护仿真模型文档SDFormat、URDF 等强 frame/单位/schema 约束的格式的团队这套边界—溯源—外部化—分层验证—强制报告的模式可以直接迁移而在本仓库内配套的参考文档 frame-semantics.md、validation.md、smoke-tests.md、design-ledger.md 与校验器源码 skills/sdf/scripts/sdf/ 提供了从规范到实现的完整对照。【免费下载链接】text-to-cadA library of agent skills for CAD, CAE and CAM项目地址: https://gitcode.com/GitHub_Trending/tex/text-to-cad创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考