npm package: @guanxing1/plugin-elizaos
Description: ElizaOS plugin for 观星 GuanXing — Chinese metaphysics AI tools (BaZi, Tarot, I-Ching, Feng Shui, fortune telling)
Author: Ryan Cheung
Latest version: 0.1.0

# @guanxing/plugin-elizaos

ElizaOS plugin for **观星 GuanXing** — Chinese metaphysics AI tools.

Give any Eliza-powered AI agent the ability to perform BaZi (八字) analysis, Tarot readings, I-Ching divination, Feng Shui assessments, dream interpretation, and more.

## Actions

| Action | Description |
|--------|-------------|
| `BAZI_ANALYSIS` | Chinese Four Pillars of Destiny (八字命理) — birth chart analysis |
| `DAILY_FORTUNE` | Daily fortune forecast by zodiac sign (每日运势) |
| `QIUQIAN` | Temple fortune stick divination (求签问卦) — Guanyin or Guandi |
| `TAROT_READING` | Tarot card reading (塔罗占卜) — single, three-card, or Celtic Cross |
| `DREAM_INTERPRET` | Dream interpretation (周公解梦) with psychology insights |
| `ALMANAC_LOOKUP` | Chinese almanac / Huang Li (黄历) — auspicious dates & activities |
| `FENGSHUI_ASSESSMENT` | Feng Shui analysis (风水评估) for home, office, or shop |
| `NAME_SCORE` | Chinese name numerology scoring (姓名打分) |
| `COMPATIBILITY_CHECK` | Zodiac/birth date compatibility (缘分配对) |
| `ZODIAC_READING` | Zodiac sign deep analysis (星座解读) |

## Installation

```bash
bun add @guanxing/plugin-elizaos
# or
npm install @guanxing/plugin-elizaos
```

## Configuration

### 1. Get an API Key

Sign up at [heartai.zeabur.app](https://heartai.zeabur.app) and create a developer API key.

### 2. Add to your character

```json
{
  "name": "MyAgent",
  "plugins": ["@guanxing/plugin-elizaos"],
  "settings": {
    "secrets": {
      "GUANXING_API_KEY": "gx_sk_your_key_here"
    }
  }
}
```

Or set the environment variable:

```bash
GUANXING_API_KEY=gx_sk_your_key_here
```

## Example Conversations

**BaZi Analysis**
```
User: Can you do a BaZi reading for someone born on 1990-06-15 at 2pm?
Agent: 八字 BaZi Analysis for 1990-06-15 at 14:00
       Four Pillars: 庚午 壬午 丁巳 丁未
       Day Master: 丁火
       Five Elements: 金: 1 | 木: 0 | 水: 1 | 火: 4 | 土: 2
       ...
```

**Daily Fortune**
```
User: What's my daily fortune? I'm a Leo.
Agent: 狮子座 — Today's Fortune
       Overall: ★★★★☆
       Career:  ★★★★★
       Lucky Color: Gold
       ...
```

**Fortune Stick (求签)**
```
User: Draw a fortune stick — should I change jobs?
Agent: 🏮 Fortune Stick #42 — 旧燕衔泥
       Grade: 中上
       ...
```

**Tarot Reading**
```
User: Do a three-card tarot spread about my relationship
Agent: 🃏 Tarot Reading — Past / Present / Future
       Card 1: The Lovers — Deep connection...
       Card 2: The Tower (Reversed) — Upheaval settling...
       Card 3: The Star — Hope and renewal ahead...
```

**Dream Interpretation**
```
User: I dreamed I was flying over an ocean and saw a golden dragon
Agent: 🌙 Dream Interpretation
       Symbols: flying, ocean, golden dragon
       ...
```

**Chinese Almanac**
```
User: Check the Chinese almanac for today
Agent: 📅 Chinese Almanac — Today
       Lunar Date: 二月十九
       Auspicious: 开业, 搬家, 签约
       Inauspicious: 动土, 安葬
       ...
```

**Feng Shui**
```
User: Check the feng shui of my south-facing home office
Agent: 🏡 Feng Shui Assessment — office
       Score: 72/100
       ...
```

**Name Score**
```
User: Score the name 张伟
Agent: 📝 Name Score — 张伟
       Total Score: 85/100
       ...
```

**Compatibility**
```
User: Check compatibility between Leo and Pisces
Agent: 💕 Compatibility Check
       狮子座 × 双鱼座
       Overall Score: 68/100
       Love:       ███████░░░ 75%
       ...
```

**Zodiac Reading**
```
User: Tell me about Scorpio's personality
Agent: ⭐ 天蝎座 Zodiac Reading — personality
       Element: Water
       Ruling Planet: Pluto
       Key Traits: Passionate, Determined, Mysterious
       ...
```

## Development

```bash
# Install dependencies
bun install

# Build
bun run build

# Watch mode
bun run dev
```

## API

This plugin connects to the [GuanXing API](https://heartai.zeabur.app) (`https://heartai.zeabur.app/api/v1/`). All 10 endpoints are POST requests authenticated via Bearer token.

## License

MIT