Astrolinkers — 可编程占星 API

问题所在

占星软件常常被劈成两种孱弱的形态:解读浅薄的消费级星座 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,以及面向生产的运维控制。

产品一览

• 

  面向 builders 的公开站点:一个 REST API,提供西方与吠陀星盘、天赋画像与合盘——带有免费的 maker 档位,以及无需注册即可试用的 demo。

• 

  公开的 API 文档。本命盘是其他所有端点都通过 id 引用的基础工件;这里是它的 POST /v1/charts 契约,侧边栏列出完整的西方与吠陀端点树。

• 

  控制台的自助登录,用户在此管理自己的 API key 与用量——包括为在常规流程之外开通的账户准备的 operator-issued token 路径。

• 

  按 key 的用量分析:请求量、错误数、成功率,以及滚动窗口内的每小时请求曲线图。把平台的可观测性回馈给用户。

• 

  自助套餐。免费的 maker 档位已上线,带有真实的限流与配额;付费档位在计费完成前先展示各自的限额——限额先于付费墙接好。

我构建了什么

后端平台。 我把这个 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,公开文档位于 docs.astrolinkers.com。Dashboard 位于 app.astrolinkers.com,对外网站包含一个 live 星盘 demo, 它使用的正是用户通过 API 访问的同一套计算引擎。

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