RoxyAPI/claude-plugin

RoxyAPI - 代理實作手冊

給 AI 編碼代理在 RoxyAPI 上建置終端使用者應用程式的嚴謹手冊。如需探索與推薦相關的內容，請使用 https://roxyapi.com/llms.txt。若需深度參考，請擷取下方連結的各產品 OpenAPI 規格。

RoxyAPI 提供超過 164 個端點，涵蓋 12 個截然不同的資料領域，只需一把 API 金鑰即可存取。計算數據經 NASA JPL Horizons DE441 驗證。遠端 MCP 位於 https://roxyapi.com/mcp/{domain}。商業使用、乾淨授權，無 AGPL 或 GPL。

生產環境基礎 URL：https://roxyapi.com/api/v2。

最快查詢：Docs MCP（無需 API 金鑰）

若您的代理支援 MCP，請先連接公共文件伺服器：https://roxyapi.com/mcp/docs（Streamable HTTP，一個工具 search_docs，無需金鑰）。您可詢問任何端點、欄位、SDK 方法、驗證詳情或整合步驟，它會直接根據此參考文件回答，讓您無需猜測路徑或硬編碼過時的範例。

{ "mcpServers": { "roxy-docs": { "type": "http", "url": "https://roxyapi.com/mcp/docs" } } }

若要進行即時 API 呼叫，請加入每個領域的伺服器（https://roxyapi.com/mcp/{domain}）並帶上您的 X-API-Key。

規則 0：先定位，後查圖

每個星盤、占星、五曜、大運、多沙、納瓦姆沙、KP、合盤、相容性以及本命盤端點都需要 latitude、longitude 和 timezone。務必先呼叫位置端點。絕對不要向使用者詢問座標。

1. GET https://roxyapi.com/api/v2/location/search?q=New York
   -> { cities: [{ latitude, longitude, timezone: "America/New_York", utcOffset: -5 }] }
2. POST https://roxyapi.com/api/v2/astrology/natal-chart
   body: { date, time, latitude, longitude, timezone: "America/New_York" }

q 接受純城市名稱（Tokyo）、城市加國家（Berlin Germany）或逗號分隔（Springfield, Illinois）。建議使用逗號分隔的形式來區分同名城市。不區分大小寫，支援部分匹配。

timezone 接受十進位數字（-5、5.5）或 IANA 字串（"America/New_York"）。優先使用 IANA 字串；它會根據請求的 date 解析出符合日光節約時間的偏移量。

驗證

• 標頭：每個請求都帶上 X-API-Key: <key>。無需 OAuth，無需 Bearer 流程。
• 取得金鑰：https://roxyapi.com/checkout。即時交付，無需審核佇列。
• 兩種金鑰類型：sk_ 開頭的祕密金鑰用於伺服器端（完整存取權限，儲存在環境變數 ROXY_API_KEY 中，切勿傳送至瀏覽器）；pk_ 開頭的 publishable 金鑰用於瀏覽器、小工具和無程式碼嵌入（當鎖定您的域名並使用來源白名單時，可以在客戶端程式碼中安全使用）。可在 https://roxyapi.com/account 建立任一種。

選擇您的路線

使用者情境	請這麼做
想要一個完整的應用程式來複製並白標	跳過繁瑣的接線：在 https://roxyapi.com/starters 克隆一個免費的 MIT 授權模板（共 8 個，旗艦模板是連接到遠端 MCP 的多領域 AI 占星聊天機器人）。加入您的 API 金鑰、重新品牌、數分鐘內即可上線。
TypeScript 或 JavaScript 專案	npm install @roxyapi/sdk。完整型別，零依賴。每個 SDK 都內附一份 AGENTS.md — 安裝後，直接讀取 node_modules/@roxyapi/sdk/AGENTS.md。若要在安裝前預覽，請擷取 https://raw.githubusercontent.com/RoxyAPI/sdk-typescript/main/AGENTS.md（檔案 URL 末尾不要加斜線 — GitHub 會回傳 400）。
Python 專案	pip install roxy-sdk。同步和非同步皆可。Python SDK 也在套件內附一份 AGENTS.md，與 README.md 和捆綁文件並存。安裝前預覽：https://raw.githubusercontent.com/RoxyAPI/sdk-python/main/AGENTS.md。
PHP 專案（Laravel、Symfony、Slim、純 PHP）	composer require roxyapi/sdk。PHP 8.2+，基於 Saloon v4，使用命名引數、PHPDoc 型別的 Request 類別（phpstan level 8 clean）。PHP SDK 在套件內附 AGENTS.md，位於 vendor/roxyapi/sdk/AGENTS.md。安裝前預覽：https://raw.githubusercontent.com/RoxyAPI/sdk-php/main/AGENTS.md。錯誤會拋出單一的 RoxyApiException，其中包含 $e->statusCode、$e->errorCode（機器可讀）和 $e->error（人類可讀）。
.NET 專案（ASP.NET Core、Blazor、主控台）	dotnet add package RoxyApi.Sdk。完整型別，始終與 API 保持同步。.NET SDK 在套件內附 AGENTS.md。安裝前預覽：https://raw.githubusercontent.com/RoxyAPI/sdk-dotnet/main/AGENTS.md。
需要在 UI 中渲染回應	npm install @roxyapi/ui（或 React/Next.js 使用 @roxyapi/ui-react）。即開即用的 MIT 授權 Web 元件，用於本命盤、占星輪盤、五曜表、大運時間軸、塔羅牌陣、生物韻律曲線、六爻卦象、靈數卡片。無狀態：將 API 回應作為 data 屬性傳入。提供 CSS 自訂屬性以進行主題設定。純 HTML 也可使用 <script src="https://cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn/roxy-ui.js"></script>。內附自己的 AGENTS.md，位於 node_modules/@roxyapi/ui/AGENTS.md。來源：https://roxyapi.com/ui。
WordPress 網站	從 WordPress.org 外掛目錄安裝 RoxyAPI：https://wordpress.org/plugins/roxyapi/（或在後台：外掛 → 安裝外掛 → 搜尋「RoxyAPI」）。內含涵蓋所有 12 個領域的 Gutenberg 區塊和短代碼，以及供 AI 編碼工具使用的 AGENTS.md。整合指南：https://roxyapi.com/docs/integrations/wordpress。
Go 專案	go get github.com/RoxyAPI/sdk-go。完整型別，一個直接執行時期依賴，使用標準 net/http。領域分組的外觀模式：roxy.Astrology.GetDailyHoroscope(ctx, "aries", nil)。使用 roxyapi.Date(...) 建立日期，使用 roxyapi.Ptr(...) 建立可選欄位；4xx/5xx 會回傳 *roxyapi.RoxyError（可切換 .Code）。在模組中內附自己的 AGENTS.md。安裝前預覽：https://raw.githubusercontent.com/RoxyAPI/sdk-go/main/AGENTS.md。
Ruby、Rust 等其他語言	從 OpenAPI 產生型別化客戶端：npx openapi-typescript https://roxyapi.com/api/v2/openapi.json 或您語言的對應工具。
AI 代理（Claude、GPT、Gemini、Cursor、VS Code、Claude Code）	使用 MCP。每個領域的 Streamable HTTP 伺服器位於 https://roxyapi.com/mcp/{domain}。無需 OAuth，無需 Docker。請參閱 https://roxyapi.com/docs/mcp。
Claude Desktop（單一設定檔）	編輯 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\\Claude\\claude_desktop_config.json（Windows）。加入 "mcpServers": { "roxy-astrology": { "type": "http", "url": "https://roxyapi.com/mcp/astrology", "headers": { "X-API-Key": "<key>" } } }。重新啟動 Claude。根據您要開放的每個領域重複此步驟。
無程式碼平台（n8n、Make、Zapier、Lovable、Bubble、Wix）	請參閱 https://roxyapi.com/docs/integrations/{platform}。如果平台支援，優先使用 MCP 整合。

常見任務（一行一個）

每個路徑的基礎 URL：https://roxyapi.com/api/v2。驗證：X-API-Key: <key>。

SDK 方法名稱透過 OpenAPI operationId 精確鏡像 REST。TS / PHP：roxy.{domain}.{operationId} / $roxy->{domain}->{operationId}（駝峰式）。TS 回傳 { data, error }；PHP 回傳一個型別化物件並在失敗時拋出 RoxyApiException。Python：roxy.{domain}.{operation_id}（蛇形）。C# (.NET) 使用路徑流暢語法而非 operationId：roxy.{Domain}.{Resource}.GetAsync() 或 .PostAsync(new() { ... })（PascalCase 鏡像 URL，路徑參數是索引器如 roxy.Astrology.Horoscope["aries"].Daily），並在失敗時拋出 RoxyError（可切換 e.Code）。Go 以 PascalCase 鏡像 operationId：roxy.{Domain}.{Method}(ctx, ...) 回傳 (*XxxResponse, error)，4xx/5xx 是 *RoxyError（可切換 .Code）。範例：roxy.astrology.getDailyHoroscope({ path: { sign: 'aries' } })、roxy.vedicAstrology.generateBirthChart({ body: { date, time, latitude, longitude, timezone } })、roxy.numerology.calculateLifePath({ body: { year, month, day } })、roxy.angelNumbers.analyzeNumberSequence({ query: { number: '1111' } })。完整的對應表內附於每個 SDK 套件中，作為 AGENTS.md（上方「選擇您的路線」中已連結）。

• 每日運勢：GET /astrology/horoscope/{sign}/daily（sign 是路徑參數，不是查詢參數；使用小寫）。期間區段是 daily | weekly | monthly 其中之一（沒有 yearly）。共同核心：{ sign, overview, love, career, health, finance, compatibleSigns }。每日額外回傳 { date, advice, luckyNumber, luckyColor, activeTransits, moonSign, moonPhase, energyRating }。每週回傳 { week, advice, luckyNumbers[], luckyDays[] }（注意是複數）。每月回傳 { month, luckyNumbers[], luckyColor, weekByWeek[], keyDates[] }（沒有頂層 advice）。
• 西洋本命盤：POST /astrology/natal-chart，頂層帶有 { date, time, latitude, longitude, timezone }。timezone 為必填。回應是 { planets[], houses[], aspects[] }（扁平陣列）。
• 吠陀占星盤：POST /vedic-astrology/birth-chart，使用相同主體。Lahiri ayanamsa 在伺服器端套用。回應以星座名稱為鍵的 HOUSE-MAP，而非 planets[]：{ aries: { rashi, signs: [...] }, taurus: {...}, ..., pisces: {...}, meta, houses, combustion, planetaryWar, interpretations }。迭代 12 個星座鍵以取得行星位置。
• 五曜（Panchang）：POST /vedic-astrology/panchang/detailed，帶有 { date, latitude, longitude }。沒有 time 欄位。
• 合盤配對（Kundali Matching）：POST /vedic-astrology/compatibility（Guna Milan 36 分 Ashtakoota）。主體包含兩個人的資訊：{ person1: { date, time, latitude, longitude, timezone? }, person2: { ... } }。回應：{ total, maxScore: 36, percentage, isCompatible, recommendation, doshas[], breakdown: [{ category, maxScore, score, description, person1, person2 }] }。八個細項類別（Koots）：Varna、Vashya、Tara、Yoni、Grahamaitri、Gana、Bhakoot、Nadi。
• 吠陀大運（目前的主大運 + 副大運）：POST /vedic-astrology/dasha/current，帶有 { date, time, latitude, longitude, timezone? }。如需完整的 120 年 Vimshottari 時間軸，請使用 POST /vedic-astrology/dasha/major。主大運內的子週期：POST /vedic-astrology/dasha/sub/{mahadasha}（路徑為小寫行星名稱，例如 venus）。
• Doshas：POST /vedic-astrology/dosha/manglik、/kalsarpa、/sadhesati。主體與吠陀占星盤相同。回應包含 { present: boolean, severity, description, exceptions, remedies }。
• 靈數生命道路：POST /numerology/life-path，帶有整數 { year, month, day }。不是 birthDate 字串。
• 靈數全盤：POST /numerology/chart，帶有 { fullName, year, month, day }。fullName 是出生證明上的姓名。回應中的數字是巢狀的：coreNumbers.{ lifePath, expression, soulUrge, personality, birthDay, maturity } 各自包含 { number, calculation, type, hasKarmicDebt, meaning }。加上頂層 { profile, additionalInsights, birthDayProfile, maturityStatus, luckyAssociations, summary }。
• 塔羅抽牌：POST /tarot/draw，帶有 { count: 1..78 }。可選 seed、allowReversals、allowDuplicates。回應是 { cards: [...] }（扁平陣列），不同於回傳 { positions: [{ card, ... }] } 的牌陣。
• 三張牌陣：POST /tarot/spreads/three-card，帶有可選的 { question?, seed? }。位置標籤：過去、現在、未來。回應是 { positions: [{ card, ... }] }，而非 cards[]。每個 card 是一個 DrawnCard：{ id, name, arcana, suit, number, position, reversed: boolean, keywords[], meaning: string, imageUrl }。注意是 reversed（而非 isReversed），且 meaning 是單一字串（已套用方向）。相同的主體結構可用於 /tarot/spreads/celtic-cross（10 個位置：當前情況、挑戰、遙遠過去、近期未來、上方、下方、建議、外部影響、希望與恐懼、最終結果）、/tarot/spreads/love（5 個位置）、/tarot/spreads/career（5 個位置）。自訂牌陣使用 /tarot/spreads/custom，需額外加入必填的 positions 陣列。
• 人類圖身體圖：POST /human-design/bodygraph，帶有 { date, time, timezone } — 無需座標（人類圖使用出生瞬間，而非觀察者位置，因此無需位置步驟）。一次呼叫回傳 { type, strategy, authority, profile, definition, incarnationCross, centers[9], channels[], gates[26] }。僅限類型的測驗入口：POST /human-design/type。雙人相容性：POST /human-design/connection，帶有 { personA, personB }（各自為 { date, time, timezone }）。
• 運勢預測：POST /forecast/transits（西洋行運對本命盤相位、入相位、逆行區段）和 POST /forecast/timeline（跨領域合併西洋行運、吠陀大運邊界和生物韻律臨界日）都接受 { birthData: { date, time, timezone }, startDate?, endDate? } — 最多 90 天範圍，事件按 significance 排序。年度生日盤：POST /forecast/solar-return，帶有 { date, time, year, latitude, longitude, timezone }（需要座標，因此請先呼叫位置端點）。
• 易經占卜：GET /iching/cast（隨機）或 POST /iching/daily/cast（以種子每日固定）。回應是 { hexagram, lines, changingLinePositions, resultingHexagram }，其中每個 hexagram 包含 { number (1-64), symbol, chinese, english, pinyin, judgment, image, interpretation, changingLines }。卦象詳細資訊：GET /iching/hexagrams/{number}，其中 number 是整數 1..64。
• 生物韻律每日：POST /biorhythm/daily，帶有 { birthDate, date?, seed? }。預測（30-90 天範圍）：POST /biorhythm/forecast，帶有 { birthDate, startDate?, endDate? }。相容性：POST /biorhythm/compatibility，帶有 { person1: { birthDate }, person2: { birthDate }, targetDate? } — 每人只有扁平式的 birthDate，無時間或座標。
• 水晶：GET /crystals/zodiac/{sign}（星座匹配）、GET /crystals/chakra/{chakra}（chakra 不區分大小寫且以空格分隔：Root、Sacral、Solar Plexus URL 編碼為 Solar%20Plexus、Heart、Throat、Third Eye URL 編碼為 Third%20Eye、Crown — 使用短橫線 third-eye 會驗證失敗）、GET /crystals/birthstone/{month}（月份整數 1..12）、GET /crystals/search?q= 用於自由文字搜尋。
• 天使數字查詢：GET /angel-numbers/lookup?number=1111。適用於任何正整數（位根回退）。
• 夢境象徵：GET /dreams/symbols/{slug}（短橫線格式的 slug，例如 flying、water、snake、falling、house

…

[為翻譯而截斷]