FateStar 郑大钱 · 开发者文档

将 FateStar 自研的紫微斗数排盘引擎接入你的应用或 AI Agent —— 免费排盘，需要解读时再按积分付费。

API Base URLhttps://www.fatestar.top

两步即可接入：先复制下面的请求跑通免费排盘，再按需要选择 API / MCP / Skill 之一深入。

快速开始

下面以“1990 年 7 月 23 日早上 8 点出生男性”为例，分别演示免费排盘与付费解读。

免费排盘：匿名调用

bash
1curl "https://www.fatestar.top/api/ziwei?year=1990&month=7&day=23&hour=8&gender=male"

付费解读：携带 FSFSKey

bash
1curl -X POST "https://www.fatestar.top/api/ziwei/reading" \
2 -H "Authorization: Bearer FSFSKey20260606XXXXXXXXXXXXXXXXXXXX" \
3 -H "Content-Type: application/json" \
4 -d '{ "year": 1990, "month": 7, "day": 23, "hour": 8, "gender": "male", "question": "看我今年的事业运，该不该跳槽？" }'
请将示例中的 FSFSKey20260606XXXXXXXXXXXXXXXXXXXX 替换为你的真实 Key。Key 可在 fatestar.top 开发者中心 创建；明文 Key 只在创建时展示一次，请自行保存。

API / MCP / Skill 怎么选？

三种方式都能免费排盘，也都能花积分让郑大钱解读。差别只在一件事：你会不会写代码、平时在哪用。

API
你会写程序。把排盘接进自己的网站、App 或后台批量跑 —— 最自由，但要动代码。
MCP
你平时用 Claude、Cursor 这类 AI。填一个网址，AI 就当场帮你排盘 —— 不用写代码。
Skill
你平时用 Claude、Codex。装一个「排盘技能包」，以后直接说人话「帮我排盘」就行。

一句话选：不会写代码 → 用 MCP 或 Skill；会写代码、要接进自己的产品 → 用 API。三种能单用，也能一起用。

你关心的APIMCPSkill
完全不用写代码✗✓✓
直接跟 AI 说人话提问✗✓✓
填个网址就能用、不用装✗✓✗
适合大批量自动跑✓△✗
最适合谁会写代码的开发者Claude·Cursor 用户Claude·Codex 用户

表中 △ = 能做，但不是它的强项。

免费能力：排盘数据

/api/ziwei 与 MCP 的 ziwei_chart / ziwei_transits 返回结构化命盘与运限数据。 这部分不需要注册、不需要 FSFSKey，也不会扣积分；系统只按 IP 做基础限流。

边界说明： 免费排盘只提供可验证的结构化数据。若用户让自己的通用 LLM 基于这些数据自行解释，解读质量取决于该 LLM 的知识、提示词和上下文，不等同于 FateStar 的郑大钱解读 API。

付费能力：郑大钱解读

/api/ziwei/reading 会在排盘结果上叠加 FateStar 知识引擎与郑大钱人格，返回完整问答式解读。 该能力需要 FSFSKey，并按问题长度与模式扣除积分。详见 解读接口。 注册、积分与计费规则见下一节 认证 & 积分。

认证 & 积分

FSFSKey 是开发者身份凭证。免费排盘不需要 Key；郑大钱解读、命盘仓库等账号能力需要 Key。 系统按你调用的接口判断是否扣积分，不是按“是否携带 Key”本身扣费：

用法 1 · 完全免费
排盘引擎
/api/ziwei
  • ● 排命盘 + 6 层运限（大限 / 小限 / 流年 / 流月 / 流日 / 流时）
  • ● 不扣积分，匿名（不带 Key）也能调用
  • ● 适合产品接入、批量排盘、Agent 先拿结构化命盘
用法 2 · 扣积分
郑大钱解读
/api/ziwei/reading
  • ● 问郑大钱一个问题，知识引擎 + 郑大钱人格断盘
  • ● 短问不扣积分：中文 ≤10 字 / 日韩 ≤15 字 / 英文及外语 ≤30 字符（含标点符号）
  • ● 超过免费门槛起扣 1 积分；长问封顶 2 积分（中文 >100 / 日韩 >150 / 外语 >300）
计费边界：调用 /api/ziwei 只返回排盘数据，不扣积分。只有调用 /api/ziwei/reading 并生成有效解读时，才按规则扣积分。

认证方式（带 / 不带 Key 的区别）

FateStar 排盘引擎支持灵活的认证策略，你可以根据需要选择是否携带 API Key：

调用方式Header 格式能力与计费
匿名排盘不提供 Authorization 头仅返回排盘与运限数据，免费、按 IP 限流
认证解读Authorization: Bearer FSFSKey…调用解读 API 时使用知识引擎与郑大钱人格，按积分计费
注意：解读 API 要求有效 FSFSKey。若 Key 缺失、非法、已禁用或已过期，系统将返回401 Unauthorized，而不会降级为匿名调用。

积分规则

  • ● 只有解读 API（问郑大钱）需注册会员；排盘 API 匿名可调，不注册也能排盘。
  • ● 解读按提问字数扣 1 ~ 2 积分（短问免费；详见 积分计费）。
  • ● 免费注册用户每日 3 积分（北京时间 21:00 重置）；无积分需充值。

排盘 API（免费）

GET / POST/api/ziwei

输入出生信息，返回完整本命盘；带 transits=1 或目标年份时，同时返回 6 层运限。GET 使用 query 参数，POST 使用 JSON body。

请求参数

字段名必填说明
year / month / day✅出生年月日（阳历；calendarType=lunar 时为农历）
hour✅出生小时 0–23（24 小时制，非时辰地支）
gender✅male / female
calendarTypesolar(默认)/ lunar
minute出生分钟，配合 longitude 做真太阳时精修
longitude / tz经度 + 时区，启用真太阳时修正
transits=1 或带 targetYear 时加 6 层运限
targetYear / targetMonth / targetDay / targetHour运限目标（默认当年 + 本命月日）

请求示例

bash
1# 本命盘
2curl "https://www.fatestar.top/api/ziwei?year=1990&month=7&day=23&hour=8&gender=male"
3
4# 本命盘 + 2026 流年运限
5curl "https://www.fatestar.top/api/ziwei?year=1990&month=7&day=23&hour=8&gender=male&transits=1&targetYear=2026"

响应格式

成功返回 { "data": { … } }，顶层字段：

字段说明
service / 输入引擎标识 + 回显你的输入（历法 / 性别 / 真太阳时启用状态）
基础五行局 / 阴阳 / 命主身主 / 命身宫地支 / 真实出生四柱（万年历按节气）
十二宫每宫主星 / 辅星 / 煞星 / 杂曜 + 庙旺亮度 + 生年四化 + 空宫借星 + 大限年龄
本命四化化禄 / 化权 / 化科 / 化忌（星 + 所在宫）
格局 / 夹宫30+ 经典格局（含古籍出处）+ 夹宫扫描
运限带 transits 时返回，含 大限列表 / 小限 / 流年 / 流月 / 流日 / 流时 / 流运目标

完整响应示例（节选）：

json
1{
2 "data": {
3 "基础": {
4 "阳历": "1990-7-23",
5 "农历": "一九九〇年六月初二",
6 "五行局": "土五局",
7 "阴阳": "阳",
8 "命主": "文曲", "身主": "火星",
9 "命宫地支": "卯", "身宫地支": "亥",
10 "真实出生四柱": { "年": "庚午", "月": "癸未", "日": "己丑", "时": "戊辰" }
11 },
12 "十二宫": [
13 {
14 "宫名": "命宫", "天干地支": "己卯",
15 "主星": [{ "名称": "廉贞", "亮度": "平" }, { "名称": "破军", "亮度": "陷" }],
16 "辅星": [],
17 "煞星": [{ "名称": "地劫", "亮度": "平" }],
18 "杂曜": ["天月", "天喜", "天德", "咸池", "喜神"],
19 "身宫": false, "大限年龄": "5-14岁", "长生十二神": "死"
20 }
21 ],
22 "本命四化": {
23 "化禄": { "星": "太阳", "宫": "交友" },
24 "化权": { "星": "武曲", "宫": "官禄" },
25 "化科": { "星": "天同", "宫": "田宅" },
26 "化忌": { "星": "太阴", "宫": "田宅" }
27 },
28 "格局": [{ "名称": "杀破狼", "类别": "中性", "星曜": ["七杀", "破军", "贪狼"], "宫位": "命宫", "出处": "《紫微斗数全书》" }],
29 "夹宫": [{ "宫位": "官禄", "类型": "昌曲夹", "吉凶": "吉", "前邻": "文昌", "后邻": "文曲" }]
30 }
31}

错误码

所有错误响应均为 { "error": { "code", "message" } } 结构。

状态码code说明
400INVALID_INPUT / VALIDATION_ERROR排盘 API 返回 INVALID_INPUT；解读 API 返回 VALIDATION_ERROR。通常是参数缺失或范围错（year/month/day/hour/gender 等）
400INVALID_JSONPOST body 不是合法 JSON
401UNAUTHORIZED解读 API 缺少或无效的 FSFSKey（不降级匿名）
402INSUFFICIENT_CREDITS积分不足（响应带 need / have）；不生成、不扣费
403CHART_QUOTA_EXCEEDED命盘配额已满
429RATE_LIMITED请求过于频繁（按 IP 限流）
500INTERNAL_ERROR服务端内部错误，可重试
502GENERATION_FAILED解读生成失败（空回复）；未扣费

错误响应示例

json
1{
2 "error": {
3 "code": "INSUFFICIENT_CREDITS",
4 "message": "积分不足：需 1，有 0",
5 "need": 1,
6 "have": 0
7 }
8}

枚举值参考

API 请求与响应里常用的枚举字段取值规范。

性别 gender

malefemale

历法 calendarType

solar（公历，默认）lunar（农历）

运限层级（transits 输出）

大限小限流年流月流日流时

星曜类型

主星（14）辅星（8）煞星（6）杂曜（38）流曜（36）

生年四化

化禄化权化科化忌

庙旺亮度

庙旺得利平不陷

五行局

水二局木三局金四局土五局火六局

十二宫

命宫兄弟夫妻子女财帛疾厄迁移交友官禄田宅福德父母

解读 API

POST/api/ziwei/reading

传入出生信息与 question，返回由知识引擎 + 郑大钱人格生成的完整解读。 请求必须携带 FSFSKey；积分从该 Key 所属账号扣除。

bash
1curl -X POST "https://www.fatestar.top/api/ziwei/reading" \
2 -H "Authorization: Bearer FSFSKey20260606XXXXXXXXXXXXXXXXXXXX" \
3 -H "Content-Type: application/json" \
4 -d '{
5 "year": 1990, "month": 7, "day": 23, "hour": 8,
6 "gender": "male",
7 "question": "看我今年的事业运，该不该跳槽？"
8 }'

响应示例

json
1{
2 "data": {
3 "reading": "…郑大钱解读全文…",
4 "creditsUsed": 1,
5 "balanceAfter": 12,
6 "chartId": "…"
7 }
8}

积分计费

免费额度：短问不扣积分。中文 ≤10 字、日文/韩文 ≤15 字、英文及其他外语 ≤30 字符（含特殊符号及标点）均视为短问。

超过免费门槛后按提问长度计费，中文 / 日韩 / 其他外语三档分别计算；空格、标点、特殊符号均计入长度：

语言完全免费1 积分2 积分（封顶）
中文≤ 10 字11 ~ 100 字> 100 字
日文 / 韩文≤ 15 字16 ~ 150 字> 150 字
英文 / 其他外语≤ 30 字符31 ~ 300 字符> 300 字符
你想知道的答案
谁来给你解读郑大钱 —— 一位顶级国学紫微专家人格
扣谁的积分扣你这把 FSFSKey 所属的开发者账号
积分不够时直接返回 402（积分不足），不解读、也不扣费
万一没生成内容生成失败（空回复）时，不扣你积分
积分能不能叠加订阅送的积分，可以和单独购买的积分一起用

MCP 安装

Model Context Protocol 让 Claude / Cursor 等 AI 客户端以工具形式调用 FateStar。当前远程 MCP 暴露三个工具：ziwei_chart（本命盘）、ziwei_transits（6 层运限）、ziwei_reading（郑大钱付费解读，需 Key 扣积分）。 FateStar 的远程 MCP 使用 HTTP 端点，客户端只需要配置 URL，无需本地桥接代理。

配置远程 MCP

在支持远程 MCP 的客户端中，填入统一端点：

json
1{
2 "mcpServers": {
3 "ziwei": { "url": "https://www.fatestar.top/api/mcp" }
4 }
5}

配置 Key 以启用解读

不配置 Key 时，MCP 仍可免费排盘；需要调用 ziwei_reading 时，请在客户端配置 Authorization 头：

json
1{
2 "mcpServers": {
3 "ziwei": {
4 "url": "https://www.fatestar.top/api/mcp",
5 "headers": { "Authorization": "Bearer FSFSKey20260606XXXXXXXXXXXXXXXXXXXX" }
6 }
7 }
8}
若某个 MCP 客户端暂不支持自定义 Header，也可以在调用 ziwei_reading 时把 apiKey 作为工具参数传入。优先推荐 Header，因为它不会混入普通对话参数。

Skill 安装（Claude / Codex）

Skill 是给 Agent 读取的操作说明与脚本集合。安装后，Agent 会知道何时免费排盘、何时调用郑大钱解读、没有 Key 或积分不足时如何兜底。 如果你的客户端已经稳定支持远程 MCP，也可以直接使用上方 MCP 配置。

下载安装

Skill 已开源（GitHub）。 克隆后将目录放入对应 Agent 的 skills 目录：

bash
1git clone https://github.com/LouisLin0723/fatestar-ziwei-skill.git
2
3# macOS / Linux: Claude Code / Claude Desktop
4mv fatestar-ziwei-skill ~/.claude/skills/ziwei-paipan
5
6# macOS / Linux: OpenAI Codex
7mv fatestar-ziwei-skill ~/.codex/skills/ziwei-paipan
powershell
1git clone https://github.com/LouisLin0723/fatestar-ziwei-skill.git
2
3# Windows PowerShell: Claude Code / Claude Desktop
4Move-Item -LiteralPath .\fatestar-ziwei-skill -Destination "$env:USERPROFILE\.claude\skills\ziwei-paipan"
5
6# Windows PowerShell: OpenAI Codex
7Move-Item -LiteralPath .\fatestar-ziwei-skill -Destination "$env:USERPROFILE\.codex\skills\ziwei-paipan"

API Key 配置

排盘免费，无需 Key。若需要 Skill 调用郑大钱解读，请将 FSFSKey 写入环境变量；Skill 会在需要解读时自动携带：

bash
1# 在 fatestar.top 开发者中心创建 Key 后，写入环境变量
2export FATESTAR_API_KEY="FSFSKey20260606XXXXXXXXXXXXXXXXXXXX"
3
4# 有 Key → 可调用郑大钱解读；无 Key → 仅使用免费排盘

验证安装

重启 Agent 后，用自然语言验证两类能力：

  • ● 排盘（免费）：「帮我排 1990 年 7 月 23 日早上 8 点、男 的紫微盘」→ 出完整命盘 = 成功。
  • ● 解读（扣积分）：「我今年事业运如何？该不该跳槽？」→ 返回郑大钱解读 = 成功（需已配置 Key 且积分足够）。
如果未配置 Key 或积分不足，Skill 应回退为“免费排盘 + Agent 自行解释”，并提示用户到 fatestar.top 创建 Key 或补充积分。

接入各 Agent

FateStar 提供 HTTP API、远程 MCP 与 Agent Skill 三种接入形态。 只要你的客户端支持其中任一方式，即可接入排盘能力；下表仅列常见客户端，不是限制清单：

  • ● MCP：填远程地址 https://www.fatestar.top/api/mcp；如需解读，再配置 Authorization 头。
  • ● API：任何能发 HTTP 的语言 / 工具都可以直接调用。
  • ● Skill：将开源 Skill 放进 Agent 的 skills 目录，让 Agent 读取调用规则。

Claude Desktop / Claude Code

json
1{
2 "mcpServers": { "ziwei": { "url": "https://www.fatestar.top/api/mcp" } }
3}
4// 或 Skill: mv fatestar-ziwei-skill ~/.claude/skills/ziwei-paipan

OpenAI Codex

json
1{
2 "mcpServers": { "ziwei": { "url": "https://www.fatestar.top/api/mcp" } }
3}
4// 或 Skill: mv fatestar-ziwei-skill ~/.codex/skills/ziwei-paipan

OpenClaw

json
1{
2 "mcpServers": { "ziwei": { "url": "https://www.fatestar.top/api/mcp" } }
3}
4// 或 Skill: mv fatestar-ziwei-skill ~/.openclaw/skills/ziwei-paipan

Hermes / Cursor / Cline / KIMI CLI / 飞书 CLI / 其他

其他客户端的配置文件位置与字段名可能不同，但核心信息一致：远程地址是 https://www.fatestar.top/api/mcp，解读所需 Header 是 Authorization: Bearer FSFSKey...。

json
1{ "mcpServers": { "ziwei": { "url": "https://www.fatestar.top/api/mcp" } } }

客户端速查

AgentMCPSkill 目录
Claude Desktop / Code填 url~/.claude/skills/
OpenAI Codex填 url~/.codex/skills/
OpenClaw填 url~/.openclaw/skills/
Cursor填 url—（无 Skill 机制，直接用 MCP）
Hermes / Cline / KIMI CLI / 飞书 CLI / 其他填 url各自 skills 目录
若客户端同时支持 MCP 与 Skill，优先使用 MCP 作为工具调用通道；Skill 可作为补充说明，帮助 Agent 理解何时排盘、何时解读、何时回退。

关于 FateStar

FateStar 是面向紫微斗数场景的 AI 应用与开发者平台。 对普通用户，它提供命盘、对话、合盘与命盘仓库；对开发者，它提供可直接接入的排盘 API、远程 MCP 与 Agent Skill。

核心由两部分组成：排盘引擎负责生成结构化命盘与运限数据；知识引擎负责在解读时引入规则、上下文与郑大钱人格，降低通用 LLM 直接解释命盘时的不稳定性。

本文档面向要接入 FateStar 能力的开发者与 Agent 用户。若你只想直接使用产品功能，可以从对话主页、排盘引擎、双人合盘或命盘仓库开始。

核心功能

  • 排盘引擎 —— 输入出生信息，生成十二宫、主星辅星、四化、格局与运限等结构化数据。
  • 郑大钱解读 —— 基于命盘与知识引擎回答感情、事业、财务、家庭、健康等问题。
  • 双人合盘 —— 对比两张命盘，用于关系、合作、分工与沟通分析。
  • 命盘仓库 —— 保存、编辑和管理自己或他人的命盘，并记录后续对话与笔记。

适用场景

  • 1. 在应用内生成结构化紫微斗数命盘。
  • 2. 给 AI Agent 增加稳定的排盘工具与解读入口。
  • 3. 为内容、咨询、关系分析或个人决策场景提供命盘数据层。
  • 4. 将命盘仓库、合盘、积分与邀请能力组合进自己的工作流。

积分获取

  • 连续登录挑战 —— 连续登录达到条件后领取积分奖励。
  • 邀请好礼 —— 邀请朋友注册成功后，双方获得对应奖励。
  • 联盟营销 —— 通过联盟计划推广 FateStar 并获取佣金分润。