# https://github.com/LuuOW/meridian-mcp 项目说明书
生成时间：2026-05-26 19:25:33 UTC
## 目录
- [项目概述](#overview)
- [轨道分类器详解](#orbital-classifier)
- [系统架构](#architecture)
- [数据流与反馈机制](#data-flow)
- [部署指南](#deployment)
- [运维手册](#operations)
- [扩展与定制开发](#extensions)
- [版本与元数据管理](#metadata-management)
- [前端组件](#frontend)
- [MCP 协议集成](#mcp-protocol)
## 项目概述
### 相关页面
相关主题：[轨道分类器详解](#orbital-classifier), [系统架构](#architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/LuuOW/meridian-mcp/blob/main/README.md)
- [package.json](https://github.com/LuuOW/meridian-mcp/blob/main/package.json)
- [design-system/README.md](https://github.com/LuuOW/meridian-mcp/blob/main/design-system/README.md)
- [design-system/ui_kits/landing/README.md](https://github.com/LuuOW/meridian-mcp/blob/main/design-system/ui_kits/landing/README.md)
- [design-system/ui_kits/miniapp/README.md](https://github.com/LuuOW/meridian-mcp/blob/main/design-system/ui_kits/miniapp/README.md)
- [design-system/ui_kits/helix/README.md](https://github.com/LuuOW/meridian-mcp/blob/main/design-system/ui_kits/helix/README.md)
- [helio-mirror/README.md](https://github.com/LuuOW/meridian-mcp/blob/main/helio-mirror/README.md)
- [finance-mcp/README.md](https://github.com/LuuOW/meridian-mcp/blob/main/finance-mcp/README.md)
- [photon-route/src/photon_route/corpus.py](https://github.com/LuuOW/meridian-mcp/blob/main/photon-route/src/photon_route/corpus.py)
# 项目概述
Meridian MCP 是一个基于 Model Context Protocol (MCP) 的**动态任务路由系统**，通过天体轨道力学（orbital mechanics）隐喻来实现领域无关的候选路由功能。该项目采用自包含（self-contained）架构，无需外部后端依赖即可独立运行。
## 项目背景与目标
Meridian MCP 的核心目标是解决 AI Agent 在执行任务时的**候选实体路由问题**。传统的路由方案通常依赖预定义的查表或领域特定的规则引擎，而 Meridian 创新性地引入了轨道物理学隐喻：
> 将每个候选实体映射为天体系统中的一个天体（行星、卫星、特洛伊小行星、彗星等），通过物理特征向量自动分类，无需人工维护候选库。
**版本信息：** 当前稳定版本为 **v3.2.0**，发布于 2026-05-14，包含轨道分类器校准和热路径优化等改进。 资料来源：[package.json](https://github.com/LuuOW/meridian-mcp/blob/main/package.json)
## 核心架构
Meridian MCP 采用分层架构设计，包含以下核心层次：
```mermaid
graph TD
subgraph "接入层 Transport"
A1[stdio 传输]
A2[HTTP/Streamable 传输]
end
subgraph "MCP 协议层"
B[MCP SDK]
end
subgraph "核心业务层"
C[任务解析器]
D[LLM 候选生成器]
E[轨道分类器]
end
subgraph "外部依赖"
F[GitHub Models
Llama-3.3-70B]
end
A1 --> B
A2 --> B
B --> C
C --> D
D --> F
F --> E
E --> G[分类结果]
```
**架构特点：**
| 特性 | 描述 | 资料来源 |
|------|------|----------|
| 自包含 | 轨道分类器运行在进程内，LLM 调用直接连接 GitHub Models | [README.md](https://github.com/LuuOW/meridian-mcp/blob/main/README.md) |
| 双传输模式 | 支持 stdio 和 HTTP/Streamable 两种传输方式 | [package.json:14-15](https://github.com/LuuOW/meridian-mcp/blob/main/package.json) |
| 多客户端兼容 | 支持 Grok、ChatGPT、Claude 等主流 AI 客户端 | [package.json:9-17](https://github.com/LuuOW/meridian-mcp/blob/main/package.json) |
| 零后端依赖 | 无需自建推理服务，利用 GitHub 免费的 Models API | [README.md](https://github.com/LuuOW/meridian-mcp/blob/main/README.md) |
## 主要组件
### MCP 核心模块
| 模块 | 文件路径 | 功能说明 |
|------|----------|----------|
| `mcp/index.mjs` | stdio 传输入口 | 标准输入输出模式的 MCP 服务器 | [package.json:14](https://github.com/LuuOW/meridian-mcp/blob/main/package.json) |
| `mcp/http.mjs` | HTTP 传输入口 | HTTP/Streamable 模式的 MCP 服务器 | [package.json:15](https://github.com/LuuOW/meridian-mcp/blob/main/package.json) |
### 设计系统
Meridian 维护了一套完整的设计系统（Design System），确保多端视觉一致性：
```mermaid
graph LR
subgraph "design-system/"
A[tokens.css]
B[preview/]
C[ui_kits/]
D[assets/]
end
subgraph "ui_kits/ 覆盖应用"
L[landing]
M[miniapp]
H[helix]
D1[docs]
L1[lens]
P[photon-router]
end
A --> L
A --> M
A --> H
A --> D1
A --> L1
A --> P
```
**Token 系统** 包含以下核心变量：
| 变量类别 | 示例 | 说明 |
|----------|------|------|
| 颜色 | `--accent` (#a78bfa) | 主强调色（霓虹紫） |
| 渐变 | `--grad-hero` | 英雄区域渐变（紫→青→薄荷） |
| 阴影 | `--shadow-card` | 卡片阴影效果 |
| 类型类 | `.t-display`, `.t-h1`, `.t-eyebrow` | 语义化字体类 |
| 动画 | `neonRotate`, `gradShift`, `liveDotPing` | 品牌标志性动效 |
资料来源：[design-system/README.md](https://github.com/LuuOW/meridian-mcp/blob/main/design-system/README.md)
### UI 套件
| 套件 | 目标站点 | 主要组件 |
|------|----------|----------|
| `landing` | ask-meridian.uk/ | Hero、FleetGrid、StatsStrip、FeaturesGrid、HowItWorks、PricingGrid、CtaFinal、Nav |
| `miniapp` | ask-meridian.uk/miniapp | AskCard、ResultsList、MetaBar、CandidatePanel、MiniGalaxy、Nav |
| `helix` | meridian.ask-meridian.uk/helix | 蛋白质→恒星系统可视化、UniProt 数据展示 |
| `docs` | ask-meridian.uk/docs | Sidebar、Article、Callout、CodeBlock、OnThisPage |
| `lens` | meridian.ask-meridian.uk/lens | WebXR Vision Lab |
| `photon-router` | photon.ask-meridian.uk | 文档与演示 |
资料来源：[design-system/ui_kits/landing/README.md](https://github.com/LuuOW/meridian-mcp/blob/main/design-system/ui_kits/landing/README.md)、[design-system/ui_kits/miniapp/README.md](https://github.com/LuuOW/meridian-mcp/blob/main/design-system/ui_kits/miniapp/README.md)、[design-system/ui_kits/helix/README.md](https://github.com/LuuOW/meridian-mcp/blob/main/design-system/ui_kits/helix/README.md)
## 轨道分类器系统
### 物理特征向量
轨道分类器从候选实体的**内容本身**提取 9 维物理签名，无需查表：
| 维度 | 计算方式 | 物理意义 |
|------|----------|----------|
| `mass` | log(body_length × keyword_count) | 天体质量 |
| `scope` | 范围广度 | 影响范围 |
| `independence` | 独立性程度 | 主权级别 |
| `cross_domain` | 跨三个恒星系统的熵 | 跨领域亲和性 |
| `fragmentation` | 分片程度 | 碎片化程度 |
| `drag` | 阻力系数 | 拖拽效应 |
| `dep_ratio` | max sibling Jaccard | 依赖比率 |
| `lagrange_potential` | 拉格朗日势能 | 稳定位置 |
| `coherence_time` | g⁽¹⁾ 风格自相关 | 相干时间 |
资料来源：[README.md](https://github.com/LuuOW/meridian-mcp/blob/main/README.md)
### 分类规则
基于提取的物理特征，六个分类评分规则决定最终天体类别：
```
score_planet = min(mass, scope, independence)^1.5
score_moon = 2 · max(0, ½ - independence) · 𝟙[parent] · (1 - mass/2)
score_trojan = dep_ratio · 𝟙[parent] · (1 - fragmentation)
score_asteroid = 2.0 (基础分)
score_comet = drag · cross_domain
score_irregular = max(fragmentation, 1 - coherence_time)
```
**天体类别定义：**
| 类别 | 描述 | 典型场景 |
|------|------|----------|
| `planet` | 大质量、高独立性、全面覆盖 | 核心工具、主流程 |
| `moon` | 依赖父实体、较低独立性 | 辅助插件、依赖工具 |
| `trojan` | 高依赖比、稳定碎片 | 配套服务 |
| `asteroid` | 基础分类分值 | 独立小工具 |
| `comet` | 高拖拽、跨域 | 跨领域桥接 |
| `irregular` | 高度碎片化、低相干 | 临时/试验性功能 |
### v3.2.0 分类器校准
**2026-05-14** 的更新重点改进了分类器死区问题：
- **Moon/Comet/Irregular 脱离死区**：原版分类器对这三类的评分区域存在重叠死区，导致部分合法候选被错误分类
- **长度偏差减少**：降低了 `mass` 对分类结果的过度影响
资料来源：[社区发布说明](https://github.com/LuuOW/meridian-mcp/issues)（见 v3.2.0 Release Notes）
## 部署与运行
### 安装方式
```bash
# 全局安装（推荐）
npm install -g meridian-orbital
# 或本地安装
npm install meridian-orbital
```
### 启动模式
| 模式 | 命令 | 适用场景 |
|------|------|----------|
| stdio | `meridian-mcp` 或 `node mcp/index.mjs` | Claude Desktop、Cursor、Windsurf |
| HTTP | `meridian-mcp-http` 或 `node mcp/http.mjs` | Grok、ChatGPT、远程连接 |
资料来源：[package.json:17-19](https://github.com/LuuOW/meridian-mcp/blob/main/package.json)
### 环境要求
| 要求 | 规格 |
|------|------|
| Node.js | >= 20 |
| GitHub 账户 | 需要 GitHub Models API 访问权限 |
| 网络 | 需要访问 github.com/models |
## 关联项目
Meridian MCP 仓库采用 monorepo 结构，包含以下独立但相关的子项目：
### Helio Mirror
天文数据镜像服务，将 Parker Solar Probe (PSP)、ISOIS、WISPR、JWST 等多源天文数据汇聚到 Hugging Face。
| 数据源 | 采集内容 | 触发方式 |
|--------|----------|----------|
| PSP | 磁场 (FIELDS) + 太阳风粒子 (SWEAP/SPC) L3 数据 | 近日点事件 |
| ISOIS | 能量粒子数据 | 近日点事件 |
| WISPR | 日冕图像 | 近日点事件 |
| JWST | Mars/Jupiter/Saturn 观测数据 | 每周两次 |
资料来源：[helio-mirror/README.md](https://github.com/LuuOW/meridian-mcp/blob/main/helio-mirror/README.md)
### Finance MCP
基于 Cloudflare Workers 的金融 MCP 服务，集成了 WebAuthn 无密码认证（Passkey）和 Binance API。
| 端点 | 方法 | 功能 |
|------|------|------|
| `/mcp` | POST | MCP JSON-RPC 接口 |
| `/authorize` | GET/POST | OAuth 登录 + Passkey |
| `/token` | POST | PKCE 授权码兑换 |
| `/admin/create-registration-link` | POST | 管理员创建一次性注册链接 |
资料来源：[finance-mcp/README.md](https://github.com/LuuOW/meridian-mcp/blob/main/finance-mcp/README.md)
### Photon Route
文档路由引擎，作为 Meridian 路由能力的独立验证实现，提供与 qrouter 的对比基准。
```python
# 示例文档结构
class Document:
text: str # 文档内容
meta: dict # 元数据（id, topic等）
# 预置测试语料库
_FIXTURE = [
Document("photons travel through optical fibers...", meta={"id": "fixture-001"}),
Document("superposition lets a quantum bit...", meta={"id": "fixture-002"}),
# ...
]
```
资料来源：[photon-route/src/photon_route/corpus.py](https://github.com/LuuOW/meridian-mcp/blob/main/photon-route/src/photon_route/corpus.py)
## 版本历史
| 版本 | 发布日期 | 主要变更 |
|------|----------|----------|
| 3.2.0 | 2026-05-14 | 轨道分类器校准：Moon/Comet/Irregular 脱离死区；长度偏差优化；热路径收紧 |
| 3.1.0 | — | 新增 `coherence_time` 维度；特征向量维度确认为 25 |
| 2.0.0 | — | 重构为自包含架构；LLM 切换至 GitHub Models |
| 1.0.1 | — | 最后支持 Cloudflare 后端的版本（已废弃） |
| 0.3.2 | — | 旧版闭合域分类器 + 88 条目语料库（已归档） |
**注意：** Issue #907 指出元数据一致性问题是当前的技术债务，包括版本号（3.1.0）、特征向量维度（25）和规范 URL 在 README.md、package.json、landing/docs/index.html 中的重复定义。建议通过 pre-commit 或 CI 检查来确保一致性。
## 运行测试
```bash
# 单元测试
npm test
# UI 测试（Playwright）
npm run test:ui
```
测试配置位于 `tests/ui/playwright.config.mjs`，依赖 Playwright 1.60.0+。
## 参见
- [设计系统详细文档](../design-system/README.md) — Token 系统、UI 组件库、品牌资源
- [Miniapp 使用指南](../miniapp/README.md) — 任务轨道交互界面
- [Helix 蛋白质可视化](../helix/README.md) — 治疗性蛋白质推荐系统
- [Helio 天文数据](../helio-mirror/README.md) — 多源天文数据镜像
- [Finance MCP 部署](../finance-mcp/README.md) — 金融数据路由服务
- [GitHub 仓库](https://github.com/LuuOW/meridian-mcp)
---
## 轨道分类器详解
### 相关页面
相关主题：[项目概述](#overview), [数据流与反馈机制](#data-flow), [版本与元数据管理](#metadata-management)
相关源码文件
以下源码文件用于生成本页说明：
- [mcp/_lib/orbital.mjs](https://github.com/LuuOW/meridian-mcp/blob/main/mcp/_lib/orbital.mjs) — 轨道分类器核心实现
- [mcp/_lib/core.mjs](https://github.com/LuuOW/meridian-mcp/blob/main/mcp/_lib/core.mjs) — MCP 核心逻辑与路由编排
- [mcp/_lib/tokenize.mjs](https://github.com/LuuOW/meridian-mcp/blob/main/mcp/_lib/tokenize.mjs) — 文本向量化与特征提取
- [package.json](https://github.com/LuuOW/meridian-mcp/blob/main/package.json) — 包配置与依赖声明
- [README.md](https://github.com/LuuOW/meridian-mcp/blob/main/README.md) — 项目整体说明
- [mcp/index.mjs](https://github.com/LuuOW/meridian-mcp/blob/main/mcp/index.mjs) — stdio 传输层入口
- [mcp/http.mjs](https://github.com/LuuOW/meridian-mcp/blob/main/mcp/http.mjs) — HTTP/Streamable 传输层入口
# 轨道分类器详解
## 1. 概述
轨道分类器（Orbital Classifier）是 Meridian MCP 的核心推理引擎，采用天体物理学类比的方式对候选路由条目进行分类排序。与传统基于规则或机器学习的路由系统不同，轨道分类器从候选内容的文本特征中提取 25 维物理签名，并将其映射为六个天体分类：`planet`（行星）、`moon`（卫星）、`trojan`（特洛伊小行星）、`asteroid`（小行星）、`comet`（彗星）、`irregular`（不规则天体）。
该分类器的设计目标包括：
- **领域无关性**：候选条目可以是工具、提示词、文档、产品或任何可路由实体
- **自包含运行**：分类器在进程内运行，无需外部依赖
- **确定性输出**：相同输入总是产生相同分类结果
- **无监督特征提取**：基于文本统计特征计算物理签名，不依赖预训练模型
> **版本说明**：当前版本为 **v3.2.0**（2026-05-14），包含分类器校准改进，将 moon、comet、irregular 从"死区"中解放出来，并减少长度偏差。资料来源：[package.json](https://github.com/LuuOW/meridian-mcp/blob/main/package.json)
---
## 2. 架构设计
### 2.1 系统架构图
```mermaid
graph TD
subgraph 输入层
A[用户请求 Task] --> B[LLM 生成候选条目]
B --> C[N 个候选路由条目]
end
subgraph 特征提取层
C --> D[Tokenize 文本分词]
D --> E[计算 25 维物理签名]
end
subgraph 分类层
E --> F[轨道分类器 Orbital]
F --> G[六分类 argmax]
end
subgraph 输出层
G --> H[分类结果 + 排名]
end
style A fill:#1a1a2e,color:#fff
style F fill:#16213e,color:#fff
style H fill:#0f3460,color:#fff
```
### 2.2 组件职责
| 组件 | 文件路径 | 职责说明 |
|------|----------|----------|
| **orbital.mjs** | `mcp/_lib/orbital.mjs` | 轨道分类器核心实现，包含物理签名计算与分类规则 |
| **core.mjs** | `mcp/_lib/core.mjs` | MCP 核心逻辑，编排 LLM 调用与分类器交互 |
| **tokenize.mjs** | `mcp/_lib/tokenize.mjs` | 文本分词与向量化，提取 token 序列用于特征计算 |
| **index.mjs** | `mcp/index.mjs` | stdio 传输层入口，对接 Claude/Cursor/Windsurf |
| **http.mjs** | `mcp/http.mjs` | HTTP/Streamable 传输层入口，对接 Grok/ChatGPT |
资料来源：[mcp/_lib/](https://github.com/LuuOW/meridian-mcp/blob/main/mcp/_lib/)
### 2.3 传输层兼容性
Meridian MCP 支持多种传输协议，不同协议对应不同的客户端兼容性：
| 传输方式 | 入口文件 | 支持客户端 |
|----------|----------|------------|
| **stdio** | `mcp/index.mjs` | Claude Desktop, Cursor, Windsurf |
| **HTTP/Streamable** | `mcp/http.mjs` | Grok, ChatGPT, 远程 MCP 客户端 |
| **远程 MCP** | `mcp.ask-meridian.uk/v1/route` | Web 前端（Miniapp） |
---
## 3. 物理签名详解
### 3.1 签名向量结构
轨道分类器从每个候选条目中提取 **25 维物理签名**，分为两类：动力学参数（9 个标量）和轨道/光学参数（16 个参数）。
#### 动力学参数（9 维）
| 参数名 | 计算方式 | 物理含义 |
|--------|----------|----------|
| `mass` | log(主体长度 × 关键词数量) | 天体质量（对数尺度） |
| `scope` | 候选内容覆盖范围 | 任务作用域 |
| `independence` | 独立执行能力 | 与其他任务的依赖程度 |
| `cross_domain` | 跨三个星系的 token-域熵 | 跨领域亲和度 |
| `fragmentation` | 内容碎片化程度 | 任务碎片化指数 |
| `drag` | 内容阻力系数 | 执行摩擦力 |
| `dep_ratio` | 最大兄弟 Jaccard 相似度 | 依赖比率 |
| `lagrange_potential` | 拉格朗日点潜力值 | 稳定性指标 |
| `coherence_time` | token 序列自相关（g¹ 风格） | 时间相干性 |
> **v3.1.0 新增**：`coherence_time` 通过 token 序列的一阶自相关计算获得，用于衡量内容的语义连贯性。资料来源：[README.md](https://github.com/LuuOW/meridian-mcp/blob/main/README.md)
#### 轨道与光学参数（16 维）
| 参数类型 | 参数列表 |
|----------|----------|
| **轨道参数** | 半长轴（semi-major axis）、离心率（eccentricity）、倾角（inclination）、周期（period）、近日点（perihelion）、远日点（aphelion）、平近点角（mean anomaly） |
| **光学参数** | 波长（wavelength）、偏振（polarization）、振幅（amplitude）、相位（phase） |
### 3.2 特征提取流程
```mermaid
graph LR
A[候选文本] --> B[Tokenize 分词]
B --> C[词频统计]
C --> D[关键词提取]
D --> E[域熵计算]
E --> F[自相关分析]
F --> G[25 维签名向量]
```
特征提取的核心逻辑位于 `tokenize.mjs` 中，该模块负责：
1. **文本分词**：将候选内容分解为 token 序列
2. **词频统计**：计算各 token 的出现频率
3. **关键词提取**：识别高权重的特征词
4. **域熵计算**：评估跨领域分布的均匀程度
5. **自相关分析**：计算 token 序列的时间相干性
---
## 4. 分类规则
### 4.1 六分类体系
轨道分类器将候选条目映射为六个天体类别：
| 分类 | 语义含义 | 典型场景 |
|------|----------|----------|
| `planet` | 核心任务 | 需要完整执行的主任务 |
| `moon` | 依赖任务 | 附属于行星的子任务 |
| `trojan` | 共享依赖任务 | 与其他任务共享依赖 |
| `asteroid` | 碎片化任务 | 分散的子任务集合 |
| `comet` | 低依赖任务 | 边缘独立任务 |
| `irregular` | 不规则任务 | 无法分类的特殊情况 |
### 4.2 评分公式
分类通过 **argmax** 机制实现，即计算六个候选分数并选择最高者。各分类的评分规则如下：
```
score_planet = min(mass, scope, independence)^1.5
score_moon = 2 · max(0, ½ - independence) · 𝟙[parent] · (1 - mass/2)
score_trojan = dep_ratio · 𝟙[parent] · (1 - fragmentation)
score_asteroid = 2 · max(0, fragmentation - ½) · (1 - dep_ratio)
score_comet = (1 - mass) · drag · (1 - independence)
score_irregular = max(0, 1 - coherence_time)
```
其中 `𝟙[parent]` 是父任务指示函数。
### 4.3 v3.2.0 分类器校准
**v3.2.0** 版本对分类器进行了关键校准，解决了以下问题：
| 问题 | 改进前 | 改进后 |
|------|--------|--------|
| Moon 死区 | 大量 moon 类条目被误判为 irregular | 通过调整 `independence` 阈值解放 |
| Comet 死区 | 低依赖任务因 `mass` 过高被排除 | 降低 `mass` 对 comet 评分的影响 |
| 长度偏差 | 长文本自然获得更高分数 | 引入归一化因子减少长度相关性 |
资料来源：[README.md - v3.2.0 Release Notes](https://github.com/LuuOW/meridian-mcp/blob/main/README.md)
### 4.4 分类决策流程
```mermaid
graph TD
A[计算 9 维动力学签名] --> B[计算 6 个分类分数]
B --> C{score_planet 最高?}
C -->|是| D[返回 planet]
C -->|否| E{score_moon 最高?}
E -->|是| F[返回 moon]
E -->|否| G{score_trojan 最高?}
G -->|是| H[返回 trojan]
G -->|否| I{score_asteroid 最高?}
I -->|是| J[返回 asteroid]
I -->|否| K{score_comet 最高?}
K -->|是| L[返回 comet]
K -->|否| M[返回 irregular]
```
---
## 5. LLM 集成
### 5.1 候选生成
轨道分类器并非独立工作，而是作为 LLM 路由管道的下游组件。完整流程如下：
1. **LLM 生成**：使用 Llama-3.3-70B（通过 GitHub Models 免费层）生成 N 个候选路由条目
2. **并行分类**：对每个候选条目独立运行轨道分类器
3. **排名输出**：根据分类结果和评分进行最终排序
### 5.2 GitHub Models 集成
| 配置项 | 值 |
|--------|-----|
| **模型** | Llama-3.3-70B |
| **API** | GitHub Models |
| **认证** | `GITHUB_TOKEN` 环境变量 |
| **配额** | GitHub Free Tier（慷慨限制） |
> **注意**：Meridian MCP 采用"自包含"设计，LLM 调用直接发送到 GitHub Models，无需中间代理。这将延迟从 30-50 秒降低到 5-15 秒。资料来源：[README.md](https://github.com/LuuOW/meridian-mcp/blob/main/README.json)
---
## 6. 配置与部署
### 6.1 环境变量
| 变量名 | 必填 | 说明 |
|--------|------|------|
| `GITHUB_TOKEN` | 是 | GitHub 认证令牌，用于访问 GitHub Models |
| `PORT` | 否 | HTTP 服务器端口（默认：3000） |
### 6.2 启动方式
```bash
# stdio 模式（Claude Desktop / Cursor / Windsurf）
npm run stdio
# HTTP 模式（Grok / ChatGPT）
npm run http
# 运行测试
npm test
```
### 6.3 依赖项
| 依赖 | 版本要求 | 用途 |
|------|----------|------|
| `@modelcontextprotocol/sdk` | ^1.0.0 | MCP 协议实现 |
| `node` | >=20 | 运行时环境 |
资料来源：[package.json](https://github.com/LuuOW/meridian-mcp/blob/main/package.json)
---
## 7. 在线学习能力
### 7.1 自适应机制
轨道分类器支持在线学习，能够根据用户反馈动态调整分类参数：
```mermaid
graph LR
A[候选分类结果] --> B[用户选择反馈]
B --> C[更新分类阈值]
C --> D[调整签名权重]
D --> A
```
### 7.2 版本迁移说明
| 版本 | 架构 | 状态 |
|------|------|------|
| **0.3.x** | 封闭域 Python 评分器 + 88 条语料库 | 已废弃（可使用 `meridian-skills-mcp@0.3.2` 固定） |
| **1.0.1** | Cloudflare 后端调用 | 已废弃（HTTP 405 错误） |
| **2.0.0+** | 自包含 Orbital 分类器 | 当前版本 |
---
## 8. 常见问题与故障排除
### 8.1 分类结果不稳定
**症状**：相同输入产生不同分类结果
**可能原因**：
- 未设置 `GITHUB_TOKEN` 导致 LLM 调用失败
- token 序列的非确定性分词
**解决方案**：
- 检查环境变量配置
- 查看 `tokenize.mjs` 的确定性分词模式
### 8.2 所有候选被分类为同一类别
**症状**：大量候选项返回相同的 `irregular` 分类
**可能原因**：
- 输入文本过短或过长
- `coherence_time` 计算异常
- v3.2.0 之前的版本存在"死区"问题
**解决方案**：
- 升级到 v3.2.0
- 检查输入文本的 token 长度分布
- 参考 [Issue #907](https://github.com/LuuOW/meridian-mcp/issues/907) 追踪元数据一致性问题
### 8.3 LLM 调用超时
**症状**：候选生成阶段超时（30+ 秒）
**可能原因**：
- GitHub Models 服务不可用
- 网络延迟过高
**解决方案**：
- 检查 GitHub 账户配额
- 考虑使用本地 LLM 替代方案
---
## 9. 相关资源
### 9.1 实时演示
| 入口 | 地址 | 说明 |
|------|------|------|
| **Miniapp** | [ask-meridian.uk/miniapp](https://ask-meridian.uk/miniapp) | 输入任务，查看轨道可视化 |
| **Lens（WebXR）** | [meridian.ask-meridian.uk/lens/](https://meridian.ask-meridian.uk/lens/) | Vision Lab，头戴设备帧分类 |
| **Live MCP** | `mcp.ask-meridian.uk/v1/route` | 远程 MCP 端点 |
### 9.2 设计系统
Meridian 视觉语言定义于 `design-system/` 目录，包含：
- `tokens.css` — CSS 自定义属性与语义类型类
- `preview/` — 49 个独立 HTML 预览页面
- `ui_kits/` — 各表面的 UI 组件包
---
## 10. See Also
- [MCP 协议集成指南](./mcp-integration.md) — 了解如何将 Meridian 连接到 Claude Desktop
- [HTTP 传输层配置](./http-transport.md) — 配置远程 MCP 连接
- [设计系统文档](../design-system/README.md) — 品牌视觉规范
- [Miniapp 开发指南](../miniapp/README.md) — 轨道可视化组件详解
---
## 系统架构
### 相关页面
相关主题：[项目概述](#overview), [部署指南](#deployment), [数据流与反馈机制](#data-flow)
相关源码文件
以下源码文件用于生成本页说明：
- [mcp/index.mjs](https://github.com/LuuOW/meridian-mcp/blob/main/mcp/index.mjs) — stdio 传输协议实现
- [mcp/http.mjs](https://github.com/LuuOW/meridian-mcp/blob/main/mcp/http.mjs) — HTTP/Streamable 传输实现
- [cf-worker/worker.mjs](https://github.com/LuuOW/meridian-mcp/blob/main/cf-worker/worker.mjs) — Cloudflare Worker 远程部署
- [api-worker/worker.mjs](https://github.com/LuuOW/meridian-mcp/blob/main/api-worker/worker.mjs) — API Worker 实现
- [package.json](https://github.com/LuuOW/meridian-mcp/blob/main/package.json) — 项目元数据与依赖配置
- [README.md](https://github.com/LuuOW/meridian-mcp/blob/main/README.md) — 核心架构说明
- [design-system/README.md](https://github.com/LuuOW/meridian-mcp/blob/main/design-system/README.md) — 设计系统架构
- [finance-mcp/README.md](https://github.com/LuuOW/meridian-mcp/blob/main/finance-mcp/README.md) — 金融模块架构
# 系统架构
Meridian MCP 是一个基于**轨道力学**的任务路由系统，通过物理类比将候选对象分类为不同的天体类型（行星、卫星、特洛伊小行星、小行星、彗星、不规则体），实现领域无关的动态路由。本文档详细阐述该系统的整体架构、核心组件、数据流向以及部署模式。
---
## 1 系统概述
### 1.1 核心定位
Meridian MCP 的设计目标是提供**自包含的 MCP（Model Context Protocol）服务器**，支持动态任务路由与候选排名。系统不依赖外部后端，LLM 调用直接对接 GitHub Models 的免费层（Llama-3.3-70B），轨道分类器在进程内运行。
资料来源：[package.json:8-15](https://github.com/LuuOW/meridian-mcp/blob/main/package.json)
### 1.2 技术栈
| 层级 | 技术选型 |
|------|---------|
| 运行时 | Node.js ≥20 |
| MCP SDK | @modelcontextprotocol/sdk ^1.0.0 |
| LLM 供应商 | GitHub Models (Llama-3.3-70B) |
| 传输协议 | stdio / HTTP/Streamable |
| 部署平台 | Cloudflare Workers |
| 测试框架 | Playwright |
| 语言 | JavaScript/TypeScript (ES Module) |
资料来源：[package.json:17-30](https://github.com/LuuOW/meridian-mcp/blob/main/package.json)
---
## 2 系统架构图
```mermaid
graph TB
subgraph "客户端层"
CLI[Claude CLI]
Cursor[Cursor IDE]
Windsurf[Windsurf]
Grok[Grok]
ChatGPT[ChatGPT]
end
subgraph "MCP 传输层"
Stdio[stdio 传输]
Http[HTTP/Streamable]
end
subgraph "核心处理层"
Router[轨道路由器]
LLM[Llama-3.3-70B]
Classifier[轨道分类器]
KV[(KV 存储)]
end
subgraph "外部服务"
GitHub[GitHub Models API]
Cloudflare[Cloudflare Workers]
end
CLI --> Stdio
Cursor --> Stdio
Windsurf --> Stdio
Grok --> Http
ChatGPT --> Http
Stdio --> Router
Http --> Router
Router --> LLM
Router --> Classifier
LLM --> GitHub
Classifier --> KV
Http --> Cloudflare
```
---
## 3 核心组件详解
### 3.1 MCP 服务器实现
#### 3.1.1 stdio 传输模式
`mcp/index.mjs` 是标准的 stdio 传输 MCP 服务器入口，提供与 Claude CLI、Cursor、Windsurf 等工具的直接集成。
**入口点配置：**
```javascript
{
"bin": {
"meridian-mcp": "./mcp/index.mjs"
}
}
```
资料来源：[package.json:10-13](https://github.com/LuuOW/meridian-mcp/blob/main/package.json)
#### 3.1.2 HTTP/Streamable 传输模式
`mcp/http.mjs` 提供 HTTP 传输支持，适用于 Grok、ChatGPT 等需要远程连接的客户端。
**入口点配置：**
```javascript
{
"bin": {
"meridian-mcp-http": "./mcp/http.mjs"
}
}
```
资料来源：[package.json:10-13](https://github.com/LuuOW/meridian-mcp/blob/main/package.json)
### 3.2 轨道分类器（Orbital Classifier）
轨道分类器是系统的核心创新，通过物理类比将候选对象映射到天体类型。
#### 3.2.1 特征向量结构
分类器提取 **25 维特征向量**：
| 特征类型 | 数量 | 具体特征 |
|---------|------|---------|
| 物理标量 | 9 | mass, scope, independence, cross_domain, fragmentation, drag, dep_ratio, lagrange_potential, coherence_time |
| 类别独热码 | 6 | planet, moon, trojan, asteroid, comet, irregular |
| 星系独热码 | 3 | token-domain entropy across three star systems |
| token 命中特征 | 3 | token-hit features |
| 排名特征 | 4 | ranking features |
资料来源：[README.md:5-10](https://github.com/LuuOW/meridian-mcp/blob/main/README.md)
#### 3.2.2 分类规则
六类天体通过以下规则进行 argmax 评分：
```
score_planet = min(mass, scope, independence)^1.5
score_moon = 2 · max(0, ½ - independence) · 𝟙[parent] · (1 - mass/2)
score_trojan = dep_ratio · 𝟙[parent] · (1 - fragmentation)
score_asteroid = 2.5 · (1 + tanh(K · w·x))
...
```
资料来源：[README.md:12-18](https://github.com/LuuOW/meridian-mcp/blob/main/README.md)
#### 3.2.3 在线学习机制
分类器支持在线学习更新：
- **权重更新公式**：`(1 + tanh(K · w·x))` — 有界于 [0, 2]
- **冷启动策略**：`w = 0`，乘数为 1，纯启发式
- **版本控制**：特征向量使用 `FEATURE_VERSION=v2` 存储于 KV
资料来源：[README.md:45-52](https://github.com/LuuOW/meridian-mcp/blob/main/README.md)
---
## 4 数据流架构
### 4.1 候选路由完整流程
```mermaid
sequenceDiagram
participant Client as MCP 客户端
participant Router as 轨道路由器
participant LLM as Llama-3.3-70B
participant Classifier as 轨道分类器
participant KV as KV 存储
Client->>Router: 请求任务描述
Router->>LLM: 生成 N 个候选路由条目
LLM-->>Router: 返回候选列表
Router->>Classifier: 提取 25 维特征向量
Classifier-->>Router: 物理签名
Router->>Classifier: 计算各类别评分
Classifier-->>Router: 天体分类结果
Router->>KV: 存储特征向量与结果
Router-->>Client: 排序后的候选结果
```
### 4.2 在线学习反馈循环
```mermaid
graph LR
A[人工标注 / HF 基准] --> B[classifier-bootstrap.yml]
B --> C[/v1/feedback 端点]
C --> D[更新分类器权重]
D --> E[/v1/model-info 读状态]
E --> A
```
分类器通过两个 GitHub Actions cron 任务实现自动化学习：
| 工作流 | 执行频率 | 功能 |
|--------|---------|------|
| `classifier-bootstrap.yml` | 每 3 天 | 从公共 HF 基准获取标注样本 |
| `classifier-health.yml` | 每周一 | 发布 recall@1/@5 和模型状态 |
资料来源：[README.md:53-57](https://github.com/LuuOW/meridian-mcp/blob/main/README.md)
---
## 5 部署架构
### 5.1 部署模式概览
| 模式 | 入口文件 | 传输协议 | 适用场景 |
|------|---------|---------|---------|
| 本地 stdio | `mcp/index.mjs` | stdio | Claude CLI, Cursor, Windsurf |
| 本地 HTTP | `mcp/http.mjs` | HTTP/Streamable | 开发调试 |
| Cloudflare Worker | `cf-worker/worker.mjs` | HTTP | 生产远程部署 |
| API Worker | `api-worker/worker.mjs` | HTTP | 专用 API 端点 |
### 5.2 远程 MCP 服务
生产环境通过 Cloudflare Workers 提供远程 MCP 访问：
- **MCP 端点**：`mcp.ask-meridian.uk/v1/route`
- **Vision 端点**：`mcp.ask-meridian.uk/v1/vision`（WebXR 使用）
资料来源：[README.md:30-35](https://github.com/LuuOW/meridian-mcp/blob/main/README.md)
---
## 6 前端集成架构
### 6.1 设计系统
Meridian 采用统一的设计系统管理多端 UI：
```mermaid
graph TB
subgraph "设计系统"
Tokens[tokens.css
设计令牌]
Preview[preview/
49 个预览页]
UIKits[ui_kits/
各端组件库]
end
subgraph "应用表面"
Landing[ask-meridian.uk/]
Miniapp[ask-meridian.uk/miniapp]
Docs[ask-meridian.uk/docs]
Helix[meridian.ask-meridian.uk/helix]
Lens[meridian.ask-meridian.uk/lens]
end
Tokens --> Preview
Tokens --> UIKits
UIKits --> Landing
UIKits --> Miniapp
UIKits --> Docs
UIKits --> Helix
UIKits --> Lens
```
资料来源：[design-system/README.md:1-30](https://github.com/LuuOW/meridian-mcp/blob/main/design-system/README.md)
### 6.2 设计令牌
核心设计令牌：
| 类别 | 令牌 | 值 |
|------|------|-----|
| 主色调 | `--accent` | `#a78bfa` (neon-violet) |
| 渐变 | `--grad-hero` | violet → cyan → mint |
| 阴影 | `--shadow-card` | 卡片阴影 |
| 字体 | Inter / JetBrains Mono | 正文字体 / 等宽字体 |
| 间距基准 | `--s-1` | 4px |
资料来源：[design-system/README.md:35-50](https://github.com/LuuOW/meridian-mcp/blob/main/design-system/README.md)
---
## 7 金融模块架构（finance-mcp）
### 7.1 认证流程
finance-mcp 提供基于 WebAuthn 的无密码认证：
```mermaid
graph LR
A[管理员创建注册链接] --> B[用户访问链接]
B --> C{注册 passkey}
C --> D[WebAuthn 注册选项]
D --> E[用户验证]
E --> F[存储 passkey]
F --> G[销毁一次性链接]
G --> H[OAuth 授权]
H --> I[MCP 调用]
```
### 7.2 OAuth 2.0 端点
| 方法 | 端点 | 功能 | 认证 |
|------|------|------|------|
| POST | `/admin/create-registration-link` | 创建一次性注册链接 | X-Admin-Secret |
| GET | `/register/:token` | Passkey 注册页面 | 一次性链接 |
| POST | `/register/:token/options` | WebAuthn 注册选项 | 一次性链接 |
| POST | `/register/:token/verify` | 验证并存储 passkey | 一次性链接 |
| GET | `/authorize` | OAuth 起始 | client_id |
| POST | `/login/options` | WebAuthn 认证选项 | challenge key |
| POST | `/login/verify` | WebAuthn 认证验证 | challenge key |
| POST | `/token` | 代码兑换 bearer | OAuth client |
| POST | `/mcp` | MCP JSON-RPC | Bearer |
资料来源：[finance-mcp/README.md:25-45](https://github.com/LuuOW/meridian-mcp/blob/main/finance-mcp/README.md)
---
## 8 配置与运维
### 8.1 环境变量配置
| 变量 | 说明 | 示例 |
|------|------|------|
| `ADMIN_SECRET` | 管理端认证密钥 | 长随机字符串 |
| `USER_ID` | 用户标识 | "lucas" |
| `OAUTH_CLIENT_ID` | OAuth 客户端 ID | "grok" |
| `ORIGIN` | 服务起源 | Cloudflare 域名 |
| `HF_TOKEN` | HuggingFace 访问令牌 | 写权限令牌 |
资料来源：[finance-mcp/README.md:48-55](https://github.com/LuuOW/meridian-mcp/blob/main/finance-mcp/README.md)
### 8.2 KV 命名空间
Cloudflare Workers 使用两个 KV 命名空间：
| 命名空间 | 用途 |
|---------|------|
| `VAULT_KV` | 生产环境存储 |
| `VAULT_KV --preview` | 预览环境存储 |
资料来源：[finance-mcp/README.md:47-50](https://github.com/LuuOW/meridian-mcp/blob/main/finance-mcp/README.md)
---
## 9 版本历史与迁移
### 9.1 版本 3.2.0（2026-05-14）
最新版本包含三项独立改进：
1. **轨道分类器校准**：将 moon/comet/irregular 从死区中释放，减少长度偏差
2. **热路径优化**：降低延迟
3. **分类数值改进**：无 API 变更，完全向后兼容
### 9.2 从旧版本迁移
| 旧版本 | 迁移目标 | 说明 |
|--------|---------|------|
| 0.3.x | meridian-skills-mcp@0.3.2 | 保留闭合域 Python 计分器 + 88 条语料库 |
| 1.0.1 | 不再使用 | 云端后端已废弃（HTTP 405） |
资料来源：[README.md:60-68](https://github.com/LuuOW/meridian-mcp/blob/main/README.md)
---
## 10 常见问题与限制
### 10.1 已知限制
| 问题 | 影响 | 规避方案 |
|------|------|---------|
| 元数据一致性（#907） | 版本号、特征向量维度、URL 在多处重复 | 计划实现 pre-commit/CI 检查 |
| 冷启动无标注数据 | 分类器初期依赖纯启发式 | 使用 `w = 0` 初始化，权重为 1 |
| OAuth 路径无学习 | Grok/ChatGPT/Claude.ai 连接器保持确定性 | 保持可重现性 |
### 10.2 模拟与监控
系统通过定时模拟任务监控健康状态：
| 文件模式 | 来源工作流 | 频率 |
|---------|-----------|------|
| `orbital-YYYY-MM-DD.txt` | `.github/workflows/sim-orbital.yml` | 周二、五 06:11 UTC |
| `helix-YYYY-MM-DD.txt` | `.github/workflows/sim-helix.yml` | 周三 08:17 UTC |
资料来源：[data/sim-reports/README.md:1-15](https://github.com/LuuOW/meridian-mcp/blob/main/data/sim-reports/README.md)
---
## 11 See Also
- [快速开始指南](getting-started) — 本地部署与快速配置
- [API 参考](api-reference) — 完整 API 端点文档
- [轨道分类器详解](orbital-classifier) — 物理类比与分类算法
- [设计系统](design-system) — UI 令牌与组件库
- [金融模块](finance-mcp) — OAuth + WebAuthn 认证架构
---
## 数据流与反馈机制
### 相关页面
相关主题：[轨道分类器详解](#orbital-classifier), [系统架构](#architecture), [运维手册](#operations)
相关源码文件
以下源码文件用于生成本页说明：
- [cf-worker/online_learning.mjs](https://github.com/LuuOW/meridian-mcp/blob/main/cf-worker/online_learning.mjs)
- [scripts/calibrate-classifier.mjs](https://github.com/LuuOW/meridian-mcp/blob/main/scripts/calibrate-classifier.mjs)
- [scripts/calibration-baseline.json](https://github.com/LuuOW/meridian-mcp/blob/main/scripts/calibration-baseline.json)
- [mcp/index.mjs](https://github.com/LuuOW/meridian-mcp/blob/main/mcp/index.mjs)
- [mcp/http.mjs](https://github.com/LuuOW/meridian-mcp/blob/main/mcp/http.mjs)
- [data/sim-reports/README.md](https://github.com/LuuOW/meridian-mcp/blob/main/data/sim-reports/README.md)
# 数据流与反馈机制
## 概述
Meridian MCP 的数据流与反馈机制构成了一个闭环系统，将自然语言任务转化为天体物理学类别的候选项，并通过持续校准与在线学习不断优化分类精度。系统核心由三个阶段组成：**任务输入 → LLM 候选生成 → 轨道分类器处理**，最终输出带完整分类信息的排序结果。
本文档详细阐述该闭环系统的架构设计、数据流向、反馈收集机制以及分类器校准流程。
## 核心数据流架构
```mermaid
graph TD
subgraph 输入层
A[自然语言任务] --> B[route_task 工具调用]
end
subgraph 处理层
B --> C[GitHub Models
Llama-3.3-70B]
C --> D[生成 N 个候选]
D --> E[轨道分类器]
E --> F[物理特征提取]
F --> G[天体分类]
end
subgraph 输出层
G --> H[排序候选项]
H --> I[返回完整结果]
end
subgraph 反馈回路
I --> J[结果使用追踪]
J --> K[在线学习模块]
K --> L[分类器微调]
L --> E
end
subgraph 校准机制
K --> M[校准脚本]
M --> N[基准数据对比]
N --> L
end
```
### 数据流阶段详解
| 阶段 | 组件 | 输入 | 输出 | 耗时 |
|------|------|------|------|------|
| 1. 任务接收 | `route_task` | 自然语言任务描述 | 任务对象 | 即时 |
| 2. 候选生成 | Llama-3.3-70B | 任务文本 | 5 个候选对象 | 2-5 秒 |
| 3. 特征提取 | 轨道分类器 | 候选内容 | 9 维物理向量 | <100ms |
| 4. 分类判决 | 分类规则引擎 | 物理向量 | 天体类别 | <50ms |
| 5. 结果输出 | MCP 响应序列化 | 分类结果 | JSON-RPC 响应 | 即时 |
资料来源：[README.md:核心流程概述]()
## 轨道分类器工作机制
### 物理特征向量
轨道分类器从每个候选项的纯内容中提取**9 维物理特征向量**，无需查表或预训练嵌入：
| 特征名称 | 计算方式 | 物理含义 |
|----------|----------|----------|
| `mass` | log(body_length × keyword_count) | 候选质量 |
| `scope` | 作用域跨度 | 影响范围 |
| `independence` | 依赖度 | 独立执行能力 |
| `cross_domain` | token-domain entropy | 跨领域亲和度 |
| `fragmentation` | 分片程度 | 结构碎片化 |
| `drag` | 执行阻力 | 复杂度指标 |
| `dep_ratio` | max sibling Jaccard | 依赖比率 |
| `lagrange_potential` | 拉格朗日势能 | 稳定性指标 |
| `coherence_time` | g⁽¹⁾-style autocorrelation | 连贯时间（v3.1.0 新增）|
资料来源：[README.md:物理特征提取]()
### 天体分类规则
系统通过六个分类规则计算得分，取 argmax 确定最终类别：
```
score_planet = min(mass, scope, independence)^1.5
score_moon = 2 · max(0, ½ - independence) · 𝟙[parent] · (1 - mass/2)
score_trojan = dep_ratio · 𝟙[parent] · (1 - fragmentation)
score_asteroid = 2.0 · (mass < threshold && independence > threshold)
score_comet = drag · cross_domain · fragmentation
score_irregular = fallback/default
```
资料来源：[README.md:分类规则引擎]()
### 分类器校准 (v3.2.0)
v3.2.0 版本对分类器进行了重新校准，主要改进包括：
- **Moon/Comet/Irregular 死区提升**：将这些类别从分类死区中移出
- **长度偏差降低**：减少候选文本长度对分类结果的影响
- **热路径优化**：缩短分类推理延迟
校准数据基准存储于 `scripts/calibration-baseline.json`，可通过 `scripts/calibrate-classifier.mjs` 脚本验证分类精度变化。
资料来源：[calibrate-classifier.mjs 脚本说明](https://github.com/LuuOW/meridian-mcp/blob/main/scripts/calibrate-classifier.mjs)
## 在线学习与反馈机制
### 反馈收集架构
```mermaid
sequenceDiagram
participant Client as 客户端代理
participant MCP as MCP 服务器
participant OLM as 在线学习模块
participant Classifier as 轨道分类器
Client->>MCP: route_task(task)
MCP->>Client: 分类结果
Note over Client: 结果被使用/采纳
Client->>OLM: 反馈信号
(采纳/拒绝/修正)
OLM->>OLM: 更新内部状态
OLM->>Classifier: 权重调整
Note over OLM: 下次调用生效
```
### 在线学习模块
`cf-worker/online_learning.mjs` 实现了边缘计算环境下的在线学习能力：
| 功能 | 描述 |
|------|------|
| 反馈收集 | 收集用户对分类结果的采纳/拒绝信号 |
| 权重更新 | 根据反馈动态调整分类器参数 |
| 状态持久化 | 在 Cloudflare KV 中存储学习状态 |
| 冷启动处理 | 使用校准基线数据初始化 |
资料来源：[cf-worker/online_learning.mjs]()
### 反馈信号类型
| 信号类型 | 触发条件 | 分类器响应 |
|----------|----------|------------|
| 采纳 | 用户使用了某个候选项 | 正向强化该类别权重 |
| 拒绝 | 用户跳过某候选项 | 负向强化该类别权重 |
| 修正 | 用户手动指定正确类别 | 直接调整分类边界 |
| 超时 | 候选项未被及时使用 | 降低新颖度权重 |
## 模拟与验证流程
### 自动化模拟报告
系统通过 GitHub Actions 定期运行模拟验证，数据流状态变更后自动生成报告：
| 报告类型 | 文件模式 | 触发频率 | 用途 |
|----------|---------|----------|------|
| Orbital 模拟 | `orbital-YYYY-MM-DD.txt` | 周二、五 06:11 UTC | 轨道分类器回归测试 |
| Helix 模拟 | `helix-YYYY-MM-DD.txt` | 周三 08:17 UTC | 蛋白质候选流程 |
| Photon 模拟 | `photon-YYYY-MM-DD-*.json` | 手动触发 | 量子路由验证 |
资料来源：[data/sim-reports/README.md]()
### 模拟异常检测
观察连续两份模拟报告可发现漂移现象：
- `recall@1` 下降 → 分类边界可能偏移
- `nDCG@5` 崩溃 → 排序权重异常
- 分类分布异常 → 特征提取管道问题
```bash
# 本地运行模拟
# 参见 OPERATIONS.md → "Simulations" 章节
```
## 环境配置与数据流控制
### 关键环境变量
| 变量名 | 默认值 | 用途 |
|--------|--------|------|
| `MERIDIAN_GITHUB_TOKEN` | 降级至 `GITHUB_TOKEN` | GitHub API 认证 |
| `MERIDIAN_MODEL` | `meta/llama-3.3-70b-instruct` | LLM 模型选择 |
| `MERIDIAN_MODELS_ENDPOINT` | `https://models.github.ai/inference/chat/completions` | API 端点 |
| `MERIDIAN_CANDIDATES` | `5` | 每请求生成的候选项数量 |
| `MERIDIAN_ENABLE_ONLINE_LEARNING` | `true` | 启用/禁用在线学习 |
| `MERIDIAN_CALIBRATION_MODE` | `production` | 校准模式（production/development）|
资料来源：[README.md:环境变量配置]()
## MCP 传输层与数据流
### Stdio 传输模式
```mermaid
graph LR
A[Claude/Cline] -->|stdio| B[meridian-mcp]
B -->|stdout| A
B <--> C[GitHub Models API]
```
适用于本地开发与 CLI 工具集成：
```bash
# 启动 stdio 模式
npm run stdio
# 或直接执行
node mcp/index.mjs
```
### HTTP/Streamable 传输模式
```mermaid
graph LR
A[Grok/ChatGPT] -->|HTTP| B[meridian-mcp-http]
B -->|Streamable HTTP| A
B <--> C[GitHub Models API]
B <--> D[Cloudflare KV
在线学习状态]
```
适用于远程部署与云端代理场景：
```bash
# 启动 HTTP 模式
npm run http
# 或直接执行
node mcp/http.mjs
```
资料来源：[mcp/http.mjs:HTTP 传输实现]()
## 常见数据流问题与解决
### 分类结果与预期不符
**症状**：返回的候选项类别与任务语义不匹配
**排查步骤**：
1. 检查 `scripts/calibration-baseline.json` 是否过期
2. 运行 `node scripts/calibrate-classifier.mjs` 验证基准
3. 查看最新 `orbital-*.txt` 模拟报告的 recall@1 指标
4. 确认 `coherence_time` 特征是否异常（v3.1.0 新增）
**解决方案**：
- 执行分类器重校准流程
- 检查反馈信号是否被正确收集
- 验证 `cross_domain` 特征提取逻辑
### 在线学习未生效
**症状**：反馈后分类结果未见改善
**排查步骤**：
1. 确认 `MERIDIAN_ENABLE_ONLINE_LEARNING=true`
2. 检查 Cloudflare KV 连接状态
3. 验证 `cf-worker/online_learning.mjs` 日志输出
4. 确认反馈信号格式正确
### 数据一致性问题
**背景**：社区 issue #907 指出元数据（版本号、特征向量维度、URL）在多处重复存在，存在不一致风险。
**受影响位置**：
- `README.md`
- `package.json`
- `landing/docs/index.html`
**建议**：实现 pre-commit 或 CI 检查确保元数据同步。
## 性能基准
| 指标 | v2.0.x（旧版） | v3.2.0（当前） | 改进 |
|------|----------------|----------------|------|
| 端到端延迟 | 30-50 秒 | 5-15 秒 | ~75% 降低 |
| 特征提取延迟 | ~500ms | <100ms | ~80% 降低 |
| 分类判决延迟 | ~200ms | <50ms | ~75% 降低 |
| LLM 调用延迟 | 25-45 秒 | 2-5 秒 | ~88% 降低 |
资料来源：[README.md:版本对比]()
## 相关资源
- [分类器校准脚本](https://github.com/LuuOW/meridian-mcp/blob/main/scripts/calibrate-classifier.mjs) — 验证分类精度
- [在线学习模块](https://github.com/LuuOW/meridian-mcp/blob/main/cf-worker/online_learning.mjs) — 边缘学习实现
- [配置参考](https://github.com/LuuOW/meridian-mcp/blob/main/README.md#configuration) — 完整环境变量列表
- [模拟报告](https://github.com/LuuOW/meridian-mcp/blob/main/data/sim-reports/README.md) — 自动化测试结果
## 参见
- [轨道分类器原理](./orbital-classifier.md) — 分类算法的数学推导
- [MCP 协议集成](./mcp-integration.md) — 与 Claude/Grok 的连接配置
- [贡献指南](./contributing.md) — 提交反馈改进建议
---
## 部署指南
### 相关页面
相关主题：[系统架构](#architecture), [运维手册](#operations)
相关源码文件
以下源码文件用于生成本页说明：
- [Dockerfile](https://github.com/LuuOW/meridian-mcp/blob/main/Dockerfile)
- [binance-proxy/Dockerfile](https://github.com/LuuOW/meridian-mcp/blob/main/binance-proxy/Dockerfile)
- [cf-worker/wrangler.toml](https://github.com/LuuOW/meridian-mcp/blob/main/cf-worker/wrangler.toml)
- [api-worker/wrangler.toml](https://github.com/LuuOW/meridian-mcp/blob/main/api-worker/wrangler.toml)
- [finance-mcp/README.md](https://github.com/LuuOW/meridian-mcp/blob/main/finance-mcp/README.md)
- [finance-mcp/src/index.ts](https://github.com/LuuOW/meridian-mcp/blob/main/finance-mcp/src/index.ts)
- [package.json](https://github.com/LuuOW/meridian-mcp/blob/main/package.json)
- [mcp/index.mjs](https://github.com/LuuOW/meridian-mcp/blob/main/mcp/index.mjs)
- [mcp/http.mjs](https://github.com/LuuOW/meridian-mcp/blob/main/mcp/http.mjs)
- [photon-route/src/photon_route/http_server.py](https://github.com/LuuOW/meridian-mcp/blob/main/photon-route/src/photon_route/http_server.py)
- [helio-mirror/README.md](https://github.com/LuuOW/meridian-mcp/blob/main/helio-mirror/README.md)
# 部署指南
本文档介绍 Meridian-MCP 项目的多种部署方式，涵盖 MCP 服务器（stdio 和 HTTP 传输层）、Cloudflare Workers 部署（Finance MCP）、Python Photon Route 服务，以及 GitHub Actions 自动化部署流程。
## 概述
Meridian-MCP 是一个自包含的 MCP（Model Context Protocol）实现，集成了轨道任务路由和在线学习分类器。项目支持多种部署模式，适用于不同的使用场景：
| 部署模式 | 传输协议 | 适用场景 | 入口文件 |
|---|---|---|---|
| 本地 MCP | stdio | Claude Desktop、Cursor、Windsurf 等本地 AI 工具 | [mcp/index.mjs](https://github.com/LuuOW/meridian-mcp/blob/main/mcp/index.mjs) |
| 远程 MCP | HTTP/Streamable | Grok、ChatGPT、Claude.ai 等云端服务 | [mcp/http.mjs](https://github.com/LuuOW/meridian-mcp/blob/main/mcp/http.mjs) |
| Finance MCP | Cloudflare Workers | 金融数据代理 + WebAuthn 认证 | [finance-mcp/src/index.ts](https://github.com/LuuOW/meridian-mcp/blob/main/finance-mcp/src/index.ts) |
| Photon Route | FastAPI | 文档检索与排名服务 | [photon-route/src/photon_route/http_server.py](https://github.com/LuuOW/meridian-mcp/blob/main/photon-route/src/photon_route/http_server.py) |
## MCP 服务器部署
### 前置条件
- Node.js >= 20
- npm 或 yarn 包管理器
- GitHub Models API 访问权限（用于生成候选路由）
### stdio 传输模式（本地部署）
stdio 模式适用于需要本地运行的 AI 工具集成，如 Claude Desktop、Cursor、Windsurf 等。
#### 安装步骤
```bash
# 克隆仓库
git clone https://github.com/LuuOW/meridian-mcp.git
cd meridian-mcp
# 安装依赖
npm install
# 全局安装 MCP 服务器
npm install -g
```
#### 配置 Claude Desktop
在 Claude Desktop 的 MCP 配置文件（`~/.config/claude-desktop/claude_desktop_config.json`）中添加：
```json
{
"mcpServers": {
"meridian-mcp": {
"command": "node",
"args": ["/path/to/meridian-mcp/mcp/index.mjs"]
}
}
}
```
#### 验证安装
```bash
# 测试 stdio 模式
npm run stdio
```
### HTTP/Streamable 传输模式（远程部署）
HTTP 模式支持通过 RESTful API 调用 MCP 功能，适用于 Web 应用集成。
#### 启动 HTTP 服务器
```bash
# 使用 npm 脚本
npm run http
# 或直接运行
node mcp/http.mjs
```
服务器默认监听端口取决于环境配置，访问 `GET /` 返回服务状态信息。
#### API 端点
| 端点 | 方法 | 描述 | 认证 |
|---|---|---|---|
| `/mcp` | POST | MCP JSON-RPC 接口 | Bearer Token |
| `/v1/model-info` | GET | 只读模型状态信息 | 无 |
| `/v1/feedback` | POST | 反馈数据入口 | 视配置而定 |
### Docker 容器部署
项目提供了多阶段构建的 Dockerfile，支持容器化部署。
```dockerfile
# 资料来源：Dockerfile
FROM node:20-slim AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
FROM node:20-slim
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY mcp ./mcp
COPY package.json .
ENV NODE_ENV=production
CMD ["node", "mcp/index.mjs"]
```
#### 构建与运行
```bash
# 构建镜像
docker build -t meridian-mcp:latest .
# 运行 stdio 模式
docker run -it meridian-mcp:latest
# 运行 HTTP 模式
docker run -p 3000:3000 meridian-mcp:latest node mcp/http.mjs
```
## Cloudflare Workers 部署
### Finance MCP 部署
Finance MCP 是一个运行在 Cloudflare Workers 上的金融数据代理服务，集成了 WebAuthn 免密码认证。
#### 部署架构
```mermaid
graph TD
A[用户浏览器] -->|WebAuthn| B[Cloudflare Workers]
B -->|读取/写入| C[KV Storage]
B -->|代理请求| D[Binance API]
A -->|OAuth 授权| B
subgraph Cloudflare Edge
B
C
end
```
#### 前置条件
- Wrangler CLI (`npm install -g wrangler`)
- Cloudflare 账号
- Cloudflare KV 命名空间
#### 部署步骤
1. **安装依赖并配置 Wrangler**
```bash
cd finance-mcp
npm install
```
2. **创建 KV 命名空间**
```bash
npx wrangler kv namespace create VAULT_KV
npx wrangler kv namespace create VAULT_KV --preview
```
3. **配置 wrangler.toml**
编辑 [cf-worker/wrangler.toml](https://github.com/LuuOW/meridian-mcp/blob/main/cf-worker/wrangler.toml)：
```toml
name = "finance-vault"
main = "src/index.ts"
compatibility_date = "2024-01-01"
[[kv_namespaces]]
binding = "VAULT_KV"
id = ""
preview_id = ""
```
4. **设置环境变量和密钥**
```bash
# 设置公共源地址
npx wrangler secret put ORIGIN # 例如 https://finance.ask-meridian.uk
# 设置管理员密钥
npx wrangler secret put ADMIN_SECRET
# 设置用户 ID
npx wrangler secret put USER_ID
# 设置 OAuth 客户端 ID
npx wrangler secret put OAUTH_CLIENT_ID
# 设置 OAuth 客户端密钥
npx wrangler secret put OAUTH_CLIENT_SECRET
# 设置 Binance API 密钥
npx wrangler secret put BINANCE_API_KEY
npx wrangler secret put BINANCE_SECRET_KEY
```
5. **部署到 Cloudflare**
```bash
npx wrangler deploy
```
#### API 端点一览
| 端点 | 方法 | 描述 | 认证方式 |
|---|---|---|---|
| `/` | GET | 服务状态页 | 无 |
| `/admin/create-registration-link` | POST | 创建一次性注册链接 | X-Admin-Secret |
| `/register/:token` | GET | Passkey 注册页面 | 一次性链接 |
| `/register/:token/options` | POST | WebAuthn 注册选项 | 一次性链接 |
| `/register/:token/verify` | POST | 验证并存储 Passkey | 一次性链接 |
| `/authorize` | GET | OAuth 授权起始 | client_id |
| `/login/options` | POST | WebAuthn 认证选项 | challenge key |
| `/login/verify` | POST | 验证 WebAuthn 响应 | challenge key |
| `/authorize/complete` | GET | 颁发 OAuth 代码 | 已完成登录 |
| `/token` | POST | 兑换访问令牌 | OAuth client |
| `/mcp` | POST | MCP JSON-RPC 接口 | Bearer |
#### OAuth 2.0 端点
服务实现了标准 OAuth 2.0 端点用于机器间认证：
```bash
# 获取授权
GET /authorize?client_id=&redirect_uri=&response_type=code&scope=read
# 交换令牌
POST /token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code=&redirect_uri=&client_id=&code_verifier=
```
### Binance Proxy 部署
Binance Proxy 是一个轻量级代理服务，用于转发 Binance API 请求。
```dockerfile
# 资料来源：binance-proxy/Dockerfile
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY src ./src
EXPOSE 8080
CMD ["node", "src/index.js"]
```
#### 构建并运行
```bash
cd binance-proxy
docker build -t binance-proxy:latest .
docker run -p 8080:8080 \
-e BINANCE_API_KEY=your_api_key \
-e BINANCE_SECRET_KEY=your_secret_key \
binance-proxy:latest
```
## Python Photon Route 服务部署
Photon Route 是一个基于 FastAPI 的文档检索和排名服务。
### 依赖安装
```bash
cd photon-route
pip install -e .
```
### 运行服务
```bash
# 使用 uvicorn
uvicorn photon_route.http_server:app --host 0.0.0.0 --port 8000
# 或使用项目脚本
python -m photon_route.http_server
```
### API 端点
| 端点 | 方法 | 描述 |
|---|---|---|
| `/` | GET | 健康检查 |
| `/rank` | GET | 查询文档排名 |
| `/corpus` | GET | 获取语料库信息 |
| `/corpus/embed` | POST | 添加文档到语料库 |
| `/weights` | GET | 获取训练权重 |
#### 排名查询示例
```bash
curl "http://localhost:8000/rank?q=quantum+entanglement&top_k=5&backend=v1"
```
响应格式：
```json
{
"query": "quantum entanglement",
"backend": "v1",
"results": [
{"rank": 1, "score": 0.95, "text": "qubits entangle across distant detectors", "meta": {"id": "fixture-005", "topic": "entanglement"}}
]
}
```
## GitHub Actions 自动化部署
### Helio Mirror 自动同步
项目使用 GitHub Actions 定时同步太阳物理学数据：
```yaml
# 资料来源：.github/workflows/helio-mirror-pull.yml（由 helio-mirror/README.md 描述）
# 触发条件：每周按计划或手动触发
# 主要功能：拉取 PSP、SolO、WISPR、JWST 等航天器数据
```
#### 触发方式
```bash
# 通过 gh CLI 触发
gh workflow run helio-mirror-pull.yml -R LuuOW/meridian-mcp -f perihelion=E20
```
#### 必需的秘密变量
| 变量名 | 描述 | 权限要求 |
|---|---|---|
| `HF_TOKEN` | Hugging Face 写入令牌 | 写访问 |
### 分类器健康检查
项目包含两个定时运行的分类器健康检查工作流：
| 工作流 | 运行频率 | 功能 |
|---|---|---|
| `classifier-bootstrap.yml` | 每 3 天 | 从 HuggingFace 公共基准测试获取标注样本，发送到 `/v1/feedback` |
| `classifier-health.yml` | 每周一 | 发布 recall@1/@5 和模型状态到 `landing/healthz.json` |
## 环境变量配置
### MCP 服务器环境变量
| 变量名 | 描述 | 默认值 |
|---|---|---|
| `GITHUB_TOKEN` | GitHub API 认证令牌 | - |
| `LOG_LEVEL` | 日志级别 (debug/info/warn/error) | info |
| `MCP_PORT` | HTTP 服务器端口 | 3000 |
### Finance MCP 环境变量
| 变量名 | 描述 | 必需 |
|---|---|---|
| `ORIGIN` | 服务公共源地址 | 是 |
| `ADMIN_SECRET` | 管理员密钥 | 是 |
| `USER_ID` | 用户标识符 | 是 |
| `OAUTH_CLIENT_ID` | OAuth 客户端 ID | 是 |
| `OAUTH_CLIENT_SECRET` | OAuth 客户端密钥 | 是 |
| `BINANCE_API_KEY` | Binance API 密钥 | 是 |
| `BINANCE_SECRET_KEY` | Binance 密钥 | 是 |
### Helio Mirror 环境变量
| 变量名 | 描述 | 必需 |
|---|---|---|
| `HF_TOKEN` | HuggingFace 写入令牌 | 是 |
## 部署检查清单
### 生产部署前验证
- [ ] Node.js 版本 >= 20
- [ ] 所有依赖已安装 (`npm ci`)
- [ ] 环境变量已正确配置
- [ ] Cloudflare KV 命名空间 ID 已更新
- [ ] 秘密变量已通过 `wrangler secret put` 设置
- [ ] Dockerfile 构建成功
- [ ] 本地测试通过 (`npm run test`)
### 安全检查项
- [ ] `ADMIN_SECRET` 使用强随机字符串
- [ ] OAuth 客户端密钥已安全存储
- [ ] Binance API 密钥限制 IP（如适用）
- [ ] CORS 配置适合目标域名
- [ ] WebAuthn RP_ID 与服务域名匹配
## 常见部署问题
### 问题：wrangler deploy 失败
**症状**：部署时报错 `Error: Not logged in`
**解决方案**：
```bash
# 重新登录 Cloudflare
npx wrangler login
# 或手动设置 API token
npx wrangler auth list
```
### 问题：KV 命名空间绑定失败
**症状**：`KV binding "VAULT_KV" not found`
**解决方案**：
```bash
# 确认命名空间已创建
npx wrangler kv:namespace list
# 更新 wrangler.toml 中的 id
```
### 问题：WebAuthn 注册链接无法访问
**症状**：访问 `/register/:token` 返回 404
**解决方案**：确认 `ORIGIN` 环境变量设置正确，且链接未过期（默认 1 小时）。
## 相关资源
- [MCP 协议文档](https://modelcontextprotocol.io)
- [Cloudflare Workers 文档](https://developers.cloudflare.com/workers/)
- [WebAuthn 规范](https://www.w3.org/TR/webauthn-2/)
- [OAuth 2.0 RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749)
## 参见
- [设计系统文档](./design-system/README.md) - 前端资产部署
- [分类器技术文档](./orbital-classifier.md) - 模型部署细节
- [Helio Mirror 文档](./helio-mirror/README.md) - 科学数据同步
---
## 运维手册
### 相关页面
相关主题：[部署指南](#deployment), [数据流与反馈机制](#data-flow), [版本与元数据管理](#metadata-management)
相关源码文件
以下源码文件用于生成本页说明：
- [OPERATIONS.md](https://github.com/LuuOW/meridian-mcp/blob/main/OPERATIONS.md)
- [MONOREPO.md](https://github.com/LuuOW/meridian-mcp/blob/main/MONOREPO.md)
- [scripts/audit.mjs](https://github.com/LuuOW/meridian-mcp/blob/main/scripts/audit.mjs)
- [scripts/simulate-ci-methods.mjs](https://github.com/LuuOW/meridian-mcp/blob/main/scripts/simulate-ci-methods.mjs)
- [data/sim-reports/README.md](https://github.com/LuuOW/meridian-mcp/blob/main/data/sim-reports/README.md)
- [.github/workflows/sim-orbital.yml](https://github.com/LuuOW/meridian-mcp/blob/main/.github/workflows/sim-orbital.yml)
- [finance-mcp/README.md](https://github.com/LuuOW/meridian-mcp/blob/main/finance-mcp/README.md)
# 运维手册
本文档为 Meridian MCP 项目提供全面的运维指南，涵盖开发环境配置、持续集成流程、部署流程、监控机制及常见故障排除方法。本手册面向需要部署、维护和调试该项目的技术运维人员及开发团队成员。
## 1. 项目架构概览
Meridian MCP 是一个基于 Model Context Protocol（MCP）的动态任务路由系统，采用轨道力学（orbital mechanics）隐喻来对候选任务进行分类和排序。项目采用 monorepo 结构，包含多个功能模块和应用表面。
```mermaid
graph TD
subgraph "核心模块"
MCP["mcp/ — MCP 服务器实现"]
CLASSIFIER["orbital classifier — 轨道分类器"]
LLM["LLM 候选生成 — Llama-3.3-70B"]
end
subgraph "应用表面"
LANDING["landing/ — 营销页面"]
MINIAPP["miniapp/ — 核心演示应用"]
HELIX["helix/ — 蛋白质推荐系统"]
LENS["lens/ — 视觉实验室"]
PHOTON["photon-route/ — 量子路由文档"]
end
subgraph "设计系统"
TOKENS["design-system/ — 视觉语言"]
UIKITS["ui_kits/ — 各表面组件库"]
end
subgraph "辅助服务"
FINANCE["finance-mcp/ — 金融保险库"]
HELIO["helio-mirror/ — 太阳物理数据镜像"]
end
MCP --> CLASSIFIER
LLM --> CLASSIFIER
CLASSIFIER --> MINIAPP
MINIAPP --> LANDING
LANDING --> TOKENS
TOKENS --> UIKITS
```
### 1.1 Monorepo 目录结构
资料来源：[MONOREPO.md:1-50]()
```
meridian-mcp/
├── mcp/ # MCP 协议核心实现
│ ├── index.mjs # stdio 传输模式入口
│ └── http.mjs # HTTP/Streamable 传输模式入口
├── landing/ # 营销落地页
├── miniapp/ # 核心任务路由演示应用
├── helix/ # 治疗性蛋白质推荐系统
├── lens/ # 视觉实验室 UI
├── photon-route/ # 量子路由文档与演示
├── finance-mcp/ # 金融数据 MCP 服务
├── helio-mirror/ # 太阳物理数据镜像
├── design-system/ # 设计系统与令牌
│ ├── tokens.css # CSS 自定义属性
│ ├── preview/ # 49 个独立预览页面
│ └── ui_kits/ # 各表面组件库
├── scripts/ # 运维脚本集合
├── data/
│ └── sim-reports/ # 模拟运行报告
└── .github/workflows/ # CI/CD 工作流
```
## 2. 环境配置与依赖
### 2.1 系统要求
项目对运行环境有明确的要求规范，确保所有组件正常工作需要满足以下条件。
| 组件 | 最低版本 | 推荐版本 | 说明 |
|------|---------|---------|------|
| Node.js | 20.x | 20.x LTS | 项目明确声明 `engines.node: ">=20"` |
| npm | 9.x | 10.x+ | 用于包管理 |
| Git | 2.40+ | 最新稳定版 | 用于版本控制 |
资料来源：[package.json:18]()
### 2.2 环境变量配置
项目运行时需要配置多个环境变量，这些变量控制 LLM 调用、传输协议、安全认证等核心功能。
| 环境变量 | 默认值 | 必需 | 用途 |
|---------|-------|-----|------|
| `MERIDIAN_GITHUB_TOKEN` | `GITHUB_TOKEN` | 是 | GitHub PAT，用于调用 GitHub Models API，需要 `Models: read` 权限范围 |
| `GITHUB_TOKEN` | — | 条件 | 当 `MERIDIAN_GITHUB_TOKEN` 未设置时的后备选项 |
| `MERIDIAN_MODEL` | `meta/llama-3.3-70b-instruct` | 否 | 指定 GitHub Models 中的聊天模型 |
| `MERIDIAN_MODELS_ENDPOINT` | `https://models.github.ai/inference/chat/completions` | 否 | 可覆盖用于自托管网关 |
| `MERIDIAN_CANDIDATES` | `5` | 否 | LLM 每次调用生成的候选数量 |
资料来源：[README.md:45-52]()
### 2.3 核心依赖
项目依赖 `@modelcontextprotocol/sdk` 实现 MCP 协议通信，开发依赖包含 Playwright 用于 UI 测试。
| 依赖类型 | 包名 | 版本 | 用途 |
|---------|-----|------|------|
| 生产依赖 | `@modelcontextprotocol/sdk` | `^1.0.0` | MCP 协议 SDK |
| 开发依赖 | `@playwright/test` | `^1.60.0` | UI 自动化测试框架 |
资料来源：[package.json:8-10]()
## 3. MCP 服务部署
### 3.1 Stdio 传输模式
Stdio 模式适用于本地开发、直接进程调用以及作为其他 MCP 客户端的集成后端。
```bash
# 安装依赖
npm install
# 启动 stdio 服务器
npm run stdio
# 或直接运行
node mcp/index.mjs
```
Stdio 模式通过标准输入输出进行 JSON-RPC 通信，适用于 Claude Desktop、Cursor、Windsurf 等支持 stdio MCP 的客户端。服务接收任务请求后，调用 GitHub Models 生成候选路由项。
资料来源：[README.md:1-30]()
### 3.2 HTTP/Streamable 传输模式
HTTP 模式适用于需要远程访问、跨网络调用或作为微服务架构的一部分。服务默认绑定 `0.0.0.0:3100`，支持 OAuth 2.0 + PKCE 认证流程。
```bash
# 启动 HTTP 服务器
npm run http
# 或直接运行
node mcp/http.mjs
```
HTTP 端点提供标准 OAuth 2.0 授权码流程，客户端需要先完成授权获取访问令牌，然后使用 Bearer Token 调用 `/mcp` 端点。
```mermaid
sequenceDiagram
participant C as 客户端
participant S as MCP HTTP Server
C->>S: GET /authorize?client_id=xxx&redirect_uri=xxx
S-->>C: 授权页面
C->>S: 用户完成认证
S->>C: 302 重定向到 redirect_uri?code=xxx
C->>S: POST /token (code, code_verifier)
S-->>C: {access_token, expires_in}
C->>S: POST /mcp (Authorization: Bearer xxx)
S-->>C: JSON-RPC 响应
```
资料来源：[finance-mcp/README.md:80-95]()
### 3.3 Finance MCP 部署（Cloudflare Workers）
Finance 模块部署在 Cloudflare Workers 平台，使用 Wrangler 进行配置和管理。
```bash
# 1. 安装依赖
npm install
# 2. 创建 KV 命名空间
npx wrangler kv namespace create VAULT_KV
npx wrangler kv namespace create VAULT_KV --preview
# 3. 将返回的两个命名空间 ID 粘贴到 wrangler.toml
# 4. 配置公开源和 RP_ID
# 编辑 wrangler.toml [vars] 部分
# 5. 设置密钥
npx wrangler secret put ADMIN_SECRET # 管理密钥
npx wrangler secret put USER_ID # 用户标识
npx wrangler secret put OAUTH_CLIENT_ID # OAuth 客户端 ID
```
资料来源：[finance-mcp/README.md:95-110]()
## 4. 持续集成与模拟测试
### 4.1 模拟测试工作流
项目维护三个自动化模拟测试工作流，定期验证核心功能的正确性。所有模拟报告存储在 `data/sim-reports/` 目录中。
| 工作流文件 | 触发频率 | 执行时间 | 报告模式 |
|-----------|---------|---------|---------|
| `sim-orbital.yml` | 每周二、五 06:11 UTC | ~25 分钟 | `orbital-YYYY-MM-DD.txt` |
| `sim-helix.yml` | 每周三 08:17 UTC | ~25 分钟 | `helix-YYYY-MM-DD.txt` |
| `sim-photon.yml` | 手动触发 | 可变 | `photon-YYYY-MM-DD-*.json` |
资料来源：[data/sim-reports/README.md:1-15]()
### 4.2 Orbital 模拟测试
Orbital 模拟测试验证轨道分类器的核心逻辑，测试用例覆盖行星（planet）、卫星（moon）、特洛伊（trojan）、小行星（asteroid）、彗星（comet）和不规则（irregular）六种分类。
```mermaid
graph LR
A[输入任务] --> B[LLM 生成候选]
B --> C[轨道特征提取]
C --> D[分类器评分]
D --> E{argmax 分类}
E -->|mass/scope/independence| F[planet]
E -->|parent + independence| G[moon]
E -->|dep_ratio + fragmentation| H[asteroid]
E -->|其他特征组合| I[trojan/comet/irregular]
F --> J[验证报告]
G --> J
H --> J
I --> J
```
模拟报告包含每次运行的完整标准输出，用于检测功能回归。运维人员应定期检查最新两份报告以识别漂移，例如 `classOf` 变更后 recall@1 下降，或语料库扩展后 nDCG@5 异常。
资料来源：[scripts/simulate-ci-methods.mjs:1-100]()
### 4.3 本地运行模拟
所有模拟测试支持本地运行，便于开发人员在提交前验证更改。
```bash
# 查看 OPERATIONS.md 获取详细说明
# 触发 orbital 模拟
npm run test
# 或直接运行测试脚本
node --test tests/*.test.mjs
# 触发 UI 测试（需要 Playwright）
npm run test:ui
```
资料来源：[package.json:22-24]()
## 5. Helio Mirror 太阳物理数据
### 5.1 数据源配置
Helio Mirror 模块从多个官方天文数据源定期拉取太阳物理数据。
| 数据源 | 覆盖范围 | 说明 |
|-------|---------|------|
| PSP（帕克太阳探测器） | FIELDS/radial-1min + SWEAP/SPC L3 离子数据 | 太阳风原位测量 |
| JWST | `obs_collection=JWST`，目标为 Mars/Jupiter/Saturn | 近红外光谱数据 |
| 星历数据 | JPL Horizons 日心坐标，1 小时间隔 | PSP、地球及 JWST 目标天体 |
资料来源：[helio-mirror/README.md:1-30]()
### 5.2 工作流触发
```bash
# 通过 GitHub Actions UI 触发
# Actions → helio-mirror-pull → Run workflow → 选择 perihelion
# 或使用 gh CLI
gh workflow run helio-mirror-pull.yml \
-R LuuOW/meridian-mcp \
-f perihelion=E20
```
**必需 GitHub 密钥**：`HF_TOKEN` — 需要写权限的 Hugging Face 访问令牌。
资料来源：[helio-mirror/README.md:35-45]()
## 6. 设计系统部署
### 6.1 运行时 CSS 注入
设计令牌（Design Tokens）已在所有在线表面上运行时注入，无需额外引入样式表即可使用。
| 表面 | CSS 文件 | 已注入状态 |
|-----|---------|-----------|
| `ask-meridian.uk/` | `landing/style.css` | 完整注入 |
| `ask-meridian.uk/docs` | `landing/docs/style.css` | 完整注入 |
| `ask-meridian.uk/miniapp` | `miniapp/miniapp.css` | 完整注入 |
| `meridian.ask-meridian.uk/helix` | `helix/helix.css` | 完整注入 |
| `meridian.ask-meridian.uk/lens` | `lens/index.html` | 部分注入（暖橙强调色保留） |
| `photon.ask-meridian.uk` | `photon-route/pages/index.html` | 部分注入（青色/靛蓝方案保留） |
资料来源：[design-system/README.md:1-30]()
### 6.2 添加新表面流程
当项目扩展到新的前端表面时，应遵循以下工作流程确保设计一致性。
```mermaid
flowchart TD
A[新表面开发] --> B{最接近的 ui_kits 是？}
B -->|landing| C[复制 landing UI kit]
B -->|miniapp| D[复制 miniapp UI kit]
B -->|helix| E[复制 helix UI kit]
C --> F[复制 tokens.css 到新表面 CSS]
D --> F
E --> F
F --> G[优先使用命名令牌]
G --> H{需要新令牌?}
H -->|是| I[在 tokens.css 中定义]
H -->|否| J[开发完成]
I --> K[同步到所有 live 表面]
K --> J
```
**命名令牌示例**：`var(--shadow-card-hover)`、`var(--accent)`、`var(--grad-hero)`。
资料来源：[design-system/README.md:30-45]()
## 7. 审计与代码质量
### 7.1 审计脚本
项目提供审计脚本用于检查代码质量、安全漏洞和依赖健康。
```bash
# 运行审计
node scripts/audit.mjs
```
审计脚本检查项包括但不限于：依赖版本安全漏洞、未使用的依赖、代码风格一致性、文档完整性等。
资料来源：[scripts/audit.mjs:1-50]()
### 7.2 CI 模拟方法
`simulate-ci-methods.mjs` 脚本模拟 CI 环境中的各种测试场景，确保本地开发与 CI 环境行为一致。
```bash
# 模拟完整 CI 流程
node scripts/simulate-ci-methods.mjs
```
此脚本对调试环境配置问题和理解 CI 工作流逻辑特别有用。
资料来源：[scripts/simulate-ci-methods.mjs:1-100]()
## 8. 常见问题与故障排除
### 8.1 元数据不一致问题
**问题描述**：Issue #907 指出包版本（3.1.0）、特征向量维度（25）和规范 URL 在 README.md、package.json 和 landing/docs/index.html 之间重复，存在不一致风险。
**建议措施**：
1. 在 `package.json` 中维护单一真相源（Single Source of Truth）
2. 配置 pre-commit 钩子在提交前验证元数据一致性
3. 添加 CI 检查步骤，确保发布前所有文件同步
| 文件 | 当前版本 | 特征维度 | 状态 |
|-----|---------|---------|------|
| `package.json` | 3.2.0 | 25 | 主版本 |
| `README.md` | 需同步 | 需同步 | 待更新 |
| `landing/docs/index.html` | 需同步 | 需同步 | 待更新 |
资料来源：[community_context: #907]()
### 8.2 GitHub Token 缺失
**症状**：`MERIDIAN_GITHUB_TOKEN` 或 `GITHUB_TOKEN` 未设置时，MCP 服务无法生成候选路由。
**解决方案**：
```bash
# 设置环境变量
export MERIDIAN_GITHUB_TOKEN="ghp_xxxxxxxxxxxx"
# 或在 .env 文件中配置
echo "MERIDIAN_GITHUB_TOKEN=ghp_xxxxxxxxxxxx" > .env
```
确保令牌具有 `Models: read` 权限范围，可在 GitHub Settings → Developer settings → Personal access tokens 中配置。
资料来源：[README.md:45-48]()
### 8.3 模拟测试失败
**症状**：本地 `npm run test` 或 CI 工作流报告失败。
**排查步骤**：
1. 检查最新两份模拟报告：`data/sim-reports/`
2. 对比 recall@1 和 nDCG@5 指标
3. 如果在 `classOf` 修改后出现下降，检查分类器评分规则
4. 如果在语料库扩展后出现异常，检查特征向量计算
```bash
# 查看最新 orbital 模拟报告
ls -lt data/sim-reports/ | head -5
cat data/sim-reports/orbital-$(date +%Y-%m-%d).txt
```
资料来源：[data/sim-reports/README.md:15-20]()
### 8.4 Cloudflare 部署失败
**症状**：`wrangler deploy` 失败或 KV 命名空间错误。
**排查步骤**：
1. 验证 `wrangler.toml` 中的 KV 命名空间 ID
2. 确保 `npx wrangler kv namespace create VAULT_KV` 执行成功
3. 检查所有必需密钥是否已设置：`npx wrangler secret list`
```bash
# 验证 KV 命名空间
npx wrangler kv:namespace list
# 验证密钥
npx wrangler secret list
```
资料来源：[finance-mcp/README.md:95-105]()
## 9. 发布流程
### 9.1 版本管理
项目遵循语义化版本（Semantic Versioning），主版本号在 `package.json` 中维护。
```json
{
"name": "meridian-orbital",
"version": "3.2.0",
"description": "Self-contained MCP — orbital task router..."
}
```
### 9.2 发布检查清单
| 步骤 | 操作 | 验证 |
|-----|------|------|
| 1 | 更新 `package.json` 版本号 | `npm run test` 通过 |
| 2 | 更新 `README.md` 中的版本引用 | 检查所有版本提及 |
| 3 | 更新 `landing/docs/index.html` 中的元数据 | HTML 验证通过 |
| 4 | 运行完整模拟测试 | `npm run test` && `npm run test:ui` |
| 5 | 提交并创建 Git tag | `git tag v3.x.x` |
| 6 | 触发 GitHub Actions 发布工作流 | 检查 Actions 日志 |
资料来源：[OPERATIONS.md:1-50]()
## 10. 参考链接
| 资源 | 链接 | 说明 |
|-----|------|------|
| GitHub 仓库 | https://github.com/LuuOW/meridian-mcp | 官方源码仓库 |
| 项目官网 | https://ask-meridian.uk | 产品落地页 |
| MCP 协议文档 | https://modelcontextprotocol.io | MCP 规范 |
| GitHub Models | https://github.com/marketplace/models | LLM 模型市场 |
| Cloudflare Workers | https://developers.cloudflare.com/workers | Finance MCP 部署平台 |
---
*本文档最后更新于 2026-05-14，版本 3.2.0 发布后。*
---
## 扩展与定制开发
### 相关页面
相关主题：[项目概述](#overview), [系统架构](#architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [skills/api/SKILL.md](https://github.com/LuuOW/meridian-mcp/blob/main/skills/api/SKILL.md)
- [skills/agent-loop/SKILL.md](https://github.com/LuuOW/meridian-mcp/blob/main/skills/agent-loop/SKILL.md)
- [example-skills/hello-world/SKILL.md](https://github.com/LuuOW/meridian-mcp/blob/main/example-skills/hello-world/SKILL.md)
- [scripts/new-skill.mjs](https://github.com/LuuOW/meridian-mcp/blob/main/scripts/new-skill.mjs)
- [design-system/README.md](https://github.com/LuuOW/meridian-mcp/blob/main/design-system/README.md)
- [design-system/tokens.css](https://github.com/LuuOW/meridian-mcp/blob/main/design-system/tokens.css)
- [photon-route/src/photon_route/corpus.py](https://github.com/LuuOW/meridian-mcp/blob/main/photon-route/src/photon_route/corpus.py)
- [finance-mcp/src/index.ts](https://github.com/LuuOW/meridian-mcp/blob/main/finance-mcp/src/index.ts)
# 扩展与定制开发
Meridian-MCP 是一个模块化的任务路由系统，支持通过多种方式进行扩展和定制开发。本页面详细介绍如何基于现有架构扩展功能，包括自定义 Skills、UI 组件定制、API 扩展以及与其他系统的集成模式。
---
## 1. 系统架构概览
Meridian-MCP 采用分层架构设计，核心组件包括轨道分类器（Orbital Classifier）、任务路由引擎和可选的 UI 界面层。
```mermaid
graph TD
A[用户请求] --> B[MCP 接口层
stdio / HTTP]
B --> C[任务路由引擎
route_task]
C --> D[LLM 候选生成
Llama-3.3-70B]
D --> E[轨道分类器
25维特征向量]
E --> F[候选排名与输出]
G[Skills 框架] --> H[API 技能]
G --> I[Agent-Loop 技能]
G --> J[自定义技能]
K[设计系统] --> L[UI Kits]
K --> M[Design Tokens]
N[扩展模块] --> O[Finance MCP]
N --> P[Helio Mirror]
N --> Q[Photon Route]
```
**核心模块说明：**
| 模块 | 路径 | 功能 |
|------|------|------|
| MCP 核心 | `mcp/index.mjs`, `mcp/http.mjs` | 任务路由引擎，支持 stdio 和 HTTP 传输 |
| Skills 框架 | `skills/` | 可插拔技能系统 |
| 设计系统 | `design-system/` | 统一的视觉语言和 UI 组件 |
| 扩展模块 | `finance-mcp/`, `helio-mirror/`, `photon-route/` | 垂直领域的扩展实现 |
资料来源：[README.md:1-50](https://github.com/LuuOW/meridian-mcp/blob/main/README.md)
---
## 2. Skills 框架
### 2.1 Skills 概述
Skills 是 Meridian-MCP 的核心扩展机制，每个 Skill 是一个独立的功能单元，包含元数据定义和实现逻辑。Skills 使用 Markdown 格式的 `SKILL.md` 文件作为入口点。
```mermaid
graph LR
A[SKILL.md
元数据] --> B[技能加载器]
B --> C[技能执行器]
C --> D[返回结果]
E[关联文件] --> B
```
### 2.2 SKILL.md 结构
每个 Skill 必须包含 YAML frontmatter 元数据块，定义技能的基本属性：
```yaml
---
name: api
description: FastAPI + async/sync HTTP client patterns...
keywords: ["api", "fastapi", "http", "jwt", ...]
orb_class: planet
---
# api
技能描述内容...
```
**必需字段：**
| 字段 | 类型 | 说明 | 示例 |
|------|------|------|------|
| `name` | string | 技能唯一标识符 | `api`, `agent-loop` |
| `description` | string | 简短的功能描述 | FastAPI patterns... |
| `keywords` | string[] | 搜索和分类标签 | `["api", "fastapi"]` |
| `orb_class` | string | 轨道分类（planet/moon/trojan/asteroid/comet/irregular） | `planet` |
资料来源：[skills/api/SKILL.md:1-12](https://github.com/LuuOW/meridian-mcp/blob/main/skills/api/SKILL.md)
### 2.3 创建自定义 Skill
使用项目提供的脚手架工具可以快速创建新的 Skill：
```bash
# 使用 Node.js 脚本生成新 Skill
node scripts/new-skill.mjs [--dir ]
```
脚本会生成标准化的目录结构和文件模板，包括：
- `SKILL.md` - 技能定义文件
- 相关的示例代码文件
- 测试文件结构
**生成目录结构示例：**
```
example-skills/hello-world/
├── SKILL.md
├── src/
│ └── index.ts
├── tests/
│ └── hello-world.test.ts
└── README.md
```
资料来源：[scripts/new-skill.mjs](https://github.com/LuuOW/meridian-mcp/blob/main/scripts/new-skill.mjs)
### 2.4 内置 Skills 示例
#### API 技能
`skills/api/SKILL.md` 提供了 FastAPI + 异步/同步 HTTP 客户端模式的最佳实践：
```python
# api/main.py
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
@asynccontextmanager
async def lifespan(app: FastAPI):
await db.connect()
yield
await db.disconnect()
app = FastAPI(lifespan=lifespan)
app.add_middleware(
CORSMiddleware,
allow_origins=["http://localhost:3000"],
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
```
**支持的功能模式：**
| 模式 | 说明 |
|------|------|
| JWT 认证 | 多提供商路由认证 |
| Pydantic 模型 | 类型安全的请求/响应定义 |
| 背景任务 | 异步任务队列处理 |
| 多提供商路由 | 灵活的 API 网关设计 |
资料来源：[skills/api/SKILL.md:15-45](https://github.com/LuuOW/meridian-mcp/blob/main/skills/api/SKILL.md)
#### Agent-Loop 技能
`skills/agent-loop/SKILL.md` 定义了 Agent 循环执行的核心模式，支持多步骤推理和工具调用链。
---
## 3. 设计系统扩展
### 3.1 设计系统架构
Meridian-MCP 的设计系统采用 CSS 自定义属性（CSS Custom Properties）作为核心，提供跨平台的视觉一致性。
```mermaid
graph TD
A[Design Tokens
tokens.css] --> B[运行时 CSS]
A --> C[预览页面
preview/]
A --> D[UI Kits
ui_kits/]
B --> E[landing
ask-meridian.uk/]
B --> F[miniapp
ask-meridian.uk/miniapp]
B --> G[helix
meridian.ask-meridian.uk/helix]
B --> H[lens
meridian.ask-meridian.uk/lens]
B --> I[photon-route
photon.ask-meridian.uk]
```
资料来源：[design-system/README.md:1-30](https://github.com/LuuOW/meridian-mcp/blob/main/design-system/README.md)
### 3.2 CSS Token 引用
设计系统导出的核心 CSS 变量：
```css
/* 颜色变量 */
--bg-page /* 页面背景（三层径向渐变叠加） */
--accent /* 主强调色 #a78bfa 霓虹紫 */
--grad-hero /* 英雄区渐变（紫→青→薄荷） */
/* 阴影变量 */
--shadow-card /* 卡片阴影 */
--shadow-card-hover /* 悬停阴影 */
/* 类型类 */
.t-display /* 显示级标题 */
.t-h1 /* 一级标题 */
.t-eyebrow /* 眉题文字 */
.t-grad /* 渐变文字效果 */
```
资料来源：[design-system/tokens.css](https://github.com/LuuOW/meridian-mcp/blob/main/design-system/tokens.css)
### 3.3 创建新 UI Kit
扩展新的用户界面时，建议按以下工作流程操作：
1. **选择基础 Kit** - 从 `ui_kits/` 目录选择最接近的现有 Kit 作为起点
2. **复制 tokens.css** - 将设计令牌复制到新界面的 CSS 文件中
3. **扩展组件** - 基于 `preview/` 中的原语组件构建新组件
| UI Kit | 目标界面 | 特点 |
|--------|----------|------|
| `landing/` | 营销主页 | Hero、FleetGrid、StatsStrip |
| `miniapp/` | 小程序界面 | AskCard、ResultsList |
| `helix/` | 蛋白质推荐 | 星系统卡片、轨道动画 |
| `lens/` | 视觉实验室 | 单页索引 |
| `photon-router/` | 路由文档 | 文档和演示 |
资料来源：[design-system/ui_kits/landing/README.md](https://github.com/LuuOW/meridian-mcp/blob/main/design-system/ui_kits/landing/README.md)
### 3.4 动画系统
设计系统包含三个签名动画：
| 动画名称 | 持续时间 | 用途 |
|----------|----------|------|
| `neonRotate` | 8-14s | 卡片后方锥形旋转 |
| `liveDotPing` | 1.6s | 实时状态指示灯 |
| `gradShift` | 8s | 英雄区渐变扫描 |
```css
/* 使用示例 */
.classifier-result {
animation: neonRotate 12s linear infinite;
}
```
---
## 4. API 扩展模式
### 4.1 文档模型扩展
Photon-Route 模块展示了如何扩展文档处理能力：
```python
from dataclasses import dataclass, field
from typing import Any
@dataclass
class Document:
text: str
meta: dict[str, Any] = field(default_factory=dict)
```
**扩展步骤：**
1. 定义数据类模型
2. 实现 `load_fixture()` 工厂方法
3. 集成到候选生成管道
资料来源：[photon-route/src/photon_route/corpus.py:1-30](https://github.com/LuuOW/meridian-mcp/blob/main/photon-route/src/photon_route/corpus.py)
### 4.2 OAuth 2.0 集成
Finance-MCP 演示了完整的 OAuth 2.1 + PKCE 实现：
| 端点 | 方法 | 功能 |
|------|------|------|
| `/authorize` | GET | OAuth 授权起始 |
| `/login/options` | POST | WebAuthn 认证选项 |
| `/login/verify` | POST | WebAuthn 验证 |
| `/authorize/complete` | GET | 颁发 OAuth 代码 |
| `/token` | POST | 代码兑换 Bearer 令牌 |
**响应头示例：**
```typescript
// OAuth 2.0 受保护资源元数据 (RFC 9728)
{
resource: `${env.ORIGIN}/mcp`,
authorization_servers: [env.ORIGIN],
scopes_supported: ["read"],
bearer_methods_supported: ["header"],
}
```
资料来源：[finance-mcp/src/index.ts:45-60](https://github.com/LuuOW/meridian-mcp/blob/main/finance-mcp/src/index.ts)
### 4.3 WebAuthn 注册流程
```mermaid
sequenceDiagram
用户->>管理端点: POST /admin/create-registration-link
管理端点-->>用户: 返回一次性 URL
用户->>注册页面: GET /register/:token
用户->>注册页面: 点击注册按钮
注册页面->>服务端: POST /register/:token/options
服务端-->>注册页面: WebAuthn options
注册页面->>浏览器: 调用 startRegistration()
浏览器-->>注册页面: 凭证
注册页面->>服务端: POST /register/:token/verify
服务端->>KV存储: 保存 Passkey
服务店-->>注册页面: 销毁一次性链接
```
---
## 5. MCP 传输层扩展
### 5.1 传输模式
Meridian-MCP 支持两种传输模式：
| 模式 | 入口文件 | 适用场景 |
|------|----------|----------|
| Stdio | `mcp/index.mjs` | Claude Desktop / Cursor 本地集成 |
| HTTP/Streamable | `mcp/http.mjs` | Grok / ChatGPT / Claude.ai 云端连接 |
```bash
# Stdio 模式
node mcp/index.mjs
# HTTP 模式
node mcp/http.mjs
```
资料来源：[package.json:10-15](https://github.com/LuuOW/meridian-mcp/blob/main/package.json)
### 5.2 环境变量配置
| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `MERIDIAN_GITHUB_TOKEN` | `GITHUB_TOKEN` | GitHub PAT（必需） |
| `MERIDIAN_MODEL` | `meta/llama-3.3-70b-instruct` | 模型选择 |
| `MERIDIAN_MODELS_ENDPOINT` | `https://models.github.ai/inference/chat/completions` | 自托管网关 |
| `MERIDIAN_CANDIDATES` | `5` | 每请求生成候选数 |
| `MERIDIAN_KV` | `VAULT_KV` | KV 命名空间 |
---
## 6. 分类器扩展
### 6.1 特征向量结构
轨道分类器使用 25 维特征向量：
| 特征类型 | 数量 | 说明 |
|----------|------|------|
| 物理标量 | 9 | mass, scope, independence, cross_domain, fragmentation, drag, dep_ratio, lagrange_potential, coherence_time |
| 类别独热 | 6 | planet/moon/trojan/asteroid/comet/irregular |
| 星系统独热 | 3 | forge/signal/mind |
| Token 命中 | 3 | Token 级匹配特征 |
| 排名特征 | 4 | 排序相关特征 |
资料来源：[README.md:15-25](https://github.com/LuuOW/meridian-mcp/blob/main/README.md)
### 6.2 类别评分规则
```python
score_planet = min(mass, scope, independence)^1.5
score_moon = 2 · max(0, ½ - independence) · 𝟙[parent] · (1 - mass/2)
score_trojan = dep_ratio · 𝟙[parent] · (1 - fragmentation)
score_asteroid = 2 · (1 + tanh(K · w·x)) # 在线学习校准
```
---
## 7. 常见问题与限制
### 7.1 元数据一致性
**已知问题 #907**：当前版本号 (3.2.0)、特征向量维度 (25) 和规范 URL 在 README.md、package.json 和 landing/docs/index.html 中重复定义。建议实现预提交或 CI 检查以确保同步。
### 7.2 冷启动行为
部署初期，分类器权重 `w = 0`，使用纯启发式排名。如需更快收敛，可通过 `/v1/feedback` 端点提供标注样本。
### 7.3 OAuth 路径限制
`/mcp` 端点保持确定性启发式排名以确保可复现性，不受在线学习权重影响。
---
## 8. 相关资源
| 资源 | 说明 |
|------|------|
| [轨道分类器博客](https://ask-meridian.uk/blog/orbital-classifier-online-learning/) | 分类器设计和校准历程 |
| [GitHub Models](https://github.com/marketplace/models) | 候选生成模型源 |
| [设计系统预览](https://ask-meridian.uk/design-system/) | 完整的 Token 和组件预览 |
---
## 9. See Also
- [架构设计](../architecture/) - 系统整体架构详解
- [API 参考](../api-reference/) - MCP 接口完整文档
- [部署指南](../deployment/) - 生产环境部署配置
- [故障排除](../troubleshooting/) - 常见问题排查
---
## 版本与元数据管理
### 相关页面
相关主题：[轨道分类器详解](#orbital-classifier), [数据流与反馈机制](#data-flow)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/LuuOW/meridian-mcp/blob/main/README.md)
- [package.json](https://github.com/LuuOW/meridian-mcp/blob/main/package.json)
- [landing/docs/index.html](https://github.com/LuuOW/meridian-mcp/blob/main/landing/docs/index.html)
- [landing/index.html](https://github.com/LuuOW/meridian-mcp/blob/main/landing/index.html)
- [design-system/README.md](https://github.com/LuuOW/meridian-mcp/blob/main/design-system/README.md)
# 版本与元数据管理
本文档介绍 Meridian MCP 项目中的版本控制策略与元数据管理机制，帮助开发者理解项目标识、版本演进以及元数据一致性维护的最佳实践。
## 概述
Meridian MCP 是一个自包含的 MCP（Model Context Protocol）实现，采用**轨道力学隐喻**进行动态任务路由。项目当前版本为 **v3.2.0**，发布于 2026 年 5 月 14 日，包含轨道分类器校准及两项热路径优化。
核心功能围绕 9 维物理特征向量构建：
- **质量（mass）**：对数缩放的候选体长度 × 关键词计数
- **范围（scope）**：作用域度量
- **独立性（independence）**：独立性评分
- **跨域亲和度（cross_domain）**：三个恒星系统间的令牌域熵
- **碎片化（fragmentation）**：碎片化程度
- **阻力（drag）**：阻力系数
- **依赖比（dep_ratio）**：最大兄弟 Jaccard 相似度
- **拉格朗日势（lagrange_potential）**：拉格朗日点势能
- **相干时间（coherence_time）**：基于 g⁽¹⁾ 风格的候选体令牌流自相关
资料来源：[README.md](https://github.com/LuuOW/meridian-mcp/blob/main/README.md)
## 版本体系结构
### 语义化版本规范
Meridian MCP 采用语义化版本（SemVer）规范，版本格式为 `MAJOR.MINOR.PATCH`：
| 版本层级 | 说明 | 示例 |
|---------|------|------|
| MAJOR | 不兼容的 API 变更 | 3.x.x → 4.0.0 |
| MINOR | 向后兼容的功能新增 | 3.1.0 → 3.2.0 |
| PATCH | 向后兼容的问题修复 | 3.2.0 → 3.2.1 |
当前主版本为 **v3**，表示项目已稳定运行并具备完整的功能集。
资料来源：[package.json](https://github.com/LuuOW/meridian-mcp/blob/main/package.json)
### 版本演进历史
```mermaid
timeline
title Meridian MCP 版本演进
2026-05-14 : v3.2.0 发布
2026-05-14 : 轨道分类器校准
2026-05-14 : 热路径优化 × 2
此前 : v3.1.0 发布
v3.1.0 : 新增 coherence_time 特征
v3.1.0 : 特征向量维度: 25 维
```
## 元数据一致性现状
### 当前元数据分布
Meridian MCP 的核心元数据分散在多个文件中，这种分布模式虽然便于各模块独立维护，但也带来了**一致性维护的挑战**。
```mermaid
graph TD
A[元数据需求] --> B[版本号: 3.2.0]
A --> C[特征向量维度: 25]
A --> D[Canonical URLs]
B --> E[README.md]
B --> F[package.json]
B --> G[landing/index.html]
B --> H[landing/docs/index.html]
C --> E
C --> F
C --> G
D --> E
D --> F
D --> G
D --> H
style E fill:#ffcccc
style F fill:#ccffcc
style G fill:#ccccff
style H fill:#ffffcc
```
### 已知问题：#907
**社区议题 #907** 指出当前元数据存在以下问题：
| 元数据类型 | 位置 | 当前状态 |
|-----------|------|---------|
| 包版本号 (3.1.0) | README.md, package.json, landing/docs/index.html | 需同步 |
| 特征向量维度 (25) | README.md, landing/index.html | 需同步 |
| Canonical URLs | README.md, landing/index.html | 需同步 |
资料来源：[社区议题 #907](https://github.com/LuuOW/meridian-mcp/issues/907)
### 元数据存储位置详解
#### package.json
```json
{
"name": "meridian-orbital",
"version": "3.2.0",
"description": "Self-contained MCP — orbital task router...",
"mcpName": "io.github.LuuOW/meridian-mcp",
"homepage": "https://ask-meridian.uk",
"repository": {
"type": "git",
"url": "git+https://github.com/LuuOW/meridian-mcp.git"
},
"bugs": {
"url": "https://github.com/LuuOW/meridian-mcp/issues"
}
}
```
`package.json` 是项目的**主元数据源**，包含 npm 包管理所需的所有标准字段。
资料来源：[package.json](https://github.com/LuuOW/meridian-mcp/blob/main/package.json)
#### README.md
README 文档包含项目描述、功能特性和使用说明，其中特征向量维度和版本信息需要与 `package.json` 保持一致。
```markdown
# Meridian MCP
```
资料来源：[README.md](https://github.com/LuuOW/meridian-mcp/blob/main/README.md)
#### Landing Pages
| 文件路径 | 内容类型 | 元数据用途 |
|---------|---------|-----------|
| `landing/index.html` | 营销首页 | 版本展示、特性说明 |
| `landing/docs/index.html` | 文档首页 | 导航、版本徽章 |
资料来源：[landing/index.html](https://github.com/LuuOW/meridian-mcp/blob/main/landing/index.html)，[landing/docs/index.html](https://github.com/LuuOW/meridian-mcp/blob/main/landing/docs/index.html)
## 推荐实践
### 单点真相原则
建议采用 **package.json 作为唯一真相来源**，其他文件通过自动化手段同步：
```mermaid
graph LR
A[package.json] -->|CI/CD 同步| B[README.md]
A -->|CI/CD 同步| C[landing/index.html]
A -->|CI/CD 同步| D[landing/docs/index.html]
style A fill:#90EE90
```
### 预提交钩子建议
为确保元数据一致性，建议实现预提交或 CI 检查：
```javascript
// pre-commit hook 示例 (伪代码)
const packageVersion = readJson('package.json').version
const readmeVersion = extractVersion('README.md')
if (packageVersion !== readmeVersion) {
console.error('❌ Version mismatch detected!')
process.exit(1)
}
```
### 设计系统令牌
设计系统的 CSS 令牌通过 `design-system/tokens.css` 集中管理，确保视觉一致性：
> 完整令牌集 + 语义类型类现已注入每个活动表面的运行时 CSS
资料来源：[design-system/README.md](https://github.com/LuuOW/meridian-mcp/blob/main/design-system/README.md)
## 发布流程
### v3.2.0 发布要点
**发布日期**：2026-05-14
| 改进类型 | 描述 | 影响 |
|---------|------|------|
| 轨道分类器校准 | 将 moon/comet/irregular 移出死区，减少长度偏差 | 分类精度提升 |
| 热路径优化 × 2 | 两项性能优化 | 响应速度提升 |
| API 变更 | 无 | 向后兼容 |
> 无需迁移，语义保持一致，分类数值略有改善。
### 发布检查清单
| 检查项 | 状态 | 说明 |
|-------|------|------|
| 版本号更新 | 必需 | 更新 package.json 中的 version 字段 |
| CHANGELOG.md | 必需 | 记录本次变更 |
| 功能测试 | 必需 | 运行 `npm test` |
| UI 测试 | 推荐 | 运行 `npm run test:ui` |
| 元数据一致性 | 必需 | 验证跨文件版本号一致 |
## 相关配置文件
### 引擎要求
```json
{
"engines": {
"node": ">=20"
}
}
```
### 依赖管理
| 依赖包 | 版本要求 | 用途 |
|-------|---------|------|
| @modelcontextprotocol/sdk | ^1.0.0 | MCP 协议实现 |
资料来源：[package.json](https://github.com/LuuOW/meridian-mcp/blob/main/package.json)
## 参见
- [README 文档](https://github.com/LuuOW/meridian-mcp/blob/main/README.md) — 项目完整说明
- [package.json](https://github.com/LuuOW/meridian-mcp/blob/main/package.json) — npm 包配置
- [CHANGELOG.md](https://github.com/LuuOW/meridian-mcp/blob/main/CHANGELOG.md) — 版本变更历史
- [设计系统文档](../design-system/README.md) — 视觉令牌管理
- [社区议题 #907](https://github.com/LuuOW/meridian-mcp/issues/907) — 元数据一致性改进建议
---
## 前端组件
### 相关页面
相关主题：[系统架构](#architecture), [数据流与反馈机制](#data-flow)
相关源码文件
以下源码文件用于生成本页说明：
- [miniapp/index.html](https://github.com/LuuOW/meridian-mcp/blob/main/miniapp/index.html)
- [miniapp/app.js](https://github.com/LuuOW/meridian-mcp/blob/main/miniapp/app.js)
- [miniapp/miniapp.css](https://github.com/LuuOW/meridian-mcp/blob/main/miniapp/miniapp.css)
- [miniapp/mini-galaxy.js](https://github.com/LuuOW/meridian-mcp/blob/main/miniapp/mini-galaxy.js)
- [lens/index.html](https://github.com/LuuOW/meridian-mcp/blob/main/lens/index.html)
- [lens/lens.css](https://github.com/LuuOW/meridian-mcp/blob/main/lens/lens.css)
- [lens/app.mjs](https://github.com/LuuOW/meridian-mcp/blob/main/lens/app.mjs)
- [helix/index.html](https://github.com/LuuOW/meridian-mcp/blob/main/helix/index.html)
- [helix/helix.css](https://github.com/LuuOW/meridian-mcp/blob/main/helix/helix.css)
- [helix/app.mjs](https://github.com/LuuOW/meridian-mcp/blob/main/helix/app.mjs)
- [landing/index.html](https://github.com/LuuOW/meridian-mcp/blob/main/landing/index.html)
- [landing/style.css](https://github.com/LuuOW/meridian-mcp/blob/main/landing/style.css)
- [design-system/README.md](https://github.com/LuuOW/meridian-mcp/blob/main/design-system/README.md)
- [design-system/tokens.css](https://github.com/LuuOW/meridian-mcp/blob/main/design-system/tokens.css)
- [photon-route/pages/index.html](https://github.com/LuuOW/meridian-mcp/blob/main/photon-route/pages/index.html)
# 前端组件
Meridian MCP 项目包含多个前端应用界面，它们共享统一的设计系统并采用天体力学主题进行可视化呈现。本页详细介绍各个前端应用的组件架构、交互模式和样式规范。
## 概览
Meridian 的前端组件体系由以下几个独立应用组成，每个应用都有其特定的功能定位：
| 应用 | 路径 | 功能描述 |
|------|------|----------|
| **Miniapp** | `ask-meridian.uk/miniapp` | 任务轨道可视化，输入任务查询获取候选路由 |
| **Lens** | `meridian.ask-meridian.uk/lens/` | WebXR 视觉实验室，AR 头显帧处理 |
| **Helix** | `meridian.ask-meridian.uk/helix/` | 治疗性蛋白推荐器，蛋白质结构可视化 |
| **Landing** | `ask-meridian.uk/` | 营销落地页 |
| **Photon-Route** | `photon.ask-meridian.uk` | 量子路由文档与演示 |
所有前端应用共享同一套设计系统，包括 CSS 自定义属性、语义化类型类和动画关键帧。资料来源：[design-system/README.md]()
## 架构概览
```mermaid
graph TB
subgraph 设计系统层
Tokens["tokens.css
设计令牌"]
Keyframes["@keyframes 动画"]
TypeClasses[".t-* 类型类"]
end
subgraph 应用层
Miniapp["Miniapp
任务轨道"]
Lens["Lens
WebXR 视觉"]
Helix["Helix
蛋白推荐"]
Landing["Landing
营销页"]
end
subgraph 后端服务
MCPServer["MCP Server
mcp.ask-meridian.uk"]
GitHubModels["GitHub Models
Llama-3.3-70B"]
end
Tokens --> Miniapp
Tokens --> Lens
Tokens --> Helix
Tokens --> Landing
Miniapp --> MCPServer
Lens --> MCPServer
Helix --> MCPServer
MCPServer --> GitHubModels
```
## 设计系统
### 设计令牌
设计系统采用 CSS 自定义属性（Custom Properties）集中管理所有视觉变量，确保跨应用的一致性。资料来源：[design-system/tokens.css]()
#### 颜色系统
| 令牌 | 默认值 | 用途 |
|------|--------|------|
| `--accent` | `#a78bfa` | 主强调色（霓虹紫） |
| `--bg-page` | 三层叠加渐变 | 页面背景 |
| `--bg-surface` | 深色表面 | 卡片、面板背景 |
| `--shadow-card` | 卡片阴影 | 容器层级感 |
| `--grad-hero` | `linear-gradient` | 标题渐变（紫→青→薄荷） |
#### 天体分类颜色
每个天体分类（Planet/Moon/Trojan 等）都有对应的语义化颜色类：
| 分类 | CSS 类 | 用途 |
|------|--------|------|
| Planet | `.class-planet` | 大型综合性任务 |
| Moon | `.class-moon` | 依赖父级任务的子任务 |
| Trojan | `.class-trojan` | 共享依赖的候选 |
| Asteroid | `.class-asteroid` | 碎片化小任务 |
| Comet | `.class-comet` | 跨领域边缘任务 |
| Irregular | `.class-irregular` | 无法分类的任务 |
资料来源：[design-system/README.md]()
#### 类型系统
| 类名 | 用途 |
|------|------|
| `.t-display` | 主标题 |
| `.t-h1` | 一级标题 |
| `.t-eyebrow` | 标签文字 |
| `.t-grad` | 渐变文字效果 |
| `.t-body` | 正文内容 |
#### 动画关键帧
| 关键帧 | 周期 | 用途 |
|--------|------|------|
| `neonRotate` | 8-14s | 卡片背后的圆锥旋转 |
| `gradShift` | 8s | 英雄区渐变扫动 |
| `liveDotPing` | 1.6s | 实时状态指示点脉动 |
### 使用方式
所有运行时 CSS 文件已包含完整的设计令牌集，无需额外引入样式表：
```html
```
## Miniapp 组件
Miniapp 是 Meridian 的核心演示应用，用户输入任务描述后，系统调用 MCP 服务生成候选路由，并以天体轨道动画进行可视化呈现。资料来源：[miniapp/index.html]()
### 组件结构
```mermaid
graph TD
subgraph Miniapp
Nav["Nav 导航栏"]
AskCard["AskCard 输入卡片"]
MetaBar["MetaBar 元信息栏"]
MiniGalaxy["MiniGalaxy 轨道画布"]
ResultsList["ResultsList 结果列表"]
CandidatePanel["CandidatePanel 候选详情面板"]
end
AskCard -->|提交任务| MiniGalaxy
MiniGalaxy -->|选择候选| ResultsList
ResultsList -->|点击行| CandidatePanel
MetaBar -->|配额/模型| AskCard
```
### 核心组件
#### Nav 导航栏
顶部固定导航栏，包含品牌标识、应用菜单、命令面板触发器和 GitHub 链接。资料来源：[design-system/ui_kits/miniapp/README.md]()
**主要元素：**
- 品牌 Logo + 产品名称
- 应用切换下拉菜单
- Cmd+K 命令面板触发器
- GitHub 仓库链接
- 移动端汉堡菜单
#### AskCard 输入卡片
核心输入组件，带有旋转霓虹环框架。资料来源：[miniapp/miniapp.css]()
| 元素 | 描述 |
|------|------|
| Eyebrow | 顶部标签文字（如 "Task Orbit"） |
| Textarea | 任务描述输入框 |
| Example Chips | 示例任务快捷标签 |
| CTA Button | 主要操作按钮 "Find compatible candidates →" |
| AR Pill | 增强现实状态指示器 |
**样式特点：**
- 旋转霓虹环动画（`neonRotate`）
- 聚焦时边框高亮
- 示例芯片点击填充输入框
#### MiniGalaxy 轨道画布
将候选路由以天体轨道形式进行 3D 可视化的核心组件。资料来源：[miniapp/mini-galaxy.js]()
**功能：**
- Canvas 2D/3D 渲染模式
- 候选天体围绕恒星系统旋转
- 点击天体查看详情
- 轨道位置基于分类得分计算
**关键参数：**
| 参数 | 说明 |
|------|------|
| candidates | 候选数组 |
| canvas | 渲染画布元素 |
| mode | 2D 或 3D 渲染模式 |
| tilt | 轨道平面倾斜角度 |
| zoom | 缩放级别 |
#### ResultsList 结果列表
候选结果列表视图，支持排序和筛选。资料来源：[miniapp/app.js]()
| 字段 | 说明 |
|------|------|
| Rank | 排名徽章 |
| Title | 候选标题 |
| Class Chip | 天体分类标签 |
| Score Badge | 得分指示 |
| 交互 | 点击行展开详情面板 |
#### CandidatePanel 候选详情面板
右侧滑入面板，展示完整候选信息。资料来源：[design-system/ui_kits/miniapp/README.md]()
**内容结构：**
- 天体分类图标
- 标题与元信息
- 得分分解图表
- 决策规则说明
- Markdown 格式的详细描述
- 操作按钮（选择/复制/分享）
### 状态流转
```mermaid
stateDiagram-v2
[*] --> Empty: 页面加载
Empty --> Loading: 输入任务并提交
Loading --> Results: 获取候选结果
Results --> Empty: 清除搜索
Results --> Candidate: 点击候选行
Candidate --> Results: 关闭面板
Loading --> Error: 请求失败
Error --> Empty: 重试或取消
```
### API 调用流程
```mermaid
sequenceDiagram
participant User as 用户
participant App as Miniapp
participant MCP as MCP Server
participant LLM as GitHub Models
User->>App: 输入任务描述
App->>MCP: POST /v1/route
MCP->>LLM: Llama-3.3-70B 生成候选
LLM-->>MCP: N 个候选路由条目
MCP->>MCP: 轨道分类器计算
MCP-->>App: 分类结果 + 得分
App->>App: 渲染轨道动画
App-->>User: 显示结果
```
## Lens 组件
Lens 是 WebXR 视觉实验室应用，接收 AR 头显捕获的画面帧，处理后以天体系统形式呈现视野中的实体。资料来源：[lens/index.html]()
### 组件结构
| 组件 | 功能 |
|------|------|
| VisionCapture | 头显帧捕获与预处理 |
| StarSystem | 天体系统渲染容器 |
| EntityOrbit | 实体轨道动画 |
| HUD | 平视显示器叠加层 |
### 处理流程
```mermaid
graph LR
A[AR 头显帧] --> B[POST /v1/vision]
B --> C[GPT-4o-mini 处理]
C --> D[轨道分类器]
D --> E[3D 天体可视化]
E --> F[锚定在视野中的恒星系统]
```
### 样式特点
Lens 应用保持了特有的深色主题和青/靛蓝配色方案，同时使用了设计系统的基础令牌。资料来源：[lens/lens.css]()
## Helix 组件
Helix 是治疗性蛋白推荐器界面，将推荐结果以恒星系统形式展示，每个蛋白质对应一个独立的星体世界。资料来源：[helix/index.html]()
### 组件结构
| 组件 | 功能 |
|------|------|
| StarSystemCard | 单个蛋白质恒星卡片 |
| ProteinCore | 中心蛋白质恒星（含 PDB 标识） |
| CompoundOrbit | 配体轨道动画 |
| ScorePill | 得分显示药丸 |
| Rationale | 推荐理由说明 |
### 可视化特点
- 垂直滚动宇宙界面
- 每张卡片代表一个推荐蛋白质
- 中心恒星：蛋白质本体
- 轨道上的化合物：真实配体名称（TrkA、p75、NGF-β、EGFR 等）
- 动画 SVG 化合物在虚线轨道上漂移
资料来源：[helix/helix.css]()
### 输入组件
```html
```
## Landing 页面组件
营销落地页组件库，包含完整的销售漏斗组件。资料来源：[landing/index.html]()
### 组件清单
| 组件 | 文件位置 | 功能 |
|------|----------|------|
| Nav | `Nav.jsx` | 顶部导航栏 |
| Hero | `Hero.jsx` | 英雄区（带轨道 SVG 动画） |
| FleetGrid | `FleetGrid.jsx` | 产品属性卡片网格 |
| StatsStrip | `StatsStrip.jsx` | 统计数据横条 |
| FeaturesGrid | `FeaturesGrid.jsx` | 功能特性卡片 |
| HowItWorks | `HowItWorks.jsx` | 三步操作说明 |
| PricingGrid | `PricingGrid.jsx` | 定价表格 |
| CtaFinal | `CtaFinal.jsx` | 最终行动号召 |
| Footer | `Footer.jsx` | 页脚 |
### Hero 组件
英雄区是 Landing 页面的核心视觉元素，包含：
- Eyebrow 标签
- 主标题（渐变文字）
- 副标题说明
- 双 CTA 按钮
- 背景轨道 SVG 动画（SMIL ``）
**交互效果：**
```javascript
// 鼠标移动控制光晕位置
document.addEventListener('mousemove', (e) => {
document.documentElement.style.setProperty('--cursor-x', e.clientX + 'px')
document.documentElement.style.setProperty('--cursor-y', e.clientY + 'px')
})
```
资料来源：[landing/style.css]()
### 特色悬停效果
FeaturesGrid 卡片使用霓虹环悬停效果：
```css
.feature-card:hover {
box-shadow: 0 0 20px var(--accent),
0 0 40px var(--accent),
0 0 60px var(--accent);
}
```
## Photon-Route 组件
光子路由文档与演示界面，基于量子主题的路由系统可视化。资料来源：[photon-route/pages/index.html]()
### 界面结构
- 单页索引布局
- 量子主题配色（青色/靛蓝）
- 文档内容区
- 交互式路由演示
## 样式复用模式
### CSS 变量优先
所有组件应优先使用设计系统中的命名令牌：
```css
/* 推荐 */
.card {
background: var(--bg-surface);
box-shadow: var(--shadow-card);
color: var(--text-primary);
}
/* 避免 */
.card {
background: #1a1a2e;
box-shadow: 0 4px 20px rgba(0, 0, 0, 0.3);
color: #e0e0e0;
}
```
### 组件分层
```mermaid
graph BT
Layer1["tokens.css
层级 1: 设计令牌"]
Layer2["app.css
层级 2: 布局与结构"]
Layer3["components.css
层级 3: 组件样式"]
Layer4["utilities.css
层级 4: 工具类"]
Layer1 --> Layer2
Layer2 --> Layer3
Layer3 --> Layer4
```
### 响应式断点
| 断点 | 宽度 | 典型设备 |
|------|------|----------|
| Mobile | < 640px | 手机竖屏 |
| Tablet | 640-1024px | 平板 |
| Desktop | > 1024px | 桌面显示器 |
## 常见问题与注意事项
### 状态同步
在单页应用状态管理中，注意以下状态转换的正确处理：
1. **加载状态**：显示骨架屏或旋转动画
2. **空状态**：显示友好提示和示例
3. **错误状态**：提供重试选项
4. **结果状态**：确保列表和可视化同步
### 性能考虑
| 场景 | 优化策略 |
|------|----------|
| 大量候选渲染 | 使用虚拟滚动 |
| 3D 动画卡顿 | 降级到 Canvas 2D 模式 |
| 频繁 API 调用 | 实现防抖/节流 |
### 无障碍性
- 所有交互元素需要有适当的 `aria-label`
- 颜色对比度需符合 WCAG 2.1 AA 标准
- 动画需尊重 `prefers-reduced-motion` 媒体查询
## 相关资源
- [设计系统文档](./design-system/README.md)
- [MCP 服务器架构](./mcp-server.md)
- [轨道分类器原理](./orbital-classifier.md)
- [API 端点参考](./api-reference.md)
## 参考链接
- [Miniapp 在线演示](https://ask-meridian.uk/miniapp)
- [Lens WebXR 应用](https://meridian.ask-meridian.uk/lens/)
- [Helix 蛋白推荐器](https://meridian.ask-meridian.uk/helix/)
- [Photon-Route 文档](https://photon.ask-meridian.uk)
---
## MCP 协议集成
### 相关页面
相关主题：[系统架构](#architecture), [部署指南](#deployment)
相关源码文件
以下源码文件用于生成本页说明：
- [mcp/index.mjs](https://github.com/LuuOW/meridian-mcp/blob/main/mcp/index.mjs) — stdio 传输协议入口
- [mcp/http.mjs](https://github.com/LuuOW/meridian-mcp/blob/main/mcp/http.mjs) — HTTP/Streamable 传输协议入口
- [src/server.mjs](https://github.com/LuuOW/meridian-mcp/blob/main/src/server.mjs) — MCP 服务器核心实现
- [src/skills.mjs](https://github.com/LuuOW/meridian-mcp/blob/main/src/skills.mjs) — 路由工具定义
- [package.json](https://github.com/LuuOW/meridian-mcp/blob/main/package.json) — 依赖与元数据
- [README.md](https://github.com/LuuOW/meridian-mcp/blob/main/README.md) — 项目概述与设计文档
# MCP 协议集成
## 概述
Meridian MCP 是一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 的动态任务路由系统，通过轨道力学类比实现领域无关的候选路由功能。该项目同时支持 **stdio 传输** 和 **HTTP/Streamable 传输** 两种协议接入方式，兼容 Grok、ChatGPT、Claude 等主流 AI 助手。
资料来源：[package.json:1-45](https://github.com/LuuOW/meridian-mcp/blob/main/package.json)
## 核心架构
Meridian MCP 采用分层架构，核心组件包括：
```mermaid
graph TD
subgraph "客户端层"
A[AI 助手 / Agent]
B[Web Miniapp]
C[Vision Lab]
end
subgraph "传输层"
D[Stdio Transport]
E[HTTP/Streamable Transport]
end
subgraph "MCP 服务器"
F[server.mjs]
G[skills.mjs
route_task 工具]
end
subgraph "业务逻辑层"
H[轨道分类器
Orbital Classifier]
I[LLM 调用
Llama-3.3-70B]
end
subgraph "外部依赖"
J[GitHub Models API]
K[KV 存储]
end
A --> D
B --> E
C --> E
D --> F
E --> F
F --> G
G --> H
G --> I
I --> J
H --> K
```
资料来源：[README.md:1-30](https://github.com/LuuOW/meridian-mcp/blob/main/README.md)
### 组件职责
| 组件 | 文件 | 职责 |
|------|------|------|
| Stdio 入口 | `mcp/index.mjs` | 通过标准输入/输出与父进程通信 |
| HTTP 入口 | `mcp/http.mjs` | 提供 RESTful API 与 Streamable HTTP 端点 |
| 服务器核心 | `src/server.mjs` | MCP 协议实现、资源管理、工具调用调度 |
| 路由工具 | `src/skills.mjs` | 定义 `route_task` 工具，处理候选生成与排名 |
资料来源：[mcp/index.mjs](https://github.com/LuuOW/meridian-mcp/blob/main/mcp/index.mjs), [mcp/http.mjs](https://github.com/LuuOW/meridian-mcp/blob/main/mcp/http.mjs)
## 传输协议支持
### Stdio 传输
Stdio 传输适用于本地进程通信场景，是 Claude Desktop、Cursor 等工具的标准集成方式。
**入口点配置：**
```json
{
"bin": {
"meridian-mcp": "./mcp/index.mjs"
}
}
```
**使用方式：**
```bash
# 直接运行（用于调试）
node mcp/index.mjs
# 在 MCP 客户端中配置
# 例如 Claude Desktop 的 settings.json:
{
"mcpServers": {
"meridian": {
"command": "node",
"args": ["/path/to/meridian-mcp/mcp/index.mjs"],
"env": {
"MERIDIAN_GITHUB_TOKEN": "your-token"
}
}
}
}
```
资料来源：[package.json:10-14](https://github.com/LuuOW/meridian-mcp/blob/main/package.json)
### HTTP/Streamable 传输
HTTP 传输支持远程部署和跨网络调用，适用于 Web Miniapp、Vision Lab 等前端应用。
**入口点配置：**
```json
{
"bin": {
"meridian-mcp-http": "./mcp/http.mjs"
}
}
```
**运行方式：**
```bash
node mcp/http.mjs
```
**端点结构：**
| 方法 | 路径 | 功能 |
|------|------|------|
| `POST` | `/v1/route` | 路由任务核心端点 |
| `GET` | `/v1/model-info` | 只读模型状态查询 |
| `POST` | `/v1/feedback` | 分类器反馈接收 |
| `POST` | `/v1/vision` | 视觉任务处理（Vision Lab） |
资料来源：[README.md:1-30](https://github.com/LuuOW/meridian-mcp/blob/main/README.md), [mcp/http.mjs](https://github.com/LuuOW/meridian-mcp/blob/main/mcp/http.mjs)
## 工具定义
### route_task 工具
`route_task` 是 Meridian MCP 提供的唯一核心工具，负责接收自然语言任务并返回排序后的候选路由列表。
**输入参数：**
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `task` | `string` | 是 | — | 自然语言任务描述 |
| `limit` | `number` | 否 | 5 | 返回候选数量上限 |
**处理流程：**
```mermaid
graph TD
A["route_task(task, limit)"] --> B["LLM 生成候选
Llama-3.3-70B
GitHub Models"]
B --> C["轨道分类器处理"]
C --> D["提取物理特征
mass, scope, independence
cross_domain, fragmentation..."]
D --> E["计算天体分类
planet | moon | trojan
asteroid | comet | irregular"]
E --> F["在线学习加权
sigmoid gating
v2 权重系统"]
F --> G["返回排序候选"]
style B fill:#e1f5fe
style E fill:#fff3e0
style G fill:#e8f5e9
```
**输出结构：**
```typescript
{
candidates: [
{
id: string,
text: string, // 完整 markdown 正文
classification: {
bodyClass: "planet" | "moon" | "trojan" | "asteroid" | "comet" | "irregular",
starSystem: "forge" | "signal" | "mind",
physics: {
mass: number,
scope: number,
independence: number,
// ... 25 维特征向量
}
},
ranking: {
score: number,
position: number
}
}
],
metadata: {
model: string,
version: string,
processingTime: number
}
}
```
资料来源：[src/skills.mjs](https://github.com/LuuOW/meridian-mcp/blob/main/src/skills.mjs), [README.md:10-35](https://github.com/LuuOW/meridian-mcp/blob/main/README.md)
## 配置选项
### 环境变量
| 变量 | 默认值 | 必填 | 说明 |
|------|--------|------|------|
| `MERIDIAN_GITHUB_TOKEN` | 降级至 `GITHUB_TOKEN` | 是 | GitHub PAT，需 `Models: read` 权限 |
| `MERIDIAN_MODEL` | `meta/llama-3.3-70b-instruct` | 否 | GitHub Models 支持的任意聊天模型 |
| `MERIDIAN_MODELS_ENDPOINT` | `https://models.github.ai/inference/chat/completions` | 否 | 自托管网关地址 |
| `MERIDIAN_CANDIDATES` | `5` | 否 | LLM 每次生成的候选数量 |
| `KV` | — | HTTP 模式 | Cloudflare Workers KV 命名空间 |
| `ORIGIN` | — | HTTP 模式 | 公共源地址 |
| `OAUTH_CLIENT_ID` | — | HTTP 模式 | OAuth 客户端标识 |
| `OAUTH_CLIENT_SECRET` | — | HTTP 模式 | OAuth 客户端密钥 |
资料来源：[package.json:15-25](https://github.com/LuuOW/meridian-mcp/blob/main/package.json), [README.md:40-55](https://github.com/LuuOW/meridian-mcp/blob/main/README.md)
### 分类器参数
| 参数 | 默认值 | 说明 |
|------|--------|------|
| `FEATURE_VERSION` | `v2` | 特征向量版本，升级时重新初始化权重 |
| `K` | — | Sigmoid 门控斜率系数 |
| 特征维度 | **25** | 9 物理标量 + 6 类别 one-hot + 3 星系 one-hot + 3 token-hit + 4 排名特征 |
资料来源：[README.md:1-30](https://github.com/LuuOW/meridian-mcp/blob/main/README.md)
## 认证机制
### Stdio 模式
Stdio 传输不涉及网络认证，依赖进程环境变量传递令牌。
### HTTP 模式 OAuth 2.1 + PKCE
HTTP 端点采用 OAuth 2.1 规范，支持 PKCE（Proof Key for Code Exchange）流程：
```mermaid
sequenceDiagram
participant C as 客户端
participant A as 授权服务器
participant M as MCP 服务器
C->>A: GET /authorize?client_id=xxx&code_challenge=yyy
A-->>C: 返回 Passkey 登录页面
C->>A: 完成 Passkey 验证
A->>C: 302 /authorize/complete?code=zzz
C->>A: POST /token (code, code_verifier)
A-->>C: {access_token, refresh_token}
C->>M: POST /mcp (Authorization: Bearer xxx)
M-->>C: MCP JSON-RPC 响应
```
资料来源：[finance-mcp/README.md](https://github.com/LuuOW/meridian-mcp/blob/main/finance-mcp/README.md)
**OAuth 端点：**
| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/authorize` | OAuth 授权起点 |
| `POST` | `/login/options` | WebAuthn 认证选项 |
| `POST` | `/login/verify` | WebAuthn 验证 |
| `GET` | `/authorize/complete` | 授权完成，发放 code |
| `POST` | `/token` | code 兑换 access_token |
资料来源：[finance-mcp/src/index.ts:1-80](https://github.com/LuuOW/meridian-mcp/blob/main/finance-mcp/src/index.ts)
### Bearer Token 模式
Node.js 二进制调用使用简化 Bearer Token 认证：
```bash
curl -X POST https://mcp.ask-meridian.uk/mcp \
-H "Authorization: Bearer your-token" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"route_task","arguments":{"task":"帮我分析销售数据"}}}'
```
资料来源：[README.md:60-70](https://github.com/LuuOW/meridian-mcp/blob/main/README.md)
## 客户端集成
### Claude Desktop
在 `~/.claude/settings.json` 中添加：
```json
{
"mcpServers": {
"meridian": {
"command": "node",
"args": ["/absolute/path/to/meridian-mcp/mcp/index.mjs"],
"env": {
"MERIDIAN_GITHUB_TOKEN": "ghp_xxxxxxxxxxxx",
"MERIDIAN_CANDIDATES": "5"
}
}
}
}
```
### Cursor
在 Cursor 设置的 MCP Server 配置中添加相同配置。
### Windsurf
使用 MCP 通用配置方式，指向 stdio 入口。
### Web Miniapp
Web 前端通过 HTTP 端点直接调用：
```javascript
const response = await fetch('https://mcp.ask-meridian.uk/v1/route', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
// OAuth Bearer Token 或其他认证
},
body: JSON.stringify({
task: '帮我规划下周的会议安排',
limit: 5
})
});
const { candidates } = await response.json();
```
资料来源：[README.md:70-90](https://github.com/LuuOW/meridian-mcp/blob/main/README.md)
## 版本演进
| 版本 | 日期 | 关键变更 |
|------|------|----------|
| 3.2.0 | 2026-05-14 | 轨道分类器校准，减少长度偏差 |
| 3.1.0 | — | 添加 `coherence_time` 特征（g⁽¹⁾ 自相关），25 维特征向量 |
| 3.0.0 | — | 重构为自包含模式，GitHub Models 直接调用 |
| 2.0.0 | — | 废弃 Cloudflare Workers 后端 |
| 1.0.1 | — | 最后支持已废弃后端的版本 |
| 0.3.x | — | 闭域 Python 评分器 + 88 条语料库 |
资料来源：[README.md:100-120](https://github.com/LuuOW/meridian-mcp/blob/main/README.md)
## 常见问题
### 元数据一致性问题
> **Issue #907**: 当前版本号 (3.1.0)、特征向量维度 (25)、规范 URL 等元数据在 README.md、package.json、landing/docs/index.html 中重复定义，存在不一致风险。
**建议**：使用 CI 检查或 pre-commit hook 验证元数据同步。
资料来源：[社区讨论 #907](https://github.com/LuuOW/meridian-mcp/issues/907)
### 处理时间
典型调用耗时 **5-15 秒**，包含：
- GitHub Models API 调用（Llama-3.3-70B 推理）
- 本地轨道分类器处理
- KV 读写（在线学习权重更新）
资料来源：[README.md:45-50](https://github.com/LuuOW/meridian-mcp/blob/main/README.md)
### 冷启动
分类器权重初始化为 `w = 0`，门控乘数 = 1，此时为纯启发式排名。部署第一天无需任何训练数据即可工作。
资料来源：[README.md:1-30](https://github.com/LuuOW/meridian-mcp/blob/main/README.md)
## 相关资源
| 资源 | 链接 |
|------|------|
| 轨道分类器博客 | [ask-meridian.uk/blog/orbital-classifier-online-learning](https://ask-meridian.uk/blog/orbital-classifier-online-learning/) |
| 在线体验 | [ask-meridian.uk/miniapp](https://ask-meridian.uk/miniapp) |
| Vision Lab | [meridian.ask-meridian.uk/lens](https://meridian.ask-meridian.uk/lens/) |
| 模型状态 | [mcp.ask-meridian.uk/v1/model-info](https://mcp.ask-meridian.uk/v1/model-info) |
## 另请参阅
- [轨道分类器](./轨道分类器.md) — 深入了解 25 维特征向量与在线学习机制
- [设计系统](./design-system/README.md) — Meridian 视觉语言与 UI 组件
- [Helio 镜像](../helio-mirror/README.md) — 天体物理数据 MCP 集成
---
---
## Doramagic 踩坑日志
项目：luuow/meridian-mcp
摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。
## 1. 身份坑 · 仓库名和安装名不一致
- 严重度：medium
- 证据强度：runtime_trace
- 发现：仓库名 `meridian-mcp` 与安装入口 `meridian-skills-mcp` 不完全一致。
- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。
- 复现命令：`npx meridian-skills-mcp`
- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。
- 证据：identity.distribution | mcp_registry:io.github.LuuOW/meridian-skills:1.0.0 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.LuuOW%2Fmeridian-skills/versions/1.0.0 | repo=meridian-mcp; install=meridian-skills-mcp
## 2. 配置坑 · 来源证据：Automate metadata consistency (version, feature-vector dims, URLs)
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Automate metadata consistency (version, feature-vector dims, URLs)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_00bb9cc4973344808616920b3eb5c648 | https://github.com/LuuOW/meridian-mcp/issues/907 | 来源类型 github_issue 暴露的待验证使用条件。
## 3. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | mcp_registry:io.github.LuuOW/meridian-skills:1.0.0 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.LuuOW%2Fmeridian-skills/versions/1.0.0 | README/documentation is current enough for a first validation pass.
## 4. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | mcp_registry:io.github.LuuOW/meridian-skills:1.0.0 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.LuuOW%2Fmeridian-skills/versions/1.0.0 | last_activity_observed missing
## 5. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | mcp_registry:io.github.LuuOW/meridian-skills:1.0.0 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.LuuOW%2Fmeridian-skills/versions/1.0.0 | no_demo; severity=medium
## 6. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | mcp_registry:io.github.LuuOW/meridian-skills:1.0.0 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.LuuOW%2Fmeridian-skills/versions/1.0.0 | no_demo; severity=medium
## 7. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | mcp_registry:io.github.LuuOW/meridian-skills:1.0.0 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.LuuOW%2Fmeridian-skills/versions/1.0.0 | issue_or_pr_quality=unknown
## 8. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | mcp_registry:io.github.LuuOW/meridian-skills:1.0.0 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.LuuOW%2Fmeridian-skills/versions/1.0.0 | release_recency=unknown