host0

host0 是做什麼的？

host0 承載你的代理所建立的任何內容 — HTML、網站、附帶共享資料庫的應用程式、Markdown、PDF — 透過一個可以分享的連結，其輕鬆程度就像分享 Google 文件一樣。適用於任何代理。

核心概念是應用程式 (app)：發佈任意檔案或資料夾 — 靜態檔案的目錄，或一個能在瀏覽器中開啟的單一檔案（PDF、圖片、單一 HTML 頁面、影片、音訊、Markdown、CSV、文字；壓縮檔或其他僅供下載的類型會被拒絕 — 請先解壓縮 zip 檔案再發佈資料夾）— 並獲得一個即時 URL，其格式為 https://{slug}.host0.app/（本地開發：http://{slug}.localhost:3000/）。每個應用程式預設為私有 — 只有擁有者（已登入 host0）以及透過電子郵件被邀請的人可以開啟。若要開放給擁有連結的任何人（無需登入；非公開且永不索引），請選擇加入：--visibility link。--visibility public 則更進一步 — 在網路上公開，搜尋引擎可能會將其建立索引 — 這僅適用於使用者想要在搜尋中發現的內容。新應用程式的 URL 是隨機的（k3x9q2m7ta.host0.app）；當使用者想要一個更易讀的連結時，將其重新命名為易記的名稱（team-todo.host0.app）— 請參閱下方的「重新命名 URL」。

應用程式也可以保存共享資料：在 h0.json 中宣告記錄集合，其前端即可在自己的來源上獲得一個資料庫，無需編寫任何伺服器端程式碼。請參閱下方的「共享資料」— 這就是將頁面轉變為團隊共同使用的工具的關鍵。

目前文件

完整文件位於 https://host0.ai/docs — 當使用者詢問某個功能的運作方式、可能性，或在告知某功能不受支援之前，請閱讀這些文件。

API 也描述自身。機器可讀的索引：

curl -sS {base}/api/v1

它會回傳目前的端點清單、檔案限制，以及平台合約（host0 目前提供的服務）。請傳送 API 金鑰（-H "authorization: bearer $HOST0_API_KEY"），而 limits 和 plan 則會根據使用者的帳戶顯示；若無金鑰，則會顯示新帳戶的預設值。GET {base}/api/v1/account 會額外顯示該帳戶當月已使用的量。如果本技巧文字與即時 API 的行為不一致，請以即時 API 為準。

若要安裝或更新此技巧：npx skills add host0-ai/skills（支援 skills CLI 的任何代理；原始碼：https://github.com/host0-ai/skills），或取得兩個檔案：`https://host0.ai/skill.md` → 儲存為 SKILL.md，以及 https://host0.ai/publish.sh → 儲存為 scripts/publish.sh 放在旁邊，然後執行 chmod +x scripts/publish.sh。該指令稿的 URL 是 /publish.sh — 其中沒有 /scripts/ 目錄。

需求

• 必要的二進位檔：curl、jq（如果缺少其中任何一個，指令稿會顯示清楚的訊息並終止）
• 一個 API 金鑰，來自 $HOST0_API_KEY 或 ~/.host0/credentials。如果沒有，publish.sh 會為你啟動裝置登入 — 使用者在自己的瀏覽器中核准一個連結與代碼（請參閱「取得 API 金鑰」）
• 內建的輔助指令稿：./scripts/publish.sh
• 網路：對外 HTTPS 連線至 host0.ai（API）和 host0.app（上傳與即時應用程式）。在具有 egress 允許清單的沙盒中，如果請求總是因 SSL_ERROR_SYSCALL、代理錯誤、或連線被拒絕/重設而失敗，請告訴使用者要允許哪個網域 — 不要重複嘗試。
• 短暫性故障是可能發生的：某些雲端沙盒在連線至 host0.ai 時會遇到偶發的連線被重設 / SSL_ERROR_SYSCALL / 連線逾時。publish.sh 會自行重試這些情況（你會在 stderr 上看到 host0: network hiccup … retrying 2/4）— 只需讓它執行即可。如果你使用原始 curl 呼叫 API，請自行重試請求；對於 GET 和裝置登入輪詢，可以加上 --retry 3 --retry-all-errors，但切勿用於會建立資源的 POST。

發佈應用程式

./scripts/publish.sh {dir} [--name "my app"]
./scripts/publish.sh {file}  [--name "my app"]   # 單一檔案：pdf、圖片、頁面

在標準輸出上印出即時 URL（例如 https://k3x9q2m7ta.host0.app/ — 新應用程式會獲得一個隨機的 slug；--name 僅為顯示名稱）。

當你使用的不是 Claude Code、Codex、Cursor 或 Gemini CLI 時，請加上 --client {your-agent}（例如 --client claude-ai）— 指令稿會自動偵測這些。它只會標記部署統計資料。

在底層，這是一個三步驟流程：manifest → 上傳檔案 → 完成。在完成成功之前，應用程式不會上線。

檔案結構： index.html 必須位於你發佈的目錄的根目錄 — 該目錄的內容即成為網站根目錄。請發佈 my-site/ 目錄，其中包含 my-site/index.html，而不是包含 my-site/ 的父資料夾。

單一檔案： 直接傳遞檔案本身（./scripts/publish.sh report.pdf）— 無需 index.html。應用程式的根 URL 會提供該檔案（在瀏覽器分頁中，它會在 host0 的檔案檢視器中開啟 — 請注意下方的標記說明；?download 則取得原始檔案，而且 PDF 對於大型檔案仍支援範圍請求），也可以在 /{filename} 存取。每當使用者只想分享一個文件或圖片時，請使用此方式。

部署建置後的輸出，而非原始碼： 如果專案使用建置步驟（React/Vite/Next export、.ts/.tsx/.vue/.svelte），請先建置，然後發佈輸出目錄（dist/、build/、out/）。切勿發佈 node_modules/、package.json 或機密資料（.env、金鑰檔案）— API 會拒絕對伺服器程式碼和機密資料，並附上可操作訊息。

Beta 測試期間免費，附帶一個標記： host0 在 Beta 測試期間免費，且每個應用程式都使用免費方案，該方案會在每個 HTML 頁面的右下角固定顯示一個小的「Hosted on host0」標記（約 28px 高，離邊緣 12px），因此請在那個角落留一點空間（不要在那個角落放置固定的按鈕或聊天泡泡），也不要試圖隱藏它。在瀏覽器分頁中直接開啟的 PDF、圖片、影片、音訊或文字檔案（.txt、.csv、.md、.json）會在 host0 的檔案檢視器中開啟：檔案填滿視窗，其下方有一條細長的工具列（檔案名稱、下載、「Hosted on host0」），不會遮蓋檔案。原始檔案仍然會提供給 <img>/<video> 標籤、嵌入、fetch()、curl、連結預覽和搜尋引擎；在任何檔案 URL 上加上 ?download 會下載原始檔案。其他檔案（zip、字型、JS、CSS）會以其原始形式提供。使用者的方案是否顯示標記，可以透過（使用其金鑰的）GET {base}/api/v1 中的 plan.badge 得知。如果使用者詢問定價或移除標記：當索引中有 plans 列表時，它會列出每個方案的名稱、價格以及它改變了什麼（一個 badge: false 的方案會移除標記）— 請引導他們前往 {base}/pricing；當沒有任何 plans 列表時，host0 在 Beta 期間免費，付費方案可能稍後推出，並可能允許他們移除標記。

內建分析功能： host0 會計算每個應用程式的造訪次數，無需使用 Cookie — 一個微小的同源指令碼（/.h0/a.js）會加入到每個 HTML 頁面中，而開啟的 PDF 則在伺服器端計數。擁有者可以在儀表板的「分析」分頁中查看訪客、頁面、來源網站、國家和裝置，也可以透過 GET {base}/api/v1/apps/{app_id_or_slug}/analytics?period=7d（period：24h、7d、30d、90d、365d；其他值會回傳 400 invalid_period；可選的篩選器 page=/path、referrer=host 或 (direct)、country=DE 或 (unknown)、device、browser 會縮小每個數字的範圍 — 如果格式錯誤則回傳 400 invalid_filter），或透過 MCP 的 get_analytics 工具檢視。請勿移除該指令碼。如果應用程式設定了 Content-Security-Policy，請在 script-src 和 connect-src 中允許 'self'。當使用者詢問「有多少人開啟了它？」時，請從該端點回答。

更新應用程式

./scripts/publish.sh {dir} --slug {slug}     # 或 --app-id {uuid}

如果沒有使用旗標，指令稿會從已發佈目錄中的 .host0/state.json 解析應用程式（對於單一檔案：檔案旁邊的 .host0/state.json，以檔案名稱為鍵，因此一個資料夾中的兩個檔案會是兩個不同的應用程式），並且僅在沒有任何匹配時才會建立新應用程式。未變更的檔案會在伺服端跳過雜湊檢查 — 重新發佈一個大型網站，如果只編輯了一個檔案，則只會上傳一個檔案。

加上 --message "what changed"（最多 200 個字元）來為新版本加上註解 — 例如 --message "Added a due date column"。每當你發佈了使用者要求的變更時，都應該這麼做；這會是他們在版本列表中看到的內容。

版本與回滾

每個上線的發佈都會被編號為應用程式的一個版本（v1、v2…）— publish_result.version 是目前的版本，publish_result.previous_version 是它所取代的版本。較早的版本會根據方案保留一定天數 — GET {base}/api/v1（使用金鑰）→ limits.account.version_retention_days（如果為 0，則只保留線上版本）；較舊的版本會自動刪除。

當使用者想要還原一項變更（「回滾」、「放回舊的」、「那個搞壞了」），請還原一個較早的版本 — 它會在一分鐘內作為新版本重新上線供所有人使用，無需重新上傳：

# 列出它們，最新的優先 (version, live, message, client, restored_from_version, created_at)
curl -sS {base}/api/v1/apps/{app_id_or_slug}/versions \
  -H "authorization: bearer $HOST0_API_KEY"

# 還原版本 3（也接受 v3）；請求主體是可選的
curl -sS -X POST {base}/api/v1/apps/{app_id_or_slug}/versions/3/restore \
  -H "authorization: bearer $HOST0_API_KEY" \
  -H "content-type: application/json" \
  -d '{"message": "Back to before the redesign"}'

• 回應中包含 version（新的版本）、restored_from_version 和 previous_version — 告訴使用者「版本 3 已作為版本 9 重新上線」，以及還原版本 8 會撤銷這個動作。
• 在還原之前請先和使用者確認：它會改變每個開啟應用程式的人所看到的內容。
• 共享資料永遠不會因為還原而改變。被還原版本的 h0.json 決定哪些集合會被提供— 某些它未宣告的集合會被隱藏（但仍存在於匯出中），當還原一個較新的版本時，它會回來。
• 還原已上線的內容會回傳 already_live: true 且不會新增版本 — 請勿在迴圈中重試。
• 如果回傳 404 version_not_found：該版本已不再保留 — 請列出版本並提供一個可用的版本；切勿將較舊且已被修剪的版本視為可還原。如果是 409 version_not_restorable：其檔案已消失 — 請改為從使用者的檔案重新發佈。如果是 403 versions_not_in_plan：使用者的方案只保留線上版本 — 請重新發佈他們想要上線的檔案，並參閱「當錯誤有 upgrade_url 時」。
• 稍後可以使用 PATCH {base}/api/v1/apps/{app_id_or_slug}/versions/{n} 和 {"message": "…"}（或 null）來設定或清除註解。MCP 伺服器的 list_versions 和 restore_version 工具的功能與上述呼叫相同，應用程式儀表板中的「版本」分頁也有一個「還原」按鈕。

存取控制

一個 host0 應用程式一次使用一種可見性：

• private（預設）：只有擁有者和被邀請的電子郵件地址可以存取；訪客需要登入才能檢視。每個新應用程式都從此狀態開始。
• link — 「擁有連結的任何人」：任何擁有 URL 的人都可以檢視，無需登入。該應用程式是非公開的且永遠不會被索引（每個回應都帶有 X-Robots-Tag: noindex），而且其 URL 初始是隨機的 — 但連結會傳播，一個已重新命名、易讀的 URL 可能會被猜到 — 請將任何敏感內容保持私有。
• public — 「在網路上公開」：任何人都可以檢視且搜尋引擎可能會將其建立索引（應用程式本身的頁面會以 X-Robots-Tag: all 提供服務）。需要主動選擇加入，且每個帳戶有上限（403 public_app_limit_reached，回應主體中包含 max_public_apps）。僅在使用者希望應用程式在搜尋中被發現時使用 — 例如作品集、登陸頁面、文件、公開工具。切勿用於任何敏感內容。

當使用者想要一個任何人都能開啟的連結（一個可以四處發送的頁面、一個展示、一個共享的 PDF），請使用 --visibility link 發佈 — 這就是「讓它公開」或「分享連結」幾乎總是意味著的意思。只有在使用者說希望它在 Google / 搜尋結果中時才選擇 public；如果不確定，請詢問。共享資料在 link 和 public 下的運作方式相同。可以在發佈時使用 --visibility private|link|public 設定可見性，或隨時透過 API 設定：

curl -sS {base}/api/v1/apps/{app_id_or_slug} -X PATCH \
  -H "authorization: bearer $HOST0_API_KEY" \
  -H "content-type: application/json" \
  -d '{"visibility": "link"}'

如果轉為 public 回傳 public_app_limit_reached，請告訴使用者該帳戶已達到在網路上公開的應用程式數量上限，並提供 link 作為替代方案（擁有連結的任何人，不會被索引），或將另一個公開應用程式移回 link。

重新命名 URL

新應用程式的 URL 是一個隨機的 slug，例如 k3x9q2m7ta.host0.app。若要給予一個易讀的名稱，請先檢查該名稱，然後重新命名：

curl -sS {base}/api/v1/slugs/team-todo -H "authorization: bearer $HOST0_API_KEY"
# → {"slug":"team-todo","available":true}   （或 available:false 加上原因）

curl -sS {base}/api/v1/apps/{app_id} -X PATCH \
  -H "authorization: bearer $HOST0_API_KEY" \
  -H "content-type: application/json" \
  -d '{"slug": "team-todo"}'
# → {"app_id":"…","slug":"team-todo","url":"https://team-todo.host0.app/","old_slug":"k3x9q2m7ta",…}

Slug 必須是 1–63 個小寫字母、數字或連字號，且開頭或結尾不能是連字號。如果 slug 已被使用，會回傳 409 slug_taken；如果格式錯誤或屬於保留字，則回傳 422 invalid_slug。即時部署、記錄和分享設定會隨著應用程式一起移動，而 publish.sh 會持續更新它（它會追蹤應用程式 ID）。舊的 URL 會維持 30 天的 301 重新導向到新的 URL，並為該使用者保留，之後才會釋放 — 在重新命名人們已經擁有的連結之前，請先告知這一點。已刪除應用程式的 URL 也會保留 30 天（會回傳 404）。如果某個 slug 在過去 30 天內被另一個帳戶使用過，會回傳 409 slug_taken（「最近被另一個應用程式使用過」）。使用者也可以在應用程式儀表板頁面的「設定」分頁中重新命名它。

應用程式的顯示名稱（在儀表板和 GET /api/v1/apps 中顯示）與其 URL 是分開的 — 使用 PATCH {base}/api/v1/apps/{app_id} {"name": "Team todo"}（1–100 個字元）來更改；URL 不會改變。

分享

使用 POST /api/v1/apps/{app_id_or_slug}/shares（請求主體 {"emails": ["[email protected]"]}）透過電子郵件邀請人員；使用 DELETE /api/v1/apps/{app_id_or_slug}/shares/{email} 移除邀請。

新的分享會收到個別的邀請電子郵件，其中包含登入和註冊連結。請檢查回應中的 invite_delivery：accepted 表示郵件伺服器已接受…

（由於原文在「[truncated for translation]」處截斷，此處的翻譯為所提供內容的完整版本。）