🔧 Add troubleshooting guide + trigger rebuild

- Created TROUBLESHOOTING.md documenting common deployment issues
- Updated README.md with new features documentation
- Trigger rebuild to fix ModuleNotFoundError

🦊 Generated with Sisi

README.md

@@ -14,15 +14,47 @@ Professional birth chart calculation API powered by Swiss Ephemeris.
 
 ## ✨ Features
 
+### Core Calculations
 - ⭐ **100% Accurate** planetary positions using Kerykeion library
 - 🏠 **12 House Systems** (Placidus, Whole Sign, Equal, Koch, Regiomontanus)
 - 🌙 **Complete Celestial Data**: Sun, Moon, all planets + North Node
 - 🔮 **Professional-grade** astronomical calculations
-- 🚀 **Fast & Reliable** API built with FastAPI
 
-## 🎯 API Endpoint
+### NEW: Knowledge Base Endpoints (FREE) 🆓
+- 📚 **48 Professional Interpretations** - Zero AI cost, instant responses
+- ♈ **12 Complete Zodiac Profiles** - Personality, love, career, 2026 themes
+- 🪐 **Planet in Sign Readings** - Sun/Moon through all 12 signs
+- 🏠 **Planet in House Readings** - Detailed house interpretations
 
-POST /api/calculate-birth-chart
+### NEW: AI-Powered Readings (Premium) ✨
+- 🤖 **Personalized Birth Chart Analysis** - 800-1200 word custom readings
+- 💰 **90% Cost Reduction** - Knowledge base + AI hybrid approach
+- 🌍 **Multi-language Support** - English, 简体中文, 繁體中文
+- 🎯 **Focus Areas** - Love, career, 2026 guidance, health, spirituality
+
+### Infrastructure
+- 🚀 **Fast & Reliable** - Built with FastAPI + Docker
+- 🔐 **Secure** - API key authentication for premium endpoints
+- 📊 **Well-documented** - Complete API docs and examples
+
+## 🎯 API Endpoints
+
+**FREE (No API Key Required)**:
+- `GET /api/zodiac-profile/{sign}` - Complete zodiac profile
+- `GET /api/planet-in-sign/{planet}/{sign}` - Planet in sign interpretation
+- `GET /api/planet-in-house/{planet}/{house}` - Planet in house interpretation
+- `GET /api/birthday-fortune/{month}/{day}` - Numerology reading
+
+**Premium (API Key Required)**:
+- `POST /api/calculate-birth-chart` - Full birth chart calculation
+- `POST /api/generate-chart-svg` - Professional chart visualization
+- `POST /api/personalized-reading` - AI-powered custom reading (NEW!)
+
+## 📖 Documentation
+
+See full API documentation in:
+- `KNOWLEDGE_BASE_ENDPOINTS.md` - Static knowledge base API
+- `AI_PERSONALIZED_READING.md` - AI-powered readings
+- `EXAMPLE_USAGE.md` - Integration examples
 
 🦊 Built with love by Sisi
-# Trigger build

TROUBLESHOOTING.md

@@ -0,0 +1,266 @@
+# 🔧 Troubleshooting Guide - Hugging Face Spaces 部署常见问题
+
+## ❌ 问题1: ModuleNotFoundError - 新添加的Python文件找不到
+
+### 错误信息
+```
+ModuleNotFoundError: No module named 'ai_service'
+ModuleNotFoundError: No module named 'knowledge_base'
+ModuleNotFoundError: No module named 'xxx'
+```
+
+### 原因分析
+Hugging Face Spaces使用Docker容器部署，有时会遇到以下问题：
+
+1. **Docker层缓存问题** - 新文件被Git正确提交，但Docker构建时使用了旧缓存
+2. **文件权限问题** - 某些情况下新文件权限不正确（虽然git commit成功）
+3. **构建触发问题** - Space没有检测到需要重新构建
+
+### ✅ 解决方案（按优先级尝试）
+
+#### 方案1: Factory Reboot（最彻底，推荐）⭐
+
+**步骤**：
+1. 前往 Hugging Face Space设置页面
+   - URL: `https://huggingface.co/spaces/sisithefox/sisi-astrology-api/settings`
+2. 滚动到底部找到 **"Factory reboot"** 按钮
+3. 点击 **Factory reboot**
+4. 等待Space重新构建（通常2-3分钟）
+5. 检查日志确认新模块被正确加载
+
+**原理**：Factory reboot会完全清除Docker缓存，从头构建容器。
+
+---
+
+#### 方案2: 触发Rebuild（简单快速）
+
+**步骤**：
+1. 修改任意文件触发rebuild（如README.md）
+   ```bash
+   cd /Volumes/sparksverse/huggingface-spaces/sisi-astrology-api
+   echo "# Trigger rebuild" >> README.md
+   git add README.md
+   git commit -m "🔧 Trigger rebuild"
+   git push
+   ```
+2. 等待自动重建
+3. 如果仍失败，使用方案1（Factory reboot）
+
+**原理**：新commit会触发Space自动重建。
+
+---
+
+#### 方案3: 检查Git是否正确提交
+
+**步骤**：
+```bash
+cd /Volumes/sparksverse/huggingface-spaces/sisi-astrology-api
+
+# 确认文件存在
+ls -la ai_service.py knowledge_base.py
+
+# 确认已被Git跟踪
+git ls-files | grep ai_service.py
+
+# 查看最新commit包含的文件
+git show --stat HEAD
+```
+
+**如果文件不在Git中**：
+```bash
+git add ai_service.py knowledge_base.py knowledge_extractor.py
+git commit -m "🔧 Add missing modules"
+git push
+```
+
+---
+
+#### 方案4: 检查requirements.txt依赖
+
+**步骤**：
+确保所有新模块需要的依赖都在`requirements.txt`中：
+
+```bash
+# 检查当前依赖
+cat requirements.txt
+
+# 如果缺少依赖，添加并提交
+git add requirements.txt
+git commit -m "🔧 Add missing dependencies"
+git push
+```
+
+**常见缺失依赖**：
+- `aiohttp` - ai_service.py需要
+- `pathlib` - 通常内置，但检查一下
+
+---
+
+## ❌ 问题2: Import错误但文件确实存在
+
+### 错误信息
+```
+File "/app/app.py", line 19, in <module>
+    from ai_service import generate_with_cache
+ModuleNotFoundError: No module named 'ai_service'
+```
+但`git ls-files`显示文件存在。
+
+### ✅ 解决方案：添加__pycache__到.gitignore
+
+**问题**：有时候`__pycache__`被错误提交，导致import混乱。
+
+**步骤**：
+```bash
+cd /Volumes/sparksverse/huggingface-spaces/sisi-astrology-api
+
+# 删除__pycache__
+rm -rf __pycache__
+
+# 确保.gitignore包含
+echo "__pycache__/" >> .gitignore
+echo "*.pyc" >> .gitignore
+
+git add .gitignore
+git commit -m "🔧 Ignore Python cache files"
+git push
+```
+
+然后执行**Factory reboot**。
+
+---
+
+## ❌ 问题3: Space一直显示"Building"
+
+### ✅ 解决方案
+
+1. **检查构建日志**：
+   - 点击Space页面的"Logs"标签
+   - 查看详细错误信息
+
+2. **常见原因**：
+   - requirements.txt中有不兼容的版本
+   - Dockerfile配置问题
+   - 超时（Space构建时间限制）
+
+3. **解决**：
+   - 根据日志修复问题
+   - Factory reboot
+
+---
+
+## ❌ 问题4: 环境变量未生效
+
+### 错误信息
+```python
+KeyError: 'GEMINI_API_KEY'
+```
+
+### ✅ 解决方案
+
+**步骤**：
+1. 前往 `https://huggingface.co/spaces/sisithefox/sisi-astrology-api/settings`
+2. 滚动到 **"Repository secrets"**
+3. 添加环境变量：
+   - Name: `GEMINI_API_KEY`
+   - Value: `your_key_here`
+4. 点击 **Save**
+5. **重要**: 添加环境变量后，必须**Factory reboot**才生效！
+
+---
+
+## 🎯 通用调试流程
+
+遇到部署问题时，按此顺序排查：
+
+```
+1. 检查Git commit
+   ↓ 文件都提交了？
+
+2. 查看Hugging Face Logs
+   ↓ 有具体错误信息？
+
+3. Factory Reboot
+   ↓ 最彻底的解决方案
+
+4. 检查环境变量
+   ↓ 所有secrets都配置了？
+
+5. 测试端点
+   ↓ 成功！
+```
+
+---
+
+## 📋 部署成功检查清单
+
+部署新功能时，确保以下步骤：
+
+- [ ] 所有新文件已`git add`
+- [ ] 所有新依赖已添加到`requirements.txt`
+- [ ] `__pycache__`已在`.gitignore`中
+- [ ] Git commit成功（`git show --stat HEAD`）
+- [ ] Git push成功
+- [ ] Hugging Face Space开始构建
+- [ ] 查看构建日志无错误
+- [ ] **如有import错误，立即Factory reboot**
+- [ ] 配置所有需要的环境变量
+- [ ] Factory reboot使环境变量生效
+- [ ] 测试所有新端点
+
+---
+
+## 🦊 经验总结
+
+### 什么时候需要Factory Reboot？
+
+**必须Factory Reboot**：
+- ✅ 添加了新的Python模块文件（如ai_service.py）
+- ✅ 修改了requirements.txt依赖
+- ✅ 添加/修改了环境变量
+- ✅ 遇到ModuleNotFoundError但文件确实提交了
+
+**不需要Factory Reboot**：
+- ❌ 只修改现有文件内容（不涉及新模块）
+- ❌ 只修改Markdown文档
+
+### Factory Reboot位置
+URL: `https://huggingface.co/spaces/sisithefox/sisi-astrology-api/settings`
+
+滚动到页面底部 → **Factory reboot** 按钮（红色）
+
+---
+
+## 🔍 快速诊断命令
+
+```bash
+# 1. 确认文件在Git中
+cd /Volumes/sparksverse/huggingface-spaces/sisi-astrology-api
+git ls-files | grep -E "(ai_service|knowledge)"
+
+# 2. 查看最新commit
+git show --stat HEAD
+
+# 3. 检查远程状态
+git log origin/main --oneline -3
+
+# 4. 确认本地和远程同步
+git status
+```
+
+---
+
+## 📞 仍无法解决？
+
+如果按照以上步骤仍无法解决：
+
+1. 检查Hugging Face状态页：https://status.huggingface.co/
+2. 查看Space构建日志的**完整错误栈**
+3. 确认Python版本兼容性（Space默认用Python 3.11）
+4. 联系Hugging Face支持
+
+---
+
+**创建日期**: 2026-01-07
+**最后更新**: 2026-01-07
+**维护者**: SisiTheFox 🦊