<p align="center"> <img src="./assets/logo.png" alt="Matrix Hub Logo" width="300"> </p>

Matrix Hub

<a href="https://github.com/ruslanmv/agent-generator"><img src="https://img.shields.io/badge/Powered%20by-agent--generator-brightgreen" alt="由 agent-generator 提供支持"></a>

欢迎来到 Matrix Hub，您的全方位人工智能代理市场和安装程序！

Matrix Hub 是一个生产就绪的目录及安装器，适用于AI代理、自定义工具和MCP服务器。它从远程目录（例如GitHub）获取结构良好的清单，提供快速搜索（词法+语义混合），安全计算并执行安装计划（pip/uv, Docker, Git, ZIP），并且可以自动注册到您的MCP网关。

• API: FastAPI 在端口 443
• 数据库: PostgreSQL (支持轻量级/开发用途的SQLite)
• 导入: 从一个或多个远程拉取 index.json，验证并丰富清单，可选分块+嵌入
• 安装: 幂等步骤，项目适配器，生成锁文件
• 认证: 可选的管理员端点承载令牌
• 日志: 带相关ID的结构化JSON

Matrix Hub 是什么？

想象一下PyPI用于智能代理和自定义工具——Matrix Hub 从GitHub（或任何远程目录）获取精心策划的清单，让您使用混合文本+语义搜索在几秒钟内找到完美的代理，然后通过单个命令安全地将一切安装到您的项目中（pip, Docker, Git 或 ZIP）。它甚至会自动将新服务注册到您的MCP网关，编写适配器框架，并生成锁文件以确保构建稳定。

flowchart TD
    A[代理作者<br>清单] --> B[GitHub 目录]
    B --> C[Matrix Hub<br>目录 & 安装]
    C --> D[CLI & SDK<br>代理创建者]
    C --> E[代理生成器<br>规划代理]
    D & E --> F[安装代理/工具]
    F --> G[MCP 网关<br>运行时注册表]
    G --> H[您的应用<br>调用代理]

准备好发现、安装和管理企业级AI技能了吗？ 浏览 完整文档 开始吧！

---

官方搜索API

Matrix Hub 提供了一个稳定的公共端点，返回查询跨代理、工具和MCP服务器的最佳匹配项Top-5。此合同是附加的且适合生产环境。

端点

GET /catalog/search

常见参数

• q (字符串，必需) – 用户意图，例如 总结pdf
• type (枚举：agent|tool|mcp_server|any，默认为any) – 按类型过滤；any 搜索所有。
• limit (整数，默认为5) – 返回的最大项目数。公共API限制为5。
• with_snippets (布尔值，默认为false) – 当可用时包含简短摘要（约前200字符的摘要/描述）。

高级参数（可选）：mode (keyword|semantic|hybrid)，with_rag (布尔值)，rerank (none|llm)，以及CSV过滤器 capabilities，frameworks，providers。

响应

每个项目包括排名分数和方便的导入/安装链接：

{
  "items": [
    {
      "id": "tool:hello@0.1.0",
      "type": "tool",
      "name": "hello",
      "version": "0.1.0",
      "summary": "返回问候",
      "capabilities": ["hello"],
      "frameworks": ["示例"],
      "providers": ["自我"],
      "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": "如果 with_snippets=true，则为简短摘要片段"
    }
  ],
  "total": 1
}

快速开始 (curl)

curl -s 'https://api.example.com/catalog/search?q=提取%20pdf%20表格&type=any&limit=5&with_snippets=true' | jq

要安装选定的项目：

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文档：Top-5 搜索API。

部署说明

• 在您的环境中设置 PUBLIC_BASE_URL（例如，https://api.example.com）。
• 可选的帮助路由 GET /catalog/manifest/{id} 可以重定向到外部清单，当 source_url 设置时。
• 不需要数据库迁移。

---

快速开始 (docker compose)

要求：Docker 24+，docker compose 插件。

# 1) 克隆并进入仓库
git clone https://github.com/agent-matrix/matrix-hub.git
cd matrix-hub

# 2) 从模板创建 .env 文件并根据需要调整
cp .env.example .env
# （可选）在 .env 中设置 MATRIX_REMOTES 为您的目录索引.json URL

# 3) 构建并运行
docker compose up -d --build

# 4) 健康检查
curl -s http://localhost:443/health | jq

您应该看到：

{ "status": "ok" }

应用程序容器等待Postgres健康后启动API。导入已安排（参见 .env 中的 INGEST_INTERVAL_MIN）。

环境

所有配置均通过环境变量进行；查看 .env.example 获取注释模板。

关键设置（通用）：

变量	目的	示例
DATABASE_URL	SQLAlchemy URL	postgresql+psycopg://matrix:matrix@db:5432/matrixhub
HOST / PORT	绑定地址/端口	0.0.0.0 / 443
MATRIX_REMOTES	要导入的 index.json URL 的CSV/JSON列表	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 <token>（例如手动导入）。如果没有设置，管理员端点将被禁用或开放，具体取决于路由配置。

API 演示

基本URL默认为 http://localhost:443。

GET /health

存活/就绪状态。可选的数据库探测：

curl -s 'http://localhost:443/health?check_db=true' | jq

返回：

{ "status": "ok", "db": "ok" }

GET /catalog/search

跨目录的混合搜索，带可选过滤器。

查询参数

• 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 (默认来自设置)

示例

curl -s 'http://localhost:443/catalog/search?q=summarize%20pdfs&type=agent&capabilities=pdf,summarize&limit=5&with_rag=true' | jq

响应（截断）

{
  "items": [
    {
      "id": "agent:pdf-summarizer@1.4.2",
      "type": "agent",
      "name": "PDF 摘要器",
      "version": "1.4.2",
      "summary": "将长PDF文档总结成简洁要点。",
      "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": "匹配 '总结pdfs'；README摘要强烈提及法律合同。"
    }
  ],
  "total": 1
}

GET /catalog/entities/{id}

获取特定目录ID的完整实体详情。

示例

curl -s 'http://localhost:443/catalog/entities/agent:pdf-summarizer@1.4.2' | jq

POST /catalog/install

计算并执行安装计划（pip/uv, docker, git, zip），将适配器写入您的项目，并（可选）将工具/服务器注册到MCP网关。发出 matrix.lock.json。

正文

{
  "id": "agent:pdf-summarizer@1.4.2",
  "target": "./apps/pdf-bot"
}

示例

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

响应（截断）

{
  "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 按计划或通过管理员触发导入这些清单。 支持的模式（JSON Schema Draft 2020-12）：

• 代理：schemas/agent.manifest.schema.json
• 工具：schemas/tool.manifest.schema.json
• MCP服务器：schemas/mcp-server.manifest.schema.json

最小接受的 index.json 格式：

{ "manifests": ["https://.../agents/pdf/1.4.2/agent.manifest.yaml"] }

或者

{ "items": [ {"manifest_url": "https://.../tool.manifest.yaml"} ] }

或者

{ "entries": [ {"base_url": "https://raw.githubusercontent.com/ORG/REPO/main/", "path": "agents/pdf/1.4.2/agent.manifest.yaml"} ] }

示例代理清单（摘录）：

schema_version: 1
type: agent
id: pdf-summarizer
name: PDF 摘要器
version: 1.4.2
description: 将长PDF文档总结成简洁要点。
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] }

本地开发

# 1) 创建虚拟环境（可选）
python3 -m venv .venv && source .venv/bin/activate

# 2) 安装在编辑模式下
pip install -U pip
pip install -e .

# 3) 使用自动重新加载运行
make dev
# 或
uvicorn src.app:app --reload --port 443

质量与测试

make fmt        # ruff fix + 格式化
make lint       # ruff 检查
make test       # pytest -q

位置

src/
  app.py                # FastAPI 应用，路由器，调度器
  routes/               # /health, /catalog/*
  services/             # 导入，搜索，安装，适配器，网关客户端...
  models.py             # SQLAlchemy 模型
  schemas.py            # Pydantic DTOs
  utils/                # 日志记录，安全，etag
schemas/                # 清单的 JSON 模式
tests/                  # 初始测试和烟雾检查

迁移

该项目包括Alembic脚手架。要创建和应用迁移：

# 生成新的修订版（编辑消息）
make migrate m="添加质量索引"

# 应用到最新版本
make upgrade

在生产中，作为部署步骤的一部分运行迁移（例如，初始化容器或CI作业），在启动新应用实例之前。

生产注意事项

容器镜像: 查看 Dockerfile（多阶段）。运行：

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 和