矩阵中心
欢迎来到Matrix Hub,您的一体化AI代理市场和安装程序!
矩阵中心 是您的AI代理、自定义工具和MCP服务器的生产就绪目录和安装程序。
它从远程目录(例如GitHub)中获取结构良好的清单,提供闪电般的速度 搜索 (词汇+语义混合),安全计算和执行 安装计划 (pip/uv、Docker、Git、ZIP),并且可以自动 注册 使用您的MCP网关。
- API:端口上的FastAPI 8000 (制作:443反向代理背后)
- 前端: matrixub.io --Next.js web用户界面(ruslanmv/matrixhub)
- 数据库:PostgreSQL(SQLite支持轻量级/开发使用)
- 摄取:拉动
index.json从一个或多个遥控器,验证和丰富清单,可选块+嵌入 - 安装:临时步骤、项目适配器、锁文件生成
- 认证:管理员端点的可选承载令牌
- 日志:带相关ID的结构化JSON
- 码头工人:
docker pull ruslanmv/matrix-hub:latest
什么是Matrix Hub?
想象一下PyPI用于智能代理和自定义工具——Matrix Hub从GitHub(或任何远程目录)接收精心策划的清单,让您使用混合文本在几秒钟内找到完美的代理 + 语义搜索,然后使用单个命令将所有内容安全地安装到您的项目中(pip、Docker、Git或ZIP)。它甚至可以自动向您的MCP注册新服务 Gateway编写脚手架适配器,并生成锁文件,使您的构建坚如磐石。```mermaid
flowchart TD
A[Agent Authors
manifests] --> B[GitHub Catalog]
B --> C[Matrix Hub
catalog & install]
C --> D[CLI & SDK
agent‑creator]
C --> E[Agent Generator
planning_agent]
D & E --> F[Install Agents/Tools]
F --> G[MCP Gateway
runtime registry]
G --> H[Your App
invokes agents]
准备好发现、安装和管理企业级人工智能技能了吗?
探索 全部文件 开始吧!
______________________________________________________________________
## 官方搜索API
Matrix Hub公开了一个稳定的公共端点,该端点返回 **前5名** 跨代理、工具和MCP服务器的查询的最佳匹配。本合同为附加合同,生产安全。
### 端点```
GET /catalog/search
通用参数
q(字符串,必填) –用户意图,例如。summarize pdfstype(枚举:代理 · 工具 · mcpserver · 任意,默认任意) –按类型过滤;any搜索全部。limit(int,默认值5) –返回的最大项目数。公共API上限为 5.with_snippets(bool,默认为false) –如果可用,请包含一个简短的片段(摘要/描述的前200个字符)。
高级参数(可选): mode (keyword · semantic · hybrid), with_rag (布尔), rerank (none · llm),以及CSV过滤器 capabilities, frameworks, providers.
响应
每个项目都包括排名分数和导入/安装的便利链接:```json
{
"items": [
{
"id": "tool:hello@0.1.0",
"type": "tool",
"name": "hello",
"version": "0.1.0",
"summary": "Return greeting",
"capabilities": ["hello"],
"frameworks": ["example"],
"providers": ["self"],
"score_lexical": 0.81,
"score_semantic": 0.74,
"score_quality": 0.90,
"score_recency": 0.88,
"score_final": 0.82,
"fit_reason": null,
"manifest_url": "https://…/hello.manifest.json",
"install_url": "https://api.example.com/catalog/install?id=tool:hello@0.1.0",
"snippet": "Short summary snippet if with_snippets=true"
}
],
"total": 1
}
### 快速启动(卷曲)```bash
curl -s 'https://api.example.com/catalog/search?q=extract%20pdf%20tables&type=any&limit=5&with_snippets=true' | jq
要安装所选项目,请执行以下操作:```bash
curl -s -X POST 'https://api.example.com/catalog/install' \
-H 'Content-Type: application/json' \
-d '{
"id": "tool:pdf_table_extractor@1.1.0",
"target": "./"
}'
> 见API文件全文: 排名前五的搜索API.
**部署说明**
- 集 `PUBLIC_BASE_URL` 在您的环境中(例如。, `https://api.example.com`).
- 可选助手路线 `GET /catalog/manifest/{id}` 可以在以下情况下重定向到外部清单 `source_url` 已设置。
- 无需进行数据库迁移。
______________________________________________________________________
## 快速启动(docker编写)
要求:Docker 24+,Docker编写插件。```bash
# 1) Clone and enter the repo
git clone https://github.com/agent-matrix/matrix-hub.git
cd matrix-hub
# 2) Create .env from template and adjust if needed
cp .env.example .env
# (Optionally) set MATRIX_REMOTES to your catalog index.json URLs in .env
# 3) Build & run
docker compose up -d --build
# 4) Health check
curl -s http://localhost:443/health | jq
您应该看到:```json
{ "status": "ok" }
应用程序容器等待Postgres恢复健康,然后启动API。已安排摄入(请参阅.env中的INGESTINTERVAL_MIN)。
## 环境
所有配置都是通过环境变量进行的;看见 `.env.example` 用于记录模板。
按键设置(常用):
|变量|目的|示例|
| :----------------------- | :------------------------------------------- | :----------------------------------------------------------------------- |
| `DATABASE_URL` |SQLAlchemy URL| `postgresql+psycopg://matrix:matrix@db:5432/matrixhub` |
| `HOST` / `PORT` |绑定地址/端口| `0.0.0.0` / `443` |
| `MATRIX_REMOTES` |CSV/JSON列表 `index.json` 要摄取的URL| `https://raw.githubusercontent.com/agent-matrix/catalog/main/index.json` |
| `INGEST_INTERVAL_MIN` |背景摄取间隔(分钟)| `15` |
| `API_TOKEN` |管理员/受保护端点的承载令牌| `set_me` |
| `MCP_GATEWAY_URL` |MCP网关基本URL| `http://mcpgateway:7200` |
| `MCP_GATEWAY_TOKEN` |网关管理员API的承载器| `supersecret` |
| `SEARCH_LEXICAL_BACKEND` | `pgtrgm` 或 `none` | `pgtrgm` |
| `SEARCH_VECTOR_BACKEND` | `pgvector` / `none` | `none` |
| `SEARCH_HYBRID_WEIGHTS` | `sem:0.6,lex:0.4,rec:0.1,q:0.1` | |
| `RAG_ENABLED` | `false` | |
| `EMBED_MODEL` |嵌入器标识符(信息性)| `sentence-transformers/all-MiniLM-L6-v2` |
**安全:** 如果你设置 `API_TOKEN`,通过 `Authorization: Bearer ` 在受保护的端点上(例如手动摄取)。没有它,管理员端点将根据路由配置禁用或打开。
## API演练
基本URL默认为 `http://localhost:443`.
### GET/健康
活力/准备就绪。可选DB探测器:```bash
curl -s 'http://localhost:443/health?check_db=true' | jq
退货:```json
{ "status": "ok", "db": "ok" }
### GET/目录/搜索
使用可选过滤器对目录进行混合搜索。
**查询参数**
- `q` (必填)--自由文本查询
- `type` — `agent` · `tool` · `mcp_server`
- `capabilities` --CSV,例如。 `pdf,summarize`
- `frameworks` --CSV,例如。 `langgraph,watsonx_orchestrate`
- `providers` --CSV,例如。 `openai,watsonx`
- `mode` — `keyword` · `semantic` · `hybrid` (默认设置)
- `limit` --默认值 `20`
- `with_rag` — `true` 用简短的“fit_reason”丰富结果
- `rerank` — `none` | `llm` (默认设置)
**示例**```bash
curl -s 'http://localhost:443/catalog/search?q=summarize%20pdfs&type=agent&capabilities=pdf,summarize&limit=5&with_rag=true' | jq
响应(截断)```json
{
"items": [
{
"id": "agent:pdf-summarizer@1.4.2",
"type": "agent",
"name": "PDF Summarizer",
"version": "1.4.2",
"summary": "Summarizes long PDF documents into concise points.",
"capabilities": ["pdf", "summarize"],
"frameworks": ["langgraph"],
"providers": ["watsonx"],
"score_lexical": 0.82,
"score_semantic": 0.76,
"score_quality": 0.9,
"score_recency": 0.88,
"score_final": 0.83,
"fit_reason": "Matches 'summarize pdfs'; strong README snippet about legal contracts."
}
],
"total": 1
}
### GET/目录/实体/{id}
获取特定目录ID的完整实体详细信息。
**示例**```bash
curl -s 'http://localhost:443/catalog/entities/agent:pdf-summarizer@1.4.2' | jq
POST/编目/安装
计算并执行安装计划(pip/uv、docker、git、zip),将适配器写入项目,并(可选)向MCP-Gateway注册工具/服务器。发射 matrix.lock.json.
身体```json
{
"id": "agent:pdf-summarizer@1.4.2",
"target": "./apps/pdf-bot"
}
**示例**```bash
curl -s -X POST 'http://localhost:443/catalog/install' \
-H 'Content-Type: application/json' \
-d '{"id":"agent:pdf-summarizer@1.4.2","target":"./apps/pdf-bot"}' | jq
响应(截断)```json
{
"plan": {
"artifacts": [
{"kind": "pypi", "command": "uv pip install --system --no-cache-dir pdf-summarizer-agent==1.4.2"}
],
"adapters": [{"framework":"langgraph","template_key":"langgraph-node"}],
"mcp_registration": {
"tool": { "name": "pdf_summarize", "integration_type": "REST", "request_type": "POST", "url": "http://..." }
}
},
"results": [
{"step":"pypi","ok":true,"returncode":0,"elapsed_secs":5.91},
{"step":"adapters.write","ok":true,"extra":{"count":1}},
{"step":"gateway.register","ok":true,"extra":{"tool":{"id":"...","name":"pdf_summarize"}}},
{"step":"lockfile.write","ok":true,"extra":{"path":"apps/pdf-bot/matrix.lock.json"}}
],
"files_written": ["apps/pdf-bot/src/flows/pdf_summarizer_node.py","apps/pdf-bot/matrix.lock.json"],
"lockfile": { "version":1, "entities":[{ "id":"agent:pdf-summarizer@1.4.2", "...": "..." }] }
}
## 清单和示意图
目录作者在单独的内容仓库中发布清单(例如。, `agent-matrix/catalog`)并生成 `index.json`.
Matrix Hub按计划或通过管理员触发器接收这些清单。
支持的模式(2020‑12年JSON模式草案):
- 代理人: `schemas/agent.manifest.schema.json`
- 工具: `schemas/tool.manifest.schema.json`
- MCP服务器: `schemas/mcp-server.manifest.schema.json`
最小化 `index.json` 接受的格式:```json
{ "manifests": ["https://.../agents/pdf/1.4.2/agent.manifest.yaml"] }
或```json
{ "items": [ {"manifest_url": "https://.../tool.manifest.yaml"} ] }
或```json
{ "entries": [ {"base_url": "https://raw.githubusercontent.com/ORG/REPO/main/", "path": "agents/pdf/1.4.2/agent.manifest.yaml"} ] }
代理清单示例(摘录):```yaml
schema_version: 1
type: agent
id: pdf-summarizer
name: PDF Summarizer
version: 1.4.2
description: Summarizes long PDF documents into concise points.
capabilities: [pdf, summarize]
compatibility:
frameworks: [langgraph]
providers: [watsonx]
artifacts:
- kind: pypi
spec: { package: pdf-summarizer-agent, version: "==1.4.2" }
adapters:
- framework: langgraph
template_key: langgraph-node
mcp_registration:
tool:
name: pdf_summarize
integration_type: REST
request_type: POST
url: https://example.com/invoke
input_schema: { type: object, properties: { input: { type: string } }, required: [input] }
## 本地开发```bash
# 1) Create a virtualenv (optional)
python3 -m venv .venv && source .venv/bin/activate
# 2) Install in editable mode
pip install -U pip
pip install -e .
# 3) Run with auto-reload
make dev
# or
uvicorn src.app:app --reload --port 443
质量和测试```bash
make fmt # ruff fix + format
make lint # ruff check
make test # pytest -q
**东西住的地方**```
src/
app.py # FastAPI app, routers, scheduler
routes/ # /health, /catalog/*
services/ # ingest, search, install, adapters, gateway client...
models.py # SQLAlchemy models
schemas.py # Pydantic DTOs
utils/ # logging, security, etag
schemas/ # JSON Schemas for manifests
tests/ # starter tests and smoke checks
迁移
该项目包括Alembic脚手架。要创建和应用迁移,请执行以下操作:```bash
Generate a new revision (edit message)
make migrate m="add quality indexes"
Apply to head
make upgrade
在生产环境中,在启动新的应用程序实例之前,将迁移作为部署步骤的一部分运行(例如,init容器或CI作业)。
## 生产说明
**容器图像:** 看 `Dockerfile` (多阶段)。运行方式:```bash
docker build -t ghcr.io/agent-matrix/matrix-hub:latest .
docker run -p 443:443 --env-file .env ghcr.io/agent-matrix/matrix-hub:latest
数据库: 在生产环境中使用PostgreSQL。SQLite仅支持快速本地试用。
缩放比例: API是无状态的;在反向代理/负载均衡器后面水平扩展。确保迁移只有一个编写器。
可观察性: 日志采用JSON格式,带有相关ID(请参阅 src/utils/logging.py).将stdout/stderr转发到您的日志堆栈(例如Loki/ELK)。根据需要添加指标/跟踪。
安全:
- 集
API_TOKEN以保护管理路由。 - 将服务置于TLS之后(例如NGINX/Envoy),并在需要时强制客户端身份验证。
- 为配置出站访问策略
pip,docker,以及git如果你的环境限制了出口。
MCP网关: 暴露MCP_GATEWAY_URL和MCP_GATEWAY_TOKEN。安装程序将在安装工件后注册工具/服务器。
故障排除
API返回500 /catalog/search
- 检查数据库连接(
/health?check_db=true). - 确保实体表已填充(摄取日志)。
- 如果运行SQLite,默认情况下禁用语义/向量搜索。
摄入后无结果
- 验证
MATRIX_REMOTES指向有效index.json. - 检查容器日志中的验证错误(架构不匹配)。
安装失败 pip/docker/git
- 请参阅
resultsstdout/stderr命令的安装响应中的数组。 - 检查容器是否具有网络访问权限,以及工件引用是否有效。
网关注册错误
- 确认
MCP_GATEWAY_URL可访问且令牌正确。 - 一些网关会自动执行发现;我们的客户负责运输标准化。
许可证
Apache 2.0。看 许可证.
Docker Hub
Docker Hub上提供了官方Docker镜像:```bash
Pull the latest image
docker pull ruslanmv/matrix-hub:latest
Run with default settings (SQLite, port 8000)
docker run -d -p 8000:8000 --name matrix-hub ruslanmv/matrix-hub:latest
Run with PostgreSQL and custom config
docker run -d -p 8000:8000 \
-e DATABASE_URL=postgresql+psycopg://matrix:matrix@db:5432/matrixhub \
-e API_TOKEN=your-secret-token \
-e CATALOG_REMOTES='["https://raw.githubusercontent.com/agent-matrix/catalog/main/index.json"]' \
--name matrix-hub \
ruslanmv/matrix-hub:latest
Build locally
make container-build
make container-run
## 前端集成
官方网站前端是 MatrixHub,部署在 matrixub.io.
前端通过服务器端代理路由与后端通信:
|前端路由|后端路由|目的|
|:---------------|:-------------|:--------|
| `GET /api/search` | `GET /catalog/search` |混合搜索|
| `GET /api/latest` | `GET /catalog` |按类型列出|
| `GET /api/entities/[id]` | `GET /catalog/entities/{id}` |实体详细信息|
| `GET /api/manifest/[id]` | `GET /catalog/manifest/{id}` |JSON清单|
| `POST /api/install` | `POST /catalog/install` |安装实体|
要将前端连接到后端,请设置 `MATRIX_HUB_BASE` 在前端 `.env.local`:```bash
MATRIX_HUB_BASE=https://api.matrixhub.io
DNS配置(生产)
记录 · 名称 · 值 · 目的
A. api.matrixhub.io · 129.213.165.60 · 后端API
A. matrixhub.io · 216.198.79.1 · 前端(Vercel)
CNAME · www.matrixhub.io · *.vercel-dns-017.com · 前端www重定向
另见
- 矩阵中心 --Web前端(Next.js)
- 代理生成器 --AI代理脚手架工具
- 目录 --精心策划的清单存储库
架构:
- 代理商--
schemas/agent.manifest.schema.json - 工具--
schemas/tool.manifest.schema.json - MCP服务器--
schemas/mcp-server.manifest.schema.json
测验:
tests/ --烟雾测试和示例;与...一起跑 make test.
