前言¶
在 DSH 里做 3D 相关工作，常见做法是拆成多块：一个技能负责参数化建模，另一个只读 STL，再单独写脚本修补非流形边。各块互不衔接时，智能体很难判断「建模成功」是否等于「切片能过」。3d-fabric 把 SolidCraft CLI 桥接、网格检查与修复收进同一个插件，用统一的退出码和报告串起从描述零件到验收网格的整条路径。
这是什么¶
3d-fabric（维护者 JiamingShi-JsPhys）是 DeepSeek Harness 社区目录中的工作流类插件。它在单机内覆盖：通过本地 SolidCraft CLI 做自然语言驱动的参数化 CAD、读取与编辑既有设计、测量与预览，以及对 STL 等网格做面向 3D 打印的质量检查与修复。插件版本 1.0.0，包含 7 个 CLI 动作；上游 README 标明已在 SolidCraft 0.30.1 上验证。
插件不含 SolidCraft 本体，也不打包其二进制；模型数据不出本机——文档声明不做外网请求、不使用 eval，子进程仅为本机安装的 solidcraft-cli。
架构：桥接与门控¶
下面介绍 README 里划分的两半，以及各自负责的模块。
桥接（SolidCraft）。 宿主智能体用自然语言；SolidCraft 消费 JSON 命令列表。scripts/solidcraft.py 是唯一接触 SolidCraft CLI 的文件：按 --solidcraft、SOLIDCRAFT_CLI、SOLIDCRAFT_HOME、PATH 或厂商默认路径定位可执行文件，用 --version 校验后再执行脚本；只有承诺的导出文件在磁盘上非空存在，才报告成功。script、model --in、measure、snapshot 等动作也经此桥完成。
门控（网格）。 scripts/engine.py 是唯一处理几何的文件，几何运算委托给 MIT 许可的 trimesh。inspect 关注切片器在乎的指标：封闭性、法线、非流形边、退化面等；结论为 ready_to_print、needs_repair 或 blocked。inspect 与 repair 不需要安装 SolidCraft，扫描件或外来源网格仍可检查与修复。
run.py 只编排上述七个动作，不嵌入 SolidCraft 源码。references/solidcraft/ 内是 SolidCraft 发布的四份智能体参考文档的逐字副本（MIT），可选；删掉后 run.py 仍可用，只是失去内置命令形状说明。
七个动作¶
| 动作 | 作用 | 需要 SolidCraft |
|---|---|---|
probe |
定位并校验 CLI | 否（仅探测） |
model |
执行脚本、导出并自动检查；--in 可编辑既有设计 |
是 |
script |
将 .sc / .step 还原为 {"commands": [...]} |
是 |
measure |
从 B-rep 读体积、质量、拓扑等 | 是 |
snapshot |
渲染 PNG 预览 | 是 |
inspect |
任意网格的可打印性报告 | 否 |
repair |
焊接、补洞、修法线等 | 否 |
一次成功的 model 往往在输出目录并列生成网格（如 .stl）、可编辑设计（.sc）以及产生该零件的脚本（.solidcraft.json）。
安装与启用¶
安装须保持 run.py、scripts/、skills/ 同属一套插件树；拆散复制会导致模块导入失败。
1. 先装 SolidCraft¶
3d-fabric 不自带实体内核。请从 SolidCraft 下载页 安装；Linux 亦可 sudo snap install solidcraft。浏览器版不提供 solidcraft-cli，无法被本插件使用。
装完后确认：
solidcraft-cli --version
若不在 PATH 上，可通过环境变量或 python run.py --action probe --solidcraft <路径> 指向可执行文件（详见仓库 docs/INSTALL_COMMANDS_zh.md）。
2. Python 依赖¶
需要 Python 3.10+，几何栈通过：
python -m pip install -r requirements.txt
3. 在 DSH 中安装插件¶
DSH 将插件视为带 package.json 与 cordis.patch.yml 的组合包，由 index.js 把技能注册进技能表。官方文档给出的 DeepSeek Harness 命令为：
dsh plugin --profile desktop add github:JiamingShi-JsPhys/3d-fabric#v1.0.0
未在 package.json 中声明 dsh.bundle.patch 的包会被 dsh 拒收；升级时需先卸载再安装新版本，不支持原地覆盖。
也可在各宿主自带的插件市场中注册仓库 Git URL（见 README「方法一」）。社区目录页：SkillHub — 3d-fabric。
安装前建议自行阅读仓库源码与 MIT 许可证，并牢记：插件以当前 dsh 进程的权限在本地运行，可调用本机上的 SolidCraft 与 Python 环境。
典型用法¶
命令行自检与流水线¶
先探测环境，再按任务选动作。下列示例来自上游 README 快速入门：
python run.py --action probe
python run.py --action model --input examples/bracket_request.json --quality fine
python run.py --action script --input bracket.sc --output build.json
python run.py --action model --script widen.json --in bracket.sc --output bracket_150.stl
python run.py --action measure --input bracket.sc
python run.py --action snapshot --input bracket.sc --output bracket.png --view iso
python run.py --action inspect --input examples/damaged_part.stl
python run.py --action repair --input examples/damaged_part.stl --center
脚本或 CI 需要结构化输出时，可加 --json；配合 --root 时，门控报告会写入工作区下的 process/gates/ 路径，与标准输出内容一致。
在对话里使用技能¶
安装为插件后，可通过技能入口触发（例如 README 中的 /3d-fabric 与自然语言尺寸描述）。智能体通常依次：probe → 编写 SolidCraft 脚本 → model → 读取门控结论；对已有设计则调用 script、measure、snapshot 或 model --in。完整操作规则见仓库内 skills/3d-fabric/SKILL.md。
适用场景与注意¶
适合谁： 需要在同一台开发机上，把「参数化建模 + 导出多格式（STL / STEP / 3MF / OBJ）+ 打印前网格验收」交给智能体工作流的 DSH 用户；也适合只处理外来 STL、在无二进制 CAD 的机器上做 inspect / repair 的场景。
有意不做的事： 有机造型、雕刻、材质、灯光与动画留给 Blender 类工具；本插件定位是参数化 CAD 前端与打印质量关口。
生态说明： DeepSeek Harness 的「一切皆插件」由社区目录与本地 dsh plugin 生态承载；SkillHub 等目录站点与 DeepSeek / 幻方无官方从属关系，本文仅作插件技术说明。
安全与合规： 仓库免责声明写明：社区插件与 SolidCraft 项目无隶属或背书关系；除 references/solidcraft/ 下按 MIT 复制的参考文档外，不包含 SolidCraft 源码或二进制。
结尾¶
若你希望减少「建模技能、质检技能、修补脚本」之间的手工拼装，3d-fabric 用一条 CLI、一套出口码和一份门控报告把路径收紧。进一步了解可查阅 GitHub 仓库 与 SkillHub 目录页。
