feat(tests): add comprehensive tests for TokenRouter and related components

- Implement tests for TokenRouter downstream policy, covering allowedRouteIds and site weight multipliers. - Add tests for TokenRouter patterns and model mapping, including regex pattern matching and model mapping precedence. - Create tests for BrandIcon component to verify brand detection logic. - Develop tests for Accounts page, focusing on rebind panel behavior and refresh action on error. - Introduce fuzzy search utility tests to validate substring and subsequence matching. - Implement navigation focus helpers tests for building and parsing focus paths. - Add progressive render tests to ensure correct initial and next visible counts. - Create route model candidates index tests to validate route candidate indexing and matching logic.
2026-03-02 13:33:35 +08:00
parent 99c9e145c3
commit f6389a999a
98 changed files with 11286 additions and 801 deletions
@@ -2,7 +2,7 @@

 <img src="docs/logos/logo-full.png" alt="Metapi" width="280">

-🔮 **中转站的中转站 — 将分散的 AI 中转站聚合为一个统一网关**
+**中转站的中转站 — 将分散的 AI 中转站聚合为一个统一网关**

 <p>
 把你在各处注册的 New API / One API / OneHub / DoneHub / Veloera / AnyRouter / Sub2API 等站点，
@@ -36,7 +36,7 @@
 </p>

 <p align="center">
-  <a href="docs/README.md"><strong>📚 文档中心</strong></a> ·
+  <a href="docs/index.md"><strong>📚 文档中心</strong></a> ·
  <a href="docs/getting-started.md">快速上手</a> ·
  <a href="docs/deployment.md">部署指南</a> ·
  <a href="docs/configuration.md">配置说明</a> ·
@@ -52,7 +52,7 @@

 现在 AI 生态里有越来越多基于 New API / One API 系列的聚合中转站，要管理多个站点的余额、模型列表和 API 密钥，往往既分散又费时。

-Metapi 作为这些中转站之上的聚合层，把多个站点统一到 **一个 API Key、一个入口**。当前已支持基于以下项目的中转站：
+**Metapi** 作为这些中转站之上的**元聚合层（Meta-Aggregation Layer）**，把多个站点统一到 **一个入口（可按项目配置多个下游 API Key）**——下游所有工具（Cursor、Claude Code、Codex、Open WebUI 等）即可无感接入全部模型。当前已支持以下上游平台：

 - [New API](https://github.com/QuantumNous/new-api)
 - [One API](https://github.com/songquanpeng/one-api)
@@ -64,7 +64,7 @@ Metapi 作为这些中转站之上的聚合层，把多个站点统一到 **一

 | 痛点                                  | Metapi 怎么解决                                                 |
 | ------------------------------------- | --------------------------------------------------------------- |
-| 🔑 每个站点一个 Key，下游工具配置一堆 | **一个 Key 统一代理**，所有站点的模型自动聚合到 `/v1/*` |
+| 🔑 每个站点一个 Key，下游工具配置一堆 | **统一代理入口 + 可选多下游 Key 策略**，模型自动聚合到 `/v1/*` |
 | 💸 不知道哪个站点用某个模型最便宜     | **智能路由** 自动按成本、余额、使用率选最优通道           |
 | 🔄 某个站点挂了，手动切换好麻烦       | **自动故障转移**，一个通道失败自动冷却并切到下一个        |
 | 📊 余额分散在各处，不知道还剩多少     | **集中看板** 一目了然，余额不足自动告警                   |
@@ -79,27 +79,82 @@ Metapi 作为这些中转站之上的聚合层，把多个站点统一到 **一
  <tr>
    <td align="center">
      <img src="docs/screenshots/dashboard.png" alt="dashboard" style="width:100%;height:auto;"/>
-      <div>仪表盘</div>
+      <div><b>仪表盘</b> — 余额分布、消费趋势、系统概览</div>
    </td>
    <td align="center">
      <img src="docs/screenshots/model-marketplace.png" alt="model-marketplace" style="width:100%;height:auto;"/>
-      <div>模型广场</div>
+      <div><b>模型广场</b> — 跨站模型覆盖、定价对比、实测指标</div>
    </td>
  </tr>
  <tr>
    <td align="center">
      <img src="docs/screenshots/routes.png" alt="routes" style="width:100%;height:auto;"/>
-      <div>智能路由</div>
+      <div><b>智能路由</b> — 多通道概率分配、成本优先选路</div>
    </td>
    <td align="center">
      <img src="docs/screenshots/accounts.png" alt="accounts" style="width:100%;height:auto;"/>
-      <div>账号管理</div>
+      <div><b>账号管理</b> — 多站点多账号、健康状态追踪</div>
+    </td>
+  </tr>
+  <tr>
+    <td align="center">
+      <img src="docs/screenshots/sites.png" alt="sites" style="width:100%;height:auto;"/>
+      <div><b>站点管理</b> — 上游站点配置与状态一览</div>
+    </td>
+    <td align="center">
+      <img src="docs/screenshots/tokens.png" alt="tokens" style="width:100%;height:auto;"/>
+      <div><b>令牌管理</b> — API Token 生命周期管理</div>
+    </td>
+  </tr>
+  <tr>
+    <td align="center">
+      <img src="docs/screenshots/playground.png" alt="playground" style="width:100%;height:auto;"/>
+      <div><b>模型操练场</b> — 在线交互式模型测试</div>
+    </td>
+    <td align="center">
+      <img src="docs/screenshots/checkin.png" alt="checkin" style="width:100%;height:auto;"/>
+      <div><b>签到记录</b> — 自动签到状态与奖励追踪</div>
+    </td>
+  </tr>
+  <tr>
+    <td align="center">
+      <img src="docs/screenshots/proxy-logs.png" alt="proxy-logs" style="width:100%;height:auto;"/>
+      <div><b>使用日志</b> — 代理请求日志与成本明细</div>
+    </td>
+    <td align="center">
+      <img src="docs/screenshots/monitor.png" alt="monitor" style="width:100%;height:auto;"/>
+      <div><b>可用性监控</b> — 通道健康度实时监测</div>
+    </td>
+  </tr>
+  <tr>
+    <td align="center">
+      <img src="docs/screenshots/settings.png" alt="settings" style="width:100%;height:auto;"/>
+      <div><b>系统设置</b> — 全局参数与安全配置</div>
+    </td>
+    <td align="center">
+      <img src="docs/screenshots/notification-settings.png" alt="notification-settings" style="width:100%;height:auto;"/>
+      <div><b>通知设置</b> — 多渠道告警与推送配置</div>
    </td>
  </tr>
 </table>

 ---

+## 🏛️ 架构概览
+
+**下游客户端**（Cursor · Claude Code · Codex · Open WebUI · Cherry Studio 等）
+&emsp;↓ &ensp;`Authorization: Bearer <PROXY_TOKEN>`
+**Metapi 网关**
+&emsp;• 统一代理 `/v1/*` — 兼容 OpenAI / Claude 全接口
+&emsp;• 智能路由引擎 — 按成本、余额、可用率加权选路，失败自动冷却与重试
+&emsp;• 模型发现 — 自动聚合上游全部模型，零配置
+&emsp;• 格式转换 — OpenAI ⇄ Claude 双向透明转换
+&emsp;• 自动签到 · 余额管理 · 告警通知 · 数据看板
+&emsp;↓
+**上游平台**（New API · One API · OneHub · DoneHub · Veloera · AnyRouter · Sub2API …）
+
+---
+
 ## ✨ 核心功能

 ### 🌐 统一代理网关
@@ -117,6 +172,11 @@ Metapi 作为这些中转站之上的聚合层，把多个站点统一到 **一
 - 请求失败自动重试，自动切换其他可用通道
 - 路由决策可视化解释，每次选择透明可审计

+<div align="center">
+  <img src="docs/screenshots/routes.png" alt="smart-routing-detail" width="700"/>
+  <p><sub>智能路由配置界面 — 支持精确匹配、通配符、概率分配等多种路由策略</sub></p>
+</div>
+
 ### 📡 多平台聚合管理

 | 平台                | 适配器        | 说明                 |
@@ -146,6 +206,11 @@ Metapi 作为这些中转站之上的聚合层，把多个站点统一到 **一
 - 上游模型目录缓存与品牌分类（OpenAI、Anthropic、Google、DeepSeek 等）
 - 交互式模型测试器，在线验证模型可用性

+<div align="center">
+  <img src="docs/screenshots/model-marketplace.png" alt="model-marketplace-detail" width="700"/>
+  <p><sub>模型广场 — 一站式浏览所有可用模型的覆盖率、定价和性能指标</sub></p>
+</div>
+
 ### ✅ 自动签到

 - Cron 定时自动签到（默认每天 08:00）
@@ -180,6 +245,22 @@ Metapi 作为这些中转站之上的聚合层，把多个站点统一到 **一
 - 全局搜索（站点、账号、模型）
 - 系统事件日志、代理请求日志（含模型、状态、延迟、Token 消耗、成本估算）

+<div align="center">
+  <img src="docs/screenshots/dashboard.png" alt="dashboard-detail" width="700"/>
+  <p><sub>数据看板 — 余额分布、消费趋势、系统健康状态一目了然</sub></p>
+</div>
+
+### 🔬 模型操练场
+
+- 在线交互式对话测试，即时验证模型可用性与响应质量
+- 支持选择任意已路由模型，对比不同通道的输出效果
+- 流式 / 非流式双模式测试
+
+<div align="center">
+  <img src="docs/screenshots/playground.png" alt="playground-detail" width="700"/>
+  <p><sub>模型操练场 — 在线交互式测试，验证模型可用性与响应质量</sub></p>
+</div>
+
 ### 📦 轻量部署

 - **单 Docker 容器**，内置 SQLite，无外部依赖
@@ -299,15 +380,33 @@ docker compose pull && docker compose up -d && docker image prune -f

 ## 📚 文档中心

+> 文档站（VitePress）本地预览：
+>
+> ```bash
+> npm run docs:dev
+> ```
+>
+> 文档站构建：
+>
+> ```bash
+> npm run docs:build
+> ```
+>
+> GitHub Actions 自动发布：推送到 `main` 分支后，会执行 `.github/workflows/docs-pages.yml` 并部署到 GitHub Pages。
+> 首次使用需在仓库设置中开启：
+> `Settings -> Pages -> Build and deployment -> Source: GitHub Actions`
+
 | 分类          | 链接                                                  | 说明                                   |
 | ------------- | ----------------------------------------------------- | -------------------------------------- |
-| 📖 文档总览   | [docs/README.md](docs/README.md)                         | 文档导航与索引                         |
-| 🚀 快速上手   | [docs/getting-started.md](docs/getting-started.md)       | 10 分钟启动                            |
-| 🚢 部署指南   | [docs/deployment.md](docs/deployment.md)                 | Docker Compose、反向代理、升级回滚     |
-| ⚙️ 配置说明 | [docs/configuration.md](docs/configuration.md)           | 全部环境变量与路由参数                 |
+| 🏠 文档站首页 | [docs/index.md](docs/index.md)                         | 可发布文档站入口（导航/侧栏/搜索）     |
+| 📖 文档总览   | [docs/README.md](docs/README.md)                       | 文档导航与索引                         |
+| 🚀 快速上手   | [docs/getting-started.md](docs/getting-started.md)     | 10 分钟启动                            |
+| 🚢 部署指南   | [docs/deployment.md](docs/deployment.md)               | Docker Compose、反向代理、升级回滚     |
+| ⚙️ 配置说明 | [docs/configuration.md](docs/configuration.md)         | 全部环境变量与路由参数                 |
 | 🔌 客户端接入 | [docs/client-integration.md](docs/client-integration.md) | Open WebUI / Cherry Studio / Cursor 等 |
-| 🔧 运维手册   | [docs/operations.md](docs/operations.md)                 | 备份恢复、日志排查、健康检查           |
-| ❓ 常见问题   | [docs/faq.md](docs/faq.md)                               | 常见报错与修复路径                     |
+| 🔧 运维手册   | [docs/operations.md](docs/operations.md)               | 备份恢复、日志排查、健康检查           |
+| ❓ 常见问题   | [docs/faq.md](docs/faq.md)                             | 常见报错与修复路径                     |
+| 🧩 经验沉淀规范 | [docs/community/faq-tutorial-guidelines.md](docs/community/faq-tutorial-guidelines.md) | FAQ 与教程提交流程、模板与命名规则 |

 ---

@@ -395,6 +494,15 @@ Metapi 对下游暴露标准 OpenAI / Claude 兼容接口：

 请求头携带 `Authorization: Bearer <PROXY_TOKEN>` 即可访问。

+默认可使用全局 `PROXY_TOKEN`。  
+从 `系统设置 -> 下游 API Key 策略` 可创建多个项目级下游 Key，并单独配置：
+
+- 过期时间（ExpireAt）
+- 费用上限与请求上限（MaxCost / MaxRequests）
+- 模型白名单（SupportedModels，支持 exact/glob/re:regex）
+- 路由白名单（AllowedRouteIds）
+- 站点倍率（SiteWeightMultipliers，用于控制不同项目的上游偏好占比）
+
 ---

 ## 🔌 接入下游客户端
@@ -582,7 +690,7 @@ Metapi 完全自托管，所有数据（账号、令牌、路由、日志）均

 ## ⭐ Star History

-[![Star History Chart](https://api.star-history.com/svg?repos=cita-777/metapi&type=date&legend=top-left&v=1)](https://www.star-history.com/#cita-777/metapi&type=date&legend=top-left)
+[![Star History Chart](https://api.star-history.com/svg?repos=cita-777/metapi&type=date&legend=top-left&v=2)](https://www.star-history.com/#cita-777/metapi&type=date&legend=top-left)
 ---

 <div align="center">