Community寫作與編輯github.com

發佈者技能/發佈者

將 HTML 前端遊戲發佈到 AI Game MCP 平台。

發佈者 是什麼?

此技能用於將 HTML 前端專案發佈到指定的發佈平台,並可選擇性地將其打包成 Android APK 檔案。它支援多種平台,包括 Claude Code、Cursor、Codex 等,並透過 MCP 工具或 HTTP API 進行操作。技能的核心是一個嚴格的有限狀態機發佈流程,引導用戶逐步完成版本檢查、帳戶驗證、應用程式可見性設定以及最終的發佈或 APK 建置。流程會嚴格按照步驟執行,不會跳過或同時詢問多個資訊,確保操作的正確性與安全性。它還處理令牌管理、專案清單檢視、可見性切換等功能。

相容平台~Claude Code✓Codex CLI~Cursor
npx skills add publisher-skill/publisher

Installed? Explore more 寫作與編輯 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

在你喜歡的 AI 中提問

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

說明文件

發佈者技能

將 HTML 前端專案發佈到發佈平台,並可選擇性地將其打包成 Android APK。

平台網址:

https://pushwebly.com

在與用戶的對話中,請使用「專案」一詞。規範的 API 路徑為 /api/projects,規範的工具名稱為 project_*。已棄用的 game_* 別名和 gameId 回應欄位可能仍會出現;請將 gameId 視為專案 ID。

Codex 執行規則

  • 如果當前環境中存在已掛載的 project_* MCP 工具,則優先使用它們。
  • 如果未掛載遠端 MCP 工具,則使用 curl 和 HTTP API。
  • 不需要 Python。如果存在可選腳本,僅供 CLI/CI 用戶使用。
  • 僅詢問確實缺失的資訊:憑證、zip 路徑、專案名稱、公開/私有可見性,或私有存取密碼偏好。
  • 切勿將憑證寫入專案 zip 或儲存庫檔案。取得用戶同意後,僅將其儲存在用戶本地的 ~/.publisher/config.json 檔案中。
  • 在 Windows/PowerShell 上,請使用臨時 JSON 檔案來存放請求主體,而不是在 shell 中跳脫內聯 JSON。

意圖對應

用戶意圖動作需詢問的缺失資訊
發佈、上傳、上線發佈專案zip 路徑、專案名稱
製作可安裝的手機應用程式、APK、Android 套件發佈並建置 APKzip 路徑、專案名稱
為已發佈的專案建置 APK建置 APK專案 ID;必要時使用專案列表
將應用程式設為私有/公開、新增/移除存取密碼變更可見性應用程式網址、目標可見性(設為私有時可選密碼)
顯示我的專案、列出已發佈的專案列出專案如果有令牌則無需詢問
登入、註冊、帳戶設定登入/註冊使用者名稱和密碼

如果意圖不明確,請簡短地問一個問題:「只是要發佈它,還是也要發佈並建置 Android APK?」

發佈對話流程

當用戶表達發佈、部署、啟動、分享應用程式、產生存取連結等意圖時,必須進入此流程。

有限狀態機的一般原則

  • 進入流程時,首先執行 S-1(版本檢查,非阻塞),然後依序進行 S0 -> S1 -> S2 -> S3 -> S4。
  • 不允許跳過步驟(S-1 除外)。
  • 不能在單次請求中詢問多個欄位。
  • 用戶已明確提供的資訊可以記錄,無需重複詢問。
  • 當用戶的回應含糊不清時,僅針對當前欄位進行一次追問。
  • 只有在當前步驟完成後,才能進入下一步。
  • 如果需要等待用戶輸入,請不要在回應的結尾附加說明、建議或下一步的預覽。

S-1:版本檢查(發佈流程的第一個節點,非阻塞)

進入發佈流程時,在 S0 之前執行版本自我檢查。此步驟不屬於 <HARD-GATE> 阻塞規則:無論結果如何——即使端點無法訪問——都要繼續。絕不因版本問題中斷發佈。

步驟:

  1. 讀取本地端技能版本:此檔案 frontmatter 中的 version 欄位。

  2. 查詢最新平台版本(無需登入):

    curl -s https://ai-pub.pushwebly.com/api/skill/latest-version
    

    回應的 data 包含:version(最新版本)、downloadUrl(跨平台文件套件,解壓即可使用)、downloadUrlWindows(Windows 安裝程式 .exe)和 downloadUrlMac(macOS 安裝程式 .zip)。

  3. 比較本地端 version 與回傳的 version。

    比較規則:版本號為 major.minor.patch。從左到右逐段以整數比較——先比較主版本號,再比較次版本號,最後比較修訂號;缺失的段以 0 補齊(1.1 視為 1.1.0)。以整數比較,而不是字串比較:1.10.0 大於 1.9.0(第二段 10 > 9);字串比較會出錯。升序範例:1.0.0 < 1.0.9 < 1.1.0 < 1.2.0 < 1.10.0 < 2.0.0。

    • 本地端版本較舊(本地端的整數段序列小於回傳的版本):在繼續之前,你必須向用戶輸出更新通知,並且通知中必須包含實際的下載網址(這不會阻塞發佈,但通知不可省略)。根據用戶的作業系統選擇下載網址:

      • Windows → 使用 downloadUrlWindows
      • macOS → 使用 downloadUrlMac
      • 作業系統未知,或對應欄位為空 → 回退到通用的 downloadUrl

      通知文字(使用與用戶交談時相同的語言輸出——如果他們寫中文則用中文,如果寫英文則用英文;不要硬編碼一種語言;以下僅為英文範例模板;將網址替換為實際選擇的內容;將下載網址寫成可點擊的 Markdown 連結 [URL](URL)——不要用反引號將其包裹為內聯程式碼,否則用戶無法點擊;絕不留佔位符,絕不提及「有新版本存在」但不給出連結):

      注意:有一個較新的發佈者技能版本 <version> 可用(您目前使用的是 <local version>)。下載:https://ai-pub.pushwebly.com/downloads/AI_Publisher_skill.exe(更新不影響當前發佈)。

    • 本地端版本等於或更新:保持沉默並繼續。

    • 請求失敗/逾時/無法解析:靜默跳過,直接進入 S0,不要顯示錯誤。

  4. 在所有情況下,接下來繼續執行 S0。因為此步驟僅通知(無輸入,非阻塞),「每個回覆最多一個面向用戶的問題」規則不適用於它——版本通知可以與第一個 S0 問題共享同一個回覆。


S0:檢查帳戶狀態

首先,檢查是否已有可用的令牌/本地憑證。

  • 如果已有帳戶憑證:前往 S2。
  • 如果沒有帳戶憑證:進入 S1_USERNAME。
  • 如果無法檢查帳戶狀態:詢問用戶是否已有發佈帳戶。

向用戶提問:

我需要先確認發佈帳戶:您是否已有可用的帳戶或令牌?

用戶回答:

  • 是:要求用戶提供或確認令牌/登入憑證,然後前往 S2。
  • 否:進入 S1_USERNAME。

S1:註冊與登入流程

S1_USERNAME:收集註冊使用者名稱

如果沒有使用者名稱,只需詢問:

請提供要註冊的使用者名稱。

收到使用者名稱後,將其記錄為 username 並進入 S1_PASSWORD。

S1_PASSWORD:收集註冊密碼

如果沒有密碼,只需詢問:

請提供註冊密碼。

收到密碼後,將其記錄為 password 並進入 S1_VALIDATE。

S1_VALIDATE:聯合驗證

只有在同時擁有 username 和 password 後,才能呼叫後端介面進行聯合驗證。

驗證通過:

  • 建立帳戶
  • 完成登入
  • 提示:註冊並登入成功
  • 進入 S2

驗證失敗:

  • 顯示後端回傳的具體錯誤原因
  • 僅詢問需要修正的項目
  • 不要終止註冊流程

S2:詢問應用程式可見性

如果尚未明確定義公開或私有狀態,只需詢問:

這個應用程式是公開的嗎?公開表示任何人都可以透過連結存取;私有則需要一個 6 位數的存取密碼。

用戶回答:

  • 公開 / 是 / public:記錄 visibility=public,進入 S4
  • 私有 / 否 / private:記錄 visibility=private,進入 S3
  • 不清楚:繼續僅詢問此項目

S3:私有存取密碼

如果 visibility=private,需要詢問是否自訂密碼,僅詢問:

您想自訂一個 6 位數的存取密碼嗎?您也可以回覆「系統產生」。

用戶回答:

  • 提供密碼:驗證必須是 6 位數字或字母;通過後,記錄 accessPassword=<用戶密碼> 並進入 S4
  • 回覆系統產生 / 不需要 / 隨機:不傳遞 accessPassword,讓後端產生,並進入 S4
  • 密碼格式錯誤:僅提示格式要求並重新詢問密碼

S4:執行發佈

僅在滿足以下條件之一時才允許呼叫發佈介面:

  • visibility=public
  • visibility=private 且用戶已選擇自訂密碼或系統產生的密碼

發佈參數:

公開應用程式:

{
  "visibility": "public"
}

私有應用程式,自訂密碼:

{
  "visibility": "private",
  "access_password": "a1b2c3"
}

如果用戶未指定可見性,則預設為 public。私有存取密碼必須符合 ^[A-Za-z0-9]{6}$;否則要求提供有效密碼或讓後端產生一個。

令牌處理

所有發佈 API 都需要 Bearer 令牌。

使用以下順序:

  1. 如果用戶在對話中提供了令牌,則直接使用。
  2. 如果 ~/.publisher/config.json 存在,讀取儲存的使用者名稱/密碼並重新登入以重新整理令牌。
  3. 否則詢問使用者名稱和密碼。登入端點會自動註冊新帳戶。

登入/註冊端點:

curl -s -X POST https://ai-pub.pushwebly.com/api/auth/login-or-register \
  -H "Content-Type: application/json" \
  -d @login.json

將 login.json 寫入為:

{"username":"alice","password":"plain-text-password"}

使用回應中的 data.token 作為:

Authorization: Bearer <TOKEN>

使用後刪除臨時登入檔案。

可選的本地憑證檔案:

{
  "baseUrl": "https://ai-pub.pushwebly.com",
  "username": "alice",
  "password": "plain-text-password",
  "authorization": "Bearer <TOKEN>",
  "userId": 1
}

在 Linux/macOS 上,寫入後設定權限為 600。遇到 401 錯誤時,透過重新登入重新整理令牌一次,然後重試失敗的操作一次。

驗證令牌:

curl -s https://ai-pub.pushwebly.com/api/auth/verify-token \
  -H "Authorization: Bearer <TOKEN>"

發佈前檢查

在發佈之前:

  1. 確認檔案存在且副檔名為 .zip。
  2. 確認 zip 檔案中包含 index.html 或 index.htm。
  3. 如果 zip 中有巢狀目錄,請確認可以找到入口檔案。
  4. 確認專案名稱不為空。
  5. 確認有可用的有效令牌。

HTTP 操作

發佈專案

公開:

curl -s -X POST https://ai-pub.pushwebly.com/api/projects/publish \
  -H "Authorization: Bearer <TOKEN>" \
  -F "project_name=demo" \
  -F "[email protected]"

私有(可選自訂密碼):

curl -s -X POST https://ai-pub.pushwebly.com/api/projects/publish \
  -H "Authorization: Bearer <TOKEN>" \
  -F "project_name=demo" \
  -F "[email protected]" \
  -F "visibility=private" \
  -F "access_password=a1b2c3"

對於私有應用程式,省略 access_password 可讓後端產生密碼。始終將回應中的最終 accessPassword 轉達給用戶。

列出專案

curl -s https://ai-pub.pushwebly.com/api/projects/my \
  -H "Authorization: Bearer <TOKEN>"

變更可見性(公開 <-> 私有)

切換已發佈的應用程式在公開和私有之間。輸入是應用程式網址;後端從中解析應用程式識別碼並驗證該應用程式屬於當前用戶——你只能更改自己的應用程式,不能更改他人的。

curl -s -X PATCH https://ai-pub.pushwebly.com/api/projects/visibility \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d @visibility.json

寫入 visibility.json(設為私有):

{"url":"https://ai-pub.pushwebly.com/play/aB3xYz/","visibility":"private","accessPassword":"a1b2c3"}

或設為公開(不需要密碼;舊密碼將被清除):

{"url":"https://ai-pub.pushwebly.com/play/aB3xYz/","visibility":"public"}

accessPassword 是可選的,僅在切換到私有時使用(6 位數字或字母;如果省略則自動產生)。回應的 data 包含最終的 visibility、url,以及當設為私有時的 accessPassword。將私有應用程式的網址和密碼分開傳達,切勿使用 ?pwd=。如果找不到應用程式、已刪除或屬於其他用戶,請說明具體原因以及只能更改自己的應用程式。

為現有專案建置 APK

curl -s -X POST https://ai-pub.pushwebly.com/api/apk/build \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d @build-apk.json

將 build-apk.json 寫入為:

{"projectId":12}

使用回應中的 data.apkUrl 作為 APK 下載網址。

發佈並建置 APK

這是當用戶想要一個可安裝的 Android 應用程式時推薦的操作。

curl -s -X POST https://ai-pub.pushwebly.com/api/apk/publish-and-build \
  -H "Authorization: Bearer <TOKEN>" \
  -F "project_name=airplane-war" \
  -F "[email protected]"

對於私有應用程式,請加上:

-F "visibility=private" -F "access_password=a1b2c3"

省略 access_password 以自動產生。

預期的回應欄位可能包括:

{
  "gameId": 12,
  "projectName": "airplane-war",
  "playUrl": "https://ai-pub.pushwebly.com/play/aB3xYz/",
  "status": "enabled",
  "apkUrl": "https://ai-pub.pushwebly.com/api/apk/download/airplane-war_aB3xYz.apk",
  "apkFileName": "airplane-war.apk",
  "accessPassword": "a1b2c3"
}

始終將 playUrl 和 accessPassword 轉達給用戶。將回應中的 gameId 視為 projectId。

備用平台網域

主 API 主機:https://ai-pub.pushwebly.com。

如果檢測到網路問題(解析、連線、TLS 錯誤),備用主機為 https://ai-pub2.pushwebly.com。所有 API 路徑相同。

重試規則:

  1. 首次請求始終發送到主主機。
  2. 如果主主機在 15 秒內未回應,重試一次,時間再延長 15 秒。
  3. 如果仍然失敗,嘗試備用主機,無需額外時間限制(預設 60 秒)。
  4. 如果備用主機也失敗,請向用戶解釋目前的發佈平台暫時無法訪問。

相關技能