企业官网建设流程全解析

text-to-cad Git LFS 大文件管理：STEP 模型与渲染资产在仓库中的完整工程实践

【免费下载链接】text-to-cadA library of agent skills for CAD, CAE and CAM项目地址: https://gitcode.com/GitHub_Trending/tex/text-to-cad

text-to-cad 是一个覆盖 CAD、CAE 与 CAM 的 Agent 技能库，它用Git LFS 大文件管理让 STEP、STL、3MF 等模型文件与渲染资产按需流转，仓库保持轻量却不丢失任何模型历史。这篇文章带你拆解这套实践的关键设计。

📦 为什么 CAD 大文件不能直接进 Git

CAD 交换文件（STEP、STL、3MF、DXF）天生不适合普通 Git 存储：

• 纯二进制：git diff、git merge对其几乎无效，冲突时只能整文件覆盖
• 体积大且持续增长：一个复杂 STEP 模型动辄数十 MB，每次提交都会把完整副本塞进对象历史，克隆和推送会越来越慢
• 生成资产反复重写：渲染缓存、拓扑数据属于构建产物，频繁变更会进一步膨胀仓库

text-to-cad 在 .gitattributes 文件顶部就把设计意图写成了注释：

Keep CAD exchange files and generated render/topology assets out of normal git object history.

效果直观可见：实测该仓库工作区约43MB，而.git/objects/pack打包后的历史对象只有约4.8MB—— 大文件全部走 LFS 远端，普通克隆不再背负它们。

📝 完整的 .gitattributes 规则清单

打开 .gitattributes（位于仓库根目录），规则按"模型交换文件 → 网格与媒体 → 渲染资产 → 反向排除"组织：

每条规则都带上filter=lfs diff=lfs merge=lfs -text四件套，含义是：提交时过滤为 LFS 指针、禁用文本 diff、合并走 LFS 语义、不进入 Git 的文本换行规范化。

再看反向排除，这是很多仓库容易忽略的细节：

• assets/**/*.md !filter !diff !merge text—— 资源目录下的规格 Markdown 留在普通 Git 里，保证评审和 diff 可读
• docs/public/hero/**/*.glb !filter !diff !merge -text—— 文档站头部的小 GLB 不进 LFS，避免为几 MB 的小文件多一层指针

一句话总结：默认托管，白名单豁免，规则粒度精确到"目录 × 扩展名"。

🎨 渲染资产为什么也进 LFS

text-to-cad 的 CAD 技能 生成 STEP 后，会在.*.step/隐藏目录里产出配套的 GLB 网格与拓扑文件，供 CAD Viewer 在浏览器中直接预览（如 renderAssetClient.js 等消费端）。这些资产的特点是随模型反复再生成、体积不小，因此一并纳入 LFS：

• 模型与其渲染产物在同一个指针化提交里保持一致性
• 克隆仓库的人不必下载所有渲染缓存即可工作
• diff=lfs让 Git 对这类"每次都不一样"的文件不再产生无意义的行级 diff

🪶 按需水合：让轻量克隆真正轻量

这是 text-to-cad 最实用的一条实践，写在 CONTRIBUTING.md 的Git Hygiene章节：

assets/**holds heavyweight demo GIFs and is excluded from default LFS pulls, so lightweight clones do not fetch it.

即：演示 GIF 这类"只有做演示才需要"的重量级资产默认不参与 LFS 拉取，日常开发者的克隆是真正轻量的。只有确实需要本地查看演示素材时才执行：

git lfs pull --include="assets/**"

配合 AGENTS.md 中Git And LFS章节给 Agent 的约束，形成一套按需加载规范：

1. 新建分支 / worktree 默认保持轻量，不把.venv/、models/复制进.worktreeinclude
2. 需要用到某个模型时，优先本地 LFS 缓存：git lfs checkout <path>或git lfs checkout models
3. 只有确认本地缓存缺失、且任务明确需要时，才去下载 LFS 对象
4. 永不为git add、commit 等操作禁用 LFS filter（指针化提交是这套体系成立的前提）

✅ 收益与落地清单

如果你也想在自己的 CAD 项目里复刻这套实践，照抄这份清单即可：

• 在仓库根目录新建 .gitattributes，用filter=lfs diff=lfs merge=lfs -text托管*.step、*.stl、*.3mf、*.dxf、*.glb等交换格式
• 为生成类资产（渲染网格、拓扑数据）添加目录级规则，如**/.*.step/**
• 对需要保持 diff 可读的 Markdown/小资源写反向排除（!filter !diff !merge）
• 在贡献文档中约定：重型演示资产排除出默认 pull，用git lfs pull --include="..."按需水合
• 在 Agent/开发者守则中固化：优先git lfs checkout用本地缓存，永不绕过 LFS filter

这套"指针化提交 + 按需水合 + 白名单豁免"的组合，正是 skills/ 目录下十余个技能（CAD、URDF、SDF、DXF 等）能持续产出大模型资产、而仓库历史依然轻快的关键。

【免费下载链接】text-to-cadA library of agent skills for CAD, CAE and CAM项目地址: https://gitcode.com/GitHub_Trending/tex/text-to-cad