astro

Astro — 面向 AI Agent 的多传统占星引擎

基于西方占星、吠陀占星（Jyotish）和中国八字，提供可靠的出生星盘、行运和合盘。引擎负责计算；模型负责解读。

---

将此内容粘贴到任意 AI 聊天或 Agent 中（Claude、ChatGPT、Gemini、Claude Code、Cursor、Codex、DeepSeek、Perplexity……），即可自动安装 Astro——无需预先进行任何设置：

You are my personal astrologer powered by Astro, an open-source multi-tradition astrology engine that computes mathematically real charts instead of guessing: https://github.com/aryaminus/astro

SET YOURSELF UP now using whatever you're capable of — try in this order, don't ask me first:
1. If you can run shell/terminal commands, get the pure-Python engine (zero dependencies — no pip install) by ANY of these:
   - `git clone https://github.com/aryaminus/astro` — most reliable; engine at astro/skills/astrology/scripts/astro_engine.py
   - `npx skills add aryaminus/astro -g` — installs the skill on Claude Code, Cursor, Codex, Gemini CLI + 50+ hosts (engine at skills/astrology/scripts/astro_engine.py)
   - latest packaged release (needs only curl + unzip): `curl -L -o astrology.skill https://github.com/aryaminus/astro/releases/latest/download/astrology.skill && unzip astrology.skill` — engine then at scripts/astro_engine.py
   Then run it: `python3 <path>/astro_engine.py --json '{"year":1990,"month":6,"day":15,"hour":14,"minute":30,"lat":40.7128,"lng":-74.0060,"tz":"America/New_York"}'`. Required: year, month, day, lat, lng (decimals, East +/West −), tz (IANA name like "America/New_York"); optional: hour+minute (omit → Sun-sign level), name, gender, "mode" (transit / synastry / compatibility / solar_return / …), "systems":["western","vedic","bazi"]. Look up the user's city's lat/lng/tz yourself.
2. If you already have an Astro MCP server or REST API connected, use those tools to compute charts. Public MCP SSE endpoint: `https://astro-api-a2rc.onrender.com/mcp/sse` (~30s cold start after idle).
3. If you can only browse the web: read the canonical spec and follow it as your operating instructions — https://raw.githubusercontent.com/aryaminus/astro/main/skills/astrology/SKILL.md — and fetch the classical reference rulesets it links (western, vedic, bazi, synastry-and-timing, consultation) from https://github.com/aryaminus/astro/tree/main/skills/astrology/references
4. If you can't do any of the above: tell me in one line how to install it (`npx skills add aryaminus/astro -g`, or download the skill from https://github.com/aryaminus/astro/releases/latest for claude.ai), then proceed by interpreting from classical reference and state clearly that you are NOT computing real positions.

THEN behave exactly as Astro's SKILL.md defines:
- COMPUTE the real chart before interpreting — NEVER invent a planetary position, house, or aspect. If no compute path worked, say so honestly.
- CITE specific placements ("your Moon in Pisces in the 4th house"); never generic statements true of everyone.
- ROUTE by question: love → synastry/compatibility; timing/career → transits; year ahead → solar return + progressions; where to live → astrocartography; auspicious dates → electional + panchang.
- TRADITIONS: Western tropical by default; Vedic (dasha/nakshatra) when I ask; Chinese BaZi (four pillars) when I ask.
- ETHICS: never predict death or guaranteed doom; give me agency; if I'm in crisis, point me to real emergency help first.

Now ask me for my birth details (date — and ideally exact time + city) and let's begin.

本地安装——适用于 Claude Code、Cursor、Codex、Copilot、Gemini CLI 和 50 多个 Agent Skills 宿主：

npx skills add aryaminus/astro -g

宿主	安装	更新
Claude Code	/plugin marketplace add aryaminus/astro 然后 /plugin install astrology	通过 marketplace 自动更新
Codex、Cursor、Copilot、Gemini CLI、50 多个宿主	npx skills add aryaminus/astro -g	npx skills update astrology -g
claude.ai	下载 .skill → Customize → Skills → +	重新下载
ChatGPT	将 openapi.yaml 复制到 Custom GPT → Actions → Import	手动更新
Poke（Messages/WhatsApp/Telegram）	添加为 MCP 集成 → URL：https://astro-api-a2rc.onrender.com/mcp/sse	—
Claude Desktop / Zed	npx @smithery/cli install astrology --client claude	重新运行
手动 / 开发	git clone https://github.com/aryaminus/astro.git && ln -sfn "$(pwd)/astro/skills/astrology" ~/.agents/skills/astrology	git pull

---

为什么要做这个项目

原始 LLM 无法告诉你 1997 年某个星期二火星的位置——它会编造星盘数据。Astro 将工作拆分为：

1. 引擎——使用确定性的 Python 数学计算真实天体位置（零依赖，仅使用标准库）
2. 技能——协调引擎并加载古典解读规则集
3. 连接层——通过 MCP、REST、CLI、ChatGPT Actions，让任何平台都能调用引擎

模型绝不会猜测天体位置。它会根据 8 套古典规则集解读结构化输出。

19 种模式 · 3 种传统 · 零依赖

模式： 本命、行运、合盘、兼容性、组合盘、占星地图、卜卦、事件、太阳／月亮／行星回归、纳瓦姆萨、分盘（D2–D60）、潘查迦、月相、数字命理、推运、行星时、行运与本命星体相位。完整列表和参数见 skills/astrology/SKILL.md。

传统： 西方回归黄道占星、吠陀占星（Jyotisha，Lahiri 恒星黄道）、中国八字 + 藏传／佛教。

每张本命星盘均自动包含： 相位格局（大三角、风筝、T 三角、大十字、Yod、神秘矩形、星群）· 福点 · 宿命点 · 黑月莉莉丝 · 月相 · 10 个阿拉伯点 · 23 个恒星合相 · 纳瓦姆萨 D9 · 潘查迦 · 火星煞 · 卡拉萨尔帕煞。

试试看

安装后，可以尝试询问：

• “我的星盘是什么样的？” → 完整本命盘
• “我和……合得来吗？” → 合盘 + 0–100 评分
• “我的土星回归是什么时候？” → 行星回归 + 时间
• “为了事业，我应该住在哪里？” → 占星地图
• “我应该选什么时间开始会议？” → 迦勒底行星时
• “帮我选个吉利的婚期” → 择日占星 + 潘查迦
• “我这个月适合做手术吗？” → 医疗时机
• “今天会有什么事发生？” → 行运 + 本命相位

项目结构

astro/
├── skills/astrology/
│   ├── SKILL.md                    # runtime spec the model reads
│   ├── scripts/astro_engine.py     # deterministic engine (~2930 lines)
│   ├── scripts/mcp_server.py       # MCP wrapper (18 tools, stdio + SSE)
│   ├── scripts/api.py              # REST API (31 endpoints)
│   └── references/                 # 8 classical rulesets
│       ├── western.md · vedic.md · bazi.md · tibetan.md
│       ├── health.md · synastry-and-timing.md
│       ├── specialty-systems.md · consultation.md
├── openapi.yaml                    # OpenAPI 3.1 (ChatGPT, Agentforce, Coze)
├── smithery.yaml                   # Smithery registry
├── Dockerfile · docker-compose.yml · render.yaml   # cloud deploy
└── AGENTS.md · CONTRIBUTING.md · SECURITY.md · CHANGELOG.md

云端托管

默认免费。 无需身份验证，也没有速率限制。设置 ASTRO_API_KEY 可启用访问控制，设置 ASTRO_RATE_LIMIT 可限制速率。

Render（一键部署，免费套餐）： 连接此仓库 → New → Blueprint。render.yaml 会配置所有内容。使用 curl https://astro-api-a2rc.onrender.com/health 验证。免费套餐在闲置 15 分钟后会停止运行；闲置后的首次请求约需 30 秒。

Docker：

docker compose up --build    # API on :8000, docs at /docs

原始 Python：

pip install -r requirements.txt
uvicorn skills.astrology.scripts.api:app --host 0.0.0.0 --port 8000

MCP SSE（Smithery、Cloudflare、Poke）：

ASTRO_MCP_TRANSPORT=sse python -m skills.astrology.scripts.mcp_server

云端 MCP SSE（无需部署）： https://astro-api-a2rc.onrender.com/mcp/sse — 免费的 Render 实例。冷启动约需 30 秒。

环境变量和运维端点见 AGENTS.md。

文档

文件	涵盖内容
AGENTS.md	安装方式、环境变量、云端配置、MCP 工具列表
docs/cloud-setup.md	在任意 AI 聊天工具中使用 Astro（Claude、ChatGPT、Gemini、DeepSeek、Qwen）
skills/astrology/SKILL.md	运行时规范、模式参数、信任准则
skills/astrology/README.md	引擎内部机制、API 接口、专业分支
openapi.yaml	REST API 架构（ChatGPT、Agentforce、Coze）
CHANGELOG.md	发布历史
CONTRIBUTING.md	严格规则、开发工作流、PR 检查清单
SECURITY.md	漏洞报告

贡献

欢迎提交 PR。严格规则：引擎保持零依赖；引擎不得导入框架；涉及所有 4 个接口（引擎 + MCP + REST + OpenAPI）；技能内容必须真实。详见 CONTRIBUTING.md。

许可证

MIT。skills/astrology/references/ 中的参考文本是基于古典来源原创撰写的 MIT 许可综合内容。