# 🌟 AstroStellar（天星紫府）— 紫微斗数智能 Skill

> 满天星曜，尽布盘中。天星紫府，观心见命。

**AstroStellar** 是一款基于紫微斗数古籍的智能排盘与解盘系统，以 OpenClaw Skill + MCP Server 双重形态提供服务。用户只需像聊天一样逐步提供出生信息，即可自动排出完整命盘，并获得基于古籍知识库的专业解读。

---

## ✨ 它能做什么

| 功能 | 说明 |
|------|------|
| 🧮 **智能排盘** | 输入生辰 → 自动计算完整命盘（十四主星、四化、十二宫、大限、流年） |
| 📚 **古籍查书** | ChromaDB 语义检索，从 18 份古籍 + 213 页《紫微斗数全书》中查找相关解读 |
| 🔮 **整体解盘** | 生成六大板块结构化报告：命盘概览 → 命宫总论 → 十二宫简析 → 四化点睛 → 格局判断 → 流年提点 |
| 💬 **专项问答** | 财运、感情、事业、健康……随你问 |
| 🌸 **善解人意** | 一次只问一个问题，记不清时辰也不怕，像朋友聊天一样自然 |

---

## 🏗️ 原理

### 整体架构

```
┌──────────────────────────────────────────────────┐
│                     👤 用户                       │
│         飞书 / 微信 / Telegram 等渠道              │
└────────────────────┬─────────────────────────────┘
                     │ 自然语言对话
                     ▼
┌──────────────────────────────────────────────────┐
│               🦞 OpenClaw 平台                     │
│                                                    │
│   ┌──────────────────────────────────────┐        │
│   │            SKILL.md                   │        │
│   │  · 10 步定盘对话状态机                │        │
│   │  · 善解人意的人物设定                 │        │
│   │  · MCP 协议工具调度                   │        │
│   └──────────────┬───────────────────────┘        │
│                  │ MCP Protocol                    │
└──────────────────┼────────────────────────────────┘
                   ▼
┌──────────────────────────────────────────────────┐
│              🔧 MCP Server (Python)                │
│                                                    │
│   ┌────────────┐ ┌──────────┐ ┌────────────────┐ │
│   │ 排盘引擎    │ │ 解盘引擎  │ │ 知识库引擎      │ │
│   │ chart.py   │ │interp.py │ │ knowledge.py   │ │
│   │            │ │          │ │                │ │
│   │ 日历转换    │ │ 星曜解读  │ │ ChromaDB       │ │
│   │ 四柱推算    │ │ 宫位解读  │ │ 语义检索       │ │
│   │ 五行局      │ │ 格局检测  │ │ 18 MD + 1 PDF │ │
│   │ 安命宫      │ │ 综合解盘  │ │                │ │
│   │ 安十四主星  │ │ 专项问答  │ │                │ │
│   │ 安四化      │ │          │ │                │ │
│   │ 大限/流年   │ │          │ │                │ │
│   └────────────┘ └──────────┘ └────────────────┘ │
└──────────────────────────────────────────────────┘
```

### 排盘算法

排盘核心基于**太阳黄经天文算法**，独立计算 24 节气交节时刻，不依赖任何查表数据：

1. **日历转换**（`lunar_calendar.py`）：`lunardate` 库负责公历⇄农历互转，四柱推算使用干支纪日基点（1900-01-01 = 甲戌日），按距基点天数推导日柱
2. **安命宫/身宫**（`chart.py`）：寅起正月，按生月顺逆数，再按生时顺逆数
3. **安十四主星**：根据五行局数和农历日定紫微位置，紫微系六星逆排，天府系八星顺排
4. **安四化**：十干四化表全覆盖
5. **排大限/流年**：阳男阴女顺行，阴男阳女逆行，局数起运

### 知识库

- **数据源**：18 份 Markdown 格式紫微斗数古籍 + 213 页《紫微斗数全书》PDF（南北山人版）
- **检索方式**：ChromaDB 向量数据库 + `sentence-transformers` 多语言嵌入模型
- **持久化**：首次加载后存入 `data/chroma_db/`，后续直接读取，无需重复构建

### 解盘引擎

采用「数据 + 知识库 + 结构化模板」三合一方式：
1. 从 `stars.json` 获取十四主星结构化属性（五行、阴阳、庙旺、落陷、各宫解读）
2. 从 ChromaDB 语义检索相关古籍段落
3. 按六大板块模板组装为完整报告
4. 专项问答通过 30+ 关键词智能路由到相关宫位

---

## 📦 下载位置

**GitHub 仓库：** [`https://github.com/zhaopeng309/AstroStellar`](https://github.com/zhaopeng309/AstroStellar)

```bash
git clone https://github.com/zhaopeng309/AstroStellar.git
cd AstroStellar
```

---

## 🚀 使用方法

### 第一步：克隆项目

```bash
git clone https://github.com/zhaopeng309/AstroStellar.git
cd AstroStellar
```

### 第二步：创建虚拟环境

```bash
python3 -m venv venv
source venv/bin/activate
```

### 第三步：安装依赖

```bash
pip install -r requirements.txt
```

> ⚠️ 首次安装会下载 `sentence-transformers` 嵌入模型（约 500MB），请确保网络畅通且磁盘空间充足。

### 第四步：（可选）初始化知识库

知识库会在首次调用 `astrostellar_search_knowledge` 时自动构建。也可以手动初始化：

```bash
source venv/bin/activate
python -c "from src.knowledge import init_knowledge_base; init_knowledge_base('references', 'data/chroma_db')"
```

> 初始化完成后，ChromaDB 数据会持久化到 `data/chroma_db/`，后续启动无需重复构建。

### 第五步：启动 MCP Server

```bash
source venv/bin/activate
python src/server.py
```

MCP Server 使用 stdio 传输协议，由 OpenClaw 平台自动调用，无需手动暴露端口。

### 第六步：在 OpenClaw 中使用

将 `SKILL.md` 软连接到 OpenClaw 的 skills 目录，或直接通过 OpenClaw 的 Skill 管理加载。

### 对话示例

```
用户：帮我排盘
天星：🌸 你好呀～我是天星，可以帮你排紫微斗数命盘……
      先从最简单的问题开始：你是哪一年出生的？（比如 1990）

用户：1990
天星：好的，1990 年，记下了 ✍️
      接下来：你的生日是几月几号？
      📝 已收集：1990 年

用户：6月15日
天星：知道了，6 月 15 日 ✍️
      这个日期是公历还是农历？
      📝 已收集：1990 年 6 月 15 日

……（继续 10 步定盘）……

天星：🌸 你的紫微斗数命盘
      ━━━━━━ 四柱 ━━━━━━
      年柱庚午 月柱壬午 日柱辛亥

用户：我的财运怎么样？
天星：关于财运——
      财帛宫坐申，宫内武曲天府，逢化禄则财运亨通……
```

---

## 📂 项目结构

```
AstroStellar/
├── SKILL.md                  # OpenClaw 技能定义（对话流 + 人物设定）
├── skill-card.md             # 技能元数据
├── README.md                 # 本文件
├── requirements.txt          # Python 依赖
│
├── src/                      # 核心引擎
│   ├── lunar_calendar.py      # Block 1: 日历 + 四柱 + 五行局 + 节气计算
│   ├── chart.py               # Block 2: 排盘核心（命宫→主星→四化→大限→流年）
│   ├── knowledge.py           # Block 3a: 知识库（ChromaDB 语义检索）
│   ├── interpreter.py         # Block 3b: 解盘引擎
│   └── server.py              # Block 4: MCP Server（3 个 tool）
│
├── data/                     # 数据
│   ├── stars.json            # 十四主星结构化属性
│   └── chroma_db/            # ChromaDB 持久化知识库
│
├── references/               # 紫微斗数参考书籍
│   └── 紫微斗数全书.pdf       #古籍全书
│
└── tests/                    # 自动化测试
```

---

## 🧪 测试

```bash
cd AstroStellar
source venv/bin/activate
python -m pytest tests/ -v
```

当前测试覆盖：**225+ 用例，全部通过**。

> 💡 知识库测试（`test_knowledge.py`）涉及 embedding 模型，若内存不足可跳过：`python -m pytest tests/ -v --ignore=tests/test_knowledge.py`

---

## 📚 技术栈

| 组件 | 技术 | 用途 |
|------|------|------|
| 历法 | `lunardate` | 公历⇄农历互转（1900-2100） |
| 节气 | 纯 Python 太阳黄经算法 | 立春/惊蛰等 12 节交节时间 |
| 排盘 | 纯 Python 实现 | 命宫、主星、四化、大限、流年 |
| 知识库 | ChromaDB + `sentence-transformers` | 古籍语义检索 |
| MCP | `mcp` (FastMCP) | 标准 Tool 接口 |
| 测试 | `pytest` | 单元 + 集成 |

---

## ⚠️ 注意事项

- **年份范围**：支持 1900-2100 年（lunardate 库限制）
- **ChromaDB 初始化**：首次构建知识库需下载 embedding 模型（~500MB），完成后持久化无需重复
- **MCP 协议**：Server 使用 stdio 传输，由 OpenClaw 自动管理生命周期
- **虚拟环境**：始终在项目 venv 中运行，不要使用系统 Python

---

> 🌟 天星紫府 — 满天星曜，尽布盘中