Community影像github.com

lego-moc

透過照片辨識零散樂高零件並建立零件庫存,接著使用這些零件設計樂高模型(MOC),最後由伺服器進行物理驗證,提供修正建議或發布包含3D預覽和逐步搭建說明的公開頁面。

lego-moc 是什麼?

此技能「lego-moc」能讓 AI 代理(如 Claude Code、Cursor、Codex)將樂高零件的照片轉換為可存取的庫存,並設計原始模型。它首先使用「掃描」階段辨識散落零件並維護庫存,接著進入「設計與驗證」階段,代理需設計一個 LDraw 格式的模型,伺服器會以物理模擬方式驗證其結構可行性。此技能支援多種平台,可透過 MCP 工具(如 scan_photos、inventory、submit_model)或一個自給自足的 Python 後備腳本運作。AI Summary 應說明其核心功能是將樂高零件照片轉為數位庫存、從庫存中設計可拼裝的 LDraw 模型、以及由伺服器提供實體驗證(包括規則違規、零件使用量及逐步搭建說明)。此技能在用戶想要識別、掃描或計數樂高零件、建立庫存、從自有零件設計 MOC、或驗證模型的實體可拼裝性時特別有用。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/garmanwu/lego-moc/tree/HEAD

Installed? Explore more 影像 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

LEGO 零件辨識與 MOC 設計

分兩個階段:

  1. 掃描。 使用者拍攝散落零件的照片;伺服器辨識這些零件並維護庫存(按使用者 ID)。
  2. 設計與驗證。 您從該庫存中設計一個模型(MOC),並將其編寫為 LDraw 檔案。伺服器會對其進行物理驗證:如果失敗,它會指出違規的行;如果通過,它會發布一個包含 3D 檢視和逐步搭建說明的頁面。伺服器不負責設計:設計是您的工作。

有兩種工作方式。MCP 工具(第 2 節)無需 shell 指令;只要它們可用,請優先使用。腳本 scripts/lego.py(第 5 節)透過 shell 指令執行相同功能,作為備用方案。

1. MCP 工具是否可用?

請在您的工具清單中尋找以下名稱,它們通常顯示在伺服器前綴下,例如 lego-moc(例如 mcp__lego-moc__scan_photos 或 lego-moc.scan_photos):

scan_photos、scan_status、inventory、edit_inventory、design_guide、connectors、submit_model、moc_status

  • 全部存在: 按照第 2 節的方式工作。
  • 除了 scan_photos 外全部存在: 主機使用的是遠端伺服器端點,無法讀取此電腦上的檔案。使用腳本上傳照片(scan),其餘操作使用工具。
  • 全部不存在: 使用腳本(第 5 節)處理此任務;所有操作都能透過它完成。然後向使用者提供以下的一次性設定,這將免除每個指令的批准。

一次性設定(由使用者執行)

  1. 執行 python3 <此技能資料夾>/scripts/lego.py mcp-config(Windows 使用 python)。它會輸出一個 JSON 區塊,且不會進行任何網路呼叫。
  2. 將該 JSON 提供給使用者,並要求他們將 lego-moc 條目新增到代理的 MCP 設定的 mcpServers 區段中(設定頁面或 MCP 設定檔),然後重新啟動代理或重新載入其 MCP 伺服器。僅在使用者要求時,您才可以直接編輯主機的組態。
  3. 重新啟動後,代理會自行啟動橋接程式(lego.py mcp,一個本機 stdio MCP 伺服器),工具便會出現。使用相同的 ~/.lego-parts/ 資料夾和使用者 ID,因此之前掃描的所有內容都不會遺失。

lego.py mcp-config --remote 則會輸出伺服器自己的端點(type: http,一個包含使用者 ID 的 URL;如果沒有 ID,它會建立一個)。僅在無法執行本機指令的主機上使用它。它沒有 scan_photos,且其 URL 屬於憑證:切勿在任何公開場合發布。

2. MCP 流程

每個工具結果都包含供您閱讀的文字部分和一個包含欄位的 structuredContent 物件。錯誤會以 isError: true 的結果形式返回,其文字會說明發生什麼事以及下一步該怎麼做。請遵照執行;不要透過您自己的 HTTP 呼叫繞過它。

掃描

  1. scan_photos {"paths": [...]}:此電腦上照片檔案、資料夾或 glob 模式的絕對路徑,每次呼叫 1-30 張照片(JPEG、PNG、WEBP、HEIC,每張 25 MB)。它會立即返回,每個照片有一個任務;它不會等待辨識完成。請將每個 rejected 和 not_uploaded 條目及其原因告知使用者。duplicate_photo 條目表示該確切檔案先前已上傳過:它不會被重新辨識,且 previous 是第一次上傳的結果(其零件已存在於庫存中)。如果主機呼叫超時,上傳仍會繼續:請改為呼叫 scan_status,不要重新上傳。如果有很多大照片,請分幾次呼叫,每次約 8 張。
  2. scan_status {"wait_s": 50}:重複直到 pending 為 0(辨識需要數分鐘;第一張照片可能需要等待 GPU 啟動)。將每個 notices 條目(pile_photo、no_pieces)逐字轉達給使用者,並指出失敗的照片及其 error。如果長時間處於 pending 狀態,請告訴使用者還有多少張照片正在處理中,而不是無限期循環。

顯示與更正庫存

  1. inventory:顯示庫存,包含概覽圖片(結果中的圖片)和 inventory_url。向使用者展示圖片並提供連結;如果您有瀏覽器或預覽面板,請在那裡打開連結。切勿呈現純零件編號的表格:大多數使用者無法分辨 3020 是什麼。指出低置信度行(圖片中的橘色邊框和 ?),並請使用者在頁面上檢查它們。designable: false 的行沒有可用的 3D 幾何圖形,永遠無法用來搭建。pending_tasks > 0 表示庫存不完整:請說明。對於較長的庫存,請使用 filter: "usable" 或 "low_confidence" 以及 offset/limit 參數。
  2. edit_inventory {"changes": [...]},僅根據使用者的指示執行(切勿為了讓設計符合而修改): {"op": "set_quantity", "key": "3001|4", "quantity": 3}、 {"op": "remove", "key": ...}、 {"op": "confirm", "key": ...}(使用者已檢查低置信度行且確認無誤)、 {"op": "replace", "key": ..., "ldraw_part": "3002", "ldraw_color": 4}(實際上是另一個零件或顏色)、 {"op": "add", "ldraw_part": "3003", "ldraw_color": 14, "quantity": 2}、 {"op": "undo", "key": ...}、 {"op": "undo_all"}。每個變更都會報告 ok;告訴使用者哪些變更未被應用及其原因。使用者也可以在庫存頁面上進行相同的編輯。

設計

  1. 理解需求(第 3 節):主題、描述、參考圖片或沒有提供任何內容;在設計之前,先檢查庫存是否能滿足需求。
  2. design_guide:在一次對話中進行第一次設計之前,請閱讀完整指南。這是伺服器當前的規則手冊:檔案格式、座標、哪些連接器可以配對、驗證器的規則、工作範例以及如何使用多個零件。它也會返回 usable_quantity 和 target_percent。
  3. connectors {"parts": ["3001", "3023", ...]}(每次呼叫 1-40 個 LDraw 零件編號):您計劃使用的每個零件的邊界和每個連接器。所有零件的原點和連接器位置都必須從此處取得;切勿猜測。如果某個零件被報告為 unsupported,則無法使用。
  4. 編寫模型:一個 0 <title> 行,然後每個零件一行 1 <colour> x y z a b c d e f g h i <part>.dat,其中 <colour> 來自 ldraw_color,<part> 來自 ldraw_part(庫存中)。僅使用 designable: true 的行,且每個 key 在整個模型中的使用次數不得超過其 quantity;在提交前請先計數。沒有子模型,沒有 0 STEP 行。

驗證與改進

  1. submit_model {"ldr": "<整個檔案>", "title": "...", "brief": "<使用者的需求,使用他們的措辭>"};新增 "moc_id" 以提交相同模型的新版本,並僅在需要宣告可動零件時新增 "design"(請參閱指南)。它會等待最多 wait_s 秒(預設 45),並返回 status、issues(每個失敗會指出違反的規則、提示以及零件所在的檔案行和位置)、usage、resubmissions_left 以及,如果通過,還有 url 和兩張預覽圖片。如果 status 尚未最終確定(queued、checking、stepping),請呼叫 moc_status {"moc_id": ..., "wait_s": 50}。status 為 error 表示伺服器端故障,而非設計問題:使用相同的 moc_id 再次提交相同的模型。
  2. 失敗: 僅修正被指出的行(根據 connectors 重新計算位置,不要微調數值),然後使用 moc_id 再次提交。
  3. 通過: 查看兩張預覽圖和 usage,然後決定是否值得進行下一輪修改(第 4 節)。公開頁面始終顯示最後一次通過的版本,因此後續的失敗輪次不會將其下架。
  4. 報告: 向使用者提供頁面 url(告知這是公開的)、零件數和步驟數、所有警告、您搭建了什麼以及您無法實現的內容。通過僅表示模型在驗證器的模擬中在物理上是一致的,並不保證實際搭建一定穩固:請如實說明。

3. 設計需求

使用者可能會提供一個主題("一輛車")、詳細描述、參考圖片,或者什麼都不提供。

  • 首先檢查可行性。 在做出任何承諾之前,先查看庫存(形狀、顏色、數量)。一輛車需要輪子和車軸或能替代它們的零件;一棟房子需要足夠的磚塊來搭建牆壁以及用於屋頂的零件。清楚地向使用者說明哪些可以做到、哪些做不到,並提出零件確實允許的替代方案(更小的版本、其他主題、風格化的版本),而不是強行設計。
  • 描述: 保留使用者命名的特徵;說明您不得不省略或更改哪些特徵及其原因。
  • 參考圖片(僅在您能看見圖片時):使用使用者擁有的零件,基於其精神(形狀、比例和主要顏色)搭建一個模型。這不會是複製品;請說明。
  • 未提供任何內容: 選擇一個適合庫存的主題(其主要顏色和數量最多的形狀),並說明您選擇了什麼。
  • 將使用者的需求文字(使用他們的措辭)作為 brief 傳遞。將主題放在 title 中。
  • 庫存稀少。 如果可用零件少於約 60 個,或者庫存主要由許多顏色的單個零件組成,請在設計前告知使用者:只能搭建一個小型或抽象模型。建議(在庫存頁面上檢查後)確認低置信度行,並拍攝更多散落的零件照片。對已經計算過的零件進行新拍照會再次計數:建議拍攝尚未掃描的零件照片,或者之後使用 set_quantity 更正數量。

4. 使用大量零件,然後精煉

  • 目標: 使用至少 60% 的可用零件(usage.target_percent),除非使用者要求的是小東西。可用 = 可設計且非低置信度,或已確認。每次提交結果中的 usage.percent 顯示您的進度,usage.unused 列出剩餘的零件,從數量最多的開始。
  • 分階段進行。 第 1 版:主要結構(基底、主體、大的形狀)。後續版本會以較大的步驟添加細節:屋頂收尾、門窗、欄杆、裝飾、底板或地面。每個模型只有 5 次重新提交機會,因此每輪必須增加大量內容;不要為了一個單個零件而浪費一次機會。
  • 每個結果: 閱讀 usage 和 unused,並詢問哪些未使用的零件能讓主題變得更好。通過時,查看兩張預覽圖並修正看起來不對的地方:顏色隨機混合、頂部裸露的凸點、在主題應該是對稱的地方卻出現不對稱的形狀、一個扁平的盒子。指南的建議部分說明了如何處理。
  • 當模型已足夠好且達到目標、庫存無法再添加任何合理的東西、或重新提交次數已用完時停止。告知使用者最終的使用率。

5. 腳本備用方案

當 MCP 工具不可用時,請使用此腳本。需要 Python 3.8+,僅需標準函式庫,無需安裝任何套件。

python3 <此技能資料夾>/scripts/lego.py <command> [options] [arguments]

在 Windows 上使用 python 或 py -3。將選項放在照片清單之前。

盡量減少使用者的批准次數。 許多代理會要求使用者批准每個新的 shell 指令、網路主機以及在工作區外的寫入操作。因此:

  • 始終以完全相同的形式呼叫腳本,作為一個純指令:沒有 cd、沒有管線、沒有 &&、沒有環境前綴、沒有包裝腳本。這樣使用者可以一次性批准 "始終允許" python3 <path>/lego.py。在第一次出現批准提示時告訴使用者這件事,並提及 MCP 設定(第 1 節),該設定可以避免這些批准。
  • 腳本需要三樣東西,使用者都可以一次性允許:執行 lego.py、連線到 lego.py whoami 顯示的伺服器主機、以及讀寫 ~/.lego-parts/。
  • 不要重複執行相同的步驟,不要以短指令循環輪詢(請使用 --wait),也不要使用 curl 或您自己的程式碼呼叫伺服器。
  • 使用您的檔案寫入工具,以盡可能少的步驟編寫 model.ldr;避免使用一系列一次性腳本。
指令功能說明
scan [--no-wait] [--wait SECONDS] [--images] PHOTO...上傳 1-30 張照片(檔案、資料夾或 glob 模式),等待最多 480 秒(預設)以取得結果並儲存。--no-wait 在上傳後立即返回。
status [--wait SECONDS] [--images] [TASK_ID...]檢查待處理的任務(或指定的任務)一次,或在 SECONDS 秒內持續輪詢。儲存已完成任務的結果。
parts [--images]儲存已完成的待處理任務,然後將整個庫存(包含在庫存頁面上或使用 edit_inventory 所做的編輯)重新載入到 parts.json 中。
whoami顯示使用者 ID、伺服器和本機資料夾。無需網路。
moc guide [--parts-file PATH]儲存設計指南 moc/DESIGN_GUIDE.md 和您零件的連接器工作表 moc/connectors.txt。
moc submit [--title NAME] [--brief TEXT] [--design design.json] [--moc MOC_ID] [--parts-file PATH] [--no-wait] [--wait SECONDS] MODEL.ldr提交模型(連同 parts.json),等待最多 300 秒(預設)進行檢查,並輸出結果、零件使用率以及(如果通過)預覽連結。--moc 提交現有 MOC 的新版本;--brief 是使用者的需求。
moc status [--wait SECONDS] [MOC_ID]檢查待處理的 MOC 提交(或指定的 MOC)一次,或在 SECONDS 秒內持續輪詢。
mcp-config [--remote]輸出 MCP 設定(第 1 節)所需的 JSON。輸出僅為該 JSON;沒有 RESULT 行。
mcpMCP 橋接程式本身。由代理主機執行;請勿自行執行。

--images 還會將每個庫存行的 LDraw 圖片和照片裁剪圖下載到 images/ 資料夾中。

  • 長時間等待。 scan 可能執行 8 分鐘,moc submit 可能執行 5 分鐘。如果您的 shell 工具較早超時,請提高其超時時間,或傳遞較小的 --wait(例如 --wait 100),然後繼續使用 status --wait 100 / moc status --wait 100。在等待過程中被中斷是安全的:ID 會先儲存在 pending.json / moc/pending.json 中,之後任何來自任何代理的指令都可以收集它們。
  • 伺服器地址。 內建於下載的腳本中。如果某個指令顯示未設定伺服器,使用者必須設定 LEGO_PARTS_SERVER(例如 https://lego.groundrl.com,不包含 /skill/v1)。LEGO_PARTS_HOME 可以更改本機資料夾。
  • 網路被封鎖。 如果指令報告 HTTP 403 ... not from the LEGO server 或無法連線到伺服器,表示沙箱、代理或防火牆正在封鎖它。請詢問使用者是否可以在其瀏覽器中訪問該位址(如果使用 whoami 顯示)以排除防火牆規則。
  • MotorLib 模型。 如果 user 提交的模型包含列在 DESIGN_GUIDE.md 中的 MotorLib 零件,您必須提供一個 design.json,其結構如指南所述(電機類型、電機角度、端口綁定)。請使用 --design design.json 參數提交。

相關技能