内容
# 大模型黄历 · Astro-LLM
> **大模型黄历**。一个仪表盘，每天告诉你 **(1)** 哪些模型 **今天表现突出**，是否应该花费或节省你的 tokens，以及 **(2)** 哪些模型 **实际上与你的价值观相符** —— 所有这些都包裹在一个类似占星术/天气报告的皮肤中，表面上看起来很有趣，实际上是一个真正的个人评估工具。
看起来像一个占卜黄历。实际上是一个基准测试工具。
**▶ 在线演示：** https://2-actual-hack.vercel.app · **仓库：** https://github.com/EthanPany/astro-llm
> 五种完全不同的主题布局（黄历 · 占卜 · 法庭 · 墨水 · 极光），一步一步的价值观匹配测验，以及实时的模型运势板块。完整的使用流程：[`docs/showcase.mp4`](docs/showcase.mp4)。
---
## 为什么
每天的编程计划（Claude Code、Codex 等）感觉略有不同 —— 有时相同的模型思考得更长，有时更敏锐，有时更糟糕。而哪个模型“理解”你的品味是个人化的。Astro-LLM 将这两者转化为每日的运势：
| 器官 | 占星术名称 | 真实测量内容 |
|------|----------------|--------------------------|
| **能力探测器** | 运势 *fortune* | 今天模型表现如何？—— 18 个确定性、自动评分的任务 → 一个智商、延迟、成本、拒绝率、趋势。 |
| **价值观匹配器** | 缘分 *affinity* | 它是否像你一样进行判断？—— 一系列主观困境；我们衡量一致性（足规则 + 裁决匹配）。 |
| **MCP 服务器** | — | 代理如何 **运行** 测试？ |
| **和谐循环** | 调和 *harmony* | 我们能否让模型更符合你的品味？—— 注入你的品味，重新测试 **未公开** 的困境。 |
“运势”是皮肤；下面的数字是真实的。请查看仪表盘底部的诚实说明。
---
## 快速开始（本地）
要求：Python 3.11+，[uv](https://docs.astral.sh/uv/)，Node 20+。
```bash
cp .env.example .env # 粘贴你的 API 密钥（所有密钥都是可选的 - 见下文）
make install # 后端虚拟环境（uv）+ 前端依赖
make seed # 探测实时模型，写入已提交的种子 JSON （可选）
make dev-backend # API 在 http://localhost:8000 （终端 1）
make dev-frontend # UI 在 http://localhost:5173 （终端 2）
```
打开 **http://localhost:5173**。
**没有密钥？** 它仍然有效。仓库中包含已提交的种子数据，因此仪表盘、判决网格和价值观匹配都可以在离线状态下渲染。密钥解锁实时重新探测（`↻ 实时巡检`）、实时自定义困境面板和和谐循环。
### 提供商
`ANTHROPIC_API_KEY`、`OPENAI_API_KEY`、`DEEPSEEK_API_KEY` 已连接并验证。
`GEMINI_API_KEY` / `QWEN_API_KEY` 已实现；如果没有这些密钥，模型将显示清晰标记的模拟数据。添加密钥将在下一次 `make seed` 时启用实时功能。
---
## 部署（一条命令）
```bash
make up # docker compose：构建前端，服务 SPA + API 在 :8000
# 或：
docker build -t astro-llm . && docker run -p 8000:8000 --env-file .env astro-llm
```
在生产环境中，FastAPI 提供构建的 SPA 和 API，来自 **相同的源**，因此无需其他配置。镜像中包含种子数据，因此即使没有密钥，也能正常渲染。
---
## 架构
```
后端/ FastAPI + httpx + pydantic + SQLite (uv-managed)
应用/
提供商/ 每个提供商的适配器（OpenAI/Anthropic/DeepSeek/Gemini/Qwen）
基准测试/ 困境库、能力任务、裁判 + 能力运行器、
匹配（足规则 + 一致性）、评分（智商 + 建议）
占星术/ 确定性十二星座 / 数秘术 / 运势 / 兼容性
循环/ 和谐（训练/测试防护栏）
存储/ SQLite 数据访问层 + 种子生成器
服务.py 装配：运行 + 占星术 -> AlmanacCards + 头条
api/路由.py REST API | mcp_server.py MCP 工具 | scheduler.py
前端/ React + Vite + TypeScript，手写 CSS，GSAP，手绘 SVG 图表
```
完整的数据合约：[`ARCHITECTURE.md`](./ARCHITECTURE.md)。
### API
`GET /api/dashboard` · `GET /api/models` · `GET /api/dilemmas` ·
`POST /api/match` · `POST /api/harmonize` · `POST /api/judge` · `GET /api/health`
### MCP
```bash
make mcp # python -m app.mcp_server （stdio）
```
工具：`list_models`、`get_almanac`、`judge_dilemma`、`match_me`、
`score_model_against_user`。将任何 MCP 客户端（例如 Claude Desktop）指向它，代理可以针对基准测试进行自我评分。
### 每小时黄历
设置 `ENABLE_SCHEDULER=true` 以按间隔（`PROBE_INTERVAL_MINUTES`）探测可用模型，
将真实运行结果持久化到 SQLite，以便趋势随时间推移成为测量数据。
---
## 测试
```bash
make test # 34 个测试：占星术、匹配、评分、裁判、裁判解析、
# 和谐、API（离线通过 TestClient + monkeypatched 种子）
```
## 设计
仅手写 CSS —— 没有 Tailwind，没有组件库，没有图表库。图表是手绘 SVG。字体：Fraunces（显示）+ Space Grotesk（UI）+ Space Mono（数字）。
GSAP 驱动进入动画、数字计数和图表绘制。
---
## 诚实说明
能力评分是真实的秒表 + 自动评分。价值观匹配衡量模型如何 **表现出与其相符的调性**，而不是隐藏的灵魂。和谐循环在模型在调谐过程中从未见过的 **未公开** 困境上进行评分 —— 这是防止“对齐”沦为奉承机器的防护栏。占星术仅供娱乐；我们如实说明。
> ⚠ 在公开此仓库之前，请旋转任何以明文共享的 API 密钥。
