RoxyAPI/claude-plugin

RoxyAPI - 智能体实施手册

面向构建基于RoxyAPI的终端应用的AI编程智能体的紧凑手册。如需发现与推荐上下文，请使用 https://roxyapi.com/llms.txt。如需深度参考，请获取下方链接的每个产品的OpenAPI规范。

RoxyAPI在一个API密钥下提供164+个跨12个不同数据域的端点。计算经过NASA JPL Horizons DE441验证。远程MCP位于 https://roxyapi.com/mcp/{domain}。商业使用，清洁许可，无AGPL或GPL。

生产环境基础URL：https://roxyapi.com/api/v2。

快速查找：文档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。始终先调用Location。永远不要向用户询问坐标。

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_ 用于浏览器、小部件和无代码嵌入（当通过来源白名单锁定到你的域名时，在客户端代码中是安全的）。在 https://roxyapi.com/account 处创建任一密钥。

选择你的路径

用户上下文	操作方式
想要一个完整应用可直接分叉和白标	跳过接线：克隆一个免费、MIT许可的模板，地址为 https://roxyapi.com/starters（共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（或 @roxyapi/ui-react 用于React/Next.js）。可直接使用的MIT许可Web组件，用于本命盘、 Kundli轮盘、盘查表、大运时间线、塔罗牌阵、生物节律曲线、卦象、数字学卡片。无状态：将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[] }（扁平数组）。
• 吠陀Kundli：POST /vedic-astrology/birth-chart，体结构相同。Lahiri ayanamsa在服务器端应用。响应是按星座名称键控的星宫映射，而非 planets[]：{ aries: { rashi, signs: [...] }, taurus: {...}, ..., pisces: {...}, meta, houses, combustion, planetaryWar, interpretations }。遍历12个星座键以获取行星位置。
• 盘查：POST /vedic-astrology/panchang/detailed，体包含 { date, latitude, longitude }。无 time 字段。
• Kundali匹配：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。
• 吠陀大运（当前Mahadasha + Antardasha）：POST /vedic-astrology/dasha/current，体包含 { date, time, latitude, longitude, timezone? }。如需完整的120年Vimshottari时间线，使用 POST /vedic-astrology/dasha/major。Mahadasha内的子周期：POST /vedic-astrology/dasha/sub/{mahadasha}（路径是小写行星名，例如 venus）。
• 塔罗萨：POST /vedic-astrology/dosha/manglik，/kalsarpa，/sadhesati。体与Kundli相同。响应包含 { 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 }——无坐标（HD使用出生时刻，而非观察者位置，因此无需Location步骤）。一次调用返回 { 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 }（需要坐标，因此先调用Location）。
• 易经占卜：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

… [因翻译而截断]