# Astrolinkers — 可编程占星 API

面向开发者的生产级占星 API:Western 与 Vedic natal charts、talent profiles、compatibility、interpretations、异步 PDF reports、API keys、公开 docs、SDK,以及 live demo。独立完成,目前作为真实产品处于 beta 运行中。

- **Author:** Fedor Chishchin
- **Role:** Solo founder-engineer
- **Period:** 2025 — 至今
- **Stack:** Python · FastAPI · SQLAlchemy (async) · PostgreSQL · Redis · Dramatiq · Swiss Ephemeris · WeasyPrint · S3-compatible storage · Anthropic / OpenAI / Ollama · MCP · OpenTelemetry · Next.js
- **Source:** https://fedorthinks.com/zh/work/astrolinkers

---

## 问题所在

占星软件常常被劈成两种孱弱的形态:解读浅薄的消费级星座 app,或者难以集成进现代产品的
老旧计算工具。Astrolinkers 正是为缺失的中间地带而生:一个可编程的占星 API,让其他开发者
能够在产品、工作流、内部工具和实验中使用它。

这款产品的承诺刻意保持技术化:用一个 REST API 提供 natal charts、talent profiles、
两两 compatibility、模板化 interpretations、可选的 AI 改写、异步 PDF reports,以及一套
广泛的 Vedic 计算引擎。对外的网站把它定位为"面向开发者的可编程 natal charts、talent
profiles 与 compatibility",并提供免费的 maker 档位、dashboard、live demo,以及官方的
Python 和 TypeScript SDK。

## 产品做什么

Astrolinkers 把出生时间数据转换成结构化的占星输出。核心 API 可以创建 Western 或 Vedic
natal charts,从一套技能 ontology 派生 talent profiles,生成基于模板的 interpretations,
计算两两 compatibility,收集逐条 statement 的反馈,并通过异步 worker 流水线产出 HTML/PDF
reports。

Vedic 这一侧是刻意做深而非装点门面的:divisional charts、bhava chakra、Parashara drishti、
dignity、functional nature、Vimshottari dasha、yogas、Ashtakavarga、Shadbala、Panchanga、
Jaimini karakas、arudha、progressions、transits、Varshaphala、KP sub-lords,以及 muhurta
优化,都通过有文档的 endpoint 暴露出来。

系统处于 beta,但不是"样机"意义上的 beta。它有对外的营销网站、公开的 API 文档、dashboard
入口、live demo endpoint、自助式 API keys、rate limit、带类型的 SDK,以及面向生产的运维控制。

## 产品一览

## 我构建了什么

**后端平台。** 我把这个 API 构建成一个 clean-architecture 的 Python 服务:边缘是 FastAPI,
中间是应用层 use-case,核心是领域类型和 protocol,再加上面向 Postgres、Redis、Dramatiq 任务队列、
object storage、email、LLM provider（Anthropic、OpenAI 与自托管的 Ollama）和 Swiss Ephemeris
的具体 adapter。

**占星计算层。** 核心通过一个专用 adapter 使用 Swiss Ephemeris,并把 Western 和 Vedic
两种计算都封装在稳定的服务边界之后。对外契约是 JSON 进 / JSON 出;在内部,目标是可复现性、
可测试性,以及一条在未来若计算引擎成为性能瓶颈时能把它抽离出来的路径。

**Talent profile 与 interpretation 流水线。** 一套技能 ontology 把从星盘派生的信号映射成
软技能和硬技能分数。基于模板的 statement 给出确定性输出,而 LLM 层可以按 tone 改写
interpretation,同时不让 LLM 成为事实来源。

**异步 reports。** 繁重的报告生成不会作为一个长耗时的 HTTP request 来处理。一份报告会被
入队、由 worker 处理、渲染成 HTML/PDF、存入 object storage,再通过一个签名下载流程返回。

**生产控制。** 平台包含 JWT/bearer 认证、API-key 的签发与撤销、租户隔离、deny-by-default
的 scope 校验、变更请求的 idempotency、rate limiting、配额与用量追踪、审计 middleware、
结构化错误、readiness probe、metrics、tracing,以及 Sentry 集成。

**SDK 与开发者体验。** 我还交付了公开文档和官方 SDK:Python(`astrolinkers-sdk`)和
TypeScript(`@astrolinkers/sdk-ts`)。这些 SDK 暴露带类型的方法、响应校验、重试行为和带类型的
错误,使用户不必手写 HTTP 调用。

## 架构选择

**先做模块化单体。** 系统是一个代码库,带多个进程:API、worker 和 scheduler。这让交付保持
迅速,同时围绕占星、报告、interpretation、反馈、认证、用量和 API keys 保留清晰的接缝。如果某个
领域日后需要拆分,port 已经在那里了。

**LLM 是 adapter,而不是架构。** Astrolinkers 有 AI interpretation,但平台并不依赖于单一模型。
LLM provider 位于 protocol 和路由策略之后,配有 fallback、成本追踪、延迟追踪,并以确定性的
模板输出作为基线。

**反馈即护城河。** 每一条 interpretation statement 都能收集准确度反馈。这把主观的解读质量
变成了数据:模板准确度可以被聚合,较弱的规则可以被找出来,未来的打分可以从真实用户的判断而非
猜测中得到改进。

**从第一天起就可观测。** 系统暴露 Prometheus metrics、OpenTelemetry trace、结构化日志、
`/healthz`、`/readyz`、`/version`,以及运维 SLO。这很重要,因为占星计算、LLM provider、
worker 队列和 PDF 渲染会以不同的方式失败。

**带着生产纪律做 beta。** Astrolinkers 目前处于 beta,但它被当作一个真实的生产服务来对待:
带版本的 API、有文档的错误信封、rate limit、租户边界、runbook、SLO、部署清单,以及软发布闸门。

## 当前状态

Astrolinkers 已上线于 [astrolinkers.com](https://astrolinkers.com),公开文档位于
[docs.astrolinkers.com](https://docs.astrolinkers.com)。Dashboard 位于
[app.astrolinkers.com](https://app.astrolinkers.com),对外网站包含一个 live 星盘 demo,
它使用的正是用户通过 API 访问的同一套计算引擎。

这个项目是我独立完成的:产品立意、后端架构、占星引擎集成、API 契约、认证与配额、报告流水线、
文档、SDK、部署姿态,以及运维加固。下一阶段是扩大 beta 使用、收紧反馈循环,并把真实的使用数据
转化为更好的解读质量和更清晰的商业打包。