LEGO 零件辨識與 MOC 設計
分兩個階段:
- 掃描。 使用者拍攝散落零件的照片;伺服器辨識這些零件並維護庫存(按使用者 ID)。
- 設計與驗證。 您從該庫存中設計一個模型(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 節)處理此任務;所有操作都能透過它完成。然後向使用者提供以下的一次性設定,這將免除每個指令的批准。
一次性設定(由使用者執行)
- 執行
python3 <此技能資料夾>/scripts/lego.py mcp-config(Windows 使用python)。它會輸出一個 JSON 區塊,且不會進行任何網路呼叫。 - 將該 JSON 提供給使用者,並要求他們將
lego-moc條目新增到代理的 MCP 設定的mcpServers區段中(設定頁面或 MCP 設定檔),然後重新啟動代理或重新載入其 MCP 伺服器。僅在使用者要求時,您才可以直接編輯主機的組態。 - 重新啟動後,代理會自行啟動橋接程式(
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 呼叫繞過它。
掃描
scan_photos{"paths": [...]}:此電腦上照片檔案、資料夾或 glob 模式的絕對路徑,每次呼叫 1-30 張照片(JPEG、PNG、WEBP、HEIC,每張 25 MB)。它會立即返回,每個照片有一個任務;它不會等待辨識完成。請將每個rejected和not_uploaded條目及其原因告知使用者。duplicate_photo條目表示該確切檔案先前已上傳過:它不會被重新辨識,且previous是第一次上傳的結果(其零件已存在於庫存中)。如果主機呼叫超時,上傳仍會繼續:請改為呼叫scan_status,不要重新上傳。如果有很多大照片,請分幾次呼叫,每次約 8 張。scan_status{"wait_s": 50}:重複直到pending為 0(辨識需要數分鐘;第一張照片可能需要等待 GPU 啟動)。將每個notices條目(pile_photo、no_pieces)逐字轉達給使用者,並指出失敗的照片及其error。如果長時間處於 pending 狀態,請告訴使用者還有多少張照片正在處理中,而不是無限期循環。
顯示與更正庫存
inventory:顯示庫存,包含概覽圖片(結果中的圖片)和inventory_url。向使用者展示圖片並提供連結;如果您有瀏覽器或預覽面板,請在那裡打開連結。切勿呈現純零件編號的表格:大多數使用者無法分辨3020是什麼。指出低置信度行(圖片中的橘色邊框和?),並請使用者在頁面上檢查它們。designable: false的行沒有可用的 3D 幾何圖形,永遠無法用來搭建。pending_tasks > 0表示庫存不完整:請說明。對於較長的庫存,請使用filter: "usable"或"low_confidence"以及offset/limit參數。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;告訴使用者哪些變更未被應用及其原因。使用者也可以在庫存頁面上進行相同的編輯。
設計
- 理解需求(第 3 節):主題、描述、參考圖片或沒有提供任何內容;在設計之前,先檢查庫存是否能滿足需求。
design_guide:在一次對話中進行第一次設計之前,請閱讀完整指南。這是伺服器當前的規則手冊:檔案格式、座標、哪些連接器可以配對、驗證器的規則、工作範例以及如何使用多個零件。它也會返回usable_quantity和target_percent。connectors{"parts": ["3001", "3023", ...]}(每次呼叫 1-40 個 LDraw 零件編號):您計劃使用的每個零件的邊界和每個連接器。所有零件的原點和連接器位置都必須從此處取得;切勿猜測。如果某個零件被報告為unsupported,則無法使用。- 編寫模型:一個
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行。
驗證與改進
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再次提交相同的模型。- 失敗: 僅修正被指出的行(根據
connectors重新計算位置,不要微調數值),然後使用moc_id再次提交。 - 通過: 查看兩張預覽圖和
usage,然後決定是否值得進行下一輪修改(第 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 行。 |
mcp | MCP 橋接程式本身。由代理主機執行;請勿自行執行。 |
--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參數提交。