發佈者技能
將 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 套件 | 發佈並建置 APK | zip 路徑、專案名稱 |
| 為已發佈的專案建置 APK | 建置 APK | 專案 ID;必要時使用專案列表 |
| 將應用程式設為私有/公開、新增/移除存取密碼 | 變更可見性 | 應用程式網址、目標可見性(設為私有時可選密碼) |
| 顯示我的專案、列出已發佈的專案 | 列出專案 | 如果有令牌則無需詢問 |
| 登入、註冊、帳戶設定 | 登入/註冊 | 使用者名稱和密碼 |
如果意圖不明確,請簡短地問一個問題:「只是要發佈它,還是也要發佈並建置 Android APK?」
發佈對話流程
當用戶表達發佈、部署、啟動、分享應用程式、產生存取連結等意圖時,必須進入此流程。
有限狀態機的一般原則
- 進入流程時,首先執行
S-1(版本檢查,非阻塞),然後依序進行S0 -> S1 -> S2 -> S3 -> S4。 - 不允許跳過步驟(
S-1除外)。 - 不能在單次請求中詢問多個欄位。
- 用戶已明確提供的資訊可以記錄,無需重複詢問。
- 當用戶的回應含糊不清時,僅針對當前欄位進行一次追問。
- 只有在當前步驟完成後,才能進入下一步。
- 如果需要等待用戶輸入,請不要在回應的結尾附加說明、建議或下一步的預覽。
S-1:版本檢查(發佈流程的第一個節點,非阻塞)
進入發佈流程時,在 S0 之前執行版本自我檢查。此步驟不屬於 <HARD-GATE> 阻塞規則:無論結果如何——即使端點無法訪問——都要繼續。絕不因版本問題中斷發佈。
步驟:
-
讀取本地端技能版本:此檔案 frontmatter 中的
version欄位。 -
查詢最新平台版本(無需登入):
curl -s https://ai-pub.pushwebly.com/api/skill/latest-version回應的
data包含:version(最新版本)、downloadUrl(跨平台文件套件,解壓即可使用)、downloadUrlWindows(Windows 安裝程式 .exe)和downloadUrlMac(macOS 安裝程式 .zip)。 -
比較本地端
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(更新不影響當前發佈)。 - Windows → 使用
-
本地端版本等於或更新:保持沉默並繼續。
-
請求失敗/逾時/無法解析:靜默跳過,直接進入
S0,不要顯示錯誤。
-
-
在所有情況下,接下來繼續執行
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=publicvisibility=private且用戶已選擇自訂密碼或系統產生的密碼
發佈參數:
公開應用程式:
{
"visibility": "public"
}
私有應用程式,自訂密碼:
{
"visibility": "private",
"access_password": "a1b2c3"
}
如果用戶未指定可見性,則預設為 public。私有存取密碼必須符合 ^[A-Za-z0-9]{6}$;否則要求提供有效密碼或讓後端產生一個。
令牌處理
所有發佈 API 都需要 Bearer 令牌。
使用以下順序:
- 如果用戶在對話中提供了令牌,則直接使用。
- 如果
~/.publisher/config.json存在,讀取儲存的使用者名稱/密碼並重新登入以重新整理令牌。 - 否則詢問使用者名稱和密碼。登入端點會自動註冊新帳戶。
登入/註冊端點:
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>"
發佈前檢查
在發佈之前:
- 確認檔案存在且副檔名為
.zip。 - 確認 zip 檔案中包含
index.html或index.htm。 - 如果 zip 中有巢狀目錄,請確認可以找到入口檔案。
- 確認專案名稱不為空。
- 確認有可用的有效令牌。
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 路徑相同。
重試規則:
- 首次請求始終發送到主主機。
- 如果主主機在 15 秒內未回應,重試一次,時間再延長 15 秒。
- 如果仍然失敗,嘗試備用主機,無需額外時間限制(預設 60 秒)。
- 如果備用主機也失敗,請向用戶解釋目前的發佈平台暫時無法訪問。