跳至主要内容

外部容器建造者技能 (External Container Builder Skill)

本規範是為了讓外部 AI 能夠在「無原始碼存取權」的情況下，開發出能與蛋蛋村（Egg Village）完美對接的獨立遊戲容器。

1. 靈魂數據規格 (UPS v1.0 JSON Schema)​

容器必須能夠解析以下標準的靈魂數據包。這是開發者唯一的資料來源：

{
  "version": "1.0",
  "homeUUID": "string (家園唯一識別碼)",
  "sequenceNumber": "number (序號，回歸時必須遞增)",
  "pet": {
    "name": "string",
    "level": "number",
    "element": "FIRE | WATER | EARTH | WIND | LIGHT | DARK",
    "vocation": "WARRIOR | MAGE | ASSASSIN",
    "seed": "string (視覺渲染核心種子)",
    "stamina": { "current": 80, "max": 100 }
  },
  "dna": { "seed": "string (同 pet.seed)" },
  "origin_url": "string (發起端的網址，結算後應跳轉回此處)"
}

2. 傳輸層演算法 (The Wire Protocol)​

由於開發者無法使用專案內的 urlProtocol.ts，AI 必須自行實作以下演算法：

A. URL-Safe Base64 解碼​

  1. 接收字串。
  2. 將 - 替換回 +，_ 替換回 /。
  3. 根據長度補回 = 填充符（(4 - str.length % 4) % 4 次）。
  4. 執行 Base64 解碼並轉為 UTF-8 JSON 物件。

B. 數位簽章驗證 (Ed25519)​

  • 演算法: Ed25519。
  • 校驗對象: 排除 origin.signature 欄位後的完整 JSON。
  • 公鑰獲取: 若為核心容器發送，預設信任 homeUUID 匹配之本地存檔（靈魂遠征模式）。

3. P2P 握手訊息結構 (P2P Message Schema)​

透過 WebRTC (PeerJS) 通訊時，訊息必須符合以下 JSON 格式：

  • 遠征邀約 (EXPEDITION_OFFER): { "type": "EXP_OFFER", "senderId": "string", "payload": { UPS_DATA } }
  • 接收確認 (EXPEDITION_ACK): { "type": "EXP_ACK", "senderId": "string", "payload": {} }

4. 回歸結算規則 (The Exfiltration Rule)​

當容器完成任務欲將靈魂送回「家」時，必須執行以下動作：

  1. 序號更新: sequenceNumber 必須 +1。
  2. 獎勵封裝: 在 UPS 根目錄新增 rewards: { xp: number, gold: number } 欄位。
  3. 打包: 執行 URL-Safe Base64 編碼。
  4. 跳轉: 導向至 origin_url + "?s=" + TOKEN。

5. 視覺渲染指南 (Rendering via Seed)​

容器不具備 PetRenderer 原始碼，必須依據 pet.seed 進行渲染：

  • 方案 A (自研): 依據 Seed 字串解析出寵物顏色、花紋與裝飾。
  • 方案 B (外掛): 引用蛋蛋村提供的 CDN 渲染腳本： <script src="https://sdk.egg-village.com/pet-renderer.v1.js"></script> 調用方式：new EggPet({ seed: data.pet.seed, target: '#canvas-id' })