# 用户指南
本指南详细介绍 Mingli MCP Server 的所有功能和使用方法。
---
## 📋 目录
- [系统概览](#系统概览)
- [紫微斗数](#紫微斗数)
- [八字系统](#八字系统)
- [真太阳时支持](#真太阳时支持) ⭐ 新功能
- [参数说明](#参数说明)
- [输出格式](#输出格式)
- [高级用法](#高级用法)
- [限制与注意事项](#限制与注意事项)
---
## 系统概览
Mingli MCP Server 支持两大命理系统：
| 系统 | 功能 | 状态 |
|------|------|------|
| 紫微斗数 | 排盘、运势、宫位分析 | ✅ 完整 |
| 八字 | 排盘、运势、五行分析 | ✅ 完整 |
| 西方占星 | 星盘 | 🔄 规划中 |
---
## 紫微斗数
### 功能列表
#### 1. 完整排盘 (`get_ziwei_chart`)
**功能**：生成完整的紫微斗数命盘
**包含信息**：
- 十二宫位（命宫、兄弟、夫妻、子女、财帛、疾厄、迁移、交友、官禄、田宅、福德、父母）
- 主星（紫微、天机、太阳、武曲等14颗主星）
- 辅星（文昌、文曲、左辅、右弼等）
- 杂曜（天魁、天钺、禄存、羊刃等）
- 四化（化禄、化权、化科、化忌）
- 十二长生（长生、沐浴、冠带等）
- 大限信息
**使用示例**：
```
帮我排紫微盘：
出生：2000年8月16日
时辰：寅时（凌晨3-5点，序号2）
性别：女
历法：阳历
```
**AI 助手提示词**：
```
请使用紫微斗数排盘工具，参数如下：
- date: 2000-08-16
- time_index: 2
- gender: 女
- calendar: solar
- format: markdown
- language: zh-CN
```
#### 2. 运势查询 (`get_ziwei_fortune`)
**功能**：查询特定日期的运势
**包含信息**：
- 大限（十年一变）
- 流年（当年运势）
- 流月（当月运势）
- 流日（当日运势）
- 流时（当时运势）
**使用示例**：
```
查询2000年8月16日寅时出生的女性，2025年1月的运势
```
**参数说明**：
- `birth_date`: 出生日期
- `time_index`: 时辰序号
- `gender`: 性别
- `query_date`: 查询日期（可选，默认今天）
#### 3. 宫位分析 (`analyze_ziwei_palace`)
**功能**：深度分析特定宫位
**可分析宫位**：
- 命宫 - 命运、性格、整体格局
- 兄弟宫 - 兄弟姐妹、朋友关系
- 夫妻宫 - 配偶、婚姻、感情
- 子女宫 - 子女、创作、才华
- 财帛宫 - 财富、收入、理财
- 疾厄宫 - 健康、疾病、意外
- 迁移宫 - 外出、迁移、人际
- 交友宫 - 下属、朋友、合作（旧称"仆役宫"）
- 官禄宫 - 事业、工作、地位
- 田宅宫 - 房产、家庭、不动产
- 福德宫 - 福气、享受、心情
- 父母宫 - 父母、长辈、上司
**使用示例**：
```
分析2000年8月16日寅时女性的命宫
```
---
## 八字系统
### 功能列表
#### 1. 四柱排盘 (`get_bazi_chart`)
**功能**：生成八字四柱命盘
**包含信息**：
- 四柱八字（年柱、月柱、日柱、时柱）
- 天干地支详细信息
- 十神分析（比肩、劫财、食神、伤官、偏财、正财、七杀、正官、偏印、正印）
- 五行分数统计
- 地支藏干信息
- 生肖、日主等基本信息
**使用示例**：
```
帮我算八字：
出生：1990年5月20日
时辰：午时（中午11-13点，序号6）
性别：男
```
**输出示例**：
```markdown
# 八字排盘
## 基本信息
- 阳历：1990-05-20
- 农历：庚午年 四月 廿六
- 性别：男
- 生肖：马
## 四柱八字
**庚午 辛巳 己未 庚午**
### 年柱：庚午
- 天干：庚（阳金）
- 地支：午（阴火）
- 十神：比肩
### 月柱：辛巳
...
## 十神分析
- 比肩：2个
- 正官：1个
...
## 五行分数
- 金：3 (37.5%)
- 木：0 (0%)
- 水：1 (12.5%)
- 火：3 (37.5%)
- 土：1 (12.5%)
```
#### 2. 运势查询 (`get_bazi_fortune`)
**功能**：查询八字运势
**包含信息**：
- 当前年龄
- 大运信息（年龄范围、干支）
- 流年信息（年份、干支、生肖）
- 本命八字
**使用示例**：
```
查询1990年5月20日午时男性今年的运势
```
#### 3. 五行分析 (`analyze_bazi_element`)
**功能**：分析八字五行强弱
**包含信息**：
- 日主及其五行属性
- 五行分数和百分比
- 最旺五行
- 最弱五行
- 缺失五行
- 平衡度评价（0-100，越接近100越平衡）
- 补救建议
**使用示例**：
```
分析1990年5月20日午时男性的五行
```
**输出示例**：
```markdown
# 五行分析
## 日主
己土
## 五行统计
- 金：3 (37.5%) ⭐⭐⭐⭐
- 木：0 (0%) ❌ 缺失
- 水：1 (12.5%) ⭐
- 火：3 (37.5%) ⭐⭐⭐⭐
- 土：1 (12.5%) ⭐
## 分析
- 最旺五行：金、火（37.5%）
- 最弱五行：木（0%）
- 缺失五行：木
- 平衡度：60/100（中等）
## 建议
- 宜补木：穿青绿色衣服、佩戴木质饰品
- 职业方向：可选择木属性行业（教育、文化、绿化）
```
---
## 真太阳时支持
### ⭐ 新功能：精确时辰修正
**真太阳时（True Solar Time）**是根据出生地经度修正后的地方时间，可以提供更精确的时辰计算。
### 为什么需要真太阳时？
中国统一使用北京时间（UTC+8），但由于地域辽阔，各地实际地方时与北京时间存在差异：
| 地区 | 经度 | 时差 | 影响 |
|------|------|------|------|
| **乌鲁木齐** | 87.6°E | **-130分钟** | ⚠️ 可能改变时辰 |
| **拉萨** | 91.1°E | **-116分钟** | ⚠️ 可能改变时辰 |
| 北京 | 116.4°E | -14分钟 | ✓ 影响极小 |
| 上海 | 121.5°E | +6分钟 | ✓ 影响极小 |
### 快速开始
```
# 告诉AI使用真太阳时
帮我排盘：2000年8月16日，北京时间12:00，女性，出生地乌鲁木齐，使用真太阳时
# 或者指定经度
帮我排盘：2000年8月16日12:00，女性，经度87.6，启用真太阳时
```
### 支持的城市
系统内置**200+个全球主要城市**的经纬度数据：
- **中国**（43个）：全部省会、直辖市、重要城市、港澳台
- **亚洲**（37个）：日本、韩国、东南亚、南亚、中东
- **欧洲**（34个）：西欧、东欧、北欧
- **美洲**（31个）：美国、加拿大、南美
- **大洋洲**（9个）：澳大利亚、新西兰
- **非洲**（5个）：主要城市
**示例城市**：
- 西北：乌鲁木齐、拉萨、兰州、西宁
- 东部：北京、上海、广州、深圳
- 国际：东京、首尔、新加坡、纽约、伦敦、悉尼
### 何时应该使用？
**✅ 强烈建议**：
- 西北地区出生（新疆、西藏、甘肃西部）
- 出生时刻接近时辰边界（如11:00-13:00）
- 追求最高精度
**🔸 可选**：
- 东部沿海地区（时差较小）
- 中部地区（时差适中）
**⚪ 无需**：
- 不知道准确出生时间
- 不追求极致精度
### 使用效果
**乌鲁木齐示例**：
```
北京时间：2000-08-16 12:00（午时）
真太阳时：2000-08-16 09:50（巳时）⚠️ 时辰改变！
时差：-130分钟
```
**北京示例**：
```
北京时间：2000-08-16 12:00（午时）
真太阳时：2000-08-16 11:46（午时）✓ 时辰不变
时差：-14分钟
```
### 详细文档
完整使用指南请参阅：**[真太阳时使用指南](TRUE_SOLAR_TIME.md)**
---
## 参数说明
### 通用参数
#### `date` / `birth_date`
- **类型**：字符串
- **格式**：`YYYY-MM-DD`
- **示例**：`2000-08-16`
- **必需**：是
#### `time_index`
- **类型**：整数
- **范围**：0-12
- **说明**：时辰序号（见下表）
- **必需**：是
#### `gender`
- **类型**：字符串
- **可选值**：`男`、`女`
- **必需**：是
#### `calendar`
- **类型**：字符串
- **可选值**：`solar`（阳历）、`lunar`（农历）
- **默认值**：`solar`
- **必需**：否
#### `is_leap_month`
- **类型**：布尔值
- **说明**：是否为闰月（仅农历有效）
- **默认值**：`false`
- **必需**：否
#### `format`
- **类型**：字符串
- **可选值**：`json`、`markdown`
- **默认值**：`markdown`
- **必需**：否
#### `language`
- **类型**：字符串
- **可选值**：
- `zh-CN` - 简体中文
- `zh-TW` - 繁体中文
- `en-US` - English
- `ja-JP` - 日本語
- `ko-KR` - 한국어
- `vi-VN` - Tiếng Việt
- **默认值**：`zh-CN`
- **必需**：否
- **注意**：八字系统暂不支持多语言
### 时辰对照表
| 序号 | 时辰 | 时间范围 | 别称 |
|------|------|----------|------|
| 0 | 早子时 | 23:00-01:00 | 夜半 |
| 1 | 丑时 | 01:00-03:00 | 鸡鸣 |
| 2 | 寅时 | 03:00-05:00 | 平旦 |
| 3 | 卯时 | 05:00-07:00 | 日出 |
| 4 | 辰时 | 07:00-09:00 | 食时 |
| 5 | 巳时 | 09:00-11:00 | 隅中 |
| 6 | 午时 | 11:00-13:00 | 日中 |
| 7 | 未时 | 13:00-15:00 | 日昳 |
| 8 | 申时 | 15:00-17:00 | 晡时 |
| 9 | 酉时 | 17:00-19:00 | 日入 |
| 10 | 戌时 | 19:00-21:00 | 黄昏 |
| 11 | 亥时 | 21:00-23:00 | 人定 |
| 12 | 晚子时 | 23:00-01:00 | 夜半 |
**注意**：
- 序号 0 和 12 都表示子时，0 为早子时，12 为晚子时
- 出生在 23:00-24:00 之间，应使用当日日期 + 晚子时(12)
---
## 输出格式
### Markdown 格式（推荐）
**优点**：
- 易读性强
- 结构清晰
- 支持 AI 助手直接展示
**示例**：
```markdown
# 紫微斗数排盘
## 基本信息
- 阳历：2000-08-16
- 农历：庚辰年 七月 十七
...
```
### JSON 格式
**优点**：
- 结构化数据
- 便于程序处理
- 可进一步分析
**使用**：在参数中指定 `"format": "json"`
**示例**：
```json
{
"system": "紫微斗数",
"basic_info": {
"阳历日期": "2000-08-16",
"农历日期": "庚辰年 七月 十七"
},
"palaces": [...]
}
```
---
## 高级用法
### 1. 批量查询
```python
from systems import get_system
ziwei = get_system('ziwei')
# 批量排盘
people = [
{'date': '2000-08-16', 'time_index': 2, 'gender': '女'},
{'date': '1990-05-20', 'time_index': 6, 'gender': '男'},
]
for person in people:
chart = ziwei.get_chart(person)
print(chart)
```
### 2. 合盘分析（自定义）
```python
# 获取两人的排盘
chart1 = ziwei.get_chart(person1)
chart2 = ziwei.get_chart(person2)
# 自定义比较逻辑
# 比较夫妻宫、命宫等
```
### 3. 运势追踪
```python
from datetime import datetime, timedelta
birth_info = {'date': '2000-08-16', 'time_index': 2, 'gender': '女'}
# 查询未来12个月的运势
for i in range(12):
query_date = datetime.now() + timedelta(days=30*i)
fortune = ziwei.get_fortune(birth_info, query_date)
print(f"Month {i+1}: {fortune}")
```
---
## 限制与注意事项
### 日期范围
**支持范围**：1900-01-01 至 2100-12-31
**原因**：农历库 (lunar_python) 的计算限制
**超出范围处理**：
```python
from core.exceptions import DateRangeError
try:
chart = ziwei.get_chart({'date': '1850-01-01', ...})
except DateRangeError as e:
print(e) # 日期超出支持范围（1900-2100）: 1850-01-01
```
### 真太阳时
**当前状态**：❌ 不支持
**说明**：
- 当前使用北京时间（东八区）
- 真太阳时需要根据经纬度调整
- 未来版本可能支持
**临时解决方案**：
```python
# 手动计算时差并调整时辰
# 例如：新疆地区约2小时时差
# 如果当地时间是14:00（未时），北京时间约16:00（申时）
# 应使用 time_index=8（申时）
```
### 农历闰月
**处理方法**：
```python
birth_info = {
'date': '1995-08-20', # 农历日期
'time_index': 2,
'gender': '女',
'calendar': 'lunar',
'is_leap_month': True # 明确指定是闰月
}
```
**注意**：
- 必须准确知道是否为闰月
- 闰月与非闰月同一天的排盘结果不同
### 性能考虑
**排盘性能**：
- 紫微排盘：约 0.1-0.3 秒
- 八字排盘：约 0.05-0.15 秒
**优化建议**：
- 使用缓存机制
- 批量查询时注意速率限制（HTTP模式）
- 启用性能监控：`LOG_LEVEL=DEBUG`
---
## 常见问题
### Q: 如何确定准确的出生时辰？
A:
1. 查看出生证明
2. 询问父母或长辈
3. 如不确定，可尝试多个时辰对比
4. 专业命理师可通过"时辰校正"方法确定
### Q: 阳历和农历有什么区别？
A:
- **阳历**（公历）：国际通用历法，如身份证上的日期
- **农历**（阴历）：中国传统历法，如春节、中秋等节日
### Q: 多语言输出的准确度如何？
A:
- 简体中文：✅ 完整支持，最准确
- 繁体中文、英文：✅ 良好支持
- 日、韩、越南语：⚠️ 基础支持，专业术语可能不够精确
- 八字系统：❌ 暂不支持多语言
---
## 下一步
- [API 使用示例](API_EXAMPLES.md)
- [故障排查指南](TROUBLESHOOTING.md)
- [开发者文档](../CLAUDE.md)
---
**📖 本指南持续更新中...**
