🌟 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

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

---

🚀 使用方法

第一步：克隆项目

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

第二步：创建虚拟环境

python3 -m venv venv
source venv/bin/activate

第三步：安装依赖

pip install -r requirements.txt

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

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

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

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

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 依赖
│
├── plan/                     # 完整开发计划（4 份）
│   ├── Inflare_Development_Plan.md   # 总体架构
│   ├── Phase2_Development_Plan.md    # 排盘核心
│   ├── Phase3_Development_Plan.md    # 解盘 + 知识库
│   └── Phase4_Development_Plan.md    # SKILL.md + 集成
│
├── 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 持久化知识库（本地生成，不纳入 git）
│
├── references/               # 紫微斗数参考书籍
│   ├── major-star.md         # 十四主星详解
│   ├── palace.md             # 十二宫详解
│   ├── mutagen.md            # 四化星
│   ├── pattern.md            # 格局大全
│   ├── setup.md              # 安星诀（排盘口诀）
│   └── 紫微斗数全书.pdf       # 213 页古籍全书
│
└── tests/                    # 自动化测试（225+ 用例）
    ├── test_calendar.py       # 日历 + 四柱 + 五行局
    ├── test_chart.py          # 排盘核心
    ├── test_knowledge.py      # 知识库
    ├── test_interpreter.py    # 解盘引擎
    └── test_server.py         # MCP Server

---

🧪 测试

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

---

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