MCP / API 接口文档

天官手记基于 Swiss Ephemeris 高精度星历库，提供七政四余排盘的精确天文计算。支持 MCP Server 和 公开 HTTP 接口 两种免登录免 API Key 调用方式。

限流说明

一、qizheng_chart 简易调用

仅需必填参数 + 出生信息，其余全部使用默认值。

{
  "birth_date": "1995-06-15",                                    # 出生日期（公历）
  "birth_time": "14:30",                                         # 出生时间
  "birth_lon": 116.407,                                          # 出生地经度（东经为正）
  "birth_lat": 39.904,                                           # 出生地纬度（北纬为正）
  "timezone": 8,                                                 # 时区（中国=8）
  "gender": "male",                                              # 性别: male/female
  "city": "北京",                                                 # 出生地（可选，用于城市查询）
  "name": "测试",                                                 # 姓名（可选）
  "xiu_method": "huangdaohuigui"                                 # 盘制: huangdaohuigui(推荐)/zhengan(推荐)，其余取值见专业调用
}

二、qizheng_chart 专业调用

在简易调用基础上增加全部计算参数。不传=简易调用的默认行为。

{
  "birth_date": "1995-06-15",
  "birth_time": "14:30",
  "birth_lon": 116.407,
  "birth_lat": 39.904,
  "timezone": 8,
  "gender": "male",
  "city": "北京",
  "name": "测试",

  # ── 星距（坐标系）：huangdao(黄道)/chidao(赤道)，须与盘制所属坐标系一致。传入值与盘制不匹配时自动报错 ──
  "coord_system": "huangdao",

  # ── 盘制（星宿制式）：全量取值见下方 xiu_method 表 ──
  "xiu_method": "huangdaohuigui",

  # ── 日期类型：solar(公历)/lunar(农历) ──
  "date_type": "solar",

  # ── 罗计排列（默认 south_north 计北罗南）：north_south(计南罗北，计都=南交点)/south_north(计北罗南，计都=北交点) ──
  "node_arrangement": "south_north",

  # ── 罗睺计算：mean(平南北交，月孛黄经平均法)/fitted(拟合南北交，考虑日心率摄动修正) ──
  "node_calculation": "mean",

  # ── 月孛计算：mean(平远月点，月孛黄经平均法)/fitted(拟合远月点，考虑摄动修正) ──
  "apogee_calculation": "mean",

  # ── 紫炁计算：equatorial_uniform(紫气赤道匀速)/ecliptic_projection(黄道投影赤道) ──
  "ziqi_calculation": "equatorial_uniform",

  # ── 童限基数：9(9岁)/10(10岁)。默认 9，如需调整可在设置内修改。例: 童限基数 9 ──
  "child_limit": 9,

  # ── 命宫起法：sun_to_mao(太阳起生时顺数至卯)/sun_to_sunrise(太阳起生时顺数至日出)/horizon_rising(地平上升宫)/rising_with_sun(上升与日同络) ──
  "ming_gong_method": "sun_to_mao",

  # ── 身宫起法：moon_is_shen(太阴为身)/moon_to_you(太阴起生时逆数至酉)/moon_to_moonrise(太阴起生时逆数至月出)/moon_to_sunset(太阴起生时逆数至日落) ──
  "shen_gong_method": "moon_is_shen",

  # ── 节气计算：true(定气法，基于太阳真实黄经)/mean(平气法，基于黄道平均划分) ──
  "jieqi_method": "true",

  # ── 昼夜设置：sunrise_sunset(日出没时间)/sunrise_sunset_shichen(日出没时辰)/mao_day_you_night(卯昼酉夜) ──
  "day_night_method": "sunrise_sunset",

  # ── 顶星容许度（度）：范围 0-30，默认 1.5 ──
  "dingxing_tolerance": 1.5,

  # ── 同络容许度（度）：范围 0-10，默认 2.0 ──
  "tongluo_tolerance": 2.0,

  # ── 换算夏令时（仅 1986-1991 年中国大陆有效） ──
  "dst_adjust": false,

  # ── 区分早晚子时（23:00-23:59 早子时，日柱算当天；00:00-00:59 晚子时，日柱算次日） ──
  "distinguish_zi_hour": true
}

专业调用示例：赤道郑案今宿 + 自定义命宫起法

{
  "birth_date": "1995-06-15",
  "birth_time": "14:30",
  "birth_lon": 116.407,
  "birth_lat": 39.904,
  "timezone": 8,
  "gender": "male",
  "xiu_method": "chidao_zhengan",
  "coord_system": "chidao",
  "ming_gong_method": "horizon_rising",
  "shen_gong_method": "moon_to_you",
  "child_limit": 10
}

三、qizheng_liunian 简易调用

{
  "birth_date": "1995-06-15",
  "birth_time": "14:30",
  "birth_lon": 116.407,
  "birth_lat": 39.904,
  "timezone": 8,
  "gender": "male",
  "city": "北京",
  "name": "测试",
  "xiu_method": "huangdaohuigui",
  "liunian_year": 2026,                                          # 流年（必填）
  "liuyue": 6,                                                   # 流月（可选，1-12）
  "liuri": 15,                                                   # 流日（可选，1-31）
  "liushi": "12:00"                                              # 流时（可选）
}

四、qizheng_liunian 专业调用

{
  "birth_date": "1995-06-15",
  "birth_time": "14:30",
  "birth_lon": 116.407,
  "birth_lat": 39.904,
  "timezone": 8,
  "gender": "male",
  "city": "北京",
  "name": "测试",
  "xiu_method": "huangdaohuigui",
  "liunian_year": 2026,
  "liuyue": 6,
  "liuri": 15,
  "liushi": "12:00",

  # ── 星距（坐标系）：huangdao(黄道)/chidao(赤道)，须与盘制所属坐标系一致。不一致时自动报错 ──
  "coord_system": "huangdao",

  # ── 罗计排列（默认 south_north 计北罗南）：north_south(计南罗北)/south_north(计北罗南) ──
  "node_arrangement": "south_north",

  # ── 罗睺计算：mean(平南北交)/fitted(拟合南北交，考虑摄动修正) ──
  "node_calculation": "mean",

  # ── 月孛计算：mean(平远月点)/fitted(拟合远月点，考虑摄动修正) ──
  "apogee_calculation": "mean",

  # ── 紫炁计算：equatorial_uniform(紫气赤道匀速)/ecliptic_projection(黄道投影赤道) ──
  "ziqi_calculation": "equatorial_uniform",

  # ── 童限基数：9(9岁)/10(10岁) ──
  "child_limit": 9,

  # ── 命宫起法：sun_to_mao(太阳起生时顺数至卯)/sun_to_sunrise(太阳起生时顺数至日出)/horizon_rising(地平上升宫)/rising_with_sun(上升与日同络) ──
  "ming_gong_method": "sun_to_mao",

  # ── 身宫起法：moon_is_shen(太阴为身)/moon_to_you(太阴起生时逆数至酉)/moon_to_moonrise(太阴起生时逆数至月出)/moon_to_sunset(太阴起生时逆数至日落) ──
  "shen_gong_method": "moon_is_shen",

  # ── 节气计算：true(定气法)/mean(平气法) ──
  "jieqi_method": "true",

  # ── 昼夜设置：sunrise_sunset(日出没时间)/sunrise_sunset_shichen(日出没时辰)/mao_day_you_night(卯昼酉夜) ──
  "day_night_method": "sunrise_sunset",

  # ── 顶星容许度（度）：0-30，默认 1.5 ──
  "dingxing_tolerance": 1.5,

  # ── 同络容许度（度）：0-10，默认 2.0 ──
  "tongluo_tolerance": 2.0,

  # ── 换算夏令时（仅 1986-1991 年中国大陆有效） ──
  "dst_adjust": false,

  # ── 区分早晚子时 ──
  "distinguish_zi_hour": true
}

五、lookup_city 城市查询

{
  "keyword": "北京"                                              # 城市关键词（支持模糊匹配）
}

六、REST API 调用示例

公开 HTTP 接口 /api/v1/public/chart/calculate 本身已支持 ChartRequest 的全部字段，以下仅补充示例。

简易调用

curl -s -X POST "https://xn--rsso0d.cn/api/v1/public/chart/calculate" \\
  -H "Content-Type: application/json" \\
  -d '{
    "birth_date": "1995-06-15",
    "birth_time": "14:30",
    "birth_lon": 116.407,
    "birth_lat": 39.904,
    "timezone": 8,
    "gender": "male",
    "xiu_method": "huangdaohuigui"
  }' | python -m json.tool

专业调用

curl -s -X POST "https://xn--rsso0d.cn/api/v1/public/chart/calculate" \\
  -H "Content-Type: application/json" \\
  -d '{
    "birth_date": "1995-06-15",
    "birth_time": "14:30",
    "birth_lon": 116.407,
    "birth_lat": 39.904,
    "timezone": 8,
    "gender": "male",
    "xiu_method": "chidao_zhengan",
    "coord_system": "chidao",
    "node_arrangement": "south_north",
    "node_calculation": "fitted",
    "apogee_calculation": "fitted",
    "ming_gong_method": "horizon_rising",
    "child_limit": 10
  }' | python -m json.tool

REST API 流年调用

curl -s -X POST "https://xn--rsso0d.cn/api/v1/public/chart/liunian" \\
  -H "Content-Type: application/json" \\
  -d '{
    "birth_date": "1995-06-15",
    "birth_time": "14:30",
    "birth_lon": 116.407,
    "birth_lat": 39.904,
    "timezone": 8,
    "gender": "male",
    "xiu_method": "huangdaohuigui",
    "liunian_year": 2026
  }' | python -m json.tool

七、xiu_method 全量取值表

以下为所有可用盘制。列名为前端设置标签→选项文本→参数值→坐标系。

八、各枚举字段取值表

列名为前端设置标签 → 设置内选项文本 → 参数值。

罗计排列（设置标签：罗计排列）

默认 计北罗南（south_north）：计都=北交点，罗睺=南交点。

时间类型（设置标签：时间类型）

罗睺计算（设置标签：罗睺计算）

月孛计算（设置标签：月孛计算）

紫炁计算（设置标签：紫炁计算）

节气计算（设置标签：节气计算）

命宫起法（设置标签：命宫起法）

身宫起法（设置标签：身宫起法）

昼夜设置（设置标签：昼夜设置）

数字参数

布尔开关

九、常见错误

给 AI / 开发者的重要提示

常见问题（FAQ）

FAQ 1：七政四余是什么？

七政四余是中国古代占星命理体系：以人出生时的"七政"（日、月、木、火、土、金、水）与"四余"（罗睺、计都、紫炁、月孛）共十一曜，落入十二宫、二十八宿的位置与相互关系，来推断人的命局与运程。

核心构成：

FAQ 2：七政四余怎么排盘？

排盘就是按出生年月日时，先定命宫身宫，再推算十一曜所躔宫度与化曜，最后排定大限。核心流程可概括为五步：定盘制 → 安命身 → 布星曜 → 起化曜 → 排限运。

1. 定盘制：选定坐标系（黄道/赤道）× 量天尺（恒星制/回归制），并取生年最近历元的宿度尺。
2. 安命身：由出生时太阳躔度推命宫（静盘以卯为命宫），取太阴所躔宿度定身宫。
3. 布星曜：将日、月、五星、四余依行度排入十二宫、二十八宿。
4. 起化曜：按生年天干（或年干支）化出福、禄、贵、刑等神煞。
5. 排限运：起童限、洞微大限，确定各年所行宫度。

FAQ 3：七政四余和八字、紫微斗数有什么区别？

三者都论命，但底层体系完全不同：八字用干支五行十神，紫微用南北斗星与十四主星，七政四余用十一曜 + 二十八宿的天文星盘。许多术语（命宫、身宫、财帛宫、文昌、驿马）虽同名，定义却不同，不能直接套用。

FAQ 4：七政四余的星曜有哪些？各代表什么？

共十一曜：七政（日、月、木、火、土、金、水）为实星，主显象与实质能量；四余（罗睺、计都、紫炁、月孛）为虚星，主隐情与潜在变数。各星曜的先天属性与吉凶倾向如下：

FAQ 5：七政四余怎么看盘？看盘步骤是什么？

看盘按"排盘 → 定原局 → 看盘起手 → 察限运 → 定格局 → 断层次 → 推流年"七步推进，前一步是后一步的输入。

1. 排盘：得命身宫、十二宫度、星曜落宫、化曜。
2. 定原局：定身命二主、宫度主、恩用仇难、四时昼夜旺衰、四正夹拱。
3. 看盘起手：起手式、观星要诀、宫度活变、纬克经论。
4. 察限运：童限、洞微大限、小限、飞限、太岁、流年。
5. 定格局：以星定格、以宫定格、八格赋、女命格。
6. 断富贵层次：富档位 × 贵档位双维度综合判定。
7. 推流年：结合限运与流年神煞，断具体事件。

实战要点：先看命主、身主强弱与所落宫位（强宫旺、弱宫衰），再看星曜庙旺与经纬生克，最后结合大限流年应期。

FAQ 6：命宫、身宫是什么？怎么定？

命宫是十二宫的第一宫，代表先天本性与命运框架；身宫代表后天实况与发展。在七政四余中，安身立命的方式有多种，常用的是安命以"卯为命宫"（四正卯立命，属天球辰次属性，非地平上升点），由出生时的太阳躔度推得；身宫（果老主流）取太阴所躔宿度的"度主"为身主。

• 命主 = 命宫所属主宰星（查宫主表：子丑土、寅亥木、卯戌火、辰酉金、巳申水、午日、未月）。
• 身主 = 太阴躔度之度主（如月躔角宿，角属木，则身主为木）。
• 十二宫次序（以命宫为第一，逆布）：命、财帛、兄弟、田宅、男女、奴仆、妻妾、疾厄、迁移、官禄、福德、相貌。
• 七强宫：命、官禄、田宅、妻妾、男女、福德、财帛（居强宫者旺）；五弱宫：兄弟、奴仆、疾厄、相貌、迁移（临弱宫者衰）。

FAQ 7：什么是庙旺、入垣、升殿、落陷？

这是描述星曜吉凶状态的术语：庙、旺、乐、入垣、升殿为五种吉状态；怒宫、陷地为凶状态。判断层级不同——"庙/旺/乐/喜/入垣"论宫，"升殿"论宿（星曜躔其本宿）。

例：太阳"庙在戌方、旺在戌宫白羊十九度、升殿在奎宿、乐在午宫"。同星在不同状态，吉凶倾向完全不同。

FAQ 8：七政四余用什么盘制？恒星制和回归制哪个准？

七政排盘有"黄道/赤道 × 恒星/回归"组合出的多套盘制（用制），天官手记支持盘制有【黄道盘制】（回归今宿 / 回归古宿 / 古宿岁差 / 郑案恒星）与【赤道盘制】（回归今宿 / 古宿岁差 / 郑案今宿 / 回归古宿 / 果老星宗）。不存在唯一"最准"的盘制，只是观察的角度不同而已。——同一生辰用不同盘制，宫度定位会不同，须按所从流派与历元取尺。

• 坐标系之争：中国古制以天赤道恒星坐标为正统（恒星定点、太阳随岁差漂移）；黄道回归制把春分点钉在白羊戌零度。二者哲学不同，不可混称。
• 三用制（黄道系）：今制（黄道现时划分）、古宿制（古人宿度）、调整岁差后宿制。
• 周天总度数轴：有"360 古度均分"（每宫恒 30 度）与"365.25 实测宿度"（每宫约 30.438 度）两套，与坐标系轴正交，取尺须两轴 × 历元同时对齐。
• 岁差影响：宿度随历元漂移（约 71.6 年退 1 度），旧尺排盘须依岁差校正，否则命宫/宿度错位。

FAQ 9：化曜是什么？怎么推算？

化曜是依生年天干（或年干支），将十一曜化出福、禄、贵、刑、耗等神煞的一组起例，用于细化吉凶。它分三类，推算轨道不同，须严格区分：

FAQ 10：七政四余准不准？新手怎么入门？

七政四余是传统命理体系，其"准验"属个人主观体验；但七政四余确实以应验清晰、简单、明确而著称，新手入门建议先打牢三块基础，再读原典：

1. 打基础：搞定干支、五行、二十八宿等概念；
2. 学核心：掌握排盘、星曜特性和宫位含义；
3. 练应用：深入洞微大限法等推断技巧，结合天官.cn平台的大量案例，进行研习；

FAQ 11：如何查看神煞含义？

双击星盘上神煞圈层内的神煞名称，即可弹出该神煞的释义。释义来源可在「设置 → 神煞释义」中切换（默认释义 / 虚怀七政专用，后者需对应权限）；无释义时显示"暂无释义"。

FAQ 12：如何查看某颗星曜的详细信息？

轻点星盘上的星曜（日、月、金、木、水、火、土、计、罗、孛、炁），弹出星曜详情，包含：状态（庙旺乐喜怒垣殿、迟留伏逆速等）、行度（宫位+宫内度+星宿+宿度）、化曜、同经、同络、余奴（仅木火土水）、三方/对宫内的星曜、以及躔某五行度的同宿星。流年星曜轻点后显示带"流年"标识的流年信息。

FAQ 13：如何切换本命盘与流年盘？

右侧按钮栏最上方有「本命 / 流年」切换按钮，点亮哪一侧即显示对应星盘。切到流年模式后，点击调时图标，选择要推演的本命/流年时间，系统基于本命盘推算流年盘。

FAQ 14：右侧那一排导航按钮（排盘 / 四柱 / 化曜 / 相位 / 批断 / 星案 / 命库 …）分别是什么？

• 排盘（生辰）：填写/修改出生时间、地点、性别，点击即排盘。
• 四柱：八字四柱、大运、流年、十神、纳音等。
• 化曜：本命与流年化曜（果老十一曜 / 天官十神）对照表。
• 相位：星曜黄经黄纬、二十八宿基点、状态等。
• 批断：批断文案输入（支持语音）、导出 / 分享星盘。
• 星案：你个人的命盘档案（搜索、查看、导入导出、云端同步）。
• 命库：公开的真实案例库，可按出身、学历、职业、婚姻等维度筛选参考。
• 设置 / 关于：参数配置与版本、备案信息。登录后还会出现「我的」。
• 面板收起时点右侧「◀」可展开，展开时点「▶」可收起，给星盘让出更大空间。

FAQ 15：如何切换星盘主题（暗夜 / 宣纸 / 素白）？

进入「设置」面板，找到"主题"下拉，可选：跟随系统 / 暗夜 / 宣纸 / 素白。星盘配色（暗夜、宣纸、素白）与整体界面主题同步切换，设置即时生效并自动记住。

FAQ 16：如何调整排盘参数（星制、盘型、真太阳时、化曜/宫度标注、罗计排列等）？

在「设置」面板中调整，常见项：

• 星制：黄道回归今宿 / 郑案恒星 / 古法恒星 / 七政凌犯盘；
• 盘型：黄道（tropical）/ 恒星（sidereal）；
• 真太阳时：勾选表示输入的是墙上时间，排盘前先做经度+均时差换算；
• 化曜标注：果老 / 天官 / 不显示；宫度标注：显示 / 不显示；
• 罗计排列：计南罗北 / 计北罗南；角距线：开 / 关；
• 命宫 / 身宫起法、昼夜判定、大限宫数、节气算法等。

改任意一项会后台静默重算，不打断当前查看。

FAQ 17：如何只显示我想看的神煞、并改吉凶配色？

「设置」里可分别勾选本命神煞和流年神煞要显示的项目（默认全显），也能调整神煞分类配色：吉神 / 凶煞 / 平平 / 重复 / 其他。星盘上的神煞会按分类着色，便于一眼区分吉凶。

FAQ 18：如何保存和管理我的命盘档案（星案）？

进入「星案」面板：

• 在排盘和批断界面均可对命例进行保存；
• 点开任一条即可自动回填生辰并重新排盘；
• 工具栏支持导入 / 导出（CSV、Excel）、上传云端 / 下载本地、清空本地或云端；
• 在单条详情里可把案例共享到「命库」公库，或删除该条。

本地存档默认存在本机，登录后可选同步到服务器（同步状态在详情中显示"已同步 / 仅本地"）。

FAQ 19：如何用语音写批断，并把星盘保存成图片？

在「批断」面板用麦克风按钮说话，语音识别结果会实时写入批断输入框（跨面板持续，不丢失）。批断面板右上角菜单可：保存图片（把当前星盘导出为 PNG）、复制批断文案、分享等。移动端还会在启动时静默检查更新，新版本就绪后可一键安装。

FAQ 20：如何微调出生时间做"调时"？

星盘附近有一个浮动的 ⏱ 图标，点开是时间微调弹窗，可前后微调出生时辰，调整后后台静默重算星盘与八字，方便对比不同时辰的盘局差异。要彻底按新时间重排，回到「排盘」面板点"排盘"按钮即可。