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 單位 = 1 公分。

搜尋與使用模型

1. 按名稱或想法搜尋，無需讀完整個目錄（約 200 行）：grep -i "蚊蟲|昆蟲" HOME3D/biblioteca/CATALOGO.md。 閱讀該行：它是什麼、檔案 → export(參數)、顏色風格和已知缺陷（尤其是 "⚠ 眼睛"）。
2. 預覽它（可選）：啟動資料夾伺服器（在 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" <專案>
   

   如果顯示"沒有新模型"或"用戶已拒絕"，則不要問任何問題並結束。
2. 在詢問之前準備好所有內容，每個模型逐一處理。從檔案頂部的註解中提取 --nombre 和 --que-es，從其主要 export 中提取 --fn。事先檢查它是否不含任何個人資訊（客戶、品牌、標誌、頻道文字）、是否為確定性、且沒有看起來像眼睛的形狀；不符合條件的就不進行準備。

   python "SKILL_DIR/aportar.py" --archivo <專案>/escena/modelos/澆水壺.js --fn crearRegadera --id regadera \
     --nombre "澆水壺" --que-es "附有把手和壺嘴的花園澆水壺" [--autor "<姓名或 @用戶名>"] --estilo casa
   

   作者姓名只會詢問一次（用戶希望如何在署名中顯示）並儲存在 ~/.explicadores-3d/autor.txt。 這會產生 400x400 縮圖、ficha.json（作者、日期、CC BY 4.0）、manifest 和目錄中的條目，並通過驗證器。此時尚未上傳任何內容。
3. 用一行話詢問，並附上準備好的清單： 「是否上傳到模型庫？(S/n)」。 按 Enter、"s"、"si" 或 "va" = 是。只有 "n" 或 "no"（或明確表示拒絕的內容） = 否。
4. 是 → 一個包含所有項目的單一 PR：

   python "SKILL_DIR/aportar.py" --publicar regadera,maceta
   python "SKILL_DIR/nuevos.py" <專案> --subido escena/modelos/澆水壺.js escena/modelos/花盆.js
   

   提供 PR 的連結。否 → python "SKILL_DIR/nuevos.py" <專案> --no，並且在該專案中不再詢問（在新 session 中也不會：資訊會儲存在 <專案>/.biblioteca.json 中）。

• 沒有 gh： --publicar 會準備好一切，並解釋手動操作的 3 個步驟（在網頁上 fork，在分支中 commit，建立 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/ 之外的變更會由儲存庫維護者手動審查。