zodiac-horoscope

根据本命盘计算，从 zodiac-today.com API 获取个性化的每日星座运势预测。 当用户想要执行以下操作时使用：(1) 关于要进行或避免哪些活动的日常指导， (2) 人生规划帮助——面试、旅行、浪漫、重要决定的最佳日子， (3) 能量/焦点/运气/浪漫预测以优化他们的日程安排， (4)当天的幸运颜色和数字， (5) 规划活动、旅行或里程碑（付费等级）的未来日期分析。 触发因素：星座运势、十二生肖、星座预测、每日指导、幸运日、最佳日子、占星建议、 今天我应该做什么，今天是个好日子，计划我的一周占星术。 所需环境：ZODIAC_API_KEY（hsk_ API 密钥）、ZODIAC_PROFILE_ID（出生图个人资料 ID）。 收集出生图的敏感 PII（电子邮件、出生日期、出生城市）——需要用户同意。

# Zodiac Horoscope

Provide personalized, actionable daily guidance powered by planetary transit calculations against the user's natal chart.

## Required Environment Variables

| Variable | Description |
|----------|-------------|
| `ZODIAC_API_KEY` | API key from zodiac-today.com (starts with `hsk_`) |
| `ZODIAC_PROFILE_ID` | Profile ID for the user's birth chart |

## Privacy Notice

This skill collects **sensitive PII** (email, birth date, birth city) required for natal chart calculations. Handle with care:
- Ask for explicit user consent before collecting birth information
- Never log or expose PII in public channels or shared contexts
- Store API keys and profile IDs in environment variables, not in plain text files
- Delete `cookies.txt` after registration is complete

## How This Helps People

- **Daily decision-making**: "Should I have that difficult conversation today?" → Check if confrontations are favorable or unfavorable
- **Schedule optimization**: Plan high-energy tasks on high-energy days, rest on low days
- **Life event planning**: Find the best window for job interviews, first dates, travel, or big purchases (paid tiers unlock future dates)
- **Relationship insights**: Romance metrics help users pick ideal date nights
- **Motivation & mindfulness**: Daily summaries provide a moment of reflection and intentional living

## Setup

Everything can be done via API — no browser needed.

### 1. Register & get API key

```bash
# Send verification code (creates account if new)
curl -s -X POST https://zodiac-today.com/api/auth/send-code \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com"}'

# Verify code (check email inbox for 6-digit code)
curl -s -X POST https://zodiac-today.com/api/auth/verify \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{"email":"user@example.com","code":"123456"}'

# Create API key (use session cookie from verify step)
curl -s -X POST https://zodiac-today.com/api/keys \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"name":"My Agent"}'
# Response: {"id":"...","key":"hsk_...","name":"My Agent"}
```

Store the `hsk_` key as environment variable `ZODIAC_API_KEY`. Delete `cookies.txt` after this step.

### 2. Create birth profile

```bash
curl -s -X POST https://zodiac-today.com/api/profiles \
  -H "Authorization: Bearer hsk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name":"John","birthDate":"1990-05-15","birthCity":"London, UK"}'
```

Save the returned `id` as environment variable `ZODIAC_PROFILE_ID`.

## Workflow

### First-time setup for a user
1. Ask for their email, birth date, and birth city (get explicit consent — this is sensitive PII)
2. Send verification code: `POST /api/auth/send-code` with their email
3. **Human-in-the-loop**: Ask the user to check their email and provide the 6-digit code. If the agent has email access (e.g., IMAP), it may retrieve the code automatically from `noreply@zodiac-today.com`
4. Verify code: `POST /api/auth/verify` — save session cookie to a temp file (`-c cookies.txt`)
5. Create API key: `POST /api/keys` (with session cookie) — save the returned `hsk_` key
6. **Clean up**: Delete `cookies.txt` immediately — it is no longer needed
7. Create profile: `POST /api/profiles` (with API key) — save the returned profile `id`
8. Store `ZODIAC_API_KEY` and `ZODIAC_PROFILE_ID` as environment variables

### Daily horoscope fetch
1. Call `GET /api/horoscope/daily?profileId=$ZODIAC_PROFILE_ID&startDate=YYYY-MM-DD&endDate=YYYY-MM-DD` with `Authorization: Bearer $ZODIAC_API_KEY`
2. Parse the response and present actionable insights

### Presenting results to users

Translate raw data into **practical advice**:

- **overallRating** (1-10): Frame as "Great day!" (8+), "Solid day" (6-8), "Take it easy" (<6)
- **favorable/unfavorable**: Present as "Good for:" and "Better to avoid:" lists
- **metrics**: Highlight the standout ones — "Your energy is HIGH today, perfect for tackling that project"
- **luckyColors**: Suggest outfit or decor choices
- **luckyNumbers**: Mention casually, fun touch
- **summary**: Use the astrological narrative to add color, but keep advice grounded and practical

### Planning ahead (paid tiers)

For users with Starter+ tiers, fetch date ranges to help:
- "What's the best day this month for my job interview?"
- "When should I plan our anniversary dinner?"
- Compare overallRating across dates and recommend the highest-rated windows

## API Details

See [references/api.md](references/api.md) for full endpoint docs, parameters, tiers, and response schemas.

## Example curl

```bash
curl "https://zodiac-today.com/api/horoscope/daily?profileId=PROFILE_ID&startDate=2026-02-15&endDate=2026-02-15" \
  -H "Authorization: Bearer hsk_your_api_key"
```

---

## 中文说明

# Zodiac Horoscope

基于行星过境与用户本命盘的计算，提供个性化、可操作的每日指导。

## 必需的环境变量

| 变量 | 说明 |
|----------|-------------|
| `ZODIAC_API_KEY` | 来自 zodiac-today.com 的 API 密钥（以 `hsk_` 开头） |
| `ZODIAC_PROFILE_ID` | 用户出生图的 Profile ID |

## 隐私须知

本技能会收集本命盘计算所需的**敏感 PII**（电子邮件、出生日期、出生城市）。请谨慎处理：
- 在收集出生信息前征得用户的明确同意
- 切勿在公开渠道或共享上下文中记录或暴露 PII
- 将 API 密钥和 profile ID 存储在环境变量中，而非明文文件里
- 注册完成后删除 `cookies.txt`

## 这对用户有何帮助

- **日常决策**："我今天该进行那次艰难的谈话吗？" → 查看冲突类活动是吉是凶
- **日程优化**：在高能量日安排高强度任务，在低能量日休息
- **人生事件规划**：找到求职面试、初次约会、旅行或大额采购的最佳时间窗口（付费等级可解锁未来日期）
- **关系洞察**：浪漫指标帮助用户挑选理想的约会之夜
- **激励与正念**：每日总结提供片刻反思与有意识生活的契机

## 设置

一切都可以通过 API 完成 —— 无需浏览器。

### 1. 注册并获取 API 密钥

```bash
# Send verification code (creates account if new)
curl -s -X POST https://zodiac-today.com/api/auth/send-code \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com"}'

# Verify code (check email inbox for 6-digit code)
curl -s -X POST https://zodiac-today.com/api/auth/verify \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{"email":"user@example.com","code":"123456"}'

# Create API key (use session cookie from verify step)
curl -s -X POST https://zodiac-today.com/api/keys \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"name":"My Agent"}'
# Response: {"id":"...","key":"hsk_...","name":"My Agent"}
```

将 `hsk_` 密钥存储为环境变量 `ZODIAC_API_KEY`。完成此步骤后删除 `cookies.txt`。

### 2. 创建出生 profile

```bash
curl -s -X POST https://zodiac-today.com/api/profiles \
  -H "Authorization: Bearer hsk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name":"John","birthDate":"1990-05-15","birthCity":"London, UK"}'
```

将返回的 `id` 保存为环境变量 `ZODIAC_PROFILE_ID`。

## 工作流

### 用户首次设置
1. 询问用户的电子邮件、出生日期和出生城市（取得明确同意 —— 这是敏感 PII）
2. 发送验证码：用其电子邮件调用 `POST /api/auth/send-code`
3. **人工介入**：请用户查看邮件并提供 6 位验证码。如果代理有邮件访问权限（例如 IMAP），可从 `noreply@zodiac-today.com` 自动获取验证码
4. 验证验证码：`POST /api/auth/verify` —— 将会话 cookie 保存到临时文件（`-c cookies.txt`）
5. 创建 API 密钥：`POST /api/keys`（带会话 cookie）—— 保存返回的 `hsk_` 密钥
6. **清理**：立即删除 `cookies.txt` —— 它已不再需要
7. 创建 profile：`POST /api/profiles`（带 API 密钥）—— 保存返回的 profile `id`
8. 将 `ZODIAC_API_KEY` 和 `ZODIAC_PROFILE_ID` 存储为环境变量

### 每日星座运势获取
1. 调用 `GET /api/horoscope/daily?profileId=$ZODIAC_PROFILE_ID&startDate=YYYY-MM-DD&endDate=YYYY-MM-DD`，带 `Authorization: Bearer $ZODIAC_API_KEY`
2. 解析响应并呈现可操作的洞察

### 向用户呈现结果

将原始数据转化为**实用建议**：

- **overallRating**（1-10）：表述为"美好的一天！"（8+）、"不错的一天"（6-8）、"放轻松"（<6）
- **favorable/unfavorable**：呈现为"适宜："和"最好避免："列表
- **metrics**：突出最亮眼的指标 —— "你今天能量很高，正适合攻克那个项目"
- **luckyColors**：建议穿搭或装饰选择
- **luckyNumbers**：随意提及，增添趣味
- **summary**：用占星叙事增添色彩，但保持建议务实落地

### 提前规划（付费等级）

对于拥有 Starter+ 等级的用户，可获取日期区间来帮助：
- "这个月哪天最适合我的求职面试？"
- "我该把周年纪念晚餐安排在什么时候？"
- 比较各日期的 overallRating，并推荐评分最高的时间窗口

## API 细节

完整的 endpoint 文档、参数、等级和响应 schema 请参见 [references/api.md](references/api.md)。

## 示例 curl

```bash
curl "https://zodiac-today.com/api/horoscope/daily?profileId=PROFILE_ID&startDate=2026-02-15&endDate=2026-02-15" \
  -H "Authorization: Bearer hsk_your_api_key"
```