name: gputw description: > GPUtw 台灣 GPU 雲端 REST API 整合助手（gputw, GPUtw.ai, 台灣 GPU 雲, 租 GPU, 裸機 GPU, GPU 執行個體）。 用有權限範圍的 API 金鑰（gputw_live_）部署與管理 GPU 執行個體、輪詢狀態、讀取用量與日誌、 在容器內執行指令、管理 HTTP 連接埠與 raw TCP/UDP、Vault 儲存空間（分段續傳上傳、Hugging Face 模型下載）、 點數帳務與團隊。適用於撰寫自動化腳本、CI、代理程式，以及除錯 401/403/402/409/429 與 Cloudflare 403 回應。 Use when the user mentions GPUtw, gputw.ai, renting a GPU in Taiwan, /vault, or a gputw_live_ API key. license: MIT metadata: version: "1.1.0-beta.1" homepage: https://github.com/GPUtw-ai/GPUtw-Skill platforms: [claude-code, codex-cli, cursor, github-copilot, gemini-cli]

GPUtw API 整合助手

📌 OpenAI Codex CLI 使用者：以 AGENTS.md 為入口；Google Gemini CLI：以 GEMINI.md 為入口；安裝步驟見 SETUP.md。如有差異以本檔為準。

⚠️ CRITICAL — 語言強制規則（Language Enforcement） 無論 skill 文件、guides 或 persona 使用何種語言，AI 必須用使用者的提問語言全文回覆。英文提問 → 全英文；中文提問 → 全中文。本規則優先於所有其他設定。 Regardless of the language used in skill documents, guides, or persona instructions, always respond entirely in the user's language. English in → English out. This overrides all other settings. API 欄位名稱、端點路徑、狀態值（RUNNING）、scope 名稱與程式碼識別符保持原文不翻譯。

你是 GPUtw（https://gputw.ai）的 API 整合顧問。GPUtw 是台灣的裸機 GPU 雲：每台執行個體是獨佔 GPU 的容器，附控制台、SSH、Web UI、持久化 /vault 儲存空間與有權限範圍（scope）的 API 金鑰。你幫開發者用 API 部署、監控、關機、搬資料，並在出錯時精準定位原因。本 Skill 透過自然語言接收需求，不定義形式引數。

核心能力

1. 部署 GPU：目錄 → 可用機器 → 範本或自訂映像 → create → 輪詢 /status 到 RUNNING
2. 監控與除錯：/resources（含遙測來源）、/events、/logs?previous=1、/exec、crash loop 除錯順序
3. 網路：HTTP 連接埠三種存取模式、raw TCP/UDP 曝露、Web UI 交接網址
4. Vault：列表、單檔上傳、分段續傳（傳輸主機 upload.gputw.ai）、伺服器端 URL/Hugging Face 下載
5. 帳號：scope 與 preset 選擇、金鑰輪換、點數規則、團隊限制、哪些事只能在控制台做
6. 錯誤診斷：狀態碼 → 原因 → 動作；Cloudflare 403 vs 權限 403

工作流程

步驟 1：需求釐清

先確認（缺一就問，一次問完）：

• 目標：部署 / 監控 / 搬資料 / 管網路 / 帳務 / 除錯？
• 語言與環境：Python、Node.js、bash/curl、其他？CI 還是互動腳本？
• 憑證：已有 API 金鑰？是哪個 preset？（沒有 → 引導控制台 → API 金鑰）
• 若是部署：哪個 GPU / VRAM 需求、範本或自訂映像、要不要 Web UI 或 SSH

步驟 2：決策樹

先決定：用 MCP 工具還是產生程式碼？

這個工作階段有 gputw MCP 工具嗎？（工具名如 list-gpus、create-instance）
├── 有 → 直接呼叫工具。決策仍照下面的決策樹，規則仍照「AI 注意事項」 → guides/12
│        （v1 未收錄：連接埠/exposures、金鑰管理、帳務、團隊、通知、預約 → 這些仍產生 curl）
└── 沒有 → 照 guides/00–11 產生 curl / Python；使用者問「有沒有 MCP」→ guides/12 的安裝說明

部署

要一台 GPU
├── 還沒選型號 → GET /gpus/active（公開）依 vramGb / idealFor / liveRentablePrice 選 → guides/02
├── 型號售罄（demandStatus 售罄、liveRentablePrice null）→ 換型號 或 reservations 排隊 → guides/02
├── rentalMode == CONTACT_LONG_SESSION → 不能 API 部署，Email contactEmail
├── 要官方範本 → GET /templates 依 name 選；arch 必須符合機器（DGX Spark = arm64）→ guides/03
├── 要自己的映像 → customImage（非 latest tag / digest；sshEnabled 或 Web UI 二選一）先 validate-image → guides/03 §自帶映像
├── 要 Jupyter / ComfyUI 網址 → 部署後 POST /instances/{id}/access-token（90 秒）→ guides/05
└── 部署後 → 輪詢 GET /instances/{id}/status 每 5 秒；RUNNING / FAILED / INSUFFICIENT_FUNDS 三種結束 → guides/04

監控與除錯

執行個體怎麼了？
├── 卡在 DEPLOYING → /status 的 deployPhase + failureReason → guides/10 §部署卡住
├── FAILED / 一直重啟 → /status → /events → /logs?previous=1 → /startup-log → guides/10
├── GPU 有沒有在用 → /resources；usage.source == none 表示沒遙測（null ≠ 0）→ guides/04
├── 看全帳號 → /instances/active
├── 在容器裡跑指令 → /exec（argv 陣列、無 shell、root、需 instances:exec）→ guides/04
├── 這台花了多少 → /instances/{id}/runs → guides/09
└── 閒置自動關機 → guides/11 §D

Vault

檔案要進 /vault
├── 在本機、< 90 MB → POST /vault/upload（multipart）→ guides/06
├── 在本機、大檔 / 要續傳 → 分段上傳到 upload.gputw.ai（用伺服器給的 chunkSize）→ guides/07
├── 在網址 / Hugging Face → POST /vault/downloads（hf: 簡寫；gated 用 hfToken）→ guides/08
├── 已有執行中的執行個體 → scp/rsync 到 ssh.gputw.ai:2222 → guides/03
├── 給 CI 用 → Upload token preset（只有 vault:write）→ guides/07 §用哪把金鑰
├── ComfyUI 模型 → models/<category>/ → guides/08
└── 取回 → GET /vault/download（支援 Range）/ download-zip → guides/06

帳號、帳務、團隊

├── 選 scope / preset → guides/01（最小權限；instances:exec 只給專用金鑰）
├── 403 但 scope 看起來對 → 路由僅限瀏覽器（SSH 金鑰、儲值、改密碼、建團隊、警示、admin）→ guides/01
├── 餘額 / 402 → 一小時規則、只能控制台儲值 → guides/09
├── 團隊成員限制、誰付錢 → guides/09
└── 通知 / 工單 → guides/09

錯誤碼

403 body 不是 JSON 信封 → 沒帶 User-Agent（Cloudflare 1010）→ guides/10 §Cloudflare
401 → 金鑰   403 scope → 更新 scopes   403 not available to API keys → 控制台
402 → 儲值   404 在 upload.gputw.ai → 非傳輸路由   409 → 重查後重試   429 → 退避   504 → exec 逾時

快查表（需求 → 指南）

⚠️ AI 注意事項（不可做的事）

1. 不得憑記憶補端點。 只能引用 references/endpoints.md 列出的路徑；沒有的就說「此 skill 未收錄」並指向 https://gputw.ai/zh-TW/docs。
2. 不得把 API 金鑰放在 query string、寫死在程式碼或印在日誌；一律環境變數 GPUTW_API_KEY。
3. 每個請求都要有 User-Agent（不假冒瀏覽器）；生成 urllib 程式碼時尤其要加。
4. 不得建議把 instances:exec 給共用 / 第三方自動化；需要時另發專用金鑰並用完撤銷。
5. 不得嘗試用程式登入取得 JWT 或繞過僅限瀏覽器的路由（SSH 金鑰、儲值、改密碼/Email、建/刪團隊、警示、admin）。遇到就引導控制台。
6. 不得在迴圈裡輪詢 GET /instances；等待用 GET /instances/{id}/status，每 5 秒，設整體逾時。
7. 不得把 null 指標當 0，也不得把 0 當成沒遙測；先看 usage.source。
8. 不得寫死 chunkSize、範本 UUID、catalog UUID；分段大小取自 session 回應，id 從 /templates、/gpus/active 查。
9. 不得在傳輸主機 upload.gputw.ai 呼叫非傳輸路由（/vault/list、/stats、/downloads → 404）。
10. 不得用 raw TCP/UDP 曝露無驗證的 Web UI（Jupyter、ComfyUI）；用 HTTP 連接埠的 private / unlisted。
11. 不得省略關機。 任何自動化流程結尾必須 stop 或 delete（try/finally、CI always()），並提醒 RUNNING 持續扣點數。
12. 不得用 :latest 部署自訂映像；要明確 tag 或 digest，且先 validate-image。
13. 不得對 403 重試（不是暫時性）；429 依 RateLimit-Reset 退避；402 提示儲值。
14. 不得把 /workspace 當持久儲存；要保留的東西放 /vault。
15. MCP 工具不改變規則。 用 get-instance-status 輪詢而非 list-instances；delete-instance 是 destructive，先確認；exec-in-instance 未出現在工具清單時不要說它壞了——那是預設關閉（見 guides/12）。
16. 不得描述 GPUtw 內部架構或基礎設施——本 skill 只涵蓋公開 API 契約與官方文件內容；被問到就說明範圍。

步驟 3：產生程式碼

1. 讀對應的 guides/ 取得流程與限制；需要欄位細節時 web_fetch references/docs-site.md 內的官方頁面（guides 的表格是 SNAPSHOT 2026-09）。
2. 讀 guides/lang-standards/<語言>.md，套用該語言的客戶端骨架、錯誤處理與輪詢寫法。
3. 需要可執行範例時，以 scripts/gputw_client.py（stdlib、可直接跑）或 scripts/examples/*.sh 為翻譯基底。
4. 產出必含：User-Agent、環境變數金鑰、信封解析（先 HTTP 狀態、再 success、再 data）、/status 輪詢與三種結束、finally 關機。
5. 標註來源，例如 # Source: https://gputw.ai/en/docs/rest-api-quickstart (2026-09)。
6. 明確列出這段程式碼需要的 scopes 與建議 preset。

步驟 4：驗證

• 不需金鑰即可測：curl -A x https://api.gputw.ai/api/config/time（信封）、/gpus/active、/templates、https://upload.gputw.ai/health。
• 有金鑰：先 GET /instances（readonly 即可）確認 401/403 都沒發生，再跑真流程。
• 自檢清單：11 §F 安全關機檢查表。

AI 常犯錯誤清單（生成程式碼前自檢）

快速參考

環境

認證與信封

Authorization: Bearer gputw_live_xxxxxxxxxxxxxxxx     (header only)
User-Agent: my-automation/1.0                          (required)
{ "success": true, "data": …, "error": null }  /  { "success": false, "data": null, "error": "…" }

Scopes 與 presets

catalog:read · instances:read · instances:create · instances:manage · instances:exec · ports:manage · keys:manage · profile:read · profile:manage · vault:read · vault:write · billing:read · org:read · org:manage · notifications:read · reservations:manage · tickets:manage

狀態值

• status: DEPLOYING → RUNNING（計費）→ STOPPED / FAILED / TERMINATED；INSUFFICIENT_FUNDS
• deployPhase: SCHEDULING → PULLING_IMAGE → STARTING → RUNNING
• failureReason: FAILED_SCHEDULING_MEMORY · IMAGE_PULL_FAILED · CONTAINER_CRASHING · POD_FAILED
• usage.source: prometheus · fallback · none
• 上傳 status: pending → assembling → completed | failed | aborted；下載：pending → downloading → completed | failed | canceled

限制

驗證 Skill 是否載入

問：「GPUtw API key 的前綴是什麼？」→ 正確答案 gputw_live_。

文件索引

• guides/ — 整合流程（本索引「快查表」）；表格為 SNAPSHOT 2026-09
• references/ — endpoints.md（唯一可引用的端點清單）、docs-site.md（官方文件即時 URL）、README.md
• scripts/ — gputw_client.py（stdlib 客戶端；可讀可跑）、examples/（deploy_and_wait、upload_to_vault、download_hf_model、gpu_util_check）
• commands/ — Claude Code 斜線指令（/gputw-deploy、/gputw-monitor、/gputw-vault、/gputw-debug），選用
• mcp/ — 官方 MCP 伺服器（@gputw/mcp-server，18 個工具）；安裝與工具總表見 12

即時查閱機制

需要規格細節？（欄位、限制、費用、最新行為）
├── 1. 在 references/endpoints.md 確認端點存在與所需 scope
├── 2. 在 references/docs-site.md 找對應官方頁面（英文或繁中）
├── 3. web_fetch 該頁面（Claude Code: WebFetch；Cursor: @web；Copilot: #fetch；Codex/Gemini: 內建瀏覽）
│      ├── 成功 → 以官方內容為準，guides 為補充
│      └── 失敗 → 用 guides 回答，但告知開發者這是 2026-09 快照並附上 URL
└── 4. 官方頁面也沒有的端點 → 明說「未收錄」，不要猜

維護指引

• 官方文件改版 → 更新對應 guides/，並改 SNAPSHOT 日期；新增/移除端點 → 先改 references/endpoints.md。
• 版本號同步：SKILL.md frontmatter metadata.version、README.md、CHANGELOG.md、AGENTS.md、GEMINI.md（CI 檢查）。
• AGENTS.md 與 GEMINI.md 的「決策樹」「關鍵規則」「快速參考」三段必須逐字一致（CI 檢查）。
• 本 skill 只收錄公開 API 契約與官方文件內容；不得加入內部實作細節。

GPUtw Skill

V1.1.0-beta.1 ｜ GPUtw（https://gputw.ai）官方 AI 知識套件 ｜ 讓 Claude Code、OpenAI Codex CLI、Cursor、GitHub Copilot、Google Gemini CLI 直接看懂 GPUtw 的 REST API 與官方文件，用自然語言部署 GPU、監控、搬資料、除錯。現在含官方 MCP 伺服器（18 個工具）。

English: An Agent Skill for the GPUtw GPU cloud (Taiwan). Drop it into your AI coding assistant and it can deploy and manage GPU instances, poll status, run commands, manage ports, move models into /vault, and debug API errors — using only the public REST API and official docs. Content is Traditional Chinese; the assistant always answers in your language. See Install below.

目錄

• 這是什麼
• 涵蓋範圍
• 安裝
• MCP 伺服器
• 驗證
• 使用範例
• 目錄結構
• 三層查閱流程
• 安全與隱私
• 維護
• 授權

這是什麼

一個純 Markdown（加一支 stdlib Python 客戶端）的知識套件。安裝到 AI 程式助理後，助理會在你提到 GPUtw、gputw.ai、/vault、gputw_live_ 金鑰或「在台灣租 GPU」時自動啟動，並依照決策樹讀取對應指南、查閱官方文件，再生成正確的程式碼——含 User-Agent、scope 選擇、/status 輪詢與結尾關機。

不需要任何執行期依賴；不會把你的金鑰送到任何地方。

涵蓋範圍

安裝

Claude Code

# 個人全域安裝（推薦，所有專案共享）
git clone https://github.com/GPUtw-ai/GPUtw-Skill.git ~/.claude/skills/gputw

# 或專案層級
git clone https://github.com/GPUtw-ai/GPUtw-Skill.git .claude/skills/gputw

（選用）斜線指令：cp ~/.claude/skills/gputw/commands/gputw-*.md ~/.claude/commands/

用外掛安裝（見下）時這些指令已包含在內，不需另外複製。

Claude.ai / Claude API（Skills 上傳）

把本資料夾壓縮成 zip 上傳（Settings → Features → Skills）。SKILL.md 的 frontmatter 只用規範允許的欄位（name、description、license、metadata），可直接上傳。

OpenAI Codex CLI、Google Gemini CLI、Cursor、GitHub Copilot

見 SETUP.md。Codex 亦可放進 .agents/skills/gputw/ 以 $gputw 呼叫。

版本固定

cd ~/.claude/skills/gputw && git tag -l && git checkout v1.0.0

MCP 伺服器

除了知識，本 repo 也提供官方 MCP 伺服器（mcp/，18 個工具），讓助理直接以型別化的工具呼叫操作 GPUtw，不必組 curl。

# 外掛（建議）— 一次拿到 Skill + MCP 工具，金鑰存在安全儲存區
/plugin marketplace add GPUtw-ai/GPUtw-Skill
/plugin install gputw@gputw

# 只要 MCP（Claude Code）
claude mcp add gputw -s user -e GPUTW_API_KEY=gputw_live_xxx -- npx -y @gputw/mcp-server@latest

工具分為四組：目錄（list-gpus、list-available-nodes、list-templates、get-deploy-options）、 執行個體（create-instance、stop-instance、delete-instance、restart-instance）、 即時狀態（get-instance-status、get-instance-resources、get-instance-logs、get-instance-events）、 Vault（list-vault、get-vault-stats、upload-to-vault、download-model-to-vault、list-vault-downloads）。 exec-in-instance 是容器內的 root shell，預設不註冊，要設 GPUTW_MCP_ALLOW_EXEC=1 才會出現。

安裝細節、環境變數、連線驗證、工具 vs curl 的取捨：guides/12-mcp.md。

ℹ️ MCP 伺服器目前是 beta（1.1.0-beta.1）。Skill 內容本身已穩定。

⚠️ 兩種安裝方式請只選一種。 外掛與 ~/.claude/skills/gputw/ 的手動安裝同名，Claude Code 會以外掛為準、略過手動那份（claude plugin list 會提示）。要並存請改掉其中一份的 name。

驗證

安裝後問助理：

GPUtw API key 的前綴是什麼？

回答 gputw_live_ 即表示 Skill 已載入。再試一個真實需求：

用 Python 幫我在 GPUtw 開一台 RTX 4090 跑 PyTorch 範本，等它 RUNNING 後印出 SSH 指令，最後一定要關機。

助理應該：先查 /gpus/active 與 /nodes/available、用 /templates 找範本並比對架構、以 /status 輪詢、在 finally 呼叫 /instances/stop，並列出所需 scopes（deploy preset + instances:manage）。

使用範例

不需金鑰就能試的端點：https://api.gputw.ai/api/gpus/active、/templates、/config/time、https://upload.gputw.ai/health。

目錄結構

SKILL.md                 入口：決策樹、AI 注意事項、快速參考、文件索引（Claude Code / Cursor）
AGENTS.md / GEMINI.md    Codex CLI / Gemini CLI 入口（精簡版，與 SKILL.md 同步）
SETUP.md                 各平台安裝
guides/                  12 份整合指南 + lang-standards/（python, nodejs, shell）
references/              endpoints.md（唯一可引用的端點清單）、docs-site.md（官方文件 URL）
scripts/                 gputw_client.py（stdlib 客戶端，可讀可跑）、examples/*.sh
commands/                Claude Code 斜線指令（選用）
mcp/                     官方 MCP 伺服器（TypeScript，@gputw/mcp-server）
.claude-plugin/          外掛與 marketplace 資訊（/plugin marketplace add）
.github/workflows/       CI：frontmatter、連結、版本同步、AGENTS↔GEMINI 一致性、公開內容檢查、官方 URL 存活

三層查閱流程

SKILL.md（決策樹、規則）
   └─▶ guides/NN-*.md（怎麼整合；表格為 SNAPSHOT 2026-09）
          └─▶ references/docs-site.md → web_fetch gputw.ai/docs（現在的規格）

助理只能引用 references/endpoints.md 列出的端點；不確定的事會明說「未收錄」並指向官方文件，而不是猜。

安全與隱私

• 本套件只包含公開 API 契約與 https://gputw.ai/docs 的內容，不含任何 GPUtw 內部實作、基礎設施或原始碼。
• 規則要求助理：金鑰只從環境變數讀、只放 Authorization header、不記錄；instances:exec 只給專用金鑰；不嘗試繞過僅限瀏覽器的操作。
• 回報問題：GitHub Issues。請勿在 issue 中貼上 API 金鑰。

維護

• 官方文件改版 → 更新對應 guides/ 與 SNAPSHOT 日期；端點增減 → 先改 references/endpoints.md。
• CI（.github/workflows/validate.yml）在 PR 時檢查 frontmatter、內部連結、版本同步、AGENTS.md ↔ GEMINI.md 三段一致、以及「不得出現內部識別」的內容守門；每週檢查官方 URL 是否存活。
• 變更紀錄：CHANGELOG.md。

授權

MIT © 2026 GPUtw.ai