# 释玄斋易通宝 · 玄学排盘 API（完整版）

> 本文档面向 AI 模型与 Agent 开发者，完整列出全部接口、参数与调用示例。
> 基础地址：`https://www.zjhl.fjzyi.com/api/calc`

## 调用约定

- 鉴权：请求头 `Authorization: Bearer <API_KEY>`
- 请求体：`Content-Type: application/json`
- 成功响应：`{ ok: true, tool, data, creditsUsed, creditsRemaining, plan, disclaimer }`
- 错误响应：`{ ok: false, error, code? }`
- 鉴权失败 HTTP 401；余额不足 HTTP 402；限流 HTTP 429；参数错误 HTTP 400
- 限流：默认每 IP 每分钟 60 次
- 缓存：相同入参 1 小时内命中缓存不重复扣费（响应含 `cached: true`）

## 八字排盘（bazi）

`POST https://www.zjhl.fjzyi.com/api/calc/v1/bazi`　分类：命理　消耗：10 积分/次

根据公历出生时间排定八字四柱（年柱、月柱、日柱、时柱），并给出日主、十神、纳音、藏干、五行计数、神煞。用于命理分析、性格/运势推断。

参数：
- `year` (integer，必填)：出生年份，公历 1900-2100
- `month` (integer，必填)：出生月份 1-12
- `day` (integer，必填)：出生日 1-31
- `hour` (integer，必填)：出生时辰 0-23（24小时制）
- `gender` (string，可选，可选值：男/女，默认：男)：性别
- `isLunar` (boolean，可选，默认：false)：入参是否为农历（默认 false=公历）
- `isLeapMonth` (boolean，可选，默认：false)：是否闰月

示例：
```bash
curl -X POST https://www.zjhl.fjzyi.com/api/calc/v1/bazi \
  -H "Authorization: Bearer $SXZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":1990,"month":5,"day":20,"hour":14,"gender":"男"}'
```

## 姓名分析（测名/公司名）（ceming）

`POST https://www.zjhl.fjzyi.com/api/calc/v1/ceming`　分类：命名　消耗：10 积分/次

分析姓名或公司名的五行搭配、三才五格、音形义吉凶，给出评分与改进建议。type 可选 person（人名）或 company（公司/品牌名）。

参数：
- `name` (string，必填)：待分析的名字（中文）
- `type` (string，可选，可选值：person/company，默认：person)：分析类型
- `gender` (string，可选，可选值：男/女，默认：男)：人名时的性别

示例：
```bash
curl -X POST https://www.zjhl.fjzyi.com/api/calc/v1/ceming \
  -H "Authorization: Bearer $SXZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"罗李华","type":"person","gender":"男"}'
```

## 择日通胜（黄历宜忌）（huangli）

`POST https://www.zjhl.fjzyi.com/api/calc/v1/huangli`　分类：择吉　消耗：1 积分/次

给定公历日期，返回当日干支、生肖、冲煞、建除十二神，以及宜/忌事项清单，用于择吉、开业、婚嫁、动土等选日。

参数：
- `year` (integer，必填)：公历年份
- `month` (integer，必填)：公历月份 1-12
- `day` (integer，必填)：公历日 1-31

示例：
```bash
curl -X POST https://www.zjhl.fjzyi.com/api/calc/v1/huangli \
  -H "Authorization: Bearer $SXZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":2026,"month":11,"day":18}'
```

## 观音灵签（guanyin）

`POST https://www.zjhl.fjzyi.com/api/calc/v1/guanyin`　分类：占卜　消耗：1 积分/次

抽取观音灵签（1-100 签），返回签号、签等（上上/上/中/下）、签诗、解曰、寓意与建议。lot 不填则随机抽一签。

参数：
- `lot` (integer，可选，默认：0)：指定签号 1-100；不填则随机

示例：
```bash
curl -X POST https://www.zjhl.fjzyi.com/api/calc/v1/guanyin \
  -H "Authorization: Bearer $SXZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lot":18}'
```

## 生肖运程（shengxiao）

`POST https://www.zjhl.fjzyi.com/api/calc/v1/shengxiao`　分类：运势　消耗：1 积分/次

给定生肖（或出生年份），返回该生肖的性格特征、年度运势、三合六合贵人、相冲相害，以及开运建议。

参数：
- `zodiac` (string，可选)：生肖名（鼠牛虎兔龙蛇马羊猴鸡狗猪）；不填可用 year
- `year` (integer，可选)：出生年份，用于推导生肖

示例：
```bash
curl -X POST https://www.zjhl.fjzyi.com/api/calc/v1/shengxiao \
  -H "Authorization: Bearer $SXZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"zodiac":"龙"}'
```

## 六爻占卜（liuyao）

`POST https://www.zjhl.fjzyi.com/api/calc/v1/liuyao`　分类：占卜　消耗：10 积分/次

依据传统六爻（文王六十四卦）起卦解卦：支持按时间起卦、手动摇卦(6枚硬币)、数字起卦、文字测字、随机起卦。返回本卦/变卦/互卦/错卦/综卦、六亲、六神与综合解读。

参数：
- `method` (string，可选，可选值：time/coins/numbers/text/random，默认：random)：起卦方式
- `year` (integer，可选)：（method=time 时）起卦公历年份
- `month` (integer，可选)：（method=time 时）月份 1-12
- `day` (integer，可选)：（method=time 时）日 1-31
- `hour` (integer，可选)：（method=time 时）时辰 0-23
- `coins` (array，可选)：（method=coins 时）6 个数字，每项为 6/7/8/9
- `numbers` (string，可选)：（method=numbers 时）6 个数字串，空格/逗号分隔，如 "7 8 6 9 7 8"
- `text` (string，可选)：（method=text 时）用于测字起卦的中文文字

示例：
```bash
curl -X POST https://www.zjhl.fjzyi.com/api/calc/v1/liuyao \
  -H "Authorization: Bearer $SXZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"method":"random"}'
```

## 奇门遁甲排盘（qimen）

`POST https://www.zjhl.fjzyi.com/api/calc/v1/qimen`　分类：术数　消耗：3 积分/次

奇门遁甲转盘排盘：真太阳时换算、定局（拆补/置闰）、值符值使、天地人神四盘（九宫地盘、天盘九星、天盘干、八门、八神）、旬空与驿马。jia 可选时/日/月/年家奇门。

参数：
- `year` (integer，必填)：公历年份
- `month` (integer，必填)：公历月份 1-12
- `day` (integer，必填)：公历日 1-31
- `hour` (integer，必填)：时辰 0-23
- `minute` (integer，可选，默认：0)：分钟 0-59
- `longitude` (number，可选，默认：120)：观测地经度（度），默认 120（中原时）
- `jia` (string，可选，可选值：时/日/月/年，默认：时)：家奇门类型
- `method` (string，可选，可选值：拆补/置闰，默认：拆补)：定局法
- `useTrue` (boolean，可选，默认：true)：是否换算真太阳时（默认 true）

示例：
```bash
curl -X POST https://www.zjhl.fjzyi.com/api/calc/v1/qimen \
  -H "Authorization: Bearer $SXZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":2026,"month":11,"day":18,"hour":14,"jia":"时","method":"拆补"}'
```

## 紫微斗数（ziwei）

`POST https://www.zjhl.fjzyi.com/api/calc/v1/ziwei`　分类：命理　消耗：3 积分/次

紫微斗数命盘：十二宫、十四主星、四化（禄权科忌）、乙级星/神煞、命宫/身宫、五行局。复用前端纯算法内核（ziweicore.js + ziweistar 常量，已剥离 jQuery/UI 依赖）。

参数：
- `year` (integer，必填)：公历年份
- `month` (integer，必填)：月份 1-12
- `day` (integer，必填)：日 1-31
- `hour` (integer，必填)：时辰 0-23
- `gender` (string，可选，可选值：男/女，默认：男)：性别
- `isLunar` (boolean，可选，默认：false)：生辰是否已为农历
- `isLeapMonth` (boolean，可选，默认：false)：农历闰月标记

示例：
```bash
curl -X POST https://www.zjhl.fjzyi.com/api/calc/v1/ziwei \
  -H "Authorization: Bearer $SXZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":1990,"month":5,"day":20,"hour":14,"gender":"男"}'
```

## 八字合婚（hehun）

`POST https://www.zjhl.fjzyi.com/api/calc/v1/hehun`　分类：合婚　消耗：3 积分/次

男女双方八字合婚：年/月/日/时柱生肖与十神关系、五行互补、喜用神互补、神煞、三元命卦、星座配对综合分析与建议。输入 male/female 各自公历生辰即可。

参数：
- `male` (object，必填)：男方：{year,month,day,hour,gender}
- `female` (object，必填)：女方：{year,month,day,hour,gender}

示例：
```bash
curl -X POST https://www.zjhl.fjzyi.com/api/calc/v1/hehun \
  -H "Authorization: Bearer $SXZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"male":{"year":1990,"month":5,"day":20,"hour":14,"gender":"男"},"female":{"year":1992,"month":8,"day":12,"hour":10,"gender":"女"}}'
```

## 塔罗占卜（taluo）

`POST https://www.zjhl.fjzyi.com/api/calc/v1/taluo`　分类：占卜　消耗：1 积分/次

塔罗牌阵占卜：支持单张牌、三张牌（过去/现在/未来）、凯尔特十字（10张）、关系/职业/决策/灵性/健康等 8 种牌阵。随机抽牌并给出正/逆位牌义与逐位释义。spread 可选 single/three/celtic/relationship/career/decision/spiritual/health。

参数：
- `spread` (string，可选，可选值：single/three/celtic/relationship/career/decision/spiritual/health，默认：three)：牌阵
- `seed` (integer，可选)：随机种子，用于复现同一抽牌结果

示例：
```bash
curl -X POST https://www.zjhl.fjzyi.com/api/calc/v1/taluo \
  -H "Authorization: Bearer $SXZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"spread":"three"}'
```

## 周公解梦（zhougong）

`POST https://www.zjhl.fjzyi.com/api/calc/v1/zhougong`　分类：占卜　消耗：1 积分/次

输入梦境关键词（如「蛇」「结婚」「掉牙」），从传统梦境库匹配最相关条目，返回梦境寓意、吉凶、建议与心理学/传统/现代多维度解读。

参数：
- `keyword` (string，必填)：梦境关键词，如「蛇」「结婚」「掉牙」「考试」
- `limit` (integer，可选，默认：10)：返回条数上限

示例：
```bash
curl -X POST https://www.zjhl.fjzyi.com/api/calc/v1/zhougong \
  -H "Authorization: Bearer $SXZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"蛇"}'
```

## 风水罗盘（坐向分金）（luopan）

`POST https://www.zjhl.fjzyi.com/api/calc/v1/luopan`　分类：风水　消耗：10 积分/次

输入方位角（deg，北=0顺时针）或坐山名（mountain，如「子」「午」）或地支（branch），返回二十四山坐向、后天/先天卦、九星、二十八宿、纳音等罗盘信息。

参数：
- `deg` (number，可选)：方位角（度），北=0，顺时针。与 mountain/branch 三选一
- `mountain` (string，可选)：坐山名（二十四山之一，如「子」「午」「艮」）
- `branch` (string，可选)：地支（子丑寅卯…亥）
- `year` (integer，可选)：用于查询该年纳音五行

示例：
```bash
curl -X POST https://www.zjhl.fjzyi.com/api/calc/v1/luopan \
  -H "Authorization: Bearer $SXZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"deg":0}'
```

## 金口诀（四课三传）（jinkoujue）

`POST https://www.zjhl.fjzyi.com/api/calc/v1/jinkoujue`　分类：术数　消耗：10 积分/次

大六壬金口诀排盘：输入公历生辰、地分（difen，如「子」）与时辰，排出人元/贵神/将神/地分四课，给出月将、空亡、格局、五行分布、神煞、合冲与文字断语。可选真太阳时与中气过宫月将法。

参数：
- `year` (integer，必填)：公历年份
- `month` (integer，必填)：公历月份 1-12
- `day` (integer，必填)：公历日 1-31
- `hour` (integer，可选，默认：12)：时辰 0-23（也可传 shichen 时辰地支或 timeStr）
- `shichen` (string，可选)：时辰地支，如「子」「午」
- `timeStr` (string，可选)：时间串 "HH:MM"
- `difen` (string，可选，默认：子)：地分地支（子丑寅卯…亥）
- `fangIdx` (integer，可选)：地分索引 0-11（与 difen 二选一）
- `useTrue` (boolean，可选，默认：false)：是否换算真太阳时
- `jiangQu` (string，可选，可选值：liuhe/zhongqi，默认：liuhe)：月将法
- `lon` (number，可选)：观测地经度（度），useTrue=true 时生效
- `lat` (number，可选)：观测地纬度（度）
- `placeText` (string，可选)：地点备注

示例：
```bash
curl -X POST https://www.zjhl.fjzyi.com/api/calc/v1/jinkoujue \
  -H "Authorization: Bearer $SXZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":2026,"month":11,"day":18,"hour":14,"difen":"子"}'
```

## 事项择日（选吉日）（zeri）

`POST https://www.zjhl.fjzyi.com/api/calc/v1/zeri`　分类：择吉　消耗：10 积分/次

依据事项（结婚/开业/动土/搬家/出行/安葬/签约等）与日期范围，逐日查黄历宜忌，筛选该事项的吉日清单并标注每日建除十二神与宜忌。事项支持口语别名（如「结婚」自动匹配「嫁娶」）。

参数：
- `matter` (string，必填)：事项名，如「结婚」「开业」「动土」「搬家」「出行」「安葬」「签约」
- `startDate` (string，必填)：起始日期 yyyy-mm-dd
- `days` (integer，可选，默认：30)：查询天数（1-92，默认 30）

示例：
```bash
curl -X POST https://www.zjhl.fjzyi.com/api/calc/v1/zeri \
  -H "Authorization: Bearer $SXZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"matter":"结婚","startDate":"2026-11-18","days":30}'
```

## 大六壬（天地盘·四课三传）（dlr）

`POST https://www.zjhl.fjzyi.com/api/calc/v1/dlr`　分类：术数　消耗：3 积分/次

大六壬起课排盘：按公历时间（可选真太阳时）排出四柱干支、月将、天地盘、十二天将、四课、三传（初/中/末传及九宗门起法）、遁干、六亲、神煞，并给出课体释义（如「重审」「元首」，附《六壬大全·九宗门》原文详解与吉凶）。适用于占事、择时、人事吉凶判断。

参数：
- `year` (integer，可选)：公历年份（默认当前年）
- `month` (integer，可选)：公历月份 1-12（默认当前月）
- `day` (integer，可选)：公历日 1-31（默认当前日）
- `hour` (integer，可选)：小时 0-23（默认当前时）
- `minute` (integer，可选，默认：0)：分钟（默认 0）
- `longitude` (number，可选，默认：116.41)：观测地经度（度），真太阳时换算用，默认 116.41（北京）
- `useTrueSolarTime` (boolean，可选，默认：true)：是否用真太阳时（默认 true）
- `nightZiRule` (string，可选，可选值：nextDay/sameDay，默认：nextDay)：子时换日规则：nextDay（夜子归次日，默认）| sameDay
- `guirenRule` (string，可选，默认：traditional)：贵人起例：traditional（默认）| 其它起例
- `shehaiRule` (string，可选，默认：depth)：涉害深浅取法：depth（默认）| 备选
- `yearBoundary` (string，可选，可选值：lichun/zhengyue，默认：lichun)：年界：lichun（立春，默认）| zhengyue（正月初一）
- `yuejiang` (integer，可选)：手动指定月将地支索引 0-11（子=0，丑=1…亥=11）；不传则按中气自动取
- `zhanshi` (integer，可选)：手动指定占时地支索引 0-11；不传则按时辰自动取

示例：
```bash
curl -X POST https://www.zjhl.fjzyi.com/api/calc/v1/dlr \
  -H "Authorization: Bearer $SXZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":2026,"month":11,"day":18,"hour":14,"longitude":116.41}'
```

## 小孩起名（喜用神取名）（qiming）

`POST https://www.zjhl.fjzyi.com/api/calc/v1/qiming`　分类：命名　消耗：3 积分/次

按出生生辰排四柱、推喜用神与忌神，以五行用字池筛选字库并组合姓名，按五格数理、人格、三才、音律、字形综合评分排序推荐。提供每个候选名的笔画、五行、音调、五格数理与三才配置详解。适合家长为婴幼儿取名。

参数：
- `surname` (string，必填)：姓氏（1-2 个汉字）
- `gender` (string，可选，可选值：男/女，默认：男)：性别：男/女
- `year` (integer，可选)：出生年（公历）；提供生辰则按喜用神筛选用字
- `month` (integer，可选)：出生月（公历）
- `day` (integer，可选)：出生日（公历）
- `hour` (integer，可选)：出生时（0-23）
- `minute` (integer，可选，默认：0)：出生分
- `calendarType` (string，可选，可选值：solar/lunar，默认：solar)：历法：solar=公历，lunar=农历
- `isLeapMonth` (boolean，可选，默认：false)：农历是否闰月
- `len` (integer，可选，默认：2)：名字字数：1 或 2
- `limit` (integer，可选，默认：12)：返回推荐数量（1-50）

示例：
```bash
curl -X POST https://www.zjhl.fjzyi.com/api/calc/v1/qiming \
  -H "Authorization: Bearer $SXZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"surname":"张","gender":"男","year":2024,"month":6,"day":15,"hour":10,"limit":10}'
```

## 公司起名（字号）（gsqm）

`POST https://www.zjhl.fjzyi.com/api/calc/v1/gsqm`　分类：命名　消耗：3 积分/次

按行业所属五行（科技/餐饮/金融/地产/文化/医疗/服装/物流/农业/法律/制造/传媒）取用字池，生成公司字号并按五格数理与三才配置评分排序，输出字号、全名笔画数理、吉凶等级与卦象含义。适合企业注册取名、品牌命名。

参数：
- `industry` (string，可选)：行业名称（科技/餐饮/金融/地产/文化/医疗/服装/物流/农业/法律/制造/传媒）
- `industryWx` (integer，可选)：行业五行编码：0水 1木 2火 3土 4金（industry 传入时自动换算）
- `suffix` (string，可选，默认：有限公司)：公司后缀，如 有限公司 / 股份有限公司 / 工作室
- `prefix` (string，可选)：公司前缀，如 北京
- `len` (integer，可选，默认：2)：字号字数：1 或 2
- `limit` (integer，可选，默认：12)：返回推荐数量（1-50）

示例：
```bash
curl -X POST https://www.zjhl.fjzyi.com/api/calc/v1/gsqm \
  -H "Authorization: Bearer $SXZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"industry":"科技","suffix":"有限公司","prefix":"北京","limit":10}'
```

## 八宅排盘（bazhai）

`POST https://www.zjhl.fjzyi.com/api/calc/v1/bazhai`　分类：风水　消耗：10 积分/次

八宅堪舆排盘：按房屋坐向（震巽离坤兑乾坎艮八宅）排出九宫八卦方位，标注每宫的八星（生气/天医/延年/伏位/绝命/五鬼/六煞/祸害）、九星（辅弼/文曲/巨门/廉贞/破军/禄存/贪狼/武曲）、五行与吉凶倾向，并给出卦位释义与布局建议。适用于家居风水与办公室调理。

参数：
- `direction` (string，必填)：房屋坐向宅型（震宅/巽宅/离宅/坤宅/兑宅/乾宅/坎宅/艮宅）或编号 1-8
- `detail` (boolean，可选，默认：true)：是否返回卦位释义与布局建议全文

示例：
```bash
curl -X POST https://www.zjhl.fjzyi.com/api/calc/v1/bazhai \
  -H "Authorization: Bearer $SXZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"direction":"震宅"}'
```

## 玄空排盘（九运）（xkfs）

`POST https://www.zjhl.fjzyi.com/api/calc/v1/xkfs`　分类：风水　消耗：6 积分/次

玄空飞星排盘：按立向年份（1864-2043）定三元九运，取下卦或替卦起星，排出九宫运星/山星/向星分布，判定旺山旺向、上山下水、双星会坐、双星会向、伏吟反吟、五黄到山到向等格局，并给出九星旺生衰死状态与星曜详解。适用于家居与商业地产风水布局。

参数：
- `year` (integer，必填)：立向公历年份（1864-2043）
- `direction` (string，必填)：坐向（24 山之一，如 子山午向 / 午山子向）
- `tiGuaType` (string，可选，可选值：xia/ti，默认：xia)：起星方式：xia=下卦，ti=替卦
- `detail` (boolean，可选，默认：true)：是否返回九星详解与宫位代表

示例：
```bash
curl -X POST https://www.zjhl.fjzyi.com/api/calc/v1/xkfs \
  -H "Authorization: Bearer $SXZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":2026,"direction":"子山午向"}'
```

## 阴宅速查（阴宅堪舆）（yinzhai）

`POST https://www.zjhl.fjzyi.com/api/calc/v1/yinzhai`　分类：风水　消耗：6 积分/次

阴宅堪舆速查：按坐山（24 山）与兼向（正针/左兼/右兼）排定坐向、度数与四局，给出杨公十二水法原文解析与吉凶水口、大空亡与龟甲空亡判定、仙命合山生克判断（可传出生年或干支）、流年太岁岁破三煞紫白飞星，以及赖公拨砂消砂生克与二十八宿参考。适用于阴宅选址与安葬择吉。

参数：
- `mountain` (string，必填)：坐山（24 山：壬子癸丑艮寅甲卯乙辰巽巳丙午丁未坤申庚酉辛戌乾亥）
- `jian` (string，可选，可选值：0/L/R，默认：0)：兼向分金：0=正针不兼，L=左兼，R=右兼
- `outlet` (string，可选)：水口方向（向 或十二长生位：长生/沐浴/冠带/临官/帝旺/衰/病/死/墓/绝/胎/养）
- `xianming` (string，可选)：仙命出生年（4 位年份如 1950）或干支（如 庚寅）
- `year` (integer，可选，默认：2026)：流年年份（1900-2100）
- `shas` (string，可选)：砂峰列表 JSON 字符串，如 [{"shan":"子","shape":"文笔"}]

示例：
```bash
curl -X POST https://www.zjhl.fjzyi.com/api/calc/v1/yinzhai \
  -H "Authorization: Bearer $SXZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mountain":"壬","jian":"0","outlet":"向","year":2026}'
```

## 鲁班尺（门公尺·丁兰尺）（luban）

`POST https://www.zjhl.fjzyi.com/api/calc/v1/luban`　分类：器物　消耗：1 积分/次

按尺寸（厘米）换算台寸，并依《鲁班尺》门公尺与《丁兰尺》阴尺两套量法各查八寸/十寸吉凶断语（如「财至」「死别」「迎福」），给出双尺吉凶与综合判语。适用于家具、门��、床铺、桌案尺寸吉凶择取。

参数：
- `cm` (number，必填)：尺寸（厘米）

示例：
```bash
curl -X POST https://www.zjhl.fjzyi.com/api/calc/v1/luban \
  -H "Authorization: Bearer $SXZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cm":81}'
```

## 号码分析（手机号）（shouji）

`POST https://www.zjhl.fjzyi.com/api/calc/v1/shouji`　分类：号码　消耗：1 积分/次

手机号码分析：查七星磁场（天医/生气/延年/绝命/六煞/五鬼/伏位）滑动分布与磁场强度，按数字五行统计旺衰与缺失，按后四位起易经卦象，综合五项基础分与磁场、连号、号段、地域加分给出百分制评分与等级，并输出财运、事业、健康、婚姻四维分析与幸运色、幸运数。

参数：
- `phone` (string，必填)：手机号码（11 位数字）

示例：
```bash
curl -X POST https://www.zjhl.fjzyi.com/api/calc/v1/shouji \
  -H "Authorization: Bearer $SXZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"13800138000"}'
```

## 星座解析（运程·合盘）（xingzuo）

`POST https://www.zjhl.fjzyi.com/api/calc/v1/xingzuo`　分类：星座　消耗：1 积分/次

十二星座解析：输出基础性格画像、优缺点、星座配对与事业倾向，并按今日/本周/本月/本年四种周期给出九维运程评分与逐项解读，附幸运色/数字/宝石/花/方位/动物与开运建议；支持指定关系类型（爱情/友情/同事/家庭）查看与十二宫兼容度矩阵，并可指定对方星座做合盘详情。

参数：
- `zodiac` (string，必填)：星座名称（白羊座/金牛座/双子座/巨蟹座/狮子座/处女座/天秤座/天蝎座/射手座/摩羯座/水瓶座/双鱼座）
- `period` (string，可选，可选值：daily/weekly/monthly/yearly，默认：daily)：运程周期：daily/weekly/monthly/yearly
- `relationship` (string，可选，可选值：love/friendship/colleague/family，默认：love)：关系类型：love/friendship/colleague/family
- `partner` (string，可选)：配对星座（可选，用于合盘详情）

示例：
```bash
curl -X POST https://www.zjhl.fjzyi.com/api/calc/v1/xingzuo \
  -H "Authorization: Bearer $SXZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"zodiac":"白羊座","period":"daily","relationship":"love"}'
```

## 鬼谷定数（guigu）

`POST https://www.zjhl.fjzyi.com/api/calc/v1/guigu`　分类：命理　消耗：6 积分/次

鬼谷定数（前定数）推演：按生辰排四柱、命宫与空亡，以年干加时干共一百组查《鬼谷定数》命数，判出第几数、所属卦象、格局名（如「莺宿野林格」）与诗诀，并给出天将/天飞/天孤等星曜断语、判词原文与基业兄弟行藏婚姻子息六分节诗。适用于命理格局参研。

参数：
- `name` (string，可选)：姓名（可选）
- `gender` (string，可选，可选值：男/女，默认：男)：性别：男/女
- `year` (integer，必填)：出生年（公历）
- `month` (integer，必填)：出生月（公历）
- `day` (integer，必填)：出生日（公历）
- `hour` (integer，必填)：出生时（0-23）
- `minute` (integer，可选，默认：0)：出生分

示例：
```bash
curl -X POST https://www.zjhl.fjzyi.com/api/calc/v1/guigu \
  -H "Authorization: Bearer $SXZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":1990,"month":5,"day":20,"hour":14,"gender":"男"}'
```

## 邵子神数（批命）（shaozi）

`POST https://www.zjhl.fjzyi.com/api/calc/v1/shaozi`　分类：命理　消耗：6 积分/次

邵子神数批命：按生辰排四柱，逐柱给出干支五行、十神、纳音、十二长生旺衰与地支藏干十神；推出命宫（配天秘等二十八星命）、空亡、刻与时辰、节气与五行分布；起八步大运（顺逆、起运岁数与各步流年）；并给出本卦、元堂卦、互卦、变卦的卦名卦辞彖辞断语，以及元辰/纳音/日诗/时柱/天资/品性等邵子原典诗诀。

参数：
- `name` (string，可选)：姓名（可选）
- `gender` (string，可选，可选值：男/女，默认：男)：性别：男/女
- `year` (integer，必填)：出生年（公历）
- `month` (integer，必填)：出生月（公历）
- `day` (integer，必填)：出生日（公历）
- `hour` (integer，必填)：出生时（0-23）
- `minute` (integer，可选，默认：0)：出生分
- `calendarType` (string，可选，可选值：solar/lunar，默认：solar)：历法：solar=公历，lunar=农历
- `isLeapMonth` (boolean，可选，默认：false)：农历是否闰月
- `lateZi` (boolean，可选，默认：false)：是否晚子时（23:00 后）
- `detail` (boolean，可选，默认：true)：是否返回邵子原典诗诀全文

示例：
```bash
curl -X POST https://www.zjhl.fjzyi.com/api/calc/v1/shaozi \
  -H "Authorization: Bearer $SXZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":1956,"month":10,"day":17,"hour":20,"minute":38,"gender":"女"}'
```

## 黄帝内经·道医辩证（daoyi）

`POST https://www.zjhl.fjzyi.com/api/calc/v1/daoyi`　分类：医易　消耗：6 积分/次

黄帝内经道医辩证：据症状清单与舌象、苔色苔质、脉象、寒热、汗出、二便、病程等四诊信息，匹配《黄帝内经》195 个证型，输出主证型、得分与症状匹配率、候选证型排序、精确匹配与别名关联症状、八纲辨证（表里寒热虚实阴阳）、症状自相矛盾与证型互斥提示、合病并病兼夹证分析，并给出经典医籍引用、经方针灸处方、情志调摄与起居饮食调护建议。

参数：
- `symptoms` (string，必填)：症状列表（逗号分隔或 JSON 数组字符串），如 "发热,咳嗽,痰黄黏稠"
- `tongueColor` (string，可选)：舌色（红/淡白/绛红）
- `coatingColor` (string，可选)：苔色（黄/白）
- `coatingThick` (string，可选)：苔厚薄（厚/薄/少苔/剥落/光剥）
- `pulseType` (string，可选)：脉象（数脉/弦脉/实脉/细脉/弱脉/代脉/伏脉/散脉/促脉）
- `tongueShape` (string，可选)：舌形
- `complexion` (string，可选)：面色
- `eyes` (string，可选)：眼神
- `voice` (string，可选)：声音
- `breath` (string，可选)：气息
- `smell` (string，可选)：气味
- `coldHeat` (string，可选)：寒热（发热/恶寒/但寒不热/但热不寒/恶风/往来寒热）
- `sweat` (string，可选)：汗出情况
- `taste` (string，可选)：口味
- `bowelUrinary` (string，可选)：二便
- `duration` (string，可选)：病程（急性/亚急性/慢性）
- `detail` (boolean，可选，默认：true)：是否返回经方针灸与调摄建议全文

示例：
```bash
curl -X POST https://www.zjhl.fjzyi.com/api/calc/v1/daoyi \
  -H "Authorization: Bearer $SXZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"symptoms":"发热,咳嗽,痰黄黏稠,咽痛","tongueColor":"红","coatingColor":"黄","pulseType":"数脉","coldHeat":"发热","duration":"急性"}'
```

## 七政星盘（七政四余）（qizheng）

`POST https://www.zjhl.fjzyi.com/api/calc/v1/qizheng`　分类：星命　消耗：6 积分/次

七政四余星盘：以 JPL Standish 轨道根数与 Meeus 月球公式计算真太阳时下的日月五星与罗睺、计都、月孛、紫炁（三王星可选）黄经黄纬赤经，排出十二宫（命宫至相貌）、宫主星与星曜分布，给出命宫身宫地支、二十八宿宿度与禽星、庙旺落陷、大限十二步、童限、四柱干支与神煞、朔望月相与日出日落。适用于七政四余命盘推演。

参数：
- `year` (integer，必填)：出生年（公历）
- `month` (integer，必填)：出生月（公历）
- `day` (integer，必填)：出生日（公历）
- `hour` (number，必填)：出生时刻（小时，可含小数，如 14.5 表示 14:30）
- `longitude` (number，必填)：出生地经度（东经为正，如 118.06）
- `latitude` (number，必填)：出生地纬度（北纬为正，如 24.48）
- `timezone` (number，可选，默认：8)：时区（东八区为 8）
- `timeMode` (string，可选，可选值：beijing/local/solar，默认：beijing)：时间制：beijing=钟表北京时间，local=地方平时，solar=真太阳时
- `coordinateMode` (string，可选，可选值：ecliptic/equator，默认：ecliptic)：坐标制：ecliptic=黄道制，equator=赤道制
- `useOuterPlanets` (boolean，可选，默认：true)：是否含三王星（天王/海王/冥王）
- `detail` (boolean，可选，默认：true)：是否返回二十八宿全表与格局

示例：
```bash
curl -X POST https://www.zjhl.fjzyi.com/api/calc/v1/qizheng \
  -H "Authorization: Bearer $SXZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":1990,"month":5,"day":20,"hour":14.5,"longitude":118.06,"latitude":24.48}'
```

## 天文占星（西洋星盘）（tianwen）

`POST https://www.zjhl.fjzyi.com/api/calc/v1/tianwen`　分类：星命　消耗：10 积分/次

西洋占星星盘：按出生地经纬度与时区（含真太阳时校正、均时差）计算十大小天体黄经与日行速度（负值为逆行），排出上升点、天顶与十二宫宫头（普拉西德/等宫/波菲利三制），计算行星间合、六合、刑、拱、冲等相位与角距偏差，给出月相与月龄，并输出太阳/月亮/上升/天顶星座、性格内核、情感、事业、人际、健康、财务等结构化文字解读。

参数：
- `year` (integer，必填)：出生年（公历）
- `month` (integer，必填)：出生月（公历）
- `day` (integer，必填)：出生日（公历）
- `hour` (integer，必填)：出生时（0-23）
- `minute` (integer，可选，默认：0)：出生分（0-59）
- `longitude` (number，可选)：经度（东经为正）；与 city 二选一
- `latitude` (number，可选)：纬度（北纬为正）；与 city 二选一
- `city` (string，可选)：城市名（如 泉州、北京）；提供后自动取经纬度
- `houseSystem` (string，可选，可选值：placidus/equal/porphyry，默认：placidus)：宫制：placidus/equal/porphyry
- `timezone` (number，可选，默认：8)：时区（东八区为 8）
- `daylightSaving` (boolean，可选，默认：false)：是否夏令时
- `useTrueSolarTime` (boolean，可选，默认：true)：是否真太阳时校正
- `name` (string，可选)：姓名（可选，用于解读署名）
- `detail` (boolean，可选，默认：true)：是否返回文字解读全文

示例：
```bash
curl -X POST https://www.zjhl.fjzyi.com/api/calc/v1/tianwen \
  -H "Authorization: Bearer $SXZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":1990,"month":5,"day":20,"hour":14,"minute":30,"city":"泉州"}'
```

## MCP 接入

```json
{
  "mcpServers": {
    "shixuanzhai": {
      "type": "http",
      "url": "https://www.zjhl.fjzyi.com/api/calc/mcp",
      "headers": {
        "Authorization": "Bearer $SXZ_API_KEY"
      }
    }
  }
}
```

## OpenAI function-calling 接入

1. `GET https://www.zjhl.fjzyi.com/api/calc/v1/openai-tools` 取回 tools 数组
2. 随请求传给模型：`{ "model": "gpt-4o", "tools": [...], "messages": [...] }`
3. 模型返回 `tool_calls` 时，按 `function.name`（去掉 `sxz_` 前缀）调用 `POST https://www.zjhl.fjzyi.com/api/calc/v1/{功能ID}`，把 `arguments` 作为 JSON body
4. 把返回的 `data` 作为 tool 消息回填给模型

## 免责声明

传统文化视角，仅供娱乐参考，不作绝对定论。