Pedrovbm1/biblioteca

社区3D模型库

HOME3D = $EXPLICADORES_3D 或 ~/.explicadores-3d。模型库位于 HOME3D/biblioteca/： CATALOGO.md（每行一个模型，包含缩略图、参数和已知缺陷），manifiesto.json，modelos/，piezas/， base/（样式、lib2d、调整面板），aportes/（社区贡献），vendor/（three.js、three.quarks、 Tweakpane、Fredoka 字体）和 vista.html。

一切都是程序化和确定性的：没有下载的纹理，没有 Math.random。默认比例 1 u = 1 cm。

搜索和使用模型

1. 按名称或想法搜索，无需阅读整个目录（约200行）：grep -i "mosquito|insecto" HOME3D/biblioteca/CATALOGO.md。 阅读该行：是什么，文件 → export(参数)，颜色风格和已知缺陷（特别是 "⚠ ojos"）。
2. 查看模型（可选）：启动文件夹的 HTTP 服务器（在 biblioteca/ 内运行 python -m http.server 8795），然后打开 localhost:8795/vista.html?m=<id>；添加 &ajustes=1 可显示调整面板，用于移动相机、更改颜色和灯光。或者查看 缩略图 miniaturas/<id>.png（如果您的 harness 允许，可以在子代理中查看，以避免在上下文中加载图像）。
3. 复制到项目（escena/modelos/），永远不要从库中直接导入，并调整样式的导入路径 （../../base/estilo3d.js → ../estilo3d.js）。如果使用粒子（piezas/particulas/），还需要复制 vendor/quarks/ 并在 importmap 中添加 "quarks.core"。
4. 每个文件顶部都有其 API（坐标轴、比例、.poner* / .update(t) 方法）：这应在构造器的任务中占一行。

贡献新模型：始终开启（每个视频完成后）

贡献是常态：每个视频完成后都会自动提供贡献选项，用户只需在不想贡献时拒绝。 代码采用 MIT 许可，模型采用 CC BY 4.0 许可，并会显示贡献者的署名。

1. 检测项目中的新模型和部件（不消耗 tokens；与库进行对比）：

   python "SKILL_DIR/nuevos.py" <proyecto>
   

   如果显示“没有新模型”或“用户已拒绝”，则不要询问任何内容并结束。
2. 在询问前准备好所有内容，逐个模型处理。从文件顶部的注释中提取 --nombre 和 --que-es， 从主 export 中提取 --fn。事先检查模型是否包含任何个人信息（客户、品牌、标志、频道文本）， 是否确定性的，以及是否包含看起来像眼睛的形状；不符合条件的模型不予准备。

   python "SKILL_DIR/aportar.py" --archivo <proyecto>/escena/modelos/regadera.js --fn crearRegadera --id regadera \
     --nombre "Regadera" --que-es "带把手和壶嘴的浇花壶" [--autor "<姓名或@用户名>"] --estilo casa
   

   只询问一次作者信息（希望如何显示在贡献者名单中），并保存在 ~/.explicadores-3d/autor.txt 中。 这将生成 400x400 缩略图、ficha.json（作者、日期、CC BY 4.0）、manifest 条目和目录条目，并通过验证器。 此时不会上传任何内容。
3. 用一行询问，包含已准备好的模型列表： 是否上传到库？(S/n)。 按下 Enter、"s"、"sí" 或 "va" = 是。只有 "n" 或 "no"（或明确拒绝的回复）= 否。
4. 是 → 一个包含所有模型的 PR：

   python "SKILL_DIR/aportar.py" --publicar regadera,maceta
   python "SKILL_DIR/nuevos.py" <proyecto> --subido escena/modelos/regadera.js escena/modelos/maceta.js
   

   提供 PR 链接。否 → python "SKILL_DIR/nuevos.py" <proyecto> --no 并且不要再询问该项目（新会话中也不会询问：状态保存在 <proyecto>/.biblioteca.json 中）。

• 没有 gh 时： --publicar 会准备所有内容并解释手动操作的3个步骤（在 Web 上 fork，在分支中提交，创建 PR）。 安装 gh：winget install GitHub.cli / brew install gh / cli.github.com，然后运行 gh auth login。
• 每个 PR 由 GitHub Action 验证（无头浏览器、确定性、无网络、大小、缩略图、条目和作者），并由人工批准。 合并后，作者会出现在 CATALOGO.md、index.html 画廊和 APORTADORES.md 排名中。 贡献者会优先获得新或精选包（参见 README，“贡献与回报”）。

修复缺陷

如果在视频中修复了库中模型的缺陷，请也向仓库提出修复建议（正常的 PR，说明修复前后的差异）；aportes/ 之外的更改由仓库维护者手动审查。